summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2014-04-23 22:10:41 +0000
committerKarl Berry <karl@freefriends.org>2014-04-23 22:10:41 +0000
commite5c6e6d9c56fbfc54508fa2c32b03a5a870b7553 (patch)
tree40fcc93aa383c1e45d31ddc42d03f15cbada7076 /Master/tlpkg/tlperl
parent300c1eb6d37d46078d448d6d58938d5a80cd68ff (diff)
oops, remove 5.16 tlperl files
git-svn-id: svn://tug.org/texlive/trunk@33649 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl')
-rwxr-xr-xMaster/tlpkg/tlperl/bin/libgcc_s_dw2-1.dllbin118784 -> 0 bytes
-rwxr-xr-xMaster/tlpkg/tlperl/bin/perl5.16.2.exebin12288 -> 0 bytes
-rwxr-xr-xMaster/tlpkg/tlperl/bin/perl516.dllbin1821184 -> 0 bytes
-rw-r--r--Master/tlpkg/tlperl/lib/CORE.pod86
-rw-r--r--Master/tlpkg/tlperl/lib/CORE/libperl516.abin910066 -> 0 bytes
-rw-r--r--Master/tlpkg/tlperl/lib/CPAN/API/HOWTO.pod44
-rw-r--r--Master/tlpkg/tlperl/lib/CPANPLUS/FAQ.pod34
-rw-r--r--Master/tlpkg/tlperl/lib/CPANPLUS/Hacking.pod135
-rw-r--r--Master/tlpkg/tlperl/lib/CPANPLUS/Shell/Default/Plugins/HOWTO.pod136
-rw-r--r--Master/tlpkg/tlperl/lib/Config.pod9027
-rw-r--r--Master/tlpkg/tlperl/lib/Encode/PerlIO.pod167
-rw-r--r--Master/tlpkg/tlperl/lib/Encode/Supported.pod901
-rw-r--r--Master/tlpkg/tlperl/lib/ExtUtils/MakeMaker/FAQ.pod435
-rw-r--r--Master/tlpkg/tlperl/lib/ExtUtils/MakeMaker/Tutorial.pod180
-rw-r--r--Master/tlpkg/tlperl/lib/ExtUtils/ParseXS.pod161
-rw-r--r--Master/tlpkg/tlperl/lib/IO/Compress/FAQ.pod597
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Codes.pod285
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Codes/API.pod320
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Codes/Changes.pod570
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Codes/Constants.pod41
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Codes/Country.pod214
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Codes/Currency.pod127
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Codes/LangExt.pod116
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Codes/LangFam.pod116
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Codes/LangVar.pod118
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Codes/Language.pod137
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Codes/Script.pod131
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Country.pod214
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Currency.pod127
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Language.pod137
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Maketext.pod1354
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Maketext/Cookbook.pod150
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Maketext/TPJ13.pod775
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Script.pod131
-rw-r--r--Master/tlpkg/tlperl/lib/Module/Build/API.pod2058
-rw-r--r--Master/tlpkg/tlperl/lib/Module/Build/Authoring.pod322
-rw-r--r--Master/tlpkg/tlperl/lib/Module/Build/Bundling.pod147
-rw-r--r--Master/tlpkg/tlperl/lib/Module/CoreList.pod214
-rw-r--r--Master/tlpkg/tlperl/lib/Net/libnetFAQ.pod303
-rw-r--r--Master/tlpkg/tlperl/lib/POSIX.pod2221
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Simple.pod395
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Simple/Subclassing.pod1057
-rw-r--r--Master/tlpkg/tlperl/lib/TAP/Harness/Beyond.pod417
-rw-r--r--Master/tlpkg/tlperl/lib/Test/Tutorial.pod604
-rw-r--r--Master/tlpkg/tlperl/lib/Tk.pod862
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/804delta.pod110
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Adjuster.pod223
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Animation.pod92
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Balloon.pod293
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Bitmap.pod103
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/BrowseEntry.pod210
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Button.pod255
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Canvas.pod2394
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Checkbutton.pod347
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Clipboard.pod89
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/CmdLine.pod454
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/ColorEditor.pod120
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Common.pod16
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Compound.pod298
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/ConfigSpecs.pod262
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/DItem.pod439
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Derived.pod89
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Dialog.pod107
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/DialogBox.pod156
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/DirTree.pod172
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/DropSite.pod33
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Entry.pod693
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Error.pod145
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Eventloop.pod62
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/FBox.pod67
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/FileSelect.pod150
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Font.pod407
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Frame.pod146
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/HList.pod1050
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/IO.pod51
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/IconList.pod82
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Image.pod145
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/InputO.pod50
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Internals.pod142
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/LabFrame.pod110
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Label.pod133
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Labelframe.pod206
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Listbox.pod794
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/MainWindow.pod85
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Menu.pod876
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Menu/Item.pod96
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Menubutton.pod249
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Message.pod151
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/MsgBox.pod83
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Mwm.pod109
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/NoteBook.pod235
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Optionmenu.pod100
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Panedwindow.pod326
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Photo.pod475
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Pixmap.pod64
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Popup.pod89
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/ROText.pod48
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Radiobutton.pod333
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Scale.pod356
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Scrollbar.pod429
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Scrolled.pod86
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Spinbox.pod819
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Submethods.pod27
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/SunConst.pod18
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/TList.pod597
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Table.pod97
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Tcl-perl.pod200
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Text.pod2220
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/TextUndo.pod73
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Tiler.pod32
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/TixGrid.pod539
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Toplevel.pod199
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Tree.pod274
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/UserGuide.pod586
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Widget.pod678
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/WidgetDemo.pod59
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Wm.pod667
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/X.pod373
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/X11Font.pod88
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Xrm.pod45
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/after.pod168
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/bind.pod583
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/bindtags.pod107
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/callbacks.pod104
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/chooseColor.pod64
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/chooseDirectory.pod95
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/composite.pod171
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/event.pod417
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/exit.pod42
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/fileevent.pod112
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/focus.pod166
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/form.pod397
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod182
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/grab.pod140
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/grid.pod409
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/mega.pod423
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/messageBox.pod67
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/option.pod217
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/options.pod787
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/overview.pod138
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/pTk.pod550
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/pack.pod324
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/palette.pod89
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/place.pod283
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/selection.pod159
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/send.pod118
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/tixWm.pod73
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/tkvars.pod107
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/widgets.pod20
-rw-r--r--Master/tlpkg/tlperl/lib/Win32/OLE/NEWS.pod380
-rw-r--r--Master/tlpkg/tlperl/lib/Win32/OLE/TPJ.pod798
-rw-r--r--Master/tlpkg/tlperl/lib/lwpcook.pod311
-rw-r--r--Master/tlpkg/tlperl/lib/lwptut.pod839
-rw-r--r--Master/tlpkg/tlperl/lib/perllocal.pod506
-rw-r--r--Master/tlpkg/tlperl/lib/pods/a2p.pod179
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl.pod480
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl5004delta.pod1612
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl5005delta.pod993
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl5100delta.pod1612
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl5101delta.pod1773
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl5120delta.pod3195
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl5121delta.pod411
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl5122delta.pod347
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl5123delta.pod118
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl5124delta.pod108
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl5140delta.pod4590
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl5141delta.pod361
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl5142delta.pod242
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl5143delta.pod291
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl5160delta.pod4314
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl5161delta.pod198
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl5162delta.pod125
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl561delta.pod3660
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl56delta.pod3022
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl581delta.pod1102
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl582delta.pod162
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl583delta.pod210
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl584delta.pod263
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl585delta.pod257
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl586delta.pod170
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl587delta.pod379
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl588delta.pod1634
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl589delta.pod2337
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perl58delta.pod3746
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlaix.pod489
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlamiga.pod278
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlapi.pod12932
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlapio.pod525
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlartistic.pod224
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlbeos.pod109
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlbook.pod292
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlboot.pod12
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlbot.pod12
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlbs2000.pod241
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlcall.pod1936
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlce.pod306
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlcheat.pod107
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlclib.pod212
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlcn.pod150
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlcommunity.pod158
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlcygwin.pod779
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perldata.pod887
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perldbmfilter.pod167
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perldebguts.pod1000
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perldebtut.pod722
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perldebug.pod1226
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perldelta.pod125
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perldgux.pod117
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perldiag.pod5763
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perldoc.pod272
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perldos.pod331
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perldsc.pod847
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perldtrace.pod179
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlebcdic.pod1446
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlembed.pod1117
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlepoc.pod154
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlexperiment.pod305
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlfaq.pod1373
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlfaq1.pod332
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlfaq2.pod246
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlfaq3.pod1160
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlfaq4.pod2679
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlfaq5.pod1574
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlfaq6.pod1124
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlfaq7.pod1061
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlfaq8.pod1422
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlfaq9.pod426
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlfilter.pod587
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlfork.pod357
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlform.pod455
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlfreebsd.pod40
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlfunc.pod9088
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlgit.pod850
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlglossary.pod3442
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlgpl.pod288
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlguts.pod2934
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlhack.pod1144
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlhacktips.pod1461
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlhacktut.pod188
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlhaiku.pod64
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlhist.pod981
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlhpux.pod674
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlhurd.pod54
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlintern.pod2276
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlinterp.pod742
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlintro.pod700
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perliol.pod1040
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlipc.pod1833
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlirix.pod137
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perljp.pod192
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlko.pod207
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perllexwarn.pod545
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perllinux.pod39
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perllocale.pod1281
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perllol.pod388
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlmacos.pod30
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlmacosx.pod256
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlmod.pod598
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlmodinstall.pod439
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlmodlib.pod3920
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlmodstyle.pod783
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlmpeix.pod711
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlmroapi.pod102
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlnetware.pod225
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlnewmod.pod280
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlnumber.pod209
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlobj.pod1049
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlootut.pod741
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlop.pod3215
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlopenbsd.pod30
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlopentut.pod998
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlos2.pod2741
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlos390.pod444
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlos400.pod120
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlpacktut.pod1265
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlperf.pod1179
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlplan9.pod146
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlpod.pod737
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlpodspec.pod1916
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlpodstyle.pod338
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlpolicy.pod479
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlport.pod2359
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlpragma.pod163
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlqnx.pod143
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlre.pod2585
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlreapi.pod706
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlrebackslash.pod661
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlrecharclass.pod850
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlref.pod751
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlreftut.pod527
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlreguts.pod886
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlrequick.pod519
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlreref.pod408
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlretut.pod2928
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlriscos.pod67
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlrun.pod1353
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlsec.pod521
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlsolaris.pod697
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlsource.pod223
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlstyle.pod303
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlsub.pod1535
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlsymbian.pod432
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlsyn.pod1213
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlthrtut.pod1178
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perltie.pod1225
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perltoc.pod37266
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perltodo.pod10
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perltooc.pod12
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perltoot.pod12
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perltrap.pod1591
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perltru64.pod172
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perltw.pod172
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlunicode.pod1826
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlunifaq.pod319
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perluniintro.pod946
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perluniprops.pod4306
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlunitut.pod208
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlutil.pod311
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perluts.pod107
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlvar.pod2174
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlvmesa.pod140
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlvms.pod1225
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlvos.pod169
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlwin32.pod895
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlxs.pod2123
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlxstut.pod1379
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlxstypemap.pod699
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/CaseFolding.txt1224
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Dt/None.pl397
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Ea/F.pl15
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Gc/Pc.pl18
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Lb/CR.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Lb/H2.pl411
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Lb/H3.pl411
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Lb/JL.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Lb/JT.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Lb/JV.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Lb/LF.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Lb/NU.pl54
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/NFKCQC/M.pl47
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Nv/NaN.pl175
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Perl/PosixSpa.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Perl/_PerlNon.pl40
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Perl/_XBegin.pl29
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Armi.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Avst.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Bali.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Bamu.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Batk.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Brah.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Brai.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Bugi.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cakm.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cans.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cari.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cham.pl16
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cher.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Copt.pl15
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Dsrt.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Egyp.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Ethi.pl44
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Glag.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Goth.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Hebr.pl21
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Ital.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Java.pl15
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Kali.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Khar.pl20
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Khmr.pl16
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Knda.pl26
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lana.pl17
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lao.pl30
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lepc.pl15
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Limb.pl17
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lisu.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lyci.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lydi.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Merc.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Mero.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Miao.pl15
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Mlym.pl23
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Mtei.pl15
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Mymr.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Nko.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Ogam.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Olck.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Orkh.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Osma.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Phli.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Phnx.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Prti.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Rjng.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Runr.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Samr.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sarb.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Saur.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Shaw.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Shrd.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sinh.pl23
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sora.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sund.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sylo.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Tale.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Talu.pl16
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Taml.pl28
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Tavt.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Telu.pl26
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Tfng.pl15
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Thai.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Tibt.pl19
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Ugar.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Vai.pl13
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Xpeo.pl14
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Xsux.pl15
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Scx/Zzzz.pl549
-rw-r--r--Master/tlpkg/tlperl/lib/unicore/lib/Space/Y.pl23
-rw-r--r--Master/tlpkg/tlperl/lib/version.pod322
-rw-r--r--Master/tlpkg/tlperl/lib/version/Internals.pod698
-rw-r--r--Master/tlpkg/tlperl/lib/version/Requirements.pm597
419 files changed, 0 insertions, 279522 deletions
diff --git a/Master/tlpkg/tlperl/bin/libgcc_s_dw2-1.dll b/Master/tlpkg/tlperl/bin/libgcc_s_dw2-1.dll
deleted file mode 100755
index 8870ba74b17..00000000000
--- a/Master/tlpkg/tlperl/bin/libgcc_s_dw2-1.dll
+++ /dev/null
Binary files differ
diff --git a/Master/tlpkg/tlperl/bin/perl5.16.2.exe b/Master/tlpkg/tlperl/bin/perl5.16.2.exe
deleted file mode 100755
index 17c80687d96..00000000000
--- a/Master/tlpkg/tlperl/bin/perl5.16.2.exe
+++ /dev/null
Binary files differ
diff --git a/Master/tlpkg/tlperl/bin/perl516.dll b/Master/tlpkg/tlperl/bin/perl516.dll
deleted file mode 100755
index f0d7573ec9b..00000000000
--- a/Master/tlpkg/tlperl/bin/perl516.dll
+++ /dev/null
Binary files differ
diff --git a/Master/tlpkg/tlperl/lib/CORE.pod b/Master/tlpkg/tlperl/lib/CORE.pod
deleted file mode 100644
index ec6a8047a4d..00000000000
--- a/Master/tlpkg/tlperl/lib/CORE.pod
+++ /dev/null
@@ -1,86 +0,0 @@
-=head1 NAME
-
-CORE - Namespace for Perl's core routines
-
-=head1 SYNOPSIS
-
- BEGIN {
- *CORE::GLOBAL::hex = sub { 1; };
- }
-
- print hex("0x50"),"\n"; # prints 1
- print CORE::hex("0x50"),"\n"; # prints 80
- CORE::say "yes"; # prints yes
-
- BEGIN { *shove = \&CORE::push; }
- shove @array, 1,2,3; # pushes on to @array
-
-=head1 DESCRIPTION
-
-The C<CORE> namespace gives access to the original built-in functions of
-Perl. The C<CORE> package is built into
-Perl, and therefore you do not need to use or
-require a hypothetical "CORE" module prior to accessing routines in this
-namespace.
-
-A list of the built-in functions in Perl can be found in L<perlfunc>.
-
-For all Perl keywords, a C<CORE::> prefix will force the built-in function
-to be used, even if it has been overridden or would normally require the
-L<feature> pragma. Despite appearances, this has nothing to do with the
-CORE package, but is part of Perl's syntax.
-
-For many Perl functions, the CORE package contains real subroutines. This
-feature is new in Perl 5.16. You can take references to these and make
-aliases. However, some can only be called as barewords; i.e., you cannot
-use ampersand syntax (C<&foo>) or call them through references. See the
-C<shove> example above. These subroutines exist for all overridable
-keywords, except for C<dump> and the infix operators. Calling with
-ampersand syntax and through references does not work for the following
-functions, as they have special syntax that cannot always be translated
-into a simple list (e.g., C<eof> vs C<eof()>):
-
-C<chdir>, C<chomp>, C<chop>, C<each>, C<eof>, C<exec>, C<keys>, C<lstat>,
-C<pop>, C<push>, C<shift>, C<splice>, C<stat>, C<system>, C<truncate>,
-C<unlink>, C<unshift>, C<values>
-
-=head1 OVERRIDING CORE FUNCTIONS
-
-To override a Perl built-in routine with your own version, you need to
-import it at compile-time. This can be conveniently achieved with the
-C<subs> pragma. This will affect only the package in which you've imported
-the said subroutine:
-
- use subs 'chdir';
- sub chdir { ... }
- chdir $somewhere;
-
-To override a built-in globally (that is, in all namespaces), you need to
-import your function into the C<CORE::GLOBAL> pseudo-namespace at compile
-time:
-
- BEGIN {
- *CORE::GLOBAL::hex = sub {
- # ... your code here
- };
- }
-
-The new routine will be called whenever a built-in function is called
-without a qualifying package:
-
- print hex("0x50"),"\n"; # prints 1
-
-In both cases, if you want access to the original, unaltered routine, use
-the C<CORE::> prefix:
-
- print CORE::hex("0x50"),"\n"; # prints 80
-
-=head1 AUTHOR
-
-This documentation provided by Tels <nospam-abuse@bloodgate.com> 2007.
-
-=head1 SEE ALSO
-
-L<perlsub>, L<perlfunc>.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/CORE/libperl516.a b/Master/tlpkg/tlperl/lib/CORE/libperl516.a
deleted file mode 100644
index b6a9b6b4ef5..00000000000
--- a/Master/tlpkg/tlperl/lib/CORE/libperl516.a
+++ /dev/null
Binary files differ
diff --git a/Master/tlpkg/tlperl/lib/CPAN/API/HOWTO.pod b/Master/tlpkg/tlperl/lib/CPAN/API/HOWTO.pod
deleted file mode 100644
index e65a4bc9313..00000000000
--- a/Master/tlpkg/tlperl/lib/CPAN/API/HOWTO.pod
+++ /dev/null
@@ -1,44 +0,0 @@
-=head1 NAME
-
-CPAN::API::HOWTO - a recipe book for programming with CPAN.pm
-
-=head1 RECIPES
-
-All of these recipes assume that you have put "use CPAN" at the top of
-your program.
-
-=head2 What distribution contains a particular module?
-
- my $distribution = CPAN::Shell->expand(
- "Module", "Data::UUID"
- )->distribution()->pretty_id();
-
-This returns a string of the form "AUTHORID/TARBALL". If you want the
-full path and filename to this distribution on a CPAN mirror, then it is
-C<.../authors/id/A/AU/AUTHORID/TARBALL>.
-
-=head2 What modules does a particular distribution contain?
-
- CPAN::Index->reload();
- my @modules = CPAN::Shell->expand(
- "Distribution", "JHI/Graph-0.83.tar.gz"
- )->containsmods();
-
-You may also refer to a distribution in the form A/AU/AUTHORID/TARBALL.
-
-=head1 SEE ALSO
-
-the main CPAN.pm documentation
-
-=head1 LICENSE
-
-This program is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-See L<http://www.perl.com/perl/misc/Artistic.html>
-
-=head1 AUTHOR
-
-David Cantrell
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/CPANPLUS/FAQ.pod b/Master/tlpkg/tlperl/lib/CPANPLUS/FAQ.pod
deleted file mode 100644
index 00c186ab0d7..00000000000
--- a/Master/tlpkg/tlperl/lib/CPANPLUS/FAQ.pod
+++ /dev/null
@@ -1,34 +0,0 @@
-=pod
-
-=head1 NAME
-
-CPANPLUS::FAQ - CPANPLUS Frequently Asked Questions
-
-=head1 NAME
-
-CPANPLUS::FAQ
-
-=head1 DESCRIPTION
-
-This document attempts to provide answers to commonly asked questions.
-
- XXX Work in progress
-
-=head1 BUG REPORTS
-
-Please report bugs or other issues to E<lt>bug-cpanplus@rt.cpan.org<gt>.
-
-=head1 AUTHOR
-
-This module by Jos Boumans E<lt>kane@cpan.orgE<gt>.
-
-=head1 COPYRIGHT
-
-The CPAN++ interface (of which this module is a part of) is copyright (c)
-2001 - 2007, Jos Boumans E<lt>kane@cpan.orgE<gt>. All rights reserved.
-
-This library is free software; you may redistribute and/or modify it
-under the same terms as Perl itself.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/CPANPLUS/Hacking.pod b/Master/tlpkg/tlperl/lib/CPANPLUS/Hacking.pod
deleted file mode 100644
index c226b071691..00000000000
--- a/Master/tlpkg/tlperl/lib/CPANPLUS/Hacking.pod
+++ /dev/null
@@ -1,135 +0,0 @@
-=pod
-
-=head1 NAME
-
-CPANPLUS::Hacking - developing CPANPLUS
-
-=head1 DESCRIPTION
-
-This document attempts to describe how to develop with the
-CPANPLUS environment most easily, how certain things work and why.
-
-This is basically a quick-start guide to people who want to add
-features or patches to CPANPLUS.
-
-=head1 OBTAINING CPANPLUS
-
-Checkout CPANPLUS from its GIT repository at
-L<https://github.com/jib/cpanplus-devel> .
-
-=head1 INSTALLING CPANPLUS
-
-CPANPLUS follows the standard perl module installation process:
-
- perl Makefile.PL
- make
- make test
- make install
-
-=head1 CONFIGURING CPANPLUS
-
-When running C<perl Makefile.PL> you will be prompted to configure.
-If you have already done so, and merely wish to update the C<Makefile>,
-simply run:
-
- perl Makefile.PL JFDI=1
-
-This will keep your configuration intact. Note however, if there are
-changes to the default configuration file C<Config.pm-orig>, you should
-either delete your current config file and reconfigure, or patch your
-config file from the new entries in C<Config.pm-orig>.
-
-=head1 RUNNING CPANPLUS FROM DEVELOPMENT ENVIRONMENT
-
-If you'd rather not install the development version to your
-C<site_perl> directory, that's no problem. You can set your C<PERL5LIB>
-environment variable to CPANPLUS' C<lib> directory, and you can run it
-from there.
-
-=head1 RUNNING CPANPLUS TESTS
-
-Tests are what tells us if CPANPLUS is working. If a test is not working,
-try to run it explicitly like this:
-
- perl -I/path/to/cpanplus/lib t/XX_name_of_test.t 1
-
-The extra '1' makes sure that all the messages and errors (they might
-be errors we're testing for!) are being printed rather than kept quiet.
-This is a great way to find out the context of any failures that may
-occur.
-
-If you believe this test failure proves a bug in CPANPLUS, the long
-output of the test file is something we'd like to see alongside your
-bug report.
-
-=head1 FINDING BUGS
-
-Sometimes you might find bugs in CPANPLUS' behaviour. If you encounter
-these in a development snapshot, we'd appreciate a complete patch (as
-described below in the L<SENDING PATCHES> section.
-
-If it's way over your head, then of course reporting the bug is always
-better than not reporting it at all. Before you do so though, make
-sure you have the B<latest> development snapshot, and the bug still
-persists there. If so, report the bug to this address:
-
- bug-cpanplus@rt.cpan.org
-
-A good C<patch> would have the following characteristics:
-
-=over 4
-
-=item Problem description
-
-Describe clearly what the bug is you found, and what it should have
-done instead.
-
-=item Program demonstrating the bug
-
-Show us how to reproduce the bug, in a simple of a program as possible
-
-=item [OPTIONAL] A patch to the test suite to test for the bug
-
-Amend our test suite by making sure this bug will be found in this, and
-future versions of CPANPLUS (see L<SUPPLYING PATCHES>)
-
-=item [OPTIONAL] A patch to the code + tests + documentation
-
-Fix the bug, update the docs & tests. That way your bug will be gone
-forever :)
-
-=back
-
-=head1 SUPPLYING PATCHES
-
-Patches are a good thing, and they are welcome. Especially if they fix
-bugs you've found along the way, or that others have reported.
-
-We prefer patches in the following format:
-
-=over 4
-
-=item * In C<diff -u> or C<diff -c> format
-
-=item * From the root of the snapshot
-
-=item * Including patches for code + tests + docs
-
-=item * Sent per mail to bug-cpanplus@rt.cpan.org
-
-=item * With subject containing C<[PATCH]> + description of the patch
-
-=back
-
-You will always be informed if a patch is applied or rejected, and in
-case of rejection why that is (perhaps you can tweak the patch to have
-it accepted after all).
-
-=cut
-
-__END__
-
-* perl5lib
-* perl t/foo 1
-* patches to cpanplus-devel
-* snap/devel.tgz
diff --git a/Master/tlpkg/tlperl/lib/CPANPLUS/Shell/Default/Plugins/HOWTO.pod b/Master/tlpkg/tlperl/lib/CPANPLUS/Shell/Default/Plugins/HOWTO.pod
deleted file mode 100644
index 8000aac9884..00000000000
--- a/Master/tlpkg/tlperl/lib/CPANPLUS/Shell/Default/Plugins/HOWTO.pod
+++ /dev/null
@@ -1,136 +0,0 @@
-=head1 NAME
-
-CPANPLUS::Shell::Default::Plugins::HOWTO -- documentation on how to write your own plugins
-
-=head1 SYNOPSIS
-
- package CPANPLUS::Shell::Default::Plugins::MyPlugin;
-
- ### return command => method mapping
- sub plugins { ( myplugin1 => 'mp1', myplugin2 => 'mp2' ) }
-
- ### method called when the command '/myplugin1' is issued
- sub mp1 { .... }
-
- ### method called when the command '/? myplugin1' is issued
- sub mp1_help { return "Help Text" }
-
-=head1 DESCRIPTION
-
-This pod text explains how to write your own plugins for
-C<CPANPLUS::Shell::Default>.
-
-=head1 HOWTO
-
-=head2 Registering Plugin Modules
-
-Plugins are detected by using C<Module::Pluggable>. Every module in
-the C<CPANPLUS::Shell::Default::Plugins::*> namespace is considered a
-plugin, and is attempted to be loaded.
-
-Therefor, any plugin must be declared in that namespace, in a corresponding
-C<.pm> file.
-
-=head2 Registering Plugin Commands
-
-To register any plugin commands, a list of key value pairs must be returned
-by a C<plugins> method in your package. The keys are the commands you wish
-to register, the values are the methods in the plugin package you wish to have
-called when the command is issued.
-
-For example, a simple 'Hello, World!' plugin:
-
- package CPANPLUS::Shell::Default::Plugins::HW;
-
- sub plugins { return ( helloworld => 'hw' ) };
-
- sub hw { print "Hello, world!\n" }
-
-When the user in the default shell now issues the C</helloworld> command,
-this command will be dispatched to the plugin, and its C<hw> method will
-be called
-
-=head2 Registering Plugin Help
-
-To provide usage information for your plugin, the user of the default shell
-can type C</? PLUGIN_COMMAND>. In that case, the function C<PLUGIN_COMMAND_help>
-will be called in your plugin package.
-
-For example, extending the above example, when a user calls C</? helloworld>,
-the function C<hw_help> will be called, which might look like this:
-
- sub hw_help { " /helloworld # prints "Hello, world!\n" }
-
-If you dont provide a corresponding _help function to your commands, the
-default shell will handle it gracefully, but the user will be stuck without
-usage information on your commands, so it's considered undesirable to omit
-the help functions.
-
-=head2 Arguments to Plugin Commands
-
-Any plugin function will receive the following arguments when called, which
-are all positional:
-
-=over 4
-
-=item Classname -- The name of your plugin class
-
-=item Shell -- The CPANPLUS::Shell::Default object
-
-=item Backend -- The CPANPLUS::Backend object
-
-=item Command -- The command issued by the user
-
-=item Input -- The input string from the user
-
-=item Options -- A hashref of options provided by the user
-
-=back
-
-For example, the following command:
-
- /helloworld bob --nofoo --bar=2 joe
-
-Would yield the following arguments:
-
- sub hw {
- my $class = shift; # CPANPLUS::Shell::Default::Plugins::HW
- my $shell = shift; # CPANPLUS::Shell::Default object
- my $cb = shift; # CPANPLUS::Backend object
- my $cmd = shift; # 'helloworld'
- my $input = shift; # 'bob joe'
- my $opts = shift; # { foo => 0, bar => 2 }
-
- ....
- }
-
-
-=head1 BUG REPORTS
-
-Please report bugs or other issues to E<lt>bug-cpanplus@rt.cpan.org<gt>.
-
-=head1 AUTHOR
-
-This module by Jos Boumans E<lt>kane@cpan.orgE<gt>.
-
-=head1 COPYRIGHT
-
-The CPAN++ interface (of which this module is a part of) is copyright (c)
-2001 - 2007, Jos Boumans E<lt>kane@cpan.orgE<gt>. All rights reserved.
-
-This library is free software; you may redistribute and/or modify it
-under the same terms as Perl itself.
-
-=head1 SEE ALSO
-
-L<CPANPLUS::Shell::Default>, L<CPANPLUS::Shell>, L<cpanp>
-
-=cut
-
-# Local variables:
-# c-indentation-style: bsd
-# c-basic-offset: 4
-# indent-tabs-mode: nil
-# End:
-# vim: expandtab shiftwidth=4:
-
diff --git a/Master/tlpkg/tlperl/lib/Config.pod b/Master/tlpkg/tlperl/lib/Config.pod
deleted file mode 100644
index c14aa382366..00000000000
--- a/Master/tlpkg/tlperl/lib/Config.pod
+++ /dev/null
@@ -1,9027 +0,0 @@
-=head1 NAME
-
-Config - access Perl configuration information
-
-=head1 SYNOPSIS
-
- use Config;
- if ($Config{usethreads}) {
- print "has thread support\n"
- }
-
- use Config qw(myconfig config_sh config_vars config_re);
-
- print myconfig();
-
- print config_sh();
-
- print config_re();
-
- config_vars(qw(osname archname));
-
-
-=head1 DESCRIPTION
-
-The Config module contains all the information that was available to
-the C<Configure> program at Perl build time (over 900 values).
-
-Shell variables from the F<config.sh> file (written by Configure) are
-stored in the readonly-variable C<%Config>, indexed by their names.
-
-Values stored in config.sh as 'undef' are returned as undefined
-values. The perl C<exists> function can be used to check if a
-named variable exists.
-
-For a description of the variables, please have a look at the
-Glossary file, as written in the Porting folder, or use the url:
-http://perl5.git.perl.org/perl.git/blob/HEAD:/Porting/Glossary
-
-=over 4
-
-=item myconfig()
-
-Returns a textual summary of the major perl configuration values.
-See also C<-V> in L<perlrun/Command Switches>.
-
-=item config_sh()
-
-Returns the entire perl configuration information in the form of the
-original config.sh shell variable assignment script.
-
-=item config_re($regex)
-
-Like config_sh() but returns, as a list, only the config entries who's
-names match the $regex.
-
-=item config_vars(@names)
-
-Prints to STDOUT the values of the named configuration variable. Each is
-printed on a separate line in the form:
-
- name='value';
-
-Names which are unknown are output as C<name='UNKNOWN';>.
-See also C<-V:name> in L<perlrun/Command Switches>.
-
-=item bincompat_options()
-
-Returns a list of C pre-processor options used when compiling this F<perl>
-binary, which affect its binary compatibility with extensions.
-C<bincompat_options()> and C<non_bincompat_options()> are shown together in
-the output of C<perl -V> as I<Compile-time options>.
-
-=item non_bincompat_options()
-
-Returns a list of C pre-processor options used when compiling this F<perl>
-binary, which do not affect binary compatibility with extensions.
-
-=item compile_date()
-
-Returns the compile date (as a string), equivalent to what is shown by
-C<perl -V>
-
-=item local_patches()
-
-Returns a list of the names of locally applied patches, equivalent to what
-is shown by C<perl -V>.
-
-=item header_files()
-
-Returns a list of the header files that should be used as dependencies for
-XS code, for this version of Perl on this platform.
-
-=back
-
-=head1 EXAMPLE
-
-Here's a more sophisticated example of using %Config:
-
- use Config;
- use strict;
-
- my %sig_num;
- my @sig_name;
- unless($Config{sig_name} && $Config{sig_num}) {
- die "No sigs?";
- } else {
- my @names = split ' ', $Config{sig_name};
- @sig_num{@names} = split ' ', $Config{sig_num};
- foreach (@names) {
- $sig_name[$sig_num{$_}] ||= $_;
- }
- }
-
- print "signal #17 = $sig_name[17]\n";
- if ($sig_num{ALRM}) {
- print "SIGALRM is $sig_num{ALRM}\n";
- }
-
-=head1 WARNING
-
-Because this information is not stored within the perl executable
-itself it is possible (but unlikely) that the information does not
-relate to the actual perl binary which is being used to access it.
-
-The Config module is installed into the architecture and version
-specific library directory ($Config{installarchlib}) and it checks the
-perl version number when loaded.
-
-The values stored in config.sh may be either single-quoted or
-double-quoted. Double-quoted strings are handy for those cases where you
-need to include escape sequences in the strings. To avoid runtime variable
-interpolation, any C<$> and C<@> characters are replaced by C<\$> and
-C<\@>, respectively. This isn't foolproof, of course, so don't embed C<\$>
-or C<\@> in double-quoted strings unless you're willing to deal with the
-consequences. (The slashes will end up escaped and the C<$> or C<@> will
-trigger variable interpolation)
-
-=head1 GLOSSARY
-
-Most C<Config> variables are determined by the C<Configure> script
-on platforms supported by it (which is most UNIX platforms). Some
-platforms have custom-made C<Config> variables, and may thus not have
-some of the variables described below, or may have extraneous variables
-specific to that particular port. See the port specific documentation
-in such cases.
-
-=cut
-
-=head2 _
-
-=over 4
-
-=cut
-
-=item C<_a>
-
-From F<Unix.U>:
-
-This variable defines the extension used for ordinary library files.
-For unix, it is F<.a>. The F<.> is included. Other possible
-values include F<.lib>.
-
-=item C<_exe>
-
-From F<Unix.U>:
-
-This variable defines the extension used for executable files.
-C<DJGPP>, Cygwin and F<OS/2> use F<.exe>. Stratus C<VOS> uses F<.pm>.
-On operating systems which do not require a specific extension
-for executable files, this variable is empty.
-
-=item C<_o>
-
-From F<Unix.U>:
-
-This variable defines the extension used for object files.
-For unix, it is F<.o>. The F<.> is included. Other possible
-values include F<.obj>.
-
-=back
-
-=cut
-
-=head2 a
-
-=over 4
-
-=cut
-
-=item C<afs>
-
-From F<afs.U>:
-
-This variable is set to C<true> if C<AFS> (Andrew File System) is used
-on the system, C<false> otherwise. It is possible to override this
-with a hint value or command line option, but you'd better know
-what you are doing.
-
-=item C<afsroot>
-
-From F<afs.U>:
-
-This variable is by default set to F</afs>. In the unlikely case
-this is not the correct root, it is possible to override this with
-a hint value or command line option. This will be used in subsequent
-tests for AFSness in the configure and test process.
-
-=item C<alignbytes>
-
-From F<alignbytes.U>:
-
-This variable holds the number of bytes required to align a
-double-- or a long double when applicable. Usual values are
-2, 4 and 8. The default is eight, for safety.
-
-=item C<ansi2knr>
-
-From F<ansi2knr.U>:
-
-This variable is set if the user needs to run ansi2knr.
-Currently, this is not supported, so we just abort.
-
-=item C<aphostname>
-
-From F<d_gethname.U>:
-
-This variable contains the command which can be used to compute the
-host name. The command is fully qualified by its absolute path, to make
-it safe when used by a process with super-user privileges.
-
-=item C<api_revision>
-
-From F<patchlevel.U>:
-
-The three variables, api_revision, api_version, and
-api_subversion, specify the version of the oldest perl binary
-compatible with the present perl. In a full version string
-such as F<5.6.1>, api_revision is the C<5>.
-Prior to 5.5.640, the format was a floating point number,
-like 5.00563.
-
-F<perl.c>:incpush() and F<lib/lib.pm> will automatically search in
-F<$sitelib/.>. for older directories back to the limit specified
-by these api_ variables. This is only useful if you have a
-perl library directory tree structured like the default one.
-See C<INSTALL> for how this works. The versioned site_perl
-directory was introduced in 5.005, so that is the lowest
-possible value. The version list appropriate for the current
-system is determined in F<inc_version_list.U>.
-
-C<XXX> To do: Since compatibility can depend on compile time
-options (such as bincompat, longlong, etc.) it should
-(perhaps) be set by Configure, but currently it isn't.
-Currently, we read a hard-wired value from F<patchlevel.h>.
-Perhaps what we ought to do is take the hard-wired value from
-F<patchlevel.h> but then modify it if the current Configure
-options warrant. F<patchlevel.h> then would use an #ifdef guard.
-
-=item C<api_subversion>
-
-From F<patchlevel.U>:
-
-The three variables, api_revision, api_version, and
-api_subversion, specify the version of the oldest perl binary
-compatible with the present perl. In a full version string
-such as F<5.6.1>, api_subversion is the C<1>. See api_revision for
-full details.
-
-=item C<api_version>
-
-From F<patchlevel.U>:
-
-The three variables, api_revision, api_version, and
-api_subversion, specify the version of the oldest perl binary
-compatible with the present perl. In a full version string
-such as F<5.6.1>, api_version is the C<6>. See api_revision for
-full details. As a special case, 5.5.0 is rendered in the
-old-style as 5.005. (In the 5.005_0x maintenance series,
-this was the only versioned directory in $sitelib.)
-
-=item C<api_versionstring>
-
-From F<patchlevel.U>:
-
-This variable combines api_revision, api_version, and
-api_subversion in a format such as 5.6.1 (or 5_6_1) suitable
-for use as a directory name. This is filesystem dependent.
-
-=item C<ar>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the ar program. After Configure runs,
-the value is reset to a plain C<ar> and is not useful.
-
-=item C<archlib>
-
-From F<archlib.U>:
-
-This variable holds the name of the directory in which the user wants
-to put architecture-dependent public library files for $package.
-It is most often a local directory such as F</usr/local/lib>.
-Programs using this variable must be prepared to deal
-with filename expansion.
-
-=item C<archlibexp>
-
-From F<archlib.U>:
-
-This variable is the same as the archlib variable, but is
-filename expanded at configuration time, for convenient use.
-
-=item C<archname>
-
-From F<archname.U>:
-
-This variable is a short name to characterize the current
-architecture. It is used mainly to construct the default archlib.
-
-=item C<archname64>
-
-From F<use64bits.U>:
-
-This variable is used for the 64-bitness part of $archname.
-
-=item C<archobjs>
-
-From F<Unix.U>:
-
-This variable defines any additional objects that must be linked
-in with the program on this architecture. On unix, it is usually
-empty. It is typically used to include emulations of unix calls
-or other facilities. For perl on F<OS/2>, for example, this would
-include F<os2/os2.obj>.
-
-=item C<asctime_r_proto>
-
-From F<d_asctime_r.U>:
-
-This variable encodes the prototype of asctime_r.
-It is zero if d_asctime_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_asctime_r
-is defined.
-
-=item C<awk>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the awk program. After Configure runs,
-the value is reset to a plain C<awk> and is not useful.
-
-=back
-
-=cut
-
-=head2 b
-
-=over 4
-
-=cut
-
-=item C<baserev>
-
-From F<baserev.U>:
-
-The base revision level of this package, from the F<.package> file.
-
-=item C<bash>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<bin>
-
-From F<bin.U>:
-
-This variable holds the name of the directory in which the user wants
-to put publicly executable images for the package in question. It
-is most often a local directory such as F</usr/local/bin>. Programs using
-this variable must be prepared to deal with F<~name> substitution.
-
-=item C<bin_ELF>
-
-From F<dlsrc.U>:
-
-This variable saves the result from configure if generated binaries
-are in C<ELF> format. Only set to defined when the test has actually
-been performed, and the result was positive.
-
-=item C<binexp>
-
-From F<bin.U>:
-
-This is the same as the bin variable, but is filename expanded at
-configuration time, for use in your makefiles.
-
-=item C<bison>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the bison program. After Configure runs,
-the value is reset to a plain C<bison> and is not useful.
-
-=item C<byacc>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the byacc program. After Configure runs,
-the value is reset to a plain C<byacc> and is not useful.
-
-=item C<byteorder>
-
-From F<byteorder.U>:
-
-This variable holds the byte order in a C<UV>. In the following,
-larger digits indicate more significance. The variable byteorder
-is either 4321 on a big-endian machine, or 1234 on a little-endian,
-or 87654321 on a Cray ... or 3412 with weird order !
-
-=back
-
-=cut
-
-=head2 c
-
-=over 4
-
-=cut
-
-=item C<c>
-
-From F<n.U>:
-
-This variable contains the \c string if that is what causes the echo
-command to suppress newline. Otherwise it is null. Correct usage is
-$echo $n "prompt for a question: $c".
-
-=item C<castflags>
-
-From F<d_castneg.U>:
-
-This variable contains a flag that precise difficulties the
-compiler has casting odd floating values to unsigned long:
-0 = ok
-1 = couldn't cast < 0
-2 = couldn't cast >= 0x80000000
-4 = couldn't cast in argument expression list
-
-=item C<cat>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the cat program. After Configure runs,
-the value is reset to a plain C<cat> and is not useful.
-
-=item C<cc>
-
-From F<cc.U>:
-
-This variable holds the name of a command to execute a C compiler which
-can resolve multiple global references that happen to have the same
-name. Usual values are C<cc> and C<gcc>.
-Fervent C<ANSI> compilers may be called C<c89>. C<AIX> has xlc.
-
-=item C<cccdlflags>
-
-From F<dlsrc.U>:
-
-This variable contains any special flags that might need to be
-passed with C<cc -c> to compile modules to be used to create a shared
-library that will be used for dynamic loading. For hpux, this
-should be +z. It is up to the makefile to use it.
-
-=item C<ccdlflags>
-
-From F<dlsrc.U>:
-
-This variable contains any special flags that might need to be
-passed to cc to link with a shared library for dynamic loading.
-It is up to the makefile to use it. For sunos 4.1, it should
-be empty.
-
-=item C<ccflags>
-
-From F<ccflags.U>:
-
-This variable contains any additional C compiler flags desired by
-the user. It is up to the Makefile to use this.
-
-=item C<ccflags_uselargefiles>
-
-From F<uselfs.U>:
-
-This variable contains the compiler flags needed by large file builds
-and added to ccflags by hints files.
-
-=item C<ccname>
-
-From F<Checkcc.U>:
-
-This can set either by hints files or by Configure. If using
-gcc, this is gcc, and if not, usually equal to cc, unimpressive, no?
-Some platforms, however, make good use of this by storing the
-flavor of the C compiler being used here. For example if using
-the Sun WorkShop suite, ccname will be C<workshop>.
-
-=item C<ccsymbols>
-
-From F<Cppsym.U>:
-
-The variable contains the symbols defined by the C compiler alone.
-The symbols defined by cpp or by cc when it calls cpp are not in
-this list, see cppsymbols and cppccsymbols.
-The list is a space-separated list of symbol=value tokens.
-
-=item C<ccversion>
-
-From F<Checkcc.U>:
-
-This can set either by hints files or by Configure. If using
-a (non-gcc) vendor cc, this variable may contain a version for
-the compiler.
-
-=item C<cf_by>
-
-From F<cf_who.U>:
-
-Login name of the person who ran the Configure script and answered the
-questions. This is used to tag both F<config.sh> and F<config_h.SH>.
-
-=item C<cf_email>
-
-From F<cf_email.U>:
-
-Electronic mail address of the person who ran Configure. This can be
-used by units that require the user's e-mail, like F<MailList.U>.
-
-=item C<cf_time>
-
-From F<cf_who.U>:
-
-Holds the output of the C<date> command when the configuration file was
-produced. This is used to tag both F<config.sh> and F<config_h.SH>.
-
-=item C<charbits>
-
-From F<charsize.U>:
-
-This variable contains the value of the C<CHARBITS> symbol, which
-indicates to the C program how many bits there are in a character.
-
-=item C<charsize>
-
-From F<charsize.U>:
-
-This variable contains the value of the C<CHARSIZE> symbol, which
-indicates to the C program how many bytes there are in a character.
-
-=item C<chgrp>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<chmod>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the chmod program. After Configure runs,
-the value is reset to a plain C<chmod> and is not useful.
-
-=item C<chown>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<clocktype>
-
-From F<d_times.U>:
-
-This variable holds the type returned by times(). It can be long,
-or clock_t on C<BSD> sites (in which case <sys/types.h> should be
-included).
-
-=item C<comm>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the comm program. After Configure runs,
-the value is reset to a plain C<comm> and is not useful.
-
-=item C<compress>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<config_arg0>
-
-From F<Options.U>:
-
-This variable contains the string used to invoke the Configure
-command, as reported by the shell in the $0 variable.
-
-=item C<config_argc>
-
-From F<Options.U>:
-
-This variable contains the number of command-line arguments
-passed to Configure, as reported by the shell in the $# variable.
-The individual arguments are stored as variables config_arg1,
-config_arg2, etc.
-
-=item C<config_args>
-
-From F<Options.U>:
-
-This variable contains a single string giving the command-line
-arguments passed to Configure. Spaces within arguments,
-quotes, and escaped characters are not correctly preserved.
-To reconstruct the command line, you must assemble the individual
-command line pieces, given in config_arg[0-9]*.
-
-=item C<contains>
-
-From F<contains.U>:
-
-This variable holds the command to do a grep with a proper return
-status. On most sane systems it is simply C<grep>. On insane systems
-it is a grep followed by a cat followed by a test. This variable
-is primarily for the use of other Configure units.
-
-=item C<cp>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the cp program. After Configure runs,
-the value is reset to a plain C<cp> and is not useful.
-
-=item C<cpio>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<cpp>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the cpp program. After Configure runs,
-the value is reset to a plain C<cpp> and is not useful.
-
-=item C<cpp_stuff>
-
-From F<cpp_stuff.U>:
-
-This variable contains an identification of the concatenation mechanism
-used by the C preprocessor.
-
-=item C<cppccsymbols>
-
-From F<Cppsym.U>:
-
-The variable contains the symbols defined by the C compiler
-when it calls cpp. The symbols defined by the cc alone or cpp
-alone are not in this list, see ccsymbols and cppsymbols.
-The list is a space-separated list of symbol=value tokens.
-
-=item C<cppflags>
-
-From F<ccflags.U>:
-
-This variable holds the flags that will be passed to the C pre-
-processor. It is up to the Makefile to use it.
-
-=item C<cpplast>
-
-From F<cppstdin.U>:
-
-This variable has the same functionality as cppminus, only it applies
-to cpprun and not cppstdin.
-
-=item C<cppminus>
-
-From F<cppstdin.U>:
-
-This variable contains the second part of the string which will invoke
-the C preprocessor on the standard input and produce to standard
-output. This variable will have the value C<-> if cppstdin needs
-a minus to specify standard input, otherwise the value is "".
-
-=item C<cpprun>
-
-From F<cppstdin.U>:
-
-This variable contains the command which will invoke a C preprocessor
-on standard input and put the output to stdout. It is guaranteed not
-to be a wrapper and may be a null string if no preprocessor can be
-made directly available. This preprocessor might be different from the
-one used by the C compiler. Don't forget to append cpplast after the
-preprocessor options.
-
-=item C<cppstdin>
-
-From F<cppstdin.U>:
-
-This variable contains the command which will invoke the C
-preprocessor on standard input and put the output to stdout.
-It is primarily used by other Configure units that ask about
-preprocessor symbols.
-
-=item C<cppsymbols>
-
-From F<Cppsym.U>:
-
-The variable contains the symbols defined by the C preprocessor
-alone. The symbols defined by cc or by cc when it calls cpp are
-not in this list, see ccsymbols and cppccsymbols.
-The list is a space-separated list of symbol=value tokens.
-
-=item C<crypt_r_proto>
-
-From F<d_crypt_r.U>:
-
-This variable encodes the prototype of crypt_r.
-It is zero if d_crypt_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_crypt_r
-is defined.
-
-=item C<cryptlib>
-
-From F<d_crypt.U>:
-
-This variable holds -lcrypt or the path to a F<libcrypt.a> archive if
-the crypt() function is not defined in the standard C library. It is
-up to the Makefile to use this.
-
-=item C<csh>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the csh program. After Configure runs,
-the value is reset to a plain C<csh> and is not useful.
-
-=item C<ctermid_r_proto>
-
-From F<d_ctermid_r.U>:
-
-This variable encodes the prototype of ctermid_r.
-It is zero if d_ctermid_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_ctermid_r
-is defined.
-
-=item C<ctime_r_proto>
-
-From F<d_ctime_r.U>:
-
-This variable encodes the prototype of ctime_r.
-It is zero if d_ctime_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_ctime_r
-is defined.
-
-=back
-
-=cut
-
-=head2 d
-
-=over 4
-
-=cut
-
-=item C<d__fwalk>
-
-From F<d__fwalk.U>:
-
-This variable conditionally defines C<HAS__FWALK> if _fwalk() is
-available to apply a function to all the file handles.
-
-=item C<d_access>
-
-From F<d_access.U>:
-
-This variable conditionally defines C<HAS_ACCESS> if the access() system
-call is available to check for access permissions using real IDs.
-
-=item C<d_accessx>
-
-From F<d_accessx.U>:
-
-This variable conditionally defines the C<HAS_ACCESSX> symbol, which
-indicates to the C program that the accessx() routine is available.
-
-=item C<d_aintl>
-
-From F<d_aintl.U>:
-
-This variable conditionally defines the C<HAS_AINTL> symbol, which
-indicates to the C program that the aintl() routine is available.
-If copysignl is also present we can emulate modfl.
-
-=item C<d_alarm>
-
-From F<d_alarm.U>:
-
-This variable conditionally defines the C<HAS_ALARM> symbol, which
-indicates to the C program that the alarm() routine is available.
-
-=item C<d_archlib>
-
-From F<archlib.U>:
-
-This variable conditionally defines C<ARCHLIB> to hold the pathname
-of architecture-dependent library files for $package. If
-$archlib is the same as $privlib, then this is set to undef.
-
-=item C<d_asctime64>
-
-From F<d_timefuncs64.U>:
-
-This variable conditionally defines the HAS_ASCTIME64 symbol, which
-indicates to the C program that the asctime64 () routine is available.
-
-=item C<d_asctime_r>
-
-From F<d_asctime_r.U>:
-
-This variable conditionally defines the C<HAS_ASCTIME_R> symbol,
-which indicates to the C program that the asctime_r()
-routine is available.
-
-=item C<d_atolf>
-
-From F<atolf.U>:
-
-This variable conditionally defines the C<HAS_ATOLF> symbol, which
-indicates to the C program that the atolf() routine is available.
-
-=item C<d_atoll>
-
-From F<atoll.U>:
-
-This variable conditionally defines the C<HAS_ATOLL> symbol, which
-indicates to the C program that the atoll() routine is available.
-
-=item C<d_attribute_deprecated>
-
-From F<d_attribut.U>:
-
-This variable conditionally defines C<HASATTRIBUTE_DEPRECATED>, which
-indicates that C<GCC> can handle the attribute for marking deprecated
-APIs
-
-=item C<d_attribute_format>
-
-From F<d_attribut.U>:
-
-This variable conditionally defines C<HASATTRIBUTE_FORMAT>, which
-indicates the C compiler can check for printf-like formats.
-
-=item C<d_attribute_malloc>
-
-From F<d_attribut.U>:
-
-This variable conditionally defines C<HASATTRIBUTE_MALLOC>, which
-indicates the C compiler can understand functions as having
-malloc-like semantics.
-
-=item C<d_attribute_nonnull>
-
-From F<d_attribut.U>:
-
-This variable conditionally defines C<HASATTRIBUTE_NONNULL>, which
-indicates that the C compiler can know that certain arguments
-must not be C<NULL>, and will check accordingly at compile time.
-
-=item C<d_attribute_noreturn>
-
-From F<d_attribut.U>:
-
-This variable conditionally defines C<HASATTRIBUTE_NORETURN>, which
-indicates that the C compiler can know that certain functions
-are guaranteed never to return.
-
-=item C<d_attribute_pure>
-
-From F<d_attribut.U>:
-
-This variable conditionally defines C<HASATTRIBUTE_PURE>, which
-indicates that the C compiler can know that certain functions
-are C<pure> functions, meaning that they have no side effects, and
-only rely on function input F<and/or> global data for their results.
-
-=item C<d_attribute_unused>
-
-From F<d_attribut.U>:
-
-This variable conditionally defines C<HASATTRIBUTE_UNUSED>, which
-indicates that the C compiler can know that certain variables
-and arguments may not always be used, and to not throw warnings
-if they don't get used.
-
-=item C<d_attribute_warn_unused_result>
-
-From F<d_attribut.U>:
-
-This variable conditionally defines
-C<HASATTRIBUTE_WARN_UNUSED_RESULT>, which indicates that the C
-compiler can know that certain functions have a return values
-that must not be ignored, such as malloc() or open().
-
-=item C<d_bcmp>
-
-From F<d_bcmp.U>:
-
-This variable conditionally defines the C<HAS_BCMP> symbol if
-the bcmp() routine is available to compare strings.
-
-=item C<d_bcopy>
-
-From F<d_bcopy.U>:
-
-This variable conditionally defines the C<HAS_BCOPY> symbol if
-the bcopy() routine is available to copy strings.
-
-=item C<d_bsd>
-
-From F<Guess.U>:
-
-This symbol conditionally defines the symbol C<BSD> when running on a
-C<BSD> system.
-
-=item C<d_bsdgetpgrp>
-
-From F<d_getpgrp.U>:
-
-This variable conditionally defines C<USE_BSD_GETPGRP> if
-getpgrp needs one arguments whereas C<USG> one needs none.
-
-=item C<d_bsdsetpgrp>
-
-From F<d_setpgrp.U>:
-
-This variable conditionally defines C<USE_BSD_SETPGRP> if
-setpgrp needs two arguments whereas C<USG> one needs none.
-See also d_setpgid for a C<POSIX> interface.
-
-=item C<d_builtin_choose_expr>
-
-From F<d_builtin.U>:
-
-This conditionally defines C<HAS_BUILTIN_CHOOSE_EXPR>, which
-indicates that the compiler supports __builtin_choose_expr(x,y,z).
-This built-in function is analogous to the C<x?y:z> operator in C,
-except that the expression returned has its type unaltered by
-promotion rules. Also, the built-in function does not evaluate
-the expression that was not chosen.
-
-=item C<d_builtin_expect>
-
-From F<d_builtin.U>:
-
-This conditionally defines C<HAS_BUILTIN_EXPECT>, which indicates
-that the compiler supports __builtin_expect(exp,c). You may use
-__builtin_expect to provide the compiler with branch prediction
-information.
-
-=item C<d_bzero>
-
-From F<d_bzero.U>:
-
-This variable conditionally defines the C<HAS_BZERO> symbol if
-the bzero() routine is available to set memory to 0.
-
-=item C<d_c99_variadic_macros>
-
-From F<d_c99_variadic.U>:
-
-This variable conditionally defines the HAS_C99_VARIADIC_MACROS
-symbol, which indicates to the C program that C99 variadic macros
-are available.
-
-=item C<d_casti32>
-
-From F<d_casti32.U>:
-
-This variable conditionally defines CASTI32, which indicates
-whether the C compiler can cast large floats to 32-bit ints.
-
-=item C<d_castneg>
-
-From F<d_castneg.U>:
-
-This variable conditionally defines C<CASTNEG>, which indicates
-whether the C compiler can cast negative float to unsigned.
-
-=item C<d_charvspr>
-
-From F<d_vprintf.U>:
-
-This variable conditionally defines C<CHARVSPRINTF> if this system
-has vsprintf returning type (char*). The trend seems to be to
-declare it as "int vsprintf()".
-
-=item C<d_chown>
-
-From F<d_chown.U>:
-
-This variable conditionally defines the C<HAS_CHOWN> symbol, which
-indicates to the C program that the chown() routine is available.
-
-=item C<d_chroot>
-
-From F<d_chroot.U>:
-
-This variable conditionally defines the C<HAS_CHROOT> symbol, which
-indicates to the C program that the chroot() routine is available.
-
-=item C<d_chsize>
-
-From F<d_chsize.U>:
-
-This variable conditionally defines the C<CHSIZE> symbol, which
-indicates to the C program that the chsize() routine is available
-to truncate files. You might need a -lx to get this routine.
-
-=item C<d_class>
-
-From F<d_class.U>:
-
-This variable conditionally defines the C<HAS_CLASS> symbol, which
-indicates to the C program that the class() routine is available.
-
-=item C<d_clearenv>
-
-From F<d_clearenv.U>:
-
-This variable conditionally defines the C<HAS_CLEARENV> symbol, which
-indicates to the C program that the clearenv () routine is available.
-
-=item C<d_closedir>
-
-From F<d_closedir.U>:
-
-This variable conditionally defines C<HAS_CLOSEDIR> if closedir() is
-available.
-
-=item C<d_cmsghdr_s>
-
-From F<d_cmsghdr_s.U>:
-
-This variable conditionally defines the C<HAS_STRUCT_CMSGHDR> symbol,
-which indicates that the struct cmsghdr is supported.
-
-=item C<d_const>
-
-From F<d_const.U>:
-
-This variable conditionally defines the C<HASCONST> symbol, which
-indicates to the C program that this C compiler knows about the
-const type.
-
-=item C<d_copysignl>
-
-From F<d_copysignl.U>:
-
-This variable conditionally defines the C<HAS_COPYSIGNL> symbol, which
-indicates to the C program that the copysignl() routine is available.
-If aintl is also present we can emulate modfl.
-
-=item C<d_cplusplus>
-
-From F<d_cplusplus.U>:
-
-This variable conditionally defines the C<USE_CPLUSPLUS> symbol, which
-indicates that a C++ compiler was used to compiled Perl and will be
-used to compile extensions.
-
-=item C<d_crypt>
-
-From F<d_crypt.U>:
-
-This variable conditionally defines the C<CRYPT> symbol, which
-indicates to the C program that the crypt() routine is available
-to encrypt passwords and the like.
-
-=item C<d_crypt_r>
-
-From F<d_crypt_r.U>:
-
-This variable conditionally defines the C<HAS_CRYPT_R> symbol,
-which indicates to the C program that the crypt_r()
-routine is available.
-
-=item C<d_csh>
-
-From F<d_csh.U>:
-
-This variable conditionally defines the C<CSH> symbol, which
-indicates to the C program that the C-shell exists.
-
-=item C<d_ctermid>
-
-From F<d_ctermid.U>:
-
-This variable conditionally defines C<CTERMID> if ctermid() is
-available to generate filename for terminal.
-
-=item C<d_ctermid_r>
-
-From F<d_ctermid_r.U>:
-
-This variable conditionally defines the C<HAS_CTERMID_R> symbol,
-which indicates to the C program that the ctermid_r()
-routine is available.
-
-=item C<d_ctime64>
-
-From F<d_timefuncs64.U>:
-
-This variable conditionally defines the HAS_CTIME64 symbol, which
-indicates to the C program that the ctime64 () routine is available.
-
-=item C<d_ctime_r>
-
-From F<d_ctime_r.U>:
-
-This variable conditionally defines the C<HAS_CTIME_R> symbol,
-which indicates to the C program that the ctime_r()
-routine is available.
-
-=item C<d_cuserid>
-
-From F<d_cuserid.U>:
-
-This variable conditionally defines the C<HAS_CUSERID> symbol, which
-indicates to the C program that the cuserid() routine is available
-to get character login names.
-
-=item C<d_dbl_dig>
-
-From F<d_dbl_dig.U>:
-
-This variable conditionally defines d_dbl_dig if this system's
-header files provide C<DBL_DIG>, which is the number of significant
-digits in a double precision number.
-
-=item C<d_dbminitproto>
-
-From F<d_dbminitproto.U>:
-
-This variable conditionally defines the C<HAS_DBMINIT_PROTO> symbol,
-which indicates to the C program that the system provides
-a prototype for the dbminit() function. Otherwise, it is
-up to the program to supply one.
-
-=item C<d_difftime>
-
-From F<d_difftime.U>:
-
-This variable conditionally defines the C<HAS_DIFFTIME> symbol, which
-indicates to the C program that the difftime() routine is available.
-
-=item C<d_difftime64>
-
-From F<d_timefuncs64.U>:
-
-This variable conditionally defines the HAS_DIFFTIME64 symbol, which
-indicates to the C program that the difftime64 () routine is available.
-
-=item C<d_dir_dd_fd>
-
-From F<d_dir_dd_fd.U>:
-
-This variable conditionally defines the C<HAS_DIR_DD_FD> symbol, which
-indicates that the C<DIR> directory stream type contains a member
-variable called dd_fd.
-
-=item C<d_dirfd>
-
-From F<d_dirfd.U>:
-
-This variable conditionally defines the C<HAS_DIRFD> constant,
-which indicates to the C program that dirfd() is available
-to return the file descriptor of a directory stream.
-
-=item C<d_dirnamlen>
-
-From F<i_dirent.U>:
-
-This variable conditionally defines C<DIRNAMLEN>, which indicates
-to the C program that the length of directory entry names is
-provided by a d_namelen field.
-
-=item C<d_dlerror>
-
-From F<d_dlerror.U>:
-
-This variable conditionally defines the C<HAS_DLERROR> symbol, which
-indicates to the C program that the dlerror() routine is available.
-
-=item C<d_dlopen>
-
-From F<d_dlopen.U>:
-
-This variable conditionally defines the C<HAS_DLOPEN> symbol, which
-indicates to the C program that the dlopen() routine is available.
-
-=item C<d_dlsymun>
-
-From F<d_dlsymun.U>:
-
-This variable conditionally defines C<DLSYM_NEEDS_UNDERSCORE>, which
-indicates that we need to prepend an underscore to the symbol
-name before calling dlsym().
-
-=item C<d_dosuid>
-
-From F<d_dosuid.U>:
-
-This variable conditionally defines the symbol C<DOSUID>, which
-tells the C program that it should insert setuid emulation code
-on hosts which have setuid #! scripts disabled.
-
-=item C<d_drand48_r>
-
-From F<d_drand48_r.U>:
-
-This variable conditionally defines the HAS_DRAND48_R symbol,
-which indicates to the C program that the drand48_r()
-routine is available.
-
-=item C<d_drand48proto>
-
-From F<d_drand48proto.U>:
-
-This variable conditionally defines the HAS_DRAND48_PROTO symbol,
-which indicates to the C program that the system provides
-a prototype for the drand48() function. Otherwise, it is
-up to the program to supply one.
-
-=item C<d_dup2>
-
-From F<d_dup2.U>:
-
-This variable conditionally defines HAS_DUP2 if dup2() is
-available to duplicate file descriptors.
-
-=item C<d_eaccess>
-
-From F<d_eaccess.U>:
-
-This variable conditionally defines the C<HAS_EACCESS> symbol, which
-indicates to the C program that the eaccess() routine is available.
-
-=item C<d_endgrent>
-
-From F<d_endgrent.U>:
-
-This variable conditionally defines the C<HAS_ENDGRENT> symbol, which
-indicates to the C program that the endgrent() routine is available
-for sequential access of the group database.
-
-=item C<d_endgrent_r>
-
-From F<d_endgrent_r.U>:
-
-This variable conditionally defines the C<HAS_ENDGRENT_R> symbol,
-which indicates to the C program that the endgrent_r()
-routine is available.
-
-=item C<d_endhent>
-
-From F<d_endhent.U>:
-
-This variable conditionally defines C<HAS_ENDHOSTENT> if endhostent() is
-available to close whatever was being used for host queries.
-
-=item C<d_endhostent_r>
-
-From F<d_endhostent_r.U>:
-
-This variable conditionally defines the C<HAS_ENDHOSTENT_R> symbol,
-which indicates to the C program that the endhostent_r()
-routine is available.
-
-=item C<d_endnent>
-
-From F<d_endnent.U>:
-
-This variable conditionally defines C<HAS_ENDNETENT> if endnetent() is
-available to close whatever was being used for network queries.
-
-=item C<d_endnetent_r>
-
-From F<d_endnetent_r.U>:
-
-This variable conditionally defines the C<HAS_ENDNETENT_R> symbol,
-which indicates to the C program that the endnetent_r()
-routine is available.
-
-=item C<d_endpent>
-
-From F<d_endpent.U>:
-
-This variable conditionally defines C<HAS_ENDPROTOENT> if endprotoent() is
-available to close whatever was being used for protocol queries.
-
-=item C<d_endprotoent_r>
-
-From F<d_endprotoent_r.U>:
-
-This variable conditionally defines the C<HAS_ENDPROTOENT_R> symbol,
-which indicates to the C program that the endprotoent_r()
-routine is available.
-
-=item C<d_endpwent>
-
-From F<d_endpwent.U>:
-
-This variable conditionally defines the C<HAS_ENDPWENT> symbol, which
-indicates to the C program that the endpwent() routine is available
-for sequential access of the passwd database.
-
-=item C<d_endpwent_r>
-
-From F<d_endpwent_r.U>:
-
-This variable conditionally defines the C<HAS_ENDPWENT_R> symbol,
-which indicates to the C program that the endpwent_r()
-routine is available.
-
-=item C<d_endsent>
-
-From F<d_endsent.U>:
-
-This variable conditionally defines C<HAS_ENDSERVENT> if endservent() is
-available to close whatever was being used for service queries.
-
-=item C<d_endservent_r>
-
-From F<d_endservent_r.U>:
-
-This variable conditionally defines the C<HAS_ENDSERVENT_R> symbol,
-which indicates to the C program that the endservent_r()
-routine is available.
-
-=item C<d_eofnblk>
-
-From F<nblock_io.U>:
-
-This variable conditionally defines C<EOF_NONBLOCK> if C<EOF> can be seen
-when reading from a non-blocking I/O source.
-
-=item C<d_eunice>
-
-From F<Guess.U>:
-
-This variable conditionally defines the symbols C<EUNICE> and C<VAX>, which
-alerts the C program that it must deal with idiosyncrasies of C<VMS>.
-
-=item C<d_faststdio>
-
-From F<d_faststdio.U>:
-
-This variable conditionally defines the C<HAS_FAST_STDIO> symbol,
-which indicates to the C program that the "fast stdio" is available
-to manipulate the stdio buffers directly.
-
-=item C<d_fchdir>
-
-From F<d_fchdir.U>:
-
-This variable conditionally defines the C<HAS_FCHDIR> symbol, which
-indicates to the C program that the fchdir() routine is available.
-
-=item C<d_fchmod>
-
-From F<d_fchmod.U>:
-
-This variable conditionally defines the C<HAS_FCHMOD> symbol, which
-indicates to the C program that the fchmod() routine is available
-to change mode of opened files.
-
-=item C<d_fchown>
-
-From F<d_fchown.U>:
-
-This variable conditionally defines the C<HAS_FCHOWN> symbol, which
-indicates to the C program that the fchown() routine is available
-to change ownership of opened files.
-
-=item C<d_fcntl>
-
-From F<d_fcntl.U>:
-
-This variable conditionally defines the C<HAS_FCNTL> symbol, and indicates
-whether the fcntl() function exists
-
-=item C<d_fcntl_can_lock>
-
-From F<d_fcntl_can_lock.U>:
-
-This variable conditionally defines the C<FCNTL_CAN_LOCK> symbol
-and indicates whether file locking with fcntl() works.
-
-=item C<d_fd_macros>
-
-From F<d_fd_set.U>:
-
-This variable contains the eventual value of the C<HAS_FD_MACROS> symbol,
-which indicates if your C compiler knows about the macros which
-manipulate an fd_set.
-
-=item C<d_fd_set>
-
-From F<d_fd_set.U>:
-
-This variable contains the eventual value of the C<HAS_FD_SET> symbol,
-which indicates if your C compiler knows about the fd_set typedef.
-
-=item C<d_fds_bits>
-
-From F<d_fd_set.U>:
-
-This variable contains the eventual value of the C<HAS_FDS_BITS> symbol,
-which indicates if your fd_set typedef contains the fds_bits member.
-If you have an fd_set typedef, but the dweebs who installed it did
-a half-fast job and neglected to provide the macros to manipulate
-an fd_set, C<HAS_FDS_BITS> will let us know how to fix the gaffe.
-
-=item C<d_fgetpos>
-
-From F<d_fgetpos.U>:
-
-This variable conditionally defines C<HAS_FGETPOS> if fgetpos() is
-available to get the file position indicator.
-
-=item C<d_finite>
-
-From F<d_finite.U>:
-
-This variable conditionally defines the C<HAS_FINITE> symbol, which
-indicates to the C program that the finite() routine is available.
-
-=item C<d_finitel>
-
-From F<d_finitel.U>:
-
-This variable conditionally defines the C<HAS_FINITEL> symbol, which
-indicates to the C program that the finitel() routine is available.
-
-=item C<d_flexfnam>
-
-From F<d_flexfnam.U>:
-
-This variable conditionally defines the C<FLEXFILENAMES> symbol, which
-indicates that the system supports filenames longer than 14 characters.
-
-=item C<d_flock>
-
-From F<d_flock.U>:
-
-This variable conditionally defines C<HAS_FLOCK> if flock() is
-available to do file locking.
-
-=item C<d_flockproto>
-
-From F<d_flockproto.U>:
-
-This variable conditionally defines the C<HAS_FLOCK_PROTO> symbol,
-which indicates to the C program that the system provides
-a prototype for the flock() function. Otherwise, it is
-up to the program to supply one.
-
-=item C<d_fork>
-
-From F<d_fork.U>:
-
-This variable conditionally defines the C<HAS_FORK> symbol, which
-indicates to the C program that the fork() routine is available.
-
-=item C<d_fp_class>
-
-From F<d_fp_class.U>:
-
-This variable conditionally defines the C<HAS_FP_CLASS> symbol, which
-indicates to the C program that the fp_class() routine is available.
-
-=item C<d_fpathconf>
-
-From F<d_pathconf.U>:
-
-This variable conditionally defines the C<HAS_FPATHCONF> symbol, which
-indicates to the C program that the pathconf() routine is available
-to determine file-system related limits and options associated
-with a given open file descriptor.
-
-=item C<d_fpclass>
-
-From F<d_fpclass.U>:
-
-This variable conditionally defines the C<HAS_FPCLASS> symbol, which
-indicates to the C program that the fpclass() routine is available.
-
-=item C<d_fpclassify>
-
-From F<d_fpclassify.U>:
-
-This variable conditionally defines the C<HAS_FPCLASSIFY> symbol, which
-indicates to the C program that the fpclassify() routine is available.
-
-=item C<d_fpclassl>
-
-From F<d_fpclassl.U>:
-
-This variable conditionally defines the C<HAS_FPCLASSL> symbol, which
-indicates to the C program that the fpclassl() routine is available.
-
-=item C<d_fpos64_t>
-
-From F<d_fpos64_t.U>:
-
-This symbol will be defined if the C compiler supports fpos64_t.
-
-=item C<d_frexpl>
-
-From F<d_frexpl.U>:
-
-This variable conditionally defines the C<HAS_FREXPL> symbol, which
-indicates to the C program that the frexpl() routine is available.
-
-=item C<d_fs_data_s>
-
-From F<d_fs_data_s.U>:
-
-This variable conditionally defines the C<HAS_STRUCT_FS_DATA> symbol,
-which indicates that the struct fs_data is supported.
-
-=item C<d_fseeko>
-
-From F<d_fseeko.U>:
-
-This variable conditionally defines the C<HAS_FSEEKO> symbol, which
-indicates to the C program that the fseeko() routine is available.
-
-=item C<d_fsetpos>
-
-From F<d_fsetpos.U>:
-
-This variable conditionally defines C<HAS_FSETPOS> if fsetpos() is
-available to set the file position indicator.
-
-=item C<d_fstatfs>
-
-From F<d_fstatfs.U>:
-
-This variable conditionally defines the C<HAS_FSTATFS> symbol, which
-indicates to the C program that the fstatfs() routine is available.
-
-=item C<d_fstatvfs>
-
-From F<d_statvfs.U>:
-
-This variable conditionally defines the C<HAS_FSTATVFS> symbol, which
-indicates to the C program that the fstatvfs() routine is available.
-
-=item C<d_fsync>
-
-From F<d_fsync.U>:
-
-This variable conditionally defines the C<HAS_FSYNC> symbol, which
-indicates to the C program that the fsync() routine is available.
-
-=item C<d_ftello>
-
-From F<d_ftello.U>:
-
-This variable conditionally defines the C<HAS_FTELLO> symbol, which
-indicates to the C program that the ftello() routine is available.
-
-=item C<d_ftime>
-
-From F<d_ftime.U>:
-
-This variable conditionally defines the C<HAS_FTIME> symbol, which indicates
-that the ftime() routine exists. The ftime() routine is basically
-a sub-second accuracy clock.
-
-=item C<d_futimes>
-
-From F<d_futimes.U>:
-
-This variable conditionally defines the C<HAS_FUTIMES> symbol, which
-indicates to the C program that the futimes() routine is available.
-
-=item C<d_Gconvert>
-
-From F<d_gconvert.U>:
-
-This variable holds what Gconvert is defined as to convert
-floating point numbers into strings. By default, Configure
-sets C<this> macro to use the first of gconvert, gcvt, or sprintf
-that pass sprintf-%g-like behaviour tests. If perl is using
-long doubles, the macro uses the first of the following
-functions that pass Configure's tests: qgcvt, sprintf (if
-Configure knows how to make sprintf format long doubles--see
-sPRIgldbl), gconvert, gcvt, and sprintf (casting to double).
-The gconvert_preference and gconvert_ld_preference variables
-can be used to alter Configure's preferences, for doubles and
-long doubles, respectively. If present, they contain a
-space-separated list of one or more of the above function
-names in the order they should be tried.
-
-d_Gconvert may be set to override Configure with a platform-
-specific function. If this function expects a double, a
-different value may need to be set by the F<uselongdouble.cbu>
-call-back unit so that long doubles can be formatted without
-loss of precision.
-
-=item C<d_gdbm_ndbm_h_uses_prototypes>
-
-From F<i_ndbm.U>:
-
-This variable conditionally defines the C<NDBM_H_USES_PROTOTYPES> symbol,
-which indicates that the gdbm-F<ndbm.h> include file uses real C<ANSI> C
-prototypes instead of K&R style function declarations. K&R style
-declarations are unsupported in C++, so the include file requires
-special handling when using a C++ compiler and this variable is
-undefined. Consult the different d_*ndbm_h_uses_prototypes variables
-to get the same information for alternative F<ndbm.h> include files.
-
-=item C<d_gdbmndbm_h_uses_prototypes>
-
-From F<i_ndbm.U>:
-
-This variable conditionally defines the C<NDBM_H_USES_PROTOTYPES> symbol,
-which indicates that the F<gdbm/ndbm.h> include file uses real C<ANSI> C
-prototypes instead of K&R style function declarations. K&R style
-declarations are unsupported in C++, so the include file requires
-special handling when using a C++ compiler and this variable is
-undefined. Consult the different d_*ndbm_h_uses_prototypes variables
-to get the same information for alternative F<ndbm.h> include files.
-
-=item C<d_getaddrinfo>
-
-From F<d_getaddrinfo.U>:
-
-This variable conditionally defines the C<HAS_GETADDRINFO> symbol,
-which indicates to the C program that the getaddrinfo() function
-is available.
-
-=item C<d_getcwd>
-
-From F<d_getcwd.U>:
-
-This variable conditionally defines the C<HAS_GETCWD> symbol, which
-indicates to the C program that the getcwd() routine is available
-to get the current working directory.
-
-=item C<d_getespwnam>
-
-From F<d_getespwnam.U>:
-
-This variable conditionally defines C<HAS_GETESPWNAM> if getespwnam() is
-available to retrieve enhanced (shadow) password entries by name.
-
-=item C<d_getfsstat>
-
-From F<d_getfsstat.U>:
-
-This variable conditionally defines the C<HAS_GETFSSTAT> symbol, which
-indicates to the C program that the getfsstat() routine is available.
-
-=item C<d_getgrent>
-
-From F<d_getgrent.U>:
-
-This variable conditionally defines the C<HAS_GETGRENT> symbol, which
-indicates to the C program that the getgrent() routine is available
-for sequential access of the group database.
-
-=item C<d_getgrent_r>
-
-From F<d_getgrent_r.U>:
-
-This variable conditionally defines the C<HAS_GETGRENT_R> symbol,
-which indicates to the C program that the getgrent_r()
-routine is available.
-
-=item C<d_getgrgid_r>
-
-From F<d_getgrgid_r.U>:
-
-This variable conditionally defines the C<HAS_GETGRGID_R> symbol,
-which indicates to the C program that the getgrgid_r()
-routine is available.
-
-=item C<d_getgrnam_r>
-
-From F<d_getgrnam_r.U>:
-
-This variable conditionally defines the C<HAS_GETGRNAM_R> symbol,
-which indicates to the C program that the getgrnam_r()
-routine is available.
-
-=item C<d_getgrps>
-
-From F<d_getgrps.U>:
-
-This variable conditionally defines the C<HAS_GETGROUPS> symbol, which
-indicates to the C program that the getgroups() routine is available
-to get the list of process groups.
-
-=item C<d_gethbyaddr>
-
-From F<d_gethbyad.U>:
-
-This variable conditionally defines the C<HAS_GETHOSTBYADDR> symbol, which
-indicates to the C program that the gethostbyaddr() routine is available
-to look up hosts by their C<IP> addresses.
-
-=item C<d_gethbyname>
-
-From F<d_gethbynm.U>:
-
-This variable conditionally defines the C<HAS_GETHOSTBYNAME> symbol, which
-indicates to the C program that the gethostbyname() routine is available
-to look up host names in some data base or other.
-
-=item C<d_gethent>
-
-From F<d_gethent.U>:
-
-This variable conditionally defines C<HAS_GETHOSTENT> if gethostent() is
-available to look up host names in some data base or another.
-
-=item C<d_gethname>
-
-From F<d_gethname.U>:
-
-This variable conditionally defines the C<HAS_GETHOSTNAME> symbol, which
-indicates to the C program that the gethostname() routine may be
-used to derive the host name.
-
-=item C<d_gethostbyaddr_r>
-
-From F<d_gethostbyaddr_r.U>:
-
-This variable conditionally defines the C<HAS_GETHOSTBYADDR_R> symbol,
-which indicates to the C program that the gethostbyaddr_r()
-routine is available.
-
-=item C<d_gethostbyname_r>
-
-From F<d_gethostbyname_r.U>:
-
-This variable conditionally defines the C<HAS_GETHOSTBYNAME_R> symbol,
-which indicates to the C program that the gethostbyname_r()
-routine is available.
-
-=item C<d_gethostent_r>
-
-From F<d_gethostent_r.U>:
-
-This variable conditionally defines the C<HAS_GETHOSTENT_R> symbol,
-which indicates to the C program that the gethostent_r()
-routine is available.
-
-=item C<d_gethostprotos>
-
-From F<d_gethostprotos.U>:
-
-This variable conditionally defines the C<HAS_GETHOST_PROTOS> symbol,
-which indicates to the C program that <netdb.h> supplies
-prototypes for the various gethost*() functions.
-See also F<netdbtype.U> for probing for various netdb types.
-
-=item C<d_getitimer>
-
-From F<d_getitimer.U>:
-
-This variable conditionally defines the C<HAS_GETITIMER> symbol, which
-indicates to the C program that the getitimer() routine is available.
-
-=item C<d_getlogin>
-
-From F<d_getlogin.U>:
-
-This variable conditionally defines the C<HAS_GETLOGIN> symbol, which
-indicates to the C program that the getlogin() routine is available
-to get the login name.
-
-=item C<d_getlogin_r>
-
-From F<d_getlogin_r.U>:
-
-This variable conditionally defines the C<HAS_GETLOGIN_R> symbol,
-which indicates to the C program that the getlogin_r()
-routine is available.
-
-=item C<d_getmnt>
-
-From F<d_getmnt.U>:
-
-This variable conditionally defines the C<HAS_GETMNT> symbol, which
-indicates to the C program that the getmnt() routine is available
-to retrieve one or more mount info blocks by filename.
-
-=item C<d_getmntent>
-
-From F<d_getmntent.U>:
-
-This variable conditionally defines the C<HAS_GETMNTENT> symbol, which
-indicates to the C program that the getmntent() routine is available
-to iterate through mounted files to get their mount info.
-
-=item C<d_getnameinfo>
-
-From F<d_getnameinfo.U>:
-
-This variable conditionally defines the C<HAS_GETNAMEINFO> symbol,
-which indicates to the C program that the getnameinfo() function
-is available.
-
-=item C<d_getnbyaddr>
-
-From F<d_getnbyad.U>:
-
-This variable conditionally defines the C<HAS_GETNETBYADDR> symbol, which
-indicates to the C program that the getnetbyaddr() routine is available
-to look up networks by their C<IP> addresses.
-
-=item C<d_getnbyname>
-
-From F<d_getnbynm.U>:
-
-This variable conditionally defines the C<HAS_GETNETBYNAME> symbol, which
-indicates to the C program that the getnetbyname() routine is available
-to look up networks by their names.
-
-=item C<d_getnent>
-
-From F<d_getnent.U>:
-
-This variable conditionally defines C<HAS_GETNETENT> if getnetent() is
-available to look up network names in some data base or another.
-
-=item C<d_getnetbyaddr_r>
-
-From F<d_getnetbyaddr_r.U>:
-
-This variable conditionally defines the C<HAS_GETNETBYADDR_R> symbol,
-which indicates to the C program that the getnetbyaddr_r()
-routine is available.
-
-=item C<d_getnetbyname_r>
-
-From F<d_getnetbyname_r.U>:
-
-This variable conditionally defines the C<HAS_GETNETBYNAME_R> symbol,
-which indicates to the C program that the getnetbyname_r()
-routine is available.
-
-=item C<d_getnetent_r>
-
-From F<d_getnetent_r.U>:
-
-This variable conditionally defines the C<HAS_GETNETENT_R> symbol,
-which indicates to the C program that the getnetent_r()
-routine is available.
-
-=item C<d_getnetprotos>
-
-From F<d_getnetprotos.U>:
-
-This variable conditionally defines the C<HAS_GETNET_PROTOS> symbol,
-which indicates to the C program that <netdb.h> supplies
-prototypes for the various getnet*() functions.
-See also F<netdbtype.U> for probing for various netdb types.
-
-=item C<d_getpagsz>
-
-From F<d_getpagsz.U>:
-
-This variable conditionally defines C<HAS_GETPAGESIZE> if getpagesize()
-is available to get the system page size.
-
-=item C<d_getpbyname>
-
-From F<d_getprotby.U>:
-
-This variable conditionally defines the C<HAS_GETPROTOBYNAME>
-symbol, which indicates to the C program that the
-getprotobyname() routine is available to look up protocols
-by their name.
-
-=item C<d_getpbynumber>
-
-From F<d_getprotby.U>:
-
-This variable conditionally defines the C<HAS_GETPROTOBYNUMBER>
-symbol, which indicates to the C program that the
-getprotobynumber() routine is available to look up protocols
-by their number.
-
-=item C<d_getpent>
-
-From F<d_getpent.U>:
-
-This variable conditionally defines C<HAS_GETPROTOENT> if getprotoent() is
-available to look up protocols in some data base or another.
-
-=item C<d_getpgid>
-
-From F<d_getpgid.U>:
-
-This variable conditionally defines the C<HAS_GETPGID> symbol, which
-indicates to the C program that the getpgid(pid) function
-is available to get the process group id.
-
-=item C<d_getpgrp>
-
-From F<d_getpgrp.U>:
-
-This variable conditionally defines C<HAS_GETPGRP> if getpgrp() is
-available to get the current process group.
-
-=item C<d_getpgrp2>
-
-From F<d_getpgrp2.U>:
-
-This variable conditionally defines the HAS_GETPGRP2 symbol, which
-indicates to the C program that the getpgrp2() (as in F<DG/C<UX>>) routine
-is available to get the current process group.
-
-=item C<d_getppid>
-
-From F<d_getppid.U>:
-
-This variable conditionally defines the C<HAS_GETPPID> symbol, which
-indicates to the C program that the getppid() routine is available
-to get the parent process C<ID>.
-
-=item C<d_getprior>
-
-From F<d_getprior.U>:
-
-This variable conditionally defines C<HAS_GETPRIORITY> if getpriority()
-is available to get a process's priority.
-
-=item C<d_getprotobyname_r>
-
-From F<d_getprotobyname_r.U>:
-
-This variable conditionally defines the C<HAS_GETPROTOBYNAME_R> symbol,
-which indicates to the C program that the getprotobyname_r()
-routine is available.
-
-=item C<d_getprotobynumber_r>
-
-From F<d_getprotobynumber_r.U>:
-
-This variable conditionally defines the C<HAS_GETPROTOBYNUMBER_R> symbol,
-which indicates to the C program that the getprotobynumber_r()
-routine is available.
-
-=item C<d_getprotoent_r>
-
-From F<d_getprotoent_r.U>:
-
-This variable conditionally defines the C<HAS_GETPROTOENT_R> symbol,
-which indicates to the C program that the getprotoent_r()
-routine is available.
-
-=item C<d_getprotoprotos>
-
-From F<d_getprotoprotos.U>:
-
-This variable conditionally defines the C<HAS_GETPROTO_PROTOS> symbol,
-which indicates to the C program that <netdb.h> supplies
-prototypes for the various getproto*() functions.
-See also F<netdbtype.U> for probing for various netdb types.
-
-=item C<d_getprpwnam>
-
-From F<d_getprpwnam.U>:
-
-This variable conditionally defines C<HAS_GETPRPWNAM> if getprpwnam() is
-available to retrieve protected (shadow) password entries by name.
-
-=item C<d_getpwent>
-
-From F<d_getpwent.U>:
-
-This variable conditionally defines the C<HAS_GETPWENT> symbol, which
-indicates to the C program that the getpwent() routine is available
-for sequential access of the passwd database.
-
-=item C<d_getpwent_r>
-
-From F<d_getpwent_r.U>:
-
-This variable conditionally defines the C<HAS_GETPWENT_R> symbol,
-which indicates to the C program that the getpwent_r()
-routine is available.
-
-=item C<d_getpwnam_r>
-
-From F<d_getpwnam_r.U>:
-
-This variable conditionally defines the C<HAS_GETPWNAM_R> symbol,
-which indicates to the C program that the getpwnam_r()
-routine is available.
-
-=item C<d_getpwuid_r>
-
-From F<d_getpwuid_r.U>:
-
-This variable conditionally defines the C<HAS_GETPWUID_R> symbol,
-which indicates to the C program that the getpwuid_r()
-routine is available.
-
-=item C<d_getsbyname>
-
-From F<d_getsrvby.U>:
-
-This variable conditionally defines the C<HAS_GETSERVBYNAME>
-symbol, which indicates to the C program that the
-getservbyname() routine is available to look up services
-by their name.
-
-=item C<d_getsbyport>
-
-From F<d_getsrvby.U>:
-
-This variable conditionally defines the C<HAS_GETSERVBYPORT>
-symbol, which indicates to the C program that the
-getservbyport() routine is available to look up services
-by their port.
-
-=item C<d_getsent>
-
-From F<d_getsent.U>:
-
-This variable conditionally defines C<HAS_GETSERVENT> if getservent() is
-available to look up network services in some data base or another.
-
-=item C<d_getservbyname_r>
-
-From F<d_getservbyname_r.U>:
-
-This variable conditionally defines the C<HAS_GETSERVBYNAME_R> symbol,
-which indicates to the C program that the getservbyname_r()
-routine is available.
-
-=item C<d_getservbyport_r>
-
-From F<d_getservbyport_r.U>:
-
-This variable conditionally defines the C<HAS_GETSERVBYPORT_R> symbol,
-which indicates to the C program that the getservbyport_r()
-routine is available.
-
-=item C<d_getservent_r>
-
-From F<d_getservent_r.U>:
-
-This variable conditionally defines the C<HAS_GETSERVENT_R> symbol,
-which indicates to the C program that the getservent_r()
-routine is available.
-
-=item C<d_getservprotos>
-
-From F<d_getservprotos.U>:
-
-This variable conditionally defines the C<HAS_GETSERV_PROTOS> symbol,
-which indicates to the C program that <netdb.h> supplies
-prototypes for the various getserv*() functions.
-See also F<netdbtype.U> for probing for various netdb types.
-
-=item C<d_getspnam>
-
-From F<d_getspnam.U>:
-
-This variable conditionally defines C<HAS_GETSPNAM> if getspnam() is
-available to retrieve SysV shadow password entries by name.
-
-=item C<d_getspnam_r>
-
-From F<d_getspnam_r.U>:
-
-This variable conditionally defines the C<HAS_GETSPNAM_R> symbol,
-which indicates to the C program that the getspnam_r()
-routine is available.
-
-=item C<d_gettimeod>
-
-From F<d_ftime.U>:
-
-This variable conditionally defines the C<HAS_GETTIMEOFDAY> symbol, which
-indicates that the gettimeofday() system call exists (to obtain a
-sub-second accuracy clock). You should probably include <sys/resource.h>.
-
-=item C<d_gmtime64>
-
-From F<d_timefuncs64.U>:
-
-This variable conditionally defines the HAS_GMTIME64 symbol, which
-indicates to the C program that the gmtime64 () routine is available.
-
-=item C<d_gmtime_r>
-
-From F<d_gmtime_r.U>:
-
-This variable conditionally defines the C<HAS_GMTIME_R> symbol,
-which indicates to the C program that the gmtime_r()
-routine is available.
-
-=item C<d_gnulibc>
-
-From F<d_gnulibc.U>:
-
-Defined if we're dealing with the C<GNU> C Library.
-
-=item C<d_grpasswd>
-
-From F<i_grp.U>:
-
-This variable conditionally defines C<GRPASSWD>, which indicates
-that struct group in <grp.h> contains gr_passwd.
-
-=item C<d_hasmntopt>
-
-From F<d_hasmntopt.U>:
-
-This variable conditionally defines the C<HAS_HASMNTOPT> symbol, which
-indicates to the C program that the hasmntopt() routine is available
-to query the mount options of file systems.
-
-=item C<d_htonl>
-
-From F<d_htonl.U>:
-
-This variable conditionally defines C<HAS_HTONL> if htonl() and its
-friends are available to do network order byte swapping.
-
-=item C<d_ilogbl>
-
-From F<d_ilogbl.U>:
-
-This variable conditionally defines the C<HAS_ILOGBL> symbol, which
-indicates to the C program that the ilogbl() routine is available.
-If scalbnl is also present we can emulate frexpl.
-
-=item C<d_inc_version_list>
-
-From F<inc_version_list.U>:
-
-This variable conditionally defines C<PERL_INC_VERSION_LIST>.
-It is set to undef when C<PERL_INC_VERSION_LIST> is empty.
-
-=item C<d_index>
-
-From F<d_strchr.U>:
-
-This variable conditionally defines C<HAS_INDEX> if index() and
-rindex() are available for string searching.
-
-=item C<d_inetaton>
-
-From F<d_inetaton.U>:
-
-This variable conditionally defines the C<HAS_INET_ATON> symbol, which
-indicates to the C program that the inet_aton() function is available
-to parse C<IP> address C<dotted-quad> strings.
-
-=item C<d_inetntop>
-
-From F<d_inetntop.U>:
-
-This variable conditionally defines the C<HAS_INETNTOP> symbol,
-which indicates to the C program that the inet_ntop() function
-is available.
-
-=item C<d_inetpton>
-
-From F<d_inetpton.U>:
-
-This variable conditionally defines the C<HAS_INETPTON> symbol,
-which indicates to the C program that the inet_pton() function
-is available.
-
-=item C<d_int64_t>
-
-From F<d_int64_t.U>:
-
-This symbol will be defined if the C compiler supports int64_t.
-
-=item C<d_ipv6_mreq>
-
-From F<d_socket.U>:
-
-This variable conditionally defines the HAS_IPV6_MREQ symbol, which
-indicates the availability of a struct ipv6_mreq.
-
-=item C<d_isascii>
-
-From F<d_isascii.U>:
-
-This variable conditionally defines the C<HAS_ISASCII> constant,
-which indicates to the C program that isascii() is available.
-
-=item C<d_isblank>
-
-From F<d_isblank.U>:
-
-This variable conditionally defines the C<HAS_ISBLANK> constant,
-which indicates to the C program that isblank() is available.
-
-=item C<d_isfinite>
-
-From F<d_isfinite.U>:
-
-This variable conditionally defines the C<HAS_ISFINITE> symbol, which
-indicates to the C program that the isfinite() routine is available.
-
-=item C<d_isinf>
-
-From F<d_isinf.U>:
-
-This variable conditionally defines the C<HAS_ISINF> symbol, which
-indicates to the C program that the isinf() routine is available.
-
-=item C<d_isnan>
-
-From F<d_isnan.U>:
-
-This variable conditionally defines the C<HAS_ISNAN> symbol, which
-indicates to the C program that the isnan() routine is available.
-
-=item C<d_isnanl>
-
-From F<d_isnanl.U>:
-
-This variable conditionally defines the C<HAS_ISNANL> symbol, which
-indicates to the C program that the isnanl() routine is available.
-
-=item C<d_killpg>
-
-From F<d_killpg.U>:
-
-This variable conditionally defines the C<HAS_KILLPG> symbol, which
-indicates to the C program that the killpg() routine is available
-to kill process groups.
-
-=item C<d_lchown>
-
-From F<d_lchown.U>:
-
-This variable conditionally defines the C<HAS_LCHOWN> symbol, which
-indicates to the C program that the lchown() routine is available
-to operate on a symbolic link (instead of following the link).
-
-=item C<d_ldbl_dig>
-
-From F<d_ldbl_dig.U>:
-
-This variable conditionally defines d_ldbl_dig if this system's
-header files provide C<LDBL_DIG>, which is the number of significant
-digits in a long double precision number.
-
-=item C<d_libm_lib_version>
-
-From F<d_libm_lib_version.U>:
-
-This variable conditionally defines the C<LIBM_LIB_VERSION> symbol,
-which indicates to the C program that F<math.h> defines C<_LIB_VERSION>
-being available in libm
-
-=item C<d_link>
-
-From F<d_link.U>:
-
-This variable conditionally defines C<HAS_LINK> if link() is
-available to create hard links.
-
-=item C<d_localtime64>
-
-From F<d_timefuncs64.U>:
-
-This variable conditionally defines the HAS_LOCALTIME64 symbol, which
-indicates to the C program that the localtime64 () routine is available.
-
-=item C<d_localtime_r>
-
-From F<d_localtime_r.U>:
-
-This variable conditionally defines the C<HAS_LOCALTIME_R> symbol,
-which indicates to the C program that the localtime_r()
-routine is available.
-
-=item C<d_localtime_r_needs_tzset>
-
-From F<d_localtime_r.U>:
-
-This variable conditionally defines the C<LOCALTIME_R_NEEDS_TZSET>
-symbol, which makes us call tzset before localtime_r()
-
-=item C<d_locconv>
-
-From F<d_locconv.U>:
-
-This variable conditionally defines C<HAS_LOCALECONV> if localeconv() is
-available for numeric and monetary formatting conventions.
-
-=item C<d_lockf>
-
-From F<d_lockf.U>:
-
-This variable conditionally defines C<HAS_LOCKF> if lockf() is
-available to do file locking.
-
-=item C<d_longdbl>
-
-From F<d_longdbl.U>:
-
-This variable conditionally defines C<HAS_LONG_DOUBLE> if
-the long double type is supported.
-
-=item C<d_longlong>
-
-From F<d_longlong.U>:
-
-This variable conditionally defines C<HAS_LONG_LONG> if
-the long long type is supported.
-
-=item C<d_lseekproto>
-
-From F<d_lseekproto.U>:
-
-This variable conditionally defines the C<HAS_LSEEK_PROTO> symbol,
-which indicates to the C program that the system provides
-a prototype for the lseek() function. Otherwise, it is
-up to the program to supply one.
-
-=item C<d_lstat>
-
-From F<d_lstat.U>:
-
-This variable conditionally defines C<HAS_LSTAT> if lstat() is
-available to do file stats on symbolic links.
-
-=item C<d_madvise>
-
-From F<d_madvise.U>:
-
-This variable conditionally defines C<HAS_MADVISE> if madvise() is
-available to map a file into memory.
-
-=item C<d_malloc_good_size>
-
-From F<d_malloc_size.U>:
-
-This symbol, if defined, indicates that the malloc_good_size
-routine is available for use.
-
-=item C<d_malloc_size>
-
-From F<d_malloc_size.U>:
-
-This symbol, if defined, indicates that the malloc_size
-routine is available for use.
-
-=item C<d_mblen>
-
-From F<d_mblen.U>:
-
-This variable conditionally defines the C<HAS_MBLEN> symbol, which
-indicates to the C program that the mblen() routine is available
-to find the number of bytes in a multibye character.
-
-=item C<d_mbstowcs>
-
-From F<d_mbstowcs.U>:
-
-This variable conditionally defines the C<HAS_MBSTOWCS> symbol, which
-indicates to the C program that the mbstowcs() routine is available
-to convert a multibyte string into a wide character string.
-
-=item C<d_mbtowc>
-
-From F<d_mbtowc.U>:
-
-This variable conditionally defines the C<HAS_MBTOWC> symbol, which
-indicates to the C program that the mbtowc() routine is available
-to convert multibyte to a wide character.
-
-=item C<d_memchr>
-
-From F<d_memchr.U>:
-
-This variable conditionally defines the C<HAS_MEMCHR> symbol, which
-indicates to the C program that the memchr() routine is available
-to locate characters within a C string.
-
-=item C<d_memcmp>
-
-From F<d_memcmp.U>:
-
-This variable conditionally defines the C<HAS_MEMCMP> symbol, which
-indicates to the C program that the memcmp() routine is available
-to compare blocks of memory.
-
-=item C<d_memcpy>
-
-From F<d_memcpy.U>:
-
-This variable conditionally defines the C<HAS_MEMCPY> symbol, which
-indicates to the C program that the memcpy() routine is available
-to copy blocks of memory.
-
-=item C<d_memmove>
-
-From F<d_memmove.U>:
-
-This variable conditionally defines the C<HAS_MEMMOVE> symbol, which
-indicates to the C program that the memmove() routine is available
-to copy potentially overlapping blocks of memory.
-
-=item C<d_memset>
-
-From F<d_memset.U>:
-
-This variable conditionally defines the C<HAS_MEMSET> symbol, which
-indicates to the C program that the memset() routine is available
-to set blocks of memory.
-
-=item C<d_mkdir>
-
-From F<d_mkdir.U>:
-
-This variable conditionally defines the C<HAS_MKDIR> symbol, which
-indicates to the C program that the mkdir() routine is available
-to create F<directories.>.
-
-=item C<d_mkdtemp>
-
-From F<d_mkdtemp.U>:
-
-This variable conditionally defines the C<HAS_MKDTEMP> symbol, which
-indicates to the C program that the mkdtemp() routine is available
-to exclusively create a uniquely named temporary directory.
-
-=item C<d_mkfifo>
-
-From F<d_mkfifo.U>:
-
-This variable conditionally defines the C<HAS_MKFIFO> symbol, which
-indicates to the C program that the mkfifo() routine is available.
-
-=item C<d_mkstemp>
-
-From F<d_mkstemp.U>:
-
-This variable conditionally defines the C<HAS_MKSTEMP> symbol, which
-indicates to the C program that the mkstemp() routine is available
-to exclusively create and open a uniquely named temporary file.
-
-=item C<d_mkstemps>
-
-From F<d_mkstemps.U>:
-
-This variable conditionally defines the C<HAS_MKSTEMPS> symbol, which
-indicates to the C program that the mkstemps() routine is available
-to exclusively create and open a uniquely named (with a suffix)
-temporary file.
-
-=item C<d_mktime>
-
-From F<d_mktime.U>:
-
-This variable conditionally defines the C<HAS_MKTIME> symbol, which
-indicates to the C program that the mktime() routine is available.
-
-=item C<d_mktime64>
-
-From F<d_timefuncs64.U>:
-
-This variable conditionally defines the HAS_MKTIME64 symbol, which
-indicates to the C program that the mktime64 () routine is available.
-
-=item C<d_mmap>
-
-From F<d_mmap.U>:
-
-This variable conditionally defines C<HAS_MMAP> if mmap() is
-available to map a file into memory.
-
-=item C<d_modfl>
-
-From F<d_modfl.U>:
-
-This variable conditionally defines the C<HAS_MODFL> symbol, which
-indicates to the C program that the modfl() routine is available.
-
-=item C<d_modfl_pow32_bug>
-
-From F<d_modfl.U>:
-
-This variable conditionally defines the HAS_MODFL_POW32_BUG symbol,
-which indicates that modfl() is broken for long doubles >= pow(2, 32).
-For example from 4294967303.150000 one would get 4294967302.000000
-and 1.150000. The bug has been seen in certain versions of glibc,
-release 2.2.2 is known to be okay.
-
-=item C<d_modflproto>
-
-From F<d_modfl.U>:
-
-This symbol, if defined, indicates that the system provides
-a prototype for the modfl() function. Otherwise, it is up
-to the program to supply one. C99 says it should be
-long double modfl(long double, long double *);
-
-=item C<d_mprotect>
-
-From F<d_mprotect.U>:
-
-This variable conditionally defines C<HAS_MPROTECT> if mprotect() is
-available to modify the access protection of a memory mapped file.
-
-=item C<d_msg>
-
-From F<d_msg.U>:
-
-This variable conditionally defines the C<HAS_MSG> symbol, which
-indicates that the entire msg*(2) library is present.
-
-=item C<d_msg_ctrunc>
-
-From F<d_socket.U>:
-
-This variable conditionally defines the C<HAS_MSG_CTRUNC> symbol,
-which indicates that the C<MSG_CTRUNC> is available. #ifdef is
-not enough because it may be an enum, glibc has been known to do this.
-
-=item C<d_msg_dontroute>
-
-From F<d_socket.U>:
-
-This variable conditionally defines the C<HAS_MSG_DONTROUTE> symbol,
-which indicates that the C<MSG_DONTROUTE> is available. #ifdef is
-not enough because it may be an enum, glibc has been known to do this.
-
-=item C<d_msg_oob>
-
-From F<d_socket.U>:
-
-This variable conditionally defines the C<HAS_MSG_OOB> symbol,
-which indicates that the C<MSG_OOB> is available. #ifdef is
-not enough because it may be an enum, glibc has been known to do this.
-
-=item C<d_msg_peek>
-
-From F<d_socket.U>:
-
-This variable conditionally defines the C<HAS_MSG_PEEK> symbol,
-which indicates that the C<MSG_PEEK> is available. #ifdef is
-not enough because it may be an enum, glibc has been known to do this.
-
-=item C<d_msg_proxy>
-
-From F<d_socket.U>:
-
-This variable conditionally defines the C<HAS_MSG_PROXY> symbol,
-which indicates that the C<MSG_PROXY> is available. #ifdef is
-not enough because it may be an enum, glibc has been known to do this.
-
-=item C<d_msgctl>
-
-From F<d_msgctl.U>:
-
-This variable conditionally defines the C<HAS_MSGCTL> symbol, which
-indicates to the C program that the msgctl() routine is available.
-
-=item C<d_msgget>
-
-From F<d_msgget.U>:
-
-This variable conditionally defines the C<HAS_MSGGET> symbol, which
-indicates to the C program that the msgget() routine is available.
-
-=item C<d_msghdr_s>
-
-From F<d_msghdr_s.U>:
-
-This variable conditionally defines the C<HAS_STRUCT_MSGHDR> symbol,
-which indicates that the struct msghdr is supported.
-
-=item C<d_msgrcv>
-
-From F<d_msgrcv.U>:
-
-This variable conditionally defines the C<HAS_MSGRCV> symbol, which
-indicates to the C program that the msgrcv() routine is available.
-
-=item C<d_msgsnd>
-
-From F<d_msgsnd.U>:
-
-This variable conditionally defines the C<HAS_MSGSND> symbol, which
-indicates to the C program that the msgsnd() routine is available.
-
-=item C<d_msync>
-
-From F<d_msync.U>:
-
-This variable conditionally defines C<HAS_MSYNC> if msync() is
-available to synchronize a mapped file.
-
-=item C<d_munmap>
-
-From F<d_munmap.U>:
-
-This variable conditionally defines C<HAS_MUNMAP> if munmap() is
-available to unmap a region mapped by mmap().
-
-=item C<d_mymalloc>
-
-From F<mallocsrc.U>:
-
-This variable conditionally defines C<MYMALLOC> in case other parts
-of the source want to take special action if C<MYMALLOC> is used.
-This may include different sorts of profiling or error detection.
-
-=item C<d_ndbm>
-
-From F<i_ndbm.U>:
-
-This variable conditionally defines the C<HAS_NDBM> symbol, which
-indicates that both the F<ndbm.h> include file and an appropriate ndbm
-library exist. Consult the different i_*ndbm variables
-to find out the actual include location. Sometimes, a system has the
-header file but not the library. This variable will only be set if
-the system has both.
-
-=item C<d_ndbm_h_uses_prototypes>
-
-From F<i_ndbm.U>:
-
-This variable conditionally defines the C<NDBM_H_USES_PROTOTYPES> symbol,
-which indicates that the F<ndbm.h> include file uses real C<ANSI> C
-prototypes instead of K&R style function declarations. K&R style
-declarations are unsupported in C++, so the include file requires
-special handling when using a C++ compiler and this variable is
-undefined. Consult the different d_*ndbm_h_uses_prototypes variables
-to get the same information for alternative F<ndbm.h> include files.
-
-=item C<d_nice>
-
-From F<d_nice.U>:
-
-This variable conditionally defines the C<HAS_NICE> symbol, which
-indicates to the C program that the nice() routine is available.
-
-=item C<d_nl_langinfo>
-
-From F<d_nl_langinfo.U>:
-
-This variable conditionally defines the C<HAS_NL_LANGINFO> symbol, which
-indicates to the C program that the nl_langinfo() routine is available.
-
-=item C<d_nv_preserves_uv>
-
-From F<perlxv.U>:
-
-This variable indicates whether a variable of type nvtype
-can preserve all the bits a variable of type uvtype.
-
-=item C<d_nv_zero_is_allbits_zero>
-
-From F<perlxv.U>:
-
-This variable indicates whether a variable of type nvtype
-stores 0.0 in memory as all bits zero.
-
-=item C<d_off64_t>
-
-From F<d_off64_t.U>:
-
-This symbol will be defined if the C compiler supports off64_t.
-
-=item C<d_old_pthread_create_joinable>
-
-From F<d_pthrattrj.U>:
-
-This variable conditionally defines pthread_create_joinable.
-undef if F<pthread.h> defines C<PTHREAD_CREATE_JOINABLE>.
-
-=item C<d_oldpthreads>
-
-From F<usethreads.U>:
-
-This variable conditionally defines the C<OLD_PTHREADS_API> symbol,
-and indicates that Perl should be built to use the old
-draft C<POSIX> threads C<API>. This is only potentially meaningful if
-usethreads is set.
-
-=item C<d_oldsock>
-
-From F<d_socket.U>:
-
-This variable conditionally defines the C<OLDSOCKET> symbol, which
-indicates that the C<BSD> socket interface is based on 4.1c and not 4.2.
-
-=item C<d_open3>
-
-From F<d_open3.U>:
-
-This variable conditionally defines the HAS_OPEN3 manifest constant,
-which indicates to the C program that the 3 argument version of
-the open(2) function is available.
-
-=item C<d_pathconf>
-
-From F<d_pathconf.U>:
-
-This variable conditionally defines the C<HAS_PATHCONF> symbol, which
-indicates to the C program that the pathconf() routine is available
-to determine file-system related limits and options associated
-with a given filename.
-
-=item C<d_pause>
-
-From F<d_pause.U>:
-
-This variable conditionally defines the C<HAS_PAUSE> symbol, which
-indicates to the C program that the pause() routine is available
-to suspend a process until a signal is received.
-
-=item C<d_perl_otherlibdirs>
-
-From F<otherlibdirs.U>:
-
-This variable conditionally defines C<PERL_OTHERLIBDIRS>, which
-contains a colon-separated set of paths for the perl binary to
-include in @C<INC>. See also otherlibdirs.
-
-=item C<d_phostname>
-
-From F<d_gethname.U>:
-
-This variable conditionally defines the C<HAS_PHOSTNAME> symbol, which
-contains the shell command which, when fed to popen(), may be
-used to derive the host name.
-
-=item C<d_pipe>
-
-From F<d_pipe.U>:
-
-This variable conditionally defines the C<HAS_PIPE> symbol, which
-indicates to the C program that the pipe() routine is available
-to create an inter-process channel.
-
-=item C<d_poll>
-
-From F<d_poll.U>:
-
-This variable conditionally defines the C<HAS_POLL> symbol, which
-indicates to the C program that the poll() routine is available
-to poll active file descriptors.
-
-=item C<d_portable>
-
-From F<d_portable.U>:
-
-This variable conditionally defines the C<PORTABLE> symbol, which
-indicates to the C program that it should not assume that it is
-running on the machine it was compiled on.
-
-=item C<d_prctl>
-
-From F<d_prctl.U>:
-
-This variable conditionally defines the C<HAS_PRCTL> symbol, which
-indicates to the C program that the prctl() routine is available.
-
-=item C<d_prctl_set_name>
-
-From F<d_prctl.U>:
-
-This variable conditionally defines the C<HAS_PRCTL_SET_NAME> symbol,
-which indicates to the C program that the prctl() routine supports
-the C<PR_SET_NAME> option.
-
-=item C<d_PRId64>
-
-From F<quadfio.U>:
-
-This variable conditionally defines the PERL_PRId64 symbol, which
-indicates that stdio has a symbol to print 64-bit decimal numbers.
-
-=item C<d_PRIeldbl>
-
-From F<longdblfio.U>:
-
-This variable conditionally defines the PERL_PRIfldbl symbol, which
-indicates that stdio has a symbol to print long doubles.
-
-=item C<d_PRIEUldbl>
-
-From F<longdblfio.U>:
-
-This variable conditionally defines the PERL_PRIfldbl symbol, which
-indicates that stdio has a symbol to print long doubles.
-The C<U> in the name is to separate this from d_PRIeldbl so that even
-case-blind systems can see the difference.
-
-=item C<d_PRIfldbl>
-
-From F<longdblfio.U>:
-
-This variable conditionally defines the PERL_PRIfldbl symbol, which
-indicates that stdio has a symbol to print long doubles.
-
-=item C<d_PRIFUldbl>
-
-From F<longdblfio.U>:
-
-This variable conditionally defines the PERL_PRIfldbl symbol, which
-indicates that stdio has a symbol to print long doubles.
-The C<U> in the name is to separate this from d_PRIfldbl so that even
-case-blind systems can see the difference.
-
-=item C<d_PRIgldbl>
-
-From F<longdblfio.U>:
-
-This variable conditionally defines the PERL_PRIfldbl symbol, which
-indicates that stdio has a symbol to print long doubles.
-
-=item C<d_PRIGUldbl>
-
-From F<longdblfio.U>:
-
-This variable conditionally defines the PERL_PRIfldbl symbol, which
-indicates that stdio has a symbol to print long doubles.
-The C<U> in the name is to separate this from d_PRIgldbl so that even
-case-blind systems can see the difference.
-
-=item C<d_PRIi64>
-
-From F<quadfio.U>:
-
-This variable conditionally defines the PERL_PRIi64 symbol, which
-indicates that stdio has a symbol to print 64-bit decimal numbers.
-
-=item C<d_printf_format_null>
-
-From F<d_attribut.U>:
-
-This variable conditionally defines C<PRINTF_FORMAT_NULL_OK>, which
-indicates the C compiler allows printf-like formats to be null.
-
-=item C<d_PRIo64>
-
-From F<quadfio.U>:
-
-This variable conditionally defines the PERL_PRIo64 symbol, which
-indicates that stdio has a symbol to print 64-bit octal numbers.
-
-=item C<d_PRIu64>
-
-From F<quadfio.U>:
-
-This variable conditionally defines the PERL_PRIu64 symbol, which
-indicates that stdio has a symbol to print 64-bit unsigned decimal
-numbers.
-
-=item C<d_PRIx64>
-
-From F<quadfio.U>:
-
-This variable conditionally defines the PERL_PRIx64 symbol, which
-indicates that stdio has a symbol to print 64-bit hexadecimal numbers.
-
-=item C<d_PRIXU64>
-
-From F<quadfio.U>:
-
-This variable conditionally defines the PERL_PRIXU64 symbol, which
-indicates that stdio has a symbol to print 64-bit hExADECimAl numbers.
-The C<U> in the name is to separate this from d_PRIx64 so that even
-case-blind systems can see the difference.
-
-=item C<d_procselfexe>
-
-From F<d_procselfexe.U>:
-
-Defined if $procselfexe is symlink to the absolute
-pathname of the executing program.
-
-=item C<d_pseudofork>
-
-From F<d_vfork.U>:
-
-This variable conditionally defines the C<HAS_PSEUDOFORK> symbol,
-which indicates that an emulation of the fork routine is available.
-
-=item C<d_pthread_atfork>
-
-From F<d_pthread_atfork.U>:
-
-This variable conditionally defines the C<HAS_PTHREAD_ATFORK> symbol,
-which indicates to the C program that the pthread_atfork()
-routine is available.
-
-=item C<d_pthread_attr_setscope>
-
-From F<d_pthread_attr_ss.U>:
-
-This variable conditionally defines C<HAS_PTHREAD_ATTR_SETSCOPE> if
-pthread_attr_setscope() is available to set the contention scope
-attribute of a thread attribute object.
-
-=item C<d_pthread_yield>
-
-From F<d_pthread_y.U>:
-
-This variable conditionally defines the C<HAS_PTHREAD_YIELD>
-symbol if the pthread_yield routine is available to yield
-the execution of the current thread.
-
-=item C<d_pwage>
-
-From F<i_pwd.U>:
-
-This variable conditionally defines C<PWAGE>, which indicates
-that struct passwd contains pw_age.
-
-=item C<d_pwchange>
-
-From F<i_pwd.U>:
-
-This variable conditionally defines C<PWCHANGE>, which indicates
-that struct passwd contains pw_change.
-
-=item C<d_pwclass>
-
-From F<i_pwd.U>:
-
-This variable conditionally defines C<PWCLASS>, which indicates
-that struct passwd contains pw_class.
-
-=item C<d_pwcomment>
-
-From F<i_pwd.U>:
-
-This variable conditionally defines C<PWCOMMENT>, which indicates
-that struct passwd contains pw_comment.
-
-=item C<d_pwexpire>
-
-From F<i_pwd.U>:
-
-This variable conditionally defines C<PWEXPIRE>, which indicates
-that struct passwd contains pw_expire.
-
-=item C<d_pwgecos>
-
-From F<i_pwd.U>:
-
-This variable conditionally defines C<PWGECOS>, which indicates
-that struct passwd contains pw_gecos.
-
-=item C<d_pwpasswd>
-
-From F<i_pwd.U>:
-
-This variable conditionally defines C<PWPASSWD>, which indicates
-that struct passwd contains pw_passwd.
-
-=item C<d_pwquota>
-
-From F<i_pwd.U>:
-
-This variable conditionally defines C<PWQUOTA>, which indicates
-that struct passwd contains pw_quota.
-
-=item C<d_qgcvt>
-
-From F<d_qgcvt.U>:
-
-This variable conditionally defines the C<HAS_QGCVT> symbol, which
-indicates to the C program that the qgcvt() routine is available.
-
-=item C<d_quad>
-
-From F<quadtype.U>:
-
-This variable, if defined, tells that there's a 64-bit integer type,
-quadtype.
-
-=item C<d_random_r>
-
-From F<d_random_r.U>:
-
-This variable conditionally defines the C<HAS_RANDOM_R> symbol,
-which indicates to the C program that the random_r()
-routine is available.
-
-=item C<d_readdir>
-
-From F<d_readdir.U>:
-
-This variable conditionally defines C<HAS_READDIR> if readdir() is
-available to read directory entries.
-
-=item C<d_readdir64_r>
-
-From F<d_readdir64_r.U>:
-
-This variable conditionally defines the HAS_READDIR64_R symbol,
-which indicates to the C program that the readdir64_r()
-routine is available.
-
-=item C<d_readdir_r>
-
-From F<d_readdir_r.U>:
-
-This variable conditionally defines the C<HAS_READDIR_R> symbol,
-which indicates to the C program that the readdir_r()
-routine is available.
-
-=item C<d_readlink>
-
-From F<d_readlink.U>:
-
-This variable conditionally defines the C<HAS_READLINK> symbol, which
-indicates to the C program that the readlink() routine is available
-to read the value of a symbolic link.
-
-=item C<d_readv>
-
-From F<d_readv.U>:
-
-This variable conditionally defines the C<HAS_READV> symbol, which
-indicates to the C program that the readv() routine is available.
-
-=item C<d_recvmsg>
-
-From F<d_recvmsg.U>:
-
-This variable conditionally defines the C<HAS_RECVMSG> symbol, which
-indicates to the C program that the recvmsg() routine is available.
-
-=item C<d_rename>
-
-From F<d_rename.U>:
-
-This variable conditionally defines the C<HAS_RENAME> symbol, which
-indicates to the C program that the rename() routine is available
-to rename files.
-
-=item C<d_rewinddir>
-
-From F<d_readdir.U>:
-
-This variable conditionally defines C<HAS_REWINDDIR> if rewinddir() is
-available.
-
-=item C<d_rmdir>
-
-From F<d_rmdir.U>:
-
-This variable conditionally defines C<HAS_RMDIR> if rmdir() is
-available to remove directories.
-
-=item C<d_safebcpy>
-
-From F<d_safebcpy.U>:
-
-This variable conditionally defines the C<HAS_SAFE_BCOPY> symbol if
-the bcopy() routine can do overlapping copies. Normally, you
-should probably use memmove().
-
-=item C<d_safemcpy>
-
-From F<d_safemcpy.U>:
-
-This variable conditionally defines the C<HAS_SAFE_MEMCPY> symbol if
-the memcpy() routine can do overlapping copies.
-For overlapping copies, memmove() should be used, if available.
-
-=item C<d_sanemcmp>
-
-From F<d_sanemcmp.U>:
-
-This variable conditionally defines the C<HAS_SANE_MEMCMP> symbol if
-the memcpy() routine is available and can be used to compare relative
-magnitudes of chars with their high bits set.
-
-=item C<d_sbrkproto>
-
-From F<d_sbrkproto.U>:
-
-This variable conditionally defines the C<HAS_SBRK_PROTO> symbol,
-which indicates to the C program that the system provides
-a prototype for the sbrk() function. Otherwise, it is
-up to the program to supply one.
-
-=item C<d_scalbnl>
-
-From F<d_scalbnl.U>:
-
-This variable conditionally defines the C<HAS_SCALBNL> symbol, which
-indicates to the C program that the scalbnl() routine is available.
-If ilogbl is also present we can emulate frexpl.
-
-=item C<d_sched_yield>
-
-From F<d_pthread_y.U>:
-
-This variable conditionally defines the C<HAS_SCHED_YIELD>
-symbol if the sched_yield routine is available to yield
-the execution of the current thread.
-
-=item C<d_scm_rights>
-
-From F<d_socket.U>:
-
-This variable conditionally defines the C<HAS_SCM_RIGHTS> symbol,
-which indicates that the C<SCM_RIGHTS> is available. #ifdef is
-not enough because it may be an enum, glibc has been known to do this.
-
-=item C<d_SCNfldbl>
-
-From F<longdblfio.U>:
-
-This variable conditionally defines the PERL_PRIfldbl symbol, which
-indicates that stdio has a symbol to scan long doubles.
-
-=item C<d_seekdir>
-
-From F<d_readdir.U>:
-
-This variable conditionally defines C<HAS_SEEKDIR> if seekdir() is
-available.
-
-=item C<d_select>
-
-From F<d_select.U>:
-
-This variable conditionally defines C<HAS_SELECT> if select() is
-available to select active file descriptors. A <sys/time.h>
-inclusion may be necessary for the timeout field.
-
-=item C<d_sem>
-
-From F<d_sem.U>:
-
-This variable conditionally defines the C<HAS_SEM> symbol, which
-indicates that the entire sem*(2) library is present.
-
-=item C<d_semctl>
-
-From F<d_semctl.U>:
-
-This variable conditionally defines the C<HAS_SEMCTL> symbol, which
-indicates to the C program that the semctl() routine is available.
-
-=item C<d_semctl_semid_ds>
-
-From F<d_union_semun.U>:
-
-This variable conditionally defines C<USE_SEMCTL_SEMID_DS>, which
-indicates that struct semid_ds * is to be used for semctl C<IPC_STAT>.
-
-=item C<d_semctl_semun>
-
-From F<d_union_semun.U>:
-
-This variable conditionally defines C<USE_SEMCTL_SEMUN>, which
-indicates that union semun is to be used for semctl C<IPC_STAT>.
-
-=item C<d_semget>
-
-From F<d_semget.U>:
-
-This variable conditionally defines the C<HAS_SEMGET> symbol, which
-indicates to the C program that the semget() routine is available.
-
-=item C<d_semop>
-
-From F<d_semop.U>:
-
-This variable conditionally defines the C<HAS_SEMOP> symbol, which
-indicates to the C program that the semop() routine is available.
-
-=item C<d_sendmsg>
-
-From F<d_sendmsg.U>:
-
-This variable conditionally defines the C<HAS_SENDMSG> symbol, which
-indicates to the C program that the sendmsg() routine is available.
-
-=item C<d_setegid>
-
-From F<d_setegid.U>:
-
-This variable conditionally defines the C<HAS_SETEGID> symbol, which
-indicates to the C program that the setegid() routine is available
-to change the effective gid of the current program.
-
-=item C<d_seteuid>
-
-From F<d_seteuid.U>:
-
-This variable conditionally defines the C<HAS_SETEUID> symbol, which
-indicates to the C program that the seteuid() routine is available
-to change the effective uid of the current program.
-
-=item C<d_setgrent>
-
-From F<d_setgrent.U>:
-
-This variable conditionally defines the C<HAS_SETGRENT> symbol, which
-indicates to the C program that the setgrent() routine is available
-for initializing sequential access to the group database.
-
-=item C<d_setgrent_r>
-
-From F<d_setgrent_r.U>:
-
-This variable conditionally defines the C<HAS_SETGRENT_R> symbol,
-which indicates to the C program that the setgrent_r()
-routine is available.
-
-=item C<d_setgrps>
-
-From F<d_setgrps.U>:
-
-This variable conditionally defines the C<HAS_SETGROUPS> symbol, which
-indicates to the C program that the setgroups() routine is available
-to set the list of process groups.
-
-=item C<d_sethent>
-
-From F<d_sethent.U>:
-
-This variable conditionally defines C<HAS_SETHOSTENT> if sethostent() is
-available.
-
-=item C<d_sethostent_r>
-
-From F<d_sethostent_r.U>:
-
-This variable conditionally defines the C<HAS_SETHOSTENT_R> symbol,
-which indicates to the C program that the sethostent_r()
-routine is available.
-
-=item C<d_setitimer>
-
-From F<d_setitimer.U>:
-
-This variable conditionally defines the C<HAS_SETITIMER> symbol, which
-indicates to the C program that the setitimer() routine is available.
-
-=item C<d_setlinebuf>
-
-From F<d_setlnbuf.U>:
-
-This variable conditionally defines the C<HAS_SETLINEBUF> symbol, which
-indicates to the C program that the setlinebuf() routine is available
-to change stderr or stdout from block-buffered or unbuffered to a
-line-buffered mode.
-
-=item C<d_setlocale>
-
-From F<d_setlocale.U>:
-
-This variable conditionally defines C<HAS_SETLOCALE> if setlocale() is
-available to handle locale-specific ctype implementations.
-
-=item C<d_setlocale_r>
-
-From F<d_setlocale_r.U>:
-
-This variable conditionally defines the C<HAS_SETLOCALE_R> symbol,
-which indicates to the C program that the setlocale_r()
-routine is available.
-
-=item C<d_setnent>
-
-From F<d_setnent.U>:
-
-This variable conditionally defines C<HAS_SETNETENT> if setnetent() is
-available.
-
-=item C<d_setnetent_r>
-
-From F<d_setnetent_r.U>:
-
-This variable conditionally defines the C<HAS_SETNETENT_R> symbol,
-which indicates to the C program that the setnetent_r()
-routine is available.
-
-=item C<d_setpent>
-
-From F<d_setpent.U>:
-
-This variable conditionally defines C<HAS_SETPROTOENT> if setprotoent() is
-available.
-
-=item C<d_setpgid>
-
-From F<d_setpgid.U>:
-
-This variable conditionally defines the C<HAS_SETPGID> symbol if the
-setpgid(pid, gpid) function is available to set process group C<ID>.
-
-=item C<d_setpgrp>
-
-From F<d_setpgrp.U>:
-
-This variable conditionally defines C<HAS_SETPGRP> if setpgrp() is
-available to set the current process group.
-
-=item C<d_setpgrp2>
-
-From F<d_setpgrp2.U>:
-
-This variable conditionally defines the HAS_SETPGRP2 symbol, which
-indicates to the C program that the setpgrp2() (as in F<DG/C<UX>>) routine
-is available to set the current process group.
-
-=item C<d_setprior>
-
-From F<d_setprior.U>:
-
-This variable conditionally defines C<HAS_SETPRIORITY> if setpriority()
-is available to set a process's priority.
-
-=item C<d_setproctitle>
-
-From F<d_setproctitle.U>:
-
-This variable conditionally defines the C<HAS_SETPROCTITLE> symbol,
-which indicates to the C program that the setproctitle() routine
-is available.
-
-=item C<d_setprotoent_r>
-
-From F<d_setprotoent_r.U>:
-
-This variable conditionally defines the C<HAS_SETPROTOENT_R> symbol,
-which indicates to the C program that the setprotoent_r()
-routine is available.
-
-=item C<d_setpwent>
-
-From F<d_setpwent.U>:
-
-This variable conditionally defines the C<HAS_SETPWENT> symbol, which
-indicates to the C program that the setpwent() routine is available
-for initializing sequential access to the passwd database.
-
-=item C<d_setpwent_r>
-
-From F<d_setpwent_r.U>:
-
-This variable conditionally defines the C<HAS_SETPWENT_R> symbol,
-which indicates to the C program that the setpwent_r()
-routine is available.
-
-=item C<d_setregid>
-
-From F<d_setregid.U>:
-
-This variable conditionally defines C<HAS_SETREGID> if setregid() is
-available to change the real and effective gid of the current
-process.
-
-=item C<d_setresgid>
-
-From F<d_setregid.U>:
-
-This variable conditionally defines C<HAS_SETRESGID> if setresgid() is
-available to change the real, effective and saved gid of the current
-process.
-
-=item C<d_setresuid>
-
-From F<d_setreuid.U>:
-
-This variable conditionally defines C<HAS_SETREUID> if setresuid() is
-available to change the real, effective and saved uid of the current
-process.
-
-=item C<d_setreuid>
-
-From F<d_setreuid.U>:
-
-This variable conditionally defines C<HAS_SETREUID> if setreuid() is
-available to change the real and effective uid of the current
-process.
-
-=item C<d_setrgid>
-
-From F<d_setrgid.U>:
-
-This variable conditionally defines the C<HAS_SETRGID> symbol, which
-indicates to the C program that the setrgid() routine is available
-to change the real gid of the current program.
-
-=item C<d_setruid>
-
-From F<d_setruid.U>:
-
-This variable conditionally defines the C<HAS_SETRUID> symbol, which
-indicates to the C program that the setruid() routine is available
-to change the real uid of the current program.
-
-=item C<d_setsent>
-
-From F<d_setsent.U>:
-
-This variable conditionally defines C<HAS_SETSERVENT> if setservent() is
-available.
-
-=item C<d_setservent_r>
-
-From F<d_setservent_r.U>:
-
-This variable conditionally defines the C<HAS_SETSERVENT_R> symbol,
-which indicates to the C program that the setservent_r()
-routine is available.
-
-=item C<d_setsid>
-
-From F<d_setsid.U>:
-
-This variable conditionally defines C<HAS_SETSID> if setsid() is
-available to set the process group C<ID>.
-
-=item C<d_setvbuf>
-
-From F<d_setvbuf.U>:
-
-This variable conditionally defines the C<HAS_SETVBUF> symbol, which
-indicates to the C program that the setvbuf() routine is available
-to change buffering on an open stdio stream.
-
-=item C<d_sfio>
-
-From F<d_sfio.U>:
-
-This variable conditionally defines the C<USE_SFIO> symbol,
-and indicates whether sfio is available (and should be used).
-
-=item C<d_shm>
-
-From F<d_shm.U>:
-
-This variable conditionally defines the C<HAS_SHM> symbol, which
-indicates that the entire shm*(2) library is present.
-
-=item C<d_shmat>
-
-From F<d_shmat.U>:
-
-This variable conditionally defines the C<HAS_SHMAT> symbol, which
-indicates to the C program that the shmat() routine is available.
-
-=item C<d_shmatprototype>
-
-From F<d_shmat.U>:
-
-This variable conditionally defines the C<HAS_SHMAT_PROTOTYPE>
-symbol, which indicates that F<sys/shm.h> has a prototype for
-shmat.
-
-=item C<d_shmctl>
-
-From F<d_shmctl.U>:
-
-This variable conditionally defines the C<HAS_SHMCTL> symbol, which
-indicates to the C program that the shmctl() routine is available.
-
-=item C<d_shmdt>
-
-From F<d_shmdt.U>:
-
-This variable conditionally defines the C<HAS_SHMDT> symbol, which
-indicates to the C program that the shmdt() routine is available.
-
-=item C<d_shmget>
-
-From F<d_shmget.U>:
-
-This variable conditionally defines the C<HAS_SHMGET> symbol, which
-indicates to the C program that the shmget() routine is available.
-
-=item C<d_sigaction>
-
-From F<d_sigaction.U>:
-
-This variable conditionally defines the C<HAS_SIGACTION> symbol, which
-indicates that the Vr4 sigaction() routine is available.
-
-=item C<d_signbit>
-
-From F<d_signbit.U>:
-
-This variable conditionally defines the C<HAS_SIGNBIT> symbol, which
-indicates to the C program that the signbit() routine is available
-and safe to use with perl's intern C<NV> type.
-
-=item C<d_sigprocmask>
-
-From F<d_sigprocmask.U>:
-
-This variable conditionally defines C<HAS_SIGPROCMASK>
-if sigprocmask() is available to examine or change the signal mask
-of the calling process.
-
-=item C<d_sigsetjmp>
-
-From F<d_sigsetjmp.U>:
-
-This variable conditionally defines the C<HAS_SIGSETJMP> symbol,
-which indicates that the sigsetjmp() routine is available to
-call setjmp() and optionally save the process's signal mask.
-
-=item C<d_sin6_scope_id>
-
-From F<d_socket.U>:
-
-This variable conditionally defines the HAS_SIN6_SCOPE_ID symbol, which
-indicates that a struct sockaddr_in6 structure has the sin6_scope_id
-member.
-
-=item C<d_sitearch>
-
-From F<sitearch.U>:
-
-This variable conditionally defines C<SITEARCH> to hold the pathname
-of architecture-dependent library files for $package. If
-$sitearch is the same as $archlib, then this is set to undef.
-
-=item C<d_snprintf>
-
-From F<d_snprintf.U>:
-
-This variable conditionally defines the C<HAS_SNPRINTF> symbol, which
-indicates to the C program that the snprintf () library function
-is available.
-
-=item C<d_sockaddr_in6>
-
-From F<d_socket.U>:
-
-This variable conditionally defines the HAS_SOCKADDR_IN6 symbol, which
-indicates the availability of a struct sockaddr_in6.
-
-=item C<d_sockaddr_sa_len>
-
-From F<d_socket.U>:
-
-This variable conditionally defines the C<HAS_SOCKADDR_SA_LEN> symbol,
-which indicates that a struct sockaddr structure has the sa_len
-member.
-
-=item C<d_sockatmark>
-
-From F<d_sockatmark.U>:
-
-This variable conditionally defines the C<HAS_SOCKATMARK> symbol, which
-indicates to the C program that the sockatmark() routine is available.
-
-=item C<d_sockatmarkproto>
-
-From F<d_sockatmarkproto.U>:
-
-This variable conditionally defines the C<HAS_SOCKATMARK_PROTO> symbol,
-which indicates to the C program that the system provides
-a prototype for the sockatmark() function. Otherwise, it is
-up to the program to supply one.
-
-=item C<d_socket>
-
-From F<d_socket.U>:
-
-This variable conditionally defines C<HAS_SOCKET>, which indicates
-that the C<BSD> socket interface is supported.
-
-=item C<d_socklen_t>
-
-From F<d_socklen_t.U>:
-
-This symbol will be defined if the C compiler supports socklen_t.
-
-=item C<d_sockpair>
-
-From F<d_socket.U>:
-
-This variable conditionally defines the C<HAS_SOCKETPAIR> symbol, which
-indicates that the C<BSD> socketpair() is supported.
-
-=item C<d_socks5_init>
-
-From F<d_socks5_init.U>:
-
-This variable conditionally defines the HAS_SOCKS5_INIT symbol, which
-indicates to the C program that the socks5_init() routine is available.
-
-=item C<d_sprintf_returns_strlen>
-
-From F<d_sprintf_len.U>:
-
-This variable defines whether sprintf returns the length of the string
-(as per the C<ANSI> spec). Some C libraries retain compatibility with
-pre-C<ANSI> C and return a pointer to the passed in buffer; for these
-this variable will be undef.
-
-=item C<d_sqrtl>
-
-From F<d_sqrtl.U>:
-
-This variable conditionally defines the C<HAS_SQRTL> symbol, which
-indicates to the C program that the sqrtl() routine is available.
-
-=item C<d_srand48_r>
-
-From F<d_srand48_r.U>:
-
-This variable conditionally defines the HAS_SRAND48_R symbol,
-which indicates to the C program that the srand48_r()
-routine is available.
-
-=item C<d_srandom_r>
-
-From F<d_srandom_r.U>:
-
-This variable conditionally defines the C<HAS_SRANDOM_R> symbol,
-which indicates to the C program that the srandom_r()
-routine is available.
-
-=item C<d_sresgproto>
-
-From F<d_sresgproto.U>:
-
-This variable conditionally defines the C<HAS_SETRESGID_PROTO> symbol,
-which indicates to the C program that the system provides
-a prototype for the setresgid() function. Otherwise, it is
-up to the program to supply one.
-
-=item C<d_sresuproto>
-
-From F<d_sresuproto.U>:
-
-This variable conditionally defines the C<HAS_SETRESUID_PROTO> symbol,
-which indicates to the C program that the system provides
-a prototype for the setresuid() function. Otherwise, it is
-up to the program to supply one.
-
-=item C<d_statblks>
-
-From F<d_statblks.U>:
-
-This variable conditionally defines C<USE_STAT_BLOCKS>
-if this system has a stat structure declaring
-st_blksize and st_blocks.
-
-=item C<d_statfs_f_flags>
-
-From F<d_statfs_f_flags.U>:
-
-This variable conditionally defines the C<HAS_STRUCT_STATFS_F_FLAGS>
-symbol, which indicates to struct statfs from has f_flags member.
-This kind of struct statfs is coming from F<sys/mount.h> (C<BSD>),
-not from F<sys/statfs.h> (C<SYSV>).
-
-=item C<d_statfs_s>
-
-From F<d_statfs_s.U>:
-
-This variable conditionally defines the C<HAS_STRUCT_STATFS> symbol,
-which indicates that the struct statfs is supported.
-
-=item C<d_static_inline>
-
-From F<d_static_inline.U>:
-
-This variable conditionally defines the C<HAS_STATIC_INLINE> symbol,
-which indicates that the C compiler supports C99-style static
-inline. That is, the function can't be called from another
-translation unit.
-
-=item C<d_statvfs>
-
-From F<d_statvfs.U>:
-
-This variable conditionally defines the C<HAS_STATVFS> symbol, which
-indicates to the C program that the statvfs() routine is available.
-
-=item C<d_stdio_cnt_lval>
-
-From F<d_stdstdio.U>:
-
-This variable conditionally defines C<STDIO_CNT_LVALUE> if the
-C<FILE_cnt> macro can be used as an lvalue.
-
-=item C<d_stdio_ptr_lval>
-
-From F<d_stdstdio.U>:
-
-This variable conditionally defines C<STDIO_PTR_LVALUE> if the
-C<FILE_ptr> macro can be used as an lvalue.
-
-=item C<d_stdio_ptr_lval_nochange_cnt>
-
-From F<d_stdstdio.U>:
-
-This symbol is defined if using the C<FILE_ptr> macro as an lvalue
-to increase the pointer by n leaves File_cnt(fp) unchanged.
-
-=item C<d_stdio_ptr_lval_sets_cnt>
-
-From F<d_stdstdio.U>:
-
-This symbol is defined if using the C<FILE_ptr> macro as an lvalue
-to increase the pointer by n has the side effect of decreasing the
-value of File_cnt(fp) by n.
-
-=item C<d_stdio_stream_array>
-
-From F<stdio_streams.U>:
-
-This variable tells whether there is an array holding
-the stdio streams.
-
-=item C<d_stdiobase>
-
-From F<d_stdstdio.U>:
-
-This variable conditionally defines C<USE_STDIO_BASE> if this system
-has a C<FILE> structure declaring a usable _base field (or equivalent)
-in F<stdio.h>.
-
-=item C<d_stdstdio>
-
-From F<d_stdstdio.U>:
-
-This variable conditionally defines C<USE_STDIO_PTR> if this system
-has a C<FILE> structure declaring usable _ptr and _cnt fields (or
-equivalent) in F<stdio.h>.
-
-=item C<d_strchr>
-
-From F<d_strchr.U>:
-
-This variable conditionally defines C<HAS_STRCHR> if strchr() and
-strrchr() are available for string searching.
-
-=item C<d_strcoll>
-
-From F<d_strcoll.U>:
-
-This variable conditionally defines C<HAS_STRCOLL> if strcoll() is
-available to compare strings using collating information.
-
-=item C<d_strctcpy>
-
-From F<d_strctcpy.U>:
-
-This variable conditionally defines the C<USE_STRUCT_COPY> symbol, which
-indicates to the C program that this C compiler knows how to copy
-structures.
-
-=item C<d_strerrm>
-
-From F<d_strerror.U>:
-
-This variable holds what Strerrr is defined as to translate an error
-code condition into an error message string. It could be C<strerror>
-or a more C<complex> macro emulating strrror with sys_errlist[], or the
-C<unknown> string when both strerror and sys_errlist are missing.
-
-=item C<d_strerror>
-
-From F<d_strerror.U>:
-
-This variable conditionally defines C<HAS_STRERROR> if strerror() is
-available to translate error numbers to strings.
-
-=item C<d_strerror_r>
-
-From F<d_strerror_r.U>:
-
-This variable conditionally defines the C<HAS_STRERROR_R> symbol,
-which indicates to the C program that the strerror_r()
-routine is available.
-
-=item C<d_strftime>
-
-From F<d_strftime.U>:
-
-This variable conditionally defines the C<HAS_STRFTIME> symbol, which
-indicates to the C program that the strftime() routine is available.
-
-=item C<d_strlcat>
-
-From F<d_strlcat.U>:
-
-This variable conditionally defines the C<HAS_STRLCAT> symbol, which
-indicates to the C program that the strlcat () routine is available.
-
-=item C<d_strlcpy>
-
-From F<d_strlcpy.U>:
-
-This variable conditionally defines the C<HAS_STRLCPY> symbol, which
-indicates to the C program that the strlcpy () routine is available.
-
-=item C<d_strtod>
-
-From F<d_strtod.U>:
-
-This variable conditionally defines the C<HAS_STRTOD> symbol, which
-indicates to the C program that the strtod() routine is available
-to provide better numeric string conversion than atof().
-
-=item C<d_strtol>
-
-From F<d_strtol.U>:
-
-This variable conditionally defines the C<HAS_STRTOL> symbol, which
-indicates to the C program that the strtol() routine is available
-to provide better numeric string conversion than atoi() and friends.
-
-=item C<d_strtold>
-
-From F<d_strtold.U>:
-
-This variable conditionally defines the C<HAS_STRTOLD> symbol, which
-indicates to the C program that the strtold() routine is available.
-
-=item C<d_strtoll>
-
-From F<d_strtoll.U>:
-
-This variable conditionally defines the C<HAS_STRTOLL> symbol, which
-indicates to the C program that the strtoll() routine is available.
-
-=item C<d_strtoq>
-
-From F<d_strtoq.U>:
-
-This variable conditionally defines the C<HAS_STRTOQ> symbol, which
-indicates to the C program that the strtoq() routine is available.
-
-=item C<d_strtoul>
-
-From F<d_strtoul.U>:
-
-This variable conditionally defines the C<HAS_STRTOUL> symbol, which
-indicates to the C program that the strtoul() routine is available
-to provide conversion of strings to unsigned long.
-
-=item C<d_strtoull>
-
-From F<d_strtoull.U>:
-
-This variable conditionally defines the C<HAS_STRTOULL> symbol, which
-indicates to the C program that the strtoull() routine is available.
-
-=item C<d_strtouq>
-
-From F<d_strtouq.U>:
-
-This variable conditionally defines the C<HAS_STRTOUQ> symbol, which
-indicates to the C program that the strtouq() routine is available.
-
-=item C<d_strxfrm>
-
-From F<d_strxfrm.U>:
-
-This variable conditionally defines C<HAS_STRXFRM> if strxfrm() is
-available to transform strings.
-
-=item C<d_suidsafe>
-
-From F<d_dosuid.U>:
-
-This variable conditionally defines C<SETUID_SCRIPTS_ARE_SECURE_NOW>
-if setuid scripts can be secure. This test looks in F</dev/fd/>.
-
-=item C<d_symlink>
-
-From F<d_symlink.U>:
-
-This variable conditionally defines the C<HAS_SYMLINK> symbol, which
-indicates to the C program that the symlink() routine is available
-to create symbolic links.
-
-=item C<d_syscall>
-
-From F<d_syscall.U>:
-
-This variable conditionally defines C<HAS_SYSCALL> if syscall() is
-available call arbitrary system calls.
-
-=item C<d_syscallproto>
-
-From F<d_syscallproto.U>:
-
-This variable conditionally defines the C<HAS_SYSCALL_PROTO> symbol,
-which indicates to the C program that the system provides
-a prototype for the syscall() function. Otherwise, it is
-up to the program to supply one.
-
-=item C<d_sysconf>
-
-From F<d_sysconf.U>:
-
-This variable conditionally defines the C<HAS_SYSCONF> symbol, which
-indicates to the C program that the sysconf() routine is available
-to determine system related limits and options.
-
-=item C<d_sysernlst>
-
-From F<d_strerror.U>:
-
-This variable conditionally defines C<HAS_SYS_ERRNOLIST> if sys_errnolist[]
-is available to translate error numbers to the symbolic name.
-
-=item C<d_syserrlst>
-
-From F<d_strerror.U>:
-
-This variable conditionally defines C<HAS_SYS_ERRLIST> if sys_errlist[] is
-available to translate error numbers to strings.
-
-=item C<d_system>
-
-From F<d_system.U>:
-
-This variable conditionally defines C<HAS_SYSTEM> if system() is
-available to issue a shell command.
-
-=item C<d_tcgetpgrp>
-
-From F<d_tcgtpgrp.U>:
-
-This variable conditionally defines the C<HAS_TCGETPGRP> symbol, which
-indicates to the C program that the tcgetpgrp() routine is available.
-to get foreground process group C<ID>.
-
-=item C<d_tcsetpgrp>
-
-From F<d_tcstpgrp.U>:
-
-This variable conditionally defines the C<HAS_TCSETPGRP> symbol, which
-indicates to the C program that the tcsetpgrp() routine is available
-to set foreground process group C<ID>.
-
-=item C<d_telldir>
-
-From F<d_readdir.U>:
-
-This variable conditionally defines C<HAS_TELLDIR> if telldir() is
-available.
-
-=item C<d_telldirproto>
-
-From F<d_telldirproto.U>:
-
-This variable conditionally defines the C<HAS_TELLDIR_PROTO> symbol,
-which indicates to the C program that the system provides
-a prototype for the telldir() function. Otherwise, it is
-up to the program to supply one.
-
-=item C<d_time>
-
-From F<d_time.U>:
-
-This variable conditionally defines the C<HAS_TIME> symbol, which indicates
-that the time() routine exists. The time() routine is normally
-provided on C<UNIX> systems.
-
-=item C<d_timegm>
-
-From F<d_timegm.U>:
-
-This variable conditionally defines the C<HAS_TIMEGM> symbol, which
-indicates to the C program that the timegm () routine is available.
-
-=item C<d_times>
-
-From F<d_times.U>:
-
-This variable conditionally defines the C<HAS_TIMES> symbol, which indicates
-that the times() routine exists. The times() routine is normally
-provided on C<UNIX> systems. You may have to include <sys/times.h>.
-
-=item C<d_tm_tm_gmtoff>
-
-From F<i_time.U>:
-
-This variable conditionally defines C<HAS_TM_TM_GMTOFF>, which indicates
-indicates to the C program that the struct tm has the tm_gmtoff field.
-
-=item C<d_tm_tm_zone>
-
-From F<i_time.U>:
-
-This variable conditionally defines C<HAS_TM_TM_ZONE>, which indicates
-indicates to the C program that the struct tm has the tm_zone field.
-
-=item C<d_tmpnam_r>
-
-From F<d_tmpnam_r.U>:
-
-This variable conditionally defines the C<HAS_TMPNAM_R> symbol,
-which indicates to the C program that the tmpnam_r()
-routine is available.
-
-=item C<d_truncate>
-
-From F<d_truncate.U>:
-
-This variable conditionally defines C<HAS_TRUNCATE> if truncate() is
-available to truncate files.
-
-=item C<d_ttyname_r>
-
-From F<d_ttyname_r.U>:
-
-This variable conditionally defines the C<HAS_TTYNAME_R> symbol,
-which indicates to the C program that the ttyname_r()
-routine is available.
-
-=item C<d_tzname>
-
-From F<d_tzname.U>:
-
-This variable conditionally defines C<HAS_TZNAME> if tzname[] is
-available to access timezone names.
-
-=item C<d_u32align>
-
-From F<d_u32align.U>:
-
-This variable tells whether you must access character data
-through U32-aligned pointers.
-
-=item C<d_ualarm>
-
-From F<d_ualarm.U>:
-
-This variable conditionally defines the C<HAS_UALARM> symbol, which
-indicates to the C program that the ualarm() routine is available.
-
-=item C<d_umask>
-
-From F<d_umask.U>:
-
-This variable conditionally defines the C<HAS_UMASK> symbol, which
-indicates to the C program that the umask() routine is available.
-to set and get the value of the file creation mask.
-
-=item C<d_uname>
-
-From F<d_gethname.U>:
-
-This variable conditionally defines the C<HAS_UNAME> symbol, which
-indicates to the C program that the uname() routine may be
-used to derive the host name.
-
-=item C<d_union_semun>
-
-From F<d_union_semun.U>:
-
-This variable conditionally defines C<HAS_UNION_SEMUN> if the
-union semun is defined by including <sys/sem.h>.
-
-=item C<d_unordered>
-
-From F<d_unordered.U>:
-
-This variable conditionally defines the C<HAS_UNORDERED> symbol, which
-indicates to the C program that the unordered() routine is available.
-
-=item C<d_unsetenv>
-
-From F<d_unsetenv.U>:
-
-This variable conditionally defines the C<HAS_UNSETENV> symbol, which
-indicates to the C program that the unsetenv () routine is available.
-
-=item C<d_usleep>
-
-From F<d_usleep.U>:
-
-This variable conditionally defines C<HAS_USLEEP> if usleep() is
-available to do high granularity sleeps.
-
-=item C<d_usleepproto>
-
-From F<d_usleepproto.U>:
-
-This variable conditionally defines the C<HAS_USLEEP_PROTO> symbol,
-which indicates to the C program that the system provides
-a prototype for the usleep() function. Otherwise, it is
-up to the program to supply one.
-
-=item C<d_ustat>
-
-From F<d_ustat.U>:
-
-This variable conditionally defines C<HAS_USTAT> if ustat() is
-available to query file system statistics by dev_t.
-
-=item C<d_vendorarch>
-
-From F<vendorarch.U>:
-
-This variable conditionally defined C<PERL_VENDORARCH>.
-
-=item C<d_vendorbin>
-
-From F<vendorbin.U>:
-
-This variable conditionally defines C<PERL_VENDORBIN>.
-
-=item C<d_vendorlib>
-
-From F<vendorlib.U>:
-
-This variable conditionally defines C<PERL_VENDORLIB>.
-
-=item C<d_vendorscript>
-
-From F<vendorscript.U>:
-
-This variable conditionally defines C<PERL_VENDORSCRIPT>.
-
-=item C<d_vfork>
-
-From F<d_vfork.U>:
-
-This variable conditionally defines the C<HAS_VFORK> symbol, which
-indicates the vfork() routine is available.
-
-=item C<d_void_closedir>
-
-From F<d_closedir.U>:
-
-This variable conditionally defines C<VOID_CLOSEDIR> if closedir()
-does not return a value.
-
-=item C<d_voidsig>
-
-From F<d_voidsig.U>:
-
-This variable conditionally defines C<VOIDSIG> if this system
-declares "void (*signal(...))()" in F<signal.h>. The old way was to
-declare it as "int (*signal(...))()".
-
-=item C<d_voidtty>
-
-From F<i_sysioctl.U>:
-
-This variable conditionally defines C<USE_IOCNOTTY> to indicate that the
-ioctl() call with C<TIOCNOTTY> should be used to void tty association.
-Otherwise (on C<USG> probably), it is enough to close the standard file
-descriptors and do a setpgrp().
-
-=item C<d_volatile>
-
-From F<d_volatile.U>:
-
-This variable conditionally defines the C<HASVOLATILE> symbol, which
-indicates to the C program that this C compiler knows about the
-volatile declaration.
-
-=item C<d_vprintf>
-
-From F<d_vprintf.U>:
-
-This variable conditionally defines the C<HAS_VPRINTF> symbol, which
-indicates to the C program that the vprintf() routine is available
-to printf with a pointer to an argument list.
-
-=item C<d_vsnprintf>
-
-From F<d_snprintf.U>:
-
-This variable conditionally defines the C<HAS_VSNPRINTF> symbol, which
-indicates to the C program that the vsnprintf () library function
-is available.
-
-=item C<d_wait4>
-
-From F<d_wait4.U>:
-
-This variable conditionally defines the HAS_WAIT4 symbol, which
-indicates the wait4() routine is available.
-
-=item C<d_waitpid>
-
-From F<d_waitpid.U>:
-
-This variable conditionally defines C<HAS_WAITPID> if waitpid() is
-available to wait for child process.
-
-=item C<d_wcstombs>
-
-From F<d_wcstombs.U>:
-
-This variable conditionally defines the C<HAS_WCSTOMBS> symbol, which
-indicates to the C program that the wcstombs() routine is available
-to convert wide character strings to multibyte strings.
-
-=item C<d_wctomb>
-
-From F<d_wctomb.U>:
-
-This variable conditionally defines the C<HAS_WCTOMB> symbol, which
-indicates to the C program that the wctomb() routine is available
-to convert a wide character to a multibyte.
-
-=item C<d_writev>
-
-From F<d_writev.U>:
-
-This variable conditionally defines the C<HAS_WRITEV> symbol, which
-indicates to the C program that the writev() routine is available.
-
-=item C<d_xenix>
-
-From F<Guess.U>:
-
-This variable conditionally defines the symbol C<XENIX>, which alerts
-the C program that it runs under Xenix.
-
-=item C<date>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the date program. After Configure runs,
-the value is reset to a plain C<date> and is not useful.
-
-=item C<db_hashtype>
-
-From F<i_db.U>:
-
-This variable contains the type of the hash structure element
-in the <db.h> header file. In older versions of C<DB>, it was
-int, while in newer ones it is u_int32_t.
-
-=item C<db_prefixtype>
-
-From F<i_db.U>:
-
-This variable contains the type of the prefix structure element
-in the <db.h> header file. In older versions of C<DB>, it was
-int, while in newer ones it is size_t.
-
-=item C<db_version_major>
-
-From F<i_db.U>:
-
-This variable contains the major version number of
-Berkeley C<DB> found in the <db.h> header file.
-
-=item C<db_version_minor>
-
-From F<i_db.U>:
-
-This variable contains the minor version number of
-Berkeley C<DB> found in the <db.h> header file.
-For C<DB> version 1 this is always 0.
-
-=item C<db_version_patch>
-
-From F<i_db.U>:
-
-This variable contains the patch version number of
-Berkeley C<DB> found in the <db.h> header file.
-For C<DB> version 1 this is always 0.
-
-=item C<defvoidused>
-
-From F<voidflags.U>:
-
-This variable contains the default value of the C<VOIDUSED> symbol (15).
-
-=item C<direntrytype>
-
-From F<i_dirent.U>:
-
-This symbol is set to C<struct direct> or C<struct dirent> depending on
-whether dirent is available or not. You should use this pseudo type to
-portably declare your directory entries.
-
-=item C<dlext>
-
-From F<dlext.U>:
-
-This variable contains the extension that is to be used for the
-dynamically loaded modules that perl generaties.
-
-=item C<dlsrc>
-
-From F<dlsrc.U>:
-
-This variable contains the name of the dynamic loading file that
-will be used with the package.
-
-=item C<doublesize>
-
-From F<doublesize.U>:
-
-This variable contains the value of the C<DOUBLESIZE> symbol, which
-indicates to the C program how many bytes there are in a double.
-
-=item C<drand01>
-
-From F<randfunc.U>:
-
-Indicates the macro to be used to generate normalized
-random numbers. Uses randfunc, often divided by
-(double) (((unsigned long) 1 << randbits)) in order to
-normalize the result.
-In C programs, the macro C<Drand01> is mapped to drand01.
-
-=item C<drand48_r_proto>
-
-From F<d_drand48_r.U>:
-
-This variable encodes the prototype of drand48_r.
-It is zero if d_drand48_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_drand48_r
-is defined.
-
-=item C<dtrace>
-
-From F<usedtrace.U>:
-
-This variable holds the location of the dtrace executable.
-
-=item C<dynamic_ext>
-
-From F<Extensions.U>:
-
-This variable holds a list of C<XS> extension files we want to
-link dynamically into the package. It is used by Makefile.
-
-=back
-
-=cut
-
-=head2 e
-
-=over 4
-
-=cut
-
-=item C<eagain>
-
-From F<nblock_io.U>:
-
-This variable bears the symbolic errno code set by read() when no
-data is present on the file and non-blocking I/O was enabled (otherwise,
-read() blocks naturally).
-
-=item C<ebcdic>
-
-From F<ebcdic.U>:
-
-This variable conditionally defines C<EBCDIC> if this
-system uses C<EBCDIC> encoding. Among other things, this
-means that the character ranges are not contiguous.
-See F<trnl.U>
-
-=item C<echo>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the echo program. After Configure runs,
-the value is reset to a plain C<echo> and is not useful.
-
-=item C<egrep>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the egrep program. After Configure runs,
-the value is reset to a plain C<egrep> and is not useful.
-
-=item C<emacs>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<endgrent_r_proto>
-
-From F<d_endgrent_r.U>:
-
-This variable encodes the prototype of endgrent_r.
-It is zero if d_endgrent_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_endgrent_r
-is defined.
-
-=item C<endhostent_r_proto>
-
-From F<d_endhostent_r.U>:
-
-This variable encodes the prototype of endhostent_r.
-It is zero if d_endhostent_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_endhostent_r
-is defined.
-
-=item C<endnetent_r_proto>
-
-From F<d_endnetent_r.U>:
-
-This variable encodes the prototype of endnetent_r.
-It is zero if d_endnetent_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_endnetent_r
-is defined.
-
-=item C<endprotoent_r_proto>
-
-From F<d_endprotoent_r.U>:
-
-This variable encodes the prototype of endprotoent_r.
-It is zero if d_endprotoent_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_endprotoent_r
-is defined.
-
-=item C<endpwent_r_proto>
-
-From F<d_endpwent_r.U>:
-
-This variable encodes the prototype of endpwent_r.
-It is zero if d_endpwent_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_endpwent_r
-is defined.
-
-=item C<endservent_r_proto>
-
-From F<d_endservent_r.U>:
-
-This variable encodes the prototype of endservent_r.
-It is zero if d_endservent_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_endservent_r
-is defined.
-
-=item C<eunicefix>
-
-From F<Init.U>:
-
-When running under Eunice this variable contains a command which will
-convert a shell script to the proper form of text file for it to be
-executable by the shell. On other systems it is a no-op.
-
-=item C<exe_ext>
-
-From F<Unix.U>:
-
-This is an old synonym for _exe.
-
-=item C<expr>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the expr program. After Configure runs,
-the value is reset to a plain C<expr> and is not useful.
-
-=item C<extensions>
-
-From F<Extensions.U>:
-
-This variable holds a list of all extension files (both C<XS> and
-non-xs linked into the package. It is propagated to F<Config.pm>
-and is typically used to test whether a particular extension
-is available.
-
-=item C<extern_C>
-
-From F<Csym.U>:
-
-C<ANSI> C requires C<extern> where C++ requires 'extern C<C>'. This
-variable can be used in Configure to do the right thing.
-
-=item C<extras>
-
-From F<Extras.U>:
-
-This variable holds a list of extra modules to install.
-
-=back
-
-=cut
-
-=head2 f
-
-=over 4
-
-=cut
-
-=item C<fflushall>
-
-From F<fflushall.U>:
-
-This symbol, if defined, tells that to flush
-all pending stdio output one must loop through all
-the stdio file handles stored in an array and fflush them.
-Note that if fflushNULL is defined, fflushall will not
-even be probed for and will be left undefined.
-
-=item C<fflushNULL>
-
-From F<fflushall.U>:
-
-This symbol, if defined, tells that fflush(C<NULL>) does flush
-all pending stdio output.
-
-=item C<find>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<firstmakefile>
-
-From F<Unix.U>:
-
-This variable defines the first file searched by make. On unix,
-it is makefile (then Makefile). On case-insensitive systems,
-it might be something else. This is only used to deal with
-convoluted make depend tricks.
-
-=item C<flex>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<fpossize>
-
-From F<fpossize.U>:
-
-This variable contains the size of a fpostype in bytes.
-
-=item C<fpostype>
-
-From F<fpostype.U>:
-
-This variable defines Fpos_t to be something like fpos_t, long,
-uint, or whatever type is used to declare file positions in libc.
-
-=item C<freetype>
-
-From F<mallocsrc.U>:
-
-This variable contains the return type of free(). It is usually
-void, but occasionally int.
-
-=item C<from>
-
-From F<Cross.U>:
-
-This variable contains the command used by Configure
-to copy files from the target host. Useful and available
-only during Perl build.
-The string C<:> if not cross-compiling.
-
-=item C<full_ar>
-
-From F<Loc_ar.U>:
-
-This variable contains the full pathname to C<ar>, whether or
-not the user has specified C<portability>. This is only used
-in the F<Makefile.SH>.
-
-=item C<full_csh>
-
-From F<d_csh.U>:
-
-This variable contains the full pathname to C<csh>, whether or
-not the user has specified C<portability>. This is only used
-in the compiled C program, and we assume that all systems which
-can share this executable will have the same full pathname to
-F<csh.>
-
-=item C<full_sed>
-
-From F<Loc_sed.U>:
-
-This variable contains the full pathname to C<sed>, whether or
-not the user has specified C<portability>. This is only used
-in the compiled C program, and we assume that all systems which
-can share this executable will have the same full pathname to
-F<sed.>
-
-=back
-
-=cut
-
-=head2 g
-
-=over 4
-
-=cut
-
-=item C<gccansipedantic>
-
-From F<gccvers.U>:
-
-If C<GNU> cc (gcc) is used, this variable will enable (if set) the
--ansi and -pedantic ccflags for building core files (through
-cflags script). (See F<Porting/pumpkin.pod> for full description).
-
-=item C<gccosandvers>
-
-From F<gccvers.U>:
-
-If C<GNU> cc (gcc) is used, this variable holds the operating system
-and version used to compile gcc. It is set to '' if not gcc,
-or if nothing useful can be parsed as the os version.
-
-=item C<gccversion>
-
-From F<gccvers.U>:
-
-If C<GNU> cc (gcc) is used, this variable holds C<1> or C<2> to
-indicate whether the compiler is version 1 or 2. This is used in
-setting some of the default cflags. It is set to '' if not gcc.
-
-=item C<getgrent_r_proto>
-
-From F<d_getgrent_r.U>:
-
-This variable encodes the prototype of getgrent_r.
-It is zero if d_getgrent_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_getgrent_r
-is defined.
-
-=item C<getgrgid_r_proto>
-
-From F<d_getgrgid_r.U>:
-
-This variable encodes the prototype of getgrgid_r.
-It is zero if d_getgrgid_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_getgrgid_r
-is defined.
-
-=item C<getgrnam_r_proto>
-
-From F<d_getgrnam_r.U>:
-
-This variable encodes the prototype of getgrnam_r.
-It is zero if d_getgrnam_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_getgrnam_r
-is defined.
-
-=item C<gethostbyaddr_r_proto>
-
-From F<d_gethostbyaddr_r.U>:
-
-This variable encodes the prototype of gethostbyaddr_r.
-It is zero if d_gethostbyaddr_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_gethostbyaddr_r
-is defined.
-
-=item C<gethostbyname_r_proto>
-
-From F<d_gethostbyname_r.U>:
-
-This variable encodes the prototype of gethostbyname_r.
-It is zero if d_gethostbyname_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_gethostbyname_r
-is defined.
-
-=item C<gethostent_r_proto>
-
-From F<d_gethostent_r.U>:
-
-This variable encodes the prototype of gethostent_r.
-It is zero if d_gethostent_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_gethostent_r
-is defined.
-
-=item C<getlogin_r_proto>
-
-From F<d_getlogin_r.U>:
-
-This variable encodes the prototype of getlogin_r.
-It is zero if d_getlogin_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_getlogin_r
-is defined.
-
-=item C<getnetbyaddr_r_proto>
-
-From F<d_getnetbyaddr_r.U>:
-
-This variable encodes the prototype of getnetbyaddr_r.
-It is zero if d_getnetbyaddr_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_getnetbyaddr_r
-is defined.
-
-=item C<getnetbyname_r_proto>
-
-From F<d_getnetbyname_r.U>:
-
-This variable encodes the prototype of getnetbyname_r.
-It is zero if d_getnetbyname_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_getnetbyname_r
-is defined.
-
-=item C<getnetent_r_proto>
-
-From F<d_getnetent_r.U>:
-
-This variable encodes the prototype of getnetent_r.
-It is zero if d_getnetent_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_getnetent_r
-is defined.
-
-=item C<getprotobyname_r_proto>
-
-From F<d_getprotobyname_r.U>:
-
-This variable encodes the prototype of getprotobyname_r.
-It is zero if d_getprotobyname_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_getprotobyname_r
-is defined.
-
-=item C<getprotobynumber_r_proto>
-
-From F<d_getprotobynumber_r.U>:
-
-This variable encodes the prototype of getprotobynumber_r.
-It is zero if d_getprotobynumber_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_getprotobynumber_r
-is defined.
-
-=item C<getprotoent_r_proto>
-
-From F<d_getprotoent_r.U>:
-
-This variable encodes the prototype of getprotoent_r.
-It is zero if d_getprotoent_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_getprotoent_r
-is defined.
-
-=item C<getpwent_r_proto>
-
-From F<d_getpwent_r.U>:
-
-This variable encodes the prototype of getpwent_r.
-It is zero if d_getpwent_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_getpwent_r
-is defined.
-
-=item C<getpwnam_r_proto>
-
-From F<d_getpwnam_r.U>:
-
-This variable encodes the prototype of getpwnam_r.
-It is zero if d_getpwnam_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_getpwnam_r
-is defined.
-
-=item C<getpwuid_r_proto>
-
-From F<d_getpwuid_r.U>:
-
-This variable encodes the prototype of getpwuid_r.
-It is zero if d_getpwuid_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_getpwuid_r
-is defined.
-
-=item C<getservbyname_r_proto>
-
-From F<d_getservbyname_r.U>:
-
-This variable encodes the prototype of getservbyname_r.
-It is zero if d_getservbyname_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_getservbyname_r
-is defined.
-
-=item C<getservbyport_r_proto>
-
-From F<d_getservbyport_r.U>:
-
-This variable encodes the prototype of getservbyport_r.
-It is zero if d_getservbyport_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_getservbyport_r
-is defined.
-
-=item C<getservent_r_proto>
-
-From F<d_getservent_r.U>:
-
-This variable encodes the prototype of getservent_r.
-It is zero if d_getservent_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_getservent_r
-is defined.
-
-=item C<getspnam_r_proto>
-
-From F<d_getspnam_r.U>:
-
-This variable encodes the prototype of getspnam_r.
-It is zero if d_getspnam_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_getspnam_r
-is defined.
-
-=item C<gidformat>
-
-From F<gidf.U>:
-
-This variable contains the format string used for printing a Gid_t.
-
-=item C<gidsign>
-
-From F<gidsign.U>:
-
-This variable contains the signedness of a gidtype.
-1 for unsigned, -1 for signed.
-
-=item C<gidsize>
-
-From F<gidsize.U>:
-
-This variable contains the size of a gidtype in bytes.
-
-=item C<gidtype>
-
-From F<gidtype.U>:
-
-This variable defines Gid_t to be something like gid_t, int,
-ushort, or whatever type is used to declare the return type
-of getgid(). Typically, it is the type of group ids in the kernel.
-
-=item C<glibpth>
-
-From F<libpth.U>:
-
-This variable holds the general path (space-separated) used to
-find libraries. It may contain directories that do not exist on
-this platform, libpth is the cleaned-up version.
-
-=item C<gmake>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the gmake program. After Configure runs,
-the value is reset to a plain C<gmake> and is not useful.
-
-=item C<gmtime_r_proto>
-
-From F<d_gmtime_r.U>:
-
-This variable encodes the prototype of gmtime_r.
-It is zero if d_gmtime_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_gmtime_r
-is defined.
-
-=item C<gnulibc_version>
-
-From F<d_gnulibc.U>:
-
-This variable contains the version number of the C<GNU> C library.
-It is usually something like F<2.2.5>. It is a plain '' if this
-is not the C<GNU> C library, or if the version is unknown.
-
-=item C<grep>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the grep program. After Configure runs,
-the value is reset to a plain C<grep> and is not useful.
-
-=item C<groupcat>
-
-From F<nis.U>:
-
-This variable contains a command that produces the text of the
-F</etc/group> file. This is normally "cat F</etc/group>", but can be
-"ypcat group" when C<NIS> is used.
-On some systems, such as os390, there may be no equivalent
-command, in which case this variable is unset.
-
-=item C<groupstype>
-
-From F<groupstype.U>:
-
-This variable defines Groups_t to be something like gid_t, int,
-ushort, or whatever type is used for the second argument to
-getgroups() and setgroups(). Usually, this is the same as
-gidtype (gid_t), but sometimes it isn't.
-
-=item C<gzip>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the gzip program. After Configure runs,
-the value is reset to a plain C<gzip> and is not useful.
-
-=back
-
-=cut
-
-=head2 h
-
-=over 4
-
-=cut
-
-=item C<h_fcntl>
-
-From F<h_fcntl.U>:
-
-This is variable gets set in various places to tell i_fcntl that
-<fcntl.h> should be included.
-
-=item C<h_sysfile>
-
-From F<h_sysfile.U>:
-
-This is variable gets set in various places to tell i_sys_file that
-<sys/file.h> should be included.
-
-=item C<hint>
-
-From F<Oldconfig.U>:
-
-Gives the type of hints used for previous answers. May be one of
-C<default>, C<recommended> or C<previous>.
-
-=item C<hostcat>
-
-From F<nis.U>:
-
-This variable contains a command that produces the text of the
-F</etc/hosts> file. This is normally "cat F</etc/hosts>", but can be
-"ypcat hosts" when C<NIS> is used.
-On some systems, such as os390, there may be no equivalent
-command, in which case this variable is unset.
-
-=item C<html1dir>
-
-From F<html1dir.U>:
-
-This variable contains the name of the directory in which html
-source pages are to be put. This directory is for pages
-that describe whole programs, not libraries or modules. It
-is intended to correspond roughly to section 1 of the Unix
-manuals.
-
-=item C<html1direxp>
-
-From F<html1dir.U>:
-
-This variable is the same as the html1dir variable, but is filename
-expanded at configuration time, for convenient use in makefiles.
-
-=item C<html3dir>
-
-From F<html3dir.U>:
-
-This variable contains the name of the directory in which html
-source pages are to be put. This directory is for pages
-that describe libraries or modules. It is intended to
-correspond roughly to section 3 of the Unix manuals.
-
-=item C<html3direxp>
-
-From F<html3dir.U>:
-
-This variable is the same as the html3dir variable, but is filename
-expanded at configuration time, for convenient use in makefiles.
-
-=back
-
-=cut
-
-=head2 i
-
-=over 4
-
-=cut
-
-=item C<i16size>
-
-From F<perlxv.U>:
-
-This variable is the size of an I16 in bytes.
-
-=item C<i16type>
-
-From F<perlxv.U>:
-
-This variable contains the C type used for Perl's I16.
-
-=item C<i32size>
-
-From F<perlxv.U>:
-
-This variable is the size of an I32 in bytes.
-
-=item C<i32type>
-
-From F<perlxv.U>:
-
-This variable contains the C type used for Perl's I32.
-
-=item C<i64size>
-
-From F<perlxv.U>:
-
-This variable is the size of an I64 in bytes.
-
-=item C<i64type>
-
-From F<perlxv.U>:
-
-This variable contains the C type used for Perl's I64.
-
-=item C<i8size>
-
-From F<perlxv.U>:
-
-This variable is the size of an I8 in bytes.
-
-=item C<i8type>
-
-From F<perlxv.U>:
-
-This variable contains the C type used for Perl's I8.
-
-=item C<i_arpainet>
-
-From F<i_arpainet.U>:
-
-This variable conditionally defines the C<I_ARPA_INET> symbol,
-and indicates whether a C program should include <arpa/inet.h>.
-
-=item C<i_assert>
-
-From F<i_assert.U>:
-
-This variable conditionally defines the C<I_ASSERT> symbol, which
-indicates to the C program that <assert.h> exists and could be
-included.
-
-=item C<i_bsdioctl>
-
-From F<i_sysioctl.U>:
-
-This variable conditionally defines the C<I_SYS_BSDIOCTL> symbol, which
-indicates to the C program that <sys/bsdioctl.h> exists and should
-be included.
-
-=item C<i_crypt>
-
-From F<i_crypt.U>:
-
-This variable conditionally defines the C<I_CRYPT> symbol, and indicates
-whether a C program should include <crypt.h>.
-
-=item C<i_db>
-
-From F<i_db.U>:
-
-This variable conditionally defines the C<I_DB> symbol, and indicates
-whether a C program may include Berkeley's C<DB> include file <db.h>.
-
-=item C<i_dbm>
-
-From F<i_dbm.U>:
-
-This variable conditionally defines the C<I_DBM> symbol, which
-indicates to the C program that <dbm.h> exists and should
-be included.
-
-=item C<i_dirent>
-
-From F<i_dirent.U>:
-
-This variable conditionally defines C<I_DIRENT>, which indicates
-to the C program that it should include <dirent.h>.
-
-=item C<i_dld>
-
-From F<i_dld.U>:
-
-This variable conditionally defines the C<I_DLD> symbol, which
-indicates to the C program that <dld.h> (C<GNU> dynamic loading)
-exists and should be included.
-
-=item C<i_dlfcn>
-
-From F<i_dlfcn.U>:
-
-This variable conditionally defines the C<I_DLFCN> symbol, which
-indicates to the C program that <dlfcn.h> exists and should
-be included.
-
-=item C<i_fcntl>
-
-From F<i_fcntl.U>:
-
-This variable controls the value of C<I_FCNTL> (which tells
-the C program to include <fcntl.h>).
-
-=item C<i_float>
-
-From F<i_float.U>:
-
-This variable conditionally defines the C<I_FLOAT> symbol, and indicates
-whether a C program may include <float.h> to get symbols like C<DBL_MAX>
-or C<DBL_MIN>, F<i.e>. machine dependent floating point values.
-
-=item C<i_fp>
-
-From F<i_fp.U>:
-
-This variable conditionally defines the C<I_FP> symbol, and indicates
-whether a C program should include <fp.h>.
-
-=item C<i_fp_class>
-
-From F<i_fp_class.U>:
-
-This variable conditionally defines the C<I_FP_CLASS> symbol, and indicates
-whether a C program should include <fp_class.h>.
-
-=item C<i_gdbm>
-
-From F<i_gdbm.U>:
-
-This variable conditionally defines the C<I_GDBM> symbol, which
-indicates to the C program that <gdbm.h> exists and should
-be included.
-
-=item C<i_gdbm_ndbm>
-
-From F<i_ndbm.U>:
-
-This variable conditionally defines the C<I_GDBM_NDBM> symbol, which
-indicates to the C program that <gdbm-F<ndbm.h>> exists and should
-be included. This is the location of the F<ndbm.h> compatibility file
-in Debian 4.0.
-
-=item C<i_gdbmndbm>
-
-From F<i_ndbm.U>:
-
-This variable conditionally defines the C<I_GDBMNDBM> symbol, which
-indicates to the C program that <gdbm/ndbm.h> exists and should
-be included. This was the location of the F<ndbm.h> compatibility file
-in RedHat 7.1.
-
-=item C<i_grp>
-
-From F<i_grp.U>:
-
-This variable conditionally defines the C<I_GRP> symbol, and indicates
-whether a C program should include <grp.h>.
-
-=item C<i_ieeefp>
-
-From F<i_ieeefp.U>:
-
-This variable conditionally defines the C<I_IEEEFP> symbol, and indicates
-whether a C program should include <ieeefp.h>.
-
-=item C<i_inttypes>
-
-From F<i_inttypes.U>:
-
-This variable conditionally defines the C<I_INTTYPES> symbol,
-and indicates whether a C program should include <inttypes.h>.
-
-=item C<i_langinfo>
-
-From F<i_langinfo.U>:
-
-This variable conditionally defines the C<I_LANGINFO> symbol,
-and indicates whether a C program should include <langinfo.h>.
-
-=item C<i_libutil>
-
-From F<i_libutil.U>:
-
-This variable conditionally defines the C<I_LIBUTIL> symbol, and indicates
-whether a C program should include <libutil.h>.
-
-=item C<i_limits>
-
-From F<i_limits.U>:
-
-This variable conditionally defines the C<I_LIMITS> symbol, and indicates
-whether a C program may include <limits.h> to get symbols like C<WORD_BIT>
-and friends.
-
-=item C<i_locale>
-
-From F<i_locale.U>:
-
-This variable conditionally defines the C<I_LOCALE> symbol,
-and indicates whether a C program should include <locale.h>.
-
-=item C<i_machcthr>
-
-From F<i_machcthr.U>:
-
-This variable conditionally defines the C<I_MACH_CTHREADS> symbol,
-and indicates whether a C program should include <mach/cthreads.h>.
-
-=item C<i_malloc>
-
-From F<i_malloc.U>:
-
-This variable conditionally defines the C<I_MALLOC> symbol, and indicates
-whether a C program should include <malloc.h>.
-
-=item C<i_mallocmalloc>
-
-From F<i_mallocmalloc.U>:
-
-This variable conditionally defines the C<I_MALLOCMALLOC> symbol,
-and indicates whether a C program should include <malloc/malloc.h>.
-
-=item C<i_math>
-
-From F<i_math.U>:
-
-This variable conditionally defines the C<I_MATH> symbol, and indicates
-whether a C program may include <math.h>.
-
-=item C<i_memory>
-
-From F<i_memory.U>:
-
-This variable conditionally defines the C<I_MEMORY> symbol, and indicates
-whether a C program should include <memory.h>.
-
-=item C<i_mntent>
-
-From F<i_mntent.U>:
-
-This variable conditionally defines the C<I_MNTENT> symbol, and indicates
-whether a C program should include <mntent.h>.
-
-=item C<i_ndbm>
-
-From F<i_ndbm.U>:
-
-This variable conditionally defines the C<I_NDBM> symbol, which
-indicates to the C program that <ndbm.h> exists and should
-be included.
-
-=item C<i_netdb>
-
-From F<i_netdb.U>:
-
-This variable conditionally defines the C<I_NETDB> symbol, and indicates
-whether a C program should include <netdb.h>.
-
-=item C<i_neterrno>
-
-From F<i_neterrno.U>:
-
-This variable conditionally defines the C<I_NET_ERRNO> symbol, which
-indicates to the C program that <net/errno.h> exists and should
-be included.
-
-=item C<i_netinettcp>
-
-From F<i_netinettcp.U>:
-
-This variable conditionally defines the C<I_NETINET_TCP> symbol,
-and indicates whether a C program should include <netinet/tcp.h>.
-
-=item C<i_niin>
-
-From F<i_niin.U>:
-
-This variable conditionally defines C<I_NETINET_IN>, which indicates
-to the C program that it should include <netinet/in.h>. Otherwise,
-you may try <sys/in.h>.
-
-=item C<i_poll>
-
-From F<i_poll.U>:
-
-This variable conditionally defines the C<I_POLL> symbol, and indicates
-whether a C program should include <poll.h>.
-
-=item C<i_prot>
-
-From F<i_prot.U>:
-
-This variable conditionally defines the C<I_PROT> symbol, and indicates
-whether a C program should include <prot.h>.
-
-=item C<i_pthread>
-
-From F<i_pthread.U>:
-
-This variable conditionally defines the C<I_PTHREAD> symbol,
-and indicates whether a C program should include <pthread.h>.
-
-=item C<i_pwd>
-
-From F<i_pwd.U>:
-
-This variable conditionally defines C<I_PWD>, which indicates
-to the C program that it should include <pwd.h>.
-
-=item C<i_rpcsvcdbm>
-
-From F<i_dbm.U>:
-
-This variable conditionally defines the C<I_RPCSVC_DBM> symbol, which
-indicates to the C program that <rpcsvc/dbm.h> exists and should
-be included. Some System V systems might need this instead of <dbm.h>.
-
-=item C<i_sfio>
-
-From F<i_sfio.U>:
-
-This variable conditionally defines the C<I_SFIO> symbol,
-and indicates whether a C program should include <sfio.h>.
-
-=item C<i_sgtty>
-
-From F<i_termio.U>:
-
-This variable conditionally defines the C<I_SGTTY> symbol, which
-indicates to the C program that it should include <sgtty.h> rather
-than <termio.h>.
-
-=item C<i_shadow>
-
-From F<i_shadow.U>:
-
-This variable conditionally defines the C<I_SHADOW> symbol, and indicates
-whether a C program should include <shadow.h>.
-
-=item C<i_socks>
-
-From F<i_socks.U>:
-
-This variable conditionally defines the C<I_SOCKS> symbol, and indicates
-whether a C program should include <socks.h>.
-
-=item C<i_stdarg>
-
-From F<i_varhdr.U>:
-
-This variable conditionally defines the C<I_STDARG> symbol, which
-indicates to the C program that <stdarg.h> exists and should
-be included.
-
-=item C<i_stdbool>
-
-From F<i_stdbool.U>:
-
-This variable conditionally defines the C<I_STDBOOL> symbol, which
-indicates to the C program that <stdbool.h> exists and should
-be included.
-
-=item C<i_stddef>
-
-From F<i_stddef.U>:
-
-This variable conditionally defines the C<I_STDDEF> symbol, which
-indicates to the C program that <stddef.h> exists and should
-be included.
-
-=item C<i_stdlib>
-
-From F<i_stdlib.U>:
-
-This variable conditionally defines the C<I_STDLIB> symbol, which
-indicates to the C program that <stdlib.h> exists and should
-be included.
-
-=item C<i_string>
-
-From F<i_string.U>:
-
-This variable conditionally defines the C<I_STRING> symbol, which
-indicates that <string.h> should be included rather than <strings.h>.
-
-=item C<i_sunmath>
-
-From F<i_sunmath.U>:
-
-This variable conditionally defines the C<I_SUNMATH> symbol, and indicates
-whether a C program should include <sunmath.h>.
-
-=item C<i_sysaccess>
-
-From F<i_sysaccess.U>:
-
-This variable conditionally defines the C<I_SYS_ACCESS> symbol,
-and indicates whether a C program should include <sys/access.h>.
-
-=item C<i_sysdir>
-
-From F<i_sysdir.U>:
-
-This variable conditionally defines the C<I_SYS_DIR> symbol, and indicates
-whether a C program should include <sys/dir.h>.
-
-=item C<i_sysfile>
-
-From F<i_sysfile.U>:
-
-This variable conditionally defines the C<I_SYS_FILE> symbol, and indicates
-whether a C program should include <sys/file.h> to get C<R_OK> and friends.
-
-=item C<i_sysfilio>
-
-From F<i_sysioctl.U>:
-
-This variable conditionally defines the C<I_SYS_FILIO> symbol, which
-indicates to the C program that <sys/filio.h> exists and should
-be included in preference to <sys/ioctl.h>.
-
-=item C<i_sysin>
-
-From F<i_niin.U>:
-
-This variable conditionally defines C<I_SYS_IN>, which indicates
-to the C program that it should include <sys/in.h> instead of
-<netinet/in.h>.
-
-=item C<i_sysioctl>
-
-From F<i_sysioctl.U>:
-
-This variable conditionally defines the C<I_SYS_IOCTL> symbol, which
-indicates to the C program that <sys/ioctl.h> exists and should
-be included.
-
-=item C<i_syslog>
-
-From F<i_syslog.U>:
-
-This variable conditionally defines the C<I_SYSLOG> symbol,
-and indicates whether a C program should include <syslog.h>.
-
-=item C<i_sysmman>
-
-From F<i_sysmman.U>:
-
-This variable conditionally defines the C<I_SYS_MMAN> symbol, and
-indicates whether a C program should include <sys/mman.h>.
-
-=item C<i_sysmode>
-
-From F<i_sysmode.U>:
-
-This variable conditionally defines the C<I_SYSMODE> symbol,
-and indicates whether a C program should include <sys/mode.h>.
-
-=item C<i_sysmount>
-
-From F<i_sysmount.U>:
-
-This variable conditionally defines the C<I_SYSMOUNT> symbol,
-and indicates whether a C program should include <sys/mount.h>.
-
-=item C<i_sysndir>
-
-From F<i_sysndir.U>:
-
-This variable conditionally defines the C<I_SYS_NDIR> symbol, and indicates
-whether a C program should include <sys/ndir.h>.
-
-=item C<i_sysparam>
-
-From F<i_sysparam.U>:
-
-This variable conditionally defines the C<I_SYS_PARAM> symbol, and indicates
-whether a C program should include <sys/param.h>.
-
-=item C<i_syspoll>
-
-From F<i_syspoll.U>:
-
-This variable conditionally defines the C<I_SYS_POLL> symbol, which
-indicates to the C program that it should include <sys/poll.h>.
-
-=item C<i_sysresrc>
-
-From F<i_sysresrc.U>:
-
-This variable conditionally defines the C<I_SYS_RESOURCE> symbol,
-and indicates whether a C program should include <sys/resource.h>.
-
-=item C<i_syssecrt>
-
-From F<i_syssecrt.U>:
-
-This variable conditionally defines the C<I_SYS_SECURITY> symbol,
-and indicates whether a C program should include <sys/security.h>.
-
-=item C<i_sysselct>
-
-From F<i_sysselct.U>:
-
-This variable conditionally defines C<I_SYS_SELECT>, which indicates
-to the C program that it should include <sys/select.h> in order to
-get the definition of struct timeval.
-
-=item C<i_syssockio>
-
-From F<i_sysioctl.U>:
-
-This variable conditionally defines C<I_SYS_SOCKIO> to indicate to the
-C program that socket ioctl codes may be found in <sys/sockio.h>
-instead of <sys/ioctl.h>.
-
-=item C<i_sysstat>
-
-From F<i_sysstat.U>:
-
-This variable conditionally defines the C<I_SYS_STAT> symbol,
-and indicates whether a C program should include <sys/stat.h>.
-
-=item C<i_sysstatfs>
-
-From F<i_sysstatfs.U>:
-
-This variable conditionally defines the C<I_SYSSTATFS> symbol,
-and indicates whether a C program should include <sys/statfs.h>.
-
-=item C<i_sysstatvfs>
-
-From F<i_sysstatvfs.U>:
-
-This variable conditionally defines the C<I_SYSSTATVFS> symbol,
-and indicates whether a C program should include <sys/statvfs.h>.
-
-=item C<i_systime>
-
-From F<i_time.U>:
-
-This variable conditionally defines C<I_SYS_TIME>, which indicates
-to the C program that it should include <sys/time.h>.
-
-=item C<i_systimek>
-
-From F<i_time.U>:
-
-This variable conditionally defines C<I_SYS_TIME_KERNEL>, which
-indicates to the C program that it should include <sys/time.h>
-with C<KERNEL> defined.
-
-=item C<i_systimes>
-
-From F<i_systimes.U>:
-
-This variable conditionally defines the C<I_SYS_TIMES> symbol, and indicates
-whether a C program should include <sys/times.h>.
-
-=item C<i_systypes>
-
-From F<i_systypes.U>:
-
-This variable conditionally defines the C<I_SYS_TYPES> symbol,
-and indicates whether a C program should include <sys/types.h>.
-
-=item C<i_sysuio>
-
-From F<i_sysuio.U>:
-
-This variable conditionally defines the C<I_SYSUIO> symbol, and indicates
-whether a C program should include <sys/uio.h>.
-
-=item C<i_sysun>
-
-From F<i_sysun.U>:
-
-This variable conditionally defines C<I_SYS_UN>, which indicates
-to the C program that it should include <sys/un.h> to get C<UNIX>
-domain socket definitions.
-
-=item C<i_sysutsname>
-
-From F<i_sysutsname.U>:
-
-This variable conditionally defines the C<I_SYSUTSNAME> symbol,
-and indicates whether a C program should include <sys/utsname.h>.
-
-=item C<i_sysvfs>
-
-From F<i_sysvfs.U>:
-
-This variable conditionally defines the C<I_SYSVFS> symbol,
-and indicates whether a C program should include <sys/vfs.h>.
-
-=item C<i_syswait>
-
-From F<i_syswait.U>:
-
-This variable conditionally defines C<I_SYS_WAIT>, which indicates
-to the C program that it should include <sys/wait.h>.
-
-=item C<i_termio>
-
-From F<i_termio.U>:
-
-This variable conditionally defines the C<I_TERMIO> symbol, which
-indicates to the C program that it should include <termio.h> rather
-than <sgtty.h>.
-
-=item C<i_termios>
-
-From F<i_termio.U>:
-
-This variable conditionally defines the C<I_TERMIOS> symbol, which
-indicates to the C program that the C<POSIX> <termios.h> file is
-to be included.
-
-=item C<i_time>
-
-From F<i_time.U>:
-
-This variable conditionally defines C<I_TIME>, which indicates
-to the C program that it should include <time.h>.
-
-=item C<i_unistd>
-
-From F<i_unistd.U>:
-
-This variable conditionally defines the C<I_UNISTD> symbol, and indicates
-whether a C program should include <unistd.h>.
-
-=item C<i_ustat>
-
-From F<i_ustat.U>:
-
-This variable conditionally defines the C<I_USTAT> symbol, and indicates
-whether a C program should include <ustat.h>.
-
-=item C<i_utime>
-
-From F<i_utime.U>:
-
-This variable conditionally defines the C<I_UTIME> symbol, and indicates
-whether a C program should include <utime.h>.
-
-=item C<i_values>
-
-From F<i_values.U>:
-
-This variable conditionally defines the C<I_VALUES> symbol, and indicates
-whether a C program may include <values.h> to get symbols like C<MAXLONG>
-and friends.
-
-=item C<i_varargs>
-
-From F<i_varhdr.U>:
-
-This variable conditionally defines C<I_VARARGS>, which indicates
-to the C program that it should include <varargs.h>.
-
-=item C<i_varhdr>
-
-From F<i_varhdr.U>:
-
-Contains the name of the header to be included to get va_dcl definition.
-Typically one of F<varargs.h> or F<stdarg.h>.
-
-=item C<i_vfork>
-
-From F<i_vfork.U>:
-
-This variable conditionally defines the C<I_VFORK> symbol, and indicates
-whether a C program should include F<vfork.h>.
-
-=item C<ignore_versioned_solibs>
-
-From F<libs.U>:
-
-This variable should be non-empty if non-versioned shared
-libraries (F<libfoo.so.x.y>) are to be ignored (because they
-cannot be linked against).
-
-=item C<inc_version_list>
-
-From F<inc_version_list.U>:
-
-This variable specifies the list of subdirectories in over
-which F<perl.c>:incpush() and F<lib/lib.pm> will automatically
-search when adding directories to @C<INC>. The elements in
-the list are separated by spaces. This is only useful
-if you have a perl library directory tree structured like the
-default one. See C<INSTALL> for how this works. The versioned
-site_perl directory was introduced in 5.005, so that is the
-lowest possible value.
-
-This list includes architecture-dependent directories back to
-version $api_versionstring (e.g. 5.5.640) and
-architecture-independent directories all the way back to
-5.005.
-
-=item C<inc_version_list_init>
-
-From F<inc_version_list.U>:
-
-This variable holds the same list as inc_version_list, but
-each item is enclosed in double quotes and separated by commas,
-suitable for use in the C<PERL_INC_VERSION_LIST> initialization.
-
-=item C<incpath>
-
-From F<usrinc.U>:
-
-This variable must precede the normal include path to get the
-right one, as in F<$F<incpath/usr/include>> or F<$F<incpath/usr/lib>>.
-Value can be "" or F</bsd43> on mips.
-
-=item C<inews>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<initialinstalllocation>
-
-From F<bin.U>:
-
-When userelocatableinc is true, this variable holds the location
-that make install should copy the perl binary to, with all the
-run-time relocatable paths calculated from this at install time.
-When used, it is initialised to the original value of binexp, and
-then binexp is set to F<.../>, as the other binaries are found
-relative to the perl binary.
-
-=item C<installarchlib>
-
-From F<archlib.U>:
-
-This variable is really the same as archlibexp but may differ on
-those systems using C<AFS>. For extra portability, only this variable
-should be used in makefiles.
-
-=item C<installbin>
-
-From F<bin.U>:
-
-This variable is the same as binexp unless C<AFS> is running in which case
-the user is explicitly prompted for it. This variable should always
-be used in your makefiles for maximum portability.
-
-=item C<installhtml1dir>
-
-From F<html1dir.U>:
-
-This variable is really the same as html1direxp, unless you are
-using a different installprefix. For extra portability, you
-should only use this variable within your makefiles.
-
-=item C<installhtml3dir>
-
-From F<html3dir.U>:
-
-This variable is really the same as html3direxp, unless you are
-using a different installprefix. For extra portability, you
-should only use this variable within your makefiles.
-
-=item C<installman1dir>
-
-From F<man1dir.U>:
-
-This variable is really the same as man1direxp, unless you are using
-C<AFS> in which case it points to the read/write location whereas
-man1direxp only points to the read-only access location. For extra
-portability, you should only use this variable within your makefiles.
-
-=item C<installman3dir>
-
-From F<man3dir.U>:
-
-This variable is really the same as man3direxp, unless you are using
-C<AFS> in which case it points to the read/write location whereas
-man3direxp only points to the read-only access location. For extra
-portability, you should only use this variable within your makefiles.
-
-=item C<installprefix>
-
-From F<installprefix.U>:
-
-This variable holds the name of the directory below which
-"make install" will install the package. For most users, this
-is the same as prefix. However, it is useful for
-installing the software into a different (usually temporary)
-location after which it can be bundled up and moved somehow
-to the final location specified by prefix.
-
-=item C<installprefixexp>
-
-From F<installprefix.U>:
-
-This variable holds the full absolute path of installprefix
-with all F<~>-expansion done.
-
-=item C<installprivlib>
-
-From F<privlib.U>:
-
-This variable is really the same as privlibexp but may differ on
-those systems using C<AFS>. For extra portability, only this variable
-should be used in makefiles.
-
-=item C<installscript>
-
-From F<scriptdir.U>:
-
-This variable is usually the same as scriptdirexp, unless you are on
-a system running C<AFS>, in which case they may differ slightly. You
-should always use this variable within your makefiles for portability.
-
-=item C<installsitearch>
-
-From F<sitearch.U>:
-
-This variable is really the same as sitearchexp but may differ on
-those systems using C<AFS>. For extra portability, only this variable
-should be used in makefiles.
-
-=item C<installsitebin>
-
-From F<sitebin.U>:
-
-This variable is usually the same as sitebinexp, unless you are on
-a system running C<AFS>, in which case they may differ slightly. You
-should always use this variable within your makefiles for portability.
-
-=item C<installsitehtml1dir>
-
-From F<sitehtml1dir.U>:
-
-This variable is really the same as sitehtml1direxp, unless you are using
-C<AFS> in which case it points to the read/write location whereas
-html1direxp only points to the read-only access location. For extra
-portability, you should only use this variable within your makefiles.
-
-=item C<installsitehtml3dir>
-
-From F<sitehtml3dir.U>:
-
-This variable is really the same as sitehtml3direxp, unless you are using
-C<AFS> in which case it points to the read/write location whereas
-html3direxp only points to the read-only access location. For extra
-portability, you should only use this variable within your makefiles.
-
-=item C<installsitelib>
-
-From F<sitelib.U>:
-
-This variable is really the same as sitelibexp but may differ on
-those systems using C<AFS>. For extra portability, only this variable
-should be used in makefiles.
-
-=item C<installsiteman1dir>
-
-From F<siteman1dir.U>:
-
-This variable is really the same as siteman1direxp, unless you are using
-C<AFS> in which case it points to the read/write location whereas
-man1direxp only points to the read-only access location. For extra
-portability, you should only use this variable within your makefiles.
-
-=item C<installsiteman3dir>
-
-From F<siteman3dir.U>:
-
-This variable is really the same as siteman3direxp, unless you are using
-C<AFS> in which case it points to the read/write location whereas
-man3direxp only points to the read-only access location. For extra
-portability, you should only use this variable within your makefiles.
-
-=item C<installsitescript>
-
-From F<sitescript.U>:
-
-This variable is usually the same as sitescriptexp, unless you are on
-a system running C<AFS>, in which case they may differ slightly. You
-should always use this variable within your makefiles for portability.
-
-=item C<installstyle>
-
-From F<installstyle.U>:
-
-This variable describes the C<style> of the perl installation.
-This is intended to be useful for tools that need to
-manipulate entire perl distributions. Perl itself doesn't use
-this to find its libraries -- the library directories are
-stored directly in F<Config.pm>. Currently, there are only two
-styles: C<lib> and F<lib/perl5>. The default library locations
-(e.g. privlib, sitelib) are either F<$prefix/lib> or
-F<$prefix/lib/perl5>. The former is useful if $prefix is a
-directory dedicated to perl (e.g. F</opt/perl>), while the latter
-is useful if $prefix is shared by many packages, e.g. if
-$prefix=F</usr/local>.
-
-Unfortunately, while this C<style> variable is used to set
-defaults for all three directory hierarchies (core, vendor, and
-site), there is no guarantee that the same style is actually
-appropriate for all those directories. For example, $prefix
-might be F</opt/perl>, but $siteprefix might be F</usr/local>.
-(Perhaps, in retrospect, the C<lib> style should never have been
-supported, but it did seem like a nice idea at the time.)
-
-The situation is even less clear for tools such as MakeMaker
-that can be used to install additional modules into
-non-standard places. For example, if a user intends to install
-a module into a private directory (perhaps by setting C<PREFIX> on
-the F<Makefile.PL> command line), then there is no reason to
-assume that the Configure-time $installstyle setting will be
-relevant for that C<PREFIX>.
-
-This may later be extended to include other information, so
-be careful with pattern-matching on the results.
-
-For compatibility with F<perl5.005> and earlier, the default
-setting is based on whether or not $prefix contains the string
-C<perl>.
-
-=item C<installusrbinperl>
-
-From F<instubperl.U>:
-
-This variable tells whether Perl should be installed also as
-F</usr/bin/perl> in addition to
-F<$installbin/perl>
-
-=item C<installvendorarch>
-
-From F<vendorarch.U>:
-
-This variable is really the same as vendorarchexp but may differ on
-those systems using C<AFS>. For extra portability, only this variable
-should be used in makefiles.
-
-=item C<installvendorbin>
-
-From F<vendorbin.U>:
-
-This variable is really the same as vendorbinexp but may differ on
-those systems using C<AFS>. For extra portability, only this variable
-should be used in makefiles.
-
-=item C<installvendorhtml1dir>
-
-From F<vendorhtml1dir.U>:
-
-This variable is really the same as vendorhtml1direxp but may differ on
-those systems using C<AFS>. For extra portability, only this variable
-should be used in makefiles.
-
-=item C<installvendorhtml3dir>
-
-From F<vendorhtml3dir.U>:
-
-This variable is really the same as vendorhtml3direxp but may differ on
-those systems using C<AFS>. For extra portability, only this variable
-should be used in makefiles.
-
-=item C<installvendorlib>
-
-From F<vendorlib.U>:
-
-This variable is really the same as vendorlibexp but may differ on
-those systems using C<AFS>. For extra portability, only this variable
-should be used in makefiles.
-
-=item C<installvendorman1dir>
-
-From F<vendorman1dir.U>:
-
-This variable is really the same as vendorman1direxp but may differ on
-those systems using C<AFS>. For extra portability, only this variable
-should be used in makefiles.
-
-=item C<installvendorman3dir>
-
-From F<vendorman3dir.U>:
-
-This variable is really the same as vendorman3direxp but may differ on
-those systems using C<AFS>. For extra portability, only this variable
-should be used in makefiles.
-
-=item C<installvendorscript>
-
-From F<vendorscript.U>:
-
-This variable is really the same as vendorscriptexp but may differ on
-those systems using C<AFS>. For extra portability, only this variable
-should be used in makefiles.
-
-=item C<intsize>
-
-From F<intsize.U>:
-
-This variable contains the value of the C<INTSIZE> symbol, which
-indicates to the C program how many bytes there are in an int.
-
-=item C<issymlink>
-
-From F<issymlink.U>:
-
-This variable holds the test command to test for a symbolic link
-(if they are supported). Typical values include C<test -h> and
-C<test -L>.
-
-=item C<ivdformat>
-
-From F<perlxvf.U>:
-
-This variable contains the format string used for printing
-a Perl C<IV> as a signed decimal integer.
-
-=item C<ivsize>
-
-From F<perlxv.U>:
-
-This variable is the size of an C<IV> in bytes.
-
-=item C<ivtype>
-
-From F<perlxv.U>:
-
-This variable contains the C type used for Perl's C<IV>.
-
-=back
-
-=cut
-
-=head2 k
-
-=over 4
-
-=cut
-
-=item C<known_extensions>
-
-From F<Extensions.U>:
-
-This variable holds a list of all C<XS> extensions included in
-the package.
-
-=item C<ksh>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=back
-
-=cut
-
-=head2 l
-
-=over 4
-
-=cut
-
-=item C<ld>
-
-From F<dlsrc.U>:
-
-This variable indicates the program to be used to link
-libraries for dynamic loading. On some systems, it is C<ld>.
-On C<ELF> systems, it should be $cc. Mostly, we'll try to respect
-the hint file setting.
-
-=item C<ld_can_script>
-
-From F<dlsrc.U>:
-
-This variable shows if the loader accepts scripts in the form of
--Wl,--version-script=F<ld.script>. This is currently only supported
-for C<GNU> ld on C<ELF> in dynamic loading builds.
-
-=item C<lddlflags>
-
-From F<dlsrc.U>:
-
-This variable contains any special flags that might need to be
-passed to $ld to create a shared library suitable for dynamic
-loading. It is up to the makefile to use it. For hpux, it
-should be C<-b>. For sunos 4.1, it is empty.
-
-=item C<ldflags>
-
-From F<ccflags.U>:
-
-This variable contains any additional C loader flags desired by
-the user. It is up to the Makefile to use this.
-
-=item C<ldflags_uselargefiles>
-
-From F<uselfs.U>:
-
-This variable contains the loader flags needed by large file builds
-and added to ldflags by hints files.
-
-=item C<ldlibpthname>
-
-From F<libperl.U>:
-
-This variable holds the name of the shared library
-search path, often C<LD_LIBRARY_PATH>. To get an empty
-string, the hints file must set this to C<none>.
-
-=item C<less>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the less program. After Configure runs,
-the value is reset to a plain C<less> and is not useful.
-
-=item C<lib_ext>
-
-From F<Unix.U>:
-
-This is an old synonym for _a.
-
-=item C<libc>
-
-From F<libc.U>:
-
-This variable contains the location of the C library.
-
-=item C<libperl>
-
-From F<libperl.U>:
-
-The perl executable is obtained by linking F<perlmain.c> with
-libperl, any static extensions (usually just DynaLoader),
-and any other libraries needed on this system. libperl
-is usually F<libperl.a>, but can also be F<libperl.so.xxx> if
-the user wishes to build a perl executable with a shared
-library.
-
-=item C<libpth>
-
-From F<libpth.U>:
-
-This variable holds the general path (space-separated) used to find
-libraries. It is intended to be used by other units.
-
-=item C<libs>
-
-From F<libs.U>:
-
-This variable holds the additional libraries we want to use.
-It is up to the Makefile to deal with it. The list can be empty.
-
-=item C<libsdirs>
-
-From F<libs.U>:
-
-This variable holds the directory names aka dirnames of the libraries
-we found and accepted, duplicates are removed.
-
-=item C<libsfiles>
-
-From F<libs.U>:
-
-This variable holds the filenames aka basenames of the libraries
-we found and accepted.
-
-=item C<libsfound>
-
-From F<libs.U>:
-
-This variable holds the full pathnames of the libraries
-we found and accepted.
-
-=item C<libspath>
-
-From F<libs.U>:
-
-This variable holds the directory names probed for libraries.
-
-=item C<libswanted>
-
-From F<Myinit.U>:
-
-This variable holds a list of all the libraries we want to
-search. The order is chosen to pick up the c library
-ahead of ucb or bsd libraries for SVR4.
-
-=item C<libswanted_uselargefiles>
-
-From F<uselfs.U>:
-
-This variable contains the libraries needed by large file builds
-and added to ldflags by hints files. It is a space separated list
-of the library names without the C<lib> prefix or any suffix, just
-like F<libswanted.>.
-
-=item C<line>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<lint>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<lkflags>
-
-From F<ccflags.U>:
-
-This variable contains any additional C partial linker flags desired by
-the user. It is up to the Makefile to use this.
-
-=item C<ln>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the ln program. After Configure runs,
-the value is reset to a plain C<ln> and is not useful.
-
-=item C<lns>
-
-From F<lns.U>:
-
-This variable holds the name of the command to make
-symbolic links (if they are supported). It can be used
-in the Makefile. It is either C<ln -s> or C<ln>
-
-=item C<localtime_r_proto>
-
-From F<d_localtime_r.U>:
-
-This variable encodes the prototype of localtime_r.
-It is zero if d_localtime_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_localtime_r
-is defined.
-
-=item C<locincpth>
-
-From F<ccflags.U>:
-
-This variable contains a list of additional directories to be
-searched by the compiler. The appropriate C<-I> directives will
-be added to ccflags. This is intended to simplify setting
-local directories from the Configure command line.
-It's not much, but it parallels the loclibpth stuff in F<libpth.U>.
-
-=item C<loclibpth>
-
-From F<libpth.U>:
-
-This variable holds the paths (space-separated) used to find local
-libraries. It is prepended to libpth, and is intended to be easily
-set from the command line.
-
-=item C<longdblsize>
-
-From F<d_longdbl.U>:
-
-This variable contains the value of the C<LONG_DOUBLESIZE> symbol, which
-indicates to the C program how many bytes there are in a long double,
-if this system supports long doubles.
-
-=item C<longlongsize>
-
-From F<d_longlong.U>:
-
-This variable contains the value of the C<LONGLONGSIZE> symbol, which
-indicates to the C program how many bytes there are in a long long,
-if this system supports long long.
-
-=item C<longsize>
-
-From F<intsize.U>:
-
-This variable contains the value of the C<LONGSIZE> symbol, which
-indicates to the C program how many bytes there are in a long.
-
-=item C<lp>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<lpr>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<ls>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the ls program. After Configure runs,
-the value is reset to a plain C<ls> and is not useful.
-
-=item C<lseeksize>
-
-From F<lseektype.U>:
-
-This variable defines lseektype to be something like off_t, long,
-or whatever type is used to declare lseek offset's type in the
-kernel (which also appears to be lseek's return type).
-
-=item C<lseektype>
-
-From F<lseektype.U>:
-
-This variable defines lseektype to be something like off_t, long,
-or whatever type is used to declare lseek offset's type in the
-kernel (which also appears to be lseek's return type).
-
-=back
-
-=cut
-
-=head2 m
-
-=over 4
-
-=cut
-
-=item C<mad>
-
-From F<mad.U>:
-
-This variable indicates that the Misc Attribute Definition code is to
-be compiled.
-
-=item C<madlyh>
-
-From F<mad.U>:
-
-If the Misc Attribute Decoration is to be compiled, this variable is
-set to the name of the extra header files to be used, else it is ''
-
-=item C<madlyobj>
-
-From F<mad.U>:
-
-If the Misc Attribute Decoration is to be compiled, this variable is
-set to the name of the extra object files to be used, else it is ''
-
-=item C<madlysrc>
-
-From F<mad.U>:
-
-If the Misc Attribute Decoration is to be compiled, this variable is
-set to the name of the extra C source files to be used, else it is ''
-
-=item C<mail>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<mailx>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<make>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the make program. After Configure runs,
-the value is reset to a plain C<make> and is not useful.
-
-=item C<make_set_make>
-
-From F<make.U>:
-
-Some versions of C<make> set the variable C<MAKE>. Others do not.
-This variable contains the string to be included in F<Makefile.SH>
-so that C<MAKE> is set if needed, and not if not needed.
-Possible values are:
-
-make_set_make=C<#> # If your make program handles this for you,
-
-make_set_make=C<MAKE=$make> # if it doesn't.
-
-This uses a comment character so that we can distinguish a
-C<set> value (from a previous F<config.sh> or Configure C<-D> option)
-from an uncomputed value.
-
-=item C<mallocobj>
-
-From F<mallocsrc.U>:
-
-This variable contains the name of the F<malloc.o> that this package
-generates, if that F<malloc.o> is preferred over the system malloc.
-Otherwise the value is null. This variable is intended for generating
-Makefiles. See mallocsrc.
-
-=item C<mallocsrc>
-
-From F<mallocsrc.U>:
-
-This variable contains the name of the F<malloc.c> that comes with
-the package, if that F<malloc.c> is preferred over the system malloc.
-Otherwise the value is null. This variable is intended for generating
-Makefiles.
-
-=item C<malloctype>
-
-From F<mallocsrc.U>:
-
-This variable contains the kind of ptr returned by malloc and realloc.
-
-=item C<man1dir>
-
-From F<man1dir.U>:
-
-This variable contains the name of the directory in which manual
-source pages are to be put. It is the responsibility of the
-F<Makefile.SH> to get the value of this into the proper command.
-You must be prepared to do the F<~name> expansion yourself.
-
-=item C<man1direxp>
-
-From F<man1dir.U>:
-
-This variable is the same as the man1dir variable, but is filename
-expanded at configuration time, for convenient use in makefiles.
-
-=item C<man1ext>
-
-From F<man1dir.U>:
-
-This variable contains the extension that the manual page should
-have: one of C<n>, C<l>, or C<1>. The Makefile must supply the F<.>.
-See man1dir.
-
-=item C<man3dir>
-
-From F<man3dir.U>:
-
-This variable contains the name of the directory in which manual
-source pages are to be put. It is the responsibility of the
-F<Makefile.SH> to get the value of this into the proper command.
-You must be prepared to do the F<~name> expansion yourself.
-
-=item C<man3direxp>
-
-From F<man3dir.U>:
-
-This variable is the same as the man3dir variable, but is filename
-expanded at configuration time, for convenient use in makefiles.
-
-=item C<man3ext>
-
-From F<man3dir.U>:
-
-This variable contains the extension that the manual page should
-have: one of C<n>, C<l>, or C<3>. The Makefile must supply the F<.>.
-See man3dir.
-
-=item C<mips_type>
-
-From F<usrinc.U>:
-
-This variable holds the environment type for the mips system.
-Possible values are "BSD 4.3" and "System V".
-
-=item C<mistrustnm>
-
-From F<Csym.U>:
-
-This variable can be used to establish a fallthrough for the cases
-where nm fails to find a symbol. If usenm is false or usenm is true
-and mistrustnm is false, this variable has no effect. If usenm is true
-and mistrustnm is C<compile>, a test program will be compiled to try to
-find any symbol that can't be located via nm lookup. If mistrustnm is
-C<run>, the test program will be run as well as being compiled.
-
-=item C<mkdir>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the mkdir program. After Configure runs,
-the value is reset to a plain C<mkdir> and is not useful.
-
-=item C<mmaptype>
-
-From F<d_mmap.U>:
-
-This symbol contains the type of pointer returned by mmap()
-(and simultaneously the type of the first argument).
-It can be C<void *> or C<caddr_t>.
-
-=item C<modetype>
-
-From F<modetype.U>:
-
-This variable defines modetype to be something like mode_t,
-int, unsigned short, or whatever type is used to declare file
-modes for system calls.
-
-=item C<more>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the more program. After Configure runs,
-the value is reset to a plain C<more> and is not useful.
-
-=item C<multiarch>
-
-From F<multiarch.U>:
-
-This variable conditionally defines the C<MULTIARCH> symbol
-which signifies the presence of multiplatform files.
-This is normally set by hints files.
-
-=item C<mv>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<myarchname>
-
-From F<archname.U>:
-
-This variable holds the architecture name computed by Configure in
-a previous run. It is not intended to be perused by any user and
-should never be set in a hint file.
-
-=item C<mydomain>
-
-From F<myhostname.U>:
-
-This variable contains the eventual value of the C<MYDOMAIN> symbol,
-which is the domain of the host the program is going to run on.
-The domain must be appended to myhostname to form a complete host name.
-The dot comes with mydomain, and need not be supplied by the program.
-
-=item C<myhostname>
-
-From F<myhostname.U>:
-
-This variable contains the eventual value of the C<MYHOSTNAME> symbol,
-which is the name of the host the program is going to run on.
-The domain is not kept with hostname, but must be gotten from mydomain.
-The dot comes with mydomain, and need not be supplied by the program.
-
-=item C<myuname>
-
-From F<Oldconfig.U>:
-
-The output of C<uname -a> if available, otherwise the hostname. On Xenix,
-pseudo variables assignments in the output are stripped, thank you. The
-whole thing is then lower-cased.
-
-=back
-
-=cut
-
-=head2 n
-
-=over 4
-
-=cut
-
-=item C<n>
-
-From F<n.U>:
-
-This variable contains the C<-n> flag if that is what causes the echo
-command to suppress newline. Otherwise it is null. Correct usage is
-$echo $n "prompt for a question: $c".
-
-=item C<need_va_copy>
-
-From F<need_va_copy.U>:
-
-This symbol, if defined, indicates that the system stores
-the variable argument list datatype, va_list, in a format
-that cannot be copied by simple assignment, so that some
-other means must be used when copying is required.
-As such systems vary in their provision (or non-provision)
-of copying mechanisms, F<handy.h> defines a platform-
-C<independent> macro, Perl_va_copy(src, dst), to do the job.
-
-=item C<netdb_hlen_type>
-
-From F<netdbtype.U>:
-
-This variable holds the type used for the 2nd argument to
-gethostbyaddr(). Usually, this is int or size_t or unsigned.
-This is only useful if you have gethostbyaddr(), naturally.
-
-=item C<netdb_host_type>
-
-From F<netdbtype.U>:
-
-This variable holds the type used for the 1st argument to
-gethostbyaddr(). Usually, this is char * or void *, possibly
-with or without a const prefix.
-This is only useful if you have gethostbyaddr(), naturally.
-
-=item C<netdb_name_type>
-
-From F<netdbtype.U>:
-
-This variable holds the type used for the argument to
-gethostbyname(). Usually, this is char * or const char *.
-This is only useful if you have gethostbyname(), naturally.
-
-=item C<netdb_net_type>
-
-From F<netdbtype.U>:
-
-This variable holds the type used for the 1st argument to
-getnetbyaddr(). Usually, this is int or long.
-This is only useful if you have getnetbyaddr(), naturally.
-
-=item C<nm>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the nm program. After Configure runs,
-the value is reset to a plain C<nm> and is not useful.
-
-=item C<nm_opt>
-
-From F<usenm.U>:
-
-This variable holds the options that may be necessary for nm.
-
-=item C<nm_so_opt>
-
-From F<usenm.U>:
-
-This variable holds the options that may be necessary for nm
-to work on a shared library but that can not be used on an
-archive library. Currently, this is only used by Linux, where
-nm --dynamic is *required* to get symbols from an C<ELF> library which
-has been stripped, but nm --dynamic is *fatal* on an archive library.
-Maybe Linux should just always set usenm=false.
-
-=item C<nonxs_ext>
-
-From F<Extensions.U>:
-
-This variable holds a list of all non-xs extensions included
-in the package. All of them will be built.
-
-=item C<nroff>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the nroff program. After Configure runs,
-the value is reset to a plain C<nroff> and is not useful.
-
-=item C<nv_overflows_integers_at>
-
-From F<perlxv.U>:
-
-This variable gives the largest integer value that NVs can hold
-as a constant floating point expression.
-If it could not be determined, it holds the value 0.
-
-=item C<nv_preserves_uv_bits>
-
-From F<perlxv.U>:
-
-This variable indicates how many of bits type uvtype
-a variable nvtype can preserve.
-
-=item C<nveformat>
-
-From F<perlxvf.U>:
-
-This variable contains the format string used for printing
-a Perl C<NV> using %e-ish floating point format.
-
-=item C<nvEUformat>
-
-From F<perlxvf.U>:
-
-This variable contains the format string used for printing
-a Perl C<NV> using %E-ish floating point format.
-
-=item C<nvfformat>
-
-From F<perlxvf.U>:
-
-This variable confains the format string used for printing
-a Perl C<NV> using %f-ish floating point format.
-
-=item C<nvFUformat>
-
-From F<perlxvf.U>:
-
-This variable confains the format string used for printing
-a Perl C<NV> using %F-ish floating point format.
-
-=item C<nvgformat>
-
-From F<perlxvf.U>:
-
-This variable contains the format string used for printing
-a Perl C<NV> using %g-ish floating point format.
-
-=item C<nvGUformat>
-
-From F<perlxvf.U>:
-
-This variable contains the format string used for printing
-a Perl C<NV> using %G-ish floating point format.
-
-=item C<nvsize>
-
-From F<perlxv.U>:
-
-This variable is the size of an C<NV> in bytes.
-
-=item C<nvtype>
-
-From F<perlxv.U>:
-
-This variable contains the C type used for Perl's C<NV>.
-
-=back
-
-=cut
-
-=head2 o
-
-=over 4
-
-=cut
-
-=item C<o_nonblock>
-
-From F<nblock_io.U>:
-
-This variable bears the symbol value to be used during open() or fcntl()
-to turn on non-blocking I/O for a file descriptor. If you wish to switch
-between blocking and non-blocking, you may try ioctl(C<FIOSNBIO>) instead,
-but that is only supported by some devices.
-
-=item C<obj_ext>
-
-From F<Unix.U>:
-
-This is an old synonym for _o.
-
-=item C<old_pthread_create_joinable>
-
-From F<d_pthrattrj.U>:
-
-This variable defines the constant to use for creating joinable
-(aka undetached) pthreads. Unused if F<pthread.h> defines
-C<PTHREAD_CREATE_JOINABLE>. If used, possible values are
-C<PTHREAD_CREATE_UNDETACHED> and C<__UNDETACHED>.
-
-=item C<optimize>
-
-From F<ccflags.U>:
-
-This variable contains any F<optimizer/debugger> flag that should be used.
-It is up to the Makefile to use it.
-
-=item C<orderlib>
-
-From F<orderlib.U>:
-
-This variable is C<true> if the components of libraries must be ordered
-(with `lorder $* | tsort`) before placing them in an archive. Set to
-C<false> if ranlib or ar can generate random libraries.
-
-=item C<osname>
-
-From F<Oldconfig.U>:
-
-This variable contains the operating system name (e.g. sunos,
-solaris, hpux, etc.). It can be useful later on for setting
-defaults. Any spaces are replaced with underscores. It is set
-to a null string if we can't figure it out.
-
-=item C<osvers>
-
-From F<Oldconfig.U>:
-
-This variable contains the operating system version (e.g.
-4.1.3, 5.2, etc.). It is primarily used for helping select
-an appropriate hints file, but might be useful elsewhere for
-setting defaults. It is set to '' if we can't figure it out.
-We try to be flexible about how much of the version number
-to keep, e.g. if 4.1.1, 4.1.2, and 4.1.3 are essentially the
-same for this package, hints files might just be F<os_4.0> or
-F<os_4.1>, etc., not keeping separate files for each little release.
-
-=item C<otherlibdirs>
-
-From F<otherlibdirs.U>:
-
-This variable contains a colon-separated set of paths for the perl
-binary to search for additional library files or modules.
-These directories will be tacked to the end of @C<INC>.
-Perl will automatically search below each path for version-
-and architecture-specific directories. See inc_version_list
-for more details.
-A value of C< > means C<none> and is used to preserve this value
-for the next run through Configure.
-
-=back
-
-=cut
-
-=head2 p
-
-=over 4
-
-=cut
-
-=item C<package>
-
-From F<package.U>:
-
-This variable contains the name of the package being constructed.
-It is primarily intended for the use of later Configure units.
-
-=item C<pager>
-
-From F<pager.U>:
-
-This variable contains the name of the preferred pager on the system.
-Usual values are (the full pathnames of) more, less, pg, or cat.
-
-=item C<passcat>
-
-From F<nis.U>:
-
-This variable contains a command that produces the text of the
-F</etc/passwd> file. This is normally "cat F</etc/passwd>", but can be
-"ypcat passwd" when C<NIS> is used.
-On some systems, such as os390, there may be no equivalent
-command, in which case this variable is unset.
-
-=item C<patchlevel>
-
-From F<patchlevel.U>:
-
-The patchlevel level of this package.
-The value of patchlevel comes from the F<patchlevel.h> file.
-In a version number such as 5.6.1, this is the C<6>.
-In F<patchlevel.h>, this is referred to as C<PERL_VERSION>.
-
-=item C<path_sep>
-
-From F<Unix.U>:
-
-This is an old synonym for p_ in F<Head.U>, the character
-used to separate elements in the command shell search C<PATH>.
-
-=item C<perl>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the perl program. After Configure runs,
-the value is reset to a plain C<perl> and is not useful.
-
-=item C<perl5>
-
-From F<perl5.U>:
-
-This variable contains the full path (if any) to a previously
-installed F<perl5.005> or later suitable for running the script
-to determine inc_version_list.
-
-=back
-
-=cut
-
-=head2 P
-
-=over 4
-
-=cut
-
-=item C<PERL_API_REVISION>
-
-From F<patchlevel.h>:
-
-This number describes the earliest compatible C<PERL_REVISION> of
-Perl (C<compatibility> here being defined as sufficient F<binary/C<API>>
-compatibility to run C<XS> code built with the older version).
-Normally this does not change across maintenance releases.
-Please read the comment in F<patchlevel.h>.
-
-=item C<PERL_API_SUBVERSION>
-
-From F<patchlevel.h>:
-
-This number describes the earliest compatible C<PERL_SUBVERSION> of
-Perl (C<compatibility> here being defined as sufficient F<binary/C<API>>
-compatibility to run C<XS> code built with the older version).
-Normally this does not change across maintenance releases.
-Please read the comment in F<patchlevel.h>.
-
-=item C<PERL_API_VERSION>
-
-From F<patchlevel.h>:
-
-This number describes the earliest compatible C<PERL_VERSION> of
-Perl (C<compatibility> here being defined as sufficient F<binary/C<API>>
-compatibility to run C<XS> code built with the older version).
-Normally this does not change across maintenance releases.
-Please read the comment in F<patchlevel.h>.
-
-=item C<PERL_CONFIG_SH>
-
-From F<Oldsyms.U>:
-
-This is set to C<true> in F<config.sh> so that a shell script
-sourcing F<config.sh> can tell if it has been sourced already.
-
-=item C<PERL_PATCHLEVEL>
-
-From F<Oldsyms.U>:
-
-This symbol reflects the patchlevel, if available. Will usually
-come from the F<.patch> file, which is available when the perl
-source tree was fetched with rsync.
-
-=item C<perl_patchlevel>
-
-From F<patchlevel.U>:
-
-This is the Perl patch level, a numeric change identifier,
-as defined by whichever source code maintenance system
-is used to maintain the patches; currently Perforce.
-It does not correlate with the Perl version numbers or
-the maintenance versus development dichotomy except
-by also being increasing.
-
-=item C<PERL_REVISION>
-
-From F<Oldsyms.U>:
-
-In a Perl version number such as 5.6.2, this is the 5.
-This value is manually set in F<patchlevel.h>
-
-=item C<perl_static_inline>
-
-From F<d_static_inline.U>:
-
-This variable defines the C<PERL_STATIC_INLINE> symbol to
-the best-guess incantation to use for static inline functions.
-Possibilities include
-static inline (c99)
-static __inline__ (gcc -ansi)
-static __inline (C<MSVC>)
-static _inline (older C<MSVC>)
-static (c89 compilers)
-
-=item C<PERL_SUBVERSION>
-
-From F<Oldsyms.U>:
-
-In a Perl version number such as 5.6.2, this is the 2.
-Values greater than 50 represent potentially unstable
-development subversions.
-This value is manually set in F<patchlevel.h>
-
-=item C<PERL_VERSION>
-
-From F<Oldsyms.U>:
-
-In a Perl version number such as 5.6.2, this is the 6.
-This value is manually set in F<patchlevel.h>
-
-=item C<perladmin>
-
-From F<perladmin.U>:
-
-Electronic mail address of the perl5 administrator.
-
-=item C<perllibs>
-
-From F<End.U>:
-
-The list of libraries needed by Perl only (any libraries needed
-by extensions only will by dropped, if using dynamic loading).
-
-=item C<perlpath>
-
-From F<perlpath.U>:
-
-This variable contains the eventual value of the C<PERLPATH> symbol,
-which contains the name of the perl interpreter to be used in
-shell scripts and in the "eval C<exec>" idiom. This variable is
-not necessarily the pathname of the file containing the perl
-interpreter; you must append the executable extension (_exe) if
-it is not already present. Note that Perl code that runs during
-the Perl build process cannot reference this variable, as Perl
-may not have been installed, or even if installed, may be a
-different version of Perl.
-
-=item C<pg>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the pg program. After Configure runs,
-the value is reset to a plain C<pg> and is not useful.
-
-=item C<phostname>
-
-From F<myhostname.U>:
-
-This variable contains the eventual value of the C<PHOSTNAME> symbol,
-which is a command that can be fed to popen() to get the host name.
-The program should probably not presume that the domain is or isn't
-there already.
-
-=item C<pidtype>
-
-From F<pidtype.U>:
-
-This variable defines C<PIDTYPE> to be something like pid_t, int,
-ushort, or whatever type is used to declare process ids in the kernel.
-
-=item C<plibpth>
-
-From F<libpth.U>:
-
-Holds the private path used by Configure to find out the libraries.
-Its value is prepend to libpth. This variable takes care of special
-machines, like the mips. Usually, it should be empty.
-
-=item C<pmake>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<pr>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<prefix>
-
-From F<prefix.U>:
-
-This variable holds the name of the directory below which the
-user will install the package. Usually, this is F</usr/local>, and
-executables go in F</usr/local/bin>, library stuff in F</usr/local/lib>,
-man pages in F</usr/local/man>, etc. It is only used to set defaults
-for things in F<bin.U>, F<mansrc.U>, F<privlib.U>, or F<scriptdir.U>.
-
-=item C<prefixexp>
-
-From F<prefix.U>:
-
-This variable holds the full absolute path of the directory below
-which the user will install the package. Derived from prefix.
-
-=item C<privlib>
-
-From F<privlib.U>:
-
-This variable contains the eventual value of the C<PRIVLIB> symbol,
-which is the name of the private library for this package. It may
-have a F<~> on the front. It is up to the makefile to eventually create
-this directory while performing installation (with F<~> substitution).
-
-=item C<privlibexp>
-
-From F<privlib.U>:
-
-This variable is the F<~name> expanded version of privlib, so that you
-may use it directly in Makefiles or shell scripts.
-
-=item C<procselfexe>
-
-From F<d_procselfexe.U>:
-
-If d_procselfexe is defined, $procselfexe is the filename
-of the symbolic link pointing to the absolute pathname of
-the executing program.
-
-=item C<prototype>
-
-From F<prototype.U>:
-
-This variable holds the eventual value of C<CAN_PROTOTYPE>, which
-indicates the C compiler can handle funciton prototypes.
-
-=item C<ptrsize>
-
-From F<ptrsize.U>:
-
-This variable contains the value of the C<PTRSIZE> symbol, which
-indicates to the C program how many bytes there are in a pointer.
-
-=back
-
-=cut
-
-=head2 q
-
-=over 4
-
-=cut
-
-=item C<quadkind>
-
-From F<quadtype.U>:
-
-This variable, if defined, encodes the type of a quad:
-1 = int, 2 = long, 3 = long long, 4 = int64_t.
-
-=item C<quadtype>
-
-From F<quadtype.U>:
-
-This variable defines Quad_t to be something like long, int,
-long long, int64_t, or whatever type is used for 64-bit integers.
-
-=back
-
-=cut
-
-=head2 r
-
-=over 4
-
-=cut
-
-=item C<randbits>
-
-From F<randfunc.U>:
-
-Indicates how many bits are produced by the function used to
-generate normalized random numbers.
-
-=item C<randfunc>
-
-From F<randfunc.U>:
-
-Indicates the name of the random number function to use.
-Values include drand48, random, and rand. In C programs,
-the C<Drand01> macro is defined to generate uniformly distributed
-random numbers over the range [0., 1.[ (see drand01 and nrand).
-
-=item C<random_r_proto>
-
-From F<d_random_r.U>:
-
-This variable encodes the prototype of random_r.
-It is zero if d_random_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_random_r
-is defined.
-
-=item C<randseedtype>
-
-From F<randfunc.U>:
-
-Indicates the type of the argument of the seedfunc.
-
-=item C<ranlib>
-
-From F<orderlib.U>:
-
-This variable is set to the pathname of the ranlib program, if it is
-needed to generate random libraries. Set to C<:> if ar can generate
-random libraries or if random libraries are not supported
-
-=item C<rd_nodata>
-
-From F<nblock_io.U>:
-
-This variable holds the return code from read() when no data is
-present. It should be -1, but some systems return 0 when C<O_NDELAY> is
-used, which is a shame because you cannot make the difference between
-no data and an F<EOF.>. Sigh!
-
-=item C<readdir64_r_proto>
-
-From F<d_readdir64_r.U>:
-
-This variable encodes the prototype of readdir64_r.
-It is zero if d_readdir64_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_readdir64_r
-is defined.
-
-=item C<readdir_r_proto>
-
-From F<d_readdir_r.U>:
-
-This variable encodes the prototype of readdir_r.
-It is zero if d_readdir_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_readdir_r
-is defined.
-
-=item C<revision>
-
-From F<patchlevel.U>:
-
-The value of revision comes from the F<patchlevel.h> file.
-In a version number such as 5.6.1, this is the C<5>.
-In F<patchlevel.h>, this is referred to as C<PERL_REVISION>.
-
-=item C<rm>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the rm program. After Configure runs,
-the value is reset to a plain C<rm> and is not useful.
-
-=item C<rm_try>
-
-From F<Unix.U>:
-
-This is a cleanup variable for try test programs.
-Internal Configure use only.
-
-=item C<rmail>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<run>
-
-From F<Cross.U>:
-
-This variable contains the command used by Configure
-to copy and execute a cross-compiled executable in the
-target host. Useful and available only during Perl build.
-Empty string '' if not cross-compiling.
-
-=item C<runnm>
-
-From F<usenm.U>:
-
-This variable contains C<true> or C<false> depending whether the
-nm extraction should be performed or not, according to the value
-of usenm and the flags on the Configure command line.
-
-=back
-
-=cut
-
-=head2 s
-
-=over 4
-
-=cut
-
-=item C<sched_yield>
-
-From F<d_pthread_y.U>:
-
-This variable defines the way to yield the execution
-of the current thread.
-
-=item C<scriptdir>
-
-From F<scriptdir.U>:
-
-This variable holds the name of the directory in which the user wants
-to put publicly scripts for the package in question. It is either
-the same directory as for binaries, or a special one that can be
-mounted across different architectures, like F</usr/share>. Programs
-must be prepared to deal with F<~name> expansion.
-
-=item C<scriptdirexp>
-
-From F<scriptdir.U>:
-
-This variable is the same as scriptdir, but is filename expanded
-at configuration time, for programs not wanting to bother with it.
-
-=item C<sed>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the sed program. After Configure runs,
-the value is reset to a plain C<sed> and is not useful.
-
-=item C<seedfunc>
-
-From F<randfunc.U>:
-
-Indicates the random number generating seed function.
-Values include srand48, srandom, and srand.
-
-=item C<selectminbits>
-
-From F<selectminbits.U>:
-
-This variable holds the minimum number of bits operated by select.
-That is, if you do select(n, ...), how many bits at least will be
-cleared in the masks if some activity is detected. Usually this
-is either n or 32*ceil(F<n/32>), especially many little-endians do
-the latter. This is only useful if you have select(), naturally.
-
-=item C<selecttype>
-
-From F<selecttype.U>:
-
-This variable holds the type used for the 2nd, 3rd, and 4th
-arguments to select. Usually, this is C<fd_set *>, if C<HAS_FD_SET>
-is defined, and C<int *> otherwise. This is only useful if you
-have select(), naturally.
-
-=item C<sendmail>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<setgrent_r_proto>
-
-From F<d_setgrent_r.U>:
-
-This variable encodes the prototype of setgrent_r.
-It is zero if d_setgrent_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_setgrent_r
-is defined.
-
-=item C<sethostent_r_proto>
-
-From F<d_sethostent_r.U>:
-
-This variable encodes the prototype of sethostent_r.
-It is zero if d_sethostent_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_sethostent_r
-is defined.
-
-=item C<setlocale_r_proto>
-
-From F<d_setlocale_r.U>:
-
-This variable encodes the prototype of setlocale_r.
-It is zero if d_setlocale_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_setlocale_r
-is defined.
-
-=item C<setnetent_r_proto>
-
-From F<d_setnetent_r.U>:
-
-This variable encodes the prototype of setnetent_r.
-It is zero if d_setnetent_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_setnetent_r
-is defined.
-
-=item C<setprotoent_r_proto>
-
-From F<d_setprotoent_r.U>:
-
-This variable encodes the prototype of setprotoent_r.
-It is zero if d_setprotoent_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_setprotoent_r
-is defined.
-
-=item C<setpwent_r_proto>
-
-From F<d_setpwent_r.U>:
-
-This variable encodes the prototype of setpwent_r.
-It is zero if d_setpwent_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_setpwent_r
-is defined.
-
-=item C<setservent_r_proto>
-
-From F<d_setservent_r.U>:
-
-This variable encodes the prototype of setservent_r.
-It is zero if d_setservent_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_setservent_r
-is defined.
-
-=item C<sGMTIME_max>
-
-From F<time_size.U>:
-
-This variable defines the maximum value of the time_t offset that
-the system function gmtime () accepts
-
-=item C<sGMTIME_min>
-
-From F<time_size.U>:
-
-This variable defines the minimum value of the time_t offset that
-the system function gmtime () accepts
-
-=item C<sh>
-
-From F<sh.U>:
-
-This variable contains the full pathname of the shell used
-on this system to execute Bourne shell scripts. Usually, this will be
-F</bin/sh>, though it's possible that some systems will have F</bin/ksh>,
-F</bin/pdksh>, F</bin/ash>, F</bin/bash>, or even something such as
-D:F</bin/sh.exe>.
-This unit comes before F<Options.U>, so you can't set sh with a C<-D>
-option, though you can override this (and startsh)
-with C<-O -Dsh=F</bin/whatever> -Dstartsh=whatever>
-
-=item C<shar>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<sharpbang>
-
-From F<spitshell.U>:
-
-This variable contains the string #! if this system supports that
-construct.
-
-=item C<shmattype>
-
-From F<d_shmat.U>:
-
-This symbol contains the type of pointer returned by shmat().
-It can be C<void *> or C<char *>.
-
-=item C<shortsize>
-
-From F<intsize.U>:
-
-This variable contains the value of the C<SHORTSIZE> symbol which
-indicates to the C program how many bytes there are in a short.
-
-=item C<shrpenv>
-
-From F<libperl.U>:
-
-If the user builds a shared F<libperl.so>, then we need to tell the
-C<perl> executable where it will be able to find the installed F<libperl.so>.
-One way to do this on some systems is to set the environment variable
-C<LD_RUN_PATH> to the directory that will be the final location of the
-shared F<libperl.so>. The makefile can use this with something like
-$shrpenv $(C<CC>) -o perl F<perlmain.o> $libperl $libs
-Typical values are
-shrpenv="env C<LD_RUN_PATH>=F<$archlibexp/C<CORE>>"
-or
-shrpenv=''
-See the main perl F<Makefile.SH> for actual working usage.
-Alternatively, we might be able to use a command line option such
-as -R F<$archlibexp/C<CORE>> (Solaris) or -Wl,-rpath
-F<$archlibexp/C<CORE>> (Linux).
-
-=item C<shsharp>
-
-From F<spitshell.U>:
-
-This variable tells further Configure units whether your sh can
-handle # comments.
-
-=item C<sig_count>
-
-From F<sig_name.U>:
-
-This variable holds a number larger than the largest valid
-signal number. This is usually the same as the C<NSIG> macro.
-
-=item C<sig_name>
-
-From F<sig_name.U>:
-
-This variable holds the signal names, space separated. The leading
-C<SIG> in signal name is removed. A C<ZERO> is prepended to the list.
-This is currently not used, sig_name_init is used instead.
-
-=item C<sig_name_init>
-
-From F<sig_name.U>:
-
-This variable holds the signal names, enclosed in double quotes and
-separated by commas, suitable for use in the C<SIG_NAME> definition
-below. A C<ZERO> is prepended to the list, and the list is
-terminated with a plain 0. The leading C<SIG> in signal names
-is removed. See sig_num.
-
-=item C<sig_num>
-
-From F<sig_name.U>:
-
-This variable holds the signal numbers, space separated. A C<ZERO> is
-prepended to the list (corresponding to the fake C<SIGZERO>).
-Those numbers correspond to the value of the signal listed
-in the same place within the sig_name list.
-This is currently not used, sig_num_init is used instead.
-
-=item C<sig_num_init>
-
-From F<sig_name.U>:
-
-This variable holds the signal numbers, enclosed in double quotes and
-separated by commas, suitable for use in the C<SIG_NUM> definition
-below. A C<ZERO> is prepended to the list, and the list is
-terminated with a plain 0.
-
-=item C<sig_size>
-
-From F<sig_name.U>:
-
-This variable contains the number of elements of the sig_name
-and sig_num arrays.
-
-=item C<signal_t>
-
-From F<d_voidsig.U>:
-
-This variable holds the type of the signal handler (void or int).
-
-=item C<sitearch>
-
-From F<sitearch.U>:
-
-This variable contains the eventual value of the C<SITEARCH> symbol,
-which is the name of the private library for this package. It may
-have a F<~> on the front. It is up to the makefile to eventually create
-this directory while performing installation (with F<~> substitution).
-The standard distribution will put nothing in this directory.
-After perl has been installed, users may install their own local
-architecture-dependent modules in this directory with
-MakeMaker F<Makefile.PL>
-or equivalent. See C<INSTALL> for details.
-
-=item C<sitearchexp>
-
-From F<sitearch.U>:
-
-This variable is the F<~name> expanded version of sitearch, so that you
-may use it directly in Makefiles or shell scripts.
-
-=item C<sitebin>
-
-From F<sitebin.U>:
-
-This variable holds the name of the directory in which the user wants
-to put add-on publicly executable files for the package in question. It
-is most often a local directory such as F</usr/local/bin>. Programs using
-this variable must be prepared to deal with F<~name> substitution.
-The standard distribution will put nothing in this directory.
-After perl has been installed, users may install their own local
-executables in this directory with
-MakeMaker F<Makefile.PL>
-or equivalent. See C<INSTALL> for details.
-
-=item C<sitebinexp>
-
-From F<sitebin.U>:
-
-This is the same as the sitebin variable, but is filename expanded at
-configuration time, for use in your makefiles.
-
-=item C<sitehtml1dir>
-
-From F<sitehtml1dir.U>:
-
-This variable contains the name of the directory in which site-specific
-html source pages are to be put. It is the responsibility of the
-F<Makefile.SH> to get the value of this into the proper command.
-You must be prepared to do the F<~name> expansion yourself.
-The standard distribution will put nothing in this directory.
-After perl has been installed, users may install their own local
-html pages in this directory with
-MakeMaker F<Makefile.PL>
-or equivalent. See C<INSTALL> for details.
-
-=item C<sitehtml1direxp>
-
-From F<sitehtml1dir.U>:
-
-This variable is the same as the sitehtml1dir variable, but is filename
-expanded at configuration time, for convenient use in makefiles.
-
-=item C<sitehtml3dir>
-
-From F<sitehtml3dir.U>:
-
-This variable contains the name of the directory in which site-specific
-library html source pages are to be put. It is the responsibility of the
-F<Makefile.SH> to get the value of this into the proper command.
-You must be prepared to do the F<~name> expansion yourself.
-The standard distribution will put nothing in this directory.
-After perl has been installed, users may install their own local
-library html pages in this directory with
-MakeMaker F<Makefile.PL>
-or equivalent. See C<INSTALL> for details.
-
-=item C<sitehtml3direxp>
-
-From F<sitehtml3dir.U>:
-
-This variable is the same as the sitehtml3dir variable, but is filename
-expanded at configuration time, for convenient use in makefiles.
-
-=item C<sitelib>
-
-From F<sitelib.U>:
-
-This variable contains the eventual value of the C<SITELIB> symbol,
-which is the name of the private library for this package. It may
-have a F<~> on the front. It is up to the makefile to eventually create
-this directory while performing installation (with F<~> substitution).
-The standard distribution will put nothing in this directory.
-After perl has been installed, users may install their own local
-architecture-independent modules in this directory with
-MakeMaker F<Makefile.PL>
-or equivalent. See C<INSTALL> for details.
-
-=item C<sitelib_stem>
-
-From F<sitelib.U>:
-
-This variable is $sitelibexp with any trailing version-specific component
-removed. The elements in inc_version_list (F<inc_version_list.U>) can
-be tacked onto this variable to generate a list of directories to search.
-
-=item C<sitelibexp>
-
-From F<sitelib.U>:
-
-This variable is the F<~name> expanded version of sitelib, so that you
-may use it directly in Makefiles or shell scripts.
-
-=item C<siteman1dir>
-
-From F<siteman1dir.U>:
-
-This variable contains the name of the directory in which site-specific
-manual source pages are to be put. It is the responsibility of the
-F<Makefile.SH> to get the value of this into the proper command.
-You must be prepared to do the F<~name> expansion yourself.
-The standard distribution will put nothing in this directory.
-After perl has been installed, users may install their own local
-man1 pages in this directory with
-MakeMaker F<Makefile.PL>
-or equivalent. See C<INSTALL> for details.
-
-=item C<siteman1direxp>
-
-From F<siteman1dir.U>:
-
-This variable is the same as the siteman1dir variable, but is filename
-expanded at configuration time, for convenient use in makefiles.
-
-=item C<siteman3dir>
-
-From F<siteman3dir.U>:
-
-This variable contains the name of the directory in which site-specific
-library man source pages are to be put. It is the responsibility of the
-F<Makefile.SH> to get the value of this into the proper command.
-You must be prepared to do the F<~name> expansion yourself.
-The standard distribution will put nothing in this directory.
-After perl has been installed, users may install their own local
-man3 pages in this directory with
-MakeMaker F<Makefile.PL>
-or equivalent. See C<INSTALL> for details.
-
-=item C<siteman3direxp>
-
-From F<siteman3dir.U>:
-
-This variable is the same as the siteman3dir variable, but is filename
-expanded at configuration time, for convenient use in makefiles.
-
-=item C<siteprefix>
-
-From F<siteprefix.U>:
-
-This variable holds the full absolute path of the directory below
-which the user will install add-on packages.
-See C<INSTALL> for usage and examples.
-
-=item C<siteprefixexp>
-
-From F<siteprefix.U>:
-
-This variable holds the full absolute path of the directory below
-which the user will install add-on packages. Derived from siteprefix.
-
-=item C<sitescript>
-
-From F<sitescript.U>:
-
-This variable holds the name of the directory in which the user wants
-to put add-on publicly executable files for the package in question. It
-is most often a local directory such as F</usr/local/bin>. Programs using
-this variable must be prepared to deal with F<~name> substitution.
-The standard distribution will put nothing in this directory.
-After perl has been installed, users may install their own local
-scripts in this directory with
-MakeMaker F<Makefile.PL>
-or equivalent. See C<INSTALL> for details.
-
-=item C<sitescriptexp>
-
-From F<sitescript.U>:
-
-This is the same as the sitescript variable, but is filename expanded at
-configuration time, for use in your makefiles.
-
-=item C<sizesize>
-
-From F<sizesize.U>:
-
-This variable contains the size of a sizetype in bytes.
-
-=item C<sizetype>
-
-From F<sizetype.U>:
-
-This variable defines sizetype to be something like size_t,
-unsigned long, or whatever type is used to declare length
-parameters for string functions.
-
-=item C<sleep>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<sLOCALTIME_max>
-
-From F<time_size.U>:
-
-This variable defines the maximum value of the time_t offset that
-the system function localtime () accepts
-
-=item C<sLOCALTIME_min>
-
-From F<time_size.U>:
-
-This variable defines the minimum value of the time_t offset that
-the system function localtime () accepts
-
-=item C<smail>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<so>
-
-From F<so.U>:
-
-This variable holds the extension used to identify shared libraries
-(also known as shared objects) on the system. Usually set to C<so>.
-
-=item C<sockethdr>
-
-From F<d_socket.U>:
-
-This variable has any cpp C<-I> flags needed for socket support.
-
-=item C<socketlib>
-
-From F<d_socket.U>:
-
-This variable has the names of any libraries needed for socket support.
-
-=item C<socksizetype>
-
-From F<socksizetype.U>:
-
-This variable holds the type used for the size argument
-for various socket calls like accept. Usual values include
-socklen_t, size_t, and int.
-
-=item C<sort>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the sort program. After Configure runs,
-the value is reset to a plain C<sort> and is not useful.
-
-=item C<spackage>
-
-From F<package.U>:
-
-This variable contains the name of the package being constructed,
-with the first letter uppercased, F<i.e>. suitable for starting
-sentences.
-
-=item C<spitshell>
-
-From F<spitshell.U>:
-
-This variable contains the command necessary to spit out a runnable
-shell on this system. It is either cat or a grep C<-v> for # comments.
-
-=item C<sPRId64>
-
-From F<quadfio.U>:
-
-This variable, if defined, contains the string used by stdio to
-format 64-bit decimal numbers (format C<d>) for output.
-
-=item C<sPRIeldbl>
-
-From F<longdblfio.U>:
-
-This variable, if defined, contains the string used by stdio to
-format long doubles (format C<e>) for output.
-
-=item C<sPRIEUldbl>
-
-From F<longdblfio.U>:
-
-This variable, if defined, contains the string used by stdio to
-format long doubles (format C<E>) for output.
-The C<U> in the name is to separate this from sPRIeldbl so that even
-case-blind systems can see the difference.
-
-=item C<sPRIfldbl>
-
-From F<longdblfio.U>:
-
-This variable, if defined, contains the string used by stdio to
-format long doubles (format C<f>) for output.
-
-=item C<sPRIFUldbl>
-
-From F<longdblfio.U>:
-
-This variable, if defined, contains the string used by stdio to
-format long doubles (format C<F>) for output.
-The C<U> in the name is to separate this from sPRIfldbl so that even
-case-blind systems can see the difference.
-
-=item C<sPRIgldbl>
-
-From F<longdblfio.U>:
-
-This variable, if defined, contains the string used by stdio to
-format long doubles (format C<g>) for output.
-
-=item C<sPRIGUldbl>
-
-From F<longdblfio.U>:
-
-This variable, if defined, contains the string used by stdio to
-format long doubles (format C<G>) for output.
-The C<U> in the name is to separate this from sPRIgldbl so that even
-case-blind systems can see the difference.
-
-=item C<sPRIi64>
-
-From F<quadfio.U>:
-
-This variable, if defined, contains the string used by stdio to
-format 64-bit decimal numbers (format C<i>) for output.
-
-=item C<sPRIo64>
-
-From F<quadfio.U>:
-
-This variable, if defined, contains the string used by stdio to
-format 64-bit octal numbers (format C<o>) for output.
-
-=item C<sPRIu64>
-
-From F<quadfio.U>:
-
-This variable, if defined, contains the string used by stdio to
-format 64-bit unsigned decimal numbers (format C<u>) for output.
-
-=item C<sPRIx64>
-
-From F<quadfio.U>:
-
-This variable, if defined, contains the string used by stdio to
-format 64-bit hexadecimal numbers (format C<x>) for output.
-
-=item C<sPRIXU64>
-
-From F<quadfio.U>:
-
-This variable, if defined, contains the string used by stdio to
-format 64-bit hExADECimAl numbers (format C<X>) for output.
-The C<U> in the name is to separate this from sPRIx64 so that even
-case-blind systems can see the difference.
-
-=item C<srand48_r_proto>
-
-From F<d_srand48_r.U>:
-
-This variable encodes the prototype of srand48_r.
-It is zero if d_srand48_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_srand48_r
-is defined.
-
-=item C<srandom_r_proto>
-
-From F<d_srandom_r.U>:
-
-This variable encodes the prototype of srandom_r.
-It is zero if d_srandom_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_srandom_r
-is defined.
-
-=item C<src>
-
-From F<src.U>:
-
-This variable holds the (possibly relative) path of the package source.
-It is up to the Makefile to use this variable and set C<VPATH> accordingly
-to find the sources remotely. Use $pkgsrc to have an absolute path.
-
-=item C<sSCNfldbl>
-
-From F<longdblfio.U>:
-
-This variable, if defined, contains the string used by stdio to
-format long doubles (format C<f>) for input.
-
-=item C<ssizetype>
-
-From F<ssizetype.U>:
-
-This variable defines ssizetype to be something like ssize_t,
-long or int. It is used by functions that return a count
-of bytes or an error condition. It must be a signed type.
-We will pick a type such that sizeof(SSize_t) == sizeof(Size_t).
-
-=item C<st_ino_sign>
-
-From F<st_ino_def.U>:
-
-This variable contains the signedness of struct stat's st_ino.
-1 for unsigned, -1 for signed.
-
-=item C<st_ino_size>
-
-From F<st_ino_def.U>:
-
-This variable contains the size of struct stat's st_ino in bytes.
-
-=item C<startperl>
-
-From F<startperl.U>:
-
-This variable contains the string to put on the front of a perl
-script to make sure (hopefully) that it runs with perl and not some
-shell. Of course, that leading line must be followed by the classical
-perl idiom:
-eval 'exec perl -S $0 ${1+C<$@>}'
-if $running_under_some_shell;
-to guarantee perl startup should the shell execute the script. Note
-that this magic incantation is not understood by csh.
-
-=item C<startsh>
-
-From F<startsh.U>:
-
-This variable contains the string to put on the front of a shell
-script to make sure (hopefully) that it runs with sh and not some
-other shell.
-
-=item C<static_ext>
-
-From F<Extensions.U>:
-
-This variable holds a list of C<XS> extension files we want to
-link statically into the package. It is used by Makefile.
-
-=item C<stdchar>
-
-From F<stdchar.U>:
-
-This variable conditionally defines C<STDCHAR> to be the type of char
-used in F<stdio.h>. It has the values "unsigned char" or C<char>.
-
-=item C<stdio_base>
-
-From F<d_stdstdio.U>:
-
-This variable defines how, given a C<FILE> pointer, fp, to access the
-_base field (or equivalent) of F<stdio.h>'s C<FILE> structure. This will
-be used to define the macro FILE_base(fp).
-
-=item C<stdio_bufsiz>
-
-From F<d_stdstdio.U>:
-
-This variable defines how, given a C<FILE> pointer, fp, to determine
-the number of bytes store in the I/O buffer pointer to by the
-_base field (or equivalent) of F<stdio.h>'s C<FILE> structure. This will
-be used to define the macro FILE_bufsiz(fp).
-
-=item C<stdio_cnt>
-
-From F<d_stdstdio.U>:
-
-This variable defines how, given a C<FILE> pointer, fp, to access the
-_cnt field (or equivalent) of F<stdio.h>'s C<FILE> structure. This will
-be used to define the macro FILE_cnt(fp).
-
-=item C<stdio_filbuf>
-
-From F<d_stdstdio.U>:
-
-This variable defines how, given a C<FILE> pointer, fp, to tell
-stdio to refill its internal buffers (?). This will
-be used to define the macro FILE_filbuf(fp).
-
-=item C<stdio_ptr>
-
-From F<d_stdstdio.U>:
-
-This variable defines how, given a C<FILE> pointer, fp, to access the
-_ptr field (or equivalent) of F<stdio.h>'s C<FILE> structure. This will
-be used to define the macro FILE_ptr(fp).
-
-=item C<stdio_stream_array>
-
-From F<stdio_streams.U>:
-
-This variable tells the name of the array holding the stdio streams.
-Usual values include _iob, __iob, and __sF.
-
-=item C<strerror_r_proto>
-
-From F<d_strerror_r.U>:
-
-This variable encodes the prototype of strerror_r.
-It is zero if d_strerror_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_strerror_r
-is defined.
-
-=item C<strings>
-
-From F<i_string.U>:
-
-This variable holds the full path of the string header that will be
-used. Typically F</usr/include/string.h> or F</usr/include/strings.h>.
-
-=item C<submit>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<subversion>
-
-From F<patchlevel.U>:
-
-The subversion level of this package.
-The value of subversion comes from the F<patchlevel.h> file.
-In a version number such as 5.6.1, this is the C<1>.
-In F<patchlevel.h>, this is referred to as C<PERL_SUBVERSION>.
-This is unique to perl.
-
-=item C<sysman>
-
-From F<sysman.U>:
-
-This variable holds the place where the manual is located on this
-system. It is not the place where the user wants to put his manual
-pages. Rather it is the place where Configure may look to find manual
-for unix commands (section 1 of the manual usually). See mansrc.
-
-=back
-
-=cut
-
-=head2 t
-
-=over 4
-
-=cut
-
-=item C<tail>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<tar>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<targetarch>
-
-From F<Cross.U>:
-
-If cross-compiling, this variable contains the target architecture.
-If not, this will be empty.
-
-=item C<tbl>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<tee>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<test>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the test program. After Configure runs,
-the value is reset to a plain C<test> and is not useful.
-
-=item C<timeincl>
-
-From F<i_time.U>:
-
-This variable holds the full path of the included time header(s).
-
-=item C<timetype>
-
-From F<d_time.U>:
-
-This variable holds the type returned by time(). It can be long,
-or time_t on C<BSD> sites (in which case <sys/types.h> should be
-included). Anyway, the type Time_t should be used.
-
-=item C<tmpnam_r_proto>
-
-From F<d_tmpnam_r.U>:
-
-This variable encodes the prototype of tmpnam_r.
-It is zero if d_tmpnam_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_tmpnam_r
-is defined.
-
-=item C<to>
-
-From F<Cross.U>:
-
-This variable contains the command used by Configure
-to copy to from the target host. Useful and available
-only during Perl build.
-The string C<:> if not cross-compiling.
-
-=item C<touch>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the touch program. After Configure runs,
-the value is reset to a plain C<touch> and is not useful.
-
-=item C<tr>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the tr program. After Configure runs,
-the value is reset to a plain C<tr> and is not useful.
-
-=item C<trnl>
-
-From F<trnl.U>:
-
-This variable contains the value to be passed to the tr(1)
-command to transliterate a newline. Typical values are
-C<\012> and C<\n>. This is needed for C<EBCDIC> systems where
-newline is not necessarily C<\012>.
-
-=item C<troff>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<ttyname_r_proto>
-
-From F<d_ttyname_r.U>:
-
-This variable encodes the prototype of ttyname_r.
-It is zero if d_ttyname_r is undef, and one of the
-C<REENTRANT_PROTO_T_ABC> macros of F<reentr.h> if d_ttyname_r
-is defined.
-
-=back
-
-=cut
-
-=head2 u
-
-=over 4
-
-=cut
-
-=item C<u16size>
-
-From F<perlxv.U>:
-
-This variable is the size of an U16 in bytes.
-
-=item C<u16type>
-
-From F<perlxv.U>:
-
-This variable contains the C type used for Perl's U16.
-
-=item C<u32size>
-
-From F<perlxv.U>:
-
-This variable is the size of an U32 in bytes.
-
-=item C<u32type>
-
-From F<perlxv.U>:
-
-This variable contains the C type used for Perl's U32.
-
-=item C<u64size>
-
-From F<perlxv.U>:
-
-This variable is the size of an U64 in bytes.
-
-=item C<u64type>
-
-From F<perlxv.U>:
-
-This variable contains the C type used for Perl's U64.
-
-=item C<u8size>
-
-From F<perlxv.U>:
-
-This variable is the size of an U8 in bytes.
-
-=item C<u8type>
-
-From F<perlxv.U>:
-
-This variable contains the C type used for Perl's U8.
-
-=item C<uidformat>
-
-From F<uidf.U>:
-
-This variable contains the format string used for printing a Uid_t.
-
-=item C<uidsign>
-
-From F<uidsign.U>:
-
-This variable contains the signedness of a uidtype.
-1 for unsigned, -1 for signed.
-
-=item C<uidsize>
-
-From F<uidsize.U>:
-
-This variable contains the size of a uidtype in bytes.
-
-=item C<uidtype>
-
-From F<uidtype.U>:
-
-This variable defines Uid_t to be something like uid_t, int,
-ushort, or whatever type is used to declare user ids in the kernel.
-
-=item C<uname>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the uname program. After Configure runs,
-the value is reset to a plain C<uname> and is not useful.
-
-=item C<uniq>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the uniq program. After Configure runs,
-the value is reset to a plain C<uniq> and is not useful.
-
-=item C<uquadtype>
-
-From F<quadtype.U>:
-
-This variable defines Uquad_t to be something like unsigned long,
-unsigned int, unsigned long long, uint64_t, or whatever type is
-used for 64-bit integers.
-
-=item C<use5005threads>
-
-From F<usethreads.U>:
-
-This variable conditionally defines the USE_5005THREADS symbol,
-and indicates that Perl should be built to use the 5.005-based
-threading implementation. Only valid up to 5.8.x.
-
-=item C<use64bitall>
-
-From F<use64bits.U>:
-
-This variable conditionally defines the USE_64_BIT_ALL symbol,
-and indicates that 64-bit integer types should be used
-when available. The maximal possible
-64-bitness is employed: LP64 or ILP64, meaning that you will
-be able to use more than 2 gigabytes of memory. This mode is
-even more binary incompatible than USE_64_BIT_INT. You may not
-be able to run the resulting executable in a 32-bit C<CPU> at all or
-you may need at least to reboot your C<OS> to 64-bit mode.
-
-=item C<use64bitint>
-
-From F<use64bits.U>:
-
-This variable conditionally defines the USE_64_BIT_INT symbol,
-and indicates that 64-bit integer types should be used
-when available. The minimal possible 64-bitness
-is employed, just enough to get 64-bit integers into Perl.
-This may mean using for example "long longs", while your memory
-may still be limited to 2 gigabytes.
-
-=item C<usecrosscompile>
-
-From F<Cross.U>:
-
-This variable conditionally defines the C<USE_CROSS_COMPILE> symbol,
-and indicates that Perl has been cross-compiled.
-
-=item C<usedevel>
-
-From F<Devel.U>:
-
-This variable indicates that Perl was configured with development
-features enabled. This should not be done for production builds.
-
-=item C<usedl>
-
-From F<dlsrc.U>:
-
-This variable indicates if the system supports dynamic
-loading of some sort. See also dlsrc and dlobj.
-
-=item C<usedtrace>
-
-From F<usedtrace.U>:
-
-This variable indicates whether we are compiling with dtrace
-support. See also dtrace.
-
-=item C<usefaststdio>
-
-From F<usefaststdio.U>:
-
-This variable conditionally defines the C<USE_FAST_STDIO> symbol,
-and indicates that Perl should be built to use C<fast stdio>.
-Defaults to define in Perls 5.8 and earlier, to undef later.
-
-=item C<useithreads>
-
-From F<usethreads.U>:
-
-This variable conditionally defines the C<USE_ITHREADS> symbol,
-and indicates that Perl should be built to use the interpreter-based
-threading implementation.
-
-=item C<usekernprocpathname>
-
-From F<usekernprocpathname.U>:
-
-This variable, indicates that we can use sysctl with
-C<KERN_PROC_PATHNAME> to get a full path for the executable, and hence
-convert $^X to an absolute path.
-
-=item C<uselargefiles>
-
-From F<uselfs.U>:
-
-This variable conditionally defines the C<USE_LARGE_FILES> symbol,
-and indicates that large file interfaces should be used when
-available.
-
-=item C<uselongdouble>
-
-From F<uselongdbl.U>:
-
-This variable conditionally defines the C<USE_LONG_DOUBLE> symbol,
-and indicates that long doubles should be used when available.
-
-=item C<usemallocwrap>
-
-From F<mallocsrc.U>:
-
-This variable contains y if we are wrapping malloc to prevent
-integer overflow during size calculations.
-
-=item C<usemorebits>
-
-From F<usemorebits.U>:
-
-This variable conditionally defines the C<USE_MORE_BITS> symbol,
-and indicates that explicit 64-bit interfaces and long doubles
-should be used when available.
-
-=item C<usemultiplicity>
-
-From F<usemultiplicity.U>:
-
-This variable conditionally defines the C<MULTIPLICITY> symbol,
-and indicates that Perl should be built to use multiplicity.
-
-=item C<usemymalloc>
-
-From F<mallocsrc.U>:
-
-This variable contains y if the malloc that comes with this package
-is desired over the system's version of malloc. People often include
-special versions of malloc for efficiency, but such versions are often
-less portable. See also mallocsrc and mallocobj.
-If this is C<y>, then -lmalloc is removed from $libs.
-
-=item C<usenm>
-
-From F<usenm.U>:
-
-This variable contains C<true> or C<false> depending whether the
-nm extraction is wanted or not.
-
-=item C<usensgetexecutablepath>
-
-From F<usensgetexecutablepath.U>:
-
-This symbol, if defined, indicates that we can use _NSGetExecutablePath
-and realpath to get a full path for the executable, and hence convert
-$^X to an absolute path.
-
-=item C<useopcode>
-
-From F<Extensions.U>:
-
-This variable holds either C<true> or C<false> to indicate
-whether the Opcode extension should be used. The sole
-use for this currently is to allow an easy mechanism
-for users to skip the Opcode extension from the Configure
-command line.
-
-=item C<useperlio>
-
-From F<useperlio.U>:
-
-This variable conditionally defines the C<USE_PERLIO> symbol,
-and indicates that the PerlIO abstraction should be
-used throughout.
-
-=item C<useposix>
-
-From F<Extensions.U>:
-
-This variable holds either C<true> or C<false> to indicate
-whether the C<POSIX> extension should be used. The sole
-use for this currently is to allow an easy mechanism
-for hints files to indicate that C<POSIX> will not compile
-on a particular system.
-
-=item C<usereentrant>
-
-From F<usethreads.U>:
-
-This variable conditionally defines the C<USE_REENTRANT_API> symbol,
-which indicates that the thread code may try to use the various
-_r versions of library functions. This is only potentially
-meaningful if usethreads is set and is very experimental, it is
-not even prompted for.
-
-=item C<userelocatableinc>
-
-From F<bin.U>:
-
-This variable is set to true to indicate that perl should relocate
-@C<INC> entries at runtime based on the path to the perl binary.
-Any @C<INC> paths starting F<.../> are relocated relative to the directory
-containing the perl binary, and a logical cleanup of the path is then
-made around the join point (removing F<dir/../> pairs)
-
-=item C<usesfio>
-
-From F<d_sfio.U>:
-
-This variable is set to true when the user agrees to use sfio.
-It is set to false when sfio is not available or when the user
-explicitly requests not to use sfio. It is here primarily so
-that command-line settings can override the auto-detection of
-d_sfio without running into a "WHOA THERE".
-
-=item C<useshrplib>
-
-From F<libperl.U>:
-
-This variable is set to C<true> if the user wishes
-to build a shared libperl, and C<false> otherwise.
-
-=item C<usesitecustomize>
-
-From F<d_sitecustomize.U>:
-
-This variable is set to true when the user requires a mechanism that
-allows the sysadmin to add entries to @C<INC> at runtime. This variable
-being set, makes perl run F<$F<sitelib/sitecustomize.pl>> at startup.
-
-=item C<usesocks>
-
-From F<usesocks.U>:
-
-This variable conditionally defines the C<USE_SOCKS> symbol,
-and indicates that Perl should be built to use C<SOCKS>.
-
-=item C<usethreads>
-
-From F<usethreads.U>:
-
-This variable conditionally defines the C<USE_THREADS> symbol,
-and indicates that Perl should be built to use threads.
-
-=item C<usevendorprefix>
-
-From F<vendorprefix.U>:
-
-This variable tells whether the vendorprefix
-and consequently other vendor* paths are in use.
-
-=item C<usevfork>
-
-From F<d_vfork.U>:
-
-This variable is set to true when the user accepts to use vfork.
-It is set to false when no vfork is available or when the user
-explicitly requests not to use vfork.
-
-=item C<usrinc>
-
-From F<usrinc.U>:
-
-This variable holds the path of the include files, which is
-usually F</usr/include>. It is mainly used by other Configure units.
-
-=item C<uuname>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<uvoformat>
-
-From F<perlxvf.U>:
-
-This variable contains the format string used for printing
-a Perl C<UV> as an unsigned octal integer.
-
-=item C<uvsize>
-
-From F<perlxv.U>:
-
-This variable is the size of a C<UV> in bytes.
-
-=item C<uvtype>
-
-From F<perlxv.U>:
-
-This variable contains the C type used for Perl's C<UV>.
-
-=item C<uvuformat>
-
-From F<perlxvf.U>:
-
-This variable contains the format string used for printing
-a Perl C<UV> as an unsigned decimal integer.
-
-=item C<uvxformat>
-
-From F<perlxvf.U>:
-
-This variable contains the format string used for printing
-a Perl C<UV> as an unsigned hexadecimal integer in lowercase abcdef.
-
-=item C<uvXUformat>
-
-From F<perlxvf.U>:
-
-This variable contains the format string used for printing
-a Perl C<UV> as an unsigned hexadecimal integer in uppercase C<ABCDEF>.
-
-=back
-
-=cut
-
-=head2 v
-
-=over 4
-
-=cut
-
-=item C<vaproto>
-
-From F<vaproto.U>:
-
-This variable conditionally defines C<CAN_VAPROTO> on systems supporting
-prototype declaration of functions with a variable number of
-arguments. See also prototype.
-
-=item C<vendorarch>
-
-From F<vendorarch.U>:
-
-This variable contains the value of the C<PERL_VENDORARCH> symbol.
-It may have a F<~> on the front.
-The standard distribution will put nothing in this directory.
-Vendors who distribute perl may wish to place their own
-architecture-dependent modules and extensions in this directory with
-MakeMaker F<Makefile.PL> C<INSTALLDIRS>=vendor
-or equivalent. See C<INSTALL> for details.
-
-=item C<vendorarchexp>
-
-From F<vendorarch.U>:
-
-This variable is the F<~name> expanded version of vendorarch, so that you
-may use it directly in Makefiles or shell scripts.
-
-=item C<vendorbin>
-
-From F<vendorbin.U>:
-
-This variable contains the eventual value of the C<VENDORBIN> symbol.
-It may have a F<~> on the front.
-The standard distribution will put nothing in this directory.
-Vendors who distribute perl may wish to place additional
-binaries in this directory with
-MakeMaker F<Makefile.PL> C<INSTALLDIRS>=vendor
-or equivalent. See C<INSTALL> for details.
-
-=item C<vendorbinexp>
-
-From F<vendorbin.U>:
-
-This variable is the F<~name> expanded version of vendorbin, so that you
-may use it directly in Makefiles or shell scripts.
-
-=item C<vendorhtml1dir>
-
-From F<vendorhtml1dir.U>:
-
-This variable contains the name of the directory for html
-pages. It may have a F<~> on the front.
-The standard distribution will put nothing in this directory.
-Vendors who distribute perl may wish to place their own
-html pages in this directory with
-MakeMaker F<Makefile.PL> C<INSTALLDIRS>=vendor
-or equivalent. See C<INSTALL> for details.
-
-=item C<vendorhtml1direxp>
-
-From F<vendorhtml1dir.U>:
-
-This variable is the F<~name> expanded version of vendorhtml1dir, so that you
-may use it directly in Makefiles or shell scripts.
-
-=item C<vendorhtml3dir>
-
-From F<vendorhtml3dir.U>:
-
-This variable contains the name of the directory for html
-library pages. It may have a F<~> on the front.
-The standard distribution will put nothing in this directory.
-Vendors who distribute perl may wish to place their own
-html pages for modules and extensions in this directory with
-MakeMaker F<Makefile.PL> C<INSTALLDIRS>=vendor
-or equivalent. See C<INSTALL> for details.
-
-=item C<vendorhtml3direxp>
-
-From F<vendorhtml3dir.U>:
-
-This variable is the F<~name> expanded version of vendorhtml3dir, so that you
-may use it directly in Makefiles or shell scripts.
-
-=item C<vendorlib>
-
-From F<vendorlib.U>:
-
-This variable contains the eventual value of the C<VENDORLIB> symbol,
-which is the name of the private library for this package.
-The standard distribution will put nothing in this directory.
-Vendors who distribute perl may wish to place their own
-modules in this directory with
-MakeMaker F<Makefile.PL> C<INSTALLDIRS>=vendor
-or equivalent. See C<INSTALL> for details.
-
-=item C<vendorlib_stem>
-
-From F<vendorlib.U>:
-
-This variable is $vendorlibexp with any trailing version-specific component
-removed. The elements in inc_version_list (F<inc_version_list.U>) can
-be tacked onto this variable to generate a list of directories to search.
-
-=item C<vendorlibexp>
-
-From F<vendorlib.U>:
-
-This variable is the F<~name> expanded version of vendorlib, so that you
-may use it directly in Makefiles or shell scripts.
-
-=item C<vendorman1dir>
-
-From F<vendorman1dir.U>:
-
-This variable contains the name of the directory for man1
-pages. It may have a F<~> on the front.
-The standard distribution will put nothing in this directory.
-Vendors who distribute perl may wish to place their own
-man1 pages in this directory with
-MakeMaker F<Makefile.PL> C<INSTALLDIRS>=vendor
-or equivalent. See C<INSTALL> for details.
-
-=item C<vendorman1direxp>
-
-From F<vendorman1dir.U>:
-
-This variable is the F<~name> expanded version of vendorman1dir, so that you
-may use it directly in Makefiles or shell scripts.
-
-=item C<vendorman3dir>
-
-From F<vendorman3dir.U>:
-
-This variable contains the name of the directory for man3
-pages. It may have a F<~> on the front.
-The standard distribution will put nothing in this directory.
-Vendors who distribute perl may wish to place their own
-man3 pages in this directory with
-MakeMaker F<Makefile.PL> C<INSTALLDIRS>=vendor
-or equivalent. See C<INSTALL> for details.
-
-=item C<vendorman3direxp>
-
-From F<vendorman3dir.U>:
-
-This variable is the F<~name> expanded version of vendorman3dir, so that you
-may use it directly in Makefiles or shell scripts.
-
-=item C<vendorprefix>
-
-From F<vendorprefix.U>:
-
-This variable holds the full absolute path of the directory below
-which the vendor will install add-on packages.
-See C<INSTALL> for usage and examples.
-
-=item C<vendorprefixexp>
-
-From F<vendorprefix.U>:
-
-This variable holds the full absolute path of the directory below
-which the vendor will install add-on packages. Derived from vendorprefix.
-
-=item C<vendorscript>
-
-From F<vendorscript.U>:
-
-This variable contains the eventual value of the C<VENDORSCRIPT> symbol.
-It may have a F<~> on the front.
-The standard distribution will put nothing in this directory.
-Vendors who distribute perl may wish to place additional
-executable scripts in this directory with
-MakeMaker F<Makefile.PL> C<INSTALLDIRS>=vendor
-or equivalent. See C<INSTALL> for details.
-
-=item C<vendorscriptexp>
-
-From F<vendorscript.U>:
-
-This variable is the F<~name> expanded version of vendorscript, so that you
-may use it directly in Makefiles or shell scripts.
-
-=item C<version>
-
-From F<patchlevel.U>:
-
-The full version number of this package, such as 5.6.1 (or 5_6_1).
-This combines revision, patchlevel, and subversion to get the
-full version number, including any possible subversions.
-This is suitable for use as a directory name, and hence is
-filesystem dependent.
-
-=item C<version_patchlevel_string>
-
-From F<patchlevel.U>:
-
-This is a string combining version, subversion and
-perl_patchlevel (if perl_patchlevel is non-zero).
-It is typically something like
-'version 7 subversion 1' or
-'version 7 subversion 1 patchlevel 11224'
-It is computed here to avoid duplication of code in F<myconfig.SH>
-and F<lib/Config.pm>.
-
-=item C<versiononly>
-
-From F<versiononly.U>:
-
-If set, this symbol indicates that only the version-specific
-components of a perl installation should be installed.
-This may be useful for making a test installation of a new
-version without disturbing the existing installation.
-Setting versiononly is equivalent to setting installperl's -v option.
-In particular, the non-versioned scripts and programs such as
-a2p, c2ph, h2xs, pod2*, and perldoc are not installed
-(see C<INSTALL> for a more complete list). Nor are the man
-pages installed.
-Usually, this is undef.
-
-=item C<vi>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<voidflags>
-
-From F<voidflags.U>:
-
-This variable contains the eventual value of the C<VOIDFLAGS> symbol,
-which indicates how much support of the void type is given by this
-compiler. See C<VOIDFLAGS> for more info.
-
-=back
-
-=cut
-
-=head2 x
-
-=over 4
-
-=cut
-
-=item C<xlibpth>
-
-From F<libpth.U>:
-
-This variable holds extra path (space-separated) used to find
-libraries on this platform, for example C<CPU>-specific libraries
-(on multi-C<CPU> platforms) may be listed here.
-
-=back
-
-=cut
-
-=head2 y
-
-=over 4
-
-=cut
-
-=item C<yacc>
-
-From F<yacc.U>:
-
-This variable holds the name of the compiler compiler we
-want to use in the Makefile. It can be yacc, byacc, or bison -y.
-
-=item C<yaccflags>
-
-From F<yacc.U>:
-
-This variable contains any additional yacc flags desired by the
-user. It is up to the Makefile to use this.
-
-=back
-
-=cut
-
-=head2 z
-
-=over 4
-
-=cut
-
-=item C<zcat>
-
-From F<Loc.U>:
-
-This variable is defined but not used by Configure.
-The value is the empty string and is not useful.
-
-=item C<zip>
-
-From F<Loc.U>:
-
-This variable is used internally by Configure to determine the
-full pathname (if any) of the zip program. After Configure runs,
-the value is reset to a plain C<zip> and is not useful.
-
-
-=back
-
-=head1 GIT DATA
-
-Information on the git commit from which the current perl binary was compiled
-can be found in the variable C<$Config::Git_Data>. The variable is a
-structured string that looks something like this:
-
- git_commit_id='ea0c2dbd5f5ac6845ecc7ec6696415bf8e27bd52'
- git_describe='GitLive-blead-1076-gea0c2db'
- git_branch='smartmatch'
- git_uncommitted_changes=''
- git_commit_id_title='Commit id:'
- git_commit_date='2009-05-09 17:47:31 +0200'
-
-Its format is not guaranteed not to change over time.
-
-=head1 NOTE
-
-This module contains a good example of how to use tie to implement a
-cache and an example of how to make a tied variable readonly to those
-outside of it.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Encode/PerlIO.pod b/Master/tlpkg/tlperl/lib/Encode/PerlIO.pod
deleted file mode 100644
index 1a9269a9b0c..00000000000
--- a/Master/tlpkg/tlperl/lib/Encode/PerlIO.pod
+++ /dev/null
@@ -1,167 +0,0 @@
-=head1 NAME
-
-Encode::PerlIO -- a detailed document on Encode and PerlIO
-
-=head1 Overview
-
-It is very common to want to do encoding transformations when
-reading or writing files, network connections, pipes etc.
-If Perl is configured to use the new 'perlio' IO system then
-C<Encode> provides a "layer" (see L<PerlIO>) which can transform
-data as it is read or written.
-
-Here is how the blind poet would modernise the encoding:
-
- use Encode;
- open(my $iliad,'<:encoding(iso-8859-7)','iliad.greek');
- open(my $utf8,'>:utf8','iliad.utf8');
- my @epic = <$iliad>;
- print $utf8 @epic;
- close($utf8);
- close($illiad);
-
-In addition, the new IO system can also be configured to read/write
-UTF-8 encoded characters (as noted above, this is efficient):
-
- open(my $fh,'>:utf8','anything');
- print $fh "Any \x{0021} string \N{SMILEY FACE}\n";
-
-Either of the above forms of "layer" specifications can be made the default
-for a lexical scope with the C<use open ...> pragma. See L<open>.
-
-Once a handle is open, its layers can be altered using C<binmode>.
-
-Without any such configuration, or if Perl itself is built using the
-system's own IO, then write operations assume that the file handle
-accepts only I<bytes> and will C<die> if a character larger than 255 is
-written to the handle. When reading, each octet from the handle becomes
-a byte-in-a-character. Note that this default is the same behaviour
-as bytes-only languages (including Perl before v5.6) would have,
-and is sufficient to handle native 8-bit encodings e.g. iso-8859-1,
-EBCDIC etc. and any legacy mechanisms for handling other encodings
-and binary data.
-
-In other cases, it is the program's responsibility to transform
-characters into bytes using the API above before doing writes, and to
-transform the bytes read from a handle into characters before doing
-"character operations" (e.g. C<lc>, C</\W+/>, ...).
-
-You can also use PerlIO to convert larger amounts of data you don't
-want to bring into memory. For example, to convert between ISO-8859-1
-(Latin 1) and UTF-8 (or UTF-EBCDIC in EBCDIC machines):
-
- open(F, "<:encoding(iso-8859-1)", "data.txt") or die $!;
- open(G, ">:utf8", "data.utf") or die $!;
- while (<F>) { print G }
-
- # Could also do "print G <F>" but that would pull
- # the whole file into memory just to write it out again.
-
-More examples:
-
- open(my $f, "<:encoding(cp1252)")
- open(my $g, ">:encoding(iso-8859-2)")
- open(my $h, ">:encoding(latin9)") # iso-8859-15
-
-See also L<encoding> for how to change the default encoding of the
-data in your script.
-
-=head1 How does it work?
-
-Here is a crude diagram of how filehandle, PerlIO, and Encode
-interact.
-
- filehandle <-> PerlIO PerlIO <-> scalar (read/printed)
- \ /
- Encode
-
-When PerlIO receives data from either direction, it fills a buffer
-(currently with 1024 bytes) and passes the buffer to Encode.
-Encode tries to convert the valid part and passes it back to PerlIO,
-leaving invalid parts (usually a partial character) in the buffer.
-PerlIO then appends more data to the buffer, calls Encode again,
-and so on until the data stream ends.
-
-To do so, PerlIO always calls (de|en)code methods with CHECK set to 1.
-This ensures that the method stops at the right place when it
-encounters partial character. The following is what happens when
-PerlIO and Encode tries to encode (from utf8) more than 1024 bytes
-and the buffer boundary happens to be in the middle of a character.
-
- A B C .... ~ \x{3000} ....
- 41 42 43 .... 7E e3 80 80 ....
- <- buffer --------------->
- << encoded >>>>>>>>>>
- <- next buffer ------
-
-Encode converts from the beginning to \x7E, leaving \xe3 in the buffer
-because it is invalid (partial character).
-
-Unfortunately, this scheme does not work well with escape-based
-encodings such as ISO-2022-JP.
-
-=head1 Line Buffering
-
-Now let's see what happens when you try to decode from ISO-2022-JP and
-the buffer ends in the middle of a character.
-
- JIS208-ESC \x{5f3e}
- A B C .... ~ \e $ B |DAN | ....
- 41 42 43 .... 7E 1b 24 41 43 46 ....
- <- buffer --------------------------->
- << encoded >>>>>>>>>>>>>>>>>>>>>>>
-
-As you see, the next buffer begins with \x43. But \x43 is 'C' in
-ASCII, which is wrong in this case because we are now in JISX 0208
-area so it has to convert \x43\x46, not \x43. Unlike utf8 and EUC,
-in escape-based encodings you can't tell if a given octet is a whole
-character or just part of it.
-
-Fortunately PerlIO also supports line buffer if you tell PerlIO to use
-one instead of fixed buffer. Since ISO-2022-JP is guaranteed to revert to ASCII at the end of the line, partial
-character will never happen when line buffer is used.
-
-To tell PerlIO to use line buffer, implement -E<gt>needs_lines method
-for your encoding object. See L<Encode::Encoding> for details.
-
-Thanks to these efforts most encodings that come with Encode support
-PerlIO but that still leaves following encodings.
-
- iso-2022-kr
- MIME-B
- MIME-Header
- MIME-Q
-
-Fortunately iso-2022-kr is hardly used (according to Jungshik) and
-MIME-* are very unlikely to be fed to PerlIO because they are for mail
-headers. See L<Encode::MIME::Header> for details.
-
-=head2 How can I tell whether my encoding fully supports PerlIO ?
-
-As of this writing, any encoding whose class belongs to Encode::XS and
-Encode::Unicode works. The Encode module has a C<perlio_ok> method
-which you can use before applying PerlIO encoding to the filehandle.
-Here is an example:
-
- my $use_perlio = perlio_ok($enc);
- my $layer = $use_perlio ? "<:raw" : "<:encoding($enc)";
- open my $fh, $layer, $file or die "$file : $!";
- while(<$fh>){
- $_ = decode($enc, $_) unless $use_perlio;
- # ....
- }
-
-=head1 SEE ALSO
-
-L<Encode::Encoding>,
-L<Encode::Supported>,
-L<Encode::PerlIO>,
-L<encoding>,
-L<perlebcdic>,
-L<perlfunc/open>,
-L<perlunicode>,
-L<utf8>,
-the Perl Unicode Mailing List E<lt>perl-unicode@perl.orgE<gt>
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Encode/Supported.pod b/Master/tlpkg/tlperl/lib/Encode/Supported.pod
deleted file mode 100644
index e84faafd9e2..00000000000
--- a/Master/tlpkg/tlperl/lib/Encode/Supported.pod
+++ /dev/null
@@ -1,901 +0,0 @@
-=head1 NAME
-
-Encode::Supported -- Encodings supported by Encode
-
-=head1 DESCRIPTION
-
-=head2 Encoding Names
-
-Encoding names are case insensitive. White space in names
-is ignored. In addition, an encoding may have aliases.
-Each encoding has one "canonical" name. The "canonical"
-name is chosen from the names of the encoding by picking
-the first in the following sequence (with a few exceptions).
-
-=over 2
-
-=item *
-
-The name used by the Perl community. That includes 'utf8' and 'ascii'.
-Unlike aliases, canonical names directly reach the method so such
-frequently used words like 'utf8' don't need to do alias lookups.
-
-=item *
-
-The MIME name as defined in IETF RFCs. This includes all "iso-"s.
-
-=item *
-
-The name in the IANA registry.
-
-=item *
-
-The name used by the organization that defined it.
-
-=back
-
-In case I<de jure> canonical names differ from that of the Encode
-module, they are always aliased if it ever be implemented. So you can
-safely tell if a given encoding is implemented or not just by passing
-the canonical name.
-
-Because of all the alias issues, and because in the general case
-encodings have state, "Encode" uses an encoding object internally
-once an operation is in progress.
-
-=head1 Supported Encodings
-
-As of Perl 5.8.0, at least the following encodings are recognized.
-Note that unless otherwise specified, they are all case insensitive
-(via alias) and all occurrence of spaces are replaced with '-'.
-In other words, "ISO 8859 1" and "iso-8859-1" are identical.
-
-Encodings are categorized and implemented in several different modules
-but you don't have to C<use Encode::XX> to make them available for
-most cases. Encode.pm will automatically load those modules on demand.
-
-=head2 Built-in Encodings
-
-The following encodings are always available.
-
- Canonical Aliases Comments & References
- ----------------------------------------------------------------
- ascii US-ascii ISO-646-US [ECMA]
- ascii-ctrl Special Encoding
- iso-8859-1 latin1 [ISO]
- null Special Encoding
- utf8 UTF-8 [RFC2279]
- ----------------------------------------------------------------
-
-I<null> and I<ascii-ctrl> are special. "null" fails for all character
-so when you set fallback mode to PERLQQ, HTMLCREF or XMLCREF, ALL
-CHARACTERS will fall back to character references. Ditto for
-"ascii-ctrl" except for control characters. For fallback modes, see
-L<Encode>.
-
-=head2 Encode::Unicode -- other Unicode encodings
-
-Unicode coding schemes other than native utf8 are supported by
-Encode::Unicode, which will be autoloaded on demand.
-
- ----------------------------------------------------------------
- UCS-2BE UCS-2, iso-10646-1 [IANA, UC]
- UCS-2LE [UC]
- UTF-16 [UC]
- UTF-16BE [UC]
- UTF-16LE [UC]
- UTF-32 [UC]
- UTF-32BE UCS-4 [UC]
- UTF-32LE [UC]
- UTF-7 [RFC2152]
- ----------------------------------------------------------------
-
-To find how (UCS-2|UTF-(16|32))(LE|BE)? differ from one another,
-see L<Encode::Unicode>.
-
-UTF-7 is a special encoding which "re-encodes" UTF-16BE into a 7-bit
-encoding. It is implemented seperately by Encode::Unicode::UTF7.
-
-=head2 Encode::Byte -- Extended ASCII
-
-Encode::Byte implements most single-byte encodings except for
-Symbols and EBCDIC. The following encodings are based on single-byte
-encodings implemented as extended ASCII. Most of them map
-\x80-\xff (upper half) to non-ASCII characters.
-
-=over 2
-
-=item ISO-8859 and corresponding vendor mappings
-
-Since there are so many, they are presented in table format with
-languages and corresponding encoding names by vendors. Note that
-the table is sorted in order of ISO-8859 and the corresponding vendor
-mappings are slightly different from that of ISO. See
-L<http://czyborra.com/charsets/iso8859.html> for details.
-
- Lang/Regions ISO/Other Std. DOS Windows Macintosh Others
- ----------------------------------------------------------------
- N. America (ASCII) cp437 AdobeStandardEncoding
- cp863 (DOSCanadaF)
- W. Europe iso-8859-1 cp850 cp1252 MacRoman nextstep
- hp-roman8
- cp860 (DOSPortuguese)
- Cntrl. Europe iso-8859-2 cp852 cp1250 MacCentralEurRoman
- MacCroatian
- MacRomanian
- MacRumanian
- Latin3[1] iso-8859-3
- Latin4[2] iso-8859-4
- Cyrillics iso-8859-5 cp855 cp1251 MacCyrillic
- (See also next section) cp866 MacUkrainian
- Arabic iso-8859-6 cp864 cp1256 MacArabic
- cp1006 MacFarsi
- Greek iso-8859-7 cp737 cp1253 MacGreek
- cp869 (DOSGreek2)
- Hebrew iso-8859-8 cp862 cp1255 MacHebrew
- Turkish iso-8859-9 cp857 cp1254 MacTurkish
- Nordics iso-8859-10 cp865
- cp861 MacIcelandic
- MacSami
- Thai iso-8859-11[3] cp874 MacThai
- (iso-8859-12 is nonexistent. Reserved for Indics?)
- Baltics iso-8859-13 cp775 cp1257
- Celtics iso-8859-14
- Latin9 [4] iso-8859-15
- Latin10 iso-8859-16
- Vietnamese viscii cp1258 MacVietnamese
- ----------------------------------------------------------------
-
- [1] Esperanto, Maltese, and Turkish. Turkish is now on 8859-9.
- [2] Baltics. Now on 8859-10, except for Latvian.
- [3] TIS 620 + Non-Breaking Space (0xA0 / U+00A0)
- [4] Nicknamed Latin0; the Euro sign as well as French and Finnish
- letters that are missing from 8859-1 were added.
-
-All cp* are also available as ibm-*, ms-*, and windows-* . See also
-L<http://czyborra.com/charsets/codepages.html>.
-
-Macintosh encodings don't seem to be registered in such entities as
-IANA. "Canonical" names in Encode are based upon Apple's Tech Note
-1150. See L<http://developer.apple.com/technotes/tn/tn1150.html>
-for details.
-
-=item KOI8 - De Facto Standard for the Cyrillic world
-
-Though ISO-8859 does have ISO-8859-5, the KOI8 series is far more
-popular in the Net. L<Encode> comes with the following KOI charsets.
-For gory details, see L<http://czyborra.com/charsets/cyrillic.html>
-
- ----------------------------------------------------------------
- koi8-f
- koi8-r cp878 [RFC1489]
- koi8-u [RFC2319]
- ----------------------------------------------------------------
-
-=back
-
-=head2 gsm0338 - Hentai Latin 1
-
-GSM0338 is for GSM handsets. Though it shares alphanumerals with
-ASCII, control character ranges and other parts are mapped very
-differently, mainly to store Greek characters. There are also escape
-sequences (starting with 0x1B) to cover e.g. the Euro sign.
-
-This was once handled by L<Encode::Bytes> but because of all those
-unusual specifications, Encode 2.20 has relocated the support to
-L<Encode::GSM0338>. See L<Encode::GSM0338> for details.
-
-=over 2
-
-=item gsm0338 support before 2.19
-
-Some special cases like a trailing 0x00 byte or a lone 0x1B byte are not
-well-defined and decode() will return an empty string for them.
-One possible workaround is
-
- $gsm =~ s/\x00\z/\x00\x00/;
- $uni = decode("gsm0338", $gsm);
- $uni .= "\xA0" if $gsm =~ /\x1B\z/;
-
-Note that the Encode implementation of GSM0338 does not implement the
-reuse of Latin capital letters as Greek capital letters (for example,
-the 0x5A is U+005A (LATIN CAPITAL LETTER Z), not U+0396 (GREEK CAPITAL
-LETTER ZETA).
-
-The GSM0338 is also covered in Encode::Byte even though it is not
-an "extended ASCII" encoding.
-
-=back
-
-=head2 CJK: Chinese, Japanese, Korean (Multibyte)
-
-Note that Vietnamese is listed above. Also read "Encoding vs Charset"
-below. Also note that these are implemented in distinct modules by
-countries, due to the size concerns (simplified Chinese is mapped
-to 'CN', continental China, while traditional Chinese is mapped to
-'TW', Taiwan). Please refer to their respective documentation pages.
-
-=over 2
-
-=item Encode::CN -- Continental China
-
- Standard DOS/Win Macintosh Comment/Reference
- ----------------------------------------------------------------
- euc-cn [1] MacChineseSimp
- (gbk) cp936 [2]
- gb12345-raw { GB12345 without CES }
- gb2312-raw { GB2312 without CES }
- hz
- iso-ir-165
- ----------------------------------------------------------------
-
- [1] GB2312 is aliased to this. See L<Microsoft-related naming mess>
- [2] gbk is aliased to this. See L<Microsoft-related naming mess>
-
-=item Encode::JP -- Japan
-
- Standard DOS/Win Macintosh Comment/Reference
- ----------------------------------------------------------------
- euc-jp
- shiftjis cp932 macJapanese
- 7bit-jis
- iso-2022-jp [RFC1468]
- iso-2022-jp-1 [RFC2237]
- jis0201-raw { JIS X 0201 (roman + halfwidth kana) without CES }
- jis0208-raw { JIS X 0208 (Kanji + fullwidth kana) without CES }
- jis0212-raw { JIS X 0212 (Extended Kanji) without CES }
- ----------------------------------------------------------------
-
-=item Encode::KR -- Korea
-
- Standard DOS/Win Macintosh Comment/Reference
- ----------------------------------------------------------------
- euc-kr MacKorean [RFC1557]
- cp949 [1]
- iso-2022-kr [RFC1557]
- johab [KS X 1001:1998, Annex 3]
- ksc5601-raw { KSC5601 without CES }
- ----------------------------------------------------------------
-
- [1] ks_c_5601-1987, (x-)?windows-949, and uhc are aliased to this.
- See below.
-
-=item Encode::TW -- Taiwan
-
- Standard DOS/Win Macintosh Comment/Reference
- ----------------------------------------------------------------
- big5-eten cp950 MacChineseTrad {big5 aliased to big5-eten}
- big5-hkscs
- ----------------------------------------------------------------
-
-=item Encode::HanExtra -- More Chinese via CPAN
-
-Due to the size concerns, additional Chinese encodings below are
-distributed separately on CPAN, under the name Encode::HanExtra.
-
- Standard DOS/Win Macintosh Comment/Reference
- ----------------------------------------------------------------
- big5ext CMEX's Big5e Extension
- big5plus CMEX's Big5+ Extension
- cccii Chinese Character Code for Information Interchange
- euc-tw EUC (Extended Unix Character)
- gb18030 GBK with Traditional Characters
- ----------------------------------------------------------------
-
-=item Encode::JIS2K -- JIS X 0213 encodings via CPAN
-
-Due to size concerns, additional Japanese encodings below are
-distributed separately on CPAN, under the name Encode::JIS2K.
-
- Standard DOS/Win Macintosh Comment/Reference
- ----------------------------------------------------------------
- euc-jisx0213
- shiftjisx0123
- iso-2022-jp-3
- jis0213-1-raw
- jis0213-2-raw
- ----------------------------------------------------------------
-
-=back
-
-=head2 Miscellaneous encodings
-
-=over 2
-
-=item Encode::EBCDIC
-
-See L<perlebcdic> for details.
-
- ----------------------------------------------------------------
- cp37
- cp500
- cp875
- cp1026
- cp1047
- posix-bc
- ----------------------------------------------------------------
-
-=item Encode::Symbols
-
-For symbols and dingbats.
-
- ----------------------------------------------------------------
- symbol
- dingbats
- MacDingbats
- AdobeZdingbat
- AdobeSymbol
- ----------------------------------------------------------------
-
-=item Encode::MIME::Header
-
-Strictly speaking, MIME header encoding documented in RFC 2047 is more
-of encapsulation than encoding. However, their support in modern
-world is imperative so they are supported.
-
- ----------------------------------------------------------------
- MIME-Header [RFC2047]
- MIME-B [RFC2047]
- MIME-Q [RFC2047]
- ----------------------------------------------------------------
-
-=item Encode::Guess
-
-This one is not a name of encoding but a utility that lets you pick up
-the most appropriate encoding for a data out of given I<suspects>. See
-L<Encode::Guess> for details.
-
-=back
-
-=head1 Unsupported encodings
-
-The following encodings are not supported as yet; some because they
-are rarely used, some because of technical difficulties. They may
-be supported by external modules via CPAN in the future, however.
-
-=over 2
-
-=item ISO-2022-JP-2 [RFC1554]
-
-Not very popular yet. Needs Unicode Database or equivalent to
-implement encode() (because it includes JIS X 0208/0212, KSC5601, and
-GB2312 simultaneously, whose code points in Unicode overlap. So you
-need to lookup the database to determine to what character set a given
-Unicode character should belong).
-
-=item ISO-2022-CN [RFC1922]
-
-Not very popular. Needs CNS 11643-1 and -2 which are not available in
-this module. CNS 11643 is supported (via euc-tw) in Encode::HanExtra.
-Autrijus Tang may add support for this encoding in his module in future.
-
-=item Various HP-UX encodings
-
-The following are unsupported due to the lack of mapping data.
-
- '8' - arabic8, greek8, hebrew8, kana8, thai8, and turkish8
- '15' - japanese15, korean15, and roi15
-
-=item Cyrillic encoding ISO-IR-111
-
-Anton Tagunov doubts its usefulness.
-
-=item ISO-8859-8-1 [Hebrew]
-
-None of the Encode team knows Hebrew enough (ISO-8859-8, cp1255 and
-MacHebrew are supported because and just because there were mappings
-available at L<http://www.unicode.org/>). Contributions welcome.
-
-=item ISIRI 3342, Iran System, ISIRI 2900 [Farsi]
-
-Ditto.
-
-=item Thai encoding TCVN
-
-Ditto.
-
-=item Vietnamese encodings VPS
-
-Though Jungshik Shin has reported that Mozilla supports this encoding,
-it was too late before 5.8.0 for us to add it. In the future, it
-may be available via a separate module. See
-L<http://lxr.mozilla.org/seamonkey/source/intl/uconv/ucvlatin/vps.uf>
-and
-L<http://lxr.mozilla.org/seamonkey/source/intl/uconv/ucvlatin/vps.ut>
-if you are interested in helping us.
-
-=item Various Mac encodings
-
-The following are unsupported due to the lack of mapping data.
-
- MacArmenian, MacBengali, MacBurmese, MacEthiopic
- MacExtArabic, MacGeorgian, MacKannada, MacKhmer
- MacLaotian, MacMalayalam, MacMongolian, MacOriya
- MacSinhalese, MacTamil, MacTelugu, MacTibetan
- MacVietnamese
-
-The rest which are already available are based upon the vendor mappings
-at L<http://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/> .
-
-=item (Mac) Indic encodings
-
-The maps for the following are available at L<http://www.unicode.org/>
-but remain unsupport because those encodings need algorithmical
-approach, currently unsupported by F<enc2xs>:
-
- MacDevanagari
- MacGurmukhi
- MacGujarati
-
-For details, please see C<Unicode mapping issues and notes:> at
-L<http://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/DEVANAGA.TXT> .
-
-I believe this issue is prevalent not only for Mac Indics but also in
-other Indic encodings, but the above were the only Indic encodings
-maps that I could find at L<http://www.unicode.org/> .
-
-=back
-
-=head1 Encoding vs. Charset -- terminology
-
-We are used to using the term (character) I<encoding> and I<character
-set> interchangeably. But just as confusing the terms byte and
-character is dangerous and the terms should be differentiated when
-needed, we need to differentiate I<encoding> and I<character set>.
-
-To understand that, here is a description of how we make computers
-grok our characters.
-
-=over 2
-
-=item *
-
-First we start with which characters to include. We call this
-collection of characters I<character repertoire>.
-
-=item *
-
-Then we have to give each character a unique ID so your computer can
-tell the difference between 'a' and 'A'. This itemized character
-repertoire is now a I<character set>.
-
-=item *
-
-If your computer can grow the character set without further
-processing, you can go ahead and use it. This is called a I<coded
-character set> (CCS) or I<raw character encoding>. ASCII is used this
-way for most cases.
-
-=item *
-
-But in many cases, especially multi-byte CJK encodings, you have to
-tweak a little more. Your network connection may not accept any data
-with the Most Significant Bit set, and your computer may not be able to
-tell if a given byte is a whole character or just half of it. So you
-have to I<encode> the character set to use it.
-
-A I<character encoding scheme> (CES) determines how to encode a given
-character set, or a set of multiple character sets. 7bit ISO-2022 is
-an example of a CES. You switch between character sets via I<escape
-sequences>.
-
-=back
-
-Technically, or mathematically, speaking, a character set encoded in
-such a CES that maps character by character may form a CCS. EUC is such
-an example. The CES of EUC is as follows:
-
-=over 2
-
-=item *
-
-Map ASCII unchanged.
-
-=item *
-
-Map such a character set that consists of 94 or 96 powered by N
-members by adding 0x80 to each byte.
-
-=item *
-
-You can also use 0x8e and 0x8f to indicate that the following sequence of
-characters belongs to yet another character set. To each following byte
-is added the value 0x80.
-
-=back
-
-By carefully looking at the encoded byte sequence, you can find that the
-byte sequence conforms a unique number. In that sense, EUC is a CCS
-generated by a CES above from up to four CCS (complicated?). UTF-8
-falls into this category. See L<perlUnicode/"UTF-8"> to find out how
-UTF-8 maps Unicode to a byte sequence.
-
-You may also have found out by now why 7bit ISO-2022 cannot comprise
-a CCS. If you look at a byte sequence \x21\x21, you can't tell if
-it is two !'s or IDEOGRAPHIC SPACE. EUC maps the latter to \xA1\xA1
-so you have no trouble differentiating between "!!". and S<" ">.
-
-=head1 Encoding Classification (by Anton Tagunov and Dan Kogai)
-
-This section tries to classify the supported encodings by their
-applicability for information exchange over the Internet and to
-choose the most suitable aliases to name them in the context of
-such communication.
-
-=over 2
-
-=item *
-
-To (en|de)code encodings marked by C<(**)>, you need
-C<Encode::HanExtra>, available from CPAN.
-
-=back
-
-Encoding names
-
- US-ASCII UTF-8 ISO-8859-* KOI8-R
- Shift_JIS EUC-JP ISO-2022-JP ISO-2022-JP-1
- EUC-KR Big5 GB2312
-
-are registered with IANA as preferred MIME names and may
-be used over the Internet.
-
-C<Shift_JIS> has been officialized by JIS X 0208:1997.
-L<Microsoft-related naming mess> gives details.
-
-C<GB2312> is the IANA name for C<EUC-CN>.
-See L<Microsoft-related naming mess> for details.
-
-C<GB_2312-80> I<raw> encoding is available as C<gb2312-raw>
-with Encode. See L<Encode::CN> for details.
-
- EUC-CN
- KOI8-U [RFC2319]
-
-have not been registered with IANA (as of March 2002) but
-seem to be supported by major web browsers.
-The IANA name for C<EUC-CN> is C<GB2312>.
-
- KS_C_5601-1987
-
-is heavily misused.
-See L<Microsoft-related naming mess> for details.
-
-C<KS_C_5601-1987> I<raw> encoding is available as C<kcs5601-raw>
-with Encode. See L<Encode::KR> for details.
-
- UTF-16 UTF-16BE UTF-16LE
-
-are IANA-registered C<charset>s. See [RFC 2781] for details.
-Jungshik Shin reports that UTF-16 with a BOM is well accepted
-by MS IE 5/6 and NS 4/6. Beware however that
-
-=over 2
-
-=item *
-
-C<UTF-16> support in any software you're going to be
-using/interoperating with has probably been less tested
-then C<UTF-8> support
-
-=item *
-
-C<UTF-8> coded data seamlessly passes traditional
-command piping (C<cat>, C<more>, etc.) while C<UTF-16> coded
-data is likely to cause confusion (with its zero bytes,
-for example)
-
-=item *
-
-it is beyond the power of words to describe the way HTML browsers
-encode non-C<ASCII> form data. To get a general impression, visit
-L<http://www.alanflavell.org.uk/charset/form-i18n.html>.
-While encoding of form data has stabilized for C<UTF-8> encoded pages
-(at least IE 5/6, NS 6, and Opera 6 behave consistently), be sure to
-expect fun (and cross-browser discrepancies) with C<UTF-16> encoded
-pages!
-
-=back
-
-The rule of thumb is to use C<UTF-8> unless you know what
-you're doing and unless you really benefit from using C<UTF-16>.
-
- ISO-IR-165 [RFC1345]
- VISCII
- GB 12345
- GB 18030 (**) (see links bellow)
- EUC-TW (**)
-
-are totally valid encodings but not registered at IANA.
-The names under which they are listed here are probably the
-most widely-known names for these encodings and are recommended
-names.
-
- BIG5PLUS (**)
-
-is a proprietary name.
-
-=head2 Microsoft-related naming mess
-
-Microsoft products misuse the following names:
-
-=over 2
-
-=item KS_C_5601-1987
-
-Microsoft extension to C<EUC-KR>.
-
-Proper names: C<CP949>, C<UHC>, C<x-windows-949> (as used by Mozilla).
-
-See L<http://lists.w3.org/Archives/Public/ietf-charsets/2001AprJun/0033.html>
-for details.
-
-Encode aliases C<KS_C_5601-1987> to C<cp949> to reflect this common
-misusage. I<Raw> C<KS_C_5601-1987> encoding is available as
-C<kcs5601-raw>.
-
-See L<Encode::KR> for details.
-
-=item GB2312
-
-Microsoft extension to C<EUC-CN>.
-
-Proper names: C<CP936>, C<GBK>.
-
-C<GB2312> has been registered in the C<EUC-CN> meaning at
-IANA. This has partially repaired the situation: Microsoft's
-C<GB2312> has become a superset of the official C<GB2312>.
-
-Encode aliases C<GB2312> to C<euc-cn> in full agreement with
-IANA registration. C<cp936> is supported separately.
-I<Raw> C<GB_2312-80> encoding is available as C<gb2312-raw>.
-
-See L<Encode::CN> for details.
-
-=item Big5
-
-Microsoft extension to C<Big5>.
-
-Proper name: C<CP950>.
-
-Encode separately supports C<Big5> and C<cp950>.
-
-=item Shift_JIS
-
-Microsoft's understanding of C<Shift_JIS>.
-
-JIS has not endorsed the full Microsoft standard however.
-The official C<Shift_JIS> includes only JIS X 0201 and JIS X 0208
-character sets, while Microsoft has always used C<Shift_JIS>
-to encode a wider character repertoire. See C<IANA> registration for
-C<Windows-31J>.
-
-As a historical predecessor, Microsoft's variant
-probably has more rights for the name, though it may be objected
-that Microsoft shouldn't have used JIS as part of the name
-in the first place.
-
-Unambiguous name: C<CP932>. C<IANA> name (also used by Mozilla, and
-provided as an alias by Encode): C<Windows-31J>.
-
-Encode separately supports C<Shift_JIS> and C<cp932>.
-
-=back
-
-=head1 Glossary
-
-=over 2
-
-=item character repertoire
-
-A collection of unique characters. A I<character> set in the strictest
-sense. At this stage, characters are not numbered.
-
-=item coded character set (CCS)
-
-A character set that is mapped in a way computers can use directly.
-Many character encodings, including EUC, fall in this category.
-
-=item character encoding scheme (CES)
-
-An algorithm to map a character set to a byte sequence. You don't
-have to be able to tell which character set a given byte sequence
-belongs. 7-bit ISO-2022 is a CES but it cannot be a CCS. EUC is an
-example of being both a CCS and CES.
-
-=item charset (in MIME context)
-
-has long been used in the meaning of C<encoding>, CES.
-
-While the word combination C<character set> has lost this meaning
-in MIME context since [RFC 2130], the C<charset> abbreviation has
-retained it. This is how [RFC 2277] and [RFC 2278] bless C<charset>:
-
- This document uses the term "charset" to mean a set of rules for
- mapping from a sequence of octets to a sequence of characters, such
- as the combination of a coded character set and a character encoding
- scheme; this is also what is used as an identifier in MIME "charset="
- parameters, and registered in the IANA charset registry ... (Note
- that this is NOT a term used by other standards bodies, such as ISO).
- [RFC 2277]
-
-=item EUC
-
-Extended Unix Character. See ISO-2022.
-
-=item ISO-2022
-
-A CES that was carefully designed to coexist with ASCII. There are a 7
-bit version and an 8 bit version.
-
-The 7 bit version switches character set via escape sequence so it
-cannot form a CCS. Since this is more difficult to handle in programs
-than the 8 bit version, the 7 bit version is not very popular except for
-iso-2022-jp, the I<de facto> standard CES for e-mails.
-
-The 8 bit version can form a CCS. EUC and ISO-8859 are two examples
-thereof. Pre-5.6 perl could use them as string literals.
-
-=item UCS
-
-Short for I<Universal Character Set>. When you say just UCS, it means
-I<Unicode>.
-
-=item UCS-2
-
-ISO/IEC 10646 encoding form: Universal Character Set coded in two
-octets.
-
-=item Unicode
-
-A character set that aims to include all character repertoires of the
-world. Many character sets in various national as well as industrial
-standards have become, in a way, just subsets of Unicode.
-
-=item UTF
-
-Short for I<Unicode Transformation Format>. Determines how to map a
-Unicode character into a byte sequence.
-
-=item UTF-16
-
-A UTF in 16-bit encoding. Can either be in big endian or little
-endian. The big endian version is called UTF-16BE (equal to UCS-2 +
-surrogate support) and the little endian version is called UTF-16LE.
-
-=back
-
-=head1 See Also
-
-L<Encode>,
-L<Encode::Byte>,
-L<Encode::CN>, L<Encode::JP>, L<Encode::KR>, L<Encode::TW>,
-L<Encode::EBCDIC>, L<Encode::Symbol>
-L<Encode::MIME::Header>, L<Encode::Guess>
-
-=head1 References
-
-=over 2
-
-=item ECMA
-
-European Computer Manufacturers Association
-L<http://www.ecma.ch>
-
-=over 2
-
-=item ECMA-035 (eq C<ISO-2022>)
-
-L<http://www.ecma.ch/ecma1/STAND/ECMA-035.HTM>
-
-The specification of ISO-2022 is available from the link above.
-
-=back
-
-=item IANA
-
-Internet Assigned Numbers Authority
-L<http://www.iana.org/>
-
-=over 2
-
-=item Assigned Charset Names by IANA
-
-L<http://www.iana.org/assignments/character-sets>
-
-Most of the C<canonical names> in Encode derive from this list
-so you can directly apply the string you have extracted from MIME
-header of mails and web pages.
-
-=back
-
-=item ISO
-
-International Organization for Standardization
-L<http://www.iso.ch/>
-
-=item RFC
-
-Request For Comments -- need I say more?
-L<http://www.rfc-editor.org/>, L<http://www.ietf.org/rfc.html>,
-L<http://www.faqs.org/rfcs/>
-
-=item UC
-
-Unicode Consortium
-L<http://www.unicode.org/>
-
-=over 2
-
-=item Unicode Glossary
-
-L<http://www.unicode.org/glossary/>
-
-The glossary of this document is based upon this site.
-
-=back
-
-=back
-
-=head2 Other Notable Sites
-
-=over 2
-
-=item czyborra.com
-
-L<http://czyborra.com/>
-
-Contains a lot of useful information, especially gory details of ISO
-vs. vendor mappings.
-
-=item CJK.inf
-
-L<http://examples.oreilly.com/cjkvinfo/doc/cjk.inf>
-
-Somewhat obsolete (last update in 1996), but still useful. Also try
-
-L<ftp://ftp.oreilly.com/pub/examples/nutshell/cjkv/pdf/GB18030_Summary.pdf>
-
-You will find brief info on C<EUC-CN>, C<GBK> and mostly on C<GB 18030>.
-
-=item Jungshik Shin's Hangul FAQ
-
-L<http://jshin.net/faq>
-
-And especially its subject 8.
-
-L<http://jshin.net/faq/qa8.html>
-
-A comprehensive overview of the Korean (C<KS *>) standards.
-
-=item debian.org: "Introduction to i18n"
-
-A brief description for most of the mentioned CJK encodings is
-contained in
-L<http://www.debian.org/doc/manuals/intro-i18n/ch-codes.en.html>
-
-=back
-
-=head2 Offline sources
-
-=over 2
-
-=item C<CJKV Information Processing> by Ken Lunde
-
-CJKV Information Processing
-1999 O'Reilly & Associates, ISBN : 1-56592-224-7
-
-The modern successor of C<CJK.inf>.
-
-Features a comprehensive coverage of CJKV character sets and
-encodings along with many other issues faced by anyone trying
-to better support CJKV languages/scripts in all the areas of
-information processing.
-
-To purchase this book, visit
-L<http://oreilly.com/catalog/9780596514471/>
-or your favourite bookstore.
-
-=back
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/ExtUtils/MakeMaker/FAQ.pod b/Master/tlpkg/tlperl/lib/ExtUtils/MakeMaker/FAQ.pod
deleted file mode 100644
index 675c95fc11e..00000000000
--- a/Master/tlpkg/tlperl/lib/ExtUtils/MakeMaker/FAQ.pod
+++ /dev/null
@@ -1,435 +0,0 @@
-package ExtUtils::MakeMaker::FAQ;
-
-our $VERSION = '6.63_02';
-
-1;
-__END__
-
-=head1 NAME
-
-ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker
-
-=head1 DESCRIPTION
-
-FAQs, tricks and tips for C<ExtUtils::MakeMaker>.
-
-
-=head2 Module Installation
-
-=over 4
-
-=item How do I install a module into my home directory?
-
-If you're not the Perl administrator you probably don't have
-permission to install a module to its default location. Then you
-should install it for your own use into your home directory like so:
-
- # Non-unix folks, replace ~ with /path/to/your/home/dir
- perl Makefile.PL INSTALL_BASE=~
-
-This will put modules into F<~/lib/perl5>, man pages into F<~/man> and
-programs into F<~/bin>.
-
-To ensure your Perl programs can see these newly installed modules,
-set your C<PERL5LIB> environment variable to F<~/lib/perl5> or tell
-each of your programs to look in that directory with the following:
-
- use lib "$ENV{HOME}/lib/perl5";
-
-or if $ENV{HOME} isn't set and you don't want to set it for some
-reason, do it the long way.
-
- use lib "/path/to/your/home/dir/lib/perl5";
-
-
-=item How do I get MakeMaker and Module::Build to install to the same place?
-
-Module::Build, as of 0.28, supports two ways to install to the same
-location as MakeMaker.
-
-1) Use INSTALL_BASE / C<--install_base>
-
-MakeMaker (as of 6.31) and Module::Build (as of 0.28) both can install
-to the same locations using the "install_base" concept. See
-L<ExtUtils::MakeMaker/INSTALL_BASE> for details. To get MM and MB to
-install to the same location simply set INSTALL_BASE in MM and
-C<--install_base> in MB to the same location.
-
- perl Makefile.PL INSTALL_BASE=/whatever
- perl Build.PL --install_base /whatever
-
-2) Use PREFIX / C<--prefix>
-
-Module::Build 0.28 added support for C<--prefix> which works like
-MakeMaker's PREFIX.
-
- perl Makefile.PL PREFIX=/whatever
- perl Build.PL --prefix /whatever
-
-
-=item How do I keep from installing man pages?
-
-Recent versions of MakeMaker will only install man pages on Unix like
-operating systems.
-
-For an individual module:
-
- perl Makefile.PL INSTALLMAN1DIR=none INSTALLMAN3DIR=none
-
-If you want to suppress man page installation for all modules you have
-to reconfigure Perl and tell it 'none' when it asks where to install
-man pages.
-
-
-=item How do I use a module without installing it?
-
-Two ways. One is to build the module normally...
-
- perl Makefile.PL
- make
- make test
-
-...and then set the PERL5LIB environment variable to point at the
-blib/lib and blib/arch directories.
-
-The other is to install the module in a temporary location.
-
- perl Makefile.PL INSTALL_BASE=~/tmp
- make
- make test
- make install
-
-And then set PERL5LIB to F<~/tmp/lib/perl5>. This works well when you
-have multiple modules to work with. It also ensures that the module
-goes through its full installation process which may modify it.
-
-=item PREFIX vs INSTALL_BASE from Module::Build::Cookbook
-
-The behavior of PREFIX is complicated and depends closely on how your
-Perl is configured. The resulting installation locations will vary from
-machine to machine and even different installations of Perl on the same machine.
-Because of this, its difficult to document where prefix will place your modules.
-
-In contrast, INSTALL_BASE has predictable, easy to explain installation locations.
-Now that Module::Build and MakeMaker both have INSTALL_BASE there is little reason
-to use PREFIX other than to preserve your existing installation locations. If you
-are starting a fresh Perl installation we encourage you to use INSTALL_BASE. If
-you have an existing installation installed via PREFIX, consider moving it to an
-installation structure matching INSTALL_BASE and using that instead.
-
-=back
-
-
-=head2 Philosophy and History
-
-=over 4
-
-=item Why not just use <insert other build config tool here>?
-
-Why did MakeMaker reinvent the build configuration wheel? Why not
-just use autoconf or automake or ppm or Ant or ...
-
-There are many reasons, but the major one is cross-platform
-compatibility.
-
-Perl is one of the most ported pieces of software ever. It works on
-operating systems I've never even heard of (see perlport for details).
-It needs a build tool that can work on all those platforms and with
-any wacky C compilers and linkers they might have.
-
-No such build tool exists. Even make itself has wildly different
-dialects. So we have to build our own.
-
-
-=item What is Module::Build and how does it relate to MakeMaker?
-
-Module::Build is a project by Ken Williams to supplant MakeMaker.
-Its primary advantages are:
-
-=over 8
-
-=item * pure perl. no make, no shell commands
-
-=item * easier to customize
-
-=item * cleaner internals
-
-=item * less cruft
-
-=back
-
-Module::Build is the official heir apparent to MakeMaker and we
-encourage people to work on M::B rather than spending time adding features
-to MakeMaker.
-
-=back
-
-
-=head2 Module Writing
-
-=over 4
-
-=item How do I keep my $VERSION up to date without resetting it manually?
-
-Often you want to manually set the $VERSION in the main module
-distribution because this is the version that everybody sees on CPAN
-and maybe you want to customize it a bit. But for all the other
-modules in your dist, $VERSION is really just bookkeeping and all that's
-important is it goes up every time the module is changed. Doing this
-by hand is a pain and you often forget.
-
-Simplest way to do it automatically is to use your version control
-system's revision number (you are using version control, right?).
-
-In CVS, RCS and SVN you use $Revision$ (see the documentation of your
-version control system for details). Every time the file is checked
-in the $Revision$ will be updated, updating your $VERSION.
-
-SVN uses a simple integer for $Revision$ so you can adapt it for your
-$VERSION like so:
-
- ($VERSION) = q$Revision$ =~ /(\d+)/;
-
-In CVS and RCS version 1.9 is followed by 1.10. Since CPAN compares
-version numbers numerically we use a sprintf() to convert 1.9 to 1.009
-and 1.10 to 1.010 which compare properly.
-
- $VERSION = sprintf "%d.%03d", q$Revision$ =~ /(\d+)\.(\d+)/g;
-
-If branches are involved (ie. $Revision: 1.5.3.4$) its a little more
-complicated.
-
- # must be all on one line or MakeMaker will get confused.
- $VERSION = do { my @r = (q$Revision$ =~ /\d+/g); sprintf "%d."."%03d" x $#r, @r };
-
-In SVN, $Revision$ should be the same for every file in the project so
-they would all have the same $VERSION. CVS and RCS have a different
-$Revision$ per file so each file will have a differnt $VERSION.
-Distributed version control systems, such as SVK, may have a different
-$Revision$ based on who checks out the file leading to a different $VERSION
-on each machine! Finally, some distributed version control systems, such
-as darcs, have no concept of revision number at all.
-
-
-=item What's this F<META.yml> thing and how did it get in my F<MANIFEST>?!
-
-F<META.yml> is a module meta-data file pioneered by Module::Build and
-automatically generated as part of the 'distdir' target (and thus
-'dist'). See L<ExtUtils::MakeMaker/"Module Meta-Data">.
-
-To shut off its generation, pass the C<NO_META> flag to C<WriteMakefile()>.
-
-
-=item How do I delete everything not in my F<MANIFEST>?
-
-Some folks are surpried that C<make distclean> does not delete
-everything not listed in their MANIFEST (thus making a clean
-distribution) but only tells them what they need to delete. This is
-done because it is considered too dangerous. While developing your
-module you might write a new file, not add it to the MANIFEST, then
-run a C<distclean> and be sad because your new work was deleted.
-
-If you really want to do this, you can use
-C<ExtUtils::Manifest::manifind()> to read the MANIFEST and File::Find
-to delete the files. But you have to be careful. Here's a script to
-do that. Use at your own risk. Have fun blowing holes in your foot.
-
- #!/usr/bin/perl -w
-
- use strict;
-
- use File::Spec;
- use File::Find;
- use ExtUtils::Manifest qw(maniread);
-
- my %manifest = map {( $_ => 1 )}
- grep { File::Spec->canonpath($_) }
- keys %{ maniread() };
-
- if( !keys %manifest ) {
- print "No files found in MANIFEST. Stopping.\n";
- exit;
- }
-
- find({
- wanted => sub {
- my $path = File::Spec->canonpath($_);
-
- return unless -f $path;
- return if exists $manifest{ $path };
-
- print "unlink $path\n";
- unlink $path;
- },
- no_chdir => 1
- },
- "."
- );
-
-
-=item Which tar should I use on Windows?
-
-We recommend ptar from Archive::Tar not older that 1.66 with '-C' option.
-
-=item Which zip should I use on Windows for '[nd]make zipdist'?
-
-We recommend InfoZIP: L<http://www.info-zip.org/Zip.html>
-
-
-=back
-
-=head2 XS
-
-=over 4
-
-=item How to I prevent "object version X.XX does not match bootstrap parameter Y.YY" errors?
-
-XS code is very sensitive to the module version number and will
-complain if the version number in your Perl module doesn't match. If
-you change your module's version # without rerunning Makefile.PL the old
-version number will remain in the Makefile causing the XS code to be built
-with the wrong number.
-
-To avoid this, you can force the Makefile to be rebuilt whenever you
-change the module containing the version number by adding this to your
-WriteMakefile() arguments.
-
- depend => { '$(FIRST_MAKEFILE)' => '$(VERSION_FROM)' }
-
-
-=item How do I make two or more XS files coexist in the same directory?
-
-Sometimes you need to have two and more XS files in the same package.
-One way to go is to put them into separate directories, but sometimes
-this is not the most suitable solution. The following technique allows
-you to put two (and more) XS files in the same directory.
-
-Let's assume that we have a package C<Cool::Foo>, which includes
-C<Cool::Foo> and C<Cool::Bar> modules each having a separate XS
-file. First we use the following I<Makefile.PL>:
-
- use ExtUtils::MakeMaker;
-
- WriteMakefile(
- NAME => 'Cool::Foo',
- VERSION_FROM => 'Foo.pm',
- OBJECT => q/$(O_FILES)/,
- # ... other attrs ...
- );
-
-Notice the C<OBJECT> attribute. MakeMaker generates the following
-variables in I<Makefile>:
-
- # Handy lists of source code files:
- XS_FILES= Bar.xs \
- Foo.xs
- C_FILES = Bar.c \
- Foo.c
- O_FILES = Bar.o \
- Foo.o
-
-Therefore we can use the C<O_FILES> variable to tell MakeMaker to use
-these objects into the shared library.
-
-That's pretty much it. Now write I<Foo.pm> and I<Foo.xs>, I<Bar.pm>
-and I<Bar.xs>, where I<Foo.pm> bootstraps the shared library and
-I<Bar.pm> simply loading I<Foo.pm>.
-
-The only issue left is to how to bootstrap I<Bar.xs>. This is done
-from I<Foo.xs>:
-
- MODULE = Cool::Foo PACKAGE = Cool::Foo
-
- BOOT:
- # boot the second XS file
- boot_Cool__Bar(aTHX_ cv);
-
-If you have more than two files, this is the place where you should
-boot extra XS files from.
-
-The following four files sum up all the details discussed so far.
-
- Foo.pm:
- -------
- package Cool::Foo;
-
- require DynaLoader;
-
- our @ISA = qw(DynaLoader);
- our $VERSION = '0.01';
- bootstrap Cool::Foo $VERSION;
-
- 1;
-
- Bar.pm:
- -------
- package Cool::Bar;
-
- use Cool::Foo; # bootstraps Bar.xs
-
- 1;
-
- Foo.xs:
- -------
- #include "EXTERN.h"
- #include "perl.h"
- #include "XSUB.h"
-
- MODULE = Cool::Foo PACKAGE = Cool::Foo
-
- BOOT:
- # boot the second XS file
- boot_Cool__Bar(aTHX_ cv);
-
- MODULE = Cool::Foo PACKAGE = Cool::Foo PREFIX = cool_foo_
-
- void
- cool_foo_perl_rules()
-
- CODE:
- fprintf(stderr, "Cool::Foo says: Perl Rules\n");
-
- Bar.xs:
- -------
- #include "EXTERN.h"
- #include "perl.h"
- #include "XSUB.h"
-
- MODULE = Cool::Bar PACKAGE = Cool::Bar PREFIX = cool_bar_
-
- void
- cool_bar_perl_rules()
-
- CODE:
- fprintf(stderr, "Cool::Bar says: Perl Rules\n");
-
-And of course a very basic test:
-
- t/cool.t:
- --------
- use Test;
- BEGIN { plan tests => 1 };
- use Cool::Foo;
- use Cool::Bar;
- Cool::Foo::perl_rules();
- Cool::Bar::perl_rules();
- ok 1;
-
-This tip has been brought to you by Nick Ing-Simmons and Stas Bekman.
-
-=back
-
-=head1 PATCHING
-
-If you have a question you'd like to see added to the FAQ (whether or
-not you have the answer) please send it to makemaker@perl.org.
-
-=head1 AUTHOR
-
-The denizens of makemaker@perl.org.
-
-=head1 SEE ALSO
-
-L<ExtUtils::MakeMaker>
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/ExtUtils/MakeMaker/Tutorial.pod b/Master/tlpkg/tlperl/lib/ExtUtils/MakeMaker/Tutorial.pod
deleted file mode 100644
index 5120271979f..00000000000
--- a/Master/tlpkg/tlperl/lib/ExtUtils/MakeMaker/Tutorial.pod
+++ /dev/null
@@ -1,180 +0,0 @@
-package ExtUtils::MakeMaker::Tutorial;
-
-our $VERSION = 6.63_02;
-
-
-=head1 NAME
-
-ExtUtils::MakeMaker::Tutorial - Writing a module with MakeMaker
-
-=head1 SYNOPSIS
-
- use ExtUtils::MakeMaker;
-
- WriteMakefile(
- NAME => 'Your::Module',
- VERSION_FROM => 'lib/Your/Module.pm'
- );
-
-=head1 DESCRIPTION
-
-This is a short tutorial on writing a simple module with MakeMaker.
-Its really not that hard.
-
-
-=head2 The Mantra
-
-MakeMaker modules are installed using this simple mantra
-
- perl Makefile.PL
- make
- make test
- make install
-
-There are lots more commands and options, but the above will do it.
-
-
-=head2 The Layout
-
-The basic files in a module look something like this.
-
- Makefile.PL
- MANIFEST
- lib/Your/Module.pm
-
-That's all that's strictly necessary. There's additional files you might
-want:
-
- lib/Your/Other/Module.pm
- t/some_test.t
- t/some_other_test.t
- Changes
- README
- INSTALL
- MANIFEST.SKIP
- bin/some_program
-
-=over 4
-
-=item Makefile.PL
-
-When you run Makefile.PL, it makes a Makefile. That's the whole point of
-MakeMaker. The Makefile.PL is a simple program which loads
-ExtUtils::MakeMaker and runs the WriteMakefile() function to generate a
-Makefile.
-
-Here's an example of what you need for a simple module:
-
- use ExtUtils::MakeMaker;
-
- WriteMakefile(
- NAME => 'Your::Module',
- VERSION_FROM => 'lib/Your/Module.pm'
- );
-
-NAME is the top-level namespace of your module. VERSION_FROM is the file
-which contains the $VERSION variable for the entire distribution. Typically
-this is the same as your top-level module.
-
-
-=item MANIFEST
-
-A simple listing of all the files in your distribution.
-
- Makefile.PL
- MANIFEST
- lib/Your/Module.pm
-
-File paths in a MANIFEST always use Unix conventions (ie. /) even if you're
-not on Unix.
-
-You can write this by hand or generate it with 'make manifest'.
-
-See L<ExtUtils::Manifest> for more details.
-
-
-=item lib/
-
-This is the directory where your .pm and .pod files you wish to have
-installed go. They are layed out according to namespace. So Foo::Bar
-is F<lib/Foo/Bar.pm>.
-
-
-=item t/
-
-Tests for your modules go here. Each test filename ends with a .t.
-So F<t/foo.t>/ 'make test' will run these tests. The directory is flat,
-you cannot, for example, have t/foo/bar.t run by 'make test'.
-
-Tests are run from the top level of your distribution. So inside a test
-you would refer to ./lib to enter the lib directory, for example.
-
-
-=item Changes
-
-A log of changes you've made to this module. The layout is free-form.
-Here's an example:
-
- 1.01 Fri Apr 11 00:21:25 PDT 2003
- - thing() does some stuff now
- - fixed the wiggy bug in withit()
-
- 1.00 Mon Apr 7 00:57:15 PDT 2003
- - "Rain of Frogs" now supported
-
-
-=item README
-
-A short description of your module, what it does, why someone would use it
-and its limitations. CPAN automatically pulls your README file out of
-the archive and makes it available to CPAN users, it is the first thing
-they will read to decide if your module is right for them.
-
-
-=item INSTALL
-
-Instructions on how to install your module along with any dependencies.
-Suggested information to include here:
-
- any extra modules required for use
- the minimum version of Perl required
- if only works on certain operating systems
-
-
-=item MANIFEST.SKIP
-
-A file full of regular expressions to exclude when using 'make
-manifest' to generate the MANIFEST. These regular expressions
-are checked against each file path found in the distribution (so
-you're matching against "t/foo.t" not "foo.t").
-
-Here's a sample:
-
- ~$ # ignore emacs and vim backup files
- .bak$ # ignore manual backups
- \# # ignore CVS old revision files and emacs temp files
-
-Since # can be used for comments, # must be escaped.
-
-MakeMaker comes with a default MANIFEST.SKIP to avoid things like
-version control directories and backup files. Specifying your own
-will override this default.
-
-
-=item bin/
-
-
-=back
-
-=head1 SEE ALSO
-
-L<perlmodstyle> gives stylistic help writing a module.
-
-L<perlnewmod> gives more information about how to write a module.
-
-There are modules to help you through the process of writing a module:
-L<ExtUtils::ModuleMaker>, L<Module::Install>, L<PAR>
-
-=cut
-
-1;
diff --git a/Master/tlpkg/tlperl/lib/ExtUtils/ParseXS.pod b/Master/tlpkg/tlperl/lib/ExtUtils/ParseXS.pod
deleted file mode 100644
index e0d1511e4a9..00000000000
--- a/Master/tlpkg/tlperl/lib/ExtUtils/ParseXS.pod
+++ /dev/null
@@ -1,161 +0,0 @@
-=head1 NAME
-
-ExtUtils::ParseXS - converts Perl XS code into C code
-
-=head1 SYNOPSIS
-
- use ExtUtils::ParseXS qw(process_file);
-
- process_file( filename => 'foo.xs' );
-
- process_file( filename => 'foo.xs',
- output => 'bar.c',
- 'C++' => 1,
- typemap => 'path/to/typemap',
- hiertype => 1,
- except => 1,
- prototypes => 1,
- versioncheck => 1,
- linenumbers => 1,
- optimize => 1,
- prototypes => 1,
- );
-
-=head1 DESCRIPTION
-
-C<ExtUtils::ParseXS> will compile XS code into C code by embedding the constructs
-necessary to let C functions manipulate Perl values and creates the glue
-necessary to let Perl access those functions. The compiler uses typemaps to
-determine how to map C function parameters and variables to Perl values.
-
-The compiler will search for typemap files called I<typemap>. It will use
-the following search path to find default typemaps, with the rightmost
-typemap taking precedence.
-
- ../../../typemap:../../typemap:../typemap:typemap
-
-=head1 EXPORT
-
-None by default. C<process_file()> may be exported upon request.
-
-=head1 FUNCTIONS
-
-=over 4
-
-=item process_file()
-
-This function processes an XS file and sends output to a C file.
-Named parameters control how the processing is done. The following
-parameters are accepted:
-
-=over 4
-
-=item B<C++>
-
-Adds C<extern "C"> to the C code. Default is false.
-
-=item B<hiertype>
-
-Retains C<::> in type names so that C++ hierarchical types can be
-mapped. Default is false.
-
-=item B<except>
-
-Adds exception handling stubs to the C code. Default is false.
-
-=item B<typemap>
-
-Indicates that a user-supplied typemap should take precedence over the
-default typemaps. A single typemap may be specified as a string, or
-multiple typemaps can be specified in an array reference, with the
-last typemap having the highest precedence.
-
-=item B<prototypes>
-
-Generates prototype code for all xsubs. Default is false.
-
-=item B<versioncheck>
-
-Makes sure at run time that the object file (derived from the C<.xs>
-file) and the C<.pm> files have the same version number. Default is
-true.
-
-=item B<linenumbers>
-
-Adds C<#line> directives to the C output so error messages will look
-like they came from the original XS file. Default is true.
-
-=item B<optimize>
-
-Enables certain optimizations. The only optimization that is currently
-affected is the use of I<target>s by the output C code (see L<perlguts>).
-Not optimizing may significantly slow down the generated code, but this is the way
-B<xsubpp> of 5.005 and earlier operated. Default is to optimize.
-
-=item B<inout>
-
-Enable recognition of C<IN>, C<OUT_LIST> and C<INOUT_LIST>
-declarations. Default is true.
-
-=item B<argtypes>
-
-Enable recognition of ANSI-like descriptions of function signature.
-Default is true.
-
-=item B<s>
-
-I<Maintainer note:> I have no clue what this does. Strips function prefixes?
-
-=back
-
-=item errors()
-
-This function returns the number of [a certain kind of] errors
-encountered during processing of the XS file.
-
-=back
-
-=head1 AUTHOR
-
-Based on xsubpp code, written by Larry Wall.
-
-Maintained by:
-
-=over 4
-
-=item *
-
-Ken Williams, <ken@mathforum.org>
-
-=item *
-
-David Golden, <dagolden@cpan.org>
-
-=item *
-
-James Keenan, <jkeenan@cpan.org>
-
-=item *
-
-Steffen Mueller, <smueller@cpan.org>
-
-=back
-
-=head1 COPYRIGHT
-
-Copyright 2002-2012 by Ken Williams, David Golden and other contributors. All
-rights reserved.
-
-This library is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-Based on the C<ExtUtils::xsubpp> code by Larry Wall and the Perl 5
-Porters, which was released under the same license terms.
-
-=head1 SEE ALSO
-
-L<perl>, ExtUtils::xsubpp, ExtUtils::MakeMaker, L<perlxs>, L<perlxstut>.
-
-=cut
-
-
diff --git a/Master/tlpkg/tlperl/lib/IO/Compress/FAQ.pod b/Master/tlpkg/tlperl/lib/IO/Compress/FAQ.pod
deleted file mode 100644
index d392ff2cc91..00000000000
--- a/Master/tlpkg/tlperl/lib/IO/Compress/FAQ.pod
+++ /dev/null
@@ -1,597 +0,0 @@
-
-=head1 NAME
-
-IO::Compress::FAQ -- Frequently Asked Questions about IO::Compress
-
-=head1 DESCRIPTION
-
-Common questions answered.
-
-=head1 GENERAL
-
-=head2 Compatibility with Unix compress/uncompress.
-
-Although C<Compress::Zlib> has a pair of functions called C<compress> and
-C<uncompress>, they are I<not> related to the Unix programs of the same
-name. The C<Compress::Zlib> module is not compatible with Unix
-C<compress>.
-
-If you have the C<uncompress> program available, you can use this to read
-compressed files
-
- open F, "uncompress -c $filename |";
- while (<F>)
- {
- ...
-
-Alternatively, if you have the C<gunzip> program available, you can use
-this to read compressed files
-
- open F, "gunzip -c $filename |";
- while (<F>)
- {
- ...
-
-and this to write compress files, if you have the C<compress> program
-available
-
- open F, "| compress -c $filename ";
- print F "data";
- ...
- close F ;
-
-=head2 Accessing .tar.Z files
-
-The C<Archive::Tar> module can optionally use C<Compress::Zlib> (via the
-C<IO::Zlib> module) to access tar files that have been compressed with
-C<gzip>. Unfortunately tar files compressed with the Unix C<compress>
-utility cannot be read by C<Compress::Zlib> and so cannot be directly
-accessed by C<Archive::Tar>.
-
-If the C<uncompress> or C<gunzip> programs are available, you can use one
-of these workarounds to read C<.tar.Z> files from C<Archive::Tar>
-
-Firstly with C<uncompress>
-
- use strict;
- use warnings;
- use Archive::Tar;
-
- open F, "uncompress -c $filename |";
- my $tar = Archive::Tar->new(*F);
- ...
-
-and this with C<gunzip>
-
- use strict;
- use warnings;
- use Archive::Tar;
-
- open F, "gunzip -c $filename |";
- my $tar = Archive::Tar->new(*F);
- ...
-
-Similarly, if the C<compress> program is available, you can use this to
-write a C<.tar.Z> file
-
- use strict;
- use warnings;
- use Archive::Tar;
- use IO::File;
-
- my $fh = new IO::File "| compress -c >$filename";
- my $tar = Archive::Tar->new();
- ...
- $tar->write($fh);
- $fh->close ;
-
-=head2 How do I recompress using a different compression?
-
-This is easier that you might expect if you realise that all the
-C<IO::Compress::*> objects are derived from C<IO::File> and that all the
-C<IO::Uncompress::*> modules can read from an C<IO::File> filehandle.
-
-So, for example, say you have a file compressed with gzip that you want to
-recompress with bzip2. Here is all that is needed to carry out the
-recompression.
-
- use IO::Uncompress::Gunzip ':all';
- use IO::Compress::Bzip2 ':all';
-
- my $gzipFile = "somefile.gz";
- my $bzipFile = "somefile.bz2";
-
- my $gunzip = new IO::Uncompress::Gunzip $gzipFile
- or die "Cannot gunzip $gzipFile: $GunzipError\n" ;
-
- bzip2 $gunzip => $bzipFile
- or die "Cannot bzip2 to $bzipFile: $Bzip2Error\n" ;
-
-Note, there is a limitation of this technique. Some compression file
-formats store extra information along with the compressed data payload. For
-example, gzip can optionally store the original filename and Zip stores a
-lot of information about the original file. If the original compressed file
-contains any of this extra information, it will not be transferred to the
-new compressed file usign the technique above.
-
-=head1 ZIP
-
-=head2 What Compression Types do IO::Compress::Zip & IO::Uncompress::Unzip support?
-
-The following compression formats are supported by C<IO::Compress::Zip> and
-C<IO::Uncompress::Unzip>
-
-=over 5
-
-=item * Store (method 0)
-
-No compression at all.
-
-=item * Deflate (method 8)
-
-This is the default compression used when creating a zip file with
-C<IO::Compress::Zip>.
-
-=item * Bzip2 (method 12)
-
-Only supported if the C<IO-Compress-Bzip2> module is installed.
-
-=item * Lzma (method 14)
-
-Only supported if the C<IO-Compress-Lzma> module is installed.
-
-=back
-
-=head2 Can I Read/Write Zip files larger the 4 Gig?
-
-Yes, both the C<IO-Compress-Zip> and C<IO-Uncompress-Unzip> modules
-support the zip feature called I<Zip64>. That allows them to read/write
-files/buffers larger than 4Gig.
-
-If you are creating a Zip file using the one-shot interface, and any of the
-input files is greater than 4Gig, a zip64 complaint zip file will be
-created.
-
- zip "really-large-file" => "my.zip";
-
-Similarly with the one-shot interface, if the input is a buffer larger than
-4 Gig, a zip64 complaint zip file will be created.
-
- zip \$really_large_buffer => "my.zip";
-
-The one-shot interface allows you to force the creation of a zip64 zip file
-by including the C<Zip64> option.
-
- zip $filehandle => "my.zip", Zip64 => 1;
-
-If you want to create a zip64 zip file with the OO interface you must
-specify the C<Zip64> option.
-
- my $zip = new IO::Compress::Zip "whatever", Zip64 => 1;
-
-When uncompressing with C<IO-Uncompress-Unzip>, it will automatically
-detect if the zip file is zip64.
-
-If you intend to manipulate the Zip64 zip files created with
-C<IO-Compress-Zip> using an external zip/unzip, make sure that it supports
-Zip64.
-
-In particular, if you are using Info-Zip you need to have zip version 3.x
-or better to update a Zip64 archive and unzip version 6.x to read a zip64
-archive.
-
-=head2 Zip Resources
-
-The primary reference for zip files is the "appnote" document available at
-L<http://www.pkware.com/documents/casestudies/APPNOTE.TXT>
-
-An alternatively is the Info-Zip appnote. This is available from
-L<ftp://ftp.info-zip.org/pub/infozip/doc/>
-
-=head1 GZIP
-
-=head2 Gzip Resources
-
-The primary reference for gzip files is RFC 1952
-L<http://www.faqs.org/rfcs/rfc1952.html>
-
-The primary site for gzip is F<http://www.gzip.org>.
-
-=head1 ZLIB
-
-=head2 Zlib Resources
-
-The primary site for the I<zlib> compression library is
-F<http://www.zlib.org>.
-
-=head1 HTTP & NETWORK
-
-=head2 Apache::GZip Revisited
-
-Below is a mod_perl Apache compression module, called C<Apache::GZip>,
-taken from
-F<http://perl.apache.org/docs/tutorials/tips/mod_perl_tricks/mod_perl_tricks.html#On_the_Fly_Compression>
-
- package Apache::GZip;
- #File: Apache::GZip.pm
-
- use strict vars;
- use Apache::Constants ':common';
- use Compress::Zlib;
- use IO::File;
- use constant GZIP_MAGIC => 0x1f8b;
- use constant OS_MAGIC => 0x03;
-
- sub handler {
- my $r = shift;
- my ($fh,$gz);
- my $file = $r->filename;
- return DECLINED unless $fh=IO::File->new($file);
- $r->header_out('Content-Encoding'=>'gzip');
- $r->send_http_header;
- return OK if $r->header_only;
-
- tie *STDOUT,'Apache::GZip',$r;
- print($_) while <$fh>;
- untie *STDOUT;
- return OK;
- }
-
- sub TIEHANDLE {
- my($class,$r) = @_;
- # initialize a deflation stream
- my $d = deflateInit(-WindowBits=>-MAX_WBITS()) || return undef;
-
- # gzip header -- don't ask how I found out
- $r->print(pack("nccVcc",GZIP_MAGIC,Z_DEFLATED,0,time(),0,OS_MAGIC));
-
- return bless { r => $r,
- crc => crc32(undef),
- d => $d,
- l => 0
- },$class;
- }
-
- sub PRINT {
- my $self = shift;
- foreach (@_) {
- # deflate the data
- my $data = $self->{d}->deflate($_);
- $self->{r}->print($data);
- # keep track of its length and crc
- $self->{l} += length($_);
- $self->{crc} = crc32($_,$self->{crc});
- }
- }
-
- sub DESTROY {
- my $self = shift;
-
- # flush the output buffers
- my $data = $self->{d}->flush;
- $self->{r}->print($data);
-
- # print the CRC and the total length (uncompressed)
- $self->{r}->print(pack("LL",@{$self}{qw/crc l/}));
- }
-
- 1;
-
-Here's the Apache configuration entry you'll need to make use of it. Once
-set it will result in everything in the /compressed directory will be
-compressed automagically.
-
- <Location /compressed>
- SetHandler perl-script
- PerlHandler Apache::GZip
- </Location>
-
-Although at first sight there seems to be quite a lot going on in
-C<Apache::GZip>, you could sum up what the code was doing as follows --
-read the contents of the file in C<< $r->filename >>, compress it and write
-the compressed data to standard output. That's all.
-
-This code has to jump through a few hoops to achieve this because
-
-=over
-
-=item 1.
-
-The gzip support in C<Compress::Zlib> version 1.x can only work with a real
-filesystem filehandle. The filehandles used by Apache modules are not
-associated with the filesystem.
-
-=item 2.
-
-That means all the gzip support has to be done by hand - in this case by
-creating a tied filehandle to deal with creating the gzip header and
-trailer.
-
-=back
-
-C<IO::Compress::Gzip> doesn't have that filehandle limitation (this was one
-of the reasons for writing it in the first place). So if
-C<IO::Compress::Gzip> is used instead of C<Compress::Zlib> the whole tied
-filehandle code can be removed. Here is the rewritten code.
-
- package Apache::GZip;
-
- use strict vars;
- use Apache::Constants ':common';
- use IO::Compress::Gzip;
- use IO::File;
-
- sub handler {
- my $r = shift;
- my ($fh,$gz);
- my $file = $r->filename;
- return DECLINED unless $fh=IO::File->new($file);
- $r->header_out('Content-Encoding'=>'gzip');
- $r->send_http_header;
- return OK if $r->header_only;
-
- my $gz = new IO::Compress::Gzip '-', Minimal => 1
- or return DECLINED ;
-
- print $gz $_ while <$fh>;
-
- return OK;
- }
-
-or even more succinctly, like this, using a one-shot gzip
-
- package Apache::GZip;
-
- use strict vars;
- use Apache::Constants ':common';
- use IO::Compress::Gzip qw(gzip);
-
- sub handler {
- my $r = shift;
- $r->header_out('Content-Encoding'=>'gzip');
- $r->send_http_header;
- return OK if $r->header_only;
-
- gzip $r->filename => '-', Minimal => 1
- or return DECLINED ;
-
- return OK;
- }
-
- 1;
-
-The use of one-shot C<gzip> above just reads from C<< $r->filename >> and
-writes the compressed data to standard output.
-
-Note the use of the C<Minimal> option in the code above. When using gzip
-for Content-Encoding you should I<always> use this option. In the example
-above it will prevent the filename being included in the gzip header and
-make the size of the gzip data stream a slight bit smaller.
-
-=head2 Compressed files and Net::FTP
-
-The C<Net::FTP> module provides two low-level methods called C<stor> and
-C<retr> that both return filehandles. These filehandles can used with the
-C<IO::Compress/Uncompress> modules to compress or uncompress files read
-from or written to an FTP Server on the fly, without having to create a
-temporary file.
-
-Firstly, here is code that uses C<retr> to uncompressed a file as it is
-read from the FTP Server.
-
- use Net::FTP;
- use IO::Uncompress::Gunzip qw(:all);
-
- my $ftp = new Net::FTP ...
-
- my $retr_fh = $ftp->retr($compressed_filename);
- gunzip $retr_fh => $outFilename, AutoClose => 1
- or die "Cannot uncompress '$compressed_file': $GunzipError\n";
-
-and this to compress a file as it is written to the FTP Server
-
- use Net::FTP;
- use IO::Compress::Gzip qw(:all);
-
- my $stor_fh = $ftp->stor($filename);
- gzip "filename" => $stor_fh, AutoClose => 1
- or die "Cannot compress '$filename': $GzipError\n";
-
-=head1 MISC
-
-=head2 Using C<InputLength> to uncompress data embedded in a larger file/buffer.
-
-A fairly common use-case is where compressed data is embedded in a larger
-file/buffer and you want to read both.
-
-As an example consider the structure of a zip file. This is a well-defined
-file format that mixes both compressed and uncompressed sections of data in
-a single file.
-
-For the purposes of this discussion you can think of a zip file as sequence
-of compressed data streams, each of which is prefixed by an uncompressed
-local header. The local header contains information about the compressed
-data stream, including the name of the compressed file and, in particular,
-the length of the compressed data stream.
-
-To illustrate how to use C<InputLength> here is a script that walks a zip
-file and prints out how many lines are in each compressed file (if you
-intend write code to walking through a zip file for real see
-L<IO::Uncompress::Unzip/"Walking through a zip file"> ). Also, although
-this example uses the zlib-based compression, the technique can be used by
-the other C<IO::Uncompress::*> modules.
-
- use strict;
- use warnings;
-
- use IO::File;
- use IO::Uncompress::RawInflate qw(:all);
-
- use constant ZIP_LOCAL_HDR_SIG => 0x04034b50;
- use constant ZIP_LOCAL_HDR_LENGTH => 30;
-
- my $file = $ARGV[0] ;
-
- my $fh = new IO::File "<$file"
- or die "Cannot open '$file': $!\n";
-
- while (1)
- {
- my $sig;
- my $buffer;
-
- my $x ;
- ($x = $fh->read($buffer, ZIP_LOCAL_HDR_LENGTH)) == ZIP_LOCAL_HDR_LENGTH
- or die "Truncated file: $!\n";
-
- my $signature = unpack ("V", substr($buffer, 0, 4));
-
- last unless $signature == ZIP_LOCAL_HDR_SIG;
-
- # Read Local Header
- my $gpFlag = unpack ("v", substr($buffer, 6, 2));
- my $compressedMethod = unpack ("v", substr($buffer, 8, 2));
- my $compressedLength = unpack ("V", substr($buffer, 18, 4));
- my $uncompressedLength = unpack ("V", substr($buffer, 22, 4));
- my $filename_length = unpack ("v", substr($buffer, 26, 2));
- my $extra_length = unpack ("v", substr($buffer, 28, 2));
-
- my $filename ;
- $fh->read($filename, $filename_length) == $filename_length
- or die "Truncated file\n";
-
- $fh->read($buffer, $extra_length) == $extra_length
- or die "Truncated file\n";
-
- if ($compressedMethod != 8 && $compressedMethod != 0)
- {
- warn "Skipping file '$filename' - not deflated $compressedMethod\n";
- $fh->read($buffer, $compressedLength) == $compressedLength
- or die "Truncated file\n";
- next;
- }
-
- if ($compressedMethod == 0 && $gpFlag & 8 == 8)
- {
- die "Streamed Stored not supported for '$filename'\n";
- }
-
- next if $compressedLength == 0;
-
- # Done reading the Local Header
-
- my $inf = new IO::Uncompress::RawInflate $fh,
- Transparent => 1,
- InputLength => $compressedLength
- or die "Cannot uncompress $file [$filename]: $RawInflateError\n" ;
-
- my $line_count = 0;
-
- while (<$inf>)
- {
- ++ $line_count;
- }
-
- print "$filename: $line_count\n";
- }
-
-The majority of the code above is concerned with reading the zip local
-header data. The code that I want to focus on is at the bottom.
-
- while (1) {
-
- # read local zip header data
- # get $filename
- # get $compressedLength
-
- my $inf = new IO::Uncompress::RawInflate $fh,
- Transparent => 1,
- InputLength => $compressedLength
- or die "Cannot uncompress $file [$filename]: $RawInflateError\n" ;
-
- my $line_count = 0;
-
- while (<$inf>)
- {
- ++ $line_count;
- }
-
- print "$filename: $line_count\n";
- }
-
-The call to C<IO::Uncompress::RawInflate> creates a new filehandle C<$inf>
-that can be used to read from the parent filehandle C<$fh>, uncompressing
-it as it goes. The use of the C<InputLength> option will guarantee that
-I<at most> C<$compressedLength> bytes of compressed data will be read from
-the C<$fh> filehandle (The only exception is for an error case like a
-truncated file or a corrupt data stream).
-
-This means that once RawInflate is finished C<$fh> will be left at the
-byte directly after the compressed data stream.
-
-Now consider what the code looks like without C<InputLength>
-
- while (1) {
-
- # read local zip header data
- # get $filename
- # get $compressedLength
-
- # read all the compressed data into $data
- read($fh, $data, $compressedLength);
-
- my $inf = new IO::Uncompress::RawInflate \$data,
- Transparent => 1,
- or die "Cannot uncompress $file [$filename]: $RawInflateError\n" ;
-
- my $line_count = 0;
-
- while (<$inf>)
- {
- ++ $line_count;
- }
-
- print "$filename: $line_count\n";
- }
-
-The difference here is the addition of the temporary variable C<$data>.
-This is used to store a copy of the compressed data while it is being
-uncompressed.
-
-If you know that C<$compressedLength> isn't that big then using temporary
-storage won't be a problem. But if C<$compressedLength> is very large or
-you are writing an application that other people will use, and so have no
-idea how big C<$compressedLength> will be, it could be an issue.
-
-Using C<InputLength> avoids the use of temporary storage and means the
-application can cope with large compressed data streams.
-
-One final point -- obviously C<InputLength> can only be used whenever you
-know the length of the compressed data beforehand, like here with a zip
-file.
-
-=head1 SEE ALSO
-
-L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzma>, L<IO::Uncompress::UnLzma>, L<IO::Compress::Xz>, L<IO::Uncompress::UnXz>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
-
-L<IO::Compress::FAQ|IO::Compress::FAQ>
-
-L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
-L<Archive::Tar|Archive::Tar>,
-L<IO::Zlib|IO::Zlib>
-
-=head1 AUTHOR
-
-This module was written by Paul Marquess, F<pmqs@cpan.org>.
-
-=head1 MODIFICATION HISTORY
-
-See the Changes file.
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright (c) 2005-2012 Paul Marquess. All rights reserved.
-
-This program is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes.pod b/Master/tlpkg/tlperl/lib/Locale/Codes.pod
deleted file mode 100644
index df10c849a1b..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Codes.pod
+++ /dev/null
@@ -1,285 +0,0 @@
-=pod
-
-=head1 NAME
-
-Locale::Codes - a distribution of modules to handle locale codes
-
-=head1 DESCRIPTION
-
-B<Locale-Codes> is a distribution containing a set of modules. The
-modules each deal with different types of codes which identify parts
-of the locale including languages, countries, currency, etc.
-
-Currently, the following modules are included:
-
-=over 4
-
-=item B<Locale::Codes::Country, Locale::Country>
-
-This includes support for country codes (such as those listed in ISO-3166)
-to specify the country.
-
-Because this module was originally distributed as Locale::Country, it is
-also available under that name.
-
-=item B<Locale::Codes::Language, Locale::Language>
-
-This includes support for language codes (such as those listed in ISO-639)
-to specify the language.
-
-Because this module was originally distributed as Locale::Language, it is
-also available under that name.
-
-=item B<Locale::Codes::Currency, Locale::Currency>
-
-This includes support for currency codes (such as those listed in ISO-4217)
-to specify the currency.
-
-Because this module was originally distributed as Locale::Currency, it is
-also available under that name.
-
-=item B<Locale::Codes::Script, Locale::Script>
-
-This includes support for script codes (such as those listed in ISO-15924)
-to specify the script.
-
-Because this module was originally distributed as Locale::Script, it is
-also available under that name.
-
-=item B<Locale::Codes::LangExt>
-
-This includes support for language extension codes (such as those listed
-in the IANA language registry) to specify the language extension.
-
-=item B<Locale::Codes::LangVar>
-
-This includes support for language variation codes (such as those listed
-in the IANA language registry) to specify the language variation.
-
-=item B<Locale::Codes::LangFam>
-
-This includes support for language family codes (such as those listed
-in ISO 639-5) to specify families of languages.
-
-=back
-
-Each module can support an arbitrary number of code sets, and it it
-not required that the relationship between these code sets be
-one-to-one. For example, the Locale::Codes::Country module supports
-code sets from ISO-3166 and the FIPS 10 standard, and they do not
-break the world down into exactly the same sets of countries. This
-does not cause any problem (though converting codes from ISO-3166 to
-FIPS or back will not work except for countries that are one-to-one).
-
-All data in all of these modules comes directly from the original
-standards (or as close to direct as possible), so it should be
-up-to-date at the time of release.
-
-I plan on releasing a new version several times a year to incorporate
-any changes made in the standards. However, I don't always know about
-changes that occur, so if any of the standards change, and you want a
-new release sooner, just email me and I'll get one out.
-
-In addition to the modules above, there are a number of support modules included
-in the distribution including:
-
-=over 4
-
-=item B<Locale::Codes>
-
-=item B<Locale::Codes::Constants>
-
-=item B<Locale::Codes::Country_codes>
-
-=item B<Locale::Codes::Language_codes>
-
-=item B<Locale::Codes::Currency_codes>
-
-=item B<Locale::Codes::Script_codes>
-
-=item B<Locale::Codes::LangExt_codes>
-
-=item B<Locale::Codes::LangVar_codes>
-
-=item B<Locale::Codes::LangFam_codes>
-
-=back
-
-These modules are not intended to be used by programmers. They contain functions
-or data that are used by the modules listed above.
-
-=head1 NEW CODE SETS
-
-I'm always open to suggestions for new code sets.
-
-In order for me to add a code set, I want the following criteria
-to be met:
-
-=over 4
-
-=item B<General-use code set>
-
-If a code set is not general use, I'm not likely to spend the time
-to add and support it.
-
-=item B<An official source of data>
-
-I require an official (or at least, a NEARLY official) source where I
-can get the data on a regular basis.
-
-Ideally, I'd only get data from an official source, but sometimes that
-is not possible. For example the ISO standards are not typically
-available for free, so I may have to get some of that data from
-alternate sources that I'm confident are getting their data from the
-official source. However, I will always be hesitant to accept a
-non-official source.
-
-As an example, I used to get some country data from the CIA World
-Factbook. Given the nature of the source, I'm sure they're updating
-data from the official sources and I consider it "nearly" official.
-However, even in this case, I found that they were adding codes that
-were not part of the standard, so I have stopped using them as a
-source.
-
-There are many 3rd party sites which maintain lists (many of which are
-actually in a more convenient form than the official sites).
-Unfortunately, I will reject most of them since I have no feel for how
-"official" they are.
-
-=item B<A free source of the data>
-
-Obviously, the data must be free-of-charge. I'm not interested in
-paying for the data (and I'm not interested in the overhead of having
-someone else pay for the data for me).
-
-=item B<A reliable source of data>
-
-The source of data must come from a source that I can reasonably expect
-to exist for the foreseeable future since I will be extremely reluctant
-to drop support for a data set once it's included.
-
-I am also reluctant to accept data sent to me by an individual.
-Although I appreciate the offer, it is simply not practical to consider
-an individual contribution as a reliable source of data. The source
-should be an official agency of some sort.
-
-=back
-
-These requirements are open to discussion. If you have a code set
-you'd like to see added, but which may not meet all of the above
-requirements, feel free to email me and we'll discuss it. Depending
-on circumstances, I may be willing to waive some of these criteria.
-
-=head1 COMMON ALIASES
-
-As of version 2.00, the modules supported common variants of names.
-
-For example, Locale::Country supports variant names for countries, and
-a few of the most common ones are included in the data. The country
-code for "United States" is "us", so:
-
- country2code('United States');
- => "us"
-
-Now the following will also return 'us':
-
- country2code('United States of America');
- country2code('USA');
-
-Any number of common aliases may be included in the data, in addition
-to the names that come directly from the standards. If you have a
-common alias for a country, language, or any other of the types of
-codes, let me know and I'll add it, with some restrictions.
-
-For example, the country name "North Korea" never appeared in any of
-the official sources (instead, it was "Korea, North" or "Korea,
-Democratic People's Republic of". I would honor a request to add an
-alias "North Korea" since that's a very common way to specify the
-country (please don't request this... I've already added it).
-
-On the other hand, a request to add Zaire as an alias for "Congo, The
-Democratic Republic of" will not be honored. The country's official
-name is no longer Zaire, so adding it as an alias violates the standard.
-Zaire was kept as an alias in versions prior to 3.00, but it has been
-removed. Other aliases (if any) which no longer appear in any standard
-(and which are not common variations of the name in the standards)
-have also been removed.
-
-=head1 DEPRECATED CODES
-
-Occasionally, a code is deprecated, but it may still be desirable to
-have access to it.
-
-Although there is no way to see every code that has ever existed and
-been deprecated (since most codesets do not have that information
-available), as of version 3.20, every code which has ever been included
-in these modules can be referenced.
-
-For more information, refer to the documentation on the code2XXX, XXX2code,
-all_XXX_codes, and all_XXX_names function in the B<Locale::Codes::API>
-documentation.
-
-=head1 SEE ALSO
-
-=over 4
-
-=item B<Locale::Codes::API>
-
-The list of functions available in each of the modules listed below.
-The APIs for each module are exactly identical.
-
-=item B<Locale::Codes::Country>
-
-Codes for identification of countries.
-
-=item B<Locale::Codes::Language>
-
-Codes for identification of languages.
-
-=item B<Locale::Codes::Script>
-
-Codes for identification of scripts.
-
-=item B<Locale::Codes::Currency>
-
-Codes for identification of currencies and funds.
-
-=item B<Locale::Codes::Changes>
-
-A history of changes made to this distribution.
-
-=back
-
-=head1 AUTHOR
-
-Locale::Country and Locale::Language were originally written by Neil
-Bowers at the Canon Research Centre Europe (CRE). They maintained the
-distribution from 1997 to 2001.
-
-Locale::Currency was originally written by Michael Hennecke and was
-modified by Neil Bowers for inclusion in the distribution.
-
-From 2001 to 2004, maintenance was continued by Neil Bowers. He
-modified Locale::Currency for inclusion in the distribution. He also
-added Locale::Constants and Locale::Script.
-
-From 2004-2009, the module was unmaintained.
-
-In 2010, maintenance was taken over by Sullivan Beck (sbeck@cpan.org)
-with Neil Bower's permission. All problems or comments should be
-sent there. Alternately, problems can be reported using the
-perl problem tracker at:
-
- https://rt.cpan.org/Dist/Display.html?Queue=Locale-Codes
-
-=head1 COPYRIGHT
-
- Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
- Copyright (c) 2001 Michael Hennecke (Locale::Currency)
- Copyright (c) 2001-2010 Neil Bowers
- Copyright (c) 2010-2012 Sullivan Beck
-
-This module is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/API.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/API.pod
deleted file mode 100644
index 1a566d2b157..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Codes/API.pod
+++ /dev/null
@@ -1,320 +0,0 @@
-=pod
-
-=head1 NAME
-
-Locale::Codes::API - a description of the callable function in each module
-
-=head1 DESCRIPTION
-
-Although there are several modules in the Locale-Codes distribution, all of them
-(as of version 3.10) use exactly the same API. As a matter of fact, each of the
-main callable modules are just wrappers around a central module which does all
-the real work.
-
-=head1 ROUTINES
-
-In order to maintain the documentation for the modules consistently,
-the functions are all documented here, rather than in the documentation
-for the separate modules.
-
-The name of the function depends on the module. For example, every module
-contains a function "code2XXX" where XXX refers to the type of data.
-The values of XXX are described in the following table:
-
- XXX MODULE
-
- country Locale::Codes::Country
- language Locale::Codes::Language
- currency Locale::Codes::Currency
- script Locale::Codes::Script
- langext Locale::Codes::LangExt
- langvar Locale::Codes::LangVar
- langfam Locale::Codes::LangFAM
-
-So, the Locale::Country module contains the function code2country, the
-Locale::Language module contains the function code2language, etc.
-
-In all of the functions below, CODE refers to a code for one element in
-the code set. For example, in the two-letter country codes from ISO 3166-1,
-the code 'fi' is used to refer to the country Finland. CODE is always
-case insensitive (though when a code is returned, it will always be in
-the case as used in the standard), so 'fi', 'FI', and 'Fi' would all
-be equivalent.
-
-CODESET refers to a constant specified in the documentation for each
-module to label the various code sets. For example, in the
-Locale::Language module, CODESET could be LOCALE_CODE_ALPHA_2 or
-LOCALE_CODE_ALPHA_3 (among others). Most functions have a default one,
-so they do not need to be specified. So the following calls are valid:
-
- code2country("fi");
- code2country("fi",LOCALE_CODE_ALPHA_2);
- code2country("fin",LOCALE_CODE_ALPHA_3);
-
-Since LOCALE_CODE_ALPHA_2 is the default code set, the first two are
-identical.
-
-=over 4
-
-=item B<code2XXX ( CODE [,CODESET] [,'retired'] )>
-
-These functions take a code and returns a string which contains
-the name of the element identified. If the code is not a valid
-code in the CODESET specified then C<undef> will be returned.
-
-The name of the element is the name as specified in the standard,
-and as a result, different variations of an element name may
-be returned for different values of CODESET.
-
-For example, the B<alpha-2> country code set defines the two-letter
-code "bo" to be "Bolivia, Plurinational State of", whereas the
-B<alpha-3> code set defines the code 'bol' to be the country "Bolivia
-(Plurinational State of)". So:
-
- code2country('bo',LOCALE_CODE_ALPHA_2);
- => 'Bolivia, Plurinational State of'
-
- code2country('bol',LOCALE_CODE_ALPHA_3);
- => 'Bolivia (Plurinational State of)'
-
-By default, only active codes will be used, but if the string
-'retired' is passed in as an argument, both active and retired
-codes will be examined.
-
-=item B<XXX2code ( NAME [,CODESET] [,'retired'] )>
-
-These functions takes the name of an element (or any of it's aliases)
-and returns the code that corresponds to it, if it exists. If NAME
-could not be identified as the name of one of the elements, then
-C<undef> will be returned.
-
-The name is not case sensitive. Also, any known variation of a name
-may be passed in.
-
-For example, even though the country name returned using
-LOCALE_CODE_ALPHA_2 and LOCALE_CODE_ALPHA_3 country codes for Bolivia is different,
-either country name may be passed in since for each code set, in addition to
-the alias 'Bolivia'. So:
-
- country2code('Bolivia, Plurinational State of',
- LOCALE_CODE_ALPHA_2);
- => bo
-
- country2code('Bolivia (Plurinational State of)',
- LOCALE_CODE_ALPHA_2);
- => bo
-
- country2code('Bolivia',LOCALE_CODE_ALPHA_2);
- => bo
-
-By default, only active names will be used, but if the string
-'retired' is passed in as an argument, both active and retired
-names will be examined.
-
-=item B<XXX_code2code ( CODE ,CODESET ,CODESET2 )>
-
-These functions takes a a code from one code set, and returns the
-corresponding code from another code set. CODE must exists in the code
-set specified by CODESET and must have a corresponding code in the
-code set specified by CODESET2 or C<undef> will be returned.
-
-Both CODESETs must be explicitly entered.
-
- country_code2code('fin', LOCALE_CODE_ALPHA_3,
- LOCALE_CODE_ALPHA_2);
- => 'fi'
-
-Note that this function does NOT support retired codes.
-
-=item B<all_XXX_codes ( [CODESET] [,'retired'] )>
-
-These returns a list of all code in the code set. The codes will be
-sorted.
-
-By default, only active codes will be returned, but if the string
-'retired' is passed in as an argument, both active and retired
-codes will be returned.
-
-=item B<all_XXX_names ( [CODESET] [,'retired'] )>
-
-These return a list of all elements names for which there is a
-corresponding code in the specified code set.
-
-The names returned are exactly as they are specified in the standard,
-and are sorted.
-
-Since not all elements are listed in all code sets, the list of
-elements may differ depending on the code set specified.
-
-By default, only active names will be returned, but if the string
-'retired' is passed in as an argument, both active and retired
-names will be returned.
-
-=back
-
-=head1 SEMI-PRIVATE ROUTINES
-
-Additional semi-private routines which may be used to modify the
-internal data are also available. Given their status, they aren't
-exported, and so need to be called by prefixing the function name with
-the package name.
-
-These routines do not currently work with retired codes.
-
-=over 4
-
-=item B<MODULE::rename_XXX ( CODE ,NEW_NAME [,CODESET] )>
-
-These routines are used to change the official name of an element. At
-that point, the name returned by the code2XXX routine would be
-NEW_NAME instead of the name specified in the standard.
-
-The original name will remain as an alias.
-
-For example, the official country name for code 'gb' is 'United
-Kingdom'. If you want to change that, you might call:
-
- Locale::Codes::Country::rename_country('gb', 'Great Britain');
-
-This means that calling code2country('gb') will now return 'Great
-Britain' instead of 'United Kingdom'.
-
-If any error occurs, a warning is issued and 0 is returned. An error
-occurs if CODE doesn't exist in the specified code set, or if
-NEW_NAME is already in use but for a different element.
-
-If the routine succeeds, 1 is returned.
-
-=item B<MODULE::add_XXX ( CODE ,NAME [,CODESET] )>
-
-These routines are used to add a new code and name to the data.
-
-Both CODE and NAME must be unused in the data set or an error
-occurs (though NAME may be used in a different data set).
-
-For example, to create the fictitious country named "Duchy of
-Grand Fenwick" with codes "gf" and "fen", use the following:
-
- Locale::Codes::Country::add_country("fe","Duchy of Grand Fenwick",
- LOCALE_CODE_ALPHA_2);
-
- Locale::Codes::Country::add_country("fen","Duchy of Grand Fenwick",
- LOCALE_CODE_ALPHA_3);
-
-The return value is 1 on success, 0 on an error.
-
-=item B<MODULE::delete_XXX ( CODE [,CODESET] )>
-
-These routines are used to delete a code from the data.
-
-CODE must refer to an existing code in the code set.
-
-The return value is 1 on success, 0 on an error.
-
-=item B<MODULE::add_XXX_alias ( NAME ,NEW_NAME )>
-
-These routines are used to add a new alias to the data. They do
-not alter the return value of the code2XXX function.
-
-NAME must be an existing element name, and NEW_NAME must
-be unused or an error occurs.
-
-The return value is 1 on success, 0 on an error.
-
-=item B<MODULE::delete_XXX_alias ( NAME )>
-
-These routines are used to delete an alias from the data. Once
-removed, the element may not be referred to by NAME.
-
-NAME must be one of a list of at least two names that may be used to
-specify an element. If the element may only be referred to by a single
-name, you'll need to use the add_XXX_alias function to add a new alias
-first, or the remove_XXX function to remove the element entirely.
-
-If the alias is used as the name in any code set, one of the other
-names will be used instead. Predicting exactly which one will
-be used requires you to know the order in which the standards
-were read, which is not reliable, so you may want to use the
-rename_XXX function to force one of the alternate names to be
-used.
-
-The return value is 1 on success, 0 on an error.
-
-=item B<MODULE::rename_XXX_code ( CODE ,NEW_CODE [,CODESET] )>
-
-These routines are used to change the official code for an element. At
-that point, the code returned by the XXX2code routine would be
-NEW_CODE instead of the code specified in the standard.
-
-NEW_CODE may either be a code that is not in use, or it may be an
-alias for CODE (in which case, CODE becomes and alias and NEW_CODE
-becomes the "real" code).
-
-The original code is kept as an alias, so that the code2XXX routines
-will work with either the code from the standard or the new code.
-
-However, the all_XXX_codes routine will only return the codes which
-are considered "real" (which means that the list of codes will now
-contain NEW_CODE, but will not contain CODE).
-
-=item B<MODULE::add_XXX_code_alias ( CODE ,NEW_CODE [,CODESET] )>
-
-These routines add an alias for the code. At that point, NEW_CODE and CODE
-will both work in the code2XXX routines. However, the XXX2code routines will
-still return the original code.
-
-=item B<MODULE::delete_XXX_code_alias ( CODE [,CODESET] )>
-
-These routines delete an alias for the code.
-
-These will only work if CODE is actually an alias. If it is the "real"
-code, it will not be deleted. You will need to use the rename_XXX_code
-function to switch the real code with one of the aliases, and then
-delete the alias.
-
-=back
-
-=head1 KNOWN BUGS AND LIMITATIONS
-
-=over 4
-
-=item B<*>
-
-Because each code set uses a slightly different list of elements, and
-they are not necessarily one-to-one, there may be some confusion
-about the relationship between codes from different code sets.
-
-For example, ISO 3166 assigns one code to the country "United States
-Minor Outlying Islands", but the FIPS 10 codes give different codes
-to different islands (Baker Island, Howland Island, etc.).
-
-This may cause some confusion... I've done the best that I could do
-to minimize it.
-
-=item B<*>
-
-Currently all names must be all ASCII. I plan on relaxing that
-limitation in the future.
-
-=back
-
-=head1 SEE ALSO
-
-Locale::Codes
-
-=head1 AUTHOR
-
-See Locale::Codes for full author history.
-
-Currently maintained by Sullivan Beck (sbeck@cpan.org).
-
-=head1 COPYRIGHT
-
- Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
- Copyright (c) 2001-2010 Neil Bowers
- Copyright (c) 2010-2012 Sullivan Beck
-
-This module is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/Changes.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/Changes.pod
deleted file mode 100644
index 88e91c78488..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Codes/Changes.pod
+++ /dev/null
@@ -1,570 +0,0 @@
-=pod
-
-=head1 NAME
-
-Locale::Codes::Changes - details changes to Locale::Codes
-
-=head1 SYNOPSIS
-
-This describes the changes made to modules in the Locale-Codes
-distribution. Major changes are marked with asterisks (*). For the
-most part, all modules have remained backward compatible at every
-release, but occasionally a change is made which is backward
-incompatible. These are marked with an exclamation mark (!).
-
-As of 3.00, the codes are autogenerated from the standards. With each
-release, codes will be re-generated and tested to see if any code
-changed. Any time there are any changes to the codes, it will be
-flagged below with a change: NEW CODE(s).
-
-I intend to check for new codes four times a year (March, June,
-September, December). I will also check on request, so if a code
-changes that you use, feel free to contact me. Any time there are new
-codes, I will add them to the module and release a new version.
-
-=head1 VERSION 3.22 (yyyy-mm-dd; sbeck)
-
-=head1 VERSION 3.21 (2012-03-01; sbeck)
-
-NEW CODE(s)
-
-=head1 VERSION 3.20 (2011-12-01; sbeck)
-
-NEW CODE(s)
-
-=over 4
-
-=item B<Added limited support for deprecated codes>
-
-The code2XXX, XXX2code, all_XXX_codes, and all_XXX_names functions
-now support retired codes. RT 71124
-
-=item B<Fixed capitalization>
-
-The 'South Sudan' country was all caps. RT 71024
-
-=item B<Pod tests off by default>
-
-The pod tests will not run at install time. RT 71122
-
-=item B<Codesets may be specified by name>
-
-All codesets may be specified by a constant or by their name now. Previously,
-they were specified only by a constant.
-
-=item B<alias_code deprecated>
-
-The alias_code function exists for backward compatibility. It has been replaced
-by rename_country_code . The alias_code function will be removed sometime
-after September, 2013 .
-
-=item B<Code cleanup>
-
-All work is now done in the central module (Locale::Codes). Previously, some
-was still done in the wrapper modules (Locale::Codes::*) but that is gone now.
-
-=item B<Added LangFam module>
-
-Added Language Family codes (langfam) as defined in ISO 639-5.
-
-=back
-
-=head1 VERSION 3.18 (2011-08-31; sbeck)
-
-NEW CODE(s)
-
-=over 4
-
-=item B<No longer use CIA data>
-
-The CIA world added non-standard values, so I no longer use it as
-a source of data. Based on a report by Michiel Beijen.
-
-=back
-
-=head1 VERSION 3.17 (2011-06-28; sbeck)
-
-NEW CODE(s)
-
-=over 4
-
-=item B<Added new types of codes>
-
-Added Language Extension codes (langext) and Language Variation codes
-(langvar) as defined in the IANA language registry.
-
-=item B<Added new codeset(s)>
-
-Added language codes from ISO 639-5
-
-Added language/script codes from the IANA language subtag
-registry
-
-=item B<Bug fixes>
-
-Fixed an uninitialized value warning. RT 67438
-
-Fixed the return value for the all_XXX_codes and all_XXX_names functions. RT 69100
-
-=item B<Reorganized code>
-
-Reorganized modules to move Locale::MODULE to Locale::Codes::MODULE to
-allow for cleaner future additions. The original four modules (Locale::Language,
-Locale::Currency, Locale::Country, Locale::Script) will continue to work, but
-all new sets of codes will be added in the Locale::Codes namespace.
-
-=back
-
-=head1 VERSION 3.16 (2011-03-01; sbeck)
-
-NEW CODE(s)
-
-=head1 VERSION 3.15 (2010-12-02; sbeck)
-
-NEW CODE(s)
-
-=over 4
-
-=item B<Minor fixes>
-
-Added version number to Makefile.PL/Build.PL requirement
-for POD testing modules. RT 62247
-
-Changed 'use vars' to 'our'
-
-=back
-
-=head1 VERSION 3.14 (2010-09-28; sbeck)
-
-NEW CODE(s)
-
-=over 4
-
-=item B<Bug fixes>
-
-Stripped out some HTML that got included with some codes.
-
-=back
-
-=head1 VERSION 3.13 (2010-06-04; sbeck)
-
-NEW CODE(s)
-
-=head1 VERSION 3.12 (2010-04-06; sbeck)
-
-NEW CODE(s)
-
-=over 4
-
-=item B<Reorganized code>
-
-Renamed test.pl to testfunc.pl to avoid causing an error
-when built as part of perl.
-
-=back
-
-=head1 VERSION 3.11 (2010-03-01; sbeck)
-
-NEW CODE(s)
-
-=over 4
-
-=item B<Added new codeset(s)>
-
-Added the IANA domain names to Country
-
-=item B<Bug fixes>
-
-Fixed a problem that produced warnings with perl 5.11.5.
-Jerry D. Hedden
-
-=back
-
-=head1 VERSION 3.10 (2010-02-18; sbeck)
-
-NEW CODE(s)
-
-=over 4
-
-=item B<Reorganized code>
-
-Moved support files into the Locale::Codes namespace.
-
-The work done in each of the Locale::XXX modules was virtually
-identical to each other. It has all been moved to a central module and
-the Locale::XXX modules are now just wrappers.
-
-=item B<(!) Changed XXX_code2code behavior slightly>
-
-In previous versions, passing in the same code set for both code set
-arguments would automatically return undef. For example:
-
- country_code2code('bo',LOCALE_CODE_ALPHA_2,LOCALE_CODE_ALPHA_2);
- => undef
-
-This doesn't seem like reasonable behavior, so it has been changed
-to allow the same code set:
-
- country_code2code('bo',LOCALE_CODE_ALPHA_2,LOCALE_CODE_ALPHA_2);
- => 'bo'
-
-Note that if an invalid code is passed in, undef will still be
-returned:
-
- country_code2code('bol',LOCALE_CODE_ALPHA_2,LOCALE_CODE_ALPHA_2);
- => undef
-
-=item B<Added many semi-private routines>
-
-Previous versions had only two semi-private routines: rename_country
-and alias_code which had the ability to modify the internal data in
-a couple very limited ways. It was requested (in an anonymous posting
-by someone named Steve and also by Steve Hay) that better support
-for modifying internal data, so a full set of routines were added.
-
-The full set of routines includes:
-
- rename_country
- rename_language
- rename_currency
- rename_script
-
- add_country
- add_language
- add_currency
- add_script
-
- delete_country
- delete_language
- delete_currency
- delete_script
-
- add_country_alias
- add_language_alias
- add_currency_alias
- add_script_alias
-
- delete_country_alias
- delete_language_alias
- delete_currency_alias
- delete_script_alias
-
- rename_country_code
- rename_language_code
- rename_currency_code
- rename_script_code
-
- add_country_code_alias
- add_language_code_alias
- add_currency_code_alias
- add_script_code_alias
-
- delete_country_code_alias
- delete_language_code_alias
- delete_currency_code_alias
- delete_script_code_alias
-
-=item B<New aliases>
-
-Added "UK" alias. Steve Hay
-
-=back
-
-=head1 VERSION 3.01 (2010-02-15; sbeck)
-
-=over 4
-
-=item B<Fixed Makefile.PL and Build.PL>
-
-They now install as core modules as they are supposed to. Reported in
-RT 54526
-
-=back
-
-=head1 VERSION 3.00 (2010-02-10; sbeck)
-
-NEW CODE(s)
-
-=over 4
-
-=item B<New maintainer>
-
-From 1997 to 2004, Locale::Codes was maintained by Neil
-Bowers. Unfortunately, no updates were made from June 2004 to January
-2010. During that time, a number of changes have been made to the
-standards since then, so the data included was out-of-date.
-
-I contacted Neil to get his permission to assume maintenance of
-the module, and he kindly agreed.
-
-=item B<(*) (!) All codes are generated from standards>
-
-All of the values returned by the various functions are now values
-directly from the standards. This means that the values returned in
-the 2.xx series are not necessarily the same as the values returned
-here.
-
-As an example, the ISO 3166 standard which lists country codes refers
-to the country associated with the code "bo" as "Bolivia,
-Plurinational State of", so that is what is returned. In the 2.xx
-series, "Bolivia" was returned. Also, the country names vary from one
-standard to another. So the code "bol" which is maintained by the
-United Nations returns the name of the country as "Bolivia
-(Plurinational State of)". Some common aliases have been added, so you
-can still request a code associated with a county name "Bolivia".
-
-Since the data comes from the standards, some "incorrect" values are
-no longer supported. For example, 2.07 treated "Zaire" as an alias for
-"Congo", but the country changed it's name, and "Zaire" is not in the
-standard, so it has been dropped in 3.00.
-
-=item B<Added new codeset(s)>
-
-FIPS 10 country codes (requested in RT 1755)
-
-Alpha-3 and Term language codes (requested in RT 11730)
-
-Numeric currency codes (requested in RT 18797)
-
-=item B<(*) (!) Locale::Script changed>
-
-In 2.xx, Locale::Script assigned scripts to country codes, which is NOT
-how it is done currently in the standards. It appears that an older version
-of ISO 15924 did this, but I haven't found an old version to confirm
-that, and in any case, that is not the case in the current standards.
-
-As a result, the Locale::Script module is completely incompatible with
-the 2.xx version with respect to the types of codes it supports. None of
-the old codes will work.
-
-=item B<Added missing functions>
-
-I've added in some functions which were "missing" previously (since there was
-only one set of codes supported, the code2code functions didn't apply):
-
- language_code2code
- currency_code2code
-
-so the interfaces for each type of codes are consistent.
-
-=item B<(!) Dropped support for _alias_code>
-
-In Locale::Country, _alias_code was an allowed, but deprecated function
-which was documented to be supported in the 2.xx series. I've removed it.
-
-=item B<(!) All functions return the standard value>
-
-code2country (and other equivalent functions) now returns the name of
-the country specified in the standard (if the different standards
-refer to the country by different variations in the name, the results
-will differ based on the CODESET)
-
-=item B<(!) rename_country function altered>
-
-The rename_country function from 2.07 would guess the CODESET (unlike
-all other functions which used a default of LOCALE_CODE_ALPHA_2). The
-guess can cause problems since (with the addition of FIPS) codes may
-appear in different codesets for different countries. The behavior has
-been changed to be the same as other functions (default to
-LOCALE_CODE_ALPHA_2).
-
-=back
-
-=head1 VERSION 2.07 (2004-06-10; neilb)
-
-Made $_ local in the initialization code for each module
-change back-propagated from Perl distribution
-
-Removed two non ISO-8859-1 characters from language names
-change back-propagated from Perl distribution
-
-Added the following aliases, with a test case for each
- - Burma added to Myanmar
- - French Southern and Antarctic Lands to
- French Southern Territories
-patch from TJ Mather
-
-"Canadian Dollar" was misspelled as "Candian Dollar"
- - noted by Nick Cabatoff, patch from Michael Hennecke
-
-Changes to Locale::Country reflecting changes in ISO 3166
- - added Aland Islands (ax, ala, 248)
- - YUGOSLAVIA is now SERBIA AND MONTENEGRO
- YU => CS
- YUG => SCG
- 891 => 891 (unchanged)
- (YUGOSLAVIA retained as an alias)
- - EAST TIMOR changed to TIMOR-LESTE
- (old name retained as an alias)
- - three letter code for Romania changed from ROM to ROU
-
-ZAIRE is now CONGO, THE DEMOCRATIC REPUBLIC OF THE
- ZR => CD
- ZAR => COD
- 180 => 180 (unchanged)
- (ZAIRE retained as alias)
-
-=head1 VERSION 2.06 (2002-07-15; neilb)
-
-The four modules which have data after __DATA__ weren't closing the
-DATA filehandle after reading from it, which they should. Bug and
-patch from Steve Hay.
-
-=head1 VERSION 2.05 (2002-07-08; neilb)
-
-Added three letter codes for the countries that were missing
-them. Patch from TJ Mather.
-
-Documentation bug: one of the examples used => where the
-lvalue was a constant, which isn't allowed, unless you
-put the () with the constant to force the right interpretation.
-Pointed out by TJ Mather and MYT.
-
-Updated the URL for the appendix in the CIA world factbook.
-Patch from TJ Mather.
-
-=head1 VERSION 2.04 (2002-05-23; neilb)
-
-Updated according to changes in ISO 3166-1 described
-in ISO 3166-1 newsletters V-4 and V-5, dated 2002-05-20:
- - Kazakstan is now "Kazakhstan"
- - Macau is now "Macao"
-The old names are retained as aliases.
-
-The alpha-2 and alpha-3 codes for East Timor have changed:
- tp -> tl
- tmp -> tls
-the numeric code stays 626. If you want to support the old
-codes, you can use the semi-private function alias_code().
-
-=head1 VERSION 2.03 (2002-03-24; neilb)
-
-Fixed a typo in the alias for the Vatican, reported (with patch)
-by Philip Newton.
-
-Added "Moldova" as an alias for "Moldova, Republic of"
-
-Updated Makefile.PL to include AUTHOR and ABSTRACT
-
-=head1 VERSION 2.02 (2002-03-09; neilb)
-
-Added semi-private routine rename_country() to Locale::Country,
-based on a patch from Iain Chalmers.
-
-Added test rename.t for the above function.
-
-Renamed _alias_code to be alias_code. Have retained the old
-name for backwards compatibility. Will remove it when the
-major version number next changes.
-
-=head1 VERSION 2.01 (2002-02-18; neilb)
-
-Split the documentation for all modules into separate pod files.
-
-Made sure all =over were =over 4; some were other values.
-
-The code2code() methods had one more shift than was needed.
-
-=head1 VERSION 2.00 (2002-02-17; neilb)
-
-Created Locale::Script which provides an interface to the ISO codes
-for identification of scripts (writing scripts, rather than perl style
-scripts). The codes are defined by ISO 15924, which is currently in
-final draft. Thanks to Jarkko for pointing out this new standard.
-All three code sets are supported, and a test-suite added.
-
-Added support for country name variants to Locale::Country,
-so that
- country2code('USA')
- country2code('United States')
- country2code('United States of America')
-will all return 'us'. This had been in the LIMITATIONS section since
-the first version. Patch from TJ Mather with additional variants from
-me. Added test-cases for these.
-
-Added VERSION to Locale::Constants. Thanks to Jarkko for
-pointing that it was missing.
-
-Should really have bumped major version with previous release,
-since there was a change to the API.
-
-=head1 VERSION 1.06 (2001-03-04; neilb)
-
-Added Locale::Constants, which defines three symbols for identifying
-which codeset is being used:
-
- LOCALE_CODE_ALPHA_2
- LOCALE_CODE_ALPHA_3
- LOCALE_CODE_NUMERIC
-
-Updated Locale::Country to support all three code sets defined by ISO
-3166. This was requested by Keith Wall. I haven't added multiple
-codeset support to the other modules yet - I'll wait until someone
-asks for them.
-
-=head1 VERSION 1.05 (2001-02-13; neilb)
-
-Added Locale::Currency, contribution from Michael Hennecke.
-
-Added test suite for it (t/currency.t) and added test cases
-to t/all.t for the all_* functions.
-
-=head1 VERSION 1.04 (2000-12-21; neilb)
-
-Fixed very minor typos from 1.03!
-
-=head1 VERSION 1.03 (2000-12-??; neilb)
-
-Updated Locale::Country:
- - fixed spelling of a few countries
- - added link to a relevant page from CIA world factbook
-
-Updated Locale::Language:
- - fixed typo in the documentation (ISO 939 should be 639)
-
-=head1 VERSION 1.02 (2000-05-04; neilb)
-
-Updated Locale::Country and Locale::Language to reflect changes in the
-relevant ISO standards. These mainly reflect languages which are new
-to the relevant standard, and changes in the spelling of some country
-names.
-
-Added official URLs for the standards to the SEE ALSO sections of the
-doc for each module.
-
-Thanks to Jarkko Hietaniemi for pointing me at the pages with latest
-versions of ISO 3166 and 639.
-
-=head1 VERSION 1.00 (1998-03-09; neilb)
-
-Added Locale::Country::_alias_code() so that 'uk' can be added as the
-code for "United Kingdom", if you want it. This was prompted by Ed
-Jordan.
-
-Added a new test suite for handling this case, and extended the
-existing test-suite to include testing of the case where 'uk' hasn't
-been defined as a valid code.
-
-=head1 VERSION 0.003 (1997-05-09; neilb)
-
-First public release to CPAN
-
-=head1 SEE ALSO
-
-Locale::Codes
-
-=head1 AUTHOR
-
-See Locale::Codes for full author history.
-
-Currently maintained by Sullivan Beck (sbeck@cpan.org).
-
-=head1 COPYRIGHT
-
- Copyright (c) 2001-2010 Neil Bowers
- Copyright (c) 2010-2012 Sullivan Beck
-
-This module is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/Constants.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/Constants.pod
deleted file mode 100644
index 78ded778e96..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Codes/Constants.pod
+++ /dev/null
@@ -1,41 +0,0 @@
-=pod
-
-=head1 NAME
-
-Locale::Codes::Constants - constants for Locale codes
-
-=head1 DESCRIPTION
-
-B<Locale::Codes::Constants> defines symbols which are used in the other
-modules from the Locale-Codes distribution.
-
-You shouldn't have to C<use> this module directly yourself - it is
-used by the other Locale modules, which in turn export the symbols.
-
-The constants are documented in each of the Locale modules.
-
-=head1 KNOWN BUGS AND LIMITATIONS
-
-None known.
-
-=head1 SEE ALSO
-
-Locale::Codes
-
-=head1 AUTHOR
-
-See Locale::Codes for full author history.
-
-Currently maintained by Sullivan Beck (sbeck@cpan.org).
-
-=head1 COPYRIGHT
-
- Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
- Copyright (c) 2001-2010 Neil Bowers
- Copyright (c) 2010-2012 Sullivan Beck
-
-This module is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/Country.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/Country.pod
deleted file mode 100644
index c559c37bf4e..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Codes/Country.pod
+++ /dev/null
@@ -1,214 +0,0 @@
-=pod
-
-=head1 NAME
-
-Locale::Codes::Country - standard codes for country identification
-
-=head1 SYNOPSIS
-
- use Locale::Codes::Country;
-
- $country = code2country('jp' [,CODESET]); # $country gets 'Japan'
- $code = country2code('Norway' [,CODESET]); # $code gets 'no'
-
- @codes = all_country_codes( [CODESET]);
- @names = all_country_names();
-
- # semi-private routines
- Locale::Codes::Country::alias_code('uk' => 'gb');
- Locale::Codes::Country::rename_country('gb' => 'Great Britain');
-
-=head1 DESCRIPTION
-
-The C<Locale::Codes::Country> module provides access to several code sets
-that can be used for identifying countries, such as those defined in
-ISO 3166-1.
-
-Most of the routines take an optional additional argument which
-specifies the code set to use. If not specified, the default ISO
-3166-1 two-letter codes will be used.
-
-=head1 SUPPORTED CODE SETS
-
-There are several different code sets you can use for identifying
-countries. A code set may be specified using either a name, or a
-constant that is automatically exported by this module.
-
-For example, the two are equivalent:
-
- $country = code2country('jp','alpha-2');
- $country = code2country('jp',LOCALE_CODE_ALPHA_2);
-
-The codesets currently supported are:
-
-=over 4
-
-=item B<alpha-2, LOCALE_CODE_ALPHA_2>
-
-This is the set of two-letter (lowercase) codes from ISO 3166-1, such
-as 'tv' for Tuvalu.
-
-This is the default code set.
-
-=item B<alpha-3, LOCALE_CODE_ALPHA_3>
-
-This is the set of three-letter (lowercase) codes from ISO 3166-1,
-such as 'brb' for Barbados. These codes are actually defined and
-maintained by the U.N. Statistics division.
-
-=item B<numeric, LOCALE_CODE_NUMERIC>
-
-This is the set of three-digit numeric codes from ISO 3166-1, such as
-064 for Bhutan. These codes are actually defined and maintained by the
-U.N. Statistics division.
-
-If a 2-digit code is entered, it is converted to 3 digits by prepending
-a 0.
-
-=item B<fips-10, LOCALE_CODE_FIPS>
-
-The FIPS 10 data are two-letter (uppercase) codes assigned by the
-National Geospatial-Intelligence Agency.
-
-=item B<dom, LOCALE_CODE_DOM>
-
-The IANA is responsible for assigning two-letter (uppercase) top-level
-domain names to each country.
-
-=back
-
-=head1 ROUTINES
-
-=over 4
-
-=item B<code2country ( CODE [,CODESET] )>
-
-=item B<country2code ( NAME [,CODESET] )>
-
-=item B<country_code2code ( CODE ,CODESET ,CODESET2 )>
-
-=item B<all_country_codes ( [CODESET] )>
-
-=item B<all_country_names ( [CODESET] )>
-
-=item B<Locale::Codes::Country::rename_country ( CODE ,NEW_NAME [,CODESET] )>
-
-=item B<Locale::Codes::Country::add_country ( CODE ,NAME [,CODESET] )>
-
-=item B<Locale::Codes::Country::delete_country ( CODE [,CODESET] )>
-
-=item B<Locale::Codes::Country::add_country_alias ( NAME ,NEW_NAME )>
-
-=item B<Locale::Codes::Country::delete_country_alias ( NAME )>
-
-=item B<Locale::Codes::Country::rename_country_code ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Codes::Country::add_country_code_alias ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Codes::Country::delete_country_code_alias ( CODE [,CODESET] )>
-
-These routines are all documented in the Locale::Codes::API man page.
-
-=item B<alias_code ( ALIAS, CODE [,CODESET] )>
-
-Version 2.07 included 2 functions for modifying the internal data:
-rename_country and alias_code. Both of these could be used only to
-modify the internal data for country codes.
-
-As of 3.10, the internal data for all types of codes can be modified.
-
-The alias_code function is preserved for backwards compatibility, but
-the following two are identical:
-
- alias_code(ALIAS,CODE [,CODESET]);
- rename_country_code(CODE,ALIAS [,CODESET]);
-
-and the latter should be used for consistency.
-
-The alias_code function is deprecated and will be removed at some point
-in the future.
-
-B<Note:> this function was previously called _alias_code, but the
-leading underscore has been dropped. The old name was supported for
-all 2.X releases, but has been dropped as of 3.00.
-
-=back
-
-=head1 SEE ALSO
-
-=over 4
-
-=item B<Locale::Codes>
-
-The Locale-Codes distribution.
-
-=item B<Locale::Codes::API>
-
-The list of functions supported by this module.
-
-=item B<Locale::SubCountry>
-
-ISO codes for country sub-divisions (states, counties, provinces,
-etc), as defined in ISO 3166-2. This module is not part of the
-Locale-Codes distribution, but is available from CPAN in
-CPAN/modules/by-module/Locale/
-
-=item B<http://www.iso.org/iso/country_codes>
-
-Official home page for the ISO 3166 maintenance agency.
-
-Unfortunately, they do not make the actual ISO available for free,
-so I cannot check the alpha-3 and numerical codes here.
-
-=item B<http://www.iso.org/iso/list-en1-semic-3.txt>
-
-The source of ISO 3166-1 two-letter codes used by this
-module.
-
-=item B<http://unstats.un.org/unsd/methods/m49/m49alpha.htm>
-
-The source of the official ISO 3166-1 three-letter codes and
-three-digit codes.
-
-For some reason, this table is incomplete! Several countries are
-missing from it, and I cannot find them anywhere on the UN site. I
-get as much of the data from here as I can.
-
-=item B<http://earth-info.nga.mil/gns/html/digraphs.htm>
-
-The official list of the FIPS 10 codes.
-
-=item B<http://www.iana.org/domains/>
-
-Official source of the top-level domain names.
-
-=item B<https://www.cia.gov/library/publications/the-world-factbook/appendix/print_appendix-d.html>
-
-The World Factbook maintained by the CIA is a potential source of
-the data. Unfortunately, it adds/preserves non-standard codes, so it is no
-longer used as a source of data.
-
-=item B<http://www.statoids.com/wab.html>
-
-Another unofficial source of data. Currently, it is not used to get
-data, but the notes and explanatory material were very useful for
-understanding discrepancies between the sources.
-
-=back
-
-=head1 AUTHOR
-
-See Locale::Codes for full author history.
-
-Currently maintained by Sullivan Beck (sbeck@cpan.org).
-
-=head1 COPYRIGHT
-
- Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
- Copyright (c) 2001-2010 Neil Bowers
- Copyright (c) 2010-2012 Sullivan Beck
-
-This module is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/Currency.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/Currency.pod
deleted file mode 100644
index a79b811c1d0..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Codes/Currency.pod
+++ /dev/null
@@ -1,127 +0,0 @@
-=pod
-
-=head1 NAME
-
-Locale::Codes::Currency - standard codes for currency identification
-
-=head1 SYNOPSIS
-
- use Locale::Codes::Currency;
-
- $curr = code2currency('usd'); # $curr gets 'US Dollar'
- $code = currency2code('Euro'); # $code gets 'eur'
-
- @codes = all_currency_codes();
- @names = all_currency_names();
-
-
-=head1 DESCRIPTION
-
-The C<Locale::Codes::Currency> module provides access to standard codes used
-for identifying currencies and funds, such as those defined in ISO 4217.
-
-Most of the routines take an optional additional argument which
-specifies the code set to use. If not specified, the default ISO
-4217 three-letter codes will be used.
-
-=head1 SUPPORTED CODE SETS
-
-There are several different code sets you can use for identifying
-currencies. A code set may be specified using either a name, or a
-constant that is automatically exported by this module.
-
-For example, the two are equivalent:
-
- $curr = code2currency('usd','alpha');
- $curr = code2currency('usd',LOCALE_CURR_ALPHA);
-
-The codesets currently supported are:
-
-=over 4
-
-=item B<alpha, LOCALE_CURR_ALPHA>
-
-This is a set of three-letter (uppercase) codes from ISO 4217 such
-as EUR for Euro.
-
-Two of the codes specified by the standard (XTS which is reserved
-for testing purposes and XXX which is for transactions where no
-currency is involved) are omitted.
-
-This is the default code set.
-
-=item B<num, LOCALE_CURR_NUMERIC>
-
-This is the set of three-digit numeric codes from ISO 4217.
-
-=back
-
-=head1 ROUTINES
-
-=over 4
-
-=item B<code2currency ( CODE [,CODESET] )>
-
-=item B<currency2code ( NAME [,CODESET] )>
-
-=item B<currency_code2code ( CODE ,CODESET ,CODESET2 )>
-
-=item B<all_currency_codes ( [CODESET] )>
-
-=item B<all_currency_names ( [CODESET] )>
-
-=item B<Locale::Codes::Currency::rename_currency ( CODE ,NEW_NAME [,CODESET] )>
-
-=item B<Locale::Codes::Currency::add_currency ( CODE ,NAME [,CODESET] )>
-
-=item B<Locale::Codes::Currency::delete_currency ( CODE [,CODESET] )>
-
-=item B<Locale::Codes::Currency::add_currency_alias ( NAME ,NEW_NAME )>
-
-=item B<Locale::Codes::Currency::delete_currency_alias ( NAME )>
-
-=item B<Locale::Codes::Currency::rename_currency_code ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Codes::Currency::add_currency_code_alias ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Codes::Currency::delete_currency_code_alias ( CODE [,CODESET] )>
-
-These routines are all documented in the Locale::Codes::API man page.
-
-=back
-
-=head1 SEE ALSO
-
-=over 4
-
-=item B<Locale::Codes>
-
-The Locale-Codes distribution.
-
-=item B<Locale::Codes::API>
-
-The list of functions supported by this module.
-
-=item B<http://www.iso.org/iso/support/currency_codes_list-1.htm>
-
-The ISO 4217 data.
-
-=back
-
-=head1 AUTHOR
-
-See Locale::Codes for full author history.
-
-Currently maintained by Sullivan Beck (sbeck@cpan.org).
-
-=head1 COPYRIGHT
-
- Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
- Copyright (c) 2001 Michael Hennecke
- Copyright (c) 2001-2010 Neil Bowers
- Copyright (c) 2010-2012 Sullivan Beck
-
-This module is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/LangExt.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/LangExt.pod
deleted file mode 100644
index da1421bcb36..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Codes/LangExt.pod
+++ /dev/null
@@ -1,116 +0,0 @@
-=pod
-
-=head1 NAME
-
-Locale::Codes::LangExt - standard codes for language extension identification
-
-=head1 SYNOPSIS
-
- use Locale::Codes::LangExt;
-
- $lext = code2langext('acm'); # $lext gets 'Mesopotamian Arabic'
- $code = langext2code('Mesopotamian Arabic'); # $code gets 'acm'
-
- @codes = all_langext_codes();
- @names = all_langext_names();
-
-=head1 DESCRIPTION
-
-The C<Locale::Codes::LangExt> module provides access to standard codes
-used for identifying language extensions, such as those as defined in
-the IANA language registry.
-
-Most of the routines take an optional additional argument which
-specifies the code set to use. If not specified, the default IANA
-language registry codes will be used.
-
-=head1 SUPPORTED CODE SETS
-
-There are several different code sets you can use for identifying
-language extensions. A code set may be specified using either a name, or a
-constant that is automatically exported by this module.
-
-For example, the two are equivalent:
-
- $lext = code2langext('acm','alpha');
- $lext = code2langext('acm',LOCALE_LANGEXT_ALPHA);
-
-The codesets currently supported are:
-
-=over 4
-
-=item B<alpha>
-
-This is the set of three-letter (lowercase) codes from the IANA
-language registry, such as 'acm' for Mesopotamian Arabic.
-
-This is the default code set.
-
-=back
-
-=head1 ROUTINES
-
-=over 4
-
-=item B<code2langext ( CODE [,CODESET] )>
-
-=item B<langext2code ( NAME [,CODESET] )>
-
-=item B<langext_code2code ( CODE ,CODESET ,CODESET2 )>
-
-=item B<all_langext_codes ( [CODESET] )>
-
-=item B<all_langext_names ( [CODESET] )>
-
-=item B<Locale::Codes::LangExt::rename_langext ( CODE ,NEW_NAME [,CODESET] )>
-
-=item B<Locale::Codes::LangExt::add_langext ( CODE ,NAME [,CODESET] )>
-
-=item B<Locale::Codes::LangExt::delete_langext ( CODE [,CODESET] )>
-
-=item B<Locale::Codes::LangExt::add_langext_alias ( NAME ,NEW_NAME )>
-
-=item B<Locale::Codes::LangExt::delete_langext_alias ( NAME )>
-
-=item B<Locale::Codes::LangExt::rename_langext_code ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Codes::LangExt::add_langext_code_alias ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Codes::LangExt::delete_langext_code_alias ( CODE [,CODESET] )>
-
-These routines are all documented in the Locale::Codes::API man page.
-
-=back
-
-=head1 SEE ALSO
-
-=over 4
-
-=item B<Locale::Codes>
-
-The Locale-Codes distribution.
-
-=item B<Locale::Codes::API>
-
-The list of functions supported by this module.
-
-=item B<http://www.iana.org/assignments/language-subtag-registry>
-
-The IANA language subtag registry.
-
-=back
-
-=head1 AUTHOR
-
-See Locale::Codes for full author history.
-
-Currently maintained by Sullivan Beck (sbeck@cpan.org).
-
-=head1 COPYRIGHT
-
- Copyright (c) 2011-2012 Sullivan Beck
-
-This module is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/LangFam.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/LangFam.pod
deleted file mode 100644
index 7faabee5b10..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Codes/LangFam.pod
+++ /dev/null
@@ -1,116 +0,0 @@
-=pod
-
-=head1 NAME
-
-Locale::Codes::LangFam - standard codes for language extension identification
-
-=head1 SYNOPSIS
-
- use Locale::Codes::LangFam;
-
- $lext = code2langfam('apa'); # $lext gets 'Apache languages'
- $code = langfam2code('Apache languages'); # $code gets 'apa'
-
- @codes = all_langfam_codes();
- @names = all_langfam_names();
-
-=head1 DESCRIPTION
-
-The C<Locale::Codes::LangFam> module provides access to standard codes
-used for identifying language families, such as those as defined in
-ISO 639-5.
-
-Most of the routines take an optional additional argument which
-specifies the code set to use. If not specified, the default ISO 639-5
-language family codes will be used.
-
-=head1 SUPPORTED CODE SETS
-
-There are several different code sets you can use for identifying
-language families. A code set may be specified using either a name, or a
-constant that is automatically exported by this module.
-
-For example, the two are equivalent:
-
- $lext = code2langfam('apa','alpha');
- $lext = code2langfam('apa',LOCALE_LANGFAM_ALPHA);
-
-The codesets currently supported are:
-
-=over 4
-
-=item B<alpha>
-
-This is the set of three-letter (lowercase) codes from ISO 639-5
-such as 'apa' for Apache languages.
-
-This is the default code set.
-
-=back
-
-=head1 ROUTINES
-
-=over 4
-
-=item B<code2langfam ( CODE [,CODESET] )>
-
-=item B<langfam2code ( NAME [,CODESET] )>
-
-=item B<langfam_code2code ( CODE ,CODESET ,CODESET2 )>
-
-=item B<all_langfam_codes ( [CODESET] )>
-
-=item B<all_langfam_names ( [CODESET] )>
-
-=item B<Locale::Codes::LangFam::rename_langfam ( CODE ,NEW_NAME [,CODESET] )>
-
-=item B<Locale::Codes::LangFam::add_langfam ( CODE ,NAME [,CODESET] )>
-
-=item B<Locale::Codes::LangFam::delete_langfam ( CODE [,CODESET] )>
-
-=item B<Locale::Codes::LangFam::add_langfam_alias ( NAME ,NEW_NAME )>
-
-=item B<Locale::Codes::LangFam::delete_langfam_alias ( NAME )>
-
-=item B<Locale::Codes::LangFam::rename_langfam_code ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Codes::LangFam::add_langfam_code_alias ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Codes::LangFam::delete_langfam_code_alias ( CODE [,CODESET] )>
-
-These routines are all documented in the Locale::Codes::API man page.
-
-=back
-
-=head1 SEE ALSO
-
-=over 4
-
-=item B<Locale::Codes>
-
-The Locale-Codes distribution.
-
-=item B<Locale::Codes::API>
-
-The list of functions supported by this module.
-
-=item B<http://www.loc.gov/standards/iso639-5/id.php>
-
-ISO 639-5 .
-
-=back
-
-=head1 AUTHOR
-
-See Locale::Codes for full author history.
-
-Currently maintained by Sullivan Beck (sbeck@cpan.org).
-
-=head1 COPYRIGHT
-
- Copyright (c) 2011-2012 Sullivan Beck
-
-This module is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/LangVar.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/LangVar.pod
deleted file mode 100644
index cb74ab7790d..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Codes/LangVar.pod
+++ /dev/null
@@ -1,118 +0,0 @@
-=pod
-
-=head1 NAME
-
-Locale::Codes::LangVar - standard codes for language variation identification
-
-=head1 SYNOPSIS
-
- use Locale::Codes::LangVar;
-
- $lvar = code2langvar('acm'); # $lvar gets 'Mesopotamian Arabic'
- $code = langvar2code('Mesopotamian Arabic'); # $code gets 'acm'
-
- @codes = all_langvar_codes();
- @names = all_langvar_names();
-
-=head1 DESCRIPTION
-
-The C<Locale::Codes::LangVar> module provides access to standard codes
-used for identifying language variations, such as those as defined in
-the IANA language registry.
-
-Most of the routines take an optional additional argument which
-specifies the code set to use. If not specified, the default IANA
-language registry codes will be used.
-
-=head1 SUPPORTED CODE SETS
-
-There are several different code sets you can use for identifying
-language variations. A code set may be specified using either a name, or a
-constant that is automatically exported by this module.
-
-For example, the two are equivalent:
-
- $lvar = code2langvar('en','alpha-2');
- $lvar = code2langvar('en',LOCALE_CODE_ALPHA_2);
-
-The codesets currently supported are:
-
-=over 4
-
-=item B<alpha>
-
-This is the set of alphanumeric codes from the IANA
-language registry, such as 'arevela' for Eastern Armenian.
-
-This code set is identified with the symbol C<LOCALE_LANGVAR_ALPHA>.
-
-This is the default code set.
-
-=back
-
-=head1 ROUTINES
-
-=over 4
-
-=item B<code2langvar ( CODE [,CODESET] )>
-
-=item B<langvar2code ( NAME [,CODESET] )>
-
-=item B<langvar_code2code ( CODE ,CODESET ,CODESET2 )>
-
-=item B<all_langvar_codes ( [CODESET] )>
-
-=item B<all_langvar_names ( [CODESET] )>
-
-=item B<Locale::Codes::LangVar::rename_langvar ( CODE ,NEW_NAME [,CODESET] )>
-
-=item B<Locale::Codes::LangVar::add_langvar ( CODE ,NAME [,CODESET] )>
-
-=item B<Locale::Codes::LangVar::delete_langvar ( CODE [,CODESET] )>
-
-=item B<Locale::Codes::LangVar::add_langvar_alias ( NAME ,NEW_NAME )>
-
-=item B<Locale::Codes::LangVar::delete_langvar_alias ( NAME )>
-
-=item B<Locale::Codes::LangVar::rename_langvar_code ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Codes::LangVar::add_langvar_code_alias ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Codes::LangVar::delete_langvar_code_alias ( CODE [,CODESET] )>
-
-These routines are all documented in the Locale::Codes::API man page.
-
-=back
-
-=head1 SEE ALSO
-
-=over 4
-
-=item B<Locale::Codes>
-
-The Locale-Codes distribution.
-
-=item B<Locale::Codes::API>
-
-The list of functions supported by this module.
-
-=item B<http://www.iana.org/assignments/language-subtag-registry>
-
-The IANA language subtag registry.
-
-=back
-
-=head1 AUTHOR
-
-See Locale::Codes for full author history.
-
-Currently maintained by Sullivan Beck (sbeck@cpan.org).
-
-=head1 COPYRIGHT
-
- Copyright (c) 2011-2012 Sullivan Beck
-
-This module is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/Language.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/Language.pod
deleted file mode 100644
index 96c10884361..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Codes/Language.pod
+++ /dev/null
@@ -1,137 +0,0 @@
-=pod
-
-=head1 NAME
-
-Locale::Codes::Language - standard codes for language identification
-
-=head1 SYNOPSIS
-
- use Locale::Codes::Language;
-
- $lang = code2language('en'); # $lang gets 'English'
- $code = language2code('French'); # $code gets 'fr'
-
- @codes = all_language_codes();
- @names = all_language_names();
-
-=head1 DESCRIPTION
-
-The C<Locale::Codes::Language> module provides access to standard codes used
-for identifying languages, such as those as defined in ISO 639.
-
-Most of the routines take an optional additional argument which
-specifies the code set to use. If not specified, the default ISO
-639 two-letter codes will be used.
-
-=head1 SUPPORTED CODE SETS
-
-There are several different code sets you can use for identifying
-languages. A code set may be specified using either a name, or a
-constant that is automatically exported by this module.
-
-For example, the two are equivalent:
-
- $lang = code2language('en','alpha-2');
- $lang = code2language('en',LOCALE_CODE_ALPHA_2);
-
-The codesets currently supported are:
-
-=over 4
-
-=item B<alpha-2, LOCALE_LANG_ALPHA_2>
-
-This is the set of two-letter (lowercase) codes from ISO 639-1, such
-as 'he' for Hebrew. It also includes additions to this set included
-in the IANA language registry.
-
-This is the default code set.
-
-=item B<alpha-3, LOCALE_LANG_ALPHA_3>
-
-This is the set of three-letter (lowercase) bibliographic codes from
-ISO 639-2 and 639-5, such as 'heb' for Hebrew. It also includes
-additions to this set included in the IANA language registry.
-
-=item B<term, LOCALE_LANG_TERM>
-
-This is the set of three-letter (lowercase) terminologic codes from
-ISO 639.
-
-=back
-
-=head1 ROUTINES
-
-=over 4
-
-=item B<code2language ( CODE [,CODESET] )>
-
-=item B<language2code ( NAME [,CODESET] )>
-
-=item B<language_code2code ( CODE ,CODESET ,CODESET2 )>
-
-=item B<all_language_codes ( [CODESET] )>
-
-=item B<all_language_names ( [CODESET] )>
-
-=item B<Locale::Codes::Language::rename_language ( CODE ,NEW_NAME [,CODESET] )>
-
-=item B<Locale::Codes::Language::add_language ( CODE ,NAME [,CODESET] )>
-
-=item B<Locale::Codes::Language::delete_language ( CODE [,CODESET] )>
-
-=item B<Locale::Codes::Language::add_language_alias ( NAME ,NEW_NAME )>
-
-=item B<Locale::Codes::Language::delete_language_alias ( NAME )>
-
-=item B<Locale::Codes::Language::rename_language_code ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Codes::Language::add_language_code_alias ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Codes::Language::delete_language_code_alias ( CODE [,CODESET] )>
-
-These routines are all documented in the Locale::Codes::API man page.
-
-=back
-
-=head1 SEE ALSO
-
-=over 4
-
-=item B<Locale::Codes>
-
-The Locale-Codes distribution.
-
-=item B<Locale::Codes::API>
-
-The list of functions supported by this module.
-
-=item B<http://www.loc.gov/standards/iso639-2/>
-
-Source of the ISO 639-2 codes.
-
-=item B<http://www.loc.gov/standards/iso639-5/>
-
-Source of the ISO 639-5 codes.
-
-=item B<http://www.iana.org/assignments/language-subtag-registry>
-
-The IANA language subtag registry.
-
-=back
-
-=head1 AUTHOR
-
-See Locale::Codes for full author history.
-
-Currently maintained by Sullivan Beck (sbeck@cpan.org).
-
-=head1 COPYRIGHT
-
- Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
- Copyright (c) 2001-2010 Neil Bowers
- Copyright (c) 2010-2012 Sullivan Beck
-
-This module is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/Script.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/Script.pod
deleted file mode 100644
index 7540c553acc..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Codes/Script.pod
+++ /dev/null
@@ -1,131 +0,0 @@
-=pod
-
-=head1 NAME
-
-Locale::Codes::Script - standard codes for script identification
-
-=head1 SYNOPSIS
-
- use Locale::Codes::Script;
-
- $script = code2script('phnx'); # 'Phoenician'
- $code = script2code('Phoenician'); # 'Phnx'
- $code = script2code('Phoenician',
- LOCALE_CODE_NUMERIC); # 115
-
- @codes = all_script_codes();
- @scripts = all_script_names();
-
-=head1 DESCRIPTION
-
-The C<Locale::Codes::Script> module provides access to standards codes used
-for identifying scripts, such as those defined in ISO 15924.
-
-Most of the routines take an optional additional argument which
-specifies the code set to use. If not specified, the default ISO
-15924 four-letter codes will be used.
-
-=head1 SUPPORTED CODE SETS
-
-There are several different code sets you can use for identifying
-scripts. A code set may be specified using either a name, or a
-constant that is automatically exported by this module.
-
-For example, the two are equivalent:
-
- $script = code2script('phnx','alpha');
- $script = code2script('phnx',LOCALE_SCRIPT_ALPHA);
-
-The codesets currently supported are:
-
-=over 4
-
-=item B<alpha, LOCALE_SCRIPT_ALPHA>
-
-This is a set of four-letter (capitalized) codes from ISO 15924
-such as 'Phnx' for Phoenician. It also includes additions to this
-set included in the IANA language registry.
-
-The Zxxx, Zyyy, and Zzzz codes are not used.
-
-This is the default code set.
-
-=item B<num, LOCALE_SCRIPT_NUMERIC>
-
-This is a set of three-digit numeric codes from ISO 15924 such as 115
-for Phoenician.
-
-=back
-
-=head1 ROUTINES
-
-=over 4
-
-=item B<code2script ( CODE [,CODESET] )>
-
-=item B<script2code ( NAME [,CODESET] )>
-
-=item B<script_code2code ( CODE ,CODESET ,CODESET2 )>
-
-=item B<all_script_codes ( [CODESET] )>
-
-=item B<all_script_names ( [CODESET] )>
-
-=item B<Locale::Codes::Script::rename_script ( CODE ,NEW_NAME [,CODESET] )>
-
-=item B<Locale::Codes::Script::add_script ( CODE ,NAME [,CODESET] )>
-
-=item B<Locale::Codes::Script::delete_script ( CODE [,CODESET] )>
-
-=item B<Locale::Codes::Script::add_script_alias ( NAME ,NEW_NAME )>
-
-=item B<Locale::Codes::Script::delete_script_alias ( NAME )>
-
-=item B<Locale::Codes::Script::rename_script_code ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Codes::Script::add_script_code_alias ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Codes::Script::delete_script_code_alias ( CODE [,CODESET] )>
-
-These routines are all documented in the Locale::Codes::API man page.
-
-=back
-
-=head1 SEE ALSO
-
-=over 4
-
-=item B<Locale::Codes>
-
-The Locale-Codes distribution.
-
-=item B<Locale::Codes::API>
-
-The list of functions supported by this module.
-
-=item B<http://www.unicode.org/iso15924/>
-
-Home page for ISO 15924.
-
-=item B<http://www.iana.org/assignments/language-subtag-registry>
-
-The IANA language subtag registry.
-
-=back
-
-=head1 AUTHOR
-
-See Locale::Codes for full author history.
-
-Currently maintained by Sullivan Beck (sbeck@cpan.org).
-
-=head1 COPYRIGHT
-
- Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
- Copyright (c) 2001-2010 Neil Bowers
- Copyright (c) 2010-2012 Sullivan Beck
-
-This module is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Locale/Country.pod b/Master/tlpkg/tlperl/lib/Locale/Country.pod
deleted file mode 100644
index b9ceff31476..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Country.pod
+++ /dev/null
@@ -1,214 +0,0 @@
-=pod
-
-=head1 NAME
-
-Locale::Country - standard codes for country identification
-
-=head1 SYNOPSIS
-
- use Locale::Country;
-
- $country = code2country('jp' [,CODESET]); # $country gets 'Japan'
- $code = country2code('Norway' [,CODESET]); # $code gets 'no'
-
- @codes = all_country_codes( [CODESET]);
- @names = all_country_names();
-
- # semi-private routines
- Locale::Country::alias_code('uk' => 'gb');
- Locale::Country::rename_country('gb' => 'Great Britain');
-
-=head1 DESCRIPTION
-
-The C<Locale::Country> module provides access to several code sets
-that can be used for identifying countries, such as those defined in
-ISO 3166-1.
-
-Most of the routines take an optional additional argument which
-specifies the code set to use. If not specified, the default ISO
-3166-1 two-letter codes will be used.
-
-=head1 SUPPORTED CODE SETS
-
-There are several different code sets you can use for identifying
-countries. A code set may be specified using either a name, or a
-constant that is automatically exported by this module.
-
-For example, the two are equivalent:
-
- $country = code2country('jp','alpha-2');
- $country = code2country('jp',LOCALE_CODE_ALPHA_2);
-
-The codesets currently supported are:
-
-=over 4
-
-=item B<alpha-2, LOCALE_CODE_ALPHA_2>
-
-This is the set of two-letter (lowercase) codes from ISO 3166-1, such
-as 'tv' for Tuvalu.
-
-This is the default code set.
-
-=item B<alpha-3, LOCALE_CODE_ALPHA_3>
-
-This is the set of three-letter (lowercase) codes from ISO 3166-1,
-such as 'brb' for Barbados. These codes are actually defined and
-maintained by the U.N. Statistics division.
-
-=item B<numeric, LOCALE_CODE_NUMERIC>
-
-This is the set of three-digit numeric codes from ISO 3166-1, such as
-064 for Bhutan. These codes are actually defined and maintained by the
-U.N. Statistics division.
-
-If a 2-digit code is entered, it is converted to 3 digits by prepending
-a 0.
-
-=item B<fips-10, LOCALE_CODE_FIPS>
-
-The FIPS 10 data are two-letter (uppercase) codes assigned by the
-National Geospatial-Intelligence Agency.
-
-=item B<dom, LOCALE_CODE_DOM>
-
-The IANA is responsible for assigning two-letter (uppercase) top-level
-domain names to each country.
-
-=back
-
-=head1 ROUTINES
-
-=over 4
-
-=item B<code2country ( CODE [,CODESET] )>
-
-=item B<country2code ( NAME [,CODESET] )>
-
-=item B<country_code2code ( CODE ,CODESET ,CODESET2 )>
-
-=item B<all_country_codes ( [CODESET] )>
-
-=item B<all_country_names ( [CODESET] )>
-
-=item B<Locale::Country::rename_country ( CODE ,NEW_NAME [,CODESET] )>
-
-=item B<Locale::Country::add_country ( CODE ,NAME [,CODESET] )>
-
-=item B<Locale::Country::delete_country ( CODE [,CODESET] )>
-
-=item B<Locale::Country::add_country_alias ( NAME ,NEW_NAME )>
-
-=item B<Locale::Country::delete_country_alias ( NAME )>
-
-=item B<Locale::Country::rename_country_code ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Country::add_country_code_alias ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Country::delete_country_code_alias ( CODE [,CODESET] )>
-
-These routines are all documented in the Locale::Codes::API man page.
-
-=item B<alias_code ( ALIAS, CODE [,CODESET] )>
-
-Version 2.07 included 2 functions for modifying the internal data:
-rename_country and alias_code. Both of these could be used only to
-modify the internal data for country codes.
-
-As of 3.10, the internal data for all types of codes can be modified.
-
-The alias_code function is preserved for backwards compatibility, but
-the following two are identical:
-
- alias_code(ALIAS,CODE [,CODESET]);
- rename_country_code(CODE,ALIAS [,CODESET]);
-
-and the latter should be used for consistency.
-
-The alias_code function is deprecated and will be removed at some point
-in the future.
-
-B<Note:> this function was previously called _alias_code, but the
-leading underscore has been dropped. The old name was supported for
-all 2.X releases, but has been dropped as of 3.00.
-
-=back
-
-=head1 SEE ALSO
-
-=over 4
-
-=item B<Locale::Codes>
-
-The Locale-Codes distribution.
-
-=item B<Locale::Codes::API>
-
-The list of functions supported by this module.
-
-=item B<Locale::SubCountry>
-
-ISO codes for country sub-divisions (states, counties, provinces,
-etc), as defined in ISO 3166-2. This module is not part of the
-Locale-Codes distribution, but is available from CPAN in
-CPAN/modules/by-module/Locale/
-
-=item B<http://www.iso.org/iso/country_codes>
-
-Official home page for the ISO 3166 maintenance agency.
-
-Unfortunately, they do not make the actual ISO available for free,
-so I cannot check the alpha-3 and numerical codes here.
-
-=item B<http://www.iso.org/iso/list-en1-semic-3.txt>
-
-The source of ISO 3166-1 two-letter codes used by this
-module.
-
-=item B<http://unstats.un.org/unsd/methods/m49/m49alpha.htm>
-
-The source of the official ISO 3166-1 three-letter codes and
-three-digit codes.
-
-For some reason, this table is incomplete! Several countries are
-missing from it, and I cannot find them anywhere on the UN site. I
-get as much of the data from here as I can.
-
-=item B<http://earth-info.nga.mil/gns/html/digraphs.htm>
-
-The official list of the FIPS 10 codes.
-
-=item B<http://www.iana.org/domains/>
-
-Official source of the top-level domain names.
-
-=item B<https://www.cia.gov/library/publications/the-world-factbook/appendix/print_appendix-d.html>
-
-The World Factbook maintained by the CIA is a potential source of
-the data. Unfortunately, it adds/preserves non-standard codes, so it is no
-longer used as a source of data.
-
-=item B<http://www.statoids.com/wab.html>
-
-Another unofficial source of data. Currently, it is not used to get
-data, but the notes and explanatory material were very useful for
-understanding discrepancies between the sources.
-
-=back
-
-=head1 AUTHOR
-
-See Locale::Codes for full author history.
-
-Currently maintained by Sullivan Beck (sbeck@cpan.org).
-
-=head1 COPYRIGHT
-
- Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
- Copyright (c) 2001-2010 Neil Bowers
- Copyright (c) 2010-2012 Sullivan Beck
-
-This module is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Locale/Currency.pod b/Master/tlpkg/tlperl/lib/Locale/Currency.pod
deleted file mode 100644
index a4156eef4c3..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Currency.pod
+++ /dev/null
@@ -1,127 +0,0 @@
-=pod
-
-=head1 NAME
-
-Locale::Currency - standard codes for currency identification
-
-=head1 SYNOPSIS
-
- use Locale::Currency;
-
- $curr = code2currency('usd'); # $curr gets 'US Dollar'
- $code = currency2code('Euro'); # $code gets 'eur'
-
- @codes = all_currency_codes();
- @names = all_currency_names();
-
-
-=head1 DESCRIPTION
-
-The C<Locale::Currency> module provides access to standard codes used
-for identifying currencies and funds, such as those defined in ISO 4217.
-
-Most of the routines take an optional additional argument which
-specifies the code set to use. If not specified, the default ISO
-4217 three-letter codes will be used.
-
-=head1 SUPPORTED CODE SETS
-
-There are several different code sets you can use for identifying
-currencies. A code set may be specified using either a name, or a
-constant that is automatically exported by this module.
-
-For example, the two are equivalent:
-
- $curr = code2currency('usd','alpha');
- $curr = code2currency('usd',LOCALE_CURR_ALPHA);
-
-The codesets currently supported are:
-
-=over 4
-
-=item B<alpha, LOCALE_CURR_ALPHA>
-
-This is a set of three-letter (uppercase) codes from ISO 4217 such
-as EUR for Euro.
-
-Two of the codes specified by the standard (XTS which is reserved
-for testing purposes and XXX which is for transactions where no
-currency is involved) are omitted.
-
-This is the default code set.
-
-=item B<num, LOCALE_CURR_NUMERIC>
-
-This is the set of three-digit numeric codes from ISO 4217.
-
-=back
-
-=head1 ROUTINES
-
-=over 4
-
-=item B<code2currency ( CODE [,CODESET] )>
-
-=item B<currency2code ( NAME [,CODESET] )>
-
-=item B<currency_code2code ( CODE ,CODESET ,CODESET2 )>
-
-=item B<all_currency_codes ( [CODESET] )>
-
-=item B<all_currency_names ( [CODESET] )>
-
-=item B<Locale::Currency::rename_currency ( CODE ,NEW_NAME [,CODESET] )>
-
-=item B<Locale::Currency::add_currency ( CODE ,NAME [,CODESET] )>
-
-=item B<Locale::Currency::delete_currency ( CODE [,CODESET] )>
-
-=item B<Locale::Currency::add_currency_alias ( NAME ,NEW_NAME )>
-
-=item B<Locale::Currency::delete_currency_alias ( NAME )>
-
-=item B<Locale::Currency::rename_currency_code ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Currency::add_currency_code_alias ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Currency::delete_currency_code_alias ( CODE [,CODESET] )>
-
-These routines are all documented in the Locale::Codes::API man page.
-
-=back
-
-=head1 SEE ALSO
-
-=over 4
-
-=item B<Locale::Codes>
-
-The Locale-Codes distribution.
-
-=item B<Locale::Codes::API>
-
-The list of functions supported by this module.
-
-=item B<http://www.iso.org/iso/support/currency_codes_list-1.htm>
-
-The ISO 4217 data.
-
-=back
-
-=head1 AUTHOR
-
-See Locale::Codes for full author history.
-
-Currently maintained by Sullivan Beck (sbeck@cpan.org).
-
-=head1 COPYRIGHT
-
- Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
- Copyright (c) 2001 Michael Hennecke
- Copyright (c) 2001-2010 Neil Bowers
- Copyright (c) 2010-2012 Sullivan Beck
-
-This module is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Locale/Language.pod b/Master/tlpkg/tlperl/lib/Locale/Language.pod
deleted file mode 100644
index c6a25032735..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Language.pod
+++ /dev/null
@@ -1,137 +0,0 @@
-=pod
-
-=head1 NAME
-
-Locale::Language - standard codes for language identification
-
-=head1 SYNOPSIS
-
- use Locale::Language;
-
- $lang = code2language('en'); # $lang gets 'English'
- $code = language2code('French'); # $code gets 'fr'
-
- @codes = all_language_codes();
- @names = all_language_names();
-
-=head1 DESCRIPTION
-
-The C<Locale::Language> module provides access to standard codes used
-for identifying languages, such as those as defined in ISO 639.
-
-Most of the routines take an optional additional argument which
-specifies the code set to use. If not specified, the default ISO
-639 two-letter codes will be used.
-
-=head1 SUPPORTED CODE SETS
-
-There are several different code sets you can use for identifying
-languages. A code set may be specified using either a name, or a
-constant that is automatically exported by this module.
-
-For example, the two are equivalent:
-
- $lang = code2language('en','alpha-2');
- $lang = code2language('en',LOCALE_CODE_ALPHA_2);
-
-The codesets currently supported are:
-
-=over 4
-
-=item B<alpha-2, LOCALE_LANG_ALPHA_2>
-
-This is the set of two-letter (lowercase) codes from ISO 639-1, such
-as 'he' for Hebrew. It also includes additions to this set included
-in the IANA language registry.
-
-This is the default code set.
-
-=item B<alpha-3, LOCALE_LANG_ALPHA_3>
-
-This is the set of three-letter (lowercase) bibliographic codes from
-ISO 639-2 and 639-5, such as 'heb' for Hebrew. It also includes
-additions to this set included in the IANA language registry.
-
-=item B<term, LOCALE_LANG_TERM>
-
-This is the set of three-letter (lowercase) terminologic codes from
-ISO 639.
-
-=back
-
-=head1 ROUTINES
-
-=over 4
-
-=item B<code2language ( CODE [,CODESET] )>
-
-=item B<language2code ( NAME [,CODESET] )>
-
-=item B<language_code2code ( CODE ,CODESET ,CODESET2 )>
-
-=item B<all_language_codes ( [CODESET] )>
-
-=item B<all_language_names ( [CODESET] )>
-
-=item B<Locale::Language::rename_language ( CODE ,NEW_NAME [,CODESET] )>
-
-=item B<Locale::Language::add_language ( CODE ,NAME [,CODESET] )>
-
-=item B<Locale::Language::delete_language ( CODE [,CODESET] )>
-
-=item B<Locale::Language::add_language_alias ( NAME ,NEW_NAME )>
-
-=item B<Locale::Language::delete_language_alias ( NAME )>
-
-=item B<Locale::Language::rename_language_code ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Language::add_language_code_alias ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Language::delete_language_code_alias ( CODE [,CODESET] )>
-
-These routines are all documented in the Locale::Codes::API man page.
-
-=back
-
-=head1 SEE ALSO
-
-=over 4
-
-=item B<Locale::Codes>
-
-The Locale-Codes distribution.
-
-=item B<Locale::Codes::API>
-
-The list of functions supported by this module.
-
-=item B<http://www.loc.gov/standards/iso639-2/>
-
-Source of the ISO 639-2 codes.
-
-=item B<http://www.loc.gov/standards/iso639-5/>
-
-Source of the ISO 639-5 codes.
-
-=item B<http://www.iana.org/assignments/language-subtag-registry>
-
-The IANA language subtag registry.
-
-=back
-
-=head1 AUTHOR
-
-See Locale::Codes for full author history.
-
-Currently maintained by Sullivan Beck (sbeck@cpan.org).
-
-=head1 COPYRIGHT
-
- Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
- Copyright (c) 2001-2010 Neil Bowers
- Copyright (c) 2010-2012 Sullivan Beck
-
-This module is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Locale/Maketext.pod b/Master/tlpkg/tlperl/lib/Locale/Maketext.pod
deleted file mode 100644
index 3ef9c3a5a9b..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Maketext.pod
+++ /dev/null
@@ -1,1354 +0,0 @@
-
-# Time-stamp: "2004-01-11 18:35:34 AST"
-
-=head1 NAME
-
-Locale::Maketext - framework for localization
-
-=head1 SYNOPSIS
-
- package MyProgram;
- use strict;
- use MyProgram::L10N;
- # ...which inherits from Locale::Maketext
- my $lh = MyProgram::L10N->get_handle() || die "What language?";
- ...
- # And then any messages your program emits, like:
- warn $lh->maketext( "Can't open file [_1]: [_2]\n", $f, $! );
- ...
-
-=head1 DESCRIPTION
-
-It is a common feature of applications (whether run directly,
-or via the Web) for them to be "localized" -- i.e., for them
-to a present an English interface to an English-speaker, a German
-interface to a German-speaker, and so on for all languages it's
-programmed with. Locale::Maketext
-is a framework for software localization; it provides you with the
-tools for organizing and accessing the bits of text and text-processing
-code that you need for producing localized applications.
-
-In order to make sense of Maketext and how all its
-components fit together, you should probably
-go read L<Locale::Maketext::TPJ13|Locale::Maketext::TPJ13>, and
-I<then> read the following documentation.
-
-You may also want to read over the source for C<File::Findgrep>
-and its constituent modules -- they are a complete (if small)
-example application that uses Maketext.
-
-=head1 QUICK OVERVIEW
-
-The basic design of Locale::Maketext is object-oriented, and
-Locale::Maketext is an abstract base class, from which you
-derive a "project class".
-The project class (with a name like "TkBocciBall::Localize",
-which you then use in your module) is in turn the base class
-for all the "language classes" for your project
-(with names "TkBocciBall::Localize::it",
-"TkBocciBall::Localize::en",
-"TkBocciBall::Localize::fr", etc.).
-
-A language class is
-a class containing a lexicon of phrases as class data,
-and possibly also some methods that are of use in interpreting
-phrases in the lexicon, or otherwise dealing with text in that
-language.
-
-An object belonging to a language class is called a "language
-handle"; it's typically a flyweight object.
-
-The normal course of action is to call:
-
- use TkBocciBall::Localize; # the localization project class
- $lh = TkBocciBall::Localize->get_handle();
- # Depending on the user's locale, etc., this will
- # make a language handle from among the classes available,
- # and any defaults that you declare.
- die "Couldn't make a language handle??" unless $lh;
-
-From then on, you use the C<maketext> function to access
-entries in whatever lexicon(s) belong to the language handle
-you got. So, this:
-
- print $lh->maketext("You won!"), "\n";
-
-...emits the right text for this language. If the object
-in C<$lh> belongs to class "TkBocciBall::Localize::fr" and
-%TkBocciBall::Localize::fr::Lexicon contains C<("You won!"
-=E<gt> "Tu as gagnE<eacute>!")>, then the above
-code happily tells the user "Tu as gagnE<eacute>!".
-
-=head1 METHODS
-
-Locale::Maketext offers a variety of methods, which fall
-into three categories:
-
-=over
-
-=item *
-
-Methods to do with constructing language handles.
-
-=item *
-
-C<maketext> and other methods to do with accessing %Lexicon data
-for a given language handle.
-
-=item *
-
-Methods that you may find it handy to use, from routines of
-yours that you put in %Lexicon entries.
-
-=back
-
-These are covered in the following section.
-
-=head2 Construction Methods
-
-These are to do with constructing a language handle:
-
-=over
-
-=item *
-
-$lh = YourProjClass->get_handle( ...langtags... ) || die "lg-handle?";
-
-This tries loading classes based on the language-tags you give (like
-C<("en-US", "sk", "kon", "es-MX", "ja", "i-klingon")>, and for the first class
-that succeeds, returns YourProjClass::I<language>->new().
-
-If it runs thru the entire given list of language-tags, and finds no classes
-for those exact terms, it then tries "superordinate" language classes.
-So if no "en-US" class (i.e., YourProjClass::en_us)
-was found, nor classes for anything else in that list, we then try
-its superordinate, "en" (i.e., YourProjClass::en), and so on thru
-the other language-tags in the given list: "es".
-(The other language-tags in our example list:
-happen to have no superordinates.)
-
-If none of those language-tags leads to loadable classes, we then
-try classes derived from YourProjClass->fallback_languages() and
-then if nothing comes of that, we use classes named by
-YourProjClass->fallback_language_classes(). Then in the (probably
-quite unlikely) event that that fails, we just return undef.
-
-=item *
-
-$lh = YourProjClass->get_handleB<()> || die "lg-handle?";
-
-When C<get_handle> is called with an empty parameter list, magic happens:
-
-If C<get_handle> senses that it's running in program that was
-invoked as a CGI, then it tries to get language-tags out of the
-environment variable "HTTP_ACCEPT_LANGUAGE", and it pretends that
-those were the languages passed as parameters to C<get_handle>.
-
-Otherwise (i.e., if not a CGI), this tries various OS-specific ways
-to get the language-tags for the current locale/language, and then
-pretends that those were the value(s) passed to C<get_handle>.
-
-Currently this OS-specific stuff consists of looking in the environment
-variables "LANG" and "LANGUAGE"; and on MSWin machines (where those
-variables are typically unused), this also tries using
-the module Win32::Locale to get a language-tag for whatever language/locale
-is currently selected in the "Regional Settings" (or "International"?)
-Control Panel. I welcome further
-suggestions for making this do the Right Thing under other operating
-systems that support localization.
-
-If you're using localization in an application that keeps a configuration
-file, you might consider something like this in your project class:
-
- sub get_handle_via_config {
- my $class = $_[0];
- my $chosen_language = $Config_settings{'language'};
- my $lh;
- if($chosen_language) {
- $lh = $class->get_handle($chosen_language)
- || die "No language handle for \"$chosen_language\""
- . " or the like";
- } else {
- # Config file missing, maybe?
- $lh = $class->get_handle()
- || die "Can't get a language handle";
- }
- return $lh;
- }
-
-=item *
-
-$lh = YourProjClass::langname->new();
-
-This constructs a language handle. You usually B<don't> call this
-directly, but instead let C<get_handle> find a language class to C<use>
-and to then call ->new on.
-
-=item *
-
-$lh->init();
-
-This is called by ->new to initialize newly-constructed language handles.
-If you define an init method in your class, remember that it's usually
-considered a good idea to call $lh->SUPER::init in it (presumably at the
-beginning), so that all classes get a chance to initialize a new object
-however they see fit.
-
-=item *
-
-YourProjClass->fallback_languages()
-
-C<get_handle> appends the return value of this to the end of
-whatever list of languages you pass C<get_handle>. Unless
-you override this method, your project class
-will inherit Locale::Maketext's C<fallback_languages>, which
-currently returns C<('i-default', 'en', 'en-US')>.
-("i-default" is defined in RFC 2277).
-
-This method (by having it return the name
-of a language-tag that has an existing language class)
-can be used for making sure that
-C<get_handle> will always manage to construct a language
-handle (assuming your language classes are in an appropriate
-@INC directory). Or you can use the next method:
-
-=item *
-
-YourProjClass->fallback_language_classes()
-
-C<get_handle> appends the return value of this to the end
-of the list of classes it will try using. Unless
-you override this method, your project class
-will inherit Locale::Maketext's C<fallback_language_classes>,
-which currently returns an empty list, C<()>.
-By setting this to some value (namely, the name of a loadable
-language class), you can be sure that
-C<get_handle> will always manage to construct a language
-handle.
-
-=back
-
-=head2 The "maketext" Method
-
-This is the most important method in Locale::Maketext:
-
- $text = $lh->maketext(I<key>, ...parameters for this phrase...);
-
-This looks in the %Lexicon of the language handle
-$lh and all its superclasses, looking
-for an entry whose key is the string I<key>. Assuming such
-an entry is found, various things then happen, depending on the
-value found:
-
-If the value is a scalarref, the scalar is dereferenced and returned
-(and any parameters are ignored).
-
-If the value is a coderef, we return &$value($lh, ...parameters...).
-
-If the value is a string that I<doesn't> look like it's in Bracket Notation,
-we return it (after replacing it with a scalarref, in its %Lexicon).
-
-If the value I<does> look like it's in Bracket Notation, then we compile
-it into a sub, replace the string in the %Lexicon with the new coderef,
-and then we return &$new_sub($lh, ...parameters...).
-
-Bracket Notation is discussed in a later section. Note
-that trying to compile a string into Bracket Notation can throw
-an exception if the string is not syntactically valid (say, by not
-balancing brackets right.)
-
-Also, calling &$coderef($lh, ...parameters...) can throw any sort of
-exception (if, say, code in that sub tries to divide by zero). But
-a very common exception occurs when you have Bracket
-Notation text that says to call a method "foo", but there is no such
-method. (E.g., "You have [quaB<tn>,_1,ball]." will throw an exception
-on trying to call $lh->quaB<tn>($_[1],'ball') -- you presumably meant
-"quant".) C<maketext> catches these exceptions, but only to make the
-error message more readable, at which point it rethrows the exception.
-
-An exception I<may> be thrown if I<key> is not found in any
-of $lh's %Lexicon hashes. What happens if a key is not found,
-is discussed in a later section, "Controlling Lookup Failure".
-
-Note that you might find it useful in some cases to override
-the C<maketext> method with an "after method", if you want to
-translate encodings, or even scripts:
-
- package YrProj::zh_cn; # Chinese with PRC-style glyphs
- use base ('YrProj::zh_tw'); # Taiwan-style
- sub maketext {
- my $self = shift(@_);
- my $value = $self->maketext(@_);
- return Chineeze::taiwan2mainland($value);
- }
-
-Or you may want to override it with something that traps
-any exceptions, if that's critical to your program:
-
- sub maketext {
- my($lh, @stuff) = @_;
- my $out;
- eval { $out = $lh->SUPER::maketext(@stuff) };
- return $out unless $@;
- ...otherwise deal with the exception...
- }
-
-Other than those two situations, I don't imagine that
-it's useful to override the C<maketext> method. (If
-you run into a situation where it is useful, I'd be
-interested in hearing about it.)
-
-=over
-
-=item $lh->fail_with I<or> $lh->fail_with(I<PARAM>)
-
-=item $lh->failure_handler_auto
-
-These two methods are discussed in the section "Controlling
-Lookup Failure".
-
-=back
-
-=head2 Utility Methods
-
-These are methods that you may find it handy to use, generally
-from %Lexicon routines of yours (whether expressed as
-Bracket Notation or not).
-
-=over
-
-=item $language->quant($number, $singular)
-
-=item $language->quant($number, $singular, $plural)
-
-=item $language->quant($number, $singular, $plural, $negative)
-
-This is generally meant to be called from inside Bracket Notation
-(which is discussed later), as in
-
- "Your search matched [quant,_1,document]!"
-
-It's for I<quantifying> a noun (i.e., saying how much of it there is,
-while giving the correct form of it). The behavior of this method is
-handy for English and a few other Western European languages, and you
-should override it for languages where it's not suitable. You can feel
-free to read the source, but the current implementation is basically
-as this pseudocode describes:
-
- if $number is 0 and there's a $negative,
- return $negative;
- elsif $number is 1,
- return "1 $singular";
- elsif there's a $plural,
- return "$number $plural";
- else
- return "$number " . $singular . "s";
- #
- # ...except that we actually call numf to
- # stringify $number before returning it.
-
-So for English (with Bracket Notation)
-C<"...[quant,_1,file]..."> is fine (for 0 it returns "0 files",
-for 1 it returns "1 file", and for more it returns "2 files", etc.)
-
-But for "directory", you'd want C<"[quant,_1,directory,directories]">
-so that our elementary C<quant> method doesn't think that the
-plural of "directory" is "directorys". And you might find that the
-output may sound better if you specify a negative form, as in:
-
- "[quant,_1,file,files,No files] matched your query.\n"
-
-Remember to keep in mind verb agreement (or adjectives too, in
-other languages), as in:
-
- "[quant,_1,document] were matched.\n"
-
-Because if _1 is one, you get "1 document B<were> matched".
-An acceptable hack here is to do something like this:
-
- "[quant,_1,document was, documents were] matched.\n"
-
-=item $language->numf($number)
-
-This returns the given number formatted nicely according to
-this language's conventions. Maketext's default method is
-mostly to just take the normal string form of the number
-(applying sprintf "%G" for only very large numbers), and then
-to add commas as necessary. (Except that
-we apply C<tr/,./.,/> if $language->{'numf_comma'} is true;
-that's a bit of a hack that's useful for languages that express
-two million as "2.000.000" and not as "2,000,000").
-
-If you want anything fancier, consider overriding this with something
-that uses L<Number::Format|Number::Format>, or does something else
-entirely.
-
-Note that numf is called by quant for stringifying all quantifying
-numbers.
-
-=item $language->numerate($number, $singular, $plural, $negative)
-
-This returns the given noun form which is appropriate for the quantity
-C<$number> according to this language's conventions. C<numerate> is
-used internally by C<quant> to quantify nouns. Use it directly --
-usually from bracket notation -- to avoid C<quant>'s implicit call to
-C<numf> and output of a numeric quantity.
-
-=item $language->sprintf($format, @items)
-
-This is just a wrapper around Perl's normal C<sprintf> function.
-It's provided so that you can use "sprintf" in Bracket Notation:
-
- "Couldn't access datanode [sprintf,%10x=~[%s~],_1,_2]!\n"
-
-returning...
-
- Couldn't access datanode Stuff=[thangamabob]!
-
-=item $language->language_tag()
-
-Currently this just takes the last bit of C<ref($language)>, turns
-underscores to dashes, and returns it. So if $language is
-an object of class Hee::HOO::Haw::en_us, $language->language_tag()
-returns "en-us". (Yes, the usual representation for that language
-tag is "en-US", but case is I<never> considered meaningful in
-language-tag comparison.)
-
-You may override this as you like; Maketext doesn't use it for
-anything.
-
-=item $language->encoding()
-
-Currently this isn't used for anything, but it's provided
-(with default value of
-C<(ref($language) && $language-E<gt>{'encoding'})) or "iso-8859-1">
-) as a sort of suggestion that it may be useful/necessary to
-associate encodings with your language handles (whether on a
-per-class or even per-handle basis.)
-
-=back
-
-=head2 Language Handle Attributes and Internals
-
-A language handle is a flyweight object -- i.e., it doesn't (necessarily)
-carry any data of interest, other than just being a member of
-whatever class it belongs to.
-
-A language handle is implemented as a blessed hash. Subclasses of yours
-can store whatever data you want in the hash. Currently the only hash
-entry used by any crucial Maketext method is "fail", so feel free to
-use anything else as you like.
-
-B<Remember: Don't be afraid to read the Maketext source if there's
-any point on which this documentation is unclear.> This documentation
-is vastly longer than the module source itself.
-
-=over
-
-=back
-
-=head1 LANGUAGE CLASS HIERARCHIES
-
-These are Locale::Maketext's assumptions about the class
-hierarchy formed by all your language classes:
-
-=over
-
-=item *
-
-You must have a project base class, which you load, and
-which you then use as the first argument in
-the call to YourProjClass->get_handle(...). It should derive
-(whether directly or indirectly) from Locale::Maketext.
-It B<doesn't matter> how you name this class, although assuming this
-is the localization component of your Super Mega Program,
-good names for your project class might be
-SuperMegaProgram::Localization, SuperMegaProgram::L10N,
-SuperMegaProgram::I18N, SuperMegaProgram::International,
-or even SuperMegaProgram::Languages or SuperMegaProgram::Messages.
-
-=item *
-
-Language classes are what YourProjClass->get_handle will try to load.
-It will look for them by taking each language-tag (B<skipping> it
-if it doesn't look like a language-tag or locale-tag!), turning it to
-all lowercase, turning dashes to underscores, and appending it
-to YourProjClass . "::". So this:
-
- $lh = YourProjClass->get_handle(
- 'en-US', 'fr', 'kon', 'i-klingon', 'i-klingon-romanized'
- );
-
-will try loading the classes
-YourProjClass::en_us (note lowercase!), YourProjClass::fr,
-YourProjClass::kon,
-YourProjClass::i_klingon
-and YourProjClass::i_klingon_romanized. (And it'll stop at the
-first one that actually loads.)
-
-=item *
-
-I assume that each language class derives (directly or indirectly)
-from your project class, and also defines its @ISA, its %Lexicon,
-or both. But I anticipate no dire consequences if these assumptions
-do not hold.
-
-=item *
-
-Language classes may derive from other language classes (although they
-should have "use I<Thatclassname>" or "use base qw(I<...classes...>)").
-They may derive from the project
-class. They may derive from some other class altogether. Or via
-multiple inheritance, it may derive from any mixture of these.
-
-=item *
-
-I foresee no problems with having multiple inheritance in
-your hierarchy of language classes. (As usual, however, Perl will
-complain bitterly if you have a cycle in the hierarchy: i.e., if
-any class is its own ancestor.)
-
-=back
-
-=head1 ENTRIES IN EACH LEXICON
-
-A typical %Lexicon entry is meant to signify a phrase,
-taking some number (0 or more) of parameters. An entry
-is meant to be accessed by via
-a string I<key> in $lh->maketext(I<key>, ...parameters...),
-which should return a string that is generally meant for
-be used for "output" to the user -- regardless of whether
-this actually means printing to STDOUT, writing to a file,
-or putting into a GUI widget.
-
-While the key must be a string value (since that's a basic
-restriction that Perl places on hash keys), the value in
-the lexicon can currently be of several types:
-a defined scalar, scalarref, or coderef. The use of these is
-explained above, in the section 'The "maketext" Method', and
-Bracket Notation for strings is discussed in the next section.
-
-While you can use arbitrary unique IDs for lexicon keys
-(like "_min_larger_max_error"), it is often
-useful for if an entry's key is itself a valid value, like
-this example error message:
-
- "Minimum ([_1]) is larger than maximum ([_2])!\n",
-
-Compare this code that uses an arbitrary ID...
-
- die $lh->maketext( "_min_larger_max_error", $min, $max )
- if $min > $max;
-
-...to this code that uses a key-as-value:
-
- die $lh->maketext(
- "Minimum ([_1]) is larger than maximum ([_2])!\n",
- $min, $max
- ) if $min > $max;
-
-The second is, in short, more readable. In particular, it's obvious
-that the number of parameters you're feeding to that phrase (two) is
-the number of parameters that it I<wants> to be fed. (Since you see
-_1 and a _2 being used in the key there.)
-
-Also, once a project is otherwise
-complete and you start to localize it, you can scrape together
-all the various keys you use, and pass it to a translator; and then
-the translator's work will go faster if what he's presented is this:
-
- "Minimum ([_1]) is larger than maximum ([_2])!\n",
- => "", # fill in something here, Jacques!
-
-rather than this more cryptic mess:
-
- "_min_larger_max_error"
- => "", # fill in something here, Jacques
-
-I think that keys as lexicon values makes the completed lexicon
-entries more readable:
-
- "Minimum ([_1]) is larger than maximum ([_2])!\n",
- => "Le minimum ([_1]) est plus grand que le maximum ([_2])!\n",
-
-Also, having valid values as keys becomes very useful if you set
-up an _AUTO lexicon. _AUTO lexicons are discussed in a later
-section.
-
-I almost always use keys that are themselves
-valid lexicon values. One notable exception is when the value is
-quite long. For example, to get the screenful of data that
-a command-line program might return when given an unknown switch,
-I often just use a brief, self-explanatory key such as "_USAGE_MESSAGE". At that point I then go
-and immediately to define that lexicon entry in the
-ProjectClass::L10N::en lexicon (since English is always my "project
-language"):
-
- '_USAGE_MESSAGE' => <<'EOSTUFF',
- ...long long message...
- EOSTUFF
-
-and then I can use it as:
-
- getopt('oDI', \%opts) or die $lh->maketext('_USAGE_MESSAGE');
-
-Incidentally,
-note that each class's C<%Lexicon> inherits-and-extends
-the lexicons in its superclasses. This is not because these are
-special hashes I<per se>, but because you access them via the
-C<maketext> method, which looks for entries across all the
-C<%Lexicon> hashes in a language class I<and> all its ancestor classes.
-(This is because the idea of "class data" isn't directly implemented
-in Perl, but is instead left to individual class-systems to implement
-as they see fit..)
-
-Note that you may have things stored in a lexicon
-besides just phrases for output: for example, if your program
-takes input from the keyboard, asking a "(Y/N)" question,
-you probably need to know what the equivalent of "Y[es]/N[o]" is
-in whatever language. You probably also need to know what
-the equivalents of the answers "y" and "n" are. You can
-store that information in the lexicon (say, under the keys
-"~answer_y" and "~answer_n", and the long forms as
-"~answer_yes" and "~answer_no", where "~" is just an ad-hoc
-character meant to indicate to programmers/translators that
-these are not phrases for output).
-
-Or instead of storing this in the language class's lexicon,
-you can (and, in some cases, really should) represent the same bit
-of knowledge as code in a method in the language class. (That
-leaves a tidy distinction between the lexicon as the things we
-know how to I<say>, and the rest of the things in the lexicon class
-as things that we know how to I<do>.) Consider
-this example of a processor for responses to French "oui/non"
-questions:
-
- sub y_or_n {
- return undef unless defined $_[1] and length $_[1];
- my $answer = lc $_[1]; # smash case
- return 1 if $answer eq 'o' or $answer eq 'oui';
- return 0 if $answer eq 'n' or $answer eq 'non';
- return undef;
- }
-
-...which you'd then call in a construct like this:
-
- my $response;
- until(defined $response) {
- print $lh->maketext("Open the pod bay door (y/n)? ");
- $response = $lh->y_or_n( get_input_from_keyboard_somehow() );
- }
- if($response) { $pod_bay_door->open() }
- else { $pod_bay_door->leave_closed() }
-
-Other data worth storing in a lexicon might be things like
-filenames for language-targetted resources:
-
- ...
- "_main_splash_png"
- => "/styles/en_us/main_splash.png",
- "_main_splash_imagemap"
- => "/styles/en_us/main_splash.incl",
- "_general_graphics_path"
- => "/styles/en_us/",
- "_alert_sound"
- => "/styles/en_us/hey_there.wav",
- "_forward_icon"
- => "left_arrow.png",
- "_backward_icon"
- => "right_arrow.png",
- # In some other languages, left equals
- # BACKwards, and right is FOREwards.
- ...
-
-You might want to do the same thing for expressing key bindings
-or the like (since hardwiring "q" as the binding for the function
-that quits a screen/menu/program is useful only if your language
-happens to associate "q" with "quit"!)
-
-=head1 BRACKET NOTATION
-
-Bracket Notation is a crucial feature of Locale::Maketext. I mean
-Bracket Notation to provide a replacement for the use of sprintf formatting.
-Everything you do with Bracket Notation could be done with a sub block,
-but bracket notation is meant to be much more concise.
-
-Bracket Notation is a like a miniature "template" system (in the sense
-of L<Text::Template|Text::Template>, not in the sense of C++ templates),
-where normal text is passed thru basically as is, but text in special
-regions is specially interpreted. In Bracket Notation, you use square brackets ("[...]"),
-not curly braces ("{...}") to note sections that are specially interpreted.
-
-For example, here all the areas that are taken literally are underlined with
-a "^", and all the in-bracket special regions are underlined with an X:
-
- "Minimum ([_1]) is larger than maximum ([_2])!\n",
- ^^^^^^^^^ XX ^^^^^^^^^^^^^^^^^^^^^^^^^^ XX ^^^^
-
-When that string is compiled from bracket notation into a real Perl sub,
-it's basically turned into:
-
- sub {
- my $lh = $_[0];
- my @params = @_;
- return join '',
- "Minimum (",
- ...some code here...
- ") is larger than maximum (",
- ...some code here...
- ")!\n",
- }
- # to be called by $lh->maketext(KEY, params...)
-
-In other words, text outside bracket groups is turned into string
-literals. Text in brackets is rather more complex, and currently follows
-these rules:
-
-=over
-
-=item *
-
-Bracket groups that are empty, or which consist only of whitespace,
-are ignored. (Examples: "[]", "[ ]", or a [ and a ] with returns
-and/or tabs and/or spaces between them.
-
-Otherwise, each group is taken to be a comma-separated group of items,
-and each item is interpreted as follows:
-
-=item *
-
-An item that is "_I<digits>" or "_-I<digits>" is interpreted as
-$_[I<value>]. I.e., "_1" becomes with $_[1], and "_-3" is interpreted
-as $_[-3] (in which case @_ should have at least three elements in it).
-Note that $_[0] is the language handle, and is typically not named
-directly.
-
-=item *
-
-An item "_*" is interpreted to mean "all of @_ except $_[0]".
-I.e., C<@_[1..$#_]>. Note that this is an empty list in the case
-of calls like $lh->maketext(I<key>) where there are no
-parameters (except $_[0], the language handle).
-
-=item *
-
-Otherwise, each item is interpreted as a string literal.
-
-=back
-
-The group as a whole is interpreted as follows:
-
-=over
-
-=item *
-
-If the first item in a bracket group looks like a method name,
-then that group is interpreted like this:
-
- $lh->that_method_name(
- ...rest of items in this group...
- ),
-
-=item *
-
-If the first item in a bracket group is "*", it's taken as shorthand
-for the so commonly called "quant" method. Similarly, if the first
-item in a bracket group is "#", it's taken to be shorthand for
-"numf".
-
-=item *
-
-If the first item in a bracket group is the empty-string, or "_*"
-or "_I<digits>" or "_-I<digits>", then that group is interpreted
-as just the interpolation of all its items:
-
- join('',
- ...rest of items in this group...
- ),
-
-Examples: "[_1]" and "[,_1]", which are synonymous; and
-"C<[,ID-(,_4,-,_2,)]>", which compiles as
-C<join "", "ID-(", $_[4], "-", $_[2], ")">.
-
-=item *
-
-Otherwise this bracket group is invalid. For example, in the group
-"[!@#,whatever]", the first item C<"!@#"> is neither the empty-string,
-"_I<number>", "_-I<number>", "_*", nor a valid method name; and so
-Locale::Maketext will throw an exception of you try compiling an
-expression containing this bracket group.
-
-=back
-
-Note, incidentally, that items in each group are comma-separated,
-not C</\s*,\s*/>-separated. That is, you might expect that this
-bracket group:
-
- "Hoohah [foo, _1 , bar ,baz]!"
-
-would compile to this:
-
- sub {
- my $lh = $_[0];
- return join '',
- "Hoohah ",
- $lh->foo( $_[1], "bar", "baz"),
- "!",
- }
-
-But it actually compiles as this:
-
- sub {
- my $lh = $_[0];
- return join '',
- "Hoohah ",
- $lh->foo(" _1 ", " bar ", "baz"), # note the <space> in " bar "
- "!",
- }
-
-In the notation discussed so far, the characters "[" and "]" are given
-special meaning, for opening and closing bracket groups, and "," has
-a special meaning inside bracket groups, where it separates items in the
-group. This begs the question of how you'd express a literal "[" or
-"]" in a Bracket Notation string, and how you'd express a literal
-comma inside a bracket group. For this purpose I've adopted "~" (tilde)
-as an escape character: "~[" means a literal '[' character anywhere
-in Bracket Notation (i.e., regardless of whether you're in a bracket
-group or not), and ditto for "~]" meaning a literal ']', and "~," meaning
-a literal comma. (Altho "," means a literal comma outside of
-bracket groups -- it's only inside bracket groups that commas are special.)
-
-And on the off chance you need a literal tilde in a bracket expression,
-you get it with "~~".
-
-Currently, an unescaped "~" before a character
-other than a bracket or a comma is taken to mean just a "~" and that
-character. I.e., "~X" means the same as "~~X" -- i.e., one literal tilde,
-and then one literal "X". However, by using "~X", you are assuming that
-no future version of Maketext will use "~X" as a magic escape sequence.
-In practice this is not a great problem, since first off you can just
-write "~~X" and not worry about it; second off, I doubt I'll add lots
-of new magic characters to bracket notation; and third off, you
-aren't likely to want literal "~" characters in your messages anyway,
-since it's not a character with wide use in natural language text.
-
-Brackets must be balanced -- every openbracket must have
-one matching closebracket, and vice versa. So these are all B<invalid>:
-
- "I ate [quant,_1,rhubarb pie."
- "I ate [quant,_1,rhubarb pie[."
- "I ate quant,_1,rhubarb pie]."
- "I ate quant,_1,rhubarb pie[."
-
-Currently, bracket groups do not nest. That is, you B<cannot> say:
-
- "Foo [bar,baz,[quux,quuux]]\n";
-
-If you need a notation that's that powerful, use normal Perl:
-
- %Lexicon = (
- ...
- "some_key" => sub {
- my $lh = $_[0];
- join '',
- "Foo ",
- $lh->bar('baz', $lh->quux('quuux')),
- "\n",
- },
- ...
- );
-
-Or write the "bar" method so you don't need to pass it the
-output from calling quux.
-
-I do not anticipate that you will need (or particularly want)
-to nest bracket groups, but you are welcome to email me with
-convincing (real-life) arguments to the contrary.
-
-=head1 AUTO LEXICONS
-
-If maketext goes to look in an individual %Lexicon for an entry
-for I<key> (where I<key> does not start with an underscore), and
-sees none, B<but does see> an entry of "_AUTO" => I<some_true_value>,
-then we actually define $Lexicon{I<key>} = I<key> right then and there,
-and then use that value as if it had been there all
-along. This happens before we even look in any superclass %Lexicons!
-
-(This is meant to be somewhat like the AUTOLOAD mechanism in
-Perl's function call system -- or, looked at another way,
-like the L<AutoLoader|AutoLoader> module.)
-
-I can picture all sorts of circumstances where you just
-do not want lookup to be able to fail (since failing
-normally means that maketext throws a C<die>, although
-see the next section for greater control over that). But
-here's one circumstance where _AUTO lexicons are meant to
-be I<especially> useful:
-
-As you're writing an application, you decide as you go what messages
-you need to emit. Normally you'd go to write this:
-
- if(-e $filename) {
- go_process_file($filename)
- } else {
- print qq{Couldn't find file "$filename"!\n};
- }
-
-but since you anticipate localizing this, you write:
-
- use ThisProject::I18N;
- my $lh = ThisProject::I18N->get_handle();
- # For the moment, assume that things are set up so
- # that we load class ThisProject::I18N::en
- # and that that's the class that $lh belongs to.
- ...
- if(-e $filename) {
- go_process_file($filename)
- } else {
- print $lh->maketext(
- qq{Couldn't find file "[_1]"!\n}, $filename
- );
- }
-
-Now, right after you've just written the above lines, you'd
-normally have to go open the file
-ThisProject/I18N/en.pm, and immediately add an entry:
-
- "Couldn't find file \"[_1]\"!\n"
- => "Couldn't find file \"[_1]\"!\n",
-
-But I consider that somewhat of a distraction from the work
-of getting the main code working -- to say nothing of the fact
-that I often have to play with the program a few times before
-I can decide exactly what wording I want in the messages (which
-in this case would require me to go changing three lines of code:
-the call to maketext with that key, and then the two lines in
-ThisProject/I18N/en.pm).
-
-However, if you set "_AUTO => 1" in the %Lexicon in,
-ThisProject/I18N/en.pm (assuming that English (en) is
-the language that all your programmers will be using for this
-project's internal message keys), then you don't ever have to
-go adding lines like this
-
- "Couldn't find file \"[_1]\"!\n"
- => "Couldn't find file \"[_1]\"!\n",
-
-to ThisProject/I18N/en.pm, because if _AUTO is true there,
-then just looking for an entry with the key "Couldn't find
-file \"[_1]\"!\n" in that lexicon will cause it to be added,
-with that value!
-
-Note that the reason that keys that start with "_"
-are immune to _AUTO isn't anything generally magical about
-the underscore character -- I just wanted a way to have most
-lexicon keys be autoable, except for possibly a few, and I
-arbitrarily decided to use a leading underscore as a signal
-to distinguish those few.
-
-=head1 READONLY LEXICONS
-
-If your lexicon is a tied hash the simple act of caching the compiled value can be fatal.
-
-For example a L<GDBM_File> GDBM_READER tied hash will die with something like:
-
- gdbm store returned -1, errno 2, key "..." at ...
-
-All you need to do is turn on caching outside of the lexicon hash itself like so:
-
- sub init {
- my ($lh) = @_;
- ...
- $lh->{'use_external_lex_cache'} = 1;
- ...
- }
-
-And then instead of storing the compiled value in the lexicon hash it will store it in $lh->{'_external_lex_cache'}
-
-=head1 CONTROLLING LOOKUP FAILURE
-
-If you call $lh->maketext(I<key>, ...parameters...),
-and there's no entry I<key> in $lh's class's %Lexicon, nor
-in the superclass %Lexicon hash, I<and> if we can't auto-make
-I<key> (because either it starts with a "_", or because none
-of its lexicons have C<_AUTO =E<gt> 1,>), then we have
-failed to find a normal way to maketext I<key>. What then
-happens in these failure conditions, depends on the $lh object's
-"fail" attribute.
-
-If the language handle has no "fail" attribute, maketext
-will simply throw an exception (i.e., it calls C<die>, mentioning
-the I<key> whose lookup failed, and naming the line number where
-the calling $lh->maketext(I<key>,...) was.
-
-If the language handle has a "fail" attribute whose value is a
-coderef, then $lh->maketext(I<key>,...params...) gives up and calls:
-
- return $that_subref->($lh, $key, @params);
-
-Otherwise, the "fail" attribute's value should be a string denoting
-a method name, so that $lh->maketext(I<key>,...params...) can
-give up with:
-
- return $lh->$that_method_name($phrase, @params);
-
-The "fail" attribute can be accessed with the C<fail_with> method:
-
- # Set to a coderef:
- $lh->fail_with( \&failure_handler );
-
- # Set to a method name:
- $lh->fail_with( 'failure_method' );
-
- # Set to nothing (i.e., so failure throws a plain exception)
- $lh->fail_with( undef );
-
- # Get the current value
- $handler = $lh->fail_with();
-
-Now, as to what you may want to do with these handlers: Maybe you'd
-want to log what key failed for what class, and then die. Maybe
-you don't like C<die> and instead you want to send the error message
-to STDOUT (or wherever) and then merely C<exit()>.
-
-Or maybe you don't want to C<die> at all! Maybe you could use a
-handler like this:
-
- # Make all lookups fall back onto an English value,
- # but only after we log it for later fingerpointing.
- my $lh_backup = ThisProject->get_handle('en');
- open(LEX_FAIL_LOG, ">>wherever/lex.log") || die "GNAARGH $!";
- sub lex_fail {
- my($failing_lh, $key, $params) = @_;
- print LEX_FAIL_LOG scalar(localtime), "\t",
- ref($failing_lh), "\t", $key, "\n";
- return $lh_backup->maketext($key,@params);
- }
-
-Some users have expressed that they think this whole mechanism of
-having a "fail" attribute at all, seems a rather pointless complication.
-But I want Locale::Maketext to be usable for software projects of I<any>
-scale and type; and different software projects have different ideas
-of what the right thing is to do in failure conditions. I could simply
-say that failure always throws an exception, and that if you want to be
-careful, you'll just have to wrap every call to $lh->maketext in an
-S<eval { }>. However, I want programmers to reserve the right (via
-the "fail" attribute) to treat lookup failure as something other than
-an exception of the same level of severity as a config file being
-unreadable, or some essential resource being inaccessible.
-
-One possibly useful value for the "fail" attribute is the method name
-"failure_handler_auto". This is a method defined in the class
-Locale::Maketext itself. You set it with:
-
- $lh->fail_with('failure_handler_auto');
-
-Then when you call $lh->maketext(I<key>, ...parameters...) and
-there's no I<key> in any of those lexicons, maketext gives up with
-
- return $lh->failure_handler_auto($key, @params);
-
-But failure_handler_auto, instead of dying or anything, compiles
-$key, caching it in
-
- $lh->{'failure_lex'}{$key} = $complied
-
-and then calls the compiled value, and returns that. (I.e., if
-$key looks like bracket notation, $compiled is a sub, and we return
-&{$compiled}(@params); but if $key is just a plain string, we just
-return that.)
-
-The effect of using "failure_auto_handler"
-is like an AUTO lexicon, except that it 1) compiles $key even if
-it starts with "_", and 2) you have a record in the new hashref
-$lh->{'failure_lex'} of all the keys that have failed for
-this object. This should avoid your program dying -- as long
-as your keys aren't actually invalid as bracket code, and as
-long as they don't try calling methods that don't exist.
-
-"failure_auto_handler" may not be exactly what you want, but I
-hope it at least shows you that maketext failure can be mitigated
-in any number of very flexible ways. If you can formalize exactly
-what you want, you should be able to express that as a failure
-handler. You can even make it default for every object of a given
-class, by setting it in that class's init:
-
- sub init {
- my $lh = $_[0]; # a newborn handle
- $lh->SUPER::init();
- $lh->fail_with('my_clever_failure_handler');
- return;
- }
- sub my_clever_failure_handler {
- ...you clever things here...
- }
-
-=head1 HOW TO USE MAKETEXT
-
-Here is a brief checklist on how to use Maketext to localize
-applications:
-
-=over
-
-=item *
-
-Decide what system you'll use for lexicon keys. If you insist,
-you can use opaque IDs (if you're nostalgic for C<catgets>),
-but I have better suggestions in the
-section "Entries in Each Lexicon", above. Assuming you opt for
-meaningful keys that double as values (like "Minimum ([_1]) is
-larger than maximum ([_2])!\n"), you'll have to settle on what
-language those should be in. For the sake of argument, I'll
-call this English, specifically American English, "en-US".
-
-=item *
-
-Create a class for your localization project. This is
-the name of the class that you'll use in the idiom:
-
- use Projname::L10N;
- my $lh = Projname::L10N->get_handle(...) || die "Language?";
-
-Assuming you call your class Projname::L10N, create a class
-consisting minimally of:
-
- package Projname::L10N;
- use base qw(Locale::Maketext);
- ...any methods you might want all your languages to share...
-
- # And, assuming you want the base class to be an _AUTO lexicon,
- # as is discussed a few sections up:
-
- 1;
-
-=item *
-
-Create a class for the language your internal keys are in. Name
-the class after the language-tag for that language, in lowercase,
-with dashes changed to underscores. Assuming your project's first
-language is US English, you should call this Projname::L10N::en_us.
-It should consist minimally of:
-
- package Projname::L10N::en_us;
- use base qw(Projname::L10N);
- %Lexicon = (
- '_AUTO' => 1,
- );
- 1;
-
-(For the rest of this section, I'll assume that this "first
-language class" of Projname::L10N::en_us has
-_AUTO lexicon.)
-
-=item *
-
-Go and write your program. Everywhere in your program where
-you would say:
-
- print "Foobar $thing stuff\n";
-
-instead do it thru maketext, using no variable interpolation in
-the key:
-
- print $lh->maketext("Foobar [_1] stuff\n", $thing);
-
-If you get tired of constantly saying C<print $lh-E<gt>maketext>,
-consider making a functional wrapper for it, like so:
-
- use Projname::L10N;
- use vars qw($lh);
- $lh = Projname::L10N->get_handle(...) || die "Language?";
- sub pmt (@) { print( $lh->maketext(@_)) }
- # "pmt" is short for "Print MakeText"
- $Carp::Verbose = 1;
- # so if maketext fails, we see made the call to pmt
-
-Besides whole phrases meant for output, anything language-dependent
-should be put into the class Projname::L10N::en_us,
-whether as methods, or as lexicon entries -- this is discussed
-in the section "Entries in Each Lexicon", above.
-
-=item *
-
-Once the program is otherwise done, and once its localization for
-the first language works right (via the data and methods in
-Projname::L10N::en_us), you can get together the data for translation.
-If your first language lexicon isn't an _AUTO lexicon, then you already
-have all the messages explicitly in the lexicon (or else you'd be
-getting exceptions thrown when you call $lh->maketext to get
-messages that aren't in there). But if you were (advisedly) lazy and are
-using an _AUTO lexicon, then you've got to make a list of all the phrases
-that you've so far been letting _AUTO generate for you. There are very
-many ways to assemble such a list. The most straightforward is to simply
-grep the source for every occurrence of "maketext" (or calls
-to wrappers around it, like the above C<pmt> function), and to log the
-following phrase.
-
-=item *
-
-You may at this point want to consider whether your base class
-(Projname::L10N), from which all lexicons inherit from (Projname::L10N::en,
-Projname::L10N::es, etc.), should be an _AUTO lexicon. It may be true
-that in theory, all needed messages will be in each language class;
-but in the presumably unlikely or "impossible" case of lookup failure,
-you should consider whether your program should throw an exception,
-emit text in English (or whatever your project's first language is),
-or some more complex solution as described in the section
-"Controlling Lookup Failure", above.
-
-=item *
-
-Submit all messages/phrases/etc. to translators.
-
-(You may, in fact, want to start with localizing to I<one> other language
-at first, if you're not sure that you've properly abstracted the
-language-dependent parts of your code.)
-
-Translators may request clarification of the situation in which a
-particular phrase is found. For example, in English we are entirely happy
-saying "I<n> files found", regardless of whether we mean "I looked for files,
-and found I<n> of them" or the rather distinct situation of "I looked for
-something else (like lines in files), and along the way I saw I<n>
-files." This may involve rethinking things that you thought quite clear:
-should "Edit" on a toolbar be a noun ("editing") or a verb ("to edit")? Is
-there already a conventionalized way to express that menu option, separate
-from the target language's normal word for "to edit"?
-
-In all cases where the very common phenomenon of quantification
-(saying "I<N> files", for B<any> value of N)
-is involved, each translator should make clear what dependencies the
-number causes in the sentence. In many cases, dependency is
-limited to words adjacent to the number, in places where you might
-expect them ("I found the-?PLURAL I<N>
-empty-?PLURAL directory-?PLURAL"), but in some cases there are
-unexpected dependencies ("I found-?PLURAL ..."!) as well as long-distance
-dependencies "The I<N> directory-?PLURAL could not be deleted-?PLURAL"!).
-
-Remind the translators to consider the case where N is 0:
-"0 files found" isn't exactly natural-sounding in any language, but it
-may be unacceptable in many -- or it may condition special
-kinds of agreement (similar to English "I didN'T find ANY files").
-
-Remember to ask your translators about numeral formatting in their
-language, so that you can override the C<numf> method as
-appropriate. Typical variables in number formatting are: what to
-use as a decimal point (comma? period?); what to use as a thousands
-separator (space? nonbreaking space? comma? period? small
-middot? prime? apostrophe?); and even whether the so-called "thousands
-separator" is actually for every third digit -- I've heard reports of
-two hundred thousand being expressible as "2,00,000" for some Indian
-(Subcontinental) languages, besides the less surprising "S<200 000>",
-"200.000", "200,000", and "200'000". Also, using a set of numeral
-glyphs other than the usual ASCII "0"-"9" might be appreciated, as via
-C<tr/0-9/\x{0966}-\x{096F}/> for getting digits in Devanagari script
-(for Hindi, Konkani, others).
-
-The basic C<quant> method that Locale::Maketext provides should be
-good for many languages. For some languages, it might be useful
-to modify it (or its constituent C<numerate> method)
-to take a plural form in the two-argument call to C<quant>
-(as in "[quant,_1,files]") if
-it's all-around easier to infer the singular form from the plural, than
-to infer the plural form from the singular.
-
-But for other languages (as is discussed at length
-in L<Locale::Maketext::TPJ13|Locale::Maketext::TPJ13>), simple
-C<quant>/C<numf> is not enough. For the particularly problematic
-Slavic languages, what you may need is a method which you provide
-with the number, the citation form of the noun to quantify, and
-the case and gender that the sentence's syntax projects onto that
-noun slot. The method would then be responsible for determining
-what grammatical number that numeral projects onto its noun phrase,
-and what case and gender it may override the normal case and gender
-with; and then it would look up the noun in a lexicon providing
-all needed inflected forms.
-
-=item *
-
-You may also wish to discuss with the translators the question of
-how to relate different subforms of the same language tag,
-considering how this reacts with C<get_handle>'s treatment of
-these. For example, if a user accepts interfaces in "en, fr", and
-you have interfaces available in "en-US" and "fr", what should
-they get? You may wish to resolve this by establishing that "en"
-and "en-US" are effectively synonymous, by having one class
-zero-derive from the other.
-
-For some languages this issue may never come up (Danish is rarely
-expressed as "da-DK", but instead is just "da"). And for other
-languages, the whole concept of a "generic" form may verge on
-being uselessly vague, particularly for interfaces involving voice
-media in forms of Arabic or Chinese.
-
-=item *
-
-Once you've localized your program/site/etc. for all desired
-languages, be sure to show the result (whether live, or via
-screenshots) to the translators. Once they approve, make every
-effort to have it then checked by at least one other speaker of
-that language. This holds true even when (or especially when) the
-translation is done by one of your own programmers. Some
-kinds of systems may be harder to find testers for than others,
-depending on the amount of domain-specific jargon and concepts
-involved -- it's easier to find people who can tell you whether
-they approve of your translation for "delete this message" in an
-email-via-Web interface, than to find people who can give you
-an informed opinion on your translation for "attribute value"
-in an XML query tool's interface.
-
-=back
-
-=head1 SEE ALSO
-
-I recommend reading all of these:
-
-L<Locale::Maketext::TPJ13|Locale::Maketext::TPJ13> -- my I<The Perl
-Journal> article about Maketext. It explains many important concepts
-underlying Locale::Maketext's design, and some insight into why
-Maketext is better than the plain old approach of having
-message catalogs that are just databases of sprintf formats.
-
-L<File::Findgrep|File::Findgrep> is a sample application/module
-that uses Locale::Maketext to localize its messages. For a larger
-internationalized system, see also L<Apache::MP3>.
-
-L<I18N::LangTags|I18N::LangTags>.
-
-L<Win32::Locale|Win32::Locale>.
-
-RFC 3066, I<Tags for the Identification of Languages>,
-as at http://sunsite.dk/RFC/rfc/rfc3066.html
-
-RFC 2277, I<IETF Policy on Character Sets and Languages>
-is at http://sunsite.dk/RFC/rfc/rfc2277.html -- much of it is
-just things of interest to protocol designers, but it explains
-some basic concepts, like the distinction between locales and
-language-tags.
-
-The manual for GNU C<gettext>. The gettext dist is available in
-C<ftp://prep.ai.mit.edu/pub/gnu/> -- get
-a recent gettext tarball and look in its "doc/" directory, there's
-an easily browsable HTML version in there. The
-gettext documentation asks lots of questions worth thinking
-about, even if some of their answers are sometimes wonky,
-particularly where they start talking about pluralization.
-
-The Locale/Maketext.pm source. Obverse that the module is much
-shorter than its documentation!
-
-=head1 COPYRIGHT AND DISCLAIMER
-
-Copyright (c) 1999-2004 Sean M. Burke. All rights reserved.
-
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
-
-This program is distributed in the hope that it will be useful, but
-without any warranty; without even the implied warranty of
-merchantability or fitness for a particular purpose.
-
-=head1 AUTHOR
-
-Sean M. Burke C<sburke@cpan.org>
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Locale/Maketext/Cookbook.pod b/Master/tlpkg/tlperl/lib/Locale/Maketext/Cookbook.pod
deleted file mode 100644
index 3457f7ca12a..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Maketext/Cookbook.pod
+++ /dev/null
@@ -1,150 +0,0 @@
-# This document contains text in Perl "POD" format.
-# Use a POD viewer like perldoc or perlman to render it.
-
-=encoding utf-8
-
-=head1 NAME
-
-Locale::Maketext::Cookbook - recipes for using Locale::Maketext
-
-=head1 INTRODUCTION
-
-This is a work in progress. Not much progress by now :-)
-
-=head1 ONESIDED LEXICONS
-
-I<Adapted from a suggestion by Dan Muey>
-
-It may be common (for example at your main lexicon) that
-the hash keys and values coincide. Like that
-
- q{Hello, tell me your name}
- => q{Hello, tell me your name}
-
-It would be nice to just write:
-
- q{Hello, tell me your name} => ''
-
-and have this magically inflated to the first form.
-Among the advantages of such representation, that would
-lead to
-smaller files, less prone to mistyping or mispasting,
-and handy to someone translating it which can simply
-copy the main lexicon and enter the translation
-instead of having to remove the value first.
-
-That can be achieved by overriding C<init>
-in your class and working on the main lexicon
-with code like that:
-
- package My::I18N;
- ...
-
- sub init {
- my $lh = shift; # a newborn handle
- $lh->SUPER::init();
- inflate_lexicon(\%My::I18N::en::Lexicon);
- return;
- }
-
- sub inflate_lexicon {
- my $lex = shift;
- while (my ($k, $v) = each %$lex) {
- $v = $k if !defined $v || $v eq '';
- }
- }
-
-Here we are assuming C<My::I18N::en> to own the
-main lexicon.
-
-There are some downsides here: the size economy
-will not stand at runtime after this C<init()>
-runs. But it should not be that critical, since
-if you don't have space for that, you won't have
-space for any other language besides the main one
-as well. You could do that too with ties,
-expanding the value at lookup time which
-should be more time expensive as an option.
-
-=head1 DECIMAL PLACES IN NUMBER FORMATTING
-
-I<After CPAN RT #36136 (https://rt.cpan.org/Ticket/Display.html?id=36136)>
-
-The documentation of L<Locale::Maketext> advises that
-the standard bracket method C<numf> is limited and that
-you must override that for better results. It even
-suggests the use of L<Number::Format>.
-
-One such defect of standard C<numf> is to not be
-able to use a certain decimal precision.
-For example,
-
- $lh->maketext('pi is [numf,_1]', 355/113);
-
-outputs
-
- pi is 3.14159292035398
-
-Since pi ≈ 355/116 is only accurate
-to 6 decimal places, you would want to say:
-
- $lh->maketext('pi is [numf,_1,6]', 355/113);
-
-and get "pi is 3.141592".
-
-One solution for that could use C<Number::Format>
-like that:
-
- package Wuu;
-
- use base qw(Locale::Maketext);
-
- use Number::Format;
-
- # can be overridden according to language conventions
- sub _numf_params {
- return (
- -thousands_sep => '.',
- -decimal_point => ',',
- -decimal_digits => 2,
- );
- }
-
- # builds a Number::Format
- sub _numf_formatter {
- my ($lh, $scale) = @_;
- my @params = $lh->_numf_params;
- if ($scale) { # use explicit scale rather than default
- push @params, (-decimal_digits => $scale);
- }
- return Number::Format->new(@params);
- }
-
- sub numf {
- my ($lh, $n, $scale) = @_;
- # get the (cached) formatter
- my $nf = $lh->{__nf}{$scale} ||= $lh->_numf_formatter($scale);
- # format the number itself
- return $nf->format_number($n);
- }
-
- package Wuu::pt;
-
- use base qw(Wuu);
-
-and then
-
- my $lh = Wuu->get_handle('pt');
- $lh->maketext('A [numf,_1,3] km de distância', 1550.2222);
-
-would return "A 1.550,222 km de distância".
-
-Notice that the standard utility methods of
-C<Locale::Maketext> are irremediably limited
-because they could not aim to do everything
-that could be expected from them in different languages,
-cultures and applications. So extending C<numf>,
-C<quant>, and C<sprintf> is natural as soon
-as your needs exceed what the standard ones do.
-
-
diff --git a/Master/tlpkg/tlperl/lib/Locale/Maketext/TPJ13.pod b/Master/tlpkg/tlperl/lib/Locale/Maketext/TPJ13.pod
deleted file mode 100644
index b9586b2cbf4..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Maketext/TPJ13.pod
+++ /dev/null
@@ -1,775 +0,0 @@
-# This document contains text in Perl "POD" format.
-# Use a POD viewer like perldoc or perlman to render it.
-
-=head1 NAME
-
-Locale::Maketext::TPJ13 -- article about software localization
-
-=head1 SYNOPSIS
-
- # This an article, not a module.
-
-=head1 DESCRIPTION
-
-The following article by Sean M. Burke and Jordan Lachler
-first appeared in I<The Perl Journal> #13
-and is copyright 1999 The Perl Journal. It appears
-courtesy of Jon Orwant and The Perl Journal. This document may be
-distributed under the same terms as Perl itself.
-
-=head1 Localization and Perl: gettext breaks, Maketext fixes
-
-by Sean M. Burke and Jordan Lachler
-
-This article points out cases where gettext (a common system for
-localizing software interfaces -- i.e., making them work in the user's
-language of choice) fails because of basic differences between human
-languages. This article then describes Maketext, a new system capable
-of correctly treating these differences.
-
-=head2 A Localization Horror Story: It Could Happen To You
-
-=over
-
-"There are a number of languages spoken by human beings in this
-world."
-
--- Harald Tveit Alvestrand, in RFC 1766, "Tags for the
-Identification of Languages"
-
-=back
-
-Imagine that your task for the day is to localize a piece of software
--- and luckily for you, the only output the program emits is two
-messages, like this:
-
- I scanned 12 directories.
-
- Your query matched 10 files in 4 directories.
-
-So how hard could that be? You look at the code that
-produces the first item, and it reads:
-
- printf("I scanned %g directories.",
- $directory_count);
-
-You think about that, and realize that it doesn't even work right for
-English, as it can produce this output:
-
- I scanned 1 directories.
-
-So you rewrite it to read:
-
- printf("I scanned %g %s.",
- $directory_count,
- $directory_count == 1 ?
- "directory" : "directories",
- );
-
-...which does the Right Thing. (In case you don't recall, "%g" is for
-locale-specific number interpolation, and "%s" is for string
-interpolation.)
-
-But you still have to localize it for all the languages you're
-producing this software for, so you pull Locale::gettext off of CPAN
-so you can access the C<gettext> C functions you've heard are standard
-for localization tasks.
-
-And you write:
-
- printf(gettext("I scanned %g %s."),
- $dir_scan_count,
- $dir_scan_count == 1 ?
- gettext("directory") : gettext("directories"),
- );
-
-But you then read in the gettext manual (Drepper, Miller, and Pinard 1995)
-that this is not a good idea, since how a single word like "directory"
-or "directories" is translated may depend on context -- and this is
-true, since in a case language like German or Russian, you'd may need
-these words with a different case ending in the first instance (where the
-word is the object of a verb) than in the second instance, which you haven't even
-gotten to yet (where the word is the object of a preposition, "in %g
-directories") -- assuming these keep the same syntax when translated
-into those languages.
-
-So, on the advice of the gettext manual, you rewrite:
-
- printf( $dir_scan_count == 1 ?
- gettext("I scanned %g directory.") :
- gettext("I scanned %g directories."),
- $dir_scan_count );
-
-So, you email your various translators (the boss decides that the
-languages du jour are Chinese, Arabic, Russian, and Italian, so you
-have one translator for each), asking for translations for "I scanned
-%g directory." and "I scanned %g directories.". When they reply,
-you'll put that in the lexicons for gettext to use when it localizes
-your software, so that when the user is running under the "zh"
-(Chinese) locale, gettext("I scanned %g directory.") will return the
-appropriate Chinese text, with a "%g" in there where printf can then
-interpolate $dir_scan.
-
-Your Chinese translator emails right back -- he says both of these
-phrases translate to the same thing in Chinese, because, in linguistic
-jargon, Chinese "doesn't have number as a grammatical category" --
-whereas English does. That is, English has grammatical rules that
-refer to "number", i.e., whether something is grammatically singular
-or plural; and one of these rules is the one that forces nouns to take
-a plural suffix (generally "s") when in a plural context, as they are when
-they follow a number other than "one" (including, oddly enough, "zero").
-Chinese has no such rules, and so has just the one phrase where English
-has two. But, no problem, you can have this one Chinese phrase appear
-as the translation for the two English phrases in the "zh" gettext
-lexicon for your program.
-
-Emboldened by this, you dive into the second phrase that your software
-needs to output: "Your query matched 10 files in 4 directories.". You notice
-that if you want to treat phrases as indivisible, as the gettext
-manual wisely advises, you need four cases now, instead of two, to
-cover the permutations of singular and plural on the two items,
-$dir_count and $file_count. So you try this:
-
- printf( $file_count == 1 ?
- ( $directory_count == 1 ?
- gettext("Your query matched %g file in %g directory.") :
- gettext("Your query matched %g file in %g directories.") ) :
- ( $directory_count == 1 ?
- gettext("Your query matched %g files in %g directory.") :
- gettext("Your query matched %g files in %g directories.") ),
- $file_count, $directory_count,
- );
-
-(The case of "1 file in 2 [or more] directories" could, I suppose,
-occur in the case of symlinking or something of the sort.)
-
-It occurs to you that this is not the prettiest code you've ever
-written, but this seems the way to go. You mail off to the
-translators asking for translations for these four cases. The
-Chinese guy replies with the one phrase that these all translate to in
-Chinese, and that phrase has two "%g"s in it, as it should -- but
-there's a problem. He translates it word-for-word back: "In %g
-directories contains %g files match your query." The %g
-slots are in an order reverse to what they are in English. You wonder
-how you'll get gettext to handle that.
-
-But you put it aside for the moment, and optimistically hope that the
-other translators won't have this problem, and that their languages
-will be better behaved -- i.e., that they will be just like English.
-
-But the Arabic translator is the next to write back. First off, your
-code for "I scanned %g directory." or "I scanned %g directories."
-assumes there's only singular or plural. But, to use linguistic
-jargon again, Arabic has grammatical number, like English (but unlike
-Chinese), but it's a three-term category: singular, dual, and plural.
-In other words, the way you say "directory" depends on whether there's
-one directory, or I<two> of them, or I<more than two> of them. Your
-test of C<($directory == 1)> no longer does the job. And it means
-that where English's grammatical category of number necessitates
-only the two permutations of the first sentence based on "directory
-[singular]" and "directories [plural]", Arabic has three -- and,
-worse, in the second sentence ("Your query matched %g file in %g
-directory."), where English has four, Arabic has nine. You sense
-an unwelcome, exponential trend taking shape.
-
-Your Italian translator emails you back and says that "I searched 0
-directories" (a possible English output of your program) is stilted,
-and if you think that's fine English, that's your problem, but that
-I<just will not do> in the language of Dante. He insists that where
-$directory_count is 0, your program should produce the Italian text
-for "I I<didn't> scan I<any> directories.". And ditto for "I didn't
-match any files in any directories", although he says the last part
-about "in any directories" should probably just be left off.
-
-You wonder how you'll get gettext to handle this; to accommodate the
-ways Arabic, Chinese, and Italian deal with numbers in just these few
-very simple phrases, you need to write code that will ask gettext for
-different queries depending on whether the numerical values in
-question are 1, 2, more than 2, or in some cases 0, and you still haven't
-figured out the problem with the different word order in Chinese.
-
-Then your Russian translator calls on the phone, to I<personally> tell
-you the bad news about how really unpleasant your life is about to
-become:
-
-Russian, like German or Latin, is an inflectional language; that is, nouns
-and adjectives have to take endings that depend on their case
-(i.e., nominative, accusative, genitive, etc...) -- which is roughly a matter of
-what role they have in syntax of the sentence --
-as well as on the grammatical gender (i.e., masculine, feminine, neuter)
-and number (i.e., singular or plural) of the noun, as well as on the
-declension class of the noun. But unlike with most other inflected languages,
-putting a number-phrase (like "ten" or "forty-three", or their Arabic
-numeral equivalents) in front of noun in Russian can change the case and
-number that noun is, and therefore the endings you have to put on it.
-
-He elaborates: In "I scanned %g directories", you'd I<expect>
-"directories" to be in the accusative case (since it is the direct
-object in the sentence) and the plural number,
-except where $directory_count is 1, then you'd expect the singular, of
-course. Just like Latin or German. I<But!> Where $directory_count %
-10 is 1 ("%" for modulo, remember), assuming $directory count is an
-integer, and except where $directory_count % 100 is 11, "directories"
-is forced to become grammatically singular, which means it gets the
-ending for the accusative singular... You begin to visualize the code
-it'd take to test for the problem so far, I<and still work for Chinese
-and Arabic and Italian>, and how many gettext items that'd take, but
-he keeps going... But where $directory_count % 10 is 2, 3, or 4
-(except where $directory_count % 100 is 12, 13, or 14), the word for
-"directories" is forced to be genitive singular -- which means another
-ending... The room begins to spin around you, slowly at first... But
-with I<all other> integer values, since "directory" is an inanimate
-noun, when preceded by a number and in the nominative or accusative
-cases (as it is here, just your luck!), it does stay plural, but it is
-forced into the genitive case -- yet another ending... And
-you never hear him get to the part about how you're going to run into
-similar (but maybe subtly different) problems with other Slavic
-languages like Polish, because the floor comes up to meet you, and you
-fade into unconsciousness.
-
-
-The above cautionary tale relates how an attempt at localization can
-lead from programmer consternation, to program obfuscation, to a need
-for sedation. But careful evaluation shows that your choice of tools
-merely needed further consideration.
-
-=head2 The Linguistic View
-
-=over
-
-"It is more complicated than you think."
-
--- The Eighth Networking Truth, from RFC 1925
-
-=back
-
-The field of Linguistics has expended a great deal of effort over the
-past century trying to find grammatical patterns which hold across
-languages; it's been a constant process
-of people making generalizations that should apply to all languages,
-only to find out that, all too often, these generalizations fail --
-sometimes failing for just a few languages, sometimes whole classes of
-languages, and sometimes nearly every language in the world except
-English. Broad statistical trends are evident in what the "average
-language" is like as far as what its rules can look like, must look
-like, and cannot look like. But the "average language" is just as
-unreal a concept as the "average person" -- it runs up against the
-fact no language (or person) is, in fact, average. The wisdom of past
-experience leads us to believe that any given language can do whatever
-it wants, in any order, with appeal to any kind of grammatical
-categories wants -- case, number, tense, real or metaphoric
-characteristics of the things that words refer to, arbitrary or
-predictable classifications of words based on what endings or prefixes
-they can take, degree or means of certainty about the truth of
-statements expressed, and so on, ad infinitum.
-
-Mercifully, most localization tasks are a matter of finding ways to
-translate whole phrases, generally sentences, where the context is
-relatively set, and where the only variation in content is I<usually>
-in a number being expressed -- as in the example sentences above.
-Translating specific, fully-formed sentences is, in practice, fairly
-foolproof -- which is good, because that's what's in the phrasebooks
-that so many tourists rely on. Now, a given phrase (whether in a
-phrasebook or in a gettext lexicon) in one language I<might> have a
-greater or lesser applicability than that phrase's translation into
-another language -- for example, strictly speaking, in Arabic, the
-"your" in "Your query matched..." would take a different form
-depending on whether the user is male or female; so the Arabic
-translation "your[feminine] query" is applicable in fewer cases than
-the corresponding English phrase, which doesn't distinguish the user's
-gender. (In practice, it's not feasible to have a program know the
-user's gender, so the masculine "you" in Arabic is usually used, by
-default.)
-
-But in general, such surprises are rare when entire sentences are
-being translated, especially when the functional context is restricted
-to that of a computer interacting with a user either to convey a fact
-or to prompt for a piece of information. So, for purposes of
-localization, translation by phrase (generally by sentence) is both the
-simplest and the least problematic.
-
-=head2 Breaking gettext
-
-=over
-
-"It Has To Work."
-
--- First Networking Truth, RFC 1925
-
-=back
-
-Consider that sentences in a tourist phrasebook are of two types: ones
-like "How do I get to the marketplace?" that don't have any blanks to
-fill in, and ones like "How much do these ___ cost?", where there's
-one or more blanks to fill in (and these are usually linked to a
-list of words that you can put in that blank: "fish", "potatoes",
-"tomatoes", etc.) The ones with no blanks are no problem, but the
-fill-in-the-blank ones may not be really straightforward. If it's a
-Swahili phrasebook, for example, the authors probably didn't bother to
-tell you the complicated ways that the verb "cost" changes its
-inflectional prefix depending on the noun you're putting in the blank.
-The trader in the marketplace will still understand what you're saying if
-you say "how much do these potatoes cost?" with the wrong
-inflectional prefix on "cost". After all, I<you> can't speak proper Swahili,
-I<you're> just a tourist. But while tourists can be stupid, computers
-are supposed to be smart; the computer should be able to fill in the
-blank, and still have the results be grammatical.
-
-In other words, a phrasebook entry takes some values as parameters
-(the things that you fill in the blank or blanks), and provides a value
-based on these parameters, where the way you get that final value from
-the given values can, properly speaking, involve an arbitrarily
-complex series of operations. (In the case of Chinese, it'd be not at
-all complex, at least in cases like the examples at the beginning of
-this article; whereas in the case of Russian it'd be a rather complex
-series of operations. And in some languages, the
-complexity could be spread around differently: while the act of
-putting a number-expression in front of a noun phrase might not be
-complex by itself, it may change how you have to, for example, inflect
-a verb elsewhere in the sentence. This is what in syntax is called
-"long-distance dependencies".)
-
-This talk of parameters and arbitrary complexity is just another way
-to say that an entry in a phrasebook is what in a programming language
-would be called a "function". Just so you don't miss it, this is the
-crux of this article: I<A phrase is a function; a phrasebook is a
-bunch of functions.>
-
-The reason that using gettext runs into walls (as in the above
-second-person horror story) is that you're trying to use a string (or
-worse, a choice among a bunch of strings) to do what you really need a
-function for -- which is futile. Preforming (s)printf interpolation
-on the strings which you get back from gettext does allow you to do I<some>
-common things passably well... sometimes... sort of; but, to paraphrase
-what some people say about C<csh> script programming, "it fools you
-into thinking you can use it for real things, but you can't, and you
-don't discover this until you've already spent too much time trying,
-and by then it's too late."
-
-=head2 Replacing gettext
-
-So, what needs to replace gettext is a system that supports lexicons
-of functions instead of lexicons of strings. An entry in a lexicon
-from such a system should I<not> look like this:
-
- "J'ai trouv\xE9 %g fichiers dans %g r\xE9pertoires"
-
-[\xE9 is e-acute in Latin-1. Some pod renderers would
-scream if I used the actual character here. -- SB]
-
-but instead like this, bearing in mind that this is just a first stab:
-
- sub I_found_X1_files_in_X2_directories {
- my( $files, $dirs ) = @_[0,1];
- $files = sprintf("%g %s", $files,
- $files == 1 ? 'fichier' : 'fichiers');
- $dirs = sprintf("%g %s", $dirs,
- $dirs == 1 ? "r\xE9pertoire" : "r\xE9pertoires");
- return "J'ai trouv\xE9 $files dans $dirs.";
- }
-
-Now, there's no particularly obvious way to store anything but strings
-in a gettext lexicon; so it looks like we just have to start over and
-make something better, from scratch. I call my shot at a
-gettext-replacement system "Maketext", or, in CPAN terms,
-Locale::Maketext.
-
-When designing Maketext, I chose to plan its main features in terms of
-"buzzword compliance". And here are the buzzwords:
-
-=head2 Buzzwords: Abstraction and Encapsulation
-
-The complexity of the language you're trying to output a phrase in is
-entirely abstracted inside (and encapsulated within) the Maketext module
-for that interface. When you call:
-
- print $lang->maketext("You have [quant,_1,piece] of new mail.",
- scalar(@messages));
-
-you don't know (and in fact can't easily find out) whether this will
-involve lots of figuring, as in Russian (if $lang is a handle to the
-Russian module), or relatively little, as in Chinese. That kind of
-abstraction and encapsulation may encourage other pleasant buzzwords
-like modularization and stratification, depending on what design
-decisions you make.
-
-=head2 Buzzword: Isomorphism
-
-"Isomorphism" means "having the same structure or form"; in discussions
-of program design, the word takes on the special, specific meaning that
-your implementation of a solution to a problem I<has the same
-structure> as, say, an informal verbal description of the solution, or
-maybe of the problem itself. Isomorphism is, all things considered,
-a good thing -- it's what problem-solving (and solution-implementing)
-should look like.
-
-What's wrong the with gettext-using code like this...
-
- printf( $file_count == 1 ?
- ( $directory_count == 1 ?
- "Your query matched %g file in %g directory." :
- "Your query matched %g file in %g directories." ) :
- ( $directory_count == 1 ?
- "Your query matched %g files in %g directory." :
- "Your query matched %g files in %g directories." ),
- $file_count, $directory_count,
- );
-
-is first off that it's not well abstracted -- these ways of testing
-for grammatical number (as in the expressions like C<foo == 1 ?
-singular_form : plural_form>) should be abstracted to each language
-module, since how you get grammatical number is language-specific.
-
-But second off, it's not isomorphic -- the "solution" (i.e., the
-phrasebook entries) for Chinese maps from these four English phrases to
-the one Chinese phrase that fits for all of them. In other words, the
-informal solution would be "The way to say what you want in Chinese is
-with the one phrase 'For your question, in Y directories you would
-find X files'" -- and so the implemented solution should be,
-isomorphically, just a straightforward way to spit out that one
-phrase, with numerals properly interpolated. It shouldn't have to map
-from the complexity of other languages to the simplicity of this one.
-
-=head2 Buzzword: Inheritance
-
-There's a great deal of reuse possible for sharing of phrases between
-modules for related dialects, or for sharing of auxiliary functions
-between related languages. (By "auxiliary functions", I mean
-functions that don't produce phrase-text, but which, say, return an
-answer to "does this number require a plural noun after it?". Such
-auxiliary functions would be used in the internal logic of functions
-that actually do produce phrase-text.)
-
-In the case of sharing phrases, consider that you have an interface
-already localized for American English (probably by having been
-written with that as the native locale, but that's incidental).
-Localizing it for UK English should, in practical terms, be just a
-matter of running it past a British person with the instructions to
-indicate what few phrases would benefit from a change in spelling or
-possibly minor rewording. In that case, you should be able to put in
-the UK English localization module I<only> those phrases that are
-UK-specific, and for all the rest, I<inherit> from the American
-English module. (And I expect this same situation would apply with
-Brazilian and Continental Portugese, possibly with some I<very>
-closely related languages like Czech and Slovak, and possibly with the
-slightly different "versions" of written Mandarin Chinese, as I hear exist in
-Taiwan and mainland China.)
-
-As to sharing of auxiliary functions, consider the problem of Russian
-numbers from the beginning of this article; obviously, you'd want to
-write only once the hairy code that, given a numeric value, would
-return some specification of which case and number a given quantified
-noun should use. But suppose that you discover, while localizing an
-interface for, say, Ukranian (a Slavic language related to Russian,
-spoken by several million people, many of whom would be relieved to
-find that your Web site's or software's interface is available in
-their language), that the rules in Ukranian are the same as in Russian
-for quantification, and probably for many other grammatical functions.
-While there may well be no phrases in common between Russian and
-Ukranian, you could still choose to have the Ukranian module inherit
-from the Russian module, just for the sake of inheriting all the
-various grammatical methods. Or, probably better organizationally,
-you could move those functions to a module called C<_E_Slavic> or
-something, which Russian and Ukrainian could inherit useful functions
-from, but which would (presumably) provide no lexicon.
-
-=head2 Buzzword: Concision
-
-Okay, concision isn't a buzzword. But it should be, so I decree that
-as a new buzzword, "concision" means that simple common things should
-be expressible in very few lines (or maybe even just a few characters)
-of code -- call it a special case of "making simple things easy and
-hard things possible", and see also the role it played in the
-MIDI::Simple language, discussed elsewhere in this issue [TPJ#13].
-
-Consider our first stab at an entry in our "phrasebook of functions":
-
- sub I_found_X1_files_in_X2_directories {
- my( $files, $dirs ) = @_[0,1];
- $files = sprintf("%g %s", $files,
- $files == 1 ? 'fichier' : 'fichiers');
- $dirs = sprintf("%g %s", $dirs,
- $dirs == 1 ? "r\xE9pertoire" : "r\xE9pertoires");
- return "J'ai trouv\xE9 $files dans $dirs.";
- }
-
-You may sense that a lexicon (to use a non-committal catch-all term for a
-collection of things you know how to say, regardless of whether they're
-phrases or words) consisting of functions I<expressed> as above would
-make for rather long-winded and repetitive code -- even if you wisely
-rewrote this to have quantification (as we call adding a number
-expression to a noun phrase) be a function called like:
-
- sub I_found_X1_files_in_X2_directories {
- my( $files, $dirs ) = @_[0,1];
- $files = quant($files, "fichier");
- $dirs = quant($dirs, "r\xE9pertoire");
- return "J'ai trouv\xE9 $files dans $dirs.";
- }
-
-And you may also sense that you do not want to bother your translators
-with having to write Perl code -- you'd much rather that they spend
-their I<very costly time> on just translation. And this is to say
-nothing of the near impossibility of finding a commercial translator
-who would know even simple Perl.
-
-In a first-hack implementation of Maketext, each language-module's
-lexicon looked like this:
-
- %Lexicon = (
- "I found %g files in %g directories"
- => sub {
- my( $files, $dirs ) = @_[0,1];
- $files = quant($files, "fichier");
- $dirs = quant($dirs, "r\xE9pertoire");
- return "J'ai trouv\xE9 $files dans $dirs.";
- },
- ... and so on with other phrase => sub mappings ...
- );
-
-but I immediately went looking for some more concise way to basically
-denote the same phrase-function -- a way that would also serve to
-concisely denote I<most> phrase-functions in the lexicon for I<most>
-languages. After much time and even some actual thought, I decided on
-this system:
-
-* Where a value in a %Lexicon hash is a contentful string instead of
-an anonymous sub (or, conceivably, a coderef), it would be interpreted
-as a sort of shorthand expression of what the sub does. When accessed
-for the first time in a session, it is parsed, turned into Perl code,
-and then eval'd into an anonymous sub; then that sub replaces the
-original string in that lexicon. (That way, the work of parsing and
-evaling the shorthand form for a given phrase is done no more than
-once per session.)
-
-* Calls to C<maketext> (as Maketext's main function is called) happen
-thru a "language session handle", notionally very much like an IO
-handle, in that you open one at the start of the session, and use it
-for "sending signals" to an object in order to have it return the text
-you want.
-
-So, this:
-
- $lang->maketext("You have [quant,_1,piece] of new mail.",
- scalar(@messages));
-
-basically means this: look in the lexicon for $lang (which may inherit
-from any number of other lexicons), and find the function that we
-happen to associate with the string "You have [quant,_1,piece] of new
-mail" (which is, and should be, a functioning "shorthand" for this
-function in the native locale -- English in this case). If you find
-such a function, call it with $lang as its first parameter (as if it
-were a method), and then a copy of scalar(@messages) as its second,
-and then return that value. If that function was found, but was in
-string shorthand instead of being a fully specified function, parse it
-and make it into a function before calling it the first time.
-
-* The shorthand uses code in brackets to indicate method calls that
-should be performed. A full explanation is not in order here, but a
-few examples will suffice:
-
- "You have [quant,_1,piece] of new mail."
-
-The above code is shorthand for, and will be interpreted as,
-this:
-
- sub {
- my $handle = $_[0];
- my(@params) = @_;
- return join '',
- "You have ",
- $handle->quant($params[1], 'piece'),
- "of new mail.";
- }
-
-where "quant" is the name of a method you're using to quantify the
-noun "piece" with the number $params[0].
-
-A string with no brackety calls, like this:
-
- "Your search expression was malformed."
-
-is somewhat of a degenerate case, and just gets turned into:
-
- sub { return "Your search expression was malformed." }
-
-However, not everything you can write in Perl code can be written in
-the above shorthand system -- not by a long shot. For example, consider
-the Italian translator from the beginning of this article, who wanted
-the Italian for "I didn't find any files" as a special case, instead
-of "I found 0 files". That couldn't be specified (at least not easily
-or simply) in our shorthand system, and it would have to be written
-out in full, like this:
-
- sub { # pretend the English strings are in Italian
- my($handle, $files, $dirs) = @_[0,1,2];
- return "I didn't find any files" unless $files;
- return join '',
- "I found ",
- $handle->quant($files, 'file'),
- " in ",
- $handle->quant($dirs, 'directory'),
- ".";
- }
-
-Next to a lexicon full of shorthand code, that sort of sticks out like a
-sore thumb -- but this I<is> a special case, after all; and at least
-it's possible, if not as concise as usual.
-
-As to how you'd implement the Russian example from the beginning of
-the article, well, There's More Than One Way To Do It, but it could be
-something like this (using English words for Russian, just so you know
-what's going on):
-
- "I [quant,_1,directory,accusative] scanned."
-
-This shifts the burden of complexity off to the quant method. That
-method's parameters are: the numeric value it's going to use to
-quantify something; the Russian word it's going to quantify; and the
-parameter "accusative", which you're using to mean that this
-sentence's syntax wants a noun in the accusative case there, although
-that quantification method may have to overrule, for grammatical
-reasons you may recall from the beginning of this article.
-
-Now, the Russian quant method here is responsible not only for
-implementing the strange logic necessary for figuring out how Russian
-number-phrases impose case and number on their noun-phrases, but also
-for inflecting the Russian word for "directory". How that inflection
-is to be carried out is no small issue, and among the solutions I've
-seen, some (like variations on a simple lookup in a hash where all
-possible forms are provided for all necessary words) are
-straightforward but I<can> become cumbersome when you need to inflect
-more than a few dozen words; and other solutions (like using
-algorithms to model the inflections, storing only root forms and
-irregularities) I<can> involve more overhead than is justifiable for
-all but the largest lexicons.
-
-Mercifully, this design decision becomes crucial only in the hairiest
-of inflected languages, of which Russian is by no means the I<worst> case
-scenario, but is worse than most. Most languages have simpler
-inflection systems; for example, in English or Swahili, there are
-generally no more than two possible inflected forms for a given noun
-("error/errors"; "kosa/makosa"), and the
-rules for producing these forms are fairly simple -- or at least,
-simple rules can be formulated that work for most words, and you can
-then treat the exceptions as just "irregular", at least relative to
-your ad hoc rules. A simpler inflection system (simpler rules, fewer
-forms) means that design decisions are less crucial to maintaining
-sanity, whereas the same decisions could incur
-overhead-versus-scalability problems in languages like Russian. It
-may I<also> be likely that code (possibly in Perl, as with
-Lingua::EN::Inflect, for English nouns) has already
-been written for the language in question, whether simple or complex.
-
-Moreover, a third possibility may even be simpler than anything
-discussed above: "Just require that all possible (or at least
-applicable) forms be provided in the call to the given language's quant
-method, as in:"
-
- "I found [quant,_1,file,files]."
-
-That way, quant just has to chose which form it needs, without having
-to look up or generate anything. While possibly not optimal for
-Russian, this should work well for most other languages, where
-quantification is not as complicated an operation.
-
-=head2 The Devil in the Details
-
-There's plenty more to Maketext than described above -- for example,
-there's the details of how language tags ("en-US", "i-pwn", "fi",
-etc.) or locale IDs ("en_US") interact with actual module naming
-("BogoQuery/Locale/en_us.pm"), and what magic can ensue; there's the
-details of how to record (and possibly negotiate) what character
-encoding Maketext will return text in (UTF8? Latin-1? KOI8?). There's
-the interesting fact that Maketext is for localization, but nowhere
-actually has a "C<use locale;>" anywhere in it. For the curious,
-there's the somewhat frightening details of how I actually
-implement something like data inheritance so that searches across
-modules' %Lexicon hashes can parallel how Perl implements method
-inheritance.
-
-And, most importantly, there's all the practical details of how to
-actually go about deriving from Maketext so you can use it for your
-interfaces, and the various tools and conventions for starting out and
-maintaining individual language modules.
-
-That is all covered in the documentation for Locale::Maketext and the
-modules that come with it, available in CPAN. After having read this
-article, which covers the why's of Maketext, the documentation,
-which covers the how's of it, should be quite straightforward.
-
-=head2 The Proof in the Pudding: Localizing Web Sites
-
-Maketext and gettext have a notable difference: gettext is in C,
-accessible thru C library calls, whereas Maketext is in Perl, and
-really can't work without a Perl interpreter (although I suppose
-something like it could be written for C). Accidents of history (and
-not necessarily lucky ones) have made C++ the most common language for
-the implementation of applications like word processors, Web browsers,
-and even many in-house applications like custom query systems. Current
-conditions make it somewhat unlikely that the next one of any of these
-kinds of applications will be written in Perl, albeit clearly more for
-reasons of custom and inertia than out of consideration of what is the
-right tool for the job.
-
-However, other accidents of history have made Perl a well-accepted
-language for design of server-side programs (generally in CGI form)
-for Web site interfaces. Localization of static pages in Web sites is
-trivial, feasable either with simple language-negotiation features in
-servers like Apache, or with some kind of server-side inclusions of
-language-appropriate text into layout templates. However, I think
-that the localization of Perl-based search systems (or other kinds of
-dynamic content) in Web sites, be they public or access-restricted,
-is where Maketext will see the greatest use.
-
-I presume that it would be only the exceptional Web site that gets
-localized for English I<and> Chinese I<and> Italian I<and> Arabic
-I<and> Russian, to recall the languages from the beginning of this
-article -- to say nothing of German, Spanish, French, Japanese,
-Finnish, and Hindi, to name a few languages that benefit from large
-numbers of programmers or Web viewers or both.
-
-However, the ever-increasing internationalization of the Web (whether
-measured in terms of amount of content, of numbers of content writers
-or programmers, or of size of content audiences) makes it increasingly
-likely that the interface to the average Web-based dynamic content
-service will be localized for two or maybe three languages. It is my
-hope that Maketext will make that task as simple as possible, and will
-remove previous barriers to localization for languages dissimilar to
-English.
-
- __END__
-
-Sean M. Burke (sburkeE<64>cpan.org) has a Master's in linguistics
-from Northwestern University; he specializes in language technology.
-Jordan Lachler (lachlerE<64>unm.edu) is a PhD student in the Department of
-Linguistics at the University of New Mexico; he specializes in
-morphology and pedagogy of North American native languages.
-
-=head2 References
-
-Alvestrand, Harald Tveit. 1995. I<RFC 1766: Tags for the
-Identification of Languages.>
-C<http://www.ietf.org/rfc/rfc1766.txt>
-[Now see RFC 3066.]
-
-Callon, Ross, editor. 1996. I<RFC 1925: The Twelve
-Networking Truths.>
-C<http://www.ietf.org/rfc/rfc1925.txt>
-
-Drepper, Ulrich, Peter Miller,
-and FranE<ccedil>ois Pinard. 1995-2001. GNU
-C<gettext>. Available in C<ftp://prep.ai.mit.edu/pub/gnu/>, with
-extensive docs in the distribution tarball. [Since
-I wrote this article in 1998, I now see that the
-gettext docs are now trying more to come to terms with
-plurality. Whether useful conclusions have come from it
-is another question altogether. -- SMB, May 2001]
-
-Forbes, Nevill. 1964. I<Russian Grammar.> Third Edition, revised
-by J. C. Dumbreck. Oxford University Press.
-
-=cut
-
-#End
-
diff --git a/Master/tlpkg/tlperl/lib/Locale/Script.pod b/Master/tlpkg/tlperl/lib/Locale/Script.pod
deleted file mode 100644
index 0afb533601e..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Script.pod
+++ /dev/null
@@ -1,131 +0,0 @@
-=pod
-
-=head1 NAME
-
-Locale::Script - standard codes for script identification
-
-=head1 SYNOPSIS
-
- use Locale::Script;
-
- $script = code2script('phnx'); # 'Phoenician'
- $code = script2code('Phoenician'); # 'Phnx'
- $code = script2code('Phoenician',
- LOCALE_CODE_NUMERIC); # 115
-
- @codes = all_script_codes();
- @scripts = all_script_names();
-
-=head1 DESCRIPTION
-
-The C<Locale::Script> module provides access to standards codes used
-for identifying scripts, such as those defined in ISO 15924.
-
-Most of the routines take an optional additional argument which
-specifies the code set to use. If not specified, the default ISO
-15924 four-letter codes will be used.
-
-=head1 SUPPORTED CODE SETS
-
-There are several different code sets you can use for identifying
-scripts. A code set may be specified using either a name, or a
-constant that is automatically exported by this module.
-
-For example, the two are equivalent:
-
- $script = code2script('phnx','alpha');
- $script = code2script('phnx',LOCALE_SCRIPT_ALPHA);
-
-The codesets currently supported are:
-
-=over 4
-
-=item B<alpha, LOCALE_SCRIPT_ALPHA>
-
-This is a set of four-letter (capitalized) codes from ISO 15924
-such as 'Phnx' for Phoenician. It also includes additions to this
-set included in the IANA language registry.
-
-The Zxxx, Zyyy, and Zzzz codes are not used.
-
-This is the default code set.
-
-=item B<num, LOCALE_SCRIPT_NUMERIC>
-
-This is a set of three-digit numeric codes from ISO 15924 such as 115
-for Phoenician.
-
-=back
-
-=head1 ROUTINES
-
-=over 4
-
-=item B<code2script ( CODE [,CODESET] )>
-
-=item B<script2code ( NAME [,CODESET] )>
-
-=item B<script_code2code ( CODE ,CODESET ,CODESET2 )>
-
-=item B<all_script_codes ( [CODESET] )>
-
-=item B<all_script_names ( [CODESET] )>
-
-=item B<Locale::Script::rename_script ( CODE ,NEW_NAME [,CODESET] )>
-
-=item B<Locale::Script::add_script ( CODE ,NAME [,CODESET] )>
-
-=item B<Locale::Script::delete_script ( CODE [,CODESET] )>
-
-=item B<Locale::Script::add_script_alias ( NAME ,NEW_NAME )>
-
-=item B<Locale::Script::delete_script_alias ( NAME )>
-
-=item B<Locale::Script::rename_script_code ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Script::add_script_code_alias ( CODE ,NEW_CODE [,CODESET] )>
-
-=item B<Locale::Script::delete_script_code_alias ( CODE [,CODESET] )>
-
-These routines are all documented in the Locale::Codes::API man page.
-
-=back
-
-=head1 SEE ALSO
-
-=over 4
-
-=item B<Locale::Codes>
-
-The Locale-Codes distribution.
-
-=item B<Locale::Codes::API>
-
-The list of functions supported by this module.
-
-=item B<http://www.unicode.org/iso15924/>
-
-Home page for ISO 15924.
-
-=item B<http://www.iana.org/assignments/language-subtag-registry>
-
-The IANA language subtag registry.
-
-=back
-
-=head1 AUTHOR
-
-See Locale::Codes for full author history.
-
-Currently maintained by Sullivan Beck (sbeck@cpan.org).
-
-=head1 COPYRIGHT
-
- Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
- Copyright (c) 2001-2010 Neil Bowers
- Copyright (c) 2010-2012 Sullivan Beck
-
-This module is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Module/Build/API.pod b/Master/tlpkg/tlperl/lib/Module/Build/API.pod
deleted file mode 100644
index 29d2f359c8e..00000000000
--- a/Master/tlpkg/tlperl/lib/Module/Build/API.pod
+++ /dev/null
@@ -1,2058 +0,0 @@
-=head1 NAME
-
-Module::Build::API - API Reference for Module Authors
-
-=for :stopwords apache bsd distdir distsign gpl installdirs lgpl mit mozilla packlists
-
-=head1 DESCRIPTION
-
-I list here some of the most important methods in C<Module::Build>.
-Normally you won't need to deal with these methods unless you want to
-subclass C<Module::Build>. But since one of the reasons I created
-this module in the first place was so that subclassing is possible
-(and easy), I will certainly write more docs as the interface
-stabilizes.
-
-
-=head2 CONSTRUCTORS
-
-=over 4
-
-=item current()
-
-[version 0.20]
-
-This method returns a reasonable facsimile of the currently-executing
-C<Module::Build> object representing the current build. You can use
-this object to query its L</notes()> method, inquire about installed
-modules, and so on. This is a great way to share information between
-different parts of your build process. For instance, you can ask
-the user a question during C<perl Build.PL>, then use their answer
-during a regression test:
-
- # In Build.PL:
- my $color = $build->prompt("What is your favorite color?");
- $build->notes(color => $color);
-
- # In t/colortest.t:
- use Module::Build;
- my $build = Module::Build->current;
- my $color = $build->notes('color');
- ...
-
-The way the C<current()> method is currently implemented, there may be
-slight differences between the C<$build> object in Build.PL and the
-one in C<t/colortest.t>. It is our goal to minimize these differences
-in future releases of Module::Build, so please report any anomalies
-you find.
-
-One important caveat: in its current implementation, C<current()> will
-B<NOT> work correctly if you have changed out of the directory that
-C<Module::Build> was invoked from.
-
-=item new()
-
-[version 0.03]
-
-Creates a new Module::Build object. Arguments to the new() method are
-listed below. Most arguments are optional, but you must provide
-either the L</module_name> argument, or L</dist_name> and one of
-L</dist_version> or L</dist_version_from>. In other words, you must
-provide enough information to determine both a distribution name and
-version.
-
-
-=over 4
-
-=item add_to_cleanup
-
-[version 0.19]
-
-An array reference of files to be cleaned up when the C<clean> action
-is performed. See also the L<add_to_cleanup()|/"add_to_cleanup(@files)">
-method.
-
-=item auto_configure_requires
-
-[version 0.34]
-
-This parameter determines whether Module::Build will add itself
-automatically to configure_requires (and build_requires) if Module::Build
-is not already there. The required version will be the last 'major' release,
-as defined by the decimal version truncated to two decimal places (e.g. 0.34,
-instead of 0.3402). The default value is true.
-
-=item auto_features
-
-[version 0.26]
-
-This parameter supports the setting of features (see
-L</feature($name)>) automatically based on a set of prerequisites. For
-instance, for a module that could optionally use either MySQL or
-PostgreSQL databases, you might use C<auto_features> like this:
-
- my $build = Module::Build->new
- (
- ...other stuff here...
- auto_features => {
- pg_support => {
- description => "Interface with Postgres databases",
- requires => { 'DBD::Pg' => 23.3,
- 'DateTime::Format::Pg' => 0 },
- },
- mysql_support => {
- description => "Interface with MySQL databases",
- requires => { 'DBD::mysql' => 17.9,
- 'DateTime::Format::MySQL' => 0 },
- },
- }
- );
-
-For each feature named, the required prerequisites will be checked, and
-if there are no failures, the feature will be enabled (set to C<1>).
-Otherwise the failures will be displayed to the user and the feature
-will be disabled (set to C<0>).
-
-See the documentation for L</requires> for the details of how
-requirements can be specified.
-
-=item autosplit
-
-[version 0.04]
-
-An optional C<autosplit> argument specifies a file which should be run
-through the L<AutoSplit::autosplit()|AutoSplit/autosplit> function.
-If multiple files should be split, the argument may be given as an
-array of the files to split.
-
-In general I don't consider autosplitting a great idea, because it's
-not always clear that autosplitting achieves its intended performance
-benefits. It may even harm performance in environments like mod_perl,
-where as much as possible of a module's code should be loaded during
-startup.
-
-=item build_class
-
-[version 0.28]
-
-The Module::Build class or subclass to use in the build script.
-Defaults to "Module::Build" or the class name passed to or created by
-a call to L</subclass()>. This property is useful if you're
-writing a custom Module::Build subclass and have a bootstrapping
-problem--that is, your subclass requires modules that may not be
-installed when C<perl Build.PL> is executed, but you've listed in
-L</build_requires> so that they should be available when C<./Build> is
-executed.
-
-=item build_requires
-
-[version 0.07]
-
-Modules listed in this section are necessary to build and install the
-given module, but are not necessary for regular usage of it. This is
-actually an important distinction - it allows for tighter control over
-the body of installed modules, and facilitates correct dependency
-checking on binary/packaged distributions of the module.
-
-See the documentation for L<Module::Build::Authoring/"PREREQUISITES">
-for the details of how requirements can be specified.
-
-=item create_packlist
-
-[version 0.28]
-
-If true, this parameter tells Module::Build to create a F<.packlist>
-file during the C<install> action, just like C<ExtUtils::MakeMaker> does.
-The file is created in a subdirectory of the C<arch> installation
-location. It is used by some other tools (CPAN, CPANPLUS, etc.) for
-determining what files are part of an install.
-
-The default value is true. This parameter was introduced in
-Module::Build version 0.2609; previously no packlists were ever
-created by Module::Build.
-
-=item c_source
-
-[version 0.04]
-
-An optional C<c_source> argument specifies a directory which contains
-C source files that the rest of the build may depend on. Any C<.c>
-files in the directory will be compiled to object files. The
-directory will be added to the search path during the compilation and
-linking phases of any C or XS files.
-
-[version 0.3604]
-
-A list of directories can be supplied using an anonymous array
-reference of strings.
-
-=item conflicts
-
-[version 0.07]
-
-Modules listed in this section conflict in some serious way with the
-given module. C<Module::Build> (or some higher-level tool) will
-refuse to install the given module if the given module/version is also
-installed.
-
-See the documentation for L<Module::Build::Authoring/"PREREQUISITES">
-for the details of how requirements can be specified.
-
-=item create_license
-
-[version 0.31]
-
-This parameter tells Module::Build to automatically create a
-F<LICENSE> file at the top level of your distribution, containing the
-full text of the author's chosen license. This requires
-C<Software::License> on the author's machine, and further requires
-that the C<license> parameter specifies a license that it knows about.
-
-=item create_makefile_pl
-
-[version 0.19]
-
-This parameter lets you use C<Module::Build::Compat> during the
-C<distdir> (or C<dist>) action to automatically create a Makefile.PL
-for compatibility with C<ExtUtils::MakeMaker>. The parameter's value
-should be one of the styles named in the L<Module::Build::Compat>
-documentation.
-
-=item create_readme
-
-[version 0.22]
-
-This parameter tells Module::Build to automatically create a F<README>
-file at the top level of your distribution. Currently it will simply
-use C<Pod::Text> (or C<Pod::Readme> if it's installed) on the file
-indicated by C<dist_version_from> and put the result in the F<README>
-file. This is by no means the only recommended style for writing a
-F<README>, but it seems to be one common one used on the CPAN.
-
-If you generate a F<README> in this way, it's probably a good idea to
-create a separate F<INSTALL> file if that information isn't in the
-generated F<README>.
-
-=item dist_abstract
-
-[version 0.20]
-
-This should be a short description of the distribution. This is used when
-generating metadata for F<META.yml> and PPD files. If it is not given
-then C<Module::Build> looks in the POD of the module from which it gets
-the distribution's version. If it finds a POD section marked "=head1
-NAME", then it looks for the first line matching C<\s+-\s+(.+)>,
-and uses the captured text as the abstract.
-
-=item dist_author
-
-[version 0.20]
-
-This should be something like "John Doe <jdoe@example.com>", or if
-there are multiple authors, an anonymous array of strings may be
-specified. This is used when generating metadata for F<META.yml> and
-PPD files. If this is not specified, then C<Module::Build> looks at
-the module from which it gets the distribution's version. If it finds
-a POD section marked "=head1 AUTHOR", then it uses the contents of
-this section.
-
-=item dist_name
-
-[version 0.11]
-
-Specifies the name for this distribution. Most authors won't need to
-set this directly, they can use C<module_name> to set C<dist_name> to
-a reasonable default. However, some agglomerative distributions like
-C<libwww-perl> or C<bioperl> have names that don't correspond directly
-to a module name, so C<dist_name> can be set independently.
-
-=item dist_suffix
-
-[version 0.37]
-
-Specifies an optional suffix to include after the version number
-in the distribution directory (and tarball) name. The only suffix
-currently recognized by PAUSE is 'TRIAL', which indicates that the
-distribution should not be indexed. For example:
-
- Foo-Bar-1.23-TRIAL.tar.gz
-
-This will automatically do the "right thing" depending on C<dist_version> and
-C<release_status>. When C<dist_version> does not have an underscore and
-C<release_status> is not 'stable', then C<dist_suffix> will default to 'TRIAL'.
-Otherwise it will default to the empty string, disabling the suffix.
-
-In general, authors should only set this if they B<must> override the default
-behavior for some particular purpose.
-
-=item dist_version
-
-[version 0.11]
-
-Specifies a version number for the distribution. See L</module_name>
-or L</dist_version_from> for ways to have this set automatically from a
-C<$VERSION> variable in a module. One way or another, a version
-number needs to be set.
-
-=item dist_version_from
-
-[version 0.11]
-
-Specifies a file to look for the distribution version in. Most
-authors won't need to set this directly, they can use L</module_name>
-to set it to a reasonable default.
-
-The version is extracted from the specified file according to the same
-rules as L<ExtUtils::MakeMaker> and C<CPAN.pm>. It involves finding
-the first line that matches the regular expression
-
- /([\$*])(([\w\:\']*)\bVERSION)\b.*\=/
-
-eval()-ing that line, then checking the value of the C<$VERSION>
-variable. Quite ugly, really, but all the modules on CPAN depend on
-this process, so there's no real opportunity to change to something
-better.
-
-If the target file of L</dist_version_from> contains more than one package
-declaration, the version returned will be the one matching the configured
-L</module_name>.
-
-=item dynamic_config
-
-[version 0.07]
-
-A boolean flag indicating whether the F<Build.PL> file must be
-executed, or whether this module can be built, tested and installed
-solely from consulting its metadata file. The main reason to set this
-to a true value is that your module performs some dynamic
-configuration as part of its build/install process. If the flag is
-omitted, the F<META.yml> spec says that installation tools should
-treat it as 1 (true), because this is a safer way to behave.
-
-Currently C<Module::Build> doesn't actually do anything with this flag
-- it's up to higher-level tools like C<CPAN.pm> to do something useful
-with it. It can potentially bring lots of security, packaging, and
-convenience improvements.
-
-=item extra_compiler_flags
-
-=item extra_linker_flags
-
-[version 0.19]
-
-These parameters can contain array references (or strings, in which
-case they will be split into arrays) to pass through to the compiler
-and linker phases when compiling/linking C code. For example, to tell
-the compiler that your code is C++, you might do:
-
- my $build = Module::Build->new
- (
- module_name => 'Foo::Bar',
- extra_compiler_flags => ['-x', 'c++'],
- );
-
-To link your XS code against glib you might write something like:
-
- my $build = Module::Build->new
- (
- module_name => 'Foo::Bar',
- dynamic_config => 1,
- extra_compiler_flags => scalar `glib-config --cflags`,
- extra_linker_flags => scalar `glib-config --libs`,
- );
-
-=item get_options
-
-[version 0.26]
-
-You can pass arbitrary command line options to F<Build.PL> or
-F<Build>, and they will be stored in the Module::Build object and can
-be accessed via the L</args()> method. However, sometimes you want
-more flexibility out of your argument processing than this allows. In
-such cases, use the C<get_options> parameter to pass in a hash
-reference of argument specifications, and the list of arguments to
-F<Build.PL> or F<Build> will be processed according to those
-specifications before they're passed on to C<Module::Build>'s own
-argument processing.
-
-The supported option specification hash keys are:
-
-
-=over 4
-
-=item type
-
-The type of option. The types are those supported by Getopt::Long; consult
-its documentation for a complete list. Typical types are C<=s> for strings,
-C<+> for additive options, and C<!> for negatable options. If the
-type is not specified, it will be considered a boolean, i.e. no
-argument is taken and a value of 1 will be assigned when the option is
-encountered.
-
-=item store
-
-A reference to a scalar in which to store the value passed to the option.
-If not specified, the value will be stored under the option name in the
-hash returned by the C<args()> method.
-
-=item default
-
-A default value for the option. If no default value is specified and no option
-is passed, then the option key will not exist in the hash returned by
-C<args()>.
-
-=back
-
-
-You can combine references to your own variables or subroutines with
-unreferenced specifications, for which the result will also be stored in the
-hash returned by C<args()>. For example:
-
- my $loud = 0;
- my $build = Module::Build->new
- (
- module_name => 'Foo::Bar',
- get_options => {
- Loud => { store => \$loud },
- Dbd => { type => '=s' },
- Quantity => { type => '+' },
- }
- );
-
- print STDERR "HEY, ARE YOU LISTENING??\n" if $loud;
- print "We'll use the ", $build->args('Dbd'), " DBI driver\n";
- print "Are you sure you want that many?\n"
- if $build->args('Quantity') > 2;
-
-The arguments for such a specification can be called like so:
-
- perl Build.PL --Loud --Dbd=DBD::pg --Quantity --Quantity --Quantity
-
-B<WARNING:> Any option specifications that conflict with Module::Build's own
-options (defined by its properties) will throw an exception. Use capitalized
-option names to avoid unintended conflicts with future Module::Build options.
-
-Consult the Getopt::Long documentation for details on its usage.
-
-=item include_dirs
-
-[version 0.24]
-
-Specifies any additional directories in which to search for C header
-files. May be given as a string indicating a single directory, or as
-a list reference indicating multiple directories.
-
-=item install_path
-
-[version 0.19]
-
-You can set paths for individual installable elements by using the
-C<install_path> parameter:
-
- my $build = Module::Build->new
- (
- ...other stuff here...
- install_path => {
- lib => '/foo/lib',
- arch => '/foo/lib/arch',
- }
- );
-
-=item installdirs
-
-[version 0.19]
-
-Determines where files are installed within the normal perl hierarchy
-as determined by F<Config.pm>. Valid values are: C<core>, C<site>,
-C<vendor>. The default is C<site>. See
-L<Module::Build/"INSTALL PATHS">
-
-=item license
-
-[version 0.07]
-
-Specifies the licensing terms of your distribution.
-
-As of Module::Build version 0.36_14, you may use a L<Software::License>
-subclass name (e.g. 'Apache_2_0') instead of one of the keys below.
-
-The legacy list of valid license values include:
-
-=over 4
-
-=item apache
-
-The distribution is licensed under the Apache License, Version 2.0
-(L<http://apache.org/licenses/LICENSE-2.0>).
-
-=item apache_1_1
-
-The distribution is licensed under the Apache Software License, Version 1.1
-(L<http://apache.org/licenses/LICENSE-1.1>).
-
-=item artistic
-
-The distribution is licensed under the Artistic License, as specified
-by the F<Artistic> file in the standard Perl distribution.
-
-=item artistic_2
-
-The distribution is licensed under the Artistic 2.0 License
-(L<http://opensource.org/licenses/artistic-license-2.0.php>.)
-
-=item bsd
-
-The distribution is licensed under the BSD License
-(L<http://www.opensource.org/licenses/bsd-license.php>).
-
-=item gpl
-
-The distribution is licensed under the terms of the GNU General
-Public License (L<http://www.opensource.org/licenses/gpl-license.php>).
-
-=item lgpl
-
-The distribution is licensed under the terms of the GNU Lesser
-General Public License
-(L<http://www.opensource.org/licenses/lgpl-license.php>).
-
-=item mit
-
-The distribution is licensed under the MIT License
-(L<http://opensource.org/licenses/mit-license.php>).
-
-=item mozilla
-
-The distribution is licensed under the Mozilla Public
-License. (L<http://opensource.org/licenses/mozilla1.0.php> or
-L<http://opensource.org/licenses/mozilla1.1.php>)
-
-=item open_source
-
-The distribution is licensed under some other Open Source
-Initiative-approved license listed at
-L<http://www.opensource.org/licenses/>.
-
-=item perl
-
-The distribution may be copied and redistributed under the same terms
-as Perl itself (this is by far the most common licensing option for
-modules on CPAN). This is a dual license, in which the user may
-choose between either the GPL or the Artistic license.
-
-=item restrictive
-
-The distribution may not be redistributed without special permission
-from the author and/or copyright holder.
-
-=item unrestricted
-
-The distribution is licensed under a license that is B<not> approved
-by www.opensource.org but that allows distribution without
-restrictions.
-
-=back
-
-Note that you must still include the terms of your license in your
-code and documentation - this field only sets the information that is included
-in distribution metadata to let automated tools figure out your
-licensing restrictions. Humans still need something to read. If you
-choose to provide this field, you should make sure that you keep it in
-sync with your written documentation if you ever change your licensing
-terms.
-
-You may also use a license type of C<unknown> if you don't wish to
-specify your terms in the metadata.
-
-Also see the C<create_license> parameter.
-
-=item meta_add
-
-[version 0.28]
-
-A hash of key/value pairs that should be added to the F<META.yml> file
-during the C<distmeta> action. Any existing entries with the same
-names will be overridden.
-
-See the L</"MODULE METADATA"> section for details.
-
-=item meta_merge
-
-[version 0.28]
-
-A hash of key/value pairs that should be merged into the F<META.yml>
-file during the C<distmeta> action. Any existing entries with the
-same names will be overridden.
-
-The only difference between C<meta_add> and C<meta_merge> is their
-behavior on hash-valued and array-valued entries: C<meta_add> will
-completely blow away the existing hash or array value, but
-C<meta_merge> will merge the supplied data into the existing hash or
-array value.
-
-See the L</"MODULE METADATA"> section for details.
-
-=item module_name
-
-[version 0.03]
-
-The C<module_name> is a shortcut for setting default values of
-C<dist_name> and C<dist_version_from>, reflecting the fact that the
-majority of CPAN distributions are centered around one "main" module.
-For instance, if you set C<module_name> to C<Foo::Bar>, then
-C<dist_name> will default to C<Foo-Bar> and C<dist_version_from> will
-default to C<lib/Foo/Bar.pm>. C<dist_version_from> will in turn be
-used to set C<dist_version>.
-
-Setting C<module_name> won't override a C<dist_*> parameter you
-specify explicitly.
-
-=item needs_compiler
-
-[version 0.36]
-
-The C<needs_compiler> parameter indicates whether a compiler is required to
-build the distsribution. The default is false, unless XS files are found or
-the C<c_source> parameter is set, in which case it is true. If true,
-L<ExtUtils::CBuilder> is automatically added to C<build_requires> if needed.
-
-For a distribution where a compiler is I<optional>, e.g. a dual XS/pure-Perl
-distribution, C<needs_compiler> should explicitly be set to a false value.
-
-=item PL_files
-
-[version 0.06]
-
-An optional parameter specifying a set of C<.PL> files in your
-distribution. These will be run as Perl scripts prior to processing
-the rest of the files in your distribution with the name of the file
-they're generating as an argument. They are usually used as templates
-for creating other files dynamically, so that a file like
-C<lib/Foo/Bar.pm.PL> might create the file C<lib/Foo/Bar.pm>.
-
-The files are specified with the C<.PL> files as hash keys, and the
-file(s) they generate as hash values, like so:
-
- my $build = Module::Build->new
- (
- module_name => 'Foo::Bar',
- ...
- PL_files => { 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm' },
- );
-
-Note that the path specifications are I<always> given in Unix-like
-format, not in the style of the local system.
-
-If your C<.PL> scripts don't create any files, or if they create files
-with unexpected names, or even if they create multiple files, you can
-indicate that so that Module::Build can properly handle these created
-files:
-
- PL_files => {
- 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm',
- 'lib/something.PL' => ['/lib/something', '/lib/else'],
- 'lib/funny.PL' => [],
- }
-
-Here's an example of a simple PL file.
-
- my $output_file = shift;
- open my $fh, ">", $output_file or die "Can't open $output_file: $!";
-
- print $fh <<'END';
- #!/usr/bin/perl
-
- print "Hello, world!\n";
- END
-
-PL files are not installed by default, so its safe to put them in
-F<lib/> and F<bin/>.
-
-
-=item pm_files
-
-[version 0.19]
-
-An optional parameter specifying the set of C<.pm> files in this
-distribution, specified as a hash reference whose keys are the files'
-locations in the distributions, and whose values are their logical
-locations based on their package name, i.e. where they would be found
-in a "normal" Module::Build-style distribution. This parameter is
-mainly intended to support alternative layouts of files.
-
-For instance, if you have an old-style C<MakeMaker> distribution for a
-module called C<Foo::Bar> and a F<Bar.pm> file at the top level of the
-distribution, you could specify your layout in your C<Build.PL> like
-this:
-
- my $build = Module::Build->new
- (
- module_name => 'Foo::Bar',
- ...
- pm_files => { 'Bar.pm' => 'lib/Foo/Bar.pm' },
- );
-
-Note that the values should include C<lib/>, because this is where
-they would be found in a "normal" Module::Build-style distribution.
-
-Note also that the path specifications are I<always> given in
-Unix-like format, not in the style of the local system.
-
-=item pod_files
-
-[version 0.19]
-
-Just like C<pm_files>, but used for specifying the set of C<.pod>
-files in your distribution.
-
-=item recommends
-
-[version 0.08]
-
-This is just like the L</requires> argument, except that modules listed
-in this section aren't essential, just a good idea. We'll just print
-a friendly warning if one of these modules aren't found, but we'll
-continue running.
-
-If a module is recommended but not required, all tests should still
-pass if the module isn't installed. This may mean that some tests
-may be skipped if recommended dependencies aren't present.
-
-Automated tools like CPAN.pm should inform the user when recommended
-modules aren't installed, and it should offer to install them if it
-wants to be helpful.
-
-See the documentation for L<Module::Build::Authoring/"PREREQUISITES">
-for the details of how requirements can be specified.
-
-=item recursive_test_files
-
-[version 0.28]
-
-Normally, C<Module::Build> does not search subdirectories when looking
-for tests to run. When this options is set it will search recursively
-in all subdirectories of the standard 't' test directory.
-
-=item release_status
-
-[version 0.37]
-
-The CPAN Meta Spec version 2 adds C<release_status> to allow authors
-to specify how a distribution should be indexed. Consistent with the
-spec, this parameter can only have one three values: 'stable',
-'testing' or 'unstable'.
-
-Unless explicitly set by the author, C<release_status> will default
-to 'stable' unless C<dist_version> contains an underscore, in which
-case it will default to 'testing'.
-
-It is an error to specify a C<release_status> of 'stable' when
-C<dist_version> contains an underscore character.
-
-=item requires
-
-[version 0.07]
-
-An optional C<requires> argument specifies any module prerequisites
-that the current module depends on.
-
-One note: currently C<Module::Build> doesn't actually I<require> the
-user to have dependencies installed, it just strongly urges. In the
-future we may require it. There's also a L</recommends> section for
-things that aren't absolutely required.
-
-Automated tools like CPAN.pm should refuse to install a module if one
-of its dependencies isn't satisfied, unless a "force" command is given
-by the user. If the tools are helpful, they should also offer to
-install the dependencies.
-
-A synonym for C<requires> is C<prereq>, to help succour people
-transitioning from C<ExtUtils::MakeMaker>. The C<requires> term is
-preferred, but the C<prereq> term will remain valid in future
-distributions.
-
-See the documentation for L<Module::Build::Authoring/"PREREQUISITES">
-for the details of how requirements can be specified.
-
-=item script_files
-
-[version 0.18]
-
-An optional parameter specifying a set of files that should be
-installed as executable Perl scripts when the module is installed.
-May be given as an array reference of the files, as a hash reference
-whose keys are the files (and whose values will currently be ignored),
-as a string giving the name of a directory in which to find scripts,
-or as a string giving the name of a single script file.
-
-The default is to install any scripts found in a F<bin> directory at
-the top level of the distribution, minus any keys of L<PL_files>.
-
-For backward compatibility, you may use the parameter C<scripts>
-instead of C<script_files>. Please consider this usage deprecated,
-though it will continue to exist for several version releases.
-
-=item share_dir
-
-[version 0.36]
-
-An optional parameter specifying directories of static data files to
-be installed as read-only files for use with L<File::ShareDir>. The
-C<share_dir> property supports both distribution-level and
-module-level share files.
-
-The simplest use of C<share_dir> is to set it to a directory name or an
-arrayref of directory names containing files to be installed in the
-distribution-level share directory.
-
- share_dir => 'share'
-
-Alternatively, if C<share_dir> is a hashref, it may have C<dist> or
-C<module> keys providing full flexibility in defining how share
-directories should be installed.
-
- share_dir => {
- dist => [ 'examples', 'more_examples' ],
- module => {
- Foo::Templates => ['share/html', 'share/text'],
- Foo::Config => 'share/config',
- }
- }
-
-If C<share_dir> is set, then File::ShareDir will automatically be added
-to the C<requires> hash.
-
-=item sign
-
-[version 0.16]
-
-If a true value is specified for this parameter, L<Module::Signature>
-will be used (via the 'distsign' action) to create a SIGNATURE file
-for your distribution during the 'distdir' action, and to add the
-SIGNATURE file to the MANIFEST (therefore, don't add it yourself).
-
-The default value is false. In the future, the default may change to
-true if you have C<Module::Signature> installed on your system.
-
-=item test_files
-
-[version 0.23]
-
-An optional parameter specifying a set of files that should be used as
-C<Test::Harness>-style regression tests to be run during the C<test>
-action. May be given as an array reference of the files, or as a hash
-reference whose keys are the files (and whose values will currently be
-ignored). If the argument is given as a single string (not in an
-array reference), that string will be treated as a C<glob()> pattern
-specifying the files to use.
-
-The default is to look for a F<test.pl> script in the top-level
-directory of the distribution, and any files matching the glob pattern
-C<*.t> in the F<t/> subdirectory. If the C<recursive_test_files>
-property is true, then the C<t/> directory will be scanned recursively
-for C<*.t> files.
-
-=item use_tap_harness
-
-[version 0.2808_03]
-
-An optional parameter indicating whether or not to use TAP::Harness for
-testing rather than Test::Harness. Defaults to false. If set to true, you must
-therefore be sure to add TAP::Harness as a requirement for your module in
-L</build_requires>. Implicitly set to a true value if C<tap_harness_args> is
-specified.
-
-=item tap_harness_args
-
-[version 0.2808_03]
-
-An optional parameter specifying parameters to be passed to TAP::Harness when
-running tests. Must be given as a hash reference of parameters; see the
-L<TAP::Harness|TAP::Harness> documentation for details. Note that specifying
-this parameter will implicitly set C<use_tap_harness> to a true value. You
-must therefore be sure to add TAP::Harness as a requirement for your module in
-L</build_requires>.
-
-=item xs_files
-
-[version 0.19]
-
-Just like C<pm_files>, but used for specifying the set of C<.xs>
-files in your distribution.
-
-=back
-
-
-=item new_from_context(%args)
-
-[version 0.28]
-
-When called from a directory containing a F<Build.PL> script (in other words,
-the base directory of a distribution), this method will run the F<Build.PL> and
-call C<resume()> to return the resulting C<Module::Build> object to the caller.
-Any key-value arguments given to C<new_from_context()> are essentially like
-command line arguments given to the F<Build.PL> script, so for example you
-could pass C<< verbose => 1 >> to this method to turn on verbosity.
-
-=item resume()
-
-[version 0.03]
-
-You'll probably never call this method directly, it's only called from the
-auto-generated C<Build> script (and the C<new_from_context> method). The
-C<new()> method is only called once, when the user runs C<perl Build.PL>.
-Thereafter, when the user runs C<Build test> or another action, the
-C<Module::Build> object is created using the C<resume()> method to
-re-instantiate with the settings given earlier to C<new()>.
-
-=item subclass()
-
-[version 0.06]
-
-This creates a new C<Module::Build> subclass on the fly, as described
-in the L<Module::Build::Authoring/"SUBCLASSING"> section. The caller
-must provide either a C<class> or C<code> parameter, or both. The
-C<class> parameter indicates the name to use for the new subclass, and
-defaults to C<MyModuleBuilder>. The C<code> parameter specifies Perl
-code to use as the body of the subclass.
-
-=item add_property
-
-[version 0.31]
-
- package 'My::Build';
- use base 'Module::Build';
- __PACKAGE__->add_property( 'pedantic' );
- __PACKAGE__->add_property( answer => 42 );
- __PACKAGE__->add_property(
- 'epoch',
- default => sub { time },
- check => sub {
- return 1 if /^\d+$/;
- shift->property_error( "'$_' is not an epoch time" );
- return 0;
- },
- );
-
-Adds a property to a Module::Build class. Properties are those attributes of a
-Module::Build object which can be passed to the constructor and which have
-accessors to get and set them. All of the core properties, such as
-C<module_name> and C<license>, are defined using this class method.
-
-The first argument to C<add_property()> is always the name of the property.
-The second argument can be either a default value for the property, or a list
-of key/value pairs. The supported keys are:
-
-=over
-
-=item C<default>
-
-The default value. May optionally be specified as a code reference, in which
-case the return value from the execution of the code reference will be used.
-If you need the default to be a code reference, just use a code reference to
-return it, e.g.:
-
- default => sub { sub { ... } },
-
-=item C<check>
-
-A code reference that checks that a value specified for the property is valid.
-During the execution of the code reference, the new value will be included in
-the C<$_> variable. If the value is correct, the C<check> code reference
-should return true. If the value is not correct, it sends an error message to
-C<property_error()> and returns false.
-
-=back
-
-When this method is called, a new property will be installed in the
-Module::Build class, and an accessor will be built to allow the property to be
-get or set on the build object.
-
- print $build->pedantic, $/;
- $build->pedantic(0);
-
-If the default value is a hash reference, this generates a special-case
-accessor method, wherein individual key/value pairs may be set or fetched:
-
- print "stuff{foo} is: ", $build->stuff( 'foo' ), $/;
- $build->stuff( foo => 'bar' );
- print $build->stuff( 'foo' ), $/; # Outputs "bar"
-
-Of course, you can still set the entire hash reference at once, as well:
-
- $build->stuff( { foo => 'bar', baz => 'yo' } );
-
-In either case, if a C<check> has been specified for the property, it will be
-applied to the entire hash. So the check code reference should look something
-like:
-
- check => sub {
- return 1 if defined $_ && exists $_->{foo};
- shift->property_error(qq{Property "stuff" needs "foo"});
- return 0;
- },
-
-=item property_error
-
-[version 0.31]
-
-=back
-
-
-=head2 METHODS
-
-=over 4
-
-=item add_build_element($type)
-
-[version 0.26]
-
-Adds a new type of entry to the build process. Accepts a single
-string specifying its type-name. There must also be a method defined
-to process things of that type, e.g. if you add a build element called
-C<'foo'>, then you must also define a method called
-C<process_foo_files()>.
-
-See also
-L<Module::Build::Cookbook/"Adding new file types to the build process">.
-
-=item add_to_cleanup(@files)
-
-[version 0.03]
-
-You may call C<< $self->add_to_cleanup(@patterns) >> to tell
-C<Module::Build> that certain files should be removed when the user
-performs the C<Build clean> action. The arguments to the method are
-patterns suitable for passing to Perl's C<glob()> function, specified
-in either Unix format or the current machine's native format. It's
-usually convenient to use Unix format when you hard-code the filenames
-(e.g. in F<Build.PL>) and the native format when the names are
-programmatically generated (e.g. in a testing script).
-
-I decided to provide a dynamic method of the C<$build> object, rather
-than just use a static list of files named in the F<Build.PL>, because
-these static lists can get difficult to manage. I usually prefer to
-keep the responsibility for registering temporary files close to the
-code that creates them.
-
-=item args()
-
-[version 0.26]
-
- my $args_href = $build->args;
- my %args = $build->args;
- my $arg_value = $build->args($key);
- $build->args($key, $value);
-
-This method is the preferred interface for retrieving the arguments passed via
-command line options to F<Build.PL> or F<Build>, minus the Module-Build
-specific options.
-
-When called in in a scalar context with no arguments, this method returns a
-reference to the hash storing all of the arguments; in an array context, it
-returns the hash itself. When passed a single argument, it returns the value
-stored in the args hash for that option key. When called with two arguments,
-the second argument is assigned to the args hash under the key passed as the
-first argument.
-
-=item autosplit_file($from, $to)
-
-[version 0.28]
-
-Invokes the L<AutoSplit> module on the C<$from> file, sending the
-output to the C<lib/auto> directory inside C<$to>. C<$to> is
-typically the C<blib/> directory.
-
-=item base_dir()
-
-[version 0.14]
-
-Returns a string containing the root-level directory of this build,
-i.e. where the C<Build.PL> script and the C<lib> directory can be
-found. This is usually the same as the current working directory,
-because the C<Build> script will C<chdir()> into this directory as
-soon as it begins execution.
-
-=item build_requires()
-
-[version 0.21]
-
-Returns a hash reference indicating the C<build_requires>
-prerequisites that were passed to the C<new()> method.
-
-=item can_action( $action )
-
-Returns a reference to the method that defines C<$action>, or false
-otherwise. This is handy for actions defined (or maybe not!) in subclasses.
-
-[version 0.32_xx]
-
-=item cbuilder()
-
-[version 0.2809]
-
-Returns the internal ExtUtils::CBuilder object that can be used for
-compiling & linking C code. If no such object is available (e.g. if
-the system has no compiler installed) an exception will be thrown.
-
-=item check_installed_status($module, $version)
-
-[version 0.11]
-
-This method returns a hash reference indicating whether a version
-dependency on a certain module is satisfied. The C<$module> argument
-is given as a string like C<"Data::Dumper"> or C<"perl">, and the
-C<$version> argument can take any of the forms described in L</requires>
-above. This allows very fine-grained version checking.
-
-The returned hash reference has the following structure:
-
- {
- ok => $whether_the_dependency_is_satisfied,
- have => $version_already_installed,
- need => $version_requested, # Same as incoming $version argument
- message => $informative_error_message,
- }
-
-If no version of C<$module> is currently installed, the C<have> value
-will be the string C<< "<none>" >>. Otherwise the C<have> value will
-simply be the version of the installed module. Note that this means
-that if C<$module> is installed but doesn't define a version number,
-the C<have> value will be C<undef> - this is why we don't use C<undef>
-for the case when C<$module> isn't installed at all.
-
-This method may be called either as an object method
-(C<< $build->check_installed_status($module, $version) >>)
-or as a class method
-(C<< Module::Build->check_installed_status($module, $version) >>).
-
-=item check_installed_version($module, $version)
-
-[version 0.05]
-
-Like L<check_installed_status()|/"check_installed_status($module, $version)">,
-but simply returns true or false depending on whether module
-C<$module> satisfies the dependency C<$version>.
-
-If the check succeeds, the return value is the actual version of
-C<$module> installed on the system. This allows you to do the
-following:
-
- my $installed = $build->check_installed_version('DBI', '1.15');
- if ($installed) {
- print "Congratulations, version $installed of DBI is installed.\n";
- } else {
- die "Sorry, you must install DBI.\n";
- }
-
-If the check fails, we return false and set C<$@> to an informative
-error message.
-
-If C<$version> is any non-true value (notably zero) and any version of
-C<$module> is installed, we return true. In this case, if C<$module>
-doesn't define a version, or if its version is zero, we return the
-special value "0 but true", which is numerically zero, but logically
-true.
-
-In general you might prefer to use C<check_installed_status> if you
-need detailed information, or this method if you just need a yes/no
-answer.
-
-=item compare_versions($v1, $op, $v2)
-
-[version 0.28]
-
-Compares two module versions C<$v1> and C<$v2> using the operator
-C<$op>, which should be one of Perl's numeric operators like C<!=> or
-C<< >= >> or the like. We do at least a halfway-decent job of
-handling versions that aren't strictly numeric, like C<0.27_02>, but
-exotic stuff will likely cause problems.
-
-In the future, the guts of this method might be replaced with a call
-out to C<version.pm>.
-
-=item config($key)
-
-=item config($key, $value)
-
-=item config() [deprecated]
-
-[version 0.22]
-
-With a single argument C<$key>, returns the value associated with that
-key in the C<Config.pm> hash, including any changes the author or user
-has specified.
-
-With C<$key> and C<$value> arguments, sets the value for future
-callers of C<config($key)>.
-
-With no arguments, returns a hash reference containing all such
-key-value pairs. This usage is deprecated, though, because it's a
-resource hog and violates encapsulation.
-
-=item config_data($name)
-
-=item config_data($name => $value)
-
-[version 0.26]
-
-With a single argument, returns the value of the configuration
-variable C<$name>. With two arguments, sets the given configuration
-variable to the given value. The value may be any Perl scalar that's
-serializable with C<Data::Dumper>. For instance, if you write a
-module that can use a MySQL or PostgreSQL back-end, you might create
-configuration variables called C<mysql_connect> and
-C<postgres_connect>, and set each to an array of connection parameters
-for C<< DBI->connect() >>.
-
-Configuration values set in this way using the Module::Build object
-will be available for querying during the build/test process and after
-installation via the generated C<...::ConfigData> module, as
-C<< ...::ConfigData->config($name) >>.
-
-The L<feature()|/"feature($name)"> and C<config_data()> methods represent
-Module::Build's main support for configuration of installed modules.
-See also L<Module::Build::Authoring/"SAVING CONFIGURATION INFORMATION">.
-
-=item conflicts()
-
-[version 0.21]
-
-Returns a hash reference indicating the C<conflicts> prerequisites
-that were passed to the C<new()> method.
-
-=item contains_pod($file) [deprecated]
-
-[version 0.20]
-
-[Deprecated] Please see L<Module::Build::ModuleInfo> instead.
-
-Returns true if the given file appears to contain POD documentation.
-Currently this checks whether the file has a line beginning with
-'=pod', '=head', or '=item', but the exact semantics may change in the
-future.
-
-=item copy_if_modified(%parameters)
-
-[version 0.19]
-
-Takes the file in the C<from> parameter and copies it to the file in
-the C<to> parameter, or the directory in the C<to_dir> parameter, if
-the file has changed since it was last copied (or if it doesn't exist
-in the new location). By default the entire directory structure of
-C<from> will be copied into C<to_dir>; an optional C<flatten>
-parameter will copy into C<to_dir> without doing so.
-
-Returns the path to the destination file, or C<undef> if nothing
-needed to be copied.
-
-Any directories that need to be created in order to perform the
-copying will be automatically created.
-
-The destination file is set to read-only. If the source file has the
-executable bit set, then the destination file will be made executable.
-
-=item create_build_script()
-
-[version 0.05]
-
-Creates an executable script called C<Build> in the current directory
-that will be used to execute further user actions. This script is
-roughly analogous (in function, not in form) to the Makefile created
-by C<ExtUtils::MakeMaker>. This method also creates some temporary
-data in a directory called C<_build/>. Both of these will be removed
-when the C<realclean> action is performed.
-
-Among the files created in C<_build/> is a F<_build/prereqs> file
-containing the set of prerequisites for this distribution, as a hash
-of hashes. This file may be C<eval()>-ed to obtain the authoritative
-set of prerequisites, which might be different from the contents of
-F<META.yml> (because F<Build.PL> might have set them dynamically).
-But fancy developers take heed: do not put any fancy custom runtime
-code in the F<_build/prereqs> file, leave it as a static declaration
-containing only strings and numbers. Similarly, do not alter the
-structure of the internal C<< $self->{properties}{requires} >> (etc.)
-data members, because that's where this data comes from.
-
-=item current_action()
-
-[version 0.28]
-
-Returns the name of the currently-running action, such as "build" or
-"test". This action is not necessarily the action that was originally
-invoked by the user. For example, if the user invoked the "test"
-action, current_action() would initially return "test". However,
-action "test" depends on action "code", so current_action() will
-return "code" while that dependency is being executed. Once that
-action has completed, current_action() will again return "test".
-
-If you need to know the name of the original action invoked by the
-user, see L</invoked_action()> below.
-
-=item depends_on(@actions)
-
-[version 0.28]
-
-Invokes the named action or list of actions in sequence. Using this
-method is preferred to calling the action explicitly because it
-performs some internal record-keeping, and it ensures that the same
-action is not invoked multiple times (note: in future versions of
-Module::Build it's conceivable that this run-only-once mechanism will
-be changed to something more intelligent).
-
-Note that the name of this method is something of a misnomer; it
-should really be called something like
-C<invoke_actions_unless_already_invoked()> or something, but for
-better or worse (perhaps better!) we were still thinking in
-C<make>-like dependency terms when we created this method.
-
-See also L<dispatch()|/"dispatch($action, %args)">. The main
-distinction between the two is that C<depends_on()> is meant to call
-an action from inside another action, whereas C<dispatch()> is meant
-to set the very top action in motion.
-
-=item dir_contains($first_dir, $second_dir)
-
-[version 0.28]
-
-Returns true if the first directory logically contains the second
-directory. This is just a convenience function because C<File::Spec>
-doesn't really provide an easy way to figure this out (but
-C<Path::Class> does...).
-
-=item dispatch($action, %args)
-
-[version 0.03]
-
-Invokes the build action C<$action>. Optionally, a list of options
-and their values can be passed in. This is equivalent to invoking an
-action at the command line, passing in a list of options.
-
-Custom options that have not been registered must be passed in as a
-hash reference in a key named "args":
-
- $build->dispatch('foo', verbose => 1, args => { my_option => 'value' });
-
-This method is intended to be used to programmatically invoke build
-actions, e.g. by applications controlling Module::Build-based builds
-rather than by subclasses.
-
-See also L<depends_on()|/"depends_on(@actions)">. The main
-distinction between the two is that C<depends_on()> is meant to call
-an action from inside another action, whereas C<dispatch()> is meant
-to set the very top action in motion.
-
-=item dist_dir()
-
-[version 0.28]
-
-Returns the name of the directory that will be created during the
-C<dist> action. The name is derived from the C<dist_name> and
-C<dist_version> properties.
-
-=item dist_name()
-
-[version 0.21]
-
-Returns the name of the current distribution, as passed to the
-C<new()> method in a C<dist_name> or modified C<module_name>
-parameter.
-
-=item dist_version()
-
-[version 0.21]
-
-Returns the version of the current distribution, as determined by the
-C<new()> method from a C<dist_version>, C<dist_version_from>, or
-C<module_name> parameter.
-
-=item do_system($cmd, @args)
-
-[version 0.21]
-
-This is a fairly simple wrapper around Perl's C<system()> built-in
-command. Given a command and an array of optional arguments, this
-method will print the command to C<STDOUT>, and then execute it using
-Perl's C<system()>. It returns true or false to indicate success or
-failure (the opposite of how C<system()> works, but more intuitive).
-
-Note that if you supply a single argument to C<do_system()>, it
-will/may be processed by the system's shell, and any special
-characters will do their special things. If you supply multiple
-arguments, no shell will get involved and the command will be executed
-directly.
-
-=item feature($name)
-
-=item feature($name => $value)
-
-[version 0.26]
-
-With a single argument, returns true if the given feature is set.
-With two arguments, sets the given feature to the given boolean value.
-In this context, a "feature" is any optional functionality of an
-installed module. For instance, if you write a module that could
-optionally support a MySQL or PostgreSQL backend, you might create
-features called C<mysql_support> and C<postgres_support>, and set them
-to true/false depending on whether the user has the proper databases
-installed and configured.
-
-Features set in this way using the Module::Build object will be
-available for querying during the build/test process and after
-installation via the generated C<...::ConfigData> module, as
-C<< ...::ConfigData->feature($name) >>.
-
-The C<feature()> and C<config_data()> methods represent
-Module::Build's main support for configuration of installed modules.
-See also L<Module::Build::Authoring/"SAVING CONFIGURATION INFORMATION">.
-
-=item fix_shebang_line(@files)
-
-[version 0.??]
-
-Modify any "shebang" line in the specified files to use the path to the
-perl executable being used for the current build. Files are modified
-in-place. The existing shebang line must have a command that contains
-"C<perl>"; arguments to the command do not count. In particular, this
-means that the use of C<#!/usr/bin/env perl> will not be changed.
-
-For an explanation of shebang lines, see
-L<http://en.wikipedia.org/wiki/Shebang_%28Unix%29>.
-
-=item have_c_compiler()
-
-[version 0.21]
-
-Returns true if the current system seems to have a working C compiler.
-We currently determine this by attempting to compile a simple C source
-file and reporting whether the attempt was successful.
-
-=item install_base_relpaths()
-
-=item install_base_relpaths($type)
-
-=item install_base_relpaths($type => $path)
-
-[version 0.28]
-
-Set or retrieve the relative paths that are appended to
-C<install_base> for any installable element. This is useful if you
-want to set the relative install path for custom build elements.
-
-With no argument, it returns a reference to a hash containing all
-elements and their respective values. This hash should not be modified
-directly; use the multiple argument below form to change values.
-
-The single argument form returns the value associated with the
-element C<$type>.
-
-The multiple argument form allows you to set the paths for element types.
-C<$value> must be a relative path using Unix-like paths. (A series of
-directories separated by slashes, e.g. C<foo/bar>.) The return value is a
-localized path based on C<$value>.
-
-Assigning the value C<undef> to an element causes it to be removed.
-
-=item install_destination($type)
-
-[version 0.28]
-
-Returns the directory in which items of type C<$type> (e.g. C<lib>,
-C<arch>, C<bin>, or anything else returned by the L</install_types()>
-method) will be installed during the C<install> action. Any settings
-for C<install_path>, C<install_base>, and C<prefix> are taken into
-account when determining the return value.
-
-=item install_path()
-
-=item install_path($type)
-
-=item install_path($type => $path)
-
-[version 0.28]
-
-Set or retrieve paths for specific installable elements. This is
-useful when you want to examine any explicit install paths specified
-by the user on the command line, or if you want to set the install
-path for a specific installable element based on another attribute
-like C<install_base()>.
-
-With no argument, it returns a reference to a hash containing all
-elements and their respective values. This hash should not be modified
-directly; use the multiple argument below form to change values.
-
-The single argument form returns the value associated with the
-element C<$type>.
-
-The multiple argument form allows you to set the paths for element types.
-The supplied C<$path> should be an absolute path to install elements
-of C<$type>. The return value is C<$path>.
-
-Assigning the value C<undef> to an element causes it to be removed.
-
-=item install_types()
-
-[version 0.28]
-
-Returns a list of installable types that this build knows about.
-These types each correspond to the name of a directory in F<blib/>,
-and the list usually includes items such as C<lib>, C<arch>, C<bin>,
-C<script>, C<libdoc>, C<bindoc>, and if HTML documentation is to be
-built, C<libhtml> and C<binhtml>. Other user-defined types may also
-exist.
-
-=item invoked_action()
-
-[version 0.28]
-
-This is the name of the original action invoked by the user. This
-value is set when the user invokes F<Build.PL>, the F<Build> script,
-or programmatically through the L<dispatch()|/"dispatch($action, %args)">
-method. It does not change as sub-actions are executed as
-dependencies are evaluated.
-
-To get the name of the currently executing dependency, see
-L</current_action()> above.
-
-=item notes()
-
-=item notes($key)
-
-=item notes($key => $value)
-
-[version 0.20]
-
-The C<notes()> value allows you to store your own persistent
-information about the build, and to share that information among
-different entities involved in the build. See the example in the
-C<current()> method.
-
-The C<notes()> method is essentially a glorified hash access. With no
-arguments, C<notes()> returns the entire hash of notes. With one argument,
-C<notes($key)> returns the value associated with the given key. With two
-arguments, C<notes($key, $value)> sets the value associated with the given key
-to C<$value> and returns the new value.
-
-The lifetime of the C<notes> data is for "a build" - that is, the
-C<notes> hash is created when C<perl Build.PL> is run (or when the
-C<new()> method is run, if the Module::Build Perl API is being used
-instead of called from a shell), and lasts until C<perl Build.PL> is
-run again or the C<clean> action is run.
-
-=item orig_dir()
-
-[version 0.28]
-
-Returns a string containing the working directory that was in effect
-before the F<Build> script chdir()-ed into the C<base_dir>. This
-might be useful for writing wrapper tools that might need to chdir()
-back out.
-
-=item os_type()
-
-[version 0.04]
-
-If you're subclassing Module::Build and some code needs to alter its
-behavior based on the current platform, you may only need to know
-whether you're running on Windows, Unix, MacOS, VMS, etc., and not the
-fine-grained value of Perl's C<$^O> variable. The C<os_type()> method
-will return a string like C<Windows>, C<Unix>, C<MacOS>, C<VMS>, or
-whatever is appropriate. If you're running on an unknown platform, it
-will return C<undef> - there shouldn't be many unknown platforms
-though.
-
-=item is_vmsish()
-
-=item is_windowsish()
-
-=item is_unixish()
-
-Convenience functions that return a boolean value indicating whether
-this platform behaves respectively like VMS, Windows, or Unix. For
-arbitrary reasons other platforms don't get their own such functions,
-at least not yet.
-
-
-=item prefix_relpaths()
-
-=item prefix_relpaths($installdirs)
-
-=item prefix_relpaths($installdirs, $type)
-
-=item prefix_relpaths($installdirs, $type => $path)
-
-[version 0.28]
-
-Set or retrieve the relative paths that are appended to C<prefix> for
-any installable element. This is useful if you want to set the
-relative install path for custom build elements.
-
-With no argument, it returns a reference to a hash containing all
-elements and their respective values as defined by the current
-C<installdirs> setting.
-
-With a single argument, it returns a reference to a hash containing
-all elements and their respective values as defined by
-C<$installdirs>.
-
-The hash returned by the above calls should not be modified directly;
-use the three-argument below form to change values.
-
-The two argument form returns the value associated with the
-element C<$type>.
-
-The multiple argument form allows you to set the paths for element types.
-C<$value> must be a relative path using Unix-like paths. (A series of
-directories separated by slashes, e.g. C<foo/bar>.) The return value is a
-localized path based on C<$value>.
-
-Assigning the value C<undef> to an element causes it to be removed.
-
-=item get_metadata()
-
-[version 0.36]
-
-This method returns a hash reference of metadata that can be used to create a
-YAML datastream. It is provided for authors to override or customize the fields
-of F<META.yml>. E.g.
-
- package My::Builder;
- use base 'Module::Build';
-
- sub get_metadata {
- my $self, @args = @_;
- my $data = $self->SUPER::get_metadata(@args);
- $data->{custom_field} = 'foo';
- return $data;
- }
-
-Valid arguments include:
-
-=over
-
-=item *
-
-C<fatal> -- indicates whether missing required
-metadata fields should be a fatal error or not. For META creation, it
-generally should, but for MYMETA creation for end-users, it should not be
-fatal.
-
-=item *
-
-C<auto> -- indicates whether any necessary configure_requires should be
-automatically added. This is used in META creation.
-
-=back
-
-This method is a wrapper around the old prepare_metadata API now that we
-no longer use YAML::Node to hold metadata.
-
-=item prepare_metadata() [deprecated]
-
-[version 0.36]
-
-[Deprecated] As of 0.36, authors should use C<get_metadata> instead. This
-method is preserved for backwards compatibility only.
-
-It takes three positional arguments: a hashref (to which metadata will be
-added), an optional arrayref (to which metadata keys will be added in order if
-the arrayref exists), and a hashref of arguments (as provided to get_metadata).
-The latter argument is new as of 0.36. Earlier versions are always fatal on
-errors.
-
-Prior to version 0.36, this method took a YAML::Node as an argument to hold
-assembled metadata.
-
-=item prereq_failures()
-
-[version 0.11]
-
-Returns a data structure containing information about any failed
-prerequisites (of any of the types described above), or C<undef> if
-all prerequisites are met.
-
-The data structure returned is a hash reference. The top level keys
-are the type of prerequisite failed, one of "requires",
-"build_requires", "conflicts", or "recommends". The associated values
-are hash references whose keys are the names of required (or
-conflicting) modules. The associated values of those are hash
-references indicating some information about the failure. For example:
-
- {
- have => '0.42',
- need => '0.59',
- message => 'Version 0.42 is installed, but we need version 0.59',
- }
-
-or
-
- {
- have => '<none>',
- need => '0.59',
- message => 'Prerequisite Foo isn't installed',
- }
-
-This hash has the same structure as the hash returned by the
-C<check_installed_status()> method, except that in the case of
-"conflicts" dependencies we change the "need" key to "conflicts" and
-construct a proper message.
-
-Examples:
-
- # Check a required dependency on Foo::Bar
- if ( $build->prereq_failures->{requires}{Foo::Bar} ) { ...
-
- # Check whether there were any failures
- if ( $build->prereq_failures ) { ...
-
- # Show messages for all failures
- my $failures = $build->prereq_failures;
- while (my ($type, $list) = each %$failures) {
- while (my ($name, $hash) = each %$list) {
- print "Failure for $name: $hash->{message}\n";
- }
- }
-
-=item prereq_data()
-
-[version 0.32]
-
-Returns a reference to a hash describing all prerequisites. The keys of the
-hash will be the various prerequisite types ('requires', 'build_requires',
-'configure_requires', 'recommends', or 'conflicts') and the values will be
-references to hashes of module names and version numbers. Only prerequisites
-types that are defined will be included. The C<prereq_data> action is just a
-thin wrapper around the C<prereq_data()> method and dumps the hash as a string
-that can be loaded using C<eval()>.
-
-=item prereq_report()
-
-[version 0.28]
-
-Returns a human-readable (table-form) string showing all
-prerequisites, the versions required, and the versions actually
-installed. This can be useful for reviewing the configuration of your
-system prior to a build, or when compiling data to send for a bug
-report. The C<prereq_report> action is just a thin wrapper around the
-C<prereq_report()> method.
-
-=item prompt($message, $default)
-
-[version 0.12]
-
-Asks the user a question and returns their response as a string. The
-first argument specifies the message to display to the user (for
-example, C<"Where do you keep your money?">). The second argument,
-which is optional, specifies a default answer (for example,
-C<"wallet">). The user will be asked the question once.
-
-If C<prompt()> detects that it is not running interactively and there
-is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment variable
-is set to true, the $default will be used without prompting.
-
-To prevent automated processes from blocking, the user must either set
-PERL_MM_USE_DEFAULT or attach something to STDIN (this can be a
-pipe/file containing a scripted set of answers or /dev/null.)
-
-If no $default is provided an empty string will be used instead. In
-non-interactive mode, the absence of $default is an error (though
-explicitly passing C<undef()> as the default is valid as of 0.27.)
-
-This method may be called as a class or object method.
-
-=item recommends()
-
-[version 0.21]
-
-Returns a hash reference indicating the C<recommends> prerequisites
-that were passed to the C<new()> method.
-
-=item requires()
-
-[version 0.21]
-
-Returns a hash reference indicating the C<requires> prerequisites that
-were passed to the C<new()> method.
-
-=item rscan_dir($dir, $pattern)
-
-[version 0.28]
-
-Uses C<File::Find> to traverse the directory C<$dir>, returning a
-reference to an array of entries matching C<$pattern>. C<$pattern>
-may either be a regular expression (using C<qr//> or just a plain
-string), or a reference to a subroutine that will return true for
-wanted entries. If C<$pattern> is not given, all entries will be
-returned.
-
-Examples:
-
- # All the *.pm files in lib/
- $m->rscan_dir('lib', qr/\.pm$/)
-
- # All the files in blib/ that aren't *.html files
- $m->rscan_dir('blib', sub {-f $_ and not /\.html$/});
-
- # All the files in t/
- $m->rscan_dir('t');
-
-=item runtime_params()
-
-=item runtime_params($key)
-
-[version 0.28]
-
-The C<runtime_params()> method stores the values passed on the command line
-for valid properties (that is, any command line options for which
-C<valid_property()> returns a true value). The value on the command line may
-override the default value for a property, as well as any value specified in a
-call to C<new()>. This allows you to programmatically tell if C<perl Build.PL>
-or any execution of C<./Build> had command line options specified that
-override valid properties.
-
-The C<runtime_params()> method is essentially a glorified read-only hash. With
-no arguments, C<runtime_params()> returns the entire hash of properties
-specified on the command line. With one argument, C<runtime_params($key)>
-returns the value associated with the given key.
-
-The lifetime of the C<runtime_params> data is for "a build" - that is, the
-C<runtime_params> hash is created when C<perl Build.PL> is run (or when the
-C<new()> method is called, if the Module::Build Perl API is being used instead
-of called from a shell), and lasts until C<perl Build.PL> is run again or the
-C<clean> action is run.
-
-=item script_files()
-
-[version 0.18]
-
-Returns a hash reference whose keys are the perl script files to be
-installed, if any. This corresponds to the C<script_files> parameter to the
-C<new()> method. With an optional argument, this parameter may be set
-dynamically.
-
-For backward compatibility, the C<scripts()> method does exactly the
-same thing as C<script_files()>. C<scripts()> is deprecated, but it
-will stay around for several versions to give people time to
-transition.
-
-=item up_to_date($source_file, $derived_file)
-
-=item up_to_date(\@source_files, \@derived_files)
-
-[version 0.20]
-
-This method can be used to compare a set of source files to a set of
-derived files. If any of the source files are newer than any of the
-derived files, it returns false. Additionally, if any of the derived
-files do not exist, it returns false. Otherwise it returns true.
-
-The arguments may be either a scalar or an array reference of file
-names.
-
-=item y_n($message, $default)
-
-[version 0.12]
-
-Asks the user a yes/no question using C<prompt()> and returns true or
-false accordingly. The user will be asked the question repeatedly
-until they give an answer that looks like "yes" or "no".
-
-The first argument specifies the message to display to the user (for
-example, C<"Shall I invest your money for you?">), and the second
-argument specifies the default answer (for example, C<"y">).
-
-Note that the default is specified as a string like C<"y"> or C<"n">,
-and the return value is a Perl boolean value like 1 or 0. I thought
-about this for a while and this seemed like the most useful way to do
-it.
-
-This method may be called as a class or object method.
-
-=back
-
-
-=head2 Autogenerated Accessors
-
-In addition to the aforementioned methods, there are also some get/set
-accessor methods for the following properties:
-
-=over 4
-
-=item PL_files()
-
-=item allow_mb_mismatch()
-
-=item auto_configure_requires()
-
-=item autosplit()
-
-=item base_dir()
-
-=item bindoc_dirs()
-
-=item blib()
-
-=item build_bat()
-
-=item build_class()
-
-=item build_elements()
-
-=item build_requires()
-
-=item build_script()
-
-=item bundle_inc()
-
-=item bundle_inc_preload()
-
-=item c_source()
-
-=item config_dir()
-
-=item configure_requires()
-
-=item conflicts()
-
-=item cpan_client()
-
-=item create_license()
-
-=item create_makefile_pl()
-
-=item create_packlist()
-
-=item create_readme()
-
-=item debug()
-
-=item debugger()
-
-=item destdir()
-
-=item dynamic_config()
-
-=item get_options()
-
-=item html_css()
-
-=item include_dirs()
-
-=item install_base()
-
-=item installdirs()
-
-=item libdoc_dirs()
-
-=item license()
-
-=item magic_number()
-
-=item mb_version()
-
-=item meta_add()
-
-=item meta_merge()
-
-=item metafile()
-
-=item metafile2()
-
-=item module_name()
-
-=item mymetafile()
-
-=item mymetafile2()
-
-=item needs_compiler()
-
-=item orig_dir()
-
-=item perl()
-
-=item pm_files()
-
-=item pod_files()
-
-=item pollute()
-
-=item prefix()
-
-=item prereq_action_types()
-
-=item program_name()
-
-=item quiet()
-
-=item recommends()
-
-=item recurse_into()
-
-=item recursive_test_files()
-
-=item requires()
-
-=item scripts()
-
-=item sign()
-
-=item tap_harness_args()
-
-=item test_file_exts()
-
-=item use_rcfile()
-
-=item use_tap_harness()
-
-=item verbose()
-
-=item xs_files()
-
-=back
-
-=head1 MODULE METADATA
-
-If you would like to add other useful metadata, C<Module::Build>
-supports this with the C<meta_add> and C<meta_merge> arguments to
-L</new()>. The authoritative list of supported metadata can be found at
-L<CPAN::META::Spec> but for convenience - here are a few of the more useful ones:
-
-=over 4
-
-=item keywords
-
-For describing the distribution using keyword (or "tags") in order to
-make CPAN.org indexing and search more efficient and useful.
-
-=item resources
-
-A list of additional resources available for users of the
-distribution. This can include links to a homepage on the web, a
-bug tracker, the repository location, and even a subscription page for the
-distribution mailing list.
-
-=back
-
-
-=head1 AUTHOR
-
-Ken Williams <kwilliams@cpan.org>
-
-
-=head1 COPYRIGHT
-
-Copyright (c) 2001-2006 Ken Williams. All rights reserved.
-
-This library is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-
-=head1 SEE ALSO
-
-perl(1), L<Module::Build>(3), L<Module::Build::Authoring>(3),
-L<Module::Build::Cookbook>(3), L<ExtUtils::MakeMaker>(3)
-
-F<META.yml> Specification:
-L<CPAN::META::Spec>
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Module/Build/Authoring.pod b/Master/tlpkg/tlperl/lib/Module/Build/Authoring.pod
deleted file mode 100644
index 92164df9211..00000000000
--- a/Master/tlpkg/tlperl/lib/Module/Build/Authoring.pod
+++ /dev/null
@@ -1,322 +0,0 @@
-=head1 NAME
-
-Module::Build::Authoring - Authoring Module::Build modules
-
-=head1 DESCRIPTION
-
-When creating a C<Build.PL> script for a module, something like the
-following code will typically be used:
-
- use Module::Build;
- my $build = Module::Build->new
- (
- module_name => 'Foo::Bar',
- license => 'perl',
- requires => {
- 'perl' => '5.6.1',
- 'Some::Module' => '1.23',
- 'Other::Module' => '>= 1.2, != 1.5, < 2.0',
- },
- );
- $build->create_build_script;
-
-A simple module could get away with something as short as this for its
-C<Build.PL> script:
-
- use Module::Build;
- Module::Build->new(
- module_name => 'Foo::Bar',
- license => 'perl',
- )->create_build_script;
-
-The model used by C<Module::Build> is a lot like the C<MakeMaker>
-metaphor, with the following correspondences:
-
- In Module::Build In ExtUtils::MakeMaker
- --------------------------- ------------------------
- Build.PL (initial script) Makefile.PL (initial script)
- Build (a short perl script) Makefile (a long Makefile)
- _build/ (saved state info) various config text in the Makefile
-
-Any customization can be done simply by subclassing C<Module::Build>
-and adding a method called (for example) C<ACTION_test>, overriding
-the default 'test' action. You could also add a method called
-C<ACTION_whatever>, and then you could perform the action C<Build
-whatever>.
-
-For information on providing compatibility with
-C<ExtUtils::MakeMaker>, see L<Module::Build::Compat> and
-L<http://www.makemaker.org/wiki/index.cgi?ModuleBuildConversionGuide>.
-
-
-=head1 STRUCTURE
-
-Module::Build creates a class hierarchy conducive to customization.
-Here is the parent-child class hierarchy in classy ASCII art:
-
- /--------------------\
- | Your::Parent | (If you subclass Module::Build)
- \--------------------/
- |
- |
- /--------------------\ (Doesn't define any functionality
- | Module::Build | of its own - just figures out what
- \--------------------/ other modules to load.)
- |
- |
- /-----------------------------------\ (Some values of $^O may
- | Module::Build::Platform::$^O | define specialized functionality.
- \-----------------------------------/ Otherwise it's ...::Default, a
- | pass-through class.)
- |
- /--------------------------\
- | Module::Build::Base | (Most of the functionality of
- \--------------------------/ Module::Build is defined here.)
-
-
-=head1 SUBCLASSING
-
-Right now, there are two ways to subclass Module::Build. The first
-way is to create a regular module (in a C<.pm> file) that inherits
-from Module::Build, and use that module's class instead of using
-Module::Build directly:
-
- ------ in Build.PL: ----------
- #!/usr/bin/perl
-
- use lib q(/nonstandard/library/path);
- use My::Builder; # Or whatever you want to call it
-
- my $build = My::Builder->new
- (
- module_name => 'Foo::Bar', # All the regular args...
- license => 'perl',
- dist_author => 'A N Other <me@here.net.au>',
- requires => { Carp => 0 }
- );
- $build->create_build_script;
-
-This is relatively straightforward, and is the best way to do things
-if your My::Builder class contains lots of code. The
-C<create_build_script()> method will ensure that the current value of
-C<@INC> (including the C</nonstandard/library/path>) is propagated to
-the Build script, so that My::Builder can be found when running build
-actions. If you find that you need to C<chdir> into a different directories
-in your subclass methods or actions, be sure to always return to the original
-directory (available via the C<base_dir()> method) before returning control
-to the parent class. This is important to avoid data serialization problems.
-
-For very small additions, Module::Build provides a C<subclass()>
-method that lets you subclass Module::Build more conveniently, without
-creating a separate file for your module:
-
- ------ in Build.PL: ----------
- #!/usr/bin/perl
-
- use Module::Build;
- my $class = Module::Build->subclass
- (
- class => 'My::Builder',
- code => q{
- sub ACTION_foo {
- print "I'm fooing to death!\n";
- }
- },
- );
-
- my $build = $class->new
- (
- module_name => 'Foo::Bar', # All the regular args...
- license => 'perl',
- dist_author => 'A N Other <me@here.net.au>',
- requires => { Carp => 0 }
- );
- $build->create_build_script;
-
-Behind the scenes, this actually does create a C<.pm> file, since the
-code you provide must persist after Build.PL is run if it is to be
-very useful.
-
-See also the documentation for the L<Module::Build::API/"subclass()">
-method.
-
-
-=head1 PREREQUISITES
-
-=head2 Types of prerequisites
-
-To specify what versions of other modules are used by this
-distribution, several types of prerequisites can be defined with the
-following parameters:
-
-=over 3
-
-=item configure_requires
-
-Items that must be installed I<before> configuring this distribution
-(i.e. before running the F<Build.PL> script). This might be a
-specific minimum version of C<Module::Build> or any other module the
-F<Build.PL> needs in order to do its stuff. Clients like C<CPAN.pm>
-or C<CPANPLUS> will be expected to pick C<configure_requires> out of the
-F<META.yml> file and install these items before running the
-C<Build.PL>.
-
-If no configure_requires is specified, the current version of Module::Build
-is automatically added to configure_requires.
-
-=item build_requires
-
-Items that are necessary for building and testing this distribution,
-but aren't necessary after installation. This can help users who only
-want to install these items temporarily. It also helps reduce the
-size of the CPAN dependency graph if everything isn't smooshed into
-C<requires>.
-
-=item requires
-
-Items that are necessary for basic functioning.
-
-=item recommends
-
-Items that are recommended for enhanced functionality, but there are
-ways to use this distribution without having them installed. You
-might also think of this as "can use" or "is aware of" or "changes
-behavior in the presence of".
-
-=item conflicts
-
-Items that can cause problems with this distribution when installed.
-This is pretty rare.
-
-=back
-
-=head2 Format of prerequisites
-
-The prerequisites are given in a hash reference, where the keys are
-the module names and the values are version specifiers:
-
- requires => {
- Foo::Module => '2.4',
- Bar::Module => 0,
- Ken::Module => '>= 1.2, != 1.5, < 2.0',
- perl => '5.6.0'
- },
-
-The above four version specifiers have different effects. The value
-C<'2.4'> means that B<at least> version 2.4 of C<Foo::Module> must be
-installed. The value C<0> means that B<any> version of C<Bar::Module>
-is acceptable, even if C<Bar::Module> doesn't define a version. The
-more verbose value C<'E<gt>= 1.2, != 1.5, E<lt> 2.0'> means that
-C<Ken::Module>'s version must be B<at least> 1.2, B<less than> 2.0,
-and B<not equal to> 1.5. The list of criteria is separated by commas,
-and all criteria must be satisfied.
-
-A special C<perl> entry lets you specify the versions of the Perl
-interpreter that are supported by your module. The same version
-dependency-checking semantics are available, except that we also
-understand perl's new double-dotted version numbers.
-
-=head2 XS Extensions
-
-Modules which need to compile XS code should list C<ExtUtils::CBuilder>
-as a C<build_requires> element.
-
-
-=head1 SAVING CONFIGURATION INFORMATION
-
-Module::Build provides a very convenient way to save configuration
-information that your installed modules (or your regression tests) can
-access. If your Build process calls the C<feature()> or
-C<config_data()> methods, then a C<Foo::Bar::ConfigData> module will
-automatically be created for you, where C<Foo::Bar> is the
-C<module_name> parameter as passed to C<new()>. This module provides
-access to the data saved by these methods, and a way to update the
-values. There is also a utility script called C<config_data>
-distributed with Module::Build that provides a command line interface
-to this same functionality. See also the generated
-C<Foo::Bar::ConfigData> documentation, and the C<config_data>
-script's documentation, for more information.
-
-
-=head1 STARTING MODULE DEVELOPMENT
-
-When starting development on a new module, it's rarely worth your time
-to create a tree of all the files by hand. Some automatic
-module-creators are available: the oldest is C<h2xs>, which has
-shipped with perl itself for a long time. Its name reflects the fact
-that modules were originally conceived of as a way to wrap up a C
-library (thus the C<h> part) into perl extensions (thus the C<xs>
-part).
-
-These days, C<h2xs> has largely been superseded by modules like
-C<ExtUtils::ModuleMaker>, and C<Module::Starter>. They have varying
-degrees of support for C<Module::Build>.
-
-
-=head1 AUTOMATION
-
-One advantage of Module::Build is that since it's implemented as Perl
-methods, you can invoke these methods directly if you want to install
-a module non-interactively. For instance, the following Perl script
-will invoke the entire build/install procedure:
-
- my $build = Module::Build->new(module_name => 'MyModule');
- $build->dispatch('build');
- $build->dispatch('test');
- $build->dispatch('install');
-
-If any of these steps encounters an error, it will throw a fatal
-exception.
-
-You can also pass arguments as part of the build process:
-
- my $build = Module::Build->new(module_name => 'MyModule');
- $build->dispatch('build');
- $build->dispatch('test', verbose => 1);
- $build->dispatch('install', sitelib => '/my/secret/place/');
-
-Building and installing modules in this way skips creating the
-C<Build> script.
-
-
-=head1 MIGRATION
-
-Note that if you want to provide both a F<Makefile.PL> and a
-F<Build.PL> for your distribution, you probably want to add the
-following to C<WriteMakefile> in your F<Makefile.PL> so that C<MakeMaker>
-doesn't try to run your F<Build.PL> as a normal F<.PL> file:
-
- PL_FILES => {},
-
-You may also be interested in looking at the C<Module::Build::Compat>
-module, which can automatically create various kinds of F<Makefile.PL>
-compatibility layers.
-
-
-=head1 AUTHOR
-
-Ken Williams <kwilliams@cpan.org>
-
-Development questions, bug reports, and patches should be sent to the
-Module-Build mailing list at <module-build@perl.org>.
-
-Bug reports are also welcome at
-<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
-
-The latest development version is available from the Git
-repository at <https://github.com/dagolden/module-build/>
-
-
-=head1 SEE ALSO
-
-perl(1), L<Module::Build>(3), L<Module::Build::API>(3),
-L<Module::Build::Cookbook>(3), L<ExtUtils::MakeMaker>(3), L<YAML>(3)
-
-F<META.yml> Specification:
-L<CPAN::META::Spec>
-
-L<http://www.dsmit.com/cons/>
-
-L<http://search.cpan.org/dist/PerlBuildSystem/>
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Module/Build/Bundling.pod b/Master/tlpkg/tlperl/lib/Module/Build/Bundling.pod
deleted file mode 100644
index 5e7b9f98075..00000000000
--- a/Master/tlpkg/tlperl/lib/Module/Build/Bundling.pod
+++ /dev/null
@@ -1,147 +0,0 @@
-=head1 NAME
-
-Module::Build::Bundling - How to bundle Module::Build with a distribution
-
-=head1 SYNOPSIS
-
- # Build.PL
- use inc::latest 'Module::Build';
-
- Module::Build->new(
- module_name => 'Foo::Bar',
- license => 'perl',
- )->create_build_script;
-
-=head1 DESCRIPTION
-
-B<WARNING -- THIS IS AN EXPERIMENTAL FEATURE>
-
-In order to install a distribution using Module::Build, users must
-have Module::Build available on their systems. There are two ways
-to do this. The first way is to include Module::Build in the
-C<configure_requires> metadata field. This field is supported by
-recent versions L<CPAN> and L<CPANPLUS> and is a standard feature
-in the Perl core as of Perl 5.10.1. Module::Build now adds itself
-to C<configure_requires> by default.
-
-The second way supports older Perls that have not upgraded CPAN or
-CPANPLUS and involves bundling an entire copy of Module::Build
-into the distribution's C<inc/> directory. This is the same approach
-used by L<Module::Install>, a modern wrapper around ExtUtils::MakeMaker
-for Makefile.PL based distributions.
-
-The "trick" to making this work for Module::Build is making sure the
-highest version Module::Build is used, whether this is in C<inc/> or
-already installed on the user's system. This ensures that all necessary
-features are available as well as any new bug fixes. This is done using
-the new L<inc::latest> module.
-
-A "normal" Build.PL looks like this (with only the minimum required
-fields):
-
- use Module::Build;
-
- Module::Build->new(
- module_name => 'Foo::Bar',
- license => 'perl',
- )->create_build_script;
-
-A "bundling" Build.PL replaces the initial "use" line with a nearly
-transparent replacement:
-
- use inc::latest 'Module::Build';
-
- Module::Build->new(
- module_name => 'Foo::Bar',
- license => 'perl',
- )->create_build_script;
-
-For I<authors>, when "Build dist" is run, Module::Build will be
-automatically bundled into C<inc> according to the rules for
-L<inc::latest>.
-
-For I<users>, inc::latest will load the latest Module::Build, whether
-installed or bundled in C<inc/>.
-
-=head1 BUNDLING OTHER CONFIGURATION DEPENDENCIES
-
-The same approach works for other configuration dependencies -- modules
-that I<must> be available for Build.PL to run. All other dependencies can
-be specified as usual in the Build.PL and CPAN or CPANPLUS will install
-them after Build.PL finishes.
-
-For example, to bundle the L<Devel::AssertOS::Unix> module (which ensures a
-"Unix-like" operating system), one could do this:
-
- use inc::latest 'Devel::AssertOS::Unix';
- use inc::latest 'Module::Build';
-
- Module::Build->new(
- module_name => 'Foo::Bar',
- license => 'perl',
- )->create_build_script;
-
-The C<inc::latest> module creates bundled directories based on the packlist
-file of an installed distribution. Even though C<inc::latest> takes module
-name arguments, it is better to think of it as bundling and making
-available entire I<distributions>. When a module is loaded through
-C<inc::latest>, it looks in all bundled distributions in C<inc/> for a
-newer module than can be found in the existing C<@INC> array.
-
-Thus, the module-name provided should usually be the "top-level" module
-name of a distribution, though this is not strictly required. For example,
-L<Module::Build> has a number of heuristics to map module names to
-packlists, allowing users to do things like this:
-
- use inc::latest 'Devel::AssertOS::Unix';
-
-even though Devel::AssertOS::Unix is contained within the Devel-CheckOS
-distribution.
-
-At the current time, packlists are required. Thus, bundling dual-core
-modules, I<including Module::Build>, may require a 'forced install' over
-versions in the latest version of perl in order to create the necessary
-packlist for bundling. This limitation will hopefully be addressed in a
-future version of Module::Build.
-
-=head2 WARNING -- How to Manage Dependency Chains
-
-Before bundling a distribution you must ensure that all prerequisites are
-also bundled and load in the correct order. For Module::Build itself, this
-should not be necessary, but it is necessary for any other distribution.
-(A future release of Module::Build will hopefully address this deficiency.)
-
-For example, if you need C<Wibble>, but C<Wibble> depends on C<Wobble>,
-your Build.PL might look like this:
-
- use inc::latest 'Wobble';
- use inc::latest 'Wibble';
- use inc::latest 'Module::Build';
-
- Module::Build->new(
- module_name => 'Foo::Bar',
- license => 'perl',
- )->create_build_script;
-
-Authors are strongly suggested to limit the bundling of additional
-dependencies if at all possible and to carefully test their distribution
-tarballs on older versions of Perl before uploading to CPAN.
-
-=head1 AUTHOR
-
-David Golden <dagolden@cpan.org>
-
-Development questions, bug reports, and patches should be sent to the
-Module-Build mailing list at <module-build@perl.org>.
-
-Bug reports are also welcome at
-<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
-
-=head1 SEE ALSO
-
-perl(1), L<inc::latest>, L<Module::Build>(3), L<Module::Build::API>(3),
-L<Module::Build::Cookbook>(3),
-
-=cut
-
-# vim: tw=75
diff --git a/Master/tlpkg/tlperl/lib/Module/CoreList.pod b/Master/tlpkg/tlperl/lib/Module/CoreList.pod
deleted file mode 100644
index 4db77e6a283..00000000000
--- a/Master/tlpkg/tlperl/lib/Module/CoreList.pod
+++ /dev/null
@@ -1,214 +0,0 @@
-=head1 NAME
-
-Module::CoreList - what modules shipped with versions of perl
-
-=head1 SYNOPSIS
-
- use Module::CoreList;
-
- print $Module::CoreList::version{5.00503}{CPAN}; # prints 1.48
-
- print Module::CoreList->first_release('File::Spec'); # prints 5.00405
- print Module::CoreList->first_release_by_date('File::Spec'); # prints 5.005
- print Module::CoreList->first_release('File::Spec', 0.82); # prints 5.006001
-
- print join ', ', Module::CoreList->find_modules(qr/Data/);
- # prints 'Data::Dumper'
- print join ', ', Module::CoreList->find_modules(qr/test::h.*::.*s/i, 5.008008);
- # prints 'Test::Harness::Assert, Test::Harness::Straps'
-
- print join ", ", @{ $Module::CoreList::families{5.005} };
- # prints "5.005, 5.00503, 5.00504"
-
-=head1 DESCRIPTION
-
-Module::CoreList provides information on which core and dual-life modules shipped
-with each version of L<perl>.
-
-It provides a number of mechanisms for querying this information.
-
-There is a utility called L<corelist> provided with this module
-which is a convenient way of querying from the command-line.
-
-There is a functional programming API available for programmers to query
-information.
-
-Programmers may also query the contained hash structures to find relevant
-information.
-
-=head1 FUNCTIONS API
-
-These are the functions that are available, they may either be called as functions or class methods:
-
- Module::CoreList::first_release('File::Spec'); # as a function
-
- Module::CoreList->first_release('File::Spec'); # class method
-
-=over
-
-=item C<first_release( MODULE )>
-
-Behaviour since version 2.11
-
-Requires a MODULE name as an argument, returns the perl version when that module first
-appeared in core as ordered by perl version number or undef ( in scalar context )
-or an empty list ( in list context ) if that module is not in core.
-
-=item C<first_release_by_date( MODULE )>
-
-Requires a MODULE name as an argument, returns the perl version when that module first
-appeared in core as ordered by release date or undef ( in scalar context )
-or an empty list ( in list context ) if that module is not in core.
-
-=item C<find_modules( REGEX, [ LIST OF PERLS ] )>
-
-Takes a regex as an argument, returns a list of modules that match the regex given.
-If only a regex is provided applies to all modules in all perl versions. Optionally
-you may provide a list of perl versions to limit the regex search.
-
-=item C<find_version( PERL_VERSION )>
-
-Takes a perl version as an argument. Returns that perl version if it exists or C<undef>
-otherwise.
-
-=item C<is_deprecated( MODULE, PERL_VERSION )>
-
-Available in version 2.22 and above.
-
-Returns true if MODULE is marked as deprecated in PERL_VERSION. If PERL_VERSION is
-omitted, it defaults to the current version of Perl.
-
-=item C<removed_from( MODULE )>
-
-Available in version 2.32 and above
-
-Takes a module name as an argument, returns the first perl version where that module
-was removed from core. Returns undef if the given module was never in core or remains
-in core.
-
-=item C<removed_from_by_date( MODULE )>
-
-Available in version 2.32 and above
-
-Takes a module name as an argument, returns the first perl version by release date where that module
-was removed from core. Returns undef if the given module was never in core or remains
-in core.
-
-=item C<changes_between( PERL_VERSION, PERL_VERSION )>
-
-Available in version 2.66 and above.
-
-Given two perl versions, this returns a list of pairs describing the changes in
-core module content betweent hem. The list is suitable for storing in a hash.
-The keys are library names and the values are hashrefs. Each hashref has an
-entry for one or both of C<left> and C<right>, giving the versions of the
-library in each of the left and right perl distributions.
-
-For example, it might return these data (among others) for the the difference
-between 5.008000 and 5.008001:
-
- 'Pod::ParseLink' => { left => '1.05', right => '1.06' },
- 'Pod::ParseUtils' => { left => '0.22', right => '0.3' },
- 'Pod::Perldoc' => { right => '3.10' },
- 'Pod::Perldoc::BaseTo' => { right => undef },
-
-This shows us two libraries being updated and two being added, one of which has
-an undefined version in the right-hand side version.
-
-=back
-
-=head1 DATA STRUCTURES
-
-These are the hash data structures that are available:
-
-=over
-
-=item C<%Module::CoreList::version>
-
-A hash of hashes that is keyed on perl version as indicated
-in $]. The second level hash is module => version pairs.
-
-Note, it is possible for the version of a module to be unspecified,
-whereby the value is C<undef>, so use C<exists $version{$foo}{$bar}> if
-that's what you're testing for.
-
-Starting with 2.10, the special module name C<Unicode> refers to the version of
-the Unicode Character Database bundled with Perl.
-
-=item C<%Module::CoreList::released>
-
-Keyed on perl version this contains ISO
-formatted versions of the release dates, as gleaned from L<perlhist>.
-
-=item C<%Module::CoreList::families>
-
-New, in 1.96, a hash that
-clusters known perl releases by their major versions.
-
-=item C<%Module::CoreList::deprecated>
-
-A hash of hashes keyed on perl version and on module name.
-If a module is defined it indicates that that module is
-deprecated in that perl version and is scheduled for removal
-from core at some future point.
-
-=item C<%Module::CoreList::upstream>
-
-A hash that contains information on where patches should be directed
-for each core module.
-
-UPSTREAM indicates where patches should go. C<undef> implies
-that this hasn't been discussed for the module at hand.
-C<blead> indicates that the copy of the module in the blead
-sources is to be considered canonical, C<cpan> means that the
-module on CPAN is to be patched first. C<first-come> means
-that blead can be patched freely if it is in sync with the
-latest release on CPAN.
-
-=item C<%Module::CoreList::bug_tracker>
-
-A hash that contains information on the appropriate bug tracker
-for each core module.
-
-BUGS is an email or url to post bug reports. For modules with
-UPSTREAM => 'blead', use perl5-porters@perl.org. rt.cpan.org
-appears to automatically provide a URL for CPAN modules; any value
-given here overrides the default:
-http://rt.cpan.org/Public/Dist/Display.html?Name=$ModuleName
-
-=back
-
-=head1 CAVEATS
-
-Module::CoreList currently covers the 5.000, 5.001, 5.002, 5.003_07,
-5.004, 5.004_05, 5.005, 5.005_03, 5.005_04, 5.6.0, 5.6.1, 5.6.2, 5.7.3,
-5.8.0, 5.8.1, 5.8.2, 5.8.3, 5.8.4, 5.8.5, 5.8.6, 5.8.7, 5.8.8, 5.8.9,
-5.9.0, 5.9.1, 5.9.2, 5.9.3, 5.9.4, 5.9.5, 5.10.0, 5.10.1, 5.11.0, 5.11.1,
-5.11.2, 5.11.3, 5.11.4, 5.11.5, 5.12.0, 5.12.1, 5.12.2, 5.12.3, 5.12.4,
-5.13.0, 5.13.1, 5.13.2, 5.13.3, 5.13.4, 5.13.5, 5.13.6, 5.13.7, 5.13.8,
-5.13.9, 5.13.10, 5.13.11, 5.14.0, 5.14.1, 5.14.2, 5.15.0, 5.15.1, 5.15.2,
-5.15.3, 5.15.4, 5.15.5, 5.15.6, 5.15.7, 5.15.8, 5.15.9, 5.16.0, 5.17.0,
-5.17.1, 5.17.2, 5.17.3, 5.17.4 and 5.17.5 releases of perl.
-
-=head1 HISTORY
-
-Moved to Changes file.
-
-=head1 AUTHOR
-
-Richard Clamp E<lt>richardc@unixbeard.netE<gt>
-
-Currently maintained by the perl 5 porters E<lt>perl5-porters@perl.orgE<gt>.
-
-=head1 LICENSE
-
-Copyright (C) 2002-2009 Richard Clamp. All Rights Reserved.
-
-This module is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-=head1 SEE ALSO
-
-L<corelist>, L<Module::Info>, L<perl>, L<http://perlpunks.de/corelist>
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Net/libnetFAQ.pod b/Master/tlpkg/tlperl/lib/Net/libnetFAQ.pod
deleted file mode 100644
index e6ec362f36a..00000000000
--- a/Master/tlpkg/tlperl/lib/Net/libnetFAQ.pod
+++ /dev/null
@@ -1,303 +0,0 @@
-=head1 NAME
-
-libnetFAQ - libnet Frequently Asked Questions
-
-=head1 DESCRIPTION
-
-=head2 Where to get this document
-
-This document is distributed with the libnet distribution, and is also
-available on the libnet web page at
-
- http://search.cpan.org/~gbarr/libnet/
-
-=head2 How to contribute to this document
-
-You may mail corrections, additions, and suggestions to me
-gbarr@pobox.com.
-
-=head1 Author and Copyright Information
-
-Copyright (c) 1997-1998 Graham Barr. All rights reserved.
-This document is free; you can redistribute it and/or modify it
-under the terms of the Artistic License.
-
-=head2 Disclaimer
-
-This information is offered in good faith and in the hope that it may
-be of use, but is not guaranteed to be correct, up to date, or suitable
-for any particular purpose whatsoever. The authors accept no liability
-in respect of this information or its use.
-
-
-=head1 Obtaining and installing libnet
-
-=head2 What is libnet ?
-
-libnet is a collection of perl5 modules which all related to network
-programming. The majority of the modules available provided the
-client side of popular server-client protocols that are used in
-the internet community.
-
-=head2 Which version of perl do I need ?
-
-libnet has been know to work with versions of perl from 5.002 onwards. However
-if your release of perl is prior to perl5.004 then you will need to
-obtain and install the IO distribution from CPAN. If you have perl5.004
-or later then you will have the IO modules in your installation already,
-but CPAN may contain updates.
-
-=head2 What other modules do I need ?
-
-The only modules you will need installed are the modules from the IO
-distribution. If you have perl5.004 or later you will already have
-these modules.
-
-=head2 What machines support libnet ?
-
-libnet itself is an entirely perl-code distribution so it should work
-on any machine that perl runs on. However IO may not work
-with some machines and earlier releases of perl. But this
-should not be the case with perl version 5.004 or later.
-
-=head2 Where can I get the latest libnet release
-
-The latest libnet release is always on CPAN, you will find it
-in
-
- http://www.cpan.org/modules/by-module/Net/
-
-The latest release and information is also available on the libnet web page
-at
-
- http://search.cpan.org/~gbarr/libnet/
-
-=head1 Using Net::FTP
-
-=head2 How do I download files from an FTP server ?
-
-An example taken from an article posted to comp.lang.perl.misc
-
- #!/your/path/to/perl
-
- # a module making life easier
-
- use Net::FTP;
-
- # for debugging: $ftp = Net::FTP->new('site','Debug',10);
- # open a connection and log in!
-
- $ftp = Net::FTP->new('target_site.somewhere.xxx');
- $ftp->login('username','password');
-
- # set transfer mode to binary
-
- $ftp->binary();
-
- # change the directory on the ftp site
-
- $ftp->cwd('/some/path/to/somewhere/');
-
- foreach $name ('file1', 'file2', 'file3') {
-
- # get's arguments are in the following order:
- # ftp server's filename
- # filename to save the transfer to on the local machine
- # can be simply used as get($name) if you want the same name
-
- $ftp->get($name,$name);
- }
-
- # ftp done!
-
- $ftp->quit;
-
-=head2 How do I transfer files in binary mode ?
-
-To transfer files without <LF><CR> translation Net::FTP provides
-the C<binary> method
-
- $ftp->binary;
-
-=head2 How can I get the size of a file on a remote FTP server ?
-
-=head2 How can I get the modification time of a file on a remote FTP server ?
-
-=head2 How can I change the permissions of a file on a remote server ?
-
-The FTP protocol does not have a command for changing the permissions
-of a file on the remote server. But some ftp servers may allow a chmod
-command to be issued via a SITE command, eg
-
- $ftp->quot('site chmod 0777',$filename);
-
-But this is not guaranteed to work.
-
-=head2 Can I do a reget operation like the ftp command ?
-
-=head2 How do I get a directory listing from an FTP server ?
-
-=head2 Changing directory to "" does not fail ?
-
-Passing an argument of "" to ->cwd() has the same affect of calling ->cwd()
-without any arguments. Turn on Debug (I<See below>) and you will see what is
-happening
-
- $ftp = Net::FTP->new($host, Debug => 1);
- $ftp->login;
- $ftp->cwd("");
-
-gives
-
- Net::FTP=GLOB(0x82196d8)>>> CWD /
- Net::FTP=GLOB(0x82196d8)<<< 250 CWD command successful.
-
-=head2 I am behind a SOCKS firewall, but the Firewall option does not work ?
-
-The Firewall option is only for support of one type of firewall. The type
-supported is an ftp proxy.
-
-To use Net::FTP, or any other module in the libnet distribution,
-through a SOCKS firewall you must create a socks-ified perl executable
-by compiling perl with the socks library.
-
-=head2 I am behind an FTP proxy firewall, but cannot access machines outside ?
-
-Net::FTP implements the most popular ftp proxy firewall approach. The scheme
-implemented is that where you log in to the firewall with C<user@hostname>
-
-I have heard of one other type of firewall which requires a login to the
-firewall with an account, then a second login with C<user@hostname>. You can
-still use Net::FTP to traverse these firewalls, but a more manual approach
-must be taken, eg
-
- $ftp = Net::FTP->new($firewall) or die $@;
- $ftp->login($firewall_user, $firewall_passwd) or die $ftp->message;
- $ftp->login($ext_user . '@' . $ext_host, $ext_passwd) or die $ftp->message.
-
-=head2 My ftp proxy firewall does not listen on port 21
-
-FTP servers usually listen on the same port number, port 21, as any other
-FTP server. But there is no reason why this has to be the case.
-
-If you pass a port number to Net::FTP then it assumes this is the port
-number of the final destination. By default Net::FTP will always try
-to connect to the firewall on port 21.
-
-Net::FTP uses IO::Socket to open the connection and IO::Socket allows
-the port number to be specified as part of the hostname. So this problem
-can be resolved by either passing a Firewall option like C<"hostname:1234">
-or by setting the C<ftp_firewall> option in Net::Config to be a string
-in in the same form.
-
-=head2 Is it possible to change the file permissions of a file on an FTP server ?
-
-The answer to this is "maybe". The FTP protocol does not specify a command to change
-file permissions on a remote host. However many servers do allow you to run the
-chmod command via the C<SITE> command. This can be done with
-
- $ftp->site('chmod','0775',$file);
-
-=head2 I have seen scripts call a method message, but cannot find it documented ?
-
-Net::FTP, like several other packages in libnet, inherits from Net::Cmd, so
-all the methods described in Net::Cmd are also available on Net::FTP
-objects.
-
-=head2 Why does Net::FTP not implement mput and mget methods
-
-The quick answer is because they are easy to implement yourself. The long
-answer is that to write these in such a way that multiple platforms are
-supported correctly would just require too much code. Below are
-some examples how you can implement these yourself.
-
-sub mput {
- my($ftp,$pattern) = @_;
- foreach my $file (glob($pattern)) {
- $ftp->put($file) or warn $ftp->message;
- }
-}
-
-sub mget {
- my($ftp,$pattern) = @_;
- foreach my $file ($ftp->ls($pattern)) {
- $ftp->get($file) or warn $ftp->message;
- }
-}
-
-
-=head1 Using Net::SMTP
-
-=head2 Why can't the part of an Email address after the @ be used as the hostname ?
-
-The part of an Email address which follows the @ is not necessarily a hostname,
-it is a mail domain. To find the name of a host to connect for a mail domain
-you need to do a DNS MX lookup
-
-=head2 Why does Net::SMTP not do DNS MX lookups ?
-
-Net::SMTP implements the SMTP protocol. The DNS MX lookup is not part
-of this protocol.
-
-=head2 The verify method always returns true ?
-
-Well it may seem that way, but it does not. The verify method returns true
-if the command succeeded. If you pass verify an address which the
-server would normally have to forward to another machine, the command
-will succeed with something like
-
- 252 Couldn't verify <someone@there> but will attempt delivery anyway
-
-This command will fail only if you pass it an address in a domain
-the server directly delivers for, and that address does not exist.
-
-=head1 Debugging scripts
-
-=head2 How can I debug my scripts that use Net::* modules ?
-
-Most of the libnet client classes allow options to be passed to the
-constructor, in most cases one option is called C<Debug>. Passing
-this option with a non-zero value will turn on a protocol trace, which
-will be sent to STDERR. This trace can be useful to see what commands
-are being sent to the remote server and what responses are being
-received back.
-
- #!/your/path/to/perl
-
- use Net::FTP;
-
- my $ftp = new Net::FTP($host, Debug => 1);
- $ftp->login('gbarr','password');
- $ftp->quit;
-
-this script would output something like
-
- Net::FTP: Net::FTP(2.22)
- Net::FTP: Exporter
- Net::FTP: Net::Cmd(2.0801)
- Net::FTP: IO::Socket::INET
- Net::FTP: IO::Socket(1.1603)
- Net::FTP: IO::Handle(1.1504)
-
- Net::FTP=GLOB(0x8152974)<<< 220 imagine FTP server (Version wu-2.4(5) Tue Jul 29 11:17:18 CDT 1997) ready.
- Net::FTP=GLOB(0x8152974)>>> user gbarr
- Net::FTP=GLOB(0x8152974)<<< 331 Password required for gbarr.
- Net::FTP=GLOB(0x8152974)>>> PASS ....
- Net::FTP=GLOB(0x8152974)<<< 230 User gbarr logged in. Access restrictions apply.
- Net::FTP=GLOB(0x8152974)>>> QUIT
- Net::FTP=GLOB(0x8152974)<<< 221 Goodbye.
-
-The first few lines tell you the modules that Net::FTP uses and their versions,
-this is useful data to me when a user reports a bug. The last seven lines
-show the communication with the server. Each line has three parts. The first
-part is the object itself, this is useful for separating the output
-if you are using multiple objects. The second part is either C<<<<<> to
-show data coming from the server or C<&gt&gt&gt&gt> to show data
-going to the server. The remainder of the line is the command
-being sent or response being received.
-
-=head1 AUTHOR AND COPYRIGHT
-
-Copyright (c) 1997 Graham Barr.
-All rights reserved.
-
diff --git a/Master/tlpkg/tlperl/lib/POSIX.pod b/Master/tlpkg/tlperl/lib/POSIX.pod
deleted file mode 100644
index f935ae05743..00000000000
--- a/Master/tlpkg/tlperl/lib/POSIX.pod
+++ /dev/null
@@ -1,2221 +0,0 @@
-=head1 NAME
-
-POSIX - Perl interface to IEEE Std 1003.1
-
-=head1 SYNOPSIS
-
- use POSIX ();
- use POSIX qw(setsid);
- use POSIX qw(:errno_h :fcntl_h);
-
- printf "EINTR is %d\n", EINTR;
-
- $sess_id = POSIX::setsid();
-
- $fd = POSIX::open($path, O_CREAT|O_EXCL|O_WRONLY, 0644);
- # note: that's a filedescriptor, *NOT* a filehandle
-
-=head1 DESCRIPTION
-
-The POSIX module permits you to access all (or nearly all) the standard
-POSIX 1003.1 identifiers. Many of these identifiers have been given Perl-ish
-interfaces.
-
-I<Everything is exported by default> with the exception of any POSIX
-functions with the same name as a built-in Perl function, such as
-C<abs>, C<alarm>, C<rmdir>, C<write>, etc.., which will be exported
-only if you ask for them explicitly. This is an unfortunate backwards
-compatibility feature. You can stop the exporting by saying C<use
-POSIX ()> and then use the fully qualified names (ie. C<POSIX::SEEK_END>),
-or by giving an explicit import list. If you do neither, and opt for the
-default, C<use POSIX;> has to import I<553 symbols>.
-
-This document gives a condensed list of the features available in the POSIX
-module. Consult your operating system's manpages for general information on
-most features. Consult L<perlfunc> for functions which are noted as being
-identical to Perl's builtin functions.
-
-The first section describes POSIX functions from the 1003.1 specification.
-The second section describes some classes for signal objects, TTY objects,
-and other miscellaneous objects. The remaining sections list various
-constants and macros in an organization which roughly follows IEEE Std
-1003.1b-1993.
-
-=head1 CAVEATS
-
-A few functions are not implemented because they are C specific. If you
-attempt to call these, they will print a message telling you that they
-aren't implemented, and suggest using the Perl equivalent should one
-exist. For example, trying to access the setjmp() call will elicit the
-message "setjmp() is C-specific: use eval {} instead".
-
-Furthermore, some evil vendors will claim 1003.1 compliance, but in fact
-are not so: they will not pass the PCTS (POSIX Compliance Test Suites).
-For example, one vendor may not define EDEADLK, or the semantics of the
-errno values set by open(2) might not be quite right. Perl does not
-attempt to verify POSIX compliance. That means you can currently
-successfully say "use POSIX", and then later in your program you find
-that your vendor has been lax and there's no usable ICANON macro after
-all. This could be construed to be a bug.
-
-=head1 FUNCTIONS
-
-=over 8
-
-=item _exit
-
-This is identical to the C function C<_exit()>. It exits the program
-immediately which means among other things buffered I/O is B<not> flushed.
-
-Note that when using threads and in Linux this is B<not> a good way to
-exit a thread because in Linux processes and threads are kind of the
-same thing (Note: while this is the situation in early 2003 there are
-projects under way to have threads with more POSIXly semantics in Linux).
-If you want not to return from a thread, detach the thread.
-
-=item abort
-
-This is identical to the C function C<abort()>. It terminates the
-process with a C<SIGABRT> signal unless caught by a signal handler or
-if the handler does not return normally (it e.g. does a C<longjmp>).
-
-=item abs
-
-This is identical to Perl's builtin C<abs()> function, returning
-the absolute value of its numerical argument.
-
-=item access
-
-Determines the accessibility of a file.
-
- if( POSIX::access( "/", &POSIX::R_OK ) ){
- print "have read permission\n";
- }
-
-Returns C<undef> on failure. Note: do not use C<access()> for
-security purposes. Between the C<access()> call and the operation
-you are preparing for the permissions might change: a classic
-I<race condition>.
-
-=item acos
-
-This is identical to the C function C<acos()>, returning
-the arcus cosine of its numerical argument. See also L<Math::Trig>.
-
-=item alarm
-
-This is identical to Perl's builtin C<alarm()> function,
-either for arming or disarming the C<SIGARLM> timer.
-
-=item asctime
-
-This is identical to the C function C<asctime()>. It returns
-a string of the form
-
- "Fri Jun 2 18:22:13 2000\n\0"
-
-and it is called thusly
-
- $asctime = asctime($sec, $min, $hour, $mday, $mon, $year,
- $wday, $yday, $isdst);
-
-The C<$mon> is zero-based: January equals C<0>. The C<$year> is
-1900-based: 2001 equals C<101>. C<$wday> and C<$yday> default to zero
-(and are usually ignored anyway), and C<$isdst> defaults to -1.
-
-=item asin
-
-This is identical to the C function C<asin()>, returning
-the arcus sine of its numerical argument. See also L<Math::Trig>.
-
-=item assert
-
-Unimplemented, but you can use L<perlfunc/die> and the L<Carp> module
-to achieve similar things.
-
-=item atan
-
-This is identical to the C function C<atan()>, returning the
-arcus tangent of its numerical argument. See also L<Math::Trig>.
-
-=item atan2
-
-This is identical to Perl's builtin C<atan2()> function, returning
-the arcus tangent defined by its two numerical arguments, the I<y>
-coordinate and the I<x> coordinate. See also L<Math::Trig>.
-
-=item atexit
-
-atexit() is C-specific: use C<END {}> instead, see L<perlsub>.
-
-=item atof
-
-atof() is C-specific. Perl converts strings to numbers transparently.
-If you need to force a scalar to a number, add a zero to it.
-
-=item atoi
-
-atoi() is C-specific. Perl converts strings to numbers transparently.
-If you need to force a scalar to a number, add a zero to it.
-If you need to have just the integer part, see L<perlfunc/int>.
-
-=item atol
-
-atol() is C-specific. Perl converts strings to numbers transparently.
-If you need to force a scalar to a number, add a zero to it.
-If you need to have just the integer part, see L<perlfunc/int>.
-
-=item bsearch
-
-bsearch() not supplied. For doing binary search on wordlists,
-see L<Search::Dict>.
-
-=item calloc
-
-calloc() is C-specific. Perl does memory management transparently.
-
-=item ceil
-
-This is identical to the C function C<ceil()>, returning the smallest
-integer value greater than or equal to the given numerical argument.
-
-=item chdir
-
-This is identical to Perl's builtin C<chdir()> function, allowing
-one to change the working (default) directory, see L<perlfunc/chdir>.
-
-=item chmod
-
-This is identical to Perl's builtin C<chmod()> function, allowing
-one to change file and directory permissions, see L<perlfunc/chmod>.
-
-=item chown
-
-This is identical to Perl's builtin C<chown()> function, allowing one
-to change file and directory owners and groups, see L<perlfunc/chown>.
-
-=item clearerr
-
-Use the method C<IO::Handle::clearerr()> instead, to reset the error
-state (if any) and EOF state (if any) of the given stream.
-
-=item clock
-
-This is identical to the C function C<clock()>, returning the
-amount of spent processor time in microseconds.
-
-=item close
-
-Close the file. This uses file descriptors such as those obtained by calling
-C<POSIX::open>.
-
- $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
- POSIX::close( $fd );
-
-Returns C<undef> on failure.
-
-See also L<perlfunc/close>.
-
-=item closedir
-
-This is identical to Perl's builtin C<closedir()> function for closing
-a directory handle, see L<perlfunc/closedir>.
-
-=item cos
-
-This is identical to Perl's builtin C<cos()> function, for returning
-the cosine of its numerical argument, see L<perlfunc/cos>.
-See also L<Math::Trig>.
-
-=item cosh
-
-This is identical to the C function C<cosh()>, for returning
-the hyperbolic cosine of its numeric argument. See also L<Math::Trig>.
-
-=item creat
-
-Create a new file. This returns a file descriptor like the ones returned by
-C<POSIX::open>. Use C<POSIX::close> to close the file.
-
- $fd = POSIX::creat( "foo", 0611 );
- POSIX::close( $fd );
-
-See also L<perlfunc/sysopen> and its C<O_CREAT> flag.
-
-=item ctermid
-
-Generates the path name for the controlling terminal.
-
- $path = POSIX::ctermid();
-
-=item ctime
-
-This is identical to the C function C<ctime()> and equivalent
-to C<asctime(localtime(...))>, see L</asctime> and L</localtime>.
-
-=item cuserid
-
-Get the login name of the owner of the current process.
-
- $name = POSIX::cuserid();
-
-=item difftime
-
-This is identical to the C function C<difftime()>, for returning
-the time difference (in seconds) between two times (as returned
-by C<time()>), see L</time>.
-
-=item div
-
-div() is C-specific, use L<perlfunc/int> on the usual C</> division and
-the modulus C<%>.
-
-=item dup
-
-This is similar to the C function C<dup()>, for duplicating a file
-descriptor.
-
-This uses file descriptors such as those obtained by calling
-C<POSIX::open>.
-
-Returns C<undef> on failure.
-
-=item dup2
-
-This is similar to the C function C<dup2()>, for duplicating a file
-descriptor to an another known file descriptor.
-
-This uses file descriptors such as those obtained by calling
-C<POSIX::open>.
-
-Returns C<undef> on failure.
-
-=item errno
-
-Returns the value of errno.
-
- $errno = POSIX::errno();
-
-This identical to the numerical values of the C<$!>, see L<perlvar/$ERRNO>.
-
-=item execl
-
-execl() is C-specific, see L<perlfunc/exec>.
-
-=item execle
-
-execle() is C-specific, see L<perlfunc/exec>.
-
-=item execlp
-
-execlp() is C-specific, see L<perlfunc/exec>.
-
-=item execv
-
-execv() is C-specific, see L<perlfunc/exec>.
-
-=item execve
-
-execve() is C-specific, see L<perlfunc/exec>.
-
-=item execvp
-
-execvp() is C-specific, see L<perlfunc/exec>.
-
-=item exit
-
-This is identical to Perl's builtin C<exit()> function for exiting the
-program, see L<perlfunc/exit>.
-
-=item exp
-
-This is identical to Perl's builtin C<exp()> function for
-returning the exponent (I<e>-based) of the numerical argument,
-see L<perlfunc/exp>.
-
-=item fabs
-
-This is identical to Perl's builtin C<abs()> function for returning
-the absolute value of the numerical argument, see L<perlfunc/abs>.
-
-=item fclose
-
-Use method C<IO::Handle::close()> instead, or see L<perlfunc/close>.
-
-=item fcntl
-
-This is identical to Perl's builtin C<fcntl()> function,
-see L<perlfunc/fcntl>.
-
-=item fdopen
-
-Use method C<IO::Handle::new_from_fd()> instead, or see L<perlfunc/open>.
-
-=item feof
-
-Use method C<IO::Handle::eof()> instead, or see L<perlfunc/eof>.
-
-=item ferror
-
-Use method C<IO::Handle::error()> instead.
-
-=item fflush
-
-Use method C<IO::Handle::flush()> instead.
-See also L<perlvar/$OUTPUT_AUTOFLUSH>.
-
-=item fgetc
-
-Use method C<IO::Handle::getc()> instead, or see L<perlfunc/read>.
-
-=item fgetpos
-
-Use method C<IO::Seekable::getpos()> instead, or see L<perlfunc/seek>.
-
-=item fgets
-
-Use method C<IO::Handle::gets()> instead. Similar to E<lt>E<gt>, also known
-as L<perlfunc/readline>.
-
-=item fileno
-
-Use method C<IO::Handle::fileno()> instead, or see L<perlfunc/fileno>.
-
-=item floor
-
-This is identical to the C function C<floor()>, returning the largest
-integer value less than or equal to the numerical argument.
-
-=item fmod
-
-This is identical to the C function C<fmod()>.
-
- $r = fmod($x, $y);
-
-It returns the remainder C<$r = $x - $n*$y>, where C<$n = trunc($x/$y)>.
-The C<$r> has the same sign as C<$x> and magnitude (absolute value)
-less than the magnitude of C<$y>.
-
-=item fopen
-
-Use method C<IO::File::open()> instead, or see L<perlfunc/open>.
-
-=item fork
-
-This is identical to Perl's builtin C<fork()> function
-for duplicating the current process, see L<perlfunc/fork>
-and L<perlfork> if you are in Windows.
-
-=item fpathconf
-
-Retrieves the value of a configurable limit on a file or directory. This
-uses file descriptors such as those obtained by calling C<POSIX::open>.
-
-The following will determine the maximum length of the longest allowable
-pathname on the filesystem which holds C</var/foo>.
-
- $fd = POSIX::open( "/var/foo", &POSIX::O_RDONLY );
- $path_max = POSIX::fpathconf( $fd, &POSIX::_PC_PATH_MAX );
-
-Returns C<undef> on failure.
-
-=item fprintf
-
-fprintf() is C-specific, see L<perlfunc/printf> instead.
-
-=item fputc
-
-fputc() is C-specific, see L<perlfunc/print> instead.
-
-=item fputs
-
-fputs() is C-specific, see L<perlfunc/print> instead.
-
-=item fread
-
-fread() is C-specific, see L<perlfunc/read> instead.
-
-=item free
-
-free() is C-specific. Perl does memory management transparently.
-
-=item freopen
-
-freopen() is C-specific, see L<perlfunc/open> instead.
-
-=item frexp
-
-Return the mantissa and exponent of a floating-point number.
-
- ($mantissa, $exponent) = POSIX::frexp( 1.234e56 );
-
-=item fscanf
-
-fscanf() is C-specific, use E<lt>E<gt> and regular expressions instead.
-
-=item fseek
-
-Use method C<IO::Seekable::seek()> instead, or see L<perlfunc/seek>.
-
-=item fsetpos
-
-Use method C<IO::Seekable::setpos()> instead, or seek L<perlfunc/seek>.
-
-=item fstat
-
-Get file status. This uses file descriptors such as those obtained by
-calling C<POSIX::open>. The data returned is identical to the data from
-Perl's builtin C<stat> function.
-
- $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
- @stats = POSIX::fstat( $fd );
-
-=item fsync
-
-Use method C<IO::Handle::sync()> instead.
-
-=item ftell
-
-Use method C<IO::Seekable::tell()> instead, or see L<perlfunc/tell>.
-
-=item fwrite
-
-fwrite() is C-specific, see L<perlfunc/print> instead.
-
-=item getc
-
-This is identical to Perl's builtin C<getc()> function,
-see L<perlfunc/getc>.
-
-=item getchar
-
-Returns one character from STDIN. Identical to Perl's C<getc()>,
-see L<perlfunc/getc>.
-
-=item getcwd
-
-Returns the name of the current working directory.
-See also L<Cwd>.
-
-=item getegid
-
-Returns the effective group identifier. Similar to Perl' s builtin
-variable C<$(>, see L<perlvar/$EGID>.
-
-=item getenv
-
-Returns the value of the specified environment variable.
-The same information is available through the C<%ENV> array.
-
-=item geteuid
-
-Returns the effective user identifier. Identical to Perl's builtin C<$E<gt>>
-variable, see L<perlvar/$EUID>.
-
-=item getgid
-
-Returns the user's real group identifier. Similar to Perl's builtin
-variable C<$)>, see L<perlvar/$GID>.
-
-=item getgrgid
-
-This is identical to Perl's builtin C<getgrgid()> function for
-returning group entries by group identifiers, see
-L<perlfunc/getgrgid>.
-
-=item getgrnam
-
-This is identical to Perl's builtin C<getgrnam()> function for
-returning group entries by group names, see L<perlfunc/getgrnam>.
-
-=item getgroups
-
-Returns the ids of the user's supplementary groups. Similar to Perl's
-builtin variable C<$)>, see L<perlvar/$GID>.
-
-=item getlogin
-
-This is identical to Perl's builtin C<getlogin()> function for
-returning the user name associated with the current session, see
-L<perlfunc/getlogin>.
-
-=item getpgrp
-
-This is identical to Perl's builtin C<getpgrp()> function for
-returning the process group identifier of the current process, see
-L<perlfunc/getpgrp>.
-
-=item getpid
-
-Returns the process identifier. Identical to Perl's builtin
-variable C<$$>, see L<perlvar/$PID>.
-
-=item getppid
-
-This is identical to Perl's builtin C<getppid()> function for
-returning the process identifier of the parent process of the current
-process , see L<perlfunc/getppid>.
-
-=item getpwnam
-
-This is identical to Perl's builtin C<getpwnam()> function for
-returning user entries by user names, see L<perlfunc/getpwnam>.
-
-=item getpwuid
-
-This is identical to Perl's builtin C<getpwuid()> function for
-returning user entries by user identifiers, see L<perlfunc/getpwuid>.
-
-=item gets
-
-Returns one line from C<STDIN>, similar to E<lt>E<gt>, also known
-as the C<readline()> function, see L<perlfunc/readline>.
-
-B<NOTE>: if you have C programs that still use C<gets()>, be very
-afraid. The C<gets()> function is a source of endless grief because
-it has no buffer overrun checks. It should B<never> be used. The
-C<fgets()> function should be preferred instead.
-
-=item getuid
-
-Returns the user's identifier. Identical to Perl's builtin C<$E<lt>> variable,
-see L<perlvar/$UID>.
-
-=item gmtime
-
-This is identical to Perl's builtin C<gmtime()> function for
-converting seconds since the epoch to a date in Greenwich Mean Time,
-see L<perlfunc/gmtime>.
-
-=item isalnum
-
-This is identical to the C function, except that it can apply to a
-single character or to a whole string. Note that locale settings may
-affect what characters are considered C<isalnum>. Does not work on
-Unicode characters code point 256 or higher. Consider using regular
-expressions and the C</[[:alnum:]]/> construct instead, or possibly
-the C</\w/> construct.
-
-=item isalpha
-
-This is identical to the C function, except that it can apply to
-a single character or to a whole string. Note that locale settings
-may affect what characters are considered C<isalpha>. Does not work
-on Unicode characters code point 256 or higher. Consider using regular
-expressions and the C</[[:alpha:]]/> construct instead.
-
-=item isatty
-
-Returns a boolean indicating whether the specified filehandle is connected
-to a tty. Similar to the C<-t> operator, see L<perlfunc/-X>.
-
-=item iscntrl
-
-This is identical to the C function, except that it can apply to
-a single character or to a whole string. Note that locale settings
-may affect what characters are considered C<iscntrl>. Does not work
-on Unicode characters code point 256 or higher. Consider using regular
-expressions and the C</[[:cntrl:]]/> construct instead.
-
-=item isdigit
-
-This is identical to the C function, except that it can apply to
-a single character or to a whole string. Note that locale settings
-may affect what characters are considered C<isdigit> (unlikely, but
-still possible). Does not work on Unicode characters code point 256
-or higher. Consider using regular expressions and the C</[[:digit:]]/>
-construct instead, or the C</\d/> construct.
-
-=item isgraph
-
-This is identical to the C function, except that it can apply to
-a single character or to a whole string. Note that locale settings
-may affect what characters are considered C<isgraph>. Does not work
-on Unicode characters code point 256 or higher. Consider using regular
-expressions and the C</[[:graph:]]/> construct instead.
-
-=item islower
-
-This is identical to the C function, except that it can apply to
-a single character or to a whole string. Note that locale settings
-may affect what characters are considered C<islower>. Does not work
-on Unicode characters code point 256 or higher. Consider using regular
-expressions and the C</[[:lower:]]/> construct instead. Do B<not> use
-C</[a-z]/>.
-
-=item isprint
-
-This is identical to the C function, except that it can apply to
-a single character or to a whole string. Note that locale settings
-may affect what characters are considered C<isprint>. Does not work
-on Unicode characters code point 256 or higher. Consider using regular
-expressions and the C</[[:print:]]/> construct instead.
-
-=item ispunct
-
-This is identical to the C function, except that it can apply to
-a single character or to a whole string. Note that locale settings
-may affect what characters are considered C<ispunct>. Does not work
-on Unicode characters code point 256 or higher. Consider using regular
-expressions and the C</[[:punct:]]/> construct instead.
-
-=item isspace
-
-This is identical to the C function, except that it can apply to
-a single character or to a whole string. Note that locale settings
-may affect what characters are considered C<isspace>. Does not work
-on Unicode characters code point 256 or higher. Consider using regular
-expressions and the C</[[:space:]]/> construct instead, or the C</\s/>
-construct. (Note that C</\s/> and C</[[:space:]]/> are slightly
-different in that C</[[:space:]]/> can normally match a vertical tab,
-while C</\s/> does not.)
-
-=item isupper
-
-This is identical to the C function, except that it can apply to
-a single character or to a whole string. Note that locale settings
-may affect what characters are considered C<isupper>. Does not work
-on Unicode characters code point 256 or higher. Consider using regular
-expressions and the C</[[:upper:]]/> construct instead. Do B<not> use
-C</[A-Z]/>.
-
-=item isxdigit
-
-This is identical to the C function, except that it can apply to a single
-character or to a whole string. Note that locale settings may affect what
-characters are considered C<isxdigit> (unlikely, but still possible).
-Does not work on Unicode characters code point 256 or higher.
-Consider using regular expressions and the C</[[:xdigit:]]/>
-construct instead, or simply C</[0-9a-f]/i>.
-
-=item kill
-
-This is identical to Perl's builtin C<kill()> function for sending
-signals to processes (often to terminate them), see L<perlfunc/kill>.
-
-=item labs
-
-(For returning absolute values of long integers.)
-labs() is C-specific, see L<perlfunc/abs> instead.
-
-=item lchown
-
-This is identical to the C function, except the order of arguments is
-consistent with Perl's builtin C<chown()> with the added restriction
-of only one path, not an list of paths. Does the same thing as the
-C<chown()> function but changes the owner of a symbolic link instead
-of the file the symbolic link points to.
-
-=item ldexp
-
-This is identical to the C function C<ldexp()>
-for multiplying floating point numbers with powers of two.
-
- $x_quadrupled = POSIX::ldexp($x, 2);
-
-=item ldiv
-
-(For computing dividends of long integers.)
-ldiv() is C-specific, use C</> and C<int()> instead.
-
-=item link
-
-This is identical to Perl's builtin C<link()> function
-for creating hard links into files, see L<perlfunc/link>.
-
-=item localeconv
-
-Get numeric formatting information. Returns a reference to a hash
-containing the current locale formatting values.
-
-Here is how to query the database for the B<de> (Deutsch or German) locale.
-
- $loc = POSIX::setlocale( &POSIX::LC_ALL, "de" );
- print "Locale = $loc\n";
- $lconv = POSIX::localeconv();
- print "decimal_point = ", $lconv->{decimal_point}, "\n";
- print "thousands_sep = ", $lconv->{thousands_sep}, "\n";
- print "grouping = ", $lconv->{grouping}, "\n";
- print "int_curr_symbol = ", $lconv->{int_curr_symbol}, "\n";
- print "currency_symbol = ", $lconv->{currency_symbol}, "\n";
- print "mon_decimal_point = ", $lconv->{mon_decimal_point}, "\n";
- print "mon_thousands_sep = ", $lconv->{mon_thousands_sep}, "\n";
- print "mon_grouping = ", $lconv->{mon_grouping}, "\n";
- print "positive_sign = ", $lconv->{positive_sign}, "\n";
- print "negative_sign = ", $lconv->{negative_sign}, "\n";
- print "int_frac_digits = ", $lconv->{int_frac_digits}, "\n";
- print "frac_digits = ", $lconv->{frac_digits}, "\n";
- print "p_cs_precedes = ", $lconv->{p_cs_precedes}, "\n";
- print "p_sep_by_space = ", $lconv->{p_sep_by_space}, "\n";
- print "n_cs_precedes = ", $lconv->{n_cs_precedes}, "\n";
- print "n_sep_by_space = ", $lconv->{n_sep_by_space}, "\n";
- print "p_sign_posn = ", $lconv->{p_sign_posn}, "\n";
- print "n_sign_posn = ", $lconv->{n_sign_posn}, "\n";
-
-=item localtime
-
-This is identical to Perl's builtin C<localtime()> function for
-converting seconds since the epoch to a date see L<perlfunc/localtime>.
-
-=item log
-
-This is identical to Perl's builtin C<log()> function,
-returning the natural (I<e>-based) logarithm of the numerical argument,
-see L<perlfunc/log>.
-
-=item log10
-
-This is identical to the C function C<log10()>,
-returning the 10-base logarithm of the numerical argument.
-You can also use
-
- sub log10 { log($_[0]) / log(10) }
-
-or
-
- sub log10 { log($_[0]) / 2.30258509299405 }
-
-or
-
- sub log10 { log($_[0]) * 0.434294481903252 }
-
-=item longjmp
-
-longjmp() is C-specific: use L<perlfunc/die> instead.
-
-=item lseek
-
-Move the file's read/write position. This uses file descriptors such as
-those obtained by calling C<POSIX::open>.
-
- $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
- $off_t = POSIX::lseek( $fd, 0, &POSIX::SEEK_SET );
-
-Returns C<undef> on failure.
-
-=item malloc
-
-malloc() is C-specific. Perl does memory management transparently.
-
-=item mblen
-
-This is identical to the C function C<mblen()>.
-Perl does not have any support for the wide and multibyte
-characters of the C standards, so this might be a rather
-useless function.
-
-=item mbstowcs
-
-This is identical to the C function C<mbstowcs()>.
-Perl does not have any support for the wide and multibyte
-characters of the C standards, so this might be a rather
-useless function.
-
-=item mbtowc
-
-This is identical to the C function C<mbtowc()>.
-Perl does not have any support for the wide and multibyte
-characters of the C standards, so this might be a rather
-useless function.
-
-=item memchr
-
-memchr() is C-specific, see L<perlfunc/index> instead.
-
-=item memcmp
-
-memcmp() is C-specific, use C<eq> instead, see L<perlop>.
-
-=item memcpy
-
-memcpy() is C-specific, use C<=>, see L<perlop>, or see L<perlfunc/substr>.
-
-=item memmove
-
-memmove() is C-specific, use C<=>, see L<perlop>, or see L<perlfunc/substr>.
-
-=item memset
-
-memset() is C-specific, use C<x> instead, see L<perlop>.
-
-=item mkdir
-
-This is identical to Perl's builtin C<mkdir()> function
-for creating directories, see L<perlfunc/mkdir>.
-
-=item mkfifo
-
-This is similar to the C function C<mkfifo()> for creating
-FIFO special files.
-
- if (mkfifo($path, $mode)) { ....
-
-Returns C<undef> on failure. The C<$mode> is similar to the
-mode of C<mkdir()>, see L<perlfunc/mkdir>, though for C<mkfifo>
-you B<must> specify the C<$mode>.
-
-=item mktime
-
-Convert date/time info to a calendar time.
-
-Synopsis:
-
- mktime(sec, min, hour, mday, mon, year, wday = 0, yday = 0, isdst = -1)
-
-The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero.
-I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The
-year (C<year>) is given in years since 1900. I.e. The year 1995 is 95; the
-year 2001 is 101. Consult your system's C<mktime()> manpage for details
-about these and the other arguments.
-
-Calendar time for December 12, 1995, at 10:30 am.
-
- $time_t = POSIX::mktime( 0, 30, 10, 12, 11, 95 );
- print "Date = ", POSIX::ctime($time_t);
-
-Returns C<undef> on failure.
-
-=item modf
-
-Return the integral and fractional parts of a floating-point number.
-
- ($fractional, $integral) = POSIX::modf( 3.14 );
-
-=item nice
-
-This is similar to the C function C<nice()>, for changing
-the scheduling preference of the current process. Positive
-arguments mean more polite process, negative values more
-needy process. Normal user processes can only be more polite.
-
-Returns C<undef> on failure.
-
-=item offsetof
-
-offsetof() is C-specific, you probably want to see L<perlfunc/pack> instead.
-
-=item open
-
-Open a file for reading for writing. This returns file descriptors, not
-Perl filehandles. Use C<POSIX::close> to close the file.
-
-Open a file read-only with mode 0666.
-
- $fd = POSIX::open( "foo" );
-
-Open a file for read and write.
-
- $fd = POSIX::open( "foo", &POSIX::O_RDWR );
-
-Open a file for write, with truncation.
-
- $fd = POSIX::open( "foo", &POSIX::O_WRONLY | &POSIX::O_TRUNC );
-
-Create a new file with mode 0640. Set up the file for writing.
-
- $fd = POSIX::open( "foo", &POSIX::O_CREAT | &POSIX::O_WRONLY, 0640 );
-
-Returns C<undef> on failure.
-
-See also L<perlfunc/sysopen>.
-
-=item opendir
-
-Open a directory for reading.
-
- $dir = POSIX::opendir( "/var" );
- @files = POSIX::readdir( $dir );
- POSIX::closedir( $dir );
-
-Returns C<undef> on failure.
-
-=item pathconf
-
-Retrieves the value of a configurable limit on a file or directory.
-
-The following will determine the maximum length of the longest allowable
-pathname on the filesystem which holds C</var>.
-
- $path_max = POSIX::pathconf( "/var", &POSIX::_PC_PATH_MAX );
-
-Returns C<undef> on failure.
-
-=item pause
-
-This is similar to the C function C<pause()>, which suspends
-the execution of the current process until a signal is received.
-
-Returns C<undef> on failure.
-
-=item perror
-
-This is identical to the C function C<perror()>, which outputs to the
-standard error stream the specified message followed by ": " and the
-current error string. Use the C<warn()> function and the C<$!>
-variable instead, see L<perlfunc/warn> and L<perlvar/$ERRNO>.
-
-=item pipe
-
-Create an interprocess channel. This returns file descriptors like those
-returned by C<POSIX::open>.
-
- my ($read, $write) = POSIX::pipe();
- POSIX::write( $write, "hello", 5 );
- POSIX::read( $read, $buf, 5 );
-
-See also L<perlfunc/pipe>.
-
-=item pow
-
-Computes C<$x> raised to the power C<$exponent>.
-
- $ret = POSIX::pow( $x, $exponent );
-
-You can also use the C<**> operator, see L<perlop>.
-
-=item printf
-
-Formats and prints the specified arguments to STDOUT.
-See also L<perlfunc/printf>.
-
-=item putc
-
-putc() is C-specific, see L<perlfunc/print> instead.
-
-=item putchar
-
-putchar() is C-specific, see L<perlfunc/print> instead.
-
-=item puts
-
-puts() is C-specific, see L<perlfunc/print> instead.
-
-=item qsort
-
-qsort() is C-specific, see L<perlfunc/sort> instead.
-
-=item raise
-
-Sends the specified signal to the current process.
-See also L<perlfunc/kill> and the C<$$> in L<perlvar/$PID>.
-
-=item rand
-
-C<rand()> is non-portable, see L<perlfunc/rand> instead.
-
-=item read
-
-Read from a file. This uses file descriptors such as those obtained by
-calling C<POSIX::open>. If the buffer C<$buf> is not large enough for the
-read then Perl will extend it to make room for the request.
-
- $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
- $bytes = POSIX::read( $fd, $buf, 3 );
-
-Returns C<undef> on failure.
-
-See also L<perlfunc/sysread>.
-
-=item readdir
-
-This is identical to Perl's builtin C<readdir()> function
-for reading directory entries, see L<perlfunc/readdir>.
-
-=item realloc
-
-realloc() is C-specific. Perl does memory management transparently.
-
-=item remove
-
-This is identical to Perl's builtin C<unlink()> function
-for removing files, see L<perlfunc/unlink>.
-
-=item rename
-
-This is identical to Perl's builtin C<rename()> function
-for renaming files, see L<perlfunc/rename>.
-
-=item rewind
-
-Seeks to the beginning of the file.
-
-=item rewinddir
-
-This is identical to Perl's builtin C<rewinddir()> function for
-rewinding directory entry streams, see L<perlfunc/rewinddir>.
-
-=item rmdir
-
-This is identical to Perl's builtin C<rmdir()> function
-for removing (empty) directories, see L<perlfunc/rmdir>.
-
-=item scanf
-
-scanf() is C-specific, use E<lt>E<gt> and regular expressions instead,
-see L<perlre>.
-
-=item setgid
-
-Sets the real group identifier and the effective group identifier for
-this process. Similar to assigning a value to the Perl's builtin
-C<$)> variable, see L<perlvar/$EGID>, except that the latter
-will change only the real user identifier, and that the setgid()
-uses only a single numeric argument, as opposed to a space-separated
-list of numbers.
-
-=item setjmp
-
-C<setjmp()> is C-specific: use C<eval {}> instead,
-see L<perlfunc/eval>.
-
-=item setlocale
-
-Modifies and queries program's locale. The following examples assume
-
- use POSIX qw(setlocale LC_ALL LC_CTYPE);
-
-has been issued.
-
-The following will set the traditional UNIX system locale behavior
-(the second argument C<"C">).
-
- $loc = setlocale( LC_ALL, "C" );
-
-The following will query the current LC_CTYPE category. (No second
-argument means 'query'.)
-
- $loc = setlocale( LC_CTYPE );
-
-The following will set the LC_CTYPE behaviour according to the locale
-environment variables (the second argument C<"">).
-Please see your systems C<setlocale(3)> documentation for the locale
-environment variables' meaning or consult L<perllocale>.
-
- $loc = setlocale( LC_CTYPE, "" );
-
-The following will set the LC_COLLATE behaviour to Argentinian
-Spanish. B<NOTE>: The naming and availability of locales depends on
-your operating system. Please consult L<perllocale> for how to find
-out which locales are available in your system.
-
- $loc = setlocale( LC_COLLATE, "es_AR.ISO8859-1" );
-
-=item setpgid
-
-This is similar to the C function C<setpgid()> for
-setting the process group identifier of the current process.
-
-Returns C<undef> on failure.
-
-=item setsid
-
-This is identical to the C function C<setsid()> for
-setting the session identifier of the current process.
-
-=item setuid
-
-Sets the real user identifier and the effective user identifier for
-this process. Similar to assigning a value to the Perl's builtin
-C<$E<lt>> variable, see L<perlvar/$UID>, except that the latter
-will change only the real user identifier.
-
-=item sigaction
-
-Detailed signal management. This uses C<POSIX::SigAction> objects for
-the C<action> and C<oldaction> arguments (the oldaction can also be
-just a hash reference). Consult your system's C<sigaction> manpage
-for details, see also C<POSIX::SigRt>.
-
-Synopsis:
-
- sigaction(signal, action, oldaction = 0)
-
-Returns C<undef> on failure. The C<signal> must be a number (like
-SIGHUP), not a string (like "SIGHUP"), though Perl does try hard
-to understand you.
-
-If you use the SA_SIGINFO flag, the signal handler will in addition to
-the first argument, the signal name, also receive a second argument, a
-hash reference, inside which are the following keys with the following
-semantics, as defined by POSIX/SUSv3:
-
- signo the signal number
- errno the error number
- code if this is zero or less, the signal was sent by
- a user process and the uid and pid make sense,
- otherwise the signal was sent by the kernel
-
-The following are also defined by POSIX/SUSv3, but unfortunately
-not very widely implemented:
-
- pid the process id generating the signal
- uid the uid of the process id generating the signal
- status exit value or signal for SIGCHLD
- band band event for SIGPOLL
-
-A third argument is also passed to the handler, which contains a copy
-of the raw binary contents of the siginfo structure: if a system has
-some non-POSIX fields, this third argument is where to unpack() them
-from.
-
-Note that not all siginfo values make sense simultaneously (some are
-valid only for certain signals, for example), and not all values make
-sense from Perl perspective, you should to consult your system's
-C<sigaction> and possibly also C<siginfo> documentation.
-
-=item siglongjmp
-
-siglongjmp() is C-specific: use L<perlfunc/die> instead.
-
-=item sigpending
-
-Examine signals that are blocked and pending. This uses C<POSIX::SigSet>
-objects for the C<sigset> argument. Consult your system's C<sigpending>
-manpage for details.
-
-Synopsis:
-
- sigpending(sigset)
-
-Returns C<undef> on failure.
-
-=item sigprocmask
-
-Change and/or examine calling process's signal mask. This uses
-C<POSIX::SigSet> objects for the C<sigset> and C<oldsigset> arguments.
-Consult your system's C<sigprocmask> manpage for details.
-
-Synopsis:
-
- sigprocmask(how, sigset, oldsigset = 0)
-
-Returns C<undef> on failure.
-
-Note that you can't reliably block or unblock a signal from its own signal
-handler if you're using safe signals. Other signals can be blocked or unblocked
-reliably.
-
-=item sigsetjmp
-
-C<sigsetjmp()> is C-specific: use C<eval {}> instead,
-see L<perlfunc/eval>.
-
-=item sigsuspend
-
-Install a signal mask and suspend process until signal arrives. This uses
-C<POSIX::SigSet> objects for the C<signal_mask> argument. Consult your
-system's C<sigsuspend> manpage for details.
-
-Synopsis:
-
- sigsuspend(signal_mask)
-
-Returns C<undef> on failure.
-
-=item sin
-
-This is identical to Perl's builtin C<sin()> function
-for returning the sine of the numerical argument,
-see L<perlfunc/sin>. See also L<Math::Trig>.
-
-=item sinh
-
-This is identical to the C function C<sinh()>
-for returning the hyperbolic sine of the numerical argument.
-See also L<Math::Trig>.
-
-=item sleep
-
-This is functionally identical to Perl's builtin C<sleep()> function
-for suspending the execution of the current for process for certain
-number of seconds, see L<perlfunc/sleep>. There is one significant
-difference, however: C<POSIX::sleep()> returns the number of
-B<unslept> seconds, while the C<CORE::sleep()> returns the
-number of slept seconds.
-
-=item sprintf
-
-This is similar to Perl's builtin C<sprintf()> function
-for returning a string that has the arguments formatted as requested,
-see L<perlfunc/sprintf>.
-
-=item sqrt
-
-This is identical to Perl's builtin C<sqrt()> function.
-for returning the square root of the numerical argument,
-see L<perlfunc/sqrt>.
-
-=item srand
-
-Give a seed the pseudorandom number generator, see L<perlfunc/srand>.
-
-=item sscanf
-
-sscanf() is C-specific, use regular expressions instead,
-see L<perlre>.
-
-=item stat
-
-This is identical to Perl's builtin C<stat()> function
-for returning information about files and directories.
-
-=item strcat
-
-strcat() is C-specific, use C<.=> instead, see L<perlop>.
-
-=item strchr
-
-strchr() is C-specific, see L<perlfunc/index> instead.
-
-=item strcmp
-
-strcmp() is C-specific, use C<eq> or C<cmp> instead, see L<perlop>.
-
-=item strcoll
-
-This is identical to the C function C<strcoll()>
-for collating (comparing) strings transformed using
-the C<strxfrm()> function. Not really needed since
-Perl can do this transparently, see L<perllocale>.
-
-=item strcpy
-
-strcpy() is C-specific, use C<=> instead, see L<perlop>.
-
-=item strcspn
-
-strcspn() is C-specific, use regular expressions instead,
-see L<perlre>.
-
-=item strerror
-
-Returns the error string for the specified errno.
-Identical to the string form of the C<$!>, see L<perlvar/$ERRNO>.
-
-=item strftime
-
-Convert date and time information to string. Returns the string.
-
-Synopsis:
-
- strftime(fmt, sec, min, hour, mday, mon, year, wday = -1, yday = -1, isdst = -1)
-
-The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero.
-I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The
-year (C<year>) is given in years since 1900. I.e., the year 1995 is 95; the
-year 2001 is 101. Consult your system's C<strftime()> manpage for details
-about these and the other arguments.
-
-If you want your code to be portable, your format (C<fmt>) argument
-should use only the conversion specifiers defined by the ANSI C
-standard (C89, to play safe). These are C<aAbBcdHIjmMpSUwWxXyYZ%>.
-But even then, the B<results> of some of the conversion specifiers are
-non-portable. For example, the specifiers C<aAbBcpZ> change according
-to the locale settings of the user, and both how to set locales (the
-locale names) and what output to expect are non-standard.
-The specifier C<c> changes according to the timezone settings of the
-user and the timezone computation rules of the operating system.
-The C<Z> specifier is notoriously unportable since the names of
-timezones are non-standard. Sticking to the numeric specifiers is the
-safest route.
-
-The given arguments are made consistent as though by calling
-C<mktime()> before calling your system's C<strftime()> function,
-except that the C<isdst> value is not affected.
-
-The string for Tuesday, December 12, 1995.
-
- $str = POSIX::strftime( "%A, %B %d, %Y", 0, 0, 0, 12, 11, 95, 2 );
- print "$str\n";
-
-=item strlen
-
-strlen() is C-specific, use C<length()> instead, see L<perlfunc/length>.
-
-=item strncat
-
-strncat() is C-specific, use C<.=> instead, see L<perlop>.
-
-=item strncmp
-
-strncmp() is C-specific, use C<eq> instead, see L<perlop>.
-
-=item strncpy
-
-strncpy() is C-specific, use C<=> instead, see L<perlop>.
-
-=item strpbrk
-
-strpbrk() is C-specific, use regular expressions instead,
-see L<perlre>.
-
-=item strrchr
-
-strrchr() is C-specific, see L<perlfunc/rindex> instead.
-
-=item strspn
-
-strspn() is C-specific, use regular expressions instead,
-see L<perlre>.
-
-=item strstr
-
-This is identical to Perl's builtin C<index()> function,
-see L<perlfunc/index>.
-
-=item strtod
-
-String to double translation. Returns the parsed number and the number
-of characters in the unparsed portion of the string. Truly
-POSIX-compliant systems set $! ($ERRNO) to indicate a translation
-error, so clear $! before calling strtod. However, non-POSIX systems
-may not check for overflow, and therefore will never set $!.
-
-strtod should respect any POSIX I<setlocale()> settings.
-
-To parse a string $str as a floating point number use
-
- $! = 0;
- ($num, $n_unparsed) = POSIX::strtod($str);
-
-The second returned item and $! can be used to check for valid input:
-
- if (($str eq '') || ($n_unparsed != 0) || $!) {
- die "Non-numeric input $str" . ($! ? ": $!\n" : "\n");
- }
-
-When called in a scalar context strtod returns the parsed number.
-
-=item strtok
-
-strtok() is C-specific, use regular expressions instead, see
-L<perlre>, or L<perlfunc/split>.
-
-=item strtol
-
-String to (long) integer translation. Returns the parsed number and
-the number of characters in the unparsed portion of the string. Truly
-POSIX-compliant systems set $! ($ERRNO) to indicate a translation
-error, so clear $! before calling strtol. However, non-POSIX systems
-may not check for overflow, and therefore will never set $!.
-
-strtol should respect any POSIX I<setlocale()> settings.
-
-To parse a string $str as a number in some base $base use
-
- $! = 0;
- ($num, $n_unparsed) = POSIX::strtol($str, $base);
-
-The base should be zero or between 2 and 36, inclusive. When the base
-is zero or omitted strtol will use the string itself to determine the
-base: a leading "0x" or "0X" means hexadecimal; a leading "0" means
-octal; any other leading characters mean decimal. Thus, "1234" is
-parsed as a decimal number, "01234" as an octal number, and "0x1234"
-as a hexadecimal number.
-
-The second returned item and $! can be used to check for valid input:
-
- if (($str eq '') || ($n_unparsed != 0) || !$!) {
- die "Non-numeric input $str" . $! ? ": $!\n" : "\n";
- }
-
-When called in a scalar context strtol returns the parsed number.
-
-=item strtoul
-
-String to unsigned (long) integer translation. strtoul() is identical
-to strtol() except that strtoul() only parses unsigned integers. See
-L</strtol> for details.
-
-Note: Some vendors supply strtod() and strtol() but not strtoul().
-Other vendors that do supply strtoul() parse "-1" as a valid value.
-
-=item strxfrm
-
-String transformation. Returns the transformed string.
-
- $dst = POSIX::strxfrm( $src );
-
-Used in conjunction with the C<strcoll()> function, see L</strcoll>.
-
-Not really needed since Perl can do this transparently, see
-L<perllocale>.
-
-=item sysconf
-
-Retrieves values of system configurable variables.
-
-The following will get the machine's clock speed.
-
- $clock_ticks = POSIX::sysconf( &POSIX::_SC_CLK_TCK );
-
-Returns C<undef> on failure.
-
-=item system
-
-This is identical to Perl's builtin C<system()> function, see
-L<perlfunc/system>.
-
-=item tan
-
-This is identical to the C function C<tan()>, returning the
-tangent of the numerical argument. See also L<Math::Trig>.
-
-=item tanh
-
-This is identical to the C function C<tanh()>, returning the
-hyperbolic tangent of the numerical argument. See also L<Math::Trig>.
-
-=item tcdrain
-
-This is similar to the C function C<tcdrain()> for draining
-the output queue of its argument stream.
-
-Returns C<undef> on failure.
-
-=item tcflow
-
-This is similar to the C function C<tcflow()> for controlling
-the flow of its argument stream.
-
-Returns C<undef> on failure.
-
-=item tcflush
-
-This is similar to the C function C<tcflush()> for flushing
-the I/O buffers of its argument stream.
-
-Returns C<undef> on failure.
-
-=item tcgetpgrp
-
-This is identical to the C function C<tcgetpgrp()> for returning the
-process group identifier of the foreground process group of the controlling
-terminal.
-
-=item tcsendbreak
-
-This is similar to the C function C<tcsendbreak()> for sending
-a break on its argument stream.
-
-Returns C<undef> on failure.
-
-=item tcsetpgrp
-
-This is similar to the C function C<tcsetpgrp()> for setting the
-process group identifier of the foreground process group of the controlling
-terminal.
-
-Returns C<undef> on failure.
-
-=item time
-
-This is identical to Perl's builtin C<time()> function
-for returning the number of seconds since the epoch
-(whatever it is for the system), see L<perlfunc/time>.
-
-=item times
-
-The times() function returns elapsed realtime since some point in the past
-(such as system startup), user and system times for this process, and user
-and system times used by child processes. All times are returned in clock
-ticks.
-
- ($realtime, $user, $system, $cuser, $csystem) = POSIX::times();
-
-Note: Perl's builtin C<times()> function returns four values, measured in
-seconds.
-
-=item tmpfile
-
-Use method C<IO::File::new_tmpfile()> instead, or see L<File::Temp>.
-
-=item tmpnam
-
-Returns a name for a temporary file.
-
- $tmpfile = POSIX::tmpnam();
-
-For security reasons, which are probably detailed in your system's
-documentation for the C library tmpnam() function, this interface
-should not be used; instead see L<File::Temp>.
-
-=item tolower
-
-This is identical to the C function, except that it can apply to a single
-character or to a whole string. Consider using the C<lc()> function,
-see L<perlfunc/lc>, or the equivalent C<\L> operator inside doublequotish
-strings.
-
-=item toupper
-
-This is identical to the C function, except that it can apply to a single
-character or to a whole string. Consider using the C<uc()> function,
-see L<perlfunc/uc>, or the equivalent C<\U> operator inside doublequotish
-strings.
-
-=item ttyname
-
-This is identical to the C function C<ttyname()> for returning the
-name of the current terminal.
-
-=item tzname
-
-Retrieves the time conversion information from the C<tzname> variable.
-
- POSIX::tzset();
- ($std, $dst) = POSIX::tzname();
-
-=item tzset
-
-This is identical to the C function C<tzset()> for setting
-the current timezone based on the environment variable C<TZ>,
-to be used by C<ctime()>, C<localtime()>, C<mktime()>, and C<strftime()>
-functions.
-
-=item umask
-
-This is identical to Perl's builtin C<umask()> function
-for setting (and querying) the file creation permission mask,
-see L<perlfunc/umask>.
-
-=item uname
-
-Get name of current operating system.
-
- ($sysname, $nodename, $release, $version, $machine) = POSIX::uname();
-
-Note that the actual meanings of the various fields are not
-that well standardized, do not expect any great portability.
-The C<$sysname> might be the name of the operating system,
-the C<$nodename> might be the name of the host, the C<$release>
-might be the (major) release number of the operating system,
-the C<$version> might be the (minor) release number of the
-operating system, and the C<$machine> might be a hardware identifier.
-Maybe.
-
-=item ungetc
-
-Use method C<IO::Handle::ungetc()> instead.
-
-=item unlink
-
-This is identical to Perl's builtin C<unlink()> function
-for removing files, see L<perlfunc/unlink>.
-
-=item utime
-
-This is identical to Perl's builtin C<utime()> function
-for changing the time stamps of files and directories,
-see L<perlfunc/utime>.
-
-=item vfprintf
-
-vfprintf() is C-specific, see L<perlfunc/printf> instead.
-
-=item vprintf
-
-vprintf() is C-specific, see L<perlfunc/printf> instead.
-
-=item vsprintf
-
-vsprintf() is C-specific, see L<perlfunc/sprintf> instead.
-
-=item wait
-
-This is identical to Perl's builtin C<wait()> function,
-see L<perlfunc/wait>.
-
-=item waitpid
-
-Wait for a child process to change state. This is identical to Perl's
-builtin C<waitpid()> function, see L<perlfunc/waitpid>.
-
- $pid = POSIX::waitpid( -1, POSIX::WNOHANG );
- print "status = ", ($? / 256), "\n";
-
-=item wcstombs
-
-This is identical to the C function C<wcstombs()>.
-Perl does not have any support for the wide and multibyte
-characters of the C standards, so this might be a rather
-useless function.
-
-=item wctomb
-
-This is identical to the C function C<wctomb()>.
-Perl does not have any support for the wide and multibyte
-characters of the C standards, so this might be a rather
-useless function.
-
-=item write
-
-Write to a file. This uses file descriptors such as those obtained by
-calling C<POSIX::open>.
-
- $fd = POSIX::open( "foo", &POSIX::O_WRONLY );
- $buf = "hello";
- $bytes = POSIX::write( $fd, $buf, 5 );
-
-Returns C<undef> on failure.
-
-See also L<perlfunc/syswrite>.
-
-=back
-
-=head1 CLASSES
-
-=head2 POSIX::SigAction
-
-=over 8
-
-=item new
-
-Creates a new C<POSIX::SigAction> object which corresponds to the C
-C<struct sigaction>. This object will be destroyed automatically when
-it is no longer needed. The first parameter is the handler, a sub
-reference. The second parameter is a C<POSIX::SigSet> object, it
-defaults to the empty set. The third parameter contains the
-C<sa_flags>, it defaults to 0.
-
- $sigset = POSIX::SigSet->new(SIGINT, SIGQUIT);
- $sigaction = POSIX::SigAction->new( \&handler, $sigset, &POSIX::SA_NOCLDSTOP );
-
-This C<POSIX::SigAction> object is intended for use with the C<POSIX::sigaction()>
-function.
-
-=back
-
-=over 8
-
-=item handler
-
-=item mask
-
-=item flags
-
-accessor functions to get/set the values of a SigAction object.
-
- $sigset = $sigaction->mask;
- $sigaction->flags(&POSIX::SA_RESTART);
-
-=item safe
-
-accessor function for the "safe signals" flag of a SigAction object; see
-L<perlipc> for general information on safe (a.k.a. "deferred") signals. If
-you wish to handle a signal safely, use this accessor to set the "safe" flag
-in the C<POSIX::SigAction> object:
-
- $sigaction->safe(1);
-
-You may also examine the "safe" flag on the output action object which is
-filled in when given as the third parameter to C<POSIX::sigaction()>:
-
- sigaction(SIGINT, $new_action, $old_action);
- if ($old_action->safe) {
- # previous SIGINT handler used safe signals
- }
-
-=back
-
-=head2 POSIX::SigRt
-
-=over 8
-
-=item %SIGRT
-
-A hash of the POSIX realtime signal handlers. It is an extension of
-the standard %SIG, the $POSIX::SIGRT{SIGRTMIN} is roughly equivalent
-to $SIG{SIGRTMIN}, but the right POSIX moves (see below) are made with
-the POSIX::SigSet and POSIX::sigaction instead of accessing the %SIG.
-
-You can set the %POSIX::SIGRT elements to set the POSIX realtime
-signal handlers, use C<delete> and C<exists> on the elements, and use
-C<scalar> on the C<%POSIX::SIGRT> to find out how many POSIX realtime
-signals there are available (SIGRTMAX - SIGRTMIN + 1, the SIGRTMAX is
-a valid POSIX realtime signal).
-
-Setting the %SIGRT elements is equivalent to calling this:
-
- sub new {
- my ($rtsig, $handler, $flags) = @_;
- my $sigset = POSIX::SigSet($rtsig);
- my $sigact = POSIX::SigAction->new($handler, $sigset, $flags);
- sigaction($rtsig, $sigact);
- }
-
-The flags default to zero, if you want something different you can
-either use C<local> on $POSIX::SigRt::SIGACTION_FLAGS, or you can
-derive from POSIX::SigRt and define your own C<new()> (the tied hash
-STORE method of the %SIGRT calls C<new($rtsig, $handler, $SIGACTION_FLAGS)>,
-where the $rtsig ranges from zero to SIGRTMAX - SIGRTMIN + 1).
-
-Just as with any signal, you can use sigaction($rtsig, undef, $oa) to
-retrieve the installed signal handler (or, rather, the signal action).
-
-B<NOTE:> whether POSIX realtime signals really work in your system, or
-whether Perl has been compiled so that it works with them, is outside
-of this discussion.
-
-=item SIGRTMIN
-
-Return the minimum POSIX realtime signal number available, or C<undef>
-if no POSIX realtime signals are available.
-
-=item SIGRTMAX
-
-Return the maximum POSIX realtime signal number available, or C<undef>
-if no POSIX realtime signals are available.
-
-=back
-
-=head2 POSIX::SigSet
-
-=over 8
-
-=item new
-
-Create a new SigSet object. This object will be destroyed automatically
-when it is no longer needed. Arguments may be supplied to initialize the
-set.
-
-Create an empty set.
-
- $sigset = POSIX::SigSet->new;
-
-Create a set with SIGUSR1.
-
- $sigset = POSIX::SigSet->new( &POSIX::SIGUSR1 );
-
-=item addset
-
-Add a signal to a SigSet object.
-
- $sigset->addset( &POSIX::SIGUSR2 );
-
-Returns C<undef> on failure.
-
-=item delset
-
-Remove a signal from the SigSet object.
-
- $sigset->delset( &POSIX::SIGUSR2 );
-
-Returns C<undef> on failure.
-
-=item emptyset
-
-Initialize the SigSet object to be empty.
-
- $sigset->emptyset();
-
-Returns C<undef> on failure.
-
-=item fillset
-
-Initialize the SigSet object to include all signals.
-
- $sigset->fillset();
-
-Returns C<undef> on failure.
-
-=item ismember
-
-Tests the SigSet object to see if it contains a specific signal.
-
- if( $sigset->ismember( &POSIX::SIGUSR1 ) ){
- print "contains SIGUSR1\n";
- }
-
-=back
-
-=head2 POSIX::Termios
-
-=over 8
-
-=item new
-
-Create a new Termios object. This object will be destroyed automatically
-when it is no longer needed. A Termios object corresponds to the termios
-C struct. new() mallocs a new one, getattr() fills it from a file descriptor,
-and setattr() sets a file descriptor's parameters to match Termios' contents.
-
- $termios = POSIX::Termios->new;
-
-=item getattr
-
-Get terminal control attributes.
-
-Obtain the attributes for stdin.
-
- $termios->getattr( 0 ) # Recommended for clarity.
- $termios->getattr()
-
-Obtain the attributes for stdout.
-
- $termios->getattr( 1 )
-
-Returns C<undef> on failure.
-
-=item getcc
-
-Retrieve a value from the c_cc field of a termios object. The c_cc field is
-an array so an index must be specified.
-
- $c_cc[1] = $termios->getcc(1);
-
-=item getcflag
-
-Retrieve the c_cflag field of a termios object.
-
- $c_cflag = $termios->getcflag;
-
-=item getiflag
-
-Retrieve the c_iflag field of a termios object.
-
- $c_iflag = $termios->getiflag;
-
-=item getispeed
-
-Retrieve the input baud rate.
-
- $ispeed = $termios->getispeed;
-
-=item getlflag
-
-Retrieve the c_lflag field of a termios object.
-
- $c_lflag = $termios->getlflag;
-
-=item getoflag
-
-Retrieve the c_oflag field of a termios object.
-
- $c_oflag = $termios->getoflag;
-
-=item getospeed
-
-Retrieve the output baud rate.
-
- $ospeed = $termios->getospeed;
-
-=item setattr
-
-Set terminal control attributes.
-
-Set attributes immediately for stdout.
-
- $termios->setattr( 1, &POSIX::TCSANOW );
-
-Returns C<undef> on failure.
-
-=item setcc
-
-Set a value in the c_cc field of a termios object. The c_cc field is an
-array so an index must be specified.
-
- $termios->setcc( &POSIX::VEOF, 1 );
-
-=item setcflag
-
-Set the c_cflag field of a termios object.
-
- $termios->setcflag( $c_cflag | &POSIX::CLOCAL );
-
-=item setiflag
-
-Set the c_iflag field of a termios object.
-
- $termios->setiflag( $c_iflag | &POSIX::BRKINT );
-
-=item setispeed
-
-Set the input baud rate.
-
- $termios->setispeed( &POSIX::B9600 );
-
-Returns C<undef> on failure.
-
-=item setlflag
-
-Set the c_lflag field of a termios object.
-
- $termios->setlflag( $c_lflag | &POSIX::ECHO );
-
-=item setoflag
-
-Set the c_oflag field of a termios object.
-
- $termios->setoflag( $c_oflag | &POSIX::OPOST );
-
-=item setospeed
-
-Set the output baud rate.
-
- $termios->setospeed( &POSIX::B9600 );
-
-Returns C<undef> on failure.
-
-=item Baud rate values
-
-B38400 B75 B200 B134 B300 B1800 B150 B0 B19200 B1200 B9600 B600 B4800 B50 B2400 B110
-
-=item Terminal interface values
-
-TCSADRAIN TCSANOW TCOON TCIOFLUSH TCOFLUSH TCION TCIFLUSH TCSAFLUSH TCIOFF TCOOFF
-
-=item c_cc field values
-
-VEOF VEOL VERASE VINTR VKILL VQUIT VSUSP VSTART VSTOP VMIN VTIME NCCS
-
-=item c_cflag field values
-
-CLOCAL CREAD CSIZE CS5 CS6 CS7 CS8 CSTOPB HUPCL PARENB PARODD
-
-=item c_iflag field values
-
-BRKINT ICRNL IGNBRK IGNCR IGNPAR INLCR INPCK ISTRIP IXOFF IXON PARMRK
-
-=item c_lflag field values
-
-ECHO ECHOE ECHOK ECHONL ICANON IEXTEN ISIG NOFLSH TOSTOP
-
-=item c_oflag field values
-
-OPOST
-
-=back
-
-=head1 PATHNAME CONSTANTS
-
-=over 8
-
-=item Constants
-
-_PC_CHOWN_RESTRICTED _PC_LINK_MAX _PC_MAX_CANON _PC_MAX_INPUT _PC_NAME_MAX _PC_NO_TRUNC _PC_PATH_MAX _PC_PIPE_BUF _PC_VDISABLE
-
-=back
-
-=head1 POSIX CONSTANTS
-
-=over 8
-
-=item Constants
-
-_POSIX_ARG_MAX _POSIX_CHILD_MAX _POSIX_CHOWN_RESTRICTED _POSIX_JOB_CONTROL _POSIX_LINK_MAX _POSIX_MAX_CANON _POSIX_MAX_INPUT _POSIX_NAME_MAX _POSIX_NGROUPS_MAX _POSIX_NO_TRUNC _POSIX_OPEN_MAX _POSIX_PATH_MAX _POSIX_PIPE_BUF _POSIX_SAVED_IDS _POSIX_SSIZE_MAX _POSIX_STREAM_MAX _POSIX_TZNAME_MAX _POSIX_VDISABLE _POSIX_VERSION
-
-=back
-
-=head1 SYSTEM CONFIGURATION
-
-=over 8
-
-=item Constants
-
-_SC_ARG_MAX _SC_CHILD_MAX _SC_CLK_TCK _SC_JOB_CONTROL _SC_NGROUPS_MAX _SC_OPEN_MAX _SC_PAGESIZE _SC_SAVED_IDS _SC_STREAM_MAX _SC_TZNAME_MAX _SC_VERSION
-
-=back
-
-=head1 ERRNO
-
-=over 8
-
-=item Constants
-
-E2BIG EACCES EADDRINUSE EADDRNOTAVAIL EAFNOSUPPORT EAGAIN EALREADY EBADF
-EBUSY ECHILD ECONNABORTED ECONNREFUSED ECONNRESET EDEADLK EDESTADDRREQ
-EDOM EDQUOT EEXIST EFAULT EFBIG EHOSTDOWN EHOSTUNREACH EINPROGRESS EINTR
-EINVAL EIO EISCONN EISDIR ELOOP EMFILE EMLINK EMSGSIZE ENAMETOOLONG
-ENETDOWN ENETRESET ENETUNREACH ENFILE ENOBUFS ENODEV ENOENT ENOEXEC
-ENOLCK ENOMEM ENOPROTOOPT ENOSPC ENOSYS ENOTBLK ENOTCONN ENOTDIR
-ENOTEMPTY ENOTSOCK ENOTTY ENXIO EOPNOTSUPP EPERM EPFNOSUPPORT EPIPE
-EPROCLIM EPROTONOSUPPORT EPROTOTYPE ERANGE EREMOTE ERESTART EROFS
-ESHUTDOWN ESOCKTNOSUPPORT ESPIPE ESRCH ESTALE ETIMEDOUT ETOOMANYREFS
-ETXTBSY EUSERS EWOULDBLOCK EXDEV
-
-=back
-
-=head1 FCNTL
-
-=over 8
-
-=item Constants
-
-FD_CLOEXEC F_DUPFD F_GETFD F_GETFL F_GETLK F_OK F_RDLCK F_SETFD F_SETFL F_SETLK F_SETLKW F_UNLCK F_WRLCK O_ACCMODE O_APPEND O_CREAT O_EXCL O_NOCTTY O_NONBLOCK O_RDONLY O_RDWR O_TRUNC O_WRONLY
-
-=back
-
-=head1 FLOAT
-
-=over 8
-
-=item Constants
-
-DBL_DIG DBL_EPSILON DBL_MANT_DIG DBL_MAX DBL_MAX_10_EXP DBL_MAX_EXP DBL_MIN DBL_MIN_10_EXP DBL_MIN_EXP FLT_DIG FLT_EPSILON FLT_MANT_DIG FLT_MAX FLT_MAX_10_EXP FLT_MAX_EXP FLT_MIN FLT_MIN_10_EXP FLT_MIN_EXP FLT_RADIX FLT_ROUNDS LDBL_DIG LDBL_EPSILON LDBL_MANT_DIG LDBL_MAX LDBL_MAX_10_EXP LDBL_MAX_EXP LDBL_MIN LDBL_MIN_10_EXP LDBL_MIN_EXP
-
-=back
-
-=head1 LIMITS
-
-=over 8
-
-=item Constants
-
-ARG_MAX CHAR_BIT CHAR_MAX CHAR_MIN CHILD_MAX INT_MAX INT_MIN LINK_MAX LONG_MAX LONG_MIN MAX_CANON MAX_INPUT MB_LEN_MAX NAME_MAX NGROUPS_MAX OPEN_MAX PATH_MAX PIPE_BUF SCHAR_MAX SCHAR_MIN SHRT_MAX SHRT_MIN SSIZE_MAX STREAM_MAX TZNAME_MAX UCHAR_MAX UINT_MAX ULONG_MAX USHRT_MAX
-
-=back
-
-=head1 LOCALE
-
-=over 8
-
-=item Constants
-
-LC_ALL LC_COLLATE LC_CTYPE LC_MONETARY LC_NUMERIC LC_TIME
-
-=back
-
-=head1 MATH
-
-=over 8
-
-=item Constants
-
-HUGE_VAL
-
-=back
-
-=head1 SIGNAL
-
-=over 8
-
-=item Constants
-
-SA_NOCLDSTOP SA_NOCLDWAIT SA_NODEFER SA_ONSTACK SA_RESETHAND SA_RESTART
-SA_SIGINFO SIGABRT SIGALRM SIGCHLD SIGCONT SIGFPE SIGHUP SIGILL SIGINT
-SIGKILL SIGPIPE SIGQUIT SIGSEGV SIGSTOP SIGTERM SIGTSTP SIGTTIN SIGTTOU
-SIGUSR1 SIGUSR2 SIG_BLOCK SIG_DFL SIG_ERR SIG_IGN SIG_SETMASK
-SIG_UNBLOCK
-
-=back
-
-=head1 STAT
-
-=over 8
-
-=item Constants
-
-S_IRGRP S_IROTH S_IRUSR S_IRWXG S_IRWXO S_IRWXU S_ISGID S_ISUID S_IWGRP S_IWOTH S_IWUSR S_IXGRP S_IXOTH S_IXUSR
-
-=item Macros
-
-S_ISBLK S_ISCHR S_ISDIR S_ISFIFO S_ISREG
-
-=back
-
-=head1 STDLIB
-
-=over 8
-
-=item Constants
-
-EXIT_FAILURE EXIT_SUCCESS MB_CUR_MAX RAND_MAX
-
-=back
-
-=head1 STDIO
-
-=over 8
-
-=item Constants
-
-BUFSIZ EOF FILENAME_MAX L_ctermid L_cuserid L_tmpname TMP_MAX
-
-=back
-
-=head1 TIME
-
-=over 8
-
-=item Constants
-
-CLK_TCK CLOCKS_PER_SEC
-
-=back
-
-=head1 UNISTD
-
-=over 8
-
-=item Constants
-
-R_OK SEEK_CUR SEEK_END SEEK_SET STDIN_FILENO STDOUT_FILENO STDERR_FILENO W_OK X_OK
-
-=back
-
-=head1 WAIT
-
-=over 8
-
-=item Constants
-
-WNOHANG WUNTRACED
-
-=over 16
-
-=item WNOHANG
-
-Do not suspend the calling process until a child process
-changes state but instead return immediately.
-
-=item WUNTRACED
-
-Catch stopped child processes.
-
-=back
-
-=item Macros
-
-WIFEXITED WEXITSTATUS WIFSIGNALED WTERMSIG WIFSTOPPED WSTOPSIG
-
-=over 16
-
-=item WIFEXITED
-
-WIFEXITED(${^CHILD_ERROR_NATIVE}) returns true if the child process
-exited normally (C<exit()> or by falling off the end of C<main()>)
-
-=item WEXITSTATUS
-
-WEXITSTATUS(${^CHILD_ERROR_NATIVE}) returns the normal exit status of
-the child process (only meaningful if WIFEXITED(${^CHILD_ERROR_NATIVE})
-is true)
-
-=item WIFSIGNALED
-
-WIFSIGNALED(${^CHILD_ERROR_NATIVE}) returns true if the child process
-terminated because of a signal
-
-=item WTERMSIG
-
-WTERMSIG(${^CHILD_ERROR_NATIVE}) returns the signal the child process
-terminated for (only meaningful if WIFSIGNALED(${^CHILD_ERROR_NATIVE})
-is true)
-
-=item WIFSTOPPED
-
-WIFSTOPPED(${^CHILD_ERROR_NATIVE}) returns true if the child process is
-currently stopped (can happen only if you specified the WUNTRACED flag
-to waitpid())
-
-=item WSTOPSIG
-
-WSTOPSIG(${^CHILD_ERROR_NATIVE}) returns the signal the child process
-was stopped for (only meaningful if WIFSTOPPED(${^CHILD_ERROR_NATIVE})
-is true)
-
-=back
-
-=back
-
diff --git a/Master/tlpkg/tlperl/lib/Pod/Simple.pod b/Master/tlpkg/tlperl/lib/Pod/Simple.pod
deleted file mode 100644
index a8ad211d3b6..00000000000
--- a/Master/tlpkg/tlperl/lib/Pod/Simple.pod
+++ /dev/null
@@ -1,395 +0,0 @@
-
-=head1 NAME
-
-Pod::Simple - framework for parsing Pod
-
-=head1 SYNOPSIS
-
- TODO
-
-=head1 DESCRIPTION
-
-Pod::Simple is a Perl library for parsing text in the Pod ("plain old
-documentation") markup language that is typically used for writing
-documentation for Perl and for Perl modules. The Pod format is explained
-L<perlpod>; the most common formatter is called C<perldoc>.
-
-Pod formatters can use Pod::Simple to parse Pod documents and render them into
-plain text, HTML, or any number of other formats. Typically, such formatters
-will be subclasses of Pod::Simple, and so they will inherit its methods, like
-C<parse_file>.
-
-If you're reading this document just because you have a Pod-processing
-subclass that you want to use, this document (plus the documentation for the
-subclass) is probably all you need to read.
-
-If you're reading this document because you want to write a formatter
-subclass, continue reading it and then read L<Pod::Simple::Subclassing>, and
-then possibly even read L<perlpodspec> (some of which is for parser-writers,
-but much of which is notes to formatter-writers).
-
-=head1 MAIN METHODS
-
-=over
-
-=item C<< $parser = I<SomeClass>->new(); >>
-
-This returns a new parser object, where I<C<SomeClass>> is a subclass
-of Pod::Simple.
-
-=item C<< $parser->output_fh( *OUT ); >>
-
-This sets the filehandle that C<$parser>'s output will be written to.
-You can pass C<*STDOUT>, otherwise you should probably do something
-like this:
-
- my $outfile = "output.txt";
- open TXTOUT, ">$outfile" or die "Can't write to $outfile: $!";
- $parser->output_fh(*TXTOUT);
-
-...before you call one of the C<< $parser->parse_I<whatever> >> methods.
-
-=item C<< $parser->output_string( \$somestring ); >>
-
-This sets the string that C<$parser>'s output will be sent to,
-instead of any filehandle.
-
-
-=item C<< $parser->parse_file( I<$some_filename> ); >>
-
-=item C<< $parser->parse_file( *INPUT_FH ); >>
-
-This reads the Pod content of the file (or filehandle) that you specify,
-and processes it with that C<$parser> object, according to however
-C<$parser>'s class works, and according to whatever parser options you
-have set up for this C<$parser> object.
-
-=item C<< $parser->parse_string_document( I<$all_content> ); >>
-
-This works just like C<parse_file> except that it reads the Pod
-content not from a file, but from a string that you have already
-in memory.
-
-=item C<< $parser->parse_lines( I<...@lines...>, undef ); >>
-
-This processes the lines in C<@lines> (where each list item must be a
-defined value, and must contain exactly one line of content -- so no
-items like C<"foo\nbar"> are allowed). The final C<undef> is used to
-indicate the end of document being parsed.
-
-The other C<parser_I<whatever>> methods are meant to be called only once
-per C<$parser> object; but C<parse_lines> can be called as many times per
-C<$parser> object as you want, as long as the last call (and only
-the last call) ends with an C<undef> value.
-
-
-=item C<< $parser->content_seen >>
-
-This returns true only if there has been any real content seen for this
-document. Returns false in cases where the document contains content,
-but does not make use of any Pod markup.
-
-=item C<< I<SomeClass>->filter( I<$filename> ); >>
-
-=item C<< I<SomeClass>->filter( I<*INPUT_FH> ); >>
-
-=item C<< I<SomeClass>->filter( I<\$document_content> ); >>
-
-This is a shortcut method for creating a new parser object, setting the
-output handle to STDOUT, and then processing the specified file (or
-filehandle, or in-memory document). This is handy for one-liners like
-this:
-
- perl -MPod::Simple::Text -e "Pod::Simple::Text->filter('thingy.pod')"
-
-=back
-
-
-
-=head1 SECONDARY METHODS
-
-Some of these methods might be of interest to general users, as
-well as of interest to formatter-writers.
-
-Note that the general pattern here is that the accessor-methods
-read the attribute's value with C<< $value = $parser->I<attribute> >>
-and set the attribute's value with
-C<< $parser->I<attribute>(I<newvalue>) >>. For each accessor, I typically
-only mention one syntax or another, based on which I think you are actually
-most likely to use.
-
-
-=over
-
-=item C<< $parser->no_whining( I<SOMEVALUE> ) >>
-
-If you set this attribute to a true value, you will suppress the
-parser's complaints about irregularities in the Pod coding. By default,
-this attribute's value is false, meaning that irregularities will
-be reported.
-
-Note that turning this attribute to true won't suppress one or two kinds
-of complaints about rarely occurring unrecoverable errors.
-
-
-=item C<< $parser->no_errata_section( I<SOMEVALUE> ) >>
-
-If you set this attribute to a true value, you will stop the parser from
-generating a "POD ERRORS" section at the end of the document. By
-default, this attribute's value is false, meaning that an errata section
-will be generated, as necessary.
-
-
-=item C<< $parser->complain_stderr( I<SOMEVALUE> ) >>
-
-If you set this attribute to a true value, it will send reports of
-parsing errors to STDERR. By default, this attribute's value is false,
-meaning that no output is sent to STDERR.
-
-Setting C<complain_stderr> also sets C<no_errata_section>.
-
-
-=item C<< $parser->source_filename >>
-
-This returns the filename that this parser object was set to read from.
-
-
-=item C<< $parser->doc_has_started >>
-
-This returns true if C<$parser> has read from a source, and has seen
-Pod content in it.
-
-
-=item C<< $parser->source_dead >>
-
-This returns true if C<$parser> has read from a source, and come to the
-end of that source.
-
-=item C<< $parser->strip_verbatim_indent( I<SOMEVALUE> ) >>
-
-The perlpod spec for a Verbatim paragraph is "It should be reproduced
-exactly...", which means that the whitespace you've used to indent your
-verbatim blocks will be preserved in the output. This can be annoying for
-outputs such as HTML, where that whitespace will remain in front of every
-line. It's an unfortunate case where syntax is turned into semantics.
-
-If the POD your parsing adheres to a consistent indentation policy, you can
-have such indentation stripped from the beginning of every line of your
-verbatim blocks. This method tells Pod::Simple what to strip. For two-space
-indents, you'd use:
-
- $parser->strip_verbatim_indent(' ');
-
-For tab indents, you'd use a tab character:
-
- $parser->strip_verbatim_indent("\t");
-
-If the POD is inconsistent about the indentation of verbatim blocks, but you
-have figured out a heuristic to determine how much a particular verbatim block
-is indented, you can pass a code reference instead. The code reference will be
-executed with one argument, an array reference of all the lines in the
-verbatim block, and should return the value to be stripped from each line. For
-example, if you decide that you're fine to use the first line of the verbatim
-block to set the standard for indentation of the rest of the block, you can
-look at the first line and return the appropriate value, like so:
-
- $new->strip_verbatim_indent(sub {
- my $lines = shift;
- (my $indent = $lines->[0]) =~ s/\S.*//;
- return $indent;
- });
-
-If you'd rather treat each line individually, you can do that, too, by just
-transforming them in-place in the code reference and returning C<undef>. Say
-that you don't want I<any> lines indented. You can do something like this:
-
- $new->strip_verbatim_indent(sub {
- my $lines = shift;
- sub { s/^\s+// for @{ $lines },
- return undef;
- });
-
-=back
-
-=head1 TERTIARY METHODS
-
-=over
-
-=item C<< $parser->abandon_output_fh() >>X<abandon_output_fh>
-
-Cancel output to the file handle. Any POD read by the C<$parser> is not
-effected.
-
-=item C<< $parser->abandon_output_string() >>X<abandon_output_string>
-
-Cancel output to the output string. Any POD read by the C<$parser> is not
-effected.
-
-=item C<< $parser->accept_code( @codes ) >>X<accept_code>
-
-Alias for L<< accept_codes >>.
-
-=item C<< $parser->accept_codes( @codes ) >>X<accept_codes>
-
-Allows C<$parser> to accept a list of L<perlpod/Formatting Codes>. This can be
-used to implement user-defined codes.
-
-=item C<< $parser->accept_directive_as_data( @directives ) >>X<accept_directive_as_data>
-
-Allows C<$parser> to accept a list of directives for data paragraphs. A
-directive is the label of a L<perlpod/Command Paragraph>. A data paragraph is
-one delimited by C<< =begin/=for/=end >> directives. This can be used to
-implement user-defined directives.
-
-=item C<< $parser->accept_directive_as_processed( @directives ) >>X<accept_directive_as_processed>
-
-Allows C<$parser> to accept a list of directives for processed paragraphs. A
-directive is the label of a L<perlpod/Command Paragraph>. A processed
-paragraph is also known as L<perlpod/Ordinary Paragraph>. This can be used to
-implement user-defined directives.
-
-=item C<< $parser->accept_directive_as_verbatim( @directives ) >>X<accept_directive_as_verbatim>
-
-Allows C<$parser> to accept a list of directives for L<perlpod/Verbatim
-Paragraph>. A directive is the label of a L<perlpod/Command Paragraph>. This
-can be used to implement user-defined directives.
-
-=item C<< $parser->accept_target( @targets ) >>X<accept_target>
-
-Alias for L<< accept_targets >>.
-
-=item C<< $parser->accept_target_as_text( @targets ) >>X<accept_target_as_text>
-
-Alias for L<< accept_targets_as_text >>.
-
-=item C<< $parser->accept_targets( @targets ) >>X<accept_targets>
-
-Accepts targets for C<< =begin/=for/=end >> sections of the POD.
-
-=item C<< $parser->accept_targets_as_text( @targets ) >>X<accept_targets_as_text>
-
-Accepts targets for C<< =begin/=for/=end >> sections that should be parsed as
-POD. For details, see L<< perlpodspec/About Data Paragraphs >>.
-
-=item C<< $parser->any_errata_seen() >>X<any_errata_seen>
-
-Used to check if any errata was seen.
-
-I<Example:>
-
- die "too many errors\n" if $parser->any_errata_seen();
-
-=item C<< $parser->parse_from_file( $source, $to ) >>X<parse_from_file>
-
-Parses from C<$source> file to C<$to> file. Similar to L<<
-Pod::Parser/parse_from_file >>.
-
-=item C<< $parser->scream( @error_messages ) >>X<scream>
-
-Log an error that can't be ignored.
-
-=item C<< $parser->unaccept_code( @codes ) >>X<unaccept_code>
-
-Alias for L<< unaccept_codes >>.
-
-=item C<< $parser->unaccept_codes( @codes ) >>X<unaccept_codes>
-
-Removes C<< @codes >> as valid codes for the parse.
-
-=item C<< $parser->unaccept_directive( @directives ) >>X<unaccept_directive>
-
-Alias for L<< unaccept_directives >>.
-
-=item C<< $parser->unaccept_directives( @directives ) >>X<unaccept_directives>
-
-Removes C<< @directives >> as valid directives for the parse.
-
-=item C<< $parser->unaccept_target( @targets ) >>X<unaccept_target>
-
-Alias for L<< unaccept_targets >>.
-
-=item C<< $parser->unaccept_targets( @targets ) >>X<unaccept_targets>
-
-Removes C<< @targets >> as valid targets for the parse.
-
-=item C<< $parser->version_report() >>X<version_report>
-
-Returns a string describing the version.
-
-=item C<< $parser->whine( @error_messages ) >>X<whine>
-
-Log an error unless C<< $parser->no_whining( TRUE ); >>.
-
-=back
-
-=head1 CAVEATS
-
-This is just a beta release -- there are a good number of things still
-left to do. Notably, support for EBCDIC platforms is still half-done,
-an untested.
-
-
-=head1 SEE ALSO
-
-L<Pod::Simple::Subclassing>
-
-L<perlpod|perlpod>
-
-L<perlpodspec|perlpodspec>
-
-L<Pod::Escapes|Pod::Escapes>
-
-L<perldoc>
-
-=head1 SUPPORT
-
-Questions or discussion about POD and Pod::Simple should be sent to the
-pod-people@perl.org mail list. Send an empty email to
-pod-people-subscribe@perl.org to subscribe.
-
-This module is managed in an open GitHub repository,
-L<http://github.com/theory/pod-simple/>. Feel free to fork and contribute, or
-to clone L<git://github.com/theory/pod-simple.git> and send patches!
-
-Patches against Pod::Simple are welcome. Please send bug reports to
-<bug-pod-simple@rt.cpan.org>.
-
-=head1 COPYRIGHT AND DISCLAIMERS
-
-Copyright (c) 2002 Sean M. Burke.
-
-This library is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-This program is distributed in the hope that it will be useful, but
-without any warranty; without even the implied warranty of
-merchantability or fitness for a particular purpose.
-
-=head1 AUTHOR
-
-Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.
-But don't bother him, he's retired.
-
-Pod::Simple is maintained by:
-
-=over
-
-=item * Allison Randal C<allison@perl.org>
-
-=item * Hans Dieter Pearcey C<hdp@cpan.org>
-
-=item * David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-Documentation has been contributed by:
-
-=over
-
-=item * Gabor Szabo C<szabgab@gmail.com>
-
-=item * Shawn H Corey C<SHCOREY at cpan.org>
-
-=back
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Pod/Simple/Subclassing.pod b/Master/tlpkg/tlperl/lib/Pod/Simple/Subclassing.pod
deleted file mode 100644
index 792d1be5a24..00000000000
--- a/Master/tlpkg/tlperl/lib/Pod/Simple/Subclassing.pod
+++ /dev/null
@@ -1,1057 +0,0 @@
-
-=head1 NAME
-
-Pod::Simple::Subclassing -- write a formatter as a Pod::Simple subclass
-
-=head1 SYNOPSIS
-
- package Pod::SomeFormatter;
- use Pod::Simple;
- @ISA = qw(Pod::Simple);
- $VERSION = '1.01';
- use strict;
-
- sub _handle_element_start {
- my($parser, $element_name, $attr_hash_r) = @_;
- ...
- }
-
- sub _handle_element_end {
- my($parser, $element_name, $attr_hash_r) = @_;
- # NOTE: $attr_hash_r is only present when $element_name is "over" or "begin"
- # The remaining code excerpts will mostly ignore this $attr_hash_r, as it is
- # mostly useless. It is documented where "over-*" and "begin" events are
- # documented.
- ...
- }
-
- sub _handle_text {
- my($parser, $text) = @_;
- ...
- }
- 1;
-
-=head1 DESCRIPTION
-
-This document is about using Pod::Simple to write a Pod processor,
-generally a Pod formatter. If you just want to know about using an
-existing Pod formatter, instead see its documentation and see also the
-docs in L<Pod::Simple>.
-
-The zeroeth step in writing a Pod formatter is to make sure that there
-isn't already a decent one in CPAN. See L<http://search.cpan.org/>, and
-run a search on the name of the format you want to render to. Also
-consider joining the Pod People list
-L<http://lists.perl.org/showlist.cgi?name=pod-people> and asking whether
-anyone has a formatter for that format -- maybe someone cobbled one
-together but just hasn't released it.
-
-The first step in writing a Pod processor is to read L<perlpodspec>,
-which contains notes information on writing a Pod parser (which has been
-largely taken care of by Pod::Simple), but also a lot of requirements
-and recommendations for writing a formatter.
-
-The second step is to actually learn the format you're planning to
-format to -- or at least as much as you need to know to represent Pod,
-which probably isn't much.
-
-The third step is to pick which of Pod::Simple's interfaces you want to
-use -- the basic interface via Pod::Simple or L<Pod::Simple::Methody> is
-event-based, sort of like L<HTML::Parser>'s interface, or sort of like
-L<XML::Parser>'s "Handlers" interface), but L<Pod::Simple::PullParser>
-provides a token-stream interface, sort of like L<HTML::TokeParser>'s
-interface; L<Pod::Simple::SimpleTree> provides a simple tree interface,
-rather like XML::Parser's "Tree" interface. Users familiar with
-XML-handling will find one of these styles relatively familiar; but if
-you would be even more at home with XML, there are classes that produce
-an XML representation of the Pod stream, notably
-L<Pod::Simple::XMLOutStream>; you can feed the output of such a class to
-whatever XML parsing system you are most at home with.
-
-The last step is to write your code based on how the events (or tokens,
-or tree-nodes, or the XML, or however you're parsing) will map to
-constructs in the output format. Also sure to consider how to escape
-text nodes containing arbitrary text, and also what to do with text
-nodes that represent preformatted text (from verbatim sections).
-
-
-
-=head1 Events
-
-TODO intro... mention that events are supplied for implicits, like for
-missing >'s
-
-
-In the following section, we use XML to represent the event structure
-associated with a particular construct. That is, TODO
-
-=over
-
-=item C<< $parser->_handle_element_start( I<element_name>, I<attr_hashref> ) >>
-
-=item C<< $parser->_handle_element_end( I<element_name> ) >>
-
-=item C<< $parser->_handle_text( I<text_string> ) >>
-
-=back
-
-TODO describe
-
-
-=over
-
-=item events with an element_name of Document
-
-Parsing a document produces this event structure:
-
- <Document start_line="543">
- ...all events...
- </Document>
-
-The value of the I<start_line> attribute will be the line number of the first
-Pod directive in the document.
-
-If there is no Pod in the given document, then the
-event structure will be this:
-
- <Document contentless="1" start_line="543">
- </Document>
-
-In that case, the value of the I<start_line> attribute will not be meaningful;
-under current implementations, it will probably be the line number of the
-last line in the file.
-
-=item events with an element_name of Para
-
-Parsing a plain (non-verbatim, non-directive, non-data) paragraph in
-a Pod document produces this event structure:
-
- <Para start_line="543">
- ...all events in this paragraph...
- </Para>
-
-The value of the I<start_line> attribute will be the line number of the start
-of the paragraph.
-
-For example, parsing this paragraph of Pod:
-
- The value of the I<start_line> attribute will be the
- line number of the start of the paragraph.
-
-produces this event structure:
-
- <Para start_line="129">
- The value of the
- <I>
- start_line
- </I>
- attribute will be the line number of the first Pod directive
- in the document.
- </Para>
-
-=item events with an element_name of B, C, F, or I.
-
-Parsing a BE<lt>...E<gt> formatting code (or of course any of its
-semantically identical syntactic variants
-S<BE<lt>E<lt> ... E<gt>E<gt>>,
-or S<BE<lt>E<lt>E<lt>E<lt> ... E<gt>E<gt>E<gt>E<gt>>, etc.)
-produces this event structure:
-
- <B>
- ...stuff...
- </B>
-
-Currently, there are no attributes conveyed.
-
-Parsing C, F, or I codes produce the same structure, with only a
-different element name.
-
-If your parser object has been set to accept other formatting codes,
-then they will be presented like these B/C/F/I codes -- i.e., without
-any attributes.
-
-=item events with an element_name of S
-
-Normally, parsing an SE<lt>...E<gt> sequence produces this event
-structure, just as if it were a B/C/F/I code:
-
- <S>
- ...stuff...
- </S>
-
-However, Pod::Simple (and presumably all derived parsers) offers the
-C<nbsp_for_S> option which, if enabled, will suppress all S events, and
-instead change all spaces in the content to non-breaking spaces. This is
-intended for formatters that output to a format that has no code that
-means the same as SE<lt>...E<gt>, but which has a code/character that
-means non-breaking space.
-
-=item events with an element_name of X
-
-Normally, parsing an XE<lt>...E<gt> sequence produces this event
-structure, just as if it were a B/C/F/I code:
-
- <X>
- ...stuff...
- </X>
-
-However, Pod::Simple (and presumably all derived parsers) offers the
-C<nix_X_codes> option which, if enabled, will suppress all X events
-and ignore their content. For formatters/processors that don't use
-X events, this is presumably quite useful.
-
-
-=item events with an element_name of L
-
-Because the LE<lt>...E<gt> is the most complex construct in the
-language, it should not surprise you that the events it generates are
-the most complex in the language. Most of complexity is hidden away in
-the attribute values, so for those of you writing a Pod formatter that
-produces a non-hypertextual format, you can just ignore the attributes
-and treat an L event structure like a formatting element that
-(presumably) doesn't actually produce a change in formatting. That is,
-the content of the L event structure (as opposed to its
-attributes) is always what text should be displayed.
-
-There are, at first glance, three kinds of L links: URL, man, and pod.
-
-When a LE<lt>I<some_url>E<gt> code is parsed, it produces this event
-structure:
-
- <L content-implicit="yes" raw="that_url" to="that_url" type="url">
- that_url
- </L>
-
-The C<type="url"> attribute is always specified for this type of
-L code.
-
-For example, this Pod source:
-
- L<http://www.perl.com/CPAN/authors/>
-
-produces this event structure:
-
- <L content-implicit="yes" raw="http://www.perl.com/CPAN/authors/" to="http://www.perl.com/CPAN/authors/" type="url">
- http://www.perl.com/CPAN/authors/
- </L>
-
-When a LE<lt>I<manpage(section)>E<gt> code is parsed (and these are
-fairly rare and not terribly useful), it produces this event structure:
-
- <L content-implicit="yes" raw="manpage(section)" to="manpage(section)" type="man">
- manpage(section)
- </L>
-
-The C<type="man"> attribute is always specified for this type of
-L code.
-
-For example, this Pod source:
-
- L<crontab(5)>
-
-produces this event structure:
-
- <L content-implicit="yes" raw="crontab(5)" to="crontab(5)" type="man">
- crontab(5)
- </L>
-
-In the rare cases where a man page link has a specified, that text appears
-in a I<section> attribute. For example, this Pod source:
-
- L<crontab(5)/"ENVIRONMENT">
-
-will produce this event structure:
-
- <L content-implicit="yes" raw="crontab(5)/&quot;ENVIRONMENT&quot;" section="ENVIRONMENT" to="crontab(5)" type="man">
- "ENVIRONMENT" in crontab(5)
- </L>
-
-In the rare case where the Pod document has code like
-LE<lt>I<sometext>|I<manpage(section)>E<gt>, then the I<sometext> will appear
-as the content of the element, the I<manpage(section)> text will appear
-only as the value of the I<to> attribute, and there will be no
-C<content-implicit="yes"> attribute (whose presence means that the Pod parser
-had to infer what text should appear as the link text -- as opposed to
-cases where that attribute is absent, which means that the Pod parser did
-I<not> have to infer the link text, because that L code explicitly specified
-some link text.)
-
-For example, this Pod source:
-
- L<hell itself!|crontab(5)>
-
-will produce this event structure:
-
- <L raw="hell itself!|crontab(5)" to="crontab(5)" type="man">
- hell itself!
- </L>
-
-The last type of L structure is for links to/within Pod documents. It is
-the most complex because it can have a I<to> attribute, I<or> a
-I<section> attribute, or both. The C<type="pod"> attribute is always
-specified for this type of L code.
-
-In the most common case, the simple case of a LE<lt>podpageE<gt> code
-produces this event structure:
-
- <L content-implicit="yes" raw="podpage" to="podpage" type="pod">
- podpage
- </L>
-
-For example, this Pod source:
-
- L<Net::Ping>
-
-produces this event structure:
-
- <L content-implicit="yes" raw="Net::Ping" to="Net::Ping" type="pod">
- Net::Ping
- </L>
-
-In cases where there is link-text explicitly specified, it
-is to be found in the content of the element (and not the
-attributes), just as with the LE<lt>I<sometext>|I<manpage(section)>E<gt>
-case discussed above. For example, this Pod source:
-
- L<Perl Error Messages|perldiag>
-
-produces this event structure:
-
- <L raw="Perl Error Messages|perldiag" to="perldiag" type="pod">
- Perl Error Messages
- </L>
-
-In cases of links to a section in the current Pod document,
-there is a I<section> attribute instead of a I<to> attribute.
-For example, this Pod source:
-
- L</"Member Data">
-
-produces this event structure:
-
- <L content-implicit="yes" raw="/&quot;Member Data&quot;" section="Member Data" type="pod">
- "Member Data"
- </L>
-
-As another example, this Pod source:
-
- L<the various attributes|/"Member Data">
-
-produces this event structure:
-
- <L raw="the various attributes|/&quot;Member Data&quot;" section="Member Data" type="pod">
- the various attributes
- </L>
-
-In cases of links to a section in a different Pod document,
-there are both a I<section> attribute and a L<to> attribute.
-For example, this Pod source:
-
- L<perlsyn/"Basic BLOCKs and Switch Statements">
-
-produces this event structure:
-
- <L content-implicit="yes" raw="perlsyn/&quot;Basic BLOCKs and Switch Statements&quot;" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
- "Basic BLOCKs and Switch Statements" in perlsyn
- </L>
-
-As another example, this Pod source:
-
- L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements">
-
-produces this event structure:
-
- <L raw="SWITCH statements|perlsyn/&quot;Basic BLOCKs and Switch Statements&quot;" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
- SWITCH statements
- </L>
-
-Incidentally, note that we do not distinguish between these syntaxes:
-
- L</"Member Data">
- L<"Member Data">
- L</Member Data>
- L<Member Data> [deprecated syntax]
-
-That is, they all produce the same event structure (for the most part), namely:
-
- <L content-implicit="yes" raw="$depends_on_syntax" section="Member Data" type="pod">
- &#34;Member Data&#34;
- </L>
-
-The I<raw> attribute depends on what the raw content of the L<> is, so that is
-why the event structure is the same "for the most part".
-
-If you have not guessed it yet, the I<raw> attribute contains the raw,
-original, unescaped content of the L<> formatting code. In addition to the
-examples above, take notice of the following event structure produced by
-the following L<> formatting code.
-
- L<click B<here>|page/About the C<-M> switch>
-
- <L raw="click B<here>|page/About the C<-M> switch" section="About the -M switch" to="page" type="pod">
- click B<here>
- </L>
-
-Specifically, notice that the formatting codes are present and unescaped
-in I<raw>.
-
-There is a known bug in the I<raw> attribute where any surrounding whitespace
-is condensed into a single ' '. For example, given LE<60> linkE<62>, I<raw>
-will be " link".
-
-=item events with an element_name of E or Z
-
-While there are Pod codes EE<lt>...E<gt> and ZE<lt>E<gt>, these
-I<do not> produce any E or Z events -- that is, there are no such
-events as E or Z.
-
-=item events with an element_name of Verbatim
-
-When a Pod verbatim paragraph (AKA "codeblock") is parsed, it
-produces this event structure:
-
- <Verbatim start_line="543" xml:space="preserve">
- ...text...
- </Verbatim>
-
-The value of the I<start_line> attribute will be the line number of the
-first line of this verbatim block. The I<xml:space> attribute is always
-present, and always has the value "preserve".
-
-The text content will have tabs already expanded.
-
-
-=item events with an element_name of head1 .. head4
-
-When a "=head1 ..." directive is parsed, it produces this event
-structure:
-
- <head1>
- ...stuff...
- </head1>
-
-For example, a directive consisting of this:
-
- =head1 Options to C<new> et al.
-
-will produce this event structure:
-
- <head1 start_line="543">
- Options to
- <C>
- new
- </C>
- et al.
- </head1>
-
-"=head2" thru "=head4" directives are the same, except for the element
-names in the event structure.
-
-=item events with an element_name of over-bullet
-
-When an "=over ... Z<>=back" block is parsed where the items are
-a bulleted list, it will produce this event structure:
-
- <over-bullet indent="4" start_line="543">
- <item-bullet start_line="545">
- ...Stuff...
- </item-bullet>
- ...more item-bullets...
- </over-bullet fake-closer="1">
-
-The attribute I<fake-closer> is only present if it is a true value; it is not
-present if it is a false value. It is shown in the above example to illustrate
-where the attribute is (in the B<closing> tag). It signifies that the C<=over>
-did not have a matching C<=back>, and thus Pod::Simple had to create a fake
-closer.
-
-For example, this Pod source:
-
- =over
-
- =item *
-
- Something
-
- =back
-
-Would produce an event structure that does B<not> have the I<fake-closer>
-attribute, whereas this Pod source:
-
- =over
-
- =item *
-
- Gasp! An unclosed =over block!
-
-would. The rest of the over-* examples will not demonstrate this attribute,
-but they all can have it. See L<Pod::Checker>'s source for an example of this
-attribute being used.
-
-The value of the I<indent> attribute is whatever value is after the
-"=over" directive, as in "=over 8". If no such value is specified
-in the directive, then the I<indent> attribute has the value "4".
-
-For example, this Pod source:
-
- =over
-
- =item *
-
- Stuff
-
- =item *
-
- Bar I<baz>!
-
- =back
-
-produces this event structure:
-
- <over-bullet indent="4" start_line="10">
- <item-bullet start_line="12">
- Stuff
- </item-bullet>
- <item-bullet start_line="14">
- Bar <I>baz</I>!
- </item-bullet>
- </over-bullet>
-
-=item events with an element_name of over-number
-
-When an "=over ... Z<>=back" block is parsed where the items are
-a numbered list, it will produce this event structure:
-
- <over-number indent="4" start_line="543">
- <item-number number="1" start_line="545">
- ...Stuff...
- </item-number>
- ...more item-number...
- </over-bullet>
-
-This is like the "over-bullet" event structure; but note that the contents
-are "item-number" instead of "item-bullet", and note that they will have
-a "number" attribute, which some formatters/processors may ignore
-(since, for example, there's no need for it in HTML when producing
-an "<UL><LI>...</LI>...</UL>" structure), but which any processor may use.
-
-Note that the values for the I<number> attributes of "item-number"
-elements in a given "over-number" area I<will> start at 1 and go up by
-one each time. If the Pod source doesn't follow that order (even though
-it really should should!), whatever numbers it has will be ignored (with
-the correct values being put in the I<number> attributes), and an error
-message might be issued to the user.
-
-=item events with an element_name of over-text
-
-These events are somewhat unlike the other over-*
-structures, as far as what their contents are. When
-an "=over ... Z<>=back" block is parsed where the items are
-a list of text "subheadings", it will produce this event structure:
-
- <over-text indent="4" start_line="543">
- <item-text>
- ...stuff...
- </item-text>
- ...stuff (generally Para or Verbatim elements)...
- <item-text>
- ...more item-text and/or stuff...
- </over-text>
-
-The I<indent> and I<fake-closer> attributes are as with the other over-* events.
-
-For example, this Pod source:
-
- =over
-
- =item Foo
-
- Stuff
-
- =item Bar I<baz>!
-
- Quux
-
- =back
-
-produces this event structure:
-
- <over-text indent="4" start_line="20">
- <item-text start_line="22">
- Foo
- </item-text>
- <Para start_line="24">
- Stuff
- </Para>
- <item-text start_line="26">
- Bar
- <I>
- baz
- </I>
- !
- </item-text>
- <Para start_line="28">
- Quux
- </Para>
- </over-text>
-
-
-
-=item events with an element_name of over-block
-
-These events are somewhat unlike the other over-*
-structures, as far as what their contents are. When
-an "=over ... Z<>=back" block is parsed where there are no items,
-it will produce this event structure:
-
- <over-block indent="4" start_line="543">
- ...stuff (generally Para or Verbatim elements)...
- </over-block>
-
-The I<indent> and I<fake-closer> attributes are as with the other over-* events.
-
-For example, this Pod source:
-
- =over
-
- For cutting off our trade with all parts of the world
-
- For transporting us beyond seas to be tried for pretended offenses
-
- He is at this time transporting large armies of foreign mercenaries to
- complete the works of death, desolation and tyranny, already begun with
- circumstances of cruelty and perfidy scarcely paralleled in the most
- barbarous ages, and totally unworthy the head of a civilized nation.
-
- =back
-
-will produce this event structure:
-
- <over-block indent="4" start_line="2">
- <Para start_line="4">
- For cutting off our trade with all parts of the world
- </Para>
- <Para start_line="6">
- For transporting us beyond seas to be tried for pretended offenses
- </Para>
- <Para start_line="8">
- He is at this time transporting large armies of [...more text...]
- </Para>
- </over-block>
-
-=item events with an element_name of over-empty
-
-B<Note: These events are only triggered if C<parse_empty_lists()> is set to a
-true value.>
-
-These events are somewhat unlike the other over-* structures, as far as what
-their contents are. When an "=over ... Z<>=back" block is parsed where there
-is no content, it will produce this event structure:
-
- <over-empty indent="4" start_line="543">
- </over-empty>
-
-The I<indent> and I<fake-closer> attributes are as with the other over-* events.
-
-For example, this Pod source:
-
- =over
-
- =over
-
- =back
-
- =back
-
-will produce this event structure:
-
- <over-block indent="4" start_line="1">
- <over-empty indent="4" start_line="3">
- </over-empty>
- </over-block>
-
-Note that the outer C<=over> is a block because it has no C<=item>s but still
-has content: the inner C<=over>. The inner C<=over>, in turn, is completely
-empty, and is treated as such.
-
-=item events with an element_name of item-bullet
-
-See L</"events with an element_name of over-bullet">, above.
-
-=item events with an element_name of item-number
-
-See L</"events with an element_name of over-number">, above.
-
-=item events with an element_name of item-text
-
-See L</"events with an element_name of over-text">, above.
-
-=item events with an element_name of for
-
-TODO...
-
-=item events with an element_name of Data
-
-TODO...
-
-=back
-
-
-
-=head1 More Pod::Simple Methods
-
-Pod::Simple provides a lot of methods that aren't generally interesting
-to the end user of an existing Pod formatter, but some of which you
-might find useful in writing a Pod formatter. They are listed below. The
-first several methods (the accept_* methods) are for declaring the
-capabilities of your parser, notably what C<=for I<targetname>> sections
-it's interested in, what extra NE<lt>...E<gt> codes it accepts beyond
-the ones described in the I<perlpod>.
-
-=over
-
-=item C<< $parser->accept_targets( I<SOMEVALUE> ) >>
-
-As the parser sees sections like:
-
- =for html <img src="fig1.jpg">
-
-or
-
- =begin html
-
- <img src="fig1.jpg">
-
- =end html
-
-...the parser will ignore these sections unless your subclass has
-specified that it wants to see sections targetted to "html" (or whatever
-the formatter name is).
-
-If you want to process all sections, even if they're not targetted for you,
-call this before you start parsing:
-
- $parser->accept_targets('*');
-
-=item C<< $parser->accept_targets_as_text( I<SOMEVALUE> ) >>
-
-This is like accept_targets, except that it specifies also that the
-content of sections for this target should be treated as Pod text even
-if the target name in "=for I<targetname>" doesn't start with a ":".
-
-At time of writing, I don't think you'll need to use this.
-
-
-=item C<< $parser->accept_codes( I<Codename>, I<Codename>... ) >>
-
-This tells the parser that you accept additional formatting codes,
-beyond just the standard ones (I B C L F S X, plus the two weird ones
-you don't actually see in the parse tree, Z and E). For example, to also
-accept codes "N", "R", and "W":
-
- $parser->accept_codes( qw( N R W ) );
-
-B<TODO: document how this interacts with =extend, and long element names>
-
-
-=item C<< $parser->accept_directive_as_data( I<directive_name> ) >>
-
-=item C<< $parser->accept_directive_as_verbatim( I<directive_name> ) >>
-
-=item C<< $parser->accept_directive_as_processed( I<directive_name> ) >>
-
-In the unlikely situation that you need to tell the parser that you will
-accept additional directives ("=foo" things), you need to first set the
-parser to treat its content as data (i.e., not really processed at
-all), or as verbatim (mostly just expanding tabs), or as processed text
-(parsing formatting codes like BE<lt>...E<gt>).
-
-For example, to accept a new directive "=method", you'd presumably
-use:
-
- $parser->accept_directive_as_processed("method");
-
-so that you could have Pod lines like:
-
- =method I<$whatever> thing B<um>
-
-Making up your own directives breaks compatibility with other Pod
-formatters, in a way that using "=for I<target> ..." lines doesn't;
-however, you may find this useful if you're making a Pod superset
-format where you don't need to worry about compatibility.
-
-
-=item C<< $parser->nbsp_for_S( I<BOOLEAN> ); >>
-
-Setting this attribute to a true value (and by default it is false) will
-turn "SE<lt>...E<gt>" sequences into sequences of words separated by
-C<\xA0> (non-breaking space) characters. For example, it will take this:
-
- I like S<Dutch apple pie>, don't you?
-
-and treat it as if it were:
-
- I like DutchE<nbsp>appleE<nbsp>pie, don't you?
-
-This is handy for output formats that don't have anything quite like an
-"SE<lt>...E<gt>" code, but which do have a code for non-breaking space.
-
-There is currently no method for going the other way; but I can
-probably provide one upon request.
-
-
-=item C<< $parser->version_report() >>
-
-This returns a string reporting the $VERSION value from your module (and
-its classname) as well as the $VERSION value of Pod::Simple. Note that
-L<perlpodspec> requires output formats (wherever possible) to note
-this detail in a comment in the output format. For example, for
-some kind of SGML output format:
-
- print OUT "<!-- \n", $parser->version_report, "\n -->";
-
-
-=item C<< $parser->pod_para_count() >>
-
-This returns the count of Pod paragraphs seen so far.
-
-
-=item C<< $parser->line_count() >>
-
-This is the current line number being parsed. But you might find the
-"line_number" event attribute more accurate, when it is present.
-
-
-=item C<< $parser->nix_X_codes( I<SOMEVALUE> ) >>
-
-This attribute, when set to a true value (and it is false by default)
-ignores any "XE<lt>...E<gt>" sequences in the document being parsed.
-Many formats don't actually use the content of these codes, so have
-no reason to process them.
-
-
-=item C<< $parser->merge_text( I<SOMEVALUE> ) >>
-
-This attribute, when set to a true value (and it is false by default)
-makes sure that only one event (or token, or node) will be created
-for any single contiguous sequence of text. For example, consider
-this somewhat contrived example:
-
- I just LOVE Z<>hotE<32>apple pie!
-
-When that is parsed and events are about to be called on it, it may
-actually seem to be four different text events, one right after another:
-one event for "I just LOVE ", one for "hot", one for " ", and one for
-"apple pie!". But if you have merge_text on, then you're guaranteed
-that it will be fired as one text event: "I just LOVE hot apple pie!".
-
-
-=item C<< $parser->code_handler( I<CODE_REF> ) >>
-
-This specifies code that should be called when a code line is seen
-(i.e., a line outside of the Pod). Normally this is undef, meaning
-that no code should be called. If you provide a routine, it should
-start out like this:
-
- sub get_code_line { # or whatever you'll call it
- my($line, $line_number, $parser) = @_;
- ...
- }
-
-Note, however, that sometimes the Pod events aren't processed in exactly
-the same order as the code lines are -- i.e., if you have a file with
-Pod, then code, then more Pod, sometimes the code will be processed (via
-whatever you have code_handler call) before the all of the preceding Pod
-has been processed.
-
-
-=item C<< $parser->cut_handler( I<CODE_REF> ) >>
-
-This is just like the code_handler attribute, except that it's for
-"=cut" lines, not code lines. The same caveats apply. "=cut" lines are
-unlikely to be interesting, but this is included for completeness.
-
-
-=item C<< $parser->pod_handler( I<CODE_REF> ) >>
-
-This is just like the code_handler attribute, except that it's for
-"=pod" lines, not code lines. The same caveats apply. "=pod" lines are
-unlikely to be interesting, but this is included for completeness.
-
-
-=item C<< $parser->whiteline_handler( I<CODE_REF> ) >>
-
-This is just like the code_handler attribute, except that it's for
-lines that are seemingly blank but have whitespace (" " and/or "\t") on them,
-not code lines. The same caveats apply. These lines are unlikely to be
-interesting, but this is included for completeness.
-
-
-=item C<< $parser->whine( I<linenumber>, I<complaint string> ) >>
-
-This notes a problem in the Pod, which will be reported to in the "Pod
-Errors" section of the document and/or send to STDERR, depending on the
-values of the attributes C<no_whining>, C<no_errata_section>, and
-C<complain_stderr>.
-
-=item C<< $parser->scream( I<linenumber>, I<complaint string> ) >>
-
-This notes an error like C<whine> does, except that it is not
-suppressible with C<no_whining>. This should be used only for very
-serious errors.
-
-
-=item C<< $parser->source_dead(1) >>
-
-This aborts parsing of the current document, by switching on the flag
-that indicates that EOF has been seen. In particularly drastic cases,
-you might want to do this. It's rather nicer than just calling
-C<die>!
-
-=item C<< $parser->hide_line_numbers( I<SOMEVALUE> ) >>
-
-Some subclasses that indiscriminately dump event attributes (well,
-except for ones beginning with "~") can use this object attribute for
-refraining to dump the "start_line" attribute.
-
-=item C<< $parser->no_whining( I<SOMEVALUE> ) >>
-
-This attribute, if set to true, will suppress reports of non-fatal
-error messages. The default value is false, meaning that complaints
-I<are> reported. How they get reported depends on the values of
-the attributes C<no_errata_section> and C<complain_stderr>.
-
-=item C<< $parser->no_errata_section( I<SOMEVALUE> ) >>
-
-This attribute, if set to true, will suppress generation of an errata
-section. The default value is false -- i.e., an errata section will be
-generated.
-
-=item C<< $parser->complain_stderr( I<SOMEVALUE> ) >>
-
-This attribute, if set to true will send complaints to STDERR. The
-default value is false -- i.e., complaints do not go to STDERR.
-
-=item C<< $parser->bare_output( I<SOMEVALUE> ) >>
-
-Some formatter subclasses use this as a flag for whether output should
-have prologue and epilogue code omitted. For example, setting this to
-true for an HTML formatter class should omit the
-"<html><head><title>...</title><body>..." prologue and the
-"</body></html>" epilogue.
-
-If you want to set this to true, you should probably also set
-C<no_whining> or at least C<no_errata_section> to true.
-
-=item C<< $parser->preserve_whitespace( I<SOMEVALUE> ) >>
-
-If you set this attribute to a true value, the parser will try to
-preserve whitespace in the output. This means that such formatting
-conventions as two spaces after periods will be preserved by the parser.
-This is primarily useful for output formats that treat whitespace as
-significant (such as text or *roff, but not HTML).
-
-=item C<< $parser->parse_empty_lists( I<SOMEVALUE> ) >>
-
-If this attribute is set to true, the parser will not ignore empty
-C<=over>/C<=back> blocks. The type of C<=over> will be I<empty>, documented
-above, L<events with an element_name of over-empty>.
-
-=back
-
-=head1 SEE ALSO
-
-L<Pod::Simple> -- event-based Pod-parsing framework
-
-L<Pod::Simple::Methody> -- like Pod::Simple, but each sort of event
-calls its own method (like C<start_head3>)
-
-L<Pod::Simple::PullParser> -- a Pod-parsing framework like Pod::Simple,
-but with a token-stream interface
-
-L<Pod::Simple::SimpleTree> -- a Pod-parsing framework like Pod::Simple,
-but with a tree interface
-
-L<Pod::Simple::Checker> -- a simple Pod::Simple subclass that reads
-documents, and then makes a plaintext report of any errors found in the
-document
-
-L<Pod::Simple::DumpAsXML> -- for dumping Pod documents as tidily
-indented XML, showing each event on its own line
-
-L<Pod::Simple::XMLOutStream> -- dumps a Pod document as XML (without
-introducing extra whitespace as Pod::Simple::DumpAsXML does).
-
-L<Pod::Simple::DumpAsText> -- for dumping Pod documents as tidily
-indented text, showing each event on its own line
-
-L<Pod::Simple::LinkSection> -- class for objects representing the values
-of the TODO and TODO attributes of LE<lt>...E<gt> elements
-
-L<Pod::Escapes> -- the module the Pod::Simple uses for evaluating
-EE<lt>...E<gt> content
-
-L<Pod::Simple::Text> -- a simple plaintext formatter for Pod
-
-L<Pod::Simple::TextContent> -- like Pod::Simple::Text, but
-makes no effort for indent or wrap the text being formatted
-
-L<Pod::Simple::HTML> -- a simple HTML formatter for Pod
-
-L<perlpod|perlpod>
-
-L<perlpodspec|perlpodspec>
-
-L<perldoc>
-
-=head1 SUPPORT
-
-Questions or discussion about POD and Pod::Simple should be sent to the
-pod-people@perl.org mail list. Send an empty email to
-pod-people-subscribe@perl.org to subscribe.
-
-This module is managed in an open GitHub repository,
-L<http://github.com/theory/pod-simple/>. Feel free to fork and contribute, or
-to clone L<git://github.com/theory/pod-simple.git> and send patches!
-
-Patches against Pod::Simple are welcome. Please send bug reports to
-<bug-pod-simple@rt.cpan.org>.
-
-=head1 COPYRIGHT AND DISCLAIMERS
-
-Copyright (c) 2002 Sean M. Burke.
-
-This library is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-This program is distributed in the hope that it will be useful, but
-without any warranty; without even the implied warranty of
-merchantability or fitness for a particular purpose.
-
-=head1 AUTHOR
-
-Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.
-But don't bother him, he's retired.
-
-Pod::Simple is maintained by:
-
-=over
-
-=item * Allison Randal C<allison@perl.org>
-
-=item * Hans Dieter Pearcey C<hdp@cpan.org>
-
-=item * David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=for notes
-Hm, my old podchecker version (1.2) says:
- *** WARNING: node 'http://search.cpan.org/' contains non-escaped | or / at line 38 in file Subclassing.pod
- *** WARNING: node 'http://lists.perl.org/showlist.cgi?name=pod-people' contains non-escaped | or / at line 41 in file Subclassing.pod
-Yes, L<...> is hard.
-
-
-=cut
-
-
diff --git a/Master/tlpkg/tlperl/lib/TAP/Harness/Beyond.pod b/Master/tlpkg/tlperl/lib/TAP/Harness/Beyond.pod
deleted file mode 100644
index ed77e13c253..00000000000
--- a/Master/tlpkg/tlperl/lib/TAP/Harness/Beyond.pod
+++ /dev/null
@@ -1,417 +0,0 @@
-=head1 Beyond make test
-
-Test::Harness is responsible for running test scripts, analysing
-their output and reporting success or failure. When I type
-F<make test> (or F<./Build test>) for a module, Test::Harness is usually
-used to run the tests (not all modules use Test::Harness but the
-majority do).
-
-To start exploring some of the features of Test::Harness I need to
-switch from F<make test> to the F<prove> command (which ships with
-Test::Harness). For the following examples I'll also need a recent
-version of Test::Harness installed; 3.14 is current as I write.
-
-For the examples I'm going to assume that we're working with a
-'normal' Perl module distribution. Specifically I'll assume that
-typing F<make> or F<./Build> causes the built, ready-to-install module
-code to be available below ./blib/lib and ./blib/arch and that
-there's a directory called 't' that contains our tests. Test::Harness
-isn't hardwired to that configuration but it saves me from explaining
-which files live where for each example.
-
-Back to F<prove>; like F<make test> it runs a test suite - but it
-provides far more control over which tests are executed, in what
-order and how their results are reported. Typically F<make test>
-runs all the test scripts below the 't' directory. To do the same
-thing with prove I type:
-
- prove -rb t
-
-The switches here are -r to recurse into any directories below 't'
-and -b which adds ./blib/lib and ./blib/arch to Perl's include path
-so that the tests can find the code they will be testing. If I'm
-testing a module of which an earlier version is already installed
-I need to be careful about the include path to make sure I'm not
-running my tests against the installed version rather than the new
-one that I'm working on.
-
-Unlike F<make test>, typing F<prove> doesn't automatically rebuild
-my module. If I forget to make before prove I will be testing against
-older versions of those files - which inevitably leads to confusion.
-I either get into the habit of typing
-
- make && prove -rb t
-
-or - if I have no XS code that needs to be built I use the modules
-below F<lib> instead
-
- prove -Ilib -r t
-
-So far I've shown you nothing that F<make test> doesn't do. Let's
-fix that.
-
-=head2 Saved State
-
-If I have failing tests in a test suite that consists of more than
-a handful of scripts and takes more than a few seconds to run it
-rapidly becomes tedious to run the whole test suite repeatedly as
-I track down the problems.
-
-I can tell prove just to run the tests that are failing like this:
-
- prove -b t/this_fails.t t/so_does_this.t
-
-That speeds things up but I have to make a note of which tests are
-failing and make sure that I run those tests. Instead I can use
-prove's --state switch and have it keep track of failing tests for
-me. First I do a complete run of the test suite and tell prove to
-save the results:
-
- prove -rb --state=save t
-
-That stores a machine readable summary of the test run in a file
-called '.prove' in the current directory. If I have failures I can
-then run just the failing scripts like this:
-
- prove -b --state=failed
-
-I can also tell prove to save the results again so that it updates
-its idea of which tests failed:
-
- prove -b --state=failed,save
-
-As soon as one of my failing tests passes it will be removed from
-the list of failed tests. Eventually I fix them all and prove can
-find no failing tests to run:
-
- Files=0, Tests=0, 0 wallclock secs ( 0.00 usr + 0.00 sys = 0.00 CPU)
- Result: NOTESTS
-
-As I work on a particular part of my module it's most likely that
-the tests that cover that code will fail. I'd like to run the whole
-test suite but have it prioritize these 'hot' tests. I can tell
-prove to do this:
-
- prove -rb --state=hot,save t
-
-All the tests will run but those that failed most recently will be
-run first. If no tests have failed since I started saving state all
-tests will run in their normal order. This combines full test
-coverage with early notification of failures.
-
-The --state switch supports a number of options; for example to run
-failed tests first followed by all remaining tests ordered by the
-timestamps of the test scripts - and save the results - I can use
-
- prove -rb --state=failed,new,save t
-
-See the prove documentation (type prove --man) for the full list
-of state options.
-
-When I tell prove to save state it writes a file called '.prove'
-('_prove' on Windows) in the current directory. It's a YAML document
-so it's quite easy to write tools of your own that work on the saved
-test state - but the format isn't officially documented so it might
-change without (much) warning in the future.
-
-=head2 Parallel Testing
-
-If my tests take too long to run I may be able to speed them up by
-running multiple test scripts in parallel. This is particularly
-effective if the tests are I/O bound or if I have multiple CPU
-cores. I tell prove to run my tests in parallel like this:
-
- prove -rb -j 9 t
-
-The -j switch enables parallel testing; the number that follows it
-is the maximum number of tests to run in parallel. Sometimes tests
-that pass when run sequentially will fail when run in parallel. For
-example if two different test scripts use the same temporary file
-or attempt to listen on the same socket I'll have problems running
-them in parallel. If I see unexpected failures I need to check my
-tests to work out which of them are trampling on the same resource
-and rename temporary files or add locks as appropriate.
-
-To get the most performance benefit I want to have the test scripts
-that take the longest to run start first - otherwise I'll be waiting
-for the one test that takes nearly a minute to complete after all
-the others are done. I can use the --state switch to run the tests
-in slowest to fastest order:
-
- prove -rb -j 9 --state=slow,save t
-
-=head2 Non-Perl Tests
-
-The Test Anything Protocol (http://testanything.org/) isn't just
-for Perl. Just about any language can be used to write tests that
-output TAP. There are TAP based testing libraries for C, C++, PHP,
-Python and many others. If I can't find a TAP library for my language
-of choice it's easy to generate valid TAP. It looks like this:
-
- 1..3
- ok 1 - init OK
- ok 2 - opened file
- not ok 3 - appended to file
-
-The first line is the plan - it specifies the number of tests I'm
-going to run so that it's easy to check that the test script didn't
-exit before running all the expected tests. The following lines are
-the test results - 'ok' for pass, 'not ok' for fail. Each test has
-a number and, optionally, a description. And that's it. Any language
-that can produce output like that on STDOUT can be used to write
-tests.
-
-Recently I've been rekindling a two-decades-old interest in Forth.
-Evidently I have a masochistic streak that even Perl can't satisfy.
-I want to write tests in Forth and run them using prove (you can
-find my gforth TAP experiments at
-https://svn.hexten.net/andy/Forth/Testing/). I can use the --exec
-switch to tell prove to run the tests using gforth like this:
-
- prove -r --exec gforth t
-
-Alternately, if the language used to write my tests allows a shebang
-line I can use that to specify the interpreter. Here's a test written
-in PHP:
-
- #!/usr/bin/php
- <?php
- print "1..2\n";
- print "ok 1\n";
- print "not ok 2\n";
- ?>
-
-If I save that as t/phptest.t the shebang line will ensure that it
-runs correctly along with all my other tests.
-
-=head2 Mixing it up
-
-Subtle interdependencies between test programs can mask problems -
-for example an earlier test may neglect to remove a temporary file
-that affects the behaviour of a later test. To find this kind of
-problem I use the --shuffle and --reverse options to run my tests
-in random or reversed order.
-
-=head2 Rolling My Own
-
-If I need a feature that prove doesn't provide I can easily write my own.
-
-Typically you'll want to change how TAP gets I<input> into and I<output>
-from the parser. L<App::Prove> supports arbitrary plugins, and L<TAP::Harness>
-supports custom I<formatters> and I<source handlers> that you can load using
-either L<prove> or L<Module::Build>; there are many examples to base mine on.
-For more details see L<App::Prove>, L<TAP::Parser::SourceHandler>, and
-L<TAP::Formatter::Base>.
-
-If writing a plugin is not enough, you can write your own test harness; one of
-the motives for the 3.00 rewrite of Test::Harness was to make it easier to
-subclass and extend.
-
-The Test::Harness module is a compatibility wrapper around TAP::Harness.
-For new applications I should use TAP::Harness directly. As we'll
-see, prove uses TAP::Harness.
-
-When I run prove it processes its arguments, figures out which test
-scripts to run and then passes control to TAP::Harness to run the
-tests, parse, analyse and present the results. By subclassing
-TAP::Harness I can customise many aspects of the test run.
-
-I want to log my test results in a database so I can track them
-over time. To do this I override the summary method in TAP::Harness.
-I start with a simple prototype that dumps the results as a YAML
-document:
-
- package My::TAP::Harness;
-
- use base qw( TAP::Harness ); use YAML;
-
- sub summary {
- my ( $self, $aggregate ) = @_;
- print Dump( $aggregate );
- $self->SUPER::summary( $aggregate );
- }
-
- 1;
-
-I need to tell prove to use my My::TAP::Harness. If My::TAP::Harness
-is on Perl's @INC include path I can
-
- prove --harness=My::TAP::Harness -rb t
-
-If I don't have My::TAP::Harness installed on @INC I need to provide
-the correct path to perl when I run prove:
-
- perl -Ilib `which prove` --harness=My::TAP::Harness -rb t
-
-I can incorporate these options into my own version of prove. It's
-pretty simple. Most of the work of prove is handled by App::Prove.
-The important code in prove is just:
-
- use App::Prove;
-
- my $app = App::Prove->new;
- $app->process_args(@ARGV);
- exit( $app->run ? 0 : 1 );
-
-If I write a subclass of App::Prove I can customise any aspect of
-the test runner while inheriting all of prove's behaviour. Here's
-myprove:
-
- #!/usr/bin/env perl use lib qw( lib ); # Add ./lib to @INC
- use App::Prove;
-
- my $app = App::Prove->new;
-
- # Use custom TAP::Harness subclass
- $app->harness( 'My::TAP::Harness' );
-
- $app->process_args( @ARGV ); exit( $app->run ? 0 : 1 );
-
-Now I can run my tests like this
-
- ./myprove -rb t
-
-=head2 Deeper Customisation
-
-Now that I know how to subclass and replace TAP::Harness I can
-replace any other part of the harness. To do that I need to know
-which classes are responsible for which functionality. Here's a
-brief guided tour; the default class for each component is shown
-in parentheses. Normally any replacements I write will be subclasses
-of these default classes.
-
-When I run my tests TAP::Harness creates a scheduler
-(TAP::Parser::Scheduler) to work out the running order for the
-tests, an aggregator (TAP::Parser::Aggregator) to collect and analyse
-the test results and a formatter (TAP::Formatter::Console) to display
-those results.
-
-If I'm running my tests in parallel there may also be a multiplexer
-(TAP::Parser::Multiplexer) - the component that allows multiple
-tests to run simultaneously.
-
-Once it has created those helpers TAP::Harness starts running the
-tests. For each test it creates a new parser (TAP::Parser) which
-is responsible for running the test script and parsing its output.
-
-To replace any of these components I call one of these harness
-methods with the name of the replacement class:
-
- aggregator_class
- formatter_class
- multiplexer_class
- parser_class
- scheduler_class
-
-For example, to replace the aggregator I would
-
- $harness->aggregator_class( 'My::Aggregator' );
-
-Alternately I can supply the names of my substitute classes to the
-TAP::Harness constructor:
-
- my $harness = TAP::Harness->new(
- { aggregator_class => 'My::Aggregator' }
- );
-
-If I need to reach even deeper into the internals of the harness I
-can replace the classes that TAP::Parser uses to execute test scripts
-and tokenise their output. Before running a test script TAP::Parser
-creates a grammar (TAP::Parser::Grammar) to decode the raw TAP into
-tokens, a result factory (TAP::Parser::ResultFactory) to turn the
-decoded TAP results into objects and, depending on whether it's
-running a test script or reading TAP from a file, scalar or array
-a source or an iterator (TAP::Parser::IteratorFactory).
-
-Each of these objects may be replaced by calling one of these parser
-methods:
-
- source_class
- perl_source_class
- grammar_class
- iterator_factory_class
- result_factory_class
-
-=head2 Callbacks
-
-As an alternative to subclassing the components I need to change I
-can attach callbacks to the default classes. TAP::Harness exposes
-these callbacks:
-
- parser_args Tweak the parameters used to create the parser
- made_parser Just made a new parser
- before_runtests About to run tests
- after_runtests Have run all tests
- after_test Have run an individual test script
-
-TAP::Parser also supports callbacks; bailout, comment, plan, test,
-unknown, version and yaml are called for the corresponding TAP
-result types, ALL is called for all results, ELSE is called for all
-results for which a named callback is not installed and EOF is
-called once at the end of each TAP stream.
-
-To install a callback I pass the name of the callback and a subroutine
-reference to TAP::Harness or TAP::Parser's callback method:
-
- $harness->callback( after_test => sub {
- my ( $script, $desc, $parser ) = @_;
- } );
-
-I can also pass callbacks to the constructor:
-
- my $harness = TAP::Harness->new({
- callbacks => {
- after_test => sub {
- my ( $script, $desc, $parser ) = @_;
- # Do something interesting here
- }
- }
- });
-
-When it comes to altering the behaviour of the test harness there's
-more than one way to do it. Which way is best depends on my
-requirements. In general if I only want to observe test execution
-without changing the harness' behaviour (for example to log test
-results to a database) I choose callbacks. If I want to make the
-harness behave differently subclassing gives me more control.
-
-=head2 Parsing TAP
-
-Perhaps I don't need a complete test harness. If I already have a
-TAP test log that I need to parse all I need is TAP::Parser and the
-various classes it depends upon. Here's the code I need to run a
-test and parse its TAP output
-
- use TAP::Parser;
-
- my $parser = TAP::Parser->new( { source => 't/simple.t' } );
- while ( my $result = $parser->next ) {
- print $result->as_string, "\n";
- }
-
-Alternately I can pass an open filehandle as source and have the
-parser read from that rather than attempting to run a test script:
-
- open my $tap, '<', 'tests.tap'
- or die "Can't read TAP transcript ($!)\n";
- my $parser = TAP::Parser->new( { source => $tap } );
- while ( my $result = $parser->next ) {
- print $result->as_string, "\n";
- }
-
-This approach is useful if I need to convert my TAP based test
-results into some other representation. See TAP::Convert::TET
-(http://search.cpan.org/dist/TAP-Convert-TET/) for an example of
-this approach.
-
-=head2 Getting Support
-
-The Test::Harness developers hang out on the tapx-dev mailing
-list[1]. For discussion of general, language independent TAP issues
-there's the tap-l[2] list. Finally there's a wiki dedicated to the
-Test Anything Protocol[3]. Contributions to the wiki, patches and
-suggestions are all welcome.
-
-[1] L<http://www.hexten.net/mailman/listinfo/tapx-dev>
-[2] L<http://testanything.org/mailman/listinfo/tap-l>
-[3] L<http://testanything.org/>
diff --git a/Master/tlpkg/tlperl/lib/Test/Tutorial.pod b/Master/tlpkg/tlperl/lib/Test/Tutorial.pod
deleted file mode 100644
index 46ac467ddae..00000000000
--- a/Master/tlpkg/tlperl/lib/Test/Tutorial.pod
+++ /dev/null
@@ -1,604 +0,0 @@
-=head1 NAME
-
-Test::Tutorial - A tutorial about writing really basic tests
-
-=head1 DESCRIPTION
-
-
-I<AHHHHHHH!!!! NOT TESTING! Anything but testing!
-Beat me, whip me, send me to Detroit, but don't make
-me write tests!>
-
-I<*sob*>
-
-I<Besides, I don't know how to write the damned things.>
-
-
-Is this you? Is writing tests right up there with writing
-documentation and having your fingernails pulled out? Did you open up
-a test and read
-
- ######## We start with some black magic
-
-and decide that's quite enough for you?
-
-It's ok. That's all gone now. We've done all the black magic for
-you. And here are the tricks...
-
-
-=head2 Nuts and bolts of testing.
-
-Here's the most basic test program.
-
- #!/usr/bin/perl -w
-
- print "1..1\n";
-
- print 1 + 1 == 2 ? "ok 1\n" : "not ok 1\n";
-
-since 1 + 1 is 2, it prints:
-
- 1..1
- ok 1
-
-What this says is: C<1..1> "I'm going to run one test." [1] C<ok 1>
-"The first test passed". And that's about all magic there is to
-testing. Your basic unit of testing is the I<ok>. For each thing you
-test, an C<ok> is printed. Simple. B<Test::Harness> interprets your test
-results to determine if you succeeded or failed (more on that later).
-
-Writing all these print statements rapidly gets tedious. Fortunately,
-there's B<Test::Simple>. It has one function, C<ok()>.
-
- #!/usr/bin/perl -w
-
- use Test::Simple tests => 1;
-
- ok( 1 + 1 == 2 );
-
-and that does the same thing as the code above. C<ok()> is the backbone
-of Perl testing, and we'll be using it instead of roll-your-own from
-here on. If C<ok()> gets a true value, the test passes. False, it
-fails.
-
- #!/usr/bin/perl -w
-
- use Test::Simple tests => 2;
- ok( 1 + 1 == 2 );
- ok( 2 + 2 == 5 );
-
-from that comes
-
- 1..2
- ok 1
- not ok 2
- # Failed test (test.pl at line 5)
- # Looks like you failed 1 tests of 2.
-
-C<1..2> "I'm going to run two tests." This number is used to ensure
-your test program ran all the way through and didn't die or skip some
-tests. C<ok 1> "The first test passed." C<not ok 2> "The second test
-failed". Test::Simple helpfully prints out some extra commentary about
-your tests.
-
-It's not scary. Come, hold my hand. We're going to give an example
-of testing a module. For our example, we'll be testing a date
-library, B<Date::ICal>. It's on CPAN, so download a copy and follow
-along. [2]
-
-
-=head2 Where to start?
-
-This is the hardest part of testing, where do you start? People often
-get overwhelmed at the apparent enormity of the task of testing a
-whole module. Best place to start is at the beginning. Date::ICal is
-an object-oriented module, and that means you start by making an
-object. So we test C<new()>.
-
- #!/usr/bin/perl -w
-
- use Test::Simple tests => 2;
-
- use Date::ICal;
-
- my $ical = Date::ICal->new; # create an object
- ok( defined $ical ); # check that we got something
- ok( $ical->isa('Date::ICal') ); # and it's the right class
-
-run that and you should get:
-
- 1..2
- ok 1
- ok 2
-
-congratulations, you've written your first useful test.
-
-
-=head2 Names
-
-That output isn't terribly descriptive, is it? When you have two
-tests you can figure out which one is #2, but what if you have 102?
-
-Each test can be given a little descriptive name as the second
-argument to C<ok()>.
-
- use Test::Simple tests => 2;
-
- ok( defined $ical, 'new() returned something' );
- ok( $ical->isa('Date::ICal'), " and it's the right class" );
-
-So now you'd see...
-
- 1..2
- ok 1 - new() returned something
- ok 2 - and it's the right class
-
-
-=head2 Test the manual
-
-Simplest way to build up a decent testing suite is to just test what
-the manual says it does. [3] Let's pull something out of the
-L<Date::ICal/SYNOPSIS> and test that all its bits work.
-
- #!/usr/bin/perl -w
-
- use Test::Simple tests => 8;
-
- use Date::ICal;
-
- $ical = Date::ICal->new( year => 1964, month => 10, day => 16,
- hour => 16, min => 12, sec => 47,
- tz => '0530' );
-
- ok( defined $ical, 'new() returned something' );
- ok( $ical->isa('Date::ICal'), " and it's the right class" );
- ok( $ical->sec == 47, ' sec()' );
- ok( $ical->min == 12, ' min()' );
- ok( $ical->hour == 16, ' hour()' );
- ok( $ical->day == 17, ' day()' );
- ok( $ical->month == 10, ' month()' );
- ok( $ical->year == 1964, ' year()' );
-
-run that and you get:
-
- 1..8
- ok 1 - new() returned something
- ok 2 - and it's the right class
- ok 3 - sec()
- ok 4 - min()
- ok 5 - hour()
- not ok 6 - day()
- # Failed test (- at line 16)
- ok 7 - month()
- ok 8 - year()
- # Looks like you failed 1 tests of 8.
-
-Whoops, a failure! [4] Test::Simple helpfully lets us know on what line
-the failure occurred, but not much else. We were supposed to get 17,
-but we didn't. What did we get?? Dunno. We'll have to re-run the
-test in the debugger or throw in some print statements to find out.
-
-Instead, we'll switch from B<Test::Simple> to B<Test::More>. B<Test::More>
-does everything B<Test::Simple> does, and more! In fact, Test::More does
-things I<exactly> the way Test::Simple does. You can literally swap
-Test::Simple out and put Test::More in its place. That's just what
-we're going to do.
-
-Test::More does more than Test::Simple. The most important difference
-at this point is it provides more informative ways to say "ok".
-Although you can write almost any test with a generic C<ok()>, it
-can't tell you what went wrong. Instead, we'll use the C<is()>
-function, which lets us declare that something is supposed to be the
-same as something else:
-
- #!/usr/bin/perl -w
-
- use Test::More tests => 8;
-
- use Date::ICal;
-
- $ical = Date::ICal->new( year => 1964, month => 10, day => 16,
- hour => 16, min => 12, sec => 47,
- tz => '0530' );
-
- ok( defined $ical, 'new() returned something' );
- ok( $ical->isa('Date::ICal'), " and it's the right class" );
- is( $ical->sec, 47, ' sec()' );
- is( $ical->min, 12, ' min()' );
- is( $ical->hour, 16, ' hour()' );
- is( $ical->day, 17, ' day()' );
- is( $ical->month, 10, ' month()' );
- is( $ical->year, 1964, ' year()' );
-
-"Is C<$ical-E<gt>sec> 47?" "Is C<$ical-E<gt>min> 12?" With C<is()> in place,
-you get some more information
-
- 1..8
- ok 1 - new() returned something
- ok 2 - and it's the right class
- ok 3 - sec()
- ok 4 - min()
- ok 5 - hour()
- not ok 6 - day()
- # Failed test (- at line 16)
- # got: '16'
- # expected: '17'
- ok 7 - month()
- ok 8 - year()
- # Looks like you failed 1 tests of 8.
-
-letting us know that C<$ical-E<gt>day> returned 16, but we expected 17. A
-quick check shows that the code is working fine, we made a mistake
-when writing up the tests. Just change it to:
-
- is( $ical->day, 16, ' day()' );
-
-and everything works.
-
-So any time you're doing a "this equals that" sort of test, use C<is()>.
-It even works on arrays. The test is always in scalar context, so you
-can test how many elements are in a list this way. [5]
-
- is( @foo, 5, 'foo has 5 elements' );
-
-
-=head2 Sometimes the tests are wrong
-
-Which brings us to a very important lesson. Code has bugs. Tests are
-code. Ergo, tests have bugs. A failing test could mean a bug in the
-code, but don't discount the possibility that the test is wrong.
-
-On the flip side, don't be tempted to prematurely declare a test
-incorrect just because you're having trouble finding the bug.
-Invalidating a test isn't something to be taken lightly, and don't use
-it as a cop out to avoid work.
-
-
-=head2 Testing lots of values
-
-We're going to be wanting to test a lot of dates here, trying to trick
-the code with lots of different edge cases. Does it work before 1970?
-After 2038? Before 1904? Do years after 10,000 give it trouble?
-Does it get leap years right? We could keep repeating the code above,
-or we could set up a little try/expect loop.
-
- use Test::More tests => 32;
- use Date::ICal;
-
- my %ICal_Dates = (
- # An ICal string And the year, month, day
- # hour, minute and second we expect.
- '19971024T120000' => # from the docs.
- [ 1997, 10, 24, 12, 0, 0 ],
- '20390123T232832' => # after the Unix epoch
- [ 2039, 1, 23, 23, 28, 32 ],
- '19671225T000000' => # before the Unix epoch
- [ 1967, 12, 25, 0, 0, 0 ],
- '18990505T232323' => # before the MacOS epoch
- [ 1899, 5, 5, 23, 23, 23 ],
- );
-
-
- while( my($ical_str, $expect) = each %ICal_Dates ) {
- my $ical = Date::ICal->new( ical => $ical_str );
-
- ok( defined $ical, "new(ical => '$ical_str')" );
- ok( $ical->isa('Date::ICal'), " and it's the right class" );
-
- is( $ical->year, $expect->[0], ' year()' );
- is( $ical->month, $expect->[1], ' month()' );
- is( $ical->day, $expect->[2], ' day()' );
- is( $ical->hour, $expect->[3], ' hour()' );
- is( $ical->min, $expect->[4], ' min()' );
- is( $ical->sec, $expect->[5], ' sec()' );
- }
-
-So now we can test bunches of dates by just adding them to
-C<%ICal_Dates>. Now that it's less work to test with more dates, you'll
-be inclined to just throw more in as you think of them.
-Only problem is, every time we add to that we have to keep adjusting
-the C<use Test::More tests =E<gt> ##> line. That can rapidly get
-annoying. There's two ways to make this work better.
-
-First, we can calculate the plan dynamically using the C<plan()>
-function.
-
- use Test::More;
- use Date::ICal;
-
- my %ICal_Dates = (
- ...same as before...
- );
-
- # For each key in the hash we're running 8 tests.
- plan tests => keys(%ICal_Dates) * 8;
-
- ...and then your tests...
-
-Or to be even more flexible, we use C<no_plan>. This means we're just
-running some tests, don't know how many. [6]
-
- use Test::More 'no_plan'; # instead of tests => 32
-
-now we can just add tests and not have to do all sorts of math to
-figure out how many we're running.
-
-
-=head2 Informative names
-
-Take a look at this line here
-
- ok( defined $ical, "new(ical => '$ical_str')" );
-
-we've added more detail about what we're testing and the ICal string
-itself we're trying out to the name. So you get results like:
-
- ok 25 - new(ical => '19971024T120000')
- ok 26 - and it's the right class
- ok 27 - year()
- ok 28 - month()
- ok 29 - day()
- ok 30 - hour()
- ok 31 - min()
- ok 32 - sec()
-
-if something in there fails, you'll know which one it was and that
-will make tracking down the problem easier. So try to put a bit of
-debugging information into the test names.
-
-Describe what the tests test, to make debugging a failed test easier
-for you or for the next person who runs your test.
-
-
-=head2 Skipping tests
-
-Poking around in the existing Date::ICal tests, I found this in
-F<t/01sanity.t> [7]
-
- #!/usr/bin/perl -w
-
- use Test::More tests => 7;
- use Date::ICal;
-
- # Make sure epoch time is being handled sanely.
- my $t1 = Date::ICal->new( epoch => 0 );
- is( $t1->epoch, 0, "Epoch time of 0" );
-
- # XXX This will only work on unix systems.
- is( $t1->ical, '19700101Z', " epoch to ical" );
-
- is( $t1->year, 1970, " year()" );
- is( $t1->month, 1, " month()" );
- is( $t1->day, 1, " day()" );
-
- # like the tests above, but starting with ical instead of epoch
- my $t2 = Date::ICal->new( ical => '19700101Z' );
- is( $t2->ical, '19700101Z', "Start of epoch in ICal notation" );
-
- is( $t2->epoch, 0, " and back to ICal" );
-
-The beginning of the epoch is different on most non-Unix operating
-systems [8]. Even though Perl smooths out the differences for the
-most part, certain ports do it differently. MacPerl is one off the
-top of my head. [9] So rather than just putting a comment in the test,
-we can explicitly say it's never going to work and skip the test.
-
- use Test::More tests => 7;
- use Date::ICal;
-
- # Make sure epoch time is being handled sanely.
- my $t1 = Date::ICal->new( epoch => 0 );
- is( $t1->epoch, 0, "Epoch time of 0" );
-
- SKIP: {
- skip('epoch to ICal not working on MacOS', 6)
- if $^O eq 'MacOS';
-
- is( $t1->ical, '19700101Z', " epoch to ical" );
-
- is( $t1->year, 1970, " year()" );
- is( $t1->month, 1, " month()" );
- is( $t1->day, 1, " day()" );
-
- # like the tests above, but starting with ical instead of epoch
- my $t2 = Date::ICal->new( ical => '19700101Z' );
- is( $t2->ical, '19700101Z', "Start of epoch in ICal notation" );
-
- is( $t2->epoch, 0, " and back to ICal" );
- }
-
-A little bit of magic happens here. When running on anything but
-MacOS, all the tests run normally. But when on MacOS, C<skip()> causes
-the entire contents of the SKIP block to be jumped over. It's never
-run. Instead, it prints special output that tells Test::Harness that
-the tests have been skipped.
-
- 1..7
- ok 1 - Epoch time of 0
- ok 2 # skip epoch to ICal not working on MacOS
- ok 3 # skip epoch to ICal not working on MacOS
- ok 4 # skip epoch to ICal not working on MacOS
- ok 5 # skip epoch to ICal not working on MacOS
- ok 6 # skip epoch to ICal not working on MacOS
- ok 7 # skip epoch to ICal not working on MacOS
-
-This means your tests won't fail on MacOS. This means less emails
-from MacPerl users telling you about failing tests that you know will
-never work. You've got to be careful with skip tests. These are for
-tests which don't work and I<never will>. It is not for skipping
-genuine bugs (we'll get to that in a moment).
-
-The tests are wholly and completely skipped. [10] This will work.
-
- SKIP: {
- skip("I don't wanna die!");
-
- die, die, die, die, die;
- }
-
-
-=head2 Todo tests
-
-Thumbing through the Date::ICal man page, I came across this:
-
- ical
-
- $ical_string = $ical->ical;
-
- Retrieves, or sets, the date on the object, using any
- valid ICal date/time string.
-
-"Retrieves or sets". Hmmm, didn't see a test for using C<ical()> to set
-the date in the Date::ICal test suite. So I'll write one.
-
- use Test::More tests => 1;
- use Date::ICal;
-
- my $ical = Date::ICal->new;
- $ical->ical('20201231Z');
- is( $ical->ical, '20201231Z', 'Setting via ical()' );
-
-run that and I get
-
- 1..1
- not ok 1 - Setting via ical()
- # Failed test (- at line 6)
- # got: '20010814T233649Z'
- # expected: '20201231Z'
- # Looks like you failed 1 tests of 1.
-
-Whoops! Looks like it's unimplemented. Let's assume we don't have
-the time to fix this. [11] Normally, you'd just comment out the test
-and put a note in a todo list somewhere. Instead, we're going to
-explicitly state "this test will fail" by wrapping it in a C<TODO> block.
-
- use Test::More tests => 1;
-
- TODO: {
- local $TODO = 'ical($ical) not yet implemented';
-
- my $ical = Date::ICal->new;
- $ical->ical('20201231Z');
-
- is( $ical->ical, '20201231Z', 'Setting via ical()' );
- }
-
-Now when you run, it's a little different:
-
- 1..1
- not ok 1 - Setting via ical() # TODO ical($ical) not yet implemented
- # got: '20010822T201551Z'
- # expected: '20201231Z'
-
-Test::More doesn't say "Looks like you failed 1 tests of 1". That '#
-TODO' tells Test::Harness "this is supposed to fail" and it treats a
-failure as a successful test. So you can write tests even before
-you've fixed the underlying code.
-
-If a TODO test passes, Test::Harness will report it "UNEXPECTEDLY
-SUCCEEDED". When that happens, you simply remove the TODO block with
-C<local $TODO> and turn it into a real test.
-
-
-=head2 Testing with taint mode.
-
-Taint mode is a funny thing. It's the globalest of all global
-features. Once you turn it on, it affects I<all> code in your program
-and I<all> modules used (and all the modules they use). If a single
-piece of code isn't taint clean, the whole thing explodes. With that
-in mind, it's very important to ensure your module works under taint
-mode.
-
-It's very simple to have your tests run under taint mode. Just throw
-a C<-T> into the C<#!> line. Test::Harness will read the switches
-in C<#!> and use them to run your tests.
-
- #!/usr/bin/perl -Tw
-
- ...test normally here...
-
-So when you say C<make test> it will be run with taint mode and
-warnings on.
-
-
-=head1 FOOTNOTES
-
-=over 4
-
-=item 1
-
-The first number doesn't really mean anything, but it has to be 1.
-It's the second number that's important.
-
-=item 2
-
-For those following along at home, I'm using version 1.31. It has
-some bugs, which is good -- we'll uncover them with our tests.
-
-=item 3
-
-You can actually take this one step further and test the manual
-itself. Have a look at B<Test::Inline> (formerly B<Pod::Tests>).
-
-=item 4
-
-Yes, there's a mistake in the test suite. What! Me, contrived?
-
-=item 5
-
-We'll get to testing the contents of lists later.
-
-=item 6
-
-But what happens if your test program dies halfway through?! Since we
-didn't say how many tests we're going to run, how can we know it
-failed? No problem, Test::More employs some magic to catch that death
-and turn the test into a failure, even if every test passed up to that
-point.
-
-=item 7
-
-I cleaned it up a little.
-
-=item 8
-
-Most Operating Systems record time as the number of seconds since a
-certain date. This date is the beginning of the epoch. Unix's starts
-at midnight January 1st, 1970 GMT.
-
-=item 9
-
-MacOS's epoch is midnight January 1st, 1904. VMS's is midnight,
-November 17th, 1858, but vmsperl emulates the Unix epoch so it's not a
-problem.
-
-=item 10
-
-As long as the code inside the SKIP block at least compiles. Please
-don't ask how. No, it's not a filter.
-
-=item 11
-
-Do NOT be tempted to use TODO tests as a way to avoid fixing simple
-bugs!
-
-=back
-
-=head1 AUTHORS
-
-Michael G Schwern E<lt>schwern@pobox.comE<gt> and the perl-qa dancers!
-
-=head1 COPYRIGHT
-
-Copyright 2001 by Michael G Schwern E<lt>schwern@pobox.comE<gt>.
-
-This documentation is free; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-Irrespective of its distribution, all code examples in these files
-are hereby placed into the public domain. You are permitted and
-encouraged to use this code in your own programs for fun
-or for profit as you see fit. A simple comment in the code giving
-credit would be courteous but is not required.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Tk.pod b/Master/tlpkg/tlperl/lib/Tk.pod
deleted file mode 100644
index 1024b3b4c5b..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk.pod
+++ /dev/null
@@ -1,862 +0,0 @@
-=head1 NAME
-
-Tk - a graphical user interface toolkit for Perl
-
-=head1 SYNOPSIS
-
- use Tk;
- $top = new MainWindow;
- MainLoop;
-
-=head1 DESCRIPTION
-
-The Perl/Tk manual is split up into a number of sections:
-
-=head2 Introduction
-
-=over 4
-
-=item *
-
-L<Tk::overview|Tk::overview>
-
-=item *
-
-L<Tk::UserGuide|Tk::UserGuide>
-
-=back
-
-=head2 Tk Geometry Management
-
-=over 4
-
-=item *
-
-L<Tk::Adjuster|Tk::Adjuster>
-
-=item *
-
-L<Tk::form|Tk::form>
-
-=item *
-
-L<Tk::grid|Tk::grid>
-
-=item *
-
-L<Tk::pack|Tk::pack>
-
-=item *
-
-L<Tk::place|Tk::place>
-
-=item *
-
-L<Tk::Table|Tk::Table>
-
-=item *
-
-L<Tk::Tiler|Tk::Tiler>
-
-=item *
-
-L<Tk::Wm|Tk::Wm>
-
-=back
-
-=head2 Binding Events and Callbacks
-
-=over 4
-
-=item *
-
-L<Tk::after|Tk::after>
-
-=item *
-
-L<Tk::bind|Tk::bind>
-
-=item *
-
-L<Tk::bindtags|Tk::bindtags>
-
-=item *
-
-L<Tk::callbacks|Tk::callbacks>
-
-=item *
-
-L<Tk::Error|Tk::Error>
-
-=item *
-
-L<Tk::event|Tk::event>
-
-=item *
-
-L<Tk::exit|Tk::exit>
-
-=item *
-
-L<Tk::fileevent|Tk::fileevent>
-
-=item *
-
-L<Tk::IO|Tk::IO>
-
-=back
-
-=head2 Tk Image Classes
-
-=over 4
-
-=item *
-
-L<Tk::Animation|Tk::Animation>
-
-=item *
-
-L<Tk::Bitmap|Tk::Bitmap>
-
-=item *
-
-L<Tk::Compound|Tk::Compound>
-
-=item *
-
-L<Tk::Image|Tk::Image>
-
-=item *
-
-L<Tk::JPEG|Tk::JPEG>
-
-=item *
-
-L<Tk::Photo|Tk::Photo>
-
-=item *
-
-L<Tk::Pixmap|Tk::Pixmap>
-
-=item *
-
-L<Tk::PNG|Tk::PNG>
-
-=back
-
-=head2 Tk Widget Classes
-
-=over 4
-
-=item *
-
-L<Tk::Button|Tk::Button>
-
-=item *
-
-L<Tk::Canvas|Tk::Canvas>
-
-=item *
-
-L<Tk::Checkbutton|Tk::Checkbutton>
-
-=item *
-
-L<Tk::Entry|Tk::Entry>
-
-=item *
-
-L<Tk::Frame|Tk::Frame>
-
-=item *
-
-L<Tk::HList|Tk::HList>
-
-=item *
-
-L<Tk::Label|Tk::Label>
-
-=item *
-
-L<Tk::Listbox|Tk::Listbox>
-
-=item *
-
-L<Tk::Menu|Tk::Menu>
-
-=item *
-
-L<Tk::Menubutton|Tk::Menubutton>
-
-=item *
-
-L<Tk::Message|Tk::Message>
-
-=item *
-
-L<Tk::Optionmenu|Tk::Optionmenu>
-
-=item *
-
-L<Tk::Radiobutton|Tk::Radiobutton>
-
-=item *
-
-L<Tk::Scale|Tk::Scale>
-
-=item *
-
-L<Tk::Scrollbar|Tk::Scrollbar>
-
-=item *
-
-L<Tk::Text|Tk::Text>
-
-=item *
-
-L<Tk::Toplevel|Tk::Toplevel>
-
-=back
-
-=head2 Tix Extensions
-
-=over 4
-
-=item *
-
-L<Tk::Balloon|Tk::Balloon>
-
-=item *
-
-L<Tk::BrowseEntry|Tk::BrowseEntry>
-
-=item *
-
-L<Tk::DialogBox|Tk::DialogBox>
-
-=item *
-
-L<Tk::DirTree|Tk::DirTree>
-
-=item *
-
-L<Tk::DItem|Tk::DItem>
-
-=item *
-
-L<Tk::InputO|Tk::InputO>
-
-=item *
-
-L<Tk::LabFrame|Tk::LabFrame>
-
-=item *
-
-L<Tk::Mwm|Tk::Mwm>
-
-=item *
-
-L<Tk::NoteBook|Tk::NoteBook>
-
-=item *
-
-L<Tk::TixGrid|Tk::TixGrid>
-
-=item *
-
-L<Tk::tixWm|Tk::tixWm>
-
-=item *
-
-L<Tk::TList|Tk::TList>
-
-=item *
-
-L<Tk::Tree|Tk::Tree>
-
-=back
-
-=head2 Tk Generic Methods
-
-=over 4
-
-=item *
-
-L<Tk::Font|Tk::Font>
-
-=item *
-
-L<Tk::send|Tk::send>
-
-=item *
-
-L<Tk::tkvars|Tk::tkvars>
-
-=item *
-
-L<Tk::Widget|Tk::Widget>
-
-=item *
-
-L<Tk::X11Font|Tk::X11Font>
-
-=back
-
-=head2 User Interaction
-
-=over 4
-
-=item *
-
-L<Tk::DropSite|Tk::DropSite>
-
-=item *
-
-L<Tk::Clipboard|Tk::Clipboard>
-
-=item *
-
-L<Tk::focus|Tk::focus>
-
-=item *
-
-L<Tk::grab|Tk::grab>
-
-=item *
-
-L<Tk::selection|Tk::selection>
-
-=back
-
-=head2 Creating and Configuring Widgets
-
-=over 4
-
-=item *
-
-L<Tk::CmdLine|Tk::CmdLine>
-
-=item *
-
-L<Tk::MainWindow|Tk::MainWindow>
-
-=item *
-
-L<Tk::option|Tk::option>
-
-=item *
-
-L<Tk::options|Tk::options>
-
-=item *
-
-L<Tk::palette|Tk::palette>
-
-=item *
-
-L<Tk::Xrm|Tk::Xrm>
-
-=back
-
-=head2 Popups and Dialogs
-
-=over 4
-
-=item *
-
-L<Tk::chooseColor|Tk::chooseColor>
-
-=item *
-
-L<Tk::chooseDirectory|Tk::chooseDirectory>
-
-=item *
-
-L<Tk::ColorEditor|Tk::ColorEditor>
-
-=item *
-
-L<Tk::Dialog|Tk::Dialog>
-
-=item *
-
-L<Tk::DialogBox|Tk::DialogBox>
-
-=item *
-
-L<Tk::FBox|Tk::FBox>
-
-=item *
-
-L<Tk::FileSelect|Tk::FileSelect>
-
-=item *
-
-L<Tk::getOpenFile|Tk::getOpenFile>
-
-=item *
-
-L<Tk::messageBox|Tk::messageBox>
-
-=item *
-
-L<Tk::MsgBox|Tk::MsgBox>
-
-=back
-
-=head2 Derived Widgets
-
-=over 4
-
-=item *
-
-L<Tk::composite|Tk::composite>
-
-=item *
-
-L<Tk::configspec|Tk::configspec>
-
-=item *
-
-L<Tk::Derived|Tk::Derived>
-
-=item *
-
-L<Tk::mega|Tk::mega>
-
-=item *
-
-L<Tk::ROText|Tk::ROText>
-
-=item *
-
-L<Tk::Scrolled|Tk::Scrolled>
-
-=item *
-
-L<Tk::TextUndo|Tk::TextUndo>
-
-=item *
-
-L<Tk::Reindex|Tk::Reindex>
-
-=item *
-
-L<Tk::Pane|Tk::Pane>
-
-=item *
-
-L<Tk::ProgressBar|Tk::ProgressBar>
-
-=back
-
-=head2 C Programming
-
-=over 4
-
-=item *
-
-Internals
-
-=item *
-
-pTk
-
-=item *
-
-3DBorder
-
-=item *
-
-BackgdErr
-
-=item *
-
-BindTable
-
-=item *
-
-CanvPsY
-
-=item *
-
-CanvTkwin
-
-=item *
-
-CanvTxtInfo
-
-=item *
-
-Clipboard
-
-=item *
-
-ClrSelect
-
-=item *
-
-ConfigWidg
-
-=item *
-
-ConfigWind
-
-=item *
-
-CoordToWin
-
-=item *
-
-CrtErrHdlr
-
-=item *
-
-CrtGenHdlr
-
-=item *
-
-CrtImgType
-
-=item *
-
-CrtItemType
-
-=item *
-
-CrtMainWin
-
-=item *
-
-CrtPhImgFmt
-
-=item *
-
-CrtSelHdlr
-
-=item *
-
-CrtWindow
-
-=item *
-
-DeleteImg
-
-=item *
-
-DoOneEvent
-
-=item *
-
-DoWhenIdle
-
-=item *
-
-DrawFocHlt
-
-=item *
-
-EventHndlr
-
-=item *
-
-EventInit
-
-=item *
-
-FileHndlr
-
-=item *
-
-FindPhoto
-
-=item *
-
-FontId
-
-=item *
-
-FreeXId
-
-=item *
-
-GeomReq
-
-=item *
-
-GetAnchor
-
-=item *
-
-GetBitmap
-
-=item *
-
-GetCapStyl
-
-=item *
-
-GetClrmap
-
-=item *
-
-GetColor
-
-=item *
-
-GetCursor
-
-=item *
-
-GetFont
-
-=item *
-
-GetFontStr
-
-=item *
-
-GetGC
-
-=item *
-
-GetImage
-
-=item *
-
-GetJoinStl
-
-=item *
-
-GetJustify
-
-=item *
-
-GetOption
-
-=item *
-
-GetPixels
-
-=item *
-
-GetPixmap
-
-=item *
-
-GetRelief
-
-=item *
-
-GetRootCrd
-
-=item *
-
-GetScroll
-
-=item *
-
-GetSelect
-
-=item *
-
-GetUid
-
-=item *
-
-GetVisual
-
-=item *
-
-GetVRoot
-
-=item *
-
-HandleEvent
-
-=item *
-
-IdToWindow
-
-=item *
-
-ImgChanged
-
-=item *
-
-InternAtom
-
-=item *
-
-MainLoop
-
-=item *
-
-MaintGeom
-
-=item *
-
-MainWin
-
-=item *
-
-ManageGeom
-
-=item *
-
-MapWindow
-
-=item *
-
-MeasureChar
-
-=item *
-
-MoveToplev
-
-=item *
-
-Name
-
-=item *
-
-NameOfImg
-
-=item *
-
-OwnSelect
-
-=item *
-
-ParseArgv
-
-=item *
-
-Preserve
-
-=item *
-
-QWinEvent
-
-=item *
-
-Restack
-
-=item *
-
-RestrictEv
-
-=item *
-
-SetAppName
-
-=item *
-
-SetClass
-
-=item *
-
-SetGrid
-
-=item *
-
-SetVisual
-
-=item *
-
-Sleep
-
-=item *
-
-StrictMotif
-
-=item *
-
-TextLayout
-
-=item *
-
-TimerHndlr
-
-=item *
-
-Tk_Init
-
-=item *
-
-WindowId
-
-=back
-
-=head2 Implementation
-
-=over 4
-
-=item *
-
-L<Tk::Eventloop|Tk::Eventloop>
-
-=item *
-
-L<Tk::Menu::Item|Tk::Menu::Item>
-
-=item *
-
-L<Tk::Submethods|Tk::Submethods>
-
-=item *
-
-L<Tk::WidgetDemo|Tk::WidgetDemo>
-
-=item *
-
-L<Tk::widgets|Tk::widgets>
-
-=back
-
-=head2 Experimental Modules
-
-=over 4
-
-=item *
-
-L<Tk::Common|Tk::Common>
-
-=item *
-
-L<Tk::SunConst|Tk::SunConst>
-
-=item *
-
-L<Tk::WinPhoto|Tk::WinPhoto>
-
-=back
-
-=head2 Other Modules and Languages
-
-=over 4
-
-=item *
-
-Tk::Compile
-
-=item *
-
-L<Tk::Tcl-perl|Tk::Tcl-perl>
-
-=item *
-
-L<Tk::X|Tk::X>
-
-=back
-
-
-=head1 AUTHOR
-
-Nick Ing-Simmons
-
-=head1 SEE ALSO
-
-L<perl>, L<wish(1)>.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Tk/804delta.pod b/Master/tlpkg/tlperl/lib/Tk/804delta.pod
deleted file mode 100644
index 1472f38c86b..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/804delta.pod
+++ /dev/null
@@ -1,110 +0,0 @@
-=head1 NAME
-
-Tk::804delta - what is new for perl/Tk 804
-
-=head1 DESCRIPTION
-
-This document describes differences between the Tk800 series and the
-Tk804 series.
-
-=head1 Incompatible Changes
-
-In Tk804.028, there are some additional incompatible changes:
-
-Return values of some B<Tk::Wm> methods (e.g. B<aspect>, B<wmGrid>,
-B<iconposition>, B<resizable> ...) were changed from returning tclish
-lists (e.g. "1 2 3 4") to perlish lists (1,2,3,4).
-
-B<Tk::Wm::wmTracing> needs argument for setting on/off, without argument
-just return the current value.
-
-All Tk804 releases have the following incompatible changes:
-
-Tk804 will only work with perl 5.8.0 and above. For older perl
-versions look for Tk800.025.
-
-B<curselection> of B<Tk::Listbox> now returns an array reference in
-scalar context. This means you have to write
-
- my(@selected) = $listbox->curselection
-
-or
-
- my(@selected) = @{ $listbox->curselection }
-
-now.
-
-The B<fontActual> method now returns the pixel value instead of the
-point value for B<-size>. Pixel values are expressed as negative
-numbers.
-
-Some enhancements from the E<quot>dashE<quot> patches are lost for now
-(i.e. B<-tile>, B<-troughtile> ...).
-
-The B<-state> option is not available anymore for B<Tk::Text> tags.
-Use B<-elide> instead.
-
-=head1 Enhancements
-
-Tk804 is Unicode-aware.
-
-It is possible to build Tk with Xft support on X11. This is strongly
-recommened if you are planning to make use of Unicode rendering
-capabilities of Tk. It also gives anti-aliased fonts for regular text
-(if you have TrueType or Type1 fonts and they are in your fontconfig
-config file).
-
-The new method B<chooseDirectory> is available as a standard directory
-selector.
-
-B<Tk::PNG> and B<Tk::JPEG> are bundled now with the perl/Tk
-distribution, providing support for the image formats B<png> and
-B<jpeg>.
-
-Improvements to B<Tk::Listbox>: new option B<-activestyle>, new
-methods B<itemconfigure> and B<itemcget>, new virtual event B<<<
-<<ListboxSelect>> >>>.
-
-More tests.
-
-=head1 New Widgets
-
-=over
-
-=item Tk::Labelframe
-
-An alternative to B<Tk::LabFrame>.
-
-=item Tk::Panedwindow
-
-An alternative to B<Tk::Adjuster>.
-
-=item Tk::Spinbox
-
-An alternative to the CPAN module B<Tk::NumEntry>.
-
-=back
-
-=head1 Selected Bug Fixes
-
-=head1 Changed Internals
-
-=head1 Platform Specific Problems
-
-=head1 Future Directions
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.tk newsgroup.
-
-If you believe you have an unreported bug, please send a mail to <ptk@lists.stanford.edu> and/or <nick@ing-simmons.net>. Be sure to trim your bug down
-to a tiny but sufficient test case.
-
-=head1 SEE ALSO
-
-L<Tk>, C<Changes> file in the Perl/Tk distribution.
-
-=cut
-
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Adjuster.pod b/Master/tlpkg/tlperl/lib/Tk/Adjuster.pod
deleted file mode 100644
index 7d094f4e262..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Adjuster.pod
+++ /dev/null
@@ -1,223 +0,0 @@
-
-=head1 NAME
-
-Tk::Adjuster - Allow size of packed widgets to be adjusted by user
-
-=for pm Tk/Adjuster.pm
-
-=for category Tk Geometry Management
-
-=head1 SYNOPSIS
-
-use Tk::Adjuster;
-
-I<$adjuster> = I<$widget>->B<Adjuster>I<(?options?)>;
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<restore>
-
-=item Class: B<Restore>
-
-=item Switch: B<-restore>
-
-Specifies a boolean value that determines whether the Adjuster
-should forcibly attempt to make room
-for itself (by reducing the size of its managed widget) when it is
-unmapped (for example, due to a size change in a top level window).
-The default value is 1.
-
-=item Name: B<side>
-
-=item Class: B<Side>
-
-=item Switch: B<-side>
-
-Specifies the side on which the managed widget lies relative to the
-Adjuster. In conjunction with the pack geometry manager, this relates to
-the side of the master against which the managed widget and the Adjuster
-are packed.
-Must be B<left>, B<right>, B<top>, or B<bottom>. Defaults to B<top>.
-
-=item Name: B<widget>
-
-=item Class: B<Widget>
-
-=item Switch: B<-widget>
-
-Specifies the widget which is to be managed by the Adjuster.
-
-=back
-
-=head1 DESCRIPTION
-
-B<Tk::Adjuster> is a Frame containing a "line" and a "blob".
-
-Dragging with Mouse Button-1 results in a line being dragged
-to indicate new size. Releasing Button-1 submits GeometryRequests
-on behalf of the managed widget which will cause the packer to change the
-widget's size.
-
-If Drag is done with Shift button down, then GeometryRequests are made
-in "real time" so that text-flow effects can be seen, but as a lot more
-work is done behaviour may be sluggish.
-
-If widget is packed with -side => left or -side => right then width is
-adjusted. If packed -side => top or -side => bottom then height is adjusted.
-
-B<packPropagate> is turned off for the master window to prevent adjustment
-changing overall window size. Similarly B<packPropagate> is turned off
-for the managed widget if it has things packed inside it. This is so that
-the GeometryRequests made by B<Tk::Adjuster> are not overridden by pack.
-
-In addition, the managed widget is made non-expandable
-to prevent the geometry manager reallocating freed space in the master
-back to the managed widget.
-Note however that expansion is turned off only after the Adjuster is mapped,
-which allows the managed widget to expand naturally on window creation.
-
-The Tk::Widget method, B<packAdjust>, calls pack on the widget, then
-creates an instance of B<Tk::Adjuster>,
-and packs that "after" the widget. Its use has two disadvantages however: the
-Adjuster widget is not made available to the caller, and
-options cannot be set on the Adjuster. For these reasons, the Tk::Adjuster
-method, B<packAfter> is preferred, but B<packAdjust> is retained
-for backwards compatibility.
-
-=head1 WIDGET METHODS
-
-=over 4
-
-=item I<$adjuster>->B<packAfter>(I<managed_widget, ?pack_options?>)
-
-This command configures the Adjuster's B<-widget> and B<-side> options
-respectively to I<managed_widget> and the B<-side> value specified in
-I<pack_options> (B<top> if not specified). It then packs the Adjuster
-after I<managed_widget>, with B<-fill> set to B<x> or B<y> as appropriate.
-
-=item I<$adjuster>->B<packForget>I<?(boolean)?>
-
-This command calls B<Tk::Widget::packForget> on the Adjuster.
-If a parameter is provided and it has a true boolean value, then
-B<packForget> is also called on the managed widget.
-
-=item I<$adjuster>->B<slave>
-
-This command returns the value I<$adjuster>->I<cget('-widget')>, ie. the
-reference to the managed widget.
-
-=back
-
-=head1 EXAMPLES
-
-B<Using an Adjuster to separate two widgets, whereby the left widget
-is managed, and right widget expands to fill space on a window resize>
-
-a) Using packAfter (preferred interface)
-
- use Tk;
- use Tk::Adjuster;
-
- my $f = MainWindow->new;
- my $lst1 = $f->Listbox();
- my $adj1 = $f->Adjuster();
- my $lst2 = $f->Listbox();
-
- my $side = 'left';
- $lst1->pack(-side => $side, -fill => 'both', -expand => 1);
- $adj1->packAfter($lst1, -side => $side);
- $lst2->pack(-side => $side, -fill => 'both', -expand => 1);
- MainLoop;
-
-b) Using packAdjust
-
- use Tk;
- use Tk::Adjuster;
-
- my $f = MainWindow->new;
- my $lst1 = $f->Listbox();
- my $lst2 = $f->Listbox();
-
- my $side = 'left';
- $lst1->packAdjust(-side => $side, -fill => 'both');
- $lst2->pack (-side => $side, -fill => 'both', -expand => 1);
- MainLoop;
-
-c) Using the standard Tk::Widget::pack
-
- use Tk;
- use Tk::Adjuster;
-
- my $f = MainWindow->new;
- my $side = 'left';
- my $lst1 = $f->Listbox();
- my $adj = $f->Adjuster(-widget => $lst1, -side => $side);
- my $lst2 = $f->Listbox();
-
- $lst1->pack(-side => $side, -fill => 'both', -expand => 1);
- $adj->pack (-side => $side, -fill => 'y');
- $lst2->pack(-side => $side, -fill => 'both', -expand => 1);
-
- MainLoop;
-
-Changing the above examples so that $side has the value 'right' means the
-left widget expands to fill space on a window resize.
-
-Changing the above examples so that $side has the value 'top'
-produces a testcase with a horizontal Adjuster.
-Here the bottom widget expands to fill space on a window resize.
-Packing to the 'bottom' makes the top widget expand to fill space on window
-resize.
-
-B<Using -restore =E<gt> 0 for multiple columns>
-
-In the case of multiple columns (or rows) the "restore" functionality of the
-Adjuster can be inconvenient. When the user adjusts the width of one column
-and thereby pushes the Adjuster of another column off the window, this
-adjuster tries to restore itself by reducing the size of its managed widget.
-This has the effect that column widths shrink; and the original size
-is not restored when
-the user reverses the originating change. The B<-restore> option can be
-used to turn off this functionality. (It makes some sense, however, to
-leave B<-restore>
-turned on for the first-packed Adjuster, so that at least one Adjuster
-always remains visible.)
-
- use Tk;
- use Tk::Adjuster;
- my $f = MainWindow->new;
- my $lst1 = $f->Listbox();
- my $adj1 = $f->Adjuster();
- my $lst2 = $f->Listbox();
- my $adj2 = $f->Adjuster(-restore => 0);
- my $lst3 = $f->Listbox();
-
- my $side = 'left';
- $lst1->pack(-side => $side, -fill => 'both', -expand => 1);
- $adj1->packAfter($lst1, -side => $side);
- $lst2->pack(-side => $side, -fill => 'both', -expand => 1);
- $adj2->packAfter($lst2, -side => $side);
- $lst3->pack(-side => $side, -fill => 'both', -expand => 1);
-
- MainLoop;
-
-=head1 BUGS
-
-It is currently not possible to configure the appearance of the Adjuster.
-It would be nice to be able to set the width and relief of the Adjuster "line"
-and the presence/absence of the "blob" on the Adjuster.
-
-Tk::Adjuster works theoretically with the grid geometry manager but there
-are currently some problems which seem to be due to bugs in grid:
-
- a) There's never an Unmap event for the adjuster, so the "restore"
- functionality has no effect.
- b) After adjusting, widgets protrude into the border of the master.
- c) grid('Propagate', 0) on MainWindow has no effect - window shrinks/grows
- when widgets are adjusted.
- d) Widgets shuffle to correct position on startup
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Animation.pod b/Master/tlpkg/tlperl/lib/Tk/Animation.pod
deleted file mode 100644
index 996b035b1c5..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Animation.pod
+++ /dev/null
@@ -1,92 +0,0 @@
-
-=head1 NAME
-
-Tk::Animation - Display sequence of Tk::Photo images
-
-=for pm Tk/Animation.pm
-
-=for category Tk Image Classes
-
-=head1 SYNOPSIS
-
- use Tk::Animation
- my $img = $widget->Animation('-format' => 'gif', -file => 'somefile.gif');
-
- $img->add_frame(@images);
-
- $img->start_animation;
- $img->start_animation( $period );
-
- $img->next_image;
- $img->prev_image;
- $img->set_image( 0 .. $#frames );
-
- $img->pause_animation;
- $img->resume_animation( $period );
-
- $img->fast_forward( $multiplier );
- $img->fast_reverse( $multiplier );
-
- $img->stop_animation;
-
- $img->set_disposal_method( $boolean );
-
-=head1 DESCRIPTION
-
-In the simple case when C<Animation> is passed a GIF89 style GIF with
-multiple 'frames', it will build an internal array of C<Photo> images.
-
-The C<add_frame> method adds images to the sequence. It is provided
-to allow animations to be constructed from separate images.
-All images must be C<Photo>s and should all be the same size.
-
-C<start_animation($period)> then initiates a C<repeat> with specified
-I<$period> to sequence through these images. As for raw C<repeat>
-I<$period> is in milliseconds, for a 50Hz monitor it should be at
-least 20ms. If I<$period> is omitted it is determined from the GIF
-metadata (see below), or if this is not possible it defaults to 100
-milliseconds.
-
-C<stop_animation> cancels the C<repeat> and resets the image to the first
-image in the sequence.
-
-For fine-grained control C<next_image> and C<prev_image> move one frame forward
-or backward. C<set_image> randomly positions the animation to a particular frame.
-
-C<pause_animation> pauses the movie and C<resume_animation> continues from the
-pause point.
-
-C<fast_forward> and C<fast_reverse> speed through the movie either
-forwards or backwards. $multiplier specifies how much faster the
-animation moves.
-
-If L<Image::Info> is installed, then the repeat period time and
-disposal method of GIF animations are determined from the GIF metadata
-directly. Otherwise the disposal method must be set manually by using
-C<set_disposal_method> (1 for blanking the previous images, 0 for
-leaving the previous images as is). The repeat period time may be
-given in the C<start_animation> method.
-
-=head1 NOTES
-
-C<set_disposal_method> was formerly known as C<blank> method, but the
-naming of this method was a mistake.
-
-If the disposal method is not set correctly, either by
-C<set_disposal_method> or by determining from the GIF metadata, then
-the following may happen: By default Animation leaves the previous
-movie frame in the animation photo. Many times overlaying subsequent
-frames produces a composite that looks blurred.
-
-=head1 BUGS
-
-This module should not depend on a module which is not declared as a
-dependency (Image::Info).
-
-The delays between images may vary in a GIF animation. This cannot be
-handled by this module yet.
-
-The handling of the various disposal methods is not correct.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Balloon.pod b/Master/tlpkg/tlperl/lib/Tk/Balloon.pod
deleted file mode 100644
index 9188a9e25a4..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Balloon.pod
+++ /dev/null
@@ -1,293 +0,0 @@
-
-=head1 NAME
-
-Tk::Balloon - pop up help balloons.
-
-=for pm Tixish/Balloon.pm
-
-=for category Tix Extensions
-
-=head1 SYNOPSIS
-
- use Tk::Balloon;
- ...
- $b = $top->Balloon(-statusbar => $status_bar_widget);
-
- # Normal Balloon:
- $b->attach($widget,
- -balloonmsg => "Balloon help message",
- -statusmsg => "Status bar message");
-
- # Balloon attached to entries in a menu widget:
- $b->attach($menu, -state => 'status',
- -msg => ['first menu entry',
- 'second menu entry',
- ...
- ],
- );
-
- # Balloon attached to individual items in a canvas widget:
- $b->attach($canvas, -balloonposition => 'mouse',
- -msg => {'item1' => 'msg1',
- 'tag2' => 'msg2',
- ...
- },
- );
-
- # Balloon attached to items in a listbox widget:
- $b->attach($listbox, -balloonposition => 'mouse',
- -msg => ['first listbox element',
- '2nd listbox element',
- ...
- ],
- );
-
-=head1 DESCRIPTION
-
-B<Balloon> provides the framework to create and attach help
-balloons to various widgets so that when the mouse pauses over the
-widget for more than a specified amount of time, a help balloon is
-popped up.
-
-=head2 Balloons and Menus or Listboxes
-
-If the balloon is attached to a B<Menu> or B<Listbox> widget and the
-message arguments are array references, then each element in the array
-will be the message corresponding to a menu entry or listbox element.
-The balloon message will then be shown for the entry which the mouse
-pauses over. Otherwise it is assumed that the balloon is to be
-attached to the B<Menu> or B<Listbox> as a whole. You can have
-separate status and balloon messages just like normal balloons.
-
-=head2 Balloons and Canvases
-
-If the balloon is attached to a B<Canvas> widget and the message
-arguments are hash references, then each hash key should correspond to
-a canvas item ID or tag and the associated value will correspond to the
-message for that canvas item. The balloon message will then be shown for
-the current item (the one at the position of the mouse). Otherwise it is
-assumed that the balloon is to be attached to the B<Canvas> as a whole.
-You can have separate status and balloon messages just like normal
-balloons.
-
-=head2 Balloons and HLists
-
-If the balloon is attached to a B<HList> widget and the message
-arguments are hash references, then each hash key should correspond to
-a HList path and the associated value will correspond to the message
-for that HList item. The balloon message will then be shown for the
-current item (the one at the position of the mouse). Otherwise it is
-assumed that the balloon is to be attached to the B<HList> as a whole.
-You can have separate status and balloon messages just like normal
-balloons.
-
-=head2 Balloon Position
-
-By default, the balloon pops up at the lower right side of the client.
-If it would extend outside the lower screen border, its positioned at the
-upper right side. If it would extend outside the right screen border
-it's shown on the lower left side of the client. If it would extend
-outside both the lower and the right screen border, it's positioned
-at the upper left side of the client. Thus, the little arrow always
-points to the attached client.
-
-=head1 OPTIONS
-
-B<Balloon> accepts all of the options that the B<Frame> widget
-accepts. In addition, the following options are also recognized.
-
-=over 4
-
-=item B<-initwait>
-
-Specifies the amount of time to wait without activity before
-popping up a help balloon. Specified in milliseconds. Defaults to
-350 milliseconds. This applies to both the popped up balloon and
-the status bar message.
-
-=item B<-state>
-
-Can be one of B<'balloon'>, B<'status'>, B<'both'> or B<'none'>
-indicating that the help balloon, status bar help, both or none
-respectively should be activated when the mouse pauses over the
-client widget. Default is B<'both'>.
-
-=item B<-statusbar>
-
-Specifies the widget used to display the status message. This
-widget should accept the B<-text> option and is typically a
-B<Label>. If the widget accepts the B<-textvariable> option and
-that option is defined then it is used instead of the B<-text>
-option.
-
-=item B<-balloonposition>
-
-Can be one of B<'widget'> or B<'mouse'>. It controls where the balloon
-will popup. B<'widget'> makes the balloon appear at the lower right
-corner of the widget it is attached to (default), and B<'mouse'> makes
-the balloon appear below and to the right of the current mouse position.
-
-=item B<-postcommand>
-
-This option takes a B<CODE> reference which will be executed before the
-balloon and statusbar messages are displayed and should return a true
-or false value to indicate whether you want the balloon to be displayed
-or not. This also lets you control where the balloon is positioned by
-returning a true value that looks like I<X,Y> (matches this regular
-expression: C</^(\d+),(\d+)$/>). If the postcommand returns a value that
-matches that re then those coordinates will be used as the position to
-post the balloon. I<Warning:> this subroutine should return quickly or
-the balloon response will appear slow.
-
-=item B<-cancelcommand>
-
-This option takes a B<CODE> reference which will be executed before the
-balloon and statusbar messages are canceled and should return a true
-or false value to indicate whether you want the balloon to be canceled
-or not. I<Warning:> this subroutine should return quickly or the balloon
-response will appear slow.
-
-=item B<-motioncommand>
-
-This option takes a B<CODE> reference which will be executed for any
-motion event and should return a true or false value to indicate
-whether the currently displayed balloon should be canceled (deactivated).
-If it returns true then the balloon will definitely be canceled, if it
-returns false then it may still be canceled depending the internal rules.
-I<Note:> a new balloon may be posted after the B<-initwait> time
-interval, use the B<-postcommand> option to control that behavior.
-I<Warning:> the subroutine should be extremely fast or the balloon
-response will appear slow and consume a lot of CPU time (it is executed
-every time the mouse moves over the widgets the balloon is attached to).
-
-=item B<-numscreens>
-
-This option accepts an integer 1 or greater. This option should be used
-to avoid disjointed balloons across multiple screens in single logical
-sceen (SLS) mode. This only currently works in the horizontal direction.
-Example: If you are running dual screens in SLS mode then you would set
-this value to 2. Default value is 1.
-
-=back
-
-=head1 METHODS
-
-The B<Balloon> widget supports only three non-standard methods:
-
-=head2 B<attach(>I<widget>, I<options>B<)>
-
-Attaches the widget indicated by I<widget> to the help system. The
-allowed options are:
-
-=over 4
-
-=item B<-statusmsg>
-
-The argument is the message to be shown on the status bar when the
-mouse pauses over this client. If this is not specified, but
-B<-msg> is specified then the message displayed on the status bar
-is the same as the argument for B<-msg>. If you give it a scalar
-reference then it is dereferenced before being displayed. Useful
-if the postcommand is used to change the message.
-
-=item B<-balloonmsg>
-
-The argument is the message to be displayed in the balloon that
-will be popped up when the mouse pauses over this client. As with
-B<-statusmsg> if this is not specified, then it takes its value
-from the B<-msg> specification if any. If neither B<-balloonmsg>
-nor B<-msg> are specified, or they are the empty string then
-no balloon is popped up instead of an empty balloon. If you
-give it a scalar reference then it is dereferenced before being
-displayed. Useful if the postcommand is used to change the message.
-
-=item B<-msg>
-
-The catch-all for B<-statusmsg> and B<-balloonmsg>. This is a
-convenient way of specifying the same message to be displayed in
-both the balloon and the status bar for the client.
-
-=item B<-initwait>
-
-=item B<-state>
-
-=item B<-statusbar>
-
-=item B<-balloonposition>
-
-=item B<-postcommand>
-
-=item B<-cancelcommand>
-
-=item B<-motioncommand>
-
-These options allow you to override the balloon's default value for
-those option for some of the widgets it is attached to. It accepts the
-same values as above and will default to the B<Balloon>'s value.
-
-=back
-
-=head2 B<detach(>I<widget>B<)>
-
-Detaches the specified I<widget> from the help system.
-
-=head2 B<destroy>
-
-Destroys the specified balloon.
-
-=head1 ADVERTISED SUBWIDGETS
-
-The balloon label is advertised as C<message>.
-
-=head1 EXAMPLES
-
-See the balloon demo included with the widget demo script that came with
-the distribution for examples on various ways to use balloons.
-
-=head1 NOTES
-
-Because of the overhead associated with each balloon you create (from
-tracking the mouse movement to know when to activate and deactivate
-them) you will see the best performance (low CPU consumption) if you
-create as few balloons as possible and attach them to as many widgets
-as you can. In other words, don't create a balloon for each widget
-you want to attach one to.
-
-=head1 CAVEATS
-
-Pressing any button will deactivate (cancel) the current balloon,
-if one exists. You can usually make the balloon reappear by moving
-the mouse a little. Creative use of the 3 command options can help
-you out also. If the mouse is over the balloon when a menu is unposted
-then the balloon will remain until you move off of it.
-
-=head1 BUGS
-
-If using balloons attached to listbox entries or canvas items in a
-scrolled widget, then the subwidget have to be used:
-
- $balloon->attach($w->Subwidget("scrolled"), -msg => ...);
-
-=head1 AUTHORS
-
-B<Rajappa Iyer> <rsi@earthling.net> did the original coding.
-
-B<Jason A. Smith> <smithj4@rpi.edu> added support for menus and made some
-other enhancements.
-
-B<Slaven Rezic> <srezic@cpan.org> added support for canvas items.
-
-B<Gerhard Petrowitsch> <gerhard@petrowitsch.de> added intelligent positioning
-
-B<Jack Dunnigan> <dunniganj@cpan.org> Made positioning I<more> intelligent and
-added support for multiple monitors under single logical screen.
-
-=head1 HISTORY
-
-The code and documentation was derived from Balloon.tcl from the
-Tix4.0 distribution by Ioi Lam and modified by the above mentioned
-authors. This code may be redistributed under the same terms as Perl.
-
-=cut
-
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Bitmap.pod b/Master/tlpkg/tlperl/lib/Tk/Bitmap.pod
deleted file mode 100644
index 49bf20ce4b4..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Bitmap.pod
+++ /dev/null
@@ -1,103 +0,0 @@
-# Copyright (c) 1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Bitmap - Images that display two colors
-
-=for category Tk Image Classes
-
-=head1 SYNOPSIS
-
-S< >I<$image> = I<$widget>-E<gt>B<Bitmap>?(I<name>??,I<options>?)
-
-=head1 DESCRIPTION
-
-A bitmap is an image whose pixels can display either of two colors
-or be transparent.
-A bitmap image is defined by four things: a background color,
-a foreground color, and two bitmaps, called the I<source>
-and the I<mask>.
-Each of the bitmaps specifies 0/1 values for a rectangular
-array of pixels, and the two bitmaps must have the same
-dimensions.
-For pixels where the mask is zero, the image displays nothing,
-producing a transparent effect.
-For other pixels, the image displays the foreground color if
-the source data is one and the background color if the source
-data is zero.
-
-=head1 CREATING BITMAPS
-
-Bitmaps are created using I<$widget>-E<gt>B<Bitmap>.
-Bitmaps support the following I<options>:
-
-=over 4
-
-=item B<-background> =E<gt> I<color>
-
-Specifies a background color for the image in any of the standard
-ways accepted by Tk. If this option is set to an empty string
-then the background pixels will be transparent. This effect
-is achieved by using the source bitmap as the mask bitmap, ignoring
-any B<-maskdata> or B<-maskfile> options.
-
-=item B<-data> =E<gt> I<string>
-
-Specifies the contents of the source bitmap as a string.
-The string must adhere to X11 bitmap format (e.g., as generated
-by the B<bitmap> program).
-If both the B<-data> and B<-file> options are specified,
-the B<-data> option takes precedence.
-
-=item B<-file> =E<gt> I<name>
-
-I<name> gives the name of a file whose contents define the
-source bitmap.
-The file must adhere to X11 bitmap format (e.g., as generated
-by the B<bitmap> program).
-
-=item B<-foreground> =E<gt> I<color>
-
-Specifies a foreground color for the image in any of the standard
-ways accepted by Tk.
-
-=item B<-maskdata> =E<gt> I<string>
-
-Specifies the contents of the mask as a string.
-The string must adhere to X11 bitmap format (e.g., as generated
-by the B<bitmap> program).
-If both the B<-maskdata> and B<-maskfile> options are specified,
-the B<-maskdata> option takes precedence.
-
-=item B<-maskfile> =E<gt> I<name>
-
-I<name> gives the name of a file whose contents define the
-mask.
-The file must adhere to X11 bitmap format (e.g., as generated
-by the B<bitmap> program).
-
-=back
-
-=head1 IMAGE METHODS
-
-When a bitmap image is created, Tk also creates a new object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-
-=head1 SEE ALSO
-
-L<Tk::Image|Tk::Image>
-L<Tk::Pixmap|Tk::Pixmap>
-L<Tk::Photo|Tk::Photo>
-
-=head1 KEYWORDS
-
-bitmap, image
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Tk/BrowseEntry.pod b/Master/tlpkg/tlperl/lib/Tk/BrowseEntry.pod
deleted file mode 100644
index 98a547c4084..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/BrowseEntry.pod
+++ /dev/null
@@ -1,210 +0,0 @@
-
-=head1 NAME
-
-Tk::BrowseEntry - entry widget with popup choices.
-
-=for pm Tixish/BrowseEntry.pm
-
-=for category Tix Extensions
-
-=head1 SYNOPSIS
-
- use Tk::BrowseEntry;
-
- $b = $frame->BrowseEntry(-label => "Label", -variable => \$var);
- $b->insert("end", "opt1");
- $b->insert("end", "opt2");
- $b->insert("end", "opt3");
- ...
- $b->pack;
-
-=head1 SUPER-CLASS
-
-The C<BrowseEntry> class is derived from the C<Frame> class and
-inherits all the methods, options and subwidgets of its super-class.
-By default, options and methods are delegated to the entry subwidget.
-
-=head1 DESCRIPTION
-
-BrowseEntry is a poor man's ComboBox. It may be considered an
-enhanced version of LabEntry which provides a button to popup the
-choices of the possible values that the Entry may
-take. BrowseEntry supports all the options LabEntry supports
-except B<-textvariable>. This is replaced by B<-variable>. Other
-options that BrowseEntry supports:
-
-=over 4
-
-=item B<-arrowimage>
-
-Specifies the image to be used in the arrow button beside the entry
-widget. The default is an downward arrow image in the file cbxarrow.xbm
-
-=item B<-autolimitheight>
-
-If set to a true value, then the height of the listbox will be at most
-the number of entries in the list. The overall maximum of
-C<-listheight> still applies.
-
-=item B<-autolistwidth>
-
-If set to a true value, then the width of the listbox will match the
-width of the largest entry.
-
-=item B<-browsecmd>
-
-Specifies a function to call when a selection is made in the
-popped up listbox. It is passed the widget and the text of the
-entry selected. This function is called after the entry variable
-has been assigned the value.
-
-=item B<-browse2cmd>
-
-Like C<-browsecmd>, but the callback is called with the listbox index
-instead of the selected value.
-
-=item B<-buttontakefocus>
-
-Set the C<-takefocus> option of the button subwidget.
-
-=item B<-choices>
-
-Specifies the list of choices to pop up. This is a reference to an
-array of strings specifying the choices.
-
-=item B<-colorstate>
-
-The state of the widget is reflected by color. A non-editable entry
-widget will get a light gray background, while an editable entry will
-be almost white. [This may change]
-
-=item B<-listcmd>
-
-Specifies the function to call when the button next to the entry
-is pressed to popup the choices in the listbox. This is called before
-popping up the listbox, so can be used to populate the entries in
-the listbox.
-
-=item B<-listheight>
-
-Set the height of the listbox. See also C<-autolimitheight>.
-
-=item B<-listwidth>
-
-Specifies the width of the popup listbox.
-
-=item B<-state>
-
-Specifies one of three states for the widget: normal, readonly, or
-disabled. If the widget is disabled then the value may not be changed
-and the arrow button won't activate. If the widget is readonly, the
-entry may not be edited, but it may be changed by choosing a value
-from the popup listbox. normal is the default.
-
-=item B<-style>
-
-Set the "style" of the widget. Permitted values are C<MSWin32> and
-C<unix>. By default C<-style> is set to the current platform. Widgets
-with the C<unix> style will look like a normal C<BrowseEntry> widget,
-whereas with the C<MSWin32> style the arrow will look close to the
-Windows' standard combobox widget, while moving the mouse the entries
-will be highlighted, and probably includes other changes.
-
-=item B<-variable>
-
-Specifies the variable in which the entered value is to be stored.
-
-=back
-
-=head1 METHODS
-
-=over 4
-
-=item B<insert(>I<index>, I<string>B<)>
-
-Inserts the text of I<string> at the specified I<index>. This string
-then becomes available as one of the choices.
-
-=item B<delete(>I<index1>, I<index2>B<)>
-
-Deletes items from I<index1> to I<index2>.
-
-=item B<get>
-
-The get method is delegated to the choices listbox.
-
-=back
-
-=head1 ADVERTISED WIDGETS
-
-The following widgets are advertised:
-
-=over
-
-=item entry
-
-The entry widget.
-
-=item arrow
-
-The button with the arrow image.
-
-=item choices
-
-The toplevel widget containing the choice listbox.
-
-=item slistbox
-
-The scrolled listbox with the choices.
-
-=back
-
-=head1 SUBCLASSING
-
-To make subclassing easier, the following methods may be overridden to
-use other standard widgets in composing the mega widget:
-
-=over
-
-=item LabEntryWidget
-
-A widget class compatible with Tk::LabEntry used for the entry.
-
-=item ButtonWidget
-
-A widget class compatible with Tk::Button used for the arrow button.
-
-=item ListboxWidget
-
-A widget class compatible with Tk::Listbox used for the choices
-listbox.
-
-=back
-
-For example to use a C<NumEntry> widget (from the Tk-GBARR CPAN
-distribution) instead of the normal C<Entry> widget:
-
- package Tk::NumBrowseEntry;
- use base qw(Tk::BrowseEntry);
- use Tk::NumEntry;
- Construct Tk::Widget 'NumBrowseEntry';
- sub LabEntryWidget { "NumEntry" }
-
-=head1 BUGS
-
-BrowseEntry should really provide more of the ComboBox options.
-
-=head1 AUTHOR
-
-B<Rajappa Iyer> rsi@earthling.net
-
-B<Chris Dean> ctdean@cogit.com made additions.
-
-More additions by B<Slaven Rezic> slaven@rezic.de
-
-This code was inspired by ComboBox.tcl in Tix4.0 by Ioi Lam and
-bears more than a passing resemblance to ComboBox code. This may
-be distributed under the same conditions as Perl.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Button.pod b/Master/tlpkg/tlperl/lib/Tk/Button.pod
deleted file mode 100644
index 2eb6401ca9d..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Button.pod
+++ /dev/null
@@ -1,255 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Button - Create and manipulate Button widgets
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
-I<$button> = I<$parent>-E<gt>B<Button>(?I<options>?);
-
-=head1 STANDARD OPTIONS
-
-B<-activebackground>
-B<-activeforeground>
-B<-anchor>
-B<-background>
-B<-bitmap>
-B<-borderwidth>
-B<-compound>
-B<-cursor>
-B<-disabledforeground>
-B<-font>
-B<-foreground>
-B<-highlightbackground>
-B<-highlightcolor>
-B<-highlightthickness>
-B<-image>
-B<-justify>
-B<-padx>
-B<-pady>
-B<-relief>
-B<-repeatdelay>
-B<-repeatinterval>
-B<-takefocus>
-B<-text>
-B<-textvariable>
-B<-underline>
-B<-wraplength>
-
-See L<Tk::options> for details of the standard options.
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<command>
-
-=item Class: B<Command>
-
-=item Switch: B<-command>
-
-Specifies a L<Perl/Tk callback|Tk::callbacks> to associate with the
-button. This command is typically invoked when mouse button 1 is
-released over the button window.
-
-=item Command-Line Name: B<-compound>
-
-=item Database Name: B<compound>
-
-=item Database Class: B<Compound>
-
-Specifies whether the button should display both an image and text,
-and if so, where the image should be placed relative to the text.
-Valid values for this option are B<bottom>, B<center>, B<left>,
-B<none>, B<right> and B<top>. The default value is B<none>, meaning
-that the button will display either an image or text, depending on the
-values of the -image and -bitmap options.
-
-=item Name: B<default>
-
-=item Class: B<Default>
-
-=item Switch: B<-default>
-
-Specifies one of three states for the default ring: B<normal>,
-B<active>, or B<disabled>. In active state, the button is drawn
-with the platform specific appearance for a default button. In normal
-state, the button is drawn with the platform specific appearance for a
-non-default button, leaving enough space to draw the default button
-appearance. The normal and active states will result in buttons of
-the same size. In disabled state, the button is drawn with the
-non-default button appearance without leaving space for the default
-appearance. The disabled state may result in a smaller button than
-the active state.
-ring.
-
-=item Name: B<height>
-
-=item Class: B<Height>
-
-=item Switch: B<-height>
-
-Specifies a desired height for the button.
-If an image or bitmap is being displayed in the button then the value is in
-screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>);
-for text it is in lines of text.
-If this option isn't specified, the button's desired height is computed
-from the size of the image or bitmap or text being displayed in it.
-
-=item Command-Line Name: B<-overrelief>
-
-=item Database Name: B<overRelief>
-
-=item Database Class: B<OverRelief>
-
-Specifies an alternative relief for the button, to be used when
-the mouse cursor is over the widget. This option can be used to
-make toolbar buttons, by configuring B<-relief flat -overrelief
-raised>. If the value of this option is the empty string, then
-no alternative relief is used when the mouse cursor is over the
-button. The empty string is the default value.
-
-=item Name: B<state>
-
-=item Class: B<State>
-
-=item Switch: B<-state>
-
-Specifies one of three states for the button: B<normal>, B<active>,
-or B<disabled>. In normal state the button is displayed using the
-B<foreground> and B<background> options. The active state is
-typically used when the pointer is over the button. In active state
-the button is displayed using the B<activeForeground> and
-B<activeBackground> options. Disabled state means that the button
-should be insensitive: the default bindings will refuse to activate
-the widget and will ignore mouse button presses.
-In this state the B<disabledForeground> and
-B<background> options determine how the button is displayed.
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-=item Switch: B<-width>
-
-Specifies a desired width for the button.
-If an image or bitmap is being displayed in the button then the value is in
-screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>);
-for text it is in characters.
-If this option isn't specified, the button's desired width is computed
-from the size of the image or bitmap or text being displayed in it.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Button> method creates a new window (given by the
-$widget argument) and makes it into a button widget.
-Additional
-options, described above, may be specified on the command line
-or in the option database
-to configure aspects of the button such as its colors, font,
-text, and initial relief. The B<button> command returns its
-$widget argument. At the time this command is invoked,
-there must not exist a window named $widget, but
-$widget's parent must exist.
-
-A button is a widget that displays a textual string, bitmap or image.
-If text is displayed, it must all be in a single font, but it
-can occupy multiple lines on the screen (if it contains newlines
-or if wrapping occurs because of the B<-wraplength> option) and
-one of the characters may optionally be underlined using the
-B<-underline> option.
-It can display itself in either of three different ways, according
-to
-the B<-state> option;
-it can be made to appear raised, sunken, or flat;
-and it can be made to flash. When a user invokes the
-button (by pressing mouse button 1 with the cursor over the
-button), then the L<perl/Tk callback|Tk::callbacks> specified in the B<-command>
-option is invoked.
-
-=head1 WIDGET METHODS
-
-The B<Button> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-The following additional methods are available for button widgets:
-
-=over 4
-
-=item I<$button>-E<gt>B<flash>
-
-Flash the button. This is accomplished by redisplaying the button
-several times, alternating between active and normal colors. At
-the end of the flash the button is left in the same normal/active
-state as when the command was invoked.
-This command is ignored if the button's state is B<disabled>.
-
-=item I<$button>-E<gt>B<invoke>
-
-Invoke the L<callback|Tk::callbacks> associated with the buttons
-B<-command> option, if there is one.
-The return value is the return value from the callback, or the
-undefined value if there is no callback associated with the button.
-This command is ignored if the button's state is B<disabled>.
-
-=back
-
-=head1 DEFAULT BINDINGS
-
-Tk automatically creates class bindings for buttons that give them
-default behavior:
-
-=over 4
-
-=item [1]
-
-A button activates whenever the mouse passes over it and deactivates
-whenever the mouse leaves the button.
-Under Windows, this binding is only active when mouse button 1 has
-been pressed over the button.
-
-=item [2]
-
-A button's relief is changed to sunken whenever mouse button 1 is
-pressed over the button, and the relief is restored to its original
-value when button 1 is later released.
-
-=item [3]
-
-If mouse button 1 is pressed over a button and later released over
-the button, the button is invoked. However, if the mouse is not
-over the button when button 1 is released, then no invocation occurs.
-
-=item [4]
-
-When a button has the input focus, the space key causes the button
-to be invoked.
-
-If the button's state is B<disabled> then none of the above
-actions occur: the button is completely non-responsive.
-
-The behavior of buttons can be changed by defining new bindings for
-individual widgets or by redefining the class bindings.
-
-=back
-
-=head1 KEYWORDS
-
-button, widget
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Canvas.pod b/Master/tlpkg/tlperl/lib/Tk/Canvas.pod
deleted file mode 100644
index daf4cf7f32e..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Canvas.pod
+++ /dev/null
@@ -1,2394 +0,0 @@
-# Copyright (c) 1992-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-
-=head1 NAME
-
-Tk::Canvas - Create and manipulate Canvas widgets
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
-I<$canvas> = I<$parent>-E<gt>B<Canvas>(?I<options>?);
-
-=head1 STANDARD OPTIONS
-
-B<-background> B<-highlightthickness> B<-insertwidth> B<-state>
-B<-borderwidth> B<-insertbackground> B<-relief> B<-tile>
-B<-cursor> B<-insertborderwidth> B<-selectbackground> B<-takefocus>
-B<-highlightbackground> B<-insertofftime> B<-selectborderwidth> B<-xscrollcommand>
-B<-highlightcolor> B<-insertontime> B<-selectforeground> B<-yscrollcommand>
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<closeEnough>
-
-=item Class: B<CloseEnough>
-
-=item Switch: B<-closeenough>
-
-Specifies a floating-point value indicating how close the mouse cursor
-must be to an item before it is considered to be ``inside'' the item.
-Defaults to 1.0.
-
-=item Name: B<confine>
-
-=item Class: B<Confine>
-
-=item Switch: B<-confine>
-
-Specifies a boolean value that indicates whether or not it should be
-allowable to set the canvas's view outside the region defined by the
-B<scrollRegion> argument.
-Defaults to true, which means that the view will
-be constrained within the scroll region.
-
-=item Name: B<height>
-
-=item Class: B<Height>
-
-=item Switch: B<-height>
-
-Specifies a desired window height that the canvas widget should request from
-its geometry manager. The value may be specified in any
-of the forms described in the L<"COORDINATES"> section below.
-
-=item Name: B<scrollRegion>
-
-=item Class: B<ScrollRegion>
-
-=item Switch: B<-scrollregion>
-
-Specifies a list with four coordinates describing the left, top, right, and
-bottom coordinates of a rectangular region.
-This region is used for scrolling purposes and is considered to be
-the boundary of the information in the canvas.
-Each of the coordinates may be specified
-in any of the forms given in the L<"COORDINATES"> section below.
-
-=item Name: B<state>
-
-=item Class: B<State>
-
-=item Switch: B<-state>
-
-Modifies the default state of the canvas where I<state> may be set to one of:
-normal, disabled, or hidden. Individual canvas objects all have their own
-state option, which overrides the default state. Many options can take
-separate specifications such that the appearance of the item can be different
-in different situations. The options that start with "active" control the
-appearence when the mouse pointer is over it, while the option starting
-with "disabled" controls the appearence when the state is disabled.
-
-=item Name: B<width>
-
-=item Class: B<width>
-
-=item Switch: B<-width>
-
-Specifies a desired window width that the canvas widget should request from
-its geometry manager. The value may be specified in any
-of the forms described in the L<"COORDINATES"> section below.
-
-=item Name: B<xScrollIncrement>
-
-=item Class: B<ScrollIncrement>
-
-=item Switch: B<-xscrollincrement>
-
-Specifies an increment for horizontal scrolling, in any of the usual forms
-permitted for screen distances. If the value of this option is greater
-than zero, the horizontal view in the window will be constrained so that
-the canvas x coordinate at the left edge of the window is always an even
-multiple of B<xScrollIncrement>; furthermore, the units for scrolling
-(e.g., the change in view when the left and right arrows of a scrollbar
-are selected) will also be B<xScrollIncrement>. If the value of
-this option is less than or equal to zero, then horizontal scrolling
-is unconstrained.
-
-=item Name: B<yScrollIncrement>
-
-=item Class: B<ScrollIncrement>
-
-=item Switch: B<-yscrollincrement>
-
-Specifies an increment for vertical scrolling, in any of the usual forms
-permitted for screen distances. If the value of this option is greater
-than zero, the vertical view in the window will be constrained so that
-the canvas y coordinate at the top edge of the window is always an even
-multiple of B<yScrollIncrement>; furthermore, the units for scrolling
-(e.g., the change in view when the top and bottom arrows of a scrollbar
-are selected) will also be B<yScrollIncrement>. If the value of
-this option is less than or equal to zero, then vertical scrolling
-is unconstrained.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Canvas> method creates a new window (given
-by the $canvas argument) and makes it into a canvas widget.
-Additional options, described above, may be specified on the
-command line or in the option database
-to configure aspects of the canvas such as its colors and 3-D relief.
-The B<canvas> command returns its
-$canvas argument. At the time this command is invoked,
-there must not exist a window named $canvas, but
-$canvas's parent must exist.
-
-Canvas widgets implement structured graphics.
-A canvas displays any number of I<items>, which may be things like
-rectangles, circles, lines, and text.
-Items may be manipulated (e.g. moved or re-colored) and
-L<callbacks|Tk::callbacks> may
-be associated with items in much the same way that the L<bind|Tk::bind>
-method allows callbacks to be bound to widgets. For example,
-a particular callback may be associated with the B<E<lt>Button-1E<gt>> event
-so that the callback is invoked whenever button 1 is pressed with
-the mouse cursor over an item.
-This means that items in a canvas can have behaviors defined by
-the Callbacks bound to them.
-
-=head1 DISPLAY LIST
-
-The items in a canvas are ordered for purposes of display,
-with the first item in the display list being displayed
-first, followed by the next item in the list, and so on.
-Items later in the display list obscure those that are
-earlier in the display list and are sometimes referred to
-as being I<``on top''> of earlier items.
-When a new item is created it is placed at the end of the
-display list, on top of everything else.
-Widget methods may be used to re-arrange the order of the
-display list.
-
-Window items are an exception to the above rules. The underlying
-window systems require them always to be drawn on top of other items.
-In addition, the stacking order of window items
-is not affected by any of the canvas methods; you must use
-the L<raise|Tk::Widget> and L<lower|Tk::Widget> Tk widget methods instead.
-
-=head1 ITEM IDS AND TAGS
-
-Items in a canvas widget may be named in either of two ways:
-by id or by tag.
-Each item has a unique identifying number which is assigned to
-that item when it is created. The id of an item never changes
-and id numbers are never re-used within the lifetime of a
-canvas widget.
-
-Each item may also have any number of I<tags> associated
-with it. A tag is just a string of characters, and it may
-take any form except that of an integer.
-For example, ``x123'' is OK but ``123'' isn't.
-The same tag may be associated with many different items.
-This is commonly done to group items in various interesting
-ways; for example, all selected items might be given the
-tag ``selected''.
-
-The tag B<all> is implicitly associated with every item
-in the canvas; it may be used to invoke operations on
-all the items in the canvas.
-
-The tag B<current> is managed automatically by Tk;
-it applies to the I<current item>, which is the
-topmost item whose drawn area covers the position of
-the mouse cursor.
-If the mouse is not in the canvas widget or is not over
-an item, then no item has the B<current> tag.
-
-When specifying items in canvas methods, if the
-specifier is an integer then it is assumed to refer to
-the single item with that id.
-If the specifier is not an integer, then it is assumed to
-refer to all of the items in the canvas that have a tag
-matching the specifier.
-The symbol I<tagOrId> is used below to indicate that
-an argument specifies either an id that selects a single
-item or a tag that selects zero or more items.
-
-I<tagOrId> may contain a logical expressions of
-tags by using operators: 'E<amp>E<amp>', '||', '^' '!', and parenthezised
-subexpressions. For example:
-
-$c-E<gt>find('withtag', '(aE<amp>E<amp>!b)|(!aE<amp>E<amp>b)');
-
-or equivalently:
-
-$c-E<gt>find('withtag', 'a^b');
-
-will find only those items with either "a" or "b" tags, but not both.
-
-Some methods only operate on a single item at a
-time; if I<tagOrId> is specified in a way that
-names multiple items, then the normal behavior is for
-the methods is to use the first (lowest) of these items in
-the display list that is suitable for the method.
-Exceptions are noted in the method descriptions
-below.
-
-=head1 COORDINATES
-
-All coordinates related to canvases are stored as floating-point
-numbers.
-Coordinates and distances are specified in screen units,
-which are floating-point numbers optionally followed
-by one of several letters.
-If no letter is supplied then the distance is in pixels.
-If the letter is B<m> then the distance is in millimeters on
-the screen; if it is B<c> then the distance is in centimeters;
-B<i> means inches, and B<p> means printers points (1/72 inch).
-Larger y-coordinates refer to points lower on the screen; larger
-x-coordinates refer to points farther to the right.
-
-=head1 TRANSFORMATIONS
-
-Normally the origin of the canvas coordinate system is at the
-upper-left corner of the window containing the canvas.
-It is possible to adjust the origin of the canvas
-coordinate system relative to the origin of the window using the
-B<xview> and B<yview> methods; this is typically used
-for scrolling.
-Canvases do not support scaling or rotation of the canvas coordinate
-system relative to the window coordinate system.
-
-Individual items may be moved or scaled using methods
-described below, but they may not be rotated.
-
-=head1 INDICES
-
-Text items support the notion of an I<index> for identifying
-particular positions within the item.
-
-Indices are used for methods such as inserting text, deleting
-a range of characters, and setting the insertion cursor position.
-An index may be specified in any of a number of ways, and
-different types of items may support different forms for
-specifying indices.
-
-In a similar fashion, line and polygon items support I<index> for
-identifying, inserting and deleting subsets of their coordinates.
-Indices are used for commands such as inserting or deleting
-a range of characters or coordinates, and setting the insertion
-cursor position. An index may be specified in any of a number
-of ways, and different types of items may support different forms
-for specifying indices.
-
-Text items support the following forms for an index; if you
-define new types of text-like items, it would be advisable to
-support as many of these forms as practical.
-Note that it is possible to refer to the character just after
-the last one in the text item; this is necessary for such
-tasks as inserting new text at the end of the item.
-Lines and Polygons don't support the insertion cursor
-and the selection. Their indices are supposed to be even
-always, because coordinates always appear in pairs.
-
-=over 4
-
-=item I<number>
-
-A decimal number giving the position of the desired character
-within the text item.
-0 refers to the first character, 1 to the next character, and
-so on. If indexes are odd for lines and polygons, they will be
-automatically decremented by one.
-A number less than 0 is treated as if it were zero, and a
-number greater than the length of the text item is treated
-as if it were equal to the length of the text item. For
-polygons, numbers less than 0 or greater then the length
-of the coordinate list will be adjusted by adding or substracting
-the length until the result is between zero and the length,
-inclusive.
-
-=item B<end>
-
-Refers to the character or coordinate just after the last one
-in the item (same as the number of characters or coordinates
-in the item).
-
-=item B<insert>
-
-Refers to the character just before which the insertion cursor
-is drawn in this item. Not valid for lines and polygons.
-
-=item B<sel.first>
-
-Refers to the first selected character in the item.
-If the selection isn't in this item then this form is illegal.
-
-=item B<sel.last>
-
-Refers to the last selected character in the item.
-If the selection isn't in this item then this form is illegal.
-
-=item B<[>I<x,y>B<]>
-
-Refers to the character or coordinate at the point given by I<x> and
-I<y>, where I<x> and I<y> are specified in the coordinate
-system of the canvas.
-If I<x> and I<y> lie outside the coordinates covered by the
-text item, then they refer to the first or last character in the
-line that is closest to the given point.
-The Tcl string form "@x,y" is also allowed.
-
-=back
-
-=head1 DASH PATTERNS
-
-Many items support the notion of an dash pattern for outlines.
-
-The first possible syntax is a list of integers. Each element
-represents the number of pixels of a line segment. Only the odd
-segments are drawn using the "outline" color. The other segments
-are drawn transparent.
-
-The second possible syntax is a character list containing only
-5 possible characters B<[.,-_ ]>, with the first 4 characters
-producing a segment of length 1 to 4, respectively, followed
-by a transparent segment of length 2. The space can be used
-repeatedly to enlarge the space between other line elements
-by 1, and can not occur as the first position in the string.
-The main difference of this syntax with the previous one is
-that it it shape-conserving. This means that all values in the dash
-list will be multiplied by the line width before display. This
-assures that "." will always be displayed as a dot and "-"
-always as a dash regardless of the line width.
-
-Some examples, for a line width of 2:
-
- -dash . = -dash [2,4]
- -dash - = -dash [6,4]
- -dash -. = -dash [6,4,2,4]
- -dash -.. = -dash [6,4,2,4,2,4]
- -dash '. ' = -dash [2,8]
- -dash ',' = -dash [4,4]
-
-On systems where only a limited set of dash patterns is available,
-the dash pattern will be displayed as the closest available dash
-pattern. For example, on Windows only the first 4 of the
-above examples are available. The last 2 examples will be
-displayed identically as the first one.
-
-=head1 WIDGET METHODS
-
-The B<Canvas> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-The following additional methods are available for canvas widgets:
-
-=over 4
-
-=item I<$canvas>-E<gt>B<addtag>(I<tag, searchSpec, >?I<arg, arg, ...>?)
-
-For each item that meets the constraints specified by
-I<searchSpec> and the I<arg>s, add
-I<tag> to the list of tags associated with the item if it
-isn't already present on that list.
-It is possible that no items will satisfy the constraints
-given by I<searchSpec> and I<arg>s, in which case the
-method has no effect.
-This command returns an empty string as result.
-I<SearchSpec> and I<arg>'s may take any of the following
-forms:
-
-=over 8
-
-=item B<above >I<tagOrId>
-
-Selects the item just after (above) the one given by I<tagOrId>
-in the display list.
-If I<tagOrId> denotes more than one item, then the last (topmost)
-of these items in the display list is used.
-
-=item B<all>
-
-Selects all the items in the canvas.
-
-=item B<below >I<tagOrId>
-
-Selects the item just before (below) the one given by I<tagOrId>
-in the display list.
-If I<tagOrId> denotes more than one item, then the first (lowest)
-of these items in the display list is used.
-
-=item B<closest >I<x y >?I<halo>? ?I<start>?
-
-Selects the item closest to the point given by I<x> and I<y>.
-If more than one item is at the same closest distance (e.g. two
-items overlap the point), then the top-most of these items (the
-last one in the display list) is used.
-If I<halo> is specified, then it must be a non-negative
-value.
-Any item closer than I<halo> to the point is considered to
-overlap it.
-The I<start> argument may be used to step circularly through
-all the closest items.
-If I<start> is specified, it names an item using a tag or id
-(if by tag, it selects the first item in the display list with
-the given tag).
-Instead of selecting the topmost closest item, this form will
-select the topmost closest item that is below I<start> in
-the display list; if no such item exists, then the selection
-behaves as if the I<start> argument had not been specified.
-
-=item B<enclosed> I<x1> I<y1> I<x2> I<y2>
-
-Selects all the items completely enclosed within the rectangular
-region given by I<x1>, I<y1>, I<x2>, and I<y2>.
-I<X1> must be no greater then I<x2> and I<y1> must be
-no greater than I<y2>.
-
-=item B<overlapping> I<x1> I<y1> I<x2> I<y2>
-
-Selects all the items that overlap or are enclosed within the
-rectangular region given by I<x1>, I<y1>, I<x2>,
-and I<y2>.
-I<X1> must be no greater then I<x2> and I<y1> must be
-no greater than I<y2>.
-
-=item B<withtag >I<tagOrId>
-
-Selects all the items given by I<tagOrId>.
-
-=back
-
-=item I<$canvas>-E<gt>B<bbox>(I<tagOrId, >?I<tagOrId, tagOrId, ...>?)
-
-Returns a list with four elements giving an approximate bounding box
-for all the items named by the I<tagOrId> arguments.
-The list has the form ``I<x1 y1 x2 y2>'' such that the drawn
-areas of all the named elements are within the region bounded by
-I<x1> on the left, I<x2> on the right, I<y1> on the top,
-and I<y2> on the bottom.
-The return value may overestimate the actual bounding box by
-a few pixels.
-If no items match any of the I<tagOrId> arguments or if the
-matching items have empty bounding boxes (i.e. they have nothing
-to display)
-then an empty string is returned.
-
-=item I<$canvas>-E<gt>B<bind>(I<tagOrId>?, I<sequence>? ?,I<callback>?)
-
-This method associates I<callback> with all the items given by
-I<tagOrId> such that whenever the event sequence given by
-I<sequence> occurs for one of the items the callback will
-be invoked.
-This method is similar to the B<bind> method except that
-it operates on items in a canvas rather than entire widgets.
-See L<Tk::bind> for complete details
-on the syntax of I<sequence> and the substitutions performed
-on I<callback> before invoking it.
-If all arguments are specified then a new binding is created, replacing
-any existing binding for the same I<sequence> and I<tagOrId>
-(if the first character of I<command> is ``+'' then I<command>
-augments an existing binding rather than replacing it).
-In this case the return value is an empty string.
-If I<callback> is omitted then the method returns the I<callback>
-associated with I<tagOrId> and I<sequence> (an error occurs
-if there is no such binding).
-If both I<callback> and I<sequence> are omitted then the method
-returns a list of all the sequences for which bindings have been
-defined for I<tagOrId>.
-
-=over 8
-
-The only events for which bindings may be specified are those related to
-the mouse and keyboard (such as B<Enter>, B<Leave>,
-B<ButtonPress>, B<Motion>, and B<KeyPress>) or virtual events.
-The handling of events in canvases uses the current item defined
-in L<"ITEM IDS AND TAGS"> above. B<Enter> and B<Leave> events trigger for an
-item when it becomes the current item or ceases to be the current item;
-note that these events are different than B<Enter> and B<Leave>
-events for windows. Mouse-related events are directed to the current
-item, if any. Keyboard-related events are directed to the focus item, if
-any (see the L<focus|/focus> method below for more on this). If a
-virtual event is used in a binding, that binding can trigger only if the
-virtual event is defined by an underlying mouse-related or
-keyboard-related event.
-
-It is possible for multiple bindings to match a particular event.
-This could occur, for example, if one binding is associated with the
-item's id and another is associated with one of the item's tags.
-When this occurs, all of the matching bindings are invoked.
-A binding associated with the B<all> tag is invoked first,
-followed by one binding for each of the item's tags (in order),
-followed by a binding associated with the item's id.
-If there are multiple matching bindings for a single tag,
-then only the most specific binding is invoked.
-A B<continue> in a callback terminates that
-subroutine, and a B<break> method terminates that subroutine
-and skips any remaining callbacks for the event, just as for the
-B<bind> method.
-
-If bindings have been created for a canvas window using the B<CanvasBind>
-method, then they are invoked in addition to bindings created for
-the canvas's items using the B<bind> method.
-The bindings for items will be invoked before any of the bindings
-for the window as a whole.
-
-=back
-
-=item I<$canvas>-E<gt>B<canvasx>(I<screenx>?, I<gridspacing>?)
-
-Given a window x-coordinate in the canvas I<screenx>, this method returns
-the canvas x-coordinate that is displayed at that location.
-If I<gridspacing> is specified, then the canvas coordinate is
-rounded to the nearest multiple of I<gridspacing> units.
-
-=item I<$canvas>-E<gt>B<canvasy>(I<screeny, >?I<gridspacing>?)
-
-Given a window y-coordinate in the canvas I<screeny> this method returns
-the canvas y-coordinate that is displayed at that location.
-If I<gridspacing> is specified, then the canvas coordinate is
-rounded to the nearest multiple of I<gridspacing> units.
-
-=item I<$canvas>-E<gt>B<coords>(I<tagOrId >?I<x0,y0 ...>?)
-
-Query or modify the coordinates that define an item.
-If no coordinates are specified, this method returns a list
-whose elements are the coordinates of the item named by
-I<tagOrId>.
-If coordinates are specified, then they replace the current
-coordinates for the named item.
-If I<tagOrId> refers to multiple items, then
-the first one in the display list is used.
-
-=item I<$canvas>-E<gt>B<create>(I<type, x, y, >?I<x, y, ...>?, ?I<option, value, ...>?)
-
-Create a new item in I<$canvas> of type I<type>.
-The exact format of the arguments after B<type> depends
-on B<type>, but usually they consist of the coordinates for
-one or more points, followed by specifications for zero or
-more item options.
-See the subsections on individual item types below for more
-on the syntax of this method.
-This method returns the id for the new item.
-
-=item I<$canvas>-E<gt>B<dchars>(I<tagOrId, first, >?I<last>?)
-
-For each item given by I<tagOrId>, delete the characters, or coordinates,
-in the range given by I<first> and I<last>, inclusive.
-If some of the items given by I<tagOrId> don't support
-Text items interpret I<first> and I<last> as indices to a character,
-line and polygon items interpret them indices to a coordinate (an x,y pair).
-within the item(s) as described in L<"INDICES"> above.
-If I<last> is omitted, it defaults to I<first>.
-This method returns an empty string.
-
-=item I<$canvas>-E<gt>B<delete>(?I<tagOrId, tagOrId, ...>?)
-
-Delete each of the items given by each I<tagOrId>, and return
-an empty string.
-
-=item I<$canvas>-E<gt>B<dtag>(I<tagOrId, >?I<tagToDelete>?)
-
-For each of the items given by I<tagOrId>, delete the
-tag given by I<tagToDelete> from the list of those
-associated with the item.
-If an item doesn't have the tag I<tagToDelete> then
-the item is unaffected by the method.
-If I<tagToDelete> is omitted then it defaults to I<tagOrId>.
-This method returns an empty string.
-
-=item I<$canvas>-E<gt>B<find>(I<searchCommand, >?I<arg, arg, ...>?)
-
-This method returns a list consisting of all the items that
-meet the constraints specified by I<searchCommand> and
-I<arg>'s.
-I<SearchCommand> and I<args> have any of the forms
-accepted by the B<addtag> method.
-The items are returned in stacking order, with the lowest item first.
-
-=item focus
-
-=item I<$canvas>-E<gt>B<focus>(?I<tagOrId>?)
-
-Set the keyboard focus for the canvas widget to the item given by
-I<tagOrId>.
-If I<tagOrId> refers to several items, then the focus is set
-to the first such item in the display list that supports the
-insertion cursor.
-If I<tagOrId> doesn't refer to any items, or if none of them
-support the insertion cursor, then the focus isn't changed.
-If I<tagOrId> is an empty
-string, then the focus item is reset so that no item has the focus.
-If I<tagOrId> is not specified then the method returns the
-id for the item that currently has the focus, or an empty string
-if no item has the focus.
-
-=over 8
-
-Once the focus has been set to an item, the item will display
-the insertion cursor and all keyboard events will be directed
-to that item.
-The focus item within a canvas and the focus window on the
-screen (set with the B<focus> method) are totally independent:
-a given item doesn't actually have the input focus unless (a)
-its canvas is the focus window and (b) the item is the focus item
-within the canvas.
-In most cases it is advisable to follow the B<focus> widget
-method with the B<CanvasFocus> method to set the focus window to
-the canvas (if it wasn't there already).
-
-=back
-
-=item I<$canvas>-E<gt>B<gettags>(I<tagOrId>)
-
-Return a list whose elements are the tags associated with the
-item given by I<tagOrId>.
-If I<tagOrId> refers to more than one item, then the tags
-are returned from the first such item in the display list.
-If I<tagOrId> doesn't refer to any items, or if the item
-contains no tags, then an empty string is returned.
-
-=item I<$canvas>-E<gt>B<icursor>(I<tagOrId, index>)
-
-Set the position of the insertion cursor for the item(s) given by I<tagOrId>
-to just before the character whose position is given by I<index>.
-If some or all of the items given by I<tagOrId> don't support
-an insertion cursor then this method has no effect on them.
-See L<"INDICES"> above for a description of the
-legal forms for I<index>.
-Note: the insertion cursor is only displayed in an item if
-that item currently has the keyboard focus (see the widget
-method B<focus>, below), but the cursor position may
-be set even when the item doesn't have the focus.
-This method returns an empty string.
-
-=item I<$canvas>-E<gt>B<index>(I<tagOrId, index>)
-
-This method returns a decimal string giving the numerical index
-within I<tagOrId> corresponding to I<index>.
-I<Index> gives a textual description of the desired position
-as described in L<"INDICES"> above.
-Text items interpret I<index> as an index to a character,
-line and polygon items interpret it as an index to a coordinate (an x,y pair).
-The return value is guaranteed to lie between 0 and the number
-of characters, or coordinates, within the item, inclusive.
-If I<tagOrId> refers to multiple items, then the index
-is processed in the first of these items that supports indexing
-operations (in display list order).
-
-=item I<$canvas>-E<gt>B<insert>(I<tagOrId, beforeThis, string>)
-
-For each of the items given by I<tagOrId>, if the item supports
-text or coordinate, insertion then I<string> is inserted into the item's
-text just before the character, or coordinate, whose index is I<beforeThis>.
-Text items interpret I<beforethis> as an index to a character,
-line and polygon items interpret it as an index to a coordinate (an x,y pair).
-For lines and polygons the I<string> must be a valid coordinate
-sequence.
-See L<"INDICES"> above for information about the forms allowed
-for I<beforeThis>.
-This method returns an empty string.
-
-=item I<$canvas>-E<gt>B<itemcget>(I<tagOrId, >I<option>)
-
-Returns the current value of the configuration option for the
-item given by I<tagOrId> whose name is I<option>.
-This method is similar to the L<cget|Tk::option> method except that
-it applies to a particular item rather than the widget as a whole.
-I<Option> may have any of the values accepted by the B<create>
-method when the item was created.
-If I<tagOrId> is a tag that refers to more than one item,
-the first (lowest) such item is used.
-
-=item I<$canvas>-E<gt>B<itemconfigure>(I<tagOrId, >?I<option>?, ?I<value>?, ?I<option, value, ...>?)
-
-This method is similar to the L<configure|Tk::option> method except
-that it modifies item-specific options for the items given by
-I<tagOrId> instead of modifying options for the overall
-canvas widget.
-If no I<option> is specified, returns a list describing all of
-the available options for the first item given by I<tagOrId>
-(see L<Tk::options> for
-information on the format of this list). If I<option> is specified
-with no I<value>, then the method returns a list describing the
-one named option (this list will be identical to the corresponding
-sublist of the value returned if no I<option> is specified). If
-one or more I<option-value> pairs are specified, then the method
-modifies the given widget option(s) to have the given value(s) in
-each of the items given by I<tagOrId>; in
-this case the method returns an empty string.
-The I<option>s and I<value>s are the same as those permissible
-in the B<create> method when the item(s) were created;
-see the sections describing individual item types below for details
-on the legal options.
-
-=item I<$canvas>-E<gt>B<lower>(I<tagOrId, >?I<belowThis>?)
-
-Move all of the items given by I<tagOrId> to a new position
-in the display list just before the item given by I<belowThis>.
-If I<tagOrId> refers to more than one item then all are moved
-but the relative order of the moved items will not be changed.
-I<BelowThis> is a tag or id; if it refers to more than one
-item then the first (lowest) of these items in the display list is used
-as the destination location for the moved items.
-Note: this method has no effect on window items. Window items always
-obscure other item types, and the stacking order of window items is
-determined by the B<raise> and B<lower> methods of the widget, not the
-B<raise> and B<lower> methods for canvases.
-This method returns an empty string.
-
-=item I<$canvas>-E<gt>B<move>(I<tagOrId, xAmount, yAmount>)
-
-Move each of the items given by I<tagOrId> in the canvas coordinate
-space by adding I<xAmount> to the x-coordinate of each point
-associated with the item and I<yAmount> to the y-coordinate of
-each point associated with the item.
-This method returns an empty string.
-
-=item I<$canvas>-E<gt>B<postscript>(?I<option, value, option, value, ...>?)
-
-Generate a Postscript representation for part or all of the canvas.
-If the B<-file> option is specified then the Postscript is written
-to a file and an empty string is returned; otherwise the Postscript
-is returned as the result of the method.
-If the interpreter that owns the canvas is marked as safe, the operation
-will fail because safe interpreters are not allowed to write files.
-If the B<-channel> option is specified, the argument denotes the name
-of a channel already opened for writing. The Postscript is written to
-that channel, and the channel is left open for further writing at the end
-of the operation.
-The Postscript is created in Encapsulated Postscript form using
-version 3.0 of the Document Structuring Conventions.
-Note: by default Postscript is only generated for information that
-appears in the canvas's window on the screen. If the canvas is
-freshly created it may still have its initial size of 1x1 pixel
-so nothing will appear in the Postscript. To get around this problem
-either invoke the B<update> method to wait for the canvas window
-to reach its final size, or else use the B<-width> and B<-height>
-options to specify the area of the canvas to print.
-The I<option>-I<value> argument pairs provide additional
-information to control the generation of Postscript. The following
-options are supported:
-
-=over 8
-
-=item B<-colormap> =E<gt> I<hashRef>
-
-I<HashRef> must be a reference to a hash variable or an anonymous hash
-that specifies a color mapping to use in the Postscript.
-Each value of the hash must consist of Postscript
-code to set a particular color value (e.g. ``B<1.0 1.0 0.0 setrgbcolor>'').
-When outputting color information in the Postscript, Tk checks
-to see if there is a key in the hash with the same
-name as the color.
-If so, Tk uses the value of the element as the Postscript method
-to set the color.
-If this option hasn't been specified, or if there isn't a key
-in I<hashRef> for a given color, then Tk uses the red, green,
-and blue intensities from the X color.
-
-=item B<-colormode> =E<gt> I<mode>
-
-Specifies how to output color information. I<Mode> must be either
-B<color> (for full color output), B<gray> (convert all colors
-to their gray-scale equivalents) or B<mono> (convert all colors
-to black or white).
-
-=item B<-file> =E<gt> I<fileName>
-
-Specifies the name of the file in which to write the Postscript.
-If this option isn't specified then the Postscript is returned as the
-result of the method instead of being written to a file.
-
-=item B<-fontmap> =E<gt> I<hashRef>
-
-I<HashRef> must be a reference to a hash variable or an anonymous hash
-that specifies a font mapping to use in the Postscript.
-Each value of the hash must consist of an array reference with
-two elements, which are the name and point size of a Postscript font.
-When outputting Postscript commands for a particular font, Tk
-checks to see if I<hashRef> contains a value with the same
-name as the font.
-If there is such an element, then the font information contained in
-that element is used in the Postscript.
-Otherwise Tk attempts to guess what Postscript font to use.
-Tk's guesses generally only work for well-known fonts such as
-Times and Helvetica and Courier, and only if the X font name does not
-omit any dashes up through the point size.
-For example, B<-*-Courier-Bold-R-Normal--*-120-*> will work but
-B<*Courier-Bold-R-Normal*120*> will not; Tk needs the dashes to
-parse the font name).
-
-=item B<-height> =E<gt> I<size>
-
-Specifies the height of the area of the canvas to print.
-Defaults to the height of the canvas window.
-
-=item B<-pageanchor> =E<gt> I<anchor>
-
-Specifies which point of the printed area of the canvas should appear over
-the positioning point on the page (which is given by the B<-pagex>
-and B<-pagey> options).
-For example, B<-pageanchor>=>B<n> means that the top center of the
-area of the canvas being printed (as it appears in the canvas window)
-should be over the positioning point. Defaults to B<center>.
-
-=item B<-pageheight> =E<gt> I<size>
-
-Specifies that the Postscript should be scaled in both x and y so
-that the printed area is I<size> high on the Postscript page.
-I<Size> consists of a floating-point number followed by
-B<c> for centimeters, B<i> for inches, B<m> for millimeters,
-or B<p> or nothing for printer's points (1/72 inch).
-Defaults to the height of the printed area on the screen.
-If both B<-pageheight> and B<-pagewidth> are specified then
-the scale factor from B<-pagewidth> is used (non-uniform scaling
-is not implemented).
-
-=item B<-pagewidth> =E<gt> I<size>
-
-Specifies that the Postscript should be scaled in both x and y so
-that the printed area is I<size> wide on the Postscript page.
-I<Size> has the same form as for B<-pageheight>.
-Defaults to the width of the printed area on the screen.
-If both B<-pageheight> and B<-pagewidth> are specified then
-the scale factor from B<-pagewidth> is used (non-uniform scaling
-is not implemented).
-
-=item B<-pagex> =E<gt> I<position>
-
-I<Position> gives the x-coordinate of the positioning point on
-the Postscript page, using any of the forms allowed for B<-pageheight>.
-Used in conjunction with the B<-pagey> and B<-pageanchor> options
-to determine where the printed area appears on the Postscript page.
-Defaults to the center of the page.
-
-=item B<-pagey> =E<gt> I<position>
-
-I<Position> gives the y-coordinate of the positioning point on
-the Postscript page, using any of the forms allowed for B<-pageheight>.
-Used in conjunction with the B<-pagex> and B<-pageanchor> options
-to determine where the printed area appears on the Postscript page.
-Defaults to the center of the page.
-
-=item B<-rotate> =E<gt> I<boolean>
-
-I<Boolean> specifies whether the printed area is to be rotated 90
-degrees.
-In non-rotated output the x-axis of the printed area runs along
-the short dimension of the page (``portrait'' orientation);
-in rotated output the x-axis runs along the long dimension of the
-page (``landscape'' orientation).
-Defaults to non-rotated.
-
-=item B<-width> =E<gt> I<size>
-
-Specifies the width of the area of the canvas to print.
-Defaults to the width of the canvas window.
-
-=item B<-x> => I<position>
-
-Specifies the x-coordinate of the left edge of the area of the
-canvas that is to be printed, in canvas coordinates, not window
-coordinates.
-Defaults to the coordinate of the left edge of the window.
-
-=item B<-y> => I<position>
-
-Specifies the y-coordinate of the top edge of the area of the
-canvas that is to be printed, in canvas coordinates, not window
-coordinates.
-Defaults to the coordinate of the top edge of the window.
-
-=back
-
-=item I<$canvas>-E<gt>B<raise>(I<tagOrId, >?I<aboveThis>?)
-
-Move all of the items given by I<tagOrId> to a new position
-in the display list just after the item given by I<aboveThis>.
-If I<tagOrId> refers to more than one item then all are moved
-but the relative order of the moved items will not be changed.
-I<AboveThis> is a tag or id; if it refers to more than one
-item then the last (topmost) of these items in the display list is used
-as the destination location for the moved items.
-Note: this method has no effect on window items. Window items always
-obscure other item types, and the stacking order of window items is
-determined by the B<raise> and B<lower> widget commands, not the
-B<raise> and B<lower> methods for canvases.
-This method returns an empty string.
-
-=item I<$canvas>-E<gt>B<scale>(I<tagOrId, xOrigin, yOrigin, xScale, yScale>)
-
-Rescale all of the items given by I<tagOrId> in canvas coordinate
-space.
-I<XOrigin> and I<yOrigin> identify the origin for the scaling
-operation and I<xScale> and I<yScale> identify the scale
-factors for x- and y-coordinates, respectively (a scale factor of
-1.0 implies no change to that coordinate).
-For each of the points defining each item, the x-coordinate is
-adjusted to change the distance from I<xOrigin> by a factor
-of I<xScale>.
-Similarly, each y-coordinate is adjusted to change the distance
-from I<yOrigin> by a factor of I<yScale>.
-This method returns an empty string.
-
-=item I<$canvas>-E<gt>B<scan>(I<option, args>)
-
-This method is used to implement scanning on canvases. It has
-two forms, depending on I<option>:
-
-=over 8
-
-=item I<$canvas>-E<gt>B<scanMark>(I<x, y>)
-
-Records I<x> and I<y> and the canvas's current view; used
-in conjunction with later B<scanDragto> method.
-Typically this method is associated with a mouse button press in
-the widget and I<x> and I<y> are the coordinates of the
-mouse. It returns an empty string.
-
-=item I<$canvas>-E<gt>B<scanDragto>(I<x, y, ?gain?>.)
-
-This method computes the difference between its I<x> and I<y>
-arguments (which are typically mouse coordinates) and the I<x> and
-I<y> arguments to the last B<scanMark> method for the widget.
-It then adjusts the view by 10 times the
-difference in coordinates. This method is typically associated
-It then adjusts the view by I<gain> times the
-difference in coordinates, where I<gain> defaults to 10.
-This command is typically associated
-with mouse motion events in the widget, to produce the effect of
-dragging the canvas at high speed through its window. The return
-value is an empty string.
-
-=back
-
-=item I<$canvas>-E<gt>B<select>(I<option, >?I<tagOrId, arg>?)
-
-Manipulates the selection in one of several ways, depending on
-I<option>.
-The method may take any of the forms described below.
-In all of the descriptions below, I<tagOrId> must refer to
-an item that supports indexing and selection; if it refers to
-multiple items then the first of
-these that supports indexing and the selection is used.
-I<Index> gives a textual description of a position
-within I<tagOrId>, as described in L<"INDICES"> above.
-
-=over 8
-
-=item I<$canvas>-E<gt>B<selectAdjust>(I<tagOrId, index>)
-
-Locate the end of the selection in I<tagOrId> nearest
-to the character given by I<index>, and adjust that
-end of the selection to be at I<index> (i.e. including
-but not going beyond I<index>).
-The other end of the selection is made the anchor point
-for future B<selectTo> method calls.
-If the selection isn't currently in I<tagOrId> then
-this method behaves the same as the B<selectTo> widget
-method.
-Returns an empty string.
-
-=item I<$canvas>-E<gt>B<selectClear>
-
-Clear the selection if it is in this widget.
-If the selection isn't in this widget then the method
-has no effect.
-Returns an empty string.
-
-=item I<$canvas>-E<gt>B<selectFrom>(I<tagOrId, index>)
-
-Set the selection anchor point for the widget to be just
-before the character
-given by I<index> in the item given by I<tagOrId>.
-This method doesn't change the selection; it just sets
-the fixed end of the selection for future B<selectTo>
-method calls.
-Returns an empty string.
-
-=item I<$canvas>-E<gt>B<selectItem>
-
-Returns the id of the selected item, if the selection is in an
-item in this canvas.
-If the selection is not in this canvas then an empty string
-is returned.
-
-=item I<$canvas>-E<gt>B<selectTo>(I<tagOrId, index>)
-
-Set the selection to consist of those characters of I<tagOrId>
-between the selection anchor point and
-I<index>.
-The new selection will include the character given by I<index>;
-it will include the character given by the anchor point only if
-I<index> is greater than or equal to the anchor point.
-The anchor point is determined by the most recent B<selectAdjust>
-or B<selectFrom> method calls for this widget.
-If the selection anchor point for the widget isn't currently in
-I<tagOrId>, then it is set to the same character given
-by I<index>.
-Returns an empty string.
-
-=back
-
-=item I<$canvas>-E<gt>B<type>(I<tagOrId>)
-
-Returns the type of the item given by I<tagOrId>, such as
-B<rectangle> or B<text>.
-If I<tagOrId> refers to more than one item, then the type
-of the first item in the display list is returned.
-If I<tagOrId> doesn't refer to any items at all then
-an empty string is returned.
-
-=item I<$canvas>-E<gt>B<xview>(?I<args>?)
-
-This method is used to query and change the horizontal position of the
-information displayed in the canvas's window.
-It can take any of the following forms:
-
-=over 8
-
-=item I<$canvas>-E<gt>B<xview>
-
-Returns a list containing two elements.
-Each element is a real fraction between 0 and 1; together they describe
-the horizontal span that is visible in the window.
-For example, if the first element is .2 and the second element is .6,
-20% of the canvas's area (as defined by the B<-scrollregion> option)
-is off-screen to the left, the middle 40% is visible
-in the window, and 40% of the canvas is off-screen to the right.
-These are the same values passed to scrollbars via the B<-xscrollcommand>
-option.
-
-=item I<$canvas>-E<gt>B<xviewMoveto>(I<fraction>)
-
-Adjusts the view in the window so that I<fraction> of the
-total width of the canvas is off-screen to the left.
-I<Fraction> must be a fraction between 0 and 1.
-
-=item I<$canvas>-E<gt>B<xviewScroll>(I<number, what>)
-
-This method shifts the view in the window left or right according to
-I<number> and I<what>.
-I<Number> must be an integer.
-I<What> must be either B<units> or B<pages> or an abbreviation
-of one of these.
-If I<what> is B<units>, the view adjusts left or right in units
-of the B<xScrollIncrement> option, if it is greater than zero,
-or in units of one-tenth the window's width otherwise.
-If I<what is >B<pages> then the view
-adjusts in units of nine-tenths the window's width.
-If I<number> is negative then information farther to the left
-becomes visible; if it is positive then information farther to the right
-becomes visible.
-
-=back
-
-=item I<$canvas>-E<gt>B<yview>(I<?args>?)
-
-This method is used to query and change the vertical position of the
-information displayed in the canvas's window.
-It can take any of the following forms:
-
-=over 8
-
-=item I<$canvas>-E<gt>B<yview>
-
-Returns a list containing two elements.
-Each element is a real fraction between 0 and 1; together they describe
-the vertical span that is visible in the window.
-For example, if the first element is .6 and the second element is 1.0,
-the lowest 40% of the canvas's area (as defined by the B<-scrollregion>
-option) is visible in the window.
-These are the same values passed to scrollbars via the B<-yscrollcommand>
-option.
-
-=item I<$canvas>-E<gt>B<yviewMoveto>(I<fraction>)
-
-Adjusts the view in the window so that I<fraction> of the canvas's
-area is off-screen to the top.
-I<Fraction> is a fraction between 0 and 1.
-
-=item I<$canvas>-E<gt>B<yviewScroll>(I<number, what>)
-
-This method adjusts the view in the window up or down according to
-I<number> and I<what>.
-I<Number> must be an integer.
-I<What> must be either B<units> or B<pages>.
-If I<what> is B<units>, the view adjusts up or down in units
-of the B<yScrollIncrement> option, if it is greater than zero,
-or in units of one-tenth the window's height otherwise.
-If I<what> is B<pages> then
-the view adjusts in units of nine-tenths the window's height.
-If I<number> is negative then higher information becomes
-visible; if it is positive then lower information
-becomes visible.
-
-=back
-
-=back
-
-=head1 OVERVIEW OF ITEM TYPES
-
-The sections below describe the various types of items supported
-by canvas widgets. Each item type is characterized by two things:
-first, the form of the B<create> method used to create
-instances of the type; and second, a set of configuration options
-for items of that type, which may be used in the
-B<create> and B<itemconfigure> methods.
-Most items don't support indexing or selection or the methods
-related to them, such as B<index> and B<insert>.
-Where items do support these facilities, it is noted explicitly
-in the descriptions below.
-At present, text, line and polygon items provide this support.
-For lines and polygons the indexing facility is used to manipulate
-the coordinates of the item.
-
-=head1 ARC ITEMS
-
-Items of type B<arc> appear on the display as arc-shaped regions.
-An arc is a section of an oval delimited by two angles (specified
-by the B<-start> and B<-extent> options) and displayed in
-one of several ways (specified by the B<-style> option).
-Arcs are created with methods of the following form:
-
- $canvas->createArc(x1, y1, x2, y2, ?option, value, option, value, ...?)
-
-The arguments I<x1>, I<y1>, I<x2>, and I<y2> give
-the coordinates of two diagonally opposite corners of a
-rectangular region enclosing the oval that defines the arc.
-After the coordinates there may be any number of I<option>-I<value>
-pairs, each of which sets one of the configuration options
-for the item. These same I<option>-I<value> pairs may be
-used in B<itemconfigure> methods to change the item's
-configuration.
-The following options are supported for arcs:
-
-=over 4
-
-=item B<-dash> =E<gt> I<pattern>
-
-=item B<-activedash> =E<gt> I<pattern>
-
-=item B<-disableddash> =E<gt> I<pattern>
-
-This option specifies dash patterns for the normal state, the active
-state, and the disabled state of an arc item.
-I<pattern> may have any of the forms accepted by B<Tk_GetDash>.
-If the dash options are omitted then the default is a solid outline.
-
-=item B<-dashoffset> =E<gt> I<offset>
-
-The starting I<offset> into the pattern provided by the
-B<-dash> option.
-B<-dashoffset> is ignored if there is no B<-dash> pattern.
-
-=item B<-extent> =E<gt> I<degrees>
-
-Specifies the size of the angular range occupied by the arc.
-The arc's range extends for I<degrees> degrees counter-clockwise
-from the starting angle given by the B<-start> option.
-I<Degrees> may be negative.
-If it is greater than 360 or less than -360, then I<degrees>
-modulo 360 is used as the extent.
-
-=item B<-fill> =E<gt> I<color>
-
-=item B<-activefill> =E<gt> I<color>
-
-=item B<-disabledfill> =E<gt> I<color>
-
-Specifies the color to be used to fill the arc region in its normal, active, and
-disabled states,
-I<Color> may have any of the forms accepted by B<Tk_GetColor>.
-If I<color> is an empty string (the default), then
-then the arc will not be filled.
-
-=item B<-outline> =E<gt> I<color>
-
-=item B<-activeoutline> =E<gt> I<color>
-
-=item B<-disabledoutline> =E<gt> I<color>
-
-This option specifies the color that should be used to draw the
-outline of the arc in its normal, active and disabled states.
-I<Color> may have any of the forms accepted by B<Tk_GetColor>.
-This option defaults to B<black>. If I<color> is specified
-as undef then no outline is drawn for the arc.
-
-=item B<-outlinestipple> =E<gt> I<bitmap>
-
-=item B<-activeoutlinestipple> =E<gt> I<bitmap>
-
-=item B<-disabledoutlinestipple> =E<gt> I<bitmap>
-
-This option specifies stipple patterns that should be used to draw the
-outline of the arc in its normal, active and disabled states.
-Indicates that the outline for the arc should be drawn with a stipple pattern;
-I<bitmap> specifies the stipple pattern to use, in any of the
-forms accepted by B<Tk_GetBitmap>.
-If the B<-outline> option hasn't been specified then this option
-has no effect.
-If I<bitmap> is an empty string (the default), then the outline is drawn
-in a solid fashion.
-
-=item B<-start> =E<gt> I<degrees>
-
-Specifies the beginning of the angular range occupied by the
-arc.
-I<Degrees> is given in units of degrees measured counter-clockwise
-from the 3-o'clock position; it may be either positive or negative.
-
-=item B<-state> =E<gt> I<state>
-
-Modifies the state of the arc item where I<state> may be set to one of:
-normal, disabled, hidden or "". If set to empty, the state of the canvas
-itself is used. An arc item may also be in the "active"
-state if the mouse is currently over it. Many options can take
-separate specifications in normal, active and disabled states such that the
-appearance of the item can be different in each state.
-
-=item B<-stipple> =E<gt> I<bitmap>
-
-=item B<-activestipple> =E<gt> I<bitmap>
-
-=item B<-disabledstipple> =E<gt> I<bitmap>
-
-This option specifies stipple patterns that should be used to fill the
-the arc in its normal, active and disabled states.
-I<bitmap> specifies the stipple pattern to use, in any of the
-forms accepted by B<Tk_GetBitmap>.
-If the B<-fill> option hasn't been specified then this option
-has no effect.
-If I<bitmap> is an empty string (the default), then filling is done
-in a solid fashion.
-
-=item B<-style> =E<gt> I<type>
-
-Specifies how to draw the arc. If I<type> is B<pieslice>
-(the default) then the arc's region is defined by a section
-of the oval's perimeter plus two line segments, one between the center
-of the oval and each end of the perimeter section.
-If I<type> is B<chord> then the arc's region is defined
-by a section of the oval's perimeter plus a single line segment
-connecting the two end points of the perimeter section.
-If I<type> is B<arc> then the arc's region consists of
-a section of the perimeter alone.
-In this last case the B<-fill> option is ignored.
-
-=item B<-tags> =E<gt> I<tagList>
-
-Specifies a set of tags to apply to the item.
-I<TagList> consists of a list of tag names, which replace any
-existing tags for the item.
-I<TagList> may be an empty list.
-
-=item B<-updatecommand> =E<gt> I<command>
-
-Specifies a callback that is to be executed every time
-the arc item is updated on the screen.
-
-=item B<-width> =E<gt> I<outlineWidth>
-
-=item B<-activewidth> =E<gt> I<outlineWidth>
-
-=item B<-disabledwidth> =E<gt> I<outlineWidth>
-
-Specifies the width of the outline to be drawn around
-the arc's region, in its normal, active and disabled states.
-I<outlineWidth> may be in any of the forms described in
-the L<"COORDINATES"> section above.
-If the B<-outline> option has been specified as undef
-then this option has no effect.
-Wide outlines will be drawn centered on the edges of the arc's region.
-This option defaults to 1.0.
-
-=back
-
-=head1 BITMAP ITEMS
-
-Items of type B<bitmap> appear on the display as images with
-two colors, foreground and background.
-Bitmaps are created with methods of the following form:
-
- $canvas->createBitmap(x, y, ?option, value, option, value, ...?)
-
-The arguments I<x> and I<y> specify the coordinates of a
-point used to position the bitmap on the display (see the B<-anchor>
-option below for more information on how bitmaps are displayed).
-After the coordinates there may be any number of I<option>-I<value>
-pairs, each of which sets one of the configuration options
-for the item. These same I<option>-I<value> pairs may be
-used in B<itemconfigure> methods to change the item's
-configuration.
-The following options are supported for bitmaps:
-
-=over 4
-
-=item B<-anchor> =E<gt> I<anchorPos>
-
-I<AnchorPos> tells how to position the bitmap relative to the
-positioning point for the item; it may have any of the forms
-accepted by B<Tk_GetAnchor>. For example, if I<anchorPos>
-is B<center> then the bitmap is centered on the point; if
-I<anchorPos> is B<n> then the bitmap will be drawn so that
-its top center point is at the positioning point.
-This option defaults to B<center>.
-
-=item B<-background> =E<gt> I<color>
-
-=item B<-activebackground> =E<gt> I<color>
-
-=item B<-disabledbackground> =E<gt> I<color>
-
-Specifies the color to use for each of the bitmap's '0' valued pixels
-in its normal, active and disabled states.
-I<Color> may have any of the forms accepted by B<Tk_GetColor>.
-If this option isn't specified, or if it is specified as undef,
-then nothing is displayed where the bitmap pixels are 0; this
-produces a transparent effect.
-
-=item B<-bitmap> =E<gt> I<bitmap>
-
-=item B<-activebitmap> =E<gt> I<bitmap>
-
-=item B<-disabledbitmap> =E<gt> I<bitmap>
-
-Specifies the bitmaps to display in the item in its normal, active and
-disabled states. All bitmaps must have the same width and height.
-I<Bitmap> may have any of the forms accepted by B<Tk_GetBitmap>.
-
-=item B<-foreground> =E<gt> I<color>
-
-=item B<-activeforeground> =E<gt> I<color>
-
-=item B<-disabledforeground> =E<gt> I<color>
-
-Specifies the color to use for each of the bitmap's '1' valued pixels
-in its normal, active and disabled states.
-I<Color> may have any of the forms accepted by B<Tk_GetColor> and
-defaults to B<black>.
-
-=item B<-state> =E<gt> I<state>
-
-Modifies the state of the bitmap item where I<state> may be set to one of:
-normal, disabled, or hidden. An bitmap item may also be in the "active"
-state if the mouse is currently over it. Many options can take
-separate specifications in normal, active and disabled states such that the
-appearance of the item can be different in each state.
-
-=item B<-tags> =E<gt> I<tagList>
-
-Specifies a set of tags to apply to the item.
-I<TagList> consists of a list of tag names, which replace any
-existing tags for the item.
-I<TagList> may be an empty list.
-
-=item B<-updatecommand> =E<gt> I<command>
-
-Specifies a callback that is to be executed every time
-the bitmap item is updated on the screen.
-
-=back
-
-=head1 GRID ITEMS
-
-Items of type B<grid> are intended for producing a visual reference for
-interpreting other items. They can be drawn as either lines (with dash
-style) or as rectangular "dots" at each grid point.
-
-Items of type B<grid> are unlike other items they always cover the
-whole of the canvas, but are never enclosed by nor overlap any area
-and are not near any point. That is they are intended to be always visible
-but not "pickable", as such they do support the "active" state.
-They are like other items in that: multiple
-grids are permitted, they can be raised and lowered relative to other
-items, they can be moved and scaled. As yet grids do not appear in
-PostScript output.
-
-Grids have outline like configure options. Grids are created with methods of the
-following form:
-
- $canvas->createGrid(x1, y1, x2, y2, ?option, value, option, value, ...?)
-
-The arguments I<x1>, I<y1> give the origin of the grid. I<x2>, and I<y2> give
-the coordinates of the next grid point in their respective directions.
-After the coordinates there may be any number of I<option>-I<value>
-pairs, each of which sets one of the configuration options
-for the item. These same I<option>-I<value> pairs may be
-used in B<itemconfigure> methods to change the item's
-configuration.
-
-The following options are supported for grids:
-
-=over 4
-
-=item B<-lines> =E<gt> I<boolean>
-
-If B<-lines> is set to a true value then lines are drawn for both X and Y
-grids in the style determined by B<-dash>. Otherwise retangular "dots"
-are drawn at each grid point.
-
-=item B<-dash> =E<gt> I<pattern>
-
-=item B<-disableddash> =E<gt> I<pattern>
-
-This option specifies dash patterns for the normal state,
-and the disabled state of a grid item.
-I<pattern> may have any of the forms accepted by B<Tk_GetDash>.
-If the dash options are omitted then the default is a solid outline.
-
-=item B<-dashoffset> =E<gt> I<offset>
-
-The starting I<offset> into the pattern provided by the
-B<-dash> option.
-B<-dashoffset> is ignored if there is no B<-dash> pattern.
-
-=item B<-color> =E<gt> I<color>
-
-=item B<-disabledcolor> =E<gt> I<color>
-
-This option specifies the color that should be used to draw the
-outline of the grid in its normal and disabled states.
-I<Color> may have any of the forms accepted by B<Tk_GetColor>.
-This option defaults to B<black>.
-If I<color> is undef then no grid will be drawn.
-
-=item B<-stipple> =E<gt> I<bitmap>
-
-=item B<-disabledstipple> =E<gt> I<bitmap>
-
-This option specifies stipple patterns that should be used to draw the
-outline of the rectangle in its normal and disabled states.
-I<bitmap> specifies the stipple pattern to use, in any of the
-forms accepted by B<Tk_GetBitmap>.
-If I<bitmap> is an empty string (the default), then the outline is drawn
-in a solid fashion.
-
-=item B<-state> =E<gt> I<state>
-
-Modifies the state of the rectangle item where I<state> may be set to one of:
-normal, disabled, or hidden. Many options can take
-separate specifications in normal and disabled states such that the
-appearance of the item can be different in each state.
-
-=item B<-tags> =E<gt> I<tagList>
-
-Specifies a set of tags to apply to the item.
-I<TagList> consists of a list of tag names, which replace any
-existing tags for the item.
-I<TagList> may be an empty list.
-
-=item B<-updatecommand> =E<gt> I<command>
-
-Specifies a callback that is to be executed every time
-the grid item is updated on the screen.
-
-=item B<-width> =E<gt> I<outlineWidth>
-
-=item B<-disabledwidth> =E<gt> I<outlineWidth>
-
-Specifies the width of the lines drawn by the grid or the size (in both X and Y)
-of the dots, in its normal and disabled states.
-This option defaults to 1.0.
-
-=back
-
-=head1 IMAGE ITEMS
-
-Items of type B<image> are used to display images on a
-canvas.
-Images are created with methods of the following form:
-
- $canvas->createImage(x, y, ?option, value, option, value, ...?)
-
-The arguments I<x> and I<y> specify the coordinates of a
-point used to position the image on the display (see the B<-anchor>
-option below for more information).
-After the coordinates there may be any number of I<option>-I<value>
-pairs, each of which sets one of the configuration options
-for the item. These same I<option>-I<value> pairs may be
-used in B<itemconfigure> methods to change the item's
-configuration.
-The following options are supported for images:
-
-=over 4
-
-=item B<-anchor> =E<gt> I<anchorPos>
-
-I<AnchorPos> tells how to position the image relative to the
-positioning point for the item; it may have any of the forms
-accepted by B<Tk_GetAnchor>. For example, if I<anchorPos>
-is B<center> then the image is centered on the point; if
-I<anchorPos> is B<n> then the image will be drawn so that
-its top center point is at the positioning point.
-This option defaults to B<center>.
-
-=item B<-image> =E<gt> I<name>
-
-=item B<-activeimage> =E<gt> I<name>
-
-=item B<-disabledimage> =E<gt> I<name>
-
-Specifies the name of the images to display in the item in is normal,
-active and disabled states. This image must have been created
-previously, see L<Tk::Image>.
-
-=item B<-state> =E<gt> I<state>
-
-Modifies the state of the image item where I<state> may be set to one of:
-normal, disabled, or hidden. An image item may also be in the "active"
-state if the mouse is currently over it. Many options can take
-separate specifications in normal, active and disabled states such that the
-appearance of the item can be different in each state.
-
-=item B<-tags> =E<gt> I<tagList>
-
-Specifies a set of tags to apply to the item.
-I<TagList> consists of a list of tag names, which replace any
-existing tags for the item; it may be an empty list.
-
-=item B<-updatecommand> =E<gt> I<command>
-
-Specifies a callback that is to be executed every time
-the image item is updated on the screen.
-
-=back
-
-=head1 LINE ITEMS
-
-Items of type B<line> appear on the display as one or more connected
-line segments or curves.
-Line items support coordinate indexing operations using the canvas
-methods: B<dchars, index, insert.>
-Lines are created with methods of the following form:
-
- $canvas->createLine(x1, y1..., xn, yn, ?option, value, option, value, ...?)
-
-The arguments I<x1> through I<yn> give
-the coordinates for a series of two or more points that describe
-a series of connected line segments.
-After the coordinates there may be any number of I<option>-I<value>
-pairs, each of which sets one of the configuration options
-for the item. These same I<option>-I<value> pairs may be
-used in B<itemconfigure> methods to change the item's
-configuration.
-The following options are supported for lines:
-
-=over 4
-
-=item B<-arrow> =E<gt> I<where>
-
-Indicates whether or not arrowheads are to be drawn at one or both
-ends of the line.
-I<Where> must have one of the values B<none> (for no arrowheads),
-B<first> (for an arrowhead at the first point of the line),
-B<last> (for an arrowhead at the last point of the line), or
-B<both> (for arrowheads at both ends).
-This option defaults to B<none>.
-
-=item B<-arrowshape> =E<gt> I<shape>
-
-This option indicates how to draw arrowheads.
-The I<shape> argument must be a list with three elements, each
-specifying a distance in any of the forms described in
-the L<"COORDINATES"> section above.
-The first element of the list gives the distance along the line
-from the neck of the arrowhead to its tip.
-The second element gives the distance along the line from the
-trailing points of the arrowhead to the tip, and the third
-element gives the distance from the outside edge of the line to the
-trailing points.
-If this option isn't specified then Tk picks a ``reasonable'' shape.
-
-=item B<-capstyle> =E<gt> I<style>
-
-Specifies the ways in which caps are to be drawn at the endpoints
-of the line.
-I<Style> may have any of the forms accepted by B<Tk_GetCapStyle>
-(B<butt>, B<projecting>, or B<round>).
-If this option isn't specified then it defaults to B<butt>.
-Where arrowheads are drawn the cap style is ignored.
-
-=item B<-dash> =E<gt> I<pattern>
-
-=item B<-activedash> =E<gt> I<pattern>
-
-=item B<-disableddash> =E<gt> I<pattern>
-
-This option specifies dash patterns for the normal state, the active
-state, and the disabled state of a line item.
-I<pattern> may have any of the forms accepted by B<Tk_GetDash>.
-If the dash options are omitted then the default is a solid outline.
-
-=item B<-dashoffset> =E<gt> I<offset>
-
-The starting I<offset> into the pattern provided by the
-B<-dash> option.
-B<-dashoffset> is ignored if there is no B<-dash> pattern.
-
-=item B<-fill> =E<gt> I<color>
-
-=item B<-activefill> =E<gt> I<color>
-
-=item B<-disabledfill> =E<gt> I<color>
-
-Specifies the color to be used to fill the line in its normal, active, and
-disabled states.
-I<Color> may have
-any of the forms acceptable to B<Tk_GetColor>. It may also be undef,
-in which case the line will be transparent.
-This option defaults to B<black>.
-
-=item B<-joinstyle> =E<gt> I<style>
-
-Specifies the ways in which joints are to be drawn at the vertices
-of the line.
-I<Style> may have any of the forms accepted by B<Tk_GetCapStyle>
-(B<bevel>, B<miter>, or B<round>).
-If this option isn't specified then it defaults to B<miter>.
-If the line only contains two points then this option is
-irrelevant.
-
-=item B<-smooth> =E<gt> I<boolean>
-
-I<Boolean> must have one of the forms accepted by B<Tk_GetBoolean>.
-It indicates whether or not the line should be drawn as a curve.
-If so, the line is rendered as a set of parabolic splines: one spline
-is drawn for the first and second line segments, one for the second
-and third, and so on. Straight-line segments can be generated within
-a curve by duplicating the end-points of the desired line segment.
-
-=item B<-splinesteps> =E<gt> I<number>
-
-Specifies the degree of smoothness desired for curves: each spline
-will be approximated with I<number> line segments. This
-option is ignored unless the B<-smooth> option is true.
-
-=item B<-state> =E<gt> I<state>
-
-Modifies the state of the line item where I<state> may be set to one of:
-normal, disabled, or hidden. A line item may also be in the "active"
-state if the mouse is currently over it. Many options can take
-separate specifications in normal, active and disabled states such that the
-appearance of the item can be different in each state.
-
-=item B<-stipple> =E<gt> I<bitmap>
-
-=item B<-activestipple> =E<gt> I<bitmap>
-
-=item B<-disabledstipple> =E<gt> I<bitmap>
-
-This option specifies stipple patterns that should be used to fill the
-the line in its normal, active and disabled states.
-I<bitmap> specifies the stipple pattern to use, in any of the
-forms accepted by B<Tk_GetBitmap>.
-If I<bitmap> is an empty string (the default), then filling is
-done in a solid fashion.
-
-=item B<-tags> =E<gt> I<tagList>
-
-Specifies a set of tags to apply to the item.
-I<TagList> consists of a list of tag names, which replace any
-existing tags for the item.
-I<TagList> may be an empty list.
-
-=item B<-updatecommand> =E<gt> I<command>
-
-Specifies a callback that is to be executed every time
-the line item is updated on the screen.
-
-=item B<-width> =E<gt> I<lineWidth>
-
-=item B<-activewidth> =E<gt> I<lineWidth>
-
-=item B<-disabledwidth> =E<gt> I<lineWidth>
-
-Specifies the width of the line
-in its normal, active and disabled states.
-I<lineWidth> may be in any of the forms
-described in the L<"COORDINATES"> section above.
-
-Wide lines will be drawn centered on the path specified by the
-points.
-If this option isn't specified then it defaults to 1.0.
-
-=back
-
-=head1 OVAL ITEMS
-
-Items of type B<oval> appear as circular or oval regions on
-the display. Each oval may have an outline, a fill, or
-both. Ovals are created with methods of the
-following form:
-
- $canvas->createOval(x1, y1, x2, y2, ?option, value, option, value, ...?)
-
-The arguments I<x1>, I<y1>, I<x2>, and I<y2> give
-the coordinates of two diagonally opposite corners of a
-rectangular region enclosing the oval.
-The oval will include the top and left edges of the rectangle
-not the lower or right edges.
-If the region is square then the resulting oval is circular;
-otherwise it is elongated in shape.
-After the coordinates there may be any number of I<option>-I<value>
-pairs, each of which sets one of the configuration options
-for the item. These same I<option>-I<value> pairs may be
-used in B<itemconfigure> methods to change the item's
-configuration.
-The following options are supported for ovals:
-
-=over 4
-
-=item B<-dash> =E<gt> I<pattern>
-
-=item B<-activedash> =E<gt> I<pattern>
-
-=item B<-disableddash> =E<gt> I<pattern>
-
-This option specifies dash patterns for the normal state, the active
-state, and the disabled state of an oval item.
-I<pattern> may have any of the forms accepted by B<Tk_GetDash>.
-If the dash options are omitted then the default is a solid outline.
-
-=item B<-dashoffset> =E<gt> I<offset>
-
-The starting I<offset> into the pattern provided by the
-B<-dash> option.
-B<-dashoffset> is ignored if there is no B<-dash> pattern.
-
-=item B<-fill> =E<gt> I<color>
-
-=item B<-activefill> =E<gt> I<color>
-
-=item B<-disabledfill> =E<gt> I<color>
-
-Specifies the color to be used to fill the oval in its normal, active, and
-disabled states.
-I<Color> may have any of the forms accepted by B<Tk_GetColor>.
-If I<color> is undef (the default), then
-then the oval will not be filled.
-
-=item B<-outline> =E<gt> I<color>
-
-=item B<-activeoutline> =E<gt> I<color>
-
-=item B<-disabledoutline> =E<gt> I<color>
-
-This option specifies the color that should be used to draw the
-outline of the oval in its normal, active and disabled states.
-I<Color> may have any of the forms accepted by B<Tk_GetColor>.
-This option defaults to B<black>.
-If I<color> is undef then no outline will be
-drawn for the oval.
-
-=item B<-outlinestipple> =E<gt> I<bitmap>
-
-=item B<-activeoutlinestipple> =E<gt> I<bitmap>
-
-=item B<-disabledoutlinestipple> =E<gt> I<bitmap>
-
-This option specifies stipple patterns that should be used to draw the
-outline of the oval in its normal, active and disabled states.
-I<bitmap> specifies the stipple pattern to use, in any of the
-forms accepted by B<Tk_GetBitmap>.
-If the B<-outline> option hasn't been specified then this option
-has no effect.
-If I<bitmap> is an empty string (the default), then the outline is drawn
-in a solid fashion.
-
-=item B<-state> =E<gt> I<state>
-
-Modifies the state of the oval item where I<state> may be set to one of:
-normal, disabled, or hidden. An oval item may also be in the "active"
-state if the mouse is currently over it. Many options can take
-separate specifications in normal, active and disabled states such that the
-appearance of the item can be different in each state.
-
-=item B<-stipple> =E<gt> I<bitmap>
-
-=item B<-activestipple> =E<gt> I<bitmap>
-
-=item B<-disabledstipple> =E<gt> I<bitmap>
-
-This option specifies stipple patterns that should be used to fill the
-the oval in its normal, active and disabled states.
-I<bitmap> specifies the stipple pattern to use, in any of the
-forms accepted by B<Tk_GetBitmap>.
-If the B<-fill> option hasn't been specified then this option
-has no effect.
-If I<bitmap> is an empty string (the default), then filling is done
-in a solid fashion.
-
-=item B<-tags> =E<gt> I<tagList>
-
-Specifies a set of tags to apply to the item.
-I<TagList> consists of a list of tag names, which replace any
-existing tags for the item.
-I<TagList> may be an empty list.
-
-=item B<-updatecommand> =E<gt> I<command>
-
-Specifies a callback that is to be executed every time
-the oval item is updated on the screen.
-
-=item B<-width> =E<gt> I<outlineWidth>
-
-=item B<-activewidth> =E<gt> I<outlineWidth>
-
-=item B<-disabledwidth> =E<gt> I<outlineWidth>
-
-Specifies the width of the outline to be drawn around
-the oval, in its normal, active and disabled states.
-I<outlineWidth> specifies the width of the outline to be drawn around
-the oval, in any of the forms described in the L<"COORDINATES"> section above.
-
-If the B<-outline> option hasn't been specified then this option
-has no effect.
-Wide outlines are drawn centered on the oval path defined by
-I<x1>, I<y1>, I<x2>, and I<y2>.
-This option defaults to 1.0.
-
-=back
-
-=head1 POLYGON ITEMS
-
-Items of type B<polygon> appear as polygonal or curved filled regions
-on the display.
-Polygon items support coordinate indexing operations using the canvas
-methods: B<dchars, index, insert.>
-Polygons are created with methods of the following form:
-
- $canvas->createPolygon(x1, y1, ..., xn, yn, ?option, value, option, value, ...?)
-
-The arguments I<x1> through I<yn> specify the coordinates for
-three or more points that define a closed polygon.
-The first and last points may be the same; whether they are or not,
-Tk will draw the polygon as a closed polygon.
-After the coordinates there may be any number of I<option>-I<value>
-pairs, each of which sets one of the configuration options
-for the item. These same I<option>-I<value> pairs may be
-used in B<itemconfigure> methods to change the item's
-configuration.
-The following options are supported for polygons:
-
-=over 4
-
-=item B<-dash> =E<gt> I<pattern>
-
-=item B<-activedash> =E<gt> I<pattern>
-
-=item B<-disableddash> =E<gt> I<pattern>
-
-This option specifies dash patterns for the normal state, the active
-state, and the disabled state of an polygon item.
-I<pattern> may have any of the forms accepted by B<Tk_GetDash>.
-If the dash options are omitted then the default is a solid outline.
-
-=item B<-dashoffset> =E<gt> I<offset>
-
-The starting I<offset> into the pattern provided by the
-B<-dash> option.
-B<-dashoffset> is ignored if there is no B<-dash> pattern.
-
-=item B<-fill> =E<gt> I<color>
-
-=item B<-activefill> =E<gt> I<color>
-
-=item B<-disabledfill> =E<gt> I<color>
-
-Specifies the color to be used to fill the polygon in its normal, active, and
-disabled states.
-I<Color>
-may have any of the forms acceptable to B<Tk_GetColor>.
-If I<color> is undef then the polygon will be
-transparent.
-This option defaults to B<black>.
-
-=item B<-joinstyle> =E<gt> I<style>
-
-Specifies the ways in which joints are to be drawn at the vertices
-of the outline.
-I<Style> may have any of the forms accepted by B<Tk_GetCapStyle>
-(B<bevel>, B<miter>, or B<round>).
-If this option isn't specified then it defaults to B<miter>.
-
-=item B<-outline> =E<gt> I<color>
-
-=item B<-activeoutline> =E<gt> I<color>
-
-=item B<-disabledoutline> =E<gt> I<color>
-
-This option specifies the color that should be used to draw the
-outline of the polygon in its normal, active and disabled states.
-I<Color> may have any of the forms accepted by B<Tk_GetColor>.
-If I<color> is undef then no outline will be
-drawn for the polygon.
-This option defaults to undef (no outline).
-
-=item B<-outlinestipple> =E<gt> I<bitmap>
-
-=item B<-activeoutlinestipple> =E<gt> I<bitmap>
-
-=item B<-disabledoutlinestipple> =E<gt> I<bitmap>
-
-This option specifies stipple patterns that should be used to draw the
-outline of the polygon in its normal, active and disabled states.
-I<bitmap> specifies the stipple pattern to use, in any of the
-forms accepted by B<Tk_GetBitmap>.
-If the B<-outline> option hasn't been specified then this option
-has no effect.
-If I<bitmap> is an empty string (the default), then the outline is drawn
-in a solid fashion.
-
-=item B<-smooth> =E<gt> I<boolean>
-
-I<Boolean> must have one of the forms accepted by B<Tk_GetBoolean>
-It indicates whether or not the polygon should be drawn with a
-curved perimeter.
-If so, the outline of the polygon becomes a set of parabolic splines,
-one spline for the first and second line segments, one for the second
-and third, and so on. Straight-line segments can be generated in a
-smoothed polygon by duplicating the end-points of the desired line segment.
-
-=item B<-splinesteps> =E<gt> I<number>
-
-Specifies the degree of smoothness desired for curves: each spline
-will be approximated with I<number> line segments. This
-option is ignored unless the B<-smooth> option is true.
-
-=item B<-state> =E<gt> I<state>
-
-Modifies the state of the polygon item where I<state> may be set to one of:
-normal, disabled, or hidden. A polygon item may also be in the "active"
-state if the mouse is currently over it. Many options can take
-separate specifications in normal, active and disabled states such that the
-appearance of the item can be different in each state.
-
-=item B<-stipple> =E<gt> I<bitmap>
-
-=item B<-activestipple> =E<gt> I<bitmap>
-
-=item B<-disabledstipple> =E<gt> I<bitmap>
-
-This option specifies stipple patterns that should be used to fill the
-the polygon in its normal, active and disabled states.
-I<bitmap> specifies the stipple pattern to use, in any of the
-forms accepted by B<Tk_GetBitmap>.
-If I<bitmap> is an empty string (the default), then filling is
-done in a solid fashion.
-
-=item B<-tags> =E<gt> I<tagList>
-
-Specifies a set of tags to apply to the item.
-I<TagList> consists of a list of tag names, which replace any
-existing tags for the item.
-I<TagList> may be an empty list.
-
-=item B<-updatecommand> =E<gt> I<command>
-
-Specifies a callback that is to be executed every time
-the polygon item is updated on the screen.
-
-=item B<-width> =E<gt> I<outlineWidth>
-
-=item B<-activewidth> =E<gt> I<outlineWidth>
-
-=item B<-disabledwidth> =E<gt> I<outlineWidth>
-
-=item Specifies the width of the outline to be drawn around
-
-the polygon, in its normal, active and disabled states.
-I<outlineWidth> may be in any of the forms described in the COORDINATES
-section above.
-I<OutlineWidth> specifies the width of the outline to be drawn around
-the polygon, in any of the forms described in the L<"COORDINATES"> section above.
-If the B<-outline> option hasn't been specified then this option
-has no effect. This option defaults to 1.0.
-
-Polygon items are different from other items such as rectangles, ovals
-and arcs in that interior points are considered to be ``inside'' a
-polygon (e.g. for purposes of the B<find closest> and
-B<find overlapping> methods) even if it is not filled.
-For most other item types, an
-interior point is considered to be inside the item only if the item
-is filled or if it has neither a fill nor an outline. If you would
-like an unfilled polygon whose interior points are not considered
-to be inside the polygon, use a line item instead.
-
-=back
-
-=head1 RECTANGLE ITEMS
-
-Items of type B<rectangle> appear as rectangular regions on
-the display. Each rectangle may have an outline, a fill, or
-both. Rectangles are created with methods of the
-following form:
-
- $canvas->createRectangle(x1, y1, x2, y2, ?option, value, option, value, ...?)
-
-The arguments I<x1>, I<y1>, I<x2>, and I<y2> give
-the coordinates of two diagonally opposite corners of the rectangle
-(the rectangle will include its upper and left edges but not
-its lower or right edges).
-After the coordinates there may be any number of I<option>-I<value>
-pairs, each of which sets one of the configuration options
-for the item. These same I<option>-I<value> pairs may be
-used in B<itemconfigure> methods to change the item's
-configuration.
-The following options are supported for rectangles:
-
-=over 4
-
-=item B<-dash> =E<gt> I<pattern>
-
-=item B<-activedash> =E<gt> I<pattern>
-
-=item B<-disableddash> =E<gt> I<pattern>
-
-This option specifies dash patterns for the normal state, the active
-state, and the disabled state of a rectangle item.
-I<pattern> may have any of the forms accepted by B<Tk_GetDash>.
-If the dash options are omitted then the default is a solid outline.
-
-=item B<-dashoffset> =E<gt> I<offset>
-
-The starting I<offset> into the pattern provided by the
-B<-dash> option.
-B<-dashoffset> is ignored if there is no B<-dash> pattern.
-
-=item B<-fill> =E<gt> I<color>
-
-=item B<-activefill> =E<gt> I<color>
-
-=item B<-disabledfill> =E<gt> I<color>
-
-Specifies the color to be used to fill the rectangle in its normal, active, and
-disabled states.
-I<Color>
-may be specified in any of the forms accepted by B<Tk_GetColor>.
-If I<color> is undef (the default),
-then the rectangle will not be filled.
-
-=item B<-outline> =E<gt> I<color>
-
-=item B<-activeoutline> =E<gt> I<color>
-
-=item B<-disabledoutline> =E<gt> I<color>
-
-This option specifies the color that should be used to draw the
-outline of the rectangle in its normal, active and disabled states.
-I<Color> may have any of the forms accepted by B<Tk_GetColor>.
-This option defaults to B<black>.
-If I<color> is undef then no outline will be
-drawn for the rectangle.
-
-=item B<-outlinestipple> =E<gt> I<bitmap>
-
-=item B<-activeoutlinestipple> =E<gt> I<bitmap>
-
-=item B<-disabledoutlinestipple> =E<gt> I<bitmap>
-
-This option specifies stipple patterns that should be used to draw the
-outline of the rectangle in its normal, active and disabled states.
-I<bitmap> specifies the stipple pattern to use, in any of the
-forms accepted by B<Tk_GetBitmap>.
-If the B<-outline> option hasn't been specified then this option
-has no effect.
-If I<bitmap> is an empty string (the default), then the outline is drawn
-in a solid fashion.
-
-=item B<-state> =E<gt> I<state>
-
-Modifies the state of the rectangle item where I<state> may be set to one of:
-normal, disabled, or hidden. A rectangle item may also be in the "active"
-state if the mouse is currently over it. Many options can take
-separate specifications in normal, active and disabled states such that the
-appearance of the item can be different in each state.
-
-=item B<-stipple> =E<gt> I<bitmap>
-
-=item B<-activestipple> =E<gt> I<bitmap>
-
-=item B<-disabledstipple> =E<gt> I<bitmap>
-
-This option specifies stipple patterns that should be used to fill the
-the rectangle in its normal, active and disabled states.
-I<bitmap> specifies the stipple pattern to use, in any of the
-forms accepted by B<Tk_GetBitmap>.
-If the B<-fill> option hasn't been specified then this option
-has no effect.
-If I<bitmap> is an empty string (the default), then filling
-is done in a solid fashion.
-
-=item B<-tags> =E<gt> I<tagList>
-
-Specifies a set of tags to apply to the item.
-I<TagList> consists of a list of tag names, which replace any
-existing tags for the item.
-I<TagList> may be an empty list.
-
-=item B<-updatecommand> =E<gt> I<command>
-
-Specifies a callback that is to be executed every time
-the rectangle item is updated on the screen.
-
-=item B<-width> =E<gt> I<outlineWidth>
-
-=item B<-activewidth> =E<gt> I<outlineWidth>
-
-=item B<-disabledwidth> =E<gt> I<outlineWidth>
-
-Specifies the width of the outline to be drawn around
-the rectangle, in its normal, active and disabled states.
-I<OutlineWidth> specifies the width of the outline to be drawn around
-the rectangle, in any of the forms described in the L<"COORDINATES"> section above.
-
-If the B<-outline> option hasn't been specified then this option
-has no effect.
-Wide outlines are drawn centered on the rectangular path
-defined by I<x1>, I<y1>, I<x2>, and I<y2>.
-This option defaults to 1.0.
-
-=back
-
-=head1 TEXT ITEMS
-
-A text item displays a string of characters on the screen in one
-or more lines.
-Text items support indexing and selection, along with the
-following text-related canvas methods: B<dchars>,
-B<focus>, B<icursor>, B<index>, B<insert>,
-B<select>.
-Text items are created with methods of the following
-form:
-
- $canvas->createText(x, y, ?option, value, option, value, ...?)
-
-The arguments I<x> and I<y> specify the coordinates of a
-point used to position the text on the display (see the options
-below for more information on how text is displayed).
-After the coordinates there may be any number of I<option>-I<value>
-pairs, each of which sets one of the configuration options
-for the item. These same I<option>-I<value> pairs may be
-used in B<itemconfigure> methods to change the item's
-configuration.
-The following options are supported for text items:
-
-=over 4
-
-=item B<-anchor> =E<gt> I<anchorPos>
-
-I<AnchorPos> tells how to position the text relative to the
-positioning point for the text; it may have any of the forms
-accepted by B<Tk_GetAnchor>. For example, if I<anchorPos>
-is B<center> then the text is centered on the point; if
-I<anchorPos> is B<n> then the text will be drawn such that
-the top center point of the rectangular region occupied by the
-text will be at the positioning point.
-This option defaults to B<center>.
-
-=item B<-fill> =E<gt> I<color>
-
-=item B<-activefill> =E<gt> I<color>
-
-=item B<-disabledfill> =E<gt> I<color>
-
-Specifies the color to be used to fill the text in its normal, active, and
-disabled states.
-I<Color> may have any of the forms accepted by B<Tk_GetColor>.
-If I<color> is undef then the text will be transparent.
-If this option isn't specified then it defaults to B<black>.
-
-=item B<-font> =E<gt> I<fontName>
-
-Specifies the font to use for the text item.
-I<FontName> may be any string acceptable to B<Tk_GetFontStruct>.
-If this option isn't specified, it defaults to a system-dependent
-font.
-
-=item B<-justify> =E<gt> I<how>
-
-Specifies how to justify the text within its bounding region.
-I<How> must be one of the values B<left>, B<right>,
-or B<center>.
-This option will only matter if the text is displayed as multiple
-lines.
-If the option is omitted, it defaults to B<left>.
-
-=item B<-state> =E<gt> I<state>
-
-Modifies the state of the text item where I<state> may be set to one of:
-normal, disabled, or hidden. A text item may also be in the "active"
-state if the mouse is currently over it. Many options can take
-separate specifications in normal, active and disabled states such that the
-appearance of the item can be different in each state.
-
-=item B<-stipple> =E<gt> I<bitmap>
-
-=item B<-activestipple> =E<gt> I<bitmap>
-
-=item B<-disabledstipple> =E<gt> I<bitmap>
-
-This option specifies stipple patterns that should be used to fill the
-the text in its normal, active and disabled states.
-I<bitmap> specifies the stipple pattern to use, in any of the
-forms accepted by B<Tk_GetBitmap>.
-If I<bitmap> is an empty string (the default) then the text
-is drawn in a solid fashion.
-
-=item B<-tags> =E<gt> I<tagList>
-
-Specifies a set of tags to apply to the item.
-I<TagList> consists of a list of tag names, which replace any
-existing tags for the item.
-I<TagList> may be an empty list.
-
-=item B<-text> =E<gt> I<string>
-
-I<String> specifies the characters to be displayed in the text item.
-Newline characters cause line breaks.
-The characters in the item may also be changed with the
-B<insert> and B<delete> methods.
-This option defaults to an empty string.
-
-=item B<-updatecommand> =E<gt> I<command>
-
-Specifies a callback that is to be executed every time
-the text item is updated on the screen.
-
-=item B<-width> =E<gt> I<lineLength>
-
-Specifies a maximum line length for the text, in any of the forms
-described in the L<"COORDINATES"> section above.
-If this option is zero (the default) the text is broken into
-lines only at newline characters.
-However, if this option is non-zero then any line that would
-be longer than I<lineLength> is broken just before a space
-character to make the line shorter than I<lineLength>; the
-space character is treated as if it were a newline
-character.
-
-=back
-
-=head1 WINDOW ITEMS
-
-Items of type B<window> cause a particular window to be displayed
-at a given position on the canvas.
-Window items are created with methods of the following form:
-
-S< >I<$canvas>->B<createWindow>(I<x, y>?, I<-option>=>I<value>, I<-option>=>I<value>, ...?)
-
-The arguments I<x> and I<y> specify the coordinates of a
-point used to position the window on the display (see the B<-anchor>
-option below for more information on how bitmaps are displayed).
-After the coordinates there may be any number of I<option-value>
-pairs, each of which sets one of the configuration options
-for the item. These same I<option>-I<value> pairs may be
-used in B<itemconfigure> method to change the item's
-configuration.
-The following options are supported for window items:
-
-=over 4
-
-=item B<-anchor> =E<gt> I<anchorPos>
-
-I<AnchorPos> tells how to position the window relative to the
-positioning point for the item; it may have any of the forms
-accepted by B<Tk_GetAnchor>. For example, if I<anchorPos>
-is B<center> then the window is centered on the point; if
-I<anchorPos> is B<n> then the window will be drawn so that
-its top center point is at the positioning point.
-This option defaults to B<center>.
-
-=item B<-height> =E<gt> I<pixels>
-
-Specifies the height to assign to the item's window.
-I<Pixels> may have any of the
-forms described in the L<"COORDINATES"> section above.
-If this option isn't specified, or if it is specified as an empty
-string, then the window is given whatever height it requests internally.
-
-=item B<-state> =E<gt> I<state>
-
-Modifies the state of the window item where I<state> may be set to one of:
-normal, disabled, or hidden.
-
-=item B<-tags> =E<gt> I<tagList>
-
-Specifies a set of tags to apply to the item.
-I<TagList> consists of a list of tag names, which replace any
-existing tags for the item.
-I<TagList> may be an empty list.
-
-=item B<-updatecommand> =E<gt> I<command>
-
-Specifies a callback that is to be executed every time
-the window item is updated on the screen.
-
-=item B<-width> =E<gt> I<pixels>
-
-Specifies the width to assign to the item's window.
-I<Pixels> may have any of the
-forms described in the L<"COORDINATES"> section above.
-If this option isn't specified, or if it is specified as an empty
-string, then the window is given whatever width it requests internally.
-
-=item B<-window> =E<gt> I<$widget>
-
-Specifies the window to associate with this item.
-The window specified by $widget must either be a child of
-the canvas widget or a child of some ancestor of the canvas widget.
-I<PathName> may not refer to a top-level window.
-
-Note: due to restrictions in the ways that windows are managed, it is not
-possible to draw other graphical items (such as lines and images) on top
-of window items. A window item always obscures any graphics that
-overlap it, regardless of their order in the display list.
-
-=back
-
-=head1 APPLICATION-DEFINED ITEM TYPES
-
-It is possible for individual applications to define new item
-types for canvas widgets using C code.
-See the documentation for B<Tk_CreateItemType>.
-
-=head1 BINDINGS
-
-Canvas has default bindings to allow scrolling if necessary:
-<Up>, <Down>, <Left> and <Right> (and their <Control-*> counter
-parts). Further <Proir>, <Next>, <Home> and <End>. These
-bindings allow you to navigate the same way as in other
-widgets that can scroll.
-
-=head1 Perl/Tk Methods
-
-The following methods are added as perl code:
-
-=over 4
-
-=item $canvas->get_corners
-
-Returns the bounding box in Canvas coordinates of the visible portion
-of the Canvas. (Written by Slaven Rezic.)
-
-=back
-
-=head1 CREDITS
-
-Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's
-I<ezd> program. I<Ezd> provides structured graphics in a Scheme
-environment and preceded canvases by a year or two. Its simple
-mechanisms for placing and animating graphical objects inspired the
-functions of canvases.
-
-=head1 KEYWORDS
-
-canvas, widget
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Checkbutton.pod b/Master/tlpkg/tlperl/lib/Tk/Checkbutton.pod
deleted file mode 100644
index 35c4fa8ffbc..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Checkbutton.pod
+++ /dev/null
@@ -1,347 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Checkbutton - Create and manipulate Checkbutton widgets
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
-I<$checkbutton> = I<$parent>-E<gt>B<Checkbutton>(?I<options>?);
-
-=head1 STANDARD OPTIONS
-
-B<-activebackground>
-B<-activeforeground>
-B<-anchor>
-B<-background>
-B<-bitmap>
-B<-borderwidth>
-B<-compound>
-B<-cursor>
-B<-disabledforeground>
-B<-font>
-B<-foreground>
-B<-highlightbackground>
-B<-highlightcolor>
-B<-highlightthickness>
-B<-image>
-B<-justify>
-B<-padx>
-B<-pady>
-B<-relief>
-B<-takefocus>
-B<-text>
-B<-textvariable>
-B<-underline>
-B<-wraplength>
-
-See L<Tk::options> for details of the standard options.
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<command>
-
-=item Class: B<Command>
-
-=item Switch: B<-command>
-
-Specifies a L<perl/Tk callback|Tk::callbacks> to associate with the button. This command
-is typically invoked when mouse button 1 is released over the button
-window. The button's global variable (B<-variable> option) will
-be updated before the command is invoked.
-
-=item Name: B<height>
-
-=item Class: B<Height>
-
-=item Switch: B<-height>
-
-Specifies a desired height for the button.
-If an image or bitmap is being displayed in the button then the value is in
-screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>);
-for text it is in lines of text.
-If this option isn't specified, the button's desired height is computed
-from the size of the image or bitmap or text being displayed in it.
-
-=item Name: B<indicatorOn>
-
-=item Class: B<IndicatorOn>
-
-=item Switch: B<-indicatoron>
-
-Specifies whether or not the indicator should be drawn. Must be a
-proper boolean value. If false, the B<relief> option is
-ignored and the widget's relief is always sunken if the widget is
-selected and raised otherwise.
-
-=item Command-Line Name: B<-offrelief>
-
-=item Database Name: B<offRelief>
-
-=item Database Class: B<OffRelief>
-
-Specifies the relief for the checkbutton when the indicator is not
-drawn and the checkbutton is off. The default value is B<raised>. By
-setting this option to B<flat> and setting
-B<-indicatoron false -overrelief raised>, the effect is achieved of
-having a flat button
-that raises on mouse-over and which is depressed when activated. This
-is the behavior typically exhibited by the Bold, Italic, and
-Underline checkbuttons on the toolbar of a word-processor, for
-example.
-
-=item Name: B<offValue>
-
-=item Class: B<Value>
-
-=item Switch: B<-offvalue>
-
-Specifies value to store in the button's associated variable whenever
-this button is deselected. Defaults to ``0''.
-
-=item Name: B<onValue>
-
-=item Class: B<Value>
-
-=item Switch: B<-onvalue>
-
-Specifies value to store in the button's associated variable whenever
-this button is selected. Defaults to ``1''.
-
-=item Command-Line Name: B<-overrelief>
-
-=item Database Name: B<overRelief>
-
-=item Database Class: B<OverRelief>
-
-Specifies an alternative relief for the button, to be used when
-the mouse cursor is over the widget. This option can be used to
-make toolbar buttons, by configuring B<-relief flat -overrelief
-raised>. If the value of this option is the empty string, then
-no alternative relief is used when the mouse cursor is over the
-button. The empty string is the default value.
-
-=item Name: B<selectColor>
-
-=item Class: B<Background>
-
-=item Switch: B<-selectcolor>
-
-Specifies a background color to use when the button is selected.
-If B<indicatorOn> is true then the color applies to the indicator.
-Under Windows, this color is used as the background for the indicator
-regardless of the select state.
-If B<indicatorOn> is false, this color is used as the background
-for the entire widget, in place of B<background> or B<activeBackground>,
-whenever the widget is selected.
-If specified as an empty string then no special color is used for
-displaying when the widget is selected.
-
-=item Name: B<selectImage>
-
-=item Class: B<SelectImage>
-
-=item Switch: B<-selectimage>
-
-Specifies an image to display (in place of the B<image> option)
-when the checkbutton is selected.
-This option is ignored unless the B<image> option has been
-specified.
-
-=item Name: B<state>
-
-=item Class: B<State>
-
-=item Switch: B<-state>
-
-Specifies one of three states for the checkbutton: B<normal>, B<active>,
-or B<disabled>. In normal state the checkbutton is displayed using the
-B<foreground> and B<background> options. The active state is
-typically used when the pointer is over the checkbutton. In active state
-the checkbutton is displayed using the B<activeForeground> and
-B<activeBackground> options. Disabled state means that the checkbutton
-should be insensitive: the default bindings will refuse to activate
-the widget and will ignore mouse button presses.
-In this state the B<disabledForeground> and
-B<background> options determine how the checkbutton is displayed.
-
-=item Name: B<variable>
-
-=item Class: B<Variable>
-
-=item Switch: B<-variable>
-
-Specifies reference to a variable to set to indicate whether
-or not this button is selected. Defaults to C<\$widget-E<gt>{'Value'}>
-member of the widget's hash. In general perl variables are C<undef> unless
-specifically initialized which will not match either default B<-onvalue> or
-default B<-offvalue>.
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-=item Switch: B<-width>
-
-Specifies a desired width for the button.
-If an image or bitmap is being displayed in the button then the value is in
-screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>);
-for text it is in characters.
-If this option isn't specified, the button's desired width is computed
-from the size of the image or bitmap or text being displayed in it.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Checkbutton> method creates a new window (given by the
-$widget argument) and makes it into a checkbutton widget.
-Additional
-options, described above, may be specified on the command line
-or in the option database
-to configure aspects of the checkbutton such as its colors, font,
-text, and initial relief. The B<checkbutton> command returns its
-$widget argument. At the time this command is invoked,
-there must not exist a window named $widget, but
-$widget's parent must exist.
-
-A checkbutton is a widget
-that displays a textual string, bitmap or image
-and a square called an I<indicator>.
-If text is displayed, it must all be in a single font, but it
-can occupy multiple lines on the screen (if it contains newlines
-or if wrapping occurs because of the B<wrapLength> option) and
-one of the characters may optionally be underlined using the
-B<underline> option.
-A checkbutton has
-all of the behavior of a simple button, including the
-following: it can display itself in either of three different
-ways, according to the B<state> option;
-it can be made to appear
-raised, sunken, or flat; it can be made to flash; and it invokes
-a L<perl/Tk callback|Tk::callbacks> whenever mouse button 1 is clicked over the
-checkbutton.
-
-In addition, checkbuttons can be I<selected>.
-If a checkbutton is selected then the indicator is normally
-drawn with a selected appearance, and
-a Tcl variable associated with the checkbutton is set to a particular
-value (normally 1).
-Under Unix, the indicator is drawn with a sunken relief and a special
-color. Under Windows, the indicator is drawn with a check mark inside.
-If the checkbutton is not selected, then the indicator is drawn with a
-deselected appearance, and the associated variable is
-set to a different value (typically 0).
-Under Unix, the indicator is drawn with a raised relief and no special
-color. Under Windows, the indicator is drawn without a check mark inside.
-By default, the name of the variable associated with a checkbutton is the
-same as the I<name> used to create the checkbutton.
-The variable name, and the ``on'' and ``off'' values stored in it,
-may be modified with options on the command line or in the option
-database.
-Configuration options may also be used to modify the way the
-indicator is displayed (or whether it is displayed at all).
-By default a checkbutton is configured to select and deselect
-itself on alternate button clicks.
-In addition, each checkbutton monitors its associated variable and
-automatically selects and deselects itself when the variables value
-changes to and from the button's ``on'' value.
-
-=head1 WIDGET METHODS
-
-The B<Checkbutton> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-The following additional methods are available for checkbutton widgets:
-
-=over 4
-
-=item I<$checkbutton>-E<gt>B<deselect>
-
-Deselects the checkbutton and sets the associated variable to its ``off''
-value.
-
-=item I<$checkbutton>-E<gt>B<flash>
-
-Flashes the checkbutton. This is accomplished by redisplaying the checkbutton
-several times, alternating between active and normal colors. At
-the end of the flash the checkbutton is left in the same normal/active
-state as when the command was invoked.
-This command is ignored if the checkbutton's state is B<disabled>.
-
-=item I<$checkbutton>-E<gt>B<invoke>
-
-Does just what would have happened if the user invoked the checkbutton
-with the mouse: toggle the selection state of the button and invoke
-the L<perl/Tk callback|Tk::callbacks> associated with the checkbutton, if there is one.
-The return value is the return value from the L<perl/Tk callback|Tk::callbacks>, or an
-empty string if there is no command associated with the checkbutton.
-This command is ignored if the checkbutton's state is B<disabled>.
-
-=item I<$checkbutton>-E<gt>B<select>
-
-Selects the checkbutton and sets the associated variable to its ``on''
-value.
-
-=item I<$checkbutton>-E<gt>B<toggle>
-
-Toggles the selection state of the button, redisplaying it and
-modifying its associated variable to reflect the new state.
-
-=back
-
-=head1 BINDINGS
-
-Tk automatically creates class bindings for checkbuttons that give them
-the following default behavior:
-
-=over 4
-
-=item [1]
-
-On Unix systems, a checkbutton activates whenever the mouse passes
-over it and deactivates whenever the mouse leaves the checkbutton. On
-Mac and Windows systems, when mouse button 1 is pressed over a
-checkbutton, the button activates whenever the mouse pointer is inside
-the button, and deactivates whenever the mouse pointer leaves the
-button.
-
-=item [2]
-
-When mouse button 1 is pressed over a checkbutton, it is invoked (its
-selection state toggles and the command associated with the button is
-invoked, if there is one).
-
-=item [3]
-
-When a checkbutton has the input focus, the space key causes the checkbutton
-to be invoked. Under Windows, there are additional key bindings; plus
-(+) and equal (=) select the button, and minus (-) deselects the button.
-
-If the checkbutton's state is B<disabled> then none of the above
-actions occur: the checkbutton is completely non-responsive.
-
-The behavior of checkbuttons can be changed by defining new bindings for
-individual widgets or by redefining the class bindings.
-
-=back
-
-=head1 KEYWORDS
-
-checkbutton, widget
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Clipboard.pod b/Master/tlpkg/tlperl/lib/Tk/Clipboard.pod
deleted file mode 100644
index a65eb37a870..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Clipboard.pod
+++ /dev/null
@@ -1,89 +0,0 @@
-# Copyright (c) 1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::clipboard - Manipulate Tk clipboard
-
-=for category User Interaction
-
-=head1 SYNOPSIS
-
-I<$widget>-E<gt>B<clipboard>I<Option>?(I<args>)?
-
-=head1 DESCRIPTION
-
-This command provides an interface to the Tk clipboard,
-which stores data for later retrieval using the selection mechanism.
-In order to copy data into the clipboard, B<clipboardClear> must
-be called, followed by a sequence of one or more calls to
-B<clipboardAppend>. To ensure that the clipboard is updated atomically, all
-appends should be completed before returning to the event loop.
-
-The following methods are currently supported:
-
-=over 4
-
-=item I<$widget>-E<gt>B<clipboardClear>
-
-Claims ownership of the clipboard on I<$widget>'s display and removes
-any previous contents. Returns an empty string.
-
-=item I<$widget>-E<gt>B<clipboardAppend>(?B<-format>=E<gt>I<format>?,?B<-type>=E<gt>I<type>?,?B<-->?,I<data>)
-
-Appends I<data> to the clipboard on $widget's
-display in the form given by I<type> with the representation given
-by I<format> and claims ownership of the clipboard on $widget's
-display.
-
-=over 4
-
-I<Type> specifies the form in which the selection is to be returned
-(the desired ``target'' for conversion, in ICCCM terminology), and
-should be an atom name such as STRING or FILE_NAME; see the
-Inter-Client Communication Conventions Manual for complete details.
-I<Type> defaults to STRING.
-
-The I<format> argument specifies the representation that should be
-used to transmit the selection to the requester (the second column of
-Table 2 of the ICCCM), and defaults to STRING. If I<format> is
-STRING, the selection is transmitted as 8-bit ASCII characters.
-See the L<Tk::Selection> documentation for explanation of what happens
-if I<format> is not STRING.
-Note that arguments passed to
-B<clipboardAppend> are concatenated before conversion, so the
-caller must take care to ensure appropriate spacing across string
-boundaries. All items appended to the clipboard with the same
-I<type> must have the same I<format>.
-
-A B<--> argument may be specified to mark the end of options: the
-next argument will always be used as I<data>.
-This feature may be convenient if, for example, I<data> starts
-with a B<->.
-
-=back
-
-=back
-
-=over 4
-
-=item I<$widget>-E<gt>B<clipboardGet>( ?-type? );
-
-Retrieve data from the clipboard on I<widget>'s display.
-I<-type> specifies the form in which the data is
-to be returned and should be an atom name such as STRING or
-FILE_NAME. Type defaults to STRING. This command is equivalent
-to C<SelectionGet( -selection =E<gt> 'CLIPBOARD' )>.
-
-=back
-
-=head1 KEYWORDS
-
-clear, format, clipboard, append, selection, type
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/CmdLine.pod b/Master/tlpkg/tlperl/lib/Tk/CmdLine.pod
deleted file mode 100644
index 58b69fded17..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/CmdLine.pod
+++ /dev/null
@@ -1,454 +0,0 @@
-=head1 NAME
-
-Tk::CmdLine - Process standard X11 command line options and set initial resources
-
-=for pm Tk/CmdLine.pm
-
-=for category Creating and Configuring Widgets
-
-=head1 SYNOPSIS
-
- Tk::CmdLine::SetArguments([@argument]);
-
- my $value = Tk::CmdLine::cget([$option]);
-
- Tk::CmdLine::SetResources((\@resource | $resource) [, $priority]);
-
- Tk::CmdLine::LoadResources(
- [ -symbol => $symbol ]
- [ -file => $fileSpec ]
- [ -priority => $priority ]
- [ -echo => $fileHandle ] );
-
-=head1 DESCRIPTION
-
-Process standard X11 command line options and set initial resources.
-
-The X11R5 man page for X11 says: "Most X programs attempt to use the same names
-for command line options and arguments. All applications written with the
-X Toolkit Intrinsics automatically accept the following options: ...".
-This module processes these command line options for perl/Tk applications
-using the C<SetArguments>() function.
-
-This module can optionally be used to load initial resources explicitly via
-function C<SetResources>(), or from specified files (default: the standard X11
-application-specific resource files) via function C<LoadResources>().
-
-=head2 Command Line Options
-
-=over 4
-
-=item B<-background> I<Color> | B<-bg> I<Color>
-
-Specifies the color to be used for the window background.
-
-=item B<-class> I<Class>
-
-Specifies the class under which resources for the application should be found.
-This option is useful in shell aliases to distinguish between invocations
-of an application, without resorting to creating links to alter the executable
-file name.
-
-=item B<-display> I<Display> | B<-screen> I<Display>
-
-Specifies the name of the X server to be used.
-
-=item B<-font> I<Font> | B<-fn> I<Font>
-
-Specifies the font to be used for displaying text.
-
-=item B<-foreground> I<Color> | B<-fg> I<Color>
-
-Specifies the color to be used for text or graphics.
-
-=item B<-geometry> I<Geometry>
-
-Specifies the initial size and location of the I<first>
-L<MainWindow|Tk::MainWindow>.
-
-=item B<-iconic>
-
-Indicates that the user would prefer that the application's windows initially
-not be visible as if the windows had been immediately iconified by the user.
-Window managers may choose not to honor the application's request.
-
-=item B<-motif>
-
-Specifies that the application should adhere as closely as possible to Motif
-look-and-feel standards. For example, active elements such as buttons and
-scrollbar sliders will not change color when the pointer passes over them.
-
-=item B<-name> I<Name>
-
-Specifies the name under which resources for the application should be found.
-This option is useful in shell aliases to distinguish between invocations
-of an application, without resorting to creating links to alter the executable
-file name.
-
-=item B<-synchronous>
-
-Indicates that requests to the X server should be sent synchronously, instead of
-asynchronously. Since Xlib normally buffers requests to the server, errors do
-do not necessarily get reported immediately after they occur. This option turns
-off the buffering so that the application can be debugged. It should never
-be used with a working program.
-
-=item B<-title> I<TitleString>
-
-This option specifies the title to be used for this window. This information is
-sometimes used by a window manager to provide some sort of header identifying
-the window.
-
-=item B<-xrm> I<ResourceString>
-
-Specifies a resource pattern and value to override any defaults. It is also
-very useful for setting resources that do not have explicit command line
-arguments.
-
-The I<ResourceString> is of the form E<lt>I<pattern>E<gt>:E<lt>I<value>E<gt>,
-that is (the first) ':' is used to determine which part is pattern and which
-part is value. The (E<lt>I<pattern>E<gt>, E<lt>I<value>E<gt>) pair is entered
-into the options database with B<optionAdd> (for each
-L<MainWindow|Tk::MainWindow> configured), with I<interactive> priority.
-
-=back
-
-=head2 Initial Resources
-
-There are several mechanism for initializing the resource database to be used
-by an X11 application. Resources may be defined in a $C<HOME>/.Xdefaults file,
-a system application defaults file (e.g.
-/usr/lib/X11/app-defaults/E<lt>B<CLASS>E<gt>),
-or a user application defaults file (e.g. $C<HOME>/E<lt>B<CLASS>E<gt>).
-The Tk::CmdLine functionality for setting initial resources concerns itself
-with the latter two.
-
-Resource files contain data lines of the form
-E<lt>I<pattern>E<gt>:E<lt>I<value>E<gt>.
-They may also contain blank lines and comment lines (denoted
-by a ! character as the first non-blank character). Refer to L<option|Tk::option>
-for a description of E<lt>I<pattern>E<gt>:E<lt>I<value>E<gt>.
-
-=over 4
-
-=item System Application Defaults Files
-
-System application defaults files may be specified via environment variable
-$C<XFILESEARCHPATH> which, if set, contains a list of file patterns
-(joined using the OS-dependent path delimiter, e.g. colon on B<UNIX>).
-
-=item User Application Defaults Files
-
-User application defaults files may be specified via environment variables
-$C<XUSERFILESEARCHPATH>, $C<XAPPLRESDIR> or $C<HOME>.
-
-=back
-
-=head1 METHODS
-
-=over 4
-
-=item B<SetArguments> - Tk::CmdLine::SetArguments([@argument])
-
-Extract the X11 options contained in a specified array (@ARGV by default).
-
- Tk::CmdLine::SetArguments([@argument])
-
-The X11 options may be specified using a single dash I<-> as per the X11
-convention, or using two dashes I<--> as per the POSIX standard (e.g.
-B<-geometry> I<100x100>, B<-geometry> I<100x100> or B<-geometry=>I<100x100>).
-The options may be interspersed with other options or arguments.
-A I<--> by itself terminates option processing.
-
-By default, command line options are extracted from @ARGV the first time
-a MainWindow is created. The Tk::MainWindow constructor indirectly invokes
-C<SetArguments>() to do this.
-
-=item B<GetArguments> - Tk::CmdLine::GetArguments()
-
-Get a list of the X11 options that have been processed by C<SetArguments>().
-(C<GetArguments>() first invokes C<SetArguments>() if it has not already been invoked.)
-
-=item B<cget> - Tk::CmdLine::cget([$option])
-
-Get the value of a configuration option specified via C<SetArguments>().
-(C<cget>() first invokes C<SetArguments>() if it has not already been invoked.)
-
- Tk::CmdLine::cget([$option])
-
-The valid options are: B<-class>, B<-name>, B<-screen> and B<-title>.
-If no option is specified, B<-class> is implied.
-
-A typical use of C<cget>() might be to obtain the application class in order
-to define the name of a resource file to be loaded in via C<LoadResources>().
-
- my $class = Tk::CmdLine::cget(); # process command line and return class
-
-=item B<SetResources> - Tk::CmdLine::SetResources((\@resource | $resource) [, $priority])
-
-Set the initial resources.
-
- Tk::CmdLine::SetResources((\@resource | $resource) [, $priority])
-
-A single resource may be specified using a string of the form
-'E<lt>I<pattern>E<gt>:E<lt>I<value>E<gt>'. Multiple resources may be specified
-by passing an array reference whose elements are either strings of the above
-form, and/or anonymous arrays of the form [ E<lt>I<pattern>E<gt>,
-E<lt>I<value>E<gt> ]. The optional second argument specifies the priority,
-as defined in L<option|Tk::option>, to be associated with the resources
-(default: I<userDefault>).
-
-Note that C<SetResources>() first invokes C<SetArguments>() if it has not already
-been invoked.
-
-=item B<LoadResources> - Tk::CmdLine::LoadResources([%options])
-
-Load initial resources from one or more files.
-
- Tk::CmdLine::LoadResources(
- [ -symbol => $symbol ]
- [ -file => $fileSpec ]
- [ -priority => $priority ]
- [ -echo => $fileHandle ] );
-
-[ B<-symbol> =E<gt> $symbol ] specifies the name of an environment variable
-that, if set, defines a list of one or more directories and/or file patterns
-(joined using the OS-dependent path delimiter, e.g. colon on B<UNIX>).
-$C<XUSERFILESEARCHPATH> is a special case.
-If $C<XUSERFILESEARCHPATH> is not set, $C<XAPPLRESDIR> is checked instead.
-If $C<XAPPLRESDIR> is not set, $C<HOME> is checked instead.
-
-An item is identified as a file pattern if it contains one or more /%[A-Za-z]/
-patterns. Only patterns B<%L>, B<%T> and B<%N> are currently recognized. All
-others are replaced with the null string. Pattern B<%L> is translated into
-$C<LANG>. Pattern B<%T> is translated into I<app-defaults>. Pattern B<%N> is
-translated into the application class name.
-
-Each file pattern, after substitutions are applied, is assumed to define a
-FileSpec to be examined.
-
-When a directory is specified, FileSpecs
-E<lt>B<DIRECTORY>E<gt>/E<lt>B<LANG>E<gt>/E<lt>B<CLASS>E<gt>
-and E<lt>B<DIRECTORY>E<gt>/E<lt>B<CLASS>E<gt> are defined, in that order.
-
-[ B<-file> =E<gt> $fileSpec ] specifies a resource file to be loaded in.
-The file is silently skipped if if does not exist, or if it is not readable.
-
-[ B<-priority> =E<gt> $priority ] specifies the priority, as defined in
-L<option|Tk::option>, to be associated with the resources
-(default: I<userDefault>).
-
-[ B<-echo> =E<gt> $fileHandle ] may be used to specify that a line should be
-printed to the corresponding FileHandle (default: \*STDOUT) everytime a file
-is examined / loaded.
-
-If no B<-symbol> or B<-file> options are specified, C<LoadResources>()
-processes symbol $C<XFILESEARCHPATH> with priority I<startupFile> and
-$C<XUSERFILESEARCHPATH> with priority I<userDefault>.
-(Note that $C<XFILESEARCHPATH> and $C<XUSERFILESEARCHPATH> are supposed to
-contain only patterns. $C<XAPPLRESDIR> and $C<HOME> are supposed to be a single
-directory. C<LoadResources>() does not check/care whether this is the case.)
-
-For each set of FileSpecs, C<LoadResources>() examines each FileSpec to
-determine if the file exists and is readable. The first file that meets this
-criteria is read in and C<SetResources>() is invoked.
-
-Note that C<LoadResources>() first invokes C<SetArguments>() if it has not already
-been invoked.
-
-=back
-
-=head1 NOTES
-
-This module is an object-oriented module whose methods can be invoked as object
-methods, class methods or regular functions. This is accomplished via an
-internally-maintained object reference which is created as necessary, and which
-always points to the last object used. C<SetArguments>(), C<SetResources>() and
-C<LoadResources>() return the object reference.
-
-=head1 EXAMPLES
-
-=over
-
-=item 1
-
-@ARGV is processed by Tk::CmdLine at MainWindow creation.
-
- use Tk;
-
- # <Process @ARGV - ignoring all X11-specific options>
-
- my $mw = MainWindow->new();
-
- MainLoop();
-
-=item 2
-
-@ARGV is processed by Tk::CmdLine before MainWindow creation.
-An @ARGV of (--geometry=100x100 -opt1 a b c -bg red)
-is equal to (-opt1 a b c) after C<SetArguments>() is invoked.
-
- use Tk;
-
- Tk::CmdLine::SetArguments(); # Tk::CmdLine->SetArguments() works too
-
- # <Process @ARGV - not worrying about X11-specific options>
-
- my $mw = MainWindow->new();
-
- MainLoop();
-
-=item 3
-
-Just like 2) except that default arguments are loaded first.
-
- use Tk;
-
- Tk::CmdLine::SetArguments(qw(-name test -iconic));
- Tk::CmdLine::SetArguments();
-
- # <Process @ARGV - not worrying about X11-specific options>
-
- my $mw = MainWindow->new();
-
- MainLoop();
-
-=item 4
-
-@ARGV is processed by Tk::CmdLine before MainWindow creation.
-Standard resource files are loaded in before MainWindow creation.
-
- use Tk;
-
- Tk::CmdLine::SetArguments();
-
- # <Process @ARGV - not worrying about X11-specific options>
-
- Tk::CmdLine::LoadResources();
-
- my $mw = MainWindow->new();
-
- MainLoop();
-
-=item 5
-
-@ARGV is processed by Tk::CmdLine before MainWindow creation.
-Standard resource files are loaded in before MainWindow creation
-using non-default priorities.
-
- use Tk;
-
- Tk::CmdLine::SetArguments();
-
- # <Process @ARGV - not worrying about X11-specific options>
-
- Tk::CmdLine::LoadResources(-echo => \*STDOUT,
- -priority => 65, -symbol => 'XFILESEARCHPATH' );
- Tk::CmdLine::LoadResources(-echo => \*STDOUT,
- -priority => 75, -symbol => 'XUSERFILESEARCHPATH' );
-
- my $mw = MainWindow->new();
-
- MainLoop();
-
-=item 6
-
-@ARGV is processed by Tk::CmdLine before MainWindow creation.
-Standard resource files are loaded in before MainWindow creation.
-Individual resources are also loaded in before MainWindow creation.
-
- use Tk;
-
- Tk::CmdLine::SetArguments();
-
- # <Process @ARGV - not worrying about X11-specific options>
-
- Tk::CmdLine::LoadResources();
-
- Tk::CmdLine::SetResources( # set a single resource
- '*Button*background: red',
- 'widgetDefault' );
-
- Tk::CmdLine::SetResources( # set multiple resources
- [ '*Button*background: red', '*Button*foreground: blue' ],
- 'widgetDefault' );
-
- my $mw = MainWindow->new();
-
- MainLoop();
-
-=back
-
-=head1 ENVIRONMENT
-
-=over 4
-
-=item B<HOME> (optional)
-
-Home directory which may contain user application defaults files as
-$C<HOME>/$C<LANG>/E<lt>B<CLASS>E<gt> or $C<HOME>/E<lt>B<CLASS>E<gt>.
-
-=item B<LANG> (optional)
-
-The current language (default: I<C>).
-
-=item B<XFILESEARCHPATH> (optional)
-
-List of FileSpec patterns
-(joined using the OS-dependent path delimiter, e.g. colon on B<UNIX>)
-used in defining system application defaults files.
-
-=item B<XUSERFILESEARCHPATH> (optional)
-
-List of FileSpec patterns
-(joined using the OS-dependent path delimiter, e.g. colon on B<UNIX>)
-used in defining user application defaults files.
-
-=item B<XAPPLRESDIR> (optional)
-
-Directory containing user application defaults files as
-$C<XAPPLRESDIR>/$C<LANG>/E<lt>B<CLASS>E<gt> or
-$C<XAPPLRESDIR>/E<lt>B<CLASS>E<gt>.
-
-=back
-
-=head1 SEE ALSO
-
-L<MainWindow|Tk::MainWindow>
-L<option|Tk::option>
-
-=head1 HISTORY
-
-=over 4
-
-=item *
-
-1999.03.04 Ben Pavon E<lt>ben.pavon@hsc.hac.comE<gt>
-
-Rewritten as an object-oriented module.
-
-Allow one to process command line options in a specified array (@ARGV by default).
-Eliminate restrictions on the format and location of the options within the array
-(previously the X11 options could not be specified in POSIX format and had to be
-at the beginning of the array).
-
-Added the C<SetResources>() and C<LoadResources>() functions to allow the definition
-of resources prior to MainWindow creation.
-
-=item *
-
-2000.08.31 Ben Pavon E<lt>ben.pavon@hsc.hac.comE<gt>
-
-Added the C<GetArguments>() method which returns the list of arguments that
-have been processed by C<SetArguments>().
-
-Modified C<LoadResources>() to split the symbols using the OS-dependent
-path delimiter defined in the B<Config> module.
-
-Modified C<LoadResources>() to eliminate a warning message when processing
-patterns B<%l>, B<%C>, B<%S>.
-
-=back
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/ColorEditor.pod b/Master/tlpkg/tlperl/lib/Tk/ColorEditor.pod
deleted file mode 100644
index 48e6477f3ef..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/ColorEditor.pod
+++ /dev/null
@@ -1,120 +0,0 @@
-
-=head1 NAME
-
-Tk::ColorEditor - a general purpose Tk widget Color Editor
-
-=for pm Tk/ColorEditor.pm
-
-=for category Popups and Dialogs
-
-=head1 SYNOPSIS
-
- use Tk::ColorEditor;
-
- $cref = $mw->ColorEditor(-title => $title, -cursor => @cursor);
-
- $cref->Show;
-
-=head1 DESCRIPTION
-
-ColorEditor is implemented as an object with various methods, described
-below. First, create your ColorEditor object during program initialization
-(one should be sufficient), and then configure it by specifying a list of Tk
-widgets to colorize. When it's time to use the editor, invoke the Show()
-method.
-
-ColorEditor allows some customization: you may alter the color attribute
-menu by adding and/or deleting menu items and/or separators, turn the status
-window on or off, alter the configurator's list of color widgets, or even
-supply your own custom color configurator callback.
-
-=over 4
-
-=item 1.
-
-Call the constructor to create the editor object, which in turn returns a
-blessed reference to the new object:
-
- use Tk::ColorEditor;
-
- $cref = $mw->ColorEditor(
- -title => $title,
- -cursor => @cursor,
- );
-
- mw - a window reference, usually the result of a MainWindow->new
- call. As the default root of a widget tree, $mw and all
- descendant widgets at object-creation-time are configured
- by the default color configurator procedure. (You probably
- want to change this though or you might end up colorizing
- ColorEditor!)
- title - Toplevel title, default = ' '.
- cursor - a valid Tk '-cursor' specification (default is
- 'top_left_arrow'). This cursor is used over all ColorEditor
- "hot spots".
-
-=item 2.
-
-Invoke the configure() method to change editor characteristics:
-
- $cref->configure(-option => value, ..., -option-n => value-n);
-
- options:
- -command : a callback to a `set_colors' replacement.
- -widgets : a reference to a list of widget references
- for the color configurator.
- -display_status : TRUE IFF display the ColorEditor status
- window when applying colors.
- -add_menu_item : 'SEP', or a color attribute menu item.
- -delete_menu_item : 'SEP', a color attribute menu item, or color
- attribute menu ordinal.
-
- For example:
-
- $cref->configure(-delete_menu_item => 3,
- -delete_menu_item => 'disabledforeground',
- -add_menu_item => 'SEP',
- -add_menu_item => 'New color attribute',
- -widgets => [$ce, $qu, $f2b2],
- -widgets => [$f2->Descendants],
- -command => [\&my_special_configurator, some, args ]
- );
-
-=item 3.
-
-Invoke the Show() method on the editor object, say, by a button or menu press:
-
- $cref->Show;
-
-=item 4.
-
-The cget(-widgets) method returns a reference to a list of widgets that
-are colorized by the configurator. Typically, you add new widgets to
-this list and then use it in a subsequent configure() call to expand your
-color list.
-
- $cref->configure(
- -widgets => [
- @{$Filesystem_ref->cget(-widgets)}, @{$cref->cget(-widgets)},
- ]
- );
-
-=item 5.
-
-The delete_widgets() method expects a reference to a list of widgets which are
-then removed from the current color list.
-
- $cref->delete_widgets($OBJTABLE{$objname}->{'-widgets'})
-
-=back
-
-=head1 AUTHORS
-
-Stephen O. Lidie, Lehigh University Computing Center. 95/03/05
-lusol@Lehigh.EDU
-
-Many thanks to Guy Decoux (decoux@moulon.inra.fr) for doing the initial
-translation of tcolor.tcl to TkPerl, from which this code has been derived.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Common.pod b/Master/tlpkg/tlperl/lib/Tk/Common.pod
deleted file mode 100644
index cd53ab79a99..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Common.pod
+++ /dev/null
@@ -1,16 +0,0 @@
-
-=head1 NAME
-
-Tk::DragDrop::Common - private class used by Drag&Drop
-
-=for pm DragDrop/DragDrop/Common.pm
-
-=for category Experimental Modules
-
-=head1 DESCRIPTION
-
-This class provides methods to automate the the loading and declaring
-of Drop and Site 'types'.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Compound.pod b/Master/tlpkg/tlperl/lib/Tk/Compound.pod
deleted file mode 100644
index 01f6e5f2639..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Compound.pod
+++ /dev/null
@@ -1,298 +0,0 @@
-# Copyright (c) 1996, Expert Interface Technologies
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-# The file man.macros and some of the macros used by this file are
-# copyrighted: (c) 1990 The Regents of the University of California.
-# (c) 1994-1995 Sun Microsystems, Inc.
-# The license terms of the Tcl/Tk distrobution are in the file
-# license.tcl.
-
-=head1 NAME
-
-Tk::Compound - Create multi-line compound images.
-
-=for category Tk Image Classes
-
-=head1 SYNOPSIS
-
- use Tk::Compound;
- $image = $widget->Compound(name,options);
- $image->Line(options);
- $image->Text(options);
- $image->Bitmap(options);
- $image->Image(options);
- $image->Space(options);
-
-=for comment
-This paragraph used to be written different, but perldoc 3.14 cannot
-display this paragraph.
-S< >use Tk::Compound;
-S< >I<$image> = I<$widget>-E<gt>B<Compound>?(I<name>??,I<options>?)
-S< >I<$image>-E<gt>B<Line>?(I<options>?)
-S< >I<$image>-E<gt>B<Text>?(I<options>?)
-S< >I<$image>-E<gt>B<Bitmap>?(I<options>?)
-S< >I<$image>-E<gt>B<Image>?(I<options>?)
-S< >I<$image>-E<gt>B<Space>?(I<options>?)
-
-=head1 DESCRIPTION
-
-Compound image types can be used to create images that consists of
-multiple horizontal lines; each line is composed of a series of items
-(texts, bitmaps, images or spaces) arranged from left to
-right. Compound images are mainly used to embed complex drawings into
-widgets that support the B<-image> option. As shown in the EXAMPLE
-section below, a compound image can be used to display a bitmap and a
-text string simutaneously in a Tk B<Button> widget.
-
-Compound images can only be used on windows on the same display as, and
-with the same pixel depth and visual as the I<$widget> used to create them.
-
-=head1 CREATING COMPOUND IMAGES
-
-Compounds are created using I<$widget>-E<gt>B<Compound>.
-Compounds support the following I<options>:
-
-=over 4
-
-=item B<-background> =E<gt> I<color>
-
-Specifies the background color of the compound image. This color is
-also used as the default background color for the bitmap items in the
-compound image.
-
-=item B<-borderwidth> =E<gt> I<pixels>
-
-Specifies a non-negative value indicating the width of the 3-D border
-drawn around the compound image.
-
-=item B<-font> =E<gt> I<font>
-
-Specifies the default font for the text items in the compound image.
-
-=item B<-foreground> =E<gt> I<color>
-
-Specifies the default foreground color for the bitmap and text items
-in the compound image.
-
-=item B<-padx> =E<gt> I<value>
-
-Specifies a non-negative value indicating how much extra space to
-request for the compound image in the X-direction. The I<value> may
-have any of the forms acceptable to B<Tk_GetPixels(3)>.
-
-=item B<-pady> =E<gt> I<value>
-
-Specifies a non-negative value indicating how much extra space to
-request for the compound image in the Y-direction.
-
-=item B<-relief> =E<gt> I<value>
-
-Specifies the 3-D effect desired for the background of the compound
-image. Acceptable values are B<raised>, B<sunken>, B<flat>,
-B<ridge>, and B<groove>.
-
-=item B<-showbackground> =E<gt> I<value>
-
-Specifies whether the background and the 3D borders should be drawn.
-Must be a valid boolean value. By default the background is not drawn
-and the compound image appears to have a transparent background.
-
-
-=back
-
-=head1 IMAGE COMMAND
-
-When a compound image is created, Tk also creates a new object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-
-The object also supports the following methods:
-
-=over 4
-
-=item I<$compound>-E<gt>B<Line>?(I<option => value ...>)?
-
-Creates a new line at the bottom of the compound image. Lines support
-the following I<options>:
-
-=over 4
-
-=item B<-anchor> value
-
-Specifies how the line should be aligned along the horizontal axis.
-When the values are B<w>, B<sw> or B<nw>, the line is aligned
-to the left. When the values are B<c>, B<s> or B<n>, the line
-is aligned to the middle. When the values are B<e>, B<se> or
-B<ne>, the line is aligned to the right.
-
-=item B<-padx> =E<gt> I<value>
-
-Specifies a non-negative value indicating how much extra space to
-request for this line in the X-direction.
-
-=back
-
-=item I<$compound>-E<gt>I<Itemtype>?(I<option => value ...>)?
-
-Creates a new item of the type I<Itemtype> at the end of the last
-line of the compound image. All types of items support
-these following common I<options>:
-
-=over 4
-
-=item B<-anchor> value
-
-Specifies how the item should be aligned along the vertical axis. When
-the values are B<n>, B<nw> or B<ne>, the item is aligned to
-the top of the line. When the values are B<c>, B<w> or B<e>,
-the item is aligned to the middle of the line. When the values are
-B<s>, B<se> or B<sw>, the item is aligned to the bottom of
-the line.
-
-=item B<-padx> =E<gt> I<value>
-
-Specifies a non-negative value indicating how much extra space to
-request for this item in the X-direction.
-
-=item B<-pady> =E<gt> I<value>
-
-Specifies a non-negative value indicating how much extra space to
-request for this item in the Y-direction.
-
-=item I<item-type> can be any of the following:
-
-=back
-
-=item I<$compound>-E<gt>B<Bitmap>?(I<option => value ...>)?
-
-Creates a new bitmap item of at the end of the last
-line of the compound image. Additional I<options> accepted by the
-bitmap type are:
-
-=over 4
-
-=item B<-background> =E<gt> I<color>
-
-Specifies the background color of the bitmap item.
-
-=item B<-bitmap> =E<gt> I<name>
-
-Specifies a bitmap to display in this item, in any of the forms
-acceptable to B<Tk_GetBitmap(3)>.
-
-=item B<-foreground> =E<gt> I<color>
-
-Specifies the foreground color of the bitmap item.
-
-=back
-
-=item I<$compound>-E<gt>B<Image>?(I<option => value ...>)?
-
-Creates a new image item of at the end of the last
-line of the compound image. Additional I<options> accepted by the
-image type are:
-
-=over 4
-
-=item B<-image> =E<gt> I<name>
-
-Specifies an image to display in this item. I<name>
-must have been created with the B<image create> command.
-
-=back
-
-=item I<$compound>-E<gt>B<Space>?(I<option => value ...>)?
-
-Creates a new space item of at the end of the last line of the
-compound image. Space items do not display anything. They just acts as
-space holders that add additional spaces between items inside a
-compound image. Additional I<options> accepted by the image type
-are:
-
-=over 4
-
-=item B<-width> =E<gt> I<value>
-
-Specifies the width of this space. The I<value> may have any of the
-forms acceptable to B<Tk_GetPixels(3)>.
-
-=item B<-height> =E<gt> I<value>
-
-Specifies the height of this space. The I<value> may have any of
-the forms acceptable to B<Tk_GetPixels(3)>.
-
-=back
-
-=item I<$compound>-E<gt>B<Text>?(I<option => value ...>)?
-
-Creates a new text item of at the end of the last line of the compound
-image. Additional I<options> accepted by the text type are:
-
-=over 4
-
-=item B<-background> =E<gt> I<color>
-
-Specifies the background color of the text item.
-
-=item B<-font> =E<gt> I<name>
-
-Specifies the font to be used for this text item.
-
-=item B<-foreground> =E<gt> I<color>
-
-Specifies the foreground color of the text item.
-
-=item B<-justify> I<value>
-
-When there are multiple lines of text displayed in a text item, this
-option determines how the lines line up with each other. I<value>
-must be one of B<left>, B<center>, or B<right>. B<Left>
-means that the lines' left edges all line up, B<center> means that
-the lines' centers are aligned, and B<right> means that the lines'
-right edges line up.
-
-=item B<-text> =E<gt> I<string>
-
-Specifies a text string to display in this text item.
-
-=item B<-underline> I<value>
-
-Specifies the integer index of a character to underline in the text
-item. 0 corresponds to the first character of the text displayed in
-the text item, 1 to the next character, and so on.
-
-=item B<-wraplength> I<value>
-
-This option specifies the maximum line length of the label string on
-this text item. If the line length of the label string exceeds this
-length, it is wrapped onto the next line, so that no line is longer
-than the specified length. The value may be specified in any of the
-standard forms for screen distances. If this value is less than or
-equal to 0 then no wrapping is done: lines will break only at newline
-characters in the text.
-
-=back
-
-=back
-
-=head1 EXAMPLE
-
-The following example creates a compound image with a bitmap and a
-text string and places this image into a B<Button(n)>
-widget. Notice that the image must be created using the widget
-that it resides in.
-
- my $b = $parent->Button;
- my $c = $b->Compound;
- $b->configure(-image => $c);
- $c->Line;
- $c->Bitmap(-bitmap => 'warning');
- $c->Space(-width => 8);
- $c->Text(-text => "Warning", -underline => 0);
- $b->pack;
-
-=head1 KEYWORDS
-
-image(n), Tix(n)
diff --git a/Master/tlpkg/tlperl/lib/Tk/ConfigSpecs.pod b/Master/tlpkg/tlperl/lib/Tk/ConfigSpecs.pod
deleted file mode 100644
index 5f90c2716bb..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/ConfigSpecs.pod
+++ /dev/null
@@ -1,262 +0,0 @@
-# $Id: configspec.pod 1.2 Wed, 12 Nov 1997 00:30:45 +0100 ach $
-
-=head1 NAME
-
-Tk::ConfigSpecs - Defining behaviour of 'configure' for composite widgets.
-
-=for category Derived Widgets
-
-=head1 SYNOPSIS
-
- sub Populate
- {
- my ($composite,$args) = @_;
- ...
- $composite->ConfigSpecs('-attribute' => [ where,dbName,dbClass,default ]);
- $composite->ConfigSpecs('-alias' => '-otherattribute');
- $composite->ConfigSpecs('DEFAULT' => [ where ]);
- $composite->ConfigSpecs($subwidget->ConfigSpecs);
- ...
- }
-
- $composite->configure(-attribute => value);
-
-=head1 DESCRIPTION
-
-The aim is to make the composite widget configure method look as much like
-a regular Tk widget's configure as possible.
-(See L<Tk::options> for a description of this behaviour.)
-To enable this the attributes that the composite as a whole accepts
-needs to be defined.
-
-=head2 Defining the ConfigSpecs for a class.
-
-Typically a widget will have one or more calls like the following
-
- $composite->ConfigSpecs(-attribute => [where,dbName,dbClass,default]);
-
-in its B<Populate> method. When B<ConfigSpecs> is called this way
-(with arguments) the arguments are used to construct or augment/replace
-a hash table for the widget. (More than one I<-option>=E<gt>I<value>
-pair can be specified to a single call.)
-
-B<dbName>, B<dbClass> and default are only used by B<ConfigDefault> described
-below, or to respond to 'inquiry' configure commands.
-
-It may be either one of the values below, or a list of such values
-enclosed in B<[]>.
-
-The currently permitted values of B<where> are:
-
-=over 4
-
-=item B<'ADVERTISED'>
-
-Apply B<configure> to I<advertised> subwidgets.
-
-=item B<'DESCENDANTS'>
-
-Apply B<configure> recursively to all descendants.
-
-=item B<'CALLBACK'>
-
-Setting the attribute does C<Tk::Callback-E<gt>new($value)> before storing
-in C<$composite-E<gt>{Configure}{-attribute}>. This is appropriate for
-C<-command =E<gt> ...> attributes that are handled by the composite and not
-forwarded to a subwidget. (E.g. B<Tk::Tiler> has C<-yscrollcommand> to
-allow it to have scrollbar attached.)
-
-This may be the first of several 'validating' keywords (e.g. font, cursor,
-anchor etc.) that core Tk makes special for C code.
-
-=item B<'CHILDREN'>
-
-Apply B<configure> to all children. (Children are the immediate
-descendants of a widget.)
-
-=item B<'METHOD'>
-
-Call C<$cw-E<gt>attribute(value)>
-
-This is the most general case. Simply have a method of the composite
-class with the same name as the attribute. The method may do any
-validation and have whatever side-effects you like. (It is probably
-worth 'queueing' using B<afterIdle> for more complex side-effects.)
-
-=item B<'PASSIVE'>
-
-Simply store value in C<$composite-E<gt>{Configure}{-attribute}>.
-
-This form is also a useful placeholder for attributes which you
-currently only handle at create time.
-
-=item B<'SELF'>
-
-Apply B<configure> to the core widget (e.g. B<Frame>) that is the basis of
-the composite. (This is the default behaviour for most attributes which
-makes a simple Frame behave the way you would expect.) Note that once
-you have specified B<ConfigSpecs> for an attribute you must explicitly
-include C<'SELF'> in the list if you want the attribute to apply to the
-composite itself (this avoids nasty infinite recursion problems).
-
-=item B<$reference> (blessed)
-
-Call B<$reference>->configure(-attribute => value)
-
-A common case is where B<$reference> is a subwidget.
-
-$reference may also be result of
-
- Tk::Config->new(setmethod,getmethod,args,...);
-
-B<Tk::Config> class is used to implement all the above keyword types. The
-class has C<configure> and C<cget> methods so allows higher level code to
-I<always> just call one of those methods on an I<object> of some kind.
-
-=item B<hash reference>
-
-Defining:
-
- $cw->ConfigSpecs(
- ...
- -option => [ { -optionX=>$w1, -optionY=>[$w2, $w3] },
- dbname dbclass default ],
- ...
- );
-
-So C<$cw-E<gt>configure(-option =E<gt> value)> actually does
-
- $w1->configure(-optionX => value);
- $w2->configure(-optionY => value);
- $w3->configure(-optionY => value);
-
-=item B<'otherstring'>
-
-Call
-
- $composite->Subwidget('otherstring')->configure( -attribute => value );
-
-While this is here for backward compatibility with Tk-b5, it is probably
-better just to use the subwidget reference directly. The only
-case for retaining this form is to allow an additional layer of
-abstraction - perhaps having a 'current' subwidget - this is unproven.
-
-=item B<Aliases>
-
-C<ConfigSpecs( -alias =E<gt> '-otherattribute' )> is used to make C<-alias>
-equivalent to C<-otherattribute>. For example the aliases
-
- -fg => '-foreground',
- -bg => '-background'
-
-are provided automatically (if not already specified).
-
-=back
-
-=head2 Delegating all options of a widget class to a subwidget
-
- $composite->ConfigSpecs($subwidget->ConfigSpecs);
-
-The above generates a list of I<composite> ConfigSpecs arguments, one
-for each valid option in $subwidget's class, and delegates said option
-to $subwidget. See L<Tk::Widget> and the I<widget> method
-ConfigSpecs. Duplicating I<composite> ConfigSpecs and I<widget>
-ConfigSpecs keys will yield undefined results.
-
-
-=head2 Default values
-
-When the B<Populate> method returns B<ConfigDefault> is called. This calls
-
- $composite->ConfigSpecs;
-
-(with no arguments) to return a reference to a hash. Entries in the hash
-take the form:
-
- '-attribute' => [ where, dbName, dbClass, default ]
-
-B<ConfigDefault> ignores 'where' completely (and also the DEFAULT entry) and
-checks the 'options' database on the widget's behalf, and if an entry is
-present matching dbName/dbClass
-
- -attribute => value
-
-is added to the list of options that B<new> will eventually apply to the
-widget. Likewise if there is not a match and default is defined this
-default value will be added.
-
-Alias entries in the hash are used to convert user-specified values for the
-alias into values for the real attribute.
-
-=head2 B<New()-time configure>
-
-Once control returns to B<new>, the list of user-supplied options
-augmented by those from B<ConfigDefault> are applied to the widget using the
-B<configure> method below.
-
-Widgets are most flexible and most Tk-like if they handle the majority of
-their attributes this way.
-
-=head2 Configuring composites
-
-Once the above have occurred calls of the form:
-
- $composite->configure( -attribute => value );
-
-should behave like any other widget as far as end-user code is concerned.
-B<configure> will be handled by B<Tk::Derived::configure> as follows:
-
- $composite->ConfigSpecs;
-
-is called (with no arguments) to return a reference to a hash B<-attribute> is
-looked up in this hash, if B<-attribute> is not present in the hash then
-B<'DEFAULT'> is looked for instead. (Aliases are tried as well and cause
-redirection to the aliased attribute). The result should be a reference to a
-list like:
-
- [ where, dbName, dbClass, default ]
-
-at this stage only I<where> is of interest, it maps to a list of object
-references (maybe only one) foreach one
-
- $object->configure( -attribute => value );
-
-is B<eval>ed.
-
-=head2 Inquiring attributes of composites
-
- $composite->cget( '-attribute' );
-
-This is handled by B<Tk::Derived::cget> in a similar manner to configure. At
-present if I<where> is a list of more than one object it is ignored completely
-and the "cached" value in
-
- $composite->{Configure}{-attribute}.
-
-is returned.
-
-=head1 CAVEATS
-
-The C<-background> and C<-foreground> option values are automatically
-propagated down to all composite widget's children. This may be
-sometimes not desirable, especially if some subwidgets should use own
-color schemes, either by using explicit options or by option database
-definitions. If this is the case, then just add
-
- -foreground => 'SELF',
- -background => 'SELF',
-
-to C<ConfigSpecs>.
-
-It is the author's intention to port as many of the "Tix" composite widgets
-as make sense. The mechanism described above may have to evolve in order to
-make this possible, although now aliases are handled I think the above is
-sufficient.
-
-=head1 SEE ALSO
-
-L<Tk::composite|Tk::composite>,
-L<Tk::options|Tk::options>,
-L<Tk::Widget>
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Tk/DItem.pod b/Master/tlpkg/tlperl/lib/Tk/DItem.pod
deleted file mode 100644
index 27db79744df..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/DItem.pod
+++ /dev/null
@@ -1,439 +0,0 @@
-=head1 NAME
-
-Tk::DItem - Tix Display Items
-
-=for category Tix Extensions
-
-=head1 SYNOPSIS
-
-=head1 DESCRIPTION
-
-The Tix B<Display Items> and B<Display Types> are devised to
-solve a general problem: many Tix widgets (both existing and planned
-ones) display many items of many types simultaneously.
-
-For example, a hierarchical listbox widget (see L<Tk::HList>) can display
-items
-of images, plain text and subwindows in the form of a
-hierarchy. Another widget, the tabular listbox widget (see L<Tk::TList>)
-also displays items of the
-same types, although it arranges the items in a tabular form. Yet
-another widget, the spreadsheet widget (see L<Tk::TixGrid>),
-also displays similar types
-items, but in yet another format.
-
-In these examples, the display items in different widgets are only
-different in how they are arranged by the B<host widget>. In Tix,
-display items are clearly separated from the host widgets. The
-advantage is two-fold: first, the creation and configuration of
-display items become uniform across different host widgets. Second,
-new display item types can be added without the need to modify the
-existing host widgets.
-
-In a way, Tix display items are similar to the items inside Tk
-the canvas widget. However, unlike the Tix display items, the canvas
-items are not independent of the canvas widget; this makes it
-impossible to use the canvas items inside other types of TK widgets.
-
-The appearance of a display item is controlled by a set of
-I<attributes>. It is observed that each the attributes usually fall
-into one of two categroies: ``I<individual>'' or
-``I<collective>''. For example, the text items inside a HList widget
-may all display a different text string; however, in most cases, the
-text items share the same color, font and spacing. Instead of keeping
-a duplicated version of the same attributes inside each display item,
-it will be advantageous to put the collective attributes in a
-special object called a B<display style>. First, there is the space
-concern: a host widget may have many thousands of items; keeping
-dupilcated attributes will be very wasteful. Second, when it becomes
-necessary to change a collective attribute, such as changing all the
-text items' foreground color to red, it will be more efficient to
-change only the display style object than to modify all the text
-items one by one.
-
-The attributes of the a display item are thus stored in two places: it
-has a set of B<item options> to store its individual attributes. Each
-display item is also associated with a I<display style>, which specifies
-the collective attributes of all items associated with itself.
-
-The division between the individual and collective attributes are
-fixed and cannot be changed. Thus, when it becomes necessary for some
-items to differ in their collective attributes, two or more B<display styles>
-can be used. For example, suppose you want to display two
-columns of text items inside an HList widget, one column in red and
-the other in blue. You can create a TextStyle object called ``$red''
-which defines a red foreground, and another called ``$blue'', which
-defines a blue foreground. You can then associate all text items of
-the first column to ``$red'' and the second column to ``$blue''
-
-=head1 DISPLAY ITEM TYPES AND OPTIONS
-
-Currently there are three types of display items: B<text>,
-B<imagetext> and I<window>.
-
-=head1 IMAGETEXT ITEMS
-
-Display items of the type B<imagetext> are used to display an image
-together with a text string. Imagetext items support the following options:
-
-=head2 Imagetext Item Options
-
-=over 4
-
-=item Name: B<bitmap>
-
-=item Class: B<Bitmap>
-
-=item Switch: B<-bitmap>
-
-Specifies the bitmap to display in the item.
-
-=item Name: B<image>
-
-=item Class: B<Image>
-
-=item Switch: B<-image>
-
-Specifies the image to display in the item. When both the
-B<-bitmap> and B<-image> options are specified, only the image
-will be displayed.
-
-=item Name: B<imageTextStyle>
-
-=item Class: B<ImageTextStyle>
-
-=item Switch: B<-style>
-
-Specifies the display style to use for this item. Must be the
-name of a B<imagetext> display style that has already be created with
-B<ItemStyle>.
-
-=item Name: B<showImage>
-
-=item Class: B<ShowImage>
-
-=item Switch: B<-showimage>
-
-A Boolean value that specifies whether the image/bitmap should be
-displayed.
-
-=item Name: B<showText>
-
-=item Class: B<ShowText>
-
-=item Switch: B<-showtext>
-
-A Boolean value that specifies whether the text string should be
-displayed.
-
-=item Name: B<text>
-
-=item Class: B<Text>
-
-=item Switch: B<-text>
-
-Specifies the text string to display in the item.
-
-=item Name: B<underline>
-
-=item Class: B<Underline>
-
-=item Switch: B<-underline>
-
-Specifies the integer index of a character to underline in the text
-string in the item. 0 corresponds to the first character of the text
-displayed in the widget, 1 to the next character, and so on.
-
-=back
-
-=head2 Imagetext Style Options
-
-The style information of B<imagetext> items are stored in the
-B<imagetext> display style. The following options are supported:
-
-B<STANDARD OPTIONS>
-
-B<-activebackground> B<-activeforeground>
-B<-anchor> B<-background>
-B<-disabledbackground> B<-disabledforeground>
-B<-foreground> B<-font>
-B<-justify> B<-padx>
-B<-pady> B<-selectbackground>
-B<-selectforeground> B<-wraplength>
-
-See L<Tk::options> for details of the standard options.
-
-B<STYLE-SPECIFIC OPTIONS>
-
-=over 4
-
-=item Name: B<gap>
-
-=item Class: B<Gap>
-
-=item Switch: B<-gap>
-
-Specifies the distance between the bitmap/image and the text string,
-in number of pixels.
-
-=item Name: B<textAnchor>
-
-=item Class: B<TextAnchor>
-
-=item Switch: B<-textanchor>
-
-The anchor position on the image to which text part is attached.
-This is a perl/Tk addition. Defaults to B<e> for compatibility with standard
-Tix. The interesting cases are
-
-=over 8
-
-=item B<n>
-
-Text is centred above the image.
-
-=item B<s>
-
-Text is centred below the image
-
-=item B<e>
-
-Text is centred to right of the image.
-
-=item B<w>
-
-Text is centred to left of the image.
-
-=item B<c>
-
-Text is centred over the image.
-
-=back
-
-The B<sw>, B<se>, B<ne>, and b<nw> cases look rather odd.
-
-To get items to line up correctly it will usually be necessary
-to specify B<-anchor> as well. e.g. with default B<e> then anchoring
-item as a whole B<w> lines images up down left with text stuck to right side.
-
-=back
-
-=head1 TEXT ITEMS
-
-Display items of the type B<text> are used to display a text string
-in a widget. Text items support the following options:
-
-=head2 Text Item Options
-
-=over 4
-
-=item Name: B<textStyle>
-
-=item Class: B<TextStyle>
-
-=item Switch: B<-style>
-
-Specifies the display style to use for this text item. Must be the
-name of a B<text> display style that has already be created with
-B<ItemStyle>.
-
-=item Name: B<text>
-
-=item Class: B<Text>
-
-=item Switch: B<-text>
-
-Specifies the text string to display in the item.
-
-=item Name: B<underline>
-
-=item Class: B<Underline>
-
-=item Switch: B<-underline>
-
-Specifies the integer index of a character to underline in the item.
-0 corresponds to the first character of the text displayed in the
-widget, 1 to the next character, and so on.
-
-=back
-
-=head2 Text Style Options
-
-B<STANDARD OPTIONS>
-
-B<-activebackground> B<-activeforeground>
-B<-anchor> B<-background>
-B<-disabledbackground> B<-disabledforeground>
-B<-foreground> B<-font>
-B<-justify> B<-padx>
-B<-pady> B<-selectbackground>
-B<-selectforeground> B<-wraplength>
-
-See L<Tk::options> for details of the standard options.
-
-=head1 WINDOW ITEMS
-
-Display items of the type I<window> are used to display a
-sub-window in a widget. B<Window> items support the following
-options:
-
-=head2 Window Item Options
-
-=over 4
-
-=item Name: B<windowStyle>
-
-=item Class: B<WindowStyle>
-
-=item Switch: B<-style>
-
-Specifies the display style to use for this window item. Must be the
-name of a I<window> display style that has already be created with
-the B<ItemStyle> method.
-
-=item Name: B<window>
-
-=item Class: B<Window>
-
-=item Switch: B<-window>
-
-=item Alias: B<-widget>
-
-Specifies the sub-window to display in the item.
-
-=back
-
-=head2 Window Style Options
-
-B<STYLE STANDARD OPTIONS>
-
-B<-anchor> B<-padx> B<-pady>
-
-See L<Tk::options> for details of the standard options.
-
-=head1 CREATING DISPLAY ITEMS
-
-Display items do not exist on their and thus they cannot be created
-independently of the widgets they reside in. As a rule, display items
-are created by special methods of their ``host'' widgets. For
-example, the HList widgets has a method B<item> which can be used
-to create new display items. The following code creates a new text
-item at the third column of the entry foo inside an HList widget:
-
- my $hlist = $parent->HList(-columns=>3);
- $hlist->add('foo');
- $hlist->itemCreate('foo', 2, -itemtype=>'text', -text=>'Hello');
-
-The B<itemCreate> method of the HList widget accepts a variable
-number of arguments. The special argument B<-itemtype> specifies
-which type of display item to create. Options that are valid for this
-type of display items can then be specified by one or more
-I<option-value> pairs.
-
-After the display item is created, they can then be configured or
-destroyed using the methods provided by the host widget. For example,
-the HList widget has the methods B<itemConfigure>, B<itemCget>
-and B<itemDelete> for accessing the display items.
-
-=head1 CREATING AND MANIPULATING ITEM STYLES
-
-Item styles are created with B<ItemStyle>:
-
-=head1 SYNOPSIS
-
-S< >I<$widget>-E<gt>B<ItemStyle>(I<itemType> ?,B<-stylename>=E<gt>I<name>? ?,B<-refwindow>=E<gt>I<pathName>? ?,I<option>=E<gt>I<value>, ...>?);
-
-I<itemType> must be one of the existing display items types such as
-B<text>, B<imagetext>, B<window> or any new types added by
-the user. Additional arguments can be given in one or more
-I<option-value> pairs. I<option> can be any of the valid option
-for this display style or any of the following:
-
-=over 4
-
-=item B<-stylename> =E<gt> I<name>
-
-Specifies a name for this style. If unspecified, then a default name
-will be chosen for this style.
-
-=item B<-refwindow> =E<gt> I<$otherwidget>
-
-Specifies a window to use for determine the default values of the
-display type. If unspecified, the I<$widget> will be used. Default
-values for the display types can be set via the options database. The
-following example sets the B<-disablebackground> and
-B<-disabledforeground> options of a B<text> display style via
-the option database:
-
- $widget->optionAdd('*table.list*disabledForeground' => 'blue');
- $widget->optionAdd('*table.list*disabledBackground' => 'darkgray');
- $widget->ItemStyle('text', -refwindow => $table_list, -fg => 'red');
-
-By using the option database to set the options of the display styles,
-we can advoid hard-coding the option values and give the user more
-flexibility in customization. See L<Tk::option> for a detailed description
-of the option database.
-
-=back
-
-=head1 STYLE METHODS
-
-The B<ItemStyle> method creates an object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-
-The following additional methods are available for item styles:
-
-=over 4
-
-=item I<$style>-E<gt>B<delete>
-
-Destroy this display style object.
-
-=back
-
-=head1 EXAMPLE
-
-The following example creates two columns of data in a HList
-widget. The first column is in red and the second column in blue. The
-colors of the columns are controlled by two different B<text>
-styles. Also, the anchor and font of the second column is chosen so
-that the income data is aligned properly.
-
- use strict;
- use Tk;
- use Tk::HList;
- use Tk::ItemStyle;
-
- my $mw = MainWindow->new();
-
- my $hlist = $mw->HList(-columns=>2)->pack;
-
- my $red = $hlist->ItemStyle('text', -foreground=>'#800000');
- my $blue = $hlist->ItemStyle('text', -foreground=>'#000080', -anchor=>'e');
-
- my $e;
- foreach ([Joe => '$10,000'], [Peter => '$20,000'],
- [Raj => '$90,000'], [Zinh => '$0']) {
- $e = $hlist->addchild("");
- $hlist->itemCreate($e, 0, -itemtype=>'text',
- -text=>$_->[0], -style=>$red );
- $hlist->itemCreate($e, 1, -itemtype=>'text',
- -text=>$_->[1], -style=>$blue);
- }
-
- Tk::MainLoop;
-
-=head1 SEE ALSO
-
-L<Tk::HList|Tk::HList>
-L<Tk::TixGrid|Tk::TixGrid>
-L<Tk::TList|Tk::TList>
-
-=head1 KEYWORDS
-
-display item, display style, item style
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Derived.pod b/Master/tlpkg/tlperl/lib/Tk/Derived.pod
deleted file mode 100644
index 4b99934d5bd..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Derived.pod
+++ /dev/null
@@ -1,89 +0,0 @@
-
-=head1 NAME
-
-Tk::Derived - Base class for widgets derived from others
-
-=for pm Tk/Derived.pm
-
-=for category Derived Widgets
-
-=head1 SYNOPSIS
-
- package Tk::MyNewWidget;
-
- use Tk::widgets qw/ BaseWidget, list of Tk widgets /;
- use base qw/ Tk::Derived Tk::BaseWidget /;
-
- Construct Tk::Widget 'MyNewWidget';
-
- sub ClassInit {
- my( $class, $mw ) = @_;
- #... e.g., class bindings here ...
- $class->SUPER::ClassInit( $mw );
- }
-
- sub Populate {
- my( $self, $args ) = @_;
-
- my $flag = delete $args->{-flag};
- if( defined $flag ) {
- # handle -flag => xxx which can only be done at create
- # time the delete above ensures that new() does not try
- # and do $self->configure( -flag => xxx );
- }
-
- $self->SUPER::Populate( $args );
-
- $self = $self->Component( ... );
-
- $self->Delegates( ... );
-
- $self->ConfigSpecs(
- '-cursor' => [ SELF, 'cursor', 'Cursor', undef ],
- '-something' => [ METHOD, dbName, dbClass, default ],
- '-text' => [ $label, dbName, dbClass, default ],
- '-heading' => [ {-text => $head},
- heading, Heading, 'My Heading' ],
- );
- }
-
- sub something {
- my( $self, $value) = @_;
- if ( @_ > 1 ) {
- # set it
- }
- return # current value
- }
-
-=head1 DESCRIPTION
-
-Tk::Derived is used with Perl's multiple inheritance to override some
-methods normally inherited from Tk::Widget.
-
-Tk::Derived should precede any Tk widgets in the class's base class
-definition.
-
-Tk::Derived's main purpose is to apply wrappers to C<configure> and C<cget>
-methods of widgets to allow the derived widget to add to or modify behaviour
-of the configure options supported by the base widget.
-
-The derived class should normally override the C<Populate> method provided
-by Tk::Derived and call C<ConfigSpecs> to declare configure options.
-
-The public methods provided by Tk::Derived are as follows:
-
-=over 4
-
-=item -E<gt>ConfigSpecs(-I<key> =E<gt> [I<kind>, I<name>, I<Class>, I<default>], ...)
-
-=back
-
-=head1 SEE ALSO
-
-L<Tk::ConfigSpecs|Tk::ConfigSpecs>
-L<Tk::mega|Tk::mega>
-L<Tk::composite|Tk::composite>
-
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Dialog.pod b/Master/tlpkg/tlperl/lib/Tk/Dialog.pod
deleted file mode 100644
index 871206d504c..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Dialog.pod
+++ /dev/null
@@ -1,107 +0,0 @@
-# Copyright (c) 1992 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Dialog - Create modal dialog and wait for a response.
-
-=for pm Tk/Dialog.pm
-
-=for category Popups and Dialogs
-
-=head1 SYNOPSIS
-
-S< >I<$dialog> = I<$parent>-E<gt>B<Dialog>(I<-option> =E<gt> I<value>, ... );
-
-=head1 DESCRIPTION
-
-This procedure is part of the Tk script library - its arguments
-describe a dialog box. After creating a dialog box, B<Dialog> waits
-for the user to select one of the Buttons either by clicking on the
-Button with the mouse or by typing return to invoke the default Button
-(if any). Then it returns the text string of the selected Button.
-
-While waiting for the user to respond, B<Dialog> sets a local
-grab. This prevents the user from interacting with the application
-in any way except to invoke the dialog box. See the B<Show()> method.
-
-=head1 OPTIONS
-
-The following option/value pairs are supported:
-
-=over 4
-
-=item B<-title>
-
-Text to appear in the window manager's title bar for the dialog.
-
-=item B<-text>
-
-Message to appear in the top portion of the Dialog.
-
-=item B<-bitmap>
-
-If non-empty, specifies a bitmap to display in the top portion of the
-Dialog, to the left of the text. If this is an empty string then no
-bitmap is displayed in the Dialog.
-
-=item B<-default_button>
-
-Text label string of the Button that displays the default ring.
-
-=item B<-buttons>
-
-A reference to a list of Button label strings. Each I<string>
-specifies text to display in a Button, in order from left to right.
-
-=back
-
-=head1 METHODS
-
-=over 4
-
-=item I<$answer> = $dialog-E<gt>B<Show(>?-global?B<)>;
-
-This method displays the Dialog, waits for the user's response, and stores
-the text string of the selected Button in I<$answer>. If I<-global> is
-specified a global (rather than local) grab is performed.
-
-The actual Dialog is shown using the B<Popup> method. Any other
-options supplied to B<Show> are passed to B<Popup>, and can be used to
-position the Dialog on the screen. Please read Tk::Popup for details.
-
-=back
-
-=head1 ADVERTISED WIDGETS
-
-Because Tk::Dialog is a subclass of Tk::DialogBox it inherits all the
-advertised subwidgets of its superclass: e.g. "B_button-text", where
-'button-text' is a Button's -text value. Additionally, Tk::Dialog
-advertises:
-
-=over 4
-
-=item B<message>
-
-The dialog's Label widget containing the message text.
-
-=item B<bitmap>
-
-The dialog's Label widget containing the bitmap image.
-
-=back
-
-=head1 EXAMPLE
-
-I<$dialog> = I<$mw>-E<gt>B<Dialog>(-text =E<gt> 'Save File?', -bitmap =E<gt> 'question', -title =E<gt> 'Save File Dialog', -default_button =E<gt> 'Yes', -buttons =E<gt> [qw/Yes No Cancel/);
-
-=head1 KEYWORDS
-
-bitmap, dialog, modal, messageBox
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/DialogBox.pod b/Master/tlpkg/tlperl/lib/Tk/DialogBox.pod
deleted file mode 100644
index a091cd98427..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/DialogBox.pod
+++ /dev/null
@@ -1,156 +0,0 @@
-
-=head1 NAME
-
-Tk::DialogBox - create and manipulate a dialog screen.
-
-=for pm Tixish/DialogBox.pm
-
-=for category Tix Extensions
-
-=head1 SYNOPSIS
-
- use Tk::DialogBox
- ...
- $d = $top->DialogBox(-title => "Title", -buttons => ["OK", "Cancel"]);
- $w = $d->add(Widget, args)->pack;
- ...
- $button = $d->Show;
-
-=head1 DESCRIPTION
-
-B<DialogBox> is very similar to B<Dialog> except that it allows
-any widget in the top Frame. B<DialogBox> creates two
-Frames, I<top> and I<bottom>. The bottom Frame shows all the
-specified Buttons, lined up from left to right. The top Frame acts
-as a container for all other widgets that can be added with the
-B<add()> method.
-
-=head1 OPTIONS
-
-The options recognized by B<DialogBox> are as follows:
-
-=over 4
-
-=item B<-title>
-
-Specify the title of the DialogBox. If this is not set, then the
-name of the program is used.
-
-=item B<-buttons>
-
-The button names to display in the bottom Frame. This is a reference
-to an array of strings containing the text to put on each
-Button. There is no default value for this. If you do not specify any
-button names, no Buttons are displayed.
-
-=item B<-default_button>
-
-Specifies the default Button that is considered invoked when user
-presses <Return> on the DialogBox. This Button is highlighted. If
-no default Button is specified, then the first element of the
-array whose reference is passed to the B<-buttons> option is used
-as the default.
-
-=item B<-cancel_button>
-
-Specifies the Button that is considered invoked when the user closes
-the DialogBox using the window manager's close button. If the
-B<-cancel_button> option is not given, and if there's only one button
-configured, then this button is also used as the cancel button.
-Otherwise no button is considered as the cancel button; in such a case
-B<Show> just returns C<undef> when the user closes the DialogBox.
-
-=item B<-command>
-
-A callback which is executed after invoking an action to close the
-DialogBox, but before restoring focus and grab information. The
-selected button is passed as the first argument.
-
-=item B<-focus>
-
-Specify the widget to receive the initial focus after popping up the
-DialogBox. By default the B<-default_button> widget receives the
-initial focus.
-
-=item B<-showcommand>
-
-A callback which is executed before displaying the DialogBox and
-waiting for user input. The DialogBox itself is passed as the first
-argument.
-
-=back
-
-=head1 METHODS
-
-B<DialogBox> supports only two methods as of now:
-
-=over 4
-
-=item B<add(>I<widget>, I<options>B<)>
-
-Add the widget indicated by I<widget>. I<Widget> can be the name
-of any Tk widget (standard or contributed). I<options> are the
-options that the widget accepts. The widget is advertized as a
-subwidget of B<DialogBox>. The name of I<widget> is
-lower-cased and used as the advertised name. If multiple instances of
-I<widget> are created in the B<DialogBox>, then only the last one gets
-the advertised name. B<add()> does not automatically B<pack()> or
-B<grid()> I<widget> into the B<DialogBox>.
-
-=item B<Show(>I<?-global?>B<)>
-
-Displays the Dialog until the user invokes one of the Buttons in the
-bottom Frame. If the grab type I<-global> is specified, then B<Show>
-uses that grab; otherwise it defaults to a local grab. Returns the
-name of the Button invoked.
-
-The actual Dialog is shown using the B<Popup> method. Any other
-options supplied to B<Show> are passed to B<Popup>, and can be used to
-position the Dialog on the screen. Please read Tk::Popup for details.
-
-=item B<Exit()>
-
-Close the dialogbox, by emulating a click on the default button.
-
-=back
-
-=head1 ADVERTISED WIDGETS
-
-=over 4
-
-=item B<top>
-
-The subwidget reference to the top half of the DialogBox widget, the Frame
-containing widgets added by the B<add> method.
-
-=item B<bottom>
-
-The subwidget reference to the bottom half of the DialogBox widget, the Frame
-containing the Button widgets.
-
-=item B<B_"button-text">
-
-Individual subwidget references to the Buttons in the DialogBox widget. The
-subwidget name is the string I<B_> concatenated with the Button's -text
-value.
-
-=back
-
-=head1 BUGS
-
-There is no way of removing a widget once it has been added to the
-top Frame, unless you access the I<top> subwidget and go through the
-child widgets.
-
-There is no control over the appearance of the Buttons in the
-bottom Frame nor is there any way to control the placement of the
-two Frames with respect to each other.
-
-=head1 AUTHOR
-
-B<Rajappa Iyer> rsi@earthling.net
-
-This code is distributed under the same terms as Perl.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/DirTree.pod b/Master/tlpkg/tlperl/lib/Tk/DirTree.pod
deleted file mode 100644
index d8ded2f41b7..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/DirTree.pod
+++ /dev/null
@@ -1,172 +0,0 @@
-
-=head1 NAME
-
-Tk::DirTree - Create and manipulate DirTree widgets
-
-=for pm Tixish/DirTree.pm
-
-=for category Tix Extensions
-
-=head1 SYNOPSIS
-
-S< >B<use Tk::DirTree;>
-
-S< >I<$dirtree> = I<$parent>-E<gt>B<DirTree>(?I<options>?);
-
-=head1 SUPER-CLASS
-
-The B<DirTree> class is derived from the L<Tree|Tk::Tree> class and inherits
-all the methods, options and subwidgets of its super-class.
-
-=head1 STANDARD OPTIONS
-
-B<Tree> supports all the standard options of a Tree widget. See
-L<Tk::options> for details on the standard options.
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<browseCmd>
-
-=item Class: B<BrowseCmd>
-
-=item Switch: B<-browsecmd>
-
-Specifies a L<callback|Tk::callbacks> to call whenever the user browses on a directory
-(usually by single-clicking on the name of the directory). The callback
-is called with one argument, the complete pathname of the directory.
-
-=item Name: B<command>
-
-=item Class: B<Command>
-
-=item Switch: B<-command>
-
-Specifies the L<callback|Tk::callbacks> to be called when the user activates on a directory
-(usually by double-clicking on the name of the directory). The callback
-is called with one argument, the complete pathname of the directory.
-
-=item Name: B<dircmd>
-
-=item Class: B<DirCmd>
-
-=item Switch: B<-dircmd>
-
-Specifies the L<callback|Tk::callbacks> to be called when a directory listing is needed
-for a particular directory. If this option is not specified, by
-default the DirTree widget will attempt to read the directory as a
-Unix directory. On special occasions, the application programmer may
-want to supply a special method for reading directories: for example,
-when he needs to list remote directories. In this case, the B<-dircmd>
-option can be used. The specified callback accepts two arguments: the
-first is the name of the directory to be listed; the second is a
-Boolean value indicating whether hidden sub-directories should be
-listed. This callback returns a list of names of the sub-directories of
-this directory. For example:
-
- sub read_dir {
- my( $dir, $showhidden ) = @_;
- return( qw/DOS NORTON WINDOWS/ ) if $dir eq "C:\\";
- return();
- }
-
-=item Name: B<showHidden>
-
-=item Class: B<ShowHidden>
-
-=item Switch: B<-showhidden>
-
-Specifies whether hidden directories should be shown. By default, a
-directory name starting with a period "." is considered as a hidden
-directory. This rule can be overridden by supplying an alternative
-B<-dircmd> option.
-
-=item Name: B<directory>
-
-=item Class: B<Directory>
-
-=item Switch: B<-directory>
-
-=item Alias: B<-value>
-
-Specifies the name of the current directory to be displayed in the
-DirTree widget.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<DirTree> constructor method creates a new window (given by the $dirtree
-argument) and makes it into a DirTree widget. Additional options,
-described above, may be specified on the command line or in the
-option database to configure aspects of the DirTree such as its
-cursor and relief. The DirTree widget displays a list view of a
-directory, its previous directories and its sub-directories. The
-user can choose one of the directories displayed in the list or
-change to another directory.
-
-=head1 WIDGET METHODS
-
-The B<DirTree> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-The following additional methods are available for DirTree widgets:
-
-=over 4
-
-=item I<$dirtree>-E<gt>B<chdir>(I<dir>)
-
-Change the current directory to I<dir>.
-
-=back
-
-=head1 OTHER METHODS
-
-These methods have to be documented or made private:
-
-=over 4
-
-=item OpenCmd
-
-=item Populate
-
-=item add_to_tree
-
-=item dirnames
-
-=item fullpath
-
-=item has_subdir
-
-=item opencmd
-
-=item set_dir
-
-=back
-
-=head1 BINDINGS
-
-The mouse and keyboard bindings of the DirTree widget are the same as
-the bindings of the L<Tree|Tk::Tree> widget.
-
-=head1 KEYWORDS
-
-directory, tree, tix
-
-=head1 SEE ALSO
-
-L<Tk::Tree|Tk::Tree>
-L<Tk::HList|Tk::HList>
-
-=head1 AUTHOR
-
-Perl/TK version by Chris Dean <ctdean@cogit.com>. Original Tcl/Tix
-version by Ioi Kim Lam.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/DropSite.pod b/Master/tlpkg/tlperl/lib/Tk/DropSite.pod
deleted file mode 100644
index 8ae5a199fe3..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/DropSite.pod
+++ /dev/null
@@ -1,33 +0,0 @@
-=head1 NAME
-
-Tk::DropSite - Receive side of Drag & Drop abstraction
-
-=for category User Interaction
-
-=head1 SYNOPSIS
-
- use Tk::DropSite qw(...);
- $widget->DropSite(-entercommand => ...,
- -dropcommand => ...,
- -motioncommand => ...,
- -dropcommand => ...,
- );
-
-=head1 DESCRIPTION
-
-C<DropSite> creates an object which represents a site on which things
-may be "Dropped".
-
-A DropSite provides the following methods:
-
-=over 4
-
-=item $site->Enter($token,$event)
-
-=item $site->Leave($token,$event)
-
-=item $site->Motion($token,$event)
-
-=item $site->Drop($token,$event)
-
-=back
diff --git a/Master/tlpkg/tlperl/lib/Tk/Entry.pod b/Master/tlpkg/tlperl/lib/Tk/Entry.pod
deleted file mode 100644
index 1b6dbf15482..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Entry.pod
+++ /dev/null
@@ -1,693 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Entry - Create and manipulate Entry widgets
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
-S< >I<$entry> = I<$parent>-E<gt>B<Entry>(?I<options>?);
-
-=head1 STANDARD OPTIONS
-
-B<-background> B<-highlightbackground> B<-insertontime> B<-selectforeground>
-B<-borderwidth> B<-highlightcolor> B<-insertwidth> B<-takefocus>
-B<-cursor> B<-highlightthickness> B<-justify> B<-textvariable>
-B<-exportselection> B<-insertbackground> B<-relief> B<-xscrollcommand>
-B<-font> B<-insertborderwidth> B<-selectbackground>
-B<-foreground> B<-insertofftime> B<-selectborderwidth>
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Command-Line Name: B<-disabledbackground>
-
-=item Database Name: B<disabledBackground>
-
-=item Database Class: B<DisabledBackground>
-
-Specifies the background color to use when the entry is disabled. If
-this option is the empty string, the normal background color is used.
-
-=item Command-Line Name: B<-disabledforeground>
-
-=item Database Name: B<disabledForeground>
-
-=item Database Class: B<DisabledForeground>
-
-Specifies the foreground color to use when the entry is disabled. If
-this option is the empty string, the normal foreground color is used.
-
-=item Name: B<invalidCommand>
-
-=item Class: B<InvalidCommand>
-
-=item Switch: B<-invalidcommand>
-
-=item Alias: B<-invcmd>
-
-Specifies a script to eval when B<validateCommand> returns 0.
-Setting it to <undef> disables this feature (the default). The best use
-of this option is to set it to I<bell>. See B<Validation>
-below for more information.
-
-=item Command-Line Name: B<-readonlybackground>
-
-=item Database Name: B<readonlyBackground>
-
-=item Database Class: B<ReadonlyBackground>
-
-Specifies the background color to use when the entry is read-only. If
-this option is the empty string, the normal background color is used.
-
-=item Name: B<show>
-
-=item Class: B<Show>
-
-=item Switch: B<-show>
-
-If this option is specified, then the true contents of the entry
-are not displayed in the window.
-Instead, each character in the entry's value will be displayed as
-the first character in the value of this option, such as ``*''.
-This is useful, for example, if the entry is to be used to enter
-a password.
-If characters in the entry are selected and copied elsewhere, the
-information copied will be what is displayed, not the true contents
-of the entry.
-
-=item Name: B<state>
-
-=item Class: B<State>
-
-=item Switch: B<-state>
-
-Specifies one of three states for the entry: B<normal>, B<disabled>, or
-B<readonly>. If the entry is B<readonly>, then the value may not be changed
-using widget commands and no insertion cursor will be displayed, even
-if the input focus is in the widget; the contents of the widget may
-still be selected. If the entry is B<disabled>, the value may not be
-changed, no insertion cursor will be displayed, the contents will not
-be selectable, and the entry may be displayed in a different color,
-depending on the values of the B<-disabledforeground> and
-B<-disabledbackground> options.
-
-=item Name: B<validate>
-
-=item Class: B<Validate>
-
-=item Switch: B<-validate>
-
-Specifies the mode in which validation should operate: B<none>,
-B<focus>, B<focusin>, B<focusout>, B<key>, or B<all>.
-It defaults to B<none>. When you want validation, you must explicitly
-state which mode you wish to use. See B<Validation> below for more.
-
-=item Name: B<validateCommand>
-
-=item Class: B<ValidateCommand>
-
-=item Switch: B<-validatecommand>
-
-=item Alias: B<-vcmd>
-
-Specifies a script to eval when you want to validate the input into
-the entry widget. Setting it to C<undef> disables this feature (the default).
-This command must return a valid boolean value. If it returns 0 (or
-the valid boolean equivalent) then it means you reject the new edition
-and it will not occur and the B<invalidCommand> will be evaluated if it
-is set. If it returns 1, then the new edition occurs.
-See B<Validation> below for more information.
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-=item Switch: B<-width>
-
-Specifies an integer value indicating the desired width of the entry window,
-in average-size characters of the widget's font.
-If the value is less than or equal to zero, the widget picks a
-size just large enough to hold its current text.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Entry> method creates a new window (given by the
-$entry argument) and makes it into an entry widget.
-Additional options, described above, may be specified on the
-command line or in the option database
-to configure aspects of the entry such as its colors, font,
-and relief. The B<entry> command returns its
-$entry argument. At the time this command is invoked,
-there must not exist a window named $entry, but
-$entry's parent must exist.
-
-An entry is a widget that displays a one-line text string and
-allows that string to be edited using methods described below, which
-are typically bound to keystrokes and mouse actions.
-When first created, an entry's string is empty.
-A portion of the entry may be selected as described below.
-If an entry is exporting its selection (see the B<exportSelection>
-option), then it will observe the standard X11 protocols for handling the
-selection; entry selections are available as type B<STRING>.
-Entries also observe the standard Tk rules for dealing with the
-input focus. When an entry has the input focus it displays an
-I<insertion cursor> to indicate where new characters will be
-inserted.
-
-Entries are capable of displaying strings that are too long to
-fit entirely within the widget's window. In this case, only a
-portion of the string will be displayed; methods described below
-may be used to change the view in the window. Entries use
-the standard B<xScrollCommand> mechanism for interacting with
-scrollbars (see the description of the B<-xscrollcommand> option
-for details). They also support scanning, as described below.
-
-=head1 VALIDATION
-
-Validation of entry widgets is derived from part of the patch written by
-jhobbs@cs.uoregon.edu. This works by setting the B<validateCommand>
-option to a callback which will be evaluated according to the B<validate>
-option as follows:
-
-=over 4
-
-=item B<none>
-
-Default. This means no validation will occur.
-
-=item B<focus>
-
-B<validateCommand> will be called when the entry receives or
-loses focus.
-
-=item B<focusin>
-
-B<validateCommand> will be called when the entry receives focus.
-
-=item B<focusout>
-
-B<validateCommand> will be called when the entry loses focus.
-
-=item B<key>
-
-B<validateCommand> will be called when the entry is edited.
-
-=item B<all>
-
-B<validateCommand> will be called for all above conditions.
-
-=back
-
-The B<validateCommand> and B<invalidCommand> are called with the following
-arguments:
-
-=over 4
-
-=item * The proposed value of the entry. If you are configuring the
-entry widget to have a new textvariable, this will be the value of that
-textvariable.
-
-=item * The characters to be added (or deleted). This will be C<undef>
-if validation is due to focus, explcit call to validate or if change
-is due to C<-textvariable> changing.
-
-=item * The current value of entry i.e. before the proposed change.
-
-=item * index of char string to be added/deleted, if any. -1 otherwise
-
-=item * type of action. 1 == INSERT, 0 == DELETE,
--1 if it's a forced validation or textvariable validation
-
-=back
-
-In general, the B<textVariable> and B<validateCommand> can be
-dangerous to mix. If you try set the B<textVariable>
-to something that the B<validateCommand> will not accept it will
-be set back to the value of the entry widget.
-Using the B<textVariable> for read-only purposes will never cause problems.
-
-The B<validateCommand> will turn itself off by setting
-B<validate> to B<none> when an error occurs, for example
-when the B<validateCommand> or B<invalidCommand> encounters
-an error in its script while evaluating, or
-B<validateCommand> does not return a valid boolean value.
-
-With the perl/Tk version B<validate> option is supposed to be
-"suspended" while executing the B<validateCommand> or the B<invalidCommand>.
-This is experimental but in theory either callback can "correct" the
-value of the widget, and override the proposed change. (B<validateCommand>
-should still return false to inhibit the change from happening when
-it returns.)
-
-=head1 WIDGET METHODS
-
-The B<Entry> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-Many of the additional methods for entries take one or more indices as
-arguments. An index specifies a particular character in the entry's
-string, in any of the following ways:
-
-=over 4
-
-=item I<number>
-
-Specifies the character as a numerical index, where 0 corresponds
-to the first character in the string.
-
-=item B<anchor>
-
-Indicates the anchor point for the selection, which is set with the
-B<selectionFrom> and B<selectionAdjust> methods.
-
-=item B<end>
-
-Indicates the character just after the last one in the entry's string.
-This is equivalent to specifying a numerical index equal to the length
-of the entry's string.
-
-=item B<insert>
-
-Indicates the character adjacent to and immediately following the
-insertion cursor.
-
-=item B<sel.first>
-
-Indicates the first character in the selection. It is an error to
-use this form if the selection isn't in the entry window.
-
-=item B<sel.last>
-
-Indicates the character just after the last one in the selection.
-It is an error to use this form if the selection isn't in the
-entry window.
-
-=item B<@>I<number>
-
-In this form, I<number> is treated as an x-coordinate in the
-entry's window; the character spanning that x-coordinate is used.
-For example, ``B<@0>'' indicates the left-most character in the
-window.
-
-=back
-
-Abbreviations may be used for any of the forms above, e.g. ``B<e>''
-or ``B<sel.f>''. In general, out-of-range indices are automatically
-rounded to the nearest legal value.
-
-The following additional methods are available for entry widgets:
-
-=over 4
-
-=item I<$entry>-E<gt>B<bbox>(I<index>)
-
-Returns a list of four numbers describing the bounding box of the
-character given by I<index>.
-The first two elements of the list give the x and y coordinates of
-the upper-left corner of the screen area covered by the character
-(in pixels relative to the widget) and the last two elements give
-the width and height of the character, in pixels.
-The bounding box may refer to a region outside the visible area
-of the window.
-
-=item I<$entry>-E<gt>B<cget>(?I<option>?)
-
-Returns the current value of the configuration option given
-by I<option>.
-I<Option> may have any of the values accepted by the B<entry>
-command.
-
-=item I<$entry>-E<gt>B<configure>(?I<option>?, ?I<value, option, value, ...>?)
-
-Query or modify the configuration options of the widget.
-If no I<option> is specified, returns a list describing all of
-the available options for $entry (see L<Tk::configure> for
-information on the format of this list). If I<option> is specified
-with no I<value>, then the command returns a list describing the
-one named option (this list will be identical to the corresponding
-sublist of the value returned if no I<option> is specified). If
-one or more I<option-value> pairs are specified, then the command
-modifies the given widget option(s) to have the given value(s); in
-this case the command returns an empty string.
-I<Option> may have any of the values accepted by the B<entry>
-command.
-
-=item I<$entry>-E<gt>B<delete>(I<first, >?I<last>?)
-
-Delete one or more elements of the entry.
-I<First> is the index of the first character to delete, and
-I<last> is the index of the character just after the last
-one to delete.
-If I<last> isn't specified it defaults to I<first>+1,
-i.e. a single character is deleted.
-This method returns an empty string.
-
-=item I<$entry>-E<gt>B<get>
-
-Returns the entry's string.
-
-=item I<$entry>-E<gt>B<icursor>(I<index>)
-
-Arrange for the insertion cursor to be displayed just before the character
-given by I<index>. Returns an empty string.
-
-=item I<$entry>-E<gt>B<index>(I<index>)
-
-Returns the numerical index corresponding to I<index>.
-
-=item I<$entry>-E<gt>B<insert>(I<index, string>)
-
-Insert the characters of I<string> just before the character
-indicated by I<index>. Returns an empty string.
-
-=item I<$entry>->B<scan>(I<option, args>)
-
-=item I<$entry>->B<scan>I<Option>(I<args>)
-
-This method is used to implement scanning on entries. It has
-two forms, depending on I<Option>:
-
-=over 8
-
-=item I<$entry>->B<scanMark>(I<x>)
-
-Records I<x> and the current view in the entry widget; used in
-conjunction with later B<scanDragto> methods. Typically this
-method is associated with a mouse button press in the widget. It
-returns an empty string.
-
-=item I<$entry>->B<scanDragto>(I<x>)
-
-This method computes the difference between its I<x> argument
-and the I<x> argument to the last B<scanMark> method for
-the widget. It then adjusts the view left or right by 10 times the
-difference in x-coordinates. This method is typically associated
-with mouse motion events in the widget, to produce the effect of
-dragging the entry at high speed through the widget. The return
-value is an empty string.
-
-=back
-
-=item I<$entry>->B<selection>(I<option, arg>)
-
-=item I<$entry>->B<selection>I<Option>(I<arg>)
-
-This method is used to adjust the selection within an entry. It
-has several forms, depending on I<Option>:
-
-=over 8
-
-=item I<$entry>-E<gt>B<selectionAdjust>(I<index>)
-
-Locate the end of the selection nearest to the character given by
-I<index>, and adjust that end of the selection to be at I<index>
-(i.e including but not going beyond I<index>). The other
-end of the selection is made the anchor point for future
-B<selectionTo> methods. If the selection
-isn't currently in the entry, then a new selection is created to
-include the characters between I<index> and the most recent
-selection anchor point, inclusive.
-Returns an empty string.
-
-=item I<$entry>-E<gt>B<selectionClear>
-
-Clear the selection if it is currently in this widget. If the
-selection isn't in this widget then the method has no effect.
-Returns an empty string.
-
-=item I<$entry>-E<gt>B<selectionFrom>(I<index>)
-
-Set the selection anchor point to just before the character
-given by I<index>. Doesn't change the selection.
-Returns an empty string.
-
-=item I<$entry>-E<gt>B<selectionPresent>
-
-Returns 1 if there is are characters selected in the entry,
-0 if nothing is selected.
-
-=item I<$entry>-E<gt>B<selectionRange>(I<start, >I<end>)
-
-Sets the selection to include the characters starting with
-the one indexed by I<start> and ending with the one just
-before I<end>.
-If I<end> refers to the same character as I<start> or an
-earlier one, then the entry's selection is cleared.
-
-=item I<$entry>-E<gt>B<selectionTo>(I<index>)
-
-If I<index> is before the anchor point, set the selection
-to the characters from I<index> up to but not including
-the anchor point.
-If I<index> is the same as the anchor point, do nothing.
-If I<index> is after the anchor point, set the selection
-to the characters from the anchor point up to but not including
-I<index>.
-The anchor point is determined by the most recent B<selectionFrom>
-or B<selectionAdjust> method in this widget.
-If the selection isn't in this widget then a new selection is
-created using the most recent anchor point specified for the widget.
-Returns an empty string.
-
-=back
-
-=item I<$entry>-E<gt>B<validate>
-
-This command is used to force an evaluation of the B<validateCommand>
-independent of the conditions specified by the B<validate> option. It
-returns 0 or 1.
-
-=item I<$entry>-E<gt>B<xview>(I<args>)
-
-This command is used to query and change the horizontal position of the
-text in the widget's window. It can take any of the following
-forms:
-
-=over 8
-
-=item I<$entry>-E<gt>B<xview>
-
-Returns a list containing two elements.
-Each element is a real fraction between 0 and 1; together they describe
-the horizontal span that is visible in the window.
-For example, if the first element is .2 and the second element is .7,
-20% of the entry's text is off-screen to the left, the middle 50% is visible
-in the window, and 30% of the text is off-screen to the right.
-These are the same values passed to scrollbars via the B<-xscrollcommand>
-option.
-
-=item I<$entry>-E<gt>B<xview>(I<index>)
-
-Adjusts the view in the window so that the character given by I<index>
-is displayed at the left edge of the window.
-
-=item I<$entry>-E<gt>B<xviewMoveto>(I<fraction>)
-
-Adjusts the view in the window so that the character I<fraction> of the
-way through the text appears at the left edge of the window.
-I<Fraction> must be a fraction between 0 and 1.
-
-=item I<$entry>-E<gt>B<xviewScroll>(I<number, what>)
-
-This method shifts the view in the window left or right according to
-I<number> and I<what>.
-I<Number> must be an integer.
-I<What> must be either B<units> or B<pages> or an abbreviation
-of one of these.
-If I<what> is B<units>, the view adjusts left or right by
-I<number> average-width characters on the display; if it is
-B<pages> then the view adjusts by I<number> screenfuls.
-If I<number> is negative then characters farther to the left
-become visible; if it is positive then characters farther to the right
-become visible.
-
-=back
-
-=back
-
-=head1 DEFAULT BINDINGS
-
-Tk automatically creates class bindings for entries that give them
-the following default behavior.
-In the descriptions below, ``word'' refers to a contiguous group
-of letters, digits, or ``_'' characters, or any single character
-other than these.
-
-=over 4
-
-=item [1]
-
-Clicking mouse button 1 positions the insertion cursor
-just before the character underneath the mouse cursor, sets the
-input focus to this widget, and clears any selection in the widget.
-Dragging with mouse button 1 strokes out a selection between
-the insertion cursor and the character under the mouse.
-
-=item [2]
-
-Double-clicking with mouse button 1 selects the word under the mouse
-and positions the insertion cursor at the beginning of the word.
-Dragging after a double click will stroke out a selection consisting
-of whole words.
-
-=item [3]
-
-Triple-clicking with mouse button 1 selects all of the text in the
-entry and positions the insertion cursor before the first character.
-
-=item [4]
-
-The ends of the selection can be adjusted by dragging with mouse
-button 1 while the Shift key is down; this will adjust the end
-of the selection that was nearest to the mouse cursor when button
-1 was pressed.
-If the button is double-clicked before dragging then the selection
-will be adjusted in units of whole words.
-
-=item [5]
-
-Clicking mouse button 1 with the Control key down will position the
-insertion cursor in the entry without affecting the selection.
-
-=item [6]
-
-If any normal printing characters are typed in an entry, they are
-inserted at the point of the insertion cursor.
-
-=item [7]
-
-The view in the entry can be adjusted by dragging with mouse button 2.
-If mouse button 2 is clicked without moving the mouse, the selection
-is copied into the entry at the position of the mouse cursor.
-
-=item [8]
-
-If the mouse is dragged out of the entry on the left or right sides
-while button 1 is pressed, the entry will automatically scroll to
-make more text visible (if there is more text off-screen on the side
-where the mouse left the window).
-
-=item [9]
-
-The Left and Right keys move the insertion cursor one character to the
-left or right; they also clear any selection in the entry and set
-the selection anchor.
-If Left or Right is typed with the Shift key down, then the insertion
-cursor moves and the selection is extended to include the new character.
-Control-Left and Control-Right move the insertion cursor by words, and
-Control-Shift-Left and Control-Shift-Right move the insertion cursor
-by words and also extend the selection.
-Control-b and Control-f behave the same as Left and Right, respectively.
-Meta-b and Meta-f behave the same as Control-Left and Control-Right,
-respectively.
-
-=item [10]
-
-The Home key, or Control-a, will move the insertion cursor to the
-beginning of the entry and clear any selection in the entry.
-Shift-Home moves the insertion cursor to the beginning of the entry
-and also extends the selection to that point.
-
-=item [11]
-
-The End key, or Control-e, will move the insertion cursor to the
-end of the entry and clear any selection in the entry.
-Shift-End moves the cursor to the end and extends the selection
-to that point.
-
-=item [12]
-
-The Select key and Control-Space set the selection anchor to the position
-of the insertion cursor. They don't affect the current selection.
-Shift-Select and Control-Shift-Space adjust the selection to the
-current position of the insertion cursor, selecting from the anchor
-to the insertion cursor if there was not any selection previously.
-
-=item [13]
-
-Control-/ selects all the text in the entry.
-
-=item [14]
-
-Control-\ clears any selection in the entry.
-
-=item [15]
-
-The F16 key (labelled Copy on many Sun workstations) or Meta-w
-copies the selection in the widget to the clipboard, if there is a selection.
-
-=item [16]
-
-The F20 key (labelled Cut on many Sun workstations) or Control-w
-copies the selection in the widget to the clipboard and deletes
-the selection.
-If there is no selection in the widget then these keys have no effect.
-
-=item [17]
-
-The F18 key (labelled Paste on many Sun workstations) or Control-y
-inserts the contents of the clipboard at the position of the
-insertion cursor.
-
-=item [18]
-
-The Delete key deletes the selection, if there is one in the entry.
-If there is no selection, it deletes the character to the right of
-the insertion cursor.
-
-=item [19]
-
-The BackSpace key and Control-h delete the selection, if there is one
-in the entry.
-If there is no selection, it deletes the character to the left of
-the insertion cursor.
-
-=item [20]
-
-Control-d deletes the character to the right of the insertion cursor.
-
-=item [21]
-
-Meta-d deletes the word to the right of the insertion cursor.
-
-=item [22]
-
-Control-k deletes all the characters to the right of the insertion
-cursor.
-
-=item [23]
-
-Control-t reverses the order of the two characters to the right of
-the insertion cursor.
-
-If the entry is disabled using the B<-state> option, then the entry's
-view can still be adjusted and text in the entry can still be selected,
-but no insertion cursor will be displayed and no text modifications will
-take place.
-
-The behavior of entries can be changed by defining new bindings for
-individual widgets or by redefining the class bindings.
-
-=back
-
-=head1 KEYWORDS
-
-entry, widget
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Error.pod b/Master/tlpkg/tlperl/lib/Tk/Error.pod
deleted file mode 100644
index 9c38f0b7d74..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Error.pod
+++ /dev/null
@@ -1,145 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Error - Method invoked to process background errors
-
-=for category Binding Events and Callbacks
-
-=head1 SYNOPSIS
-
-Customization:
-
- require Tk::ErrorDialog;
-
-or
-
- sub Tk::Error
- {
- my ($widget,$error,@locations) = @_;
- ...
-
- }
-
-=head1 DESCRIPTION
-
-The B<Tk::Error> method is invoked by perl/Tk when a background
-error occurs. Two possible implementations are provided in the
-distribution and individual applications or users can (re)define a B<Tk::Error>
-method (e.g. as a perl sub) if they wish to handle background
-errors in some other manner.
-
-A background error is one that occurs in a command that didn't
-originate with the application. For example, if an error occurs
-while executing a L<callback|Tk::callbacks> specified with a
-L<bind|Tk::bind> or a L<after|Tk::after>
-command, then it is a background error. For a non-background error,
-the error can simply be returned up through nested subroutines
-until it reaches the top-level code in the application;
-then the application can report the error in whatever way it
-wishes. When a background error occurs, the unwinding ends in
-the Tk library and there is no obvious way for Tk to report
-the error.
-
-When Tk detects a background error, it saves information about the
-error and invokes the B<Tk::Error> method later when Tk is idle.
-
-B<Tk::Error> is invoked by perl/Tk as if by the perl code:
-
-S< >I<$mainwindow>-E<gt>B<Tk::Error>(I<"error message">, I<location ...>);
-
-I<$mainwindow> is the B<MainWindow> associated with widget which
-detected the error, I<"error message"> is a string describing the error
-that has been detected, I<location> is a list of one or more "locations"
-which describe the call sequence at the point the error was detected.
-
-The locations are a typically a mixture of perl location reports giving
-script name and line number, and simple strings describing locations in
-core Tk or perl/Tk C code.
-
-Tk will ignore any result returned by the B<Tk::Error> method.
-If another error occurs within the B<Tk::Error> method
-(for example if it calls B<die>) then Tk reports this error
-itself by writing a message to stderr (this is to avoid infinite loops
-due to any bugs in B<Tk::Error>).
-
-If several background errors accumulate before B<Tk::Error>
-is invoked to process them, B<Tk::Error> will be invoked once
-for each error, in the order they occurred.
-However, if B<Tk::Error> calls B<Tk-E<gt>break>, then
-any remaining errors are skipped without calling B<Tk::Error>.
-
-The B<Tk> module includes a default B<Tk::Error> subroutine
-that simply reports the error on stderr.
-
-=head1 Tk::ErrorDialog
-
-An alternate definition is provided via:
-
-S< >C<require Tk::ErrorDialog;>
-
-that posts a dialog box containing the error message and offers
-the user a chance to see a stack trace showing where the
-error occurred.
-
-This is an OO implementation of the Tcl/Tk command B<bgerror>, with a
-twist: since there is only one B<ErrorDialog> widget, you aren't required
-to invoke the constructor to create it; it will be created
-automatically when the first background error occurs. However, in
-order to configure the I<-cleanupcode> and I<-appendtraceback>
-B<ErrorDialog> options you must call the constructor and create it
-manually.
-
-The B<ErrorDialog> object essentially consists of two subwidgets: a
-B<Dialog> widget to display the background error and a B<Text> widget
-for the traceback information. If required, you can invoke various
-widget methods to customize these subwidgets - their advertised names
-are described below.
-
-S< >I<$mw>-E<gt>B<ErrorDialog>(-cleanupcode => I<code>, -appendtraceback => I<bool>);
-
-$mw is a window reference.
-
-I<code> is a CODE reference if special post-background error
-processing is required (default is undefined). The callback subroutine
-is called with @_ having the same arguments that B<Tk::Error> was
-invoked with.
-
-I<bool> is a boolean indicating whether or not to append successive
-tracebacks (default is 1, do append).
-
-=head2 Advertised ErrorDialog widgets
-
-I<error_dialog> is the Dialog widget reference.
-
-I<text> is the Text widget reference containing the traceback information.
-
-=head1 BUGS
-
-If B<after> or B<fileevent> are not invoked as methods of a widget
-then perl/Tk is unable to provide a I<$mainwindow> argument.
-To support such code from earlier versions of perl/Tk
-perl/Tk therefore calls B<Tk::Error> with string 'Tk' instead:
-B<Tk-E<gt>Tk::Error\(...\)>.
-In this case the B<Tk::Error> in B<Tk::ErrorDialog> and similar
-implementations cannot "popup" a window as they don't know which display
-to use. A mechanism to supply I<the> B<MainWindow> in applications
-which only have one (a very common case) should be provided.
-
-=head1 SEE ALSO
-
-L<Tk::bind|Tk::bind>
-L<Tk::after|Tk::after>
-L<Tk::fileevent|Tk::fileevent>
-
-=head1 KEYWORDS
-
-background error, reporting
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Eventloop.pod b/Master/tlpkg/tlperl/lib/Tk/Eventloop.pod
deleted file mode 100644
index a4c99e7988e..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Eventloop.pod
+++ /dev/null
@@ -1,62 +0,0 @@
-
-=head1 NAME
-
-Tk::Event - ToolKit for Events
-
-=for category Implementation
-
-=head1 SYNOPSIS
-
- use Tk::Event;
-
- Tk::Event->fileevent(\*FH, 'readable' => callback);
-
- Tk::Event->lineavail(\*FH, callback);
-
- use Tk::Event::Signal qw(INT);
-
- $SIG{'INT'} = callback;
-
- use Tk::Event::process;
-
- Tk::Event->proc($pid, callback);
-
- QueueEvent(callback [, position])
-
-
-=head1 DESCRIPTION
-
-
-That is better than nothing but still hard to use. Most scripts want higher
-level result (a line, a "block" of data etc.)
-
-So it has occured to me that we could use new-ish TIEHANDLE thus:
-
- my $obj = tie SOMEHANDLE,Tk::Event::IO;
-
- while (<SOMEHANDLE>)
- {
- }
-
-Then the READLINE routine registers a callback and looks something like:
-
- sub READLINE
- {
- my $obj = shift;
- Event->io(*$obj,'readable',sub { sysread(*$obj,${*$obj},1,length(${*$obj}) });
- my $pos;
- while (($pos = index(${*$obj},$/) < 0)
- {
- DoOneEvent();
- }
- Event->io(*$obj,'readable',''); # unregister
- $pos += length($/);
- my $result = substr(${*$obj},0,$pos);
- substr(${*$obj},0,$pos) = '';
- return $result;
- }
-
-This is using the scalar part of the glob representing the _inner_ IO
-as a buffer in which to accumulate chars.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Tk/FBox.pod b/Master/tlpkg/tlperl/lib/Tk/FBox.pod
deleted file mode 100644
index dada482a761..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/FBox.pod
+++ /dev/null
@@ -1,67 +0,0 @@
-=head1 NAME
-
-Tk::FBox - a file dialog
-
-=for pm Tk/FBox.pm
-
-=for category Popups and Dialogs
-
-=head1 SYNOPSIS
-
- use Tk::FBox;
- $file = $mw->FBox(...)->Show;
-
-=head1 DESCRIPTION
-
-C<Tk::FBox> is the dialog implementation behind the C<getOpenFile>,
-C<getSaveFile>, and C<chooseDirectory> method calls in the Unix/X11
-world. As such, it supports all options for these methods and
-additionally:
-
-=over
-
-=item -sortcmd => sub { $_[0] cmp $_[1] }
-
-Specified a callback for changing the sorting of the icons in the
-C<IconList> widget. By default, perl's C<cmp> operator will be used.
-
-From the source code:
-
- # Using -sortcmd is really strange :-(
- # $top->getOpenFile(-sortcmd => sub { package Tk::FBox; uc $b cmp uc $a});
- # or, un-perlish, but useable (now activated in code):
- # $top->getOpenFile(-sortcmd => sub { uc $_[1] cmp uc $_[0]});
-
-This is an experimental option!
-
-=item -type => $type
-
-Type should be "open" for choosing existing files to open (default),
-"save" for choosing existing or non-existing files to save, or "dir"
-for choosing directories.
-
-=item -filter => $glob
-
-A file glob to restrict displayed files. This is only active if no
-B<-filetypes> are defined.
-
-=item -force => $bool
-
-If true, then there will be no dialog if a file already exists.
-
-=back
-
-=head1 COPYRIGHT
-
-The original tkfbox.tcl from Tcl/Tk is:
-
-Copyright (c) 1994-1996 Sun Microsystems, Inc.
-
-See the file "license.terms" for information on usage and redistribution
-of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-
-Translated to Perl/Tk by Slaven Rezic <srezic@cpan.org>.
-
-=head1 SEE ALSO
-
-L<Tk::getOpenFile>, L<Tk::IconList>.
diff --git a/Master/tlpkg/tlperl/lib/Tk/FileSelect.pod b/Master/tlpkg/tlperl/lib/Tk/FileSelect.pod
deleted file mode 100644
index 2ea633de674..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/FileSelect.pod
+++ /dev/null
@@ -1,150 +0,0 @@
-
-=head1 NAME
-
-Tk::FileSelect - a widget for choosing files
-
-=for pm Tk/FileSelect.pm
-
-=for category Popups and Dialogs
-
-=head1 SYNOPSIS
-
- use Tk::FileSelect;
-
- $FSref = $top->FileSelect(-directory => $start_dir);
- $top - a window reference, e.g. MainWindow->new
- $start_dir - the starting point for the FileSelect
- $file = $FSref->Show;
- Executes the fileselector until either a filename is
- accepted or the user hits Cancel. Returns the filename
- or the empty string, respectively, and unmaps the
- FileSelect.
- $FSref->configure(option => value[, ...])
- Please see the Populate subroutine as the configuration
- list changes rapidly.
-
-=head1 DESCRIPTION
-
-This Module pops up a Fileselector box, with a directory entry on
-top, a list of directories in the current directory, a list of
-files in the current directory, an entry for entering/modifying a
-file name, an accept button and a cancel button.
-
-You can enter a starting directory in the directory entry. After
-hitting Return, the listboxes get updated. Double clicking on any
-directory shows you the respective contents. Single clicking on a
-file brings it into the file entry for further consideration,
-double clocking on a file pops down the file selector and calls
-the optional command with the complete path for the selected file.
-Hitting return in the file selector box or pressing the accept
-button will also work. *NOTE* the file selector box will only then
-get destroyed if the file name is not zero length. If you want
-yourself take care of it, change the if(length(.. in sub
-accept_file.
-
-=head1 AUTHORS
-
-Based on original FileSelect by
-Klaus Lichtenwalder, Lichtenwalder@ACM.org, Datapat GmbH, Munich,
-April 22, 1995 adapted by
-Frederick L. Wagner, derf@ti.com, Texas Instruments Incorporated, Dallas,
-21Jun95
-
-=head1 HISTORY
-
-=head2 950621 -- The following changes were made:
-
-=over 4
-
-=item *
-
-Rewrote Tk stuff to take advantage of new Compound widget module, so
-FileSelect is now composed of 2 LabEntry and 2 ScrlListbox2
-subwidgets.
-
-=item *
-
-Moved entry labels (from to the left of) to above the entry fields.
-
-=item *
-
-Caller is now able to control these aspects of widget, in both
-FileSelect (new) and configure :
-
-(Please see subroutine Populate for details, as these options
-change rapidly!)
-
-=item *
-
-I changed from Double-Button-1 to Button-1 in the Files listbox,
-to work with multiple mode in addition to browse mode. I also
-made some name changes (LastPath --> saved_path, ...).
-
-=item *
-
-The show method is not yet updated.
-
-=item *
-
-The topLevel stuff is not done yet. I took it out while I toy with
-the idea of FileSelect as a subwidget. Then the 'normal' topLevel
-thing with Buttons along the bottom could be build on top of it.
-
-=item *
-
-By request of Henry Katz <katz@fs09.webo.dg.com>, I added the functionality
-of using the Directory entry as a filter. So, if you want to only see the
-*.c files, you add a .c (the *'s already there :) and hit return.
-
-=back
-
-=head2 95/10/17, SOL, LUCC. lusol@Lehigh.EDU
-
-=over 4
-
-=item *
-
- Allow either file or directory names to be accepted.
-
-=item *
-
-Require double click to move into a new directory rather than a single
-click. This allows a single click to select a directory name so it can
-be accepted.
-
-=item *
-
-Add -verify list option so that standard Perl file test operators (like
--d and -x) can be specified for further name validation. The default
-value is the special value '!-d' (not a directory), so any name can be
-selected as long as it's not a directory - after all, this IS FileSelect!
-
-For example:
-
- $fs->configure(-verify => ['-d', [\&verify_code, $P1, $P2, ... $Pn]]);
-
-ensures that the selected name is a directory. Further, if an element of
-the list is an array reference, the first element is a code reference to a
-subroutine and the remaining optional elements are it's parameters. The
-subroutine is called like this:
-
- &verify_code($cd, $leaf, $P1, $P2, ... $Pn);
-
-where $cd is the current directory, $leaf is a directory or file name, and
-$P1 .. $Pn are your optional parameters. The subroutine should return TRUE
-if success or FALSE if failure.
-
-=back
-
-=head2 961008 -- derf@ti.com :
-
-By request of Jim Stern <js@world.northgrum.com> and Brad Vance
-<bvance@ti.com>, I updated the Accept and Show functions to support
-selection of multiple files. I also corrected a typo in the -verify code.
-
-=head1 SEE ALSO
-
-L<Tk::getOpenFile>, L<Tk::FBox>.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Font.pod b/Master/tlpkg/tlperl/lib/Tk/Font.pod
deleted file mode 100644
index 594efa58bca..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Font.pod
+++ /dev/null
@@ -1,407 +0,0 @@
-# Copyright (c) 1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-font - Create and inspect fonts.
-
-=for category Tk Generic Methods
-
-=head1 SYNOPSIS
-
-S< >I<$widget>->B<Font>(I<option>?, I<arg, arg, ...>?)
-
-S< >I<$font>->I<Option>?(I<arg, arg, ...>)?
-
-=head1 DESCRIPTION
-
-The B<Font> method provides several facilities for dealing with
-fonts, such as defining named fonts and inspecting the actual attributes of
-a font. The command has several different forms, determined by the
-first argument. The following forms are currently supported:
-
-=over 4
-
-=item I<$font>-E<gt>B<actual>(I<-option>?)
-
-=item I<$widget>-E<gt>B<fontActual>(I<font>?, I<-option>?)
-
-Returns information about the actual attributes that are obtained when
-I<font> is used on I<$font>'s display; the actual attributes obtained
-may differ from the attributes requested due to platform-dependant
-limitations, such as the availability of font families and pointsizes.
-I<font> is a font description; see L<"FONT DESCRIPTION"> below. If
-I<option> is specified, returns the value of that attribute; if it is
-omitted, the return value is a list of all the attributes and their values.
-See L<"FONT OPTIONS"> below for a list of the possible attributes.
-
-=item I<$font>-E<gt>B<configure>(I<-option>??=>I<value>, I<-option>=>I<value>, ...?)
-
-Query or modify the desired attributes for I<$font>.
-If no I<-option> is specified, returns a list describing
-all the options and their values for I<fontname>. If a single I<-option>
-is specified with no I<value>, then returns the current value of that
-attribute. If one or more I<option-value> pairs are specified,
-then the method modifies the given named font to have the given values; in
-this case, all widgets using that font will redisplay themselves using the
-new attributes for the font. See L<"FONT OPTIONS"> below for a list of the
-possible attributes.
-
-Note: the above behaviour differs in detail to B<configure> on widgets,
-images etc.
-
-=item I<$font> = I<$widget>-E<gt>B<Font>(I<-option>=>I<value>, ...>?)
-
-=item I<$font> = I<$widget>-E<gt>B<fontCreate>(?I<fontname>??, I<-option>=>I<value>, ...>?)
-
-Creates a new font object and returns a reference to it.
-I<fontname> specifies the name for the font; if it is omitted, then Tk generates
-a new name of the form B<font>I<x>, where I<x> is an integer. There may be any
-number of I<option-value> pairs, which provide the desired attributes for
-the new named font. See L<"FONT OPTIONS"> below for a list of the possible
-attributes.
-
-Note: the created font is I<not> shared between widgets of different
-L<MainWindow|Tk::MainWindow>s.
-
-=item I<$font>-E<gt>B<delete>
-
-=item I<$widget>-E<gt>B<fontDelete>(I<fontname>?, I<fontname>, ...?)
-
-Delete the specified named fonts. If there are widgets using the named font,
-the named font won't actually be deleted until all the instances are
-released. Those widgets will continue to display using the last known values
-for the named font. If a deleted named font is subsequently recreated with
-another call to B<fontCreate>, the widgets will use the new named font
-and redisplay themselves using the new attributes of that font.
-
-=item I<$widget>-E<gt>B<fontFamilies>
-
-The return value is a list of the case-insensitive names of all font families
-that exist on I<$widget>'s display.
-
-=item I<$font>-E<gt>B<measure>(I<text>)
-
-=item I<$widget>-E<gt>B<fontMeasure>(I<font>, I<text>)
-
-Measures the amount of space the string I<text> would use in the given
-I<font> when displayed in I<$widget>. I<font> is a font description;
-see L<"FONT DESCRIPTION"> below.
-The return value is the total width in pixels
-of I<text>, not including the extra pixels used by highly exagerrated
-characters such as cursive ``I<f>''. If the string contains newlines or tabs,
-those characters are not expanded or treated specially when measuring the
-string.
-
-=item I<$font>-E<gt>B<metrics>(I<-option>?)
-
-=item I<$widget>-E<gt>B<fontMetrics>(I<font>?, I<-option>?)
-
-Returns information about the metrics (the font-specific data), for
-I<font> when it is used on I<$widget>'s display. I<font> is a font
-description; see L<"FONT DESCRIPTION"> below.
-If I<option> is specified,
-returns the value of that metric; if it is omitted, the return value is a
-list of all the metrics and their values. See L<"FONT METRICS"> below for a list
-of the possible metrics.
-
-=item I<$widget>-E<gt>B<fontNames>
-
-The return value is a list of all font objects that are currently defined for
-I<$widget>'s MainWindow.
-
-=back
-
-=head1 FONT DESCRIPTION
-
-The following formats are accepted as a font description anywhere
-I<font> is specified as an argument above; these same forms are also
-permitted when specifying the B<-font> option for widgets.
-
-=over 4
-
-=item [1] I<fontname>
-
-The name of a named font, created using the B<fontCreate> method. When
-a widget uses a named font, it is guaranteed that this will never cause an
-error, as long as the named font exists, no matter what potentially invalid
-or meaningless set of attributes the named font has. If the named font
-cannot be displayed with exactly the specified attributes, some other close
-font will be substituted automatically.
-
-=item [1a] I<$font>
-
-A font object created using the B<Font> method. This is essentially the same
-as using a named font. The object is a reference to the name, and carries
-additional information e.g. which MainWindow it relates to in an manner peculiar
-to perl/Tk.
-
-=item [3] I<systemfont>
-
-The platform-specific name of a font, interpreted by the graphics server.
-This also includes, under X, an XLFD (see L<[4]|/[4]>) for which a single ``B<*>''
-character was used to elide more than one field in the middle of the
-name. See L<"PLATFORM-SPECIFIC ISSUES"> for a list of the system fonts.
-
-=item [3] [I<family>,?I<size>,??I<style>,??I<style ...>?]
-
-A properly formed list whose first element is the desired font
-I<family> and whose optional second element is the desired I<size>.
-The interpretation of the I<size> attribute follows the same rules
-described for L<-size|/-size> in L<"FONT OPTIONS"> below. Any additional optional
-arguments following the I<size> are font I<style>s. Possible values
-for the I<style> arguments are as follows:
-
- normal bold roman italic
- underline overstrike
-
-=item [4] X-font names (XLFD)
-
-A Unix-centric font name of the form
-I<-foundry-family-weight-slant-setwidth-addstyle-pixel-point-resx-resy-spacing-width-charset-encoding>.
-The ``B<*>'' character may be used to skip individual fields that the
-user does not care about. There must be exactly one ``B<*>'' for each
-field skipped, except that a ``B<*>'' at the end of the XLFD skips any
-remaining fields; the shortest valid XLFD is simply ``B<*>'', signifying
-all fields as defaults. Any fields that were skipped are given default
-values. For compatibility, an XLFD always chooses a font of the specified
-pixel size (not point size); although this interpretation is not strictly
-correct, all existing applications using XLFDs assumed that one ``point''
-was in fact one pixel and would display incorrectly (generally larger) if
-the correct size font were actually used.
-
-=item [5] I<option value >?I<option value ...>?
-
-A properly formed list of I<option-value> pairs that specify
-the desired attributes of the font, in the same format used when defining
-a named font; see L<"FONT OPTIONS"> below.
-
-=back
-
-When font description I<font> is used, the system attempts to parse the
-description according to each of the above five rules, in the order specified.
-Cases [1] and [2] must match the name of an existing named font or of a
-system font. Cases [3], [4], and [5] are accepted on all
-platforms and the closest available font will be used. In some situations
-it may not be possible to find any close font (e.g., the font family was
-a garbage value); in that case, some system-dependant default font is
-chosen. If the font description does not match any of the above patterns,
-an error is generated.
-
-=head1 FONT METRICS
-
-The following options are used by the B<metrics>/B<fontMetrics> method to query
-font-specific data determined when the font was created. These properties are
-for the whole font itself and not for individual characters drawn in that
-font. In the following definitions, the ``baseline'' of a font is the
-horizontal line where the bottom of most letters line up; certain letters,
-such as lower-case ``g'' stick below the baseline.
-
-=over 4
-
-=item B<-ascent>
-
-The amount in pixels that the tallest letter sticks up above the baseline of
-the font, plus any extra blank space added by the designer of the font.
-(I<$font>-E<gt>B<ascent> is provided for compatibility.)
-
-=item B<-descent>
-
-The largest amount in pixels that any letter sticks down below the baseline
-of the font, plus any extra blank space added by the designer of the font.
-(I<$font>-E<gt>B<descent> is provided for compatibility.)
-
-=item B<-linespace>
-
-Returns how far apart vertically in pixels two lines of text using the same
-font should be placed so that none of the characters in one line overlap any
-of the characters in the other line. This is generally the sum of the ascent
-above the baseline line plus the descent below the baseline.
-
-=item B<-fixed>
-
-Returns a boolean flag that is ``B<1>'' if this is a fixed-width font,
-where each normal character is the the same width as all the other
-characters, or is ``B<0>'' if this is a proportionally-spaced font, where
-individual characters have different widths. The widths of control
-characters, tab characters, and other non-printing characters are not
-included when calculating this value.
-
-=back
-
-=head1 FONT OPTIONS
-
-The following options are supported on all platforms, and are used when
-constructing a named font or when specifying a font using style [5] as
-above:
-
-=over 4
-
-=item B<-family> => I<name>
-
-The case-insensitive font family name. Tk guarantees to support the font
-families named B<Courier> (a monospaced ``typewriter'' font), B<Times>
-(a serifed ``newspaper'' font), and B<Helvetica> (a sans-serif
-``European'' font). The most closely matching native font family will
-automatically be substituted when one of the above font families is used.
-The I<name> may also be the name of a native, platform-specific font
-family; in that case it will work as desired on one platform but may not
-display correctly on other platforms. If the family is unspecified or
-unrecognized, a platform-specific default font will be chosen.
-
-=item B<-size> => I<size>
-
-The desired size of the font. If the I<size> argument is a positive
-number, it is interpreted as a size in points. If I<size> is a negative
-number, its absolute value is interpreted as a size in pixels. If a
-font cannot be displayed at the specified size, a nearby size will be
-chosen. If I<size> is unspecified or zero, a platform-dependent default
-size will be chosen.
-
-The original Tcl/Tk authors believe sizes should normally be specified in points
-so the application will remain the same ruler size on the screen, even when
-changing screen resolutions or moving scripts across platforms. While this is an
-admirable goal it does not work as well in practice as they hoped.
-The mapping between points and pixels is set when the application starts, based
-on alleged properties of the installed monitor, but it can be overridden by
-calling the L<scaling|Tk::Widget/scaling> command. However this can be
-problematic when system has no way of telling if (say) an 11" or 22" monitor is
-attached, also if it I<can> tell then some monitor sizes may result in poorer
-quality scaled fonts being used rather than a "tuned" bitmap font.
-In addition specifying pixels is useful in certain circumstances such as when a piece of text
-must line up with respect to a fixed-size bitmap.
-
-At present the Tcl/Tk scheme is used unchanged, with "point" size being returned
-by I<actual> (as an integer), and used internally. Suggestions for work-rounds
-to undesirable behaviour welcome.
-
-=item B<-weight> => I<weight>
-
-The nominal thickness of the characters in the font. The value
-B<normal> specifies a normal weight font, while B<bold> specifies a
-bold font. The closest available weight to the one specified will
-be chosen. The default weight is B<normal>.
-
-=item B<-slant> => I<slant>
-
-The amount the characters in the font are slanted away from the
-vertical. Valid values for slant are B<roman> and B<italic>.
-A roman font is the normal, upright appearance of a font, while
-an italic font is one that is tilted some number of degrees from upright.
-The closest available slant to the one specified will be chosen.
-The default slant is B<roman>.
-
-=item B<-underline> => I<boolean>
-
-The value is a boolean flag that specifies whether characters in this
-font should be underlined. The default value for underline is B<false>.
-
-=item B<-overstrike> => I<boolean>
-
-The value is a boolean flag that specifies whether a horizontal line should
-be drawn through the middle of characters in this font. The default value
-for overstrike is B<false>.
-
-=back
-
-=head1 PLATFORM-SPECIFIC ISSUES
-
-The following named system fonts are supported:
-
-=over 4
-
-=item X Windows:
-
-All valid X font names, including those listed by xlsfonts(1), are available.
-
-=item MS Windows:
-
- system ansi device
- systemfixed ansifixed oemfixed
-
-=item Macintosh:
-
- system application
-
-=back
-
-=head1 COMPATIBILITY WITH PREVIOUS VERSIONS
-
-In prior versions of perl/Tk the I<$widget>-E<gt>B<Font> method was a perl
-wrapper on the original "[4] X-font names (XLFD)" style as described above
-(which was the only form supported by versions of core tk prior to version
-tk8.0).
-This module is provided in its original form (it has just been renamed)
-via:
-
- use Tk::X11Font;
- I<$widget>-E<gt>B<X11Font>(...)
-
-However the methods of the old scheme have been mimiced as closely as possible
-with the new scheme. It is intended that code should work without modification,
-except for the case of using :
-
- @names = $font->Name;
-
-i.e. the I<Name> method in an array/list context. This now returns one element
-on all platforms (as it did on Win32), while previously on X systems it returned
-a list of fonts that matched an under-specified pattern.
-
-Briefly the methods supported for compatibilty are as follows:
-
-=over 4
-
-=item $newfont = I<$font>-E<gt>B<Clone>(I<-option>=>I<value>, ...>?)
-
-Returns a new font object I<$newfont> related to the original I<$font> by
-changing the values of the specified I<-option>s.
-
-=item I<$font>-E<gt>Family - maps to -family
-
-=item I<$font>-E<gt>Weight - maps to -weight
-
-=item I<$font>-E<gt>Slant - maps to -slant
-
-=item I<$font>-E<gt>Pixel and Point - map to -size
-
-=back
-
-New code should use I<$font>-E<gt>B<configure> to achieve same effect as last
-four items above.
-
-=over 4
-
-=item Foundry, Swidth, Adstyle, Xres, Yres, Space, Avgwidth, Registry, Encoding
-
-Are all ignored if set, and return '*' if queried.
-
-=item I<$font>-E<gt>B<Name>
-
-Returns the name of a named font, or a string representation of an unnamed
-font. Using I<$font> in a scalar context does the same. Note this is distinctly
-different from behaviour of L<X11Font's Name|Tk::X11Font/Name( [ $max ] )> in
-a list context.
-
-=item I<$font>-E<gt>B<Pattern>
-
-Returns a XLFD string for the font based on I<actual> values, and some heuristics
-to map Tk's forms to the "standard" X conventions.
-
-=back
-
-
-=head1 SEE ALSO
-
-L<Tk::options|Tk::options>
-
-L<Tk::X11Font|Tk::X11Font>
-
-=head1 KEYWORDS
-
-font
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Frame.pod b/Master/tlpkg/tlperl/lib/Tk/Frame.pod
deleted file mode 100644
index 6570b6a18c7..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Frame.pod
+++ /dev/null
@@ -1,146 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Frame - Create and manipulate Frame widgets
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
-S< >I<$frame> = I<$parent>-E<gt>B<Frame>(?I<options>?);
-
-=head1 STANDARD OPTIONS
-
-B<-borderwidth> B<-highlightbackground> B<-highlightthickness> B<-takefocus>
-B<-class> B<-highlightcolor> B<-relief>
-B<-cursor>
-
-See L<Tk::options> for details of the standard options.
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<background>
-
-=item Class: B<Background>
-
-=item Switch: B<-background>
-
-This option is the same as the standard B<background> option
-except that its value may also be specified as an undefined value.
-In this case, the widget will display no background or border, and
-no colors will be consumed from its colormap for its background
-and border.
-
-=item Name: B<colormap>
-
-=item Class: B<Colormap>
-
-=item Switch: B<-colormap>
-
-Specifies a colormap to use for the window.
-The value may be either B<new>, in which case a new colormap is
-created for the window and its children, or the name of another
-window (which must be on the same screen and have the same visual
-as $widget), in which case the new window will use the colormap
-from the specified window.
-If the B<colormap> option is not specified, the new window
-uses the same colormap as its parent.
-This option may not be changed with the B<configure>
-method.
-
-=item Name: B<container>
-
-=item Class: B<Container>
-
-=item Switch: B<-container>
-
-The value must be a boolean. If true, it means that this window will
-be used as a container in which some other application will be embedded
-(for example, a Tk toplevel can be embedded using the B<-use> option).
-The window will support the appropriate window manager protocols for
-things like geometry requests. The window should not have any
-children of its own in this application.
-This option may not be changed with the B<configure>
-method.
-
-=item Name: B<height>
-
-=item Class: B<Height>
-
-=item Switch: B<-height>
-
-Specifies the desired height for the window in any of the forms
-acceptable to B<Tk_GetPixels>.
-If this option is less than or equal to zero then the window will
-not request any size at all.
-
-=item Name: B<visual>
-
-=item Class: B<Visual>
-
-=item Switch: B<-visual>
-
-Specifies visual information for the new window in any of the
-forms accepted by B<Tk_GetVisual>.
-If this option is not specified, the new window will use the same
-visual as its parent.
-The B<visual> option may not be modified with the B<configure>
-method.
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-=item Switch: B<-width>
-
-Specifies the desired width for the window in any of the forms
-acceptable to B<Tk_GetPixels>.
-If this option is less than or equal to zero then the window will
-not request any size at all.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Frame> method creates a new window (given by the
-$widget argument) and makes it into a frame widget.
-Additional
-options, described above, may be specified on the command line
-or in the option database
-to configure aspects of the frame such as its background color
-and relief. The B<frame> command returns the
-path name of the new window.
-
-A frame is a simple widget. Its primary purpose is to act as a
-spacer or container for complex window layouts. The only features
-of a frame are its background color and an optional 3-D border to make the
-frame appear raised or sunken.
-
-=head1 WIDGET METHODS
-
-The B<Frame> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-=head1 BINDINGS
-
-When a new frame is created, it has no default event bindings:
-frames are not intended to be interactive.
-
-=head1 KEYWORDS
-
-frame, widget
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/HList.pod b/Master/tlpkg/tlperl/lib/Tk/HList.pod
deleted file mode 100644
index 0843e689843..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/HList.pod
+++ /dev/null
@@ -1,1050 +0,0 @@
-# Copyright (c) 1996, Expert Interface Technologies
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-# The file man.macros and some of the macros used by this file are
-# copyrighted: (c) 1990 The Regents of the University of California.
-# (c) 1994-1995 Sun Microsystems, Inc.
-# The license terms of the Tcl/Tk distribution are in the file
-# license.tcl.
-
-=head1 NAME
-
-Tk::HList - Create and manipulate Tix Hierarchial List widgets
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
-I<$hlist> = I<$parent>-E<gt>B<HList>(?I<options>?);
-
-=head1 STANDARD OPTIONS
-
-B<-background> B<-borderwidth> B<-cursor> B<-exportselection>
-B<-foreground> B<-font> B<-height> B<-highlightcolor>
-B<-highlightthickness> B<-relief> B<-selectbackground>
-B<-selectforeground> B<-xscrollcommand> B<-yscrollcommand>
-B<-width>
-
-See L<Tk::options> for details of the standard options.
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<browsecmd>
-
-=item Class: B<BrowseCmd>
-
-=item Switch: B<-browsecmd>
-
-Specifies a perl/Tk L<callback|Tk::callbacks> to be executed when the user browses through the
-entries in the HList widget.
-
-=item Name: B<columns>
-
-=item Class: B<Columns>
-
-=item Switch: B<-columns>
-
-Specifies the number of columns in this HList widget. This option can
-only be set during the creation of the HList widget and cannot be
-changed subsequently.
-
-=item Name: B<command>
-
-=item Class: B<Command>
-
-=item Switch: B<-command>
-
-Specifies the perl/Tk L<callback|Tk::callbacks> to be executed when the user invokes a list
-entry in the HList widget. Normally the user invokes a list
-entry by double-clicking it or pressing the Return key.
-
-=item Name: B<drawBranch>
-
-=item Class: B<DrawBranch>
-
-=item Switch: B<-drawbranch>
-
-A Boolean value to specify whether branch line should be drawn to
-connect list entries to their parents.
-
-=item Name: B<foreground>
-
-=item Class: B<Foreground>
-
-=item Switch: B<-foreground>
-
-=item Alias: B<-fg>
-
-B<[OBSOLETE]> Specifies the default foreground color for the list entries.
-
-=item Name: B<gap>
-
-=item Class: B<Gap>
-
-=item Switch: B<-gap>
-
-B<[OBSOLETE]> The default distance between the bitmap/image and the
-text in list entries.
-
-=item Name: B<header>
-
-=item Class: B<Header>
-
-=item Switch: B<-header>
-
-A Boolean value specifying whether headers should be displayed for
-this HList widget (see the B<header> method below).
-
-=item Name: B<height>
-
-=item Class: B<Height>
-
-=item Switch: B<-height>
-
-Specifies the desired height for the window in number of characters.
-
-=item Name: B<indent>
-
-=item Class: B<Indent>
-
-=item Switch: B<-indent>
-
-Specifies the amount of horizontal indentation between a list entry
-and its children. Must be a valid screen distance value.
-
-=item Name: B<indicator>
-
-=item Class: B<Indicator>
-
-=item Switch: B<-indicator>
-
-Specifies whether the indicators should be displayed inside the HList
-widget. See the B<indicator> method below.
-
-=item Name: B<indicatorCmd>
-
-=item Class: B<IndicatorCmd>
-
-=item Switch: B<-indicatorcmd>
-
-Specifies a perl/Tk L<callback|Tk::callbacks> to be executed when the user manipulates the
-indicator of an HList entry. The B<-indicatorcmd> is triggered
-when the user press or releases the mouse button over the indicator in
-an HList entry. By default the perl/Tk B<callback> specified by
-B<-indicatorcmd> is executed with two additional arguments, the
-entryPath of the entry whose indicator has been triggered and additional
-information about the event. The additional information is one of the
-following strings: B<E<lt>ArmE<gt>>, B<E<lt>DisarmE<gt>>,
-and B<E<lt>ActivateE<gt>>.
-
-=item Name: B<itemType>
-
-=item Class: B<ItemType>
-
-=item Switch: B<-itemtype>
-
-Specifies the default type of display item for this HList widget. When
-you call the B<itemCreate>, B<add> and B<addchild> methods, display
-items of this
-type will be created if the B<-itemtype> option is not specified .
-
-=item Name: B<padX>
-
-=item Class: B<Pad>
-
-=item Switch: B<-padx>
-
-B<[OBSOLETE]> The default horizontal padding for list entries.
-
-=item Name: B<padY>
-
-=item Class: B<Pad>
-
-=item Switch: B<-padx>
-
-B<[OBSOLETE]> The default vertical padding for list entries.
-
-=item Name: B<selectBackground>
-
-=item Class: B<SelectBackground>
-
-=item Switch: B<-selectbackground>
-
-Specifies the background color for the selected list entries.
-
-=item Name: B<selectBorderWidth>
-
-=item Class: B<BorderWidth>
-
-=item Switch: B<-selectborderwidth>
-
-Specifies a non-negative value indicating the width of the 3-D border
-to draw around selected items. The value may have any of the forms
-acceptable to B<Tk_GetPixels>.
-
-=item Name: B<selectForeground>
-
-=item Class: B<SelectForeground>
-
-=item Switch: B<-selectforeground>
-
-Specifies the foreground color for the selected list entries.
-
-=item Name: B<selectMode>
-
-=item Class: B<SelectMode>
-
-=item Switch: B<-selectmode>
-
-Specifies one of several styles for manipulating the selection. The
-value of the option may be arbitrary, but the default bindings expect
-it to be either B<single>, B<browse>, B<multiple>, or
-B<extended>; the default value is B<single>.
-
-=item Name: B<sizeCmd>
-
-=item Class: B<SizeCmd>
-
-=item Switch: B<-sizecmd>
-
-Specifies a perl/Tk L<callback|Tk::callbacks> to be called whenever the HList widget
-changes its size. This method can be useful to implement ``I<user scroll
-bars when needed>'' features.
-
-=item Name: B<separator>
-
-=item Class: B<Separator>
-
-=item Switch: B<-separator>
-
-Specifies the character to used as the separator character when
-intepreting the path-names of list entries. By default the character
-"." is used.
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-=item Switch: B<-width>
-
-Specifies the desired width for the window in characters.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<HList> method creates a new window (given by the
-$widget argument) and makes it into a HList widget.
-Additional options, described above, may be specified on the command
-line or in the option database to configure aspects of the
-HList widget such as its cursor and relief.
-
-The HList widget can be used to display any data that have a
-hierarchical structure, for example, file system directory trees. The
-list entries are indented and connected by branch lines according to
-their places in the hierachy.
-
-Each list entry is identified by an B<entryPath>. The entryPath is a
-sequence of B<entry names> separated by the separator charactor
-(specified by the B<-separator> option). An B<entry name> can be
-any string that does not contain the separator charactor, or it can be
-the a string that contains only one separator charactor.
-
-For example, when "." is used as the separator charactor,
-"one.two.three" is the entryPath for a list entry whose parent is
-"one.two", whose parent is "one", which is a toplevel entry (has no
-parents).
-
-Another examples: ".two.three" is the entryPath for a list entry whose
-parent is ".two", whose parent is ".", which is a toplevel entry.
-
-=head1 DISPLAY ITEMS
-
-Each list entry in an HList widget is associated with a B<display>
-item. The display item determines what visual information should
-be displayed for this list entry. Please see L<Tk::DItem>
-for a list of all display items.
-When a list entry is created by the B<itemCreate>, B<add> or
-B<addchild> widget
-methods, the type of its display item is determined by the
-B<-itemtype> option passed to these methods. If the
-B<-itemtype> is omitted, then by default the type specified by
-this HList widget's B<-itemtype> option is used.
-
-=head1 WIDGET METHODS
-
-The B<HList> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-The following additional methods are available HList widgets:
-
-=over 4
-
-=item I<$hlist>-E<gt>B<add>(I<$entryPath> ?,I<option>=E<gt>I<value>, ...?)
-
-Creates a new list entry with the pathname I<$entryPath>. A list
-entry must be created after its parent is created (unless this entry
-is a top-level entry, which has no parent). See also L<"BUGS"> below.
-This method returns the
-entryPath of the newly created list entry. The following
-configuration options can be given to configure the list entry:
-
-=over 8
-
-=item B<-at> =E<gt> I<position>
-
-Insert the new list at the position given by I<position>.
-I<position> must be a valid integer. The position B<0> indicates
-the first position, B<1> indicates the second position, and so on.
-
-=item B<-after> =E<gt> I<afterWhich>
-
-Insert the new list entry after the entry identified by
-I<afterWhich>. I<afterWhich> must be a valid list entry and it
-mush have the same parent as the new list entry
-
-=item B<-before> =E<gt> I<beforeWhich>
-
-Insert the new list entry before the entry identified by
-I<beforeWhich>. I<beforeWhich> must be a valid list entry and it
-mush have the same parent as the new list entry
-
-=item B<-data> =E<gt> I<string>
-
-Specifies a string to associate with this list entry. This string can
-be queried by the B<info> method. The application
-programmer can use the B<-data> option to associate the list entry
-with the data it represents.
-
-=item B<-itemtype> =E<gt> I<type>
-
-Specifies the type of display item to be display for the new list
-entry. B<type> must be a valid display item type. Currently the
-available display item types are B<imagetext>, B<text>, and
-$widget. If this option is not specified, then by default the
-type specified by this HList widget's B<-itemtype> option is used.
-
-=item B<-state> =E<gt> I<state>
-
-Specifies whether this entry can be selected or invoked by the user.
-Must be either B<normal> or B<disabled>.
-
-=back
-
-The B<add> method accepts additional configuration options
-to configure the display item associated with this list entry. The set
-of additional configuration options depends on the type of the display
-item given by the B<-itemtype> option. Please see
-L<Tk::DItem> for a list of the configuration options for
-each of the display item types.
-
-=item I<$hlist>-E<gt>B<addchild>(I<$parentPath, >?I<option, value, ..., >?)
-
-Adds a new child entry to the children list of the list entry
-identified by I<$parentPath>. Or, if I<$parentPath> is set to be
-the empty string, then creates a new toplevel entry. The name of the
-new list entry will be a unique name automatically generated by the
-HList widget. Usually if I<$parentPath> is B<foo>, then the
-entryPath of the new entry will be B<foo.0>, B<foo.1>, ... etc.
-This method returns the entryPath of the newly created list entry.
-I<option> can be any option for the B<add> method.
-See also L<"BUGS"> below.
-
-=item I<$hlist>-E<gt>B<anchorSet>(I<$entryPath>)
-
-Sets the anchor to the list entry identified by I<$entryPath>. The
-anchor is the end of the selection that is fixed while the user is
-dragging out a selection with the mouse.
-
-=item I<$hlist>-E<gt>B<anchorClear>
-
-Removes the anchor, if any, from this HList widget. This only
-removes the surrounding highlights of the anchor entry and does not
-affect its selection status.
-
-=item I<$hlist>-E<gt>B<columnWidth>(I<$col>?, I<-char>?, ?I<width>?)
-
-Querys or sets the width of a the column I<$col> in the HList
-widget. The value of I<$col> is zero-based: 0 stands for the first
-column, 1 stands for the second, and so on. If no further parameters
-are given, returns the current width of this column (in number of
-pixels). Additional parameters can be given to set the width of this
-column:
-
-=over 8
-
-=item I<$hlist>-E<gt>B<columnWidth>(I<$col>, B<''>)
-
-An empty string indicates that the width of the column should be just
-wide enough to display the widest element in this column. In this
-case, the width of this column may change as a result of the elements
-in this column changing their sizes.
-
-=item I<$hlist>-E<gt>B<columnWidth>(I<$col, >I<width>)
-
-I<width> must be in a form accepted by B<Tk_GetPixels>.
-
-=item I<$hlist>-E<gt>B<columnWidth>(I<$col, >B<-char, >I<nChars>)
-
-The width is set to be the average width occupied by I<nChars>
-number of characters of the font specified by the B<-font> option
-of this HList widget.
-
-=back
-
-=item I<$hlist>-E<gt>B<delete>(I<option>, I<$entryPath>)
-
-Delete one or more list entries. I<option> may be one of the
-following:
-
-=over 8
-
-=item B<all>
-
-Delete all entries in the HList. In this case the I<$entryPath>
-does not need to be specified.
-
-=item B<entry>
-
-Delete the entry specified by I<$entryPath> and all its offsprings,
-if any.
-
-=item B<offsprings>
-
-Delete all the offsprings, if any, of the entry specified by
-I<$entryPath>. However, I<$entryPath> itself is not deleted.
-
-=item B<siblings>
-
-Delete all the list entries that share the same parent with the entry
-specified by I<$entryPath>. However, I<$entryPath> itself is not
-deleted.
-
-=back
-
-=item I<$hlist>-E<gt>B<dragsiteSet>(I<$entryPath>)
-
-Sets the dragsite to the list entry identified by
-I<$entryPath>. The dragsite is used to indicate the source of a
-drag-and-drop action. Currently drag-and-drop functionality has not
-been implemented in Tix yet.
-
-=item I<$hlist>-E<gt>B<dragsiteClear>
-
-Remove the dragsite, if any, from the this HList widget. This only
-removes the surrounding highlights of the dragsite entry and does not
-affect its selection status.
-
-=item I<$hlist>-E<gt>B<dropsiteSet>(I<$entryPath>)
-
-Sets the dropsite to the list entry identified by I<$entryPath>. The
-dropsite is used to indicate the target of a drag-and-drop
-action. Currently drag-and-drop functionality has not been implemented
-in Tix yet.
-
-=item I<$hlist>-E<gt>B<dropsiteClear>
-
-Remove the dropsite, if any, from the this HList widget. This only
-removes the surrounding highlights of the dropsite entry and does not
-affect its selection status.
-
-=item I<$hlist>-E<gt>B<entrycget>(I<$entryPath>, I<option>)
-
-Returns the current value of the configuration option given by
-I<option> for the entry indentfied by I<$entryPath>. I<Option>
-may have any of the values accepted by the B<add> method.
-
-=item I<$hlist>-E<gt>B<entryconfigure>(I<$entryPath> ?,I<option>?, ?I<value>=E<gt>I<option>, ...?)
-
-Query or modify the configuration options of the list entry indentfied
-by I<$entryPath>. If no I<option> is specified, returns a list
-describing all of the available options for I<$entryPath> (see
-L<Tk::options> for information on the format of this list.) If
-I<option> is specified with no I<value>, then the method
-returns a list describing the one named option (this list will be
-identical to the corresponding sublist of the value returned if no
-I<option> is specified). If one or more I<option-value> pairs
-are specified, then the method modifies the given option(s) to have
-the given value(s); in this case the method returns an empty string.
-I<Option> may have any of the values accepted by the B<add> or
-B<addchild> method. The exact set of options depends on the
-value of the B<-itemtype> option passed to the the B<add> or
-B<addchild> method when this list entry is created.
-
-=item I<$hlist>-E<gt>B<header>(I<option>, I<$col> ?,I<args>, ...?)
-
-Manipulates the header items of this HList widget. If the
-B<-header> option of this HList widget is set to true, then a
-header item is displayed at the top of each column. The I<$col>
-argument for this method must be a valid integer. 0 indicates the
-first column, 1 the second column, ... and so on. This method
-supports the following options:
-
-=over 8
-
-=item I<$hlist>-E<gt>B<header>(B<cget>, I<$col>, I<option>)
-
-If the I<$col>-th column has a header display item, returns the
-value of the specified I<option> of the header item. If the header
-doesn't exist, returns an error.
-
-=item I<$hlist>-E<gt>B<header>(B<configure, >I<$col, >?I<option>?, I<?value, option, value, ...>?)
-
-Query or modify the configuration options of the header display item
-of the I<$col>-th column. The header item must exist, or an error
-will result. If no I<option> is specified, returns a list
-describing all of the available options for the header display item
-(see L<Tk::options> for information on the format of this
-list.) If I<option> is specified with no I<value>, then the
-method returns a list describing the one named option (this list will
-be identical to the corresponding sublist of the value returned if no
-I<option> is specified). If one or more I<option-value> pairs
-are specified, then the method modifies the given option(s) to have
-the given value(s); in this case the method returns an empty
-string. I<Option> may have any of the values accepted by the
-B<header create> method. The exact set of options depends
-on the value of the B<-itemtype> option passed to the the B<header>
-create method when this display item was created.
-
-=item I<$hlist>-E<gt>B<header>(B<create, >I<$col, >?I<-itemtype type>? ?I<option value ...>?
-
-Creates a new display item as the header for the I<$col>-th
-column. See also L<"BUGS"> below.
-If an header display item already exists for this column, it
-will be replaced by the new item. An optional parameter
-I<-itemtype> can be used to specify what type of display item
-should be created. If the I<-itemtype> is not given, then by
-default the type specified by this HList widget's B<-itemtype>
-option is used. Additional parameters, in I<option-value> pairs,
-can be passed to configure the appearance of the display item. Each
-I<option-value> pair must be a valid option for this type of
-display item or one of the following:
-
-=over 12
-
-=item B<-borderwidth> =E<gt> I<color>
-
-Specifies the border width of this header item.
-
-=item B<-headerbackground> =E<gt> I<color>
-
-Specifies the background color of this header item.
-
-=item B<-relief> =E<gt> I<type>
-
-Specifies the relief type of the border of this header item.
-
-=back
-
-=item I<$hlist>-E<gt>B<header>(B<delete, >I<$col>)
-
-Deletes the header display item for the I<$col>-th column.
-
-=item I<$hlist>-E<gt>B<header>(B<exists, >I<$col>)
-
-Return true if an header display item exists for the I<$col>-th
-column; return false otherwise.
-
-=item I<$hlist>-E<gt>B<header>(B<size>, I<$col>)
-
-If an header display item exists for the I<$col>-th column , returns
-its size in pixels in a two element list I<(width, height)>;
-returns an error if the header display item does not exist.
-
-=back
-
-=item I<$hlist>-E<gt>B<hide>(I<option> ?,I<$entryPath>?)
-
-Makes some of entries invisible without deleting them.
-I<Option> can be one of the following:
-
-=over 8
-
-=item B<entry>
-
-Hides the list entry identified by I<$entryPath>.
-
-=back
-
-Currently only the B<entry> option is supported. Other options will
-be added in the next release.
-
-=item I<$hlist>-E<gt>B<indicator>(I<option>, I<$entryPath>, ?I<args, ...>?)
-
-Manipulates the indicator on the list entries. An indicator is usually
-a small display item (such as an image) that is displayed to the left
-to an entry to indicate the status of the entry. For example, it may
-be used to indicate whether a directory is opened or
-closed. I<Option> can be one of the following:
-
-=over 8
-
-=item I<$hlist>-E<gt>B<indicator>(B<cget>, I<$entryPath>, I<option>)
-
-If the list entry given by I<$entryPath> has an indicator, returns
-the value of the specified I<option> of the indicator. If the
-indicator doesn't exist, returns an error.
-
-=item I<$hlist>-E<gt>B<indicator>(B<configure>, I<$entryPath>, ?I<option>?, I<?value, option, value, ...>?)
-
-Query or modify the configuration options of the indicator display
-item of the entry specified by I<$entryPath>. The indicator item
-must exist, or an error will result. If no I<option> is specified,
-returns a list describing all of the available options for the
-indicator display item (see L<Tk::options> for information
-on the format of this list). If I<option> is specified with no
-I<value>, then the method returns a list describing the one named
-option (this list will be identical to the corresponding sublist of
-the value returned if no I<option> is specified). If one or more
-I<option-value> pairs are specified, then the method modifies the
-given option(s) to have the given value(s); in this case the method
-returns an empty string. I<Option> may have any of the values
-accepted by the B<indicator create> method. The exact set
-of options depends on the value of the B<-itemtype> option passed
-to the the B<indicator create> method when this display item
-was created.
-
-=item I<$hlist>-E<gt>B<indicator>(B<create, >I<$entryPath, >?, I<-itemtype type>? ?I<option value ...>?)
-
-Creates a new display item as the indicator for the entry specified by
-I<$entryPath>. If an indicator display item already exists for this
-entry, it will be replaced by the new item. An optional parameter
-I<-itemtype> can be used to specify what type of display item
-should be created. If the I<-itemtype> is not given, then by
-default the type specified by this HList widget's B<-itemtype>
-option is used. Additional parameters, in I<option-value> pairs,
-can be passed to configure the appearance of the display item. Each
-I<option-value> pair must be a valid option for this type of
-display item.
-
-=item I<$hlist>-E<gt>B<indicator>(B<delete>, I<$entryPath>)
-
-Deletes the indicator display item for the entry given by I<$entryPath>.
-
-=item I<$hlist>-E<gt>B<indicator>(B<exists>, I<$entryPath>)
-
-Return true if an indicator display item exists for the entry given by
-I<$entryPath>; return false otherwise.
-
-=item I<$hlist>-E<gt>B<indicator>(B<size>, I<$entryPath>)
-
-If an indicator display item exists for the entry given by
-I<$entryPath>, returns its size in a two element list of the form
-{I<width height>}; returns an error if the indicator display item
-does not exist.
-
-=back
-
-=item I<$hlist>-E<gt>B<info>(I<option>, I<arg, ...>)
-
-Query information about the HList widget. I<option> can be one
-of the following:
-
-=over 8
-
-=item I<$hlist>-E<gt>B<info>(B<anchor>)
-
-Returns the entryPath of the current anchor, if any, of the HList
-widget. If the anchor is not set, returns the empty string.
-
-=item I<$hlist>-E<gt>B<infoBbox>(I<$entryPath>)
-
-Returns a list of four numbers describing the visible bounding box of
-the entry given I<$entryPath>. The first two elements of the list
-give the x and y coordinates of the upper-left corner of the screen
-area covered by the entry (specified in pixels relative to the widget)
-and the last two elements give the lower-right corner of the area, in
-pixels. If no part of the entry given by index is visible on the
-screen then the result is an empty string; if the entry is partially
-visible, the result gives the only the visible area of the entry.
-
-=item I<$hlist>-E<gt>B<info>(B<children> ?,I<$entryPath>?)
-
-If I<$entryPath> is given, returns a list of the entryPath's of its
-children entries. Otherwise returns a list of the toplevel
-entryPath's.
-
-=item I<$hlist>-E<gt>B<info>(B<data> ?,I<$entryPath>?)
-
-Returns the data associated with I<$entryPath>.
-
-=item I<$hlist>-E<gt>B<info>(B<dragsite>)
-
-Returns the entryPath of the current dragsite, if any, of the HList
-widget. If the dragsite is not set, returns the empty string.
-
-=item I<$hlist>-E<gt>B<info>(B<dropsite>)
-
-Returns the entryPath of the current dropsite, if any, of the HList
-widget. If the dropsite is not set, returns the empty string.
-
-=item I<$hlist>-E<gt>B<info>(B<exists>, I<$entryPath>)
-
-Returns a boolean value indicating whether the list entry
-I<$entryPath> exists.
-
-=item I<$hlist>-E<gt>B<info>(B<hidden>, I<$entryPath>)
-
-Returns a boolean value indicating whether the list entry
-B<$entryPath> is hidden or not.
-
-=item I<$hlist>-E<gt>B<info>(B<next>, I<$entryPath>)
-
-Returns the entryPath of the list entry, if any, immediately below
-this list entry. If this entry is already at the bottom of the HList
-widget, returns an empty string.
-
-=item I<$hlist>-E<gt>B<info>(B<parent>, I<$entryPath>)
-
-Returns the name of the parent of the list entry identified by
-I<$entryPath>. If I<entryPath> is a toplevel list entry,
-returns the empty string.
-
-=item I<$hlist>-E<gt>B<info>(B<prev>, I<$entryPath>)
-
-Returns the entryPath of the list entry, if any, immediately above
-this list entry. If this entry is already at the top of the HList
-widget, returns an empty string.
-
-=item I<$hlist>-E<gt>B<info>(B<selection>)
-
-Returns a list of selected entries in the HList widget. In scalar
-context, returns an anonymous list of the selected entries.
-If no entries are selected, undef is returned in scalar context, and
-an empty list otherwise.
-
-=back
-
-=item I<$hlist>-E<gt>B<item>(I<option, >?I<args, ...>?)
-
-Creates and configures the display items at individual columns the
-entries. The form of additional of arguments depends on the choice of
-I<option>:
-
-=over 8
-
-=item I<$hlist>-E<gt>B<itemCget>(I<$entryPath>, I<$col>, I<option>)
-
-Returns the current value of the configure I<option> of the display
-item at the column designated by I<$col> of the entry specified by
-I<$entryPath>.
-
-=item I<$hlist>-E<gt>B<itemConfigure>(I<$entryPath>, I<$col> ?,I<option>?, I<?value, option, value, ...>?)
-
-Query or modify the configuration options of the display item at the
-column designated by I<$col> of the entry specified by
-I<$entryPath>. If no I<option> is specified, returns a list
-describing all of the available options for I<$entryPath> (see
-L<Tk::options> for information on the format of this
-list). If I<option> is specified with no I<value>, then the
-method returns a list describing the one named option (this list will
-be identical to the corresponding sublist of the value returned if no
-I<option> is specified). If one or more I<option-value> pairs
-are specified, then the method modifies the given option(s) to have
-the given value(s); in this case the method returns an empty string.
-I<Option> may have any of the values accepted by the B<item>
-create method. The exact set of options depends on the
-value of the B<-itemtype> option passed to the the B<item>
-create method when this display item was created.
-
-=item I<$hlist>-E<gt>B<itemCreate>(I<$entryPath>, I<$col> ?,I<-itemtype>=E<gt>I<type>? ?,I<option value ...>?)
-
-Creates a new display item at the column designated by I<$col> of
-the entry specified by I<$entryPath>. An optional parameter
-I<-itemtype> can be used to specify what type of display items
-should be created. If the I<-itemtype> is not specified, then by
-default the type specified by this HList widget's B<-itemtype>
-option is used. Additional parameters, in I<option-value> pairs,
-can be passed to configure the appearance of the display item. Each
-I<option- value> pair must be a valid option for this type of
-display item.
-
-=item I<$hlist>-E<gt>B<itemDelete>(I<$entryPath>, I<$col>)
-
-Deletes the display item at the column designated by I<$col> of
-the entry specified by I<$entryPath>.
-
-=item I<$hlist>-E<gt>B<itemExists>(I<$entryPath>, I<$col>)
-
-Returns true if there is a display item at the column designated by
-I<$col> of the entry specified by I<$entryPath>; returns false
-otherwise.
-
-=back
-
-=item I<$hlist>-E<gt>B<nearest>(I<y>)
-
-I<$hlist>-E<gt>B<nearest>(I<y>)
-Given a y-coordinate within the HList window, this method returns
-the entryPath of the (visible) HList element nearest to that
-y-coordinate.
-
-=item I<$hlist>-E<gt>B<see>(I<$entryPath>)
-
-Adjust the view in the HList so that the entry given by I<$entryPath> is
-visible. If the entry is already visible then the method has no
-effect; if the entry is near one edge of the window then the HList
-scrolls to bring the element into view at the edge; otherwise the
-HList widget scrolls to center the entry.
-
-=item I<$hlist>-E<gt>B<selection>(I<option>, I<arg>, ...)
-
-=item I<$hlist>-E<gt>B<selection>I<Option>(I<arg>, ...)
-
-This method is used to adjust the selection within a HList widget. It
-has several forms, depending on I<option>:
-
-=over 8
-
-=item I<$hlist>-E<gt>B<selectionClear>(?I<from>?, ?I<to>?)
-
-When no extra arguments are given, deselects all of the list entrie(s)
-in this HList widget. When only I<from> is given, only the list
-entry identified by I<from> is deselected. When both I<from> and
-I<to> are given, deselects all of the list entrie(s) between
-between I<from> and I<to>, inclusive, without affecting the
-selection state of elements outside that range.
-
-=item I<$hlist>-E<gt>B<selectionGet>
-
-This is an alias for the B<infoSelection> method.
-
-=item I<$hlist>-E<gt>B<selectionIncludes>(I<$entryPath>)
-
-Returns 1 if the list entry indicated by I<$entryPath> is currently
-selected; returns 0 otherwise.
-
-=item I<$hlist>-E<gt>B<selectionSet>(I<from>?, I<to>?)
-
-Selects all of the list entrie(s) between between I<from> and
-I<to>, inclusive, without affecting the selection state of entries
-outside that range. When only I<from> is given, only the list entry
-identified by I<from> is selected.
-
-=back
-
-=item I<$hlist>-E<gt>B<show>(I<option> ?,I<$entryPath>?)
-
-Show the entries that are hidden by the B<hide> method,
-I<option> can be one of the following:
-
-=over 8
-
-=item B<entry>
-
-Shows the list entry identified by I<$entryPath>.
-
-=back
-
-Currently only the B<entry> option is supported. Other options will
-be added in future releases.
-
-=item I<$hlist>-E<gt>B<xview>(I<args>)
-
-This method is used to query and change the horizontal position of the
-information in the widget's window. It can take any of the following
-forms:
-
-=over 8
-
-=item I<$hlist>-E<gt>B<xview>
-
-Returns a list containing two elements. Each element is a real
-fraction between 0 and 1; together they describe the horizontal span
-that is visible in the window. For example, if the first element is
-.2 and the second element is .6, 20% of the HList entry is
-off-screen to the left, the middle 40% is visible in the window, and
-40% of the entry is off-screen to the right. These are the same values
-passed to scrollbars via the B<-xscrollcommand> option.
-
-=item I<$hlist>-E<gt>B<xview>(I<$entryPath>)
-
-Adjusts the view in the window so that the list entry identified by
-I<$entryPath> is aligned to the left edge of the window.
-
-=item I<$hlist>-E<gt>B<xview>(B<moveto> =E<gt> I<fraction>)
-
-Adjusts the view in the window so that I<fraction> of the total
-width of the HList is off-screen to the left. I<fraction> must be
-a fraction between 0 and 1.
-
-=item I<$hlist>-E<gt>B<xview>(B<scroll> =E<gt> I<number, what>)
-
-This method shifts the view in the window left or right according to
-I<number> and I<what>. I<Number> must be an integer.
-I<What> must be either B<units> or B<pages> or an
-abbreviation of one of these. If I<what> is B<units>, the view
-adjusts left or right by I<number> character units (the width of
-the B<0> character) on the display; if it is B<pages> then the
-view adjusts by I<number> screenfuls. If I<number> is negative
-then characters farther to the left become visible; if it is positive
-then characters farther to the right become visible.
-
-=back
-
-=item I<$hlist>-E<gt>B<yview>(I<?args>?)
-
-This method is used to query and change the vertical position of the
-entries in the widget's window. It can take any of the following forms:
-
-=over 8
-
-=item I<$hlist>-E<gt>B<yview>
-
-Returns a list containing two elements, both of which are real
-fractions between 0 and 1. The first element gives the position of
-the list element at the top of the window, relative to the HList as a
-whole (0.5 means it is halfway through the HList, for example). The
-second element gives the position of the list entry just after the
-last one in the window, relative to the HList as a whole. These are
-the same values passed to scrollbars via the B<-yscrollcommand>
-option.
-
-=item I<$hlist>-E<gt>B<yview>(I<$entryPath>)
-
-Adjusts the view in the window so that the list entry given by
-I<$entryPath> is displayed at the top of the window.
-
-=item I<$hlist>-E<gt>B<yview>(B<moveto> =E<gt> I<fraction>)
-
-Adjusts the view in the window so that the list entry given by
-I<fraction> appears at the top of the window. I<Fraction> is a
-fraction between 0 and 1; 0 indicates the first entry in the
-HList, 0.33 indicates the entry one-third the way through the
-HList, and so on.
-
-=item I<$hlist>-E<gt>B<yview>(B<scroll> =E<gt> I<number, what>)
-
-This method adjust the view in the window up or down according to
-I<number> and I<what>. I<Number> must be an integer.
-I<What> must be either B<units> or B<pages>. If I<what>
-is B<units>, the view adjusts up or down by I<number> lines; if
-it is B<pages> then the view adjusts by I<number> screenfuls.
-If I<number> is negative then earlier entries become visible; if
-it is positive then later entries become visible.
-
-=back
-
-=back
-
-=head1 BINDINGS
-
-=over 4
-
-=item [1]
-
-If the B<-selectmode> is "browse", when the user drags the mouse
-pointer over the list entries, the entry under the pointer will be
-highlighted and the B<-browsecmd> callback will be called with
-one parameter, the entryPath of the highlighted entry. Only one entry
-can be highlighted at a time. The B<-command> callback will be
-called when the user double-clicks on a list entry.
-
-=item [2]
-
-If the B<-selectmode> is "single", the entries will only be
-highlighted by mouse E<lt>ButtonRelease-1E<gt> events. When a new list entry
-is highlighted, the B<-browsecmd> callback will be called with
-one parameter indicating the highlighted list entry. The
-B<-command> callback will be called when the user double-clicks
-on a list entry.
-
-=item [3]
-
-If the B<-selectmode> is "multiple", when the user drags the mouse
-pointer over the list entries, all the entries under the pointer will
-be highlighted. However, only a contiguous region of list entries can
-be selected. When the highlighted area is changed, the
-B<-browsecmd> callback will be called with an undefined
-parameter. It is the responsibility of the B<-browsecmd> callback
-to find out the exact highlighted selection in the HList. The
-B<-command> callback will be called when the user double-clicks
-on a list entry.
-
-=item [4]
-
-If the B<-selectmode> is "extended", when the user drags the mouse
-pointer over the list entries, all the entries under the pointer will
-be highlighted. The user can also make disjointed selections using
-E<lt>Control-ButtonPress-1E<gt>. When the highlighted area is changed, the
-B<-browsecmd> callback will be called with an undefined
-parameter. It is the responsibility of the B<-browsecmd> callback
-to find out the exact highlighted selection in the HList. The
-B<-command> callback will be called when the user double-clicks
-on a list entry.
-
-=item [5]
-
-B<Arrow key bindings:> E<lt>UpE<gt> arrow key moves the anchor point to the
-item right on top of the current anchor item. E<lt>DownE<gt> arrow key moves
-the anchor point to the item right below the current anchor item.
-E<lt>LeftE<gt> arrow key moves the anchor to the parent item of the current
-anchor item. E<lt>RightE<gt> moves the anchor to the first child of the
-current anchor item. If the current anchor item does not have any
-children, moves the anchor to the item right below the current anchor
-item.
-
-=back
-
-=head1 EXAMPLE
-
-This example demonstrates how to use an HList to store a file
-directory structure and respond to the user's browse events:
-
- use strict;
- use Tk;
- use Tk::Label;
- use Tk::HList;
-
- my $mw = MainWindow->new();
- my $label = $mw->Label(-width=>15);
- my $hlist = $mw->HList(
- -itemtype => 'text',
- -separator => '/',
- -selectmode => 'single',
- -browsecmd => sub {
- my $file = shift;
- $label->configure(-text=>$file);
- }
- );
-
- foreach ( qw(/ /home /home/ioi /home/foo /usr /usr/lib) ) {
- $hlist->add($_, -text=>$_);
- }
-
- $hlist->pack;
- $label->pack;
-
- MainLoop;
-
-=head1 BUGS
-
-The fact that the display item at column 0 is implicitly associated
-with the whole entry is probably a design bug. This was done for
-backward compatibility purposes. The result is that there is a large
-overlap between the B<item> method and the B<add>,
-B<addchild>, B<entrycget> and B<entryconfigure>
-methods. Whenever multiple columns exist, the programmer should use
-ONLY the B<item> method to create and configure the display items
-in each column; the B<add>, B<addchild>, B<entrycget> and
-B<entryconfigure> should be used ONLY to create and configure
-entries.
-
-=head1 KEYWORDS
-
-Hierarchical Listbox
-
-=head1 SEE ALSO
-
-L<Tk::DItem|Tk::DItem>
-
-=cut
-
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/IO.pod b/Master/tlpkg/tlperl/lib/Tk/IO.pod
deleted file mode 100644
index 2781d2e17e6..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/IO.pod
+++ /dev/null
@@ -1,51 +0,0 @@
-
-=head1 NAME
-
-Tk::IO - high level interface to Tk's 'fileevent' mechanism
-
-=for pm IO/IO.pm
-
-=for category Binding Events and Callbacks
-
-=head1 SYNOPSIS
-
- my $fh = Tk::IO->new(-linecommand => callback, -childcommand => callback);
- $fh->exec("command")
- $fh->wait
- $fh->kill
-
-=head1 WARNING
-
-INTERFACES TO THIS MODULE MAY CHANGE AS PERL'S IO EVOLVES
-AND WITH PORT OF TK4.1
-
-=head1 DESCRIPTION
-
-Tk::IO is now layered on perl's IO::Handle class. Interfaces
-have changed, and are still evolving.
-
-In theory C methods which enable non-blocking IO as in earlier Tk-b*
-release(s) are still there. I have not changed them to use perl's
-additional Configure information, or tested them much.
-
-Assumption is that B<exec> is
-used to fork a child process and a callback is called each time a
-complete line arrives up the implied pipe.
-
-"line" should probably be defined in terms of perl's input record
-separator but is not yet.
-
-The -childcommand callback is called when end-of-file occurs.
-
-$fh->B<wait> can be used to wait for child process while processing
-other Tk events.
-
-$fh->B<kill> can be used to send signal to child process.
-
-=head1 BUGS
-
-Still not finished.
-Idea is to use "exec" to emulate "system" in a non-blocking manner.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/IconList.pod b/Master/tlpkg/tlperl/lib/Tk/IconList.pod
deleted file mode 100644
index e68324ce4b6..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/IconList.pod
+++ /dev/null
@@ -1,82 +0,0 @@
-=head1 NAME
-
-Tk::IconList - an icon list widget
-
-=for pm Tk/IconList.pm
-
-=for category Derived Widgets
-
-=head1 SYNOPSIS
-
- use Tk::IconList;
- $il = $mw->IconList(-browsecmd => sub { ... },
- -command => sub { ... })->pack;
- $il->Add($icon1, $text1);
- $il->Add($icon2, $text2);
- $il->Arrange;
- ...
- $il->DeleteAll;
-
-=head1 DESCRIPTION
-
-=head2 OPTIONS
-
-=over
-
-=item -browsecmd
-
-=item -command
-
-=item -font
-
--item -foreground|-fg
-
-=back
-
-=head2 METHODS
-
-=over 4
-
-=item DeleteAll
-
-Deletes all the items inside the canvas subwidget and reset the IconList's
-state.
-
-=item Add($image, $text)
-
-Adds an icon into the IconList with the designated image and text.
-
-=item Arrange
-
-Places the icons in a column-major arrangement.
-
-=item Get
-
-Return the selected item.
-
-=item Invoke
-
-Gets called when the user invokes the IconList (usually by double-clicking
-or pressing the Return key) (internal method).
-
-=item See($tag)
-
-If the item is not (completely) visible, scroll the canvas so that it
-becomes visible (internal method).
-
-=back
-
-=head1 COPYRIGHT
-
-The original tkfbox.tcl from Tcl/Tk is:
-
-Copyright (c) 1994-1996 Sun Microsystems, Inc.
-
-See the file "license.terms" for information on usage and redistribution
-of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-
-Translated to Perl/Tk by Slaven Rezic <srezic@cpan.org>.
-
-=head1 SEE ALSO
-
-L<Tk::FBox>.
diff --git a/Master/tlpkg/tlperl/lib/Tk/Image.pod b/Master/tlpkg/tlperl/lib/Tk/Image.pod
deleted file mode 100644
index 797ecc23cbf..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Image.pod
+++ /dev/null
@@ -1,145 +0,0 @@
-# Copyright (c) 1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Image - Create and manipulate images
-
-=for category Tk Image Classes
-
-=head1 SYNOPSIS
-
-I<$image> = I<$widget>-E<gt>I<type>(?I<arg arg ...>?)
-
-I<$image>-E<gt>I<method>(?I<arg arg ...>?)
-
-=head1 DESCRIPTION
-
-The B<image> constructors and methods are used to create, delete, and query images.
-It can take several different forms, depending on the
-I<type>.
-
-The constructors require a I<$widget> to invoke them, this is used
-to locate a B<MainWindow>. (This is because the underlying Tk code
-registers the images in the data structure for the B<MainWindow>.)
-
-The legal forms are:
-
-=over 4
-
-=item I<$widget>-E<gt>I<type>?(?I<name>?,?I<option>=E<gt>I<value ...>)?
-
-Creates a new image and returns an object.
-I<type> specifies the type of the image, which must be one of
-the types currently defined (e.g., B<Bitmap>).
-I<name> specifies the name for the image; if it is omitted then
-Tk picks a name of the form B<image>I<x>, where I<x> is
-an integer.
-There may be any number of I<option>=E<gt>I<value> pairs,
-which provide configuration options for the new image.
-The legal set of options is defined separately for each image
-type; see below for details on the options for built-in image types.
-If an image already exists by the given name then it is replaced
-with the new image and any instances of that image will redisplay
-with the new contents.
-
-=item I<$image>-E<gt>B<delete>
-
-Deletes the image I<$image> and returns an empty string.
-If there are instances of the image displayed in widgets,
-the image won't actually be deleted until all of the instances
-are released.
-However, the association between the instances and the image
-manager will be dropped.
-Existing instances will retain their sizes but redisplay as
-empty areas.
-If a deleted image is recreated (with the same I<name>)
-the existing instances will use the new image.
-
-=item I<$image>-E<gt>B<height>
-
-Returns a decimal string giving the height of image I<name>
-in pixels.
-
-=item I<$image>-E<gt>B<inuse>
-
-Returns a boolean value indicating whether or not the image is in use
-by any widgets.
-
-=item I<$widget>-E<gt>B<imageNames>
-
-Returns a list containing all existing images for I<$widget>'s
-B<MainWindow>.
-
-=item I<$image>-E<gt>B<type>
-
-Returns the type of I<$image> (the value of the I<type>
-method when the image was created).
-
-=item I<$widget>-E<gt>B<imageTypes>
-
-Returns a list whose elements are all of the valid image types
-(i.e., all of the values that may be supplied for the I<type>
-to create an image).
-
-=item I<$image>-E<gt>B<width>
-
-Returns a decimal string giving the width of image I<name>
-in pixels.
-
-=back
-
-=head1 BUILT-IN IMAGE TYPES
-
-The following image types are defined by Tk so they will be available
-in any Tk application.
-Individual applications or extensions may define additional types.
-
-=over 4
-
-=item B<Bitmap>
-
-Each pixel in the image displays a foreground color, a background
-color, or nothing.
-See L<Tk::Bitmap> for more information.
-
-=item B<Pixmap>
-
-B<Pixmap> is slightly more general than B<Bitmap>, each pixel can
-be any available color or "transparent" (rendered as background color of the
-widget image is displayed in). B<Pixmap> is best used for icons and other
-simple graphics with only a few colors.
-
-B<Pixmap> is derived from Tix. See L<Tk::Pixmap> for more information.
-
-=item B<Photo>
-
-Displays a variety of full-color images, using dithering to
-approximate colors on displays with limited color capabilities.
-See L<Tk::Photo> documentation for more information.
-
-=back
-
-=head1 CAVEATS
-
-It's necessary to use the L</delete> method to delete an image object
-and free memory associated with it. Just using a lexical variable for
-storing the image object and letting the variable to go out of scope
-or setting to C<undef> is not sufficient.
-
-=head1 SEE ALSO
-
-L<Tk::Bitmap|Tk::Bitmap>
-L<Tk::Pixmap|Tk::Pixmap>
-L<Tk::Photo|Tk::Photo>
-
-=head1 KEYWORDS
-
-height, image, types of images, width
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/InputO.pod b/Master/tlpkg/tlperl/lib/Tk/InputO.pod
deleted file mode 100644
index 03a43b29ed7..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/InputO.pod
+++ /dev/null
@@ -1,50 +0,0 @@
-=head1 NAME
-
-Tk::InputO - Create and manipulate TIX InputO widgets
-
-=for category Tix Extensions
-
-=head1 SYNOPSIS
-
-I<$inputonly> = I<$parent>-E<gt>B<InputO>(?I<options>?);
-
-=head1 STANDARD OPTIONS
-
-Only the following three standard options are supported by
-B<InputO>:
-
-B<cursor> B<width> B<height>
-
-See L<Tk::options> for details of the standard options.
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-B<InputO> does not have any widget specific options.
-
-=head1 DESCRIPTION
-
-The B<InputO> method creates a new window (given by the
-$widget argument) and makes it into a B<InputO>
-widget. Additional options, described above, may be specified on the
-command line or in the option database to configure aspects of the
-B<InputO> such as its cursor or width.
-
-B<InputO> widgets are not visible to the user. The only
-purpose of B<InputO> widgets are to accept inputs from the
-user, which can be done with the B<bind> method.
-
-=head1 WIDGET METHODS
-
-The B<InputO> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-=head1 BINDINGS
-
-B<InputO> widgets have no default bindings.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Internals.pod b/Master/tlpkg/tlperl/lib/Tk/Internals.pod
deleted file mode 100644
index 4ee1e0126ca..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Internals.pod
+++ /dev/null
@@ -1,142 +0,0 @@
-=head1 NAME
-
-CallingTk - what is Perl Tk interface doing when you call Tk functions.
-
-=for category C Programming
-
-This information is worse than useless for C<perlTk> users, but can of
-some help for people interested in using modified Tk source with
-C<perlTk>.
-
-I<This document is under construction. The information is believed to
-be pertinent to the version of> C<portableTk> I<available when it was
-created. All the details are subject to change.>
-
-=head1 DESCRIPTION
-
-=over 4
-
-=item PreCompiling
-
-Before the actual compilation stage a script scans the source
-and extracts the subcommands of different commands. This information
-resides in the file C<pTk/Methods.def>.
-
-=item Compilation
-
-During compilation the above file is included in the source of booting
-routine of dynamic (or static) library. More precisely, the booting
-code of module C<Tk> calls the subroutine Boot_Glue() from the module
-C<tkGlue.c>, and this subroutine includes the file (with appropriate
-macro definitions).
-
-=item Inside C<use Tk;>
-
-The module bootstraps the C code, then loads the Perl libraries. The
-heart of the Perl code is contained in the C<Tk::Widget> library, all the
-widgets inherit from this module. Code for toplevels is loaded from
-C<Tk::MainWindow>.
-
-During bootstrap of the C glue code the C<Xevent::?> codes and a
-handful of C<Tk::Widget> and C<Tk::Image> routines are defined. (Much
-more XSUBs are created from C<Tk.xs> code.) The widget subcommands are
-glued to Perl basing on the list included from C<pTk/Methods.def>. In
-fact all the subcommands are glued to XSUBs that are related to the
-same C subroutine XStoWidget(), but have different data parts.
-
-During the Perl code bootstrap the method C<Tk::Widget::import> is
-called. This call requires all the code from particular widget
-packages.
-
-Code from the widget packages calls an obscure command like
-
- (bless \"Text")->WidgetClass;
-
-This command (actually Tk::Widget::WidgetClass()) creates three
-routines: Tk::Widget::Text(), Tk::Widget::isText(), and
-Tk::Text::isText(). The first one is basically C<new> of C<Tk::Text>,
-the other two return constants. It also puts the class into
-depository.
-
-=item Inside C<$top = MainWindow-E<gt>new;>
-
-This is quite intuitive. This call goes direct to
-C<Tk::MainWindow::new>, that calls XSUB
-C<Tk::MainWindow::CreateMainWindow>, that calls C subroutine
-Tk_CreateMainWindow(). It is a C<Tk> subroutine, so here black magic
-ends (almost).
-
-The only remaining black magic is that the C<Tk> initialization
-routine creates a lot of commands, but the subroutine for creation is
-usurped by B<portableTk> and the commands are created in the package
-C<Tk>. They are associated to XSUBs that are related to one of three C
-subroutines XStoSubCmd(), XStoBind(), or XStoTk(), but have different
-data parts.
-
-The result of the call is blessed into C<Tk::MainWindow>, as it should.
-
-=item Inside C<$top-E<gt>title('Text demo');>
-
-The package C<Tk::Toplevel> defines a lot of subroutines on the fly on
-some list. All the commands from the list are converted to the
-corresponding subcommands of C<wm> method of the widget. Here
-subcommand is a command with some particular second argument (in this
-case C<"title">). Recall that the first argument is $self.
-
-Now C<Tk::Toplevel> @ISA C<Tk::Widget>, that in turn @ISA C<Tk>. So a
-call to C<$top-E<gt>wm('title','Text demo')> calls C<Tk::wm>, that is
-defined during call to Tk_CreateMainWindow(). As it is described
-above, the XSUB associated to XStoSubCmd() is called.
-
-This C routine is defined in C<tkGlue.c>. It gets the data part of
-XSUB, creates a C<SV> with the name of the command, and calls
-Call_Tk() with the XSUB data as the first argument, and with the name
-of XSUB stuffed into the Perl stack in the place there C<tk> expects
-it. (In fact it can also reorder the arguments if it thinks it is
-what you want).
-
-The latter procedure extracts name of C<tk> procedure and
-C<clientData> from the first argument and makes a call, using Perl
-stack as C<argv> for the procedure. A lot of black magic is performed
-afterwards to convert result of the procedure to a Perl array return.
-
-=item Inside C<$text = $top-E<gt>Text(background =E<gt> $txtBg);>
-
-Above we discussed how the command C<Tk::Widget::Text> is created. The
-above command calls it via inheritance. It is translated to
-
- Tk::Text::new($top, background => $txtBg);
-
-The package C<Tk::Text> has no method C<new>, so the
-C<Tk::Widget::new> is called. In turn it calls
-C<Tk::Text-E<gt>DoInit($top)>, that is
-C<Tk::Widget::DoInit(Tk::Text,$top)>, that initializes the bindings if
-necessary. Then it creates the name for the widget of the form
-C<.text0>, and calls C<Tk::text('.text0', background =E<gt> $txtBg)>
-(note lowercase). The result of the call is blessed into C<Tk::Text>,
-and the method C<bindtags> for this object is called.
-
-Now the only thing to discuss is who defines the methods C<text> and
-C<bindtags>. The answer is that they are defined in C<tkWindow.c>,
-and these commands are created in the package C<Tk> in the same sweep
-that created the command C<Tk::wm> discussed above.
-
-So the the same C code that corresponds to the processing of
-corresponding TCL commands is called here as well (this time via
-C<XStoTk> interface).
-
-=item Inside C<$text-E<gt>insert('insert','Hello, world!');>
-
-As we discussed above, the subcommands of widget procedures correspond
-to XSUB C<XStoWidget>. This XSUB substitutes the first argument $text
-(that is a hash reference) to an appropriate value from this hash,
-adds the additional argument after the first one that contains the
-name of the subcommand extracted from the data part of XSUB, and calls
-the corresponding Tk C subroutine via C<Call_Tk>.
-
-=back
-
-Ilya Zakharevich <ilya@math.ohio-state.edu>
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/LabFrame.pod b/Master/tlpkg/tlperl/lib/Tk/LabFrame.pod
deleted file mode 100644
index cf5cebf754a..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/LabFrame.pod
+++ /dev/null
@@ -1,110 +0,0 @@
-=head1 NAME
-
-Tk::LabFrame - labeled frame.
-
-=for pm Tixish/LabFrame.pm
-
-=for category Tix Extensions
-
-=head1 SYNOPSIS
-
-S< >B<use Tk::LabFrame;>
-
-S< >I<$f> = I<$parent>-E<gt>B<LabFrame>(?B<-label>=E<gt>I<text>,
-B<-labelside>=E<gt>I<where>, ...?);
-
-=head1 DESCRIPTION
-
-B<LabFrame> is exactly like B<Frame> and additionaly allows to
-add a label to the frame.
-
-=head1 WIDGET-OPTIONS
-
-B<LabFrame> supports the same options as the
-L<Frame|Tk::Frame/"STANDARD OPTIONS"> widget.
-
-Additional options of B<LabFrame> are:
-
-=over 4
-
-=item B<-font> =E<gt> I<font>
-
-Specifies the label's font
-
-=item B<-foreground> =E<gt> I<color>
-
-Specifies the label's foreground color
-
-=item B<-label> =E<gt> I<text>
-
-The text of the label to be placed with the Frame.
-
-=item B<-labelside> =E<gt> I<where>
-
-I<Where> can be one of B<left>, B<right>, B<top>, B<bottom> or B<acrosstop>.
-The first four work as might be expected and place the label to the
-left, right, above or below the frame respectively. The B<acrosstop>
-creates a grooved frame around the central frame and puts the label
-near the northwest corner such that it appears to "overwrite" the
-groove.
-
-=item B<-labelvariable> =E<gt> I<scalar_ref>
-
-Specifies a reference to a variable and used as an
-alternative to -label. If the value of the variable changes,
-then the widget will be updated automatically to reflect the
-change. Used like -textvariable.
-
-=back
-
-=head1 ADVERTISED SUBWIDGETS
-
-See L<Tk::mega/"Subwidget"> how to use advertised widgets.
-
-=over 4
-
-=item I<border>
-
- Frame used to display the border
-
-=item I<frame>
-
- Frame used to create new LabFrame children.
-
-=item I<label>
-
- Label used for displaying text
-
-=back
-
-=head1 EXAMPLE
-
-Run the following test program to see this in action:
-
- use strict;
- use Tk;
- require Tk::LabFrame;
- require Tk::LabEntry;
-
- my $test = 'Test this';
- my $mw = Tk::MainWindow->new;
- my $f = $mw->LabFrame(-label => "This is a label",
- -labelside => "acrosstop");
- $f->LabEntry(-label => "Testing", -textvariable => \$test)->pack;
- $f->pack;
- Tk::MainLoop;
-
-=head1 BUGS
-
-Perhaps B<LabFrame> should be subsumed within the generic pTk
-labeled widget mechanism.
-
-=head1 AUTHOR
-
-B<Rajappa Iyer> rsi@earthling.net
-
-This code is derived from LabFrame.tcl and LabWidg.tcl in the Tix4.0
-distribution by Ioi Lam. The code may be redistributed under the same
-terms as Perl.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Tk/Label.pod b/Master/tlpkg/tlperl/lib/Tk/Label.pod
deleted file mode 100644
index 96386b09b5c..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Label.pod
+++ /dev/null
@@ -1,133 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Label - Create and manipulate Label widgets
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
-I<$label> = I<$parent>-E<gt>B<Label>(?I<options>?);
-
-=head1 STANDARD OPTIONS
-
-B<-activebackground>
-B<-activeforeground>
-B<-anchor>
-B<-background>
-B<-bitmap>
-B<-borderwidth>
-B<-compound>
-B<-cursor>
-B<-disabledforeground>
-B<-font>
-B<-foreground>
-B<-highlightbackground>
-B<-highlightcolor>
-B<-highlightthickness>
-B<-image>
-B<-justify>
-B<-padx>
-B<-pady>
-B<-relief>
-B<-takefocus>
-B<-text>
-B<-textvariable>
-B<-underline>
-B<-wraplength>
-
-See L<Tk::options> for details of the standard options.
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<height>
-
-=item Class: B<Height>
-
-=item Switch: B<-height>
-
-Specifies a desired height for the label.
-If an image or bitmap is being displayed in the label then the value is in
-screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>);
-for text it is in lines of text.
-If this option isn't specified, the label's desired height is computed
-from the size of the image or bitmap or text being displayed in it.
-
-=item Name: B<state>
-
-=item Class: B<State>
-
-=item Switch: B<-state>
-
-Specifies one of three states for the label: B<normal>, B<active>, or
-B<disabled>. In normal state the label is displayed using the
-B<foreground> and B<background> options. In active state the label is
-displayed using the B<activeForeground> and B<activeBackground>
-options. In the disabled state the B<disabledForeground> and
-B<background> options determine how the button is displayed.
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-=item Switch: B<-width>
-
-Specifies a desired width for the label.
-If an image or bitmap is being displayed in the label then the value is in
-screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>);
-for text it is in characters.
-If this option isn't specified, the label's desired width is computed
-from the size of the image or bitmap or text being displayed in it.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Label> method creates a new window (given by the
-$widget argument) and makes it into a label widget.
-Additional
-options, described above, may be specified on the command line
-or in the option database
-to configure aspects of the label such as its colors, font,
-text, and initial relief. The B<label> command returns its
-$widget argument. At the time this command is invoked,
-there must not exist a window named $widget, but
-$widget's parent must exist.
-
-A label is a widget that displays a textual string, bitmap or image.
-If text is displayed, it must all be in a single font, but it
-can occupy multiple lines on the screen (if it contains newlines
-or if wrapping occurs because of the B<wrapLength> option) and
-one of the characters may optionally be underlined using the
-B<underline> option.
-The label can be manipulated in a few simple ways, such as
-changing its relief or text, using the commands described below.
-
-=head1 WIDGET METHODS
-
-The B<Label> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-=head1 BINDINGS
-
-When a new label is created, it has no default event bindings:
-labels are not intended to be interactive.
-
-=head1 KEYWORDS
-
-label, widget
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Labelframe.pod b/Master/tlpkg/tlperl/lib/Tk/Labelframe.pod
deleted file mode 100644
index b904ad7775b..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Labelframe.pod
+++ /dev/null
@@ -1,206 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-# RCS: @(#) $Id: labelframe.n,v 1.1 2001/09/26 21:36:19 pspjuth Exp $
-
-=head1 NAME
-
-Tk::Labelframe - Create and manipulate Labelframe widgets
-
-=for category Tk Generic Methods
-
-=head1 SYNOPSIS
-
-I<$labelframe> = I<$parent>-E<gt>B<Labelframe>(?I<options>?);
-
- -borderwidth -highlightbackground -pady
- -cursor -highlightcolor -relief
- -font -highlightthickness -takefocus
- -foreground -padx -text
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Option: B<-background>
-
-=item Name: B<background>
-
-=item Class: B<Background>
-
-This option is the same as the standard B<background> option
-except that its value may also be specified as an empty string.
-In this case, the widget will display no background or border, and
-no colors will be consumed from its colormap for its background
-and border.
-
-=item Option: B<-class>
-
-=item Name: B<class>
-
-=item Class: B<Class>
-
-Specifies a class for the window.
-This class will be used when querying the option database for
-the window's other options, and it will also be used later for
-other purposes such as bindings.
-The B<class> option may not be changed with the B<configure>
-method.
-
-=item Option: B<-colormap>
-
-=item Name: B<colormap>
-
-=item Class: B<Colormap>
-
-Specifies a colormap to use for the window.
-The value may be either B<new>, in which case a new colormap is
-created for the window and its children, or the name of another
-window (which must be on the same screen and have the same visual
-as $widget), in which case the new window will use the colormap
-from the specified window.
-If the B<colormap> option is not specified, the new window
-uses the same colormap as its parent.
-This option may not be changed with the B<configure>
-method.
-
-=item Option: B<-container>
-
-=item Name: B<container>
-
-=item Class: B<Container>
-
-The value must be a boolean. If true, it means that this window will
-be used as a container in which some other application will be embedded
-(for example, a Tk toplevel can be embedded using the B<-use> option).
-The window will support the appropriate window manager protocols for
-things like geometry requests. The window should not have any
-children of its own in this application.
-This option may not be changed with the B<configure>
-method.
-
-=item Option: B<-height>
-
-=item Name: B<height>
-
-=item Class: B<Height>
-
-Specifies the desired height for the window in any of the forms
-acceptable to B<Tk_GetPixels>.
-If this option is less than or equal to zero then the window will
-not request any size at all.
-
-=item Option: B<-labelanchor>
-
-=item Name: B<labelAnchor>
-
-=item Class: B<LabelAnchor>
-
-Specifies where to place the label. A label is only displayed if the
-B<-text> option is not the empty string.
-Valid values for this option are (listing them clockwise)
-B<nw>, B<n>, B<ne>, B<en>, B<e>, B<es>,
-B<se>, B<s>,B<sw>, B<ws>, B<w> and B<wn>.
-The default value is B<nw>.
-
-=item Option: B<-labelwidget>
-
-=item Name: B<labelWidget>
-
-=item Class: B<LabelWidget>
-
-Specifies a widget to use as label. This overrides any B<-text>
-option. The widget must exist before being used as B<-labelwidget>
-and if it is not a descendant of this window, it will be raised
-above it in the stacking order.
-
-=item Option: B<-visual>
-
-=item Name: B<visual>
-
-=item Class: B<Visual>
-
-Specifies visual information for the new window in any of the
-forms accepted by B<Tk_GetVisual>.
-If this option is not specified, the new window will use the same
-visual as its parent.
-The B<visual> option may not be modified with the B<configure>
-method.
-
-=item Option: B<-width>
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-Specifies the desired width for the window in any of the forms
-acceptable to B<Tk_GetPixels>.
-If this option is less than or equal to zero then the window will
-not request any size at all.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Labelframe> method creates a new window (given by the
-$labelframe argument) and makes it into a Labelframe widget.
-Additional
-options, described above, may be specified on the command line
-or in the option database
-to configure aspects of the Labelframe such as its background color
-and relief.
-
-A Labelframe is a simple widget. Its primary purpose is to act as a
-spacer or container for complex window layouts. It has the features
-of a B<Frame> plus the ability to display a label.
-
-=head1 WIDGET METHODS
-
-The B<Labelframe> method
-may be used to invoke various operations on the widget. It has the
-following general form:
-
- $widget->method(?arg arg ...?);
-
-The following
-methods are possible for Labelframe widgets:
-
-=over 4
-
-=item I<$widget>-E<gt>B<cget>(I<option>);
-
-Returns the current value of the configuration option given
-by I<option>.
-I<Option> may have any of the values accepted by the B<Labelframe>
-command.
-
-=item I<$widget>-E<gt>B<configure>(?I<option>?, I<?value, option, value, ...>?);
-
-Query or modify the configuration options of the widget.
-If no I<option> is specified, returns a list describing all of
-the available options for $widget (see L<Tk::configure> for
-information on the format of this list). If I<option> is specified
-with no I<value>, then the command returns a list describing the
-one named option (this list will be identical to the corresponding
-sublist of the value returned if no I<option> is specified). If
-one or more I<option-value> pairs are specified, then the command
-modifies the given widget option(s) to have the given value(s); in
-this case the command returns an empty string.
-I<Option> may have any of the values accepted by the B<Labelframe>
-command.
-
-=back
-
-=head1 BINDINGS
-
-When a new Labelframe is created, it has no default event bindings:
-Labelframes are not intended to be interactive.
-
-=head1 SEE ALSO
-
-L<Tk::Frame>, L<Tk::Label>
-
-=head1 KEYWORDS
-
-Labelframe, widget
diff --git a/Master/tlpkg/tlperl/lib/Tk/Listbox.pod b/Master/tlpkg/tlperl/lib/Tk/Listbox.pod
deleted file mode 100644
index ba00afe3ed9..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Listbox.pod
+++ /dev/null
@@ -1,794 +0,0 @@
-# Copyright (c) 1990 The Regents of the University of California.
-# Copyright (c) 1994-1997 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Listbox - Create and manipulate Listbox widgets
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
-I<$listbox> = I<$parent>-E<gt>B<Listbox>(?I<options>?);
-
-=head1 STANDARD OPTIONS
-
-B<-background> B<-borderwidth> B<-cursor> B<-disabledforeground>
-B<-exportselection> B<-font> B<-foreground> B<-height>
-B<-highlightbackground> B<-highlightcolor> B<-highlightthickness>
-B<-offset> B<-relief> B<-selectbackground> B<-selectborderwidth>
-B<-selectforeground> B<-setgrid> B<-state> B<-takefocus> B<-tile>
-B<-width> B<-xscrollcommand> B<-yscrollcommand>
-
-
-See L<Tk::options> for details of the standard options.
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<activeStyle>
-
-=item Class: B<ActiveStyle>
-
-=item Switch: B<-activestyle>
-
-Specifies the style in which to draw the active element. This must be
-one of B<dotbox> (show a focus ring around the active element), B<none>
-(no special indication of active element) or B<underline> (underline the
-active element). The default is B<underline>.
-
-=item Name: B<height>
-
-=item Class: B<Height>
-
-=item Switch: B<-height>
-
-Specifies the desired height for the window, in lines.
-If zero or less, then the desired height for the window is made just
-large enough to hold all the elements in the listbox.
-
-=item Name: B<listVariable>
-
-=item Class: B<Variable>
-
-=item Switch: B<-listvariable>
-
-I<The following is only partially implemented in Perl/Tk:>
-
-Specifies the reference of a variable. The value of the variable is an array
-to be displayed inside the widget; if the variable value changes
-then the widget will automatically update itself to reflect the new
-value. Attempts to assign a variable with an invalid list value to
-B<-listvariable> will cause an error. Attempts to unset a variable in use
-as a B<-listvariable> will fail but will not generate an error.
-
-=item Name: B<selectMode>
-
-=item Class: B<SelectMode>
-
-=item Switch: B<-selectmode>
-
-Specifies one of several styles for manipulating the selection.
-The value of the option may be arbitrary, but the default bindings
-expect it to be either B<single>, B<browse>, B<multiple>,
-or B<extended>; the default value is B<browse>.
-
-=item Name: B<state>
-
-=item Class: B<State>
-
-=item Switch: B<-state>
-
-Specifies one of two states for the listbox: B<normal> or B<disabled>.
-If the listbox is disabled then items may not be inserted or deleted,
-items are drawn in the B<-disabledforeground> color, and selection
-cannot be modified and is not shown (though selection information is
-retained).
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-=item Switch: B<-width>
-
-Specifies the desired width for the window in characters.
-If the font doesn't have a uniform width then the width of the
-character ``0'' is used in translating from character units to
-screen units.
-If zero or less, then the desired width for the window is made just
-large enough to hold all the elements in the listbox.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Listbox> method creates a new window (given by the
-$widget argument) and makes it into a listbox widget.
-Additional
-options, described above, may be specified on the command line
-or in the option database
-to configure aspects of the listbox such as its colors, font,
-text, and relief. The B<listbox> command returns its
-$widget argument. At the time this command is invoked,
-there must not exist a window named $widget, but
-$widget's parent must exist.
-
-A listbox is a widget that displays a list of strings, one per line.
-When first created, a new listbox has no elements.
-Elements may be added or deleted using methods described
-below. In addition, one or more elements may be selected as described
-below.
-If a listbox is exporting its selection (see B<exportSelection>
-option), then it will observe the standard X11 protocols
-for handling the selection.
-Listbox selections are available as type B<STRING>;
-the value of the selection will be the text of the selected elements, with
-newlines separating the elements.
-
-It is not necessary for all the elements to be
-displayed in the listbox window at once; commands described below
-may be used to change the view in the window. Listboxes allow
-scrolling in both directions using the standard B<xScrollCommand>
-and B<yScrollCommand> options.
-They also support scanning, as described below.
-
-=head1 INDICES
-
-Many of the methods for listboxes take one or more indices
-as arguments.
-An index specifies a particular element of the listbox, in any of
-the following ways:
-
-=over 4
-
-=item I<number>
-
-Specifies the element as a numerical index, where 0 corresponds
-to the first element in the listbox.
-
-=item B<active>
-
-Indicates the element that has the location cursor. This element
-will be displayed with an underline when the listbox has the
-keyboard focus, and it is specified with the B<activate>
-method.
-
-=item B<anchor>
-
-Indicates the anchor point for the selection, which is set with the
-B<selection anchor> method.
-
-=item B<end>
-
-Indicates the end of the listbox.
-For most commands this refers to the last element in the listbox,
-but for a few commands such as B<index> and B<insert>
-it refers to the element just after the last one.
-
-=item B<@>I<x>B<,>I<y>
-
-Indicates the element that covers the point in the listbox window
-specified by I<x> and I<y> (in pixel coordinates). If no
-element covers that point, then the closest element to that
-point is used.
-
-=back
-
-In the method descriptions below, arguments named I<index>,
-I<first>, and I<last> always contain text indices in one of
-the above forms.
-
-=head1 WIDGET METHODS
-
-The B<Listbox> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-The following additional methods are available for listbox widgets:
-
-=over 4
-
-=item I<$listbox>-E<gt>B<activate>(I<index>)
-
-Sets the active element to the one indicated by I<index>.
-If I<index> is outside the range of elements in the listbox
-then the closest element is activated.
-The active element is drawn with an underline when the widget
-has the input focus, and its index may be retrieved with the
-index B<active>.
-
-=item I<$listbox>-E<gt>B<bbox>(I<index>)
-
-Returns a list of four numbers describing the bounding box of
-the text in the element given by I<index>.
-The first two elements of the list give the x and y coordinates
-of the upper-left corner of the screen area covered by the text
-(specified in pixels relative to the widget) and the last two
-elements give the width and height of the area, in pixels.
-If no part of the element given by I<index> is visible on the
-screen,
-or if I<index> refers to a non-existent element,
-then the result is an empty string; if the element is
-partially visible, the result gives the full area of the element,
-including any parts that are not visible.
-
-=item I<$listbox>-E<gt>B<curselection>
-
-Returns a list containing the numerical indices of
-all of the elements in the listbox that are currently selected.
-If there are no elements selected in the listbox then an empty
-string is returned.
-
-=item I<$listbox>-E<gt>B<delete>(I<first, >?I<last>?)
-
-Deletes one or more elements of the listbox. I<First> and I<last>
-are indices specifying the first and last elements in the range
-to delete. If I<last> isn't specified it defaults to
-I<first>, i.e. a single element is deleted.
-
-=item I<$listbox>-E<gt>B<get>(I<first, >?I<last>?)
-
-If I<last> is omitted, returns the contents of the listbox
-element indicated by I<first>,
-or an empty string if I<first> refers to a non-existent element.
-If I<last> is specified, the command returns a list whose elements
-are all of the listbox elements between I<first> and I<last>,
-inclusive.
-Both I<first> and I<last> may have any of the standard
-forms for indices.
-
-=item I<$listbox>-E<gt>B<index>(I<index>)
-
-Returns the integer index value that corresponds to I<index>.
-If I<index> is B<end> the return value is a count of the number
-of elements in the listbox (not the index of the last element).
-
-=item I<$listbox>-E<gt>B<insert>(I<index, >?I<element, element, ...>?)
-
-Inserts zero or more new elements in the list just before the
-element given by I<index>. If I<index> is specified as
-B<end> then the new elements are added to the end of the
-list. Returns an empty string.
-
-=item I<$listbox>-E<gt>B<itemcget>(I<index>, I<option>)
-
-Returns the current value of the item configuration option given by
-I<option>. Option may have any of the values accepted by the listbox
-B<itemconfigure> command.
-
-=item I<$listbox>-E<gt>B<itemconfigure>(I<index, >?I<option, value,
-option, value, ...>?)
-
-Query or modify the configuration options of an item in the listbox.
-If no option is specified, returns a list describing all of the
-available options for the item (see Tk_ConfigureInfo for information
-on the format of this list). If option is specified with no value,
-then the command returns a list describing the one named option (this
-list will be identical to the corresponding sublist of the value
-returned if no option is specified). If one or more option-value pairs
-are specified, then the command modifies the given widget option(s) to
-have the given value(s); in this case the command returns an empty
-string. The following options are currently supported for items:
-
-=over
-
-=item B<-background> =E<gt> I<color>
-
-I<Color> specifies the background color to use when displaying the
-item. It may have any of the forms accepted by Tk_GetColor.
-
-=item B<-foreground> =E<gt> I<color>
-
-I<Color> specifies the foreground color to use when displaying the
-item. It may have any of the forms accepted by Tk_GetColor.
-
-=item B<-selectbackground> =E<gt> I<color>
-
-I<Color> specifies the background color to use when displaying the
-item while it is selected. It may have any of the forms accepted by
-Tk_GetColor.
-
-=item B<-selectforeground> =E<gt> I<color>
-
-I<Color> specifies the foreground color to use when displaying the
-item while it is selected. It may have any of the forms accepted by
-Tk_GetColor.
-
-=back
-
-=item I<$listbox>-E<gt>B<nearest>(I<y>)
-
-Given a y-coordinate within the listbox window, this command returns
-the index of the (visible) listbox element nearest to that y-coordinate.
-
-=item I<$listbox>-E<gt>B<scan>(I<option, args>)
-
-This command is used to implement scanning on listboxes. It has
-two forms, depending on I<option>:
-
-=over 8
-
-=item I<$listbox>-E<gt>B<scanMark>(I<x, y>)
-
-Records I<x> and I<y> and the current view in the listbox
-window; used in conjunction with later B<scan dragto> commands.
-Typically this command is associated with a mouse button press in
-the widget. It returns an empty string.
-
-=item I<$listbox>-E<gt>B<scanDragto>(I<x, y>.)
-
-This command computes the difference between its I<x> and I<y>
-arguments and the I<x> and I<y> arguments to the last
-B<scan mark> command for the widget.
-It then adjusts the view by 10 times the
-difference in coordinates. This command is typically associated
-with mouse motion events in the widget, to produce the effect of
-dragging the list at high speed through the window. The return
-value is an empty string.
-
-=back
-
-=item I<$listbox>-E<gt>B<see>(I<index>)
-
-Adjust the view in the listbox so that the element given by I<index>
-is visible.
-If the element is already visible then the command has no effect;
-if the element is near one edge of the window then the listbox
-scrolls to bring the element into view at the edge; otherwise
-the listbox scrolls to center the element.
-
-=item I<$listbox>-E<gt>B<selection>(I<option, arg>)
-
-This command is used to adjust the selection within a listbox. It
-has several forms, depending on I<option>:
-
-=over 8
-
-=item I<$listbox>-E<gt>B<selectionAnchor>(I<index>)
-
-Sets the selection anchor to the element given by I<index>.
-If I<index> refers to a non-existent element, then the closest
-element is used.
-The selection anchor is the end of the selection that is fixed
-while dragging out a selection with the mouse.
-The index B<anchor> may be used to refer to the anchor
-element.
-
-=item I<$listbox>-E<gt>B<selectionClear>(I<first, >?I<last>?)
-
-If any of the elements between I<first> and I<last>
-(inclusive) are selected, they are deselected.
-The selection state is not changed for elements outside
-this range.
-
-=item I<$listbox>-E<gt>B<selectionIncludes>(I<index>)
-
-Returns 1 if the element indicated by I<index> is currently
-selected, 0 if it isn't.
-
-=item I<$listbox>-E<gt>B<selectionSet>(I<first, >?I<last>?)
-
-Selects all of the elements in the range between
-I<first> and I<last>, inclusive, without affecting
-the selection state of elements outside that range.
-
-=back
-
-=item I<$listbox>-E<gt>B<size>
-
-Returns a decimal string indicating the total number of elements
-in the listbox.
-
-=item I<$listbox>-E<gt>B<xview>(I<args>)
-
-This command is used to query and change the horizontal position of the
-information in the widget's window. It can take any of the following
-forms:
-
-=over 8
-
-=item I<$listbox>-E<gt>B<xview>
-
-Returns a list containing two elements.
-Each element is a real fraction between 0 and 1; together they describe
-the horizontal span that is visible in the window.
-For example, if the first element is .2 and the second element is .6,
-20% of the listbox's text is off-screen to the left, the middle 40% is visible
-in the window, and 40% of the text is off-screen to the right.
-These are the same values passed to scrollbars via the B<-xscrollcommand>
-option.
-
-=item I<$listbox>-E<gt>B<xview>(I<index>)
-
-Adjusts the view in the window so that the character position given by
-I<index> is displayed at the left edge of the window.
-Character positions are defined by the width of the character B<0>.
-
-=item I<$listbox>-E<gt>B<xviewMoveto>( I<fraction> );
-
-Adjusts the view in the window so that I<fraction> of the
-total width of the listbox text is off-screen to the left.
-I<fraction> must be a fraction between 0 and 1.
-
-=item I<$listbox>-E<gt>B<xviewScroll>( I<number, what> );
-
-This command shifts the view in the window left or right according to
-I<number> and I<what>.
-I<Number> must be an integer.
-I<What> must be either B<units> or B<pages> or an abbreviation
-of one of these.
-If I<what> is B<units>, the view adjusts left or right by
-I<number> character units (the width of the B<0> character)
-on the display; if it is B<pages> then the view adjusts by
-I<number> screenfuls.
-If I<number> is negative then characters farther to the left
-become visible; if it is positive then characters farther to the right
-become visible.
-
-=back
-
-=item I<$listbox>-E<gt>B<yview>(I<?args>?)
-
-This command is used to query and change the vertical position of the
-text in the widget's window.
-It can take any of the following forms:
-
-=over 8
-
-=item I<$listbox>-E<gt>B<yview>
-
-Returns a list containing two elements, both of which are real fractions
-between 0 and 1.
-The first element gives the position of the listbox element at the
-top of the window, relative to the listbox as a whole (0.5 means
-it is halfway through the listbox, for example).
-The second element gives the position of the listbox element just after
-the last one in the window, relative to the listbox as a whole.
-These are the same values passed to scrollbars via the B<-yscrollcommand>
-option.
-
-=item I<$listbox>-E<gt>B<yview>(I<index>)
-
-Adjusts the view in the window so that the element given by
-I<index> is displayed at the top of the window.
-
-=item I<$listbox>-E<gt>B<yviewMoveto>( I<fraction> );
-
-Adjusts the view in the window so that the element given by I<fraction>
-appears at the top of the window.
-I<Fraction> is a fraction between 0 and 1; 0 indicates the first
-element in the listbox, 0.33 indicates the element one-third the
-way through the listbox, and so on.
-
-=item I<$listbox>-E<gt>B<yviewScroll>( I<number, what> );
-
-This command adjusts the view in the window up or down according to
-I<number> and I<what>.
-I<Number> must be an integer.
-I<What> must be either B<units> or B<pages>.
-If I<what> is B<units>, the view adjusts up or down by
-I<number> lines; if it is B<pages> then
-the view adjusts by I<number> screenfuls.
-If I<number> is negative then earlier elements
-become visible; if it is positive then later elements
-become visible.
-
-=back
-
-=back
-
-=head1 DEFAULT BINDINGS
-
-Tk automatically creates class bindings for listboxes that give them
-Motif-like behavior. Much of the behavior of a listbox is determined
-by its B<selectMode> option, which selects one of four ways
-of dealing with the selection.
-
-If the selection mode is B<single> or B<browse>, at most one
-element can be selected in the listbox at once.
-In both modes, clicking button 1 on an element selects
-it and deselects any other selected item.
-In B<browse> mode it is also possible to drag the selection
-with button 1.
-
-If the selection mode is B<multiple> or B<extended>,
-any number of elements may be selected at once, including discontiguous
-ranges. In B<multiple> mode, clicking button 1 on an element
-toggles its selection state without affecting any other elements.
-In B<extended> mode, pressing button 1 on an element selects
-it, deselects everything else, and sets the anchor to the element
-under the mouse; dragging the mouse with button 1
-down extends the selection to include all the elements between
-the anchor and the element under the mouse, inclusive.
-
-Most people will probably want to use B<browse> mode for
-single selections and B<extended> mode for multiple selections;
-the other modes appear to be useful only in special situations.
-
-Any time the selection changes in the listbox, the virtual event
-B<<< <<ListboxSelect>> >>> will be generated. It is easiest to bind to this
-event to be made aware of any changes to listbox selection.
-
-
-In addition to the above behavior, the following additional behavior
-is defined by the default bindings:
-
-=over 4
-
-=item [1]
-
-In B<extended> mode, the selected range can be adjusted by pressing
-button 1 with the Shift key down: this modifies the selection to
-consist of the elements between the anchor and the element under
-the mouse, inclusive.
-The un-anchored end of this new selection can also be dragged with
-the button down.
-
-=item [2]
-
-In B<extended> mode, pressing button 1 with the Control key down
-starts a toggle operation: the anchor is set to the element under
-the mouse, and its selection state is reversed. The selection state
-of other elements isn't changed.
-If the mouse is dragged with button 1 down, then the selection state
-of all elements between the anchor and the element under the mouse
-is set to match that of the anchor element; the selection state of
-all other elements remains what it was before the toggle operation
-began.
-
-=item [3]
-
-If the mouse leaves the listbox window with button 1 down, the window
-scrolls away from the mouse, making information visible that used
-to be off-screen on the side of the mouse.
-The scrolling continues until the mouse re-enters the window, the
-button is released, or the end of the listbox is reached.
-
-=item [4]
-
-Mouse button 2 may be used for scanning.
-If it is pressed and dragged over the listbox, the contents of
-the listbox drag at high speed in the direction the mouse moves.
-
-=item [5]
-
-If the Up or Down key is pressed, the location cursor (active
-element) moves up or down one element.
-If the selection mode is B<browse> or B<extended> then the
-new active element is also selected and all other elements are
-deselected.
-In B<extended> mode the new active element becomes the
-selection anchor.
-
-=item [6]
-
-In B<extended> mode, Shift-Up and Shift-Down move the location
-cursor (active element) up or down one element and also extend
-the selection to that element in a fashion similar to dragging
-with mouse button 1.
-
-=item [7]
-
-The Left and Right keys scroll the listbox view left and right
-by the width of the character B<0>.
-Control-Left and Control-Right scroll the listbox view left and
-right by the width of the window.
-Control-Prior and Control-Next also scroll left and right by
-the width of the window.
-
-=item [8]
-
-The Prior and Next keys scroll the listbox view up and down
-by one page (the height of the window).
-
-=item [9]
-
-The Home and End keys scroll the listbox horizontally to
-the left and right edges, respectively.
-
-=item [10]
-
-Control-Home sets the location cursor to the the first element in
-the listbox, selects that element, and deselects everything else
-in the listbox.
-
-=item [11]
-
-Control-End sets the location cursor to the the last element in
-the listbox, selects that element, and deselects everything else
-in the listbox.
-
-=item [12]
-
-In B<extended> mode, Control-Shift-Home extends the selection
-to the first element in the listbox and Control-Shift-End extends
-the selection to the last element.
-
-=item [13]
-
-In B<multiple> mode, Control-Shift-Home moves the location cursor
-to the first element in the listbox and Control-Shift-End moves
-the location cursor to the last element.
-
-=item [14]
-
-The space and Select keys make a selection at the location cursor
-(active element) just as if mouse button 1 had been pressed over
-this element.
-
-=item [15]
-
-In B<extended> mode, Control-Shift-space and Shift-Select
-extend the selection to the active element just as if button 1
-had been pressed with the Shift key down.
-
-=item [16]
-
-In B<extended> mode, the Escape key cancels the most recent
-selection and restores all the elements in the selected range
-to their previous selection state.
-
-=item [17]
-
-Control-slash selects everything in the widget, except in
-B<single> and B<browse> modes, in which case it selects
-the active element and deselects everything else.
-
-=item [18]
-
-Control-backslash deselects everything in the widget, except in
-B<browse> mode where it has no effect.
-
-=item [19]
-
-The F16 key (labelled Copy on many Sun workstations) or Meta-w
-copies the selection in the widget to the clipboard, if there is
-a selection.
-
-The behavior of listboxes can be changed by defining new bindings for
-individual widgets or by redefining the class bindings.
-
-=back
-
-=head1 TIED INTERFACE
-
-The Tk::Listbox widget can also be tied to a scalar or array variable, with
-different behaviour depending on the variable type, with the following
-tie commands:
-
- use Tk;
-
- my ( @array, $scalar, $other );
- my %options = ( ReturnType => "index" );
-
- my $MW = MainWindow->new();
- my $lbox = $MW->Listbox()->pack();
-
- my @list = ( "a", "b", "c", "d", "e", "f" );
- $lbox->insert('end', @list );
-
- tie @array, "Tk::Listbox", $lbox
- tie $scalar, "Tk::Listbox", $lbox;
- tie $other, "Tk::Listbox", $lbox, %options;
-
-currently only one modifier is implemented, a 3 way flag for tied scalars
-"ReturnType" which can have values "element", "index" or "both". The default
-is "element".
-
-=over 4
-
-=item Tied Arrays
-
-If you tie an array to the Listbox you can manipulate the items currently
-contained by the box in the same manner as a normal array, e.g.
-
- print @array;
- push(@array, @list);
- my $popped = pop(@array);
- my $shifted = shift(@array);
- unshift(@array, @list);
- delete $array[$index];
- print $string if exists $array[$i];
- @array = ();
- splice @array, $offset, $length, @list
-
-The delete function is implemented slightly differently from the standard
-array implementation. Instead of setting the element at that index to undef
-it instead physically removes it from the Listbox. This has the effect of
-changing the array indices, so for instance if you had a list on non-continuous
-indices you wish to remove from the Listbox you should reverse sort the list
-and then apply the delete function, e.g.
-
- my @list = ( 1, 2, 4, 12, 20 );
- my @remove = reverse sort { $a <=> $b } @list;
- delete @array[@remove];
-
-would safely remove indices 20, 12, 4, 2 and 1 from the Listbox without
-problems. It should also be noted that a similar warning applies to the
-splice function (which would normally be used in this context to perform
-the same job).
-
-
-=item Tied Scalars
-
-Unlike tied arrays, if you tie a scalar to the Listbox you can retrieve the
-currently selected elements in the box as an array referenced by the scalar,
-for instance
-
- my @list = ( "a", "b", "c", "d", "e", "f" );
- $lbox->insert('end', sort @list );
- $lbox->selectionSet(1);
-
-inserts @list as elements in an already existing listbox and selects the
-element at index 1, which is "b". If we then
-
- print @$selected;
-
-this will return the currently selected elements, in this case "b".
-
-However, if the "ReturnType" arguement is passed when tying the Listbox to the
-scalar with value "index" then the indices of the selected elements will be
-returned instead of the elements themselves, ie in this case "1". This can be
-useful when manipulating both contents and selected elements in the Listbox at
-the same time.
-
-Importantly, if a value "both" is given the scalar will not be tied to an
-array, but instead to a hash, with keys being the indices and values being
-the elements at those indices
-
-You can also manipulate the selected items using the scalar. Equating the
-scalar to an array reference will select any elements that match elements
-in the Listbox, non-matching array items are ignored, e.g.
-
- my @list = ( "a", "b", "c", "d", "e", "f" );
- $lbox->insert('end', sort @list );
- $lbox->selectionSet(1);
-
-would insert the array @list into an already existing Listbox and select
-element at index 1, i.e. "b"
-
- @array = ( "a", "b", "f" );
- $selected = \@array;
-
-would select elements "a", "b" and "f" in the Listbox.
-
-Again, if the "index" we indicate we want to use indices in the options hash
-then the indices are use instead of elements, e.g.
-
- @array = ( 0, 1, 5 );
- $selected = \@array;
-
-would have the same effect, selecting elements "a", "b" and "f" if the
-$selected variable was tied with %options = ( ReturnType => "index" ).
-
-If we are returning "both", i.e. the tied scalar points to a hash, both key and
-value must match, e.g.
-
- %hash = ( 0 => "a", 1 => "b", 5 => "f" );
- $selected = \%hash;
-
-would have the same effect as the previous examples.
-
-It should be noted that, despite being a reference to an array (or possibly a has), you still can not copy the tied variable without it being untied, instead
-you must pass a reference to the tied scalar between subroutines.
-
-=back
-
-=head1 KEYWORDS
-
-listbox, widget, tied
-
-=head1 SEE ALSO
-
-L<Tk::HList>, L<Tk::TextList>.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/MainWindow.pod b/Master/tlpkg/tlperl/lib/Tk/MainWindow.pod
deleted file mode 100644
index 565658adc1d..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/MainWindow.pod
+++ /dev/null
@@ -1,85 +0,0 @@
-
-=head1 NAME
-
-Tk::MainWindow - Root widget of a widget tree
-
-=for pm Tk/MainWindow.pm
-
-=for category Creating and Configuring Widgets
-
-=head1 SYNOPSIS
-
- use Tk;
-
- my $mw = MainWindow->new( ... options ... );
-
- my $this = $mw->ThisWidget -> pack ;
- my $that = $mw->ThatWidget;
- ...
-
- MainLoop;
-
-=head1 DESCRIPTION
-
-Perl/Tk applications (which have windows associated with them) create
-one or more B<MainWindow>s which act as the containers and parents
-of the other widgets.
-
-B<Tk::MainWindow> is a special kind of L<Toplevel|Tk::Toplevel> widget. It is
-the root of a widget tree. Therefore C<$mw-E<gt>Parent> returns
-C<undef>.
-
-The default title of a MainWindow is the basename of the script
-(actually the Class name used for options lookup, i.e. with basename
-with inital caps) or 'Ptk' as the fallback value. If more than one MainWindow is created
-or several instances of the script are running at the same time the
-string C<" #n"> is appended where the number C<n> is set to get
-a unique value.
-
-Unlike the standard Tcl/Tk's wish, perl/Tk allows you to create
-several MainWindows. When the I<last> B<MainWindow> is destroyed
-the Tk eventloop exits (the eventloop is entered with the call of
-C<MainLoop>). Various resources (bindings, fonts, images, colors) are
-maintained or cached for each MainWindow, so each MainWindow consumes more
-resources than a Toplevel. However multiple MainWindows can make sense when
-the user can destroy them independently.
-
-=head1 METHODS
-
-You can apply all methods that a L<Toplevel|Tk::Toplevel> widget accepts.
-
-The method I<$w>-E<gt>B<MainWindow> applied to any widget will return the
-B<MainWindow> to which the widget belongs (the MainWindow belongs to itself).
-
-=head1 MISSING
-
-Documentation is incomplete.
-Here are I<some> missing items that should be explained in
-more detail:
-
-=over 4
-
-=item *
-
-The new mechanism for MainWindows is slightly different to
-other widgets.
-
-=item *
-
-There no explanation about what resources are bound
-to a MainWindow (e.g., ClassInit done per MainWindow)
-
-=item *
-
-Passing of command line options to override or augment
-arguments of the C<new> method (see L<Tk::CmdLine>).
-
-=back
-
-=head1 SEE ALSO
-
-L<Tk::Toplevel|Tk::Toplevel>
-L<Tk::CmdLine|Tk::CmdLine>
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Menu.pod b/Master/tlpkg/tlperl/lib/Tk/Menu.pod
deleted file mode 100644
index b7414e57510..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Menu.pod
+++ /dev/null
@@ -1,876 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1997 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Menu - Create and manipulate Menu widgets
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
-S< >I<$menu> = I<$parent>-E<gt>B<Menu>(?I<options>?);
-
-=head1 STANDARD OPTIONS
-
-B<-activebackground> B<-background> B<-disabledforeground> B<-relief>
-B<-activeborderwidth> B<-borderwidth> B<-font> B<-takefocus>
-B<-activeforeground> B<-cursor> B<-foreground>
-
-See L<Tk::options> for details of the standard options.
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<postCommand>
-
-=item Class: B<Command>
-
-=item Switch: B<-postcommand>
-
-If this option is specified then it provides a L<callback|Tk::callbacks> to execute
-each time the menu is posted. The callback is invoked by the B<post>
-method before posting the menu. Note that in 8.0 on Macintosh
-and Windows, all commands in a menu systems are executed before any
-are posted. This is due to the limitations in the individual platforms'
-menu managers.
-
-=item Name: B<selectColor>
-
-=item Class: B<Background>
-
-=item Switch: B<-selectcolor>
-
-For menu entries that are check buttons or radio buttons, this option
-specifies the color to display in the indicator when the check button
-or radio button is selected.
-
-=item Name: B<tearOff>
-
-=item Class: B<TearOff>
-
-=item Switch: B<-tearoff>
-
-This option must have a proper boolean value, which specifies
-whether or not the menu should include a tear-off entry at the
-top. If so, it will exist as entry 0 of the menu and the other
-entries will number starting at 1. The default
-menu bindings arrange for the menu to be torn off when the tear-off
-entry is invoked.
-
-=item Name: B<tearOffCommand>
-
-=item Class: B<TearOffCommand>
-
-=item Switch: B<-tearoffcommand>
-
-If this option has a non-empty value, then it specifies a L<perl/Tk callback|Tk::callbacks>
-to invoke whenever the menu is torn off. The actual command will
-consist of the value of this option, followed by a space, followed
-by the name of the menu window, followed by a space, followed by
-the name of the name of the torn off menu window. For example, if
-the option's is ``B<a b>'' and menu B<.x.y> is torn off to
-create a new menu B<.x.tearoff1>, then the command
-``B<a b .x.y .x.tearoff1>'' will be invoked.
-
-=item Name: B<title>
-
-=item Class: B<Title>
-
-=item Switch: B<-title>
-
-The string will be used to title the window created when this menu is
-torn off. If the title is NULL, then the window will have the title
-of the menubutton or the text of the cascade item from which this menu
-was invoked.
-
-=item Name: B<type>
-
-=item Class: B<Type>
-
-=item Switch: B<-type>
-
-This option can be one of B<menubar>, B<tearoff>, or
-B<normal>, and is set when the menu is created. While the string
-returned by the configuration database will change if this option is
-changed, this does not affect the menu widget's behavior. This is used
-by the cloning mechanism and is not normally set outside of the Tk
-library.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Menu> method creates a new top-level window (given
-by the $widget argument) and makes it into a menu widget.
-Additional
-options, described above, may be specified on the command line
-or in the option database
-to configure aspects of the menu such as its colors and font.
-The B<menu> command returns its
-$widget argument. At the time this command is invoked,
-there must not exist a window named $widget, but
-$widget's parent must exist.
-
-A menu is a widget that displays a collection of one-line entries arranged
-in one or more columns. There exist several different types of entries,
-each with different properties. Entries of different types may be
-combined in a single menu. Menu entries are not the same as
-entry widgets. In fact, menu entries are not even distinct widgets;
-the entire menu is one widget.
-
-Menu entries are displayed with up to three separate fields.
-The main field is a label in the form of a text string,
-a bitmap, or an image, controlled by the B<-label>,
-B<-bitmap>, and B<-image> options for the entry.
-If the B<-accelerator> option is specified for an entry then a second
-textual field is displayed to the right of the label. The accelerator
-typically describes a keystroke sequence that may be typed in the
-application to cause the same result as invoking the menu entry.
-The third field is an I<indicator>. The indicator is present only for
-checkbutton or radiobutton entries. It indicates whether the entry
-is selected or not, and is displayed to the left of the entry's
-string.
-
-In normal use, an entry becomes active (displays itself differently)
-whenever the mouse pointer is over the entry. If a mouse
-button is released over the entry then the entry is I<invoked>.
-The effect of invocation is different for each type of entry;
-these effects are described below in the sections on individual
-entries.
-
-Entries may be I<disabled>, which causes their labels
-and accelerators to be displayed
-with dimmer colors.
-The default menu bindings will not allow
-a disabled entry to be activated or invoked.
-Disabled entries may be re-enabled, at which point it becomes
-possible to activate and invoke them again.
-
-Whenever a menu's active entry is changed, a E<lt>E<lt>MenuSelectE<gt>E<gt> virtual
-event is sent to the menu. The active item can then be queried from
-the menu, and an action can be taken, such as setting
-context-sensitive help text for the entry.
-
-=head2 COMMAND ENTRIES
-
-The most common kind of menu entry is a command entry, which
-behaves much like a button widget. When a command entry is
-invoked, a callback is executed. The callback
-is specified with the B<-command> option.
-
-=head2 SEPARATOR ENTRIES
-
-A separator is an entry that is displayed as a horizontal dividing
-line. A separator may not be activated or invoked, and it has
-no behavior other than its display appearance.
-
-=head2 CHECKBUTTON ENTRIES
-
-A checkbutton menu entry behaves much like a checkbutton widget.
-When it is invoked it toggles back and forth between the selected
-and deselected states. When the entry is selected, a particular
-value is stored in a particular global variable (as determined by
-the B<-onvalue> and B<-variable> options for the entry); when
-the entry is deselected another value (determined by the
-B<-offvalue> option) is stored in the global variable.
-An indicator box is displayed to the left of the label in a checkbutton
-entry. If the entry is selected then the indicator's center is displayed
-in the color given by the B<-selectcolor> option for the entry;
-otherwise the indicator's center is displayed in the background color for
-the menu. If a B<-command> option is specified for a checkbutton
-entry, then its value is evaluated each time the entry
-is invoked; this happens after toggling the entry's
-selected state.
-
-=head2 RADIOBUTTON ENTRIES
-
-A radiobutton menu entry behaves much like a radiobutton widget.
-Radiobutton entries are organized in groups of which only one
-entry may be selected at a time. Whenever a particular entry
-becomes selected it stores a particular value into a particular
-global variable (as determined by the B<-value> and
-B<-variable> options for the entry). This action
-causes any previously-selected entry in the same group
-to deselect itself.
-Once an entry has become selected, any change to the entry's
-associated variable will cause the entry to deselect itself.
-Grouping of radiobutton entries is determined by their
-associated variables: if two entries have the same associated
-variable then they are in the same group.
-An indicator diamond is displayed to the left of the label in each
-radiobutton entry. If the entry is selected then the indicator's
-center is displayed in the color given by the B<-selectcolor> option
-for the entry;
-otherwise the indicator's center is displayed in the background color for
-the menu. If a B<-command> option is specified for a radiobutton
-entry, then its value is evaluated each time the entry
-is invoked; this happens after selecting the entry.
-
-=head2 CASCADE ENTRIES
-
-A cascade entry is one with an associated menu (determined
-by the B<-menu> option). Cascade entries allow the construction
-of cascading menus.
-The B<postcascade> method can be used to post and unpost
-the associated menu just next to of the cascade entry.
-The associated menu must be a child of the menu containing
-the cascade entry (this is needed in order for menu traversal to
-work correctly).
-
-A cascade entry posts its associated menu by invoking
-
-=over 4
-
-I<$menu>-E<gt>B<post>(I<x,y>)
-
-=back
-
-where I<menu> is the path name of the associated menu, and I<x>
-and I<y> are the root-window coordinates of the upper-right
-corner of the cascade entry.
-On Unix, the lower-level menu is unposted by executing
-
-=over 4
-
-I<$menu>-E<gt>B<unpost>
-
-=back
-
-where I<menu> is the name of the associated menu.
-On other platforms, the platform's native code takes care of unposting the
-menu.
-
-If a B<-command> option is specified for a cascade entry then it is
-evaluated whenever the entry is invoked. This is not supported on Windows.
-
-=head2 TEAR-OFF ENTRIES
-
-A tear-off entry appears at the top of the menu if enabled with the
-B<tearOff> option. It is not like other menu entries in that
-it cannot be created with the B<add> method and
-cannot be deleted with the B<delete> method.
-When a tear-off entry is created it appears as a dashed line at
-the top of the menu. Under the default bindings, invoking the
-tear-off entry causes a torn-off copy to be made of the menu and
-all of its submenus.
-
-=head2 MENUBARS
-
-Any menu can be set as a menubar for a toplevel window (see the
-L<Toplevel|Tk::Toplevel> constructor for syntax). On the Macintosh, whenever the
-toplevel is in front, this menu's cascade items will appear in the
-menubar across the top of the main monitor. On Windows and Unix, this
-menu's items will be displayed in a menubar accross the top of the
-window. These menus will behave according to the interface guidelines
-of their platforms. For every menu set as a menubar, a clone menu is
-made. See L<"CLONES"> for more information.
-
-As noted, menubars may behave differently on different platforms. One
-example of this concerns the handling of checkbuttons and radiobuttons
-within the menu. While it is permitted to put these menu elements on
-menubars, they may not be drawn with indicators on some platforms, due
-to system restrictions.
-
-=head2 SPECIAL MENUS IN MENUBARS
-
-Certain menus in a menubar will be treated specially. On the Macintosh,
-access to the special Apple and Help menus is provided. On Windows,
-access to the Windows System menu in each window is provided. On X Windows,
-a special right-justified help menu is provided. In all cases, these
-menus must be created with the command name of the menubar menu concatenated
-with the special name. So for a menubar named .menubar, on the Macintosh,
-the special menus would be .menubar.apple and .menubar.help; on Windows,
-the special menu would be .menubar.system; on X Windows, the help
-menu would be .menubar.help.
-
-When Tk sees an Apple menu on the Macintosh, that menu's contents make
-up the first items of the Apple menu on the screen whenever the window
-containing the menubar is in front. The menu is the
-first one that the user sees and has a title which is an Apple logo.
-After all of the Tk-defined items, the menu will have a separator,
-followed by all of the items in the user's Apple Menu Items folder.
-Since the System uses a different menu definition procedure for
-the Apple menu than Tk uses for its menus, and the system APIs do
-not fully support everything Tk tries to do, the menu item will only
-have its text displayed. No font attributes, images, bitmaps, or colors
-will be displayed. In addition, a menu with a tearoff item will have
-the tearoff item displayed as "(TearOff)".
-
-When Tk see a Help menu on the Macintosh, the menu's contents are
-appended to the standard help menu on the right of the user's menubar
-whenever the user's menubar is in front. The first items in the menu
-are provided by Apple. Similar to the Apple Menu, cusomization in this
-menu is limited to what the system provides.
-
-When Tk sees a System menu on Windows, its items are appended to the
-system menu that the menubar is attached to. This menu has an icon
-representing a spacebar, and can be invoked with the mouse or by typing
-Alt+Spacebar. Due to limitations in the Windows API, any font changes,
-colors, images, bitmaps, or tearoff images will not appear in the
-system menu.
-
-When Tk see a Help menu on X Windows, the menu is moved to be last in
-the menubar and is right justified.
-
-=head2 CLONES
-
-When a menu is set as a menubar for a toplevel window, or when a menu
-is torn off, a clone of the menu is made. This clone is a menu widget
-in its own right, but it is a child of the original. Changes in the
-configuration of the original are reflected in the
-clone. Additionally, any cascades that are pointed to are also cloned
-so that menu traversal will work right. Clones are destroyed when
-either the tearoff or menubar goes away, or when the original menu is
-destroyed.
-
-=head2 WIDGET METHODS
-
-The B<Menu> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class, and the L<Tk::Wm|Tk::Wm> class.
-
-Many of the methods for a menu take as one argument an
-indicator of which entry of the menu to operate on. These
-indicators are called I<index>es and may be specified in
-any of the following forms:
-
-=over 4
-
-=item I<number>
-
-Specifies the entry numerically, where 0 corresponds
-to the top-most entry of the menu, 1 to the entry below it, and
-so on.
-
-=item B<active>
-
-Indicates the entry that is currently active. If no entry is
-active then this form is equivalent to B<none>. This form may
-not be abbreviated.
-
-=item B<end>
-
-Indicates the bottommost entry in the menu. If there are no
-entries in the menu then this form is equivalent to B<none>.
-This form may not be abbreviated.
-
-=item B<last>
-
-Same as B<end>.
-
-=item B<none>
-
-Indicates ``no entry at all''; this is used most commonly with
-the B<activate> option to deactivate all the entries in the
-menu. In most cases the specification of B<none> causes
-nothing to happen in the method.
-This form may not be abbreviated.
-
-=item B<@>I<number>
-
-In this form, I<number> is treated as a y-coordinate in the
-menu's window; the entry closest to that y-coordinate is used.
-For example, ``B<@0>'' indicates the top-most entry in the
-window.
-
-=item I<pattern>
-
-If the index doesn't satisfy one of the above forms then this
-form is used. I<Pattern> is pattern-matched against the label of
-each entry in the menu, in order from the top down, until a
-matching entry is found.
-(In perl/Tk the matching is under review, but exact match
-should work.)
-
-=back
-
-The following methods are possible for menu widgets:
-
-=over 4
-
-=item I<$menu>-E<gt>B<activate>(I<index>)
-
-Change the state of the entry indicated by I<index> to B<active>
-and redisplay it using its active colors.
-Any previously-active entry is deactivated. If I<index>
-is specified as B<none>, or if the specified entry is
-disabled, then the menu ends up with no active entry.
-Returns an empty string.
-
-=item I<$menu>-E<gt>B<add>(I<type, >?I<option, value, option, value, ...>?)
-
-Add a new entry to the bottom of the menu. The new entry's type
-is given by I<type> and must be one of B<cascade>,
-B<checkbutton>, B<command>, B<radiobutton>, or B<separator>,
-or a unique abbreviation of one of the above. If additional arguments
-are present, they specify any of the following options:
-
-=over 8
-
-=item B<-activebackground> =E<gt> I<value>
-
-Specifies a background color to use for displaying this entry when it
-is active.
-If this option is specified as an empty string (the default), then the
-B<activeBackground> option for the overall menu is used.
-If the B<$Tk::strictMotif> variable has been set to request strict
-Motif compliance, then this option is ignored and the B<-background>
-option is used in its place.
-This option is not available for separator or tear-off entries.
-
-=item B<-activeforeground> =E<gt> I<value>
-
-Specifies a foreground color to use for displaying this entry when it
-is active.
-If this option is specified as an empty string (the default), then the
-B<activeForeground> option for the overall menu is used.
-This option is not available for separator or tear-off entries.
-
-=item B<-accelerator> =E<gt> I<value>
-
-Specifies a string to display at the right side of the menu entry.
-Normally describes an accelerator keystroke sequence that may be
-typed to invoke the same function as the menu entry. This option
-is not available for separator or tear-off entries.
-
-=item B<-background> =E<gt> I<value>
-
-Specifies a background color to use for displaying this entry when it
-is in the normal state (neither active nor disabled).
-If this option is specified as an empty string (the default), then the
-B<background> option for the overall menu is used.
-This option is not available for separator or tear-off entries.
-
-=item B<-bitmap> =E<gt> I<value>
-
-Specifies a bitmap to display in the menu instead of a textual
-label, in any of the forms accepted by B<Tk_GetBitmap>.
-This option overrides the B<-label> option but may be reset
-to an empty string to enable a textual label to be displayed.
-If a B<-image> option has been specified, it overrides
-B<-bitmap>.
-This option is not available for separator or tear-off entries.
-
-=item B<-columnbreak> =E<gt> I<value>
-
-When this option is zero, the appears below the previous entry. When
-this option is one, the menu appears at the top of a new column in the
-menu.
-
-=item B<-compound> =E<gt> I<value>
-
-Specifies whether the button should display both an image and text,
-and if so, where the image should be placed relative to the text.
-Valid values for this option are B<bottom>, B<center>, B<left>,
-B<none>, B<right> and B<top>. The default value is B<none>, meaning
-that the button will display either an image or text, depending on the
-values of the -image and -bitmap options.
-
-=item B<-command> =E<gt> I<value>
-
-For command, checkbutton, and radiobutton entries, specifies a
-callback to execute when the menu entry is invoked.
-For cascade entries, specifies a callback to execute
-when the entry is activated (i.e. just before its submenu is
-posted).
-Not available for separator or tear-off entries.
-
-=item B<-font> =E<gt> I<value>
-
-Specifies the font to use when drawing the label or accelerator
-string in this entry.
-If this option is specified as an empty string (the default) then
-the B<font> option for the overall menu is used.
-This option is not available for separator or tear-off entries.
-
-=item B<-foreground> =E<gt> I<value>
-
-Specifies a foreground color to use for displaying this entry when it
-is in the normal state (neither active nor disabled).
-If this option is specified as an empty string (the default), then the
-B<foreground> option for the overall menu is used.
-This option is not available for separator or tear-off entries.
-
-=item B<-hidemargin> =E<gt> I<value>
-
-Specifies whether the standard margins should be drawn for this menu
-entry. This is useful when creating palette with images in them, i.e.,
-color palettes, pattern palettes, etc. 1 indicates that the margin for
-the entry is hidden; 0 means that the margin is used.
-
-=item B<-image> =E<gt> I<value>
-
-Specifies an image to display in the menu instead of a text string
-or bitmap
-The image must have been created by some previous invocation of
-B<image create>.
-This option overrides the B<-label> and B<-bitmap> options
-but may be reset to an empty string to enable a textual or
-bitmap label to be displayed.
-This option is not available for separator or tear-off entries.
-
-=item B<-indicatoron> =E<gt> I<value>
-
-Available only for checkbutton and radiobutton entries.
-I<Value> is a boolean that determines whether or not the
-indicator should be displayed.
-
-=item B<-label> =E<gt> I<value>
-
-Specifies a string to display as an identifying label in the menu
-entry. Not available for separator or tear-off entries.
-
-=item B<-menu> =E<gt> I<value>
-
-Available only for cascade entries. Specifies the path name of
-the submenu associated with this entry.
-The submenu must be a child of the menu.
-
-=item B<-offvalue> =E<gt> I<value>
-
-Available only for checkbutton entries. Specifies the value to
-store in the entry's associated variable when the entry is
-deselected.
-
-=item B<-onvalue> =E<gt> I<value>
-
-Available only for checkbutton entries. Specifies the value to
-store in the entry's associated variable when the entry is selected.
-
-=item B<-selectcolor> =E<gt> I<value>
-
-Available only for checkbutton and radiobutton entries.
-Specifies the color to display in the indicator when the entry is
-selected.
-If the value is an empty string (the default) then the B<selectColor>
-option for the menu determines the indicator color.
-
-=item B<-selectimage> =E<gt> I<value>
-
-Available only for checkbutton and radiobutton entries.
-Specifies an image to display in the entry (in place of
-the B<-image> option) when it is selected.
-I<Value> is the name of an image, which must have been created
-by some previous invocation of B<image create>.
-This option is ignored unless the B<-image> option has
-been specified.
-
-=item B<-state> =E<gt> I<value>
-
-Specifies one of three states for the entry: B<normal>, B<active>,
-or B<disabled>. In normal state the entry is displayed using the
-B<foreground> option for the menu and the B<background>
-option from the entry or the menu.
-The active state is typically used when the pointer is over the entry.
-In active state the entry is displayed using the B<activeForeground>
-option for the menu along with the B<activebackground> option from
-the entry. Disabled state means that the entry
-should be insensitive: the default bindings will refuse to activate
-or invoke the entry.
-In this state the entry is displayed according to the
-B<disabledForeground> option for the menu and the
-B<background> option from the entry.
-This option is not available for separator entries.
-
-=item B<-underline> =E<gt> I<value>
-
-Specifies the integer index of a character to underline in the entry.
-This option is also queried by the default bindings and used to
-implement keyboard traversal.
-0 corresponds to the first character of the text displayed in the entry,
-1 to the next character, and so on.
-If a bitmap or image is displayed in the entry then this option is ignored.
-This option is not available for separator or tear-off entries.
-
-=item B<-value> =E<gt> I<value>
-
-Available only for radiobutton entries. Specifies the value to
-store in the entry's associated variable when the entry is selected.
-If an empty string is specified, then the B<-label> option
-for the entry as the value to store in the variable.
-
-=item B<-variable> =E<gt> I<value>
-
-Available only for checkbutton and radiobutton entries. Specifies
-the name of a global value to set when the entry is selected.
-For checkbutton entries the variable is also set when the entry
-is deselected. For radiobutton entries, changing the variable
-causes the currently-selected entry to deselect itself.
-
-=back
-
-The B<add> method returns an empty string.
-
-=item I<$menu>-E<gt>B<clone>(I<$parent> ?, I<cloneType?>)
-
-Makes a clone of the current menu as a child of I<$parent>. This clone
-is a menu in its own right, but any changes to the clone are
-propogated to the original menu and vice versa. I<cloneType> can be
-B<normal>, B<menubar>, or B<tearoff>. Should not normally be
-called outside of the Tk library. See L<"CLONES"> for
-more information.
-
-=item I<$menu>-E<gt>B<delete>(I<index1>?, I<index2>?)
-
-Delete all of the menu entries between I<index1> and
-I<index2> inclusive.
-If I<index2> is omitted then it defaults to I<index1>.
-Attempts to delete a tear-off menu entry are ignored (instead, you
-should change the B<tearOff> option to remove the tear-off entry).
-
-=item I<$menu>-E<gt>B<entrycget>(I<index, option>)
-
-Returns the current value of a configuration option for
-the entry given by I<index>.
-I<Option> may have any of the values accepted by the B<add>
-method.
-
-=item I<$menu>-E<gt>B<entryconfigure>(I<index> ?,I<options>?)
-
-This method is similar to the B<configure> method, except that
-it applies to the options for an individual entry, whereas B<configure>
-applies to the options for the menu as a whole.
-I<Options> may have any of the values accepted by the B<add>
-method. If I<options> are specified, options are modified
-as indicated
-in the method call and the method returns an empty string.
-If no I<options> are specified, returns a list describing
-the current options for entry I<index> (see L<Tk::options> for
-information on the format of this list).
-
-=item I<$menu>-E<gt>B<index>(I<index>)
-
-Returns the numerical index corresponding to I<index>, or
-B<none> if I<index> was specified as B<none>.
-
-=item I<$menu>-E<gt>B<insert>(I<index, type>?, I<-option>=E<gt>I<value>, ...?)
-
-Same as the B<add> method except that it inserts the new
-entry just before the entry given by I<index>, instead of appending
-to the end of the menu. The I<type>, I<-option>, and I<value>
-arguments have the same interpretation as for the B<add> widget
-method. It is not possible to insert new menu entries before the
-tear-off entry, if the menu has one.
-
-=item I<$menu>-E<gt>B<invoke>(I<index>)
-
-Invoke the action of the menu entry. See the sections on the
-individual entries above for details on what happens. If the
-menu entry is disabled then nothing happens. If the
-entry has a callback associated with it then the result of that
-callback is returned as the result of the B<invoke> widget
-method. Otherwise the result is an empty string. Note: invoking
-a menu entry does not automatically unpost the menu; the default
-bindings normally take care of this before invoking the B<invoke>
-method.
-
-=item I<$menu>-E<gt>B<post>(I<x, y>)
-
-Arrange for the menu to be displayed on the screen at the root-window
-coordinates given by I<x> and I<y>. These coordinates are
-adjusted if necessary to guarantee that the entire menu is visible on
-the screen. This method normally returns an empty string.
-If the B<postCommand> option has been specified, then its value is
-executed before posting the menu and the result of
-that callback is returned as the result of the B<post> widget
-method.
-If an error returns while executing the method, then the error is
-returned without posting the menu.
-
-=item I<$menu>-E<gt>B<postcascade>(I<index>)
-
-Posts the submenu associated with the cascade entry given by
-I<index>, and unposts any previously posted submenu.
-If I<index> doesn't correspond to a cascade entry,
-or if I<$menu> isn't posted,
-the method has no effect except to unpost any currently posted
-submenu.
-
-=item I<$menu>-E<gt>B<type>(I<index>)
-
-Returns the type of the menu entry given by I<index>.
-This is the I<type> argument passed to the B<add> widget
-method when the entry was created, such as B<command>
-or B<separator>, or B<tearoff> for a tear-off entry.
-
-=item I<$menu>-E<gt>B<unpost>
-
-Unmap the window so that it is no longer displayed. If a
-lower-level cascaded menu is posted, unpost that menu. Returns an
-empty string. This method does not work on Windows and the
-Macintosh, as those platforms have their own way of unposting menus.
-
-=item I<$menu>-E<gt>B<yposition>(I<index>)
-
-Returns a decimal string giving the y-coordinate within the menu
-window of the topmost pixel in the entry specified by I<index>.
-
-=back
-
-=head1 MENU CONFIGURATIONS
-
-The default bindings support four different ways of using menus:
-
-=over 4
-
-=item B<Pulldown Menus in Menubar>
-
-This is the most command case. You create a menu widget that will become the
-menu bar. You then add cascade entries to this menu, specifying the
-pull down menus you wish to use in your menu bar. You then create all
-of the pulldowns. Once you have done this, specify the menu using the
-B<-menu> option of the toplevel's method. See the
-B<toplevel> manual entry for details.
-
-=item B<Pulldown Menus in Menu Buttons>
-
-This is the compatable way to do menu bars. You create one menubutton
-widget for each top-level menu, and typically you arrange a series of
-menubuttons in a row in a menubar window. You also create the top-level menus
-and any cascaded submenus, and tie them together with B<-menu>
-options in menubuttons and cascade menu entries. The top-level menu must
-be a child of the menubutton, and each submenu must be a child of the
-menu that refers to it. Once you have done this, the default bindings
-will allow users to traverse and invoke the tree of menus via its
-menubutton; see the B<menubutton> documentation for details.
-
-=item B<Popup Menus>
-
-Popup menus typically post in response to a mouse button press or
-keystroke. You create the popup menus and any cascaded submenus,
-then you call the B<Post> method at the appropriate time
-to post the top-level menu.
-
-I<$menu>-E<gt>B<Post>(I<$x>,I<$y>?,I<$entry>?)
-
-I<$x> and I<$y> are the root window coordinates at which the I<$menu>
-will be displayed. If I<$entry> is specified then that entry is centred
-on that point, otherwise the top-left corner of the I<$menu> is placed
-at that point.
-
-B<Menu> also inherits methods from L<Tk::Wm> and so the method
-B<Popup> can be used to position menu relative to other windows, the
-mouse cursor or the screen.
-
-=item B<Option Menus>
-
-An option menu consists of a menubutton with an associated menu
-that allows you to select one of several values. The current value
-is displayed in the menubutton and is also stored in a global
-variable. Use the L<Tk::Optionmenu> class to create option
-menubuttons and their menus.
-
-=item B<Torn-off Menus>
-
-You create a torn-off menu by invoking the tear-off entry at
-the top of an existing menu. The default bindings will create a new menu
-that is a copy of the original menu and leave it permanently
-posted as a top-level window. The torn-off menu behaves just
-the same as the original menu.
-
-=back
-
-=head1 DEFAULT BINDINGS
-
-Tk automatically creates class bindings for menus that give them
-the following default behavior:
-
-=over 4
-
-=item [1]
-
-When the mouse enters a menu, the entry underneath the mouse
-cursor activates; as the mouse moves around the menu, the active
-entry changes to track the mouse.
-
-=item [2]
-
-When the mouse leaves a menu all of the entries in the menu
-deactivate, except in the special case where the mouse moves from
-a menu to a cascaded submenu.
-
-=item [3]
-
-When a button is released over a menu, the active entry (if any) is invoked.
-The menu also unposts unless it is a torn-off menu.
-
-=item [4]
-
-The Space and Return keys invoke the active entry and
-unpost the menu.
-
-=item [5]
-
-If any of the entries in a menu have letters underlined with
-with B<-underline> option, then pressing one of the underlined
-letters (or its upper-case or lower-case equivalent) invokes that
-entry and unposts the menu.
-
-=item [6]
-
-The Escape key aborts a menu selection in progress without invoking any
-entry. It also unposts the menu unless it is a torn-off menu.
-
-=item [7]
-
-The Up and Down keys activate the next higher or lower entry
-in the menu. When one end of the menu is reached, the active
-entry wraps around to the other end.
-
-=item [8]
-
-The Left key moves to the next menu to the left.
-If the current menu is a cascaded submenu, then the submenu is
-unposted and the current menu entry becomes the cascade entry
-in the parent.
-If the current menu is a top-level menu posted from a
-menubutton, then the current menubutton is unposted and the
-next menubutton to the left is posted.
-Otherwise the key has no effect.
-The left-right order of menubuttons is determined by their stacking
-order: Tk assumes that the lowest menubutton (which by default
-is the first one created) is on the left.
-
-=item [9]
-
-The Right key moves to the next menu to the right.
-If the current entry is a cascade entry, then the submenu is
-posted and the current menu entry becomes the first entry
-in the submenu.
-Otherwise, if the current menu was posted from a
-menubutton, then the current menubutton is unposted and the
-next menubutton to the right is posted.
-
-Disabled menu entries are non-responsive: they don't activate and
-they ignore mouse button presses and releases.
-
-The behavior of menus can be changed by defining new bindings for
-individual widgets or by redefining the class bindings.
-
-=back
-
-=head1 BUGS
-
-At present it isn't possible to use the
-option database to specify values for the options to individual
-entries.
-
-=head1 SEE ALSO
-
-L<Tk::callbacks|Tk::callbacks>
-
-=head1 KEYWORDS
-
-menu, widget
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Menu/Item.pod b/Master/tlpkg/tlperl/lib/Tk/Menu/Item.pod
deleted file mode 100644
index dabaadb8a58..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Menu/Item.pod
+++ /dev/null
@@ -1,96 +0,0 @@
-
-=head1 NAME
-
-Tk::Menu::Item - Base class for Menu items
-
-=for pm Tk/Menu/Item.pm
-
-=for category Implementation
-
-=head1 SYNOPSIS
-
- require Tk::Menu::Item;
-
- my $but = $menu->Button(...);
- $but->configure(...);
- my $what = $but->cget();
-
- package Whatever;
- require Tk::Menu::Item;
- @ISA = qw(Tk::Menu::Item);
-
- sub PreInit
- {
- my ($class,$menu,$info) = @_;
- $info->{'-xxxxx'} = ...
- my $y = delete $info->{'-yyyy'};
- }
-
-=head1 DESCRIPTION
-
-Tk::Menu::Item is the base class from which Tk::Menu::Button,
-Tk::Menu::Cascade, Tk::Menu::Radiobutton and Tk::Menu::Checkbutton are derived.
-There is also a Tk::Menu::Separator.
-
-Constructors are declared so that $menu-E<gt>Button(...) etc. do what you would
-expect.
-
-The C<-label> option is pre-processed allowing ~ to be prefixed to the character
-to derive a C<-underline> value. Thus
-
- $menu->Button(-label => 'Goto ~Home',...)
-
- is equivalent to
-
- $menu->Button(-label => 'Goto Home', -underline => 6, ...)
-
-The C<Cascade> menu item creates a sub-menu and accepts
-these options:
-
-=over 4
-
-=item B<-menuitems>
-
-A list of items for the sub-menu.
-Within this list (which is also accepted by Menu and Menubutton) the first
-two elements of each item should be the "constructor" name and the label:
-
- -menuitems => [
- [Button => '~Quit', -command => [destroy => $mw]],
- [Checkbutton => '~Oil', -variable => \$oil],
- ]
-
-=item B<-postcommand>
-
-A callback to be invoked before posting the menu.
-
-=item B<-tearoff>
-
-Specifies whether sub-menu can be torn-off or not.
-
-=item B<-menuvar>
-
-Scalar reference that will be set to the newly-created sub-menu.
-
-=back
-
-The returned object is currently a blessed reference to an array of two items:
-the containing Menu and the 'label'.
-Methods C<configure> and C<cget> are mapped onto underlying C<entryconfigure>
-and C<entrycget>.
-
-The main purpose of the OO interface is to allow derived item classes to
-be defined which pre-set the options used to create a more basic item.
-
-=head1 BUGS
-
-This OO interface is very new. Using the label as the "key" is a problem
-for separaror items which don't have one. The alternative would be to
-use an index into the menu but that is a problem if items are deleted
-(or inserted other than at the end).
-
-There should probably be a PostInit entry point too, or a more widget like
-defered 'configure'.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Menubutton.pod b/Master/tlpkg/tlperl/lib/Tk/Menubutton.pod
deleted file mode 100644
index fcda3e958aa..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Menubutton.pod
+++ /dev/null
@@ -1,249 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1997 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Menubutton - Create and manipulate Menubutton widgets
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
-I<$menubutton> = I<$parent>-E<gt>B<Menubutton>(?I<options>?);
-
-=head1 STANDARD OPTIONS
-
-B<-activebackground> B<-cursor> B<-highlightthickness> B<-takefocus>
-B<-activeforeground> B<-disabledforeground> B<-image> B<-text>
-B<-anchor> B<-font> B<-justify> B<-textvariable>
-B<-background> B<-foreground> B<-padx> B<-underline>
-B<-bitmap> B<-highlightbackground> B<-pady> B<-wraplength>
-B<-borderwidth> B<-highlightcolor> B<-relief>
-
-See L<Tk::options> for details of the standard options.
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Command-Line Name: B<-compound>
-
-=item Database Name: B<compound>
-
-=item Database Class: B<Compound>
-
-Specifies whether the button should display both an image and text,
-and if so, where the image should be placed relative to the text.
-Valid values for this option are B<bottom>, B<center>, B<left>,
-B<none>, B<right> and B<top>. The default value is B<none>, meaning
-that the button will display either an image or text, depending on the
-values of the -image and -bitmap options.
-
-=item Name: B<direction>
-
-=item Class: B<Height>
-
-=item Switch: B<-direction>
-
-Specifies where the menu is going to be popup up. B<above> tries to
-pop the menu above the menubutton. B<below> tries to pop the menu
-below the menubutton. B<left> tries to pop the menu to the left of
-the menubutton. B<right> tries to pop the menu to the right of the
-menu button. B<flush> pops the menu directly over the menubutton.
-
-=item Name: B<height>
-
-=item Class: B<Height>
-
-=item Switch: B<-height>
-
-Specifies a desired height for the menubutton.
-If an image or bitmap is being displayed in the menubutton then the value is in
-screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>);
-for text it is in lines of text.
-If this option isn't specified, the menubutton's desired height is computed
-from the size of the image or bitmap or text being displayed in it.
-
-=item Name: B<indicatorOn>
-
-=item Class: B<IndicatorOn>
-
-=item Switch: B<-indicatoron>
-
-The value must be a proper boolean value. If it is true then
-a small indicator rectangle will be displayed on the right side
-of the menubutton and the default menu bindings will treat this
-as an option menubutton. If false then no indicator will be
-displayed.
-
-=item Name: B<menu>
-
-=item Class: B<MenuName>
-
-=item Switch: B<-menu>
-
-Specifies the path name of the menu associated with this menubutton.
-The menu must be a child of the menubutton.
-
-=item Name: B<state>
-
-=item Class: B<State>
-
-=item Switch: B<-state>
-
-Specifies one of three states for the menubutton: B<normal>, B<active>,
-or B<disabled>. In normal state the menubutton is displayed using the
-B<foreground> and B<background> options. The active state is
-typically used when the pointer is over the menubutton. In active state
-the menubutton is displayed using the B<activeForeground> and
-B<activeBackground> options. Disabled state means that the menubutton
-should be insensitive: the default bindings will refuse to activate
-the widget and will ignore mouse button presses.
-In this state the B<disabledForeground> and
-B<background> options determine how the button is displayed.
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-=item Switch: B<-width>
-
-Specifies a desired width for the menubutton.
-If an image or bitmap is being displayed in the menubutton then the value is in
-screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>);
-for text it is in characters.
-If this option isn't specified, the menubutton's desired width is computed
-from the size of the image or bitmap or text being displayed in it.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Menubutton> method creates a new window (given by the
-$widget argument) and makes it into a menubutton widget.
-Additional
-options, described above, may be specified on the command line
-or in the option database
-to configure aspects of the menubutton such as its colors, font,
-text, and initial relief. The B<menubutton> command returns its
-$widget argument. At the time this command is invoked,
-there must not exist a window named $widget, but
-$widget's parent must exist.
-
-A menubutton is a widget that displays a textual string, bitmap, or image
-and is associated with a menu widget.
-If text is displayed, it must all be in a single font, but it
-can occupy multiple lines on the screen (if it contains newlines
-or if wrapping occurs because of the B<wrapLength> option) and
-one of the characters may optionally be underlined using the
-B<underline> option. In normal usage, pressing
-mouse button 1 over the menubutton causes the associated menu to
-be posted just underneath the menubutton. If the mouse is moved over
-the menu before releasing the mouse button, the button release
-causes the underlying menu entry to be invoked. When the button
-is released, the menu is unposted.
-
-Menubuttons are typically organized into groups called menu bars
-that allow scanning:
-if the mouse button is pressed over one menubutton (causing it
-to post its menu) and the mouse is moved over another menubutton
-in the same menu bar without releasing the mouse button, then the
-menu of the first menubutton is unposted and the menu of the
-new menubutton is posted instead.
-
-There are several interactions between menubuttons and menus; see
-the B<menu> manual entry for information on various menu configurations,
-such as pulldown menus and option menus.
-
-=head1 WIDGET METHODS
-
-The B<Menubutton> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The B<menu> method returns the menu associated with the widget.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-=head1 DEFAULT BINDINGS
-
-Tk automatically creates class bindings for menubuttons that give them
-the following default behavior:
-
-=over 4
-
-=item [1]
-
-A menubutton activates whenever the mouse passes over it and deactivates
-whenever the mouse leaves it.
-
-=item [2]
-
-Pressing mouse button 1 over a menubutton posts the menubutton:
-its relief changes to raised and its associated menu is posted
-under the menubutton. If the mouse is dragged down into the menu
-with the button still down, and if the mouse button is then
-released over an entry in the menu, the menubutton is unposted
-and the menu entry is invoked.
-
-=item [3]
-
-If button 1 is pressed over a menubutton and then released over that
-menubutton, the menubutton stays posted: you can still move the mouse
-over the menu and click button 1 on an entry to invoke it.
-Once a menu entry has been invoked, the menubutton unposts itself.
-
-=item [4]
-
-If button 1 is pressed over a menubutton and then dragged over some
-other menubutton, the original menubutton unposts itself and the
-new menubutton posts.
-
-=item [5]
-
-If button 1 is pressed over a menubutton and released outside
-any menubutton or menu, the menubutton unposts without invoking
-any menu entry.
-
-=item [6]
-
-When a menubutton is posted, its associated menu claims the input
-focus to allow keyboard traversal of the menu and its submenus.
-See the B<menu> documentation for details on these bindings.
-
-=item [7]
-
-If the B<underline> option has been specified for a menubutton
-then keyboard traversal may be used to post the menubutton:
-Alt+I<x>, where I<x> is the underlined character (or its
-lower-case or upper-case equivalent), may be typed in any window
-under the menubutton's toplevel to post the menubutton.
-
-=item [8]
-
-The F10 key may be typed in any window to post the first menubutton
-under its toplevel window that isn't disabled.
-
-=item [9]
-
-If a menubutton has the input focus, the space and return keys
-post the menubutton.
-
-If the menubutton's state is B<disabled> then none of the above
-actions occur: the menubutton is completely non-responsive.
-
-The behavior of menubuttons can be changed by defining new bindings for
-individual widgets or by redefining the class bindings.
-
-=back
-
-=head1 KEYWORDS
-
-menubutton, widget
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Message.pod b/Master/tlpkg/tlperl/lib/Tk/Message.pod
deleted file mode 100644
index 9b0d67f3118..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Message.pod
+++ /dev/null
@@ -1,151 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Message - Create and manipulate Message widgets
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
-I<$message> = I<$parent>-E<gt>B<Message>(?I<options>?);
-
-=head1 STANDARD OPTIONS
-
-B<-anchor> B<-font> B<-highlightthickness> B<-takefocus>
-B<-background> B<-foreground> B<-padx> B<-text>
-B<-borderwidth> B<-highlightbackground> B<-pady> B<-textvariable>
-B<-cursor> B<-highlightcolor> B<-relief> B<-width>
-
-See L<Tk::options> for details of the standard options.
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<aspect>
-
-=item Class: B<Aspect>
-
-=item Switch: B<-aspect>
-
-Specifies a non-negative integer value indicating desired
-aspect ratio for the text. The aspect ratio is specified as
-100*width/height. 100 means the text should
-be as wide as it is tall, 200 means the text should
-be twice as wide as it is tall, 50 means the text should
-be twice as tall as it is wide, and so on.
-Used to choose line length for text if B<width> option
-isn't specified.
-Defaults to 150.
-
-=item Name: B<justify>
-
-=item Class: B<Justify>
-
-=item Switch: B<-justify>
-
-Specifies how to justify lines of text.
-Must be one of B<left>, B<center>, or B<right>. Defaults
-to B<left>.
-This option works together with the B<anchor>, B<aspect>,
-B<padX>, B<padY>, and B<width> options to provide a variety
-of arrangements of the text within the window.
-The B<aspect> and B<width> options determine the amount of
-screen space needed to display the text.
-The B<anchor>, B<padX>, and B<padY> options determine where this
-rectangular area is displayed within the widget's window, and the
-B<justify> option determines how each line is displayed within that
-rectangular region.
-For example, suppose B<anchor> is B<e> and B<justify> is
-B<left>, and that the message window is much larger than needed
-for the text.
-The the text will displayed so that the left edges of all the lines
-line up and the right edge of the longest line is B<padX> from
-the right side of the window; the entire text block will be centered
-in the vertical span of the window.
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-=item Switch: B<-width>
-
-Specifies the length of lines in the window.
-The value may have any of the forms acceptable to B<Tk_GetPixels>.
-If this option has a value greater than zero then the B<aspect>
-option is ignored and the B<width> option determines the line
-length.
-If this option has a value less than or equal to zero, then
-the B<aspect> option determines the line length.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Message> method creates a new window (given by the
-$widget argument) and makes it into a message widget.
-Additional
-options, described above, may be specified on the command line
-or in the option database
-to configure aspects of the message such as its colors, font,
-text, and initial relief. The B<message> command returns its
-$widget argument. At the time this command is invoked,
-there must not exist a window named $widget, but
-$widget's parent must exist.
-
-A message is a widget that displays a textual string. A message
-widget has three special features. First, it breaks up
-its string into lines in order to produce a given aspect ratio
-for the window. The line breaks are chosen at word boundaries
-wherever possible (if not even a single word would fit on a
-line, then the word will be split across lines). Newline characters
-in the string will force line breaks; they can be used, for example,
-to leave blank lines in the display.
-
-The second feature of a message widget is justification. The text
-may be displayed left-justified (each line starts at the left side of
-the window), centered on a line-by-line basis, or right-justified
-(each line ends at the right side of the window).
-
-The third feature of a message widget is that it handles control
-characters and non-printing characters specially. Tab characters
-are replaced with enough blank space to line up on the next
-8-character boundary. Newlines cause line breaks. Other control
-characters (ASCII code less than 0x20) and characters not defined
-in the font are displayed as a four-character sequence B<\x>I<hh> where
-I<hh> is the two-digit hexadecimal number corresponding to
-the character. In the unusual case where the font doesn't contain
-all of the characters in ``0123456789abcdef\x'' then control
-characters and undefined characters are not displayed at all.
-
-=head1 WIDGET METHODS
-
-The B<Message> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-=head1 DEFAULT BINDINGS
-
-When a new message is created, it has no default event bindings:
-messages are intended for output purposes only.
-
-=head1 BUGS
-
-Tabs don't work very well with text that is centered or right-justified.
-The most common result is that the line is justified wrong.
-
-=head1 KEYWORDS
-
-message, widget
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/MsgBox.pod b/Master/tlpkg/tlperl/lib/Tk/MsgBox.pod
deleted file mode 100644
index 6f5536cf89c..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/MsgBox.pod
+++ /dev/null
@@ -1,83 +0,0 @@
-
-=head1 NAME
-
-Tk::MsgBox - create and manipulate a message dialog
-
-=for pm Tk/MsgBox.pm
-
-=for category Popups and Dialogs
-
-=head1 SYNOPSIS
-
- use Tk::MsgBox
- ...
- $d = $top->MsgBox(-title => "Title", -type => "okcancel");
- ...
- $button = $d->Show;
-
-=head1 DESCRIPTION
-
-B<MsgBox> is a simple dialog with predefined buttons.
-
-=head1 OPTIONS
-
-The options recognized by B<MsgBox> are as follows:
-
-=over 4
-
-=item B<-icon>
-
-Specify the icon of the MsgBox. Valid values are B<error>, B<info>,
-B<question>, or B<warning>.
-
-=item B<-type>
-
-Specify the type of the MsgBox. Valid values are B<abortretryignore>,
-B<ok>, B<okcancel>, B<retrycancel>, B<yesno>, or B<yesnocancel>. The
-type determines the buttons to be shown.
-
-=item B<-default>
-
-Specify the default button. This must be one of B<abort>, B<retry>,
-B<ignore>, B<ok>, B<cancel>, B<yes>, or B<no>, depending on the type
-of the MsgBox previously specified.
-
-=item B<-detail>
-
-Specify text for the detail region of the MsgBox.
-
-=item B<-message>
-
-Specify the message text of the MsgBox.
-
-=item B<-title>
-
-Specify the title of the MsgBox.
-
-=back
-
-=head1 METHODS
-
-B<MsgBox> supports only one method as of now:
-
-=over 4
-
-=item B<Show()>
-
-Displays the MsgBox until the user invokes one of the buttons. Returns
-the name of the button invoked.
-
-=back
-
-=head1 AUTHOR
-
-Translated from Tcl/Tk by B<Slaven Rezic> srezic@cpan.org
-
-This code is distributed under the same terms as Perl.
-
-=head1 SEE ALSO
-
-L<Tk::messageBox>, L<Tk::DialogBox>, L<Tk::Dialog>.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Mwm.pod b/Master/tlpkg/tlperl/lib/Tk/Mwm.pod
deleted file mode 100644
index e9c09cd0358..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Mwm.pod
+++ /dev/null
@@ -1,109 +0,0 @@
-
-=head1 NAME
-
-Tk::Mwm - Communicate with the Motif(tm) window manager.
-
-=for category Tix Extensions
-
-=head1 SYNOPSIS
-
-S< >B<use Tk::Mwm;>
-
-S< >I<$toplevel>-E<gt>B<mwm>I<Option>?(I<args>)?
-
-S< >I<$toplevel>-E<gt>B<mwm>(I<option> ?,I<args>?)
-
-=head1 DESCRIPTION
-
-Interface to special extentions supported by mwm.
-
-=head1 METHODS
-
-=over 4
-
-=item I<$toplevel>-E<gt>B<mwmDecoration>?(?option??=E<gt>value? ?,...?)?
-
-When no options are given, this method returns the values of all the
-decorations options for the toplevel window with the I<$toplevel>.
-When only one option is given without specifying the value, the
-current value of that option is returned.
-When more than one "option-value" pairs are passed to this method,
-the specified values will be assigned to the corresponding options. As
-a result, the appearance of the Motif decorations around the toplevel
-window will be changed.
-Possible options are: B<-border>, B<-menu>, B<-maximize>,
-B<-minimize>, B<-resizeh> and B<-title>. The value must be a
-Boolean value. The values returned by this command are undefined when
-the window is not managed by mwm.
-
-=item I<$toplevel>-E<gt>B<mwmIsmwmrunning>
-
-This returns value is true if mwm is running on the screen where the specified
-window is located, false otherwise.
-
-=item I<$toplevel>-E<gt>B<mwmProtocol>
-
-When no additional options are given, this method returns all
-protocols associated with this toplevel window.
-
-=item I<$toplevel>-E<gt>B<mwmProtocol>(B<activate> =E<gt> I<protocol_name>)
-
-Activate the mwm protocol message in mwm's menu.
-
-=item I<$toplevel>-E<gt>B<MwmProtocol>(B<add> =E<gt> I<protocol_name>, I<menu_message>)
-
-Add a new mwm protocol message for this toplevel window. The
-message is identified by the string name specified in
-I<protocol_name>. A menu item will be added into mwm's menu as
-specified by I<menu_message>. Once a new mwm protocol message is
-added to a toplevel, it can be caught by the TK B<protocol>
-method. Here is an example:
-
-S< >I<$toplevel>-E<gt>B<mwmProtocol>(B<'add'> =E<gt> 'MY_PRINT_HELLO', '"Print Hello" _H CtrlE<lt>KeyE<gt>H');
-
-S< >I<$toplevel>-E<gt>B<protocol>(B<'MY_PRINT_HELLO'> =E<gt> sub {print "Hello"});
-
-=item I<$toplevel>-E<gt>B<mwmProtocol>(B<'deactivate'> =E<gt> I<protocol_name>)
-
-Deactivate the mwm protocol message in mwm's menu.
-
-=item I<$toplevel>-E<gt>B<mwmProtocol>(B<'delete'> =E<gt> I<protocol_name>)
-
-Delete the mwm protocol message from mwm's menu. Please note that the
-window manager protocol handler associated with this protocol (by the
-B<protocol> method) is not deleted automatically. You have to
-delete the protocol handle explicitly. E.g.:
-
-S< >I<$mw>-E<gt>B<mwmProtocol>(B<'delete'> =E<gt> 'MY_PRINT_HELLO');
-
-S< >I<$mw>-E<gt>B<protocol>(B<'MY_PRINT_HELLO'> =E<gt> '');
-
-=back
-
-=head1 BUGS
-
-This is a Tix extension which perl/Tk has adopted. It has not been
-tested as perl/Tk's author has not got round to installing a Motif Window
-Manager.
-
-On some versions of mwm, the B<-border> will not disappear unless
-B<-resizeh> is turned off. Also, the B<-title> will not disappear
-unless all of B<-title>, B<-menu>, B<-maximize> and
-B<-minimize> are turned off.
-
-=head1 SEE ALSO
-
-L<Tk::Wm|Tk::Wm>
-L<Tk::tixWm|Tk::tixWm>
-L<Tk::Toplevel|Tk::Toplevel>
-
-=head1 KEYWORDS
-
-window manager, mwm, TIX
-
-=head1 AUTHOR
-
-Ioi Kim Lam - ioi@graphics.cis.upenn.edu
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/NoteBook.pod b/Master/tlpkg/tlperl/lib/Tk/NoteBook.pod
deleted file mode 100644
index 2cc84bb3fad..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/NoteBook.pod
+++ /dev/null
@@ -1,235 +0,0 @@
-
-=head1 NAME
-
-Tk::NoteBook - display several windows in limited space with notebook metaphor.
-
-=for pm Tixish/NoteBook.pm
-
-=for category Tix Extensions
-
-=head1 SYNOPSIS
-
- use Tk::NoteBook;
- ...
- $w = $frame->NoteBook();
- $page1 = $w->add("page1", options);
- $page2 = $w->add("page2", options);
- ...
- $page2 = $w->add("page2", options);
-
-=head1 DESCRIPTION
-
-The NoteBook widget provides a notebook metaphor to display several
-windows in limited space. The notebook is divided into a stack of pages
-of which only one is displayed at any time. The other pages can be
-selected by means of choosing the visual "tabs" at the top of the
-widget. Additionally, the <Tab> key may be used to traverse the pages.
-If B<-underline> is used, Alt- bindings will also work.
-
-The widget takes all the options that a Frame does. In addition,
-it supports the following options:
-
-=over 4
-
-=item B<-dynamicgeometry>
-
-If set to false (default and recommended), the size of the NoteBook
-will match the size of the largest page. Otherwise the size will
-match the size of the current page causing the NoteBook to change
-size when different pages of different sizes are selected.
-
-=item B<-ipadx>
-
-The amount of internal horizontal padding around the pages.
-
-=item B<-ipady>
-
-The amount of internal vertical padding around the pages.
-
-=item B<-backpagecolor>
-
-The background color of the tabs and back page.
-
-=item B<-disabledforeground>
-
-XXX
-
-=item B<-focuscolor>
-
-The color of the focus border around the tabs.
-
-=item B<-font>
-
-The font of the tab labels.
-
-=item B<-inactivebackground>
-
-XXX
-
-=item B<-tabpadx>
-
-Horizonzal padding around the tab label.
-
-=item B<-tabpady>
-
-Vertical padding around the tab label.
-
-=back
-
-=head1 METHODS
-
-The following methods may be used with a NoteBook object in addition
-to standard methods.
-
-=over 4
-
-=item B<add(>I<pageName>, I<options>B<)>
-
-Adds a page with name I<pageName> to the notebook. Returns an object
-of type B<Frame>. The recognized I<options> are:
-
-=over 4
-
-=item B<-anchor>
-
-Specifies how the information in a tab is to be displayed. Must be
-one of B<n>, B<ne>, B<e>, B<se>, B<s>, B<sw>, B<w>, B<nw> or
-B<center>.
-
-=item B<-bitmap>
-
-Specifies a bitmap to display on the tab of this page. The bitmap
-is displayed only if none of the B<-label> or B<-image> options
-are specified.
-
-=item B<-image>
-
-Specifies an image to display on the tab of this page. The image
-is displayed only if the B<-label> option is not specified.
-
-=item B<-label>
-
-Specifies the text string to display on the tab of this page.
-
-=item B<-justify>
-
-When there are multiple lines of text displayed in a tab, this
-option determines the justification of the lines.
-
-=item B<-createcmd>
-
-Specifies a L<callback|Tk::callbacks> to be called the first time the page is
-shown on the screen. This option can be used to delay the creation
-of the contents of a page until necessary. It can be useful in
-situations where there are a large number of pages in a NoteBook
-widget; with B<-createcmd> you do not have to make the user wait
-until all pages are constructed before displaying the first page.
-
-=item B<-raisecmd>
-
-Specifies a L<callback|Tk::callbacks> to be called whenever this page is raised
-by the user.
-
-=item B<-state>
-
-Specifies whether this page can be raised by the user. Must be
-either B<normal> or B<disabled>.
-
-=item B<-underline>
-
-Specifies the integer index of a character to underline in the
-tab. This option is used by the default bindings to implement
-keyboard traversal for menu buttons and menu entries. 0
-corresponds to the first character of text displayed on the
-widget, 1 to the next character and so on.
-
-=item B<-wraplength>
-
-This option specifies the maximum line length of the label string
-on this tab. If the line length of the label string exceeds this
-length, then it is wrapped onto the next line so that no line is
-longer than the specified length. The value may be specified in
-any standard forms for screen distances. If this value is less
-than or equal to 0, then no wrapping is done: lines will break
-only at newline characters in the text.
-
-=back
-
-=item B<delete(>I<pageName>B<)>
-
-Deletes the page identified by I<pageName>.
-
-=item B<pagecget(>I<pageName>, I<-option>B<)>
-
-Returns the current value of the configuration option given by
-I<-option> in the page given by I<pageName>. I<Option> may have any of
-the values accepted in the B<add> method.
-
-=item B<pageconfigure(>I<pageName>, I<options>B<)>
-
-Like configure for the page indicated by I<pageName>. I<Options> may
-be any of the options accepted by the B<add> method.
-
-=item B<pages>
-
-Returns a list consisting of the names of all currently defined
-pages, i.e., those created with the B<add> method.
-
-=item B<page_widget(>I<pageName>B<)>
-
-Returns the page with name I<pageName>.
-
-=item B<raise(>I<pageName>B<)>
-
-Raise the page identified by I<pageName>.
-
-=item B<raised()>
-
-Returns the name of the currently raised page.
-
-=item B<geometryinfo>
-
-Return the dimensions of the tab area.
-
-=item B<identify(>I<x>,I<y>B<)>
-
-Identify the tab's page name under the specified coordinates. Return
-an empty string if there's no tab.
-
-=item B<info(E<quot>pagesE<quot>)>
-
-Return a list of all pages.
-
-=item B<info(E<quot>focusE<quot>)>
-
-Return the page name of the tab with the current focus.
-
-=item B<info(E<quot>focusnextE<quot>)>
-
-Return the page name of the tab which would receive the next focus.
-
-=item B<info(E<quot>focusprevE<quot>)>
-
-Return the page name of the tab which had the previous focus.
-
-=item B<info(E<quot>activeE<quot>)>
-
-Return the page name of the active tab.
-
-=back
-
-=head1 BUGS
-
-The options C<-width> and C<-height> do not work.
-
-=head1 AUTHORS
-
-B<Rajappa Iyer> <rsi@earthling.net>
-Nick Ing-Simmons <nick@ni-s.u-net.com>
-
-This code and documentation was derived from NoteBook.tcl in
-Tix4.0 written by Ioi Lam. It may be distributed under the same
-conditions as Perl itself.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Optionmenu.pod b/Master/tlpkg/tlperl/lib/Tk/Optionmenu.pod
deleted file mode 100644
index f5e514c63b3..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Optionmenu.pod
+++ /dev/null
@@ -1,100 +0,0 @@
-
-=head1 NAME
-
-Tk::Optionmenu - Let the user select one of some predefined options values
-
-=for pm Tk/Optionmenu.pm
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
- use Tk::Optionmenu;
-
- $opt = $w->Optionmenu(
- -options => REFERENCE_to_OPTIONLIST,
- -command => CALLBACK,
- -variable => SCALAR_REF,
- );
-
- $opt->addOptions( OPTIONLIST );
-
- # OPTION LIST is
- # a) $val1, $val2, $val3,...
- # b) [ $lab1=>$val1], [$lab2=>val2], ... ]
- # c) combination of a) and b), e.g.,
- # val1, [$lab2=>val2], val3, val4, [...], ...
-
-=head1 DESCRIPTION
-
-The B<Optionmenu> widget allows the user chose between a given set
-of options.
-
-If the user should be able to change the available option have a look
-at L<Tk::BrowseEntry>.
-
-=head1 OPTIONS
-
-=over 4
-
-=item -options
-
-(Re)sets the list of options presented.
-
-=item -command
-
-Defines the L<callback|Tk::callbacks> that is invokes when a new option
-is selected.
-
-=item -variable
-
-Reference to a scalar that contains the current value of the
-selected option.
-
-=item -textvariable
-
-Reference to a scalar that contains the text label of the current value of the
-selected option.
-
-=back
-
-=head1 METHODS
-
-=over 4
-
-=item addOptions
-
-Adds OPTION_LIST to the already available options.
-
-=back
-
-=head1 EXAMPLE
-
- use Tk;
- my $mw = MainWindow->new();
-
- my ($var, $tvar);
- my $opt = $mw->Optionmenu(
- -options => [[jan=>1], [feb=>2], [mar=>3], [apr=>4]],
- -command => sub { print "got: ", shift, "\n" },
- -variable => \$var,
- -textvariable => \$tvar
- )->pack;
-
- $opt->addOptions([may=>5],[jun=>6],[jul=>7],[aug=>8]);
-
- my $f = $mw->Frame(-relief=>'groove', -borderwidth => 2)->pack;
- $f->Label(-textvariable=>\$tvar)->pack(-side => 'left');
- $f->Label(-text => " -> ")->pack(-side => 'left');
- $f->Label(-textvariable=>\$var)->pack(-side => 'left');
-
- $mw->Button(-text=>'Exit', -command=>sub{$mw->destroy})->pack;
-
- MainLoop;
-
-=head1 SEE ALSO
-
-L<Tk::Menubutton>, L<Tk::BrowseEntry>
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Panedwindow.pod b/Master/tlpkg/tlperl/lib/Tk/Panedwindow.pod
deleted file mode 100644
index 673938d55e5..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Panedwindow.pod
+++ /dev/null
@@ -1,326 +0,0 @@
-# Copyright (c) 1992 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-# RCS: @(#) $Id: panedwindow.n,v 1.2.2.1 2003/07/17 20:49:00 dkf Exp $
-
-=head1 NAME
-
-Tk::Panedwindow - Create and manipulate Panedwindow widgets
-
-=for category Tk Generic Methods
-
-=head1 SYNOPSIS
-
-I<$panedwindow> = I<$parent>-E<gt>B<Panedwindow>(?I<options>?);
-
- -background -height -width
- -borderwidth -orient
- -cursor -relief
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Option: B<-handlepad>
-
-=item Name: B<handlePad>
-
-=item Class: B<HandlePad>
-
-When sash handles are drawn, specifies the distance from the top or
-left end of the sash (depending on the orientation of the widget) at
-which to draw the handle. May be any value accepted by B<Tk_GetPixels>.
-
-=item Option: B<-handlesize>
-
-=item Name: B<handleSize>
-
-=item Class: B<HandleSize>
-
-Specifies the side length of a sash handle. Handles are always
-drawn as squares. May be any value accepted by B<Tk_GetPixels>.
-
-=item Option: B<-opaqueresize>
-
-=item Name: B<opaqueResize>
-
-=item Class: B<OpaqueResize>
-
-Specifies whether panes should be resized as a sash is moved (true),
-or if resizing should be deferred until the sash is placed (false).
-
-=item Option: B<-sashcursor>
-
-=item Name: B<sashCursor>
-
-=item Class: B<SashCursor>
-
-Mouse cursor to use when over a sash. If null,
-B<sb_h_double_arrow> will be used for horizontal Panedwindows, and
-B<sb_v_double_arrow> will be used for vertical Panedwindows.
-
-=item Option: B<-sashpad>
-
-=item Name: B<sashPad>
-
-=item Class: B<SashPad>
-
-Specifies the amount of padding to leave of each side of a sash. May
-be any value accepted by B<Tk_GetPixels>.
-
-=item Option: B<-sashrelief>
-
-=item Name: B<sashRelief>
-
-=item Class: B<SashRelief>
-
-Relief to use when drawing a sash. May be any of the standard Tk
-relief values.
-
-=item Option: B<-sashwidth>
-
-=item Name: B<sashWidth>
-
-=item Class: B<SashWidth>
-
-Specifies the width of each sash. May be any value accepted by
-B<Tk_GetPixels>.
-
-=item Option: B<-showhandle>
-
-=item Name: B<showHandle>
-
-=item Class: B<ShowHandle>
-
-Specifies whether sash handles should be shown. May be any valid
-boolean value.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Panedwindow> method creates a new window (given by the
-$panedwindow argument) and makes it into a Panedwindow widget.
-Additional options, described above, may be specified on the command
-line or in the option database to configure aspects of the Panedwindow
-such as its default background color and relief.
-
-A Panedwindow widget contains any number of panes, arranged
-horizontally or vertically, according to the value of the
-B<-orient> option. Each pane contains one widget, and each pair of
-panes is separated by a moveable (via mouse movements) sash. Moving a
-sash causes the widgets on either side of the sash to be resized.
-
-=head1 WIDGET METHODS
-
-The B<Panedwindow> method
-may be used to invoke various operations on the widget. It has the
-following general form:
-
- $widget->method(?arg arg ...?);
-
-The following
-commands are possible for Panedwindow widgets:
-
-=over 4
-
-=item I<$widget>-E<gt>B<add>(?window ...? ?option value ...?);
-
-Add one or more windows to the Panedwindow, each in a separate pane.
-The arguments consist of the names of one or more windows
-followed by pairs of arguments that specify how to manage the windows.
-I<Option> may have any of the values accepted by the
-B<configure> subcommand.
-
-=item I<$widget>-E<gt>B<cget>(I<option>);
-
-Returns the current value of the configuration option given by
-I<option>. I<Option> may have any of the values accepted by the
-B<Panedwindow> command.
-
-=item I<$widget>-E<gt>B<configure>(I<?option?, ?value, option, value, ...?>);
-
-Query or modify the configuration options of the widget. If no
-I<option> is specified, returns a list describing all of the
-available options for $widget (see L<Tk::configure> for
-information on the format of this list). If I<option> is specified
-with no I<value>, then the command returns a list describing the
-one named option (this list will be identical to the corresponding
-sublist of the value returned if no I<option> is specified). If
-one or more I<option-value> pairs are specified, then the command
-modifies the given widget option(s) to have the given value(s); in
-this case the command returns an empty string. I<Option> may have
-any of the values accepted by the B<Panedwindow> command.
-
-=item I<$widget>-E<gt>B<forget>(?window ...?);
-
-Remove the pane containing $widget from the Panedwindow. All
-geometry management options for $widget will be forgotten.
-
-=item I<$widget>-E<gt>B<identify>(I<x, y>);
-
-Identify the Panedwindow component underneath the point given by
-I<x> and I<y>, in window coordinates. If the point is over a
-sash or a sash handle, the result is a two element list containing the
-index of the sash or handle, and a word indicating whether it is over
-a sash or a handle, such as [0, 'sash'] or [2, 'handle']. If the point is
-over any other part of the Panedwindow, the result is an empty list.
-
-=item I<$widget>-E<gt>B<proxy>(I<?args?>);
-
-This command is used to query and change the position of the sash
-proxy, used for rubberband-style pane resizing. It can take any of
-the following forms:
-
-=over 4
-
-=item I<$widget>-E<gt>B<proxyCoord>;
-
-Return a list containing the x and y coordinates of the most recent
-proxy location.
-
-=item I<$widget>-E<gt>B<proxyForget>;
-
-Remove the proxy from the display.
-
-=item I<$widget>-E<gt>B<proxyPlace>(I<x, y>);
-
-Place the proxy at the given I<x> and I<y> coordinates.
-
-=back
-
-=item I<$widget>-E<gt>B<sash>(I<?args?>);
-
-This command is used to query and change the position of sashes in the
-Panedwindow. It can take any of the following forms:
-
-=over 4
-
-=item I<$widget>-E<gt>B<sashCoord>(I<index>);
-
-Return the current x and y coordinate pair for the sash given by
-I<index>. I<Index> must be an integer between 0 and 1 less than
-the number of panes in the Panedwindow. The coordinates given are
-those of the top left corner of the region containing the sash.
-I<$widget>-E<gt>B<sashDragto>(I<index, x, y>)
-This command computes the difference between the given coordinates and the
-coordinates given to the last B<sash coord> command for the given
-sash. It then moves that sash the computed difference. The return
-value is the empty string.
-
-=item I<$widget>-E<gt>B<sashMark>(I<index, x, y>);
-
-Records I<x> and I<y> for the sash given by I<index>; used in
-conjunction with later dragto commands to move the sash.
-
-=item I<$widget>-E<gt>B<sashPlace>(I<index, x, y>);
-
-Place the sash given by I<index> at the given coordinates.
-
-=back
-
-=item $widget I<$widget>-E<gt>B<panecget>(option);
-
-Query a management option for $widget. I<Option> may be any
-value allowed by the B<paneconfigure> subcommand.
-
-=item $widget I<$widget>-E<gt>B<paneconfigure>(?option? ?value option value ...?);
-
-Query or modify the management options for $widget. If no
-I<option> is specified, returns a list describing all of the
-available options for $widget (see L<Tk::configure> for
-information on the format of this list). If I<option> is specified
-with no I<value>, then the command returns a list describing the
-one named option (this list will be identical to the corresponding
-sublist of the value returned if no I<option> is specified). If
-one or more I<option-value> pairs are specified, then the command
-modifies the given widget option(s) to have the given value(s); in
-this case the command returns an empty string. The following options
-are supported:
-
-=over 4
-
-=item B<-after> =E<gt> $widget
-
-Insert the window after the window specified. $widget should be the
-name of a window already managed by $widget.
-
-=item B<-before> =E<gt> $widget
-
-Insert the window before the window specified. $widget should be
-the name of a window already managed by $widget.
-
-=item B<-height> =E<gt> I<size>
-
-Specify a height for the window. The height will be the outer
-dimension of the window including its border, if any. If I<size>
-is an empty string, or if B<-height> is not specified, then the
-height requested internally by the window will be used initially; the
-height may later be adjusted by the movement of sashes in the
-Panedwindow. I<Size> may be any value accepted by B<Tk_GetPixels>.
-
-=item B<-minsize> =E<gt> I<n>
-
-Specifies that the size of the window cannot be made less than
-I<n>. This constraint only affects the size of the widget in the
-paned dimension -- the x dimension for horizontal Panedwindows, the y
-dimension for vertical Panedwindows. May be any value accepted by
-B<Tk_GetPixels>.
-
-=item B<-padx> =E<gt> I<n>
-
-Specifies a non-negative value indicating how much extra space to
-leave on each side of the window in the X-direction. The value may
-have any of the forms accepted by B<Tk_GetPixels>.
-
-=item B<-pady> =E<gt> I<n>
-
-Specifies a non-negative value indicating how much extra space to
-leave on each side of the window in the Y-direction. The value may
-have any of the forms accepted by B<Tk_GetPixels>.
-
-=item B<-sticky> =E<gt> I<style>
-
-If a window's pane is larger than the requested dimensions of the
-window, this option may be used to position (or stretch) the window
-within its pane. I<Style> is a string that contains zero or more
-of the characters B<n>, B<s>, B<e> or B<w>. The string
-can optionally contains spaces or commas, but they are ignored. Each
-letter refers to a side (north, south, east, or west) that the window
-will "stick" to. If both B<n> and B<s> (or B<e> and B<w>)
-are specified, the window will be stretched to fill the entire height
-(or width) of its cavity.
-
-=item B<-width> =E<gt> I<size>
-
-Specify a width for the window. The width will be the outer
-dimension of the window including its border, if any. If I<size>
-is an empty string, or if B<-width> is not specified, then the
-width requested internally by the window will be used initially; the
-width may later be adjusted by the movement of sashes in the
-Panedwindow. I<Size> may be any value accepted by B<Tk_GetPixels>.
-
-=back
-
-=item I<$widget>-E<gt>B<panes>;
-
-Returns an ordered list of the widgets managed by $widget.
-
-=back
-
-=head1 RESIZING PANES
-
-A pane is resized by grabbing the sash (or sash handle if present) and
-dragging with the mouse. This is accomplished via mouse motion
-bindings on the widget. When a sash is moved, the sizes of the panes
-on each side of the sash, and thus the widgets in those panes, are
-adjusted.
-
-When a pane is resized from outside (eg, it is packed to expand and
-fill, and the containing toplevel is resized), space is added to the final
-(rightmost or bottommost) pane in the window.
-
-=head1 KEYWORDS
-
-Panedwindow, widget, geometry management
diff --git a/Master/tlpkg/tlperl/lib/Tk/Photo.pod b/Master/tlpkg/tlperl/lib/Tk/Photo.pod
deleted file mode 100644
index 02a691d6261..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Photo.pod
+++ /dev/null
@@ -1,475 +0,0 @@
-# Copyright (c) 1994 The Australian National University
-# Copyright (c) 1994-1997 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-# Author: Paul Mackerras (paulus@cs.anu.edu.au),
-# Department of Computer Science,
-# Australian National University.
-# RCS: @(#) $Id: photo.n,v 1.2 1998/09/14 18:22:59 stanton Exp $
-#
-
-=head1 NAME
-
-Tk::Photo - Full-color images
-
-=for category Tk Image Classes
-
-=head1 SYNOPSIS
-
-S< >I<$widget>-E<gt>B<Photo>(?I<name>??, I<options>?)
-
-=head1 DESCRIPTION
-
-A photo is an L<image|Tk::Image> whose pixels can display any color or be
-transparent. A photo image is stored internally in full color (32
-bits per pixel), and is displayed using dithering if necessary. Image
-data for a photo image can be obtained from a file or a string, or it
-can be supplied from
-C code through a procedural interface. At present, only GIF,
-XBM, XPM, BMP, JPEG, PNG and PPM/PGM
-formats are supported, but an interface exists to allow additional
-image file formats to be added easily. A photo image is transparent
-in regions where no image data has been supplied
-or where it has been set transparent by the B<transparencySet>
-subcommand.
-
-=head1 CREATING PHOTOS
-
-Photos are created using the B<Photo> method.
-B<Photo> supports the following I<options>:
-
-=over 4
-
-=item B<-data> =E<gt> I<string>
-
-Specifies the contents of the image as a string.
-The string can
-contain base64 encoded data or binary data.
-The format of the
-string must be one of those for which there is an image file format
-handler that will accept string data. If both the B<-data>
-and B<-file> options are specified, the B<-file> option takes
-precedence.
-
-=item B<-format> =E<gt> I<format-name>
-
-Specifies the name of the file format for the data specified with the
-B<-data> or B<-file> option.
-
-=item B<-file> =E<gt> I<name>
-
-I<name> gives the name of a file that is to be read to supply data
-for the photo image. The file format must be one of those for which
-there is an image file format handler that can read data.
-
-=item B<-gamma> =E<gt> I<value>
-
-Specifies that the colors allocated for displaying this image in a
-window should be corrected for a non-linear display with the specified
-gamma exponent value. (The intensity produced by most
-CRT displays is a power function of the input value, to a good
-approximation; gamma is the exponent and is typically around 2).
-The value specified must be greater than zero. The default
-value is one (no correction). In general, values greater than one
-will make the image lighter, and values less than one will make it
-darker.
-
-=item B<-height> =E<gt> I<number>
-
-Specifies the height of the image, in pixels. This option is useful
-primarily in situations where the user wishes to build up the contents
-of the image piece by piece. A value of zero (the default) allows the
-image to expand or shrink vertically to fit the data stored in it.
-
-=item B<-palette> =E<gt> I<palette-spec>
-
-Specifies the resolution of the color cube to be allocated for
-displaying this image, and thus the number of colors used from the
-colormaps of the windows where it is displayed. The
-I<palette-spec> string may be either a single decimal number,
-specifying the number of shades of gray to use, or three decimal
-numbers separated by slashes (/), specifying the number of shades of
-red, green and blue to use, respectively. If the first form (a single
-number) is used, the image will be displayed in monochrome (i.e.,
-grayscale).
-
-=item B<-width> =E<gt> I<number>
-
-Specifies the width of the image, in pixels. This option is useful
-primarily in situations where the user wishes to build up the contents
-of the image piece by piece. A value of zero (the default) allows the
-image to expand or shrink horizontally to fit the data stored in it.
-
-=back
-
-=head1 IMAGE METHODS
-
-When a photo image is created, Tk also creates a new object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-
-Those options that write data to the image generally expand the size
-of the image, if necessary, to accommodate the data written to the
-image, unless the user has specified non-zero values for the
-B<-width> and/or B<-height> configuration options, in which
-case the width and/or height, respectively, of the image will not be
-changed.
-
-The following addition methods are available for photo images:
-
-=over 4
-
-=item I<$image>-E<gt>B<blank>
-
-Blank the image; that is, set the entire image to have no data, so it
-will be displayed as transparent, and the background of whatever
-window it is displayed in will show through.
-
-=item I<$image>-E<gt>B<copy>(I<sourceImage> ?,I<option value(s) ...>?)
-
-Copies a region from the image called I<$sourceImage> (which must
-be a photo image) to the image called I<$image>, possibly with
-pixel zooming and/or subsampling. If no options are specified, this
-method copies the whole of I<$sourceImage> into I<$image>,
-starting at coordinates (0,0) in I<$image>. The following
-options may be specified:
-
-=over 8
-
-=item B<-from> =E<gt> I<x1, y1, ? ,x2, y2?>
-
-Specifies a rectangular sub-region of the source image to be copied.
-(I<x1,y1>) and (I<x2,y2>) specify diagonally opposite corners of
-the rectangle. If I<x2> and I<y2> are not specified, the
-default value is the bottom-right corner of the source image. The
-pixels copied will include the left and top edges of the specified
-rectangle but not the bottom or right edges. If the B<-from>
-option is not given, the default is the whole source image.
-
-=item B<-to> =E<gt> I<x1, y1, ?, x2, y2?>
-
-Specifies a rectangular sub-region of the destination image to be
-affected. (I<x1,y1>) and (I<x2,y2>) specify diagonally opposite
-corners of the rectangle. If I<x2> and I<y2> are not specified,
-the default value is (I<x1,y1>) plus the size of the source
-region (after subsampling and zooming, if specified). If I<x2> and
-I<y2> are specified, the source region will be replicated if
-necessary to fill the destination region in a tiled fashion.
-
-=item B<-shrink>
-
-Specifies that the size of the destination image should be reduced, if
-necessary, so that the region being copied into is at the bottom-right
-corner of the image. This option will not affect the width or height
-of the image if the user has specified a non-zero value for the
-B<-width> or B<-height> configuration option, respectively.
-
-=item B<-zoom> =E<gt> I<x, y>
-
-Specifies that the source region should be magnified by a factor of
-I<x> in the X direction and I<y> in the Y direction. If I<y>
-is not given, the default value is the same as I<x>. With this
-option, each pixel in the source image will be expanded into a block
-of I<x> x I<y> pixels in the destination image, all the same
-color. I<x> and I<y> must be greater than 0.
-
-=item B<-subsample> =E<gt> I<x, y>
-
-Specifies that the source image should be reduced in size by using
-only every I<x>th pixel in the X direction and I<y>th pixel in
-the Y direction. Negative values will cause the image to be flipped
-about the Y or X axes, respectively. If I<y> is not given, the
-default value is the same as I<x>.
-
-=item B<-compositingrule> =E<gt> I<rule>
-
-Specifies how transparent pixels in the source image are combined with
-the destination image. When a compositing rule of I<overlay> is
-set, the old contents of the destination image are visible, as if the
-source image were printed on a piece of transparent film and placed
-over the top of the destination. When a compositing rule of I<set>
-is set, the old contents of the destination image are discarded and
-the source image is used as-is. The default compositing rule is
-I<overlay>.
-
-=back
-
-=item I<$image>-E<gt>B<data>(?I<option value(s), ...>?)
-
-Returns image data in the form of a string.
-The following options may be specified:
-
-=over 8
-
-=item B<-background> =E<gt> I< color>
-
-If the color is specified, the data will not contain any transparency
-information. In all transparent pixels the color will be replaced by
-the specified color.
-
-=item B<-format> =E<gt> I<format-name>
-
-Specifies the name of the image file format handler to be used.
-Specifically, this method searches
-for the first handler whose name matches a initial substring of
-I<format-name> and which has the capability to read this image data.
-If this option is not given, this method uses the first
-handler that has the capability to read the image data.
-
-=item B<-from> =E<gt> I<x1, y1, ?, x2, y2?>
-
-Specifies a rectangular region of I<$image> to be
-returned. If only I<x1> and I<y1> are specified, the region
-extends from I<(x1,y1)> to the bottom-right corner of
-I<$image>. If all four coordinates are given, they specify
-diagonally opposite corners of the rectangular region, including x1,y1
-and excluding x2,y2. The default,
-if this option is not given, is the whole image.
-
-=item B<-grayscale>
-
-If this options is specified, the data will not contain color
-information. All pixel data will be transformed into grayscale.
-
-=back
-
-=item I<$image>-E<gt>B<get>(I<x, y>)
-
-Returns the color of the pixel at coordinates (I<x>,I<y>) in the
-image as a list of three integers between 0 and 255, representing the
-red, green and blue components respectively.
-
-=item I<$image>-E<gt>B<put>(I<data> ?,B<-format>=E<gt>I<format-name>? ?,B<-to>=E<gt>I< x1 y1 ?x2 y2?>?)
-
-Sets pixels in I<$image> to the data specified in I<data>.
-This command first searches the list of image file format handlers for
-a handler that can interpret the data in I<data>, and then reads
-the image encoded within into I<$image> (the destination image).
-If I<data> does not match any known format, an attempt to interpret
-it as a (top-to-bottom) list of scan-lines is made, with each
-scan-line being a (left-to-right) list of pixel colors (see
-B<Tk_GetColor> for a description of valid colors.) Every scan-line
-must be of the same length. Note that when I<data> is a single
-color name, you are instructing Tk to fill a rectangular region with
-that color. The following options may be specified:
-
-=over 4
-
-=item B<-format> =E<gt>I<format-name>
-
-Specifies the format of the image data in I<data>.
-Specifically, only image file format handlers whose names begin with
-I<format-name> will be used while searching for an image data
-format handler to read the data.
-
-=item B<-to> =E<gt>I<x, y> ?I<, x2, y2>?
-
-Specifies the coordinates of the top-left corner (I<x1>,I<y1>)
-of the region of I<$image> into which data from I<filename>
-are to be read. The default is (0,0). If I<x2>,I<y2> is given
-and I<data> is not large enough to cover the rectangle specified by
-this option, the image data extracted will be tiled so it covers the
-entire destination rectangle. Note that if I<data> specifies a
-single color value, then a region extending to the bottom-right corner
-represented by (I<x2>,I<y2>) will be filled with that color.
-
-=back
-
-=item I<$image>-E<gt>B<read>(I<filename> ?,I<option value(s), ...>?)
-
-Reads image data from the file named I<filename> into the image.
-This method first searches the list of
-image file format handlers for a handler that can interpret the data
-in I<filename>, and then reads the image in I<filename> into
-I<$image> (the destination image). The following options may be
-specified:
-
-=over 8
-
-=item B<-format> =E<gt> I<format-name>
-
-Specifies the format of the image data in I<filename>.
-Specifically, only image file format handlers whose names begin with
-I<format-name> will be used while searching for an image data
-format handler to read the data.
-
-=item B<-from> =E<gt> I<x1, y1, x2, y2>
-
-Specifies a rectangular sub-region of the image file data to be copied
-to the destination image. If only I<x1> and I<y1> are
-specified, the region extends from (I<x1,y1>) to the bottom-right
-corner of the image in the image file. If all four coordinates are
-specified, they specify diagonally opposite corners or the region.
-The default, if this option is not specified, is the whole of the
-image in the image file.
-
-=item B<-shrink>
-
-If this option is specified, the size of I<$image> will be reduced, if
-necessary, so that the region into which the image file data are read
-is at the bottom-right corner of the I<$image>. This option
-will not affect the width or height of the image if the user has
-specified a non-zero value for the B<-width> or B<-height>
-configuration option, respectively.
-
-=item B<-to> =E<gt> I<x, y>
-
-Specifies the coordinates of the top-left corner of the region of
-I<$image> into which data from I<filename> are to be read.
-The default is (0,0).
-
-=back
-
-=item I<$image>-E<gt>B<redither>
-
-The dithering algorithm used in displaying photo images propagates
-quantization errors from one pixel to its neighbors.
-If the image data for I<$image> is supplied in pieces, the
-dithered image may not be exactly correct. Normally the difference is
-not noticeable, but if it is a problem, this method can be used to
-recalculate the dithered image in each window where the image is
-displayed.
-
-=item I<$image>-E<gt>B<transparency>(I<subcommand, ?arg, arg ...?>);
-
-Allows examination and manipulation of the transparency information in
-the photo image. Several subcommands are available:
-
-=over 4
-
-=item I<$image>-E<gt>B<transparencyGet>(I<x, y>);
-
-Returns a boolean indicating if the pixel at (I<x>,I<y>) is
-transparent.
-
-=item I<$image>-E<gt>B<transparencySet>(I<x, y, boolean>);
-
-Makes the pixel at (I<x>,I<y>) transparent if I<boolean> is
-true, and makes that pixel opaque otherwise.
-
-=back
-
-=item I<$image>-E<gt>B<write>(I<filename> ?,I<option value(s), ...>?)
-
-Writes image data from I<$image> to a file named I<filename>.
-The following options may be specified:
-
-=over 8
-
-=item B<-background> =E<gt> I< color>
-
-If the color is specified, the data will not contain any transparency
-information. In all transparent pixels the color will be replaced by
-the specified color.
-
-=item B<-format> =E<gt> I<format-name>
-
-Specifies the name of the image file format handler to be used to
-write the data to the file. Specifically, this subcommand searches
-for the first handler whose name matches a initial substring of
-I<format-name> and which has the capability to write an image
-file. If this option is not given, this subcommand uses the first
-handler that has the capability to write an image file.
-
-=item B<-from> =E<gt> I<x1, y1, ?, x2, y2?>
-
-Specifies a rectangular region of I<$image> to be written to the
-image file. If only I<x1> and I<y1> are specified, the region
-extends from I<(x1,y1)> to the bottom-right corner of
-I<$image>. If all four coordinates are given, they specify
-diagonally opposite corners of the rectangular region. The default,
-if this option is not given, is the whole image.
-
-
-=item B<-grayscale>
-
-If this options is specified, the data will not contain color
-information. All pixel data will be transformed into grayscale.
-
-=back
-
-=back
-
-=head1 IMAGE FORMATS
-
-The photo image code is structured to allow handlers for additional
-image file formats to be added easily. The photo image code maintains
-a list of these handlers. Handlers are added to the list by
-registering them with a call to B<Tk_CreatePhotoImageFormat>. The
-standard Tk distribution comes with handlers for XBM, XPM, BMP, JPEG,
-PNG and PPM/PGM formats, which are automatically registered on
-initialization.
-
-When reading an image file or processing
-string data specified with the B<-data> configuration option, the
-photo image code invokes each handler in turn until one is
-found that claims to be able to read the data in the file or string.
-Usually this will find the correct handler, but if it doesn't, the
-user may give a format name with the B<-format> option to specify
-which handler to use. In fact the photo image code will try those
-handlers whose names begin with the string specified for the
-B<-format> option (the comparison is case-insensitive). For
-example, if the user specifies B<-format> B<=E<gt>> B<gif>, then a handler
-named GIF87 or GIF89 may be invoked, but a handler
-named JPEG may not (assuming that such handlers had been
-registered).
-
-When writing image data to a file, the processing of the
-B<-format> option is slightly different: the string value given
-for the B<-format> option must begin with the complete name of the
-requested handler, and may contain additional information following
-that, which the handler can use, for example, to specify which variant
-to use of the formats supported by the handler.
-Note that not all image handlers may support writing transparency data
-to a file, even where the target image format does.
-
-=head1 COLOR ALLOCATION
-
-When a photo image is displayed in a window, the photo image code
-allocates colors to use to display the image and dithers the image, if
-necessary, to display a reasonable approximation to the image using
-the colors that are available. The colors are allocated as a color
-cube, that is, the number of colors allocated is the product of the
-number of shades of red, green and blue.
-
-Normally, the number of
-colors allocated is chosen based on the depth of the window. For
-example, in an 8-bit PseudoColor window, the photo image code will
-attempt to allocate seven shades of red, seven shades of green and
-four shades of blue, for a total of 198 colors. In a 1-bit StaticGray
-(monochrome) window, it will allocate two colors, black and white. In
-a 24-bit DirectColor or TrueColor window, it will allocate 256 shades
-each of red, green and blue. Fortunately, because of the way that
-pixel values can be combined in DirectColor and TrueColor windows,
-this only requires 256 colors to be allocated. If not all of the
-colors can be allocated, the photo image code reduces the number of
-shades of each primary color and tries again.
-
-The user can exercise some control over the number of colors that a
-photo image uses with the B<-palette> configuration option. If
-this option is used, it specifies the maximum number of shades of
-each primary color to try to allocate. It can also be used to force
-the image to be displayed in shades of gray, even on a color display,
-by giving a single number rather than three numbers separated by
-slashes.
-
-=head1 CREDITS
-
-The photo image type was designed and implemented by Paul Mackerras,
-based on his earlier photo widget and some suggestions from
-John Ousterhout.
-
-=head1 SEE ALSO
-
-L<Tk::Bitmap|Tk::Bitmap>
-L<Tk::Image|Tk::Image>
-L<Tk::Pixmap|Tk::Pixmap>
-
-=head1 KEYWORDS
-
-photo, image, color
-
-=cut
-
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Pixmap.pod b/Master/tlpkg/tlperl/lib/Tk/Pixmap.pod
deleted file mode 100644
index d0f36b00e65..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Pixmap.pod
+++ /dev/null
@@ -1,64 +0,0 @@
-# Copyright (c) 1996, Expert Interface Technologies
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-# The file man.macros and some of the macros used by this file are
-# copyrighted: (c) 1990 The Regents of the University of California.
-# (c) 1994-1995 Sun Microsystems, Inc.
-# The license terms of the Tcl/Tk distribution are in the file
-# license.tcl.
-
-=head1 NAME
-
-Tk::Pixmap - Create color images from XPM files.
-
-=for category Tk Image Classes
-
-=head1 SYNOPSIS
-
-S< >I<$widget>-E<gt>B<Pixmap>?(I<name>?,I<options>?)?
-
-=head1 DESCRIPTION
-
-XPM is a popular X Window image file format for storing color icons.
-The B<Pixmap> image type can be used to create color images using XPM files.
-
-Pixmaps support the following I<options>:
-
-=over 4
-
-=item B<-data> =E<gt> I<string>
-
-Specifies the contents of the source pixmap as a string. The string
-must adhere to the XPM file format (e.g., as generated by the
-B<pixmap(1)> program). If both the B<-data> and B<-file>
-options are specified, the B<-data> option takes precedence.
-Please note that the XPM file parsing code in the xpm library is
-somewhat fragile. The first line of the string must be "B</* XPM>
-*/" or otherwise a segmatation fault will be caused.
-
-=item B<-file> =E<gt> I<name>
-
-I<name> gives the name of a file whose contents define the source
-pixmap. The file must adhere to the XPM file format (e.g., as
-generated by the B<pixmap(1)> program).
-
-=back
-
-=head1 IMAGE METHODS
-
-When a pixmap image is created, Tk also creates a new object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-
-=head1 SEE ALSO
-
-L<Tk::Image|Tk::Image>
-
-=head1 KEYWORDS
-
-pixmap, image, tix
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Popup.pod b/Master/tlpkg/tlperl/lib/Tk/Popup.pod
deleted file mode 100644
index 8d40a4ed275..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Popup.pod
+++ /dev/null
@@ -1,89 +0,0 @@
-
-=head1 NAME
-
-Tk::Wm::Popup - popup dialog windows.
-
-=for pm Tk/Wm.pm
-
-=for category Tk Toplevel widgets
-
-=head1 SYNOPSIS
-
- $dialog->Popup(qw/
- -popover => 'cursor' | $widget | undef,
- -overanchor => c | n | ne | e | se | s | sw | w | nw,
- -popanchor => c | n | ne | e | se | s | sw | w | nw,
- /);
-
-=head1 DESCRIPTION
-
-You've probably had occasion to use a Dialog (or DialogBox)
-widget. These widgets are derived from a Toplevel (which is a subclass
-of Tk::Wm, the window manager) and spend most of their time in a
-withdrawn state. It's also common to use Toplevels as containers for
-custom built popup windows. Menus, too, are dialogs derived from the
-window manager class. For this discussion, we'll use the simple term
-I<dialog> to refer any widget that pops up and awaits user
-interaction, whether it be a Menu, a special purpose Toplevel, or any
-of the dialog-type widgets, including, but not limited to, ColorEditor,
-Dialog, DialogBox, ErrorDialog, FileSelect, FBox, getOpenFile and
-getSaveFile.
-
-When it's time to display these dialogs, we call the Perl/Tk
-window manager B<Popup> method. B<Popup> accepts three special purpose
-options that specify placement information in high-level terms rather
-than numerical coordinates. It is B<Popup>'s responsibility to take
-our human specifications and turn them into actual screen
-coordinates before displaying the dialog.
-
-We can direct the dialog to appear in two general locations, either
-over another window (e.g. the root window (screen) or a particular
-widget), or over the cursor. This is called the I<popover
-location>. Once we've made this decision we can further refine the
-exact placement of the dialog relative to the popover location by
-specifying the intersection of two I<anchor points>. The I<popanchor
-point> is associated with the dialog and the I<overanchor point> is
-associated with the popover location (whether it be a window or the
-cursor). The point where the two anchor points coincide is the I<popup
-locus>. Anchor points are string values and can be I<c> (for center),
-or any of the eight cardinal compass points: I<n>, I<ne>, I<e>, I<se>,
-I<s>, I<sw>, I<w> or I<nw>.
-
-For example, if I<-popover> specifies a widget, I<-popanchor> is I<sw>,
-and I<-overanchor> is I<ne>, the the dialog's southwest corner pops up
-at the widget's northeast corner.
-
-=head1 OPTIONS
-
-The options recognized by B<Popup> are as follows:
-
-=over 4
-
-=item B<-popover>
-
-Specifies whether the dialog "pops over" a window or the cursor.
-It may be the string I<cursor>, a widget reference, or undef for the
-root window.
-
-=item B<-popanchor>
-
-Specifies the anchor point of the dialog. For instance, if I<e> is
-specified, the right side of the dialog is the anchor.
-
-=item B<-overanchor>
-
-Specifies where the dialog should anchor relative to the popover
-location. For instance, if I<e> is specified the dialog appears over
-the right side of the popover location and if it's I<ne> the the
-dialog is positioned at the upper-right corner of the popover location.
-
-=back
-
-=head1 AUTHOR
-
-Nick Ing-Simmons, Steve Lidie
-
-This code is distributed under the same terms as Perl.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/ROText.pod b/Master/tlpkg/tlperl/lib/Tk/ROText.pod
deleted file mode 100644
index b442164ae72..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/ROText.pod
+++ /dev/null
@@ -1,48 +0,0 @@
-
-=head1 NAME
-
-Tk::ROText - 'readonly' perl/Tk Text widget
-
-=for pm Tk/ROText.pm
-
-=for category Derived Widgets
-
-=head1 SYNOPSIS
-
- use Tk::ROText;
- ...
- $ro = $mw->ROText(?options,...?);
-
-=head1 DESCRIPTION
-
-This "I<IS A>" text widget with all bindings removed that would alter
-the contents of the text widget. The contents can still be modified
-via method calls.
-
-=head2 BINDINGS
-
-Only read-only bindings from L<Tk::Text> are available in
-B<Tk::ROText>. Additionally the following bindings are defined:
-
-=over
-
-=item <space>
-
-Move the cursor forward by one screenful.
-
-=item <BackSpace>
-
-Move the cursor backward by one screenful.
-
-=back
-
-=head1 KEYWORDS
-
-widget, text, readonly
-
-=head1 SEE ALSO
-
-L<Tk::Text>
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Radiobutton.pod b/Master/tlpkg/tlperl/lib/Tk/Radiobutton.pod
deleted file mode 100644
index 82fad4893fd..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Radiobutton.pod
+++ /dev/null
@@ -1,333 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Radiobutton - Create and manipulate Radiobutton widgets
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
-I<$radiobutton> = I<$parent>-E<gt>B<Radiobutton>(?I<options>?);
-
-=head1 STANDARD OPTIONS
-
-B<-activebackground>
-B<-activeforeground>
-B<-anchor>
-B<-background>
-B<-bitmap>
-B<-borderwidth>
-B<-compound>
-B<-cursor>
-B<-disabledforeground>
-B<-font>
-B<-foreground>
-B<-highlightbackground>
-B<-highlightcolor>
-B<-highlightthickness>
-B<-image>
-B<-justify>
-B<-padx>
-B<-pady>
-B<-relief>
-B<-takefocus>
-B<-text>
-B<-textvariable>
-B<-underline>
-B<-wraplength>
-
-See L<Tk::options> for details of the standard options.
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<command>
-
-=item Class: B<Command>
-
-=item Switch: B<-command>
-
-Specifies a L<perl/Tk callback|Tk::callbacks> to associate with the button. This command
-is typically invoked when mouse button 1 is released over the button
-window. The button's global variable (B<-variable> option) will
-be updated before the command is invoked.
-
-=item Name: B<height>
-
-=item Class: B<Height>
-
-=item Switch: B<-height>
-
-Specifies a desired height for the button.
-If an image or bitmap is being displayed in the button then the value is in
-screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>);
-for text it is in lines of text.
-If this option isn't specified, the button's desired height is computed
-from the size of the image or bitmap or text being displayed in it.
-
-=item Name: B<indicatorOn>
-
-=item Class: B<IndicatorOn>
-
-=item Switch: B<-indicatoron>
-
-Specifies whether or not the indicator should be drawn. Must be a
-proper boolean value. If false, the B<relief> option is
-ignored and the widget's relief is always sunken if the widget is
-selected and raised otherwise.
-
-=item Command-Line Name: B<-offrelief>
-
-=item Database Name: B<offRelief>
-
-=item Database Class: B<OffRelief>
-
-Specifies the relief for the checkbutton when the indicator is not
-drawn and the checkbutton is off. The default value is B<raised>. By
-setting this option to B<flat> and setting
-B<-indicatoron false -overrelief raised>, the effect is achieved of
-having a flat button
-that raises on mouse-over and which is depressed when activated. This
-is the behavior typically exhibited by the Bold, Italic, and
-Underline checkbuttons on the toolbar of a word-processor, for
-example.
-
-=item Command-Line Name: B<-overrelief>
-
-=item Database Name: B<overRelief>
-
-=item Database Class: B<OverRelief>
-
-Specifies an alternative relief for the button, to be used when
-the mouse cursor is over the widget. This option can be used to
-make toolbar buttons, by configuring B<-relief flat -overrelief
-raised>. If the value of this option is the empty string, then
-no alternative relief is used when the mouse cursor is over the
-button. The empty string is the default value.
-
-=item Name: B<selectColor>
-
-=item Class: B<Background>
-
-=item Switch: B<-selectcolor>
-
-Specifies a background color to use when the button is selected.
-If B<indicatorOn> is true then the color applies to the indicator.
-Under Windows, this color is used as the background for the indicator
-regardless of the select state.
-If B<indicatorOn> is false, this color is used as the background
-for the entire widget, in place of B<background> or B<activeBackground>,
-whenever the widget is selected.
-If specified as an empty string then no special color is used for
-displaying when the widget is selected.
-
-=item Name: B<selectImage>
-
-=item Class: B<SelectImage>
-
-=item Switch: B<-selectimage>
-
-Specifies an image to display (in place of the B<image> option)
-when the radiobutton is selected.
-This option is ignored unless the B<image> option has been
-specified.
-
-=item Name: B<state>
-
-=item Class: B<State>
-
-=item Switch: B<-state>
-
-Specifies one of three states for the radiobutton: B<normal>, B<active>,
-or B<disabled>. In normal state the radiobutton is displayed using the
-B<foreground> and B<background> options. The active state is
-typically used when the pointer is over the radiobutton. In active state
-the radiobutton is displayed using the B<activeForeground> and
-B<activeBackground> options. Disabled state means that the radiobutton
-should be insensitive: the default bindings will refuse to activate
-the widget and will ignore mouse button presses.
-In this state the B<disabledForeground> and
-B<background> options determine how the radiobutton is displayed.
-
-=item Name: B<value>
-
-=item Class: B<Value>
-
-=item Switch: B<-value>
-
-Specifies value to store in the button's associated variable whenever
-this button is selected.
-
-=item Name: B<variable>
-
-=item Class: B<Variable>
-
-=item Switch: B<-variable>
-
-Specifies reference to a variable to set whenever this button is
-selected. Changes in this variable also cause the button to select
-or deselect itself. Defaults to the value C<\$Tk::selectedButton>.
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-=item Switch: B<-width>
-
-Specifies a desired width for the button.
-If an image or bitmap is being displayed in the button, the value is in
-screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>);
-for text it is in characters.
-If this option isn't specified, the button's desired width is computed
-from the size of the image or bitmap or text being displayed in it.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Radiobutton> method creates a new window (given by the
-$widget argument) and makes it into a radiobutton widget.
-Additional
-options, described above, may be specified on the command line
-or in the option database
-to configure aspects of the radiobutton such as its colors, font,
-text, and initial relief. The B<radiobutton> command returns its
-$widget argument. At the time this command is invoked,
-there must not exist a window named $widget, but
-$widget's parent must exist.
-
-A radiobutton is a widget that displays a textual string, bitmap or image
-and a diamond or circle called an I<indicator>.
-If text is displayed, it must all be in a single font, but it
-can occupy multiple lines on the screen (if it contains newlines
-or if wrapping occurs because of the B<wrapLength> option) and
-one of the characters may optionally be underlined using the
-B<underline> option. A radiobutton has
-all of the behavior of a simple button: it can display itself in either
-of three different ways, according to the B<state> option;
-it can be made to appear
-raised, sunken, or flat; it can be made to flash; and it invokes
-a L<perl/Tk callback|Tk::callbacks> whenever mouse button 1 is clicked over the
-check button.
-
-In addition, radiobuttons can be I<selected>.
-If a radiobutton is selected, the indicator is normally
-drawn with a selected appearance, and
-a Tcl variable associated with the radiobutton is set to a particular
-value (normally 1).
-Under Unix, the indicator is drawn with a sunken relief and a special
-color. Under Windows, the indicator is drawn with a round mark inside.
-If the radiobutton is not selected, then the indicator is drawn with a
-deselected appearance, and the associated variable is
-set to a different value (typically 0).
-Under Unix, the indicator is drawn with a raised relief and no special
-color. Under Windows, the indicator is drawn without a round mark inside.
-Typically, several radiobuttons share a single variable and the
-value of the variable indicates which radiobutton is to be selected.
-When a radiobutton is selected it sets the value of the variable to
-indicate that fact; each radiobutton also monitors the value of
-the variable and automatically selects and deselects itself when the
-variable's value changes.
-By default the variable B<selectedButton>
-is used; its contents give the name of the button that is
-selected, or the empty string if no button associated with that
-variable is selected.
-The name of the variable for a radiobutton,
-plus the variable to be stored into it, may be modified with options
-on the command line or in the option database.
-Configuration options may also be used to modify the way the
-indicator is displayed (or whether it is displayed at all).
-By default a radiobutton is configured to select itself on button clicks.
-
-=head1 WIDGET METHODS
-
-The B<Radiobutton> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-The following additional methods are available for radiobutton widgets:
-
-=over 4
-
-=item I<$radiobutton>-E<gt>B<deselect>
-
-Deselects the radiobutton and sets the associated variable to an
-empty string.
-If this radiobutton was not currently selected, the command has
-no effect.
-
-=item I<$radiobutton>-E<gt>B<flash>
-
-Flashes the radiobutton. This is accomplished by redisplaying the radiobutton
-several times, alternating between active and normal colors. At
-the end of the flash the radiobutton is left in the same normal/active
-state as when the command was invoked.
-This command is ignored if the radiobutton's state is B<disabled>.
-
-=item I<$radiobutton>-E<gt>B<invoke>
-
-Does just what would have happened if the user invoked the radiobutton
-with the mouse: selects the button and invokes
-its associated Tcl command, if there is one.
-The return value is the return value from the Tcl command, or an
-empty string if there is no command associated with the radiobutton.
-This command is ignored if the radiobutton's state is B<disabled>.
-
-=item I<$radiobutton>-E<gt>B<select>
-
-Selects the radiobutton and sets the associated variable to the
-value corresponding to this widget.
-
-=back
-
-=head1 BINDINGS
-
-Tk automatically creates class bindings for radiobuttons that give them
-the following default behavior:
-
-=over 4
-
-=item [1]
-
-On Unix systems, a radiobutton activates whenever the mouse passes
-over it and deactivates whenever the mouse leaves the radiobutton. On
-Mac and Windows systems, when mouse button 1 is pressed over a
-radiobutton, the button activates whenever the mouse pointer is inside
-the button, and deactivates whenever the mouse pointer leaves the
-button.
-
-=item [2]
-
-When mouse button 1 is pressed over a radiobutton it is invoked (it
-becomes selected and the command associated with the button is
-invoked, if there is one).
-
-=item [3]
-
-When a radiobutton has the input focus, the space key causes the radiobutton
-to be invoked.
-
-If the radiobutton's state is B<disabled> then none of the above
-actions occur: the radiobutton is completely non-responsive.
-
-The behavior of radiobuttons can be changed by defining new bindings for
-individual widgets or by redefining the class bindings.
-
-=back
-
-=head1 KEYWORDS
-
-radiobutton, widget
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Scale.pod b/Master/tlpkg/tlperl/lib/Tk/Scale.pod
deleted file mode 100644
index f7de2390bba..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Scale.pod
+++ /dev/null
@@ -1,356 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Scale - Create and manipulate Scale widgets
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
-I<$scale> = I<$parent>-E<gt>B<Scale>(?I<options>?);
-
-=head1 STANDARD OPTIONS
-
-B<-activebackground> B<-font> B<-highlightthickness> B<-repeatinterval>
-B<-background> B<-foreground> B<-orient> B<-takefocus>
-B<-borderwidth> B<-highlightbackground> B<-relief> B<-troughcolor>
-B<-cursor> B<-highlightcolor> B<-repeatdelay>
-
-See L<Tk::options> for details of the standard options.
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<bigIncrement>
-
-=item Class: B<BigIncrement>
-
-=item Switch: B<-bigincrement>
-
-Some interactions with the scale cause its value to change by
-``large'' increments; this option specifies the size of the
-large increments. If specified as 0, the large increments default
-to 1/10 the range of the scale.
-
-=item Name: B<command>
-
-=item Class: B<Command>
-
-=item Switch: B<-command>
-
-Specifies the prefix of a L<perl/Tk callback|Tk::callbacks> to invoke whenever the scale's
-value is changed via a method.
-The actual command consists
-of this option followed by a space and a real number indicating the
-new value of the scale.
-
-=item Name: B<digits>
-
-=item Class: B<Digits>
-
-=item Switch: B<-digits>
-
-An integer specifying how many significant digits should be retained
-when converting the value of the scale to a string.
-If the number is less than or equal to zero, then the scale picks
-the smallest value that guarantees that every possible slider
-position prints as a different string.
-
-=item Name: B<from>
-
-=item Class: B<From>
-
-=item Switch: B<-from>
-
-A real value corresponding to the left or top end of the scale.
-
-=item Name: B<label>
-
-=item Class: B<Label>
-
-=item Switch: B<-label>
-
-A string to display as a label for the scale. For
-vertical scales the label is displayed just to the right of the
-top end of the scale. For horizontal scales the label is displayed
-just above the left end of the scale. If the option is specified
-as an empty string, no label is displayed.
-
-=item Name: B<length>
-
-=item Class: B<Length>
-
-=item Switch: B<-length>
-
-Specifies the desired long dimension of the scale in screen units
-(i.e. any of the forms acceptable to B<Tk_GetPixels>).
-For vertical scales this is the scale's height; for horizontal scales
-it is the scale's width.
-
-=item Name: B<resolution>
-
-=item Class: B<Resolution>
-
-=item Switch: B<-resolution>
-
-A real value specifying the resolution for the scale.
-If this value is greater than zero then the scale's value will always be
-rounded to an even multiple of this value, as will tick marks and
-the endpoints of the scale. If the value is less than zero then no
-rounding occurs. Defaults to 1 (i.e., the value will be integral).
-
-=item Name: B<showValue>
-
-=item Class: B<ShowValue>
-
-=item Switch: B<-showvalue>
-
-Specifies a boolean value indicating whether or not the current
-value of the scale is to be displayed.
-
-=item Name: B<sliderLength>
-
-=item Class: B<SliderLength>
-
-=item Switch: B<-sliderlength>
-
-Specfies the size of the slider, measured in screen units along the slider's
-long dimension. The value may be specified in any of the forms acceptable
-to B<Tk_GetPixels>.
-
-=item Name: B<sliderRelief>
-
-=item Class: B<SliderRelief>
-
-=item Switch: B<-sliderrelief>
-
-Specifies the relief to use when drawing the slider, such as B<raised>
-or B<sunken>.
-
-=item Name: B<state>
-
-=item Class: B<State>
-
-=item Switch: B<-state>
-
-Specifies one of three states for the scale: B<normal>,
-B<active>, or B<disabled>.
-If the scale is disabled then the value may not be changed and the scale
-won't activate.
-If the scale is active, the slider is displayed using the color
-specified by the B<activeBackground> option.
-
-=item Name: B<tickInterval>
-
-=item Class: B<TickInterval>
-
-=item Switch: B<-tickinterval>
-
-Must be a real value.
-Determines the spacing between numerical
-tick marks displayed below or to the left of the slider.
-If 0, no tick marks will be displayed.
-
-=item Name: B<to>
-
-=item Class: B<To>
-
-=item Switch: B<-to>
-
-Specifies a real value corresponding
-to the right or bottom end of the scale.
-This value may be either less than or greater than the B<from> option.
-
-=item Name: B<variable>
-
-=item Class: B<Variable>
-
-=item Switch: B<-variable>
-
-Specifies the name of a global variable to link to the scale. Whenever the
-value of the variable changes, the scale will update to reflect this
-value.
-Whenever the scale is manipulated interactively, the variable
-will be modified to reflect the scale's new value.
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-=item Switch: B<-width>
-
-Specifies the desired narrow dimension of the trough in screen units
-(i.e. any of the forms acceptable to B<Tk_GetPixels>).
-For vertical scales this is the trough's width; for horizontal scales
-this is the trough's height.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Scale> method creates a new window (given by the
-$widget argument) and makes it into a scale widget.
-Additional
-options, described above, may be specified on the command line
-or in the option database
-to configure aspects of the scale such as its colors, orientation,
-and relief. The B<scale> command returns its
-$widget argument. At the time this command is invoked,
-there must not exist a window named $widget, but
-$widget's parent must exist.
-
-A scale is a widget that displays a rectangular I<trough> and a
-small I<slider>. The trough corresponds to a range
-of real values (determined by the B<from>, B<to>, and
-B<resolution> options),
-and the position of the slider selects a particular real value.
-The slider's position (and hence the scale's value) may be adjusted
-with the mouse or keyboard as described in
-the L<"BINDINGS"> section below. Whenever the scale's value is changed, a Tcl
-command is invoked (using the B<command> option) to notify
-other interested widgets of the change.
-In addition, the value
-of the scale can be linked to a Tcl variable (using the B<variable>
-option), so that changes in either are reflected in the other.
-
-Three annotations may be displayed in a scale widget: a label
-appearing at the top right of the widget (top left for horizontal
-scales), a number displayed just to the left of the slider
-(just above the slider for horizontal scales), and a collection
-of numerical tick marks just to the left of the current value
-(just below the trough for horizontal scales). Each of these three
-annotations may be enabled or disabled using the
-configuration options.
-
-=head1 WIDGET METHODS
-
-The B<Scale> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-The following additional methods are available for scale widgets:
-
-=over 4
-
-=item I<$scale>-E<gt>B<coords>(?I<value>?)
-
-Returns a list whose elements are the x and y coordinates of
-the point along the centerline of the trough that corresponds
-to I<value>.
-If I<value> is omitted then the scale's current value is used.
-
-=item I<$scale>-E<gt>B<get>(?I<x, y>?)
-
-If I<x> and I<y> are omitted, returns the current value
-of the scale. If I<x> and I<y> are specified, they give
-pixel coordinates within the widget; the command returns
-the scale value corresponding to the given pixel.
-Only one of I<x> or I<y> is used: for horizontal scales
-I<y> is ignored, and for vertical scales I<x> is ignored.
-
-=item I<$scale>-E<gt>B<identify>(I<x, y>)
-
-Returns a string indicating what part of the scale lies under
-the coordinates given by I<x> and I<y>.
-A return value of B<slider> means that the point is over
-the slider; B<trough1> means that the point is over the
-portion of the slider above or to the left of the slider;
-and B<trough2> means that the point is over the portion
-of the slider below or to the right of the slider.
-If the point isn't over one of these elements, an empty string
-is returned.
-
-=item I<$scale>-E<gt>B<set>(I<value>)
-
-This command is invoked to change the current value of the scale,
-and hence the position at which the slider is displayed. I<Value>
-gives the new value for the scale.
-The command has no effect if the scale is disabled.
-
-=back
-
-=head1 BINDINGS
-
-Tk automatically creates class bindings for scales that give them
-the following default behavior.
-Where the behavior is different for vertical and horizontal scales,
-the horizontal behavior is described in parentheses.
-
-=over 4
-
-=item [1]
-
-If button 1 is pressed in the trough, the scale's value will
-be incremented or decremented by the value of the B<resolution>
-option so that the slider moves in the direction of the cursor.
-If the button is held down, the action auto-repeats.
-
-=item [2]
-
-If button 1 is pressed over the slider, the slider can be dragged
-with the mouse.
-
-=item [3]
-
-If button 1 is pressed in the trough with the Control key down,
-the slider moves all the way to the end of its range, in the
-direction towards the mouse cursor.
-
-=item [4]
-
-If button 2 is pressed, the scale's value is set to the mouse
-position. If the mouse is dragged with button 2 down, the scale's
-value changes with the drag.
-
-=item [5]
-
-The Up and Left keys move the slider up (left) by the value
-of the B<resolution> option.
-
-=item [6]
-
-The Down and Right keys move the slider down (right) by the value
-of the B<resolution> option.
-
-=item [7]
-
-Control-Up and Control-Left move the slider up (left) by the
-value of the B<bigIncrement> option.
-
-=item [8]
-
-Control-Down and Control-Right move the slider down (right) by the
-value of the B<bigIncrement> option.
-
-=item [9]
-
-Home moves the slider to the top (left) end of its range.
-
-=item [10]
-
-End moves the slider to the bottom (right) end of its range.
-
-If the scale is disabled using the B<state> option then
-none of the above bindings have any effect.
-
-The behavior of scales can be changed by defining new bindings for
-individual widgets or by redefining the class bindings.
-
-=back
-
-=head1 KEYWORDS
-
-scale, slider, trough, widget
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Scrollbar.pod b/Master/tlpkg/tlperl/lib/Tk/Scrollbar.pod
deleted file mode 100644
index 838eb97e666..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Scrollbar.pod
+++ /dev/null
@@ -1,429 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Scrollbar - Create and manipulate Scrollbar widgets
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
-I<$scrollbar> = I<$parent>-E<gt>B<Scrollbar>(?I<options>?);
-
-=head1 STANDARD OPTIONS
-
-B<-activebackground> B<-highlightbackground> B<-orient> B<-takefocus>
-B<-background> B<-highlightcolor> B<-relief> B<-troughcolor>
-B<-borderwidth> B<-highlightthickness> B<-repeatdelay>
-B<-cursor> B<-jump> B<-repeatinterval>
-
-See L<Tk::options> for details of the standard options.
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<activeRelief>
-
-=item Class: B<ActiveRelief>
-
-=item Switch: B<-activerelief>
-
-Specifies the relief to use when displaying the element that is
-active, if any.
-Elements other than the active element are always displayed with
-a raised relief.
-
-=item Name: B<command>
-
-=item Class: B<Command>
-
-=item Switch: B<-command>
-
-Specifies a callback to invoke to change the view
-in the widget associated with the scrollbar. When a user requests
-a view change by manipulating the scrollbar, the callback is
-invoked. The callback is passed
-additional arguments as described later. This option almost always has
-a value such as B<[xview =E<gt> $widget]> or B<[yview =E<gt> $widget]>, consisting of the
-a widget object and either B<xview> (if the scrollbar is for
-horizontal scrolling) or B<yview> (for vertical scrolling).
-All scrollable widgets have B<xview> and B<yview> methods
-that take exactly the additional arguments appended by the scrollbar
-as described in L<"SCROLLING COMMANDS"> below.
-
-=item Name: B<elementBorderWidth>
-
-=item Class: B<BorderWidth>
-
-=item Switch: B<-elementborderwidth>
-
-Specifies the width of borders drawn around the internal elements
-of the scrollbar (the two arrows and the slider). The value may
-have any of the forms acceptable to B<Tk_GetPixels>.
-If this value is less than zero, the value of the B<borderWidth>
-option is used in its place.
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-=item Switch: B<-width>
-
-Specifies the desired narrow dimension of the scrollbar window,
-not including 3-D border, if any. For vertical
-scrollbars this will be the width and for horizontal scrollbars
-this will be the height.
-The value may have any of the forms acceptable to B<Tk_GetPixels>.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Scrollbar> method creates a new window (given by the
-$widget argument) and makes it into a scrollbar widget.
-Additional options, described above, may be specified on the command
-line or in the option database to configure aspects of the scrollbar
-such as its colors, orientation, and relief.
-The B<scrollbar> command returns its $widget argument.
-At the time this command is invoked, there must not exist a window
-named $widget, but $widget's parent must exist.
-
-A scrollbar is a widget that displays two arrows, one at each end of
-the scrollbar, and a I<slider> in the middle portion of the
-scrollbar.
-It provides information about what is visible in an I<associated window>
-that displays an document of some sort (such as a file being edited or
-a drawing).
-The position and size of the slider indicate which portion of the
-document is visible in the associated window. For example, if the
-slider in a vertical scrollbar covers the top third of the area
-between the two arrows, it means that the associated window displays
-the top third of its document.
-
-Scrollbars can be used to adjust the view in the associated window
-by clicking or dragging with the mouse.
-See L<"BINDINGS"> below for details.
-
-=head1 ELEMENTS
-
-A scrollbar displays five elements, which are referred to in the
-methods for the scrollbar:
-
-=over 4
-
-=item B<arrow1>
-
-The top or left arrow in the scrollbar.
-
-=item B<trough1>
-
-The region between the slider and B<arrow1>.
-
-=item B<slider>
-
-The rectangle that indicates what is visible in the associated widget.
-
-=item B<trough2>
-
-The region between the slider and B<arrow2>.
-
-=item B<arrow2>
-
-The bottom or right arrow in the scrollbar.
-
-=back
-
-=head1 WIDGET METHODS
-
-The B<Scrollbar> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-The following additional methods are available for scrollbar widgets:
-
-=over 4
-
-=item I<$scrollbar>-E<gt>B<activate>(?I<element>?)
-
-Marks the element indicated by I<element> as active, which
-causes it to be displayed as specified by the B<activeBackground>
-and B<activeRelief> options.
-The only element values understood by this command are B<arrow1>,
-B<slider>, or B<arrow2>.
-If any other value is specified then no element of the scrollbar
-will be active.
-If I<element> is not specified, the command returns
-the name of the element that is currently active, or an empty string
-if no element is active.
-
-=item I<$scrollbar>-E<gt>B<delta>(I<deltaX, deltaY>)
-
-Returns a real number indicating the fractional change in
-the scrollbar setting that corresponds to a given change
-in slider position. For example, if the scrollbar is horizontal,
-the result indicates how much the scrollbar setting must change
-to move the slider I<deltaX> pixels to the right (I<deltaY> is
-ignored in this case).
-If the scrollbar is vertical, the result indicates how much the
-scrollbar setting must change to move the slider I<deltaY> pixels
-down. The arguments and the result may be zero or negative.
-
-=item I<$scrollbar>-E<gt>B<fraction>(I<x, y>)
-
-Returns a real number between 0 and 1 indicating where the point
-given by I<x> and I<y> lies in the trough area of the scrollbar.
-The value 0 corresponds to the top or left of the trough, the
-value 1 corresponds to the bottom or right, 0.5 corresponds to
-the middle, and so on.
-I<X> and I<y> must be pixel coordinates relative to the scrollbar
-widget.
-If I<x> and I<y> refer to a point outside the trough, the closest
-point in the trough is used.
-
-=item I<$scrollbar>-E<gt>B<get>
-
-Returns the scrollbar settings in the form of a list whose
-elements are the arguments to the most recent B<set> method.
-
-=item I<$scrollbar>-E<gt>B<identify>(I<x, y>)
-
-Returns the name of the element under the point given by I<x> and
-I<y> (such as B<arrow1>), or an empty string if the point does
-not lie in any element of the scrollbar.
-I<X> and I<y> must be pixel coordinates relative to the scrollbar
-widget.
-
-=item I<$scrollbar>-E<gt>B<set>(I<first, last>)
-
-This command is invoked by the scrollbar's associated widget to
-tell the scrollbar about the current view in the widget.
-The command takes two arguments, each of which is a real fraction
-between 0 and 1.
-The fractions describe the range of the document that is visible in
-the associated widget.
-For example, if I<first> is 0.2 and I<last> is 0.4, it means
-that the first part of the document visible in the window is 20%
-of the way through the document, and the last visible part is 40%
-of the way through.
-
-=back
-
-=head1 SCROLLING COMMANDS
-
-When the user interacts with the scrollbar, for example by dragging
-the slider, the scrollbar notifies the associated widget that it
-must change its view.
-The scrollbar makes the notification by evaluating a callback
-specified as the scrollbar's B<-command> option.
-The callback may take several forms.
-In each case, the intial arguments passed are those
-specified in the B<-command> callback itself,
-which usually has a form like [B<yview> =E<gt> I<$widget>].
-(Which will invoke I<$widget>-E<gt>B<yview>(...) where
-the ... part is as below. See L<Tk::callbacks> for details.)
-The callback is passed additional arguments as follows:
-
-=over 4
-
-=item B<moveto>,I<fraction>
-
-I<Fraction> is a real number between 0 and 1.
-The widget should adjust its view so that the point given
-by I<fraction> appears at the beginning of the widget.
-If I<fraction> is 0 it refers to the beginning of the
-document. 1.0 refers to the end of the document, 0.333
-refers to a point one-third of the way through the document,
-and so on.
-
-=item B<scroll,>I<number,>B<units>
-
-The widget should adjust its view by I<number> units.
-The units are defined in whatever way makes sense for the widget,
-such as characters or lines in a text widget.
-I<Number> is either 1, which means one unit should scroll off
-the top or left of the window, or -1, which means that one unit
-should scroll off the bottom or right of the window.
-
-=item B<scroll>,I<number>,B<page>
-
-The widget should adjust its view by I<number> pages.
-It is up to the widget to define the meaning of a page; typically
-it is slightly less than what fits in the window, so that there
-is a slight overlap between the old and new views.
-I<Number> is either 1, which means the next page should
-become visible, or -1, which means that the previous page should
-become visible.
-
-=back
-
-=head1 OLD COMMAND SYNTAX
-
-In versions of Tk before 4.0, the B<set> and B<get> widget
-commands used a different form.
-This form is still supported for backward compatibility, but it
-is deprecated.
-In the old command syntax, the B<set> method has the
-following form:
-
-=over 4
-
-=item I<$scrollbar>-E<gt>B<set>(I<totalUnits, windowUnits, firstUnit, lastUnit>)
-
-In this form the arguments are all integers.
-I<TotalUnits> gives the total size of the object being displayed in the
-associated widget. The meaning of one unit depends on the associated
-widget; for example, in a text editor widget units might
-correspond to lines of
-text. I<WindowUnits> indicates the total number of units that
-can fit in the associated window at one time. I<FirstUnit>
-and I<lastUnit> give the indices of the first and last units
-currently visible in the associated window (zero corresponds to the
-first unit of the object).
-
-=back
-
-Under the old syntax the B<get> method returns a list
-of four integers, consisting of the I<totalUnits>, I<windowUnits>,
-I<firstUnit>, and I<lastUnit> values from the last B<set>
-method.
-
-The callbacks generated by scrollbars also have a different form
-when the old syntax is being used, the callback is passed a single argument:
-
-=over 4
-
-=item I<unit>
-
-I<Unit> is an integer that indicates what should appear at
-the top or left of the associated widget's window.
-It has the same meaning as the I<firstUnit> and I<lastUnit>
-arguments to the B<set> method.
-
-=back
-
-The most recent B<set> method determines whether or not
-to use the old syntax.
-If it is given two real arguments then the new syntax will be
-used in the future, and if it is given four integer arguments then
-the old syntax will be used.
-
-=head1 BINDINGS
-
-Tk automatically creates class bindings for scrollbars that give them
-the following default behavior.
-If the behavior is different for vertical and horizontal scrollbars,
-the horizontal behavior is described in parentheses.
-
-=over 4
-
-=item [1]
-
-Pressing button 1 over B<arrow1> causes the view in the
-associated widget to shift up (left) by one unit so that the
-document appears to move down (right) one unit.
-If the button is held down, the action auto-repeats.
-
-=item [2]
-
-Pressing button 1 over B<trough1> causes the view in the
-associated widget to shift up (left) by one screenful so that the
-document appears to move down (right) one screenful.
-If the button is held down, the action auto-repeats.
-
-=item [3]
-
-Pressing button 1 over the slider and dragging causes the view
-to drag with the slider.
-If the B<jump> option is true, then the view doesn't drag along
-with the slider; it changes only when the mouse button is released.
-
-=item [4]
-
-Pressing button 1 over B<trough2> causes the view in the
-associated widget to shift down (right) by one screenful so that the
-document appears to move up (left) one screenful.
-If the button is held down, the action auto-repeats.
-
-=item [5]
-
-Pressing button 1 over B<arrow2> causes the view in the
-associated widget to shift down (right) by one unit so that the
-document appears to move up (left) one unit.
-If the button is held down, the action auto-repeats.
-
-=item [6]
-
-If button 2 is pressed over the trough or the slider, it sets
-the view to correspond to the mouse position; dragging the
-mouse with button 2 down causes the view to drag with the mouse.
-If button 2 is pressed over one of the arrows, it causes the
-same behavior as pressing button 1.
-
-=item [7]
-
-If button 1 is pressed with the Control key down, then if the
-mouse is over B<arrow1> or B<trough1> the view changes
-to the very top (left) of the document; if the mouse is over
-B<arrow2> or B<trough2> the view changes
-to the very bottom (right) of the document; if the mouse is
-anywhere else then the button press has no effect.
-
-=item [8]
-
-In vertical scrollbars the Up and Down keys have the same behavior
-as mouse clicks over B<arrow1> and B<arrow2>, respectively.
-In horizontal scrollbars these keys have no effect.
-
-=item [9]
-
-In vertical scrollbars Control-Up and Control-Down have the same
-behavior as mouse clicks over B<trough1> and B<trough2>, respectively.
-In horizontal scrollbars these keys have no effect.
-
-=item [10]
-
-In horizontal scrollbars the Up and Down keys have the same behavior
-as mouse clicks over B<arrow1> and B<arrow2>, respectively.
-In vertical scrollbars these keys have no effect.
-
-=item [11]
-
-In horizontal scrollbars Control-Up and Control-Down have the same
-behavior as mouse clicks over B<trough1> and B<trough2>, respectively.
-In vertical scrollbars these keys have no effect.
-
-=item [12]
-
-The Prior and Next keys have the same behavior
-as mouse clicks over B<trough1> and B<trough2>, respectively.
-
-=item [13]
-
-The Home key adjusts the view to the top (left edge) of the document.
-
-=item [14]
-
-The End key adjusts the view to the bottom (right edge) of the document.
-
-=back
-
-=head1 SEE ALSO
-
-L<Tk::callbacks|Tk::callbacks>
-L<Tk::Scrolled|Tk::Scrolled>
-
-=head1 KEYWORDS
-
-scrollbar, widget
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Scrolled.pod b/Master/tlpkg/tlperl/lib/Tk/Scrolled.pod
deleted file mode 100644
index cd6c648ef5e..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Scrolled.pod
+++ /dev/null
@@ -1,86 +0,0 @@
-=head1 NAME
-
-Tk::Scrolled - Create a widget with attached scrollbar(s)
-
-=for category Derived Widgets
-
-=for index_group Perl/Tk Constructs
-
-=head1 SYNOPSIS
-
-S< >I<$whatever> = I<$parent>-E<gt>B<Scrolled>(I<Whatever> ?,B<-scrollbars>=E<gt>I<where>? ?,...?);
-
-=head1 DESCRIPTION
-
-To stop a flood of B<ScrlWhatever> widgets Perl/Tk introcuded the special
-constructor B<Scrolled>. B<Scrolled> creates a widget of the given Class
-I<Whatever> with attached L<scrollbar(s)|Tk::Scrollbar>.
-
-=head1 OPTIONS
-
-All options beside B<-scrollbars> explained below are passed to
-the I<Whatever> widget constructor.
-
-=over 4
-
-=item -scrollbars
-
-Expects as argument the position where the scrollbars should be
-created: B<w>, B<e> or B<n>, B<s> or a combination of
-them. If the one or both positions are prefixed with B<o> the
-scrollbar will only show up if there is a 'real' need to scroll.
-
-=back
-
-=head1 ADVERTISED SUBWIDGETS
-
-See L<Tk::mega/"Subwidget"> how to use advertised widgets.
-
-=over 4
-
-=item scrolled
-
-the scrolled widget
-
-=item I<widget>
-
-same as B<scrolled> above. I<widget> is the kind of widget passed
-to scrolled as first argument in all lowercase.
-
-=item xscrollbar
-
-the B<Scrollbar> widget used for horizontal scrolling (if it exists)
-
-=item yscrollbar
-
-the B<Scrollbar> widget used for vertical scrolling (if it exists)
-
-=item corner
-
-a frame in the corner between the vertical and horizontal scrolbar
-
-=back
-
-=head1 BUGS
-
-If a widget does not support I<-{x,y}scrollcommand> options,
-B<Scrolled> does not complain if the specified widget class does
-not support them. E.g.,
-
-S< >I<$parent>->B<Scrolled>(B<'Button'>, ...)
-
-One does not get an error message or warning when one tries to
-configure scrollbars after the widget construction:
-
-S< >I<$ascrolled>->B<configure>(B<-scrollbars> => B<'e'>);
-
-=head1 SEE ALSO
-
-L<Tk::Scrollbar|Tk::Scrollbar>
-
-=head1 KEYWORDS
-
-scrolled, scrollbar
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Spinbox.pod b/Master/tlpkg/tlperl/lib/Tk/Spinbox.pod
deleted file mode 100644
index b18b7e1b9ae..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Spinbox.pod
+++ /dev/null
@@ -1,819 +0,0 @@
-# Copyright (c) 2000 Jeffrey Hobbs.
-# Copyright (c) 2000 Ajuba Solutions.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-# RCS: @(#) $Id: spinbox.n,v 1.3 2001/12/18 23:02:35 hobbs Exp $
-
-=head1 NAME
-
-Tk::Spinbox - Create and manipulate Spinbox widgets
-
-=for category Tk Generic Methods
-
-=head1 SYNOPSIS
-
-I<$spinbox> = I<$parent>-E<gt>Spinbox(?I<options>?);
-
- -activebackground -highlightthickness -repeatinterval
- -background -insertbackground -selectbackground
- -borderwidth -insertborderwidth -selectborderwidth
- -cursor -insertontime -selectforeground
- -exportselection -insertwidth -takefocus
- -font -insertofftime -textvariable
- -foreground -justify -xscrollcommand
- -highlightbackground -relief
- -highlightcolor -repeatdelay
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Option: B<-buttonbackground>
-
-=item Name: B<buttonBackground>
-
-=item Class: B<Background>
-
-The background color to be used for the spin buttons.
-
-=item Option: B<-buttoncursor>
-
-=item Name: B<buttonCursor>
-
-=item Class: B<Cursor>
-
-The cursor to be used when over the spin buttons. If this is empty
-(the default), a default cursor will be used.
-
-=item Option: B<-buttondownrelief>
-
-=item Name: B<buttonDownRelief>
-
-=item Class: B<Relief>
-
-The relief to be used for the upper spin button.
-
-=item Option: B<-buttonuprelief>
-
-=item Name: B<buttonUpRelief>
-
-=item Class: B<Relief>
-
-The relief to be used for the lower spin button.
-
-=item Option: B<-command>
-
-=item Name: B<command>
-
-=item Class: B<Command>
-
-Specifies a Perl/Tk callback to invoke whenever a Spinbutton is invoked.
-The callback has these two arguments I<appended> to any existing callback
-arguments: the current value of the widget and the direction of the button
-press (B<up> or B<down>).
-
-=item Option: B<-disabledbackground>
-
-=item Name: B<disabledBackground>
-
-=item Class: B<DisabledBackground>
-
-Specifies the background color to use when the Spinbox is disabled. If
-this option is the empty string, the normal background color is used.
-
-=item Option: B<-disabledforeground>
-
-=item Name: B<disabledForeground>
-
-=item Class: B<DisabledForeground>
-
-Specifies the foreground color to use when the Spinbox is disabled. If
-this option is the empty string, the normal foreground color is used.
-
-=item Option: B<-format>
-
-=item Name: B<format>
-
-=item Class: B<Format>
-
-Specifies an alternate format to use when setting the string value
-when using the B<-from> and B<-to> range.
-This must be a format specifier of the form B<%E<lt>padE<gt>.E<lt>padE<gt>f>,
-as it will format a floating-point number.
-
-=item Option: B<-from>
-
-=item Name: B<from>
-
-=item Class: B<From>
-
-A floating-point value corresponding to the lowest value for a Spinbox, to
-be used in conjunction with B<-to> and B<-increment>. When all
-are specified correctly, the Spinbox will use these values to control its
-contents. This value must be less than the B<-to> option.
-If B<-values> is specified, it supercedes this option.
-
-=item Option: B<-invalidcommand>
-
-=item Alias: B<-invcmd>
-
-=item Name: B<invalidCommand>
-
-=item Class: B<InvalidCommand>
-
-Specifies a script to eval when B<validateCommand> returns 0. Setting
-it to an empty string disables this feature (the default). The best use of
-this option is to set it to I<bell>. See B<Validation> below for
-more information.
-
-=item Option: B<-increment>
-
-=item Name: B<increment>
-
-=item Class: B<Increment>
-
-A floating-point value specifying the increment. When used with
-B<-from> and B<-to>, the value in the widget will be adjusted by
-B<-increment> when a spin button is pressed (up adds the value,
-down subtracts the value).
-
-=item Option: B<-readonlybackground>
-
-=item Name: B<readonlyBackground>
-
-=item Class: B<ReadonlyBackground>
-
-Specifies the background color to use when the Spinbox is readonly. If
-this option is the empty string, the normal background color is used.
-
-=item Option: B<-state>
-
-=item Name: B<state>
-
-=item Class: B<State>
-
-Specifies one of three states for the Spinbox: B<normal>,
-B<disabled>, or B<readonly>. If the Spinbox is readonly, then the
-value may not be changed using methods and no insertion cursor
-will be displayed, even if the input focus is in the widget; the
-contents of the widget may still be selected. If the Spinbox is
-disabled, the value may not be changed, no insertion cursor will be
-displayed, the contents will not be selectable, and the Spinbox may
-be displayed in a different color, depending on the values of the
-B<-disabledforeground> and B<-disabledbackground> options.
-
-=item Option: B<-to>
-
-=item Name: B<to>
-
-=item Class: B<To>
-
-A floating-point value corresponding to the highest value for the Spinbox,
-to be used in conjunction with B<-from> and B<-increment>. When
-all are specified correctly, the Spinbox will use these values to control
-its contents. This value must be greater than the B<-from> option.
-If B<-values> is specified, it supercedes this option.
-
-=item Option: B<-validate>
-
-=item Name: B<validate>
-
-=item Class: B<Validate>
-
-Specifies the mode in which validation should operate: B<none>,
-B<focus>, B<focusin>, B<focusout>, B<key>, or B<all>.
-It defaults to B<none>. When you want validation, you must explicitly
-state which mode you wish to use. See B<Validation> below for more.
-
-=item Option: B<-validatecommand>
-
-=item Alias: B<-vcmd>
-
-=item Name: B<validateCommand>
-
-=item Class: B<ValidateCommand>
-
-Specifies a script to evaluate when you want to validate the input in the
-widget. Setting it to an empty string disables this feature (the default).
-Validation occurs according to the value of B<-validate>.
-This command must return a valid boolean value. If it returns 0 (or
-the valid boolean equivalent) then the value of the widget will not
-change and the B<invalidCommand> will be evaluated if it is set. If it
-returns 1, then value will be changed.
-See B<Validation> below for more information.
-
-=item Option: B<-values>
-
-=item Name: B<values>
-
-=item Class: B<Values>
-
-Must be a proper list value. If specified, the Spinbox will use these
-values as to control its contents, starting with the first value. This
-option has precedence over the B<-from> and B<-to> range.
-
-=item Option: B<-width>
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-Specifies an integer value indicating the desired width of the Spinbox window,
-in average-size characters of the widget's font.
-If the value is less than or equal to zero, the widget picks a
-size just large enough to hold its current text.
-
-=item Option: B<-wrap>
-
-=item Name: B<wrap>
-
-=item Class: B<Wrap>
-
-Must be a proper boolean value. If on, the Spinbox will wrap around the
-values of data in the widget.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Spinbox> method creates a new window (given by the
-$spinbox argument) and makes it into a Spinbox widget.
-Additional options, described above, may be specified on the
-command line or in the option database
-to configure aspects of the Spinbox such as its colors, font,
-and relief.
-
-A B<Spinbox> is an extended B<Entry> widget that allows he user
-to move, or spin, through a fixed set of ascending or descending values
-such as times or dates in addition to editing the value as in an
-B<entry>. When first created, a Spinbox's string is empty.
-A portion of the Spinbox may be selected as described below.
-If a Spinbox is exporting its selection (see the B<exportSelection>
-option), then it will observe the standard protocols for handling the
-selection; Spinbox selections are available as type B<STRING>.
-Spinboxes also observe the standard Tk rules for dealing with the
-input focus. When a Spinbox has the input focus it displays an
-I<insertion cursor> to indicate where new characters will be
-inserted.
-
-Spinboxes are capable of displaying strings that are too long to
-fit entirely within the widget's window. In this case, only a
-portion of the string will be displayed; commands described below
-may be used to change the view in the window. Spinboxes use
-the standard B<-xscrollcommand> mechanism for interacting with
-scrollbars (see the description of the B<-xscrollcommand> option
-for details). They also support scanning, as described below.
-
-=head1 VALIDATION
-
-Validation works by setting the B<validateCommand>
-option to a callback which will be evaluated according to the B<validate>
-option as follows:
-
-=over 4
-
-=item B<none>
-
-Default. This means no validation will occur.
-
-=item B<focus>
-
-B<validateCommand> will be called when the Spinbox receives or
-loses focus.
-
-=item B<focusin>
-
-B<validateCommand> will be called when the Spinbox receives focus.
-
-=item B<focusout>
-
-B<validateCommand> will be called when the Spinbox loses focus.
-
-=item B<key>
-
-B<validateCommand> will be called when the Spinbox is edited.
-
-=item B<all>
-
-B<validateCommand> will be called for all above conditions.
-
-
-The B<validateCommand> and B<invalidCommand> callbacks are invoked
-with at least 5 positional arguments, which are I<appended> to any already
-existing callback arguments:
-
-=over 4
-
-=item * 1
-
-The proposed value of the entry. If you are configuring the
-entry widget to have a new textVariable, this will be the value of that
-textVariable.
-
-=item * 2
-
-The characters to be added (or deleted). This will be C<undef>
-if validation is due to focus, explcit call to validate or if change
-is due to C<-textvariable> changing.
-
-=item * 3
-
-The current value of entry i.e. before the proposed change.
-
-=item * 4
-
-The index of character string to be added/deleted, if any. Otherwise -1.
-
-=item * 5
-
-Type of action. 1 == INSERT, 0 == DELETE,
--1 if it's a forced validation or textVariable validation.
-
-=back
-
-In general, the B<textVariable> and B<validateCommand> can be
-dangerous to mix. Any problems have been overcome so that using the
-B<validateCommand> will not interfere with the traditional behavior of
-the Spinbox widget. Using the B<textVariable> for read-only purposes will
-never cause problems. The danger comes when you try set the
-B<textVariable> to something that the B<validateCommand> would not
-accept, which causes B<validate> to become I<none> (the
-B<invalidCommand> will not be triggered). The same happens
-when an error occurs evaluating the B<validateCommand>.
-
-Primarily, an error will occur when the B<validateCommand> or
-B<invalidCommand> encounters an error in its script while evaluating or
-B<validateCommand> does not return a valid boolean value. The
-B<validate> option will also set itself to B<none> when you edit the
-Spinbox widget from within either the B<validateCommand> or the
-B<invalidCommand>. Such editions will override the one that was being
-validated. If you wish to edit the value of the widget
-during validation and still have the B<validate> option set, you should
-include the command
-
- my $val = $spinbox->cget(-validate);
- $spinbox->configure(-validate => $val);
-
-in the B<validateCommand> or B<invalidCommand> (whichever one you
-were editing the Spinbox widget from). It is also recommended to not set an
-associated B<textVariable> during validation, as that can cause the
-Spinbox widget to become out of sync with the B<textVariable>.
-
-=back
-
-=head1 WIDGET METHODS
-
-The B<Spinbox> command creates a widget object whose
-name is $widget. This command may be used to invoke various
-operations on the widget. It has the following general form:
-
- $widget->method(?arg arg ...?);
-
-Many of the methods for Spinboxes take one or more indices as
-arguments. An index specifies a particular character in the Spinbox's
-string, in any of the following ways:
-
-=over 4
-
-=item I<number>
-
-Specifies the character as a numerical index, where 0 corresponds
-to the first character in the string.
-
-=item B<anchor>
-
-Indicates the anchor point for the selection, which is set with the
-B<select from> and B<select adjust> methods.
-
-=item B<end>
-
-Indicates the character just after the last one in the Spinbox's string.
-This is equivalent to specifying a numerical index equal to the length
-of the Spinbox's string.
-
-=item B<insert>
-
-Indicates the character adjacent to and immediately following the
-insertion cursor.
-
-=item B<sel.first>
-
-Indicates the first character in the selection. It is an error to
-use this form if the selection isn't in the Spinbox window.
-
-=item B<sel.last>
-
-Indicates the character just after the last one in the selection.
-It is an error to use this form if the selection isn't in the
-Spinbox window.
-
-=item B<@>I<number>
-
-In this form, I<number> is treated as an x-coordinate in the
-Spinbox's window; the character spanning that x-coordinate is used.
-For example, ``B<@0>'' indicates the left-most character in the
-window.
-
-=back
-
-Abbreviations may be used for any of the forms above, e.g. ``B<e>''
-or ``B<sel.f>''. In general, out-of-range indices are automatically
-rounded to the nearest legal value.
-
-The following commands are possible for Spinbox widgets:
-
-=over 4
-
-=item I<$widget>-E<gt>B<bbox>(I<index>);
-
-Returns a list of four numbers describing the bounding box of the
-character given by I<index>.
-The first two elements of the list give the x and y coordinates of
-the upper-left corner of the screen area covered by the character
-(in pixels relative to the widget) and the last two elements give
-the width and height of the character, in pixels.
-The bounding box may refer to a region outside the visible area
-of the window.
-
-=item I<$widget>-E<gt>B<cget>(I<option>);
-
-Returns the current value of the configuration option given
-by I<option>.
-I<Option> may have any of the values accepted by the B<Spinbox>
-command.
-
-=item I<$widget>-E<gt>B<configure>(?I<option>?, ?I<value, option, value, ...>?);
-
-Query or modify the configuration options of the widget.
-If no I<option> is specified, returns a list describing all of
-the available options for $widget (see L<Tk::configure> for
-information on the format of this list). If I<option> is specified
-with no I<value>, then the command returns a list describing the
-one named option (this list will be identical to the corresponding
-sublist of the value returned if no I<option> is specified). If
-one or more I<option-value> pairs are specified, then the command
-modifies the given widget option(s) to have the given value(s); in
-this case the command returns an empty string.
-I<Option> may have any of the values accepted by the B<Spinbox>
-command.
-
-=item I<$widget>-E<gt>B<delete>(I<first, >?I<last>?);
-
-Delete one or more elements of the Spinbox.
-I<First> is the index of the first character to delete, and
-I<last> is the index of the character just after the last
-one to delete.
-If I<last> isn't specified it defaults to I<first>+1,
-i.e. a single character is deleted.
-This command returns an empty string.
-
-=item I<$widget>-E<gt>B<get>;
-
-Returns the Spinbox's string.
-
-=item I<$widget>-E<gt>B<icursor>(I<index>);
-
-Arrange for the insertion cursor to be displayed just before the character
-given by I<index>. Returns an empty string.
-
-=item I<$widget>-E<gt>B<identify>(I<x, y>);
-
-Returns the name of the window element corresponding to coordinates
-I<x> and I<y> in the Spinbox. Return value is one of:
-B<none>, B<buttondown>, B<buttonup>, B<entry>.
-
-=item I<$widget>-E<gt>B<index>(I<index>);
-
-Returns the numerical index corresponding to I<index>.
-
-=item I<$widget>-E<gt>B<insert>(I<index, string>);
-
-Insert the characters of I<string> just before the character
-indicated by I<index>. Returns an empty string.
-
-=item I<$widget>-E<gt>B<invoke>(I<element>);
-
-Causes the specified element, either B<buttondown> or B<buttonup>,
-to be invoked, triggering the action associated with it.
-
-=item I<$widget>-E<gt>B<scan>(I<option, args>);
-
-This command is used to implement scanning on Spinboxes. It has
-two forms, depending on I<option>:
-
-=over 4
-
-=item I<$widget>-E<gt>B<scanMark>(I<x>);
-
-Records I<x> and the current view in the Spinbox window; used in
-conjunction with later B<scan dragto> commands. Typically this
-command is associated with a mouse button press in the widget. It
-returns an empty string.
-
-=item I<$widget>-E<gt>B<scanDragto>(I<x>);
-
-This command computes the difference between its I<x> argument
-and the I<x> argument to the last B<scan mark> command for
-the widget. It then adjusts the view left or right by 10 times the
-difference in x-coordinates. This command is typically associated
-with mouse motion events in the widget, to produce the effect of
-dragging the Spinbox at high speed through the window. The return
-value is an empty string.
-
-=back
-
-=item I<$widget>-E<gt>B<selection>(I<option, arg>);
-
-This command is used to adjust the selection within a Spinbox. It
-has several forms, depending on I<option>:
-
-=over 4
-
-=item I<$widget>-E<gt>B<selectionAdjust>(I<index>);
-
-Locate the end of the selection nearest to the character given by
-I<index>, and adjust that end of the selection to be at I<index>
-(i.e including but not going beyond I<index>). The other
-end of the selection is made the anchor point for future
-B<select to> commands. If the selection
-isn't currently in the Spinbox, then a new selection is created to
-include the characters between I<index> and the most recent
-selection anchor point, inclusive.
-Returns an empty string.
-
-=item I<$widget>-E<gt>B<selectionClear>;
-
-Clear the selection if it is currently in this widget. If the
-selection isn't in this widget then the command has no effect.
-Returns an empty string.
-
-=item I<$widget>-E<gt>B<selectionElement>(?I<element>?);
-
-Sets or gets the currently selected element. If a spinbutton element
-is specified, it will be displayed depressed.
-
-=item I<$widget>-E<gt>B<selectionFrom>(I<index>);
-
-Set the selection anchor point to just before the character
-given by I<index>. Doesn't change the selection.
-Returns an empty string.
-
-=item I<$widget>-E<gt>B<selectionPresent>;
-
-Returns 1 if there is are characters selected in the Spinbox,
-0 if nothing is selected.
-
-=item I<$widget>-E<gt>B<selectionRange>(I<start, >I<end>);
-
-Sets the selection to include the characters starting with
-the one indexed by I<start> and ending with the one just
-before I<end>.
-If I<end> refers to the same character as I<start> or an
-earlier one, then the Spinbox's selection is cleared.
-
-=item I<$widget>-E<gt>B<selectionTo>(I<index>);
-
-If I<index> is before the anchor point, set the selection
-to the characters from I<index> up to but not including
-the anchor point.
-If I<index> is the same as the anchor point, do nothing.
-If I<index> is after the anchor point, set the selection
-to the characters from the anchor point up to but not including
-I<index>.
-The anchor point is determined by the most recent B<select from>
-or B<select adjust> command in this widget.
-If the selection isn't in this widget then a new selection is
-created using the most recent anchor point specified for the widget.
-Returns an empty string.
-
-=back
-
-=item I<$widget>-E<gt>B<set>(?I<string>?);
-
-If I<string> is specified, the Spinbox will try and set it to this
-value, otherwise it just returns the Spinbox's string.
-If validation is on, it will occur when setting the string.
-
-=item I<$widget>-E<gt>B<validate>;
-
-This command is used to force an evaluation of the B<validateCommand>
-independent of the conditions specified by the B<validate> option.
-This is done by temporarily setting the B<validate> option to B<all>.
-It returns 0 or 1.
-
-=item I<$widget>-E<gt>B<xview>(I<args>);
-
-This command is used to query and change the horizontal position of the
-text in the widget's window. It can take any of the following
-forms:
-
-=over 4
-
-=item I<$widget>-E<gt>B<xview>;
-
-Returns a list containing two elements.
-Each element is a real fraction between 0 and 1; together they describe
-the horizontal span that is visible in the window.
-For example, if the first element is .2 and the second element is .6,
-20% of the Spinbox's text is off-screen to the left, the middle 40% is visible
-in the window, and 40% of the text is off-screen to the right.
-These are the same values passed to scrollbars via the B<-xscrollcommand>
-option.
-
-=item I<$widget>-E<gt>B<xview>(I<index>);
-
-Adjusts the view in the window so that the character given by I<index>
-is displayed at the left edge of the window.
-
-=item I<$widget>-E<gt>B<xviewMoveto>(I<fraction>);
-
-Adjusts the view in the window so that the character I<fraction> of the
-way through the text appears at the left edge of the window.
-I<Fraction> must be a fraction between 0 and 1.
-
-=item I<$widget>-E<gt>B<xviewScroll>(I<number, what>);
-
-This command shifts the view in the window left or right according to
-I<number> and I<what>.
-I<Number> must be an integer.
-I<What> must be either B<units> or B<pages> or an abbreviation
-of one of these.
-If I<what> is B<units>, the view adjusts left or right by
-I<number> average-width characters on the display; if it is
-B<pages> then the view adjusts by I<number> screenfuls.
-If I<number> is negative then characters farther to the left
-become visible; if it is positive then characters farther to the right
-become visible.
-
-=back
-
-=back
-
-=head1 DEFAULT BINDINGS
-
-Tk automatically creates class bindings for Spinboxes that give them
-the following default behavior.
-In the descriptions below, ``word'' refers to a contiguous group
-of letters, digits, or ``_'' characters, or any single character
-other than these.
-
-=over 4
-
-=item [1]
-
-Clicking mouse button 1 positions the insertion cursor
-just before the character underneath the mouse cursor, sets the
-input focus to this widget, and clears any selection in the widget.
-Dragging with mouse button 1 strokes out a selection between
-the insertion cursor and the character under the mouse.
-
-=item [2]
-
-Double-clicking with mouse button 1 selects the word under the mouse
-and positions the insertion cursor at the beginning of the word.
-Dragging after a double click will stroke out a selection consisting
-of whole words.
-
-=item [3]
-
-Triple-clicking with mouse button 1 selects all of the text in the
-Spinbox and positions the insertion cursor before the first character.
-
-=item [4]
-
-The ends of the selection can be adjusted by dragging with mouse
-button 1 while the Shift key is down; this will adjust the end
-of the selection that was nearest to the mouse cursor when button
-1 was pressed.
-If the button is double-clicked before dragging then the selection
-will be adjusted in units of whole words.
-
-=item [5]
-
-Clicking mouse button 1 with the Control key down will position the
-insertion cursor in the Spinbox without affecting the selection.
-
-=item [6]
-
-If any normal printing characters are typed in a Spinbox, they are
-inserted at the point of the insertion cursor.
-
-=item [7]
-
-The view in the Spinbox can be adjusted by dragging with mouse button 2.
-If mouse button 2 is clicked without moving the mouse, the selection
-is copied into the Spinbox at the position of the mouse cursor.
-
-=item [8]
-
-If the mouse is dragged out of the Spinbox on the left or right sides
-while button 1 is pressed, the Spinbox will automatically scroll to
-make more text visible (if there is more text off-screen on the side
-where the mouse left the window).
-
-=item [9]
-
-The Left and Right keys move the insertion cursor one character to the
-left or right; they also clear any selection in the Spinbox and set
-the selection anchor.
-If Left or Right is typed with the Shift key down, then the insertion
-cursor moves and the selection is extended to include the new character.
-Control-Left and Control-Right move the insertion cursor by words, and
-Control-Shift-Left and Control-Shift-Right move the insertion cursor
-by words and also extend the selection.
-Control-b and Control-f behave the same as Left and Right, respectively.
-Meta-b and Meta-f behave the same as Control-Left and Control-Right,
-respectively.
-
-=item [10]
-
-The Home key, or Control-a, will move the insertion cursor to the
-beginning of the Spinbox and clear any selection in the Spinbox.
-Shift-Home moves the insertion cursor to the beginning of the Spinbox
-and also extends the selection to that point.
-
-=item [11]
-
-The End key, or Control-e, will move the insertion cursor to the
-end of the Spinbox and clear any selection in the Spinbox.
-Shift-End moves the cursor to the end and extends the selection
-to that point.
-
-=item [12]
-
-The Select key and Control-Space set the selection anchor to the position
-of the insertion cursor. They don't affect the current selection.
-Shift-Select and Control-Shift-Space adjust the selection to the
-current position of the insertion cursor, selecting from the anchor
-to the insertion cursor if there was not any selection previously.
-
-=item [13]
-
-Control-/ selects all the text in the Spinbox.
-
-=item [14]
-
-Control-\ clears any selection in the Spinbox.
-
-=item [15]
-
-The F16 key (labelled Copy on many Sun workstations) or Meta-w
-copies the selection in the widget to the clipboard, if there is a selection.
-
-=item [16]
-
-The F20 key (labelled Cut on many Sun workstations) or Control-w
-copies the selection in the widget to the clipboard and deletes
-the selection.
-If there is no selection in the widget then these keys have no effect.
-
-=item [17]
-
-The F18 key (labelled Paste on many Sun workstations) or Control-y
-inserts the contents of the clipboard at the position of the
-insertion cursor.
-
-=item [18]
-
-The Delete key deletes the selection, if there is one in the Spinbox.
-If there is no selection, it deletes the character to the right of
-the insertion cursor.
-
-=item [19]
-
-The BackSpace key and Control-h delete the selection, if there is one
-in the Spinbox.
-If there is no selection, it deletes the character to the left of
-the insertion cursor.
-
-=item [20]
-
-Control-d deletes the character to the right of the insertion cursor.
-
-=item [21]
-
-Meta-d deletes the word to the right of the insertion cursor.
-
-=item [22]
-
-Control-k deletes all the characters to the right of the insertion
-cursor.
-
-=item [23]
-
-Control-t reverses the order of the two characters to the right of
-the insertion cursor.
-
-If the Spinbox is disabled using the B<-state> option, then the Spinbox's
-view can still be adjusted and text in the Spinbox can still be selected,
-but no insertion cursor will be displayed and no text modifications will
-take place.
-
-The behavior of Spinboxes can be changed by defining new bindings for
-individual widgets or by redefining the class bindings.
-
-=back
-
-=head1 KEYWORDS
-
-Spinbox, Entry, widget
diff --git a/Master/tlpkg/tlperl/lib/Tk/Submethods.pod b/Master/tlpkg/tlperl/lib/Tk/Submethods.pod
deleted file mode 100644
index 2a83334f8b2..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Submethods.pod
+++ /dev/null
@@ -1,27 +0,0 @@
-
-=head1 NAME
-
-Tk::Submethods - add aliases for tk sub-commands
-
-=for pm Tk/Submethods.pm
-
-=for category Implementation
-
-=head1 SYNOPSIS
-
- use Tk::Submethods ( 'command1' => [qw(sub1 sub2 sub3)],
- 'command2' => [qw(sub1 sub2 sub3)]);
-
-=head1 DESCRIPTION
-
-Creates C<-E<gt>commandSub(...)> as an alias for C<-E<gt>command('sub',...)>
-e.g. C<-E<gt>grabRelease> for C<-E<gt>grab('release')>.
-
-For each command/subcommand pair this creates a closure with command
-and subcommand as bound lexical variables and assigns a reference to this
-to a 'glob' in the callers package.
-
-Someday the sub-commands may be created directly in the C code.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/SunConst.pod b/Master/tlpkg/tlperl/lib/Tk/SunConst.pod
deleted file mode 100644
index eb5d892871b..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/SunConst.pod
+++ /dev/null
@@ -1,18 +0,0 @@
-
-=head1 NAME
-
-Tk::DragDrop::SunConst - Constants for Sun's Drag&Drop protocol
-
-=for pm DragDrop/DragDrop/SunConst.pm
-
-=for category Experimental Modules
-
-=head1 DESCRIPTION
-
-This module defines symbolic name subs for the numeric constants that
-make up Sun's Drag&Drop protocol. They are in this module with Exporter
-as they are shared between the two halves (Dropper and Receiver) of
-the protocol.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/TList.pod b/Master/tlpkg/tlperl/lib/Tk/TList.pod
deleted file mode 100644
index b8937fa8ef0..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/TList.pod
+++ /dev/null
@@ -1,597 +0,0 @@
-# Copyright (c) 1996, Expert Interface Technologies
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-# The file man.macros and some of the macros used by this file are
-# copyrighted: (c) 1990 The Regents of the University of California.
-# (c) 1994-1995 Sun Microsystems, Inc.
-# The license terms of the Tcl/Tk distribution are in the file
-# license.tcl.
-
-=head1 NAME
-
-Tk::TList - Create and manipulate Tix Tabular List widgets
-
-=for category Tix Extensions
-
-=head1 SYNOPSIS
-
-S< >I<$tlist> = I<$parent>-E<gt>B<TList>(?I<options>?);
-
-=head1 SUPER-CLASS
-
-None.
-
-=head1 STANDARD OPTIONS
-
-B<-background> B<-borderwidth> B<-class> B<-cursor> B<-foreground>
-B<-font> B<-height> B<-highlightcolor> B<-highlightthickness>
-B<-relief> B<-selectbackground> B<-selectforeground>
-B<-xscrollcommand> B<-yscrollcommand> B<-width>
-
-See L<Tk::options> for details of the standard options.
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<browsecmd>
-
-=item Class: B<BrowseCmd>
-
-=item Switch: B<-browsecmd>
-
-Specifies a perl/Tk B<callback> to be executed when the user browses through the
-entries in the TList widget.
-
-=item Name: B<command>
-
-=item Class: B<Command>
-
-=item Switch: B<-command>
-
-Specifies the perl/Tk B<callback> to be executed when the user invokes a list
-entry in the TList widget. Normally the user invokes a list
-entry by double-clicking it or pressing the Return key.
-
-=item Name: B<foreground>
-
-=item Class: B<Foreground>
-
-=item Switch: B<-foreground>
-
-=item Alias: B<-fg>
-
-Specifies the default foreground color for the list entries.
-
-=item Name: B<height>
-
-=item Class: B<Height>
-
-=item Switch: B<-height>
-
-Specifies the desired height for the window in number of characters.
-
-=item Name: B<itemType>
-
-=item Class: B<ItemType>
-
-=item Switch: B<-itemtype>
-
-Specifies the default type of display item for this TList widget. When
-you call the B<insert> methods, display items of this
-type will be created if the B<-itemtype> option is not specified.
-
-=item Name: B<orient>
-
-=item Class: B<Orient>
-
-=item Switch: B<-orient>
-
-Specifies the order of tabularizing the list entries. When set to
-"B<vertical>", the entries are arranged in a column, from top to
-bottom. If the entries cannot be contained in one column, the
-remaining entries will go to the next column, and so on. When set to
-"B<horizontal>", the entries are arranged in a row, from left to
-right. If the entries cannot be contained in one row, the remaining
-entries will go to the next row, and so on.
-
-=item Name: B<padX>
-
-=item Class: B<Pad>
-
-=item Switch: B<-padx>
-
-The default horizontal padding for list entries.
-
-=item Name: B<padY>
-
-=item Class: B<Pad>
-
-=item Switch: B<-padx>
-
-The default vertical padding for list entries.
-
-=item Name: B<selectBackground>
-
-=item Class: B<SelectBackground>
-
-=item Switch: B<-selectbackground>
-
-Specifies the background color for the selected list entries.
-
-=item Name: B<selectBorderWidth>
-
-=item Class: B<BorderWidth>
-
-=item Switch: B<-selectborderwidth>
-
-Specifies a non-negative value indicating the width of the 3-D border
-to draw around selected items. The value may have any of the forms
-acceptable to B<Tk_GetPixels>.
-
-=item Name: B<selectForeground>
-
-=item Class: B<SelectForeground>
-
-=item Switch: B<-selectforeground>
-
-Specifies the foreground color for the selected list entries.
-
-=item Name: B<selectMode>
-
-=item Class: B<SelectMode>
-
-=item Switch: B<-selectmode>
-
-Specifies one of several styles for manipulating the selection. The
-value of the option may be arbitrary, but the default bindings expect
-it to be either B<single>, B<browse>, B<multiple>, or
-B<extended>; the default value is B<single>.
-
-=item Name: B<sizeCmd>
-
-=item Class: B<SizeCmd>
-
-=item Switch: B<-sizecmd>
-
-Specifies a perl/Tk B<callback> to be called whenever the TList widget
-changes its size. This command can be useful to implement "user scroll
-bars when needed" features.
-
-=item Name: B<state>
-
-=item Class: B<State>
-
-=item Switch: B<-state>
-
-Specifies whether the TList command should react to user actions. When
-set to "B<normal>", the TList reacts to user actions in the normal
-way. When set to "B<disabled>", the TList can only be scrolled, but
-its entries cannot be selected or activated.
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-=item Switch: B<-width>
-
-Specifies the desired width for the window in characters.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<TList> method creates a new window (given by the
-$widget argument) and makes it into a TList widget.
-Additional options, described above, may be specified on the command
-line or in the option database to configure aspects of the
-TList widget such as its cursor and relief.
-
-The TList widget can be used to display data in a tabular format. The
-list entries of a TList widget are similar to the entries in the Tk
-listbox widget. The main differences are (1) the TList widget can
-display the list entries in a two dimensional format and (2) you can
-use graphical images as well as multiple colors and fonts for
-the list entries.
-
-Each list entry is identified by an B<index>, which can be in the
-following forms:
-
-=over 4
-
-=item I<number>
-
-An integer that indicates the position of the entry in the list. 0
-means the first position, 1 means the second position, and so on.
-
-=item B<end>
-
-Indicates the end of the listbox. For some commands this means just
-after the last entry; for other commands it means the last entry.
-
-=item B<@>I<x>,I<y>
-
-Indicates the element that covers the point in the listbox window
-specified by x and y (in pixel coordinates). If no element covers that
-point, then the closest element to that point is used.
-
-=back
-
-=head1 DISPLAY ITEMS
-
-Each list entry in an TList widget is associated with a B<display>
-item. The display item determines what visual information should
-be displayed for this list entry. Please see L<Tk::DItem>
-for a list of all display items.
-
-When a list entry is created by the B<insert> command, the type of
-its display item is determined by the B<-itemtype> option passed
-to these commands. If the B<-itemtype> is omitted, then by default
-the type specified by this TList widget's B<-itemtype> option is
-used.
-
-=head1 WIDGET METHODS
-
-The B<TList> method creates a widget object.
-
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-The following additional methods are available for TList widgets:
-
-=over 4
-
-=item I<$tlist>-E<gt>B<anchorSet>(I<index>)
-
-Sets the anchor to the list entry identified by I<index>. The
-anchor is the end of the selection that is fixed while dragging out a
-selection with the mouse.
-
-=item I<$tlist>-E<gt>B<anchorClear>
-
-Removes the anchor, if any, from this TList widget. This only removes
-the surrounding highlights of the anchor entry and does not affect its
-selection status.
-
-=item I<$tlist>-E<gt>B<delete>(I<from, >?I<to>?)
-
-Deletes one or more list entries between the two entries specified by
-the indices I<from> and I<to>. If I<to> is not specified, deletes
-the single entry specified by I<from>.
-
-=item I<$tlist>-E<gt>B<dragsiteSet>(I<index>)
-
-Sets the dragsite to the list entry identified by
-I<index>. The dragsite is used to indicate the source of a
-drag-and-drop action. Currently drag-and-drop functionality has not
-been implemented in Tix yet.
-
-=item I<$tlist>-E<gt>B<dragsiteClear>
-
-Remove the dragsite, if any, from the this TList widget. This only
-removes the surrounding highlights of the dragsite entry and does not
-affect its selection status.
-
-=item I<$tlist>-E<gt>B<dropsiteSet>(I<index>)
-
-Sets the dropsite to the list entry identified by I<index>. The
-dropsite is used to indicate the target of a drag-and-drop
-action. Currently drag-and-drop functionality has not been implemented
-in Tix yet.
-
-=item I<$tlist>-E<gt>B<dropsiteClear>
-
-Remove the dropsite, if any, from the this TList widget. This only
-removes the surrounding highlights of the dropsite entry and does not
-affect its selection status.
-
-=item I<$tlist>-E<gt>B<entrycget>(I<index, option>)
-
-Returns the current value of the configuration option given by
-I<option> for the entry indentfied by I<index>. I<Option> may
-have any of the values accepted by the B<insert> method.
-
-=item I<$tlist>-E<gt>B<entryconfigure>(I<index, >?I<option>?, I<?value, option, value, ...>?)
-
-Query or modify the configuration options of the list entry identified
-by I<index>. If no I<option> is specified, returns a list
-describing all of the available options for I<index> (see
-B<Tk_ConfigureInfo> for information on the format of this list). If
-I<option> is specified with no I<value>, then the method
-returns a list describing the one named option (this list will be
-identical to the corresponding sublist of the value returned if no
-I<option> is specified). If one or more I<option-value> pairs
-are specified, then the command modifies the given option(s) to have
-the given value(s); in this case the method returns an empty string.
-I<Option> may have any of the values accepted by the B<insert>
-method. The exact set of options depends on the
-value of the B<-itemtype> option passed to the the B<insert>
-method when this list entry is created.
-
-=item I<$tlist>-E<gt>B<insert>(I<index, >?I<option, value, ...>?)
-
-Creates a new list entry at the position indicated by I<index>. The
-following configuration options can be given to configure the list
-entry:
-
-=over 8
-
-=item B<-itemtype> => I<type>
-
-Specifies the type of display item to be display for the new list
-entry. I<type> must be a valid display item type. Currently the
-available display item types are B<image>, B<imagetext>,
-B<text>, and I<$widget>. If this option is not specified, then by
-default the type specified by this TList widget's B<-itemtype>
-option is used.
-
-=item B<-state> => I<state>
-
-Specifies whether this entry can be selected or invoked by the user.
-Must be either B<normal> or B<disabled>.
-
-=item B<-data> => I<data>
-
-Arbitrary data to be associated with the entry (a perl scalar value).
-
-=back
-
-The B<insert> method accepts additional configuration options
-to configure the display item associated with this list entry. The set
-of additional configuration options depends on the type of the display
-item given by the B<-itemtype> option. Please see
-L<Tk::DItem> for a list of the configuration options for
-each of the display item types.
-
-=item I<$tlist>-E<gt>B<info>(I<option, >I<arg, ...>)
-
-Query information about the TList widget. I<option> can be one
-of the following:
-
-=over 8
-
-=item I<$tlist>-E<gt>B<info>(B<anchor, >I<index>)
-
-Returns the index of the current anchor, if any, of the TList
-widget. If the anchor is not set, returns the empty string.
-
-=item I<$tlist>-E<gt>B<info>(B<dragsite, >I<index>)
-
-Returns the index of the current dragsite, if any, of the TList
-widget. If the dragsite is not set, returns the empty string.
-
-=item I<$tlist>-E<gt>B<info>(B<dropsite, >I<index>)
-
-Returns the index of the current dropsite, if any, of the TList
-widget. If the dropsite is not set, returns the empty string.
-
-=item I<$tlist>-E<gt>B<info>(B<selection>)
-
-Returns a list of selected elements in the TList widget. If no entries
-are selected, returns an empty string.
-
-=back
-
-=item I<$tlist>-E<gt>B<nearest>(I<x, y>)
-
-Given an I<(x,y)> coordinate within the TList window, this command
-returns the index of the TList element nearest to that coordinate.
-
-=item I<$tlist>-E<gt>B<see>(I<index>)
-
-Adjust the view in the TList so that the entry given by I<index> is
-visible. If the entry is already visible then the command has no
-effect; otherwise TList scrolls to bring the element into view at the edge
-to which it is nearest.
-
-=item I<$tlist>-E<gt>B<selection>(I<option, >I<arg, ...>)
-
-This command is used to adjust the selection within a TList widget. It
-has several forms, depending on I<option>:
-
-=over 8
-
-=item I<$tlist>-E<gt>B<selectionClear>(?I<from>?, ?I<to>?)
-
-When no extra arguments are given, deselects all of the list entrie(s)
-in this TList widget. When only I<from> is given, only the list
-entry identified by I<from> is deselected. When both I<from> and
-I<to> are given, deselects all of the list entrie(s) between
-between I<from> and I<to>, inclusive, without affecting the
-selection state of entries outside that range.
-
-=item I<$tlist>-E<gt>B<selectionIncludes>(I<index>)
-
-Returns 1 if the list entry indicated by I<index> is currently
-selected; returns 0 otherwise.
-
-=item I<$tlist>-E<gt>B<selectionSet>(I<from, >?I<to>?)
-
-Selects all of the list entrie(s) between between I<from> and
-I<to>, inclusive, without affecting the selection state of entries
-outside that range. When only I<from> is given, only the list entry
-identified by I<from> is selected.
-
-=back
-
-=item I<$tlist>-E<gt>B<xview>(I<args>)
-
-This command is used to query and change the horizontal position of the
-information in the widget's window. It can take any of the following
-forms:
-
-=over 8
-
-=item I<$tlist>-E<gt>B<xview>
-
-Returns a list containing two elements. Each element is a real
-fraction between 0 and 1; together they describe the horizontal span
-that is visible in the window. For example, if the first element is
-0.2 and the second element is 0.6, 20% of the TList entry is
-off-screen to the left, the middle 40% is visible in the window, and
-40% of the entry is off-screen to the right. These are the same values
-passed to scrollbars via the B<-xscrollcommand> option.
-
-=item I<$tlist>-E<gt>B<xview>(I<index>)
-
-Adjusts the view in the window so that the list entry identified by
-I<index> is aligned to the left edge of the window.
-
-=item I<$tlist>-E<gt>B<xviewMoveto>(I<fraction>)
-
-Adjusts the view in the window so that I<fraction> of the total
-width of the TList is off-screen to the left. I<fraction> must be
-a fraction between 0 and 1.
-
-=item I<$tlist>-E<gt>B<xviewScroll>(I<number, what>)
-
-This command shifts the view in the window left or right according to
-I<number> and I<what>. I<Number> must be an integer.
-I<What> must be either B<units> or B<pages> or an
-abbreviation of one of these. If I<what> is B<units>, the view
-adjusts left or right by I<number> character units (the width of
-the B<0> character) on the display; if it is B<pages> then the
-view adjusts by I<number> screenfuls. If I<number> is negative
-then characters farther to the left become visible; if it is positive
-then characters farther to the right become visible.
-
-=back
-
-=item I<$tlist>-E<gt>B<yview>(I<?args>?)
-
-This command is used to query and change the vertical position of the
-entries in the widget's window. It can take any of the following forms:
-
-=over 8
-
-=item I<$tlist>-E<gt>B<yview>
-
-Returns a list containing two elements, both of which are real
-fractions between 0 and 1. The first element gives the position of
-the list element at the top of the window, relative to the TList as a
-whole (0.5 means it is halfway through the TList, for example). The
-second element gives the position of the list entry just after the
-last one in the window, relative to the TList as a whole. These are
-the same values passed to scrollbars via the B<-yscrollcommand>
-option.
-
-=item I<$tlist>-E<gt>B<yview>(I<index>)
-
-Adjusts the view in the window so that the list entry given by
-I<index> is displayed at the top of the window.
-
-=item I<$tlist>-E<gt>B<yviewMoveto>(I<fraction>)
-
-Adjusts the view in the window so that the list entry given by
-I<fraction> appears at the top of the window. I<Fraction> is a
-fraction between 0 and 1; 0 indicates the first entry in the TList,
-0.33 indicates the entry one-third the way through the TList, and so
-on.
-
-=item I<$tlist>-E<gt>B<yviewScroll>(I<number, what>)
-
-This command adjust the view in the window up or down according to
-I<number> and I<what>. I<Number> must be an integer.
-I<What> must be either B<units> or B<pages>. If I<what>
-is B<units>, the view adjusts up or down by I<number> lines; if
-it is B<pages> then the view adjusts by I<number> screenfuls.
-If I<number> is negative then earlier entries become visible; if
-it is positive then later entries become visible.
-
-=back
-
-=back
-
-=head1 BINDINGS
-
-=over 4
-
-=item [1]
-
-If the B<-selectmode> is "browse", when the user drags the mouse
-pointer over the list entries, the entry under the pointer will be
-highlighted and the B<-browsecmd> procedure will be called with
-one parameter, the index of the highlighted entry. Only one entry
-can be highlighted at a time. The B<-command> procedure will be
-called when the user double-clicks on a list entry.
-
-=item [2]
-
-If the B<-selectmode> is "single", the entries will only be
-highlighted by mouse E<lt>ButtonRelease-1E<gt> events. When a new list entry
-is highlighted, the B<-browsecmd> procedure will be called with
-one parameter indicating the highlighted list entry. The
-B<-command> procedure will be called when the user double-clicks
-on a list entry.
-
-=item [3]
-
-If the B<-selectmode> is "multiple", when the user drags the mouse
-pointer over the list entries, all the entries under the pointer will
-be highlighted. However, only a contiguous region of list entries can
-be selected. When the highlighted area is changed, the
-B<-browsecmd> procedure will be called with an undefined
-parameter. It is the responsibility of the B<-browsecmd> procedure
-to find out the exact highlighted selection in the TList. The
-B<-command> procedure will be called when the user double-clicks
-on a list entry.
-
-=item [4]
-
-If the B<-selectmode> is "extended", when the user drags the mouse
-pointer over the list entries, all the entries under the pointer will
-be highlighted. The user can also make disjointed selections using
-E<lt>Control-ButtonPress-1E<gt>. When the highlighted area is changed, the
-B<-browsecmd> procedure will be called with an undefined
-parameter. It is the responsibility of the B<-browsecmd> procedure
-to find out the exact highlighted selection in the TList. The
-B<-command> procedure will be called when the user double-clicks
-on a list entry.
-
-=back
-
-=cut
-
-# BUG:
-# click on 'one' in example below does not make
-# it 'active' item (didn't GBARR reported this before!?)
-
-=head1 EXAMPLE
-
-This example demonstrates how to use an TList to store a list of
-numbers:
-
- use strict;
- use Tk ();
- use Tk::TList;
-
- my $mw = Tk::MainWindow->new();
- my $image = $mw->Getimage('folder');
- my $tlist = $mw->TList(-orient => 'vertical');
- for my $text ( qw/one two three four five six seven eight nine/ ) {
- $tlist->insert('end',
- -itemtype=>'imagetext', -image=>$image, -text=>$text);
- }
-
- $tlist->pack(-expand=>'yes', -fill=>'both');
-
- Tk::MainLoop;
-
-=head1 SEE ALSO
-
-L<Tk::options|Tk::options>
-L<Tk::Widget|Tk::Widget>
-L<Tk::DItem|Tk::DItem>
-L<Tk::HList|Tk::HList>
-L<Tk::TixGrid|Tk::TixGrid>
-
-=head1 KEYWORDS
-
-Tix(n), Tabular Listbox, Display Items
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Table.pod b/Master/tlpkg/tlperl/lib/Tk/Table.pod
deleted file mode 100644
index f73e93907b4..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Table.pod
+++ /dev/null
@@ -1,97 +0,0 @@
-
-=head1 NAME
-
-Tk::Table - Scrollable 2 dimensional table of Tk widgets
-
-=for pm Tk/Table.pm
-
-=for category Tk Geometry Management
-
-=head1 SYNOPSIS
-
- use Tk::Table;
-
- $table = $parent->Table(-rows => number,
- -columns => number,
- -scrollbars => anchor,
- -fixedrows => number,
- -fixedcolumns => number,
- -takefocus => boolean);
-
- $widget = $table->Button(...);
-
- $old = $table->put($row,$col,$widget);
- $old = $table->put($row,$col,"Text"); # simple Label
- $widget = $table->get($row,$col);
-
- $cols = $table->totalColumns;
- $rows = $table->totalRows;
-
- $table->see($widget);
- $table->see($row,$col);
-
- ($row,$col) = $table->Posn($widget);
-
-=head1 DESCRIPTION
-
-Tk::Table is an all-perl widget/geometry manager which allows a two dimensional
-table of arbitary perl/Tk widgets to be displayed.
-
-Entries in the Table are simply ordinary perl/Tk widgets. They should
-be created with the Table as their parent. Widgets are positioned in the
-table using:
-
- $table->put($row,$col,$widget)
-
-If I<$widget> is not a reference it is treated as a string, and
-a Lable widget is created with the string as its text.
-
-All the widgets in each column are set to the same width - the requested
-width of the widest widget in the column.
-Likewise, all the widgets in each row are set to the same height - the requested
-height of the tallest widget in the column.
-
-A number of rows and/or columns can be marked as 'fixed' - and so can serve
-as 'headings' for the remainder the rows which are scrollable.
-
-The requested size of the table as a whole is such that the number of rows
-specified by -rows (default 10), and number of columns specified by -columns
-(default 10) can be displayed.
-
-If the Table is told it can take the keyboard focus then cursor and scroll
-keys scroll the displayed widgets.
-
-The Table will create and manage its own scrollbars if requested via
--scrollbars.
-
-The table can be emptied using
-
- $table->clear
-
-the widgets which were in the table are destroyed.
-
-
-The Tk::Table widget is derived from a Tk::Frame, so inherits all its
-configure options.
-
-=head1 BUGS / Snags / Possible enhancements
-
-=over 4
-
-=item *
-
-Very large Tables consume a lot of X windows.
-
-=item *
-
-No equivalent of pack's -anchor/-pad etc. options
-
-=back
-
-=head1 SEE ALSO
-
-L<Tk::grid>, L<Tk::HList>, L<Tk::TableMatrix>, L<Tk::MListbox>,
-L<Tk::Columns>
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Tcl-perl.pod b/Master/tlpkg/tlperl/lib/Tk/Tcl-perl.pod
deleted file mode 100644
index 2310e0738e4..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Tcl-perl.pod
+++ /dev/null
@@ -1,200 +0,0 @@
-=head1 NAME
-
-Tcl vs perl - very old suspect documentation on porting.
-
-=for category Other Modules and Languages
-
-=head1 DESCRIPTION
-
-This isn't really a .pod yet, nor is it Tcl vs perl
-it is a copy of John's comparison of Malcolm's original perl/Tk
-port with the current one. It is also out-of-date in places.
-
- From: john@WPI.EDU (John Stoffel )
-
- Here are some thoughts on the new Tk extension and how I think the
- organization of the commands looks. Mostly, I'm happy with it, it
- makes some things more organized and more consistent with tcl/tk, but
- since the overlying language is so different, I don't think we need to
- follow exactly the tcl/tk model for how to call the language.
-
- The basic structure of the Tk program is:
-
- require Tk;
-
- $top = MainWindow->new();
-
- #
- # create widgets
- #
-
- Tk::MainLoop;
-
- sub method1 {
- }
-
- sub methodN {
- }
-
- This is pretty much the same as tkperl5a5, with some cosmetic naming
- changes, and some more useful command name and usage changes. A quick
- comparison in no particular order follows:
-
- tkperl5a5 Tk
- ------------------------------- -----------------------------------
- $top=tkinit(name,display,sync); $top=MainWindow->new();
-
- tkpack $w, ... ; $w->pack(...)
-
- $w = Class::new($top, ...); $w = $top->Class(...);
-
- tkmainloop; Tk::MainLoop;
-
- tkbind($w,"<key>",sub); $w->bind("<key>",sub);
-
- tkdelete($w, ...); $w->delete(...);
-
- $w->scanmark(...); $w->scan("mark", ...);
-
- $w->scandragto(...); $w->scan("dragto", ...);
-
- $w->tkselect(); $w->Select();
-
- $w->selectadjust(...); $w->selection("adjust", ...);
-
- $w->selectto(...); $w->selection("to", ...);
-
- $w->selectfrom(...); $w->selection("from", ...);
-
- $w->tkindex(...); $w->index(...);
-
- tclcmd("xxx",...); &Tk::xxx(...) # all Tk commands, but no Tcl at all
-
- tclcmd("winfo", xxx, $w, ...); $w->xxx(...);
-
- $w->mark(...);
-
- $w->tag(...);
-
- $w->grabstatus(); $w->grab("status");
-
- $w->grabrelease(...); $w->grab("release", ...);
-
- focus($w); $w->focus;
-
- update(); Tk->update();
-
- idletasks(); Tk->update("idletasks");
-
- wm("cmd",$w, ...); $w->cmd(...);
-
- destroy($w); $w->destroy();
-
- Tk::option(...);
- $w->OptionGet(name,Class)
-
- $w->place(...)
-
- Tk::property(...);
-
- $w = Entry::new($parent,...)
-
- is now
-
- $w = $parent->Entry(...)
-
- As this allows new to be inherited from a Window class.
-
- -method=>x,-slave=>y
-
- is now
-
- -command => [x,y]
-
- 1st element of list is treated as "method" if y is an object reference.
- (You can have -command => [a,b,c,d,e] too; b..e get passed as args).
-
- Object references are now hashes rather than scalars and there
- is only ever one such per window. The Tcl_CmdInfo and PathName
- are entries in the hash.
-
- (This allows derived classes to
- re-bless the hash and keep their on stuff in it too.)
-
- Tk's "Tcl_Interp" is in fact a ref to "." window.
- You can find all the Tk windows descended from it as their object
- references get added (by PathName) into this hash.
- $w->MainWindow returns this hash from any window.
-
- I think that it should extend to multiple tkinits / Tk->news
- with different Display's - if Tk code does.
-
- Finally "bind" passes window as "extra" (or only)
- argument. Thus
-
- Tk::Button->bind(<Any-Enter>,"Enter");
-
- Binds Enter events to Tk::Button::Enter by default
- but gets called as $w->Enter so derived class of Button can just
- define its own Enter method. &EvWref and associated globals and race
- conditions are no longer needed.
-
- One thing to beware of : commands bound to events with $widget->bind
- follow same pattern, but get passed extra args :
-
- $widget->bind(<Any-1>,[sub {print shift}, $one, $two ]);
-
- When sub gets called it has :
-
- $widget $one $two
-
- passed.
-
- 1st extra arg is reference to the per-widget hash that serves as the
- perl object for the widget.
-
- Every time an XEvent a reference to a special class is placed
- in the widget hash. It can be retrieved by $w->XEvent method.
-
- The methods of the XEvent class are the
- Tcl/Tk % special characters.
-
- Thus:
-
- $widget->bind(<Any-KeyPress>,
- sub {
- my $w = shift;
- my $e = $w->XEvent;
- print $w->PathName," ",$e->A," pressed ,$e->xy,"\n");
- });
-
- XEvent->xy is a special case which returns "@" . $e->x . "," . $e->y
- which is common in Text package.
-
- Because of passing a blessed widget hash to "bound" subs they can be
- bound to (possibly inherited) methods of the widget's class:
-
- Class->bind(<Any-Down>,Down);
-
- sub Class::Down
- {
- my $w = shift;
- # handle down arrow
- }
-
- Also:
-
- -command and friends can take a list the 1st element can be a ref to
- as sub or a method name. Remaining elements are passed as args to the
- sub at "invoke" time. Thus :
-
- $b= $w->Button(blah blah, '-command' => [sub{print shift} , $fred ]);
-
- Should do the trick, provided $fred is defined at time of button creation.
-
- Thus 1st element of list is equivalent to Malcolm's -method and second
- would be his -slave. Any further elements are a bonus and avoid
- having to pass ref to an array/hash as a slave.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Text.pod b/Master/tlpkg/tlperl/lib/Tk/Text.pod
deleted file mode 100644
index 200cda9b033..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Text.pod
+++ /dev/null
@@ -1,2220 +0,0 @@
-# Copyright (c) 1992 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# Copyright (c) 2002 O'Reilly & Associates Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Text - Create and manipulate Text widgets
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
-I<$text> = I<$parent>-E<gt>B<Text>(?I<options>?);
-
-B<-background> B<-highlightbackground> B<-insertontime> B<-selectborderwidth>
-B<-borderwidth> B<-highlightcolor> B<-insertwidth> B<-selectforeground>
-B<-cursor> B<-highlightthickness> B<-padx> B<-setgrid>
-B<-exportselection> B<-insertbackground> B<-pady> B<-takefocus>
-B<-font> B<-insertborderwidth> B<-relief> B<-xscrollcommand>
-B<-foreground> B<-insertofftime> B<-selectbackground> B<-yscrollcommand>
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<height>
-
-=item Class: B<Height>
-
-=item Switch: B<-height>
-
-Specifies the desired height for the window, in units of characters
-in the font given by the B<-font> option.
-Must be at least one.
-
-=item Name: B<spacing1>
-
-=item Class: B<Spacing1>
-
-=item Switch: B<-spacing1>
-
-Requests additional space above each text line in the widget,
-using any of the standard forms for screen distances.
-If a line wraps, this option only applies to the first line
-on the display.
-This option may be overriden with B<-spacing1> options in
-tags.
-
-=item Name: B<spacing2>
-
-=item Class: B<Spacing2>
-
-=item Switch: B<-spacing2>
-
-For lines that wrap (so that they cover more than one line on the
-display) this option specifies additional space to provide between
-the display lines that represent a single line of text.
-The value may have any of the standard forms for screen distances.
-This option may be overriden with B<-spacing2> options in
-tags.
-
-=item Name: B<spacing3>
-
-=item Class: B<Spacing3>
-
-=item Switch: B<-spacing3>
-
-Requests additional space below each text line in the widget,
-using any of the standard forms for screen distances.
-If a line wraps, this option only applies to the last line
-on the display.
-This option may be overriden with B<-spacing3> options in
-tags.
-
-=item Name: B<state>
-
-=item Class: B<State>
-
-=item Switch: B<-state>
-
-Specifies one of two states for the text: B<normal> or B<disabled>.
-If the text is disabled then characters may not be inserted or deleted
-and no insertion cursor will be displayed, even if the input focus is
-in the widget.
-
-=item Name: B<tabs>
-
-=item Class: B<Tabs>
-
-=item Switch: B<-tabs>
-
-Specifies a set of tab stops for the window. The option's value consists
-of a list of screen distances giving the positions of the tab stops. Each
-position may optionally be followed in the next list element
-by one of the keywords B<left>, B<right>, B<center>,
-or B<numeric>, which specifies how to justify
-text relative to the tab stop. B<Left> is the default; it causes
-the text following the tab character to be positioned with its left edge
-at the tab position. B<Right> means that the right edge of the text
-following the tab character is positioned at the tab position, and
-B<center> means that the text is centered at the tab position.
-B<Numeric> means that the decimal point in the text is positioned
-at the tab position; if there is no decimal point then the least
-significant digit of the number is positioned just to the left of the
-tab position; if there is no number in the text then the text is
-right-justified at the tab position.
-For example, B<-tabs =E<gt> [qw/2c left 4c 6c center/]> creates three
-tab stops at two-centimeter intervals; the first two use left
-justification and the third uses center justification.
-If the list of tab stops does not have enough elements to cover all
-of the tabs in a text line, then Tk extrapolates new tab stops using
-the spacing and alignment from the last tab stop in the list.
-The value of the B<tabs> option may be overridden by B<-tabs>
-options in tags.
-If no B<-tabs> option is specified, or if it is specified as
-an empty list, then Tk uses default tabs spaced every eight
-(average size) characters.
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-=item Switch: B<-width>
-
-Specifies the desired width for the window in units of characters
-in the font given by the B<-font> option.
-If the font doesn't have a uniform width then the width of the
-character ``0'' is used in translating from character units to
-screen units.
-
-=item Name: B<wrap>
-
-=item Class: B<Wrap>
-
-=item Switch: B<-wrap>
-
-Specifies how to handle lines in the text that are too long to be
-displayed in a single line of the text's window.
-The value must be B<none> or B<char> or B<word>.
-A wrap mode of B<none> means that each line of text appears as
-exactly one line on the screen; extra characters that don't fit
-on the screen are not displayed.
-In the other modes each line of text will be broken up into several
-screen lines if necessary to keep all the characters visible.
-In B<char> mode a screen line break may occur after any character;
-in B<word> mode a line break will only be made at word boundaries.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Text> method creates a new window (given by the
-$text argument) and makes it into a text widget.
-Additional
-options, described above, may be specified on the command line
-or in the option database
-to configure aspects of the text such as its default background color
-and relief. The B<text> command returns the
-path name of the new window.
-
-A text widget displays one or more lines of text and allows that
-text to be edited.
-Text widgets support four different kinds of annotations on the
-text, called tags, marks, embedded windows or embedded images.
-Tags allow different portions of the text
-to be displayed with different fonts and colors.
-In addition, L<perl/Tk callbacks|Tk::callbacks> can be associated with tags so
-that scripts are invoked when particular actions such as keystrokes
-and mouse button presses occur in particular ranges of the text.
-See L<"TAGS"> below for more details.
-
-The second form of annotation consists of marks, which are floating
-markers in the text.
-Marks are used to keep track of various interesting positions in the
-text as it is edited.
-See L<"MARKS"> below for more details.
-
-The third form of annotation allows arbitrary windows to be
-embedded in a text widget.
-See L<"EMBEDDED WINDOWS"> below for more details.
-
-The fourth form of annotation allows Tk images to be embedded in a text
-widget.
-See L<"EMBEDDED IMAGES"> below for more details.
-
-The Perl/Tk B<Text> widget does not support undo/redo, use the B<TextUndo>
-widget instead.
-
-=head1 INDICES
-
-Many of the methods for texts take one or more indices
-as arguments.
-An index is a string used to indicate a particular place within
-a text, such as a place to insert characters or one endpoint of a
-range of characters to delete.
-Indices have the syntax
-
- base modifier modifier modifier ...
-
-Where I<base> gives a starting point and the I<modifier>s
-adjust the index from the starting point (e.g. move forward or
-backward one character). Every index must contain a I<base>,
-but the I<modifier>s are optional.
-
-The I<base> for an index must have one of the following forms:
-
-=over 4
-
-=item I<line>B<.>I<char>
-
-Indicates I<char>'th character on line I<line>.
-Lines are numbered from 1 for consistency with other UNIX programs
-that use this numbering scheme.
-Within a line, characters are numbered from 0.
-If I<char> is B<end> then it refers to the newline character
-that ends the line.
-
-=item B<@>I<x>B<,>I<y>
-
-Indicates the character that covers the pixel whose x and y coordinates
-within the text's window are I<x> and I<y>.
-
-=item B<end>
-
-Indicates the end of the text (the character just after the last
-newline).
-
-=item I<mark>
-
-Indicates the character just after the mark whose name is I<mark>.
-
-=item I<tag>B<.first>
-
-Indicates the first character in the text that has been tagged with
-I<tag>.
-This form generates an error if no characters are currently tagged
-with I<tag>.
-
-=item I<tag>B<.last>
-
-Indicates the character just after the last one in the text that has
-been tagged with I<tag>.
-This form generates an error if no characters are currently tagged
-with I<tag>.
-
-=item I<$widget>
-
-Indicates the position of the embedded window referenced by I<$widget>.
-This form generates an error if I<$widget> does not reference to an
-embedded window.
-
-=item I<imageName>
-
-Indicates the position of the embedded image whose name is
-I<imageName>.
-This form generates an error if there is no embedded image
-by the given name.
-
-If the I<base> could match more than one of the above forms, such
-as a I<mark> and I<imageName> both having the same value, then
-the form earlier in the above list takes precedence.
-If modifiers follow the base index, each one of them must have one
-of the forms listed below. Keywords such as B<chars> and B<wordend>
-may be abbreviated as long as the abbreviation is unambiguous.
-
-=item B<+ >I<count>B< chars>
-
-Adjust the index forward by I<count> characters, moving to later
-lines in the text if necessary. If there are fewer than I<count>
-characters in the text after the current index, then set the index
-to the last character in the text.
-Spaces on either side of I<count> are optional.
-
-=item B<- >I<count>B< chars>
-
-Adjust the index backward by I<count> characters, moving to earlier
-lines in the text if necessary. If there are fewer than I<count>
-characters in the text before the current index, then set the index
-to the first character in the text.
-Spaces on either side of I<count> are optional.
-
-=item B<+ >I<count>B< lines>
-
-Adjust the index forward by I<count> lines, retaining the same
-character position within the line. If there are fewer than I<count>
-lines after the line containing the current index, then set the index
-to refer to the same character position on the last line of the text.
-Then, if the line is not long enough to contain a character at the indicated
-character position, adjust the character position to refer to the last
-character of the line (the newline).
-Spaces on either side of I<count> are optional.
-
-=item B<- >I<count>B< lines>
-
-Adjust the index backward by I<count> lines, retaining the same
-character position within the line. If there are fewer than I<count>
-lines before the line containing the current index, then set the index
-to refer to the same character position on the first line of the text.
-Then, if the line is not long enough to contain a character at the indicated
-character position, adjust the character position to refer to the last
-character of the line (the newline).
-Spaces on either side of I<count> are optional.
-
-=item B<linestart>
-
-Adjust the index to refer to the first character on the line.
-
-=item B<lineend>
-
-Adjust the index to refer to the last character on the line (the newline).
-
-=item B<wordstart>
-
-Adjust the index to refer to the first character of the word containing
-the current index. A word consists of any number of adjacent characters
-that are letters, digits, or underscores, or a single character that
-is not one of these.
-
-=item B<wordend>
-
-Adjust the index to refer to the character just after the last one of the
-word containing the current index. If the current index refers to the last
-character of the text then it is not modified.
-
-If more than one modifier is present then they are applied in
-left-to-right order. For example, the index ``B<end - 1 chars>''
-refers to the next-to-last character in the text and
-``B<insert wordstart - 1 c>'' refers to the character just before
-the first one in the word containing the insertion cursor.
-
-=back
-
-=head1 TAGS
-
-The first form of annotation in text widgets is a tag.
-A tag is a textual string that is associated with some of the characters
-in a text.
-Tags may contain arbitrary characters, but it is probably best to
-avoid using the the characters `` '' (space), B<+>, or B<->:
-these characters have special meaning in indices, so tags containing
-them can't be used as indices.
-There may be any number of tags associated with characters in a
-text.
-Each tag may refer to a single character, a range of characters, or
-several ranges of characters.
-An individual character may have any number of tags associated with it.
-
-A priority order is defined among tags, and this order is used in
-implementing some of the tag-related functions described below.
-When a tag is defined (by associating it with characters or setting
-its display options or binding callbacks to it), it is given
-a priority higher than any existing tag.
-The priority order of tags may be redefined using the
-``I<$text>-E<gt>B<tagRaise>'' and ``I<$text>-E<gt>B<tagLower>''
-methods.
-
-Tags serve three purposes in text widgets.
-First, they control the way information is displayed on the screen.
-By default, characters are displayed as determined by the
-B<background>, B<font>, and B<foreground> options for the
-text widget.
-However, display options may be associated with individual tags
-using the ``I<$text>-E<gt>B<tagConfigure>'' method.
-If a character has been tagged, then the display options associated
-with the tag override the default display style.
-The following options are currently supported for tags:
-
-=over 4
-
-=item B<-background> =E<gt> I<color>
-
-I<Color> specifies the background color to use for characters
-associated with the tag.
-It may have any of the forms accepted by B<Tk_GetColor>.
-
-=item B<-bgstipple> =E<gt> I<bitmap>
-
-I<Bitmap> specifies a bitmap that is used as a stipple pattern
-for the background.
-It may have any of the forms accepted by B<Tk_GetBitmap>.
-If I<bitmap> hasn't been specified, or if it is specified
-as an empty string, then a solid fill will be used for the
-background.
-
-=item B<-borderwidth> =E<gt> I<pixels>
-
-I<Pixels> specifies the width of a 3-D border to draw around
-the background.
-It may have any of the forms accepted by B<Tk_GetPixels>.
-This option is used in conjunction with the B<-relief>
-option to give a 3-D appearance to the background for characters;
-it is ignored unless the B<-background> option
-has been set for the tag.
-
-=item B<-elide> =E<gt> boolean
-
-Elide specifies whether the data should be elided. Elided data
-is not displayed and takes no space on screen, but further on
-behaves just as normal data.
-
-=item B<-data> =E<gt> I<value>
-
-Allows an arbitrary perl scalar I<value> to be associated with the tag.
-
-=item B<-fgstipple> =E<gt> I<bitmap>
-
-I<Bitmap> specifies a bitmap that is used as a stipple pattern
-when drawing text and other foreground information such as
-underlines.
-It may have any of the forms accepted by B<Tk_GetBitmap>.
-If I<bitmap> hasn't been specified, or if it is specified
-as an empty string, then a solid fill will be used.
-
-=item B<-font> =E<gt> I<fontName>
-
-I<FontName> is the name of a font to use for drawing characters.
-It may have any of the forms accepted by B<Tk_GetFontStruct>.
-
-=item B<-foreground> =E<gt> I<color>
-
-I<Color> specifies the color to use when drawing text and other
-foreground information such as underlines.
-It may have any of the forms accepted by B<Tk_GetColor>.
-
-=item B<-justify> =E<gt> I<justify>
-
-If the first character of a display line has a tag for which this
-option has been specified, then I<justify> determines how to
-justify the line.
-It must be one of B<left>, B<right>, or B<center>.
-If a line wraps, then the justification for each line on the
-display is determined by the first character of that display line.
-
-=item B<-lmargin1> =E<gt> I<pixels>
-
-If the first character of a text line has a tag for which this
-option has been specified, then I<pixels> specifies how
-much the line should be indented from the left edge of the
-window.
-I<Pixels> may have any of the standard forms for screen
-distances.
-If a line of text wraps, this option only applies to the
-first line on the display; the B<-lmargin2> option controls
-the indentation for subsequent lines.
-
-=item B<-lmargin2> =E<gt> I<pixels>
-
-If the first character of a display line has a tag for which this
-option has been specified, and if the display line is not the
-first for its text line (i.e., the text line has wrapped), then
-I<pixels> specifies how much the line should be indented from
-the left edge of the window.
-I<Pixels> may have any of the standard forms for screen
-distances.
-This option is only used when wrapping is enabled, and it only
-applies to the second and later display lines for a text line.
-
-=item B<-offset> =E<gt> I<pixels>
-
-I<Pixels> specifies an amount by which the text's baseline
-should be offset vertically from the baseline of the overall
-line, in pixels.
-For example, a positive offset can be used for superscripts
-and a negative offset can be used for subscripts.
-I<Pixels> may have any of the standard forms for screen
-distances.
-
-=item B<-overstrike> =E<gt> I<boolean>
-
-Specifies whether or not to draw a horizontal rule through
-the middle of characters.
-I<Boolean> may have any of the forms accepted by B<Tk_GetBoolean>.
-
-=item B<-relief> =E<gt> I<relief>
-
-I<Relief> specifies the 3-D relief to use for drawing backgrounds,
-in any of the forms accepted by B<Tk_GetRelief>.
-This option is used in conjunction with the B<-borderwidth>
-option to give a 3-D appearance to the background for characters;
-it is ignored unless the B<-background> option
-has been set for the tag.
-
-=item B<-rmargin> =E<gt> I<pixels>
-
-If the first character of a display line has a tag for which this
-option has been specified, then I<pixels> specifies how wide
-a margin to leave between the end of the line and the right
-edge of the window.
-I<Pixels> may have any of the standard forms for screen
-distances.
-This option is only used when wrapping is enabled.
-If a text line wraps, the right margin for each line on the
-display is determined by the first character of that display
-line.
-
-=item B<-spacing1> =E<gt> I<pixels>
-
-I<Pixels> specifies how much additional space should be
-left above each text line, using any of the standard forms for
-screen distances.
-If a line wraps, this option only applies to the first
-line on the display.
-
-=item B<-spacing2> =E<gt> I<pixels>
-
-For lines that wrap, this option specifies how much additional
-space to leave between the display lines for a single text line.
-I<Pixels> may have any of the standard forms for screen
-distances.
-
-=item B<-spacing3> =E<gt> I<pixels>
-
-I<Pixels> specifies how much additional space should be
-left below each text line, using any of the standard forms for
-screen distances.
-If a line wraps, this option only applies to the last
-line on the display.
-
-=item B<-tabs> =E<gt> I<tabList>
-
-I<TabList> specifies a set of tab stops in the same form
-as for the B<-tabs> option for the text widget. This
-option only applies to a display line if it applies to the
-first character on that display line.
-If this option is specified as an empty string, it cancels
-the option, leaving it unspecified for the tag (the default).
-If the option is specified as a non-empty string that is
-an empty list, such as B<-tabs => " ">, then it requests
-default 8-character tabs as described for the B<tabs>
-widget option.
-
-=item B<-underline> =E<gt> I<boolean>
-
-I<Boolean> specifies whether or not to draw an underline underneath
-characters.
-It may have any of the forms accepted by B<Tk_GetBoolean>.
-
-=item B<-wrap> =E<gt> I<mode>
-
-I<Mode> specifies how to handle lines that are wider than the
-text's window.
-It has the same legal values as the B<-wrap> option
-for the text widget: B<none>, B<char>, or B<word>.
-If this tag option is specified, it overrides the B<-wrap> option
-for the text widget.
-
-=back
-
-If a character has several tags associated with it, and if their
-display options conflict, then the options of the highest priority
-tag are used.
-If a particular display option hasn't been specified for a
-particular tag, or if it is specified as an empty string, then
-that option will never be used; the next-highest-priority
-tag's option will used instead.
-If no tag specifies a particular display option, then the default
-style for the widget will be used.
-
-The second purpose for tags is event bindings.
-You can associate bindings with a tag in much the same way you can
-associate bindings with a widget class: whenever particular X
-events occur on characters with the given tag, a given
-<perl/Tk callback|Tk::callbacks> will be executed.
-Tag bindings can be used to give behaviors to ranges of characters;
-among other things, this allows hypertext-like
-features to be implemented.
-For details, see the description of the B<tagBind> widget
-method below.
-
-The third use for tags is in managing the selection.
-See L<"THE SELECTION"> below.
-
-=head1 MARKS
-
-The second form of annotation in text widgets is a mark.
-Marks are used for remembering particular places in a text.
-They are something like tags, in that they have names and
-they refer to places in the file, but a mark isn't associated
-with particular characters.
-Instead, a mark is associated with the gap between two characters.
-Only a single position may be associated with a mark at any given
-time.
-If the characters around a mark are deleted the mark will still
-remain; it will just have new neighbor characters.
-In contrast, if the characters containing a tag are deleted then
-the tag will no longer have an association with characters in
-the file.
-Marks may be manipulated with the ``I<$text>-E<gt>B<mark>'' text widget
-method, and their current locations may be determined by using the
-mark name as an index in methods.
-
-Each mark also has a I<gravity>, which is either B<left> or
-B<right>.
-The gravity for a mark specifies what happens to the mark when
-text is inserted at the point of the mark.
-If a mark has left gravity, then the mark is treated as if it
-were attached to the character on its left, so the mark will
-remain to the left of any text inserted at the mark position.
-If the mark has right gravity, new text inserted at the mark
-position will appear to the right of the mark. The gravity
-for a mark defaults to B<right>.
-
-The name space for marks is different from that for tags: the
-same name may be used for both a mark and a tag, but they will refer
-to different things.
-
-Two marks have special significance.
-First, the mark B<insert> is associated with the insertion cursor,
-as described under L<"THE INSERTION CURSOR"> below.
-Second, the mark B<current> is associated with the character
-closest to the mouse and is adjusted automatically to track the
-mouse position and any changes to the text in the widget (one
-exception: B<current> is not updated in response to mouse
-motions if a mouse button is down; the update will be deferred
-until all mouse buttons have been released).
-Neither of these special marks may be deleted.
-
-=head1 EMBEDDED WINDOWS
-
-The third form of annotation in text widgets is an embedded window.
-Each embedded window annotation causes a window to be displayed
-at a particular point in the text.
-There may be any number of embedded windows in a text widget,
-and any widget may be used as an embedded window (subject to the
-usual rules for geometry management, which require the text window
-to be the parent of the embedded window or a descendant of its
-parent).
-The embedded window's position on the screen will be updated as the
-text is modified or scrolled, and it will be mapped and unmapped as
-it moves into and out of the visible area of the text widget.
-Each embedded window occupies one character's worth of index space
-in the text widget, and it may be referred to either by the name
-of its embedded window or by its position in the widget's
-index space.
-If the range of text containing the embedded window is deleted then
-the window is destroyed.
-
-When an embedded window is added to a text widget with the
-B<widgetCreate> method, several configuration
-options may be associated with it.
-These options may be modified later with the B<widgetConfigure>
-method.
-The following options are currently supported:
-
-=over 4
-
-=item B<-align> =E<gt> I<where>
-
-If the window is not as tall as the line in which it is displayed,
-this option determines where the window is displayed in the line.
-I<Where> must have one of the values B<top> (align the top of the window
-with the top of the line), B<center> (center the window
-within the range of the line), B<bottom> (align the bottom of the
-window with the bottom of the line's area),
-or B<baseline> (align the bottom of the window with the baseline
-of the line).
-
-=item B<-create> =E<gt> I<callback>
-
-Specifies a L<callback|Tk::callbacks> that may be evaluated to create the window
-for the annotation.
-If no B<-window> option has been specified for the annotation
-this I<callback> will be evaluated when the annotation is about to
-be displayed on the screen.
-I<Callback> must create a window for the annotation and return
-the name of that window as its result.
-If the annotation's window should ever be deleted, I<callback>
-will be evaluated again the next time the annotation is displayed.
-
-=item B<-padx> =E<gt> I<pixels>
-
-I<Pixels> specifies the amount of extra space to leave on
-each side of the embedded window.
-It may have any of the usual forms defined for a screen distance
-(see B<Tk_GetPixels>).
-
-=item B<-pady> =E<gt> I<pixels>
-
-I<Pixels> specifies the amount of extra space to leave on
-the top and on the bottom of the embedded window.
-It may have any of the usual forms defined for a screen distance
-(see B<Tk_GetPixels>).
-
-=item B<-stretch> =E<gt> I<boolean>
-
-If the requested height of the embedded window is less than the
-height of the line in which it is displayed, this option can be
-used to specify whether the window should be stretched vertically
-to fill its line.
-If the B<-pady> option has been specified as well, then the
-requested padding will be retained even if the window is
-stretched.
-
-=item B<-window> =E<gt> I<$widget>
-
-Specifies the name of a window to display in the annotation.
-
-=back
-
-=head1 EMBEDDED IMAGES
-
-The final form of annotation in text widgets is an embedded image.
-Each embedded image annotation causes an image to be displayed
-at a particular point in the text.
-There may be any number of embedded images in a text widget,
-and a particular image may be embedded in multiple places in the same
-text widget.
-The embedded image's position on the screen will be updated as the
-text is modified or scrolled.
-Each embedded image occupies one character's worth of index space
-in the text widget, and it may be referred to either by
-its position in the widget's index space, or the name it is assigned
-when the image is inserted into the text widget with B<imageCreate>.
-If the range of text containing the embedded image is deleted then
-that copy of the image is removed from the screen.
-
-When an embedded image is added to a text widget with the B<image>
-create method, a name unique to this instance of the image
-is returned. This name may then be used to refer to this image
-instance. The name is taken to be the value of the B<-name> option
-(described below). If the B<-name> option is not provided, the
-B<-image> name is used instead. If the I<imageName> is already
-in use in the text widget, then B<#>I<nn> is added to the end of the
-I<imageName>, where I<nn> is an arbitrary integer. This insures
-the I<imageName> is unique.
-Once this name is assigned to this instance of the image, it does not
-change, even though the B<-image> or B<-name> values can be changed
-with B<image configure>.
-
-When an embedded image is added to a text widget with the
-B<imageCreate> method, several configuration
-options may be associated with it.
-These options may be modified later with the B<image configure>
-method.
-The following options are currently supported:
-
-=over 4
-
-=item B<-align> =E<gt> I<where>
-
-If the image is not as tall as the line in which it is displayed,
-this option determines where the image is displayed in the line.
-I<Where> must have one of the values B<top> (align the top of the image
-with the top of the line), B<center> (center the image
-within the range of the line), B<bottom> (align the bottom of the
-image with the bottom of the line's area),
-or B<baseline> (align the bottom of the image with the baseline
-of the line).
-
-=item B<-image> =E<gt> I<image>
-
-Specifies the name of the Tk image to display in the annotation.
-If I<image> is not a valid Tk image, then an error is returned.
-
-=item B<-name> =E<gt> I<ImageName>
-
-Specifies the name by which this image instance may be referenced in
-the text widget. If I<ImageName> is not supplied, then the
-name of the Tk image is used instead.
-If the I<imageName> is already in use, I<#nn> is appended to
-the end of the name as described above.
-
-=item B<-padx> =E<gt> I<pixels>
-
-I<Pixels> specifies the amount of extra space to leave on
-each side of the embedded image.
-It may have any of the usual forms defined for a screen distance.
-
-=item B<-pady> =E<gt> I<pixels>
-
-I<Pixels> specifies the amount of extra space to leave on
-the top and on the bottom of the embedded image.
-It may have any of the usual forms defined for a screen distance.
-
-=back
-
-=head1 THE SELECTION
-
-Selection support is implemented via tags.
-If the B<exportSelection> option for the text widget is true
-then the B<sel> tag will be associated with the selection:
-
-=over 4
-
-=item [1]
-
-Whenever characters are tagged with B<sel> the text widget
-will claim ownership of the selection.
-
-=item [2]
-
-Attempts to retrieve the
-selection will be serviced by the text widget, returning all the
-characters with the B<sel> tag.
-
-=item [3]
-
-If the selection is claimed away by another application or by another
-window within this application, then the B<sel> tag will be removed
-from all characters in the text.
-
-=item [4]
-
-Whenever the sel tag range changes a virtual event B<<<Selection>>>
-is generated.
-
-The B<sel> tag is automatically defined when a text widget is
-created, and it may not be deleted with the ``I<$text>-E<gt>B<tagDelete>''
-method. Furthermore, the B<selectBackground>,
-B<selectBorderWidth>, and B<selectForeground> options for
-the text widget are tied to the B<-background>,
-B<-borderwidth>, and B<-foreground> options for the B<sel>
-tag: changes in either will automatically be reflected in the
-other.
-
-=back
-
-=head1 THE INSERTION CURSOR
-
-The mark named B<insert> has special significance in text widgets.
-It is defined automatically when a text widget is created and it
-may not be unset with the ``I<$text>-E<gt>B<markUnset>'' widget
-command.
-The B<insert> mark represents the position of the insertion
-cursor, and the insertion cursor will automatically be drawn at
-this point whenever the text widget has the input focus.
-
-=head1 THE MODIFIED FLAG
-
-The text widget can keep track of changes to the content of the widget
-by means of the modified flag. Inserting or deleting text will set this
-flag. The flag can be queried, set and cleared programatically as well.
-Whenever the flag changes state a B<<<Modified>>> virtual event is gener-
-ated. See the edit modified widget command for more details.
-
-
-=head1 WIDGET METHODS
-
-The B<Text> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-The following additional methods are available for text widgets.
-In addition, the extended text widget methods as documented
-in I<"Mastering Perl/Tk"> are included in this pod (with
-permission from the publisher, B<O'Reilly and Associates Inc.>).
-
-=over 4
-
-=item I<$text>-E<gt>B<adjustSelect>
-
-Moves the end point of the selection and anchor point to the
-mouse pointer location.
-
-=item I<$text>-E<gt>B<bbox>(I<index>)
-
-Returns a list of four elements describing the screen area
-of the character given by I<index>.
-The first two elements of the list give the x and y coordinates
-of the upper-left corner of the area occupied by the
-character, and the last two elements give the width and height
-of the area.
-If the character is only partially visible on the screen, then
-the return value reflects just the visible part.
-If the character is not visible on the screen then the return
-value is an empty list.
-
-=item I<$text>-E<gt>B<clipboardColumnCopy>
-
-Performs a rectangular copy of the currently selected text with
-basic compensation for tab characters.
-
-=item I<$text>-E<gt>B<clipboardColumnCut>
-
-Performs a rectangular cut of the currently selected text with
-basic compensation for tab characters.
-
-=item I<$text>-E<gt>B<clipboardColumnPaste>
-
-Performs a rectangular paste of the text in the clipboard. The
-upper-left corner is specified by the current position of the
-insert mark with basic compensation for tab characters.
-
-=item I<$text>-E<gt>B<compare>(I<index1, op, index2>)
-
-Compares the indices given by I<index1> and I<index2> according
-to the relational operator given by I<op>, and returns 1 if
-the relationship is satisfied and 0 if it isn't.
-I<Op> must be one of the operators E<lt>, E<lt>=, ==, E<gt>=, E<gt>, or !=.
-If I<op> is == then 1 is returned if the two indices refer to
-the same character, if I<op> is E<lt> then 1 is returned if I<index1>
-refers to an earlier character in the text than I<index2>, and
-so on.
-
-=item I<$text>-E<gt>B<Contents>(I<?args>?)
-
-Query or change the entire contents of the text widget. If no
-arguments are given, the entire contents of the text widget are
-returned. If any arguments are given, the entire contents of the
-text widget are deleted and replaced by the argument list.
-
-=item I<$text>-E<gt>B<debug>(?I<boolean>?)
-
-If I<boolean> is specified, then it must have one of the true or
-false values accepted by Tcl_GetBoolean.
-If the value is a true one then internal consistency checks will be
-turned on in the B-tree code associated with text widgets.
-If I<boolean> has a false value then the debugging checks will
-be turned off.
-In either case the command returns an empty string.
-If I<boolean> is not specified then the command returns B<on>
-or B<off> to indicate whether or not debugging is turned on.
-There is a single debugging switch shared by all text widgets: turning
-debugging on or off in any widget turns it on or off for all widgets.
-For widgets with large amounts of text, the consistency checks may
-cause a noticeable slow-down.
-
-=item I<$text>-E<gt>B<delete>(I<index1, >?I<index2>?)
-
-Delete a range of characters from the text.
-If both I<index1> and I<index2> are specified, then delete
-all the characters starting with the one given by I<index1>
-and stopping just before I<index2> (i.e. the character at
-I<index2> is not deleted).
-If I<index2> doesn't specify a position later in the text
-than I<index1> then no characters are deleted.
-If I<index2> isn't specified then the single character at
-I<index1> is deleted.
-It is not allowable to delete characters in a way that would leave
-the text without a newline as the last character.
-The command returns an empty string.
-If more indices are given, multiple ranges of text will
-be deleted. All indices are first checked for validity before
-any deletions are made. They are sorted and the text is removed
-from the last range to the first range to deleted text does not
-cause a undesired index shifting side-effects. If multiple
-ranges with the same start index are given, then the longest
-range is used. If overlapping ranges are given, then they will
-be merged into spans that do not cause deletion of text outside
-the given ranges due to text shifted during deletion.
-
-=item I<$text>-E<gt>B<deleteSelected>
-
-Delete the currently selected text.
-
-=item I<$text>-E<gt>B<deleteTextTaggedWith>(I<tag>)
-
-Delete the text tagged with the I<tag> parameter.
-
-=item I<$text>-E<gt>B<deleteToEndofLine>
-
-Delete from the insert mark location to the end of line.
-
-=item I<$text>-E<gt>B<dlineinfo>(I<index>)
-
-Returns a list with five elements describing the area occupied
-by the display line containing I<index>.
-The first two elements of the list give the x and y coordinates
-of the upper-left corner of the area occupied by the
-line, the third and fourth elements give the width and height
-of the area, and the fifth element gives the position of the baseline
-for the line, measured down from the top of the area.
-All of this information is measured in pixels.
-If the current wrap mode is B<none> and the line extends beyond
-the boundaries of the window,
-the area returned reflects the entire area of the line, including the
-portions that are out of the window.
-If the line is shorter than the full width of the window then the
-area returned reflects just the portion of the line that is occupied
-by characters and embedded windows.
-If the display line containing I<index> is not visible on
-the screen then the return value is an empty list.
-
-=item I<$text>-E<gt>B<dump>(?I<switches>?, I<index1, >?I<index2>?)
-
-Return the contents of the text widget from I<index1> up to,
-but not including I<index2>,
-including the text and
-information about marks, tags, and embedded windows.
-If I<index2> is not specified, then it defaults to
-one character past I<index1>. The information is returned
-in the following format:
-
-I<key1 value1 index1 key2 value2 index2> ...
-
-The possible I<key> values are B<text>, B<mark>,
-B<tagon>, B<tagoff>, and I<$text>. The corresponding
-I<value> is the text, mark name, tag name, or window name.
-The I<index> information is the index of the
-start of the text, the mark, the tag transition, or the window.
-One or more of the following switches (or abbreviations thereof)
-may be specified to control the dump:
-
-=over 4
-
-=item B<-all>
-
-Return information about all elements: text, marks, tags, and windows.
-This is the default.
-
-=item B<-command> =E<gt> I<callback>
-
-Instead of returning the information as the result of the dump operation,
-invoke the I<callback> on each element of the text widget within the range.
-The callback has three arguments appended to it before it is evaluated:
-the I<key>, I<value>, and I<index>.
-
-=item B<-mark>
-
-Include information about marks in the dump results.
-
-=item B<-tag>
-
-Include information about tag transitions in the dump results. Tag information is
-returned as B<tagon> and B<tagoff> elements that indicate the
-begin and end of each range of each tag, respectively.
-
-=item B<-text>
-
-Include information about text in the dump results. The value is the
-text up to the next element or the end of range indicated by I<index2>.
-A text element does not span newlines. A multi-line block of text that
-contains no marks or tag transitions will still be dumped as a set
-of text seqments that each end with a newline. The newline is part
-of the value.
-
-=item B<-window>
-
-=back
-
-Include information about embedded windows in the dump results.
-The value of a window is its Tk pathname, unless the window
-has not been created yet. (It must have a create script.)
-In this case an empty string is returned, and you must query the
-window by its index position to get more information.
-
-=item I<$text>-E<gt>B<edit>( I< option, ?arg, arg ...?> );
-
-This command controls the undo mechanism and the modified flag.
-The exact behavior of the command depends on the option argument
-that follows the edit argument. The following forms of the command
-are currently supported:
-
-=over 4
-
-=item I<$text>-E<gt>B<editModified>( ?boolean? );
-
-If boolean is not specified, returns the modified flag of
-the widget. The insert, delete, edit undo and edit redo
-commands or the user can set or clear the modified flag.
-If boolean is specified, sets the modified flag of the
-widget to boolean.
-
-=item I<$text>-E<gt>B<editRedo>;
-
-(Not implemented, use B<TextUndo>.) When the B<-undo> option is true,
-reapplies the last undone edits provided no other edits were done
-since then. Generates an error when the redo stack is empty. Does
-nothing when the B<-undo> option is false.
-
-=item I<$text>-E<gt>B<editReset>;
-
-(Not implemented, use B<TextUndo>.) Clears the undo and redo stacks.
-
-=item I<$text>-E<gt>B<editSeparator>;
-
-(Not implemented, use B<TextUndo>.) Inserts a separator (boundary) on
-the undo stack. Does nothing when the -undo option is false.
-
-=item I<$text>-E<gt>B<editUndo>;
-
-(Not implemented, use B<TextUndo>.) Undoes the last edit action when
-the -undo option is true. An edit action is defined as all the insert
-and delete commands that are recorded on the undo stack in between two
-separators. Generates an error when the undo stack is empty. Does
-nothing when the -undo option is false.
-
-=back
-
-=item I<$text>-E<gt>B<FindAll>(I<mode, case, pattern>)
-
-Removes any current selections and then performs a global text
-search. All matches are tagged with the B<sel> tag.
-
-I<mode> can be be B<-exact> or B<-regexp>. See the B<search> command
-for more information
-
-I<case> can be B<-nocase> or B<-case>. See the B<search> command
-for more information
-
-I<pattern> is an exact string to match if I<mode> is B<-exact> or a
-regular expression if the match I<mode> is B<-regexp>.
-
-
-=item I<$text>-E<gt>B<FindAndReplaceAll>(I<mode, case, find, replace>)
-
-Same as the B<FindAll> method, however additionally substitutes the
-matched text with the characters I<replace>.
-
-=item I<$text>-E<gt>B<FindAndReplacePopUp>
-
-Creates a find-and-replace popup window if one does not already exist.
-If there is currently selected text, then the 'find' field will be
-'pre-filled' with the selection.
-
-=item I<$text>-E<gt>B<FindNext>(I<direction, mode, case, pattern>)
-
-Removes any current selections and then performs a forward or reverse
-text search. All matches are tagged with the B<sel> tag. I<direction>
-can be B<-forwards> or B<-backwards>. I<mode, case> and I<pattern> are
-as for the B<FindAll> method.
-
-=item I<$text>-E<gt>B<FindPopUp>
-
-Creates a find popup, if one does not yet exist. If there is currently
-selected text, then the 'find' field will be 'pre-filled' with the
-selection.
-
-=item I<$text>-E<gt>B<FindSelectionNext>
-
-Gets the currently selected text and removes all selections. It then
-finds the next exact, case-sensitive string that matches in a forward
-direction and selects the text and makes the new selection visible.
-
-=item I<$text>-E<gt>B<FindSelectionPrevious>
-
-Gets the currently selected text and removes all selections. It then
-finds the next exact, case-sensitive string that matches in a reverse
-direction and selects the text and makes the new selection visible.
-
-=item I<$text>-E<gt>B<get>(I<index1, >?I<index2>?)
-
-Return a range of characters from the text. The return value will be
-all the characters in the text starting with the one whose index is
-I<index1> and ending just before the one whose index is I<index2> (the
-character at I<index2> will not be returned). If I<index2> is omitted
-then the single character at I<index1> is returned. If there are no
-characters in the specified range (e.g. I<index1> is past the end of
-the file or I<index2> is less than or equal to I<index1>) then an
-empty string is returned. If the specified range contains embedded
-windows, no information about them is included in the returned string.
-If multiple index pairs are given, multiple ranges of text will be
-returned in a list. Invalid ranges will not be represented with empty
-strings in the list. The ranges are returned in the order passed to
-B<get>.
-
-=item I<$text>-E<gt>B<getSelected>
-
-Return the currently selected text.
-
-=item I<$text>-E<gt>B<GetTextTaggedWith>(I<tag>)
-
-Return the text tagged with the I<tag> parameter.
-
-=item I<$text>-E<gt>B<GotoLineNumber>(I<line_number>)
-
-Set the insert mark to I<line_number> and ensures the line is
-visible.
-
-=item I<$text>-E<gt>B<GotoLineNumberPopUp>(I<line_number>)
-
-Displays a popup, pre-filling it with selected numeric text
-(if any), or the line number from B<GotoLineNumber> (if any).
-
-=item I<$text>-E<gt>B<image>(I<option>, ?I<arg, arg, ...>?)
-
-=item I<$text>-E<gt>B<image>I<Option>(?I<arg, arg, ...>?)
-
-This method is used to manipulate embedded images.
-The behavior of the method depends on the I<option> argument
-that follows the B<image> prefix.
-The following forms of the methods are currently supported:
-
-=over 8
-
-=item I<$text>-E<gt>B<imageCget>(I<index, option>)
-
-Returns the value of a configuration option for an embedded image.
-I<Index> identifies the embedded image, and I<option>
-specifies a particular configuration option, which must be one of
-the ones listed in L<"EMBEDDED IMAGES">.
-
-=item I<$text>-E<gt>B<imageConfigure>(I<index, >?I<option, value, ...>?)
-
-Query or modify the configuration options for an embedded image.
-If no I<option> is specified, returns a list describing all of
-the available options for the embedded image at I<index>
-(see L<Tk::options> for information on the format of this list).
-If I<option> is specified with no I<value>, then the command
-returns a list describing the one named option (this list will be
-identical to the corresponding sublist of the value returned if no
-I<option> is specified).
-If one or more I<option-value> pairs are specified, then the command
-modifies the given option(s) to have the given value(s); in
-this case the command returns an empty string.
-See L<"EMBEDDED IMAGES"> for information on the options that
-are supported.
-
-=item I<$text>-E<gt>B<imageCreate>(I<index, >?I<option, value, ...>?)
-
-This command creates a new image annotation, which will appear
-in the text at the position given by I<index>.
-Any number of I<option-value> pairs may be specified to
-configure the annotation.
-Returns a unique identifier that may be used as an index to refer to
-this image.
-See L<"EMBEDDED IMAGES"> for information on the options that
-are supported, and a description of the identifier returned.
-
-=item I<$text>-E<gt>B<imageNames>
-
-Returns a list whose elements are the names of all image instances currently
-embedded in $text.
-
-=back
-
-=item I<$text>-E<gt>B<index>(I<index>)
-
-Returns the position corresponding to I<index> in the form
-I<line.char> where I<line> is the line number and I<char>
-is the character number.
-I<Index> may have any of the forms described under L<"INDICES"> above.
-
-=item I<$text>-E<gt>B<insert>(I<index, chars, >?I<tagList, chars, tagList, ...>?)
-
-Inserts all of the I<chars> arguments just before the character at
-I<index>.
-If I<index> refers to the end of the text (the character after
-the last newline) then the new text is inserted just before the
-last newline instead.
-If there is a single I<chars> argument and no I<tagList>, then
-the new text will receive any tags that are present on both the
-character before and the character after the insertion point; if a tag
-is present on only one of these characters then it will not be
-applied to the new text.
-If I<tagList> is specified then it consists of a list of
-tag names; the new characters will receive all of the tags in
-this list and no others, regardless of the tags present around
-the insertion point.
-If multiple I<chars>-I<tagList> argument pairs are present,
-they produce the same effect as if a separate B<insert> widget
-command had been issued for each pair, in order.
-The last I<tagList> argument may be omitted.
-
-=item I<$text>-E<gt>B<Insert>(I<string>)
-
-Do NOT confuse this with the lower-case B<insert> method.
-Insert I<string> at the point of the insertion cursor. If there is
-a selection in the text, and it covers the point of the insertion
-cursor, then it deletes the selection before inserting.
-
-=item I<$text>-E<gt>B<InsertKeypress>(I<character>)
-
-Inserts I<character> at the B<insert> mark. If in overstrike mode,
-it firsts deletes the character at the B<insert> mark.
-
-=item I<$text>-E<gt>B<InsertSelection>
-
-Inserts the current selection at the B<insert> mark.
-
-=item I<$text>-E<gt>B<insertTab>
-
-Inserts a tab (\t) character at the B<insert> mark.
-
-=item I<$text>-E<gt>B<mark>(I<option, >?I<arg, arg, ...>?)
-
-This command is used to manipulate marks. The exact behavior of
-the command depends on the I<option> argument that follows
-the B<mark> argument. The following forms of the command
-are currently supported:
-
-=over 8
-
-=item I<$text>-E<gt>B<markGravity>(I<markName, >?I<direction>?)
-
-If I<direction> is not specified, returns B<left> or B<right>
-to indicate which of its adjacent characters I<markName> is attached
-to.
-If I<direction> is specified, it must be B<left> or B<right>;
-the gravity of I<markName> is set to the given value.
-
-=item I<$text>-E<gt>B<markNames>
-
-Returns a list whose elements are the names of all the marks that
-are currently set.
-
-=item I<$text>-E<gt>B<markNext>(I<index>)
-
-Returns the name of the next mark at or after I<index>.
-If I<index> is specified in numerical form, then the search for
-the next mark begins at that index.
-If I<index> is the name of a mark, then the search for
-the next mark begins immediately after that mark.
-This can still return a mark at the same position if
-there are multiple marks at the same index.
-These semantics mean that the B<mark next> operation can be used to
-step through all the marks in a text widget in the same order
-as the mark information returned by the B<dump> operation.
-If a mark has been set to the special B<end> index,
-then it appears to be I<after> B<end> with respect to the B<mark next> operation.
-An empty string is returned if there are no marks after I<index>.
-
-=item I<$text>-E<gt>B<markPrevious>(I<index>)
-
-Returns the name of the mark at or before I<index>.
-If I<index> is specified in numerical form, then the search for
-the previous mark begins with the character just before that index.
-If I<index> is the name of a mark, then the search for
-the next mark begins immediately before that mark.
-This can still return a mark at the same position if
-there are multiple marks at the same index.
-These semantics mean that the B<mark previous> operation can be used to
-step through all the marks in a text widget in the reverse order
-as the mark information returned by the B<dump> operation.
-An empty string is returned if there are no marks before I<index>.
-
-=item I<$text>-E<gt>B<markSet>(I<markName, index>)
-
-Sets the mark named I<markName> to a position just before the
-character at I<index>.
-If I<markName> already exists, it is moved from its old position;
-if it doesn't exist, a new mark is created.
-This command returns an empty string.
-
-=item I<$text>-E<gt>B<markUnset>(I<markName>?, I<markName, markName, ...>?)
-
-Remove the mark corresponding to each of the I<markName> arguments.
-The removed marks will not be usable in indices and will not be
-returned by future calls to ``I<$text>-E<gt>B<markNames>''.
-This command returns an empty string.
-
-=back
-
-=item I<$text>-E<gt>B<markExists>(I<markname>)
-
-Returns true if I<markname> exists - false otherwise.
-
-=item I<$text>-E<gt>B<menu>(I<?menu?>)
-
-If I<menu> reference is given as an argument, then the text widget
-menu is adjusted to use this new I<menu>. If the I<menu> argument
-is B<undef>, then this command disables the current text widget menu.
-If the I<menu> argument is omitted altogether, then the current text
-widget menu reference is returned.
-
-=item I<$text>-E<gt>B<openLine>
-
-Inserts a newline (\n) at the insert mark.
-
-=item I<$text>-E<gt>B<OverstrikeMode>(I<?boolean?>)
-
-Returns the overstrike mode if I<boolean> is omitted or sets the
-overstrike mode to I<boolean>. True means overstrike mode is enabled.
-
-=item I<$text>-E<gt>B<PostPopupMenu>(I<x,y>)
-
-Creates a popup menu at the specified (I<x,y>) pixel coordinates. The
-default menu has File, Edit, Search and View menu items which cascade
-to sub-menus for further commands. There is an implicit E<lt>Button-3E<gt>
-binding to this method that posts the menu over the cursor.
-
-=item I<$text>-E<gt>B<ResetAnchor>
-
-Sets the selection anchor to whichever end is farthest from the index
-argument.
-
-=item I<$text>-E<gt>B<scan>(I<option>, I<args>) or
-
-=item I<$text>-E<gt>B<scan>I<option>(I<args>)
-
-This method is used to implement scanning on texts. It has
-two forms, depending on I<option>:
-
-=over 8
-
-=item I<$text>-E<gt>B<scanMark>(I<x, y>)
-
-Records I<x> and I<y> and the current view in the text window,
-for use in conjunction with later B<scanDragto> method.
-Typically this method is associated with a mouse button press in
-the widget. It returns an empty string.
-
-=item I<$text>-E<gt>B<scanDragto>(I<x, y>)
-
-This command computes the difference between its I<x> and I<y>
-arguments and the I<x> and I<y> arguments to the last
-B<scanMark> method for the widget.
-It then adjusts the view by 10 times the difference in coordinates.
-This command is typically associated
-with mouse motion events in the widget, to produce the effect of
-dragging the text at high speed through the window. The return
-value is an empty string.
-
-=back
-
-=item I<$text>-E<gt>B<search>(?I<switches>,? I<pattern, index, >?I<stopIndex>?)
-
-Searches the text in I<$text> starting at I<index> for a range
-of characters that matches I<pattern>.
-If a match is found, the index of the first character in the match is
-returned as result; otherwise an empty string is returned.
-One or more of the following switches (or abbreviations thereof)
-may be specified to control the search:
-
-=over 8
-
-=item B<-forwards>
-
-The search will proceed forward through the text, finding the first
-matching range starting at or after the position given by I<index>.
-This is the default.
-
-=item B<-backwards>
-
-The search will proceed backward through the text, finding the
-matching range closest to I<index> whose first character
-is before I<index>.
-
-=item B<-exact>
-
-Use exact matching: the characters in the matching range must be
-identical to those in I<pattern>.
-This is the default.
-
-=item B<-regexp>
-
-Treat I<pattern> as a regular expression and match it against
-the text using the rules for regular expressions (see the B<regexp>
-command for details).
-
-=item B<-nocase>
-
-Ignore case differences between the pattern and the text.
-
-=item B<-count>I< varName>
-
-The argument following B<-count> gives the name of a variable;
-if a match is found, the number of characters in the matching
-range will be stored in the variable.
-
-=item B<-hidden>
-
-Find hidden text as well. By default only displayed text is found.
-
-=item B<-->
-
-This switch has no effect except to terminate the list of switches:
-the next argument will be treated as I<pattern> even if it starts
-with B<->.
-
-=back
-
-=back
-
-The matching range must be entirely within a single line of text.
-For regular expression matching the newlines are removed from the ends
-of the lines before matching: use the B<$> feature in regular
-expressions to match the end of a line.
-For exact matching the newlines are retained.
-If I<stopIndex> is specified, the search stops at that index:
-for forward searches, no match at or after I<stopIndex> will
-be considered; for backward searches, no match earlier in the
-text than I<stopIndex> will be considered.
-If I<stopIndex> is omitted, the entire text will be searched:
-when the beginning or end of the text is reached, the search
-continues at the other end until the starting location is reached
-again; if I<stopIndex> is specified, no wrap-around will occur.
-
-=over 4
-
-=item I<$text>-E<gt>B<see>(I<index>)
-
-Adjusts the view in the window so that the character given by I<index>
-is completely visible.
-If I<index> is already visible then the command does nothing.
-If I<index> is a short distance out of view, the command
-adjusts the view just enough to make I<index> visible at the
-edge of the window.
-If I<index> is far out of view, then the command centers
-I<index> in the window.
-
-=item I<$text>-E<gt>B<selectAll>
-
-Selects all the text in the widget.
-
-=item I<$text>-E<gt>B<selectLine>
-
-Selects the line with the insert mark.
-
-=item I<$text>-E<gt>B<selectWord>
-
-Selects the word with the insert mark.
-
-=item I<$text>-E<gt>B<SetCursor>(I<position>)
-
-Moves the insert mark to I<position>.
-
-=item I<$text>-E<gt>B<tag>(I<option, >?I<arg, arg, ...>?)
-
-This command is used to manipulate tags. The exact behavior of the
-command depends on the I<option> argument that follows the
-B<tag> argument. The following forms of the command are currently
-supported:
-
-=over 8
-
-=item I<$text>-E<gt>B<tagAdd>(I<tagName, index1, >?I<index2, index1, index2, ...>?)
-
-Associate the tag I<tagName> with all of the characters starting
-with I<index1> and ending just before
-I<index2> (the character at I<index2> isn't tagged).
-A single command may contain any number of I<index1>-I<index2>
-pairs.
-If the last I<index2> is omitted then the single character at
-I<index1> is tagged.
-If there are no characters in the specified range (e.g. I<index1>
-is past the end of the file or I<index2> is less than or equal
-to I<index1>) then the command has no effect.
-
-=item I<$text>-E<gt>B<tagBind>(I<tagName, >?I<sequence>?, ?I<script>?)
-
-This command associates I<script> with the tag given by
-I<tagName>.
-Whenever the event sequence given by I<sequence> occurs for a
-character that has been tagged with I<tagName>,
-the script will be invoked.
-This method is similar to the B<bind> command except that
-it operates on characters in a text rather than entire widgets.
-See the L<Tk::bind> documentation for complete details
-on the syntax of I<sequence> and the substitutions performed
-on I<script> before invoking it.
-If all arguments are specified then a new binding is created, replacing
-any existing binding for the same I<sequence> and I<tagName>
-(if the first character of I<script> is ``+'' then I<script>
-augments an existing binding rather than replacing it).
-In this case the return value is an empty string.
-If I<script> is omitted then the command returns the I<script>
-associated with I<tagName> and I<sequence> (an error occurs
-if there is no such binding).
-If both I<script> and I<sequence> are omitted then the command
-returns a list of all the sequences for which bindings have been
-defined for I<tagName>.
-
-The only events for which bindings may be specified are those related
-to the mouse and keyboard (such as B<Enter>, B<Leave>,
-B<ButtonPress>, B<Motion>, and B<KeyPress>) or virtual events.
-Event bindings for a text widget use the B<current> mark described
-under L<"MARKS"> above. An B<Enter> event triggers for a tag when the tag
-first becomes present on the current character, and a B<Leave> event
-triggers for a tag when it ceases to be present on the current character.
-B<Enter> and B<Leave> events can happen either because the
-B<current> mark moved or because the character at that position
-changed. Note that these events are different than B<Enter> and
-B<Leave> events for windows. Mouse and keyboard events are directed
-to the current character. If a virtual event is used in a binding, that
-binding can trigger only if the virtual event is defined by an underlying
-mouse-related or keyboard-related event.
-
-It is possible for the current character to have multiple tags,
-and for each of them to have a binding for a particular event
-sequence.
-When this occurs, one binding is invoked for each tag, in order
-from lowest-priority to highest priority.
-If there are multiple matching bindings for a single tag, then
-the most specific binding is chosen (see the the documentation for
-the B<bind> command for details).
-B<continue> and B<break> commands within binding scripts
-are processed in the same way as for bindings created with
-the B<bind> command.
-
-If bindings are created for the widget as a whole using the
-B<bind> command, then those bindings will supplement the
-tag bindings.
-The tag bindings will be invoked first, followed by bindings
-for the window as a whole.
-
-=item I<$text>-E<gt>B<tagCget>(I<tagName, option>)
-
-This command returns the current value of the option named I<option>
-associated with the tag given by I<tagName>.
-I<Option> may have any of the values accepted by the B<tag configure>
-method.
-
-=item I<$text>-E<gt>B<tagConfigure>(I<tagName, >?I<option>?, ?I<value>?, ?I<option, value, ...>?)
-
-This command is similar to the B<configure> method except
-that it modifies options associated with the tag given by I<tagName>
-instead of modifying options for the overall text widget.
-If no I<option> is specified, the command returns a list describing
-all of the available options for I<tagName>
-(see L<Tk::options> for information on the format of this list).
-If I<option> is specified with no I<value>, then the command returns
-a list describing the one named option (this list will be identical to
-the corresponding sublist of the value returned if no I<option>
-is specified).
-If one or more I<option-value> pairs are specified, then the command
-modifies the given option(s) to have the given value(s) in I<tagName>;
-in this case the command returns an empty string.
-See L<"TAGS"> above for details on the options available for tags.
-
-=item I<$text>-E<gt>B<tagDelete>(I<tagName, >?I<tagName, ...>?)
-
-Deletes all tag information for each of the I<tagName>
-arguments.
-The command removes the tags from all characters in the file
-and also deletes any other information associated with the tags,
-such as bindings and display information.
-The command returns an empty string.
-
-=item I<$text>-E<gt>B<tagLower>(I<tagName>?, I<belowThis>?)
-
-Changes the priority of tag I<tagName> so that it is just lower
-in priority than the tag whose name is I<belowThis>.
-If I<belowThis> is omitted, then I<tagName>'s priority
-is changed to make it lowest priority of all tags.
-
-=item I<$text>-E<gt>B<tagNames>(?I<index>?)
-
-Returns a list whose elements are the names of all the tags that
-are active at the character position given by I<index>.
-If I<index> is omitted, then the return value will describe
-all of the tags that exist for the text (this includes all tags
-that have been named in a ``I<$text>-E<gt>B<tag>'' widget
-command but haven't been deleted by a ``I<$text>-E<gt>B<tagDelete>''
-method, even if no characters are currently marked with
-the tag).
-The list will be sorted in order from lowest priority to highest
-priority.
-
-=item I<$text>-E<gt>B<tagNextrange>(I<tagName, index1, >?I<index2>?)
-
-This command searches the text for a range of characters tagged
-with I<tagName> where the first character of the range is
-no earlier than the character at I<index1> and no later than
-the character just before I<index2> (a range starting at
-I<index2> will not be considered).
-If several matching ranges exist, the first one is chosen.
-The command's return value is a list containing
-two elements, which are the index of the first character of the
-range and the index of the character just after the last one in
-the range.
-If no matching range is found then the return value is an
-empty string.
-If I<index2> is not given then it defaults to the end of the text.
-
-=item I<$text>-E<gt>B<tagPrevrange>(I<tagName, index1, >?I<index2>?)
-
-This command searches the text for a range of characters tagged
-with I<tagName> where the first character of the range is
-before the character at I<index1> and no earlier than
-the character at I<index2> (a range starting at
-I<index2> will be considered).
-If several matching ranges exist, the one closest to I<index1> is chosen.
-The command's return value is a list containing
-two elements, which are the index of the first character of the
-range and the index of the character just after the last one in
-the range.
-If no matching range is found then the return value is an
-empty string.
-If I<index2> is not given then it defaults to the beginning of the text.
-
-=item I<$text>-E<gt>B<tagRaise>(I<tagName, >?I<aboveThis>?)
-
-Changes the priority of tag I<tagName> so that it is just higher
-in priority than the tag whose name is I<aboveThis>.
-If I<aboveThis> is omitted, then I<tagName>'s priority
-is changed to make it highest priority of all tags.
-
-=item I<$text>-E<gt>B<tagRanges>(I<tagName>)
-
-Returns a list describing all of the ranges of text that have been
-tagged with I<tagName>.
-The first two elements of the list describe the first tagged range
-in the text, the next two elements describe the second range, and
-so on.
-The first element of each pair contains the index of the first
-character of the range, and the second element of the pair contains
-the index of the character just after the last one in the
-range.
-If there are no characters tagged with I<tag> then an
-empty string is returned.
-
-=item I<$text>-E<gt>B<tagRemove>(I<tagName, index1, >?I<index2, index1, index2, ...>?)
-
-Remove the tag I<tagName> from all of the characters starting
-at I<index1> and ending just before
-I<index2> (the character at I<index2> isn't affected).
-A single command may contain any number of I<index1>-I<index2>
-pairs.
-If the last I<index2> is omitted then the single character at
-I<index1> is tagged.
-If there are no characters in the specified range (e.g. I<index1>
-is past the end of the file or I<index2> is less than or equal
-to I<index1>) then the command has no effect.
-This command returns an empty string.
-
-=back
-
-=item I<$text>-E<gt>B<ToggleInsertMode>
-
-Toggles the current overstrike mode.
-
-=item I<$text>-E<gt>B<unselectAll>
-
-Unselects all the text in the widget.
-
-=item I<$text>-E<gt>B<WhatLineNumberPopup>
-
-Creates a popup that displays the current line number of the
-insert mark.
-
-=item I<$text>->B<widget>(I<option?, arg, arg, ...>?)
-
-=item I<$text>->B<widget>I<Option>(?I<arg, arg, ...>?)
-
-This method is used to manipulate embedded windows.
-The behavior of the method depends on the I<option> argument
-that follows the B<window> argument.
-The following forms of the method are currently supported:
-
-=over 8
-
-=item I<$text>->B<windowCget>(I<index, option>)
-
-Returns the value of a configuration option for an embedded window.
-I<Index> identifies the embedded window, and I<option>
-specifies a particular configuration option, which must be one of
-the ones listed in L<"EMBEDDED WINDOWS"> above.
-
-=item I<$text>->B<windowConfigure>(I<index>?, I<option, value, ...>?)
-
-Query or modify the configuration options for an embedded window.
-If no I<option> is specified, returns a list describing all of
-the available options for the embedded window at I<index>
-(see L<Tk::options> for information on the format of this list).
-If I<option> is specified with no I<value>, then the command
-returns a list describing the one named option (this list will be
-identical to the corresponding sublist of the value returned if no
-I<option> is specified).
-If one or more I<option-value> pairs are specified, then the command
-modifies the given option(s) to have the given value(s); in
-this case the command returns an empty string.
-See L<"EMBEDDED WINDOWS"> above for information on the options that
-are supported.
-
-=item I<$text>->B<windowCreate>(I<index>?, I<option, value, ...>?)
-
-This command creates a new window annotation, which will appear
-in the text at the position given by I<index>.
-Any number of I<option-value> pairs may be specified to
-configure the annotation.
-See L<"EMBEDDED WINDOWS"> above for information on the options that
-are supported.
-Returns an empty string.
-
-=item I<$text>->B<windowNames>
-
-Returns a list whose elements are the names of all windows currently
-embedded in $text.
-
-=back
-
-=item I<$text>->B<xview>(I<option, args>)
-
-This command is used to query and change the horizontal position of the
-text in the widget's window. It can take any of the following
-forms:
-
-=over 8
-
-=item I<$text>->B<xview>
-
-Returns a list containing two elements.
-Each element is a real fraction between 0 and 1; together they describe
-the portion of the document's horizontal span that is visible in
-the window.
-For example, if the first element is .2 and the second element is .6,
-20% of the text is off-screen to the left, the middle 40% is visible
-in the window, and 40% of the text is off-screen to the right.
-The fractions refer only to the lines that are actually visible in the
-window: if the lines in the window are all very short, so that they
-are entirely visible, the returned fractions will be 0 and 1,
-even if there are other lines in the text that are
-much wider than the window.
-These are the same values passed to scrollbars via the B<-xscrollcommand>
-option.
-
-=item I<$text>-E<gt>B<xviewMoveto>(I<fraction>)
-
-Adjusts the view in the window so that I<fraction> of the horizontal
-span of the text is off-screen to the left.
-I<Fraction> is a fraction between 0 and 1.
-
-=item I<$text>-E<gt>B<xviewScroll>(I<number, what>)
-
-This command shifts the view in the window left or right according to
-I<number> and I<what>.
-I<Number> must be an integer.
-I<What> must be either B<units> or B<pages> or an abbreviation
-of one of these.
-If I<what> is B<units>, the view adjusts left or right by
-I<number> average-width characters on the display; if it is
-B<pages> then the view adjusts by I<number> screenfuls.
-If I<number> is negative then characters farther to the left
-become visible; if it is positive then characters farther to the right
-become visible.
-
-=back
-
-=item I<$text>-E<gt>B<yview>(I<?args>?)
-
-This command is used to query and change the vertical position of the
-text in the widget's window.
-It can take any of the following forms:
-
-=over 8
-
-=item I<$text>-E<gt>B<yview>
-
-Returns a list containing two elements, both of which are real fractions
-between 0 and 1.
-The first element gives the position of the first character in the
-top line in the window, relative to the text as a whole (0.5 means
-it is halfway through the text, for example).
-The second element gives the position of the character just after
-the last one in the bottom line of the window,
-relative to the text as a whole.
-These are the same values passed to scrollbars via the B<-yscrollcommand>
-option.
-
-=item I<$text>-E<gt>B<yviewMoveto>(I<fraction>)
-
-Adjusts the view in the window so that the character given by I<fraction>
-appears on the top line of the window.
-I<Fraction> is a fraction between 0 and 1; 0 indicates the first
-character in the text, 0.33 indicates the character one-third the
-way through the text, and so on.
-
-=item I<$text>-E<gt>B<yviewScroll>(I<number, what>)
-
-This command adjust the view in the window up or down according to
-I<number> and I<what>.
-I<Number> must be an integer.
-I<What> must be either B<units> or B<pages>.
-If I<what> is B<units>, the view adjusts up or down by
-I<number> lines on the display; if it is B<pages> then
-the view adjusts by I<number> screenfuls.
-If I<number> is negative then earlier positions in the text
-become visible; if it is positive then later positions in the text
-become visible.
-
-=item I<$text>->B<yview>(?B<-pickplace>,? I<index>)
-
-Changes the view in the I<$text>'s window to make I<index> visible.
-If the B<-pickplace> option isn't specified then I<index> will
-appear at the top of the window.
-If B<-pickplace> is specified then the widget chooses where
-I<index> appears in the window:
-
-=over 12
-
-=item [1]
-
-If I<index> is already visible somewhere in the window then the
-command does nothing.
-
-=item [2]
-
-If I<index> is only a few lines off-screen above the window then
-it will be positioned at the top of the window.
-
-=item [3]
-
-If I<index> is only a few lines off-screen below the window then
-it will be positioned at the bottom of the window.
-
-=item [4]
-
-Otherwise, I<index> will be centered in the window.
-
-=back
-
-=back
-
-=back
-
-The B<-pickplace> option has been obsoleted by the B<see> widget
-command (B<see> handles both x- and y-motion to make a location
-visible, whereas B<-pickplace> only handles motion in y).
-
-=over 4
-
-=item I<$text>-E<gt>B<yview>(I<number>)
-
-This command makes the first character on the line after
-the one given by I<number> visible at the top of the window.
-I<Number> must be an integer.
-This command used to be used for scrolling, but now it is obsolete.
-
-=back
-
-=head1 BINDINGS
-
-Tk automatically creates class bindings for texts that give them
-the following default behavior.
-In the descriptions below, ``word'' refers to a contiguous group
-of letters, digits, or ``_'' characters, or any single character
-other than these.
-
-=over 4
-
-=item [1]
-
-Clicking mouse button 1 positions the insertion cursor
-just before the character underneath the mouse cursor, sets the
-input focus to this widget, and clears any selection in the widget.
-Dragging with mouse button 1 strokes out a selection between
-the insertion cursor and the character under the mouse.
-
-=item [2]
-
-Double-clicking with mouse button 1 selects the word under the mouse
-and positions the insertion cursor at the beginning of the word.
-Dragging after a double click will stroke out a selection consisting
-of whole words.
-
-=item [3]
-
-Triple-clicking with mouse button 1 selects the line under the mouse
-and positions the insertion cursor at the beginning of the line.
-Dragging after a triple click will stroke out a selection consisting
-of whole lines.
-
-=item [4]
-
-The ends of the selection can be adjusted by dragging with mouse
-button 1 while the Shift key is down; this will adjust the end
-of the selection that was nearest to the mouse cursor when button
-1 was pressed.
-If the button is double-clicked before dragging then the selection
-will be adjusted in units of whole words; if it is triple-clicked
-then the selection will be adjusted in units of whole lines.
-
-=item [5]
-
-Clicking mouse button 1 with the Control key down will reposition the
-insertion cursor without affecting the selection.
-
-=item [6]
-
-If any normal printing characters are typed, they are
-inserted at the point of the insertion cursor.
-
-=item [7]
-
-The view in the widget can be adjusted by dragging with mouse button 2.
-If mouse button 2 is clicked without moving the mouse, the selection
-is copied into the text at the position of the mouse cursor.
-The Insert key also inserts the selection, but at the position of
-the insertion cursor.
-
-=item [8]
-
-If the mouse is dragged out of the widget
-while button 1 is pressed, the entry will automatically scroll to
-make more text visible (if there is more text off-screen on the side
-where the mouse left the window).
-
-=item [9]
-
-The Left and Right keys move the insertion cursor one character to the
-left or right; they also clear any selection in the text.
-If Left or Right is typed with the Shift key down, then the insertion
-cursor moves and the selection is extended to include the new character.
-Control-Left and Control-Right move the insertion cursor by words, and
-Control-Shift-Left and Control-Shift-Right move the insertion cursor
-by words and also extend the selection.
-Control-b and Control-f behave the same as Left and Right, respectively.
-Meta-b and Meta-f behave the same as Control-Left and Control-Right,
-respectively.
-
-=item [10]
-
-The Up and Down keys move the insertion cursor one line up or
-down and clear any selection in the text.
-If Up or Right is typed with the Shift key down, then the insertion
-cursor moves and the selection is extended to include the new character.
-Control-Up and Control-Down move the insertion cursor by paragraphs (groups
-of lines separated by blank lines), and
-Control-Shift-Up and Control-Shift-Down move the insertion cursor
-by paragraphs and also extend the selection.
-Control-p and Control-n behave the same as Up and Down, respectively.
-
-=item [11]
-
-The Next and Prior keys move the insertion cursor forward or backwards
-by one screenful and clear any selection in the text.
-If the Shift key is held down while Next or Prior is typed, then
-the selection is extended to include the new character.
-Control-v moves the view down one screenful without moving the
-insertion cursor or adjusting the selection.
-
-=item [12]
-
-Control-Next and Control-Prior scroll the view right or left by one page
-without moving the insertion cursor or affecting the selection.
-
-=item [13]
-
-Home and Control-a move the insertion cursor to the
-beginning of its line and clear any selection in the widget.
-Shift-Home moves the insertion cursor to the beginning of the line
-and also extends the selection to that point.
-
-=item [14]
-
-End and Control-e move the insertion cursor to the
-end of the line and clear any selection in the widget.
-Shift-End moves the cursor to the end of the line and extends the selection
-to that point.
-
-=item [15]
-
-Control-Home and Meta-E<lt> move the insertion cursor to the beginning of
-the text and clear any selection in the widget.
-Control-Shift-Home moves the insertion cursor to the beginning of the text
-and also extends the selection to that point.
-
-=item [16]
-
-Control-End and Meta-E<gt> move the insertion cursor to the end of the
-text and clear any selection in the widget.
-Control-Shift-End moves the cursor to the end of the text and extends
-the selection to that point.
-
-=item [17]
-
-The Select key and Control-Space set the selection anchor to the position
-of the insertion cursor. They don't affect the current selection.
-Shift-Select and Control-Shift-Space adjust the selection to the
-current position of the insertion cursor, selecting from the anchor
-to the insertion cursor if there was not any selection previously.
-
-=item [18]
-
-Control-/ selects the entire contents of the widget.
-
-=item [19]
-
-Control-\ clears any selection in the widget.
-
-=item [20]
-
-The F16 key (labelled Copy on many Sun workstations) or Meta-w
-copies the selection in the widget to the clipboard, if there is a selection.
-
-=item [21]
-
-The F20 key (labelled Cut on many Sun workstations) or Control-w
-copies the selection in the widget to the clipboard and deletes
-the selection.
-If there is no selection in the widget then these keys have no effect.
-
-=item [22]
-
-The F18 key (labelled Paste on many Sun workstations) or Control-y
-inserts the contents of the clipboard at the position of the
-insertion cursor.
-
-=item [23]
-
-The Delete key deletes the selection, if there is one in the widget.
-If there is no selection, it deletes the character to the right of
-the insertion cursor.
-
-=item [24]
-
-Backspace and Control-h delete the selection, if there is one
-in the widget.
-If there is no selection, they delete the character to the left of
-the insertion cursor.
-
-=item [25]
-
-Control-d deletes the character to the right of the insertion cursor.
-
-=item [26]
-
-Meta-d deletes the word to the right of the insertion cursor.
-
-=item [27]
-
-Control-k deletes from the insertion cursor to the end of its line;
-if the insertion cursor is already at the end of a line, then
-Control-k deletes the newline character.
-
-=item [28]
-
-Control-o opens a new line by inserting a newline character in
-front of the insertion cursor without moving the insertion cursor.
-
-=item [29]
-
-Meta-backspace and Meta-Delete delete the word to the left of the
-insertion cursor.
-
-=item [30]
-
-Control-x deletes whatever is selected in the text widget.
-
-=item [31]
-
-Control-t reverses the order of the two characters to the right of
-the insertion cursor.
-
-=item [32]
-
-Control-z (and Control-underscore on UNIX when tk_strictMotif is
-true) undoes the last edit action if the -undo option is true.
-Does nothing otherwise.
-
-=item [33]
-
-Control-Z (or Control-y on Windows) reapplies the last undone edit
-action if the -undo option is true. Does nothing otherwise.
-
-=back
-
-If the widget is disabled using the B<-state> option, then its
-view can still be adjusted and text can still be selected,
-but no insertion cursor will be displayed and no text modifications will
-take place.
-
-The behavior of texts can be changed by defining new bindings for
-individual widgets or by redefining the class bindings.
-
-
-=head1 TIED INTERFACE
-
-The Perl/Tk Text widget also has built-in TIEHANDLE methods for
-B<print> and B<printf> statements. This means you can print to file
-handles tied to a Text widget, and the tied methods automatically
-insert the print statement's arguments into the Text widget.
-
-For example:
-
- #!/usr/local/bin/perl -w
- use POSIX 'acos';
- use Tk;
- use strict;
-
- my $mw = MainWindow->new;
- my $text = $mw->Text(qw/-width 40 -height 10/)->pack;
-
- tie *STDOUT, ref $text, $text;
-
- print "Hello Text World!\n";
- printf "pi ~= %1.5f", acos(-1.0);
-
- MainLoop;
-
-To tie a scrolled Text widget, use the Subwidget method to get to the
-E<quot>realE<quot> widget:
-
- my $text = $mw->Scrolled('Text')->pack;
- tie *STDOUT, 'Tk::Text', $text->Subwidget('scrolled');
-
-=head1 PERFORMANCE ISSUES
-
-Text widgets should run efficiently under a variety
-of conditions. The text widget uses about 2-3 bytes of
-main memory for each byte of text, so texts containing a megabyte
-or more should be practical on most workstations.
-Text is represented internally with a modified B-tree structure
-that makes operations relatively efficient even with large texts.
-Tags are included in the B-tree structure in a way that allows
-tags to span large ranges or have many disjoint smaller ranges
-without loss of efficiency.
-Marks are also implemented in a way that allows large numbers of
-marks.
-In most cases it is fine to have large numbers of unique tags,
-or a tag that has many distinct ranges.
-
-One performance problem can arise if you have hundreds or thousands
-of different tags that all have the following characteristics:
-the first and last ranges of each tag are near the beginning and
-end of the text, respectively,
-or a single tag range covers most of the text widget.
-The cost of adding and deleting tags like this is proportional
-to the number of other tags with the same properties.
-In contrast, there is no problem with having thousands of distinct
-tags if their overall ranges are localized and spread uniformly throughout
-the text.
-
-Very long text lines can be expensive,
-especially if they have many marks and tags within them.
-
-The display line with the insert cursor is redrawn each time the
-cursor blinks, which causes a steady stream of graphics traffic.
-Set the B<-insertofftime> option to 0 avoid this.
-
-=head1 SEE ALSO
-
-L<Tk::ROText|Tk::ROText>
-L<Tk::TextUndo|Tk::TextUndo>
-
-=head1 KEYWORDS
-
-text, widget
-
-=cut
-
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/TextUndo.pod b/Master/tlpkg/tlperl/lib/Tk/TextUndo.pod
deleted file mode 100644
index 2b9d98a3c4a..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/TextUndo.pod
+++ /dev/null
@@ -1,73 +0,0 @@
-
-=head1 NAME
-
-Tk::TextUndo - perl/tk text widget with bindings to undo changes.
-
-=for pm Tk/TextUndo.pm
-
-=for category Derived Widgets
-
-=head1 SYNOPSIS
-
-S< >B<use Tk::TextUndo;>
-
-S< >I<$testundo> = I<$parent>-E<gt>B<TextUndo>(?I<-option>=E<gt>I<value>, ...?);
-
-=head1 DESCRIPTION
-
-This IS-A text widget with an unlimited 'undo' history but without
-a re'undo' capability.
-
-=head2 Bindings
-
-The C<TextUndo> widget has the same bindings as the L<Text|Tk::Text> widget.
-In addition there are the following bindings:
-
-=over 4
-
-=item Event <L4> <<Undo>>
-
-undo the last change. Pressing <L4> several times undo
-step by step the changes made to the text widget.
-
-=back
-
-=head2 Methods
-
-The C<TextUndo> widget has the same methods as C<Text> widget.
-Additional methods for the C<TextUndo> widget are:
-
-=over 4
-
-=item $text->Load($filename);
-
-Loads the contents of the $filename into the text widget. Load()
-delete the previous contents of the text widget as well as it's
-undo history of the previous file.
-
-=item $text->Save(?$otherfilename?)
-
-Save contents of the text widget to a file. If the
-$otherfilename is not specified, the text widget contents
-writes the file of $filename used in the last Load()
-call. If no file was previously Load()'ed an error message
-pops up. The default filename of the last Load() call
-is not overwriten by $otherfilename.
-
-=item $text->FileName(?$otherfilename?)
-
-If passed an argument sets the file name associated with the loaded
-document. Returns the current file name associated with the document.
-
-=back
-
-=head1 KEYS
-
-widget, text, undo
-
-=head1 SEE ALSO
-
-L<Tk::Text>, L<Tk::ROText>
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Tiler.pod b/Master/tlpkg/tlperl/lib/Tk/Tiler.pod
deleted file mode 100644
index 2db172ebaf1..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Tiler.pod
+++ /dev/null
@@ -1,32 +0,0 @@
-
-=head1 NAME
-
-Tk::Tiler - Scrollable frame with sub-widgets arranged into rows
-
-=for pm Tk/Tiler.pm
-
-=for category Tk Geometry Management
-
-=head1 SYNOPSIS
-
- use Tk::Tiler;
-
- my $tl = $parent->Scrolled('Tiler', -columns => n, -rows => n);
-
- my $a = $tl->Xxxxx(...);
- my $b = $tl->Xxxxx(...);
- my $c = $tl->Xxxxx(...);
-
- $tl->Manage($a,$b,$c);
-
-=head1 DESCRIPTION
-
-Tiler is derived form Tk::Frame. It is a geometry managing widget which
-accepts widgets to manage. It places the widgets in a grid with as many
-widgets as possible in a row. All the "slots" in the grid are the same size,
-which is determined by the largest managed widget.
-
-The grid may be scrolled vertically.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/TixGrid.pod b/Master/tlpkg/tlperl/lib/Tk/TixGrid.pod
deleted file mode 100644
index 93484db0076..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/TixGrid.pod
+++ /dev/null
@@ -1,539 +0,0 @@
-# Copyright (c) 1996, Expert Interface Technologies
-# See the file "license.terms" for information on usage and
-# redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-# The file man.macros and some of the macros used by this file are
-# copyrighted: (c) 1990 The Regents of the University of California.
-# (c) 1994-1995 Sun Microsystems, Inc.
-# The license terms of the Tcl/Tk distribution are in the file
-# license.tcl.
-
-## TO CHECK:
-##
-## callback: checked for defined of code ref (compare -edit*cmd)
-##
-## option
-## formatcmd mentions format method but there is no format
-## method documented
-##
-## methods:
-## bdtype: what is it? no description given
-## see: not documented? Not implemented??
-##
-## todo: missing peaces marked by ????
-
-=head1 NAME
-
-Tk::TixGrid - Create and manipulate Tix Grid widgets
-
-=for pm TixGrid/TixGrid.pm
-
-=for category Tix Extensions
-
-=head1 SYNOPSIS
-
-S< >I<$tixgrid> = I<$parent>->B<TixGrid>?(I<options>)?;
-
-=head1 DESCRIPTION
-
-This widget is intended as the basis of "spread sheet" like interfaces.
-The widget displays its contents in a two dimensional "grid" of cells.
-Each cell may contain one Tix display item, which may be in text,
-graphics or other formats. See L<Tk::DItem> for more information
-about Tix display items. Because these "items" need not be "windows" large
-grids can be handled without consuming excessive display system resources.
-
-Individual cells, or groups of cells, can be formatted with a wide range of
-attributes, such as its color, relief and border. However because the
-widget is intended to handle large grids the mechanisms to achieve these
-are lower level, and more callback oriented than for other widgets. The
-assumption is that to avoid storing display details of a large number
-of cells, the data will be re-computed as needed.
-
-The port of Tix C code and some of the bindings to perl/Tk is done but still
-need further work. In several places the intent of the Tix code is not
-yet understood. For example the 'edit' interface is clearly intended
-for spread-sheet like cell content editing in an auxillary "entry" widget
-or similar, but how that should work is not yet clear.
-
-The B<TixGrid> method creates a new TixGrid window and returns a
-blessed reference of this TixGrid widget. Additional options,
-described below, may be specified on the command line or in the
-option database to configure aspects of the B<TixGrid> widget.
-
-=head1 STANDARD OPTIONS
-
-B<-background>
- B<-borderwidth>
- B<-cursor>
- B<-font>
- B<-foreground>
- B<-height>
- B<-highlightbackground>
- B<-highlightcolor>
- B<-highlightthickness>
- B<-padx>
- B<-pady>
- B<-relief>
- B<-selectbackground>
- B<-selectborderwidth>
- B<-selectforeground>
- B<-state>
- B<-takefocus>
- B<-width>
- B<-xscrollcommand>
- B<-yscrollcommand>
-
-See L<Tk::options> for details of the standard options.
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<browseCmd>
-
-=item Class: B<BrowseCmd>
-
-=item Switch: B<-browsecmd>
-
-If defined, gives a perl/Tk L<callback|Tk::callbacks> to be executed when the
-user browses a grid cell (This is normally the case when the user clicks on an
-entry). When this callback is called, it is passed with two additional
-parameters: I<x> I<y>, where (I<x>,I<y>) is the location of the cell that has
-just been clicked.
-
-=item Name: B<Command>
-
-=item Class: B<Command>
-
-=item Switch: B<-command>
-
-If defined, gives a perl/Tk L<callback|Tk::callbacks> to be executed when the
-user double-clicks a grid cell. When this callback is called, it is passed
-with two additional parameters: I<x> I<y>, where (I<x>,I<y>) is the location of
-the cell that has just been clicked.
-
-=item Name: B<editDoneCmd>
-
-=item Class: B<EditDoneCmd>
-
-=item Switch: B<-editdonecmd>
-
-If defined, gives a perl/Tk L<callback|Tk::callbacks>
-to be executed when the
-user has edited grid cell. When this callback is called, it is
-passed with two additional parameters: I<x> I<y>, where (I<x>,I<y>)
-is the location of the cell that has just been edited.
-
-=item Name: B<editNotifyCmd>
-
-=item Class: B<EditNotifyCmd>
-
-=item Switch: B<-editnotifycmd>
-
-If defined gives a perl/Tk L<callback|Tk::callbacks>
-to be executed when the user tries to edit a grid cell.
-When this callback is called, it is passed with two additional
-parameters: I<x> I<y>, where (I<x>,I<y>,) is the location
-of the cell. This callback should return a boolean value: B<true>
-indicates that the cell is editable and B<false> otherwise.
-
-=item Name: B<FloatingCols>
-
-=item Class: B<floatingCols>
-
-=item Switch: B<-floatingcols>
-
-Defines the number of extra columns beyond the existing grid
-that can be brought into view by scrolling.
-
-=item Name: B<FloatingRows>
-
-=item Class: B<floatingRows>
-
-=item Switch: B<-floatingrows>
-
-Defines the number of extra rows beyond the the existing grid
-that can be brought into view by scrolling.
-
-=item Name: B<formatCmd>
-
-=item Class: B<FormatCmd>
-
-=item Switch: B<-formatcmd>
-
-If defined, gives a perl/Tk L<callback|Tk::callbacks> to be
-executed when the grid cells need to be displayed on the screen.
-Its primary purpose is to draw the background of the region
-before the cells are rendered on top. This is normally
-achieved by calling B<formatGrid> or B<formatBorder> (see below).
-However other uses can be made of this low-level callback. For example it can be used
-to "lazily" populate the grid by calling the B<set> method only as cells come
-into view.
-
-When this callback is called, it is passed with five additional
-parameters: I<type> I<x1> I<y1> I<x2> I<y2>.
-
-I<x1> I<y1> I<x2> I<y2> gives the extent of the region that needs
-formatting.
-
-I<type> gives the logical type of the region in the grid. It may be one of the
-following.
-
-=over 8
-
-=item B<x_margin>
-
-The horizontal margin.
-
-=item B<y_margin>
-
-The vertical margin.
-
-=item B<s_margin>
-
-The area in the top left corner where the horizontal and vertical margins
-are joined.
-
-=item B<main>
-
-The main body i.e. all the cells that do not fall into the above three types.
-
-=back
-
-=item Name: B<leftMargin>
-
-=item Class: B<LeftMargin>
-
-=item Switch: B<-leftmargin>
-
-Gives the width of vertical margin in cells (columns).
-A zero indicates that no vertical margin exists. A positive value I<N>
-indicates that first I<N> columns are "labels" and are always displayed
-and not scrolled.
-
-=item Name: B<itemType>
-
-=item Class: B<ItemType>
-
-=item Switch: B<-itemtype>
-
-Default item type for cells.
-
-=item Name: B<selectMode>
-
-=item Class: B<SelectMode>
-
-=item Switch: B<-selectmode>
-
-Specifies one of several styles for manipulating the selection.
-The value of the option may be arbitrary, but the default bindings
-expect it to be either B<single>, B<browse>, B<multiple>, or B<extended>;
-the default value is B<single>.
-
-=item Name: B<selectUnit>
-
-=item Class: B<SelectUnit>
-
-=item Switch: B<-selectunit>
-
-Specifies the selection unit. Valid values are B<cell>, B<column> or B<row>.
-
-=item Name: B<sizeCmd>
-
-=item Class: B<SizeCmd>
-
-=item Switch: B<-sizecmd>
-
-Callback is called (with no extra arguments) when grid sizes are
-re-computed. For example if window changes size, a different font
-is specified etc.
-
-It is called just after scrollbars (if present) are updated.
-
-=item Name: B<topMargin>
-
-=item Class: B<TopMargin>
-
-=item Switch: B<-topmargin>
-
-Gives the width of horizontal margin in cells (rows).
-A zero indicates that no horizontal margin exists. A positive value
-I<N> indicates that first I<N> rows are "labels" and are always
-displayed and not scrolled.
-
-=back
-
-=head1 WIDGET METHODS
-
-The B<TixGrid> method creates a TixGrid widget and returns a blessed
-reference of this TixGrid widget. This reference may be used to
-invoke various operations on the widget. It has the following general
-form:
-
-S< >I<$tixgrid>->B<method>?(I<arg, arg, ...>)?
-
-I<arg>s determine the exact behavior of the method.
-
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-The following additional methods are possible for B<TixGrid> widgets:
-
-=over 4
-
-=item I<$tixgrid>->B<anchorGet>(I<x>, I<y>)
-
-=item I<$tixgrid>->B<anchorSet>(I<x>, I<y>)
-
-=item I<$tixgrid>->B<anchorClear>
-
-Manipulates the B<anchor cell> of the B<TixGrid> widget.
-The anchor cell is the end of the selection that is fixed
-while the user is dragging out a selection with the mouse.
-
-=item ($bd,$col,$row) = I<$tixgrid>->B<bdtype>(I<x,y> ?,I<xDelta>,I<yDelta>?)
-
-Determines if the the screen (pixel) position I<x,y> is in a border.
-This is useful for changing the mouse cursor when the user points at a
-border - e.g. to indicate that the border can be adjusted
-interactively.
-
-If in a border returns a list of three elements. First element
-is 'xy', 'x' or 'y', second two elements are integers.
-(Value of these are not understood, seem to indicate which
-column and row of the border the screen position corresponds to?)
-
-If not in a border returns an empty list.
-
-=item I<$tixgrid>->B<delete>(I<dim>, I<from>?, I<to>?)
-
-=item I<$tixgrid>->B<deleteColumn>(I<from>?, I<to>?)
-
-=item I<$tixgrid>->B<deleteRow>(I<from>?, I<to>?)
-
-I<Dim> may be B<row> or B<column>. If I<to> is not given,
-deletes a single row (or column) at the position I<from>.
-If I<to> is given, deletes the range of rows (or columns)
-from position I<from> through I<to>.
-
-=item I<$tixgrid>->B<dragsite>(I<option>, I<x>, I<y>)
-
-=item I<$tixgrid>->B<dropsite>(I<option>, I<x>, I<y>)
-
-Tcl/Tix has (or was going to have) Drag&Drop support.
-Meaning for perl/Tk is not clear yet.
-
-=item I<$tixgrid>->B<editApply>
-
-If any cell is being edited, de-highlight the cell and
-applies the changes.
-
-=item I<$tixgrid>->B<editSet>(I<x>, I<y>)
-
-Highlights the cell at (I<x>,I<y>) for editing,
-if the B<-editnotify> callback returns true for this cell.
-
-=item I<$tixgrid>->B<entrycget>(I<x>, I<y>, 'I<-option>')
-
-=item I<$tixgrid>->B<entryconfigure>(I<x>, I<y>?, I<-option>??=>I<value>, I<-option>=>I<value>, I<...>?)
-
-Provide a configue interface to cells in the grid.
-The I<-option>s depend on the item type of the cell.
-
-=item I<$tixgrid>->B<formatBorder>(I<x1,y1>, I<x2,y2>, I<options>);
-
-=item I<$tixgrid>->B<formatGrid>(I<x1,y1>, I<x2,y2>, I<options>);
-
-The B<formatBorder> and B<formatBorder> methods can only be called by the
-B<-formatcmd> callback of the tixGrid widget. They draw the background of
-the region described by I<x1,y1>, I<x2,y2> according the the supplied
-I<options>. One call to B<-formatcmd> callback can make multiple
-calls to B<formatBorder> and/or B<formatBorder> for different
-sub-regions.
-
-B<formatBorder> draws the background using Tk relief style,
-B<formatGrid> also draws grid lines between the cells.
-It only makes sense to call one or the other for a particular
-sub-region as one will over-write the other.
-
-The options allowed are:
-
-=over 8
-
-=item -background / -bg
-
-=item -borderwidth / -bd
-
-=item -filled
-
-=item -relief
-
-=item -selectbackground
-
-=item -xoff
-
-=item -xon
-
-=item -yoff
-
-=item -yon
-
-=back
-
-The B<-xon/-xoff and -yon/-yoff> options are obscure. If anyone
-can figure out how to do something interesting given what
-F<pTk/tixGrFmt.c> is doing with them please let Nick know!.
-
-=item I<$tixgrid>->B<geometryinfo>(?I<width>, I<height>?)
-
-Returns list of four values - two sets of two floating point numbers.
-First set is the scrollbar fractions for x direction, second set
-is scrollbar fractions for y direction. If I<width> and I<height>
-are specified then fractions are based on as if window size was of
-specified size (in pixels, but not allowing normal GetPixels units).
-Otherwise fractions are based on current size of the window.
-
-Usage obscure.
-
-=item I<$tixgrid>->B<index>(I<xcoord>, I<ycoord>)
-
-Retuns I<(x, y)> of entry at position (I<$coordx>, I<$coordy>).
-Either coordinate may be B<'max'> which is largest existing entry
-in that direction, B<'end'> which is one I<beyond> largest existing
-entry, or a number. (This is how you find out how big the grid is.)
-
-=item I<$tixgrid>->B<infoBbox>(I<x>,I<y>)
-
-Return the pixel bounding box of the cell at I<x,y>.
-
-=item I<$tixgrid>->B<infoExists>(I<x>,I<y>)
-
-Returns true if there is an item in the cell at I<x,y>.
-Throws an exception (dies) if I<x,y> is outside the
-grid - this may change (Nick doesn't like it).
-
-=item I<$tixgrid>->B<move>(I<dim>, I<from>, I<to>, I<offset>)
-
-=item I<$tixgrid>->B<moveColumn>(I<from>, I<to>, I<offset>)
-
-=item I<$tixgrid>->B<moveRow>(I<from>, I<to>, I<offset>)
-
-I<Dim> may be B<row> or B<column>. Moves the range of rows
-(or columns) from position I<from> through I<to> by the distance
-indicated by I<offset>. For example,
-I<$tixgrid>->B<moveRow>(B<2>, B<4>, B<1>) moves the rows 2,3,4
-to rows 3,4,5.
-
-=item I<$tixgrid>->B<nearest>(I<x>, I<y>)
-
-Screen pos (pixels) to entry (nx,ny) translation.
-
-=item I<$tixgrid>->B<selectionAdjust>(I<x1>, I<y1> ?,I<x2>, I<y2>?)
-
-=item I<$tixgrid>->B<selectionClear>(I<x1>, I<y1> ?,I<x2>, I<y2>?)
-
-=item I<$tixgrid>->B<selectionIncludes>(I<x1>, I<y1> ?,I<x2>, I<y2>?)
-
-=item I<$tixgrid>->B<selectionSet>(I<x1>, I<y1> ?,I<x2>, I<y2>?)
-
-=item I<$tixgrid>->B<selectionToggle>(I<x1>, I<y1> ?,I<x2>, I<y2>?)
-
-Selection support methods - probably buggy.
-
-x1 (y1) has not to be greater than x2 (y2), but only x2 and y2 can be 'max'.
-
-BUG: I<selectionIncludes>: has no visible effect (as in Tix). Eh???
-
-BUG: I<selectionClear>: only works for 0, 0, max, max (as in Tix). Eh???
-
-When I<x2, y2> are not given they default to I<x1, y1>, respectively.
-
-=item I<$tixgrid>->B<set>(I<x>, I<y>?, B<-itemtype>=>I<type>??, I<-option>=>I<value>, I<...>?)
-
-Creates a new display item at the cell at (I<x>,I<y>). The optional
-B<-itemtype> parameter gives the type of the display item.
-An additional list of I<option-value> pairs specify options
-of the display item. If a display item already exists at this cell,
-the old item will be deleted automatically.
-
-=item I<$tixgrid>->B<size>(I<dim>, I<index>?, I<-option>??=>I<value>, I<...>?)
-
-=item I<$tixgrid>->B<sizeColumn>(I<index>?, I<-option>??=>I<value>, I<...>?)
-
-=item I<$tixgrid>->B<sizeRow>(I<index>?, I<-option>??=>I<value>, I<...>?)
-
-Queries or sets the size of the row or column given by I<dim> and
-I<index>. I<Dim> may be B<row> or B<column>. I<Index> may be any
-non-negative integer that gives the position of a given row (or column).
-I<Index> can also be the string B<default>; in this case, this method
-queries or sets the default size of all rows (or columns).
-When no I<option-value> pair is given, this method returns
-a list containing the current size setting of the given row (or column).
-When I<option-value> pairs are given, the corresponding options
-of the size setting of the given row are changed. I<-option> may be
-one of the following:
-
-=over 8
-
-=item B<-pad0> => I<pixels>
-
-Specifies the paddings to the left of a column or the top of a row.
-
-=item B<-pad1> => I<pixels>
-
-Specifies the paddings to the right of a column or the bottom of a row.
-
-=item B<-size> => I<val>
-
-Specifies the width of a column or the height of a row.
-I<Val> may be: B<auto> -- the width of the column is set
-the widest cell in the column; a valid Tk screen distance
-unit (see B<Tk_GetPixels>); or a real number following by the
-word B<chars> (e.g. B<3.4chars>) that sets the width of the
-column to the given number of characters.
-
-=back
-
-=item I<$tixgrid>->B<sort>(I<dimension>, I<start>, I<end>, ?I<args ...>?)
-
-?docu here? (not supported on Win* OSs up to now)
-
-=item I<$tixgrid>->B<unset>(I<x>, I<y>)
-
-Clears the cell at (I<x>,I<y>) by removing its display item.
-
-=item I<$tixgrid>->B<xview>
-
-Normal horizontal scrollbar method.
-
-=item I<$tixgrid>->B<yview>
-
-Normal vertical scrollbar method.
-
-=back
-
-=head1 BINDINGS
-
-To be done - only most obvious basic bindings work. The Tcl/Tix code
-was coded as a "state machine" which is not easy to follow.
-
-=head1 SEE ALSO
-
-L<Tk::DItem|Tk::DItem>
-L<Tk::callbacks|Tk::callbacks>
-L<Tk::FloatEntry|Tk::FloatEntry>
-
-=head1 BUGS
-
-Tcl/Tix was/is not finished and both C code and bindings of TixGrid
-have some bugs.
-
-=head1 KEYWORDS
-
-tix, tixgrid, table, display item, spreadsheet
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Toplevel.pod b/Master/tlpkg/tlperl/lib/Tk/Toplevel.pod
deleted file mode 100644
index e3bbf579c0b..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Toplevel.pod
+++ /dev/null
@@ -1,199 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Toplevel - Create and manipulate Toplevel widgets
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
-S< >I<$toplevel> = I<$parent>-E<gt>B<Toplevel>(?I<options>?);
-
-=head1 STANDARD OPTIONS
-
-B<-borderwidth> B<-highlightbackground> B<-highlightthickness> B<-takefocus>
-B<-class> B<-highlightcolor> B<-relief>
-B<-cursor>
-
-See L<Tk::options> for details of the standard options.
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<background>
-
-=item Class: B<Background>
-
-=item Switch: B<-background>
-
-This option is the same as the standard B<background> option
-except that its value may also be specified as an undefined value.
-In this case, the widget will display no background or border, and
-no colors will be consumed from its colormap for its background
-and border.
-
-=item Name: B<colormap>
-
-=item Class: B<Colormap>
-
-=item Switch: B<-colormap>
-
-Specifies a colormap to use for the window.
-The value may be either B<new>, in which case a new colormap is
-created for the window and its children, or the name of another
-window (which must be on the same screen and have the same visual
-as $widget), in which case the new window will use the colormap
-from the specified window.
-If the B<colormap> option is not specified, the new window
-uses the default colormap of its screen.
-This option may not be changed with the B<configure>
-method.
-
-=item Name: B<container>
-
-=item Class: B<Container>
-
-=item Switch: B<-container>
-
-The value must be a boolean. If true, it means that this window will
-be used as a container in which some other application will be embedded
-(for example, a Tk toplevel can be embedded using the B<-use> option).
-The window will support the appropriate window manager protocols for
-things like geometry requests. The window should not have any
-children of its own in this application.
-This option may not be changed with the B<configure>
-method.
-
-=item Name: B<height>
-
-=item Class: B<Height>
-
-=item Switch: B<-height>
-
-Specifies the desired height for the window in any of the forms
-acceptable to B<Tk_GetPixels>.
-If this option is less than or equal to zero then the window will
-not request any size at all.
-
-=item Name: B<menu>
-
-=item Class: B<Menu>
-
-=item Switch: B<-menu>
-
-Specifies a menu widget to be used as a menubar. On the Macintosh, the
-menubar will be displayed accross the top of the main monitor. On
-Microsoft Windows and all UNIX platforms, the menu will appear accross
-the toplevel window as part of the window dressing maintained by the
-window manager.
-
-=item Name: B<"">
-
-=item Class: B<"">
-
-=item Switch: B<-screen>
-
-Specifies the screen on which to place the new window.
-Any valid screen name may be used, even one associated with a
-different display.
-Defaults to the same screen as its parent.
-This option is special in that it may not be specified via the option
-database, and it may not be modified with the B<configure>
-method.
-
-=item Switch: B<-title>
-
-Specifies the title of the toplevel window.
-
-=item Name: B<use>
-
-=item Class: B<Use>
-
-=item Switch: B<-use>
-
-This option is used for embedding. If the value isn't an empty string,
-it must be the the window identifier of a container window, specified as
-a hexadecimal string like the ones returned by the B<winfo id>
-command. The toplevel widget will be created as a child of the given
-container instead of the root window for the screen. If the container
-window is in a Tk application, it must be a frame or toplevel widget for
-which the B<-container> option was specified.
-This option may not be changed with the B<configure>
-method.
-
-=item Name: B<visual>
-
-=item Class: B<Visual>
-
-=item Switch: B<-visual>
-
-Specifies visual information for the new window in any of the
-forms accepted by B<Tk_GetVisual>.
-If this option is not specified, the new window will use the default
-visual for its screen.
-The B<visual> option may not be modified with the B<configure>
-method.
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-=item Switch: B<-width>
-
-Specifies the desired width for the window in any of the forms
-acceptable to B<Tk_GetPixels>.
-If this option is less than or equal to zero then the window will
-not request any size at all.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Toplevel> method creates a new toplevel widget (given
-by the $widget argument). Additional
-options, described above, may be specified on the command line
-or in the option database
-to configure aspects of the toplevel such as its background color
-and relief. The B<toplevel> command returns the
-path name of the new window.
-
-A toplevel is similar to a frame except that it is created as a
-top-level window: its X parent is the root window of a screen
-rather than the logical parent from its path name. The primary
-purpose of a toplevel is to serve as a container for dialog boxes
-and other collections of widgets. The only visible features
-of a toplevel are its background color and an optional 3-D border
-to make the toplevel appear raised or sunken.
-
-=head1 WIDGET METHODS
-
-The B<Toplevel> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class, and the L<Tk::Wm|Tk::Wm> class.
-
-=head1 BINDINGS
-
-When a new toplevel is created, it has no default event bindings:
-toplevels are not intended to be interactive.
-
-=head1 SEE ALSO
-
-L<Tk::Widget|Tk::Widget>
-L<Tk::Wm|Tk::Wm>
-
-=head1 KEYWORDS
-
-toplevel, widget
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Tree.pod b/Master/tlpkg/tlperl/lib/Tk/Tree.pod
deleted file mode 100644
index 445d2f0765b..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Tree.pod
+++ /dev/null
@@ -1,274 +0,0 @@
-
-=head1 NAME
-
-Tk::Tree - Create and manipulate Tree widgets
-
-=for pm Tixish/Tree.pm
-
-=for category Tix Extensions
-
-=head1 SYNOPSIS
-
-S< >B<use Tk::Tree;>
-
-S< >I<$tree> = I<$parent>-E<gt>B<Tree>(?I<options>?);
-
-=head1 SUPER-CLASS
-
-The B<Tree> class is derived from the L<HList|Tk::HList> class and inherits all
-the methods, options and subwidgets of its super-class. A B<Tree> widget is
-not scrolled by default.
-
-=head1 STANDARD OPTIONS
-
-B<Tree> supports all the standard options of an HList widget.
-See L<Tk::options> for details on the standard options.
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<browseCmd>
-
-=item Class: B<BrowseCmd>
-
-=item Switch: B<-browsecmd>
-
-Specifies a L<callback|Tk::callbacks> to call whenever the user browses on an entry
-(usually by single-clicking on the entry). The callback is called with
-one argument, the pathname of the entry.
-
-=item Name: B<closeCmd>
-
-=item Class: B<CloseCmd>
-
-=item Switch: B<-closecmd>
-
-Specifies a L<callback|Tk::callbacks> to call whenever an entry needs to be closed (See
-L<"BINDINGS"> below). This method is called with one argument,
-the pathname of the entry. This method should perform appropriate
-actions to close the specified entry. If the B<-closecmd> option
-is not specified, the default closing action is to hide all child
-entries of the specified entry.
-
-=item Name: B<command>
-
-=item Class: B<Command>
-
-=item Switch: B<-command>
-
-Specifies a L<callback|Tk::callbacks> to call whenever the user activates an entry
-(usually by double-clicking on the entry). The callback
-is called with one argument, the pathname of the entry.
-
-=item Name: B<ignoreInvoke>
-
-=item Class: B<IgnoreInvoke>
-
-=item Switch: B<-ignoreinvoke>
-
-A Boolean value that specifies when a branch should be opened or
-closed. A branch will always be opened or closed when the user presses
-the (+) and (-) indicators. However, when the user invokes a branch
-(by doublc-clicking or pressing E<lt>ReturnE<gt>), the branch will be opened
-or closed only if B<-ignoreinvoke> is set to false (the default
-setting).
-
-=item Name: B<openCmd>
-
-=item Class: B<OpenCmd>
-
-=item Switch: B<-opencmd>
-
-Specifies a L<callback|Tk::callbacks> to call whenever an entry needs to be opened (See
-L<"BINDINGS"> below). This method is called with one argument,
-the pathname of the entry. This method should perform appropriate
-actions to open the specified entry. If the B<-opencmd> option
-is not specified, the default opening action is to show all the child
-entries of the specified entry.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Tree> method creates a new window and makes it into a Tree widget
-and return a reference to it. Additional options, described above, may
-be specified on the command line or in the option database to configure
-aspects of the Tree widget such as its cursor and relief.
-
-The Tree widget can be used to display hierarchical data in a tree
-form. The user can adjust the view of the tree by opening or closing
-parts of the tree.
-
-To display a static tree structure, you can add the entries into the
-Tree widget and hide any entries as desired. Then you can call
-the B<autosetmode> method. This will set up the Tree widget so that it
-handles all the I<open> and I<close> events automatically.
-the demonstration program F<Tixish/examples/perl-tix-tree>).
-
-The above method is not applicable if you want to maintain a dynamic tree
-structure, i.e, you do not know all the entries in the tree and you need
-to add or delete entries subsequently. To do this, you should first create
-the entries in the Tree widget. Then, use the B<setmode> method to
-indicate the entries that can be opened or closed, and use the B<-opencmd>
-and B<-closecmd> options to handle the opening and closing events. (Please
-see the demonstration program F<Tixish/examples/perl-tix-dyntree>).
-
-Use either
-
-S< >I<$parent>-E<gt>B<Scrolled>(B<'Tree'>, ... );
-
-or
-
-S< >I<$parent>-E<gt>B<ScrlTree>( ... );
-
-to create a scrolled B<Tree>. See L<Tk::Scrolled> for details.
-
-=head1 WIDGET METHODS
-
-The B<Tree> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-The following additional methods are available for Tree widgets:
-
-=over 4
-
-=item I<$tree-E<gt>>B<add_pathimage>(I<treeRegExp [, openImg, closeImg]>)
-
-This method defines images for a given path (images must be in xpm
-format). The path can be determined by a simplified regular
-expression. There are just three metasymbols:
-
-=over
-
-=item ^
-
-at the beginning of the C<treeRegExp> same as in Perl regular
-expressions
-
-=item *
-
-anything
-
-=item $
-
-at the end of the C<TreeRegExp>, the same as in Perl regular
-expressions
-
-=back
-
-Examples:
-
- $tree->add_pathimage('^root','openfolder','folder');
-
-matches C<root>, C<root.foo>, C<root.bar>, but not C<foo.root>
-
- $tree->add_pathimage('root.*.class','openfolder','folder');
-
-matches all paths containing C<< root.<anything>.class >>, but not
-C<< root.<anything>.<anything>.class >> C<*> is one part of the path. If
-you want to use a wildcard for two steps, you have to use C<*.*>.
-
- $tree->add_pathimage('class$','openfolder','folder');
-
-This matches all path with C<class> at the end.
-
-=item I<$tree>-E<gt>B<autosetmode>
-
-This method calls the B<setmode> method for all the entries in
-this Tree widget: if an entry has no child entries, its mode is set to
-B<none>. Otherwise, if the entry has any hidden child entries, its
-mode is set to B<open>; otherwise its mode is set to B<close>.
-
-=item I<$tree-E<gt>>B<child_entries>([$path][,$depth])
-
-This method returns in list context an array that contains all
-pathnames of subentries within the given path. In scalar context it
-returns the number of subentries in the given path.
-
- Example:
- root
- | foo
- | bar
- | | bar1
- | | bar2
-
- my @childentries = $tree->child_entries('root.bar');
- # returns (root.bar.bar1, root.bar.bar2)
-
- my $nr_of_subentries = $tree->child_entries('root',2);
- # returns 4
-
-If C<$path> is omitted, all it is assumed, that the entry above
-'root' is meant. C<$depth> defines the numbers of levels.
-
-=item I<$tree>-E<gt>B<close>(I<entryPath>)
-
-Close the entry given by I<entryPath> if its I<mode> is B<close>.
-
-=item I<$tree>-E<gt>B<getmode>(I<entryPath>)
-
-Returns the current I<mode> of the entry given by I<entryPath>.
-
-=item I<$tree>-E<gt>B<open>(I<entryPath>)
-
-Open the entry given by I<entryPath> if its I<mode> is B<open>.
-
-=item I<$tree>-E<gt>B<setmode>(I<entryPath, mode>)
-
-This method is used to indicate whether the entry given by
-I<entryPath> has children entries and whether the children are
-visible. I<mode> must be one of B<open>,
-B<close> or B<none>. If I<mode> is set to B<open>, a (+)
-indicator is drawn next to the entry. If I<mode> is set to
-B<close>, a (-) indicator is drawn next to the entry. If
-I<mode> is set to B<none>, no indicators will be drawn for this
-entry. The default I<mode> is none. The B<open> mode indicates
-the entry has hidden children and this entry can be opened by the
-user. The B<close> mode indicates that all the children of the entry
-are now visible and the entry can be closed by the user.
-
-=back
-
-=head1 BINDINGS
-
-The basic mouse and keyboard bindings of the Tree widget are the same
-as the L<bindings of the HList|Tk::HList/"BINDINGS"> widget.
-In addition, the entries can be opened or closed under the following
-conditions:
-
-=over 4
-
-=item [1]
-
-If the I<mode> of the entry is B<open>, it can be opened by clicking
-on its (+) indicator.
-
-=item [2]
-
-If the I<mode> of the entry is B<close>, it can be closed by clicking
-on its (-) indicator.
-
-=back
-
-=head1 SEE ALSO
-
-L<Tk::HList|Tk::HList>
-
-=head1 AUTHOR
-
-Perl/TK version by Chris Dean <ctdean@cogit.com>. Original Tcl/Tix
-version by Ioi Kim Lam.
-
-Additions by Renee Baecker <module@renee-baecker.de>
-
-=head1 ACKNOWLEDGEMENTS
-
-Thanks to Achim Bohnet <ach@mpe.mpg.de> for all his help.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/UserGuide.pod b/Master/tlpkg/tlperl/lib/Tk/UserGuide.pod
deleted file mode 100644
index 08d397d4db7..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/UserGuide.pod
+++ /dev/null
@@ -1,586 +0,0 @@
-=head1 NAME
-
-Perl/Tk - Writing Tk applications in Perl 5
-
-=for category Introduction
-
-=head1 DESCRIPTION
-
-This document is for beginners. It assumes you know some B<Perl>, and
-have it and Tk running. If you are I<not> currently reading this
-document courtesy of the B<widget> demonstration program, please be
-sure to run B<widget>, as it will show you the various widget types
-supported by Tk and how to use them. B<widget> should be installed in
-your default path, so type I<widget> at a command prompt.
-
-Here are links to other novice tutorials:
-
-L<http://www.lehigh.edu/~sol0/ptk/tpj1.html>
-L<http://www.lehigh.edu/~sol0/ptk/perlmonth01/pm1.html>
-
-I<Mastering Perl/Tk> is the definitive book on Perl/Tk:
-
-L<http://www.oreilly.com/catalog/mastperltk>
-
-=head1 Some Background
-
-Tk GUI programming is event-driven. (This may already be familiar to
-you.) In event-driven programs, the main GUI loop is outside of the
-user program and inside the GUI library. This loop - initiated by
-calling B<MainLoop> - watches all events of interest and activates
-the correct handler procedures to handle these events. Some of these
-handler procedures may be user-supplied; others will be part of the
-library.
-
-For a programmer, this means that you're not watching what is happening;
-instead, you are requested by the toolkit to perform actions whenever
-necessary.
-So, you're not watching for 'raise window / close window / redraw window'
-requests, but you tell the toolkit which routine will handle such cases,
-and the toolkit will call the procedures when required. These procedures
-are known as I<callbacks>, and some of them you write yourself.
-
-=head1 First Requirements
-
-B<Perl> programs that use Tk need to include C<use Tk>.
-A program should also use C<use strict> and the B<-w> switch to ensure
-the program is working without common errors.
-
-Any Perl/Tk application starts by creating the Tk B<L<MainWindow|Tk::MainWindow>>. You
-then create items inside the B<MainWindow>, and/or create new windows
-called B<L<Toplevel|Tk::Toplevel>>s that also contain child items, before starting the
-B<MainLoop>, which is the last logical statment in your program. You
-can also create more items and windows while you're running, using
-callbacks. Items are only shown on the display after they have been
-arranged by a I<geometry manager> like B<L<pack|Tk::pack>>; more information on
-this later. B<MainLoop> starts the GUI and handle all events. That's
-all there is to it! A trivial one-window example is shown below:
-
- #!/usr/bin/perl -w
- use Tk;
- use strict;
-
- my $mw = MainWindow->new;
- $mw->Label(-text => 'Hello, world!')->pack;
- $mw->Button(
- -text => 'Quit',
- -command => sub { exit },
- )->pack;
- MainLoop;
-
-Please run this example. It shows you two widget types, a B<L<Label|Tk::Label>>
-and a B<L<Button|Tk::Button>>, and how they are packed. When clicked, the B<Button>
-widget invokes the callback specified by the C<-command> option. Finally,
-note the typical Tk style using C<-option> =E<gt> C<value> pairs.
-
-=head1 Widget creation
-
-Tk windows and widgets are hierarchical, S<i.e. one> window includes
-one or more other windows. You create the first Tk window using
-C<MainWindow-E<gt>new>. This returns a window handle, assigned to
-C<$mw> in the example above. Keep track of the main handle, commonly
-called a I<widget reference>.
-
-You can use any Tk handle to create child widgets within the window (or
-widget). This is done by calling the Tk constructor method on the
-variable. In the example above, the C<Label> method called from
-C<$mw> creates a B<Label> widget inside the B<MainWindow>. In the
-constructor call, you can specify various options; you can later add
-or change options for any widget using the B<configure> method, which
-takes the same parameters as the constructor. The one exception to
-the hierarchical structure is the B<Toplevel> constructor, which
-creates a new outermost window.
-
-After you create any widget (other than the B<MainWindow> or
-B<Toplevel>s, you must render it by calling B<pack>. (This is not
-entirely true; more later)). If you do not need to refer to the widget
-after construction and packing, call B<pack> off the constructor
-results, as shown for the B<Label> and B<Button> in the example above. Note
-that the result of the compound call is the result of B<pack>, which
-is a valid Tk handle.
-
-Windows and widgets are deleted by calling B<destroy> on them;
-this will delete and un-draw the widget and all its children.
-
-=head1 Standard Tk widgets
-
-Here is an itemize of the standard Tk widget set.
-
-=over 4
-
-=item L<Button|Tk::Button>
-
-=item L<Canvas|Tk::Canvas>
-
-=item L<Checkbutton|Tk::Checkbutton>
-
-=item L<Entry|Tk::Entry>
-
-=item L<Frame|Tk::Frame>
-
-=item L<Label|Tk::Label>
-
-=item L<Labelframe|Tk::Labelframe>
-
-=item L<Listbox|Tk::Listbox>
-
-=item L<Menu|Tk::Menu>
-
-=item L<Menubutton|Tk::Menubutton>
-
-=item L<Message|Tk::Message>
-
-=item L<Panedwindow|Tk::Panedwindow>
-
-=item L<Radiobutton|Tk::Radiobutton>
-
-=item L<Scale|Tk::Scale>
-
-=item L<Scrollbar|Tk::Scrollbar>
-
-=item L<Spinbox|Tk::Spinbox>
-
-=item L<Text|Tk::Text>
-
-=item L<Toplevel|Tk::Toplevel>
-
-=back
-
-Perl/Tk provides an equal number of new widgets, above and beyond this
-core set.
-
-=over 4
-
-=item L<Adjuster|Tk::Adjuster>
-
-=item L<Balloon|Tk::Balloon>
-
-=item L<BrowseEntry|Tk::BrowseEntry>
-
-=item L<ColorEditor|Tk::ColorEditor>
-
-=item L<Dialog|Tk::Dialog>
-
-=item L<DialogBox|Tk::DialogBox>
-
-=item L<DirTree|Tk::DirTree>
-
-=item ErrorDialog
-
-=item L<FBox|Tk::FBox>
-
-=item L<FileSelect|Tk::FileSelect>
-
-=item L<HList|Tk::HList>
-
-=item LabEntry
-
-=item L<LabFrame|Tk::LabFrame>
-
-=item L<NoteBook|Tk::NoteBook>
-
-=item L<Optionmenu|Tk::Optionmenu>
-
-=item L<Pane|Tk::Pane>
-
-=item L<ProgressBar|Tk::ProgressBar>
-
-=item L<ROText|Tk::ROText>
-
-=item L<Table|Tk::Table>
-
-=item L<TextUndo|Tk::TextUndo>
-
-=item L<Tiler|Tk::Tiler>
-
-=item L<TList|Tk::TList>
-
-=item L<Tree|Tk::Tree>
-
-=back
-
-=head1 Variables and callback routines
-
-Most graphical interfaces are used to set up a set of values and conditions,
-and then perform the appropriate action. The Tk toolkit is different
-from your average text-based prompting or menu driven system in that you do
-not collect settings yourself, and decide on an action based on an
-input code; instead, you leave these
-values to your toolkit and only get them when the action is performed.
-
-So, where a traditional text-based system would look like this:
-
- #!/usr/bin/perl -w
- use strict;
-
- print "Please type a font name\n";
- my $font = <>; chomp $font;
- # Validate font
-
- print "Please type a file name\n";
- my $filename = <>; chomp $filename;
- # Validate filename
-
- print "Type <1> to fax, <2> to print\n";
- my $option = <>; chomp $option;
- if ($option eq 1) {
- print "Faxing $filename in font $font\n";
- } elsif ($option eq 2) {
- print "Now sending $filename to printer in font $font\n";
- }
-
-The slightly larger example below shows how to do this in Tk.
-Note the use of callbacks. Note, also, that Tk handles the values, and
-the subroutine uses the method B<get> to get at the values.
-If a user changes his mind and wants to change the font again,
-the application never notices; it's all handled by Tk.
-
- #!/usr/bin/perl -w
- use Tk;
- use strict;
-
- my $mw = MainWindow->new;
-
- $mw->Label(-text => 'File Name')->pack;
- my $filename = $mw->Entry(-width => 20);
- $filename->pack;
-
- $mw->Label(-text => 'Font Name')->pack;
- my $font = $mw->Entry(-width => 10);
- $font->pack;
-
- $mw->Button(
- -text => 'Fax',
- -command => sub{do_fax($filename, $font)}
- )->pack;
-
- $mw->Button(
- -text => 'Print',
- -command => sub{do_print($filename, $font)}
- )->pack;
-
- MainLoop;
-
- sub do_fax {
- my ($file, $font) = @_;
- my $file_val = $file->get;
- my $font_val = $font->get;
- print "Now faxing $file_val in font $font_val\n";
- }
-
- sub do_print {
- my ($file, $font) = @_;
- my $file_val = $file->get;
- my $font_val = $font->get;
- print "Sending file $file_val to printer in font $font_val\n";
- }
-
-=head1 The packer - grouping with Frame widgets
-
-In the examples above, you must have noticed the B<pack> calls. This
-is one of the more complicated parts of Tk. The basic idea is that
-any window or widget should be subject to a Tk geometry manager; the
-I<packer> is one of the placement managers, and B<L<grid|Tk::grid>> is another.
-
-The actions of the packer are rather simple: when applied
-to a widget, the packer positions that widget on the indicated position
-within the remaining space in its parent. By default, the position is
-on top; this means the next items will be put below. You can also
-specify the left, right, or bottom positions. Specify position
-using B<-side =E<gt> 'right'>.
-
-Additional packing parameters specify the behavior of the widget when
-there is some space left in the B<L<Frame|Tk::Frame>> or when the window size is
-increased. If widgets should maintain a fixed size, specify nothing;
-this is the default. For widgets that you want to fill up the current
-horizontal and/or vertical space, specify B<-fill =E<gt> 'x'>, B<'y'>,
-or B<'both'>; for widgets that should grow, specify B<-expand =E<gt> 1>.
-These parameters are not shown in the example below; see the B<widget>
-demonstration.
-
-If you want to group some items within a window that have a different
-packing order than others, you can include them in a Frame. This is a
-do-nothing window type that is meant for packing or filling (and to
-play games with borders and colors).
-
-The example below shows the use of pack and Frames:
-
- #!/usr/bin/perl -w
- use Tk;
- use strict;
-
- # Take top and the bottom - now implicit top is in the middle
- my $mw = MainWindow->new;
- $mw->title( 'The MainWindow' );
- $mw->Label(-text => 'At the top (default)')->pack;
- $mw->Label(-text => 'At the bottom')->pack(-side => 'bottom');
- $mw->Label(-text => 'The middle remains')->pack;
-
- # Since left and right are taken, bottom will not work...
- my $top1 = $mw->Toplevel;
- $top1->title( 'Toplevel 1' );
- $top1->Label(-text => 'Left')->pack(-side => 'left');
- $top1->Label(-text => 'Right')->pack(-side => 'right');
- $top1->Label(-text => '?Bottom?')->pack(-side => 'bottom');
-
- # But when you use Frames, things work quite alright
- my $top2 = $mw->Toplevel;
- $top2->title( 'Toplevel 2' );
- my $frame = $top2->Frame;
- $frame->pack;
- $frame->Label(-text => 'Left2')->pack(-side => 'left');
- $frame->Label(-text => 'Right2')->pack(-side => 'right');
- $top2->Label(-text => 'Bottom2')->pack(-side => 'bottom');
-
- MainLoop;
-
-=head1 More than one window
-
-Most real applications require more than one window. As you just saw,
-you can create more outermost windows by using a B<Toplevel> widget.
-Each window is independent; destroying a B<Toplevel> window does not
-affect the others as long as they are not a child of the closed
-B<Toplevel>. However, exiting the B<MainWindow> will destroy all remaining
-B<Toplevel> widgets and end the application. The
-example below shows a trivial three-window application:
-
- #!/usr/bin/perl -w
- use Tk;
- use strict;
-
- my $mw = MainWindow->new;
- fill_window($mw, 'Main');
- my $top1 = $mw->Toplevel;
- fill_window($top1, 'First top-level');
- my $top2 = $mw->Toplevel;
- fill_window($top2, 'Second top-level');
- MainLoop;
-
- sub fill_window {
- my ($window, $header) = @_;
- $window->Label(-text => $header)->pack;
- $window->Button(
- -text => 'close',
- -command => [$window => 'destroy']
- )->pack(-side => 'left');
- $window->Button(
- -text => 'exit',
- -command => [$mw => 'destroy']
- )->pack(-side => 'right');
- }
-
-=head1 More callbacks
-
-So far, all callback routines shown called a user procedure.
-You can also have a callback routine call another Tk routine.
-This is the way that scroll bars are implemented: scroll-bars
-can call a Tk item or a user procedure, whenever their position
-has changed. The Tk item that has a scrollbar attached calls the
-scrollbar when its size or offset has changed. In this way,
-the items are linked. You can still ask a scrollbar's position,
-or set it by hand - but the defaults will be taken care of.
-
-The example below shows a B<L<Listbox|Tk::Listbox>> with a scroll bar. Moving
-the scrollbar moves the B<Listbox>. Scanning a B<Listbox> (dragging
-an item with the left mouse button) moves the scrollbar.
-
- #!/usr/bin/perl -w
- use Tk;
- use strict;
-
- my $mw = MainWindow->new;
- my $box = $mw->Listbox(
- -relief => 'sunken',
- -height => 5,
- -setgrid => 1,
- );
- my @items = qw(One Two Three Four Five Six Seven
- Eight Nine Ten Eleven Twelve);
- foreach (@items) {
- $box->insert('end', $_);
- }
- my $scroll = $mw->Scrollbar(-command => ['yview', $box]);
- $box->configure(-yscrollcommand => ['set', $scroll]);
- $box->pack(-side => 'left', -fill => 'both', -expand => 1);
- $scroll->pack(-side => 'right', -fill => 'y');
-
- MainLoop;
-
-Note that there's a convenience method B<L<Scrolled|Tk::Scrolled>>
-which helps constructing widgets with automatically managed
-scrollbars.
-
-=head1 Canvases and tags
-
-One of the most powerful widgets in Tk is the B<L<Canvas|Tk::Canvas>> window.
-In a B<Canvas> window, you can draw simple graphics and include
-other widgets. The B<Canvas> area may be larger than the visible window,
-and may then be scrolled. Any item you draw on the canvas has its own id,
-and may optionally have one or more I<tags>. You may refer to any
-item by its id, and may refer to any group of items by a common tag;
-you can move, delete, or change groups of items using these tags,
-and you can I<bind> actions to tags. For a properly designed (often
-structured) B<Canvas>, you can specify powerful actions quite simply.
-
-In the example below, actions are bound to circles (single click)
-and blue items (double-click); obviously, this can be extended to any
-tag or group of tags.
-
- #!/usr/bin/perl -w
- use Tk;
- use strict;
-
- # Create B<MainWindow> and canvas
- my $mw = MainWindow->new;
- my $canvas = $mw->Canvas;
- $canvas->pack(-expand => 1, -fill => 'both');
-
- # Create various items
- create_item($canvas, 1, 1, 'circle', 'blue', 'Jane');
- create_item($canvas, 4, 4, 'circle', 'red', 'Peter');
- create_item($canvas, 4, 1, 'square', 'blue', 'James');
- create_item($canvas, 1, 4, 'square', 'red', 'Patricia');
-
- # Single-clicking with left on a 'circle' item invokes a procedure
- $canvas->bind('circle', '<1>' => sub {handle_circle($canvas)});
- # Double-clicking with left on a 'blue' item invokes a procedure
- $canvas->bind('blue', '<Double-1>' => sub {handle_blue($canvas)});
- MainLoop;
-
- # Create an item; use parameters as tags (this is not a default!)
- sub create_item {
- my ($can, $x, $y, $form, $color, $name) = @_;
-
- my $x2 = $x + 1;
- my $y2 = $y + 1;
- my $kind;
- $kind = 'oval' if ($form eq 'circle');
- $kind = 'rectangle' if ($form eq 'square');
- $can->create(
- ($kind, "$x" . 'c', "$y" . 'c',
- "$x2" . 'c', "$y2" . 'c'),
- -tags => [$form, $color, $name],
- -fill => $color);
- }
-
- # This gets the real name (not current, blue/red, square/circle)
- # Note: you'll want to return a list in realistic situations...
- sub get_name {
- my ($can) = @_;
- my $item = $can->find('withtag', 'current');
- my @taglist = $can->gettags($item);
- my $name;
- foreach (@taglist) {
- next if ($_ eq 'current');
- next if ($_ eq 'red' or $_ eq 'blue');
- next if ($_ eq 'square' or $_ eq 'circle');
- $name = $_;
- last;
- }
- return $name;
- }
-
- sub handle_circle {
- my ($can) = @_;
- my $name = get_name($can);
- print "Action on circle $name...\n";
- }
-
- sub handle_blue {
- my ($can) = @_;
- my $name = get_name($can);
- print "Action on blue item $name...\n";
- }
-
-=head1 Perl/Tk and Unicode
-
-Perl/Tk follows Perl's model of handling Unicode. That is, if a string
-is correctly flagged as a E<quot>characterE<quot> string in the sense
-like described in L<Encode/TERMINOLOGY>, then Perl/Tk will very
-probably display and handle this string correctly.
-
-Note that every variable which is passed somehow into a Perl/Tk method
-will be implicitely changed into an internally utf8-flagged variable.
-Semantically nothing changes, as the series of codepoints stays the
-same, but things will change when variables with high-bit iso-8859-1
-characters will be passed to the "outer" world. In this case you have
-to explicitely mark the encoding of your output stream if using IO, or
-encode the variables using L<Encode> for other style of communication.
-
-This is the theory, now some examples.
-
-If you use non-iso-8859-1 characters in the source code, then use
-either the C<use utf8;> or C<use encoding 'I<encodingname>'> pragma:
-
- use utf8;
- use Tk;
- my $x = "some characters using utf8 encoding";
- tkinit->Label(-text => $x)->pack;
- MainLoop;
-
-For data that comes from a file you have to specify the encoding
-unless it's encoded as ascii or iso-8559-1:
-
- use Tk;
- open my $FH, "<:encoding(utf-8)", "filename" or die $!;
- # or for utf-16 data: open my $FH, "<:encoding(utf-16)", "filename" or die $!;
- my $data = <$FH>;
- tkinit->Label(-text => $data)->pack;
- MainLoop;
-
-Likewise, the encoding must be specified for all data which is read
-from Tk widgets and that shall be output into a file. For the output,
-the encoding should be always specified, even if it is iso-8859-1:
-
- use Tk;
- $mw = tkinit;
- $mw->Entry(-textvariable => \$input)->pack;
- $mw->Button(
- -text => "Write to file",
- -command => sub {
- open my $FH, ">:encoding(iso-8859-1)", "filename" or die $!;
- print $FH $input;
- },
- )->pack;
- MainLoop;
-
-Note that Tk is Unicode-capable. So you need to be prepared that the
-user has the appropriate input methods activated to enter non-ascii
-characters. If an output encoding is used which does not cover the
-whole of Unicode codepoints then a warning will be issued when writing
-the file, like this:
-
- "\x{20ac}" does not map to iso-8859-1 at /usr/local/lib/perl5/site_perl/5.8.8/mach/Tk.pm line 250.
-
-Also, the same hexadecimal notation will be used as replacements for
-the unhandled characters.
-
-Handling encoding in I/O is pretty simple using the C<encoding> PerlIO
-layer, as described above. In other cases, such as when dealing with
-databases, encoding the data usually has to be done manually, unless
-the database driver has some means for automatically do this for you.
-So when working with a MySQL database, one could use:
-
- use Tk;
- use DBI;
- use Encode qw(encode);
- $mw = tkinit;
- $mw->Entry(-textvariable => \$input)->pack;
- $mw->Button(
- -text => "Write to database",
- -command => sub {
- my $dbh = DBI->connect("dbi:mysql:test", "root", "") or die;
- my $encoded_input = encode("iso-8859-1", $input);
- $dbh->do("INSERT INTO testtable VALUES (?)", undef, $encoded_input) or die;
- },
- )->pack;
- MainLoop;
-
-Unfortunately, there are still places in Perl ignorant of Unicode. One
-of these places are filenames. Consequently, the file selectors in
-Perl/Tk do not handle encoding of filenames properly. Currently they
-suppose that filenames are in iso-8859-1 encoding, at least on Unix
-systems. As soon as Perl has a concept of filename encodings, then
-Perl/Tk will also implement such schemes.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Tk/Widget.pod b/Master/tlpkg/tlperl/lib/Tk/Widget.pod
deleted file mode 100644
index 696bbab22b7..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Widget.pod
+++ /dev/null
@@ -1,678 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1997 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Widget - Base class of all widgets
-
-=for pm Tk/Widget.pm
-
-=for category Tk Generic Methods
-
-=head1 SYNOPSIS
-
- package Tk::Whatever;
- require Tk::Widget;
- @ISA = qw(Tk::Widget);
- Construct Tk::Widget 'Whatever';
-
- sub Tk_cmd { \&Tk::whatever }
-
-S< >I<$widget>-E<gt>I<method>(?I<arg, arg, ...>?)
-
-=head1 DESCRIPTION
-
-The B<Tk::Widget> is an abstract base class for all Tk widgets.
-
-Generic methods available to all widgets include the methods based on core
-C<winfo> mechanism and are used to retrieve information about windows managed by
-Tk. They can take any of a number of different forms, depending on the I<method>.
-The legal forms are:
-
-=over 4
-
-=item I<$widget>-E<gt>B<appname>?(I<newName>)?
-
-If I<newName> isn't specified, this method returns the name
-of the application (the name that may be used in B<send>
-commands to communicate with the application).
-If I<newName> is specified, then the name of the application
-is changed to I<newName>.
-If the given name is already in use, then a suffix of the form
-``B< #2>'' or ``B< #3>'' is appended in order to make the name unique.
-The method's result is the name actually chosen.
-I<newName> should not start with a capital letter.
-This will interfere with L<option|Tk::option> processing, since names starting with
-capitals are assumed to be classes; as a result, Tk may not
-be able to find some options for the application.
-If sends have been disabled by deleting the B<send> command,
-this command will reenable them and recreate the B<send>
-command.
-
-=item I<$widget>-E<gt>B<atom>(I<name>)
-
-Returns a decimal string giving the integer identifier for the
-atom whose name is I<name>. If no atom exists with the name
-I<name> then a new one is created.
-
-=item I<$widget>-E<gt>B<atomname>(I<id>)
-
-Returns the textual name for the atom whose integer identifier is
-I<id>.
-This command is the inverse of the I<$widget>-E<gt>B<atom> command.
-It generates an error if no such atom exists.
-
-=item I<$widget>-E<gt>B<bell>( ?-nice? );
-
-This command rings the bell on the display for I<$widget> and
-returns an empty string.
-The command uses the current bell-related settings for the display, which
-may be modified with programs such as B<xset>.
-
-If I<-nice> is not specified, this command also resets the screen saver
-for the screen. Some screen savers will ignore this, but others will
-reset so that the screen becomes visible again.
-
-=item I<$widget>-E<gt>B<bindDump>
-
-This command returns a list of strings suitable for printing detailing
-binding information for a widget. It prints a widget's
-bindtags. For each binding tag it prints all the bindings, comprised
-of the event descriptor and the callback. Callback arguments are
-printed, and B<Tk::Ev> objects are expanded.
-
-=item I<$widget>-E<gt>B<Busy>?(?-recurse => 1?,I<-option> => I<value>?)?
-
-This method B<configure>s a B<-cursor> option for I<$widget> and
-(if B<-recurse => 1> is specified) all its descendants. The cursor to
-be set may be passed as S<B<-cursor> => I<cursor>> or defaults to 'watch'.
-Additional B<configure> options are applied to I<$widget> only.
-It also adds a special tag B<'Busy'> to the B<bindtags> of the widgets so
-configured so that B<KeyPress>, B<KeyRelease>, B<ButtonPress> and
-B<ButtonRelease> events are ignored (with press events generating a call to
-B<bell>). It then acquires a local B<grab> for I<$widget>.
-The state of the widgets and the grab is restored by a call to
-I<$widget>-E<gt>B<Unbusy>.
-
-=item I<$widget>-E<gt>B<caret>( ?-x => I<x>?, ?-y => I<y>?, ?-height
-=> I<height>? );
-
-Sets and queries the caret location for the display of the specified
-Tk window window. The caret is the per-display cursor location used
-for indicating global focus (e.g. to comply with Microsoft
-Accessibility guidelines), as well as for location of the
-over-the-spot XIM (X Input Methods) or Windows IME windows. If no
-options are specified, the last values used for setting the caret are
-return in option-value pair format. -x and -y represent
-window-relative coordinates, and -height is the height of the current
-cursor location, or the height of the specified window if none is
-given.
-
-=item I<$widget>-E<gt>B<cells>
-
-Returns a decimal string giving the number of cells in the
-color map for I<$widget>.
-
-=item I<$widget>-E<gt>B<children>
-
-I<$widget->>B<children>
-Returns a list containing all the children
-of $widget. The list is in stacking order, with the lowest
-window first. Top-level windows are returned as children
-of their logical parents.
-
-=item I<$widget>-E<gt>B<class>
-
-Returns the class name for I<$widget>.
-
-=item I<$widget>-E<gt>B<colormapfull>
-
-Returns 1 if the colormap for I<$widget> is known to be full, 0
-otherwise. The colormap for a window is ``known'' to be full if the last
-attempt to allocate a new color on that window failed and this
-application hasn't freed any colors in the colormap since the
-failed allocation.
-
-=item I<$widget>-E<gt>B<ConfigSpecs>
-
-Used to perform delegated option configuration for a mega-widget.
-Returns, in Tk::Derived::ConfigSpecs notation (see L<Tk::ConfigSpecs>),
-all possible options for a widget. For example,
-
- $s = $self->Scale;
- $self->ConfigSpecs(
- $s->ConfigSpecs,
- .... more ConfigSpecs specifications
- );
-
-returns a hash of all Tk::Scale options, delegated to $s - e.g. some
-representative examples:
-
- -bigincrement => [$s, bigIncrement, BigIncrement, 0, 0]
- -digits => [$s, digits, Digits, 0, 0]
- -sliderlength => [$s, sliderLength, SliderLength, 10m, 30]
- -troughcolor => [$s, troughColor, Background, #c3c3c3, #c3c3c3]
-
-This provides an easy means of populating a mega-widget's ConfigSpecs
-with initializers.
-
-=item I<$widget>-E<gt>B<containing>(I<rootX,rootY>)
-
-Returns the window containing the point given
-by I<rootX> and I<rootY>.
-I<RootX> and I<rootY> are specified in screen units (i.e.
-any form acceptable to B<Tk_GetPixels>) in the coordinate
-system of the root window (if a virtual-root window manager is in
-use then the coordinate system of the virtual root window is used).
-If no window in this application contains the point then an empty
-string is returned.
-In selecting the containing window, children are given higher priority
-than parents and among siblings the highest one in the stacking order is
-chosen.
-
-=item I<$widget>-E<gt>B<depth>
-
-Returns a decimal string giving the depth of I<$widget> (number
-of bits per pixel).
-
-=item I<$widget>-E<gt>B<destroy>
-
-This command deletes the window related to
-I<$widget>, plus all its descendants.
-If all the B<MainWindows> are deleted then the entire application
-will be destroyed.
-
-The perl object I<$widget> continues to exist while references
-to it still exist, e.g. until variable goes out of scope.
-However any attempt to use Tk methods on the object will fail.
-B<Exists>(I<$widget>) will return false on such objects.
-
-Note however that while a window exists for I<$widget> the
-perl object is maintained (due to "references" in perl/Tk internals)
-even though original variables may have gone out of scope.
-(Normally this is intuitive.)
-
-=item B<Exists>(I<$widget>)
-
-Returns 1 if there exists a window for I<$widget>, 0 if no such
-window exists.
-
-=item I<$widget>-E<gt>B<font>(I<option>?, I<arg, arg, ...>?)
-
-Create and inspect fonts. See L<Tk::Font> for further details.
-
-=item I<$widget>-E<gt>B<fpixels>(I<number>)
-
-Returns a floating-point value giving the number of pixels
-in I<$widget> corresponding to the distance given by I<number>.
-I<Number> may be specified in any of the forms acceptable
-to B<Tk_GetScreenMM>, such as ``2.0c'' or ``1i''.
-The return value may be fractional; for an integer value, use
-I<$widget>-E<gt>B<pixels>.
-
-=item I<$widget>-E<gt>B<Getimage>(I<name>)
-
-Given I<name>, look for an image file with that base name and return
-a L<Tk::Image>. File extensions are tried in this order: F<xpm>,
-F<gif>, F<ppm>, F<xbm> until a valid iamge is found. If no image is
-found, try a builtin image with that name.
-
-=item I<$widget>-E<gt>B<geometry>
-
-Returns the geometry for I<$widget>, in the form
-I<width>B<x>I<height>B<+>I<x>B<+>I<y>. All dimensions are
-in pixels.
-
-=item I<$widget>-E<gt>B<height>
-
-Returns a decimal string giving I<$widget>'s height in pixels.
-When a window is first created its height will be 1 pixel; the
-height will eventually be changed by a geometry manager to fulfill
-the window's needs.
-If you need the true height immediately after creating a widget,
-invoke B<update> to force the geometry manager to arrange it,
-or use I<$widget>-E<gt>B<reqheight> to get the window's requested height
-instead of its actual height.
-
-=item I<$widget>-E<gt>B<id>
-
-Returns a hexadecimal string giving a low-level platform-specific
-identifier for $widget. On Unix platforms, this is the X
-window identifier. Under Windows, this is the Windows
-HWND. On the Macintosh the value has no meaning outside Tk.
-
-=item I<$widget>-E<gt>B<idletasks>
-
-One of two methods which are used to bring the application ``up to date''
-by entering the event loop repeated until all pending events
-(including idle callbacks) have been processed.
-
-If the B<idletasks> method is specified, then no new events or errors
-are processed; only idle callbacks are invoked. This causes operations
-that are normally deferred, such as display updates and window layout
-calculations, to be performed immediately.
-
-The B<idletasks> command is useful in scripts where changes have been
-made to the application's state and you want those changes to appear
-on the display immediately, rather than waiting for the script to
-complete. Most display updates are performed as idle callbacks, so
-B<idletasks> will cause them to run. However, there are some kinds of
-updates that only happen in response to events, such as those
-triggered by window size changes; these updates will not occur in
-B<idletasks>.
-
-=item I<$widget>-E<gt>B<interps>
-
-Returns a list whose members are the names of all Tcl interpreters
-(e.g. all Tk-based applications) currently registered for
-a particular display.
-The return value refers
-to the display of I<$widget>.
-
-=item I<$widget>-E<gt>B<ismapped>
-
-Returns B<1> if I<$widget> is currently mapped, B<0> otherwise.
-
-=item I<$widget->>B<lower>(?I<belowThis>?)
-
-If the I<belowThis> argument is omitted then the command lowers
-$widget so that it is below all of its siblings in the stacking
-order (it will be obscured by any siblings that overlap it and
-will not obscure any siblings).
-If I<belowThis> is specified then it must be the path name of
-a window that is either a sibling of $widget or the descendant
-of a sibling of $widget.
-In this case the B<lower> command will insert
-$widget into the stacking order just below I<belowThis>
-(or the ancestor of I<belowThis> that is a sibling of $widget);
-this could end up either raising or lowering $widget.
-
-=item I<$widget>-E<gt>B<MapWindow>
-
-Cause I<$widget> to be "mapped" i.e. made visible on the display.
-May confuse the geometry manager (pack, grid, place, ...)
-that thinks it is managing the widget.
-
-=item I<$widget>-E<gt>B<manager>
-
-Returns the name of the geometry manager currently
-responsible for I<$widget>, or an empty string if I<$widget>
-isn't managed by any geometry manager.
-The name is usually the name of the method for the geometry
-manager, such as B<pack> or B<place>.
-If the geometry manager is a widget, such as canvases or text, the
-name is the widget's class command, such as B<canvas>.
-
-=item I<$widget>-E<gt>B<name>
-
-Returns I<$widget>'s name (i.e. its name within its parent, as opposed
-to its full path name).
-The command I<$mainwin>-E<gt>B<name> will return the name of the application.
-
-=item I<$widget>-E<gt>B<OnDestroy>(I<callback>);
-
-OnDestroy accepts a standard perl/Tk I<callback>.
-When the window associated with I<$widget> is destroyed then
-the callback is invoked. Unlike I<$widget->>bind('E<lt>DestroyE<gt>',...)
-the widgets methods are still available when I<callback> is executed,
-so (for example) a B<Text> widget can save its contents to a file.
-
-OnDestroy was required for new B<after> mechanism.
-
-=item I<$widget>-E<gt>B<parent>
-
-Returns I<$widget>'s parent, or an empty string
-if I<$widget> is the main window of the application.
-
-=item I<$widget>-E<gt>B<PathName>
-
-Returns the Tk path name of I<$widget>. This is the inverse of the
-L</Widget> method. (This is an import from the C interface.)
-
-=item I<$widget>-E<gt>B<pathname>(I<id>)
-
-Returns an object whose X identifier is I<id>.
-The identifier is looked up on the display of I<$widget>.
-I<Id> must be a decimal, hexadecimal, or octal integer and must
-correspond to a window in the invoking application, or an error
-occurs which can be trapped with C<eval { }> or C<Tk::catch { }>.
-If the window belongs to the application, but is not an object
-(for example wrapper windows, HList header, etc.) then C<undef>
-is returned.
-
-=item I<$widget>-E<gt>B<pixels>(I<number>)
-
-Returns the number of pixels in I<$widget> corresponding
-to the distance given by I<number>.
-I<Number> may be specified in any of the forms acceptable
-to B<Tk_GetPixels>, such as ``2.0c'' or ``1i''.
-The result is rounded to the nearest integer value; for a
-fractional result, use I<$widget>-E<gt>B<fpixels>.
-
-=item I<$widget>-E<gt>B<pointerx>
-
-If the mouse pointer is on the same screen as I<$widget>, returns the
-pointer's x coordinate, measured in pixels in the screen's root window.
-If a virtual root window is in use on the screen, the position is
-measured in the virtual root.
-If the mouse pointer isn't on the same screen as I<$widget> then
--1 is returned.
-
-=item I<$widget>-E<gt>B<pointerxy>
-
-If the mouse pointer is on the same screen as I<$widget>, returns a list
-with two elements, which are the pointer's x and y coordinates measured
-in pixels in the screen's root window.
-If a virtual root window is in use on the screen, the position
-is computed in the virtual root.
-If the mouse pointer isn't on the same screen as I<$widget> then
-both of the returned coordinates are -1.
-
-=item I<$widget>-E<gt>B<pointery>
-
-If the mouse pointer is on the same screen as I<$widget>, returns the
-pointer's y coordinate, measured in pixels in the screen's root window.
-If a virtual root window is in use on the screen, the position
-is computed in the virtual root.
-If the mouse pointer isn't on the same screen as I<$widget> then
--1 is returned.
-
-=item I<$widget>-E<gt>B<raise>(?I<aboveThis>?)
-
-If the I<aboveThis> argument is omitted then the command raises
-$widget so that it is above all of its siblings in the stacking
-order (it will not be obscured by any siblings and will obscure
-any siblings that overlap it).
-If I<aboveThis> is specified then it must be the path name of
-a window that is either a sibling of $widget or the descendant
-of a sibling of $widget.
-In this case the B<raise> command will insert
-$widget into the stacking order just above I<aboveThis>
-(or the ancestor of I<aboveThis> that is a sibling of $widget);
-this could end up either raising or lowering $widget.
-
-=item I<$widget>-E<gt>B<reqheight>
-
-Returns a decimal string giving I<$widget>'s requested height,
-in pixels. This is the value used by I<$widget>'s geometry
-manager to compute its geometry.
-
-=item I<$widget>-E<gt>B<reqwidth>
-
-Returns a decimal string giving I<$widget>'s requested width,
-in pixels. This is the value used by I<$widget>'s geometry
-manager to compute its geometry.
-
-=item I<$widget>-E<gt>B<rgb>(I<color>)
-
-Returns a list containing three decimal values, which are the
-red, green, and blue intensities that correspond to I<color> in
-the window given by I<$widget>. I<Color>
-may be specified in any of the forms acceptable for a color
-option.
-
-=item I<$widget>-E<gt>B<rootx>
-
-Returns a decimal string giving the x-coordinate, in the root
-window of the screen, of the
-upper-left corner of I<$widget>'s border (or I<$widget> if it
-has no border).
-
-=item I<$widget>-E<gt>B<rooty>
-
-Returns a decimal string giving the y-coordinate, in the root
-window of the screen, of the
-upper-left corner of I<$widget>'s border (or I<$widget> if it
-has no border).
-
-=item I<$widget>-E<gt>B<scaling>?(I<number>)?
-
-Sets and queries the current scaling factor used by Tk to convert between
-physical units (for example, points, inches, or millimeters) and pixels. The
-I<number> argument is a floating point number that specifies the number of
-pixels per point on $widget's display. If the I<number> argument is
-omitted, the current value of the scaling factor is returned.
-
-A ``point'' is a unit of measurement equal to 1/72 inch. A scaling factor
-of 1.0 corresponds to 1 pixel per point, which is equivalent to a standard
-72 dpi monitor. A scaling factor of 1.25 would mean 1.25 pixels per point,
-which is the setting for a 90 dpi monitor; setting the scaling factor to
-1.25 on a 72 dpi monitor would cause everything in the application to be
-displayed 1.25 times as large as normal. The initial value for the scaling
-factor is set when the application starts, based on properties of the
-installed monitor (as reported via the window system),
-but it can be changed at any time. Measurements made
-after the scaling factor is changed will use the new scaling factor, but it
-is undefined whether existing widgets will resize themselves dynamically to
-accomodate the new scaling factor.
-
-=item I<$widget>-E<gt>B<screen>
-
-Returns the name of the screen associated with I<$widget>, in
-the form I<displayName>.I<screenIndex>.
-
-=item I<$widget>-E<gt>B<screencells>
-
-Returns a decimal string giving the number of cells in the default
-color map for I<$widget>'s screen.
-
-=item I<$widget>-E<gt>B<screendepth>
-
-Returns a decimal string giving the depth of the root window
-of I<$widget>'s screen (number of bits per pixel).
-
-=item I<$widget>-E<gt>B<screenheight>
-
-Returns a decimal string giving the height of I<$widget>'s screen,
-in pixels.
-
-=item I<$widget>-E<gt>B<screenmmheight>
-
-Returns a decimal string giving the height of I<$widget>'s screen,
-in millimeters.
-
-=item I<$widget>-E<gt>B<screenmmwidth>
-
-Returns a decimal string giving the width of I<$widget>'s screen,
-in millimeters.
-
-=item I<$widget>-E<gt>B<screenvisual>
-
-Returns one of the following strings to indicate the default visual
-class for I<$widget>'s screen: B<directcolor>, B<grayscale>,
-B<pseudocolor>, B<staticcolor>, B<staticgray>, or
-B<truecolor>.
-
-=item I<$widget>-E<gt>B<screenwidth>
-
-Returns a decimal string giving the width of I<$widget>'s screen,
-in pixels.
-
-=item I<$widget>-E<gt>B<server>
-
-Returns a string containing information about the server for
-I<$widget>'s display. The exact format of this string may vary
-from platform to platform. For X servers the string
-has the form ``B<X>I<major>B<R>I<minor vendor vendorVersion>''
-where I<major> and I<minor> are the version and revision
-numbers provided by the server (e.g., B<X11R5>), I<vendor>
-is the name of the vendor for the server, and I<vendorRelease>
-is an integer release number provided by the server.
-
-=item I<$widget>-E<gt>B<toplevel>
-
-Returns the reference of the top-level window containing I<$widget>.
-
-=item I<$widget>-E<gt>B<Unbusy>
-
-Restores widget state after a call to I<$widget>-E<gt>B<Busy>.
-
-=item I<$widget>-E<gt>B<UnmapWindow>
-
-Cause I<$widget> to be "unmapped" i.e. removed from the display.
-This does for any widget what I<$widget>-E<gt>withdraw does for
-toplevel widgets. May confuse the geometry manager (pack, grid, place, ...)
-that thinks it is managing the widget.
-
-=item I<$widget>-E<gt>B<update>
-
-One of two methods which are used to bring the application ``up to date''
-by entering the event loop repeated until all pending events
-(including idle callbacks) have been processed.
-
-The B<update> method is useful in scripts where you are performing a
-long-running computation but you still want the application to respond
-to events such as user interactions; if you occasionally call
-B<update> then user input will be processed during the next call to
-B<update>.
-
-=item I<$widget>-E<gt>B<useinputmethods>( ?I<boolean>? )
-
-Sets and queries the state of whether Tk should use XIM (X Input
-Methods) for filtering events. The resulting state is returned.
-XIM is used in some locales (ie: Japanese, Korean), to handle
-special input devices. This feature is only significant on X.
-If XIM support is not available, this will always return 0.
-If the boolean argument is omitted, the current state is
-returned. This is turned on by default for the main display.
-
-=item I<$widget>-E<gt>B<viewable>
-
-Returns 1 if I<$widget> and all of its ancestors up through the
-nearest toplevel window are mapped. Returns 0 if any of these
-windows are not mapped.
-
-=item I<$widget>-E<gt>B<visual>
-
-Returns one of the following strings to indicate the visual
-class for I<$widget>: B<directcolor>, B<grayscale>,
-B<pseudocolor>, B<staticcolor>, B<staticgray>, or
-B<truecolor>.
-
-=item I<$widget>-E<gt>B<visualid>
-
-Returns the X identifier for the visual for $widget.
-
-=item I<$widget>-E<gt>B<visualsavailable>(?B<includeids>?)
-
-Returns a list whose elements describe the visuals available for
-I<$widget>'s screen.
-Each element consists of a visual class followed by an integer depth.
-The class has the same form as returned by I<$widget>-E<gt>B<visual>.
-The depth gives the number of bits per pixel in the visual.
-In addition, if the B<includeids> argument is provided, then the
-depth is followed by the X identifier for the visual.
-
-=item I<$widget>-E<gt>B<vrootheight>
-
-Returns the height of the virtual root window associated with I<$widget>
-if there is one; otherwise returns the height of I<$widget>'s screen.
-
-=item I<$widget>-E<gt>B<vrootwidth>
-
-Returns the width of the virtual root window associated with I<$widget>
-if there is one; otherwise returns the width of I<$widget>'s screen.
-
-=item I<$widget>-E<gt>B<vrootx>
-
-Returns the x-offset of the virtual root window associated with I<$widget>,
-relative to the root window of its screen.
-This is normally either zero or negative.
-Returns 0 if there is no virtual root window for I<$widget>.
-
-=item I<$widget>-E<gt>B<vrooty>
-
-Returns the y-offset of the virtual root window associated with I<$widget>,
-relative to the root window of its screen.
-This is normally either zero or negative.
-Returns 0 if there is no virtual root window for I<$widget>.
-
-=item I<$widget->>B<waitVariable>(\$I<name>)
-
-=item I<$widget->>B<waitVisibility>
-
-=item I<$widget->>B<waitWindow>
-
-The B<tk wait> methods wait for one of several things to happen,
-then it returns without taking any other actions.
-The return value is always an empty string.
-B<waitVariable> expects a reference to a perl
-variable and the command waits for that variable to be modified.
-This form is typically used to wait for a user to finish interacting
-with a dialog which sets the variable as part (possibly final)
-part of the interaction.
-B<waitVisibility> waits for a change in I<$widget>'s
-visibility state (as indicated by the arrival of a VisibilityNotify
-event). This form is typically used to wait for a newly-created
-window to appear on the screen before taking some action.
-B<waitWindow> waits for I<$widget> to be destroyed.
-This form is typically used to wait for a user to finish interacting
-with a dialog box before using the result of that interaction.
-Note that creating and destroying the window each time a dialog is required
-makes code modular but imposes overhead which can be avoided by B<withdrawing>
-the window instead and using B<waitVisibility>.
-
-While the B<tk wait> methods are waiting they processes events in
-the normal fashion, so the application will continue to respond
-to user interactions.
-If an event handler invokes B<tkwait> again, the nested call
-to B<tkwait> must complete before the outer call can complete.
-
-=item I<$widget>-E<gt>B<Walk>(I<proc>?, I<arg, ...>?)
-
-Traverse a widget hierarchy starting at I<$widget> while executing the
-subroutine I<proc> to every visited widget. The arguments I<arg, ...>
-are supplied to the subroutine.
-
-=item I<$widget>-E<gt>B<Widget>(I<pathname>)
-
-Returns the widget reference for the given Tk path name, or C<undef>
-if the path name does not match a Tk widget. This is the inverse of
-the L</PathName> method. (This is an import from the C interface.)
-
-=item I<$widget>-E<gt>B<width>
-
-Returns a decimal string giving I<$widget>'s width in pixels.
-When a window is first created its width will be 1 pixel; the
-width will eventually be changed by a geometry manager to fulfill
-the window's needs.
-If you need the true width immediately after creating a widget,
-invoke B<update> to force the geometry manager to arrange it,
-or use I<$widget>-E<gt>B<reqwidth> to get the window's requested width
-instead of its actual width.
-
-=item I<$widget>-E<gt>B<windowingsystem>
-
-Returns the current Tk windowing system, one of B<x11> (X11-based),
-B<win32> (MS Windows), B<classic> (Mac OS Classic), or B<aqua> (Mac OS X Aqua).
-
-=item I<$widget>-E<gt>B<x>
-
-Returns a decimal string giving the x-coordinate, in I<$widget>'s
-parent, of the upper-left corner of I<$widget>'s border (or I<$widget>
-if it has no border).
-
-=item I<$widget>-E<gt>B<y>
-
-Returns a decimal string giving the y-coordinate, in I<$widget>'s
-parent, of the
-upper-left corner of I<$widget>'s border (or I<$widget> if it
-has no border).
-
-=back
-
-=head1 CAVEATS
-
-The above documentaion on generic methods is incomplete.
-
-=head1 KEYWORDS
-
-atom, children, class, geometry, height, identifier, information, interpreters,
-mapped, parent, path name, screen, virtual root, width, window
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/WidgetDemo.pod b/Master/tlpkg/tlperl/lib/Tk/WidgetDemo.pod
deleted file mode 100644
index 32c7a101dc6..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/WidgetDemo.pod
+++ /dev/null
@@ -1,59 +0,0 @@
-
-=head1 NAME
-
-WidgetDemo() - create a standard widget demonstration window.
-
-=for pm demos/demos/widget_lib/WidgetDemo.pm
-
-=for category Implementation
-
-=head1 SYNOPSIS
-
- use WidgetDemo;
- my $TOP = $MW->WidgetDemo(
- -name => $demo,
- -text => 'Learn how to write a widget demonstration!',
- -title => 'WidgetDemo Demonstration',
- -iconname => 'WidgetDemo',
- -geometry_manager => 'grid',
- -font => $FONT,
- );
-
-=head1 DESCRIPTION
-
-This constructor builds a standard widget demonstration window, composed of
-three frames. The top frame contains descriptive demonstration text. The
-bottom frame contains the "Dismiss" and "See Code" buttons. The middle frame
-is demonstration container, which came be managed by either the pack or grid
-geometry manager.
-
-The -text attribute is supplied to a Label widget, which is left-adjusted
-with -wraplength set to 4 inches. If you require different specifications
-then pass an array to -text; the first element is the text string and
-the remaining array elements are standard Label widget attributes - WidgetDemo
-will rearrange things as required..
-
- -text => ['Hello World!', qw/-wraplength 6i/],
-
-=head1 AUTHOR
-
-Steve Lidie <Stephen.O.Lidie@Lehigh.EDU>
-
-=head1 HISTORY
-
-lusol@Lehigh.EDU, LUCC, 97/02/11
-lusol@Lehigh.EDU, LUCC, 97/06/07
-Stephen.O.Lidie@Lehigh.EDU, LUCC, 97/06/07
- . Add Delegates() call that obviates the need for Top(). Many thanks to
- Achim Bohnet for this patch.
- . Fix -title so that it works.
-
-=head1 COPYRIGHT
-
-Copyright (C) 1997 - 1998 Stephen O. Lidie. All rights reserved.
-
-This program is free software; you can redistribute it and/or modify it under
-the same terms as Perl itself.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Wm.pod b/Master/tlpkg/tlperl/lib/Tk/Wm.pod
deleted file mode 100644
index 395fdf07d22..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Wm.pod
+++ /dev/null
@@ -1,667 +0,0 @@
-# Copyright (c) 1991-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Wm - Communicate with window manager
-
-=for category Tk Geometry Management
-
-=head1 SYNOPSIS
-
-S< >I<$toplevel>-E<gt>I<method>(?I<args>?)
-
-=head1 DESCRIPTION
-
-The B<wm> methods are used to interact with window managers in
-order to control such things as the title for a window, its geometry,
-or the increments in terms of which it may be resized.
-The B<wm> methods can take any of a number of different forms, depending on
-the particular I<method> argument.
-All of the forms expect I<$toplevel>, which must be a
-top-level window object.
-
-The legal forms for the B<wm> methods are:
-
-=over 4
-
-=item I<$toplevel>-E<gt>B<aspect>(?I<minNumer minDenom maxNumer maxDenom>?)
-
-If I<minNumer>, I<minDenom>, I<maxNumer>, and I<maxDenom>
-are all specified, then they will be passed to the window manager
-and the window manager should use them to enforce a range of
-acceptable aspect ratios for I<$toplevel>. The aspect ratio of
-I<$toplevel> (width/length) will be constrained to lie
-between I<minNumer>/I<minDenom> and I<maxNumer>/I<maxDenom>.
-If I<minNumer> etc. are all specified as empty strings, then
-any existing aspect ratio restrictions are removed.
-If I<minNumer> etc. are specified, then the method returns an
-empty string. Otherwise, it returns
-a array containing four elements, which are the current values
-of I<minNumer>, I<minDenom>, I<maxNumer>, and I<maxDenom>
-(if no aspect restrictions are in effect, then an empty string is
-returned).
-
-=item I<$widget>-E<gt>B<attributes>( I<?args?> );
-
-This subcommand returns or sets platform specific attributes
-associated with a window.
-
-=over 4
-
-=item I<$widget>-E<gt>B<attributes>;
-
-Returns a list of the platform specific flags and their values.
-
-=item I<$widget>-E<gt>B<attributes>( I<?option?> );
-
-Returns the value for the specific option.
-
-=item I<$widget>-E<gt>B<attributes>( I<?option value option value...?> );
-
-Sets one or more of the values. The values are as follows:
-
-On Windows, B<-disabled> gets or sets whether the window is in a
-disabled state. B<-toolwindow> gets or sets the style of the window
-to toolwindow (as defined in the MSDN). B<-topmost> gets or sets
-whether this is a topmost window (displays above all other windows).
-
-On Macintosh, there are currently no special attribute values.
-
-On Unix, there are currently no special attribute values.
-
-=back
-
-=item I<$toplevel>-E<gt>B<client>(?I<name>?)
-
-If I<name> is specified, this method stores I<name> (which
-should be the name of
-the host on which the application is executing) in I<$toplevel>'s
-B<WM_CLIENT_MACHINE> property for use by the window manager or
-session manager.
-The method returns an empty string in this case.
-If I<name> isn't specified, the method returns the last name
-set in a B<client> method for I<$toplevel>.
-If I<name> is specified as an empty string, the method deletes the
-B<WM_CLIENT_MACHINE> property from I<$toplevel>.
-
-=item I<$toplevel>-E<gt>B<colormapwindows>(?I<windowList>?)
-
-This method is used to manipulate the B<WM_COLORMAP_WINDOWS>
-property, which provides information to the window managers about
-windows that have private colormaps.
-If I<windowList> isn't specified, the method returns a list
-whose elements are the names of the windows in the B<WM_COLORMAP_WINDOWS>
-property.
-If I<windowList> is specified, it consists of a list of widgets;
-the method overwrites the B<WM_COLORMAP_WINDOWS>
-property with the given windows and returns an empty string.
-The B<WM_COLORMAP_WINDOWS> property should normally contain a
-list of the internal windows within I<$toplevel> whose colormaps differ
-from their parents.
-The order of the windows in the property indicates a priority order:
-the window manager will attempt to install as many colormaps as possible
-from the head of this list when I<$widget> gets the colormap focus.
-If I<$widget> is not included among the windows in I<windowList>,
-Tk implicitly adds it at the end of the B<WM_COLORMAP_WINDOWS>
-property, so that its colormap is lowest in priority.
-If I<$widget>-E<gt>colormapwindows is not invoked, Tk will automatically set
-the property for each top-level window to all the internal windows
-whose colormaps differ from their parents, followed by the top-level
-itself; the order of the internal windows is undefined.
-See the ICCCM documentation for more information on the
-B<WM_COLORMAP_WINDOWS> property.
-
-=item I<$toplevel>-E<gt>B<command>(?I<value>?)
-
-If I<value> is specified, this method stores I<value> in I<$toplevel>'s
-B<WM_COMMAND> property for use by the window manager or
-session manager and returns an empty string.
-I<Value> must have proper list structure; the elements should
-contain the words of the command used to invoke the application.
-If I<value> isn't specified then the method returns the last value
-set in a B<command> method for I<$toplevel>.
-If I<value> is specified as an empty string, the method
-deletes the B<WM_COMMAND> property from I<$toplevel>.
-
-=item I<$toplevel>-E<gt>B<deiconify>
-
-Arrange for I<$toplevel> to be displayed in normal (non-iconified) form.
-This is done by mapping the window. If the window has never been
-mapped then this method will not map the window, but it will ensure
-that when the window is first mapped it will be displayed
-in de-iconified form. Returns an empty string.
-
-=item I<$toplevel>-E<gt>B<focusmodel>(?B<active>|B<passive>?)
-
-If B<active> or B<passive> is supplied as an optional argument
-to the method, then it specifies the focus model for I<$toplevel>.
-In this case the method returns an empty string. If no additional
-argument is supplied, then the method returns the current focus
-model for I<$toplevel>.
-An B<active> focus model means that I<$toplevel> will claim the
-input focus for itself or its descendants, even at times when
-the focus is currently in some other application. B<Passive> means that
-I<$toplevel> will never claim the focus for itself: the window manager
-should give the focus to I<$toplevel> at appropriate times. However,
-once the focus has been given to I<$toplevel> or one of its descendants,
-the application may re-assign the focus among I<$toplevel>'s descendants.
-The focus model defaults to B<passive>, and Tk's B<focus> method
-assumes a passive model of focusing.
-
-=item I<$toplevel>-E<gt>B<frame>
-
-If I<$widget> has been reparented by the window manager into a
-decorative frame, the method returns the platform specific window
-identifier for the outermost frame that contains I<$toplevel> (the
-window whose parent is the root or virtual root). If I<$toplevel>
-hasn't been reparented by the window manager then the method returns
-the platform specific window identifier for I<$toplevel>.
-
-=item I<$toplevel>-E<gt>B<geometry>(?I<newGeometry>?)
-
-If I<newGeometry> is specified, then the geometry of I<$toplevel>
-is changed and an empty string is returned. Otherwise the current
-geometry for I<$toplevel> is returned (this is the most recent
-geometry specified either by manual resizing or
-in a B<geometry> method). I<NewGeometry> has
-the form B<=>I<width>B<x>I<height>B<+->I<x>B<+->I<y>, where
-any of B<=>, I<width>B<x>I<height>, or B<+->I<x>B<+->I<y>
-may be omitted. I<Width> and I<height> are positive integers
-specifying the desired dimensions of I<$toplevel>. If I<$toplevel>
-is gridded (see L<"GRIDDED GEOMETRY MANAGEMENT"> below) then the dimensions
-are specified in grid units; otherwise they are specified in pixel
-units. I<X> and I<y> specify the desired location of
-I<$toplevel> on the screen, in pixels.
-If I<x> is preceded by B<+>, it specifies
-the number of pixels between the left edge of the screen and the left
-edge of I<$toplevel>'s border; if preceded by B<-> then
-I<x> specifies the number of pixels
-between the right edge of the screen and the right edge of I<$toplevel>'s
-border. If I<y> is preceded by B<+> then it specifies the
-number of pixels between the top of the screen and the top
-of I<$toplevel>'s border; if I<y> is preceded by B<-> then
-it specifies the number of pixels between the bottom of I<$toplevel>'s
-border and the bottom of the screen.
-If I<newGeometry> is specified as an empty string then any
-existing user-specified geometry for I<$toplevel> is cancelled, and
-the window will revert to the size requested internally by its
-widgets.
-
-=item I<$toplevel>-E<gt>B<wmGrid>(?I<baseWidth,baseHeight,widthInc,heightInc>?)
-
-This method indicates that I<$toplevel> is to be managed as a
-gridded window.
-It also specifies the relationship between grid units and pixel units.
-I<BaseWidth> and I<baseHeight> specify the number of grid
-units corresponding to the pixel dimensions requested internally
-by I<$toplevel> using B<Tk_GeometryRequest>. I<WidthInc>
-and I<heightInc> specify the number of pixels in each horizontal
-and vertical grid unit.
-These four values determine a range of acceptable sizes for
-I<$toplevel>, corresponding to grid-based widths and heights
-that are non-negative integers.
-Tk will pass this information to the window manager; during
-manual resizing, the window manager will restrict the window's size
-to one of these acceptable sizes.
-Furthermore, during manual resizing the window manager will display
-the window's current size in terms of grid units rather than pixels.
-If I<baseWidth> etc. are all specified as empty strings, then
-I<$toplevel> will no longer be managed as a gridded window. If
-I<baseWidth> etc. are specified then the return value is an
-empty string.
-Otherwise the return value is a array containing
-four elements corresponding to the current I<baseWidth>,
-I<baseHeight>, I<widthInc>, and I<heightInc>; if
-I<$toplevel> is not currently gridded, then an empty string
-is returned.
-Note: this command should not be needed very often, since the
-B<Tk_SetGrid> library procedure and the B<-setgrid> option
-provide easier access to the same functionality.
-
-=item I<$toplevel>-E<gt>B<group>(?I<$widget>?)
-
-If I<$widget> is specified, it is the the leader of
-a group of related windows. The window manager may use this information,
-for example, to unmap all of the windows in a group when the group's
-leader is iconified. I<$widget> may be specified as an empty string to
-remove I<$toplevel> from any group association. If I<$widget> is
-specified then the method returns an empty string; otherwise it
-returns the I<$toplevel>'s current group leader, or an empty
-string if I<$toplevel> isn't part of any group.
-
-=item I<$toplevel>-E<gt>B<iconbitmap>(?I<bitmap>?)
-
-If I<bitmap> is specified, then it names a bitmap in the standard
-forms accepted by Tk (see the B<Tk_GetBitmap> documentation for details).
-This I<black and white> bitmap is passed to the window manager to be displayed
-in I<$toplevel>'s icon, and the method returns an empty string. If
-an empty string is specified for I<bitmap>, then any current icon
-bitmap or image is cancelled for I<$toplevel>.
-If I<bitmap> is specified then the method returns an empty string.
-Otherwise it returns the name of
-the current icon bitmap associated with I<$toplevel>, or an empty
-string if I<$toplevel> has no icon bitmap.
-
-=item I<$toplevel>-E<gt>B<iconify>
-
-Arrange for I<$toplevel> to be iconified. It I<$toplevel> hasn't
-yet been mapped for the first time, this method will arrange for
-it to appear in the iconified state when it is eventually mapped.
-
-=item I<$toplevel>-E<gt>B<iconimage>(?I<image>?)
-
-If I<image> is specified, then it names a normal Tk image.
-This image is rendered into a private I<coloured> bitmap which is passed to
-the window manager to be displayed in I<$toplevel>'s icon, and the method returns
-an empty string. If an empty string is specified for I<image>, then any current
-icon bitmap or image is cancelled for I<$toplevel>.
-If I<image> is specified then the method returns an empty string.
-Otherwise it returns the name of
-the current icon image associated with I<$toplevel>, or an empty
-string if I<$toplevel> has no icon image.
-The private pixmap is not pre-cleared so images which are partly "transparent"
-display rubbish in their transparent parts.
-
-The sizes of images that can be used as icons in this manner are platform
-dependant. On Win32 this sets the "large" icon, which should be 32x32, it
-will automatically be scaled down to 16x16 for use as a small icon.
-
-=item I<$toplevel>-E<gt>B<iconmask>(?I<bitmap>?)
-
-If I<bitmap> is specified, then it names a bitmap in the standard
-forms accepted by Tk (see the B<Tk_GetBitmap> documentation for details).
-This bitmap is passed to the window manager to be used as a mask
-in conjunction with the B<iconbitmap> option: where the mask
-has zeroes no icon will be displayed; where it has ones, the bits
-from the icon bitmap will be displayed. If
-an empty string is specified for I<bitmap> then any current icon
-mask is cancelled for I<$toplevel> (this is equivalent to specifying
-a bitmap of all ones). If I<bitmap> is specified
-then the method returns an empty string. Otherwise it
-returns the name of the current icon mask associated with
-I<$toplevel>, or an empty string if no mask is in effect.
-
-=item I<$toplevel>-E<gt>B<iconname>(?I<newName>?)
-
-If I<newName> is specified, then it is passed to the window
-manager; the window manager should display I<newName> inside
-the icon associated with I<$toplevel>. In this case an empty
-string is returned as result. If I<newName> isn't specified
-then the method returns the current icon name for I<$toplevel>,
-or an empty string if no icon name has been specified (in this
-case the window manager will normally display the window's title,
-as specified with the B<title> method).
-
-=item I<$toplevel>-E<gt>B<iconphoto>(?-default? I<image1> ?I<image2>
-...?)
-
-Sets the titlebar icon for window based on the named photo
-images. If -default is specified, this is applied to all future
-created toplevels as well. The data in the images is taken as a
-snapshot at the time of invocation. If the images are later
-changed, this is not reflected to the titlebar icons. Multiple
-images are accepted to allow different images sizes (eg, 16x16
-and 32x32) to be provided. The window manager may scale pro-
-vided icons to an appropriate size.
-
-On Windows, the images are packed into a Windows icon structure.
-This will override an ico specified to wm iconbitmap, and vice
-versa. [NOTE: This is not implemented yet!]
-
-On X, the images are arranged into the _NET_WM_ICON X property,
-which most modern window managers support. A wm iconbitmap may
-exist simultaneously. It is recommended to use not more than 2
-icons, placing the larger icon first.
-
-On Macintosh, this is currently does nothing.
-
-=item I<$toplevel>-E<gt>B<iconposition>(?I<x y>?)
-
-If I<x> and I<y> are specified, they are passed to the window
-manager as a hint about where to position the icon for I<$toplevel>.
-In this case an empty string is returned. If I<x> and I<y> are
-specified as empty strings then any existing icon position hint is cancelled.
-If neither I<x> nor I<y> is specified, then the method returns
-a array containing two values, which are the current icon position
-hints (if no hints are in effect then an empty string is returned).
-
-=item I<$toplevel>-E<gt>B<iconwindow>(?I<$widget>?)
-
-If I<$widget> is specified, it is a window to
-use as icon for I<$toplevel>: when I<$toplevel> is iconified then
-I<$widget> will be mapped to serve as icon, and when I<$toplevel>
-is de-iconified then I<$widget> will be unmapped again. If
-I<$widget> is specified as an empty string then any existing
-icon window association for I<$toplevel> will be cancelled. If
-the I<$widget> argument is specified then an empty string is
-returned. Otherwise the method returns the
-current icon window for I<$toplevel>, or an empty string if there
-is no icon window currently specified for I<$toplevel>.
-Button press events are disabled for I<$toplevel> as long as it is
-an icon window; this is needed in order to allow window managers
-to ``own'' those events.
-Note: not all window managers support the notion of an icon window.
-
-=item I<$toplevel>-E<gt>B<maxsize>(?I<width,height>?)
-
-If I<width> and I<height> are specified, they give
-the maximum permissible dimensions for I<$toplevel>.
-For gridded windows the dimensions are specified in
-grid units; otherwise they are specified in pixel units.
-The window manager will restrict the window's dimensions to be
-less than or equal to I<width> and I<height>.
-If I<width> and I<height> are
-specified, then the method returns an empty string. Otherwise
-it returns a array with two elements, which are the
-maximum width and height currently in effect.
-The maximum size defaults to the size of the screen.
-If resizing has been disabled with the B<resizable> method,
-then this method has no effect.
-See the sections on geometry management below for more information.
-
-=item I<$toplevel>-E<gt>B<minsize>(?I<width,height>?)
-
-If I<width> and I<height> are specified, they give the
-minimum permissible dimensions for I<$toplevel>.
-For gridded windows the dimensions are specified in
-grid units; otherwise they are specified in pixel units.
-The window manager will restrict the window's dimensions to be
-greater than or equal to I<width> and I<height>.
-If I<width> and I<height> are
-specified, then the method returns an empty string. Otherwise
-it returns a array with two elements, which are the
-minimum width and height currently in effect.
-The minimum size defaults to one pixel in each dimension.
-If resizing has been disabled with the B<resizable> method,
-then this method has no effect.
-See the sections on geometry management below for more information.
-
-=item I<$toplevel>-E<gt>B<overrideredirect(?>I<boolean>?)
-
-If I<boolean> is specified, it must have a proper boolean form and
-the override-redirect flag for I<$toplevel> is set to that value.
-If I<boolean> is not specified then B<1> or B<0> is
-returned to indicate whether or not the override-redirect flag
-is currently set for I<$toplevel>.
-Setting the override-redirect flag for a window causes
-it to be ignored by the window manager; among other things, this means
-that the window will not be reparented from the root window into a
-decorative frame and the user will not be able to manipulate the
-window using the normal window manager mechanisms.
-
-=item I<$toplevel>-E<gt>B<positionfrom>(?I<who>?)
-
-If I<who> is specified, it must be either B<program> or
-B<user>, or an abbreviation of one of these two. It indicates
-whether I<$toplevel>'s current position was requested by the
-program or by the user. Many window managers ignore program-requested
-initial positions and ask the user to manually position the window; if
-B<user> is specified then the window manager should position the
-window at the given place without asking the user for assistance.
-If I<who> is specified as an empty string, then the current position
-source is cancelled.
-If I<who> is specified, then the method returns an empty string.
-Otherwise it returns B<user> or $widget to indicate the
-source of the window's current position, or an empty string if
-no source has been specified yet. Most window managers interpret
-``no source'' as equivalent to B<program>.
-Tk will automatically set the position source to B<user>
-when a B<geometry> method is invoked, unless the source has
-been set explicitly to B<program>.
-
-=item I<$toplevel>-E<gt>B<protocol>(?I<name>?,?I<callback>?)
-
-This method is used to manage window manager protocols such as
-B<WM_DELETE_WINDOW>.
-I<Name> is the name of an atom corresponding to a window manager
-protocol, such as B<WM_DELETE_WINDOW> or B<WM_SAVE_YOURSELF>
-or B<WM_TAKE_FOCUS>.
-If both I<name> and I<callback> are specified, then I<callback>
-is associated with the protocol specified by I<name>.
-I<Name> will be added to I<$toplevel>'s B<WM_PROTOCOLS>
-property to tell the window manager that the application has a
-protocol handler for I<name>, and I<callback> will
-be invoked in the future whenever the window manager sends a
-message to the client for that protocol.
-In this case the method returns an empty string.
-If I<name> is specified but I<callback> isn't, then the current
-callback for I<name> is returned, or an empty string if there
-is no handler defined for I<name>.
-If I<callback> is specified as an empty string then the current
-handler for I<name> is deleted and it is removed from the
-B<WM_PROTOCOLS> property on I<$toplevel>; an empty string is
-returned.
-Lastly, if neither I<name> nor I<callback> is specified, the
-method returns a list of all the protocols for which handlers
-are currently defined for I<$toplevel>.
-
-=over 8
-
-Tk always defines a protocol handler for B<WM_DELETE_WINDOW>, even if
-you haven't asked for one with B<protocol>.
-If a B<WM_DELETE_WINDOW> message arrives when you haven't defined
-a handler, then Tk handles the message by destroying the window for
-which it was received.
-
-=back
-
-=item I<$toplevel>-E<gt>B<resizable>(?I<width,height>?)
-
-This method controls whether or not the user may interactively
-resize a top-level window. If I<width> and I<height> are
-specified, they are boolean values that determine whether the
-width and height of I<$toplevel> may be modified by the user.
-In this case the method returns an empty string.
-If I<width> and I<height> are omitted then the method
-returns a list with two 0/1 elements that indicate whether the
-width and height of I<$toplevel> are currently resizable.
-By default, windows are resizable in both dimensions.
-If resizing is disabled, then the window's size will be the size
-from the most recent interactive resize or B<geometry>
-method. If there has been no such operation then
-the window's natural size will be used.
-
-=item I<$toplevel>-E<gt>B<sizefrom>(?I<who>?)
-
-If I<who> is specified, it must be either B<program> or
-B<user>, or an abbreviation of one of these two. It indicates
-whether I<$toplevel>'s current size was requested by the
-program or by the user. Some window managers ignore program-requested
-sizes and ask the user to manually size the window; if
-B<user> is specified then the window manager should give the
-window its specified size without asking the user for assistance.
-If I<who> is specified as an empty string, then the current size
-source is cancelled.
-If I<who> is specified, then the method returns an empty string.
-Otherwise it returns B<user> or $widget to indicate the
-source of the window's current size, or an empty string if
-no source has been specified yet. Most window managers interpret
-``no source'' as equivalent to B<program>.
-
-=item I<$toplevel>-E<gt>B<stackorder>( I<?isabove|isbelow $toplevel?> );
-
-The stackorder command returns a list of toplevel windows in
-stacking order, from lowest to highest. When a single toplevel
-window is passed, the returned list recursively includes all of
-the window's children that are toplevels. Only those toplevels
-that are currently mapped to the screen are returned. The
-stackorder command can also be used to determine if one toplevel
-is positioned above or below a second toplevel. When two window
-arguments separated by either isabove or isbelow are passed, a
-boolean result indicates whether or not the first window is
-currently above or below the second window in the stacking order.
-
-
-=item I<$toplevel>-E<gt>B<state>(?I<newstate>?)
-
-If I<newstate> is specified, the window will be set to
-the new state, otherwise it returns the current state of
-I<$toplevel>: either B<normal>, B<iconic>, B<withdrawn>, B<icon>, or
-(Windows only) B<zoomed>. The
-difference between B<iconic> and B<icon> is that B<iconic> refers to a
-window that has been iconified (e.g., with the B<iconify> method)
-while B<icon> refers to a window whose only purpose is to serve as the
-icon for some other window (via the B<iconwindow> method). The
-B<icon> state cannot be set.
-
-
-=item I<$toplevel>-E<gt>B<title>(?I<string>?)
-
-If I<string> is specified, then it will be passed to the window
-manager for use as the title for I<$toplevel> (the window manager
-should display this string in I<$toplevel>'s title bar). In this
-case the method returns an empty string. If I<string> isn't
-specified then the method returns the current title for the
-I<$toplevel>. The title for a window defaults to its name.
-
-=item I<$toplevel>-E<gt>B<transient>(?I<master>?)
-
-If I<master> is specified, then the window manager is informed
-that I<$toplevel> is a transient window (e.g. pull-down menu) working
-on behalf of I<master> (where I<master> is
-a top-level window). Some window managers will use
-this information to manage I<$toplevel> specially. If I<master>
-is specified as an empty string then I<$toplevel> is marked as not
-being a transient window any more. If I<master> is specified,
-then the method returns an empty string. Otherwise the method
-returns the path name of I<$toplevel>'s current master, or an
-empty string if I<$toplevel> isn't currently a transient window.
-
-=item I<$toplevel>-E<gt>B<withdraw>
-
-Arranges for I<$toplevel> to be withdrawn from the screen. This
-causes the window to be unmapped and forgotten about by the window
-manager. If the window
-has never been mapped, then this method
-causes the window to be mapped in the withdrawn state. Not all
-window managers appear to know how to handle windows that are
-mapped in the withdrawn state.
-Note: it sometimes seems to be necessary to withdraw a
-window and then re-map it (e.g. with B<deiconify>) to get some
-window managers to pay attention to changes in window attributes
-such as group.
-
-=item I<$toplevel>-E<gt>B<wrapper>
-
-Returns the window id of the wrapper window in which Tk has placed
-I<$toplevel>. This is the id by which window manager will know
-I<$toplevel>, and so is appropriate place to add X properties.
-
-=back
-
-=head1 ICON SIZES
-
-The sizes of bitmaps/images that can be used as icons in this manner are platform
-and window manager dependant. Unix window managers are typically more tolerant
-than Win32. It is possible that coloured C<iconimage> icons may cause problems
-on some X window managers.
-
-=over 4
-
-=item * Win32
-
-C<iconimage> and C<iconbitmap> set the "large" icon, which should be
-32x32, it will automatically be scaled down to 16x16 for use as a small icon.
-Win32 ignores C<iconwin> requests.
-
-=item * KDE's "kwm"
-
-Accepts coloured C<iconimage> and black and white C<iconbitmap> but
-will scale either to a small (14x14?) icon. Kwm ignores C<iconwin>.
-
-=item * Sun's "olwm" or "olvwm"
-
-Honours C<iconwin> which will override C<iconimage> or C<iconbitmap>.
-Coloured images work.
-
-=item * Sun's CDE window manager
-
-Coloured images work. ...
-
-=back
-
-=head1 GEOMETRY MANAGEMENT
-
-By default a top-level window appears on the screen in its
-I<natural size>, which is the one determined internally by its
-widgets and geometry managers.
-If the natural size of a top-level window changes, then the window's size
-changes to match.
-A top-level window can be given a size other than its natural size in two ways.
-First, the user can resize the window manually using the facilities
-of the window manager, such as resize handles.
-Second, the application can request a particular size for a
-top-level window using the B<geometry> method.
-These two cases are handled identically by Tk; in either case,
-the requested size overrides the natural size.
-You can return the window to its natural by invoking B<geometry>
-with an empty I<geometry> string.
-
-Normally a top-level window can have any size from one pixel in each
-dimension up to the size of its screen.
-However, you can use the B<minsize> and B<maxsize> methods
-to limit the range of allowable sizes.
-The range set by B<minsize> and B<maxsize> applies to
-all forms of resizing, including the window's natural size as
-well as manual resizes and the B<geometry> method.
-You can also use the method B<resizable> to completely
-disable interactive resizing in one or both dimensions.
-
-=head1 GRIDDED GEOMETRY MANAGEMENT
-
-Gridded geometry management occurs when one of the widgets of an
-application supports a range of useful sizes.
-This occurs, for example, in a text editor where the scrollbars,
-menus, and other adornments are fixed in size but the edit widget
-can support any number of lines of text or characters per line.
-In this case, it is usually desirable to let the user specify the
-number of lines or characters-per-line, either with the
-B<geometry> method or by interactively resizing the window.
-In the case of text, and in other interesting cases also, only
-discrete sizes of the window make sense, such as integral numbers
-of lines and characters-per-line; arbitrary pixel sizes are not useful.
-
-Gridded geometry management provides support for this kind of
-application.
-Tk (and the window manager) assume that there is a grid of some
-sort within the application and that the application should be
-resized in terms of I<grid units> rather than pixels.
-Gridded geometry management is typically invoked by turning on
-the B<setGrid> option for a widget; it can also be invoked
-with the B<wmGrid> method or by calling B<Tk_SetGrid>.
-In each of these approaches the particular widget (or sometimes
-code in the application as a whole) specifies the relationship between
-integral grid sizes for the window and pixel sizes.
-To return to non-gridded geometry management, invoke
-B<grid> with empty argument strings.
-
-When gridded geometry management is enabled then all the dimensions specified
-in B<minsize>, B<maxsize>, and B<geometry> methods
-are treated as grid units rather than pixel units.
-Interactive resizing is also carried out in even numbers of grid units
-rather than pixels.
-
-=head1 BUGS
-
-Most existing window managers appear to have bugs that affect the
-operation of the B<wm> methods. For example, some changes won't
-take effect if the window is already active: the window will have
-to be withdrawn and de-iconified in order to make the change happen.
-
-=head1 SEE ALSO
-
-L<Tk::Widget|Tk::Widget>
-L<Tk::tixWm|Tk::tixWm>
-L<Tk::Mwm|Tk::Mwm>
-
-=head1 KEYWORDS
-
-aspect ratio, deiconify, focus model, geometry, grid, group, icon, iconify, increments, position, size, title, top-level window, units, window manager
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/X.pod b/Master/tlpkg/tlperl/lib/Tk/X.pod
deleted file mode 100644
index e6c7614a72c..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/X.pod
+++ /dev/null
@@ -1,373 +0,0 @@
-
-=head1 NAME
-
-Tk::X - Perl extension for Xlib constants.
-
-=for pm Xlib/X/X.pm
-
-=for category Other Modules and Languages
-
-=head1 SYNOPSIS
-
- use Tk::X;
-
-=head1 DESCRIPTION
-
-A module generated by h2xs. It exists to export Xlib #define type
-constants for possible use with Tk::Xlib.
-
-=head1 Exported constants
-
- Above
- AllTemporary
- AllocAll
- AllocNone
- AllowExposures
- AlreadyGrabbed
- Always
- AnyButton
- AnyKey
- AnyModifier
- AnyPropertyType
- ArcChord
- ArcPieSlice
- AsyncBoth
- AsyncKeyboard
- AsyncPointer
- AutoRepeatModeDefault
- AutoRepeatModeOff
- AutoRepeatModeOn
- BadAccess
- BadAlloc
- BadAtom
- BadColor
- BadCursor
- BadDrawable
- BadFont
- BadGC
- BadIDChoice
- BadImplementation
- BadLength
- BadMatch
- BadName
- BadPixmap
- BadRequest
- BadValue
- BadWindow
- Below
- BottomIf
- Button1
- Button1Mask
- Button1MotionMask
- Button2
- Button2Mask
- Button2MotionMask
- Button3
- Button3Mask
- Button3MotionMask
- Button4
- Button4Mask
- Button4MotionMask
- Button5
- Button5Mask
- Button5MotionMask
- ButtonMotionMask
- ButtonPress
- ButtonPressMask
- ButtonRelease
- ButtonReleaseMask
- CWBackPixel
- CWBackPixmap
- CWBackingPixel
- CWBackingPlanes
- CWBackingStore
- CWBitGravity
- CWBorderPixel
- CWBorderPixmap
- CWBorderWidth
- CWColormap
- CWCursor
- CWDontPropagate
- CWEventMask
- CWHeight
- CWOverrideRedirect
- CWSaveUnder
- CWSibling
- CWStackMode
- CWWidth
- CWWinGravity
- CWX
- CWY
- CapButt
- CapNotLast
- CapProjecting
- CapRound
- CenterGravity
- CirculateNotify
- CirculateRequest
- ClientMessage
- ClipByChildren
- ColormapChangeMask
- ColormapInstalled
- ColormapNotify
- ColormapUninstalled
- Complex
- ConfigureNotify
- ConfigureRequest
- ControlMapIndex
- ControlMask
- Convex
- CoordModeOrigin
- CoordModePrevious
- CopyFromParent
- CreateNotify
- CurrentTime
- CursorShape
- DefaultBlanking
- DefaultExposures
- DestroyAll
- DestroyNotify
- DirectColor
- DisableAccess
- DisableScreenInterval
- DisableScreenSaver
- DoBlue
- DoGreen
- DoRed
- DontAllowExposures
- DontPreferBlanking
- EastGravity
- EnableAccess
- EnterNotify
- EnterWindowMask
- EvenOddRule
- Expose
- ExposureMask
- FamilyChaos
- FamilyDECnet
- FamilyInternet
- FillOpaqueStippled
- FillSolid
- FillStippled
- FillTiled
- FirstExtensionError
- FocusChangeMask
- FocusIn
- FocusOut
- FontChange
- FontLeftToRight
- FontRightToLeft
- ForgetGravity
- GCArcMode
- GCBackground
- GCCapStyle
- GCClipMask
- GCClipXOrigin
- GCClipYOrigin
- GCDashList
- GCDashOffset
- GCFillRule
- GCFillStyle
- GCFont
- GCForeground
- GCFunction
- GCGraphicsExposures
- GCJoinStyle
- GCLastBit
- GCLineStyle
- GCLineWidth
- GCPlaneMask
- GCStipple
- GCSubwindowMode
- GCTile
- GCTileStipXOrigin
- GCTileStipYOrigin
- GXand
- GXandInverted
- GXandReverse
- GXclear
- GXcopy
- GXcopyInverted
- GXequiv
- GXinvert
- GXnand
- GXnoop
- GXnor
- GXor
- GXorInverted
- GXorReverse
- GXset
- GXxor
- GrabFrozen
- GrabInvalidTime
- GrabModeAsync
- GrabModeSync
- GrabNotViewable
- GrabSuccess
- GraphicsExpose
- GravityNotify
- GrayScale
- HostDelete
- HostInsert
- IncludeInferiors
- InputFocus
- InputOnly
- InputOutput
- IsUnmapped
- IsUnviewable
- IsViewable
- JoinBevel
- JoinMiter
- JoinRound
- KBAutoRepeatMode
- KBBellDuration
- KBBellPercent
- KBBellPitch
- KBKey
- KBKeyClickPercent
- KBLed
- KBLedMode
- KeyPress
- KeyPressMask
- KeyRelease
- KeyReleaseMask
- KeymapNotify
- KeymapStateMask
- LASTEvent
- LSBFirst
- LastExtensionError
- LeaveNotify
- LeaveWindowMask
- LedModeOff
- LedModeOn
- LineDoubleDash
- LineOnOffDash
- LineSolid
- LockMapIndex
- LockMask
- LowerHighest
- MSBFirst
- MapNotify
- MapRequest
- MappingBusy
- MappingFailed
- MappingKeyboard
- MappingModifier
- MappingNotify
- MappingPointer
- MappingSuccess
- Mod1MapIndex
- Mod1Mask
- Mod2MapIndex
- Mod2Mask
- Mod3MapIndex
- Mod3Mask
- Mod4MapIndex
- Mod4Mask
- Mod5MapIndex
- Mod5Mask
- MotionNotify
- NoEventMask
- NoExpose
- NoSymbol
- Nonconvex
- None
- NorthEastGravity
- NorthGravity
- NorthWestGravity
- NotUseful
- NotifyAncestor
- NotifyDetailNone
- NotifyGrab
- NotifyHint
- NotifyInferior
- NotifyNonlinear
- NotifyNonlinearVirtual
- NotifyNormal
- NotifyPointer
- NotifyPointerRoot
- NotifyUngrab
- NotifyVirtual
- NotifyWhileGrabbed
- Opposite
- OwnerGrabButtonMask
- ParentRelative
- PlaceOnBottom
- PlaceOnTop
- PointerMotionHintMask
- PointerMotionMask
- PointerRoot
- PointerWindow
- PreferBlanking
- PropModeAppend
- PropModePrepend
- PropModeReplace
- PropertyChangeMask
- PropertyDelete
- PropertyNewValue
- PropertyNotify
- PseudoColor
- RaiseLowest
- ReparentNotify
- ReplayKeyboard
- ReplayPointer
- ResizeRedirectMask
- ResizeRequest
- RetainPermanent
- RetainTemporary
- RevertToNone
- RevertToParent
- RevertToPointerRoot
- ScreenSaverActive
- ScreenSaverReset
- SelectionClear
- SelectionNotify
- SelectionRequest
- SetModeDelete
- SetModeInsert
- ShiftMapIndex
- ShiftMask
- SouthEastGravity
- SouthGravity
- SouthWestGravity
- StaticColor
- StaticGravity
- StaticGray
- StippleShape
- StructureNotifyMask
- SubstructureNotifyMask
- SubstructureRedirectMask
- Success
- SyncBoth
- SyncKeyboard
- SyncPointer
- TileShape
- TopIf
- TrueColor
- UnmapGravity
- UnmapNotify
- Unsorted
- VisibilityChangeMask
- VisibilityFullyObscured
- VisibilityNotify
- VisibilityPartiallyObscured
- VisibilityUnobscured
- WestGravity
- WhenMapped
- WindingRule
- XYBitmap
- XYPixmap
- X_H
- X_PROTOCOL
- X_PROTOCOL_REVISION
- YSorted
- YXBanded
- YXSorted
- ZPixmap
-
-=head1 AUTHOR
-
-Nick Ing-Simmons ran h2xs ...
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/X11Font.pod b/Master/tlpkg/tlperl/lib/Tk/X11Font.pod
deleted file mode 100644
index bd5b353abe0..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/X11Font.pod
+++ /dev/null
@@ -1,88 +0,0 @@
-
-=head1 NAME
-
-Tk::Font - a class for finding X Fonts
-
-=for pm Tk/X11Font.pm
-
-=for category Tk Generic Methods
-
-=head1 SYNOPSIS
-
- use Tk::X11Font;
-
- $font = $widget->X11Font(foundry => 'adobe',
- family => 'times',
- point => 120
- );
-
- $font = $widget->X11Font('*-courier-medium-r-normal-*-*');
-
-=head1 DESCRIPTION
-
- This module can be use to interrogate the X server what fonts are
- avaliable.
-
-=head1 METHODS
-
-=head2 Foundry( [ $val ] )
-
-=head2 Family( [ $val ] )
-
-=head2 Weight( [ $val ] )
-
-=head2 Slant( [ $val ] )
-
-=head2 Swidth( [ $val ] )
-
-=head2 Adstyle( [ $val ] )
-
-=head2 Pixel( [ $val ] )
-
-=head2 Point( [ $val ] )
-
-=head2 Xres( [ $val ] )
-
-=head2 Yres( [ $val ] )
-
-=head2 Space( [ $val ] )
-
-=head2 Avgwidth( [ $val ] )
-
-=head2 Registry( [ $val ] )
-
-=head2 Encoding( [ $val ] )
-
-Set the given field in the font name to C<$val> if given and return the current
-or previous value
-
-=head2 Name( [ $max ] )
-
-In a list context it returns a list of all font names that match the
-fields given. It will return a maximum of C<$max> names, or 128 if
-$max is not given.
-
-In a scalar contex it returns the first matching name or undef
-
-=head2 Clone( [ key => value, [ ...]] )
-
-Create a duplicate of the curent font object and modify the given fields
-
-=head1 AUTHOR
-
-Graham Barr <Graham.Barr@tiuk.ti.com>
-
-=head1 HISTORY
-
-11-Jan-96 Initial version
-
-08-Nov-98 Renamed for Tk800.012
-
-=head1 COPYRIGHT
-
-Copyright (c) 1995-1996 Graham Barr. All rights reserved. This program is free
-software; you can redistribute it and/or modify it under the same terms
-as Perl itself.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/Xrm.pod b/Master/tlpkg/tlperl/lib/Tk/Xrm.pod
deleted file mode 100644
index 55f885bc849..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Xrm.pod
+++ /dev/null
@@ -1,45 +0,0 @@
-
-=head1 NAME
-
-Tk::Xrm - X Resource/Defaults/Options routines that obey the rules.
-
-=for pm Tk/Xrm.pm
-
-=for category Creating and Configuring Widgets
-
-=head1 SYNOPSIS
-
- use Tk;
- use Tk::Xrm;
-
-=head1 DESCRIPTION
-
-Using this modules causes Tk's Option code to be replaced by versions
-which use routines from <X11/Xresource.h> - i.e. same ones every other
-X toolkit uses.
-
-Result is that "matching" of name/Class with the options database follows
-the same rules as other X toolkits. This makes it more predictable,
-and makes it easier to have a single ~/.Xdefaults file which gives sensible
-results for both Tk and (say) Motif applications.
-
-=head1 BUGS
-
-Currently B<optionAdd>(I<key> =E<gt> I<value>?, I<priority>?) ignores optional
-priority completely and just does XrmPutStringResource().
-Perhaps it should be more subtle and do XrmMergeDatabases() or
-XrmCombineDatabase().
-
-This version is a little slower than Tk's re-invention but there is
-more optimization that can be done.
-
-=head1 SEE ALSO
-
-L<Tk::option|Tk::option>
-
-=head1 KEYWORDS
-
-database, option, priority, retrieve
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/after.pod b/Master/tlpkg/tlperl/lib/Tk/after.pod
deleted file mode 100644
index 97c61ba380b..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/after.pod
+++ /dev/null
@@ -1,168 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::after - Execute a command after a time delay
-
-=for category Binding Events and Callbacks
-
-=head1 SYNOPSIS
-
-S< >I<$widget>-E<gt>B<after>(I<ms>)
-
-S< >I<$id> = I<$widget>-E<gt>B<after>(I<ms>?,I<callback>?)
-
-S< >I<$id> = I<$widget>-E<gt>B<repeat>(I<ms>?,I<callback>?)
-
-S< >I<$widget>-E<gt>B<afterCancel>(I<$id>)
-
-S< >I<$id> = I<$widget>-E<gt>B<afterIdle>(I<callback>)
-
-S< >I<$widget>-E<gt>B<afterInfo>?(I<$id>)?
-
-S< >I<$id>-E<gt>B<time>(?I<delay>?)
-
-=head1 DESCRIPTION
-
-This method is used to delay execution of the program or to execute
-a callback in background sometime in the future.
-
-In perl/Tk I<$widget>-E<gt>B<after> is implemented via the class C<Tk::After>,
-and callbacks are associated with I<$widget>, and are automatically cancelled
-when the widget is destroyed. An almost identical interface, but without
-automatic cancel, and without repeat is provided via Tk::after method.
-
-=head2 Internal Details
-
-The internal Tk::After class has the following synopsis:
-
- $id = Tk::After->new($widget, tid, $time, 'once', callback);
- $id = Tk::After->new($widget, tid, $time, 'repeat', callback);
- $id->cancel;
- $id->time(?delay?);
-
-$id is a Tk::After object, an array of 5 elements:
-
-I<$widget> is the parent widget reference.
-
-I<tid> is the internal timer id, a unique string.
-
-I<$time> is the string 'idle', representing an idle queue timer, or a
-integer millisecond value.
-
-I<once> or I<repeat> specifies whether the timer is a one-time B<after>
-event, or a repeating B<repeat> event.
-
-I<callback> specifies a Perl/Tk Tk::Callback object.
-
-=head1 Changing a B<repeat> timer interval
-
-It's posible to change a B<repeat> timer's delay value, or even cancel
-any timer, using the B<time> method. If I<delay> is specified and
-non-zero, a new timer delay is established. If I<delay> is zero the
-timer event is canceled just as if I<$id>-E<gt>B<cancel> were invoked.
-In all cases the current millisecond timer delay is returned.
-
-Note: the new timer delay will take effect on the I<subsequent> timer
-event - this command will not cancel the pending timer event and
-re-issue it with the new delay time.
-
-=head1 The after() method has several forms as follows:
-
-=over 4
-
-=item I<$widget>-E<gt>B<after>(I<ms>)
-
-The value I<ms> must be an integer giving a time in milliseconds.
-The command sleeps for I<ms> milliseconds and then returns.
-While the command is sleeping the application does not respond to
-events.
-
-=item I<$widget>-E<gt>B<after>(I<ms>,I<callback>)
-
-In this form the command returns immediately, but it arranges
-for I<callback> be executed I<ms> milliseconds later as an
-event handler.
-The callback will be executed exactly once, at the given time.
-The command will be executed in context of I<$widget>.
-If an error occurs while executing the delayed command then the
-L<Tk::Error|Tk::Error> mechanism is used to report the error.
-The B<after> command returns an identifier (an object in the perl/Tk
-case) that can be used to cancel the delayed command using B<afterCancel>.
-
-=item I<$widget>-E<gt>B<repeat>(I<ms>,I<callback>)
-
-In this form the command returns immediately, but it arranges
-for I<callback> be executed I<ms> milliseconds later as an
-event handler. After I<callback> has executed it is re-scheduled,
-to be executed in a futher I<ms>, and so on until it is cancelled.
-
-=item I<$widget>-E<gt>B<afterCancel>(I<$id>)
-
-=item I<$id>-E<gt>B<cancel>
-
-Cancels the execution of a delayed command that
-was previously scheduled.
-I<$id> indicates which command should be canceled; it must have
-been the return value from a previous B<after> command.
-If the command given by I<$id> has already been executed (and
-is not scheduled to be executed again) then B<afterCancel>
-has no effect.
-
-=item I<$widget>-E<gt>B<afterCancel>(I<callback>)
-
-I<This form is not robust in perl/Tk - its use is deprecated.>
-This command should also cancel the execution of a delayed command.
-The I<callback> argument is compared with pending callbacks,
-if a match is found, that callback is
-cancelled and will never be executed; if no such callback is
-currently pending then the B<afterCancel> has no effect.
-
-=item I<$widget>-E<gt>B<afterIdle>(I<callback>)
-
-Arranges for I<callback> to be evaluated later as an idle callback.
-The script will be run exactly once, the next time the event
-loop is entered and there are no events to process.
-The command returns an identifier that can be used
-to cancel the delayed command using B<afterCancel>.
-If an error occurs while executing the script then the
-L<Tk::Error|Tk::Error> mechanism is used to report the error.
-
-=item I<$widget>-E<gt>B<afterInfo>?(I<$id>)?
-
-This command returns information about existing event handlers. If no
-I<$id> argument is supplied, the command returns a list of the
-identifiers for all existing event handlers created by the B<after>
-and B<repeat> commands for I<$widget>. If I<$id> is supplied, it
-specifies an existing handler; I<$id> must have been the return value
-from some previous call to B<after> or B<repeat> and it must not have
-triggered yet or been cancelled. In this case the command returns a
-list with three elements. The first element of the list is the
-callback associated with I<$id>, the second element is either B<idle>
-or the I<integer> timer millisecond value to indicate what kind of
-event handler it is, and the third is a string I<once> or I<repeat> to
-differentiate an B<after> from a B<repeat> event.
-
-=back
-
-The B<after>(I<ms>) and B<afterIdle> forms of the command
-assume that the application is event driven: the delayed commands
-will not be executed unless the application enters the event loop.
-In applications that are not normally event-driven,
-the event loop can be entered with the B<vwait> and B<update> commands.
-
-=head1 SEE ALSO
-
-L<Tk::Error|Tk::Error>
-L<Tk::callbacks|Tk::callbacks>
-
-=head1 KEYWORDS
-
-cancel, delay, idle callback, sleep, time
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Tk/bind.pod b/Master/tlpkg/tlperl/lib/Tk/bind.pod
deleted file mode 100644
index f595a48e318..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/bind.pod
+++ /dev/null
@@ -1,583 +0,0 @@
-# Copyright (c) 1990 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::bind - Arrange for X events to invoke callbacks
-
-=for category Binding Events and Callbacks
-
-=head1 SYNOPSIS
-
-Retrieve bindings:
-
-S< >I<$widget>-E<gt>B<bind>
-
-S< >I<$widget>-E<gt>B<bind>(I<tag>)
-
-S< >I<$widget>-E<gt>B<bind>(I<sequence>)
-
-S< >I<$widget>-E<gt>B<bind>(I<tag>,I<sequence>)
-
-Associate and destroy bindings:
-
-S< >I<$widget>-E<gt>B<bind>(I<sequence>,I<callback>)
-
-S< >I<$widget>-E<gt>B<bind>(I<tag>,I<sequence>,I<callback>)
-
-=head1 DESCRIPTION
-
-The B<bind> method associates callbacks with X events.
-If I<callback> is specified, B<bind> will
-arrange for I<callback> to be evaluated whenever
-the event(s) given by I<sequence> occur in the window(s)
-identified by I<$widget> or I<tag>.
-If I<callback> is an empty string then the current binding for
-I<sequence> is destroyed, leaving I<sequence> unbound.
-In all of the cases where a I<callback> argument is provided,
-B<bind> returns an empty string.
-
-If I<sequence> is specified without a I<callback>, then the
-callback currently bound to I<sequence> is returned, or
-B<undef> is returned if there is no binding for I<sequence>.
-If neither I<sequence> nor I<callback> is specified, then the
-return value is a list whose elements are all the sequences
-for which there exist bindings for I<tag>.
-
-If no I<tag> is specified then the B<bind> refers to I<$widget>.
-If I<tag> is specified then it is typically a class name and the B<bind>
-refers to all instances of the class on the B<MainWindow> associated
-with I<$widget>. (It is possible for I<tag> to be another "widget object"
-but this practice is deprecated.) Perl's B<ref>(I<$object>) can be used
-to get the class name of any object.
-Each window has an associated list of tags, and a binding applies
-to a particular window if its tag is among those specified for
-the window.
-Although the B<bindtags> method may be used to assign an
-arbitrary set of binding tags to a window, the default binding
-tags provide the following behavior:
-
-If a tag is the name of an internal window the binding applies
-to that window.
-
-If the tag is the name of a toplevel window the binding applies
-to the toplevel window and all its internal windows.
-
-If the tag is the name of a class of widgets, such as B<Tk::Button>,
-the binding applies to all widgets in that class;
-
-If I<tag> has the value B<all>,
-the binding applies to all windows descended from the MainWindow
-of the application.
-
-=head1 EVENT PATTERNS
-
-The I<sequence> argument specifies a sequence of one or more event
-patterns, with optional white space between the patterns. Each event
-pat may take one of three forms. In the simplest case it is a single
-printing ASCII character, such as B<a> or B<[>. The character may not
-be a space character or the character <. This form of pattern matches
-a B<KeyPress> event for the particular character. The second form of
-pattern is longer but more general. It has the following syntax:
-
-S< >'<modifier-modifier-type-detail>'
-
-The entire event pattern is surrounded by angle brackets, and normally
-needs to be quoted, as angle brackets are special to perl.
-Inside the angle brackets are zero or more modifiers, an event
-type, and an extra piece of information (I<detail>) identifying
-a particular button or keysym. Any of the fields may be omitted,
-as long as at least one of I<type> and I<detail> is present.
-The fields must be separated by white space or dashes.
-
-The third form of pattern is used to specify a user-defined, named virtual
-event; see L<Tk::event> for details. It has the following syntax:
-
-S< >'<<name>>'
-
-The entire virtual event pattern is surrounded by double angle brackets.
-Inside the angle brackets is the user-defined name of the virtual event.
-Modifiers, such as B<Shift> or B<Control>, may not be combined with a
-virtual event to modify it. Bindings on a virtual event may be created
-before the virtual event is defined, and if the definition of a virtual
-event changes dynamically, all windows bound to that virtual event will
-respond immediately to the new definition.
-
-=head1 MODIFIERS
-
-Modifiers consist of any of the following values:
-
- Control Mod2, M2
- Shift Mod3, M3
- Lock Mod4, M4
- Button1, B1 Mod5, M5
- Button2, B2 Meta, M
- Button3, B3 Alt
- Button4, B4 Double
- Button5, B5 Triple
- Mod1, M1 Quadruple
-
-Where more than one value is listed, separated by commas, the values
-are equivalent.
-Most of the modifiers have the obvious X meanings.
-For example, B<Button1> requires that
-button 1 be depressed when the event occurs.
-For a binding to match a given event, the modifiers in the event
-must include all of those specified in the event pattern.
-An event may also contain additional modifiers not specified in
-the binding.
-For example, if button 1 is pressed while the shift and control keys
-are down, the pattern B<E<lt>Control-Button-1E<gt>> will match
-the event, but B<E<lt>Mod1-Button-1E<gt>> will not.
-If no modifiers are specified, then any combination of modifiers may
-be present in the event.
-
-B<Meta> and B<M> refer to whichever of the
-B<M1> through B<M5> modifiers is associated with the meta
-key(s) on the keyboard (keysyms B<Meta_R> and B<Meta_L>).
-If there are no meta keys, or if they are not associated with any
-modifiers, then B<Meta> and B<M> will not match any events.
-Similarly, the B<Alt> modifier refers to whichever modifier
-is associated with the alt key(s) on the keyboard (keysyms
-B<Alt_L> and B<Alt_R>).
-
-The B<Double>, B<Triple> and B<Quadruple> modifiers are a convenience
-for specifying double mouse clicks and other repeated events. They
-cause a particular event pattern to be repeated 2, 3 or 4 times, and
-also place a time and space requirement on the sequence: for a
-sequence of events to match a B<Double>, B<Triple> or B<Quadruple>
-pattern, all of the events must occur close together in time and
-without substantial mouse motion in between. For example,
-B<E<lt>Double-Button-1E<gt>> is equivalent to
-B<E<lt>Button-1E<gt>E<lt>Button-1E<gt>> with the extra time and space
-requirement.
-
-=head1 EVENT TYPES
-
-The I<type> field may be any of the standard X event types, with a
-few extra abbreviations. Below is a list of all the valid types;
-where two names appear together, they are synonyms.
-
-
- Activate Destroy Map
- ButtonPress, Button Enter MapRequest
- ButtonRelease Expose Motion
- Circulate FocusIn MouseWheel
- CirculateRequest FocusOut Property
- Colormap Gravity Reparent
- Configure KeyPress, Key ResizeRequest
- ConfigureRequest KeyRelease Unmap
- Create Leave Visibility
- Deactivate
-
-Most of the above events have the same fields and behaviors as events
-in the X Windowing system. You can find more detailed descriptions of
-these events in any X window programming book. A couple of the events
-are extensions to the X event system to support features unique to the
-Macintosh and Windows platforms. We provide a little more detail on
-these events here. These include:
-
- Activate
- Deactivate
-
-These two events are sent to every sub-window of a toplevel when they
-change state. In addition to the focus Window, the Macintosh platform
-and Windows platforms have a notion of an active window (which often
-has but is not required to have the focus). On the Macintosh, widgets
-in the active window have a different appearance than widgets in
-deactive windows. The Activate event is sent to all the sub-windows
-in a toplevel when it changes from being deactive to active.
-Likewise, the Deactive event is sent when the window's state changes
-from active to deactive. There are no use- ful percent substitutions
-you would make when binding to these events.
-
- MouseWheel
-
-Some mice on the Windows platform support a mouse wheel which is
-used for scrolling documents without using the scrollbars. By
-rolling the wheel, the system will generate MouseWheel events that
-the application can use to scroll. Like Key events the event is
-always routed to the window that currently has focus. When the
-event is received you can use the %D substitution to get the delta
-field for the event which is a integer value of motion that the
-mouse wheel has moved. The smallest value for which the system
-will report is defined by the OS. On Windows 95 & 98 machines
-this value is at least 120 before it is reported. However, higher
-resolution devices may be available in the future. The sign of
-the value determines which direction your widget should scroll.
-Positive values should scroll up and negative values should scroll
-down.
-
-The last part of a long event specification is I<detail>. In the
-case of a B<ButtonPress> or B<ButtonRelease> event, it is the
-number of a button (1-5). If a button number is given, then only an
-event on that particular button will match; if no button number is
-given, then an event on any button will match. Note: giving a
-specific button number is different than specifying a button modifier;
-in the first case, it refers to a button being pressed or released,
-while in the second it refers to some other button that is already
-depressed when the matching event occurs. If a button
-number is given then I<type> may be omitted: if will default
-to B<ButtonPress>. For example, the specifier B<E<lt>1E<gt>>
-is equivalent to B<E<lt>ButtonPress-1E<gt>>.
-
-If the event type is B<KeyPress> or B<KeyRelease>, then
-I<detail> may be specified in the form of an X keysym. Keysyms
-are textual specifications for particular keys on the keyboard;
-they include all the alphanumeric ASCII characters (e.g. ``a'' is
-the keysym for the ASCII character ``a''), plus descriptions for
-non-alphanumeric characters (``comma'' is the keysym for the comma
-character), plus descriptions for all the non-ASCII keys on the
-keyboard (``Shift_L'' is the keysm for the left shift key, and
-``F1'' is the keysym for the F1 function key, if it exists). The
-complete list of keysyms is not presented here; it is
-available in other X documentation and may vary from system to
-system.
-If necessary, you can use the B<'K'> notation described below
-to print out the keysym name for a particular key.
-If a keysym I<detail> is given, then the
-I<type> field may be omitted; it will default to B<KeyPress>.
-For example, B<E<lt>Control-commaE<gt>> is equivalent to
-B<E<lt>Control-KeyPress-commaE<gt>>.
-
-=head1 BINDING CALLBACKS AND SUBSTITUTIONS
-
-The I<callback> argument to B<bind> is a perl/Tk callback.
-which will be executed whenever the given event sequence occurs.
-(See L<Tk::callbacks> for description of the possible forms.)
-I<Callback> will be associated with the same B<MainWindow>
-that is associated with the I<$widget> that was used to invoke
-the B<bind> method, and it will run as though called from B<MainLoop>.
-If I<callback> contains
-any B<Ev>(I<%>) calls, then each "nested" B<Ev>(I<%>)
-"callback" will be evaluated when the event occurs to form arguments
-to be passed to the main I<callback>.
-The replacement
-depends on the character I<%>, as defined in the
-list below. Unless otherwise indicated, the
-replacement string is the numeric (decimal) value of the given field from
-the current event. Perl/Tk has enhanced this mechanism slightly compared
-to the comparable Tcl/Tk mechanism. The enhancements are not yet all
-reflected in the list below.
-Some of the substitutions are only valid for
-certain types of events; if they are used for other types of events
-the value substituted is undefined (not the same as B<undef>!).
-
-=over 4
-
-=item B<'#'>
-
-The number of the last client request processed by the server
-(the I<serial> field from the event). Valid for all event
-types.
-
-=item B<'a'>
-
-The I<above> field from the event,
-formatted as a hexadecimal number.
-Valid only for B<Configure> events.
-
-=item B<'b'>
-
-The number of the button that was pressed or released. Valid only
-for B<ButtonPress> and B<ButtonRelease> events.
-
-=item B<'c'>
-
-The I<count> field from the event. Valid only for B<Expose> events.
-
-=item B<'d'>
-
-The I<detail> field from the event. The B<'d'> is replaced by
-a string identifying the detail. For B<Enter>,
-B<Leave>, B<FocusIn>, and B<FocusOut> events,
-the string will be one of the following:
-
- NotifyAncestor NotifyNonlinearVirtual
- NotifyDetailNone NotifyPointer
- NotifyInferior NotifyPointerRoot
- NotifyNonlinear NotifyVirtual
-
-For B<ConfigureRequest> events, the string will be one of:
-
- Above Opposite
- Below None
- BottomIf TopIf
-
-For events other than these, the substituted string is undefined.
-(Note that this is I<not> the same as Detail part of sequence
-use to specify the event.)
-
-=item B<'f'>
-
-The I<focus> field from the event (B<0> or B<1>). Valid only
-for B<Enter> and B<Leave> events.
-
-=item B<'h'>
-
-The I<height> field from the event. Valid only for B<Configure>,
-B<ConfigureRequest>, B<Create>, B<Expose>, and B<ResizeRequest> events.
-
-=item B<'i'>
-
-The window field from the event, represented as a hexadecimal integer.
-
-=item B<'k'>
-
-The I<keycode> field from the event. Valid only for B<KeyPress>
-and B<KeyRelease> events.
-
-=item B<'m'>
-
-The I<mode> field from the event. The substituted string is one of
-B<NotifyNormal>, B<NotifyGrab>, B<NotifyUngrab>, or
-B<NotifyWhileGrabbed>. Valid only for B<Enter>,
-B<FocusIn>, B<FocusOut>, and B<Leave> events.
-
-=item B<'o'>
-
-The I<override_redirect> field from the event. Valid only for
-B<Map>, B<Reparent>, and B<Configure> events.
-
-=item B<'p'>
-
-The I<place> field from the event, substituted as one of the
-strings B<PlaceOnTop> or B<PlaceOnBottom>. Valid only
-for B<Circulate> and B<CirculateRequest> events.
-
-=item B<'s'>
-
-The I<state> field from the event. For B<ButtonPress>,
-B<ButtonRelease>, B<Enter>, B<KeyPress>, B<KeyRelease>,
-B<Leave>, and B<Motion> events, a decimal string
-is substituted. For B<Visibility>, one of the strings
-B<VisibilityUnobscured>, B<VisibilityPartiallyObscured>,
-and B<VisibilityFullyObscured> is substituted.
-
-=item B<'t'>
-
-The I<time> field from the event. Valid only for events that
-contain a I<time> field.
-
-=item B<'w'>
-
-The I<width> field from the event. Valid only for B<Configure>,
-B<ConfigueRequest>, B<Create>, B<Expose>, and B<ResizeREquest> events.
-
-=item B<'x'>
-
-The I<x> field from the event. Valid only for events containing
-an I<x> field.
-
-=item B<'y'>
-
-The I<y> field from the event. Valid only for events containing
-a I<y> field.
-
-=item B<'@'>
-
-The string "@I<x,y>" where I<x> and I<y> are as above.
-Valid only for events containing I<x> and I<y> fields.
-This format is used my methods of B<Tk::Text> and similar widgets.
-
-=item B<'A'>
-
-Substitutes the UNICODE character corresponding to the event, or
-the empty string if the event doesn't correspond to a UNICODE character
-(e.g. the shift key was pressed). B<XmbLookupString> does all the
-work of translating from the event to a UNICODE character.
-Valid only for B<KeyPress> and B<KeyRelease> events.
-
-=item B<'B'>
-
-The I<border_width> field from the event. Valid only for
-B<Configure>, B<ConfigureRequest> and B<Create> events.
-
-=item B<'D'>
-
-This reports the delta value of a B<MouseWheel> event. The delta
-value represents the rotation units the mouse wheel has been
-moved. On Windows 95 & 98 systems the smallest value for the
-delta is 120. Future systems may support higher resolution values
-for the delta. The sign of the value represents the direction the
-mouse wheel was scrolled.
-
-=item B<'E'>
-
-The I<send_event> field from the event. Valid for all event types.
-
-=item B<'K'>
-
-The keysym corresponding to the event, substituted as a textual
-string. Valid only for B<KeyPress> and B<KeyRelease> events.
-
-=item B<'N'>
-
-The keysym corresponding to the event, substituted as
-a decimal
-number. Valid only for B<KeyPress> and B<KeyRelease> events.
-
-=item B<'R'>
-
-The I<root> window identifier from the event. Valid only for
-events containing a I<root> field.
-
-=item B<'S'>
-
-The I<subwindow> window identifier from the event,
-as an object if it is one otherwise as a hexadecimal number.
-Valid only for events containing a I<subwindow> field.
-
-=item B<'T'>
-
-The I<type> field from the event. Valid for all event types.
-
-=item B<'W'>
-
-The window to which the event was reported (the
-$widget field from the event) - as an perl/Tk object.
-Valid for all event types.
-
-=item B<'X'>
-
-The I<x_root> field from the event.
-If a virtual-root window manager is being used then the substituted
-value is the corresponding x-coordinate in the virtual root.
-Valid only for
-B<ButtonPress>, B<ButtonRelease>, B<KeyPress>, B<KeyRelease>,
-and B<Motion> events.
-
-=item B<'Y'>
-
-The I<y_root> field from the event.
-If a virtual-root window manager is being used then the substituted
-value is the corresponding y-coordinate in the virtual root.
-Valid only for
-B<ButtonPress>, B<ButtonRelease>, B<KeyPress>, B<KeyRelease>,
-and B<Motion> events.
-
-=back
-
-=head1 MULTIPLE MATCHES
-
-It is possible for several bindings to match a given X event.
-If the bindings are associated with different I<tag>'s,
-then each of the bindings will be executed, in order.
-By default, a class binding will be executed first, followed
-by a binding for the widget, a binding for its toplevel, and
-an B<all> binding.
-The B<bindtags> method may be used to change this order for
-a particular window or to associate additional binding tags with
-the window.
-
-B<return> and B<Tk-E<gt>break> may be used inside a
-callback to control the processing of matching callbacks.
-If B<return> is invoked, then the current callback
-is terminated but Tk will continue processing callbacks
-associated with other I<tag>'s.
-If B<Tk-E<gt>break> is invoked within a callback,
-then that callback terminates and no other callbacks will be invoked
-for the event.
-(B<Tk-E<gt>break> is implemented via perl's B<die> with a special value
-which is "caught" by the perl/Tk "glue" code.)
-
-If more than one binding matches a particular event and they
-have the same I<tag>, then the most specific binding
-is chosen and its callback is evaluated.
-The following tests are applied, in order, to determine which of
-several matching sequences is more specific:
-(a) an event pattern that specifies a specific button or key is more specific
-than one that doesn't;
-(b) a longer sequence (in terms of number
-of events matched) is more specific than a shorter sequence;
-(c) if the modifiers specified in one pattern are a subset of the
-modifiers in another pattern, then the pattern with more modifiers
-is more specific.
-(d) a virtual event whose physical pattern matches the sequence is less
-specific than the same physical pattern that is not associated with a
-virtual event.
-(e) given a sequence that matches two or more virtual events, one
-of the virtual events will be chosen, but the order is undefined.
-
-If the matching sequences contain more than one event, then tests
-(c)-(e) are applied in order from the most recent event to the least recent
-event in the sequences. If these tests fail to determine a winner, then the
-most recently registered sequence is the winner.
-
-If there are two (or more) virtual events that are both triggered by the
-same sequence, and both of those virtual events are bound to the same window
-tag, then only one of the virtual events will be triggered, and it will
-be picked at random:
-
- $widget->eventAdd('<<Paste>>' => '<Control-y>');
- $widget->eventAdd('<<Paste>>' => '<Button-2>');
- $widget->eventAdd <<Scroll>>' => '<Button-2>');
- $widget->bind('Tk::Entry','<<Paste>>',sub { print 'Paste'});
- $widget->bind('Tk::Entry','<<Scroll>>', sub {print 'Scroll'});
-
-If the user types Control-y, the B<E<lt>E<lt>PasteE<gt>E<gt>> binding
-will be invoked, but if the user presses button 2 then one of
-either the B<E<lt>E<lt>PasteE<gt>E<gt>> or the B<E<lt>E<lt>ScrollE<gt>E<gt>> bindings will
-be invoked, but exactly which one gets invoked is undefined.
-
-If an X event does not match any of the existing bindings, then the
-event is ignored.
-An unbound event is not considered to be an error.
-
-=head1 MULTI-EVENT SEQUENCES AND IGNORED EVENTS
-
-When a I<sequence> specified in a B<bind> method contains
-more than one event pattern, then its callback is executed whenever
-the recent events (leading up to and including the current event)
-match the given sequence. This means, for example, that if button 1 is
-clicked repeatedly the sequence B<E<lt>Double-ButtonPress-1E<gt>> will match
-each button press but the first.
-If extraneous events that would prevent a match occur in the middle
-of an event sequence then the extraneous events are
-ignored unless they are B<KeyPress> or B<ButtonPress> events.
-For example, B<E<lt>Double-ButtonPress-1E<gt>> will match a sequence of
-presses of button 1, even though there will be B<ButtonRelease>
-events (and possibly B<Motion> events) between the
-B<ButtonPress> events.
-Furthermore, a B<KeyPress> event may be preceded by any number
-of other B<KeyPress> events for modifier keys without the
-modifier keys preventing a match.
-For example, the event sequence B<aB> will match a press of the
-B<a> key, a release of the B<a> key, a press of the B<Shift>
-key, and a press of the B<b> key: the press of B<Shift> is
-ignored because it is a modifier key.
-Finally, if several B<Motion> events occur in a row, only
-the last one is used for purposes of matching binding sequences.
-
-=head1 ERRORS
-
-If an error occurs in executing the callback for a binding then the
-B<Tk::Error> mechanism is used to report the error.
-The B<Tk::Error> mechanism will be executed at same call level,
-and associated with the same B<MainWindow> as
-as the callback was invoked.
-
-=head1 CAVEATS
-
-Note that for the B<Canvas> widget, the call to B<bind> has to be
-fully qualified. This is because there is already a bind method for
-the B<Canvas> widget, which binds individual canvas tags.
-
-S< >I<$canvas>-E<gt>B<Tk::bind>
-
-=head1 SEE ALSO
-
-L<Tk::Error|Tk::Error>
-L<Tk::callbacks|Tk::callbacks>
-L<Tk::bindtags|Tk::bindtags>
-
-=head1 KEYWORDS
-
-Event, binding
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/bindtags.pod b/Master/tlpkg/tlperl/lib/Tk/bindtags.pod
deleted file mode 100644
index 3ee6ddb9473..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/bindtags.pod
+++ /dev/null
@@ -1,107 +0,0 @@
-# Copyright (c) 1990 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::bindtags - Determine which bindings apply to a window, and order of evaluation
-
-=for category Binding Events and Callbacks
-
-=head1 SYNOPSIS
-
-I<$widget>-E<gt>B<bindtags>([I<tagList>]);
-
-I<@tags> = I<$widget>-E<gt>B<bindtags>;
-
-=head1 DESCRIPTION
-
-When a binding is created with the B<bind> command, it is
-associated either with a particular window such as I<$widget>,
-a class name such as B<Tk::Button>, the keyword B<all>, or any
-other string.
-All of these forms are called I<binding tags>.
-Each window has a list of binding tags that determine how
-events are processed for the window.
-When an event occurs in a window, it is applied to each of the
-window's tags in order: for each tag, the most specific binding
-that matches the given tag and event is executed.
-See the L<Tk::bind> documentation for more information on the matching
-process.
-
-By default, each window has four binding tags consisting of the
-the window's class name, name of the window, the name of the window's
-nearest toplevel ancestor, and B<all>, in that order.
-Toplevel windows have only three tags by default, since the toplevel
-name is the same as that of the window.
-
-Note that this order is I<different> from order used by Tcl/Tk.
-Tcl/Tk has the window ahead of the class name in the binding order.
-This is because Tcl is procedural rather than object oriented and
-the normal way for Tcl/Tk applications to override class bindings
-is with an instance binding. However, with perl/Tk the normal way
-to override a class binding is to derive a class. The perl/Tk order
-causes instance bindings to execute after the class binding, and
-so instance bind callbacks can make use of state changes (e.g. changes
-to the selection) than the class bindings have made.
-
-The B<bindtags> command allows the binding tags for a window to be
-read and modified.
-
-If I<$widget>-E<gt>B<bindtags> is invoked without an argument, then the
-current set of binding tags for $widget is returned as a list.
-If the I<tagList> argument is specified to B<bindtags>,
-then it must be a reference to and array; the tags for $widget are changed
-to the elements of the array. (A reference to an anonymous array can
-be created by enclosin the elements in B<[ ]>.)
-The elements of I<tagList> may be arbitrary strings or widget objects,
-if no window exists for an object at the time an event is processed,
-then the tag is ignored for that event.
-The order of the elements in I<tagList> determines the order in
-which binding callbacks are executed in response to events.
-For example, the command
-
- $b->bindtags([$b,ref($b),$b->toplevel,'all'])
-
-applies the Tcl/Tk binding order which binding callbacks will be
-evaluated for a button (say) B<$b> so that B<$b>'s instance bindings
-are invoked first, following by bindings for B<$b>'s class, followed by
-bindings for B<$b>'s toplevel, followed by 'B<all>' bindings.
-
-If I<tagList> is an empty list i.e. B<[]>, then the binding
-tags for $widget are returned to the perl/Tk default state described above.
-
-The B<bindtags> command may be used to introduce arbitrary
-additional binding tags for a window, or to remove standard tags.
-For example, the command
-
- $b->bindtags(['TrickyButton',$b->toplevel,'all'])
-
-replaces the (say) B<Tk::Button> tag for B<$b> with B<TrickyButton>.
-This means that the default widget bindings for buttons, which are
-associated with the B<Tk::Button> tag, will no longer apply to B<$b>,
-but any bindings associated with B<TrickyButton> (perhaps some
-new button behavior) will apply.
-
-=head1 BUGS
-
-The current mapping of the 'native' Tk behaviour of this method
-i.e. returning a list but only accepting a reference to an array is
-counter intuitive. The perl/Tk interface may be tidied up, returning
-a list is sensible so, most likely fix will be to allow a list to be
-passed to I<set> the bindtags.
-
-=head1 SEE ALSO
-
-L<Tk::bind|Tk::bind>
-L<Tk::callbacks|Tk::callbacks>
-
-=head1 KEYWORDS
-
-binding, event, tag
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/callbacks.pod b/Master/tlpkg/tlperl/lib/Tk/callbacks.pod
deleted file mode 100644
index 5b62cb7c12c..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/callbacks.pod
+++ /dev/null
@@ -1,104 +0,0 @@
-# $Id: callbacks.pod 1.3 Thu, 27 Nov 1997 00:26:00 +0100 ach $
-
-=head1 NAME
-
-Tk::callbacks - Specifying code for Tk to call.
-
-=for category Binding Events and Callbacks
-
-=head1 SYNOPSIS
-
-One can specify a callback in one of the following ways:
-
-Without arguments:
-
- ... => \&subname, ...
- ... => sub { ... }, ...
- ... => 'methodname', ...
-
-or with arguments:
-
- ... => [ \&subname, args ... ], ...
- ... => [ sub { ... }, args... ], ...
- ... => [ 'methodname', args... ], ...
-
-=head1 DESCRIPTION
-
-Perl/Tk has a callback, where Tcl/Tk has a command string (i.e. a fragment of
-Tcl to be executed). A perl/Tk callback can take one of the following
-basic forms:
-
-=over 4
-
-=item * Reference to a subroutine C<\E<amp>subname>
-
-=item * Anonymous subroutine (closure) C<sub { ... }>
-
-=item * A method name C<'methodname'>
-
-=back
-
-Any of these can be provided with arguments by enclosing them and the
-arguments in B<[]>. Here are some examples:
-
-I<$mw>->B<bind>(I<$class,> B<"E<lt>DeleteE<gt>" =E<gt> 'Delete'>);
-
-This will call I<$widget>->B<Delete>, the I<$widget> being provided (by bind) as
-the one where the Delete key was pressed.
-
-While having bind provide a widget object for you is ideal in many cases
-it can be irritating in others. Using the list form this behaviour
-can be modified:
-
-I<$a>-E<gt>B<bind>(B<"E<lt>DeleteE<gt>">,[I<$b> =E<gt> 'Delete']);
-
-because the first element I<$b> is an object bind
-will call I<$b>-E<gt>B<Delete>.
-
-Note that method/object ordering only matters for C<bind> callbacks,
-the auto-quoting in perl5.001 makes the first of these a little more readable:
-
- $w->configure(-yscrollcommand => [ set => $ysb]);
- $w->configure(-yscrollcommand => [ $ysb => 'set' ]);
-
-but both will call C<$ysb>-E<gt>set(args provided by Tk)
-
-Another use of arguments allows you to write generalized methods which are
-easier to re-use:
-
- $a->bind("<Next>",['Next','Page']);
- $a->bind("<Down>",['Next','Line']);
-
-This will call C<$a>-E<gt>I<Next>('Page') or C<$a>-E<gt>I<Next>('Line') respectively.
-
-Note that the contents of the C<[]> are evaluated by perl when the
-callback is created. It is often desirable for the arguments provided
-to the callback to depend on the details of the event which caused
-it to be executed. To allow for this callbacks can be nested using the
-C<Ev(...)> "constructor".
-C<Ev(...)> inserts callback objects into the
-argument list. When perl/Tk glue code is preparing the argument list for
-the callback it is about to call it spots these special objects and
-recursively applies the callback process to them.
-
-=head1 EXAMPLES
-
- $entry->bind('<Return>' => [$w , 'validate', Ev(['get'])]);
-
- $toplevel->bind('all', '<Visibility>', [\&unobscure, Ev('s')]);
-
- $mw->bind($class, '<Down>', ['SetCursor', Ev('UpDownLine',1)]);
-
-=head1 SEE ALSO
-
-L<Tk::bind|Tk::bind>
-L<Tk::after|Tk::after>
-L<Tk::options|Tk::options>
-L<Tk::fileevent|Tk::fileevent>
-
-=head1 KEYWORDS
-
-callback, closure, anonymous subroutine, bind
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/chooseColor.pod b/Master/tlpkg/tlperl/lib/Tk/chooseColor.pod
deleted file mode 100644
index dbb8f158efa..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/chooseColor.pod
+++ /dev/null
@@ -1,64 +0,0 @@
-# Copyright (c) 1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-chooseColor - pops up a dialog box for the user to select a color.
-
-=for category Popups and Dialogs
-
-=head1 SYNOPSIS
-
-S< >I<$color> = I<$widget>-E<gt>B<chooseColor>?(I<-option>=E<gt>I<value>, ...)?;
-
-=head1 DESCRIPTION
-
-The method B<chooseColor> is implemented as a perl wrapper
-on the core tk "command" B<tk_chooseColor>, and I<$widget>
-is passed as the argument to the hidden B<-parent> option.
-The implementation of internal B<tk_chooseColor> is platform
-specific, on Win32 it is a native dialog, and on UNIX/X11 it is implemented
-in terms of L<Tk::ColorEditor|Tk::ColorEditor>.
-
-The B<chooseColor> method pops up a dialog box for the
-user to select a color. The following I<option-value> pairs are
-possible as command line arguments:
-
-=over 4
-
-=item B<-initialcolor>=E<gt>I<color>
-
-Specifies the color to display in the color dialog when it pops
-up. I<color> must be in a form acceptable to the B<Tk_GetColor>
-function.
-
-=item B<-parent>=E<gt>$widget
-
-Makes $widget the logical parent of the color dialog. The color
-dialog is displayed on top of its parent window.
-
-=item B<-title>=E<gt>I<titleString>
-
-Specifies a string to display as the title of the dialog box. If this
-option is not specified, then a default title will be displayed.
-
-=back
-
-If the user selects a color, B<tk_chooseColor> will return the
-name of the color in a form acceptable to B<Tk_GetColor>. If the
-user cancels the operation, the command will return B<undef>.
-
-=head1 EXAMPLE
-
- $widget->configure(-fg => $parent->chooseColor(-initialcolor => 'gray',
- -title => "Choose color"));
-
-=head1 KEYWORDS
-
-color selection dialog
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/chooseDirectory.pod b/Master/tlpkg/tlperl/lib/Tk/chooseDirectory.pod
deleted file mode 100644
index 8a2edc9d672..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/chooseDirectory.pod
+++ /dev/null
@@ -1,95 +0,0 @@
-# Copyright (c) 1998-2000 by Scriptics Corporation.
-# All rights reserved.
-#
-# RCS: @(#) $Id: chooseDirectory.n,v 1.1 2000/01/27 00:23:10 ericm Exp $
-#
-
-=head1 NAME
-
-chooseDirectory - pops up a dialog box for the user to select a directory.
-
-=for category Tk Generic Methods
-
-=head1 SYNOPSIS
-
-I<$widget>-E<gt>B<chooseDirectory>( ?I<option value ...>? );
-
-=head1 DESCRIPTION
-
-The method B<chooseDirectory> is implemented as a perl wrapper on the
-core tk "command" B<tk_chooseDirectory>, and I<$widget> is passed as
-the argument to the hidden B<-parent> option.
-
-The B<chooseDirectory>
-method pops up a dialog box for the user to select a directory. The
-following I<option-value> pairs are possible as command line
-arguments:
-
-=over 4
-
-=item B<-initialdir> I<dirname>
-
-Specifies that the directories in I<directory> should be displayed
-when the dialog pops up. If this parameter is not specified, then
-the directories in the current working directory are displayed. If the
-parameter specifies a relative path, the return value will convert the
-relative path to an absolute path. This option may not always work on
-the Macintosh. This is not a bug. Rather, the I<General Controls>
-control panel on the Mac allows the end user to override the
-application default directory.
-
-=item B<-parent> $widget
-
-Makes $widget the logical parent of the dialog. The dialog
-is displayed on top of its parent window.
-
-=item B<-title> I<titleString>
-
-Specifies a string to display as the title of the dialog box. If this
-option is not specified, then a default title will be displayed.
-
-=item B<-mustexist> I<boolean>
-
-Specifies whether the user may specify non-existant directories. If
-this parameter is true, then the user may only select directories that
-already exist. The default value is I<false>.
-
-=back
-
-=head1 CAVEATS
-
-Perl does not have a concept of encoded filesystems yet. This means
-that operations on filenames like C<opendir> and C<open> still use
-byte semantics. Tk however uses character semantics internally, which
-means that you can get filenames with the UTF-8 flag set in functions
-like C<chooseDirectory>, C<getOpenFile> and similar. It's the user's
-responsibility to determine the encoding of the underlying filesystem
-and convert the result into bytes, e.g.
-
- use Encode;
- ...
- my $dir = $mw->chooseDirectory;
- $dir = encode("windows-1252", $dir);
- opendir DIR, $dir or die $!;
- ...
-
-See also L<perlunicode/When Unicode Does Not Happen> and
-L<perltodo/Unicode in Filenames>.
-
-=head1 EXAMPLE
-
- my $dir = $mw->chooseDirectory(-initialdir => '~',
- -title => 'Choose a directory');
- if (!defined $dir) {
- warn 'No directory selected';
- } else {
- warn "Selected $dir";
- }
-
-=head1 SEE ALSO
-
-L<Tk::getOpenFile>, L<Tk::getOpenFile>
-
-=head1 KEYWORDS
-
-directory selection dialog
diff --git a/Master/tlpkg/tlperl/lib/Tk/composite.pod b/Master/tlpkg/tlperl/lib/Tk/composite.pod
deleted file mode 100644
index a493b5ee1f2..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/composite.pod
+++ /dev/null
@@ -1,171 +0,0 @@
-# $Id: composite.pod 1.2 Wed, 12 Nov 1997 00:30:45 +0100 ach $
-
-=head1 NAME
-
-Tk::composite - Defining a new composite widget class
-
-=for category Derived Widgets
-
-=head1 SYNOPSIS
-
- package Tk::MyNewWidget;
-
- use Tk:widgets qw/ list of Tk widgets /;
- use base qw/ Tk::Frame /; # or Tk::Toplevel
-
- Construct Tk::Widget 'MyNewWidget';
-
- sub ClassInit {
- my( $class, $mw ) = @_;
- #... e.g., class bindings here ...
- $class->SUPER::ClassInit( $mw );
- }
-
- sub Populate {
- my( $self, $args ) = @_;
-
- my $flag = delete $args->{-flag};
- if( defined $flag ) {
- # handle -flag => xxx which can only be done at create
- # time the delete above ensures that new() does not try
- # and do $self->configure( -flag => xxx );
- }
-
- $self->SUPER::Populate( $args );
-
- $self = $self->Component( ... );
-
- $self->Delegates( ... );
-
- $self->ConfigSpecs(
- '-cursor' => [ SELF, 'cursor', 'Cursor', undef ],
- '-something' => [ METHOD, dbName, dbClass, default ],
- '-text' => [ $label, dbName, dbClass, default ],
- '-heading' => [ {-text => $head},
- heading, Heading, 'My Heading' ],
- );
- }
-
- sub something {
- my( $self, $value) = @_;
- if ( @_ > 1 ) {
- # set it
- }
- return # current value
- }
-
- 1;
-
- __END__
-
-
- =head1 NAME
-
- Tk::Whatever - a whatever widget
-
- =head1 SYNOPSIS
-
- use Tk::Whatever;
-
- $widget = $parent->Whatever(...);
-
- =head1 DESCRIPTION
-
- ...
-
-=head1 DESCRIPTION
-
-The intention behind a composite is to create a higher-level widget,
-sometimes called a "super-widget" or "mega-widget". Most often,
-a composite will be
-built upon other widgets by B<using> them, as opposed to specializing on them.
-For example, the supplied composite widget B<LabEntry> is I<made of> an
-B<Entry> and a B<Label>; it is neither a I<kind-of> B<Label>
-nor is it a I<kind-of> B<Entry>.
-
-Most of the work of a composite widget consistd in creating subwidgets,
-arranging to dispatch configure options to the proper subwidgets and manage
-composite-specific configure options.
-
-=head1 GLORY DETAILS
-
-Depending on your Perl/Tk knowledge this section may be enlighting
-or confusing.
-
-=head2 Composite Widget
-
-Since Perl/Tk is heavilly using an object-oriented approach, it is no
-suprise that creating a composite goes through a B<new()> method.
-However, the composite does not normally define a B<new()> method
-itself: it is usually sufficient to simply inherit it from
-B<Tk::Widget>.
-
-This is what happens when the composite uses
-
- use base qw/ Tk::Frame /; # or Tk::Toplevel
-
-to specify its inheritance chain. To complete the initialisation of the
-widget, it must call the B<Construct> method from class B<Widget>. That
-method accepts the name of the new class to create, i.e. the package name
-of your composite widget:
-
- Construct Tk::Widget 'MyNewWidget';
-
-Here, B<MyNewWidget> is the package name (aka the widget's B<class>). This
-will define a constructor method for B<MyNewWidget>, normally named after the
-widget's class. Instanciating that composite in client code would
-the look like:
-
- $mw = MainWindow->new; # creates a top-level MainWindow
-
- $self = $mw->MyNewWidget(); # creates an instance of the
- # composite widget MyNewWidget
-
-Whenever a composite is instanciated in client code,
-C<Tk::Widget::new()> will be invoked via the widget's class
-constructor. That B<new> method will call
-
- $self->Populate(\%args);
-
-where I<%args> is the arguments passed to the widget's constructor. Note
-that B<Populate> receives a B<reference> to the hash array
-containing all arguments.
-
-B<Populate> is typically defined in the composite class (package),
-which creates the characteristic subwidgets of the class.
-
-=head2 Creating Subwidgets
-
-Subwidget creation happens usually in B<Populate()>.
-The composite usually calls the
-subwidget's constructor method either directly, for "private" subwidgets,
-or indirectly through the B<Component> method for subwidgets that should
-be advertised to clients.
-
-B<Populate> may call B<Delegates> to direct calls to methods
-of chosen subwidgets. For simple composites, typically most if not all
-methods are directed
-to a single subwidget - e.g. B<ScrListbox> directs all methods to the core
-B<Listbox> so that I<$composite>-E<gt>B<get>(...) calls
-I<$listbox>-E<gt>B<get>(...).
-
-=head2 Defining mega-widget options
-
-B<Populate> should also call B<ConfigSpecs()> to specify the
-way that configure-like options should be handled in the composite.
-Once B<Populate> returns, method B<Tk::Frame::ConfigDefault>
-walks through the B<ConfigSpecs> entries and populates
-%$args hash with defaults for options from X resources (F<.Xdefaults>, etc).
-
-When B<Populate> returns to B<Tk::Widget::new()>,
-a call to B<$self>-E<gt>I<configure>(%$args) is made which sets *all*
-the options.
-
-=head1 SEE ALSO
-
-L<Tk::ConfigSpecs|Tk::ConfigSpecs>
-L<Tk::mega|Tk::mega>
-L<Tk::Derived|Tk::Derived>
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/event.pod b/Master/tlpkg/tlperl/lib/Tk/event.pod
deleted file mode 100644
index 9012a596267..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/event.pod
+++ /dev/null
@@ -1,417 +0,0 @@
-# Copyright (c) 1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::event - Miscellaneous event facilities: define virtual events and generate events
-
-=for category Binding Events and Callbacks
-
-=head1 SYNOPSIS
-
-I<$widget>-E<gt>B<event>I<Action>(?I<arg, arg, ...>?);
-
-=head1 DESCRIPTION
-
-The B<event>I<Action> methods provides several facilities for dealing with
-window system events, such as defining virtual events and synthesizing
-events. Virtual events are shared by all widgets of the same
-B<MainWindow>. Different L<MainWindow|Tk::MainWindow>s can have different
-virtual event.
-
-The following methods are currently supported:
-
-=over 4
-
-=item I<$widget>-E<gt>B<eventAdd>(B<'E<lt>E<lt>>I<virtual>B<E<gt>E<gt>'>I<, sequence >?,I<sequence, ...>?)
-
-Associates the virtual event I<virtual> with the physical
-event sequence(s) given by the I<sequence> arguments, so that
-the virtual event will trigger whenever any one of the I<sequence>s
-occurs.
-I<Virtual> may be any string value and I<sequence> may have
-any of the values allowed for the I<sequence> argument to the
-L<bind|Tk::bind> method.
-If I<virtual> is already defined, the new physical event sequences
-add to the existing sequences for the event.
-
-=item I<$widget>-E<gt>B<eventDelete>(B<'E<lt>E<lt>>I<virtual>B<E<gt>E<gt>'> ?,I<sequence,> I<sequence, ...>?)
-
-Deletes each of the I<sequence>s from those associated with
-the virtual event given by I<virtual>.
-I<Virtual> may be any string value and I<sequence> may have
-any of the values allowed for the I<sequence> argument to the
-L<bind|Tk::bind> method.
-Any I<sequence>s not currently associated with I<virtual>
-are ignored.
-If no I<sequence> argument is provided, all physical event sequences
-are removed for I<virtual>, so that the virtual event will not
-trigger anymore.
-
-=item I<$widget>-E<gt>B<eventGenerate>(I<event> ?,I<option =E<gt> value, option =E<gt> value, ...>?)
-
-Generates a window event and arranges for it to be processed just as if
-it had come from the window system.
-I<$window> is a reference to the window for which the event
-will be generated.
-I<Event> provides a basic description of
-the event, such as B<E<lt>Shift-Button-2E<gt>> or B<E<lt>E<lt>PasteE<gt>E<gt>>.
-If I<Window> is empty the whole screen is meant, and coordinates
-are relative to the screen.
-I<Event> may have any of the forms allowed for the I<sequence>
-argument of the L<bind|Tk::bind> method except that it must consist
-of a single event pattern, not a sequence.
-I<Option-value> pairs may be used to specify additional
-attributes of the event, such as the x and y mouse position;
-see L<"EVENT FIELDS"> below. If the B<-when> option is not specified, the
-event is processed immediately: all of the handlers for the event
-will complete before the B<eventGenerate> method returns.
-If the B<-when> option is specified then it determines when the
-event is processed.
-
-=item I<$widget>-E<gt>B<eventInfo>(?'B<E<lt>E<lt>>I<virtual>B<E<gt>E<gt>'>?)
-
-Returns information about virtual events.
-If the B<E<lt>E<lt>>I<virtual>B<E<gt>E<gt>> argument is omitted, the return value
-is a list of all the virtual events that are currently defined.
-If B<E<lt>E<lt>>I<virtual>B<E<gt>E<gt>> is specified then the return value is
-a list whose elements are the physical event sequences currently
-defined for the given virtual event; if the virtual event is
-not defined then B<undef> is returned.
-
-=back
-
-=head1 EVENT FIELDS
-
-The following options are supported for the B<eventGenerate>
-method. These correspond to the ``%'' expansions
-allowed in binding callback for the L<bind|Tk::bind> method.
-
-=over 4
-
-=item B<-above> => I<window>
-
-I<Window> specifies the I<above> field for the event,
-either as a window path name or as an integer window id.
-Valid for B<Configure> events.
-Corresponds to the L<%a|Tk::bind/'a'> substitution for binding scripts.
-
-=item B<-borderwidth> => I<size>
-
-I<Size> must be a screen distance; it specifies the
-I<border_width> field for the event.
-Valid for B<Configure> events.
-Corresponds to the L<%B|Tk::bind/'B'> substitution for binding scripts.
-
-=item B<-button> => I<number>
-
-I<Number> must be an integer; it specifies the I<detail> field
-for a B<ButtonPress> or B<ButtonRelease> event, overriding
-any button number provided in the base I<event> argument.
-Corresponds to the L<%b|Tk::bind/'b'> substitution for binding scripts.
-
-=item B<-count> => I<number>
-
-I<Number> must be an integer; it specifies the I<count> field
-for the event. Valid for B<Expose> events.
-Corresponds to the L<%c|Tk::bind/'c'> substitution for binding scripts.
-
-=item B<-delta> =E<gt> I<number>
-
-B<number> must be an integer; it specifies the B<delta> field for the
-B<MouseWheel> event. The delta refers to the direction and magnitude the
-mouse wheel was rotated. Note the value is not a screen distance but
-are units of motion in the mouse wheel. Typically these values are
-multiples of 120. For example, 120 should scroll the text widget up 4
-lines and -240 would scroll the text widget down 8 lines. Of course,
-other widgets may define different behaviors for mouse wheel motion.
-This field corresponds to the %D substitution for binding scripts.
-
-=item B<-detail> => I<detail>
-
-I<Detail> specifies the I<detail> field for the event
-and must be one of the following:
-
-=over 8
-
- NotifyAncestor NotifyNonlinearVirtual
- NotifyDetailNone NotifyPointer
- NotifyInferior NotifyPointerRoot
- NotifyNonlinear NotifyVirtual
-
-=back
-
-Valid for B<Enter>, B<Leave>, B<FocusIn> and
-B<FocusOut> events.
-Corresponds to the L<%d|Tk::bind/'d'> substitution for binding scripts.
-
-=item B<-focus>I< boolean>
-
-I<Boolean> must be a boolean value; it specifies the I<focus>
-field for the event.
-Valid for B<Enter> and B<Leave> events.
-Corresponds to the L<%f|Tk::bind/'f'> substitution for binding scripts.
-
-=item B<-height>I< size>
-
-I<Size> must be a screen distance; it specifies the I<height>
-field for the event. Valid for B<Configure> events.
-Corresponds to the L<%h|Tk::bind/'h'> substitution for binding scripts.
-
-=item B<-keycode>I< number>
-
-I<Number> must be an integer; it specifies the I<keycode>
-field for the event.
-Valid for B<KeyPress> and B<KeyRelease> events.
-Corresponds to the L<%k|Tk::bind/'k'> substitution for binding scripts.
-
-=item B<-keysym>I< name>
-
-I<Name> must be the name of a valid keysym, such as B<g>,
-B<space>, or B<Return>; its corresponding
-keycode value is used as the I<keycode> field for event, overriding
-any detail specified in the base I<event> argument.
-Valid for B<KeyPress> and B<KeyRelease> events.
-Corresponds to the L<%K|Tk::bind/'K'> substitution for binding scripts.
-
-=item B<-mode>I< notify>
-
-I<Notify> specifies the I<mode> field for the event and must be
-one of B<NotifyNormal>, B<NotifyGrab>, B<NotifyUngrab>, or
-B<NotifyWhileGrabbed>.
-Valid for B<Enter>, B<Leave>, B<FocusIn>, and
-B<FocusOut> events.
-Corresponds to the L<%m|Tk::bind/'m'> substitution for binding scripts.
-
-=item B<-override>I< boolean>
-
-I<Boolean> must be a boolean value; it specifies the
-I<override_redirect> field for the event.
-Valid for B<Map>, B<Reparent>, and B<Configure> events.
-Corresponds to the L<%o|Tk::bind/'o'> substitution for binding scripts.
-
-=item B<-place>I< where>
-
-I<Where> specifies the I<place> field for the event; it must be
-either B<PlaceOnTop> or B<PlaceOnBottom>.
-Valid for B<Circulate> events.
-Corresponds to the L<%p|Tk::bind/'p'> substitution for binding scripts.
-
-=item B<-root>I< window>
-
-I<Window> must be either a window path name or an integer window
-identifier; it specifies the I<root> field for the event.
-Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
-B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion>
-events.
-Corresponds to the L<%R|Tk::bind/'R'> substitution for binding scripts.
-
-=item B<-rootx>I< coord>
-
-I<Coord> must be a screen distance; it specifies the I<x_root>
-field for the event.
-Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
-B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion>
-events. Corresponds to the L<%X|Tk::bind/'X'> substitution for binding scripts.
-
-=item B<-rooty>I< coord>
-
-I<Coord> must be a screen distance; it specifies the I<y_root>
-field for the event.
-Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
-B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion>
-events.
-Corresponds to the L<%Y|Tk::bind/'Y'> substitution for binding scripts.
-
-=item B<-sendevent>I< boolean>
-
-B<Boolean> must be a boolean value; it specifies the I<send_event>
-field for the event. Valid for all events. Corresponds to the
-L<%E|Tk::bind/'E'> substitution for binding scripts.
-
-=item B<-serial>I< number>
-
-I<Number> must be an integer; it specifies the I<serial> field
-for the event. Valid for all events.
-Corresponds to the L<%#|Tk::bind/'#'> substitution for binding scripts.
-
-=item B<-state>I< state>
-
-I<State> specifies the I<state> field for the event.
-For B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
-B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> events
-it must be an integer value.
-For B<Visibility> events it must be one of B<VisibilityUnobscured>,
-B<VisibilityPartiallyObscured>, or B<VisibilityFullyObscured>.
-This option overrides any modifiers such as B<Meta> or B<Control>
-specified in the base I<event>.
-Corresponds to the L<%s|Tk::bind/'s'> substitution for binding scripts.
-
-=item B<-subwindow>I< window>
-
-I<Window> specifies the I<subwindow> field for the event, either
-as a path name for a Tk widget or as an integer window identifier.
-Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
-B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> events.
-Similar to L<%S|Tk::bind/'S'> substitution for binding scripts.
-
-=item B<-time>I< integer>
-
-I<Integer> must be an integer value; it specifies the I<time> field
-for the event.
-Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
-B<ButtonRelease>, B<Enter>, B<Leave>, B<Motion>,
-and B<Property> events.
-Corresponds to the L<%t|Tk::bind/'t'> substitution for binding scripts.
-
-
-=item B<-warp>I< boolean>
-
-I<boolean> must be a boolean value; it specifies whether
-the screen pointer should be warped as well.
-Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
-B<ButtonRelease>, and B<Motion> events.
-
-=item B<-width>I< size>
-
-I<Size> must be a screen distance; it specifies the I<width> field
-for the event.
-Valid for B<Configure> events.
-Corresponds to the L<%w|Tk::bind/'w'> substitution for binding scripts.
-
-=item B<-when>I< when>
-
-I<When> determines when the event will be processed; it must have one
-of the following values:
-
-=over 8
-
-=item B<now>
-
-Process the event immediately, before the command returns.
-This also happens if the B<-when> option is omitted.
-
-=item B<tail>
-
-Place the event on perl/Tk's event queue behind any events already
-queued for this application.
-
-=item B<head>
-
-Place the event at the front of perl/Tk's event queue, so that it
-will be handled before any other events already queued.
-
-=item B<mark>
-
-Place the event at the front of perl/Tk's event queue but behind any
-other events already queued with B<-when mark>.
-This option is useful when generating a series of events that should
-be processed in order but at the front of the queue.
-
-=back
-
-=item B<-x>I< coord>
-
-I<Coord> must be a screen distance; it specifies the I<x> field
-for the event.
-Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
-B<ButtonRelease>, B<Motion>, B<Enter>, B<Leave>,
-B<Expose>, B<Configure>, B<Gravity>, and B<Reparent>
-events.
-Corresponds to the the L<%x|Tk::bind/'x'> substitution for binding scripts.
-If I<Window> is empty the coordinate is relative to the
-screen, and this option corresponds to the L<%X|Tk::bind/'X'> substitution
-for binding scripts.
-
-=item B<-y>I< coord>
-
-I<Coord> must be a screen distance; it specifies the I<y>
-field for the event.
-Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
-B<ButtonRelease>, B<Motion>, B<Enter>, B<Leave>,
-B<Expose>, B<Configure>, B<Gravity>, and B<Reparent>
-events.
-Corresponds to the the L<%y|Tk::bind/'y'> substitution for binding scripts.
-If I<Window> is empty the coordinate is relative to the
-screen, and this option corresponds to the L<%Y|Tk::bind/'Y'> substitution
-for binding scripts.
-
-Any options that are not specified when generating an event are filled
-with the value 0, except for I<serial>, which is filled with the
-next X event serial number.
-
-=back
-
-=head1 VIRTUAL EVENT EXAMPLES
-
-In order for a virtual event binding to trigger, two things must
-happen. First, the virtual event must be defined with the
-B<eventAdd> method. Second, a binding must be created for
-the virtual event with the B<bind> method.
-Consider the following virtual event definitions:
-
- $widget->eventAdd('<<Paste>>' => '<Control-y>');
- $widget->eventAdd('<<Paste>>' => '<Button-2>');
- $widget->eventAdd('<<Save>>' => '<Control-X><Control-S>');
- $widget->eventAdd('<<Save>>' => '<Shift-F12>');
-
-In the B<bind> method, a virtual event can be bound like any other
-builtin event type as follows:
-
- $entry->bind('Tk::Entry', '<<Paste>>' => sub {
- $entry->Insert($entry->selectionGet) });
-
-The double angle brackets are used to specify that a virtual event is being
-bound. If the user types Control-y or presses button 2, or if
-a B<E<lt>E<lt>PasteE<gt>E<gt>> virtual event is synthesized with B<eventGenerate>,
-then the B<E<lt>E<lt>PasteE<gt>E<gt>> binding will be invoked.
-
-If a virtual binding has the exact same sequence as a separate
-physical binding, then the physical binding will take precedence.
-Consider the following example:
-
- $mw->eventAdd('<<Paste>>' => '<Control-y>','<Meta-Control-y>');
- $mw->bind('Tk::Entry', '<Control-y>' => sub{print 'Control-y'});
- $mw->bind('Tk::Entry', '<<Paste>>' => sub{print 'Paste'});
-
-When the user types Control-y the B<E<lt>Control-yE<gt>> binding
-will be invoked, because a physical event is considered
-more specific than a virtual event, all other things being equal.
-However, when the user types Meta-Control-y the
-B<E<lt>E<lt>PasteE<gt>E<gt>> binding will be invoked, because the
-B<Meta> modifier in the physical pattern associated with the
-virtual binding is more specific than the B<E<lt>Control-y>E<gt> sequence for
-the physical event.
-
-Bindings on a virtual event may be created before the virtual event exists.
-Indeed, the virtual event never actually needs to be defined, for instance,
-on platforms where the specific virtual event would meaningless or
-ungeneratable.
-
-When a definition of a virtual event changes at run time, all windows
-will respond immediately to the new definition.
-Starting from the preceding example, if the following code is executed:
-
- $entry->bind(ref($entry), '<Control-y>' => undef);
- $entry->eventAdd('<<Paste>>' => '<Key-F6>');
-
-the behavior will change such in two ways. First, the shadowed
-B<E<lt>E<lt>PasteE<gt>E<gt>> binding will emerge.
-Typing Control-y will no longer invoke the B<E<lt>Control-yE<gt>> binding,
-but instead invoke the virtual event B<E<lt>E<lt>PasteE<gt>E<gt>>. Second,
-pressing the F6 key will now also invoke the B<E<lt>E<lt>PasteE<gt>E<gt>> binding.
-
-=head1 SEE ALSO
-
-L<Tk::bind|Tk::bind>
-L<Tk::callbacks|Tk::callbacks>
-
-=head1 KEYWORDS
-
-event, binding, define, handle, virtual event
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/exit.pod b/Master/tlpkg/tlperl/lib/Tk/exit.pod
deleted file mode 100644
index bb564cd0b82..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/exit.pod
+++ /dev/null
@@ -1,42 +0,0 @@
-# Copyright (c) 1993 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::exit - End the application
-
-=for category Binding Events and Callbacks
-
-=head1 SYNOPSIS
-
- use Tk qw(exit);
- ...
- B<exit>?(I<returnCode>)?;
-
-=head1 DESCRIPTION
-
-Terminate the process, returning I<returnCode> to the
-system as the exit status.
-If I<returnCode> isn't specified then it defaults
-to 0.
-
-If calling C<exit> from code invoked via a Tk callback then
-this Tk version of C<exit> cleans up more reliably than using
-the perl C<exit>.
-
-=head1 CAVEATS
-
-Using C<exit> from a forked process will terminate both the child
-process B<and> the parent process. As C<Tk::exit> is imported by
-default one should use C<CORE::exit> in the forked process instead.
-
-=head1 KEYWORDS
-
-exit, process
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/fileevent.pod b/Master/tlpkg/tlperl/lib/Tk/fileevent.pod
deleted file mode 100644
index 1a98cfd6b71..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/fileevent.pod
+++ /dev/null
@@ -1,112 +0,0 @@
-# Copyright (c) 1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::fileevent - Execute a callback when a filehandle becomes readable or writable
-
-=for category Binding Events and Callbacks
-
-=head1 SYNOPSIS
-
-I<$widget>-E<gt>B<fileevent>(I<fileHandle>,B<readable>?,I<callback>?)
-
-I<$widget>-E<gt>B<fileevent>(I<fileHandle>,B<writable>?,I<callback>?)
-
-=head1 DESCRIPTION
-
-This command is used to create I<file event handlers>. A file event
-handler is a binding between a filehandle and a callback, such that the callback
-is evaluated whenever the filehandle becomes readable or writable. File event
-handlers are most commonly used to allow data to be received from another
-process on an event-driven basis, so that the receiver can continue to
-interact with the user while waiting for the data to arrive. If an
-application invokes C<E<lt>E<gt>>, C<sysread> or C<read> on a blocking filehandle when
-there is no input data available, the process will block; until the input
-data arrives, it will not be able to service other events, so it will
-appear to the user to ``freeze up''. With B<fileevent>, the process can
-tell when data is present and only invoke B<gets> or B<read> when
-they won't block.
-
-The I<fileHandle> argument to B<fileevent> refers to an open filehandle,
-such as the return value from a previous B<open> or B<socket>
-command.
-If the I<callback> argument is specified, then B<fileevent>
-creates a new event handler: I<callback> will be evaluated
-whenever the filehandle becomes readable or writable (depending on the
-argument to B<fileevent>).
-In this case B<fileevent> returns an empty string.
-The B<readable> and B<writable> event handlers for a file
-are independent, and may be created and deleted separately.
-However, there may be at most one B<readable> and one B<writable>
-handler for a file at a given time in a given interpreter.
-If B<fileevent> is called when the specified handler already
-exists in the invoking interpreter, the new callback replaces the old one.
-
-If the I<callback> argument is not specified, B<fileevent>
-returns the current callback for I<fileHandle>, or an empty string
-if there is none.
-If the I<callback> argument is specified as an empty string
-then the event handler is deleted, so that no callback will be invoked.
-A file event handler is also deleted automatically whenever
-its filehandle is closed or its interpreter is deleted.
-
-A filehandle is considered to be readable if there is unread data
-available on the underlying device.
-A filehandle is also considered to be readable if an end of file or
-error condition is present on the underlying file or device.
-It is important for I<callback> to check for these conditions
-and handle them appropriately; for example, if there is no special
-check for end of file, an infinite loop may occur where I<callback>
-reads no data, returns, and is immediately invoked again.
-
-A filehandle is considered to be writable if at least one byte of data
-can be written to the underlying file or device without blocking,
-or if an error condition is present on the underlying file or device.
-
-Event-driven I/O works best for filehandles that have been
-placed into nonblocking mode.
-In blocking mode, a C<print> command may block if you give it
-more data than the underlying file or device can accept, and a
-C<E<lt>E<gt>>, C<sysread> or C<read> command will block if you attempt to read
-more data than is ready; no events will be processed while the
-commands block.
-In nonblocking mode C<print>, C<E<lt>E<gt>>, C<sysread> and C<read> never block.
-See the documentation for the individual commands for information
-on how they handle blocking and nonblocking filehandles.
-
-The callback for a file event is executed in the context of I<$widget>
-with which B<fileevent> was invoked.
-If an error occurs while executing the callback then the
-L<Tk::Error> mechanism is used to report the error.
-In addition, the file event handler is deleted if it ever returns
-an error; this is done in order to prevent infinite loops due to
-buggy handlers.
-
-=head1 BUGS
-
-On windows platforms B<fileevent> is limited in the types of filehandles
-that behave correctly. Making filefhandles non-blocking is only implemented
-on a subset of UNIX platforms (see L<Tk::IO>).
-
-=head1 CREDITS
-
-B<fileevent> is based on the B<addinput> command created
-by Mark Diekhans.
-
-=head1 SEE ALSO
-
-L<Tk::IO|Tk::IO>
-L<Tk::callbacks|Tk::callbacks>
-
-=head1 KEYWORDS
-
-asynchronous I/O, blocking, filehandle, event handler, nonblocking, readable,
-callback, writable.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/focus.pod b/Master/tlpkg/tlperl/lib/Tk/focus.pod
deleted file mode 100644
index 61dab55b277..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/focus.pod
+++ /dev/null
@@ -1,166 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-focus - Manage the input focus
-
-=for category User Interaction
-
-=head1 SYNOPSIS
-
-S< >I<$widget>-E<gt>B<focus>
-
-S< >I<$widget>-E<gt>B<focus>I<Option>
-
-S< >I<$widget>-E<gt>B<focusNext>
-
-S< >I<$widget>-E<gt>B<focusPrev>
-
-S< >I<$widget>-E<gt>B<focusFollowsMouse>
-
-=head1 DESCRIPTION
-
-The B<focus> methods are used to manage the Tk input focus.
-At any given time, one window on each display is designated as
-the I<focus window>; any key press or key release events for the
-display are sent to that window.
-It is normally up to the window manager to redirect the focus among the
-top-level windows of a display. For example, some window managers
-automatically set the input focus to a top-level window whenever
-the mouse enters it; others redirect the input focus only when
-the user clicks on a window.
-Usually the window manager will set the focus
-only to top-level windows, leaving it up to the application to
-redirect the focus among the children of the top-level.
-
-Tk remembers one focus window for each top-level (the most recent
-descendant of that top-level to receive the focus); when the window
-manager gives the focus
-to a top-level, Tk automatically redirects it to the remembered
-window. Within a top-level Tk uses an I<explicit> focus model
-by default. Moving the mouse within a top-level does not normally
-change the focus; the focus changes only when a widget
-decides explicitly to claim the focus (e.g., because of a button
-click), or when the user types a key such as Tab that moves the
-focus.
-
-The method B<focusFollowsMouse> may be invoked to
-create an I<implicit> focus model: it reconfigures Tk so that
-the focus is set to a window whenever the mouse enters it.
-The methods B<focusNext> and B<focusPrev>
-implement a focus order among the windows of a top-level; they
-are used in the default bindings for Tab and Shift-Tab, among other
-things.
-
-The B<focus> methods can take any of the following forms:
-
-=over 4
-
-=item I<$widget>-E<gt>B<focusCurrent>
-
-Returns the focus window on the display containing
-the I<$widget>, or an empty string if no window in
-this application has the focus on that display.
-
-=item I<$widget>-E<gt>B<focus>
-
-If the application currently has the input focus on I<$widget>'s
-display, this command resets the input focus for I<$widget>'s display
-to I<$widget> and returns an empty string.
-If the application doesn't currently have the input focus on
-I<$widget>'s display, I<$widget> will be remembered as the focus
-for its top-level; the next time the focus arrives at the top-level,
-Tk will redirect it to I<$widget>.
-
-=item I<$widget>-E<gt>B<focusForce>
-
-Sets the focus of I<$widget>'s display to I<$widget>, even if
-the application doesn't currently have the input focus for the display.
-This command should be used sparingly, if at all.
-In normal usage, an application should not claim the focus for
-itself; instead, it should wait for the window manager to give it
-the focus.
-
-=item I<$widget>-E<gt>B<focusLastfor>
-
-Returns the name of the most recent window to have the input focus
-among all the windows in the same top-level as I<$widget>.
-If no window in that top-level has ever had the input focus, or
-if the most recent focus window has been deleted, then
-the top-level is returned. The return value is the window that
-will receive the input focus the next time the window manager gives
-the focus to the top-level.
-
-=item I<$widget>-E<gt>B<focusNext>
-
-=item I<$widget>-E<gt>B<focusPrev>
-
-B<focusNext> is a utility method used for keyboard traversal, but can be
-useful in other contexts.
-It sets the focus to the ``next'' window after I<$widget> in focus order.
-The focus order is determined by
-the stacking order of windows and the structure of the window hierarchy.
-Among siblings, the focus order is the same as the stacking order, with the
-lowest window being first.
-If a window has children, the window is visited first, followed by
-its children (recursively), followed by its next sibling.
-Top-level windows other than I<$widget> are skipped, so that
-B<focusNext> never returns a window in a different top-level
-from I<$widget>.
-
-After computing the next window, B<focusNext> examines the
-window's B<-takefocus> option to see whether it should be skipped.
-If so, B<focusNext> continues on to the next window in the focus
-order, until it eventually finds a window that will accept the focus
-or returns back to I<$widget>.
-
-B<focusPrev> is similar to B<focusNext> except that it
-sets the focus to the window just before I<$widget> in the focus order.
-
-=item I<$widget>-E<gt>B<focusFollowsMouse>
-
-B<focusFollowsMouse> changes the focus model for the application
-to an implicit one where the window under the mouse gets the focus.
-After this procedure is called, whenever the mouse enters a window
-Tk will automatically give it the input focus.
-The B<focus> command may be used to move the focus to a window
-other than the one under the mouse, but as soon as the mouse moves
-into a new window the focus will jump to that window.
-Note: at present there is no built-in support for returning the
-application to an explicit focus model; to do this you'll have
-to write a script that deletes the bindings created by
-B<focusFollowsMouse>.
-
-=back
-
-=head1 QUIRKS
-
-When an internal window receives the input focus, Tk doesn't actually
-set the X focus to that window; as far as X is concerned, the focus
-will stay on the top-level window containing the window with the focus.
-However, Tk generates FocusIn and FocusOut events just as if the X
-focus were on the internal window. This approach gets around a
-number of problems that would occur if the X focus were actually moved;
-the fact that the X focus is on the top-level is invisible unless
-you use C code to query the X server directly.
-
-=head1 CAVEATS
-
-Note that for the B<Canvas> widget, the call to B<focus> has to be
-fully qualified. This is because there is already a focus method for
-the B<Canvas> widget, which sets the focus on individual canvas tags.
-
-S< >I<$canvas>-E<gt>B<Tk::focus>
-
-
-=head1 KEYWORDS
-
-events, focus, keyboard, top-level, window manager
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/form.pod b/Master/tlpkg/tlperl/lib/Tk/form.pod
deleted file mode 100644
index 64208c8e26e..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/form.pod
+++ /dev/null
@@ -1,397 +0,0 @@
-# Copyright (c) 1996, Expert Interface Technologies
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-# The file man.macros and some of the macros used by this file are
-# copyrighted: (c) 1990 The Regents of the University of California.
-# (c) 1994-1995 Sun Microsystems, Inc.
-# The license terms of the Tcl/Tk distribution are in the file
-# license.tcl.
-
-=head1 NAME
-
-Tk::form - Geometry manager based on attachment rules
-
-=for category Tk Geometry Management
-
-=head1 SYNOPSIS
-
-S< >I<$widget>->B<form>?(I<args>)?
-
-S< >I<$widget>->B<form>I<Option>?(I<args>)?
-
-=head1 DESCRIPTION
-
-The B<form> method is used to communicate with the
-B<form> Geometry Manager, a geometry manager that arranges the
-geometry of the children in a parent window according to attachment
-rules. The B<form> geometry manager is very flexible and
-powerful; it can be used to emulate all the existing features of the
-Tk packer and placer geometry managers (see L<pack|Tk::pack>,
-L<place|Tk::place>).
-The B<form> method can have any of several forms,
-depending on I<Option>:
-
-=over 4
-
-=item I<$slave>->B<form>?(I<options>)?
-
-Sets or adjusts the attachment values of the slave window
-according to the I<-option>=>I<value> argument pairs.
-
-=over 8
-
-=item B<-b> => I<attachment>
-
-Abbreviation for the B<-bottom> option.
-
-=item B<-bottom> => I<attachment>
-
-Specifies an attachment for the bottom edge of the slave window. The
-attachment must specified according to L<"SPECIFYING ATTACHMENTS"> below.
-
-=item B<-bottomspring> => I<weight>
-
-Specifies the weight of the spring at the bottom edge of the slave
-window. See L<"USING SPRINGS"> below.
-
-=item B<-bp> => I<value>
-
-Abbreviation for the B<-padbottom> option.
-
-=item B<-bs> => I<weight>
-
-Abbreviation for the B<-bottomspring> option.
-
-=item B<-fill> => I<style>
-
-Specifies the fillings when springs are used for this widget. The
-value must be B<x>, B<y>, B<both> or B<none>.
-
-=item B<-in> => I<$master>
-
-Places the slave window into the specified I<$master> window. If the slave
-was originally in another master window, all attachment values with
-respect to the original master window are discarded. Even if the
-attachment values are the same as in the original master window, they
-need to be specified again. The B<-in> flag, when needed, must appear
-as the first flag of I<options>. Otherwise an error is
-generated.
-
-=item B<-l> => I<attachment>
-
-Abbreviation for the B<-left> option.
-
-=item B<-left> => I<attachment>
-
-Specifies an attachment for the left edge of the slave window. The
-attachment must specified according to L<"SPECIFYING ATTACHMENTS"> below.
-
-=item B<-leftspring> => I<weight>
-
-Specifies the weight of the spring at the left edge of the slave
-window. See L<"USING SPRINGS"> below.
-
-=item B<-lp> => I<value>
-
-Abbreviation for the B<-padleft> option.
-
-=item B<-ls> => I<weight>
-
-Abbreviation for the B<-leftspring> option.
-
-=item B<-padbottom> => I<value>
-
-Specifies the amount of external padding to leave on the bottom side
-of the slave. The I<value> may have any of the forms acceptable to
-B<Tk_GetPixels>.
-
-=item B<-padleft> => I<value>
-
-Specifies the amount of external padding to leave on the left side of
-the slave.
-
-=item B<-padright> => I<value>
-
-Specifies the amount of external padding to leave on the right side of
-the slave.
-
-=item B<-padtop> => I<value>
-
-Specifies the amount of external padding to leave on the top side of
-the slave.
-
-=item B<-padx> => I<value>
-
-Specifies the amount of external padding to leave on both the left and
-the right sides of the slave.
-
-=item B<-pady> => I<value>
-
-Specifies the amount of external padding to leave on both the top and
-the bottom sides of the slave.
-
-=item B<-r> => I<attachment>
-
-Abbreviation for the B<-right> option.
-
-=item B<-right> => I<attachment>
-
-Specifies an attachment for the right edge of the slave window. The
-attachment must specified according to L<"SPECIFYING ATTACHMENTS"> below.
-
-=item B<-rightspring> => I<weight>
-
-Specifies the weight of the spring at the right edge of the slave
-window. See L<"USING SPRINGS"> below.
-
-=item B<-rp> => I<value>
-
-Abbreviation for the B<-padright> option.
-
-=item B<-rs> => I<weight>
-
-Abbreviation for the B<-rightspring> option.
-
-=item B<-t> => I<attachment>
-
-Abbreviation for the B<-top> option.
-
-=item B<-top> => I<attachment>
-
-Specifies an attachment for the top edge of the slave window. The
-attachment must specified according to L<"SPECIFYING ATTACHMENTS"> below.
-
-=item B<-topspring> => I<weight>
-
-Specifies the weight of the spring at the top edge of the slave
-window. See L<"USING SPRINGS"> below.
-
-=item B<-tp> => I<value>
-
-Abbreviation for the B<-padtop> option.
-
-=item B<-ts> => I<weight>
-
-Abbreviation for the B<-topspring> option.
-
-=back
-
-=item I<$master>->B<formCheck>
-
-This method checks whether there is circular dependency in the
-attachments of the master's slaves (see L<"CIRCULAR DEPENDENCY"> below).
-It returns the Boolean value B<TRUE> if it
-discover circular dependency and B<FALSE> otherwise.
-
-=item I<$slave>->B<formForget>
-
-Removes the slave from its master and unmaps its window.
-The slave will no longer be managed by form. All attachment values
-with respect to its master window are discarded. If another slave
-is attached to this slave, then the attachment of the other slave will
-be changed to grid attachment based on its geometry.
-
-=item I<$master>->B<formGrid>?(I<x_size, y_size>)?
-
-When I<x_size> and I<y_size> are given, this method returns the
-number of grids of the I<$master> window in a pair of integers of the form
-(I<x_size, y_size>). When both I<x_size> and I<y_size> are
-given, this method changes the number of horizontal and vertical
-grids on the master window.
-
-=item I<$slave>->B<formInfo>?(I<-option)>?
-
-Queries the attachment options of a slave window. I<-option> can be
-any of the options accepted by the B<form> method. If
-I<-option> is given, only the value of that option is returned.
-Otherwise, this method returns a list whose elements are the current
-configuration state of the slave given in the same I<option-value> form
-that might be specified to B<form>. The first two
-elements in this list list are "B<-in>=>I<$master>" where
-I<$master> is the slave's master window.
-
-=item I<$master>->B<formSlaves>
-
-Returns a list of all of the slaves for the master window. The order
-of the slaves in the list is the same as their order in the packing
-order. If master has no slaves then an empty string is returned.
-
-=back
-
-=head1 SPECIFYING ATTACHMENTS
-
-One can specify an attachment for each side of a slave window managed
-by form. An attachment is specified in the the form "-I<side> =>
-[I<anchor_point>, I<offset>]". -I<side> can be one of
-B<-top>, B<-bottom>, B<-left> or B<-right>.
-
-I<Offset> is given in screen units (i.e. any of the forms
-acceptable to B<Tk_GetPixels>). A positive offset indicates
-shifting to a position to the right or bottom of an anchor point. A
-negative offset indicates shifting to a position to the left or top of
-an anchor point.
-
-I<Anchor_point> can be given in one of the
-following forms:
-
-=over 4
-
-=item B<Grid Attachment>
-
-The master window is divided into a number of horizontal and vertical
-grids. By default the master window is divided into 100x100 grids; the
-number of grids can be adjusted by the B<formGrid> method. A
-grid attachment anchor point is given by a B<%> sign followed by an
-integer value. For example, B<'%0'> specifies the first grid
-line (the top or left edge of the master window). B<'%100'> specifies
-the last grid line (the bottom or right edge of the master window).
-
-=item B<Opposite Side Attachment>
-
-Opposite attachment specifies an anchor point located on the
-B<opposite> side of another slave widget, which must be managed by
-form in the same master window. An opposite attachment anchor point
-is given by the name of another widget. For example,
-"I<$b>->B<form>(B<-top>=>[I<$a>,0])" attaches the top side of the widget I<$b> to the
-bottom of the widget I<$a>.
-
-=item B<Parallel Side Attachment>
-
-Opposite attachment specifies an anchor point located on the
-B<same> side of another slave widget, which must be managed by
-form in the same master window. An parallel attachment anchor point
-is given by the sign B<E<amp>> follwed by the name of another widget.
-For example, "I<$b>->B<form>(B<-top>=>['&',I<$a>,0])" attaches the top side of
-the widget I<$b> to the top of the widget I<$a>, making
-the top sides of these two widgets at the same vertical position
-in their parent window.
-
-=item B<No Attachment>
-
-Specifies a side of the slave to be attached to nothing, indicated by
-the keyword B<none>. When the B<none> anchor point is given, the
-offset must be zero (or not present).
-When a side of a slave is attached to B<['none', 0]>, the position
-of this side is calculated by the position of the other side and the
-natural size of the slave. For example, if a the left side of a
-widget is attached to B<['%0', 100]>, its right side attached to
-B<['none', 0]>, and the natural size of the widget is B<50> pixels,
-the right side of the widget will be positioned at pixel
-B<['%0', 149]>.
-When both B<-top> and B<-bottom> are attached to B<none>,
-then by default B<-top> will be attached to B<['%0', 0]>. When both
-B<-left> and B<-right> are attached to none, then by default
-B<-left> will be attached to B<['%0', 0]>.
-
-=back
-
-Shifting effects can be achieved by specifying a non-zero offset with
-an anchor point. In the following example, the top side of
-widget I<\$b> is attached to the bottom of
-I<\$a>; hence I<\$b>
-always appears below I<\$a>. Also, the left edge of I<\$b>
-is attached to the left side of I<\$a> with a 10
-pixel offest. Therefore, the left edge of I<\$b> is always
-shifted 10 pixels to the right of I<\$a>'s left edge:
-
-S< >I<$b>->B<form>(B<-left>=>[I<$a>,10], B<-top>=>[I<$a>,0]);
-
-=head2 ABBREVIATIONS:
-
-Certain abbreviations can be made on the
-attachment specifications: First an offset of zero can be omitted.
-Thus, the following two lines are equivalent:
-
-S< >I<$b>->B<form>(B<-top>=>[I<$a>,0], B<-right>=>['%100',0]);
-
-S< >I<$b>->B<form>(B<-top>=>[I<$a>], B<-right>=>'%100');
-
-In the second case, when the anchor point is omitted, the offset must
-be given. A default anchor point is chosen according to the value of
-the offset. If the anchor point is B<0> or positive, the default
-anchor point %0 is used; thus, "I<$b>->B<form>(B<-top>=>15)" attaches the top
-edge of I<$b> to a position 15 pixels below the top edge of the
-master window. If the anchor point is "B<-0>" or negative, the
-default anchor point B<%100> is used; thus, "I<$a>->B<form>(B<-right>=>-2)"
-attaches the right edge of I<\$a> to a position 2 pixels to
-the left of the master window's right edge. An further example
-below shows a method with its equivalent abbreviation.
-
-S< >I<$b>->B<form>(B<-top>=>['%0',10], B<-bottom>=>['%100',0]);
-
-S< >I<$b>->B<form>(B<-top>=>10, B<-bottom>=>-0);
-
-=head1 USING SPRINGS
-
-To be written.
-
-=head1 ALGORITHM OF FORM
-
-B<form> starts with any slave in the list of slaves of the master
-window. Then it tries to determine the position of each side of the
-slave.
-
-If the attachment of a side of the slave is grid attachment, the
-position of the side is readily determined.
-
-If the attachment of this side is B<none>, then form tries to
-determine the position of the opposite side first, and then use the
-position of the opposite side and the natural size of the slave to
-determine the position of this side.
-
-If the attachment is opposite or parallel widget attachments, then
-form tries to determine the positions of the other widget first,
-and then use the positions of the other widget and the natural size of
-the slave determine the position of this side. This recursive
-algorithmis carried on until the positions of all slaves are
-determined.
-
-=head1 CIRCULAR DEPENDENCY
-
-The algorithm of form will fail if a circular dependency exists in
-the attachments of the slaves. For example:
-
-S< >I<$c>->B<form>(B<-left>=>I<$b>);
-
-S< >I<$b>->B<form>(B<-right>=>I<$c>);
-
-In this example, the position of the left side of I<$b> depends on
-the right side of I<$c>, which in turn depends on the left side of I<$b>.
-
-When a circular dependency is discovered during the execution of the
-form algorithm, form will generate a background error and the
-geometry of the slaves are undefined (and will be arbitrary). Notice
-that form only executes the algorithm when the specification of the
-slaves' attachments is complete. Therefore, it allows intermediate
-states of circular dependency during the specification of the slaves'
-attachments. Also, unlike the Motif Form manager widget, form
-defines circular dependency as
-``I<dependency in the same dimension>''.
-Therefore, the following code fragment will does not
-have circular dependency because the two widgets do not depend on each
-other in the same dimension (I<$b> depends I<$c> in the
-horizontal dimension and I<$c> depends on I<$b> in the vertical
-dimension):
-
-S< >I<$b>->B<form>(B<-left>=>I<$c>);
-
-S< >I<$c>->B<form>(B<-top>=>I<$b>);
-
-=head1 BUGS
-
-Springs have not been fully implemented yet.
-
-=head1 SEE ALSO
-
-L<Tk::grid|Tk::grid>
-L<Tk::pack|Tk::pack>
-L<Tk::place|Tk::place>
-
-=head1 KEYWORDS
-
-geometry manager, form, attachment, spring, propagation, size, pack,
-tix, master, slave
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod b/Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod
deleted file mode 100644
index 56d39422afd..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod
+++ /dev/null
@@ -1,182 +0,0 @@
-# Copyright (c) 1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-
-=head1 NAME
-
-getOpenFile, getSaveFile - pop up a dialog box for the user to select a file to open or save.
-
-=for category Popups and Dialogs
-
-=head1 SYNOPSIS
-
-S< >I<$widget>-E<gt>B<getOpenFile>(?I<-option>=E<gt>value, ...>?)
-
-S< >I<$widget>-E<gt>B<getSaveFile>(?I<-option>=E<gt>value, ...>?)
-
-=head1 DESCRIPTION
-
-The methods B<getOpenFile> and B<getSaveFile> pop up a
-dialog box for the user to select a file to open or save.
-
-The B<getOpenFile> method is usually associated with the B<Open>
-command in the B<File> menu. Its purpose is for the user to select an
-existing file I<only>. If the user enters an non-existent file, the
-dialog box gives the user an error prompt and requires the user to give
-an alternative selection. If an application allows the user to create
-new files, it should do so by providing a separate B<New> menu command.
-
-The B<getSaveFile> method is usually associated with the B<Save>
-as command in the B<File> menu. If the user enters a file that
-already exists, the dialog box prompts the user for confirmation
-whether the existing file should be overwritten or not.
-
-If the user selects a file, both B<getOpenFile> and
-B<getSaveFile> return the full pathname of this file. If the
-user cancels the operation, both commands return an undefined value.
-
-The following I<option-value> pairs are possible as command line
-arguments to these two commands:
-
-=over 4
-
-=item B<-defaultextension> =E<gt> I<extension>
-
-Specifies a string that will be appended to the filename if the user
-enters a filename without an extension. The default value is the empty
-string, which means no extension will be appended to the filename in
-any case. This option is ignored on the Macintosh platform, which
-does not require extensions to filenames, and the UNIX implementation
-guesses reasonable values for this from the B<-filetypes>
-option when this is not supplied.
-
-=item B<-filetypes> =E<gt> [I<filePattern> ?, ...?]
-
-If a B<File types> listbox exists in the file dialog on the particular
-platform, this option gives the I<filetype>s in this listbox. When
-the user choose a filetype in the listbox, only the files of that type
-are listed. If this option is unspecified, or if it is set to the
-empty list, or if the B<File types> listbox is not supported by the
-particular platform then all files are listed regardless of their
-types. See L<"SPECIFYING FILE PATTERNS"> below for a
-discussion on the contents of I<filePattern>s.
-
-=item B<-initialdir> =E<gt> I<directory>
-
-Specifies that the files in I<directory> should be displayed
-when the dialog pops up. If this parameter is not specified, then
-the files in the current working directory are displayed. This
-option may not always work on the Macintosh. This is not a bug.
-Rather, the I<General Controls> control panel on the Mac allows the
-end user to override the application default directory.
-
-=item B<-initialfile> =E<gt> I<filename>
-
-Specifies a filename to be displayed in the dialog when it pops
-up. This option is ignored by the B<getOpenFile> method.
-
-=item B<-multiple>
-
-Allows the user to choose multiple files from the Open dialog. On the
-Macintosh, this is only available when Navigation Services are
-installed.
-
-=item B<-message> =E<gt> I<string>
-
-Specifies a message to include in the client area of the dialog. This
-is only available on the Macintosh, and only when Navigation Services
-are installed.
-
-=item B<-title> =E<gt> I<titleString>
-
-Specifies a string to display as the title of the dialog box. If this
-option is not specified, then a default title is displayed. This
-option is ignored on the Macintosh platform.
-
-=back
-
-=head1 SPECIFYING FILE PATTERNS
-
-The I<filePattern>s given by the B<-filetypes> option
-are a list of file patterns. Each file pattern is a list of the
-form
-
- typeName [extension ?extension ...?] ?[macType ?macType ...?]?
-
-I<typeName> is the name of the file type described by this
-file pattern and is the text string that appears in the B<File types>
-listbox. I<extension> is a file extension for this file pattern.
-I<macType> is a four-character Macintosh file type. The list of
-I<macType>s is optional and may be omitted for applications that do
-not need to execute on the Macintosh platform.
-
-Several file patterns may have the same I<typeName,> in which case
-they refer to the same file type and share the same entry in the
-listbox. When the user selects an entry in the listbox, all the files
-that match at least one of the file patterns corresponding
-to that entry are listed. Usually, each file pattern corresponds to a
-distinct type of file. The use of more than one file patterns for one
-type of file is necessary on the Macintosh platform only.
-
-On the Macintosh platform, a file matches a file pattern if its
-name matches at least one of the I<extension>(s) AND it
-belongs to at least one of the I<macType>(s) of the
-file pattern. For example, the B<C Source Files> file pattern in the
-sample code matches with files that have a B<\.c> extension AND
-belong to the I<macType> B<TEXT>. To use the OR rule instead,
-you can use two file patterns, one with the I<extensions> only and
-the other with the I<macType> only. The B<GIF Files> file type
-in the sample code matches files that EITHER have a B<\.gif>
-extension OR belong to the I<macType> B<GIFF>.
-
-On the Unix and Windows platforms, a file matches a file pattern
-if its name matches at at least one of the I<extension>(s) of
-the file pattern. The I<macType>s are ignored.
-
-=head1 SPECIFYING EXTENSIONS
-
-On the Unix and Macintosh platforms, extensions are matched using
-glob-style pattern matching. On the Windows platforms, extensions are
-matched by the underlying operating system. The types of possible
-extensions are: (1) the special extension * matches any
-file; (2) the special extension "" matches any files that
-do not have an extension (i.e., the filename contains no full stop
-character); (3) any character string that does not contain any wild
-card characters (* and ?).
-
-Due to the different pattern matching rules on the various platforms,
-to ensure portability, wild card characters are not allowed in the
-extensions, except as in the special extension *. Extensions
-without a full stop character (e.g, ~) are allowed but may not
-work on all platforms.
-
-=head1 CAVEATS
-
-See L<Tk::chooseDirectory/CAVEATS>.
-
-=head1 EXAMPLE
-
- my $types = [
- ['Text Files', ['.txt', '.text']],
- ['TCL Scripts', '.tcl' ],
- ['C Source Files', '.c', 'TEXT'],
- ['GIF Files', '.gif', ],
- ['GIF Files', '', 'GIFF'],
- ['All Files', '*', ],
- ];
- my $filename = $widget->getOpenFile(-filetypes=>$types);
-
- if ($filename ne "") {
- # Open the file ...
- }
-
-=head1 SEE ALSO
-
-L<Tk::FBox|Tk::FBox>, L<Tk::FileSelect|Tk::FileSelect>
-
-=head1 KEYWORDS
-
-file selection dialog
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/grab.pod b/Master/tlpkg/tlperl/lib/Tk/grab.pod
deleted file mode 100644
index 98a488d09f7..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/grab.pod
+++ /dev/null
@@ -1,140 +0,0 @@
-# Copyright (c) 1992 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-grab - Confine pointer and keyboard events to a window sub-tree
-
-=for category User Interaction
-
-=head1 SYNOPSIS
-
-I<$widget>-E<gt>B<grab>
-
-I<$widget>-E<gt>B<grab>I<Option>
-
-=head1 DESCRIPTION
-
-This set of methods implement simple pointer and keyboard grabs for Tk.
-Tk's grabs are different than the grabs
-described in the Xlib documentation.
-When a grab is set for a particular window, Tk restricts all pointer
-events to the grab window and its descendants in Tk's window hierarchy.
-Whenever the pointer is within the grab window's subtree, the pointer
-will behave exactly the same as if there had been no grab at all
-and all events will be reported in the normal fashion.
-When the pointer is outside I<$widget>'s tree, button presses and
-releases and
-mouse motion events are reported to I<$widget>, and window entry
-and window exit events are ignored.
-The grab subtree ``owns'' the pointer:
-windows outside the grab subtree will be visible on the screen
-but they will be insensitive until the grab is released.
-The tree of windows underneath the grab window can include top-level
-windows, in which case all of those top-level windows
-and their descendants will continue to receive mouse events
-during the grab.
-
-Two forms of grabs are possible: local and global.
-A local grab affects only the grabbing application: events will
-be reported to other applications as if the grab had never occurred.
-Grabs are local by default.
-A global grab locks out all applications on the screen,
-so that only the given subtree of the grabbing application will be
-sensitive to pointer events (mouse button presses, mouse button releases,
-pointer motions, window entries, and window exits).
-During global grabs the window manager will not receive pointer
-events either.
-
-During local grabs, keyboard events (key presses and key releases)
-are delivered as usual: the window
-manager controls which application receives keyboard events, and
-if they are sent to any window in the grabbing application then they are
-redirected to the focus window.
-During a global grab Tk grabs the keyboard so that all keyboard events
-are always sent to the grabbing application.
-The B<focus> method is still used to determine which window in the
-application receives the keyboard events.
-The keyboard grab is released when the grab is released.
-
-Grabs apply to particular displays. If an application has windows
-on multiple displays then it can establish a separate grab on each
-display.
-The grab on a particular display affects only the windows on
-that display.
-It is possible for different applications on a single display to have
-simultaneous local grabs, but only one application can have a global
-grab on a given display at once.
-
-The B<grab> methods take any of the following forms:
-
-=over 4
-
-=item I<$widget>-E<gt>B<grabCurrent>
-
-Returns the current grab
-window in this application for I<$widget>'s display, or an empty
-string if there is no such window.
-
-=item I<$widget>-E<gt>B<grabs>
-
-Returns a list whose elements
-are all of the windows grabbed by this application for all displays,
-or an empty string if the application has no grabs.
-
-I<Not implemented yet!>
-
-=item I<$widget>-E<gt>B<grabRelease>
-
-Releases the grab on I<$widget> if there is one, otherwise does
-nothing. Returns an empty string.
-
-=item I<$widget>-E<gt>B<grab>
-
-Sets a local grab on I<$widget>.
-If a grab was already in effect for this application on
-I<$widget>'s display then it is automatically released.
-If there is already a local grab on I<$widget>, then the command
-does nothing. Returns an empty string.
-
-=item I<$widget>-E<gt>B<grabGlobal>
-
-Sets a global grab on I<$widget>.
-If a grab was already in effect for this application on
-I<$widget>'s display then it is automatically released.
-If there is already a global grab on I<$widget>,
-then the command does nothing. Returns an empty string.
-
-=item I<$widget>-E<gt>B<grabStatus>
-
-Returns B<none> if no grab is currently set on I<$widget>,
-B<local> if a local grab is set on I<$widget>, and
-B<global> if a global grab is set.
-
-=back
-
-=head1 BUGS
-
-It took an incredibly complex and gross implementation to produce
-the simple grab effect described above.
-Given the current implementation, it isn't safe for applications
-to use the Xlib grab facilities at all except through the Tk grab
-procedures.
-If applications try to manipulate X's grab mechanisms directly,
-things will probably break.
-
-If a single process is managing several different Tk applications,
-only one of those applications can have a local grab for a given
-display at any given time. If the applications are in different
-processes, this restriction doesn't exist.
-
-=head1 KEYWORDS
-
-grab, keyboard events, pointer events, window
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/grid.pod b/Master/tlpkg/tlperl/lib/Tk/grid.pod
deleted file mode 100644
index 8db89587a62..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/grid.pod
+++ /dev/null
@@ -1,409 +0,0 @@
-# Copyright (c) 1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::grid - Geometry manager that arranges widgets in a grid
-
-=for category Tk Geometry Management
-
-=head1 SYNOPSIS
-
-S< >I<$widget>-E<gt>B<grid>?(?I<widget> ...,? ?I<arg> ?...>?)?
-
-S< >I<$widget>-E<gt>B<grid>I<Option>?(I<arg> ?,I<arg> ...?)?
-
-=head1 DESCRIPTION
-
-The B<grid> method is used to communicate with the grid
-geometry manager that arranges widgets in rows and columns inside
-of another window, called the geometry master (or master window).
-The B<grid> method can have any of several forms, depending
-on the I<option> argument:
-
-=over 4
-
-=item I<$slave>-E<gt>B<grid>(?I<$slave, ...>??, I<options>?)
-
-The arguments consist of the optional references to more slave windows
-followed by pairs of arguments that specify how to manage the slaves.
-The characters B<->, B<x> and B<^>,
-can be specified instead of a window reference to alter the default
-location of a I<$slave>, as described in L<"RELATIVE PLACEMENT">, below.
-
-If any of the slaves are already managed by the geometry manager
-then any unspecified options for them retain their previous values rather
-than receiving default values.
-
-The following options are supported:
-
-=over 8
-
-=item B<-column> => I<n>
-
-Insert the I<$slave> so that it occupies the I<n>th column in the grid.
-Column numbers start with 0. If this option is not supplied, then the
-I<$slave> is arranged just to the right of previous slave specified on this
-call to B<grid>, or column "0" if it is the first slave. For each
-B<x> that immediately precedes the I<$slave>, the column position
-is incremented by one. Thus the B<x> represents a blank column
-for this row in the grid.
-
-=item B<-columnspan> => I<n>
-
-Insert the slave so that it occupies I<n> columns in the grid.
-The default is one column, unless the window name is followed by a
-B<->, in which case the columnspan is incremented once for each immediately
-following B<->.
-
-=item B<-in> => I<$other>
-
-Insert the slave(s) in the master
-window given by I<$other>. The default is the first slave's
-parent window.
-
-=item B<-ipadx> => I<amount>
-
-The I<amount> specifies how much horizontal internal padding to
-leave on each side of the slave(s). This is space is added
-inside the slave(s) border.
-The I<amount> must be a valid screen distance, such as B<2> or B<'.5c'>.
-It defaults to 0.
-
-=item B<-ipady> => I<amount>
-
-The I<amount> specifies how much vertical internal padding to
-leave on on the top and bottom of the slave(s).
-This space is added inside the slave(s) border.
-The I<amount> defaults to 0.
-
-=item B<-padx> => I<amount>
-
-The I<amount> specifies how much horizontal external padding to
-leave on each side of the slave(s), in screen units.
-The I<amount> defaults to 0.
-This space is added outside the slave(s) border.
-
-=item B<-pady> => I<amount>
-
-The I<amount> specifies how much vertical external padding to
-leave on the top and bottom of the slave(s), in screen units.
-The I<amount> defaults to 0.
-This space is added outside the slave(s) border.
-
-=item B<-row> => I<n>
-
-Insert the slave so that it occupies the I<n>th row in the grid.
-Row numbers start with 0. If this option is not supplied, then the
-slave is arranged on the same row as the previous slave specified on this
-call to B<grid>, or the first unoccupied row if this is the first slave.
-
-=item B<-rowspan> => I<n>
-
-Insert the slave so that it occupies I<n> rows in the grid.
-The default is one row. If the next B<grid> method contains
-B<^> characters instead of I<$slave>s that line up with the columns
-of this I<$slave>, then the B<rowspan> of this I<$slave> is
-extended by one.
-
-=item B<-sticky> => I<style>
-
-If a slave's cell is larger than its requested dimensions, this
-option may be used to position (or stretch) the slave within its cell.
-I<Style> is a string that contains zero or more of the characters
-B<n>, B<s>, B<e> or B<w>.
-The string can optionally contain spaces or
-commas, but they are ignored. Each letter refers to a side (north, south,
-east, or west) that the slave will "stick" to. If both B<n> and B<s> (or
-B<e> and B<w>) are specified, the slave will be stretched to fill the entire
-height (or width) of its cavity. The B<sticky> option subsumes the
-combination of B<-anchor> and B<-fill> that is used by L<pack|Tk::pack>.
-The default is B<''>, which causes the slave to be centered in its cavity,
-at its requested size.
-
-=back
-
-=item I<$master>-E<gt>B<gridBbox>(?I<column, row>,? ?I<column2, row2>?)
-
-With no arguments,
-the bounding box (in pixels) of the grid is returned.
-The return value consists of 4 integers. The first two are the pixel
-offset from the master window (x then y) of the top-left corner of the
-grid, and the second two integers are the width and height of the grid,
-also in pixels. If a single I<column> and I<row> is specified on
-the command line, then the bounding box for that cell is returned, where the
-top left cell is numbered from zero. If both I<column> and I<row>
-arguments are specified, then the bounding box spanning the rows and columns
-indicated is returned.
-
-=item I<$master>-E<gt>B<gridColumnconfigure>(I<index>?, I<-option>=>I<value, ...>?)
-
-Query or set the column properties of the I<index> column of the
-geometry master, I<$master>.
-The valid options are B<-minsize>, B<-weight> and B<-pad>.
-If one or more options are provided, then I<index> may be given as
-a list of column indices to which the configuration options will operate on.
-The B<-minsize> option sets the minimum size, in screen units,
-that will be permitted for this column.
-The B<-weight> option (an integer value)
-sets the relative weight for apportioning
-any extra spaces among
-columns.
-A weight of zero (0) indicates the column will not deviate from its requested
-size. A column whose weight is two will grow at twice the rate as a column
-of weight one when extra space is allocated to the layout.
-The B<-uniform> option, when a
-non-empty value is supplied, places the column in a I<uniform
-group> with other columns that have the same value for B<-uniform>.
-The space for columns belonging to a uniform group is allocated
-so that their sizes are always in strict proportion to their
-B<-weight> values. See I<THE GRID ALGORITHM> below for further
-details.
-The B<-pad> option specifies the number of screen units that will be
-added to the largest window contained completely in that column when the
-grid geometry manager requests a size from the containing window.
-If only an option is specified, with no value,
-the current value of that option is returned.
-If only the master window and index is specified, all the current settings
-are returned in an list of "-option value" pairs.
-
-=item I<$slave>-E<gt>B<gridConfigure>(?I<$slave, ...>?, I<options>?)
-
-The same as B<grid> method.
-
-=item I<$slave>-E<gt>B<gridForget>?(I<$slave, ...>)?
-
-Removes each of the I<$slave>s from grid for its
-master and unmaps their windows.
-The slaves will no longer be managed by the grid geometry manager.
-The configuration options for that window are forgotten, so that if the
-slave is managed once more by the grid geometry manager, the initial
-default settings are used.
-
-=item I<$slave>-E<gt>B<gridInfo>
-
-Returns a list whose elements are the current configuration state of
-the slave given by I<$slave> in the same option-value form that
-might be specified to B<gridConfigure>.
-The first two elements of the list are ``B<-in>=>I<$master>'' where
-I<$master> is the slave's master.
-
-=item I<$master>-E<gt>B<gridLocation>(I<x, y>)
-
-Given I<x> and I<y> values in screen units relative to the master window,
-the column and row number at that I<x> and I<y> location is returned.
-For locations that are above or to the left of the grid, B<-1> is returned.
-
-=item I<$master>-E<gt>B<gridPropagate>?(I<boolean>)?
-
-If I<boolean> has a true boolean value such as B<1> or B<on>
-then propagation is enabled for I<$master>, which must be a window
-name (see L<"GEOMETRY PROPAGATION"> below).
-If I<boolean> has a false boolean value then propagation is
-disabled for I<$master>.
-In either of these cases an empty string is returned.
-If I<boolean> is omitted then the method returns B<0> or
-B<1> to indicate whether propagation is currently enabled
-for I<$master>.
-Propagation is enabled by default.
-
-=item I<$master>-E<gt>B<gridRowconfigure>(I<index>?, I<-option>=>I<value, ...>?)
-
-Query or set the row properties of the I<index> row of the
-geometry master, I<$master>.
-The valid options are B<-minsize>, B<-weight> and B<-pad>.
-If one or more options are provided, then I<index> may be given as
-a list of row indeces to which the configuration options will operate on.
-The B<-minsize> option sets the minimum size, in screen units,
-that will be permitted for this row.
-The B<-weight> option (an integer value)
-sets the relative weight for apportioning
-any extra spaces among
-rows.
-A weight of zero (0) indicates the row will not deviate from its requested
-size. A row whose weight is two will grow at twice the rate as a row
-of weight one when extra space is allocated to the layout.
-The B<-uniform> option, when a non-empty value is supplied, places the
-row in a I<uniform group> with other rows that have the same value
-for B<-uniform>. The space for rows belonging to a uniform group
-is allocated so that their sizes are always in strict proportion
-to their B<-weight> values. See I<THE GRID ALGORITHM> below for
-further details.
-The B<-pad> option specifies the number of screen units that will be
-added to the largest window contained completely in that row when the
-grid geometry manager requests a size from the containing window.
-If only an option is specified, with no value,
-the current value of that option is returned.
-If only the master window and index is specified, all the current settings
-are returned in an list of "option-value" pairs.
-
-=item I<$slave>-E<gt>B<gridRemove>?(I<$slave, ...>)?
-
-Removes each of the I<$slave>s from grid for its
-master and unmaps their windows.
-The slaves will no longer be managed by the grid geometry manager.
-However, the configuration options for that window are remembered,
-so that if the
-slave is managed once more by the grid geometry manager, the previous
-values are retained.
-
-=item I<$master>-E<gt>B<gridSize>
-
-Returns the size of the grid (in columns then rows) for I<$master>.
-The size is determined either by the I<$slave> occupying the largest
-row or column, or the largest column or row with a B<-minsize>,
-B<-weight>, or B<-pad> that is non-zero.
-
-=item I<$master>-E<gt>B<gridSlaves>?(I<-option>=>I<value>)?
-
-If no options are supplied, a list of all of the slaves in I<$master>
-are returned, most recently manages first.
-I<-option> can be either B<-row> or B<-column> which
-causes only the slaves in the row (or column) specified by I<value>
-to be returned.
-
-=back
-
-=head1 RELATIVE PLACEMENT
-
-The B<grid> method contains a limited set of capabilities that
-permit layouts to be created without specifying the row and column
-information for each slave. This permits slaves to be rearranged,
-added, or removed without the need to explicitly specify row and
-column information.
-When no column or row information is specified for a I<$slave>,
-default values are chosen for
-B<-column>, B<-row>, B<-columnspan> and B<-rowspan>
-at the time the I<$slave> is managed. The values are chosen
-based upon the current layout of the grid, the position of the I<$slave>
-relative to other I<$slave>s in the same grid method, and the presence
-of the characters B<->, B<^>, and B<^> in B<grid>
-method where I<$slave> names are normally expected.
-
-=over 4
-
-=item B<->
-
-This increases the columnspan of the I<$slave> to the left. Several
-B<->'s in a row will successively increase the columnspan. A B<->
-may not follow a B<^> or a B<x>.
-
-=item B<x>
-
-This leaves an empty column between the I<$slave> on the left and
-the I<$slave> on the right.
-
-=item B<^>
-
-This extends the B<-rowspan> of the I<$slave> above the B<^>'s
-in the grid. The number of B<^>'s in a row must match the number of
-columns spanned by the I<$slave> above it.
-
-=back
-
-=head1 THE GRID ALGORITHM
-
-The grid geometry manager lays out its slaves in three steps.
-In the first step, the minimum size needed to fit all of the slaves
-is computed, then (if propagation is turned on), a request is made
-of the master window to become that size.
-In the second step, the requested size is compared against the actual size
-of the master. If the sizes are different, then space is added to or taken
-away from the layout as needed.
-For the final step, each slave is positioned in its row(s) and column(s)
-based on the setting of its I<sticky> flag.
-
-To compute the minimum size of a layout, the grid geometry manager
-first looks at all slaves whose columnspan and rowspan values are one,
-and computes the nominal size of each row or column to be either the
-I<minsize> for that row or column, or the sum of the I<pad>ding
-plus the size of the largest slave, whichever is greater. Then the
-slaves whose rowspans or columnspans are greater than one are
-examined. If a group of rows or columns need to be increased in size
-in order to accommodate these slaves, then extra space is added to each
-row or column in the group according to its I<weight>. For each
-group whose weights are all zero, the additional space is apportioned
-equally.
-
-When multiple rows or columns belong to a uniform group, the space
-allocated to them is always in proportion to their weights. (A weight
-of zero is considered to be 1.) In other words, a row or column
-configured with B<-weight 1 -uniform> a will have exactly the same size
-as any other row or column configured with B<-weight 1 -uniform a>. A
-row or column configured with B<-weight 2 -uniform b> will be exactly
-twice as large as one that is configured with B<-weight 1 -uniform b>.
-
-More technically, each row or column in the group will have a size
-equal to I<k*weight> for some constant k. The constant k is chosen so
-that no row or column becomes smaller than its minimum size. For
-example, if all rows or columns in a group have the same weight, then
-each row or column will have the same size as the largest row or
-column in the group.
-
-
-For masters whose size is larger than the requested layout, the additional
-space is apportioned according to the row and column weights. If all of
-the weights are zero, the layout is centered within its master.
-For masters whose size is smaller than the requested layout, space is taken
-away from columns and rows according to their weights. However, once a
-column or row shrinks to its minsize, its weight is taken to be zero.
-If more space needs to be removed from a layout than would be permitted, as
-when all the rows or columns are at there minimum sizes, the layout is
-clipped on the bottom and right.
-
-=head1 GEOMETRY PROPAGATION
-
-The grid geometry manager normally computes how large a master must be to
-just exactly meet the needs of its slaves, and it sets the
-requested width and height of the master to these dimensions.
-This causes geometry information to propagate up through a
-window hierarchy to a top-level window so that the entire
-sub-tree sizes itself to fit the needs of the leaf windows.
-However, the B<gridPropagate> method may be used to
-turn off propagation for one or more masters.
-If propagation is disabled then grid will not set
-the requested width and height of the master window.
-This may be useful if, for example, you wish for a master
-window to have a fixed size that you specify.
-
-=head1 RESTRICTIONS ON MASTER WINDOWS
-
-The master for each slave must either be the slave's parent
-(the default) or a descendant of the slave's parent.
-This restriction is necessary to guarantee that the
-slave can be placed over any part of its master that is
-visible without danger of the slave being clipped by its parent.
-In addition, all slaves in one call to B<grid> must have the same master.
-
-=head1 STACKING ORDER
-
-If the master for a slave is not its parent then you must make sure
-that the slave is higher in the stacking order than the master.
-Otherwise the master will obscure the slave and it will appear as
-if the slave hasn't been managed correctly.
-The easiest way to make sure the slave is higher than the master is
-to create the master window first: the most recently created window
-will be highest in the stacking order.
-
-=head1 CREDITS
-
-The B<grid> method is based on ideas taken from the I<GridBag>
-geometry manager written by Doug. Stein, and the B<blt_table> geometry
-manager, written by George Howlett.
-
-=head1 SEE ALSO
-
-L<Tk::form|Tk::form>
-L<Tk::pack|Tk::pack>
-L<Tk::place|Tk::place>
-
-=head1 KEYWORDS
-
-geometry manager, location, grid, cell, propagation, size, pack,
-master, slave
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/mega.pod b/Master/tlpkg/tlperl/lib/Tk/mega.pod
deleted file mode 100644
index 76e40e7891f..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/mega.pod
+++ /dev/null
@@ -1,423 +0,0 @@
-
-## Author: Achim Bohnet <ach@mpe.mpg.de>
-##
-## Copyright (c) 1997-1998 Achim Bohnet. All rights reserved.
-## You can redistribute this document and/or modify it under the
-## same terms as Perl itself.
-##
-## Update for Tk804.025, Steve Lidie, 2004/01/11.
-
-=head1 NAME
-
-Tk::mega - Perl/Tk support for writing widgets in pure Perl
-
-=for category Derived Widgets
-
-=head1 SYNOPSIS
-
-Define the widget's new class name:
-
-S< >B<package Tk::>I<MyNewWidget>;
-
-For composite widget classes:
-
-S< >B<use base qw/ Tk::container />; # where B<container> is I<Frame> or I<Toplevel>
-
-For derived widget classes:
-
-S< >B<use base qw/ Tk::Derived Tk::DerivedWidget /;>
-
-Install the new widget in Tk's namespace and establish class and instance
-constructors.
-
-S< >B<Construct Tk::>I<Widget> I<'MyNewWidget'>;
-
-S< >B<sub ClassInit> { I<my ($self, $args) = @_; ...> }
-
-S< >B<sub Populate> { I<my ($self, $args) = @_; ...> }
-
-=head1 DESCRIPTION
-
-The goal of the mega-widget support of Perl/Tk is to make it
-easy to write mega-widgets that obey the same protocol and
-interface that the Tk core widgets support.
-I<For mega-widget sample code please run the B<widget> demonstration program and go to the section B<Sample Perl Mega-Widgets>.>
-
-There are two kinds of mega-widgets:
-
-=over 4
-
-=item * Composite Widgets
-
-A composite widget is composed with one or more existing widgets.
-The composite widget looks to the user like a simple single widget.
-A well known example is the file selection box.
-
-=item * Derived Widgets
-
-A derived widget adds/modifies/removes properties and methods
-from a single widget (this widget may itself be a mega-widget).
-
-=back
-
-=head1 MEGA-WIDGET SUPPORT
-
-=head2 Advertise
-
-Give a subwidget a symbolic name.
-
-Usage:
-
-S< >I<$self>-E<gt>B<Advertise>(B<name>=E<gt>I<$widget>);
-
-Gives a subwidget I<$widget> of the mega-widget I<$self> the
-name B<name>. One can retrieve the reference of an advertised subwidget
-with the L<Subwidget|"Subwidget"> method.
-
-B<Comment:> Mega-Widget Writers: Please make sure to document the
-advertised widgets that are intended for I<public> use.
-If there are none, document this fact, e.g.:
-
- =head1 ADVERTISED WIDGETS
-
- None.
-
-=head2 Callback
-
-Invoke a callback specified with an option.
-
-Usage:
-
-S< >I<$self>-E<gt>B<Callback>(I<-option> ?,I<args> ...?);
-
-B<Callback> executes the L<callback|Tk::callbacks> defined with
-I<$self>-E<gt>B<ConfigSpecs>(I<-option>, [B<CALLBACK>, ...]);
-If I<args> are given they are passed to the callback. If
-I<-option> is not defined it does nothing.
-
-=head2 ClassInit
-
-Initialization of the mega-widget class.
-
-Usage:
-
-S< >B<sub ClassInit> { I<my ($class, $mw) = @_;> ... }
-
-B<ClassInit> is called once for I<each> L<MainWindow|Tk::MainWindow>
-just before the first widget instance of a class is created in
-the widget tree of B<MainWindow>.
-
-B<ClassInit> is often used to define bindings and/or other
-resources shared by all instances, e.g., images.
-
-Examples:
-
- $mw->bind($class,"<Tab>", sub { my $w = shift; $w->Insert("\t"); $w->focus; $w->break});
- $mw->bind($class,"<Return>", ['Insert',"\n"]);
- $mw->bind($class,"<Delete>",'Delete');
-
-Notice that I<$class> is the class name (e.g. B<Tk::MyText>) and I<$mw> is the mainwindow.
-
-Don't forget to call I<$class>-E<gt>B<SUPER::ClassInit($mw)> in
-B<ClassInit>.
-
-=head2 Component
-
-Convenience function to create subwidgets.
-
-Usage:
-
- $cw->Component('Whatever', 'AdvertisedName',
- -delegate => ['method1', 'method2', ...],
- ... more widget options ...,
- );
-
-B<Component> does several things for you with one call:
-
-=over 4
-
-o Creates the widget
-
-o Advertises it with a given name (overridden by 'Name' option)
-
-o Delegates a set of methods to this widget (optional)
-
-=back
-
-Example:
-
- $cw->Component('Button', 'quitButton', -command => sub{$mw->'destroy'});
-
-=head2 ConfigSpecs
-
-Defines options and their treatment
-
-Usage:
-
- $cw->ConfigSpecs(
- -option => [ where, dbname, dbclass, default],
- ...,
- DEFAULT => [where],
- );
-
-Defines the options of a mega-widget and what actions
-are triggered by configure/cget of an option
-(see L<Tk::ConfigSpecs> and L<Tk::Derived> for details).
-
-=head2 Construct
-
-Make the new mega-widget known to B<Tk>.
-
-Usage:
-
-S< >B<Construct> I<baseclass> B<'Name'>;
-
-B<Construct> declares the new widget class so that your mega-widget
-works like normal Perl/Tk widgets.
-
-Examples:
-
-S< >B<Construct Tk::Widget> I<'Whatever'>;
-S< >B<Construct Tk::Menu> I<'MyItem'>;
-
-First example lets one use I<$widget>-E<gt>B<Whatever> to create
-new B<Whatever> widget.
-
-The second example restricts the usage of the B<MyItem> constructor
-method to widgets that are derived from B<Menu>:
-I<$isamenu>-E<gt>I<MyItem>.
-
-=head2 CreateArgs
-
-Process options before any widget is created:
-
-S< >B<sub CreateArgs> { I<my ($package, $parent, $args) = @_; ...; return @newargs;> }
-
-I<$package> is the package of the mega-widget (e.g., B<Tk::MyText>,
-I<$parent> the parent of the widget to be created and $args the hash
-reference to the options specified in the widget constructor call.
-
-Don't forget to call I<$package>-E<gt>B<SUPER::CreateArgs>(I<$parent>, I<$args>) in
-B<CreateArgs>.
-
-=head2 Delegates
-
-Redirect a method of the mega-widget to a subwidget of
-the composite widget
-
-Usage:
-
- $cw->Delegates(
- 'method1' => $subwidget1,
- 'method2' => 'advertived_name',
- ...,
- 'Construct' => $subwidget2,
- 'DEFAULT' => $subwidget3,
- );
-
-The B<'Construct'> delegation has a special meaning. After
-'Construct' is delegated all Widget constructors are redirected.
-E.g. after
-
-S< >I<$self>-E<gt>B<Delegates>(B<'Construct'>=E<gt>I<$subframe>);
-
-a I<$self>-E<gt>B<Button> does really a I<$subframe>-E<gt>B<Button>
-so the created button is a child of I<$subframe> and not I<$self>.
-
-B<Comment:> Delegates works only with methods that I<$cw> does
-not have itself.
-
-=head2 InitObject
-
-I<Note: this method should not, in general, be used, as it has been
-superceeded by B<Populate> and specifying B<Tk::Derived> as one of the base
-classes.>
-
-Defines construction and interface of derived widgets.
-
-Usage:
-
- sub InitObject {
- my ($derived, $args) = @_;
- ...
- }
-
-where I<$derived> is the widget reference of the already created
-baseclass widget and I<$args> is the reference to a hash of
-I<-option-value> pairs.
-
-B<InitObject> is almost identical to L<Populate|"Populate"> method.
-B<Populate> does some more 'magic' things useful for mega-widgets
-with several widgets.
-
-Don't forget to call I<$derived>-E<gt>B<SUPER::InitObject>(I<$args>) in
-B<InitObject>.
-
-=head2 OnDestroy
-
-Define a callback invoked when the mega-widget is destroyed.
-
-Usage:
-
-S< >I<$widget>-E<gt>B<OnDestroy>(I<callback>);
-
-B<OnDestroy> installs a L<callback|Tk::callbacks> that's called
-when a widget is going to to be destroyed. Useful
-for special cleanup actions. It differs from a normal B<destroy>
-in that all the widget's data structures are still intact.
-
-B<Comment:> This method could be used with any widgets not just
-for mega-widgets. It's listed here because of it's usefulness.
-
-=head2 Populate
-
-Defines construction and interface of the composite
-widget.
-
-Usage:
-
- sub Populate {
- my ($self, $args) = @_;
- ...
- }
-
-where I<$self> is the widget reference of the already created baseclass
-widget and I<$args> is the
-reference to a hash of I<-option-value> pairs.
-
-Most the other support function are normally used inside the B<Populate>
-subroutine.
-
-Don't forget to call I<$cw>-E<gt>B<SUPER::Populate>(I<$args>) in
-B<Populate>.
-
-=head2 privateData
-
-Set/get a private hash of a widget to storage
-composite internal data
-
-Usage:
-
-S< >I<$hashref> = I<$self>-E<gt>B<privateData>();
-
-S< >I<$another> = I<$self>-E<gt>B<privateData>(I<unique_key>|I<package>);
-
-=head2 Subwidget
-
-Get the widget reference of an advertised subwidget.
-
-S< >I<@subwidget> = I<$cw>-E<gt>B<Subwidget>();
-
-S< >I<$subwidget> = I<$cw>-E<gt>B<Subwidget>(I<name>);
-
-S< >I<@subwidget> = I<$cw>-E<gt>B<Subwidget>(I<name> ?,...?);
-
-Returns the widget reference(s) of the subwidget known under the given
-name(s). Without arguments, return all known subwidgets of I<$cw>. See
-L<Advertise|"Advertise"> method how to define I<name> for a subwidget.
-
-B<Comment:> Mega-Widget Users: Use B<Subwidget> to get I<only>
-documented subwidgets.
-
-=head1 PITFALLS
-
-=over 4
-
-=item * Resource DB class name
-
-Some of the standard options use a resource date base class
-that is not equal to the resource database name. E.g.,
-
- Switch: Name: Class:
-
- -padx padX Pad
- -activerelief activeRelief Relief
- -activebackground activeBackground Foreground
- -status undef undef
-
-One should do the same when one defines one of these
-options via B<ConfigSpecs>.
-
-=item * Method delegation
-
-Redirecting methods to a subwidget with B<Delegate>
-can only work if the base widget itself does have a
-method with this name. Therefore one can't ``I<delegate>''
-any of the methods listed in L<Tk::Widget|Tk::Widget>.
-A common problematic method is B<bind>. In this case
-one as to explicitely redirect the method.
-
- sub bind {
- my $self = shift;
- my $to = $self->privateData->{'my_bind_target'};
- $to->bind(@_);
- }
-
-=item * privateData
-
-Graham Barr wrote: ... It is probably
-more private than most people think. Not all calls to privateData will
-return that same HASH reference. The HASH reference that is returned
-depends on the package it was called from, a different HASH is returned
-for each package. This allows a widget to hold private data, but then
-if it is sub-classed the sub-class will get a different HASH and so not
-cause duplicate name clashes.
-
-But privateData does take an optional argument if you want to
-force which HASH is returned.
-
-=item * Scrolled and Composite
-
-B<Scrolled>(I<Kind>,...) constructor can not be used with B<Composite>.
-One has to use $cw->B<Composite>(B<Scrl>I<Kind> =E<gt> B<'name'>, ...);
-
-=back
-
-=head1 MISSING
-
-Of course Perl/Tk does not define support function for
-all necessities. Here's a short list of things you have to
-handle yourself:
-
-=over 4
-
-=item *
-
-No support to define construction-time only options.
-
-=item *
-
-No support to remove an option that is known to the
-base widget.
-
-=item *
-
-It's hard to define B<undef> as fallback for an widget
-option that is not already B<undef>.
-
-=item *
-
-Frame in Perl/Tk carries magic and overhead not needed
-for composite widget class definition.
-
-=item *
-
-No support methods for bindings that are shared between all
-widgets of a composite widget (makes sense at all?)
-
-=back
-
-=head1 KEYWORDS
-
-mega, composite, derived, widget
-
-=head1 SEE ALSO
-
-L<Tk::composite|Tk::composite>
-L<Tk::ConfigSpecs|Tk::ConfigSpecs>
-L<Tk::option|Tk::option>
-L<Tk::callbacks|Tk::callbacks>
-L<Tk::bind|Tk::bind>
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/messageBox.pod b/Master/tlpkg/tlperl/lib/Tk/messageBox.pod
deleted file mode 100644
index 3cae94beb0d..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/messageBox.pod
+++ /dev/null
@@ -1,67 +0,0 @@
-=head1 NAME
-
-messageBox - pop up a message window and wait for user response.
-
-=for category Popups and Dialogs
-
-=head1 SYNOPSIS
-
-S< >I<$response> = I<$widget>-E<gt>B<messageBox>(I<-option> =E<gt> I<value>, ... );
-
-=head1 DESCRIPTION
-
-This method uses L<Tk::Dialog|Tk::Dialog> to quickly create several
-common dialog boxes. A dialog widget consists of a message, an icon
-and a set of buttons (see the I<-type> option). After the message
-window is popped up, B<messageBox> waits for the user to select one of
-the buttons and return the button text (note that it's best to check the
-returned value in a case insensitive manner). NOTE: unlike
-B<Tk::Dialog> which creates its widget once and can be used many
-times, the B<messageBox> window is created every time it's used.
-
-The following option/value pairs are supported:
-
-=over 4
-
-=item B<-default>
-
-The case-sensitive symbolic name of the default button
-for this message window ('Ok', 'Cancel' and so
-on). See B<-type> for a list of the symbolic names.
-If the message box has just one button it will
-automatically be made the default, otherwise if
-this option is not specified, there won't be any
-default button.
-
-=item B<-icon>
-
-Specifies an icon to display. On X11 any of the builtin Tk bitmaps can
-specified. On Windows only B<error>, B<info>, B<question> or
-B<warning> are supported.
-
-=item B<-message>
-
-Specifies the message to display.
-
-=item B<-title>
-
-Specifies a string to display as the title.
-
-=item B<-type>
-
-Specifies a predefined set of buttons to be displayed. The following
-values are possible: 'AbortRetryIgnore', 'Ok', 'OkCancel',
-'RetryCancel', 'YesNo' or 'YesNoCancel'.
-
-=back
-
-=head1 EXAMPLE
-
-I<$response> = I<$mw>-E<gt>B<messageBox>(-icon =E<gt> 'question', -message =E<gt> 'Hello World!', -title =E<gt> 'My title', -type =E<gt> 'AbortRetryIgnore', -default =E<gt> 'Retry');
-
-=head1 AUTHOR
-
-Stephen.O.Lidie@Lehigh.EDU. 98/05/25
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/option.pod b/Master/tlpkg/tlperl/lib/Tk/option.pod
deleted file mode 100644
index 1214357d181..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/option.pod
+++ /dev/null
@@ -1,217 +0,0 @@
-# Copyright (c) 1990 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-option - Using the option database in Perl/Tk
-
-=for category Creating and Configuring Widgets
-
-=head1 SYNOPSIS
-
-S< >I<$widget>-E<gt>B<widgetClass>(B<Name>=E<gt>I<name>, B<-class>=E<gt>I<class>);
-
-S< >I<$widget>-E<gt>B<PathName>;
-
-S< >I<$widget>-E<gt>B<optionAdd>(I<pattern>=E<gt>I<value > ?,I<priority>?);
-
-S< >I<$widget>-E<gt>B<optionClear>;
-
-S< >I<$widget>-E<gt>B<optionGet>(I<name, class>);
-
-S< >I<$widget>-E<gt>B<optionReadfile>(I<fileName> ?,I<priority>?);
-
-=head1 DESCRIPTION
-
-The option database (also known as the I<resource database> or the
-I<application defaults database>) is a set of rules for applying
-default options to widgets. Users and system administrators can
-set up these rules to customize the appearance of applications
-without changing any application code; for example, a user might
-set up personal foreground and background colors, or a site
-might use fonts associated with visual or language preferences.
-Different window managers (and implementations of them) have implemented
-the database differently, but most Xt-based window managers use the
-I<.Xdefaults> file or the I<xrdb> utility to manage user preferences;
-some use both, and/or implement a more complex set of site, user and
-application databases. Check your site documentation for these topics
-or your window manager's B<RESOURCE_MANAGER> property.
-
-=head2 Being a good citizen
-
-For most applications, the option database "just works." The B<option...>
-methods are for applications that need to do something unusual, such as
-add new rules or test an option's default. Even in such cases, the
-application should provide for user preferences.
-Do not hardcode widget options without a B<very> good reason.
-All users have their own tastes and they are all different.
-They choose a special font in a special size and have often spend a
-lot of time working out a color scheme that they will love until death.
-When you respect their choices they will enjoy working with your
-applications much more. Don't destroy the common look and feel of a
-personal desktop.
-
-=head2 Option rules and widget identification
-
-All widgets in an application are identified hierarchically by I<pathname>,
-starting from the B<MainWindow> and passing through each widget used to create
-the endpoint. The path elements are I<widget names>, much like the elements
-of a file path from the root directory to a file. The rules in the option
-database are patterns that are matched against a widget's I<pathname> to
-determine which defaults apply.
-When a widget is created, the B<Name> option can be
-used to assign the widget's name and thus create a distinctive path
-for widgets in an application. If the B<Name> option isn't given,
-Perl/Tk assigns a default name based on the type of widget; a
-B<MainWindow>'s default name is the B<appname>. These defaults are fine
-for most widgets, so don't feel you need to find a meaningful name for
-every widget you create.
-A widget must have a distinctive name to allow users to tailor its
-options independently of other widgets in an application. For instance,
-to create a B<Text> widget that will
-have special options assigned to it, give it a name such as:
-
- $text = $mw->Text(Name => 'importantText');
-
-You can then tailor the widget's attributes with a rule in the option
-database such as:
-
- *importantText*foreground: red
-
-The I<class> attribute identifies groups of widgets, usually within an
-application but also to group similar widgets among different applications.
-One typically assigns a class to a B<TopLevel> or B<Frame> so that the
-class will apply to all of that widget's children. To extend the example,
-we could be more specific about the importantText widget
-by giving its frame a class:
-
- $frame = $mw->Frame(-class => 'Urgent');
- $text = $frame->Text(Name => 'importantText');
-
-Then the resource pattern can be specified as so:
-
- *Urgent*importantText*foreground: red
-
-Similarly, the pattern C<*Urgent*background: cyan> would apply to all
-widgets in the frame.
-
-=head1 METHODS
-
-=over 4
-
-=item I<$widget>-E<gt>B<widgetClass>(B<Name>=E<gt>I<name>, B<-class>=E<gt>I<class>);
-
-Identify a new widget with I<name> and/or I<class>.
-B<Name> specifies the path element for the widget; names generally begin with a
-lowercase letter. B<-class> specifies the class for the widget and its
-children; classes generally begin with an uppercase letter.
-If not specified, Perl/Tk will assign a unique default name to each widget.
-Only B<MainWindow> widgets have a default class, made by uppercasing the
-first letter of the application name.
-
-=item I<$widget>-E<gt>B<PathName>;
-
-The B<PathName> method returns the widget's I<pathname>, which uniquely
-identifies the widget within the application.
-
-=item I<$widget>-E<gt>B<optionAdd>(I<pattern>=E<gt>I<value >?, I<priority>?);
-
-The B<optionAdd> method adds a new option to the database.
-I<Pattern> contains the option being specified, and consists of
-names and/or classes separated by asterisks or dots, in the usual
-X format. I<Value> contains a text string to associate with
-I<pattern>; this is the value that will be returned in calls to
-the B<optionGet> method. If I<priority> is specified, it indicates
-the priority level for this option (see below for legal values);
-it defaults to B<interactive>. This method always returns an empty
-string.
-
-=item I<$widget>-E<gt>B<optionClear>;
-
-The B<optionClear> method clears the option database. Default
-options (from the B<RESOURCE_MANAGER> property or the B<.Xdefaults>
-file) will be reloaded automatically the next time an option is
-added to the database or removed from it. This method always returns
-an empty string.
-
-=item I<$widget>-E<gt>B<optionGet>(I<name,class>);
-
-The B<optionGet> method returns the value of the option specified for
-I<$widget> under I<name> and I<class>. To look up the option,
-B<optionGet> matches the patterns in the resource database against
-I<$widget>'s I<pathname> along with the class of I<$widget>
-(or its parent if I<$widget> has no class specified). The widget's
-class and name are options set when the widget is created (not
-related to class in the sense of L<bless>); the B<MainWindow>'s name
-is the B<appname> and its class is (by default) derived from the name
-of the script.
-
-If several entries in the option database match I<$widget>'s I<pathname>,
-I<name>, and I<class>, then the method returns whichever was created with
-highest I<priority> level. If there are several matching
-entries at the same priority level, then it returns whichever entry
-was I<most recently entered> into the option database. If there are
-no matching entries, then the empty string is returned.
-
-=item I<$widget>-E<gt>B<optionReadfile>(I<fileName>?,I<priority>?);
-
-The B<optionReadfile> method reads I<fileName>, which should have the
-standard format for an X resource database such as B<.Xdefaults>, and
-adds all the options specified in that file to the option database.
-If I<priority> is specified, it indicates the priority level at which
-to enter the options; I<priority> defaults to B<interactive>.
-
-The I<priority> arguments to the B<option> methods are
-normally specified symbolically using one of the following values:
-
-=over 8
-
-=item B<widgetDefault>
-
-Level 20. Used for default values hard-coded into widgets.
-
-=item B<startupFile>
-
-Level 40. Used for options specified in application-specific
-startup files.
-
-=item B<userDefault>
-
-Level 60. Used for options specified in user-specific defaults
-files, such as B<.Xdefaults>, resource databases loaded into
-the X server, or user-specific startup files.
-
-=item B<interactive>
-
-Level 80. Used for options specified interactively after the application
-starts running. If I<priority> isn't specified, it defaults to
-this level.
-
-=back
-
-Any of the above keywords may be abbreviated. In addition, priorities
-may be specified numerically using integers between 0 and 100,
-inclusive. The numeric form is probably a bad idea except for new priority
-levels other than the ones given above.
-
-=back
-
-=head1 BUGS
-
-The priority scheme used by core Tk is not the same as used by normal Xlib
-routines. In particular is assumes that the order of the entries is defined,
-but user commands like B<xrdb -merge> can change the order.
-
-=head1 SEE ALSO
-
-L<Tk::Xrm|Tk::Xrm>
-
-=head1 KEYWORDS
-
-database, option, priority, retrieve
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Tk/options.pod b/Master/tlpkg/tlperl/lib/Tk/options.pod
deleted file mode 100644
index 49d81ddd2b4..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/options.pod
+++ /dev/null
@@ -1,787 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::options - Standard options supported by widgets and their manipulation
-
-=for category Creating and Configuring Widgets
-
-=head1 SYNOPSIS
-
-S< >I<$value> = I<$widget>-E<gt>B<cget>('I<-option>');
-
-S< >I<$widget>-E<gt>B<configure>(I<-option>=E<gt>I<value> ?,I<-option>=E<gt>I<value> ...?);
-
-S< >I<@list> = I<$widget>-E<gt>B<configure>('I<-option>');
-
-S< >I<@lol> = I<$widget>-E<gt>B<configure>;
-
-=head1 DESCRIPTION
-
-All widgets, and images have a standard mechanism for setting and querying
-attibutes or options. The mechanism is based on two methods B<configure>
-and B<cget>. The behaviour of these methods is as follows:
-
-=over 4
-
-=item I<$widget>-E<gt>B<configure>(I<-option>=E<gt>I<value> ?,I<-option>=E<gt>I<value> ...?);
-
-Sets the values of I<-option> to I<value> for each I<-option>=E<gt>I<value>
-pair. The internal B<new> method does an implicit B<configure> in this
-form with options passed in at widget create time.
-
-=item I<$widget>-E<gt>B<configure>('I<-option>')
-
-In array context returns a list of five or two elements. If I<-option>
-is an alias for another options it return a list consisting of the
-alias option and the name for the option is is an alias for, e.g.,
-C<('-bg', 'background')>. If I<-option> is not an alias the returned
-list has the following five elements:
-
-=over 8
-
-=item I<Option Name>
-
-The value of I<-option>, e.g., B<-background>.
-
-=item I<Name>
-
-The option's name in the option database, e.g., C<background>.
-
-=item I<Class>
-
-The option's class value in the option database, e.g., C<Background>.
-
-=item I<Default>
-
-The default value for the option if not specified or in the option database,
-e.g., C<grey>.
-
-=item I<Value>
-
-The current value (as returned by B<cget>), e.g., C<white>.
-
-=back
-
-=item I<$widget>-E<gt>B<configure>
-
-Returns a list of lists for all the options supported by I<$widget>.
-Each sub-list is in the form returned by B<configure>('I<-option>').
-(This mechanism is used by the B<Tk::Derived> class to determine
-the options available from base class.)
-
-=item I<$widget>-E<gt>B<cget>('I<-option>')
-
-Returns the current value of I<-option> for I<$widget>.
-
-B<cget>('I<-option>') is clumsy with the need for B<''> due to perl's
-parsing rules. Something more subtle using L<tie|perlfunc/tie> might look better.
-
-=back
-
-The following paragraphs describe the common configuration options supported by
-widgets in the Tk toolkit. Every widget does not necessarily support every option
-(see the the documentation entries for individual widgets for a list of the
-standard options supported by that widget), but if a widget does support an option
-with one of the names listed below, then the option has exactly the effect
-described below.
-
-In the descriptions below, ``Name'' refers to the option's name in the option
-database. ``Class'' refers to the option's class value
-in the option database. ``Switch'' refers to the switch used in widget-creation
-and B<configure> widget methods to set this value. For example, if an option's
-configure option is B<-foreground> and there exists a widget I<$widget>, then the
-call:
-
-S< >I<$widget>-E<gt>B<configure>(B<-foreground>=E<gt>B<'black'>)
-
-may be used to specify the value B<black> for the option in the widget I<$widget>.
-Configure options may be abbreviated, as long as the abbreviation is unambiguous
-(abbreviation is deprecated in perl/Tk).
-
-=head2 Creation options: Widget Name and Class
-
-The B<Name> and B<-class> options can only be specified when a widget is
-created, and cannot be changed with B<configure>. These options determine
-the widget's identity and how Tk applies resource values from the
-option database (see L<Tk::option>) and so they
-cannot be assigned by the options database.
-
-=over 4
-
-=item Name: I<name>
-
-=item Switch: B<Name>
-
-Specifies the path element for the widget. Names generally begin with a
-lowercase letter.
-
-Each widget has a unique I<pathname> that follows the hierarchy from the
-B<MainWindow> to the widget itself. Since the widget's B<PathName> is
-used to assign options from the options database, it is important to
-specify a distinctive B<Name> for any widget that will have non-default
-options. See L<Tk::option> for details.
-
-=item Name: I<class>
-
-=item Switch: B<-class>
-
-Specifies a class for the window. Classes generally begin with an
-uppercase letter.
-
-This class will be used when querying the option database for
-the window's other options (see Tk::options), and it will also be used
-later for other purposes such as bindings. One typically assigns a class
-to a B<TopLevel> or B<Frame> so that the class will apply to all of
-that widget's children.
-
-=back
-
-=head2 Reconfigurable options
-
-These options can be set at widget creation or changed later via B<configure>.
-
-=over 4
-
-=item Name: B<activeBackground>
-
-=item Class: B<Foreground>
-
-=item Switch: B<-activebackground>
-
-Specifies background color to use when drawing active elements.
-An element (a widget or portion of a widget) is active if the
-mouse cursor is positioned over the element and pressing a mouse button
-will cause some action to occur.
-If strict Motif compliance has been requested by setting the
-B<$Tk::strictMotif> variable, this option will normally be
-ignored; the normal background color will be used instead.
-For some elements on Windows and Macintosh systems, the active color
-will only be used while mouse button 1 is pressed over the element.
-
-=item Name: B<activeBorderWidth>
-
-=item Class: B<BorderWidth>
-
-=item Switch: B<-activeborderwidth>
-
-Specifies a non-negative value indicating
-the width of the 3-D border drawn around active elements.
-See above for definition of active elements.
-The value may have any of the forms acceptable to B<Tk_GetPixels>.
-This option is typically only available in widgets displaying more
-than one element at a time (e.g. menus but not buttons).
-
-=item Name: B<activeForeground>
-
-=item Class: B<Background>
-
-=item Switch: B<-activeforeground>
-
-Specifies foreground color to use when drawing active elements.
-See above for definition of active elements.
-
-=item Name: B<activetile>
-
-=item Class: B<Tile>
-
-=item Switch: B<-activetile>
-
-Specifies image used to display inside active elements of the widget.
-See above for definition of active elements.
-
-=item Name: B<anchor>
-
-=item Class: B<Anchor>
-
-=item Switch: B<-anchor>
-
-Specifies how the information in a widget (e.g. text or a bitmap)
-is to be displayed in the widget.
-Must be one of the values B<n>, B<ne>, B<e>, B<se>,
-B<s>, B<sw>, B<w>, B<nw>, or B<center>.
-For example, B<nw> means display the information such that its
-top-left corner is at the top-left corner of the widget.
-
-=item Name: B<background>
-
-=item Class: B<Background>
-
-=item Switch: B<-background>
-
-=item Alias: B<-bg>
-
-Specifies the normal background color to use when displaying the
-widget.
-
-=item Name: B<bitmap>
-
-=item Class: B<Bitmap>
-
-=item Switch: B<-bitmap>
-
-Specifies a bitmap to display in the widget, in any of the forms
-acceptable to B<Tk_GetBitmap>.
-The exact way in which the bitmap is displayed may be affected by
-other options such as B<-anchor> or B<-justify>.
-Typically, if this option is specified then it overrides other
-options that specify a textual value to display in the widget;
-the B<-bitmap> option may be reset to an empty string to re-enable
-a text display.
-In widgets that support both B<-bitmap> and B<-image> options,
-B<-image> will usually override B<-bitmap>.
-
-=item Name: B<borderWidth>
-
-=item Class: B<BorderWidth>
-
-=item Switch: B<-borderwidth>
-
-=item Alias: B<-bd>
-
-Specifies a non-negative value indicating the width
-of the 3-D border to draw around the outside of the widget (if such a
-border is being drawn; the B<relief> option typically determines
-this). The value may also be used when drawing 3-D effects in the
-interior of the widget.
-The value may have any of the forms acceptable to B<Tk_GetPixels>.
-
-=item Name: B<compound>
-
-=item Class: B<Compound>
-
-=item Switch: B<-compound>
-
-Specifies if the widget should display text and bitmaps/images at the
-same time, and if so, where the bitmap/image should be placed relative
-to the text. Must be one of the values B<none>, B<bottom>, B<top>,
-B<left>, B<right>, or B<center>. For example, the (default) value
-B<none> specifies that the bitmap or image should (if defined) be
-displayed instead of the text, the value B<left> specifies that the
-bitmap or image should be displayed to the left of the text, and the
-value B<center> specifies that the bitmap or image should be displayed on
-top of the text.
-
-=item Name: B<cursor>
-
-=item Class: B<Cursor>
-
-=item Switch: B<-cursor>
-
-Specifies the mouse cursor to be used for the widget.
-The value may have any of the forms acceptable to B<Tk_GetCursor>.
-
-=item Name: B<dash>
-
-=item Class: B<Dash>
-
-=item Switch: B<-dash>
-
-The value may have any of the forms accepted by B<Tk_GetDash>,
-such as B<4>, B<[6,4]>, B<.>, B<->, B<-.>, or B<-..>.
-
-=item Name: B<dashoffset>
-
-=item Class: B<Dashoffset>
-
-=item Switch: B<-dashoffset>
-
-Specifies the offset in the dash list where the drawing starts.
-
-=item Name: B<disabledForeground>
-
-=item Class: B<DisabledForeground>
-
-=item Switch: B<-disabledforeground>
-
-Specifies foreground color to use when drawing a disabled element.
-If the option is specified as an empty string (which is typically the
-case on monochrome displays), disabled elements are drawn with the
-normal foreground color but they are dimmed by drawing them
-with a stippled fill pattern.
-
-=item Name: B<disabledtile>
-
-=item Class: B<Tile>
-
-=item Switch: B<-disabledtile>
-
-Specifies image to use when drawing a disabled element.
-
-=item Name: B<exportSelection>
-
-=item Class: B<ExportSelection>
-
-=item Switch: B<-exportselection>
-
-Specifies whether or not a selection in the widget should also be
-the X selection.
-The value may have any of the forms accepted by B<Tcl_GetBoolean>,
-such as B<true>, B<false>, B<0>, B<1>, B<yes>, or B<no>.
-If the selection is exported, then selecting in the widget deselects
-the current X selection, selecting outside the widget deselects any
-widget selection, and the widget will respond to selection retrieval
-requests when it has a selection. The default is usually for widgets
-to export selections.
-
-=item Name: B<font>
-
-=item Class: B<Font>
-
-=item Switch: B<-font>
-
-Specifies the font to use when drawing text inside the widget.
-
-=item Name: B<foreground>
-
-=item Class: B<Foreground>
-
-=item Switch: B<-foreground>
-
-=item Alias: B<-fg>
-
-Specifies the normal foreground color to use when displaying the widget.
-
-=item Name: B<highlightBackground>
-
-=item Class: B<HighlightBackground>
-
-=item Switch: B<-highlightbackground>
-
-Specifies the color to display in the traversal highlight region when
-the widget does not have the input focus.
-
-=item Name: B<highlightColor>
-
-=item Class: B<HighlightColor>
-
-=item Switch: B<-highlightcolor>
-
-Specifies the color to use for the traversal highlight rectangle that is
-drawn around the widget when it has the input focus.
-
-=item Name: B<highlightThickness>
-
-=item Class: B<HighlightThickness>
-
-=item Switch: B<-highlightthickness>
-
-Specifies a non-negative value indicating the width of the highlight
-rectangle to draw around the outside of the widget when it has the
-input focus.
-The value may have any of the forms acceptable to B<Tk_GetPixels>.
-If the value is zero, no focus highlight is drawn around the widget.
-
-=item Name: B<image>
-
-=item Class: B<Image>
-
-=item Switch: B<-image>
-
-Specifies an image to display in the widget, which must have been
-created with an image create. (See L<Tk::Image> for details of image creation.)
-Typically, if the B<-image> option is specified then it overrides other
-options that specify a bitmap or textual value to display in the widget;
-the B<-image> option may be reset to an empty string to re-enable
-a bitmap or text display.
-
-=item Name: B<insertBackground>
-
-=item Class: B<Foreground>
-
-=item Switch: B<-insertbackground>
-
-Specifies the color to use as background in the area covered by the
-insertion cursor. This color will normally override either the normal
-background for the widget (or the selection background if the insertion
-cursor happens to fall in the selection).
-
-=item Name: B<insertBorderWidth>
-
-=item Class: B<BorderWidth>
-
-=item Switch: B<-insertborderwidth>
-
-Specifies a non-negative value indicating the width
-of the 3-D border to draw around the insertion cursor.
-The value may have any of the forms acceptable to B<Tk_GetPixels>.
-
-=item Name: B<insertOffTime>
-
-=item Class: B<OffTime>
-
-=item Switch: B<-insertofftime>
-
-Specifies a non-negative integer value indicating the number of
-milliseconds the insertion cursor should remain ``off'' in each blink cycle.
-If this option is zero then the cursor doesn't blink: it is on
-all the time.
-
-=item Name: B<insertOnTime>
-
-=item Class: B<OnTime>
-
-=item Switch: B<-insertontime>
-
-Specifies a non-negative integer value indicating the number of
-milliseconds the insertion cursor should remain ``on'' in each blink cycle.
-
-=item Name: B<insertWidth>
-
-=item Class: B<InsertWidth>
-
-=item Switch: B<-insertwidth>
-
-Specifies a value indicating the total width of the insertion cursor.
-The value may have any of the forms acceptable to B<Tk_GetPixels>.
-If a border has been specified for the insertion
-cursor (using the B<insertBorderWidth> option), the border
-will be drawn inside the width specified by the B<insertWidth>
-option.
-
-=item Name: B<jump>
-
-=item Class: B<Jump>
-
-=item Switch: B<-jump>
-
-For widgets with a slider that can be dragged to adjust a value,
-such as scrollbars, this option determines when
-notifications are made about changes in the value.
-The option's value must be a boolean of the form accepted by
-B<Tcl_GetBoolean>.
-If the value is false, updates are made continuously as the
-slider is dragged.
-If the value is true, updates are delayed until the mouse button
-is released to end the drag; at that point a single notification
-is made (the value ``jumps'' rather than changing smoothly).
-
-=item Name: B<justify>
-
-=item Class: B<Justify>
-
-=item Switch: B<-justify>
-
-When there are multiple lines of text displayed in a widget, this
-option determines how the lines line up with each other.
-Must be one of B<left>, B<center>, or B<right>.
-B<Left> means that the lines' left edges all line up, B<center>
-means that the lines' centers are aligned, and B<right> means
-that the lines' right edges line up.
-
-=item Name: B<offset>
-
-=item Class: B<Offset>
-
-=item Switch: B<-offset>
-
-Specifies the offset of tiles (see also B<-tile> option). It can
-have two different formats B<-offset x,y> or B<-offset side>,
-where side can be B<n>, B<ne>, B<e>, B<se>, B<s>,
-B<sw>, B<w>, B<nw>, or B<center>. In the first case
-the origin is the origin of the toplevel of the current window.
-For the canvas itself and canvas objects the origin is the canvas
-origin, but putting B<#> in front of the coordinate pair
-indicates using the toplevel origin in stead. For canvas objects,
-the B<-offset> option is used for stippling as well.
-For the line and polygon canvas items you can also specify
-an index as argument, which connects the stipple or tile
-origin to one of the coordinate points of the line/polygon.
-
-=item Name: B<orient>
-
-=item Class: B<Orient>
-
-=item Switch: B<-orient>
-
-For widgets that can lay themselves out with either a horizontal
-or vertical orientation, such as scrollbars, this option specifies
-which orientation should be used. Must be either B<horizontal>
-or B<vertical> or an abbreviation of one of these.
-
-=item Name: B<padX>
-
-=item Class: B<Pad>
-
-=item Switch: B<-padx>
-
-Specifies a non-negative value indicating how much extra space
-to request for the widget in the X-direction.
-The value may have any of the forms acceptable to B<Tk_GetPixels>.
-When computing how large a window it needs, the widget will
-add this amount to the width it would normally need (as determined
-by the width of the things displayed in the widget); if the geometry
-manager can satisfy this request, the widget will end up with extra
-internal space to the left and/or right of what it displays inside.
-Most widgets only use this option for padding text: if they are
-displaying a bitmap or image, then they usually ignore padding
-options.
-
-=item Name: B<padY>
-
-=item Class: B<Pad>
-
-=item Switch: B<-pady>
-
-Specifies a non-negative value indicating how much extra space
-to request for the widget in the Y-direction.
-The value may have any of the forms acceptable to B<Tk_GetPixels>.
-When computing how large a window it needs, the widget will add
-this amount to the height it would normally need (as determined by
-the height of the things displayed in the widget); if the geometry
-manager can satisfy this request, the widget will end up with extra
-internal space above and/or below what it displays inside.
-Most widgets only use this option for padding text: if they are
-displaying a bitmap or image, then they usually ignore padding
-options.
-
-=item Name: B<relief>
-
-=item Class: B<Relief>
-
-=item Switch: B<-relief>
-
-Specifies the 3-D effect desired for the widget. Acceptable
-values are B<raised>, B<sunken>, B<flat>, B<ridge>,
-B<solid>, and B<groove>.
-The value
-indicates how the interior of the widget should appear relative
-to its exterior; for example, B<raised> means the interior of
-the widget should appear to protrude from the screen, relative to
-the exterior of the widget.
-
-=item Name: B<repeatDelay>
-
-=item Class: B<RepeatDelay>
-
-=item Switch: B<-repeatdelay>
-
-Specifies the number of milliseconds a button or key must be held
-down before it begins to auto-repeat. Used, for example, on the
-up- and down-arrows in scrollbars.
-
-=item Name: B<repeatInterval>
-
-=item Class: B<RepeatInterval>
-
-=item Switch: B<-repeatinterval>
-
-Used in conjunction with B<repeatDelay>: once auto-repeat
-begins, this option determines the number of milliseconds between
-auto-repeats.
-
-=item Name: B<selectBackground>
-
-=item Class: B<Foreground>
-
-=item Switch: B<-selectbackground>
-
-Specifies the background color to use when displaying selected
-items.
-
-=item Name: B<selectBorderWidth>
-
-=item Class: B<BorderWidth>
-
-=item Switch: B<-selectborderwidth>
-
-Specifies a non-negative value indicating the width
-of the 3-D border to draw around selected items.
-The value may have any of the forms acceptable to B<Tk_GetPixels>.
-
-=item Name: B<selectForeground>
-
-=item Class: B<Background>
-
-=item Switch: B<-selectforeground>
-
-Specifies the foreground color to use when displaying selected
-items.
-
-=item Name: B<setGrid>
-
-=item Class: B<SetGrid>
-
-=item Switch: B<-setgrid>
-
-Specifies a boolean value that determines whether this widget controls the
-resizing grid for its top-level window.
-This option is typically used in text widgets, where the information
-in the widget has a natural size (the size of a character) and it makes
-sense for the window's dimensions to be integral numbers of these units.
-These natural window sizes form a grid.
-If the B<setGrid> option is set to true then the widget will
-communicate with the window manager so that when the user interactively
-resizes the top-level window that contains the widget, the dimensions of
-the window will be displayed to the user in grid units and the window
-size will be constrained to integral numbers of grid units.
-See L<Tk::Wm/"GRIDDED GEOMETRY MANAGEMENT">
-for more details.
-
-=item Name: B<takeFocus>
-
-=item Class: B<TakeFocus>
-
-=item Switch: B<-takefocus>
-
-Determines whether the window accepts the focus during keyboard
-traversal (e.g., Tab and Shift-Tab).
-Before setting the focus to a window, the traversal scripts
-consult the value of the B<takeFocus> option.
-A value of B<0> means that the window should be skipped entirely
-during keyboard traversal.
-B<1> means that the window should receive the input
-focus as long as it is viewable (it and all of its ancestors are mapped).
-An empty value for the option means that the traversal scripts make
-the decision about whether or not to focus on the window: the current
-algorithm is to skip the window if it is
-disabled, if it has no key bindings, or if it is not viewable.
-If the value has any other form, then the traversal scripts take
-the value, append the name of the window to it (with a separator space),
-and evaluate the resulting string as a Callback.
-The script must return B<0>, B<1>, or an empty string: a
-B<0> or B<1> value specifies whether the window will receive
-the input focus, and an empty string results in the default decision
-described above.
-Note: this interpretation of the option is defined entirely by
-the Callbacks that implement traversal: the widget implementations
-ignore the option entirely, so you can change its meaning if you
-redefine the keyboard traversal scripts.
-
-=item Name: B<text>
-
-=item Class: B<Text>
-
-=item Switch: B<-text>
-
-Specifies a string to be displayed inside the widget. The way in which
-the string is displayed depends on the particular widget and may be
-determined by other options, such as B<anchor> or B<justify>.
-
-=item Name: B<textVariable>
-
-=item Class: B<Variable>
-
-=item Switch: B<-textvariable>
-
-Specifies the name of a variable. The value of the variable is a text
-string to be displayed inside the widget; if the variable value changes
-then the widget will automatically update itself to reflect the new value.
-The way in which the string is displayed in the widget depends on the
-particular widget and may be determined by other options, such as
-B<anchor> or B<justify>.
-
-=item Name: B<tile>
-
-=item Class: B<Tile>
-
-=item Switch: B<-tile>
-
-Specifies image used to display the widget. If image is the empty
-string, then the normal background color is displayed.
-
-=item Name: B<troughColor>
-
-=item Class: B<Background>
-
-=item Switch: B<-troughcolor>
-
-Specifies the color to use for the rectangular trough areas
-in widgets such as scrollbars and scales.
-
-=item Name: B<troughTile>
-
-=item Class: B<Tile>
-
-=item Switch: B<-troughtile>
-
-Specifies image used to display in the rectangular trough areas
-in widgets such as scrollbars and scales.
-
-=item Name: B<underline>
-
-=item Class: B<Underline>
-
-=item Switch: B<-underline>
-
-Specifies the integer index of a character to underline in the widget.
-This option is used by the default bindings to implement keyboard
-traversal for menu buttons and menu entries.
-0 corresponds to the first character of the text displayed in the
-widget, 1 to the next character, and so on.
-
-=item Name: B<wrapLength>
-
-=item Class: B<WrapLength>
-
-=item Switch: B<-wraplength>
-
-For widgets that can perform word-wrapping, this option specifies
-the maximum line length.
-Lines that would exceed this length are wrapped onto the next line,
-so that no line is longer than the specified length.
-The value may be specified in any of the standard forms for
-screen distances.
-If this value is less than or equal to 0 then no wrapping is done: lines
-will break only at newline characters in the text.
-
-=item Name: B<xScrollCommand>
-
-=item Class: B<ScrollCommand>
-
-=item Switch: B<-xscrollcommand>
-
-Specifies a callback used to communicate with horizontal
-scrollbars.
-When the view in the widget's window changes (or
-whenever anything else occurs that could change the display in a
-scrollbar, such as a change in the total size of the widget's
-contents), the widget will
-make a callback passing two numeric arguments in addition to
-any specified in the callback.
-Each of the numbers is a fraction between 0 and 1, which indicates
-a position in the document. 0 indicates the beginning of the document,
-1 indicates the end, .333 indicates a position one third the way through
-the document, and so on.
-The first fraction indicates the first information in the document
-that is visible in the window, and the second fraction indicates
-the information just after the last portion that is visible.
-Typically the
-B<xScrollCommand> option consists of the scrollbar widget object
-and the method ``set'' i.e. [B<set> =E<gt> I<$sb>]:
-this will cause the scrollbar to be updated whenever the view in the window changes.
-If this option is not specified, then no command will be executed.
-
-=item Name: B<yScrollCommand>
-
-=item Class: B<ScrollCommand>
-
-=item Switch: B<-yscrollcommand>
-
-Specifies a calback used to communicate with vertical
-scrollbars. This option is treated in the same way as the
-B<xScrollCommand> option, except that it is used for vertical
-scrollbars and is provided by widgets that support vertical scrolling.
-See the description of B<xScrollCommand> for details
-on how this option is used.
-
-=back
-
-=head1 SEE ALSO
-
-L<Tk::option>
-L<Tk::callbacks>
-L<Tk::ConfigSpecs>
-L<Tk_GetPixels|Tk::pTk::GetPixels>
-
-=head1 KEYWORDS
-
-class, name, standard option, switch
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/overview.pod b/Master/tlpkg/tlperl/lib/Tk/overview.pod
deleted file mode 100644
index 0c9e183b68a..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/overview.pod
+++ /dev/null
@@ -1,138 +0,0 @@
-
-=head1 NAME
-
-B<Tk> - An overview of an Object Oriented Tk8 extension for perl5
-
-=for category Introduction
-
-=head1 SYNOPSIS
-
-C<< use Tk; >>
-
-C<< $main = MainWindow-E<gt>new(); >>
-
-C<< $widget = $main-E<gt>I<Widget>(...); >>
-
-C<< $widget-E<gt>pack(...); >>
-
-...
-
-C<< MainLoop; >>
-
-=head1 DESCRIPTION
-
-In writing the perl Tk extension, the goals were to provide a complete
-interface to the latest production version of John Ousterhout's Tk, while providing
-an Object Oriented interface to perl code.
-
-=head1 CONTENTS
-
-The package is composed of three loosely connected parts:
-
-=over 4
-
-=item I<pTk> - Converted Tk source
-
-The I<pTk> sub-directory is a copy of the C code of Tk8.x, modified
-to allow use by languages other than the original Tcl.
-(The pTk can be read as 'perl' Tk or 'portable' Tk, depending on
-your sensibilities.)
-
-=item B<Tk> to Perl 'Glue'
-
-The top level directory provides I<Tk.xs> and I<tkGlue.c>
-which provide the perl-callable interfaces to pTk
-
-=item Perl code for 'Widget' Classes
-
-The I<Tk> sub-directory contains the various perl modules that comprise
-the "Classes" that are visible to Tk applications.
-
-The "major" widgets such as B<Tk::Text> are actually in separate directories
-at the top level (e.g. I<Text/*> for B<Tk::Text>) and are dynamically
-loaded as needed on platforms which support perl5's B<DynaLoader>.
-
-=back
-
-=head1 CLASS HIERARCHY
-
-=over 4
-
-=item B<package Tk;> - the 'base class'
-
-All the "command names" documented in Tcl/Tk are made to look like perl
-sub's and reside in the Tk package. Their names are all lower case.
-Typically there are very few commands at this level which are called
-directly by applications.
-
-=item B<package Tk::Widget;> - the 'Widget class'
-
-There are no actual objects of the B<Tk::Widget> class; however all
-the various Tk window "widgets" inherit from it, and it in turn
-inherits all the core Tk functions from Tk.
-
-B<Tk::Widget> provides various functions and interfaces which are
-common to all Widgets.
-
-A widget is represented to perl as a blessed reference to a hash. There are some
-members of the hash which are private to Tk and its tkGlue code. Keys
-starting with B<'.'> and of the form B</_[A-Z][A-Za-z_]+_/>
-(i.e. starting and ending in _ and with first char after _ being upper case) should be
-considered reserved to B<Tk>.
-
-=item B<Tk::Button>, B<Tk::Entry>, B<Tk::Text> ...
-
-There is one class for each of the "Tk" widget item types.
-Some of them like B<Tk::Frame> do very little indeed, and really
-only exist so that they can be derived from or so that focus or menu
-traversal can discover the "kind" of window being processed.
-
-Other classes, B<Tk::Text> for example, provide a lot of methods
-used with Tk's "bind" to provide a rich keyboard/mouse interface
-to the widgets' data.
-
-These widget classes also include conversions of the Tcl code for
-event bindings, keyboard focus traversal, menu bars, and menu keyboard
-traversal. All the Tcl functions have been converted, but the names have
-changed (systematically) and they have been split up between the various
-classes in what I hope is an appropriate manner.
-Name changes are normally: dropping initial tk_ as the Tk-ness is implicit
-in the B<Tk::> prefix, and similarly dropping say Menu from the name if it
-has been moved the Tk::Menu class.
-Thus 'proc tkMenuNextEntry' becomes 'sub NextEntry' in the Tk::Menu package.
-
-=item B<Tk::Image>
-
-This does for Tk8.x's "images" what B<Tk::Widget> does for widgets.
-Images are new to Tk8.x and the class structure is not mature either.
-
-There are three sub-classes B<Tk::Bitmap>, B<Tk::Pixmap> and B<Tk::Photo>.
-
-It is possible to create dynamic or auto-loaded image types inherited
-from B<Tk::Image> for other image types or photo formats (e.g. support
-for TIFF format).
-
-=item Composite Widgets
-
-A composite is some kind of 'frame' with subwidgets which give it useful behaviour.
-B<Tk::Dialog> is an example of
-a composite widget classes built from the basic B<Tk> ones.
-It is intended that user code should not need to be aware that a particular
-class is a composite, and create and configure such widgets in the same manner
-as any other kind. The B<configure> mechanism and the methods of the
-class manipulate the subwidgets as required.
-
-Composite widgets are implemented via B<Tk::Frame> and multiple inheritance.
-The two 'frame' base classes B<Tk::Frame> and
-B<Tk::Toplevel> include the additional class B<Tk::Derived>
-in their inheritance. B<Tk::Derived> provides methods to allow additional
-B<configure> options to be defined for a widget.
-
-A Composite widget is typically defined as derived
-from B<Tk::Frame> or B<Tk::Toplevel>
-(e.g. B<Tk::Dialog>).
-
-=back
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/pTk.pod b/Master/tlpkg/tlperl/lib/Tk/pTk.pod
deleted file mode 100644
index 6e1a2a04022..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/pTk.pod
+++ /dev/null
@@ -1,550 +0,0 @@
-=head1 NAME
-
-Tk2portableTk - how to make your B<Tk> source portable to other
-interpreted languages.
-
-=for category C Programming
-
-=head1 Author
-
-Ilya Zakharevich <ilya@math.ohio-state.edu> has contributed most of
-this document. Many thanks.
-
-=head1 DESCRIPTION
-
-B<PortableTk> is an attempt to make B<Tk> useful from other
-languages. Currently tk4.0 runs under Perl using this
-approach. Below, I<Lang> is the notation for an external language to
-which B<PortableTk> glues B<Tk> code.
-
-The main problem with using the code developed for B<TCL> with
-different languages is the absence of data types: almost anything is
-C<char*>. It makes automatic translation hopeless. However, if you
-C<typedef> several new symbols to be C<char*>, you can still use your
-code in B<TCL>, I<and> it will make the automatic translation
-possible.
-
-Another problem with the approach that "everything is a string" is
-impossibility to have a result that says "NotApplicable" without
-setting an error. Thus different B<Tk> command return different string
-values that mean "error happened", like C<"">, C<" "> or
-C<"??">. Other languages can be more flexible, so in B<portableTk> you
-should inform the compiler that what you want to return means "error"
-(see L<Setting variables>).
-
-Currently B<PortableTk> uses several different approachs
-to simplify translation: several B<TCL> functions that are especially
-dangerous to use are undefined, so you can easily find places that
-need to be updated to use Language-independent functions based on
-compiler warnings. Eventually a way to use these Language-independent
-functions under proper B<TCL> will be also provided. The end of this
-document provides a starting point for such a project.
-
-=head1 Structure of B<pTk>, porting your code
-
-B<pTk>, that is a port of B<Tk>, is very special with respect to porting
-of other code to B<portableTk>. The problem is that currently there is
-very little hope to merge the modifications back into B<Tk>, so a
-special strategy is needed to maintain this port. Do not use this
-strategy to port your own code.
-
-B<pTk> is produced from B<Tk> via a two-step process: first, some
-manual editing (the result is in the subdirectory C<mTk>), and second,
-automatic conversion by the C<munge> script (written in Perl). Thus the
-subdirectory C<pTk/mTk> contains code with minimal possible difference
-from the virgin B<Tk> code, so it is easier to merge(1) the
-differences between B<Tk> versions into modified code.
-
-It looks like the strategy for a portable code should be exactly
-opposite: starting from B<TCL>-based code, apply C<munge>, and then
-hand-edit the resulting code. Probably it is also possible to target
-your code to B<portableTk> from scratch, since this will make it
-possible to run it under a lot of I<Lang>uages.
-
-The only reason anyone would like to look into contents of C<pTk/mTk>
-directory is to find out which constructs are not supported by
-C<munge>. On the other hand, C<pTk> directory contains code that is
-conformant to B<portableTk>, so you can look there to find example code.
-
-C<munge> is the script that converts most common B<Tk> constructs to
-their C<portableTk> equivalent. For your code to qualify, you should
-follow B<Tk> conventions on indentation and names of variables, in
-particular, the array of arguments for the C<...CmdProc> should be
-called C<argv>.
-
-For details on what C<munge> can do, see
-L<Translation of some TCL functions>.
-
-=head1 B<PortableTk> API
-
-=head2 Checking what you are running under
-
-B<PortableTk> provides a symbol C<????>. If this symbol is defined,
-your source is compiled with it.
-
-=head2 New types of configuration options
-
-B<PortableTk> defines several new types of configuration options:
-
- TK_CONFIG_CALLBACK
- TK_CONFIG_LANGARG
- TK_CONFIG_SCALARVAR
- TK_CONFIG_HASHVAR
- TK_CONFIG_ARRAYVAR
- TK_CONFIG_IMAGE
-
-You should use them instead of TK_CONFIG_STRING whenever
-appropriate. This allows your application to receive a direct
-representation of the corresponding resource instead of the string
-representation, if this is possible under given language.
-
-???? It looks like C<TK_CONFIG_IMAGE> and C<TK_CONFIG_SCALARVAR> set
-variables of type C<char*>.
-
-=head2 Language data
-
-The following data types are defined:
-
-=over 4
-
-=item C<Tcl_Obj *>
-
-is the main datatype of the language. This is a type that your C
-function gets pointers to for arguments when the corresponding I<Lang>
-function is called. The corresponding config type is
-C<TK_CONFIG_LANGARG>.
-
-This is also a type that keeps information about contents of I<Lang>
-variable.
-
-=item C<Var>
-
-Is a substitute for a C<char *> that contains name of variable. In
-I<Lang> it is an object that contains reference to another I<Lang>
-variable.
-
-=item C<LangResultSave>
-
-????
-
-=item C<LangCallback>
-
-C<LangCallback*> a substitute for a C<char *> that contains command to
-call. The corresponding config type is C<TK_CONFIG_CALLBACK>.
-
-=item C<LangFreeProc>
-
-It is the type that the C<Lang_SplitList> sets. Before you call it,
-declare
-
- Args *args;
- LangFreeProc *freeProc = NULL;
- ...
- code = Lang_SplitList(interp, value,
- &argc, &args, &freeProc);
-
-After you use the split values, call
-
- if (args != NULL && freeProc) (*freeProc)(argc,args);
-
-It is not guaranteed that the C<args> can survive deletion of C<value>.
-
-=back
-
-=head2 Conversion
-
-The following macros and functions are used for conversion between
-strings and the additional types:
-
- LangCallback * LangMakeCallback(Tcl_Obj *)
- Tcl_Obj * LangCallbackArg(LangCallback *)
- char * LangString(Tcl_Obj *)
-
-After you use the result of LangCallbackArg(), you should free it with
-C<freeProc> C<LANG_DYNAMIC> (it is not guaranteed that any change of
-C<Tcl_Obj *> will not be reflected in <LangCallback>, so you cannot do
-LangSet...() in between, and you should reset it to C<NULL> if you
-want to do any further assignments to this C<Tcl_Obj *>).
-
-The following function returns the C<Tcl_Obj *> that is a reference to C<Var>:
-
- Tcl_Obj * LangVarArg(Var)
-
-???? It is very anti-intuitive, I hope the name is changed.
-
- int LangCmpCallback(LangCallback *a,Tcl_Obj * b)
-
-(currently only a stub), and, at last,
-
- LangCallback * LangCopyCallback(LangCallback *)
-
-=head2 Callbacks
-
-Above we have seen the new datatype C<LangCallback> and the
-corresponding I<Config option> C<TK_CONFIG_CALLBACK>. The following
-functions are provided for manipulation of C<LangCallback>s:
-
- void LangFreeCallback(LangCallback *)
- int LangDoCallback(Tcl_Interp *,LangCallback *,
- int result,int argc, char *format,...)
-
-The argument C<format> of C<LangDoCallback> should contain a string that is
-suitable for C<sprintf> with optional arguments of C<LangDoCallback>.
-C<result> should be false if result of callback is not needed.
-
- int LangMethodCall(Tcl_Interp *,Tcl_Obj *,char *method,
- int result,int argc,...)
-
-????
-
-Conceptually, C<LangCallback*> is a substitute for ubiquitous C<char *>
-in B<TCL>. So you should use C<LangFreeCallback> instead of C<ckfree>
-or C<free> if appropriate.
-
-=head2 Setting variables
-
- void LangFreeArg (Tcl_Obj *, Tcl_FreeProc *freeProc)
- Tcl_Obj * LangCopyArg (Tcl_Obj *);
- void Tcl_AppendArg (Tcl_Interp *interp, Tcl_Obj *)
- void LangSetString(Tcl_Obj * *, char *s)
- void LangSetDefault(Tcl_Obj * *, char *s)
-
-These two are equivalent unless s is an empty string. In this case
-C<LangSetDefault> behaves like C<LangSetString> with C<s==NULL>, i.e.,
-it sets the current value of the I<Lang> variable to be false.
-
- void LangSetInt(Tcl_Obj * *,int)
- void LangSetDouble(Tcl_Obj * *,double)
-
-The I<Lang> functions separate uninitialized and initialized data
-comparing data with C<NULL>. So the declaration for an C<Tcl_Obj *> should
-look like
-
- Tcl_Obj * arg = NULL;
-
-if you want to use this C<arg> with the above functions. After you are
-done, you should use C<LangFreeArg> with C<TCL_DYNAMIC> as C<freeProc>.
-
-=head2 Language functions
-
-Use
-
-=over 4
-
-=item C<int LangNull(Tcl_Obj *)>
-
-to check that an object is false;
-
-=item C<int LangStringMatch(char *string, Tcl_Obj * match)>
-
-????
-
-=item C<void LangExit(int)>
-
-to make a proper shutdown;
-
-=item C<int LangEval(Tcl_Interp *interp, char *cmd, int global)>
-
-to call I<Lang> C<eval>;
-
-=item C<void Lang_SetErrorCode(Tcl_Interp *interp,char *code)>
-
-=item C<char *Lang_GetErrorCode(Tcl_Interp *interp)>
-
-=item C<char *Lang_GetErrorInfo(Tcl_Interp *interp)>
-
-=item C<void LangCloseHandler(Tcl_Interp *interp,Tcl_Obj * arg,FILE *f,Lang_FileCloseProc *proc)>
-
-currently stubs only;
-
-=item C<int LangSaveVar(Tcl_Interp *,Tcl_Obj * arg,Var *varPtr,int type)>
-
-to save the structure C<arg> into I<Lang> variable C<*varPtr>;
-
-=item C<void LangFreeVar(Var var)>
-
-to free the result;
-
-=item C<int LangEventCallback(Tcl_Interp *,LangCallback *,XEvent *,KeySym)>
-
-????
-
-=item C<int LangEventHook(int flags)>
-
-=item C<void LangBadFile(int fd)>
-
-=item C<int LangCmpConfig(char *spec, char *arg, size_t length)>
-
-unsupported????;
-
-=item C<void Tcl_AppendArg (Tcl_Interp *interp, Tcl_Obj *)>
-
-=back
-
-Another useful construction is
-
- Tcl_Obj * variable = LangFindVar(interp, Tk_Window tkwin, char *name);
-
-After using the above function, you should call
-
- LangFreeVar(Var variable);
-
-???? Note discrepancy in types!
-
-If you want to find the value of a variable (of type C<Tcl_Obj *>) given the
-variable name, use C<Tcl_GetVar(interp, varName, flags)>. If you are
-interested in the string value of this variable, use
-C<LangString(Tcl_GetVar(...))>.
-
-To get a B<C> array of C<Tcl_Obj *> of length C<n>, use
-
- Tcl_Obj * *args = LangAllocVec(n);
- ...
- LangFreeVec(n,args);
-
-You can set the values of the C<Tcl_Obj *>s using C<LangSet...> functions,
-and get string value using C<LangString>.
-
-If you want to merge an array of C<Tcl_Obj *>s into one C<Tcl_Obj *> (that will
-be an array variable), use
-
- result = Tcl_Merge(listLength, list);
-
-=head2 Translation of some TCL functions
-
-We mark items that can be dealt with by C<munge> by I<Autoconverted>.
-
-=over 4
-
-=item C<Tcl_AppendResult>
-
-does not take C<(char*)NULL>, but C<NULL> as delimiter. I<Autoconverted>.
-
-=item C<Tcl_CreateCommand>, C<Tcl_DeleteCommand>
-
-C<Tk_CreateWidget>, C<Tk_DeleteWidget>, the second argument is the
-window itself, not the pathname. I<Autoconverted>.
-
-=item C<sprintf(interp-E<gt>result, "%d %d %d %d",...)>
-
-C<Tcl_IntResults(interp,4,0,...)>. I<Autoconverted>.
-
-=item C<interp-E<gt>result = "1";>
-
-C<Tcl_SetResult(interp,"1", TCL_STATIC)>. I<Autoconverted>.
-
-=item Reading C<interp-E<gt>result>
-
-C<Tcl_GetResult(interp)>. I<Autoconverted>.
-
-=item C<interp-E<gt>result = Tk_PathName(textPtr-E<gt>tkwin);>
-
-C<Tk_WidgetResult(interp,textPtr-E<gt>tkwin)>. I<Autoconverted>.
-
-=item Sequence C<Tcl_PrintDouble, Tcl_PrintDouble, ..., Tcl_AppendResult>
-
-Use a single command
-
- void Tcl_DoubleResults(Tcl_Interp *interp, int append,
- int argc,...);
-
-C<append> governs whether it is required to clear the result first.
-
-A similar command for C<int> arguments is C<Tcl_IntResults>.
-
-=item C<Tcl_SplitList>
-
-Use C<Lang_SplitList> (see the description above).
-
-=back
-
-=head1 Translation back to TCL
-
-To use your B<portableTk> program with B<TCL>, put
-
- #include "ptcl.h"
-
-I<before> inclusion of C<tk.h>, and link the resulting code with
-C<ptclGlue.c>.
-
-These files currently implement the following:
-
-=over 4
-
-=item Additional config types:
-
- TK_CONFIG_CALLBACK
- TK_CONFIG_LANGARG
- TK_CONFIG_SCALARVAR
- TK_CONFIG_HASHVAR
- TK_CONFIG_ARRAYVAR
- TK_CONFIG_IMAGE
-
-=item Types:
-
- Var, Tcl_Obj *, LangCallback, LangFreeProc.
-
-=item Functions and macros:
-
- Lang_SplitList, LangString, LangSetString, LangSetDefault,
- LangSetInt, LangSetDouble Tcl_ArgResult, LangCallbackArg,
- LangSaveVar, LangFreeVar,
- LangFreeSplitProc, LangFreeArg, Tcl_DoubleResults, Tcl_IntResults,
- LangDoCallback, Tk_WidgetResult, Tcl_CreateCommand,
- Tcl_DeleteCommand, Tcl_GetResult.
-
-=back
-
-Current implementation contains enough to make it possible to compile
-C<mTk/tkText*.[ch]> with the virgin B<Tk>.
-
-=head2 New types of events ????
-
-PortableTk defines following new types of events:
-
- TK_EVENTTYPE_NONE
- TK_EVENTTYPE_STRING
- TK_EVENTTYPE_NUMBER
- TK_EVENTTYPE_WINDOW
- TK_EVENTTYPE_ATOM
- TK_EVENTTYPE_DISPLAY
- TK_EVENTTYPE_DATA
-
-and a function
-
- char * Tk_EventInfo(int letter,
- Tk_Window tkwin, XEvent *eventPtr,
- KeySym keySym, int *numPtr, int *isNum, int *type,
- int num_size, char *numStorage)
-
-=head1 Checking for trouble
-
-If you start with working TCL code, you can start convertion using
-the above hints. Good indication that you are doing is OK is absence
-of C<sprintf> and C<sscanf> in your code (at least in the part that is
-working with interpreter).
-
-=head1 Additional API
-
-What is described here is not included into base B<portableTk>
-distribution. Currently it is coded in B<TCL> and as Perl macros (core
-is coded as functions, so theoretically you can use the same object
-files with different interpreted languages).
-
-=head2 C<ListFactory>
-
-Dynamic arrays in B<TCL> are used for two different purposes: to
-construct strings, and to construct lists. These two usages will have
-separate interfaces in other languages (since list is a different type
-from a string), so you should use a different interface in your code.
-
-The type for construction of dynamic lists is C<ListFactory>. The API
-below is a counterpart of the API for construction of dynamic lists
-in B<TCL>:
-
- void ListFactoryInit(ListFactory *)
- void ListFactoryFinish(ListFactory *)
- void ListFactoryFree(ListFactory *)
- Tcl_Obj * * ListFactoryArg(ListFactory *)
- void ListFactoryAppend(ListFactory *, Tcl_Obj * *arg)
- void ListFactoryAppendCopy(ListFactory *, Tcl_Obj * *arg)
- ListFactory * ListFactoryNewLevel(ListFactory *)
- ListFactory * ListFactoryEndLevel(ListFactory *)
- void ListFactoryResult(Tcl_Interp *, ListFactory *)
-
-The difference is that a call to C<ListFactoryFinish> should precede the
-actual usage of the value of C<ListFactory>, and there are two
-different ways to append an C<Tcl_Obj *> to a C<ListFactory>:
-ListFactoryAppendCopy() guarantees that the value of C<arg> is copied
-to the list, but ListFactoryAppend() may append to the list a
-reference to the current value of C<arg>. If you are not going to change
-the value of C<arg> after appending, the call to ListFactoryAppend may
-be quicker.
-
-As in B<TCL>, the call to ListFactoryFree() does not free the
-C<ListFactory>, only the objects it references.
-
-The functions ListFactoryNewLevel() and ListFactoryEndLevel() return a
-pointer to a C<ListFactory> to fill. The argument of
-ListFactoryEndLevel() cannot be used after a call to this function.
-
-=head2 DStrings
-
-Production of strings are still supported in B<portableTk>.
-
-=head2 Accessing C<Tcl_Obj *>s
-
-The following functions for getting a value of an C<Tcl_Obj *> I<may> be
-provided:
-
- double LangDouble(Tcl_Obj *)
- int LangInt(Tcl_Obj *)
- long LangLong(Tcl_Obj *)
- int LangIsList(Tcl_Obj * arg)
-
-The function LangIsList() is supported only partially under B<TCL>,
-since there is no data types. It checks whether there is a space
-inside the string C<arg>.
-
-=head2 Assigning numbers to C<Tcl_Obj *>s
-
-While LangSetDouble() and LangSetInt() are supported ways to assign
-numbers to assign an integer value to a variable, for the sake of
-efficiency under B<TCL> it is supposed that the destination of these
-commands was massaged before the call so it contains a long enough
-string to sprintf() the numbers inside it. If you are going to
-immediately use the resulting C<Tcl_Obj *>, the best way to do this is to
-declare a buffer in the beginning of a block by
-
- dArgBuffer;
-
-and assign this buffer to the C<Tcl_Obj *> by
-
- void LangSetDefaultBuffer(Tcl_Obj * *)
-
-You can also create the buffer(s) manually and assign them using
-
- void LangSetBuffer(Tcl_Obj * *, char *)
-
-This is the only choice if you need to assign numeric values to
-several C<Tcl_Obj *>s simultaneously. The advantage of the first approach is
-that the above declarations can be made C<nop>s in different languages.
-
-Note that if you apply C<LangSetDefaultBuffer> to an C<Tcl_Obj *> that
-contains some value, you can create a leak if you do not free that
-C<Tcl_Obj *> first. This is a non-problem in real languages, but can be a
-trouble in C<TCL>, unless you use only the above API.
-
-=head2 Creating new C<Tcl_Obj *>s
-
-The API for creating a new C<Tcl_Obj *> is
-
- void LangNewArg(Tcl_Obj * *, LangFreeProc *)
-
-The API for creating a new C<Tcl_Obj *> is absent. Just initialize C<Tcl_Obj *> to
-be C<NULL>, and apply one of C<LangSet...> methods.
-
-After you use this C<Tcl_Obj *>, it should be freed thusly:
-
-C<LangFreeArg(arg, freeProc)>.
-
-=head2 Evaluating a list
-
-Use
-
- int LangArgEval(Tcl_Interp *, Tcl_Obj * arg)
-
-Here C<arg> should be a list to evaluate, in particular, the first
-element should be a C<LangCallback> massaged to be an C<Tcl_Obj *>. The
-arguments can be send to the subroutine by reference or by value in
-different languages.
-
-=head2 Getting result as C<Tcl_Obj *>
-
-Use C<Tcl_ArgResult>. It is not guaranteed that result survives this
-operation, so the C<Tcl_Obj *> you get should be the only mean to access the
-data from this moment on. After you use this C<Tcl_Obj *>, you should free
-it with C<freeProc> C<LANG_DYNAMIC> (you can do LangSet...() in between).
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/pack.pod b/Master/tlpkg/tlperl/lib/Tk/pack.pod
deleted file mode 100644
index 0449556265c..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/pack.pod
+++ /dev/null
@@ -1,324 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::pack - Geometry manager that packs around edges of cavity
-
-=for category Tk Geometry Management
-
-=head1 SYNOPSIS
-
-S< >I<$widget>-E<gt>B<pack>?(I<args>)?
-
-S< >I<$widget>-E<gt>B<pack>I<Option>?(I<args>)?
-
-=head1 DESCRIPTION
-
-The B<pack> method is used to communicate with the packer,
-a geometry manager that arranges the children of a parent by
-packing them in order around the edges of the parent.
-
-In this B<perl> port of Tk it is normal to pack widgets one-at-a-time
-using the widget object to be packed to invoke a method call.
-This is a slight distortion of underlying Tk interface (which
-can handle lists of windows to one pack method call) but has proven
-effective in practice.
-
-The B<pack> method can have any of several forms, depending
-on I<Option>:
-
-=over 4
-
-=item I<$slave>-E<gt>B<pack>?(I<options>)?
-
-The options consist of pairs of arguments that specify how
-to manage the slave.
-See L<"THE PACKER ALGORITHM"> below for details on how the options
-are used by the packer.
-The following options are supported:
-
-=over 8
-
-=item B<-after> =E<gt> I<$other>
-
-I<$other> must be another window.
-Use its master as the master for the slave, and insert
-the slave just after I<$other> in the packing order.
-
-=item B<-anchor> =E<gt> I<anchor>
-
-I<Anchor> must be a valid anchor position such as B<n>
-or B<sw>; it specifies where to position each slave in its
-parcel.
-Defaults to B<center>.
-
-=item B<-before> =E<gt> I<$other>
-
-I<$other> must be another window.
-Use its master as the master for the slave, and insert
-the slave just before I<$other> in the packing order.
-
-=item B<-expand> =E<gt> I<boolean>
-
-Specifies whether the slave should be expanded to consume
-extra space in their master.
-I<Boolean> may have any proper boolean value, such as B<1>
-or B<no>.
-Defaults to 0.
-
-=item B<-fill> =E<gt> I<style>
-
-If a slave's parcel is larger than its requested dimensions, this
-option may be used to stretch the slave.
-I<Style> must have one of the following values:
-
-=over 12
-
-=item B<none>
-
-Give the slave its requested dimensions plus any internal padding
-requested with B<-ipadx> or B<-ipady>. This is the default.
-
-=item B<x>
-
-Stretch the slave horizontally to fill the entire width of its
-parcel (except leave external padding as specified by B<-padx>).
-
-=item B<y>
-
-Stretch the slave vertically to fill the entire height of its
-parcel (except leave external padding as specified by B<-pady>).
-
-=item B<both>
-
-Stretch the slave both horizontally and vertically.
-
-=back
-
-=item B<-in> =E<gt> I<$master>
-
-Insert the slave(s) at the end of the packing order for the master
-window given by I<$master>.
-
-=item B<-ipadx> =E<gt> I<amount>
-
-I<Amount> specifies how much horizontal internal padding to
-leave on each side of the slave(s).
-I<Amount> must be a valid screen distance, such as B<2> or B<.5c>.
-It defaults to 0.
-
-=item B<-ipady> =E<gt> I<amount>
-
-I<Amount> specifies how much vertical internal padding to
-leave on each side of the slave(s).
-I<Amount> defaults to 0.
-
-=item B<-padx> =E<gt> I<amount>
-
-I<Amount> specifies how much horizontal external padding to
-leave on each side of the slave(s).
-I<Amount> defaults to 0.
-
-=item B<-pady> =E<gt> I<amount>
-
-I<Amount> specifies how much vertical external padding to
-leave on each side of the slave(s).
-I<Amount> defaults to 0.
-
-=item B<-side> =E<gt> I<side>
-
-Specifies which side of the master the slave(s) will be packed against.
-Must be B<left>, B<right>, B<top>, or B<bottom>.
-Defaults to B<top>.
-
-=back
-
-=back
-
-If no B<-in>, B<-after> or B<-before> option is specified
-then slave will be inserted at the end of the packing list
-for its parent unless it is already managed by the packer (in which
-case it will be left where it is).
-If one of these options is specified then slave will be
-inserted at the specified point.
-If the slave are already managed by the geometry manager
-then any unspecified options for them retain their previous values rather
-than receiving default values.
-
-=over 4
-
-=item I<$slave>-E<gt>B<packConfigure>?(I<options>)?
-
-Same as B<pack>.
-
-=item I<$slave>-E<gt>B<packForget>
-
-Removes I<slave> from the packing order for its
-master and unmaps its window.
-The slave will no longer be managed by the packer.
-
-=item I<$slave>-E<gt>B<packInfo>
-
-Returns a list whose elements are the current configuration state of
-the slave given by I<$slave> in the same option-value form that
-might be specified to B<packConfigure>.
-The first two elements of the list are ``B<-in>=E<gt>I<$master>'' where
-I<$master> is the slave's master.
-
-=item I<$master>-E<gt>B<packPropagate>?(I<boolean>)?
-
-If I<boolean> has a true boolean value such as B<1> or B<on>
-then propagation is enabled for I<$master>,
-(see L<"GEOMETRY PROPAGATION"> below).
-If I<boolean> has a false boolean value then propagation is
-disabled for I<$master>.
-In either of these cases an empty string is returned.
-If I<boolean> is omitted then the method returns B<0> or
-B<1> to indicate whether propagation is currently enabled
-for I<$master>.
-Propagation is enabled by default.
-
-=item I<$master>-E<gt>B<packSlaves>
-
-Returns a list of all of the slaves in the packing order for I<$master>.
-The order of the slaves in the list is the same as their order in
-the packing order.
-If I<$master> has no slaves then an empty list/string is returned in
-array/scalar context, respectively
-
-=back
-
-=head1 THE PACKER ALGORITHM
-
-For each master the packer maintains an ordered list of slaves
-called the I<packing list>.
-The B<-in>, B<-after>, and B<-before> configuration
-options are used to specify the master for each slave and the slave's
-position in the packing list.
-If none of these options is given for a slave then the slave
-is added to the end of the packing list for its parent.
-
-The packer arranges the slaves for a master by scanning the
-packing list in order.
-At the time it processes each slave, a rectangular area within
-the master is still unallocated.
-This area is called the I<cavity>; for the first slave it
-is the entire area of the master.
-
-For each slave the packer carries out the following steps:
-
-=over 4
-
-=item [1]
-
-The packer allocates a rectangular I<parcel> for the slave
-along the side of the cavity given by the slave's B<-side> option.
-If the side is top or bottom then the width of the parcel is
-the width of the cavity and its height is the requested height
-of the slave plus the B<-ipady> and B<-pady> options.
-For the left or right side the height of the parcel is
-the height of the cavity and the width is the requested width
-of the slave plus the B<-ipadx> and B<-padx> options.
-The parcel may be enlarged further because of the B<-expand>
-option (see L<"EXPANSION"> below)
-
-=item [2]
-
-The packer chooses the dimensions of the slave.
-The width will normally be the slave's requested width plus
-twice its B<-ipadx> option and the height will normally be
-the slave's requested height plus twice its B<-ipady>
-option.
-However, if the B<-fill> option is B<x> or B<both>
-then the width of the slave is expanded to fill the width of the parcel,
-minus twice the B<-padx> option.
-If the B<-fill> option is B<y> or B<both>
-then the height of the slave is expanded to fill the width of the parcel,
-minus twice the B<-pady> option.
-
-=item [3]
-
-The packer positions the slave over its parcel.
-If the slave is smaller than the parcel then the B<-anchor>
-option determines where in the parcel the slave will be placed.
-If B<-padx> or B<-pady> is non-zero, then the given
-amount of external padding will always be left between the
-slave and the edges of the parcel.
-
-Once a given slave has been packed, the area of its parcel
-is subtracted from the cavity, leaving a smaller rectangular
-cavity for the next slave.
-If a slave doesn't use all of its parcel, the unused space
-in the parcel will not be used by subsequent slaves.
-If the cavity should become too small to meet the needs of
-a slave then the slave will be given whatever space is
-left in the cavity.
-If the cavity shrinks to zero size, then all remaining slaves
-on the packing list will be unmapped from the screen until
-the master window becomes large enough to hold them again.
-
-=back
-
-=head1 EXPANSION
-
-If a master window is so large that there will be extra space
-left over after all of its slaves have been packed, then the
-extra space is distributed uniformly among all of the slaves
-for which the B<-expand> option is set.
-Extra horizontal space is distributed among the expandable
-slaves whose B<-side> is B<left> or B<right>,
-and extra vertical space is distributed among the expandable
-slaves whose B<-side> is B<top> or B<bottom>.
-
-=head1 GEOMETRY PROPAGATION
-
-The packer normally computes how large a master must be to
-just exactly meet the needs of its slaves, and it sets the
-requested width and height of the master to these dimensions.
-This causes geometry information to propagate up through a
-window hierarchy to a top-level window so that the entire
-sub-tree sizes itself to fit the needs of the leaf windows.
-However, the B<packPropagate> method may be used to
-turn off propagation for one or more masters.
-If propagation is disabled then the packer will not set
-the requested width and height of the packer.
-This may be useful if, for example, you wish for a master
-window to have a fixed size that you specify.
-
-=head1 RESTRICTIONS ON MASTER WINDOWS
-
-The master for each slave must either be the slave's parent
-(the default) or a descendant of the slave's parent.
-This restriction is necessary to guarantee that the
-slave can be placed over any part of its master that is
-visible without danger of the slave being clipped by its parent.
-
-=head1 PACKING ORDER
-
-If the master for a slave is not its parent then you must make sure
-that the slave is higher in the stacking order than the master.
-Otherwise the master will obscure the slave and it will appear as
-if the slave hasn't been packed correctly.
-The easiest way to make sure the slave is higher than the master is
-to create the master window first: the most recently created window
-will be highest in the stacking order.
-Or, you can use the B<raise> and B<lower> methods to change
-the stacking order of either the master or the slave.
-
-=head1 SEE ALSO
-
-L<Tk::form|Tk::form>
-L<Tk::grid|Tk::grid>
-L<Tk::place|Tk::place>
-
-=head1 KEYWORDS
-
-geometry manager, location, packer, parcel, propagation, size
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/palette.pod b/Master/tlpkg/tlperl/lib/Tk/palette.pod
deleted file mode 100644
index 40a6914fd5c..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/palette.pod
+++ /dev/null
@@ -1,89 +0,0 @@
-# Copyright (c) 1995-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-setPalette, bisque - Modify the Tk color palette
-
-=for category Creating and Configuring Widgets
-
-=head1 SYNOPSIS
-
-I<$widget>-E<gt>B<setPalette>(I<background>)
-
-I<$widget>-E<gt>B<setPalette(>I<name>=E<gt>I<value>?,I<name>=E<gt>I<value ...>?)
-
-I<$widget>-E<gt>B<bisque>
-
-=head1 DESCRIPTION
-
-The B<setPalette> method changes the color scheme for Tk.
-It does this by modifying the colors of existing widgets and by changing
-the option database so that future widgets will use the new color scheme.
-If B<setPalette> is invoked with a single argument, the
-argument is the name of a color to use as the normal background
-color; B<setPalette> will compute a complete color palette
-from this background color.
-Alternatively, the arguments to B<setPalette> may consist of any number
-of I<name>-I<value> pairs, where the first argument of the pair
-is the name of an option in the Tk option database and the second
-argument is the new value to use for that option. The following
-database names are currently supported:
-
- activeBackground foreground selectColor
- activeForeground highlightBackground selectBackground
- background highlightColor selectForeground
- disabledForeground insertBackground troughColor
-
-B<setPalette> tries to compute reasonable defaults for any
-options that you don't specify. You can specify options other
-than the above ones and Tk will change those options on widgets as
-well. This feature may be useful if you are using custom widgets with
-additional color options.
-
-Once it has computed the new value to use for each of the color options,
-B<setPalette> scans the widget hierarchy to modify the options
-of all existing widgets. For each widget, it checks to see if any
-of the above options is defined for the widget. If so, and if the
-option's current value is the default, then the value is changed; if
-the option has a value other than the default, B<setPalette>
-will not change it. The default for an option is the one provided by
-the widget (B<($w-E<gt>configure('option'))[3]>) unless
-B<setPalette> has been run previously, in which case it is the
-value specified in the previous invocation of B<setPalette>.
-
-After modifying all the widgets in the application, B<setPalette>
-adds options to the option database to change the defaults for
-widgets created in the future. The new options are added at
-priority B<widgetDefault>, so they will be overridden by options
-from the .Xdefaults file or options specified on the command-line
-that creates a widget.
-
-The method B<bisque> is provided for backward compatibility:
-it restores the application's colors to the light brown (``bisque'')
-color scheme used in Tk 3.6 and earlier versions.
-
-=head1 BUGS
-
-The use of option database names rather than the configure names is
-understandable given the mechanism (copied from Tcl/Tk), but
-is potentially confusing.
-
-The interpolation of different 'shades' of color used for 3D effects
-in 'RGB' space can lead to undesirable changes in 'hue'.
-Interpolation in 'HSV' (as used in B<Tk::ColorEditor>) would be more
-robust and X11R5's color support probably even more so.
-
-=head1 SEE ALSO
-
-L<Tk::options|Tk::options>
-
-=head1 KEYWORDS
-
-bisque, color, palette
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/place.pod b/Master/tlpkg/tlperl/lib/Tk/place.pod
deleted file mode 100644
index 9f7e74f210f..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/place.pod
+++ /dev/null
@@ -1,283 +0,0 @@
-# Copyright (c) 1992 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::place - Geometry manager for fixed or rubber-sheet placement
-
-=for category Tk Geometry Management
-
-=head1 SYNOPSIS
-
-S< >I<$widget>->B<place>?(I<-option>=>I<value>?, I<-option>=>I<value>, ...)?
-
-S< >I<$widget>->B<placeForget>
-
-S< >I<$widget>->B<placeInfo>
-
-S< >I<$master>->B<placeSlaves>
-
-=head1 DESCRIPTION
-
-The placer is a geometry manager for Tk.
-It provides simple fixed placement of windows, where you specify
-the exact size and location of one window, called the I<slave>,
-within another window, called the I<master>.
-The placer also provides rubber-sheet placement, where you specify the
-size and location of the slave in terms of the dimensions of
-the master, so that the slave changes size and location
-in response to changes in the size of the master.
-Lastly, the placer allows you to mix these styles of placement so
-that, for example, the slave has a fixed width and height but is
-centered inside the master.
-
-=over 4
-
-=item I<$slave>->B<place>?(I<-option>=>I<value>?, I<-option>=>I<value>, ...?)?
-
-The B<place> method arranges for the placer
-to manage the geometry of I<$slave>.
-The remaining arguments consist of one or more I<-option>=>I<value>
-pairs that specify the way in which I<$slave>'s
-geometry is managed. I<-option> may have any of the values accepted
-by the L<< placeConfigure|/$slave->placeConfigure >> method.
-
-The B<place> method returns I<$slave>.
-
-=item I<$slave>->B<placeConfigure>?(I<-option>=>I<value>?, I<-option>=>I<value>, ...?)?
-
-Query or modify the geometry options of the I<$slave>. If no option is
-specified, this method returns a list describing the available
-options (see Tk_ConfigureInfo for information on the format of this
-list). If option is specified with no value, then the command returns
-a list describing the one named option (this list will be identical to
-the corresponding sublist of the value returned if no option is
-specified). If one or more option-value pairs are specified, then the
-method modifies the given option(s) to have the given value(s); in
-this case the command returns C<undef>.
-
-The following I<-option>=>I<value> pairs are supported:
-
-=over 8
-
-=item B<-anchor> => I<where>
-
-I<Where> specifies which point of I<$slave> is to be positioned
-at the (x,y) location selected by the B<-x>, B<-y>,
-B<-relx>, and B<-rely> options.
-The anchor point is in terms of the outer area of I<$slave>
-including its border, if any.
-Thus if I<where> is B<se> then the lower-right corner of
-I<$slave>'s border will appear at the given (x,y) location
-in the master.
-The anchor position defaults to B<nw>.
-
-=item B<-bordermode> => I<mode>
-
-I<Mode> determines the degree to which borders within the
-master are used in determining the placement of the slave.
-The default and most common value is B<inside>.
-In this case the placer considers the area of the master to
-be the innermost area of the master, inside any border:
-an option of B<-x>=>B<0> corresponds to an x-coordinate just
-inside the border and an option of B<-relwidth>=>1.0
-means I<$slave> will fill the area inside the master's
-border.
-If I<mode> is B<outside> then the placer considers
-the area of the master to include its border;
-this mode is typically used when placing I<$slave>
-outside its master, as with the options
-B<-x>=>B<0>, B<-y>=>B<0>, B<-anchor>=>B<ne>.
-Lastly, I<mode> may be specified as B<ignore>, in which
-case borders are ignored: the area of the master is considered
-to be its official X area, which includes any internal border but
-no external border. A bordermode of B<ignore> is probably
-not very useful.
-
-=item B<-height> => I<size>
-
-I<Size> specifies the height for I<$slave> in screen units
-(i.e. any of the forms accepted by B<Tk_GetPixels>).
-The height will be the outer dimension of I<$slave> including its
-border, if any.
-If I<size> is an empty string, or if no B<-height> or
-B<-relheight> option is specified, then the height requested
-internally by the window will be used.
-
-=item B<-in> => I<$master>
-
-I<$master> is the reference to the window relative
-to which I<$slave> is to be placed.
-I<$master> must either be I<$slave>'s parent or a descendant
-of I<$slave>'s parent.
-In addition, I<$master> and I<$slave> must both be descendants
-of the same top-level window.
-These restrictions are necessary to guarantee
-that I<$slave> is visible whenever I<$master> is visible.
-If this option isn't specified then the master defaults to
-I<$slave>'s parent.
-
-=item B<-relheight> => I<size>
-
-I<Size> specifies the height for I<$slave>.
-In this case the height is specified as a floating-point number
-relative to the height of the master: 0.5 means I<$slave> will
-be half as high as the master, 1.0 means I<$slave> will have
-the same height as the master, and so on.
-If both B<-height> and B<-relheight> are specified for a slave,
-their values are summed. For example, B<-relheight>=>1.0, B<-height>=>-2
-makes the slave 2 pixels shorter than the master.
-
-=item B<-relwidth> => I<size>
-
-I<Size> specifies the width for I<$slave>.
-In this case the width is specified as a floating-point number
-relative to the width of the master: 0.5 means I<$slave> will
-be half as wide as the master, 1.0 means I<$slave> will have
-the same width as the master, and so on.
-If both B<-width> and B<-relwidth> are specified for a slave,
-their values are summed. For example, B<-relwidth>=>1.0, B<-width>=>5
-makes the slave 5 pixels wider than the master.
-
-=item B<-relx> => I<location>
-
-I<Location> specifies the x-coordinate within the master window
-of the anchor point for I<$slave> widget.
-In this case the location is specified in a relative fashion
-as a floating-point number: 0.0 corresponds to the left edge
-of the master and 1.0 corresponds to the right edge of the master.
-I<Location> need not be in the range 0.0-1.0.
-If both B<-x> and B<-relx> are specified for a slave
-then their values are summed. For example, "B<-relx>=>0.5, B<-x>=-2"
-positions the left edge of the slave 2 pixels to the left of the
-center of its master.
-
-=item B<-rely> => I<location>
-
-I<Location> specifies the y-coordinate within the master window
-of the anchor point for I<$slave> widget.
-In this case the value is specified in a relative fashion
-as a floating-point number: 0.0 corresponds to the top edge
-of the master and 1.0 corresponds to the bottom edge of the master.
-I<Location> need not be in the range 0.0-1.0.
-If both B<-y> and B<-rely> are specified for a slave
-then their values are summed. For example, B<-rely>=>0.5, B<-x>=>3
-positions the top edge of the slave 3 pixels below the
-center of its master.
-
-=item B<-width> => I<size>
-
-I<Size> specifies the width for I<$slave> in screen units
-(i.e. any of the forms accepted by B<Tk_GetPixels>).
-The width will be the outer width of I<$slave> including its
-border, if any.
-If I<size> is an empty string, or if no B<-width>
-or B<-relwidth> option is specified, then the width requested
-internally by the window will be used.
-
-=item B<-x> => I<location>
-
-I<Location> specifies the x-coordinate within the master window
-of the anchor point for I<$slave> widget.
-The location is specified in screen units (i.e. any of the forms
-accepted by B<Tk_GetPixels>) and need not lie within the bounds
-of the master window.
-
-=item B<-y> => I<location>
-
-I<Location> specifies the y-coordinate within the master window
-of the anchor point for I<$slave> widget.
-The location is specified in screen units (i.e. any of the forms
-accepted by B<Tk_GetPixels>) and need not lie within the bounds
-of the master window.
-
-=back
-
-If the same value is specified separately with
-two different options, such as B<-x> and B<-relx>, then
-the most recent option is used and the older one is ignored.
-
-=item I<$slave>->B<placeForget>
-
-The B<placeForget> method causes the placer to stop managing
-the geometry of I<$slave>. As a side effect of this method call
-I<$slave> will be unmapped so that it doesn't appear on the
-screen.
-If I<$slave> isn't currently managed by the placer then the
-method call has no effect.
-B<placeForget> returns an empty string as result.
-
-=item I<$slave>->B<placeInfo>
-
-The B<placeInfo> method returns a list giving the current
-configuration of I<$slave>.
-The list consists of I<-option>=>I<value> pairs in exactly the
-same form as might be specified to the B<place>
-method.
-
-=item I<$slave>->B<placeSlaves>
-
-The B<placeSlaves> method returns a list of all the slave
-windows for which I<$master> is the master.
-If there are no slaves for I<$master> then an empty list is
-returned.
-
-=back
-
-If the configuration of a window has been retrieved with
-B<placeInfo>, that configuration can be restored later by
-first using B<placeForget> to erase any existing information
-for the window and then invoking B<place> with
-the saved information.
-
-=head1 FINE POINTS
-
-It is not necessary for the master window to be the parent
-of the slave window.
-This feature is useful in at least two situations.
-First, for complex window layouts it means you can create a
-hierarchy of subwindows whose only purpose
-is to assist in the layout of the parent.
-The ``I<real children>'' of the parent (i.e. the windows that
-are significant for the application's user interface) can be
-children of the parent yet be placed inside the windows
-of the geometry-management hierarchy.
-This means that the path names of the ``I<real children>''
-don't reflect the geometry-management hierarchy and users
-can specify options for the real children
-without being aware of the structure of the geometry-management
-hierarchy.
-
-A second reason for having a master different than the slave's
-parent is to tie two siblings together.
-For example, the placer can be used to force a window always to
-be positioned centered just below one of its
-siblings by specifying the configuration
-
-S< >B<-in>=>I<$sibling>, B<-relx>=>0.5, B<-rely>=>1.0,
-B<-anchor>=>'n', B<-bordermode>=>'outside'
-
-Whenever the I<$sibling> widget is repositioned in the future, the slave
-will be repositioned as well.
-
-Unlike many other geometry managers (such as the packer)
-the placer does not make any attempt to manipulate the geometry of
-the master windows or the parents of slave windows (i.e. it doesn't
-set their requested sizes).
-To control the sizes of these windows, make them windows like
-frames and canvases that provide configuration options for this purpose.
-
-=head1 SEE ALSO
-
-L<Tk::form>, L<Tk::grid>, L<Tk::pack>
-
-=head1 KEYWORDS
-
-geometry manager, height, location, master, place, rubber sheet, slave, width
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/selection.pod b/Master/tlpkg/tlperl/lib/Tk/selection.pod
deleted file mode 100644
index f8a3ce54856..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/selection.pod
+++ /dev/null
@@ -1,159 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Selection - Manipulate the X selection
-
-=for category User Interaction
-
-=head1 SYNOPSIS
-
-I<$widget>-E<gt>B<Selection>I<Option>?(I<args>)?
-
-=head1 DESCRIPTION
-
-This command provides an interface to the X selection mechanism and
-implements the full selection functionality described in the
-X Inter-Client Communication Conventions Manual (ICCCM).
-
-The widget object used to invoke the methods below determines which
-display is used to access the selection.
-In order to avoid conflicts with B<selection> methods of widget classes
-(e.g. B<Text>) this set of methods uses the prefix B<Selection>.
-The following methods are currently supported:
-
-=over 4
-
-=item I<$widget>-E<gt>B<SelectionClear>?(B<-selection>=E<gt>I<selection>)?
-
-If I<selection> exists anywhere on I<$widget>'s display, clear it
-so that no window owns the selection anymore. I<Selection>
-specifies the X selection that should be cleared, and should be an
-atom name such as PRIMARY or CLIPBOARD; see the Inter-Client
-Communication Conventions Manual for complete details.
-I<Selection> defaults to PRIMARY.
-Returns an empty string.
-
-=item I<$widget>-E<gt>B<SelectionGet>?(?B<-selection>=E<gt>I<selection>?,?B<-type>=E<gt>I<type>?)?
-
-Retrieves the value of I<selection> from I<$widget>'s display and
-returns it as a result. I<Selection> defaults to PRIMARY.
-
-I<Type> specifies the form in which the selection is to be returned
-(the desired ``target'' for conversion, in ICCCM terminology), and
-should be an atom name such as STRING or FILE_NAME; see the
-Inter-Client Communication Conventions Manual for complete details.
-I<Type> defaults to STRING. The selection owner may choose to
-return the selection in any of several different representation
-formats, such as STRING, ATOM, INTEGER, etc. (this format is different
-than the selection type; see the ICCCM for all the confusing details).
-
-If I<format> is not STRING then things get messy, the following
-description is from the Tcl/Tk man page as yet incompetely translated for
-the perl version - it is misleading at best.
-
-If the selection is returned in a non-string format, such as INTEGER
-or ATOM, the B<SelectionGet> converts it to a list of perl
-values: atoms are converted to their
-textual names, and anything else is converted integers.
-
-A goal of the perl port is to provide better handling of different
-formats than Tcl/Tk does, which should be possible given perl's
-wider range of ``types''. Although some thought went into this
-in very early days of perl/Tk what exactly happens is still
-"not quite right" and subject to change.
-
-=item I<$widget>-E<gt>B<SelectionHandle>(?B<-selection>=E<gt>I<selection>?,?B<-type>=E<gt>I<type>?,?B<-format>=E<gt>I<format>? I<callback>)
-
-Creates a handler for selection requests, such that I<callback> will
-be executed whenever I<selection> is owned by I<$widget> and
-someone attempts to retrieve it in the form given by I<type>
-(e.g. I<type> is specified in the B<selection get> command).
-I<Selection> defaults to PRIMARY, I<type> defaults to STRING, and
-I<format> defaults to STRING. If I<callback> is an empty string
-then any existing handler for I<$widget>, I<type>, and
-I<selection> is removed.
-
-When I<selection> is requested, I<$widget> is the selection owner,
-and I<type> is the requested type, I<callback> will be executed
-with two additional arguments.
-The two additional arguments
-are I<offset> and I<maxBytes>: I<offset> specifies a starting
-character position in the selection and I<maxBytes> gives the maximum
-number of bytes to retrieve. The command should return a value consisting
-of at most I<maxBytes> of the selection, starting at position
-I<offset>. For very large selections (larger than I<maxBytes>)
-the selection will be retrieved using several invocations of I<callback>
-with increasing I<offset> values. If I<callback> returns a string
-whose length is less than I<maxBytes>, the return value is assumed to
-include all of the remainder of the selection; if the length of
-I<callback>'s result is equal to I<maxBytes> then
-I<callback> will be invoked again, until it eventually
-returns a result shorter than I<maxBytes>. The value of I<maxBytes>
-will always be relatively large (thousands of bytes).
-
-If I<callback> returns an error (e.g. via B<die>)
-then the selection retrieval is rejected
-just as if the selection didn't exist at all.
-
-The I<format> argument specifies the representation that should be
-used to transmit the selection to the requester (the second column of
-Table 2 of the ICCCM), and defaults to STRING. If I<format> is
-STRING, the selection is transmitted as 8-bit ASCII characters (i.e.
-just in the form returned by I<command>).
-
-If I<format> is not STRING then things get messy, the following
-description is from the Tcl/Tk man page as yet untranslated for
-the perl version - it is misleading at best.
-
-If I<format> is
-ATOM, then the return value from I<command> is divided into fields
-separated by white space; each field is converted to its atom value,
-and the 32-bit atom value is transmitted instead of the atom name.
-For any other I<format>, the return value from I<command> is
-divided into fields separated by white space and each field is
-converted to a 32-bit integer; an array of integers is transmitted
-to the selection requester.
-
-The I<format> argument is needed only for compatibility with
-many selection requesters, except Tcl/Tk. If Tcl/Tk is being
-used to retrieve the selection then the value is converted back to
-a string at the requesting end, so I<format> is
-irrelevant.
-
-A goal of the perl port is to provide better handling of different
-formats than Tcl/Tk does, which should be possible given perl's
-wider range of ``types''. Although some thought went into this
-in very early days of perl/Tk what exactly happens is still
-"not quite right" and subject to change.
-
-=item I<$widget>-E<gt>B<SelectionOwner>?(B<-selection>=E<gt>I<selection>)?
-
-B<SelectionOwner> returns the
-window in this application that owns I<selection> on the display
-containing I<$widget>, or an empty string if no window in this
-application owns the selection. I<Selection> defaults to PRIMARY.
-
-=item I<$widget>-E<gt>B<SelectionOwn>?(?B<-command>=E<gt>I<callback>?,?B<-selection>=E<gt>I<selection>?)?
-
-B<SelectionOwn> causes I<$widget> to become
-the new owner of I<selection> on I<$widget>'s display, returning
-an empty string as result. The existing owner, if any, is notified
-that it has lost the selection.
-If I<callback> is specified, it will be executed when
-some other window claims ownership of the selection away from
-I<$widget>. I<Selection> defaults to PRIMARY.
-
-=back
-
-=head1 KEYWORDS
-
-clear, format, handler, ICCCM, own, selection, target, type
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/send.pod b/Master/tlpkg/tlperl/lib/Tk/send.pod
deleted file mode 100644
index 40382f2422d..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/send.pod
+++ /dev/null
@@ -1,118 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-send - Execute a command in a different application
-
-=for category Tk Generic Methods
-
-=head1 SYNOPSIS
-
-S< >I<$result> = I<$widget>-E<gt>B<send>(?I<options>,?I<app>=E<gt>I<cmd>?I<arg arg ...>?)
-
-=head1 DESCRIPTION
-
-This method arranges for I<cmd> (and I<arg>s) to be 'sent' to the
-application named by I<app>. It returns the result or
-an error (hence above should probably be 'wrapped' in B<eval{}> and $@ tested).
-I<App> may be the name of any application whose main window is
-on the display containing the sender's main window; it need not
-be within the same process.
-If no I<arg> arguments are present, then the string to be sent
-is contained entirely within the I<cmd> argument. If one or
-more I<arg>s are present, they are concatenated separated by white space to
-form the string to be sent.
-
-If the initial arguments of the call begin with ``-''
-they are treated as options. The following options are
-currently defined:
-
-=over 4
-
-=item B<-async>
-
-Requests asynchronous invocation. In this case the B<send>
-command will complete immediately without waiting for I<cmd>
-to complete in the target application; no result will be available
-and errors in the sent command will be ignored.
-If the target application is in the same process as the sending
-application then the B<-async> option is ignored.
-
-=item B<-->
-
-Serves no purpose except to terminate the list of options. This
-option is needed only if I<app> could contain a leading ``-''
-character.
-
-=back
-
-=head1 APPLICATION NAMES
-
-The name of an application is set initially from the name of the
-program or script that created the application.
-You can query and change the name of an application with the
-B<appname> method.
-
-=head1 WHAT IS A SEND
-
-The B<send> mechanism was designed to allow Tcl/Tk applications
-to send Tcl Scripts to each other. This does not map very well onto perl/Tk.
-Perl/Tk "sends" a string to I<app>, what happens as a result of this
-depends on the receiving application. If the other application is a Tcl/Tk4.*
-application it will be treated as a Tcl Script. If the "other" application is
-perl/Tk application (including sends to self) then the string is
-passed as an argument to a method call of the following form:
-
-I<$mainwindow>-E<gt>B<Receive(>I<string>);
-
-There is a default (AutoLoaded) B<Tk::Receive> which returns an error to the
-sending application. A particular application may define its own
-B<Receive> method in any class in B<MainWindow>'s inheritance tree
-to do whatever it sees fit. For example it could B<eval> the string,
-possibly in a B<Safe> "compartment".
-
-If a Tcl/Tk application "sends" anything to a perl/Tk application
-then the perl/Tk application would have to attempt to interpret the
-incoming string as a Tcl Script. Simple cases are should not be too hard to
-emulate (split on white space and treat first element as "command" and other
-elements as arguments).
-
-=head1 SECURITY
-
-The B<send> command is potentially a serious security loophole,
-since any application that can connect to your X server can send
-scripts to your applications. Hence the default behaviour outlined above.
-(With the availability of B<Safe> it may make sense to relax default behaviour
-a little.)
-
-Unmonitored B<eval>'ing of these incoming "scripts" can cause perl to
-read and write files and invoke subprocesses under your name.
-Host-based access control such as that provided by B<xhost>
-is particularly insecure, since it allows anyone with an account
-on particular hosts to connect to your server, and if disabled it
-allows anyone anywhere to connect to your server.
-In order to provide at least a small amount of
-security, core Tk checks the access control being used by the server
-and rejects incoming sends unless (a) B<xhost>-style access control
-is enabled (i.e. only certain hosts can establish connections) and (b) the
-list of enabled hosts is empty.
-This means that applications cannot connect to your server unless
-they use some other form of authorization
-such as that provide by B<xauth>.
-
-=head1 SEE ALSO
-
-L<perlfunc/eval>, L<Safe>,
-system's administrator/corporate security guidelines etc.
-
-=head1 KEYWORDS
-
-application, name, remote execution, security, send
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/tixWm.pod b/Master/tlpkg/tlperl/lib/Tk/tixWm.pod
deleted file mode 100644
index 9bdd02d461c..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/tixWm.pod
+++ /dev/null
@@ -1,73 +0,0 @@
-
-
-=head1 NAME
-
-Tk::tixWm - Tix's addition to the standard TK wm command.
-
-=for category Tix Extensions
-
-=head1 SYNOPSIS
-
-S< >I<$widget>-E<gt>B<wmCapture>
-
-S< >I<$widget>-E<gt>B<wmRelease>
-
-=head1 DESCRIPTION
-
-The B<wmCapture> and the B<wmRelease> methods change the
-toplevel attribute of Tk widgets.
-
-=head1 METHODS
-
-=over 4
-
-=item I<$widget>-E<gt>B<wmCapture>
-
-Converts the toplevel window specified by I<$widget> into a non-toplevel
-widget. Normally this command is called to convert a L<Toplevel|Tk::Toplevel> widget
-into a L<Frame|Tk::Frame> widget. The newly-converted frame widget is
-un-mapped from the screen. To make it appear inside its parent, you
-must call a geometry manager (e.g. grid or pack) explictly.
-
-=item I<$widget>-E<gt>B<wmRelease>
-
-Makes the non-toplevel window specified by I<$widget> into a toplevel
-widget. Normally this command is called to convert a L<Frame|Tk::Frame> widget
-into a L<Toplevel|Tk::Toplevel> widget, but it can also be used on any
-non-toplevel widget (e.g, label). The newly-converted toplevel window
-is in a B<withdrawn> state. To make it appear on the screen, you must call
-B<deiconify> after calling B<wmRelease>.
-
-Any data associated with I<$widget> via B<wm> methods (icon, protocol,
-command etc.) are released, and must be re-established if window is later
-re-captured.
-
-=back
-
-=head1 BUGS
-
-B<wmCapture> does not exist in the Win32 window manager code.
-
-How these methods interact with perl/Tk's class hierarchy is not yet clear.
-In particular a B<wmRelease>d window will not automatically ``I<inherit>''
-the B<Tk::Wm> methods, however a B<wmCapture>d window still will.
-(A B<release>d B<Label> might make a good candidate for an B<Icon>.)
-
-=head1 AUTHORS
-
-Ioi Kim Lam - ioi@graphics.cis.upenn.edu wrote original Tix version.
-Updated for tk8.0, Win32 and perl by Nick Ing-Simmons.
-
-=head1 SEE ALSO
-
-L<Tk::Wm|Tk::Wm>
-L<Tk::Mwm|Tk::Mwm>
-L<Tk::Frame|Tk::Frame>
-L<Tk::Toplevel|Tk::Toplevel>
-
-=head1 KEYWORDS
-
-window manager, wm, TIX
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/tkvars.pod b/Master/tlpkg/tlperl/lib/Tk/tkvars.pod
deleted file mode 100644
index 5ae8ac477ef..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/tkvars.pod
+++ /dev/null
@@ -1,107 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-tkvars - Variables used or set by Tk
-
-=for category Tk Generic Methods
-
-=head1 DESCRIPTION
-
-The following perl variables are either set or used by Tk at various times
-in its execution. (For a list of variables used by perl see L<perlvar>.)
-
-=over 4
-
-=item B<$Tk::library>
-
-This variable holds the file name for a directory containing the modules
-related to Tk. These modules include an initialization
-file that is normally processed whenever a Tk application starts up,
-plus other files containing procedures that implement default behaviors
-for widgets.
-The initial value of B<$Tk::library> is set when Tk is added to
-an interpreter; this is done by searching searching for a directory
-named Tk in the directory where the file F<Tk.pm>, or the first
-directory F<Tk> in C<@INC>.
-
-The B<TK_LIBRARY> environment variable used by Tcl/Tk is not
-supported by perl/Tk. Please use L<@INC|perlvar/@INC> to change where modules
-are searched.
-
-B<Note:> This is Tcl remnant. With perl it makes more sense to
-use C<@INC> and C<%INC>).
-
-=item B<$Tk::patchLevel>
-
-Contains a decimal integer giving the current patch level for Tk.
-The patch level is incremented for each new release or patch, and
-it uniquely identifies an official version of Tk.
-
-B<Note:> this is Tcl remnant. With perl it makes more sense to
-use B<$Tk::VERSION> described below.
-
-=item B<$Tk::strictMotif>
-
-This variable is set to zero by default.
-If an application sets it to one, then Tk attempts to adhere as
-closely as possible to Motif look-and-feel standards.
-For example, active elements such as buttons and scrollbar
-sliders will not change color when the pointer passes over them.
-
-=item B<$Tk::VERSION>
-
-The variable holds the current version number of the perl/Tk
-release in the form I<major>.I<minor>. I<Major> and
-I<minor> are integers.
-
-The I<major> version number shows on which
-Tcl/Tk release perl/Tk is based. E.g., B<402> means based on
-Tcls Tk 4.2. (Patchlevel of Tcls Tk are not incorporated because
-perl/Tk tended to be ``I<ahead>'' of them on some fixes and behind on
-others. The first digest of the major version number increases in
-any Tk release that includes changes that are not backward compatible
-(i.e. whenever existing perl/Tk applications and scripts may have to change to
-work with the new release).
-
-The I<minor> version depends on perl/Tk only. It uses the
-'even'='stable', 'odd'='experimental' scheme that linux uses:
-
- .0xx - inherently 'alpha'
- .1xx - experimental 'beta'
- .2xx - stable
- .3xx - experimental
- .4xx - stable
- ...
-
-The minor version number increases with
-each new release of Tk, except that it resets to zero whenever the
-major version number changes.
-
-=item B<$Tk::version>
-
-The variable holds the current version number of the Tk
-library in the form I<major>.I<minor>. I<Major> and
-I<minor> are integers. The major version number increases in
-any Tk release that includes changes that are not backward compatible
-(i.e. whenever existing Tk applications and scripts may have to change to
-work with the new release). The minor version number increases with
-each new release of Tk, except that it resets to zero whenever the
-major version number changes.
-
-B<Note:> this is Tcl remnant. With perl it makes more sense to
-use B<$Tk::VERSION> described above.
-
-=back
-
-=head1 KEYWORDS
-
-variables, version
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Tk/widgets.pod b/Master/tlpkg/tlperl/lib/Tk/widgets.pod
deleted file mode 100644
index 114f52505d7..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/widgets.pod
+++ /dev/null
@@ -1,20 +0,0 @@
-
-=head1 NAME
-
-Tk::widgets - preload widget classes
-
-=for pm Tk/widgets.pm
-
-=for category Implementation
-
-=head1 SYNOPSIS
-
- use Tk::widgets qw(Button Label Frame);
-
-=head1 DESCRIPTION
-
-Does a 'require Tk::Foo' for each 'Foo' in the list.
-May speed startup by avoiding AUTOLOADs.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/Win32/OLE/NEWS.pod b/Master/tlpkg/tlperl/lib/Win32/OLE/NEWS.pod
deleted file mode 100644
index 1de6b7ce0a5..00000000000
--- a/Master/tlpkg/tlperl/lib/Win32/OLE/NEWS.pod
+++ /dev/null
@@ -1,380 +0,0 @@
-=pod
-
-=head1 NAME
-
-Win32::OLE::NEWS - What's new in Win32::OLE
-
-This file contains a history of user visible changes to the
-Win32::OLE::* modules. Only new features and major bug fixes that
-might affect backwards compatibility are included.
-
-=head1 Version 0.18
-
-=head2 VT_CY and VT_DECIMAL return values handled differently
-
-The new C<Variant> option enables values of VT_CY or VT_DECIMAL type
-to be returned as Win32::OLE::Variant objects instead of being
-converted into strings and numbers respectively. This is similar to
-the change in Win32::OLE version 0.12 to VT_DATE and VT_ERROR values.
-The Win32::OLE::Variant module must be included to make sure that
-VT_CY and VT_DECIMAL values behave as before in numeric or string
-contexts.
-
-Because the new behavior is potentially incompatible, it must be
-explicitly enabled:
-
- Win32::OLE->Option(Variant => 1);
-
-
-=head1 Version 0.17
-
-=head2 New nullstring() function in Win32::OLE::Variant
-
-The nullstring() function returns a VT_BSTR variant containing a NULL
-string pointer. Note that this is not the same as a VT_BSTR variant
-containing the empty string "".
-
-The nullstring() return value is equivalent to the Visual Basic
-C<vbNullString> constant.
-
-
-=head1 Version 0.16
-
-=head2 Improved Unicode support
-
-Passing Unicode strings to methods and properties as well as returning
-Unicode strings back to Perl works now with both Perl 5.6 and 5.8.
-Note that the Unicode support in 5.8 is much more complete than in 5.6
-or 5.6.1.
-
-C<Unicode::String> objects can now be passed to methods or assigned to
-properties.
-
-You must enable Unicode support by switching Win32::OLE to the UTF8
-codepage:
-
- Win32::OLE->Option(CP => Win32::OLE::CP_UTF8());
-
-
-=head1 Version 0.13
-
-=head2 New nothing() function in Win32::OLE::Variant
-
-The nothing() function returns an empty VT_DISPATCH variant. It can be
-used to clear an object reference stored in a property
-
- use Win32::OLE::Variant qw(:DEFAULT nothing);
- # ...
- $object->{Property} = nothing;
-
-This has the same effect as the Visual Basic statement
-
- Set object.Property = Nothing
-
-=head2 New _NewEnum and _Unique options
-
-There are two new options available for the Win32::OLE->Option class
-method: C<_NewEnum> provides the elements of a collection object
-directly as the value of a C<_NewEnum> property. The C<_Unique>
-option guarantees that Win32::OLE will not create multiple proxy
-objects for the same underlying COM/OLE object.
-
-Both options are only really useful to tree traversal programs or
-during debugging.
-
-
-=head1 Version 0.12
-
-=head2 Additional error handling functionality
-
-The Warn option can now be set to a CODE reference too. For example,
-
- Win32::OLE->Option(Warn => 3);
-
-could now be written as
-
- Win32::OLE->Option(Warn => \&Carp::croak);
-
-This can even be used to emulate the VisualBasic C<On Error Goto
-Label> construct:
-
- Win32::OLE->Option(Warn => sub {goto CheckError});
- # ... your normal OLE code here ...
-
- CheckError:
- # ... your error handling code here ...
-
-=head2 Builtin event loop
-
-Processing OLE events required a polling loop before, e.g.
-
- my $Quit;
- #...
- until ($Quit) {
- Win32::OLE->SpinMessageLoop;
- Win32::Sleep(100);
- }
- package BrowserEvents;
- sub OnQuit { $Quit = 1 }
-
-This is inefficient and a bit odd. This version of Win32::OLE now
-supports a standard messageloop:
-
- Win32::OLE->MessageLoop();
-
- package BrowserEvents;
- sub OnQuit { Win32::OLE->QuitMessageLoop }
-
-=head2 Free unused OLE libraries
-
-Previous versions of Win32::OLE would call the CoFreeUnusedLibraries()
-API whenever an OLE object was destroyed. This made sure that OLE
-libraries would be unloaded as soon as they were no longer needed.
-Unfortunately, objects implemented in Visual Basic tend to crash
-during this call, as they pretend to be ready for unloading, when in
-fact, they aren't.
-
-The unloading of object libraries is really only important for long
-running processes that might instantiate a huge number of B<different>
-objects over time. Therefore this API is no longer called
-automatically. The functionality is now available explicitly to those
-who want or need it by calling a Win32::OLE class method:
-
- Win32::OLE->FreeUnusedLibraries();
-
-=head2 The "Win32::OLE" article from "The Perl Journal #10"
-
-The article is Copyright 1998 by I<The Perl
-Journal>. http://www.tpj.com
-
-It originally appeared in I<The Perl Journal> # 10 and appears here
-courtesy of Jon Orwant and I<The Perl Journal>. The sample code from
-the article is in the F<eg/tpj.pl> file.
-
-=head2 VARIANT->Put() bug fixes
-
-The Put() method didn't work correctly for arrays of type VT_BSTR,
-VT_DISPATH or VT_UNKNOWN. This has been fixed.
-
-=head2 Error message fixes
-
-Previous versions of Win32::OLE gave a wrong argument index for some
-OLE error messages (the number was too large by 1). This should be
-fixed now.
-
-=head2 VT_DATE and VT_ERROR return values handled differently
-
-Method calls and property accesses returning a VT_DATE or VT_ERROR
-value would previously translate the value to string or integer
-format. This has been changed to return a Win32::OLE::Variant object.
-The return values will behave as before if the Win32::OLE::Variant
-module is being used. This module overloads the conversion of
-the objects to strings and numbers.
-
-
-=head1 Version 0.11 (changes since 0.1008)
-
-=head2 new DHTML typelib browser
-
-The Win32::OLE distribution now contains a type library browser. It
-is written in PerlScript, generating dynamic HTML. It requires
-Internet Explorer 4.0 or later. You'll find it in
-F<browser/Browser.html>. It should be available in the ActivePerl
-HTML help under Win32::OLE::Browser.
-
-After selecting a library, type or member you can press F1 to call up
-the corresponding help file at the appropriate location.
-
-=head2 VT_DECIMAL support
-
-The Win32::OLE::Variant module now supports VT_DECIMAL variants too.
-They are not "officially" allowed in OLE Automation calls, but even
-Microsoft's "ActiveX Data Objects" sometimes returns VT_DECIMAL
-values.
-
-VT_DECIMAL variables are stored as 96-bit integers scaled by a
-variable power of 10. The power of 10 scaling factor specifies the
-number of digits to the right of the decimal point, and ranges from 0
-to 28. With a scale of 0 (no decimal places), the largest possible
-value is +/-79,228,162,514,264,337,593,543,950,335. With a 28 decimal
-places, the largest value is +/-7.9228162514264337593543950335 and the
-smallest, non-zero value is +/-0.0000000000000000000000000001.
-
-=head1 Version 0.1008
-
-=head2 new LetProperty() object method
-
-In Win32::OLE property assignment using the hash syntax is equivalent
-to the Visual Basic C<Set> syntax (I<by reference> assignment):
-
- $Object->{Property} = $OtherObject;
-
-corresponds to this Visual Basic statement:
-
- Set Object.Property = OtherObject
-
-To get the I<by value> treatment of the Visual Basic C<Let> statement
-
- Object.Property = OtherObject
-
-you have to use the LetProperty() object method in Perl:
-
- $Object->LetProperty($Property, $OtherObject);
-
-=head2 new HRESULT() function
-
-The HRESULT() function converts an unsigned number into a signed HRESULT
-error value as used by OLE internally. This is necessary because Perl
-treats all hexadecimal constants as unsigned. To check if the last OLE
-function returned "Member not found" (0x80020003) you can write:
-
- if (Win32::OLE->LastError == HRESULT(0x80020003)) {
- # your error recovery here
- }
-
-=head1 Version 0.1007 (changes since 0.1005)
-
-=head2 OLE Event support
-
-This version of Win32::OLE contains B<ALPHA> level support for OLE events. The
-userinterface is still subject to change. There are ActiveX objects / controls
-that don't fire events under the current implementation.
-
-Events are enabled for a specific object with the Win32::OLE->WithEvents()
-class method:
-
- Win32::OLE->WithEvents(OBJECT, HANDLER, INTERFACE)
-
-Please read further documentation in Win32::OLE.
-
-=head2 GetObject() and GetActiveObject() now support optional DESTRUCTOR argument
-
-It is now possible to specify a DESTRUCTOR argument to the GetObject() and
-GetActiveObject() class methods. They work identical to the new() DESTRUCTOR
-argument.
-
-=head2 Remote object instantiation via DCOM
-
-This has actually been in Win32::OLE since 0.0608, but somehow never got
-documented. You can provide an array reference in place of the usual PROGID
-parameter to Win32::OLE->new():
-
- OBJ = Win32::OLE->new([MACHINE, PRODID]);
-
-The array must contain two elements: the name of the MACHINE and the PROGID.
-This will try to create the object on the remote MACHINE.
-
-=head2 Enumerate all Win32::OLE objects
-
-This class method returns the number Win32::OLE objects currently in
-existance. It will call the optional CALLBACK function for each of
-these objects:
-
- $Count = Win32::OLE->EnumAllObjects(sub {
- my $Object = shift;
- my $Class = Win32::OLE->QueryObjectType($Object);
- printf "# Object=%s Class=%s\n", $Object, $Class;
- });
-
-The EnumAllObjects() method is primarily a debugging tool. It can be
-used e.g. in an END block to check if all external connections have
-been properly destroyed.
-
-=head2 The VARIANT->Put() method now returns the VARIANT object itself
-
-This allows chaining of Put() method calls to set multiple values in an
-array variant:
-
- $Array->Put(0,0,$First_value)->Put(0,1,$Another_value);
-
-=head2 The VARIANT->Put(ARRAYREF) form allows assignment to a complete SAFEARRAY
-
-This allows automatic conversion from a list of lists to a SAFEARRAY.
-You can now write:
-
- my $Array = Variant(VT_ARRAY|VT_R8, [1,2], 2);
- $Array->Put([[1,2], [3,4]]);
-
-instead of the tedious:
-
- $Array->Put(1,0,1);
- $Array->Put(1,1,2);
- $Array->Put(2,0,3);
- $Array->Put(2,1,4);
-
-=head2 New Variant formatting methods
-
-There are four new methods for formatting variant values: Currency(), Date(),
-Number() and Time(). For example:
-
- my $v = Variant(VT_DATE, "April 1 99");
- print $v->Date(DATE_LONGDATE), "\n";
- print $v->Date("ddd',' MMM dd yy"), "\n";
-
-will print:
-
- Thursday, April 01, 1999
- Thu, Apr 01 99
-
-=head2 new Win32::OLE::NLS methods: SendSettingChange() and SetLocaleInfo()
-
-SendSettingChange() sends a WM_SETTINGCHANGE message to all top level windows.
-
-SetLocaleInfo() allows changing elements in the user override section of the
-locale database. Unfortunately these changes are not automatically available
-to further Variant formatting; you have to call SendSettingChange() first.
-
-=head2 Win32::OLE::Const now correctly treats version numbers as hex
-
-The minor and major version numbers of type libraries have been treated as
-decimal. This was wrong. They are now correctly decoded as hex.
-
-=head2 more robust global destruction of Win32::OLE objects
-
-The final destruction of Win32::OLE objects has always been somewhat fragile.
-The reason for this is that Perl doesn't honour reference counts during global
-destruction but destroys objects in seemingly random order. This can lead
-to leaked database connections or unterminated external objects. The only
-solution was to make all objects lexical and hope that no object would be
-trapped in a closure. Alternatively all objects could be explicitly set to
-C<undef>, which doesn't work very well with exception handling.
-
-With version 0.1007 of Win32::OLE this problem should be gone: The module
-keeps a list of active Win32::OLE objects. It uses an END block to destroy
-all objects at program termination I<before> the Perl's global destruction
-starts. Objects still existing at program termination are now destroyed in
-reverse order of creation. The effect is similar to explicitly calling
-Win32::OLE->Uninitialize() just prior to termination.
-
-=head1 Version 0.1005 (changes since 0.1003)
-
-Win32::OLE 0.1005 has been release with ActivePerl build 509. It is also
-included in the I<Perl Resource Kit for Win32> Update.
-
-=head2 optional DESTRUCTOR for GetActiveObject() GetObject() class methods
-
-The GetActiveObject() and GetObject() class method now also support an
-optional DESTRUCTOR parameter just like Win32::OLE->new(). The DESTRUCTOR
-is executed when the last reference to this object goes away. It is
-generally considered C<impolite> to stop applications that you did not
-start yourself.
-
-=head2 new Variant object method: $object->Copy()
-
-See L<Win32::OLE::Variant/Copy([DIM])>.
-
-=head2 new Win32::OLE->Option() class method
-
-The Option() class method can be used to inspect and modify
-L<Win32::OLE/Module Options>. The single argument form retrieves
-the value of an option:
-
- my $CP = Win32::OLE->Option('CP');
-
-A single call can be used to set multiple options simultaneously:
-
- Win32::OLE->Option(CP => CP_ACP, Warn => 3);
-
-Currently the following options exist: CP, LCID and C<Warn>.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/Win32/OLE/TPJ.pod b/Master/tlpkg/tlperl/lib/Win32/OLE/TPJ.pod
deleted file mode 100644
index e45770baa42..00000000000
--- a/Master/tlpkg/tlperl/lib/Win32/OLE/TPJ.pod
+++ /dev/null
@@ -1,798 +0,0 @@
-=pod
-
-=head1 NAME
-
-The Perl Journal #10 - Win32::OLE by Jan Dubois
-
-=head1 INTRODUCTION
-
-Suppose you're composing a document with Microsoft Word. You want to
-include an Excel spreadsheet. You could save the spreadsheet in some
-image format that Word can understand, and import it into your
-document. But if the spreadsheet changes, your document will be out of
-date.
-
-Microsoft's OLE (Object Linking and Embedding, pronounced "olay") lets
-one program use objects from another. In the above scenario, the
-spreadsheet is the object. As long as Excel makes that spreadsheet
-available as an OLE object, and Word knows to treat it like one, your
-document will always be current.
-
-You can control OLE objects from Perl with the Win32::OLE module, and
-that's what this article is about. First, I'll show you how to "think
-OLE," which mostly involves a lot of jargon. Next, I'll show you the
-mechanics involved in using Win32::OLE. Then we'll go through a Perl
-program that uses OLE to manipulate Microsoft Excel, Microsoft Access,
-and Lotus Notes. Finally, I'll talk about Variants, an internal OLE
-data type.
-
-
-=head1 THE OLE MINDSET
-
-When an application makes an OLE object available for other
-applications to use, that's called OLE I<automation>. The program
-using the object is called the I<controller>, and the application
-providing the object is called the I<server>. OLE automation is guided
-by the OLE Component Object Model (COM) which specifies how those
-objects must behave if they are to be used by other processes and
-machines.
-
-There are two different types of OLE automation servers. I<In-process>
-servers are implemented as dynamic link libraries (DLLs) and run in
-the same process space as the controller. I<Out-of-process> servers
-are more interesting; they are standalone executables that exist as
-separate processes - possibly on a different computer.
-
-The Win32::OLE module lets your Perl program act as an OLE
-controller. It allows Perl to be used in place of other languages like
-Visual Basic or Java to control OLE objects. This makes all OLE
-automation servers immediately available as Perl modules.
-
-Don't confuse ActiveState OLE with Win32::OLE. ActiveState OLE is
-completely different, although future builds of ActiveState Perl (500
-and up) will work with Win32::OLE.
-
-Objects can expose OLE methods, properties, and events to the outside
-world. Methods are functions that the controller can call to make the
-object do something; properties describe the state of the object; and
-events let the controller know about external events affecting the
-object, such as the user clicking on a button. Since events involve
-asynchronous communication with their objects, they require either
-threads or an event loop. They are not yet supported by the Win32::OLE
-module, and for the same reason ActiveX controls (OCXs) are currently
-unsupported as well.
-
-=head1 WORKING WITH WIN32::OLE
-
-The Win32::OLE module doesn't let your Perl program create OLE
-objects. What it does do is let your Perl program act like a remote
-control for other applications-it lets your program be an OLE
-controller. You can take an OLE object from another application
-(Access, Notes, Excel, or anything else that speaks OLE) and invoke
-its methods or manipulate its properties.
-
-=head2 THE FIRST STEP: CREATING AN OLE SERVER OBJECT
-
-First, we need to create a Perl object to represent the OLE
-server. This is a weird idea; what it amounts to is that if we want to
-control OLE objects produced by, say, Excel, we have to create a Perl
-object that represents Excel. So even though our program is an OLE
-controller, it'll contain objects that represent OLE servers.
-
-You can create a new OLE I<server object> with C<< Win32::OLE->new >>.
-This takes a program ID (a human readable string like
-C<'Speech.VoiceText'>) and returns a server object:
-
- my $server = Win32::OLE->new('Excel.Application', 'Quit');
-
-Some server objects (particularly those for Microsoft Office
-applications) don't automatically terminate when your program no
-longer needs them. They need some kind of Quit method, and that's just
-what our second argument is. It can be either a code reference or a
-method name to be invoked when the object is destroyed. This lets you
-ensure that objects will be properly cleaned up even when the Perl
-program dies abnormally.
-
-To access a server object on a different computer, replace the first
-argument with a reference to a list of the server name and program ID:
-
- my $server = Win32::OLE->new(['foo.bar.com',
- 'Excel.Application']);
-
-(To get the requisite permissions, you'll need to configure your
-security settings with F<DCOMCNFG.EXE>.)
-
-You can also directly attach your program to an already running OLE
-server:
-
- my $server = Win32::OLE->GetActiveObject('Excel.Application');
-
-This fails (returning C<undef>) if no server exists, or if the server
-refuses the connection for some reason. It is also possible to use a
-persistent object moniker (usually a filename) to start the associated
-server and load the object into memory:
-
- my $doc = Win32::OLE->GetObject("MyDocument.Doc");
-
-=head2 METHOD CALLS
-
-Once you've created one of these server objects, you need to call its
-methods to make the OLE objects sing and dance. OLE methods are
-invoked just like normal Perl object methods:
-
- $server->Foo(@Arguments);
-
-This is a Perl method call - but it also triggers an OLE method call
-in the object. After your program executes this statement, the
-C<$server> object will execute its Foo() method. The available methods
-are typically documented in the application's I<object model>.
-
-B<Parameters.> By default, all parameters are positional
-(e.g. C<foo($first, $second, $third)>) rather than named (e.g.
-C<< foo(-name => "Yogi", -title => "Coach") >>). The required parameters
-come first, followed by the optional parameters; if you need to
-provide a dummy value for an optional parameter, use undef.
-
-Positional parameters get cumbersome if a method takes a lot of
-them. You can use named arguments instead if you go to a little extra
-trouble - when the last argument is a reference to a hash, the
-key/value pairs of the hash are treated as named parameters:
-
- $server->Foo($Pos1, $Pos2, {Name1 => $Value1,
- Name2 => $Value2});
-
-B<Foreign Languages and Default Methods.> Sometimes OLE servers use
-method and property names that are specific to a non-English
-locale. That means they might have non-ASCII characters, which aren't
-allowed in Perl variable names. In German, you might see C<Öffnen> used
-instead of C<Open>. In these cases, you can use the Invoke() method:
-
- $server->Invoke('Öffnen', @Arguments);
-
-This is necessary because C<< $Server->Öffnen(@Arguments) >> is a syntax
-error in current versions of Perl.
-
-=head2 PROPERTIES
-
-As I said earlier, objects can expose three things to the outside
-world: methods, properties, and events. We've covered methods, and
-Win32::OLE can't handle events. That leaves properties. But as it
-turns out, properties and events are largely interchangeable. Most
-methods have corresponding properties, and vice versa.
-
-An object's properties can be accessed with a hash reference:
-
- $server->{Bar} = $value;
- $value = $server->{Bar};
-
-This example sets and queries the value of the property named
-C<Bar>. You could also have called the object's Bar() method to
-achieve the same effect:
-
- $value = $server->Bar;
-
-However, you can't write the first line as C<< $server->Bar = $value >>,
-because you can't assign to the return value of a method call. In
-Visual Basic, OLE automation distinguishes between assigning the name
-of an object and assigning its value:
-
- Set Object = OtherObject
-
- Let Value = Object
-
-The C<Set> statement shown here makes C<Object> refer to the same object as
-C<OtherObject>. The C<Let> statement copies the value instead. (The value of
-an OLE object is what you get when you call the object's default
-method.
-
-In Perl, saying C<< $server1 = $server2 >> always creates another reference,
-just like the C<Set> in Visual Basic. If you want to assign the value
-instead, use the valof() function:
-
- my $value = valof $server;
-
-This is equivalent to
-
- my $value = $server->Invoke('');
-
-=head2 SAMPLE APPLICATION
-
-Let's look at how all of this might be used. In Listing: 1 you'll see
-F<T-Bond.pl>, a program that uses Win32::OLE for an almost-real world
-application.
-
-The developer of this application, Mary Lynch, is a financial futures
-broker. Every afternoon, she connects to the Chicago Board of Trade
-(CBoT) web site at http://www.cbot.com and collects the time and sales
-information for U.S. T-bond futures. She wants her program to create a
-chart that depicts the data in 15-minute intervals, and then she wants
-to record the data in a database for later analysis. Then she wants
-her program to send mail to her clients.
-
-Mary's program will use Microsoft Access as a database, Microsoft
-Excel to produce the chart, and Lotus Notes to send the mail. It will
-all be controlled from a single Perl program using OLE automation. In
-this section, we'll go through T-Bond. pl step by step so you can see
-how Win32::OLE lets you control these applications.
-
-=head2 DOWNLOADING A WEB PAGE WITH LWP
-
-However, Mary first needs to amass the raw T-bond data by having her
-Perl program automatically download and parse a web page. That's the
-perfect job for LWP, the libwww-perl bundle available on the CPAN. LWP
-has nothing to do with OLE. But this is a real-world application, and
-it's just what Mary needs to download her data from the Chicago Board
-of Trade.
-
- use LWP::Simple;
- my $URL = 'http://www.cbot.com/mplex/quotes/tsfut';
- my $text = get("$URL/tsf$Contract.htm");
-
-She could also have used the Win32::Internet module:
-
- use Win32::Internet;
- my $URL = 'http://www.cbot.com/mplex/quotes/tsfut';
- my $text = $Win32::Internet->new->FetchURL("$URL/tsf$Contract.htm");
-
-Mary wants to condense the ticker data into 15 minute bars. She's
-interested only in lines that look like this:
-
- 03/12/1998 US 98Mar 12116 15:28:34 Open
-
-A regular expression can be used to determine whether a line looks
-like this. If it does, the regex can split it up into individual
-fields. The price quoted above, C<12116>, really means 121 16/32, and
-needs to be converted to 121.5. The data is then condensed into 15
-minute intervals and only the first, last, highest, and lowest price
-during each interval are kept. The time series is stored in the array
-C<@Bars>. Each entry in C<@Bars> is a reference to a list of 5 elements:
-Time, Open, High, Low, and Close.
-
- foreach (split "\n", $text) {
- # 03/12/1998 US 98Mar 12116 15:28:34 Open
- my ($Date,$Price,$Hour,$Min,$Sec,$Ind) =
- m|^\s*(\d+/\d+/\d+) # " 03/12/1998"
- \s+US\s+\S+\s+(\d+) # " US 98Mar 12116"
- \s+(\d+):(\d+):(\d+) # " 12:42:40"
- \s*(.*)$|x; # " Ask"
- next unless defined $Date;
- $Day = $Date;
-
- # Convert from fractional to decimal format
- $Price = int($Price/100) + ($Price%100)/32;
-
- # Round up time to next multiple of 15 minutes
- my $NewTime = int(($Sec+$Min*60+$Hour*3600)/900+1)*900;
- unless (defined $Time && $NewTime == $Time) {
- push @Bars, [$hhmm, $Open, $High, $Low, $Close]
- if defined $Time;
- $Open = $High = $Low = $Close = undef;
- $Time = $NewTime;
- my $Hour = int($Time/3600);
- $hhmm = sprintf "%02d:%02d", $Hour, $Time/60-$Hour*60;
- }
-
- # Update 15 minute bar values
- $Close = $Price;
- $Open = $Price unless defined $Open;
- $High = $Price unless defined $High && $High > $Price;
- $Low = $Price unless defined $Low && $Low > $Price;
- }
-
- die "No data found" unless defined $Time;
- push @Bars, [$hhmm, $Open, $High, $Low, $Close];
-
-=head2 MICROSOFT ACCESS
-
-Now that Mary has her T-bond quotes, she's ready to use Win32::OLE to
-store them into a Microsoft Access database. This has the advantage
-that she can copy the database to her lap-top and work with it on her
-long New York commute. She's able to create an Access database as
-follows:
-
- use Win32::ODBC;
- use Win32::OLE;
-
- # Include the constants for the Microsoft Access
- # "Data Access Object".
-
- use Win32::OLE::Const 'Microsoft DAO';
-
- my $DSN = 'T-Bonds';
- my $Driver = 'Microsoft Access Driver (*.mdb)';
- my $Desc = 'US T-Bond Quotes';
- my $Dir = 'i:\tmp\tpj';
- my $File = 'T-Bonds.mdb';
- my $Fullname = "$Dir\\$File";
-
- # Remove old database and dataset name
- unlink $Fullname if -f $Fullname;
- Win32::ODBC::ConfigDSN(ODBC_REMOVE_DSN, $Driver, "DSN=$DSN")
- if Win32::ODBC::DataSources($DSN);
-
- # Create new database
- my $Access = Win32::OLE->new('Access.Application', 'Quit');
- my $Workspace = $Access->DBEngine->CreateWorkspace('', 'Admin', '');
- my $Database = $Workspace->CreateDatabase($Fullname, dbLangGeneral);
-
- # Add new database name
- Win32::ODBC::ConfigDSN(ODBC_ADD_DSN, $Driver,
- "DSN=$DSN", "Description=$Desc", "DBQ=$Fullname",
- "DEFAULTDIR=$Dir", "UID=", "PWD=");
-
-This uses Win32::ODBC (described in TPJ #9) to remove and create
-F<T-Bonds.mdb>. This lets Mary use the same script on her workstation
-and on her laptop even when the database is stored in different
-locations on each. The program also uses Win32::OLE to make Microsoft
-Access create an empty database.
-
-Every OLE server has some constants that your Perl program will need
-to use, made accessible by the Win32::OLE::Const module. For instance,
-to grab the Excel constants, say C<use Win32::OLE::Const 'Microsoft
-Excel'>.
-
-In the above example, we imported the Data Access Object con-stants
-just so we could use C<dbLangGeneral>.
-
-=head2 MICROSOFT EXCEL
-
-Now Mary uses Win32::OLE a second time, to have Microsoft Excel create
-the chart shown below.
-
- Figure 1: T-Bond data generated by MicroSoft Excel via Win32::OLE
-
- # Start Excel and create new workbook with a single sheet
- use Win32::OLE qw(in valof with);
- use Win32::OLE::Const 'Microsoft Excel';
- use Win32::OLE::NLS qw(:DEFAULT :LANG :SUBLANG);
-
- my $lgid = MAKELANGID(LANG_ENGLISH, SUBLANG_DEFAULT);
- $Win32::OLE::LCID = MAKELCID($lgid);
-
- $Win32::OLE::Warn = 3;
-
-Here, Mary sets the locale to American English, which lets her do
-things like use American date formats (e.g. C<"12-30-98"> rather than
-C<"30-12-98">) in her program. It will continue to work even when she's
-visiting one of her international customers and has to run this
-program on their computers.
-
-The value of C<$Win32::OLE::Warn> determines what happens when an OLE
-error occurs. If it's 0, the error is ignored. If it's 2, or if it's 1
-and the script is running under C<-w>, the Win32::OLE module invokes
-C<Carp::carp()>. If C<$Win32::OLE::Warn> is set to 3, C<Carp::croak()>
-is invoked and the program dies immediately.
-
-Now the data can be put into an Excel spreadsheet to produce the
-chart. The following section of the program launches Excel and creates
-a new workbook with a single worksheet. It puts the column titles
-('Time', 'Open', 'High', 'Low', and 'Close') in a bold font on the
-first row of the sheet. The first column displays the timestamp in
-I<hh:mm> format; the next four display prices.
-
- my $Excel = Win32::OLE->new('Excel.Application', 'Quit');
- $Excel->{SheetsInNewWorkbook} = 1;
- my $Book = $Excel->Workbooks->Add;
- my $Sheet = $Book->Worksheets(1);
- $Sheet->{Name} = 'Candle';
-
- # Insert column titles
- my $Range = $Sheet->Range("A1:E1");
- $Range->{Value} = [qw(Time Open High Low Close)];
- $Range->Font->{Bold} = 1;
-
- $Sheet->Columns("A:A")->{NumberFormat} = "h:mm";
- # Open/High/Low/Close to be displayed in 32nds
- $Sheet->Columns("B:E")->{NumberFormat} = "# ?/32";
-
- # Add 15 minute data to spreadsheet
- print "Add data\n";
- $Range = $Sheet->Range(sprintf "A2:E%d", 2+$#Bars);
- $Range->{Value} = \@Bars;
-
-The last statement shows how to pass arrays to OLE objects. The
-Win32::OLE module automatically translates each array reference to a
-C<SAFEARRAY>, the internal OLE array data type. This translation first
-determines the maximum nesting level used by the Perl array, and then
-creates a C<SAFEARRAY> of the same dimension. The C<@Bars> array
-already contains the data in the correct form for the spreadsheet:
-
- ([Time1, Open1, High1, Low1, Close1],
- ...
- [TimeN, OpenN, HighN, LowN, CloseN])
-
-Now the table in the spreadsheet can be used to create a candle stick
-chart from our bars. Excel automatically chooses the time axis labels
-if they are selected before the chart is created:
-
- # Create candle stick chart as new object on worksheet
- $Sheet->Range("A:E")->Select;
-
- my $Chart = $Book->Charts->Add;
- $Chart->{ChartType} = xlStockOHLC;
- $Chart->Location(xlLocationAsObject, $Sheet->{Name});
- # Excel bug: the old $Chart is now invalid!
- $Chart = $Excel->ActiveChart;
-
-We can change the type of the chart from a separate sheet to a chart
-object on the spreadsheet page with the C<< $Chart->Location >>
-method. (This invalidates the chart object handle, which might be
-considered a bug in Excel.) Fortunately, this new chart is still the
-'active' chart, so an object handle to it can be reclaimed simply by
-asking Excel.
-
-At this point, our chart still needs a title, the legend is
-meaningless, and the axis has decimals instead of fractions. We can
-fix those with the following code:
-
- # Add title, remove legend
- with($Chart, HasLegend => 0, HasTitle => 1);
- $Chart->ChartTitle->Characters->{Text} = "US T-Bond";
-
- # Set up daily statistics
- $Open = $Bars[0][1];
- $High = $Sheet->Evaluate("MAX(C:C)");
- $Low = $Sheet->Evaluate("MIN(D:D)");
- $Close = $Bars[$#Bars][4];
-
-The with() function partially mimics the Visual Basic With statement,
-but allows only property assignments. It's a convenient shortcut for
-this:
-
- { # open new scope
- my $Axis = $Chart->Axes(xlValue);
- $Axis->{HasMajorGridlines} = 1;
- $Axis->{HasMinorGridlines} = 1;
- # etc ...
- }
-
-The C<$High> and C<$Low> for the day are needed to determine the
-minimum and maximum scaling levels. MIN and MAX are spreadsheet
-functions, and aren't automatically available as methods. However,
-Excel provides an Evaluate() method to calculate arbitrary spreadsheet
-functions, so we can use that.
-
-We want the chart to show major gridlines at every fourth tick and
-minor gridlines at every second tick. The minimum and maximum are
-chosen to be whatever multiples of 1/16 we need to do that.
-
- # Change tickmark spacing from decimal to fractional
- with($Chart->Axes(xlValue),
- HasMajorGridlines => 1,
- HasMinorGridlines => 1,
- MajorUnit => 1/8,
- MinorUnit => 1/16,
- MinimumScale => int($Low*16)/16,
- MaximumScale => int($High*16+1)/16
- );
-
- # Fat candles with only 5% gaps
- $Chart->ChartGroups(1)->{GapWidth} = 5;
-
- sub RGB { $_[0] | ($_[1] >> 8) | ($_[2] >> 16) }
-
- # White background with a solid border
-
- $Chart->PlotArea->Border->{LineStyle} = xlContinuous;
- $Chart->PlotArea->Border->{Color} = RGB(0,0,0);
- $Chart->PlotArea->Interior->{Color} = RGB(255,255,255);
-
- # Add 1 hour moving average of the Close series
- my $MovAvg = $Chart->SeriesCollection(4)->Trendlines
- ->Add({Type => xlMovingAvg, Period => 4});
- $MovAvg->Border->{Color} = RGB(255,0,0);
-
-Now the finished workbook can be saved to disk as
-F<i:\tmp\tpj\data.xls>. That file most likely still exists from when the
-program ran yesterday, so we'll remove it. (Otherwise, Excel would pop
-up a dialog with a warning, because the SaveAs() method doesn't like
-to overwrite files.)
-
-
- # Save workbook to file my $Filename = 'i:\tmp\tpj\data.xls';
- unlink $Filename if -f $Filename;
- $Book->SaveAs($Filename);
- $Book->Close;
-
-=head2 ACTIVEX DATA OBJECTS
-
-Mary stores the daily prices in her T-bonds database, keeping the data
-for the different contracts in separate tables. After creating an ADO
-(ActiveX Data Object) connection to the database, she tries to connect
-a record set to the table for the current contract. If this fails, she
-assumes that the table doesn't exists yet and tries to create it:
-
- use Win32::OLE::Const 'Microsoft ActiveX Data Objects';
-
- my $Connection = Win32::OLE->new('ADODB.Connection');
- my $Recordset = Win32::OLE->new('ADODB.Recordset');
- $Connection->Open('T-Bonds');
-
- # Open a record set for the table of this contract
- {
- local $Win32::OLE::Warn = 0;
- $Recordset->Open($Contract, $Connection, adOpenKeyset,
- adLockOptimistic, adCmdTable);
- }
-
- # Create table and index if it doesn't exist yet
- if (Win32::OLE->LastError) {
- $Connection->Execute(<<"SQL");
- CREATE TABLE $Contract
- (
- Day DATETIME,
- Open DOUBLE, High DOUBLE, Low DOUBLE, Close DOUBLE
- )
- SQL
- $Connection->Execute(<<"SQL");
- CREATE INDEX $Contract
- ON $Contract (Day) WITH PRIMARY
- SQL
- $Recordset->Open($Contract, $Connection, adOpenKeyset,
- adLockOptimistic, adCmdTable);
- }
-
-C<$Win32::OLE::Warn> is temporarily set to zero, so that if
-C<$Recordset->Open> fails, the failure will be recorded silently without
-terminating the program. C<Win32::OLE->LastError> shows whether the Open
-failed or not. C<LastError> returns the OLE error code in a numeric
-context and the OLE error message in a string context, just like
-Perl's C<$!> variable.
-
-Now Mary can add today's data:
-
- # Add new record to table
- use Win32::OLE::Variant;
- $Win32::OLE::Variant::LCID = $Win32::OLE::LCID;
-
- my $Fields = [qw(Day Open High Low Close)];
- my $Values = [Variant(VT_DATE, $Day),
- $Open, $High, $Low, $Close];
-
-Mary uses the Win32::OLE::Variant module to store C<$Day> as a date
-instead of a mere string. She wants to make sure that it's stored as
-an American-style date, so in the third line shown here she sets the
-locale ID of the Win32::OLE::Variant module to match the Win32::OLE
-module. (C<$Win32::OLE::LCID> had been set earlier to English, since
-that's what the Chicago Board of Trade uses.)
-
- {
- local $Win32::OLE::Warn = 0;
- $Recordset->AddNew($Fields, $Values);
- }
-
- # Replace existing record
- if (Win32::OLE->LastError) {
- $Recordset->CancelUpdate;
- $Recordset->Close;
- $Recordset->Open(<<"SQL", $Connection, adOpenDynamic);
- SELECT * FROM $Contract
- WHERE Day = #$Day#
- SQL
- $Recordset->Update($Fields, $Values);
- }
-
- $Recordset->Close;
- $Connection->Close;
-
-The program expects to be able to add a new record to the table. It
-fails if a record for this date already exists, because the Day field
-is the primary index and therefore must be unique. If an error occurs,
-the update operation started by AddNew() must first be cancelled with
-C<< $Recordset->CancelUpdate >>; otherwise the record set won't close.
-
-=head2 LOTUS NOTES
-
-Now Mary can use Lotus Notes to mail updates to all her customers
-interested in the T-bond data. (Lotus Notes doesn't provide its
-constants in the OLE type library, so Mary had to determine them by
-playing around with LotusScript.) The actual task is quite simple: A
-Notes session must be started, the mail database must be opened and
-the mail message must be created. The body of the message is created
-as a rich text field, which lets her mix formatted text with object
-attachments.
-
-In her program, Mary extracts the email addresses from her customer
-database and sends separate message to each. Here, we've simplified it
-somewhat.
-
- sub EMBED_ATTACHMENT {1454;} # from LotusScript
-
- my $Notes = Win32::OLE->new('Notes.NotesSession');
- my $Database = $Notes->GetDatabase('', '');
- $Database->OpenMail;
- my $Document = $Database->CreateDocument;
-
- $Document->{Form} = 'Memo';
- $Document->{SendTo} = ['Jon Orwant >orwant@tpj.com>',
- 'Jan Dubois >jan.dubois@ibm.net>'];
- $Document->{Subject} = "US T-Bonds Chart for $Day";
-
- my $Body = $Document->CreateRichtextItem('Body');
- $Body->AppendText(<<"EOT");
- I\'ve attached the latest US T-Bond data and chart for $Day.
- The daily statistics were:
-
- \tOpen\t$Open
- \tHigh\t$High
- \tLow\t$Low
- \tClose\t$Close
-
- Kind regards,
-
- Mary
- EOT
-
- $Body->EmbedObject(EMBED_ATTACHMENT, '', $Filename);
-
- $Document->Send(0);
-
-=head1 VARIANTS
-
-In this final section, I'll talk about Variants, which are the data
-types that you use to talk to OLE objects. We talked about this line
-earlier:
-
- my $Values = [Variant(VT_DATE, $Day),
- $Open, $High, $Low, $Close];
-
-Here, the Variant() function creates a Variant object, of type C<VT_DATE>
-and with the value C<$Day>. Variants are similar in many ways to Perl
-scalars. Arguments to OLE methods are transparently converted from
-their internal Perl representation to Variants and back again by the
-Win32::OLE module.
-
-OLE automation uses a generic C<VARIANT> data type to pass
-parameters. This data type contains type information in addition to
-the actual data value. Only the following data types are valid for OLE
-automation:
-
- B<Data Type Meaning>
- VT_EMPTY Not specified
- VT_NULL Null
- VT_I2 2 byte signed integer
- VT_I4 4 byte signed integer
- VT_R4 4 byte real
- VT_R8 8 byte real
- VT_CY Currency
- VT_DATE Date
- VT_BSTR Unicode string
- VT_DISPATCH OLE automation interface
- VT_ERROR Error
- VT_BOOL Boolean
- VT_VARIANT (only valid with VT_BYREF)
- VT_UNKNOWN Generic COM interface
- VT_UI1 Unsigned character
-
-The following two flags can also be used:
-
- VT_ARRAY Array of values
- VT_BYREF Pass by reference (instead of by value)
-
-B<The Perl to Variant transformation.> The following conversions are
-performed automatically whenever a Perl value must be translated into
-a Variant:
-
- Perl value Variant
- Integer values VT_I4
- Real values VT_R8
- Strings VT_BSTR
- undef VT_ERROR (DISP_E_PARAMNOTFOUND)
- Array reference VT_VARIANT | VT_ARRAY
- Win32::OLE object VT_DISPATCH
- Win32::OLE::Variant object Type of the Variant object
-
-What if your Perl value is a list of lists? Those can be irregularly
-shaped in Perl; that is, the subsidiary lists needn't have the same
-number of elements. In this case, the structure will be converted to a
-"rectangular" C<SAFEARRAY> of Variants, with unused slots set to
-C<VT_EMPTY>. Consider this Perl 2-D array:
-
- [ ["Perl" ], # one element
- [1, 3.1215, undef] # three elements
- ]
-
-This will be translated to a 2 by 3 C<SAFEARRAY> that looks like this:
-
- VT_BSTR("Perl") VT_EMPTY VT_EMPTY
- VT_I4(1) VT_R8(3.1415) VT_ERROR(DISP_E_PARAMNOTFOUND)
-
-B<The Variant To Perl Transformation.> Automatic conversion from Variants
-to Perl values happens as follows:
-
- Variant Perl value
- VT_BOOL, VT_ERROR Integer
- VT_UI1, VT_I2, VT_I4 Integer
- VT_R4, VT_R8 Float value
- VT_BSTR String
- VT_DISPATCH Win32::OLE object
-
-B<The Win32::OLE::Variant module.> This module provides access to the
-Variant data type, which gives you more control over how these
-arguments to OLE methods are encoded. (This is rarely necessary if you
-have a good grasp of the default conversion rules.) A Variant object
-can be created with the C<< Win32::OLE::Variant->new >> method or the
-equivalent Variant() function:
-
- use Win32::OLE::Variant;
- my $var1 = Win32::OLE::Variant->new(VT_DATE, 'Jan 1,1970');
- my $var2 = Variant(VT_BSTR, 'This is an Unicode string');
-
-Several methods let you inspect and manipulate Variant objects: The
-Type() and Value() methods return the variant type and value; the As()
-method returns the value after converting it to a different variant
-type; ChangeType() coerces the Variant into a different type; and
-Unicode() returns the value of a Variant object as an object of the
-Unicode::String class.
-
-These conversions are more interesting if they can be applied directly
-to the return value of an OLE method call without first mutilating the
-value with default conversions. This is possible with the following
-trick:
-
- my $RetVal = Variant(VT_EMPTY, undef);
- $Object->Dispatch($Method, $RetVal, @Arguments);
-
-Normally, you wouldn't call Dispatch() directly; it's executed
-implicitly by either AUTOLOAD() or Invoke(). If Dispatch() realizes
-that the return value is already a Win32::OLE::Variant object, the
-return value is not translated into a Perl representation but rather
-copied verbatim into the Variant object.
-
-Whenever a Win32::OLE::Variant object is used in a numeric or string
-context it is automatically converted into the corresponding format.
-
- printf "Number: %f and String: %s\n",
- $Var, $Var;
-
-This is equivalent to:
-
- printf "Number: %f and String: %s\n",
- $Var->As(VT_R8), $Var->As(VT_BSTR);
-
-For methods that modify their arguments, you need to use the C<VT_BYREF>
-flag. This lets you create number and string Variants that can be
-modified by OLE methods. Here, Corel's GetSize() method takes two
-integers and stores the C<x> and C<y> dimensions in them:
-
- my $x = Variant( VT_I4 | VT_BYREF, 0);
- my $y = Variant( VT_I4 | VT_BYREF, 0);
- $Corel->GetSize($x, $y);
-
-C<VT_BYREF> support for other Variant types might appear in future
-releases of Win32::OLE.
-
-=head1 FURTHER INFORMATION
-
-=head2 DOCUMENTATION AND EXAMPLE CODE
-
-More information about the OLE modules can be found in the
-documentation bundled with Win32::OLE. The distribution also contains
-other code samples.
-
-The object model for Microsoft Office applications can be found in the
-Visual Basic Reference for Microsoft Access, Excel, Word, or
-PowerPoint. These help files are not installed by default, but they
-can be added later by rerunning F<setup.exe> and choosing I<custom
-setup>. The object model for Microsoft Outlook can be found on the
-Microsoft Office Developer Forum at:
-http://www.microsoft.com/OutlookDev/.
-
-Information about the LotusScript object model can be found at:
-http://www.lotus.com/products/lotusscript.nsf.
-
-=head2 OLE AUTOMATION ON OTHER PLATFORMS
-
-Microsoft also makes OLE technology available for the Mac. DCOM is
-already included in Windows NT 4.0 and can be downloaded for Windows
-95. MVS and some Unix systems can use EntireX to get OLE
-functionality; see
-http://www.softwareag.com/corporat/solutions/entirex/entirex.htm.
-
-=head1 COPYRIGHT
-
-Copyright 1998 I<The Perl Journal>. http://www.tpj.com
-
-This article originally appeared in I<The Perl Journal> #10. It
-appears courtesy of Jon Orwant and I<The Perl Journal>. This document
-may be distributed under the same terms as Perl itself.
diff --git a/Master/tlpkg/tlperl/lib/lwpcook.pod b/Master/tlpkg/tlperl/lib/lwpcook.pod
deleted file mode 100644
index 2002b79925e..00000000000
--- a/Master/tlpkg/tlperl/lib/lwpcook.pod
+++ /dev/null
@@ -1,311 +0,0 @@
-=head1 NAME
-
-lwpcook - The libwww-perl cookbook
-
-=head1 DESCRIPTION
-
-This document contain some examples that show typical usage of the
-libwww-perl library. You should consult the documentation for the
-individual modules for more detail.
-
-All examples should be runnable programs. You can, in most cases, test
-the code sections by piping the program text directly to perl.
-
-
-
-=head1 GET
-
-It is very easy to use this library to just fetch documents from the
-net. The LWP::Simple module provides the get() function that return
-the document specified by its URL argument:
-
- use LWP::Simple;
- $doc = get 'http://search.cpan.org/dist/libwww-perl/';
-
-or, as a perl one-liner using the getprint() function:
-
- perl -MLWP::Simple -e 'getprint "http://search.cpan.org/dist/libwww-perl/"'
-
-or, how about fetching the latest perl by running this command:
-
- perl -MLWP::Simple -e '
- getstore "ftp://ftp.sunet.se/pub/lang/perl/CPAN/src/latest.tar.gz",
- "perl.tar.gz"'
-
-You will probably first want to find a CPAN site closer to you by
-running something like the following command:
-
- perl -MLWP::Simple -e 'getprint "http://www.cpan.org/SITES.html"'
-
-Enough of this simple stuff! The LWP object oriented interface gives
-you more control over the request sent to the server. Using this
-interface you have full control over headers sent and how you want to
-handle the response returned.
-
- use LWP::UserAgent;
- $ua = LWP::UserAgent->new;
- $ua->agent("$0/0.1 " . $ua->agent);
- # $ua->agent("Mozilla/8.0") # pretend we are very capable browser
-
- $req = HTTP::Request->new(
- GET => 'http://search.cpan.org/dist/libwww-perl/');
- $req->header('Accept' => 'text/html');
-
- # send request
- $res = $ua->request($req);
-
- # check the outcome
- if ($res->is_success) {
- print $res->decoded_content;
- }
- else {
- print "Error: " . $res->status_line . "\n";
- }
-
-The lwp-request program (alias GET) that is distributed with the
-library can also be used to fetch documents from WWW servers.
-
-
-
-=head1 HEAD
-
-If you just want to check if a document is present (i.e. the URL is
-valid) try to run code that looks like this:
-
- use LWP::Simple;
-
- if (head($url)) {
- # ok document exists
- }
-
-The head() function really returns a list of meta-information about
-the document. The first three values of the list returned are the
-document type, the size of the document, and the age of the document.
-
-More control over the request or access to all header values returned
-require that you use the object oriented interface described for GET
-above. Just s/GET/HEAD/g.
-
-
-=head1 POST
-
-There is no simple procedural interface for posting data to a WWW server. You
-must use the object oriented interface for this. The most common POST
-operation is to access a WWW form application:
-
- use LWP::UserAgent;
- $ua = LWP::UserAgent->new;
-
- my $req = HTTP::Request->new(
- POST => 'http://rt.cpan.org/Public/Dist/Display.html');
- $req->content_type('application/x-www-form-urlencoded');
- $req->content('Status=Active&Name=libwww-perl');
-
- my $res = $ua->request($req);
- print $res->as_string;
-
-Lazy people use the HTTP::Request::Common module to set up a suitable
-POST request message (it handles all the escaping issues) and has a
-suitable default for the content_type:
-
- use HTTP::Request::Common qw(POST);
- use LWP::UserAgent;
- $ua = LWP::UserAgent->new;
-
- my $req = POST 'http://rt.cpan.org/Public/Dist/Display.html',
- [ Status => 'Active', Name => 'libwww-perl' ];
-
- print $ua->request($req)->as_string;
-
-The lwp-request program (alias POST) that is distributed with the
-library can also be used for posting data.
-
-
-
-=head1 PROXIES
-
-Some sites use proxies to go through fire wall machines, or just as
-cache in order to improve performance. Proxies can also be used for
-accessing resources through protocols not supported directly (or
-supported badly :-) by the libwww-perl library.
-
-You should initialize your proxy setting before you start sending
-requests:
-
- use LWP::UserAgent;
- $ua = LWP::UserAgent->new;
- $ua->env_proxy; # initialize from environment variables
- # or
- $ua->proxy(ftp => 'http://proxy.myorg.com');
- $ua->proxy(wais => 'http://proxy.myorg.com');
- $ua->no_proxy(qw(no se fi));
-
- my $req = HTTP::Request->new(GET => 'wais://xxx.com/');
- print $ua->request($req)->as_string;
-
-The LWP::Simple interface will call env_proxy() for you automatically.
-Applications that use the $ua->env_proxy() method will normally not
-use the $ua->proxy() and $ua->no_proxy() methods.
-
-Some proxies also require that you send it a username/password in
-order to let requests through. You should be able to add the
-required header, with something like this:
-
- use LWP::UserAgent;
-
- $ua = LWP::UserAgent->new;
- $ua->proxy(['http', 'ftp'] => 'http://username:password@proxy.myorg.com');
-
- $req = HTTP::Request->new('GET',"http://www.perl.com");
-
- $res = $ua->request($req);
- print $res->decoded_content if $res->is_success;
-
-Replace C<proxy.myorg.com>, C<username> and
-C<password> with something suitable for your site.
-
-
-=head1 ACCESS TO PROTECTED DOCUMENTS
-
-Documents protected by basic authorization can easily be accessed
-like this:
-
- use LWP::UserAgent;
- $ua = LWP::UserAgent->new;
- $req = HTTP::Request->new(GET => 'http://www.linpro.no/secret/');
- $req->authorization_basic('aas', 'mypassword');
- print $ua->request($req)->as_string;
-
-The other alternative is to provide a subclass of I<LWP::UserAgent> that
-overrides the get_basic_credentials() method. Study the I<lwp-request>
-program for an example of this.
-
-
-=head1 COOKIES
-
-Some sites like to play games with cookies. By default LWP ignores
-cookies provided by the servers it visits. LWP will collect cookies
-and respond to cookie requests if you set up a cookie jar.
-
- use LWP::UserAgent;
- use HTTP::Cookies;
-
- $ua = LWP::UserAgent->new;
- $ua->cookie_jar(HTTP::Cookies->new(file => "lwpcookies.txt",
- autosave => 1));
-
- # and then send requests just as you used to do
- $res = $ua->request(HTTP::Request->new(GET => "http://no.yahoo.com/"));
- print $res->status_line, "\n";
-
-As you visit sites that send you cookies to keep, then the file
-F<lwpcookies.txt"> will grow.
-
-=head1 HTTPS
-
-URLs with https scheme are accessed in exactly the same way as with
-http scheme, provided that an SSL interface module for LWP has been
-properly installed (see the F<README.SSL> file found in the
-libwww-perl distribution for more details). If no SSL interface is
-installed for LWP to use, then you will get "501 Protocol scheme
-'https' is not supported" errors when accessing such URLs.
-
-Here's an example of fetching and printing a WWW page using SSL:
-
- use LWP::UserAgent;
-
- my $ua = LWP::UserAgent->new;
- my $req = HTTP::Request->new(GET => 'https://www.helsinki.fi/');
- my $res = $ua->request($req);
- if ($res->is_success) {
- print $res->as_string;
- }
- else {
- print "Failed: ", $res->status_line, "\n";
- }
-
-=head1 MIRRORING
-
-If you want to mirror documents from a WWW server, then try to run
-code similar to this at regular intervals:
-
- use LWP::Simple;
-
- %mirrors = (
- 'http://www.sn.no/' => 'sn.html',
- 'http://www.perl.com/' => 'perl.html',
- 'http://search.cpan.org/distlibwww-perl/' => 'lwp.html',
- 'gopher://gopher.sn.no/' => 'gopher.html',
- );
-
- while (($url, $localfile) = each(%mirrors)) {
- mirror($url, $localfile);
- }
-
-Or, as a perl one-liner:
-
- perl -MLWP::Simple -e 'mirror("http://www.perl.com/", "perl.html")';
-
-The document will not be transferred unless it has been updated.
-
-
-
-=head1 LARGE DOCUMENTS
-
-If the document you want to fetch is too large to be kept in memory,
-then you have two alternatives. You can instruct the library to write
-the document content to a file (second $ua->request() argument is a file
-name):
-
- use LWP::UserAgent;
- $ua = LWP::UserAgent->new;
-
- my $req = HTTP::Request->new(GET =>
- 'http://www.cpan.org/authors/Gisle_Aas/libwww-perl-6.02.tar.gz');
- $res = $ua->request($req, "libwww-perl.tar.gz");
- if ($res->is_success) {
- print "ok\n";
- }
- else {
- print $res->status_line, "\n";
- }
-
-
-Or you can process the document as it arrives (second $ua->request()
-argument is a code reference):
-
- use LWP::UserAgent;
- $ua = LWP::UserAgent->new;
- $URL = 'ftp://ftp.unit.no/pub/rfc/rfc-index.txt';
-
- my $expected_length;
- my $bytes_received = 0;
- my $res =
- $ua->request(HTTP::Request->new(GET => $URL),
- sub {
- my($chunk, $res) = @_;
- $bytes_received += length($chunk);
- unless (defined $expected_length) {
- $expected_length = $res->content_length || 0;
- }
- if ($expected_length) {
- printf STDERR "%d%% - ",
- 100 * $bytes_received / $expected_length;
- }
- print STDERR "$bytes_received bytes received\n";
-
- # XXX Should really do something with the chunk itself
- # print $chunk;
- });
- print $res->status_line, "\n";
-
-
-
-=head1 COPYRIGHT
-
-Copyright 1996-2001, Gisle Aas
-
-This library is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-
diff --git a/Master/tlpkg/tlperl/lib/lwptut.pod b/Master/tlpkg/tlperl/lib/lwptut.pod
deleted file mode 100644
index 2969a330edf..00000000000
--- a/Master/tlpkg/tlperl/lib/lwptut.pod
+++ /dev/null
@@ -1,839 +0,0 @@
-=head1 NAME
-
-lwptut -- An LWP Tutorial
-
-=head1 DESCRIPTION
-
-LWP (short for "Library for WWW in Perl") is a very popular group of
-Perl modules for accessing data on the Web. Like most Perl
-module-distributions, each of LWP's component modules comes with
-documentation that is a complete reference to its interface. However,
-there are so many modules in LWP that it's hard to know where to start
-looking for information on how to do even the simplest most common
-things.
-
-Really introducing you to using LWP would require a whole book -- a book
-that just happens to exist, called I<Perl & LWP>. But this article
-should give you a taste of how you can go about some common tasks with
-LWP.
-
-
-=head2 Getting documents with LWP::Simple
-
-If you just want to get what's at a particular URL, the simplest way
-to do it is LWP::Simple's functions.
-
-In a Perl program, you can call its C<get($url)> function. It will try
-getting that URL's content. If it works, then it'll return the
-content; but if there's some error, it'll return undef.
-
- my $url = 'http://www.npr.org/programs/fa/?todayDate=current';
- # Just an example: the URL for the most recent /Fresh Air/ show
-
- use LWP::Simple;
- my $content = get $url;
- die "Couldn't get $url" unless defined $content;
-
- # Then go do things with $content, like this:
-
- if($content =~ m/jazz/i) {
- print "They're talking about jazz today on Fresh Air!\n";
- }
- else {
- print "Fresh Air is apparently jazzless today.\n";
- }
-
-The handiest variant on C<get> is C<getprint>, which is useful in Perl
-one-liners. If it can get the page whose URL you provide, it sends it
-to STDOUT; otherwise it complains to STDERR.
-
- % perl -MLWP::Simple -e "getprint 'http://www.cpan.org/RECENT'"
-
-That is the URL of a plain text file that lists new files in CPAN in
-the past two weeks. You can easily make it part of a tidy little
-shell command, like this one that mails you the list of new
-C<Acme::> modules:
-
- % perl -MLWP::Simple -e "getprint 'http://www.cpan.org/RECENT'" \
- | grep "/by-module/Acme" | mail -s "New Acme modules! Joy!" $USER
-
-There are other useful functions in LWP::Simple, including one function
-for running a HEAD request on a URL (useful for checking links, or
-getting the last-revised time of a URL), and two functions for
-saving/mirroring a URL to a local file. See L<the LWP::Simple
-documentation|LWP::Simple> for the full details, or chapter 2 of I<Perl
-& LWP> for more examples.
-
-
-
-=for comment
- ##########################################################################
-
-
-
-=head2 The Basics of the LWP Class Model
-
-LWP::Simple's functions are handy for simple cases, but its functions
-don't support cookies or authorization, don't support setting header
-lines in the HTTP request, generally don't support reading header lines
-in the HTTP response (notably the full HTTP error message, in case of an
-error). To get at all those features, you'll have to use the full LWP
-class model.
-
-While LWP consists of dozens of classes, the main two that you have to
-understand are L<LWP::UserAgent> and L<HTTP::Response>. LWP::UserAgent
-is a class for "virtual browsers" which you use for performing requests,
-and L<HTTP::Response> is a class for the responses (or error messages)
-that you get back from those requests.
-
-The basic idiom is C<< $response = $browser->get($url) >>, or more fully
-illustrated:
-
- # Early in your program:
-
- use LWP 5.64; # Loads all important LWP classes, and makes
- # sure your version is reasonably recent.
-
- my $browser = LWP::UserAgent->new;
-
- ...
-
- # Then later, whenever you need to make a get request:
- my $url = 'http://www.npr.org/programs/fa/?todayDate=current';
-
- my $response = $browser->get( $url );
- die "Can't get $url -- ", $response->status_line
- unless $response->is_success;
-
- die "Hey, I was expecting HTML, not ", $response->content_type
- unless $response->content_type eq 'text/html';
- # or whatever content-type you're equipped to deal with
-
- # Otherwise, process the content somehow:
-
- if($response->decoded_content =~ m/jazz/i) {
- print "They're talking about jazz today on Fresh Air!\n";
- }
- else {
- print "Fresh Air is apparently jazzless today.\n";
- }
-
-There are two objects involved: C<$browser>, which holds an object of
-class LWP::UserAgent, and then the C<$response> object, which is of
-class HTTP::Response. You really need only one browser object per
-program; but every time you make a request, you get back a new
-HTTP::Response object, which will have some interesting attributes:
-
-=over
-
-=item *
-
-A status code indicating
-success or failure
-(which you can test with C<< $response->is_success >>).
-
-=item *
-
-An HTTP status
-line that is hopefully informative if there's failure (which you can
-see with C<< $response->status_line >>,
-returning something like "404 Not Found").
-
-=item *
-
-A MIME content-type like "text/html", "image/gif",
-"application/xml", etc., which you can see with
-C<< $response->content_type >>
-
-=item *
-
-The actual content of the response, in C<< $response->decoded_content >>.
-If the response is HTML, that's where the HTML source will be; if
-it's a GIF, then C<< $response->decoded_content >> will be the binary
-GIF data.
-
-=item *
-
-And dozens of other convenient and more specific methods that are
-documented in the docs for L<HTTP::Response>, and its superclasses
-L<HTTP::Message> and L<HTTP::Headers>.
-
-=back
-
-
-
-=for comment
- ##########################################################################
-
-
-
-=head2 Adding Other HTTP Request Headers
-
-The most commonly used syntax for requests is C<< $response =
-$browser->get($url) >>, but in truth, you can add extra HTTP header
-lines to the request by adding a list of key-value pairs after the URL,
-like so:
-
- $response = $browser->get( $url, $key1, $value1, $key2, $value2, ... );
-
-For example, here's how to send some more Netscape-like headers, in case
-you're dealing with a site that would otherwise reject your request:
-
-
- my @ns_headers = (
- 'User-Agent' => 'Mozilla/4.76 [en] (Win98; U)',
- 'Accept' => 'image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, */*',
- 'Accept-Charset' => 'iso-8859-1,*,utf-8',
- 'Accept-Language' => 'en-US',
- );
-
- ...
-
- $response = $browser->get($url, @ns_headers);
-
-If you weren't reusing that array, you could just go ahead and do this:
-
- $response = $browser->get($url,
- 'User-Agent' => 'Mozilla/4.76 [en] (Win98; U)',
- 'Accept' => 'image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, */*',
- 'Accept-Charset' => 'iso-8859-1,*,utf-8',
- 'Accept-Language' => 'en-US',
- );
-
-If you were only ever changing the 'User-Agent' line, you could just change
-the C<$browser> object's default line from "libwww-perl/5.65" (or the like)
-to whatever you like, using the LWP::UserAgent C<agent> method:
-
- $browser->agent('Mozilla/4.76 [en] (Win98; U)');
-
-
-
-=for comment
- ##########################################################################
-
-
-
-=head2 Enabling Cookies
-
-A default LWP::UserAgent object acts like a browser with its cookies
-support turned off. There are various ways of turning it on, by setting
-its C<cookie_jar> attribute. A "cookie jar" is an object representing
-a little database of all
-the HTTP cookies that a browser can know about. It can correspond to a
-file on disk (the way Netscape uses its F<cookies.txt> file), or it can
-be just an in-memory object that starts out empty, and whose collection of
-cookies will disappear once the program is finished running.
-
-To give a browser an in-memory empty cookie jar, you set its C<cookie_jar>
-attribute like so:
-
- $browser->cookie_jar({});
-
-To give it a copy that will be read from a file on disk, and will be saved
-to it when the program is finished running, set the C<cookie_jar> attribute
-like this:
-
- use HTTP::Cookies;
- $browser->cookie_jar( HTTP::Cookies->new(
- 'file' => '/some/where/cookies.lwp',
- # where to read/write cookies
- 'autosave' => 1,
- # save it to disk when done
- ));
-
-That file will be an LWP-specific format. If you want to be access the
-cookies in your Netscape cookies file, you can use the
-HTTP::Cookies::Netscape class:
-
- use HTTP::Cookies;
- # yes, loads HTTP::Cookies::Netscape too
-
- $browser->cookie_jar( HTTP::Cookies::Netscape->new(
- 'file' => 'c:/Program Files/Netscape/Users/DIR-NAME-HERE/cookies.txt',
- # where to read cookies
- ));
-
-You could add an C<< 'autosave' => 1 >> line as further above, but at
-time of writing, it's uncertain whether Netscape might discard some of
-the cookies you could be writing back to disk.
-
-
-
-=for comment
- ##########################################################################
-
-
-
-=head2 Posting Form Data
-
-Many HTML forms send data to their server using an HTTP POST request, which
-you can send with this syntax:
-
- $response = $browser->post( $url,
- [
- formkey1 => value1,
- formkey2 => value2,
- ...
- ],
- );
-
-Or if you need to send HTTP headers:
-
- $response = $browser->post( $url,
- [
- formkey1 => value1,
- formkey2 => value2,
- ...
- ],
- headerkey1 => value1,
- headerkey2 => value2,
- );
-
-For example, the following program makes a search request to AltaVista
-(by sending some form data via an HTTP POST request), and extracts from
-the HTML the report of the number of matches:
-
- use strict;
- use warnings;
- use LWP 5.64;
- my $browser = LWP::UserAgent->new;
-
- my $word = 'tarragon';
-
- my $url = 'http://search.yahoo.com/yhs/search';
- my $response = $browser->post( $url,
- [ 'q' => $word, # the Altavista query string
- 'fr' => 'altavista', 'pg' => 'q', 'avkw' => 'tgz', 'kl' => 'XX',
- ]
- );
- die "$url error: ", $response->status_line
- unless $response->is_success;
- die "Weird content type at $url -- ", $response->content_type
- unless $response->content_is_html;
-
- if( $response->decoded_content =~ m{([0-9,]+)(?:<.*?>)? results for} ) {
- # The substring will be like "996,000</strong> results for"
- print "$word: $1\n";
- }
- else {
- print "Couldn't find the match-string in the response\n";
- }
-
-
-
-=for comment
- ##########################################################################
-
-
-
-=head2 Sending GET Form Data
-
-Some HTML forms convey their form data not by sending the data
-in an HTTP POST request, but by making a normal GET request with
-the data stuck on the end of the URL. For example, if you went to
-C<www.imdb.com> and ran a search on "Blade Runner", the URL you'd see
-in your browser window would be:
-
- http://www.imdb.com/find?s=all&q=Blade+Runner
-
-To run the same search with LWP, you'd use this idiom, which involves
-the URI class:
-
- use URI;
- my $url = URI->new( 'http://www.imdb.com/find' );
- # makes an object representing the URL
-
- $url->query_form( # And here the form data pairs:
- 'q' => 'Blade Runner',
- 's' => 'all',
- );
-
- my $response = $browser->get($url);
-
-See chapter 5 of I<Perl & LWP> for a longer discussion of HTML forms
-and of form data, and chapters 6 through 9 for a longer discussion of
-extracting data from HTML.
-
-
-
-=head2 Absolutizing URLs
-
-The URI class that we just mentioned above provides all sorts of methods
-for accessing and modifying parts of URLs (such as asking sort of URL it
-is with C<< $url->scheme >>, and asking what host it refers to with C<<
-$url->host >>, and so on, as described in L<the docs for the URI
-class|URI>. However, the methods of most immediate interest
-are the C<query_form> method seen above, and now the C<new_abs> method
-for taking a probably-relative URL string (like "../foo.html") and getting
-back an absolute URL (like "http://www.perl.com/stuff/foo.html"), as
-shown here:
-
- use URI;
- $abs = URI->new_abs($maybe_relative, $base);
-
-For example, consider this program that matches URLs in the HTML
-list of new modules in CPAN:
-
- use strict;
- use warnings;
- use LWP;
- my $browser = LWP::UserAgent->new;
-
- my $url = 'http://www.cpan.org/RECENT.html';
- my $response = $browser->get($url);
- die "Can't get $url -- ", $response->status_line
- unless $response->is_success;
-
- my $html = $response->decoded_content;
- while( $html =~ m/<A HREF=\"(.*?)\"/g ) {
- print "$1\n";
- }
-
-When run, it emits output that starts out something like this:
-
- MIRRORING.FROM
- RECENT
- RECENT.html
- authors/00whois.html
- authors/01mailrc.txt.gz
- authors/id/A/AA/AASSAD/CHECKSUMS
- ...
-
-However, if you actually want to have those be absolute URLs, you
-can use the URI module's C<new_abs> method, by changing the C<while>
-loop to this:
-
- while( $html =~ m/<A HREF=\"(.*?)\"/g ) {
- print URI->new_abs( $1, $response->base ) ,"\n";
- }
-
-(The C<< $response->base >> method from L<HTTP::Message|HTTP::Message>
-is for returning what URL
-should be used for resolving relative URLs -- it's usually just
-the same as the URL that you requested.)
-
-That program then emits nicely absolute URLs:
-
- http://www.cpan.org/MIRRORING.FROM
- http://www.cpan.org/RECENT
- http://www.cpan.org/RECENT.html
- http://www.cpan.org/authors/00whois.html
- http://www.cpan.org/authors/01mailrc.txt.gz
- http://www.cpan.org/authors/id/A/AA/AASSAD/CHECKSUMS
- ...
-
-See chapter 4 of I<Perl & LWP> for a longer discussion of URI objects.
-
-Of course, using a regexp to match hrefs is a bit simplistic, and for
-more robust programs, you'll probably want to use an HTML-parsing module
-like L<HTML::LinkExtor> or L<HTML::TokeParser> or even maybe
-L<HTML::TreeBuilder>.
-
-
-
-
-=for comment
- ##########################################################################
-
-=head2 Other Browser Attributes
-
-LWP::UserAgent objects have many attributes for controlling how they
-work. Here are a few notable ones:
-
-=over
-
-=item *
-
-C<< $browser->timeout(15); >>
-
-This sets this browser object to give up on requests that don't answer
-within 15 seconds.
-
-
-=item *
-
-C<< $browser->protocols_allowed( [ 'http', 'gopher'] ); >>
-
-This sets this browser object to not speak any protocols other than HTTP
-and gopher. If it tries accessing any other kind of URL (like an "ftp:"
-or "mailto:" or "news:" URL), then it won't actually try connecting, but
-instead will immediately return an error code 500, with a message like
-"Access to 'ftp' URIs has been disabled".
-
-
-=item *
-
-C<< use LWP::ConnCache; $browser->conn_cache(LWP::ConnCache->new()); >>
-
-This tells the browser object to try using the HTTP/1.1 "Keep-Alive"
-feature, which speeds up requests by reusing the same socket connection
-for multiple requests to the same server.
-
-
-=item *
-
-C<< $browser->agent( 'SomeName/1.23 (more info here maybe)' ) >>
-
-This changes how the browser object will identify itself in
-the default "User-Agent" line is its HTTP requests. By default,
-it'll send "libwww-perl/I<versionnumber>", like
-"libwww-perl/5.65". You can change that to something more descriptive
-like this:
-
- $browser->agent( 'SomeName/3.14 (contact@robotplexus.int)' );
-
-Or if need be, you can go in disguise, like this:
-
- $browser->agent( 'Mozilla/4.0 (compatible; MSIE 5.12; Mac_PowerPC)' );
-
-
-=item *
-
-C<< push @{ $ua->requests_redirectable }, 'POST'; >>
-
-This tells this browser to obey redirection responses to POST requests
-(like most modern interactive browsers), even though the HTTP RFC says
-that should not normally be done.
-
-
-=back
-
-
-For more options and information, see L<the full documentation for
-LWP::UserAgent|LWP::UserAgent>.
-
-
-
-=for comment
- ##########################################################################
-
-
-
-=head2 Writing Polite Robots
-
-If you want to make sure that your LWP-based program respects F<robots.txt>
-files and doesn't make too many requests too fast, you can use the LWP::RobotUA
-class instead of the LWP::UserAgent class.
-
-LWP::RobotUA class is just like LWP::UserAgent, and you can use it like so:
-
- use LWP::RobotUA;
- my $browser = LWP::RobotUA->new('YourSuperBot/1.34', 'you@yoursite.com');
- # Your bot's name and your email address
-
- my $response = $browser->get($url);
-
-But HTTP::RobotUA adds these features:
-
-
-=over
-
-=item *
-
-If the F<robots.txt> on C<$url>'s server forbids you from accessing
-C<$url>, then the C<$browser> object (assuming it's of class LWP::RobotUA)
-won't actually request it, but instead will give you back (in C<$response>) a 403 error
-with a message "Forbidden by robots.txt". That is, if you have this line:
-
- die "$url -- ", $response->status_line, "\nAborted"
- unless $response->is_success;
-
-then the program would die with an error message like this:
-
- http://whatever.site.int/pith/x.html -- 403 Forbidden by robots.txt
- Aborted at whateverprogram.pl line 1234
-
-=item *
-
-If this C<$browser> object sees that the last time it talked to
-C<$url>'s server was too recently, then it will pause (via C<sleep>) to
-avoid making too many requests too often. How long it will pause for, is
-by default one minute -- but you can control it with the C<<
-$browser->delay( I<minutes> ) >> attribute.
-
-For example, this code:
-
- $browser->delay( 7/60 );
-
-...means that this browser will pause when it needs to avoid talking to
-any given server more than once every 7 seconds.
-
-=back
-
-For more options and information, see L<the full documentation for
-LWP::RobotUA|LWP::RobotUA>.
-
-
-
-
-
-=for comment
- ##########################################################################
-
-=head2 Using Proxies
-
-In some cases, you will want to (or will have to) use proxies for
-accessing certain sites and/or using certain protocols. This is most
-commonly the case when your LWP program is running (or could be running)
-on a machine that is behind a firewall.
-
-To make a browser object use proxies that are defined in the usual
-environment variables (C<HTTP_PROXY>, etc.), just call the C<env_proxy>
-on a user-agent object before you go making any requests on it.
-Specifically:
-
- use LWP::UserAgent;
- my $browser = LWP::UserAgent->new;
-
- # And before you go making any requests:
- $browser->env_proxy;
-
-For more information on proxy parameters, see L<the LWP::UserAgent
-documentation|LWP::UserAgent>, specifically the C<proxy>, C<env_proxy>,
-and C<no_proxy> methods.
-
-
-
-=for comment
- ##########################################################################
-
-=head2 HTTP Authentication
-
-Many web sites restrict access to documents by using "HTTP
-Authentication". This isn't just any form of "enter your password"
-restriction, but is a specific mechanism where the HTTP server sends the
-browser an HTTP code that says "That document is part of a protected
-'realm', and you can access it only if you re-request it and add some
-special authorization headers to your request".
-
-For example, the Unicode.org admins stop email-harvesting bots from
-harvesting the contents of their mailing list archives, by protecting
-them with HTTP Authentication, and then publicly stating the username
-and password (at C<http://www.unicode.org/mail-arch/>) -- namely
-username "unicode-ml" and password "unicode".
-
-For example, consider this URL, which is part of the protected
-area of the web site:
-
- http://www.unicode.org/mail-arch/unicode-ml/y2002-m08/0067.html
-
-If you access that with a browser, you'll get a prompt
-like
-"Enter username and password for 'Unicode-MailList-Archives' at server
-'www.unicode.org'".
-
-In LWP, if you just request that URL, like this:
-
- use LWP;
- my $browser = LWP::UserAgent->new;
-
- my $url =
- 'http://www.unicode.org/mail-arch/unicode-ml/y2002-m08/0067.html';
- my $response = $browser->get($url);
-
- die "Error: ", $response->header('WWW-Authenticate') || 'Error accessing',
- # ('WWW-Authenticate' is the realm-name)
- "\n ", $response->status_line, "\n at $url\n Aborting"
- unless $response->is_success;
-
-Then you'll get this error:
-
- Error: Basic realm="Unicode-MailList-Archives"
- 401 Authorization Required
- at http://www.unicode.org/mail-arch/unicode-ml/y2002-m08/0067.html
- Aborting at auth1.pl line 9. [or wherever]
-
-...because the C<$browser> doesn't know any the username and password
-for that realm ("Unicode-MailList-Archives") at that host
-("www.unicode.org"). The simplest way to let the browser know about this
-is to use the C<credentials> method to let it know about a username and
-password that it can try using for that realm at that host. The syntax is:
-
- $browser->credentials(
- 'servername:portnumber',
- 'realm-name',
- 'username' => 'password'
- );
-
-In most cases, the port number is 80, the default TCP/IP port for HTTP; and
-you usually call the C<credentials> method before you make any requests.
-For example:
-
- $browser->credentials(
- 'reports.mybazouki.com:80',
- 'web_server_usage_reports',
- 'plinky' => 'banjo123'
- );
-
-So if we add the following to the program above, right after the C<<
-$browser = LWP::UserAgent->new; >> line...
-
- $browser->credentials( # add this to our $browser 's "key ring"
- 'www.unicode.org:80',
- 'Unicode-MailList-Archives',
- 'unicode-ml' => 'unicode'
- );
-
-...then when we run it, the request succeeds, instead of causing the
-C<die> to be called.
-
-
-
-=for comment
- ##########################################################################
-
-=head2 Accessing HTTPS URLs
-
-When you access an HTTPS URL, it'll work for you just like an HTTP URL
-would -- if your LWP installation has HTTPS support (via an appropriate
-Secure Sockets Layer library). For example:
-
- use LWP;
- my $url = 'https://www.paypal.com/'; # Yes, HTTPS!
- my $browser = LWP::UserAgent->new;
- my $response = $browser->get($url);
- die "Error at $url\n ", $response->status_line, "\n Aborting"
- unless $response->is_success;
- print "Whee, it worked! I got that ",
- $response->content_type, " document!\n";
-
-If your LWP installation doesn't have HTTPS support set up, then the
-response will be unsuccessful, and you'll get this error message:
-
- Error at https://www.paypal.com/
- 501 Protocol scheme 'https' is not supported
- Aborting at paypal.pl line 7. [or whatever program and line]
-
-If your LWP installation I<does> have HTTPS support installed, then the
-response should be successful, and you should be able to consult
-C<$response> just like with any normal HTTP response.
-
-For information about installing HTTPS support for your LWP
-installation, see the helpful F<README.SSL> file that comes in the
-libwww-perl distribution.
-
-
-=for comment
- ##########################################################################
-
-
-
-=head2 Getting Large Documents
-
-When you're requesting a large (or at least potentially large) document,
-a problem with the normal way of using the request methods (like C<<
-$response = $browser->get($url) >>) is that the response object in
-memory will have to hold the whole document -- I<in memory>. If the
-response is a thirty megabyte file, this is likely to be quite an
-imposition on this process's memory usage.
-
-A notable alternative is to have LWP save the content to a file on disk,
-instead of saving it up in memory. This is the syntax to use:
-
- $response = $ua->get($url,
- ':content_file' => $filespec,
- );
-
-For example,
-
- $response = $ua->get('http://search.cpan.org/',
- ':content_file' => '/tmp/sco.html'
- );
-
-When you use this C<:content_file> option, the C<$response> will have
-all the normal header lines, but C<< $response->content >> will be
-empty.
-
-Note that this ":content_file" option isn't supported under older
-versions of LWP, so you should consider adding C<use LWP 5.66;> to check
-the LWP version, if you think your program might run on systems with
-older versions.
-
-If you need to be compatible with older LWP versions, then use
-this syntax, which does the same thing:
-
- use HTTP::Request::Common;
- $response = $ua->request( GET($url), $filespec );
-
-
-=for comment
- ##########################################################################
-
-
-=head1 SEE ALSO
-
-Remember, this article is just the most rudimentary introduction to
-LWP -- to learn more about LWP and LWP-related tasks, you really
-must read from the following:
-
-=over
-
-=item *
-
-L<LWP::Simple> -- simple functions for getting/heading/mirroring URLs
-
-=item *
-
-L<LWP> -- overview of the libwww-perl modules
-
-=item *
-
-L<LWP::UserAgent> -- the class for objects that represent "virtual browsers"
-
-=item *
-
-L<HTTP::Response> -- the class for objects that represent the response to
-a LWP response, as in C<< $response = $browser->get(...) >>
-
-=item *
-
-L<HTTP::Message> and L<HTTP::Headers> -- classes that provide more methods
-to HTTP::Response.
-
-=item *
-
-L<URI> -- class for objects that represent absolute or relative URLs
-
-=item *
-
-L<URI::Escape> -- functions for URL-escaping and URL-unescaping strings
-(like turning "this & that" to and from "this%20%26%20that").
-
-=item *
-
-L<HTML::Entities> -- functions for HTML-escaping and HTML-unescaping strings
-(like turning "C. & E. BrontE<euml>" to and from "C. &amp; E. Bront&euml;")
-
-=item *
-
-L<HTML::TokeParser> and L<HTML::TreeBuilder> -- classes for parsing HTML
-
-=item *
-
-L<HTML::LinkExtor> -- class for finding links in HTML documents
-
-=item *
-
-The book I<Perl & LWP> by Sean M. Burke. O'Reilly & Associates,
-2002. ISBN: 0-596-00178-9, L<http://oreilly.com/catalog/perllwp/>. The
-whole book is also available free online:
-L<http://lwp.interglacial.com>.
-
-=back
-
-
-=head1 COPYRIGHT
-
-Copyright 2002, Sean M. Burke. You can redistribute this document and/or
-modify it, but only under the same terms as Perl itself.
-
-=head1 AUTHOR
-
-Sean M. Burke C<sburke@cpan.org>
-
-=for comment
- ##########################################################################
-
-=cut
-
-# End of Pod
diff --git a/Master/tlpkg/tlperl/lib/perllocal.pod b/Master/tlpkg/tlperl/lib/perllocal.pod
deleted file mode 100644
index 57a67a6b7f0..00000000000
--- a/Master/tlpkg/tlperl/lib/perllocal.pod
+++ /dev/null
@@ -1,506 +0,0 @@
-=head2 Sat Nov 17 13:05:52 2012: C<Module> L<Win32::API|Win32::API>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 0.68>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 13:07:00 2012: C<Module> L<Win32::Shortcut|Win32::Shortcut>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 0.07>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 13:08:22 2012: C<Module> L<Win32API::Registry|Win32API::Registry>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 0.32>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 21:49:34 2012: C<Module> L<Win32::TieRegistry|Win32::TieRegistry>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 0.26>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 21:50:53 2012: C<Module> L<Win32::Process::Info|Win32::Process::Info>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 1.019>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 22:13:33 2012: C<Module> L<Tk|Tk>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 804.03>
-
-=item *
-
-C<EXE_FILES: ptksh ptked gedi>
-
-=back
-
-=head2 Sat Nov 17 22:15:25 2012: C<Module> L<HTML::Tagset|HTML::Tagset>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 3.20>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 22:16:33 2012: C<Module> L<HTML::Parser|HTML::Parser>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 3.69>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 22:17:43 2012: C<Module> L<URI|URI>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 1.60>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 22:18:21 2012: C<Module> L<Encode::Locale|Encode::Locale>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 1.03>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 22:19:01 2012: C<Module> L<HTTP::Date|HTTP::Date>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 6.02>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 22:20:02 2012: C<Module> L<File::Listing|File::Listing>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 6.04>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 22:20:43 2012: C<Module> L<LWP::MediaTypes|LWP::MediaTypes>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 6.02>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 22:21:36 2012: C<Module> L<HTTP::Message|HTTP::Message>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 6.03>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 22:22:27 2012: C<Module> L<HTTP::Cookies|HTTP::Cookies>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 6.01>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 22:23:13 2012: C<Module> L<HTTP::Daemon|HTTP::Daemon>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 6.01>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 22:23:55 2012: C<Module> L<HTTP::Negotiate|HTTP::Negotiate>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 6.01>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 22:24:28 2012: C<Module> L<Net::HTTP|Net::HTTP>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 6.03>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 22:28:00 2012: C<Module> L<WWW::RobotRules|WWW::RobotRules>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 6.02>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 22:29:15 2012: C<Module> L<LWP|LWP>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 6.04>
-
-=item *
-
-C<EXE_FILES: bin/lwp-request bin/lwp-mirror bin/lwp-download bin/lwp-dump>
-
-=back
-
-=head2 Sat Nov 17 22:29:51 2012: C<Module> L<IO::String|IO::String>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 1.08>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Sat Nov 17 22:30:33 2012: C<Module> L<Digest::SHA1|Digest::SHA1>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 2.13>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
-=head2 Tue Mar 5 22:14:06 2013: C<Module> L<Win32::OLE|Win32::OLE>
-
-=over 4
-
-=item *
-
-C<installed into: c:\perl\site\lib>
-
-=item *
-
-C<LINKTYPE: dynamic>
-
-=item *
-
-C<VERSION: 0.1709>
-
-=item *
-
-C<EXE_FILES: >
-
-=back
-
diff --git a/Master/tlpkg/tlperl/lib/pods/a2p.pod b/Master/tlpkg/tlperl/lib/pods/a2p.pod
deleted file mode 100644
index d32a9c7efa1..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/a2p.pod
+++ /dev/null
@@ -1,179 +0,0 @@
-=head1 NAME
-
-a2p - Awk to Perl translator
-
-=head1 SYNOPSIS
-
-B<a2p> [I<options>] [I<filename>]
-
-=head1 DESCRIPTION
-
-I<A2p> takes an awk script specified on the command line (or from
-standard input) and produces a comparable I<perl> script on the
-standard output.
-
-=head2 OPTIONS
-
-Options include:
-
-=over 5
-
-=item B<-DE<lt>numberE<gt>>
-
-sets debugging flags.
-
-=item B<-FE<lt>characterE<gt>>
-
-tells a2p that this awk script is always invoked with this B<-F>
-switch.
-
-=item B<-nE<lt>fieldlistE<gt>>
-
-specifies the names of the input fields if input does not have to be
-split into an array. If you were translating an awk script that
-processes the password file, you might say:
-
- a2p -7 -nlogin.password.uid.gid.gcos.shell.home
-
-Any delimiter can be used to separate the field names.
-
-=item B<-E<lt>numberE<gt>>
-
-causes a2p to assume that input will always have that many fields.
-
-=item B<-o>
-
-tells a2p to use old awk behavior. The only current differences are:
-
-=over 5
-
-=item *
-
-Old awk always has a line loop, even if there are no line
-actions, whereas new awk does not.
-
-=item *
-
-In old awk, sprintf is extremely greedy about its arguments.
-For example, given the statement
-
- print sprintf(some_args), extra_args;
-
-old awk considers I<extra_args> to be arguments to C<sprintf>; new awk
-considers them arguments to C<print>.
-
-=back
-
-=back
-
-=head2 "Considerations"
-
-A2p cannot do as good a job translating as a human would, but it
-usually does pretty well. There are some areas where you may want to
-examine the perl script produced and tweak it some. Here are some of
-them, in no particular order.
-
-There is an awk idiom of putting int() around a string expression to
-force numeric interpretation, even though the argument is always
-integer anyway. This is generally unneeded in perl, but a2p can't
-tell if the argument is always going to be integer, so it leaves it
-in. You may wish to remove it.
-
-Perl differentiates numeric comparison from string comparison. Awk
-has one operator for both that decides at run time which comparison to
-do. A2p does not try to do a complete job of awk emulation at this
-point. Instead it guesses which one you want. It's almost always
-right, but it can be spoofed. All such guesses are marked with the
-comment "C<#???>". You should go through and check them. You might
-want to run at least once with the B<-w> switch to perl, which will
-warn you if you use == where you should have used eq.
-
-Perl does not attempt to emulate the behavior of awk in which
-nonexistent array elements spring into existence simply by being
-referenced. If somehow you are relying on this mechanism to create
-null entries for a subsequent for...in, they won't be there in perl.
-
-If a2p makes a split line that assigns to a list of variables that
-looks like (Fld1, Fld2, Fld3...) you may want to rerun a2p using the
-B<-n> option mentioned above. This will let you name the fields
-throughout the script. If it splits to an array instead, the script
-is probably referring to the number of fields somewhere.
-
-The exit statement in awk doesn't necessarily exit; it goes to the END
-block if there is one. Awk scripts that do contortions within the END
-block to bypass the block under such circumstances can be simplified
-by removing the conditional in the END block and just exiting directly
-from the perl script.
-
-Perl has two kinds of array, numerically-indexed and associative.
-Perl associative arrays are called "hashes". Awk arrays are usually
-translated to hashes, but if you happen to know that the index is
-always going to be numeric you could change the {...} to [...].
-Iteration over a hash is done using the keys() function, but iteration
-over an array is NOT. You might need to modify any loop that iterates
-over such an array.
-
-Awk starts by assuming OFMT has the value %.6g. Perl starts by
-assuming its equivalent, $#, to have the value %.20g. You'll want to
-set $# explicitly if you use the default value of OFMT.
-
-Near the top of the line loop will be the split operation that is
-implicit in the awk script. There are times when you can move this
-down past some conditionals that test the entire record so that the
-split is not done as often.
-
-For aesthetic reasons you may wish to change index variables from being
-1-based (awk style) to 0-based (Perl style). Be sure to change all
-operations the variable is involved in to match.
-
-Cute comments that say "# Here is a workaround because awk is dumb"
-are passed through unmodified.
-
-Awk scripts are often embedded in a shell script that pipes stuff into
-and out of awk. Often the shell script wrapper can be incorporated
-into the perl script, since perl can start up pipes into and out of
-itself, and can do other things that awk can't do by itself.
-
-Scripts that refer to the special variables RSTART and RLENGTH can
-often be simplified by referring to the variables $`, $& and $', as
-long as they are within the scope of the pattern match that sets them.
-
-The produced perl script may have subroutines defined to deal with
-awk's semantics regarding getline and print. Since a2p usually picks
-correctness over efficiency. it is almost always possible to rewrite
-such code to be more efficient by discarding the semantic sugar.
-
-For efficiency, you may wish to remove the keyword from any return
-statement that is the last statement executed in a subroutine. A2p
-catches the most common case, but doesn't analyze embedded blocks for
-subtler cases.
-
-ARGV[0] translates to $ARGV0, but ARGV[n] translates to $ARGV[$n-1]. A
-loop that tries to iterate over ARGV[0] won't find it.
-
-=head1 ENVIRONMENT
-
-A2p uses no environment variables.
-
-=head1 AUTHOR
-
-Larry Wall E<lt>F<larry@wall.org>E<gt>
-
-=head1 FILES
-
-=head1 SEE ALSO
-
- perl The perl compiler/interpreter
-
- s2p sed to perl translator
-
-=head1 DIAGNOSTICS
-
-=head1 BUGS
-
-It would be possible to emulate awk's behavior in selecting string
-versus numeric operations at run time by inspection of the operands,
-but it would be gross and inefficient. Besides, a2p almost always
-guesses right.
-
-Storage for the awk syntax tree is currently static, and can run out.
diff --git a/Master/tlpkg/tlperl/lib/pods/perl.pod b/Master/tlpkg/tlperl/lib/pods/perl.pod
deleted file mode 100644
index 5f154980ee0..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl.pod
+++ /dev/null
@@ -1,480 +0,0 @@
-=head1 NAME
-
-perl - The Perl 5 language interpreter
-
-=head1 SYNOPSIS
-
-B<perl> S<[ B<-sTtuUWX> ]>
- S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
- S<[ B<-cw> ] [ B<-d>[B<t>][:I<debugger>] ] [ B<-D>[I<number/list>] ]>
- S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal/hexadecimal>] ]>
- S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ] [ B<-f> ]>
- S<[ B<-C [I<number/list>] >]>
- S<[ B<-S> ]>
- S<[ B<-x>[I<dir>] ]>
- S<[ B<-i>[I<extension>] ]>
- S<[ [B<-e>|B<-E>] I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
-
-=head1 GETTING HELP
-
-The F<perldoc> program gives you access to all the documentation that comes
-with Perl. You can get more documentation, tutorials and community support
-online at L<http://www.perl.org/>.
-
-If you're new to Perl, you should start by running C<perldoc perlintro>,
-which is a general intro for beginners and provides some background to help
-you navigate the rest of Perl's extensive documentation. Run C<perldoc
-perldoc> to learn more things you can do with F<perldoc>.
-
-For ease of access, the Perl manual has been split up into several sections.
-
-=begin buildtoc
-
-# This section is parsed by Porting/pod_lib.pl for use by pod/buildtoc etc
-
-flag =g perluniprops perlmodlib perlapi perlintern
-flag =go perltoc
-flag =ro perlcn perljp perlko perltw
-flag = perlvms
-
-path perlfaq.* cpan/perlfaq/lib/
-path perlglossary cpan/perlfaq/lib/
-path perlxs(?:tut|typemap)? dist/ExtUtils-ParseXS/lib/
-path perldoc cpan/Pod-Perldoc/lib/
-
-aux a2p c2ph h2ph h2xs perlbug pl2pm pod2html pod2man s2p splain xsubpp
-
-=end buildtoc
-
-=head2 Overview
-
- perl Perl overview (this section)
- perlintro Perl introduction for beginners
- perltoc Perl documentation table of contents
-
-=head2 Tutorials
-
- perlreftut Perl references short introduction
- perldsc Perl data structures intro
- perllol Perl data structures: arrays of arrays
-
- perlrequick Perl regular expressions quick start
- perlretut Perl regular expressions tutorial
-
- perlootut Perl OO tutorial for beginners
-
- perlperf Perl Performance and Optimization Techniques
-
- perlstyle Perl style guide
-
- perlcheat Perl cheat sheet
- perltrap Perl traps for the unwary
- perldebtut Perl debugging tutorial
-
- perlfaq Perl frequently asked questions
- perlfaq1 General Questions About Perl
- perlfaq2 Obtaining and Learning about Perl
- perlfaq3 Programming Tools
- perlfaq4 Data Manipulation
- perlfaq5 Files and Formats
- perlfaq6 Regexes
- perlfaq7 Perl Language Issues
- perlfaq8 System Interaction
- perlfaq9 Networking
-
-=head2 Reference Manual
-
- perlsyn Perl syntax
- perldata Perl data structures
- perlop Perl operators and precedence
- perlsub Perl subroutines
- perlfunc Perl built-in functions
- perlopentut Perl open() tutorial
- perlpacktut Perl pack() and unpack() tutorial
- perlpod Perl plain old documentation
- perlpodspec Perl plain old documentation format specification
- perlpodstyle Perl POD style guide
- perlrun Perl execution and options
- perldiag Perl diagnostic messages
- perllexwarn Perl warnings and their control
- perldebug Perl debugging
- perlvar Perl predefined variables
- perlre Perl regular expressions, the rest of the story
- perlrebackslash Perl regular expression backslash sequences
- perlrecharclass Perl regular expression character classes
- perlreref Perl regular expressions quick reference
- perlref Perl references, the rest of the story
- perlform Perl formats
- perlobj Perl objects
- perltie Perl objects hidden behind simple variables
- perldbmfilter Perl DBM filters
-
- perlipc Perl interprocess communication
- perlfork Perl fork() information
- perlnumber Perl number semantics
-
- perlthrtut Perl threads tutorial
-
- perlport Perl portability guide
- perllocale Perl locale support
- perluniintro Perl Unicode introduction
- perlunicode Perl Unicode support
- perlunifaq Perl Unicode FAQ
- perluniprops Index of Unicode Version 6.0.0 properties in Perl
- perlunitut Perl Unicode tutorial
- perlebcdic Considerations for running Perl on EBCDIC platforms
-
- perlsec Perl security
-
- perlmod Perl modules: how they work
- perlmodlib Perl modules: how to write and use
- perlmodstyle Perl modules: how to write modules with style
- perlmodinstall Perl modules: how to install from CPAN
- perlnewmod Perl modules: preparing a new module for distribution
- perlpragma Perl modules: writing a user pragma
-
- perlutil utilities packaged with the Perl distribution
-
- perlfilter Perl source filters
-
- perldtrace Perl's support for DTrace
-
- perlglossary Perl Glossary
-
-=head2 Internals and C Language Interface
-
- perlembed Perl ways to embed perl in your C or C++ application
- perldebguts Perl debugging guts and tips
- perlxstut Perl XS tutorial
- perlxs Perl XS application programming interface
- perlxstypemap Perl XS C/Perl type conversion tools
- perlclib Internal replacements for standard C library functions
- perlguts Perl internal functions for those doing extensions
- perlcall Perl calling conventions from C
- perlmroapi Perl method resolution plugin interface
- perlreapi Perl regular expression plugin interface
- perlreguts Perl regular expression engine internals
-
- perlapi Perl API listing (autogenerated)
- perlintern Perl internal functions (autogenerated)
- perliol C API for Perl's implementation of IO in Layers
- perlapio Perl internal IO abstraction interface
-
- perlhack Perl hackers guide
- perlsource Guide to the Perl source tree
- perlinterp Overview of the Perl interpreter source and how it works
- perlhacktut Walk through the creation of a simple C code patch
- perlhacktips Tips for Perl core C code hacking
- perlpolicy Perl development policies
- perlgit Using git with the Perl repository
-
-=head2 Miscellaneous
-
- perlbook Perl book information
- perlcommunity Perl community information
-
- perldoc Look up Perl documentation in Pod format
-
- perlhist Perl history records
- perldelta Perl changes since previous version
- perl5161delta Perl changes in version 5.16.1
- perl5160delta Perl changes in version 5.16.0
- perl5160delta Perl changes in version 5.16.0
- perl5143delta Perl changes in version 5.14.3
- perl5142delta Perl changes in version 5.14.2
- perl5141delta Perl changes in version 5.14.1
- perl5140delta Perl changes in version 5.14.0
- perl5124delta Perl changes in version 5.12.4
- perl5123delta Perl changes in version 5.12.3
- perl5122delta Perl changes in version 5.12.2
- perl5121delta Perl changes in version 5.12.1
- perl5120delta Perl changes in version 5.12.0
- perl5101delta Perl changes in version 5.10.1
- perl5100delta Perl changes in version 5.10.0
- perl589delta Perl changes in version 5.8.9
- perl588delta Perl changes in version 5.8.8
- perl587delta Perl changes in version 5.8.7
- perl586delta Perl changes in version 5.8.6
- perl585delta Perl changes in version 5.8.5
- perl584delta Perl changes in version 5.8.4
- perl583delta Perl changes in version 5.8.3
- perl582delta Perl changes in version 5.8.2
- perl581delta Perl changes in version 5.8.1
- perl58delta Perl changes in version 5.8.0
- perl561delta Perl changes in version 5.6.1
- perl56delta Perl changes in version 5.6
- perl5005delta Perl changes in version 5.005
- perl5004delta Perl changes in version 5.004
-
- perlexperiment A listing of experimental features in Perl
-
- perlartistic Perl Artistic License
- perlgpl GNU General Public License
-
-=head2 Language-Specific
-
-=for buildtoc flag +r
-
- perlcn Perl for Simplified Chinese (in EUC-CN)
- perljp Perl for Japanese (in EUC-JP)
- perlko Perl for Korean (in EUC-KR)
- perltw Perl for Traditional Chinese (in Big5)
-
-=head2 Platform-Specific
-
- perlaix Perl notes for AIX
- perlamiga Perl notes for AmigaOS
- perlbeos Perl notes for BeOS
- perlbs2000 Perl notes for POSIX-BC BS2000
- perlce Perl notes for WinCE
- perlcygwin Perl notes for Cygwin
- perldgux Perl notes for DG/UX
- perldos Perl notes for DOS
- perlepoc Perl notes for EPOC
- perlfreebsd Perl notes for FreeBSD
- perlhaiku Perl notes for Haiku
- perlhpux Perl notes for HP-UX
- perlhurd Perl notes for Hurd
- perlirix Perl notes for Irix
- perllinux Perl notes for Linux
- perlmacos Perl notes for Mac OS (Classic)
- perlmacosx Perl notes for Mac OS X
- perlmpeix Perl notes for MPE/iX
- perlnetware Perl notes for NetWare
- perlopenbsd Perl notes for OpenBSD
- perlos2 Perl notes for OS/2
- perlos390 Perl notes for OS/390
- perlos400 Perl notes for OS/400
- perlplan9 Perl notes for Plan 9
- perlqnx Perl notes for QNX
- perlriscos Perl notes for RISC OS
- perlsolaris Perl notes for Solaris
- perlsymbian Perl notes for Symbian
- perltru64 Perl notes for Tru64
- perluts Perl notes for UTS
- perlvmesa Perl notes for VM/ESA
- perlvms Perl notes for VMS
- perlvos Perl notes for Stratus VOS
- perlwin32 Perl notes for Windows
-
-=for buildtoc flag -r
-
-=head2 Stubs for Deleted Documents
-
- perlboot
- perlbot
- perltodo
- perltooc
- perltoot
-
-=for buildtoc __END__
-
-On a Unix-like system, these documentation files will usually also be
-available as manpages for use with the F<man> program.
-
-In general, if something strange has gone wrong with your program and you're
-not sure where you should look for help, try the B<-w> switch first. It will
-often point out exactly where the trouble is.
-
-=head1 DESCRIPTION
-
-Perl officially stands for Practical Extraction and Report Language,
-except when it doesn't.
-
-Perl was originally a language optimized for scanning arbitrary
-text files, extracting information from those text files, and printing
-reports based on that information. It quickly became a good language
-for many system management tasks. Over the years, Perl has grown into
-a general-purpose programming language. It's widely used for everything
-from quick "one-liners" to full-scale application development.
-
-The language is intended to be practical (easy to use, efficient,
-complete) rather than beautiful (tiny, elegant, minimal).
-
-Perl combines (in the author's opinion, anyway) some of the best
-features of C, B<sed>, B<awk>, and B<sh>, so people familiar with
-those languages should have little difficulty with it. (Language
-historians will also note some vestiges of B<csh>, Pascal, and even
-BASIC-PLUS.) Expression syntax corresponds closely to C
-expression syntax. Unlike most Unix utilities, Perl does not
-arbitrarily limit the size of your data--if you've got the memory,
-Perl can slurp in your whole file as a single string. Recursion is of
-unlimited depth. And the tables used by hashes (sometimes called
-"associative arrays") grow as necessary to prevent degraded
-performance. Perl can use sophisticated pattern matching techniques to
-scan large amounts of data quickly. Although optimized for
-scanning text, Perl also has many excellent tools for slicing
-and dicing binary data.
-
-But wait, there's more...
-
-Begun in 1993 (see L<perlhist>), Perl version 5 is nearly a complete
-rewrite that provides the following additional benefits:
-
-=over 4
-
-=item *
-
-modularity and reusability using innumerable modules
-
-Described in L<perlmod>, L<perlmodlib>, and L<perlmodinstall>.
-
-=item *
-
-embeddable and extensible
-
-Described in L<perlembed>, L<perlxstut>, L<perlxs>, L<perlxstypemap>,
-L<perlcall>, L<perlguts>, and L<xsubpp>.
-
-=item *
-
-roll-your-own magic variables (including multiple simultaneous DBM
-implementations)
-
-Described in L<perltie> and L<AnyDBM_File>.
-
-=item *
-
-subroutines can now be overridden, autoloaded, and prototyped
-
-Described in L<perlsub>.
-
-=item *
-
-arbitrarily nested data structures and anonymous functions
-
-Described in L<perlreftut>, L<perlref>, L<perldsc>, and L<perllol>.
-
-=item *
-
-object-oriented programming
-
-Described in L<perlobj> and L<perlootut>.
-
-=item *
-
-support for light-weight processes (threads)
-
-Described in L<perlthrtut> and L<threads>.
-
-=item *
-
-support for Unicode, internationalization, and localization
-
-Described in L<perluniintro>, L<perllocale> and L<Locale::Maketext>.
-
-=item *
-
-lexical scoping
-
-Described in L<perlsub>.
-
-=item *
-
-regular expression enhancements
-
-Described in L<perlre>, with additional examples in L<perlop>.
-
-=item *
-
-enhanced debugger and interactive Perl environment,
-with integrated editor support
-
-Described in L<perldebtut>, L<perldebug> and L<perldebguts>.
-
-=item *
-
-POSIX 1003.1 compliant library
-
-Described in L<POSIX>.
-
-=back
-
-Okay, that's I<definitely> enough hype.
-
-=head1 AVAILABILITY
-
-Perl is available for most operating systems, including virtually
-all Unix-like platforms. See L<perlport/"Supported Platforms">
-for a listing.
-
-=head1 ENVIRONMENT
-
-See L<perlrun>.
-
-=head1 AUTHOR
-
-Larry Wall <larry@wall.org>, with the help of oodles of other folks.
-
-If your Perl success stories and testimonials may be of help to others
-who wish to advocate the use of Perl in their applications,
-or if you wish to simply express your gratitude to Larry and the
-Perl developers, please write to perl-thanks@perl.org .
-
-=head1 FILES
-
- "@INC" locations of perl libraries
-
-=head1 SEE ALSO
-
- http://www.perl.org/ the Perl homepage
- http://www.perl.com/ Perl articles (O'Reilly)
- http://www.cpan.org/ the Comprehensive Perl Archive
- http://www.pm.org/ the Perl Mongers
-
-=head1 DIAGNOSTICS
-
-The C<use warnings> pragma (and the B<-w> switch) produces some
-lovely diagnostics.
-
-See L<perldiag> for explanations of all Perl's diagnostics. The C<use
-diagnostics> pragma automatically turns Perl's normally terse warnings
-and errors into these longer forms.
-
-Compilation errors will tell you the line number of the error, with an
-indication of the next token or token type that was to be examined.
-(In a script passed to Perl via B<-e> switches, each
-B<-e> is counted as one line.)
-
-Setuid scripts have additional constraints that can produce error
-messages such as "Insecure dependency". See L<perlsec>.
-
-Did we mention that you should definitely consider using the B<-w>
-switch?
-
-=head1 BUGS
-
-The B<-w> switch is not mandatory.
-
-Perl is at the mercy of your machine's definitions of various
-operations such as type casting, atof(), and floating-point
-output with sprintf().
-
-If your stdio requires a seek or eof between reads and writes on a
-particular stream, so does Perl. (This doesn't apply to sysread()
-and syswrite().)
-
-While none of the built-in data types have any arbitrary size limits
-(apart from memory size), there are still a few arbitrary limits: a
-given variable name may not be longer than 251 characters. Line numbers
-displayed by diagnostics are internally stored as short integers,
-so they are limited to a maximum of 65535 (higher numbers usually being
-affected by wraparound).
-
-You may mail your bug reports (be sure to include full configuration
-information as output by the myconfig program in the perl source
-tree, or by C<perl -V>) to perlbug@perl.org . If you've succeeded
-in compiling perl, the L<perlbug> script in the F<utils/> subdirectory
-can be used to help mail in a bug report.
-
-Perl actually stands for Pathologically Eclectic Rubbish Lister, but
-don't tell anyone I said that.
-
-=head1 NOTES
-
-The Perl motto is "There's more than one way to do it." Divining
-how many more is left as an exercise to the reader.
-
-The three principal virtues of a programmer are Laziness,
-Impatience, and Hubris. See the Camel Book for why.
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perl5004delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5004delta.pod
deleted file mode 100644
index fc5ae62bb85..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl5004delta.pod
+++ /dev/null
@@ -1,1612 +0,0 @@
-=head1 NAME
-
-perl5004delta - what's new for perl5.004
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.003 release (as
-documented in I<Programming Perl>, second edition--the Camel Book) and
-this one.
-
-=head1 Supported Environments
-
-Perl5.004 builds out of the box on Unix, Plan 9, LynxOS, VMS, OS/2,
-QNX, AmigaOS, and Windows NT. Perl runs on Windows 95 as well, but it
-cannot be built there, for lack of a reasonable command interpreter.
-
-=head1 Core Changes
-
-Most importantly, many bugs were fixed, including several security
-problems. See the F<Changes> file in the distribution for details.
-
-=head2 List assignment to %ENV works
-
-C<%ENV = ()> and C<%ENV = @list> now work as expected (except on VMS
-where it generates a fatal error).
-
-=head2 Change to "Can't locate Foo.pm in @INC" error
-
-The error "Can't locate Foo.pm in @INC" now lists the contents of @INC
-for easier debugging.
-
-=head2 Compilation option: Binary compatibility with 5.003
-
-There is a new Configure question that asks if you want to maintain
-binary compatibility with Perl 5.003. If you choose binary
-compatibility, you do not have to recompile your extensions, but you
-might have symbol conflicts if you embed Perl in another application,
-just as in the 5.003 release. By default, binary compatibility
-is preserved at the expense of symbol table pollution.
-
-=head2 $PERL5OPT environment variable
-
-You may now put Perl options in the $PERL5OPT environment variable.
-Unless Perl is running with taint checks, it will interpret this
-variable as if its contents had appeared on a "#!perl" line at the
-beginning of your script, except that hyphens are optional. PERL5OPT
-may only be used to set the following switches: B<-[DIMUdmw]>.
-
-=head2 Limitations on B<-M>, B<-m>, and B<-T> options
-
-The C<-M> and C<-m> options are no longer allowed on the C<#!> line of
-a script. If a script needs a module, it should invoke it with the
-C<use> pragma.
-
-The B<-T> option is also forbidden on the C<#!> line of a script,
-unless it was present on the Perl command line. Due to the way C<#!>
-works, this usually means that B<-T> must be in the first argument.
-Thus:
-
- #!/usr/bin/perl -T -w
-
-will probably work for an executable script invoked as C<scriptname>,
-while:
-
- #!/usr/bin/perl -w -T
-
-will probably fail under the same conditions. (Non-Unix systems will
-probably not follow this rule.) But C<perl scriptname> is guaranteed
-to fail, since then there is no chance of B<-T> being found on the
-command line before it is found on the C<#!> line.
-
-=head2 More precise warnings
-
-If you removed the B<-w> option from your Perl 5.003 scripts because it
-made Perl too verbose, we recommend that you try putting it back when
-you upgrade to Perl 5.004. Each new perl version tends to remove some
-undesirable warnings, while adding new warnings that may catch bugs in
-your scripts.
-
-=head2 Deprecated: Inherited C<AUTOLOAD> for non-methods
-
-Before Perl 5.004, C<AUTOLOAD> functions were looked up as methods
-(using the C<@ISA> hierarchy), even when the function to be autoloaded
-was called as a plain function (e.g. C<Foo::bar()>), not a method
-(e.g. C<< Foo->bar() >> or C<< $obj->bar() >>).
-
-Perl 5.005 will use method lookup only for methods' C<AUTOLOAD>s.
-However, there is a significant base of existing code that may be using
-the old behavior. So, as an interim step, Perl 5.004 issues an optional
-warning when a non-method uses an inherited C<AUTOLOAD>.
-
-The simple rule is: Inheritance will not work when autoloading
-non-methods. The simple fix for old code is: In any module that used to
-depend on inheriting C<AUTOLOAD> for non-methods from a base class named
-C<BaseClass>, execute C<*AUTOLOAD = \&BaseClass::AUTOLOAD> during startup.
-
-=head2 Previously deprecated %OVERLOAD is no longer usable
-
-Using %OVERLOAD to define overloading was deprecated in 5.003.
-Overloading is now defined using the overload pragma. %OVERLOAD is
-still used internally but should not be used by Perl scripts. See
-L<overload> for more details.
-
-=head2 Subroutine arguments created only when they're modified
-
-In Perl 5.004, nonexistent array and hash elements used as subroutine
-parameters are brought into existence only if they are actually
-assigned to (via C<@_>).
-
-Earlier versions of Perl vary in their handling of such arguments.
-Perl versions 5.002 and 5.003 always brought them into existence.
-Perl versions 5.000 and 5.001 brought them into existence only if
-they were not the first argument (which was almost certainly a bug).
-Earlier versions of Perl never brought them into existence.
-
-For example, given this code:
-
- undef @a; undef %a;
- sub show { print $_[0] };
- sub change { $_[0]++ };
- show($a[2]);
- change($a{b});
-
-After this code executes in Perl 5.004, $a{b} exists but $a[2] does
-not. In Perl 5.002 and 5.003, both $a{b} and $a[2] would have existed
-(but $a[2]'s value would have been undefined).
-
-=head2 Group vector changeable with C<$)>
-
-The C<$)> special variable has always (well, in Perl 5, at least)
-reflected not only the current effective group, but also the group list
-as returned by the C<getgroups()> C function (if there is one).
-However, until this release, there has not been a way to call the
-C<setgroups()> C function from Perl.
-
-In Perl 5.004, assigning to C<$)> is exactly symmetrical with examining
-it: The first number in its string value is used as the effective gid;
-if there are any numbers after the first one, they are passed to the
-C<setgroups()> C function (if there is one).
-
-=head2 Fixed parsing of $$<digit>, &$<digit>, etc.
-
-Perl versions before 5.004 misinterpreted any type marker followed by
-"$" and a digit. For example, "$$0" was incorrectly taken to mean
-"${$}0" instead of "${$0}". This bug is (mostly) fixed in Perl 5.004.
-
-However, the developers of Perl 5.004 could not fix this bug completely,
-because at least two widely-used modules depend on the old meaning of
-"$$0" in a string. So Perl 5.004 still interprets "$$<digit>" in the
-old (broken) way inside strings; but it generates this message as a
-warning. And in Perl 5.005, this special treatment will cease.
-
-=head2 Fixed localization of $<digit>, $&, etc.
-
-Perl versions before 5.004 did not always properly localize the
-regex-related special variables. Perl 5.004 does localize them, as
-the documentation has always said it should. This may result in $1,
-$2, etc. no longer being set where existing programs use them.
-
-=head2 No resetting of $. on implicit close
-
-The documentation for Perl 5.0 has always stated that C<$.> is I<not>
-reset when an already-open file handle is reopened with no intervening
-call to C<close>. Due to a bug, perl versions 5.000 through 5.003
-I<did> reset C<$.> under that circumstance; Perl 5.004 does not.
-
-=head2 C<wantarray> may return undef
-
-The C<wantarray> operator returns true if a subroutine is expected to
-return a list, and false otherwise. In Perl 5.004, C<wantarray> can
-also return the undefined value if a subroutine's return value will
-not be used at all, which allows subroutines to avoid a time-consuming
-calculation of a return value if it isn't going to be used.
-
-=head2 C<eval EXPR> determines value of EXPR in scalar context
-
-Perl (version 5) used to determine the value of EXPR inconsistently,
-sometimes incorrectly using the surrounding context for the determination.
-Now, the value of EXPR (before being parsed by eval) is always determined in
-a scalar context. Once parsed, it is executed as before, by providing
-the context that the scope surrounding the eval provided. This change
-makes the behavior Perl4 compatible, besides fixing bugs resulting from
-the inconsistent behavior. This program:
-
- @a = qw(time now is time);
- print eval @a;
- print '|', scalar eval @a;
-
-used to print something like "timenowis881399109|4", but now (and in perl4)
-prints "4|4".
-
-=head2 Changes to tainting checks
-
-A bug in previous versions may have failed to detect some insecure
-conditions when taint checks are turned on. (Taint checks are used
-in setuid or setgid scripts, or when explicitly turned on with the
-C<-T> invocation option.) Although it's unlikely, this may cause a
-previously-working script to now fail, which should be construed
-as a blessing since that indicates a potentially-serious security
-hole was just plugged.
-
-The new restrictions when tainting include:
-
-=over 4
-
-=item No glob() or <*>
-
-These operators may spawn the C shell (csh), which cannot be made
-safe. This restriction will be lifted in a future version of Perl
-when globbing is implemented without the use of an external program.
-
-=item No spawning if tainted $CDPATH, $ENV, $BASH_ENV
-
-These environment variables may alter the behavior of spawned programs
-(especially shells) in ways that subvert security. So now they are
-treated as dangerous, in the manner of $IFS and $PATH.
-
-=item No spawning if tainted $TERM doesn't look like a terminal name
-
-Some termcap libraries do unsafe things with $TERM. However, it would be
-unnecessarily harsh to treat all $TERM values as unsafe, since only shell
-metacharacters can cause trouble in $TERM. So a tainted $TERM is
-considered to be safe if it contains only alphanumerics, underscores,
-dashes, and colons, and unsafe if it contains other characters (including
-whitespace).
-
-=back
-
-=head2 New Opcode module and revised Safe module
-
-A new Opcode module supports the creation, manipulation and
-application of opcode masks. The revised Safe module has a new API
-and is implemented using the new Opcode module. Please read the new
-Opcode and Safe documentation.
-
-=head2 Embedding improvements
-
-In older versions of Perl it was not possible to create more than one
-Perl interpreter instance inside a single process without leaking like a
-sieve and/or crashing. The bugs that caused this behavior have all been
-fixed. However, you still must take care when embedding Perl in a C
-program. See the updated perlembed manpage for tips on how to manage
-your interpreters.
-
-=head2 Internal change: FileHandle class based on IO::* classes
-
-File handles are now stored internally as type IO::Handle. The
-FileHandle module is still supported for backwards compatibility, but
-it is now merely a front end to the IO::* modules, specifically
-IO::Handle, IO::Seekable, and IO::File. We suggest, but do not
-require, that you use the IO::* modules in new code.
-
-In harmony with this change, C<*GLOB{FILEHANDLE}> is now just a
-backward-compatible synonym for C<*GLOB{IO}>.
-
-=head2 Internal change: PerlIO abstraction interface
-
-It is now possible to build Perl with AT&T's sfio IO package
-instead of stdio. See L<perlapio> for more details, and
-the F<INSTALL> file for how to use it.
-
-=head2 New and changed syntax
-
-=over 4
-
-=item $coderef->(PARAMS)
-
-A subroutine reference may now be suffixed with an arrow and a
-(possibly empty) parameter list. This syntax denotes a call of the
-referenced subroutine, with the given parameters (if any).
-
-This new syntax follows the pattern of S<C<< $hashref->{FOO} >>> and
-S<C<< $aryref->[$foo] >>>: You may now write S<C<&$subref($foo)>> as
-S<C<< $subref->($foo) >>>. All these arrow terms may be chained;
-thus, S<C<< &{$table->{FOO}}($bar) >>> may now be written
-S<C<< $table->{FOO}->($bar) >>>.
-
-=back
-
-=head2 New and changed builtin constants
-
-=over 4
-
-=item __PACKAGE__
-
-The current package name at compile time, or the undefined value if
-there is no current package (due to a C<package;> directive). Like
-C<__FILE__> and C<__LINE__>, C<__PACKAGE__> does I<not> interpolate
-into strings.
-
-=back
-
-=head2 New and changed builtin variables
-
-=over 4
-
-=item $^E
-
-Extended error message on some platforms. (Also known as
-$EXTENDED_OS_ERROR if you C<use English>).
-
-=item $^H
-
-The current set of syntax checks enabled by C<use strict>. See the
-documentation of C<strict> for more details. Not actually new, but
-newly documented.
-Because it is intended for internal use by Perl core components,
-there is no C<use English> long name for this variable.
-
-=item $^M
-
-By default, running out of memory it is not trappable. However, if
-compiled for this, Perl may use the contents of C<$^M> as an emergency
-pool after die()ing with this message. Suppose that your Perl were
-compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc. Then
-
- $^M = 'a' x (1<<16);
-
-would allocate a 64K buffer for use when in emergency.
-See the F<INSTALL> file for information on how to enable this option.
-As a disincentive to casual use of this advanced feature,
-there is no C<use English> long name for this variable.
-
-=back
-
-=head2 New and changed builtin functions
-
-=over 4
-
-=item delete on slices
-
-This now works. (e.g. C<delete @ENV{'PATH', 'MANPATH'}>)
-
-=item flock
-
-is now supported on more platforms, prefers fcntl to lockf when
-emulating, and always flushes before (un)locking.
-
-=item printf and sprintf
-
-Perl now implements these functions itself; it doesn't use the C
-library function sprintf() any more, except for floating-point
-numbers, and even then only known flags are allowed. As a result, it
-is now possible to know which conversions and flags will work, and
-what they will do.
-
-The new conversions in Perl's sprintf() are:
-
- %i a synonym for %d
- %p a pointer (the address of the Perl value, in hexadecimal)
- %n special: *stores* the number of characters output so far
- into the next variable in the parameter list
-
-The new flags that go between the C<%> and the conversion are:
-
- # prefix octal with "0", hex with "0x"
- h interpret integer as C type "short" or "unsigned short"
- V interpret integer as Perl's standard integer type
-
-Also, where a number would appear in the flags, an asterisk ("*") may
-be used instead, in which case Perl uses the next item in the
-parameter list as the given number (that is, as the field width or
-precision). If a field width obtained through "*" is negative, it has
-the same effect as the '-' flag: left-justification.
-
-See L<perlfunc/sprintf> for a complete list of conversion and flags.
-
-=item keys as an lvalue
-
-As an lvalue, C<keys> allows you to increase the number of hash buckets
-allocated for the given hash. This can gain you a measure of efficiency if
-you know the hash is going to get big. (This is similar to pre-extending
-an array by assigning a larger number to $#array.) If you say
-
- keys %hash = 200;
-
-then C<%hash> will have at least 200 buckets allocated for it. These
-buckets will be retained even if you do C<%hash = ()>; use C<undef
-%hash> if you want to free the storage while C<%hash> is still in scope.
-You can't shrink the number of buckets allocated for the hash using
-C<keys> in this way (but you needn't worry about doing this by accident,
-as trying has no effect).
-
-=item my() in Control Structures
-
-You can now use my() (with or without the parentheses) in the control
-expressions of control structures such as:
-
- while (defined(my $line = <>)) {
- $line = lc $line;
- } continue {
- print $line;
- }
-
- if ((my $answer = <STDIN>) =~ /^y(es)?$/i) {
- user_agrees();
- } elsif ($answer =~ /^n(o)?$/i) {
- user_disagrees();
- } else {
- chomp $answer;
- die "`$answer' is neither `yes' nor `no'";
- }
-
-Also, you can declare a foreach loop control variable as lexical by
-preceding it with the word "my". For example, in:
-
- foreach my $i (1, 2, 3) {
- some_function();
- }
-
-$i is a lexical variable, and the scope of $i extends to the end of
-the loop, but not beyond it.
-
-Note that you still cannot use my() on global punctuation variables
-such as $_ and the like.
-
-=item pack() and unpack()
-
-A new format 'w' represents a BER compressed integer (as defined in
-ASN.1). Its format is a sequence of one or more bytes, each of which
-provides seven bits of the total value, with the most significant
-first. Bit eight of each byte is set, except for the last byte, in
-which bit eight is clear.
-
-If 'p' or 'P' are given undef as values, they now generate a NULL
-pointer.
-
-Both pack() and unpack() now fail when their templates contain invalid
-types. (Invalid types used to be ignored.)
-
-=item sysseek()
-
-The new sysseek() operator is a variant of seek() that sets and gets the
-file's system read/write position, using the lseek(2) system call. It is
-the only reliable way to seek before using sysread() or syswrite(). Its
-return value is the new position, or the undefined value on failure.
-
-=item use VERSION
-
-If the first argument to C<use> is a number, it is treated as a version
-number instead of a module name. If the version of the Perl interpreter
-is less than VERSION, then an error message is printed and Perl exits
-immediately. Because C<use> occurs at compile time, this check happens
-immediately during the compilation process, unlike C<require VERSION>,
-which waits until runtime for the check. This is often useful if you
-need to check the current Perl version before C<use>ing library modules
-which have changed in incompatible ways from older versions of Perl.
-(We try not to do this more than we have to.)
-
-=item use Module VERSION LIST
-
-If the VERSION argument is present between Module and LIST, then the
-C<use> will call the VERSION method in class Module with the given
-version as an argument. The default VERSION method, inherited from
-the UNIVERSAL class, croaks if the given version is larger than the
-value of the variable $Module::VERSION. (Note that there is not a
-comma after VERSION!)
-
-This version-checking mechanism is similar to the one currently used
-in the Exporter module, but it is faster and can be used with modules
-that don't use the Exporter. It is the recommended method for new
-code.
-
-=item prototype(FUNCTION)
-
-Returns the prototype of a function as a string (or C<undef> if the
-function has no prototype). FUNCTION is a reference to or the name of the
-function whose prototype you want to retrieve.
-(Not actually new; just never documented before.)
-
-=item srand
-
-The default seed for C<srand>, which used to be C<time>, has been changed.
-Now it's a heady mix of difficult-to-predict system-dependent values,
-which should be sufficient for most everyday purposes.
-
-Previous to version 5.004, calling C<rand> without first calling C<srand>
-would yield the same sequence of random numbers on most or all machines.
-Now, when perl sees that you're calling C<rand> and haven't yet called
-C<srand>, it calls C<srand> with the default seed. You should still call
-C<srand> manually if your code might ever be run on a pre-5.004 system,
-of course, or if you want a seed other than the default.
-
-=item $_ as Default
-
-Functions documented in the Camel to default to $_ now in
-fact do, and all those that do are so documented in L<perlfunc>.
-
-=item C<m//gc> does not reset search position on failure
-
-The C<m//g> match iteration construct has always reset its target
-string's search position (which is visible through the C<pos> operator)
-when a match fails; as a result, the next C<m//g> match after a failure
-starts again at the beginning of the string. With Perl 5.004, this
-reset may be disabled by adding the "c" (for "continue") modifier,
-i.e. C<m//gc>. This feature, in conjunction with the C<\G> zero-width
-assertion, makes it possible to chain matches together. See L<perlop>
-and L<perlre>.
-
-=item C<m//x> ignores whitespace before ?*+{}
-
-The C<m//x> construct has always been intended to ignore all unescaped
-whitespace. However, before Perl 5.004, whitespace had the effect of
-escaping repeat modifiers like "*" or "?"; for example, C</a *b/x> was
-(mis)interpreted as C</a\*b/x>. This bug has been fixed in 5.004.
-
-=item nested C<sub{}> closures work now
-
-Prior to the 5.004 release, nested anonymous functions didn't work
-right. They do now.
-
-=item formats work right on changing lexicals
-
-Just like anonymous functions that contain lexical variables
-that change (like a lexical index variable for a C<foreach> loop),
-formats now work properly. For example, this silently failed
-before (printed only zeros), but is fine now:
-
- my $i;
- foreach $i ( 1 .. 10 ) {
- write;
- }
- format =
- my i is @#
- $i
- .
-
-However, it still fails (without a warning) if the foreach is within a
-subroutine:
-
- my $i;
- sub foo {
- foreach $i ( 1 .. 10 ) {
- write;
- }
- }
- foo;
- format =
- my i is @#
- $i
- .
-
-=back
-
-=head2 New builtin methods
-
-The C<UNIVERSAL> package automatically contains the following methods that
-are inherited by all other classes:
-
-=over 4
-
-=item isa(CLASS)
-
-C<isa> returns I<true> if its object is blessed into a subclass of C<CLASS>
-
-C<isa> is also exportable and can be called as a sub with two arguments. This
-allows the ability to check what a reference points to. Example:
-
- use UNIVERSAL qw(isa);
-
- if(isa($ref, 'ARRAY')) {
- ...
- }
-
-=item can(METHOD)
-
-C<can> checks to see if its object has a method called C<METHOD>,
-if it does then a reference to the sub is returned; if it does not then
-I<undef> is returned.
-
-=item VERSION( [NEED] )
-
-C<VERSION> returns the version number of the class (package). If the
-NEED argument is given then it will check that the current version (as
-defined by the $VERSION variable in the given package) not less than
-NEED; it will die if this is not the case. This method is normally
-called as a class method. This method is called automatically by the
-C<VERSION> form of C<use>.
-
- use A 1.2 qw(some imported subs);
- # implies:
- A->VERSION(1.2);
-
-=back
-
-B<NOTE:> C<can> directly uses Perl's internal code for method lookup, and
-C<isa> uses a very similar method and caching strategy. This may cause
-strange effects if the Perl code dynamically changes @ISA in any package.
-
-You may add other methods to the UNIVERSAL class via Perl or XS code.
-You do not need to C<use UNIVERSAL> in order to make these methods
-available to your program. This is necessary only if you wish to
-have C<isa> available as a plain subroutine in the current package.
-
-=head2 TIEHANDLE now supported
-
-See L<perltie> for other kinds of tie()s.
-
-=over 4
-
-=item TIEHANDLE classname, LIST
-
-This is the constructor for the class. That means it is expected to
-return an object of some sort. The reference can be used to
-hold some internal information.
-
- sub TIEHANDLE {
- print "<shout>\n";
- my $i;
- return bless \$i, shift;
- }
-
-=item PRINT this, LIST
-
-This method will be triggered every time the tied handle is printed to.
-Beyond its self reference it also expects the list that was passed to
-the print function.
-
- sub PRINT {
- $r = shift;
- $$r++;
- return print join( $, => map {uc} @_), $\;
- }
-
-=item PRINTF this, LIST
-
-This method will be triggered every time the tied handle is printed to
-with the C<printf()> function.
-Beyond its self reference it also expects the format and list that was
-passed to the printf function.
-
- sub PRINTF {
- shift;
- my $fmt = shift;
- print sprintf($fmt, @_)."\n";
- }
-
-=item READ this LIST
-
-This method will be called when the handle is read from via the C<read>
-or C<sysread> functions.
-
- sub READ {
- $r = shift;
- my($buf,$len,$offset) = @_;
- print "READ called, \$buf=$buf, \$len=$len, \$offset=$offset";
- }
-
-=item READLINE this
-
-This method will be called when the handle is read from. The method
-should return undef when there is no more data.
-
- sub READLINE {
- $r = shift;
- return "PRINT called $$r times\n"
- }
-
-=item GETC this
-
-This method will be called when the C<getc> function is called.
-
- sub GETC { print "Don't GETC, Get Perl"; return "a"; }
-
-=item DESTROY this
-
-As with the other types of ties, this method will be called when the
-tied handle is about to be destroyed. This is useful for debugging and
-possibly for cleaning up.
-
- sub DESTROY {
- print "</shout>\n";
- }
-
-=back
-
-=head2 Malloc enhancements
-
-If perl is compiled with the malloc included with the perl distribution
-(that is, if C<perl -V:d_mymalloc> is 'define') then you can print
-memory statistics at runtime by running Perl thusly:
-
- env PERL_DEBUG_MSTATS=2 perl your_script_here
-
-The value of 2 means to print statistics after compilation and on
-exit; with a value of 1, the statistics are printed only on exit.
-(If you want the statistics at an arbitrary time, you'll need to
-install the optional module Devel::Peek.)
-
-Three new compilation flags are recognized by malloc.c. (They have no
-effect if perl is compiled with system malloc().)
-
-=over 4
-
-=item -DPERL_EMERGENCY_SBRK
-
-If this macro is defined, running out of memory need not be a fatal
-error: a memory pool can allocated by assigning to the special
-variable C<$^M>. See L<"$^M">.
-
-=item -DPACK_MALLOC
-
-Perl memory allocation is by bucket with sizes close to powers of two.
-Because of these malloc overhead may be big, especially for data of
-size exactly a power of two. If C<PACK_MALLOC> is defined, perl uses
-a slightly different algorithm for small allocations (up to 64 bytes
-long), which makes it possible to have overhead down to 1 byte for
-allocations which are powers of two (and appear quite often).
-
-Expected memory savings (with 8-byte alignment in C<alignbytes>) is
-about 20% for typical Perl usage. Expected slowdown due to additional
-malloc overhead is in fractions of a percent (hard to measure, because
-of the effect of saved memory on speed).
-
-=item -DTWO_POT_OPTIMIZE
-
-Similarly to C<PACK_MALLOC>, this macro improves allocations of data
-with size close to a power of two; but this works for big allocations
-(starting with 16K by default). Such allocations are typical for big
-hashes and special-purpose scripts, especially image processing.
-
-On recent systems, the fact that perl requires 2M from system for 1M
-allocation will not affect speed of execution, since the tail of such
-a chunk is not going to be touched (and thus will not require real
-memory). However, it may result in a premature out-of-memory error.
-So if you will be manipulating very large blocks with sizes close to
-powers of two, it would be wise to define this macro.
-
-Expected saving of memory is 0-100% (100% in applications which
-require most memory in such 2**n chunks); expected slowdown is
-negligible.
-
-=back
-
-=head2 Miscellaneous efficiency enhancements
-
-Functions that have an empty prototype and that do nothing but return
-a fixed value are now inlined (e.g. C<sub PI () { 3.14159 }>).
-
-Each unique hash key is only allocated once, no matter how many hashes
-have an entry with that key. So even if you have 100 copies of the
-same hash, the hash keys never have to be reallocated.
-
-=head1 Support for More Operating Systems
-
-Support for the following operating systems is new in Perl 5.004.
-
-=head2 Win32
-
-Perl 5.004 now includes support for building a "native" perl under
-Windows NT, using the Microsoft Visual C++ compiler (versions 2.0
-and above) or the Borland C++ compiler (versions 5.02 and above).
-The resulting perl can be used under Windows 95 (if it
-is installed in the same directory locations as it got installed
-in Windows NT). This port includes support for perl extension
-building tools like L<ExtUtils::MakeMaker> and L<h2xs>, so that many extensions
-available on the Comprehensive Perl Archive Network (CPAN) can now be
-readily built under Windows NT. See http://www.perl.com/ for more
-information on CPAN and F<README.win32> in the perl distribution for more
-details on how to get started with building this port.
-
-There is also support for building perl under the Cygwin32 environment.
-Cygwin32 is a set of GNU tools that make it possible to compile and run
-many Unix programs under Windows NT by providing a mostly Unix-like
-interface for compilation and execution. See F<README.cygwin32> in the
-perl distribution for more details on this port and how to obtain the
-Cygwin32 toolkit.
-
-=head2 Plan 9
-
-See F<README.plan9> in the perl distribution.
-
-=head2 QNX
-
-See F<README.qnx> in the perl distribution.
-
-=head2 AmigaOS
-
-See F<README.amigaos> in the perl distribution.
-
-=head1 Pragmata
-
-Six new pragmatic modules exist:
-
-=over 4
-
-=item use autouse MODULE => qw(sub1 sub2 sub3)
-
-Defers C<require MODULE> until someone calls one of the specified
-subroutines (which must be exported by MODULE). This pragma should be
-used with caution, and only when necessary.
-
-=item use blib
-
-=item use blib 'dir'
-
-Looks for MakeMaker-like I<'blib'> directory structure starting in
-I<dir> (or current directory) and working back up to five levels of
-parent directories.
-
-Intended for use on command line with B<-M> option as a way of testing
-arbitrary scripts against an uninstalled version of a package.
-
-=item use constant NAME => VALUE
-
-Provides a convenient interface for creating compile-time constants,
-See L<perlsub/"Constant Functions">.
-
-=item use locale
-
-Tells the compiler to enable (or disable) the use of POSIX locales for
-builtin operations.
-
-When C<use locale> is in effect, the current LC_CTYPE locale is used
-for regular expressions and case mapping; LC_COLLATE for string
-ordering; and LC_NUMERIC for numeric formatting in printf and sprintf
-(but B<not> in print). LC_NUMERIC is always used in write, since
-lexical scoping of formats is problematic at best.
-
-Each C<use locale> or C<no locale> affects statements to the end of
-the enclosing BLOCK or, if not inside a BLOCK, to the end of the
-current file. Locales can be switched and queried with
-POSIX::setlocale().
-
-See L<perllocale> for more information.
-
-=item use ops
-
-Disable unsafe opcodes, or any named opcodes, when compiling Perl code.
-
-=item use vmsish
-
-Enable VMS-specific language features. Currently, there are three
-VMS-specific features available: 'status', which makes C<$?> and
-C<system> return genuine VMS status values instead of emulating POSIX;
-'exit', which makes C<exit> take a genuine VMS status value instead of
-assuming that C<exit 1> is an error; and 'time', which makes all times
-relative to the local time zone, in the VMS tradition.
-
-=back
-
-=head1 Modules
-
-=head2 Required Updates
-
-Though Perl 5.004 is compatible with almost all modules that work
-with Perl 5.003, there are a few exceptions:
-
- Module Required Version for Perl 5.004
- ------ -------------------------------
- Filter Filter-1.12
- LWP libwww-perl-5.08
- Tk Tk400.202 (-w makes noise)
-
-Also, the majordomo mailing list program, version 1.94.1, doesn't work
-with Perl 5.004 (nor with perl 4), because it executes an invalid
-regular expression. This bug is fixed in majordomo version 1.94.2.
-
-=head2 Installation directories
-
-The I<installperl> script now places the Perl source files for
-extensions in the architecture-specific library directory, which is
-where the shared libraries for extensions have always been. This
-change is intended to allow administrators to keep the Perl 5.004
-library directory unchanged from a previous version, without running
-the risk of binary incompatibility between extensions' Perl source and
-shared libraries.
-
-=head2 Module information summary
-
-Brand new modules, arranged by topic rather than strictly
-alphabetically:
-
- CGI.pm Web server interface ("Common Gateway Interface")
- CGI/Apache.pm Support for Apache's Perl module
- CGI/Carp.pm Log server errors with helpful context
- CGI/Fast.pm Support for FastCGI (persistent server process)
- CGI/Push.pm Support for server push
- CGI/Switch.pm Simple interface for multiple server types
-
- CPAN Interface to Comprehensive Perl Archive Network
- CPAN::FirstTime Utility for creating CPAN configuration file
- CPAN::Nox Runs CPAN while avoiding compiled extensions
-
- IO.pm Top-level interface to IO::* classes
- IO/File.pm IO::File extension Perl module
- IO/Handle.pm IO::Handle extension Perl module
- IO/Pipe.pm IO::Pipe extension Perl module
- IO/Seekable.pm IO::Seekable extension Perl module
- IO/Select.pm IO::Select extension Perl module
- IO/Socket.pm IO::Socket extension Perl module
-
- Opcode.pm Disable named opcodes when compiling Perl code
-
- ExtUtils/Embed.pm Utilities for embedding Perl in C programs
- ExtUtils/testlib.pm Fixes up @INC to use just-built extension
-
- FindBin.pm Find path of currently executing program
-
- Class/Struct.pm Declare struct-like datatypes as Perl classes
- File/stat.pm By-name interface to Perl's builtin stat
- Net/hostent.pm By-name interface to Perl's builtin gethost*
- Net/netent.pm By-name interface to Perl's builtin getnet*
- Net/protoent.pm By-name interface to Perl's builtin getproto*
- Net/servent.pm By-name interface to Perl's builtin getserv*
- Time/gmtime.pm By-name interface to Perl's builtin gmtime
- Time/localtime.pm By-name interface to Perl's builtin localtime
- Time/tm.pm Internal object for Time::{gm,local}time
- User/grent.pm By-name interface to Perl's builtin getgr*
- User/pwent.pm By-name interface to Perl's builtin getpw*
-
- Tie/RefHash.pm Base class for tied hashes with references as keys
-
- UNIVERSAL.pm Base class for *ALL* classes
-
-=head2 Fcntl
-
-New constants in the existing Fcntl modules are now supported,
-provided that your operating system happens to support them:
-
- F_GETOWN F_SETOWN
- O_ASYNC O_DEFER O_DSYNC O_FSYNC O_SYNC
- O_EXLOCK O_SHLOCK
-
-These constants are intended for use with the Perl operators sysopen()
-and fcntl() and the basic database modules like SDBM_File. For the
-exact meaning of these and other Fcntl constants please refer to your
-operating system's documentation for fcntl() and open().
-
-In addition, the Fcntl module now provides these constants for use
-with the Perl operator flock():
-
- LOCK_SH LOCK_EX LOCK_NB LOCK_UN
-
-These constants are defined in all environments (because where there is
-no flock() system call, Perl emulates it). However, for historical
-reasons, these constants are not exported unless they are explicitly
-requested with the ":flock" tag (e.g. C<use Fcntl ':flock'>).
-
-=head2 IO
-
-The IO module provides a simple mechanism to load all the IO modules at one
-go. Currently this includes:
-
- IO::Handle
- IO::Seekable
- IO::File
- IO::Pipe
- IO::Socket
-
-For more information on any of these modules, please see its
-respective documentation.
-
-=head2 Math::Complex
-
-The Math::Complex module has been totally rewritten, and now supports
-more operations. These are overloaded:
-
- + - * / ** <=> neg ~ abs sqrt exp log sin cos atan2 "" (stringify)
-
-And these functions are now exported:
-
- pi i Re Im arg
- log10 logn ln cbrt root
- tan
- csc sec cot
- asin acos atan
- acsc asec acot
- sinh cosh tanh
- csch sech coth
- asinh acosh atanh
- acsch asech acoth
- cplx cplxe
-
-=head2 Math::Trig
-
-This new module provides a simpler interface to parts of Math::Complex for
-those who need trigonometric functions only for real numbers.
-
-=head2 DB_File
-
-There have been quite a few changes made to DB_File. Here are a few of
-the highlights:
-
-=over 4
-
-=item *
-
-Fixed a handful of bugs.
-
-=item *
-
-By public demand, added support for the standard hash function exists().
-
-=item *
-
-Made it compatible with Berkeley DB 1.86.
-
-=item *
-
-Made negative subscripts work with RECNO interface.
-
-=item *
-
-Changed the default flags from O_RDWR to O_CREAT|O_RDWR and the default
-mode from 0640 to 0666.
-
-=item *
-
-Made DB_File automatically import the open() constants (O_RDWR,
-O_CREAT etc.) from Fcntl, if available.
-
-=item *
-
-Updated documentation.
-
-=back
-
-Refer to the HISTORY section in DB_File.pm for a complete list of
-changes. Everything after DB_File 1.01 has been added since 5.003.
-
-=head2 Net::Ping
-
-Major rewrite - support added for both udp echo and real icmp pings.
-
-=head2 Object-oriented overrides for builtin operators
-
-Many of the Perl builtins returning lists now have
-object-oriented overrides. These are:
-
- File::stat
- Net::hostent
- Net::netent
- Net::protoent
- Net::servent
- Time::gmtime
- Time::localtime
- User::grent
- User::pwent
-
-For example, you can now say
-
- use File::stat;
- use User::pwent;
- $his = (stat($filename)->st_uid == pwent($whoever)->pw_uid);
-
-=head1 Utility Changes
-
-=head2 pod2html
-
-=over 4
-
-=item Sends converted HTML to standard output
-
-The I<pod2html> utility included with Perl 5.004 is entirely new.
-By default, it sends the converted HTML to its standard output,
-instead of writing it to a file like Perl 5.003's I<pod2html> did.
-Use the B<--outfile=FILENAME> option to write to a file.
-
-=back
-
-=head2 xsubpp
-
-=over 4
-
-=item C<void> XSUBs now default to returning nothing
-
-Due to a documentation/implementation bug in previous versions of
-Perl, XSUBs with a return type of C<void> have actually been
-returning one value. Usually that value was the GV for the XSUB,
-but sometimes it was some already freed or reused value, which would
-sometimes lead to program failure.
-
-In Perl 5.004, if an XSUB is declared as returning C<void>, it
-actually returns no value, i.e. an empty list (though there is a
-backward-compatibility exception; see below). If your XSUB really
-does return an SV, you should give it a return type of C<SV *>.
-
-For backward compatibility, I<xsubpp> tries to guess whether a
-C<void> XSUB is really C<void> or if it wants to return an C<SV *>.
-It does so by examining the text of the XSUB: if I<xsubpp> finds
-what looks like an assignment to C<ST(0)>, it assumes that the
-XSUB's return type is really C<SV *>.
-
-=back
-
-=head1 C Language API Changes
-
-=over 4
-
-=item C<gv_fetchmethod> and C<perl_call_sv>
-
-The C<gv_fetchmethod> function finds a method for an object, just like
-in Perl 5.003. The GV it returns may be a method cache entry.
-However, in Perl 5.004, method cache entries are not visible to users;
-therefore, they can no longer be passed directly to C<perl_call_sv>.
-Instead, you should use the C<GvCV> macro on the GV to extract its CV,
-and pass the CV to C<perl_call_sv>.
-
-The most likely symptom of passing the result of C<gv_fetchmethod> to
-C<perl_call_sv> is Perl's producing an "Undefined subroutine called"
-error on the I<second> call to a given method (since there is no cache
-on the first call).
-
-=item C<perl_eval_pv>
-
-A new function handy for eval'ing strings of Perl code inside C code.
-This function returns the value from the eval statement, which can
-be used instead of fetching globals from the symbol table. See
-L<perlguts>, L<perlembed> and L<perlcall> for details and examples.
-
-=item Extended API for manipulating hashes
-
-Internal handling of hash keys has changed. The old hashtable API is
-still fully supported, and will likely remain so. The additions to the
-API allow passing keys as C<SV*>s, so that C<tied> hashes can be given
-real scalars as keys rather than plain strings (nontied hashes still
-can only use strings as keys). New extensions must use the new hash
-access functions and macros if they wish to use C<SV*> keys. These
-additions also make it feasible to manipulate C<HE*>s (hash entries),
-which can be more efficient. See L<perlguts> for details.
-
-=back
-
-=head1 Documentation Changes
-
-Many of the base and library pods were updated. These
-new pods are included in section 1:
-
-=over 4
-
-=item L<perldelta>
-
-This document.
-
-=item L<perlfaq>
-
-Frequently asked questions.
-
-=item L<perllocale>
-
-Locale support (internationalization and localization).
-
-=item L<perltoot>
-
-Tutorial on Perl OO programming.
-
-=item L<perlapio>
-
-Perl internal IO abstraction interface.
-
-=item L<perlmodlib>
-
-Perl module library and recommended practice for module creation.
-Extracted from L<perlmod> (which is much smaller as a result).
-
-=item L<perldebug>
-
-Although not new, this has been massively updated.
-
-=item L<perlsec>
-
-Although not new, this has been massively updated.
-
-=back
-
-=head1 New Diagnostics
-
-Several new conditions will trigger warnings that were
-silent before. Some only affect certain platforms.
-The following new warnings and errors outline these.
-These messages are classified as follows (listed in
-increasing order of desperation):
-
- (W) A warning (optional).
- (D) A deprecation (optional).
- (S) A severe warning (mandatory).
- (F) A fatal error (trappable).
- (P) An internal error you should never see (trappable).
- (X) A very fatal error (nontrappable).
- (A) An alien error message (not generated by Perl).
-
-=over 4
-
-=item "my" variable %s masks earlier declaration in same scope
-
-(W) A lexical variable has been redeclared in the same scope, effectively
-eliminating all access to the previous instance. This is almost always
-a typographical error. Note that the earlier variable will still exist
-until the end of the scope or until all closure referents to it are
-destroyed.
-
-=item %s argument is not a HASH element or slice
-
-(F) The argument to delete() must be either a hash element, such as
-
- $foo{$bar}
- $ref->[12]->{"susie"}
-
-or a hash slice, such as
-
- @foo{$bar, $baz, $xyzzy}
- @{$ref->[12]}{"susie", "queue"}
-
-=item Allocation too large: %lx
-
-(X) You can't allocate more than 64K on an MS-DOS machine.
-
-=item Allocation too large
-
-(F) You can't allocate more than 2^31+"small amount" bytes.
-
-=item Applying %s to %s will act on scalar(%s)
-
-(W) The pattern match (//), substitution (s///), and transliteration (tr///)
-operators work on scalar values. If you apply one of them to an array
-or a hash, it will convert the array or hash to a scalar value (the
-length of an array or the population info of a hash) and then work on
-that scalar value. This is probably not what you meant to do. See
-L<perlfunc/grep> and L<perlfunc/map> for alternatives.
-
-=item Attempt to free nonexistent shared string
-
-(P) Perl maintains a reference counted internal table of strings to
-optimize the storage and access of hash keys and other strings. This
-indicates someone tried to decrement the reference count of a string
-that can no longer be found in the table.
-
-=item Attempt to use reference as lvalue in substr
-
-(W) You supplied a reference as the first argument to substr() used
-as an lvalue, which is pretty strange. Perhaps you forgot to
-dereference it first. See L<perlfunc/substr>.
-
-=item Bareword "%s" refers to nonexistent package
-
-(W) You used a qualified bareword of the form C<Foo::>, but
-the compiler saw no other uses of that namespace before that point.
-Perhaps you need to predeclare a package?
-
-=item Can't redefine active sort subroutine %s
-
-(F) Perl optimizes the internal handling of sort subroutines and keeps
-pointers into them. You tried to redefine one such sort subroutine when it
-was currently active, which is not allowed. If you really want to do
-this, you should write C<sort { &func } @x> instead of C<sort func @x>.
-
-=item Can't use bareword ("%s") as %s ref while "strict refs" in use
-
-(F) Only hard references are allowed by "strict refs". Symbolic references
-are disallowed. See L<perlref>.
-
-=item Cannot resolve method `%s' overloading `%s' in package `%s'
-
-(P) Internal error trying to resolve overloading specified by a method
-name (as opposed to a subroutine reference).
-
-=item Constant subroutine %s redefined
-
-(S) You redefined a subroutine which had previously been eligible for
-inlining. See L<perlsub/"Constant Functions"> for commentary and
-workarounds.
-
-=item Constant subroutine %s undefined
-
-(S) You undefined a subroutine which had previously been eligible for
-inlining. See L<perlsub/"Constant Functions"> for commentary and
-workarounds.
-
-=item Copy method did not return a reference
-
-(F) The method which overloads "=" is buggy. See L<overload/Copy Constructor>.
-
-=item Died
-
-(F) You passed die() an empty string (the equivalent of C<die "">) or
-you called it with no args and both C<$@> and C<$_> were empty.
-
-=item Exiting pseudo-block via %s
-
-(W) You are exiting a rather special block construct (like a sort block or
-subroutine) by unconventional means, such as a goto, or a loop control
-statement. See L<perlfunc/sort>.
-
-=item Identifier too long
-
-(F) Perl limits identifiers (names for variables, functions, etc.) to
-252 characters for simple names, somewhat more for compound names (like
-C<$A::B>). You've exceeded Perl's limits. Future versions of Perl are
-likely to eliminate these arbitrary limitations.
-
-=item Illegal character %s (carriage return)
-
-(F) A carriage return character was found in the input. This is an
-error, and not a warning, because carriage return characters can break
-multi-line strings, including here documents (e.g., C<print <<EOF;>).
-
-=item Illegal switch in PERL5OPT: %s
-
-(X) The PERL5OPT environment variable may only be used to set the
-following switches: B<-[DIMUdmw]>.
-
-=item Integer overflow in hex number
-
-(S) The literal hex number you have specified is too big for your
-architecture. On a 32-bit architecture the largest hex literal is
-0xFFFFFFFF.
-
-=item Integer overflow in octal number
-
-(S) The literal octal number you have specified is too big for your
-architecture. On a 32-bit architecture the largest octal literal is
-037777777777.
-
-=item internal error: glob failed
-
-(P) Something went wrong with the external program(s) used for C<glob>
-and C<< <*.c> >>. This may mean that your csh (C shell) is
-broken. If so, you should change all of the csh-related variables in
-config.sh: If you have tcsh, make the variables refer to it as if it
-were csh (e.g. C<full_csh='/usr/bin/tcsh'>); otherwise, make them all
-empty (except that C<d_csh> should be C<'undef'>) so that Perl will
-think csh is missing. In either case, after editing config.sh, run
-C<./Configure -S> and rebuild Perl.
-
-=item Invalid conversion in %s: "%s"
-
-(W) Perl does not understand the given format conversion.
-See L<perlfunc/sprintf>.
-
-=item Invalid type in pack: '%s'
-
-(F) The given character is not a valid pack type. See L<perlfunc/pack>.
-
-=item Invalid type in unpack: '%s'
-
-(F) The given character is not a valid unpack type. See L<perlfunc/unpack>.
-
-=item Name "%s::%s" used only once: possible typo
-
-(W) Typographical errors often show up as unique variable names.
-If you had a good reason for having a unique name, then just mention
-it again somehow to suppress the message (the C<use vars> pragma is
-provided for just this purpose).
-
-=item Null picture in formline
-
-(F) The first argument to formline must be a valid format picture
-specification. It was found to be empty, which probably means you
-supplied it an uninitialized value. See L<perlform>.
-
-=item Offset outside string
-
-(F) You tried to do a read/write/send/recv operation with an offset
-pointing outside the buffer. This is difficult to imagine.
-The sole exception to this is that C<sysread()>ing past the buffer
-will extend the buffer and zero pad the new area.
-
-=item Out of memory!
-
-(X|F) The malloc() function returned 0, indicating there was insufficient
-remaining memory (or virtual memory) to satisfy the request.
-
-The request was judged to be small, so the possibility to trap it
-depends on the way Perl was compiled. By default it is not trappable.
-However, if compiled for this, Perl may use the contents of C<$^M> as
-an emergency pool after die()ing with this message. In this case the
-error is trappable I<once>.
-
-=item Out of memory during request for %s
-
-(F) The malloc() function returned 0, indicating there was insufficient
-remaining memory (or virtual memory) to satisfy the request. However,
-the request was judged large enough (compile-time default is 64K), so
-a possibility to shut down by trapping this error is granted.
-
-=item panic: frexp
-
-(P) The library function frexp() failed, making printf("%f") impossible.
-
-=item Possible attempt to put comments in qw() list
-
-(W) qw() lists contain items separated by whitespace; as with literal
-strings, comment characters are not ignored, but are instead treated
-as literal data. (You may have used different delimiters than the
-parentheses shown here; braces are also frequently used.)
-
-You probably wrote something like this:
-
- @list = qw(
- a # a comment
- b # another comment
- );
-
-when you should have written this:
-
- @list = qw(
- a
- b
- );
-
-If you really want comments, build your list the
-old-fashioned way, with quotes and commas:
-
- @list = (
- 'a', # a comment
- 'b', # another comment
- );
-
-=item Possible attempt to separate words with commas
-
-(W) qw() lists contain items separated by whitespace; therefore commas
-aren't needed to separate the items. (You may have used different
-delimiters than the parentheses shown here; braces are also frequently
-used.)
-
-You probably wrote something like this:
-
- qw! a, b, c !;
-
-which puts literal commas into some of the list items. Write it without
-commas if you don't want them to appear in your data:
-
- qw! a b c !;
-
-=item Scalar value @%s{%s} better written as $%s{%s}
-
-(W) You've used a hash slice (indicated by @) to select a single element of
-a hash. Generally it's better to ask for a scalar value (indicated by $).
-The difference is that C<$foo{&bar}> always behaves like a scalar, both when
-assigning to it and when evaluating its argument, while C<@foo{&bar}> behaves
-like a list when you assign to it, and provides a list context to its
-subscript, which can do weird things if you're expecting only one subscript.
-
-=item Stub found while resolving method `%s' overloading `%s' in %s
-
-(P) Overloading resolution over @ISA tree may be broken by importing stubs.
-Stubs should never be implicitly created, but explicit calls to C<can>
-may break this.
-
-=item Too late for "B<-T>" option
-
-(X) The #! line (or local equivalent) in a Perl script contains the
-B<-T> option, but Perl was not invoked with B<-T> in its argument
-list. This is an error because, by the time Perl discovers a B<-T> in
-a script, it's too late to properly taint everything from the
-environment. So Perl gives up.
-
-=item untie attempted while %d inner references still exist
-
-(W) A copy of the object returned from C<tie> (or C<tied>) was still
-valid when C<untie> was called.
-
-=item Unrecognized character %s
-
-(F) The Perl parser has no idea what to do with the specified character
-in your Perl script (or eval). Perhaps you tried to run a compressed
-script, a binary program, or a directory as a Perl program.
-
-=item Unsupported function fork
-
-(F) Your version of executable does not support forking.
-
-Note that under some systems, like OS/2, there may be different flavors of
-Perl executables, some of which may support fork, some not. Try changing
-the name you call Perl by to C<perl_>, C<perl__>, and so on.
-
-=item Use of "$$<digit>" to mean "${$}<digit>" is deprecated
-
-(D) Perl versions before 5.004 misinterpreted any type marker followed
-by "$" and a digit. For example, "$$0" was incorrectly taken to mean
-"${$}0" instead of "${$0}". This bug is (mostly) fixed in Perl 5.004.
-
-However, the developers of Perl 5.004 could not fix this bug completely,
-because at least two widely-used modules depend on the old meaning of
-"$$0" in a string. So Perl 5.004 still interprets "$$<digit>" in the
-old (broken) way inside strings; but it generates this message as a
-warning. And in Perl 5.005, this special treatment will cease.
-
-=item Value of %s can be "0"; test with defined()
-
-(W) In a conditional expression, you used <HANDLE>, <*> (glob), C<each()>,
-or C<readdir()> as a boolean value. Each of these constructs can return a
-value of "0"; that would make the conditional expression false, which is
-probably not what you intended. When using these constructs in conditional
-expressions, test their values with the C<defined> operator.
-
-=item Variable "%s" may be unavailable
-
-(W) An inner (nested) I<anonymous> subroutine is inside a I<named>
-subroutine, and outside that is another subroutine; and the anonymous
-(innermost) subroutine is referencing a lexical variable defined in
-the outermost subroutine. For example:
-
- sub outermost { my $a; sub middle { sub { $a } } }
-
-If the anonymous subroutine is called or referenced (directly or
-indirectly) from the outermost subroutine, it will share the variable
-as you would expect. But if the anonymous subroutine is called or
-referenced when the outermost subroutine is not active, it will see
-the value of the shared variable as it was before and during the
-*first* call to the outermost subroutine, which is probably not what
-you want.
-
-In these circumstances, it is usually best to make the middle
-subroutine anonymous, using the C<sub {}> syntax. Perl has specific
-support for shared variables in nested anonymous subroutines; a named
-subroutine in between interferes with this feature.
-
-=item Variable "%s" will not stay shared
-
-(W) An inner (nested) I<named> subroutine is referencing a lexical
-variable defined in an outer subroutine.
-
-When the inner subroutine is called, it will probably see the value of
-the outer subroutine's variable as it was before and during the
-*first* call to the outer subroutine; in this case, after the first
-call to the outer subroutine is complete, the inner and outer
-subroutines will no longer share a common value for the variable. In
-other words, the variable will no longer be shared.
-
-Furthermore, if the outer subroutine is anonymous and references a
-lexical variable outside itself, then the outer and inner subroutines
-will I<never> share the given variable.
-
-This problem can usually be solved by making the inner subroutine
-anonymous, using the C<sub {}> syntax. When inner anonymous subs that
-reference variables in outer subroutines are called or referenced,
-they are automatically rebound to the current values of such
-variables.
-
-=item Warning: something's wrong
-
-(W) You passed warn() an empty string (the equivalent of C<warn "">) or
-you called it with no args and C<$_> was empty.
-
-=item Ill-formed logical name |%s| in prime_env_iter
-
-(W) A warning peculiar to VMS. A logical name was encountered when preparing
-to iterate over %ENV which violates the syntactic rules governing logical
-names. Since it cannot be translated normally, it is skipped, and will not
-appear in %ENV. This may be a benign occurrence, as some software packages
-might directly modify logical name tables and introduce nonstandard names,
-or it may indicate that a logical name table has been corrupted.
-
-=item Got an error from DosAllocMem
-
-(P) An error peculiar to OS/2. Most probably you're using an obsolete
-version of Perl, and this should not happen anyway.
-
-=item Malformed PERLLIB_PREFIX
-
-(F) An error peculiar to OS/2. PERLLIB_PREFIX should be of the form
-
- prefix1;prefix2
-
-or
-
- prefix1 prefix2
-
-with nonempty prefix1 and prefix2. If C<prefix1> is indeed a prefix
-of a builtin library search path, prefix2 is substituted. The error
-may appear if components are not found, or are too long. See
-"PERLLIB_PREFIX" in F<README.os2>.
-
-=item PERL_SH_DIR too long
-
-(F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the
-C<sh>-shell in. See "PERL_SH_DIR" in F<README.os2>.
-
-=item Process terminated by SIG%s
-
-(W) This is a standard message issued by OS/2 applications, while *nix
-applications die in silence. It is considered a feature of the OS/2
-port. One can easily disable this by appropriate sighandlers, see
-L<perlipc/"Signals">. See also "Process terminated by SIGTERM/SIGINT"
-in F<README.os2>.
-
-=back
-
-=head1 BUGS
-
-If you find what you think is a bug, you might check the headers of
-recently posted articles in the comp.lang.perl.misc newsgroup.
-There may also be information at http://www.perl.com/perl/ , the Perl
-Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Make sure you trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to <F<perlbug@perl.com>> to be
-analysed by the Perl porting team.
-
-=head1 SEE ALSO
-
-The F<Changes> file for exhaustive details on what changed.
-
-The F<INSTALL> file for how to build Perl. This file has been
-significantly updated for 5.004, so even veteran users should
-look through it.
-
-The F<README> file for general stuff.
-
-The F<Copying> file for copyright information.
-
-=head1 HISTORY
-
-Constructed by Tom Christiansen, grabbing material with permission
-from innumerable contributors, with kibitzing by more than a few Perl
-porters.
-
-Last update: Wed May 14 11:14:09 EDT 1997
diff --git a/Master/tlpkg/tlperl/lib/pods/perl5005delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5005delta.pod
deleted file mode 100644
index 62661254a21..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl5005delta.pod
+++ /dev/null
@@ -1,993 +0,0 @@
-=head1 NAME
-
-perl5005delta - what's new for perl5.005
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.004 release and this one.
-
-=head1 About the new versioning system
-
-Perl is now developed on two tracks: a maintenance track that makes
-small, safe updates to released production versions with emphasis on
-compatibility; and a development track that pursues more aggressive
-evolution. Maintenance releases (which should be considered production
-quality) have subversion numbers that run from C<1> to C<49>, and
-development releases (which should be considered "alpha" quality) run
-from C<50> to C<99>.
-
-Perl 5.005 is the combined product of the new dual-track development
-scheme.
-
-=head1 Incompatible Changes
-
-=head2 WARNING: This version is not binary compatible with Perl 5.004.
-
-Starting with Perl 5.004_50 there were many deep and far-reaching changes
-to the language internals. If you have dynamically loaded extensions
-that you built under perl 5.003 or 5.004, you can continue to use them
-with 5.004, but you will need to rebuild and reinstall those extensions
-to use them 5.005. See F<INSTALL> for detailed instructions on how to
-upgrade.
-
-=head2 Default installation structure has changed
-
-The new Configure defaults are designed to allow a smooth upgrade from
-5.004 to 5.005, but you should read F<INSTALL> for a detailed
-discussion of the changes in order to adapt them to your system.
-
-=head2 Perl Source Compatibility
-
-When none of the experimental features are enabled, there should be
-very few user-visible Perl source compatibility issues.
-
-If threads are enabled, then some caveats apply. C<@_> and C<$_> become
-lexical variables. The effect of this should be largely transparent to
-the user, but there are some boundary conditions under which user will
-need to be aware of the issues. For example, C<local(@_)> results in
-a "Can't localize lexical variable @_ ..." message. This may be enabled
-in a future version.
-
-Some new keywords have been introduced. These are generally expected to
-have very little impact on compatibility. See L<New C<INIT> keyword>,
-L<New C<lock> keyword>, and L<New C<qrE<sol>E<sol>> operator>.
-
-Certain barewords are now reserved. Use of these will provoke a warning
-if you have asked for them with the C<-w> switch.
-See L<C<our> is now a reserved word>.
-
-=head2 C Source Compatibility
-
-There have been a large number of changes in the internals to support
-the new features in this release.
-
-=over 4
-
-=item *
-
-Core sources now require ANSI C compiler
-
-An ANSI C compiler is now B<required> to build perl. See F<INSTALL>.
-
-=item *
-
-All Perl global variables must now be referenced with an explicit prefix
-
-All Perl global variables that are visible for use by extensions now
-have a C<PL_> prefix. New extensions should C<not> refer to perl globals
-by their unqualified names. To preserve sanity, we provide limited
-backward compatibility for globals that are being widely used like
-C<sv_undef> and C<na> (which should now be written as C<PL_sv_undef>,
-C<PL_na> etc.)
-
-If you find that your XS extension does not compile anymore because a
-perl global is not visible, try adding a C<PL_> prefix to the global
-and rebuild.
-
-It is strongly recommended that all functions in the Perl API that don't
-begin with C<perl> be referenced with a C<Perl_> prefix. The bare function
-names without the C<Perl_> prefix are supported with macros, but this
-support may cease in a future release.
-
-See L<perlapi>.
-
-=item *
-
-Enabling threads has source compatibility issues
-
-Perl built with threading enabled requires extensions to use the new
-C<dTHR> macro to initialize the handle to access per-thread data.
-If you see a compiler error that talks about the variable C<thr> not
-being declared (when building a module that has XS code), you need
-to add C<dTHR;> at the beginning of the block that elicited the error.
-
-The API function C<perl_get_sv("@",GV_ADD)> should be used instead of
-directly accessing perl globals as C<GvSV(errgv)>. The API call is
-backward compatible with existing perls and provides source compatibility
-with threading is enabled.
-
-See L<"C Source Compatibility"> for more information.
-
-=back
-
-=head2 Binary Compatibility
-
-This version is NOT binary compatible with older versions. All extensions
-will need to be recompiled. Further binaries built with threads enabled
-are incompatible with binaries built without. This should largely be
-transparent to the user, as all binary incompatible configurations have
-their own unique architecture name, and extension binaries get installed at
-unique locations. This allows coexistence of several configurations in
-the same directory hierarchy. See F<INSTALL>.
-
-=head2 Security fixes may affect compatibility
-
-A few taint leaks and taint omissions have been corrected. This may lead
-to "failure" of scripts that used to work with older versions. Compiling
-with -DINCOMPLETE_TAINTS provides a perl with minimal amounts of changes
-to the tainting behavior. But note that the resulting perl will have
-known insecurities.
-
-Oneliners with the C<-e> switch do not create temporary files anymore.
-
-=head2 Relaxed new mandatory warnings introduced in 5.004
-
-Many new warnings that were introduced in 5.004 have been made
-optional. Some of these warnings are still present, but perl's new
-features make them less often a problem. See L<New Diagnostics>.
-
-=head2 Licensing
-
-Perl has a new Social Contract for contributors. See F<Porting/Contract>.
-
-The license included in much of the Perl documentation has changed.
-Most of the Perl documentation was previously under the implicit GNU
-General Public License or the Artistic License (at the user's choice).
-Now much of the documentation unambiguously states the terms under which
-it may be distributed. Those terms are in general much less restrictive
-than the GNU GPL. See L<perl> and the individual perl manpages listed
-therein.
-
-=head1 Core Changes
-
-
-=head2 Threads
-
-WARNING: Threading is considered an B<experimental> feature. Details of the
-implementation may change without notice. There are known limitations
-and some bugs. These are expected to be fixed in future versions.
-
-See F<README.threads>.
-
-=head2 Compiler
-
-WARNING: The Compiler and related tools are considered B<experimental>.
-Features may change without notice, and there are known limitations
-and bugs. Since the compiler is fully external to perl, the default
-configuration will build and install it.
-
-The Compiler produces three different types of transformations of a
-perl program. The C backend generates C code that captures perl's state
-just before execution begins. It eliminates the compile-time overheads
-of the regular perl interpreter, but the run-time performance remains
-comparatively the same. The CC backend generates optimized C code
-equivalent to the code path at run-time. The CC backend has greater
-potential for big optimizations, but only a few optimizations are
-implemented currently. The Bytecode backend generates a platform
-independent bytecode representation of the interpreter's state
-just before execution. Thus, the Bytecode back end also eliminates
-much of the compilation overhead of the interpreter.
-
-The compiler comes with several valuable utilities.
-
-C<B::Lint> is an experimental module to detect and warn about suspicious
-code, especially the cases that the C<-w> switch does not detect.
-
-C<B::Deparse> can be used to demystify perl code, and understand
-how perl optimizes certain constructs.
-
-C<B::Xref> generates cross reference reports of all definition and use
-of variables, subroutines and formats in a program.
-
-C<B::Showlex> show the lexical variables used by a subroutine or file
-at a glance.
-
-C<perlcc> is a simple frontend for compiling perl.
-
-See C<ext/B/README>, L<B>, and the respective compiler modules.
-
-=head2 Regular Expressions
-
-Perl's regular expression engine has been seriously overhauled, and
-many new constructs are supported. Several bugs have been fixed.
-
-Here is an itemized summary:
-
-=over 4
-
-=item Many new and improved optimizations
-
-Changes in the RE engine:
-
- Unneeded nodes removed;
- Substrings merged together;
- New types of nodes to process (SUBEXPR)* and similar expressions
- quickly, used if the SUBEXPR has no side effects and matches
- strings of the same length;
- Better optimizations by lookup for constant substrings;
- Better search for constants substrings anchored by $ ;
-
-Changes in Perl code using RE engine:
-
- More optimizations to s/longer/short/;
- study() was not working;
- /blah/ may be optimized to an analogue of index() if $& $` $' not seen;
- Unneeded copying of matched-against string removed;
- Only matched part of the string is copying if $` $' were not seen;
-
-=item Many bug fixes
-
-Note that only the major bug fixes are listed here. See F<Changes> for others.
-
- Backtracking might not restore start of $3.
- No feedback if max count for * or + on "complex" subexpression
- was reached, similarly (but at compile time) for {3,34567}
- Primitive restrictions on max count introduced to decrease a
- possibility of a segfault;
- (ZERO-LENGTH)* could segfault;
- (ZERO-LENGTH)* was prohibited;
- Long REs were not allowed;
- /RE/g could skip matches at the same position after a
- zero-length match;
-
-=item New regular expression constructs
-
-The following new syntax elements are supported:
-
- (?<=RE)
- (?<!RE)
- (?{ CODE })
- (?i-x)
- (?i:RE)
- (?(COND)YES_RE|NO_RE)
- (?>RE)
- \z
-
-=item New operator for precompiled regular expressions
-
-See L<New C<qrE<sol>E<sol>> operator>.
-
-=item Other improvements
-
- Better debugging output (possibly with colors),
- even from non-debugging Perl;
- RE engine code now looks like C, not like assembler;
- Behaviour of RE modifiable by `use re' directive;
- Improved documentation;
- Test suite significantly extended;
- Syntax [:^upper:] etc., reserved inside character classes;
-
-=item Incompatible changes
-
- (?i) localized inside enclosing group;
- $( is not interpolated into RE any more;
- /RE/g may match at the same position (with non-zero length)
- after a zero-length match (bug fix).
-
-=back
-
-See L<perlre> and L<perlop>.
-
-=head2 Improved malloc()
-
-See banner at the beginning of C<malloc.c> for details.
-
-=head2 Quicksort is internally implemented
-
-Perl now contains its own highly optimized qsort() routine. The new qsort()
-is resistant to inconsistent comparison functions, so Perl's C<sort()> will
-not provoke coredumps any more when given poorly written sort subroutines.
-(Some C library C<qsort()>s that were being used before used to have this
-problem.) In our testing, the new C<qsort()> required the minimal number
-of pair-wise compares on average, among all known C<qsort()> implementations.
-
-See C<perlfunc/sort>.
-
-=head2 Reliable signals
-
-Perl's signal handling is susceptible to random crashes, because signals
-arrive asynchronously, and the Perl runtime is not reentrant at arbitrary
-times.
-
-However, one experimental implementation of reliable signals is available
-when threads are enabled. See C<Thread::Signal>. Also see F<INSTALL> for
-how to build a Perl capable of threads.
-
-=head2 Reliable stack pointers
-
-The internals now reallocate the perl stack only at predictable times.
-In particular, magic calls never trigger reallocations of the stack,
-because all reentrancy of the runtime is handled using a "stack of stacks".
-This should improve reliability of cached stack pointers in the internals
-and in XSUBs.
-
-=head2 More generous treatment of carriage returns
-
-Perl used to complain if it encountered literal carriage returns in
-scripts. Now they are mostly treated like whitespace within program text.
-Inside string literals and here documents, literal carriage returns are
-ignored if they occur paired with linefeeds, or get interpreted as whitespace
-if they stand alone. This behavior means that literal carriage returns
-in files should be avoided. You can get the older, more compatible (but
-less generous) behavior by defining the preprocessor symbol
-C<PERL_STRICT_CR> when building perl. Of course, all this has nothing
-whatever to do with how escapes like C<\r> are handled within strings.
-
-Note that this doesn't somehow magically allow you to keep all text files
-in DOS format. The generous treatment only applies to files that perl
-itself parses. If your C compiler doesn't allow carriage returns in
-files, you may still be unable to build modules that need a C compiler.
-
-=head2 Memory leaks
-
-C<substr>, C<pos> and C<vec> don't leak memory anymore when used in lvalue
-context. Many small leaks that impacted applications that embed multiple
-interpreters have been fixed.
-
-=head2 Better support for multiple interpreters
-
-The build-time option C<-DMULTIPLICITY> has had many of the details
-reworked. Some previously global variables that should have been
-per-interpreter now are. With care, this allows interpreters to call
-each other. See the C<PerlInterp> extension on CPAN.
-
-=head2 Behavior of local() on array and hash elements is now well-defined
-
-See L<perlsub/"Temporary Values via local()">.
-
-=head2 C<%!> is transparently tied to the L<Errno> module
-
-See L<perlvar>, and L<Errno>.
-
-=head2 Pseudo-hashes are supported
-
-See L<perlref>.
-
-=head2 C<EXPR foreach EXPR> is supported
-
-See L<perlsyn>.
-
-=head2 Keywords can be globally overridden
-
-See L<perlsub>.
-
-=head2 C<$^E> is meaningful on Win32
-
-See L<perlvar>.
-
-=head2 C<foreach (1..1000000)> optimized
-
-C<foreach (1..1000000)> is now optimized into a counting loop. It does
-not try to allocate a 1000000-size list anymore.
-
-=head2 C<Foo::> can be used as implicitly quoted package name
-
-Barewords caused unintuitive behavior when a subroutine with the same
-name as a package happened to be defined. Thus, C<new Foo @args>,
-use the result of the call to C<Foo()> instead of C<Foo> being treated
-as a literal. The recommended way to write barewords in the indirect
-object slot is C<new Foo:: @args>. Note that the method C<new()> is
-called with a first argument of C<Foo>, not C<Foo::> when you do that.
-
-=head2 C<exists $Foo::{Bar::}> tests existence of a package
-
-It was impossible to test for the existence of a package without
-actually creating it before. Now C<exists $Foo::{Bar::}> can be
-used to test if the C<Foo::Bar> namespace has been created.
-
-=head2 Better locale support
-
-See L<perllocale>.
-
-=head2 Experimental support for 64-bit platforms
-
-Perl5 has always had 64-bit support on systems with 64-bit longs.
-Starting with 5.005, the beginnings of experimental support for systems
-with 32-bit long and 64-bit 'long long' integers has been added.
-If you add -DUSE_LONG_LONG to your ccflags in config.sh (or manually
-define it in perl.h) then perl will be built with 'long long' support.
-There will be many compiler warnings, and the resultant perl may not
-work on all systems. There are many other issues related to
-third-party extensions and libraries. This option exists to allow
-people to work on those issues.
-
-=head2 prototype() returns useful results on builtins
-
-See L<perlfunc/prototype>.
-
-=head2 Extended support for exception handling
-
-C<die()> now accepts a reference value, and C<$@> gets set to that
-value in exception traps. This makes it possible to propagate
-exception objects. This is an undocumented B<experimental> feature.
-
-=head2 Re-blessing in DESTROY() supported for chaining DESTROY() methods
-
-See L<perlobj/Destructors>.
-
-=head2 All C<printf> format conversions are handled internally
-
-See L<perlfunc/printf>.
-
-=head2 New C<INIT> keyword
-
-C<INIT> subs are like C<BEGIN> and C<END>, but they get run just before
-the perl runtime begins execution. e.g., the Perl Compiler makes use of
-C<INIT> blocks to initialize and resolve pointers to XSUBs.
-
-=head2 New C<lock> keyword
-
-The C<lock> keyword is the fundamental synchronization primitive
-in threaded perl. When threads are not enabled, it is currently a noop.
-
-To minimize impact on source compatibility this keyword is "weak", i.e., any
-user-defined subroutine of the same name overrides it, unless a C<use Thread>
-has been seen.
-
-=head2 New C<qr//> operator
-
-The C<qr//> operator, which is syntactically similar to the other quote-like
-operators, is used to create precompiled regular expressions. This compiled
-form can now be explicitly passed around in variables, and interpolated in
-other regular expressions. See L<perlop>.
-
-=head2 C<our> is now a reserved word
-
-Calling a subroutine with the name C<our> will now provoke a warning when
-using the C<-w> switch.
-
-=head2 Tied arrays are now fully supported
-
-See L<Tie::Array>.
-
-=head2 Tied handles support is better
-
-Several missing hooks have been added. There is also a new base class for
-TIEARRAY implementations. See L<Tie::Array>.
-
-=head2 4th argument to substr
-
-substr() can now both return and replace in one operation. The optional
-4th argument is the replacement string. See L<perlfunc/substr>.
-
-=head2 Negative LENGTH argument to splice
-
-splice() with a negative LENGTH argument now work similar to what the
-LENGTH did for substr(). Previously a negative LENGTH was treated as
-0. See L<perlfunc/splice>.
-
-=head2 Magic lvalues are now more magical
-
-When you say something like C<substr($x, 5) = "hi">, the scalar returned
-by substr() is special, in that any modifications to it affect $x.
-(This is called a 'magic lvalue' because an 'lvalue' is something on
-the left side of an assignment.) Normally, this is exactly what you
-would expect to happen, but Perl uses the same magic if you use substr(),
-pos(), or vec() in a context where they might be modified, like taking
-a reference with C<\> or as an argument to a sub that modifies C<@_>.
-In previous versions, this 'magic' only went one way, but now changes
-to the scalar the magic refers to ($x in the above example) affect the
-magic lvalue too. For instance, this code now acts differently:
-
- $x = "hello";
- sub printit {
- $x = "g'bye";
- print $_[0], "\n";
- }
- printit(substr($x, 0, 5));
-
-In previous versions, this would print "hello", but it now prints "g'bye".
-
-=head2 <> now reads in records
-
-If C<$/> is a reference to an integer, or a scalar that holds an integer,
-<> will read in records instead of lines. For more info, see
-L<perlvar/$E<sol>>.
-
-=head1 Supported Platforms
-
-Configure has many incremental improvements. Site-wide policy for building
-perl can now be made persistent, via Policy.sh. Configure also records
-the command-line arguments used in F<config.sh>.
-
-=head2 New Platforms
-
-BeOS is now supported. See F<README.beos>.
-
-DOS is now supported under the DJGPP tools. See F<README.dos> (installed
-as L<perldos> on some systems).
-
-MiNT is now supported. See F<README.mint>.
-
-MPE/iX is now supported. See F<README.mpeix>.
-
-MVS (aka OS390, aka Open Edition) is now supported. See F<README.os390>
-(installed as L<perlos390> on some systems).
-
-Stratus VOS is now supported. See F<README.vos>.
-
-=head2 Changes in existing support
-
-Win32 support has been vastly enhanced. Support for Perl Object, a C++
-encapsulation of Perl. GCC and EGCS are now supported on Win32.
-See F<README.win32>, aka L<perlwin32>.
-
-VMS configuration system has been rewritten. See F<README.vms> (installed
-as F<README_vms> on some systems).
-
-The hints files for most Unix platforms have seen incremental improvements.
-
-=head1 Modules and Pragmata
-
-=head2 New Modules
-
-=over 4
-
-=item B
-
-Perl compiler and tools. See L<B>.
-
-=item Data::Dumper
-
-A module to pretty print Perl data. See L<Data::Dumper>.
-
-=item Dumpvalue
-
-A module to dump perl values to the screen. See L<Dumpvalue>.
-
-=item Errno
-
-A module to look up errors more conveniently. See L<Errno>.
-
-=item File::Spec
-
-A portable API for file operations.
-
-=item ExtUtils::Installed
-
-Query and manage installed modules.
-
-=item ExtUtils::Packlist
-
-Manipulate .packlist files.
-
-=item Fatal
-
-Make functions/builtins succeed or die.
-
-=item IPC::SysV
-
-Constants and other support infrastructure for System V IPC operations
-in perl.
-
-=item Test
-
-A framework for writing test suites.
-
-=item Tie::Array
-
-Base class for tied arrays.
-
-=item Tie::Handle
-
-Base class for tied handles.
-
-=item Thread
-
-Perl thread creation, manipulation, and support.
-
-=item attrs
-
-Set subroutine attributes.
-
-=item fields
-
-Compile-time class fields.
-
-=item re
-
-Various pragmata to control behavior of regular expressions.
-
-=back
-
-=head2 Changes in existing modules
-
-=over 4
-
-=item Benchmark
-
-You can now run tests for I<x> seconds instead of guessing the right
-number of tests to run.
-
-Keeps better time.
-
-=item Carp
-
-Carp has a new function cluck(). cluck() warns, like carp(), but also adds
-a stack backtrace to the error message, like confess().
-
-=item CGI
-
-CGI has been updated to version 2.42.
-
-=item Fcntl
-
-More Fcntl constants added: F_SETLK64, F_SETLKW64, O_LARGEFILE for
-large (more than 4G) file access (the 64-bit support is not yet
-working, though, so no need to get overly excited), Free/Net/OpenBSD
-locking behaviour flags F_FLOCK, F_POSIX, Linux F_SHLCK, and
-O_ACCMODE: the mask of O_RDONLY, O_WRONLY, and O_RDWR.
-
-=item Math::Complex
-
-The accessors methods Re, Im, arg, abs, rho, theta, methods can
-($z->Re()) now also act as mutators ($z->Re(3)).
-
-=item Math::Trig
-
-A little bit of radial trigonometry (cylindrical and spherical) added,
-for example the great circle distance.
-
-=item POSIX
-
-POSIX now has its own platform-specific hints files.
-
-=item DB_File
-
-DB_File supports version 2.x of Berkeley DB. See C<ext/DB_File/Changes>.
-
-=item MakeMaker
-
-MakeMaker now supports writing empty makefiles, provides a way to
-specify that site umask() policy should be honored. There is also
-better support for manipulation of .packlist files, and getting
-information about installed modules.
-
-Extensions that have both architecture-dependent and
-architecture-independent files are now always installed completely in
-the architecture-dependent locations. Previously, the shareable parts
-were shared both across architectures and across perl versions and were
-therefore liable to be overwritten with newer versions that might have
-subtle incompatibilities.
-
-=item CPAN
-
-See L<perlmodinstall> and L<CPAN>.
-
-=item Cwd
-
-Cwd::cwd is faster on most platforms.
-
-=back
-
-=head1 Utility Changes
-
-C<h2ph> and related utilities have been vastly overhauled.
-
-C<perlcc>, a new experimental front end for the compiler is available.
-
-The crude GNU C<configure> emulator is now called C<configure.gnu> to
-avoid trampling on C<Configure> under case-insensitive filesystems.
-
-C<perldoc> used to be rather slow. The slower features are now optional.
-In particular, case-insensitive searches need the C<-i> switch, and
-recursive searches need C<-r>. You can set these switches in the
-C<PERLDOC> environment variable to get the old behavior.
-
-=head1 Documentation Changes
-
-Config.pm now has a glossary of variables.
-
-F<Porting/patching.pod> has detailed instructions on how to create and
-submit patches for perl.
-
-L<perlport> specifies guidelines on how to write portably.
-
-L<perlmodinstall> describes how to fetch and install modules from C<CPAN>
-sites.
-
-Some more Perl traps are documented now. See L<perltrap>.
-
-L<perlopentut> gives a tutorial on using open().
-
-L<perlreftut> gives a tutorial on references.
-
-L<perlthrtut> gives a tutorial on threads.
-
-=head1 New Diagnostics
-
-=over 4
-
-=item Ambiguous call resolved as CORE::%s(), qualify as such or use &
-
-(W) A subroutine you have declared has the same name as a Perl keyword,
-and you have used the name without qualification for calling one or the
-other. Perl decided to call the builtin because the subroutine is
-not imported.
-
-To force interpretation as a subroutine call, either put an ampersand
-before the subroutine name, or qualify the name with its package.
-Alternatively, you can import the subroutine (or pretend that it's
-imported with the C<use subs> pragma).
-
-To silently interpret it as the Perl operator, use the C<CORE::> prefix
-on the operator (e.g. C<CORE::log($x)>) or by declaring the subroutine
-to be an object method (see L</attrs>).
-
-=item Bad index while coercing array into hash
-
-(F) The index looked up in the hash found as the 0'th element of a
-pseudo-hash is not legal. Index values must be at 1 or greater.
-See L<perlref>.
-
-=item Bareword "%s" refers to nonexistent package
-
-(W) You used a qualified bareword of the form C<Foo::>, but
-the compiler saw no other uses of that namespace before that point.
-Perhaps you need to predeclare a package?
-
-=item Can't call method "%s" on an undefined value
-
-(F) You used the syntax of a method call, but the slot filled by the
-object reference or package name contains an undefined value.
-Something like this will reproduce the error:
-
- $BADREF = 42;
- process $BADREF 1,2,3;
- $BADREF->process(1,2,3);
-
-=item Can't check filesystem of script "%s" for nosuid
-
-(P) For some reason you can't check the filesystem of the script for nosuid.
-
-=item Can't coerce array into hash
-
-(F) You used an array where a hash was expected, but the array has no
-information on how to map from keys to array indices. You can do that
-only with arrays that have a hash reference at index 0.
-
-=item Can't goto subroutine from an eval-string
-
-(F) The "goto subroutine" call can't be used to jump out of an eval "string".
-(You can use it to jump out of an eval {BLOCK}, but you probably don't want to.)
-
-=item Can't localize pseudo-hash element
-
-(F) You said something like C<< local $ar->{'key'} >>, where $ar is
-a reference to a pseudo-hash. That hasn't been implemented yet, but
-you can get a similar effect by localizing the corresponding array
-element directly: C<< local $ar->[$ar->[0]{'key'}] >>.
-
-=item Can't use %%! because Errno.pm is not available
-
-(F) The first time the %! hash is used, perl automatically loads the
-Errno.pm module. The Errno module is expected to tie the %! hash to
-provide symbolic names for C<$!> errno values.
-
-=item Cannot find an opnumber for "%s"
-
-(F) A string of a form C<CORE::word> was given to prototype(), but
-there is no builtin with the name C<word>.
-
-=item Character class syntax [. .] is reserved for future extensions
-
-(W) Within regular expression character classes ([]) the syntax beginning
-with "[." and ending with ".]" is reserved for future extensions.
-If you need to represent those character sequences inside a regular
-expression character class, just quote the square brackets with the
-backslash: "\[." and ".\]".
-
-=item Character class syntax [: :] is reserved for future extensions
-
-(W) Within regular expression character classes ([]) the syntax beginning
-with "[:" and ending with ":]" is reserved for future extensions.
-If you need to represent those character sequences inside a regular
-expression character class, just quote the square brackets with the
-backslash: "\[:" and ":\]".
-
-=item Character class syntax [= =] is reserved for future extensions
-
-(W) Within regular expression character classes ([]) the syntax
-beginning with "[=" and ending with "=]" is reserved for future extensions.
-If you need to represent those character sequences inside a regular
-expression character class, just quote the square brackets with the
-backslash: "\[=" and "=\]".
-
-=item %s: Eval-group in insecure regular expression
-
-(F) Perl detected tainted data when trying to compile a regular expression
-that contains the C<(?{ ... })> zero-width assertion, which is unsafe.
-See L<perlre/(?{ code })>, and L<perlsec>.
-
-=item %s: Eval-group not allowed, use re 'eval'
-
-(F) A regular expression contained the C<(?{ ... })> zero-width assertion,
-but that construct is only allowed when the C<use re 'eval'> pragma is
-in effect. See L<perlre/(?{ code })>.
-
-=item %s: Eval-group not allowed at run time
-
-(F) Perl tried to compile a regular expression containing the C<(?{ ... })>
-zero-width assertion at run time, as it would when the pattern contains
-interpolated values. Since that is a security risk, it is not allowed.
-If you insist, you may still do this by explicitly building the pattern
-from an interpolated string at run time and using that in an eval().
-See L<perlre/(?{ code })>.
-
-=item Explicit blessing to '' (assuming package main)
-
-(W) You are blessing a reference to a zero length string. This has
-the effect of blessing the reference into the package main. This is
-usually not what you want. Consider providing a default target
-package, e.g. bless($ref, $p || 'MyPackage');
-
-=item Illegal hex digit ignored
-
-(W) You may have tried to use a character other than 0 - 9 or A - F in a
-hexadecimal number. Interpretation of the hexadecimal number stopped
-before the illegal character.
-
-=item No such array field
-
-(F) You tried to access an array as a hash, but the field name used is
-not defined. The hash at index 0 should map all valid field names to
-array indices for that to work.
-
-=item No such field "%s" in variable %s of type %s
-
-(F) You tried to access a field of a typed variable where the type
-does not know about the field name. The field names are looked up in
-the %FIELDS hash in the type package at compile time. The %FIELDS hash
-is usually set up with the 'fields' pragma.
-
-=item Out of memory during ridiculously large request
-
-(F) You can't allocate more than 2^31+"small amount" bytes. This error
-is most likely to be caused by a typo in the Perl program. e.g., C<$arr[time]>
-instead of C<$arr[$time]>.
-
-=item Range iterator outside integer range
-
-(F) One (or both) of the numeric arguments to the range operator ".."
-are outside the range which can be represented by integers internally.
-One possible workaround is to force Perl to use magical string
-increment by prepending "0" to your numbers.
-
-=item Recursive inheritance detected while looking for method '%s' %s
-
-(F) More than 100 levels of inheritance were encountered while invoking a
-method. Probably indicates an unintended loop in your inheritance hierarchy.
-
-=item Reference found where even-sized list expected
-
-(W) You gave a single reference where Perl was expecting a list with
-an even number of elements (for assignment to a hash). This
-usually means that you used the anon hash constructor when you meant
-to use parens. In any case, a hash requires key/value B<pairs>.
-
- %hash = { one => 1, two => 2, }; # WRONG
- %hash = [ qw/ an anon array / ]; # WRONG
- %hash = ( one => 1, two => 2, ); # right
- %hash = qw( one 1 two 2 ); # also fine
-
-=item Undefined value assigned to typeglob
-
-(W) An undefined value was assigned to a typeglob, a la C<*foo = undef>.
-This does nothing. It's possible that you really mean C<undef *foo>.
-
-=item Use of reserved word "%s" is deprecated
-
-(D) The indicated bareword is a reserved word. Future versions of perl
-may use it as a keyword, so you're better off either explicitly quoting
-the word in a manner appropriate for its context of use, or using a
-different name altogether. The warning can be suppressed for subroutine
-names by either adding a C<&> prefix, or using a package qualifier,
-e.g. C<&our()>, or C<Foo::our()>.
-
-=item perl: warning: Setting locale failed.
-
-(S) The whole warning message will look something like:
-
- perl: warning: Setting locale failed.
- perl: warning: Please check that your locale settings:
- LC_ALL = "En_US",
- LANG = (unset)
- are supported and installed on your system.
- perl: warning: Falling back to the standard locale ("C").
-
-Exactly what were the failed locale settings varies. In the above the
-settings were that the LC_ALL was "En_US" and the LANG had no value.
-This error means that Perl detected that you and/or your system
-administrator have set up the so-called variable system but Perl could
-not use those settings. This was not dead serious, fortunately: there
-is a "default locale" called "C" that Perl can and will use, the
-script will be run. Before you really fix the problem, however, you
-will get the same error message each time you run Perl. How to really
-fix the problem can be found in L<perllocale/"LOCALE PROBLEMS">.
-
-=back
-
-
-=head1 Obsolete Diagnostics
-
-=over 4
-
-=item Can't mktemp()
-
-(F) The mktemp() routine failed for some reason while trying to process
-a B<-e> switch. Maybe your /tmp partition is full, or clobbered.
-
-Removed because B<-e> doesn't use temporary files any more.
-
-=item Can't write to temp file for B<-e>: %s
-
-(F) The write routine failed for some reason while trying to process
-a B<-e> switch. Maybe your /tmp partition is full, or clobbered.
-
-Removed because B<-e> doesn't use temporary files any more.
-
-=item Cannot open temporary file
-
-(F) The create routine failed for some reason while trying to process
-a B<-e> switch. Maybe your /tmp partition is full, or clobbered.
-
-Removed because B<-e> doesn't use temporary files any more.
-
-=item regexp too big
-
-(F) The current implementation of regular expressions uses shorts as
-address offsets within a string. Unfortunately this means that if
-the regular expression compiles to longer than 32767, it'll blow up.
-Usually when you want a regular expression this big, there is a better
-way to do it with multiple statements. See L<perlre>.
-
-=back
-
-=head1 Configuration Changes
-
-You can use "Configure -Uinstallusrbinperl" which causes installperl
-to skip installing perl also as /usr/bin/perl. This is useful if you
-prefer not to modify /usr/bin for some reason or another but harmful
-because many scripts assume to find Perl in /usr/bin/perl.
-
-=head1 BUGS
-
-If you find what you think is a bug, you might check the headers of
-recently posted articles in the comp.lang.perl.misc newsgroup.
-There may also be information at http://www.perl.com/perl/ , the Perl
-Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Make sure you trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to <F<perlbug@perl.com>> to be
-analysed by the Perl porting team.
-
-=head1 SEE ALSO
-
-The F<Changes> file for exhaustive details on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=head1 HISTORY
-
-Written by Gurusamy Sarathy <F<gsar@activestate.com>>, with many contributions
-from The Perl Porters.
-
-Send omissions or corrections to <F<perlbug@perl.com>>.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl5100delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5100delta.pod
deleted file mode 100644
index 4e5c6d3a2b6..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl5100delta.pod
+++ /dev/null
@@ -1,1612 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perl5100delta - what is new for perl 5.10.0
-
-=head1 DESCRIPTION
-
-This document describes the differences between the 5.8.8 release and
-the 5.10.0 release.
-
-Many of the bug fixes in 5.10.0 were already seen in the 5.8.X maintenance
-releases; they are not duplicated here and are documented in the set of
-man pages named perl58[1-8]?delta.
-
-=head1 Core Enhancements
-
-=head2 The C<feature> pragma
-
-The C<feature> pragma is used to enable new syntax that would break Perl's
-backwards-compatibility with older releases of the language. It's a lexical
-pragma, like C<strict> or C<warnings>.
-
-Currently the following new features are available: C<switch> (adds a
-switch statement), C<say> (adds a C<say> built-in function), and C<state>
-(adds a C<state> keyword for declaring "static" variables). Those
-features are described in their own sections of this document.
-
-The C<feature> pragma is also implicitly loaded when you require a minimal
-perl version (with the C<use VERSION> construct) greater than, or equal
-to, 5.9.5. See L<feature> for details.
-
-=head2 New B<-E> command-line switch
-
-B<-E> is equivalent to B<-e>, but it implicitly enables all
-optional features (like C<use feature ":5.10">).
-
-=head2 Defined-or operator
-
-A new operator C<//> (defined-or) has been implemented.
-The following expression:
-
- $a // $b
-
-is merely equivalent to
-
- defined $a ? $a : $b
-
-and the statement
-
- $c //= $d;
-
-can now be used instead of
-
- $c = $d unless defined $c;
-
-The C<//> operator has the same precedence and associativity as C<||>.
-Special care has been taken to ensure that this operator Do What You Mean
-while not breaking old code, but some edge cases involving the empty
-regular expression may now parse differently. See L<perlop> for
-details.
-
-=head2 Switch and Smart Match operator
-
-Perl 5 now has a switch statement. It's available when C<use feature
-'switch'> is in effect. This feature introduces three new keywords,
-C<given>, C<when>, and C<default>:
-
- given ($foo) {
- when (/^abc/) { $abc = 1; }
- when (/^def/) { $def = 1; }
- when (/^xyz/) { $xyz = 1; }
- default { $nothing = 1; }
- }
-
-A more complete description of how Perl matches the switch variable
-against the C<when> conditions is given in L<perlsyn/"Switch statements">.
-
-This kind of match is called I<smart match>, and it's also possible to use
-it outside of switch statements, via the new C<~~> operator. See
-L<perlsyn/"Smart matching in detail">.
-
-This feature was contributed by Robin Houston.
-
-=head2 Regular expressions
-
-=over 4
-
-=item Recursive Patterns
-
-It is now possible to write recursive patterns without using the C<(??{})>
-construct. This new way is more efficient, and in many cases easier to
-read.
-
-Each capturing parenthesis can now be treated as an independent pattern
-that can be entered by using the C<(?PARNO)> syntax (C<PARNO> standing for
-"parenthesis number"). For example, the following pattern will match
-nested balanced angle brackets:
-
- /
- ^ # start of line
- ( # start capture buffer 1
- < # match an opening angle bracket
- (?: # match one of:
- (?> # don't backtrack over the inside of this group
- [^<>]+ # one or more non angle brackets
- ) # end non backtracking group
- | # ... or ...
- (?1) # recurse to bracket 1 and try it again
- )* # 0 or more times.
- > # match a closing angle bracket
- ) # end capture buffer one
- $ # end of line
- /x
-
-PCRE users should note that Perl's recursive regex feature allows
-backtracking into a recursed pattern, whereas in PCRE the recursion is
-atomic or "possessive" in nature. As in the example above, you can
-add (?>) to control this selectively. (Yves Orton)
-
-=item Named Capture Buffers
-
-It is now possible to name capturing parenthesis in a pattern and refer to
-the captured contents by name. The naming syntax is C<< (?<NAME>....) >>.
-It's possible to backreference to a named buffer with the C<< \k<NAME> >>
-syntax. In code, the new magical hashes C<%+> and C<%-> can be used to
-access the contents of the capture buffers.
-
-Thus, to replace all doubled chars with a single copy, one could write
-
- s/(?<letter>.)\k<letter>/$+{letter}/g
-
-Only buffers with defined contents will be "visible" in the C<%+> hash, so
-it's possible to do something like
-
- foreach my $name (keys %+) {
- print "content of buffer '$name' is $+{$name}\n";
- }
-
-The C<%-> hash is a bit more complete, since it will contain array refs
-holding values from all capture buffers similarly named, if there should
-be many of them.
-
-C<%+> and C<%-> are implemented as tied hashes through the new module
-C<Tie::Hash::NamedCapture>.
-
-Users exposed to the .NET regex engine will find that the perl
-implementation differs in that the numerical ordering of the buffers
-is sequential, and not "unnamed first, then named". Thus in the pattern
-
- /(A)(?<B>B)(C)(?<D>D)/
-
-$1 will be 'A', $2 will be 'B', $3 will be 'C' and $4 will be 'D' and not
-$1 is 'A', $2 is 'C' and $3 is 'B' and $4 is 'D' that a .NET programmer
-would expect. This is considered a feature. :-) (Yves Orton)
-
-=item Possessive Quantifiers
-
-Perl now supports the "possessive quantifier" syntax of the "atomic match"
-pattern. Basically a possessive quantifier matches as much as it can and never
-gives any back. Thus it can be used to control backtracking. The syntax is
-similar to non-greedy matching, except instead of using a '?' as the modifier
-the '+' is used. Thus C<?+>, C<*+>, C<++>, C<{min,max}+> are now legal
-quantifiers. (Yves Orton)
-
-=item Backtracking control verbs
-
-The regex engine now supports a number of special-purpose backtrack
-control verbs: (*THEN), (*PRUNE), (*MARK), (*SKIP), (*COMMIT), (*FAIL)
-and (*ACCEPT). See L<perlre> for their descriptions. (Yves Orton)
-
-=item Relative backreferences
-
-A new syntax C<\g{N}> or C<\gN> where "N" is a decimal integer allows a
-safer form of back-reference notation as well as allowing relative
-backreferences. This should make it easier to generate and embed patterns
-that contain backreferences. See L<perlre/"Capture buffers">. (Yves Orton)
-
-=item C<\K> escape
-
-The functionality of Jeff Pinyan's module Regexp::Keep has been added to
-the core. In regular expressions you can now use the special escape C<\K>
-as a way to do something like floating length positive lookbehind. It is
-also useful in substitutions like:
-
- s/(foo)bar/$1/g
-
-that can now be converted to
-
- s/foo\Kbar//g
-
-which is much more efficient. (Yves Orton)
-
-=item Vertical and horizontal whitespace, and linebreak
-
-Regular expressions now recognize the C<\v> and C<\h> escapes that match
-vertical and horizontal whitespace, respectively. C<\V> and C<\H>
-logically match their complements.
-
-C<\R> matches a generic linebreak, that is, vertical whitespace, plus
-the multi-character sequence C<"\x0D\x0A">.
-
-=back
-
-=head2 C<say()>
-
-say() is a new built-in, only available when C<use feature 'say'> is in
-effect, that is similar to print(), but that implicitly appends a newline
-to the printed string. See L<perlfunc/say>. (Robin Houston)
-
-=head2 Lexical C<$_>
-
-The default variable C<$_> can now be lexicalized, by declaring it like
-any other lexical variable, with a simple
-
- my $_;
-
-The operations that default on C<$_> will use the lexically-scoped
-version of C<$_> when it exists, instead of the global C<$_>.
-
-In a C<map> or a C<grep> block, if C<$_> was previously my'ed, then the
-C<$_> inside the block is lexical as well (and scoped to the block).
-
-In a scope where C<$_> has been lexicalized, you can still have access to
-the global version of C<$_> by using C<$::_>, or, more simply, by
-overriding the lexical declaration with C<our $_>. (Rafael Garcia-Suarez)
-
-=head2 The C<_> prototype
-
-A new prototype character has been added. C<_> is equivalent to C<$> but
-defaults to C<$_> if the corresponding argument isn't supplied (both C<$>
-and C<_> denote a scalar). Due to the optional nature of the argument,
-you can only use it at the end of a prototype, or before a semicolon.
-
-This has a small incompatible consequence: the prototype() function has
-been adjusted to return C<_> for some built-ins in appropriate cases (for
-example, C<prototype('CORE::rmdir')>). (Rafael Garcia-Suarez)
-
-=head2 UNITCHECK blocks
-
-C<UNITCHECK>, a new special code block has been introduced, in addition to
-C<BEGIN>, C<CHECK>, C<INIT> and C<END>.
-
-C<CHECK> and C<INIT> blocks, while useful for some specialized purposes,
-are always executed at the transition between the compilation and the
-execution of the main program, and thus are useless whenever code is
-loaded at runtime. On the other hand, C<UNITCHECK> blocks are executed
-just after the unit which defined them has been compiled. See L<perlmod>
-for more information. (Alex Gough)
-
-=head2 New Pragma, C<mro>
-
-A new pragma, C<mro> (for Method Resolution Order) has been added. It
-permits to switch, on a per-class basis, the algorithm that perl uses to
-find inherited methods in case of a multiple inheritance hierarchy. The
-default MRO hasn't changed (DFS, for Depth First Search). Another MRO is
-available: the C3 algorithm. See L<mro> for more information.
-(Brandon Black)
-
-Note that, due to changes in the implementation of class hierarchy search,
-code that used to undef the C<*ISA> glob will most probably break. Anyway,
-undef'ing C<*ISA> had the side-effect of removing the magic on the @ISA
-array and should not have been done in the first place. Also, the
-cache C<*::ISA::CACHE::> no longer exists; to force reset the @ISA cache,
-you now need to use the C<mro> API, or more simply to assign to @ISA
-(e.g. with C<@ISA = @ISA>).
-
-=head2 readdir() may return a "short filename" on Windows
-
-The readdir() function may return a "short filename" when the long
-filename contains characters outside the ANSI codepage. Similarly
-Cwd::cwd() may return a short directory name, and glob() may return short
-names as well. On the NTFS file system these short names can always be
-represented in the ANSI codepage. This will not be true for all other file
-system drivers; e.g. the FAT filesystem stores short filenames in the OEM
-codepage, so some files on FAT volumes remain unaccessible through the
-ANSI APIs.
-
-Similarly, $^X, @INC, and $ENV{PATH} are preprocessed at startup to make
-sure all paths are valid in the ANSI codepage (if possible).
-
-The Win32::GetLongPathName() function now returns the UTF-8 encoded
-correct long file name instead of using replacement characters to force
-the name into the ANSI codepage. The new Win32::GetANSIPathName()
-function can be used to turn a long pathname into a short one only if the
-long one cannot be represented in the ANSI codepage.
-
-Many other functions in the C<Win32> module have been improved to accept
-UTF-8 encoded arguments. Please see L<Win32> for details.
-
-=head2 readpipe() is now overridable
-
-The built-in function readpipe() is now overridable. Overriding it permits
-also to override its operator counterpart, C<qx//> (a.k.a. C<``>).
-Moreover, it now defaults to C<$_> if no argument is provided. (Rafael
-Garcia-Suarez)
-
-=head2 Default argument for readline()
-
-readline() now defaults to C<*ARGV> if no argument is provided. (Rafael
-Garcia-Suarez)
-
-=head2 state() variables
-
-A new class of variables has been introduced. State variables are similar
-to C<my> variables, but are declared with the C<state> keyword in place of
-C<my>. They're visible only in their lexical scope, but their value is
-persistent: unlike C<my> variables, they're not undefined at scope entry,
-but retain their previous value. (Rafael Garcia-Suarez, Nicholas Clark)
-
-To use state variables, one needs to enable them by using
-
- use feature 'state';
-
-or by using the C<-E> command-line switch in one-liners.
-See L<perlsub/"Persistent Private Variables">.
-
-=head2 Stacked filetest operators
-
-As a new form of syntactic sugar, it's now possible to stack up filetest
-operators. You can now write C<-f -w -x $file> in a row to mean
-C<-x $file && -w _ && -f _>. See L<perlfunc/-X>.
-
-=head2 UNIVERSAL::DOES()
-
-The C<UNIVERSAL> class has a new method, C<DOES()>. It has been added to
-solve semantic problems with the C<isa()> method. C<isa()> checks for
-inheritance, while C<DOES()> has been designed to be overridden when
-module authors use other types of relations between classes (in addition
-to inheritance). (chromatic)
-
-See L<< UNIVERSAL/"$obj->DOES( ROLE )" >>.
-
-=head2 Formats
-
-Formats were improved in several ways. A new field, C<^*>, can be used for
-variable-width, one-line-at-a-time text. Null characters are now handled
-correctly in picture lines. Using C<@#> and C<~~> together will now
-produce a compile-time error, as those format fields are incompatible.
-L<perlform> has been improved, and miscellaneous bugs fixed.
-
-=head2 Byte-order modifiers for pack() and unpack()
-
-There are two new byte-order modifiers, C<E<gt>> (big-endian) and C<E<lt>>
-(little-endian), that can be appended to most pack() and unpack() template
-characters and groups to force a certain byte-order for that type or group.
-See L<perlfunc/pack> and L<perlpacktut> for details.
-
-=head2 C<no VERSION>
-
-You can now use C<no> followed by a version number to specify that you
-want to use a version of perl older than the specified one.
-
-=head2 C<chdir>, C<chmod> and C<chown> on filehandles
-
-C<chdir>, C<chmod> and C<chown> can now work on filehandles as well as
-filenames, if the system supports respectively C<fchdir>, C<fchmod> and
-C<fchown>, thanks to a patch provided by Gisle Aas.
-
-=head2 OS groups
-
-C<$(> and C<$)> now return groups in the order where the OS returns them,
-thanks to Gisle Aas. This wasn't previously the case.
-
-=head2 Recursive sort subs
-
-You can now use recursive subroutines with sort(), thanks to Robin Houston.
-
-=head2 Exceptions in constant folding
-
-The constant folding routine is now wrapped in an exception handler, and
-if folding throws an exception (such as attempting to evaluate 0/0), perl
-now retains the current optree, rather than aborting the whole program.
-Without this change, programs would not compile if they had expressions that
-happened to generate exceptions, even though those expressions were in code
-that could never be reached at runtime. (Nicholas Clark, Dave Mitchell)
-
-=head2 Source filters in @INC
-
-It's possible to enhance the mechanism of subroutine hooks in @INC by
-adding a source filter on top of the filehandle opened and returned by the
-hook. This feature was planned a long time ago, but wasn't quite working
-until now. See L<perlfunc/require> for details. (Nicholas Clark)
-
-=head2 New internal variables
-
-=over 4
-
-=item C<${^RE_DEBUG_FLAGS}>
-
-This variable controls what debug flags are in effect for the regular
-expression engine when running under C<use re "debug">. See L<re> for
-details.
-
-=item C<${^CHILD_ERROR_NATIVE}>
-
-This variable gives the native status returned by the last pipe close,
-backtick command, successful call to wait() or waitpid(), or from the
-system() operator. See L<perlvar> for details. (Contributed by Gisle Aas.)
-
-=item C<${^RE_TRIE_MAXBUF}>
-
-See L</"Trie optimisation of literal string alternations">.
-
-=item C<${^WIN32_SLOPPY_STAT}>
-
-See L</"Sloppy stat on Windows">.
-
-=back
-
-=head2 Miscellaneous
-
-C<unpack()> now defaults to unpacking the C<$_> variable.
-
-C<mkdir()> without arguments now defaults to C<$_>.
-
-The internal dump output has been improved, so that non-printable characters
-such as newline and backspace are output in C<\x> notation, rather than
-octal.
-
-The B<-C> option can no longer be used on the C<#!> line. It wasn't
-working there anyway, since the standard streams are already set up
-at this point in the execution of the perl interpreter. You can use
-binmode() instead to get the desired behaviour.
-
-=head2 UCD 5.0.0
-
-The copy of the Unicode Character Database included in Perl 5 has
-been updated to version 5.0.0.
-
-=head2 MAD
-
-MAD, which stands for I<Miscellaneous Attribute Decoration>, is a
-still-in-development work leading to a Perl 5 to Perl 6 converter. To
-enable it, it's necessary to pass the argument C<-Dmad> to Configure. The
-obtained perl isn't binary compatible with a regular perl 5.10, and has
-space and speed penalties; moreover not all regression tests still pass
-with it. (Larry Wall, Nicholas Clark)
-
-=head2 kill() on Windows
-
-On Windows platforms, C<kill(-9, $pid)> now kills a process tree.
-(On Unix, this delivers the signal to all processes in the same process
-group.)
-
-=head1 Incompatible Changes
-
-=head2 Packing and UTF-8 strings
-
-The semantics of pack() and unpack() regarding UTF-8-encoded data has been
-changed. Processing is now by default character per character instead of
-byte per byte on the underlying encoding. Notably, code that used things
-like C<pack("a*", $string)> to see through the encoding of string will now
-simply get back the original $string. Packed strings can also get upgraded
-during processing when you store upgraded characters. You can get the old
-behaviour by using C<use bytes>.
-
-To be consistent with pack(), the C<C0> in unpack() templates indicates
-that the data is to be processed in character mode, i.e. character by
-character; on the contrary, C<U0> in unpack() indicates UTF-8 mode, where
-the packed string is processed in its UTF-8-encoded Unicode form on a byte
-by byte basis. This is reversed with regard to perl 5.8.X, but now consistent
-between pack() and unpack().
-
-Moreover, C<C0> and C<U0> can also be used in pack() templates to specify
-respectively character and byte modes.
-
-C<C0> and C<U0> in the middle of a pack or unpack format now switch to the
-specified encoding mode, honoring parens grouping. Previously, parens were
-ignored.
-
-Also, there is a new pack() character format, C<W>, which is intended to
-replace the old C<C>. C<C> is kept for unsigned chars coded as bytes in
-the strings internal representation. C<W> represents unsigned (logical)
-character values, which can be greater than 255. It is therefore more
-robust when dealing with potentially UTF-8-encoded data (as C<C> will wrap
-values outside the range 0..255, and not respect the string encoding).
-
-In practice, that means that pack formats are now encoding-neutral, except
-C<C>.
-
-For consistency, C<A> in unpack() format now trims all Unicode whitespace
-from the end of the string. Before perl 5.9.2, it used to strip only the
-classical ASCII space characters.
-
-=head2 Byte/character count feature in unpack()
-
-A new unpack() template character, C<".">, returns the number of bytes or
-characters (depending on the selected encoding mode, see above) read so far.
-
-=head2 The C<$*> and C<$#> variables have been removed
-
-C<$*>, which was deprecated in favor of the C</s> and C</m> regexp
-modifiers, has been removed.
-
-The deprecated C<$#> variable (output format for numbers) has been
-removed.
-
-Two new severe warnings, C<$#/$* is no longer supported>, have been added.
-
-=head2 substr() lvalues are no longer fixed-length
-
-The lvalues returned by the three argument form of substr() used to be a
-"fixed length window" on the original string. In some cases this could
-cause surprising action at distance or other undefined behaviour. Now the
-length of the window adjusts itself to the length of the string assigned to
-it.
-
-=head2 Parsing of C<-f _>
-
-The identifier C<_> is now forced to be a bareword after a filetest
-operator. This solves a number of misparsing issues when a global C<_>
-subroutine is defined.
-
-=head2 C<:unique>
-
-The C<:unique> attribute has been made a no-op, since its current
-implementation was fundamentally flawed and not threadsafe.
-
-=head2 Effect of pragmas in eval
-
-The compile-time value of the C<%^H> hint variable can now propagate into
-eval("")uated code. This makes it more useful to implement lexical
-pragmas.
-
-As a side-effect of this, the overloaded-ness of constants now propagates
-into eval("").
-
-=head2 chdir FOO
-
-A bareword argument to chdir() is now recognized as a file handle.
-Earlier releases interpreted the bareword as a directory name.
-(Gisle Aas)
-
-=head2 Handling of .pmc files
-
-An old feature of perl was that before C<require> or C<use> look for a
-file with a F<.pm> extension, they will first look for a similar filename
-with a F<.pmc> extension. If this file is found, it will be loaded in
-place of any potentially existing file ending in a F<.pm> extension.
-
-Previously, F<.pmc> files were loaded only if more recent than the
-matching F<.pm> file. Starting with 5.9.4, they'll be always loaded if
-they exist.
-
-=head2 $^V is now a C<version> object instead of a v-string
-
-$^V can still be used with the C<%vd> format in printf, but any
-character-level operations will now access the string representation
-of the C<version> object and not the ordinals of a v-string.
-Expressions like C<< substr($^V, 0, 2) >> or C<< split //, $^V >>
-no longer work and must be rewritten.
-
-=head2 @- and @+ in patterns
-
-The special arrays C<@-> and C<@+> are no longer interpolated in regular
-expressions. (Sadahiro Tomoyuki)
-
-=head2 $AUTOLOAD can now be tainted
-
-If you call a subroutine by a tainted name, and if it defers to an
-AUTOLOAD function, then $AUTOLOAD will be (correctly) tainted.
-(Rick Delaney)
-
-=head2 Tainting and printf
-
-When perl is run under taint mode, C<printf()> and C<sprintf()> will now
-reject any tainted format argument. (Rafael Garcia-Suarez)
-
-=head2 undef and signal handlers
-
-Undefining or deleting a signal handler via C<undef $SIG{FOO}> is now
-equivalent to setting it to C<'DEFAULT'>. (Rafael Garcia-Suarez)
-
-=head2 strictures and dereferencing in defined()
-
-C<use strict 'refs'> was ignoring taking a hard reference in an argument
-to defined(), as in :
-
- use strict 'refs';
- my $x = 'foo';
- if (defined $$x) {...}
-
-This now correctly produces the run-time error C<Can't use string as a
-SCALAR ref while "strict refs" in use>.
-
-C<defined @$foo> and C<defined %$bar> are now also subject to C<strict
-'refs'> (that is, C<$foo> and C<$bar> shall be proper references there.)
-(C<defined(@foo)> and C<defined(%bar)> are discouraged constructs anyway.)
-(Nicholas Clark)
-
-=head2 C<(?p{})> has been removed
-
-The regular expression construct C<(?p{})>, which was deprecated in perl
-5.8, has been removed. Use C<(??{})> instead. (Rafael Garcia-Suarez)
-
-=head2 Pseudo-hashes have been removed
-
-Support for pseudo-hashes has been removed from Perl 5.9. (The C<fields>
-pragma remains here, but uses an alternate implementation.)
-
-=head2 Removal of the bytecode compiler and of perlcc
-
-C<perlcc>, the byteloader and the supporting modules (B::C, B::CC,
-B::Bytecode, etc.) are no longer distributed with the perl sources. Those
-experimental tools have never worked reliably, and, due to the lack of
-volunteers to keep them in line with the perl interpreter developments, it
-was decided to remove them instead of shipping a broken version of those.
-The last version of those modules can be found with perl 5.9.4.
-
-However the B compiler framework stays supported in the perl core, as with
-the more useful modules it has permitted (among others, B::Deparse and
-B::Concise).
-
-=head2 Removal of the JPL
-
-The JPL (Java-Perl Lingo) has been removed from the perl sources tarball.
-
-=head2 Recursive inheritance detected earlier
-
-Perl will now immediately throw an exception if you modify any package's
-C<@ISA> in such a way that it would cause recursive inheritance.
-
-Previously, the exception would not occur until Perl attempted to make
-use of the recursive inheritance while resolving a method or doing a
-C<$foo-E<gt>isa($bar)> lookup.
-
-=head2 warnings::enabled and warnings::warnif changed to favor users of modules
-
-The behaviour in 5.10.x favors the person using the module;
-The behaviour in 5.8.x favors the module writer;
-
-Assume the following code:
-
- main calls Foo::Bar::baz()
- Foo::Bar inherits from Foo::Base
- Foo::Bar::baz() calls Foo::Base::_bazbaz()
- Foo::Base::_bazbaz() calls: warnings::warnif('substr', 'some warning
-message');
-
-On 5.8.x, the code warns when Foo::Bar contains C<use warnings;>
-It does not matter if Foo::Base or main have warnings enabled
-to disable the warning one has to modify Foo::Bar.
-
-On 5.10.0 and newer, the code warns when main contains C<use warnings;>
-It does not matter if Foo::Base or Foo::Bar have warnings enabled
-to disable the warning one has to modify main.
-
-=head1 Modules and Pragmata
-
-=head2 Upgrading individual core modules
-
-Even more core modules are now also available separately through the
-CPAN. If you wish to update one of these modules, you don't need to
-wait for a new perl release. From within the cpan shell, running the
-'r' command will report on modules with upgrades available. See
-C<perldoc CPAN> for more information.
-
-=head2 Pragmata Changes
-
-=over 4
-
-=item C<feature>
-
-The new pragma C<feature> is used to enable new features that might break
-old code. See L</"The C<feature> pragma"> above.
-
-=item C<mro>
-
-This new pragma enables to change the algorithm used to resolve inherited
-methods. See L</"New Pragma, C<mro>"> above.
-
-=item Scoping of the C<sort> pragma
-
-The C<sort> pragma is now lexically scoped. Its effect used to be global.
-
-=item Scoping of C<bignum>, C<bigint>, C<bigrat>
-
-The three numeric pragmas C<bignum>, C<bigint> and C<bigrat> are now
-lexically scoped. (Tels)
-
-=item C<base>
-
-The C<base> pragma now warns if a class tries to inherit from itself.
-(Curtis "Ovid" Poe)
-
-=item C<strict> and C<warnings>
-
-C<strict> and C<warnings> will now complain loudly if they are loaded via
-incorrect casing (as in C<use Strict;>). (Johan Vromans)
-
-=item C<version>
-
-The C<version> module provides support for version objects.
-
-=item C<warnings>
-
-The C<warnings> pragma doesn't load C<Carp> anymore. That means that code
-that used C<Carp> routines without having loaded it at compile time might
-need to be adjusted; typically, the following (faulty) code won't work
-anymore, and will require parentheses to be added after the function name:
-
- use warnings;
- require Carp;
- Carp::confess 'argh';
-
-=item C<less>
-
-C<less> now does something useful (or at least it tries to). In fact, it
-has been turned into a lexical pragma. So, in your modules, you can now
-test whether your users have requested to use less CPU, or less memory,
-less magic, or maybe even less fat. See L<less> for more. (Joshua ben
-Jore)
-
-=back
-
-=head2 New modules
-
-=over 4
-
-=item *
-
-C<encoding::warnings>, by Audrey Tang, is a module to emit warnings
-whenever an ASCII character string containing high-bit bytes is implicitly
-converted into UTF-8. It's a lexical pragma since Perl 5.9.4; on older
-perls, its effect is global.
-
-=item *
-
-C<Module::CoreList>, by Richard Clamp, is a small handy module that tells
-you what versions of core modules ship with any versions of Perl 5. It
-comes with a command-line frontend, C<corelist>.
-
-=item *
-
-C<Math::BigInt::FastCalc> is an XS-enabled, and thus faster, version of
-C<Math::BigInt::Calc>.
-
-=item *
-
-C<Compress::Zlib> is an interface to the zlib compression library. It
-comes with a bundled version of zlib, so having a working zlib is not a
-prerequisite to install it. It's used by C<Archive::Tar> (see below).
-
-=item *
-
-C<IO::Zlib> is an C<IO::>-style interface to C<Compress::Zlib>.
-
-=item *
-
-C<Archive::Tar> is a module to manipulate C<tar> archives.
-
-=item *
-
-C<Digest::SHA> is a module used to calculate many types of SHA digests,
-has been included for SHA support in the CPAN module.
-
-=item *
-
-C<ExtUtils::CBuilder> and C<ExtUtils::ParseXS> have been added.
-
-=item *
-
-C<Hash::Util::FieldHash>, by Anno Siegel, has been added. This module
-provides support for I<field hashes>: hashes that maintain an association
-of a reference with a value, in a thread-safe garbage-collected way.
-Such hashes are useful to implement inside-out objects.
-
-=item *
-
-C<Module::Build>, by Ken Williams, has been added. It's an alternative to
-C<ExtUtils::MakeMaker> to build and install perl modules.
-
-=item *
-
-C<Module::Load>, by Jos Boumans, has been added. It provides a single
-interface to load Perl modules and F<.pl> files.
-
-=item *
-
-C<Module::Loaded>, by Jos Boumans, has been added. It's used to mark
-modules as loaded or unloaded.
-
-=item *
-
-C<Package::Constants>, by Jos Boumans, has been added. It's a simple
-helper to list all constants declared in a given package.
-
-=item *
-
-C<Win32API::File>, by Tye McQueen, has been added (for Windows builds).
-This module provides low-level access to Win32 system API calls for
-files/dirs.
-
-=item *
-
-C<Locale::Maketext::Simple>, needed by CPANPLUS, is a simple wrapper around
-C<Locale::Maketext::Lexicon>. Note that C<Locale::Maketext::Lexicon> isn't
-included in the perl core; the behaviour of C<Locale::Maketext::Simple>
-gracefully degrades when the later isn't present.
-
-=item *
-
-C<Params::Check> implements a generic input parsing/checking mechanism. It
-is used by CPANPLUS.
-
-=item *
-
-C<Term::UI> simplifies the task to ask questions at a terminal prompt.
-
-=item *
-
-C<Object::Accessor> provides an interface to create per-object accessors.
-
-=item *
-
-C<Module::Pluggable> is a simple framework to create modules that accept
-pluggable sub-modules.
-
-=item *
-
-C<Module::Load::Conditional> provides simple ways to query and possibly
-load installed modules.
-
-=item *
-
-C<Time::Piece> provides an object oriented interface to time functions,
-overriding the built-ins localtime() and gmtime().
-
-=item *
-
-C<IPC::Cmd> helps to find and run external commands, possibly
-interactively.
-
-=item *
-
-C<File::Fetch> provide a simple generic file fetching mechanism.
-
-=item *
-
-C<Log::Message> and C<Log::Message::Simple> are used by the log facility
-of C<CPANPLUS>.
-
-=item *
-
-C<Archive::Extract> is a generic archive extraction mechanism
-for F<.tar> (plain, gzipped or bzipped) or F<.zip> files.
-
-=item *
-
-C<CPANPLUS> provides an API and a command-line tool to access the CPAN
-mirrors.
-
-=item *
-
-C<Pod::Escapes> provides utilities that are useful in decoding Pod
-EE<lt>...E<gt> sequences.
-
-=item *
-
-C<Pod::Simple> is now the backend for several of the Pod-related modules
-included with Perl.
-
-=back
-
-=head2 Selected Changes to Core Modules
-
-=over 4
-
-=item C<Attribute::Handlers>
-
-C<Attribute::Handlers> can now report the caller's file and line number.
-(David Feldman)
-
-All interpreted attributes are now passed as array references. (Damian
-Conway)
-
-=item C<B::Lint>
-
-C<B::Lint> is now based on C<Module::Pluggable>, and so can be extended
-with plugins. (Joshua ben Jore)
-
-=item C<B>
-
-It's now possible to access the lexical pragma hints (C<%^H>) by using the
-method B::COP::hints_hash(). It returns a C<B::RHE> object, which in turn
-can be used to get a hash reference via the method B::RHE::HASH(). (Joshua
-ben Jore)
-
-=item C<Thread>
-
-As the old 5005thread threading model has been removed, in favor of the
-ithreads scheme, the C<Thread> module is now a compatibility wrapper, to
-be used in old code only. It has been removed from the default list of
-dynamic extensions.
-
-=back
-
-=head1 Utility Changes
-
-=over 4
-
-=item perl -d
-
-The Perl debugger can now save all debugger commands for sourcing later;
-notably, it can now emulate stepping backwards, by restarting and
-rerunning all bar the last command from a saved command history.
-
-It can also display the parent inheritance tree of a given class, with the
-C<i> command.
-
-=item ptar
-
-C<ptar> is a pure perl implementation of C<tar> that comes with
-C<Archive::Tar>.
-
-=item ptardiff
-
-C<ptardiff> is a small utility used to generate a diff between the contents
-of a tar archive and a directory tree. Like C<ptar>, it comes with
-C<Archive::Tar>.
-
-=item shasum
-
-C<shasum> is a command-line utility, used to print or to check SHA
-digests. It comes with the new C<Digest::SHA> module.
-
-=item corelist
-
-The C<corelist> utility is now installed with perl (see L</"New modules">
-above).
-
-=item h2ph and h2xs
-
-C<h2ph> and C<h2xs> have been made more robust with regard to
-"modern" C code.
-
-C<h2xs> implements a new option C<--use-xsloader> to force use of
-C<XSLoader> even in backwards compatible modules.
-
-The handling of authors' names that had apostrophes has been fixed.
-
-Any enums with negative values are now skipped.
-
-=item perlivp
-
-C<perlivp> no longer checks for F<*.ph> files by default. Use the new C<-a>
-option to run I<all> tests.
-
-=item find2perl
-
-C<find2perl> now assumes C<-print> as a default action. Previously, it
-needed to be specified explicitly.
-
-Several bugs have been fixed in C<find2perl>, regarding C<-exec> and
-C<-eval>. Also the options C<-path>, C<-ipath> and C<-iname> have been
-added.
-
-=item config_data
-
-C<config_data> is a new utility that comes with C<Module::Build>. It
-provides a command-line interface to the configuration of Perl modules
-that use Module::Build's framework of configurability (that is,
-C<*::ConfigData> modules that contain local configuration information for
-their parent modules.)
-
-=item cpanp
-
-C<cpanp>, the CPANPLUS shell, has been added. (C<cpanp-run-perl>, a
-helper for CPANPLUS operation, has been added too, but isn't intended for
-direct use).
-
-=item cpan2dist
-
-C<cpan2dist> is a new utility that comes with CPANPLUS. It's a tool to
-create distributions (or packages) from CPAN modules.
-
-=item pod2html
-
-The output of C<pod2html> has been enhanced to be more customizable via
-CSS. Some formatting problems were also corrected. (Jari Aalto)
-
-=back
-
-=head1 New Documentation
-
-The L<perlpragma> manpage documents how to write one's own lexical
-pragmas in pure Perl (something that is possible starting with 5.9.4).
-
-The new L<perlglossary> manpage is a glossary of terms used in the Perl
-documentation, technical and otherwise, kindly provided by O'Reilly Media,
-Inc.
-
-The L<perlreguts> manpage, courtesy of Yves Orton, describes internals of the
-Perl regular expression engine.
-
-The L<perlreapi> manpage describes the interface to the perl interpreter
-used to write pluggable regular expression engines (by Ævar Arnfjörð
-Bjarmason).
-
-The L<perlunitut> manpage is an tutorial for programming with Unicode and
-string encodings in Perl, courtesy of Juerd Waalboer.
-
-A new manual page, L<perlunifaq> (the Perl Unicode FAQ), has been added
-(Juerd Waalboer).
-
-The L<perlcommunity> manpage gives a description of the Perl community
-on the Internet and in real life. (Edgar "Trizor" Bering)
-
-The L<CORE> manual page documents the C<CORE::> namespace. (Tels)
-
-The long-existing feature of C</(?{...})/> regexps setting C<$_> and pos()
-is now documented.
-
-=head1 Performance Enhancements
-
-=head2 In-place sorting
-
-Sorting arrays in place (C<@a = sort @a>) is now optimized to avoid
-making a temporary copy of the array.
-
-Likewise, C<reverse sort ...> is now optimized to sort in reverse,
-avoiding the generation of a temporary intermediate list.
-
-=head2 Lexical array access
-
-Access to elements of lexical arrays via a numeric constant between 0 and
-255 is now faster. (This used to be only the case for global arrays.)
-
-=head2 XS-assisted SWASHGET
-
-Some pure-perl code that perl was using to retrieve Unicode properties and
-transliteration mappings has been reimplemented in XS.
-
-=head2 Constant subroutines
-
-The interpreter internals now support a far more memory efficient form of
-inlineable constants. Storing a reference to a constant value in a symbol
-table is equivalent to a full typeglob referencing a constant subroutine,
-but using about 400 bytes less memory. This proxy constant subroutine is
-automatically upgraded to a real typeglob with subroutine if necessary.
-The approach taken is analogous to the existing space optimisation for
-subroutine stub declarations, which are stored as plain scalars in place
-of the full typeglob.
-
-Several of the core modules have been converted to use this feature for
-their system dependent constants - as a result C<use POSIX;> now takes about
-200K less memory.
-
-=head2 C<PERL_DONT_CREATE_GVSV>
-
-The new compilation flag C<PERL_DONT_CREATE_GVSV>, introduced as an option
-in perl 5.8.8, is turned on by default in perl 5.9.3. It prevents perl
-from creating an empty scalar with every new typeglob. See L<perl589delta>
-for details.
-
-=head2 Weak references are cheaper
-
-Weak reference creation is now I<O(1)> rather than I<O(n)>, courtesy of
-Nicholas Clark. Weak reference deletion remains I<O(n)>, but if deletion only
-happens at program exit, it may be skipped completely.
-
-=head2 sort() enhancements
-
-Salvador Fandiño provided improvements to reduce the memory usage of C<sort>
-and to speed up some cases.
-
-=head2 Memory optimisations
-
-Several internal data structures (typeglobs, GVs, CVs, formats) have been
-restructured to use less memory. (Nicholas Clark)
-
-=head2 UTF-8 cache optimisation
-
-The UTF-8 caching code is now more efficient, and used more often.
-(Nicholas Clark)
-
-=head2 Sloppy stat on Windows
-
-On Windows, perl's stat() function normally opens the file to determine
-the link count and update attributes that may have been changed through
-hard links. Setting ${^WIN32_SLOPPY_STAT} to a true value speeds up
-stat() by not performing this operation. (Jan Dubois)
-
-=head2 Regular expressions optimisations
-
-=over 4
-
-=item Engine de-recursivised
-
-The regular expression engine is no longer recursive, meaning that
-patterns that used to overflow the stack will either die with useful
-explanations, or run to completion, which, since they were able to blow
-the stack before, will likely take a very long time to happen. If you were
-experiencing the occasional stack overflow (or segfault) and upgrade to
-discover that now perl apparently hangs instead, look for a degenerate
-regex. (Dave Mitchell)
-
-=item Single char char-classes treated as literals
-
-Classes of a single character are now treated the same as if the character
-had been used as a literal, meaning that code that uses char-classes as an
-escaping mechanism will see a speedup. (Yves Orton)
-
-=item Trie optimisation of literal string alternations
-
-Alternations, where possible, are optimised into more efficient matching
-structures. String literal alternations are merged into a trie and are
-matched simultaneously. This means that instead of O(N) time for matching
-N alternations at a given point, the new code performs in O(1) time.
-A new special variable, ${^RE_TRIE_MAXBUF}, has been added to fine-tune
-this optimization. (Yves Orton)
-
-B<Note:> Much code exists that works around perl's historic poor
-performance on alternations. Often the tricks used to do so will disable
-the new optimisations. Hopefully the utility modules used for this purpose
-will be educated about these new optimisations.
-
-=item Aho-Corasick start-point optimisation
-
-When a pattern starts with a trie-able alternation and there aren't
-better optimisations available, the regex engine will use Aho-Corasick
-matching to find the start point. (Yves Orton)
-
-=back
-
-=head1 Installation and Configuration Improvements
-
-=head2 Configuration improvements
-
-=over 4
-
-=item C<-Dusesitecustomize>
-
-Run-time customization of @INC can be enabled by passing the
-C<-Dusesitecustomize> flag to Configure. When enabled, this will make perl
-run F<$sitelibexp/sitecustomize.pl> before anything else. This script can
-then be set up to add additional entries to @INC.
-
-=item Relocatable installations
-
-There is now Configure support for creating a relocatable perl tree. If
-you Configure with C<-Duserelocatableinc>, then the paths in @INC (and
-everything else in %Config) can be optionally located via the path of the
-perl executable.
-
-That means that, if the string C<".../"> is found at the start of any
-path, it's substituted with the directory of $^X. So, the relocation can
-be configured on a per-directory basis, although the default with
-C<-Duserelocatableinc> is that everything is relocated. The initial
-install is done to the original configured prefix.
-
-=item strlcat() and strlcpy()
-
-The configuration process now detects whether strlcat() and strlcpy() are
-available. When they are not available, perl's own version is used (from
-Russ Allbery's public domain implementation). Various places in the perl
-interpreter now use them. (Steve Peters)
-
-=item C<d_pseudofork> and C<d_printf_format_null>
-
-A new configuration variable, available as C<$Config{d_pseudofork}> in
-the L<Config> module, has been added, to distinguish real fork() support
-from fake pseudofork used on Windows platforms.
-
-A new configuration variable, C<d_printf_format_null>, has been added,
-to see if printf-like formats are allowed to be NULL.
-
-=item Configure help
-
-C<Configure -h> has been extended with the most commonly used options.
-
-=back
-
-=head2 Compilation improvements
-
-=over 4
-
-=item Parallel build
-
-Parallel makes should work properly now, although there may still be problems
-if C<make test> is instructed to run in parallel.
-
-=item Borland's compilers support
-
-Building with Borland's compilers on Win32 should work more smoothly. In
-particular Steve Hay has worked to side step many warnings emitted by their
-compilers and at least one C compiler internal error.
-
-=item Static build on Windows
-
-Perl extensions on Windows now can be statically built into the Perl DLL.
-
-Also, it's now possible to build a C<perl-static.exe> that doesn't depend
-on the Perl DLL on Win32. See the Win32 makefiles for details.
-(Vadim Konovalov)
-
-=item ppport.h files
-
-All F<ppport.h> files in the XS modules bundled with perl are now
-autogenerated at build time. (Marcus Holland-Moritz)
-
-=item C++ compatibility
-
-Efforts have been made to make perl and the core XS modules compilable
-with various C++ compilers (although the situation is not perfect with
-some of the compilers on some of the platforms tested.)
-
-=item Support for Microsoft 64-bit compiler
-
-Support for building perl with Microsoft's 64-bit compiler has been
-improved. (ActiveState)
-
-=item Visual C++
-
-Perl can now be compiled with Microsoft Visual C++ 2005 (and 2008 Beta 2).
-
-=item Win32 builds
-
-All win32 builds (MS-Win, WinCE) have been merged and cleaned up.
-
-=back
-
-=head2 Installation improvements
-
-=over 4
-
-=item Module auxiliary files
-
-README files and changelogs for CPAN modules bundled with perl are no
-longer installed.
-
-=back
-
-=head2 New Or Improved Platforms
-
-Perl has been reported to work on Symbian OS. See L<perlsymbian> for more
-information.
-
-Many improvements have been made towards making Perl work correctly on
-z/OS.
-
-Perl has been reported to work on DragonFlyBSD and MidnightBSD.
-
-Perl has also been reported to work on NexentaOS
-( http://www.gnusolaris.org/ ).
-
-The VMS port has been improved. See L<perlvms>.
-
-Support for Cray XT4 Catamount/Qk has been added. See
-F<hints/catamount.sh> in the source code distribution for more
-information.
-
-Vendor patches have been merged for RedHat and Gentoo.
-
-DynaLoader::dl_unload_file() now works on Windows.
-
-=head1 Selected Bug Fixes
-
-=over 4
-
-=item strictures in regexp-eval blocks
-
-C<strict> wasn't in effect in regexp-eval blocks (C</(?{...})/>).
-
-=item Calling CORE::require()
-
-CORE::require() and CORE::do() were always parsed as require() and do()
-when they were overridden. This is now fixed.
-
-=item Subscripts of slices
-
-You can now use a non-arrowed form for chained subscripts after a list
-slice, like in:
-
- ({foo => "bar"})[0]{foo}
-
-This used to be a syntax error; a C<< -> >> was required.
-
-=item C<no warnings 'category'> works correctly with -w
-
-Previously when running with warnings enabled globally via C<-w>, selective
-disabling of specific warning categories would actually turn off all warnings.
-This is now fixed; now C<no warnings 'io';> will only turn off warnings in the
-C<io> class. Previously it would erroneously turn off all warnings.
-
-=item threads improvements
-
-Several memory leaks in ithreads were closed. Also, ithreads were made
-less memory-intensive.
-
-C<threads> is now a dual-life module, also available on CPAN. It has been
-expanded in many ways. A kill() method is available for thread signalling.
-One can get thread status, or the list of running or joinable threads.
-
-A new C<< threads->exit() >> method is used to exit from the application
-(this is the default for the main thread) or from the current thread only
-(this is the default for all other threads). On the other hand, the exit()
-built-in now always causes the whole application to terminate. (Jerry
-D. Hedden)
-
-=item chr() and negative values
-
-chr() on a negative value now gives C<\x{FFFD}>, the Unicode replacement
-character, unless when the C<bytes> pragma is in effect, where the low
-eight bits of the value are used.
-
-=item PERL5SHELL and tainting
-
-On Windows, the PERL5SHELL environment variable is now checked for
-taintedness. (Rafael Garcia-Suarez)
-
-=item Using *FILE{IO}
-
-C<stat()> and C<-X> filetests now treat *FILE{IO} filehandles like *FILE
-filehandles. (Steve Peters)
-
-=item Overloading and reblessing
-
-Overloading now works when references are reblessed into another class.
-Internally, this has been implemented by moving the flag for "overloading"
-from the reference to the referent, which logically is where it should
-always have been. (Nicholas Clark)
-
-=item Overloading and UTF-8
-
-A few bugs related to UTF-8 handling with objects that have
-stringification overloaded have been fixed. (Nicholas Clark)
-
-=item eval memory leaks fixed
-
-Traditionally, C<eval 'syntax error'> has leaked badly. Many (but not all)
-of these leaks have now been eliminated or reduced. (Dave Mitchell)
-
-=item Random device on Windows
-
-In previous versions, perl would read the file F</dev/urandom> if it
-existed when seeding its random number generator. That file is unlikely
-to exist on Windows, and if it did would probably not contain appropriate
-data, so perl no longer tries to read it on Windows. (Alex Davies)
-
-=item PERLIO_DEBUG
-
-The C<PERLIO_DEBUG> environment variable no longer has any effect for
-setuid scripts and for scripts run with B<-T>.
-
-Moreover, with a thread-enabled perl, using C<PERLIO_DEBUG> could lead to
-an internal buffer overflow. This has been fixed.
-
-=item PerlIO::scalar and read-only scalars
-
-PerlIO::scalar will now prevent writing to read-only scalars. Moreover,
-seek() is now supported with PerlIO::scalar-based filehandles, the
-underlying string being zero-filled as needed. (Rafael, Jarkko Hietaniemi)
-
-=item study() and UTF-8
-
-study() never worked for UTF-8 strings, but could lead to false results.
-It's now a no-op on UTF-8 data. (Yves Orton)
-
-=item Critical signals
-
-The signals SIGILL, SIGBUS and SIGSEGV are now always delivered in an
-"unsafe" manner (contrary to other signals, that are deferred until the
-perl interpreter reaches a reasonably stable state; see
-L<perlipc/"Deferred Signals (Safe Signals)">). (Rafael)
-
-=item @INC-hook fix
-
-When a module or a file is loaded through an @INC-hook, and when this hook
-has set a filename entry in %INC, __FILE__ is now set for this module
-accordingly to the contents of that %INC entry. (Rafael)
-
-=item C<-t> switch fix
-
-The C<-w> and C<-t> switches can now be used together without messing
-up which categories of warnings are activated. (Rafael)
-
-=item Duping UTF-8 filehandles
-
-Duping a filehandle which has the C<:utf8> PerlIO layer set will now
-properly carry that layer on the duped filehandle. (Rafael)
-
-=item Localisation of hash elements
-
-Localizing a hash element whose key was given as a variable didn't work
-correctly if the variable was changed while the local() was in effect (as
-in C<local $h{$x}; ++$x>). (Bo Lindbergh)
-
-=back
-
-=head1 New or Changed Diagnostics
-
-=over 4
-
-=item Use of uninitialized value
-
-Perl will now try to tell you the name of the variable (if any) that was
-undefined.
-
-=item Deprecated use of my() in false conditional
-
-A new deprecation warning, I<Deprecated use of my() in false conditional>,
-has been added, to warn against the use of the dubious and deprecated
-construct
-
- my $x if 0;
-
-See L<perldiag>. Use C<state> variables instead.
-
-=item !=~ should be !~
-
-A new warning, C<!=~ should be !~>, is emitted to prevent this misspelling
-of the non-matching operator.
-
-=item Newline in left-justified string
-
-The warning I<Newline in left-justified string> has been removed.
-
-=item Too late for "-T" option
-
-The error I<Too late for "-T" option> has been reformulated to be more
-descriptive.
-
-=item "%s" variable %s masks earlier declaration
-
-This warning is now emitted in more consistent cases; in short, when one
-of the declarations involved is a C<my> variable:
-
- my $x; my $x; # warns
- my $x; our $x; # warns
- our $x; my $x; # warns
-
-On the other hand, the following:
-
- our $x; our $x;
-
-now gives a C<"our" variable %s redeclared> warning.
-
-=item readdir()/closedir()/etc. attempted on invalid dirhandle
-
-These new warnings are now emitted when a dirhandle is used but is
-either closed or not really a dirhandle.
-
-=item Opening dirhandle/filehandle %s also as a file/directory
-
-Two deprecation warnings have been added: (Rafael)
-
- Opening dirhandle %s also as a file
- Opening filehandle %s also as a directory
-
-=item Use of -P is deprecated
-
-Perl's command-line switch C<-P> is now deprecated.
-
-=item v-string in use/require is non-portable
-
-Perl will warn you against potential backwards compatibility problems with
-the C<use VERSION> syntax.
-
-=item perl -V
-
-C<perl -V> has several improvements, making it more useable from shell
-scripts to get the value of configuration variables. See L<perlrun> for
-details.
-
-=back
-
-=head1 Changed Internals
-
-In general, the source code of perl has been refactored, tidied up,
-and optimized in many places. Also, memory management and allocation
-has been improved in several points.
-
-When compiling the perl core with gcc, as many gcc warning flags are
-turned on as is possible on the platform. (This quest for cleanliness
-doesn't extend to XS code because we cannot guarantee the tidiness of
-code we didn't write.) Similar strictness flags have been added or
-tightened for various other C compilers.
-
-=head2 Reordering of SVt_* constants
-
-The relative ordering of constants that define the various types of C<SV>
-have changed; in particular, C<SVt_PVGV> has been moved before C<SVt_PVLV>,
-C<SVt_PVAV>, C<SVt_PVHV> and C<SVt_PVCV>. This is unlikely to make any
-difference unless you have code that explicitly makes assumptions about that
-ordering. (The inheritance hierarchy of C<B::*> objects has been changed
-to reflect this.)
-
-=head2 Elimination of SVt_PVBM
-
-Related to this, the internal type C<SVt_PVBM> has been removed. This
-dedicated type of C<SV> was used by the C<index> operator and parts of the
-regexp engine to facilitate fast Boyer-Moore matches. Its use internally has
-been replaced by C<SV>s of type C<SVt_PVGV>.
-
-=head2 New type SVt_BIND
-
-A new type C<SVt_BIND> has been added, in readiness for the project to
-implement Perl 6 on 5. There deliberately is no implementation yet, and
-they cannot yet be created or destroyed.
-
-=head2 Removal of CPP symbols
-
-The C preprocessor symbols C<PERL_PM_APIVERSION> and
-C<PERL_XS_APIVERSION>, which were supposed to give the version number of
-the oldest perl binary-compatible (resp. source-compatible) with the
-present one, were not used, and sometimes had misleading values. They have
-been removed.
-
-=head2 Less space is used by ops
-
-The C<BASEOP> structure now uses less space. The C<op_seq> field has been
-removed and replaced by a single bit bit-field C<op_opt>. C<op_type> is now 9
-bits long. (Consequently, the C<B::OP> class doesn't provide an C<seq>
-method anymore.)
-
-=head2 New parser
-
-perl's parser is now generated by bison (it used to be generated by
-byacc.) As a result, it seems to be a bit more robust.
-
-Also, Dave Mitchell improved the lexer debugging output under C<-DT>.
-
-=head2 Use of C<const>
-
-Andy Lester supplied many improvements to determine which function
-parameters and local variables could actually be declared C<const> to the C
-compiler. Steve Peters provided new C<*_set> macros and reworked the core to
-use these rather than assigning to macros in LVALUE context.
-
-=head2 Mathoms
-
-A new file, F<mathoms.c>, has been added. It contains functions that are
-no longer used in the perl core, but that remain available for binary or
-source compatibility reasons. However, those functions will not be
-compiled in if you add C<-DNO_MATHOMS> in the compiler flags.
-
-=head2 C<AvFLAGS> has been removed
-
-The C<AvFLAGS> macro has been removed.
-
-=head2 C<av_*> changes
-
-The C<av_*()> functions, used to manipulate arrays, no longer accept null
-C<AV*> parameters.
-
-=head2 $^H and %^H
-
-The implementation of the special variables $^H and %^H has changed, to
-allow implementing lexical pragmas in pure Perl.
-
-=head2 B:: modules inheritance changed
-
-The inheritance hierarchy of C<B::> modules has changed; C<B::NV> now
-inherits from C<B::SV> (it used to inherit from C<B::IV>).
-
-=head2 Anonymous hash and array constructors
-
-The anonymous hash and array constructors now take 1 op in the optree
-instead of 3, now that pp_anonhash and pp_anonlist return a reference to
-an hash/array when the op is flagged with OPf_SPECIAL. (Nicholas Clark)
-
-=head1 Known Problems
-
-There's still a remaining problem in the implementation of the lexical
-C<$_>: it doesn't work inside C</(?{...})/> blocks. (See the TODO test in
-F<t/op/mydef.t>.)
-
-Stacked filetest operators won't work when the C<filetest> pragma is in
-effect, because they rely on the stat() buffer C<_> being populated, and
-filetest bypasses stat().
-
-=head2 UTF-8 problems
-
-The handling of Unicode still is unclean in several places, where it's
-dependent on whether a string is internally flagged as UTF-8. This will
-be made more consistent in perl 5.12, but that won't be possible without
-a certain amount of backwards incompatibility.
-
-=head1 Platform Specific Problems
-
-When compiled with g++ and thread support on Linux, it's reported that the
-C<$!> stops working correctly. This is related to the fact that the glibc
-provides two strerror_r(3) implementation, and perl selects the wrong
-one.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://rt.perl.org/rt3/ . There may also be
-information at http://www.perl.org/ , the Perl Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team.
-
-=head1 SEE ALSO
-
-The F<Changes> file and the perl590delta to perl595delta man pages for
-exhaustive details on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl5101delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5101delta.pod
deleted file mode 100644
index 415ab6be245..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl5101delta.pod
+++ /dev/null
@@ -1,1773 +0,0 @@
-=head1 NAME
-
-perl5101delta - what is new for perl v5.10.1
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.10.0 release and
-the 5.10.1 release.
-
-If you are upgrading from an earlier release such as 5.8.8, first read
-the L<perl5100delta>, which describes differences between 5.8.8 and
-5.10.0
-
-=head1 Incompatible Changes
-
-=head2 Switch statement changes
-
-The handling of complex expressions by the C<given>/C<when> switch
-statement has been enhanced. There are two new cases where C<when> now
-interprets its argument as a boolean, instead of an expression to be used
-in a smart match:
-
-=over 4
-
-=item flip-flop operators
-
-The C<..> and C<...> flip-flop operators are now evaluated in boolean
-context, following their usual semantics; see L<perlop/"Range Operators">.
-
-Note that, as in perl 5.10.0, C<when (1..10)> will not work to test
-whether a given value is an integer between 1 and 10; you should use
-C<when ([1..10])> instead (note the array reference).
-
-However, contrary to 5.10.0, evaluating the flip-flop operators in boolean
-context ensures it can now be useful in a C<when()>, notably for
-implementing bistable conditions, like in:
-
- when (/^=begin/ .. /^=end/) {
- # do something
- }
-
-=item defined-or operator
-
-A compound expression involving the defined-or operator, as in
-C<when (expr1 // expr2)>, will be treated as boolean if the first
-expression is boolean. (This just extends the existing rule that applies
-to the regular or operator, as in C<when (expr1 || expr2)>.)
-
-=back
-
-The next section details more changes brought to the semantics to
-the smart match operator, that naturally also modify the behaviour
-of the switch statements where smart matching is implicitly used.
-
-=head2 Smart match changes
-
-=head3 Changes to type-based dispatch
-
-The smart match operator C<~~> is no longer commutative. The behaviour of
-a smart match now depends primarily on the type of its right hand
-argument. Moreover, its semantics have been adjusted for greater
-consistency or usefulness in several cases. While the general backwards
-compatibility is maintained, several changes must be noted:
-
-=over 4
-
-=item *
-
-Code references with an empty prototype are no longer treated specially.
-They are passed an argument like the other code references (even if they
-choose to ignore it).
-
-=item *
-
-C<%hash ~~ sub {}> and C<@array ~~ sub {}> now test that the subroutine
-returns a true value for each key of the hash (or element of the
-array), instead of passing the whole hash or array as a reference to
-the subroutine.
-
-=item *
-
-Due to the commutativity breakage, code references are no longer
-treated specially when appearing on the left of the C<~~> operator,
-but like any vulgar scalar.
-
-=item *
-
-C<undef ~~ %hash> is always false (since C<undef> can't be a key in a
-hash). No implicit conversion to C<""> is done (as was the case in perl
-5.10.0).
-
-=item *
-
-C<$scalar ~~ @array> now always distributes the smart match across the
-elements of the array. It's true if one element in @array verifies
-C<$scalar ~~ $element>. This is a generalization of the old behaviour
-that tested whether the array contained the scalar.
-
-=back
-
-The full dispatch table for the smart match operator is given in
-L<perlsyn/"Smart matching in detail">.
-
-=head3 Smart match and overloading
-
-According to the rule of dispatch based on the rightmost argument type,
-when an object overloading C<~~> appears on the right side of the
-operator, the overload routine will always be called (with a 3rd argument
-set to a true value, see L<overload>.) However, when the object will
-appear on the left, the overload routine will be called only when the
-rightmost argument is a simple scalar. This way distributivity of smart match
-across arrays is not broken, as well as the other behaviours with complex
-types (coderefs, hashes, regexes). Thus, writers of overloading routines
-for smart match mostly need to worry only with comparing against a scalar,
-and possibly with stringification overloading; the other common cases
-will be automatically handled consistently.
-
-C<~~> will now refuse to work on objects that do not overload it (in order
-to avoid relying on the object's underlying structure). (However, if the
-object overloads the stringification or the numification operators, and
-if overload fallback is active, it will be used instead, as usual.)
-
-=head2 Other incompatible changes
-
-=over 4
-
-=item *
-
-The semantics of C<use feature :5.10*> have changed slightly.
-See L<"Modules and Pragmata"> for more information.
-
-=item *
-
-It is now a run-time error to use the smart match operator C<~~>
-with an object that has no overload defined for it. (This way
-C<~~> will not break encapsulation by matching against the
-object's internal representation as a reference.)
-
-=item *
-
-The version control system used for the development of the perl
-interpreter has been switched from Perforce to git. This is mainly an
-internal issue that only affects people actively working on the perl core;
-but it may have minor external visibility, for example in some of details
-of the output of C<perl -V>. See L<perlrepository> for more information.
-
-=item *
-
-The internal structure of the C<ext/> directory in the perl source has
-been reorganised. In general, a module C<Foo::Bar> whose source was
-stored under F<ext/Foo/Bar/> is now located under F<ext/Foo-Bar/>. Also,
-some modules have been moved from F<lib/> to F<ext/>. This is purely a
-source tarball change, and should make no difference to the compilation or
-installation of perl, unless you have a very customised build process that
-explicitly relies on this structure, or which hard-codes the C<nonxs_ext>
-F<Configure> parameter. Specifically, this change does not by default
-alter the location of any files in the final installation.
-
-=item *
-
-As part of the C<Test::Harness> 2.x to 3.x upgrade, the experimental
-C<Test::Harness::Straps> module has been removed.
-See L</"Updated Modules"> for more details.
-
-=item *
-
-As part of the C<ExtUtils::MakeMaker> upgrade, the
-C<ExtUtils::MakeMaker::bytes> and C<ExtUtils::MakeMaker::vmsish> modules
-have been removed from this distribution.
-
-=item *
-
-C<Module::CoreList> no longer contains the C<%:patchlevel> hash.
-
-=item *
-
-This one is actually a change introduced in 5.10.0, but it was missed
-from that release's perldelta, so it is mentioned here instead.
-
-A bugfix related to the handling of the C</m> modifier and C<qr> resulted
-in a change of behaviour between 5.8.x and 5.10.0:
-
- # matches in 5.8.x, doesn't match in 5.10.0
- $re = qr/^bar/; "foo\nbar" =~ /$re/m;
-
-=back
-
-=head1 Core Enhancements
-
-=head2 Unicode Character Database 5.1.0
-
-The copy of the Unicode Character Database included in Perl 5.10.1 has
-been updated to 5.1.0 from 5.0.0. See
-L<http://www.unicode.org/versions/Unicode5.1.0/#Notable_Changes> for the
-notable changes.
-
-=head2 A proper interface for pluggable Method Resolution Orders
-
-As of Perl 5.10.1 there is a new interface for plugging and using method
-resolution orders other than the default (linear depth first search).
-The C3 method resolution order added in 5.10.0 has been re-implemented as
-a plugin, without changing its Perl-space interface. See L<perlmroapi> for
-more information.
-
-=head2 The C<overloading> pragma
-
-This pragma allows you to lexically disable or enable overloading
-for some or all operations. (Yuval Kogman)
-
-=head2 Parallel tests
-
-The core distribution can now run its regression tests in parallel on
-Unix-like platforms. Instead of running C<make test>, set C<TEST_JOBS> in
-your environment to the number of tests to run in parallel, and run
-C<make test_harness>. On a Bourne-like shell, this can be done as
-
- TEST_JOBS=3 make test_harness # Run 3 tests in parallel
-
-An environment variable is used, rather than parallel make itself, because
-L<TAP::Harness> needs to be able to schedule individual non-conflicting test
-scripts itself, and there is no standard interface to C<make> utilities to
-interact with their job schedulers.
-
-Note that currently some test scripts may fail when run in parallel (most
-notably C<ext/IO/t/io_dir.t>). If necessary run just the failing scripts
-again sequentially and see if the failures go away.
-
-=head2 DTrace support
-
-Some support for DTrace has been added. See "DTrace support" in F<INSTALL>.
-
-=head2 Support for C<configure_requires> in CPAN module metadata
-
-Both C<CPAN> and C<CPANPLUS> now support the C<configure_requires> keyword
-in the C<META.yml> metadata file included in most recent CPAN distributions.
-This allows distribution authors to specify configuration prerequisites that
-must be installed before running F<Makefile.PL> or F<Build.PL>.
-
-See the documentation for C<ExtUtils::MakeMaker> or C<Module::Build> for more
-on how to specify C<configure_requires> when creating a distribution for CPAN.
-
-=head1 Modules and Pragmata
-
-=head2 New Modules and Pragmata
-
-=over 4
-
-=item C<autodie>
-
-This is a new lexically-scoped alternative for the C<Fatal> module.
-The bundled version is 2.06_01. Note that in this release, using a string
-eval when C<autodie> is in effect can cause the autodie behaviour to leak
-into the surrounding scope. See L<autodie/"BUGS"> for more details.
-
-=item C<Compress::Raw::Bzip2>
-
-This has been added to the core (version 2.020).
-
-=item C<parent>
-
-This pragma establishes an ISA relationship with base classes at compile
-time. It provides the key feature of C<base> without the feature creep.
-
-=item C<Parse::CPAN::Meta>
-
-This has been added to the core (version 1.39).
-
-=back
-
-=head2 Pragmata Changes
-
-=over 4
-
-=item C<attributes>
-
-Upgraded from version 0.08 to 0.09.
-
-=item C<attrs>
-
-Upgraded from version 1.02 to 1.03.
-
-=item C<base>
-
-Upgraded from version 2.13 to 2.14. See L<parent> for a replacement.
-
-=item C<bigint>
-
-Upgraded from version 0.22 to 0.23.
-
-=item C<bignum>
-
-Upgraded from version 0.22 to 0.23.
-
-=item C<bigrat>
-
-Upgraded from version 0.22 to 0.23.
-
-=item C<charnames>
-
-Upgraded from version 1.06 to 1.07.
-
-The Unicode F<NameAliases.txt> database file has been added. This has the
-effect of adding some extra C<\N> character names that formerly wouldn't
-have been recognised; for example, C<"\N{LATIN CAPITAL LETTER GHA}">.
-
-=item C<constant>
-
-Upgraded from version 1.13 to 1.17.
-
-=item C<feature>
-
-The meaning of the C<:5.10> and C<:5.10.X> feature bundles has
-changed slightly. The last component, if any (i.e. C<X>) is simply ignored.
-This is predicated on the assumption that new features will not, in
-general, be added to maintenance releases. So C<:5.10> and C<:5.10.X>
-have identical effect. This is a change to the behaviour documented for
-5.10.0.
-
-=item C<fields>
-
-Upgraded from version 2.13 to 2.14 (this was just a version bump; there
-were no functional changes).
-
-=item C<lib>
-
-Upgraded from version 0.5565 to 0.62.
-
-=item C<open>
-
-Upgraded from version 1.06 to 1.07.
-
-=item C<overload>
-
-Upgraded from version 1.06 to 1.07.
-
-=item C<overloading>
-
-See L</"The C<overloading> pragma"> above.
-
-=item C<version>
-
-Upgraded from version 0.74 to 0.77.
-
-=back
-
-=head2 Updated Modules
-
-=over 4
-
-=item C<Archive::Extract>
-
-Upgraded from version 0.24 to 0.34.
-
-=item C<Archive::Tar>
-
-Upgraded from version 1.38 to 1.52.
-
-=item C<Attribute::Handlers>
-
-Upgraded from version 0.79 to 0.85.
-
-=item C<AutoLoader>
-
-Upgraded from version 5.63 to 5.68.
-
-=item C<AutoSplit>
-
-Upgraded from version 1.05 to 1.06.
-
-=item C<B>
-
-Upgraded from version 1.17 to 1.22.
-
-=item C<B::Debug>
-
-Upgraded from version 1.05 to 1.11.
-
-=item C<B::Deparse>
-
-Upgraded from version 0.83 to 0.89.
-
-=item C<B::Lint>
-
-Upgraded from version 1.09 to 1.11.
-
-=item C<B::Xref>
-
-Upgraded from version 1.01 to 1.02.
-
-=item C<Benchmark>
-
-Upgraded from version 1.10 to 1.11.
-
-=item C<Carp>
-
-Upgraded from version 1.08 to 1.11.
-
-=item C<CGI>
-
-Upgraded from version 3.29 to 3.43.
-(also includes the "default_value for popup_menu()" fix from 3.45).
-
-=item C<Compress::Zlib>
-
-Upgraded from version 2.008 to 2.020.
-
-=item C<CPAN>
-
-Upgraded from version 1.9205 to 1.9402. C<CPAN::FTP> has a local fix to
-stop it being too verbose on download failure.
-
-=item C<CPANPLUS>
-
-Upgraded from version 0.84 to 0.88.
-
-=item C<CPANPLUS::Dist::Build>
-
-Upgraded from version 0.06_02 to 0.36.
-
-=item C<Cwd>
-
-Upgraded from version 3.25_01 to 3.30.
-
-=item C<Data::Dumper>
-
-Upgraded from version 2.121_14 to 2.124.
-
-=item C<DB>
-
-Upgraded from version 1.01 to 1.02.
-
-=item C<DB_File>
-
-Upgraded from version 1.816_1 to 1.820.
-
-=item C<Devel::PPPort>
-
-Upgraded from version 3.13 to 3.19.
-
-=item C<Digest::MD5>
-
-Upgraded from version 2.36_01 to 2.39.
-
-=item C<Digest::SHA>
-
-Upgraded from version 5.45 to 5.47.
-
-=item C<DirHandle>
-
-Upgraded from version 1.01 to 1.03.
-
-=item C<Dumpvalue>
-
-Upgraded from version 1.12 to 1.13.
-
-=item C<DynaLoader>
-
-Upgraded from version 1.08 to 1.10.
-
-=item C<Encode>
-
-Upgraded from version 2.23 to 2.35.
-
-=item C<Errno>
-
-Upgraded from version 1.10 to 1.11.
-
-=item C<Exporter>
-
-Upgraded from version 5.62 to 5.63.
-
-=item C<ExtUtils::CBuilder>
-
-Upgraded from version 0.21 to 0.2602.
-
-=item C<ExtUtils::Command>
-
-Upgraded from version 1.13 to 1.16.
-
-=item C<ExtUtils::Constant>
-
-Upgraded from 0.20 to 0.22. (Note that neither of these versions are
-available on CPAN.)
-
-=item C<ExtUtils::Embed>
-
-Upgraded from version 1.27 to 1.28.
-
-=item C<ExtUtils::Install>
-
-Upgraded from version 1.44 to 1.54.
-
-=item C<ExtUtils::MakeMaker>
-
-Upgraded from version 6.42 to 6.55_02.
-
-Note that C<ExtUtils::MakeMaker::bytes> and C<ExtUtils::MakeMaker::vmsish>
-have been removed from this distribution.
-
-=item C<ExtUtils::Manifest>
-
-Upgraded from version 1.51_01 to 1.56.
-
-=item C<ExtUtils::ParseXS>
-
-Upgraded from version 2.18_02 to 2.2002.
-
-=item C<Fatal>
-
-Upgraded from version 1.05 to 2.06_01. See also the new pragma C<autodie>.
-
-=item C<File::Basename>
-
-Upgraded from version 2.76 to 2.77.
-
-=item C<File::Compare>
-
-Upgraded from version 1.1005 to 1.1006.
-
-=item C<File::Copy>
-
-Upgraded from version 2.11 to 2.14.
-
-=item C<File::Fetch>
-
-Upgraded from version 0.14 to 0.20.
-
-=item C<File::Find>
-
-Upgraded from version 1.12 to 1.14.
-
-=item C<File::Path>
-
-Upgraded from version 2.04 to 2.07_03.
-
-=item C<File::Spec>
-
-Upgraded from version 3.2501 to 3.30.
-
-=item C<File::stat>
-
-Upgraded from version 1.00 to 1.01.
-
-=item C<File::Temp>
-
-Upgraded from version 0.18 to 0.22.
-
-=item C<FileCache>
-
-Upgraded from version 1.07 to 1.08.
-
-=item C<FileHandle>
-
-Upgraded from version 2.01 to 2.02.
-
-=item C<Filter::Simple>
-
-Upgraded from version 0.82 to 0.84.
-
-=item C<Filter::Util::Call>
-
-Upgraded from version 1.07 to 1.08.
-
-=item C<FindBin>
-
-Upgraded from version 1.49 to 1.50.
-
-=item C<GDBM_File>
-
-Upgraded from version 1.08 to 1.09.
-
-=item C<Getopt::Long>
-
-Upgraded from version 2.37 to 2.38.
-
-=item C<Hash::Util::FieldHash>
-
-Upgraded from version 1.03 to 1.04. This fixes a memory leak.
-
-=item C<I18N::Collate>
-
-Upgraded from version 1.00 to 1.01.
-
-=item C<IO>
-
-Upgraded from version 1.23_01 to 1.25.
-
-This makes non-blocking mode work on Windows in C<IO::Socket::INET>
-[CPAN #43573].
-
-=item C<IO::Compress::*>
-
-Upgraded from version 2.008 to 2.020.
-
-=item C<IO::Dir>
-
-Upgraded from version 1.06 to 1.07.
-
-=item C<IO::Handle>
-
-Upgraded from version 1.27 to 1.28.
-
-=item C<IO::Socket>
-
-Upgraded from version 1.30_01 to 1.31.
-
-=item C<IO::Zlib>
-
-Upgraded from version 1.07 to 1.09.
-
-=item C<IPC::Cmd>
-
-Upgraded from version 0.40_1 to 0.46.
-
-=item C<IPC::Open3>
-
-Upgraded from version 1.02 to 1.04.
-
-=item C<IPC::SysV>
-
-Upgraded from version 1.05 to 2.01.
-
-=item C<lib>
-
-Upgraded from version 0.5565 to 0.62.
-
-=item C<List::Util>
-
-Upgraded from version 1.19 to 1.21.
-
-=item C<Locale::MakeText>
-
-Upgraded from version 1.12 to 1.13.
-
-=item C<Log::Message>
-
-Upgraded from version 0.01 to 0.02.
-
-=item C<Math::BigFloat>
-
-Upgraded from version 1.59 to 1.60.
-
-=item C<Math::BigInt>
-
-Upgraded from version 1.88 to 1.89.
-
-=item C<Math::BigInt::FastCalc>
-
-Upgraded from version 0.16 to 0.19.
-
-=item C<Math::BigRat>
-
-Upgraded from version 0.21 to 0.22.
-
-=item C<Math::Complex>
-
-Upgraded from version 1.37 to 1.56.
-
-=item C<Math::Trig>
-
-Upgraded from version 1.04 to 1.20.
-
-=item C<Memoize>
-
-Upgraded from version 1.01_02 to 1.01_03 (just a minor documentation
-change).
-
-=item C<Module::Build>
-
-Upgraded from version 0.2808_01 to 0.34_02.
-
-=item C<Module::CoreList>
-
-Upgraded from version 2.13 to 2.18. This release no longer contains the
-C<%Module::CoreList::patchlevel> hash.
-
-=item C<Module::Load>
-
-Upgraded from version 0.12 to 0.16.
-
-=item C<Module::Load::Conditional>
-
-Upgraded from version 0.22 to 0.30.
-
-=item C<Module::Loaded>
-
-Upgraded from version 0.01 to 0.02.
-
-=item C<Module::Pluggable>
-
-Upgraded from version 3.6 to 3.9.
-
-=item C<NDBM_File>
-
-Upgraded from version 1.07 to 1.08.
-
-=item C<Net::Ping>
-
-Upgraded from version 2.33 to 2.36.
-
-=item C<NEXT>
-
-Upgraded from version 0.60_01 to 0.64.
-
-=item C<Object::Accessor>
-
-Upgraded from version 0.32 to 0.34.
-
-=item C<OS2::REXX>
-
-Upgraded from version 1.03 to 1.04.
-
-=item C<Package::Constants>
-
-Upgraded from version 0.01 to 0.02.
-
-=item C<PerlIO>
-
-Upgraded from version 1.04 to 1.06.
-
-=item C<PerlIO::via>
-
-Upgraded from version 0.04 to 0.07.
-
-=item C<Pod::Man>
-
-Upgraded from version 2.16 to 2.22.
-
-=item C<Pod::Parser>
-
-Upgraded from version 1.35 to 1.37.
-
-=item C<Pod::Simple>
-
-Upgraded from version 3.05 to 3.07.
-
-=item C<Pod::Text>
-
-Upgraded from version 3.08 to 3.13.
-
-=item C<POSIX>
-
-Upgraded from version 1.13 to 1.17.
-
-=item C<Safe>
-
-Upgraded from 2.12 to 2.18.
-
-=item C<Scalar::Util>
-
-Upgraded from version 1.19 to 1.21.
-
-=item C<SelectSaver>
-
-Upgraded from 1.01 to 1.02.
-
-=item C<SelfLoader>
-
-Upgraded from 1.11 to 1.17.
-
-=item C<Socket>
-
-Upgraded from 1.80 to 1.82.
-
-=item C<Storable>
-
-Upgraded from 2.18 to 2.20.
-
-=item C<Switch>
-
-Upgraded from version 2.13 to 2.14. Please see L</Deprecations>.
-
-=item C<Symbol>
-
-Upgraded from version 1.06 to 1.07.
-
-=item C<Sys::Syslog>
-
-Upgraded from version 0.22 to 0.27.
-
-=item C<Term::ANSIColor>
-
-Upgraded from version 1.12 to 2.00.
-
-=item C<Term::ReadLine>
-
-Upgraded from version 1.03 to 1.04.
-
-=item C<Term::UI>
-
-Upgraded from version 0.18 to 0.20.
-
-=item C<Test::Harness>
-
-Upgraded from version 2.64 to 3.17.
-
-Note that one side-effect of the 2.x to 3.x upgrade is that the
-experimental C<Test::Harness::Straps> module (and its supporting
-C<Assert>, C<Iterator>, C<Point> and C<Results> modules) have been
-removed. If you still need this, then they are available in the
-(unmaintained) C<Test-Harness-Straps> distribution on CPAN.
-
-=item C<Test::Simple>
-
-Upgraded from version 0.72 to 0.92.
-
-=item C<Text::ParseWords>
-
-Upgraded from version 3.26 to 3.27.
-
-=item C<Text::Tabs>
-
-Upgraded from version 2007.1117 to 2009.0305.
-
-=item C<Text::Wrap>
-
-Upgraded from version 2006.1117 to 2009.0305.
-
-=item C<Thread::Queue>
-
-Upgraded from version 2.00 to 2.11.
-
-=item C<Thread::Semaphore>
-
-Upgraded from version 2.01 to 2.09.
-
-=item C<threads>
-
-Upgraded from version 1.67 to 1.72.
-
-=item C<threads::shared>
-
-Upgraded from version 1.14 to 1.29.
-
-=item C<Tie::RefHash>
-
-Upgraded from version 1.37 to 1.38.
-
-=item C<Tie::StdHandle>
-
-This has documentation changes, and has been assigned a version for the
-first time: version 4.2.
-
-=item C<Time::HiRes>
-
-Upgraded from version 1.9711 to 1.9719.
-
-=item C<Time::Local>
-
-Upgraded from version 1.18 to 1.1901.
-
-=item C<Time::Piece>
-
-Upgraded from version 1.12 to 1.15.
-
-=item C<Unicode::Normalize>
-
-Upgraded from version 1.02 to 1.03.
-
-=item C<Unicode::UCD>
-
-Upgraded from version 0.25 to 0.27.
-
-C<charinfo()> now works on Unified CJK code points added to later versions
-of Unicode.
-
-C<casefold()> has new fields returned to provide both a simpler interface
-and previously missing information. The old fields are retained for
-backwards compatibility. Information about Turkic-specific code points is
-now returned.
-
-The documentation has been corrected and expanded.
-
-=item C<UNIVERSAL>
-
-Upgraded from version 1.04 to 1.05.
-
-=item C<Win32>
-
-Upgraded from version 0.34 to 0.39.
-
-=item C<Win32API::File>
-
-Upgraded from version 0.1001_01 to 0.1101.
-
-=item C<XSLoader>
-
-Upgraded from version 0.08 to 0.10.
-
-=back
-
-=head1 Utility Changes
-
-=over 4
-
-=item F<h2ph>
-
-Now looks in C<include-fixed> too, which is a recent addition to gcc's
-search path.
-
-=item F<h2xs>
-
-No longer incorrectly treats enum values like macros (Daniel Burr).
-
-Now handles C++ style constants (C<//>) properly in enums. (A patch from
-Rainer Weikusat was used; Daniel Burr also proposed a similar fix).
-
-=item F<perl5db.pl>
-
-C<LVALUE> subroutines now work under the debugger.
-
-The debugger now correctly handles proxy constant subroutines, and
-subroutine stubs.
-
-=item F<perlthanks>
-
-Perl 5.10.1 adds a new utility F<perlthanks>, which is a variant of
-F<perlbug>, but for sending non-bug-reports to the authors and maintainers
-of Perl. Getting nothing but bug reports can become a bit demoralising:
-we'll see if this changes things.
-
-=back
-
-=head1 New Documentation
-
-=over 4
-
-=item L<perlhaiku>
-
-This contains instructions on how to build perl for the Haiku platform.
-
-=item L<perlmroapi>
-
-This describes the new interface for pluggable Method Resolution Orders.
-
-=item L<perlperf>
-
-This document, by Richard Foley, provides an introduction to the use of
-performance and optimization techniques which can be used with particular
-reference to perl programs.
-
-=item L<perlrepository>
-
-This describes how to access the perl source using the I<git> version
-control system.
-
-=item L<perlthanks>
-
-This describes the new F<perlthanks> utility.
-
-=back
-
-=head1 Changes to Existing Documentation
-
-The various large C<Changes*> files (which listed every change made to perl
-over the last 18 years) have been removed, and replaced by a small file,
-also called C<Changes>, which just explains how that same information may
-be extracted from the git version control system.
-
-The file F<Porting/patching.pod> has been deleted, as it mainly described
-interacting with the old Perforce-based repository, which is now obsolete.
-Information still relevant has been moved to L<perlrepository>.
-
-L<perlapi>, L<perlintern>, L<perlmodlib> and L<perltoc> are now all
-generated at build time, rather than being shipped as part of the release.
-
-=head1 Performance Enhancements
-
-=over 4
-
-=item *
-
-A new internal cache means that C<isa()> will often be faster.
-
-=item *
-
-Under C<use locale>, the locale-relevant information is now cached on
-read-only values, such as the list returned by C<keys %hash>. This makes
-operations such as C<sort keys %hash> in the scope of C<use locale> much
-faster.
-
-=item *
-
-Empty C<DESTROY> methods are no longer called.
-
-=back
-
-=head1 Installation and Configuration Improvements
-
-=head2 F<ext/> reorganisation
-
-The layout of directories in F<ext> has been revised. Specifically, all
-extensions are now flat, and at the top level, with C</> in pathnames
-replaced by C<->, so that F<ext/Data/Dumper/> is now F<ext/Data-Dumper/>,
-etc. The names of the extensions as specified to F<Configure>, and as
-reported by C<%Config::Config> under the keys C<dynamic_ext>,
-C<known_extensions>, C<nonxs_ext> and C<static_ext> have not changed, and
-still use C</>. Hence this change will not have any affect once perl is
-installed. However, C<Attribute::Handlers>, C<Safe> and C<mro> have now
-become extensions in their own right, so if you run F<Configure> with
-options to specify an exact list of extensions to build, you will need to
-change it to account for this.
-
-For 5.10.2, it is planned that many dual-life modules will have been moved
-from F<lib> to F<ext>; again this will have no effect on an installed
-perl, but will matter if you invoke F<Configure> with a pre-canned list of
-extensions to build.
-
-=head2 Configuration improvements
-
-If C<vendorlib> and C<vendorarch> are the same, then they are only added to
-C<@INC> once.
-
-C<$Config{usedevel}> and the C-level C<PERL_USE_DEVEL> are now defined if
-perl is built with C<-Dusedevel>.
-
-F<Configure> will enable use of C<-fstack-protector>, to provide protection
-against stack-smashing attacks, if the compiler supports it.
-
-F<Configure> will now determine the correct prototypes for re-entrant
-functions, and for C<gconvert>, if you are using a C++ compiler rather
-than a C compiler.
-
-On Unix, if you build from a tree containing a git repository, the
-configuration process will note the commit hash you have checked out, for
-display in the output of C<perl -v> and C<perl -V>. Unpushed local commits
-are automatically added to the list of local patches displayed by
-C<perl -V>.
-
-=head2 Compilation improvements
-
-As part of the flattening of F<ext>, all extensions on all platforms are
-built by F<make_ext.pl>. This replaces the Unix-specific
-F<ext/util/make_ext>, VMS-specific F<make_ext.com> and Win32-specific
-F<win32/buildext.pl>.
-
-=head2 Platform Specific Changes
-
-=over 4
-
-=item AIX
-
-Removed F<libbsd> for AIX 5L and 6.1. Only flock() was used from F<libbsd>.
-
-Removed F<libgdbm> for AIX 5L and 6.1. The F<libgdbm> is delivered as an
-optional package with the AIX Toolbox. Unfortunately the 64 bit version
-is broken.
-
-Hints changes mean that AIX 4.2 should work again.
-
-=item Cygwin
-
-On Cygwin we now strip the last number from the DLL. This has been the
-behaviour in the cygwin.com build for years. The hints files have been
-updated.
-
-=item FreeBSD
-
-The hints files now identify the correct threading libraries on FreeBSD 7
-and later.
-
-=item Irix
-
-We now work around a bizarre preprocessor bug in the Irix 6.5 compiler:
-C<cc -E -> unfortunately goes into K&R mode, but C<cc -E file.c> doesn't.
-
-=item Haiku
-
-Patches from the Haiku maintainers have been merged in. Perl should now
-build on Haiku.
-
-=item MirOS BSD
-
-Perl should now build on MirOS BSD.
-
-=item NetBSD
-
-Hints now supports versions 5.*.
-
-=item Stratus VOS
-
-Various changes from Stratus have been merged in.
-
-=item Symbian
-
-There is now support for Symbian S60 3.2 SDK and S60 5.0 SDK.
-
-=item Win32
-
-Improved message window handling means that C<alarm> and C<kill> messages
-will no longer be dropped under race conditions.
-
-=item VMS
-
-Reads from the in-memory temporary files of C<PerlIO::scalar> used to fail
-if C<$/> was set to a numeric reference (to indicate record-style reads).
-This is now fixed.
-
-VMS now supports C<getgrgid>.
-
-Many improvements and cleanups have been made to the VMS file name handling
-and conversion code.
-
-Enabling the C<PERL_VMS_POSIX_EXIT> logical name now encodes a POSIX exit
-status in a VMS condition value for better interaction with GNV's bash
-shell and other utilities that depend on POSIX exit values. See
-L<perlvms/"$?"> for details.
-
-=back
-
-=head1 Selected Bug Fixes
-
-=over 4
-
-=item *
-
-5.10.0 inadvertently disabled an optimisation, which caused a measurable
-performance drop in list assignment, such as is often used to assign
-function parameters from C<@_>. The optimisation has been re-instated, and
-the performance regression fixed.
-
-=item *
-
-Fixed memory leak on C<while (1) { map 1, 1 }> [RT #53038].
-
-=item *
-
-Some potential coredumps in PerlIO fixed [RT #57322,54828].
-
-=item *
-
-The debugger now works with lvalue subroutines.
-
-=item *
-
-The debugger's C<m> command was broken on modules that defined constants
-[RT #61222].
-
-=item *
-
-C<crypt()> and string complement could return tainted values for untainted
-arguments [RT #59998].
-
-=item *
-
-The C<-i.suffix> command-line switch now recreates the file using
-restricted permissions, before changing its mode to match the original
-file. This eliminates a potential race condition [RT #60904].
-
-=item *
-
-On some Unix systems, the value in C<$?> would not have the top bit set
-(C<$? & 128>) even if the child core dumped.
-
-=item *
-
-Under some circumstances, $^R could incorrectly become undefined
-[RT #57042].
-
-=item *
-
-(XS) In various hash functions, passing a pre-computed hash to when the
-key is UTF-8 might result in an incorrect lookup.
-
-=item *
-
-(XS) Including F<XSUB.h> before F<perl.h> gave a compile-time error
-[RT #57176].
-
-=item *
-
-C<< $object->isa('Foo') >> would report false if the package C<Foo> didn't
-exist, even if the object's C<@ISA> contained C<Foo>.
-
-=item *
-
-Various bugs in the new-to 5.10.0 mro code, triggered by manipulating
-C<@ISA>, have been found and fixed.
-
-=item *
-
-Bitwise operations on references could crash the interpreter, e.g.
-C<$x=\$y; $x |= "foo"> [RT #54956].
-
-=item *
-
-Patterns including alternation might be sensitive to the internal UTF-8
-representation, e.g.
-
- my $byte = chr(192);
- my $utf8 = chr(192); utf8::upgrade($utf8);
- $utf8 =~ /$byte|X}/i; # failed in 5.10.0
-
-=item *
-
-Within UTF8-encoded Perl source files (i.e. where C<use utf8> is in
-effect), double-quoted literal strings could be corrupted where a C<\xNN>,
-C<\0NNN> or C<\N{}> is followed by a literal character with ordinal value
-greater than 255 [RT #59908].
-
-=item *
-
-C<B::Deparse> failed to correctly deparse various constructs:
-C<readpipe STRING> [RT #62428], C<CORE::require(STRING)> [RT #62488],
-C<sub foo(_)> [RT #62484].
-
-=item *
-
-Using C<setpgrp()> with no arguments could corrupt the perl stack.
-
-=item *
-
-The block form of C<eval> is now specifically trappable by C<Safe> and
-C<ops>. Previously it was erroneously treated like string C<eval>.
-
-=item *
-
-In 5.10.0, the two characters C<[~> were sometimes parsed as the smart
-match operator (C<~~>) [RT #63854].
-
-=item *
-
-In 5.10.0, the C<*> quantifier in patterns was sometimes treated as
-C<{0,32767}> [RT #60034, #60464]. For example, this match would fail:
-
- ("ab" x 32768) =~ /^(ab)*$/
-
-=item *
-
-C<shmget> was limited to a 32 bit segment size on a 64 bit OS [RT #63924].
-
-=item *
-
-Using C<next> or C<last> to exit a C<given> block no longer produces a
-spurious warning like the following:
-
- Exiting given via last at foo.pl line 123
-
-=item *
-
-On Windows, C<'.\foo'> and C<'..\foo'> were treated differently than
-C<'./foo'> and C<'../foo'> by C<do> and C<require> [RT #63492].
-
-=item *
-
-Assigning a format to a glob could corrupt the format; e.g.:
-
- *bar=*foo{FORMAT}; # foo format now bad
-
-=item *
-
-Attempting to coerce a typeglob to a string or number could cause an
-assertion failure. The correct error message is now generated,
-C<Can't coerce GLOB to I<$type>>.
-
-=item *
-
-Under C<use filetest 'access'>, C<-x> was using the wrong access mode. This
-has been fixed [RT #49003].
-
-=item *
-
-C<length> on a tied scalar that returned a Unicode value would not be
-correct the first time. This has been fixed.
-
-=item *
-
-Using an array C<tie> inside in array C<tie> could SEGV. This has been
-fixed. [RT #51636]
-
-=item *
-
-A race condition inside C<PerlIOStdio_close()> has been identified and
-fixed. This used to cause various threading issues, including SEGVs.
-
-=item *
-
-In C<unpack>, the use of C<()> groups in scalar context was internally
-placing a list on the interpreter's stack, which manifested in various
-ways, including SEGVs. This is now fixed [RT #50256].
-
-=item *
-
-Magic was called twice in C<substr>, C<\&$x>, C<tie $x, $m> and C<chop>.
-These have all been fixed.
-
-=item *
-
-A 5.10.0 optimisation to clear the temporary stack within the implicit
-loop of C<s///ge> has been reverted, as it turned out to be the cause of
-obscure bugs in seemingly unrelated parts of the interpreter [commit
-ef0d4e17921ee3de].
-
-=item *
-
-The line numbers for warnings inside C<elsif> are now correct.
-
-=item *
-
-The C<..> operator now works correctly with ranges whose ends are at or
-close to the values of the smallest and largest integers.
-
-=item *
-
-C<binmode STDIN, ':raw'> could lead to segmentation faults on some platforms.
-This has been fixed [RT #54828].
-
-=item *
-
-An off-by-one error meant that C<index $str, ...> was effectively being
-executed as C<index "$str\0", ...>. This has been fixed [RT #53746].
-
-=item *
-
-Various leaks associated with named captures in regexes have been fixed
-[RT #57024].
-
-=item *
-
-A weak reference to a hash would leak. This was affecting C<DBI>
-[RT #56908].
-
-=item *
-
-Using (?|) in a regex could cause a segfault [RT #59734].
-
-=item *
-
-Use of a UTF-8 C<tr//> within a closure could cause a segfault [RT #61520].
-
-=item *
-
-Calling C<sv_chop()> or otherwise upgrading an SV could result in an
-unaligned 64-bit access on the SPARC architecture [RT #60574].
-
-=item *
-
-In the 5.10.0 release, C<inc_version_list> would incorrectly list
-C<5.10.*> after C<5.8.*>; this affected the C<@INC> search order
-[RT #67628].
-
-=item *
-
-In 5.10.0, C<pack "a*", $tainted_value> returned a non-tainted value
-[RT #52552].
-
-=item *
-
-In 5.10.0, C<printf> and C<sprintf> could produce the fatal error
-C<panic: utf8_mg_pos_cache_update> when printing UTF-8 strings
-[RT #62666].
-
-=item *
-
-In the 5.10.0 release, a dynamically created C<AUTOLOAD> method might be
-missed (method cache issue) [RT #60220,60232].
-
-=item *
-
-In the 5.10.0 release, a combination of C<use feature> and C<//ee> could
-cause a memory leak [RT #63110].
-
-=item *
-
-C<-C> on the shebang (C<#!>) line is once more permitted if it is also
-specified on the command line. C<-C> on the shebang line used to be a
-silent no-op I<if> it was not also on the command line, so perl 5.10.0
-disallowed it, which broke some scripts. Now perl checks whether it is
-also on the command line and only dies if it is not [RT #67880].
-
-=item *
-
-In 5.10.0, certain types of re-entrant regular expression could crash,
-or cause the following assertion failure [RT #60508]:
-
- Assertion rx->sublen >= (s - rx->subbeg) + i failed
-
-
-=back
-
-=head1 New or Changed Diagnostics
-
-=over 4
-
-=item C<panic: sv_chop %s>
-
-This new fatal error occurs when the C routine C<Perl_sv_chop()> was
-passed a position that is not within the scalar's string buffer. This
-could be caused by buggy XS code, and at this point recovery is not
-possible.
-
-=item C<Can't locate package %s for the parents of %s>
-
-This warning has been removed. In general, it only got produced in
-conjunction with other warnings, and removing it allowed an ISA lookup
-optimisation to be added.
-
-=item C<v-string in use/require is non-portable>
-
-This warning has been removed.
-
-=item C<Deep recursion on subroutine "%s">
-
-It is now possible to change the depth threshold for this warning from the
-default of 100, by recompiling the F<perl> binary, setting the C
-pre-processor macro C<PERL_SUB_DEPTH_WARN> to the desired value.
-
-=back
-
-=head1 Changed Internals
-
-=over 4
-
-=item *
-
-The J.R.R. Tolkien quotes at the head of C source file have been checked and
-proper citations added, thanks to a patch from Tom Christiansen.
-
-=item *
-
-C<vcroak()> now accepts a null first argument. In addition, a full audit
-was made of the "not NULL" compiler annotations, and those for several
-other internal functions were corrected.
-
-=item *
-
-New macros C<dSAVEDERRNO>, C<dSAVE_ERRNO>, C<SAVE_ERRNO>, C<RESTORE_ERRNO>
-have been added to formalise the temporary saving of the C<errno>
-variable.
-
-=item *
-
-The function C<Perl_sv_insert_flags> has been added to augment
-C<Perl_sv_insert>.
-
-=item *
-
-The function C<Perl_newSV_type(type)> has been added, equivalent to
-C<Perl_newSV()> followed by C<Perl_sv_upgrade(type)>.
-
-=item *
-
-The function C<Perl_newSVpvn_flags()> has been added, equivalent to
-C<Perl_newSVpvn()> and then performing the action relevant to the flag.
-
-Two flag bits are currently supported.
-
-=over 4
-
-=item C<SVf_UTF8>
-
-This will call C<SvUTF8_on()> for you. (Note that this does not convert an
-sequence of ISO 8859-1 characters to UTF-8). A wrapper, C<newSVpvn_utf8()>
-is available for this.
-
-=item C<SVs_TEMP>
-
-Call C<sv_2mortal()> on the new SV.
-
-=back
-
-There is also a wrapper that takes constant strings, C<newSVpvs_flags()>.
-
-=item *
-
-The function C<Perl_croak_xs_usage> has been added as a wrapper to
-C<Perl_croak>.
-
-=item *
-
-The functions C<PerlIO_find_layer> and C<PerlIO_list_alloc> are now
-exported.
-
-=item *
-
-C<PL_na> has been exterminated from the core code, replaced by local STRLEN
-temporaries, or C<*_nolen()> calls. Either approach is faster than C<PL_na>,
-which is a pointer deference into the interpreter structure under ithreads,
-and a global variable otherwise.
-
-=item *
-
-C<Perl_mg_free()> used to leave freed memory accessible via SvMAGIC() on
-the scalar. It now updates the linked list to remove each piece of magic
-as it is freed.
-
-=item *
-
-Under ithreads, the regex in C<PL_reg_curpm> is now reference counted. This
-eliminates a lot of hackish workarounds to cope with it not being reference
-counted.
-
-=item *
-
-C<Perl_mg_magical()> would sometimes incorrectly turn on C<SvRMAGICAL()>.
-This has been fixed.
-
-=item *
-
-The I<public> IV and NV flags are now not set if the string value has
-trailing "garbage". This behaviour is consistent with not setting the
-public IV or NV flags if the value is out of range for the type.
-
-=item *
-
-SV allocation tracing has been added to the diagnostics enabled by C<-Dm>.
-The tracing can alternatively output via the C<PERL_MEM_LOG> mechanism, if
-that was enabled when the F<perl> binary was compiled.
-
-=item *
-
-Uses of C<Nullav>, C<Nullcv>, C<Nullhv>, C<Nullop>, C<Nullsv> etc have been
-replaced by C<NULL> in the core code, and non-dual-life modules, as C<NULL>
-is clearer to those unfamiliar with the core code.
-
-=item *
-
-A macro C<MUTABLE_PTR(p)> has been added, which on (non-pedantic) gcc will
-not cast away C<const>, returning a C<void *>. Macros C<MUTABLE_SV(av)>,
-C<MUTABLE_SV(cv)> etc build on this, casting to C<AV *> etc without
-casting away C<const>. This allows proper compile-time auditing of
-C<const> correctness in the core, and helped picked up some errors (now
-fixed).
-
-=item *
-
-Macros C<mPUSHs()> and C<mXPUSHs()> have been added, for pushing SVs on the
-stack and mortalizing them.
-
-=item *
-
-Use of the private structure C<mro_meta> has changed slightly. Nothing
-outside the core should be accessing this directly anyway.
-
-=item *
-
-A new tool, C<Porting/expand-macro.pl> has been added, that allows you
-to view how a C preprocessor macro would be expanded when compiled.
-This is handy when trying to decode the macro hell that is the perl
-guts.
-
-=back
-
-=head1 New Tests
-
-Many modules updated from CPAN incorporate new tests.
-
-Several tests that have the potential to hang forever if they fail now
-incorporate a "watchdog" functionality that will kill them after a timeout,
-which helps ensure that C<make test> and C<make test_harness> run to
-completion automatically. (Jerry Hedden).
-
-Some core-specific tests have been added:
-
-=over 4
-
-=item t/comp/retainedlines.t
-
-Check that the debugger can retain source lines from C<eval>.
-
-=item t/io/perlio_fail.t
-
-Check that bad layers fail.
-
-=item t/io/perlio_leaks.t
-
-Check that PerlIO layers are not leaking.
-
-=item t/io/perlio_open.t
-
-Check that certain special forms of open work.
-
-=item t/io/perlio.t
-
-General PerlIO tests.
-
-=item t/io/pvbm.t
-
-Check that there is no unexpected interaction between the internal types
-C<PVBM> and C<PVGV>.
-
-=item t/mro/package_aliases.t
-
-Check that mro works properly in the presence of aliased packages.
-
-=item t/op/dbm.t
-
-Tests for C<dbmopen> and C<dbmclose>.
-
-=item t/op/index_thr.t
-
-Tests for the interaction of C<index> and threads.
-
-=item t/op/pat_thr.t
-
-Tests for the interaction of esoteric patterns and threads.
-
-=item t/op/qr_gc.t
-
-Test that C<qr> doesn't leak.
-
-=item t/op/reg_email_thr.t
-
-Tests for the interaction of regex recursion and threads.
-
-=item t/op/regexp_qr_embed_thr.t
-
-Tests for the interaction of patterns with embedded C<qr//> and threads.
-
-=item t/op/regexp_unicode_prop.t
-
-Tests for Unicode properties in regular expressions.
-
-=item t/op/regexp_unicode_prop_thr.t
-
-Tests for the interaction of Unicode properties and threads.
-
-=item t/op/reg_nc_tie.t
-
-Test the tied methods of C<Tie::Hash::NamedCapture>.
-
-=item t/op/reg_posixcc.t
-
-Check that POSIX character classes behave consistently.
-
-=item t/op/re.t
-
-Check that exportable C<re> functions in F<universal.c> work.
-
-=item t/op/setpgrpstack.t
-
-Check that C<setpgrp> works.
-
-=item t/op/substr_thr.t
-
-Tests for the interaction of C<substr> and threads.
-
-=item t/op/upgrade.t
-
-Check that upgrading and assigning scalars works.
-
-=item t/uni/lex_utf8.t
-
-Check that Unicode in the lexer works.
-
-=item t/uni/tie.t
-
-Check that Unicode and C<tie> work.
-
-=back
-
-=head1 Known Problems
-
-This is a list of some significant unfixed bugs, which are regressions
-from either 5.10.0 or 5.8.x.
-
-=over 4
-
-=item *
-
-C<List::Util::first> misbehaves in the presence of a lexical C<$_>
-(typically introduced by C<my $_> or implicitly by C<given>). The variable
-which gets set for each iteration is the package variable C<$_>, not the
-lexical C<$_> [RT #67694].
-
-A similar issue may occur in other modules that provide functions which
-take a block as their first argument, like
-
- foo { ... $_ ...} list
-
-=item *
-
-The C<charnames> pragma may generate a run-time error when a regex is
-interpolated [RT #56444]:
-
- use charnames ':full';
- my $r1 = qr/\N{THAI CHARACTER SARA I}/;
- "foo" =~ $r1; # okay
- "foo" =~ /$r1+/; # runtime error
-
-A workaround is to generate the character outside of the regex:
-
- my $a = "\N{THAI CHARACTER SARA I}";
- my $r1 = qr/$a/;
-
-=item *
-
-Some regexes may run much more slowly when run in a child thread compared
-with the thread the pattern was compiled into [RT #55600].
-
-
-=back
-
-=head1 Deprecations
-
-The following items are now deprecated.
-
-=over 4
-
-=item *
-
-C<Switch> is buggy and should be avoided. From perl 5.11.0 onwards, it is
-intended that any use of the core version of this module will emit a
-warning, and that the module will eventually be removed from the core
-(probably in perl 5.14.0). See L<perlsyn/"Switch statements"> for its
-replacement.
-
-=item *
-
-C<suidperl> will be removed in 5.12.0. This provides a mechanism to
-emulate setuid permission bits on systems that don't support it properly.
-
-=back
-
-=head1 Acknowledgements
-
-Some of the work in this release was funded by a TPF grant.
-
-Nicholas Clark officially retired from maintenance pumpking duty at the
-end of 2008; however in reality he has put much effort in since then to
-help get 5.10.1 into a fit state to be released, including writing a
-considerable chunk of this perldelta.
-
-Steffen Mueller and David Golden in particular helped getting CPAN modules
-polished and synchronised with their in-core equivalents.
-
-Craig Berry was tireless in getting maint to run under VMS, no matter how
-many times we broke it for him.
-
-The other core committers contributed most of the changes, and applied most
-of the patches sent in by the hundreds of contributors listed in F<AUTHORS>.
-
-(Sorry to all the people I haven't mentioned by name).
-
-Finally, thanks to Larry Wall, without whom none of this would be
-necessary.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://rt.perl.org/perlbug/ . There may also be
-information at http://www.perl.org/ , the Perl Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team.
-
-If the bug you are reporting has security implications, which make it
-inappropriate to send to a publicly archived mailing list, then please send
-it to perl5-security-report@perl.org. This points to a closed subscription
-unarchived mailing list, which includes
-all the core committers, who will be able
-to help assess the impact of issues, figure out a resolution, and help
-co-ordinate the release of patches to mitigate or fix the problem across all
-platforms on which Perl is supported. Please only use this address for
-security issues in the Perl core, not for modules independently
-distributed on CPAN.
-
-=head1 SEE ALSO
-
-The F<Changes> file for an explanation of how to view exhaustive details
-on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl5120delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5120delta.pod
deleted file mode 100644
index f8a1810c861..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl5120delta.pod
+++ /dev/null
@@ -1,3195 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perl5120delta - what is new for perl v5.12.0
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.10.0 release and the
-5.12.0 release.
-
-Many of the bug fixes in 5.12.0 are already included in the 5.10.1
-maintenance release.
-
-You can see the list of those changes in the 5.10.1 release notes
-(L<perl5101delta>).
-
-
-=head1 Core Enhancements
-
-=head2 New C<package NAME VERSION> syntax
-
-This new syntax allows a module author to set the $VERSION of a namespace
-when the namespace is declared with 'package'. It eliminates the need
-for C<our $VERSION = ...> and similar constructs. E.g.
-
- package Foo::Bar 1.23;
- # $Foo::Bar::VERSION == 1.23
-
-There are several advantages to this:
-
-=over
-
-=item *
-
-C<$VERSION> is parsed in exactly the same way as C<use NAME VERSION>
-
-=item *
-
-C<$VERSION> is set at compile time
-
-=item *
-
-C<$VERSION> is a version object that provides proper overloading of
-comparison operators so comparing C<$VERSION> to decimal (1.23) or
-dotted-decimal (v1.2.3) version numbers works correctly.
-
-=item *
-
-Eliminates C<$VERSION = ...> and C<eval $VERSION> clutter
-
-=item *
-
-As it requires VERSION to be a numeric literal or v-string
-literal, it can be statically parsed by toolchain modules
-without C<eval> the way MM-E<gt>parse_version does for C<$VERSION = ...>
-
-=back
-
-It does not break old code with only C<package NAME>, but code that uses
-C<package NAME VERSION> will need to be restricted to perl 5.12.0 or newer
-This is analogous to the change to C<open> from two-args to three-args.
-Users requiring the latest Perl will benefit, and perhaps after several
-years, it will become a standard practice.
-
-
-However, C<package NAME VERSION> requires a new, 'strict' version
-number format. See L<"Version number formats"> for details.
-
-
-=head2 The C<...> operator
-
-A new operator, C<...>, nicknamed the Yada Yada operator, has been added.
-It is intended to mark placeholder code that is not yet implemented.
-See L<perlop/"Yada Yada Operator">.
-
-=head2 Implicit strictures
-
-Using the C<use VERSION> syntax with a version number greater or equal
-to 5.11.0 will lexically enable strictures just like C<use strict>
-would do (in addition to enabling features.) The following:
-
- use 5.12.0;
-
-means:
-
- use strict;
- use feature ':5.12';
-
-=head2 Unicode improvements
-
-Perl 5.12 comes with Unicode 5.2, the latest version available to
-us at the time of release. This version of Unicode was released in
-October 2009. See L<http://www.unicode.org/versions/Unicode5.2.0> for
-further details about what's changed in this version of the standard.
-See L<perlunicode> for instructions on installing and using other versions
-of Unicode.
-
-Additionally, Perl's developers have significantly improved Perl's Unicode
-implementation. For full details, see L</Unicode overhaul> below.
-
-=head2 Y2038 compliance
-
-Perl's core time-related functions are now Y2038 compliant. (It may not mean much to you, but your kids will love it!)
-
-=head2 qr overloading
-
-It is now possible to overload the C<qr//> operator, that is,
-conversion to regexp, like it was already possible to overload
-conversion to boolean, string or number of objects. It is invoked when
-an object appears on the right hand side of the C<=~> operator or when
-it is interpolated into a regexp. See L<overload>.
-
-=head2 Pluggable keywords
-
-Extension modules can now cleanly hook into the Perl parser to define
-new kinds of keyword-headed expression and compound statement. The
-syntax following the keyword is defined entirely by the extension. This
-allow a completely non-Perl sublanguage to be parsed inline, with the
-correct ops cleanly generated.
-
-See L<perlapi/PL_keyword_plugin> for the mechanism. The Perl core
-source distribution also includes a new module
-L<XS::APItest::KeywordRPN>, which implements reverse Polish notation
-arithmetic via pluggable keywords. This module is mainly used for test
-purposes, and is not normally installed, but also serves as an example
-of how to use the new mechanism.
-
-Perl's developers consider this feature to be experimental. We may remove
-it or change it in a backwards-incompatible way in Perl 5.14.
-
-=head2 APIs for more internals
-
-The lowest layers of the lexer and parts of the pad system now have C
-APIs available to XS extensions. These are necessary to support proper
-use of pluggable keywords, but have other uses too. The new APIs are
-experimental, and only cover a small proportion of what would be
-necessary to take full advantage of the core's facilities in these
-areas. It is intended that the Perl 5.13 development cycle will see the
-addition of a full range of clean, supported interfaces.
-
-Perl's developers consider this feature to be experimental. We may remove
-it or change it in a backwards-incompatible way in Perl 5.14.
-
-=head2 Overridable function lookup
-
-Where an extension module hooks the creation of rv2cv ops to modify the
-subroutine lookup process, this now works correctly for bareword
-subroutine calls. This means that prototypes on subroutines referenced
-this way will be processed correctly. (Previously bareword subroutine
-names were initially looked up, for parsing purposes, by an unhookable
-mechanism, so extensions could only properly influence subroutine names
-that appeared with an C<&> sigil.)
-
-=head2 A proper interface for pluggable Method Resolution Orders
-
-As of Perl 5.12.0 there is a new interface for plugging and using method
-resolution orders other than the default linear depth first search.
-The C3 method resolution order added in 5.10.0 has been re-implemented as
-a plugin, without changing its Perl-space interface. See L<perlmroapi> for
-more information.
-
-
-
-=head2 C<\N> experimental regex escape
-
-Perl now supports C<\N>, a new regex escape which you can think of as
-the inverse of C<\n>. It will match any character that is not a newline,
-independently from the presence or absence of the single line match
-modifier C</s>. It is not usable within a character class. C<\N{3}>
-means to match 3 non-newlines; C<\N{5,}> means to match at least 5.
-C<\N{NAME}> still means the character or sequence named C<NAME>, but
-C<NAME> no longer can be things like C<3>, or C<5,>.
-
-This will break a L<custom charnames translator|charnames/CUSTOM
-TRANSLATORS> which allows numbers for character names, as C<\N{3}> will
-now mean to match 3 non-newline characters, and not the character whose
-name is C<3>. (No name defined by the Unicode standard is a number,
-so only custom translators might be affected.)
-
-Perl's developers are somewhat concerned about possible user confusion
-with the existing C<\N{...}> construct which matches characters by their
-Unicode name. Consequently, this feature is experimental. We may remove
-it or change it in a backwards-incompatible way in Perl 5.14.
-
-=head2 DTrace support
-
-Perl now has some support for DTrace. See "DTrace support" in F<INSTALL>.
-
-=head2 Support for C<configure_requires> in CPAN module metadata
-
-Both C<CPAN> and C<CPANPLUS> now support the C<configure_requires>
-keyword in the F<META.yml> metadata file included in most recent CPAN
-distributions. This allows distribution authors to specify configuration
-prerequisites that must be installed before running F<Makefile.PL>
-or F<Build.PL>.
-
-See the documentation for C<ExtUtils::MakeMaker> or C<Module::Build> for
-more on how to specify C<configure_requires> when creating a distribution
-for CPAN.
-
-=head2 C<each>, C<keys>, C<values> are now more flexible
-
-The C<each>, C<keys>, C<values> function can now operate on arrays.
-
-=head2 C<when> as a statement modifier
-
-C<when> is now allowed to be used as a statement modifier.
-
-=head2 C<$,> flexibility
-
-The variable C<$,> may now be tied.
-
-=head2 // in when clauses
-
-// now behaves like || in when clauses
-
-=head2 Enabling warnings from your shell environment
-
-You can now set C<-W> from the C<PERL5OPT> environment variable
-
-=head2 C<delete local>
-
-C<delete local> now allows you to locally delete a hash entry.
-
-=head2 New support for Abstract namespace sockets
-
-Abstract namespace sockets are Linux-specific socket type that live in
-AF_UNIX family, slightly abusing it to be able to use arbitrary
-character arrays as addresses: They start with nul byte and are not
-terminated by nul byte, but with the length passed to the socket()
-system call.
-
-=head2 32-bit limit on substr arguments removed
-
-The 32-bit limit on C<substr> arguments has now been removed. The full
-range of the system's signed and unsigned integers is now available for
-the C<pos> and C<len> arguments.
-
-=head1 Potentially Incompatible Changes
-
-=head2 Deprecations warn by default
-
-Over the years, Perl's developers have deprecated a number of language
-features for a variety of reasons. Perl now defaults to issuing a
-warning if a deprecated language feature is used. Many of the deprecations
-Perl now warns you about have been deprecated for many years. You can
-find a list of what was deprecated in a given release of Perl in the
-C<perl5xxdelta.pod> file for that release.
-
-To disable this feature in a given lexical scope, you should use C<no
-warnings 'deprecated';> For information about which language features
-are deprecated and explanations of various deprecation warnings, please
-see L<perldiag>. See L</Deprecations> below for the list of features
-and modules Perl's developers have deprecated as part of this release.
-
-=head2 Version number formats
-
-Acceptable version number formats have been formalized into "strict" and
-"lax" rules. C<package NAME VERSION> takes a strict version number.
-C<UNIVERSAL::VERSION> and the L<version> object constructors take lax
-version numbers. Providing an invalid version will result in a fatal
-error. The version argument in C<use NAME VERSION> is first parsed as a
-numeric literal or v-string and then passed to C<UNIVERSAL::VERSION>
-(and must then pass the "lax" format test).
-
-These formats are documented fully in the L<version> module. To a first
-approximation, a "strict" version number is a positive decimal number
-(integer or decimal-fraction) without exponentiation or else a
-dotted-decimal v-string with a leading 'v' character and at least three
-components. A "lax" version number allows v-strings with fewer than
-three components or without a leading 'v'. Under "lax" rules, both
-decimal and dotted-decimal versions may have a trailing "alpha"
-component separated by an underscore character after a fractional or
-dotted-decimal component.
-
-The L<version> module adds C<version::is_strict> and C<version::is_lax>
-functions to check a scalar against these rules.
-
-=head2 @INC reorganization
-
-In C<@INC>, C<ARCHLIB> and C<PRIVLIB> now occur after after the current
-version's C<site_perl> and C<vendor_perl>. Modules installed into
-C<site_perl> and C<vendor_perl> will now be loaded in preference to
-those installed in C<ARCHLIB> and C<PRIVLIB>.
-
-
-=head2 REGEXPs are now first class
-
-Internally, Perl now treats compiled regular expressions (such as
-those created with C<qr//>) as first class entities. Perl modules which
-serialize, deserialize or otherwise have deep interaction with Perl's
-internal data structures need to be updated for this change. Most
-affected CPAN modules have already been updated as of this writing.
-
-=head2 Switch statement changes
-
-The C<given>/C<when> switch statement handles complex statements better
-than Perl 5.10.0 did (These enhancements are also available in
-5.10.1 and subsequent 5.10 releases.) There are two new cases where
-C<when> now interprets its argument as a boolean, instead of an
-expression to be used in a smart match:
-
-=over
-
-=item flip-flop operators
-
-The C<..> and C<...> flip-flop operators are now evaluated in boolean
-context, following their usual semantics; see L<perlop/"Range Operators">.
-
-Note that, as in perl 5.10.0, C<when (1..10)> will not work to test
-whether a given value is an integer between 1 and 10; you should use
-C<when ([1..10])> instead (note the array reference).
-
-However, contrary to 5.10.0, evaluating the flip-flop operators in
-boolean context ensures it can now be useful in a C<when()>, notably
-for implementing bistable conditions, like in:
-
- when (/^=begin/ .. /^=end/) {
- # do something
- }
-
-=item defined-or operator
-
-A compound expression involving the defined-or operator, as in
-C<when (expr1 // expr2)>, will be treated as boolean if the first
-expression is boolean. (This just extends the existing rule that applies
-to the regular or operator, as in C<when (expr1 || expr2)>.)
-
-=back
-
-=head2 Smart match changes
-
-Since Perl 5.10.0, Perl's developers have made a number of changes to
-the smart match operator. These, of course, also alter the behaviour
-of the switch statements where smart matching is implicitly used.
-These changes were also made for the 5.10.1 release, and will remain in
-subsequent 5.10 releases.
-
-=head3 Changes to type-based dispatch
-
-The smart match operator C<~~> is no longer commutative. The behaviour of
-a smart match now depends primarily on the type of its right hand
-argument. Moreover, its semantics have been adjusted for greater
-consistency or usefulness in several cases. While the general backwards
-compatibility is maintained, several changes must be noted:
-
-=over 4
-
-=item *
-
-Code references with an empty prototype are no longer treated specially.
-They are passed an argument like the other code references (even if they
-choose to ignore it).
-
-=item *
-
-C<%hash ~~ sub {}> and C<@array ~~ sub {}> now test that the subroutine
-returns a true value for each key of the hash (or element of the
-array), instead of passing the whole hash or array as a reference to
-the subroutine.
-
-=item *
-
-Due to the commutativity breakage, code references are no longer
-treated specially when appearing on the left of the C<~~> operator,
-but like any vulgar scalar.
-
-=item *
-
-C<undef ~~ %hash> is always false (since C<undef> can't be a key in a
-hash). No implicit conversion to C<""> is done (as was the case in perl
-5.10.0).
-
-=item *
-
-C<$scalar ~~ @array> now always distributes the smart match across the
-elements of the array. It's true if one element in @array verifies
-C<$scalar ~~ $element>. This is a generalization of the old behaviour
-that tested whether the array contained the scalar.
-
-=back
-
-The full dispatch table for the smart match operator is given in
-L<perlsyn/"Smart matching in detail">.
-
-=head3 Smart match and overloading
-
-According to the rule of dispatch based on the rightmost argument type,
-when an object overloading C<~~> appears on the right side of the
-operator, the overload routine will always be called (with a 3rd argument
-set to a true value, see L<overload>.) However, when the object will
-appear on the left, the overload routine will be called only when the
-rightmost argument is a simple scalar. This way, distributivity of smart
-match across arrays is not broken, as well as the other behaviours with
-complex types (coderefs, hashes, regexes). Thus, writers of overloading
-routines for smart match mostly need to worry only with comparing
-against a scalar, and possibly with stringification overloading; the
-other common cases will be automatically handled consistently.
-
-C<~~> will now refuse to work on objects that do not overload it (in order
-to avoid relying on the object's underlying structure). (However, if the
-object overloads the stringification or the numification operators, and
-if overload fallback is active, it will be used instead, as usual.)
-
-=head2 Other potentially incompatible changes
-
-=over 4
-
-=item *
-
-The definitions of a number of Unicode properties have changed to match
-those of the current Unicode standard. These are listed above under
-L</Unicode overhaul>. This change may break code that expects the old
-definitions.
-
-=item *
-
-The boolkeys op has moved to the group of hash ops. This breaks binary
-compatibility.
-
-=item *
-
-Filehandles are now always blessed into C<IO::File>.
-
-The previous behaviour was to bless Filehandles into L<FileHandle>
-(an empty proxy class) if it was loaded into memory and otherwise
-to bless them into C<IO::Handle>.
-
-=item *
-
-The semantics of C<use feature :5.10*> have changed slightly.
-See L<"Modules and Pragmata"> for more information.
-
-=item *
-
-Perl's developers now use git, rather than Perforce. This should be
-a purely internal change only relevant to people actively working on
-the core. However, you may see minor difference in perl as a consequence
-of the change. For example in some of details of the output of C<perl
--V>. See L<perlrepository> for more information.
-
-=item *
-
-As part of the C<Test::Harness> 2.x to 3.x upgrade, the experimental
-C<Test::Harness::Straps> module has been removed.
-See L</"Modules and Pragmata"> for more details.
-
-=item *
-
-As part of the C<ExtUtils::MakeMaker> upgrade, the
-C<ExtUtils::MakeMaker::bytes> and C<ExtUtils::MakeMaker::vmsish> modules
-have been removed from this distribution.
-
-=item *
-
-C<Module::CoreList> no longer contains the C<%:patchlevel> hash.
-
-=item *
-
-C<length undef> now returns undef.
-
-=item *
-
-Unsupported private C API functions are now declared "static" to prevent
-leakage to Perl's public API.
-
-=item *
-
-To support the bootstrapping process, F<miniperl> no longer builds with
-UTF-8 support in the regexp engine.
-
-This allows a build to complete with PERL_UNICODE set and a UTF-8 locale.
-Without this there's a bootstrapping problem, as miniperl can't load
-the UTF-8 components of the regexp engine, because they're not yet built.
-
-=item *
-
-F<miniperl>'s @INC is now restricted to just C<-I...>, the split of
-C<$ENV{PERL5LIB}>, and "C<.>"
-
-=item *
-
-A space or a newline is now required after a C<"#line XXX"> directive.
-
-=item *
-
-Tied filehandles now have an additional method EOF which provides the
-EOF type.
-
-=item *
-
-To better match all other flow control statements, C<foreach> may no
-longer be used as an attribute.
-
-=item *
-
-Perl's command-line switch "-P", which was deprecated in version 5.10.0, has
-now been removed. The CPAN module C<< Filter::cpp >> can be used as an
-alternative.
-
-=back
-
-
-=head1 Deprecations
-
-From time to time, Perl's developers find it necessary to deprecate
-features or modules we've previously shipped as part of the core
-distribution. We are well aware of the pain and frustration that a
-backwards-incompatible change to Perl can cause for developers building
-or maintaining software in Perl. You can be sure that when we deprecate
-a functionality or syntax, it isn't a choice we make lightly. Sometimes,
-we choose to deprecate functionality or syntax because it was found to
-be poorly designed or implemented. Sometimes, this is because they're
-holding back other features or causing performance problems. Sometimes,
-the reasons are more complex. Wherever possible, we try to keep deprecated
-functionality available to developers in its previous form for at least
-one major release. So long as a deprecated feature isn't actively
-disrupting our ability to maintain and extend Perl, we'll try to leave
-it in place as long as possible.
-
-The following items are now deprecated:
-
-=over
-
-=item suidperl
-
-C<suidperl> is no longer part of Perl. It used to provide a mechanism to
-emulate setuid permission bits on systems that don't support it properly.
-
-=item Use of C<:=> to mean an empty attribute list
-
-An accident of Perl's parser meant that these constructions were all
-equivalent:
-
- my $pi := 4;
- my $pi : = 4;
- my $pi : = 4;
-
-with the C<:> being treated as the start of an attribute list, which
-ends before the C<=>. As whitespace is not significant here, all are
-parsed as an empty attribute list, hence all the above are equivalent
-to, and better written as
-
- my $pi = 4;
-
-because no attribute processing is done for an empty list.
-
-As is, this meant that C<:=> cannot be used as a new token, without
-silently changing the meaning of existing code. Hence that particular
-form is now deprecated, and will become a syntax error. If it is
-absolutely necessary to have empty attribute lists (for example,
-because of a code generator) then avoid the warning by adding a space
-before the C<=>.
-
-=item C<< UNIVERSAL->import() >>
-
-The method C<< UNIVERSAL->import() >> is now deprecated. Attempting to
-pass import arguments to a C<use UNIVERSAL> statement will result in a
-deprecation warning.
-
-=item Use of "goto" to jump into a construct
-
-Using C<goto> to jump from an outer scope into an inner scope is now
-deprecated. This rare use case was causing problems in the
-implementation of scopes.
-
-=item Custom character names in \N{name} that don't look like names
-
-In C<\N{I<name>}>, I<name> can be just about anything. The standard
-Unicode names have a very limited domain, but a custom name translator
-could create names that are, for example, made up entirely of punctuation
-symbols. It is now deprecated to make names that don't begin with an
-alphabetic character, and aren't alphanumeric or contain other than
-a very few other characters, namely spaces, dashes, parentheses
-and colons. Because of the added meaning of C<\N> (See L</C<\N>
-experimental regex escape>), names that look like curly brace -enclosed
-quantifiers won't work. For example, C<\N{3,4}> now means to match 3 to
-4 non-newlines; before a custom name C<3,4> could have been created.
-
-=item Deprecated Modules
-
-The following modules will be removed from the core distribution in a
-future release, and should be installed from CPAN instead. Distributions
-on CPAN which require these should add them to their prerequisites. The
-core versions of these modules warnings will issue a deprecation warning.
-
-If you ship a packaged version of Perl, either alone or as part of a
-larger system, then you should carefully consider the repercussions of
-core module deprecations. You may want to consider shipping your default
-build of Perl with packages for some or all deprecated modules which
-install into C<vendor> or C<site> perl library directories. This will
-inhibit the deprecation warnings.
-
-Alternatively, you may want to consider patching F<lib/deprecate.pm>
-to provide deprecation warnings specific to your packaging system
-or distribution of Perl, consistent with how your packaging system
-or distribution manages a staged transition from a release where the
-installation of a single package provides the given functionality, to
-a later release where the system administrator needs to know to install
-multiple packages to get that same functionality.
-
-You can silence these deprecation warnings by installing the modules
-in question from CPAN. To install the latest version of all of them,
-just install C<Task::Deprecations::5_12>.
-
-=over
-
-=item L<Class::ISA>
-
-=item L<Pod::Plainer>
-
-=item L<Shell>
-
-=item L<Switch>
-
-Switch is buggy and should be avoided. You may find Perl's new
-C<given>/C<when> feature a suitable replacement. See L<perlsyn/"Switch
-statements"> for more information.
-
-=back
-
-=item Assignment to $[
-
-=item Use of the attribute :locked on subroutines
-
-=item Use of "locked" with the attributes pragma
-
-=item Use of "unique" with the attributes pragma
-
-=item Perl_pmflag
-
-C<Perl_pmflag> is no longer part of Perl's public API. Calling it now
-generates a deprecation warning, and it will be removed in a future
-release. Although listed as part of the API, it was never documented,
-and only ever used in F<toke.c>, and prior to 5.10, F<regcomp.c>. In
-core, it has been replaced by a static function.
-
-=item Numerous Perl 4-era libraries
-
-F<termcap.pl>, F<tainted.pl>, F<stat.pl>, F<shellwords.pl>, F<pwd.pl>,
-F<open3.pl>, F<open2.pl>, F<newgetopt.pl>, F<look.pl>, F<find.pl>,
-F<finddepth.pl>, F<importenv.pl>, F<hostname.pl>, F<getopts.pl>,
-F<getopt.pl>, F<getcwd.pl>, F<flush.pl>, F<fastcwd.pl>, F<exceptions.pl>,
-F<ctime.pl>, F<complete.pl>, F<cacheout.pl>, F<bigrat.pl>, F<bigint.pl>,
-F<bigfloat.pl>, F<assert.pl>, F<abbrev.pl>, F<dotsh.pl>, and
-F<timelocal.pl> are all now deprecated. Earlier, Perl's developers
-intended to remove these libraries from Perl's core for the 5.14.0 release.
-
-During final testing before the release of 5.12.0, several developers
-discovered current production code using these ancient libraries, some
-inside the Perl core itself. Accordingly, the pumpking granted them
-a stay of execution. They will begin to warn about their deprecation
-in the 5.14.0 release and will be removed in the 5.16.0 release.
-
-
-=back
-
-=head1 Unicode overhaul
-
-Perl's developers have made a concerted effort to update Perl to be in
-sync with the latest Unicode standard. Changes for this include:
-
-Perl can now handle every Unicode character property. New documentation,
-L<perluniprops>, lists all available non-Unihan character properties. By
-default, perl does not expose Unihan, deprecated or Unicode-internal
-properties. See below for more details on these; there is also a section
-in the pod listing them, and explaining why they are not exposed.
-
-Perl now fully supports the Unicode compound-style of using C<=>
-and C<:> in writing regular expressions: C<\p{property=value}> and
-C<\p{property:value}> (both of which mean the same thing).
-
-Perl now fully supports the Unicode loose matching rules for text between
-the braces in C<\p{...}> constructs. In addition, Perl allows underscores
-between digits of numbers.
-
-Perl now accepts all the Unicode-defined synonyms for properties and
-property values.
-
-C<qr/\X/>, which matches a Unicode logical character, has
-been expanded to work better with various Asian languages. It
-now is defined as an I<extended grapheme cluster>. (See
-L<http://www.unicode.org/reports/tr29/>). Anything matched previously
-and that made sense will continue to be accepted. Additionally:
-
-=over
-
-=item *
-
-C<\X> will not break apart a C<S<CR LF>> sequence.
-
-=item *
-
-C<\X> will now match a sequence which includes the C<ZWJ> and C<ZWNJ>
-characters.
-
-=item *
-
-C<\X> will now always match at least one character, including an initial
-mark. Marks generally come after a base character, but it is possible in
-Unicode to have them in isolation, and C<\X> will now handle that case,
-for example at the beginning of a line, or after a C<ZWSP>. And this is
-the part where C<\X> doesn't match the things that it used to that don't
-make sense. Formerly, for example, you could have the nonsensical case
-of an accented LF.
-
-=item *
-
-C<\X> will now match a (Korean) Hangul syllable sequence, and the Thai
-and Lao exception cases.
-
-=back
-
-Otherwise, this change should be transparent for the non-affected
-languages.
-
-C<\p{...}> matches using the Canonical_Combining_Class property were
-completely broken in previous releases of Perl. They should now work
-correctly.
-
-Before Perl 5.12, the Unicode C<Decomposition_Type=Compat> property
-and a Perl extension had the same name, which led to neither matching
-all the correct values (with more than 100 mistakes in one, and several
-thousand in the other). The Perl extension has now been renamed to be
-C<Decomposition_Type=Noncanonical> (short: C<dt=noncanon>). It has the
-same meaning as was previously intended, namely the union of all the
-non-canonical Decomposition types, with Unicode C<Compat> being just
-one of those.
-
-C<\p{Decomposition_Type=Canonical}> now includes the Hangul syllables.
-
-C<\p{Uppercase}> and C<\p{Lowercase}> now work as the Unicode standard
-says they should. This means they each match a few more characters than
-they used to.
-
-C<\p{Cntrl}> now matches the same characters as C<\p{Control}>. This
-means it no longer will match Private Use (gc=co), Surrogates (gc=cs),
-nor Format (gc=cf) code points. The Format code points represent the
-biggest possible problem. All but 36 of them are either officially
-deprecated or strongly discouraged from being used. Of those 36, likely
-the most widely used are the soft hyphen (U+00AD), and BOM, ZWSP, ZWNJ,
-WJ, and similar characters, plus bidirectional controls.
-
-C<\p{Alpha}> now matches the same characters as C<\p{Alphabetic}>. Before
-5.12, Perl's definition definition included a number of things that aren't
-really alpha (all marks) while omitting many that were. The definitions
-of C<\p{Alnum}> and C<\p{Word}> depend on Alpha's definition and have
-changed accordingly.
-
-C<\p{Word}> no longer incorrectly matches non-word characters such
-as fractions.
-
-C<\p{Print}> no longer matches the line control characters: Tab, LF,
-CR, FF, VT, and NEL. This brings it in line with standards and the
-documentation.
-
-C<\p{XDigit}> now matches the same characters as C<\p{Hex_Digit}>. This
-means that in addition to the characters it currently matches,
-C<[A-Fa-f0-9]>, it will also match the 22 fullwidth equivalents, for
-example U+FF10: FULLWIDTH DIGIT ZERO.
-
-The Numeric type property has been extended to include the Unihan
-characters.
-
-There is a new Perl extension, the 'Present_In', or simply 'In',
-property. This is an extension of the Unicode Age property, but
-C<\p{In=5.0}> matches any code point whose usage has been determined
-I<as of> Unicode version 5.0. The C<\p{Age=5.0}> only matches code points
-added in I<precisely> version 5.0.
-
-A number of properties now have the correct values for unassigned
-code points. The affected properties are Bidi_Class, East_Asian_Width,
-Joining_Type, Decomposition_Type, Hangul_Syllable_Type, Numeric_Type,
-and Line_Break.
-
-The Default_Ignorable_Code_Point, ID_Continue, and ID_Start properties
-are now up to date with current Unicode definitions.
-
-Earlier versions of Perl erroneously exposed certain properties that
-are supposed to be Unicode internal-only. Use of these in regular
-expressions will now generate, if enabled, a deprecation warning message.
-The properties are: Other_Alphabetic, Other_Default_Ignorable_Code_Point,
-Other_Grapheme_Extend, Other_ID_Continue, Other_ID_Start, Other_Lowercase,
-Other_Math, and Other_Uppercase.
-
-It is now possible to change which Unicode properties Perl understands
-on a per-installation basis. As mentioned above, certain properties
-are turned off by default. These include all the Unihan properties
-(which should be accessible via the CPAN module Unicode::Unihan) and any
-deprecated or Unicode internal-only property that Perl has never exposed.
-
-The generated files in the C<lib/unicore/To> directory are now more
-clearly marked as being stable, directly usable by applications. New hash
-entries in them give the format of the normal entries, which allows for
-easier machine parsing. Perl can generate files in this directory for
-any property, though most are suppressed. You can find instructions
-for changing which are written in L<perluniprops>.
-
-=head1 Modules and Pragmata
-
-=head2 New Modules and Pragmata
-
-=over 4
-
-=item C<autodie>
-
-C<autodie> is a new lexically-scoped alternative for the C<Fatal> module.
-The bundled version is 2.06_01. Note that in this release, using a string
-eval when C<autodie> is in effect can cause the autodie behaviour to leak
-into the surrounding scope. See L<autodie/"BUGS"> for more details.
-
-Version 2.06_01 has been added to the Perl core.
-
-=item C<Compress::Raw::Bzip2>
-
-Version 2.024 has been added to the Perl core.
-
-=item C<overloading>
-
-C<overloading> allows you to lexically disable or enable overloading
-for some or all operations.
-
-Version 0.001 has been added to the Perl core.
-
-=item C<parent>
-
-C<parent> establishes an ISA relationship with base classes at compile
-time. It provides the key feature of C<base> without further unwanted
-behaviors.
-
-Version 0.223 has been added to the Perl core.
-
-=item C<Parse::CPAN::Meta>
-
-Version 1.40 has been added to the Perl core.
-
-=item C<VMS::DCLsym>
-
-Version 1.03 has been added to the Perl core.
-
-=item C<VMS::Stdio>
-
-Version 2.4 has been added to the Perl core.
-
-=item C<XS::APItest::KeywordRPN>
-
-Version 0.003 has been added to the Perl core.
-
-=back
-
-=head2 Updated Pragmata
-
-=over 4
-
-=item C<base>
-
-Upgraded from version 2.13 to 2.15.
-
-=item C<bignum>
-
-Upgraded from version 0.22 to 0.23.
-
-=item C<charnames>
-
-C<charnames> now contains the Unicode F<NameAliases.txt> database file.
-This has the effect of adding some extra C<\N> character names that
-formerly wouldn't have been recognised; for example, C<"\N{LATIN CAPITAL
-LETTER GHA}">.
-
-Upgraded from version 1.06 to 1.07.
-
-=item C<constant>
-
-Upgraded from version 1.13 to 1.20.
-
-=item C<diagnostics>
-
-C<diagnostics> now supports %.0f formatting internally.
-
-C<diagnostics> no longer suppresses C<Use of uninitialized value in range
-(or flip)> warnings. [perl #71204]
-
-Upgraded from version 1.17 to 1.19.
-
-=item C<feature>
-
-In C<feature>, the meaning of the C<:5.10> and C<:5.10.X> feature
-bundles has changed slightly. The last component, if any (i.e. C<X>) is
-simply ignored. This is predicated on the assumption that new features
-will not, in general, be added to maintenance releases. So C<:5.10>
-and C<:5.10.X> have identical effect. This is a change to the behaviour
-documented for 5.10.0.
-
-C<feature> now includes the C<unicode_strings> feature:
-
- use feature "unicode_strings";
-
-This pragma turns on Unicode semantics for the case-changing operations
-(C<uc>, C<lc>, C<ucfirst>, C<lcfirst>) on strings that don't have the
-internal UTF-8 flag set, but that contain single-byte characters between
-128 and 255.
-
-Upgraded from version 1.11 to 1.16.
-
-=item C<less>
-
-C<less> now includes the C<stash_name> method to allow subclasses of
-C<less> to pick where in %^H to store their stash.
-
-Upgraded from version 0.02 to 0.03.
-
-=item C<lib>
-
-Upgraded from version 0.5565 to 0.62.
-
-=item C<mro>
-
-C<mro> is now implemented as an XS extension. The documented interface has
-not changed. Code relying on the implementation detail that some C<mro::>
-methods happened to be available at all times gets to "keep both pieces".
-
-Upgraded from version 1.00 to 1.02.
-
-=item C<overload>
-
-C<overload> now allow overloading of 'qr'.
-
-Upgraded from version 1.06 to 1.10.
-
-=item C<threads>
-
-Upgraded from version 1.67 to 1.75.
-
-=item C<threads::shared>
-
-Upgraded from version 1.14 to 1.32.
-
-=item C<version>
-
-C<version> now has support for L</Version number formats> as described
-earlier in this document and in its own documentation.
-
-Upgraded from version 0.74 to 0.82.
-
-=item C<warnings>
-
-C<warnings> has a new C<warnings::fatal_enabled()> function. It also
-includes a new C<illegalproto> warning category. See also L</New or
-Changed Diagnostics> for this change.
-
-Upgraded from version 1.06 to 1.09.
-
-=back
-
-=head2 Updated Modules
-
-=over 4
-
-=item C<Archive::Extract>
-
-Upgraded from version 0.24 to 0.38.
-
-=item C<Archive::Tar>
-
-Upgraded from version 1.38 to 1.54.
-
-=item C<Attribute::Handlers>
-
-Upgraded from version 0.79 to 0.87.
-
-=item C<AutoLoader>
-
-Upgraded from version 5.63 to 5.70.
-
-=item C<B::Concise>
-
-Upgraded from version 0.74 to 0.78.
-
-=item C<B::Debug>
-
-Upgraded from version 1.05 to 1.12.
-
-=item C<B::Deparse>
-
-Upgraded from version 0.83 to 0.96.
-
-=item C<B::Lint>
-
-Upgraded from version 1.09 to 1.11_01.
-
-=item C<CGI>
-
-Upgraded from version 3.29 to 3.48.
-
-=item C<Class::ISA>
-
-Upgraded from version 0.33 to 0.36.
-
-NOTE: C<Class::ISA> is deprecated and may be removed from a future
-version of Perl.
-
-=item C<Compress::Raw::Zlib>
-
-Upgraded from version 2.008 to 2.024.
-
-=item C<CPAN>
-
-Upgraded from version 1.9205 to 1.94_56.
-
-=item C<CPANPLUS>
-
-Upgraded from version 0.84 to 0.90.
-
-=item C<CPANPLUS::Dist::Build>
-
-Upgraded from version 0.06_02 to 0.46.
-
-=item C<Data::Dumper>
-
-Upgraded from version 2.121_14 to 2.125.
-
-=item C<DB_File>
-
-Upgraded from version 1.816_1 to 1.820.
-
-=item C<Devel::PPPort>
-
-Upgraded from version 3.13 to 3.19.
-
-=item C<Digest>
-
-Upgraded from version 1.15 to 1.16.
-
-=item C<Digest::MD5>
-
-Upgraded from version 2.36_01 to 2.39.
-
-=item C<Digest::SHA>
-
-Upgraded from version 5.45 to 5.47.
-
-=item C<Encode>
-
-Upgraded from version 2.23 to 2.39.
-
-=item C<Exporter>
-
-Upgraded from version 5.62 to 5.64_01.
-
-=item C<ExtUtils::CBuilder>
-
-Upgraded from version 0.21 to 0.27.
-
-=item C<ExtUtils::Command>
-
-Upgraded from version 1.13 to 1.16.
-
-=item C<ExtUtils::Constant>
-
-Upgraded from version 0.2 to 0.22.
-
-=item C<ExtUtils::Install>
-
-Upgraded from version 1.44 to 1.55.
-
-=item C<ExtUtils::MakeMaker>
-
-Upgraded from version 6.42 to 6.56.
-
-=item C<ExtUtils::Manifest>
-
-Upgraded from version 1.51_01 to 1.57.
-
-=item C<ExtUtils::ParseXS>
-
-Upgraded from version 2.18_02 to 2.21.
-
-=item C<File::Fetch>
-
-Upgraded from version 0.14 to 0.24.
-
-=item C<File::Path>
-
-Upgraded from version 2.04 to 2.08_01.
-
-=item C<File::Temp>
-
-Upgraded from version 0.18 to 0.22.
-
-=item C<Filter::Simple>
-
-Upgraded from version 0.82 to 0.84.
-
-=item C<Filter::Util::Call>
-
-Upgraded from version 1.07 to 1.08.
-
-=item C<Getopt::Long>
-
-Upgraded from version 2.37 to 2.38.
-
-=item C<IO>
-
-Upgraded from version 1.23_01 to 1.25_02.
-
-=item C<IO::Zlib>
-
-Upgraded from version 1.07 to 1.10.
-
-=item C<IPC::Cmd>
-
-Upgraded from version 0.40_1 to 0.54.
-
-=item C<IPC::SysV>
-
-Upgraded from version 1.05 to 2.01.
-
-=item C<Locale::Maketext>
-
-Upgraded from version 1.12 to 1.14.
-
-=item C<Locale::Maketext::Simple>
-
-Upgraded from version 0.18 to 0.21.
-
-=item C<Log::Message>
-
-Upgraded from version 0.01 to 0.02.
-
-=item C<Log::Message::Simple>
-
-Upgraded from version 0.04 to 0.06.
-
-=item C<Math::BigInt>
-
-Upgraded from version 1.88 to 1.89_01.
-
-=item C<Math::BigInt::FastCalc>
-
-Upgraded from version 0.16 to 0.19.
-
-=item C<Math::BigRat>
-
-Upgraded from version 0.21 to 0.24.
-
-=item C<Math::Complex>
-
-Upgraded from version 1.37 to 1.56.
-
-=item C<Memoize>
-
-Upgraded from version 1.01_02 to 1.01_03.
-
-=item C<MIME::Base64>
-
-Upgraded from version 3.07_01 to 3.08.
-
-=item C<Module::Build>
-
-Upgraded from version 0.2808_01 to 0.3603.
-
-=item C<Module::CoreList>
-
-Upgraded from version 2.12 to 2.29.
-
-=item C<Module::Load>
-
-Upgraded from version 0.12 to 0.16.
-
-=item C<Module::Load::Conditional>
-
-Upgraded from version 0.22 to 0.34.
-
-=item C<Module::Loaded>
-
-Upgraded from version 0.01 to 0.06.
-
-=item C<Module::Pluggable>
-
-Upgraded from version 3.6 to 3.9.
-
-=item C<Net::Ping>
-
-Upgraded from version 2.33 to 2.36.
-
-=item C<NEXT>
-
-Upgraded from version 0.60_01 to 0.64.
-
-=item C<Object::Accessor>
-
-Upgraded from version 0.32 to 0.36.
-
-=item C<Package::Constants>
-
-Upgraded from version 0.01 to 0.02.
-
-=item C<PerlIO>
-
-Upgraded from version 1.04 to 1.06.
-
-=item C<Pod::Parser>
-
-Upgraded from version 1.35 to 1.37.
-
-=item C<Pod::Perldoc>
-
-Upgraded from version 3.14_02 to 3.15_02.
-
-=item C<Pod::Plainer>
-
-Upgraded from version 0.01 to 1.02.
-
-NOTE: C<Pod::Plainer> is deprecated and may be removed from a future
-version of Perl.
-
-=item C<Pod::Simple>
-
-Upgraded from version 3.05 to 3.13.
-
-=item C<Safe>
-
-Upgraded from version 2.12 to 2.22.
-
-=item C<SelfLoader>
-
-Upgraded from version 1.11 to 1.17.
-
-=item C<Storable>
-
-Upgraded from version 2.18 to 2.22.
-
-=item C<Switch>
-
-Upgraded from version 2.13 to 2.16.
-
-NOTE: C<Switch> is deprecated and may be removed from a future version
-of Perl.
-
-=item C<Sys::Syslog>
-
-Upgraded from version 0.22 to 0.27.
-
-=item C<Term::ANSIColor>
-
-Upgraded from version 1.12 to 2.02.
-
-=item C<Term::UI>
-
-Upgraded from version 0.18 to 0.20.
-
-=item C<Test>
-
-Upgraded from version 1.25 to 1.25_02.
-
-=item C<Test::Harness>
-
-Upgraded from version 2.64 to 3.17.
-
-=item C<Test::Simple>
-
-Upgraded from version 0.72 to 0.94.
-
-=item C<Text::Balanced>
-
-Upgraded from version 2.0.0 to 2.02.
-
-=item C<Text::ParseWords>
-
-Upgraded from version 3.26 to 3.27.
-
-=item C<Text::Soundex>
-
-Upgraded from version 3.03 to 3.03_01.
-
-=item C<Thread::Queue>
-
-Upgraded from version 2.00 to 2.11.
-
-=item C<Thread::Semaphore>
-
-Upgraded from version 2.01 to 2.09.
-
-=item C<Tie::RefHash>
-
-Upgraded from version 1.37 to 1.38.
-
-=item C<Time::HiRes>
-
-Upgraded from version 1.9711 to 1.9719.
-
-=item C<Time::Local>
-
-Upgraded from version 1.18 to 1.1901_01.
-
-=item C<Time::Piece>
-
-Upgraded from version 1.12 to 1.15.
-
-=item C<Unicode::Collate>
-
-Upgraded from version 0.52 to 0.52_01.
-
-=item C<Unicode::Normalize>
-
-Upgraded from version 1.02 to 1.03.
-
-=item C<Win32>
-
-Upgraded from version 0.34 to 0.39.
-
-=item C<Win32API::File>
-
-Upgraded from version 0.1001_01 to 0.1101.
-
-=item C<XSLoader>
-
-Upgraded from version 0.08 to 0.10.
-
-=back
-
-=head2 Removed Modules and Pragmata
-
-=over 4
-
-=item C<attrs>
-
-Removed from the Perl core. Prior version was 1.02.
-
-=item C<CPAN::API::HOWTO>
-
-Removed from the Perl core. Prior version was 'undef'.
-
-=item C<CPAN::DeferedCode>
-
-Removed from the Perl core. Prior version was 5.50.
-
-=item C<CPANPLUS::inc>
-
-Removed from the Perl core. Prior version was 'undef'.
-
-=item C<DCLsym>
-
-Removed from the Perl core. Prior version was 1.03.
-
-=item C<ExtUtils::MakeMaker::bytes>
-
-Removed from the Perl core. Prior version was 6.42.
-
-=item C<ExtUtils::MakeMaker::vmsish>
-
-Removed from the Perl core. Prior version was 6.42.
-
-=item C<Stdio>
-
-Removed from the Perl core. Prior version was 2.3.
-
-=item C<Test::Harness::Assert>
-
-Removed from the Perl core. Prior version was 0.02.
-
-=item C<Test::Harness::Iterator>
-
-Removed from the Perl core. Prior version was 0.02.
-
-=item C<Test::Harness::Point>
-
-Removed from the Perl core. Prior version was 0.01.
-
-=item C<Test::Harness::Results>
-
-Removed from the Perl core. Prior version was 0.01.
-
-=item C<Test::Harness::Straps>
-
-Removed from the Perl core. Prior version was 0.26_01.
-
-=item C<Test::Harness::Util>
-
-Removed from the Perl core. Prior version was 0.01.
-
-=item C<XSSymSet>
-
-Removed from the Perl core. Prior version was 1.1.
-
-=back
-
-=head2 Deprecated Modules and Pragmata
-
-See L</Deprecated Modules> above.
-
-
-=head1 Documentation
-
-=head2 New Documentation
-
-=over 4
-
-=item *
-
-L<perlhaiku> contains instructions on how to build perl for the Haiku
-platform.
-
-=item *
-
-L<perlmroapi> describes the new interface for pluggable Method Resolution
-Orders.
-
-=item *
-
-L<perlperf>, by Richard Foley, provides an introduction to the use of
-performance and optimization techniques which can be used with particular
-reference to perl programs.
-
-=item *
-
-L<perlrepository> describes how to access the perl source using the I<git>
-version control system.
-
-=item *
-
-L<perlpolicy> extends the "Social contract about contributed modules" into
-the beginnings of a document on Perl porting policies.
-
-=back
-
-=head2 Changes to Existing Documentation
-
-
-=over
-
-=item *
-
-The various large F<Changes*> files (which listed every change made
-to perl over the last 18 years) have been removed, and replaced by a
-small file, also called F<Changes>, which just explains how that same
-information may be extracted from the git version control system.
-
-=item *
-
-F<Porting/patching.pod> has been deleted, as it mainly described
-interacting with the old Perforce-based repository, which is now obsolete.
-Information still relevant has been moved to L<perlrepository>.
-
-=item *
-
-The syntax C<unless (EXPR) BLOCK else BLOCK> is now documented as valid,
-as is the syntax C<unless (EXPR) BLOCK elsif (EXPR) BLOCK ... else
-BLOCK>, although actually using the latter may not be the best idea for
-the readability of your source code.
-
-=item *
-
-Documented -X overloading.
-
-=item *
-
-Documented that C<when()> treats specially most of the filetest operators
-
-=item *
-
-Documented C<when> as a syntax modifier.
-
-=item *
-
-Eliminated "Old Perl threads tutorial", which described 5005 threads.
-
-F<pod/perlthrtut.pod> is the same material reworked for ithreads.
-
-=item *
-
-Correct previous documentation: v-strings are not deprecated
-
-With version objects, we need them to use MODULE VERSION syntax. This
-patch removes the deprecation notice.
-
-=item *
-
-Security contact information is now part of L<perlsec>.
-
-=item *
-
-A significant fraction of the core documentation has been updated to
-clarify the behavior of Perl's Unicode handling.
-
-Much of the remaining core documentation has been reviewed and edited
-for clarity, consistent use of language, and to fix the spelling of Tom
-Christiansen's name.
-
-=item *
-
-The Pod specification (L<perlpodspec>) has been updated to bring the
-specification in line with modern usage already supported by most Pod
-systems. A parameter string may now follow the format name in a
-"begin/end" region. Links to URIs with a text description are now
-allowed. The usage of C<LE<lt>"section"E<gt>> has been marked as
-deprecated.
-
-=item *
-
-L<if.pm|if> has been documented in L<perlfunc/use> as a means to get
-conditional loading of modules despite the implicit BEGIN block around
-C<use>.
-
-=item *
-
-The documentation for C<$1> in perlvar.pod has been clarified.
-
-=item *
-
-C<\N{U+I<code point>}> is now documented.
-
-=back
-
-=head1 Selected Performance Enhancements
-
-=over 4
-
-=item *
-
-A new internal cache means that C<isa()> will often be faster.
-
-=item *
-
-The implementation of C<C3> Method Resolution Order has been
-optimised - linearisation for classes with single inheritance is 40%
-faster. Performance for multiple inheritance is unchanged.
-
-=item *
-
-Under C<use locale>, the locale-relevant information is now cached on
-read-only values, such as the list returned by C<keys %hash>. This makes
-operations such as C<sort keys %hash> in the scope of C<use locale>
-much faster.
-
-=item *
-
-Empty C<DESTROY> methods are no longer called.
-
-=item *
-
-C<Perl_sv_utf8_upgrade()> is now faster.
-
-=item *
-
-C<keys> on empty hash is now faster.
-
-=item *
-
-C<if (%foo)> has been optimized to be faster than C<if (keys %foo)>.
-
-=item *
-
-The string repetition operator (C<$str x $num>) is now several times
-faster when C<$str> has length one or C<$num> is large.
-
-=item *
-
-Reversing an array to itself (as in C<@a = reverse @a>) in void context
-now happens in-place and is several orders of magnitude faster than
-it used to be. It will also preserve non-existent elements whenever
-possible, i.e. for non magical arrays or tied arrays with C<EXISTS>
-and C<DELETE> methods.
-
-=back
-
-=head1 Installation and Configuration Improvements
-
-=over 4
-
-=item *
-
-L<perlapi>, L<perlintern>, L<perlmodlib> and L<perltoc> are now all
-generated at build time, rather than being shipped as part of the release.
-
-=item *
-
-If C<vendorlib> and C<vendorarch> are the same, then they are only added
-to C<@INC> once.
-
-=item *
-
-C<$Config{usedevel}> and the C-level C<PERL_USE_DEVEL> are now defined if
-perl is built with C<-Dusedevel>.
-
-=item *
-
-F<Configure> will enable use of C<-fstack-protector>, to provide protection
-against stack-smashing attacks, if the compiler supports it.
-
-=item *
-
-F<Configure> will now determine the correct prototypes for re-entrant
-functions and for C<gconvert> if you are using a C++ compiler rather
-than a C compiler.
-
-=item *
-
-On Unix, if you build from a tree containing a git repository, the
-configuration process will note the commit hash you have checked out, for
-display in the output of C<perl -v> and C<perl -V>. Unpushed local commits
-are automatically added to the list of local patches displayed by
-C<perl -V>.
-
-=item *
-
-Perl now supports SystemTap's C<dtrace> compatibility layer and an
-issue with linking C<miniperl> has been fixed in the process.
-
-=item *
-
-perldoc now uses C<less -R> instead of C<less> for improved behaviour
-in the face of C<groff>'s new usage of ANSI escape codes.
-
-=item *
-
-
-C<perl -V> now reports use of the compile-time options C<USE_PERL_ATOF> and
-C<USE_ATTRIBUTES_FOR_PERLIO>.
-
-=item *
-
-As part of the flattening of F<ext>, all extensions on all platforms are
-built by F<make_ext.pl>. This replaces the Unix-specific
-F<ext/util/make_ext>, VMS-specific F<make_ext.com> and Win32-specific
-F<win32/buildext.pl>.
-
-=back
-
-=head1 Internal Changes
-
-Each release of Perl sees numerous internal changes which shouldn't
-affect day to day usage but may still be notable for developers working
-with Perl's source code.
-
-=over
-
-=item *
-
-The J.R.R. Tolkien quotes at the head of C source file have been checked
-and proper citations added, thanks to a patch from Tom Christiansen.
-
-=item *
-
-The internal structure of the dual-life modules traditionally found in
-the F<lib/> and F<ext/> directories in the perl source has changed
-significantly. Where possible, dual-lifed modules have been extracted
-from F<lib/> and F<ext/>.
-
-Dual-lifed modules maintained by Perl's developers as part of the Perl
-core now live in F<dist/>. Dual-lifed modules maintained primarily on
-CPAN now live in F<cpan/>. When reporting a bug in a module located
-under F<cpan/>, please send your bug report directly to the module's
-bug tracker or author, rather than Perl's bug tracker.
-
-=item *
-
-C<\N{...}> now compiles better, always forces UTF-8 internal representation
-
-Perl's developers have fixed several problems with the recognition of
-C<\N{...}> constructs. As part of this, perl will store any scalar
-or regex containing C<\N{I<name>}> or C<\N{U+I<code point>}> in its
-definition in UTF-8 format. (This was true previously for all occurrences
-of C<\N{I<name>}> that did not use a custom translator, but now it's
-always true.)
-
-=item *
-
-Perl_magic_setmglob now knows about globs, fixing RT #71254.
-
-=item *
-
-C<SVt_RV> no longer exists. RVs are now stored in IVs.
-
-=item *
-
-C<Perl_vcroak()> now accepts a null first argument. In addition, a full
-audit was made of the "not NULL" compiler annotations, and those for
-several other internal functions were corrected.
-
-=item *
-
-New macros C<dSAVEDERRNO>, C<dSAVE_ERRNO>, C<SAVE_ERRNO>, C<RESTORE_ERRNO>
-have been added to formalise the temporary saving of the C<errno>
-variable.
-
-=item *
-
-The function C<Perl_sv_insert_flags> has been added to augment
-C<Perl_sv_insert>.
-
-=item *
-
-The function C<Perl_newSV_type(type)> has been added, equivalent to
-C<Perl_newSV()> followed by C<Perl_sv_upgrade(type)>.
-
-=item *
-
-The function C<Perl_newSVpvn_flags()> has been added, equivalent to
-C<Perl_newSVpvn()> and then performing the action relevant to the flag.
-
-Two flag bits are currently supported.
-
-=over 4
-
-=item *
-
-C<SVf_UTF8> will call C<SvUTF8_on()> for you. (Note that this does
-not convert an sequence of ISO 8859-1 characters to UTF-8). A wrapper,
-C<newSVpvn_utf8()> is available for this.
-
-=item *
-
-C<SVs_TEMP> now calls C<Perl_sv_2mortal()> on the new SV.
-
-=back
-
-There is also a wrapper that takes constant strings, C<newSVpvs_flags()>.
-
-=item *
-
-The function C<Perl_croak_xs_usage> has been added as a wrapper to
-C<Perl_croak>.
-
-=item *
-
-Perl now exports the functions C<PerlIO_find_layer> and C<PerlIO_list_alloc>.
-
-=item *
-
-C<PL_na> has been exterminated from the core code, replaced by local
-STRLEN temporaries, or C<*_nolen()> calls. Either approach is faster than
-C<PL_na>, which is a pointer dereference into the interpreter structure
-under ithreads, and a global variable otherwise.
-
-=item *
-
-C<Perl_mg_free()> used to leave freed memory accessible via C<SvMAGIC()>
-on the scalar. It now updates the linked list to remove each piece of
-magic as it is freed.
-
-=item *
-
-Under ithreads, the regex in C<PL_reg_curpm> is now reference
-counted. This eliminates a lot of hackish workarounds to cope with it
-not being reference counted.
-
-=item *
-
-C<Perl_mg_magical()> would sometimes incorrectly turn on C<SvRMAGICAL()>.
-This has been fixed.
-
-=item *
-
-The I<public> IV and NV flags are now not set if the string value has
-trailing "garbage". This behaviour is consistent with not setting the
-public IV or NV flags if the value is out of range for the type.
-
-=item *
-
-Uses of C<Nullav>, C<Nullcv>, C<Nullhv>, C<Nullop>, C<Nullsv> etc have
-been replaced by C<NULL> in the core code, and non-dual-life modules,
-as C<NULL> is clearer to those unfamiliar with the core code.
-
-=item *
-
-A macro C<MUTABLE_PTR(p)> has been added, which on (non-pedantic) gcc will
-not cast away C<const>, returning a C<void *>. Macros C<MUTABLE_SV(av)>,
-C<MUTABLE_SV(cv)> etc build on this, casting to C<AV *> etc without
-casting away C<const>. This allows proper compile-time auditing of
-C<const> correctness in the core, and helped picked up some errors
-(now fixed).
-
-=item *
-
-Macros C<mPUSHs()> and C<mXPUSHs()> have been added, for pushing SVs on the
-stack and mortalizing them.
-
-=item *
-
-Use of the private structure C<mro_meta> has changed slightly. Nothing
-outside the core should be accessing this directly anyway.
-
-=item *
-
-A new tool, F<Porting/expand-macro.pl> has been added, that allows you
-to view how a C preprocessor macro would be expanded when compiled.
-This is handy when trying to decode the macro hell that is the perl
-guts.
-
-=back
-
-=head1 Testing
-
-=head2 Testing improvements
-
-=over 4
-
-=item Parallel tests
-
-The core distribution can now run its regression tests in parallel on
-Unix-like platforms. Instead of running C<make test>, set C<TEST_JOBS> in
-your environment to the number of tests to run in parallel, and run
-C<make test_harness>. On a Bourne-like shell, this can be done as
-
- TEST_JOBS=3 make test_harness # Run 3 tests in parallel
-
-An environment variable is used, rather than parallel make itself, because
-L<TAP::Harness> needs to be able to schedule individual non-conflicting test
-scripts itself, and there is no standard interface to C<make> utilities to
-interact with their job schedulers.
-
-Note that currently some test scripts may fail when run in parallel (most
-notably C<ext/IO/t/io_dir.t>). If necessary run just the failing scripts
-again sequentially and see if the failures go away.
-
-=item Test harness flexibility
-
-It's now possible to override C<PERL5OPT> and friends in F<t/TEST>
-
-=item Test watchdog
-
-Several tests that have the potential to hang forever if they fail now
-incorporate a "watchdog" functionality that will kill them after a timeout,
-which helps ensure that C<make test> and C<make test_harness> run to
-completion automatically.
-
-
-=back
-
-=head2 New Tests
-
-Perl's developers have added a number of new tests to the core.
-In addition to the items listed below, many modules updated from CPAN
-incorporate new tests.
-
-=over 4
-
-=item *
-
-Significant cleanups to core tests to ensure that language and
-interpreter features are not used before they're tested.
-
-=item *
-
-C<make test_porting> now runs a number of important pre-commit checks
-which might be of use to anyone working on the Perl core.
-
-=item *
-
-F<t/porting/podcheck.t> automatically checks the well-formedness of
-POD found in all .pl, .pm and .pod files in the F<MANIFEST>, other than in
-dual-lifed modules which are primarily maintained outside the Perl core.
-
-=item *
-
-F<t/porting/manifest.t> now tests that all files listed in MANIFEST
-are present.
-
-=item *
-
-F<t/op/while_readdir.t> tests that a bare readdir in while loop sets $_.
-
-=item *
-
-F<t/comp/retainedlines.t> checks that the debugger can retain source
-lines from C<eval>.
-
-=item *
-
-F<t/io/perlio_fail.t> checks that bad layers fail.
-
-=item *
-
-F<t/io/perlio_leaks.t> checks that PerlIO layers are not leaking.
-
-=item *
-
-F<t/io/perlio_open.t> checks that certain special forms of open work.
-
-=item *
-
-F<t/io/perlio.t> includes general PerlIO tests.
-
-=item *
-
-F<t/io/pvbm.t> checks that there is no unexpected interaction between
-the internal types C<PVBM> and C<PVGV>.
-
-=item *
-
-F<t/mro/package_aliases.t> checks that mro works properly in the presence
-of aliased packages.
-
-=item *
-
-F<t/op/dbm.t> tests C<dbmopen> and C<dbmclose>.
-
-=item *
-
-F<t/op/index_thr.t> tests the interaction of C<index> and threads.
-
-=item *
-
-F<t/op/pat_thr.t> tests the interaction of esoteric patterns and threads.
-
-=item *
-
-F<t/op/qr_gc.t> tests that C<qr> doesn't leak.
-
-=item *
-
-F<t/op/reg_email_thr.t> tests the interaction of regex recursion and threads.
-
-=item *
-
-F<t/op/regexp_qr_embed_thr.t> tests the interaction of patterns with
-embedded C<qr//> and threads.
-
-=item *
-
-F<t/op/regexp_unicode_prop.t> tests Unicode properties in regular
-expressions.
-
-=item *
-
-F<t/op/regexp_unicode_prop_thr.t> tests the interaction of Unicode
-properties and threads.
-
-=item *
-
-F<t/op/reg_nc_tie.t> tests the tied methods of C<Tie::Hash::NamedCapture>.
-
-=item *
-
-F<t/op/reg_posixcc.t> checks that POSIX character classes behave
-consistently.
-
-=item *
-
-F<t/op/re.t> checks that exportable C<re> functions in F<universal.c> work.
-
-=item *
-
-F<t/op/setpgrpstack.t> checks that C<setpgrp> works.
-
-=item *
-
-F<t/op/substr_thr.t> tests the interaction of C<substr> and threads.
-
-=item *
-
-F<t/op/upgrade.t> checks that upgrading and assigning scalars works.
-
-=item *
-
-F<t/uni/lex_utf8.t> checks that Unicode in the lexer works.
-
-=item *
-
-F<t/uni/tie.t> checks that Unicode and C<tie> work.
-
-=item *
-
-F<t/comp/final_line_num.t> tests whether line numbers are correct at EOF
-
-=item *
-
-F<t/comp/form_scope.t> tests format scoping.
-
-=item *
-
-F<t/comp/line_debug.t> tests whether C<< @{"_<$file"} >> works.
-
-=item *
-
-F<t/op/filetest_t.t> tests if -t file test works.
-
-=item *
-
-F<t/op/qr.t> tests C<qr>.
-
-=item *
-
-F<t/op/utf8cache.t> tests malfunctions of the utf8 cache.
-
-=item *
-
-F<t/re/uniprops.t> test unicodes C<\p{}> regex constructs.
-
-=item *
-
-F<t/op/filehandle.t> tests some suitably portable filetest operators
-to check that they work as expected, particularly in the light of some
-internal changes made in how filehandles are blessed.
-
-=item *
-
-F<t/op/time_loop.t> tests that unix times greater than C<2**63>, which
-can now be handed to C<gmtime> and C<localtime>, do not cause an internal
-overflow or an excessively long loop.
-
-=back
-
-
-=head1 New or Changed Diagnostics
-
-=head2 New Diagnostics
-
-=over
-
-=item *
-
-SV allocation tracing has been added to the diagnostics enabled by C<-Dm>.
-The tracing can alternatively output via the C<PERL_MEM_LOG> mechanism, if
-that was enabled when the F<perl> binary was compiled.
-
-=item *
-
-Smartmatch resolution tracing has been added as a new diagnostic. Use
-C<-DM> to enable it.
-
-=item *
-
-A new debugging flag C<-DB> now dumps subroutine definitions, leaving
-C<-Dx> for its original purpose of dumping syntax trees.
-
-=item *
-
-Perl 5.12 provides a number of new diagnostic messages to help you write
-better code. See L<perldiag> for details of these new messages.
-
-=over 4
-
-=item *
-
-C<Bad plugin affecting keyword '%s'>
-
-=item *
-
-C<gmtime(%.0f) too large>
-
-=item *
-
-C<Lexing code attempted to stuff non-Latin-1 character into Latin-1 input>
-
-=item *
-
-C<Lexing code internal error (%s)>
-
-=item *
-
-C<localtime(%.0f) too large>
-
-=item *
-
-C<Overloaded dereference did not return a reference>
-
-=item *
-
-C<Overloaded qr did not return a REGEXP>
-
-=item *
-
-C<Perl_pmflag() is deprecated, and will be removed from the XS API>
-
-=item *
-
-C<lvalue attribute ignored after the subroutine has been defined>
-
-This new warning is issued when one attempts to mark a subroutine as
-lvalue after it has been defined.
-
-=item *
-
-Perl now warns you if C<++> or C<--> are unable to change the value
-because it's beyond the limit of representation.
-
-This uses a new warnings category: "imprecision".
-
-=item *
-
-C<lc>, C<uc>, C<lcfirst>, and C<ucfirst> warn when passed undef.
-
-=item *
-
-C<Show constant in "Useless use of a constant in void context">
-
-=item *
-
-C<Prototype after '%s'>
-
-=item *
-
-C<panic: sv_chop %s>
-
-This new fatal error occurs when the C routine C<Perl_sv_chop()> was
-passed a position that is not within the scalar's string buffer. This
-could be caused by buggy XS code, and at this point recovery is not
-possible.
-
-=item *
-
-The fatal error C<Malformed UTF-8 returned by \N> is now produced if the
-C<charnames> handler returns malformed UTF-8.
-
-=item *
-
-If an unresolved named character or sequence was encountered when
-compiling a regex pattern then the fatal error C<\N{NAME} must be resolved
-by the lexer> is now produced. This can happen, for example, when using a
-single-quotish context like C<$re = '\N{SPACE}'; /$re/;>. See L<perldiag>
-for more examples of how the lexer can get bypassed.
-
-=item *
-
-C<Invalid hexadecimal number in \N{U+...}> is a new fatal error
-triggered when the character constant represented by C<...> is not a
-valid hexadecimal number.
-
-=item *
-
-The new meaning of C<\N> as C<[^\n]> is not valid in a bracketed character
-class, just like C<.> in a character class loses its special meaning,
-and will cause the fatal error C<\N in a character class must be a named
-character: \N{...}>.
-
-=item *
-
-The rules on what is legal for the C<...> in C<\N{...}> have been
-tightened up so that unless the C<...> begins with an alphabetic
-character and continues with a combination of alphanumerics, dashes,
-spaces, parentheses or colons then the warning C<Deprecated character(s)
-in \N{...} starting at '%s'> is now issued.
-
-=item *
-
-The warning C<Using just the first characters returned by \N{}> will
-be issued if the C<charnames> handler returns a sequence of characters
-which exceeds the limit of the number of characters that can be used. The
-message will indicate which characters were used and which were discarded.
-
-=back
-
-=back
-
-=head2 Changed Diagnostics
-
-A number of existing diagnostic messages have been improved or corrected:
-
-=over
-
-=item *
-
-A new warning category C<illegalproto> allows finer-grained control of
-warnings around function prototypes.
-
-The two warnings:
-
-=over
-
-=item C<Illegal character in prototype for %s : %s>
-
-=item C<Prototype after '%c' for %s : %s>
-
-=back
-
-have been moved from the C<syntax> top-level warnings category into a new
-first-level category, C<illegalproto>. These two warnings are currently
-the only ones emitted during parsing of an invalid/illegal prototype,
-so one can now use
-
- no warnings 'illegalproto';
-
-to suppress only those, but not other syntax-related warnings. Warnings
-where prototypes are changed, ignored, or not met are still in the
-C<prototype> category as before.
-
-=item *
-
-C<Deep recursion on subroutine "%s">
-
-It is now possible to change the depth threshold for this warning from the
-default of 100, by recompiling the F<perl> binary, setting the C
-pre-processor macro C<PERL_SUB_DEPTH_WARN> to the desired value.
-
-=item *
-
-C<Illegal character in prototype> warning is now more precise
-when reporting illegal characters after _
-
-=item *
-
-mro merging error messages are now very similar to those produced by
-L<Algorithm::C3>.
-
-=item *
-
-Amelioration of the error message "Unrecognized character %s in column %d"
-
-Changes the error message to "Unrecognized character %s; marked by E<lt>--
-HERE after %sE<lt>-- HERE near column %d". This should make it a little
-simpler to spot and correct the suspicious character.
-
-=item *
-
-Perl now explicitly points to C<$.> when it causes an uninitialized
-warning for ranges in scalar context.
-
-=item *
-
-C<split> now warns when called in void context.
-
-=item *
-
-C<printf>-style functions called with too few arguments will now issue the
-warning C<"Missing argument in %s"> [perl #71000]
-
-=item *
-
-Perl now properly returns a syntax error instead of segfaulting
-if C<each>, C<keys>, or C<values> is used without an argument.
-
-=item *
-
-C<tell()> now fails properly if called without an argument and when no
-previous file was read.
-
-C<tell()> now returns C<-1>, and sets errno to C<EBADF>, thus restoring
-the 5.8.x behaviour.
-
-=item *
-
-C<overload> no longer implicitly unsets fallback on repeated 'use
-overload' lines.
-
-=item *
-
-POSIX::strftime() can now handle Unicode characters in the format string.
-
-=item *
-
-The C<syntax> category was removed from 5 warnings that should only be in
-C<deprecated>.
-
-=item *
-
-Three fatal C<pack>/C<unpack> error messages have been normalized to
-C<panic: %s>
-
-=item *
-
-C<Unicode character is illegal> has been rephrased to be more accurate
-
-It now reads C<Unicode non-character is illegal in interchange> and the
-perldiag documentation has been expanded a bit.
-
-=item *
-
-Currently, all but the first of the several characters that the
-C<charnames> handler may return are discarded when used in a regular
-expression pattern bracketed character class. If this happens then the
-warning C<Using just the first character returned by \N{} in character
-class> will be issued.
-
-=item *
-
-The warning C<Missing right brace on \N{} or unescaped left brace after
-\N. Assuming the latter> will be issued if Perl encounters a C<\N{>
-but doesn't find a matching C<}>. In this case Perl doesn't know if it
-was mistakenly omitted, or if "match non-newline" followed by "match
-a C<{>" was desired. It assumes the latter because that is actually a
-valid interpretation as written, unlike the other case. If you meant
-the former, you need to add the matching right brace. If you did mean
-the latter, you can silence this warning by writing instead C<\N\{>.
-
-=item *
-
-C<gmtime> and C<localtime> called with numbers smaller than they can
-reliably handle will now issue the warnings C<gmtime(%.0f) too small>
-and C<localtime(%.0f) too small>.
-
-=back
-
-The following diagnostic messages have been removed:
-
-=over 4
-
-=item *
-
-C<Runaway format>
-
-=item *
-
-C<Can't locate package %s for the parents of %s>
-
-In general this warning it only got produced in
-conjunction with other warnings, and removing it allowed an ISA lookup
-optimisation to be added.
-
-=item *
-
-C<v-string in use/require is non-portable>
-
-=back
-
-=head1 Utility Changes
-
-=over 4
-
-=item *
-
-F<h2ph> now looks in C<include-fixed> too, which is a recent addition
-to gcc's search path.
-
-=item *
-
-F<h2xs> no longer incorrectly treats enum values like macros.
-It also now handles C++ style comments (C<//>) properly in enums.
-
-=item *
-
-F<perl5db.pl> now supports C<LVALUE> subroutines. Additionally, the
-debugger now correctly handles proxy constant subroutines, and
-subroutine stubs.
-
-=item *
-
-F<perlbug> now uses C<%Module::CoreList::bug_tracker> to print out
-upstream bug tracker URLs. If a user identifies a particular module
-as the topic of their bug report and we're able to divine the URL for
-its upstream bug tracker, perlbug now provide a message to the user
-explaining that the core copies the CPAN version directly, and provide
-the URL for reporting the bug directly to the upstream author.
-
-F<perlbug> no longer reports "Message sent" when it hasn't actually sent
-the message
-
-=item *
-
-F<perlthanks> is a new utility for sending non-bug-reports to the
-authors and maintainers of Perl. Getting nothing but bug reports can
-become a bit demoralising. If Perl 5.12 works well for you, please try
-out F<perlthanks>. It will make the developers smile.
-
-=item *
-
-Perl's developers have fixed bugs in F<a2p> having to do with the
-C<match()> operator in list context. Additionally, F<a2p> no longer
-generates code that uses the C<$[> variable.
-
-=back
-
-=head1 Selected Bug Fixes
-
-=over 4
-
-=item *
-
-U+0FFFF is now a legal character in regular expressions.
-
-=item *
-
-pp_qr now always returns a new regexp SV. Resolves RT #69852.
-
-Instead of returning a(nother) reference to the (pre-compiled) regexp
-in the optree, use reg_temp_copy() to create a copy of it, and return a
-reference to that. This resolves issues about Regexp::DESTROY not being
-called in a timely fashion (the original bug tracked by RT #69852), as
-well as bugs related to blessing regexps, and of assigning to regexps,
-as described in correspondence added to the ticket.
-
-It transpires that we also need to undo the SvPVX() sharing when ithreads
-cloning a Regexp SV, because mother_re is set to NULL, instead of a
-cloned copy of the mother_re. This change might fix bugs with regexps
-and threads in certain other situations, but as yet neither tests nor
-bug reports have indicated any problems, so it might not actually be an
-edge case that it's possible to reach.
-
-=item *
-
-Several compilation errors and segfaults when perl was built with C<-Dmad>
-were fixed.
-
-=item *
-
-Fixes for lexer API changes in 5.11.2 which broke NYTProf's savesrc option.
-
-=item *
-
-C<-t> should only return TRUE for file handles connected to a TTY
-
-The Microsoft C version of C<isatty()> returns TRUE for all character mode
-devices, including the F</dev/null>-style "nul" device and printers like
-"lpt1".
-
-=item *
-
-Fixed a regression caused by commit fafafbaf which caused a panic during
-parameter passing [perl #70171]
-
-=item *
-
-On systems which in-place edits without backup files, -i'*' now works as
-the documentation says it does [perl #70802]
-
-=item *
-
-Saving and restoring magic flags no longer loses readonly flag.
-
-=item *
-
-The malformed syntax C<grep EXPR LIST> (note the missing comma) no longer
-causes abrupt and total failure.
-
-=item *
-
-Regular expressions compiled with C<qr{}> literals properly set C<$'> when
-matching again.
-
-=item *
-
-Using named subroutines with C<sort> should no longer lead to bus errors
-[perl #71076]
-
-=item *
-
-Numerous bugfixes catch small issues caused by the recently-added Lexer API.
-
-=item *
-
-Smart match against C<@_> sometimes gave false negatives. [perl #71078]
-
-=item *
-
-C<$@> may now be assigned a read-only value (without error or busting
-the stack).
-
-=item *
-
-C<sort> called recursively from within an active comparison subroutine no
-longer causes a bus error if run multiple times. [perl #71076]
-
-=item *
-
-Tie::Hash::NamedCapture::* will not abort if passed bad input (RT #71828)
-
-=item *
-
-@_ and $_ no longer leak under threads (RT #34342 and #41138, also
-#70602, #70974)
-
-=item *
-
-C<-I> on shebang line now adds directories in front of @INC
-as documented, and as does C<-I> when specified on the command-line.
-
-=item *
-
-C<kill> is now fatal when called on non-numeric process identifiers.
-Previously, an C<undef> process identifier would be interpreted as a
-request to kill process 0, which would terminate the current process
-group on POSIX systems. Since process identifiers are always integers,
-killing a non-numeric process is now fatal.
-
-=item *
-
-5.10.0 inadvertently disabled an optimisation, which caused a measurable
-performance drop in list assignment, such as is often used to assign
-function parameters from C<@_>. The optimisation has been re-instated, and
-the performance regression fixed. (This fix is also present in 5.10.1)
-
-=item *
-
-Fixed memory leak on C<while (1) { map 1, 1 }> [RT #53038].
-
-=item *
-
-Some potential coredumps in PerlIO fixed [RT #57322,54828].
-
-=item *
-
-The debugger now works with lvalue subroutines.
-
-=item *
-
-The debugger's C<m> command was broken on modules that defined constants
-[RT #61222].
-
-=item *
-
-C<crypt> and string complement could return tainted values for untainted
-arguments [RT #59998].
-
-=item *
-
-The C<-i>I<.suffix> command-line switch now recreates the file using
-restricted permissions, before changing its mode to match the original
-file. This eliminates a potential race condition [RT #60904].
-
-=item *
-
-On some Unix systems, the value in C<$?> would not have the top bit set
-(C<$? & 128>) even if the child core dumped.
-
-=item *
-
-Under some circumstances, C<$^R> could incorrectly become undefined
-[RT #57042].
-
-=item *
-
-In the XS API, various hash functions, when passed a pre-computed hash where
-the key is UTF-8, might result in an incorrect lookup.
-
-=item *
-
-XS code including F<XSUB.h> before F<perl.h> gave a compile-time error
-[RT #57176].
-
-=item *
-
-C<< $object-E<gt>isa('Foo') >> would report false if the package C<Foo>
-didn't exist, even if the object's C<@ISA> contained C<Foo>.
-
-=item *
-
-Various bugs in the new-to 5.10.0 mro code, triggered by manipulating
-C<@ISA>, have been found and fixed.
-
-=item *
-
-Bitwise operations on references could crash the interpreter, e.g.
-C<$x=\$y; $x |= "foo"> [RT #54956].
-
-=item *
-
-Patterns including alternation might be sensitive to the internal UTF-8
-representation, e.g.
-
- my $byte = chr(192);
- my $utf8 = chr(192); utf8::upgrade($utf8);
- $utf8 =~ /$byte|X}/i; # failed in 5.10.0
-
-=item *
-
-Within UTF8-encoded Perl source files (i.e. where C<use utf8> is in
-effect), double-quoted literal strings could be corrupted where a C<\xNN>,
-C<\0NNN> or C<\N{}> is followed by a literal character with ordinal value
-greater than 255 [RT #59908].
-
-=item *
-
-C<B::Deparse> failed to correctly deparse various constructs:
-C<readpipe STRING> [RT #62428], C<CORE::require(STRING)> [RT #62488],
-C<sub foo(_)> [RT #62484].
-
-=item *
-
-Using C<setpgrp> with no arguments could corrupt the perl stack.
-
-=item *
-
-The block form of C<eval> is now specifically trappable by C<Safe> and
-C<ops>. Previously it was erroneously treated like string C<eval>.
-
-=item *
-
-In 5.10.0, the two characters C<[~> were sometimes parsed as the smart
-match operator (C<~~>) [RT #63854].
-
-=item *
-
-In 5.10.0, the C<*> quantifier in patterns was sometimes treated as
-C<{0,32767}> [RT #60034, #60464]. For example, this match would fail:
-
- ("ab" x 32768) =~ /^(ab)*$/
-
-=item *
-
-C<shmget> was limited to a 32 bit segment size on a 64 bit OS [RT #63924].
-
-=item *
-
-Using C<next> or C<last> to exit a C<given> block no longer produces a
-spurious warning like the following:
-
- Exiting given via last at foo.pl line 123
-
-=item *
-
-Assigning a format to a glob could corrupt the format; e.g.:
-
- *bar=*foo{FORMAT}; # foo format now bad
-
-=item *
-
-Attempting to coerce a typeglob to a string or number could cause an
-assertion failure. The correct error message is now generated,
-C<Can't coerce GLOB to I<$type>>.
-
-=item *
-
-Under C<use filetest 'access'>, C<-x> was using the wrong access
-mode. This has been fixed [RT #49003].
-
-=item *
-
-C<length> on a tied scalar that returned a Unicode value would not be
-correct the first time. This has been fixed.
-
-=item *
-
-Using an array C<tie> inside in array C<tie> could SEGV. This has been
-fixed. [RT #51636]
-
-=item *
-
-A race condition inside C<PerlIOStdio_close()> has been identified and
-fixed. This used to cause various threading issues, including SEGVs.
-
-=item *
-
-In C<unpack>, the use of C<()> groups in scalar context was internally
-placing a list on the interpreter's stack, which manifested in various
-ways, including SEGVs. This is now fixed [RT #50256].
-
-=item *
-
-Magic was called twice in C<substr>, C<\&$x>, C<tie $x, $m> and C<chop>.
-These have all been fixed.
-
-=item *
-
-A 5.10.0 optimisation to clear the temporary stack within the implicit
-loop of C<s///ge> has been reverted, as it turned out to be the cause of
-obscure bugs in seemingly unrelated parts of the interpreter [commit
-ef0d4e17921ee3de].
-
-=item *
-
-The line numbers for warnings inside C<elsif> are now correct.
-
-=item *
-
-The C<..> operator now works correctly with ranges whose ends are at or
-close to the values of the smallest and largest integers.
-
-=item *
-
-C<binmode STDIN, ':raw'> could lead to segmentation faults on some platforms.
-This has been fixed [RT #54828].
-
-=item *
-
-An off-by-one error meant that C<index $str, ...> was effectively being
-executed as C<index "$str\0", ...>. This has been fixed [RT #53746].
-
-=item *
-
-Various leaks associated with named captures in regexes have been fixed
-[RT #57024].
-
-=item *
-
-A weak reference to a hash would leak. This was affecting C<DBI>
-[RT #56908].
-
-=item *
-
-Using (?|) in a regex could cause a segfault [RT #59734].
-
-=item *
-
-Use of a UTF-8 C<tr//> within a closure could cause a segfault [RT #61520].
-
-=item *
-
-Calling C<Perl_sv_chop()> or otherwise upgrading an SV could result in an
-unaligned 64-bit access on the SPARC architecture [RT #60574].
-
-=item *
-
-In the 5.10.0 release, C<inc_version_list> would incorrectly list
-C<5.10.*> after C<5.8.*>; this affected the C<@INC> search order
-[RT #67628].
-
-=item *
-
-In 5.10.0, C<pack "a*", $tainted_value> returned a non-tainted value
-[RT #52552].
-
-=item *
-
-In 5.10.0, C<printf> and C<sprintf> could produce the fatal error
-C<panic: utf8_mg_pos_cache_update> when printing UTF-8 strings
-[RT #62666].
-
-=item *
-
-In the 5.10.0 release, a dynamically created C<AUTOLOAD> method might be
-missed (method cache issue) [RT #60220,60232].
-
-=item *
-
-In the 5.10.0 release, a combination of C<use feature> and C<//ee> could
-cause a memory leak [RT #63110].
-
-=item *
-
-C<-C> on the shebang (C<#!>) line is once more permitted if it is also
-specified on the command line. C<-C> on the shebang line used to be a
-silent no-op I<if> it was not also on the command line, so perl 5.10.0
-disallowed it, which broke some scripts. Now perl checks whether it is
-also on the command line and only dies if it is not [RT #67880].
-
-=item *
-
-In 5.10.0, certain types of re-entrant regular expression could crash,
-or cause the following assertion failure [RT #60508]:
-
- Assertion rx->sublen >= (s - rx->subbeg) + i failed
-
-=item *
-
-Perl now includes previously missing files from the Unicode Character
-Database.
-
-=item *
-
-Perl now honors C<TMPDIR> when opening an anonymous temporary file.
-
-=back
-
-
-=head1 Platform Specific Changes
-
-Perl is incredibly portable. In general, if a platform has a C compiler,
-someone has ported Perl to it (or will soon). We're happy to announce
-that Perl 5.12 includes support for several new platforms. At the same
-time, it's time to bid farewell to some (very) old friends.
-
-=head2 New Platforms
-
-=over
-
-=item Haiku
-
-Perl's developers have merged patches from Haiku's maintainers. Perl
-should now build on Haiku.
-
-=item MirOS BSD
-
-Perl should now build on MirOS BSD.
-
-=back
-
-=head2 Discontinued Platforms
-
-=over
-
-=item Domain/OS
-
-=item MiNT
-
-=item Tenon MachTen
-
-=back
-
-=head2 Updated Platforms
-
-=over 4
-
-=item AIX
-
-=over 4
-
-=item *
-
-Removed F<libbsd> for AIX 5L and 6.1. Only C<flock()> was used from
-F<libbsd>.
-
-=item *
-
-Removed F<libgdbm> for AIX 5L and 6.1 if F<libgdbm> < 1.8.3-5 is
-installed. The F<libgdbm> is delivered as an optional package with the
-AIX Toolbox. Unfortunately the versions below 1.8.3-5 are broken.
-
-=item *
-
-Hints changes mean that AIX 4.2 should work again.
-
-=back
-
-=item Cygwin
-
-=over 4
-
-=item *
-
-Perl now supports IPv6 on Cygwin 1.7 and newer.
-
-=item *
-
-On Cygwin we now strip the last number from the DLL. This has been the
-behaviour in the cygwin.com build for years. The hints files have been
-updated.
-
-=back
-
-=item Darwin (Mac OS X)
-
-=over 4
-
-=item *
-
-Skip testing the be_BY.CP1131 locale on Darwin 10 (Mac OS X 10.6),
-as it's still buggy.
-
-=item *
-
-Correct infelicities in the regexp used to identify buggy locales
-on Darwin 8 and 9 (Mac OS X 10.4 and 10.5, respectively).
-
-=back
-
-=item DragonFly BSD
-
-=over 4
-
-=item *
-
-Fix thread library selection [perl #69686]
-
-=back
-
-=item FreeBSD
-
-=over 4
-
-=item *
-
-The hints files now identify the correct threading libraries on FreeBSD 7
-and later.
-
-=back
-
-=item Irix
-
-=over 4
-
-=item *
-
-We now work around a bizarre preprocessor bug in the Irix 6.5 compiler:
-C<cc -E -> unfortunately goes into K&R mode, but C<cc -E file.c> doesn't.
-
-=back
-
-=item NetBSD
-
-=over 4
-
-=item *
-
-Hints now supports versions 5.*.
-
-=back
-
-=item OpenVMS
-
-=over 4
-
-=item *
-
-C<-UDEBUGGING> is now the default on VMS.
-
-Like it has been everywhere else for ages and ages. Also make command-line
-selection of -UDEBUGGING and -DDEBUGGING work in configure.com; before
-the only way to turn it off was by saying no in answer to the interactive
-question.
-
-=item *
-
-The default pipe buffer size on VMS has been updated to 8192 on 64-bit
-systems.
-
-=item *
-
-Reads from the in-memory temporary files of C<PerlIO::scalar> used to fail
-if C<$/> was set to a numeric reference (to indicate record-style reads).
-This is now fixed.
-
-=item *
-
-VMS now supports C<getgrgid>.
-
-=item *
-
-Many improvements and cleanups have been made to the VMS file name handling
-and conversion code.
-
-=item *
-
-Enabling the C<PERL_VMS_POSIX_EXIT> logical name now encodes a POSIX exit
-status in a VMS condition value for better interaction with GNV's bash
-shell and other utilities that depend on POSIX exit values. See
-L<perlvms/"$?"> for details.
-
-=item *
-
-C<File::Copy> now detects Unix compatibility mode on VMS.
-
-=back
-
-=item Stratus VOS
-
-=over 4
-
-=item *
-
-Various changes from Stratus have been merged in.
-
-=back
-
-=item Symbian
-
-=over 4
-
-=item *
-
-There is now support for Symbian S60 3.2 SDK and S60 5.0 SDK.
-
-=back
-
-=item Windows
-
-=over 4
-
-=item *
-
-Perl 5.12 supports Windows 2000 and later. The supporting code for
-legacy versions of Windows is still included, but will be removed
-during the next development cycle.
-
-=item *
-
-Initial support for building Perl with MinGW-w64 is now available.
-
-=item *
-
-F<perl.exe> now includes a manifest resource to specify the C<trustInfo>
-settings for Windows Vista and later. Without this setting Windows
-would treat F<perl.exe> as a legacy application and apply various
-heuristics like redirecting access to protected file system areas
-(like the "Program Files" folder) to the users "VirtualStore"
-instead of generating a proper "permission denied" error.
-
-The manifest resource also requests the Microsoft Common-Controls
-version 6.0 (themed controls introduced in Windows XP). Check out the
-Win32::VisualStyles module on CPAN to switch back to old style
-unthemed controls for legacy applications.
-
-=item *
-
-The C<-t> filetest operator now only returns true if the filehandle
-is connected to a console window. In previous versions of Perl it
-would return true for all character mode devices, including F<NUL>
-and F<LPT1>.
-
-=item *
-
-The C<-p> filetest operator now works correctly, and the
-Fcntl::S_IFIFO constant is defined when Perl is compiled with
-Microsoft Visual C. In previous Perl versions C<-p> always
-returned a false value, and the Fcntl::S_IFIFO constant
-was not defined.
-
-This bug is specific to Microsoft Visual C and never affected
-Perl binaries built with MinGW.
-
-=item *
-
-The socket error codes are now more widely supported: The POSIX
-module will define the symbolic names, like POSIX::EWOULDBLOCK,
-and stringification of socket error codes in $! works as well
-now;
-
- C:\>perl -MPOSIX -E "$!=POSIX::EWOULDBLOCK; say $!"
- A non-blocking socket operation could not be completed immediately.
-
-=item *
-
-flock() will now set sensible error codes in $!. Previous Perl versions
-copied the value of $^E into $!, which caused much confusion.
-
-=item *
-
-select() now supports all empty C<fd_set>s more correctly.
-
-=item *
-
-C<'.\foo'> and C<'..\foo'> were treated differently than
-C<'./foo'> and C<'../foo'> by C<do> and C<require> [RT #63492].
-
-=item *
-
-Improved message window handling means that C<alarm> and C<kill> messages
-will no longer be dropped under race conditions.
-
-=item *
-
-Various bits of Perl's build infrastructure are no longer converted to
-win32 line endings at release time. If this hurts you, please report the
-problem with the L<perlbug> program included with perl.
-
-=back
-
-=back
-
-
-=head1 Known Problems
-
-This is a list of some significant unfixed bugs, which are regressions
-from either 5.10.x or 5.8.x.
-
-=over 4
-
-=item *
-
-Some CPANPLUS tests may fail if there is a functioning file
-F<../../cpanp-run-perl> outside your build directory. The failure
-shouldn't imply there's a problem with the actual functional
-software. The bug is already fixed in [RT #74188] and is scheduled for
-inclusion in perl-v5.12.1.
-
-=item *
-
-C<List::Util::first> misbehaves in the presence of a lexical C<$_>
-(typically introduced by C<my $_> or implicitly by C<given>). The variable
-which gets set for each iteration is the package variable C<$_>, not the
-lexical C<$_> [RT #67694].
-
-A similar issue may occur in other modules that provide functions which
-take a block as their first argument, like
-
- foo { ... $_ ...} list
-
-=item *
-
-Some regexes may run much more slowly when run in a child thread compared
-with the thread the pattern was compiled into [RT #55600].
-
-=item *
-
-Things like C<"\N{LATIN SMALL LIGATURE FF}" =~ /\N{LATIN SMALL LETTER F}+/>
-will appear to hang as they get into a very long running loop [RT #72998].
-
-=item *
-
-Several porters have reported mysterious crashes when Perl's entire
-test suite is run after a build on certain Windows 2000 systems. When
-run by hand, the individual tests reportedly work fine.
-
-=back
-
-=head1 Errata
-
-=over
-
-=item *
-
-This one is actually a change introduced in 5.10.0, but it was missed
-from that release's perldelta, so it is mentioned here instead.
-
-A bugfix related to the handling of the C</m> modifier and C<qr> resulted
-in a change of behaviour between 5.8.x and 5.10.0:
-
- # matches in 5.8.x, doesn't match in 5.10.0
- $re = qr/^bar/; "foo\nbar" =~ /$re/m;
-
-=back
-
-=head1 Acknowledgements
-
-Perl 5.12.0 represents approximately two years of development since
-Perl 5.10.0 and contains over 750,000 lines of changes across over
-3,000 files from over 200 authors and committers.
-
-Perl continues to flourish into its third decade thanks to a vibrant
-community of users and developers. The following people are known to
-have contributed the improvements that became Perl 5.12.0:
-
-Aaron Crane, Abe Timmerman, Abhijit Menon-Sen, Abigail, Adam Russell,
-Adriano Ferreira, Ævar Arnfjörð Bjarmason, Alan Grover, Alexandr
-Ciornii, Alex Davies, Alex Vandiver, Andreas Koenig, Andrew Rodland,
-andrew@sundale.net, Andy Armstrong, Andy Dougherty, Jose AUGUSTE-ETIENNE,
-Benjamin Smith, Ben Morrow, bharanee rathna, Bo Borgerson, Bo Lindbergh,
-Brad Gilbert, Bram, Brendan O'Dea, brian d foy, Charles Bailey,
-Chip Salzenberg, Chris 'BinGOs' Williams, Christoph Lamprecht, Chris
-Williams, chromatic, Claes Jakobsson, Craig A. Berry, Dan Dascalescu,
-Daniel Frederick Crisman, Daniel M. Quinlan, Dan Jacobson, Dan Kogai,
-Dave Mitchell, Dave Rolsky, David Cantrell, David Dick, David Golden,
-David Mitchell, David M. Syzdek, David Nicol, David Wheeler, Dennis
-Kaarsemaker, Dintelmann, Peter, Dominic Dunlop, Dr.Ruud, Duke Leto,
-Enrico Sorcinelli, Eric Brine, Father Chrysostomos, Florian Ragwitz,
-Frank Wiegand, Gabor Szabo, Gene Sullivan, Geoffrey T. Dairiki, George
-Greer, Gerard Goossen, Gisle Aas, Goro Fuji, Graham Barr, Green, Paul,
-Hans Dieter Pearcey, Harmen, H. Merijn Brand, Hugo van der Sanden,
-Ian Goodacre, Igor Sutton, Ingo Weinhold, James Bence, James Mastros,
-Jan Dubois, Jari Aalto, Jarkko Hietaniemi, Jay Hannah, Jerry Hedden,
-Jesse Vincent, Jim Cromie, Jody Belka, John E. Malmberg, John Malmberg,
-John Peacock, John Peacock via RT, John P. Linderman, John Wright,
-Josh ben Jore, Jos I. Boumans, Karl Williamson, Kenichi Ishigaki, Ken
-Williams, Kevin Brintnall, Kevin Ryde, Kurt Starsinic, Leon Brocard,
-Lubomir Rintel, Luke Ross, Marcel Grünauer, Marcus Holland-Moritz, Mark
-Jason Dominus, Marko Asplund, Martin Hasch, Mashrab Kuvatov, Matt Kraai,
-Matt S Trout, Max Maischein, Michael Breen, Michael Cartmell, Michael
-G Schwern, Michael Witten, Mike Giroux, Milosz Tanski, Moritz Lenz,
-Nicholas Clark, Nick Cleaton, Niko Tyni, Offer Kaye, Osvaldo Villalon,
-Paul Fenwick, Paul Gaborit, Paul Green, Paul Johnson, Paul Marquess,
-Philip Hazel, Philippe Bruhat, Rafael Garcia-Suarez, Rainer Tammer,
-Rajesh Mandalemula, Reini Urban, Renée Bäcker, Ricardo Signes,
-Ricardo SIGNES, Richard Foley, Rich Rauenzahn, Rick Delaney, Risto
-Kankkunen, Robert May, Roberto C. Sanchez, Robin Barker, SADAHIRO
-Tomoyuki, Salvador Ortiz Garcia, Sam Vilain, Scott Lanning, Sébastien
-Aperghis-Tramoni, Sérgio Durigan Júnior, Shlomi Fish, Simon 'corecode'
-Schubert, Sisyphus, Slaven Rezic, Smylers, Steffen Müller, Steffen
-Ullrich, Stepan Kasal, Steve Hay, Steven Schubiger, Steve Peters, Tels,
-The Doctor, Tim Bunce, Tim Jenness, Todd Rinaldo, Tom Christiansen,
-Tom Hukins, Tom Wyant, Tony Cook, Torsten Schoenfeld, Tye McQueen,
-Vadim Konovalov, Vincent Pit, Hio YAMASHINA, Yasuhiro Matsumoto,
-Yitzchak Scott-Thoennes, Yuval Kogman, Yves Orton, Zefram, Zsban Ambrus
-
-This is woefully incomplete as it's automatically generated from version
-control history. In particular, it doesn't include the names of the
-(very much appreciated) contributors who reported issues in previous
-versions of Perl that helped make Perl 5.12.0 better. For a more complete
-list of all of Perl's historical contributors, please see the C<AUTHORS>
-file in the Perl 5.12.0 distribution.
-
-Our "retired" pumpkings Nicholas Clark and Rafael Garcia-Suarez
-deserve special thanks for their brilliant and substantive ongoing
-contributions. Nicholas personally authored over 30% of the patches
-since 5.10.0. Rafael comes in second in patch authorship with 11%,
-but is first by a long shot in committing patches authored by others,
-pushing 44% of the commits since 5.10.0 in this category, often after
-providing considerable coaching to the patch authors. These statistics
-in no way comprise all of their contributions, but express in shorthand
-that we couldn't have done it without them.
-
-Many of the changes included in this version originated in the CPAN
-modules included in Perl's core. We're grateful to the entire CPAN
-community for helping Perl to flourish.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at L<http://rt.perl.org/perlbug/>. There may also be
-information at L<http://www.perl.org/>, the Perl Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analyzed by the Perl porting team.
-
-If the bug you are reporting has security implications, which make it
-inappropriate to send to a publicly archived mailing list, then please send
-it to perl5-security-report@perl.org. This points to a closed subscription
-unarchived mailing list, which includes
-all the core committers, who will be able
-to help assess the impact of issues, figure out a resolution, and help
-co-ordinate the release of patches to mitigate or fix the problem across all
-platforms on which Perl is supported. Please only use this address for
-security issues in the Perl core, not for modules independently
-distributed on CPAN.
-
-=head1 SEE ALSO
-
-The F<Changes> file for an explanation of how to view exhaustive details
-on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-L<http://dev.perl.org/perl5/errata.html> for a list of issues
-found after this release, as well as a list of CPAN modules known
-to be incompatible with this release.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl5121delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5121delta.pod
deleted file mode 100644
index a999f144848..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl5121delta.pod
+++ /dev/null
@@ -1,411 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perl5121delta - what is new for perl v5.12.1
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.12.0 release and
-the 5.12.1 release.
-
-If you are upgrading from an earlier release such as 5.10.1, first read
-L<perl5120delta>, which describes differences between 5.10.1 and
-5.12.0.
-
-=head1 Incompatible Changes
-
-There are no changes intentionally incompatible with 5.12.0. If any
-incompatibilities with 5.12.0 exist, they are bugs. Please report them.
-
-=head1 Core Enhancements
-
-Other than the bug fixes listed below, there should be no user-visible
-changes to the core language in this release.
-
-=head1 Modules and Pragmata
-
-=head2 Pragmata Changes
-
-=over
-
-=item *
-
-We fixed exporting of C<is_strict> and C<is_lax> from L<version>.
-
-These were being exported with a wrapper that treated them as method
-calls, which caused them to fail. They are just functions, are
-documented as such, and should never be subclassed, so this patch
-just exports them directly as functions without the wrapper.
-
-=back
-
-=head2 Updated Modules
-
-=over
-
-=item *
-
-We upgraded L<CGI.pm> to version 3.49 to incorporate fixes for regressions
-introduced in the release we shipped with Perl 5.12.0.
-
-=item *
-
-We upgraded L<Pod::Simple> to version 3.14 to get an improvement to \C\<\< \>\>
-parsing.
-
-=item *
-
-We made a small fix to the L<CPANPLUS> test suite to fix an occasional spurious test failure.
-
-=item *
-
-We upgraded L<Safe> to version 2.27 to wrap coderefs returned by C<reval()> and C<rdo()>.
-
-=back
-
-=head1 Changes to Existing Documentation
-
-=over
-
-=item *
-
-We added the new maintenance release policy to L<perlpolicy.pod>
-
-=item *
-
-We've clarified the multiple-angle-bracket construct in the spec for POD
-in L<perlpodspec>
-
-=item *
-
-We added a missing explanation for a warning about C<:=> to L<perldiag.pod>
-
-=item *
-
-We removed a false claim in L<perlunitut> that all text strings are Unicode strings in Perl.
-
-=item *
-
-We updated the Github mirror link in L<perlrepository> to mirrors/perl, not github/perl
-
-=item *
-
-We fixed a a minor error in L<perl5114delta.pod>.
-
-=item *
-
-We replaced a mention of the now-obsolete L<Switch.pm> with F<given>/F<when>.
-
-=item *
-
-We improved documentation about F<$sitelibexp/sitecustomize.pl> in L<perlrun>.
-
-=item *
-
-We corrected L<perlmodlib.pod> which had unintentionally omitted a number of modules.
-
-=item *
-
-We updated the documentation for 'require' in L<perlfunc.pod> relating to putting Perl code in @INC.
-
-=item *
-
-We reinstated some erroneously-removed documentation about quotemeta in L<perlfunc>.
-
-=item *
-
-We fixed an F<a2p> example in L<perlutil.pod>.
-
-=item *
-
-We filled in a blank in L<perlport.pod> with the release date of Perl 5.12.
-
-=item *
-
-We fixed broken links in a number of perldelta files.
-
-=item *
-
-The documentation for L<Carp.pm> incorrectly stated that the $Carp::Verbose
-variable makes cluck generate stack backtraces.
-
-=item *
-
-We fixed a number of typos in L<Pod::Functions>
-
-=item *
-
-We improved documentation of case-changing functions in L<perlfunc.pod>
-
-=item *
-
-We corrected L<perlgpl.pod> to contain the correct version of the GNU
-General Public License.
-
-
-
-=back
-
-=head1 Testing
-
-=head2 Testing Improvements
-
-=over
-
-=item *
-
-F<t/op/sselect.t> is now less prone to clock jitter during timing checks
-on Windows.
-
-sleep() time on Win32 may be rounded down to multiple of
-the clock tick interval.
-
-=item *
-
-F<lib/blib.t> and F<lib/locale.t>: Fixes for test failures on Darwin/PPC
-
-=item *
-
-F<perl5db.t>: Fix for test failures when C<Term::ReadLine::Gnu> is installed.
-
-=back
-
-=head1 Installation and Configuration Improvements
-
-=head2 Configuration improvements
-
-=over
-
-=item *
-
-We updated F<INSTALL> with notes about how to deal with broken F<dbm.h>
-on OpenSUSE (and possibly other platforms)
-
-=back
-
-=head1 Bug Fixes
-
-=over 4
-
-=item *
-
-A bug in how we process filetest operations could cause a segfault.
-Filetests don't always expect an op on the stack, so we now use
-TOPs only if we're sure that we're not stat'ing the _ filehandle.
-This is indicated by OPf_KIDS (as checked in ck_ftst).
-
-See also: L<http://rt.perl.org/rt3/Public/Bug/Display.html?id=74542>
-
-=item *
-
-When deparsing a nextstate op that has both a change of package (relative
-to the previous nextstate) and a label, the package declaration is now
-emitted first, because it is syntactically impermissible for a label to
-prefix a package declaration.
-
-=item *
-
-XSUB.h now correctly redefines fgets under PERL_IMPLICIT_SYS
-
-See also: L<http://rt.cpan.org/Public/Bug/Display.html?id=55049>
-
-=item *
-
-utf8::is_utf8 now respects GMAGIC (e.g. $1)
-
-=item *
-
-XS code using C<fputc()> or C<fputs()>: on Windows could cause an error
-due to their arguments being swapped.
-
-See also: L<http://rt.perl.org/rt3/Public/Bug/Display.html?id=72704>
-
-=item *
-
-We fixed a small bug in lex_stuff_pvn() that caused spurious syntax errors
-in an obscure situation. It happened when stuffing was performed on the
-last line of a file and the line ended with a statement that lacked a
-terminating semicolon.
-
-See also: L<http://rt.perl.org/rt3/Public/Bug/Display.html?id=74006>
-
-=item *
-
-We fixed a bug that could cause \N{} constructs followed by a single . to
-be parsed incorrectly.
-
-See also: L<http://rt.perl.org/rt3/Public/Bug/Display.html?id=74978>
-
-=item *
-
-
-We fixed a bug that caused when(scalar) without an argument not to be
-treated as a syntax error.
-
-See also: L<http://rt.perl.org/rt3/Public/Bug/Display.html?id=74114>
-
-=item *
-
-We fixed a regression in the handling of labels immediately before string
-evals that was introduced in Perl 5.12.0.
-
-See also: L<http://rt.perl.org/rt3/Public/Bug/Display.html?id=74290>
-
-=item *
-
-We fixed a regression in case-insensitive matching of folded characters
-in regular expressions introduced in Perl 5.10.1.
-
-See also: L<http://rt.perl.org/rt3/Public/Bug/Display.html?id=72998>
-
-=back
-
-=head1 Platform Specific Notes
-
-=head2 HP-UX
-
-=over
-
-=item *
-
-Perl now allows -Duse64bitint without promoting to use64bitall on HP-UX
-
-=back
-
-=head2 AIX
-
-=over
-
-=item *
-
-Perl now builds on AIX 4.2
-
-The changes required work around AIX 4.2s' lack of support for IPv6,
-and limited support for POSIX C<sigaction()>.
-
-=back
-
-=head2 FreeBSD 7
-
-=over
-
-=item *
-
-FreeBSD 7 no longer contains F</usr/bin/objformat>. At build time,
-Perl now skips the F<objformat> check for versions 7 and higher and
-assumes ELF.
-
-=back
-
-=head2 VMS
-
-=over
-
-=item *
-
-It's now possible to build extensions on older (pre 7.3-2) VMS systems.
-
-DCL symbol length was limited to 1K up until about seven years or
-so ago, but there was no particularly deep reason to prevent those
-older systems from configuring and building Perl.
-
-=item *
-
-We fixed the previously-broken C<-Uuseperlio> build on VMS.
-
-We were checking a variable that doesn't exist in the non-default
-case of disabling perlio. Now we only look at it when it exists.
-
-=item *
-
-We fixed the -Uuseperlio command-line option in configure.com.
-
-Formerly it only worked if you went through all the questions
-interactively and explicitly answered no.
-
-=back
-
-=head1 Known Problems
-
-=over
-
-=item *
-
-C<List::Util::first> misbehaves in the presence of a lexical C<$_>
-(typically introduced by C<my $_> or implicitly by C<given>). The variable
-which gets set for each iteration is the package variable C<$_>, not the
-lexical C<$_>.
-
-A similar issue may occur in other modules that provide functions which
-take a block as their first argument, like
-
- foo { ... $_ ...} list
-
-See also: L<http://rt.perl.org/rt3/Public/Bug/Display.html?id=67694>
-
-=item *
-
-C<Module::Load::Conditional> and C<version> have an unfortunate
-interaction which can cause C<CPANPLUS> to crash when it encounters
-an unparseable version string. Upgrading to C<CPANPLUS> 0.9004 or
-C<Module::Load::Conditional> 0.38 from CPAN will resolve this issue.
-
-=back
-
-
-=head1 Acknowledgements
-
-Perl 5.12.1 represents approximately four weeks of development since
-Perl 5.12.0 and contains approximately 4,000 lines of changes
-across 142 files from 28 authors.
-
-Perl continues to flourish into its third decade thanks to a vibrant
-community of users and developers. The following people are known to
-have contributed the improvements that became Perl 5.12.1:
-
-Ævar Arnfjörð Bjarmason, Chris Williams, chromatic, Craig A. Berry,
-David Golden, Father Chrysostomos, Florian Ragwitz, Frank Wiegand,
-Gene Sullivan, Goro Fuji, H.Merijn Brand, James E Keenan, Jan Dubois,
-Jesse Vincent, Josh ben Jore, Karl Williamson, Leon Brocard, Michael
-Schwern, Nga Tang Chan, Nicholas Clark, Niko Tyni, Philippe Bruhat,
-Rafael Garcia-Suarez, Ricardo Signes, Steffen Mueller, Todd Rinaldo,
-Vincent Pit and Zefram.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://rt.perl.org/perlbug/ . There may also be
-information at http://www.perl.org/ , the Perl Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team.
-
-If the bug you are reporting has security implications, which make it
-inappropriate to send to a publicly archived mailing list, then please send
-it to perl5-security-report@perl.org. This points to a closed subscription
-unarchived mailing list, which includes
-all the core committers, who will be able
-to help assess the impact of issues, figure out a resolution, and help
-co-ordinate the release of patches to mitigate or fix the problem across all
-platforms on which Perl is supported. Please only use this address for
-security issues in the Perl core, not for modules independently
-distributed on CPAN.
-
-=head1 SEE ALSO
-
-The F<Changes> file for an explanation of how to view exhaustive details
-on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perl5122delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5122delta.pod
deleted file mode 100644
index f441a385812..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl5122delta.pod
+++ /dev/null
@@ -1,347 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perl5122delta - what is new for perl v5.12.2
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.12.1 release and
-the 5.12.2 release.
-
-If you are upgrading from an earlier major version, such as 5.10.1,
-first read L<perl5120delta>, which describes differences between 5.10.1
-and 5.12.0, as well as L<perl5121delta>, which describes earlier changes
-in the 5.12 stable release series.
-
-=head1 Incompatible Changes
-
-There are no changes intentionally incompatible with 5.12.1. If any exist, they
-are bugs and reports are welcome.
-
-=head1 Core Enhancements
-
-Other than the bug fixes listed below, there should be no user-visible
-changes to the core language in this release.
-
-=head1 Modules and Pragmata
-
-=head2 New Modules and Pragmata
-
-This release does not introduce any new modules or pragmata.
-
-=head2 Pragmata Changes
-
-In the previous release, C<no I<VERSION>;> statements triggered a bug
-which could cause L<feature> bundles to be loaded and L<strict> mode to
-be enabled unintentionally.
-
-=head2 Updated Modules
-
-=over 4
-
-=item C<Carp>
-
-Upgraded from version 1.16 to 1.17.
-
-L<Carp> now detects incomplete L<caller()|perlfunc/"caller EXPR">
-overrides and avoids using bogus C<@DB::args>. To provide backtraces, Carp
-relies on particular behaviour of the caller built-in. Carp now detects
-if other code has overridden this with an incomplete implementation, and
-modifies its backtrace accordingly. Previously incomplete overrides would
-cause incorrect values in backtraces (best case), or obscure fatal errors
-(worst case)
-
-This fixes certain cases of C<Bizarre copy of ARRAY> caused by modules
-overriding C<caller()> incorrectly.
-
-=item C<CPANPLUS>
-
-A patch to F<cpanp-run-perl> has been backported from CPANPLUS C<0.9004>. This
-resolves L<RT #55964|http://rt.cpan.org/Public/Bug/Display.html?id=55964>
-and L<RT #57106|http://rt.cpan.org/Public/Bug/Display.html?id=57106>, both
-of which related to failures to install distributions that use
-C<Module::Install::DSL>.
-
-=item C<File::Glob>
-
-A regression which caused a failure to find C<CORE::GLOBAL::glob> after
-loading C<File::Glob> to crash has been fixed. Now, it correctly falls back
-to external globbing via C<pp_glob>.
-
-=item C<File::Copy>
-
-C<File::Copy::copy(FILE, DIR)> is now documented.
-
-=item C<File::Spec>
-
-Upgraded from version 3.31 to 3.31_01.
-
-Several portability fixes were made in C<File::Spec::VMS>: a colon is now
-recognized as a delimiter in native filespecs; caret-escaped delimiters are
-recognized for better handling of extended filespecs; C<catpath()> returns
-an empty directory rather than the current directory if the input directory
-name is empty; C<abs2rel()> properly handles Unix-style input.
-
-=back
-
-=head1 Utility Changes
-
-=over
-
-=item *
-
-F<perlbug> now always gives the reporter a chance to change the email address it
-guesses for them.
-
-=item *
-
-F<perlbug> should no longer warn about uninitialized values when using the C<-d>
-and C<-v> options.
-
-=back
-
-=head1 Changes to Existing Documentation
-
-=over
-
-=item *
-
-The existing policy on backward-compatibility and deprecation has
-been added to L<perlpolicy>, along with definitions of terms like
-I<deprecation>.
-
-=item *
-
-L<perlfunc/srand>'s usage has been clarified.
-
-=item *
-
-The entry for L<perlfunc/die> was reorganized to emphasize its
-role in the exception mechanism.
-
-=item *
-
-Perl's L<INSTALL> file has been clarified to explicitly state that Perl
-requires a C89 compliant ANSI C Compiler.
-
-=item *
-
-L<IO::Socket>'s C<getsockopt()> and C<setsockopt()> have been documented.
-
-=item *
-
-F<alarm()>'s inability to interrupt blocking IO on Windows has been documented.
-
-=item *
-
-L<Math::TrulyRandom> hasn't been updated since 1996 and has been removed
-as a recommended solution for random number generation.
-
-=item *
-
-L<perlrun> has been updated to clarify the behaviour of octal flags to F<perl>.
-
-=item *
-
-To ease user confusion, C<$#> and C<$*>, two special variables that were
-removed in earlier versions of Perl have been documented.
-
-=item *
-
-The version of L<perlfaq> shipped with the Perl core has been updated from the
-official FAQ version, which is now maintained in the C<briandfoy/perlfaq>
-branch of the Perl repository at L<git://perl5.git.perl.org/perl.git>.
-
-=back
-
-=head1 Installation and Configuration Improvements
-
-=head2 Configuration improvements
-
-=over
-
-=item *
-
-The C<d_u32align> configuration probe on ARM has been fixed.
-
-=back
-
-=head2 Compilation improvements
-
-=over
-
-=item *
-
-An "C<incompatible operand types>" error in ternary expressions when building
-with C<clang> has been fixed.
-
-=item *
-
-Perl now skips setuid C<File::Copy> tests on partitions it detects to be mounted
-as C<nosuid>.
-
-=back
-
-=head1 Selected Bug Fixes
-
-=over 4
-
-=item *
-
-A possible segfault in the C<T_PRTOBJ> default typemap has been fixed.
-
-=item *
-
-A possible memory leak when using L<caller()|perlfunc/"caller EXPR"> to set
-C<@DB::args> has been fixed.
-
-=item *
-
-Several memory leaks when loading XS modules were fixed.
-
-=item *
-
-C<unpack()> now handles scalar context correctly for C<%32H> and C<%32u>,
-fixing a potential crash. C<split()> would crash because the third item
-on the stack wasn't the regular expression it expected. C<unpack("%2H",
-...)> would return both the unpacked result and the checksum on the stack,
-as would C<unpack("%2u", ...)>.
-L<[perl #73814]|http://rt.perl.org/rt3/Ticket/Display.html?id=73814>
-
-=item *
-
-Perl now avoids using memory after calling C<free()> in F<pp_require>
-when there are CODEREFs in C<@INC>.
-
-=item *
-
-A bug that could cause "C<Unknown error>" messages when
-"C<call_sv(code, G_EVAL)>" is called from an XS destructor has been fixed.
-
-=item *
-
-The implementation of the C<open $fh, 'E<gt>' \$buffer> feature
-now supports get/set magic and thus tied buffers correctly.
-
-=item *
-
-The C<pp_getc>, C<pp_tell>, and C<pp_eof> opcodes now make room on the
-stack for their return values in cases where no argument was passed in.
-
-=item *
-
-When matching unicode strings under some conditions inappropriate backtracking would
-result in a C<Malformed UTF-8 character (fatal)> error. This should no longer occur.
-See L<[perl #75680]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=75680>
-
-=back
-
-=head1 Platform Specific Notes
-
-=head2 AIX
-
-=over
-
-=item *
-
-F<README.aix> has been updated with information about the XL C/C++ V11 compiler
-suite.
-
-=back
-
-=head2 Windows
-
-=over
-
-=item *
-
-When building Perl with the mingw64 x64 cross-compiler C<incpath>,
-C<libpth>, C<ldflags>, C<lddlflags> and C<ldflags_nolargefiles> values
-in F<Config.pm> and F<Config_heavy.pl> were not previously being set
-correctly because, with that compiler, the include and lib directories
-are not immediately below C<$(CCHOME)>.
-
-=back
-
-=head2 VMS
-
-=over
-
-=item *
-
-F<git_version.h> is now installed on VMS. This was an oversight in v5.12.0 which
-caused some extensions to fail to build.
-
-=item *
-
-Several memory leaks in L<stat()|perlfunc/"stat FILEHANDLE"> have been fixed.
-
-=item *
-
-A memory leak in C<Perl_rename()> due to a double allocation has been
-fixed.
-
-=item *
-
-A memory leak in C<vms_fid_to_name()> (used by C<realpath()> and
-C<realname()>) has been fixed.
-
-=back
-
-=head1 Acknowledgements
-
-Perl 5.12.2 represents approximately three months of development since
-Perl 5.12.1 and contains approximately 2,000 lines of changes across
-100 files from 36 authors.
-
-Perl continues to flourish into its third decade thanks to a vibrant
-community of users and developers. The following people are known to
-have contributed the improvements that became Perl 5.12.2:
-
-Abigail, Ævar Arnfjörð Bjarmason, Ben Morrow, brian d foy, Brian
-Phillips, Chas. Owens, Chris 'BinGOs' Williams, Chris Williams,
-Craig A. Berry, Curtis Jewell, Dan Dascalescu, David Golden, David
-Mitchell, Father Chrysostomos, Florian Ragwitz, George Greer, H.Merijn
-Brand, Jan Dubois, Jesse Vincent, Jim Cromie, Karl Williamson, Lars
-Dɪᴇᴄᴋá´á´¡ 迪拉斯, Leon Brocard, Maik Hentsche, Matt S Trout,
-Nicholas Clark, Rafael Garcia-Suarez, Rainer Tammer, Ricardo Signes,
-Salvador Ortiz Garcia, Sisyphus, Slaven Rezic, Steffen Mueller, Tony Cook,
-Vincent Pit and Yves Orton.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://rt.perl.org/perlbug/ . There may also be
-information at http://www.perl.org/ , the Perl Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team.
-
-If the bug you are reporting has security implications, which make it
-inappropriate to send to a publicly archived mailing list, then please send
-it to perl5-security-report@perl.org. This points to a closed subscription
-unarchived mailing list, which includes
-all the core committers, who will be able
-to help assess the impact of issues, figure out a resolution, and help
-co-ordinate the release of patches to mitigate or fix the problem across all
-platforms on which Perl is supported. Please only use this address for
-security issues in the Perl core, not for modules independently
-distributed on CPAN.
-
-=head1 SEE ALSO
-
-The F<Changes> file for an explanation of how to view exhaustive details
-on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl5123delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5123delta.pod
deleted file mode 100644
index 580af240169..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl5123delta.pod
+++ /dev/null
@@ -1,118 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perl5123delta - what is new for perl v5.12.3
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.12.2 release and
-the 5.12.3 release.
-
-If you are upgrading from an earlier release such as 5.12.1, first read
-L<perl5122delta>, which describes differences between 5.12.1 and
-5.12.2. The major changes made in 5.12.0 are described in L<perl5120delta>.
-
-=head1 Incompatible Changes
-
- There are no changes intentionally incompatible with 5.12.2. If any
- exist, they are bugs and reports are welcome.
-
-=head1 Core Enhancements
-
-=head2 C<keys>, C<values> work on arrays
-
-You can now use the C<keys>, C<values>, C<each> builtin functions on arrays
-(previously you could only use them on hashes). See L<perlfunc> for details.
-This is actually a change introduced in perl 5.12.0, but it was missed from
-that release's perldelta.
-
-=head1 Bug Fixes
-
-"no VERSION" will now correctly deparse with B::Deparse, as will certain
-constant expressions.
-
-Module::Build should be more reliably pass its tests under cygwin.
-
-Lvalue subroutines are again able to return copy-on-write scalars. This
-had been broken since version 5.10.0.
-
-=head1 Platform Specific Notes
-
-=over 4
-
-=item Solaris
-
-A separate DTrace is now build for miniperl, which means that perl can be
-compiled with -Dusedtrace on Solaris again.
-
-=item VMS
-
-A number of regressions on VMS have been fixed. In addition to minor cleanup
-of questionable expressions in F<vms.c>, file permissions should no longer be
-garbled by the PerlIO layer, and spurious record boundaries should no longer be
-introduced by the PerlIO layer during output.
-
-For more details and discussion on the latter, see:
-
- http://www.nntp.perl.org/group/perl.vmsperl/2010/11/msg15419.html
-
-=item VOS
-
-A few very small changes were made to the build process on VOS to better
-support the platform. Longer-than-32-character filenames are now supported on
-OpenVOS, and build properly without IPv6 support.
-
-=back
-
-=head1 Acknowledgements
-
-Perl 5.12.3 represents approximately four months of development since
-Perl 5.12.2 and contains approximately 2500 lines of changes across
-54 files from 16 authors.
-
-Perl continues to flourish into its third decade thanks to a vibrant
-community of users and developers. The following people are known to
-have contributed the improvements that became Perl 5.12.3:
-
-Craig A. Berry, David Golden, David Leadbeater, Father Chrysostomos, Florian
-Ragwitz, Jesse Vincent, Karl Williamson, Nick Johnston, Nicolas Kaiser, Paul
-Green, Rafael Garcia-Suarez, Rainer Tammer, Ricardo Signes, Steffen Mueller,
-Zsbán Ambrus, Ævar Arnfjörð Bjarmason
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://rt.perl.org/perlbug/ . There may also be
-information at http://www.perl.org/ , the Perl Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team.
-
-If the bug you are reporting has security implications, which make it
-inappropriate to send to a publicly archived mailing list, then please send
-it to perl5-security-report@perl.org. This points to a closed subscription
-unarchived mailing list, which includes
-all the core committers, who will be able
-to help assess the impact of issues, figure out a resolution, and help
-co-ordinate the release of patches to mitigate or fix the problem across all
-platforms on which Perl is supported. Please only use this address for
-security issues in the Perl core, not for modules independently
-distributed on CPAN.
-
-=head1 SEE ALSO
-
-The F<Changes> file for an explanation of how to view exhaustive details
-on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl5124delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5124delta.pod
deleted file mode 100644
index bd3a1db43be..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl5124delta.pod
+++ /dev/null
@@ -1,108 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perl5124delta - what is new for perl v5.12.4
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.12.3 release and
-the 5.12.4 release.
-
-If you are upgrading from an earlier release such as 5.12.2, first read
-L<perl5123delta>, which describes differences between 5.12.2
-and 5.12.3. The major changes made in 5.12.0 are described in L<perl5120delta>.
-
-=head1 Incompatible Changes
-
-There are no changes intentionally incompatible with 5.12.3. If any
-exist, they are bugs and reports are welcome.
-
-=head1 Selected Bug Fixes
-
-When strict "refs" mode is off, C<%{...}> in rvalue context returns
-C<undef> if its argument is undefined. An optimisation introduced in Perl
-5.12.0 to make C<keys %{...}> faster when used as a boolean did not take
-this into account, causing C<keys %{+undef}> (and C<keys %$foo> when
-C<$foo> is undefined) to be an error, which it should be so in strict
-mode only [perl #81750].
-
-C<lc>, C<uc>, C<lcfirst>, and C<ucfirst> no longer return untainted strings
-when the argument is tainted. This has been broken since perl 5.8.9
-[perl #87336].
-
-Fixed a case where it was possible that a freed buffer may have been read
-from when parsing a here document.
-
-=head1 Modules and Pragmata
-
-L<Module::CoreList> has been upgraded from version 2.43 to 2.50.
-
-=head1 Testing
-
-The F<cpan/CGI/t/http.t> test script has been fixed to work when the
-environment has HTTPS_* environment variables, such as HTTPS_PROXY.
-
-=head1 Documentation
-
-Updated the documentation for rand() in L<perlfunc> to note that it is not
-cryptographically secure.
-
-=head1 Platform Specific Notes
-
-=over 4
-
-=item Linux
-
-Support Ubuntu 11.04's new multi-arch library layout.
-
-=back
-
-=head1 Acknowledgements
-
-Perl 5.12.4 represents approximately 5 months of development since
-Perl 5.12.3 and contains approximately 200 lines of changes across
-11 files from 8 authors.
-
-Perl continues to flourish into its third decade thanks to a vibrant
-community of users and developers. The following people are known to
-have contributed the improvements that became Perl 5.12.4:
-
-Andy Dougherty, David Golden, David Leadbeater, Father Chrysostomos,
-Florian Ragwitz, Jesse Vincent, Leon Brocard, Zsbán Ambrus.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://rt.perl.org/perlbug/ . There may also be
-information at http://www.perl.org/ , the Perl Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team.
-
-If the bug you are reporting has security implications, which make it
-inappropriate to send to a publicly archived mailing list, then please send
-it to perl5-security-report@perl.org. This points to a closed subscription
-unarchived mailing list, which includes all the core committers, who be able
-to help assess the impact of issues, figure out a resolution, and help
-co-ordinate the release of patches to mitigate or fix the problem across all
-platforms on which Perl is supported. Please only use this address for
-security issues in the Perl core, not for modules independently
-distributed on CPAN.
-
-=head1 SEE ALSO
-
-The F<Changes> file for an explanation of how to view exhaustive details
-on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl5140delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5140delta.pod
deleted file mode 100644
index 74c82a8e141..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl5140delta.pod
+++ /dev/null
@@ -1,4590 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perl5140delta - what is new for perl v5.14.0
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.12.0 release and
-the 5.14.0 release.
-
-If you are upgrading from an earlier release such as 5.10.0, first read
-L<perl5120delta>, which describes differences between 5.10.0 and
-5.12.0.
-
-Some of the bug fixes in this release have been backported to subsequent
-releases of 5.12.x. Those are indicated with the 5.12.x version in
-parentheses.
-
-=head1 Notice
-
-As described in L<perlpolicy>, the release of Perl 5.14.0 marks the
-official end of support for Perl 5.10. Users of Perl 5.10 or earlier
-should consider upgrading to a more recent release of Perl.
-
-=head1 Core Enhancements
-
-=head2 Unicode
-
-=head3 Unicode Version 6.0 is now supported (mostly)
-
-Perl comes with the Unicode 6.0 data base updated with
-L<Corrigendum #8|http://www.unicode.org/versions/corrigendum8.html>,
-with one exception noted below.
-See L<http://unicode.org/versions/Unicode6.0.0/> for details on the new
-release. Perl does not support any Unicode provisional properties,
-including the new ones for this release.
-
-Unicode 6.0 has chosen to use the name C<BELL> for the character at U+1F514,
-which is a symbol that looks like a bell, and is used in Japanese cell
-phones. This conflicts with the long-standing Perl usage of having
-C<BELL> mean the ASCII C<BEL> character, U+0007. In Perl 5.14,
-C<\N{BELL}> continues to mean U+0007, but its use generates a
-deprecation warning message unless such warnings are turned off. The
-new name for U+0007 in Perl is C<ALERT>, which corresponds nicely
-with the existing shorthand sequence for it, C<"\a">. C<\N{BEL}>
-means U+0007, with no warning given. The character at U+1F514 has no
-name in 5.14, but can be referred to by C<\N{U+1F514}>.
-In Perl 5.16, C<\N{BELL}> will refer to U+1F514; all code
-that uses C<\N{BELL}> should be converted to use C<\N{ALERT}>,
-C<\N{BEL}>, or C<"\a"> before upgrading.
-
-=head3 Full functionality for C<use feature 'unicode_strings'>
-
-This release provides full functionality for C<use feature
-'unicode_strings'>. Under its scope, all string operations executed and
-regular expressions compiled (even if executed outside its scope) have
-Unicode semantics. See L<feature/"the 'unicode_strings' feature">.
-However, see L</Inverted bracketed character classes and multi-character folds>,
-below.
-
-This feature avoids most forms of the "Unicode Bug" (see
-L<perlunicode/The "Unicode Bug"> for details). If there is any
-possibility that your code will process Unicode strings, you are
-I<strongly> encouraged to use this subpragma to avoid nasty surprises.
-
-=head3 C<\N{I<NAME>}> and C<charnames> enhancements
-
-=over
-
-=item *
-
-C<\N{I<NAME>}> and C<charnames::vianame> now know about the abbreviated
-character names listed by Unicode, such as NBSP, SHY, LRO, ZWJ, etc.; all
-customary abbreviations for the C0 and C1 control characters (such as
-ACK, BEL, CAN, etc.); and a few new variants of some C1 full names that
-are in common usage.
-
-=item *
-
-Unicode has several I<named character sequences>, in which particular sequences
-of code points are given names. C<\N{I<NAME>}> now recognizes these.
-
-=item *
-
-C<\N{I<NAME>}>, C<charnames::vianame>, and C<charnames::viacode>
-now know about every character in Unicode. In earlier releases of
-Perl, they didn't know about the Hangul syllables nor several
-CJK (Chinese/Japanese/Korean) characters.
-
-=item *
-
-It is now possible to override Perl's abbreviations with your own custom aliases.
-
-=item *
-
-You can now create a custom alias of the ordinal of a
-character, known by C<\N{I<NAME>}>, C<charnames::vianame()>, and
-C<charnames::viacode()>. Previously, aliases had to be to official
-Unicode character names. This made it impossible to create an alias for
-unnamed code points, such as those reserved for private
-use.
-
-=item *
-
-The new function charnames::string_vianame() is a run-time version
-of C<\N{I<NAME>}}>, returning the string of characters whose Unicode
-name is its parameter. It can handle Unicode named character
-sequences, whereas the pre-existing charnames::vianame() cannot,
-as the latter returns a single code point.
-
-=back
-
-See L<charnames> for details on all these changes.
-
-=head3 New warnings categories for problematic (non-)Unicode code points.
-
-Three new warnings subcategories of "utf8" have been added. These
-allow you to turn off some "utf8" warnings, while allowing
-other warnings to remain on. The three categories are:
-C<surrogate> when UTF-16 surrogates are encountered;
-C<nonchar> when Unicode non-character code points are encountered;
-and C<non_unicode> when code points above the legal Unicode
-maximum of 0x10FFFF are encountered.
-
-=head3 Any unsigned value can be encoded as a character
-
-With this release, Perl is adopting a model that any unsigned value
-can be treated as a code point and encoded internally (as utf8)
-without warnings, not just the code points that are legal in Unicode.
-However, unless utf8 or the corresponding sub-category (see previous
-item) of lexical warnings have been explicitly turned off, outputting
-or executing a Unicode-defined operation such as upper-casing
-on such a code point generates a warning. Attempting to input these
-using strict rules (such as with the C<:encoding(UTF-8)> layer)
-will continue to fail. Prior to this release, handling was
-inconsistent and in places, incorrect.
-
-Unicode non-characters, some of which previously were erroneously
-considered illegal in places by Perl, contrary to the Unicode Standard,
-are now always legal internally. Inputting or outputting them
-works the same as with the non-legal Unicode code points, because the Unicode
-Standard says they are (only) illegal for "open interchange".
-
-=head3 Unicode database files not installed
-
-The Unicode database files are no longer installed with Perl. This
-doesn't affect any functionality in Perl and saves significant disk
-space. If you need these files, you can download them from
-L<http://www.unicode.org/Public/zipped/6.0.0/>.
-
-=head2 Regular Expressions
-
-=head3 C<(?^...)> construct signifies default modifiers
-
-An ASCII caret C<"^"> immediately following a C<"(?"> in a regular
-expression now means that the subexpression does not inherit surrounding
-modifiers such as C</i>, but reverts to the Perl defaults. Any modifiers
-following the caret override the defaults.
-
-Stringification of regular expressions now uses this notation.
-For example, C<qr/hlagh/i> would previously be stringified as
-C<(?i-xsm:hlagh)>, but now it's stringified as C<(?^i:hlagh)>.
-
-The main purpose of this change is to allow tests that rely on the
-stringification I<not> to have to change whenever new modifiers are added.
-See L<perlre/Extended Patterns>.
-
-This change is likely to break code that compares stringified regular
-expressions with fixed strings containing C<?-xism>.
-
-=head3 C</d>, C</l>, C</u>, and C</a> modifiers
-
-Four new regular expression modifiers have been added. These are mutually
-exclusive: one only can be turned on at a time.
-
-=over
-
-=item *
-
-The C</l> modifier says to compile the regular expression as if it were
-in the scope of C<use locale>, even if it is not.
-
-=item *
-
-The C</u> modifier says to compile the regular expression as if it were
-in the scope of a C<use feature 'unicode_strings'> pragma.
-
-=item *
-
-The C</d> (default) modifier is used to override any C<use locale> and
-C<use feature 'unicode_strings'> pragmas in effect at the time
-of compiling the regular expression.
-
-=item *
-
-The C</a> regular expression modifier restricts C<\s>, C<\d> and C<\w> and
-the POSIX (C<[[:posix:]]>) character classes to the ASCII range. Their
-complements and C<\b> and C<\B> are correspondingly
-affected. Otherwise, C</a> behaves like the C</u> modifier, in that
-case-insensitive matching uses Unicode semantics.
-
-If the C</a> modifier is repeated, then additionally in case-insensitive
-matching, no ASCII character can match a non-ASCII character.
-For example,
-
- "k" =~ /\N{KELVIN SIGN}/ai
- "\xDF" =~ /ss/ai
-
-match but
-
- "k" =~ /\N{KELVIN SIGN}/aai
- "\xDF" =~ /ss/aai
-
-do not match.
-
-=back
-
-See L<perlre/Modifiers> for more detail.
-
-=head3 Non-destructive substitution
-
-The substitution (C<s///>) and transliteration
-(C<y///>) operators now support an C</r> option that
-copies the input variable, carries out the substitution on
-the copy, and returns the result. The original remains unmodified.
-
- my $old = "cat";
- my $new = $old =~ s/cat/dog/r;
- # $old is "cat" and $new is "dog"
-
-This is particularly useful with C<map>. See L<perlop> for more examples.
-
-=head3 Re-entrant regular expression engine
-
-It is now safe to use regular expressions within C<(?{...})> and
-C<(??{...})> code blocks inside regular expressions.
-
-These blocks are still experimental, however, and still have problems with
-lexical (C<my>) variables and abnormal exiting.
-
-=head3 C<use re '/flags'>
-
-The C<re> pragma now has the ability to turn on regular expression flags
-till the end of the lexical scope:
-
- use re "/x";
- "foo" =~ / (.+) /; # /x implied
-
-See L<re/"'/flags' mode"> for details.
-
-=head3 \o{...} for octals
-
-There is a new octal escape sequence, C<"\o">, in doublequote-like
-contexts. This construct allows large octal ordinals beyond the
-current max of 0777 to be represented. It also allows you to specify a
-character in octal which can safely be concatenated with other regex
-snippets and which won't be confused with being a backreference to
-a regex capture group. See L<perlre/Capture groups>.
-
-=head3 Add C<\p{Titlecase}> as a synonym for C<\p{Title}>
-
-This synonym is added for symmetry with the Unicode property names
-C<\p{Uppercase}> and C<\p{Lowercase}>.
-
-=head3 Regular expression debugging output improvement
-
-Regular expression debugging output (turned on by C<use re 'debug'>) now
-uses hexadecimal when escaping non-ASCII characters, instead of octal.
-
-=head3 Return value of C<delete $+{...}>
-
-Custom regular expression engines can now determine the return value of
-C<delete> on an entry of C<%+> or C<%->.
-
-=head2 Syntactical Enhancements
-
-=head3 Array and hash container functions accept references
-
-B<Warning:> This feature is considered experimental, as the exact behaviour
-may change in a future version of Perl.
-
-All builtin functions that operate directly on array or hash
-containers now also accept unblessed hard references to arrays
-or hashes:
-
- |----------------------------+---------------------------|
- | Traditional syntax | Terse syntax |
- |----------------------------+---------------------------|
- | push @$arrayref, @stuff | push $arrayref, @stuff |
- | unshift @$arrayref, @stuff | unshift $arrayref, @stuff |
- | pop @$arrayref | pop $arrayref |
- | shift @$arrayref | shift $arrayref |
- | splice @$arrayref, 0, 2 | splice $arrayref, 0, 2 |
- | keys %$hashref | keys $hashref |
- | keys @$arrayref | keys $arrayref |
- | values %$hashref | values $hashref |
- | values @$arrayref | values $arrayref |
- | ($k,$v) = each %$hashref | ($k,$v) = each $hashref |
- | ($k,$v) = each @$arrayref | ($k,$v) = each $arrayref |
- |----------------------------+---------------------------|
-
-This allows these builtin functions to act on long dereferencing chains
-or on the return value of subroutines without needing to wrap them in
-C<@{}> or C<%{}>:
-
- push @{$obj->tags}, $new_tag; # old way
- push $obj->tags, $new_tag; # new way
-
- for ( keys %{$hoh->{genres}{artists}} ) {...} # old way
- for ( keys $hoh->{genres}{artists} ) {...} # new way
-
-=head3 Single term prototype
-
-The C<+> prototype is a special alternative to C<$> that acts like
-C<\[@%]> when given a literal array or hash variable, but will otherwise
-force scalar context on the argument. See L<perlsub/Prototypes>.
-
-=head3 C<package> block syntax
-
-A package declaration can now contain a code block, in which case the
-declaration is in scope inside that block only. So C<package Foo { ... }>
-is precisely equivalent to C<{ package Foo; ... }>. It also works with
-a version number in the declaration, as in C<package Foo 1.2 { ... }>,
-which is its most attractive feature. See L<perlfunc>.
-
-=head3 Statement labels can appear in more places
-
-Statement labels can now occur before any type of statement or declaration,
-such as C<package>.
-
-=head3 Stacked labels
-
-Multiple statement labels can now appear before a single statement.
-
-=head3 Uppercase X/B allowed in hexadecimal/binary literals
-
-Literals may now use either upper case C<0X...> or C<0B...> prefixes,
-in addition to the already supported C<0x...> and C<0b...>
-syntax [perl #76296].
-
-C, Ruby, Python, and PHP already support this syntax, and it makes
-Perl more internally consistent: a round-trip with C<eval sprintf
-"%#X", 0x10> now returns C<16>, just like C<eval sprintf "%#x", 0x10>.
-
-=head3 Overridable tie functions
-
-C<tie>, C<tied> and C<untie> can now be overridden [perl #75902].
-
-=head2 Exception Handling
-
-To make them more reliable and consistent, several changes have been made
-to how C<die>, C<warn>, and C<$@> behave.
-
-=over
-
-=item *
-
-When an exception is thrown inside an C<eval>, the exception is no
-longer at risk of being clobbered by destructor code running during unwinding.
-Previously, the exception was written into C<$@>
-early in the throwing process, and would be overwritten if C<eval> was
-used internally in the destructor for an object that had to be freed
-while exiting from the outer C<eval>. Now the exception is written
-into C<$@> last thing before exiting the outer C<eval>, so the code
-running immediately thereafter can rely on the value in C<$@> correctly
-corresponding to that C<eval>. (C<$@> is still also set before exiting the
-C<eval>, for the sake of destructors that rely on this.)
-
-Likewise, a C<local $@> inside an C<eval> no longer clobbers any
-exception thrown in its scope. Previously, the restoration of C<$@> upon
-unwinding would overwrite any exception being thrown. Now the exception
-gets to the C<eval> anyway. So C<local $@> is safe before a C<die>.
-
-Exceptions thrown from object destructors no longer modify the C<$@>
-of the surrounding context. (If the surrounding context was exception
-unwinding, this used to be another way to clobber the exception being
-thrown.) Previously such an exception was
-sometimes emitted as a warning, and then either was
-string-appended to the surrounding C<$@> or completely replaced the
-surrounding C<$@>, depending on whether that exception and the surrounding
-C<$@> were strings or objects. Now, an exception in this situation is
-always emitted as a warning, leaving the surrounding C<$@> untouched.
-In addition to object destructors, this also affects any function call
-run by XS code using the C<G_KEEPERR> flag.
-
-=item *
-
-Warnings for C<warn> can now be objects in the same way as exceptions
-for C<die>. If an object-based warning gets the default handling
-of writing to standard error, it is stringified as before with the
-filename and line number appended. But a C<$SIG{__WARN__}> handler now
-receives an object-based warning as an object, where previously it
-was passed the result of stringifying the object.
-
-=back
-
-=head2 Other Enhancements
-
-=head3 Assignment to C<$0> sets the legacy process name with prctl() on Linux
-
-On Linux the legacy process name is now set with L<prctl(2)>, in
-addition to altering the POSIX name via C<argv[0]>, as Perl has done
-since version 4.000. Now system utilities that read the legacy process
-name such as I<ps>, I<top>, and I<killall> recognize the name you set when
-assigning to C<$0>. The string you supply is truncated at 16 bytes;
-this limitation is imposed by Linux.
-
-=head3 srand() now returns the seed
-
-This allows programs that need to have repeatable results not to have to come
-up with their own seed-generating mechanism. Instead, they can use srand()
-and stash the return value for future use. One example is a test program with
-too many combinations to test comprehensively in the time available for
-each run. It can test a random subset each time and, should there be a failure,
-log the seed used for that run so this can later be used to produce the same results.
-
-=head3 printf-like functions understand post-1980 size modifiers
-
-Perl's printf and sprintf operators, and Perl's internal printf replacement
-function, now understand the C90 size modifiers "hh" (C<char>), "z"
-(C<size_t>), and "t" (C<ptrdiff_t>). Also, when compiled with a C99
-compiler, Perl now understands the size modifier "j" (C<intmax_t>)
-(but this is not portable).
-
-So, for example, on any modern machine, C<sprintf("%hhd", 257)> returns "1".
-
-=head3 New global variable C<${^GLOBAL_PHASE}>
-
-A new global variable, C<${^GLOBAL_PHASE}>, has been added to allow
-introspection of the current phase of the Perl interpreter. It's explained in
-detail in L<perlvar/"${^GLOBAL_PHASE}"> and in
-L<perlmod/"BEGIN, UNITCHECK, CHECK, INIT and END">.
-
-=head3 C<-d:-foo> calls C<Devel::foo::unimport>
-
-The syntax B<-d:foo> was extended in 5.6.1 to make B<-d:foo=bar>
-equivalent to B<-MDevel::foo=bar>, which expands
-internally to C<use Devel::foo 'bar'>.
-Perl now allows prefixing the module name with B<->, with the same
-semantics as B<-M>; that is:
-
-=over 4
-
-=item C<-d:-foo>
-
-Equivalent to B<-M-Devel::foo>: expands to
-C<no Devel::foo> and calls C<< Devel::foo->unimport() >>
-if that method exists.
-
-=item C<-d:-foo=bar>
-
-Equivalent to B<-M-Devel::foo=bar>: expands to C<no Devel::foo 'bar'>,
-and calls C<< Devel::foo->unimport("bar") >> if that method exists.
-
-=back
-
-This is particularly useful for suppressing the default actions of a
-C<Devel::*> module's C<import> method whilst still loading it for debugging.
-
-=head3 Filehandle method calls load L<IO::File> on demand
-
-When a method call on a filehandle would die because the method cannot
-be resolved and L<IO::File> has not been loaded, Perl now loads L<IO::File>
-via C<require> and attempts method resolution again:
-
- open my $fh, ">", $file;
- $fh->binmode(":raw"); # loads IO::File and succeeds
-
-This also works for globs like C<STDOUT>, C<STDERR>, and C<STDIN>:
-
- STDOUT->autoflush(1);
-
-Because this on-demand load happens only if method resolution fails, the
-legacy approach of manually loading an L<IO::File> parent class for partial
-method support still works as expected:
-
- use IO::Handle;
- open my $fh, ">", $file;
- $fh->autoflush(1); # IO::File not loaded
-
-=head3 Improved IPv6 support
-
-The C<Socket> module provides new affordances for IPv6,
-including implementations of the C<Socket::getaddrinfo()> and
-C<Socket::getnameinfo()> functions, along with related constants and a
-handful of new functions. See L<Socket>.
-
-=head3 DTrace probes now include package name
-
-The C<DTrace> probes now include an additional argument, C<arg3>, which contains
-the package the subroutine being entered or left was compiled in.
-
-For example, using the following DTrace script:
-
- perl$target:::sub-entry
- {
- printf("%s::%s\n", copyinstr(arg0), copyinstr(arg3));
- }
-
-and then running:
-
- $ perl -e 'sub test { }; test'
-
-C<DTrace> will print:
-
- main::test
-
-=head2 New C APIs
-
-See L</Internal Changes>.
-
-=head1 Security
-
-=head2 User-defined regular expression properties
-
-L<perlunicode/"User-Defined Character Properties"> documented that you can
-create custom properties by defining subroutines whose names begin with
-"In" or "Is". However, Perl did not actually enforce that naming
-restriction, so C<\p{foo::bar}> could call foo::bar() if it existed. The documented
-convention is now enforced.
-
-Also, Perl no longer allows tainted regular expressions to invoke a
-user-defined property. It simply dies instead [perl #82616].
-
-=head1 Incompatible Changes
-
-Perl 5.14.0 is not binary-compatible with any previous stable release.
-
-In addition to the sections that follow, see L</C API Changes>.
-
-=head2 Regular Expressions and String Escapes
-
-=head3 Inverted bracketed character classes and multi-character folds
-
-Some characters match a sequence of two or three characters in C</i>
-regular expression matching under Unicode rules. One example is
-C<LATIN SMALL LETTER SHARP S> which matches the sequence C<ss>.
-
- 'ss' =~ /\A[\N{LATIN SMALL LETTER SHARP S}]\z/i # Matches
-
-This, however, can lead to very counter-intuitive results, especially
-when inverted. Because of this, Perl 5.14 does not use multi-character C</i>
-matching in inverted character classes.
-
- 'ss' =~ /\A[^\N{LATIN SMALL LETTER SHARP S}]+\z/i # ???
-
-This should match any sequences of characters that aren't the C<SHARP S>
-nor what C<SHARP S> matches under C</i>. C<"s"> isn't C<SHARP S>, but
-Unicode says that C<"ss"> is what C<SHARP S> matches under C</i>. So
-which one "wins"? Do you fail the match because the string has C<ss> or
-accept it because it has an C<s> followed by another C<s>?
-
-Earlier releases of Perl did allow this multi-character matching,
-but due to bugs, it mostly did not work.
-
-=head3 \400-\777
-
-In certain circumstances, C<\400>-C<\777> in regexes have behaved
-differently than they behave in all other doublequote-like contexts.
-Since 5.10.1, Perl has issued a deprecation warning when this happens.
-Now, these literals behave the same in all doublequote-like contexts,
-namely to be equivalent to C<\x{100}>-C<\x{1FF}>, with no deprecation
-warning.
-
-Use of C<\400>-C<\777> in the command-line option B<-0> retain their
-conventional meaning. They slurp whole input files; previously, this
-was documented only for B<-0777>.
-
-Because of various ambiguities, you should use the new
-C<\o{...}> construct to represent characters in octal instead.
-
-=head3 Most C<\p{}> properties are now immune to case-insensitive matching
-
-For most Unicode properties, it doesn't make sense to have them match
-differently under C</i> case-insensitive matching. Doing so can lead
-to unexpected results and potential security holes. For example
-
- m/\p{ASCII_Hex_Digit}+/i
-
-could previously match non-ASCII characters because of the Unicode
-matching rules (although there were several bugs with this). Now
-matching under C</i> gives the same results as non-C</i> matching except
-for those few properties where people have come to expect differences,
-namely the ones where casing is an integral part of their meaning, such
-as C<m/\p{Uppercase}/i> and C<m/\p{Lowercase}/i>, both of which match
-the same code points as matched by C<m/\p{Cased}/i>.
-Details are in L<perlrecharclass/Unicode Properties>.
-
-User-defined property handlers that need to match differently under C</i>
-must be changed to read the new boolean parameter passed to them, which
-is non-zero if case-insensitive matching is in effect and 0 otherwise.
-See L<perlunicode/User-Defined Character Properties>.
-
-=head3 \p{} implies Unicode semantics
-
-Specifying a Unicode property in the pattern indicates
-that the pattern is meant for matching according to Unicode rules, the way
-C<\N{I<NAME>}> does.
-
-=head3 Regular expressions retain their localeness when interpolated
-
-Regular expressions compiled under C<use locale> now retain this when
-interpolated into a new regular expression compiled outside a
-C<use locale>, and vice-versa.
-
-Previously, one regular expression interpolated into another inherited
-the localeness of the surrounding regex, losing whatever state it
-originally had. This is considered a bug fix, but may trip up code that
-has come to rely on the incorrect behaviour.
-
-=head3 Stringification of regexes has changed
-
-Default regular expression modifiers are now notated using
-C<(?^...)>. Code relying on the old stringification will fail.
-This is so that when new modifiers are added, such code won't
-have to keep changing each time this happens, because the stringification
-will automatically incorporate the new modifiers.
-
-Code that needs to work properly with both old- and new-style regexes
-can avoid the whole issue by using (for perls since 5.9.5; see L<re>):
-
- use re qw(regexp_pattern);
- my ($pat, $mods) = regexp_pattern($re_ref);
-
-If the actual stringification is important or older Perls need to be
-supported, you can use something like the following:
-
- # Accept both old and new-style stringification
- my $modifiers = (qr/foobar/ =~ /\Q(?^/) ? "^" : "-xism";
-
-And then use C<$modifiers> instead of C<-xism>.
-
-=head3 Run-time code blocks in regular expressions inherit pragmata
-
-Code blocks in regular expressions (C<(?{...})> and C<(??{...})>) previously
-did not inherit pragmata (strict, warnings, etc.) if the regular expression
-was compiled at run time as happens in cases like these two:
-
- use re "eval";
- $foo =~ $bar; # when $bar contains (?{...})
- $foo =~ /$bar(?{ $finished = 1 })/;
-
-This bug has now been fixed, but code that relied on the buggy behaviour
-may need to be fixed to account for the correct behaviour.
-
-=head2 Stashes and Package Variables
-
-=head3 Localised tied hashes and arrays are no longed tied
-
-In the following:
-
- tie @a, ...;
- {
- local @a;
- # here, @a is a now a new, untied array
- }
- # here, @a refers again to the old, tied array
-
-Earlier versions of Perl incorrectly tied the new local array. This has
-now been fixed. This fix could however potentially cause a change in
-behaviour of some code.
-
-=head3 Stashes are now always defined
-
-C<defined %Foo::> now always returns true, even when no symbols have yet been
-defined in that package.
-
-This is a side-effect of removing a special-case kludge in the tokeniser,
-added for 5.10.0, to hide side-effects of changes to the internal storage of
-hashes. The fix drastically reduces hashes' memory overhead.
-
-Calling defined on a stash has been deprecated since 5.6.0, warned on
-lexicals since 5.6.0, and warned for stashes and other package
-variables since 5.12.0. C<defined %hash> has always exposed an
-implementation detail: emptying a hash by deleting all entries from it does
-not make C<defined %hash> false. Hence C<defined %hash> is not valid code to
-determine whether an arbitrary hash is empty. Instead, use the behaviour
-of an empty C<%hash> always returning false in scalar context.
-
-=head3 Clearing stashes
-
-Stash list assignment C<%foo:: = ()> used to make the stash temporarily
-anonymous while it was being emptied. Consequently, any of its
-subroutines referenced elsewhere would become anonymous, showing up as
-"(unknown)" in C<caller>. They now retain their package names such that
-C<caller> returns the original sub name if there is still a reference
-to its typeglob and "foo::__ANON__" otherwise [perl #79208].
-
-=head3 Dereferencing typeglobs
-
-If you assign a typeglob to a scalar variable:
-
- $glob = *foo;
-
-the glob that is copied to C<$glob> is marked with a special flag
-indicating that the glob is just a copy. This allows subsequent
-assignments to C<$glob> to overwrite the glob. The original glob,
-however, is immutable.
-
-Some Perl operators did not distinguish between these two types of globs.
-This would result in strange behaviour in edge cases: C<untie $scalar>
-would not untie the scalar if the last thing assigned to it was a glob
-(because it treated it as C<untie *$scalar>, which unties a handle).
-Assignment to a glob slot (such as C<*$glob = \@some_array>) would simply
-assign C<\@some_array> to C<$glob>.
-
-To fix this, the C<*{}> operator (including its C<*foo> and C<*$foo> forms)
-has been modified to make a new immutable glob if its operand is a glob
-copy. This allows operators that make a distinction between globs and
-scalars to be modified to treat only immutable globs as globs. (C<tie>,
-C<tied> and C<untie> have been left as they are for compatibility's sake,
-but will warn. See L</Deprecations>.)
-
-This causes an incompatible change in code that assigns a glob to the
-return value of C<*{}> when that operator was passed a glob copy. Take the
-following code, for instance:
-
- $glob = *foo;
- *$glob = *bar;
-
-The C<*$glob> on the second line returns a new immutable glob. That new
-glob is made an alias to C<*bar>. Then it is discarded. So the second
-assignment has no effect.
-
-See L<http://rt.perl.org/rt3/Public/Bug/Display.html?id=77810> for
-more detail.
-
-=head3 Magic variables outside the main package
-
-In previous versions of Perl, magic variables like C<$!>, C<%SIG>, etc. would
-"leak" into other packages. So C<%foo::SIG> could be used to access signals,
-C<${"foo::!"}> (with strict mode off) to access C's C<errno>, etc.
-
-This was a bug, or an "unintentional" feature, which caused various ill effects,
-such as signal handlers being wiped when modules were loaded, etc.
-
-This has been fixed (or the feature has been removed, depending on how you see
-it).
-
-=head3 local($_) strips all magic from $_
-
-local() on scalar variables gives them a new value but keeps all
-their magic intact. This has proven problematic for the default
-scalar variable $_, where L<perlsub> recommends that any subroutine
-that assigns to $_ should first localize it. This would throw an
-exception if $_ is aliased to a read-only variable, and could in general have
-various unintentional side-effects.
-
-Therefore, as an exception to the general rule, local($_) will not
-only assign a new value to $_, but also remove all existing magic from
-it as well.
-
-=head3 Parsing of package and variable names
-
-Parsing the names of packages and package variables has changed:
-multiple adjacent pairs of colons, as in C<foo::::bar>, are now all
-treated as package separators.
-
-Regardless of this change, the exact parsing of package separators has
-never been guaranteed and is subject to change in future Perl versions.
-
-=head2 Changes to Syntax or to Perl Operators
-
-=head3 C<given> return values
-
-C<given> blocks now return the last evaluated
-expression, or an empty list if the block was exited by C<break>. Thus you
-can now write:
-
- my $type = do {
- given ($num) {
- break when undef;
- "integer" when /^[+-]?[0-9]+$/;
- "float" when /^[+-]?[0-9]+(?:\.[0-9]+)?$/;
- "unknown";
- }
- };
-
-See L<perlsyn/Return value> for details.
-
-=head3 Change in parsing of certain prototypes
-
-Functions declared with the following prototypes now behave correctly as unary
-functions:
-
- *
- \$ \% \@ \* \&
- \[...]
- ;$ ;*
- ;\$ ;\% etc.
- ;\[...]
-
-Due to this bug fix [perl #75904], functions
-using the C<(*)>, C<(;$)> and C<(;*)> prototypes
-are parsed with higher precedence than before. So
-in the following example:
-
- sub foo(;$);
- foo $a < $b;
-
-the second line is now parsed correctly as C<< foo($a) < $b >>, rather than
-C<< foo($a < $b) >>. This happens when one of these operators is used in
-an unparenthesised argument:
-
- < > <= >= lt gt le ge
- == != <=> eq ne cmp ~~
- &
- | ^
- &&
- || //
- .. ...
- ?:
- = += -= *= etc.
- , =>
-
-=head3 Smart-matching against array slices
-
-Previously, the following code resulted in a successful match:
-
- my @a = qw(a y0 z);
- my @b = qw(a x0 z);
- @a[0 .. $#b] ~~ @b;
-
-This odd behaviour has now been fixed [perl #77468].
-
-=head3 Negation treats strings differently from before
-
-The unary negation operator, C<->, now treats strings that look like numbers
-as numbers [perl #57706].
-
-=head3 Negative zero
-
-Negative zero (-0.0), when converted to a string, now becomes "0" on all
-platforms. It used to become "-0" on some, but "0" on others.
-
-If you still need to determine whether a zero is negative, use
-C<sprintf("%g", $zero) =~ /^-/> or the L<Data::Float> module on CPAN.
-
-=head3 C<:=> is now a syntax error
-
-Previously C<my $pi := 4> was exactly equivalent to C<my $pi : = 4>,
-with the C<:> being treated as the start of an attribute list, ending before
-the C<=>. The use of C<:=> to mean C<: => was deprecated in 5.12.0, and is
-now a syntax error. This allows future use of C<:=> as a new token.
-
-Outside the core's tests for it, we find no Perl 5 code on CPAN
-using this construction, so we believe that this change will have
-little impact on real-world codebases.
-
-If it is absolutely necessary to have empty attribute lists (for example,
-because of a code generator), simply avoid the error by adding a space before
-the C<=>.
-
-=head3 Change in the parsing of identifiers
-
-Characters outside the Unicode "XIDStart" set are no longer allowed at the
-beginning of an identifier. This means that certain accents and marks
-that normally follow an alphabetic character may no longer be the first
-character of an identifier.
-
-=head2 Threads and Processes
-
-=head3 Directory handles not copied to threads
-
-On systems other than Windows that do not have
-a C<fchdir> function, newly-created threads no
-longer inherit directory handles from their parent threads. Such programs
-would usually have crashed anyway [perl #75154].
-
-=head3 C<close> on shared pipes
-
-To avoid deadlocks, the C<close> function no longer waits for the
-child process to exit if the underlying file descriptor is still
-in use by another thread. It returns true in such cases.
-
-=head3 fork() emulation will not wait for signalled children
-
-On Windows parent processes would not terminate until all forked
-children had terminated first. However, C<kill("KILL", ...)> is
-inherently unstable on pseudo-processes, and C<kill("TERM", ...)>
-might not get delivered if the child is blocked in a system call.
-
-To avoid the deadlock and still provide a safe mechanism to terminate
-the hosting process, Perl now no longer waits for children that
-have been sent a SIGTERM signal. It is up to the parent process to
-waitpid() for these children if child-cleanup processing must be
-allowed to finish. However, it is also then the responsibility of the
-parent to avoid the deadlock by making sure the child process
-can't be blocked on I/O.
-
-See L<perlfork> for more information about the fork() emulation on
-Windows.
-
-=head2 Configuration
-
-=head3 Naming fixes in Policy_sh.SH may invalidate Policy.sh
-
-Several long-standing typos and naming confusions in F<Policy_sh.SH> have
-been fixed, standardizing on the variable names used in F<config.sh>.
-
-This will change the behaviour of F<Policy.sh> if you happen to have been
-accidentally relying on its incorrect behaviour.
-
-=head3 Perl source code is read in text mode on Windows
-
-Perl scripts used to be read in binary mode on Windows for the benefit
-of the L<ByteLoader> module (which is no longer part of core Perl). This
-had the side-effect of breaking various operations on the C<DATA> filehandle,
-including seek()/tell(), and even simply reading from C<DATA> after filehandles
-have been flushed by a call to system(), backticks, fork() etc.
-
-The default build options for Windows have been changed to read Perl source
-code on Windows in text mode now. L<ByteLoader> will (hopefully) be updated on
-CPAN to automatically handle this situation [perl #28106].
-
-=head1 Deprecations
-
-See also L</Deprecated C APIs>.
-
-=head2 Omitting a space between a regular expression and subsequent word
-
-Omitting the space between a regular expression operator or
-its modifiers and the following word is deprecated. For
-example, C<< m/foo/sand $bar >> is for now still parsed
-as C<< m/foo/s and $bar >>, but will now issue a warning.
-
-=head2 C<\cI<X>>
-
-The backslash-c construct was designed as a way of specifying
-non-printable characters, but there were no restrictions (on ASCII
-platforms) on what the character following the C<c> could be. Now,
-a deprecation warning is raised if that character isn't an ASCII character.
-Also, a deprecation warning is raised for C<"\c{"> (which is the same
-as simply saying C<";">).
-
-=head2 C<"\b{"> and C<"\B{">
-
-In regular expressions, a literal C<"{"> immediately following a C<"\b">
-(not in a bracketed character class) or a C<"\B{"> is now deprecated
-to allow for its future use by Perl itself.
-
-=head2 Perl 4-era .pl libraries
-
-Perl bundles a handful of library files that predate Perl 5.
-This bundling is now deprecated for most of these files, which are now
-available from CPAN. The affected files now warn when run, if they were
-installed as part of the core.
-
-This is a mandatory warning, not obeying B<-X> or lexical warning bits.
-The warning is modelled on that supplied by F<deprecate.pm> for
-deprecated-in-core F<.pm> libraries. It points to the specific CPAN
-distribution that contains the F<.pl> libraries. The CPAN versions, of
-course, do not generate the warning.
-
-=head2 List assignment to C<$[>
-
-Assignment to C<$[> was deprecated and started to give warnings in
-Perl version 5.12.0. This version of Perl (5.14) now also emits a warning
-when assigning to C<$[> in list context. This fixes an oversight in 5.12.0.
-
-=head2 Use of qw(...) as parentheses
-
-Historically the parser fooled itself into thinking that C<qw(...)> literals
-were always enclosed in parentheses, and as a result you could sometimes omit
-parentheses around them:
-
- for $x qw(a b c) { ... }
-
-The parser no longer lies to itself in this way. Wrap the list literal in
-parentheses like this:
-
- for $x (qw(a b c)) { ... }
-
-This is being deprecated because the parentheses in C<for $i (1,2,3) { ... }>
-are not part of expression syntax. They are part of the statement
-syntax, with the C<for> statement wanting literal parentheses.
-The synthetic parentheses that a C<qw> expression acquired were only
-intended to be treated as part of expression syntax.
-
-Note that this does not change the behaviour of cases like:
-
- use POSIX qw(setlocale localeconv);
- our @EXPORT = qw(foo bar baz);
-
-where parentheses were never required around the expression.
-
-=head2 C<\N{BELL}>
-
-This is because Unicode is using that name for a different character.
-See L</Unicode Version 6.0 is now supported (mostly)> for more
-explanation.
-
-=head2 C<?PATTERN?>
-
-C<?PATTERN?> (without the initial C<m>) has been deprecated and now produces
-a warning. This is to allow future use of C<?> in new operators.
-The match-once functionality is still available as C<m?PATTERN?>.
-
-=head2 Tie functions on scalars holding typeglobs
-
-Calling a tie function (C<tie>, C<tied>, C<untie>) with a scalar argument
-acts on a filehandle if the scalar happens to hold a typeglob.
-
-This is a long-standing bug that will be removed in Perl 5.16, as
-there is currently no way to tie the scalar itself when it holds
-a typeglob, and no way to untie a scalar that has had a typeglob
-assigned to it.
-
-Now there is a deprecation warning whenever a tie
-function is used on a handle without an explicit C<*>.
-
-=head2 User-defined case-mapping
-
-This feature is being deprecated due to its many issues, as documented in
-L<perlunicode/User-Defined Case Mappings (for serious hackers only)>.
-This feature will be removed in Perl 5.16. Instead use the CPAN module
-L<Unicode::Casing>, which provides improved functionality.
-
-=head2 Deprecated modules
-
-The following module will be removed from the core distribution in a
-future release, and should be installed from CPAN instead. Distributions
-on CPAN that require this should add it to their prerequisites. The
-core version of these module now issues a deprecation warning.
-
-If you ship a packaged version of Perl, either alone or as part of a
-larger system, then you should carefully consider the repercussions of
-core module deprecations. You may want to consider shipping your default
-build of Perl with a package for the deprecated module that
-installs into C<vendor> or C<site> Perl library directories. This will
-inhibit the deprecation warnings.
-
-Alternatively, you may want to consider patching F<lib/deprecate.pm>
-to provide deprecation warnings specific to your packaging system
-or distribution of Perl, consistent with how your packaging system
-or distribution manages a staged transition from a release where the
-installation of a single package provides the given functionality, to
-a later release where the system administrator needs to know to install
-multiple packages to get that same functionality.
-
-You can silence these deprecation warnings by installing the module
-in question from CPAN. To install the latest version of it by role
-rather than by name, just install C<Task::Deprecations::5_14>.
-
-=over
-
-=item L<Devel::DProf>
-
-We strongly recommend that you install and use L<Devel::NYTProf> instead
-of L<Devel::DProf>, as L<Devel::NYTProf> offers significantly
-improved profiling and reporting.
-
-=back
-
-=head1 Performance Enhancements
-
-=head2 "Safe signals" optimisation
-
-Signal dispatch has been moved from the runloop into control ops.
-This should give a few percent speed increase, and eliminates nearly
-all the speed penalty caused by the introduction of "safe signals"
-in 5.8.0. Signals should still be dispatched within the same
-statement as they were previously. If this does I<not> happen, or
-if you find it possible to create uninterruptible loops, this is a
-bug, and reports are encouraged of how to recreate such issues.
-
-=head2 Optimisation of shift() and pop() calls without arguments
-
-Two fewer OPs are used for shift() and pop() calls with no argument (with
-implicit C<@_>). This change makes shift() 5% faster than C<shift @_>
-on non-threaded perls, and 25% faster on threaded ones.
-
-=head2 Optimisation of regexp engine string comparison work
-
-The C<foldEQ_utf8> API function for case-insensitive comparison of strings (which
-is used heavily by the regexp engine) was substantially refactored and
-optimised -- and its documentation much improved as a free bonus.
-
-=head2 Regular expression compilation speed-up
-
-Compiling regular expressions has been made faster when upgrading
-the regex to utf8 is necessary but this isn't known when the compilation begins.
-
-=head2 String appending is 100 times faster
-
-When doing a lot of string appending, perls built to use the system's
-C<malloc> could end up allocating a lot more memory than needed in a
-inefficient way.
-
-C<sv_grow>, the function used to allocate more memory if necessary
-when appending to a string, has been taught to round up the memory
-it requests to a certain geometric progression, making it much faster on
-certain platforms and configurations. On Win32, it's now about 100 times
-faster.
-
-=head2 Eliminate C<PL_*> accessor functions under ithreads
-
-When C<MULTIPLICITY> was first developed, and interpreter state moved into
-an interpreter struct, thread- and interpreter-local C<PL_*> variables
-were defined as macros that called accessor functions (returning the
-address of the value) outside the Perl core. The intent was to allow
-members within the interpreter struct to change size without breaking
-binary compatibility, so that bug fixes could be merged to a maintenance
-branch that necessitated such a size change. This mechanism was redundant
-and penalised well-behaved code. It has been removed.
-
-=head2 Freeing weak references
-
-When there are many weak references to an object, freeing that object
-can under some circumstances take O(I<N*N>) time to free, where
-I<N> is the number of references. The circumstances in which this can happen
-have been reduced [perl #75254]
-
-=head2 Lexical array and hash assignments
-
-An earlier optimisation to speed up C<my @array = ...> and
-C<my %hash = ...> assignments caused a bug and was disabled in Perl 5.12.0.
-
-Now we have found another way to speed up these assignments [perl #82110].
-
-=head2 C<@_> uses less memory
-
-Previously, C<@_> was allocated for every subroutine at compile time with
-enough space for four entries. Now this allocation is done on demand when
-the subroutine is called [perl #72416].
-
-=head2 Size optimisations to SV and HV structures
-
-C<xhv_fill> has been eliminated from C<struct xpvhv>, saving 1 IV per hash and
-on some systems will cause C<struct xpvhv> to become cache-aligned. To avoid
-this memory saving causing a slowdown elsewhere, boolean use of C<HvFILL>
-now calls C<HvTOTALKEYS> instead (which is equivalent), so while the fill
-data when actually required are now calculated on demand, cases when
-this needs to be done should be rare.
-
-The order of structure elements in SV bodies has changed. Effectively,
-the NV slot has swapped location with STASH and MAGIC. As all access to
-SV members is via macros, this should be completely transparent. This
-change allows the space saving for PVHVs documented above, and may reduce
-the memory allocation needed for PVIVs on some architectures.
-
-C<XPV>, C<XPVIV>, and C<XPVNV> now allocate only the parts of the C<SV> body
-they actually use, saving some space.
-
-Scalars containing regular expressions now allocate only the part of the C<SV>
-body they actually use, saving some space.
-
-=head2 Memory consumption improvements to Exporter
-
-The C<@EXPORT_FAIL> AV is no longer created unless needed, hence neither is
-the typeglob backing it. This saves about 200 bytes for every package that
-uses Exporter but doesn't use this functionality.
-
-=head2 Memory savings for weak references
-
-For weak references, the common case of just a single weak reference
-per referent has been optimised to reduce the storage required. In this
-case it saves the equivalent of one small Perl array per referent.
-
-=head2 C<%+> and C<%-> use less memory
-
-The bulk of the C<Tie::Hash::NamedCapture> module used to be in the Perl
-core. It has now been moved to an XS module to reduce overhead for
-programs that do not use C<%+> or C<%->.
-
-=head2 Multiple small improvements to threads
-
-The internal structures of threading now make fewer API calls and fewer
-allocations, resulting in noticeably smaller object code. Additionally,
-many thread context checks have been deferred so they're done only
-as needed (although this is only possible for non-debugging builds).
-
-=head2 Adjacent pairs of nextstate opcodes are now optimized away
-
-Previously, in code such as
-
- use constant DEBUG => 0;
-
- sub GAK {
- warn if DEBUG;
- print "stuff\n";
- }
-
-the ops for C<warn if DEBUG> would be folded to a C<null> op (C<ex-const>), but
-the C<nextstate> op would remain, resulting in a runtime op dispatch of
-C<nextstate>, C<nextstate>, etc.
-
-The execution of a sequence of C<nextstate> ops is indistinguishable from just
-the last C<nextstate> op so the peephole optimizer now eliminates the first of
-a pair of C<nextstate> ops except when the first carries a label, since labels
-must not be eliminated by the optimizer, and label usage isn't conclusively known
-at compile time.
-
-=head1 Modules and Pragmata
-
-=head2 New Modules and Pragmata
-
-=over 4
-
-=item *
-
-L<CPAN::Meta::YAML> 0.003 has been added as a dual-life module. It supports a
-subset of YAML sufficient for reading and writing F<META.yml> and F<MYMETA.yml> files
-included with CPAN distributions or generated by the module installation
-toolchain. It should not be used for any other general YAML parsing or
-generation task.
-
-=item *
-
-L<CPAN::Meta> version 2.110440 has been added as a dual-life module. It
-provides a standard library to read, interpret and write CPAN distribution
-metadata files (like F<META.json> and F<META.yml)> that describe a
-distribution, its contents, and the requirements for building it and
-installing it. The latest CPAN distribution metadata specification is
-included as L<CPAN::Meta::Spec> and notes on changes in the specification
-over time are given in L<CPAN::Meta::History>.
-
-=item *
-
-L<HTTP::Tiny> 0.012 has been added as a dual-life module. It is a very
-small, simple HTTP/1.1 client designed for simple GET requests and file
-mirroring. It has been added so that F<CPAN.pm> and L<CPANPLUS> can
-"bootstrap" HTTP access to CPAN using pure Perl without relying on external
-binaries like L<curl(1)> or L<wget(1)>.
-
-=item *
-
-L<JSON::PP> 2.27105 has been added as a dual-life module to allow CPAN
-clients to read F<META.json> files in CPAN distributions.
-
-=item *
-
-L<Module::Metadata> 1.000004 has been added as a dual-life module. It gathers
-package and POD information from Perl module files. It is a standalone module
-based on L<Module::Build::ModuleInfo> for use by other module installation
-toolchain components. L<Module::Build::ModuleInfo> has been deprecated in
-favor of this module instead.
-
-=item *
-
-L<Perl::OSType> 1.002 has been added as a dual-life module. It maps Perl
-operating system names (like "dragonfly" or "MSWin32") to more generic types
-with standardized names (like "Unix" or "Windows"). It has been refactored
-out of L<Module::Build> and L<ExtUtils::CBuilder> and consolidates such mappings into
-a single location for easier maintenance.
-
-=item *
-
-The following modules were added by the L<Unicode::Collate>
-upgrade. See below for details.
-
-L<Unicode::Collate::CJK::Big5>
-
-L<Unicode::Collate::CJK::GB2312>
-
-L<Unicode::Collate::CJK::JISX0208>
-
-L<Unicode::Collate::CJK::Korean>
-
-L<Unicode::Collate::CJK::Pinyin>
-
-L<Unicode::Collate::CJK::Stroke>
-
-=item *
-
-L<Version::Requirements> version 0.101020 has been added as a dual-life
-module. It provides a standard library to model and manipulates module
-prerequisites and version constraints defined in L<CPAN::Meta::Spec>.
-
-=back
-
-=head2 Updated Modules and Pragma
-
-=over 4
-
-=item *
-
-L<attributes> has been upgraded from version 0.12 to 0.14.
-
-=item *
-
-L<Archive::Extract> has been upgraded from version 0.38 to 0.48.
-
-Updates since 0.38 include: a safe print method that guards
-L<Archive::Extract> from changes to C<$\>; a fix to the tests when run in core
-Perl; support for TZ files; a modification for the lzma
-logic to favour L<IO::Uncompress::Unlzma>; and a fix
-for an issue with NetBSD-current and its new L<unzip(1)>
-executable.
-
-=item *
-
-L<Archive::Tar> has been upgraded from version 1.54 to 1.76.
-
-Important changes since 1.54 include the following:
-
-=over
-
-=item *
-
-Compatibility with busybox implementations of L<tar(1)>.
-
-=item *
-
-A fix so that write() and create_archive()
-close only filehandles they themselves opened.
-
-=item *
-
-A bug was fixed regarding the exit code of extract_archive.
-
-=item *
-
-The L<ptar(1)> utility has a new option to allow safe creation of
-tarballs without world-writable files on Windows, allowing those
-archives to be uploaded to CPAN.
-
-=item *
-
-A new L<ptargrep(1)> utility for using regular expressions against
-the contents of files in a tar archive.
-
-=item *
-
-L<pax> extended headers are now skipped.
-
-=back
-
-=item *
-
-L<Attribute::Handlers> has been upgraded from version 0.87 to 0.89.
-
-=item *
-
-L<autodie> has been upgraded from version 2.06_01 to 2.1001.
-
-=item *
-
-L<AutoLoader> has been upgraded from version 5.70 to 5.71.
-
-=item *
-
-The L<B> module has been upgraded from version 1.23 to 1.29.
-
-It no longer crashes when taking apart a C<y///> containing characters
-outside the octet range or compiled in a C<use utf8> scope.
-
-The size of the shared object has been reduced by about 40%, with no
-reduction in functionality.
-
-=item *
-
-L<B::Concise> has been upgraded from version 0.78 to 0.83.
-
-L<B::Concise> marks rv2sv(), rv2av(), and rv2hv() ops with the new
-C<OPpDEREF> flag as "DREFed".
-
-It no longer produces mangled output with the B<-tree> option
-[perl #80632].
-
-=item *
-
-L<B::Debug> has been upgraded from version 1.12 to 1.16.
-
-=item *
-
-L<B::Deparse> has been upgraded from version 0.96 to 1.03.
-
-The deparsing of a C<nextstate> op has changed when it has both a
-change of package relative to the previous nextstate, or a change of
-C<%^H> or other state and a label. The label was previously emitted
-first, but is now emitted last (5.12.1).
-
-The C<no 5.13.2> or similar form is now correctly handled by L<B::Deparse>
-(5.12.3).
-
-L<B::Deparse> now properly handles the code that applies a conditional
-pattern match against implicit C<$_> as it was fixed in [perl #20444].
-
-Deparsing of C<our> followed by a variable with funny characters
-(as permitted under the C<use utf8> pragma) has also been fixed [perl #33752].
-
-=item *
-
-L<B::Lint> has been upgraded from version 1.11_01 to 1.13.
-
-=item *
-
-L<base> has been upgraded from version 2.15 to 2.16.
-
-=item *
-
-L<Benchmark> has been upgraded from version 1.11 to 1.12.
-
-=item *
-
-L<bignum> has been upgraded from version 0.23 to 0.27.
-
-=item *
-
-L<Carp> has been upgraded from version 1.15 to 1.20.
-
-L<Carp> now detects incomplete L<caller()|perlfunc/"caller EXPR">
-overrides and avoids using bogus C<@DB::args>. To provide backtraces,
-Carp relies on particular behaviour of the caller() builtin.
-L<Carp> now detects if other code has overridden this with an
-incomplete implementation, and modifies its backtrace accordingly.
-Previously incomplete overrides would cause incorrect values in
-backtraces (best case), or obscure fatal errors (worst case).
-
-This fixes certain cases of "Bizarre copy of ARRAY" caused by modules
-overriding caller() incorrectly (5.12.2).
-
-It now also avoids using regular expressions that cause Perl to
-load its Unicode tables, so as to avoid the "BEGIN not safe after
-errors" error that ensue if there has been a syntax error
-[perl #82854].
-
-=item *
-
-L<CGI> has been upgraded from version 3.48 to 3.52.
-
-This provides the following security fixes: the MIME boundary in
-multipart_init() is now random and the handling of
-newlines embedded in header values has been improved.
-
-=item *
-
-L<Compress::Raw::Bzip2> has been upgraded from version 2.024 to 2.033.
-
-It has been updated to use L<bzip2(1)> 1.0.6.
-
-=item *
-
-L<Compress::Raw::Zlib> has been upgraded from version 2.024 to 2.033.
-
-=item *
-
-L<constant> has been upgraded from version 1.20 to 1.21.
-
-Unicode constants work once more. They have been broken since Perl 5.10.0
-[CPAN RT #67525].
-
-=item *
-
-L<CPAN> has been upgraded from version 1.94_56 to 1.9600.
-
-Major highlights:
-
-=over 4
-
-=item * much less configuration dialog hassle
-
-=item * support for F<META/MYMETA.json>
-
-=item * support for L<local::lib>
-
-=item * support for L<HTTP::Tiny> to reduce the dependency on FTP sites
-
-=item * automatic mirror selection
-
-=item * iron out all known bugs in configure_requires
-
-=item * support for distributions compressed with L<bzip2(1)>
-
-=item * allow F<Foo/Bar.pm> on the command line to mean C<Foo::Bar>
-
-=back
-
-=item *
-
-L<CPANPLUS> has been upgraded from version 0.90 to 0.9103.
-
-A change to F<cpanp-run-perl>
-resolves L<RT #55964|http://rt.cpan.org/Public/Bug/Display.html?id=55964>
-and L<RT #57106|http://rt.cpan.org/Public/Bug/Display.html?id=57106>, both
-of which related to failures to install distributions that use
-C<Module::Install::DSL> (5.12.2).
-
-A dependency on L<Config> was not recognised as a
-core module dependency. This has been fixed.
-
-L<CPANPLUS> now includes support for F<META.json> and F<MYMETA.json>.
-
-=item *
-
-L<CPANPLUS::Dist::Build> has been upgraded from version 0.46 to 0.54.
-
-=item *
-
-L<Data::Dumper> has been upgraded from version 2.125 to 2.130_02.
-
-The indentation used to be off when C<$Data::Dumper::Terse> was set. This
-has been fixed [perl #73604].
-
-This upgrade also fixes a crash when using custom sort functions that might
-cause the stack to change [perl #74170].
-
-L<Dumpxs> no longer crashes with globs returned by C<*$io_ref>
-[perl #72332].
-
-=item *
-
-L<DB_File> has been upgraded from version 1.820 to 1.821.
-
-=item *
-
-L<DBM_Filter> has been upgraded from version 0.03 to 0.04.
-
-=item *
-
-L<Devel::DProf> has been upgraded from version 20080331.00 to 20110228.00.
-
-Merely loading L<Devel::DProf> now no longer triggers profiling to start.
-Both C<use Devel::DProf> and C<perl -d:DProf ...> behave as before and start
-the profiler.
-
-B<NOTE>: L<Devel::DProf> is deprecated and will be removed from a future
-version of Perl. We strongly recommend that you install and use
-L<Devel::NYTProf> instead, as it offers significantly improved
-profiling and reporting.
-
-=item *
-
-L<Devel::Peek> has been upgraded from version 1.04 to 1.07.
-
-=item *
-
-L<Devel::SelfStubber> has been upgraded from version 1.03 to 1.05.
-
-=item *
-
-L<diagnostics> has been upgraded from version 1.19 to 1.22.
-
-It now renders pod links slightly better, and has been taught to find
-descriptions for messages that share their descriptions with other
-messages.
-
-=item *
-
-L<Digest::MD5> has been upgraded from version 2.39 to 2.51.
-
-It is now safe to use this module in combination with threads.
-
-=item *
-
-L<Digest::SHA> has been upgraded from version 5.47 to 5.61.
-
-C<shasum> now more closely mimics L<sha1sum(1)>/L<md5sum(1)>.
-
-C<addfile> accepts all POSIX filenames.
-
-New SHA-512/224 and SHA-512/256 transforms (ref. NIST Draft FIPS 180-4
-[February 2011])
-
-=item *
-
-L<DirHandle> has been upgraded from version 1.03 to 1.04.
-
-=item *
-
-L<Dumpvalue> has been upgraded from version 1.13 to 1.16.
-
-=item *
-
-L<DynaLoader> has been upgraded from version 1.10 to 1.13.
-
-It fixes a buffer overflow when passed a very long file name.
-
-It no longer inherits from L<AutoLoader>; hence it no longer
-produces weird error messages for unsuccessful method calls on classes that
-inherit from L<DynaLoader> [perl #84358].
-
-=item *
-
-L<Encode> has been upgraded from version 2.39 to 2.42.
-
-Now, all 66 Unicode non-characters are treated the same way U+FFFF has
-always been treated: in cases when it was disallowed, all 66 are
-disallowed, and in cases where it warned, all 66 warn.
-
-=item *
-
-L<Env> has been upgraded from version 1.01 to 1.02.
-
-=item *
-
-L<Errno> has been upgraded from version 1.11 to 1.13.
-
-The implementation of L<Errno> has been refactored to use about 55% less memory.
-
-On some platforms with unusual header files, like Win32 L<gcc(1)> using C<mingw64>
-headers, some constants that weren't actually error numbers have been exposed
-by L<Errno>. This has been fixed [perl #77416].
-
-=item *
-
-L<Exporter> has been upgraded from version 5.64_01 to 5.64_03.
-
-Exporter no longer overrides C<$SIG{__WARN__}> [perl #74472]
-
-=item *
-
-L<ExtUtils::CBuilder> has been upgraded from version 0.27 to 0.280203.
-
-=item *
-
-L<ExtUtils::Command> has been upgraded from version 1.16 to 1.17.
-
-=item *
-
-L<ExtUtils::Constant> has been upgraded from 0.22 to 0.23.
-
-The L<AUTOLOAD> helper code generated by C<ExtUtils::Constant::ProxySubs>
-can now croak() for missing constants, or generate a complete C<AUTOLOAD>
-subroutine in XS, allowing simplification of many modules that use it
-(L<Fcntl>, L<File::Glob>, L<GDBM_File>, L<I18N::Langinfo>, L<POSIX>,
-L<Socket>).
-
-L<ExtUtils::Constant::ProxySubs> can now optionally push the names of all
-constants onto the package's C<@EXPORT_OK>.
-
-=item *
-
-L<ExtUtils::Install> has been upgraded from version 1.55 to 1.56.
-
-=item *
-
-L<ExtUtils::MakeMaker> has been upgraded from version 6.56 to 6.57_05.
-
-=item *
-
-L<ExtUtils::Manifest> has been upgraded from version 1.57 to 1.58.
-
-=item *
-
-L<ExtUtils::ParseXS> has been upgraded from version 2.21 to 2.2210.
-
-=item *
-
-L<Fcntl> has been upgraded from version 1.06 to 1.11.
-
-=item *
-
-L<File::Basename> has been upgraded from version 2.78 to 2.82.
-
-=item *
-
-L<File::CheckTree> has been upgraded from version 4.4 to 4.41.
-
-=item *
-
-L<File::Copy> has been upgraded from version 2.17 to 2.21.
-
-=item *
-
-L<File::DosGlob> has been upgraded from version 1.01 to 1.04.
-
-It allows patterns containing literal parentheses: they no longer need to
-be escaped. On Windows, it no longer
-adds an extra F<./> to file names
-returned when the pattern is a relative glob with a drive specification,
-like F<C:*.pl> [perl #71712].
-
-=item *
-
-L<File::Fetch> has been upgraded from version 0.24 to 0.32.
-
-L<HTTP::Lite> is now supported for the "http" scheme.
-
-The L<fetch(1)> utility is supported on FreeBSD, NetBSD, and
-Dragonfly BSD for the C<http> and C<ftp> schemes.
-
-=item *
-
-L<File::Find> has been upgraded from version 1.15 to 1.19.
-
-It improves handling of backslashes on Windows, so that paths like
-F<C:\dir\/file> are no longer generated [perl #71710].
-
-=item *
-
-L<File::Glob> has been upgraded from version 1.07 to 1.12.
-
-=item *
-
-L<File::Spec> has been upgraded from version 3.31 to 3.33.
-
-Several portability fixes were made in L<File::Spec::VMS>: a colon is now
-recognized as a delimiter in native filespecs; caret-escaped delimiters are
-recognized for better handling of extended filespecs; catpath() returns
-an empty directory rather than the current directory if the input directory
-name is empty; and abs2rel() properly handles Unix-style input (5.12.2).
-
-=item *
-
-L<File::stat> has been upgraded from 1.02 to 1.05.
-
-The C<-x> and C<-X> file test operators now work correctly when run
-by the superuser.
-
-=item *
-
-L<Filter::Simple> has been upgraded from version 0.84 to 0.86.
-
-=item *
-
-L<GDBM_File> has been upgraded from 1.10 to 1.14.
-
-This fixes a memory leak when DBM filters are used.
-
-=item *
-
-L<Hash::Util> has been upgraded from 0.07 to 0.11.
-
-L<Hash::Util> no longer emits spurious "uninitialized" warnings when
-recursively locking hashes that have undefined values [perl #74280].
-
-=item *
-
-L<Hash::Util::FieldHash> has been upgraded from version 1.04 to 1.09.
-
-=item *
-
-L<I18N::Collate> has been upgraded from version 1.01 to 1.02.
-
-=item *
-
-L<I18N::Langinfo> has been upgraded from version 0.03 to 0.08.
-
-langinfo() now defaults to using C<$_> if there is no argument given, just
-as the documentation has always claimed.
-
-=item *
-
-L<I18N::LangTags> has been upgraded from version 0.35 to 0.35_01.
-
-=item *
-
-L<if> has been upgraded from version 0.05 to 0.0601.
-
-=item *
-
-L<IO> has been upgraded from version 1.25_02 to 1.25_04.
-
-This version of L<IO> includes a new L<IO::Select>, which now allows L<IO::Handle>
-objects (and objects in derived classes) to be removed from an L<IO::Select> set
-even if the underlying file descriptor is closed or invalid.
-
-=item *
-
-L<IPC::Cmd> has been upgraded from version 0.54 to 0.70.
-
-Resolves an issue with splitting Win32 command lines. An argument
-consisting of the single character "0" used to be omitted (CPAN RT #62961).
-
-=item *
-
-L<IPC::Open3> has been upgraded from 1.05 to 1.09.
-
-open3() now produces an error if the C<exec> call fails, allowing this
-condition to be distinguished from a child process that exited with a
-non-zero status [perl #72016].
-
-The internal xclose() routine now knows how to handle file descriptors as
-documented, so duplicating C<STDIN> in a child process using its file
-descriptor now works [perl #76474].
-
-=item *
-
-L<IPC::SysV> has been upgraded from version 2.01 to 2.03.
-
-=item *
-
-L<lib> has been upgraded from version 0.62 to 0.63.
-
-=item *
-
-L<Locale::Maketext> has been upgraded from version 1.14 to 1.19.
-
-L<Locale::Maketext> now supports external caches.
-
-This upgrade also fixes an infinite loop in
-C<Locale::Maketext::Guts::_compile()> when
-working with tainted values (CPAN RT #40727).
-
-C<< ->maketext >> calls now back up and restore C<$@> so error
-messages are not suppressed (CPAN RT #34182).
-
-=item *
-
-L<Log::Message> has been upgraded from version 0.02 to 0.04.
-
-=item *
-
-L<Log::Message::Simple> has been upgraded from version 0.06 to 0.08.
-
-=item *
-
-L<Math::BigInt> has been upgraded from version 1.89_01 to 1.994.
-
-This fixes, among other things, incorrect results when computing binomial
-coefficients [perl #77640].
-
-It also prevents C<sqrt($int)> from crashing under C<use bigrat>.
-[perl #73534].
-
-=item *
-
-L<Math::BigInt::FastCalc> has been upgraded from version 0.19 to 0.28.
-
-=item *
-
-L<Math::BigRat> has been upgraded from version 0.24 to 0.26_02.
-
-=item *
-
-L<Memoize> has been upgraded from version 1.01_03 to 1.02.
-
-=item *
-
-L<MIME::Base64> has been upgraded from 3.08 to 3.13.
-
-Includes new functions to calculate the length of encoded and decoded
-base64 strings.
-
-Now provides encode_base64url() and decode_base64url() functions to process
-the base64 scheme for "URL applications".
-
-=item *
-
-L<Module::Build> has been upgraded from version 0.3603 to 0.3800.
-
-A notable change is the deprecation of several modules.
-L<Module::Build::Version> has been deprecated and L<Module::Build> now
-relies on the L<version> pragma directly. L<Module::Build::ModuleInfo> has
-been deprecated in favor of a standalone copy called L<Module::Metadata>.
-L<Module::Build::YAML> has been deprecated in favor of L<CPAN::Meta::YAML>.
-
-L<Module::Build> now also generates F<META.json> and F<MYMETA.json> files
-in accordance with version 2 of the CPAN distribution metadata specification,
-L<CPAN::Meta::Spec>. The older format F<META.yml> and F<MYMETA.yml> files are
-still generated.
-
-=item *
-
-L<Module::CoreList> has been upgraded from version 2.29 to 2.47.
-
-Besides listing the updated core modules of this release, it also stops listing
-the C<Filespec> module. That module never existed in core. The scripts
-generating L<Module::CoreList> confused it with L<VMS::Filespec>, which actually
-is a core module as of Perl 5.8.7.
-
-=item *
-
-L<Module::Load> has been upgraded from version 0.16 to 0.18.
-
-=item *
-
-L<Module::Load::Conditional> has been upgraded from version 0.34 to 0.44.
-
-=item *
-
-The L<mro> pragma has been upgraded from version 1.02 to 1.07.
-
-=item *
-
-L<NDBM_File> has been upgraded from version 1.08 to 1.12.
-
-This fixes a memory leak when DBM filters are used.
-
-=item *
-
-L<Net::Ping> has been upgraded from version 2.36 to 2.38.
-
-=item *
-
-L<NEXT> has been upgraded from version 0.64 to 0.65.
-
-=item *
-
-L<Object::Accessor> has been upgraded from version 0.36 to 0.38.
-
-=item *
-
-L<ODBM_File> has been upgraded from version 1.07 to 1.10.
-
-This fixes a memory leak when DBM filters are used.
-
-=item *
-
-L<Opcode> has been upgraded from version 1.15 to 1.18.
-
-=item *
-
-The L<overload> pragma has been upgraded from 1.10 to 1.13.
-
-C<overload::Method> can now handle subroutines that are themselves blessed
-into overloaded classes [perl #71998].
-
-The documentation has greatly improved. See L</Documentation> below.
-
-=item *
-
-L<Params::Check> has been upgraded from version 0.26 to 0.28.
-
-=item *
-
-The L<parent> pragma has been upgraded from version 0.223 to 0.225.
-
-=item *
-
-L<Parse::CPAN::Meta> has been upgraded from version 1.40 to 1.4401.
-
-The latest Parse::CPAN::Meta can now read YAML and JSON files using
-L<CPAN::Meta::YAML> and L<JSON::PP>, which are now part of the Perl core.
-
-=item *
-
-L<PerlIO::encoding> has been upgraded from version 0.12 to 0.14.
-
-=item *
-
-L<PerlIO::scalar> has been upgraded from 0.07 to 0.11.
-
-A read() after a seek() beyond the end of the string no longer thinks it
-has data to read [perl #78716].
-
-=item *
-
-L<PerlIO::via> has been upgraded from version 0.09 to 0.11.
-
-=item *
-
-L<Pod::Html> has been upgraded from version 1.09 to 1.11.
-
-=item *
-
-L<Pod::LaTeX> has been upgraded from version 0.58 to 0.59.
-
-=item *
-
-L<Pod::Perldoc> has been upgraded from version 3.15_02 to 3.15_03.
-
-=item *
-
-L<Pod::Simple> has been upgraded from version 3.13 to 3.16.
-
-=item *
-
-L<POSIX> has been upgraded from 1.19 to 1.24.
-
-It now includes constants for POSIX signal constants.
-
-=item *
-
-The L<re> pragma has been upgraded from version 0.11 to 0.18.
-
-The C<use re '/flags'> subpragma is new.
-
-The regmust() function used to crash when called on a regular expression
-belonging to a pluggable engine. Now it croaks instead.
-
-regmust() no longer leaks memory.
-
-=item *
-
-L<Safe> has been upgraded from version 2.25 to 2.29.
-
-Coderefs returned by reval() and rdo() are now wrapped via
-wrap_code_refs() (5.12.1).
-
-This fixes a possible infinite loop when looking for coderefs.
-
-It adds several C<version::vxs::*> routines to the default share.
-
-=item *
-
-L<SDBM_File> has been upgraded from version 1.06 to 1.09.
-
-=item *
-
-L<SelfLoader> has been upgraded from 1.17 to 1.18.
-
-It now works in taint mode [perl #72062].
-
-=item *
-
-The L<sigtrap> pragma has been upgraded from version 1.04 to 1.05.
-
-It no longer tries to modify read-only arguments when generating a
-backtrace [perl #72340].
-
-=item *
-
-L<Socket> has been upgraded from version 1.87 to 1.94.
-
-See L</Improved IPv6 support> above.
-
-=item *
-
-L<Storable> has been upgraded from version 2.22 to 2.27.
-
-Includes performance improvement for overloaded classes.
-
-This adds support for serialising code references that contain UTF-8 strings
-correctly. The L<Storable> minor version
-number changed as a result, meaning that
-L<Storable> users who set C<$Storable::accept_future_minor> to a C<FALSE> value
-will see errors (see L<Storable/FORWARD COMPATIBILITY> for more details).
-
-Freezing no longer gets confused if the Perl stack gets reallocated
-during freezing [perl #80074].
-
-=item *
-
-L<Sys::Hostname> has been upgraded from version 1.11 to 1.16.
-
-=item *
-
-L<Term::ANSIColor> has been upgraded from version 2.02 to 3.00.
-
-=item *
-
-L<Term::UI> has been upgraded from version 0.20 to 0.26.
-
-=item *
-
-L<Test::Harness> has been upgraded from version 3.17 to 3.23.
-
-=item *
-
-L<Test::Simple> has been upgraded from version 0.94 to 0.98.
-
-Among many other things, subtests without a C<plan> or C<no_plan> now have an
-implicit done_testing() added to them.
-
-=item *
-
-L<Thread::Semaphore> has been upgraded from version 2.09 to 2.12.
-
-It provides two new methods that give more control over the decrementing of
-semaphores: C<down_nb> and C<down_force>.
-
-=item *
-
-L<Thread::Queue> has been upgraded from version 2.11 to 2.12.
-
-=item *
-
-The L<threads> pragma has been upgraded from version 1.75 to 1.83.
-
-=item *
-
-The L<threads::shared> pragma has been upgraded from version 1.32 to 1.37.
-
-=item *
-
-L<Tie::Hash> has been upgraded from version 1.03 to 1.04.
-
-Calling C<< Tie::Hash->TIEHASH() >> used to loop forever. Now it C<croak>s.
-
-=item *
-
-L<Tie::Hash::NamedCapture> has been upgraded from version 0.06 to 0.08.
-
-=item *
-
-L<Tie::RefHash> has been upgraded from version 1.38 to 1.39.
-
-=item *
-
-L<Time::HiRes> has been upgraded from version 1.9719 to 1.9721_01.
-
-=item *
-
-L<Time::Local> has been upgraded from version 1.1901_01 to 1.2000.
-
-=item *
-
-L<Time::Piece> has been upgraded from version 1.15_01 to 1.20_01.
-
-=item *
-
-L<Unicode::Collate> has been upgraded from version 0.52_01 to 0.73.
-
-L<Unicode::Collate> has been updated to use Unicode 6.0.0.
-
-L<Unicode::Collate::Locale> now supports a plethora of new locales: I<ar, be,
-bg, de__phonebook, hu, hy, kk, mk, nso, om, tn, vi, hr, ig, ja, ko, ru, sq,
-se, sr, to, uk, zh, zh__big5han, zh__gb2312han, zh__pinyin>, and I<zh__stroke>.
-
-The following modules have been added:
-
-L<Unicode::Collate::CJK::Big5> for C<zh__big5han> which makes
-tailoring of CJK Unified Ideographs in the order of CLDR's big5han ordering.
-
-L<Unicode::Collate::CJK::GB2312> for C<zh__gb2312han> which makes
-tailoring of CJK Unified Ideographs in the order of CLDR's gb2312han ordering.
-
-L<Unicode::Collate::CJK::JISX0208> which makes tailoring of 6355 kanji
-(CJK Unified Ideographs) in the JIS X 0208 order.
-
-L<Unicode::Collate::CJK::Korean> which makes tailoring of CJK Unified Ideographs
-in the order of CLDR's Korean ordering.
-
-L<Unicode::Collate::CJK::Pinyin> for C<zh__pinyin> which makes
-tailoring of CJK Unified Ideographs in the order of CLDR's pinyin ordering.
-
-L<Unicode::Collate::CJK::Stroke> for C<zh__stroke> which makes
-tailoring of CJK Unified Ideographs in the order of CLDR's stroke ordering.
-
-This also sees the switch from using the pure-Perl version of this
-module to the XS version.
-
-=item *
-
-L<Unicode::Normalize> has been upgraded from version 1.03 to 1.10.
-
-=item *
-
-L<Unicode::UCD> has been upgraded from version 0.27 to 0.32.
-
-A new function, Unicode::UCD::num(), has been added. This function
-returns the numeric value of the string passed it or C<undef> if the string
-in its entirety has no "safe" numeric value. (For more detail, and for the
-definition of "safe", see L<Unicode::UCD/num()>.)
-
-This upgrade also includes several bug fixes:
-
-=over 4
-
-=item charinfo()
-
-=over 4
-
-=item *
-
-It is now updated to Unicode Version 6.0.0 with I<Corrigendum #8>,
-excepting that, just as with Perl 5.14, the code point at U+1F514 has no name.
-
-=item *
-
-Hangul syllable code points have the correct names, and their
-decompositions are always output without requiring L<Lingua::KO::Hangul::Util>
-to be installed.
-
-=item *
-
-CJK (Chinese-Japanese-Korean) code points U+2A700 to U+2B734
-and U+2B740 to U+2B81D are now properly handled.
-
-=item *
-
-Numeric values are now output for those CJK code points that have them.
-
-=item *
-
-Names output for code points with multiple aliases are now the
-corrected ones.
-
-=back
-
-=item charscript()
-
-This now correctly returns "Unknown" instead of C<undef> for the script
-of a code point that hasn't been assigned another one.
-
-=item charblock()
-
-This now correctly returns "No_Block" instead of C<undef> for the block
-of a code point that hasn't been assigned to another one.
-
-=back
-
-=item *
-
-The L<version> pragma has been upgraded from 0.82 to 0.88.
-
-Because of a bug, now fixed, the is_strict() and is_lax() functions did not
-work when exported (5.12.1).
-
-=item *
-
-The L<warnings> pragma has been upgraded from version 1.09 to 1.12.
-
-Calling C<use warnings> without arguments is now significantly more efficient.
-
-=item *
-
-The L<warnings::register> pragma has been upgraded from version 1.01 to 1.02.
-
-It is now possible to register warning categories other than the names of
-packages using L<warnings::register>. See L<perllexwarn(1)> for more information.
-
-=item *
-
-L<XSLoader> has been upgraded from version 0.10 to 0.13.
-
-=item *
-
-L<VMS::DCLsym> has been upgraded from version 1.03 to 1.05.
-
-Two bugs have been fixed [perl #84086]:
-
-The symbol table name was lost when tying a hash, due to a thinko in
-C<TIEHASH>. The result was that all tied hashes interacted with the
-local symbol table.
-
-Unless a symbol table name had been explicitly specified in the call
-to the constructor, querying the special key C<:LOCAL> failed to
-identify objects connected to the local symbol table.
-
-=item *
-
-The L<Win32> module has been upgraded from version 0.39 to 0.44.
-
-This release has several new functions: Win32::GetSystemMetrics(),
-Win32::GetProductInfo(), Win32::GetOSDisplayName().
-
-The names returned by Win32::GetOSName() and Win32::GetOSDisplayName()
-have been corrected.
-
-=item *
-
-L<XS::Typemap> has been upgraded from version 0.03 to 0.05.
-
-=back
-
-=head2 Removed Modules and Pragmata
-
-As promised in Perl 5.12.0's release notes, the following modules have
-been removed from the core distribution, and if needed should be installed
-from CPAN instead.
-
-=over
-
-=item *
-
-L<Class::ISA> has been removed from the Perl core. Prior version was 0.36.
-
-=item *
-
-L<Pod::Plainer> has been removed from the Perl core. Prior version was 1.02.
-
-=item *
-
-L<Switch> has been removed from the Perl core. Prior version was 2.16.
-
-=back
-
-The removal of L<Shell> has been deferred until after 5.14, as the
-implementation of L<Shell> shipped with 5.12.0 did not correctly issue the
-warning that it was to be removed from core.
-
-=head1 Documentation
-
-=head2 New Documentation
-
-=head3 L<perlgpl>
-
-L<perlgpl> has been updated to contain GPL version 1, as is included in the
-F<README> distributed with Perl (5.12.1).
-
-=head3 Perl 5.12.x delta files
-
-The perldelta files for Perl 5.12.1 to 5.12.3 have been added from the
-maintenance branch: L<perl5121delta>, L<perl5122delta>, L<perl5123delta>.
-
-=head3 L<perlpodstyle>
-
-New style guide for POD documentation,
-split mostly from the NOTES section of the L<pod2man(1)> manpage.
-
-=head3 L<perlsource>, L<perlinterp>, L<perlhacktut>, and L<perlhacktips>
-
-See L</perlhack and perlrepository revamp>, below.
-
-=head2 Changes to Existing Documentation
-
-=head3 L<perlmodlib> is now complete
-
-The L<perlmodlib> manpage that came with Perl 5.12.0 was missing several
-modules due to a bug in the script that generates the list. This has been
-fixed [perl #74332] (5.12.1).
-
-=head3 Replace incorrect tr/// table in L<perlebcdic>
-
-L<perlebcdic> contains a helpful table to use in C<tr///> to convert
-between EBCDIC and Latin1/ASCII. The table was the inverse of the one
-it describes, though the code that used the table worked correctly for
-the specific example given.
-
-The table has been corrected and the sample code changed to correspond.
-
-The table has also been changed to hex from octal, and the recipes in the
-pod have been altered to print out leading zeros to make all values
-the same length.
-
-=head3 Tricks for user-defined casing
-
-L<perlunicode> now contains an explanation of how to override, mangle
-and otherwise tweak the way Perl handles upper-, lower- and other-case
-conversions on Unicode data, and how to provide scoped changes to alter
-one's own code's behaviour without stomping on anybody else's.
-
-=head3 INSTALL explicitly states that Perl requires a C89 compiler
-
-This was already true, but it's now Officially Stated For The Record
-(5.12.2).
-
-=head3 Explanation of C<\xI<HH>> and C<\oI<OOO>> escapes
-
-L<perlop> has been updated with more detailed explanation of these two
-character escapes.
-
-=head3 B<-0I<NNN>> switch
-
-In L<perlrun>, the behaviour of the B<-0NNN> switch for B<-0400> or higher
-has been clarified (5.12.2).
-
-=head3 Maintenance policy
-
-L<perlpolicy> now contains the policy on what patches are acceptable for
-maintenance branches (5.12.1).
-
-=head3 Deprecation policy
-
-L<perlpolicy> now contains the policy on compatibility and deprecation
-along with definitions of terms like "deprecation" (5.12.2).
-
-=head3 New descriptions in L<perldiag>
-
-The following existing diagnostics are now documented:
-
-=over 4
-
-=item *
-
-L<Ambiguous use of %c resolved as operator %c|perldiag/"Ambiguous use of %c resolved as operator %c">
-
-=item *
-
-L<Ambiguous use of %c{%s} resolved to %c%s|perldiag/"Ambiguous use of %c{%s} resolved to %c%s">
-
-=item *
-
-L<Ambiguous use of %c{%s[...]} resolved to %c%s[...]|perldiag/"Ambiguous use of %c{%s[...]} resolved to %c%s[...]">
-
-=item *
-
-L<Ambiguous use of %c{%s{...}} resolved to %c%s{...}|perldiag/"Ambiguous use of %c{%s{...}} resolved to %c%s{...}">
-
-=item *
-
-L<Ambiguous use of -%s resolved as -&%s()|perldiag/"Ambiguous use of -%s resolved as -&%s()">
-
-=item *
-
-L<Invalid strict version format (%s)|perldiag/"Invalid strict version format (%s)">
-
-=item *
-
-L<Invalid version format (%s)|perldiag/"Invalid version format (%s)">
-
-=item *
-
-L<Invalid version object|perldiag/"Invalid version object">
-
-=back
-
-=head3 L<perlbook>
-
-L<perlbook> has been expanded to cover many more popular books.
-
-=head3 C<SvTRUE> macro
-
-The documentation for the C<SvTRUE> macro in
-L<perlapi> was simply wrong in stating that
-get-magic is not processed. It has been corrected.
-
-=head3 op manipulation functions
-
-Several API functions that process optrees have been newly documented.
-
-=head3 L<perlvar> revamp
-
-L<perlvar> reorders the variables and groups them by topic. Each variable
-introduced after Perl 5.000 notes the first version in which it is
-available. L<perlvar> also has a new section for deprecated variables to
-note when they were removed.
-
-=head3 Array and hash slices in scalar context
-
-These are now documented in L<perldata>.
-
-=head3 C<use locale> and formats
-
-L<perlform> and L<perllocale> have been corrected to state that
-C<use locale> affects formats.
-
-=head3 L<overload>
-
-L<overload>'s documentation has practically undergone a rewrite. It
-is now much more straightforward and clear.
-
-=head3 perlhack and perlrepository revamp
-
-The L<perlhack> document is now much shorter, and focuses on the Perl 5
-development process and submitting patches to Perl. The technical content
-has been moved to several new documents, L<perlsource>, L<perlinterp>,
-L<perlhacktut>, and L<perlhacktips>. This technical content has
-been only lightly edited.
-
-The perlrepository document has been renamed to L<perlgit>. This new
-document is just a how-to on using git with the Perl source code.
-Any other content that used to be in perlrepository has been moved
-to L<perlhack>.
-
-=head3 Time::Piece examples
-
-Examples in L<perlfaq4> have been updated to show the use of
-L<Time::Piece>.
-
-=head1 Diagnostics
-
-The following additions or changes have been made to diagnostic output,
-including warnings and fatal error messages. For the complete list of
-diagnostic messages, see L<perldiag>.
-
-=head2 New Diagnostics
-
-=head3 New Errors
-
-=over
-
-=item Closure prototype called
-
-This error occurs when a subroutine reference passed to an attribute
-handler is called, if the subroutine is a closure [perl #68560].
-
-=item Insecure user-defined property %s
-
-Perl detected tainted data when trying to compile a regular
-expression that contains a call to a user-defined character property
-function, meaning C<\p{IsFoo}> or C<\p{InFoo}>.
-See L<perlunicode/User-Defined Character Properties> and L<perlsec>.
-
-=item panic: gp_free failed to free glob pointer - something is repeatedly re-creating entries
-
-This new error is triggered if a destructor called on an object in a
-typeglob that is being freed creates a new typeglob entry containing an
-object with a destructor that creates a new entry containing an object etc.
-
-=item Parsing code internal error (%s)
-
-This new fatal error is produced when parsing
-code supplied by an extension violates the
-parser's API in a detectable way.
-
-=item refcnt: fd %d%s
-
-This new error only occurs if a internal consistency check fails when a
-pipe is about to be closed.
-
-=item Regexp modifier "/%c" may not appear twice
-
-The regular expression pattern has one of the
-mutually exclusive modifiers repeated.
-
-=item Regexp modifiers "/%c" and "/%c" are mutually exclusive
-
-The regular expression pattern has more than one of the mutually
-exclusive modifiers.
-
-=item Using !~ with %s doesn't make sense
-
-This error occurs when C<!~> is used with C<s///r> or C<y///r>.
-
-=back
-
-=head3 New Warnings
-
-=over
-
-=item "\b{" is deprecated; use "\b\{" instead
-
-=item "\B{" is deprecated; use "\B\{" instead
-
-Use of an unescaped "{" immediately following a C<\b> or C<\B> is now
-deprecated in order to reserve its use for Perl itself in a future release.
-
-=item Operation "%s" returns its argument for ...
-
-Performing an operation requiring Unicode semantics (such as case-folding)
-on a Unicode surrogate or a non-Unicode character now triggers this
-warning.
-
-=item Use of qw(...) as parentheses is deprecated
-
-See L</"Use of qw(...) as parentheses">, above, for details.
-
-=back
-
-=head2 Changes to Existing Diagnostics
-
-=over 4
-
-=item *
-
-The "Variable $foo is not imported" warning that precedes a
-C<strict 'vars'> error has now been assigned the "misc" category, so that
-C<no warnings> will suppress it [perl #73712].
-
-=item *
-
-warn() and die() now produce "Wide character" warnings when fed a
-character outside the byte range if C<STDERR> is a byte-sized handle.
-
-=item *
-
-The "Layer does not match this perl" error message has been replaced with
-these more helpful messages [perl #73754]:
-
-=over 4
-
-=item *
-
-PerlIO layer function table size (%d) does not match size expected by this
-perl (%d)
-
-=item *
-
-PerlIO layer instance size (%d) does not match size expected by this perl
-(%d)
-
-=back
-
-=item *
-
-The "Found = in conditional" warning that is emitted when a constant is
-assigned to a variable in a condition is now withheld if the constant is
-actually a subroutine or one generated by C<use constant>, since the value
-of the constant may not be known at the time the program is written
-[perl #77762].
-
-=item *
-
-Previously, if none of the gethostbyaddr(), gethostbyname() and
-gethostent() functions were implemented on a given platform, they would
-all die with the message "Unsupported socket function 'gethostent' called",
-with analogous messages for getnet*() and getserv*(). This has been
-corrected.
-
-=item *
-
-The warning message about unrecognized regular expression escapes passed
-through has been changed to include any literal "{" following the
-two-character escape. For example, "\q{" is now emitted instead of "\q".
-
-=back
-
-=head1 Utility Changes
-
-=head3 L<perlbug(1)>
-
-=over 4
-
-=item *
-
-L<perlbug> now looks in the EMAIL environment variable for a return address
-if the REPLY-TO and REPLYTO variables are empty.
-
-=item *
-
-L<perlbug> did not previously generate a "From:" header, potentially
-resulting in dropped mail; it now includes that header.
-
-=item *
-
-The user's address is now used as the Return-Path.
-
-Many systems these days don't have a valid Internet domain name, and
-perlbug@perl.org does not accept email with a return-path that does
-not resolve. So the user's address is now passed to sendmail so it's
-less likely to get stuck in a mail queue somewhere [perl #82996].
-
-=item *
-
-L<perlbug> now always gives the reporter a chance to change the email
-address it guesses for them (5.12.2).
-
-=item *
-
-L<perlbug> should no longer warn about uninitialized values when using the B<-d>
-and B<-v> options (5.12.2).
-
-=back
-
-=head3 L<perl5db.pl>
-
-=over
-
-=item *
-
-The remote terminal works after forking and spawns new sessions, one
-per forked process.
-
-=back
-
-=head3 L<ptargrep>
-
-=over 4
-
-=item *
-
-L<ptargrep> is a new utility to apply pattern matching to the contents of
-files in a tar archive. It comes with C<Archive::Tar>.
-
-=back
-
-=head1 Configuration and Compilation
-
-See also L</"Naming fixes in Policy_sh.SH may invalidate Policy.sh">,
-above.
-
-=over 4
-
-=item *
-
-CCINCDIR and CCLIBDIR for the mingw64 cross-compiler are now correctly
-under F<$(CCHOME)\mingw\include> and F<\lib> rather than immediately below
-F<$(CCHOME)>.
-
-This means the "incpath", "libpth", "ldflags", "lddlflags" and
-"ldflags_nolargefiles" values in F<Config.pm> and F<Config_heavy.pl> are now
-set correctly.
-
-=item *
-
-C<make test.valgrind> has been adjusted to account for F<cpan/dist/ext>
-separation.
-
-=item *
-
-On compilers that support it, B<-Wwrite-strings> is now added to cflags by
-default.
-
-=item *
-
-The L<Encode> module can now (once again) be included in a static Perl
-build. The special-case handling for this situation got broken in Perl
-5.11.0, and has now been repaired.
-
-=item *
-
-The previous default size of a PerlIO buffer (4096 bytes) has been increased
-to the larger of 8192 bytes and your local BUFSIZ. Benchmarks show that doubling
-this decade-old default increases read and write performance by around
-25% to 50% when using the default layers of perlio on top of unix. To choose
-a non-default size, such as to get back the old value or to obtain an even
-larger value, configure with:
-
- ./Configure -Accflags=-DPERLIOBUF_DEFAULT_BUFSIZ=N
-
-where N is the desired size in bytes; it should probably be a multiple of
-your page size.
-
-=item *
-
-An "incompatible operand types" error in ternary expressions when building
-with C<clang> has been fixed (5.12.2).
-
-=item *
-
-Perl now skips setuid L<File::Copy> tests on partitions it detects mounted
-as C<nosuid> (5.12.2).
-
-=back
-
-=head1 Platform Support
-
-=head2 New Platforms
-
-=over 4
-
-=item AIX
-
-Perl now builds on AIX 4.2 (5.12.1).
-
-=back
-
-=head2 Discontinued Platforms
-
-=over 4
-
-=item Apollo DomainOS
-
-The last vestiges of support for this platform have been excised from
-the Perl distribution. It was officially discontinued in version 5.12.0.
-It had not worked for years before that.
-
-=item MacOS Classic
-
-The last vestiges of support for this platform have been excised from the
-Perl distribution. It was officially discontinued in an earlier version.
-
-=back
-
-=head2 Platform-Specific Notes
-
-=head3 AIX
-
-=over
-
-=item *
-
-F<README.aix> has been updated with information about the XL C/C++ V11 compiler
-suite (5.12.2).
-
-=back
-
-=head3 ARM
-
-=over
-
-=item *
-
-The C<d_u32align> configuration probe on ARM has been fixed (5.12.2).
-
-=back
-
-=head3 Cygwin
-
-=over 4
-
-=item *
-
-L<MakeMaker> has been updated to build manpages on cygwin.
-
-=item *
-
-Improved rebase behaviour
-
-If a DLL is updated on cygwin the old imagebase address is reused.
-This solves most rebase errors, especially when updating on core DLL's.
-See L<http://www.tishler.net/jason/software/rebase/rebase-2.4.2.README>
-for more information.
-
-=item *
-
-Support for the standard cygwin dll prefix (needed for FFIs)
-
-=item *
-
-Updated build hints file
-
-=back
-
-=head3 FreeBSD 7
-
-=over
-
-=item *
-
-FreeBSD 7 no longer contains F</usr/bin/objformat>. At build time,
-Perl now skips the F<objformat> check for versions 7 and higher and
-assumes ELF (5.12.1).
-
-=back
-
-=head3 HP-UX
-
-=over
-
-=item *
-
-Perl now allows B<-Duse64bitint> without promoting to C<use64bitall> on HP-UX
-(5.12.1).
-
-=back
-
-=head3 IRIX
-
-=over
-
-=item *
-
-Conversion of strings to floating-point numbers is now more accurate on
-IRIX systems [perl #32380].
-
-=back
-
-=head3 Mac OS X
-
-=over
-
-=item *
-
-Early versions of Mac OS X (Darwin) had buggy implementations of the
-setregid(), setreuid(), setrgid(,) and setruid() functions, so Perl
-would pretend they did not exist.
-
-These functions are now recognised on Mac OS 10.5 (Leopard; Darwin 9) and
-higher, as they have been fixed [perl #72990].
-
-=back
-
-=head3 MirBSD
-
-=over
-
-=item *
-
-Previously if you built Perl with a shared F<libperl.so> on MirBSD (the
-default config), it would work up to the installation; however, once
-installed, it would be unable to find F<libperl>. Path handling is now
-treated as in the other BSD dialects.
-
-=back
-
-=head3 NetBSD
-
-=over
-
-=item *
-
-The NetBSD hints file has been changed to make the system malloc the
-default.
-
-=back
-
-=head3 OpenBSD
-
-=over
-
-=item *
-
-OpenBSD E<gt> 3.7 has a new malloc implementation which is I<mmap>-based,
-and as such can release memory back to the OS; however, Perl's use of
-this malloc causes a substantial slowdown, so we now default to using
-Perl's malloc instead [perl #75742].
-
-=back
-
-=head3 OpenVOS
-
-=over
-
-=item *
-
-Perl now builds again with OpenVOS (formerly known as Stratus VOS)
-[perl #78132] (5.12.3).
-
-=back
-
-=head3 Solaris
-
-=over
-
-=item *
-
-DTrace is now supported on Solaris. There used to be build failures, but
-these have been fixed [perl #73630] (5.12.3).
-
-=back
-
-=head3 VMS
-
-=over
-
-=item *
-
-Extension building on older (pre 7.3-2) VMS systems was broken because
-configure.com hit the DCL symbol length limit of 1K. We now work within
-this limit when assembling the list of extensions in the core build (5.12.1).
-
-=item *
-
-We fixed configuring and building Perl with B<-Uuseperlio> (5.12.1).
-
-=item *
-
-C<PerlIOUnix_open> now honours the default permissions on VMS.
-
-When C<perlio> became the default and C<unix> became the default bottom layer,
-the most common path for creating files from Perl became C<PerlIOUnix_open>,
-which has always explicitly used C<0666> as the permission mask. This prevents
-inheriting permissions from RMS defaults and ACLs, so to avoid that problem,
-we now pass C<0777> to open(). In the VMS CRTL, C<0777> has a special
-meaning over and above intersecting with the current umask; specifically, it
-allows Unix syscalls to preserve native default permissions (5.12.3).
-
-=item *
-
-The shortening of symbols longer than 31 characters in the core C sources
-and in extensions is now by default done by the C compiler rather than by
-xsubpp (which could only do so for generated symbols in XS code). You can
-reenable xsubpp's symbol shortening by configuring with -Uuseshortenedsymbols,
-but you'll have some work to do to get the core sources to compile.
-
-=item *
-
-Record-oriented files (record format variable or variable with fixed control)
-opened for write by the C<perlio> layer will now be line-buffered to prevent the
-introduction of spurious line breaks whenever the perlio buffer fills up.
-
-=item *
-
-F<git_version.h> is now installed on VMS. This was an oversight in v5.12.0 which
-caused some extensions to fail to build (5.12.2).
-
-=item *
-
-Several memory leaks in L<stat()|perlfunc/"stat FILEHANDLE"> have been fixed (5.12.2).
-
-=item *
-
-A memory leak in Perl_rename() due to a double allocation has been
-fixed (5.12.2).
-
-=item *
-
-A memory leak in vms_fid_to_name() (used by realpath() and
-realname()> has been fixed (5.12.2).
-
-=back
-
-=head3 Windows
-
-See also L</"fork() emulation will not wait for signalled children"> and
-L</"Perl source code is read in text mode on Windows">, above.
-
-=over 4
-
-=item *
-
-Fixed build process for SDK2003SP1 compilers.
-
-=item *
-
-Compilation with Visual Studio 2010 is now supported.
-
-=item *
-
-When using old 32-bit compilers, the define C<_USE_32BIT_TIME_T> is now
-set in C<$Config{ccflags}>. This improves portability when compiling
-XS extensions using new compilers, but for a Perl compiled with old 32-bit
-compilers.
-
-=item *
-
-C<$Config{gccversion}> is now set correctly when Perl is built using the
-mingw64 compiler from L<http://mingw64.org> [perl #73754].
-
-=item *
-
-When building Perl with the mingw64 x64 cross-compiler C<incpath>,
-C<libpth>, C<ldflags>, C<lddlflags> and C<ldflags_nolargefiles> values
-in F<Config.pm> and F<Config_heavy.pl> were not previously being set
-correctly because, with that compiler, the include and lib directories
-are not immediately below C<$(CCHOME)> (5.12.2).
-
-=item *
-
-The build process proceeds more smoothly with mingw and dmake when
-F<C:\MSYS\bin> is in the PATH, due to a C<Cwd> fix.
-
-=item *
-
-Support for building with Visual C++ 2010 is now underway, but is not yet
-complete. See F<README.win32> or L<perlwin32> for more details.
-
-=item *
-
-The option to use an externally-supplied crypt(), or to build with no
-crypt() at all, has been removed. Perl supplies its own crypt()
-implementation for Windows, and the political situation that required
-this part of the distribution to sometimes be omitted is long gone.
-
-=back
-
-=head1 Internal Changes
-
-=head2 New APIs
-
-=head3 CLONE_PARAMS structure added to ease correct thread creation
-
-Modules that create threads should now create C<CLONE_PARAMS> structures
-by calling the new function Perl_clone_params_new(), and free them with
-Perl_clone_params_del(). This will ensure compatibility with any future
-changes to the internals of the C<CLONE_PARAMS> structure layout, and that
-it is correctly allocated and initialised.
-
-=head3 New parsing functions
-
-Several functions have been added for parsing Perl statements and
-expressions. These functions are meant to be used by XS code invoked
-during Perl parsing, in a recursive-descent manner, to allow modules to
-augment the standard Perl syntax.
-
-=over
-
-=item *
-
-L<parse_stmtseq()|perlapi/parse_stmtseq>
-parses a sequence of statements, up to closing brace or EOF.
-
-=item *
-
-L<parse_fullstmt()|perlapi/parse_fullstmt>
-parses a complete Perl statement, including optional label.
-
-=item *
-
-L<parse_barestmt()|perlapi/parse_barestmt>
-parses a statement without a label.
-
-=item *
-
-L<parse_block()|perlapi/parse_block>
-parses a code block.
-
-=item *
-
-L<parse_label()|perlapi/parse_label>
-parses a statement label, separate from statements.
-
-=item *
-
-L<C<parse_fullexpr()>|perlapi/parse_fullexpr>,
-L<C<parse_listexpr()>|perlapi/parse_listexpr>,
-L<C<parse_termexpr()>|perlapi/parse_termexpr>, and
-L<C<parse_arithexpr()>|perlapi/parse_arithexpr>
-parse expressions at various precedence levels.
-
-=back
-
-=head3 Hints hash API
-
-A new C API for introspecting the hinthash C<%^H> at runtime has been
-added. See C<cop_hints_2hv>, C<cop_hints_fetchpvn>, C<cop_hints_fetchpvs>,
-C<cop_hints_fetchsv>, and C<hv_copy_hints_hv> in L<perlapi> for details.
-
-A new, experimental API has been added for accessing the internal
-structure that Perl uses for C<%^H>. See the functions beginning with
-C<cophh_> in L<perlapi>.
-
-=head3 C interface to caller()
-
-The C<caller_cx> function has been added as an XSUB-writer's equivalent of
-caller(). See L<perlapi> for details.
-
-=head3 Custom per-subroutine check hooks
-
-XS code in an extension module can now annotate a subroutine (whether
-implemented in XS or in Perl) so that nominated XS code will be called
-at compile time (specifically as part of op checking) to change the op
-tree of that subroutine. The compile-time check function (supplied by
-the extension module) can implement argument processing that can't be
-expressed as a prototype, generate customised compile-time warnings,
-perform constant folding for a pure function, inline a subroutine
-consisting of sufficiently simple ops, replace the whole call with a
-custom op, and so on. This was previously all possible by hooking the
-C<entersub> op checker, but the new mechanism makes it easy to tie the
-hook to a specific subroutine. See L<perlapi/cv_set_call_checker>.
-
-To help in writing custom check hooks, several subtasks within standard
-C<entersub> op checking have been separated out and exposed in the API.
-
-=head3 Improved support for custom OPs
-
-Custom ops can now be registered with the new C<custom_op_register> C
-function and the C<XOP> structure. This will make it easier to add new
-properties of custom ops in the future. Two new properties have been added
-already, C<xop_class> and C<xop_peep>.
-
-C<xop_class> is one of the OA_*OP constants. It allows L<B> and other
-introspection mechanisms to work with custom ops
-that aren't BASEOPs. C<xop_peep> is a pointer to
-a function that will be called for ops of this
-type from C<Perl_rpeep>.
-
-See L<perlguts/Custom Operators> and L<perlapi/Custom Operators> for more
-detail.
-
-The old C<PL_custom_op_names>/C<PL_custom_op_descs> interface is still
-supported but discouraged.
-
-=head3 Scope hooks
-
-It is now possible for XS code to hook into Perl's lexical scope
-mechanism at compile time, using the new C<Perl_blockhook_register>
-function. See L<perlguts/"Compile-time scope hooks">.
-
-=head3 The recursive part of the peephole optimizer is now hookable
-
-In addition to C<PL_peepp>, for hooking into the toplevel peephole optimizer, a
-C<PL_rpeepp> is now available to hook into the optimizer recursing into
-side-chains of the optree.
-
-=head3 New non-magical variants of existing functions
-
-The following functions/macros have been added to the API. The C<*_nomg>
-macros are equivalent to their non-C<_nomg> variants, except that they ignore
-get-magic. Those ending in C<_flags> allow one to specify whether
-get-magic is processed.
-
- sv_2bool_flags
- SvTRUE_nomg
- sv_2nv_flags
- SvNV_nomg
- sv_cmp_flags
- sv_cmp_locale_flags
- sv_eq_flags
- sv_collxfrm_flags
-
-In some of these cases, the non-C<_flags> functions have
-been replaced with wrappers around the new functions.
-
-=head3 pv/pvs/sv versions of existing functions
-
-Many functions ending with pvn now have equivalent C<pv/pvs/sv> versions.
-
-=head3 List op-building functions
-
-List op-building functions have been added to the
-API. See L<op_append_elem|perlapi/op_append_elem>,
-L<op_append_list|perlapi/op_append_list>, and
-L<op_prepend_elem|perlapi/op_prepend_elem> in L<perlapi>.
-
-=head3 C<LINKLIST>
-
-The L<LINKLIST|perlapi/LINKLIST> macro, part of op building that
-constructs the execution-order op chain, has been added to the API.
-
-=head3 Localisation functions
-
-The C<save_freeop>, C<save_op>, C<save_pushi32ptr> and C<save_pushptrptr>
-functions have been added to the API.
-
-=head3 Stash names
-
-A stash can now have a list of effective names in addition to its usual
-name. The first effective name can be accessed via the C<HvENAME> macro,
-which is now the recommended name to use in MRO linearisations (C<HvNAME>
-being a fallback if there is no C<HvENAME>).
-
-These names are added and deleted via C<hv_ename_add> and
-C<hv_ename_delete>. These two functions are I<not> part of the API.
-
-=head3 New functions for finding and removing magic
-
-The L<C<mg_findext()>|perlapi/mg_findext> and
-L<C<sv_unmagicext()>|perlapi/sv_unmagicext>
-functions have been added to the API.
-They allow extension authors to find and remove magic attached to
-scalars based on both the magic type and the magic virtual table, similar to how
-sv_magicext() attaches magic of a certain type and with a given virtual table
-to a scalar. This eliminates the need for extensions to walk the list of
-C<MAGIC> pointers of an C<SV> to find the magic that belongs to them.
-
-=head3 C<find_rundefsv>
-
-This function returns the SV representing C<$_>, whether it's lexical
-or dynamic.
-
-=head3 C<Perl_croak_no_modify>
-
-Perl_croak_no_modify() is short-hand for
-C<Perl_croak("%s", PL_no_modify)>.
-
-=head3 C<PERL_STATIC_INLINE> define
-
-The C<PERL_STATIC_INLINE> define has been added to provide the best-guess
-incantation to use for static inline functions, if the C compiler supports
-C99-style static inline. If it doesn't, it'll give a plain C<static>.
-
-C<HAS_STATIC_INLINE> can be used to check if the compiler actually supports
-inline functions.
-
-=head3 New C<pv_escape> option for hexadecimal escapes
-
-A new option, C<PERL_PV_ESCAPE_NONASCII>, has been added to C<pv_escape> to
-dump all characters above ASCII in hexadecimal. Before, one could get all
-characters as hexadecimal or the Latin1 non-ASCII as octal.
-
-=head3 C<lex_start>
-
-C<lex_start> has been added to the API, but is considered experimental.
-
-=head3 op_scope() and op_lvalue()
-
-The op_scope() and op_lvalue() functions have been added to the API,
-but are considered experimental.
-
-=head2 C API Changes
-
-=head3 C<PERL_POLLUTE> has been removed
-
-The option to define C<PERL_POLLUTE> to expose older 5.005 symbols for
-backwards compatibility has been removed. Its use was always discouraged,
-and MakeMaker contains a more specific escape hatch:
-
- perl Makefile.PL POLLUTE=1
-
-This can be used for modules that have not been upgraded to 5.6 naming
-conventions (and really should be completely obsolete by now).
-
-=head3 Check API compatibility when loading XS modules
-
-When Perl's API changes in incompatible ways (which usually happens between
-major releases), XS modules compiled for previous versions of Perl will no
-longer work. They need to be recompiled against the new Perl.
-
-The C<XS_APIVERSION_BOOTCHECK> macro has been added to ensure that modules
-are recompiled and to prevent users from accidentally loading modules
-compiled for old perls into newer perls. That macro, which is called when
-loading every newly compiled extension, compares the API version of the
-running perl with the version a module has been compiled for and raises an
-exception if they don't match.
-
-=head3 Perl_fetch_cop_label
-
-The first argument of the C API function C<Perl_fetch_cop_label> has changed
-from C<struct refcounted_he *> to C<COP *>, to insulate the user from
-implementation details.
-
-This API function was marked as "may change", and likely isn't in use outside
-the core. (Neither an unpacked CPAN nor Google's codesearch finds any other
-references to it.)
-
-=head3 GvCV() and GvGP() are no longer lvalues
-
-The new GvCV_set() and GvGP_set() macros are now provided to replace
-assignment to those two macros.
-
-This allows a future commit to eliminate some backref magic between GV
-and CVs, which will require complete control over assignment to the
-C<gp_cv> slot.
-
-=head3 CvGV() is no longer an lvalue
-
-Under some circumstances, the CvGV() field of a CV is now
-reference-counted. To ensure consistent behaviour, direct assignment to
-it, for example C<CvGV(cv) = gv> is now a compile-time error. A new macro,
-C<CvGV_set(cv,gv)> has been introduced to run this operation
-safely. Note that modification of this field is not part of the public
-API, regardless of this new macro (and despite its being listed in this section).
-
-=head3 CvSTASH() is no longer an lvalue
-
-The CvSTASH() macro can now only be used as an rvalue. CvSTASH_set()
-has been added to replace assignment to CvSTASH(). This is to ensure
-that backreferences are handled properly. These macros are not part of the
-API.
-
-=head3 Calling conventions for C<newFOROP> and C<newWHILEOP>
-
-The way the parser handles labels has been cleaned up and refactored. As a
-result, the newFOROP() constructor function no longer takes a parameter
-stating what label is to go in the state op.
-
-The newWHILEOP() and newFOROP() functions no longer accept a line
-number as a parameter.
-
-=head3 Flags passed to C<uvuni_to_utf8_flags> and C<utf8n_to_uvuni>
-
-Some of the flags parameters to uvuni_to_utf8_flags() and
-utf8n_to_uvuni() have changed. This is a result of Perl's now allowing
-internal storage and manipulation of code points that are problematic
-in some situations. Hence, the default actions for these functions has
-been complemented to allow these code points. The new flags are
-documented in L<perlapi>. Code that requires the problematic code
-points to be rejected needs to change to use the new flags. Some flag
-names are retained for backward source compatibility, though they do
-nothing, as they are now the default. However the flags
-C<UNICODE_ALLOW_FDD0>, C<UNICODE_ALLOW_FFFF>, C<UNICODE_ILLEGAL>, and
-C<UNICODE_IS_ILLEGAL> have been removed, as they stem from a
-fundamentally broken model of how the Unicode non-character code points
-should be handled, which is now described in
-L<perlunicode/Non-character code points>. See also the Unicode section
-under L</Selected Bug Fixes>.
-
-=head2 Deprecated C APIs
-
-=over
-
-=item C<Perl_ptr_table_clear>
-
-C<Perl_ptr_table_clear> is no longer part of Perl's public API. Calling it
-now generates a deprecation warning, and it will be removed in a future
-release.
-
-=item C<sv_compile_2op>
-
-The sv_compile_2op() API function is now deprecated. Searches suggest
-that nothing on CPAN is using it, so this should have zero impact.
-
-It attempted to provide an API to compile code down to an optree, but failed
-to bind correctly to lexicals in the enclosing scope. It's not possible to
-fix this problem within the constraints of its parameters and return value.
-
-=item C<find_rundefsvoffset>
-
-The C<find_rundefsvoffset> function has been deprecated. It appeared that
-its design was insufficient for reliably getting the lexical C<$_> at
-run-time.
-
-Use the new C<find_rundefsv> function or the C<UNDERBAR> macro
-instead. They directly return the right SV
-representing C<$_>, whether it's
-lexical or dynamic.
-
-=item C<CALL_FPTR> and C<CPERLscope>
-
-Those are left from an old implementation of C<MULTIPLICITY> using C++ objects,
-which was removed in Perl 5.8. Nowadays these macros do exactly nothing, so
-they shouldn't be used anymore.
-
-For compatibility, they are still defined for external C<XS> code. Only
-extensions defining C<PERL_CORE> must be updated now.
-
-=back
-
-=head2 Other Internal Changes
-
-=head3 Stack unwinding
-
-The protocol for unwinding the C stack at the last stage of a C<die>
-has changed how it identifies the target stack frame. This now uses
-a separate variable C<PL_restartjmpenv>, where previously it relied on
-the C<blk_eval.cur_top_env> pointer in the C<eval> context frame that
-has nominally just been discarded. This change means that code running
-during various stages of Perl-level unwinding no longer needs to take
-care to avoid destroying the ghost frame.
-
-=head3 Scope stack entries
-
-The format of entries on the scope stack has been changed, resulting in a
-reduction of memory usage of about 10%. In particular, the memory used by
-the scope stack to record each active lexical variable has been halved.
-
-=head3 Memory allocation for pointer tables
-
-Memory allocation for pointer tables has been changed. Previously
-C<Perl_ptr_table_store> allocated memory from the same arena system as
-C<SV> bodies and C<HE>s, with freed memory remaining bound to those arenas
-until interpreter exit. Now it allocates memory from arenas private to the
-specific pointer table, and that memory is returned to the system when
-C<Perl_ptr_table_free> is called. Additionally, allocation and release are
-both less CPU intensive.
-
-=head3 C<UNDERBAR>
-
-The C<UNDERBAR> macro now calls C<find_rundefsv>. C<dUNDERBAR> is now a
-noop but should still be used to ensure past and future compatibility.
-
-=head3 String comparison routines renamed
-
-The C<ibcmp_*> functions have been renamed and are now called C<foldEQ>,
-C<foldEQ_locale>, and C<foldEQ_utf8>. The old names are still available as
-macros.
-
-=head3 C<chop> and C<chomp> implementations merged
-
-The opcode bodies for C<chop> and C<chomp> and for C<schop> and C<schomp>
-have been merged. The implementation functions Perl_do_chop() and
-Perl_do_chomp(), never part of the public API, have been merged and
-moved to a static function in F<pp.c>. This shrinks the Perl binary
-slightly, and should not affect any code outside the core (unless it is
-relying on the order of side-effects when C<chomp> is passed a I<list> of
-values).
-
-=head1 Selected Bug Fixes
-
-=head2 I/O
-
-=over 4
-
-=item *
-
-Perl no longer produces this warning:
-
- $ perl -we 'open(my $f, ">", \my $x); binmode($f, "scalar")'
- Use of uninitialized value in binmode at -e line 1.
-
-=item *
-
-Opening a glob reference via C<< open($fh, ">", \*glob) >> no longer
-causes the glob to be corrupted when the filehandle is printed to. This would
-cause Perl to crash whenever the glob's contents were accessed
-[perl #77492].
-
-=item *
-
-PerlIO no longer crashes when called recursively, such as from a signal
-handler. Now it just leaks memory [perl #75556].
-
-=item *
-
-Most I/O functions were not warning for unopened handles unless the
-"closed" and "unopened" warnings categories were both enabled. Now only
-C<use warnings 'unopened'> is necessary to trigger these warnings, as
-had always been the intention.
-
-=item *
-
-There have been several fixes to PerlIO layers:
-
-When C<binmode(FH, ":crlf")> pushes the C<:crlf> layer on top of the stack,
-it no longer enables crlf layers lower in the stack so as to avoid
-unexpected results [perl #38456].
-
-Opening a file in C<:raw> mode now does what it advertises to do (first
-open the file, then C<binmode> it), instead of simply leaving off the top
-layer [perl #80764].
-
-The three layers C<:pop>, C<:utf8>, and C<:bytes> didn't allow stacking when
-opening a file. For example
-this:
-
- open(FH, ">:pop:perlio", "some.file") or die $!;
-
-would throw an "Invalid argument" error. This has been fixed in this
-release [perl #82484].
-
-=back
-
-=head2 Regular Expression Bug Fixes
-
-=over
-
-=item *
-
-The regular expression engine no longer loops when matching
-C<"\N{LATIN SMALL LIGATURE FF}" =~ /f+/i> and similar expressions
-[perl #72998] (5.12.1).
-
-=item *
-
-The trie runtime code should no longer allocate massive amounts of memory,
-fixing #74484.
-
-=item *
-
-Syntax errors in C<< (?{...}) >> blocks no longer cause panic messages
-[perl #2353].
-
-=item *
-
-A pattern like C<(?:(o){2})?> no longer causes a "panic" error
-[perl #39233].
-
-=item *
-
-A fatal error in regular expressions containing C<(.*?)> when processing
-UTF-8 data has been fixed [perl #75680] (5.12.2).
-
-=item *
-
-An erroneous regular expression engine optimisation that caused regex verbs like
-C<*COMMIT> sometimes to be ignored has been removed.
-
-=item *
-
-The regular expression bracketed character class C<[\8\9]> was effectively the
-same as C<[89\000]>, incorrectly matching a NULL character. It also gave
-incorrect warnings that the C<8> and C<9> were ignored. Now C<[\8\9]> is the
-same as C<[89]> and gives legitimate warnings that C<\8> and C<\9> are
-unrecognized escape sequences, passed-through.
-
-=item *
-
-A regular expression match in the right-hand side of a global substitution
-(C<s///g>) that is in the same scope will no longer cause match variables
-to have the wrong values on subsequent iterations. This can happen when an
-array or hash subscript is interpolated in the right-hand side, as in
-C<s|(.)|@a{ print($1), /./ }|g> [perl #19078].
-
-=item *
-
-Several cases in which characters in the Latin-1 non-ASCII range (0x80 to
-0xFF) used not to match themselves, or used to match both a character class
-and its complement, have been fixed. For instance, U+00E2 could match both
-C<\w> and C<\W> [perl #78464] [perl #18281] [perl #60156].
-
-=item *
-
-Matching a Unicode character against an alternation containing characters
-that happened to match continuation bytes in the former's UTF8
-representation (like C<qq{\x{30ab}} =~ /\xab|\xa9/>) would cause erroneous
-warnings [perl #70998].
-
-=item *
-
-The trie optimisation was not taking empty groups into account, preventing
-"foo" from matching C</\A(?:(?:)foo|bar|zot)\z/> [perl #78356].
-
-=item *
-
-A pattern containing a C<+> inside a lookahead would sometimes cause an
-incorrect match failure in a global match (for example, C</(?=(\S+))/g>)
-[perl #68564].
-
-=item *
-
-A regular expression optimisation would sometimes cause a match with a
-C<{n,m}> quantifier to fail when it should have matched [perl #79152].
-
-=item *
-
-Case-insensitive matching in regular expressions compiled under
-C<use locale> now works much more sanely when the pattern or target
-string is internally encoded in UTF8. Previously, under these
-conditions the localeness was completely lost. Now, code points
-above 255 are treated as Unicode, but code points between 0 and 255
-are treated using the current locale rules, regardless of whether
-the pattern or the string is encoded in UTF8. The few case-insensitive
-matches that cross the 255/256 boundary are not allowed. For
-example, 0xFF does not caselessly match the character at 0x178,
-LATIN CAPITAL LETTER Y WITH DIAERESIS, because 0xFF may not be LATIN
-SMALL LETTER Y in the current locale, and Perl has no way of knowing
-if that character even exists in the locale, much less what code
-point it is.
-
-=item *
-
-The C<(?|...)> regular expression construct no longer crashes if the final
-branch has more sets of capturing parentheses than any other branch. This
-was fixed in Perl 5.10.1 for the case of a single branch, but that fix did
-not take multiple branches into account [perl #84746].
-
-=item *
-
-A bug has been fixed in the implementation of C<{...}> quantifiers in
-regular expressions that prevented the code block in
-C</((\w+)(?{ print $2 })){2}/> from seeing the C<$2> sometimes
-[perl #84294].
-
-=back
-
-=head2 Syntax/Parsing Bugs
-
-=over
-
-=item *
-
-C<when (scalar) {...}> no longer crashes, but produces a syntax error
-[perl #74114] (5.12.1).
-
-=item *
-
-A label right before a string eval (C<foo: eval $string>) no longer causes
-the label to be associated also with the first statement inside the eval
-[perl #74290] (5.12.1).
-
-=item *
-
-The C<no 5.13.2> form of C<no> no longer tries to turn on features or
-pragmata (like L<strict>) [perl #70075] (5.12.2).
-
-=item *
-
-C<BEGIN {require 5.12.0}> now behaves as documented, rather than behaving
-identically to C<use 5.12.0>. Previously, C<require> in a C<BEGIN> block
-was erroneously executing the C<use feature ':5.12.0'> and
-C<use strict> behaviour, which only C<use> was documented to
-provide [perl #69050].
-
-=item *
-
-A regression introduced in Perl 5.12.0, making
-C<< my $x = 3; $x = length(undef) >> result in C<$x> set to C<3> has been
-fixed. C<$x> will now be C<undef> [perl #85508] (5.12.2).
-
-=item *
-
-When strict "refs" mode is off, C<%{...}> in rvalue context returns
-C<undef> if its argument is undefined. An optimisation introduced in Perl
-5.12.0 to make C<keys %{...}> faster when used as a boolean did not take
-this into account, causing C<keys %{+undef}> (and C<keys %$foo> when
-C<$foo> is undefined) to be an error, which it should be so in strict
-mode only [perl #81750].
-
-=item *
-
-Constant-folding used to cause
-
- $text =~ ( 1 ? /phoo/ : /bear/)
-
-to turn into
-
- $text =~ /phoo/
-
-at compile time. Now it correctly matches against C<$_> [perl #20444].
-
-=item *
-
-Parsing Perl code (either with string C<eval> or by loading modules) from
-within a C<UNITCHECK> block no longer causes the interpreter to crash
-[perl #70614].
-
-=item *
-
-String C<eval>s no longer fail after 2 billion scopes have been
-compiled [perl #83364].
-
-=item *
-
-The parser no longer hangs when encountering certain Unicode characters,
-such as U+387 [perl #74022].
-
-=item *
-
-Defining a constant with the same name as one of Perl's special blocks
-(like C<INIT>) stopped working in 5.12.0, but has now been fixed
-[perl #78634].
-
-=item *
-
-A reference to a literal value used as a hash key (C<$hash{\"foo"}>) used
-to be stringified, even if the hash was tied [perl #79178].
-
-=item *
-
-A closure containing an C<if> statement followed by a constant or variable
-is no longer treated as a constant [perl #63540].
-
-=item *
-
-C<state> can now be used with attributes. It
-used to mean the same thing as
-C<my> if any attributes were present [perl #68658].
-
-=item *
-
-Expressions like C<< @$a > 3 >> no longer cause C<$a> to be mentioned in
-the "Use of uninitialized value in numeric gt" warning when C<$a> is
-undefined (since it is not part of the C<< > >> expression, but the operand
-of the C<@>) [perl #72090].
-
-=item *
-
-Accessing an element of a package array with a hard-coded number (as
-opposed to an arbitrary expression) would crash if the array did not exist.
-Usually the array would be autovivified during compilation, but typeglob
-manipulation could remove it, as in these two cases which used to crash:
-
- *d = *a; print $d[0];
- undef *d; print $d[0];
-
-=item *
-
-The B<-C> command-line option, when used on the shebang line, can now be
-followed by other options [perl #72434].
-
-=item *
-
-The C<B> module was returning C<B::OP>s instead of C<B::LOGOP>s for
-C<entertry> [perl #80622]. This was due to a bug in the Perl core,
-not in C<B> itself.
-
-=back
-
-=head2 Stashes, Globs and Method Lookup
-
-Perl 5.10.0 introduced a new internal mechanism for caching MROs (method
-resolution orders, or lists of parent classes; aka "isa" caches) to make
-method lookup faster (so C<@ISA> arrays would not have to be searched
-repeatedly). Unfortunately, this brought with it quite a few bugs. Almost
-all of these have been fixed now, along with a few MRO-related bugs that
-existed before 5.10.0:
-
-=over
-
-=item *
-
-The following used to have erratic effects on method resolution, because
-the "isa" caches were not reset or otherwise ended up listing the wrong
-classes. These have been fixed.
-
-=over
-
-=item Aliasing packages by assigning to globs [perl #77358]
-
-=item Deleting packages by deleting their containing stash elements
-
-=item Undefining the glob containing a package (C<undef *Foo::>)
-
-=item Undefining an ISA glob (C<undef *Foo::ISA>)
-
-=item Deleting an ISA stash element (C<delete $Foo::{ISA}>)
-
-=item Sharing @ISA arrays between classes (via C<*Foo::ISA = \@Bar::ISA> or
-C<*Foo::ISA = *Bar::ISA>) [perl #77238]
-
-=back
-
-C<undef *Foo::ISA> would even stop a new C<@Foo::ISA> array from updating
-caches.
-
-=item *
-
-Typeglob assignments would crash if the glob's stash no longer existed, so
-long as the glob assigned to were named C<ISA> or the glob on either side of
-the assignment contained a subroutine.
-
-=item *
-
-C<PL_isarev>, which is accessible to Perl via C<mro::get_isarev> is now
-updated properly when packages are deleted or removed from the C<@ISA> of
-other classes. This allows many packages to be created and deleted without
-causing a memory leak [perl #75176].
-
-=back
-
-In addition, various other bugs related to typeglobs and stashes have been
-fixed:
-
-=over
-
-=item *
-
-Some work has been done on the internal pointers that link between symbol
-tables (stashes), typeglobs, and subroutines. This has the effect that
-various edge cases related to deleting stashes or stash entries (for example,
-<%FOO:: = ()>), and complex typeglob or code-reference aliasing, will no
-longer crash the interpreter.
-
-=item *
-
-Assigning a reference to a glob copy now assigns to a glob slot instead of
-overwriting the glob with a scalar [perl #1804] [perl #77508].
-
-=item *
-
-A bug when replacing the glob of a loop variable within the loop has been fixed
-[perl #21469]. This
-means the following code will no longer crash:
-
- for $x (...) {
- *x = *y;
- }
-
-=item *
-
-Assigning a glob to a PVLV used to convert it to a plain string. Now it
-works correctly, and a PVLV can hold a glob. This would happen when a
-nonexistent hash or array element was passed to a subroutine:
-
- sub { $_[0] = *foo }->($hash{key});
- # $_[0] would have been the string "*main::foo"
-
-It also happened when a glob was assigned to, or returned from, an element
-of a tied array or hash [perl #36051].
-
-=item *
-
-When trying to report C<Use of uninitialized value $Foo::BAR>, crashes could
-occur if the glob holding the global variable in question had been detached
-from its original stash by, for example, C<delete $::{"Foo::"}>. This has
-been fixed by disabling the reporting of variable names in those
-cases.
-
-=item *
-
-During the restoration of a localised typeglob on scope exit, any
-destructors called as a result would be able to see the typeglob in an
-inconsistent state, containing freed entries, which could result in a
-crash. This would affect code like this:
-
- local *@;
- eval { die bless [] }; # puts an object in $@
- sub DESTROY {
- local $@; # boom
- }
-
-Now the glob entries are cleared before any destructors are called. This
-also means that destructors can vivify entries in the glob. So Perl tries
-again and, if the entries are re-created too many times, dies with a
-"panic: gp_free ..." error message.
-
-=item *
-
-If a typeglob is freed while a subroutine attached to it is still
-referenced elsewhere, the subroutine is renamed to C<__ANON__> in the same
-package, unless the package has been undefined, in which case the C<__ANON__>
-package is used. This could cause packages to be sometimes autovivified,
-such as if the package had been deleted. Now this no longer occurs.
-The C<__ANON__> package is also now used when the original package is
-no longer attached to the symbol table. This avoids memory leaks in some
-cases [perl #87664].
-
-=item *
-
-Subroutines and package variables inside a package whose name ends with
-C<::> can now be accessed with a fully qualified name.
-
-=back
-
-=head2 Unicode
-
-=over
-
-=item *
-
-What has become known as "the Unicode Bug" is almost completely resolved in
-this release. Under C<use feature 'unicode_strings'> (which is
-automatically selected by C<use 5.012> and above), the internal
-storage format of a string no longer affects the external semantics.
-[perl #58182].
-
-There are two known exceptions:
-
-=over
-
-=item 1
-
-The now-deprecated, user-defined case-changing
-functions require utf8-encoded strings to operate. The CPAN module
-L<Unicode::Casing> has been written to replace this feature without its
-drawbacks, and the feature is scheduled to be removed in 5.16.
-
-=item 2
-
-quotemeta() (and its in-line equivalent C<\Q>) can also give different
-results depending on whether a string is encoded in UTF-8. See
-L<perlunicode/The "Unicode Bug">.
-
-=back
-
-=item *
-
-Handling of Unicode non-character code points has changed.
-Previously they were mostly considered illegal, except that in some
-place only one of the 66 of them was known. The Unicode Standard
-considers them all legal, but forbids their "open interchange".
-This is part of the change to allow internal use of any code
-point (see L</Core Enhancements>). Together, these changes resolve
-[perl #38722], [perl #51918], [perl #51936], and [perl #63446].
-
-=item *
-
-Case-insensitive C<"/i"> regular expression matching of Unicode
-characters that match multiple characters now works much more as
-intended. For example
-
- "\N{LATIN SMALL LIGATURE FFI}" =~ /ffi/ui
-
-and
-
- "ffi" =~ /\N{LATIN SMALL LIGATURE FFI}/ui
-
-are both true. Previously, there were many bugs with this feature.
-What hasn't been fixed are the places where the pattern contains the
-multiple characters, but the characters are split up by other things,
-such as in
-
- "\N{LATIN SMALL LIGATURE FFI}" =~ /(f)(f)i/ui
-
-or
-
- "\N{LATIN SMALL LIGATURE FFI}" =~ /ffi*/ui
-
-or
-
- "\N{LATIN SMALL LIGATURE FFI}" =~ /[a-f][f-m][g-z]/ui
-
-None of these match.
-
-Also, this matching doesn't fully conform to the current Unicode
-Standard, which asks that the matching be made upon the NFD
-(Normalization Form Decomposed) of the text. However, as of this
-writing (April 2010), the Unicode Standard is currently in flux about
-what they will recommend doing with regard in such scenarios. It may be
-that they will throw out the whole concept of multi-character matches.
-[perl #71736].
-
-=item *
-
-Naming a deprecated character in C<\N{I<NAME>}> no longer leaks memory.
-
-=item *
-
-We fixed a bug that could cause C<\N{I<NAME>}> constructs followed by
-a single C<"."> to be parsed incorrectly [perl #74978] (5.12.1).
-
-=item *
-
-C<chop> now correctly handles characters above C<"\x{7fffffff}">
-[perl #73246].
-
-=item *
-
-Passing to C<index> an offset beyond the end of the string when the string
-is encoded internally in UTF8 no longer causes panics [perl #75898].
-
-=item *
-
-warn() and die() now respect utf8-encoded scalars [perl #45549].
-
-=item *
-
-Sometimes the UTF8 length cache would not be reset on a value
-returned by substr, causing C<length(substr($uni_string, ...))> to give
-wrong answers. With C<${^UTF8CACHE}> set to -1, it would also produce
-a "panic" error message [perl #77692].
-
-=back
-
-=head2 Ties, Overloading and Other Magic
-
-=over
-
-=item *
-
-Overloading now works properly in conjunction with tied
-variables. What formerly happened was that most ops checked their
-arguments for overloading I<before> checking for magic, so for example
-an overloaded object returned by a tied array access would usually be
-treated as not overloaded [RT #57012].
-
-=item *
-
-Various instances of magic (like tie methods) being called on tied variables
-too many or too few times have been fixed:
-
-=over
-
-=item *
-
-C<< $tied->() >> did not always call FETCH [perl #8438].
-
-=item *
-
-Filetest operators and C<y///> and C<tr///> were calling FETCH too
-many times.
-
-=item *
-
-The C<=> operator used to ignore magic on its right-hand side if the
-scalar happened to hold a typeglob (if a typeglob was the last thing
-returned from or assigned to a tied scalar) [perl #77498].
-
-=item *
-
-Dereference operators used to ignore magic if the argument was a
-reference already (such as from a previous FETCH) [perl #72144].
-
-=item *
-
-C<splice> now calls set-magic (so changes made
-by C<splice @ISA> are respected by method calls) [perl #78400].
-
-=item *
-
-In-memory files created by C<< open($fh, ">", \$buffer) >> were not calling
-FETCH/STORE at all [perl #43789] (5.12.2).
-
-=item *
-
-utf8::is_utf8() now respects get-magic (like C<$1>) (5.12.1).
-
-=back
-
-=item *
-
-Non-commutative binary operators used to swap their operands if the same
-tied scalar was used for both operands and returned a different value for
-each FETCH. For instance, if C<$t> returned 2 the first time and 3 the
-second, then C<$t/$t> would evaluate to 1.5. This has been fixed
-[perl #87708].
-
-=item *
-
-String C<eval> now detects taintedness of overloaded or tied
-arguments [perl #75716].
-
-=item *
-
-String C<eval> and regular expression matches against objects with string
-overloading no longer cause memory corruption or crashes [perl #77084].
-
-=item *
-
-L<readline|perlfunc/"readline EXPR"> now honors C<< <> >> overloading on tied
-arguments.
-
-=item *
-
-C<< <expr> >> always respects overloading now if the expression is
-overloaded.
-
-Because "S<< <> as >> glob" was parsed differently from
-"S<< <> as >> filehandle" from 5.6 onwards, something like C<< <$foo[0]> >> did
-not handle overloading, even if C<$foo[0]> was an overloaded object. This
-was contrary to the documentation for L<overload>, and meant that C<< <> >>
-could not be used as a general overloaded iterator operator.
-
-=item *
-
-The fallback behaviour of overloading on binary operators was asymmetric
-[perl #71286].
-
-=item *
-
-Magic applied to variables in the main package no longer affects other packages.
-See L</Magic variables outside the main package> above [perl #76138].
-
-=item *
-
-Sometimes magic (ties, taintedness, etc.) attached to variables could cause
-an object to last longer than it should, or cause a crash if a tied
-variable were freed from within a tie method. These have been fixed
-[perl #81230].
-
-=item *
-
-DESTROY methods of objects implementing ties are no longer able to crash by
-accessing the tied variable through a weak reference [perl #86328].
-
-=item *
-
-Fixed a regression of kill() when a match variable is used for the
-process ID to kill [perl #75812].
-
-=item *
-
-C<$AUTOLOAD> used to remain tainted forever if it ever became tainted. Now
-it is correctly untainted if an autoloaded method is called and the method
-name was not tainted.
-
-=item *
-
-C<sprintf> now dies when passed a tainted scalar for the format. It did
-already die for arbitrary expressions, but not for simple scalars
-[perl #82250].
-
-=item *
-
-C<lc>, C<uc>, C<lcfirst>, and C<ucfirst> no longer return untainted strings
-when the argument is tainted. This has been broken since perl 5.8.9
-[perl #87336].
-
-=back
-
-=head2 The Debugger
-
-=over
-
-=item *
-
-The Perl debugger now also works in taint mode [perl #76872].
-
-=item *
-
-Subroutine redefinition works once more in the debugger [perl #48332].
-
-=item *
-
-When B<-d> is used on the shebang (C<#!>) line, the debugger now has access
-to the lines of the main program. In the past, this sometimes worked and
-sometimes did not, depending on the order in which things happened to be
-arranged in memory [perl #71806].
-
-=item *
-
-A possible memory leak when using L<caller()|perlfunc/"caller EXPR"> to set
-C<@DB::args> has been fixed (5.12.2).
-
-=item *
-
-Perl no longer stomps on C<$DB::single>, C<$DB::trace>, and C<$DB::signal>
-if these variables already have values when C<$^P> is assigned to [perl #72422].
-
-=item *
-
-C<#line> directives in string evals were not properly updating the arrays
-of lines of code (C<< @{"_< ..."} >>) that the debugger (or any debugging or
-profiling module) uses. In threaded builds, they were not being updated at
-all. In non-threaded builds, the line number was ignored, so any change to
-the existing line number would cause the lines to be misnumbered
-[perl #79442].
-
-=back
-
-=head2 Threads
-
-=over
-
-=item *
-
-Perl no longer accidentally clones lexicals in scope within active stack
-frames in the parent when creating a child thread [perl #73086].
-
-=item *
-
-Several memory leaks in cloning and freeing threaded Perl interpreters have been
-fixed [perl #77352].
-
-=item *
-
-Creating a new thread when directory handles were open used to cause a
-crash, because the handles were not cloned, but simply passed to the new
-thread, resulting in a double free.
-
-Now directory handles are cloned properly on Windows
-and on systems that have a C<fchdir> function. On other
-systems, new threads simply do not inherit directory
-handles from their parent threads [perl #75154].
-
-=item *
-
-The typeglob C<*,>, which holds the scalar variable C<$,> (output field
-separator), had the wrong reference count in child threads.
-
-=item *
-
-[perl #78494] When pipes are shared between threads, the C<close> function
-(and any implicit close, such as on thread exit) no longer blocks.
-
-=item *
-
-Perl now does a timely cleanup of SVs that are cloned into a new
-thread but then discovered to be orphaned (that is, their owners
-are I<not> cloned). This eliminates several "scalars leaked"
-warnings when joining threads.
-
-=back
-
-=head2 Scoping and Subroutines
-
-=over
-
-=item *
-
-Lvalue subroutines are again able to return copy-on-write scalars. This
-had been broken since version 5.10.0 [perl #75656] (5.12.3).
-
-=item *
-
-C<require> no longer causes C<caller> to return the wrong file name for
-the scope that called C<require> and other scopes higher up that had the
-same file name [perl #68712].
-
-=item *
-
-C<sort> with a C<($$)>-prototyped comparison routine used to cause the value
-of C<@_> to leak out of the sort. Taking a reference to C<@_> within the
-sorting routine could cause a crash [perl #72334].
-
-=item *
-
-Match variables (like C<$1>) no longer persist between calls to a sort
-subroutine [perl #76026].
-
-=item *
-
-Iterating with C<foreach> over an array returned by an lvalue sub now works
-[perl #23790].
-
-=item *
-
-C<$@> is now localised during calls to C<binmode> to prevent action at a
-distance [perl #78844].
-
-=item *
-
-Calling a closure prototype (what is passed to an attribute handler for a
-closure) now results in a "Closure prototype called" error message instead
-of a crash [perl #68560].
-
-=item *
-
-Mentioning a read-only lexical variable from the enclosing scope in a
-string C<eval> no longer causes the variable to become writable
-[perl #19135].
-
-=back
-
-=head2 Signals
-
-=over
-
-=item *
-
-Within signal handlers, C<$!> is now implicitly localized.
-
-=item *
-
-CHLD signals are no longer unblocked after a signal handler is called if
-they were blocked before by C<POSIX::sigprocmask> [perl #82040].
-
-=item *
-
-A signal handler called within a signal handler could cause leaks or
-double-frees. Now fixed [perl #76248].
-
-=back
-
-=head2 Miscellaneous Memory Leaks
-
-=over
-
-=item *
-
-Several memory leaks when loading XS modules were fixed (5.12.2).
-
-=item *
-
-L<substr()|perlfunc/"substr EXPR,OFFSET,LENGTH,REPLACEMENT">,
-L<pos()|perlfunc/"index STR,SUBSTR,POSITION">, L<keys()|perlfunc/"keys HASH">,
-and L<vec()|perlfunc/"vec EXPR,OFFSET,BITS"> could, when used in combination
-with lvalues, result in leaking the scalar value they operate on, and cause its
-destruction to happen too late. This has now been fixed.
-
-=item *
-
-The postincrement and postdecrement operators, C<++> and C<-->, used to cause
-leaks when used on references. This has now been fixed.
-
-=item *
-
-Nested C<map> and C<grep> blocks no longer leak memory when processing
-large lists [perl #48004].
-
-=item *
-
-C<use I<VERSION>> and C<no I<VERSION>> no longer leak memory [perl #78436]
-[perl #69050].
-
-=item *
-
-C<.=> followed by C<< <> >> or C<readline> would leak memory if C<$/>
-contained characters beyond the octet range and the scalar assigned to
-happened to be encoded as UTF8 internally [perl #72246].
-
-=item *
-
-C<eval 'BEGIN{die}'> no longer leaks memory on non-threaded builds.
-
-=back
-
-=head2 Memory Corruption and Crashes
-
-=over
-
-=item *
-
-glob() no longer crashes when C<%File::Glob::> is empty and
-C<CORE::GLOBAL::glob> isn't present [perl #75464] (5.12.2).
-
-=item *
-
-readline() has been fixed when interrupted by signals so it no longer
-returns the "same thing" as before or random memory.
-
-=item *
-
-When assigning a list with duplicated keys to a hash, the assignment used to
-return garbage and/or freed values:
-
- @a = %h = (list with some duplicate keys);
-
-This has now been fixed [perl #31865].
-
-=item *
-
-The mechanism for freeing objects in globs used to leave dangling
-pointers to freed SVs, meaning Perl users could see corrupted state
-during destruction.
-
-Perl now frees only the affected slots of the GV, rather than freeing
-the GV itself. This makes sure that there are no dangling refs or
-corrupted state during destruction.
-
-=item *
-
-The interpreter no longer crashes when freeing deeply-nested arrays of
-arrays. Hashes have not been fixed yet [perl #44225].
-
-=item *
-
-Concatenating long strings under C<use encoding> no longer causes Perl to
-crash [perl #78674].
-
-=item *
-
-Calling C<< ->import >> on a class lacking an import method could corrupt
-the stack, resulting in strange behaviour. For instance,
-
- push @a, "foo", $b = bar->import;
-
-would assign "foo" to C<$b> [perl #63790].
-
-=item *
-
-The C<recv> function could crash when called with the MSG_TRUNC flag
-[perl #75082].
-
-=item *
-
-C<formline> no longer crashes when passed a tainted format picture. It also
-taints C<$^A> now if its arguments are tainted [perl #79138].
-
-=item *
-
-A bug in how we process filetest operations could cause a segfault.
-Filetests don't always expect an op on the stack, so we now use
-TOPs only if we're sure that we're not C<stat>ing the C<_> filehandle.
-This is indicated by C<OPf_KIDS> (as checked in ck_ftst) [perl #74542]
-(5.12.1).
-
-=item *
-
-unpack() now handles scalar context correctly for C<%32H> and C<%32u>,
-fixing a potential crash. split() would crash because the third item
-on the stack wasn't the regular expression it expected. C<unpack("%2H",
-...)> would return both the unpacked result and the checksum on the stack,
-as would C<unpack("%2u", ...)> [perl #73814] (5.12.2).
-
-=back
-
-=head2 Fixes to Various Perl Operators
-
-=over
-
-=item *
-
-The C<&>, C<|>, and C<^> bitwise operators no longer coerce read-only arguments
-[perl #20661].
-
-=item *
-
-Stringifying a scalar containing "-0.0" no longer has the effect of turning
-false into true [perl #45133].
-
-=item *
-
-Some numeric operators were converting integers to floating point,
-resulting in loss of precision on 64-bit platforms [perl #77456].
-
-=item *
-
-sprintf() was ignoring locales when called with constant arguments
-[perl #78632].
-
-=item *
-
-Combining the vector (C<%v>) flag and dynamic precision would
-cause C<sprintf> to confuse the order of its arguments, making it
-treat the string as the precision and vice-versa [perl #83194].
-
-=back
-
-=head2 Bugs Relating to the C API
-
-=over
-
-=item *
-
-The C-level C<lex_stuff_pvn> function would sometimes cause a spurious
-syntax error on the last line of the file if it lacked a final semicolon
-[perl #74006] (5.12.1).
-
-=item *
-
-The C<eval_sv> and C<eval_pv> C functions now set C<$@> correctly when
-there is a syntax error and no C<G_KEEPERR> flag, and never set it if the
-C<G_KEEPERR> flag is present [perl #3719].
-
-=item *
-
-The XS multicall API no longer causes subroutines to lose reference counts
-if called via the multicall interface from within those very subroutines.
-This affects modules like L<List::Util>. Calling one of its functions with an
-active subroutine as the first argument could cause a crash [perl #78070].
-
-=item *
-
-The C<SvPVbyte> function available to XS modules now calls magic before
-downgrading the SV, to avoid warnings about wide characters [perl #72398].
-
-=item *
-
-The ref types in the typemap for XS bindings now support magical variables
-[perl #72684].
-
-=item *
-
-C<sv_catsv_flags> no longer calls C<mg_get> on its second argument (the
-source string) if the flags passed to it do not include SV_GMAGIC. So it
-now matches the documentation.
-
-=item *
-
-C<my_strftime> no longer leaks memory. This fixes a memory leak in
-C<POSIX::strftime> [perl #73520].
-
-=item *
-
-F<XSUB.h> now correctly redefines fgets under PERL_IMPLICIT_SYS [perl #55049]
-(5.12.1).
-
-=item *
-
-XS code using fputc() or fputs() on Windows could cause an error
-due to their arguments being swapped [perl #72704] (5.12.1).
-
-=item *
-
-A possible segfault in the C<T_PTROBJ> default typemap has been fixed
-(5.12.2).
-
-=item *
-
-A bug that could cause "Unknown error" messages when
-C<call_sv(code, G_EVAL)> is called from an XS destructor has been fixed
-(5.12.2).
-
-=back
-
-=head1 Known Problems
-
-This is a list of significant unresolved issues which are regressions
-from earlier versions of Perl or which affect widely-used CPAN modules.
-
-=over 4
-
-=item *
-
-C<List::Util::first> misbehaves in the presence of a lexical C<$_>
-(typically introduced by C<my $_> or implicitly by C<given>). The variable
-that gets set for each iteration is the package variable C<$_>, not the
-lexical C<$_>.
-
-A similar issue may occur in other modules that provide functions which
-take a block as their first argument, like
-
- foo { ... $_ ...} list
-
-See also: L<http://rt.perl.org/rt3/Public/Bug/Display.html?id=67694>
-
-=item *
-
-readline() returns an empty string instead of a cached previous value
-when it is interrupted by a signal
-
-=item *
-
-The changes in prototype handling break L<Switch>. A patch has been sent
-upstream and will hopefully appear on CPAN soon.
-
-=item *
-
-The upgrade to F<ExtUtils-MakeMaker-6.57_05> has caused
-some tests in the F<Module-Install> distribution on CPAN to
-fail. (Specifically, F<02_mymeta.t> tests 5 and 21; F<18_all_from.t>
-tests 6 and 15; F<19_authors.t> tests 5, 13, 21, and 29; and
-F<20_authors_with_special_characters.t> tests 6, 15, and 23 in version
-1.00 of that distribution now fail.)
-
-=item *
-
-On VMS, C<Time::HiRes> tests will fail due to a bug in the CRTL's
-implementation of C<setitimer>: previous timer values would be cleared
-if a timer expired but not if the timer was reset before expiring. HP
-OpenVMS Engineering have corrected the problem and will release a patch
-in due course (Quix case # QXCM1001115136).
-
-=item *
-
-On VMS, there were a handful of C<Module::Build> test failures we didn't
-get to before the release; please watch CPAN for updates.
-
-=back
-
-=head1 Errata
-
-=head2 keys(), values(), and each() work on arrays
-
-You can now use the keys(), values(), and each() builtins on arrays;
-previously you could use them only on hashes. See L<perlfunc> for details.
-This is actually a change introduced in perl 5.12.0, but it was missed from
-that release's L<perl5120delta>.
-
-=head2 split() and C<@_>
-
-split() no longer modifies C<@_> when called in scalar or void context.
-In void context it now produces a "Useless use of split" warning.
-This was also a perl 5.12.0 change that missed the perldelta.
-
-=head1 Obituary
-
-Randy Kobes, creator of http://kobesearch.cpan.org/ and
-contributor/maintainer to several core Perl toolchain modules, passed
-away on September 18, 2010 after a battle with lung cancer. The community
-was richer for his involvement. He will be missed.
-
-=head1 Acknowledgements
-
-Perl 5.14.0 represents one year of development since
-Perl 5.12.0 and contains nearly 550,000 lines of changes across nearly
-3,000 files from 150 authors and committers.
-
-Perl continues to flourish into its third decade thanks to a vibrant
-community of users and developers. The following people are known to
-have contributed the improvements that became Perl 5.14.0:
-
-Aaron Crane, Abhijit Menon-Sen, Abigail, Ævar Arnfjörð Bjarmason,
-Alastair Douglas, Alexander Alekseev, Alexander Hartmaier, Alexandr
-Ciornii, Alex Davies, Alex Vandiver, Ali Polatel, Allen Smith, Andreas
-König, Andrew Rodland, Andy Armstrong, Andy Dougherty, Aristotle
-Pagaltzis, Arkturuz, Arvan, A. Sinan Unur, Ben Morrow, Bo Lindbergh,
-Boris Ratner, Brad Gilbert, Bram, brian d foy, Brian Phillips, Casey
-West, Charles Bailey, Chas. Owens, Chip Salzenberg, Chris 'BinGOs'
-Williams, chromatic, Craig A. Berry, Curtis Jewell, Dagfinn Ilmari
-Mannsåker, Dan Dascalescu, Dave Rolsky, David Caldwell, David Cantrell,
-David Golden, David Leadbeater, David Mitchell, David Wheeler, Eric
-Brine, Father Chrysostomos, Fingle Nark, Florian Ragwitz, Frank Wiegand,
-Franz Fasching, Gene Sullivan, George Greer, Gerard Goossen, Gisle Aas,
-Goro Fuji, Grant McLean, gregor herrmann, H.Merijn Brand, Hongwen Qiu,
-Hugo van der Sanden, Ian Goodacre, James E Keenan, James Mastros, Jan
-Dubois, Jay Hannah, Jerry D. Hedden, Jesse Vincent, Jim Cromie, Jirka
-Hruška, John Peacock, Joshua ben Jore, Joshua Pritikin, Karl Williamson,
-Kevin Ryde, kmx, Lars Dɪᴇᴄᴋá´á´¡ 迪拉斯, Larwan Berke, Leon Brocard, Leon
-Timmermans, Lubomir Rintel, Lukas Mai, Maik Hentsche, Marty Pauley,
-Marvin Humphrey, Matt Johnson, Matt S Trout, Max Maischein, Michael
-Breen, Michael Fig, Michael G Schwern, Michael Parker, Michael Stevens,
-Michael Witten, Mike Kelly, Moritz Lenz, Nicholas Clark, Nick Cleaton,
-Nick Johnston, Nicolas Kaiser, Niko Tyni, Noirin Shirley, Nuno Carvalho,
-Paul Evans, Paul Green, Paul Johnson, Paul Marquess, Peter J. Holzer,
-Peter John Acklam, Peter Martini, Philippe Bruhat (BooK), Piotr Fusik,
-Rafael Garcia-Suarez, Rainer Tammer, Reini Urban, Renee Baecker, Ricardo
-Signes, Richard Möhn, Richard Soderberg, Rob Hoelz, Robin Barker, Ruslan
-Zakirov, Salvador Fandiño, Salvador Ortiz Garcia, Shlomi Fish, Sinan
-Unur, Sisyphus, Slaven Rezic, Steffen Müller, Steve Hay, Steven
-Schubiger, Steve Peters, Sullivan Beck, Tatsuhiko Miyagawa, Tim Bunce,
-Todd Rinaldo, Tom Christiansen, Tom Hukins, Tony Cook, Tye McQueen,
-Vadim Konovalov, Vernon Lyon, Vincent Pit, Walt Mankowski, Wolfram
-Humann, Yves Orton, Zefram, and Zsbán Ambrus.
-
-This is woefully incomplete as it's automatically generated from version
-control history. In particular, it doesn't include the names of the
-(very much appreciated) contributors who reported issues in previous
-versions of Perl that helped make Perl 5.14.0 better. For a more complete
-list of all of Perl's historical contributors, please see the C<AUTHORS>
-file in the Perl 5.14.0 distribution.
-
-Many of the changes included in this version originated in the CPAN
-modules included in Perl's core. We're grateful to the entire CPAN
-community for helping Perl to flourish.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the Perl
-bug database at http://rt.perl.org/perlbug/ . There may also be
-information at http://www.perl.org/ , the Perl Home Page.
-
-If you believe you have an unreported bug, please run the L<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team.
-
-If the bug you are reporting has security implications, which make it
-inappropriate to send to a publicly archived mailing list, then please send
-it to perl5-security-report@perl.org. This points to a closed subscription
-unarchived mailing list, which includes all the core committers, who are able
-to help assess the impact of issues, figure out a resolution, and help
-co-ordinate the release of patches to mitigate or fix the problem across all
-platforms on which Perl is supported. Please use this address for
-security issues in the Perl core I<only>, not for modules independently
-distributed on CPAN.
-
-=head1 SEE ALSO
-
-The F<Changes> file for an explanation of how to view exhaustive details
-on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl5141delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5141delta.pod
deleted file mode 100644
index db24343c695..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl5141delta.pod
+++ /dev/null
@@ -1,361 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perl5141delta - what is new for perl v5.14.1
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.14.0 release and
-the 5.14.1 release.
-
-If you are upgrading from an earlier release such as 5.12.0, first read
-L<perl5140delta>, which describes differences between 5.12.0 and
-5.14.0.
-
-=head1 Core Enhancements
-
-No changes since 5.14.0.
-
-=head1 Security
-
-No changes since 5.14.0.
-
-=head1 Incompatible Changes
-
-There are no changes intentionally incompatible with 5.14.0. If any
-exist, they are bugs and reports are welcome.
-
-=head1 Deprecations
-
-There have been no deprecations since 5.14.0.
-
-=head1 Modules and Pragmata
-
-=head2 New Modules and Pragmata
-
-None
-
-=head2 Updated Modules and Pragmata
-
-=over 4
-
-=item *
-
-L<B::Deparse> has been upgraded from version 1.03 to 1.04, to address two
-regressions in Perl 5.14.0:
-
-Deparsing of the C<glob> operator and its diamond (C<< <> >>) form now
-works again. [perl #90898]
-
-The presence of subroutines named C<::::> or C<::::::> no longer causes
-B::Deparse to hang.
-
-=item *
-
-L<Pod::Perldoc> has been upgraded from version 3.15_03 to 3.15_04.
-
-It corrects the search paths on VMS. [perl #90640]
-
-=back
-
-=head2 Removed Modules and Pragmata
-
-None
-
-=head1 Documentation
-
-=head2 New Documentation
-
-None
-
-=head2 Changes to Existing Documentation
-
-=head3 L<perlfunc>
-
-=over
-
-=item *
-
-C<given>, C<when> and C<default> are now listed in L<perlfunc>.
-
-=item *
-
-Documentation for C<use> now includes a pointer to F<if.pm>.
-
-=back
-
-=head3 L<perllol>
-
-=over
-
-=item *
-
-L<perllol> has been expanded with examples using the new C<push $scalar>
-syntax introduced in Perl 5.14.0.
-
-=back
-
-=head3 L<perlop>
-
-=over 4
-
-=item *
-
-The explanation of bitwise operators has been expanded to explain how they
-work on Unicode strings.
-
-=item *
-
-The section on the triple-dot or yada-yada operator has been moved up, as
-it used to separate two closely related sections about the comma operator.
-
-=item *
-
-More examples for C<m//g> have been added.
-
-=item *
-
-The C<<< <<\FOO >>> here-doc syntax has been documented.
-
-=back
-
-=head3 L<perlrun>
-
-=over
-
-=item *
-
-L<perlrun> has undergone a significant clean-up. Most notably, the
-B<-0x...> form of the B<-0> flag has been clarified, and the final section
-on environment variables has been corrected and expanded.
-
-=back
-
-=head3 L<POSIX>
-
-=over
-
-=item *
-
-The invocation documentation for C<WIFEXITED>, C<WEXITSTATUS>,
-C<WIFSIGNALED>, C<WTERMSIG>, C<WIFSTOPPED>, and C<WSTOPSIG> was corrected.
-
-=back
-
-
-=head1 Diagnostics
-
-The following additions or changes have been made to diagnostic output,
-including warnings and fatal error messages. For the complete list of
-diagnostic messages, see L<perldiag>.
-
-=head2 New Diagnostics
-
-None
-
-=head2 Changes to Existing Diagnostics
-
-None
-
-=head1 Utility Changes
-
-None
-
-=head1 Configuration and Compilation
-
-=over 4
-
-=item *
-
-F<regexp.h> has been modified for compatibility with GCC's C<-Werror>
-option, as used by some projects that include perl's header files.
-
-=back
-
-=head1 Testing
-
-=over 4
-
-=item *
-
-Some test failures in F<dist/Locale-Maketext/t/09_compile.t> that could
-occur depending on the environment have been fixed. [perl #89896]
-
-=item *
-
-A watchdog timer for F<t/re/re.t> was lengthened to accommodate SH-4 systems
-which were unable to complete the tests before the previous timer ran out.
-
-
-=back
-
-=head1 Platform Support
-
-=head2 New Platforms
-
-None
-
-=head2 Discontinued Platforms
-
-None
-
-=head2 Platform-Specific Notes
-
-=head3 Solaris
-
-=over
-
-=item *
-
-Documentation listing the Solaris packages required to build Perl on
-Solaris 9 and Solaris 10 has been corrected.
-
-=back
-
-=head3 Mac OS X
-
-=over
-
-=item *
-
-The F<lib/locale.t> test script has been updated to work on the upcoming
-Lion release.
-
-=item *
-
-Mac OS X specific compilation instructions have been clarified.
-
-=back
-
-=head3 Ubuntu Linux
-
-=over
-
-=item *
-
-The L<ODBM_File> installation process has been updated with the new library
-paths on Ubuntu natty.
-
-=back
-
-=head1 Internal Changes
-
-=over
-
-=item *
-
-The compiled representation of formats is now stored via the mg_ptr of
-their PERL_MAGIC_fm. Previously it was stored in the string buffer,
-beyond SvLEN(), the regular end of the string. SvCOMPILED() and
-SvCOMPILED_{on,off}() now exist solely for compatibility for XS code.
-The first is always 0, the other two now no-ops.
-
-=back
-
-=head1 Bug Fixes
-
-=over 4
-
-=item *
-
-A bug has been fixed that would cause a "Use of freed value in iteration"
-error if the next two hash elements that would be iterated over are
-deleted. [perl #85026]
-
-=item *
-
-Passing the same constant subroutine to both C<index> and C<formline> no
-longer causes one or the other to fail. [perl #89218]
-
-=item *
-
-5.14.0 introduced some memory leaks in regular expression character
-classes such as C<[\w\s]>, which have now been fixed.
-
-=item *
-
-An edge case in regular expression matching could potentially loop.
-This happened only under C</i> in bracketed character classes that have
-characters with multi-character folds, and the target string to match
-against includes the first portion of the fold, followed by another
-character that has a multi-character fold that begins with the remaining
-portion of the fold, plus some more.
-
- "s\N{U+DF}" =~ /[\x{DF}foo]/i
-
-is one such case. C<\xDF> folds to C<"ss">.
-
-=item *
-
-Several Unicode case-folding bugs have been fixed.
-
-=item *
-
-The new (in 5.14.0) regular expression modifier C</a> when repeated like
-C</aa> forbids the characters outside the ASCII range that match
-characters inside that range from matching under C</i>. This did not
-work under some circumstances, all involving alternation, such as:
-
- "\N{KELVIN SIGN}" =~ /k|foo/iaa;
-
-succeeded inappropriately. This is now fixed.
-
-=item *
-
-Fixed a case where it was possible that a freed buffer may have been read
-from when parsing a here document.
-
-=back
-
-=head1 Acknowledgements
-
-Perl 5.14.1 represents approximately four weeks of development since
-Perl 5.14.0 and contains approximately 3500 lines of changes
-across 38 files from 17 authors.
-
-Perl continues to flourish into its third decade thanks to a vibrant
-community of users and developers. The following people are known to
-have contributed the improvements that became Perl 5.14.1:
-
-Bo Lindbergh, Claudio Ramirez, Craig A. Berry, David Leadbeater, Father
-Chrysostomos, Jesse Vincent, Jim Cromie, Justin Case, Karl Williamson,
-Leo Lapworth, Nicholas Clark, Nobuhiro Iwamatsu, smash, Tom Christiansen,
-Ton Hospel, Vladimir Timofeev, and Zsbán Ambrus.
-
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://rt.perl.org/perlbug/ . There may also be
-information at http://www.perl.org/ , the Perl Home Page.
-
-If you believe you have an unreported bug, please run the L<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team.
-
-If the bug you are reporting has security implications, which make it
-inappropriate to send to a publicly archived mailing list, then please send
-it to perl5-security-report@perl.org. This points to a closed subscription
-unarchived mailing list, which includes all the core committers, who be able
-to help assess the impact of issues, figure out a resolution, and help
-co-ordinate the release of patches to mitigate or fix the problem across all
-platforms on which Perl is supported. Please only use this address for
-security issues in the Perl core, not for modules independently
-distributed on CPAN.
-
-=head1 SEE ALSO
-
-The F<Changes> file for an explanation of how to view exhaustive details
-on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl5142delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5142delta.pod
deleted file mode 100644
index 3d78ba232bd..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl5142delta.pod
+++ /dev/null
@@ -1,242 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perl5142delta - what is new for perl v5.14.2
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.14.1 release and
-the 5.14.2 release.
-
-If you are upgrading from an earlier release such as 5.14.0, first read
-L<perl5141delta>, which describes differences between 5.14.0 and
-5.14.1.
-
-=head1 Core Enhancements
-
-No changes since 5.14.0.
-
-=head1 Security
-
-=head2 C<File::Glob::bsd_glob()> memory error with GLOB_ALTDIRFUNC (CVE-2011-2728).
-
-Calling C<File::Glob::bsd_glob> with the unsupported flag GLOB_ALTDIRFUNC would
-cause an access violation / segfault. A Perl program that accepts a flags value from
-an external source could expose itself to denial of service or arbitrary code
-execution attacks. There are no known exploits in the wild. The problem has been
-corrected by explicitly disabling all unsupported flags and setting unused function
-pointers to null. Bug reported by Clément Lecigne.
-
-=head2 C<Encode> decode_xs n-byte heap-overflow (CVE-2011-2939)
-
-A bug in C<Encode> could, on certain inputs, cause the heap to overflow.
-This problem has been corrected. Bug reported by Robert Zacek.
-
-=head1 Incompatible Changes
-
-There are no changes intentionally incompatible with 5.14.0. If any
-exist, they are bugs and reports are welcome.
-
-=head1 Deprecations
-
-There have been no deprecations since 5.14.0.
-
-=head1 Modules and Pragmata
-
-=head2 New Modules and Pragmata
-
-None
-
-=head2 Updated Modules and Pragmata
-
-=over 4
-
-=item *
-
-L<CPAN> has been upgraded from version 1.9600 to version 1.9600_01.
-
-L<CPAN::Distribution> has been upgraded from version 1.9602 to 1.9602_01.
-
-Backported bugfixes from CPAN version 1.9800. Ensures proper
-detection of C<configure_requires> prerequisites from CPAN Meta files
-in the case where C<dynamic_config> is true. [rt.cpan.org #68835]
-
-Also ensures that C<configure_requires> is only checked in META files,
-not MYMETA files, so protect against MYMETA generation that drops
-C<configure_requires>.
-
-=item *
-
-L<Encode> has been upgraded from version 2.42 to 2.42_01.
-
-See L</Security>.
-
-=item *
-
-L<File::Glob> has been upgraded from version 1.12 to version 1.13.
-
-See L</Security>.
-
-=item *
-
-L<PerlIO::scalar> has been upgraded from version 0.11 to 0.11_01.
-
-It fixes a problem with C<< open my $fh, ">", \$scalar >> not working if
-C<$scalar> is a copy-on-write scalar.
-
-=back
-
-=head2 Removed Modules and Pragmata
-
-None
-
-=head1 Platform Support
-
-=head2 New Platforms
-
-None
-
-=head2 Discontinued Platforms
-
-None
-
-=head2 Platform-Specific Notes
-
-=over 4
-
-=item HP-UX PA-RISC/64 now supports gcc-4.x
-
-A fix to correct the socketsize now makes the test suite pass on HP-UX
-PA-RISC for 64bitall builds.
-
-=item Building on OS X 10.7 Lion and Xcode 4 works again
-
-The build system has been updated to work with the build tools under Mac OS X
-10.7.
-
-=back
-
-=head1 Bug Fixes
-
-=over 4
-
-=item *
-
-In @INC filters (subroutines returned by subroutines in @INC), $_ used to
-misbehave: If returned from a subroutine, it would not be copied, but the
-variable itself would be returned; and freeing $_ (e.g., with C<undef *_>)
-would cause perl to crash. This has been fixed [perl #91880].
-
-=item *
-
-Perl 5.10.0 introduced some faulty logic that made "U*" in the middle of
-a pack template equivalent to "U0" if the input string was empty. This has
-been fixed [perl #90160].
-
-=item *
-
-C<caller> no longer leaks memory when called from the DB package if
-C<@DB::args> was assigned to after the first call to C<caller>. L<Carp>
-was triggering this bug [perl #97010].
-
-=item *
-
-C<utf8::decode> had a nasty bug that would modify copy-on-write scalars'
-string buffers in place (i.e., skipping the copy). This could result in
-hashes having two elements with the same key [perl #91834].
-
-=item *
-
-Localising a tied variable used to make it read-only if it contained a
-copy-on-write string.
-
-=item *
-
-Elements of restricted hashes (see the L<fields> pragma) containing
-copy-on-write values couldn't be deleted, nor could such hashes be cleared
-(C<%hash = ()>).
-
-=item *
-
-Locking a hash element that is a glob copy no longer causes subsequent
-assignment to it to corrupt the glob.
-
-=item *
-
-A panic involving the combination of the regular expression modifiers
-C</aa> introduced in 5.14.0 and the C<\b> escape sequence has been
-fixed [perl #95964].
-
-=back
-
-=head1 Known Problems
-
-This is a list of some significant unfixed bugs, which are regressions
-from 5.12.0.
-
-=over 4
-
-=item *
-
-C<PERL_GLOBAL_STRUCT> is broken.
-
-Since perl 5.14.0, building with C<-DPERL_GLOBAL_STRUCT> hasn't been
-possible. This means that perl currently doesn't work on any platforms that
-require it to be built this way, including Symbian.
-
-While C<PERL_GLOBAL_STRUCT> now works again on recent development versions of
-perl, it actually working on Symbian again hasn't been verified.
-
-We'd be very interested in hearing from anyone working with Perl on Symbian.
-
-=back
-
-=head1 Acknowledgements
-
-Perl 5.14.2 represents approximately three months of development since
-Perl 5.14.1 and contains approximately 1200 lines of changes
-across 61 files from 9 authors.
-
-Perl continues to flourish into its third decade thanks to a vibrant
-community of users and developers. The following people are known to
-have contributed the improvements that became Perl 5.14.2:
-
-Craig A. Berry, David Golden, Father Chrysostomos, Florian Ragwitz, H.Merijn
-Brand, Karl Williamson, Nicholas Clark, Pau Amma and Ricardo Signes.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://rt.perl.org/perlbug/ . There may also be
-information at http://www.perl.org/ , the Perl Home Page.
-
-If you believe you have an unreported bug, please run the L<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team.
-
-If the bug you are reporting has security implications, which make it
-inappropriate to send to a publicly archived mailing list, then please send
-it to perl5-security-report@perl.org. This points to a closed subscription
-unarchived mailing list, which includes all the core committers, who be able
-to help assess the impact of issues, figure out a resolution, and help
-co-ordinate the release of patches to mitigate or fix the problem across all
-platforms on which Perl is supported. Please only use this address for
-security issues in the Perl core, not for modules independently
-distributed on CPAN.
-
-=head1 SEE ALSO
-
-The F<Changes> file for an explanation of how to view exhaustive details
-on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl5143delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5143delta.pod
deleted file mode 100644
index 093b6272dcb..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl5143delta.pod
+++ /dev/null
@@ -1,291 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perl5143delta - what is new for perl v5.14.3
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.14.2 release and
-the 5.14.3 release.
-
-If you are upgrading from an earlier release such as 5.12.0, first read
-L<perl5140delta>, which describes differences between 5.12.0 and
-5.14.0.
-
-=head1 Core Enhancements
-
-No changes since 5.14.0.
-
-=head1 Security
-
-=head2 C<Digest> unsafe use of eval (CVE-2011-3597)
-
-The C<Digest-E<gt>new()> function did not properly sanitize input before
-using it in an eval() call, which could lead to the injection of arbitrary
-Perl code.
-
-In order to exploit this flaw, the attacker would need to be able to set
-the algorithm name used, or be able to execute arbitrary Perl code already.
-
-This problem has been fixed.
-
-=head2 Heap buffer overrun in 'x' string repeat operator (CVE-2012-5195)
-
-Poorly written perl code that allows an attacker to specify the count to
-perl's 'x' string repeat operator can already cause a memory exhaustion
-denial-of-service attack. A flaw in versions of perl before 5.15.5 can
-escalate that into a heap buffer overrun; coupled with versions of glibc
-before 2.16, it possibly allows the execution of arbitrary code.
-
-This problem has been fixed.
-
-=head1 Incompatible Changes
-
-There are no changes intentionally incompatible with 5.14.0. If any
-exist, they are bugs and reports are welcome.
-
-=head1 Deprecations
-
-There have been no deprecations since 5.14.0.
-
-=head1 Modules and Pragmata
-
-=head2 New Modules and Pragmata
-
-None
-
-=head2 Updated Modules and Pragmata
-
-=over 4
-
-=item *
-
-L<PerlIO::scalar> was updated to fix a bug in which opening a filehandle to
-a glob copy caused assertion failures (under debugging) or hangs or other
-erratic behaviour without debugging.
-
-=item *
-
-L<ODBM_File> and L<NDBM_File> were updated to allow building on GNU/Hurd.
-
-=item *
-
-L<IPC::Open3> has been updated to fix a regression introduced in perl
-5.12, which broke C<IPC::Open3::open3($in, $out, $err, '-')>.
-[perl #95748]
-
-=item *
-
-L<Digest> has been upgraded from version 1.16 to 1.16_01.
-
-See L</Security>.
-
-=item *
-
-L<Module::CoreList> has been updated to version 2.49_04 to add data for
-this release.
-
-=back
-
-=head2 Removed Modules and Pragmata
-
-None
-
-=head1 Documentation
-
-=head2 New Documentation
-
-None
-
-=head2 Changes to Existing Documentation
-
-=head3 L<perlcheat>
-
-=over 4
-
-=item *
-
-L<perlcheat> was updated to 5.14.
-
-=back
-
-=head1 Configuration and Compilation
-
-=over 4
-
-=item *
-
-h2ph was updated to search correctly gcc include directories on platforms
-such as Debian with multi-architecture support.
-
-=item *
-
-In Configure, the test for procselfexe was refactored into a loop.
-
-=back
-
-=head1 Platform Support
-
-=head2 New Platforms
-
-None
-
-=head2 Discontinued Platforms
-
-None
-
-=head2 Platform-Specific Notes
-
-=over 4
-
-=item FreeBSD
-
-The FreeBSD hints file was corrected to be compatible with FreeBSD 10.0.
-
-=item Solaris and NetBSD
-
-Configure was updated for "procselfexe" support on Solaris and NetBSD.
-
-=item HP-UX
-
-README.hpux was updated to note the existence of a broken header in
-HP-UX 11.00.
-
-=item Linux
-
-libutil is no longer used when compiling on Linux platforms, which avoids
-warnings being emitted.
-
-The system gcc (rather than any other gcc which might be in the compiling
-user's path) is now used when searching for libraries such as C<-lm>.
-
-=item Mac OS X
-
-The locale tests were updated to reflect the behaviour of locales in
-Mountain Lion.
-
-=item GNU/Hurd
-
-Various build and test fixes were included for GNU/Hurd.
-
-LFS support was enabled in GNU/Hurd.
-
-=item NetBSD
-
-The NetBSD hints file was corrected to be compatible with NetBSD 6.*
-
-=back
-
-=head1 Bug Fixes
-
-=over 4
-
-=item *
-
-A regression has been fixed that was introduced in 5.14, in C</i>
-regular expression matching, in which a match improperly fails if the
-pattern is in UTF-8, the target string is not, and a Latin-1 character
-precedes a character in the string that should match the pattern. [perl
-#101710]
-
-=item *
-
-In case-insensitive regular expression pattern matching, no longer on
-UTF-8 encoded strings does the scan for the start of match only look at
-the first possible position. This caused matches such as
-C<"f\x{FB00}" =~ /ff/i> to fail.
-
-=item *
-
-The sitecustomize support was made relocatableinc aware, so that
--Dusesitecustomize and -Duserelocatableinc may be used together.
-
-=item *
-
-The smartmatch operator (C<~~>) was changed so that the right-hand side
-takes precedence during C<Any ~~ Object> operations.
-
-=item *
-
-A bug has been fixed in the tainting support, in which an C<index()>
-operation on a tainted constant would cause all other constants to become
-tainted. [perl #64804]
-
-=item *
-
-A regression has been fixed that was introduced in perl 5.12, whereby
-tainting errors were not correctly propagated through C<die()>.
-[perl #111654]
-
-=item *
-
-A regression has been fixed that was introduced in perl 5.14, in which
-C</[[:lower:]]/i> and C</[[:upper:]]/i> no longer matched the opposite case.
-[perl #101970]
-
-=back
-
-=head1 Acknowledgements
-
-Perl 5.14.3 represents approximately 12 months of development since Perl 5.14.2
-and contains approximately 2,300 lines of changes across 64 files from 22
-authors.
-
-Perl continues to flourish into its third decade thanks to a vibrant community
-of users and developers. The following people are known to have contributed the
-improvements that became Perl 5.14.3:
-
-Abigail, Andy Dougherty, Carl Hayter, Chris 'BinGOs' Williams, Dave Rolsky,
-David Mitchell, Dominic Hargreaves, Father Chrysostomos, Florian Ragwitz,
-H.Merijn Brand, Jilles Tjoelker, Karl Williamson, Leon Timmermans, Michael G
-Schwern, Nicholas Clark, Niko Tyni, Pino Toscano, Ricardo Signes, Salvador
-Fandiño, Samuel Thibault, Steve Hay, Tony Cook.
-
-The list above is almost certainly incomplete as it is automatically generated
-from version control history. In particular, it does not include the names of
-the (very much appreciated) contributors who reported issues to the Perl bug
-tracker.
-
-Many of the changes included in this version originated in the CPAN modules
-included in Perl's core. We're grateful to the entire CPAN community for
-helping Perl to flourish.
-
-For a more complete list of all of Perl's historical contributors, please see
-the F<AUTHORS> file in the Perl source distribution.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://rt.perl.org/perlbug/ . There may also be
-information at http://www.perl.org/ , the Perl Home Page.
-
-If you believe you have an unreported bug, please run the L<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team.
-
-If the bug you are reporting has security implications, which make it
-inappropriate to send to a publicly archived mailing list, then please send
-it to perl5-security-report@perl.org. This points to a closed subscription
-unarchived mailing list, which includes all the core committers, who be able
-to help assess the impact of issues, figure out a resolution, and help
-co-ordinate the release of patches to mitigate or fix the problem across all
-platforms on which Perl is supported. Please only use this address for
-security issues in the Perl core, not for modules independently
-distributed on CPAN.
-
-=head1 SEE ALSO
-
-The F<Changes> file for an explanation of how to view exhaustive details
-on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl5160delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5160delta.pod
deleted file mode 100644
index 9b67d17a243..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl5160delta.pod
+++ /dev/null
@@ -1,4314 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perl5160delta - what is new for perl v5.16.0
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.14.0 release and
-the 5.16.0 release.
-
-If you are upgrading from an earlier release such as 5.12.0, first read
-L<perl5140delta>, which describes differences between 5.12.0 and
-5.14.0.
-
-Some bug fixes in this release have been backported to later
-releases of 5.14.x. Those are indicated with the 5.14.x version in
-parentheses.
-
-=head1 Notice
-
-With the release of Perl 5.16.0, the 5.12.x series of releases is now out of
-its support period. There may be future 5.12.x releases, but only in the
-event of a critical security issue. Users of Perl 5.12 or earlier should
-consider upgrading to a more recent release of Perl.
-
-This policy is described in greater detail in
-L<perlpolicy|perlpolicy/MAINTENANCE AND SUPPORT>.
-
-=head1 Core Enhancements
-
-=head2 C<use I<VERSION>>
-
-As of this release, version declarations like C<use v5.16> now disable
-all features before enabling the new feature bundle. This means that
-the following holds true:
-
- use 5.016;
- # only 5.16 features enabled here
- use 5.014;
- # only 5.14 features enabled here (not 5.16)
-
-C<use v5.12> and higher continue to enable strict, but explicit C<use
-strict> and C<no strict> now override the version declaration, even
-when they come first:
-
- no strict;
- use 5.012;
- # no strict here
-
-There is a new ":default" feature bundle that represents the set of
-features enabled before any version declaration or C<use feature> has
-been seen. Version declarations below 5.10 now enable the ":default"
-feature set. This does not actually change the behavior of C<use
-v5.8>, because features added to the ":default" set are those that were
-traditionally enabled by default, before they could be turned off.
-
-C<< no feature >> now resets to the default feature set. To disable all
-features (which is likely to be a pretty special-purpose request, since
-it presumably won't match any named set of semantics) you can now
-write C<< no feature ':all' >>.
-
-C<$[> is now disabled under C<use v5.16>. It is part of the default
-feature set and can be turned on or off explicitly with C<use feature
-'array_base'>.
-
-=head2 C<__SUB__>
-
-The new C<__SUB__> token, available under the C<current_sub> feature
-(see L<feature>) or C<use v5.16>, returns a reference to the current
-subroutine, making it easier to write recursive closures.
-
-=head2 New and Improved Built-ins
-
-=head3 More consistent C<eval>
-
-The C<eval> operator sometimes treats a string argument as a sequence of
-characters and sometimes as a sequence of bytes, depending on the
-internal encoding. The internal encoding is not supposed to make any
-difference, but there is code that relies on this inconsistency.
-
-The new C<unicode_eval> and C<evalbytes> features (enabled under C<use
-5.16.0>) resolve this. The C<unicode_eval> feature causes C<eval
-$string> to treat the string always as Unicode. The C<evalbytes>
-features provides a function, itself called C<evalbytes>, which
-evaluates its argument always as a string of bytes.
-
-These features also fix oddities with source filters leaking to outer
-dynamic scopes.
-
-See L<feature> for more detail.
-
-=head3 C<substr> lvalue revamp
-
-=for comment Does this belong here, or under Incompatible Changes?
-
-When C<substr> is called in lvalue or potential lvalue context with two
-or three arguments, a special lvalue scalar is returned that modifies
-the original string (the first argument) when assigned to.
-
-Previously, the offsets (the second and third arguments) passed to
-C<substr> would be converted immediately to match the string, negative
-offsets being translated to positive and offsets beyond the end of the
-string being truncated.
-
-Now, the offsets are recorded without modification in the special
-lvalue scalar that is returned, and the original string is not even
-looked at by C<substr> itself, but only when the returned lvalue is
-read or modified.
-
-These changes result in an incompatible change:
-
-If the original string changes length after the call to C<substr> but
-before assignment to its return value, negative offsets will remember
-their position from the end of the string, affecting code like this:
-
- my $string = "string";
- my $lvalue = \substr $string, -4, 2;
- print $$lvalue, "\n"; # prints "ri"
- $string = "bailing twine";
- print $$lvalue, "\n"; # prints "wi"; used to print "il"
-
-The same thing happens with an omitted third argument. The returned
-lvalue will always extend to the end of the string, even if the string
-becomes longer.
-
-Since this change also allowed many bugs to be fixed (see
-L</The C<substr> operator>), and since the behavior
-of negative offsets has never been specified, the
-change was deemed acceptable.
-
-=head3 Return value of C<tied>
-
-The value returned by C<tied> on a tied variable is now the actual
-scalar that holds the object to which the variable is tied. This
-lets ties be weakened with C<Scalar::Util::weaken(tied
-$tied_variable)>.
-
-=head2 Unicode Support
-
-=head3 Supports (I<almost>) Unicode 6.1
-
-Besides the addition of whole new scripts, and new characters in
-existing scripts, this new version of Unicode, as always, makes some
-changes to existing characters. One change that may trip up some
-applications is that the General Category of two characters in the
-Latin-1 range, PILCROW SIGN and SECTION SIGN, has been changed from
-Other_Symbol to Other_Punctuation. The same change has been made for
-a character in each of Tibetan, Ethiopic, and Aegean.
-The code points U+3248..U+324F (CIRCLED NUMBER TEN ON BLACK SQUARE
-through CIRCLED NUMBER EIGHTY ON BLACK SQUARE) have had their General
-Category changed from Other_Symbol to Other_Numeric. The Line Break
-property has changes for Hebrew and Japanese; and because of
-other changes in 6.1, the Perl regular expression construct C<\X> now
-works differently for some characters in Thai and Lao.
-
-New aliases (synonyms) have been defined for many property values;
-these, along with the previously existing ones, are all cross-indexed in
-L<perluniprops>.
-
-The return value of C<charnames::viacode()> is affected by other
-changes:
-
- Code point Old Name New Name
- U+000A LINE FEED (LF) LINE FEED
- U+000C FORM FEED (FF) FORM FEED
- U+000D CARRIAGE RETURN (CR) CARRIAGE RETURN
- U+0085 NEXT LINE (NEL) NEXT LINE
- U+008E SINGLE-SHIFT 2 SINGLE-SHIFT-2
- U+008F SINGLE-SHIFT 3 SINGLE-SHIFT-3
- U+0091 PRIVATE USE 1 PRIVATE USE-1
- U+0092 PRIVATE USE 2 PRIVATE USE-2
- U+2118 SCRIPT CAPITAL P WEIERSTRASS ELLIPTIC FUNCTION
-
-Perl will accept any of these names as input, but
-C<charnames::viacode()> now returns the new name of each pair. The
-change for U+2118 is considered by Unicode to be a correction, that is
-the original name was a mistake (but again, it will remain forever valid
-to use it to refer to U+2118). But most of these changes are the
-fallout of the mistake Unicode 6.0 made in naming a character used in
-Japanese cell phones to be "BELL", which conflicts with the longstanding
-industry use of (and Unicode's recommendation to use) that name
-to mean the ASCII control character at U+0007. Therefore, that name
-has been deprecated in Perl since v5.14, and any use of it will raise a
-warning message (unless turned off). The name "ALERT" is now the
-preferred name for this code point, with "BEL" an acceptable short
-form. The name for the new cell phone character, at code point U+1F514,
-remains undefined in this version of Perl (hence we don't
-implement quite all of Unicode 6.1), but starting in v5.18, BELL will mean
-this character, and not U+0007.
-
-Unicode has taken steps to make sure that this sort of mistake does not
-happen again. The Standard now includes all generally accepted
-names and abbreviations for control characters, whereas previously it
-didn't (though there were recommended names for most of them, which Perl
-used). This means that most of those recommended names are now
-officially in the Standard. Unicode did not recommend names for the
-four code points listed above between U+008E and U+008F, and in
-standardizing them Unicode subtly changed the names that Perl had
-previously given them, by replacing the final blank in each name by a
-hyphen. Unicode also officially accepts names that Perl had deprecated,
-such as FILE SEPARATOR. Now the only deprecated name is BELL.
-Finally, Perl now uses the new official names instead of the old
-(now considered obsolete) names for the first four code points in the
-list above (the ones which have the parentheses in them).
-
-Now that the names have been placed in the Unicode standard, these kinds
-of changes should not happen again, though corrections, such as to
-U+2118, are still possible.
-
-Unicode also added some name abbreviations, which Perl now accepts:
-SP for SPACE;
-TAB for CHARACTER TABULATION;
-NEW LINE, END OF LINE, NL, and EOL for LINE FEED;
-LOCKING-SHIFT ONE for SHIFT OUT;
-LOCKING-SHIFT ZERO for SHIFT IN;
-and ZWNBSP for ZERO WIDTH NO-BREAK SPACE.
-
-More details on this version of Unicode are provided in
-L<http://www.unicode.org/versions/Unicode6.1.0/>.
-
-=head3 C<use charnames> is no longer needed for C<\N{I<name>}>
-
-When C<\N{I<name>}> is encountered, the C<charnames> module is now
-automatically loaded when needed as if the C<:full> and C<:short>
-options had been specified. See L<charnames> for more information.
-
-=head3 C<\N{...}> can now have Unicode loose name matching
-
-This is described in the C<charnames> item in
-L</Updated Modules and Pragmata> below.
-
-=head3 Unicode Symbol Names
-
-Perl now has proper support for Unicode in symbol names. It used to be
-that C<*{$foo}> would ignore the internal UTF8 flag and use the bytes of
-the underlying representation to look up the symbol. That meant that
-C<*{"\x{100}"}> and C<*{"\xc4\x80"}> would return the same thing. All
-these parts of Perl have been fixed to account for Unicode:
-
-=over
-
-=item *
-
-Method names (including those passed to C<use overload>)
-
-=item *
-
-Typeglob names (including names of variables, subroutines, and filehandles)
-
-=item *
-
-Package names
-
-=item *
-
-C<goto>
-
-=item *
-
-Symbolic dereferencing
-
-=item *
-
-Second argument to C<bless()> and C<tie()>
-
-=item *
-
-Return value of C<ref()>
-
-=item *
-
-Subroutine prototypes
-
-=item *
-
-Attributes
-
-=item *
-
-Various warnings and error messages that mention variable names or values,
-methods, etc.
-
-=back
-
-In addition, a parsing bug has been fixed that prevented C<*{é}> from
-implicitly quoting the name, but instead interpreted it as C<*{+é}>, which
-would cause a strict violation.
-
-C<*{"*a::b"}> automatically strips off the * if it is followed by an ASCII
-letter. That has been extended to all Unicode identifier characters.
-
-One-character non-ASCII non-punctuation variables (like C<$é>) are now
-subject to "Used only once" warnings. They used to be exempt, as they
-were treated as punctuation variables.
-
-Also, single-character Unicode punctuation variables (like C<$‰>) are now
-supported [perl #69032].
-
-=head3 Improved ability to mix locales and Unicode, including UTF-8 locales
-
-An optional parameter has been added to C<use locale>
-
- use locale ':not_characters';
-
-which tells Perl to use all but the C<LC_CTYPE> and C<LC_COLLATE>
-portions of the current locale. Instead, the character set is assumed
-to be Unicode. This lets locales and Unicode be seamlessly mixed,
-including the increasingly frequent UTF-8 locales. When using this
-hybrid form of locales, the C<:locale> layer to the L<open> pragma can
-be used to interface with the file system, and there are CPAN modules
-available for ARGV and environment variable conversions.
-
-Full details are in L<perllocale>.
-
-=head3 New function C<fc> and corresponding escape sequence C<\F> for Unicode foldcase
-
-Unicode foldcase is an extension to lowercase that gives better results
-when comparing two strings case-insensitively. It has long been used
-internally in regular expression C</i> matching. Now it is available
-explicitly through the new C<fc> function call (enabled by
-S<C<"use feature 'fc'">>, or C<use v5.16>, or explicitly callable via
-C<CORE::fc>) or through the new C<\F> sequence in double-quotish
-strings.
-
-Full details are in L<perlfunc/fc>.
-
-=head3 The Unicode C<Script_Extensions> property is now supported.
-
-New in Unicode 6.0, this is an improved C<Script> property. Details
-are in L<perlunicode/Scripts>.
-
-=head2 XS Changes
-
-=head3 Improved typemaps for Some Builtin Types
-
-Most XS authors will know there is a longstanding bug in the
-OUTPUT typemap for T_AVREF (C<AV*>), T_HVREF (C<HV*>), T_CVREF (C<CV*>),
-and T_SVREF (C<SVREF> or C<\$foo>) that requires manually decrementing
-the reference count of the return value instead of the typemap taking
-care of this. For backwards-compatibility, this cannot be changed in the
-default typemaps. But we now provide additional typemaps
-C<T_AVREF_REFCOUNT_FIXED>, etc. that do not exhibit this bug. Using
-them in your extension is as simple as having one line in your
-C<TYPEMAP> section:
-
- HV* T_HVREF_REFCOUNT_FIXED
-
-=head3 C<is_utf8_char()>
-
-The XS-callable function C<is_utf8_char()>, when presented with
-malformed UTF-8 input, can read up to 12 bytes beyond the end of the
-string. This cannot be fixed without changing its API, and so its
-use is now deprecated. Use C<is_utf8_char_buf()> (described just below)
-instead.
-
-=head3 Added C<is_utf8_char_buf()>
-
-This function is designed to replace the deprecated L</is_utf8_char()>
-function. It includes an extra parameter to make sure it doesn't read
-past the end of the input buffer.
-
-=head3 Other C<is_utf8_foo()> functions, as well as C<utf8_to_foo()>, etc.
-
-Most other XS-callable functions that take UTF-8 encoded input
-implicitly assume that the UTF-8 is valid (not malformed) with respect to
-buffer length. Do not do things such as change a character's case or
-see if it is alphanumeric without first being sure that it is valid
-UTF-8. This can be safely done for a whole string by using one of the
-functions C<is_utf8_string()>, C<is_utf8_string_loc()>, and
-C<is_utf8_string_loclen()>.
-
-=head3 New Pad API
-
-Many new functions have been added to the API for manipulating lexical
-pads. See L<perlapi/Pad Data Structures> for more information.
-
-=head2 Changes to Special Variables
-
-=head3 C<$$> can be assigned to
-
-C<$$> was made read-only in Perl 5.8.0. But only sometimes: C<local $$>
-would make it writable again. Some CPAN modules were using C<local $$> or
-XS code to bypass the read-only check, so there is no reason to keep C<$$>
-read-only. (This change also allowed a bug to be fixed while maintaining
-backward compatibility.)
-
-=head3 C<$^X> converted to an absolute path on FreeBSD, OS X and Solaris
-
-C<$^X> is now converted to an absolute path on OS X, FreeBSD (without
-needing F</proc> mounted) and Solaris 10 and 11. This augments the
-previous approach of using F</proc> on Linux, FreeBSD, and NetBSD
-(in all cases, where mounted).
-
-This makes relocatable perl installations more useful on these platforms.
-(See "Relocatable @INC" in F<INSTALL>)
-
-=head2 Debugger Changes
-
-=head3 Features inside the debugger
-
-The current Perl's L<feature> bundle is now enabled for commands entered
-in the interactive debugger.
-
-=head3 New option for the debugger's B<t> command
-
-The B<t> command in the debugger, which toggles tracing mode, now
-accepts a numeric argument that determines how many levels of subroutine
-calls to trace.
-
-=head3 C<enable> and C<disable>
-
-The debugger now has C<disable> and C<enable> commands for disabling
-existing breakpoints and re-enabling them. See L<perldebug>.
-
-=head3 Breakpoints with file names
-
-The debugger's "b" command for setting breakpoints now lets a line
-number be prefixed with a file name. See
-L<perldebug/"b [file]:[line] [condition]">.
-
-=head2 The C<CORE> Namespace
-
-=head3 The C<CORE::> prefix
-
-The C<CORE::> prefix can now be used on keywords enabled by
-L<feature.pm|feature>, even outside the scope of C<use feature>.
-
-=head3 Subroutines in the C<CORE> namespace
-
-Many Perl keywords are now available as subroutines in the CORE namespace.
-This lets them be aliased:
-
- BEGIN { *entangle = \&CORE::tie }
- entangle $variable, $package, @args;
-
-And for prototypes to be bypassed:
-
- sub mytie(\[%$*@]$@) {
- my ($ref, $pack, @args) = @_;
- ... do something ...
- goto &CORE::tie;
- }
-
-Some of these cannot be called through references or via C<&foo> syntax,
-but must be called as barewords.
-
-See L<CORE> for details.
-
-=head2 Other Changes
-
-=head3 Anonymous handles
-
-Automatically generated file handles are now named __ANONIO__ when the
-variable name cannot be determined, rather than $__ANONIO__.
-
-=head3 Autoloaded sort Subroutines
-
-Custom sort subroutines can now be autoloaded [perl #30661]:
-
- sub AUTOLOAD { ... }
- @sorted = sort foo @list; # uses AUTOLOAD
-
-=head3 C<continue> no longer requires the "switch" feature
-
-The C<continue> keyword has two meanings. It can introduce a C<continue>
-block after a loop, or it can exit the current C<when> block. Up to now,
-the latter meaning was valid only with the "switch" feature enabled, and
-was a syntax error otherwise. Since the main purpose of feature.pm is to
-avoid conflicts with user-defined subroutines, there is no reason for
-C<continue> to depend on it.
-
-=head3 DTrace probes for interpreter phase change
-
-The C<phase-change> probes will fire when the interpreter's phase
-changes, which tracks the C<${^GLOBAL_PHASE}> variable. C<arg0> is
-the new phase name; C<arg1> is the old one. This is useful
-for limiting your instrumentation to one or more of: compile time,
-run time, or destruct time.
-
-=head3 C<__FILE__()> Syntax
-
-The C<__FILE__>, C<__LINE__> and C<__PACKAGE__> tokens can now be written
-with an empty pair of parentheses after them. This makes them parse the
-same way as C<time>, C<fork> and other built-in functions.
-
-=head3 The C<\$> prototype accepts any scalar lvalue
-
-The C<\$> and C<\[$]> subroutine prototypes now accept any scalar lvalue
-argument. Previously they accepted only scalars beginning with C<$> and
-hash and array elements. This change makes them consistent with the way
-the built-in C<read> and C<recv> functions (among others) parse their
-arguments. This means that one can override the built-in functions with
-custom subroutines that parse their arguments the same way.
-
-=head3 C<_> in subroutine prototypes
-
-The C<_> character in subroutine prototypes is now allowed before C<@> or
-C<%>.
-
-=head1 Security
-
-=head2 Use C<is_utf8_char_buf()> and not C<is_utf8_char()>
-
-The latter function is now deprecated because its API is insufficient to
-guarantee that it doesn't read (up to 12 bytes in the worst case) beyond
-the end of its input string. See
-L<is_utf8_char_buf()|/Added is_utf8_char_buf()>.
-
-=head2 Malformed UTF-8 input could cause attempts to read beyond the end of the buffer
-
-Two new XS-accessible functions, C<utf8_to_uvchr_buf()> and
-C<utf8_to_uvuni_buf()> are now available to prevent this, and the Perl
-core has been converted to use them.
-See L</Internal Changes>.
-
-=head2 C<File::Glob::bsd_glob()> memory error with GLOB_ALTDIRFUNC (CVE-2011-2728).
-
-Calling C<File::Glob::bsd_glob> with the unsupported flag
-GLOB_ALTDIRFUNC would cause an access violation / segfault. A Perl
-program that accepts a flags value from an external source could expose
-itself to denial of service or arbitrary code execution attacks. There
-are no known exploits in the wild. The problem has been corrected by
-explicitly disabling all unsupported flags and setting unused function
-pointers to null. Bug reported by Clément Lecigne. (5.14.2)
-
-=head2 Privileges are now set correctly when assigning to C<$(>
-
-A hypothetical bug (probably unexploitable in practice) because the
-incorrect setting of the effective group ID while setting C<$(> has been
-fixed. The bug would have affected only systems that have C<setresgid()>
-but not C<setregid()>, but no such systems are known to exist.
-
-=head1 Deprecations
-
-=head2 Don't read the Unicode data base files in F<lib/unicore>
-
-It is now deprecated to directly read the Unicode data base files.
-These are stored in the F<lib/unicore> directory. Instead, you should
-use the new functions in L<Unicode::UCD>. These provide a stable API,
-and give complete information.
-
-Perl may at some point in the future change or remove these files. The
-file which applications were most likely to have used is
-F<lib/unicore/ToDigit.pl>. L<Unicode::UCD/prop_invmap()> can be used to
-get at its data instead.
-
-=head2 XS functions C<is_utf8_char()>, C<utf8_to_uvchr()> and
-C<utf8_to_uvuni()>
-
-This function is deprecated because it could read beyond the end of the
-input string. Use the new L<is_utf8_char_buf()|/Added is_utf8_char_buf()>,
-C<utf8_to_uvchr_buf()> and C<utf8_to_uvuni_buf()> instead.
-
-=head1 Future Deprecations
-
-This section serves as a notice of features that are I<likely> to be
-removed or L<deprecated|perlpolicy/deprecated> in the next release of
-perl (5.18.0). If your code depends on these features, you should
-contact the Perl 5 Porters via the L<mailing
-list|http://lists.perl.org/list/perl5-porters.html> or L<perlbug> to
-explain your use case and inform the deprecation process.
-
-=head2 Core Modules
-
-These modules may be marked as deprecated I<from the core>. This only
-means that they will no longer be installed by default with the core
-distribution, but will remain available on the CPAN.
-
-=over
-
-=item *
-
-CPANPLUS
-
-=item *
-
-Filter::Simple
-
-=item *
-
-PerlIO::mmap
-
-=item *
-
-Pod::LaTeX
-
-=item *
-
-Pod::Parser
-
-=item *
-
-SelfLoader
-
-=item *
-
-Text::Soundex
-
-=item *
-
-Thread.pm
-
-=back
-
-=head2 Platforms with no supporting programmers:
-
-These platforms will probably have their
-special build support removed during the
-5.17.0 development series.
-
-=over
-
-=item *
-
-BeOS
-
-=item *
-
-djgpp
-
-=item *
-
-dgux
-
-=item *
-
-EPOC
-
-=item *
-
-MPE/iX
-
-=item *
-
-Rhapsody
-
-=item *
-
-UTS
-
-=item *
-
-VM/ESA
-
-=back
-
-=head2 Other Future Deprecations
-
-=over
-
-=item *
-
-Swapping of $< and $>
-
-For more information about this future deprecation, see L<the relevant RT
-ticket|https://rt.perl.org/rt3/Ticket/Display.html?id=96212>.
-
-=item *
-
-sfio, stdio
-
-Perl supports being built without PerlIO proper, using a stdio or sfio
-wrapper instead. A perl build like this will not support IO layers and
-thus Unicode IO, making it rather handicapped.
-
-PerlIO supports a C<stdio> layer if stdio use is desired, and similarly a
-sfio layer could be produced.
-
-=item *
-
-Unescaped literal C<< "{" >> in regular expressions.
-
-Starting with v5.20, it is planned to require a literal C<"{"> to be
-escaped, for example by preceding it with a backslash. In v5.18, a
-deprecated warning message will be emitted for all such uses.
-This affects only patterns that are to match a literal C<"{">. Other
-uses of this character, such as part of a quantifier or sequence as in
-those below, are completely unaffected:
-
- /foo{3,5}/
- /\p{Alphabetic}/
- /\N{DIGIT ZERO}
-
-Removing this will permit extensions to Perl's pattern syntax and better
-error checking for existing syntax. See L<perlre/Quantifiers> for an
-example.
-
-=item *
-
-Revamping C<< "\Q" >> semantics in double-quotish strings when combined with other escapes.
-
-There are several bugs and inconsistencies involving combinations
-of C<\Q> and escapes like C<\x>, C<\L>, etc., within a C<\Q...\E> pair.
-These need to be fixed, and doing so will necessarily change current
-behavior. The changes have not yet been settled.
-
-=back
-
-=head1 Incompatible Changes
-
-=head2 Special blocks called in void context
-
-Special blocks (C<BEGIN>, C<CHECK>, C<INIT>, C<UNITCHECK>, C<END>) are now
-called in void context. This avoids wasteful copying of the result of the
-last statement [perl #108794].
-
-=head2 The C<overloading> pragma and regexp objects
-
-With C<no overloading>, regular expression objects returned by C<qr//> are
-now stringified as "Regexp=REGEXP(0xbe600d)" instead of the regular
-expression itself [perl #108780].
-
-=head2 Two XS typemap Entries removed
-
-Two presumably unused XS typemap entries have been removed from the
-core typemap: T_DATAUNIT and T_CALLBACK. If you are, against all odds,
-a user of these, please see the instructions on how to restore them
-in L<perlxstypemap>.
-
-=head2 Unicode 6.1 has incompatibilities with Unicode 6.0
-
-These are detailed in L</Supports (almost) Unicode 6.1> above.
-You can compile this version of Perl to use Unicode 6.0. See
-L<perlunicode/Hacking Perl to work on earlier Unicode versions (for very serious hackers only)>.
-
-=head2 Borland compiler
-
-All support for the Borland compiler has been dropped. The code had not
-worked for a long time anyway.
-
-=head2 Certain deprecated Unicode properties are no longer supported by default
-
-Perl should never have exposed certain Unicode properties that are used
-by Unicode internally and not meant to be publicly available. Use of
-these has generated deprecated warning messages since Perl 5.12. The
-removed properties are Other_Alphabetic,
-Other_Default_Ignorable_Code_Point, Other_Grapheme_Extend,
-Other_ID_Continue, Other_ID_Start, Other_Lowercase, Other_Math, and
-Other_Uppercase.
-
-Perl may be recompiled to include any or all of them; instructions are
-given in
-L<perluniprops/Unicode character properties that are NOT accepted by Perl>.
-
-=head2 Dereferencing IO thingies as typeglobs
-
-The C<*{...}> operator, when passed a reference to an IO thingy (as in
-C<*{*STDIN{IO}}>), creates a new typeglob containing just that IO object.
-Previously, it would stringify as an empty string, but some operators would
-treat it as undefined, producing an "uninitialized" warning.
-Now it stringifies as __ANONIO__ [perl #96326].
-
-=head2 User-defined case-changing operations
-
-This feature was deprecated in Perl 5.14, and has now been removed.
-The CPAN module L<Unicode::Casing> provides better functionality without
-the drawbacks that this feature had, as are detailed in the 5.14
-documentation:
-L<http://perldoc.perl.org/5.14.0/perlunicode.html#User-Defined-Case-Mappings-%28for-serious-hackers-only%29>
-
-=head2 XSUBs are now 'static'
-
-XSUB C functions are now 'static', that is, they are not visible from
-outside the compilation unit. Users can use the new C<XS_EXTERNAL(name)>
-and C<XS_INTERNAL(name)> macros to pick the desired linking behavior.
-The ordinary C<XS(name)> declaration for XSUBs will continue to declare
-non-'static' XSUBs for compatibility, but the XS compiler,
-L<ExtUtils::ParseXS> (C<xsubpp>) will emit 'static' XSUBs by default.
-L<ExtUtils::ParseXS>'s behavior can be reconfigured from XS using the
-C<EXPORT_XSUB_SYMBOLS> keyword. See L<perlxs> for details.
-
-=head2 Weakening read-only references
-
-Weakening read-only references is no longer permitted. It should never
-have worked anyway, and could sometimes result in crashes.
-
-=head2 Tying scalars that hold typeglobs
-
-Attempting to tie a scalar after a typeglob was assigned to it would
-instead tie the handle in the typeglob's IO slot. This meant that it was
-impossible to tie the scalar itself. Similar problems affected C<tied> and
-C<untie>: C<tied $scalar> would return false on a tied scalar if the last
-thing returned was a typeglob, and C<untie $scalar> on such a tied scalar
-would do nothing.
-
-We fixed this problem before Perl 5.14.0, but it caused problems with some
-CPAN modules, so we put in a deprecation cycle instead.
-
-Now the deprecation has been removed and this bug has been fixed. So
-C<tie $scalar> will always tie the scalar, not the handle it holds. To tie
-the handle, use C<tie *$scalar> (with an explicit asterisk). The same
-applies to C<tied *$scalar> and C<untie *$scalar>.
-
-=head2 IPC::Open3 no longer provides C<xfork()>, C<xclose_on_exec()>
-and C<xpipe_anon()>
-
-All three functions were private, undocumented, and unexported. They do
-not appear to be used by any code on CPAN. Two have been inlined and one
-deleted entirely.
-
-=head2 C<$$> no longer caches PID
-
-Previously, if one called fork(3) from C, Perl's
-notion of C<$$> could go out of sync with what getpid() returns. By always
-fetching the value of C<$$> via getpid(), this potential bug is eliminated.
-Code that depends on the caching behavior will break. As described in
-L<Core Enhancements|/C<$$> can be assigned to>,
-C<$$> is now writable, but it will be reset during a
-fork.
-
-=head2 C<$$> and C<getppid()> no longer emulate POSIX semantics under LinuxThreads
-
-The POSIX emulation of C<$$> and C<getppid()> under the obsolete
-LinuxThreads implementation has been removed.
-This only impacts users of Linux 2.4 and
-users of Debian GNU/kFreeBSD up to and including 6.0, not the vast
-majority of Linux installations that use NPTL threads.
-
-This means that C<getppid()>, like C<$$>, is now always guaranteed to
-return the OS's idea of the current state of the process, not perl's
-cached version of it.
-
-See the documentation for L<$$|perlvar/$$> for details.
-
-=head2 C<< $< >>, C<< $> >>, C<$(> and C<$)> are no longer cached
-
-Similarly to the changes to C<$$> and C<getppid()>, the internal
-caching of C<< $< >>, C<< $> >>, C<$(> and C<$)> has been removed.
-
-When we cached these values our idea of what they were would drift out
-of sync with reality if someone (e.g., someone embedding perl) called
-C<sete?[ug]id()> without updating C<PL_e?[ug]id>. Having to deal with
-this complexity wasn't worth it given how cheap the C<gete?[ug]id()>
-system call is.
-
-This change will break a handful of CPAN modules that use the XS-level
-C<PL_uid>, C<PL_gid>, C<PL_euid> or C<PL_egid> variables.
-
-The fix for those breakages is to use C<PerlProc_gete?[ug]id()> to
-retrieve them (e.g., C<PerlProc_getuid()>), and not to assign to
-C<PL_e?[ug]id> if you change the UID/GID/EUID/EGID. There is no longer
-any need to do so since perl will always retrieve the up-to-date
-version of those values from the OS.
-
-=head2 Which Non-ASCII characters get quoted by C<quotemeta> and C<\Q> has changed
-
-This is unlikely to result in a real problem, as Perl does not attach
-special meaning to any non-ASCII character, so it is currently
-irrelevant which are quoted or not. This change fixes bug [perl #77654] and
-brings Perl's behavior more into line with Unicode's recommendations.
-See L<perlfunc/quotemeta>.
-
-=head1 Performance Enhancements
-
-=over
-
-=item *
-
-Improved performance for Unicode properties in regular expressions
-
-=for comment Can this be compacted some? -- rjbs, 2012-02-20
-
-Matching a code point against a Unicode property is now done via a
-binary search instead of linear. This means for example that the worst
-case for a 1000 item property is 10 probes instead of 1000. This
-inefficiency has been compensated for in the past by permanently storing
-in a hash the results of a given probe plus the results for the adjacent
-64 code points, under the theory that near-by code points are likely to
-be searched for. A separate hash was used for each mention of a Unicode
-property in each regular expression. Thus, C<qr/\p{foo}abc\p{foo}/>
-would generate two hashes. Any probes in one instance would be unknown
-to the other, and the hashes could expand separately to be quite large
-if the regular expression were used on many different widely-separated
-code points.
-Now, however, there is just one hash shared by all instances of a given
-property. This means that if C<\p{foo}> is matched against "A" in one
-regular expression in a thread, the result will be known immediately to
-all regular expressions, and the relentless march of using up memory is
-slowed considerably.
-
-=item *
-
-Version declarations with the C<use> keyword (e.g., C<use 5.012>) are now
-faster, as they enable features without loading F<feature.pm>.
-
-=item *
-
-C<local $_> is faster now, as it no longer iterates through magic that it
-is not going to copy anyway.
-
-=item *
-
-Perl 5.12.0 sped up the destruction of objects whose classes define
-empty C<DESTROY> methods (to prevent autoloading), by simply not
-calling such empty methods. This release takes this optimization a
-step further, by not calling any C<DESTROY> method that begins with a
-C<return> statement. This can be useful for destructors that are only
-used for debugging:
-
- use constant DEBUG => 1;
- sub DESTROY { return unless DEBUG; ... }
-
-Constant-folding will reduce the first statement to C<return;> if DEBUG
-is set to 0, triggering this optimization.
-
-=item *
-
-Assigning to a variable that holds a typeglob or copy-on-write scalar
-is now much faster. Previously the typeglob would be stringified or
-the copy-on-write scalar would be copied before being clobbered.
-
-=item *
-
-Assignment to C<substr> in void context is now more than twice its
-previous speed. Instead of creating and returning a special lvalue
-scalar that is then assigned to, C<substr> modifies the original string
-itself.
-
-=item *
-
-C<substr> no longer calculates a value to return when called in void
-context.
-
-=item *
-
-Due to changes in L<File::Glob>, Perl's C<glob> function and its C<<
-<...> >> equivalent are now much faster. The splitting of the pattern
-into words has been rewritten in C, resulting in speed-ups of 20% for
-some cases.
-
-This does not affect C<glob> on VMS, as it does not use File::Glob.
-
-=item *
-
-The short-circuiting operators C<&&>, C<||>, and C<//>, when chained
-(such as C<$a || $b || $c>), are now considerably faster to short-circuit,
-due to reduced optree traversal.
-
-=item *
-
-The implementation of C<s///r> makes one fewer copy of the scalar's value.
-
-=item *
-
-Recursive calls to lvalue subroutines in lvalue scalar context use less
-memory.
-
-=back
-
-=head1 Modules and Pragmata
-
-=head2 Deprecated Modules
-
-=over
-
-=item L<Version::Requirements>
-
-Version::Requirements is now DEPRECATED, use L<CPAN::Meta::Requirements>,
-which is a drop-in replacement. It will be deleted from perl.git blead
-in v5.17.0.
-
-=back
-
-=head2 New Modules and Pragmata
-
-=over 4
-
-=item *
-
-L<arybase> -- this new module implements the C<$[> variable.
-
-=item *
-
-L<PerlIO::mmap> 0.010 has been added to the Perl core.
-
-The C<mmap> PerlIO layer is no longer implemented by perl itself, but has
-been moved out into the new L<PerlIO::mmap> module.
-
-=back
-
-=head2 Updated Modules and Pragmata
-
-This is only an overview of selected module updates. For a complete list of
-updates, run:
-
- $ corelist --diff 5.14.0 5.16.0
-
-You can substitute your favorite version in place of 5.14.0, too.
-
-=over 4
-
-=item *
-
-L<Archive::Extract> has been upgraded from version 0.48 to 0.58.
-
-Includes a fix for FreeBSD to only use C<unzip> if it is located in
-C</usr/local/bin>, as FreeBSD 9.0 will ship with a limited C<unzip> in
-C</usr/bin>.
-
-=item *
-
-L<Archive::Tar> has been upgraded from version 1.76 to 1.82.
-
-Adjustments to handle files >8gb (>0777777777777 octal) and a feature
-to return the MD5SUM of files in the archive.
-
-=item *
-
-L<base> has been upgraded from version 2.16 to 2.18.
-
-C<base> no longer sets a module's C<$VERSION> to "-1" when a module it
-loads does not define a C<$VERSION>. This change has been made because
-"-1" is not a valid version number under the new "lax" criteria used
-internally by C<UNIVERSAL::VERSION>. (See L<version> for more on "lax"
-version criteria.)
-
-C<base> no longer internally skips loading modules it has already loaded
-and instead relies on C<require> to inspect C<%INC>. This fixes a bug
-when C<base> is used with code that clear C<%INC> to force a module to
-be reloaded.
-
-=item *
-
-L<Carp> has been upgraded from version 1.20 to 1.26.
-
-It now includes last read filehandle info and puts a dot after the file
-and line number, just like errors from C<die> [perl #106538].
-
-=item *
-
-L<charnames> has been updated from version 1.18 to 1.30.
-
-C<charnames> can now be invoked with a new option, C<:loose>,
-which is like the existing C<:full> option, but enables Unicode loose
-name matching. Details are in L<charnames/LOOSE MATCHES>.
-
-=item *
-
-L<B::Deparse> has been upgraded from version 1.03 to 1.14. This fixes
-numerous deparsing bugs.
-
-=item *
-
-L<CGI> has been upgraded from version 3.52 to 3.59.
-
-It uses the public and documented FCGI.pm API in CGI::Fast. CGI::Fast was
-using an FCGI API that was deprecated and removed from documentation
-more than ten years ago. Usage of this deprecated API with FCGI E<gt>=
-0.70 or FCGI E<lt>= 0.73 introduces a security issue.
-L<https://rt.cpan.org/Public/Bug/Display.html?id=68380>
-L<http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2011-2766>
-
-Things that may break your code:
-
-C<url()> was fixed to return C<PATH_INFO> when it is explicitly requested
-with either the C<path=E<gt>1> or C<path_info=E<gt>1> flag.
-
-If your code is running under mod_rewrite (or compatible) and you are
-calling C<self_url()> or you are calling C<url()> and passing
-C<path_info=E<gt>1>, these methods will actually be returning
-C<PATH_INFO> now, as you have explicitly requested or C<self_url()>
-has requested on your behalf.
-
-The C<PATH_INFO> has been omitted in such URLs since the issue was
-introduced in the 3.12 release in December, 2005.
-
-This bug is so old your application may have come to depend on it or
-workaround it. Check for application before upgrading to this release.
-
-Examples of affected method calls:
-
- $q->url(-absolute => 1, -query => 1, -path_info => 1);
- $q->url(-path=>1);
- $q->url(-full=>1,-path=>1);
- $q->url(-rewrite=>1,-path=>1);
- $q->self_url();
-
-We no longer read from STDIN when the Content-Length is not set,
-preventing requests with no Content-Length from sometimes freezing.
-This is consistent with the CGI RFC 3875, and is also consistent with
-CGI::Simple. However, the old behavior may have been expected by some
-command-line uses of CGI.pm.
-
-In addition, the DELETE HTTP verb is now supported.
-
-=item *
-
-L<Compress::Zlib> has been upgraded from version 2.035 to 2.048.
-
-IO::Compress::Zip and IO::Uncompress::Unzip now have support for LZMA
-(method 14). There is a fix for a CRC issue in IO::Compress::Unzip and
-it supports Streamed Stored context now. And fixed a Zip64 issue in
-IO::Compress::Zip when the content size was exactly 0xFFFFFFFF.
-
-=item *
-
-L<Digest::SHA> has been upgraded from version 5.61 to 5.71.
-
-Added BITS mode to the addfile method and shasum. This makes
-partial-byte inputs possible via files/STDIN and lets shasum check
-all 8074 NIST Msg vectors, where previously special programming was
-required to do this.
-
-=item *
-
-L<Encode> has been upgraded from version 2.42 to 2.44.
-
-Missing aliases added, a deep recursion error fixed and various
-documentation updates.
-
-Addressed 'decode_xs n-byte heap-overflow' security bug in Unicode.xs
-(CVE-2011-2939). (5.14.2)
-
-=item *
-
-L<ExtUtils::CBuilder> updated from version 0.280203 to 0.280206.
-
-The new version appends CFLAGS and LDFLAGS to their Config.pm
-counterparts.
-
-=item *
-
-L<ExtUtils::ParseXS> has been upgraded from version 2.2210 to 3.16.
-
-Much of L<ExtUtils::ParseXS>, the module behind the XS compiler C<xsubpp>,
-was rewritten and cleaned up. It has been made somewhat more extensible
-and now finally uses strictures.
-
-The typemap logic has been moved into a separate module,
-L<ExtUtils::Typemaps>. See L</New Modules and Pragmata>, above.
-
-For a complete set of changes, please see the ExtUtils::ParseXS
-changelog, available on the CPAN.
-
-=item *
-
-L<File::Glob> has been upgraded from version 1.12 to 1.17.
-
-On Windows, tilde (~) expansion now checks the C<USERPROFILE> environment
-variable, after checking C<HOME>.
-
-It has a new C<:bsd_glob> export tag, intended to replace C<:glob>. Like
-C<:glob> it overrides C<glob> with a function that does not split the glob
-pattern into words, but, unlike C<:glob>, it iterates properly in scalar
-context, instead of returning the last file.
-
-There are other changes affecting Perl's own C<glob> operator (which uses
-File::Glob internally, except on VMS). See L</Performance Enhancements>
-and L</Selected Bug Fixes>.
-
-=item *
-
-L<FindBin> updated from version 1.50 to 1.51.
-
-It no longer returns a wrong result if a script of the same name as the
-current one exists in the path and is executable.
-
-=item *
-
-L<HTTP::Tiny> has been upgraded from version 0.012 to 0.017.
-
-Added support for using C<$ENV{http_proxy}> to set the default proxy host.
-
-Adds additional shorthand methods for all common HTTP verbs,
-a C<post_form()> method for POST-ing x-www-form-urlencoded data and
-a C<www_form_urlencode()> utility method.
-
-=item *
-
-L<IO> has been upgraded from version 1.25_04 to 1.25_06, and L<IO::Handle>
-from version 1.31 to 1.33.
-
-Together, these upgrades fix a problem with IO::Handle's C<getline> and
-C<getlines> methods. When these methods are called on the special ARGV
-handle, the next file is automatically opened, as happens with the built-in
-C<E<lt>E<gt>> and C<readline> functions. But, unlike the built-ins, these
-methods were not respecting the caller's use of the L<open> pragma and
-applying the appropriate I/O layers to the newly-opened file
-[rt.cpan.org #66474].
-
-=item *
-
-L<IPC::Cmd> has been upgraded from version 0.70 to 0.76.
-
-Capturing of command output (both C<STDOUT> and C<STDERR>) is now supported
-using L<IPC::Open3> on MSWin32 without requiring L<IPC::Run>.
-
-=item *
-
-L<IPC::Open3> has been upgraded from version 1.09 to 1.12.
-
-Fixes a bug which prevented use of C<open3> on Windows when C<*STDIN>,
-C<*STDOUT> or C<*STDERR> had been localized.
-
-Fixes a bug which prevented duplicating numeric file descriptors on Windows.
-
-C<open3> with "-" for the program name works once more. This was broken in
-version 1.06 (and hence in Perl 5.14.0) [perl #95748].
-
-=item *
-
-L<Locale::Codes> has been upgraded from version 3.16 to 3.21.
-
-Added Language Extension codes (langext) and Language Variation codes (langvar)
-as defined in the IANA language registry.
-
-Added language codes from ISO 639-5
-
-Added language/script codes from the IANA language subtag registry
-
-Fixed an uninitialized value warning [rt.cpan.org #67438].
-
-Fixed the return value for the all_XXX_codes and all_XXX_names functions
-[rt.cpan.org #69100].
-
-Reorganized modules to move Locale::MODULE to Locale::Codes::MODULE to allow
-for cleaner future additions. The original four modules (Locale::Language,
-Locale::Currency, Locale::Country, Locale::Script) will continue to work, but
-all new sets of codes will be added in the Locale::Codes namespace.
-
-The code2XXX, XXX2code, all_XXX_codes, and all_XXX_names functions now
-support retired codes. All codesets may be specified by a constant or
-by their name now. Previously, they were specified only by a constant.
-
-The alias_code function exists for backward compatibility. It has been
-replaced by rename_country_code. The alias_code function will be
-removed some time after September, 2013.
-
-All work is now done in the central module (Locale::Codes). Previously,
-some was still done in the wrapper modules (Locale::Codes::*). Added
-Language Family codes (langfam) as defined in ISO 639-5.
-
-=item *
-
-L<Math::BigFloat> has been upgraded from version 1.993 to 1.997.
-
-The C<numify> method has been corrected to return a normalized Perl number
-(the result of C<0 + $thing>), instead of a string [rt.cpan.org #66732].
-
-=item *
-
-L<Math::BigInt> has been upgraded from version 1.994 to 1.998.
-
-It provides a new C<bsgn> method that complements the C<babs> method.
-
-It fixes the internal C<objectify> function's handling of "foreign objects"
-so they are converted to the appropriate class (Math::BigInt or
-Math::BigFloat).
-
-=item *
-
-L<Math::BigRat> has been upgraded from version 0.2602 to 0.2603.
-
-C<int()> on a Math::BigRat object containing -1/2 now creates a
-Math::BigInt containing 0, rather than -0. L<Math::BigInt> does not even
-support negative zero, so the resulting object was actually malformed
-[perl #95530].
-
-=item *
-
-L<Math::Complex> has been upgraded from version 1.56 to 1.59
-and L<Math::Trig> from version 1.2 to 1.22.
-
-Fixes include: correct copy constructor usage; fix polarwise formatting with
-numeric format specifier; and more stable C<great_circle_direction> algorithm.
-
-=item *
-
-L<Module::CoreList> has been upgraded from version 2.51 to 2.66.
-
-The C<corelist> utility now understands the C<-r> option for displaying
-Perl release dates and the C<--diff> option to print the set of modlib
-changes between two perl distributions.
-
-=item *
-
-L<Module::Metadata> has been upgraded from version 1.000004 to 1.000009.
-
-Adds C<provides> method to generate a CPAN META provides data structure
-correctly; use of C<package_versions_from_directory> is discouraged.
-
-=item *
-
-L<ODBM_File> has been upgraded from version 1.10 to 1.12.
-
-The XS code is now compiled with C<PERL_NO_GET_CONTEXT>, which will aid
-performance under ithreads.
-
-=item *
-
-L<open> has been upgraded from version 1.08 to 1.10.
-
-It no longer turns off layers on standard handles when invoked without the
-":std" directive. Similarly, when invoked I<with> the ":std" directive, it
-now clears layers on STDERR before applying the new ones, and not just on
-STDIN and STDOUT [perl #92728].
-
-=item *
-
-L<overload> has been upgraded from version 1.13 to 1.18.
-
-C<overload::Overloaded> no longer calls C<can> on the class, but uses
-another means to determine whether the object has overloading. It was
-never correct for it to call C<can>, as overloading does not respect
-AUTOLOAD. So classes that autoload methods and implement C<can> no longer
-have to account for overloading [perl #40333].
-
-A warning is now produced for invalid arguments. See L</New Diagnostics>.
-
-=item *
-
-L<PerlIO::scalar> has been upgraded from version 0.11 to 0.14.
-
-(This is the module that implements C<< open $fh, '>', \$scalar >>.)
-
-It fixes a problem with C<< open my $fh, ">", \$scalar >> not working if
-C<$scalar> is a copy-on-write scalar. (5.14.2)
-
-It also fixes a hang that occurs with C<readline> or C<< <$fh> >> if a
-typeglob has been assigned to $scalar [perl #92258].
-
-It no longer assumes during C<seek> that $scalar is a string internally.
-If it didn't crash, it was close to doing so [perl #92706]. Also, the
-internal print routine no longer assumes that the position set by C<seek>
-is valid, but extends the string to that position, filling the intervening
-bytes (between the old length and the seek position) with nulls
-[perl #78980].
-
-Printing to an in-memory handle now works if the $scalar holds a reference,
-stringifying the reference before modifying it. References used to be
-treated as empty strings.
-
-Printing to an in-memory handle no longer crashes if the $scalar happens to
-hold a number internally, but no string buffer.
-
-Printing to an in-memory handle no longer creates scalars that confuse
-the regular expression engine [perl #108398].
-
-=item *
-
-L<Pod::Functions> has been upgraded from version 1.04 to 1.05.
-
-F<Functions.pm> is now generated at perl build time from annotations in
-F<perlfunc.pod>. This will ensure that L<Pod::Functions> and L<perlfunc>
-remain in synchronisation.
-
-=item *
-
-L<Pod::Html> has been upgraded from version 1.11 to 1.1502.
-
-This is an extensive rewrite of Pod::Html to use L<Pod::Simple> under
-the hood. The output has changed significantly.
-
-=item *
-
-L<Pod::Perldoc> has been upgraded from version 3.15_03 to 3.17.
-
-It corrects the search paths on VMS [perl #90640]. (5.14.1)
-
-The B<-v> option now fetches the right section for C<$0>.
-
-This upgrade has numerous significant fixes. Consult its changelog on
-the CPAN for more information.
-
-=item *
-
-L<POSIX> has been upgraded from version 1.24 to 1.30.
-
-L<POSIX> no longer uses L<AutoLoader>. Any code which was relying on this
-implementation detail was buggy, and may fail because of this change.
-The module's Perl code has been considerably simplified, roughly halving
-the number of lines, with no change in functionality. The XS code has
-been refactored to reduce the size of the shared object by about 12%,
-with no change in functionality. More POSIX functions now have tests.
-
-C<sigsuspend> and C<pause> now run signal handlers before returning, as the
-whole point of these two functions is to wait until a signal has
-arrived, and then return I<after> it has been triggered. Delayed, or
-"safe", signals were preventing that from happening, possibly resulting in
-race conditions [perl #107216].
-
-C<POSIX::sleep> is now a direct call into the underlying OS C<sleep>
-function, instead of being a Perl wrapper on C<CORE::sleep>.
-C<POSIX::dup2> now returns the correct value on Win32 (I<i.e.>, the file
-descriptor). C<POSIX::SigSet> C<sigsuspend> and C<sigpending> and
-C<POSIX::pause> now dispatch safe signals immediately before returning to
-their caller.
-
-C<POSIX::Termios::setattr> now defaults the third argument to C<TCSANOW>,
-instead of 0. On most platforms C<TCSANOW> is defined to be 0, but on some
-0 is not a valid parameter, which caused a call with defaults to fail.
-
-=item *
-
-L<Socket> has been upgraded from version 1.94 to 2.001.
-
-It has new functions and constants for handling IPv6 sockets:
-
- pack_ipv6_mreq
- unpack_ipv6_mreq
- IPV6_ADD_MEMBERSHIP
- IPV6_DROP_MEMBERSHIP
- IPV6_MTU
- IPV6_MTU_DISCOVER
- IPV6_MULTICAST_HOPS
- IPV6_MULTICAST_IF
- IPV6_MULTICAST_LOOP
- IPV6_UNICAST_HOPS
- IPV6_V6ONLY
-
-=item *
-
-L<Storable> has been upgraded from version 2.27 to 2.34.
-
-It no longer turns copy-on-write scalars into read-only scalars when
-freezing and thawing.
-
-=item *
-
-L<Sys::Syslog> has been upgraded from version 0.27 to 0.29.
-
-This upgrade closes many outstanding bugs.
-
-=item *
-
-L<Term::ANSIColor> has been upgraded from version 3.00 to 3.01.
-
-Only interpret an initial array reference as a list of colors, not any initial
-reference, allowing the colored function to work properly on objects with
-stringification defined.
-
-=item *
-
-L<Term::ReadLine> has been upgraded from version 1.07 to 1.09.
-
-Term::ReadLine now supports any event loop, including unpublished ones and
-simple L<IO::Select>, loops without the need to rewrite existing code for
-any particular framework [perl #108470].
-
-=item *
-
-L<threads::shared> has been upgraded from version 1.37 to 1.40.
-
-Destructors on shared objects used to be ignored sometimes if the objects
-were referenced only by shared data structures. This has been mostly
-fixed, but destructors may still be ignored if the objects still exist at
-global destruction time [perl #98204].
-
-=item *
-
-L<Unicode::Collate> has been upgraded from version 0.73 to 0.89.
-
-Updated to CLDR 1.9.1
-
-Locales updated to CLDR 2.0: mk, mt, nb, nn, ro, ru, sk, sr, sv, uk,
-zh__pinyin, zh__stroke
-
-Newly supported locales: bn, fa, ml, mr, or, pa, sa, si, si__dictionary,
-sr_Latn, sv__reformed, ta, te, th, ur, wae.
-
-Tailored compatibility ideographs as well as unified ideographs for the
-locales: ja, ko, zh__big5han, zh__gb2312han, zh__pinyin, zh__stroke.
-
-Locale/*.pl files are now searched for in @INC.
-
-=item *
-
-L<Unicode::Normalize> has been upgraded from version 1.10 to 1.14.
-
-Fixes for the removal of F<unicore/CompositionExclusions.txt> from core.
-
-=item *
-
-L<Unicode::UCD> has been upgraded from version 0.32 to 0.43.
-
-This adds four new functions: C<prop_aliases()> and
-C<prop_value_aliases()>, which are used to find all Unicode-approved
-synonyms for property names, or to convert from one name to another;
-C<prop_invlist> which returns all code points matching a given
-Unicode binary property; and C<prop_invmap> which returns the complete
-specification of a given Unicode property.
-
-=item *
-
-L<Win32API::File> has been upgraded from version 0.1101 to 0.1200.
-
-Added SetStdHandle and GetStdHandle functions
-
-=back
-
-=head2 Removed Modules and Pragmata
-
-As promised in Perl 5.14.0's release notes, the following modules have
-been removed from the core distribution, and if needed should be installed
-from CPAN instead.
-
-=over
-
-=item *
-
-L<Devel::DProf> has been removed from the Perl core. Prior version was
-20110228.00.
-
-=item *
-
-L<Shell> has been removed from the Perl core. Prior version was 0.72_01.
-
-=item *
-
-Several old perl4-style libraries which have been deprecated with 5.14
-are now removed:
-
- abbrev.pl assert.pl bigfloat.pl bigint.pl bigrat.pl cacheout.pl
- complete.pl ctime.pl dotsh.pl exceptions.pl fastcwd.pl flush.pl
- getcwd.pl getopt.pl getopts.pl hostname.pl importenv.pl
- lib/find{,depth}.pl look.pl newgetopt.pl open2.pl open3.pl
- pwd.pl shellwords.pl stat.pl tainted.pl termcap.pl timelocal.pl
-
-They can be found on CPAN as L<Perl4::CoreLibs>.
-
-=back
-
-=head1 Documentation
-
-=head2 New Documentation
-
-=head3 L<perldtrace>
-
-L<perldtrace> describes Perl's DTrace support, listing the provided probes
-and gives examples of their use.
-
-=head3 L<perlexperiment>
-
-This document is intended to provide a list of experimental features in
-Perl. It is still a work in progress.
-
-=head3 L<perlootut>
-
-This a new OO tutorial. It focuses on basic OO concepts, and then recommends
-that readers choose an OO framework from CPAN.
-
-=head3 L<perlxstypemap>
-
-The new manual describes the XS typemapping mechanism in unprecedented
-detail and combines new documentation with information extracted from
-L<perlxs> and the previously unofficial list of all core typemaps.
-
-=head2 Changes to Existing Documentation
-
-=head3 L<perlapi>
-
-=over 4
-
-=item *
-
-The HV API has long accepted negative lengths to show that the key is
-in UTF8. This is now documented.
-
-=item *
-
-The C<boolSV()> macro is now documented.
-
-=back
-
-=head3 L<perlfunc>
-
-=over 4
-
-=item *
-
-C<dbmopen> treats a 0 mode as a special case, that prevents a nonexistent
-file from being created. This has been the case since Perl 5.000, but was
-never documented anywhere. Now the perlfunc entry mentions it
-[perl #90064].
-
-=item *
-
-As an accident of history, C<open $fh, '<:', ...> applies the default
-layers for the platform (C<:raw> on Unix, C<:crlf> on Windows), ignoring
-whatever is declared by L<open.pm|open>. This seems such a useful feature
-it has been documented in L<perlfunc|perlfunc/open> and L<open>.
-
-=item *
-
-The entry for C<split> has been rewritten. It is now far clearer than
-before.
-
-=back
-
-=head3 L<perlguts>
-
-=over 4
-
-=item *
-
-A new section, L<Autoloading with XSUBs|perlguts/Autoloading with XSUBs>,
-has been added, which explains the two APIs for accessing the name of the
-autoloaded sub.
-
-=item *
-
-Some function descriptions in L<perlguts> were confusing, as it was
-not clear whether they referred to the function above or below the
-description. This has been clarified [perl #91790].
-
-=back
-
-=head3 L<perlobj>
-
-=over 4
-
-=item *
-
-This document has been rewritten from scratch, and its coverage of various OO
-concepts has been expanded.
-
-=back
-
-=head3 L<perlop>
-
-=over 4
-
-=item *
-
-Documentation of the smartmatch operator has been reworked and moved from
-perlsyn to perlop where it belongs.
-
-It has also been corrected for the case of C<undef> on the left-hand
-side. The list of different smart match behaviors had an item in the
-wrong place.
-
-=item *
-
-Documentation of the ellipsis statement (C<...>) has been reworked and
-moved from perlop to perlsyn.
-
-=item *
-
-The explanation of bitwise operators has been expanded to explain how they
-work on Unicode strings (5.14.1).
-
-=item *
-
-More examples for C<m//g> have been added (5.14.1).
-
-=item *
-
-The C<<< <<\FOO >>> here-doc syntax has been documented (5.14.1).
-
-=back
-
-=head3 L<perlpragma>
-
-=over 4
-
-=item *
-
-There is now a standard convention for naming keys in the C<%^H>,
-documented under L<Key naming|perlpragma/Key naming>.
-
-=back
-
-=head3 L<perlsec/Laundering and Detecting Tainted Data>
-
-=over 4
-
-=item *
-
-The example function for checking for taintedness contained a subtle
-error. C<$@> needs to be localized to prevent its changing this
-global's value outside the function. The preferred method to check for
-this remains L<Scalar::Util/tainted>.
-
-=back
-
-=head3 L<perllol>
-
-=over
-
-=item *
-
-L<perllol> has been expanded with examples using the new C<push $scalar>
-syntax introduced in Perl 5.14.0 (5.14.1).
-
-=back
-
-=head3 L<perlmod>
-
-=over
-
-=item *
-
-L<perlmod> now states explicitly that some types of explicit symbol table
-manipulation are not supported. This codifies what was effectively already
-the case [perl #78074].
-
-=back
-
-=head3 L<perlpodstyle>
-
-=over 4
-
-=item *
-
-The tips on which formatting codes to use have been corrected and greatly
-expanded.
-
-=item *
-
-There are now a couple of example one-liners for previewing POD files after
-they have been edited.
-
-=back
-
-=head3 L<perlre>
-
-=over
-
-=item *
-
-The C<(*COMMIT)> directive is now listed in the right section
-(L<Verbs without an argument|perlre/Verbs without an argument>).
-
-=back
-
-=head3 L<perlrun>
-
-=over
-
-=item *
-
-L<perlrun> has undergone a significant clean-up. Most notably, the
-B<-0x...> form of the B<-0> flag has been clarified, and the final section
-on environment variables has been corrected and expanded (5.14.1).
-
-=back
-
-=head3 L<perlsub>
-
-=over
-
-=item *
-
-The ($;) prototype syntax, which has existed for rather a long time, is now
-documented in L<perlsub>. It lets a unary function have the same
-precedence as a list operator.
-
-=back
-
-=head3 L<perltie>
-
-=over
-
-=item *
-
-The required syntax for tying handles has been documented.
-
-=back
-
-=head3 L<perlvar>
-
-=over
-
-=item *
-
-The documentation for L<$!|perlvar/$!> has been corrected and clarified.
-It used to state that $! could be C<undef>, which is not the case. It was
-also unclear whether system calls set C's C<errno> or Perl's C<$!>
-[perl #91614].
-
-=item *
-
-Documentation for L<$$|perlvar/$$> has been amended with additional
-cautions regarding changing the process ID.
-
-=back
-
-=head3 Other Changes
-
-=over 4
-
-=item *
-
-L<perlxs> was extended with documentation on inline typemaps.
-
-=item *
-
-L<perlref> has a new L<Circular References|perlref/Circular References>
-section explaining how circularities may not be freed and how to solve that
-with weak references.
-
-=item *
-
-Parts of L<perlapi> were clarified, and Perl equivalents of some C
-functions have been added as an additional mode of exposition.
-
-=item *
-
-A few parts of L<perlre> and L<perlrecharclass> were clarified.
-
-=back
-
-=head2 Removed Documentation
-
-=head3 Old OO Documentation
-
-The old OO tutorials, perltoot, perltooc, and perlboot, have been
-removed. The perlbot (bag of object tricks) document has been removed
-as well.
-
-=head3 Development Deltas
-
-The perldelta files for development releases are no longer packaged with
-perl. These can still be found in the perl source code repository.
-
-=head1 Diagnostics
-
-The following additions or changes have been made to diagnostic output,
-including warnings and fatal error messages. For the complete list of
-diagnostic messages, see L<perldiag>.
-
-=head2 New Diagnostics
-
-=head3 New Errors
-
-=over 4
-
-=item *
-
-L<Cannot set tied @DB::args|perldiag/"Cannot set tied @DB::args">
-
-This error occurs when C<caller> tries to set C<@DB::args> but finds it
-tied. Before this error was added, it used to crash instead.
-
-=item *
-
-L<Cannot tie unreifiable array|perldiag/"Cannot tie unreifiable array">
-
-This error is part of a safety check that the C<tie> operator does before
-tying a special array like C<@_>. You should never see this message.
-
-=item *
-
-L<&CORE::%s cannot be called directly|perldiag/"&CORE::%s cannot be called directly">
-
-This occurs when a subroutine in the C<CORE::> namespace is called
-with C<&foo> syntax or through a reference. Some subroutines
-in this package cannot yet be called that way, but must be
-called as barewords. See L</Subroutines in the C<CORE> namespace>, above.
-
-=item *
-
-L<Source filters apply only to byte streams|perldiag/"Source filters apply only to byte streams">
-
-This new error occurs when you try to activate a source filter (usually by
-loading a source filter module) within a string passed to C<eval> under the
-C<unicode_eval> feature.
-
-=back
-
-=head3 New Warnings
-
-=over 4
-
-=item *
-
-L<defined(@array) is deprecated|perldiag/"defined(@array) is deprecated">
-
-The long-deprecated C<defined(@array)> now also warns for package variables.
-Previously it issued a warning for lexical variables only.
-
-=item *
-
-L<length() used on %s|perldiag/length() used on %s>
-
-This new warning occurs when C<length> is used on an array or hash, instead
-of C<scalar(@array)> or C<scalar(keys %hash)>.
-
-=item *
-
-L<lvalue attribute %s already-defined subroutine|perldiag/"lvalue attribute %s already-defined subroutine">
-
-L<attributes.pm|attributes> now emits this warning when the :lvalue
-attribute is applied to a Perl subroutine that has already been defined, as
-doing so can have unexpected side-effects.
-
-=item *
-
-L<overload arg '%s' is invalid|perldiag/"overload arg '%s' is invalid">
-
-This warning, in the "overload" category, is produced when the overload
-pragma is given an argument it doesn't recognize, presumably a mistyped
-operator.
-
-=item *
-
-L<$[ used in %s (did you mean $] ?)|perldiag/"$[ used in %s (did you mean $] ?)">
-
-This new warning exists to catch the mistaken use of C<$[> in version
-checks. C<$]>, not C<$[>, contains the version number.
-
-=item *
-
-L<Useless assignment to a temporary|perldiag/"Useless assignment to a temporary">
-
-Assigning to a temporary scalar returned
-from an lvalue subroutine now produces this
-warning [perl #31946].
-
-=item *
-
-L<Useless use of \E|perldiag/"Useless use of \E">
-
-C<\E> does nothing unless preceded by C<\Q>, C<\L> or C<\U>.
-
-=back
-
-=head2 Removed Errors
-
-=over
-
-=item *
-
-"sort is now a reserved word"
-
-This error used to occur when C<sort> was called without arguments,
-followed by C<;> or C<)>. (E.g., C<sort;> would die, but C<{sort}> was
-OK.) This error message was added in Perl 3 to catch code like
-C<close(sort)> which would no longer work. More than two decades later,
-this message is no longer appropriate. Now C<sort> without arguments is
-always allowed, and returns an empty list, as it did in those cases
-where it was already allowed [perl #90030].
-
-=back
-
-=head2 Changes to Existing Diagnostics
-
-=over 4
-
-=item *
-
-The "Applying pattern match..." or similar warning produced when an
-array or hash is on the left-hand side of the C<=~> operator now
-mentions the name of the variable.
-
-=item *
-
-The "Attempt to free non-existent shared string" has had the spelling
-of "non-existent" corrected to "nonexistent". It was already listed
-with the correct spelling in L<perldiag>.
-
-=item *
-
-The error messages for using C<default> and C<when> outside a
-topicalizer have been standardized to match the messages for C<continue>
-and loop controls. They now read 'Can't "default" outside a
-topicalizer' and 'Can't "when" outside a topicalizer'. They both used
-to be 'Can't use when() outside a topicalizer' [perl #91514].
-
-=item *
-
-The message, "Code point 0x%X is not Unicode, no properties match it;
-all inverse properties do" has been changed to "Code point 0x%X is not
-Unicode, all \p{} matches fail; all \P{} matches succeed".
-
-=item *
-
-Redefinition warnings for constant subroutines used to be mandatory,
-even occurring under C<no warnings>. Now they respect the L<warnings>
-pragma.
-
-=item *
-
-The "glob failed" warning message is now suppressible via C<no warnings>
-[perl #111656].
-
-=item *
-
-The L<Invalid version format|perldiag/"Invalid version format (%s)">
-error message now says "negative version number" within the parentheses,
-rather than "non-numeric data", for negative numbers.
-
-=item *
-
-The two warnings
-L<Possible attempt to put comments in qw() list|perldiag/"Possible attempt to put comments in qw() list">
-and
-L<Possible attempt to separate words with commas|perldiag/"Possible attempt to separate words with commas">
-are no longer mutually exclusive: the same C<qw> construct may produce
-both.
-
-=item *
-
-The uninitialized warning for C<y///r> when C<$_> is implicit and
-undefined now mentions the variable name, just like the non-/r variation
-of the operator.
-
-=item *
-
-The 'Use of "foo" without parentheses is ambiguous' warning has been
-extended to apply also to user-defined subroutines with a (;$)
-prototype, and not just to built-in functions.
-
-=item *
-
-Warnings that mention the names of lexical (C<my>) variables with
-Unicode characters in them now respect the presence or absence of the
-C<:utf8> layer on the output handle, instead of outputting UTF8
-regardless. Also, the correct names are included in the strings passed
-to C<$SIG{__WARN__}> handlers, rather than the raw UTF8 bytes.
-
-=back
-
-=head1 Utility Changes
-
-=head3 L<h2ph>
-
-=over 4
-
-=item *
-
-L<h2ph> used to generate code of the form
-
- unless(defined(&FOO)) {
- sub FOO () {42;}
- }
-
-But the subroutine is a compile-time declaration, and is hence unaffected
-by the condition. It has now been corrected to emit a string C<eval>
-around the subroutine [perl #99368].
-
-=back
-
-=head3 L<splain>
-
-=over 4
-
-=item *
-
-F<splain> no longer emits backtraces with the first line number repeated.
-
-This:
-
- Uncaught exception from user code:
- Cannot fwiddle the fwuddle at -e line 1.
- at -e line 1
- main::baz() called at -e line 1
- main::bar() called at -e line 1
- main::foo() called at -e line 1
-
-has become this:
-
- Uncaught exception from user code:
- Cannot fwiddle the fwuddle at -e line 1.
- main::baz() called at -e line 1
- main::bar() called at -e line 1
- main::foo() called at -e line 1
-
-=item *
-
-Some error messages consist of multiple lines that are listed as separate
-entries in L<perldiag>. splain has been taught to find the separate
-entries in these cases, instead of simply failing to find the message.
-
-=back
-
-=head3 L<zipdetails>
-
-=over 4
-
-=item *
-
-This is a new utility, included as part of an
-L<IO::Compress::Base> upgrade.
-
-L<zipdetails> displays information about the internal record structure
-of the zip file. It is not concerned with displaying any details of
-the compressed data stored in the zip file.
-
-=back
-
-=head1 Configuration and Compilation
-
-=over 4
-
-=item *
-
-F<regexp.h> has been modified for compatibility with GCC's B<-Werror>
-option, as used by some projects that include perl's header files (5.14.1).
-
-=item *
-
-C<USE_LOCALE{,_COLLATE,_CTYPE,_NUMERIC}> have been added the output of perl -V
-as they have affect the behavior of the interpreter binary (albeit
-in only a small area).
-
-=item *
-
-The code and tests for L<IPC::Open2> have been moved from F<ext/IPC-Open2>
-into F<ext/IPC-Open3>, as C<IPC::Open2::open2()> is implemented as a thin
-wrapper around C<IPC::Open3::_open3()>, and hence is very tightly coupled to
-it.
-
-=item *
-
-The magic types and magic vtables are now generated from data in a new script
-F<regen/mg_vtable.pl>, instead of being maintained by hand. As different
-EBCDIC variants can't agree on the code point for '~', the character to code
-point conversion is done at build time by F<generate_uudmap> to a new generated
-header F<mg_data.h>. C<PL_vtbl_bm> and C<PL_vtbl_fm> are now defined by the
-pre-processor as C<PL_vtbl_regexp>, instead of being distinct C variables.
-C<PL_vtbl_sig> has been removed.
-
-=item *
-
-Building with C<-DPERL_GLOBAL_STRUCT> works again. This configuration is not
-generally used.
-
-=item *
-
-Perl configured with I<MAD> now correctly frees C<MADPROP> structures when
-OPs are freed. C<MADPROP>s are now allocated with C<PerlMemShared_malloc()>
-
-=item *
-
-F<makedef.pl> has been refactored. This should have no noticeable affect on
-any of the platforms that use it as part of their build (AIX, VMS, Win32).
-
-=item *
-
-C<useperlio> can no longer be disabled.
-
-=item *
-
-The file F<global.sym> is no longer needed, and has been removed. It
-contained a list of all exported functions, one of the files generated by
-F<regen/embed.pl> from data in F<embed.fnc> and F<regen/opcodes>. The code
-has been refactored so that the only user of F<global.sym>, F<makedef.pl>,
-now reads F<embed.fnc> and F<regen/opcodes> directly, removing the need to
-store the list of exported functions in an intermediate file.
-
-As F<global.sym> was never installed, this change should not be visible
-outside the build process.
-
-=item *
-
-F<pod/buildtoc>, used by the build process to build L<perltoc>, has been
-refactored and simplified. It now contains only code to build L<perltoc>;
-the code to regenerate Makefiles has been moved to F<Porting/pod_rules.pl>.
-It's a bug if this change has any material effect on the build process.
-
-=item *
-
-F<pod/roffitall> is now built by F<pod/buildtoc>, instead of being
-shipped with the distribution. Its list of manpages is now generated
-(and therefore current). See also RT #103202 for an unresolved related
-issue.
-
-=item *
-
-The man page for C<XS::Typemap> is no longer installed. C<XS::Typemap>
-is a test module which is not installed, hence installing its
-documentation makes no sense.
-
-=item *
-
-The -Dusesitecustomize and -Duserelocatableinc options now work
-together properly.
-
-=back
-
-=head1 Platform Support
-
-=head2 Platform-Specific Notes
-
-=head3 Cygwin
-
-=over 4
-
-=item *
-
-Since version 1.7, Cygwin supports native UTF-8 paths. If Perl is built
-under that environment, directory and filenames will be UTF-8 encoded.
-
-=item *
-
-Cygwin does not initialize all original Win32 environment variables. See
-F<README.cygwin> for a discussion of the newly-added
-C<Cygwin::sync_winenv()> function [perl #110190] and for
-further links.
-
-=back
-
-=head3 HP-UX
-
-=over 4
-
-=item *
-
-HP-UX PA-RISC/64 now supports gcc-4.x
-
-A fix to correct the socketsize now makes the test suite pass on HP-UX
-PA-RISC for 64bitall builds. (5.14.2)
-
-=back
-
-=head3 VMS
-
-=over 4
-
-=item *
-
-Remove unnecessary includes, fix miscellaneous compiler warnings and
-close some unclosed comments on F<vms/vms.c>.
-
-=item *
-
-Remove sockadapt layer from the VMS build.
-
-=item *
-
-Explicit support for VMS versions before v7.0 and DEC C versions
-before v6.0 has been removed.
-
-=item *
-
-Since Perl 5.10.1, the home-grown C<stat> wrapper has been unable to
-distinguish between a directory name containing an underscore and an
-otherwise-identical filename containing a dot in the same position
-(e.g., t/test_pl as a directory and t/test.pl as a file). This problem
-has been corrected.
-
-=item *
-
-The build on VMS now permits names of the resulting symbols in C code for
-Perl longer than 31 characters. Symbols like
-C<Perl__it_was_the_best_of_times_it_was_the_worst_of_times> can now be
-created freely without causing the VMS linker to seize up.
-
-=back
-
-=head3 GNU/Hurd
-
-=over 4
-
-=item *
-
-Numerous build and test failures on GNU/Hurd have been resolved with hints
-for building DBM modules, detection of the library search path, and enabling
-of large file support.
-
-=back
-
-=head3 OpenVOS
-
-=over 4
-
-=item *
-
-Perl is now built with dynamic linking on OpenVOS, the minimum supported
-version of which is now Release 17.1.0.
-
-=back
-
-=head3 SunOS
-
-The CC workshop C++ compiler is now detected and used on systems that ship
-without cc.
-
-=head1 Internal Changes
-
-=over 4
-
-=item *
-
-The compiled representation of formats is now stored via the C<mg_ptr> of
-their C<PERL_MAGIC_fm>. Previously it was stored in the string buffer,
-beyond C<SvLEN()>, the regular end of the string. C<SvCOMPILED()> and
-C<SvCOMPILED_{on,off}()> now exist solely for compatibility for XS code.
-The first is always 0, the other two now no-ops. (5.14.1)
-
-=item *
-
-Some global variables have been marked C<const>, members in the interpreter
-structure have been re-ordered, and the opcodes have been re-ordered. The
-op C<OP_AELEMFAST> has been split into C<OP_AELEMFAST> and C<OP_AELEMFAST_LEX>.
-
-=item *
-
-When empting a hash of its elements (e.g., via undef(%h), or %h=()), HvARRAY
-field is no longer temporarily zeroed. Any destructors called on the freed
-elements see the remaining elements. Thus, %h=() becomes more like
-C<delete $h{$_} for keys %h>.
-
-=item *
-
-Boyer-Moore compiled scalars are now PVMGs, and the Boyer-Moore tables are now
-stored via the mg_ptr of their C<PERL_MAGIC_bm>.
-Previously they were PVGVs, with the tables stored in
-the string buffer, beyond C<SvLEN()>. This eliminates
-the last place where the core stores data beyond C<SvLEN()>.
-
-=item *
-
-Simplified logic in C<Perl_sv_magic()> introduces a small change of
-behavior for error cases involving unknown magic types. Previously, if
-C<Perl_sv_magic()> was passed a magic type unknown to it, it would
-
-=over
-
-=item 1.
-
-Croak "Modification of a read-only value attempted" if read only
-
-=item 2.
-
-Return without error if the SV happened to already have this magic
-
-=item 3.
-
-otherwise croak "Don't know how to handle magic of type \\%o"
-
-=back
-
-Now it will always croak "Don't know how to handle magic of type \\%o", even
-on read-only values, or SVs which already have the unknown magic type.
-
-=item *
-
-The experimental C<fetch_cop_label> function has been renamed to
-C<cop_fetch_label>.
-
-=item *
-
-The C<cop_store_label> function has been added to the API, but is
-experimental.
-
-=item *
-
-F<embedvar.h> has been simplified, and one level of macro indirection for
-PL_* variables has been removed for the default (non-multiplicity)
-configuration. PERLVAR*() macros now directly expand their arguments to
-tokens such as C<PL_defgv>, instead of expanding to C<PL_Idefgv>, with
-F<embedvar.h> defining a macro to map C<PL_Idefgv> to C<PL_defgv>. XS code
-which has unwarranted chumminess with the implementation may need updating.
-
-=item *
-
-An API has been added to explicitly choose whether to export XSUB
-symbols. More detail can be found in the comments for commit e64345f8.
-
-=item *
-
-The C<is_gv_magical_sv> function has been eliminated and merged with
-C<gv_fetchpvn_flags>. It used to be called to determine whether a GV
-should be autovivified in rvalue context. Now it has been replaced with a
-new C<GV_ADDMG> flag (not part of the API).
-
-=item *
-
-The returned code point from the function C<utf8n_to_uvuni()>
-when the input is malformed UTF-8, malformations are allowed, and
-C<utf8> warnings are off is now the Unicode REPLACEMENT CHARACTER
-whenever the malformation is such that no well-defined code point can be
-computed. Previously the returned value was essentially garbage. The
-only malformations that have well-defined values are a zero-length
-string (0 is the return), and overlong UTF-8 sequences.
-
-=item *
-
-Padlists are now marked C<AvREAL>; i.e., reference-counted. They have
-always been reference-counted, but were not marked real, because F<pad.c>
-did its own clean-up, instead of using the usual clean-up code in F<sv.c>.
-That caused problems in thread cloning, so now the C<AvREAL> flag is on,
-but is turned off in F<pad.c> right before the padlist is freed (after
-F<pad.c> has done its custom freeing of the pads).
-
-=item *
-
-All C files that make up the Perl core have been converted to UTF-8.
-
-=item *
-
-These new functions have been added as part of the work on Unicode symbols:
-
- HvNAMELEN
- HvNAMEUTF8
- HvENAMELEN
- HvENAMEUTF8
- gv_init_pv
- gv_init_pvn
- gv_init_pvsv
- gv_fetchmeth_pv
- gv_fetchmeth_pvn
- gv_fetchmeth_sv
- gv_fetchmeth_pv_autoload
- gv_fetchmeth_pvn_autoload
- gv_fetchmeth_sv_autoload
- gv_fetchmethod_pv_flags
- gv_fetchmethod_pvn_flags
- gv_fetchmethod_sv_flags
- gv_autoload_pv
- gv_autoload_pvn
- gv_autoload_sv
- newGVgen_flags
- sv_derived_from_pv
- sv_derived_from_pvn
- sv_derived_from_sv
- sv_does_pv
- sv_does_pvn
- sv_does_sv
- whichsig_pv
- whichsig_pvn
- whichsig_sv
- newCONSTSUB_flags
-
-The gv_fetchmethod_*_flags functions, like gv_fetchmethod_flags, are
-experimental and may change in a future release.
-
-=item *
-
-The following functions were added. These are I<not> part of the API:
-
- GvNAMEUTF8
- GvENAMELEN
- GvENAME_HEK
- CopSTASH_flags
- CopSTASH_flags_set
- PmopSTASH_flags
- PmopSTASH_flags_set
- sv_sethek
- HEKfARG
-
-There is also a C<HEKf> macro corresponding to C<SVf>, for
-interpolating HEKs in formatted strings.
-
-=item *
-
-C<sv_catpvn_flags> takes a couple of new internal-only flags,
-C<SV_CATBYTES> and C<SV_CATUTF8>, which tell it whether the char array to
-be concatenated is UTF8. This allows for more efficient concatenation than
-creating temporary SVs to pass to C<sv_catsv>.
-
-=item *
-
-For XS AUTOLOAD subs, $AUTOLOAD is set once more, as it was in 5.6.0. This
-is in addition to setting C<SvPVX(cv)>, for compatibility with 5.8 to 5.14.
-See L<perlguts/Autoloading with XSUBs>.
-
-=item *
-
-Perl now checks whether the array (the linearized isa) returned by a MRO
-plugin begins with the name of the class itself, for which the array was
-created, instead of assuming that it does. This prevents the first element
-from being skipped during method lookup. It also means that
-C<mro::get_linear_isa> may return an array with one more element than the
-MRO plugin provided [perl #94306].
-
-=item *
-
-C<PL_curstash> is now reference-counted.
-
-=item *
-
-There are now feature bundle hints in C<PL_hints> (C<$^H>) that version
-declarations use, to avoid having to load F<feature.pm>. One setting of
-the hint bits indicates a "custom" feature bundle, which means that the
-entries in C<%^H> still apply. F<feature.pm> uses that.
-
-The C<HINT_FEATURE_MASK> macro is defined in F<perl.h> along with other
-hints. Other macros for setting and testing features and bundles are in
-the new F<feature.h>. C<FEATURE_IS_ENABLED> (which has moved to
-F<feature.h>) is no longer used throughout the codebase, but more specific
-macros, e.g., C<FEATURE_SAY_IS_ENABLED>, that are defined in F<feature.h>.
-
-=item *
-
-F<lib/feature.pm> is now a generated file, created by the new
-F<regen/feature.pl> script, which also generates F<feature.h>.
-
-=item *
-
-Tied arrays are now always C<AvREAL>. If C<@_> or C<DB::args> is tied, it
-is reified first, to make sure this is always the case.
-
-=item *
-
-Two new functions C<utf8_to_uvchr_buf()> and C<utf8_to_uvuni_buf()> have
-been added. These are the same as C<utf8_to_uvchr> and
-C<utf8_to_uvuni> (which are now deprecated), but take an extra parameter
-that is used to guard against reading beyond the end of the input
-string.
-See L<perlapi/utf8_to_uvchr_buf> and L<perlapi/utf8_to_uvuni_buf>.
-
-=item *
-
-The regular expression engine now does TRIE case insensitive matches
-under Unicode. This may change the output of C<< use re 'debug'; >>,
-and will speed up various things.
-
-=item *
-
-There is a new C<wrap_op_checker()> function, which provides a thread-safe
-alternative to writing to C<PL_check> directly.
-
-=back
-
-=head1 Selected Bug Fixes
-
-=head2 Array and hash
-
-=over
-
-=item *
-
-A bug has been fixed that would cause a "Use of freed value in iteration"
-error if the next two hash elements that would be iterated over are
-deleted [perl #85026]. (5.14.1)
-
-=item *
-
-Deleting the current hash iterator (the hash element that would be returned
-by the next call to C<each>) in void context used not to free it
-[perl #85026].
-
-=item *
-
-Deletion of methods via C<delete $Class::{method}> syntax used to update
-method caches if called in void context, but not scalar or list context.
-
-=item *
-
-When hash elements are deleted in void context, the internal hash entry is
-now freed before the value is freed, to prevent destructors called by that
-latter freeing from seeing the hash in an inconsistent state. It was
-possible to cause double-frees if the destructor freed the hash itself
-[perl #100340].
-
-=item *
-
-A C<keys> optimization in Perl 5.12.0 to make it faster on empty hashes
-caused C<each> not to reset the iterator if called after the last element
-was deleted.
-
-=item *
-
-Freeing deeply nested hashes no longer crashes [perl #44225].
-
-=item *
-
-It is possible from XS code to create hashes with elements that have no
-values. The hash element and slice operators used to crash
-when handling these in lvalue context. They now
-produce a "Modification of non-creatable hash value attempted" error
-message.
-
-=item *
-
-If list assignment to a hash or array triggered destructors that freed the
-hash or array itself, a crash would ensue. This is no longer the case
-[perl #107440].
-
-=item *
-
-It used to be possible to free the typeglob of a localized array or hash
-(e.g., C<local @{"x"}; delete $::{x}>), resulting in a crash on scope exit.
-
-=item *
-
-Some core bugs affecting L<Hash::Util> have been fixed: locking a hash
-element that is a glob copy no longer causes the next assignment to it to
-corrupt the glob (5.14.2), and unlocking a hash element that holds a
-copy-on-write scalar no longer causes modifications to that scalar to
-modify other scalars that were sharing the same string buffer.
-
-=back
-
-=head2 C API fixes
-
-=over
-
-=item *
-
-The C<newHVhv> XS function now works on tied hashes, instead of crashing or
-returning an empty hash.
-
-=item *
-
-The C<SvIsCOW> C macro now returns false for read-only copies of typeglobs,
-such as those created by:
-
- $hash{elem} = *foo;
- Hash::Util::lock_value %hash, 'elem';
-
-It used to return true.
-
-=item *
-
-The C<SvPVutf8> C function no longer tries to modify its argument,
-resulting in errors [perl #108994].
-
-=item *
-
-C<SvPVutf8> now works properly with magical variables.
-
-=item *
-
-C<SvPVbyte> now works properly non-PVs.
-
-=item *
-
-When presented with malformed UTF-8 input, the XS-callable functions
-C<is_utf8_string()>, C<is_utf8_string_loc()>, and
-C<is_utf8_string_loclen()> could read beyond the end of the input
-string by up to 12 bytes. This no longer happens. [perl #32080].
-However, currently, C<is_utf8_char()> still has this defect, see
-L</is_utf8_char()> above.
-
-=item *
-
-The C-level C<pregcomp> function could become confused about whether the
-pattern was in UTF8 if the pattern was an overloaded, tied, or otherwise
-magical scalar [perl #101940].
-
-=back
-
-=head2 Compile-time hints
-
-=over
-
-=item *
-
-Tying C<%^H> no longer causes perl to crash or ignore the contents of
-C<%^H> when entering a compilation scope [perl #106282].
-
-=item *
-
-C<eval $string> and C<require> used not to
-localize C<%^H> during compilation if it
-was empty at the time the C<eval> call itself was compiled. This could
-lead to scary side effects, like C<use re "/m"> enabling other flags that
-the surrounding code was trying to enable for its caller [perl #68750].
-
-=item *
-
-C<eval $string> and C<require> no longer localize hints (C<$^H> and C<%^H>)
-at run time, but only during compilation of the $string or required file.
-This makes C<BEGIN { $^H{foo}=7 }> equivalent to
-C<BEGIN { eval '$^H{foo}=7' }> [perl #70151].
-
-=item *
-
-Creating a BEGIN block from XS code (via C<newXS> or C<newATTRSUB>) would,
-on completion, make the hints of the current compiling code the current
-hints. This could cause warnings to occur in a non-warning scope.
-
-=back
-
-=head2 Copy-on-write scalars
-
-Copy-on-write or shared hash key scalars
-were introduced in 5.8.0, but most Perl code
-did not encounter them (they were used mostly internally). Perl
-5.10.0 extended them, such that assigning C<__PACKAGE__> or a
-hash key to a scalar would make it copy-on-write. Several parts
-of Perl were not updated to account for them, but have now been fixed.
-
-=over
-
-=item *
-
-C<utf8::decode> had a nasty bug that would modify copy-on-write scalars'
-string buffers in place (i.e., skipping the copy). This could result in
-hashes having two elements with the same key [perl #91834]. (5.14.2)
-
-=item *
-
-Lvalue subroutines were not allowing COW scalars to be returned. This was
-fixed for lvalue scalar context in Perl 5.12.3 and 5.14.0, but list context
-was not fixed until this release.
-
-=item *
-
-Elements of restricted hashes (see the L<fields> pragma) containing
-copy-on-write values couldn't be deleted, nor could such hashes be cleared
-(C<%hash = ()>). (5.14.2)
-
-=item *
-
-Localizing a tied variable used to make it read-only if it contained a
-copy-on-write string. (5.14.2)
-
-=item *
-
-Assigning a copy-on-write string to a stash
-element no longer causes a double free. Regardless of this change, the
-results of such assignments are still undefined.
-
-=item *
-
-Assigning a copy-on-write string to a tied variable no longer stops that
-variable from being tied if it happens to be a PVMG or PVLV internally.
-
-=item *
-
-Doing a substitution on a tied variable returning a copy-on-write
-scalar used to cause an assertion failure or an "Attempt to free
-nonexistent shared string" warning.
-
-=item *
-
-This one is a regression from 5.12: In 5.14.0, the bitwise assignment
-operators C<|=>, C<^=> and C<&=> started leaving the left-hand side
-undefined if it happened to be a copy-on-write string [perl #108480].
-
-=item *
-
-L<Storable>, L<Devel::Peek> and L<PerlIO::scalar> had similar problems.
-See L</Updated Modules and Pragmata>, above.
-
-=back
-
-=head2 The debugger
-
-=over
-
-=item *
-
-F<dumpvar.pl>, and therefore the C<x> command in the debugger, have been
-fixed to handle objects blessed into classes whose names contain "=". The
-contents of such objects used not to be dumped [perl #101814].
-
-=item *
-
-The "R" command for restarting a debugger session has been fixed to work on
-Windows, or any other system lacking a C<POSIX::_SC_OPEN_MAX> constant
-[perl #87740].
-
-=item *
-
-The C<#line 42 foo> directive used not to update the arrays of lines used
-by the debugger if it occurred in a string eval. This was partially fixed
-in 5.14, but it worked only for a single C<#line 42 foo> in each eval. Now
-it works for multiple.
-
-=item *
-
-When subroutine calls are intercepted by the debugger, the name of the
-subroutine or a reference to it is stored in C<$DB::sub>, for the debugger
-to access. Sometimes (such as C<$foo = *bar; undef *bar; &$foo>)
-C<$DB::sub> would be set to a name that could not be used to find the
-subroutine, and so the debugger's attempt to call it would fail. Now the
-check to see whether a reference is needed is more robust, so those
-problems should not happen anymore [rt.cpan.org #69862].
-
-=item *
-
-Every subroutine has a filename associated with it that the debugger uses.
-The one associated with constant subroutines used to be misallocated when
-cloned under threads. Consequently, debugging threaded applications could
-result in memory corruption [perl #96126].
-
-=back
-
-=head2 Dereferencing operators
-
-=over
-
-=item *
-
-C<defined(${"..."})>, C<defined(*{"..."})>, etc., used to
-return true for most, but not all built-in variables, if
-they had not been used yet. This bug affected C<${^GLOBAL_PHASE}> and
-C<${^UTF8CACHE}>, among others. It also used to return false if the
-package name was given as well (C<${"::!"}>) [perl #97978, #97492].
-
-=item *
-
-Perl 5.10.0 introduced a similar bug: C<defined(*{"foo"})> where "foo"
-represents the name of a built-in global variable used to return false if
-the variable had never been used before, but only on the I<first> call.
-This, too, has been fixed.
-
-=item *
-
-Since 5.6.0, C<*{ ... }> has been inconsistent in how it treats undefined
-values. It would die in strict mode or lvalue context for most undefined
-values, but would be treated as the empty string (with a warning) for the
-specific scalar return by C<undef()> (C<&PL_sv_undef> internally). This
-has been corrected. C<undef()> is now treated like other undefined
-scalars, as in Perl 5.005.
-
-=back
-
-=head2 Filehandle, last-accessed
-
-Perl has an internal variable that stores the last filehandle to be
-accessed. It is used by C<$.> and by C<tell> and C<eof> without
-arguments.
-
-=over
-
-=item *
-
-It used to be possible to set this internal variable to a glob copy and
-then modify that glob copy to be something other than a glob, and still
-have the last-accessed filehandle associated with the variable after
-assigning a glob to it again:
-
- my $foo = *STDOUT; # $foo is a glob copy
- <$foo>; # $foo is now the last-accessed handle
- $foo = 3; # no longer a glob
- $foo = *STDERR; # still the last-accessed handle
-
-Now the C<$foo = 3> assignment unsets that internal variable, so there
-is no last-accessed filehandle, just as if C<< <$foo> >> had never
-happened.
-
-This also prevents some unrelated handle from becoming the last-accessed
-handle if $foo falls out of scope and the same internal SV gets used for
-another handle [perl #97988].
-
-=item *
-
-A regression in 5.14 caused these statements not to set that internal
-variable:
-
- my $fh = *STDOUT;
- tell $fh;
- eof $fh;
- seek $fh, 0,0;
- tell *$fh;
- eof *$fh;
- seek *$fh, 0,0;
- readline *$fh;
-
-This is now fixed, but C<tell *{ *$fh }> still has the problem, and it
-is not clear how to fix it [perl #106536].
-
-=back
-
-=head2 Filetests and C<stat>
-
-The term "filetests" refers to the operators that consist of a hyphen
-followed by a single letter: C<-r>, C<-x>, C<-M>, etc. The term "stacked"
-when applied to filetests means followed by another filetest operator
-sharing the same operand, as in C<-r -x -w $fooo>.
-
-=over
-
-=item *
-
-C<stat> produces more consistent warnings. It no longer warns for "_"
-[perl #71002] and no longer skips the warning at times for other unopened
-handles. It no longer warns about an unopened handle when the operating
-system's C<fstat> function fails.
-
-=item *
-
-C<stat> would sometimes return negative numbers for large inode numbers,
-because it was using the wrong internal C type. [perl #84590]
-
-=item *
-
-C<lstat> is documented to fall back to C<stat> (with a warning) when given
-a filehandle. When passed an IO reference, it was actually doing the
-equivalent of S<C<stat _>> and ignoring the handle.
-
-=item *
-
-C<-T _> with no preceding C<stat> used to produce a
-confusing "uninitialized" warning, even though there
-is no visible uninitialized value to speak of.
-
-=item *
-
-C<-T>, C<-B>, C<-l> and C<-t> now work
-when stacked with other filetest operators
-[perl #77388].
-
-=item *
-
-In 5.14.0, filetest ops (C<-r>, C<-x>, etc.) started calling FETCH on a
-tied argument belonging to the previous argument to a list operator, if
-called with a bareword argument or no argument at all. This has been
-fixed, so C<push @foo, $tied, -r> no longer calls FETCH on C<$tied>.
-
-=item *
-
-In Perl 5.6, C<-l> followed by anything other than a bareword would treat
-its argument as a file name. That was changed in 5.8 for glob references
-(C<\*foo>), but not for globs themselves (C<*foo>). C<-l> started
-returning C<undef> for glob references without setting the last
-stat buffer that the "_" handle uses, but only if warnings
-were turned on. With warnings off, it was the same as 5.6.
-In other words, it was simply buggy and inconsistent. Now the 5.6
-behavior has been restored.
-
-=item *
-
-C<-l> followed by a bareword no longer "eats" the previous argument to
-the list operator in whose argument list it resides. Hence,
-C<print "bar", -l foo> now actually prints "bar", because C<-l>
-on longer eats it.
-
-=item *
-
-Perl keeps several internal variables to keep track of the last stat
-buffer, from which file(handle) it originated, what type it was, and
-whether the last stat succeeded.
-
-There were various cases where these could get out of synch, resulting in
-inconsistent or erratic behavior in edge cases (every mention of C<-T>
-applies to C<-B> as well):
-
-=over
-
-=item *
-
-C<-T I<HANDLE>>, even though it does a C<stat>, was not resetting the last
-stat type, so an C<lstat _> following it would merrily return the wrong
-results. Also, it was not setting the success status.
-
-=item *
-
-Freeing the handle last used by C<stat> or a filetest could result in
-S<C<-T _>> using an unrelated handle.
-
-=item *
-
-C<stat> with an IO reference would not reset the stat type or record the
-filehandle for S<C<-T _>> to use.
-
-=item *
-
-Fatal warnings could cause the stat buffer not to be reset
-for a filetest operator on an unopened filehandle or C<-l> on any handle.
-Fatal warnings also stopped C<-T> from setting C<$!>.
-
-=item *
-
-When the last stat was on an unreadable file, C<-T _> is supposed to
-return C<undef>, leaving the last stat buffer unchanged. But it was
-setting the stat type, causing C<lstat _> to stop working.
-
-=item *
-
-C<-T I<FILENAME>> was not resetting the internal stat buffers for
-unreadable files.
-
-=back
-
-These have all been fixed.
-
-=back
-
-=head2 Formats
-
-=over
-
-=item *
-
-Several edge cases have been fixed with formats and C<formline>;
-in particular, where the format itself is potentially variable (such as
-with ties and overloading), and where the format and data differ in their
-encoding. In both these cases, it used to possible for the output to be
-corrupted [perl #91032].
-
-=item *
-
-C<formline> no longer converts its argument into a string in-place. So
-passing a reference to C<formline> no longer destroys the reference
-[perl #79532].
-
-=item *
-
-Assignment to C<$^A> (the format output accumulator) now recalculates
-the number of lines output.
-
-=back
-
-=head2 C<given> and C<when>
-
-=over
-
-=item *
-
-C<given> was not scoping its implicit $_ properly, resulting in memory
-leaks or "Variable is not available" warnings [perl #94682].
-
-=item *
-
-C<given> was not calling set-magic on the implicit lexical C<$_> that it
-uses. This meant, for example, that C<pos> would be remembered from one
-execution of the same C<given> block to the next, even if the input were a
-different variable [perl #84526].
-
-=item *
-
-C<when> blocks are now capable of returning variables declared inside the
-enclosing C<given> block [perl #93548].
-
-=back
-
-=head2 The C<glob> operator
-
-=over
-
-=item *
-
-On OSes other than VMS, Perl's C<glob> operator (and the C<< <...> >> form)
-use L<File::Glob> underneath. L<File::Glob> splits the pattern into words,
-before feeding each word to its C<bsd_glob> function.
-
-There were several inconsistencies in the way the split was done. Now
-quotation marks (' and ") are always treated as shell-style word delimiters
-(that allow whitespace as part of a word) and backslashes are always
-preserved, unless they exist to escape quotation marks. Before, those
-would only sometimes be the case, depending on whether the pattern
-contained whitespace. Also, escaped whitespace at the end of the pattern
-is no longer stripped [perl #40470].
-
-=item *
-
-C<CORE::glob> now works as a way to call the default globbing function. It
-used to respect overrides, despite the C<CORE::> prefix.
-
-=item *
-
-Under miniperl (used to configure modules when perl itself is built),
-C<glob> now clears %ENV before calling csh, since the latter croaks on some
-systems if it does not like the contents of the LS_COLORS environment
-variable [perl #98662].
-
-=back
-
-=head2 Lvalue subroutines
-
-=over
-
-=item *
-
-Explicit return now returns the actual argument passed to return, instead
-of copying it [perl #72724, #72706].
-
-=item *
-
-Lvalue subroutines used to enforce lvalue syntax (i.e., whatever can go on
-the left-hand side of C<=>) for the last statement and the arguments to
-return. Since lvalue subroutines are not always called in lvalue context,
-this restriction has been lifted.
-
-=item *
-
-Lvalue subroutines are less restrictive about what values can be returned.
-It used to croak on values returned by C<shift> and C<delete> and from
-other subroutines, but no longer does so [perl #71172].
-
-=item *
-
-Empty lvalue subroutines (C<sub :lvalue {}>) used to return C<@_> in list
-context. All subroutines used to do this, but regular subs were fixed in
-Perl 5.8.2. Now lvalue subroutines have been likewise fixed.
-
-=item *
-
-Autovivification now works on values returned from lvalue subroutines
-[perl #7946], as does returning C<keys> in lvalue context.
-
-=item *
-
-Lvalue subroutines used to copy their return values in rvalue context. Not
-only was this a waste of CPU cycles, but it also caused bugs. A C<($)>
-prototype would cause an lvalue sub to copy its return value [perl #51408],
-and C<while(lvalue_sub() =~ m/.../g) { ... }> would loop endlessly
-[perl #78680].
-
-=item *
-
-When called in potential lvalue context
-(e.g., subroutine arguments or a list
-passed to C<for>), lvalue subroutines used to copy
-any read-only value that was returned. E.g., C< sub :lvalue { $] } >
-would not return C<$]>, but a copy of it.
-
-=item *
-
-When called in potential lvalue context, an lvalue subroutine returning
-arrays or hashes used to bind the arrays or hashes to scalar variables,
-resulting in bugs. This was fixed in 5.14.0 if an array were the first
-thing returned from the subroutine (but not for C<$scalar, @array> or
-hashes being returned). Now a more general fix has been applied
-[perl #23790].
-
-=item *
-
-Method calls whose arguments were all surrounded with C<my()> or C<our()>
-(as in C<< $object->method(my($a,$b)) >>) used to force lvalue context on
-the subroutine. This would prevent lvalue methods from returning certain
-values.
-
-=item *
-
-Lvalue sub calls that are not determined to be such at compile time
-(C<&$name> or &{"name"}) are no longer exempt from strict refs if they
-occur in the last statement of an lvalue subroutine [perl #102486].
-
-=item *
-
-Sub calls whose subs are not visible at compile time, if
-they occurred in the last statement of an lvalue subroutine,
-would reject non-lvalue subroutines and die with "Can't modify non-lvalue
-subroutine call" [perl #102486].
-
-Non-lvalue sub calls whose subs I<are> visible at compile time exhibited
-the opposite bug. If the call occurred in the last statement of an lvalue
-subroutine, there would be no error when the lvalue sub was called in
-lvalue context. Perl would blindly assign to the temporary value returned
-by the non-lvalue subroutine.
-
-=item *
-
-C<AUTOLOAD> routines used to take precedence over the actual sub being
-called (i.e., when autoloading wasn't needed), for sub calls in lvalue or
-potential lvalue context, if the subroutine was not visible at compile
-time.
-
-=item *
-
-Applying the C<:lvalue> attribute to an XSUB or to an aliased subroutine
-stub with C<< sub foo :lvalue; >> syntax stopped working in Perl 5.12.
-This has been fixed.
-
-=item *
-
-Applying the :lvalue attribute to subroutine that is already defined does
-not work properly, as the attribute changes the way the sub is compiled.
-Hence, Perl 5.12 began warning when an attempt is made to apply the
-attribute to an already defined sub. In such cases, the attribute is
-discarded.
-
-But the change in 5.12 missed the case where custom attributes are also
-present: that case still silently and ineffectively applied the attribute.
-That omission has now been corrected. C<sub foo :lvalue :Whatever> (when
-C<foo> is already defined) now warns about the :lvalue attribute, and does
-not apply it.
-
-=item *
-
-A bug affecting lvalue context propagation through nested lvalue subroutine
-calls has been fixed. Previously, returning a value in nested rvalue
-context would be treated as lvalue context by the inner subroutine call,
-resulting in some values (such as read-only values) being rejected.
-
-=back
-
-=head2 Overloading
-
-=over
-
-=item *
-
-Arithmetic assignment (C<$left += $right>) involving overloaded objects
-that rely on the 'nomethod' override no longer segfault when the left
-operand is not overloaded.
-
-=item *
-
-Errors that occur when methods cannot be found during overloading now
-mention the correct package name, as they did in 5.8.x, instead of
-erroneously mentioning the "overload" package, as they have since 5.10.0.
-
-=item *
-
-Undefining C<%overload::> no longer causes a crash.
-
-=back
-
-=head2 Prototypes of built-in keywords
-
-=over
-
-=item *
-
-The C<prototype> function no longer dies for the C<__FILE__>, C<__LINE__>
-and C<__PACKAGE__> directives. It now returns an empty-string prototype
-for them, because they are syntactically indistinguishable from nullary
-functions like C<time>.
-
-=item *
-
-C<prototype> now returns C<undef> for all overridable infix operators,
-such as C<eq>, which are not callable in any way resembling functions.
-It used to return incorrect prototypes for some and die for others
-[perl #94984].
-
-=item *
-
-The prototypes of several built-in functions--C<getprotobynumber>, C<lock>,
-C<not> and C<select>--have been corrected, or at least are now closer to
-reality than before.
-
-=back
-
-=head2 Regular expressions
-
-=for comment Is it possible to merge some of these items?
-
-=over 4
-
-=item *
-
-C</[[:ascii:]]/> and C</[[:blank:]]/> now use locale rules under
-C<use locale> when the platform supports that. Previously, they used
-the platform's native character set.
-
-=item *
-
-C<m/[[:ascii:]]/i> and C</\p{ASCII}/i> now match identically (when not
-under a differing locale). This fixes a regression introduced in 5.14
-in which the first expression could match characters outside of ASCII,
-such as the KELVIN SIGN.
-
-=item *
-
-C</.*/g> would sometimes refuse to match at the end of a string that ends
-with "\n". This has been fixed [perl #109206].
-
-=item *
-
-Starting with 5.12.0, Perl used to get its internal bookkeeping muddled up
-after assigning C<${ qr// }> to a hash element and locking it with
-L<Hash::Util>. This could result in double frees, crashes, or erratic
-behavior.
-
-=item *
-
-The new (in 5.14.0) regular expression modifier C</a> when repeated like
-C</aa> forbids the characters outside the ASCII range that match
-characters inside that range from matching under C</i>. This did not
-work under some circumstances, all involving alternation, such as:
-
- "\N{KELVIN SIGN}" =~ /k|foo/iaa;
-
-succeeded inappropriately. This is now fixed.
-
-=item *
-
-5.14.0 introduced some memory leaks in regular expression character
-classes such as C<[\w\s]>, which have now been fixed. (5.14.1)
-
-=item *
-
-An edge case in regular expression matching could potentially loop.
-This happened only under C</i> in bracketed character classes that have
-characters with multi-character folds, and the target string to match
-against includes the first portion of the fold, followed by another
-character that has a multi-character fold that begins with the remaining
-portion of the fold, plus some more.
-
- "s\N{U+DF}" =~ /[\x{DF}foo]/i
-
-is one such case. C<\xDF> folds to C<"ss">. (5.14.1)
-
-=item *
-
-A few characters in regular expression pattern matches did not
-match correctly in some circumstances, all involving C</i>. The
-affected characters are:
-COMBINING GREEK YPOGEGRAMMENI,
-GREEK CAPITAL LETTER IOTA,
-GREEK CAPITAL LETTER UPSILON,
-GREEK PROSGEGRAMMENI,
-GREEK SMALL LETTER IOTA WITH DIALYTIKA AND OXIA,
-GREEK SMALL LETTER IOTA WITH DIALYTIKA AND TONOS,
-GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND OXIA,
-GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND TONOS,
-LATIN SMALL LETTER LONG S,
-LATIN SMALL LIGATURE LONG S T,
-and
-LATIN SMALL LIGATURE ST.
-
-=item *
-
-A memory leak regression in regular expression compilation
-under threading has been fixed.
-
-=item *
-
-A regression introduced in 5.14.0 has
-been fixed. This involved an inverted
-bracketed character class in a regular expression that consisted solely
-of a Unicode property. That property wasn't getting inverted outside the
-Latin1 range.
-
-=item *
-
-Three problematic Unicode characters now work better in regex pattern matching under C</i>.
-
-In the past, three Unicode characters:
-LATIN SMALL LETTER SHARP S,
-GREEK SMALL LETTER IOTA WITH DIALYTIKA AND TONOS,
-and
-GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND TONOS,
-along with the sequences that they fold to
-(including "ss" for LATIN SMALL LETTER SHARP S),
-did not properly match under C</i>. 5.14.0 fixed some of these cases,
-but introduced others, including a panic when one of the characters or
-sequences was used in the C<(?(DEFINE)> regular expression predicate.
-The known bugs that were introduced in 5.14 have now been fixed; as well
-as some other edge cases that have never worked until now. These all
-involve using the characters and sequences outside bracketed character
-classes under C</i>. This closes [perl #98546].
-
-There remain known problems when using certain characters with
-multi-character folds inside bracketed character classes, including such
-constructs as C<qr/[\N{LATIN SMALL LETTER SHARP}a-z]/i>. These
-remaining bugs are addressed in [perl #89774].
-
-=item *
-
-RT #78266: The regex engine has been leaking memory when accessing
-named captures that weren't matched as part of a regex ever since 5.10
-when they were introduced; e.g., this would consume over a hundred MB of
-memory:
-
- for (1..10_000_000) {
- if ("foo" =~ /(foo|(?<capture>bar))?/) {
- my $capture = $+{capture}
- }
- }
- system "ps -o rss $$"'
-
-=item *
-
-In 5.14, C</[[:lower:]]/i> and C</[[:upper:]]/i> no longer matched the
-opposite case. This has been fixed [perl #101970].
-
-=item *
-
-A regular expression match with an overloaded object on the right-hand side
-would sometimes stringify the object too many times.
-
-=item *
-
-A regression has been fixed that was introduced in 5.14, in C</i>
-regular expression matching, in which a match improperly fails if the
-pattern is in UTF-8, the target string is not, and a Latin-1 character
-precedes a character in the string that should match the pattern.
-[perl #101710]
-
-=item *
-
-In case-insensitive regular expression pattern matching, no longer on
-UTF-8 encoded strings does the scan for the start of match look only at
-the first possible position. This caused matches such as
-C<"f\x{FB00}" =~ /ff/i> to fail.
-
-=item *
-
-The regexp optimizer no longer crashes on debugging builds when merging
-fixed-string nodes with inconvenient contents.
-
-=item *
-
-A panic involving the combination of the regular expression modifiers
-C</aa> and the C<\b> escape sequence introduced in 5.14.0 has been
-fixed [perl #95964]. (5.14.2)
-
-=item *
-
-The combination of the regular expression modifiers C</aa> and the C<\b>
-and C<\B> escape sequences did not work properly on UTF-8 encoded
-strings. All non-ASCII characters under C</aa> should be treated as
-non-word characters, but what was happening was that Unicode rules were
-used to determine wordness/non-wordness for non-ASCII characters. This
-is now fixed [perl #95968].
-
-=item *
-
-C<< (?foo: ...) >> no longer loses passed in character set.
-
-=item *
-
-The trie optimization used to have problems with alternations containing
-an empty C<(?:)>, causing C<< "x" =~ /\A(?>(?:(?:)A|B|C?x))\z/ >> not to
-match, whereas it should [perl #111842].
-
-=item *
-
-Use of lexical (C<my>) variables in code blocks embedded in regular
-expressions will no longer result in memory corruption or crashes.
-
-Nevertheless, these code blocks are still experimental, as there are still
-problems with the wrong variables being closed over (in loops for instance)
-and with abnormal exiting (e.g., C<die>) causing memory corruption.
-
-=item *
-
-The C<\h>, C<\H>, C<\v> and C<\V> regular expression metacharacters used to
-cause a panic error message when trying to match at the end of the
-string [perl #96354].
-
-=item *
-
-The abbreviations for four C1 control characters C<MW> C<PM>, C<RI>, and
-C<ST> were previously unrecognized by C<\N{}>, vianame(), and
-string_vianame().
-
-=item *
-
-Mentioning a variable named "&" other than C<$&> (i.e., C<@&> or C<%&>) no
-longer stops C<$&> from working. The same applies to variables named "'"
-and "`" [perl #24237].
-
-=item *
-
-Creating a C<UNIVERSAL::AUTOLOAD> sub no longer stops C<%+>, C<%-> and
-C<%!> from working some of the time [perl #105024].
-
-=back
-
-=head2 Smartmatching
-
-=over
-
-=item *
-
-C<~~> now correctly handles the precedence of Any~~Object, and is not tricked
-by an overloaded object on the left-hand side.
-
-=item *
-
-In Perl 5.14.0, C<$tainted ~~ @array> stopped working properly. Sometimes
-it would erroneously fail (when C<$tainted> contained a string that occurs
-in the array I<after> the first element) or erroneously succeed (when
-C<undef> occurred after the first element) [perl #93590].
-
-=back
-
-=head2 The C<sort> operator
-
-=over
-
-=item *
-
-C<sort> was not treating C<sub {}> and C<sub {()}> as equivalent when
-such a sub was provided as the comparison routine. It used to croak on
-C<sub {()}>.
-
-=item *
-
-C<sort> now works once more with custom sort routines that are XSUBs. It
-stopped working in 5.10.0.
-
-=item *
-
-C<sort> with a constant for a custom sort routine, although it produces
-unsorted results, no longer crashes. It started crashing in 5.10.0.
-
-=item *
-
-Warnings emitted by C<sort> when a custom comparison routine returns a
-non-numeric value now contain "in sort" and show the line number of the
-C<sort> operator, rather than the last line of the comparison routine. The
-warnings also now occur only if warnings are enabled in the scope where
-C<sort> occurs. Previously the warnings would occur if enabled in the
-comparison routine's scope.
-
-=item *
-
-C<< sort { $a <=> $b } >>, which is optimized internally, now produces
-"uninitialized" warnings for NaNs (not-a-number values), since C<< <=> >>
-returns C<undef> for those. This brings it in line with
-S<C<< sort { 1; $a <=> $b } >>> and other more complex cases, which are not
-optimized [perl #94390].
-
-=back
-
-=head2 The C<substr> operator
-
-=over
-
-=item *
-
-Tied (and otherwise magical) variables are no longer exempt from the
-"Attempt to use reference as lvalue in substr" warning.
-
-=item *
-
-That warning now occurs when the returned lvalue is assigned to, not
-when C<substr> itself is called. This makes a difference only if the
-return value of C<substr> is referenced and later assigned to.
-
-=item *
-
-Passing a substring of a read-only value or a typeglob to a function
-(potential lvalue context) no longer causes an immediate "Can't coerce"
-or "Modification of a read-only value" error. That error occurs only
-if the passed value is assigned to.
-
-The same thing happens with the "substr outside of string" error. If
-the lvalue is only read from, not written to, it is now just a warning, as
-with rvalue C<substr>.
-
-=item *
-
-C<substr> assignments no longer call FETCH twice if the first argument
-is a tied variable, just once.
-
-=back
-
-=head2 Support for embedded nulls
-
-Some parts of Perl did not work correctly with nulls (C<chr 0>) embedded in
-strings. That meant that, for instance, C<< $m = "a\0b"; foo->$m >> would
-call the "a" method, instead of the actual method name contained in $m.
-These parts of perl have been fixed to support nulls:
-
-=over
-
-=item *
-
-Method names
-
-=item *
-
-Typeglob names (including filehandle and subroutine names)
-
-=item *
-
-Package names, including the return value of C<ref()>
-
-=item *
-
-Typeglob elements (C<*foo{"THING\0stuff"}>)
-
-=item *
-
-Signal names
-
-=item *
-
-Various warnings and error messages that mention variable names or values,
-methods, etc.
-
-=back
-
-One side effect of these changes is that blessing into "\0" no longer
-causes C<ref()> to return false.
-
-=head2 Threading bugs
-
-=over
-
-=item *
-
-Typeglobs returned from threads are no longer cloned if the parent thread
-already has a glob with the same name. This means that returned
-subroutines will now assign to the right package variables [perl #107366].
-
-=item *
-
-Some cases of threads crashing due to memory allocation during cloning have
-been fixed [perl #90006].
-
-=item *
-
-Thread joining would sometimes emit "Attempt to free unreferenced scalar"
-warnings if C<caller> had been used from the C<DB> package before thread
-creation [perl #98092].
-
-=item *
-
-Locking a subroutine (via C<lock &sub>) is no longer a compile-time error
-for regular subs. For lvalue subroutines, it no longer tries to return the
-sub as a scalar, resulting in strange side effects like C<ref \$_>
-returning "CODE" in some instances.
-
-C<lock &sub> is now a run-time error if L<threads::shared> is loaded (a
-no-op otherwise), but that may be rectified in a future version.
-
-=back
-
-=head2 Tied variables
-
-=over
-
-=item *
-
-Various cases in which FETCH was being ignored or called too many times
-have been fixed:
-
-=over
-
-=item *
-
-C<PerlIO::get_layers> [perl #97956]
-
-=item *
-
-C<$tied =~ y/a/b/>, C<chop $tied> and C<chomp $tied> when $tied holds a
-reference.
-
-=item *
-
-When calling C<local $_> [perl #105912]
-
-=item *
-
-Four-argument C<select>
-
-=item *
-
-A tied buffer passed to C<sysread>
-
-=item *
-
-C<< $tied .= <> >>
-
-=item *
-
-Three-argument C<open>, the third being a tied file handle
-(as in C<< open $fh, ">&", $tied >>)
-
-=item *
-
-C<sort> with a reference to a tied glob for the comparison routine.
-
-=item *
-
-C<..> and C<...> in list context [perl #53554].
-
-=item *
-
-C<${$tied}>, C<@{$tied}>, C<%{$tied}> and C<*{$tied}> where the tied
-variable returns a string (C<&{}> was unaffected)
-
-=item *
-
-C<defined ${ $tied_variable }>
-
-=item *
-
-Various functions that take a filehandle argument in rvalue context
-(C<close>, C<readline>, etc.) [perl #97482]
-
-=item *
-
-Some cases of dereferencing a complex expression, such as
-C<${ (), $tied } = 1>, used to call C<FETCH> multiple times, but now call
-it once.
-
-=item *
-
-C<$tied-E<gt>method> where $tied returns a package name--even resulting in
-a failure to call the method, due to memory corruption
-
-=item *
-
-Assignments like C<*$tied = \&{"..."}> and C<*glob = $tied>
-
-=item *
-
-C<chdir>, C<chmod>, C<chown>, C<utime>, C<truncate>, C<stat>, C<lstat> and
-the filetest ops (C<-r>, C<-x>, etc.)
-
-=back
-
-=item *
-
-C<caller> sets C<@DB::args> to the subroutine arguments when called from
-the DB package. It used to crash when doing so if C<@DB::args> happened to
-be tied. Now it croaks instead.
-
-=item *
-
-Tying an element of %ENV or C<%^H> and then deleting that element would
-result in a call to the tie object's DELETE method, even though tying the
-element itself is supposed to be equivalent to tying a scalar (the element
-is, of course, a scalar) [perl #67490].
-
-=item *
-
-When Perl autovivifies an element of a tied array or hash (which entails
-calling STORE with a new reference), it now calls FETCH immediately after
-the STORE, instead of assuming that FETCH would have returned the same
-reference. This can make it easier to implement tied objects [perl #35865, #43011].
-
-=item *
-
-Four-argument C<select> no longer produces its "Non-string passed as
-bitmask" warning on tied or tainted variables that are strings.
-
-=item *
-
-Localizing a tied scalar that returns a typeglob no longer stops it from
-being tied till the end of the scope.
-
-=item *
-
-Attempting to C<goto> out of a tied handle method used to cause memory
-corruption or crashes. Now it produces an error message instead
-[perl #8611].
-
-=item *
-
-A bug has been fixed that occurs when a tied variable is used as a
-subroutine reference: if the last thing assigned to or returned from the
-variable was a reference or typeglob, the C<\&$tied> could either crash or
-return the wrong subroutine. The reference case is a regression introduced
-in Perl 5.10.0. For typeglobs, it has probably never worked till now.
-
-=back
-
-=head2 Version objects and vstrings
-
-=over
-
-=item *
-
-The bitwise complement operator (and possibly other operators, too) when
-passed a vstring would leave vstring magic attached to the return value,
-even though the string had changed. This meant that
-C<< version->new(~v1.2.3) >> would create a version looking like "v1.2.3"
-even though the string passed to C<< version->new >> was actually
-"\376\375\374". This also caused L<B::Deparse> to deparse C<~v1.2.3>
-incorrectly, without the C<~> [perl #29070].
-
-=item *
-
-Assigning a vstring to a magic (e.g., tied, C<$!>) variable and then
-assigning something else used to blow away all magic. This meant that
-tied variables would come undone, C<$!> would stop getting updated on
-failed system calls, C<$|> would stop setting autoflush, and other
-mischief would take place. This has been fixed.
-
-=item *
-
-C<< version->new("version") >> and C<printf "%vd", "version"> no longer
-crash [perl #102586].
-
-=item *
-
-Version comparisons, such as those that happen implicitly with C<use
-v5.43>, no longer cause locale settings to change [perl #105784].
-
-=item *
-
-Version objects no longer cause memory leaks in boolean context
-[perl #109762].
-
-=back
-
-=head2 Warnings, redefinition
-
-=over
-
-=item *
-
-Subroutines from the C<autouse> namespace are once more exempt from
-redefinition warnings. This used to work in 5.005, but was broken in
-5.6 for most subroutines. For subs created via XS that redefine
-subroutines from the C<autouse> package, this stopped working in 5.10.
-
-=item *
-
-New XSUBs now produce redefinition warnings if they overwrite existing
-subs, as they did in 5.8.x. (The C<autouse> logic was reversed in
-5.10-14. Only subroutines from the C<autouse> namespace would warn
-when clobbered.)
-
-=item *
-
-C<newCONSTSUB> used to use compile-time warning hints, instead of
-run-time hints. The following code should never produce a redefinition
-warning, but it used to, if C<newCONSTSUB> redefined an existing
-subroutine:
-
- use warnings;
- BEGIN {
- no warnings;
- some_XS_function_that_calls_new_CONSTSUB();
- }
-
-=item *
-
-Redefinition warnings for constant subroutines are on by default (what
-are known as severe warnings in L<perldiag>). This occurred only
-when it was a glob assignment or declaration of a Perl subroutine that
-caused the warning. If the creation of XSUBs triggered the warning, it
-was not a default warning. This has been corrected.
-
-=item *
-
-The internal check to see whether a redefinition warning should occur
-used to emit "uninitialized" warnings in cases like this:
-
- use warnings "uninitialized";
- use constant {u => undef, v => undef};
- sub foo(){u}
- sub foo(){v}
-
-=back
-
-=head2 Warnings, "Uninitialized"
-
-=over
-
-=item *
-
-Various functions that take a filehandle argument in rvalue context
-(C<close>, C<readline>, etc.) used to warn twice for an undefined handle
-[perl #97482].
-
-=item *
-
-C<dbmopen> now only warns once, rather than three times, if the mode
-argument is C<undef> [perl #90064].
-
-=item *
-
-The C<+=> operator does not usually warn when the left-hand side is
-C<undef>, but it was doing so for tied variables. This has been fixed
-[perl #44895].
-
-=item *
-
-A bug fix in Perl 5.14 introduced a new bug, causing "uninitialized"
-warnings to report the wrong variable if the operator in question had
-two operands and one was C<%{...}> or C<@{...}>. This has been fixed
-[perl #103766].
-
-=item *
-
-C<..> and C<...> in list context now mention the name of the variable in
-"uninitialized" warnings for string (as opposed to numeric) ranges.
-
-=back
-
-=head2 Weak references
-
-=over
-
-=item *
-
-Weakening the first argument to an automatically-invoked C<DESTROY> method
-could result in erroneous "DESTROY created new reference" errors or
-crashes. Now it is an error to weaken a read-only reference.
-
-=item *
-
-Weak references to lexical hashes going out of scope were not going stale
-(becoming undefined), but continued to point to the hash.
-
-=item *
-
-Weak references to lexical variables going out of scope are now broken
-before any magical methods (e.g., DESTROY on a tie object) are called.
-This prevents such methods from modifying the variable that will be seen
-the next time the scope is entered.
-
-=item *
-
-Creating a weak reference to an @ISA array or accessing the array index
-(C<$#ISA>) could result in confused internal bookkeeping for elements
-later added to the @ISA array. For instance, creating a weak
-reference to the element itself could push that weak reference on to @ISA;
-and elements added after use of C<$#ISA> would be ignored by method lookup
-[perl #85670].
-
-=back
-
-=head2 Other notable fixes
-
-=over
-
-=item *
-
-C<quotemeta> now quotes consistently the same non-ASCII characters under
-C<use feature 'unicode_strings'>, regardless of whether the string is
-encoded in UTF-8 or not, hence fixing the last vestiges (we hope) of the
-notorious L<perlunicode/The "Unicode Bug">. [perl #77654].
-
-Which of these code points is quoted has changed, based on Unicode's
-recommendations. See L<perlfunc/quotemeta> for details.
-
-=item *
-
-C<study> is now a no-op, presumably fixing all outstanding bugs related to
-study causing regex matches to behave incorrectly!
-
-=item *
-
-When one writes C<open foo || die>, which used to work in Perl 4, a
-"Precedence problem" warning is produced. This warning used erroneously to
-apply to fully-qualified bareword handle names not followed by C<||>. This
-has been corrected.
-
-=item *
-
-After package aliasing (C<*foo:: = *bar::>), C<select> with 0 or 1 argument
-would sometimes return a name that could not be used to refer to the
-filehandle, or sometimes it would return C<undef> even when a filehandle
-was selected. Now it returns a typeglob reference in such cases.
-
-=item *
-
-C<PerlIO::get_layers> no longer ignores some arguments that it thinks are
-numeric, while treating others as filehandle names. It is now consistent
-for flat scalars (i.e., not references).
-
-=item *
-
-Unrecognized switches on C<#!> line
-
-If a switch, such as B<-x>, that cannot occur on the C<#!> line is used
-there, perl dies with "Can't emulate...".
-
-It used to produce the same message for switches that perl did not
-recognize at all, whether on the command line or the C<#!> line.
-
-Now it produces the "Unrecognized switch" error message [perl #104288].
-
-=item *
-
-C<system> now temporarily blocks the SIGCHLD signal handler, to prevent the
-signal handler from stealing the exit status [perl #105700].
-
-=item *
-
-The %n formatting code for C<printf> and C<sprintf>, which causes the number
-of characters to be assigned to the next argument, now actually
-assigns the number of characters, instead of the number of bytes.
-
-It also works now with special lvalue functions like C<substr> and with
-nonexistent hash and array elements [perl #3471, #103492].
-
-=item *
-
-Perl skips copying values returned from a subroutine, for the sake of
-speed, if doing so would make no observable difference. Because of faulty
-logic, this would happen with the
-result of C<delete>, C<shift> or C<splice>, even if the result was
-referenced elsewhere. It also did so with tied variables about to be freed
-[perl #91844, #95548].
-
-=item *
-
-C<utf8::decode> now refuses to modify read-only scalars [perl #91850].
-
-=item *
-
-Freeing $_ inside a C<grep> or C<map> block, a code block embedded in a
-regular expression, or an @INC filter (a subroutine returned by a
-subroutine in @INC) used to result in double frees or crashes
-[perl #91880, #92254, #92256].
-
-=item *
-
-C<eval> returns C<undef> in scalar context or an empty list in list
-context when there is a run-time error. When C<eval> was passed a
-string in list context and a syntax error occurred, it used to return a
-list containing a single undefined element. Now it returns an empty
-list in list context for all errors [perl #80630].
-
-=item *
-
-C<goto &func> no longer crashes, but produces an error message, when
-the unwinding of the current subroutine's scope fires a destructor that
-undefines the subroutine being "goneto" [perl #99850].
-
-=item *
-
-Perl now holds an extra reference count on the package that code is
-currently compiling in. This means that the following code no longer
-crashes [perl #101486]:
-
- package Foo;
- BEGIN {*Foo:: = *Bar::}
- sub foo;
-
-=item *
-
-The C<x> repetition operator no longer crashes on 64-bit builds with large
-repeat counts [perl #94560].
-
-=item *
-
-Calling C<require> on an implicit C<$_> when C<*CORE::GLOBAL::require> has
-been overridden does not segfault anymore, and C<$_> is now passed to the
-overriding subroutine [perl #78260].
-
-=item *
-
-C<use> and C<require> are no longer affected by the I/O layers active in
-the caller's scope (enabled by L<open.pm|open>) [perl #96008].
-
-=item *
-
-C<our $::é; $é> (which is invalid) no longer produces the "Compilation
-error at lib/utf8_heavy.pl..." error message, which it started emitting in
-5.10.0 [perl #99984].
-
-=item *
-
-On 64-bit systems, C<read()> now understands large string offsets beyond
-the 32-bit range.
-
-=item *
-
-Errors that occur when processing subroutine attributes no longer cause the
-subroutine's op tree to leak.
-
-=item *
-
-Passing the same constant subroutine to both C<index> and C<formline> no
-longer causes one or the other to fail [perl #89218]. (5.14.1)
-
-=item *
-
-List assignment to lexical variables declared with attributes in the same
-statement (C<my ($x,@y) : blimp = (72,94)>) stopped working in Perl 5.8.0.
-It has now been fixed.
-
-=item *
-
-Perl 5.10.0 introduced some faulty logic that made "U*" in the middle of
-a pack template equivalent to "U0" if the input string was empty. This has
-been fixed [perl #90160]. (5.14.2)
-
-=item *
-
-Destructors on objects were not called during global destruction on objects
-that were not referenced by any scalars. This could happen if an array
-element were blessed (e.g., C<bless \$a[0]>) or if a closure referenced a
-blessed variable (C<bless \my @a; sub foo { @a }>).
-
-Now there is an extra pass during global destruction to fire destructors on
-any objects that might be left after the usual passes that check for
-objects referenced by scalars [perl #36347].
-
-=item *
-
-Fixed a case where it was possible that a freed buffer may have been read
-from when parsing a here document [perl #90128]. (5.14.1)
-
-=item *
-
-C<each(I<ARRAY>)> is now wrapped in C<defined(...)>, like C<each(I<HASH>)>,
-inside a C<while> condition [perl #90888].
-
-=item *
-
-A problem with context propagation when a C<do> block is an argument to
-C<return> has been fixed. It used to cause C<undef> to be returned in
-certain cases of a C<return> inside an C<if> block which itself is followed by
-another C<return>.
-
-=item *
-
-Calling C<index> with a tainted constant no longer causes constants in
-subsequently compiled code to become tainted [perl #64804].
-
-=item *
-
-Infinite loops like C<1 while 1> used to stop C<strict 'subs'> mode from
-working for the rest of the block.
-
-=item *
-
-For list assignments like C<($a,$b) = ($b,$a)>, Perl has to make a copy of
-the items on the right-hand side before assignment them to the left. For
-efficiency's sake, it assigns the values on the right straight to the items
-on the left if no one variable is mentioned on both sides, as in C<($a,$b) =
-($c,$d)>. The logic for determining when it can cheat was faulty, in that
-C<&&> and C<||> on the right-hand side could fool it. So C<($a,$b) =
-$some_true_value && ($b,$a)> would end up assigning the value of C<$b> to
-both scalars.
-
-=item *
-
-Perl no longer tries to apply lvalue context to the string in
-C<("string", $variable) ||= 1> (which used to be an error). Since the
-left-hand side of C<||=> is evaluated in scalar context, that's a scalar
-comma operator, which gives all but the last item void context. There is
-no such thing as void lvalue context, so it was a mistake for Perl to try
-to force it [perl #96942].
-
-=item *
-
-C<caller> no longer leaks memory when called from the DB package if
-C<@DB::args> was assigned to after the first call to C<caller>. L<Carp>
-was triggering this bug [perl #97010]. (5.14.2)
-
-=item *
-
-C<close> and similar filehandle functions, when called on built-in global
-variables (like C<$+>), used to die if the variable happened to hold the
-undefined value, instead of producing the usual "Use of uninitialized
-value" warning.
-
-=item *
-
-When autovivified file handles were introduced in Perl 5.6.0, C<readline>
-was inadvertently made to autovivify when called as C<readline($foo)> (but
-not as C<E<lt>$fooE<gt>>). It has now been fixed never to autovivify.
-
-=item *
-
-Calling an undefined anonymous subroutine (e.g., what $x holds after
-C<undef &{$x = sub{}}>) used to cause a "Not a CODE reference" error, which
-has been corrected to "Undefined subroutine called" [perl #71154].
-
-=item *
-
-Causing C<@DB::args> to be freed between uses of C<caller> no longer
-results in a crash [perl #93320].
-
-=item *
-
-C<setpgrp($foo)> used to be equivalent to C<($foo, setpgrp)>, because
-C<setpgrp> was ignoring its argument if there was just one. Now it is
-equivalent to C<setpgrp($foo,0)>.
-
-=item *
-
-C<shmread> was not setting the scalar flags correctly when reading from
-shared memory, causing the existing cached numeric representation in the
-scalar to persist [perl #98480].
-
-=item *
-
-C<++> and C<--> now work on copies of globs, instead of dying.
-
-=item *
-
-C<splice()> doesn't warn when truncating
-
-You can now limit the size of an array using C<splice(@a,MAX_LEN)> without
-worrying about warnings.
-
-=item *
-
-C<< $$ >> is no longer tainted. Since this value comes directly from
-C<< getpid() >>, it is always safe.
-
-=item *
-
-The parser no longer leaks a filehandle if STDIN was closed before parsing
-started [perl #37033].
-
-=item *
-
-C<< die; >> with a non-reference, non-string, or magical (e.g., tainted)
-value in $@ now properly propagates that value [perl #111654].
-
-=back
-
-=head1 Known Problems
-
-=over 4
-
-=item *
-
-On Solaris, we have two kinds of failure.
-
-If F<make> is Sun's F<make>, we get an error about a badly formed macro
-assignment in the F<Makefile>. That happens when F<./Configure> tries to
-make depends. F<Configure> then exits 0, but further F<make>-ing fails.
-
-If F<make> is F<gmake>, F<Configure> completes, then we get errors related
-to F</usr/include/stdbool.h>
-
-=item *
-
-On Win32, a number of tests hang unless STDERR is redirected. The cause of
-this is still under investigation.
-
-=item *
-
-When building as root with a umask that prevents files from being
-other-readable, F<t/op/filetest.t> will fail. This is a test bug, not a
-bug in perl's behavior.
-
-=item *
-
-Configuring with a recent gcc and link-time-optimization, such as
-C<Configure -Doptimize='-O2 -flto'> fails
-because the optimizer optimizes away some of Configure's tests. A
-workaround is to omit the C<-flto> flag when running Configure, but add
-it back in while actually building, something like
-
- sh Configure -Doptimize=-O2
- make OPTIMIZE='-O2 -flto'
-
-=item *
-
-The following CPAN modules have test failures with perl 5.16. Patches have
-been submitted for all of these, so hopefully there will be new releases
-soon:
-
-=over
-
-=item *
-
-L<Date::Pcalc> version 6.1
-
-=item *
-
-L<Module::CPANTS::Analyse> version 0.85
-
-This fails due to problems in L<Module::Find> 0.10 and L<File::MMagic>
-1.27.
-
-=item *
-
-L<PerlIO::Util> version 0.72
-
-=back
-
-=back
-
-=head1 Acknowledgements
-
-Perl 5.16.0 represents approximately 12 months of development since Perl
-5.14.0 and contains approximately 590,000 lines of changes across 2,500
-files from 139 authors.
-
-Perl continues to flourish into its third decade thanks to a vibrant
-community of users and developers. The following people are known to
-have contributed the improvements that became Perl 5.16.0:
-
-Aaron Crane, Abhijit Menon-Sen, Abigail, Alan Haggai Alavi, Alberto
-Simões, Alexandr Ciornii, Andreas König, Andy Dougherty, Aristotle
-Pagaltzis, Bo Johansson, Bo Lindbergh, Breno G. de Oliveira, brian d
-foy, Brian Fraser, Brian Greenfield, Carl Hayter, Chas. Owens,
-Chia-liang Kao, Chip Salzenberg, Chris 'BinGOs' Williams, Christian
-Hansen, Christopher J. Madsen, chromatic, Claes Jacobsson, Claudio
-Ramirez, Craig A. Berry, Damian Conway, Daniel Kahn Gillmor, Darin
-McBride, Dave Rolsky, David Cantrell, David Golden, David Leadbeater,
-David Mitchell, Dee Newcum, Dennis Kaarsemaker, Dominic Hargreaves,
-Douglas Christopher Wilson, Eric Brine, Father Chrysostomos, Florian
-Ragwitz, Frederic Briere, George Greer, Gerard Goossen, Gisle Aas,
-H.Merijn Brand, Hojung Youn, Ian Goodacre, James E Keenan, Jan Dubois,
-Jerry D. Hedden, Jesse Luehrs, Jesse Vincent, Jilles Tjoelker, Jim
-Cromie, Jim Meyering, Joel Berger, Johan Vromans, Johannes Plunien, John
-Hawkinson, John P. Linderman, John Peacock, Joshua ben Jore, Juerd
-Waalboer, Karl Williamson, Karthik Rajagopalan, Keith Thompson, Kevin J.
-Woolley, Kevin Ryde, Laurent Dami, Leo Lapworth, Leon Brocard, Leon
-Timmermans, Louis Strous, Lukas Mai, Marc Green, Marcel Grünauer, Mark
-A. Stratman, Mark Dootson, Mark Jason Dominus, Martin Hasch, Matthew
-Horsfall, Max Maischein, Michael G Schwern, Michael Witten, Mike
-Sheldrake, Moritz Lenz, Nicholas Clark, Niko Tyni, Nuno Carvalho, Pau
-Amma, Paul Evans, Paul Green, Paul Johnson, Perlover, Peter John Acklam,
-Peter Martini, Peter Scott, Phil Monsen, Pino Toscano, Rafael
-Garcia-Suarez, Rainer Tammer, Reini Urban, Ricardo Signes, Robin Barker,
-Rodolfo Carvalho, Salvador Fandiño, Sam Kimbrel, Samuel Thibault, Shawn
-M Moore, Shigeya Suzuki, Shirakata Kentaro, Shlomi Fish, Sisyphus,
-Slaven Rezic, Spiros Denaxas, Steffen Müller, Steffen Schwigon, Stephen
-Bennett, Stephen Oberholtzer, Stevan Little, Steve Hay, Steve Peters,
-Thomas Sibley, Thorsten Glaser, Timothe Litt, Todd Rinaldo, Tom
-Christiansen, Tom Hukins, Tony Cook, Vadim Konovalov, Vincent Pit,
-Vladimir Timofeev, Walt Mankowski, Yves Orton, Zefram, Zsbán Ambrus,
-Ævar Arnfjörð Bjarmason.
-
-The list above is almost certainly incomplete as it is automatically
-generated from version control history. In particular, it does not
-include the names of the (very much appreciated) contributors who
-reported issues to the Perl bug tracker.
-
-Many of the changes included in this version originated in the CPAN
-modules included in Perl's core. We're grateful to the entire CPAN
-community for helping Perl to flourish.
-
-For a more complete list of all of Perl's historical contributors,
-please see the F<AUTHORS> file in the Perl source distribution.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at L<http://rt.perl.org/perlbug/>. There may also be
-information at L<http://www.perl.org/>, the Perl Home Page.
-
-If you believe you have an unreported bug, please run the L<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team.
-
-If the bug you are reporting has security implications, which make it
-inappropriate to send to a publicly archived mailing list, then please
-send it to perl5-security-report@perl.org. This points to a closed
-subscription unarchived mailing list, which includes all core
-committers, who will be able to help assess the impact of issues, figure
-out a resolution, and help co-ordinate the release of patches to
-mitigate or fix the problem across all platforms on which Perl is
-supported. Please use this address only for security issues in the Perl
-core, not for modules independently distributed on CPAN.
-
-=head1 SEE ALSO
-
-The F<Changes> file for an explanation of how to view exhaustive details
-on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl5161delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5161delta.pod
deleted file mode 100644
index 406e1cc3e2d..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl5161delta.pod
+++ /dev/null
@@ -1,198 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perl5161delta - what is new for perl v5.16.1
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.16.0 release and
-the 5.16.1 release.
-
-If you are upgrading from an earlier release such as 5.14.0, first read
-L<perl5160delta>, which describes differences between 5.14.0 and
-5.16.0.
-
-=head1 Security
-
-=head2 an off-by-two error in Scalar-List-Util has been fixed
-
-The bugfix was in Scalar-List-Util 1.23_04, and perl 5.16.1 includes
-Scalar-List-Util 1.25.
-
-=head1 Incompatible Changes
-
-There are no changes intentionally incompatible with 5.16.0 If any
-exist, they are bugs, and we request that you submit a report. See
-L</Reporting Bugs> below.
-
-=head1 Modules and Pragmata
-
-=head2 Updated Modules and Pragmata
-
-=over 4
-
-=item *
-
-L<Scalar::Util> and L<List::Util> have been upgraded from version 1.23 to
-version 1.25.
-
-=item *
-
-L<B::Deparse> has been updated from version 1.14 to 1.14_01. An
-"uninitialized" warning emitted by B::Deparse has been squashed
-[perl #113464].
-
-=back
-
-=head1 Configuration and Compilation
-
-=over
-
-=item *
-
-Building perl with some Windows compilers used to fail due to a problem
-with miniperl's C<glob> operator (which uses the C<perlglob> program)
-deleting the PATH environment variable [perl #113798].
-
-=back
-
-=head1 Platform Support
-
-=head2 Platform-Specific Notes
-
-=over 4
-
-=item VMS
-
-All C header files from the top-level directory of the distribution are now
-installed on VMS, providing consistency with a long-standing practice on other
-platforms. Previously only a subset were installed, which broke non-core extension
-builds for extensions that depended on the missing include files.
-
-=back
-
-=head1 Selected Bug Fixes
-
-=over 4
-
-=item *
-
-A regression introduced in Perl v5.16.0 involving
-C<tr/I<SEARCHLIST>/I<REPLACEMENTLIST>/> has been fixed. Only the first
-instance is supposed to be meaningful if a character appears more than
-once in C<I<SEARCHLIST>>. Under some circumstances, the final instance
-was overriding all earlier ones. [perl #113584]
-
-=item *
-
-C<B::COP::stashlen> has been added. This provides access to an internal
-field added in perl 5.16 under threaded builds. It was broken at the last
-minute before 5.16 was released [perl #113034].
-
-=item *
-
-The L<re> pragma will no longer clobber C<$_>. [perl #113750]
-
-=item *
-
-Unicode 6.1 published an incorrect alias for one of the
-Canonical_Combining_Class property's values (which range between 0 and
-254). The alias C<CCC133> should have been C<CCC132>. Perl now
-overrides the data file furnished by Unicode to give the correct value.
-
-=item *
-
-Duplicating scalar filehandles works again. [perl #113764]
-
-=item *
-
-Under threaded perls, a runtime code block in a regular expression could
-corrupt the package name stored in the op tree, resulting in bad reads
-in C<caller>, and possibly crashes [perl #113060].
-
-=item *
-
-For efficiency's sake, many operators and built-in functions return the
-same scalar each time. Lvalue subroutines and subroutines in the CORE::
-namespace were allowing this implementation detail to leak through.
-C<print &CORE::uc("a"), &CORE::uc("b")> used to print "BB". The same thing
-would happen with an lvalue subroutine returning the return value of C<uc>.
-Now the value is copied in such cases [perl #113044].
-
-=item *
-
-C<__SUB__> now works in special blocks (C<BEGIN>, C<END>, etc.).
-
-=item *
-
-Formats that reference lexical variables from outside no longer result
-in crashes.
-
-=back
-
-=head1 Known Problems
-
-There are no new known problems, but consult L<perl5160delta/Known
-Problems> to see those identified in the 5.16.0 release.
-
-=head1 Acknowledgements
-
-Perl 5.16.1 represents approximately 2 months of development since Perl
-5.16.0 and contains approximately 14,000 lines of changes across 96
-files from 8 authors.
-
-Perl continues to flourish into its third decade thanks to a vibrant
-community of users and developers. The following people are known to
-have contributed the improvements that became Perl 5.16.1:
-
-Chris 'BinGOs' Williams, Craig A. Berry, Father Chrysostomos, Karl
-Williamson, Paul Johnson, Reini Urban, Ricardo Signes, Tony Cook.
-
-The list above is almost certainly incomplete as it is automatically
-generated from version control history. In particular, it does not
-include the names of the (very much appreciated) contributors who
-reported issues to the Perl bug tracker.
-
-Many of the changes included in this version originated in the CPAN
-modules included in Perl's core. We're grateful to the entire CPAN
-community for helping Perl to flourish.
-
-For a more complete list of all of Perl's historical contributors,
-please see the F<AUTHORS> file in the Perl source distribution.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://rt.perl.org/perlbug/ . There may also be
-information at http://www.perl.org/ , the Perl Home Page.
-
-If you believe you have an unreported bug, please run the L<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team.
-
-If the bug you are reporting has security implications, which make it
-inappropriate to send to a publicly archived mailing list, then please
-send it to perl5-security-report@perl.org. This points to a closed
-subscription unarchived mailing list, which includes all the core
-committers, who will be able to help assess the impact of issues, figure
-out a resolution, and help co-ordinate the release of patches to
-mitigate or fix the problem across all platforms on which Perl is
-supported. Please only use this address for security issues in the Perl
-core, not for modules independently distributed on CPAN.
-
-=head1 SEE ALSO
-
-The F<Changes> file for an explanation of how to view exhaustive details
-on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl5162delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5162delta.pod
deleted file mode 100644
index d41e3b5cfe3..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl5162delta.pod
+++ /dev/null
@@ -1,125 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perldelta - what is new for perl v5.16.2
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.16.1 release and
-the 5.16.2 release.
-
-If you are upgrading from an earlier release such as 5.16.0, first read
-L<perl5161delta>, which describes differences between 5.16.0 and
-5.16.1.
-
-=head1 Incompatible Changes
-
-There are no changes intentionally incompatible with 5.16.0
-If any exist, they are bugs, and we request that you submit a
-report. See L</Reporting Bugs> below.
-
-=head1 Modules and Pragmata
-
-=head2 Updated Modules and Pragmata
-
-=over 4
-
-=item *
-
-L<Module::CoreList> has been upgraded from version 2.70 to version 2.76.
-
-=back
-
-=head1 Configuration and Compilation
-
-=over 4
-
-=item * configuration should no longer be confused by ls colorization
-
-=back
-
-=head1 Platform Support
-
-=head2 Platform-Specific Notes
-
-=over 4
-
-=item AIX
-
-Configure now always adds -qlanglvl=extc99 to the CC flags on AIX when
-using xlC. This will make it easier to compile a number of XS-based modules
-that assume C99 [perl #113778].
-
-=back
-
-=head1 Selected Bug Fixes
-
-=over 4
-
-=item * fix /\h/ equivalence with /[\h]/
-
-see [perl #114220]
-
-=back
-
-=head1 Known Problems
-
-There are no new known problems.
-
-=head1 Acknowledgements
-
-Perl 5.16.2 represents approximately 2 months of development since Perl
-5.16.1 and contains approximately 740 lines of changes across 20 files
-from 9 authors.
-
-Perl continues to flourish into its third decade thanks to a vibrant
-community of users and developers. The following people are known to
-have contributed the improvements that became Perl 5.16.2:
-
-Andy Dougherty, Craig A. Berry, Darin McBride, Dominic Hargreaves, Karen
-Etheridge, Karl Williamson, Peter Martini, Ricardo Signes, Tony Cook.
-
-The list above is almost certainly incomplete as it is automatically
-generated from version control history. In particular, it does not
-include the names of the (very much appreciated) contributors who
-reported issues to the Perl bug tracker.
-
-For a more complete list of all of Perl's historical contributors,
-please see the F<AUTHORS> file in the Perl source distribution.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://rt.perl.org/perlbug/ . There may also be
-information at http://www.perl.org/ , the Perl Home Page.
-
-If you believe you have an unreported bug, please run the L<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team.
-
-If the bug you are reporting has security implications, which make it
-inappropriate to send to a publicly archived mailing list, then please
-send it to perl5-security-report@perl.org. This points to a closed
-subscription unarchived mailing list, which includes all the core
-committers, who will be able to help assess the impact of issues, figure
-out a resolution, and help co-ordinate the release of patches to
-mitigate or fix the problem across all platforms on which Perl is
-supported. Please only use this address for security issues in the Perl
-core, not for modules independently distributed on CPAN.
-
-=head1 SEE ALSO
-
-The F<Changes> file for an explanation of how to view exhaustive details
-on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl561delta.pod b/Master/tlpkg/tlperl/lib/pods/perl561delta.pod
deleted file mode 100644
index 49ff54f8983..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl561delta.pod
+++ /dev/null
@@ -1,3660 +0,0 @@
-=head1 NAME
-
-perl561delta - what's new for perl v5.6.1
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.005 release and the 5.6.1
-release.
-
-=head1 Summary of changes between 5.6.0 and 5.6.1
-
-This section contains a summary of the changes between the 5.6.0 release
-and the 5.6.1 release. More details about the changes mentioned here
-may be found in the F<Changes> files that accompany the Perl source
-distribution. See L<perlhack> for pointers to online resources where you
-can inspect the individual patches described by these changes.
-
-=head2 Security Issues
-
-suidperl will not run /bin/mail anymore, because some platforms have
-a /bin/mail that is vulnerable to buffer overflow attacks.
-
-Note that suidperl is neither built nor installed by default in
-any recent version of perl. Use of suidperl is highly discouraged.
-If you think you need it, try alternatives such as sudo first.
-See http://www.courtesan.com/sudo/ .
-
-=head2 Core bug fixes
-
-This is not an exhaustive list. It is intended to cover only the
-significant user-visible changes.
-
-=over
-
-=item C<UNIVERSAL::isa()>
-
-A bug in the caching mechanism used by C<UNIVERSAL::isa()> that affected
-base.pm has been fixed. The bug has existed since the 5.005 releases,
-but wasn't tickled by base.pm in those releases.
-
-=item Memory leaks
-
-Various cases of memory leaks and attempts to access uninitialized memory
-have been cured. See L</"Known Problems"> below for further issues.
-
-=item Numeric conversions
-
-Numeric conversions did not recognize changes in the string value
-properly in certain circumstances.
-
-In other situations, large unsigned numbers (those above 2**31) could
-sometimes lose their unsignedness, causing bogus results in arithmetic
-operations.
-
-Integer modulus on large unsigned integers sometimes returned
-incorrect values.
-
-Perl 5.6.0 generated "not a number" warnings on certain conversions where
-previous versions didn't.
-
-These problems have all been rectified.
-
-Infinity is now recognized as a number.
-
-=item qw(a\\b)
-
-In Perl 5.6.0, qw(a\\b) produced a string with two backslashes instead
-of one, in a departure from the behavior in previous versions. The
-older behavior has been reinstated.
-
-=item caller()
-
-caller() could cause core dumps in certain situations. Carp was sometimes
-affected by this problem.
-
-=item Bugs in regular expressions
-
-Pattern matches on overloaded values are now handled correctly.
-
-Perl 5.6.0 parsed m/\x{ab}/ incorrectly, leading to spurious warnings.
-This has been corrected.
-
-The RE engine found in Perl 5.6.0 accidentally pessimised certain kinds
-of simple pattern matches. These are now handled better.
-
-Regular expression debug output (whether through C<use re 'debug'>
-or via C<-Dr>) now looks better.
-
-Multi-line matches like C<"a\nxb\n" =~ /(?!\A)x/m> were flawed. The
-bug has been fixed.
-
-Use of $& could trigger a core dump under some situations. This
-is now avoided.
-
-Match variables $1 et al., weren't being unset when a pattern match
-was backtracking, and the anomaly showed up inside C</...(?{ ... }).../>
-etc. These variables are now tracked correctly.
-
-pos() did not return the correct value within s///ge in earlier
-versions. This is now handled correctly.
-
-=item "slurp" mode
-
-readline() on files opened in "slurp" mode could return an extra "" at
-the end in certain situations. This has been corrected.
-
-=item Autovivification of symbolic references to special variables
-
-Autovivification of symbolic references of special variables described
-in L<perlvar> (as in C<${$num}>) was accidentally disabled. This works
-again now.
-
-=item Lexical warnings
-
-Lexical warnings now propagate correctly into C<eval "...">.
-
-C<use warnings qw(FATAL all)> did not work as intended. This has been
-corrected.
-
-Lexical warnings could leak into other scopes in some situations.
-This is now fixed.
-
-warnings::enabled() now reports the state of $^W correctly if the caller
-isn't using lexical warnings.
-
-=item Spurious warnings and errors
-
-Perl 5.6.0 could emit spurious warnings about redefinition of dl_error()
-when statically building extensions into perl. This has been corrected.
-
-"our" variables could result in bogus "Variable will not stay shared"
-warnings. This is now fixed.
-
-"our" variables of the same name declared in two sibling blocks
-resulted in bogus warnings about "redeclaration" of the variables.
-The problem has been corrected.
-
-=item glob()
-
-Compatibility of the builtin glob() with old csh-based glob has been
-improved with the addition of GLOB_ALPHASORT option. See C<File::Glob>.
-
-File::Glob::glob() has been renamed to File::Glob::bsd_glob()
-because the name clashes with the builtin glob(). The older
-name is still available for compatibility, but is deprecated.
-
-Spurious syntax errors generated in certain situations, when glob()
-caused File::Glob to be loaded for the first time, have been fixed.
-
-=item Tainting
-
-Some cases of inconsistent taint propagation (such as within hash
-values) have been fixed.
-
-The tainting behavior of sprintf() has been rationalized. It does
-not taint the result of floating point formats anymore, making the
-behavior consistent with that of string interpolation.
-
-=item sort()
-
-Arguments to sort() weren't being provided the right wantarray() context.
-The comparison block is now run in scalar context, and the arguments to
-be sorted are always provided list context.
-
-sort() is also fully reentrant, in the sense that the sort function
-can itself call sort(). This did not work reliably in previous releases.
-
-=item #line directives
-
-#line directives now work correctly when they appear at the very
-beginning of C<eval "...">.
-
-=item Subroutine prototypes
-
-The (\&) prototype now works properly.
-
-=item map()
-
-map() could get pathologically slow when the result list it generates
-is larger than the source list. The performance has been improved for
-common scenarios.
-
-=item Debugger
-
-Debugger exit code now reflects the script exit code.
-
-Condition C<"0"> in breakpoints is now treated correctly.
-
-The C<d> command now checks the line number.
-
-C<$.> is no longer corrupted by the debugger.
-
-All debugger output now correctly goes to the socket if RemotePort
-is set.
-
-=item PERL5OPT
-
-PERL5OPT can be set to more than one switch group. Previously,
-it used to be limited to one group of options only.
-
-=item chop()
-
-chop(@list) in list context returned the characters chopped in reverse
-order. This has been reversed to be in the right order.
-
-=item Unicode support
-
-Unicode support has seen a large number of incremental improvements,
-but continues to be highly experimental. It is not expected to be
-fully supported in the 5.6.x maintenance releases.
-
-substr(), join(), repeat(), reverse(), quotemeta() and string
-concatenation were all handling Unicode strings incorrectly in
-Perl 5.6.0. This has been corrected.
-
-Support for C<tr///CU> and C<tr///UC> etc., have been removed since
-we realized the interface is broken. For similar functionality,
-see L<perlfunc/pack>.
-
-The Unicode Character Database has been updated to version 3.0.1
-with additions made available to the public as of August 30, 2000.
-
-The Unicode character classes \p{Blank} and \p{SpacePerl} have been
-added. "Blank" is like C isblank(), that is, it contains only
-"horizontal whitespace" (the space character is, the newline isn't),
-and the "SpacePerl" is the Unicode equivalent of C<\s> (\p{Space}
-isn't, since that includes the vertical tabulator character, whereas
-C<\s> doesn't.)
-
-If you are experimenting with Unicode support in perl, the development
-versions of Perl may have more to offer. In particular, I/O layers
-are now available in the development track, but not in the maintenance
-track, primarily to do backward compatibility issues. Unicode support
-is also evolving rapidly on a daily basis in the development track--the
-maintenance track only reflects the most conservative of these changes.
-
-=item 64-bit support
-
-Support for 64-bit platforms has been improved, but continues to be
-experimental. The level of support varies greatly among platforms.
-
-=item Compiler
-
-The B Compiler and its various backends have had many incremental
-improvements, but they continue to remain highly experimental. Use in
-production environments is discouraged.
-
-The perlcc tool has been rewritten so that the user interface is much
-more like that of a C compiler.
-
-The perlbc tools has been removed. Use C<perlcc -B> instead.
-
-=item Lvalue subroutines
-
-There have been various bugfixes to support lvalue subroutines better.
-However, the feature still remains experimental.
-
-=item IO::Socket
-
-IO::Socket::INET failed to open the specified port if the service
-name was not known. It now correctly uses the supplied port number
-as is.
-
-=item File::Find
-
-File::Find now chdir()s correctly when chasing symbolic links.
-
-=item xsubpp
-
-xsubpp now tolerates embedded POD sections.
-
-=item C<no Module;>
-
-C<no Module;> does not produce an error even if Module does not have an
-unimport() method. This parallels the behavior of C<use> vis-a-vis
-C<import>.
-
-=item Tests
-
-A large number of tests have been added.
-
-=back
-
-=head2 Core features
-
-untie() will now call an UNTIE() hook if it exists. See L<perltie>
-for details.
-
-The C<-DT> command line switch outputs copious tokenizing information.
-See L<perlrun>.
-
-Arrays are now always interpolated in double-quotish strings. Previously,
-C<"foo@bar.com"> used to be a fatal error at compile time, if an array
-C<@bar> was not used or declared. This transitional behavior was
-intended to help migrate perl4 code, and is deemed to be no longer useful.
-See L</"Arrays now always interpolate into double-quoted strings">.
-
-keys(), each(), pop(), push(), shift(), splice() and unshift()
-can all be overridden now.
-
-C<my __PACKAGE__ $obj> now does the expected thing.
-
-=head2 Configuration issues
-
-On some systems (IRIX and Solaris among them) the system malloc is demonstrably
-better. While the defaults haven't been changed in order to retain binary
-compatibility with earlier releases, you may be better off building perl
-with C<Configure -Uusemymalloc ...> as discussed in the F<INSTALL> file.
-
-C<Configure> has been enhanced in various ways:
-
-=over
-
-=item *
-
-Minimizes use of temporary files.
-
-=item *
-
-By default, does not link perl with libraries not used by it, such as
-the various dbm libraries. SunOS 4.x hints preserve behavior on that
-platform.
-
-=item *
-
-Support for pdp11-style memory models has been removed due to obsolescence.
-
-=item *
-
-Building outside the source tree is supported on systems that have
-symbolic links. This is done by running
-
- sh /path/to/source/Configure -Dmksymlinks ...
- make all test install
-
-in a directory other than the perl source directory. See F<INSTALL>.
-
-=item *
-
-C<Configure -S> can be run non-interactively.
-
-=back
-
-=head2 Documentation
-
-README.aix, README.solaris and README.macos have been added.
-README.posix-bc has been renamed to README.bs2000. These are
-installed as L<perlaix>, L<perlsolaris>, L<perlmacos>, and
-L<perlbs2000> respectively.
-
-The following pod documents are brand new:
-
- perlclib Internal replacements for standard C library functions
- perldebtut Perl debugging tutorial
- perlebcdic Considerations for running Perl on EBCDIC platforms
- perlnewmod Perl modules: preparing a new module for distribution
- perlrequick Perl regular expressions quick start
- perlretut Perl regular expressions tutorial
- perlutil utilities packaged with the Perl distribution
-
-The F<INSTALL> file has been expanded to cover various issues, such as
-64-bit support.
-
-A longer list of contributors has been added to the source distribution.
-See the file C<AUTHORS>.
-
-Numerous other changes have been made to the included documentation and FAQs.
-
-=head2 Bundled modules
-
-The following modules have been added.
-
-=over
-
-=item B::Concise
-
-Walks Perl syntax tree, printing concise info about ops. See L<B::Concise>.
-
-=item File::Temp
-
-Returns name and handle of a temporary file safely. See L<File::Temp>.
-
-=item Pod::LaTeX
-
-Converts Pod data to formatted LaTeX. See L<Pod::LaTeX>.
-
-=item Pod::Text::Overstrike
-
-Converts POD data to formatted overstrike text. See L<Pod::Text::Overstrike>.
-
-=back
-
-The following modules have been upgraded.
-
-=over
-
-=item CGI
-
-CGI v2.752 is now included.
-
-=item CPAN
-
-CPAN v1.59_54 is now included.
-
-=item Class::Struct
-
-Various bugfixes have been added.
-
-=item DB_File
-
-DB_File v1.75 supports newer Berkeley DB versions, among other
-improvements.
-
-=item Devel::Peek
-
-Devel::Peek has been enhanced to support dumping of memory statistics,
-when perl is built with the included malloc().
-
-=item File::Find
-
-File::Find now supports pre and post-processing of the files in order
-to sort() them, etc.
-
-=item Getopt::Long
-
-Getopt::Long v2.25 is included.
-
-=item IO::Poll
-
-Various bug fixes have been included.
-
-=item IPC::Open3
-
-IPC::Open3 allows use of numeric file descriptors.
-
-=item Math::BigFloat
-
-The fmod() function supports modulus operations. Various bug fixes
-have also been included.
-
-=item Math::Complex
-
-Math::Complex handles inf, NaN etc., better.
-
-=item Net::Ping
-
-ping() could fail on odd number of data bytes, and when the echo service
-isn't running. This has been corrected.
-
-=item Opcode
-
-A memory leak has been fixed.
-
-=item Pod::Parser
-
-Version 1.13 of the Pod::Parser suite is included.
-
-=item Pod::Text
-
-Pod::Text and related modules have been upgraded to the versions
-in podlators suite v2.08.
-
-=item SDBM_File
-
-On dosish platforms, some keys went missing because of lack of support for
-files with "holes". A workaround for the problem has been added.
-
-=item Sys::Syslog
-
-Various bug fixes have been included.
-
-=item Tie::RefHash
-
-Now supports Tie::RefHash::Nestable to automagically tie hashref values.
-
-=item Tie::SubstrHash
-
-Various bug fixes have been included.
-
-=back
-
-=head2 Platform-specific improvements
-
-The following new ports are now available.
-
-=over
-
-=item NCR MP-RAS
-
-=item NonStop-UX
-
-=back
-
-Perl now builds under Amdahl UTS.
-
-Perl has also been verified to build under Amiga OS.
-
-Support for EPOC has been much improved. See README.epoc.
-
-Building perl with -Duseithreads or -Duse5005threads now works
-under HP-UX 10.20 (previously it only worked under 10.30 or later).
-You will need a thread library package installed. See README.hpux.
-
-Long doubles should now work under Linux.
-
-Mac OS Classic is now supported in the mainstream source package.
-See README.macos.
-
-Support for MPE/iX has been updated. See README.mpeix.
-
-Support for OS/2 has been improved. See C<os2/Changes> and README.os2.
-
-Dynamic loading on z/OS (formerly OS/390) has been improved. See
-README.os390.
-
-Support for VMS has seen many incremental improvements, including
-better support for operators like backticks and system(), and better
-%ENV handling. See C<README.vms> and L<perlvms>.
-
-Support for Stratus VOS has been improved. See C<vos/Changes> and README.vos.
-
-Support for Windows has been improved.
-
-=over
-
-=item *
-
-fork() emulation has been improved in various ways, but still continues
-to be experimental. See L<perlfork> for known bugs and caveats.
-
-=item *
-
-%SIG has been enabled under USE_ITHREADS, but its use is completely
-unsupported under all configurations.
-
-=item *
-
-Borland C++ v5.5 is now a supported compiler that can build Perl.
-However, the generated binaries continue to be incompatible with those
-generated by the other supported compilers (GCC and Visual C++).
-
-=item *
-
-Non-blocking waits for child processes (or pseudo-processes) are
-supported via C<waitpid($pid, &POSIX::WNOHANG)>.
-
-=item *
-
-A memory leak in accept() has been fixed.
-
-=item *
-
-wait(), waitpid() and backticks now return the correct exit status under
-Windows 9x.
-
-=item *
-
-Trailing new %ENV entries weren't propagated to child processes. This
-is now fixed.
-
-=item *
-
-Current directory entries in %ENV are now correctly propagated to child
-processes.
-
-=item *
-
-Duping socket handles with open(F, ">&MYSOCK") now works under Windows 9x.
-
-=item *
-
-The makefiles now provide a single switch to bulk-enable all the features
-enabled in ActiveState ActivePerl (a popular binary distribution).
-
-=item *
-
-Win32::GetCwd() correctly returns C:\ instead of C: when at the drive root.
-Other bugs in chdir() and Cwd::cwd() have also been fixed.
-
-=item *
-
-fork() correctly returns undef and sets EAGAIN when it runs out of
-pseudo-process handles.
-
-=item *
-
-ExtUtils::MakeMaker now uses $ENV{LIB} to search for libraries.
-
-=item *
-
-UNC path handling is better when perl is built to support fork().
-
-=item *
-
-A handle leak in socket handling has been fixed.
-
-=item *
-
-send() works from within a pseudo-process.
-
-=back
-
-Unless specifically qualified otherwise, the remainder of this document
-covers changes between the 5.005 and 5.6.0 releases.
-
-=head1 Core Enhancements
-
-=head2 Interpreter cloning, threads, and concurrency
-
-Perl 5.6.0 introduces the beginnings of support for running multiple
-interpreters concurrently in different threads. In conjunction with
-the perl_clone() API call, which can be used to selectively duplicate
-the state of any given interpreter, it is possible to compile a
-piece of code once in an interpreter, clone that interpreter
-one or more times, and run all the resulting interpreters in distinct
-threads.
-
-On the Windows platform, this feature is used to emulate fork() at the
-interpreter level. See L<perlfork> for details about that.
-
-This feature is still in evolution. It is eventually meant to be used
-to selectively clone a subroutine and data reachable from that
-subroutine in a separate interpreter and run the cloned subroutine
-in a separate thread. Since there is no shared data between the
-interpreters, little or no locking will be needed (unless parts of
-the symbol table are explicitly shared). This is obviously intended
-to be an easy-to-use replacement for the existing threads support.
-
-Support for cloning interpreters and interpreter concurrency can be
-enabled using the -Dusethreads Configure option (see win32/Makefile for
-how to enable it on Windows.) The resulting perl executable will be
-functionally identical to one that was built with -Dmultiplicity, but
-the perl_clone() API call will only be available in the former.
-
--Dusethreads enables the cpp macro USE_ITHREADS by default, which in turn
-enables Perl source code changes that provide a clear separation between
-the op tree and the data it operates with. The former is immutable, and
-can therefore be shared between an interpreter and all of its clones,
-while the latter is considered local to each interpreter, and is therefore
-copied for each clone.
-
-Note that building Perl with the -Dusemultiplicity Configure option
-is adequate if you wish to run multiple B<independent> interpreters
-concurrently in different threads. -Dusethreads only provides the
-additional functionality of the perl_clone() API call and other
-support for running B<cloned> interpreters concurrently.
-
- NOTE: This is an experimental feature. Implementation details are
- subject to change.
-
-=head2 Lexically scoped warning categories
-
-You can now control the granularity of warnings emitted by perl at a finer
-level using the C<use warnings> pragma. L<warnings> and L<perllexwarn>
-have copious documentation on this feature.
-
-=head2 Unicode and UTF-8 support
-
-Perl now uses UTF-8 as its internal representation for character
-strings. The C<utf8> and C<bytes> pragmas are used to control this support
-in the current lexical scope. See L<perlunicode>, L<utf8> and L<bytes> for
-more information.
-
-This feature is expected to evolve quickly to support some form of I/O
-disciplines that can be used to specify the kind of input and output data
-(bytes or characters). Until that happens, additional modules from CPAN
-will be needed to complete the toolkit for dealing with Unicode.
-
- NOTE: This should be considered an experimental feature. Implementation
- details are subject to change.
-
-=head2 Support for interpolating named characters
-
-The new C<\N> escape interpolates named characters within strings.
-For example, C<"Hi! \N{WHITE SMILING FACE}"> evaluates to a string
-with a Unicode smiley face at the end.
-
-=head2 "our" declarations
-
-An "our" declaration introduces a value that can be best understood
-as a lexically scoped symbolic alias to a global variable in the
-package that was current where the variable was declared. This is
-mostly useful as an alternative to the C<vars> pragma, but also provides
-the opportunity to introduce typing and other attributes for such
-variables. See L<perlfunc/our>.
-
-=head2 Support for strings represented as a vector of ordinals
-
-Literals of the form C<v1.2.3.4> are now parsed as a string composed
-of characters with the specified ordinals. This is an alternative, more
-readable way to construct (possibly Unicode) strings instead of
-interpolating characters, as in C<"\x{1}\x{2}\x{3}\x{4}">. The leading
-C<v> may be omitted if there are more than two ordinals, so C<1.2.3> is
-parsed the same as C<v1.2.3>.
-
-Strings written in this form are also useful to represent version "numbers".
-It is easy to compare such version "numbers" (which are really just plain
-strings) using any of the usual string comparison operators C<eq>, C<ne>,
-C<lt>, C<gt>, etc., or perform bitwise string operations on them using C<|>,
-C<&>, etc.
-
-In conjunction with the new C<$^V> magic variable (which contains
-the perl version as a string), such literals can be used as a readable way
-to check if you're running a particular version of Perl:
-
- # this will parse in older versions of Perl also
- if ($^V and $^V gt v5.6.0) {
- # new features supported
- }
-
-C<require> and C<use> also have some special magic to support such literals.
-They will be interpreted as a version rather than as a module name:
-
- require v5.6.0; # croak if $^V lt v5.6.0
- use v5.6.0; # same, but croaks at compile-time
-
-Alternatively, the C<v> may be omitted if there is more than one dot:
-
- require 5.6.0;
- use 5.6.0;
-
-Also, C<sprintf> and C<printf> support the Perl-specific format flag C<%v>
-to print ordinals of characters in arbitrary strings:
-
- printf "v%vd", $^V; # prints current version, such as "v5.5.650"
- printf "%*vX", ":", $addr; # formats IPv6 address
- printf "%*vb", " ", $bits; # displays bitstring
-
-See L<perldata/"Scalar value constructors"> for additional information.
-
-=head2 Improved Perl version numbering system
-
-Beginning with Perl version 5.6.0, the version number convention has been
-changed to a "dotted integer" scheme that is more commonly found in open
-source projects.
-
-Maintenance versions of v5.6.0 will be released as v5.6.1, v5.6.2 etc.
-The next development series following v5.6.0 will be numbered v5.7.x,
-beginning with v5.7.0, and the next major production release following
-v5.6.0 will be v5.8.0.
-
-The English module now sets $PERL_VERSION to $^V (a string value) rather
-than C<$]> (a numeric value). (This is a potential incompatibility.
-Send us a report via perlbug if you are affected by this.)
-
-The v1.2.3 syntax is also now legal in Perl.
-See L<Support for strings represented as a vector of ordinals> for more on that.
-
-To cope with the new versioning system's use of at least three significant
-digits for each version component, the method used for incrementing the
-subversion number has also changed slightly. We assume that versions older
-than v5.6.0 have been incrementing the subversion component in multiples of
-10. Versions after v5.6.0 will increment them by 1. Thus, using the new
-notation, 5.005_03 is the "same" as v5.5.30, and the first maintenance
-version following v5.6.0 will be v5.6.1 (which should be read as being
-equivalent to a floating point value of 5.006_001 in the older format,
-stored in C<$]>).
-
-=head2 New syntax for declaring subroutine attributes
-
-Formerly, if you wanted to mark a subroutine as being a method call or
-as requiring an automatic lock() when it is entered, you had to declare
-that with a C<use attrs> pragma in the body of the subroutine.
-That can now be accomplished with declaration syntax, like this:
-
- sub mymethod : locked method;
- ...
- sub mymethod : locked method {
- ...
- }
-
- sub othermethod :locked :method;
- ...
- sub othermethod :locked :method {
- ...
- }
-
-
-(Note how only the first C<:> is mandatory, and whitespace surrounding
-the C<:> is optional.)
-
-F<AutoSplit.pm> and F<SelfLoader.pm> have been updated to keep the attributes
-with the stubs they provide. See L<attributes>.
-
-=head2 File and directory handles can be autovivified
-
-Similar to how constructs such as C<< $x->[0] >> autovivify a reference,
-handle constructors (open(), opendir(), pipe(), socketpair(), sysopen(),
-socket(), and accept()) now autovivify a file or directory handle
-if the handle passed to them is an uninitialized scalar variable. This
-allows the constructs such as C<open(my $fh, ...)> and C<open(local $fh,...)>
-to be used to create filehandles that will conveniently be closed
-automatically when the scope ends, provided there are no other references
-to them. This largely eliminates the need for typeglobs when opening
-filehandles that must be passed around, as in the following example:
-
- sub myopen {
- open my $fh, "@_"
- or die "Can't open '@_': $!";
- return $fh;
- }
-
- {
- my $f = myopen("</etc/motd");
- print <$f>;
- # $f implicitly closed here
- }
-
-=head2 open() with more than two arguments
-
-If open() is passed three arguments instead of two, the second argument
-is used as the mode and the third argument is taken to be the file name.
-This is primarily useful for protecting against unintended magic behavior
-of the traditional two-argument form. See L<perlfunc/open>.
-
-=head2 64-bit support
-
-Any platform that has 64-bit integers either
-
- (1) natively as longs or ints
- (2) via special compiler flags
- (3) using long long or int64_t
-
-is able to use "quads" (64-bit integers) as follows:
-
-=over 4
-
-=item *
-
-constants (decimal, hexadecimal, octal, binary) in the code
-
-=item *
-
-arguments to oct() and hex()
-
-=item *
-
-arguments to print(), printf() and sprintf() (flag prefixes ll, L, q)
-
-=item *
-
-printed as such
-
-=item *
-
-pack() and unpack() "q" and "Q" formats
-
-=item *
-
-in basic arithmetics: + - * / % (NOTE: operating close to the limits
-of the integer values may produce surprising results)
-
-=item *
-
-in bit arithmetics: & | ^ ~ << >> (NOTE: these used to be forced
-to be 32 bits wide but now operate on the full native width.)
-
-=item *
-
-vec()
-
-=back
-
-Note that unless you have the case (a) you will have to configure
-and compile Perl using the -Duse64bitint Configure flag.
-
- NOTE: The Configure flags -Duselonglong and -Duse64bits have been
- deprecated. Use -Duse64bitint instead.
-
-There are actually two modes of 64-bitness: the first one is achieved
-using Configure -Duse64bitint and the second one using Configure
--Duse64bitall. The difference is that the first one is minimal and
-the second one maximal. The first works in more places than the second.
-
-The C<use64bitint> does only as much as is required to get 64-bit
-integers into Perl (this may mean, for example, using "long longs")
-while your memory may still be limited to 2 gigabytes (because your
-pointers could still be 32-bit). Note that the name C<64bitint> does
-not imply that your C compiler will be using 64-bit C<int>s (it might,
-but it doesn't have to): the C<use64bitint> means that you will be
-able to have 64 bits wide scalar values.
-
-The C<use64bitall> goes all the way by attempting to switch also
-integers (if it can), longs (and pointers) to being 64-bit. This may
-create an even more binary incompatible Perl than -Duse64bitint: the
-resulting executable may not run at all in a 32-bit box, or you may
-have to reboot/reconfigure/rebuild your operating system to be 64-bit
-aware.
-
-Natively 64-bit systems like Alpha and Cray need neither -Duse64bitint
-nor -Duse64bitall.
-
-Last but not least: note that due to Perl's habit of always using
-floating point numbers, the quads are still not true integers.
-When quads overflow their limits (0...18_446_744_073_709_551_615 unsigned,
--9_223_372_036_854_775_808...9_223_372_036_854_775_807 signed), they
-are silently promoted to floating point numbers, after which they will
-start losing precision (in their lower digits).
-
- NOTE: 64-bit support is still experimental on most platforms.
- Existing support only covers the LP64 data model. In particular, the
- LLP64 data model is not yet supported. 64-bit libraries and system
- APIs on many platforms have not stabilized--your mileage may vary.
-
-=head2 Large file support
-
-If you have filesystems that support "large files" (files larger than
-2 gigabytes), you may now also be able to create and access them from
-Perl.
-
- NOTE: The default action is to enable large file support, if
- available on the platform.
-
-If the large file support is on, and you have a Fcntl constant
-O_LARGEFILE, the O_LARGEFILE is automatically added to the flags
-of sysopen().
-
-Beware that unless your filesystem also supports "sparse files" seeking
-to umpteen petabytes may be inadvisable.
-
-Note that in addition to requiring a proper file system to do large
-files you may also need to adjust your per-process (or your
-per-system, or per-process-group, or per-user-group) maximum filesize
-limits before running Perl scripts that try to handle large files,
-especially if you intend to write such files.
-
-Finally, in addition to your process/process group maximum filesize
-limits, you may have quota limits on your filesystems that stop you
-(your user id or your user group id) from using large files.
-
-Adjusting your process/user/group/file system/operating system limits
-is outside the scope of Perl core language. For process limits, you
-may try increasing the limits using your shell's limits/limit/ulimit
-command before running Perl. The BSD::Resource extension (not
-included with the standard Perl distribution) may also be of use, it
-offers the getrlimit/setrlimit interface that can be used to adjust
-process resource usage limits, including the maximum filesize limit.
-
-=head2 Long doubles
-
-In some systems you may be able to use long doubles to enhance the
-range and precision of your double precision floating point numbers
-(that is, Perl's numbers). Use Configure -Duselongdouble to enable
-this support (if it is available).
-
-=head2 "more bits"
-
-You can "Configure -Dusemorebits" to turn on both the 64-bit support
-and the long double support.
-
-=head2 Enhanced support for sort() subroutines
-
-Perl subroutines with a prototype of C<($$)>, and XSUBs in general, can
-now be used as sort subroutines. In either case, the two elements to
-be compared are passed as normal parameters in @_. See L<perlfunc/sort>.
-
-For unprototyped sort subroutines, the historical behavior of passing
-the elements to be compared as the global variables $a and $b remains
-unchanged.
-
-=head2 C<sort $coderef @foo> allowed
-
-sort() did not accept a subroutine reference as the comparison
-function in earlier versions. This is now permitted.
-
-=head2 File globbing implemented internally
-
-Perl now uses the File::Glob implementation of the glob() operator
-automatically. This avoids using an external csh process and the
-problems associated with it.
-
- NOTE: This is currently an experimental feature. Interfaces and
- implementation are subject to change.
-
-=head2 Support for CHECK blocks
-
-In addition to C<BEGIN>, C<INIT>, C<END>, C<DESTROY> and C<AUTOLOAD>,
-subroutines named C<CHECK> are now special. These are queued up during
-compilation and behave similar to END blocks, except they are called at
-the end of compilation rather than at the end of execution. They cannot
-be called directly.
-
-=head2 POSIX character class syntax [: :] supported
-
-For example to match alphabetic characters use /[[:alpha:]]/.
-See L<perlre> for details.
-
-=head2 Better pseudo-random number generator
-
-In 5.005_0x and earlier, perl's rand() function used the C library
-rand(3) function. As of 5.005_52, Configure tests for drand48(),
-random(), and rand() (in that order) and picks the first one it finds.
-
-These changes should result in better random numbers from rand().
-
-=head2 Improved C<qw//> operator
-
-The C<qw//> operator is now evaluated at compile time into a true list
-instead of being replaced with a run time call to C<split()>. This
-removes the confusing misbehaviour of C<qw//> in scalar context, which
-had inherited that behaviour from split().
-
-Thus:
-
- $foo = ($bar) = qw(a b c); print "$foo|$bar\n";
-
-now correctly prints "3|a", instead of "2|a".
-
-=head2 Better worst-case behavior of hashes
-
-Small changes in the hashing algorithm have been implemented in
-order to improve the distribution of lower order bits in the
-hashed value. This is expected to yield better performance on
-keys that are repeated sequences.
-
-=head2 pack() format 'Z' supported
-
-The new format type 'Z' is useful for packing and unpacking null-terminated
-strings. See L<perlfunc/"pack">.
-
-=head2 pack() format modifier '!' supported
-
-The new format type modifier '!' is useful for packing and unpacking
-native shorts, ints, and longs. See L<perlfunc/"pack">.
-
-=head2 pack() and unpack() support counted strings
-
-The template character '/' can be used to specify a counted string
-type to be packed or unpacked. See L<perlfunc/"pack">.
-
-=head2 Comments in pack() templates
-
-The '#' character in a template introduces a comment up to
-end of the line. This facilitates documentation of pack()
-templates.
-
-=head2 Weak references
-
-In previous versions of Perl, you couldn't cache objects so as
-to allow them to be deleted if the last reference from outside
-the cache is deleted. The reference in the cache would hold a
-reference count on the object and the objects would never be
-destroyed.
-
-Another familiar problem is with circular references. When an
-object references itself, its reference count would never go
-down to zero, and it would not get destroyed until the program
-is about to exit.
-
-Weak references solve this by allowing you to "weaken" any
-reference, that is, make it not count towards the reference count.
-When the last non-weak reference to an object is deleted, the object
-is destroyed and all the weak references to the object are
-automatically undef-ed.
-
-To use this feature, you need the Devel::WeakRef package from CPAN, which
-contains additional documentation.
-
- NOTE: This is an experimental feature. Details are subject to change.
-
-=head2 Binary numbers supported
-
-Binary numbers are now supported as literals, in s?printf formats, and
-C<oct()>:
-
- $answer = 0b101010;
- printf "The answer is: %b\n", oct("0b101010");
-
-=head2 Lvalue subroutines
-
-Subroutines can now return modifiable lvalues.
-See L<perlsub/"Lvalue subroutines">.
-
- NOTE: This is an experimental feature. Details are subject to change.
-
-=head2 Some arrows may be omitted in calls through references
-
-Perl now allows the arrow to be omitted in many constructs
-involving subroutine calls through references. For example,
-C<< $foo[10]->('foo') >> may now be written C<$foo[10]('foo')>.
-This is rather similar to how the arrow may be omitted from
-C<< $foo[10]->{'foo'} >>. Note however, that the arrow is still
-required for C<< foo(10)->('bar') >>.
-
-=head2 Boolean assignment operators are legal lvalues
-
-Constructs such as C<($a ||= 2) += 1> are now allowed.
-
-=head2 exists() is supported on subroutine names
-
-The exists() builtin now works on subroutine names. A subroutine
-is considered to exist if it has been declared (even if implicitly).
-See L<perlfunc/exists> for examples.
-
-=head2 exists() and delete() are supported on array elements
-
-The exists() and delete() builtins now work on simple arrays as well.
-The behavior is similar to that on hash elements.
-
-exists() can be used to check whether an array element has been
-initialized. This avoids autovivifying array elements that don't exist.
-If the array is tied, the EXISTS() method in the corresponding tied
-package will be invoked.
-
-delete() may be used to remove an element from the array and return
-it. The array element at that position returns to its uninitialized
-state, so that testing for the same element with exists() will return
-false. If the element happens to be the one at the end, the size of
-the array also shrinks up to the highest element that tests true for
-exists(), or 0 if none such is found. If the array is tied, the DELETE()
-method in the corresponding tied package will be invoked.
-
-See L<perlfunc/exists> and L<perlfunc/delete> for examples.
-
-=head2 Pseudo-hashes work better
-
-Dereferencing some types of reference values in a pseudo-hash,
-such as C<< $ph->{foo}[1] >>, was accidentally disallowed. This has
-been corrected.
-
-When applied to a pseudo-hash element, exists() now reports whether
-the specified value exists, not merely if the key is valid.
-
-delete() now works on pseudo-hashes. When given a pseudo-hash element
-or slice it deletes the values corresponding to the keys (but not the keys
-themselves). See L<perlref/"Pseudo-hashes: Using an array as a hash">.
-
-Pseudo-hash slices with constant keys are now optimized to array lookups
-at compile-time.
-
-List assignments to pseudo-hash slices are now supported.
-
-The C<fields> pragma now provides ways to create pseudo-hashes, via
-fields::new() and fields::phash(). See L<fields>.
-
- NOTE: The pseudo-hash data type continues to be experimental.
- Limiting oneself to the interface elements provided by the
- fields pragma will provide protection from any future changes.
-
-=head2 Automatic flushing of output buffers
-
-fork(), exec(), system(), qx//, and pipe open()s now flush buffers
-of all files opened for output when the operation was attempted. This
-mostly eliminates confusing buffering mishaps suffered by users unaware
-of how Perl internally handles I/O.
-
-This is not supported on some platforms like Solaris where a suitably
-correct implementation of fflush(NULL) isn't available.
-
-=head2 Better diagnostics on meaningless filehandle operations
-
-Constructs such as C<< open(<FH>) >> and C<< close(<FH>) >>
-are compile time errors. Attempting to read from filehandles that
-were opened only for writing will now produce warnings (just as
-writing to read-only filehandles does).
-
-=head2 Where possible, buffered data discarded from duped input filehandle
-
-C<< open(NEW, "<&OLD") >> now attempts to discard any data that
-was previously read and buffered in C<OLD> before duping the handle.
-On platforms where doing this is allowed, the next read operation
-on C<NEW> will return the same data as the corresponding operation
-on C<OLD>. Formerly, it would have returned the data from the start
-of the following disk block instead.
-
-=head2 eof() has the same old magic as <>
-
-C<eof()> would return true if no attempt to read from C<< <> >> had
-yet been made. C<eof()> has been changed to have a little magic of its
-own, it now opens the C<< <> >> files.
-
-=head2 binmode() can be used to set :crlf and :raw modes
-
-binmode() now accepts a second argument that specifies a discipline
-for the handle in question. The two pseudo-disciplines ":raw" and
-":crlf" are currently supported on DOS-derivative platforms.
-See L<perlfunc/"binmode"> and L<open>.
-
-=head2 C<-T> filetest recognizes UTF-8 encoded files as "text"
-
-The algorithm used for the C<-T> filetest has been enhanced to
-correctly identify UTF-8 content as "text".
-
-=head2 system(), backticks and pipe open now reflect exec() failure
-
-On Unix and similar platforms, system(), qx() and open(FOO, "cmd |")
-etc., are implemented via fork() and exec(). When the underlying
-exec() fails, earlier versions did not report the error properly,
-since the exec() happened to be in a different process.
-
-The child process now communicates with the parent about the
-error in launching the external command, which allows these
-constructs to return with their usual error value and set $!.
-
-=head2 Improved diagnostics
-
-Line numbers are no longer suppressed (under most likely circumstances)
-during the global destruction phase.
-
-Diagnostics emitted from code running in threads other than the main
-thread are now accompanied by the thread ID.
-
-Embedded null characters in diagnostics now actually show up. They
-used to truncate the message in prior versions.
-
-$foo::a and $foo::b are now exempt from "possible typo" warnings only
-if sort() is encountered in package C<foo>.
-
-Unrecognized alphabetic escapes encountered when parsing quote
-constructs now generate a warning, since they may take on new
-semantics in later versions of Perl.
-
-Many diagnostics now report the internal operation in which the warning
-was provoked, like so:
-
- Use of uninitialized value in concatenation (.) at (eval 1) line 1.
- Use of uninitialized value in print at (eval 1) line 1.
-
-Diagnostics that occur within eval may also report the file and line
-number where the eval is located, in addition to the eval sequence
-number and the line number within the evaluated text itself. For
-example:
-
- Not enough arguments for scalar at (eval 4)[newlib/perl5db.pl:1411] line 2, at EOF
-
-=head2 Diagnostics follow STDERR
-
-Diagnostic output now goes to whichever file the C<STDERR> handle
-is pointing at, instead of always going to the underlying C runtime
-library's C<stderr>.
-
-=head2 More consistent close-on-exec behavior
-
-On systems that support a close-on-exec flag on filehandles, the
-flag is now set for any handles created by pipe(), socketpair(),
-socket(), and accept(), if that is warranted by the value of $^F
-that may be in effect. Earlier versions neglected to set the flag
-for handles created with these operators. See L<perlfunc/pipe>,
-L<perlfunc/socketpair>, L<perlfunc/socket>, L<perlfunc/accept>,
-and L<perlvar/$^F>.
-
-=head2 syswrite() ease-of-use
-
-The length argument of C<syswrite()> has become optional.
-
-=head2 Better syntax checks on parenthesized unary operators
-
-Expressions such as:
-
- print defined(&foo,&bar,&baz);
- print uc("foo","bar","baz");
- undef($foo,&bar);
-
-used to be accidentally allowed in earlier versions, and produced
-unpredictable behaviour. Some produced ancillary warnings
-when used in this way; others silently did the wrong thing.
-
-The parenthesized forms of most unary operators that expect a single
-argument now ensure that they are not called with more than one
-argument, making the cases shown above syntax errors. The usual
-behaviour of:
-
- print defined &foo, &bar, &baz;
- print uc "foo", "bar", "baz";
- undef $foo, &bar;
-
-remains unchanged. See L<perlop>.
-
-=head2 Bit operators support full native integer width
-
-The bit operators (& | ^ ~ << >>) now operate on the full native
-integral width (the exact size of which is available in $Config{ivsize}).
-For example, if your platform is either natively 64-bit or if Perl
-has been configured to use 64-bit integers, these operations apply
-to 8 bytes (as opposed to 4 bytes on 32-bit platforms).
-For portability, be sure to mask off the excess bits in the result of
-unary C<~>, e.g., C<~$x & 0xffffffff>.
-
-=head2 Improved security features
-
-More potentially unsafe operations taint their results for improved
-security.
-
-The C<passwd> and C<shell> fields returned by the getpwent(), getpwnam(),
-and getpwuid() are now tainted, because the user can affect their own
-encrypted password and login shell.
-
-The variable modified by shmread(), and messages returned by msgrcv()
-(and its object-oriented interface IPC::SysV::Msg::rcv) are also tainted,
-because other untrusted processes can modify messages and shared memory
-segments for their own nefarious purposes.
-
-=head2 More functional bareword prototype (*)
-
-Bareword prototypes have been rationalized to enable them to be used
-to override builtins that accept barewords and interpret them in
-a special way, such as C<require> or C<do>.
-
-Arguments prototyped as C<*> will now be visible within the subroutine
-as either a simple scalar or as a reference to a typeglob.
-See L<perlsub/Prototypes>.
-
-=head2 C<require> and C<do> may be overridden
-
-C<require> and C<do 'file'> operations may be overridden locally
-by importing subroutines of the same name into the current package
-(or globally by importing them into the CORE::GLOBAL:: namespace).
-Overriding C<require> will also affect C<use>, provided the override
-is visible at compile-time.
-See L<perlsub/"Overriding Built-in Functions">.
-
-=head2 $^X variables may now have names longer than one character
-
-Formerly, $^X was synonymous with ${"\cX"}, but $^XY was a syntax
-error. Now variable names that begin with a control character may be
-arbitrarily long. However, for compatibility reasons, these variables
-I<must> be written with explicit braces, as C<${^XY}> for example.
-C<${^XYZ}> is synonymous with ${"\cXYZ"}. Variable names with more
-than one control character, such as C<${^XY^Z}>, are illegal.
-
-The old syntax has not changed. As before, `^X' may be either a
-literal control-X character or the two-character sequence `caret' plus
-`X'. When braces are omitted, the variable name stops after the
-control character. Thus C<"$^XYZ"> continues to be synonymous with
-C<$^X . "YZ"> as before.
-
-As before, lexical variables may not have names beginning with control
-characters. As before, variables whose names begin with a control
-character are always forced to be in package `main'. All such variables
-are reserved for future extensions, except those that begin with
-C<^_>, which may be used by user programs and are guaranteed not to
-acquire special meaning in any future version of Perl.
-
-=head2 New variable $^C reflects C<-c> switch
-
-C<$^C> has a boolean value that reflects whether perl is being run
-in compile-only mode (i.e. via the C<-c> switch). Since
-BEGIN blocks are executed under such conditions, this variable
-enables perl code to determine whether actions that make sense
-only during normal running are warranted. See L<perlvar>.
-
-=head2 New variable $^V contains Perl version as a string
-
-C<$^V> contains the Perl version number as a string composed of
-characters whose ordinals match the version numbers, i.e. v5.6.0.
-This may be used in string comparisons.
-
-See C<Support for strings represented as a vector of ordinals> for an
-example.
-
-=head2 Optional Y2K warnings
-
-If Perl is built with the cpp macro C<PERL_Y2KWARN> defined,
-it emits optional warnings when concatenating the number 19
-with another number.
-
-This behavior must be specifically enabled when running Configure.
-See F<INSTALL> and F<README.Y2K>.
-
-=head2 Arrays now always interpolate into double-quoted strings
-
-In double-quoted strings, arrays now interpolate, no matter what. The
-behavior in earlier versions of perl 5 was that arrays would interpolate
-into strings if the array had been mentioned before the string was
-compiled, and otherwise Perl would raise a fatal compile-time error.
-In versions 5.000 through 5.003, the error was
-
- Literal @example now requires backslash
-
-In versions 5.004_01 through 5.6.0, the error was
-
- In string, @example now must be written as \@example
-
-The idea here was to get people into the habit of writing
-C<"fred\@example.com"> when they wanted a literal C<@> sign, just as
-they have always written C<"Give me back my \$5"> when they wanted a
-literal C<$> sign.
-
-Starting with 5.6.1, when Perl now sees an C<@> sign in a
-double-quoted string, it I<always> attempts to interpolate an array,
-regardless of whether or not the array has been used or declared
-already. The fatal error has been downgraded to an optional warning:
-
- Possible unintended interpolation of @example in string
-
-This warns you that C<"fred@example.com"> is going to turn into
-C<fred.com> if you don't backslash the C<@>.
-See http://perl.plover.com/at-error.html for more details
-about the history here.
-
-=head2 @- and @+ provide starting/ending offsets of regex submatches
-
-The new magic variables @- and @+ provide the starting and ending
-offsets, respectively, of $&, $1, $2, etc. See L<perlvar> for
-details.
-
-=head1 Modules and Pragmata
-
-=head2 Modules
-
-=over 4
-
-=item attributes
-
-While used internally by Perl as a pragma, this module also
-provides a way to fetch subroutine and variable attributes.
-See L<attributes>.
-
-=item B
-
-The Perl Compiler suite has been extensively reworked for this
-release. More of the standard Perl test suite passes when run
-under the Compiler, but there is still a significant way to
-go to achieve production quality compiled executables.
-
- NOTE: The Compiler suite remains highly experimental. The
- generated code may not be correct, even when it manages to execute
- without errors.
-
-=item Benchmark
-
-Overall, Benchmark results exhibit lower average error and better timing
-accuracy.
-
-You can now run tests for I<n> seconds instead of guessing the right
-number of tests to run: e.g., timethese(-5, ...) will run each
-code for at least 5 CPU seconds. Zero as the "number of repetitions"
-means "for at least 3 CPU seconds". The output format has also
-changed. For example:
-
- use Benchmark;$x=3;timethese(-5,{a=>sub{$x*$x},b=>sub{$x**2}})
-
-will now output something like this:
-
- Benchmark: running a, b, each for at least 5 CPU seconds...
- a: 5 wallclock secs ( 5.77 usr + 0.00 sys = 5.77 CPU) @ 200551.91/s (n=1156516)
- b: 4 wallclock secs ( 5.00 usr + 0.02 sys = 5.02 CPU) @ 159605.18/s (n=800686)
-
-New features: "each for at least N CPU seconds...", "wallclock secs",
-and the "@ operations/CPU second (n=operations)".
-
-timethese() now returns a reference to a hash of Benchmark objects containing
-the test results, keyed on the names of the tests.
-
-timethis() now returns the iterations field in the Benchmark result object
-instead of 0.
-
-timethese(), timethis(), and the new cmpthese() (see below) can also take
-a format specifier of 'none' to suppress output.
-
-A new function countit() is just like timeit() except that it takes a
-TIME instead of a COUNT.
-
-A new function cmpthese() prints a chart comparing the results of each test
-returned from a timethese() call. For each possible pair of tests, the
-percentage speed difference (iters/sec or seconds/iter) is shown.
-
-For other details, see L<Benchmark>.
-
-=item ByteLoader
-
-The ByteLoader is a dedicated extension to generate and run
-Perl bytecode. See L<ByteLoader>.
-
-=item constant
-
-References can now be used.
-
-The new version also allows a leading underscore in constant names, but
-disallows a double leading underscore (as in "__LINE__"). Some other names
-are disallowed or warned against, including BEGIN, END, etc. Some names
-which were forced into main:: used to fail silently in some cases; now they're
-fatal (outside of main::) and an optional warning (inside of main::).
-The ability to detect whether a constant had been set with a given name has
-been added.
-
-See L<constant>.
-
-=item charnames
-
-This pragma implements the C<\N> string escape. See L<charnames>.
-
-=item Data::Dumper
-
-A C<Maxdepth> setting can be specified to avoid venturing
-too deeply into deep data structures. See L<Data::Dumper>.
-
-The XSUB implementation of Dump() is now automatically called if the
-C<Useqq> setting is not in use.
-
-Dumping C<qr//> objects works correctly.
-
-=item DB
-
-C<DB> is an experimental module that exposes a clean abstraction
-to Perl's debugging API.
-
-=item DB_File
-
-DB_File can now be built with Berkeley DB versions 1, 2 or 3.
-See C<ext/DB_File/Changes>.
-
-=item Devel::DProf
-
-Devel::DProf, a Perl source code profiler has been added. See
-L<Devel::DProf> and L<dprofpp>.
-
-=item Devel::Peek
-
-The Devel::Peek module provides access to the internal representation
-of Perl variables and data. It is a data debugging tool for the XS programmer.
-
-=item Dumpvalue
-
-The Dumpvalue module provides screen dumps of Perl data.
-
-=item DynaLoader
-
-DynaLoader now supports a dl_unload_file() function on platforms that
-support unloading shared objects using dlclose().
-
-Perl can also optionally arrange to unload all extension shared objects
-loaded by Perl. To enable this, build Perl with the Configure option
-C<-Accflags=-DDL_UNLOAD_ALL_AT_EXIT>. (This maybe useful if you are
-using Apache with mod_perl.)
-
-=item English
-
-$PERL_VERSION now stands for C<$^V> (a string value) rather than for C<$]>
-(a numeric value).
-
-=item Env
-
-Env now supports accessing environment variables like PATH as array
-variables.
-
-=item Fcntl
-
-More Fcntl constants added: F_SETLK64, F_SETLKW64, O_LARGEFILE for
-large file (more than 4GB) access (NOTE: the O_LARGEFILE is
-automatically added to sysopen() flags if large file support has been
-configured, as is the default), Free/Net/OpenBSD locking behaviour
-flags F_FLOCK, F_POSIX, Linux F_SHLCK, and O_ACCMODE: the combined
-mask of O_RDONLY, O_WRONLY, and O_RDWR. The seek()/sysseek()
-constants SEEK_SET, SEEK_CUR, and SEEK_END are available via the
-C<:seek> tag. The chmod()/stat() S_IF* constants and S_IS* functions
-are available via the C<:mode> tag.
-
-=item File::Compare
-
-A compare_text() function has been added, which allows custom
-comparison functions. See L<File::Compare>.
-
-=item File::Find
-
-File::Find now works correctly when the wanted() function is either
-autoloaded or is a symbolic reference.
-
-A bug that caused File::Find to lose track of the working directory
-when pruning top-level directories has been fixed.
-
-File::Find now also supports several other options to control its
-behavior. It can follow symbolic links if the C<follow> option is
-specified. Enabling the C<no_chdir> option will make File::Find skip
-changing the current directory when walking directories. The C<untaint>
-flag can be useful when running with taint checks enabled.
-
-See L<File::Find>.
-
-=item File::Glob
-
-This extension implements BSD-style file globbing. By default,
-it will also be used for the internal implementation of the glob()
-operator. See L<File::Glob>.
-
-=item File::Spec
-
-New methods have been added to the File::Spec module: devnull() returns
-the name of the null device (/dev/null on Unix) and tmpdir() the name of
-the temp directory (normally /tmp on Unix). There are now also methods
-to convert between absolute and relative filenames: abs2rel() and
-rel2abs(). For compatibility with operating systems that specify volume
-names in file paths, the splitpath(), splitdir(), and catdir() methods
-have been added.
-
-=item File::Spec::Functions
-
-The new File::Spec::Functions modules provides a function interface
-to the File::Spec module. Allows shorthand
-
- $fullname = catfile($dir1, $dir2, $file);
-
-instead of
-
- $fullname = File::Spec->catfile($dir1, $dir2, $file);
-
-=item Getopt::Long
-
-Getopt::Long licensing has changed to allow the Perl Artistic License
-as well as the GPL. It used to be GPL only, which got in the way of
-non-GPL applications that wanted to use Getopt::Long.
-
-Getopt::Long encourages the use of Pod::Usage to produce help
-messages. For example:
-
- use Getopt::Long;
- use Pod::Usage;
- my $man = 0;
- my $help = 0;
- GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
- pod2usage(1) if $help;
- pod2usage(-exitstatus => 0, -verbose => 2) if $man;
-
- __END__
-
- =head1 NAME
-
- sample - Using Getopt::Long and Pod::Usage
-
- =head1 SYNOPSIS
-
- sample [options] [file ...]
-
- Options:
- -help brief help message
- -man full documentation
-
- =head1 OPTIONS
-
- =over 8
-
- =item B<-help>
-
- Print a brief help message and exits.
-
- =item B<-man>
-
- Prints the manual page and exits.
-
- =back
-
- =head1 DESCRIPTION
-
- B<This program> will read the given input file(s) and do something
- useful with the contents thereof.
-
- =cut
-
-See L<Pod::Usage> for details.
-
-A bug that prevented the non-option call-back <> from being
-specified as the first argument has been fixed.
-
-To specify the characters < and > as option starters, use ><. Note,
-however, that changing option starters is strongly deprecated.
-
-=item IO
-
-write() and syswrite() will now accept a single-argument
-form of the call, for consistency with Perl's syswrite().
-
-You can now create a TCP-based IO::Socket::INET without forcing
-a connect attempt. This allows you to configure its options
-(like making it non-blocking) and then call connect() manually.
-
-A bug that prevented the IO::Socket::protocol() accessor
-from ever returning the correct value has been corrected.
-
-IO::Socket::connect now uses non-blocking IO instead of alarm()
-to do connect timeouts.
-
-IO::Socket::accept now uses select() instead of alarm() for doing
-timeouts.
-
-IO::Socket::INET->new now sets $! correctly on failure. $@ is
-still set for backwards compatibility.
-
-=item JPL
-
-Java Perl Lingo is now distributed with Perl. See jpl/README
-for more information.
-
-=item lib
-
-C<use lib> now weeds out any trailing duplicate entries.
-C<no lib> removes all named entries.
-
-=item Math::BigInt
-
-The bitwise operations C<<< << >>>, C<<< >> >>>, C<&>, C<|>,
-and C<~> are now supported on bigints.
-
-=item Math::Complex
-
-The accessor methods Re, Im, arg, abs, rho, and theta can now also
-act as mutators (accessor $z->Re(), mutator $z->Re(3)).
-
-The class method C<display_format> and the corresponding object method
-C<display_format>, in addition to accepting just one argument, now can
-also accept a parameter hash. Recognized keys of a parameter hash are
-C<"style">, which corresponds to the old one parameter case, and two
-new parameters: C<"format">, which is a printf()-style format string
-(defaults usually to C<"%.15g">, you can revert to the default by
-setting the format string to C<undef>) used for both parts of a
-complex number, and C<"polar_pretty_print"> (defaults to true),
-which controls whether an attempt is made to try to recognize small
-multiples and rationals of pi (2pi, pi/2) at the argument (angle) of a
-polar complex number.
-
-The potentially disruptive change is that in list context both methods
-now I<return the parameter hash>, instead of only the value of the
-C<"style"> parameter.
-
-=item Math::Trig
-
-A little bit of radial trigonometry (cylindrical and spherical),
-radial coordinate conversions, and the great circle distance were added.
-
-=item Pod::Parser, Pod::InputObjects
-
-Pod::Parser is a base class for parsing and selecting sections of
-pod documentation from an input stream. This module takes care of
-identifying pod paragraphs and commands in the input and hands off the
-parsed paragraphs and commands to user-defined methods which are free
-to interpret or translate them as they see fit.
-
-Pod::InputObjects defines some input objects needed by Pod::Parser, and
-for advanced users of Pod::Parser that need more about a command besides
-its name and text.
-
-As of release 5.6.0 of Perl, Pod::Parser is now the officially sanctioned
-"base parser code" recommended for use by all pod2xxx translators.
-Pod::Text (pod2text) and Pod::Man (pod2man) have already been converted
-to use Pod::Parser and efforts to convert Pod::HTML (pod2html) are already
-underway. For any questions or comments about pod parsing and translating
-issues and utilities, please use the pod-people@perl.org mailing list.
-
-For further information, please see L<Pod::Parser> and L<Pod::InputObjects>.
-
-=item Pod::Checker, podchecker
-
-This utility checks pod files for correct syntax, according to
-L<perlpod>. Obvious errors are flagged as such, while warnings are
-printed for mistakes that can be handled gracefully. The checklist is
-not complete yet. See L<Pod::Checker>.
-
-=item Pod::ParseUtils, Pod::Find
-
-These modules provide a set of gizmos that are useful mainly for pod
-translators. L<Pod::Find|Pod::Find> traverses directory structures and
-returns found pod files, along with their canonical names (like
-C<File::Spec::Unix>). L<Pod::ParseUtils|Pod::ParseUtils> contains
-B<Pod::List> (useful for storing pod list information), B<Pod::Hyperlink>
-(for parsing the contents of C<LE<lt>E<gt>> sequences) and B<Pod::Cache>
-(for caching information about pod files, e.g., link nodes).
-
-=item Pod::Select, podselect
-
-Pod::Select is a subclass of Pod::Parser which provides a function
-named "podselect()" to filter out user-specified sections of raw pod
-documentation from an input stream. podselect is a script that provides
-access to Pod::Select from other scripts to be used as a filter.
-See L<Pod::Select>.
-
-=item Pod::Usage, pod2usage
-
-Pod::Usage provides the function "pod2usage()" to print usage messages for
-a Perl script based on its embedded pod documentation. The pod2usage()
-function is generally useful to all script authors since it lets them
-write and maintain a single source (the pods) for documentation, thus
-removing the need to create and maintain redundant usage message text
-consisting of information already in the pods.
-
-There is also a pod2usage script which can be used from other kinds of
-scripts to print usage messages from pods (even for non-Perl scripts
-with pods embedded in comments).
-
-For details and examples, please see L<Pod::Usage>.
-
-=item Pod::Text and Pod::Man
-
-Pod::Text has been rewritten to use Pod::Parser. While pod2text() is
-still available for backwards compatibility, the module now has a new
-preferred interface. See L<Pod::Text> for the details. The new Pod::Text
-module is easily subclassed for tweaks to the output, and two such
-subclasses (Pod::Text::Termcap for man-page-style bold and underlining
-using termcap information, and Pod::Text::Color for markup with ANSI color
-sequences) are now standard.
-
-pod2man has been turned into a module, Pod::Man, which also uses
-Pod::Parser. In the process, several outstanding bugs related to quotes
-in section headers, quoting of code escapes, and nested lists have been
-fixed. pod2man is now a wrapper script around this module.
-
-=item SDBM_File
-
-An EXISTS method has been added to this module (and sdbm_exists() has
-been added to the underlying sdbm library), so one can now call exists
-on an SDBM_File tied hash and get the correct result, rather than a
-runtime error.
-
-A bug that may have caused data loss when more than one disk block
-happens to be read from the database in a single FETCH() has been
-fixed.
-
-=item Sys::Syslog
-
-Sys::Syslog now uses XSUBs to access facilities from syslog.h so it
-no longer requires syslog.ph to exist.
-
-=item Sys::Hostname
-
-Sys::Hostname now uses XSUBs to call the C library's gethostname() or
-uname() if they exist.
-
-=item Term::ANSIColor
-
-Term::ANSIColor is a very simple module to provide easy and readable
-access to the ANSI color and highlighting escape sequences, supported by
-most ANSI terminal emulators. It is now included standard.
-
-=item Time::Local
-
-The timelocal() and timegm() functions used to silently return bogus
-results when the date fell outside the machine's integer range. They
-now consistently croak() if the date falls in an unsupported range.
-
-=item Win32
-
-The error return value in list context has been changed for all functions
-that return a list of values. Previously these functions returned a list
-with a single element C<undef> if an error occurred. Now these functions
-return the empty list in these situations. This applies to the following
-functions:
-
- Win32::FsType
- Win32::GetOSVersion
-
-The remaining functions are unchanged and continue to return C<undef> on
-error even in list context.
-
-The Win32::SetLastError(ERROR) function has been added as a complement
-to the Win32::GetLastError() function.
-
-The new Win32::GetFullPathName(FILENAME) returns the full absolute
-pathname for FILENAME in scalar context. In list context it returns
-a two-element list containing the fully qualified directory name and
-the filename. See L<Win32>.
-
-=item XSLoader
-
-The XSLoader extension is a simpler alternative to DynaLoader.
-See L<XSLoader>.
-
-=item DBM Filters
-
-A new feature called "DBM Filters" has been added to all the
-DBM modules--DB_File, GDBM_File, NDBM_File, ODBM_File, and SDBM_File.
-DBM Filters add four new methods to each DBM module:
-
- filter_store_key
- filter_store_value
- filter_fetch_key
- filter_fetch_value
-
-These can be used to filter key-value pairs before the pairs are
-written to the database or just after they are read from the database.
-See L<perldbmfilter> for further information.
-
-=back
-
-=head2 Pragmata
-
-C<use attrs> is now obsolete, and is only provided for
-backward-compatibility. It's been replaced by the C<sub : attributes>
-syntax. See L<perlsub/"Subroutine Attributes"> and L<attributes>.
-
-Lexical warnings pragma, C<use warnings;>, to control optional warnings.
-See L<perllexwarn>.
-
-C<use filetest> to control the behaviour of filetests (C<-r> C<-w>
-...). Currently only one subpragma implemented, "use filetest
-'access';", that uses access(2) or equivalent to check permissions
-instead of using stat(2) as usual. This matters in filesystems
-where there are ACLs (access control lists): the stat(2) might lie,
-but access(2) knows better.
-
-The C<open> pragma can be used to specify default disciplines for
-handle constructors (e.g. open()) and for qx//. The two
-pseudo-disciplines C<:raw> and C<:crlf> are currently supported on
-DOS-derivative platforms (i.e. where binmode is not a no-op).
-See also L</"binmode() can be used to set :crlf and :raw modes">.
-
-=head1 Utility Changes
-
-=head2 dprofpp
-
-C<dprofpp> is used to display profile data generated using C<Devel::DProf>.
-See L<dprofpp>.
-
-=head2 find2perl
-
-The C<find2perl> utility now uses the enhanced features of the File::Find
-module. The -depth and -follow options are supported. Pod documentation
-is also included in the script.
-
-=head2 h2xs
-
-The C<h2xs> tool can now work in conjunction with C<C::Scan> (available
-from CPAN) to automatically parse real-life header files. The C<-M>,
-C<-a>, C<-k>, and C<-o> options are new.
-
-=head2 perlcc
-
-C<perlcc> now supports the C and Bytecode backends. By default,
-it generates output from the simple C backend rather than the
-optimized C backend.
-
-Support for non-Unix platforms has been improved.
-
-=head2 perldoc
-
-C<perldoc> has been reworked to avoid possible security holes.
-It will not by default let itself be run as the superuser, but you
-may still use the B<-U> switch to try to make it drop privileges
-first.
-
-=head2 The Perl Debugger
-
-Many bug fixes and enhancements were added to F<perl5db.pl>, the
-Perl debugger. The help documentation was rearranged. New commands
-include C<< < ? >>, C<< > ? >>, and C<< { ? >> to list out current
-actions, C<man I<docpage>> to run your doc viewer on some perl
-docset, and support for quoted options. The help information was
-rearranged, and should be viewable once again if you're using B<less>
-as your pager. A serious security hole was plugged--you should
-immediately remove all older versions of the Perl debugger as
-installed in previous releases, all the way back to perl3, from
-your system to avoid being bitten by this.
-
-=head1 Improved Documentation
-
-Many of the platform-specific README files are now part of the perl
-installation. See L<perl> for the complete list.
-
-=over 4
-
-=item perlapi.pod
-
-The official list of public Perl API functions.
-
-=item perlboot.pod
-
-A tutorial for beginners on object-oriented Perl.
-
-=item perlcompile.pod
-
-An introduction to using the Perl Compiler suite.
-
-=item perldbmfilter.pod
-
-A howto document on using the DBM filter facility.
-
-=item perldebug.pod
-
-All material unrelated to running the Perl debugger, plus all
-low-level guts-like details that risked crushing the casual user
-of the debugger, have been relocated from the old manpage to the
-next entry below.
-
-=item perldebguts.pod
-
-This new manpage contains excessively low-level material not related
-to the Perl debugger, but slightly related to debugging Perl itself.
-It also contains some arcane internal details of how the debugging
-process works that may only be of interest to developers of Perl
-debuggers.
-
-=item perlfork.pod
-
-Notes on the fork() emulation currently available for the Windows platform.
-
-=item perlfilter.pod
-
-An introduction to writing Perl source filters.
-
-=item perlhack.pod
-
-Some guidelines for hacking the Perl source code.
-
-=item perlintern.pod
-
-A list of internal functions in the Perl source code.
-(List is currently empty.)
-
-=item perllexwarn.pod
-
-Introduction and reference information about lexically scoped
-warning categories.
-
-=item perlnumber.pod
-
-Detailed information about numbers as they are represented in Perl.
-
-=item perlopentut.pod
-
-A tutorial on using open() effectively.
-
-=item perlreftut.pod
-
-A tutorial that introduces the essentials of references.
-
-=item perltootc.pod
-
-A tutorial on managing class data for object modules.
-
-=item perltodo.pod
-
-Discussion of the most often wanted features that may someday be
-supported in Perl.
-
-=item perlunicode.pod
-
-An introduction to Unicode support features in Perl.
-
-=back
-
-=head1 Performance enhancements
-
-=head2 Simple sort() using { $a <=> $b } and the like are optimized
-
-Many common sort() operations using a simple inlined block are now
-optimized for faster performance.
-
-=head2 Optimized assignments to lexical variables
-
-Certain operations in the RHS of assignment statements have been
-optimized to directly set the lexical variable on the LHS,
-eliminating redundant copying overheads.
-
-=head2 Faster subroutine calls
-
-Minor changes in how subroutine calls are handled internally
-provide marginal improvements in performance.
-
-=head2 delete(), each(), values() and hash iteration are faster
-
-The hash values returned by delete(), each(), values() and hashes in a
-list context are the actual values in the hash, instead of copies.
-This results in significantly better performance, because it eliminates
-needless copying in most situations.
-
-=head1 Installation and Configuration Improvements
-
-=head2 -Dusethreads means something different
-
-The -Dusethreads flag now enables the experimental interpreter-based thread
-support by default. To get the flavor of experimental threads that was in
-5.005 instead, you need to run Configure with "-Dusethreads -Duse5005threads".
-
-As of v5.6.0, interpreter-threads support is still lacking a way to
-create new threads from Perl (i.e., C<use Thread;> will not work with
-interpreter threads). C<use Thread;> continues to be available when you
-specify the -Duse5005threads option to Configure, bugs and all.
-
- NOTE: Support for threads continues to be an experimental feature.
- Interfaces and implementation are subject to sudden and drastic changes.
-
-=head2 New Configure flags
-
-The following new flags may be enabled on the Configure command line
-by running Configure with C<-Dflag>.
-
- usemultiplicity
- usethreads useithreads (new interpreter threads: no Perl API yet)
- usethreads use5005threads (threads as they were in 5.005)
-
- use64bitint (equal to now deprecated 'use64bits')
- use64bitall
-
- uselongdouble
- usemorebits
- uselargefiles
- usesocks (only SOCKS v5 supported)
-
-=head2 Threadedness and 64-bitness now more daring
-
-The Configure options enabling the use of threads and the use of
-64-bitness are now more daring in the sense that they no more have an
-explicit list of operating systems of known threads/64-bit
-capabilities. In other words: if your operating system has the
-necessary APIs and datatypes, you should be able just to go ahead and
-use them, for threads by Configure -Dusethreads, and for 64 bits
-either explicitly by Configure -Duse64bitint or implicitly if your
-system has 64-bit wide datatypes. See also L<"64-bit support">.
-
-=head2 Long Doubles
-
-Some platforms have "long doubles", floating point numbers of even
-larger range than ordinary "doubles". To enable using long doubles for
-Perl's scalars, use -Duselongdouble.
-
-=head2 -Dusemorebits
-
-You can enable both -Duse64bitint and -Duselongdouble with -Dusemorebits.
-See also L<"64-bit support">.
-
-=head2 -Duselargefiles
-
-Some platforms support system APIs that are capable of handling large files
-(typically, files larger than two gigabytes). Perl will try to use these
-APIs if you ask for -Duselargefiles.
-
-See L<"Large file support"> for more information.
-
-=head2 installusrbinperl
-
-You can use "Configure -Uinstallusrbinperl" which causes installperl
-to skip installing perl also as /usr/bin/perl. This is useful if you
-prefer not to modify /usr/bin for some reason or another but harmful
-because many scripts assume to find Perl in /usr/bin/perl.
-
-=head2 SOCKS support
-
-You can use "Configure -Dusesocks" which causes Perl to probe
-for the SOCKS proxy protocol library (v5, not v4). For more information
-on SOCKS, see:
-
- http://www.socks.nec.com/
-
-=head2 C<-A> flag
-
-You can "post-edit" the Configure variables using the Configure C<-A>
-switch. The editing happens immediately after the platform specific
-hints files have been processed but before the actual configuration
-process starts. Run C<Configure -h> to find out the full C<-A> syntax.
-
-=head2 Enhanced Installation Directories
-
-The installation structure has been enriched to improve the support
-for maintaining multiple versions of perl, to provide locations for
-vendor-supplied modules, scripts, and manpages, and to ease maintenance
-of locally-added modules, scripts, and manpages. See the section on
-Installation Directories in the INSTALL file for complete details.
-For most users building and installing from source, the defaults should
-be fine.
-
-If you previously used C<Configure -Dsitelib> or C<-Dsitearch> to set
-special values for library directories, you might wish to consider using
-the new C<-Dsiteprefix> setting instead. Also, if you wish to re-use a
-config.sh file from an earlier version of perl, you should be sure to
-check that Configure makes sensible choices for the new directories.
-See INSTALL for complete details.
-
-=head2 gcc automatically tried if 'cc' does not seem to be working
-
-In many platforms the vendor-supplied 'cc' is too stripped-down to
-build Perl (basically, the 'cc' doesn't do ANSI C). If this seems
-to be the case and the 'cc' does not seem to be the GNU C compiler
-'gcc', an automatic attempt is made to find and use 'gcc' instead.
-
-=head1 Platform specific changes
-
-=head2 Supported platforms
-
-=over 4
-
-=item *
-
-The Mach CThreads (NEXTSTEP, OPENSTEP) are now supported by the Thread
-extension.
-
-=item *
-
-GNU/Hurd is now supported.
-
-=item *
-
-Rhapsody/Darwin is now supported.
-
-=item *
-
-EPOC is now supported (on Psion 5).
-
-=item *
-
-The cygwin port (formerly cygwin32) has been greatly improved.
-
-=back
-
-=head2 DOS
-
-=over 4
-
-=item *
-
-Perl now works with djgpp 2.02 (and 2.03 alpha).
-
-=item *
-
-Environment variable names are not converted to uppercase any more.
-
-=item *
-
-Incorrect exit codes from backticks have been fixed.
-
-=item *
-
-This port continues to use its own builtin globbing (not File::Glob).
-
-=back
-
-=head2 OS390 (OpenEdition MVS)
-
-Support for this EBCDIC platform has not been renewed in this release.
-There are difficulties in reconciling Perl's standardization on UTF-8
-as its internal representation for characters with the EBCDIC character
-set, because the two are incompatible.
-
-It is unclear whether future versions will renew support for this
-platform, but the possibility exists.
-
-=head2 VMS
-
-Numerous revisions and extensions to configuration, build, testing, and
-installation process to accommodate core changes and VMS-specific options.
-
-Expand %ENV-handling code to allow runtime mapping to logical names,
-CLI symbols, and CRTL environ array.
-
-Extension of subprocess invocation code to accept filespecs as command
-"verbs".
-
-Add to Perl command line processing the ability to use default file types and
-to recognize Unix-style C<2E<gt>&1>.
-
-Expansion of File::Spec::VMS routines, and integration into ExtUtils::MM_VMS.
-
-Extension of ExtUtils::MM_VMS to handle complex extensions more flexibly.
-
-Barewords at start of Unix-syntax paths may be treated as text rather than
-only as logical names.
-
-Optional secure translation of several logical names used internally by Perl.
-
-Miscellaneous bugfixing and porting of new core code to VMS.
-
-Thanks are gladly extended to the many people who have contributed VMS
-patches, testing, and ideas.
-
-=head2 Win32
-
-Perl can now emulate fork() internally, using multiple interpreters running
-in different concurrent threads. This support must be enabled at build
-time. See L<perlfork> for detailed information.
-
-When given a pathname that consists only of a drivename, such as C<A:>,
-opendir() and stat() now use the current working directory for the drive
-rather than the drive root.
-
-The builtin XSUB functions in the Win32:: namespace are documented. See
-L<Win32>.
-
-$^X now contains the full path name of the running executable.
-
-A Win32::GetLongPathName() function is provided to complement
-Win32::GetFullPathName() and Win32::GetShortPathName(). See L<Win32>.
-
-POSIX::uname() is supported.
-
-system(1,...) now returns true process IDs rather than process
-handles. kill() accepts any real process id, rather than strictly
-return values from system(1,...).
-
-For better compatibility with Unix, C<kill(0, $pid)> can now be used to
-test whether a process exists.
-
-The C<Shell> module is supported.
-
-Better support for building Perl under command.com in Windows 95
-has been added.
-
-Scripts are read in binary mode by default to allow ByteLoader (and
-the filter mechanism in general) to work properly. For compatibility,
-the DATA filehandle will be set to text mode if a carriage return is
-detected at the end of the line containing the __END__ or __DATA__
-token; if not, the DATA filehandle will be left open in binary mode.
-Earlier versions always opened the DATA filehandle in text mode.
-
-The glob() operator is implemented via the C<File::Glob> extension,
-which supports glob syntax of the C shell. This increases the flexibility
-of the glob() operator, but there may be compatibility issues for
-programs that relied on the older globbing syntax. If you want to
-preserve compatibility with the older syntax, you might want to run
-perl with C<-MFile::DosGlob>. For details and compatibility information,
-see L<File::Glob>.
-
-=head1 Significant bug fixes
-
-=head2 <HANDLE> on empty files
-
-With C<$/> set to C<undef>, "slurping" an empty file returns a string of
-zero length (instead of C<undef>, as it used to) the first time the
-HANDLE is read after C<$/> is set to C<undef>. Further reads yield
-C<undef>.
-
-This means that the following will append "foo" to an empty file (it used
-to do nothing):
-
- perl -0777 -pi -e 's/^/foo/' empty_file
-
-The behaviour of:
-
- perl -pi -e 's/^/foo/' empty_file
-
-is unchanged (it continues to leave the file empty).
-
-=head2 C<eval '...'> improvements
-
-Line numbers (as reflected by caller() and most diagnostics) within
-C<eval '...'> were often incorrect where here documents were involved.
-This has been corrected.
-
-Lexical lookups for variables appearing in C<eval '...'> within
-functions that were themselves called within an C<eval '...'> were
-searching the wrong place for lexicals. The lexical search now
-correctly ends at the subroutine's block boundary.
-
-The use of C<return> within C<eval {...}> caused $@ not to be reset
-correctly when no exception occurred within the eval. This has
-been fixed.
-
-Parsing of here documents used to be flawed when they appeared as
-the replacement expression in C<eval 's/.../.../e'>. This has
-been fixed.
-
-=head2 All compilation errors are true errors
-
-Some "errors" encountered at compile time were by necessity
-generated as warnings followed by eventual termination of the
-program. This enabled more such errors to be reported in a
-single run, rather than causing a hard stop at the first error
-that was encountered.
-
-The mechanism for reporting such errors has been reimplemented
-to queue compile-time errors and report them at the end of the
-compilation as true errors rather than as warnings. This fixes
-cases where error messages leaked through in the form of warnings
-when code was compiled at run time using C<eval STRING>, and
-also allows such errors to be reliably trapped using C<eval "...">.
-
-=head2 Implicitly closed filehandles are safer
-
-Sometimes implicitly closed filehandles (as when they are localized,
-and Perl automatically closes them on exiting the scope) could
-inadvertently set $? or $!. This has been corrected.
-
-
-=head2 Behavior of list slices is more consistent
-
-When taking a slice of a literal list (as opposed to a slice of
-an array or hash), Perl used to return an empty list if the
-result happened to be composed of all undef values.
-
-The new behavior is to produce an empty list if (and only if)
-the original list was empty. Consider the following example:
-
- @a = (1,undef,undef,2)[2,1,2];
-
-The old behavior would have resulted in @a having no elements.
-The new behavior ensures it has three undefined elements.
-
-Note in particular that the behavior of slices of the following
-cases remains unchanged:
-
- @a = ()[1,2];
- @a = (getpwent)[7,0];
- @a = (anything_returning_empty_list())[2,1,2];
- @a = @b[2,1,2];
- @a = @c{'a','b','c'};
-
-See L<perldata>.
-
-=head2 C<(\$)> prototype and C<$foo{a}>
-
-A scalar reference prototype now correctly allows a hash or
-array element in that slot.
-
-=head2 C<goto &sub> and AUTOLOAD
-
-The C<goto &sub> construct works correctly when C<&sub> happens
-to be autoloaded.
-
-=head2 C<-bareword> allowed under C<use integer>
-
-The autoquoting of barewords preceded by C<-> did not work
-in prior versions when the C<integer> pragma was enabled.
-This has been fixed.
-
-=head2 Failures in DESTROY()
-
-When code in a destructor threw an exception, it went unnoticed
-in earlier versions of Perl, unless someone happened to be
-looking in $@ just after the point the destructor happened to
-run. Such failures are now visible as warnings when warnings are
-enabled.
-
-=head2 Locale bugs fixed
-
-printf() and sprintf() previously reset the numeric locale
-back to the default "C" locale. This has been fixed.
-
-Numbers formatted according to the local numeric locale
-(such as using a decimal comma instead of a decimal dot) caused
-"isn't numeric" warnings, even while the operations accessing
-those numbers produced correct results. These warnings have been
-discontinued.
-
-=head2 Memory leaks
-
-The C<eval 'return sub {...}'> construct could sometimes leak
-memory. This has been fixed.
-
-Operations that aren't filehandle constructors used to leak memory
-when used on invalid filehandles. This has been fixed.
-
-Constructs that modified C<@_> could fail to deallocate values
-in C<@_> and thus leak memory. This has been corrected.
-
-=head2 Spurious subroutine stubs after failed subroutine calls
-
-Perl could sometimes create empty subroutine stubs when a
-subroutine was not found in the package. Such cases stopped
-later method lookups from progressing into base packages.
-This has been corrected.
-
-=head2 Taint failures under C<-U>
-
-When running in unsafe mode, taint violations could sometimes
-cause silent failures. This has been fixed.
-
-=head2 END blocks and the C<-c> switch
-
-Prior versions used to run BEGIN B<and> END blocks when Perl was
-run in compile-only mode. Since this is typically not the expected
-behavior, END blocks are not executed anymore when the C<-c> switch
-is used, or if compilation fails.
-
-See L</"Support for CHECK blocks"> for how to run things when the compile
-phase ends.
-
-=head2 Potential to leak DATA filehandles
-
-Using the C<__DATA__> token creates an implicit filehandle to
-the file that contains the token. It is the program's
-responsibility to close it when it is done reading from it.
-
-This caveat is now better explained in the documentation.
-See L<perldata>.
-
-=head1 New or Changed Diagnostics
-
-=over 4
-
-=item "%s" variable %s masks earlier declaration in same %s
-
-(W misc) A "my" or "our" variable has been redeclared in the current scope or statement,
-effectively eliminating all access to the previous instance. This is almost
-always a typographical error. Note that the earlier variable will still exist
-until the end of the scope or until all closure referents to it are
-destroyed.
-
-=item "my sub" not yet implemented
-
-(F) Lexically scoped subroutines are not yet implemented. Don't try that
-yet.
-
-=item "our" variable %s redeclared
-
-(W misc) You seem to have already declared the same global once before in the
-current lexical scope.
-
-=item '!' allowed only after types %s
-
-(F) The '!' is allowed in pack() and unpack() only after certain types.
-See L<perlfunc/pack>.
-
-=item / cannot take a count
-
-(F) You had an unpack template indicating a counted-length string,
-but you have also specified an explicit size for the string.
-See L<perlfunc/pack>.
-
-=item / must be followed by a, A or Z
-
-(F) You had an unpack template indicating a counted-length string,
-which must be followed by one of the letters a, A or Z
-to indicate what sort of string is to be unpacked.
-See L<perlfunc/pack>.
-
-=item / must be followed by a*, A* or Z*
-
-(F) You had a pack template indicating a counted-length string,
-Currently the only things that can have their length counted are a*, A* or Z*.
-See L<perlfunc/pack>.
-
-=item / must follow a numeric type
-
-(F) You had an unpack template that contained a '#',
-but this did not follow some numeric unpack specification.
-See L<perlfunc/pack>.
-
-=item /%s/: Unrecognized escape \\%c passed through
-
-(W regexp) You used a backslash-character combination which is not recognized
-by Perl. This combination appears in an interpolated variable or a
-C<'>-delimited regular expression. The character was understood literally.
-
-=item /%s/: Unrecognized escape \\%c in character class passed through
-
-(W regexp) You used a backslash-character combination which is not recognized
-by Perl inside character classes. The character was understood literally.
-
-=item /%s/ should probably be written as "%s"
-
-(W syntax) You have used a pattern where Perl expected to find a string,
-as in the first argument to C<join>. Perl will treat the true
-or false result of matching the pattern against $_ as the string,
-which is probably not what you had in mind.
-
-=item %s() called too early to check prototype
-
-(W prototype) You've called a function that has a prototype before the parser saw a
-definition or declaration for it, and Perl could not check that the call
-conforms to the prototype. You need to either add an early prototype
-declaration for the subroutine in question, or move the subroutine
-definition ahead of the call to get proper prototype checking. Alternatively,
-if you are certain that you're calling the function correctly, you may put
-an ampersand before the name to avoid the warning. See L<perlsub>.
-
-=item %s argument is not a HASH or ARRAY element
-
-(F) The argument to exists() must be a hash or array element, such as:
-
- $foo{$bar}
- $ref->{"susie"}[12]
-
-=item %s argument is not a HASH or ARRAY element or slice
-
-(F) The argument to delete() must be either a hash or array element, such as:
-
- $foo{$bar}
- $ref->{"susie"}[12]
-
-or a hash or array slice, such as:
-
- @foo[$bar, $baz, $xyzzy]
- @{$ref->[12]}{"susie", "queue"}
-
-=item %s argument is not a subroutine name
-
-(F) The argument to exists() for C<exists &sub> must be a subroutine
-name, and not a subroutine call. C<exists &sub()> will generate this error.
-
-=item %s package attribute may clash with future reserved word: %s
-
-(W reserved) A lowercase attribute name was used that had a package-specific handler.
-That name might have a meaning to Perl itself some day, even though it
-doesn't yet. Perhaps you should use a mixed-case attribute name, instead.
-See L<attributes>.
-
-=item (in cleanup) %s
-
-(W misc) This prefix usually indicates that a DESTROY() method raised
-the indicated exception. Since destructors are usually called by
-the system at arbitrary points during execution, and often a vast
-number of times, the warning is issued only once for any number
-of failures that would otherwise result in the same message being
-repeated.
-
-Failure of user callbacks dispatched using the C<G_KEEPERR> flag
-could also result in this warning. See L<perlcall/G_KEEPERR>.
-
-=item <> should be quotes
-
-(F) You wrote C<< require <file> >> when you should have written
-C<require 'file'>.
-
-=item Attempt to join self
-
-(F) You tried to join a thread from within itself, which is an
-impossible task. You may be joining the wrong thread, or you may
-need to move the join() to some other thread.
-
-=item Bad evalled substitution pattern
-
-(F) You've used the /e switch to evaluate the replacement for a
-substitution, but perl found a syntax error in the code to evaluate,
-most likely an unexpected right brace '}'.
-
-=item Bad realloc() ignored
-
-(S) An internal routine called realloc() on something that had never been
-malloc()ed in the first place. Mandatory, but can be disabled by
-setting environment variable C<PERL_BADFREE> to 1.
-
-=item Bareword found in conditional
-
-(W bareword) The compiler found a bareword where it expected a conditional,
-which often indicates that an || or && was parsed as part of the
-last argument of the previous construct, for example:
-
- open FOO || die;
-
-It may also indicate a misspelled constant that has been interpreted
-as a bareword:
-
- use constant TYPO => 1;
- if (TYOP) { print "foo" }
-
-The C<strict> pragma is useful in avoiding such errors.
-
-=item Binary number > 0b11111111111111111111111111111111 non-portable
-
-(W portable) The binary number you specified is larger than 2**32-1
-(4294967295) and therefore non-portable between systems. See
-L<perlport> for more on portability concerns.
-
-=item Bit vector size > 32 non-portable
-
-(W portable) Using bit vector sizes larger than 32 is non-portable.
-
-=item Buffer overflow in prime_env_iter: %s
-
-(W internal) A warning peculiar to VMS. While Perl was preparing to iterate over
-%ENV, it encountered a logical name or symbol definition which was too long,
-so it was truncated to the string shown.
-
-=item Can't check filesystem of script "%s"
-
-(P) For some reason you can't check the filesystem of the script for nosuid.
-
-=item Can't declare class for non-scalar %s in "%s"
-
-(S) Currently, only scalar variables can declared with a specific class
-qualifier in a "my" or "our" declaration. The semantics may be extended
-for other types of variables in future.
-
-=item Can't declare %s in "%s"
-
-(F) Only scalar, array, and hash variables may be declared as "my" or
-"our" variables. They must have ordinary identifiers as names.
-
-=item Can't ignore signal CHLD, forcing to default
-
-(W signal) Perl has detected that it is being run with the SIGCHLD signal
-(sometimes known as SIGCLD) disabled. Since disabling this signal
-will interfere with proper determination of exit status of child
-processes, Perl has reset the signal to its default value.
-This situation typically indicates that the parent program under
-which Perl may be running (e.g., cron) is being very careless.
-
-=item Can't modify non-lvalue subroutine call
-
-(F) Subroutines meant to be used in lvalue context should be declared as
-such, see L<perlsub/"Lvalue subroutines">.
-
-=item Can't read CRTL environ
-
-(S) A warning peculiar to VMS. Perl tried to read an element of %ENV
-from the CRTL's internal environment array and discovered the array was
-missing. You need to figure out where your CRTL misplaced its environ
-or define F<PERL_ENV_TABLES> (see L<perlvms>) so that environ is not searched.
-
-=item Can't remove %s: %s, skipping file
-
-(S) You requested an inplace edit without creating a backup file. Perl
-was unable to remove the original file to replace it with the modified
-file. The file was left unmodified.
-
-=item Can't return %s from lvalue subroutine
-
-(F) Perl detected an attempt to return illegal lvalues (such
-as temporary or readonly values) from a subroutine used as an lvalue.
-This is not allowed.
-
-=item Can't weaken a nonreference
-
-(F) You attempted to weaken something that was not a reference. Only
-references can be weakened.
-
-=item Character class [:%s:] unknown
-
-(F) The class in the character class [: :] syntax is unknown.
-See L<perlre>.
-
-=item Character class syntax [%s] belongs inside character classes
-
-(W unsafe) The character class constructs [: :], [= =], and [. .] go
-I<inside> character classes, the [] are part of the construct,
-for example: /[012[:alpha:]345]/. Note that [= =] and [. .]
-are not currently implemented; they are simply placeholders for
-future extensions.
-
-=item Constant is not %s reference
-
-(F) A constant value (perhaps declared using the C<use constant> pragma)
-is being dereferenced, but it amounts to the wrong type of reference. The
-message indicates the type of reference that was expected. This usually
-indicates a syntax error in dereferencing the constant value.
-See L<perlsub/"Constant Functions"> and L<constant>.
-
-=item constant(%s): %s
-
-(F) The parser found inconsistencies either while attempting to define an
-overloaded constant, or when trying to find the character name specified
-in the C<\N{...}> escape. Perhaps you forgot to load the corresponding
-C<overload> or C<charnames> pragma? See L<charnames> and L<overload>.
-
-=item CORE::%s is not a keyword
-
-(F) The CORE:: namespace is reserved for Perl keywords.
-
-=item defined(@array) is deprecated
-
-(D) defined() is not usually useful on arrays because it checks for an
-undefined I<scalar> value. If you want to see if the array is empty,
-just use C<if (@array) { # not empty }> for example.
-
-=item defined(%hash) is deprecated
-
-(D) defined() is not usually useful on hashes because it checks for an
-undefined I<scalar> value. If you want to see if the hash is empty,
-just use C<if (%hash) { # not empty }> for example.
-
-=item Did not produce a valid header
-
-See Server error.
-
-=item (Did you mean "local" instead of "our"?)
-
-(W misc) Remember that "our" does not localize the declared global variable.
-You have declared it again in the same lexical scope, which seems superfluous.
-
-=item Document contains no data
-
-See Server error.
-
-=item entering effective %s failed
-
-(F) While under the C<use filetest> pragma, switching the real and
-effective uids or gids failed.
-
-=item false [] range "%s" in regexp
-
-(W regexp) A character class range must start and end at a literal character, not
-another character class like C<\d> or C<[:alpha:]>. The "-" in your false
-range is interpreted as a literal "-". Consider quoting the "-", "\-".
-See L<perlre>.
-
-=item Filehandle %s opened only for output
-
-(W io) You tried to read from a filehandle opened only for writing. If you
-intended it to be a read/write filehandle, you needed to open it with
-"+<" or "+>" or "+>>" instead of with "<" or nothing. If
-you intended only to read from the file, use "<". See
-L<perlfunc/open>.
-
-=item flock() on closed filehandle %s
-
-(W closed) The filehandle you're attempting to flock() got itself closed some
-time before now. Check your logic flow. flock() operates on filehandles.
-Are you attempting to call flock() on a dirhandle by the same name?
-
-=item Global symbol "%s" requires explicit package name
-
-(F) You've said "use strict vars", which indicates that all variables
-must either be lexically scoped (using "my"), declared beforehand using
-"our", or explicitly qualified to say which package the global variable
-is in (using "::").
-
-=item Hexadecimal number > 0xffffffff non-portable
-
-(W portable) The hexadecimal number you specified is larger than 2**32-1
-(4294967295) and therefore non-portable between systems. See
-L<perlport> for more on portability concerns.
-
-=item Ill-formed CRTL environ value "%s"
-
-(W internal) A warning peculiar to VMS. Perl tried to read the CRTL's internal
-environ array, and encountered an element without the C<=> delimiter
-used to separate keys from values. The element is ignored.
-
-=item Ill-formed message in prime_env_iter: |%s|
-
-(W internal) A warning peculiar to VMS. Perl tried to read a logical name
-or CLI symbol definition when preparing to iterate over %ENV, and
-didn't see the expected delimiter between key and value, so the
-line was ignored.
-
-=item Illegal binary digit %s
-
-(F) You used a digit other than 0 or 1 in a binary number.
-
-=item Illegal binary digit %s ignored
-
-(W digit) You may have tried to use a digit other than 0 or 1 in a binary number.
-Interpretation of the binary number stopped before the offending digit.
-
-=item Illegal number of bits in vec
-
-(F) The number of bits in vec() (the third argument) must be a power of
-two from 1 to 32 (or 64, if your platform supports that).
-
-=item Integer overflow in %s number
-
-(W overflow) The hexadecimal, octal or binary number you have specified either
-as a literal or as an argument to hex() or oct() is too big for your
-architecture, and has been converted to a floating point number. On a
-32-bit architecture the largest hexadecimal, octal or binary number
-representable without overflow is 0xFFFFFFFF, 037777777777, or
-0b11111111111111111111111111111111 respectively. Note that Perl
-transparently promotes all numbers to a floating point representation
-internally--subject to loss of precision errors in subsequent
-operations.
-
-=item Invalid %s attribute: %s
-
-The indicated attribute for a subroutine or variable was not recognized
-by Perl or by a user-supplied handler. See L<attributes>.
-
-=item Invalid %s attributes: %s
-
-The indicated attributes for a subroutine or variable were not recognized
-by Perl or by a user-supplied handler. See L<attributes>.
-
-=item invalid [] range "%s" in regexp
-
-The offending range is now explicitly displayed.
-
-=item Invalid separator character %s in attribute list
-
-(F) Something other than a colon or whitespace was seen between the
-elements of an attribute list. If the previous attribute
-had a parenthesised parameter list, perhaps that list was terminated
-too soon. See L<attributes>.
-
-=item Invalid separator character %s in subroutine attribute list
-
-(F) Something other than a colon or whitespace was seen between the
-elements of a subroutine attribute list. If the previous attribute
-had a parenthesised parameter list, perhaps that list was terminated
-too soon.
-
-=item leaving effective %s failed
-
-(F) While under the C<use filetest> pragma, switching the real and
-effective uids or gids failed.
-
-=item Lvalue subs returning %s not implemented yet
-
-(F) Due to limitations in the current implementation, array and hash
-values cannot be returned in subroutines used in lvalue context.
-See L<perlsub/"Lvalue subroutines">.
-
-=item Method %s not permitted
-
-See Server error.
-
-=item Missing %sbrace%s on \N{}
-
-(F) Wrong syntax of character name literal C<\N{charname}> within
-double-quotish context.
-
-=item Missing command in piped open
-
-(W pipe) You used the C<open(FH, "| command")> or C<open(FH, "command |")>
-construction, but the command was missing or blank.
-
-=item Missing name in "my sub"
-
-(F) The reserved syntax for lexically scoped subroutines requires that they
-have a name with which they can be found.
-
-=item No %s specified for -%c
-
-(F) The indicated command line switch needs a mandatory argument, but
-you haven't specified one.
-
-=item No package name allowed for variable %s in "our"
-
-(F) Fully qualified variable names are not allowed in "our" declarations,
-because that doesn't make much sense under existing semantics. Such
-syntax is reserved for future extensions.
-
-=item No space allowed after -%c
-
-(F) The argument to the indicated command line switch must follow immediately
-after the switch, without intervening spaces.
-
-=item no UTC offset information; assuming local time is UTC
-
-(S) A warning peculiar to VMS. Perl was unable to find the local
-timezone offset, so it's assuming that local system time is equivalent
-to UTC. If it's not, define the logical name F<SYS$TIMEZONE_DIFFERENTIAL>
-to translate to the number of seconds which need to be added to UTC to
-get local time.
-
-=item Octal number > 037777777777 non-portable
-
-(W portable) The octal number you specified is larger than 2**32-1 (4294967295)
-and therefore non-portable between systems. See L<perlport> for more
-on portability concerns.
-
-See also L<perlport> for writing portable code.
-
-=item panic: del_backref
-
-(P) Failed an internal consistency check while trying to reset a weak
-reference.
-
-=item panic: kid popen errno read
-
-(F) forked child returned an incomprehensible message about its errno.
-
-=item panic: magic_killbackrefs
-
-(P) Failed an internal consistency check while trying to reset all weak
-references to an object.
-
-=item Parentheses missing around "%s" list
-
-(W parenthesis) You said something like
-
- my $foo, $bar = @_;
-
-when you meant
-
- my ($foo, $bar) = @_;
-
-Remember that "my", "our", and "local" bind tighter than comma.
-
-=item Possible unintended interpolation of %s in string
-
-(W ambiguous) It used to be that Perl would try to guess whether you
-wanted an array interpolated or a literal @. It no longer does this;
-arrays are now I<always> interpolated into strings. This means that
-if you try something like:
-
- print "fred@example.com";
-
-and the array C<@example> doesn't exist, Perl is going to print
-C<fred.com>, which is probably not what you wanted. To get a literal
-C<@> sign in a string, put a backslash before it, just as you would
-to get a literal C<$> sign.
-
-=item Possible Y2K bug: %s
-
-(W y2k) You are concatenating the number 19 with another number, which
-could be a potential Year 2000 problem.
-
-=item pragma "attrs" is deprecated, use "sub NAME : ATTRS" instead
-
-(W deprecated) You have written something like this:
-
- sub doit
- {
- use attrs qw(locked);
- }
-
-You should use the new declaration syntax instead.
-
- sub doit : locked
- {
- ...
-
-The C<use attrs> pragma is now obsolete, and is only provided for
-backward-compatibility. See L<perlsub/"Subroutine Attributes">.
-
-=item Premature end of script headers
-
-See Server error.
-
-=item Repeat count in pack overflows
-
-(F) You can't specify a repeat count so large that it overflows
-your signed integers. See L<perlfunc/pack>.
-
-=item Repeat count in unpack overflows
-
-(F) You can't specify a repeat count so large that it overflows
-your signed integers. See L<perlfunc/unpack>.
-
-=item realloc() of freed memory ignored
-
-(S) An internal routine called realloc() on something that had already
-been freed.
-
-=item Reference is already weak
-
-(W misc) You have attempted to weaken a reference that is already weak.
-Doing so has no effect.
-
-=item setpgrp can't take arguments
-
-(F) Your system has the setpgrp() from BSD 4.2, which takes no arguments,
-unlike POSIX setpgid(), which takes a process ID and process group ID.
-
-=item Strange *+?{} on zero-length expression
-
-(W regexp) You applied a regular expression quantifier in a place where it
-makes no sense, such as on a zero-width assertion.
-Try putting the quantifier inside the assertion instead. For example,
-the way to match "abc" provided that it is followed by three
-repetitions of "xyz" is C</abc(?=(?:xyz){3})/>, not C</abc(?=xyz){3}/>.
-
-=item switching effective %s is not implemented
-
-(F) While under the C<use filetest> pragma, we cannot switch the
-real and effective uids or gids.
-
-=item This Perl can't reset CRTL environ elements (%s)
-
-=item This Perl can't set CRTL environ elements (%s=%s)
-
-(W internal) Warnings peculiar to VMS. You tried to change or delete an element
-of the CRTL's internal environ array, but your copy of Perl wasn't
-built with a CRTL that contained the setenv() function. You'll need to
-rebuild Perl with a CRTL that does, or redefine F<PERL_ENV_TABLES> (see
-L<perlvms>) so that the environ array isn't the target of the change to
-%ENV which produced the warning.
-
-=item Too late to run %s block
-
-(W void) A CHECK or INIT block is being defined during run time proper,
-when the opportunity to run them has already passed. Perhaps you are
-loading a file with C<require> or C<do> when you should be using
-C<use> instead. Or perhaps you should put the C<require> or C<do>
-inside a BEGIN block.
-
-=item Unknown open() mode '%s'
-
-(F) The second argument of 3-argument open() is not among the list
-of valid modes: C<< < >>, C<< > >>, C<<< >> >>>, C<< +< >>,
-C<< +> >>, C<<< +>> >>>, C<-|>, C<|->.
-
-=item Unknown process %x sent message to prime_env_iter: %s
-
-(P) An error peculiar to VMS. Perl was reading values for %ENV before
-iterating over it, and someone else stuck a message in the stream of
-data Perl expected. Someone's very confused, or perhaps trying to
-subvert Perl's population of %ENV for nefarious purposes.
-
-=item Unrecognized escape \\%c passed through
-
-(W misc) You used a backslash-character combination which is not recognized
-by Perl. The character was understood literally.
-
-=item Unterminated attribute parameter in attribute list
-
-(F) The lexer saw an opening (left) parenthesis character while parsing an
-attribute list, but the matching closing (right) parenthesis
-character was not found. You may need to add (or remove) a backslash
-character to get your parentheses to balance. See L<attributes>.
-
-=item Unterminated attribute list
-
-(F) The lexer found something other than a simple identifier at the start
-of an attribute, and it wasn't a semicolon or the start of a
-block. Perhaps you terminated the parameter list of the previous attribute
-too soon. See L<attributes>.
-
-=item Unterminated attribute parameter in subroutine attribute list
-
-(F) The lexer saw an opening (left) parenthesis character while parsing a
-subroutine attribute list, but the matching closing (right) parenthesis
-character was not found. You may need to add (or remove) a backslash
-character to get your parentheses to balance.
-
-=item Unterminated subroutine attribute list
-
-(F) The lexer found something other than a simple identifier at the start
-of a subroutine attribute, and it wasn't a semicolon or the start of a
-block. Perhaps you terminated the parameter list of the previous attribute
-too soon.
-
-=item Value of CLI symbol "%s" too long
-
-(W misc) A warning peculiar to VMS. Perl tried to read the value of an %ENV
-element from a CLI symbol table, and found a resultant string longer
-than 1024 characters. The return value has been truncated to 1024
-characters.
-
-=item Version number must be a constant number
-
-(P) The attempt to translate a C<use Module n.n LIST> statement into
-its equivalent C<BEGIN> block found an internal inconsistency with
-the version number.
-
-=back
-
-=head1 New tests
-
-=over 4
-
-=item lib/attrs
-
-Compatibility tests for C<sub : attrs> vs the older C<use attrs>.
-
-=item lib/env
-
-Tests for new environment scalar capability (e.g., C<use Env qw($BAR);>).
-
-=item lib/env-array
-
-Tests for new environment array capability (e.g., C<use Env qw(@PATH);>).
-
-=item lib/io_const
-
-IO constants (SEEK_*, _IO*).
-
-=item lib/io_dir
-
-Directory-related IO methods (new, read, close, rewind, tied delete).
-
-=item lib/io_multihomed
-
-INET sockets with multi-homed hosts.
-
-=item lib/io_poll
-
-IO poll().
-
-=item lib/io_unix
-
-UNIX sockets.
-
-=item op/attrs
-
-Regression tests for C<my ($x,@y,%z) : attrs> and <sub : attrs>.
-
-=item op/filetest
-
-File test operators.
-
-=item op/lex_assign
-
-Verify operations that access pad objects (lexicals and temporaries).
-
-=item op/exists_sub
-
-Verify C<exists &sub> operations.
-
-=back
-
-=head1 Incompatible Changes
-
-=head2 Perl Source Incompatibilities
-
-Beware that any new warnings that have been added or old ones
-that have been enhanced are B<not> considered incompatible changes.
-
-Since all new warnings must be explicitly requested via the C<-w>
-switch or the C<warnings> pragma, it is ultimately the programmer's
-responsibility to ensure that warnings are enabled judiciously.
-
-=over 4
-
-=item CHECK is a new keyword
-
-All subroutine definitions named CHECK are now special. See
-C</"Support for CHECK blocks"> for more information.
-
-=item Treatment of list slices of undef has changed
-
-There is a potential incompatibility in the behavior of list slices
-that are comprised entirely of undefined values.
-See L</"Behavior of list slices is more consistent">.
-
-=item Format of $English::PERL_VERSION is different
-
-The English module now sets $PERL_VERSION to $^V (a string value) rather
-than C<$]> (a numeric value). This is a potential incompatibility.
-Send us a report via perlbug if you are affected by this.
-
-See L</"Improved Perl version numbering system"> for the reasons for
-this change.
-
-=item Literals of the form C<1.2.3> parse differently
-
-Previously, numeric literals with more than one dot in them were
-interpreted as a floating point number concatenated with one or more
-numbers. Such "numbers" are now parsed as strings composed of the
-specified ordinals.
-
-For example, C<print 97.98.99> used to output C<97.9899> in earlier
-versions, but now prints C<abc>.
-
-See L</"Support for strings represented as a vector of ordinals">.
-
-=item Possibly changed pseudo-random number generator
-
-Perl programs that depend on reproducing a specific set of pseudo-random
-numbers may now produce different output due to improvements made to the
-rand() builtin. You can use C<sh Configure -Drandfunc=rand> to obtain
-the old behavior.
-
-See L</"Better pseudo-random number generator">.
-
-=item Hashing function for hash keys has changed
-
-Even though Perl hashes are not order preserving, the apparently
-random order encountered when iterating on the contents of a hash
-is actually determined by the hashing algorithm used. Improvements
-in the algorithm may yield a random order that is B<different> from
-that of previous versions, especially when iterating on hashes.
-
-See L</"Better worst-case behavior of hashes"> for additional
-information.
-
-=item C<undef> fails on read only values
-
-Using the C<undef> operator on a readonly value (such as $1) has
-the same effect as assigning C<undef> to the readonly value--it
-throws an exception.
-
-=item Close-on-exec bit may be set on pipe and socket handles
-
-Pipe and socket handles are also now subject to the close-on-exec
-behavior determined by the special variable $^F.
-
-See L</"More consistent close-on-exec behavior">.
-
-=item Writing C<"$$1"> to mean C<"${$}1"> is unsupported
-
-Perl 5.004 deprecated the interpretation of C<$$1> and
-similar within interpolated strings to mean C<$$ . "1">,
-but still allowed it.
-
-In Perl 5.6.0 and later, C<"$$1"> always means C<"${$1}">.
-
-=item delete(), each(), values() and C<\(%h)>
-
-operate on aliases to values, not copies
-
-delete(), each(), values() and hashes (e.g. C<\(%h)>)
-in a list context return the actual
-values in the hash, instead of copies (as they used to in earlier
-versions). Typical idioms for using these constructs copy the
-returned values, but this can make a significant difference when
-creating references to the returned values. Keys in the hash are still
-returned as copies when iterating on a hash.
-
-See also L</"delete(), each(), values() and hash iteration are faster">.
-
-=item vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS
-
-vec() generates a run-time error if the BITS argument is not
-a valid power-of-two integer.
-
-=item Text of some diagnostic output has changed
-
-Most references to internal Perl operations in diagnostics
-have been changed to be more descriptive. This may be an
-issue for programs that may incorrectly rely on the exact
-text of diagnostics for proper functioning.
-
-=item C<%@> has been removed
-
-The undocumented special variable C<%@> that used to accumulate
-"background" errors (such as those that happen in DESTROY())
-has been removed, because it could potentially result in memory
-leaks.
-
-=item Parenthesized not() behaves like a list operator
-
-The C<not> operator now falls under the "if it looks like a function,
-it behaves like a function" rule.
-
-As a result, the parenthesized form can be used with C<grep> and C<map>.
-The following construct used to be a syntax error before, but it works
-as expected now:
-
- grep not($_), @things;
-
-On the other hand, using C<not> with a literal list slice may not
-work. The following previously allowed construct:
-
- print not (1,2,3)[0];
-
-needs to be written with additional parentheses now:
-
- print not((1,2,3)[0]);
-
-The behavior remains unaffected when C<not> is not followed by parentheses.
-
-=item Semantics of bareword prototype C<(*)> have changed
-
-The semantics of the bareword prototype C<*> have changed. Perl 5.005
-always coerced simple scalar arguments to a typeglob, which wasn't useful
-in situations where the subroutine must distinguish between a simple
-scalar and a typeglob. The new behavior is to not coerce bareword
-arguments to a typeglob. The value will always be visible as either
-a simple scalar or as a reference to a typeglob.
-
-See L</"More functional bareword prototype (*)">.
-
-=item Semantics of bit operators may have changed on 64-bit platforms
-
-If your platform is either natively 64-bit or if Perl has been
-configured to used 64-bit integers, i.e., $Config{ivsize} is 8,
-there may be a potential incompatibility in the behavior of bitwise
-numeric operators (& | ^ ~ << >>). These operators used to strictly
-operate on the lower 32 bits of integers in previous versions, but now
-operate over the entire native integral width. In particular, note
-that unary C<~> will produce different results on platforms that have
-different $Config{ivsize}. For portability, be sure to mask off
-the excess bits in the result of unary C<~>, e.g., C<~$x & 0xffffffff>.
-
-See L</"Bit operators support full native integer width">.
-
-=item More builtins taint their results
-
-As described in L</"Improved security features">, there may be more
-sources of taint in a Perl program.
-
-To avoid these new tainting behaviors, you can build Perl with the
-Configure option C<-Accflags=-DINCOMPLETE_TAINTS>. Beware that the
-ensuing perl binary may be insecure.
-
-=back
-
-=head2 C Source Incompatibilities
-
-=over 4
-
-=item C<PERL_POLLUTE>
-
-Release 5.005 grandfathered old global symbol names by providing preprocessor
-macros for extension source compatibility. As of release 5.6.0, these
-preprocessor definitions are not available by default. You need to explicitly
-compile perl with C<-DPERL_POLLUTE> to get these definitions. For
-extensions still using the old symbols, this option can be
-specified via MakeMaker:
-
- perl Makefile.PL POLLUTE=1
-
-=item C<PERL_IMPLICIT_CONTEXT>
-
-This new build option provides a set of macros for all API functions
-such that an implicit interpreter/thread context argument is passed to
-every API function. As a result of this, something like C<sv_setsv(foo,bar)>
-amounts to a macro invocation that actually translates to something like
-C<Perl_sv_setsv(my_perl,foo,bar)>. While this is generally expected
-to not have any significant source compatibility issues, the difference
-between a macro and a real function call will need to be considered.
-
-This means that there B<is> a source compatibility issue as a result of
-this if your extensions attempt to use pointers to any of the Perl API
-functions.
-
-Note that the above issue is not relevant to the default build of
-Perl, whose interfaces continue to match those of prior versions
-(but subject to the other options described here).
-
-See L<perlguts/Background and PERL_IMPLICIT_CONTEXT> for detailed information
-on the ramifications of building Perl with this option.
-
- NOTE: PERL_IMPLICIT_CONTEXT is automatically enabled whenever Perl is built
- with one of -Dusethreads, -Dusemultiplicity, or both. It is not
- intended to be enabled by users at this time.
-
-=item C<PERL_POLLUTE_MALLOC>
-
-Enabling Perl's malloc in release 5.005 and earlier caused the namespace of
-the system's malloc family of functions to be usurped by the Perl versions,
-since by default they used the same names. Besides causing problems on
-platforms that do not allow these functions to be cleanly replaced, this
-also meant that the system versions could not be called in programs that
-used Perl's malloc. Previous versions of Perl have allowed this behaviour
-to be suppressed with the HIDEMYMALLOC and EMBEDMYMALLOC preprocessor
-definitions.
-
-As of release 5.6.0, Perl's malloc family of functions have default names
-distinct from the system versions. You need to explicitly compile perl with
-C<-DPERL_POLLUTE_MALLOC> to get the older behaviour. HIDEMYMALLOC
-and EMBEDMYMALLOC have no effect, since the behaviour they enabled is now
-the default.
-
-Note that these functions do B<not> constitute Perl's memory allocation API.
-See L<perlguts/"Memory Allocation"> for further information about that.
-
-=back
-
-=head2 Compatible C Source API Changes
-
-=over 4
-
-=item C<PATCHLEVEL> is now C<PERL_VERSION>
-
-The cpp macros C<PERL_REVISION>, C<PERL_VERSION>, and C<PERL_SUBVERSION>
-are now available by default from perl.h, and reflect the base revision,
-patchlevel, and subversion respectively. C<PERL_REVISION> had no
-prior equivalent, while C<PERL_VERSION> and C<PERL_SUBVERSION> were
-previously available as C<PATCHLEVEL> and C<SUBVERSION>.
-
-The new names cause less pollution of the B<cpp> namespace and reflect what
-the numbers have come to stand for in common practice. For compatibility,
-the old names are still supported when F<patchlevel.h> is explicitly
-included (as required before), so there is no source incompatibility
-from the change.
-
-=back
-
-=head2 Binary Incompatibilities
-
-In general, the default build of this release is expected to be binary
-compatible for extensions built with the 5.005 release or its maintenance
-versions. However, specific platforms may have broken binary compatibility
-due to changes in the defaults used in hints files. Therefore, please be
-sure to always check the platform-specific README files for any notes to
-the contrary.
-
-The usethreads or usemultiplicity builds are B<not> binary compatible
-with the corresponding builds in 5.005.
-
-On platforms that require an explicit list of exports (AIX, OS/2 and Windows,
-among others), purely internal symbols such as parser functions and the
-run time opcodes are not exported by default. Perl 5.005 used to export
-all functions irrespective of whether they were considered part of the
-public API or not.
-
-For the full list of public API functions, see L<perlapi>.
-
-=head1 Known Problems
-
-=head2 Localizing a tied hash element may leak memory
-
-As of the 5.6.1 release, there is a known leak when code such as this
-is executed:
-
- use Tie::Hash;
- tie my %tie_hash => 'Tie::StdHash';
-
- ...
-
- local($tie_hash{Foo}) = 1; # leaks
-
-=head2 Known test failures
-
-=over
-
-=item *
-
-64-bit builds
-
-Subtest #15 of lib/b.t may fail under 64-bit builds on platforms such
-as HP-UX PA64 and Linux IA64. The issue is still being investigated.
-
-The lib/io_multihomed test may hang in HP-UX if Perl has been
-configured to be 64-bit. Because other 64-bit platforms do not
-hang in this test, HP-UX is suspect. All other tests pass
-in 64-bit HP-UX. The test attempts to create and connect to
-"multihomed" sockets (sockets which have multiple IP addresses).
-
-Note that 64-bit support is still experimental.
-
-=item *
-
-Failure of Thread tests
-
-The subtests 19 and 20 of lib/thr5005.t test are known to fail due to
-fundamental problems in the 5.005 threading implementation. These are
-not new failures--Perl 5.005_0x has the same bugs, but didn't have these
-tests. (Note that support for 5.005-style threading remains experimental.)
-
-=item *
-
-NEXTSTEP 3.3 POSIX test failure
-
-In NEXTSTEP 3.3p2 the implementation of the strftime(3) in the
-operating system libraries is buggy: the %j format numbers the days of
-a month starting from zero, which, while being logical to programmers,
-will cause the subtests 19 to 27 of the lib/posix test may fail.
-
-=item *
-
-Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with gcc
-
-If compiled with gcc 2.95 the lib/sdbm test will fail (dump core).
-The cure is to use the vendor cc, it comes with the operating system
-and produces good code.
-
-=back
-
-=head2 EBCDIC platforms not fully supported
-
-In earlier releases of Perl, EBCDIC environments like OS390 (also
-known as Open Edition MVS) and VM-ESA were supported. Due to changes
-required by the UTF-8 (Unicode) support, the EBCDIC platforms are not
-supported in Perl 5.6.0.
-
-The 5.6.1 release improves support for EBCDIC platforms, but they
-are not fully supported yet.
-
-=head2 UNICOS/mk CC failures during Configure run
-
-In UNICOS/mk the following errors may appear during the Configure run:
-
- Guessing which symbols your C compiler and preprocessor define...
- CC-20 cc: ERROR File = try.c, Line = 3
- ...
- bad switch yylook 79bad switch yylook 79bad switch yylook 79bad switch yylook 79#ifdef A29K
- ...
- 4 errors detected in the compilation of "try.c".
-
-The culprit is the broken awk of UNICOS/mk. The effect is fortunately
-rather mild: Perl itself is not adversely affected by the error, only
-the h2ph utility coming with Perl, and that is rather rarely needed
-these days.
-
-=head2 Arrow operator and arrays
-
-When the left argument to the arrow operator C<< -> >> is an array, or
-the C<scalar> operator operating on an array, the result of the
-operation must be considered erroneous. For example:
-
- @x->[2]
- scalar(@x)->[2]
-
-These expressions will get run-time errors in some future release of
-Perl.
-
-=head2 Experimental features
-
-As discussed above, many features are still experimental. Interfaces and
-implementation of these features are subject to change, and in extreme cases,
-even subject to removal in some future release of Perl. These features
-include the following:
-
-=over 4
-
-=item Threads
-
-=item Unicode
-
-=item 64-bit support
-
-=item Lvalue subroutines
-
-=item Weak references
-
-=item The pseudo-hash data type
-
-=item The Compiler suite
-
-=item Internal implementation of file globbing
-
-=item The DB module
-
-=item The regular expression code constructs:
-
-C<(?{ code })> and C<(??{ code })>
-
-=back
-
-=head1 Obsolete Diagnostics
-
-=over 4
-
-=item Character class syntax [: :] is reserved for future extensions
-
-(W) Within regular expression character classes ([]) the syntax beginning
-with "[:" and ending with ":]" is reserved for future extensions.
-If you need to represent those character sequences inside a regular
-expression character class, just quote the square brackets with the
-backslash: "\[:" and ":\]".
-
-=item Ill-formed logical name |%s| in prime_env_iter
-
-(W) A warning peculiar to VMS. A logical name was encountered when preparing
-to iterate over %ENV which violates the syntactic rules governing logical
-names. Because it cannot be translated normally, it is skipped, and will not
-appear in %ENV. This may be a benign occurrence, as some software packages
-might directly modify logical name tables and introduce nonstandard names,
-or it may indicate that a logical name table has been corrupted.
-
-=item In string, @%s now must be written as \@%s
-
-The description of this error used to say:
-
- (Someday it will simply assume that an unbackslashed @
- interpolates an array.)
-
-That day has come, and this fatal error has been removed. It has been
-replaced by a non-fatal warning instead.
-See L</Arrays now always interpolate into double-quoted strings> for
-details.
-
-=item Probable precedence problem on %s
-
-(W) The compiler found a bareword where it expected a conditional,
-which often indicates that an || or && was parsed as part of the
-last argument of the previous construct, for example:
-
- open FOO || die;
-
-=item regexp too big
-
-(F) The current implementation of regular expressions uses shorts as
-address offsets within a string. Unfortunately this means that if
-the regular expression compiles to longer than 32767, it'll blow up.
-Usually when you want a regular expression this big, there is a better
-way to do it with multiple statements. See L<perlre>.
-
-=item Use of "$$<digit>" to mean "${$}<digit>" is deprecated
-
-(D) Perl versions before 5.004 misinterpreted any type marker followed
-by "$" and a digit. For example, "$$0" was incorrectly taken to mean
-"${$}0" instead of "${$0}". This bug is (mostly) fixed in Perl 5.004.
-
-However, the developers of Perl 5.004 could not fix this bug completely,
-because at least two widely-used modules depend on the old meaning of
-"$$0" in a string. So Perl 5.004 still interprets "$$<digit>" in the
-old (broken) way inside strings; but it generates this message as a
-warning. And in Perl 5.005, this special treatment will cease.
-
-=back
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the
-articles recently posted to the comp.lang.perl.misc newsgroup.
-There may also be information at http://www.perl.com/ , the Perl
-Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team.
-
-=head1 SEE ALSO
-
-The F<Changes> file for exhaustive details on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=head1 HISTORY
-
-Written by Gurusamy Sarathy <F<gsar@ActiveState.com>>, with many
-contributions from The Perl Porters.
-
-Send omissions or corrections to <F<perlbug@perl.org>>.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl56delta.pod b/Master/tlpkg/tlperl/lib/pods/perl56delta.pod
deleted file mode 100644
index 24c2072c253..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl56delta.pod
+++ /dev/null
@@ -1,3022 +0,0 @@
-=head1 NAME
-
-perl56delta - what's new for perl v5.6.0
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.005 release and the 5.6.0
-release.
-
-=head1 Core Enhancements
-
-=head2 Interpreter cloning, threads, and concurrency
-
-Perl 5.6.0 introduces the beginnings of support for running multiple
-interpreters concurrently in different threads. In conjunction with
-the perl_clone() API call, which can be used to selectively duplicate
-the state of any given interpreter, it is possible to compile a
-piece of code once in an interpreter, clone that interpreter
-one or more times, and run all the resulting interpreters in distinct
-threads.
-
-On the Windows platform, this feature is used to emulate fork() at the
-interpreter level. See L<perlfork> for details about that.
-
-This feature is still in evolution. It is eventually meant to be used
-to selectively clone a subroutine and data reachable from that
-subroutine in a separate interpreter and run the cloned subroutine
-in a separate thread. Since there is no shared data between the
-interpreters, little or no locking will be needed (unless parts of
-the symbol table are explicitly shared). This is obviously intended
-to be an easy-to-use replacement for the existing threads support.
-
-Support for cloning interpreters and interpreter concurrency can be
-enabled using the -Dusethreads Configure option (see win32/Makefile for
-how to enable it on Windows.) The resulting perl executable will be
-functionally identical to one that was built with -Dmultiplicity, but
-the perl_clone() API call will only be available in the former.
-
--Dusethreads enables the cpp macro USE_ITHREADS by default, which in turn
-enables Perl source code changes that provide a clear separation between
-the op tree and the data it operates with. The former is immutable, and
-can therefore be shared between an interpreter and all of its clones,
-while the latter is considered local to each interpreter, and is therefore
-copied for each clone.
-
-Note that building Perl with the -Dusemultiplicity Configure option
-is adequate if you wish to run multiple B<independent> interpreters
-concurrently in different threads. -Dusethreads only provides the
-additional functionality of the perl_clone() API call and other
-support for running B<cloned> interpreters concurrently.
-
- NOTE: This is an experimental feature. Implementation details are
- subject to change.
-
-=head2 Lexically scoped warning categories
-
-You can now control the granularity of warnings emitted by perl at a finer
-level using the C<use warnings> pragma. L<warnings> and L<perllexwarn>
-have copious documentation on this feature.
-
-=head2 Unicode and UTF-8 support
-
-Perl now uses UTF-8 as its internal representation for character
-strings. The C<utf8> and C<bytes> pragmas are used to control this support
-in the current lexical scope. See L<perlunicode>, L<utf8> and L<bytes> for
-more information.
-
-This feature is expected to evolve quickly to support some form of I/O
-disciplines that can be used to specify the kind of input and output data
-(bytes or characters). Until that happens, additional modules from CPAN
-will be needed to complete the toolkit for dealing with Unicode.
-
- NOTE: This should be considered an experimental feature. Implementation
- details are subject to change.
-
-=head2 Support for interpolating named characters
-
-The new C<\N> escape interpolates named characters within strings.
-For example, C<"Hi! \N{WHITE SMILING FACE}"> evaluates to a string
-with a unicode smiley face at the end.
-
-=head2 "our" declarations
-
-An "our" declaration introduces a value that can be best understood
-as a lexically scoped symbolic alias to a global variable in the
-package that was current where the variable was declared. This is
-mostly useful as an alternative to the C<vars> pragma, but also provides
-the opportunity to introduce typing and other attributes for such
-variables. See L<perlfunc/our>.
-
-=head2 Support for strings represented as a vector of ordinals
-
-Literals of the form C<v1.2.3.4> are now parsed as a string composed
-of characters with the specified ordinals. This is an alternative, more
-readable way to construct (possibly unicode) strings instead of
-interpolating characters, as in C<"\x{1}\x{2}\x{3}\x{4}">. The leading
-C<v> may be omitted if there are more than two ordinals, so C<1.2.3> is
-parsed the same as C<v1.2.3>.
-
-Strings written in this form are also useful to represent version "numbers".
-It is easy to compare such version "numbers" (which are really just plain
-strings) using any of the usual string comparison operators C<eq>, C<ne>,
-C<lt>, C<gt>, etc., or perform bitwise string operations on them using C<|>,
-C<&>, etc.
-
-In conjunction with the new C<$^V> magic variable (which contains
-the perl version as a string), such literals can be used as a readable way
-to check if you're running a particular version of Perl:
-
- # this will parse in older versions of Perl also
- if ($^V and $^V gt v5.6.0) {
- # new features supported
- }
-
-C<require> and C<use> also have some special magic to support such
-literals, but this particular usage should be avoided because it leads to
-misleading error messages under versions of Perl which don't support vector
-strings. Using a true version number will ensure correct behavior in all
-versions of Perl:
-
- require 5.006; # run time check for v5.6
- use 5.006_001; # compile time check for v5.6.1
-
-Also, C<sprintf> and C<printf> support the Perl-specific format flag C<%v>
-to print ordinals of characters in arbitrary strings:
-
- printf "v%vd", $^V; # prints current version, such as "v5.5.650"
- printf "%*vX", ":", $addr; # formats IPv6 address
- printf "%*vb", " ", $bits; # displays bitstring
-
-See L<perldata/"Scalar value constructors"> for additional information.
-
-=head2 Improved Perl version numbering system
-
-Beginning with Perl version 5.6.0, the version number convention has been
-changed to a "dotted integer" scheme that is more commonly found in open
-source projects.
-
-Maintenance versions of v5.6.0 will be released as v5.6.1, v5.6.2 etc.
-The next development series following v5.6.0 will be numbered v5.7.x,
-beginning with v5.7.0, and the next major production release following
-v5.6.0 will be v5.8.0.
-
-The English module now sets $PERL_VERSION to $^V (a string value) rather
-than C<$]> (a numeric value). (This is a potential incompatibility.
-Send us a report via perlbug if you are affected by this.)
-
-The v1.2.3 syntax is also now legal in Perl.
-See L<Support for strings represented as a vector of ordinals> for more on that.
-
-To cope with the new versioning system's use of at least three significant
-digits for each version component, the method used for incrementing the
-subversion number has also changed slightly. We assume that versions older
-than v5.6.0 have been incrementing the subversion component in multiples of
-10. Versions after v5.6.0 will increment them by 1. Thus, using the new
-notation, 5.005_03 is the "same" as v5.5.30, and the first maintenance
-version following v5.6.0 will be v5.6.1 (which should be read as being
-equivalent to a floating point value of 5.006_001 in the older format,
-stored in C<$]>).
-
-=head2 New syntax for declaring subroutine attributes
-
-Formerly, if you wanted to mark a subroutine as being a method call or
-as requiring an automatic lock() when it is entered, you had to declare
-that with a C<use attrs> pragma in the body of the subroutine.
-That can now be accomplished with declaration syntax, like this:
-
- sub mymethod : locked method;
- ...
- sub mymethod : locked method {
- ...
- }
-
- sub othermethod :locked :method;
- ...
- sub othermethod :locked :method {
- ...
- }
-
-
-(Note how only the first C<:> is mandatory, and whitespace surrounding
-the C<:> is optional.)
-
-F<AutoSplit.pm> and F<SelfLoader.pm> have been updated to keep the attributes
-with the stubs they provide. See L<attributes>.
-
-=head2 File and directory handles can be autovivified
-
-Similar to how constructs such as C<< $x->[0] >> autovivify a reference,
-handle constructors (open(), opendir(), pipe(), socketpair(), sysopen(),
-socket(), and accept()) now autovivify a file or directory handle
-if the handle passed to them is an uninitialized scalar variable. This
-allows the constructs such as C<open(my $fh, ...)> and C<open(local $fh,...)>
-to be used to create filehandles that will conveniently be closed
-automatically when the scope ends, provided there are no other references
-to them. This largely eliminates the need for typeglobs when opening
-filehandles that must be passed around, as in the following example:
-
- sub myopen {
- open my $fh, "@_"
- or die "Can't open '@_': $!";
- return $fh;
- }
-
- {
- my $f = myopen("</etc/motd");
- print <$f>;
- # $f implicitly closed here
- }
-
-=head2 open() with more than two arguments
-
-If open() is passed three arguments instead of two, the second argument
-is used as the mode and the third argument is taken to be the file name.
-This is primarily useful for protecting against unintended magic behavior
-of the traditional two-argument form. See L<perlfunc/open>.
-
-=head2 64-bit support
-
-Any platform that has 64-bit integers either
-
- (1) natively as longs or ints
- (2) via special compiler flags
- (3) using long long or int64_t
-
-is able to use "quads" (64-bit integers) as follows:
-
-=over 4
-
-=item *
-
-constants (decimal, hexadecimal, octal, binary) in the code
-
-=item *
-
-arguments to oct() and hex()
-
-=item *
-
-arguments to print(), printf() and sprintf() (flag prefixes ll, L, q)
-
-=item *
-
-printed as such
-
-=item *
-
-pack() and unpack() "q" and "Q" formats
-
-=item *
-
-in basic arithmetics: + - * / % (NOTE: operating close to the limits
-of the integer values may produce surprising results)
-
-=item *
-
-in bit arithmetics: & | ^ ~ << >> (NOTE: these used to be forced
-to be 32 bits wide but now operate on the full native width.)
-
-=item *
-
-vec()
-
-=back
-
-Note that unless you have the case (a) you will have to configure
-and compile Perl using the -Duse64bitint Configure flag.
-
- NOTE: The Configure flags -Duselonglong and -Duse64bits have been
- deprecated. Use -Duse64bitint instead.
-
-There are actually two modes of 64-bitness: the first one is achieved
-using Configure -Duse64bitint and the second one using Configure
--Duse64bitall. The difference is that the first one is minimal and
-the second one maximal. The first works in more places than the second.
-
-The C<use64bitint> does only as much as is required to get 64-bit
-integers into Perl (this may mean, for example, using "long longs")
-while your memory may still be limited to 2 gigabytes (because your
-pointers could still be 32-bit). Note that the name C<64bitint> does
-not imply that your C compiler will be using 64-bit C<int>s (it might,
-but it doesn't have to): the C<use64bitint> means that you will be
-able to have 64 bits wide scalar values.
-
-The C<use64bitall> goes all the way by attempting to switch also
-integers (if it can), longs (and pointers) to being 64-bit. This may
-create an even more binary incompatible Perl than -Duse64bitint: the
-resulting executable may not run at all in a 32-bit box, or you may
-have to reboot/reconfigure/rebuild your operating system to be 64-bit
-aware.
-
-Natively 64-bit systems like Alpha and Cray need neither -Duse64bitint
-nor -Duse64bitall.
-
-Last but not least: note that due to Perl's habit of always using
-floating point numbers, the quads are still not true integers.
-When quads overflow their limits (0...18_446_744_073_709_551_615 unsigned,
--9_223_372_036_854_775_808...9_223_372_036_854_775_807 signed), they
-are silently promoted to floating point numbers, after which they will
-start losing precision (in their lower digits).
-
- NOTE: 64-bit support is still experimental on most platforms.
- Existing support only covers the LP64 data model. In particular, the
- LLP64 data model is not yet supported. 64-bit libraries and system
- APIs on many platforms have not stabilized--your mileage may vary.
-
-=head2 Large file support
-
-If you have filesystems that support "large files" (files larger than
-2 gigabytes), you may now also be able to create and access them from
-Perl.
-
- NOTE: The default action is to enable large file support, if
- available on the platform.
-
-If the large file support is on, and you have a Fcntl constant
-O_LARGEFILE, the O_LARGEFILE is automatically added to the flags
-of sysopen().
-
-Beware that unless your filesystem also supports "sparse files" seeking
-to umpteen petabytes may be inadvisable.
-
-Note that in addition to requiring a proper file system to do large
-files you may also need to adjust your per-process (or your
-per-system, or per-process-group, or per-user-group) maximum filesize
-limits before running Perl scripts that try to handle large files,
-especially if you intend to write such files.
-
-Finally, in addition to your process/process group maximum filesize
-limits, you may have quota limits on your filesystems that stop you
-(your user id or your user group id) from using large files.
-
-Adjusting your process/user/group/file system/operating system limits
-is outside the scope of Perl core language. For process limits, you
-may try increasing the limits using your shell's limits/limit/ulimit
-command before running Perl. The BSD::Resource extension (not
-included with the standard Perl distribution) may also be of use, it
-offers the getrlimit/setrlimit interface that can be used to adjust
-process resource usage limits, including the maximum filesize limit.
-
-=head2 Long doubles
-
-In some systems you may be able to use long doubles to enhance the
-range and precision of your double precision floating point numbers
-(that is, Perl's numbers). Use Configure -Duselongdouble to enable
-this support (if it is available).
-
-=head2 "more bits"
-
-You can "Configure -Dusemorebits" to turn on both the 64-bit support
-and the long double support.
-
-=head2 Enhanced support for sort() subroutines
-
-Perl subroutines with a prototype of C<($$)>, and XSUBs in general, can
-now be used as sort subroutines. In either case, the two elements to
-be compared are passed as normal parameters in @_. See L<perlfunc/sort>.
-
-For unprototyped sort subroutines, the historical behavior of passing
-the elements to be compared as the global variables $a and $b remains
-unchanged.
-
-=head2 C<sort $coderef @foo> allowed
-
-sort() did not accept a subroutine reference as the comparison
-function in earlier versions. This is now permitted.
-
-=head2 File globbing implemented internally
-
-Perl now uses the File::Glob implementation of the glob() operator
-automatically. This avoids using an external csh process and the
-problems associated with it.
-
- NOTE: This is currently an experimental feature. Interfaces and
- implementation are subject to change.
-
-=head2 Support for CHECK blocks
-
-In addition to C<BEGIN>, C<INIT>, C<END>, C<DESTROY> and C<AUTOLOAD>,
-subroutines named C<CHECK> are now special. These are queued up during
-compilation and behave similar to END blocks, except they are called at
-the end of compilation rather than at the end of execution. They cannot
-be called directly.
-
-=head2 POSIX character class syntax [: :] supported
-
-For example to match alphabetic characters use /[[:alpha:]]/.
-See L<perlre> for details.
-
-=head2 Better pseudo-random number generator
-
-In 5.005_0x and earlier, perl's rand() function used the C library
-rand(3) function. As of 5.005_52, Configure tests for drand48(),
-random(), and rand() (in that order) and picks the first one it finds.
-
-These changes should result in better random numbers from rand().
-
-=head2 Improved C<qw//> operator
-
-The C<qw//> operator is now evaluated at compile time into a true list
-instead of being replaced with a run time call to C<split()>. This
-removes the confusing misbehaviour of C<qw//> in scalar context, which
-had inherited that behaviour from split().
-
-Thus:
-
- $foo = ($bar) = qw(a b c); print "$foo|$bar\n";
-
-now correctly prints "3|a", instead of "2|a".
-
-=head2 Better worst-case behavior of hashes
-
-Small changes in the hashing algorithm have been implemented in
-order to improve the distribution of lower order bits in the
-hashed value. This is expected to yield better performance on
-keys that are repeated sequences.
-
-=head2 pack() format 'Z' supported
-
-The new format type 'Z' is useful for packing and unpacking null-terminated
-strings. See L<perlfunc/"pack">.
-
-=head2 pack() format modifier '!' supported
-
-The new format type modifier '!' is useful for packing and unpacking
-native shorts, ints, and longs. See L<perlfunc/"pack">.
-
-=head2 pack() and unpack() support counted strings
-
-The template character '/' can be used to specify a counted string
-type to be packed or unpacked. See L<perlfunc/"pack">.
-
-=head2 Comments in pack() templates
-
-The '#' character in a template introduces a comment up to
-end of the line. This facilitates documentation of pack()
-templates.
-
-=head2 Weak references
-
-In previous versions of Perl, you couldn't cache objects so as
-to allow them to be deleted if the last reference from outside
-the cache is deleted. The reference in the cache would hold a
-reference count on the object and the objects would never be
-destroyed.
-
-Another familiar problem is with circular references. When an
-object references itself, its reference count would never go
-down to zero, and it would not get destroyed until the program
-is about to exit.
-
-Weak references solve this by allowing you to "weaken" any
-reference, that is, make it not count towards the reference count.
-When the last non-weak reference to an object is deleted, the object
-is destroyed and all the weak references to the object are
-automatically undef-ed.
-
-To use this feature, you need the Devel::WeakRef package from CPAN, which
-contains additional documentation.
-
- NOTE: This is an experimental feature. Details are subject to change.
-
-=head2 Binary numbers supported
-
-Binary numbers are now supported as literals, in s?printf formats, and
-C<oct()>:
-
- $answer = 0b101010;
- printf "The answer is: %b\n", oct("0b101010");
-
-=head2 Lvalue subroutines
-
-Subroutines can now return modifiable lvalues.
-See L<perlsub/"Lvalue subroutines">.
-
- NOTE: This is an experimental feature. Details are subject to change.
-
-=head2 Some arrows may be omitted in calls through references
-
-Perl now allows the arrow to be omitted in many constructs
-involving subroutine calls through references. For example,
-C<< $foo[10]->('foo') >> may now be written C<$foo[10]('foo')>.
-This is rather similar to how the arrow may be omitted from
-C<< $foo[10]->{'foo'} >>. Note however, that the arrow is still
-required for C<< foo(10)->('bar') >>.
-
-=head2 Boolean assignment operators are legal lvalues
-
-Constructs such as C<($a ||= 2) += 1> are now allowed.
-
-=head2 exists() is supported on subroutine names
-
-The exists() builtin now works on subroutine names. A subroutine
-is considered to exist if it has been declared (even if implicitly).
-See L<perlfunc/exists> for examples.
-
-=head2 exists() and delete() are supported on array elements
-
-The exists() and delete() builtins now work on simple arrays as well.
-The behavior is similar to that on hash elements.
-
-exists() can be used to check whether an array element has been
-initialized. This avoids autovivifying array elements that don't exist.
-If the array is tied, the EXISTS() method in the corresponding tied
-package will be invoked.
-
-delete() may be used to remove an element from the array and return
-it. The array element at that position returns to its uninitialized
-state, so that testing for the same element with exists() will return
-false. If the element happens to be the one at the end, the size of
-the array also shrinks up to the highest element that tests true for
-exists(), or 0 if none such is found. If the array is tied, the DELETE()
-method in the corresponding tied package will be invoked.
-
-See L<perlfunc/exists> and L<perlfunc/delete> for examples.
-
-=head2 Pseudo-hashes work better
-
-Dereferencing some types of reference values in a pseudo-hash,
-such as C<< $ph->{foo}[1] >>, was accidentally disallowed. This has
-been corrected.
-
-When applied to a pseudo-hash element, exists() now reports whether
-the specified value exists, not merely if the key is valid.
-
-delete() now works on pseudo-hashes. When given a pseudo-hash element
-or slice it deletes the values corresponding to the keys (but not the keys
-themselves). See L<perlref/"Pseudo-hashes: Using an array as a hash">.
-
-Pseudo-hash slices with constant keys are now optimized to array lookups
-at compile-time.
-
-List assignments to pseudo-hash slices are now supported.
-
-The C<fields> pragma now provides ways to create pseudo-hashes, via
-fields::new() and fields::phash(). See L<fields>.
-
- NOTE: The pseudo-hash data type continues to be experimental.
- Limiting oneself to the interface elements provided by the
- fields pragma will provide protection from any future changes.
-
-=head2 Automatic flushing of output buffers
-
-fork(), exec(), system(), qx//, and pipe open()s now flush buffers
-of all files opened for output when the operation was attempted. This
-mostly eliminates confusing buffering mishaps suffered by users unaware
-of how Perl internally handles I/O.
-
-This is not supported on some platforms like Solaris where a suitably
-correct implementation of fflush(NULL) isn't available.
-
-=head2 Better diagnostics on meaningless filehandle operations
-
-Constructs such as C<< open(<FH>) >> and C<< close(<FH>) >>
-are compile time errors. Attempting to read from filehandles that
-were opened only for writing will now produce warnings (just as
-writing to read-only filehandles does).
-
-=head2 Where possible, buffered data discarded from duped input filehandle
-
-C<< open(NEW, "<&OLD") >> now attempts to discard any data that
-was previously read and buffered in C<OLD> before duping the handle.
-On platforms where doing this is allowed, the next read operation
-on C<NEW> will return the same data as the corresponding operation
-on C<OLD>. Formerly, it would have returned the data from the start
-of the following disk block instead.
-
-=head2 eof() has the same old magic as <>
-
-C<eof()> would return true if no attempt to read from C<< <> >> had
-yet been made. C<eof()> has been changed to have a little magic of its
-own, it now opens the C<< <> >> files.
-
-=head2 binmode() can be used to set :crlf and :raw modes
-
-binmode() now accepts a second argument that specifies a discipline
-for the handle in question. The two pseudo-disciplines ":raw" and
-":crlf" are currently supported on DOS-derivative platforms.
-See L<perlfunc/"binmode"> and L<open>.
-
-=head2 C<-T> filetest recognizes UTF-8 encoded files as "text"
-
-The algorithm used for the C<-T> filetest has been enhanced to
-correctly identify UTF-8 content as "text".
-
-=head2 system(), backticks and pipe open now reflect exec() failure
-
-On Unix and similar platforms, system(), qx() and open(FOO, "cmd |")
-etc., are implemented via fork() and exec(). When the underlying
-exec() fails, earlier versions did not report the error properly,
-since the exec() happened to be in a different process.
-
-The child process now communicates with the parent about the
-error in launching the external command, which allows these
-constructs to return with their usual error value and set $!.
-
-=head2 Improved diagnostics
-
-Line numbers are no longer suppressed (under most likely circumstances)
-during the global destruction phase.
-
-Diagnostics emitted from code running in threads other than the main
-thread are now accompanied by the thread ID.
-
-Embedded null characters in diagnostics now actually show up. They
-used to truncate the message in prior versions.
-
-$foo::a and $foo::b are now exempt from "possible typo" warnings only
-if sort() is encountered in package C<foo>.
-
-Unrecognized alphabetic escapes encountered when parsing quote
-constructs now generate a warning, since they may take on new
-semantics in later versions of Perl.
-
-Many diagnostics now report the internal operation in which the warning
-was provoked, like so:
-
- Use of uninitialized value in concatenation (.) at (eval 1) line 1.
- Use of uninitialized value in print at (eval 1) line 1.
-
-Diagnostics that occur within eval may also report the file and line
-number where the eval is located, in addition to the eval sequence
-number and the line number within the evaluated text itself. For
-example:
-
- Not enough arguments for scalar at (eval 4)[newlib/perl5db.pl:1411] line 2, at EOF
-
-=head2 Diagnostics follow STDERR
-
-Diagnostic output now goes to whichever file the C<STDERR> handle
-is pointing at, instead of always going to the underlying C runtime
-library's C<stderr>.
-
-=head2 More consistent close-on-exec behavior
-
-On systems that support a close-on-exec flag on filehandles, the
-flag is now set for any handles created by pipe(), socketpair(),
-socket(), and accept(), if that is warranted by the value of $^F
-that may be in effect. Earlier versions neglected to set the flag
-for handles created with these operators. See L<perlfunc/pipe>,
-L<perlfunc/socketpair>, L<perlfunc/socket>, L<perlfunc/accept>,
-and L<perlvar/$^F>.
-
-=head2 syswrite() ease-of-use
-
-The length argument of C<syswrite()> has become optional.
-
-=head2 Better syntax checks on parenthesized unary operators
-
-Expressions such as:
-
- print defined(&foo,&bar,&baz);
- print uc("foo","bar","baz");
- undef($foo,&bar);
-
-used to be accidentally allowed in earlier versions, and produced
-unpredictable behaviour. Some produced ancillary warnings
-when used in this way; others silently did the wrong thing.
-
-The parenthesized forms of most unary operators that expect a single
-argument now ensure that they are not called with more than one
-argument, making the cases shown above syntax errors. The usual
-behaviour of:
-
- print defined &foo, &bar, &baz;
- print uc "foo", "bar", "baz";
- undef $foo, &bar;
-
-remains unchanged. See L<perlop>.
-
-=head2 Bit operators support full native integer width
-
-The bit operators (& | ^ ~ << >>) now operate on the full native
-integral width (the exact size of which is available in $Config{ivsize}).
-For example, if your platform is either natively 64-bit or if Perl
-has been configured to use 64-bit integers, these operations apply
-to 8 bytes (as opposed to 4 bytes on 32-bit platforms).
-For portability, be sure to mask off the excess bits in the result of
-unary C<~>, e.g., C<~$x & 0xffffffff>.
-
-=head2 Improved security features
-
-More potentially unsafe operations taint their results for improved
-security.
-
-The C<passwd> and C<shell> fields returned by the getpwent(), getpwnam(),
-and getpwuid() are now tainted, because the user can affect their own
-encrypted password and login shell.
-
-The variable modified by shmread(), and messages returned by msgrcv()
-(and its object-oriented interface IPC::SysV::Msg::rcv) are also tainted,
-because other untrusted processes can modify messages and shared memory
-segments for their own nefarious purposes.
-
-=head2 More functional bareword prototype (*)
-
-Bareword prototypes have been rationalized to enable them to be used
-to override builtins that accept barewords and interpret them in
-a special way, such as C<require> or C<do>.
-
-Arguments prototyped as C<*> will now be visible within the subroutine
-as either a simple scalar or as a reference to a typeglob.
-See L<perlsub/Prototypes>.
-
-=head2 C<require> and C<do> may be overridden
-
-C<require> and C<do 'file'> operations may be overridden locally
-by importing subroutines of the same name into the current package
-(or globally by importing them into the CORE::GLOBAL:: namespace).
-Overriding C<require> will also affect C<use>, provided the override
-is visible at compile-time.
-See L<perlsub/"Overriding Built-in Functions">.
-
-=head2 $^X variables may now have names longer than one character
-
-Formerly, $^X was synonymous with ${"\cX"}, but $^XY was a syntax
-error. Now variable names that begin with a control character may be
-arbitrarily long. However, for compatibility reasons, these variables
-I<must> be written with explicit braces, as C<${^XY}> for example.
-C<${^XYZ}> is synonymous with ${"\cXYZ"}. Variable names with more
-than one control character, such as C<${^XY^Z}>, are illegal.
-
-The old syntax has not changed. As before, `^X' may be either a
-literal control-X character or the two-character sequence `caret' plus
-`X'. When braces are omitted, the variable name stops after the
-control character. Thus C<"$^XYZ"> continues to be synonymous with
-C<$^X . "YZ"> as before.
-
-As before, lexical variables may not have names beginning with control
-characters. As before, variables whose names begin with a control
-character are always forced to be in package `main'. All such variables
-are reserved for future extensions, except those that begin with
-C<^_>, which may be used by user programs and are guaranteed not to
-acquire special meaning in any future version of Perl.
-
-=head2 New variable $^C reflects C<-c> switch
-
-C<$^C> has a boolean value that reflects whether perl is being run
-in compile-only mode (i.e. via the C<-c> switch). Since
-BEGIN blocks are executed under such conditions, this variable
-enables perl code to determine whether actions that make sense
-only during normal running are warranted. See L<perlvar>.
-
-=head2 New variable $^V contains Perl version as a string
-
-C<$^V> contains the Perl version number as a string composed of
-characters whose ordinals match the version numbers, i.e. v5.6.0.
-This may be used in string comparisons.
-
-See C<Support for strings represented as a vector of ordinals> for an
-example.
-
-=head2 Optional Y2K warnings
-
-If Perl is built with the cpp macro C<PERL_Y2KWARN> defined,
-it emits optional warnings when concatenating the number 19
-with another number.
-
-This behavior must be specifically enabled when running Configure.
-See F<INSTALL> and F<README.Y2K>.
-
-=head2 Arrays now always interpolate into double-quoted strings
-
-In double-quoted strings, arrays now interpolate, no matter what. The
-behavior in earlier versions of perl 5 was that arrays would interpolate
-into strings if the array had been mentioned before the string was
-compiled, and otherwise Perl would raise a fatal compile-time error.
-In versions 5.000 through 5.003, the error was
-
- Literal @example now requires backslash
-
-In versions 5.004_01 through 5.6.0, the error was
-
- In string, @example now must be written as \@example
-
-The idea here was to get people into the habit of writing
-C<"fred\@example.com"> when they wanted a literal C<@> sign, just as
-they have always written C<"Give me back my \$5"> when they wanted a
-literal C<$> sign.
-
-Starting with 5.6.1, when Perl now sees an C<@> sign in a
-double-quoted string, it I<always> attempts to interpolate an array,
-regardless of whether or not the array has been used or declared
-already. The fatal error has been downgraded to an optional warning:
-
- Possible unintended interpolation of @example in string
-
-This warns you that C<"fred@example.com"> is going to turn into
-C<fred.com> if you don't backslash the C<@>.
-See http://perl.plover.com/at-error.html for more details
-about the history here.
-
-=head2 @- and @+ provide starting/ending offsets of regex matches
-
-The new magic variables @- and @+ provide the starting and ending
-offsets, respectively, of $&, $1, $2, etc. See L<perlvar> for
-details.
-
-=head1 Modules and Pragmata
-
-=head2 Modules
-
-=over 4
-
-=item attributes
-
-While used internally by Perl as a pragma, this module also
-provides a way to fetch subroutine and variable attributes.
-See L<attributes>.
-
-=item B
-
-The Perl Compiler suite has been extensively reworked for this
-release. More of the standard Perl test suite passes when run
-under the Compiler, but there is still a significant way to
-go to achieve production quality compiled executables.
-
- NOTE: The Compiler suite remains highly experimental. The
- generated code may not be correct, even when it manages to execute
- without errors.
-
-=item Benchmark
-
-Overall, Benchmark results exhibit lower average error and better timing
-accuracy.
-
-You can now run tests for I<n> seconds instead of guessing the right
-number of tests to run: e.g., timethese(-5, ...) will run each
-code for at least 5 CPU seconds. Zero as the "number of repetitions"
-means "for at least 3 CPU seconds". The output format has also
-changed. For example:
-
- use Benchmark;$x=3;timethese(-5,{a=>sub{$x*$x},b=>sub{$x**2}})
-
-will now output something like this:
-
- Benchmark: running a, b, each for at least 5 CPU seconds...
- a: 5 wallclock secs ( 5.77 usr + 0.00 sys = 5.77 CPU) @ 200551.91/s (n=1156516)
- b: 4 wallclock secs ( 5.00 usr + 0.02 sys = 5.02 CPU) @ 159605.18/s (n=800686)
-
-New features: "each for at least N CPU seconds...", "wallclock secs",
-and the "@ operations/CPU second (n=operations)".
-
-timethese() now returns a reference to a hash of Benchmark objects containing
-the test results, keyed on the names of the tests.
-
-timethis() now returns the iterations field in the Benchmark result object
-instead of 0.
-
-timethese(), timethis(), and the new cmpthese() (see below) can also take
-a format specifier of 'none' to suppress output.
-
-A new function countit() is just like timeit() except that it takes a
-TIME instead of a COUNT.
-
-A new function cmpthese() prints a chart comparing the results of each test
-returned from a timethese() call. For each possible pair of tests, the
-percentage speed difference (iters/sec or seconds/iter) is shown.
-
-For other details, see L<Benchmark>.
-
-=item ByteLoader
-
-The ByteLoader is a dedicated extension to generate and run
-Perl bytecode. See L<ByteLoader>.
-
-=item constant
-
-References can now be used.
-
-The new version also allows a leading underscore in constant names, but
-disallows a double leading underscore (as in "__LINE__"). Some other names
-are disallowed or warned against, including BEGIN, END, etc. Some names
-which were forced into main:: used to fail silently in some cases; now they're
-fatal (outside of main::) and an optional warning (inside of main::).
-The ability to detect whether a constant had been set with a given name has
-been added.
-
-See L<constant>.
-
-=item charnames
-
-This pragma implements the C<\N> string escape. See L<charnames>.
-
-=item Data::Dumper
-
-A C<Maxdepth> setting can be specified to avoid venturing
-too deeply into deep data structures. See L<Data::Dumper>.
-
-The XSUB implementation of Dump() is now automatically called if the
-C<Useqq> setting is not in use.
-
-Dumping C<qr//> objects works correctly.
-
-=item DB
-
-C<DB> is an experimental module that exposes a clean abstraction
-to Perl's debugging API.
-
-=item DB_File
-
-DB_File can now be built with Berkeley DB versions 1, 2 or 3.
-See C<ext/DB_File/Changes>.
-
-=item Devel::DProf
-
-Devel::DProf, a Perl source code profiler has been added. See
-L<Devel::DProf> and L<dprofpp>.
-
-=item Devel::Peek
-
-The Devel::Peek module provides access to the internal representation
-of Perl variables and data. It is a data debugging tool for the XS programmer.
-
-=item Dumpvalue
-
-The Dumpvalue module provides screen dumps of Perl data.
-
-=item DynaLoader
-
-DynaLoader now supports a dl_unload_file() function on platforms that
-support unloading shared objects using dlclose().
-
-Perl can also optionally arrange to unload all extension shared objects
-loaded by Perl. To enable this, build Perl with the Configure option
-C<-Accflags=-DDL_UNLOAD_ALL_AT_EXIT>. (This maybe useful if you are
-using Apache with mod_perl.)
-
-=item English
-
-$PERL_VERSION now stands for C<$^V> (a string value) rather than for C<$]>
-(a numeric value).
-
-=item Env
-
-Env now supports accessing environment variables like PATH as array
-variables.
-
-=item Fcntl
-
-More Fcntl constants added: F_SETLK64, F_SETLKW64, O_LARGEFILE for
-large file (more than 4GB) access (NOTE: the O_LARGEFILE is
-automatically added to sysopen() flags if large file support has been
-configured, as is the default), Free/Net/OpenBSD locking behaviour
-flags F_FLOCK, F_POSIX, Linux F_SHLCK, and O_ACCMODE: the combined
-mask of O_RDONLY, O_WRONLY, and O_RDWR. The seek()/sysseek()
-constants SEEK_SET, SEEK_CUR, and SEEK_END are available via the
-C<:seek> tag. The chmod()/stat() S_IF* constants and S_IS* functions
-are available via the C<:mode> tag.
-
-=item File::Compare
-
-A compare_text() function has been added, which allows custom
-comparison functions. See L<File::Compare>.
-
-=item File::Find
-
-File::Find now works correctly when the wanted() function is either
-autoloaded or is a symbolic reference.
-
-A bug that caused File::Find to lose track of the working directory
-when pruning top-level directories has been fixed.
-
-File::Find now also supports several other options to control its
-behavior. It can follow symbolic links if the C<follow> option is
-specified. Enabling the C<no_chdir> option will make File::Find skip
-changing the current directory when walking directories. The C<untaint>
-flag can be useful when running with taint checks enabled.
-
-See L<File::Find>.
-
-=item File::Glob
-
-This extension implements BSD-style file globbing. By default,
-it will also be used for the internal implementation of the glob()
-operator. See L<File::Glob>.
-
-=item File::Spec
-
-New methods have been added to the File::Spec module: devnull() returns
-the name of the null device (/dev/null on Unix) and tmpdir() the name of
-the temp directory (normally /tmp on Unix). There are now also methods
-to convert between absolute and relative filenames: abs2rel() and
-rel2abs(). For compatibility with operating systems that specify volume
-names in file paths, the splitpath(), splitdir(), and catdir() methods
-have been added.
-
-=item File::Spec::Functions
-
-The new File::Spec::Functions modules provides a function interface
-to the File::Spec module. Allows shorthand
-
- $fullname = catfile($dir1, $dir2, $file);
-
-instead of
-
- $fullname = File::Spec->catfile($dir1, $dir2, $file);
-
-=item Getopt::Long
-
-Getopt::Long licensing has changed to allow the Perl Artistic License
-as well as the GPL. It used to be GPL only, which got in the way of
-non-GPL applications that wanted to use Getopt::Long.
-
-Getopt::Long encourages the use of Pod::Usage to produce help
-messages. For example:
-
- use Getopt::Long;
- use Pod::Usage;
- my $man = 0;
- my $help = 0;
- GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
- pod2usage(1) if $help;
- pod2usage(-exitstatus => 0, -verbose => 2) if $man;
-
- __END__
-
- =head1 NAME
-
- sample - Using Getopt::Long and Pod::Usage
-
- =head1 SYNOPSIS
-
- sample [options] [file ...]
-
- Options:
- -help brief help message
- -man full documentation
-
- =head1 OPTIONS
-
- =over 8
-
- =item B<-help>
-
- Print a brief help message and exits.
-
- =item B<-man>
-
- Prints the manual page and exits.
-
- =back
-
- =head1 DESCRIPTION
-
- B<This program> will read the given input file(s) and do something
- useful with the contents thereof.
-
- =cut
-
-See L<Pod::Usage> for details.
-
-A bug that prevented the non-option call-back <> from being
-specified as the first argument has been fixed.
-
-To specify the characters < and > as option starters, use ><. Note,
-however, that changing option starters is strongly deprecated.
-
-=item IO
-
-write() and syswrite() will now accept a single-argument
-form of the call, for consistency with Perl's syswrite().
-
-You can now create a TCP-based IO::Socket::INET without forcing
-a connect attempt. This allows you to configure its options
-(like making it non-blocking) and then call connect() manually.
-
-A bug that prevented the IO::Socket::protocol() accessor
-from ever returning the correct value has been corrected.
-
-IO::Socket::connect now uses non-blocking IO instead of alarm()
-to do connect timeouts.
-
-IO::Socket::accept now uses select() instead of alarm() for doing
-timeouts.
-
-IO::Socket::INET->new now sets $! correctly on failure. $@ is
-still set for backwards compatibility.
-
-=item JPL
-
-Java Perl Lingo is now distributed with Perl. See jpl/README
-for more information.
-
-=item lib
-
-C<use lib> now weeds out any trailing duplicate entries.
-C<no lib> removes all named entries.
-
-=item Math::BigInt
-
-The bitwise operations C<<< << >>>, C<<< >> >>>, C<&>, C<|>,
-and C<~> are now supported on bigints.
-
-=item Math::Complex
-
-The accessor methods Re, Im, arg, abs, rho, and theta can now also
-act as mutators (accessor $z->Re(), mutator $z->Re(3)).
-
-The class method C<display_format> and the corresponding object method
-C<display_format>, in addition to accepting just one argument, now can
-also accept a parameter hash. Recognized keys of a parameter hash are
-C<"style">, which corresponds to the old one parameter case, and two
-new parameters: C<"format">, which is a printf()-style format string
-(defaults usually to C<"%.15g">, you can revert to the default by
-setting the format string to C<undef>) used for both parts of a
-complex number, and C<"polar_pretty_print"> (defaults to true),
-which controls whether an attempt is made to try to recognize small
-multiples and rationals of pi (2pi, pi/2) at the argument (angle) of a
-polar complex number.
-
-The potentially disruptive change is that in list context both methods
-now I<return the parameter hash>, instead of only the value of the
-C<"style"> parameter.
-
-=item Math::Trig
-
-A little bit of radial trigonometry (cylindrical and spherical),
-radial coordinate conversions, and the great circle distance were added.
-
-=item Pod::Parser, Pod::InputObjects
-
-Pod::Parser is a base class for parsing and selecting sections of
-pod documentation from an input stream. This module takes care of
-identifying pod paragraphs and commands in the input and hands off the
-parsed paragraphs and commands to user-defined methods which are free
-to interpret or translate them as they see fit.
-
-Pod::InputObjects defines some input objects needed by Pod::Parser, and
-for advanced users of Pod::Parser that need more about a command besides
-its name and text.
-
-As of release 5.6.0 of Perl, Pod::Parser is now the officially sanctioned
-"base parser code" recommended for use by all pod2xxx translators.
-Pod::Text (pod2text) and Pod::Man (pod2man) have already been converted
-to use Pod::Parser and efforts to convert Pod::HTML (pod2html) are already
-underway. For any questions or comments about pod parsing and translating
-issues and utilities, please use the pod-people@perl.org mailing list.
-
-For further information, please see L<Pod::Parser> and L<Pod::InputObjects>.
-
-=item Pod::Checker, podchecker
-
-This utility checks pod files for correct syntax, according to
-L<perlpod>. Obvious errors are flagged as such, while warnings are
-printed for mistakes that can be handled gracefully. The checklist is
-not complete yet. See L<Pod::Checker>.
-
-=item Pod::ParseUtils, Pod::Find
-
-These modules provide a set of gizmos that are useful mainly for pod
-translators. L<Pod::Find|Pod::Find> traverses directory structures and
-returns found pod files, along with their canonical names (like
-C<File::Spec::Unix>). L<Pod::ParseUtils|Pod::ParseUtils> contains
-B<Pod::List> (useful for storing pod list information), B<Pod::Hyperlink>
-(for parsing the contents of C<LE<lt>E<gt>> sequences) and B<Pod::Cache>
-(for caching information about pod files, e.g., link nodes).
-
-=item Pod::Select, podselect
-
-Pod::Select is a subclass of Pod::Parser which provides a function
-named "podselect()" to filter out user-specified sections of raw pod
-documentation from an input stream. podselect is a script that provides
-access to Pod::Select from other scripts to be used as a filter.
-See L<Pod::Select>.
-
-=item Pod::Usage, pod2usage
-
-Pod::Usage provides the function "pod2usage()" to print usage messages for
-a Perl script based on its embedded pod documentation. The pod2usage()
-function is generally useful to all script authors since it lets them
-write and maintain a single source (the pods) for documentation, thus
-removing the need to create and maintain redundant usage message text
-consisting of information already in the pods.
-
-There is also a pod2usage script which can be used from other kinds of
-scripts to print usage messages from pods (even for non-Perl scripts
-with pods embedded in comments).
-
-For details and examples, please see L<Pod::Usage>.
-
-=item Pod::Text and Pod::Man
-
-Pod::Text has been rewritten to use Pod::Parser. While pod2text() is
-still available for backwards compatibility, the module now has a new
-preferred interface. See L<Pod::Text> for the details. The new Pod::Text
-module is easily subclassed for tweaks to the output, and two such
-subclasses (Pod::Text::Termcap for man-page-style bold and underlining
-using termcap information, and Pod::Text::Color for markup with ANSI color
-sequences) are now standard.
-
-pod2man has been turned into a module, Pod::Man, which also uses
-Pod::Parser. In the process, several outstanding bugs related to quotes
-in section headers, quoting of code escapes, and nested lists have been
-fixed. pod2man is now a wrapper script around this module.
-
-=item SDBM_File
-
-An EXISTS method has been added to this module (and sdbm_exists() has
-been added to the underlying sdbm library), so one can now call exists
-on an SDBM_File tied hash and get the correct result, rather than a
-runtime error.
-
-A bug that may have caused data loss when more than one disk block
-happens to be read from the database in a single FETCH() has been
-fixed.
-
-=item Sys::Syslog
-
-Sys::Syslog now uses XSUBs to access facilities from syslog.h so it
-no longer requires syslog.ph to exist.
-
-=item Sys::Hostname
-
-Sys::Hostname now uses XSUBs to call the C library's gethostname() or
-uname() if they exist.
-
-=item Term::ANSIColor
-
-Term::ANSIColor is a very simple module to provide easy and readable
-access to the ANSI color and highlighting escape sequences, supported by
-most ANSI terminal emulators. It is now included standard.
-
-=item Time::Local
-
-The timelocal() and timegm() functions used to silently return bogus
-results when the date fell outside the machine's integer range. They
-now consistently croak() if the date falls in an unsupported range.
-
-=item Win32
-
-The error return value in list context has been changed for all functions
-that return a list of values. Previously these functions returned a list
-with a single element C<undef> if an error occurred. Now these functions
-return the empty list in these situations. This applies to the following
-functions:
-
- Win32::FsType
- Win32::GetOSVersion
-
-The remaining functions are unchanged and continue to return C<undef> on
-error even in list context.
-
-The Win32::SetLastError(ERROR) function has been added as a complement
-to the Win32::GetLastError() function.
-
-The new Win32::GetFullPathName(FILENAME) returns the full absolute
-pathname for FILENAME in scalar context. In list context it returns
-a two-element list containing the fully qualified directory name and
-the filename. See L<Win32>.
-
-=item XSLoader
-
-The XSLoader extension is a simpler alternative to DynaLoader.
-See L<XSLoader>.
-
-=item DBM Filters
-
-A new feature called "DBM Filters" has been added to all the
-DBM modules--DB_File, GDBM_File, NDBM_File, ODBM_File, and SDBM_File.
-DBM Filters add four new methods to each DBM module:
-
- filter_store_key
- filter_store_value
- filter_fetch_key
- filter_fetch_value
-
-These can be used to filter key-value pairs before the pairs are
-written to the database or just after they are read from the database.
-See L<perldbmfilter> for further information.
-
-=back
-
-=head2 Pragmata
-
-C<use attrs> is now obsolete, and is only provided for
-backward-compatibility. It's been replaced by the C<sub : attributes>
-syntax. See L<perlsub/"Subroutine Attributes"> and L<attributes>.
-
-Lexical warnings pragma, C<use warnings;>, to control optional warnings.
-See L<perllexwarn>.
-
-C<use filetest> to control the behaviour of filetests (C<-r> C<-w>
-...). Currently only one subpragma implemented, "use filetest
-'access';", that uses access(2) or equivalent to check permissions
-instead of using stat(2) as usual. This matters in filesystems
-where there are ACLs (access control lists): the stat(2) might lie,
-but access(2) knows better.
-
-The C<open> pragma can be used to specify default disciplines for
-handle constructors (e.g. open()) and for qx//. The two
-pseudo-disciplines C<:raw> and C<:crlf> are currently supported on
-DOS-derivative platforms (i.e. where binmode is not a no-op).
-See also L</"binmode() can be used to set :crlf and :raw modes">.
-
-=head1 Utility Changes
-
-=head2 dprofpp
-
-C<dprofpp> is used to display profile data generated using C<Devel::DProf>.
-See L<dprofpp>.
-
-=head2 find2perl
-
-The C<find2perl> utility now uses the enhanced features of the File::Find
-module. The -depth and -follow options are supported. Pod documentation
-is also included in the script.
-
-=head2 h2xs
-
-The C<h2xs> tool can now work in conjunction with C<C::Scan> (available
-from CPAN) to automatically parse real-life header files. The C<-M>,
-C<-a>, C<-k>, and C<-o> options are new.
-
-=head2 perlcc
-
-C<perlcc> now supports the C and Bytecode backends. By default,
-it generates output from the simple C backend rather than the
-optimized C backend.
-
-Support for non-Unix platforms has been improved.
-
-=head2 perldoc
-
-C<perldoc> has been reworked to avoid possible security holes.
-It will not by default let itself be run as the superuser, but you
-may still use the B<-U> switch to try to make it drop privileges
-first.
-
-=head2 The Perl Debugger
-
-Many bug fixes and enhancements were added to F<perl5db.pl>, the
-Perl debugger. The help documentation was rearranged. New commands
-include C<< < ? >>, C<< > ? >>, and C<< { ? >> to list out current
-actions, C<man I<docpage>> to run your doc viewer on some perl
-docset, and support for quoted options. The help information was
-rearranged, and should be viewable once again if you're using B<less>
-as your pager. A serious security hole was plugged--you should
-immediately remove all older versions of the Perl debugger as
-installed in previous releases, all the way back to perl3, from
-your system to avoid being bitten by this.
-
-=head1 Improved Documentation
-
-Many of the platform-specific README files are now part of the perl
-installation. See L<perl> for the complete list.
-
-=over 4
-
-=item perlapi.pod
-
-The official list of public Perl API functions.
-
-=item perlboot.pod
-
-A tutorial for beginners on object-oriented Perl.
-
-=item perlcompile.pod
-
-An introduction to using the Perl Compiler suite.
-
-=item perldbmfilter.pod
-
-A howto document on using the DBM filter facility.
-
-=item perldebug.pod
-
-All material unrelated to running the Perl debugger, plus all
-low-level guts-like details that risked crushing the casual user
-of the debugger, have been relocated from the old manpage to the
-next entry below.
-
-=item perldebguts.pod
-
-This new manpage contains excessively low-level material not related
-to the Perl debugger, but slightly related to debugging Perl itself.
-It also contains some arcane internal details of how the debugging
-process works that may only be of interest to developers of Perl
-debuggers.
-
-=item perlfork.pod
-
-Notes on the fork() emulation currently available for the Windows platform.
-
-=item perlfilter.pod
-
-An introduction to writing Perl source filters.
-
-=item perlhack.pod
-
-Some guidelines for hacking the Perl source code.
-
-=item perlintern.pod
-
-A list of internal functions in the Perl source code.
-(List is currently empty.)
-
-=item perllexwarn.pod
-
-Introduction and reference information about lexically scoped
-warning categories.
-
-=item perlnumber.pod
-
-Detailed information about numbers as they are represented in Perl.
-
-=item perlopentut.pod
-
-A tutorial on using open() effectively.
-
-=item perlreftut.pod
-
-A tutorial that introduces the essentials of references.
-
-=item perltootc.pod
-
-A tutorial on managing class data for object modules.
-
-=item perltodo.pod
-
-Discussion of the most often wanted features that may someday be
-supported in Perl.
-
-=item perlunicode.pod
-
-An introduction to Unicode support features in Perl.
-
-=back
-
-=head1 Performance enhancements
-
-=head2 Simple sort() using { $a <=> $b } and the like are optimized
-
-Many common sort() operations using a simple inlined block are now
-optimized for faster performance.
-
-=head2 Optimized assignments to lexical variables
-
-Certain operations in the RHS of assignment statements have been
-optimized to directly set the lexical variable on the LHS,
-eliminating redundant copying overheads.
-
-=head2 Faster subroutine calls
-
-Minor changes in how subroutine calls are handled internally
-provide marginal improvements in performance.
-
-=head2 delete(), each(), values() and hash iteration are faster
-
-The hash values returned by delete(), each(), values() and hashes in a
-list context are the actual values in the hash, instead of copies.
-This results in significantly better performance, because it eliminates
-needless copying in most situations.
-
-=head1 Installation and Configuration Improvements
-
-=head2 -Dusethreads means something different
-
-The -Dusethreads flag now enables the experimental interpreter-based thread
-support by default. To get the flavor of experimental threads that was in
-5.005 instead, you need to run Configure with "-Dusethreads -Duse5005threads".
-
-As of v5.6.0, interpreter-threads support is still lacking a way to
-create new threads from Perl (i.e., C<use Thread;> will not work with
-interpreter threads). C<use Thread;> continues to be available when you
-specify the -Duse5005threads option to Configure, bugs and all.
-
- NOTE: Support for threads continues to be an experimental feature.
- Interfaces and implementation are subject to sudden and drastic changes.
-
-=head2 New Configure flags
-
-The following new flags may be enabled on the Configure command line
-by running Configure with C<-Dflag>.
-
- usemultiplicity
- usethreads useithreads (new interpreter threads: no Perl API yet)
- usethreads use5005threads (threads as they were in 5.005)
-
- use64bitint (equal to now deprecated 'use64bits')
- use64bitall
-
- uselongdouble
- usemorebits
- uselargefiles
- usesocks (only SOCKS v5 supported)
-
-=head2 Threadedness and 64-bitness now more daring
-
-The Configure options enabling the use of threads and the use of
-64-bitness are now more daring in the sense that they no more have an
-explicit list of operating systems of known threads/64-bit
-capabilities. In other words: if your operating system has the
-necessary APIs and datatypes, you should be able just to go ahead and
-use them, for threads by Configure -Dusethreads, and for 64 bits
-either explicitly by Configure -Duse64bitint or implicitly if your
-system has 64-bit wide datatypes. See also L<"64-bit support">.
-
-=head2 Long Doubles
-
-Some platforms have "long doubles", floating point numbers of even
-larger range than ordinary "doubles". To enable using long doubles for
-Perl's scalars, use -Duselongdouble.
-
-=head2 -Dusemorebits
-
-You can enable both -Duse64bitint and -Duselongdouble with -Dusemorebits.
-See also L<"64-bit support">.
-
-=head2 -Duselargefiles
-
-Some platforms support system APIs that are capable of handling large files
-(typically, files larger than two gigabytes). Perl will try to use these
-APIs if you ask for -Duselargefiles.
-
-See L<"Large file support"> for more information.
-
-=head2 installusrbinperl
-
-You can use "Configure -Uinstallusrbinperl" which causes installperl
-to skip installing perl also as /usr/bin/perl. This is useful if you
-prefer not to modify /usr/bin for some reason or another but harmful
-because many scripts assume to find Perl in /usr/bin/perl.
-
-=head2 SOCKS support
-
-You can use "Configure -Dusesocks" which causes Perl to probe
-for the SOCKS proxy protocol library (v5, not v4). For more information
-on SOCKS, see:
-
- http://www.socks.nec.com/
-
-=head2 C<-A> flag
-
-You can "post-edit" the Configure variables using the Configure C<-A>
-switch. The editing happens immediately after the platform specific
-hints files have been processed but before the actual configuration
-process starts. Run C<Configure -h> to find out the full C<-A> syntax.
-
-=head2 Enhanced Installation Directories
-
-The installation structure has been enriched to improve the support
-for maintaining multiple versions of perl, to provide locations for
-vendor-supplied modules, scripts, and manpages, and to ease maintenance
-of locally-added modules, scripts, and manpages. See the section on
-Installation Directories in the INSTALL file for complete details.
-For most users building and installing from source, the defaults should
-be fine.
-
-If you previously used C<Configure -Dsitelib> or C<-Dsitearch> to set
-special values for library directories, you might wish to consider using
-the new C<-Dsiteprefix> setting instead. Also, if you wish to re-use a
-config.sh file from an earlier version of perl, you should be sure to
-check that Configure makes sensible choices for the new directories.
-See INSTALL for complete details.
-
-=head1 Platform specific changes
-
-=head2 Supported platforms
-
-=over 4
-
-=item *
-
-The Mach CThreads (NEXTSTEP, OPENSTEP) are now supported by the Thread
-extension.
-
-=item *
-
-GNU/Hurd is now supported.
-
-=item *
-
-Rhapsody/Darwin is now supported.
-
-=item *
-
-EPOC is now supported (on Psion 5).
-
-=item *
-
-The cygwin port (formerly cygwin32) has been greatly improved.
-
-=back
-
-=head2 DOS
-
-=over 4
-
-=item *
-
-Perl now works with djgpp 2.02 (and 2.03 alpha).
-
-=item *
-
-Environment variable names are not converted to uppercase any more.
-
-=item *
-
-Incorrect exit codes from backticks have been fixed.
-
-=item *
-
-This port continues to use its own builtin globbing (not File::Glob).
-
-=back
-
-=head2 OS390 (OpenEdition MVS)
-
-Support for this EBCDIC platform has not been renewed in this release.
-There are difficulties in reconciling Perl's standardization on UTF-8
-as its internal representation for characters with the EBCDIC character
-set, because the two are incompatible.
-
-It is unclear whether future versions will renew support for this
-platform, but the possibility exists.
-
-=head2 VMS
-
-Numerous revisions and extensions to configuration, build, testing, and
-installation process to accommodate core changes and VMS-specific options.
-
-Expand %ENV-handling code to allow runtime mapping to logical names,
-CLI symbols, and CRTL environ array.
-
-Extension of subprocess invocation code to accept filespecs as command
-"verbs".
-
-Add to Perl command line processing the ability to use default file types and
-to recognize Unix-style C<2E<gt>&1>.
-
-Expansion of File::Spec::VMS routines, and integration into ExtUtils::MM_VMS.
-
-Extension of ExtUtils::MM_VMS to handle complex extensions more flexibly.
-
-Barewords at start of Unix-syntax paths may be treated as text rather than
-only as logical names.
-
-Optional secure translation of several logical names used internally by Perl.
-
-Miscellaneous bugfixing and porting of new core code to VMS.
-
-Thanks are gladly extended to the many people who have contributed VMS
-patches, testing, and ideas.
-
-=head2 Win32
-
-Perl can now emulate fork() internally, using multiple interpreters running
-in different concurrent threads. This support must be enabled at build
-time. See L<perlfork> for detailed information.
-
-When given a pathname that consists only of a drivename, such as C<A:>,
-opendir() and stat() now use the current working directory for the drive
-rather than the drive root.
-
-The builtin XSUB functions in the Win32:: namespace are documented. See
-L<Win32>.
-
-$^X now contains the full path name of the running executable.
-
-A Win32::GetLongPathName() function is provided to complement
-Win32::GetFullPathName() and Win32::GetShortPathName(). See L<Win32>.
-
-POSIX::uname() is supported.
-
-system(1,...) now returns true process IDs rather than process
-handles. kill() accepts any real process id, rather than strictly
-return values from system(1,...).
-
-For better compatibility with Unix, C<kill(0, $pid)> can now be used to
-test whether a process exists.
-
-The C<Shell> module is supported.
-
-Better support for building Perl under command.com in Windows 95
-has been added.
-
-Scripts are read in binary mode by default to allow ByteLoader (and
-the filter mechanism in general) to work properly. For compatibility,
-the DATA filehandle will be set to text mode if a carriage return is
-detected at the end of the line containing the __END__ or __DATA__
-token; if not, the DATA filehandle will be left open in binary mode.
-Earlier versions always opened the DATA filehandle in text mode.
-
-The glob() operator is implemented via the C<File::Glob> extension,
-which supports glob syntax of the C shell. This increases the flexibility
-of the glob() operator, but there may be compatibility issues for
-programs that relied on the older globbing syntax. If you want to
-preserve compatibility with the older syntax, you might want to run
-perl with C<-MFile::DosGlob>. For details and compatibility information,
-see L<File::Glob>.
-
-=head1 Significant bug fixes
-
-=head2 <HANDLE> on empty files
-
-With C<$/> set to C<undef>, "slurping" an empty file returns a string of
-zero length (instead of C<undef>, as it used to) the first time the
-HANDLE is read after C<$/> is set to C<undef>. Further reads yield
-C<undef>.
-
-This means that the following will append "foo" to an empty file (it used
-to do nothing):
-
- perl -0777 -pi -e 's/^/foo/' empty_file
-
-The behaviour of:
-
- perl -pi -e 's/^/foo/' empty_file
-
-is unchanged (it continues to leave the file empty).
-
-=head2 C<eval '...'> improvements
-
-Line numbers (as reflected by caller() and most diagnostics) within
-C<eval '...'> were often incorrect where here documents were involved.
-This has been corrected.
-
-Lexical lookups for variables appearing in C<eval '...'> within
-functions that were themselves called within an C<eval '...'> were
-searching the wrong place for lexicals. The lexical search now
-correctly ends at the subroutine's block boundary.
-
-The use of C<return> within C<eval {...}> caused $@ not to be reset
-correctly when no exception occurred within the eval. This has
-been fixed.
-
-Parsing of here documents used to be flawed when they appeared as
-the replacement expression in C<eval 's/.../.../e'>. This has
-been fixed.
-
-=head2 All compilation errors are true errors
-
-Some "errors" encountered at compile time were by necessity
-generated as warnings followed by eventual termination of the
-program. This enabled more such errors to be reported in a
-single run, rather than causing a hard stop at the first error
-that was encountered.
-
-The mechanism for reporting such errors has been reimplemented
-to queue compile-time errors and report them at the end of the
-compilation as true errors rather than as warnings. This fixes
-cases where error messages leaked through in the form of warnings
-when code was compiled at run time using C<eval STRING>, and
-also allows such errors to be reliably trapped using C<eval "...">.
-
-=head2 Implicitly closed filehandles are safer
-
-Sometimes implicitly closed filehandles (as when they are localized,
-and Perl automatically closes them on exiting the scope) could
-inadvertently set $? or $!. This has been corrected.
-
-
-=head2 Behavior of list slices is more consistent
-
-When taking a slice of a literal list (as opposed to a slice of
-an array or hash), Perl used to return an empty list if the
-result happened to be composed of all undef values.
-
-The new behavior is to produce an empty list if (and only if)
-the original list was empty. Consider the following example:
-
- @a = (1,undef,undef,2)[2,1,2];
-
-The old behavior would have resulted in @a having no elements.
-The new behavior ensures it has three undefined elements.
-
-Note in particular that the behavior of slices of the following
-cases remains unchanged:
-
- @a = ()[1,2];
- @a = (getpwent)[7,0];
- @a = (anything_returning_empty_list())[2,1,2];
- @a = @b[2,1,2];
- @a = @c{'a','b','c'};
-
-See L<perldata>.
-
-=head2 C<(\$)> prototype and C<$foo{a}>
-
-A scalar reference prototype now correctly allows a hash or
-array element in that slot.
-
-=head2 C<goto &sub> and AUTOLOAD
-
-The C<goto &sub> construct works correctly when C<&sub> happens
-to be autoloaded.
-
-=head2 C<-bareword> allowed under C<use integer>
-
-The autoquoting of barewords preceded by C<-> did not work
-in prior versions when the C<integer> pragma was enabled.
-This has been fixed.
-
-=head2 Failures in DESTROY()
-
-When code in a destructor threw an exception, it went unnoticed
-in earlier versions of Perl, unless someone happened to be
-looking in $@ just after the point the destructor happened to
-run. Such failures are now visible as warnings when warnings are
-enabled.
-
-=head2 Locale bugs fixed
-
-printf() and sprintf() previously reset the numeric locale
-back to the default "C" locale. This has been fixed.
-
-Numbers formatted according to the local numeric locale
-(such as using a decimal comma instead of a decimal dot) caused
-"isn't numeric" warnings, even while the operations accessing
-those numbers produced correct results. These warnings have been
-discontinued.
-
-=head2 Memory leaks
-
-The C<eval 'return sub {...}'> construct could sometimes leak
-memory. This has been fixed.
-
-Operations that aren't filehandle constructors used to leak memory
-when used on invalid filehandles. This has been fixed.
-
-Constructs that modified C<@_> could fail to deallocate values
-in C<@_> and thus leak memory. This has been corrected.
-
-=head2 Spurious subroutine stubs after failed subroutine calls
-
-Perl could sometimes create empty subroutine stubs when a
-subroutine was not found in the package. Such cases stopped
-later method lookups from progressing into base packages.
-This has been corrected.
-
-=head2 Taint failures under C<-U>
-
-When running in unsafe mode, taint violations could sometimes
-cause silent failures. This has been fixed.
-
-=head2 END blocks and the C<-c> switch
-
-Prior versions used to run BEGIN B<and> END blocks when Perl was
-run in compile-only mode. Since this is typically not the expected
-behavior, END blocks are not executed anymore when the C<-c> switch
-is used, or if compilation fails.
-
-See L</"Support for CHECK blocks"> for how to run things when the compile
-phase ends.
-
-=head2 Potential to leak DATA filehandles
-
-Using the C<__DATA__> token creates an implicit filehandle to
-the file that contains the token. It is the program's
-responsibility to close it when it is done reading from it.
-
-This caveat is now better explained in the documentation.
-See L<perldata>.
-
-=head1 New or Changed Diagnostics
-
-=over 4
-
-=item "%s" variable %s masks earlier declaration in same %s
-
-(W misc) A "my" or "our" variable has been redeclared in the current scope or statement,
-effectively eliminating all access to the previous instance. This is almost
-always a typographical error. Note that the earlier variable will still exist
-until the end of the scope or until all closure referents to it are
-destroyed.
-
-=item "my sub" not yet implemented
-
-(F) Lexically scoped subroutines are not yet implemented. Don't try that
-yet.
-
-=item "our" variable %s redeclared
-
-(W misc) You seem to have already declared the same global once before in the
-current lexical scope.
-
-=item '!' allowed only after types %s
-
-(F) The '!' is allowed in pack() and unpack() only after certain types.
-See L<perlfunc/pack>.
-
-=item / cannot take a count
-
-(F) You had an unpack template indicating a counted-length string,
-but you have also specified an explicit size for the string.
-See L<perlfunc/pack>.
-
-=item / must be followed by a, A or Z
-
-(F) You had an unpack template indicating a counted-length string,
-which must be followed by one of the letters a, A or Z
-to indicate what sort of string is to be unpacked.
-See L<perlfunc/pack>.
-
-=item / must be followed by a*, A* or Z*
-
-(F) You had a pack template indicating a counted-length string,
-Currently the only things that can have their length counted are a*, A* or Z*.
-See L<perlfunc/pack>.
-
-=item / must follow a numeric type
-
-(F) You had an unpack template that contained a '#',
-but this did not follow some numeric unpack specification.
-See L<perlfunc/pack>.
-
-=item /%s/: Unrecognized escape \\%c passed through
-
-(W regexp) You used a backslash-character combination which is not recognized
-by Perl. This combination appears in an interpolated variable or a
-C<'>-delimited regular expression. The character was understood literally.
-
-=item /%s/: Unrecognized escape \\%c in character class passed through
-
-(W regexp) You used a backslash-character combination which is not recognized
-by Perl inside character classes. The character was understood literally.
-
-=item /%s/ should probably be written as "%s"
-
-(W syntax) You have used a pattern where Perl expected to find a string,
-as in the first argument to C<join>. Perl will treat the true
-or false result of matching the pattern against $_ as the string,
-which is probably not what you had in mind.
-
-=item %s() called too early to check prototype
-
-(W prototype) You've called a function that has a prototype before the parser saw a
-definition or declaration for it, and Perl could not check that the call
-conforms to the prototype. You need to either add an early prototype
-declaration for the subroutine in question, or move the subroutine
-definition ahead of the call to get proper prototype checking. Alternatively,
-if you are certain that you're calling the function correctly, you may put
-an ampersand before the name to avoid the warning. See L<perlsub>.
-
-=item %s argument is not a HASH or ARRAY element
-
-(F) The argument to exists() must be a hash or array element, such as:
-
- $foo{$bar}
- $ref->{"susie"}[12]
-
-=item %s argument is not a HASH or ARRAY element or slice
-
-(F) The argument to delete() must be either a hash or array element, such as:
-
- $foo{$bar}
- $ref->{"susie"}[12]
-
-or a hash or array slice, such as:
-
- @foo[$bar, $baz, $xyzzy]
- @{$ref->[12]}{"susie", "queue"}
-
-=item %s argument is not a subroutine name
-
-(F) The argument to exists() for C<exists &sub> must be a subroutine
-name, and not a subroutine call. C<exists &sub()> will generate this error.
-
-=item %s package attribute may clash with future reserved word: %s
-
-(W reserved) A lowercase attribute name was used that had a package-specific handler.
-That name might have a meaning to Perl itself some day, even though it
-doesn't yet. Perhaps you should use a mixed-case attribute name, instead.
-See L<attributes>.
-
-=item (in cleanup) %s
-
-(W misc) This prefix usually indicates that a DESTROY() method raised
-the indicated exception. Since destructors are usually called by
-the system at arbitrary points during execution, and often a vast
-number of times, the warning is issued only once for any number
-of failures that would otherwise result in the same message being
-repeated.
-
-Failure of user callbacks dispatched using the C<G_KEEPERR> flag
-could also result in this warning. See L<perlcall/G_KEEPERR>.
-
-=item <> should be quotes
-
-(F) You wrote C<< require <file> >> when you should have written
-C<require 'file'>.
-
-=item Attempt to join self
-
-(F) You tried to join a thread from within itself, which is an
-impossible task. You may be joining the wrong thread, or you may
-need to move the join() to some other thread.
-
-=item Bad evalled substitution pattern
-
-(F) You've used the /e switch to evaluate the replacement for a
-substitution, but perl found a syntax error in the code to evaluate,
-most likely an unexpected right brace '}'.
-
-=item Bad realloc() ignored
-
-(S) An internal routine called realloc() on something that had never been
-malloc()ed in the first place. Mandatory, but can be disabled by
-setting environment variable C<PERL_BADFREE> to 1.
-
-=item Bareword found in conditional
-
-(W bareword) The compiler found a bareword where it expected a conditional,
-which often indicates that an || or && was parsed as part of the
-last argument of the previous construct, for example:
-
- open FOO || die;
-
-It may also indicate a misspelled constant that has been interpreted
-as a bareword:
-
- use constant TYPO => 1;
- if (TYOP) { print "foo" }
-
-The C<strict> pragma is useful in avoiding such errors.
-
-=item Binary number > 0b11111111111111111111111111111111 non-portable
-
-(W portable) The binary number you specified is larger than 2**32-1
-(4294967295) and therefore non-portable between systems. See
-L<perlport> for more on portability concerns.
-
-=item Bit vector size > 32 non-portable
-
-(W portable) Using bit vector sizes larger than 32 is non-portable.
-
-=item Buffer overflow in prime_env_iter: %s
-
-(W internal) A warning peculiar to VMS. While Perl was preparing to iterate over
-%ENV, it encountered a logical name or symbol definition which was too long,
-so it was truncated to the string shown.
-
-=item Can't check filesystem of script "%s"
-
-(P) For some reason you can't check the filesystem of the script for nosuid.
-
-=item Can't declare class for non-scalar %s in "%s"
-
-(S) Currently, only scalar variables can declared with a specific class
-qualifier in a "my" or "our" declaration. The semantics may be extended
-for other types of variables in future.
-
-=item Can't declare %s in "%s"
-
-(F) Only scalar, array, and hash variables may be declared as "my" or
-"our" variables. They must have ordinary identifiers as names.
-
-=item Can't ignore signal CHLD, forcing to default
-
-(W signal) Perl has detected that it is being run with the SIGCHLD signal
-(sometimes known as SIGCLD) disabled. Since disabling this signal
-will interfere with proper determination of exit status of child
-processes, Perl has reset the signal to its default value.
-This situation typically indicates that the parent program under
-which Perl may be running (e.g., cron) is being very careless.
-
-=item Can't modify non-lvalue subroutine call
-
-(F) Subroutines meant to be used in lvalue context should be declared as
-such, see L<perlsub/"Lvalue subroutines">.
-
-=item Can't read CRTL environ
-
-(S) A warning peculiar to VMS. Perl tried to read an element of %ENV
-from the CRTL's internal environment array and discovered the array was
-missing. You need to figure out where your CRTL misplaced its environ
-or define F<PERL_ENV_TABLES> (see L<perlvms>) so that environ is not searched.
-
-=item Can't remove %s: %s, skipping file
-
-(S) You requested an inplace edit without creating a backup file. Perl
-was unable to remove the original file to replace it with the modified
-file. The file was left unmodified.
-
-=item Can't return %s from lvalue subroutine
-
-(F) Perl detected an attempt to return illegal lvalues (such
-as temporary or readonly values) from a subroutine used as an lvalue.
-This is not allowed.
-
-=item Can't weaken a nonreference
-
-(F) You attempted to weaken something that was not a reference. Only
-references can be weakened.
-
-=item Character class [:%s:] unknown
-
-(F) The class in the character class [: :] syntax is unknown.
-See L<perlre>.
-
-=item Character class syntax [%s] belongs inside character classes
-
-(W unsafe) The character class constructs [: :], [= =], and [. .] go
-I<inside> character classes, the [] are part of the construct,
-for example: /[012[:alpha:]345]/. Note that [= =] and [. .]
-are not currently implemented; they are simply placeholders for
-future extensions.
-
-=item Constant is not %s reference
-
-(F) A constant value (perhaps declared using the C<use constant> pragma)
-is being dereferenced, but it amounts to the wrong type of reference. The
-message indicates the type of reference that was expected. This usually
-indicates a syntax error in dereferencing the constant value.
-See L<perlsub/"Constant Functions"> and L<constant>.
-
-=item constant(%s): %s
-
-(F) The parser found inconsistencies either while attempting to define an
-overloaded constant, or when trying to find the character name specified
-in the C<\N{...}> escape. Perhaps you forgot to load the corresponding
-C<overload> or C<charnames> pragma? See L<charnames> and L<overload>.
-
-=item CORE::%s is not a keyword
-
-(F) The CORE:: namespace is reserved for Perl keywords.
-
-=item defined(@array) is deprecated
-
-(D) defined() is not usually useful on arrays because it checks for an
-undefined I<scalar> value. If you want to see if the array is empty,
-just use C<if (@array) { # not empty }> for example.
-
-=item defined(%hash) is deprecated
-
-(D) defined() is not usually useful on hashes because it checks for an
-undefined I<scalar> value. If you want to see if the hash is empty,
-just use C<if (%hash) { # not empty }> for example.
-
-=item Did not produce a valid header
-
-See Server error.
-
-=item (Did you mean "local" instead of "our"?)
-
-(W misc) Remember that "our" does not localize the declared global variable.
-You have declared it again in the same lexical scope, which seems superfluous.
-
-=item Document contains no data
-
-See Server error.
-
-=item entering effective %s failed
-
-(F) While under the C<use filetest> pragma, switching the real and
-effective uids or gids failed.
-
-=item false [] range "%s" in regexp
-
-(W regexp) A character class range must start and end at a literal character, not
-another character class like C<\d> or C<[:alpha:]>. The "-" in your false
-range is interpreted as a literal "-". Consider quoting the "-", "\-".
-See L<perlre>.
-
-=item Filehandle %s opened only for output
-
-(W io) You tried to read from a filehandle opened only for writing. If you
-intended it to be a read/write filehandle, you needed to open it with
-"+<" or "+>" or "+>>" instead of with "<" or nothing. If
-you intended only to read from the file, use "<". See
-L<perlfunc/open>.
-
-=item flock() on closed filehandle %s
-
-(W closed) The filehandle you're attempting to flock() got itself closed some
-time before now. Check your logic flow. flock() operates on filehandles.
-Are you attempting to call flock() on a dirhandle by the same name?
-
-=item Global symbol "%s" requires explicit package name
-
-(F) You've said "use strict vars", which indicates that all variables
-must either be lexically scoped (using "my"), declared beforehand using
-"our", or explicitly qualified to say which package the global variable
-is in (using "::").
-
-=item Hexadecimal number > 0xffffffff non-portable
-
-(W portable) The hexadecimal number you specified is larger than 2**32-1
-(4294967295) and therefore non-portable between systems. See
-L<perlport> for more on portability concerns.
-
-=item Ill-formed CRTL environ value "%s"
-
-(W internal) A warning peculiar to VMS. Perl tried to read the CRTL's internal
-environ array, and encountered an element without the C<=> delimiter
-used to separate keys from values. The element is ignored.
-
-=item Ill-formed message in prime_env_iter: |%s|
-
-(W internal) A warning peculiar to VMS. Perl tried to read a logical name
-or CLI symbol definition when preparing to iterate over %ENV, and
-didn't see the expected delimiter between key and value, so the
-line was ignored.
-
-=item Illegal binary digit %s
-
-(F) You used a digit other than 0 or 1 in a binary number.
-
-=item Illegal binary digit %s ignored
-
-(W digit) You may have tried to use a digit other than 0 or 1 in a binary number.
-Interpretation of the binary number stopped before the offending digit.
-
-=item Illegal number of bits in vec
-
-(F) The number of bits in vec() (the third argument) must be a power of
-two from 1 to 32 (or 64, if your platform supports that).
-
-=item Integer overflow in %s number
-
-(W overflow) The hexadecimal, octal or binary number you have specified either
-as a literal or as an argument to hex() or oct() is too big for your
-architecture, and has been converted to a floating point number. On a
-32-bit architecture the largest hexadecimal, octal or binary number
-representable without overflow is 0xFFFFFFFF, 037777777777, or
-0b11111111111111111111111111111111 respectively. Note that Perl
-transparently promotes all numbers to a floating point representation
-internally--subject to loss of precision errors in subsequent
-operations.
-
-=item Invalid %s attribute: %s
-
-The indicated attribute for a subroutine or variable was not recognized
-by Perl or by a user-supplied handler. See L<attributes>.
-
-=item Invalid %s attributes: %s
-
-The indicated attributes for a subroutine or variable were not recognized
-by Perl or by a user-supplied handler. See L<attributes>.
-
-=item invalid [] range "%s" in regexp
-
-The offending range is now explicitly displayed.
-
-=item Invalid separator character %s in attribute list
-
-(F) Something other than a colon or whitespace was seen between the
-elements of an attribute list. If the previous attribute
-had a parenthesised parameter list, perhaps that list was terminated
-too soon. See L<attributes>.
-
-=item Invalid separator character %s in subroutine attribute list
-
-(F) Something other than a colon or whitespace was seen between the
-elements of a subroutine attribute list. If the previous attribute
-had a parenthesised parameter list, perhaps that list was terminated
-too soon.
-
-=item leaving effective %s failed
-
-(F) While under the C<use filetest> pragma, switching the real and
-effective uids or gids failed.
-
-=item Lvalue subs returning %s not implemented yet
-
-(F) Due to limitations in the current implementation, array and hash
-values cannot be returned in subroutines used in lvalue context.
-See L<perlsub/"Lvalue subroutines">.
-
-=item Method %s not permitted
-
-See Server error.
-
-=item Missing %sbrace%s on \N{}
-
-(F) Wrong syntax of character name literal C<\N{charname}> within
-double-quotish context.
-
-=item Missing command in piped open
-
-(W pipe) You used the C<open(FH, "| command")> or C<open(FH, "command |")>
-construction, but the command was missing or blank.
-
-=item Missing name in "my sub"
-
-(F) The reserved syntax for lexically scoped subroutines requires that they
-have a name with which they can be found.
-
-=item No %s specified for -%c
-
-(F) The indicated command line switch needs a mandatory argument, but
-you haven't specified one.
-
-=item No package name allowed for variable %s in "our"
-
-(F) Fully qualified variable names are not allowed in "our" declarations,
-because that doesn't make much sense under existing semantics. Such
-syntax is reserved for future extensions.
-
-=item No space allowed after -%c
-
-(F) The argument to the indicated command line switch must follow immediately
-after the switch, without intervening spaces.
-
-=item no UTC offset information; assuming local time is UTC
-
-(S) A warning peculiar to VMS. Perl was unable to find the local
-timezone offset, so it's assuming that local system time is equivalent
-to UTC. If it's not, define the logical name F<SYS$TIMEZONE_DIFFERENTIAL>
-to translate to the number of seconds which need to be added to UTC to
-get local time.
-
-=item Octal number > 037777777777 non-portable
-
-(W portable) The octal number you specified is larger than 2**32-1 (4294967295)
-and therefore non-portable between systems. See L<perlport> for more
-on portability concerns.
-
-See also L<perlport> for writing portable code.
-
-=item panic: del_backref
-
-(P) Failed an internal consistency check while trying to reset a weak
-reference.
-
-=item panic: kid popen errno read
-
-(F) forked child returned an incomprehensible message about its errno.
-
-=item panic: magic_killbackrefs
-
-(P) Failed an internal consistency check while trying to reset all weak
-references to an object.
-
-=item Parentheses missing around "%s" list
-
-(W parenthesis) You said something like
-
- my $foo, $bar = @_;
-
-when you meant
-
- my ($foo, $bar) = @_;
-
-Remember that "my", "our", and "local" bind tighter than comma.
-
-=item Possible unintended interpolation of %s in string
-
-(W ambiguous) It used to be that Perl would try to guess whether you
-wanted an array interpolated or a literal @. It no longer does this;
-arrays are now I<always> interpolated into strings. This means that
-if you try something like:
-
- print "fred@example.com";
-
-and the array C<@example> doesn't exist, Perl is going to print
-C<fred.com>, which is probably not what you wanted. To get a literal
-C<@> sign in a string, put a backslash before it, just as you would
-to get a literal C<$> sign.
-
-=item Possible Y2K bug: %s
-
-(W y2k) You are concatenating the number 19 with another number, which
-could be a potential Year 2000 problem.
-
-=item pragma "attrs" is deprecated, use "sub NAME : ATTRS" instead
-
-(W deprecated) You have written something like this:
-
- sub doit
- {
- use attrs qw(locked);
- }
-
-You should use the new declaration syntax instead.
-
- sub doit : locked
- {
- ...
-
-The C<use attrs> pragma is now obsolete, and is only provided for
-backward-compatibility. See L<perlsub/"Subroutine Attributes">.
-
-=item Premature end of script headers
-
-See Server error.
-
-=item Repeat count in pack overflows
-
-(F) You can't specify a repeat count so large that it overflows
-your signed integers. See L<perlfunc/pack>.
-
-=item Repeat count in unpack overflows
-
-(F) You can't specify a repeat count so large that it overflows
-your signed integers. See L<perlfunc/unpack>.
-
-=item realloc() of freed memory ignored
-
-(S) An internal routine called realloc() on something that had already
-been freed.
-
-=item Reference is already weak
-
-(W misc) You have attempted to weaken a reference that is already weak.
-Doing so has no effect.
-
-=item setpgrp can't take arguments
-
-(F) Your system has the setpgrp() from BSD 4.2, which takes no arguments,
-unlike POSIX setpgid(), which takes a process ID and process group ID.
-
-=item Strange *+?{} on zero-length expression
-
-(W regexp) You applied a regular expression quantifier in a place where it
-makes no sense, such as on a zero-width assertion.
-Try putting the quantifier inside the assertion instead. For example,
-the way to match "abc" provided that it is followed by three
-repetitions of "xyz" is C</abc(?=(?:xyz){3})/>, not C</abc(?=xyz){3}/>.
-
-=item switching effective %s is not implemented
-
-(F) While under the C<use filetest> pragma, we cannot switch the
-real and effective uids or gids.
-
-=item This Perl can't reset CRTL environ elements (%s)
-
-=item This Perl can't set CRTL environ elements (%s=%s)
-
-(W internal) Warnings peculiar to VMS. You tried to change or delete an element
-of the CRTL's internal environ array, but your copy of Perl wasn't
-built with a CRTL that contained the setenv() function. You'll need to
-rebuild Perl with a CRTL that does, or redefine F<PERL_ENV_TABLES> (see
-L<perlvms>) so that the environ array isn't the target of the change to
-%ENV which produced the warning.
-
-=item Too late to run %s block
-
-(W void) A CHECK or INIT block is being defined during run time proper,
-when the opportunity to run them has already passed. Perhaps you are
-loading a file with C<require> or C<do> when you should be using
-C<use> instead. Or perhaps you should put the C<require> or C<do>
-inside a BEGIN block.
-
-=item Unknown open() mode '%s'
-
-(F) The second argument of 3-argument open() is not among the list
-of valid modes: C<< < >>, C<< > >>, C<<< >> >>>, C<< +< >>,
-C<< +> >>, C<<< +>> >>>, C<-|>, C<|->.
-
-=item Unknown process %x sent message to prime_env_iter: %s
-
-(P) An error peculiar to VMS. Perl was reading values for %ENV before
-iterating over it, and someone else stuck a message in the stream of
-data Perl expected. Someone's very confused, or perhaps trying to
-subvert Perl's population of %ENV for nefarious purposes.
-
-=item Unrecognized escape \\%c passed through
-
-(W misc) You used a backslash-character combination which is not recognized
-by Perl. The character was understood literally.
-
-=item Unterminated attribute parameter in attribute list
-
-(F) The lexer saw an opening (left) parenthesis character while parsing an
-attribute list, but the matching closing (right) parenthesis
-character was not found. You may need to add (or remove) a backslash
-character to get your parentheses to balance. See L<attributes>.
-
-=item Unterminated attribute list
-
-(F) The lexer found something other than a simple identifier at the start
-of an attribute, and it wasn't a semicolon or the start of a
-block. Perhaps you terminated the parameter list of the previous attribute
-too soon. See L<attributes>.
-
-=item Unterminated attribute parameter in subroutine attribute list
-
-(F) The lexer saw an opening (left) parenthesis character while parsing a
-subroutine attribute list, but the matching closing (right) parenthesis
-character was not found. You may need to add (or remove) a backslash
-character to get your parentheses to balance.
-
-=item Unterminated subroutine attribute list
-
-(F) The lexer found something other than a simple identifier at the start
-of a subroutine attribute, and it wasn't a semicolon or the start of a
-block. Perhaps you terminated the parameter list of the previous attribute
-too soon.
-
-=item Value of CLI symbol "%s" too long
-
-(W misc) A warning peculiar to VMS. Perl tried to read the value of an %ENV
-element from a CLI symbol table, and found a resultant string longer
-than 1024 characters. The return value has been truncated to 1024
-characters.
-
-=item Version number must be a constant number
-
-(P) The attempt to translate a C<use Module n.n LIST> statement into
-its equivalent C<BEGIN> block found an internal inconsistency with
-the version number.
-
-=back
-
-=head1 New tests
-
-=over 4
-
-=item lib/attrs
-
-Compatibility tests for C<sub : attrs> vs the older C<use attrs>.
-
-=item lib/env
-
-Tests for new environment scalar capability (e.g., C<use Env qw($BAR);>).
-
-=item lib/env-array
-
-Tests for new environment array capability (e.g., C<use Env qw(@PATH);>).
-
-=item lib/io_const
-
-IO constants (SEEK_*, _IO*).
-
-=item lib/io_dir
-
-Directory-related IO methods (new, read, close, rewind, tied delete).
-
-=item lib/io_multihomed
-
-INET sockets with multi-homed hosts.
-
-=item lib/io_poll
-
-IO poll().
-
-=item lib/io_unix
-
-UNIX sockets.
-
-=item op/attrs
-
-Regression tests for C<my ($x,@y,%z) : attrs> and <sub : attrs>.
-
-=item op/filetest
-
-File test operators.
-
-=item op/lex_assign
-
-Verify operations that access pad objects (lexicals and temporaries).
-
-=item op/exists_sub
-
-Verify C<exists &sub> operations.
-
-=back
-
-=head1 Incompatible Changes
-
-=head2 Perl Source Incompatibilities
-
-Beware that any new warnings that have been added or old ones
-that have been enhanced are B<not> considered incompatible changes.
-
-Since all new warnings must be explicitly requested via the C<-w>
-switch or the C<warnings> pragma, it is ultimately the programmer's
-responsibility to ensure that warnings are enabled judiciously.
-
-=over 4
-
-=item CHECK is a new keyword
-
-All subroutine definitions named CHECK are now special. See
-C</"Support for CHECK blocks"> for more information.
-
-=item Treatment of list slices of undef has changed
-
-There is a potential incompatibility in the behavior of list slices
-that are comprised entirely of undefined values.
-See L</"Behavior of list slices is more consistent">.
-
-=item Format of $English::PERL_VERSION is different
-
-The English module now sets $PERL_VERSION to $^V (a string value) rather
-than C<$]> (a numeric value). This is a potential incompatibility.
-Send us a report via perlbug if you are affected by this.
-
-See L</"Improved Perl version numbering system"> for the reasons for
-this change.
-
-=item Literals of the form C<1.2.3> parse differently
-
-Previously, numeric literals with more than one dot in them were
-interpreted as a floating point number concatenated with one or more
-numbers. Such "numbers" are now parsed as strings composed of the
-specified ordinals.
-
-For example, C<print 97.98.99> used to output C<97.9899> in earlier
-versions, but now prints C<abc>.
-
-See L</"Support for strings represented as a vector of ordinals">.
-
-=item Possibly changed pseudo-random number generator
-
-Perl programs that depend on reproducing a specific set of pseudo-random
-numbers may now produce different output due to improvements made to the
-rand() builtin. You can use C<sh Configure -Drandfunc=rand> to obtain
-the old behavior.
-
-See L</"Better pseudo-random number generator">.
-
-=item Hashing function for hash keys has changed
-
-Even though Perl hashes are not order preserving, the apparently
-random order encountered when iterating on the contents of a hash
-is actually determined by the hashing algorithm used. Improvements
-in the algorithm may yield a random order that is B<different> from
-that of previous versions, especially when iterating on hashes.
-
-See L</"Better worst-case behavior of hashes"> for additional
-information.
-
-=item C<undef> fails on read only values
-
-Using the C<undef> operator on a readonly value (such as $1) has
-the same effect as assigning C<undef> to the readonly value--it
-throws an exception.
-
-=item Close-on-exec bit may be set on pipe and socket handles
-
-Pipe and socket handles are also now subject to the close-on-exec
-behavior determined by the special variable $^F.
-
-See L</"More consistent close-on-exec behavior">.
-
-=item Writing C<"$$1"> to mean C<"${$}1"> is unsupported
-
-Perl 5.004 deprecated the interpretation of C<$$1> and
-similar within interpolated strings to mean C<$$ . "1">,
-but still allowed it.
-
-In Perl 5.6.0 and later, C<"$$1"> always means C<"${$1}">.
-
-=item delete(), each(), values() and C<\(%h)>
-
-operate on aliases to values, not copies
-
-delete(), each(), values() and hashes (e.g. C<\(%h)>)
-in a list context return the actual
-values in the hash, instead of copies (as they used to in earlier
-versions). Typical idioms for using these constructs copy the
-returned values, but this can make a significant difference when
-creating references to the returned values. Keys in the hash are still
-returned as copies when iterating on a hash.
-
-See also L</"delete(), each(), values() and hash iteration are faster">.
-
-=item vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS
-
-vec() generates a run-time error if the BITS argument is not
-a valid power-of-two integer.
-
-=item Text of some diagnostic output has changed
-
-Most references to internal Perl operations in diagnostics
-have been changed to be more descriptive. This may be an
-issue for programs that may incorrectly rely on the exact
-text of diagnostics for proper functioning.
-
-=item C<%@> has been removed
-
-The undocumented special variable C<%@> that used to accumulate
-"background" errors (such as those that happen in DESTROY())
-has been removed, because it could potentially result in memory
-leaks.
-
-=item Parenthesized not() behaves like a list operator
-
-The C<not> operator now falls under the "if it looks like a function,
-it behaves like a function" rule.
-
-As a result, the parenthesized form can be used with C<grep> and C<map>.
-The following construct used to be a syntax error before, but it works
-as expected now:
-
- grep not($_), @things;
-
-On the other hand, using C<not> with a literal list slice may not
-work. The following previously allowed construct:
-
- print not (1,2,3)[0];
-
-needs to be written with additional parentheses now:
-
- print not((1,2,3)[0]);
-
-The behavior remains unaffected when C<not> is not followed by parentheses.
-
-=item Semantics of bareword prototype C<(*)> have changed
-
-The semantics of the bareword prototype C<*> have changed. Perl 5.005
-always coerced simple scalar arguments to a typeglob, which wasn't useful
-in situations where the subroutine must distinguish between a simple
-scalar and a typeglob. The new behavior is to not coerce bareword
-arguments to a typeglob. The value will always be visible as either
-a simple scalar or as a reference to a typeglob.
-
-See L</"More functional bareword prototype (*)">.
-
-=item Semantics of bit operators may have changed on 64-bit platforms
-
-If your platform is either natively 64-bit or if Perl has been
-configured to used 64-bit integers, i.e., $Config{ivsize} is 8,
-there may be a potential incompatibility in the behavior of bitwise
-numeric operators (& | ^ ~ << >>). These operators used to strictly
-operate on the lower 32 bits of integers in previous versions, but now
-operate over the entire native integral width. In particular, note
-that unary C<~> will produce different results on platforms that have
-different $Config{ivsize}. For portability, be sure to mask off
-the excess bits in the result of unary C<~>, e.g., C<~$x & 0xffffffff>.
-
-See L</"Bit operators support full native integer width">.
-
-=item More builtins taint their results
-
-As described in L</"Improved security features">, there may be more
-sources of taint in a Perl program.
-
-To avoid these new tainting behaviors, you can build Perl with the
-Configure option C<-Accflags=-DINCOMPLETE_TAINTS>. Beware that the
-ensuing perl binary may be insecure.
-
-=back
-
-=head2 C Source Incompatibilities
-
-=over 4
-
-=item C<PERL_POLLUTE>
-
-Release 5.005 grandfathered old global symbol names by providing preprocessor
-macros for extension source compatibility. As of release 5.6.0, these
-preprocessor definitions are not available by default. You need to explicitly
-compile perl with C<-DPERL_POLLUTE> to get these definitions. For
-extensions still using the old symbols, this option can be
-specified via MakeMaker:
-
- perl Makefile.PL POLLUTE=1
-
-=item C<PERL_IMPLICIT_CONTEXT>
-
-This new build option provides a set of macros for all API functions
-such that an implicit interpreter/thread context argument is passed to
-every API function. As a result of this, something like C<sv_setsv(foo,bar)>
-amounts to a macro invocation that actually translates to something like
-C<Perl_sv_setsv(my_perl,foo,bar)>. While this is generally expected
-to not have any significant source compatibility issues, the difference
-between a macro and a real function call will need to be considered.
-
-This means that there B<is> a source compatibility issue as a result of
-this if your extensions attempt to use pointers to any of the Perl API
-functions.
-
-Note that the above issue is not relevant to the default build of
-Perl, whose interfaces continue to match those of prior versions
-(but subject to the other options described here).
-
-
-See L<perlguts/Background and PERL_IMPLICIT_CONTEXT> for detailed information on the
-ramifications of building Perl with this option.
-
- NOTE: PERL_IMPLICIT_CONTEXT is automatically enabled whenever Perl is built
- with one of -Dusethreads, -Dusemultiplicity, or both. It is not
- intended to be enabled by users at this time.
-
-=item C<PERL_POLLUTE_MALLOC>
-
-Enabling Perl's malloc in release 5.005 and earlier caused the namespace of
-the system's malloc family of functions to be usurped by the Perl versions,
-since by default they used the same names. Besides causing problems on
-platforms that do not allow these functions to be cleanly replaced, this
-also meant that the system versions could not be called in programs that
-used Perl's malloc. Previous versions of Perl have allowed this behaviour
-to be suppressed with the HIDEMYMALLOC and EMBEDMYMALLOC preprocessor
-definitions.
-
-As of release 5.6.0, Perl's malloc family of functions have default names
-distinct from the system versions. You need to explicitly compile perl with
-C<-DPERL_POLLUTE_MALLOC> to get the older behaviour. HIDEMYMALLOC
-and EMBEDMYMALLOC have no effect, since the behaviour they enabled is now
-the default.
-
-Note that these functions do B<not> constitute Perl's memory allocation API.
-See L<perlguts/"Memory Allocation"> for further information about that.
-
-=back
-
-=head2 Compatible C Source API Changes
-
-=over 4
-
-=item C<PATCHLEVEL> is now C<PERL_VERSION>
-
-The cpp macros C<PERL_REVISION>, C<PERL_VERSION>, and C<PERL_SUBVERSION>
-are now available by default from perl.h, and reflect the base revision,
-patchlevel, and subversion respectively. C<PERL_REVISION> had no
-prior equivalent, while C<PERL_VERSION> and C<PERL_SUBVERSION> were
-previously available as C<PATCHLEVEL> and C<SUBVERSION>.
-
-The new names cause less pollution of the B<cpp> namespace and reflect what
-the numbers have come to stand for in common practice. For compatibility,
-the old names are still supported when F<patchlevel.h> is explicitly
-included (as required before), so there is no source incompatibility
-from the change.
-
-=back
-
-=head2 Binary Incompatibilities
-
-In general, the default build of this release is expected to be binary
-compatible for extensions built with the 5.005 release or its maintenance
-versions. However, specific platforms may have broken binary compatibility
-due to changes in the defaults used in hints files. Therefore, please be
-sure to always check the platform-specific README files for any notes to
-the contrary.
-
-The usethreads or usemultiplicity builds are B<not> binary compatible
-with the corresponding builds in 5.005.
-
-On platforms that require an explicit list of exports (AIX, OS/2 and Windows,
-among others), purely internal symbols such as parser functions and the
-run time opcodes are not exported by default. Perl 5.005 used to export
-all functions irrespective of whether they were considered part of the
-public API or not.
-
-For the full list of public API functions, see L<perlapi>.
-
-=head1 Known Problems
-
-=head2 Thread test failures
-
-The subtests 19 and 20 of lib/thr5005.t test are known to fail due to
-fundamental problems in the 5.005 threading implementation. These are
-not new failures--Perl 5.005_0x has the same bugs, but didn't have these
-tests.
-
-=head2 EBCDIC platforms not supported
-
-In earlier releases of Perl, EBCDIC environments like OS390 (also
-known as Open Edition MVS) and VM-ESA were supported. Due to changes
-required by the UTF-8 (Unicode) support, the EBCDIC platforms are not
-supported in Perl 5.6.0.
-
-=head2 In 64-bit HP-UX the lib/io_multihomed test may hang
-
-The lib/io_multihomed test may hang in HP-UX if Perl has been
-configured to be 64-bit. Because other 64-bit platforms do not
-hang in this test, HP-UX is suspect. All other tests pass
-in 64-bit HP-UX. The test attempts to create and connect to
-"multihomed" sockets (sockets which have multiple IP addresses).
-
-=head2 NEXTSTEP 3.3 POSIX test failure
-
-In NEXTSTEP 3.3p2 the implementation of the strftime(3) in the
-operating system libraries is buggy: the %j format numbers the days of
-a month starting from zero, which, while being logical to programmers,
-will cause the subtests 19 to 27 of the lib/posix test may fail.
-
-=head2 Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with gcc
-
-If compiled with gcc 2.95 the lib/sdbm test will fail (dump core).
-The cure is to use the vendor cc, it comes with the operating system
-and produces good code.
-
-=head2 UNICOS/mk CC failures during Configure run
-
-In UNICOS/mk the following errors may appear during the Configure run:
-
- Guessing which symbols your C compiler and preprocessor define...
- CC-20 cc: ERROR File = try.c, Line = 3
- ...
- bad switch yylook 79bad switch yylook 79bad switch yylook 79bad switch yylook 79#ifdef A29K
- ...
- 4 errors detected in the compilation of "try.c".
-
-The culprit is the broken awk of UNICOS/mk. The effect is fortunately
-rather mild: Perl itself is not adversely affected by the error, only
-the h2ph utility coming with Perl, and that is rather rarely needed
-these days.
-
-=head2 Arrow operator and arrays
-
-When the left argument to the arrow operator C<< -> >> is an array, or
-the C<scalar> operator operating on an array, the result of the
-operation must be considered erroneous. For example:
-
- @x->[2]
- scalar(@x)->[2]
-
-These expressions will get run-time errors in some future release of
-Perl.
-
-=head2 Experimental features
-
-As discussed above, many features are still experimental. Interfaces and
-implementation of these features are subject to change, and in extreme cases,
-even subject to removal in some future release of Perl. These features
-include the following:
-
-=over 4
-
-=item Threads
-
-=item Unicode
-
-=item 64-bit support
-
-=item Lvalue subroutines
-
-=item Weak references
-
-=item The pseudo-hash data type
-
-=item The Compiler suite
-
-=item Internal implementation of file globbing
-
-=item The DB module
-
-=item The regular expression code constructs:
-
-C<(?{ code })> and C<(??{ code })>
-
-=back
-
-=head1 Obsolete Diagnostics
-
-=over 4
-
-=item Character class syntax [: :] is reserved for future extensions
-
-(W) Within regular expression character classes ([]) the syntax beginning
-with "[:" and ending with ":]" is reserved for future extensions.
-If you need to represent those character sequences inside a regular
-expression character class, just quote the square brackets with the
-backslash: "\[:" and ":\]".
-
-=item Ill-formed logical name |%s| in prime_env_iter
-
-(W) A warning peculiar to VMS. A logical name was encountered when preparing
-to iterate over %ENV which violates the syntactic rules governing logical
-names. Because it cannot be translated normally, it is skipped, and will not
-appear in %ENV. This may be a benign occurrence, as some software packages
-might directly modify logical name tables and introduce nonstandard names,
-or it may indicate that a logical name table has been corrupted.
-
-=item In string, @%s now must be written as \@%s
-
-The description of this error used to say:
-
- (Someday it will simply assume that an unbackslashed @
- interpolates an array.)
-
-That day has come, and this fatal error has been removed. It has been
-replaced by a non-fatal warning instead.
-See L</Arrays now always interpolate into double-quoted strings> for
-details.
-
-=item Probable precedence problem on %s
-
-(W) The compiler found a bareword where it expected a conditional,
-which often indicates that an || or && was parsed as part of the
-last argument of the previous construct, for example:
-
- open FOO || die;
-
-=item regexp too big
-
-(F) The current implementation of regular expressions uses shorts as
-address offsets within a string. Unfortunately this means that if
-the regular expression compiles to longer than 32767, it'll blow up.
-Usually when you want a regular expression this big, there is a better
-way to do it with multiple statements. See L<perlre>.
-
-=item Use of "$$<digit>" to mean "${$}<digit>" is deprecated
-
-(D) Perl versions before 5.004 misinterpreted any type marker followed
-by "$" and a digit. For example, "$$0" was incorrectly taken to mean
-"${$}0" instead of "${$0}". This bug is (mostly) fixed in Perl 5.004.
-
-However, the developers of Perl 5.004 could not fix this bug completely,
-because at least two widely-used modules depend on the old meaning of
-"$$0" in a string. So Perl 5.004 still interprets "$$<digit>" in the
-old (broken) way inside strings; but it generates this message as a
-warning. And in Perl 5.005, this special treatment will cease.
-
-=back
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the
-articles recently posted to the comp.lang.perl.misc newsgroup.
-There may also be information at http://www.perl.com/perl/ , the Perl
-Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team.
-
-=head1 SEE ALSO
-
-The F<Changes> file for exhaustive details on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=head1 HISTORY
-
-Written by Gurusamy Sarathy <F<gsar@activestate.com>>, with many
-contributions from The Perl Porters.
-
-Send omissions or corrections to <F<perlbug@perl.org>>.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl581delta.pod b/Master/tlpkg/tlperl/lib/pods/perl581delta.pod
deleted file mode 100644
index cd88c73ba62..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl581delta.pod
+++ /dev/null
@@ -1,1102 +0,0 @@
-=head1 NAME
-
-perl581delta - what is new for perl v5.8.1
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.8.0 release and
-the 5.8.1 release.
-
-If you are upgrading from an earlier release such as 5.6.1, first read
-the L<perl58delta>, which describes differences between 5.6.0 and
-5.8.0.
-
-In case you are wondering about 5.6.1, it was bug-fix-wise rather
-identical to the development release 5.7.1. Confused? This timeline
-hopefully helps a bit: it lists the new major releases, their maintenance
-releases, and the development releases.
-
- New Maintenance Development
-
- 5.6.0 2000-Mar-22
- 5.7.0 2000-Sep-02
- 5.6.1 2001-Apr-08
- 5.7.1 2001-Apr-09
- 5.7.2 2001-Jul-13
- 5.7.3 2002-Mar-05
- 5.8.0 2002-Jul-18
- 5.8.1 2003-Sep-25
-
-=head1 Incompatible Changes
-
-=head2 Hash Randomisation
-
-Mainly due to security reasons, the "random ordering" of hashes
-has been made even more random. Previously while the order of hash
-elements from keys(), values(), and each() was essentially random,
-it was still repeatable. Now, however, the order varies between
-different runs of Perl.
-
-B<Perl has never guaranteed any ordering of the hash keys>, and the
-ordering has already changed several times during the lifetime of
-Perl 5. Also, the ordering of hash keys has always been, and
-continues to be, affected by the insertion order.
-
-The added randomness may affect applications.
-
-One possible scenario is when output of an application has included
-hash data. For example, if you have used the Data::Dumper module to
-dump data into different files, and then compared the files to see
-whether the data has changed, now you will have false positives since
-the order in which hashes are dumped will vary. In general the cure
-is to sort the keys (or the values); in particular for Data::Dumper to
-use the C<Sortkeys> option. If some particular order is really
-important, use tied hashes: for example the Tie::IxHash module
-which by default preserves the order in which the hash elements
-were added.
-
-More subtle problem is reliance on the order of "global destruction".
-That is what happens at the end of execution: Perl destroys all data
-structures, including user data. If your destructors (the DESTROY
-subroutines) have assumed any particular ordering to the global
-destruction, there might be problems ahead. For example, in a
-destructor of one object you cannot assume that objects of any other
-class are still available, unless you hold a reference to them.
-If the environment variable PERL_DESTRUCT_LEVEL is set to a non-zero
-value, or if Perl is exiting a spawned thread, it will also destruct
-the ordinary references and the symbol tables that are no longer in use.
-You can't call a class method or an ordinary function on a class that
-has been collected that way.
-
-The hash randomisation is certain to reveal hidden assumptions about
-some particular ordering of hash elements, and outright bugs: it
-revealed a few bugs in the Perl core and core modules.
-
-To disable the hash randomisation in runtime, set the environment
-variable PERL_HASH_SEED to 0 (zero) before running Perl (for more
-information see L<perlrun/PERL_HASH_SEED>), or to disable the feature
-completely in compile time, compile with C<-DNO_HASH_SEED> (see F<INSTALL>).
-
-See L<perlsec/"Algorithmic Complexity Attacks"> for the original
-rationale behind this change.
-
-=head2 UTF-8 On Filehandles No Longer Activated By Locale
-
-In Perl 5.8.0 all filehandles, including the standard filehandles,
-were implicitly set to be in Unicode UTF-8 if the locale settings
-indicated the use of UTF-8. This feature caused too many problems,
-so the feature was turned off and redesigned: see L</"Core Enhancements">.
-
-=head2 Single-number v-strings are no longer v-strings before "=>"
-
-The version strings or v-strings (see L<perldata/"Version Strings">)
-feature introduced in Perl 5.6.0 has been a source of some confusion--
-especially when the user did not want to use it, but Perl thought it
-knew better. Especially troublesome has been the feature that before
-a "=>" a version string (a "v" followed by digits) has been interpreted
-as a v-string instead of a string literal. In other words:
-
- %h = ( v65 => 42 );
-
-has meant since Perl 5.6.0
-
- %h = ( 'A' => 42 );
-
-(at least in platforms of ASCII progeny) Perl 5.8.1 restores the
-more natural interpretation
-
- %h = ( 'v65' => 42 );
-
-The multi-number v-strings like v65.66 and 65.66.67 still continue to
-be v-strings in Perl 5.8.
-
-=head2 (Win32) The -C Switch Has Been Repurposed
-
-The -C switch has changed in an incompatible way. The old semantics
-of this switch only made sense in Win32 and only in the "use utf8"
-universe in 5.6.x releases, and do not make sense for the Unicode
-implementation in 5.8.0. Since this switch could not have been used
-by anyone, it has been repurposed. The behavior that this switch
-enabled in 5.6.x releases may be supported in a transparent,
-data-dependent fashion in a future release.
-
-For the new life of this switch, see L<"UTF-8 no longer default under
-UTF-8 locales">, and L<perlrun/-C>.
-
-=head2 (Win32) The /d Switch Of cmd.exe
-
-Perl 5.8.1 uses the /d switch when running the cmd.exe shell
-internally for system(), backticks, and when opening pipes to external
-programs. The extra switch disables the execution of AutoRun commands
-from the registry, which is generally considered undesirable when
-running external programs. If you wish to retain compatibility with
-the older behavior, set PERL5SHELL in your environment to C<cmd /x/c>.
-
-=head1 Core Enhancements
-
-=head2 UTF-8 no longer default under UTF-8 locales
-
-In Perl 5.8.0 many Unicode features were introduced. One of them
-was found to be of more nuisance than benefit: the automagic
-(and silent) "UTF-8-ification" of filehandles, including the
-standard filehandles, if the user's locale settings indicated
-use of UTF-8.
-
-For example, if you had C<en_US.UTF-8> as your locale, your STDIN and
-STDOUT were automatically "UTF-8", in other words an implicit
-binmode(..., ":utf8") was made. This meant that trying to print, say,
-chr(0xff), ended up printing the bytes 0xc3 0xbf. Hardly what
-you had in mind unless you were aware of this feature of Perl 5.8.0.
-The problem is that the vast majority of people weren't: for example
-in RedHat releases 8 and 9 the B<default> locale setting is UTF-8, so
-all RedHat users got UTF-8 filehandles, whether they wanted it or not.
-The pain was intensified by the Unicode implementation of Perl 5.8.0
-(still) having nasty bugs, especially related to the use of s/// and
-tr///. (Bugs that have been fixed in 5.8.1)
-
-Therefore a decision was made to backtrack the feature and change it
-from implicit silent default to explicit conscious option. The new
-Perl command line option C<-C> and its counterpart environment
-variable PERL_UNICODE can now be used to control how Perl and Unicode
-interact at interfaces like I/O and for example the command line
-arguments. See L<perlrun/-C> and L<perlrun/PERL_UNICODE> for more
-information.
-
-=head2 Unsafe signals again available
-
-In Perl 5.8.0 the so-called "safe signals" were introduced. This
-means that Perl no longer handles signals immediately but instead
-"between opcodes", when it is safe to do so. The earlier immediate
-handling easily could corrupt the internal state of Perl, resulting
-in mysterious crashes.
-
-However, the new safer model has its problems too. Because now an
-opcode, a basic unit of Perl execution, is never interrupted but
-instead let to run to completion, certain operations that can take a
-long time now really do take a long time. For example, certain
-network operations have their own blocking and timeout mechanisms, and
-being able to interrupt them immediately would be nice.
-
-Therefore perl 5.8.1 introduces a "backdoor" to restore the pre-5.8.0
-(pre-5.7.3, really) signal behaviour. Just set the environment variable
-PERL_SIGNALS to C<unsafe>, and the old immediate (and unsafe)
-signal handling behaviour returns. See L<perlrun/PERL_SIGNALS>
-and L<perlipc/"Deferred Signals (Safe Signals)">.
-
-In completely unrelated news, you can now use safe signals with
-POSIX::SigAction. See L<POSIX/POSIX::SigAction>.
-
-=head2 Tied Arrays with Negative Array Indices
-
-Formerly, the indices passed to C<FETCH>, C<STORE>, C<EXISTS>, and
-C<DELETE> methods in tied array class were always non-negative. If
-the actual argument was negative, Perl would call FETCHSIZE implicitly
-and add the result to the index before passing the result to the tied
-array method. This behaviour is now optional. If the tied array class
-contains a package variable named C<$NEGATIVE_INDICES> which is set to
-a true value, negative values will be passed to C<FETCH>, C<STORE>,
-C<EXISTS>, and C<DELETE> unchanged.
-
-=head2 local ${$x}
-
-The syntaxes
-
- local ${$x}
- local @{$x}
- local %{$x}
-
-now do localise variables, given that the $x is a valid variable name.
-
-=head2 Unicode Character Database 4.0.0
-
-The copy of the Unicode Character Database included in Perl 5.8 has
-been updated to 4.0.0 from 3.2.0. This means for example that the
-Unicode character properties are as in Unicode 4.0.0.
-
-=head2 Deprecation Warnings
-
-There is one new feature deprecation. Perl 5.8.0 forgot to add
-some deprecation warnings, these warnings have now been added.
-Finally, a reminder of an impending feature removal.
-
-=head3 (Reminder) Pseudo-hashes are deprecated (really)
-
-Pseudo-hashes were deprecated in Perl 5.8.0 and will be removed in
-Perl 5.10.0, see L<perl58delta> for details. Each attempt to access
-pseudo-hashes will trigger the warning C<Pseudo-hashes are deprecated>.
-If you really want to continue using pseudo-hashes but not to see the
-deprecation warnings, use:
-
- no warnings 'deprecated';
-
-Or you can continue to use the L<fields> pragma, but please don't
-expect the data structures to be pseudohashes any more.
-
-=head3 (Reminder) 5.005-style threads are deprecated (really)
-
-5.005-style threads (activated by C<use Thread;>) were deprecated in
-Perl 5.8.0 and will be removed after Perl 5.8, see L<perl58delta> for
-details. Each 5.005-style thread creation will trigger the warning
-C<5.005 threads are deprecated>. If you really want to continue
-using the 5.005 threads but not to see the deprecation warnings, use:
-
- no warnings 'deprecated';
-
-=head3 (Reminder) The $* variable is deprecated (really)
-
-The C<$*> variable controlling multi-line matching has been deprecated
-and will be removed after 5.8. The variable has been deprecated for a
-long time, and a deprecation warning C<Use of $* is deprecated> is given,
-now the variable will just finally be removed. The functionality has
-been supplanted by the C</s> and C</m> modifiers on pattern matching.
-If you really want to continue using the C<$*>-variable but not to see
-the deprecation warnings, use:
-
- no warnings 'deprecated';
-
-=head2 Miscellaneous Enhancements
-
-C<map> in void context is no longer expensive. C<map> is now context
-aware, and will not construct a list if called in void context.
-
-If a socket gets closed by the server while printing to it, the client
-now gets a SIGPIPE. While this new feature was not planned, it fell
-naturally out of PerlIO changes, and is to be considered an accidental
-feature.
-
-PerlIO::get_layers(FH) returns the names of the PerlIO layers
-active on a filehandle.
-
-PerlIO::via layers can now have an optional UTF8 method to
-indicate whether the layer wants to "auto-:utf8" the stream.
-
-utf8::is_utf8() has been added as a quick way to test whether
-a scalar is encoded internally in UTF-8 (Unicode).
-
-=head1 Modules and Pragmata
-
-=head2 Updated Modules And Pragmata
-
-The following modules and pragmata have been updated since Perl 5.8.0:
-
-=over 4
-
-=item base
-
-=item B::Bytecode
-
-In much better shape than it used to be. Still far from perfect, but
-maybe worth a try.
-
-=item B::Concise
-
-=item B::Deparse
-
-=item Benchmark
-
-An optional feature, C<:hireswallclock>, now allows for high
-resolution wall clock times (uses Time::HiRes).
-
-=item ByteLoader
-
-See B::Bytecode.
-
-=item bytes
-
-Now has bytes::substr.
-
-=item CGI
-
-=item charnames
-
-One can now have custom character name aliases.
-
-=item CPAN
-
-There is now a simple command line frontend to the CPAN.pm
-module called F<cpan>.
-
-=item Data::Dumper
-
-A new option, Pair, allows choosing the separator between hash keys
-and values.
-
-=item DB_File
-
-=item Devel::PPPort
-
-=item Digest::MD5
-
-=item Encode
-
-Significant updates on the encoding pragma functionality
-(tr/// and the DATA filehandle, formats).
-
-If a filehandle has been marked as to have an encoding, unmappable
-characters are detected already during input, not later (when the
-corrupted data is being used).
-
-The ISO 8859-6 conversion table has been corrected (the 0x30..0x39
-erroneously mapped to U+0660..U+0669, instead of U+0030..U+0039). The
-GSM 03.38 conversion did not handle escape sequences correctly. The
-UTF-7 encoding has been added (making Encode feature-complete with
-Unicode::String).
-
-=item fields
-
-=item libnet
-
-=item Math::BigInt
-
-A lot of bugs have been fixed since v1.60, the version included in Perl
-v5.8.0. Especially noteworthy are the bug in Calc that caused div and mod to
-fail for some large values, and the fixes to the handling of bad inputs.
-
-Some new features were added, e.g. the broot() method, you can now pass
-parameters to config() to change some settings at runtime, and it is now
-possible to trap the creation of NaN and infinity.
-
-As usual, some optimizations took place and made the math overall a tad
-faster. In some cases, quite a lot faster, actually. Especially alternative
-libraries like Math::BigInt::GMP benefit from this. In addition, a lot of the
-quite clunky routines like fsqrt() and flog() are now much much faster.
-
-=item MIME::Base64
-
-=item NEXT
-
-Diamond inheritance now works.
-
-=item Net::Ping
-
-=item PerlIO::scalar
-
-Reading from non-string scalars (like the special variables, see
-L<perlvar>) now works.
-
-=item podlators
-
-=item Pod::LaTeX
-
-=item PodParsers
-
-=item Pod::Perldoc
-
-Complete rewrite. As a side-effect, no longer refuses to startup when
-run by root.
-
-=item Scalar::Util
-
-New utilities: refaddr, isvstring, looks_like_number, set_prototype.
-
-=item Storable
-
-Can now store code references (via B::Deparse, so not foolproof).
-
-=item strict
-
-Earlier versions of the strict pragma did not check the parameters
-implicitly passed to its "import" (use) and "unimport" (no) routine.
-This caused the false idiom such as:
-
- use strict qw(@ISA);
- @ISA = qw(Foo);
-
-This however (probably) raised the false expectation that the strict
-refs, vars and subs were being enforced (and that @ISA was somehow
-"declared"). But the strict refs, vars, and subs are B<not> enforced
-when using this false idiom.
-
-Starting from Perl 5.8.1, the above B<will> cause an error to be
-raised. This may cause programs which used to execute seemingly
-correctly without warnings and errors to fail when run under 5.8.1.
-This happens because
-
- use strict qw(@ISA);
-
-will now fail with the error:
-
- Unknown 'strict' tag(s) '@ISA'
-
-The remedy to this problem is to replace this code with the correct idiom:
-
- use strict;
- use vars qw(@ISA);
- @ISA = qw(Foo);
-
-=item Term::ANSIcolor
-
-=item Test::Harness
-
-Now much more picky about extra or missing output from test scripts.
-
-=item Test::More
-
-=item Test::Simple
-
-=item Text::Balanced
-
-=item Time::HiRes
-
-Use of nanosleep(), if available, allows mixing subsecond sleeps with
-alarms.
-
-=item threads
-
-Several fixes, for example for join() problems and memory
-leaks. In some platforms (like Linux) that use glibc the minimum memory
-footprint of one ithread has been reduced by several hundred kilobytes.
-
-=item threads::shared
-
-Many memory leaks have been fixed.
-
-=item Unicode::Collate
-
-=item Unicode::Normalize
-
-=item Win32::GetFolderPath
-
-=item Win32::GetOSVersion
-
-Now returns extra information.
-
-=back
-
-=head1 Utility Changes
-
-The C<h2xs> utility now produces a more modern layout:
-F<Foo-Bar/lib/Foo/Bar.pm> instead of F<Foo/Bar/Bar.pm>.
-Also, the boilerplate test is now called F<t/Foo-Bar.t>
-instead of F<t/1.t>.
-
-The Perl debugger (F<lib/perl5db.pl>) has now been extensively
-documented and bugs found while documenting have been fixed.
-
-C<perldoc> has been rewritten from scratch to be more robust and
-feature rich.
-
-C<perlcc -B> works now at least somewhat better, while C<perlcc -c>
-is rather more broken. (The Perl compiler suite as a whole continues
-to be experimental.)
-
-=head1 New Documentation
-
-perl573delta has been added to list the differences between the
-(now quite obsolete) development releases 5.7.2 and 5.7.3.
-
-perl58delta has been added: it is the perldelta of 5.8.0, detailing
-the differences between 5.6.0 and 5.8.0.
-
-perlartistic has been added: it is the Artistic License in pod format,
-making it easier for modules to refer to it.
-
-perlcheat has been added: it is a Perl cheat sheet.
-
-perlgpl has been added: it is the GNU General Public License in pod
-format, making it easier for modules to refer to it.
-
-perlmacosx has been added to tell about the installation and use
-of Perl in Mac OS X.
-
-perlos400 has been added to tell about the installation and use
-of Perl in OS/400 PASE.
-
-perlreref has been added: it is a regular expressions quick reference.
-
-=head1 Installation and Configuration Improvements
-
-The Unix standard Perl location, F</usr/bin/perl>, is no longer
-overwritten by default if it exists. This change was very prudent
-because so many Unix vendors already provide a F</usr/bin/perl>,
-but simultaneously many system utilities may depend on that
-exact version of Perl, so better not to overwrite it.
-
-One can now specify installation directories for site and vendor man
-and HTML pages, and site and vendor scripts. See F<INSTALL>.
-
-One can now specify a destination directory for Perl installation
-by specifying the DESTDIR variable for C<make install>. (This feature
-is slightly different from the previous C<Configure -Dinstallprefix=...>.)
-See F<INSTALL>.
-
-gcc versions 3.x introduced a new warning that caused a lot of noise
-during Perl compilation: C<gcc -Ialreadyknowndirectory (warning:
-changing search order)>. This warning has now been avoided by
-Configure weeding out such directories before the compilation.
-
-One can now build subsets of Perl core modules by using the
-Configure flags C<-Dnoextensions=...> and C<-Donlyextensions=...>,
-see F<INSTALL>.
-
-=head2 Platform-specific enhancements
-
-In Cygwin Perl can now be built with threads (C<Configure -Duseithreads>).
-This works with both Cygwin 1.3.22 and Cygwin 1.5.3.
-
-In newer FreeBSD releases Perl 5.8.0 compilation failed because of
-trying to use F<malloc.h>, which in FreeBSD is just a dummy file, and
-a fatal error to even try to use. Now F<malloc.h> is not used.
-
-Perl is now known to build also in Hitachi HI-UXMPP.
-
-Perl is now known to build again in LynxOS.
-
-Mac OS X now installs with Perl version number embedded in
-installation directory names for easier upgrading of user-compiled
-Perl, and the installation directories in general are more standard.
-In other words, the default installation no longer breaks the
-Apple-provided Perl. On the other hand, with C<Configure -Dprefix=/usr>
-you can now really replace the Apple-supplied Perl (B<please be careful>).
-
-Mac OS X now builds Perl statically by default. This change was done
-mainly for faster startup times. The Apple-provided Perl is still
-dynamically linked and shared, and you can enable the sharedness for
-your own Perl builds by C<Configure -Duseshrplib>.
-
-Perl has been ported to IBM's OS/400 PASE environment. The best way
-to build a Perl for PASE is to use an AIX host as a cross-compilation
-environment. See README.os400.
-
-Yet another cross-compilation option has been added: now Perl builds
-on OpenZaurus, an Linux distribution based on Mandrake + Embedix for
-the Sharp Zaurus PDA. See the Cross/README file.
-
-Tru64 when using gcc 3 drops the optimisation for F<toke.c> to C<-O2>
-because of gigantic memory use with the default C<-O3>.
-
-Tru64 can now build Perl with the newer Berkeley DBs.
-
-Building Perl on WinCE has been much enhanced, see F<README.ce>
-and F<README.perlce>.
-
-=head1 Selected Bug Fixes
-
-=head2 Closures, eval and lexicals
-
-There have been many fixes in the area of anonymous subs, lexicals and
-closures. Although this means that Perl is now more "correct", it is
-possible that some existing code will break that happens to rely on
-the faulty behaviour. In practice this is unlikely unless your code
-contains a very complex nesting of anonymous subs, evals and lexicals.
-
-=head2 Generic fixes
-
-If an input filehandle is marked C<:utf8> and Perl sees illegal UTF-8
-coming in when doing C<< <FH> >>, if warnings are enabled a warning is
-immediately given - instead of being silent about it and Perl being
-unhappy about the broken data later. (The C<:encoding(utf8)> layer
-also works the same way.)
-
-binmode(SOCKET, ":utf8") only worked on the input side, not on the
-output side of the socket. Now it works both ways.
-
-For threaded Perls certain system database functions like getpwent()
-and getgrent() now grow their result buffer dynamically, instead of
-failing. This means that at sites with lots of users and groups the
-functions no longer fail by returning only partial results.
-
-Perl 5.8.0 had accidentally broken the capability for users
-to define their own uppercase<->lowercase Unicode mappings
-(as advertised by the Camel). This feature has been fixed and
-is also documented better.
-
-In 5.8.0 this
-
- $some_unicode .= <FH>;
-
-didn't work correctly but instead corrupted the data. This has now
-been fixed.
-
-Tied methods like FETCH etc. may now safely access tied values, i.e.
-resulting in a recursive call to FETCH etc. Remember to break the
-recursion, though.
-
-At startup Perl blocks the SIGFPE signal away since there isn't much
-Perl can do about it. Previously this blocking was in effect also for
-programs executed from within Perl. Now Perl restores the original
-SIGFPE handling routine, whatever it was, before running external
-programs.
-
-Linenumbers in Perl scripts may now be greater than 65536, or 2**16.
-(Perl scripts have always been able to be larger than that, it's just
-that the linenumber for reported errors and warnings have "wrapped
-around".) While scripts that large usually indicate a need to rethink
-your code a bit, such Perl scripts do exist, for example as results
-from generated code. Now linenumbers can go all the way to
-4294967296, or 2**32.
-
-=head2 Platform-specific fixes
-
-Linux
-
-=over 4
-
-=item *
-
-Setting $0 works again (with certain limitations that
-Perl cannot do much about: see L<perlvar/$0>)
-
-=back
-
-HP-UX
-
-=over 4
-
-=item *
-
-Setting $0 now works.
-
-=back
-
-VMS
-
-=over 4
-
-=item *
-
-Configuration now tests for the presence of C<poll()>, and IO::Poll
-now uses the vendor-supplied function if detected.
-
-=item *
-
-A rare access violation at Perl start-up could occur if the Perl image was
-installed with privileges or if there was an identifier with the
-subsystem attribute set in the process's rightslist. Either of these
-circumstances triggered tainting code that contained a pointer bug.
-The faulty pointer arithmetic has been fixed.
-
-=item *
-
-The length limit on values (not keys) in the %ENV hash has been raised
-from 255 bytes to 32640 bytes (except when the PERL_ENV_TABLES setting
-overrides the default use of logical names for %ENV). If it is
-necessary to access these long values from outside Perl, be aware that
-they are implemented using search list logical names that store the
-value in pieces, each 255-byte piece (up to 128 of them) being an
-element in the search list. When doing a lookup in %ENV from within
-Perl, the elements are combined into a single value. The existing
-VMS-specific ability to access individual elements of a search list
-logical name via the $ENV{'foo;N'} syntax (where N is the search list
-index) is unimpaired.
-
-=item *
-
-The piping implementation now uses local rather than global DCL
-symbols for inter-process communication.
-
-=item *
-
-File::Find could become confused when navigating to a relative
-directory whose name collided with a logical name. This problem has
-been corrected by adding directory syntax to relative path names, thus
-preventing logical name translation.
-
-=back
-
-Win32
-
-=over 4
-
-=item *
-
-A memory leak in the fork() emulation has been fixed.
-
-=item *
-
-The return value of the ioctl() built-in function was accidentally
-broken in 5.8.0. This has been corrected.
-
-=item *
-
-The internal message loop executed by perl during blocking operations
-sometimes interfered with messages that were external to Perl.
-This often resulted in blocking operations terminating prematurely or
-returning incorrect results, when Perl was executing under environments
-that could generate Windows messages. This has been corrected.
-
-=item *
-
-Pipes and sockets are now automatically in binary mode.
-
-=item *
-
-The four-argument form of select() did not preserve $! (errno) properly
-when there were errors in the underlying call. This is now fixed.
-
-=item *
-
-The "CR CR LF" problem of has been fixed, binmode(FH, ":crlf")
-is now effectively a no-op.
-
-=back
-
-=head1 New or Changed Diagnostics
-
-All the warnings related to pack() and unpack() were made more
-informative and consistent.
-
-=head2 Changed "A thread exited while %d threads were running"
-
-The old version
-
- A thread exited while %d other threads were still running
-
-was misleading because the "other" included also the thread giving
-the warning.
-
-=head2 Removed "Attempt to clear a restricted hash"
-
-It is not illegal to clear a restricted hash, so the warning
-was removed.
-
-=head2 New "Illegal declaration of anonymous subroutine"
-
-You must specify the block of code for C<sub>.
-
-=head2 Changed "Invalid range "%s" in transliteration operator"
-
-The old version
-
- Invalid [] range "%s" in transliteration operator
-
-was simply wrong because there are no "[] ranges" in tr///.
-
-=head2 New "Missing control char name in \c"
-
-Self-explanatory.
-
-=head2 New "Newline in left-justified string for %s"
-
-The padding spaces would appear after the newline, which is
-probably not what you had in mind.
-
-=head2 New "Possible precedence problem on bitwise %c operator"
-
-If you think this
-
- $x & $y == 0
-
-tests whether the bitwise AND of $x and $y is zero,
-you will like this warning.
-
-=head2 New "Pseudo-hashes are deprecated"
-
-This warning should have been already in 5.8.0, since they are.
-
-=head2 New "read() on %s filehandle %s"
-
-You cannot read() (or sysread()) from a closed or unopened filehandle.
-
-=head2 New "5.005 threads are deprecated"
-
-This warning should have been already in 5.8.0, since they are.
-
-=head2 New "Tied variable freed while still in use"
-
-Something pulled the plug on a live tied variable, Perl plays
-safe by bailing out.
-
-=head2 New "To%s: illegal mapping '%s'"
-
-An illegal user-defined Unicode casemapping was specified.
-
-=head2 New "Use of freed value in iteration"
-
-Something modified the values being iterated over. This is not good.
-
-=head1 Changed Internals
-
-These news matter to you only if you either write XS code or like to
-know about or hack Perl internals (using Devel::Peek or any of the
-C<B::> modules counts), or like to run Perl with the C<-D> option.
-
-The embedding examples of L<perlembed> have been reviewed to be
-up to date and consistent: for example, the correct use of
-PERL_SYS_INIT3() and PERL_SYS_TERM().
-
-Extensive reworking of the pad code (the code responsible
-for lexical variables) has been conducted by Dave Mitchell.
-
-Extensive work on the v-strings by John Peacock.
-
-UTF-8 length and position cache: to speed up the handling of Unicode
-(UTF-8) scalars, a cache was introduced. Potential problems exist if
-an extension bypasses the official APIs and directly modifies the PV
-of an SV: the UTF-8 cache does not get cleared as it should.
-
-APIs obsoleted in Perl 5.8.0, like sv_2pv, sv_catpvn, sv_catsv,
-sv_setsv, are again available.
-
-Certain Perl core C APIs like cxinc and regatom are no longer
-available at all to code outside the Perl core of the Perl core
-extensions. This is intentional. They never should have been
-available with the shorter names, and if you application depends on
-them, you should (be ashamed and) contact perl5-porters to discuss
-what are the proper APIs.
-
-Certain Perl core C APIs like C<Perl_list> are no longer available
-without their C<Perl_> prefix. If your XS module stops working
-because some functions cannot be found, in many cases a simple fix is
-to add the C<Perl_> prefix to the function and the thread context
-C<aTHX_> as the first argument of the function call. This is also how
-it should always have been done: letting the Perl_-less forms to leak
-from the core was an accident. For cleaner embedding you can also
-force this for all APIs by defining at compile time the cpp define
-PERL_NO_SHORT_NAMES.
-
-Perl_save_bool() has been added.
-
-Regexp objects (those created with C<qr>) now have S-magic rather than
-R-magic. This fixed regexps of the form /...(??{...;$x})/ to no
-longer ignore changes made to $x. The S-magic avoids dropping
-the caching optimization and making (??{...}) constructs obscenely
-slow (and consequently useless). See also L<perlguts/"Magic Variables">.
-Regexp::Copy was affected by this change.
-
-The Perl internal debugging macros DEBUG() and DEB() have been renamed
-to PERL_DEBUG() and PERL_DEB() to avoid namespace conflicts.
-
-C<-DL> removed (the leaktest had been broken and unsupported for years,
-use alternative debugging mallocs or tools like valgrind and Purify).
-
-Verbose modifier C<v> added for C<-DXv> and C<-Dsv>, see L<perlrun>.
-
-=head1 New Tests
-
-In Perl 5.8.0 there were about 69000 separate tests in about 700 test files,
-in Perl 5.8.1 there are about 77000 separate tests in about 780 test files.
-The exact numbers depend on the Perl configuration and on the operating
-system platform.
-
-=head1 Known Problems
-
-The hash randomisation mentioned in L</Incompatible Changes> is definitely
-problematic: it will wake dormant bugs and shake out bad assumptions.
-
-If you want to use mod_perl 2.x with Perl 5.8.1, you will need
-mod_perl-1.99_10 or higher. Earlier versions of mod_perl 2.x
-do not work with the randomised hashes. (mod_perl 1.x works fine.)
-You will also need Apache::Test 1.04 or higher.
-
-Many of the rarer platforms that worked 100% or pretty close to it
-with perl 5.8.0 have been left a little bit untended since their
-maintainers have been otherwise busy lately, and therefore there will
-be more failures on those platforms. Such platforms include Mac OS
-Classic, IBM z/OS (and other EBCDIC platforms), and NetWare. The most
-common Perl platforms (Unix and Unix-like, Microsoft platforms, and
-VMS) have large enough testing and expert population that they are
-doing well.
-
-=head2 Tied hashes in scalar context
-
-Tied hashes do not currently return anything useful in scalar context,
-for example when used as boolean tests:
-
- if (%tied_hash) { ... }
-
-The current nonsensical behaviour is always to return false,
-regardless of whether the hash is empty or has elements.
-
-The root cause is that there is no interface for the implementors of
-tied hashes to implement the behaviour of a hash in scalar context.
-
-=head2 Net::Ping 450_service and 510_ping_udp failures
-
-The subtests 9 and 18 of lib/Net/Ping/t/450_service.t, and the
-subtest 2 of lib/Net/Ping/t/510_ping_udp.t might fail if you have
-an unusual networking setup. For example in the latter case the
-test is trying to send a UDP ping to the IP address 127.0.0.1.
-
-=head2 B::C
-
-The C-generating compiler backend B::C (the frontend being
-C<perlcc -c>) is even more broken than it used to be because of
-the extensive lexical variable changes. (The good news is that
-B::Bytecode and ByteLoader are better than they used to be.)
-
-=head1 Platform Specific Problems
-
-=head2 EBCDIC Platforms
-
-IBM z/OS and other EBCDIC platforms continue to be problematic
-regarding Unicode support. Many Unicode tests are skipped when
-they really should be fixed.
-
-=head2 Cygwin 1.5 problems
-
-In Cygwin 1.5 the F<io/tell> and F<op/sysio> tests have failures for
-some yet unknown reason. In 1.5.5 the threads tests stress_cv,
-stress_re, and stress_string are failing unless the environment
-variable PERLIO is set to "perlio" (which makes also the io/tell
-failure go away).
-
-Perl 5.8.1 does build and work well with Cygwin 1.3: with (uname -a)
-C<CYGWIN_NT-5.0 ... 1.3.22(0.78/3/2) 2003-03-18 09:20 i686 ...>
-a 100% "make test" was achieved with C<Configure -des -Duseithreads>.
-
-=head2 HP-UX: HP cc warnings about sendfile and sendpath
-
-With certain HP C compiler releases (e.g. B.11.11.02) you will
-get many warnings like this (lines wrapped for easier reading):
-
- cc: "/usr/include/sys/socket.h", line 504: warning 562:
- Redeclaration of "sendfile" with a different storage class specifier:
- "sendfile" will have internal linkage.
- cc: "/usr/include/sys/socket.h", line 505: warning 562:
- Redeclaration of "sendpath" with a different storage class specifier:
- "sendpath" will have internal linkage.
-
-The warnings show up both during the build of Perl and during certain
-lib/ExtUtils tests that invoke the C compiler. The warning, however,
-is not serious and can be ignored.
-
-=head2 IRIX: t/uni/tr_7jis.t falsely failing
-
-The test t/uni/tr_7jis.t is known to report failure under 'make test'
-or the test harness with certain releases of IRIX (at least IRIX 6.5
-and MIPSpro Compilers Version 7.3.1.1m), but if run manually the test
-fully passes.
-
-=head2 Mac OS X: no usemymalloc
-
-The Perl malloc (C<-Dusemymalloc>) does not work at all in Mac OS X.
-This is not that serious, though, since the native malloc works just
-fine.
-
-=head2 Tru64: No threaded builds with GNU cc (gcc)
-
-In the latest Tru64 releases (e.g. v5.1B or later) gcc cannot be used
-to compile a threaded Perl (-Duseithreads) because the system
-C<< <pthread.h> >> file doesn't know about gcc.
-
-=head2 Win32: sysopen, sysread, syswrite
-
-As of the 5.8.0 release, sysopen()/sysread()/syswrite() do not behave
-like they used to in 5.6.1 and earlier with respect to "text" mode.
-These built-ins now always operate in "binary" mode (even if sysopen()
-was passed the O_TEXT flag, or if binmode() was used on the file
-handle). Note that this issue should only make a difference for disk
-files, as sockets and pipes have always been in "binary" mode in the
-Windows port. As this behavior is currently considered a bug,
-compatible behavior may be re-introduced in a future release. Until
-then, the use of sysopen(), sysread() and syswrite() is not supported
-for "text" mode operations.
-
-=head1 Future Directions
-
-The following things B<might> happen in future. The first publicly
-available releases having these characteristics will be the developer
-releases Perl 5.9.x, culminating in the Perl 5.10.0 release. These
-are our best guesses at the moment: we reserve the right to rethink.
-
-=over 4
-
-=item *
-
-PerlIO will become The Default. Currently (in Perl 5.8.x) the stdio
-library is still used if Perl thinks it can use certain tricks to
-make stdio go B<really> fast. For future releases our goal is to
-make PerlIO go even faster.
-
-=item *
-
-A new feature called I<assertions> will be available. This means that
-one can have code called assertions sprinkled in the code: usually
-they are optimised away, but they can be enabled with the C<-A> option.
-
-=item *
-
-A new operator C<//> (defined-or) will be available. This means that
-one will be able to say
-
- $a // $b
-
-instead of
-
- defined $a ? $a : $b
-
-and
-
- $c //= $d;
-
-instead of
-
- $c = $d unless defined $c;
-
-The operator will have the same precedence and associativity as C<||>.
-A source code patch against the Perl 5.8.1 sources will be available
-in CPAN as F<authors/id/H/HM/HMBRAND/dor-5.8.1.diff>.
-
-=item *
-
-C<unpack()> will default to unpacking the C<$_>.
-
-=item *
-
-Various Copy-On-Write techniques will be investigated in hopes
-of speeding up Perl.
-
-=item *
-
-CPANPLUS, Inline, and Module::Build will become core modules.
-
-=item *
-
-The ability to write true lexically scoped pragmas will be introduced.
-
-=item *
-
-Work will continue on the bytecompiler and byteloader.
-
-=item *
-
-v-strings as they currently exist are scheduled to be deprecated. The
-v-less form (1.2.3) will become a "version object" when used with C<use>,
-C<require>, and C<$VERSION>. $^V will also be a "version object" so the
-printf("%vd",...) construct will no longer be needed. The v-ful version
-(v1.2.3) will become obsolete. The equivalence of strings and v-strings (e.g.
-that currently 5.8.0 is equal to "\5\8\0") will go away. B<There may be no
-deprecation warning for v-strings>, though: it is quite hard to detect when
-v-strings are being used safely, and when they are not.
-
-=item *
-
-5.005 Threads Will Be Removed
-
-=item *
-
-The C<$*> Variable Will Be Removed
-(it was deprecated a long time ago)
-
-=item *
-
-Pseudohashes Will Be Removed
-
-=back
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://bugs.perl.org/ . There may also be
-information at http://www.perl.com/ , the Perl Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team. You can browse and search
-the Perl 5 bugs at http://bugs.perl.org/
-
-=head1 SEE ALSO
-
-The F<Changes> file for exhaustive details on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl582delta.pod b/Master/tlpkg/tlperl/lib/pods/perl582delta.pod
deleted file mode 100644
index 87080702ac8..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl582delta.pod
+++ /dev/null
@@ -1,162 +0,0 @@
-=head1 NAME
-
-perl582delta - what is new for perl v5.8.2
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.8.1 release and
-the 5.8.2 release.
-
-If you are upgrading from an earlier release such as 5.6.1, first read
-the L<perl58delta>, which describes differences between 5.6.0 and
-5.8.0, and the L<perl581delta>, which describes differences between
-5.8.0 and 5.8.1.
-
-=head1 Incompatible Changes
-
-For threaded builds for modules calling certain re-entrant system calls,
-binary compatibility was accidentally lost between 5.8.0 and 5.8.1.
-Binary compatibility with 5.8.0 has been restored in 5.8.2, which
-necessitates breaking compatibility with 5.8.1. We see this as the
-lesser of two evils.
-
-This will only affect people who have a threaded perl 5.8.1, and compiled
-modules which use these calls, and now attempt to run the compiled modules
-with 5.8.2. The fix is to re-compile and re-install the modules using 5.8.2.
-
-=head1 Core Enhancements
-
-=head2 Hash Randomisation
-
-The hash randomisation introduced with 5.8.1 has been amended. It
-transpired that although the implementation introduced in 5.8.1 was source
-compatible with 5.8.0, it was not binary compatible in certain cases. 5.8.2
-contains an improved implementation which is both source and binary
-compatible with both 5.8.0 and 5.8.1, and remains robust against the form of
-attack which prompted the change for 5.8.1.
-
-We are grateful to the Debian project for their input in this area.
-See L<perlsec/"Algorithmic Complexity Attacks"> for the original
-rationale behind this change.
-
-=head2 Threading
-
-Several memory leaks associated with variables shared between threads
-have been fixed.
-
-=head1 Modules and Pragmata
-
-=head2 Updated Modules And Pragmata
-
-The following modules and pragmata have been updated since Perl 5.8.1:
-
-=over 4
-
-=item Devel::PPPort
-
-=item Digest::MD5
-
-=item I18N::LangTags
-
-=item libnet
-
-=item MIME::Base64
-
-=item Pod::Perldoc
-
-=item strict
-
-Documentation improved
-
-=item Tie::Hash
-
-Documentation improved
-
-=item Time::HiRes
-
-=item Unicode::Collate
-
-=item Unicode::Normalize
-
-=item UNIVERSAL
-
-Documentation improved
-
-=back
-
-=head1 Selected Bug Fixes
-
-Some syntax errors involving unrecognized filetest operators are now handled
-correctly by the parser.
-
-=head1 Changed Internals
-
-Interpreter initialization is more complete when -DMULTIPLICITY is off.
-This should resolve problems with initializing and destroying the Perl
-interpreter more than once in a single process.
-
-=head1 Platform Specific Problems
-
-Dynamic linker flags have been tweaked for Solaris and OS X, which should
-solve problems seen while building some XS modules.
-
-Bugs in OS/2 sockets and tmpfile have been fixed.
-
-In OS X C<setreuid> and friends are troublesome - perl will now work
-around their problems as best possible.
-
-=head1 Future Directions
-
-Starting with 5.8.3 we intend to make more frequent maintenance releases,
-with a smaller number of changes in each. The intent is to propagate
-bug fixes out to stable releases more rapidly and make upgrading stable
-releases less of an upheaval. This should give end users more
-flexibility in their choice of upgrade timing, and allow them easier
-assessment of the impact of upgrades. The current plan is for code freezes
-as follows
-
-=over 4
-
-=item *
-
-5.8.3 23:59:59 GMT, Wednesday December 31st 2003
-
-=item *
-
-5.8.4 23:59:59 GMT, Wednesday March 31st 2004
-
-=item *
-
-5.8.5 23:59:59 GMT, Wednesday June 30th 2004
-
-=back
-
-with the release following soon after, when testing is complete.
-
-See L<perl581delta/"Future Directions"> for more soothsaying.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://bugs.perl.org/. There may also be
-information at http://www.perl.com/, the Perl Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team. You can browse and search
-the Perl 5 bugs at http://bugs.perl.org/
-
-=head1 SEE ALSO
-
-The F<Changes> file for exhaustive details on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl583delta.pod b/Master/tlpkg/tlperl/lib/pods/perl583delta.pod
deleted file mode 100644
index 2981a9834a8..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl583delta.pod
+++ /dev/null
@@ -1,210 +0,0 @@
-=head1 NAME
-
-perl583delta - what is new for perl v5.8.3
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.8.2 release and
-the 5.8.3 release.
-
-If you are upgrading from an earlier release such as 5.6.1, first read
-the L<perl58delta>, which describes differences between 5.6.0 and
-5.8.0, and the L<perl581delta> and L<perl582delta>, which describe differences
-between 5.8.0, 5.8.1 and 5.8.2
-
-=head1 Incompatible Changes
-
-There are no changes incompatible with 5.8.2.
-
-=head1 Core Enhancements
-
-A C<SCALAR> method is now available for tied hashes. This is called when
-a tied hash is used in scalar context, such as
-
- if (%tied_hash) {
- ...
- }
-
-
-The old behaviour was that %tied_hash would return whatever would have been
-returned for that hash before the hash was tied (so usually 0). The new
-behaviour in the absence of a SCALAR method is to return TRUE if in the
-middle of an C<each> iteration, and otherwise call FIRSTKEY to check if the
-hash is empty (making sure that a subsequent C<each> will also begin by
-calling FIRSTKEY). Please see L<perltie/SCALAR> for the full details and
-caveats.
-
-=head1 Modules and Pragmata
-
-=over 4
-
-=item CGI
-
-=item Cwd
-
-=item Digest
-
-=item Digest::MD5
-
-=item Encode
-
-=item File::Spec
-
-=item FindBin
-
-A function C<again> is provided to resolve problems where modules in different
-directories wish to use FindBin.
-
-=item List::Util
-
-You can now weaken references to read only values.
-
-=item Math::BigInt
-
-=item PodParser
-
-=item Pod::Perldoc
-
-=item POSIX
-
-=item Unicode::Collate
-
-=item Unicode::Normalize
-
-=item Test::Harness
-
-=item threads::shared
-
-C<cond_wait> has a new two argument form. C<cond_timedwait> has been added.
-
-=back
-
-=head1 Utility Changes
-
-C<find2perl> now assumes C<-print> as a default action. Previously, it
-needed to be specified explicitly.
-
-A new utility, C<prove>, makes it easy to run an individual regression test
-at the command line. C<prove> is part of Test::Harness, which users of earlier
-Perl versions can install from CPAN.
-
-=head1 New Documentation
-
-The documentation has been revised in places to produce more standard manpages.
-
-The documentation for the special code blocks (BEGIN, CHECK, INIT, END)
-has been improved.
-
-=head1 Installation and Configuration Improvements
-
-Perl now builds on OpenVMS I64
-
-=head1 Selected Bug Fixes
-
-Using substr() on a UTF8 string could cause subsequent accesses on that
-string to return garbage. This was due to incorrect UTF8 offsets being
-cached, and is now fixed.
-
-join() could return garbage when the same join() statement was used to
-process 8 bit data having earlier processed UTF8 data, due to the flags
-on that statement's temporary workspace not being reset correctly. This
-is now fixed.
-
-C<$a .. $b> will now work as expected when either $a or $b is C<undef>
-
-Using Unicode keys with tied hashes should now work correctly.
-
-Reading $^E now preserves $!. Previously, the C code implementing $^E
-did not preserve C<errno>, so reading $^E could cause C<errno> and therefore
-C<$!> to change unexpectedly.
-
-Reentrant functions will (once more) work with C++. 5.8.2 introduced a bugfix
-which accidentally broke the compilation of Perl extensions written in C++
-
-=head1 New or Changed Diagnostics
-
-The fatal error "DESTROY created new reference to dead object" is now
-documented in L<perldiag>.
-
-=head1 Changed Internals
-
-The hash code has been refactored to reduce source duplication. The
-external interface is unchanged, and aside from the bug fixes described
-above, there should be no change in behaviour.
-
-C<hv_clear_placeholders> is now part of the perl API
-
-Some C macros have been tidied. In particular macros which create temporary
-local variables now name these variables more defensively, which should
-avoid bugs where names clash.
-
-<signal.h> is now always included.
-
-=head1 Configuration and Building
-
-C<Configure> now invokes callbacks regardless of the value of the variable
-they are called for. Previously callbacks were only invoked in the
-C<case $variable $define)> branch. This change should only affect platform
-maintainers writing configuration hints files.
-
-=head1 Platform Specific Problems
-
-The regression test ext/threads/shared/t/wait.t fails on early RedHat 9
-and HP-UX 10.20 due to bugs in their threading implementations.
-RedHat users should see https://rhn.redhat.com/errata/RHBA-2003-136.html
-and consider upgrading their glibc.
-
-=head1 Known Problems
-
-Detached threads aren't supported on Windows yet, as they may lead to
-memory access violation problems.
-
-There is a known race condition opening scripts in C<suidperl>. C<suidperl>
-is neither built nor installed by default, and has been deprecated since
-perl 5.8.0. You are advised to replace use of suidperl with tools such
-as sudo ( http://www.courtesan.com/sudo/ )
-
-We have a backlog of unresolved bugs. Dealing with bugs and bug reports
-is unglamorous work; not something ideally suited to volunteer labour,
-but that is all that we have.
-
-The perl5 development team are implementing changes to help address this
-problem, which should go live in early 2004.
-
-=head1 Future Directions
-
-Code freeze for the next maintenance release (5.8.4) is on March 31st 2004,
-with release expected by mid April. Similarly 5.8.5's freeze will be at
-the end of June, with release by mid July.
-
-=head1 Obituary
-
-Iain 'Spoon' Truskett, Perl hacker, author of L<perlreref> and
-contributor to CPAN, died suddenly on 29th December 2003, aged 24.
-He will be missed.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://bugs.perl.org. There may also be
-information at http://www.perl.org, the Perl Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team. You can browse and search
-the Perl 5 bugs at http://bugs.perl.org/
-
-=head1 SEE ALSO
-
-The F<Changes> file for exhaustive details on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl584delta.pod b/Master/tlpkg/tlperl/lib/pods/perl584delta.pod
deleted file mode 100644
index b2cdcc6b822..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl584delta.pod
+++ /dev/null
@@ -1,263 +0,0 @@
-=head1 NAME
-
-perl584delta - what is new for perl v5.8.4
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.8.3 release and
-the 5.8.4 release.
-
-=head1 Incompatible Changes
-
-Many minor bugs have been fixed. Scripts which happen to rely on previously
-erroneous behaviour will consider these fixes as incompatible changes :-)
-You are advised to perform sufficient acceptance testing on this release
-to satisfy yourself that this does not affect you, before putting this
-release into production.
-
-The diagnostic output of Carp has been changed slightly, to add a space after
-the comma between arguments. This makes it much easier for tools such as
-web browsers to wrap it, but might confuse any automatic tools which perform
-detailed parsing of Carp output.
-
-The internal dump output has been improved, so that non-printable characters
-such as newline and backspace are output in C<\x> notation, rather than
-octal. This might just confuse non-robust tools which parse the output of
-modules such as Devel::Peek.
-
-=head1 Core Enhancements
-
-=head2 Malloc wrapping
-
-Perl can now be built to detect attempts to assign pathologically large chunks
-of memory. Previously such assignments would suffer from integer wrap-around
-during size calculations causing a misallocation, which would crash perl, and
-could theoretically be used for "stack smashing" attacks. The wrapping
-defaults to enabled on platforms where we know it works (most AIX
-configurations, BSDi, Darwin, DEC OSF/1, FreeBSD, HP/UX, GNU Linux, OpenBSD,
-Solaris, VMS and most Win32 compilers) and defaults to disabled on other
-platforms.
-
-=head2 Unicode Character Database 4.0.1
-
-The copy of the Unicode Character Database included in Perl 5.8 has
-been updated to 4.0.1 from 4.0.0.
-
-=head2 suidperl less insecure
-
-Paul Szabo has analysed and patched C<suidperl> to remove existing known
-insecurities. Currently there are no known holes in C<suidperl>, but previous
-experience shows that we cannot be confident that these were the last. You may
-no longer invoke the set uid perl directly, so to preserve backwards
-compatibility with scripts that invoke #!/usr/bin/suidperl the only set uid
-binary is now C<sperl5.8.>I<n> (C<sperl5.8.4> for this release). C<suidperl>
-is installed as a hard link to C<perl>; both C<suidperl> and C<perl> will
-invoke C<sperl5.8.4> automatically the set uid binary, so this change should
-be completely transparent.
-
-For new projects the core perl team would strongly recommend that you use
-dedicated, single purpose security tools such as C<sudo> in preference to
-C<suidperl>.
-
-=head2 format
-
-In addition to bug fixes, C<format>'s features have been enhanced. See
-L<perlform>
-
-=head1 Modules and Pragmata
-
-The (mis)use of C</tmp> in core modules and documentation has been tidied up.
-Some modules available both within the perl core and independently from CPAN
-("dual-life modules") have not yet had these changes applied; the changes
-will be integrated into future stable perl releases as the modules are
-updated on CPAN.
-
-=head2 Updated modules
-
-=over 4
-
-=item Attribute::Handlers
-
-=item B
-
-=item Benchmark
-
-=item CGI
-
-=item Carp
-
-=item Cwd
-
-=item Exporter
-
-=item File::Find
-
-=item IO
-
-=item IPC::Open3
-
-=item Local::Maketext
-
-=item Math::BigFloat
-
-=item Math::BigInt
-
-=item Math::BigRat
-
-=item MIME::Base64
-
-=item ODBM_File
-
-=item POSIX
-
-=item Shell
-
-=item Socket
-
-There is experimental support for Linux abstract Unix domain sockets.
-
-=item Storable
-
-=item Switch
-
-Synced with its CPAN version 2.10
-
-=item Sys::Syslog
-
-C<syslog()> can now use numeric constants for facility names and priorities,
-in addition to strings.
-
-=item Term::ANSIColor
-
-=item Time::HiRes
-
-=item Unicode::UCD
-
-=item Win32
-
-Win32.pm/Win32.xs has moved from the libwin32 module to core Perl
-
-=item base
-
-=item open
-
-=item threads
-
-Detached threads are now also supported on Windows.
-
-=item utf8
-
-=back
-
-=head1 Performance Enhancements
-
-=over 4
-
-=item *
-
-Accelerated Unicode case mappings (C</i>, C<lc>, C<uc>, etc).
-
-=item *
-
-In place sort optimised (eg C<@a = sort @a>)
-
-=item *
-
-Unnecessary assignment optimised away in
-
- my $s = undef;
- my @a = ();
- my %h = ();
-
-=item *
-
-Optimised C<map> in scalar context
-
-=back
-
-=head1 Utility Changes
-
-The Perl debugger (F<lib/perl5db.pl>) can now save all debugger commands for
-sourcing later, and can display the parent inheritance tree of a given class.
-
-=head1 Installation and Configuration Improvements
-
-The build process on both VMS and Windows has had several minor improvements
-made. On Windows Borland's C compiler can now compile perl with PerlIO and/or
-USE_LARGE_FILES enabled.
-
-C<perl.exe> on Windows now has a "Camel" logo icon. The use of a camel with
-the topic of Perl is a trademark of O'Reilly and Associates Inc., and is used
-with their permission (ie distribution of the source, compiling a Windows
-executable from it, and using that executable locally). Use of the supplied
-camel for anything other than a perl executable's icon is specifically not
-covered, and anyone wishing to redistribute perl binaries I<with> the icon
-should check directly with O'Reilly beforehand.
-
-Perl should build cleanly on Stratus VOS once more.
-
-=head1 Selected Bug Fixes
-
-More utf8 bugs fixed, notably in how C<chomp>, C<chop>, C<send>, and
-C<syswrite> and interact with utf8 data. Concatenation now works correctly
-when C<use bytes;> is in scope.
-
-Pragmata are now correctly propagated into (?{...}) constructions in regexps.
-Code such as
-
- my $x = qr{ ... (??{ $x }) ... };
-
-will now (correctly) fail under use strict. (As the inner C<$x> is and
-has always referred to C<$::x>)
-
-The "const in void context" warning has been suppressed for a constant in an
-optimised-away boolean expression such as C<5 || print;>
-
-C<perl -i> could C<fchmod(stdin)> by mistake. This is serious if stdin is
-attached to a terminal, and perl is running as root. Now fixed.
-
-=head1 New or Changed Diagnostics
-
-C<Carp> and the internal diagnostic routines used by C<Devel::Peek> have been
-made clearer, as described in L</Incompatible Changes>
-
-=head1 Changed Internals
-
-Some bugs have been fixed in the hash internals. Restricted hashes and
-their place holders are now allocated and deleted at slightly different times,
-but this should not be visible to user code.
-
-=head1 Future Directions
-
-Code freeze for the next maintenance release (5.8.5) will be on 30th June
-2004, with release by mid July.
-
-=head1 Platform Specific Problems
-
-This release is known not to build on Windows 95.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://bugs.perl.org. There may also be
-information at http://www.perl.org, the Perl Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team. You can browse and search
-the Perl 5 bugs at http://bugs.perl.org/
-
-=head1 SEE ALSO
-
-The F<Changes> file for exhaustive details on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl585delta.pod b/Master/tlpkg/tlperl/lib/pods/perl585delta.pod
deleted file mode 100644
index 1717c74e028..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl585delta.pod
+++ /dev/null
@@ -1,257 +0,0 @@
-=head1 NAME
-
-perl585delta - what is new for perl v5.8.5
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.8.4 release and
-the 5.8.5 release.
-
-=head1 Incompatible Changes
-
-There are no changes incompatible with 5.8.4.
-
-=head1 Core Enhancements
-
-Perl's regular expression engine now contains support for matching on the
-intersection of two Unicode character classes. You can also now refer to
-user-defined character classes from within other user defined character
-classes.
-
-=head1 Modules and Pragmata
-
-=over 4
-
-=item *
-
-Carp improved to work nicely with Safe. Carp's message reporting should now
-be anomaly free - it will always print out line number information.
-
-=item *
-
-CGI upgraded to version 3.05
-
-=item *
-
-charnames now avoids clobbering $_
-
-=item *
-
-Digest upgraded to version 1.08
-
-=item *
-
-Encode upgraded to version 2.01
-
-=item *
-
-FileCache upgraded to version 1.04
-
-=item *
-
-libnet upgraded to version 1.19
-
-=item *
-
-Pod::Parser upgraded to version 1.28
-
-=item *
-
-Pod::Perldoc upgraded to version 3.13
-
-=item *
-
-Pod::LaTeX upgraded to version 0.57
-
-=item *
-
-Safe now works properly with Carp
-
-=item *
-
-Scalar-List-Utils upgraded to version 1.14
-
-=item *
-
-Shell's documentation has been re-written, and its historical partial
-auto-quoting of command arguments can now be disabled.
-
-=item *
-
-Test upgraded to version 1.25
-
-=item *
-
-Test::Harness upgraded to version 2.42
-
-=item *
-
-Time::Local upgraded to version 1.10
-
-=item *
-
-Unicode::Collate upgraded to version 0.40
-
-=item *
-
-Unicode::Normalize upgraded to version 0.30
-
-=back
-
-=head1 Utility Changes
-
-=head2 Perl's debugger
-
-The debugger can now emulate stepping backwards, by restarting and rerunning
-all bar the last command from a saved command history.
-
-=head2 h2ph
-
-F<h2ph> is now able to understand a very limited set of C inline functions
--- basically, the inline functions that look like CPP macros. This has
-been introduced to deal with some of the headers of the newest versions of
-the glibc. The standard warning still applies; to quote F<h2ph>'s
-documentation, I<you may need to dicker with the files produced>.
-
-=head1 Installation and Configuration Improvements
-
-Perl 5.8.5 should build cleanly from source on LynxOS.
-
-=head1 Selected Bug Fixes
-
-=over 4
-
-=item *
-
-The in-place sort optimisation introduced in 5.8.4 had a bug. For example,
-in code such as
-
- @a = sort ($b, @a)
-
-the result would omit the value $b. This is now fixed.
-
-=item *
-
-The optimisation for unnecessary assignments introduced in 5.8.4 could give
-spurious warnings. This has been fixed.
-
-=item *
-
-Perl should now correctly detect and read BOM-marked and (BOMless) UTF-16
-scripts of either endianness.
-
-=item *
-
-Creating a new thread when weak references exist was buggy, and would often
-cause warnings at interpreter destruction time. The known bug is now fixed.
-
-=item *
-
-Several obscure bugs involving manipulating Unicode strings with C<substr> have
-been fixed.
-
-=item *
-
-Previously if Perl's file globbing function encountered a directory that it
-did not have permission to open it would return immediately, leading to
-unexpected truncation of the list of results. This has been fixed, to be
-consistent with Unix shells' globbing behaviour.
-
-=item *
-
-Thread creation time could vary wildly between identical runs. This was caused
-by a poor hashing algorithm in the thread cloning routines, which has now
-been fixed.
-
-=item *
-
-The internals of the ithreads implementation were not checking if OS-level
-thread creation had failed. threads->create() now returns C<undef> in if
-thread creation fails instead of crashing perl.
-
-=back
-
-=head1 New or Changed Diagnostics
-
-=over 4
-
-=item *
-
-Perl -V has several improvements
-
-=over 4
-
-=item *
-
-correctly outputs local patch names that contain embedded code snippets
-or other characters that used to confuse it.
-
-=item *
-
-arguments to -V that look like regexps will give multiple lines of output.
-
-=item *
-
-a trailing colon suppresses the linefeed and ';' terminator, allowing
-embedding of queries into shell commands.
-
-=item *
-
-a leading colon removes the 'name=' part of the response, allowing mapping to
-any name.
-
-=back
-
-=item *
-
-When perl fails to find the specified script, it now outputs a second line
-suggesting that the user use the C<-S> flag:
-
- $ perl5.8.5 missing.pl
- Can't open perl script "missing.pl": No such file or directory.
- Use -S to search $PATH for it.
-
-=back
-
-=head1 Changed Internals
-
-The Unicode character class files used by the regular expression engine are
-now built at build time from the supplied Unicode consortium data files,
-instead of being shipped prebuilt. This makes the compressed Perl source
-tarball about 200K smaller. A side effect is that the layout of files inside
-lib/unicore has changed.
-
-=head1 Known Problems
-
-The regression test F<t/uni/class.t> is now performing considerably more
-tests, and can take several minutes to run even on a fast machine.
-
-=head1 Platform Specific Problems
-
-This release is known not to build on Windows 95.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://bugs.perl.org. There may also be
-information at http://www.perl.org, the Perl Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team. You can browse and search
-the Perl 5 bugs at http://bugs.perl.org/
-
-=head1 SEE ALSO
-
-The F<Changes> file for exhaustive details on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl586delta.pod b/Master/tlpkg/tlperl/lib/pods/perl586delta.pod
deleted file mode 100644
index 6cd0fa85496..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl586delta.pod
+++ /dev/null
@@ -1,170 +0,0 @@
-=head1 NAME
-
-perl586delta - what is new for perl v5.8.6
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.8.5 release and
-the 5.8.6 release.
-
-=head1 Incompatible Changes
-
-There are no changes incompatible with 5.8.5.
-
-=head1 Core Enhancements
-
-The perl interpreter is now more tolerant of UTF-16-encoded scripts.
-
-On Win32, Perl can now use non-IFS compatible LSPs, which allows Perl to
-work in conjunction with firewalls such as McAfee Guardian. For full details
-see the file F<README.win32>, particularly if you're running Win95.
-
-=head1 Modules and Pragmata
-
-=over 4
-
-=item *
-
-With the C<base> pragma, an intermediate class with no fields used to messes
-up private fields in the base class. This has been fixed.
-
-=item *
-
-Cwd upgraded to version 3.01 (as part of the new PathTools distribution)
-
-=item *
-
-Devel::PPPort upgraded to version 3.03
-
-=item *
-
-File::Spec upgraded to version 3.01 (as part of the new PathTools distribution)
-
-=item *
-
-Encode upgraded to version 2.08
-
-=item *
-
-ExtUtils::MakeMaker remains at version 6.17, as later stable releases currently
-available on CPAN have some issues with core modules on some core platforms.
-
-=item *
-
-I18N::LangTags upgraded to version 0.35
-
-=item *
-
-Math::BigInt upgraded to version 1.73
-
-=item *
-
-Math::BigRat upgraded to version 0.13
-
-=item *
-
-MIME::Base64 upgraded to version 3.05
-
-=item *
-
-POSIX::sigprocmask function can now retrieve the current signal mask without
-also setting it.
-
-=item *
-
-Time::HiRes upgraded to version 1.65
-
-=back
-
-=head1 Utility Changes
-
-Perl has a new -dt command-line flag, which enables threads support in the
-debugger.
-
-=head1 Performance Enhancements
-
-C<reverse sort ...> is now optimized to sort in reverse, avoiding the
-generation of a temporary intermediate list.
-
-C<for (reverse @foo)> now iterates in reverse, avoiding the generation of a
-temporary reversed list.
-
-=head1 Selected Bug Fixes
-
-The regexp engine is now more robust when given invalid utf8 input, as is
-sometimes generated by buggy XS modules.
-
-C<foreach> on threads::shared array used to be able to crash Perl. This bug
-has now been fixed.
-
-A regexp in C<STDOUT>'s destructor used to coredump, because the regexp pad
-was already freed. This has been fixed.
-
-C<goto &> is now more robust - bugs in deep recursion and chained C<goto &>
-have been fixed.
-
-Using C<delete> on an array no longer leaks memory. A C<pop> of an item from a
-shared array reference no longer causes a leak.
-
-C<eval_sv()> failing a taint test could corrupt the stack - this has been
-fixed.
-
-On platforms with 64 bit pointers numeric comparison operators used to
-erroneously compare the addresses of references that are overloaded, rather
-than using the overloaded values. This has been fixed.
-
-C<read> into a UTF8-encoded buffer with an offset off the end of the buffer
-no longer mis-calculates buffer lengths.
-
-Although Perl has promised since version 5.8 that C<sort()> would be
-stable, the two cases C<sort {$b cmp $a}> and C<< sort {$b <=> $a} >> could
-produce non-stable sorts. This is corrected in perl5.8.6.
-
-Localising C<$^D> no longer generates a diagnostic message about valid -D
-flags.
-
-=head1 New or Changed Diagnostics
-
-For -t and -T,
- Too late for "-T" option
-has been changed to the more informative
- "-T" is on the #! line, it must also be used on the command line
-
-=head1 Changed Internals
-
-From now on all applications embedding perl will behave as if perl
-were compiled with -DPERL_USE_SAFE_PUTENV. See "Environment access" in
-the F<INSTALL> file for details.
-
-Most C<C> source files now have comments at the top explaining their purpose,
-which should help anyone wishing to get an overview of the implementation.
-
-=head1 New Tests
-
-There are significantly more tests for the C<B> suite of modules.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://bugs.perl.org. There may also be
-information at http://www.perl.org, the Perl Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team. You can browse and search
-the Perl 5 bugs at http://bugs.perl.org/
-
-=head1 SEE ALSO
-
-The F<Changes> file for exhaustive details on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl587delta.pod b/Master/tlpkg/tlperl/lib/pods/perl587delta.pod
deleted file mode 100644
index 34ee8f21724..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl587delta.pod
+++ /dev/null
@@ -1,379 +0,0 @@
-=head1 NAME
-
-perl587delta - what is new for perl v5.8.7
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.8.6 release and
-the 5.8.7 release.
-
-=head1 Incompatible Changes
-
-There are no changes incompatible with 5.8.6.
-
-=head1 Core Enhancements
-
-=head2 Unicode Character Database 4.1.0
-
-The copy of the Unicode Character Database included in Perl 5.8 has
-been updated to 4.1.0 from 4.0.1. See
-L<http://www.unicode.org/versions/Unicode4.1.0/#NotableChanges> for the
-notable changes.
-
-=head2 suidperl less insecure
-
-A pair of exploits in C<suidperl> involving debugging code have been closed.
-
-For new projects the core perl team strongly recommends that you use
-dedicated, single purpose security tools such as C<sudo> in preference to
-C<suidperl>.
-
-=head2 Optional site customization script
-
-The perl interpreter can be built to allow the use of a site customization
-script. By default this is not enabled, to be consistent with previous perl
-releases. To use this, add C<-Dusesitecustomize> to the command line flags
-when running the C<Configure> script. See also L<perlrun/-f>.
-
-=head2 C<Config.pm> is now much smaller.
-
-C<Config.pm> is now about 3K rather than 32K, with the infrequently used
-code and C<%Config> values loaded on demand. This is transparent to the
-programmer, but means that most code will save parsing and loading 29K of
-script (for example, code that uses C<File::Find>).
-
-=head1 Modules and Pragmata
-
-=over 4
-
-=item *
-
-B upgraded to version 1.09
-
-=item *
-
-base upgraded to version 2.07
-
-=item *
-
-bignum upgraded to version 0.17
-
-=item *
-
-bytes upgraded to version 1.02
-
-=item *
-
-Carp upgraded to version 1.04
-
-=item *
-
-CGI upgraded to version 3.10
-
-=item *
-
-Class::ISA upgraded to version 0.33
-
-=item *
-
-Data::Dumper upgraded to version 2.121_02
-
-=item *
-
-DB_File upgraded to version 1.811
-
-=item *
-
-Devel::PPPort upgraded to version 3.06
-
-=item *
-
-Digest upgraded to version 1.10
-
-=item *
-
-Encode upgraded to version 2.10
-
-=item *
-
-FileCache upgraded to version 1.05
-
-=item *
-
-File::Path upgraded to version 1.07
-
-=item *
-
-File::Temp upgraded to version 0.16
-
-=item *
-
-IO::File upgraded to version 1.11
-
-=item *
-
-IO::Socket upgraded to version 1.28
-
-=item *
-
-Math::BigInt upgraded to version 1.77
-
-=item *
-
-Math::BigRat upgraded to version 0.15
-
-=item *
-
-overload upgraded to version 1.03
-
-=item *
-
-PathTools upgraded to version 3.05
-
-=item *
-
-Pod::HTML upgraded to version 1.0503
-
-=item *
-
-Pod::Perldoc upgraded to version 3.14
-
-=item *
-
-Pod::LaTeX upgraded to version 0.58
-
-=item *
-
-Pod::Parser upgraded to version 1.30
-
-=item *
-
-Symbol upgraded to version 1.06
-
-=item *
-
-Term::ANSIColor upgraded to version 1.09
-
-=item *
-
-Test::Harness upgraded to version 2.48
-
-=item *
-
-Test::Simple upgraded to version 0.54
-
-=item *
-
-Text::Wrap upgraded to version 2001.09293, to fix a bug when wrap() was
-called with a non-space separator.
-
-=item *
-
-threads::shared upgraded to version 0.93
-
-=item *
-
-Time::HiRes upgraded to version 1.66
-
-=item *
-
-Time::Local upgraded to version 1.11
-
-=item *
-
-Unicode::Normalize upgraded to version 0.32
-
-=item *
-
-utf8 upgraded to version 1.05
-
-=item *
-
-Win32 upgraded to version 0.24, which provides Win32::GetFileVersion
-
-=back
-
-=head1 Utility Changes
-
-=head2 find2perl enhancements
-
-C<find2perl> has new options C<-iname>, C<-path> and C<-ipath>.
-
-=head1 Performance Enhancements
-
-The internal pointer mapping hash used during ithreads cloning now uses an
-arena for memory allocation. In tests this reduced ithreads cloning time by
-about 10%.
-
-=head1 Installation and Configuration Improvements
-
-=over 4
-
-=item *
-
-The Win32 "dmake" makefile.mk has been updated to make it compatible
-with the latest versions of dmake.
-
-=item *
-
-C<PERL_MALLOC>, C<DEBUG_MSTATS>, C<PERL_HASH_SEED_EXPLICIT> and C<NO_HASH_SEED>
-should now work in Win32 makefiles.
-
-=back
-
-=head1 Selected Bug Fixes
-
-=over 4
-
-=item *
-
-The socket() function on Win32 has been fixed so that it is able to use
-transport providers which specify a protocol of 0 (meaning any protocol
-is allowed) once more. (This was broken in 5.8.6, and typically caused
-the use of ICMP sockets to fail.)
-
-=item *
-
-Another obscure bug involving C<substr> and UTF-8 caused by bad internal
-offset caching has been identified and fixed.
-
-=item *
-
-A bug involving the loading of UTF-8 tables by the regexp engine has been
-fixed - code such as C<"\x{100}" =~ /[[:print:]]/> will no longer give
-corrupt results.
-
-=item *
-
-Case conversion operations such as C<uc> on a long Unicode string could
-exhaust memory. This has been fixed.
-
-=item *
-
-C<index>/C<rindex> were buggy for some combinations of Unicode and
-non-Unicode data. This has been fixed.
-
-=item *
-
-C<read> (and presumably C<sysread>) would expose the UTF-8 internals when
-reading from a byte oriented file handle into a UTF-8 scalar. This has
-been fixed.
-
-=item *
-
-Several C<pack>/C<unpack> bug fixes:
-
-=over 4
-
-=item *
-
-Checksums with C<b> or C<B> formats were broken.
-
-=item *
-
-C<unpack> checksums could overflow with the C<C> format.
-
-=item *
-
-C<U0> and C<C0> are now scoped to C<()> C<pack> sub-templates.
-
-=item *
-
-Counted length prefixes now don't change C<C0>/C<U0> mode.
-
-=item *
-
-C<pack> C<Z0> used to destroy the preceding character.
-
-=item *
-
-C<P>/C<p> C<pack> formats used to only recognise literal C<undef>
-
-=back
-
-=item *
-
-Using closures with ithreads could cause perl to crash. This was due to
-failure to correctly lock internal OP structures, and has been fixed.
-
-=item *
-
-The return value of C<close> now correctly reflects any file errors that
-occur while flushing the handle's data, instead of just giving failure if
-the actual underlying file close operation failed.
-
-=item *
-
-C<not() || 1> used to segfault. C<not()> now behaves like C<not(0)>, which was
-the pre 5.6.0 behaviour.
-
-=item *
-
-C<h2ph> has various enhancements to cope with constructs in header files that
-used to result in incorrect or invalid output.
-
-=back
-
-=head1 New or Changed Diagnostics
-
-There is a new taint error, "%ENV is aliased to %s". This error is thrown
-when taint checks are enabled and when C<*ENV> has been aliased, so that
-C<%ENV> has no env-magic anymore and hence the environment cannot be verified
-as taint-free.
-
-The internals of C<pack> and C<unpack> have been updated. All legitimate
-templates should work as before, but there may be some changes in the error
-reported for complex failure cases. Any behaviour changes for non-error cases
-are bugs, and should be reported.
-
-=head1 Changed Internals
-
-There has been a fair amount of refactoring of the C<C> source code, partly to
-make it tidier and more maintainable. The resulting object code and the
-C<perl> binary may well be smaller than 5.8.6, and hopefully faster in some
-cases, but apart from this there should be no user-detectable changes.
-
-C<${^UTF8LOCALE}> has been added to give perl space access to C<PL_utf8locale>.
-
-The size of the arenas used to allocate SV heads and most SV bodies can now
-be changed at compile time. The old size was 1008 bytes, the new default size
-is 4080 bytes.
-
-=head1 Known Problems
-
-Unicode strings returned from overloaded operators can be buggy. This is a
-long standing bug reported since 5.8.6 was released, but we do not yet have
-a suitable fix for it.
-
-=head1 Platform Specific Problems
-
-On UNICOS, lib/Math/BigInt/t/bigintc.t hangs burning CPU.
-ext/B/t/bytecode.t and ext/Socket/t/socketpair.t both fail tests.
-These are unlikely to be resolved, as our valiant UNICOS porter's last
-Cray is being decommissioned.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://bugs.perl.org. There may also be
-information at http://www.perl.org, the Perl Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team. You can browse and search
-the Perl 5 bugs at http://bugs.perl.org/
-
-=head1 SEE ALSO
-
-The F<Changes> file for exhaustive details on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl588delta.pod b/Master/tlpkg/tlperl/lib/pods/perl588delta.pod
deleted file mode 100644
index b2203bcf71d..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl588delta.pod
+++ /dev/null
@@ -1,1634 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perl588delta - what is new for perl v5.8.8
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.8.7 release and
-the 5.8.8 release.
-
-=head1 Incompatible Changes
-
-There are no changes intentionally incompatible with 5.8.7. If any exist,
-they are bugs and reports are welcome.
-
-=head1 Core Enhancements
-
-=over
-
-=item *
-
-C<chdir>, C<chmod> and C<chown> can now work on filehandles as well as
-filenames, if the system supports respectively C<fchdir>, C<fchmod> and
-C<fchown>, thanks to a patch provided by Gisle Aas.
-
-=back
-
-=head1 Modules and Pragmata
-
-=over
-
-=item *
-
-C<Attribute::Handlers> upgraded to version 0.78_02
-
-=over
-
-=item *
-
-Documentation typo fix
-
-=back
-
-=item *
-
-C<attrs> upgraded to version 1.02
-
-=over
-
-=item *
-
-Internal cleanup only
-
-=back
-
-=item *
-
-C<autouse> upgraded to version 1.05
-
-=over
-
-=item *
-
-Simplified implementation
-
-=back
-
-=item *
-
-C<B> upgraded to version 1.09_01
-
-=over
-
-=item *
-
-The inheritance hierarchy of the C<B::> modules has been corrected;
-C<B::NV> now inherits from C<B::SV> (instead of C<B::IV>).
-
-=back
-
-=item *
-
-C<blib> upgraded to version 1.03
-
-=over
-
-=item *
-
-Documentation typo fix
-
-=back
-
-=item *
-
-C<ByteLoader> upgraded to version 0.06
-
-=over
-
-=item *
-
-Internal cleanup
-
-=back
-
-=item *
-
-C<CGI> upgraded to version 3.15
-
-=over
-
-=item *
-
-Extraneous "?" from C<self_url()> removed
-
-=item *
-
-C<scrolling_list()> select attribute fixed
-
-=item *
-
-C<virtual_port> now works properly with the https protocol
-
-=item *
-
-C<upload_hook()> and C<append()> now works in function-oriented mode
-
-=item *
-
-C<POST_MAX> doesn't cause the client to hang any more
-
-=item *
-
-Automatic tab indexes are now disabled and new C<-tabindex> pragma has
-been added to turn automatic indexes back on
-
-=item *
-
-C<end_form()> doesn't emit empty (and non-validating) C<< <div> >>
-
-=item *
-
-C<CGI::Carp> works better in certain mod_perl configurations
-
-=item *
-
-Setting C<$CGI::TMPDIRECTORY> is now effective
-
-=item *
-
-Enhanced documentation
-
-=back
-
-=item *
-
-C<charnames> upgraded to version 1.05
-
-=over
-
-=item *
-
-C<viacode()> now accept hex strings and has been optimized.
-
-=back
-
-=item *
-
-C<CPAN> upgraded to version 1.76_02
-
-=over
-
-=item *
-
-1 minor bug fix for Win32
-
-=back
-
-=item *
-
-C<Cwd> upgraded to version 3.12
-
-=over
-
-=item *
-
-C<canonpath()> on Win32 now collapses F<foo\..> sections correctly.
-
-=item *
-
-Improved behaviour on Symbian OS.
-
-=item *
-
-Enhanced documentation and typo fixes
-
-=item *
-
-Internal cleanup
-
-=back
-
-=item *
-
-C<Data::Dumper> upgraded to version 2.121_08
-
-=over
-
-=item *
-
-A problem where C<Data::Dumper> would sometimes update the iterator state
-of hashes has been fixed
-
-=item *
-
-Numeric labels now work
-
-=item *
-
-Internal cleanup
-
-=back
-
-=item *
-
-C<DB> upgraded to version 1.01
-
-=over
-
-=item *
-
-A problem where the state of the regexp engine would sometimes get clobbered when running
-under the debugger has been fixed.
-
-=back
-
-=item *
-
-C<DB_File> upgraded to version 1.814
-
-=over
-
-=item *
-
-Adds support for Berkeley DB 4.4.
-
-=back
-
-=item *
-
-C<Devel::DProf> upgraded to version 20050603.00
-
-=over
-
-=item *
-
-Internal cleanup
-
-=back
-
-=item *
-
-C<Devel::Peek> upgraded to version 1.03
-
-=over
-
-=item *
-
-Internal cleanup
-
-=back
-
-=item *
-
-C<Devel::PPPort> upgraded to version 3.06_01
-
-=over
-
-=item *
-
-C<--compat-version> argument checking has been improved
-
-=item *
-
-Files passed on the command line are filtered by default
-
-=item *
-
-C<--nofilter> option to override the filtering has been added
-
-=item *
-
-Enhanced documentation
-
-=back
-
-=item *
-
-C<diagnostics> upgraded to version 1.15
-
-=over
-
-=item *
-
-Documentation typo fix
-
-=back
-
-=item *
-
-C<Digest> upgraded to version 1.14
-
-=over
-
-=item *
-
-The constructor now knows which module implements SHA-224
-
-=item *
-
-Documentation tweaks and typo fixes
-
-=back
-
-=item *
-
-C<Digest::MD5> upgraded to version 2.36
-
-=over
-
-=item *
-
-C<XSLoader> is now used for faster loading
-
-=item *
-
-Enhanced documentation including MD5 weaknesses discovered lately
-
-=back
-
-=item *
-
-C<Dumpvalue> upgraded to version 1.12
-
-=over
-
-=item *
-
-Documentation fix
-
-=back
-
-=item *
-
-C<DynaLoader> upgraded but unfortunately we're not able to increment its version number :-(
-
-=over
-
-=item *
-
-Implements C<dl_unload_file> on Win32
-
-=item *
-
-Internal cleanup
-
-=item *
-
-C<XSLoader> 0.06 incorporated; small optimisation for calling
-C<bootstrap_inherit()> and documentation enhancements.
-
-=back
-
-=item *
-
-C<Encode> upgraded to version 2.12
-
-=over
-
-=item *
-
-A coderef is now acceptable for C<CHECK>!
-
-=item *
-
-3 new characters added to the ISO-8859-7 encoding
-
-=item *
-
-New encoding C<MIME-Header-ISO_2022_JP> added
-
-=item *
-
-Problem with partial characters and C<< encoding(utf-8-strict) >> fixed.
-
-=item *
-
-Documentation enhancements and typo fixes
-
-=back
-
-=item *
-
-C<English> upgraded to version 1.02
-
-=over
-
-=item *
-
-the C<< $COMPILING >> variable has been added
-
-=back
-
-=item *
-
-C<ExtUtils::Constant> upgraded to version 0.17
-
-=over
-
-=item *
-
-Improved compatibility with older versions of perl
-
-=back
-
-=item *
-
-C<ExtUtils::MakeMaker> upgraded to version 6.30 (was 6.17)
-
-=over
-
-=item *
-
-Too much to list here; see L<http://search.cpan.org/dist/ExtUtils-MakeMaker/Changes>
-
-=back
-
-=item *
-
-C<File::Basename> upgraded to version 2.74, with changes contributed by Michael Schwern.
-
-=over
-
-=item *
-
-Documentation clarified and errors corrected.
-
-=item *
-
-C<basename> now strips trailing path separators before processing the name.
-
-=item *
-
-C<basename> now returns C</> for parameter C</>, to make C<basename>
-consistent with the shell utility of the same name.
-
-=item *
-
-The suffix is no longer stripped if it is identical to the remaining characters
-in the name, again for consistency with the shell utility.
-
-=item *
-
-Some internal code cleanup.
-
-=back
-
-=item *
-
-C<File::Copy> upgraded to version 2.09
-
-=over
-
-=item *
-
-Copying a file onto itself used to fail.
-
-=item *
-
-Moving a file between file systems now preserves the access and
-modification time stamps
-
-=back
-
-=item *
-
-C<File::Find> upgraded to version 1.10
-
-=over
-
-=item *
-
-Win32 portability fixes
-
-=item *
-
-Enhanced documentation
-
-=back
-
-=item *
-
-C<File::Glob> upgraded to version 1.05
-
-=over
-
-=item *
-
-Internal cleanup
-
-=back
-
-=item *
-
-C<File::Path> upgraded to version 1.08
-
-=over
-
-=item *
-
-C<mkpath> now preserves C<errno> when C<mkdir> fails
-
-=back
-
-=item *
-
-C<File::Spec> upgraded to version 3.12
-
-=over
-
-=item *
-
-C<File::Spec->rootdir()> now returns C<\> on Win32, instead of C</>
-
-=item *
-
-C<$^O> could sometimes become tainted. This has been fixed.
-
-=item *
-
-C<canonpath> on Win32 now collapses C<foo/..> (or C<foo\..>) sections
-correctly, rather than doing the "misguided" work it was previously doing.
-Note that C<canonpath> on Unix still does B<not> collapse these sections, as
-doing so would be incorrect.
-
-=item *
-
-Some documentation improvements
-
-=item *
-
-Some internal code cleanup
-
-=back
-
-=item *
-
-C<FileCache> upgraded to version 1.06
-
-=over
-
-=item *
-
-POD formatting errors in the documentation fixed
-
-=back
-
-=item *
-
-C<Filter::Simple> upgraded to version 0.82
-
-=item *
-
-C<FindBin> upgraded to version 1.47
-
-=over
-
-=item *
-
-Now works better with directories where access rights are more
-restrictive than usual.
-
-=back
-
-=item *
-
-C<GDBM_File> upgraded to version 1.08
-
-=over
-
-=item *
-
-Internal cleanup
-
-=back
-
-=item *
-
-C<Getopt::Long> upgraded to version 2.35
-
-=over
-
-=item *
-
-C<prefix_pattern> has now been complemented by a new configuration
-option C<long_prefix_pattern> that allows the user to specify what
-prefix patterns should have long option style semantics applied.
-
-=item *
-
-Options can now take multiple values at once (experimental)
-
-=item *
-
-Various bug fixes
-
-=back
-
-=item *
-
-C<if> upgraded to version 0.05
-
-=over
-
-=item *
-
-Give more meaningful error messages from C<if> when invoked with a
-condition in list context.
-
-=item *
-
-Restore backwards compatibility with earlier versions of perl
-
-=back
-
-=item *
-
-C<IO> upgraded to version 1.22
-
-=over
-
-=item *
-
-Enhanced documentation
-
-=item *
-
-Internal cleanup
-
-=back
-
-=item *
-
-C<IPC::Open2> upgraded to version 1.02
-
-=over
-
-=item *
-
-Enhanced documentation
-
-=back
-
-=item *
-
-C<IPC::Open3> upgraded to version 1.02
-
-=over
-
-=item *
-
-Enhanced documentation
-
-=back
-
-=item *
-
-C<List::Util> upgraded to version 1.18 (was 1.14)
-
-=over
-
-=item *
-
-Fix pure-perl version of C<refaddr> to avoid blessing an un-blessed reference
-
-=item *
-
-Use C<XSLoader> for faster loading
-
-=item *
-
-Fixed various memory leaks
-
-=item *
-
-Internal cleanup and portability fixes
-
-=back
-
-=item *
-
-C<Math::Complex> upgraded to version 1.35
-
-=over
-
-=item *
-
-C<atan2(0, i)> now works, as do all the (computable) complex argument cases
-
-=item *
-
-Fixes for certain bugs in C<make> and C<emake>
-
-=item *
-
-Support returning the I<k>th root directly
-
-=item *
-
-Support C<[2,-3pi/8]> in C<emake>
-
-=item *
-
-Support C<inf> for C<make>/C<emake>
-
-=item *
-
-Document C<make>/C<emake> more visibly
-
-=back
-
-=item *
-
-C<Math::Trig> upgraded to version 1.03
-
-=over
-
-=item *
-
-Add more great circle routines: C<great_circle_waypoint> and
-C<great_circle_destination>
-
-=back
-
-=item *
-
-C<MIME::Base64> upgraded to version 3.07
-
-=over
-
-=item *
-
-Use C<XSLoader> for faster loading
-
-=item *
-
-Enhanced documentation
-
-=item *
-
-Internal cleanup
-
-=back
-
-=item *
-
-C<NDBM_File> upgraded to version 1.06
-
-=over
-
-=item *
-
-Enhanced documentation
-
-=back
-
-=item *
-
-C<ODBM_File> upgraded to version 1.06
-
-=over
-
-=item *
-
-Documentation typo fixed
-
-=item *
-
-Internal cleanup
-
-=back
-
-=item *
-
-C<Opcode> upgraded to version 1.06
-
-=over
-
-=item *
-
-Enhanced documentation
-
-=item *
-
-Internal cleanup
-
-=back
-
-=item *
-
-C<open> upgraded to version 1.05
-
-=over
-
-=item *
-
-Enhanced documentation
-
-=back
-
-=item *
-
-C<overload> upgraded to version 1.04
-
-=over
-
-=item *
-
-Enhanced documentation
-
-=back
-
-=item *
-
-C<PerlIO> upgraded to version 1.04
-
-=over
-
-=item *
-
-C<PerlIO::via> iterate over layers properly now
-
-=item *
-
-C<PerlIO::scalar> understands C<< $/ = "" >> now
-
-=item *
-
-C<encoding(utf-8-strict)> with partial characters now works
-
-=item *
-
-Enhanced documentation
-
-=item *
-
-Internal cleanup
-
-=back
-
-=item *
-
-C<Pod::Functions> upgraded to version 1.03
-
-=over
-
-=item *
-
-Documentation typos fixed
-
-=back
-
-=item *
-
-C<Pod::Html> upgraded to version 1.0504
-
-=over
-
-=item *
-
-HTML output will now correctly link
-to C<=item>s on the same page, and should be valid XHTML.
-
-=item *
-
-Variable names are recognized as intended
-
-=item *
-
-Documentation typos fixed
-
-=back
-
-=item *
-
-C<Pod::Parser> upgraded to version 1.32
-
-=over
-
-=item *
-
-Allow files that start with C<=head> on the first line
-
-=item *
-
-Win32 portability fix
-
-=item *
-
-Exit status of C<pod2usage> fixed
-
-=item *
-
-New C<-noperldoc> switch for C<pod2usage>
-
-=item *
-
-Arbitrary URL schemes now allowed
-
-=item *
-
-Documentation typos fixed
-
-=back
-
-=item *
-
-C<POSIX> upgraded to version 1.09
-
-=over
-
-=item *
-
-Documentation typos fixed
-
-=item *
-
-Internal cleanup
-
-=back
-
-=item *
-
-C<re> upgraded to version 0.05
-
-=over
-
-=item *
-
-Documentation typo fixed
-
-=back
-
-=item *
-
-C<Safe> upgraded to version 2.12
-
-=over
-
-=item *
-
-Minor documentation enhancement
-
-=back
-
-=item *
-
-C<SDBM_File> upgraded to version 1.05
-
-=over
-
-=item *
-
-Documentation typo fixed
-
-=item *
-
-Internal cleanup
-
-=back
-
-=item *
-
-C<Socket> upgraded to version 1.78
-
-=over
-
-=item *
-
-Internal cleanup
-
-=back
-
-=item *
-
-C<Storable> upgraded to version 2.15
-
-=over
-
-=item *
-
-This includes the C<STORABLE_attach> hook functionality added by
-Adam Kennedy, and more frugal memory requirements when storing under C<ithreads>, by
-using the C<ithreads> cloning tracking code.
-
-=back
-
-=item *
-
-C<Switch> upgraded to version 2.10_01
-
-=over
-
-=item *
-
-Documentation typos fixed
-
-=back
-
-=item *
-
-C<Sys::Syslog> upgraded to version 0.13
-
-=over
-
-=item *
-
-Now provides numeric macros and meaningful C<Exporter> tags.
-
-=item *
-
-No longer uses C<Sys::Hostname> as it may provide useless values in
-unconfigured network environments, so instead uses C<INADDR_LOOPBACK> directly.
-
-=item *
-
-C<syslog()> now uses local timestamp.
-
-=item *
-
-C<setlogmask()> now behaves like its C counterpart.
-
-=item *
-
-C<setlogsock()> will now C<croak()> as documented.
-
-=item *
-
-Improved error and warnings messages.
-
-=item *
-
-Improved documentation.
-
-=back
-
-=item *
-
-C<Term::ANSIColor> upgraded to version 1.10
-
-=over
-
-=item *
-
-Fixes a bug in C<colored> when C<$EACHLINE> is set that caused it to not color
-lines consisting solely of 0 (literal zero).
-
-=item *
-
-Improved tests.
-
-=back
-
-=item *
-
-C<Term::ReadLine> upgraded to version 1.02
-
-=over
-
-=item *
-
-Documentation tweaks
-
-=back
-
-=item *
-
-C<Test::Harness> upgraded to version 2.56 (was 2.48)
-
-=over
-
-=item *
-
-The C<Test::Harness> timer is now off by default.
-
-=item *
-
-Now shows elapsed time in milliseconds.
-
-=item *
-
-Various bug fixes
-
-=back
-
-=item *
-
-C<Test::Simple> upgraded to version 0.62 (was 0.54)
-
-=over
-
-=item *
-
-C<is_deeply()> no longer fails to work for many cases
-
-=item *
-
-Various minor bug fixes
-
-=item *
-
-Documentation enhancements
-
-=back
-
-=item *
-
-C<Text::Tabs> upgraded to version 2005.0824
-
-=over
-
-=item *
-
-Provides a faster implementation of C<expand>
-
-=back
-
-=item *
-
-C<Text::Wrap> upgraded to version 2005.082401
-
-=over
-
-=item *
-
-Adds C<$Text::Wrap::separator2>, which allows you to preserve existing newlines
-but add line-breaks with some other string.
-
-=back
-
-=item *
-
-C<threads> upgraded to version 1.07
-
-=over
-
-=item *
-
-C<threads> will now honour C<no warnings 'threads'>
-
-=item *
-
-A thread's interpreter is now freed after C<< $t->join() >> rather than after
-C<undef $t>, which should fix some C<ithreads> memory leaks. (Fixed by Dave
-Mitchell)
-
-=item *
-
-Some documentation typo fixes.
-
-=back
-
-=item *
-
-C<threads::shared> upgraded to version 0.94
-
-=over
-
-=item *
-
-Documentation changes only
-
-=item *
-
-Note: An improved implementation of C<threads::shared> is available on
-CPAN - this will be merged into 5.8.9 if it proves stable.
-
-=back
-
-=item *
-
-C<Tie::Hash> upgraded to version 1.02
-
-=over
-
-=item *
-
-Documentation typo fixed
-
-=back
-
-=item *
-
-C<Time::HiRes> upgraded to version 1.86 (was 1.66)
-
-=over
-
-=item *
-
-C<clock_nanosleep()> and C<clock()> functions added
-
-=item *
-
-Support for the POSIX C<clock_gettime()> and C<clock_getres()> has been added
-
-=item *
-
-Return C<undef> or an empty list if the C C<gettimeofday()> function fails
-
-=item *
-
-Improved C<nanosleep> detection
-
-=item *
-
-Internal cleanup
-
-=item *
-
-Enhanced documentation
-
-=back
-
-=item *
-
-C<Unicode::Collate> upgraded to version 0.52
-
-=over
-
-=item *
-
-Now implements UCA Revision 14 (based on Unicode 4.1.0).
-
-=item *
-
-C<Unicode::Collate->new> method no longer overwrites user's C<$_>
-
-=item *
-
-Enhanced documentation
-
-=back
-
-=item *
-
-C<Unicode::UCD> upgraded to version 0.24
-
-=over
-
-=item *
-
-Documentation typos fixed
-
-=back
-
-=item *
-
-C<User::grent> upgraded to version 1.01
-
-=over
-
-=item *
-
-Documentation typo fixed
-
-=back
-
-=item *
-
-C<utf8> upgraded to version 1.06
-
-=over
-
-=item *
-
-Documentation typos fixed
-
-=back
-
-=item *
-
-C<vmsish> upgraded to version 1.02
-
-=over
-
-=item *
-
-Documentation typos fixed
-
-=back
-
-=item *
-
-C<warnings> upgraded to version 1.05
-
-=over
-
-=item *
-
-Gentler messing with C<Carp::> internals
-
-=item *
-
-Internal cleanup
-
-=item *
-
-Documentation update
-
-=back
-
-=item *
-
-C<Win32> upgraded to version 0.2601
-
-=for cynics And how many perl 5.8.x versions can I release ahead of Vista?
-
-=over
-
-=item *
-
-Provides Windows Vista support to C<Win32::GetOSName>
-
-=item *
-
-Documentation enhancements
-
-=back
-
-=item *
-
-C<XS::Typemap> upgraded to version 0.02
-
-=over
-
-=item *
-
-Internal cleanup
-
-=back
-
-=back
-
-=head1 Utility Changes
-
-=head2 C<h2xs> enhancements
-
-C<h2xs> implements new option C<--use-xsloader> to force use of
-C<XSLoader> even in backwards compatible modules.
-
-The handling of authors' names that had apostrophes has been fixed.
-
-Any enums with negative values are now skipped.
-
-=head2 C<perlivp> enhancements
-
-C<perlivp> implements new option C<-a> and will not check for F<*.ph>
-files by default any more. Use the C<-a> option to run I<all> tests.
-
-=head1 New Documentation
-
-The L<perlglossary> manpage is a glossary of terms used in the Perl
-documentation, technical and otherwise, kindly provided by O'Reilly Media,
-inc.
-
-=head1 Performance Enhancements
-
-=over 4
-
-=item *
-
-Weak reference creation is now I<O(1)> rather than I<O(n)>, courtesy of
-Nicholas Clark. Weak reference deletion remains I<O(n)>, but if deletion only
-happens at program exit, it may be skipped completely.
-
-=item *
-
-Salvador Fandiño provided improvements to reduce the memory usage of C<sort>
-and to speed up some cases.
-
-=item *
-
-Jarkko Hietaniemi and Andy Lester worked to mark as much data as possible in
-the C source files as C<static>, to increase the proportion of the executable
-file that the operating system can share between process, and thus reduce
-real memory usage on multi-user systems.
-
-=back
-
-=head1 Installation and Configuration Improvements
-
-Parallel makes should work properly now, although there may still be problems
-if C<make test> is instructed to run in parallel.
-
-Building with Borland's compilers on Win32 should work more smoothly. In
-particular Steve Hay has worked to side step many warnings emitted by their
-compilers and at least one C compiler internal error.
-
-C<Configure> will now detect C<clearenv> and C<unsetenv>, thanks to a patch
-from Alan Burlison. It will also probe for C<futimes> and whether C<sprintf>
-correctly returns the length of the formatted string, which will both be used
-in perl 5.8.9.
-
-There are improved hints for next-3.0, vmesa, IX, Darwin, Solaris, Linux,
-DEC/OSF, HP-UX and MPE/iX
-
-Perl extensions on Windows now can be statically built into the Perl DLL,
-thanks to a work by Vadim Konovalov. (This improvement was actually in 5.8.7,
-but was accidentally omitted from L<perl587delta>).
-
-=head1 Selected Bug Fixes
-
-=head2 no warnings 'category' works correctly with -w
-
-Previously when running with warnings enabled globally via C<-w>, selective
-disabling of specific warning categories would actually turn off all warnings.
-This is now fixed; now C<no warnings 'io';> will only turn off warnings in the
-C<io> class. Previously it would erroneously turn off all warnings.
-
-This bug fix may cause some programs to start correctly issuing warnings.
-
-=head2 Remove over-optimisation
-
-Perl 5.8.4 introduced a change so that assignments of C<undef> to a
-scalar, or of an empty list to an array or a hash, were optimised away. As
-this could cause problems when C<goto> jumps were involved, this change
-has been backed out.
-
-=head2 sprintf() fixes
-
-Using the sprintf() function with some formats could lead to a buffer
-overflow in some specific cases. This has been fixed, along with several
-other bugs, notably in bounds checking.
-
-In related fixes, it was possible for badly written code that did not follow
-the documentation of C<Sys::Syslog> to have formatting vulnerabilities.
-C<Sys::Syslog> has been changed to protect people from poor quality third
-party code.
-
-=head2 Debugger and Unicode slowdown
-
-It had been reported that running under perl's debugger when processing
-Unicode data could cause unexpectedly large slowdowns. The most likely cause
-of this was identified and fixed by Nicholas Clark.
-
-=head2 Smaller fixes
-
-=over 4
-
-=item *
-
-C<FindBin> now works better with directories where access rights are more
-restrictive than usual.
-
-=item *
-
-Several memory leaks in ithreads were closed. An improved implementation of
-C<threads::shared> is available on CPAN - this will be merged into 5.8.9 if
-it proves stable.
-
-=item *
-
-Trailing spaces are now trimmed from C<$!> and C<$^E>.
-
-=item *
-
-Operations that require perl to read a process's list of groups, such as reads
-of C<$(> and C<$)>, now dynamically allocate memory rather than using a
-fixed sized array. The fixed size array could cause C stack exhaustion on
-systems configured to use large numbers of groups.
-
-=item *
-
-C<PerlIO::scalar> now works better with non-default C<$/> settings.
-
-=item *
-
-You can now use the C<x> operator to repeat a C<qw//> list. This used
-to raise a syntax error.
-
-=item *
-
-The debugger now traces correctly execution in eval("")uated code that
-contains #line directives.
-
-=item *
-
-The value of the C<open> pragma is no longer ignored for three-argument
-opens.
-
-=item *
-
-The optimisation of C<for (reverse @a)> introduced in perl 5.8.6 could
-misbehave when the array had undefined elements and was used in LVALUE
-context. Dave Mitchell provided a fix.
-
-=item *
-
-Some case insensitive matches between UTF-8 encoded data and 8 bit regexps,
-and vice versa, could give malformed character warnings. These have been
-fixed by Dave Mitchell and Yves Orton.
-
-=item *
-
-C<lcfirst> and C<ucfirst> could corrupt the string for certain cases where
-the length UTF-8 encoding of the string in lower case, upper case or title
-case differed. This was fixed by Nicholas Clark.
-
-=item *
-
-Perl will now use the C library calls C<unsetenv> and C<clearenv> if present
-to delete keys from C<%ENV> and delete C<%ENV> entirely, thanks to a patch
-from Alan Burlison.
-
-=back
-
-=head1 New or Changed Diagnostics
-
-=head2 Attempt to set length of freed array
-
-This is a new warning, produced in situations such as this:
-
- $r = do {my @a; \$#a};
- $$r = 503;
-
-=head2 Non-string passed as bitmask
-
-This is a new warning, produced when number has been passed as a argument to
-select(), instead of a bitmask.
-
- # Wrong, will now warn
- $rin = fileno(STDIN);
- ($nfound,$timeleft) = select($rout=$rin, undef, undef, $timeout);
-
- # Should be
- $rin = '';
- vec($rin,fileno(STDIN),1) = 1;
- ($nfound,$timeleft) = select($rout=$rin, undef, undef, $timeout);
-
-=head2 Search pattern not terminated or ternary operator parsed as search pattern
-
-This syntax error indicates that the lexer couldn't find the final
-delimiter of a C<?PATTERN?> construct. Mentioning the ternary operator in
-this error message makes it easier to diagnose syntax errors.
-
-=head1 Changed Internals
-
-There has been a fair amount of refactoring of the C<C> source code, partly to
-make it tidier and more maintainable. The resulting object code and the
-C<perl> binary may well be smaller than 5.8.7, in particular due to a change
-contributed by Dave Mitchell which reworked the warnings code to be
-significantly smaller. Apart from being smaller and possibly faster, there
-should be no user-detectable changes.
-
-Andy Lester supplied many improvements to determine which function
-parameters and local variables could actually be declared C<const> to the C
-compiler. Steve Peters provided new C<*_set> macros and reworked the core to
-use these rather than assigning to macros in LVALUE context.
-
-Dave Mitchell improved the lexer debugging output under C<-DT>
-
-Nicholas Clark changed the string buffer allocation so that it is now rounded
-up to the next multiple of 4 (or 8 on platforms with 64 bit pointers). This
-should reduce the number of calls to C<realloc> without actually using any
-extra memory.
-
-The C<HV>'s array of C<HE*>s is now allocated at the correct (minimal) size,
-thanks to another change by Nicholas Clark. Compile with
-C<-DPERL_USE_LARGE_HV_ALLOC> to use the old, sloppier, default.
-
-For XS or embedding debugging purposes, if perl is compiled with
-C<-DDEBUG_LEAKING_SCALARS_FORK_DUMP> in addition to
-C<-DDEBUG_LEAKING_SCALARS> then a child process is C<fork>ed just before
-global destruction, which is used to display the values of any scalars
-found to have leaked at the end of global destruction. Without this, the
-scalars have already been freed sufficiently at the point of detection that
-it is impossible to produce any meaningful dump of their contents. This
-feature was implemented by the indefatigable Nicholas Clark, based on an idea
-by Mike Giroux.
-
-=head1 Platform Specific Problems
-
-The optimiser on HP-UX 11.23 (Itanium 2) is currently partly disabled (scaled
-down to +O1) when using HP C-ANSI-C; the cause of problems at higher
-optimisation levels is still unclear.
-
-There are a handful of remaining test failures on VMS, mostly due to
-test fixes and minor module tweaks with too many dependencies to
-integrate into this release from the development stream, where they have
-all been corrected. The following is a list of expected failures with
-the patch number of the fix where that is known:
-
- ext/Devel/PPPort/t/ppphtest.t #26913
- ext/List/Util/t/p_tainted.t #26912
- lib/ExtUtils/t/PL_FILES.t #26813
- lib/ExtUtils/t/basic.t #26813
- t/io/fs.t
- t/op/cmp.t
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://bugs.perl.org. There may also be
-information at http://www.perl.org, the Perl Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team. You can browse and search
-the Perl 5 bugs at http://bugs.perl.org/
-
-=head1 SEE ALSO
-
-The F<Changes> file for exhaustive details on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl589delta.pod b/Master/tlpkg/tlperl/lib/pods/perl589delta.pod
deleted file mode 100644
index f10099ccfa4..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl589delta.pod
+++ /dev/null
@@ -1,2337 +0,0 @@
-=head1 NAME
-
-perl589delta - what is new for perl v5.8.9
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.8.8 release and
-the 5.8.9 release.
-
-=head1 Notice
-
-The 5.8.9 release will be the last significant release of the 5.8.x
-series. Any future releases of 5.8.x will likely only be to deal with
-security issues, and platform build failures. Hence you should look to
-migrating to 5.10.x, if you have not started already.
-See L</"Known Problems"> for more information.
-
-=head1 Incompatible Changes
-
-A particular construction in the source code of extensions written in C++
-may need changing. See L</"Changed Internals"> for more details. All
-extensions written in C, most written in C++, and all existing compiled
-extensions are unaffected. This was necessary to improve C++ support.
-
-Other than this, there are no changes intentionally incompatible with 5.8.8.
-If any exist, they are bugs and reports are welcome.
-
-=head1 Core Enhancements
-
-=head2 Unicode Character Database 5.1.0.
-
-The copy of the Unicode Character Database included in Perl 5.8 has
-been updated to 5.1.0 from 4.1.0. See
-L<http://www.unicode.org/versions/Unicode5.1.0/#NotableChanges> for the
-notable changes.
-
-=head2 stat and -X on directory handles
-
-It is now possible to call C<stat> and the C<-X> filestat operators on
-directory handles. As both directory and file handles are barewords, there
-can be ambiguities over which was intended. In these situations the file
-handle semantics are preferred. Both also treat C<*FILE{IO}> filehandles
-like C<*FILE> filehandles.
-
-=head2 Source filters in @INC
-
-It's possible to enhance the mechanism of subroutine hooks in @INC by
-adding a source filter on top of the filehandle opened and returned by the
-hook. This feature was planned a long time ago, but wasn't quite working
-until now. See L<perlfunc/require> for details. (Nicholas Clark)
-
-=head2 Exceptions in constant folding
-
-The constant folding routine is now wrapped in an exception handler, and
-if folding throws an exception (such as attempting to evaluate 0/0), perl
-now retains the current optree, rather than aborting the whole program.
-Without this change, programs would not compile if they had expressions that
-happened to generate exceptions, even though those expressions were in code
-that could never be reached at runtime. (Nicholas Clark, Dave Mitchell)
-
-=head2 C<no VERSION>
-
-You can now use C<no> followed by a version number to specify that you
-want to use a version of perl older than the specified one.
-
-=head2 Improved internal UTF-8 caching code
-
-The code that caches calculated UTF-8 byte offsets for character offsets for
-a string has been re-written. Several bugs have been located and eliminated,
-and the code now makes better use of the information it has, so should be
-faster. In particular, it doesn't scan to the end of a string before
-calculating an offset within the string, which should speed up some operations
-on long strings. It is now possible to disable the caching code at run time,
-to verify that it is not the cause of suspected problems.
-
-=head2 Runtime relocatable installations
-
-There is now F<Configure> support for creating a perl tree that is relocatable
-at run time. see L</Relocatable installations>.
-
-=head2 New internal variables
-
-=over 4
-
-=item C<${^CHILD_ERROR_NATIVE}>
-
-This variable gives the native status returned by the last pipe close,
-backtick command, successful call to C<wait> or C<waitpid>, or from the
-C<system> operator. See L<perlvar> for details. (Contributed by Gisle Aas.)
-
-=item C<${^UTF8CACHE}>
-
-This variable controls the state of the internal UTF-8 offset caching code.
-1 for on (the default), 0 for off, -1 to debug the caching code by checking
-all its results against linear scans, and panicking on any discrepancy.
-
-=back
-
-=head2 C<readpipe> is now overridable
-
-The built-in function C<readpipe> is now overridable. Overriding it permits
-also to override its operator counterpart, C<qx//> (also known as C<``>).
-
-=head2 simple exception handling macros
-
-Perl 5.8.9 (and 5.10.0 onwards) now provides a couple of macros to do very
-basic exception handling in XS modules. You can use these macros if you call
-code that may C<croak>, but you need to do some cleanup before giving control
-back to Perl. See L<perlguts/Exception Handling> for more details.
-
-=head2 -D option enhancements
-
-=over
-
-=item *
-
-C<-Dq> suppresses the I<EXECUTING...> message when running under C<-D>
-
-=item *
-
-C<-Dl> logs runops loop entry and exit, and jump level popping.
-
-=item *
-
-C<-Dv> displays the process id as part of the trace output.
-
-=back
-
-=head2 XS-assisted SWASHGET
-
-Some pure-perl code that the regexp engine was using to retrieve Unicode
-properties and transliteration mappings has been reimplemented in XS
-for faster execution.
-(SADAHIRO Tomoyuki)
-
-=head2 Constant subroutines
-
-The interpreter internals now support a far more memory efficient form of
-inlineable constants. Storing a reference to a constant value in a symbol
-table is equivalent to a full typeglob referencing a constant subroutine,
-but using about 400 bytes less memory. This proxy constant subroutine is
-automatically upgraded to a real typeglob with subroutine if necessary.
-The approach taken is analogous to the existing space optimisation for
-subroutine stub declarations, which are stored as plain scalars in place
-of the full typeglob.
-
-However, to aid backwards compatibility of existing code, which (wrongly)
-does not expect anything other than typeglobs in symbol tables, nothing in
-core uses this feature, other than the regression tests.
-
-Stubs for prototyped subroutines have been stored in symbol tables as plain
-strings, and stubs for unprototyped subroutines as the number -1, since 5.005,
-so code which assumes that the core only places typeglobs in symbol tables
-has been making incorrect assumptions for over 10 years.
-
-=head1 New Platforms
-
-Compile support added for:
-
-=over
-
-=item *
-
-DragonFlyBSD
-
-=item *
-
-MidnightBSD
-
-=item *
-
-MirOS BSD
-
-=item *
-
-RISC OS
-
-=item *
-
-Cray XT4/Catamount
-
-=back
-
-=head1 Modules and Pragmata
-
-=head2 New Modules
-
-=over
-
-=item *
-
-C<Module::Pluggable> is a simple framework to create modules that accept
-pluggable sub-modules. The bundled version is 3.8
-
-=item *
-
-C<Module::CoreList> is a hash of hashes that is keyed on perl version as
-indicated in C<$]>. The bundled version is 2.17
-
-=item *
-
-C<Win32API::File> now available in core on Microsoft Windows. The bundled
-version is 0.1001_01
-
-=item *
-
-C<Devel::InnerPackage> finds all the packages defined by a single file. It is
-part of the C<Module::Pluggable> distribution. The bundled version is 0.3
-
-=back
-
-=head2 Updated Modules
-
-=over
-
-=item *
-
-C<attributes> upgraded to version 0.09
-
-=item *
-
-C<AutoLoader> upgraded to version 5.67
-
-=item *
-
-C<AutoSplit> upgraded to 1.06
-
-=item *
-
-C<autouse> upgraded to version 1.06
-
-=item *
-
-C<B> upgraded from 1.09_01 to 1.19
-
-=over
-
-=item *
-
-provides new pad related abstraction macros C<B::NV::COP_SEQ_RANGE_LOW>,
-C<B::NV::COP_SEQ_RANGE_HIGH>, C<B::NV::PARENT_PAD_INDEX>,
-C<B::NV::PARENT_FAKELEX_FLAGS>, which hides the difference in storage in
-5.10.0 and later.
-
-=item *
-
-provides C<B::sub_generation>, which exposes C<PL_sub_generation>
-
-=item *
-
-provides C<B::GV::isGV_with_GP>, which on pre-5.10 perls always returns true.
-
-=item *
-
-New type C<B::HE> added with methods C<VAL>, C<HASH> and C<SVKEY_force>
-
-=item *
-
-The C<B::GVf_IMPORTED_CV> flag is now set correctly when a proxy
-constant subroutine is imported.
-
-=item *
-
-bugs fixed in the handling of C<PMOP>s.
-
-=item *
-
-C<B::BM::PREVIOUS> returns now C<U32>, not C<U16>.
-C<B::CV::START> and C<B:CV::ROOT> return now C<NULL> on an XSUB,
-C<B::CV::XSUB> and C<B::CV::XSUBANY> return 0 on a non-XSUB.
-
-=back
-
-=item *
-
-C<B::C> upgraded to 1.05
-
-=item *
-
-C<B::Concise> upgraded to 0.76
-
-=over
-
-=item *
-
-new option C<-src> causes the rendering of each statement (starting with
-the nextstate OP) to be preceded by the first line of source code that
-generates it.
-
-=item *
-
-new option C<-stash="somepackage">, C<require>s "somepackage", and then renders
-each function defined in its namespace.
-
-=item *
-
-now has documentation of detailed hint symbols.
-
-=back
-
-=item *
-
-C<B::Debug> upgraded to version 1.05
-
-=item *
-
-C<B::Deparse> upgraded to version 0.87
-
-=over 4
-
-=item *
-
-properly deparse C<print readpipe $x, $y>.
-
-=item *
-
-now handles C<''->()>, C<::()>, C<sub :: {}>, I<etc.> correctly [RT #43010].
-All bugs in parsing these kinds of syntax are now fixed:
-
- perl -MO=Deparse -e '"my %h = "->()'
- perl -MO=Deparse -e '::->()'
- perl -MO=Deparse -e 'sub :: {}'
- perl -MO=Deparse -e 'package a; sub a::b::c {}'
- perl -MO=Deparse -e 'sub the::main::road {}'
-
-=item *
-
-does B<not> deparse C<$^H{v_string}>, which is automatically set by the
-internals.
-
-=back
-
-=item *
-
-C<B::Lint> upgraded to version 1.11
-
-=item *
-
-C<B::Terse> upgraded to version 1.05
-
-=item *
-
-C<base> upgraded to version 2.13
-
-=over 4
-
-=item *
-
-loading a module via base.pm would mask a global C<$SIG{__DIE__}> in that
-module.
-
-=item *
-
-push all classes at once in C<@ISA>
-
-=back
-
-=item *
-
-C<Benchmark> upgraded to version 1.10
-
-=item *
-
-C<bigint> upgraded to 0.23
-
-=item *
-
-C<bignum> upgraded to 0.23
-
-=item *
-
-C<bigrat> upgraded to 0.23
-
-=item *
-
-C<blib> upgraded to 0.04
-
-=item *
-
-C<Carp> upgraded to version 1.10
-
-The argument backtrace code now shows C<undef> as C<undef>,
-instead of a string I<"undef">.
-
-=item *
-
-C<CGI> upgraded to version 3.42
-
-=item *
-
-C<charnames> upgraded to 1.06
-
-=item *
-
-C<constant> upgraded to version 1.17
-
-=item *
-
-C<CPAN> upgraded to version 1.9301
-
-=item *
-
-C<Cwd> upgraded to version 3.29 with some platform specific
-improvements (including for VMS).
-
-=item *
-
-C<Data::Dumper> upgraded to version 2.121_17
-
-=over
-
-=item *
-
-Fixes hash iterator current position with the pure Perl version [RT #40668]
-
-=item *
-
-Performance enhancements, which will be most evident on platforms where
-repeated calls to C's C<realloc()> are slow, such as Win32.
-
-=back
-
-=item *
-
-C<DB_File> upgraded to version 1.817
-
-=item *
-
-C<DB_Filter> upgraded to version 0.02
-
-=item *
-
-C<Devel::DProf> upgraded to version 20080331.00
-
-=item *
-
-C<Devel::Peek> upgraded to version 1.04
-
-=item *
-
-C<Devel::PPPort> upgraded to version 3.14
-
-=item *
-
-C<diagnostics> upgraded to version 1.16
-
-=item *
-
-C<Digest> upgraded to version 1.15
-
-=item *
-
-C<Digest::MD5> upgraded to version 2.37
-
-=item *
-
-C<DirHandle> upgraded to version 1.02
-
-=over
-
-=item *
-
-now localises C<$.>, C<$@>, C<$!>, C<$^E>, and C<$?> before closing the
-directory handle to suppress leaking any side effects of warnings about it
-already being closed.
-
-=back
-
-=item *
-
-C<DynaLoader> upgraded to version 1.09
-
-C<DynaLoader> can now dynamically load a loadable object from a file with a
-non-default file extension.
-
-=item *
-
-C<Encode> upgraded to version 2.26
-
-C<Encode::Alias> includes a fix for encoding "646" on Solaris (better known as
-ASCII).
-
-=item *
-
-C<English> upgraded to version 1.03
-
-=item *
-
-C<Errno> upgraded to version 1.10
-
-=item *
-
-C<Exporter> upgraded to version 5.63
-
-=item *
-
-C<ExtUtils::Command> upgraded to version 1.15
-
-=item *
-
-C<ExtUtils::Constant> upgraded to version 0.21
-
-=item *
-
-C<ExtUtils::Embed> upgraded to version 1.28
-
-=item *
-
-C<ExtUtils::Install> upgraded to version 1.50_01
-
-=item *
-
-C<ExtUtils::Installed> upgraded to version 1.43
-
-=item *
-
-C<ExtUtils::MakeMaker> upgraded to version 6.48
-
-=over
-
-=item *
-
-support for C<INSTALLSITESCRIPT> and C<INSTALLVENDORSCRIPT>
-configuration.
-
-=back
-
-=item *
-
-C<ExtUtils::Manifest> upgraded to version 1.55
-
-=item *
-
-C<ExtUtils::ParseXS> upgraded to version 2.19
-
-=item *
-
-C<Fatal> upgraded to version 1.06
-
-=over
-
-=item *
-
-allows built-ins in C<CORE::GLOBAL> to be made fatal.
-
-=back
-
-=item *
-
-C<Fcntl> upgraded to version 1.06
-
-=item *
-
-C<fields> upgraded to version 2.12
-
-=item *
-
-C<File::Basename> upgraded to version 2.77
-
-=item *
-
-C<FileCache> upgraded to version 1.07
-
-=item *
-
-C<File::Compare> upgraded to 1.1005
-
-=item *
-
-C<File::Copy> upgraded to 2.13
-
-=over 4
-
-=item *
-
-now uses 3-arg open.
-
-=back
-
-=item *
-
-C<File::DosGlob> upgraded to 1.01
-
-=item *
-
-C<File::Find> upgraded to version 1.13
-
-=item *
-
-C<File::Glob> upgraded to version 1.06
-
-=over
-
-=item *
-
-fixes spurious results with brackets inside braces.
-
-=back
-
-=item *
-
-C<File::Path> upgraded to version 2.07_02
-
-=item *
-
-C<File::Spec> upgraded to version 3.29
-
-=over 4
-
-=item *
-
-improved handling of bad arguments.
-
-=item *
-
-some platform specific improvements (including for VMS and Cygwin), with
-an optimisation on C<abs2rel> when handling both relative arguments.
-
-=back
-
-=item *
-
-C<File::stat> upgraded to version 1.01
-
-=item *
-
-C<File::Temp> upgraded to version 0.20
-
-=item *
-
-C<filetest> upgraded to version 1.02
-
-=item *
-
-C<Filter::Util::Call> upgraded to version 1.07
-
-=item *
-
-C<Filter::Simple> upgraded to version 0.83
-
-=item *
-
-C<FindBin> upgraded to version 1.49
-
-=item *
-
-C<GDBM_File> upgraded to version 1.09
-
-=item *
-
-C<Getopt::Long> upgraded to version 2.37
-
-=item *
-
-C<Getopt::Std> upgraded to version 1.06
-
-=item *
-
-C<Hash::Util> upgraded to version 0.06
-
-=item *
-
-C<if> upgraded to version 0.05
-
-=item *
-
-C<IO> upgraded to version 1.23
-
-Reduced number of calls to C<getpeername> in C<IO::Socket>
-
-=item *
-
-C<IPC::Open> upgraded to version 1.03
-
-=item *
-
-C<IPC::Open3> upgraded to version 1.03
-
-=item *
-
-C<IPC::SysV> upgraded to version 2.00
-
-=item *
-
-C<lib> upgraded to version 0.61
-
-=over
-
-=item *
-
-avoid warning about loading F<.par> files.
-
-=back
-
-=item *
-
-C<libnet> upgraded to version 1.22
-
-=item *
-
-C<List::Util> upgraded to 1.19
-
-=item *
-
-C<Locale::Maketext> upgraded to 1.13
-
-=item *
-
-C<Math::BigFloat> upgraded to version 1.60
-
-=item *
-
-C<Math::BigInt> upgraded to version 1.89
-
-=item *
-
-C<Math::BigRat> upgraded to version 0.22
-
-=over 4
-
-=item *
-
-implements new C<as_float> method.
-
-=back
-
-=item *
-
-C<Math::Complex> upgraded to version 1.54.
-
-=item *
-
-C<Math::Trig> upgraded to version 1.18.
-
-=item *
-
-C<NDBM_File> upgraded to version 1.07
-
-=over
-
-=item *
-
-improve F<g++> handling for systems using GDBM compatibility headers.
-
-=back
-
-=item *
-
-C<Net::Ping> upgraded to version 2.35
-
-=item *
-
-C<NEXT> upgraded to version 0.61
-
-=over
-
-=item *
-
-fix several bugs with C<NEXT> when working with C<AUTOLOAD>, C<eval> block, and
-within overloaded stringification.
-
-=back
-
-=item *
-
-C<ODBM_File> upgraded to 1.07
-
-=item *
-
-C<open> upgraded to 1.06
-
-=item *
-
-C<ops> upgraded to 1.02
-
-=item *
-
-C<PerlIO::encoding> upgraded to version 0.11
-
-=item *
-
-C<PerlIO::scalar> upgraded to version 0.06
-
-=over 4
-
-=item *
-
-[RT #40267] C<PerlIO::scalar> doesn't respect readonly-ness.
-
-=back
-
-=item *
-
-C<PerlIO::via> upgraded to version 0.05
-
-=item *
-
-C<Pod::Html> upgraded to version 1.09
-
-=item *
-
-C<Pod::Parser> upgraded to version 1.35
-
-=item *
-
-C<Pod::Usage> upgraded to version 1.35
-
-=item *
-
-C<POSIX> upgraded to version 1.15
-
-=over
-
-=item *
-
-C<POSIX> constants that duplicate those in C<Fcntl> are now imported from
-C<Fcntl> and re-exported, rather than being duplicated by C<POSIX>
-
-=item *
-
-C<POSIX::remove> can remove empty directories.
-
-=item *
-
-C<POSIX::setlocale> safer to call multiple times.
-
-=item *
-
-C<POSIX::SigRt> added, which provides access to POSIX realtime signal
-functionality on systems that support it.
-
-=back
-
-=item *
-
-C<re> upgraded to version 0.06_01
-
-=item *
-
-C<Safe> upgraded to version 2.16
-
-=item *
-
-C<Scalar::Util> upgraded to 1.19
-
-=item *
-
-C<SDBM_File> upgraded to version 1.06
-
-=item *
-
-C<SelfLoader> upgraded to version 1.17
-
-=item *
-
-C<Shell> upgraded to version 0.72
-
-=item *
-
-C<sigtrap> upgraded to version 1.04
-
-=item *
-
-C<Socket> upgraded to version 1.81
-
-=over
-
-=item *
-
-this fixes an optimistic use of C<gethostbyname>
-
-=back
-
-=item *
-
-C<Storable> upgraded to 2.19
-
-=item *
-
-C<Switch> upgraded to version 2.13
-
-=item *
-
-C<Sys::Syslog> upgraded to version 0.27
-
-=item *
-
-C<Term::ANSIColor> upgraded to version 1.12
-
-=item *
-
-C<Term::Cap> upgraded to version 1.12
-
-=item *
-
-C<Term::ReadLine> upgraded to version 1.03
-
-=item *
-
-C<Test::Builder> upgraded to version 0.80
-
-=item *
-
-C<Test::Harness> upgraded version to 2.64
-
-=over
-
-=item *
-
-this makes it able to handle newlines.
-
-=back
-
-=item *
-
-C<Test::More> upgraded to version 0.80
-
-=item *
-
-C<Test::Simple> upgraded to version 0.80
-
-=item *
-
-C<Text::Balanced> upgraded to version 1.98
-
-=item *
-
-C<Text::ParseWords> upgraded to version 3.27
-
-=item *
-
-C<Text::Soundex> upgraded to version 3.03
-
-=item *
-
-C<Text::Tabs> upgraded to version 2007.1117
-
-=item *
-
-C<Text::Wrap> upgraded to version 2006.1117
-
-=item *
-
-C<Thread> upgraded to version 2.01
-
-=item *
-
-C<Thread::Semaphore> upgraded to version 2.09
-
-=item *
-
-C<Thread::Queue> upgraded to version 2.11
-
-=over
-
-=item *
-
-added capability to add complex structures (e.g., hash of hashes) to queues.
-
-=item *
-
-added capability to dequeue multiple items at once.
-
-=item *
-
-added new methods to inspect and manipulate queues: C<peek>, C<insert> and
-C<extract>
-
-=back
-
-=item *
-
-C<Tie::Handle> upgraded to version 4.2
-
-=item *
-
-C<Tie::Hash> upgraded to version 1.03
-
-=item *
-
-C<Tie::Memoize> upgraded to version 1.1
-
-=over
-
-=item *
-
-C<Tie::Memoize::EXISTS> now correctly caches its results.
-
-=back
-
-=item *
-
-C<Tie::RefHash> upgraded to version 1.38
-
-=item *
-
-C<Tie::Scalar> upgraded to version 1.01
-
-=item *
-
-C<Tie::StdHandle> upgraded to version 4.2
-
-=item *
-
-C<Time::gmtime> upgraded to version 1.03
-
-=item *
-
-C<Time::Local> upgraded to version 1.1901
-
-=item *
-
-C<Time::HiRes> upgraded to version 1.9715 with various build improvements
-(including VMS) and minor platform-specific bug fixes (including
-for HP-UX 11 ia64).
-
-=item *
-
-C<threads> upgraded to 1.71
-
-=over
-
-=item *
-
-new thread state information methods: C<is_running>, C<is_detached>
-and C<is_joinable>. C<list> method enhanced to return running or joinable
-threads.
-
-=item *
-
-new thread signal method: C<kill>
-
-=item *
-
-added capability to specify thread stack size.
-
-=item *
-
-added capability to control thread exiting behavior. Added a new C<exit>
-method.
-
-=back
-
-=item *
-
-C<threads::shared> upgraded to version 1.27
-
-=over
-
-=item *
-
-smaller and faster implementation that eliminates one internal structure and
-the consequent level of indirection.
-
-=item *
-
-user locks are now stored in a safer manner.
-
-=item *
-
-new function C<shared_clone> creates a copy of an object leaving
-shared elements as-is and deep-cloning non-shared elements.
-
-=item *
-
-added new C<is_shared> method.
-
-=back
-
-=item *
-
-C<Unicode::Normalize> upgraded to version 1.02
-
-=item *
-
-C<Unicode::UCD> upgraded to version 0.25
-
-=item *
-
-C<warnings> upgraded to version 1.05_01
-
-=item *
-
-C<Win32> upgraded to version 0.38
-
-=over 4
-
-=item *
-
-added new function C<GetCurrentProcessId> which returns the regular Windows
-process identifier of the current process, even when called from within a fork.
-
-=back
-
-=item *
-
-C<XSLoader> upgraded to version 0.10
-
-=item *
-
-C<XS::APItest> and C<XS::Typemap> are for internal use only and hence
-no longer installed. Many more tests have been added to C<XS::APItest>.
-
-=back
-
-=head1 Utility Changes
-
-=head2 debugger upgraded to version 1.31
-
-=over 4
-
-=item *
-
-Andreas KE<ouml>nig contributed two functions to save and load the debugger
-history.
-
-=item *
-
-C<NEXT::AUTOLOAD> no longer emits warnings under the debugger.
-
-=item *
-
-The debugger should now correctly find tty the device on OS X 10.5 and VMS
-when the program C<fork>s.
-
-=item *
-
-LVALUE subs now work inside the debugger.
-
-=back
-
-=head2 F<perlthanks>
-
-Perl 5.8.9 adds a new utility F<perlthanks>, which is a variant of F<perlbug>,
-but for sending non-bug-reports to the authors and maintainers of Perl.
-Getting nothing but bug reports can become a bit demoralising - we'll see if
-this changes things.
-
-=head2 F<perlbug>
-
-F<perlbug> now checks if you're reporting about a non-core module and suggests
-you report it to the CPAN author instead.
-
-=head2 F<h2xs>
-
-=over
-
-=item *
-
-won't define an empty string as a constant [RT #25366]
-
-=item *
-
-has examples for C<h2xs -X>
-
-=back
-
-=head2 F<h2ph>
-
-=over 4
-
-=item *
-
-now attempts to deal sensibly with the difference in path implications
-between C<""> and C<< E<lt>E<gt> >> quoting in C<#include> statements.
-
-=item *
-
-now generates correct code for C<#if defined A || defined B>
-[RT #39130]
-
-=back
-
-=head1 New Documentation
-
-As usual, the documentation received its share of corrections, clarifications
-and other nitfixes. More C<< X<...> >> tags were added for indexing.
-
-L<perlunitut> is a tutorial written by Juerd Waalboer on Unicode-related
-terminology and how to correctly handle Unicode in Perl scripts.
-
-L<perlunicode> is updated in section user defined properties.
-
-L<perluniintro> has been updated in the example of detecting data that is not
-valid in particular encoding.
-
-L<perlcommunity> provides an overview of the Perl Community along with further
-resources.
-
-L<CORE> documents the pseudo-namespace for Perl's core routines.
-
-=head1 Changes to Existing Documentation
-
-L<perlglossary> adds I<deprecated modules and features> and I<to be dropped modules>.
-
-L<perlhack> has been updated and added resources on smoke testing.
-
-The Perl FAQs (F<perlfaq1>..F<perlfaq9>) have been updated.
-
-L<perlcheat> is updated with better details on C<\w>, C<\d>, and C<\s>.
-
-L<perldebug> is updated with information on how to call the debugger.
-
-L<perldiag> documentation updated with I<subroutine with an ampersand> on the
-argument to C<exists> and C<delete> and also several terminology updates on
-warnings.
-
-L<perlfork> documents the limitation of C<exec> inside pseudo-processes.
-
-L<perlfunc>:
-
-=over
-
-=item *
-
-Documentation is fixed in section C<caller> and C<pop>.
-
-=item *
-
-Function C<alarm> now mentions C<Time::HiRes::ualarm> in preference
-to C<select>.
-
-=item *
-
-Regarding precedence in C<-X>, filetest operators are the same as unary
-operators, but not regarding parsing and parentheses (spotted by Eirik Berg
-Hanssen).
-
-=item *
-
-C<reverse> function documentation received scalar context examples.
-
-=back
-
-L<perllocale> documentation is adjusted for number localization and
-C<POSIX::setlocale> to fix Debian bug #379463.
-
-L<perlmodlib> is updated with C<CPAN::API::HOWTO> and
-C<Sys::Syslog::win32::Win32>
-
-L<perlre> documentation updated to reflect the differences between
-C<[[:xxxxx:]]> and C<\p{IsXxxxx}> matches. Also added section on C</g> and
-C</c> modifiers.
-
-L<perlreguts> describe the internals of the regular expressions engine. It has
-been contributed by Yves Orton.
-
-L<perlrebackslash> describes all perl regular expression backslash and escape
-sequences.
-
-L<perlrecharclass> describes the syntax and use of character classes in
-Perl Regular Expressions.
-
-L<perlrun> is updated to clarify on the hash seed I<PERL_HASH_SEED>. Also more
-information in options C<-x> and C<-u>.
-
-L<perlsub> example is updated to use a lexical variable for C<opendir> syntax.
-
-L<perlvar> fixes confusion about real GID C<$(> and effective GID C<$)>.
-
-Perl thread tutorial example is fixed in section
-L<perlthrtut/Queues: Passing Data Around> and L<perlthrtut>.
-
-L<perlhack> documentation extensively improved by Jarkko Hietaniemi and others.
-
-L<perltoot> provides information on modifying C<@UNIVERSAL::ISA>.
-
-L<perlport> documentation extended to include different C<kill(-9, ...)>
-semantics on Windows. It also clearly states C<dump> is not supported on Win32
-and cygwin.
-
-F<INSTALL> has been updated and modernised.
-
-=head1 Performance Enhancements
-
-=over
-
-=item *
-
-The default since perl 5.000 has been for perl to create an empty scalar
-with every new typeglob. The increased use of lexical variables means that
-most are now unused. Thanks to Nicholas Clark's efforts, Perl can now be
-compiled with C<-DPERL_DONT_CREATE_GVSV> to avoid creating these empty scalars.
-This will significantly decrease the number of scalars allocated for all
-configurations, and the number of scalars that need to be copied for ithread
-creation. Whilst this option is binary compatible with existing perl
-installations, it does change a long-standing assumption about the
-internals, hence it is not enabled by default, as some third party code may
-rely on the old behaviour.
-
-We would recommend testing with this configuration on new deployments of
-perl, particularly for multi-threaded servers, to see whether all third party
-code is compatible with it, as this configuration may give useful performance
-improvements. For existing installations we would not recommend changing to
-this configuration unless thorough testing is performed before deployment.
-
-=item *
-
-C<diagnostics> no longer uses C<$&>, which results in large speedups
-for regexp matching in all code using it.
-
-=item *
-
-Regular expressions classes of a single character are now treated the same as
-if the character had been used as a literal, meaning that code that uses
-char-classes as an escaping mechanism will see a speedup. (Yves Orton)
-
-=item *
-
-Creating anonymous array and hash references (ie. C<[]> and C<{}>) now incurs
-no more overhead than creating an anonymous list or hash. Nicholas Clark
-provided changes with a saving of two ops and one stack push, which was measured
-as a slightly better than 5% improvement for these operations.
-
-=item *
-
-Many calls to C<strlen()> have been eliminated, either because the length was
-already known, or by adopting or enhancing APIs that pass lengths. This has
-been aided by the adoption of a C<my_sprintf()> wrapper, which returns the
-correct C89 value - the length of the formatted string. Previously we could
-not rely on the return value of C<sprintf()>, because on some ancient but
-extant platforms it still returns C<char *>.
-
-=item *
-
-C<index> is now faster if the search string is stored in UTF-8 but only contains
-characters in the Latin-1 range.
-
-=item *
-
-The Unicode swatch cache inside the regexp engine is now used. (the lookup had
-a key mismatch, present since the initial implementation). [RT #42839]
-
-=back
-
-=head1 Installation and Configuration Improvements
-
-=head2 Relocatable installations
-
-There is now F<Configure> support for creating a relocatable perl tree. If
-you F<Configure> with C<-Duserelocatableinc>, then the paths in C<@INC> (and
-everything else in C<%Config>) can be optionally located via the path of the
-F<perl> executable.
-
-At start time, if any paths in C<@INC> or C<Config> that F<Configure> marked
-as relocatable (by starting them with C<".../">), then they are prefixed the
-directory of C<$^X>. This allows the relocation can be configured on a
-per-directory basis, although the default with C<-Duserelocatableinc> is that
-everything is relocated. The initial install is done to the original configured
-prefix.
-
-=head2 Configuration improvements
-
-F<Configure> is now better at removing temporary files. Tom Callaway
-(from RedHat) also contributed patches that complete the set of flags
-passed to the compiler and the linker, in particular that C<-fPIC> is now
-enabled on Linux. It will also croak when your F</dev/null> isn't a device.
-
-A new configuration variable C<d_pseudofork> has been to F<Configure>, and is
-available as C<$Config{d_pseudofork}> in the C<Config> module. This
-distinguishes real C<fork> support from the pseudofork emulation used on
-Windows platforms.
-
-F<Config.pod> and F<config.sh> are now placed correctly for cross-compilation.
-
-C<$Config{useshrplib}> is now 'true' rather than 'yes' when using a shared perl
-library.
-
-=head2 Compilation improvements
-
-Parallel makes should work properly now, although there may still be problems
-if C<make test> is instructed to run in parallel.
-
-Many compilation warnings have been cleaned up. A very stubborn compiler
-warning in C<S_emulate_eaccess()> was killed after six attempts.
-F<g++> support has been tuned, especially for FreeBSD.
-
-F<mkppport> has been integrated, and all F<ppport.h> files in the core will now
-be autogenerated at build time (and removed during cleanup).
-
-=head2 Installation improvements.
-
-F<installman> now works with C<-Duserelocatableinc> and C<DESTDIR>.
-
-F<installperl> no longer installs:
-
-=over 4
-
-=item *
-
-static library files of statically linked extensions when a shared perl library
-is being used. (They are not needed. See L</Windows> below).
-
-=item *
-
-F<SIGNATURE> and F<PAUSE*.pub> (CPAN files)
-
-=item *
-
-F<NOTES> and F<PATCHING> (ExtUtils files)
-
-=item *
-
-F<perlld> and F<ld2> (Cygwin files)
-
-=back
-
-=head2 Platform Specific Changes
-
-There are improved hints for AIX, Cygwin, DEC/OSF, FreeBSD, HP/UX, Irix 6
-Linux, MachTen, NetBSD, OS/390, QNX, SCO, Solaris, SunOS, System V Release 5.x
-(UnixWare 7, OpenUNIX 8), Ultrix, UMIPS, uts and VOS.
-
-=head3 FreeBSD
-
-=over 4
-
-=item *
-
-Drop C<-std=c89> and C<-ansi> if using C<long long> as the main integral type,
-else in FreeBSD 6.2 (and perhaps other releases), system headers do not
-declare some functions required by perl.
-
-=back
-
-=head3 Solaris
-
-=over 4
-
-=item *
-
-Starting with Solaris 10, we do not want versioned shared libraries, because
-those often indicate a private use only library. These problems could often
-be triggered when L<SUNWbdb> (Berkeley DB) was installed. Hence if Solaris 10
-is detected set C<ignore_versioned_solibs=y>.
-
-=back
-
-=head3 VMS
-
-=over 4
-
-=item *
-
-Allow IEEE math to be deselected on OpenVMS I64 (but it remains the default).
-
-=item *
-
-Record IEEE usage in C<config.h>
-
-=item *
-
-Help older VMS compilers by using C<ccflags> when building C<munchconfig.exe>.
-
-=item *
-
-Don't try to build old C<Thread> extension on VMS when C<-Duseithreads> has
-been chosen.
-
-=item *
-
-Passing a raw string of "NaN" to F<nawk> causes a core dump - so the string
-has been changed to "*NaN*"
-
-=item *
-
-F<t/op/stat.t> tests will now test hard links on VMS if they are supported.
-
-=back
-
-=head3 Windows
-
-=over 4
-
-=item *
-
-When using a shared perl library F<installperl> no longer installs static
-library files, import library files and export library files (of statically
-linked extensions) and empty bootstrap files (of dynamically linked
-extensions). This fixes a problem building PAR-Packer on Win32 with a debug
-build of perl.
-
-=item *
-
-Various improvements to the win32 build process, including support for Visual
-C++ 2005 Express Edition (aka Visual C++ 8.x).
-
-=item *
-
-F<perl.exe> will now have an icon if built with MinGW or Borland.
-
-=item *
-
-Improvements to the perl-static.exe build process.
-
-=item *
-
-Add Win32 makefile option to link all extensions statically.
-
-=item *
-
-The F<WinCE> directory has been merged into the F<Win32> directory.
-
-=item *
-
-C<setlocale> tests have been re-enabled for Windows XP onwards.
-
-=back
-
-=head1 Selected Bug Fixes
-
-=head2 Unicode
-
-Many many bugs related to the internal Unicode implementation (UTF-8) have
-been fixed. In particular, long standing bugs related to returning Unicode
-via C<tie>, overloading or C<$@> are now gone, some of which were never
-reported.
-
-C<unpack> will internally convert the string back from UTF-8 on numeric types.
-This is a compromise between the full consistency now in 5.10, and the current
-behaviour, which is often used as a "feature" on string types.
-
-Using C<:crlf> and C<UTF-16> IO layers together will now work.
-
-Fixed problems with C<split>, Unicode C</\s+/> and C</ \0/>.
-
-Fixed bug RT #40641 - encoding of Unicode characters in regular expressions.
-
-Fixed a bug where using certain patterns in a regexp led to a panic.
-[RT #45337]
-
-Perl no longer segfaults (due to infinite internal recursion) if the locale's
-character is not UTF-8 [RT #41442]:
-
- use open ':locale';
- print STDERR "\x{201e}"; # &bdquo;
-
-=head2 PerlIO
-
-Inconsistencies have been fixed in the reference counting PerlIO uses to keep
-track of Unix file descriptors, and the API used by XS code to manage getting
-and releasing C<FILE *>s
-
-=head2 Magic
-
-Several bugs have been fixed in Magic, the internal system used to implement
-features such as C<tie>, tainting and threads sharing.
-
-C<undef @array> on a tied array now correctly calls the C<CLEAR> method.
-
-Some of the bitwise ops were not checking whether their arguments were magical
-before using them. [RT #24816]
-
-Magic is no longer invoked twice by the expression C<\&$x>
-
-A bug with assigning large numbers and tainting has been resolved.
-[RT #40708]
-
-A new entry has been added to the MAGIC vtable - C<svt_local>. This is used
-when copying magic to the new value during C<local>, allowing certain problems
-with localising shared variables to be resolved.
-
-For the implementation details, see L<perlguts/Magic Virtual Tables>.
-
-=head2 Reblessing overloaded objects now works
-
-Internally, perl object-ness is on the referent, not the reference, even
-though methods can only be called via a reference. However, the original
-implementation of overloading stored flags related to overloading on the
-reference, relying on the flags being copied when the reference was copied,
-or set at the creation of a new reference. This manifests in a bug - if you
-rebless an object from a class that has overloading, into one that does not,
-then any other existing references think that they (still) point to an
-overloaded object, choose these C code paths, and then throw errors.
-Analogously, blessing into an overloaded class when other references exist will
-result in them not using overloading.
-
-The implementation has been fixed for 5.10, but this fix changes the semantics
-of flag bits, so is not binary compatible, so can't be applied to 5.8.9.
-However, 5.8.9 has a work-around that implements the same bug fix. If the
-referent has multiple references, then all the other references are located and
-corrected. A full search is avoided whenever possible by scanning lexicals
-outwards from the current subroutine, and the argument stack.
-
-A certain well known Linux vendor applied incomplete versions of this bug fix
-to their F</usr/bin/perl> and then prematurely closed bug reports about
-performance issues without consulting back upstream. This not being enough,
-they then proceeded to ignore the necessary fixes to these unreleased changes
-for 11 months, until massive pressure was applied by their long-suffering
-paying customers, catalysed by the failings being featured on a prominent blog
-and Slashdot.
-
-=head2 C<strict> now propagates correctly into string evals
-
-Under 5.8.8 and earlier:
-
- $ perl5.8.8 -e 'use strict; eval "use foo bar" or die $@'
- Can't locate foo.pm in @INC (@INC contains: ... .) at (eval 1) line 2.
- BEGIN failed--compilation aborted at (eval 1) line 2.
-
-Under 5.8.9 and later:
-
- $ perl5.8.9 -e 'use strict; eval "use foo bar" or die $@'
- Bareword "bar" not allowed while "strict subs" in use at (eval 1) line 1.
-
-This may cause problems with programs that parse the error message and rely
-on the buggy behaviour.
-
-=head2 Other fixes
-
-=over
-
-=item *
-
-The tokenizer no longer treats C<=cute> (and other words beginning
-with C<=cut>) as a synonym for C<=cut>.
-
-=item *
-
-Calling C<CORE::require>
-
-C<CORE::require> and C<CORE::do> were always parsed as C<require> and C<do>
-when they were overridden. This is now fixed.
-
-=item *
-
-Stopped memory leak on long F</etc/groups> entries.
-
-=item *
-
-C<while (my $x ...) { ...; redo }> shouldn't C<undef $x>.
-
-In the presence of C<my> in the conditional of a C<while()>, C<until()>,
-or C<for(;;)> loop, we now add an extra scope to the body so that C<redo>
-doesn't C<undef> the lexical.
-
-=item *
-
-The C<encoding> pragma now correctly ignores anything following an C<@>
-character in the C<LC_ALL> and C<LANG> environment variables. [RT # 49646]
-
-=item *
-
-A segfault observed with some F<gcc> 3.3 optimisations is resolved.
-
-=item *
-
-A possible segfault when C<unpack> used in scalar context with C<()> groups
-is resolved. [RT #50256]
-
-=item *
-
-Resolved issue where C<$!> could be changed by a signal handler interrupting
-a C<system> call.
-
-=item *
-
-Fixed bug RT #37886, symbolic dereferencing was allowed in the argument of
-C<defined> even under the influence of C<use strict 'refs'>.
-
-=item *
-
-Fixed bug RT #43207, where C<lc>/C<uc> inside C<sort> affected the return
-value.
-
-=item *
-
-Fixed bug RT #45607, where C<*{"BONK"} = \&{"BONK"}> didn't work correctly.
-
-=item *
-
-Fixed bug RT #35878, croaking from a XSUB called via C<goto &xsub> corrupts perl
-internals.
-
-=item *
-
-Fixed bug RT #32539, F<DynaLoader.o> is moved into F<libperl.so> to avoid the
-need to statically link DynaLoader into the stub perl executable. With this
-F<libperl.so> provides everything needed to get a functional embedded perl
-interpreter to run.
-
-=item *
-
-Fix bug RT #36267 so that assigning to a tied hash doesn't change the
-underlying hash.
-
-=item *
-
-Fix bug RT #6006, regexp replaces using large replacement variables
-fail some of the time, I<i.e.> when substitution contains something
-like C<${10}> (note the bracket) instead of just C<$10>.
-
-=item *
-
-Fix bug RT #45053, C<Perl_newCONSTSUB()> is now thread safe.
-
-=back
-
-=head2 Platform Specific Fixes
-
-=head3 Darwin / MacOS X
-
-=over 4
-
-=item *
-
-Various improvements to 64 bit builds.
-
-=item *
-
-Mutex protection added in C<PerlIOStdio_close()> to avoid race conditions.
-Hopefully this fixes failures in the threads tests F<free.t> and F<blocks.t>.
-
-=item *
-
-Added forked terminal support to the debugger, with the ability to update the
-window title.
-
-=back
-
-=head3 OS/2
-
-=over 4
-
-=item *
-
-A build problem with specifying C<USE_MULTI> and C<USE_ITHREADS> but without
-C<USE_IMP_SYS> has been fixed.
-
-=item *
-
-C<OS2::REXX> upgraded to version 1.04
-
-=back
-
-=head3 Tru64
-
-=over 4
-
-=item *
-
-Aligned floating point build policies for F<cc> and F<gcc>.
-
-=back
-
-=head3 RedHat Linux
-
-=over 4
-
-=item *
-
-Revisited a patch from 5.6.1 for RH7.2 for Intel's F<icc> [RT #7916], added an
-additional check for C<$Config{gccversion}>.
-
-=back
-
-=head3 Solaris/i386
-
-=over 4
-
-=item *
-
-Use C<-DPTR_IS_LONG> when using 64 bit integers
-
-=back
-
-=head3 VMS
-
-=over 4
-
-=item *
-
-Fixed C<PerlIO::Scalar> in-memory file record-style reads.
-
-=item *
-
-pipe shutdown at process exit should now be more robust.
-
-=item *
-
-Bugs in VMS exit handling tickled by C<Test::Harness> 2.64 have been fixed.
-
-=item *
-
-Fix C<fcntl()> locking capability test in F<configure.com>.
-
-=item *
-
-Replaced C<shrplib='define'> with C<useshrplib='true'> on VMS.
-
-=back
-
-=head3 Windows
-
-=over 4
-
-=item *
-
-C<File::Find> used to fail when the target directory is a bare drive letter and
-C<no_chdir> is 1 (the default is 0). [RT #41555]
-
-=item *
-
-A build problem with specifying C<USE_MULTI> and C<USE_ITHREADS> but without
-C<USE_IMP_SYS> has been fixed.
-
-=item *
-
-The process id is no longer truncated to 16 bits on some Windows platforms
-( http://bugs.activestate.com/show_bug.cgi?id=72443 )
-
-=item *
-
-Fixed bug RT #54828 in F<perlio.c> where calling C<binmode> on Win32 and Cygwin
-may cause a segmentation fault.
-
-=back
-
-=head2 Smaller fixes
-
-=over 4
-
-=item *
-
-It is now possible to overload C<eq> when using C<nomethod>.
-
-=item *
-
-Various problems using C<overload> with 64 bit integers corrected.
-
-=item *
-
-The reference count of C<PerlIO> file descriptors is now correctly handled.
-
-=item *
-
-On VMS, escaped dots will be preserved when converted to Unix syntax.
-
-=item *
-
-C<keys %+> no longer throws an C<'ambiguous'> warning.
-
-=item *
-
-Using C<#!perl -d> could trigger an assertion, which has been fixed.
-
-=item *
-
-Don't stringify tied code references in C<@INC> when calling C<require>.
-
-=item *
-
-Code references in C<@INC> report the correct file name when C<__FILE__> is
-used.
-
-=item *
-
-Width and precision in sprintf didn't handle characters above 255 correctly.
-[RT #40473]
-
-=item *
-
-List slices with indices out of range now work more consistently.
-[RT #39882]
-
-=item *
-
-A change introduced with perl 5.8.1 broke the parsing of arguments of the form
-C<-foo=bar> with the C<-s> on the <#!> line. This has been fixed. See
-http://bugs.activestate.com/show_bug.cgi?id=43483
-
-=item *
-
-C<tr///> is now threadsafe. Previously it was storing a swash inside its OP,
-rather than in a pad.
-
-=item *
-
-F<pod2html> labels anchors more consistently and handles nested definition
-lists better.
-
-=item *
-
-C<threads> cleanup veto has been extended to include C<perl_free()> and
-C<perl_destruct()>
-
-=item *
-
-On some systems, changes to C<$ENV{TZ}> would not always be
-respected by the underlying calls to C<localtime_r()>. Perl now
-forces the inspection of the environment on these systems.
-
-=item *
-
-The special variable C<$^R> is now more consistently set when executing
-regexps using the C<(?{...})> construct. In particular, it will still
-be set even if backreferences or optional sub-patterns C<(?:...)?> are
-used.
-
-=back
-
-=head1 New or Changed Diagnostics
-
-=head2 panic: sv_chop %s
-
-This new fatal error occurs when the C routine C<Perl_sv_chop()> was passed a
-position that is not within the scalar's string buffer. This is caused by
-buggy XS code, and at this point recovery is not possible.
-
-=head2 Maximal count of pending signals (%s) exceeded
-
-This new fatal error occurs when the perl process has to abort due to
-too many pending signals, which is bound to prevent perl from being
-able to handle further incoming signals safely.
-
-=head2 panic: attempt to call %s in %s
-
-This new fatal error occurs when the ACL version file test operator is used
-where it is not available on the current platform. Earlier checks mean that
-it should never be possible to get this.
-
-=head2 FETCHSIZE returned a negative value
-
-New error indicating that a tied array has claimed to have a negative
-number of elements.
-
-=head2 Can't upgrade %s (%d) to %d
-
-Previously the internal error from the SV upgrade code was the less informative
-I<Can't upgrade that kind of scalar>. It now reports the current internal type,
-and the new type requested.
-
-=head2 %s argument is not a HASH or ARRAY element or a subroutine
-
-This error, thrown if an invalid argument is provided to C<exists> now
-correctly includes "or a subroutine". [RT #38955]
-
-=head2 Cannot make the non-overridable builtin %s fatal
-
-This error in C<Fatal> previously did not show the name of the builtin in
-question (now represented by %s above).
-
-=head2 Unrecognized character '%s' in column %d
-
-This error previously did not state the column.
-
-=head2 Offset outside string
-
-This can now also be generated by a C<seek> on a file handle using
-C<PerlIO::scalar>.
-
-=head2 Invalid escape in the specified encoding in regexp; marked by <-- HERE in m/%s/
-
-New error, introduced as part of the fix to RT #40641 to handle encoding
-of Unicode characters in regular expression comments.
-
-=head2 Your machine doesn't support dump/undump.
-
-A more informative fatal error issued when calling C<dump> on Win32 and
-Cygwin. (Given that the purpose of C<dump> is to abort with a core dump,
-and core dumps can't be produced on these platforms, this is more useful than
-silently exiting.)
-
-=head1 Changed Internals
-
-The perl sources can now be compiled with a C++ compiler instead of a C
-compiler. A necessary implementation details is that under C++, the macro
-C<XS> used to define XSUBs now includes an C<extern "C"> definition. A side
-effect of this is that B<C++> code that used the construction
-
- typedef XS(SwigPerlWrapper);
-
-now needs to be written
-
- typedef XSPROTO(SwigPerlWrapper);
-
-using the new C<XSPROTO> macro, in order to compile. C extensions are
-unaffected, although C extensions are encouraged to use C<XSPROTO> too.
-This change was present in the 5.10.0 release of perl, so any actively
-maintained code that happened to use this construction should already have
-been adapted. Code that needs changing will fail with a compilation error.
-
-C<set> magic on localizing/assigning to a magic variable will now only
-trigger for I<container magics>, i.e. it will for C<%ENV> or C<%SIG>
-but not for C<$#array>.
-
-The new API macro C<newSVpvs()> can be used in place of constructions such as
-C<newSVpvn("ISA", 3)>. It takes a single string constant, and at C compile
-time determines its length.
-
-The new API function C<Perl_newSV_type()> can be used as a more efficient
-replacement of the common idiom
-
- sv = newSV(0);
- sv_upgrade(sv, type);
-
-Similarly C<Perl_newSVpvn_flags()> can be used to combine
-C<Perl_newSVpv()> with C<Perl_sv_2mortal()> or the equivalent
-C<Perl_sv_newmortal()> with C<Perl_sv_setpvn()>
-
-Two new macros C<mPUSHs()> and C<mXPUSHs()> are added, to make it easier to
-push mortal SVs onto the stack. They were then used to fix several bugs where
-values on the stack had not been mortalised.
-
-A C<Perl_signbit()> function was added to test the sign of an C<NV>. It
-maps to the system one when available.
-
-C<Perl_av_reify()>, C<Perl_lex_end()>, C<Perl_mod()>, C<Perl_op_clear()>,
-C<Perl_pop_return()>, C<Perl_qerror()>, C<Perl_setdefout()>,
-C<Perl_vivify_defelem()> and C<Perl_yylex()> are now visible to extensions.
-This was required to allow C<Data::Alias> to work on Windows.
-
-C<Perl_find_runcv()> is now visible to perl core extensions. This was required
-to allow C<Sub::Current> to work on Windows.
-
-C<ptr_table*> functions are now available in unthreaded perl. C<Storable>
-takes advantage of this.
-
-There have been many small cleanups made to the internals. In particular,
-C<Perl_sv_upgrade()> has been simplified considerably, with a straight-through
-code path that uses C<memset()> and C<memcpy()> to initialise the new body,
-rather than assignment via multiple temporary variables. It has also
-benefited from simplification and de-duplication of the arena management
-code.
-
-A lot of small improvements in the code base were made due to reports from
-the Coverity static code analyzer.
-
-Corrected use and documentation of C<Perl_gv_stashpv()>, C<Perl_gv_stashpvn()>,
-C<Perl_gv_stashsv()> functions (last parameter is a bitmask, not boolean).
-
-C<PERL_SYS_INIT>, C<PERL_SYS_INIT3> and C<PERL_SYS_TERM> macros have been
-changed into functions.
-
-C<PERLSYS_TERM> no longer requires a context. C<PerlIO_teardown()>
-is now called without a context, and debugging output in this function has
-been disabled because that required that an interpreter was present, an invalid
-assumption at termination time.
-
-All compile time options which affect binary compatibility have been grouped
-together into a global variable (C<PL_bincompat_options>).
-
-The values of C<PERL_REVISION>, C<PERL_VERSION> and C<PERL_SUBVERSION> are
-now baked into global variables (and hence into any shared perl library).
-Additionally under C<MULTIPLICITY>, the perl executable now records the size of
-the interpreter structure (total, and for this version). Coupled with
-C<PL_bincompat_options> this will allow 5.8.10 (and later), when compiled with a
-shared perl library, to perform sanity checks in C<main()> to verify that the
-shared library is indeed binary compatible.
-
-Symbolic references can now have embedded NULs. The new public function
-C<Perl_get_cvn_flags()> can be used in extensions if you have to handle them.
-
-=head2 Macro cleanups
-
-The core code, and XS code in F<ext> that is not dual-lived on CPAN, no longer
-uses the macros C<PL_na>, C<NEWSV()>, C<Null()>, C<Nullav>, C<Nullcv>,
-C<Nullhv>, C<Nullhv> I<etc>. Their use is discouraged in new code,
-particularly C<PL_na>, which is a small performance hit.
-
-=head1 New Tests
-
-Many modules updated from CPAN incorporate new tests. Some core specific
-tests have been added:
-
-=over 4
-
-=item ext/DynaLoader/t/DynaLoader.t
-
-Tests for the C<DynaLoader> module.
-
-=item t/comp/fold.t
-
-Tests for compile-time constant folding.
-
-=item t/io/pvbm.t
-
-Tests incorporated from 5.10.0 which check that there is no unexpected
-interaction between the internal types C<PVBM> and C<PVGV>.
-
-=item t/lib/proxy_constant_subs.t
-
-Tests for the new form of constant subroutines.
-
-=item t/op/attrhand.t
-
-Tests for C<Attribute::Handlers>.
-
-=item t/op/dbm.t
-
-Tests for C<dbmopen>.
-
-=item t/op/inccode-tie.t
-
-Calls all tests in F<t/op/inccode.t> after first tying C<@INC>.
-
-=item t/op/incfilter.t
-
-Tests for source filters returned from code references in C<@INC>.
-
-=item t/op/kill0.t
-
-Tests for RT #30970.
-
-=item t/op/qrstack.t
-
-Tests for RT #41484.
-
-=item t/op/qr.t
-
-Tests for the C<qr//> construct.
-
-=item t/op/regexp_qr_embed.t
-
-Tests for the C<qr//> construct within another regexp.
-
-=item t/op/regexp_qr.t
-
-Tests for the C<qr//> construct.
-
-=item t/op/rxcode.t
-
-Tests for RT #32840.
-
-=item t/op/studytied.t
-
-Tests for C<study> on tied scalars.
-
-=item t/op/substT.t
-
-Tests for C<subst> run under C<-T> mode.
-
-=item t/op/symbolcache.t
-
-Tests for C<undef> and C<delete> on stash entries that are bound to
-subroutines or methods.
-
-=item t/op/upgrade.t
-
-Tests for C<Perl_sv_upgrade()>.
-
-=item t/mro/package_aliases.t
-
-MRO tests for C<isa> and package aliases.
-
-=item t/pod/twice.t
-
-Tests for calling C<Pod::Parser> twice.
-
-=item t/run/cloexec.t
-
-Tests for inheriting file descriptors across C<exec> (close-on-exec).
-
-=item t/uni/cache.t
-
-Tests for the UTF-8 caching code.
-
-=item t/uni/chr.t
-
-Test that strange encodings do not upset C<Perl_pp_chr()>.
-
-=item t/uni/greek.t
-
-Tests for RT #40641.
-
-=item t/uni/latin2.t
-
-Tests for RT #40641.
-
-=item t/uni/overload.t
-
-Tests for returning Unicode from overloaded values.
-
-=item t/uni/tie.t
-
-Tests for returning Unicode from tied variables.
-
-=back
-
-=head1 Known Problems
-
-There are no known new bugs.
-
-However, programs that rely on bugs that have been fixed will have problems.
-Also, many bug fixes present in 5.10.0 can't be back-ported to the 5.8.x
-branch, because they require changes that are binary incompatible, or because
-the code changes are too large and hence too risky to incorporate.
-
-We have only limited volunteer labour, and the maintenance burden is
-getting increasingly complex. Hence this will be the last significant
-release of the 5.8.x series. Any future releases of 5.8.x will likely
-only be to deal with security issues, and platform build
-failures. Hence you should look to migrating to 5.10.x, if you have
-not started already. Alternatively, if business requirements constrain
-you to continue to use 5.8.x, you may wish to consider commercial
-support from firms such as ActiveState.
-
-=head1 Platform Specific Notes
-
-=head2 Win32
-
-C<readdir()>, C<cwd()>, C<$^X> and C<@INC> now use the alternate (short)
-filename if the long name is outside the current codepage (Jan Dubois).
-
-=head3 Updated Modules
-
-=over 4
-
-=item *
-
-C<Win32> upgraded to version 0.38. Now has a documented 'WinVista' response
-from C<GetOSName> and support for Vista's privilege elevation in C<IsAdminUser>.
-Support for Unicode characters in path names. Improved cygwin and Win64
-compatibility.
-
-=item *
-
-C<Win32API> updated to 0.1001_01
-
-=item *
-
-C<killpg()> support added to C<MSWin32> (Jan Dubois).
-
-=item *
-
-C<File::Spec::Win32> upgraded to version 3.2701
-
-=back
-
-=head2 OS/2
-
-=head3 Updated Modules
-
-=over 4
-
-=item *
-
-C<OS2::Process> upgraded to 1.03
-
-Ilya Zakharevich has added and documented several C<Window*> and C<Clipbrd*>
-functions.
-
-=item *
-
-C<OS2::REXX::DLL>, C<OS2::REXX> updated to version 1.03
-
-=back
-
-=head2 VMS
-
-=head3 Updated Modules
-
-=over 4
-
-=item *
-
-C<DCLsym> upgraded to version 1.03
-
-=item *
-
-C<Stdio> upgraded to version 2.4
-
-=item *
-
-C<VMS::XSSymSet> upgraded to 1.1.
-
-=back
-
-=head1 Obituary
-
-Nick Ing-Simmons, long time Perl hacker, author of the C<Tk> and C<Encode>
-modules, F<perlio.c> in the core, and 5.003_02 pumpking, died of a heart
-attack on 25th September 2006. He will be missed.
-
-=head1 Acknowledgements
-
-Some of the work in this release was funded by a TPF grant.
-
-Steve Hay worked behind the scenes working out the causes of the differences
-between core modules, their CPAN releases, and previous core releases, and
-the best way to rectify them. He doesn't want to do it again. I know this
-feeling, and I'm very glad he did it this time, instead of me.
-
-Paul Fenwick assembled a team of 18 volunteers, who broke the back of writing
-this document. In particular, Bradley Dean, Eddy Tan, and Vincent Pit
-provided half the team's contribution.
-
-Schwern verified the list of updated module versions, correcting quite a few
-errors that I (and everyone else) had missed, both wrongly stated module
-versions, and changed modules that had not been listed.
-
-The crack Berlin-based QA team of Andreas KE<ouml>nig and Slaven Rezic
-tirelessly re-built snapshots, tested most everything CPAN against
-them, and then identified the changes responsible for any module regressions,
-ensuring that several show-stopper bugs were stomped before the first release
-candidate was cut.
-
-The other core committers contributed most of the changes, and applied most
-of the patches sent in by the hundreds of contributors listed in F<AUTHORS>.
-
-And obviously, Larry Wall, without whom we wouldn't have Perl.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://bugs.perl.org. There may also be
-information at http://www.perl.org, the Perl Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team. You can browse and search
-the Perl 5 bugs at http://bugs.perl.org/
-
-If the bug you are reporting has security implications, which make it
-inappropriate to send to a publicly archived mailing list, then please send
-it to perl5-security-report@perl.org. This points to a closed subscription
-unarchived mailing list, which includes
-all the core committers, who will be able
-to help assess the impact of issues, figure out a resolution, and help
-co-ordinate the release of patches to mitigate or fix the problem across all
-platforms on which Perl is supported. Please only use this address for security
-issues in the Perl core, not for modules independently distributed on CPAN.
-
-=head1 SEE ALSO
-
-The F<Changes> file for exhaustive details on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perl58delta.pod b/Master/tlpkg/tlperl/lib/pods/perl58delta.pod
deleted file mode 100644
index 0612ca6bae9..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perl58delta.pod
+++ /dev/null
@@ -1,3746 +0,0 @@
-=head1 NAME
-
-perl58delta - what is new for perl v5.8.0
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.6.0 release and
-the 5.8.0 release.
-
-Many of the bug fixes in 5.8.0 were already seen in the 5.6.1
-maintenance release since the two releases were kept closely
-coordinated (while 5.8.0 was still called 5.7.something).
-
-Changes that were integrated into the 5.6.1 release are marked C<[561]>.
-Many of these changes have been further developed since 5.6.1 was released,
-those are marked C<[561+]>.
-
-You can see the list of changes in the 5.6.1 release (both from the
-5.005_03 release and the 5.6.0 release) by reading L<perl561delta>.
-
-=head1 Highlights In 5.8.0
-
-=over 4
-
-=item *
-
-Better Unicode support
-
-=item *
-
-New IO Implementation
-
-=item *
-
-New Thread Implementation
-
-=item *
-
-Better Numeric Accuracy
-
-=item *
-
-Safe Signals
-
-=item *
-
-Many New Modules
-
-=item *
-
-More Extensive Regression Testing
-
-=back
-
-=head1 Incompatible Changes
-
-=head2 Binary Incompatibility
-
-B<Perl 5.8 is not binary compatible with earlier releases of Perl.>
-
-B<You have to recompile your XS modules.>
-
-(Pure Perl modules should continue to work.)
-
-The major reason for the discontinuity is the new IO architecture
-called PerlIO. PerlIO is the default configuration because without
-it many new features of Perl 5.8 cannot be used. In other words:
-you just have to recompile your modules containing XS code, sorry
-about that.
-
-In future releases of Perl, non-PerlIO aware XS modules may become
-completely unsupported. This shouldn't be too difficult for module
-authors, however: PerlIO has been designed as a drop-in replacement
-(at the source code level) for the stdio interface.
-
-Depending on your platform, there are also other reasons why
-we decided to break binary compatibility, please read on.
-
-=head2 64-bit platforms and malloc
-
-If your pointers are 64 bits wide, the Perl malloc is no longer being
-used because it does not work well with 8-byte pointers. Also,
-usually the system mallocs on such platforms are much better optimized
-for such large memory models than the Perl malloc. Some memory-hungry
-Perl applications like the PDL don't work well with Perl's malloc.
-Finally, other applications than Perl (such as mod_perl) tend to prefer
-the system malloc. Such platforms include Alpha and 64-bit HPPA,
-MIPS, PPC, and Sparc.
-
-=head2 AIX Dynaloading
-
-The AIX dynaloading now uses in AIX releases 4.3 and newer the native
-dlopen interface of AIX instead of the old emulated interface. This
-change will probably break backward compatibility with compiled
-modules. The change was made to make Perl more compliant with other
-applications like mod_perl which are using the AIX native interface.
-
-=head2 Attributes for C<my> variables now handled at run-time
-
-The C<my EXPR : ATTRS> syntax now applies variable attributes at
-run-time. (Subroutine and C<our> variables still get attributes applied
-at compile-time.) See L<attributes> for additional details. In particular,
-however, this allows variable attributes to be useful for C<tie> interfaces,
-which was a deficiency of earlier releases. Note that the new semantics
-doesn't work with the Attribute::Handlers module (as of version 0.76).
-
-=head2 Socket Extension Dynamic in VMS
-
-The Socket extension is now dynamically loaded instead of being
-statically built in. This may or may not be a problem with ancient
-TCP/IP stacks of VMS: we do not know since we weren't able to test
-Perl in such configurations.
-
-=head2 IEEE-format Floating Point Default on OpenVMS Alpha
-
-Perl now uses IEEE format (T_FLOAT) as the default internal floating
-point format on OpenVMS Alpha, potentially breaking binary compatibility
-with external libraries or existing data. G_FLOAT is still available as
-a configuration option. The default on VAX (D_FLOAT) has not changed.
-
-=head2 New Unicode Semantics (no more C<use utf8>, almost)
-
-Previously in Perl 5.6 to use Unicode one would say "use utf8" and
-then the operations (like string concatenation) were Unicode-aware
-in that lexical scope.
-
-This was found to be an inconvenient interface, and in Perl 5.8 the
-Unicode model has completely changed: now the "Unicodeness" is bound
-to the data itself, and for most of the time "use utf8" is not needed
-at all. The only remaining use of "use utf8" is when the Perl script
-itself has been written in the UTF-8 encoding of Unicode. (UTF-8 has
-not been made the default since there are many Perl scripts out there
-that are using various national eight-bit character sets, which would
-be illegal in UTF-8.)
-
-See L<perluniintro> for the explanation of the current model,
-and L<utf8> for the current use of the utf8 pragma.
-
-=head2 New Unicode Properties
-
-Unicode I<scripts> are now supported. Scripts are similar to (and superior
-to) Unicode I<blocks>. The difference between scripts and blocks is that
-scripts are the glyphs used by a language or a group of languages, while
-the blocks are more artificial groupings of (mostly) 256 characters based
-on the Unicode numbering.
-
-In general, scripts are more inclusive, but not universally so. For
-example, while the script C<Latin> includes all the Latin characters and
-their various diacritic-adorned versions, it does not include the various
-punctuation or digits (since they are not solely C<Latin>).
-
-A number of other properties are now supported, including C<\p{L&}>,
-C<\p{Any}> C<\p{Assigned}>, C<\p{Unassigned}>, C<\p{Blank}> [561] and
-C<\p{SpacePerl}> [561] (along with their C<\P{...}> versions, of course).
-See L<perlunicode> for details, and more additions.
-
-The C<In> or C<Is> prefix to names used with the C<\p{...}> and C<\P{...}>
-are now almost always optional. The only exception is that a C<In> prefix
-is required to signify a Unicode block when a block name conflicts with a
-script name. For example, C<\p{Tibetan}> refers to the script, while
-C<\p{InTibetan}> refers to the block. When there is no name conflict, you
-can omit the C<In> from the block name (e.g. C<\p{BraillePatterns}>), but
-to be safe, it's probably best to always use the C<In>).
-
-=head2 REF(...) Instead Of SCALAR(...)
-
-A reference to a reference now stringifies as "REF(0x81485ec)" instead
-of "SCALAR(0x81485ec)" in order to be more consistent with the return
-value of ref().
-
-=head2 pack/unpack D/F recycled
-
-The undocumented pack/unpack template letters D/F have been recycled
-for better use: now they stand for long double (if supported by the
-platform) and NV (Perl internal floating point type). (They used
-to be aliases for d/f, but you never knew that.)
-
-=head2 glob() now returns filenames in alphabetical order
-
-The list of filenames from glob() (or <...>) is now by default sorted
-alphabetically to be csh-compliant (which is what happened before
-in most Unix platforms). (bsd_glob() does still sort platform
-natively, ASCII or EBCDIC, unless GLOB_ALPHASORT is specified.) [561]
-
-=head2 Deprecations
-
-=over 4
-
-=item *
-
-The semantics of bless(REF, REF) were unclear and until someone proves
-it to make some sense, it is forbidden.
-
-=item *
-
-The obsolete chat2 library that should never have been allowed
-to escape the laboratory has been decommissioned.
-
-=item *
-
-Using chdir("") or chdir(undef) instead of explicit chdir() is
-doubtful. A failure (think chdir(some_function()) can lead into
-unintended chdir() to the home directory, therefore this behaviour
-is deprecated.
-
-=item *
-
-The builtin dump() function has probably outlived most of its
-usefulness. The core-dumping functionality will remain in future
-available as an explicit call to C<CORE::dump()>, but in future
-releases the behaviour of an unqualified C<dump()> call may change.
-
-=item *
-
-The very dusty examples in the eg/ directory have been removed.
-Suggestions for new shiny examples welcome but the main issue is that
-the examples need to be documented, tested and (most importantly)
-maintained.
-
-=item *
-
-The (bogus) escape sequences \8 and \9 now give an optional warning
-("Unrecognized escape passed through"). There is no need to \-escape
-any C<\w> character.
-
-=item *
-
-The *glob{FILEHANDLE} is deprecated, use *glob{IO} instead.
-
-=item *
-
-The C<package;> syntax (C<package> without an argument) has been
-deprecated. Its semantics were never that clear and its
-implementation even less so. If you have used that feature to
-disallow all but fully qualified variables, C<use strict;> instead.
-
-=item *
-
-The unimplemented POSIX regex features [[.cc.]] and [[=c=]] are still
-recognised but now cause fatal errors. The previous behaviour of
-ignoring them by default and warning if requested was unacceptable
-since it, in a way, falsely promised that the features could be used.
-
-=item *
-
-In future releases, non-PerlIO aware XS modules may become completely
-unsupported. Since PerlIO is a drop-in replacement for stdio at the
-source code level, this shouldn't be that drastic a change.
-
-=item *
-
-Previous versions of perl and some readings of some sections of Camel
-III implied that the C<:raw> "discipline" was the inverse of C<:crlf>.
-Turning off "clrfness" is no longer enough to make a stream truly
-binary. So the PerlIO C<:raw> layer (or "discipline", to use the Camel
-book's older terminology) is now formally defined as being equivalent
-to binmode(FH) - which is in turn defined as doing whatever is
-necessary to pass each byte as-is without any translation. In
-particular binmode(FH) - and hence C<:raw> - will now turn off both
-CRLF and UTF-8 translation and remove other layers (e.g. :encoding())
-which would modify byte stream.
-
-=item *
-
-The current user-visible implementation of pseudo-hashes (the weird
-use of the first array element) is deprecated starting from Perl 5.8.0
-and will be removed in Perl 5.10.0, and the feature will be
-implemented differently. Not only is the current interface rather
-ugly, but the current implementation slows down normal array and hash
-use quite noticeably. The C<fields> pragma interface will remain
-available. The I<restricted hashes> interface is expected to
-be the replacement interface (see L<Hash::Util>). If your existing
-programs depends on the underlying implementation, consider using
-L<Class::PseudoHash> from CPAN.
-
-=item *
-
-The syntaxes C<< @a->[...] >> and C<< %h->{...} >> have now been deprecated.
-
-=item *
-
-After years of trying, suidperl is considered to be too complex to
-ever be considered truly secure. The suidperl functionality is likely
-to be removed in a future release.
-
-=item *
-
-The 5.005 threads model (module C<Thread>) is deprecated and expected
-to be removed in Perl 5.10. Multithreaded code should be migrated to
-the new ithreads model (see L<threads>, L<threads::shared> and
-L<perlthrtut>).
-
-=item *
-
-The long deprecated uppercase aliases for the string comparison
-operators (EQ, NE, LT, LE, GE, GT) have now been removed.
-
-=item *
-
-The tr///C and tr///U features have been removed and will not return;
-the interface was a mistake. Sorry about that. For similar
-functionality, see pack('U0', ...) and pack('C0', ...). [561]
-
-=item *
-
-Earlier Perls treated "sub foo (@bar)" as equivalent to "sub foo (@)".
-The prototypes are now checked better at compile-time for invalid
-syntax. An optional warning is generated ("Illegal character in
-prototype...") but this may be upgraded to a fatal error in a future
-release.
-
-=item *
-
-The C<exec LIST> and C<system LIST> operations now produce warnings on
-tainted data and in some future release they will produce fatal errors.
-
-=item *
-
-The existing behaviour when localising tied arrays and hashes is wrong,
-and will be changed in a future release, so do not rely on the existing
-behaviour. See L<"Localising Tied Arrays and Hashes Is Broken">.
-
-=back
-
-=head1 Core Enhancements
-
-=head2 Unicode Overhaul
-
-Unicode in general should be now much more usable than in Perl 5.6.0
-(or even in 5.6.1). Unicode can be used in hash keys, Unicode in
-regular expressions should work now, Unicode in tr/// should work now,
-Unicode in I/O should work now. See L<perluniintro> for introduction
-and L<perlunicode> for details.
-
-=over 4
-
-=item *
-
-The Unicode Character Database coming with Perl has been upgraded
-to Unicode 3.2.0. For more information, see http://www.unicode.org/ .
-[561+] (5.6.1 has UCD 3.0.1.)
-
-=item *
-
-For developers interested in enhancing Perl's Unicode capabilities:
-almost all the UCD files are included with the Perl distribution in
-the F<lib/unicore> subdirectory. The most notable omission, for space
-considerations, is the Unihan database.
-
-=item *
-
-The properties \p{Blank} and \p{SpacePerl} have been added. "Blank" is like
-C isblank(), that is, it contains only "horizontal whitespace" (the space
-character is, the newline isn't), and the "SpacePerl" is the Unicode
-equivalent of C<\s> (\p{Space} isn't, since that includes the vertical
-tabulator character, whereas C<\s> doesn't.)
-
-See "New Unicode Properties" earlier in this document for additional
-information on changes with Unicode properties.
-
-=back
-
-=head2 PerlIO is Now The Default
-
-=over 4
-
-=item *
-
-IO is now by default done via PerlIO rather than system's "stdio".
-PerlIO allows "layers" to be "pushed" onto a file handle to alter the
-handle's behaviour. Layers can be specified at open time via 3-arg
-form of open:
-
- open($fh,'>:crlf :utf8', $path) || ...
-
-or on already opened handles via extended C<binmode>:
-
- binmode($fh,':encoding(iso-8859-7)');
-
-The built-in layers are: unix (low level read/write), stdio (as in
-previous Perls), perlio (re-implementation of stdio buffering in a
-portable manner), crlf (does CRLF <=> "\n" translation as on Win32,
-but available on any platform). A mmap layer may be available if
-platform supports it (mostly Unixes).
-
-Layers to be applied by default may be specified via the 'open' pragma.
-
-See L</"Installation and Configuration Improvements"> for the effects
-of PerlIO on your architecture name.
-
-=item *
-
-If your platform supports fork(), you can use the list form of C<open>
-for pipes. For example:
-
- open KID_PS, "-|", "ps", "aux" or die $!;
-
-forks the ps(1) command (without spawning a shell, as there are more
-than three arguments to open()), and reads its standard output via the
-C<KID_PS> filehandle. See L<perlipc>.
-
-=item *
-
-File handles can be marked as accepting Perl's internal encoding of Unicode
-(UTF-8 or UTF-EBCDIC depending on platform) by a pseudo layer ":utf8" :
-
- open($fh,">:utf8","Uni.txt");
-
-Note for EBCDIC users: the pseudo layer ":utf8" is erroneously named
-for you since it's not UTF-8 what you will be getting but instead
-UTF-EBCDIC. See L<perlunicode>, L<utf8>, and
-http://www.unicode.org/unicode/reports/tr16/ for more information.
-In future releases this naming may change. See L<perluniintro>
-for more information about UTF-8.
-
-=item *
-
-If your environment variables (LC_ALL, LC_CTYPE, LANG) look like you
-want to use UTF-8 (any of the variables match C</utf-?8/i>), your
-STDIN, STDOUT, STDERR handles and the default open layer (see L<open>)
-are marked as UTF-8. (This feature, like other new features that
-combine Unicode and I/O, work only if you are using PerlIO, but that's
-the default.)
-
-Note that after this Perl really does assume that everything is UTF-8:
-for example if some input handle is not, Perl will probably very soon
-complain about the input data like this "Malformed UTF-8 ..." since
-any old eight-bit data is not legal UTF-8.
-
-Note for code authors: if you want to enable your users to use UTF-8
-as their default encoding but in your code still have eight-bit I/O streams
-(such as images or zip files), you need to explicitly open() or binmode()
-with C<:bytes> (see L<perlfunc/open> and L<perlfunc/binmode>), or you
-can just use C<binmode(FH)> (nice for pre-5.8.0 backward compatibility).
-
-=item *
-
-File handles can translate character encodings from/to Perl's internal
-Unicode form on read/write via the ":encoding()" layer.
-
-=item *
-
-File handles can be opened to "in memory" files held in Perl scalars via:
-
- open($fh,'>', \$variable) || ...
-
-=item *
-
-Anonymous temporary files are available without need to
-'use FileHandle' or other module via
-
- open($fh,"+>", undef) || ...
-
-That is a literal undef, not an undefined value.
-
-=back
-
-=head2 ithreads
-
-The new interpreter threads ("ithreads" for short) implementation of
-multithreading, by Arthur Bergman, replaces the old "5.005 threads"
-implementation. In the ithreads model any data sharing between
-threads must be explicit, as opposed to the model where data sharing
-was implicit. See L<threads> and L<threads::shared>, and
-L<perlthrtut>.
-
-As a part of the ithreads implementation Perl will also use
-any necessary and detectable reentrant libc interfaces.
-
-=head2 Restricted Hashes
-
-A restricted hash is restricted to a certain set of keys, no keys
-outside the set can be added. Also individual keys can be restricted
-so that the key cannot be deleted and the value cannot be changed.
-No new syntax is involved: the Hash::Util module is the interface.
-
-=head2 Safe Signals
-
-Perl used to be fragile in that signals arriving at inopportune moments
-could corrupt Perl's internal state. Now Perl postpones handling of
-signals until it's safe (between opcodes).
-
-This change may have surprising side effects because signals no longer
-interrupt Perl instantly. Perl will now first finish whatever it was
-doing, like finishing an internal operation (like sort()) or an
-external operation (like an I/O operation), and only then look at any
-arrived signals (and before starting the next operation). No more corrupt
-internal state since the current operation is always finished first,
-but the signal may take more time to get heard. Note that breaking
-out from potentially blocking operations should still work, though.
-
-=head2 Understanding of Numbers
-
-In general a lot of fixing has happened in the area of Perl's
-understanding of numbers, both integer and floating point. Since in
-many systems the standard number parsing functions like C<strtoul()>
-and C<atof()> seem to have bugs, Perl tries to work around their
-deficiencies. This results hopefully in more accurate numbers.
-
-Perl now tries internally to use integer values in numeric conversions
-and basic arithmetics (+ - * /) if the arguments are integers, and
-tries also to keep the results stored internally as integers.
-This change leads to often slightly faster and always less lossy
-arithmetics. (Previously Perl always preferred floating point numbers
-in its math.)
-
-=head2 Arrays now always interpolate into double-quoted strings [561]
-
-In double-quoted strings, arrays now interpolate, no matter what. The
-behavior in earlier versions of perl 5 was that arrays would interpolate
-into strings if the array had been mentioned before the string was
-compiled, and otherwise Perl would raise a fatal compile-time error.
-In versions 5.000 through 5.003, the error was
-
- Literal @example now requires backslash
-
-In versions 5.004_01 through 5.6.0, the error was
-
- In string, @example now must be written as \@example
-
-The idea here was to get people into the habit of writing
-C<"fred\@example.com"> when they wanted a literal C<@> sign, just as
-they have always written C<"Give me back my \$5"> when they wanted a
-literal C<$> sign.
-
-Starting with 5.6.1, when Perl now sees an C<@> sign in a
-double-quoted string, it I<always> attempts to interpolate an array,
-regardless of whether or not the array has been used or declared
-already. The fatal error has been downgraded to an optional warning:
-
- Possible unintended interpolation of @example in string
-
-This warns you that C<"fred@example.com"> is going to turn into
-C<fred.com> if you don't backslash the C<@>.
-See http://perl.plover.com/at-error.html for more details
-about the history here.
-
-=head2 Miscellaneous Changes
-
-=over 4
-
-=item *
-
-AUTOLOAD is now lvaluable, meaning that you can add the :lvalue attribute
-to AUTOLOAD subroutines and you can assign to the AUTOLOAD return value.
-
-=item *
-
-The $Config{byteorder} (and corresponding BYTEORDER in config.h) was
-previously wrong in platforms if sizeof(long) was 4, but sizeof(IV)
-was 8. The byteorder was only sizeof(long) bytes long (1234 or 4321),
-but now it is correctly sizeof(IV) bytes long, (12345678 or 87654321).
-(This problem didn't affect Windows platforms.)
-
-Also, $Config{byteorder} is now computed dynamically--this is more
-robust with "fat binaries" where an executable image contains binaries
-for more than one binary platform, and when cross-compiling.
-
-=item *
-
-C<perl -d:Module=arg,arg,arg> now works (previously one couldn't pass
-in multiple arguments.)
-
-=item *
-
-C<do> followed by a bareword now ensures that this bareword isn't
-a keyword (to avoid a bug where C<do q(foo.pl)> tried to call a
-subroutine called C<q>). This means that for example instead of
-C<do format()> you must write C<do &format()>.
-
-=item *
-
-The builtin dump() now gives an optional warning
-C<dump() better written as CORE::dump()>,
-meaning that by default C<dump(...)> is resolved as the builtin
-dump() which dumps core and aborts, not as (possibly) user-defined
-C<sub dump>. To call the latter, qualify the call as C<&dump(...)>.
-(The whole dump() feature is to considered deprecated, and possibly
-removed/changed in future releases.)
-
-=item *
-
-chomp() and chop() are now overridable. Note, however, that their
-prototype (as given by C<prototype("CORE::chomp")> is undefined,
-because it cannot be expressed and therefore one cannot really write
-replacements to override these builtins.
-
-=item *
-
-END blocks are now run even if you exit/die in a BEGIN block.
-Internally, the execution of END blocks is now controlled by
-PL_exit_flags & PERL_EXIT_DESTRUCT_END. This enables the new
-behaviour for Perl embedders. This will default in 5.10. See
-L<perlembed>.
-
-=item *
-
-Formats now support zero-padded decimal fields.
-
-=item *
-
-Although "you shouldn't do that", it was possible to write code that
-depends on Perl's hashed key order (Data::Dumper does this). The new
-algorithm "One-at-a-Time" produces a different hashed key order.
-More details are in L</"Performance Enhancements">.
-
-=item *
-
-lstat(FILEHANDLE) now gives a warning because the operation makes no sense.
-In future releases this may become a fatal error.
-
-=item *
-
-Spurious syntax errors generated in certain situations, when glob()
-caused File::Glob to be loaded for the first time, have been fixed. [561]
-
-=item *
-
-Lvalue subroutines can now return C<undef> in list context. However,
-the lvalue subroutine feature still remains experimental. [561+]
-
-=item *
-
-A lost warning "Can't declare ... dereference in my" has been
-restored (Perl had it earlier but it became lost in later releases.)
-
-=item *
-
-A new special regular expression variable has been introduced:
-C<$^N>, which contains the most-recently closed group (submatch).
-
-=item *
-
-C<no Module;> does not produce an error even if Module does not have an
-unimport() method. This parallels the behavior of C<use> vis-a-vis
-C<import>. [561]
-
-=item *
-
-The numerical comparison operators return C<undef> if either operand
-is a NaN. Previously the behaviour was unspecified.
-
-=item *
-
-C<our> can now have an experimental optional attribute C<unique> that
-affects how global variables are shared among multiple interpreters,
-see L<perlfunc/our>.
-
-=item *
-
-The following builtin functions are now overridable: each(), keys(),
-pop(), push(), shift(), splice(), unshift(). [561]
-
-=item *
-
-C<pack() / unpack()> can now group template letters with C<()> and then
-apply repetition/count modifiers on the groups.
-
-=item *
-
-C<pack() / unpack()> can now process the Perl internal numeric types:
-IVs, UVs, NVs-- and also long doubles, if supported by the platform.
-The template letters are C<j>, C<J>, C<F>, and C<D>.
-
-=item *
-
-C<pack('U0a*', ...)> can now be used to force a string to UTF-8.
-
-=item *
-
-my __PACKAGE__ $obj now works. [561]
-
-=item *
-
-POSIX::sleep() now returns the number of I<unslept> seconds
-(as the POSIX standard says), as opposed to CORE::sleep() which
-returns the number of slept seconds.
-
-=item *
-
-printf() and sprintf() now support parameter reordering using the
-C<%\d+\$> and C<*\d+\$> syntaxes. For example
-
- printf "%2\$s %1\$s\n", "foo", "bar";
-
-will print "bar foo\n". This feature helps in writing
-internationalised software, and in general when the order
-of the parameters can vary.
-
-=item *
-
-The (\&) prototype now works properly. [561]
-
-=item *
-
-prototype(\[$@%&]) is now available to implicitly create references
-(useful for example if you want to emulate the tie() interface).
-
-=item *
-
-A new command-line option, C<-t> is available. It is the
-little brother of C<-T>: instead of dying on taint violations,
-lexical warnings are given. B<This is only meant as a temporary
-debugging aid while securing the code of old legacy applications.
-This is not a substitute for -T.>
-
-=item *
-
-In other taint news, the C<exec LIST> and C<system LIST> have now been
-considered too risky (think C<exec @ARGV>: it can start any program
-with any arguments), and now the said forms cause a warning under
-lexical warnings. You should carefully launder the arguments to
-guarantee their validity. In future releases of Perl the forms will
-become fatal errors so consider starting laundering now.
-
-=item *
-
-Tied hash interfaces are now required to have the EXISTS and DELETE
-methods (either own or inherited).
-
-=item *
-
-If tr/// is just counting characters, it doesn't attempt to
-modify its target.
-
-=item *
-
-untie() will now call an UNTIE() hook if it exists. See L<perltie>
-for details. [561]
-
-=item *
-
-L<perlfunc/utime> now supports C<utime undef, undef, @files> to change the
-file timestamps to the current time.
-
-=item *
-
-The rules for allowing underscores (underbars) in numeric constants
-have been relaxed and simplified: now you can have an underscore
-simply B<between digits>.
-
-=item *
-
-Rather than relying on C's argv[0] (which may not contain a full pathname)
-where possible $^X is now set by asking the operating system.
-(eg by reading F</proc/self/exe> on Linux, F</proc/curproc/file> on FreeBSD)
-
-=item *
-
-A new variable, C<${^TAINT}>, indicates whether taint mode is enabled.
-
-=item *
-
-You can now override the readline() builtin, and this overrides also
-the <FILEHANDLE> angle bracket operator.
-
-=item *
-
-The command-line options -s and -F are now recognized on the shebang
-(#!) line.
-
-=item *
-
-Use of the C</c> match modifier without an accompanying C</g> modifier
-elicits a new warning: C<Use of /c modifier is meaningless without /g>.
-
-Use of C</c> in substitutions, even with C</g>, elicits
-C<Use of /c modifier is meaningless in s///>.
-
-Use of C</g> with C<split> elicits C<Use of /g modifier is meaningless
-in split>.
-
-=item *
-
-Support for the C<CLONE> special subroutine had been added.
-With ithreads, when a new thread is created, all Perl data is cloned,
-however non-Perl data cannot be cloned automatically. In C<CLONE> you
-can do whatever you need to do, like for example handle the cloning of
-non-Perl data, if necessary. C<CLONE> will be executed once for every
-package that has it defined or inherited. It will be called in the
-context of the new thread, so all modifications are made in the new area.
-
-See L<perlmod>
-
-=back
-
-=head1 Modules and Pragmata
-
-=head2 New Modules and Pragmata
-
-=over 4
-
-=item *
-
-C<Attribute::Handlers>, originally by Damian Conway and now maintained
-by Arthur Bergman, allows a class to define attribute handlers.
-
- package MyPack;
- use Attribute::Handlers;
- sub Wolf :ATTR(SCALAR) { print "howl!\n" }
-
- # later, in some package using or inheriting from MyPack...
-
- my MyPack $Fluffy : Wolf; # the attribute handler Wolf will be called
-
-Both variables and routines can have attribute handlers. Handlers can
-be specific to type (SCALAR, ARRAY, HASH, or CODE), or specific to the
-exact compilation phase (BEGIN, CHECK, INIT, or END).
-See L<Attribute::Handlers>.
-
-=item *
-
-C<B::Concise>, by Stephen McCamant, is a new compiler backend for
-walking the Perl syntax tree, printing concise info about ops.
-The output is highly customisable. See L<B::Concise>. [561+]
-
-=item *
-
-The new bignum, bigint, and bigrat pragmas, by Tels, implement
-transparent bignum support (using the Math::BigInt, Math::BigFloat,
-and Math::BigRat backends).
-
-=item *
-
-C<Class::ISA>, by Sean Burke, is a module for reporting the search
-path for a class's ISA tree. See L<Class::ISA>.
-
-=item *
-
-C<Cwd> now has a split personality: if possible, an XS extension is
-used, (this will hopefully be faster, more secure, and more robust)
-but if not possible, the familiar Perl implementation is used.
-
-=item *
-
-C<Devel::PPPort>, originally by Kenneth Albanowski and now
-maintained by Paul Marquess, has been added. It is primarily used
-by C<h2xs> to enhance portability of XS modules between different
-versions of Perl. See L<Devel::PPPort>.
-
-=item *
-
-C<Digest>, frontend module for calculating digests (checksums), from
-Gisle Aas, has been added. See L<Digest>.
-
-=item *
-
-C<Digest::MD5> for calculating MD5 digests (checksums) as defined in
-RFC 1321, from Gisle Aas, has been added. See L<Digest::MD5>.
-
- use Digest::MD5 'md5_hex';
-
- $digest = md5_hex("Thirsty Camel");
-
- print $digest, "\n"; # 01d19d9d2045e005c3f1b80e8b164de1
-
-NOTE: the C<MD5> backward compatibility module is deliberately not
-included since its further use is discouraged.
-
-See also L<PerlIO::via::QuotedPrint>.
-
-=item *
-
-C<Encode>, originally by Nick Ing-Simmons and now maintained by Dan
-Kogai, provides a mechanism to translate between different character
-encodings. Support for Unicode, ISO-8859-1, and ASCII are compiled in
-to the module. Several other encodings (like the rest of the
-ISO-8859, CP*/Win*, Mac, KOI8-R, three variants EBCDIC, Chinese,
-Japanese, and Korean encodings) are included and can be loaded at
-runtime. (For space considerations, the largest Chinese encodings
-have been separated into their own CPAN module, Encode::HanExtra,
-which Encode will use if available). See L<Encode>.
-
-Any encoding supported by Encode module is also available to the
-":encoding()" layer if PerlIO is used.
-
-=item *
-
-C<Hash::Util> is the interface to the new I<restricted hashes>
-feature. (Implemented by Jeffrey Friedl, Nick Ing-Simmons, and
-Michael Schwern.) See L<Hash::Util>.
-
-=item *
-
-C<I18N::Langinfo> can be used to query locale information.
-See L<I18N::Langinfo>.
-
-=item *
-
-C<I18N::LangTags>, by Sean Burke, has functions for dealing with
-RFC3066-style language tags. See L<I18N::LangTags>.
-
-=item *
-
-C<ExtUtils::Constant>, by Nicholas Clark, is a new tool for extension
-writers for generating XS code to import C header constants.
-See L<ExtUtils::Constant>.
-
-=item *
-
-C<Filter::Simple>, by Damian Conway, is an easy-to-use frontend to
-Filter::Util::Call. See L<Filter::Simple>.
-
- # in MyFilter.pm:
-
- package MyFilter;
-
- use Filter::Simple sub {
- while (my ($from, $to) = splice @_, 0, 2) {
- s/$from/$to/g;
- }
- };
-
- 1;
-
- # in user's code:
-
- use MyFilter qr/red/ => 'green';
-
- print "red\n"; # this code is filtered, will print "green\n"
- print "bored\n"; # this code is filtered, will print "bogreen\n"
-
- no MyFilter;
-
- print "red\n"; # this code is not filtered, will print "red\n"
-
-=item *
-
-C<File::Temp>, by Tim Jenness, allows one to create temporary files
-and directories in an easy, portable, and secure way. See L<File::Temp>.
-[561+]
-
-=item *
-
-C<Filter::Util::Call>, by Paul Marquess, provides you with the
-framework to write I<source filters> in Perl. For most uses, the
-frontend Filter::Simple is to be preferred. See L<Filter::Util::Call>.
-
-=item *
-
-C<if>, by Ilya Zakharevich, is a new pragma for conditional inclusion
-of modules.
-
-=item *
-
-L<libnet>, by Graham Barr, is a collection of perl5 modules related
-to network programming. See L<Net::FTP>, L<Net::NNTP>, L<Net::Ping>
-(not part of libnet, but related), L<Net::POP3>, L<Net::SMTP>,
-and L<Net::Time>.
-
-Perl installation leaves libnet unconfigured; use F<libnetcfg>
-to configure it.
-
-=item *
-
-C<List::Util>, by Graham Barr, is a selection of general-utility
-list subroutines, such as sum(), min(), first(), and shuffle().
-See L<List::Util>.
-
-=item *
-
-C<Locale::Constants>, C<Locale::Country>, C<Locale::Currency>
-C<Locale::Language>, and L<Locale::Script>, by Neil Bowers, have
-been added. They provide the codes for various locale standards, such
-as "fr" for France, "usd" for US Dollar, and "ja" for Japanese.
-
- use Locale::Country;
-
- $country = code2country('jp'); # $country gets 'Japan'
- $code = country2code('Norway'); # $code gets 'no'
-
-See L<Locale::Constants>, L<Locale::Country>, L<Locale::Currency>,
-and L<Locale::Language>.
-
-=item *
-
-C<Locale::Maketext>, by Sean Burke, is a localization framework. See
-L<Locale::Maketext>, and L<Locale::Maketext::TPJ13>. The latter is an
-article about software localization, originally published in The Perl
-Journal #13, and republished here with kind permission.
-
-=item *
-
-C<Math::BigRat> for big rational numbers, to accompany Math::BigInt and
-Math::BigFloat, from Tels. See L<Math::BigRat>.
-
-=item *
-
-C<Memoize> can make your functions faster by trading space for time,
-from Mark-Jason Dominus. See L<Memoize>.
-
-=item *
-
-C<MIME::Base64>, by Gisle Aas, allows you to encode data in base64,
-as defined in RFC 2045 - I<MIME (Multipurpose Internet Mail
-Extensions)>.
-
- use MIME::Base64;
-
- $encoded = encode_base64('Aladdin:open sesame');
- $decoded = decode_base64($encoded);
-
- print $encoded, "\n"; # "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
-
-See L<MIME::Base64>.
-
-=item *
-
-C<MIME::QuotedPrint>, by Gisle Aas, allows you to encode data
-in quoted-printable encoding, as defined in RFC 2045 - I<MIME
-(Multipurpose Internet Mail Extensions)>.
-
- use MIME::QuotedPrint;
-
- $encoded = encode_qp("\xDE\xAD\xBE\xEF");
- $decoded = decode_qp($encoded);
-
- print $encoded, "\n"; # "=DE=AD=BE=EF\n"
- print $decoded, "\n"; # "\xDE\xAD\xBE\xEF\n"
-
-See also L<PerlIO::via::QuotedPrint>.
-
-=item *
-
-C<NEXT>, by Damian Conway, is a pseudo-class for method redispatch.
-See L<NEXT>.
-
-=item *
-
-C<open> is a new pragma for setting the default I/O layers
-for open().
-
-=item *
-
-C<PerlIO::scalar>, by Nick Ing-Simmons, provides the implementation
-of IO to "in memory" Perl scalars as discussed above. It also serves
-as an example of a loadable PerlIO layer. Other future possibilities
-include PerlIO::Array and PerlIO::Code. See L<PerlIO::scalar>.
-
-=item *
-
-C<PerlIO::via>, by Nick Ing-Simmons, acts as a PerlIO layer and wraps
-PerlIO layer functionality provided by a class (typically implemented
-in Perl code).
-
-=item *
-
-C<PerlIO::via::QuotedPrint>, by Elizabeth Mattijsen, is an example
-of a C<PerlIO::via> class:
-
- use PerlIO::via::QuotedPrint;
- open($fh,">:via(QuotedPrint)",$path);
-
-This will automatically convert everything output to C<$fh> to
-Quoted-Printable. See L<PerlIO::via> and L<PerlIO::via::QuotedPrint>.
-
-=item *
-
-C<Pod::ParseLink>, by Russ Allbery, has been added,
-to parse LZ<><> links in pods as described in the new
-perlpodspec.
-
-=item *
-
-C<Pod::Text::Overstrike>, by Joe Smith, has been added.
-It converts POD data to formatted overstrike text.
-See L<Pod::Text::Overstrike>. [561+]
-
-=item *
-
-C<Scalar::Util> is a selection of general-utility scalar subroutines,
-such as blessed(), reftype(), and tainted(). See L<Scalar::Util>.
-
-=item *
-
-C<sort> is a new pragma for controlling the behaviour of sort().
-
-=item *
-
-C<Storable> gives persistence to Perl data structures by allowing the
-storage and retrieval of Perl data to and from files in a fast and
-compact binary format. Because in effect Storable does serialisation
-of Perl data structures, with it you can also clone deep, hierarchical
-datastructures. Storable was originally created by Raphael Manfredi,
-but it is now maintained by Abhijit Menon-Sen. Storable has been
-enhanced to understand the two new hash features, Unicode keys and
-restricted hashes. See L<Storable>.
-
-=item *
-
-C<Switch>, by Damian Conway, has been added. Just by saying
-
- use Switch;
-
-you have C<switch> and C<case> available in Perl.
-
- use Switch;
-
- switch ($val) {
-
- case 1 { print "number 1" }
- case "a" { print "string a" }
- case [1..10,42] { print "number in list" }
- case (@array) { print "number in list" }
- case /\w+/ { print "pattern" }
- case qr/\w+/ { print "pattern" }
- case (%hash) { print "entry in hash" }
- case (\%hash) { print "entry in hash" }
- case (\&sub) { print "arg to subroutine" }
- else { print "previous case not true" }
- }
-
-See L<Switch>.
-
-=item *
-
-C<Test::More>, by Michael Schwern, is yet another framework for writing
-test scripts, more extensive than Test::Simple. See L<Test::More>.
-
-=item *
-
-C<Test::Simple>, by Michael Schwern, has basic utilities for writing
-tests. See L<Test::Simple>.
-
-=item *
-
-C<Text::Balanced>, by Damian Conway, has been added, for extracting
-delimited text sequences from strings.
-
- use Text::Balanced 'extract_delimited';
-
- ($a, $b) = extract_delimited("'never say never', he never said", "'", '');
-
-$a will be "'never say never'", $b will be ', he never said'.
-
-In addition to extract_delimited(), there are also extract_bracketed(),
-extract_quotelike(), extract_codeblock(), extract_variable(),
-extract_tagged(), extract_multiple(), gen_delimited_pat(), and
-gen_extract_tagged(). With these, you can implement rather advanced
-parsing algorithms. See L<Text::Balanced>.
-
-=item *
-
-C<threads>, by Arthur Bergman, is an interface to interpreter threads.
-Interpreter threads (ithreads) is the new thread model introduced in
-Perl 5.6 but only available as an internal interface for extension
-writers (and for Win32 Perl for C<fork()> emulation). See L<threads>,
-L<threads::shared>, and L<perlthrtut>.
-
-=item *
-
-C<threads::shared>, by Arthur Bergman, allows data sharing for
-interpreter threads. See L<threads::shared>.
-
-=item *
-
-C<Tie::File>, by Mark-Jason Dominus, associates a Perl array with the
-lines of a file. See L<Tie::File>.
-
-=item *
-
-C<Tie::Memoize>, by Ilya Zakharevich, provides on-demand loaded hashes.
-See L<Tie::Memoize>.
-
-=item *
-
-C<Tie::RefHash::Nestable>, by Edward Avis, allows storing hash
-references (unlike the standard Tie::RefHash) The module is contained
-within Tie::RefHash. See L<Tie::RefHash>.
-
-=item *
-
-C<Time::HiRes>, by Douglas E. Wegscheid, provides high resolution
-timing (ualarm, usleep, and gettimeofday). See L<Time::HiRes>.
-
-=item *
-
-C<Unicode::UCD> offers a querying interface to the Unicode Character
-Database. See L<Unicode::UCD>.
-
-=item *
-
-C<Unicode::Collate>, by SADAHIRO Tomoyuki, implements the UCA
-(Unicode Collation Algorithm) for sorting Unicode strings.
-See L<Unicode::Collate>.
-
-=item *
-
-C<Unicode::Normalize>, by SADAHIRO Tomoyuki, implements the various
-Unicode normalization forms. See L<Unicode::Normalize>.
-
-=item *
-
-C<XS::APItest>, by Tim Jenness, is a test extension that exercises XS
-APIs. Currently only C<printf()> is tested: how to output various
-basic data types from XS.
-
-=item *
-
-C<XS::Typemap>, by Tim Jenness, is a test extension that exercises
-XS typemaps. Nothing gets installed, but the code is worth studying
-for extension writers.
-
-=back
-
-=head2 Updated And Improved Modules and Pragmata
-
-=over 4
-
-=item *
-
-The following independently supported modules have been updated to the
-newest versions from CPAN: CGI, CPAN, DB_File, File::Spec, File::Temp,
-Getopt::Long, Math::BigFloat, Math::BigInt, the podlators bundle
-(Pod::Man, Pod::Text), Pod::LaTeX [561+], Pod::Parser, Storable,
-Term::ANSIColor, Test, Text-Tabs+Wrap.
-
-=item *
-
-attributes::reftype() now works on tied arguments.
-
-=item *
-
-AutoLoader can now be disabled with C<no AutoLoader;>.
-
-=item *
-
-B::Deparse has been significantly enhanced by Robin Houston. It can
-now deparse almost all of the standard test suite (so that the tests
-still succeed). There is a make target "test.deparse" for trying this
-out.
-
-=item *
-
-Carp now has better interface documentation, and the @CARP_NOT
-interface has been added to get optional control over where errors
-are reported independently of @ISA, by Ben Tilly.
-
-=item *
-
-Class::Struct can now define the classes in compile time.
-
-=item *
-
-Class::Struct now assigns the array/hash element if the accessor
-is called with an array/hash element as the B<sole> argument.
-
-=item *
-
-The return value of Cwd::fastcwd() is now tainted.
-
-=item *
-
-Data::Dumper now has an option to sort hashes.
-
-=item *
-
-Data::Dumper now has an option to dump code references
-using B::Deparse.
-
-=item *
-
-DB_File now supports newer Berkeley DB versions, among
-other improvements.
-
-=item *
-
-Devel::Peek now has an interface for the Perl memory statistics
-(this works only if you are using perl's malloc, and if you have
-compiled with debugging).
-
-=item *
-
-The English module can now be used without the infamous performance
-hit by saying
-
- use English '-no_match_vars';
-
-(Assuming, of course, that you don't need the troublesome variables
-C<$`>, C<$&>, or C<$'>.) Also, introduced C<@LAST_MATCH_START> and
-C<@LAST_MATCH_END> English aliases for C<@-> and C<@+>.
-
-=item *
-
-ExtUtils::MakeMaker has been significantly cleaned up and fixed.
-The enhanced version has also been backported to earlier releases
-of Perl and submitted to CPAN so that the earlier releases can
-enjoy the fixes.
-
-=item *
-
-The arguments of WriteMakefile() in Makefile.PL are now checked
-for sanity much more carefully than before. This may cause new
-warnings when modules are being installed. See L<ExtUtils::MakeMaker>
-for more details.
-
-=item *
-
-ExtUtils::MakeMaker now uses File::Spec internally, which hopefully
-leads to better portability.
-
-=item *
-
-Fcntl, Socket, and Sys::Syslog have been rewritten by Nicholas Clark
-to use the new-style constant dispatch section (see L<ExtUtils::Constant>).
-This means that they will be more robust and hopefully faster.
-
-=item *
-
-File::Find now chdir()s correctly when chasing symbolic links. [561]
-
-=item *
-
-File::Find now has pre- and post-processing callbacks. It also
-correctly changes directories when chasing symbolic links. Callbacks
-(naughtily) exiting with "next;" instead of "return;" now work.
-
-=item *
-
-File::Find is now (again) reentrant. It also has been made
-more portable.
-
-=item *
-
-The warnings issued by File::Find now belong to their own category.
-You can enable/disable them with C<use/no warnings 'File::Find';>.
-
-=item *
-
-File::Glob::glob() has been renamed to File::Glob::bsd_glob()
-because the name clashes with the builtin glob(). The older
-name is still available for compatibility, but is deprecated. [561]
-
-=item *
-
-File::Glob now supports C<GLOB_LIMIT> constant to limit the size of
-the returned list of filenames.
-
-=item *
-
-IPC::Open3 now allows the use of numeric file descriptors.
-
-=item *
-
-IO::Socket now has an atmark() method, which returns true if the socket
-is positioned at the out-of-band mark. The method is also exportable
-as a sockatmark() function.
-
-=item *
-
-IO::Socket::INET failed to open the specified port if the service name
-was not known. It now correctly uses the supplied port number as is. [561]
-
-=item *
-
-IO::Socket::INET has support for the ReusePort option (if your
-platform supports it). The Reuse option now has an alias, ReuseAddr.
-For clarity, you may want to prefer ReuseAddr.
-
-=item *
-
-IO::Socket::INET now supports a value of zero for C<LocalPort>
-(usually meaning that the operating system will make one up.)
-
-=item *
-
-'use lib' now works identically to @INC. Removing directories
-with 'no lib' now works.
-
-=item *
-
-Math::BigFloat and Math::BigInt have undergone a full rewrite by Tels.
-They are now magnitudes faster, and they support various bignum
-libraries such as GMP and PARI as their backends.
-
-=item *
-
-Math::Complex handles inf, NaN etc., better.
-
-=item *
-
-Net::Ping has been considerably enhanced by Rob Brown: multihoming is
-now supported, Win32 functionality is better, there is now time
-measuring functionality (optionally high-resolution using
-Time::HiRes), and there is now "external" protocol which uses
-Net::Ping::External module which runs your external ping utility and
-parses the output. A version of Net::Ping::External is available in
-CPAN.
-
-Note that some of the Net::Ping tests are disabled when running
-under the Perl distribution since one cannot assume one or more
-of the following: enabled echo port at localhost, full Internet
-connectivity, or sympathetic firewalls. You can set the environment
-variable PERL_TEST_Net_Ping to "1" (one) before running the Perl test
-suite to enable all the Net::Ping tests.
-
-=item *
-
-POSIX::sigaction() is now much more flexible and robust.
-You can now install coderef handlers, 'DEFAULT', and 'IGNORE'
-handlers, installing new handlers was not atomic.
-
-=item *
-
-In Safe, C<%INC> is now localised in a Safe compartment so that
-use/require work.
-
-=item *
-
-In SDBM_File on dosish platforms, some keys went missing because of
-lack of support for files with "holes". A workaround for the problem
-has been added.
-
-=item *
-
-In Search::Dict one can now have a pre-processing hook for the
-lines being searched.
-
-=item *
-
-The Shell module now has an OO interface.
-
-=item *
-
-In Sys::Syslog there is now a failover mechanism that will go
-through alternative connection mechanisms until the message
-is successfully logged.
-
-=item *
-
-The Test module has been significantly enhanced.
-
-=item *
-
-Time::Local::timelocal() does not handle fractional seconds anymore.
-The rationale is that neither does localtime(), and timelocal() and
-localtime() are supposed to be inverses of each other.
-
-=item *
-
-The vars pragma now supports declaring fully qualified variables.
-(Something that C<our()> does not and will not support.)
-
-=item *
-
-The C<utf8::> name space (as in the pragma) provides various
-Perl-callable functions to provide low level access to Perl's
-internal Unicode representation. At the moment only length()
-has been implemented.
-
-=back
-
-=head1 Utility Changes
-
-=over 4
-
-=item *
-
-Emacs perl mode (emacs/cperl-mode.el) has been updated to version
-4.31.
-
-=item *
-
-F<emacs/e2ctags.pl> is now much faster.
-
-=item *
-
-C<enc2xs> is a tool for people adding their own encodings to the
-Encode module.
-
-=item *
-
-C<h2ph> now supports C trigraphs.
-
-=item *
-
-C<h2xs> now produces a template README.
-
-=item *
-
-C<h2xs> now uses C<Devel::PPPort> for better portability between
-different versions of Perl.
-
-=item *
-
-C<h2xs> uses the new L<ExtUtils::Constant|ExtUtils::Constant> module
-which will affect newly created extensions that define constants.
-Since the new code is more correct (if you have two constants where the
-first one is a prefix of the second one, the first constant B<never>
-got defined), less lossy (it uses integers for integer constant,
-as opposed to the old code that used floating point numbers even for
-integer constants), and slightly faster, you might want to consider
-regenerating your extension code (the new scheme makes regenerating
-easy). L<h2xs> now also supports C trigraphs.
-
-=item *
-
-C<libnetcfg> has been added to configure libnet.
-
-=item *
-
-C<perlbug> is now much more robust. It also sends the bug report to
-perl.org, not perl.com.
-
-=item *
-
-C<perlcc> has been rewritten and its user interface (that is,
-command line) is much more like that of the Unix C compiler, cc.
-(The perlbc tools has been removed. Use C<perlcc -B> instead.)
-B<Note that perlcc is still considered very experimental and
-unsupported.> [561]
-
-=item *
-
-C<perlivp> is a new Installation Verification Procedure utility
-for running any time after installing Perl.
-
-=item *
-
-C<piconv> is an implementation of the character conversion utility
-C<iconv>, demonstrating the new Encode module.
-
-=item *
-
-C<pod2html> now allows specifying a cache directory.
-
-=item *
-
-C<pod2html> now produces XHTML 1.0.
-
-=item *
-
-C<pod2html> now understands POD written using different line endings
-(PC-like CRLF versus Unix-like LF versus MacClassic-like CR).
-
-=item *
-
-C<s2p> has been completely rewritten in Perl. (It is in fact a full
-implementation of sed in Perl: you can use the sed functionality by
-using the C<psed> utility.)
-
-=item *
-
-C<xsubpp> now understands POD documentation embedded in the *.xs
-files. [561]
-
-=item *
-
-C<xsubpp> now supports the OUT keyword.
-
-=back
-
-=head1 New Documentation
-
-=over 4
-
-=item *
-
-perl56delta details the changes between the 5.005 release and the
-5.6.0 release.
-
-=item *
-
-perlclib documents the internal replacements for standard C library
-functions. (Interesting only for extension writers and Perl core
-hackers.) [561+]
-
-=item *
-
-perldebtut is a Perl debugging tutorial. [561+]
-
-=item *
-
-perlebcdic contains considerations for running Perl on EBCDIC
-platforms. [561+]
-
-=item *
-
-perlintro is a gentle introduction to Perl.
-
-=item *
-
-perliol documents the internals of PerlIO with layers.
-
-=item *
-
-perlmodstyle is a style guide for writing modules.
-
-=item *
-
-perlnewmod tells about writing and submitting a new module. [561+]
-
-=item *
-
-perlpacktut is a pack() tutorial.
-
-=item *
-
-perlpod has been rewritten to be clearer and to record the best
-practices gathered over the years.
-
-=item *
-
-perlpodspec is a more formal specification of the pod format,
-mainly of interest for writers of pod applications, not to
-people writing in pod.
-
-=item *
-
-perlretut is a regular expression tutorial. [561+]
-
-=item *
-
-perlrequick is a regular expressions quick-start guide.
-Yes, much quicker than perlretut. [561]
-
-=item *
-
-perltodo has been updated.
-
-=item *
-
-perltootc has been renamed as perltooc (to not to conflict
-with perltoot in filesystems restricted to "8.3" names).
-
-=item *
-
-perluniintro is an introduction to using Unicode in Perl.
-(perlunicode is more of a detailed reference and background
-information)
-
-=item *
-
-perlutil explains the command line utilities packaged with the Perl
-distribution. [561+]
-
-=back
-
-The following platform-specific documents are available before
-the installation as README.I<platform>, and after the installation
-as perlI<platform>:
-
- perlaix perlamiga perlapollo perlbeos perlbs2000
- perlce perlcygwin perldgux perldos perlepoc perlfreebsd perlhpux
- perlhurd perlirix perlmachten perlmacos perlmint perlmpeix
- perlnetware perlos2 perlos390 perlplan9 perlqnx perlsolaris
- perltru64 perluts perlvmesa perlvms perlvos perlwin32
-
-These documents usually detail one or more of the following subjects:
-configuring, building, testing, installing, and sometimes also using
-Perl on the said platform.
-
-Eastern Asian Perl users are now welcomed in their own languages:
-README.jp (Japanese), README.ko (Korean), README.cn (simplified
-Chinese) and README.tw (traditional Chinese), which are written in
-normal pod but encoded in EUC-JP, EUC-KR, EUC-CN and Big5. These
-will get installed as
-
- perljp perlko perlcn perltw
-
-=over 4
-
-=item *
-
-The documentation for the POSIX-BC platform is called "BS2000", to avoid
-confusion with the Perl POSIX module.
-
-=item *
-
-The documentation for the WinCE platform is called perlce (README.ce
-in the source code kit), to avoid confusion with the perlwin32
-documentation on 8.3-restricted filesystems.
-
-=back
-
-=head1 Performance Enhancements
-
-=over 4
-
-=item *
-
-map() could get pathologically slow when the result list it generates
-is larger than the source list. The performance has been improved for
-common scenarios. [561]
-
-=item *
-
-sort() is also fully reentrant, in the sense that the sort function
-can itself call sort(). This did not work reliably in previous
-releases. [561]
-
-=item *
-
-sort() has been changed to use primarily mergesort internally as
-opposed to the earlier quicksort. For very small lists this may
-result in slightly slower sorting times, but in general the speedup
-should be at least 20%. Additional bonuses are that the worst case
-behaviour of sort() is now better (in computer science terms it now
-runs in time O(N log N), as opposed to quicksort's Theta(N**2)
-worst-case run time behaviour), and that sort() is now stable
-(meaning that elements with identical keys will stay ordered as they
-were before the sort). See the C<sort> pragma for information.
-
-The story in more detail: suppose you want to serve yourself a little
-slice of Pi.
-
- @digits = ( 3,1,4,1,5,9 );
-
-A numerical sort of the digits will yield (1,1,3,4,5,9), as expected.
-Which C<1> comes first is hard to know, since one C<1> looks pretty
-much like any other. You can regard this as totally trivial,
-or somewhat profound. However, if you just want to sort the even
-digits ahead of the odd ones, then what will
-
- sort { ($a % 2) <=> ($b % 2) } @digits;
-
-yield? The only even digit, C<4>, will come first. But how about
-the odd numbers, which all compare equal? With the quicksort algorithm
-used to implement Perl 5.6 and earlier, the order of ties is left up
-to the sort. So, as you add more and more digits of Pi, the order
-in which the sorted even and odd digits appear will change.
-and, for sufficiently large slices of Pi, the quicksort algorithm
-in Perl 5.8 won't return the same results even if reinvoked with the
-same input. The justification for this rests with quicksort's
-worst case behavior. If you run
-
- sort { $a <=> $b } ( 1 .. $N , 1 .. $N );
-
-(something you might approximate if you wanted to merge two sorted
-arrays using sort), doubling $N doesn't just double the quicksort time,
-it I<quadruples> it. Quicksort has a worst case run time that can
-grow like N**2, so-called I<quadratic> behaviour, and it can happen
-on patterns that may well arise in normal use. You won't notice this
-for small arrays, but you I<will> notice it with larger arrays,
-and you may not live long enough for the sort to complete on arrays
-of a million elements. So the 5.8 quicksort scrambles large arrays
-before sorting them, as a statistical defence against quadratic behaviour.
-But that means if you sort the same large array twice, ties may be
-broken in different ways.
-
-Because of the unpredictability of tie-breaking order, and the quadratic
-worst-case behaviour, quicksort was I<almost> replaced completely with
-a stable mergesort. I<Stable> means that ties are broken to preserve
-the original order of appearance in the input array. So
-
- sort { ($a % 2) <=> ($b % 2) } (3,1,4,1,5,9);
-
-will yield (4,3,1,1,5,9), guaranteed. The even and odd numbers
-appear in the output in the same order they appeared in the input.
-Mergesort has worst case O(N log N) behaviour, the best value
-attainable. And, ironically, this mergesort does particularly
-well where quicksort goes quadratic: mergesort sorts (1..$N, 1..$N)
-in O(N) time. But quicksort was rescued at the last moment because
-it is faster than mergesort on certain inputs and platforms.
-For example, if you really I<don't> care about the order of even
-and odd digits, quicksort will run in O(N) time; it's very good
-at sorting many repetitions of a small number of distinct elements.
-The quicksort divide and conquer strategy works well on platforms
-with relatively small, very fast, caches. Eventually, the problem gets
-whittled down to one that fits in the cache, from which point it
-benefits from the increased memory speed.
-
-Quicksort was rescued by implementing a sort pragma to control aspects
-of the sort. The B<stable> subpragma forces stable behaviour,
-regardless of algorithm. The B<_quicksort> and B<_mergesort>
-subpragmas are heavy-handed ways to select the underlying implementation.
-The leading C<_> is a reminder that these subpragmas may not survive
-beyond 5.8. More appropriate mechanisms for selecting the implementation
-exist, but they wouldn't have arrived in time to save quicksort.
-
-=item *
-
-Hashes now use Bob Jenkins "One-at-a-Time" hashing key algorithm
-( http://burtleburtle.net/bob/hash/doobs.html ). This algorithm is
-reasonably fast while producing a much better spread of values than
-the old hashing algorithm (originally by Chris Torek, later tweaked by
-Ilya Zakharevich). Hash values output from the algorithm on a hash of
-all 3-char printable ASCII keys comes much closer to passing the
-DIEHARD random number generation tests. According to perlbench, this
-change has not affected the overall speed of Perl.
-
-=item *
-
-unshift() should now be noticeably faster.
-
-=back
-
-=head1 Installation and Configuration Improvements
-
-=head2 Generic Improvements
-
-=over 4
-
-=item *
-
-INSTALL now explains how you can configure Perl to use 64-bit
-integers even on non-64-bit platforms.
-
-=item *
-
-Policy.sh policy change: if you are reusing a Policy.sh file
-(see INSTALL) and you use Configure -Dprefix=/foo/bar and in the old
-Policy $prefix eq $siteprefix and $prefix eq $vendorprefix, all of
-them will now be changed to the new prefix, /foo/bar. (Previously
-only $prefix changed.) If you do not like this new behaviour,
-specify prefix, siteprefix, and vendorprefix explicitly.
-
-=item *
-
-A new optional location for Perl libraries, otherlibdirs, is available.
-It can be used for example for vendor add-ons without disturbing Perl's
-own library directories.
-
-=item *
-
-In many platforms, the vendor-supplied 'cc' is too stripped-down to
-build Perl (basically, 'cc' doesn't do ANSI C). If this seems
-to be the case and 'cc' does not seem to be the GNU C compiler
-'gcc', an automatic attempt is made to find and use 'gcc' instead.
-
-=item *
-
-gcc needs to closely track the operating system release to avoid
-build problems. If Configure finds that gcc was built for a different
-operating system release than is running, it now gives a clearly visible
-warning that there may be trouble ahead.
-
-=item *
-
-Since Perl 5.8 is not binary-compatible with previous releases
-of Perl, Configure no longer suggests including the 5.005
-modules in @INC.
-
-=item *
-
-Configure C<-S> can now run non-interactively. [561]
-
-=item *
-
-Configure support for pdp11-style memory models has been removed due
-to obsolescence. [561]
-
-=item *
-
-configure.gnu now works with options with whitespace in them.
-
-=item *
-
-installperl now outputs everything to STDERR.
-
-=item *
-
-Because PerlIO is now the default on most platforms, "-perlio" doesn't
-get appended to the $Config{archname} (also known as $^O) anymore.
-Instead, if you explicitly choose not to use perlio (Configure command
-line option -Uuseperlio), you will get "-stdio" appended.
-
-=item *
-
-Another change related to the architecture name is that "-64all"
-(-Duse64bitall, or "maximally 64-bit") is appended only if your
-pointers are 64 bits wide. (To be exact, the use64bitall is ignored.)
-
-=item *
-
-In AFS installations, one can configure the root of the AFS to be
-somewhere else than the default F</afs> by using the Configure
-parameter C<-Dafsroot=/some/where/else>.
-
-=item *
-
-APPLLIB_EXP, a lesser-known configuration-time definition, has been
-documented. It can be used to prepend site-specific directories
-to Perl's default search path (@INC); see INSTALL for information.
-
-=item *
-
-The version of Berkeley DB used when the Perl (and, presumably, the
-DB_File extension) was built is now available as
-C<@Config{qw(db_version_major db_version_minor db_version_patch)}>
-from Perl and as C<DB_VERSION_MAJOR_CFG DB_VERSION_MINOR_CFG
-DB_VERSION_PATCH_CFG> from C.
-
-=item *
-
-Building Berkeley DB3 for compatibility modes for DB, NDBM, and ODBM
-has been documented in INSTALL.
-
-=item *
-
-If you have CPAN access (either network or a local copy such as a
-CD-ROM) you can during specify extra modules to Configure to build and
-install with Perl using the -Dextras=... option. See INSTALL for
-more details.
-
-=item *
-
-In addition to config.over, a new override file, config.arch, is
-available. This file is supposed to be used by hints file writers
-for architecture-wide changes (as opposed to config.over which is
-for site-wide changes).
-
-=item *
-
-If your file system supports symbolic links, you can build Perl outside
-of the source directory by
-
- mkdir perl/build/directory
- cd perl/build/directory
- sh /path/to/perl/source/Configure -Dmksymlinks ...
-
-This will create in perl/build/directory a tree of symbolic links
-pointing to files in /path/to/perl/source. The original files are left
-unaffected. After Configure has finished, you can just say
-
- make all test
-
-and Perl will be built and tested, all in perl/build/directory.
-[561]
-
-=item *
-
-For Perl developers, several new make targets for profiling
-and debugging have been added; see L<perlhack>.
-
-=over 8
-
-=item *
-
-Use of the F<gprof> tool to profile Perl has been documented in
-L<perlhack>. There is a make target called "perl.gprof" for
-generating a gprofiled Perl executable.
-
-=item *
-
-If you have GCC 3, there is a make target called "perl.gcov" for
-creating a gcoved Perl executable for coverage analysis. See
-L<perlhack>.
-
-=item *
-
-If you are on IRIX or Tru64 platforms, new profiling/debugging options
-have been added; see L<perlhack> for more information about pixie and
-Third Degree.
-
-=back
-
-=item *
-
-Guidelines of how to construct minimal Perl installations have
-been added to INSTALL.
-
-=item *
-
-The Thread extension is now not built at all under ithreads
-(C<Configure -Duseithreads>) because it wouldn't work anyway (the
-Thread extension requires being Configured with C<-Duse5005threads>).
-
-B<Note that the 5.005 threads are unsupported and deprecated: if you
-have code written for the old threads you should migrate it to the
-new ithreads model.>
-
-=item *
-
-The Gconvert macro ($Config{d_Gconvert}) used by perl for stringifying
-floating-point numbers is now more picky about using sprintf %.*g
-rules for the conversion. Some platforms that used to use gcvt may
-now resort to the slower sprintf.
-
-=item *
-
-The obsolete method of making a special (e.g., debugging) flavor
-of perl by saying
-
- make LIBPERL=libperld.a
-
-has been removed. Use -DDEBUGGING instead.
-
-=back
-
-=head2 New Or Improved Platforms
-
-For the list of platforms known to support Perl,
-see L<perlport/"Supported Platforms">.
-
-=over 4
-
-=item *
-
-AIX dynamic loading should be now better supported.
-
-=item *
-
-AIX should now work better with gcc, threads, and 64-bitness. Also the
-long doubles support in AIX should be better now. See L<perlaix>.
-
-=item *
-
-AtheOS ( http://www.atheos.cx/ ) is a new platform.
-
-=item *
-
-BeOS has been reclaimed.
-
-=item *
-
-The DG/UX platform now supports 5.005-style threads.
-See L<perldgux>.
-
-=item *
-
-The DYNIX/ptx platform (also known as dynixptx) is supported at or
-near osvers 4.5.2.
-
-=item *
-
-EBCDIC platforms (z/OS (also known as OS/390), POSIX-BC, and VM/ESA)
-have been regained. Many test suite tests still fail and the
-co-existence of Unicode and EBCDIC isn't quite settled, but the
-situation is much better than with Perl 5.6. See L<perlos390>,
-L<perlbs2000> (for POSIX-BC), and L<perlvmesa> for more information.
-
-=item *
-
-Building perl with -Duseithreads or -Duse5005threads now works under
-HP-UX 10.20 (previously it only worked under 10.30 or later). You will
-need a thread library package installed. See README.hpux. [561]
-
-=item *
-
-Mac OS Classic is now supported in the mainstream source package
-(MacPerl has of course been available since perl 5.004 but now the
-source code bases of standard Perl and MacPerl have been synchronised)
-[561]
-
-=item *
-
-Mac OS X (or Darwin) should now be able to build Perl even on HFS+
-filesystems. (The case-insensitivity used to confuse the Perl build
-process.)
-
-=item *
-
-NCR MP-RAS is now supported. [561]
-
-=item *
-
-All the NetBSD specific patches (except for the installation
-specific ones) have been merged back to the main distribution.
-
-=item *
-
-NetWare from Novell is now supported. See L<perlnetware>.
-
-=item *
-
-NonStop-UX is now supported. [561]
-
-=item *
-
-NEC SUPER-UX is now supported.
-
-=item *
-
-All the OpenBSD specific patches (except for the installation
-specific ones) have been merged back to the main distribution.
-
-=item *
-
-Perl has been tested with the GNU pth userlevel thread package
-( http://www.gnu.org/software/pth/pth.html ). All thread tests
-of Perl now work, but not without adding some yield()s to the tests,
-so while pth (and other userlevel thread implementations) can be
-considered to be "working" with Perl ithreads, keep in mind the
-possible non-preemptability of the underlying thread implementation.
-
-=item *
-
-Stratus VOS is now supported using Perl's native build method
-(Configure). This is the recommended method to build Perl on
-VOS. The older methods, which build miniperl, are still
-available. See L<perlvos>. [561+]
-
-=item *
-
-The Amdahl UTS Unix mainframe platform is now supported. [561]
-
-=item *
-
-WinCE is now supported. See L<perlce>.
-
-=item *
-
-z/OS (formerly known as OS/390, formerly known as MVS OE) now has
-support for dynamic loading. This is not selected by default,
-however, you must specify -Dusedl in the arguments of Configure. [561]
-
-=back
-
-=head1 Selected Bug Fixes
-
-Numerous memory leaks and uninitialized memory accesses have been
-hunted down. Most importantly, anonymous subs used to leak quite
-a bit. [561]
-
-=over 4
-
-=item *
-
-The autouse pragma didn't work for Multi::Part::Function::Names.
-
-=item *
-
-caller() could cause core dumps in certain situations. Carp was
-sometimes affected by this problem. In particular, caller() now
-returns a subroutine name of C<(unknown)> for subroutines that have
-been removed from the symbol table.
-
-=item *
-
-chop(@list) in list context returned the characters chopped in
-reverse order. This has been reversed to be in the right order. [561]
-
-=item *
-
-Configure no longer includes the DBM libraries (dbm, gdbm, db, ndbm)
-when building the Perl binary. The only exception to this is SunOS 4.x,
-which needs them. [561]
-
-=item *
-
-The behaviour of non-decimal but numeric string constants such as
-"0x23" was platform-dependent: in some platforms that was seen as 35,
-in some as 0, in some as a floating point number (don't ask). This
-was caused by Perl's using the operating system libraries in a situation
-where the result of the string to number conversion is undefined: now
-Perl consistently handles such strings as zero in numeric contexts.
-
-=item *
-
-Several debugger fixes: exit code now reflects the script exit code,
-condition C<"0"> now treated correctly, the C<d> command now checks
-line number, C<$.> no longer gets corrupted, and all debugger output
-now goes correctly to the socket if RemotePort is set. [561]
-
-=item *
-
-The debugger (perl5db.pl) has been modified to present a more
-consistent commands interface, via (CommandSet=580). perl5db.t was
-also added to test the changes, and as a placeholder for further tests.
-
-See L<perldebug>.
-
-=item *
-
-The debugger has a new C<dumpDepth> option to control the maximum
-depth to which nested structures are dumped. The C<x> command has
-been extended so that C<x N EXPR> dumps out the value of I<EXPR> to a
-depth of at most I<N> levels.
-
-=item *
-
-The debugger can now show lexical variables if you have the CPAN
-module PadWalker installed.
-
-=item *
-
-The order of DESTROYs has been made more predictable.
-
-=item *
-
-Perl 5.6.0 could emit spurious warnings about redefinition of
-dl_error() when statically building extensions into perl.
-This has been corrected. [561]
-
-=item *
-
-L<dprofpp> -R didn't work.
-
-=item *
-
-C<*foo{FORMAT}> now works.
-
-=item *
-
-Infinity is now recognized as a number.
-
-=item *
-
-UNIVERSAL::isa no longer caches methods incorrectly. (This broke
-the Tk extension with 5.6.0.) [561]
-
-=item *
-
-Lexicals I: lexicals outside an eval "" weren't resolved
-correctly inside a subroutine definition inside the eval "" if they
-were not already referenced in the top level of the eval""ed code.
-
-=item *
-
-Lexicals II: lexicals leaked at file scope into subroutines that
-were declared before the lexicals.
-
-=item *
-
-Lexical warnings now propagating correctly between scopes
-and into C<eval "...">.
-
-=item *
-
-C<use warnings qw(FATAL all)> did not work as intended. This has been
-corrected. [561]
-
-=item *
-
-warnings::enabled() now reports the state of $^W correctly if the caller
-isn't using lexical warnings. [561]
-
-=item *
-
-Line renumbering with eval and C<#line> now works. [561]
-
-=item *
-
-Fixed numerous memory leaks, especially in eval "".
-
-=item *
-
-Localised tied variables no longer leak memory
-
- use Tie::Hash;
- tie my %tied_hash => 'Tie::StdHash';
-
- ...
-
- # Used to leak memory every time local() was called;
- # in a loop, this added up.
- local($tied_hash{Foo}) = 1;
-
-=item *
-
-Localised hash elements (and %ENV) are correctly unlocalised to not
-exist, if they didn't before they were localised.
-
-
- use Tie::Hash;
- tie my %tied_hash => 'Tie::StdHash';
-
- ...
-
- # Nothing has set the FOO element so far
-
- { local $tied_hash{FOO} = 'Bar' }
-
- # This used to print, but not now.
- print "exists!\n" if exists $tied_hash{FOO};
-
-As a side effect of this fix, tied hash interfaces B<must> define
-the EXISTS and DELETE methods.
-
-=item *
-
-mkdir() now ignores trailing slashes in the directory name,
-as mandated by POSIX.
-
-=item *
-
-Some versions of glibc have a broken modfl(). This affects builds
-with C<-Duselongdouble>. This version of Perl detects this brokenness
-and has a workaround for it. The glibc release 2.2.2 is known to have
-fixed the modfl() bug.
-
-=item *
-
-Modulus of unsigned numbers now works (4063328477 % 65535 used to
-return 27406, instead of 27047). [561]
-
-=item *
-
-Some "not a number" warnings introduced in 5.6.0 eliminated to be
-more compatible with 5.005. Infinity is now recognised as a number. [561]
-
-=item *
-
-Numeric conversions did not recognize changes in the string value
-properly in certain circumstances. [561]
-
-=item *
-
-Attributes (such as :shared) didn't work with our().
-
-=item *
-
-our() variables will not cause bogus "Variable will not stay shared"
-warnings. [561]
-
-=item *
-
-"our" variables of the same name declared in two sibling blocks
-resulted in bogus warnings about "redeclaration" of the variables.
-The problem has been corrected. [561]
-
-=item *
-
-pack "Z" now correctly terminates the string with "\0".
-
-=item *
-
-Fix password routines which in some shadow password platforms
-(e.g. HP-UX) caused getpwent() to return every other entry.
-
-=item *
-
-The PERL5OPT environment variable (for passing command line arguments
-to Perl) didn't work for more than a single group of options. [561]
-
-=item *
-
-PERL5OPT with embedded spaces didn't work.
-
-=item *
-
-printf() no longer resets the numeric locale to "C".
-
-=item *
-
-C<qw(a\\b)> now parses correctly as C<'a\\b'>: that is, as three
-characters, not four. [561]
-
-=item *
-
-pos() did not return the correct value within s///ge in earlier
-versions. This is now handled correctly. [561]
-
-=item *
-
-Printing quads (64-bit integers) with printf/sprintf now works
-without the q L ll prefixes (assuming you are on a quad-capable platform).
-
-=item *
-
-Regular expressions on references and overloaded scalars now work. [561+]
-
-=item *
-
-Right-hand side magic (GMAGIC) could in many cases such as string
-concatenation be invoked too many times.
-
-=item *
-
-scalar() now forces scalar context even when used in void context.
-
-=item *
-
-SOCKS support is now much more robust.
-
-=item *
-
-sort() arguments are now compiled in the right wantarray context
-(they were accidentally using the context of the sort() itself).
-The comparison block is now run in scalar context, and the arguments
-to be sorted are always provided list context. [561]
-
-=item *
-
-Changed the POSIX character class C<[[:space:]]> to include the (very
-rarely used) vertical tab character. Added a new POSIX-ish character
-class C<[[:blank:]]> which stands for horizontal whitespace
-(currently, the space and the tab).
-
-=item *
-
-The tainting behaviour of sprintf() has been rationalized. It does
-not taint the result of floating point formats anymore, making the
-behaviour consistent with that of string interpolation. [561]
-
-=item *
-
-Some cases of inconsistent taint propagation (such as within hash
-values) have been fixed.
-
-=item *
-
-The RE engine found in Perl 5.6.0 accidentally pessimised certain kinds
-of simple pattern matches. These are now handled better. [561]
-
-=item *
-
-Regular expression debug output (whether through C<use re 'debug'>
-or via C<-Dr>) now looks better. [561]
-
-=item *
-
-Multi-line matches like C<"a\nxb\n" =~ /(?!\A)x/m> were flawed. The
-bug has been fixed. [561]
-
-=item *
-
-Use of $& could trigger a core dump under some situations. This
-is now avoided. [561]
-
-=item *
-
-The regular expression captured submatches ($1, $2, ...) are now
-more consistently unset if the match fails, instead of leaving false
-data lying around in them. [561]
-
-=item *
-
-readline() on files opened in "slurp" mode could return an extra
-"" (blank line) at the end in certain situations. This has been
-corrected. [561]
-
-=item *
-
-Autovivification of symbolic references of special variables described
-in L<perlvar> (as in C<${$num}>) was accidentally disabled. This works
-again now. [561]
-
-=item *
-
-Sys::Syslog ignored the C<LOG_AUTH> constant.
-
-=item *
-
-$AUTOLOAD, sort(), lock(), and spawning subprocesses
-in multiple threads simultaneously are now thread-safe.
-
-=item *
-
-Tie::Array's SPLICE method was broken.
-
-=item *
-
-Allow a read-only string on the left-hand side of a non-modifying tr///.
-
-=item *
-
-If C<STDERR> is tied, warnings caused by C<warn> and C<die> now
-correctly pass to it.
-
-=item *
-
-Several Unicode fixes.
-
-=over 8
-
-=item *
-
-BOMs (byte order marks) at the beginning of Perl files
-(scripts, modules) should now be transparently skipped.
-UTF-16 and UCS-2 encoded Perl files should now be read correctly.
-
-=item *
-
-The character tables have been updated to Unicode 3.2.0.
-
-=item *
-
-Comparing with utf8 data does not magically upgrade non-utf8 data
-into utf8. (This was a problem for example if you were mixing data
-from I/O and Unicode data: your output might have got magically encoded
-as UTF-8.)
-
-=item *
-
-Generating illegal Unicode code points such as U+FFFE, or the UTF-16
-surrogates, now also generates an optional warning.
-
-=item *
-
-C<IsAlnum>, C<IsAlpha>, and C<IsWord> now match titlecase.
-
-=item *
-
-Concatenation with the C<.> operator or via variable interpolation,
-C<eq>, C<substr>, C<reverse>, C<quotemeta>, the C<x> operator,
-substitution with C<s///>, single-quoted UTF-8, should now work.
-
-=item *
-
-The C<tr///> operator now works. Note that the C<tr///CU>
-functionality has been removed (but see pack('U0', ...)).
-
-=item *
-
-C<eval "v200"> now works.
-
-=item *
-
-Perl 5.6.0 parsed m/\x{ab}/ incorrectly, leading to spurious warnings.
-This has been corrected. [561]
-
-=item *
-
-Zero entries were missing from the Unicode classes such as C<IsDigit>.
-
-=back
-
-=item *
-
-Large unsigned numbers (those above 2**31) could sometimes lose their
-unsignedness, causing bogus results in arithmetic operations. [561]
-
-=item *
-
-The Perl parser has been stress tested using both random input and
-Markov chain input and the few found crashes and lockups have been
-fixed.
-
-=back
-
-=head2 Platform Specific Changes and Fixes
-
-=over 4
-
-=item *
-
-BSDI 4.*
-
-Perl now works on post-4.0 BSD/OSes.
-
-=item *
-
-All BSDs
-
-Setting C<$0> now works (as much as possible; see L<perlvar> for details).
-
-=item *
-
-Cygwin
-
-Numerous updates; currently synchronised with Cygwin 1.3.10.
-
-=item *
-
-Previously DYNIX/ptx had problems in its Configure probe for non-blocking I/O.
-
-=item *
-
-EPOC
-
-EPOC now better supported. See README.epoc. [561]
-
-=item *
-
-FreeBSD 3.*
-
-Perl now works on post-3.0 FreeBSDs.
-
-=item *
-
-HP-UX
-
-README.hpux updated; C<Configure -Duse64bitall> now works;
-now uses HP-UX malloc instead of Perl malloc.
-
-=item *
-
-IRIX
-
-Numerous compilation flag and hint enhancements; accidental mixing
-of 32-bit and 64-bit libraries (a doomed attempt) made much harder.
-
-=item *
-
-Linux
-
-=over 8
-
-=item *
-
-Long doubles should now work (see INSTALL). [561]
-
-=item *
-
-Linux previously had problems related to sockaddrlen when using
-accept(), recvfrom() (in Perl: recv()), getpeername(), and
-getsockname().
-
-=back
-
-=item *
-
-Mac OS Classic
-
-Compilation of the standard Perl distribution in Mac OS Classic should
-now work if you have the Metrowerks development environment and the
-missing Mac-specific toolkit bits. Contact the macperl mailing list
-for details.
-
-=item *
-
-MPE/iX
-
-MPE/iX update after Perl 5.6.0. See README.mpeix. [561]
-
-=item *
-
-NetBSD/threads: try installing the GNU pth (should be in the
-packages collection, or http://www.gnu.org/software/pth/),
-and Configure with -Duseithreads.
-
-=item *
-
-NetBSD/sparc
-
-Perl now works on NetBSD/sparc.
-
-=item *
-
-OS/2
-
-Now works with usethreads (see INSTALL). [561]
-
-=item *
-
-Solaris
-
-64-bitness using the Sun Workshop compiler now works.
-
-=item *
-
-Stratus VOS
-
-The native build method requires at least VOS Release 14.5.0
-and GNU C++/GNU Tools 2.0.1 or later. The Perl pack function
-now maps overflowed values to +infinity and underflowed values
-to -infinity.
-
-=item *
-
-Tru64 (aka Digital UNIX, aka DEC OSF/1)
-
-The operating system version letter now recorded in $Config{osvers}.
-Allow compiling with gcc (previously explicitly forbidden). Compiling
-with gcc still not recommended because buggy code results, even with
-gcc 2.95.2.
-
-=item *
-
-Unicos
-
-Fixed various alignment problems that lead into core dumps either
-during build or later; no longer dies on math errors at runtime;
-now using full quad integers (64 bits), previously was using
-only 46 bit integers for speed.
-
-=item *
-
-VMS
-
-See L</"Socket Extension Dynamic in VMS"> and L</"IEEE-format Floating Point
-Default on OpenVMS Alpha"> for important changes not otherwise listed here.
-
-chdir() now works better despite a CRT bug; now works with MULTIPLICITY
-(see INSTALL); now works with Perl's malloc.
-
-The tainting of C<%ENV> elements via C<keys> or C<values> was previously
-unimplemented. It now works as documented.
-
-The C<waitpid> emulation has been improved. The worst bug (now fixed)
-was that a pid of -1 would cause a wildcard search of all processes on
-the system.
-
-POSIX-style signals are now emulated much better on VMS versions prior
-to 7.0.
-
-The C<system> function and backticks operator have improved
-functionality and better error handling. [561]
-
-File access tests now use current process privileges rather than the
-user's default privileges, which could sometimes result in a mismatch
-between reported access and actual access. This improvement is only
-available on VMS v6.0 and later.
-
-There is a new C<kill> implementation based on C<sys$sigprc> that allows
-older VMS systems (pre-7.0) to use C<kill> to send signals rather than
-simply force exit. This implementation also allows later systems to
-call C<kill> from within a signal handler.
-
-Iterative logical name translations are now limited to 10 iterations in
-imitation of SHOW LOGICAL and other OpenVMS facilities.
-
-=item *
-
-Windows
-
-=over 8
-
-=item *
-
-Signal handling now works better than it used to. It is now implemented
-using a Windows message loop, and is therefore less prone to random
-crashes.
-
-=item *
-
-fork() emulation is now more robust, but still continues to have a few
-esoteric bugs and caveats. See L<perlfork> for details. [561+]
-
-=item *
-
-A failed (pseudo)fork now returns undef and sets errno to EAGAIN. [561]
-
-=item *
-
-The following modules now work on Windows:
-
- ExtUtils::Embed [561]
- IO::Pipe
- IO::Poll
- Net::Ping
-
-=item *
-
-IO::File::new_tmpfile() is no longer limited to 32767 invocations
-per-process.
-
-=item *
-
-Better chdir() return value for a non-existent directory.
-
-=item *
-
-Compiling perl using the 64-bit Platform SDK tools is now supported.
-
-=item *
-
-The Win32::SetChildShowWindow() builtin can be used to control the
-visibility of windows created by child processes. See L<Win32> for
-details.
-
-=item *
-
-Non-blocking waits for child processes (or pseudo-processes) are
-supported via C<waitpid($pid, &POSIX::WNOHANG)>.
-
-=item *
-
-The behavior of system() with multiple arguments has been rationalized.
-Each unquoted argument will be automatically quoted to protect whitespace,
-and any existing whitespace in the arguments will be preserved. This
-improves the portability of system(@args) by avoiding the need for
-Windows C<cmd> shell specific quoting in perl programs.
-
-Note that this means that some scripts that may have relied on earlier
-buggy behavior may no longer work correctly. For example,
-C<system("nmake /nologo", @args)> will now attempt to run the file
-C<nmake /nologo> and will fail when such a file isn't found.
-On the other hand, perl will now execute code such as
-C<system("c:/Program Files/MyApp/foo.exe", @args)> correctly.
-
-=item *
-
-The perl header files no longer suppress common warnings from the
-Microsoft Visual C++ compiler. This means that additional warnings may
-now show up when compiling XS code.
-
-=item *
-
-Borland C++ v5.5 is now a supported compiler that can build Perl.
-However, the generated binaries continue to be incompatible with those
-generated by the other supported compilers (GCC and Visual C++). [561]
-
-=item *
-
-Duping socket handles with open(F, ">&MYSOCK") now works under Windows 9x.
-[561]
-
-=item *
-
-Current directory entries in %ENV are now correctly propagated to child
-processes. [561]
-
-=item *
-
-New %ENV entries now propagate to subprocesses. [561]
-
-=item *
-
-Win32::GetCwd() correctly returns C:\ instead of C: when at the drive root.
-Other bugs in chdir() and Cwd::cwd() have also been fixed. [561]
-
-=item *
-
-The makefiles now default to the features enabled in ActiveState ActivePerl
-(a popular Win32 binary distribution). [561]
-
-=item *
-
-HTML files will now be installed in c:\perl\html instead of
-c:\perl\lib\pod\html
-
-=item *
-
-REG_EXPAND_SZ keys are now allowed in registry settings used by perl. [561]
-
-=item *
-
-Can now send() from all threads, not just the first one. [561]
-
-=item *
-
-ExtUtils::MakeMaker now uses $ENV{LIB} to search for libraries. [561]
-
-=item *
-
-Less stack reserved per thread so that more threads can run
-concurrently. (Still 16M per thread.) [561]
-
-=item *
-
-C<< File::Spec->tmpdir() >> now prefers C:/temp over /tmp
-(works better when perl is running as service).
-
-=item *
-
-Better UNC path handling under ithreads. [561]
-
-=item *
-
-wait(), waitpid(), and backticks now return the correct exit status
-under Windows 9x. [561]
-
-=item *
-
-A socket handle leak in accept() has been fixed. [561]
-
-=back
-
-=back
-
-=head1 New or Changed Diagnostics
-
-Please see L<perldiag> for more details.
-
-=over 4
-
-=item *
-
-Ambiguous range in the transliteration operator (like a-z-9) now
-gives a warning.
-
-=item *
-
-chdir("") and chdir(undef) now give a deprecation warning because they
-cause a possible unintentional chdir to the home directory.
-Say chdir() if you really mean that.
-
-=item *
-
-Two new debugging options have been added: if you have compiled your
-Perl with debugging, you can use the -DT [561] and -DR options to trace
-tokenising and to add reference counts to displaying variables,
-respectively.
-
-=item *
-
-The lexical warnings category "deprecated" is no longer a sub-category
-of the "syntax" category. It is now a top-level category in its own
-right.
-
-=item *
-
-Unadorned dump() will now give a warning suggesting to
-use explicit CORE::dump() if that's what really is meant.
-
-=item *
-
-The "Unrecognized escape" warning has been extended to include C<\8>,
-C<\9>, and C<\_>. There is no need to escape any of the C<\w> characters.
-
-=item *
-
-All regular expression compilation error messages are now hopefully
-easier to understand both because the error message now comes before
-the failed regex and because the point of failure is now clearly
-marked by a C<E<lt>-- HERE> marker.
-
-=item *
-
-Various I/O (and socket) functions like binmode(), close(), and so
-forth now more consistently warn if they are used illogically either
-on a yet unopened or on an already closed filehandle (or socket).
-
-=item *
-
-Using lstat() on a filehandle now gives a warning. (It's a non-sensical
-thing to do.)
-
-=item *
-
-The C<-M> and C<-m> options now warn if you didn't supply the module name.
-
-=item *
-
-If you in C<use> specify a required minimum version, modules matching
-the name and but not defining a $VERSION will cause a fatal failure.
-
-=item *
-
-Using negative offset for vec() in lvalue context is now a warnable offense.
-
-=item *
-
-Odd number of arguments to overload::constant now elicits a warning.
-
-=item *
-
-Odd number of elements in anonymous hash now elicits a warning.
-
-=item *
-
-The various "opened only for", "on closed", "never opened" warnings
-drop the C<main::> prefix for filehandles in the C<main> package,
-for example C<STDIN> instead of C<main::STDIN>.
-
-=item *
-
-Subroutine prototypes are now checked more carefully, you may
-get warnings for example if you have used non-prototype characters.
-
-=item *
-
-If an attempt to use a (non-blessed) reference as an array index
-is made, a warning is given.
-
-=item *
-
-C<push @a;> and C<unshift @a;> (with no values to push or unshift)
-now give a warning. This may be a problem for generated and eval'ed
-code.
-
-=item *
-
-If you try to L<perlfunc/pack> a number less than 0 or larger than 255
-using the C<"C"> format you will get an optional warning. Similarly
-for the C<"c"> format and a number less than -128 or more than 127.
-
-=item *
-
-pack C<P> format now demands an explicit size.
-
-=item *
-
-unpack C<w> now warns of unterminated compressed integers.
-
-=item *
-
-Warnings relating to the use of PerlIO have been added.
-
-=item *
-
-Certain regex modifiers such as C<(?o)> make sense only if applied to
-the entire regex. You will get an optional warning if you try to do
-otherwise.
-
-=item *
-
-Variable length lookbehind has not yet been implemented, trying to
-use it will tell that.
-
-=item *
-
-Using arrays or hashes as references (e.g. C<< %foo->{bar} >>
-has been deprecated for a while. Now you will get an optional warning.
-
-=item *
-
-Warnings relating to the use of the new restricted hashes feature
-have been added.
-
-=item *
-
-Self-ties of arrays and hashes are not supported and fatal errors
-will happen even at an attempt to do so.
-
-=item *
-
-Using C<sort> in scalar context now issues an optional warning.
-This didn't do anything useful, as the sort was not performed.
-
-=item *
-
-Using the /g modifier in split() is meaningless and will cause a warning.
-
-=item *
-
-Using splice() past the end of an array now causes a warning.
-
-=item *
-
-Malformed Unicode encodings (UTF-8 and UTF-16) cause a lot of warnings,
-as does trying to use UTF-16 surrogates (which are unimplemented).
-
-=item *
-
-Trying to use Unicode characters on an I/O stream without marking the
-stream's encoding (using open() or binmode()) will cause "Wide character"
-warnings.
-
-=item *
-
-Use of v-strings in use/require causes a (backward) portability warning.
-
-=item *
-
-Warnings relating to the use interpreter threads and their shared data
-have been added.
-
-=back
-
-=head1 Changed Internals
-
-=over 4
-
-=item *
-
-PerlIO is now the default.
-
-=item *
-
-perlapi.pod (a companion to perlguts) now attempts to document the
-internal API.
-
-=item *
-
-You can now build a really minimal perl called microperl.
-Building microperl does not require even running Configure;
-C<make -f Makefile.micro> should be enough. Beware: microperl makes
-many assumptions, some of which may be too bold; the resulting
-executable may crash or otherwise misbehave in wondrous ways.
-For careful hackers only.
-
-=item *
-
-Added rsignal(), whichsig(), do_join(), op_clear, op_null,
-ptr_table_clear(), ptr_table_free(), sv_setref_uv(), and several UTF-8
-interfaces to the publicised API. For the full list of the available
-APIs see L<perlapi>.
-
-=item *
-
-Made possible to propagate customised exceptions via croak()ing.
-
-=item *
-
-Now xsubs can have attributes just like subs. (Well, at least the
-built-in attributes.)
-
-=item *
-
-dTHR and djSP have been obsoleted; the former removed (because it's
-a no-op) and the latter replaced with dSP.
-
-=item *
-
-PERL_OBJECT has been completely removed.
-
-=item *
-
-The MAGIC constants (e.g. C<'P'>) have been macrofied
-(e.g. C<PERL_MAGIC_TIED>) for better source code readability
-and maintainability.
-
-=item *
-
-The regex compiler now maintains a structure that identifies nodes in
-the compiled bytecode with the corresponding syntactic features of the
-original regex expression. The information is attached to the new
-C<offsets> member of the C<struct regexp>. See L<perldebguts> for more
-complete information.
-
-=item *
-
-The C code has been made much more C<gcc -Wall> clean. Some warning
-messages still remain in some platforms, so if you are compiling with
-gcc you may see some warnings about dubious practices. The warnings
-are being worked on.
-
-=item *
-
-F<perly.c>, F<sv.c>, and F<sv.h> have now been extensively commented.
-
-=item *
-
-Documentation on how to use the Perl source repository has been added
-to F<Porting/repository.pod>.
-
-=item *
-
-There are now several profiling make targets.
-
-=back
-
-=head1 Security Vulnerability Closed [561]
-
-(This change was already made in 5.7.0 but bears repeating here.)
-(5.7.0 came out before 5.6.1: the development branch 5.7 released
-earlier than the maintenance branch 5.6)
-
-A potential security vulnerability in the optional suidperl component
-of Perl was identified in August 2000. suidperl is neither built nor
-installed by default. As of November 2001 the only known vulnerable
-platform is Linux, most likely all Linux distributions. CERT and
-various vendors and distributors have been alerted about the vulnerability.
-See http://www.cpan.org/src/5.0/sperl-2000-08-05/sperl-2000-08-05.txt
-for more information.
-
-The problem was caused by Perl trying to report a suspected security
-exploit attempt using an external program, /bin/mail. On Linux
-platforms the /bin/mail program had an undocumented feature which
-when combined with suidperl gave access to a root shell, resulting in
-a serious compromise instead of reporting the exploit attempt. If you
-don't have /bin/mail, or if you have 'safe setuid scripts', or if
-suidperl is not installed, you are safe.
-
-The exploit attempt reporting feature has been completely removed from
-Perl 5.8.0 (and the maintenance release 5.6.1, and it was removed also
-from all the Perl 5.7 releases), so that particular vulnerability
-isn't there anymore. However, further security vulnerabilities are,
-unfortunately, always possible. The suidperl functionality is most
-probably going to be removed in Perl 5.10. In any case, suidperl
-should only be used by security experts who know exactly what they are
-doing and why they are using suidperl instead of some other solution
-such as sudo ( see http://www.courtesan.com/sudo/ ).
-
-=head1 New Tests
-
-Several new tests have been added, especially for the F<lib> and
-F<ext> subsections. There are now about 69 000 individual tests
-(spread over about 700 test scripts), in the regression suite (5.6.1
-has about 11 700 tests, in 258 test scripts) The exact numbers depend
-on the platform and Perl configuration used. Many of the new tests
-are of course introduced by the new modules, but still in general Perl
-is now more thoroughly tested.
-
-Because of the large number of tests, running the regression suite
-will take considerably longer time than it used to: expect the suite
-to take up to 4-5 times longer to run than in perl 5.6. On a really
-fast machine you can hope to finish the suite in about 6-8 minutes
-(wallclock time).
-
-The tests are now reported in a different order than in earlier Perls.
-(This happens because the test scripts from under t/lib have been moved
-to be closer to the library/extension they are testing.)
-
-=head1 Known Problems
-
-=head2 The Compiler Suite Is Still Very Experimental
-
-The compiler suite is slowly getting better but it continues to be
-highly experimental. Use in production environments is discouraged.
-
-=head2 Localising Tied Arrays and Hashes Is Broken
-
- local %tied_array;
-
-doesn't work as one would expect: the old value is restored
-incorrectly. This will be changed in a future release, but we don't
-know yet what the new semantics will exactly be. In any case, the
-change will break existing code that relies on the current
-(ill-defined) semantics, so just avoid doing this in general.
-
-=head2 Building Extensions Can Fail Because Of Largefiles
-
-Some extensions like mod_perl are known to have issues with
-`largefiles', a change brought by Perl 5.6.0 in which file offsets
-default to 64 bits wide, where supported. Modules may fail to compile
-at all, or they may compile and work incorrectly. Currently, there
-is no good solution for the problem, but Configure now provides
-appropriate non-largefile ccflags, ldflags, libswanted, and libs
-in the %Config hash (e.g., $Config{ccflags_nolargefiles}) so the
-extensions that are having problems can try configuring themselves
-without the largefileness. This is admittedly not a clean solution,
-and the solution may not even work at all. One potential failure is
-whether one can (or, if one can, whether it's a good idea to) link
-together at all binaries with different ideas about file offsets;
-all this is platform-dependent.
-
-=head2 Modifying $_ Inside for(..)
-
- for (1..5) { $_++ }
-
-works without complaint. It shouldn't. (You should be able to
-modify only lvalue elements inside the loops.) You can see the
-correct behaviour by replacing the 1..5 with 1, 2, 3, 4, 5.
-
-=head2 mod_perl 1.26 Doesn't Build With Threaded Perl
-
-Use mod_perl 1.27 or higher.
-
-=head2 lib/ftmp-security tests warn 'system possibly insecure'
-
-Don't panic. Read the 'make test' section of INSTALL instead.
-
-=head2 libwww-perl (LWP) fails base/date #51
-
-Use libwww-perl 5.65 or later.
-
-=head2 PDL failing some tests
-
-Use PDL 2.3.4 or later.
-
-=head2 Perl_get_sv
-
-You may get errors like 'Undefined symbol "Perl_get_sv"' or "can't
-resolve symbol 'Perl_get_sv'", or the symbol may be "Perl_sv_2pv".
-This probably means that you are trying to use an older shared Perl
-library (or extensions linked with such) with Perl 5.8.0 executable.
-Perl used to have such a subroutine, but that is no more the case.
-Check your shared library path, and any shared Perl libraries in those
-directories.
-
-Sometimes this problem may also indicate a partial Perl 5.8.0
-installation, see L</"Mac OS X dyld undefined symbols"> for an
-example and how to deal with it.
-
-=head2 Self-tying Problems
-
-Self-tying of arrays and hashes is broken in rather deep and
-hard-to-fix ways. As a stop-gap measure to avoid people from getting
-frustrated at the mysterious results (core dumps, most often), it is
-forbidden for now (you will get a fatal error even from an attempt).
-
-A change to self-tying of globs has caused them to be recursively
-referenced (see: L<perlobj/"Two-Phased Garbage Collection">). You
-will now need an explicit untie to destroy a self-tied glob. This
-behaviour may be fixed at a later date.
-
-Self-tying of scalars and IO thingies works.
-
-=head2 ext/threads/t/libc
-
-If this test fails, it indicates that your libc (C library) is not
-threadsafe. This particular test stress tests the localtime() call to
-find out whether it is threadsafe. See L<perlthrtut> for more information.
-
-=head2 Failure of Thread (5.005-style) tests
-
-B<Note that support for 5.005-style threading is deprecated,
-experimental and practically unsupported. In 5.10, it is expected
-to be removed. You should migrate your code to ithreads.>
-
-The following tests are known to fail due to fundamental problems in
-the 5.005 threading implementation. These are not new failures--Perl
-5.005_0x has the same bugs, but didn't have these tests.
-
- ../ext/B/t/xref.t 255 65280 14 12 85.71% 3-14
- ../ext/List/Util/t/first.t 255 65280 7 4 57.14% 2 5-7
- ../lib/English.t 2 512 54 2 3.70% 2-3
- ../lib/FileCache.t 5 1 20.00% 5
- ../lib/Filter/Simple/t/data.t 6 3 50.00% 1-3
- ../lib/Filter/Simple/t/filter_only. 9 3 33.33% 1-2 5
- ../lib/Math/BigInt/t/bare_mbf.t 1627 4 0.25% 8 11 1626-1627
- ../lib/Math/BigInt/t/bigfltpm.t 1629 4 0.25% 10 13 1628-
- 1629
- ../lib/Math/BigInt/t/sub_mbf.t 1633 4 0.24% 8 11 1632-1633
- ../lib/Math/BigInt/t/with_sub.t 1628 4 0.25% 9 12 1627-1628
- ../lib/Tie/File/t/31_autodefer.t 255 65280 65 32 49.23% 34-65
- ../lib/autouse.t 10 1 10.00% 4
- op/flip.t 15 1 6.67% 15
-
-These failures are unlikely to get fixed as 5.005-style threads
-are considered fundamentally broken. (Basically what happens is that
-competing threads can corrupt shared global state, one good example
-being regular expression engine's state.)
-
-=head2 Timing problems
-
-The following tests may fail intermittently because of timing
-problems, for example if the system is heavily loaded.
-
- t/op/alarm.t
- ext/Time/HiRes/HiRes.t
- lib/Benchmark.t
- lib/Memoize/t/expmod_t.t
- lib/Memoize/t/speed.t
-
-In case of failure please try running them manually, for example
-
- ./perl -Ilib ext/Time/HiRes/HiRes.t
-
-=head2 Tied/Magical Array/Hash Elements Do Not Autovivify
-
-For normal arrays C<$foo = \$bar[1]> will assign C<undef> to
-C<$bar[1]> (assuming that it didn't exist before), but for
-tied/magical arrays and hashes such autovivification does not happen
-because there is currently no way to catch the reference creation.
-The same problem affects slicing over non-existent indices/keys of
-a tied/magical array/hash.
-
-=head2 Unicode in package/class and subroutine names does not work
-
-One can have Unicode in identifier names, but not in package/class or
-subroutine names. While some limited functionality towards this does
-exist as of Perl 5.8.0, that is more accidental than designed; use of
-Unicode for the said purposes is unsupported.
-
-One reason of this unfinishedness is its (currently) inherent
-unportability: since both package names and subroutine names may
-need to be mapped to file and directory names, the Unicode capability
-of the filesystem becomes important-- and there unfortunately aren't
-portable answers.
-
-=head1 Platform Specific Problems
-
-=head2 AIX
-
-=over 4
-
-=item *
-
-If using the AIX native make command, instead of just "make" issue
-"make all". In some setups the former has been known to spuriously
-also try to run "make install". Alternatively, you may want to use
-GNU make.
-
-=item *
-
-In AIX 4.2, Perl extensions that use C++ functions that use statics
-may have problems in that the statics are not getting initialized.
-In newer AIX releases, this has been solved by linking Perl with
-the libC_r library, but unfortunately in AIX 4.2 the said library
-has an obscure bug where the various functions related to time
-(such as time() and gettimeofday()) return broken values, and
-therefore in AIX 4.2 Perl is not linked against libC_r.
-
-=item *
-
-vac 5.0.0.0 May Produce Buggy Code For Perl
-
-The AIX C compiler vac version 5.0.0.0 may produce buggy code,
-resulting in a few random tests failing when run as part of "make
-test", but when the failing tests are run by hand, they succeed.
-We suggest upgrading to at least vac version 5.0.1.0, that has been
-known to compile Perl correctly. "lslpp -L|grep vac.C" will tell
-you the vac version. See README.aix.
-
-=item *
-
-If building threaded Perl, you may get compilation warning from pp_sys.c:
-
- "pp_sys.c", line 4651.39: 1506-280 (W) Function argument assignment between types "unsigned char*" and "const void*" is not allowed.
-
-This is harmless; it is caused by the getnetbyaddr() and getnetbyaddr_r()
-having slightly different types for their first argument.
-
-=back
-
-=head2 Alpha systems with old gccs fail several tests
-
-If you see op/pack, op/pat, op/regexp, or ext/Storable tests failing
-in a Linux/alpha or *BSD/Alpha, it's probably time to upgrade your gcc.
-gccs prior to 2.95.3 are definitely not good enough, and gcc 3.1 may
-be even better. (RedHat Linux/alpha with gcc 3.1 reported no problems,
-as did Linux 2.4.18 with gcc 2.95.4.) (In Tru64, it is preferable to
-use the bundled C compiler.)
-
-=head2 AmigaOS
-
-Perl 5.8.0 doesn't build in AmigaOS. It broke at some point during
-the ithreads work and we could not find Amiga experts to unbreak the
-problems. Perl 5.6.1 still works for AmigaOS (as does the 5.7.2
-development release).
-
-=head2 BeOS
-
-The following tests fail on 5.8.0 Perl in BeOS Personal 5.03:
-
- t/op/lfs............................FAILED at test 17
- t/op/magic..........................FAILED at test 24
- ext/Fcntl/t/syslfs..................FAILED at test 17
- ext/File/Glob/t/basic...............FAILED at test 3
- ext/POSIX/t/sigaction...............FAILED at test 13
- ext/POSIX/t/waitpid.................FAILED at test 1
-
-See L<perlbeos> (README.beos) for more details.
-
-=head2 Cygwin "unable to remap"
-
-For example when building the Tk extension for Cygwin,
-you may get an error message saying "unable to remap".
-This is known problem with Cygwin, and a workaround is
-detailed in here: http://sources.redhat.com/ml/cygwin/2001-12/msg00894.html
-
-=head2 Cygwin ndbm tests fail on FAT
-
-One can build but not install (or test the build of) the NDBM_File
-on FAT filesystems. Installation (or build) on NTFS works fine.
-If one attempts the test on a FAT install (or build) the following
-failures are expected:
-
- ../ext/NDBM_File/ndbm.t 13 3328 71 59 83.10% 1-2 4 16-71
- ../ext/ODBM_File/odbm.t 255 65280 ?? ?? % ??
- ../lib/AnyDBM_File.t 2 512 12 2 16.67% 1 4
- ../lib/Memoize/t/errors.t 0 139 11 5 45.45% 7-11
- ../lib/Memoize/t/tie_ndbm.t 13 3328 4 4 100.00% 1-4
- run/fresh_perl.t 97 1 1.03% 91
-
-NDBM_File fails and ODBM_File just coredumps.
-
-If you intend to run only on FAT (or if using AnyDBM_File on FAT),
-run Configure with the -Ui_ndbm and -Ui_dbm options to prevent
-NDBM_File and ODBM_File being built.
-
-=head2 DJGPP Failures
-
- t/op/stat............................FAILED at test 29
- lib/File/Find/t/find.................FAILED at test 1
- lib/File/Find/t/taint................FAILED at test 1
- lib/h2xs.............................FAILED at test 15
- lib/Pod/t/eol........................FAILED at test 1
- lib/Test/Harness/t/strap-analyze.....FAILED at test 8
- lib/Test/Harness/t/test-harness......FAILED at test 23
- lib/Test/Simple/t/exit...............FAILED at test 1
-
-The above failures are known as of 5.8.0 with native builds with long
-filenames, but there are a few more if running under dosemu because of
-limitations (and maybe bugs) of dosemu:
-
- t/comp/cpp...........................FAILED at test 3
- t/op/inccode.........................(crash)
-
-and a few lib/ExtUtils tests, and several hundred Encode/t/Aliases.t
-failures that work fine with long filenames. So you really might
-prefer native builds and long filenames.
-
-=head2 FreeBSD built with ithreads coredumps reading large directories
-
-This is a known bug in FreeBSD 4.5's readdir_r(), it has been fixed in
-FreeBSD 4.6 (see L<perlfreebsd> (README.freebsd)).
-
-=head2 FreeBSD Failing locale Test 117 For ISO 8859-15 Locales
-
-The ISO 8859-15 locales may fail the locale test 117 in FreeBSD.
-This is caused by the characters \xFF (y with diaeresis) and \xBE
-(Y with diaeresis) not behaving correctly when being matched
-case-insensitively. Apparently this problem has been fixed in
-the latest FreeBSD releases.
-( http://www.freebsd.org/cgi/query-pr.cgi?pr=34308 )
-
-=head2 IRIX fails ext/List/Util/t/shuffle.t or Digest::MD5
-
-IRIX with MIPSpro 7.3.1.2m or 7.3.1.3m compiler may fail the List::Util
-test ext/List/Util/t/shuffle.t by dumping core. This seems to be
-a compiler error since if compiled with gcc no core dump ensues, and
-no failures have been seen on the said test on any other platform.
-
-Similarly, building the Digest::MD5 extension has been
-known to fail with "*** Termination code 139 (bu21)".
-
-The cure is to drop optimization level (Configure -Doptimize=-O2).
-
-=head2 HP-UX lib/posix Subtest 9 Fails When LP64-Configured
-
-If perl is configured with -Duse64bitall, the successful result of the
-subtest 10 of lib/posix may arrive before the successful result of the
-subtest 9, which confuses the test harness so much that it thinks the
-subtest 9 failed.
-
-=head2 Linux with glibc 2.2.5 fails t/op/int subtest #6 with -Duse64bitint
-
-This is a known bug in the glibc 2.2.5 with long long integers.
-( http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=65612 )
-
-=head2 Linux With Sfio Fails op/misc Test 48
-
-No known fix.
-
-=head2 Mac OS X
-
-Please remember to set your environment variable LC_ALL to "C"
-(setenv LC_ALL C) before running "make test" to avoid a lot of
-warnings about the broken locales of Mac OS X.
-
-The following tests are known to fail in Mac OS X 10.1.5 because of
-buggy (old) implementations of Berkeley DB included in Mac OS X:
-
- Failed Test Stat Wstat Total Fail Failed List of Failed
- -------------------------------------------------------------------------
- ../ext/DB_File/t/db-btree.t 0 11 ?? ?? % ??
- ../ext/DB_File/t/db-recno.t 149 3 2.01% 61 63 65
-
-If you are building on a UFS partition, you will also probably see
-t/op/stat.t subtest #9 fail. This is caused by Darwin's UFS not
-supporting inode change time.
-
-Also the ext/POSIX/t/posix.t subtest #10 fails but it is skipped for
-now because the failure is Apple's fault, not Perl's (blocked signals
-are lost).
-
-If you Configure with ithreads, ext/threads/t/libc.t will fail. Again,
-this is not Perl's fault-- the libc of Mac OS X is not threadsafe
-(in this particular test, the localtime() call is found to be
-threadunsafe.)
-
-=head2 Mac OS X dyld undefined symbols
-
-If after installing Perl 5.8.0 you are getting warnings about missing
-symbols, for example
-
- dyld: perl Undefined symbols
- _perl_sv_2pv
- _perl_get_sv
-
-you probably have an old pre-Perl-5.8.0 installation (or parts of one)
-in /Library/Perl (the undefined symbols used to exist in pre-5.8.0 Perls).
-It seems that for some reason "make install" doesn't always completely
-overwrite the files in /Library/Perl. You can move the old Perl
-shared library out of the way like this:
-
- cd /Library/Perl/darwin/CORE
- mv libperl.dylib libperlold.dylib
-
-and then reissue "make install". Note that the above of course is
-extremely disruptive for anything using the /usr/local/bin/perl.
-If that doesn't help, you may have to try removing all the .bundle
-files from beneath /Library/Perl, and again "make install"-ing.
-
-=head2 OS/2 Test Failures
-
-The following tests are known to fail on OS/2 (for clarity
-only the failures are shown, not the full error messages):
-
- ../lib/ExtUtils/t/Mkbootstrap.t 1 256 18 1 5.56% 8
- ../lib/ExtUtils/t/Packlist.t 1 256 34 1 2.94% 17
- ../lib/ExtUtils/t/basic.t 1 256 17 1 5.88% 14
- lib/os2_process.t 2 512 227 2 0.88% 174 209
- lib/os2_process_kid.t 227 2 0.88% 174 209
- lib/rx_cmprt.t 255 65280 18 3 16.67% 16-18
-
-=head2 op/sprintf tests 91, 129, and 130
-
-The op/sprintf tests 91, 129, and 130 are known to fail on some platforms.
-Examples include any platform using sfio, and Compaq/Tandem's NonStop-UX.
-
-Test 91 is known to fail on QNX6 (nto), because C<sprintf '%e',0>
-incorrectly produces C<0.000000e+0> instead of C<0.000000e+00>.
-
-For tests 129 and 130, the failing platforms do not comply with
-the ANSI C Standard: lines 19ff on page 134 of ANSI X3.159 1989, to
-be exact. (They produce something other than "1" and "-1" when
-formatting 0.6 and -0.6 using the printf format "%.0f"; most often,
-they produce "0" and "-0".)
-
-=head2 SCO
-
-The socketpair tests are known to be unhappy in SCO 3.2v5.0.4:
-
- ext/Socket/socketpair.t...............FAILED tests 15-45
-
-=head2 Solaris 2.5
-
-In case you are still using Solaris 2.5 (aka SunOS 5.5), you may
-experience failures (the test core dumping) in lib/locale.t.
-The suggested cure is to upgrade your Solaris.
-
-=head2 Solaris x86 Fails Tests With -Duse64bitint
-
-The following tests are known to fail in Solaris x86 with Perl
-configured to use 64 bit integers:
-
- ext/Data/Dumper/t/dumper.............FAILED at test 268
- ext/Devel/Peek/Peek..................FAILED at test 7
-
-=head2 SUPER-UX (NEC SX)
-
-The following tests are known to fail on SUPER-UX:
-
- op/64bitint...........................FAILED tests 29-30, 32-33, 35-36
- op/arith..............................FAILED tests 128-130
- op/pack...............................FAILED tests 25-5625
- op/pow................................
- op/taint..............................# msgsnd failed
- ../ext/IO/lib/IO/t/io_poll............FAILED tests 3-4
- ../ext/IPC/SysV/ipcsysv...............FAILED tests 2, 5-6
- ../ext/IPC/SysV/t/msg.................FAILED tests 2, 4-6
- ../ext/Socket/socketpair..............FAILED tests 12
- ../lib/IPC/SysV.......................FAILED tests 2, 5-6
- ../lib/warnings.......................FAILED tests 115-116, 118-119
-
-The op/pack failure ("Cannot compress negative numbers at op/pack.t line 126")
-is serious but as of yet unsolved. It points at some problems with the
-signedness handling of the C compiler, as do the 64bitint, arith, and pow
-failures. Most of the rest point at problems with SysV IPC.
-
-=head2 Term::ReadKey not working on Win32
-
-Use Term::ReadKey 2.20 or later.
-
-=head2 UNICOS/mk
-
-=over 4
-
-=item *
-
-During Configure, the test
-
- Guessing which symbols your C compiler and preprocessor define...
-
-will probably fail with error messages like
-
- CC-20 cc: ERROR File = try.c, Line = 3
- The identifier "bad" is undefined.
-
- bad switch yylook 79bad switch yylook 79bad switch yylook 79bad switch yylook 79#ifdef A29K
- ^
-
- CC-65 cc: ERROR File = try.c, Line = 3
- A semicolon is expected at this point.
-
-This is caused by a bug in the awk utility of UNICOS/mk. You can ignore
-the error, but it does cause a slight problem: you cannot fully
-benefit from the h2ph utility (see L<h2ph>) that can be used to
-convert C headers to Perl libraries, mainly used to be able to access
-from Perl the constants defined using C preprocessor, cpp. Because of
-the above error, parts of the converted headers will be invisible.
-Luckily, these days the need for h2ph is rare.
-
-=item *
-
-If building Perl with interpreter threads (ithreads), the
-getgrent(), getgrnam(), and getgrgid() functions cannot return the
-list of the group members due to a bug in the multithreaded support of
-UNICOS/mk. What this means is that in list context the functions will
-return only three values, not four.
-
-=back
-
-=head2 UTS
-
-There are a few known test failures, see L<perluts> (README.uts).
-
-=head2 VOS (Stratus)
-
-When Perl is built using the native build process on VOS Release
-14.5.0 and GNU C++/GNU Tools 2.0.1, all attempted tests either
-pass or result in TODO (ignored) failures.
-
-=head2 VMS
-
-There should be no reported test failures with a default configuration,
-though there are a number of tests marked TODO that point to areas
-needing further debugging and/or porting work.
-
-=head2 Win32
-
-In multi-CPU boxes, there are some problems with the I/O buffering:
-some output may appear twice.
-
-=head2 XML::Parser not working
-
-Use XML::Parser 2.31 or later.
-
-=head2 z/OS (OS/390)
-
-z/OS has rather many test failures but the situation is actually much
-better than it was in 5.6.0; it's just that so many new modules and
-tests have been added.
-
- Failed Test Stat Wstat Total Fail Failed List of Failed
- ---------------------------------------------------------------------------
- ../ext/Data/Dumper/t/dumper.t 357 8 2.24% 311 314 325 327
- 331 333 337 339
- ../ext/IO/lib/IO/t/io_unix.t 5 4 80.00% 2-5
- ../ext/Storable/t/downgrade.t 12 3072 169 12 7.10% 14-15 46-47 78-79
- 110-111 150 161
- ../lib/ExtUtils/t/Constant.t 121 30976 48 48 100.00% 1-48
- ../lib/ExtUtils/t/Embed.t 9 9 100.00% 1-9
- op/pat.t 922 7 0.76% 665 776 785 832-
- 834 845
- op/sprintf.t 224 3 1.34% 98 100 136
- op/tr.t 97 5 5.15% 63 71-74
- uni/fold.t 780 6 0.77% 61 169 196 661
- 710-711
-
-The failures in dumper.t and downgrade.t are problems in the tests,
-those in io_unix and sprintf are problems in the USS (UDP sockets and
-printf formats). The pat, tr, and fold failures are genuine Perl
-problems caused by EBCDIC (and in the pat and fold cases, combining
-that with Unicode). The Constant and Embed are probably problems in
-the tests (since they test Perl's ability to build extensions, and
-that seems to be working reasonably well.)
-
-=head2 Unicode Support on EBCDIC Still Spotty
-
-Though mostly working, Unicode support still has problem spots on
-EBCDIC platforms. One such known spot are the C<\p{}> and C<\P{}>
-regular expression constructs for code points less than 256: the
-C<pP> are testing for Unicode code points, not knowing about EBCDIC.
-
-=head2 Seen In Perl 5.7 But Gone Now
-
-C<Time::Piece> (previously known as C<Time::Object>) was removed
-because it was felt that it didn't have enough value in it to be a
-core module. It is still a useful module, though, and is available
-from the CPAN.
-
-Perl 5.8 unfortunately does not build anymore on AmigaOS; this broke
-accidentally at some point. Since there are not that many Amiga
-developers available, we could not get this fixed and tested in time
-for 5.8.0. Perl 5.6.1 still works for AmigaOS (as does the 5.7.2
-development release).
-
-The C<PerlIO::Scalar> and C<PerlIO::Via> (capitalised) were renamed as
-C<PerlIO::scalar> and C<PerlIO::via> (all lowercase) just before 5.8.0.
-The main rationale was to have all core PerlIO layers to have all
-lowercase names. The "plugins" are named as usual, for example
-C<PerlIO::via::QuotedPrint>.
-
-The C<threads::shared::queue> and C<threads::shared::semaphore> were
-renamed as C<Thread::Queue> and C<Thread::Semaphore> just before 5.8.0.
-The main rationale was to have thread modules to obey normal naming,
-C<Thread::> (the C<threads> and C<threads::shared> themselves are
-more pragma-like, they affect compile-time, so they stay lowercase).
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://bugs.perl.org/ . There may also be
-information at http://www.perl.com/ , the Perl Home Page.
-
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team.
-
-=head1 SEE ALSO
-
-The F<Changes> file for exhaustive details on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=head1 HISTORY
-
-Written by Jarkko Hietaniemi <F<jhi@iki.fi>>.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlaix.pod b/Master/tlpkg/tlperl/lib/pods/perlaix.pod
deleted file mode 100644
index 97e94abcf25..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlaix.pod
+++ /dev/null
@@ -1,489 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you see.
-It is written in the POD format (see pod/perlpod.pod) which is specially
-designed to be readable as is.
-
-=head1 NAME
-
-perlaix - Perl version 5 on IBM AIX (UNIX) systems
-
-=head1 DESCRIPTION
-
-This document describes various features of IBM's UNIX operating
-system AIX that will affect how Perl version 5 (hereafter just Perl)
-is compiled and/or runs.
-
-=head2 Compiling Perl 5 on AIX
-
-For information on compilers on older versions of AIX, see L<Compiling
-Perl 5 on older AIX versions up to 4.3.3>.
-
-When compiling Perl, you must use an ANSI C compiler. AIX does not ship
-an ANSI compliant C compiler with AIX by default, but binary builds of
-gcc for AIX are widely available. A version of gcc is also included in
-the AIX Toolbox which is shipped with AIX.
-
-=head2 Supported Compilers
-
-Currently all versions of IBM's "xlc", "xlc_r", "cc", "cc_r" or
-"vac" ANSI/C compiler will work for building Perl if that compiler
-works on your system.
-
-If you plan to link Perl to any module that requires thread-support,
-like DBD::Oracle, it is better to use the _r version of the compiler.
-This will not build a threaded Perl, but a thread-enabled Perl. See
-also L<Threaded Perl> later on.
-
-As of writing (2010-09) only the I<IBM XL C for AIX> or I<IBM XL C/C++
-for AIX> compiler is supported by IBM on AIX 5L/6.1/7.1.
-
-The following compiler versions are currently supported by IBM:
-
- IBM XL C and IBM XL C/C++ V8, V9, V10, V11
-
-The XL C for AIX is integrated in the XL C/C++ for AIX compiler and
-therefore also supported.
-
-If you choose XL C/C++ V9 you need APAR IZ35785 installed
-otherwise the integrated SDBM_File do not compile correctly due
-to an optimization bug. You can circumvent this problem by
-adding -qipa to the optimization flags (-Doptimize='-O -qipa').
-The PTF for APAR IZ35785 which solves this problem is available
-from IBM (April 2009 PTF for XL C/C++ Enterprise Edition for AIX, V9.0).
-
-If you choose XL C/C++ V11 you need the April 2010 PTF (or newer)
-installed otherwise you will not get a working Perl version.
-
-Perl can be compiled with either IBM's ANSI C compiler or with gcc.
-The former is recommended, as not only it can compile Perl with no
-difficulty, but also can take advantage of features listed later
-that require the use of IBM compiler-specific command-line flags.
-
-If you decide to use gcc, make sure your installation is recent and
-complete, and be sure to read the Perl INSTALL file for more gcc-specific
-details. Please report any hoops you had to jump through to the
-development team.
-
-=head2 Incompatibility with AIX Toolbox lib gdbm
-
-If the AIX Toolbox version of lib gdbm < 1.8.3-5 is installed on your
-system then Perl will not work. This library contains the header files
-/opt/freeware/include/gdbm/dbm.h|ndbm.h which conflict with the AIX
-system versions. The lib gdbm will be automatically removed from the
-wanted libraries if the presence of one of these two header files is
-detected. If you want to build Perl with GDBM support then please install
-at least gdbm-devel-1.8.3-5 (or higher).
-
-=head2 Perl 5 was successfully compiled and tested on:
-
- Perl | AIX Level | Compiler Level | w th | w/o th
- -------+---------------------+-------------------------+------+-------
- 5.12.2 |5.1 TL9 32 bit | XL C/C++ V7 | OK | OK
- 5.12.2 |5.1 TL9 64 bit | XL C/C++ V7 | OK | OK
- 5.12.2 |5.2 TL10 SP8 32 bit | XL C/C++ V8 | OK | OK
- 5.12.2 |5.2 TL10 SP8 32 bit | gcc 3.2.2 | OK | OK
- 5.12.2 |5.2 TL10 SP8 64 bit | XL C/C++ V8 | OK | OK
- 5.12.2 |5.3 TL8 SP8 32 bit | XL C/C++ V9 + IZ35785 | OK | OK
- 5.12.2 |5.3 TL8 SP8 32 bit | gcc 4.2.4 | OK | OK
- 5.12.2 |5.3 TL8 SP8 64 bit | XL C/C++ V9 + IZ35785 | OK | OK
- 5.12.2 |5.3 TL10 SP3 32 bit | XL C/C++ V11 + Apr 2010 | OK | OK
- 5.12.2 |5.3 TL10 SP3 64 bit | XL C/C++ V11 + Apr 2010 | OK | OK
- 5.12.2 |6.1 TL1 SP7 32 bit | XL C/C++ V10 | OK | OK
- 5.12.2 |6.1 TL1 SP7 64 bit | XL C/C++ V10 | OK | OK
- 5.13 |7.1 TL0 SP1 32 bit | XL C/C++ V11 + Jul 2010 | OK | OK
- 5.13 |7.1 TL0 SP1 64 bit | XL C/C++ V11 + Jul 2010 | OK | OK
-
- w th = with thread support
- w/o th = without thread support
- OK = tested
-
-Successfully tested means that all "make test" runs finish with a
-result of 100% OK. All tests were conducted with -Duseshrplib set.
-
-All tests were conducted on the oldest supported AIX technology level
-with the latest support package applied. If the tested AIX version is
-out of support (AIX 4.3.3, 5.1, 5.2) then the last available support
-level was used.
-
-=head2 Building Dynamic Extensions on AIX
-
-Starting from Perl 5.7.2 (and consequently 5.8.x / 5.10.x / 5.12.x)
-and AIX 4.3 or newer Perl uses the AIX native dynamic loading interface
-in the so called runtime linking mode instead of the emulated interface
-that was used in Perl releases 5.6.1 and earlier or, for AIX releases
-4.2 and earlier. This change does break backward compatibility with
-compiled modules from earlier Perl releases. The change was made to make
-Perl more compliant with other applications like Apache/mod_perl which are
-using the AIX native interface. This change also enables the use of
-C++ code with static constructors and destructors in Perl extensions,
-which was not possible using the emulated interface.
-
-It is highly recommended to use the new interface.
-
-=head2 Using Large Files with Perl
-
-Should yield no problems.
-
-=head2 Threaded Perl
-
-Should yield no problems with AIX 5.1 / 5.2 / 5.3 / 6.1 / 7.1.
-
-IBM uses the AIX system Perl (V5.6.0 on AIX 5.1 and V5.8.2 on
-AIX 5.2 / 5.3 and 6.1; V5.8.8 on AIX 5.3 TL11 and AIX 6.1 TL4; V5.10.1
-on AIX 7.1) for some AIX system scripts. If you switch the links in
-/usr/bin from the AIX system Perl (/usr/opt/perl5) to the newly build
-Perl then you get the same features as with the IBM AIX system Perl if
-the threaded options are used.
-
-The threaded Perl build works also on AIX 5.1 but the IBM Perl
-build (Perl v5.6.0) is not threaded on AIX 5.1.
-
-Perl 5.12 an newer is not compatible with the IBM fileset perl.libext.
-
-=head2 64-bit Perl
-
-If your AIX system is installed with 64-bit support, you can expect 64-bit
-configurations to work. If you want to use 64-bit Perl on AIX 6.1
-you need an APAR for a libc.a bug which affects (n)dbm_XXX functions.
-The APAR number for this problem is IZ39077.
-
-If you need more memory (larger data segment) for your Perl programs you
-can set:
-
- /etc/security/limits
- default: (or your user)
- data = -1 (default is 262144 * 512 byte)
-
-With the default setting the size is limited to 128MB.
-The -1 removes this limit. If the "make test" fails please change
-your /etc/security/limits as stated above.
-
-=head2 Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (threaded/32-bit)
-
-With the following options you get a threaded Perl version which
-passes all make tests in threaded 32-bit mode, which is the default
-configuration for the Perl builds that AIX ships with.
-
- rm config.sh
- ./Configure \
- -d \
- -Dcc=cc_r \
- -Duseshrplib \
- -Dusethreads \
- -Dprefix=/usr/opt/perl5_32
-
-The -Dprefix option will install Perl in a directory parallel to the
-IBM AIX system Perl installation.
-
-=head2 Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (32-bit)
-
-With the following options you get a Perl version which passes
-all make tests in 32-bit mode.
-
- rm config.sh
- ./Configure \
- -d \
- -Dcc=cc_r \
- -Duseshrplib \
- -Dprefix=/usr/opt/perl5_32
-
-The -Dprefix option will install Perl in a directory parallel to the
-IBM AIX system Perl installation.
-
-=head2 Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (threaded/64-bit)
-
-With the following options you get a threaded Perl version which
-passes all make tests in 64-bit mode.
-
- export OBJECT_MODE=64 / setenv OBJECT_MODE 64 (depending on your shell)
-
- rm config.sh
- ./Configure \
- -d \
- -Dcc=cc_r \
- -Duseshrplib \
- -Dusethreads \
- -Duse64bitall \
- -Dprefix=/usr/opt/perl5_64
-
-=head2 Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (64-bit)
-
-With the following options you get a Perl version which passes all
-make tests in 64-bit mode.
-
- export OBJECT_MODE=64 / setenv OBJECT_MODE 64 (depending on your shell)
-
- rm config.sh
- ./Configure \
- -d \
- -Dcc=cc_r \
- -Duseshrplib \
- -Duse64bitall \
- -Dprefix=/usr/opt/perl5_64
-
-The -Dprefix option will install Perl in a directory parallel to the
-IBM AIX system Perl installation.
-
-If you choose gcc to compile 64-bit Perl then you need to add the
-following option:
-
- -Dcc='gcc -maix64'
-
-
-=head2 Compiling Perl 5 on older AIX versions up to 4.3.3
-
-Due to the fact that AIX 4.3.3 reached end-of-service in December 31,
-2003 this information is provided as is. The Perl versions prior to
-Perl 5.8.9 could be compiled on AIX up to 4.3.3 with the following
-settings (your mileage may vary):
-
-When compiling Perl, you must use an ANSI C compiler. AIX does not ship
-an ANSI compliant C-compiler with AIX by default, but binary builds of
-gcc for AIX are widely available.
-
-At the moment of writing, AIX supports two different native C compilers,
-for which you have to pay: B<xlC> and B<vac>. If you decide to use either
-of these two (which is quite a lot easier than using gcc), be sure to
-upgrade to the latest available patch level. Currently:
-
- xlC.C 3.1.4.10 or 3.6.6.0 or 4.0.2.2 or 5.0.2.9 or 6.0.0.3
- vac.C 4.4.0.3 or 5.0.2.6 or 6.0.0.1
-
-note that xlC has the OS version in the name as of version 4.0.2.0, so
-you will find xlC.C for AIX-5.0 as package
-
- xlC.aix50.rte 5.0.2.0 or 6.0.0.3
-
-subversions are not the same "latest" on all OS versions. For example,
-the latest xlC-5 on aix41 is 5.0.2.9, while on aix43, it is 5.0.2.7.
-
-Perl can be compiled with either IBM's ANSI C compiler or with gcc.
-The former is recommended, as not only can it compile Perl with no
-difficulty, but also can take advantage of features listed later that
-require the use of IBM compiler-specific command-line flags.
-
-The IBM's compiler patch levels 5.0.0.0 and 5.0.1.0 have compiler
-optimization bugs that affect compiling perl.c and regcomp.c,
-respectively. If Perl's configuration detects those compiler patch
-levels, optimization is turned off for the said source code files.
-Upgrading to at least 5.0.2.0 is recommended.
-
-If you decide to use gcc, make sure your installation is recent and
-complete, and be sure to read the Perl INSTALL file for more gcc-specific
-details. Please report any hoops you had to jump through to the development
-team.
-
-=head2 OS level
-
-Before installing the patches to the IBM C-compiler you need to know the
-level of patching for the Operating System. IBM's command 'oslevel' will
-show the base, but is not always complete (in this example oslevel shows
-4.3.NULL, whereas the system might run most of 4.3.THREE):
-
- # oslevel
- 4.3.0.0
- # lslpp -l | grep 'bos.rte '
- bos.rte 4.3.3.75 COMMITTED Base Operating System Runtime
- bos.rte 4.3.2.0 COMMITTED Base Operating System Runtime
- #
-
-The same might happen to AIX 5.1 or other OS levels. As a side note, Perl
-cannot be built without bos.adt.syscalls and bos.adt.libm installed
-
- # lslpp -l | egrep "syscalls|libm"
- bos.adt.libm 5.1.0.25 COMMITTED Base Application Development
- bos.adt.syscalls 5.1.0.36 COMMITTED System Calls Application
- #
-
-=head2 Building Dynamic Extensions on AIX E<lt> 5L
-
-AIX supports dynamically loadable objects as well as shared libraries.
-Shared libraries by convention end with the suffix .a, which is a bit
-misleading, as an archive can contain static as well as dynamic members.
-For Perl dynamically loaded objects we use the .so suffix also used on
-many other platforms.
-
-Note that starting from Perl 5.7.2 (and consequently 5.8.0) and AIX 4.3
-or newer Perl uses the AIX native dynamic loading interface in the so
-called runtime linking mode instead of the emulated interface that was
-used in Perl releases 5.6.1 and earlier or, for AIX releases 4.2 and
-earlier. This change does break backward compatibility with compiled
-modules from earlier Perl releases. The change was made to make Perl
-more compliant with other applications like Apache/mod_perl which are
-using the AIX native interface. This change also enables the use of C++
-code with static constructors and destructors in Perl extensions, which
-was not possible using the emulated interface.
-
-=head2 The IBM ANSI C Compiler
-
-All defaults for Configure can be used.
-
-If you've chosen to use vac 4, be sure to run 4.4.0.3. Older versions
-will turn up nasty later on. For vac 5 be sure to run at least 5.0.1.0,
-but vac 5.0.2.6 or up is highly recommended. Note that since IBM has
-removed vac 5.0.2.1 through 5.0.2.5 from the software depot, these
-versions should be considered obsolete.
-
-Here's a brief lead of how to upgrade the compiler to the latest
-level. Of course this is subject to changes. You can only upgrade
-versions from ftp-available updates if the first three digit groups
-are the same (in where you can skip intermediate unlike the patches
-in the developer snapshots of Perl), or to one version up where the
-"base" is available. In other words, the AIX compiler patches are
-cumulative.
-
- vac.C.4.4.0.1 => vac.C.4.4.0.3 is OK (vac.C.4.4.0.2 not needed)
- xlC.C.3.1.3.3 => xlC.C.3.1.4.10 is NOT OK (xlC.C.3.1.4.0 is not available)
-
- # ftp ftp.software.ibm.com
- Connected to service.boulder.ibm.com.
- : welcome message ...
- Name (ftp.software.ibm.com:merijn): anonymous
- 331 Guest login ok, send your complete e-mail address as password.
- Password:
- ... accepted login stuff
- ftp> cd /aix/fixes/v4/
- ftp> dir other other.ll
- output to local-file: other.ll? y
- 200 PORT command successful.
- 150 Opening ASCII mode data connection for /bin/ls.
- 226 Transfer complete.
- ftp> dir xlc xlc.ll
- output to local-file: xlc.ll? y
- 200 PORT command successful.
- 150 Opening ASCII mode data connection for /bin/ls.
- 226 Transfer complete.
- ftp> bye
- ... goodbye messages
- # ls -l *.ll
- -rw-rw-rw- 1 merijn system 1169432 Nov 2 17:29 other.ll
- -rw-rw-rw- 1 merijn system 29170 Nov 2 17:29 xlc.ll
-
-On AIX 4.2 using xlC, we continue:
-
- # lslpp -l | fgrep 'xlC.C '
- xlC.C 3.1.4.9 COMMITTED C for AIX Compiler
- xlC.C 3.1.4.0 COMMITTED C for AIX Compiler
- # grep 'xlC.C.3.1.4.*.bff' xlc.ll
- -rw-r--r-- 1 45776101 1 6286336 Jul 22 1996 xlC.C.3.1.4.1.bff
- -rw-rw-r-- 1 45776101 1 6173696 Aug 24 1998 xlC.C.3.1.4.10.bff
- -rw-r--r-- 1 45776101 1 6319104 Aug 14 1996 xlC.C.3.1.4.2.bff
- -rw-r--r-- 1 45776101 1 6316032 Oct 21 1996 xlC.C.3.1.4.3.bff
- -rw-r--r-- 1 45776101 1 6315008 Dec 20 1996 xlC.C.3.1.4.4.bff
- -rw-rw-r-- 1 45776101 1 6178816 Mar 28 1997 xlC.C.3.1.4.5.bff
- -rw-rw-r-- 1 45776101 1 6188032 May 22 1997 xlC.C.3.1.4.6.bff
- -rw-rw-r-- 1 45776101 1 6191104 Sep 5 1997 xlC.C.3.1.4.7.bff
- -rw-rw-r-- 1 45776101 1 6185984 Jan 13 1998 xlC.C.3.1.4.8.bff
- -rw-rw-r-- 1 45776101 1 6169600 May 27 1998 xlC.C.3.1.4.9.bff
- # wget ftp://ftp.software.ibm.com/aix/fixes/v4/xlc/xlC.C.3.1.4.10.bff
- #
-
-On AIX 4.3 using vac, we continue:
-
- # lslpp -l | grep 'vac.C '
- vac.C 5.0.2.2 COMMITTED C for AIX Compiler
- vac.C 5.0.2.0 COMMITTED C for AIX Compiler
- # grep 'vac.C.5.0.2.*.bff' other.ll
- -rw-rw-r-- 1 45776101 1 13592576 Apr 16 2001 vac.C.5.0.2.0.bff
- -rw-rw-r-- 1 45776101 1 14133248 Apr 9 2002 vac.C.5.0.2.3.bff
- -rw-rw-r-- 1 45776101 1 14173184 May 20 2002 vac.C.5.0.2.4.bff
- -rw-rw-r-- 1 45776101 1 14192640 Nov 22 2002 vac.C.5.0.2.6.bff
- # wget ftp://ftp.software.ibm.com/aix/fixes/v4/other/vac.C.5.0.2.6.bff
- #
-
-Likewise on all other OS levels. Then execute the following command, and
-fill in its choices
-
- # smit install_update
- -> Install and Update from LATEST Available Software
- * INPUT device / directory for software [ vac.C.5.0.2.6.bff ]
- [ OK ]
- [ OK ]
-
-Follow the messages ... and you're done.
-
-If you like a more web-like approach, a good start point can be
-http://www14.software.ibm.com/webapp/download/downloadaz.jsp and click
-"C for AIX", and follow the instructions.
-
-=head2 The usenm option
-
-If linking miniperl
-
- cc -o miniperl ... miniperlmain.o opmini.o perl.o ... -lm -lc ...
-
-causes error like this
-
- ld: 0711-317 ERROR: Undefined symbol: .aintl
- ld: 0711-317 ERROR: Undefined symbol: .copysignl
- ld: 0711-317 ERROR: Undefined symbol: .syscall
- ld: 0711-317 ERROR: Undefined symbol: .eaccess
- ld: 0711-317 ERROR: Undefined symbol: .setresuid
- ld: 0711-317 ERROR: Undefined symbol: .setresgid
- ld: 0711-317 ERROR: Undefined symbol: .setproctitle
- ld: 0711-345 Use the -bloadmap or -bnoquiet option to obtain more information.
-
-you could retry with
-
- make realclean
- rm config.sh
- ./Configure -Dusenm ...
-
-which makes Configure to use the C<nm> tool when scanning for library
-symbols, which usually is not done in AIX.
-
-Related to this, you probably should not use the C<-r> option of
-Configure in AIX, because that affects of how the C<nm> tool is used.
-
-=head2 Using GNU's gcc for building Perl
-
-Using gcc-3.x (tested with 3.0.4, 3.1, and 3.2) now works out of the box,
-as do recent gcc-2.9 builds available directly from IBM as part of their
-Linux compatibility packages, available here:
-
- http://www.ibm.com/servers/aix/products/aixos/linux/
-
-=head2 Using Large Files with Perl E<lt> 5L
-
-Should yield no problems.
-
-=head2 Threaded Perl E<lt> 5L
-
-Threads seem to work OK, though at the moment not all tests pass when
-threads are used in combination with 64-bit configurations.
-
-You may get a warning when doing a threaded build:
-
- "pp_sys.c", line 4640.39: 1506-280 (W) Function argument assignment
- between types "unsigned char*" and "const void*" is not allowed.
-
-The exact line number may vary, but if the warning (W) comes from a line
-line this
-
- hent = PerlSock_gethostbyaddr(addr, (Netdb_hlen_t) addrlen, addrtype);
-
-in the "pp_ghostent" function, you may ignore it safely. The warning
-is caused by the reentrant variant of gethostbyaddr() having a slightly
-different prototype than its non-reentrant variant, but the difference
-is not really significant here.
-
-=head2 64-bit Perl E<lt> 5L
-
-If your AIX is installed with 64-bit support, you can expect 64-bit
-configurations to work. In combination with threads some tests might
-still fail.
-
-=head2 AIX 4.2 and extensions using C++ with statics
-
-In AIX 4.2 Perl extensions that use C++ functions that use statics
-may have problems in that the statics are not getting initialized.
-In newer AIX releases this has been solved by linking Perl with
-the libC_r library, but unfortunately in AIX 4.2 the said library
-has an obscure bug where the various functions related to time
-(such as time() and gettimeofday()) return broken values, and
-therefore in AIX 4.2 Perl is not linked against the libC_r.
-
-=head1 AUTHORS
-
-Rainer Tammer <tammer@tammer.net>
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlamiga.pod b/Master/tlpkg/tlperl/lib/pods/perlamiga.pod
deleted file mode 100644
index c86adefe7b4..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlamiga.pod
+++ /dev/null
@@ -1,278 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see perlpod manpage) which is
-specially designed to be readable as is.
-
-=head1 NAME
-
-perlamiga - Perl under Amiga OS
-
-=head1 NOTE
-
-B<Perl 5.8.0 cannot be built in AmigaOS. You can use either the
-maintenance release Perl 5.6.1 or the development release Perl 5.7.2
-in AmigaOS. See L</"PERL 5.8.0 BROKEN IN AMIGAOS"> if you want to help
-fixing this problem.>
-
-=head1 SYNOPSIS
-
-One can read this document in the following formats:
-
- man perlamiga
- multiview perlamiga.guide
-
-to list some (not all may be available simultaneously), or it may
-be read I<as is>: either as F<README.amiga>, or F<pod/perlamiga.pod>.
-
-A recent version of perl for the Amiga can be found at the Geek Gadgets
-section of the Aminet:
-
- http://www.aminet.net/~aminet/dev/gg
-
-=cut
-
-Contents
-
- perlamiga - Perl under Amiga OS
-
- NAME
- SYNOPSIS
- DESCRIPTION
- - Prerequisites
- - Starting Perl programs under AmigaOS
- - Shortcomings of Perl under AmigaOS
- INSTALLATION
- Accessing documentation
- - Manpages
- - HTML
- - GNU info files
- - LaTeX docs
- BUILD
- - Build Prerequisites
- - Getting the perl source
- - Application of the patches
- - Making
- - Testing
- - Installing the built perl
- AUTHOR
- SEE ALSO
-
-=head1 DESCRIPTION
-
-=head2 Prerequisites for Compiling Perl on AmigaOS
-
-=over 6
-
-=item B<Unix emulation for AmigaOS: ixemul.library>
-
-You need the Unix emulation for AmigaOS, whose most important part is
-B<ixemul.library>. For a minimum setup, get the latest versions
-of the following packages from the Aminet archives
-( L<http://www.aminet.net/~aminet/> ):
-
- ixemul-bin
- ixemul-env-bin
- pdksh-bin
-
-Note also that this is a minimum setup; you might want to add other
-packages of B<ADE> (the I<Amiga Developers Environment>).
-
-=item B<Version of Amiga OS>
-
-You need at the very least AmigaOS version 2.0. Recommended is version 3.1.
-
-=back
-
-=head2 Starting Perl programs under AmigaOS
-
-Start your Perl program F<foo> with arguments C<arg1 arg2 arg3> the
-same way as on any other platform, by
-
- perl foo arg1 arg2 arg3
-
-If you want to specify perl options C<-my_opts> to the perl itself (as
-opposed to your program), use
-
- perl -my_opts foo arg1 arg2 arg3
-
-Alternately, you can try to get a replacement for the system's B<Execute>
-command that honors the #!/usr/bin/perl syntax in scripts and set the s-Bit
-of your scripts. Then you can invoke your scripts like under UNIX with
-
- foo arg1 arg2 arg3
-
-(Note that having *nixish full path to perl F</usr/bin/perl> is not
-necessary, F<perl> would be enough, but having full path would make it
-easier to use your script under *nix.)
-
-=head2 Shortcomings of Perl under AmigaOS
-
-Perl under AmigaOS lacks some features of perl under UNIX because of
-deficiencies in the UNIX-emulation, most notably:
-
-=over 6
-
-=item *
-
-fork()
-
-=item *
-
-some features of the UNIX filesystem regarding link count and file dates
-
-=item *
-
-inplace operation (the -i switch) without backup file
-
-=item *
-
-umask() works, but the correct permissions are only set when the file is
-finally close()d
-
-=back
-
-=head1 INSTALLATION
-
-Change to the installation directory (most probably ADE:), and
-extract the binary distribution:
-
-lha -mraxe x perl-$VERSION-bin.lha
-
-or
-
-tar xvzpf perl-$VERSION-bin.tgz
-
-(Of course you need lha or tar and gunzip for this.)
-
-For installation of the Unix emulation, read the appropriate docs.
-
-=head1 Accessing documentation
-
-=head2 Manpages for Perl on AmigaOS
-
-If you have C<man> installed on your system, and you installed perl
-manpages, use something like this:
-
- man perlfunc
- man less
- man ExtUtils.MakeMaker
-
-to access documentation for different components of Perl. Start with
-
- man perl
-
-Note: You have to modify your man.conf file to search for manpages
-in the /ade/lib/perl5/man/man3 directory, or the man pages for the
-perl library will not be found.
-
-Note that dot (F<.>) is used as a package separator for documentation
-for packages, and as usual, sometimes you need to give the section - C<3>
-above - to avoid shadowing by the I<less(1) manpage>.
-
-
-=head2 Perl HTML Documentation on AmigaOS
-
-If you have some WWW browser available, you can build B<HTML> docs.
-Cd to directory with F<.pod> files, and do like this
-
- cd /ade/lib/perl5/pod
- pod2html
-
-After this you can direct your browser the file F<perl.html> in this
-directory, and go ahead with reading docs.
-
-Alternatively you may be able to get these docs prebuilt from C<CPAN>.
-
-=head2 Perl GNU Info Files on AmigaOS
-
-Users of C<Emacs> would appreciate it very much, especially with
-C<CPerl> mode loaded. You need to get latest C<pod2info> from C<CPAN>,
-or, alternately, prebuilt info pages.
-
-=head2 Perl LaTeX Documentation on AmigaOS
-
-Can be constructed using C<pod2latex>.
-
-=head1 BUILDING PERL ON AMIGAOS
-
-Here we discuss how to build Perl under AmigaOS.
-
-=head2 Build Prerequisites for Perl on AmigaOS
-
-You need to have the latest B<ixemul> (Unix emulation for Amiga)
-from Aminet.
-
-=head2 Getting the Perl Source for AmigaOS
-
-You can either get the latest perl-for-amiga source from Ninemoons
-and extract it with:
-
- tar xvzpf perl-$VERSION-src.tgz
-
-or get the official source from CPAN:
-
- http://www.cpan.org/src/5.0
-
-Extract it like this
-
- tar xvzpf perl-$VERSION.tar.gz
-
-You will see a message about errors while extracting F<Configure>. This
-is normal and expected. (There is a conflict with a similarly-named file
-F<configure>, but it causes no harm.)
-
-=head2 Making Perl on AmigaOS
-
-Remember to use a hefty wad of stack (I use 2000000)
-
- sh configure.gnu --prefix=/gg
-
-Now type
-
- make depend
-
-Now!
-
- make
-
-=head2 Testing Perl on AmigaOS
-
-Now run
-
- make test
-
-Some tests will be skipped because they need the fork() function:
-
-F<io/pipe.t>, F<op/fork.t>, F<lib/filehand.t>, F<lib/open2.t>, F<lib/open3.t>,
-F<lib/io_pipe.t>, F<lib/io_sock.t>
-
-=head2 Installing the built Perl on AmigaOS
-
-Run
-
- make install
-
-=head1 PERL 5.8.0 BROKEN IN AMIGAOS
-
-As told above, Perl 5.6.1 was still good in AmigaOS, as was 5.7.2.
-After Perl 5.7.2 (change #11423, see the Changes file, and the file
-pod/perlhack.pod for how to get the individual changes) Perl dropped
-its internal support for vfork(), and that was very probably the step
-that broke AmigaOS (since the ixemul library has only vfork).
-The build finally fails when the ext/DynaLoader is being built, and
-PERL ends up as "0" in the produced Makefile, trying to run "0" does
-not quite work. Also, executing miniperl in backticks seems to
-generate nothing: very probably related to the (v)fork problems.
-B<Fixing the breakage requires someone quite familiar with the ixemul
-library, and how one is supposed to run external commands in AmigaOS
-without fork().>
-
-=head1 AUTHORS
-
-Norbert Pueschel, pueschel@imsdd.meb.uni-bonn.de
-Jan-Erik Karlsson, trg@privat.utfors.se
-
-=head1 SEE ALSO
-
-perl(1).
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlapi.pod b/Master/tlpkg/tlperl/lib/pods/perlapi.pod
deleted file mode 100644
index 57ddb06f97f..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlapi.pod
+++ /dev/null
@@ -1,12932 +0,0 @@
--*- buffer-read-only: t -*-
-
-!!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-This file is built by ..\autodoc.pl extracting documentation from the C source
-files.
-
-=head1 NAME
-
-perlapi - autogenerated documentation for the perl public API
-
-=head1 DESCRIPTION
-X<Perl API> X<API> X<api>
-
-This file contains the documentation of the perl public API generated by
-F<embed.pl>, specifically a listing of functions, macros, flags, and variables
-that may be used by extension writers. L<At the end|/Undocumented functions>
-is a list of functions which have yet to be documented. The interfaces of
-those are subject to change without notice. Any functions not listed here are
-not part of the public API, and should not be used by extension writers at
-all. For these reasons, blindly using functions listed in proto.h is to be
-avoided when writing extensions.
-
-Note that all Perl API global variables must be referenced with the C<PL_>
-prefix. Some macros are provided for compatibility with the older,
-unadorned names, but this support may be disabled in a future release.
-
-Perl was originally written to handle US-ASCII only (that is characters
-whose ordinal numbers are in the range 0 - 127).
-And documentation and comments may still use the term ASCII, when
-sometimes in fact the entire range from 0 - 255 is meant.
-
-Note that Perl can be compiled and run under EBCDIC (See L<perlebcdic>)
-or ASCII. Most of the documentation (and even comments in the code)
-ignore the EBCDIC possibility.
-For almost all purposes the differences are transparent.
-As an example, under EBCDIC,
-instead of UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so
-whenever this documentation refers to C<utf8>
-(and variants of that name, including in function names),
-it also (essentially transparently) means C<UTF-EBCDIC>.
-But the ordinals of characters differ between ASCII, EBCDIC, and
-the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy more bytes
-than in UTF-8.
-
-Also, on some EBCDIC machines, functions that are documented as operating on
-US-ASCII (or Basic Latin in Unicode terminology) may in fact operate on all
-256 characters in the EBCDIC range, not just the subset corresponding to
-US-ASCII.
-
-The listing below is alphabetical, case insensitive.
-
-
-=head1 "Gimme" Values
-
-=over 8
-
-=item GIMME
-X<GIMME>
-
-A backward-compatible version of C<GIMME_V> which can only return
-C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
-Deprecated. Use C<GIMME_V> instead.
-
- U32 GIMME
-
-=for hackers
-Found in file op.h
-
-=item GIMME_V
-X<GIMME_V>
-
-The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>,
-C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
-respectively. See L<perlcall> for a usage example.
-
- U32 GIMME_V
-
-=for hackers
-Found in file op.h
-
-=item G_ARRAY
-X<G_ARRAY>
-
-Used to indicate list context. See C<GIMME_V>, C<GIMME> and
-L<perlcall>.
-
-=for hackers
-Found in file cop.h
-
-=item G_DISCARD
-X<G_DISCARD>
-
-Indicates that arguments returned from a callback should be discarded. See
-L<perlcall>.
-
-=for hackers
-Found in file cop.h
-
-=item G_EVAL
-X<G_EVAL>
-
-Used to force a Perl C<eval> wrapper around a callback. See
-L<perlcall>.
-
-=for hackers
-Found in file cop.h
-
-=item G_NOARGS
-X<G_NOARGS>
-
-Indicates that no arguments are being sent to a callback. See
-L<perlcall>.
-
-=for hackers
-Found in file cop.h
-
-=item G_SCALAR
-X<G_SCALAR>
-
-Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and
-L<perlcall>.
-
-=for hackers
-Found in file cop.h
-
-=item G_VOID
-X<G_VOID>
-
-Used to indicate void context. See C<GIMME_V> and L<perlcall>.
-
-=for hackers
-Found in file cop.h
-
-
-=back
-
-=head1 Array Manipulation Functions
-
-=over 8
-
-=item AvFILL
-X<AvFILL>
-
-Same as C<av_len()>. Deprecated, use C<av_len()> instead.
-
- int AvFILL(AV* av)
-
-=for hackers
-Found in file av.h
-
-=item av_clear
-X<av_clear>
-
-Clears an array, making it empty. Does not free the memory the av uses to
-store its list of scalars. If any destructors are triggered as a result,
-the av itself may be freed when this function returns.
-
-Perl equivalent: C<@myarray = ();>.
-
- void av_clear(AV *av)
-
-=for hackers
-Found in file av.c
-
-=item av_create_and_push
-X<av_create_and_push>
-
-Push an SV onto the end of the array, creating the array if necessary.
-A small internal helper function to remove a commonly duplicated idiom.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void av_create_and_push(AV **const avp,
- SV *const val)
-
-=for hackers
-Found in file av.c
-
-=item av_create_and_unshift_one
-X<av_create_and_unshift_one>
-
-Unshifts an SV onto the beginning of the array, creating the array if
-necessary.
-A small internal helper function to remove a commonly duplicated idiom.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- SV** av_create_and_unshift_one(AV **const avp,
- SV *const val)
-
-=for hackers
-Found in file av.c
-
-=item av_delete
-X<av_delete>
-
-Deletes the element indexed by C<key> from the array, makes the element mortal,
-and returns it. If C<flags> equals C<G_DISCARD>, the element is freed and null
-is returned. Perl equivalent: C<my $elem = delete($myarray[$idx]);> for the
-non-C<G_DISCARD> version and a void-context C<delete($myarray[$idx]);> for the
-C<G_DISCARD> version.
-
- SV* av_delete(AV *av, I32 key, I32 flags)
-
-=for hackers
-Found in file av.c
-
-=item av_exists
-X<av_exists>
-
-Returns true if the element indexed by C<key> has been initialized.
-
-This relies on the fact that uninitialized array elements are set to
-C<&PL_sv_undef>.
-
-Perl equivalent: C<exists($myarray[$key])>.
-
- bool av_exists(AV *av, I32 key)
-
-=for hackers
-Found in file av.c
-
-=item av_extend
-X<av_extend>
-
-Pre-extend an array. The C<key> is the index to which the array should be
-extended.
-
- void av_extend(AV *av, I32 key)
-
-=for hackers
-Found in file av.c
-
-=item av_fetch
-X<av_fetch>
-
-Returns the SV at the specified index in the array. The C<key> is the
-index. If lval is true, you are guaranteed to get a real SV back (in case
-it wasn't real before), which you can then modify. Check that the return
-value is non-null before dereferencing it to a C<SV*>.
-
-See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
-more information on how to use this function on tied arrays.
-
-The rough perl equivalent is C<$myarray[$idx]>.
-
- SV** av_fetch(AV *av, I32 key, I32 lval)
-
-=for hackers
-Found in file av.c
-
-=item av_fill
-X<av_fill>
-
-Set the highest index in the array to the given number, equivalent to
-Perl's C<$#array = $fill;>.
-
-The number of elements in the an array will be C<fill + 1> after
-av_fill() returns. If the array was previously shorter, then the
-additional elements appended are set to C<PL_sv_undef>. If the array
-was longer, then the excess elements are freed. C<av_fill(av, -1)> is
-the same as C<av_clear(av)>.
-
- void av_fill(AV *av, I32 fill)
-
-=for hackers
-Found in file av.c
-
-=item av_len
-X<av_len>
-
-Returns the highest index in the array. The number of elements in the
-array is C<av_len(av) + 1>. Returns -1 if the array is empty.
-
-The Perl equivalent for this is C<$#myarray>.
-
- I32 av_len(AV *av)
-
-=for hackers
-Found in file av.c
-
-=item av_make
-X<av_make>
-
-Creates a new AV and populates it with a list of SVs. The SVs are copied
-into the array, so they may be freed after the call to av_make. The new AV
-will have a reference count of 1.
-
-Perl equivalent: C<my @new_array = ($scalar1, $scalar2, $scalar3...);>
-
- AV* av_make(I32 size, SV **strp)
-
-=for hackers
-Found in file av.c
-
-=item av_pop
-X<av_pop>
-
-Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array
-is empty.
-
-Perl equivalent: C<pop(@myarray);>
-
- SV* av_pop(AV *av)
-
-=for hackers
-Found in file av.c
-
-=item av_push
-X<av_push>
-
-Pushes an SV onto the end of the array. The array will grow automatically
-to accommodate the addition. This takes ownership of one reference count.
-
-Perl equivalent: C<push @myarray, $elem;>.
-
- void av_push(AV *av, SV *val)
-
-=for hackers
-Found in file av.c
-
-=item av_shift
-X<av_shift>
-
-Shifts an SV off the beginning of the
-array. Returns C<&PL_sv_undef> if the
-array is empty.
-
-Perl equivalent: C<shift(@myarray);>
-
- SV* av_shift(AV *av)
-
-=for hackers
-Found in file av.c
-
-=item av_store
-X<av_store>
-
-Stores an SV in an array. The array index is specified as C<key>. The
-return value will be NULL if the operation failed or if the value did not
-need to be actually stored within the array (as in the case of tied
-arrays). Otherwise, it can be dereferenced
-to get the C<SV*> that was stored
-there (= C<val>)).
-
-Note that the caller is responsible for suitably incrementing the reference
-count of C<val> before the call, and decrementing it if the function
-returned NULL.
-
-Approximate Perl equivalent: C<$myarray[$key] = $val;>.
-
-See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
-more information on how to use this function on tied arrays.
-
- SV** av_store(AV *av, I32 key, SV *val)
-
-=for hackers
-Found in file av.c
-
-=item av_undef
-X<av_undef>
-
-Undefines the array. Frees the memory used by the av to store its list of
-scalars. If any destructors are triggered as a result, the av itself may
-be freed.
-
- void av_undef(AV *av)
-
-=for hackers
-Found in file av.c
-
-=item av_unshift
-X<av_unshift>
-
-Unshift the given number of C<undef> values onto the beginning of the
-array. The array will grow automatically to accommodate the addition. You
-must then use C<av_store> to assign values to these new elements.
-
-Perl equivalent: C<unshift @myarray, ( (undef) x $n );>
-
- void av_unshift(AV *av, I32 num)
-
-=for hackers
-Found in file av.c
-
-=item get_av
-X<get_av>
-
-Returns the AV of the specified Perl global or package array with the given
-name (so it won't work on lexical variables). C<flags> are passed
-to C<gv_fetchpv>. If C<GV_ADD> is set and the
-Perl variable does not exist then it will be created. If C<flags> is zero
-and the variable does not exist then NULL is returned.
-
-Perl equivalent: C<@{"$name"}>.
-
-NOTE: the perl_ form of this function is deprecated.
-
- AV* get_av(const char *name, I32 flags)
-
-=for hackers
-Found in file perl.c
-
-=item newAV
-X<newAV>
-
-Creates a new AV. The reference count is set to 1.
-
-Perl equivalent: C<my @array;>.
-
- AV* newAV()
-
-=for hackers
-Found in file av.h
-
-=item sortsv
-X<sortsv>
-
-Sort an array. Here is an example:
-
- sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
-
-Currently this always uses mergesort. See sortsv_flags for a more
-flexible routine.
-
- void sortsv(SV** array, size_t num_elts,
- SVCOMPARE_t cmp)
-
-=for hackers
-Found in file pp_sort.c
-
-=item sortsv_flags
-X<sortsv_flags>
-
-Sort an array, with various options.
-
- void sortsv_flags(SV** array, size_t num_elts,
- SVCOMPARE_t cmp, U32 flags)
-
-=for hackers
-Found in file pp_sort.c
-
-
-=back
-
-=head1 Callback Functions
-
-=over 8
-
-=item call_argv
-X<call_argv>
-
-Performs a callback to the specified named and package-scoped Perl subroutine
-with C<argv> (a NULL-terminated array of strings) as arguments. See L<perlcall>.
-
-Approximate Perl equivalent: C<&{"$sub_name"}(@$argv)>.
-
-NOTE: the perl_ form of this function is deprecated.
-
- I32 call_argv(const char* sub_name, I32 flags,
- char** argv)
-
-=for hackers
-Found in file perl.c
-
-=item call_method
-X<call_method>
-
-Performs a callback to the specified Perl method. The blessed object must
-be on the stack. See L<perlcall>.
-
-NOTE: the perl_ form of this function is deprecated.
-
- I32 call_method(const char* methname, I32 flags)
-
-=for hackers
-Found in file perl.c
-
-=item call_pv
-X<call_pv>
-
-Performs a callback to the specified Perl sub. See L<perlcall>.
-
-NOTE: the perl_ form of this function is deprecated.
-
- I32 call_pv(const char* sub_name, I32 flags)
-
-=for hackers
-Found in file perl.c
-
-=item call_sv
-X<call_sv>
-
-Performs a callback to the Perl sub whose name is in the SV. See
-L<perlcall>.
-
-NOTE: the perl_ form of this function is deprecated.
-
- I32 call_sv(SV* sv, VOL I32 flags)
-
-=for hackers
-Found in file perl.c
-
-=item ENTER
-X<ENTER>
-
-Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
-
- ENTER;
-
-=for hackers
-Found in file scope.h
-
-=item eval_pv
-X<eval_pv>
-
-Tells Perl to C<eval> the given string and return an SV* result.
-
-NOTE: the perl_ form of this function is deprecated.
-
- SV* eval_pv(const char* p, I32 croak_on_error)
-
-=for hackers
-Found in file perl.c
-
-=item eval_sv
-X<eval_sv>
-
-Tells Perl to C<eval> the string in the SV. It supports the same flags
-as C<call_sv>, with the obvious exception of G_EVAL. See L<perlcall>.
-
-NOTE: the perl_ form of this function is deprecated.
-
- I32 eval_sv(SV* sv, I32 flags)
-
-=for hackers
-Found in file perl.c
-
-=item FREETMPS
-X<FREETMPS>
-
-Closing bracket for temporaries on a callback. See C<SAVETMPS> and
-L<perlcall>.
-
- FREETMPS;
-
-=for hackers
-Found in file scope.h
-
-=item LEAVE
-X<LEAVE>
-
-Closing bracket on a callback. See C<ENTER> and L<perlcall>.
-
- LEAVE;
-
-=for hackers
-Found in file scope.h
-
-=item SAVETMPS
-X<SAVETMPS>
-
-Opening bracket for temporaries on a callback. See C<FREETMPS> and
-L<perlcall>.
-
- SAVETMPS;
-
-=for hackers
-Found in file scope.h
-
-
-=back
-
-=head1 Character case changing
-
-=over 8
-
-=item toLOWER
-X<toLOWER>
-
-Converts the specified character to lowercase in the platform's native
-character set, if possible; otherwise returns the input character itself.
-
- char toLOWER(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item toUPPER
-X<toUPPER>
-
-Converts the specified character to uppercase in the platform's native
-character set, if possible; otherwise returns the input character itself.
-
- char toUPPER(char ch)
-
-=for hackers
-Found in file handy.h
-
-
-=back
-
-=head1 Character classes
-
-There are three variants for all the functions in this section. The base ones
-operate using the character set of the platform Perl is running on. The ones
-with an C<_A> suffix operate on the ASCII character set, and the ones with an
-C<_L1> suffix operate on the full Latin1 character set. All are unaffected by
-locale and by C<use bytes>.
-
-For ASCII platforms, the base function with no suffix and the one with the
-C<_A> suffix are identical. The function with the C<_L1> suffix imposes the
-Latin-1 character set onto the platform. That is, the code points that are
-ASCII are unaffected, since ASCII is a subset of Latin-1. But the non-ASCII
-code points are treated as if they are Latin-1 characters. For example,
-C<isSPACE_L1()> will return true when called with the code point 0xA0, which is
-the Latin-1 NO-BREAK SPACE.
-
-For EBCDIC platforms, the base function with no suffix and the one with the
-C<_L1> suffix should be identical, since, as of this writing, the EBCDIC code
-pages that Perl knows about all are equivalent to Latin-1. The function that
-ends in an C<_A> suffix will not return true unless the specified character also
-has an ASCII equivalent.
-
-
-=over 8
-
-=item isALPHA
-X<isALPHA>
-
-Returns a boolean indicating whether the specified character is an
-alphabetic character in the platform's native character set.
-See the L<top of this section|/Character classes> for an explanation of variants
-C<isALPHA_A> and C<isALPHA_L1>.
-
- bool isALPHA(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item isASCII
-X<isASCII>
-
-Returns a boolean indicating whether the specified character is one of the 128
-characters in the ASCII character set. On non-ASCII platforms, it is if this
-character corresponds to an ASCII character. Variants C<isASCII_A()> and
-C<isASCII_L1()> are identical to C<isASCII()>.
-
- bool isASCII(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item isDIGIT
-X<isDIGIT>
-
-Returns a boolean indicating whether the specified character is a
-digit in the platform's native character set.
-Variants C<isDIGIT_A> and C<isDIGIT_L1> are identical to C<isDIGIT>.
-
- bool isDIGIT(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item isLOWER
-X<isLOWER>
-
-Returns a boolean indicating whether the specified character is a
-lowercase character in the platform's native character set.
-See the L<top of this section|/Character classes> for an explanation of variants
-C<isLOWER_A> and C<isLOWER_L1>.
-
- bool isLOWER(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item isOCTAL
-X<isOCTAL>
-
-Returns a boolean indicating whether the specified character is an
-octal digit, [0-7] in the platform's native character set.
-Variants C<isOCTAL_A> and C<isOCTAL_L1> are identical to C<isOCTAL>.
-
- bool isOCTAL(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item isSPACE
-X<isSPACE>
-
-Returns a boolean indicating whether the specified character is a
-whitespace character in the platform's native character set. This is the same
-as what C<\s> matches in a regular expression.
-See the L<top of this section|/Character classes> for an explanation of variants
-C<isSPACE_A> and C<isSPACE_L1>.
-
- bool isSPACE(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item isUPPER
-X<isUPPER>
-
-Returns a boolean indicating whether the specified character is an
-uppercase character in the platform's native character set.
-See the L<top of this section|/Character classes> for an explanation of variants
-C<isUPPER_A> and C<isUPPER_L1>.
-
- bool isUPPER(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item isWORDCHAR
-X<isWORDCHAR>
-
-Returns a boolean indicating whether the specified character is a
-character that is any of: alphabetic, numeric, or an underscore. This is the
-same as what C<\w> matches in a regular expression.
-C<isALNUM()> is a synonym provided for backward compatibility. Note that it
-does not have the standard C language meaning of alphanumeric, since it matches
-an underscore and the standard meaning does not.
-See the L<top of this section|/Character classes> for an explanation of variants
-C<isWORDCHAR_A> and C<isWORDCHAR_L1>.
-
- bool isWORDCHAR(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item isXDIGIT
-X<isXDIGIT>
-
-Returns a boolean indicating whether the specified character is a hexadecimal
-digit, [0-9A-Fa-f]. Variants C<isXDIGIT_A()> and C<isXDIGIT_L1()> are
-identical to C<isXDIGIT()>.
-
- bool isXDIGIT(char ch)
-
-=for hackers
-Found in file handy.h
-
-
-=back
-
-=head1 Cloning an interpreter
-
-=over 8
-
-=item perl_clone
-X<perl_clone>
-
-Create and return a new interpreter by cloning the current one.
-
-perl_clone takes these flags as parameters:
-
-CLONEf_COPY_STACKS - is used to, well, copy the stacks also,
-without it we only clone the data and zero the stacks,
-with it we copy the stacks and the new perl interpreter is
-ready to run at the exact same point as the previous one.
-The pseudo-fork code uses COPY_STACKS while the
-threads->create doesn't.
-
-CLONEf_KEEP_PTR_TABLE -
-perl_clone keeps a ptr_table with the pointer of the old
-variable as a key and the new variable as a value,
-this allows it to check if something has been cloned and not
-clone it again but rather just use the value and increase the
-refcount. If KEEP_PTR_TABLE is not set then perl_clone will kill
-the ptr_table using the function
-C<ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;>,
-reason to keep it around is if you want to dup some of your own
-variable who are outside the graph perl scans, example of this
-code is in threads.xs create.
-
-CLONEf_CLONE_HOST -
-This is a win32 thing, it is ignored on unix, it tells perls
-win32host code (which is c++) to clone itself, this is needed on
-win32 if you want to run two threads at the same time,
-if you just want to do some stuff in a separate perl interpreter
-and then throw it away and return to the original one,
-you don't need to do anything.
-
- PerlInterpreter* perl_clone(
- PerlInterpreter *proto_perl,
- UV flags
- )
-
-=for hackers
-Found in file sv.c
-
-
-=back
-
-=head1 Compile-time scope hooks
-
-=over 8
-
-=item BhkDISABLE
-X<BhkDISABLE>
-
-Temporarily disable an entry in this BHK structure, by clearing the
-appropriate flag. I<which> is a preprocessor token indicating which
-entry to disable.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void BhkDISABLE(BHK *hk, which)
-
-=for hackers
-Found in file op.h
-
-=item BhkENABLE
-X<BhkENABLE>
-
-Re-enable an entry in this BHK structure, by setting the appropriate
-flag. I<which> is a preprocessor token indicating which entry to enable.
-This will assert (under -DDEBUGGING) if the entry doesn't contain a valid
-pointer.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void BhkENABLE(BHK *hk, which)
-
-=for hackers
-Found in file op.h
-
-=item BhkENTRY_set
-X<BhkENTRY_set>
-
-Set an entry in the BHK structure, and set the flags to indicate it is
-valid. I<which> is a preprocessing token indicating which entry to set.
-The type of I<ptr> depends on the entry.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void BhkENTRY_set(BHK *hk, which, void *ptr)
-
-=for hackers
-Found in file op.h
-
-=item blockhook_register
-X<blockhook_register>
-
-Register a set of hooks to be called when the Perl lexical scope changes
-at compile time. See L<perlguts/"Compile-time scope hooks">.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
-NOTE: this function must be explicitly called as Perl_blockhook_register with an aTHX_ parameter.
-
- void Perl_blockhook_register(pTHX_ BHK *hk)
-
-=for hackers
-Found in file op.c
-
-
-=back
-
-=head1 COP Hint Hashes
-
-=over 8
-
-=item cophh_2hv
-X<cophh_2hv>
-
-Generates and returns a standard Perl hash representing the full set of
-key/value pairs in the cop hints hash I<cophh>. I<flags> is currently
-unused and must be zero.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- HV * cophh_2hv(const COPHH *cophh, U32 flags)
-
-=for hackers
-Found in file cop.h
-
-=item cophh_copy
-X<cophh_copy>
-
-Make and return a complete copy of the cop hints hash I<cophh>.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- COPHH * cophh_copy(COPHH *cophh)
-
-=for hackers
-Found in file cop.h
-
-=item cophh_delete_pv
-X<cophh_delete_pv>
-
-Like L</cophh_delete_pvn>, but takes a nul-terminated string instead of
-a string/length pair.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- COPHH * cophh_delete_pv(const COPHH *cophh,
- const char *key, U32 hash,
- U32 flags)
-
-=for hackers
-Found in file cop.h
-
-=item cophh_delete_pvn
-X<cophh_delete_pvn>
-
-Delete a key and its associated value from the cop hints hash I<cophh>,
-and returns the modified hash. The returned hash pointer is in general
-not the same as the hash pointer that was passed in. The input hash is
-consumed by the function, and the pointer to it must not be subsequently
-used. Use L</cophh_copy> if you need both hashes.
-
-The key is specified by I<keypv> and I<keylen>. If I<flags> has the
-C<COPHH_KEY_UTF8> bit set, the key octets are interpreted as UTF-8,
-otherwise they are interpreted as Latin-1. I<hash> is a precomputed
-hash of the key string, or zero if it has not been precomputed.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- COPHH * cophh_delete_pvn(COPHH *cophh,
- const char *keypv,
- STRLEN keylen, U32 hash,
- U32 flags)
-
-=for hackers
-Found in file cop.h
-
-=item cophh_delete_pvs
-X<cophh_delete_pvs>
-
-Like L</cophh_delete_pvn>, but takes a literal string instead of a
-string/length pair, and no precomputed hash.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- COPHH * cophh_delete_pvs(const COPHH *cophh,
- const char *key, U32 flags)
-
-=for hackers
-Found in file cop.h
-
-=item cophh_delete_sv
-X<cophh_delete_sv>
-
-Like L</cophh_delete_pvn>, but takes a Perl scalar instead of a
-string/length pair.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- COPHH * cophh_delete_sv(const COPHH *cophh, SV *key,
- U32 hash, U32 flags)
-
-=for hackers
-Found in file cop.h
-
-=item cophh_fetch_pv
-X<cophh_fetch_pv>
-
-Like L</cophh_fetch_pvn>, but takes a nul-terminated string instead of
-a string/length pair.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- SV * cophh_fetch_pv(const COPHH *cophh,
- const char *key, U32 hash,
- U32 flags)
-
-=for hackers
-Found in file cop.h
-
-=item cophh_fetch_pvn
-X<cophh_fetch_pvn>
-
-Look up the entry in the cop hints hash I<cophh> with the key specified by
-I<keypv> and I<keylen>. If I<flags> has the C<COPHH_KEY_UTF8> bit set,
-the key octets are interpreted as UTF-8, otherwise they are interpreted
-as Latin-1. I<hash> is a precomputed hash of the key string, or zero if
-it has not been precomputed. Returns a mortal scalar copy of the value
-associated with the key, or C<&PL_sv_placeholder> if there is no value
-associated with the key.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- SV * cophh_fetch_pvn(const COPHH *cophh,
- const char *keypv,
- STRLEN keylen, U32 hash,
- U32 flags)
-
-=for hackers
-Found in file cop.h
-
-=item cophh_fetch_pvs
-X<cophh_fetch_pvs>
-
-Like L</cophh_fetch_pvn>, but takes a literal string instead of a
-string/length pair, and no precomputed hash.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- SV * cophh_fetch_pvs(const COPHH *cophh,
- const char *key, U32 flags)
-
-=for hackers
-Found in file cop.h
-
-=item cophh_fetch_sv
-X<cophh_fetch_sv>
-
-Like L</cophh_fetch_pvn>, but takes a Perl scalar instead of a
-string/length pair.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- SV * cophh_fetch_sv(const COPHH *cophh, SV *key,
- U32 hash, U32 flags)
-
-=for hackers
-Found in file cop.h
-
-=item cophh_free
-X<cophh_free>
-
-Discard the cop hints hash I<cophh>, freeing all resources associated
-with it.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void cophh_free(COPHH *cophh)
-
-=for hackers
-Found in file cop.h
-
-=item cophh_new_empty
-X<cophh_new_empty>
-
-Generate and return a fresh cop hints hash containing no entries.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- COPHH * cophh_new_empty()
-
-=for hackers
-Found in file cop.h
-
-=item cophh_store_pv
-X<cophh_store_pv>
-
-Like L</cophh_store_pvn>, but takes a nul-terminated string instead of
-a string/length pair.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- COPHH * cophh_store_pv(const COPHH *cophh,
- const char *key, U32 hash,
- SV *value, U32 flags)
-
-=for hackers
-Found in file cop.h
-
-=item cophh_store_pvn
-X<cophh_store_pvn>
-
-Stores a value, associated with a key, in the cop hints hash I<cophh>,
-and returns the modified hash. The returned hash pointer is in general
-not the same as the hash pointer that was passed in. The input hash is
-consumed by the function, and the pointer to it must not be subsequently
-used. Use L</cophh_copy> if you need both hashes.
-
-The key is specified by I<keypv> and I<keylen>. If I<flags> has the
-C<COPHH_KEY_UTF8> bit set, the key octets are interpreted as UTF-8,
-otherwise they are interpreted as Latin-1. I<hash> is a precomputed
-hash of the key string, or zero if it has not been precomputed.
-
-I<value> is the scalar value to store for this key. I<value> is copied
-by this function, which thus does not take ownership of any reference
-to it, and later changes to the scalar will not be reflected in the
-value visible in the cop hints hash. Complex types of scalar will not
-be stored with referential integrity, but will be coerced to strings.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- COPHH * cophh_store_pvn(COPHH *cophh, const char *keypv,
- STRLEN keylen, U32 hash,
- SV *value, U32 flags)
-
-=for hackers
-Found in file cop.h
-
-=item cophh_store_pvs
-X<cophh_store_pvs>
-
-Like L</cophh_store_pvn>, but takes a literal string instead of a
-string/length pair, and no precomputed hash.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- COPHH * cophh_store_pvs(const COPHH *cophh,
- const char *key, SV *value,
- U32 flags)
-
-=for hackers
-Found in file cop.h
-
-=item cophh_store_sv
-X<cophh_store_sv>
-
-Like L</cophh_store_pvn>, but takes a Perl scalar instead of a
-string/length pair.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- COPHH * cophh_store_sv(const COPHH *cophh, SV *key,
- U32 hash, SV *value, U32 flags)
-
-=for hackers
-Found in file cop.h
-
-
-=back
-
-=head1 COP Hint Reading
-
-=over 8
-
-=item cop_hints_2hv
-X<cop_hints_2hv>
-
-Generates and returns a standard Perl hash representing the full set of
-hint entries in the cop I<cop>. I<flags> is currently unused and must
-be zero.
-
- HV * cop_hints_2hv(const COP *cop, U32 flags)
-
-=for hackers
-Found in file cop.h
-
-=item cop_hints_fetch_pv
-X<cop_hints_fetch_pv>
-
-Like L</cop_hints_fetch_pvn>, but takes a nul-terminated string instead
-of a string/length pair.
-
- SV * cop_hints_fetch_pv(const COP *cop,
- const char *key, U32 hash,
- U32 flags)
-
-=for hackers
-Found in file cop.h
-
-=item cop_hints_fetch_pvn
-X<cop_hints_fetch_pvn>
-
-Look up the hint entry in the cop I<cop> with the key specified by
-I<keypv> and I<keylen>. If I<flags> has the C<COPHH_KEY_UTF8> bit set,
-the key octets are interpreted as UTF-8, otherwise they are interpreted
-as Latin-1. I<hash> is a precomputed hash of the key string, or zero if
-it has not been precomputed. Returns a mortal scalar copy of the value
-associated with the key, or C<&PL_sv_placeholder> if there is no value
-associated with the key.
-
- SV * cop_hints_fetch_pvn(const COP *cop,
- const char *keypv,
- STRLEN keylen, U32 hash,
- U32 flags)
-
-=for hackers
-Found in file cop.h
-
-=item cop_hints_fetch_pvs
-X<cop_hints_fetch_pvs>
-
-Like L</cop_hints_fetch_pvn>, but takes a literal string instead of a
-string/length pair, and no precomputed hash.
-
- SV * cop_hints_fetch_pvs(const COP *cop,
- const char *key, U32 flags)
-
-=for hackers
-Found in file cop.h
-
-=item cop_hints_fetch_sv
-X<cop_hints_fetch_sv>
-
-Like L</cop_hints_fetch_pvn>, but takes a Perl scalar instead of a
-string/length pair.
-
- SV * cop_hints_fetch_sv(const COP *cop, SV *key,
- U32 hash, U32 flags)
-
-=for hackers
-Found in file cop.h
-
-
-=back
-
-=head1 Custom Operators
-
-=over 8
-
-=item custom_op_register
-X<custom_op_register>
-
-Register a custom op. See L<perlguts/"Custom Operators">.
-
-NOTE: this function must be explicitly called as Perl_custom_op_register with an aTHX_ parameter.
-
- void Perl_custom_op_register(pTHX_
- Perl_ppaddr_t ppaddr,
- const XOP *xop)
-
-=for hackers
-Found in file op.c
-
-=item custom_op_xop
-X<custom_op_xop>
-
-Return the XOP structure for a given custom op. This function should be
-considered internal to OP_NAME and the other access macros: use them instead.
-
-NOTE: this function must be explicitly called as Perl_custom_op_xop with an aTHX_ parameter.
-
- const XOP * Perl_custom_op_xop(pTHX_ const OP *o)
-
-=for hackers
-Found in file op.c
-
-=item XopDISABLE
-X<XopDISABLE>
-
-Temporarily disable a member of the XOP, by clearing the appropriate flag.
-
- void XopDISABLE(XOP *xop, which)
-
-=for hackers
-Found in file op.h
-
-=item XopENABLE
-X<XopENABLE>
-
-Reenable a member of the XOP which has been disabled.
-
- void XopENABLE(XOP *xop, which)
-
-=for hackers
-Found in file op.h
-
-=item XopENTRY
-X<XopENTRY>
-
-Return a member of the XOP structure. I<which> is a cpp token indicating
-which entry to return. If the member is not set this will return a
-default value. The return type depends on I<which>.
-
- XopENTRY(XOP *xop, which)
-
-=for hackers
-Found in file op.h
-
-=item XopENTRY_set
-X<XopENTRY_set>
-
-Set a member of the XOP structure. I<which> is a cpp token indicating
-which entry to set. See L<perlguts/"Custom Operators"> for details about
-the available members and how they are used.
-
- void XopENTRY_set(XOP *xop, which, value)
-
-=for hackers
-Found in file op.h
-
-=item XopFLAGS
-X<XopFLAGS>
-
-Return the XOP's flags.
-
- U32 XopFLAGS(XOP *xop)
-
-=for hackers
-Found in file op.h
-
-
-=back
-
-=head1 CV Manipulation Functions
-
-=over 8
-
-=item CvSTASH
-X<CvSTASH>
-
-Returns the stash of the CV. A stash is the symbol table hash, containing
-the package-scoped variables in the package where the subroutine was defined.
-For more information, see L<perlguts>.
-
-This also has a special use with XS AUTOLOAD subs.
-See L<perlguts/Autoloading with XSUBs>.
-
- HV* CvSTASH(CV* cv)
-
-=for hackers
-Found in file cv.h
-
-=item get_cv
-X<get_cv>
-
-Uses C<strlen> to get the length of C<name>, then calls C<get_cvn_flags>.
-
-NOTE: the perl_ form of this function is deprecated.
-
- CV* get_cv(const char* name, I32 flags)
-
-=for hackers
-Found in file perl.c
-
-=item get_cvn_flags
-X<get_cvn_flags>
-
-Returns the CV of the specified Perl subroutine. C<flags> are passed to
-C<gv_fetchpvn_flags>. If C<GV_ADD> is set and the Perl subroutine does not
-exist then it will be declared (which has the same effect as saying
-C<sub name;>). If C<GV_ADD> is not set and the subroutine does not exist
-then NULL is returned.
-
-NOTE: the perl_ form of this function is deprecated.
-
- CV* get_cvn_flags(const char* name, STRLEN len,
- I32 flags)
-
-=for hackers
-Found in file perl.c
-
-
-=back
-
-=head1 Embedding Functions
-
-=over 8
-
-=item cv_clone
-X<cv_clone>
-
-Clone a CV, making a lexical closure. I<proto> supplies the prototype
-of the function: its code, pad structure, and other attributes.
-The prototype is combined with a capture of outer lexicals to which the
-code refers, which are taken from the currently-executing instance of
-the immediately surrounding code.
-
- CV * cv_clone(CV *proto)
-
-=for hackers
-Found in file pad.c
-
-=item cv_undef
-X<cv_undef>
-
-Clear out all the active components of a CV. This can happen either
-by an explicit C<undef &foo>, or by the reference count going to zero.
-In the former case, we keep the CvOUTSIDE pointer, so that any anonymous
-children can still follow the full lexical scope chain.
-
- void cv_undef(CV* cv)
-
-=for hackers
-Found in file pad.c
-
-=item find_rundefsv
-X<find_rundefsv>
-
-Find and return the variable that is named C<$_> in the lexical scope
-of the currently-executing function. This may be a lexical C<$_>,
-or will otherwise be the global one.
-
- SV * find_rundefsv()
-
-=for hackers
-Found in file pad.c
-
-=item find_rundefsvoffset
-X<find_rundefsvoffset>
-
-Find the position of the lexical C<$_> in the pad of the
-currently-executing function. Returns the offset in the current pad,
-or C<NOT_IN_PAD> if there is no lexical C<$_> in scope (in which case
-the global one should be used instead).
-L</find_rundefsv> is likely to be more convenient.
-
-NOTE: the perl_ form of this function is deprecated.
-
- PADOFFSET find_rundefsvoffset()
-
-=for hackers
-Found in file pad.c
-
-=item load_module
-X<load_module>
-
-Loads the module whose name is pointed to by the string part of name.
-Note that the actual module name, not its filename, should be given.
-Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of
-PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS
-(or 0 for no flags). ver, if specified and not NULL, provides version semantics
-similar to C<use Foo::Bar VERSION>. The optional trailing SV*
-arguments can be used to specify arguments to the module's import()
-method, similar to C<use Foo::Bar VERSION LIST>. They must be
-terminated with a final NULL pointer. Note that this list can only
-be omitted when the PERL_LOADMOD_NOIMPORT flag has been used.
-Otherwise at least a single NULL pointer to designate the default
-import list is required.
-
-The reference count for each specified C<SV*> parameter is decremented.
-
- void load_module(U32 flags, SV* name, SV* ver, ...)
-
-=for hackers
-Found in file op.c
-
-=item nothreadhook
-X<nothreadhook>
-
-Stub that provides thread hook for perl_destruct when there are
-no threads.
-
- int nothreadhook()
-
-=for hackers
-Found in file perl.c
-
-=item pad_add_anon
-X<pad_add_anon>
-
-Allocates a place in the currently-compiling pad (via L</pad_alloc>)
-for an anonymous function that is lexically scoped inside the
-currently-compiling function.
-The function I<func> is linked into the pad, and its C<CvOUTSIDE> link
-to the outer scope is weakened to avoid a reference loop.
-
-I<optype> should be an opcode indicating the type of operation that the
-pad entry is to support. This doesn't affect operational semantics,
-but is used for debugging.
-
- PADOFFSET pad_add_anon(CV *func, I32 optype)
-
-=for hackers
-Found in file pad.c
-
-=item pad_add_name_pv
-X<pad_add_name_pv>
-
-Exactly like L</pad_add_name_pvn>, but takes a nul-terminated string
-instead of a string/length pair.
-
- PADOFFSET pad_add_name_pv(const char *name, U32 flags,
- HV *typestash, HV *ourstash)
-
-=for hackers
-Found in file pad.c
-
-=item pad_add_name_pvn
-X<pad_add_name_pvn>
-
-Allocates a place in the currently-compiling pad for a named lexical
-variable. Stores the name and other metadata in the name part of the
-pad, and makes preparations to manage the variable's lexical scoping.
-Returns the offset of the allocated pad slot.
-
-I<namepv>/I<namelen> specify the variable's name, including leading sigil.
-If I<typestash> is non-null, the name is for a typed lexical, and this
-identifies the type. If I<ourstash> is non-null, it's a lexical reference
-to a package variable, and this identifies the package. The following
-flags can be OR'ed together:
-
- padadd_OUR redundantly specifies if it's a package var
- padadd_STATE variable will retain value persistently
- padadd_NO_DUP_CHECK skip check for lexical shadowing
-
- PADOFFSET pad_add_name_pvn(const char *namepv,
- STRLEN namelen, U32 flags,
- HV *typestash, HV *ourstash)
-
-=for hackers
-Found in file pad.c
-
-=item pad_add_name_sv
-X<pad_add_name_sv>
-
-Exactly like L</pad_add_name_pvn>, but takes the name string in the form
-of an SV instead of a string/length pair.
-
- PADOFFSET pad_add_name_sv(SV *name, U32 flags,
- HV *typestash, HV *ourstash)
-
-=for hackers
-Found in file pad.c
-
-=item pad_alloc
-X<pad_alloc>
-
-Allocates a place in the currently-compiling pad,
-returning the offset of the allocated pad slot.
-No name is initially attached to the pad slot.
-I<tmptype> is a set of flags indicating the kind of pad entry required,
-which will be set in the value SV for the allocated pad entry:
-
- SVs_PADMY named lexical variable ("my", "our", "state")
- SVs_PADTMP unnamed temporary store
-
-I<optype> should be an opcode indicating the type of operation that the
-pad entry is to support. This doesn't affect operational semantics,
-but is used for debugging.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- PADOFFSET pad_alloc(I32 optype, U32 tmptype)
-
-=for hackers
-Found in file pad.c
-
-=item pad_compname_type
-X<pad_compname_type>
-
-Looks up the type of the lexical variable at position I<po> in the
-currently-compiling pad. If the variable is typed, the stash of the
-class to which it is typed is returned. If not, C<NULL> is returned.
-
- HV * pad_compname_type(PADOFFSET po)
-
-=for hackers
-Found in file pad.c
-
-=item pad_findmy_pv
-X<pad_findmy_pv>
-
-Exactly like L</pad_findmy_pvn>, but takes a nul-terminated string
-instead of a string/length pair.
-
- PADOFFSET pad_findmy_pv(const char *name, U32 flags)
-
-=for hackers
-Found in file pad.c
-
-=item pad_findmy_pvn
-X<pad_findmy_pvn>
-
-Given the name of a lexical variable, find its position in the
-currently-compiling pad.
-I<namepv>/I<namelen> specify the variable's name, including leading sigil.
-I<flags> is reserved and must be zero.
-If it is not in the current pad but appears in the pad of any lexically
-enclosing scope, then a pseudo-entry for it is added in the current pad.
-Returns the offset in the current pad,
-or C<NOT_IN_PAD> if no such lexical is in scope.
-
- PADOFFSET pad_findmy_pvn(const char *namepv,
- STRLEN namelen, U32 flags)
-
-=for hackers
-Found in file pad.c
-
-=item pad_findmy_sv
-X<pad_findmy_sv>
-
-Exactly like L</pad_findmy_pvn>, but takes the name string in the form
-of an SV instead of a string/length pair.
-
- PADOFFSET pad_findmy_sv(SV *name, U32 flags)
-
-=for hackers
-Found in file pad.c
-
-=item pad_setsv
-X<pad_setsv>
-
-Set the value at offset I<po> in the current (compiling or executing) pad.
-Use the macro PAD_SETSV() rather than calling this function directly.
-
- void pad_setsv(PADOFFSET po, SV *sv)
-
-=for hackers
-Found in file pad.c
-
-=item pad_sv
-X<pad_sv>
-
-Get the value at offset I<po> in the current (compiling or executing) pad.
-Use macro PAD_SV instead of calling this function directly.
-
- SV * pad_sv(PADOFFSET po)
-
-=for hackers
-Found in file pad.c
-
-=item pad_tidy
-X<pad_tidy>
-
-Tidy up a pad at the end of compilation of the code to which it belongs.
-Jobs performed here are: remove most stuff from the pads of anonsub
-prototypes; give it a @_; mark temporaries as such. I<type> indicates
-the kind of subroutine:
-
- padtidy_SUB ordinary subroutine
- padtidy_SUBCLONE prototype for lexical closure
- padtidy_FORMAT format
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void pad_tidy(padtidy_type type)
-
-=for hackers
-Found in file pad.c
-
-=item perl_alloc
-X<perl_alloc>
-
-Allocates a new Perl interpreter. See L<perlembed>.
-
- PerlInterpreter* perl_alloc()
-
-=for hackers
-Found in file perl.c
-
-=item perl_construct
-X<perl_construct>
-
-Initializes a new Perl interpreter. See L<perlembed>.
-
- void perl_construct(PerlInterpreter *my_perl)
-
-=for hackers
-Found in file perl.c
-
-=item perl_destruct
-X<perl_destruct>
-
-Shuts down a Perl interpreter. See L<perlembed>.
-
- int perl_destruct(PerlInterpreter *my_perl)
-
-=for hackers
-Found in file perl.c
-
-=item perl_free
-X<perl_free>
-
-Releases a Perl interpreter. See L<perlembed>.
-
- void perl_free(PerlInterpreter *my_perl)
-
-=for hackers
-Found in file perl.c
-
-=item perl_parse
-X<perl_parse>
-
-Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
-
- int perl_parse(PerlInterpreter *my_perl,
- XSINIT_t xsinit, int argc,
- char** argv, char** env)
-
-=for hackers
-Found in file perl.c
-
-=item perl_run
-X<perl_run>
-
-Tells a Perl interpreter to run. See L<perlembed>.
-
- int perl_run(PerlInterpreter *my_perl)
-
-=for hackers
-Found in file perl.c
-
-=item require_pv
-X<require_pv>
-
-Tells Perl to C<require> the file named by the string argument. It is
-analogous to the Perl code C<eval "require '$file'">. It's even
-implemented that way; consider using load_module instead.
-
-NOTE: the perl_ form of this function is deprecated.
-
- void require_pv(const char* pv)
-
-=for hackers
-Found in file perl.c
-
-
-=back
-
-=head1 Functions in file dump.c
-
-
-=over 8
-
-=item pv_display
-X<pv_display>
-
-Similar to
-
- pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
-
-except that an additional "\0" will be appended to the string when
-len > cur and pv[cur] is "\0".
-
-Note that the final string may be up to 7 chars longer than pvlim.
-
- char* pv_display(SV *dsv, const char *pv, STRLEN cur,
- STRLEN len, STRLEN pvlim)
-
-=for hackers
-Found in file dump.c
-
-=item pv_escape
-X<pv_escape>
-
-Escapes at most the first "count" chars of pv and puts the results into
-dsv such that the size of the escaped string will not exceed "max" chars
-and will not contain any incomplete escape sequences.
-
-If flags contains PERL_PV_ESCAPE_QUOTE then any double quotes in the string
-will also be escaped.
-
-Normally the SV will be cleared before the escaped string is prepared,
-but when PERL_PV_ESCAPE_NOCLEAR is set this will not occur.
-
-If PERL_PV_ESCAPE_UNI is set then the input string is treated as Unicode,
-if PERL_PV_ESCAPE_UNI_DETECT is set then the input string is scanned
-using C<is_utf8_string()> to determine if it is Unicode.
-
-If PERL_PV_ESCAPE_ALL is set then all input chars will be output
-using C<\x01F1> style escapes, otherwise if PERL_PV_ESCAPE_NONASCII is set, only
-chars above 127 will be escaped using this style; otherwise, only chars above
-255 will be so escaped; other non printable chars will use octal or
-common escaped patterns like C<\n>. Otherwise, if PERL_PV_ESCAPE_NOBACKSLASH
-then all chars below 255 will be treated as printable and
-will be output as literals.
-
-If PERL_PV_ESCAPE_FIRSTCHAR is set then only the first char of the
-string will be escaped, regardless of max. If the output is to be in hex,
-then it will be returned as a plain hex
-sequence. Thus the output will either be a single char,
-an octal escape sequence, a special escape like C<\n> or a hex value.
-
-If PERL_PV_ESCAPE_RE is set then the escape char used will be a '%' and
-not a '\\'. This is because regexes very often contain backslashed
-sequences, whereas '%' is not a particularly common character in patterns.
-
-Returns a pointer to the escaped text as held by dsv.
-
- char* pv_escape(SV *dsv, char const * const str,
- const STRLEN count, const STRLEN max,
- STRLEN * const escaped,
- const U32 flags)
-
-=for hackers
-Found in file dump.c
-
-=item pv_pretty
-X<pv_pretty>
-
-Converts a string into something presentable, handling escaping via
-pv_escape() and supporting quoting and ellipses.
-
-If the PERL_PV_PRETTY_QUOTE flag is set then the result will be
-double quoted with any double quotes in the string escaped. Otherwise
-if the PERL_PV_PRETTY_LTGT flag is set then the result be wrapped in
-angle brackets.
-
-If the PERL_PV_PRETTY_ELLIPSES flag is set and not all characters in
-string were output then an ellipsis C<...> will be appended to the
-string. Note that this happens AFTER it has been quoted.
-
-If start_color is non-null then it will be inserted after the opening
-quote (if there is one) but before the escaped text. If end_color
-is non-null then it will be inserted after the escaped text but before
-any quotes or ellipses.
-
-Returns a pointer to the prettified text as held by dsv.
-
- char* pv_pretty(SV *dsv, char const * const str,
- const STRLEN count, const STRLEN max,
- char const * const start_color,
- char const * const end_color,
- const U32 flags)
-
-=for hackers
-Found in file dump.c
-
-
-=back
-
-=head1 Functions in file mathoms.c
-
-
-=over 8
-
-=item custom_op_desc
-X<custom_op_desc>
-
-Return the description of a given custom op. This was once used by the
-OP_DESC macro, but is no longer: it has only been kept for
-compatibility, and should not be used.
-
- const char * custom_op_desc(const OP *o)
-
-=for hackers
-Found in file mathoms.c
-
-=item custom_op_name
-X<custom_op_name>
-
-Return the name for a given custom op. This was once used by the OP_NAME
-macro, but is no longer: it has only been kept for compatibility, and
-should not be used.
-
- const char * custom_op_name(const OP *o)
-
-=for hackers
-Found in file mathoms.c
-
-=item gv_fetchmethod
-X<gv_fetchmethod>
-
-See L</gv_fetchmethod_autoload>.
-
- GV* gv_fetchmethod(HV* stash, const char* name)
-
-=for hackers
-Found in file mathoms.c
-
-=item pack_cat
-X<pack_cat>
-
-The engine implementing pack() Perl function. Note: parameters next_in_list and
-flags are not used. This call should not be used; use packlist instead.
-
- void pack_cat(SV *cat, const char *pat,
- const char *patend, SV **beglist,
- SV **endlist, SV ***next_in_list,
- U32 flags)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_2pvbyte_nolen
-X<sv_2pvbyte_nolen>
-
-Return a pointer to the byte-encoded representation of the SV.
-May cause the SV to be downgraded from UTF-8 as a side-effect.
-
-Usually accessed via the C<SvPVbyte_nolen> macro.
-
- char* sv_2pvbyte_nolen(SV* sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_2pvutf8_nolen
-X<sv_2pvutf8_nolen>
-
-Return a pointer to the UTF-8-encoded representation of the SV.
-May cause the SV to be upgraded to UTF-8 as a side-effect.
-
-Usually accessed via the C<SvPVutf8_nolen> macro.
-
- char* sv_2pvutf8_nolen(SV* sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_2pv_nolen
-X<sv_2pv_nolen>
-
-Like C<sv_2pv()>, but doesn't return the length too. You should usually
-use the macro wrapper C<SvPV_nolen(sv)> instead.
-
- char* sv_2pv_nolen(SV* sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_catpvn_mg
-X<sv_catpvn_mg>
-
-Like C<sv_catpvn>, but also handles 'set' magic.
-
- void sv_catpvn_mg(SV *sv, const char *ptr,
- STRLEN len)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_catsv_mg
-X<sv_catsv_mg>
-
-Like C<sv_catsv>, but also handles 'set' magic.
-
- void sv_catsv_mg(SV *dsv, SV *ssv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_force_normal
-X<sv_force_normal>
-
-Undo various types of fakery on an SV: if the PV is a shared string, make
-a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
-an xpvmg. See also C<sv_force_normal_flags>.
-
- void sv_force_normal(SV *sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_iv
-X<sv_iv>
-
-A private implementation of the C<SvIVx> macro for compilers which can't
-cope with complex macro expressions. Always use the macro instead.
-
- IV sv_iv(SV* sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_nolocking
-X<sv_nolocking>
-
-Dummy routine which "locks" an SV when there is no locking module present.
-Exists to avoid test for a NULL function pointer and because it could
-potentially warn under some level of strict-ness.
-
-"Superseded" by sv_nosharing().
-
- void sv_nolocking(SV *sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_nounlocking
-X<sv_nounlocking>
-
-Dummy routine which "unlocks" an SV when there is no locking module present.
-Exists to avoid test for a NULL function pointer and because it could
-potentially warn under some level of strict-ness.
-
-"Superseded" by sv_nosharing().
-
- void sv_nounlocking(SV *sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_nv
-X<sv_nv>
-
-A private implementation of the C<SvNVx> macro for compilers which can't
-cope with complex macro expressions. Always use the macro instead.
-
- NV sv_nv(SV* sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_pv
-X<sv_pv>
-
-Use the C<SvPV_nolen> macro instead
-
- char* sv_pv(SV *sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_pvbyte
-X<sv_pvbyte>
-
-Use C<SvPVbyte_nolen> instead.
-
- char* sv_pvbyte(SV *sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_pvbyten
-X<sv_pvbyten>
-
-A private implementation of the C<SvPVbyte> macro for compilers
-which can't cope with complex macro expressions. Always use the macro
-instead.
-
- char* sv_pvbyten(SV *sv, STRLEN *lp)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_pvn
-X<sv_pvn>
-
-A private implementation of the C<SvPV> macro for compilers which can't
-cope with complex macro expressions. Always use the macro instead.
-
- char* sv_pvn(SV *sv, STRLEN *lp)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_pvutf8
-X<sv_pvutf8>
-
-Use the C<SvPVutf8_nolen> macro instead
-
- char* sv_pvutf8(SV *sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_pvutf8n
-X<sv_pvutf8n>
-
-A private implementation of the C<SvPVutf8> macro for compilers
-which can't cope with complex macro expressions. Always use the macro
-instead.
-
- char* sv_pvutf8n(SV *sv, STRLEN *lp)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_taint
-X<sv_taint>
-
-Taint an SV. Use C<SvTAINTED_on> instead.
-
- void sv_taint(SV* sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_unref
-X<sv_unref>
-
-Unsets the RV status of the SV, and decrements the reference count of
-whatever was being referenced by the RV. This can almost be thought of
-as a reversal of C<newSVrv>. This is C<sv_unref_flags> with the C<flag>
-being zero. See C<SvROK_off>.
-
- void sv_unref(SV* sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_usepvn
-X<sv_usepvn>
-
-Tells an SV to use C<ptr> to find its string value. Implemented by
-calling C<sv_usepvn_flags> with C<flags> of 0, hence does not handle 'set'
-magic. See C<sv_usepvn_flags>.
-
- void sv_usepvn(SV* sv, char* ptr, STRLEN len)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_usepvn_mg
-X<sv_usepvn_mg>
-
-Like C<sv_usepvn>, but also handles 'set' magic.
-
- void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_uv
-X<sv_uv>
-
-A private implementation of the C<SvUVx> macro for compilers which can't
-cope with complex macro expressions. Always use the macro instead.
-
- UV sv_uv(SV* sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item unpack_str
-X<unpack_str>
-
-The engine implementing unpack() Perl function. Note: parameters strbeg, new_s
-and ocnt are not used. This call should not be used, use unpackstring instead.
-
- I32 unpack_str(const char *pat, const char *patend,
- const char *s, const char *strbeg,
- const char *strend, char **new_s,
- I32 ocnt, U32 flags)
-
-=for hackers
-Found in file mathoms.c
-
-
-=back
-
-=head1 Functions in file op.c
-
-
-=over 8
-
-=item op_contextualize
-X<op_contextualize>
-
-Applies a syntactic context to an op tree representing an expression.
-I<o> is the op tree, and I<context> must be C<G_SCALAR>, C<G_ARRAY>,
-or C<G_VOID> to specify the context to apply. The modified op tree
-is returned.
-
- OP * op_contextualize(OP *o, I32 context)
-
-=for hackers
-Found in file op.c
-
-
-=back
-
-=head1 Functions in file perl.h
-
-
-=over 8
-
-=item PERL_SYS_INIT
-X<PERL_SYS_INIT>
-
-Provides system-specific tune up of the C runtime environment necessary to
-run Perl interpreters. This should be called only once, before creating
-any Perl interpreters.
-
- void PERL_SYS_INIT(int argc, char** argv)
-
-=for hackers
-Found in file perl.h
-
-=item PERL_SYS_INIT3
-X<PERL_SYS_INIT3>
-
-Provides system-specific tune up of the C runtime environment necessary to
-run Perl interpreters. This should be called only once, before creating
-any Perl interpreters.
-
- void PERL_SYS_INIT3(int argc, char** argv,
- char** env)
-
-=for hackers
-Found in file perl.h
-
-=item PERL_SYS_TERM
-X<PERL_SYS_TERM>
-
-Provides system-specific clean up of the C runtime environment after
-running Perl interpreters. This should be called only once, after
-freeing any remaining Perl interpreters.
-
- void PERL_SYS_TERM()
-
-=for hackers
-Found in file perl.h
-
-
-=back
-
-=head1 Functions in file pp_ctl.c
-
-
-=over 8
-
-=item caller_cx
-X<caller_cx>
-
-The XSUB-writer's equivalent of L<caller()|perlfunc/caller>. The
-returned C<PERL_CONTEXT> structure can be interrogated to find all the
-information returned to Perl by C<caller>. Note that XSUBs don't get a
-stack frame, so C<caller_cx(0, NULL)> will return information for the
-immediately-surrounding Perl code.
-
-This function skips over the automatic calls to C<&DB::sub> made on the
-behalf of the debugger. If the stack frame requested was a sub called by
-C<DB::sub>, the return value will be the frame for the call to
-C<DB::sub>, since that has the correct line number/etc. for the call
-site. If I<dbcxp> is non-C<NULL>, it will be set to a pointer to the
-frame for the sub call itself.
-
- const PERL_CONTEXT * caller_cx(
- I32 level,
- const PERL_CONTEXT **dbcxp
- )
-
-=for hackers
-Found in file pp_ctl.c
-
-=item find_runcv
-X<find_runcv>
-
-Locate the CV corresponding to the currently executing sub or eval.
-If db_seqp is non_null, skip CVs that are in the DB package and populate
-*db_seqp with the cop sequence number at the point that the DB:: code was
-entered. (allows debuggers to eval in the scope of the breakpoint rather
-than in the scope of the debugger itself).
-
- CV* find_runcv(U32 *db_seqp)
-
-=for hackers
-Found in file pp_ctl.c
-
-
-=back
-
-=head1 Functions in file pp_pack.c
-
-
-=over 8
-
-=item packlist
-X<packlist>
-
-The engine implementing pack() Perl function.
-
- void packlist(SV *cat, const char *pat,
- const char *patend, SV **beglist,
- SV **endlist)
-
-=for hackers
-Found in file pp_pack.c
-
-=item unpackstring
-X<unpackstring>
-
-The engine implementing unpack() Perl function. C<unpackstring> puts the
-extracted list items on the stack and returns the number of elements.
-Issue C<PUTBACK> before and C<SPAGAIN> after the call to this function.
-
- I32 unpackstring(const char *pat,
- const char *patend, const char *s,
- const char *strend, U32 flags)
-
-=for hackers
-Found in file pp_pack.c
-
-
-=back
-
-=head1 Functions in file pp_sys.c
-
-
-=over 8
-
-=item setdefout
-X<setdefout>
-
-Sets PL_defoutgv, the default file handle for output, to the passed in
-typeglob. As PL_defoutgv "owns" a reference on its typeglob, the reference
-count of the passed in typeglob is increased by one, and the reference count
-of the typeglob that PL_defoutgv points to is decreased by one.
-
- void setdefout(GV* gv)
-
-=for hackers
-Found in file pp_sys.c
-
-
-=back
-
-=head1 Functions in file utf8.h
-
-
-=over 8
-
-=item ibcmp_utf8
-X<ibcmp_utf8>
-
-This is a synonym for (! foldEQ_utf8())
-
- I32 ibcmp_utf8(const char *s1, char **pe1, UV l1,
- bool u1, const char *s2, char **pe2,
- UV l2, bool u2)
-
-=for hackers
-Found in file utf8.h
-
-
-=back
-
-=head1 Functions in file util.h
-
-
-=over 8
-
-=item ibcmp
-X<ibcmp>
-
-This is a synonym for (! foldEQ())
-
- I32 ibcmp(const char* a, const char* b, I32 len)
-
-=for hackers
-Found in file util.h
-
-=item ibcmp_locale
-X<ibcmp_locale>
-
-This is a synonym for (! foldEQ_locale())
-
- I32 ibcmp_locale(const char* a, const char* b,
- I32 len)
-
-=for hackers
-Found in file util.h
-
-
-=back
-
-=head1 Global Variables
-
-=over 8
-
-=item PL_check
-X<PL_check>
-
-Array, indexed by opcode, of functions that will be called for the "check"
-phase of optree building during compilation of Perl code. For most (but
-not all) types of op, once the op has been initially built and populated
-with child ops it will be filtered through the check function referenced
-by the appropriate element of this array. The new op is passed in as the
-sole argument to the check function, and the check function returns the
-completed op. The check function may (as the name suggests) check the op
-for validity and signal errors. It may also initialise or modify parts of
-the ops, or perform more radical surgery such as adding or removing child
-ops, or even throw the op away and return a different op in its place.
-
-This array of function pointers is a convenient place to hook into the
-compilation process. An XS module can put its own custom check function
-in place of any of the standard ones, to influence the compilation of a
-particular type of op. However, a custom check function must never fully
-replace a standard check function (or even a custom check function from
-another module). A module modifying checking must instead B<wrap> the
-preexisting check function. A custom check function must be selective
-about when to apply its custom behaviour. In the usual case where
-it decides not to do anything special with an op, it must chain the
-preexisting op function. Check functions are thus linked in a chain,
-with the core's base checker at the end.
-
-For thread safety, modules should not write directly to this array.
-Instead, use the function L</wrap_op_checker>.
-
-=for hackers
-Found in file perlvars.h
-
-=item PL_keyword_plugin
-X<PL_keyword_plugin>
-
-Function pointer, pointing at a function used to handle extended keywords.
-The function should be declared as
-
- int keyword_plugin_function(pTHX_
- char *keyword_ptr, STRLEN keyword_len,
- OP **op_ptr)
-
-The function is called from the tokeniser, whenever a possible keyword
-is seen. C<keyword_ptr> points at the word in the parser's input
-buffer, and C<keyword_len> gives its length; it is not null-terminated.
-The function is expected to examine the word, and possibly other state
-such as L<%^H|perlvar/%^H>, to decide whether it wants to handle it
-as an extended keyword. If it does not, the function should return
-C<KEYWORD_PLUGIN_DECLINE>, and the normal parser process will continue.
-
-If the function wants to handle the keyword, it first must
-parse anything following the keyword that is part of the syntax
-introduced by the keyword. See L</Lexer interface> for details.
-
-When a keyword is being handled, the plugin function must build
-a tree of C<OP> structures, representing the code that was parsed.
-The root of the tree must be stored in C<*op_ptr>. The function then
-returns a constant indicating the syntactic role of the construct that
-it has parsed: C<KEYWORD_PLUGIN_STMT> if it is a complete statement, or
-C<KEYWORD_PLUGIN_EXPR> if it is an expression. Note that a statement
-construct cannot be used inside an expression (except via C<do BLOCK>
-and similar), and an expression is not a complete statement (it requires
-at least a terminating semicolon).
-
-When a keyword is handled, the plugin function may also have
-(compile-time) side effects. It may modify C<%^H>, define functions, and
-so on. Typically, if side effects are the main purpose of a handler,
-it does not wish to generate any ops to be included in the normal
-compilation. In this case it is still required to supply an op tree,
-but it suffices to generate a single null op.
-
-That's how the C<*PL_keyword_plugin> function needs to behave overall.
-Conventionally, however, one does not completely replace the existing
-handler function. Instead, take a copy of C<PL_keyword_plugin> before
-assigning your own function pointer to it. Your handler function should
-look for keywords that it is interested in and handle those. Where it
-is not interested, it should call the saved plugin function, passing on
-the arguments it received. Thus C<PL_keyword_plugin> actually points
-at a chain of handler functions, all of which have an opportunity to
-handle keywords, and only the last function in the chain (built into
-the Perl core) will normally return C<KEYWORD_PLUGIN_DECLINE>.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
-=for hackers
-Found in file perlvars.h
-
-
-=back
-
-=head1 GV Functions
-
-=over 8
-
-=item GvSV
-X<GvSV>
-
-Return the SV from the GV.
-
- SV* GvSV(GV* gv)
-
-=for hackers
-Found in file gv.h
-
-=item gv_const_sv
-X<gv_const_sv>
-
-If C<gv> is a typeglob whose subroutine entry is a constant sub eligible for
-inlining, or C<gv> is a placeholder reference that would be promoted to such
-a typeglob, then returns the value returned by the sub. Otherwise, returns
-NULL.
-
- SV* gv_const_sv(GV* gv)
-
-=for hackers
-Found in file gv.c
-
-=item gv_fetchmeth
-X<gv_fetchmeth>
-
-Like L</gv_fetchmeth_pvn>, but lacks a flags parameter.
-
- GV* gv_fetchmeth(HV* stash, const char* name,
- STRLEN len, I32 level)
-
-=for hackers
-Found in file gv.c
-
-=item gv_fetchmethod_autoload
-X<gv_fetchmethod_autoload>
-
-Returns the glob which contains the subroutine to call to invoke the method
-on the C<stash>. In fact in the presence of autoloading this may be the
-glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is
-already setup.
-
-The third parameter of C<gv_fetchmethod_autoload> determines whether
-AUTOLOAD lookup is performed if the given method is not present: non-zero
-means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
-Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
-with a non-zero C<autoload> parameter.
-
-These functions grant C<"SUPER"> token as a prefix of the method name. Note
-that if you want to keep the returned glob for a long time, you need to
-check for it being "AUTOLOAD", since at the later time the call may load a
-different subroutine due to $AUTOLOAD changing its value. Use the glob
-created via a side effect to do this.
-
-These functions have the same side-effects and as C<gv_fetchmeth> with
-C<level==0>. C<name> should be writable if contains C<':'> or C<'
-''>. The warning against passing the GV returned by C<gv_fetchmeth> to
-C<call_sv> apply equally to these functions.
-
- GV* gv_fetchmethod_autoload(HV* stash,
- const char* name,
- I32 autoload)
-
-=for hackers
-Found in file gv.c
-
-=item gv_fetchmeth_autoload
-X<gv_fetchmeth_autoload>
-
-This is the old form of L</gv_fetchmeth_pvn_autoload>, which has no flags
-parameter.
-
- GV* gv_fetchmeth_autoload(HV* stash,
- const char* name,
- STRLEN len, I32 level)
-
-=for hackers
-Found in file gv.c
-
-=item gv_fetchmeth_pv
-X<gv_fetchmeth_pv>
-
-Exactly like L</gv_fetchmeth_pvn>, but takes a nul-terminated string
-instead of a string/length pair.
-
- GV* gv_fetchmeth_pv(HV* stash, const char* name,
- I32 level, U32 flags)
-
-=for hackers
-Found in file gv.c
-
-=item gv_fetchmeth_pvn
-X<gv_fetchmeth_pvn>
-
-Returns the glob with the given C<name> and a defined subroutine or
-C<NULL>. The glob lives in the given C<stash>, or in the stashes
-accessible via @ISA and UNIVERSAL::.
-
-The argument C<level> should be either 0 or -1. If C<level==0>, as a
-side-effect creates a glob with the given C<name> in the given C<stash>
-which in the case of success contains an alias for the subroutine, and sets
-up caching info for this glob.
-
-Currently, the only significant value for C<flags> is SVf_UTF8.
-
-This function grants C<"SUPER"> token as a postfix of the stash name. The
-GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
-visible to Perl code. So when calling C<call_sv>, you should not use
-the GV directly; instead, you should use the method's CV, which can be
-obtained from the GV with the C<GvCV> macro.
-
- GV* gv_fetchmeth_pvn(HV* stash, const char* name,
- STRLEN len, I32 level,
- U32 flags)
-
-=for hackers
-Found in file gv.c
-
-=item gv_fetchmeth_pvn_autoload
-X<gv_fetchmeth_pvn_autoload>
-
-Same as gv_fetchmeth_pvn(), but looks for autoloaded subroutines too.
-Returns a glob for the subroutine.
-
-For an autoloaded subroutine without a GV, will create a GV even
-if C<level < 0>. For an autoloaded subroutine without a stub, GvCV()
-of the result may be zero.
-
-Currently, the only significant value for C<flags> is SVf_UTF8.
-
- GV* gv_fetchmeth_pvn_autoload(HV* stash,
- const char* name,
- STRLEN len, I32 level,
- U32 flags)
-
-=for hackers
-Found in file gv.c
-
-=item gv_fetchmeth_pv_autoload
-X<gv_fetchmeth_pv_autoload>
-
-Exactly like L</gv_fetchmeth_pvn_autoload>, but takes a nul-terminated string
-instead of a string/length pair.
-
- GV* gv_fetchmeth_pv_autoload(HV* stash,
- const char* name,
- I32 level, U32 flags)
-
-=for hackers
-Found in file gv.c
-
-=item gv_fetchmeth_sv
-X<gv_fetchmeth_sv>
-
-Exactly like L</gv_fetchmeth_pvn>, but takes the name string in the form
-of an SV instead of a string/length pair.
-
- GV* gv_fetchmeth_sv(HV* stash, SV* namesv,
- I32 level, U32 flags)
-
-=for hackers
-Found in file gv.c
-
-=item gv_fetchmeth_sv_autoload
-X<gv_fetchmeth_sv_autoload>
-
-Exactly like L</gv_fetchmeth_pvn_autoload>, but takes the name string in the form
-of an SV instead of a string/length pair.
-
- GV* gv_fetchmeth_sv_autoload(HV* stash, SV* namesv,
- I32 level, U32 flags)
-
-=for hackers
-Found in file gv.c
-
-=item gv_init
-X<gv_init>
-
-The old form of gv_init_pvn(). It does not work with UTF8 strings, as it
-has no flags parameter. If the C<multi> parameter is set, the
-GV_ADDMULTI flag will be passed to gv_init_pvn().
-
- void gv_init(GV* gv, HV* stash, const char* name,
- STRLEN len, int multi)
-
-=for hackers
-Found in file gv.c
-
-=item gv_init_pv
-X<gv_init_pv>
-
-Same as gv_init_pvn(), but takes a nul-terminated string for the name
-instead of separate char * and length parameters.
-
- void gv_init_pv(GV* gv, HV* stash, const char* name,
- U32 flags)
-
-=for hackers
-Found in file gv.c
-
-=item gv_init_pvn
-X<gv_init_pvn>
-
-Converts a scalar into a typeglob. This is an incoercible typeglob;
-assigning a reference to it will assign to one of its slots, instead of
-overwriting it as happens with typeglobs created by SvSetSV. Converting
-any scalar that is SvOK() may produce unpredictable results and is reserved
-for perl's internal use.
-
-C<gv> is the scalar to be converted.
-
-C<stash> is the parent stash/package, if any.
-
-C<name> and C<len> give the name. The name must be unqualified;
-that is, it must not include the package name. If C<gv> is a
-stash element, it is the caller's responsibility to ensure that the name
-passed to this function matches the name of the element. If it does not
-match, perl's internal bookkeeping will get out of sync.
-
-C<flags> can be set to SVf_UTF8 if C<name> is a UTF8 string, or
-the return value of SvUTF8(sv). It can also take the
-GV_ADDMULTI flag, which means to pretend that the GV has been
-seen before (i.e., suppress "Used once" warnings).
-
- void gv_init_pvn(GV* gv, HV* stash, const char* name,
- STRLEN len, U32 flags)
-
-=for hackers
-Found in file gv.c
-
-=item gv_init_sv
-X<gv_init_sv>
-
-Same as gv_init_pvn(), but takes an SV * for the name instead of separate
-char * and length parameters. C<flags> is currently unused.
-
- void gv_init_sv(GV* gv, HV* stash, SV* namesv,
- U32 flags)
-
-=for hackers
-Found in file gv.c
-
-=item gv_stashpv
-X<gv_stashpv>
-
-Returns a pointer to the stash for a specified package. Uses C<strlen> to
-determine the length of C<name>, then calls C<gv_stashpvn()>.
-
- HV* gv_stashpv(const char* name, I32 flags)
-
-=for hackers
-Found in file gv.c
-
-=item gv_stashpvn
-X<gv_stashpvn>
-
-Returns a pointer to the stash for a specified package. The C<namelen>
-parameter indicates the length of the C<name>, in bytes. C<flags> is passed
-to C<gv_fetchpvn_flags()>, so if set to C<GV_ADD> then the package will be
-created if it does not already exist. If the package does not exist and
-C<flags> is 0 (or any other setting that does not create packages) then NULL
-is returned.
-
-
- HV* gv_stashpvn(const char* name, U32 namelen,
- I32 flags)
-
-=for hackers
-Found in file gv.c
-
-=item gv_stashpvs
-X<gv_stashpvs>
-
-Like C<gv_stashpvn>, but takes a literal string instead of a string/length pair.
-
- HV* gv_stashpvs(const char* name, I32 create)
-
-=for hackers
-Found in file handy.h
-
-=item gv_stashsv
-X<gv_stashsv>
-
-Returns a pointer to the stash for a specified package. See C<gv_stashpvn>.
-
- HV* gv_stashsv(SV* sv, I32 flags)
-
-=for hackers
-Found in file gv.c
-
-
-=back
-
-=head1 Handy Values
-
-=over 8
-
-=item Nullav
-X<Nullav>
-
-Null AV pointer.
-
-(deprecated - use C<(AV *)NULL> instead)
-
-=for hackers
-Found in file av.h
-
-=item Nullch
-X<Nullch>
-
-Null character pointer. (No longer available when C<PERL_CORE> is defined.)
-
-=for hackers
-Found in file handy.h
-
-=item Nullcv
-X<Nullcv>
-
-Null CV pointer.
-
-(deprecated - use C<(CV *)NULL> instead)
-
-=for hackers
-Found in file cv.h
-
-=item Nullhv
-X<Nullhv>
-
-Null HV pointer.
-
-(deprecated - use C<(HV *)NULL> instead)
-
-=for hackers
-Found in file hv.h
-
-=item Nullsv
-X<Nullsv>
-
-Null SV pointer. (No longer available when C<PERL_CORE> is defined.)
-
-=for hackers
-Found in file handy.h
-
-
-=back
-
-=head1 Hash Manipulation Functions
-
-=over 8
-
-=item cop_fetch_label
-X<cop_fetch_label>
-
-Returns the label attached to a cop.
-The flags pointer may be set to C<SVf_UTF8> or 0.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- const char * cop_fetch_label(COP *const cop,
- STRLEN *len, U32 *flags)
-
-=for hackers
-Found in file hv.c
-
-=item cop_store_label
-X<cop_store_label>
-
-Save a label into a C<cop_hints_hash>. You need to set flags to C<SVf_UTF8>
-for a utf-8 label.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void cop_store_label(COP *const cop,
- const char *label, STRLEN len,
- U32 flags)
-
-=for hackers
-Found in file hv.c
-
-=item get_hv
-X<get_hv>
-
-Returns the HV of the specified Perl hash. C<flags> are passed to
-C<gv_fetchpv>. If C<GV_ADD> is set and the
-Perl variable does not exist then it will be created. If C<flags> is zero
-and the variable does not exist then NULL is returned.
-
-NOTE: the perl_ form of this function is deprecated.
-
- HV* get_hv(const char *name, I32 flags)
-
-=for hackers
-Found in file perl.c
-
-=item HEf_SVKEY
-X<HEf_SVKEY>
-
-This flag, used in the length slot of hash entries and magic structures,
-specifies the structure contains an C<SV*> pointer where a C<char*> pointer
-is to be expected. (For information only--not to be used).
-
-=for hackers
-Found in file hv.h
-
-=item HeHASH
-X<HeHASH>
-
-Returns the computed hash stored in the hash entry.
-
- U32 HeHASH(HE* he)
-
-=for hackers
-Found in file hv.h
-
-=item HeKEY
-X<HeKEY>
-
-Returns the actual pointer stored in the key slot of the hash entry. The
-pointer may be either C<char*> or C<SV*>, depending on the value of
-C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros are
-usually preferable for finding the value of a key.
-
- void* HeKEY(HE* he)
-
-=for hackers
-Found in file hv.h
-
-=item HeKLEN
-X<HeKLEN>
-
-If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
-holds an C<SV*> key. Otherwise, holds the actual length of the key. Can
-be assigned to. The C<HePV()> macro is usually preferable for finding key
-lengths.
-
- STRLEN HeKLEN(HE* he)
-
-=for hackers
-Found in file hv.h
-
-=item HePV
-X<HePV>
-
-Returns the key slot of the hash entry as a C<char*> value, doing any
-necessary dereferencing of possibly C<SV*> keys. The length of the string
-is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do
-not care about what the length of the key is, you may use the global
-variable C<PL_na>, though this is rather less efficient than using a local
-variable. Remember though, that hash keys in perl are free to contain
-embedded nulls, so using C<strlen()> or similar is not a good way to find
-the length of hash keys. This is very similar to the C<SvPV()> macro
-described elsewhere in this document. See also C<HeUTF8>.
-
-If you are using C<HePV> to get values to pass to C<newSVpvn()> to create a
-new SV, you should consider using C<newSVhek(HeKEY_hek(he))> as it is more
-efficient.
-
- char* HePV(HE* he, STRLEN len)
-
-=for hackers
-Found in file hv.h
-
-=item HeSVKEY
-X<HeSVKEY>
-
-Returns the key as an C<SV*>, or C<NULL> if the hash entry does not
-contain an C<SV*> key.
-
- SV* HeSVKEY(HE* he)
-
-=for hackers
-Found in file hv.h
-
-=item HeSVKEY_force
-X<HeSVKEY_force>
-
-Returns the key as an C<SV*>. Will create and return a temporary mortal
-C<SV*> if the hash entry contains only a C<char*> key.
-
- SV* HeSVKEY_force(HE* he)
-
-=for hackers
-Found in file hv.h
-
-=item HeSVKEY_set
-X<HeSVKEY_set>
-
-Sets the key to a given C<SV*>, taking care to set the appropriate flags to
-indicate the presence of an C<SV*> key, and returns the same
-C<SV*>.
-
- SV* HeSVKEY_set(HE* he, SV* sv)
-
-=for hackers
-Found in file hv.h
-
-=item HeUTF8
-X<HeUTF8>
-
-Returns whether the C<char *> value returned by C<HePV> is encoded in UTF-8,
-doing any necessary dereferencing of possibly C<SV*> keys. The value returned
-will be 0 or non-0, not necessarily 1 (or even a value with any low bits set),
-so B<do not> blindly assign this to a C<bool> variable, as C<bool> may be a
-typedef for C<char>.
-
- char* HeUTF8(HE* he)
-
-=for hackers
-Found in file hv.h
-
-=item HeVAL
-X<HeVAL>
-
-Returns the value slot (type C<SV*>) stored in the hash entry.
-
- SV* HeVAL(HE* he)
-
-=for hackers
-Found in file hv.h
-
-=item HvENAME
-X<HvENAME>
-
-Returns the effective name of a stash, or NULL if there is none. The
-effective name represents a location in the symbol table where this stash
-resides. It is updated automatically when packages are aliased or deleted.
-A stash that is no longer in the symbol table has no effective name. This
-name is preferable to C<HvNAME> for use in MRO linearisations and isa
-caches.
-
- char* HvENAME(HV* stash)
-
-=for hackers
-Found in file hv.h
-
-=item HvENAMELEN
-X<HvENAMELEN>
-
-Returns the length of the stash's effective name.
-
- STRLEN HvENAMELEN(HV *stash)
-
-=for hackers
-Found in file hv.h
-
-=item HvENAMEUTF8
-X<HvENAMEUTF8>
-
-Returns true if the effective name is in UTF8 encoding.
-
- unsigned char HvENAMEUTF8(HV *stash)
-
-=for hackers
-Found in file hv.h
-
-=item HvNAME
-X<HvNAME>
-
-Returns the package name of a stash, or NULL if C<stash> isn't a stash.
-See C<SvSTASH>, C<CvSTASH>.
-
- char* HvNAME(HV* stash)
-
-=for hackers
-Found in file hv.h
-
-=item HvNAMELEN
-X<HvNAMELEN>
-
-Returns the length of the stash's name.
-
- STRLEN HvNAMELEN(HV *stash)
-
-=for hackers
-Found in file hv.h
-
-=item HvNAMEUTF8
-X<HvNAMEUTF8>
-
-Returns true if the name is in UTF8 encoding.
-
- unsigned char HvNAMEUTF8(HV *stash)
-
-=for hackers
-Found in file hv.h
-
-=item hv_assert
-X<hv_assert>
-
-Check that a hash is in an internally consistent state.
-
- void hv_assert(HV *hv)
-
-=for hackers
-Found in file hv.c
-
-=item hv_clear
-X<hv_clear>
-
-Frees the all the elements of a hash, leaving it empty.
-The XS equivalent of C<%hash = ()>. See also L</hv_undef>.
-
-If any destructors are triggered as a result, the hv itself may
-be freed.
-
- void hv_clear(HV *hv)
-
-=for hackers
-Found in file hv.c
-
-=item hv_clear_placeholders
-X<hv_clear_placeholders>
-
-Clears any placeholders from a hash. If a restricted hash has any of its keys
-marked as readonly and the key is subsequently deleted, the key is not actually
-deleted but is marked by assigning it a value of &PL_sv_placeholder. This tags
-it so it will be ignored by future operations such as iterating over the hash,
-but will still allow the hash to have a value reassigned to the key at some
-future point. This function clears any such placeholder keys from the hash.
-See Hash::Util::lock_keys() for an example of its use.
-
- void hv_clear_placeholders(HV *hv)
-
-=for hackers
-Found in file hv.c
-
-=item hv_copy_hints_hv
-X<hv_copy_hints_hv>
-
-A specialised version of L</newHVhv> for copying C<%^H>. I<ohv> must be
-a pointer to a hash (which may have C<%^H> magic, but should be generally
-non-magical), or C<NULL> (interpreted as an empty hash). The content
-of I<ohv> is copied to a new hash, which has the C<%^H>-specific magic
-added to it. A pointer to the new hash is returned.
-
- HV * hv_copy_hints_hv(HV *ohv)
-
-=for hackers
-Found in file hv.c
-
-=item hv_delete
-X<hv_delete>
-
-Deletes a key/value pair in the hash. The value's SV is removed from
-the hash, made mortal, and returned to the caller. The absolute
-value of C<klen> is the length of the key. If C<klen> is negative the
-key is assumed to be in UTF-8-encoded Unicode. The C<flags> value
-will normally be zero; if set to G_DISCARD then NULL will be returned.
-NULL will also be returned if the key is not found.
-
- SV* hv_delete(HV *hv, const char *key, I32 klen,
- I32 flags)
-
-=for hackers
-Found in file hv.c
-
-=item hv_delete_ent
-X<hv_delete_ent>
-
-Deletes a key/value pair in the hash. The value SV is removed from the hash,
-made mortal, and returned to the caller. The C<flags> value will normally be
-zero; if set to G_DISCARD then NULL will be returned. NULL will also be
-returned if the key is not found. C<hash> can be a valid precomputed hash
-value, or 0 to ask for it to be computed.
-
- SV* hv_delete_ent(HV *hv, SV *keysv, I32 flags,
- U32 hash)
-
-=for hackers
-Found in file hv.c
-
-=item hv_exists
-X<hv_exists>
-
-Returns a boolean indicating whether the specified hash key exists. The
-absolute value of C<klen> is the length of the key. If C<klen> is
-negative the key is assumed to be in UTF-8-encoded Unicode.
-
- bool hv_exists(HV *hv, const char *key, I32 klen)
-
-=for hackers
-Found in file hv.c
-
-=item hv_exists_ent
-X<hv_exists_ent>
-
-Returns a boolean indicating whether
-the specified hash key exists. C<hash>
-can be a valid precomputed hash value, or 0 to ask for it to be
-computed.
-
- bool hv_exists_ent(HV *hv, SV *keysv, U32 hash)
-
-=for hackers
-Found in file hv.c
-
-=item hv_fetch
-X<hv_fetch>
-
-Returns the SV which corresponds to the specified key in the hash.
-The absolute value of C<klen> is the length of the key. If C<klen> is
-negative the key is assumed to be in UTF-8-encoded Unicode. If
-C<lval> is set then the fetch will be part of a store. Check that the
-return value is non-null before dereferencing it to an C<SV*>.
-
-See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
-information on how to use this function on tied hashes.
-
- SV** hv_fetch(HV *hv, const char *key, I32 klen,
- I32 lval)
-
-=for hackers
-Found in file hv.c
-
-=item hv_fetchs
-X<hv_fetchs>
-
-Like C<hv_fetch>, but takes a literal string instead of a string/length pair.
-
- SV** hv_fetchs(HV* tb, const char* key, I32 lval)
-
-=for hackers
-Found in file handy.h
-
-=item hv_fetch_ent
-X<hv_fetch_ent>
-
-Returns the hash entry which corresponds to the specified key in the hash.
-C<hash> must be a valid precomputed hash number for the given C<key>, or 0
-if you want the function to compute it. IF C<lval> is set then the fetch
-will be part of a store. Make sure the return value is non-null before
-accessing it. The return value when C<hv> is a tied hash is a pointer to a
-static location, so be sure to make a copy of the structure if you need to
-store it somewhere.
-
-See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
-information on how to use this function on tied hashes.
-
- HE* hv_fetch_ent(HV *hv, SV *keysv, I32 lval,
- U32 hash)
-
-=for hackers
-Found in file hv.c
-
-=item hv_fill
-X<hv_fill>
-
-Returns the number of hash buckets that happen to be in use. This function is
-wrapped by the macro C<HvFILL>.
-
-Previously this value was stored in the HV structure, rather than being
-calculated on demand.
-
- STRLEN hv_fill(HV const *const hv)
-
-=for hackers
-Found in file hv.c
-
-=item hv_iterinit
-X<hv_iterinit>
-
-Prepares a starting point to traverse a hash table. Returns the number of
-keys in the hash (i.e. the same as C<HvUSEDKEYS(hv)>). The return value is
-currently only meaningful for hashes without tie magic.
-
-NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
-hash buckets that happen to be in use. If you still need that esoteric
-value, you can get it through the macro C<HvFILL(hv)>.
-
-
- I32 hv_iterinit(HV *hv)
-
-=for hackers
-Found in file hv.c
-
-=item hv_iterkey
-X<hv_iterkey>
-
-Returns the key from the current position of the hash iterator. See
-C<hv_iterinit>.
-
- char* hv_iterkey(HE* entry, I32* retlen)
-
-=for hackers
-Found in file hv.c
-
-=item hv_iterkeysv
-X<hv_iterkeysv>
-
-Returns the key as an C<SV*> from the current position of the hash
-iterator. The return value will always be a mortal copy of the key. Also
-see C<hv_iterinit>.
-
- SV* hv_iterkeysv(HE* entry)
-
-=for hackers
-Found in file hv.c
-
-=item hv_iternext
-X<hv_iternext>
-
-Returns entries from a hash iterator. See C<hv_iterinit>.
-
-You may call C<hv_delete> or C<hv_delete_ent> on the hash entry that the
-iterator currently points to, without losing your place or invalidating your
-iterator. Note that in this case the current entry is deleted from the hash
-with your iterator holding the last reference to it. Your iterator is flagged
-to free the entry on the next call to C<hv_iternext>, so you must not discard
-your iterator immediately else the entry will leak - call C<hv_iternext> to
-trigger the resource deallocation.
-
- HE* hv_iternext(HV *hv)
-
-=for hackers
-Found in file hv.c
-
-=item hv_iternextsv
-X<hv_iternextsv>
-
-Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
-operation.
-
- SV* hv_iternextsv(HV *hv, char **key, I32 *retlen)
-
-=for hackers
-Found in file hv.c
-
-=item hv_iternext_flags
-X<hv_iternext_flags>
-
-Returns entries from a hash iterator. See C<hv_iterinit> and C<hv_iternext>.
-The C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is
-set the placeholders keys (for restricted hashes) will be returned in addition
-to normal keys. By default placeholders are automatically skipped over.
-Currently a placeholder is implemented with a value that is
-C<&PL_sv_placeholder>. Note that the implementation of placeholders and
-restricted hashes may change, and the implementation currently is
-insufficiently abstracted for any change to be tidy.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- HE* hv_iternext_flags(HV *hv, I32 flags)
-
-=for hackers
-Found in file hv.c
-
-=item hv_iterval
-X<hv_iterval>
-
-Returns the value from the current position of the hash iterator. See
-C<hv_iterkey>.
-
- SV* hv_iterval(HV *hv, HE *entry)
-
-=for hackers
-Found in file hv.c
-
-=item hv_magic
-X<hv_magic>
-
-Adds magic to a hash. See C<sv_magic>.
-
- void hv_magic(HV *hv, GV *gv, int how)
-
-=for hackers
-Found in file hv.c
-
-=item hv_scalar
-X<hv_scalar>
-
-Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied.
-
- SV* hv_scalar(HV *hv)
-
-=for hackers
-Found in file hv.c
-
-=item hv_store
-X<hv_store>
-
-Stores an SV in a hash. The hash key is specified as C<key> and the
-absolute value of C<klen> is the length of the key. If C<klen> is
-negative the key is assumed to be in UTF-8-encoded Unicode. The
-C<hash> parameter is the precomputed hash value; if it is zero then
-Perl will compute it.
-
-The return value will be
-NULL if the operation failed or if the value did not need to be actually
-stored within the hash (as in the case of tied hashes). Otherwise it can
-be dereferenced to get the original C<SV*>. Note that the caller is
-responsible for suitably incrementing the reference count of C<val> before
-the call, and decrementing it if the function returned NULL. Effectively
-a successful hv_store takes ownership of one reference to C<val>. This is
-usually what you want; a newly created SV has a reference count of one, so
-if all your code does is create SVs then store them in a hash, hv_store
-will own the only reference to the new SV, and your code doesn't need to do
-anything further to tidy up. hv_store is not implemented as a call to
-hv_store_ent, and does not create a temporary SV for the key, so if your
-key data is not already in SV form then use hv_store in preference to
-hv_store_ent.
-
-See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
-information on how to use this function on tied hashes.
-
- SV** hv_store(HV *hv, const char *key, I32 klen,
- SV *val, U32 hash)
-
-=for hackers
-Found in file hv.c
-
-=item hv_stores
-X<hv_stores>
-
-Like C<hv_store>, but takes a literal string instead of a string/length pair
-and omits the hash parameter.
-
- SV** hv_stores(HV* tb, const char* key,
- NULLOK SV* val)
-
-=for hackers
-Found in file handy.h
-
-=item hv_store_ent
-X<hv_store_ent>
-
-Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
-parameter is the precomputed hash value; if it is zero then Perl will
-compute it. The return value is the new hash entry so created. It will be
-NULL if the operation failed or if the value did not need to be actually
-stored within the hash (as in the case of tied hashes). Otherwise the
-contents of the return value can be accessed using the C<He?> macros
-described here. Note that the caller is responsible for suitably
-incrementing the reference count of C<val> before the call, and
-decrementing it if the function returned NULL. Effectively a successful
-hv_store_ent takes ownership of one reference to C<val>. This is
-usually what you want; a newly created SV has a reference count of one, so
-if all your code does is create SVs then store them in a hash, hv_store
-will own the only reference to the new SV, and your code doesn't need to do
-anything further to tidy up. Note that hv_store_ent only reads the C<key>;
-unlike C<val> it does not take ownership of it, so maintaining the correct
-reference count on C<key> is entirely the caller's responsibility. hv_store
-is not implemented as a call to hv_store_ent, and does not create a temporary
-SV for the key, so if your key data is not already in SV form then use
-hv_store in preference to hv_store_ent.
-
-See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
-information on how to use this function on tied hashes.
-
- HE* hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
-
-=for hackers
-Found in file hv.c
-
-=item hv_undef
-X<hv_undef>
-
-Undefines the hash. The XS equivalent of C<undef(%hash)>.
-
-As well as freeing all the elements of the hash (like hv_clear()), this
-also frees any auxiliary data and storage associated with the hash.
-
-If any destructors are triggered as a result, the hv itself may
-be freed.
-
-See also L</hv_clear>.
-
- void hv_undef(HV *hv)
-
-=for hackers
-Found in file hv.c
-
-=item newHV
-X<newHV>
-
-Creates a new HV. The reference count is set to 1.
-
- HV* newHV()
-
-=for hackers
-Found in file hv.h
-
-
-=back
-
-=head1 Hook manipulation
-
-=over 8
-
-=item wrap_op_checker
-X<wrap_op_checker>
-
-Puts a C function into the chain of check functions for a specified op
-type. This is the preferred way to manipulate the L</PL_check> array.
-I<opcode> specifies which type of op is to be affected. I<new_checker>
-is a pointer to the C function that is to be added to that opcode's
-check chain, and I<old_checker_p> points to the storage location where a
-pointer to the next function in the chain will be stored. The value of
-I<new_pointer> is written into the L</PL_check> array, while the value
-previously stored there is written to I<*old_checker_p>.
-
-L</PL_check> is global to an entire process, and a module wishing to
-hook op checking may find itself invoked more than once per process,
-typically in different threads. To handle that situation, this function
-is idempotent. The location I<*old_checker_p> must initially (once
-per process) contain a null pointer. A C variable of static duration
-(declared at file scope, typically also marked C<static> to give
-it internal linkage) will be implicitly initialised appropriately,
-if it does not have an explicit initialiser. This function will only
-actually modify the check chain if it finds I<*old_checker_p> to be null.
-This function is also thread safe on the small scale. It uses appropriate
-locking to avoid race conditions in accessing L</PL_check>.
-
-When this function is called, the function referenced by I<new_checker>
-must be ready to be called, except for I<*old_checker_p> being unfilled.
-In a threading situation, I<new_checker> may be called immediately,
-even before this function has returned. I<*old_checker_p> will always
-be appropriately set before I<new_checker> is called. If I<new_checker>
-decides not to do anything special with an op that it is given (which
-is the usual case for most uses of op check hooking), it must chain the
-check function referenced by I<*old_checker_p>.
-
-If you want to influence compilation of calls to a specific subroutine,
-then use L</cv_set_call_checker> rather than hooking checking of all
-C<entersub> ops.
-
- void wrap_op_checker(Optype opcode,
- Perl_check_t new_checker,
- Perl_check_t *old_checker_p)
-
-=for hackers
-Found in file op.c
-
-
-=back
-
-=head1 Lexer interface
-
-=over 8
-
-=item lex_bufutf8
-X<lex_bufutf8>
-
-Indicates whether the octets in the lexer buffer
-(L</PL_parser-E<gt>linestr>) should be interpreted as the UTF-8 encoding
-of Unicode characters. If not, they should be interpreted as Latin-1
-characters. This is analogous to the C<SvUTF8> flag for scalars.
-
-In UTF-8 mode, it is not guaranteed that the lexer buffer actually
-contains valid UTF-8. Lexing code must be robust in the face of invalid
-encoding.
-
-The actual C<SvUTF8> flag of the L</PL_parser-E<gt>linestr> scalar
-is significant, but not the whole story regarding the input character
-encoding. Normally, when a file is being read, the scalar contains octets
-and its C<SvUTF8> flag is off, but the octets should be interpreted as
-UTF-8 if the C<use utf8> pragma is in effect. During a string eval,
-however, the scalar may have the C<SvUTF8> flag on, and in this case its
-octets should be interpreted as UTF-8 unless the C<use bytes> pragma
-is in effect. This logic may change in the future; use this function
-instead of implementing the logic yourself.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- bool lex_bufutf8()
-
-=for hackers
-Found in file toke.c
-
-=item lex_discard_to
-X<lex_discard_to>
-
-Discards the first part of the L</PL_parser-E<gt>linestr> buffer,
-up to I<ptr>. The remaining content of the buffer will be moved, and
-all pointers into the buffer updated appropriately. I<ptr> must not
-be later in the buffer than the position of L</PL_parser-E<gt>bufptr>:
-it is not permitted to discard text that has yet to be lexed.
-
-Normally it is not necessarily to do this directly, because it suffices to
-use the implicit discarding behaviour of L</lex_next_chunk> and things
-based on it. However, if a token stretches across multiple lines,
-and the lexing code has kept multiple lines of text in the buffer for
-that purpose, then after completion of the token it would be wise to
-explicitly discard the now-unneeded earlier lines, to avoid future
-multi-line tokens growing the buffer without bound.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void lex_discard_to(char *ptr)
-
-=for hackers
-Found in file toke.c
-
-=item lex_grow_linestr
-X<lex_grow_linestr>
-
-Reallocates the lexer buffer (L</PL_parser-E<gt>linestr>) to accommodate
-at least I<len> octets (including terminating NUL). Returns a
-pointer to the reallocated buffer. This is necessary before making
-any direct modification of the buffer that would increase its length.
-L</lex_stuff_pvn> provides a more convenient way to insert text into
-the buffer.
-
-Do not use C<SvGROW> or C<sv_grow> directly on C<PL_parser-E<gt>linestr>;
-this function updates all of the lexer's variables that point directly
-into the buffer.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- char * lex_grow_linestr(STRLEN len)
-
-=for hackers
-Found in file toke.c
-
-=item lex_next_chunk
-X<lex_next_chunk>
-
-Reads in the next chunk of text to be lexed, appending it to
-L</PL_parser-E<gt>linestr>. This should be called when lexing code has
-looked to the end of the current chunk and wants to know more. It is
-usual, but not necessary, for lexing to have consumed the entirety of
-the current chunk at this time.
-
-If L</PL_parser-E<gt>bufptr> is pointing to the very end of the current
-chunk (i.e., the current chunk has been entirely consumed), normally the
-current chunk will be discarded at the same time that the new chunk is
-read in. If I<flags> includes C<LEX_KEEP_PREVIOUS>, the current chunk
-will not be discarded. If the current chunk has not been entirely
-consumed, then it will not be discarded regardless of the flag.
-
-Returns true if some new text was added to the buffer, or false if the
-buffer has reached the end of the input text.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- bool lex_next_chunk(U32 flags)
-
-=for hackers
-Found in file toke.c
-
-=item lex_peek_unichar
-X<lex_peek_unichar>
-
-Looks ahead one (Unicode) character in the text currently being lexed.
-Returns the codepoint (unsigned integer value) of the next character,
-or -1 if lexing has reached the end of the input text. To consume the
-peeked character, use L</lex_read_unichar>.
-
-If the next character is in (or extends into) the next chunk of input
-text, the next chunk will be read in. Normally the current chunk will be
-discarded at the same time, but if I<flags> includes C<LEX_KEEP_PREVIOUS>
-then the current chunk will not be discarded.
-
-If the input is being interpreted as UTF-8 and a UTF-8 encoding error
-is encountered, an exception is generated.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- I32 lex_peek_unichar(U32 flags)
-
-=for hackers
-Found in file toke.c
-
-=item lex_read_space
-X<lex_read_space>
-
-Reads optional spaces, in Perl style, in the text currently being
-lexed. The spaces may include ordinary whitespace characters and
-Perl-style comments. C<#line> directives are processed if encountered.
-L</PL_parser-E<gt>bufptr> is moved past the spaces, so that it points
-at a non-space character (or the end of the input text).
-
-If spaces extend into the next chunk of input text, the next chunk will
-be read in. Normally the current chunk will be discarded at the same
-time, but if I<flags> includes C<LEX_KEEP_PREVIOUS> then the current
-chunk will not be discarded.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void lex_read_space(U32 flags)
-
-=for hackers
-Found in file toke.c
-
-=item lex_read_to
-X<lex_read_to>
-
-Consume text in the lexer buffer, from L</PL_parser-E<gt>bufptr> up
-to I<ptr>. This advances L</PL_parser-E<gt>bufptr> to match I<ptr>,
-performing the correct bookkeeping whenever a newline character is passed.
-This is the normal way to consume lexed text.
-
-Interpretation of the buffer's octets can be abstracted out by
-using the slightly higher-level functions L</lex_peek_unichar> and
-L</lex_read_unichar>.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void lex_read_to(char *ptr)
-
-=for hackers
-Found in file toke.c
-
-=item lex_read_unichar
-X<lex_read_unichar>
-
-Reads the next (Unicode) character in the text currently being lexed.
-Returns the codepoint (unsigned integer value) of the character read,
-and moves L</PL_parser-E<gt>bufptr> past the character, or returns -1
-if lexing has reached the end of the input text. To non-destructively
-examine the next character, use L</lex_peek_unichar> instead.
-
-If the next character is in (or extends into) the next chunk of input
-text, the next chunk will be read in. Normally the current chunk will be
-discarded at the same time, but if I<flags> includes C<LEX_KEEP_PREVIOUS>
-then the current chunk will not be discarded.
-
-If the input is being interpreted as UTF-8 and a UTF-8 encoding error
-is encountered, an exception is generated.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- I32 lex_read_unichar(U32 flags)
-
-=for hackers
-Found in file toke.c
-
-=item lex_start
-X<lex_start>
-
-Creates and initialises a new lexer/parser state object, supplying
-a context in which to lex and parse from a new source of Perl code.
-A pointer to the new state object is placed in L</PL_parser>. An entry
-is made on the save stack so that upon unwinding the new state object
-will be destroyed and the former value of L</PL_parser> will be restored.
-Nothing else need be done to clean up the parsing context.
-
-The code to be parsed comes from I<line> and I<rsfp>. I<line>, if
-non-null, provides a string (in SV form) containing code to be parsed.
-A copy of the string is made, so subsequent modification of I<line>
-does not affect parsing. I<rsfp>, if non-null, provides an input stream
-from which code will be read to be parsed. If both are non-null, the
-code in I<line> comes first and must consist of complete lines of input,
-and I<rsfp> supplies the remainder of the source.
-
-The I<flags> parameter is reserved for future use. Currently it is only
-used by perl internally, so extensions should always pass zero.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void lex_start(SV *line, PerlIO *rsfp, U32 flags)
-
-=for hackers
-Found in file toke.c
-
-=item lex_stuff_pv
-X<lex_stuff_pv>
-
-Insert characters into the lexer buffer (L</PL_parser-E<gt>linestr>),
-immediately after the current lexing point (L</PL_parser-E<gt>bufptr>),
-reallocating the buffer if necessary. This means that lexing code that
-runs later will see the characters as if they had appeared in the input.
-It is not recommended to do this as part of normal parsing, and most
-uses of this facility run the risk of the inserted characters being
-interpreted in an unintended manner.
-
-The string to be inserted is represented by octets starting at I<pv>
-and continuing to the first nul. These octets are interpreted as either
-UTF-8 or Latin-1, according to whether the C<LEX_STUFF_UTF8> flag is set
-in I<flags>. The characters are recoded for the lexer buffer, according
-to how the buffer is currently being interpreted (L</lex_bufutf8>).
-If it is not convenient to nul-terminate a string to be inserted, the
-L</lex_stuff_pvn> function is more appropriate.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void lex_stuff_pv(const char *pv, U32 flags)
-
-=for hackers
-Found in file toke.c
-
-=item lex_stuff_pvn
-X<lex_stuff_pvn>
-
-Insert characters into the lexer buffer (L</PL_parser-E<gt>linestr>),
-immediately after the current lexing point (L</PL_parser-E<gt>bufptr>),
-reallocating the buffer if necessary. This means that lexing code that
-runs later will see the characters as if they had appeared in the input.
-It is not recommended to do this as part of normal parsing, and most
-uses of this facility run the risk of the inserted characters being
-interpreted in an unintended manner.
-
-The string to be inserted is represented by I<len> octets starting
-at I<pv>. These octets are interpreted as either UTF-8 or Latin-1,
-according to whether the C<LEX_STUFF_UTF8> flag is set in I<flags>.
-The characters are recoded for the lexer buffer, according to how the
-buffer is currently being interpreted (L</lex_bufutf8>). If a string
-to be inserted is available as a Perl scalar, the L</lex_stuff_sv>
-function is more convenient.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void lex_stuff_pvn(const char *pv, STRLEN len,
- U32 flags)
-
-=for hackers
-Found in file toke.c
-
-=item lex_stuff_pvs
-X<lex_stuff_pvs>
-
-Like L</lex_stuff_pvn>, but takes a literal string instead of a
-string/length pair.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void lex_stuff_pvs(const char *pv, U32 flags)
-
-=for hackers
-Found in file handy.h
-
-=item lex_stuff_sv
-X<lex_stuff_sv>
-
-Insert characters into the lexer buffer (L</PL_parser-E<gt>linestr>),
-immediately after the current lexing point (L</PL_parser-E<gt>bufptr>),
-reallocating the buffer if necessary. This means that lexing code that
-runs later will see the characters as if they had appeared in the input.
-It is not recommended to do this as part of normal parsing, and most
-uses of this facility run the risk of the inserted characters being
-interpreted in an unintended manner.
-
-The string to be inserted is the string value of I<sv>. The characters
-are recoded for the lexer buffer, according to how the buffer is currently
-being interpreted (L</lex_bufutf8>). If a string to be inserted is
-not already a Perl scalar, the L</lex_stuff_pvn> function avoids the
-need to construct a scalar.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void lex_stuff_sv(SV *sv, U32 flags)
-
-=for hackers
-Found in file toke.c
-
-=item lex_unstuff
-X<lex_unstuff>
-
-Discards text about to be lexed, from L</PL_parser-E<gt>bufptr> up to
-I<ptr>. Text following I<ptr> will be moved, and the buffer shortened.
-This hides the discarded text from any lexing code that runs later,
-as if the text had never appeared.
-
-This is not the normal way to consume lexed text. For that, use
-L</lex_read_to>.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void lex_unstuff(char *ptr)
-
-=for hackers
-Found in file toke.c
-
-=item parse_arithexpr
-X<parse_arithexpr>
-
-Parse a Perl arithmetic expression. This may contain operators of precedence
-down to the bit shift operators. The expression must be followed (and thus
-terminated) either by a comparison or lower-precedence operator or by
-something that would normally terminate an expression such as semicolon.
-If I<flags> includes C<PARSE_OPTIONAL> then the expression is optional,
-otherwise it is mandatory. It is up to the caller to ensure that the
-dynamic parser state (L</PL_parser> et al) is correctly set to reflect
-the source of the code to be parsed and the lexical context for the
-expression.
-
-The op tree representing the expression is returned. If an optional
-expression is absent, a null pointer is returned, otherwise the pointer
-will be non-null.
-
-If an error occurs in parsing or compilation, in most cases a valid op
-tree is returned anyway. The error is reflected in the parser state,
-normally resulting in a single exception at the top level of parsing
-which covers all the compilation errors that occurred. Some compilation
-errors, however, will throw an exception immediately.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- OP * parse_arithexpr(U32 flags)
-
-=for hackers
-Found in file toke.c
-
-=item parse_barestmt
-X<parse_barestmt>
-
-Parse a single unadorned Perl statement. This may be a normal imperative
-statement or a declaration that has compile-time effect. It does not
-include any label or other affixture. It is up to the caller to ensure
-that the dynamic parser state (L</PL_parser> et al) is correctly set to
-reflect the source of the code to be parsed and the lexical context for
-the statement.
-
-The op tree representing the statement is returned. This may be a
-null pointer if the statement is null, for example if it was actually
-a subroutine definition (which has compile-time side effects). If not
-null, it will be ops directly implementing the statement, suitable to
-pass to L</newSTATEOP>. It will not normally include a C<nextstate> or
-equivalent op (except for those embedded in a scope contained entirely
-within the statement).
-
-If an error occurs in parsing or compilation, in most cases a valid op
-tree (most likely null) is returned anyway. The error is reflected in
-the parser state, normally resulting in a single exception at the top
-level of parsing which covers all the compilation errors that occurred.
-Some compilation errors, however, will throw an exception immediately.
-
-The I<flags> parameter is reserved for future use, and must always
-be zero.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- OP * parse_barestmt(U32 flags)
-
-=for hackers
-Found in file toke.c
-
-=item parse_block
-X<parse_block>
-
-Parse a single complete Perl code block. This consists of an opening
-brace, a sequence of statements, and a closing brace. The block
-constitutes a lexical scope, so C<my> variables and various compile-time
-effects can be contained within it. It is up to the caller to ensure
-that the dynamic parser state (L</PL_parser> et al) is correctly set to
-reflect the source of the code to be parsed and the lexical context for
-the statement.
-
-The op tree representing the code block is returned. This is always a
-real op, never a null pointer. It will normally be a C<lineseq> list,
-including C<nextstate> or equivalent ops. No ops to construct any kind
-of runtime scope are included by virtue of it being a block.
-
-If an error occurs in parsing or compilation, in most cases a valid op
-tree (most likely null) is returned anyway. The error is reflected in
-the parser state, normally resulting in a single exception at the top
-level of parsing which covers all the compilation errors that occurred.
-Some compilation errors, however, will throw an exception immediately.
-
-The I<flags> parameter is reserved for future use, and must always
-be zero.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- OP * parse_block(U32 flags)
-
-=for hackers
-Found in file toke.c
-
-=item parse_fullexpr
-X<parse_fullexpr>
-
-Parse a single complete Perl expression. This allows the full
-expression grammar, including the lowest-precedence operators such
-as C<or>. The expression must be followed (and thus terminated) by a
-token that an expression would normally be terminated by: end-of-file,
-closing bracketing punctuation, semicolon, or one of the keywords that
-signals a postfix expression-statement modifier. If I<flags> includes
-C<PARSE_OPTIONAL> then the expression is optional, otherwise it is
-mandatory. It is up to the caller to ensure that the dynamic parser
-state (L</PL_parser> et al) is correctly set to reflect the source of
-the code to be parsed and the lexical context for the expression.
-
-The op tree representing the expression is returned. If an optional
-expression is absent, a null pointer is returned, otherwise the pointer
-will be non-null.
-
-If an error occurs in parsing or compilation, in most cases a valid op
-tree is returned anyway. The error is reflected in the parser state,
-normally resulting in a single exception at the top level of parsing
-which covers all the compilation errors that occurred. Some compilation
-errors, however, will throw an exception immediately.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- OP * parse_fullexpr(U32 flags)
-
-=for hackers
-Found in file toke.c
-
-=item parse_fullstmt
-X<parse_fullstmt>
-
-Parse a single complete Perl statement. This may be a normal imperative
-statement or a declaration that has compile-time effect, and may include
-optional labels. It is up to the caller to ensure that the dynamic
-parser state (L</PL_parser> et al) is correctly set to reflect the source
-of the code to be parsed and the lexical context for the statement.
-
-The op tree representing the statement is returned. This may be a
-null pointer if the statement is null, for example if it was actually
-a subroutine definition (which has compile-time side effects). If not
-null, it will be the result of a L</newSTATEOP> call, normally including
-a C<nextstate> or equivalent op.
-
-If an error occurs in parsing or compilation, in most cases a valid op
-tree (most likely null) is returned anyway. The error is reflected in
-the parser state, normally resulting in a single exception at the top
-level of parsing which covers all the compilation errors that occurred.
-Some compilation errors, however, will throw an exception immediately.
-
-The I<flags> parameter is reserved for future use, and must always
-be zero.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- OP * parse_fullstmt(U32 flags)
-
-=for hackers
-Found in file toke.c
-
-=item parse_label
-X<parse_label>
-
-Parse a single label, possibly optional, of the type that may prefix a
-Perl statement. It is up to the caller to ensure that the dynamic parser
-state (L</PL_parser> et al) is correctly set to reflect the source of
-the code to be parsed. If I<flags> includes C<PARSE_OPTIONAL> then the
-label is optional, otherwise it is mandatory.
-
-The name of the label is returned in the form of a fresh scalar. If an
-optional label is absent, a null pointer is returned.
-
-If an error occurs in parsing, which can only occur if the label is
-mandatory, a valid label is returned anyway. The error is reflected in
-the parser state, normally resulting in a single exception at the top
-level of parsing which covers all the compilation errors that occurred.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- SV * parse_label(U32 flags)
-
-=for hackers
-Found in file toke.c
-
-=item parse_listexpr
-X<parse_listexpr>
-
-Parse a Perl list expression. This may contain operators of precedence
-down to the comma operator. The expression must be followed (and thus
-terminated) either by a low-precedence logic operator such as C<or> or by
-something that would normally terminate an expression such as semicolon.
-If I<flags> includes C<PARSE_OPTIONAL> then the expression is optional,
-otherwise it is mandatory. It is up to the caller to ensure that the
-dynamic parser state (L</PL_parser> et al) is correctly set to reflect
-the source of the code to be parsed and the lexical context for the
-expression.
-
-The op tree representing the expression is returned. If an optional
-expression is absent, a null pointer is returned, otherwise the pointer
-will be non-null.
-
-If an error occurs in parsing or compilation, in most cases a valid op
-tree is returned anyway. The error is reflected in the parser state,
-normally resulting in a single exception at the top level of parsing
-which covers all the compilation errors that occurred. Some compilation
-errors, however, will throw an exception immediately.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- OP * parse_listexpr(U32 flags)
-
-=for hackers
-Found in file toke.c
-
-=item parse_stmtseq
-X<parse_stmtseq>
-
-Parse a sequence of zero or more Perl statements. These may be normal
-imperative statements, including optional labels, or declarations
-that have compile-time effect, or any mixture thereof. The statement
-sequence ends when a closing brace or end-of-file is encountered in a
-place where a new statement could have validly started. It is up to
-the caller to ensure that the dynamic parser state (L</PL_parser> et al)
-is correctly set to reflect the source of the code to be parsed and the
-lexical context for the statements.
-
-The op tree representing the statement sequence is returned. This may
-be a null pointer if the statements were all null, for example if there
-were no statements or if there were only subroutine definitions (which
-have compile-time side effects). If not null, it will be a C<lineseq>
-list, normally including C<nextstate> or equivalent ops.
-
-If an error occurs in parsing or compilation, in most cases a valid op
-tree is returned anyway. The error is reflected in the parser state,
-normally resulting in a single exception at the top level of parsing
-which covers all the compilation errors that occurred. Some compilation
-errors, however, will throw an exception immediately.
-
-The I<flags> parameter is reserved for future use, and must always
-be zero.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- OP * parse_stmtseq(U32 flags)
-
-=for hackers
-Found in file toke.c
-
-=item parse_termexpr
-X<parse_termexpr>
-
-Parse a Perl term expression. This may contain operators of precedence
-down to the assignment operators. The expression must be followed (and thus
-terminated) either by a comma or lower-precedence operator or by
-something that would normally terminate an expression such as semicolon.
-If I<flags> includes C<PARSE_OPTIONAL> then the expression is optional,
-otherwise it is mandatory. It is up to the caller to ensure that the
-dynamic parser state (L</PL_parser> et al) is correctly set to reflect
-the source of the code to be parsed and the lexical context for the
-expression.
-
-The op tree representing the expression is returned. If an optional
-expression is absent, a null pointer is returned, otherwise the pointer
-will be non-null.
-
-If an error occurs in parsing or compilation, in most cases a valid op
-tree is returned anyway. The error is reflected in the parser state,
-normally resulting in a single exception at the top level of parsing
-which covers all the compilation errors that occurred. Some compilation
-errors, however, will throw an exception immediately.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- OP * parse_termexpr(U32 flags)
-
-=for hackers
-Found in file toke.c
-
-=item PL_parser
-X<PL_parser>
-
-Pointer to a structure encapsulating the state of the parsing operation
-currently in progress. The pointer can be locally changed to perform
-a nested parse without interfering with the state of an outer parse.
-Individual members of C<PL_parser> have their own documentation.
-
-=for hackers
-Found in file toke.c
-
-=item PL_parser-E<gt>bufend
-X<PL_parser-E<gt>bufend>
-
-Direct pointer to the end of the chunk of text currently being lexed, the
-end of the lexer buffer. This is equal to C<SvPVX(PL_parser-E<gt>linestr)
-+ SvCUR(PL_parser-E<gt>linestr)>. A NUL character (zero octet) is
-always located at the end of the buffer, and does not count as part of
-the buffer's contents.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
-=for hackers
-Found in file toke.c
-
-=item PL_parser-E<gt>bufptr
-X<PL_parser-E<gt>bufptr>
-
-Points to the current position of lexing inside the lexer buffer.
-Characters around this point may be freely examined, within
-the range delimited by C<SvPVX(L</PL_parser-E<gt>linestr>)> and
-L</PL_parser-E<gt>bufend>. The octets of the buffer may be intended to be
-interpreted as either UTF-8 or Latin-1, as indicated by L</lex_bufutf8>.
-
-Lexing code (whether in the Perl core or not) moves this pointer past
-the characters that it consumes. It is also expected to perform some
-bookkeeping whenever a newline character is consumed. This movement
-can be more conveniently performed by the function L</lex_read_to>,
-which handles newlines appropriately.
-
-Interpretation of the buffer's octets can be abstracted out by
-using the slightly higher-level functions L</lex_peek_unichar> and
-L</lex_read_unichar>.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
-=for hackers
-Found in file toke.c
-
-=item PL_parser-E<gt>linestart
-X<PL_parser-E<gt>linestart>
-
-Points to the start of the current line inside the lexer buffer.
-This is useful for indicating at which column an error occurred, and
-not much else. This must be updated by any lexing code that consumes
-a newline; the function L</lex_read_to> handles this detail.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
-=for hackers
-Found in file toke.c
-
-=item PL_parser-E<gt>linestr
-X<PL_parser-E<gt>linestr>
-
-Buffer scalar containing the chunk currently under consideration of the
-text currently being lexed. This is always a plain string scalar (for
-which C<SvPOK> is true). It is not intended to be used as a scalar by
-normal scalar means; instead refer to the buffer directly by the pointer
-variables described below.
-
-The lexer maintains various C<char*> pointers to things in the
-C<PL_parser-E<gt>linestr> buffer. If C<PL_parser-E<gt>linestr> is ever
-reallocated, all of these pointers must be updated. Don't attempt to
-do this manually, but rather use L</lex_grow_linestr> if you need to
-reallocate the buffer.
-
-The content of the text chunk in the buffer is commonly exactly one
-complete line of input, up to and including a newline terminator,
-but there are situations where it is otherwise. The octets of the
-buffer may be intended to be interpreted as either UTF-8 or Latin-1.
-The function L</lex_bufutf8> tells you which. Do not use the C<SvUTF8>
-flag on this scalar, which may disagree with it.
-
-For direct examination of the buffer, the variable
-L</PL_parser-E<gt>bufend> points to the end of the buffer. The current
-lexing position is pointed to by L</PL_parser-E<gt>bufptr>. Direct use
-of these pointers is usually preferable to examination of the scalar
-through normal scalar means.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
-=for hackers
-Found in file toke.c
-
-
-=back
-
-=head1 Magical Functions
-
-=over 8
-
-=item mg_clear
-X<mg_clear>
-
-Clear something magical that the SV represents. See C<sv_magic>.
-
- int mg_clear(SV* sv)
-
-=for hackers
-Found in file mg.c
-
-=item mg_copy
-X<mg_copy>
-
-Copies the magic from one SV to another. See C<sv_magic>.
-
- int mg_copy(SV *sv, SV *nsv, const char *key,
- I32 klen)
-
-=for hackers
-Found in file mg.c
-
-=item mg_find
-X<mg_find>
-
-Finds the magic pointer for type matching the SV. See C<sv_magic>.
-
- MAGIC* mg_find(const SV* sv, int type)
-
-=for hackers
-Found in file mg.c
-
-=item mg_findext
-X<mg_findext>
-
-Finds the magic pointer of C<type> with the given C<vtbl> for the C<SV>. See
-C<sv_magicext>.
-
- MAGIC* mg_findext(const SV* sv, int type,
- const MGVTBL *vtbl)
-
-=for hackers
-Found in file mg.c
-
-=item mg_free
-X<mg_free>
-
-Free any magic storage used by the SV. See C<sv_magic>.
-
- int mg_free(SV* sv)
-
-=for hackers
-Found in file mg.c
-
-=item mg_free_type
-X<mg_free_type>
-
-Remove any magic of type I<how> from the SV I<sv>. See L</sv_magic>.
-
- void mg_free_type(SV *sv, int how)
-
-=for hackers
-Found in file mg.c
-
-=item mg_get
-X<mg_get>
-
-Do magic before a value is retrieved from the SV. See C<sv_magic>.
-
- int mg_get(SV* sv)
-
-=for hackers
-Found in file mg.c
-
-=item mg_length
-X<mg_length>
-
-Report on the SV's length. See C<sv_magic>.
-
- U32 mg_length(SV* sv)
-
-=for hackers
-Found in file mg.c
-
-=item mg_magical
-X<mg_magical>
-
-Turns on the magical status of an SV. See C<sv_magic>.
-
- void mg_magical(SV* sv)
-
-=for hackers
-Found in file mg.c
-
-=item mg_set
-X<mg_set>
-
-Do magic after a value is assigned to the SV. See C<sv_magic>.
-
- int mg_set(SV* sv)
-
-=for hackers
-Found in file mg.c
-
-=item SvGETMAGIC
-X<SvGETMAGIC>
-
-Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
-argument more than once.
-
- void SvGETMAGIC(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvLOCK
-X<SvLOCK>
-
-Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
-has been loaded.
-
- void SvLOCK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvSETMAGIC
-X<SvSETMAGIC>
-
-Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
-argument more than once.
-
- void SvSETMAGIC(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvSetMagicSV
-X<SvSetMagicSV>
-
-Like C<SvSetSV>, but does any set magic required afterwards.
-
- void SvSetMagicSV(SV* dsb, SV* ssv)
-
-=for hackers
-Found in file sv.h
-
-=item SvSetMagicSV_nosteal
-X<SvSetMagicSV_nosteal>
-
-Like C<SvSetSV_nosteal>, but does any set magic required afterwards.
-
- void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
-
-=for hackers
-Found in file sv.h
-
-=item SvSetSV
-X<SvSetSV>
-
-Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
-more than once.
-
- void SvSetSV(SV* dsb, SV* ssv)
-
-=for hackers
-Found in file sv.h
-
-=item SvSetSV_nosteal
-X<SvSetSV_nosteal>
-
-Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
-ssv. May evaluate arguments more than once.
-
- void SvSetSV_nosteal(SV* dsv, SV* ssv)
-
-=for hackers
-Found in file sv.h
-
-=item SvSHARE
-X<SvSHARE>
-
-Arranges for sv to be shared between threads if a suitable module
-has been loaded.
-
- void SvSHARE(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUNLOCK
-X<SvUNLOCK>
-
-Releases a mutual exclusion lock on sv if a suitable module
-has been loaded.
-
- void SvUNLOCK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-
-=back
-
-=head1 Memory Management
-
-=over 8
-
-=item Copy
-X<Copy>
-
-The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the
-source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
-the type. May fail on overlapping copies. See also C<Move>.
-
- void Copy(void* src, void* dest, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item CopyD
-X<CopyD>
-
-Like C<Copy> but returns dest. Useful for encouraging compilers to tail-call
-optimise.
-
- void * CopyD(void* src, void* dest, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item Move
-X<Move>
-
-The XSUB-writer's interface to the C C<memmove> function. The C<src> is the
-source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
-the type. Can do overlapping moves. See also C<Copy>.
-
- void Move(void* src, void* dest, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item MoveD
-X<MoveD>
-
-Like C<Move> but returns dest. Useful for encouraging compilers to tail-call
-optimise.
-
- void * MoveD(void* src, void* dest, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item Newx
-X<Newx>
-
-The XSUB-writer's interface to the C C<malloc> function.
-
-In 5.9.3, Newx() and friends replace the older New() API, and drops
-the first parameter, I<x>, a debug aid which allowed callers to identify
-themselves. This aid has been superseded by a new build option,
-PERL_MEM_LOG (see L<perlhacktips/PERL_MEM_LOG>). The older API is still
-there for use in XS modules supporting older perls.
-
- void Newx(void* ptr, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item Newxc
-X<Newxc>
-
-The XSUB-writer's interface to the C C<malloc> function, with
-cast. See also C<Newx>.
-
- void Newxc(void* ptr, int nitems, type, cast)
-
-=for hackers
-Found in file handy.h
-
-=item Newxz
-X<Newxz>
-
-The XSUB-writer's interface to the C C<malloc> function. The allocated
-memory is zeroed with C<memzero>. See also C<Newx>.
-
- void Newxz(void* ptr, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item Poison
-X<Poison>
-
-PoisonWith(0xEF) for catching access to freed memory.
-
- void Poison(void* dest, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item PoisonFree
-X<PoisonFree>
-
-PoisonWith(0xEF) for catching access to freed memory.
-
- void PoisonFree(void* dest, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item PoisonNew
-X<PoisonNew>
-
-PoisonWith(0xAB) for catching access to allocated but uninitialized memory.
-
- void PoisonNew(void* dest, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item PoisonWith
-X<PoisonWith>
-
-Fill up memory with a byte pattern (a byte repeated over and over
-again) that hopefully catches attempts to access uninitialized memory.
-
- void PoisonWith(void* dest, int nitems, type,
- U8 byte)
-
-=for hackers
-Found in file handy.h
-
-=item Renew
-X<Renew>
-
-The XSUB-writer's interface to the C C<realloc> function.
-
- void Renew(void* ptr, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item Renewc
-X<Renewc>
-
-The XSUB-writer's interface to the C C<realloc> function, with
-cast.
-
- void Renewc(void* ptr, int nitems, type, cast)
-
-=for hackers
-Found in file handy.h
-
-=item Safefree
-X<Safefree>
-
-The XSUB-writer's interface to the C C<free> function.
-
- void Safefree(void* ptr)
-
-=for hackers
-Found in file handy.h
-
-=item savepv
-X<savepv>
-
-Perl's version of C<strdup()>. Returns a pointer to a newly allocated
-string which is a duplicate of C<pv>. The size of the string is
-determined by C<strlen()>. The memory allocated for the new string can
-be freed with the C<Safefree()> function.
-
- char* savepv(const char* pv)
-
-=for hackers
-Found in file util.c
-
-=item savepvn
-X<savepvn>
-
-Perl's version of what C<strndup()> would be if it existed. Returns a
-pointer to a newly allocated string which is a duplicate of the first
-C<len> bytes from C<pv>, plus a trailing NUL byte. The memory allocated for
-the new string can be freed with the C<Safefree()> function.
-
- char* savepvn(const char* pv, I32 len)
-
-=for hackers
-Found in file util.c
-
-=item savepvs
-X<savepvs>
-
-Like C<savepvn>, but takes a literal string instead of a string/length pair.
-
- char* savepvs(const char* s)
-
-=for hackers
-Found in file handy.h
-
-=item savesharedpv
-X<savesharedpv>
-
-A version of C<savepv()> which allocates the duplicate string in memory
-which is shared between threads.
-
- char* savesharedpv(const char* pv)
-
-=for hackers
-Found in file util.c
-
-=item savesharedpvn
-X<savesharedpvn>
-
-A version of C<savepvn()> which allocates the duplicate string in memory
-which is shared between threads. (With the specific difference that a NULL
-pointer is not acceptable)
-
- char* savesharedpvn(const char *const pv,
- const STRLEN len)
-
-=for hackers
-Found in file util.c
-
-=item savesharedpvs
-X<savesharedpvs>
-
-A version of C<savepvs()> which allocates the duplicate string in memory
-which is shared between threads.
-
- char* savesharedpvs(const char* s)
-
-=for hackers
-Found in file handy.h
-
-=item savesharedsvpv
-X<savesharedsvpv>
-
-A version of C<savesharedpv()> which allocates the duplicate string in
-memory which is shared between threads.
-
- char* savesharedsvpv(SV *sv)
-
-=for hackers
-Found in file util.c
-
-=item savesvpv
-X<savesvpv>
-
-A version of C<savepv()>/C<savepvn()> which gets the string to duplicate from
-the passed in SV using C<SvPV()>
-
- char* savesvpv(SV* sv)
-
-=for hackers
-Found in file util.c
-
-=item StructCopy
-X<StructCopy>
-
-This is an architecture-independent macro to copy one structure to another.
-
- void StructCopy(type src, type dest, type)
-
-=for hackers
-Found in file handy.h
-
-=item Zero
-X<Zero>
-
-The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
-destination, C<nitems> is the number of items, and C<type> is the type.
-
- void Zero(void* dest, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item ZeroD
-X<ZeroD>
-
-Like C<Zero> but returns dest. Useful for encouraging compilers to tail-call
-optimise.
-
- void * ZeroD(void* dest, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-
-=back
-
-=head1 Miscellaneous Functions
-
-=over 8
-
-=item fbm_compile
-X<fbm_compile>
-
-Analyses the string in order to make fast searches on it using fbm_instr()
--- the Boyer-Moore algorithm.
-
- void fbm_compile(SV* sv, U32 flags)
-
-=for hackers
-Found in file util.c
-
-=item fbm_instr
-X<fbm_instr>
-
-Returns the location of the SV in the string delimited by C<str> and
-C<strend>. It returns C<NULL> if the string can't be found. The C<sv>
-does not have to be fbm_compiled, but the search will not be as fast
-then.
-
- char* fbm_instr(unsigned char* big,
- unsigned char* bigend, SV* littlestr,
- U32 flags)
-
-=for hackers
-Found in file util.c
-
-=item foldEQ
-X<foldEQ>
-
-Returns true if the leading len bytes of the strings s1 and s2 are the same
-case-insensitively; false otherwise. Uppercase and lowercase ASCII range bytes
-match themselves and their opposite case counterparts. Non-cased and non-ASCII
-range bytes match only themselves.
-
- I32 foldEQ(const char* a, const char* b, I32 len)
-
-=for hackers
-Found in file util.c
-
-=item foldEQ_locale
-X<foldEQ_locale>
-
-Returns true if the leading len bytes of the strings s1 and s2 are the same
-case-insensitively in the current locale; false otherwise.
-
- I32 foldEQ_locale(const char* a, const char* b,
- I32 len)
-
-=for hackers
-Found in file util.c
-
-=item form
-X<form>
-
-Takes a sprintf-style format pattern and conventional
-(non-SV) arguments and returns the formatted string.
-
- (char *) Perl_form(pTHX_ const char* pat, ...)
-
-can be used any place a string (char *) is required:
-
- char * s = Perl_form("%d.%d",major,minor);
-
-Uses a single private buffer so if you want to format several strings you
-must explicitly copy the earlier strings away (and free the copies when you
-are done).
-
- char* form(const char* pat, ...)
-
-=for hackers
-Found in file util.c
-
-=item getcwd_sv
-X<getcwd_sv>
-
-Fill the sv with current working directory
-
- int getcwd_sv(SV* sv)
-
-=for hackers
-Found in file util.c
-
-=item mess
-X<mess>
-
-Take a sprintf-style format pattern and argument list. These are used to
-generate a string message. If the message does not end with a newline,
-then it will be extended with some indication of the current location
-in the code, as described for L</mess_sv>.
-
-Normally, the resulting message is returned in a new mortal SV.
-During global destruction a single SV may be shared between uses of
-this function.
-
- SV * mess(const char *pat, ...)
-
-=for hackers
-Found in file util.c
-
-=item mess_sv
-X<mess_sv>
-
-Expands a message, intended for the user, to include an indication of
-the current location in the code, if the message does not already appear
-to be complete.
-
-C<basemsg> is the initial message or object. If it is a reference, it
-will be used as-is and will be the result of this function. Otherwise it
-is used as a string, and if it already ends with a newline, it is taken
-to be complete, and the result of this function will be the same string.
-If the message does not end with a newline, then a segment such as C<at
-foo.pl line 37> will be appended, and possibly other clauses indicating
-the current state of execution. The resulting message will end with a
-dot and a newline.
-
-Normally, the resulting message is returned in a new mortal SV.
-During global destruction a single SV may be shared between uses of this
-function. If C<consume> is true, then the function is permitted (but not
-required) to modify and return C<basemsg> instead of allocating a new SV.
-
- SV * mess_sv(SV *basemsg, bool consume)
-
-=for hackers
-Found in file util.c
-
-=item my_snprintf
-X<my_snprintf>
-
-The C library C<snprintf> functionality, if available and
-standards-compliant (uses C<vsnprintf>, actually). However, if the
-C<vsnprintf> is not available, will unfortunately use the unsafe
-C<vsprintf> which can overrun the buffer (there is an overrun check,
-but that may be too late). Consider using C<sv_vcatpvf> instead, or
-getting C<vsnprintf>.
-
- int my_snprintf(char *buffer, const Size_t len,
- const char *format, ...)
-
-=for hackers
-Found in file util.c
-
-=item my_sprintf
-X<my_sprintf>
-
-The C library C<sprintf>, wrapped if necessary, to ensure that it will return
-the length of the string written to the buffer. Only rare pre-ANSI systems
-need the wrapper function - usually this is a direct call to C<sprintf>.
-
- int my_sprintf(char *buffer, const char *pat, ...)
-
-=for hackers
-Found in file util.c
-
-=item my_vsnprintf
-X<my_vsnprintf>
-
-The C library C<vsnprintf> if available and standards-compliant.
-However, if if the C<vsnprintf> is not available, will unfortunately
-use the unsafe C<vsprintf> which can overrun the buffer (there is an
-overrun check, but that may be too late). Consider using
-C<sv_vcatpvf> instead, or getting C<vsnprintf>.
-
- int my_vsnprintf(char *buffer, const Size_t len,
- const char *format, va_list ap)
-
-=for hackers
-Found in file util.c
-
-=item new_version
-X<new_version>
-
-Returns a new version object based on the passed in SV:
-
- SV *sv = new_version(SV *ver);
-
-Does not alter the passed in ver SV. See "upg_version" if you
-want to upgrade the SV.
-
- SV* new_version(SV *ver)
-
-=for hackers
-Found in file util.c
-
-=item prescan_version
-X<prescan_version>
-
-Validate that a given string can be parsed as a version object, but doesn't
-actually perform the parsing. Can use either strict or lax validation rules.
-Can optionally set a number of hint variables to save the parsing code
-some time when tokenizing.
-
- const char* prescan_version(const char *s, bool strict,
- const char** errstr,
- bool *sqv,
- int *ssaw_decimal,
- int *swidth, bool *salpha)
-
-=for hackers
-Found in file util.c
-
-=item scan_version
-X<scan_version>
-
-Returns a pointer to the next character after the parsed
-version string, as well as upgrading the passed in SV to
-an RV.
-
-Function must be called with an already existing SV like
-
- sv = newSV(0);
- s = scan_version(s, SV *sv, bool qv);
-
-Performs some preprocessing to the string to ensure that
-it has the correct characteristics of a version. Flags the
-object if it contains an underscore (which denotes this
-is an alpha version). The boolean qv denotes that the version
-should be interpreted as if it had multiple decimals, even if
-it doesn't.
-
- const char* scan_version(const char *s, SV *rv, bool qv)
-
-=for hackers
-Found in file util.c
-
-=item strEQ
-X<strEQ>
-
-Test two strings to see if they are equal. Returns true or false.
-
- bool strEQ(char* s1, char* s2)
-
-=for hackers
-Found in file handy.h
-
-=item strGE
-X<strGE>
-
-Test two strings to see if the first, C<s1>, is greater than or equal to
-the second, C<s2>. Returns true or false.
-
- bool strGE(char* s1, char* s2)
-
-=for hackers
-Found in file handy.h
-
-=item strGT
-X<strGT>
-
-Test two strings to see if the first, C<s1>, is greater than the second,
-C<s2>. Returns true or false.
-
- bool strGT(char* s1, char* s2)
-
-=for hackers
-Found in file handy.h
-
-=item strLE
-X<strLE>
-
-Test two strings to see if the first, C<s1>, is less than or equal to the
-second, C<s2>. Returns true or false.
-
- bool strLE(char* s1, char* s2)
-
-=for hackers
-Found in file handy.h
-
-=item strLT
-X<strLT>
-
-Test two strings to see if the first, C<s1>, is less than the second,
-C<s2>. Returns true or false.
-
- bool strLT(char* s1, char* s2)
-
-=for hackers
-Found in file handy.h
-
-=item strNE
-X<strNE>
-
-Test two strings to see if they are different. Returns true or
-false.
-
- bool strNE(char* s1, char* s2)
-
-=for hackers
-Found in file handy.h
-
-=item strnEQ
-X<strnEQ>
-
-Test two strings to see if they are equal. The C<len> parameter indicates
-the number of bytes to compare. Returns true or false. (A wrapper for
-C<strncmp>).
-
- bool strnEQ(char* s1, char* s2, STRLEN len)
-
-=for hackers
-Found in file handy.h
-
-=item strnNE
-X<strnNE>
-
-Test two strings to see if they are different. The C<len> parameter
-indicates the number of bytes to compare. Returns true or false. (A
-wrapper for C<strncmp>).
-
- bool strnNE(char* s1, char* s2, STRLEN len)
-
-=for hackers
-Found in file handy.h
-
-=item sv_destroyable
-X<sv_destroyable>
-
-Dummy routine which reports that object can be destroyed when there is no
-sharing module present. It ignores its single SV argument, and returns
-'true'. Exists to avoid test for a NULL function pointer and because it
-could potentially warn under some level of strict-ness.
-
- bool sv_destroyable(SV *sv)
-
-=for hackers
-Found in file util.c
-
-=item sv_nosharing
-X<sv_nosharing>
-
-Dummy routine which "shares" an SV when there is no sharing module present.
-Or "locks" it. Or "unlocks" it. In other words, ignores its single SV argument.
-Exists to avoid test for a NULL function pointer and because it could
-potentially warn under some level of strict-ness.
-
- void sv_nosharing(SV *sv)
-
-=for hackers
-Found in file util.c
-
-=item upg_version
-X<upg_version>
-
-In-place upgrade of the supplied SV to a version object.
-
- SV *sv = upg_version(SV *sv, bool qv);
-
-Returns a pointer to the upgraded SV. Set the boolean qv if you want
-to force this SV to be interpreted as an "extended" version.
-
- SV* upg_version(SV *ver, bool qv)
-
-=for hackers
-Found in file util.c
-
-=item vcmp
-X<vcmp>
-
-Version object aware cmp. Both operands must already have been
-converted into version objects.
-
- int vcmp(SV *lhv, SV *rhv)
-
-=for hackers
-Found in file util.c
-
-=item vmess
-X<vmess>
-
-C<pat> and C<args> are a sprintf-style format pattern and encapsulated
-argument list. These are used to generate a string message. If the
-message does not end with a newline, then it will be extended with
-some indication of the current location in the code, as described for
-L</mess_sv>.
-
-Normally, the resulting message is returned in a new mortal SV.
-During global destruction a single SV may be shared between uses of
-this function.
-
- SV * vmess(const char *pat, va_list *args)
-
-=for hackers
-Found in file util.c
-
-=item vnormal
-X<vnormal>
-
-Accepts a version object and returns the normalized string
-representation. Call like:
-
- sv = vnormal(rv);
-
-NOTE: you can pass either the object directly or the SV
-contained within the RV.
-
-The SV returned has a refcount of 1.
-
- SV* vnormal(SV *vs)
-
-=for hackers
-Found in file util.c
-
-=item vnumify
-X<vnumify>
-
-Accepts a version object and returns the normalized floating
-point representation. Call like:
-
- sv = vnumify(rv);
-
-NOTE: you can pass either the object directly or the SV
-contained within the RV.
-
-The SV returned has a refcount of 1.
-
- SV* vnumify(SV *vs)
-
-=for hackers
-Found in file util.c
-
-=item vstringify
-X<vstringify>
-
-In order to maintain maximum compatibility with earlier versions
-of Perl, this function will return either the floating point
-notation or the multiple dotted notation, depending on whether
-the original version contained 1 or more dots, respectively.
-
-The SV returned has a refcount of 1.
-
- SV* vstringify(SV *vs)
-
-=for hackers
-Found in file util.c
-
-=item vverify
-X<vverify>
-
-Validates that the SV contains valid internal structure for a version object.
-It may be passed either the version object (RV) or the hash itself (HV). If
-the structure is valid, it returns the HV. If the structure is invalid,
-it returns NULL.
-
- SV *hv = vverify(sv);
-
-Note that it only confirms the bare minimum structure (so as not to get
-confused by derived classes which may contain additional hash entries):
-
- SV* vverify(SV *vs)
-
-=for hackers
-Found in file util.c
-
-
-=back
-
-=head1 MRO Functions
-
-=over 8
-
-=item mro_get_linear_isa
-X<mro_get_linear_isa>
-
-Returns the mro linearisation for the given stash. By default, this
-will be whatever C<mro_get_linear_isa_dfs> returns unless some
-other MRO is in effect for the stash. The return value is a
-read-only AV*.
-
-You are responsible for C<SvREFCNT_inc()> on the
-return value if you plan to store it anywhere
-semi-permanently (otherwise it might be deleted
-out from under you the next time the cache is
-invalidated).
-
- AV* mro_get_linear_isa(HV* stash)
-
-=for hackers
-Found in file mro.c
-
-=item mro_method_changed_in
-X<mro_method_changed_in>
-
-Invalidates method caching on any child classes
-of the given stash, so that they might notice
-the changes in this one.
-
-Ideally, all instances of C<PL_sub_generation++> in
-perl source outside of F<mro.c> should be
-replaced by calls to this.
-
-Perl automatically handles most of the common
-ways a method might be redefined. However, there
-are a few ways you could change a method in a stash
-without the cache code noticing, in which case you
-need to call this method afterwards:
-
-1) Directly manipulating the stash HV entries from
-XS code.
-
-2) Assigning a reference to a readonly scalar
-constant into a stash entry in order to create
-a constant subroutine (like constant.pm
-does).
-
-This same method is available from pure perl
-via, C<mro::method_changed_in(classname)>.
-
- void mro_method_changed_in(HV* stash)
-
-=for hackers
-Found in file mro.c
-
-=item mro_register
-X<mro_register>
-
-Registers a custom mro plugin. See L<perlmroapi> for details.
-
- void mro_register(const struct mro_alg *mro)
-
-=for hackers
-Found in file mro.c
-
-
-=back
-
-=head1 Multicall Functions
-
-=over 8
-
-=item dMULTICALL
-X<dMULTICALL>
-
-Declare local variables for a multicall. See L<perlcall/LIGHTWEIGHT CALLBACKS>.
-
- dMULTICALL;
-
-=for hackers
-Found in file cop.h
-
-=item MULTICALL
-X<MULTICALL>
-
-Make a lightweight callback. See L<perlcall/LIGHTWEIGHT CALLBACKS>.
-
- MULTICALL;
-
-=for hackers
-Found in file cop.h
-
-=item POP_MULTICALL
-X<POP_MULTICALL>
-
-Closing bracket for a lightweight callback.
-See L<perlcall/LIGHTWEIGHT CALLBACKS>.
-
- POP_MULTICALL;
-
-=for hackers
-Found in file cop.h
-
-=item PUSH_MULTICALL
-X<PUSH_MULTICALL>
-
-Opening bracket for a lightweight callback.
-See L<perlcall/LIGHTWEIGHT CALLBACKS>.
-
- PUSH_MULTICALL;
-
-=for hackers
-Found in file cop.h
-
-
-=back
-
-=head1 Numeric functions
-
-=over 8
-
-=item grok_bin
-X<grok_bin>
-
-converts a string representing a binary number to numeric form.
-
-On entry I<start> and I<*len> give the string to scan, I<*flags> gives
-conversion flags, and I<result> should be NULL or a pointer to an NV.
-The scan stops at the end of the string, or the first invalid character.
-Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
-invalid character will also trigger a warning.
-On return I<*len> is set to the length of the scanned string,
-and I<*flags> gives output flags.
-
-If the value is <= C<UV_MAX> it is returned as a UV, the output flags are clear,
-and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
-returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
-and writes the value to I<*result> (or the value is discarded if I<result>
-is NULL).
-
-The binary number may optionally be prefixed with "0b" or "b" unless
-C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
-C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
-number may use '_' characters to separate digits.
-
- UV grok_bin(const char* start, STRLEN* len_p,
- I32* flags, NV *result)
-
-=for hackers
-Found in file numeric.c
-
-=item grok_hex
-X<grok_hex>
-
-converts a string representing a hex number to numeric form.
-
-On entry I<start> and I<*len> give the string to scan, I<*flags> gives
-conversion flags, and I<result> should be NULL or a pointer to an NV.
-The scan stops at the end of the string, or the first invalid character.
-Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
-invalid character will also trigger a warning.
-On return I<*len> is set to the length of the scanned string,
-and I<*flags> gives output flags.
-
-If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
-and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
-returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
-and writes the value to I<*result> (or the value is discarded if I<result>
-is NULL).
-
-The hex number may optionally be prefixed with "0x" or "x" unless
-C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
-C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
-number may use '_' characters to separate digits.
-
- UV grok_hex(const char* start, STRLEN* len_p,
- I32* flags, NV *result)
-
-=for hackers
-Found in file numeric.c
-
-=item grok_number
-X<grok_number>
-
-Recognise (or not) a number. The type of the number is returned
-(0 if unrecognised), otherwise it is a bit-ORed combination of
-IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
-IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
-
-If the value of the number can fit an in UV, it is returned in the *valuep
-IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
-will never be set unless *valuep is valid, but *valuep may have been assigned
-to during processing even though IS_NUMBER_IN_UV is not set on return.
-If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
-valuep is non-NULL, but no actual assignment (or SEGV) will occur.
-
-IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
-seen (in which case *valuep gives the true value truncated to an integer), and
-IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
-absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the
-number is larger than a UV.
-
- int grok_number(const char *pv, STRLEN len,
- UV *valuep)
-
-=for hackers
-Found in file numeric.c
-
-=item grok_numeric_radix
-X<grok_numeric_radix>
-
-Scan and skip for a numeric decimal separator (radix).
-
- bool grok_numeric_radix(const char **sp,
- const char *send)
-
-=for hackers
-Found in file numeric.c
-
-=item grok_oct
-X<grok_oct>
-
-converts a string representing an octal number to numeric form.
-
-On entry I<start> and I<*len> give the string to scan, I<*flags> gives
-conversion flags, and I<result> should be NULL or a pointer to an NV.
-The scan stops at the end of the string, or the first invalid character.
-Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
-8 or 9 will also trigger a warning.
-On return I<*len> is set to the length of the scanned string,
-and I<*flags> gives output flags.
-
-If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
-and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct>
-returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
-and writes the value to I<*result> (or the value is discarded if I<result>
-is NULL).
-
-If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal
-number may use '_' characters to separate digits.
-
- UV grok_oct(const char* start, STRLEN* len_p,
- I32* flags, NV *result)
-
-=for hackers
-Found in file numeric.c
-
-=item Perl_signbit
-X<Perl_signbit>
-
-Return a non-zero integer if the sign bit on an NV is set, and 0 if
-it is not.
-
-If Configure detects this system has a signbit() that will work with
-our NVs, then we just use it via the #define in perl.h. Otherwise,
-fall back on this implementation. As a first pass, this gets everything
-right except -0.0. Alas, catching -0.0 is the main use for this function,
-so this is not too helpful yet. Still, at least we have the scaffolding
-in place to support other systems, should that prove useful.
-
-
-Configure notes: This function is called 'Perl_signbit' instead of a
-plain 'signbit' because it is easy to imagine a system having a signbit()
-function or macro that doesn't happen to work with our particular choice
-of NVs. We shouldn't just re-#define signbit as Perl_signbit and expect
-the standard system headers to be happy. Also, this is a no-context
-function (no pTHX_) because Perl_signbit() is usually re-#defined in
-perl.h as a simple macro call to the system's signbit().
-Users should just always call Perl_signbit().
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- int Perl_signbit(NV f)
-
-=for hackers
-Found in file numeric.c
-
-=item scan_bin
-X<scan_bin>
-
-For backwards compatibility. Use C<grok_bin> instead.
-
- NV scan_bin(const char* start, STRLEN len,
- STRLEN* retlen)
-
-=for hackers
-Found in file numeric.c
-
-=item scan_hex
-X<scan_hex>
-
-For backwards compatibility. Use C<grok_hex> instead.
-
- NV scan_hex(const char* start, STRLEN len,
- STRLEN* retlen)
-
-=for hackers
-Found in file numeric.c
-
-=item scan_oct
-X<scan_oct>
-
-For backwards compatibility. Use C<grok_oct> instead.
-
- NV scan_oct(const char* start, STRLEN len,
- STRLEN* retlen)
-
-=for hackers
-Found in file numeric.c
-
-
-=back
-
-=head1 Optree construction
-
-=over 8
-
-=item newASSIGNOP
-X<newASSIGNOP>
-
-Constructs, checks, and returns an assignment op. I<left> and I<right>
-supply the parameters of the assignment; they are consumed by this
-function and become part of the constructed op tree.
-
-If I<optype> is C<OP_ANDASSIGN>, C<OP_ORASSIGN>, or C<OP_DORASSIGN>, then
-a suitable conditional optree is constructed. If I<optype> is the opcode
-of a binary operator, such as C<OP_BIT_OR>, then an op is constructed that
-performs the binary operation and assigns the result to the left argument.
-Either way, if I<optype> is non-zero then I<flags> has no effect.
-
-If I<optype> is zero, then a plain scalar or list assignment is
-constructed. Which type of assignment it is is automatically determined.
-I<flags> gives the eight bits of C<op_flags>, except that C<OPf_KIDS>
-will be set automatically, and, shifted up eight bits, the eight bits
-of C<op_private>, except that the bit with value 1 or 2 is automatically
-set as required.
-
- OP * newASSIGNOP(I32 flags, OP *left, I32 optype,
- OP *right)
-
-=for hackers
-Found in file op.c
-
-=item newBINOP
-X<newBINOP>
-
-Constructs, checks, and returns an op of any binary type. I<type>
-is the opcode. I<flags> gives the eight bits of C<op_flags>, except
-that C<OPf_KIDS> will be set automatically, and, shifted up eight bits,
-the eight bits of C<op_private>, except that the bit with value 1 or
-2 is automatically set as required. I<first> and I<last> supply up to
-two ops to be the direct children of the binary op; they are consumed
-by this function and become part of the constructed op tree.
-
- OP * newBINOP(I32 type, I32 flags, OP *first,
- OP *last)
-
-=for hackers
-Found in file op.c
-
-=item newCONDOP
-X<newCONDOP>
-
-Constructs, checks, and returns a conditional-expression (C<cond_expr>)
-op. I<flags> gives the eight bits of C<op_flags>, except that C<OPf_KIDS>
-will be set automatically, and, shifted up eight bits, the eight bits of
-C<op_private>, except that the bit with value 1 is automatically set.
-I<first> supplies the expression selecting between the two branches,
-and I<trueop> and I<falseop> supply the branches; they are consumed by
-this function and become part of the constructed op tree.
-
- OP * newCONDOP(I32 flags, OP *first, OP *trueop,
- OP *falseop)
-
-=for hackers
-Found in file op.c
-
-=item newFOROP
-X<newFOROP>
-
-Constructs, checks, and returns an op tree expressing a C<foreach>
-loop (iteration through a list of values). This is a heavyweight loop,
-with structure that allows exiting the loop by C<last> and suchlike.
-
-I<sv> optionally supplies the variable that will be aliased to each
-item in turn; if null, it defaults to C<$_> (either lexical or global).
-I<expr> supplies the list of values to iterate over. I<block> supplies
-the main body of the loop, and I<cont> optionally supplies a C<continue>
-block that operates as a second half of the body. All of these optree
-inputs are consumed by this function and become part of the constructed
-op tree.
-
-I<flags> gives the eight bits of C<op_flags> for the C<leaveloop>
-op and, shifted up eight bits, the eight bits of C<op_private> for
-the C<leaveloop> op, except that (in both cases) some bits will be set
-automatically.
-
- OP * newFOROP(I32 flags, OP *sv, OP *expr, OP *block,
- OP *cont)
-
-=for hackers
-Found in file op.c
-
-=item newGIVENOP
-X<newGIVENOP>
-
-Constructs, checks, and returns an op tree expressing a C<given> block.
-I<cond> supplies the expression that will be locally assigned to a lexical
-variable, and I<block> supplies the body of the C<given> construct; they
-are consumed by this function and become part of the constructed op tree.
-I<defsv_off> is the pad offset of the scalar lexical variable that will
-be affected.
-
- OP * newGIVENOP(OP *cond, OP *block,
- PADOFFSET defsv_off)
-
-=for hackers
-Found in file op.c
-
-=item newGVOP
-X<newGVOP>
-
-Constructs, checks, and returns an op of any type that involves an
-embedded reference to a GV. I<type> is the opcode. I<flags> gives the
-eight bits of C<op_flags>. I<gv> identifies the GV that the op should
-reference; calling this function does not transfer ownership of any
-reference to it.
-
- OP * newGVOP(I32 type, I32 flags, GV *gv)
-
-=for hackers
-Found in file op.c
-
-=item newLISTOP
-X<newLISTOP>
-
-Constructs, checks, and returns an op of any list type. I<type> is
-the opcode. I<flags> gives the eight bits of C<op_flags>, except that
-C<OPf_KIDS> will be set automatically if required. I<first> and I<last>
-supply up to two ops to be direct children of the list op; they are
-consumed by this function and become part of the constructed op tree.
-
- OP * newLISTOP(I32 type, I32 flags, OP *first,
- OP *last)
-
-=for hackers
-Found in file op.c
-
-=item newLOGOP
-X<newLOGOP>
-
-Constructs, checks, and returns a logical (flow control) op. I<type>
-is the opcode. I<flags> gives the eight bits of C<op_flags>, except
-that C<OPf_KIDS> will be set automatically, and, shifted up eight bits,
-the eight bits of C<op_private>, except that the bit with value 1 is
-automatically set. I<first> supplies the expression controlling the
-flow, and I<other> supplies the side (alternate) chain of ops; they are
-consumed by this function and become part of the constructed op tree.
-
- OP * newLOGOP(I32 type, I32 flags, OP *first,
- OP *other)
-
-=for hackers
-Found in file op.c
-
-=item newLOOPEX
-X<newLOOPEX>
-
-Constructs, checks, and returns a loop-exiting op (such as C<goto>
-or C<last>). I<type> is the opcode. I<label> supplies the parameter
-determining the target of the op; it is consumed by this function and
-become part of the constructed op tree.
-
- OP * newLOOPEX(I32 type, OP *label)
-
-=for hackers
-Found in file op.c
-
-=item newLOOPOP
-X<newLOOPOP>
-
-Constructs, checks, and returns an op tree expressing a loop. This is
-only a loop in the control flow through the op tree; it does not have
-the heavyweight loop structure that allows exiting the loop by C<last>
-and suchlike. I<flags> gives the eight bits of C<op_flags> for the
-top-level op, except that some bits will be set automatically as required.
-I<expr> supplies the expression controlling loop iteration, and I<block>
-supplies the body of the loop; they are consumed by this function and
-become part of the constructed op tree. I<debuggable> is currently
-unused and should always be 1.
-
- OP * newLOOPOP(I32 flags, I32 debuggable, OP *expr,
- OP *block)
-
-=for hackers
-Found in file op.c
-
-=item newNULLLIST
-X<newNULLLIST>
-
-Constructs, checks, and returns a new C<stub> op, which represents an
-empty list expression.
-
- OP * newNULLLIST()
-
-=for hackers
-Found in file op.c
-
-=item newOP
-X<newOP>
-
-Constructs, checks, and returns an op of any base type (any type that
-has no extra fields). I<type> is the opcode. I<flags> gives the
-eight bits of C<op_flags>, and, shifted up eight bits, the eight bits
-of C<op_private>.
-
- OP * newOP(I32 type, I32 flags)
-
-=for hackers
-Found in file op.c
-
-=item newPADOP
-X<newPADOP>
-
-Constructs, checks, and returns an op of any type that involves a
-reference to a pad element. I<type> is the opcode. I<flags> gives the
-eight bits of C<op_flags>. A pad slot is automatically allocated, and
-is populated with I<sv>; this function takes ownership of one reference
-to it.
-
-This function only exists if Perl has been compiled to use ithreads.
-
- OP * newPADOP(I32 type, I32 flags, SV *sv)
-
-=for hackers
-Found in file op.c
-
-=item newPMOP
-X<newPMOP>
-
-Constructs, checks, and returns an op of any pattern matching type.
-I<type> is the opcode. I<flags> gives the eight bits of C<op_flags>
-and, shifted up eight bits, the eight bits of C<op_private>.
-
- OP * newPMOP(I32 type, I32 flags)
-
-=for hackers
-Found in file op.c
-
-=item newPVOP
-X<newPVOP>
-
-Constructs, checks, and returns an op of any type that involves an
-embedded C-level pointer (PV). I<type> is the opcode. I<flags> gives
-the eight bits of C<op_flags>. I<pv> supplies the C-level pointer, which
-must have been allocated using L</PerlMemShared_malloc>; the memory will
-be freed when the op is destroyed.
-
- OP * newPVOP(I32 type, I32 flags, char *pv)
-
-=for hackers
-Found in file op.c
-
-=item newRANGE
-X<newRANGE>
-
-Constructs and returns a C<range> op, with subordinate C<flip> and
-C<flop> ops. I<flags> gives the eight bits of C<op_flags> for the
-C<flip> op and, shifted up eight bits, the eight bits of C<op_private>
-for both the C<flip> and C<range> ops, except that the bit with value
-1 is automatically set. I<left> and I<right> supply the expressions
-controlling the endpoints of the range; they are consumed by this function
-and become part of the constructed op tree.
-
- OP * newRANGE(I32 flags, OP *left, OP *right)
-
-=for hackers
-Found in file op.c
-
-=item newSLICEOP
-X<newSLICEOP>
-
-Constructs, checks, and returns an C<lslice> (list slice) op. I<flags>
-gives the eight bits of C<op_flags>, except that C<OPf_KIDS> will
-be set automatically, and, shifted up eight bits, the eight bits of
-C<op_private>, except that the bit with value 1 or 2 is automatically
-set as required. I<listval> and I<subscript> supply the parameters of
-the slice; they are consumed by this function and become part of the
-constructed op tree.
-
- OP * newSLICEOP(I32 flags, OP *subscript,
- OP *listval)
-
-=for hackers
-Found in file op.c
-
-=item newSTATEOP
-X<newSTATEOP>
-
-Constructs a state op (COP). The state op is normally a C<nextstate> op,
-but will be a C<dbstate> op if debugging is enabled for currently-compiled
-code. The state op is populated from L</PL_curcop> (or L</PL_compiling>).
-If I<label> is non-null, it supplies the name of a label to attach to
-the state op; this function takes ownership of the memory pointed at by
-I<label>, and will free it. I<flags> gives the eight bits of C<op_flags>
-for the state op.
-
-If I<o> is null, the state op is returned. Otherwise the state op is
-combined with I<o> into a C<lineseq> list op, which is returned. I<o>
-is consumed by this function and becomes part of the returned op tree.
-
- OP * newSTATEOP(I32 flags, char *label, OP *o)
-
-=for hackers
-Found in file op.c
-
-=item newSVOP
-X<newSVOP>
-
-Constructs, checks, and returns an op of any type that involves an
-embedded SV. I<type> is the opcode. I<flags> gives the eight bits
-of C<op_flags>. I<sv> gives the SV to embed in the op; this function
-takes ownership of one reference to it.
-
- OP * newSVOP(I32 type, I32 flags, SV *sv)
-
-=for hackers
-Found in file op.c
-
-=item newUNOP
-X<newUNOP>
-
-Constructs, checks, and returns an op of any unary type. I<type> is
-the opcode. I<flags> gives the eight bits of C<op_flags>, except that
-C<OPf_KIDS> will be set automatically if required, and, shifted up eight
-bits, the eight bits of C<op_private>, except that the bit with value 1
-is automatically set. I<first> supplies an optional op to be the direct
-child of the unary op; it is consumed by this function and become part
-of the constructed op tree.
-
- OP * newUNOP(I32 type, I32 flags, OP *first)
-
-=for hackers
-Found in file op.c
-
-=item newWHENOP
-X<newWHENOP>
-
-Constructs, checks, and returns an op tree expressing a C<when> block.
-I<cond> supplies the test expression, and I<block> supplies the block
-that will be executed if the test evaluates to true; they are consumed
-by this function and become part of the constructed op tree. I<cond>
-will be interpreted DWIMically, often as a comparison against C<$_>,
-and may be null to generate a C<default> block.
-
- OP * newWHENOP(OP *cond, OP *block)
-
-=for hackers
-Found in file op.c
-
-=item newWHILEOP
-X<newWHILEOP>
-
-Constructs, checks, and returns an op tree expressing a C<while> loop.
-This is a heavyweight loop, with structure that allows exiting the loop
-by C<last> and suchlike.
-
-I<loop> is an optional preconstructed C<enterloop> op to use in the
-loop; if it is null then a suitable op will be constructed automatically.
-I<expr> supplies the loop's controlling expression. I<block> supplies the
-main body of the loop, and I<cont> optionally supplies a C<continue> block
-that operates as a second half of the body. All of these optree inputs
-are consumed by this function and become part of the constructed op tree.
-
-I<flags> gives the eight bits of C<op_flags> for the C<leaveloop>
-op and, shifted up eight bits, the eight bits of C<op_private> for
-the C<leaveloop> op, except that (in both cases) some bits will be set
-automatically. I<debuggable> is currently unused and should always be 1.
-I<has_my> can be supplied as true to force the
-loop body to be enclosed in its own scope.
-
- OP * newWHILEOP(I32 flags, I32 debuggable,
- LOOP *loop, OP *expr, OP *block,
- OP *cont, I32 has_my)
-
-=for hackers
-Found in file op.c
-
-
-=back
-
-=head1 Optree Manipulation Functions
-
-=over 8
-
-=item ck_entersub_args_list
-X<ck_entersub_args_list>
-
-Performs the default fixup of the arguments part of an C<entersub>
-op tree. This consists of applying list context to each of the
-argument ops. This is the standard treatment used on a call marked
-with C<&>, or a method call, or a call through a subroutine reference,
-or any other call where the callee can't be identified at compile time,
-or a call where the callee has no prototype.
-
- OP * ck_entersub_args_list(OP *entersubop)
-
-=for hackers
-Found in file op.c
-
-=item ck_entersub_args_proto
-X<ck_entersub_args_proto>
-
-Performs the fixup of the arguments part of an C<entersub> op tree
-based on a subroutine prototype. This makes various modifications to
-the argument ops, from applying context up to inserting C<refgen> ops,
-and checking the number and syntactic types of arguments, as directed by
-the prototype. This is the standard treatment used on a subroutine call,
-not marked with C<&>, where the callee can be identified at compile time
-and has a prototype.
-
-I<protosv> supplies the subroutine prototype to be applied to the call.
-It may be a normal defined scalar, of which the string value will be used.
-Alternatively, for convenience, it may be a subroutine object (a C<CV*>
-that has been cast to C<SV*>) which has a prototype. The prototype
-supplied, in whichever form, does not need to match the actual callee
-referenced by the op tree.
-
-If the argument ops disagree with the prototype, for example by having
-an unacceptable number of arguments, a valid op tree is returned anyway.
-The error is reflected in the parser state, normally resulting in a single
-exception at the top level of parsing which covers all the compilation
-errors that occurred. In the error message, the callee is referred to
-by the name defined by the I<namegv> parameter.
-
- OP * ck_entersub_args_proto(OP *entersubop,
- GV *namegv, SV *protosv)
-
-=for hackers
-Found in file op.c
-
-=item ck_entersub_args_proto_or_list
-X<ck_entersub_args_proto_or_list>
-
-Performs the fixup of the arguments part of an C<entersub> op tree either
-based on a subroutine prototype or using default list-context processing.
-This is the standard treatment used on a subroutine call, not marked
-with C<&>, where the callee can be identified at compile time.
-
-I<protosv> supplies the subroutine prototype to be applied to the call,
-or indicates that there is no prototype. It may be a normal scalar,
-in which case if it is defined then the string value will be used
-as a prototype, and if it is undefined then there is no prototype.
-Alternatively, for convenience, it may be a subroutine object (a C<CV*>
-that has been cast to C<SV*>), of which the prototype will be used if it
-has one. The prototype (or lack thereof) supplied, in whichever form,
-does not need to match the actual callee referenced by the op tree.
-
-If the argument ops disagree with the prototype, for example by having
-an unacceptable number of arguments, a valid op tree is returned anyway.
-The error is reflected in the parser state, normally resulting in a single
-exception at the top level of parsing which covers all the compilation
-errors that occurred. In the error message, the callee is referred to
-by the name defined by the I<namegv> parameter.
-
- OP * ck_entersub_args_proto_or_list(OP *entersubop,
- GV *namegv,
- SV *protosv)
-
-=for hackers
-Found in file op.c
-
-=item cv_const_sv
-X<cv_const_sv>
-
-If C<cv> is a constant sub eligible for inlining. returns the constant
-value returned by the sub. Otherwise, returns NULL.
-
-Constant subs can be created with C<newCONSTSUB> or as described in
-L<perlsub/"Constant Functions">.
-
- SV* cv_const_sv(const CV *const cv)
-
-=for hackers
-Found in file op.c
-
-=item cv_get_call_checker
-X<cv_get_call_checker>
-
-Retrieves the function that will be used to fix up a call to I<cv>.
-Specifically, the function is applied to an C<entersub> op tree for a
-subroutine call, not marked with C<&>, where the callee can be identified
-at compile time as I<cv>.
-
-The C-level function pointer is returned in I<*ckfun_p>, and an SV
-argument for it is returned in I<*ckobj_p>. The function is intended
-to be called in this manner:
-
- entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
-
-In this call, I<entersubop> is a pointer to the C<entersub> op,
-which may be replaced by the check function, and I<namegv> is a GV
-supplying the name that should be used by the check function to refer
-to the callee of the C<entersub> op if it needs to emit any diagnostics.
-It is permitted to apply the check function in non-standard situations,
-such as to a call to a different subroutine or to a method call.
-
-By default, the function is
-L<Perl_ck_entersub_args_proto_or_list|/ck_entersub_args_proto_or_list>,
-and the SV parameter is I<cv> itself. This implements standard
-prototype processing. It can be changed, for a particular subroutine,
-by L</cv_set_call_checker>.
-
- void cv_get_call_checker(CV *cv,
- Perl_call_checker *ckfun_p,
- SV **ckobj_p)
-
-=for hackers
-Found in file op.c
-
-=item cv_set_call_checker
-X<cv_set_call_checker>
-
-Sets the function that will be used to fix up a call to I<cv>.
-Specifically, the function is applied to an C<entersub> op tree for a
-subroutine call, not marked with C<&>, where the callee can be identified
-at compile time as I<cv>.
-
-The C-level function pointer is supplied in I<ckfun>, and an SV argument
-for it is supplied in I<ckobj>. The function is intended to be called
-in this manner:
-
- entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
-
-In this call, I<entersubop> is a pointer to the C<entersub> op,
-which may be replaced by the check function, and I<namegv> is a GV
-supplying the name that should be used by the check function to refer
-to the callee of the C<entersub> op if it needs to emit any diagnostics.
-It is permitted to apply the check function in non-standard situations,
-such as to a call to a different subroutine or to a method call.
-
-The current setting for a particular CV can be retrieved by
-L</cv_get_call_checker>.
-
- void cv_set_call_checker(CV *cv,
- Perl_call_checker ckfun,
- SV *ckobj)
-
-=for hackers
-Found in file op.c
-
-=item LINKLIST
-X<LINKLIST>
-
-Given the root of an optree, link the tree in execution order using the
-C<op_next> pointers and return the first op executed. If this has
-already been done, it will not be redone, and C<< o->op_next >> will be
-returned. If C<< o->op_next >> is not already set, I<o> should be at
-least an C<UNOP>.
-
- OP* LINKLIST(OP *o)
-
-=for hackers
-Found in file op.h
-
-=item newCONSTSUB
-X<newCONSTSUB>
-
-See L</newCONSTSUB_flags>.
-
- CV* newCONSTSUB(HV* stash, const char* name, SV* sv)
-
-=for hackers
-Found in file op.c
-
-=item newCONSTSUB_flags
-X<newCONSTSUB_flags>
-
-Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
-eligible for inlining at compile-time.
-
-Currently, the only useful value for C<flags> is SVf_UTF8.
-
-Passing NULL for SV creates a constant sub equivalent to C<sub BAR () {}>,
-which won't be called if used as a destructor, but will suppress the overhead
-of a call to C<AUTOLOAD>. (This form, however, isn't eligible for inlining at
-compile time.)
-
- CV* newCONSTSUB_flags(HV* stash, const char* name,
- STRLEN len, U32 flags, SV* sv)
-
-=for hackers
-Found in file op.c
-
-=item newXS
-X<newXS>
-
-Used by C<xsubpp> to hook up XSUBs as Perl subs. I<filename> needs to be
-static storage, as it is used directly as CvFILE(), without a copy being made.
-
-=for hackers
-Found in file op.c
-
-=item op_append_elem
-X<op_append_elem>
-
-Append an item to the list of ops contained directly within a list-type
-op, returning the lengthened list. I<first> is the list-type op,
-and I<last> is the op to append to the list. I<optype> specifies the
-intended opcode for the list. If I<first> is not already a list of the
-right type, it will be upgraded into one. If either I<first> or I<last>
-is null, the other is returned unchanged.
-
- OP * op_append_elem(I32 optype, OP *first, OP *last)
-
-=for hackers
-Found in file op.c
-
-=item op_append_list
-X<op_append_list>
-
-Concatenate the lists of ops contained directly within two list-type ops,
-returning the combined list. I<first> and I<last> are the list-type ops
-to concatenate. I<optype> specifies the intended opcode for the list.
-If either I<first> or I<last> is not already a list of the right type,
-it will be upgraded into one. If either I<first> or I<last> is null,
-the other is returned unchanged.
-
- OP * op_append_list(I32 optype, OP *first, OP *last)
-
-=for hackers
-Found in file op.c
-
-=item OP_CLASS
-X<OP_CLASS>
-
-Return the class of the provided OP: that is, which of the *OP
-structures it uses. For core ops this currently gets the information out
-of PL_opargs, which does not always accurately reflect the type used.
-For custom ops the type is returned from the registration, and it is up
-to the registree to ensure it is accurate. The value returned will be
-one of the OA_* constants from op.h.
-
- U32 OP_CLASS(OP *o)
-
-=for hackers
-Found in file op.h
-
-=item OP_DESC
-X<OP_DESC>
-
-Return a short description of the provided OP.
-
- const char * OP_DESC(OP *o)
-
-=for hackers
-Found in file op.h
-
-=item op_linklist
-X<op_linklist>
-
-This function is the implementation of the L</LINKLIST> macro. It should
-not be called directly.
-
- OP* op_linklist(OP *o)
-
-=for hackers
-Found in file op.c
-
-=item op_lvalue
-X<op_lvalue>
-
-Propagate lvalue ("modifiable") context to an op and its children.
-I<type> represents the context type, roughly based on the type of op that
-would do the modifying, although C<local()> is represented by OP_NULL,
-because it has no op type of its own (it is signalled by a flag on
-the lvalue op).
-
-This function detects things that can't be modified, such as C<$x+1>, and
-generates errors for them. For example, C<$x+1 = 2> would cause it to be
-called with an op of type OP_ADD and a C<type> argument of OP_SASSIGN.
-
-It also flags things that need to behave specially in an lvalue context,
-such as C<$$x = 5> which might have to vivify a reference in C<$x>.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- OP * op_lvalue(OP *o, I32 type)
-
-=for hackers
-Found in file op.c
-
-=item OP_NAME
-X<OP_NAME>
-
-Return the name of the provided OP. For core ops this looks up the name
-from the op_type; for custom ops from the op_ppaddr.
-
- const char * OP_NAME(OP *o)
-
-=for hackers
-Found in file op.h
-
-=item op_prepend_elem
-X<op_prepend_elem>
-
-Prepend an item to the list of ops contained directly within a list-type
-op, returning the lengthened list. I<first> is the op to prepend to the
-list, and I<last> is the list-type op. I<optype> specifies the intended
-opcode for the list. If I<last> is not already a list of the right type,
-it will be upgraded into one. If either I<first> or I<last> is null,
-the other is returned unchanged.
-
- OP * op_prepend_elem(I32 optype, OP *first, OP *last)
-
-=for hackers
-Found in file op.c
-
-=item op_scope
-X<op_scope>
-
-Wraps up an op tree with some additional ops so that at runtime a dynamic
-scope will be created. The original ops run in the new dynamic scope,
-and then, provided that they exit normally, the scope will be unwound.
-The additional ops used to create and unwind the dynamic scope will
-normally be an C<enter>/C<leave> pair, but a C<scope> op may be used
-instead if the ops are simple enough to not need the full dynamic scope
-structure.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- OP * op_scope(OP *o)
-
-=for hackers
-Found in file op.c
-
-=item rv2cv_op_cv
-X<rv2cv_op_cv>
-
-Examines an op, which is expected to identify a subroutine at runtime,
-and attempts to determine at compile time which subroutine it identifies.
-This is normally used during Perl compilation to determine whether
-a prototype can be applied to a function call. I<cvop> is the op
-being considered, normally an C<rv2cv> op. A pointer to the identified
-subroutine is returned, if it could be determined statically, and a null
-pointer is returned if it was not possible to determine statically.
-
-Currently, the subroutine can be identified statically if the RV that the
-C<rv2cv> is to operate on is provided by a suitable C<gv> or C<const> op.
-A C<gv> op is suitable if the GV's CV slot is populated. A C<const> op is
-suitable if the constant value must be an RV pointing to a CV. Details of
-this process may change in future versions of Perl. If the C<rv2cv> op
-has the C<OPpENTERSUB_AMPER> flag set then no attempt is made to identify
-the subroutine statically: this flag is used to suppress compile-time
-magic on a subroutine call, forcing it to use default runtime behaviour.
-
-If I<flags> has the bit C<RV2CVOPCV_MARK_EARLY> set, then the handling
-of a GV reference is modified. If a GV was examined and its CV slot was
-found to be empty, then the C<gv> op has the C<OPpEARLY_CV> flag set.
-If the op is not optimised away, and the CV slot is later populated with
-a subroutine having a prototype, that flag eventually triggers the warning
-"called too early to check prototype".
-
-If I<flags> has the bit C<RV2CVOPCV_RETURN_NAME_GV> set, then instead
-of returning a pointer to the subroutine it returns a pointer to the
-GV giving the most appropriate name for the subroutine in this context.
-Normally this is just the C<CvGV> of the subroutine, but for an anonymous
-(C<CvANON>) subroutine that is referenced through a GV it will be the
-referencing GV. The resulting C<GV*> is cast to C<CV*> to be returned.
-A null pointer is returned as usual if there is no statically-determinable
-subroutine.
-
- CV * rv2cv_op_cv(OP *cvop, U32 flags)
-
-=for hackers
-Found in file op.c
-
-
-=back
-
-=head1 Pad Data Structures
-
-=over 8
-
-=item CvPADLIST
-X<CvPADLIST>
-
-CV's can have CvPADLIST(cv) set to point to an AV. This is the CV's
-scratchpad, which stores lexical variables and opcode temporary and
-per-thread values.
-
-For these purposes "forms" are a kind-of CV, eval""s are too (except they're
-not callable at will and are always thrown away after the eval"" is done
-executing). Require'd files are simply evals without any outer lexical
-scope.
-
-XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad,
-but that is really the callers pad (a slot of which is allocated by
-every entersub).
-
-The CvPADLIST AV has the REFCNT of its component items managed "manually"
-(mostly in pad.c) rather than by normal av.c rules. So we turn off AvREAL
-just before freeing it, to let av.c know not to touch the entries.
-The items in the AV are not SVs as for a normal AV, but other AVs:
-
-0'th Entry of the CvPADLIST is an AV which represents the "names" or rather
-the "static type information" for lexicals.
-
-The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that
-depth of recursion into the CV.
-The 0'th slot of a frame AV is an AV which is @_.
-other entries are storage for variables and op targets.
-
-Iterating over the names AV iterates over all possible pad
-items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having
-&PL_sv_undef "names" (see pad_alloc()).
-
-Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names.
-The rest are op targets/GVs/constants which are statically allocated
-or resolved at compile time. These don't have names by which they
-can be looked up from Perl code at run time through eval"" like
-my/our variables can be. Since they can't be looked up by "name"
-but only by their index allocated at compile time (which is usually
-in PL_op->op_targ), wasting a name SV for them doesn't make sense.
-
-The SVs in the names AV have their PV being the name of the variable.
-xlow+1..xhigh inclusive in the NV union is a range of cop_seq numbers for
-which the name is valid (accessed through the macros COP_SEQ_RANGE_LOW and
-_HIGH). During compilation, these fields may hold the special value
-PERL_PADSEQ_INTRO to indicate various stages:
-
- COP_SEQ_RANGE_LOW _HIGH
- ----------------- -----
- PERL_PADSEQ_INTRO 0 variable not yet introduced: { my ($x
- valid-seq# PERL_PADSEQ_INTRO variable in scope: { my ($x)
- valid-seq# valid-seq# compilation of scope complete: { my ($x) }
-
-For typed lexicals name SV is SVt_PVMG and SvSTASH
-points at the type. For C<our> lexicals, the type is also SVt_PVMG, with the
-SvOURSTASH slot pointing at the stash of the associated global (so that
-duplicate C<our> declarations in the same package can be detected). SvUVX is
-sometimes hijacked to store the generation number during compilation.
-
-If SvFAKE is set on the name SV, then that slot in the frame AV is
-a REFCNT'ed reference to a lexical from "outside". In this case,
-the name SV does not use xlow and xhigh to store a cop_seq range, since it is
-in scope throughout. Instead xhigh stores some flags containing info about
-the real lexical (is it declared in an anon, and is it capable of being
-instantiated multiple times?), and for fake ANONs, xlow contains the index
-within the parent's pad where the lexical's value is stored, to make
-cloning quicker.
-
-If the 'name' is '&' the corresponding entry in frame AV
-is a CV representing a possible closure.
-(SvFAKE and name of '&' is not a meaningful combination currently but could
-become so if C<my sub foo {}> is implemented.)
-
-Note that formats are treated as anon subs, and are cloned each time
-write is called (if necessary).
-
-The flag SVs_PADSTALE is cleared on lexicals each time the my() is executed,
-and set on scope exit. This allows the 'Variable $x is not available' warning
-to be generated in evals, such as
-
- { my $x = 1; sub f { eval '$x'} } f();
-
-For state vars, SVs_PADSTALE is overloaded to mean 'not yet initialised'
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- PADLIST * CvPADLIST(CV *cv)
-
-=for hackers
-Found in file pad.c
-
-=item pad_add_name_pvs
-X<pad_add_name_pvs>
-
-Exactly like L</pad_add_name_pvn>, but takes a literal string instead
-of a string/length pair.
-
- PADOFFSET pad_add_name_pvs(const char *name, U32 flags,
- HV *typestash, HV *ourstash)
-
-=for hackers
-Found in file pad.h
-
-=item pad_findmy_pvs
-X<pad_findmy_pvs>
-
-Exactly like L</pad_findmy_pvn>, but takes a literal string instead
-of a string/length pair.
-
- PADOFFSET pad_findmy_pvs(const char *name, U32 flags)
-
-=for hackers
-Found in file pad.h
-
-=item pad_new
-X<pad_new>
-
-Create a new padlist, updating the global variables for the
-currently-compiling padlist to point to the new padlist. The following
-flags can be OR'ed together:
-
- padnew_CLONE this pad is for a cloned CV
- padnew_SAVE save old globals on the save stack
- padnew_SAVESUB also save extra stuff for start of sub
-
- PADLIST * pad_new(int flags)
-
-=for hackers
-Found in file pad.c
-
-=item PL_comppad
-X<PL_comppad>
-
-During compilation, this points to the array containing the values
-part of the pad for the currently-compiling code. (At runtime a CV may
-have many such value arrays; at compile time just one is constructed.)
-At runtime, this points to the array containing the currently-relevant
-values for the pad for the currently-executing code.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
-=for hackers
-Found in file pad.c
-
-=item PL_comppad_name
-X<PL_comppad_name>
-
-During compilation, this points to the array containing the names part
-of the pad for the currently-compiling code.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
-=for hackers
-Found in file pad.c
-
-=item PL_curpad
-X<PL_curpad>
-
-Points directly to the body of the L</PL_comppad> array.
-(I.e., this is C<AvARRAY(PL_comppad)>.)
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
-=for hackers
-Found in file pad.c
-
-
-=back
-
-=head1 Per-Interpreter Variables
-
-=over 8
-
-=item PL_modglobal
-X<PL_modglobal>
-
-C<PL_modglobal> is a general purpose, interpreter global HV for use by
-extensions that need to keep information on a per-interpreter basis.
-In a pinch, it can also be used as a symbol table for extensions
-to share data among each other. It is a good idea to use keys
-prefixed by the package name of the extension that owns the data.
-
- HV* PL_modglobal
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_na
-X<PL_na>
-
-A convenience variable which is typically used with C<SvPV> when one
-doesn't care about the length of the string. It is usually more efficient
-to either declare a local variable and use that instead or to use the
-C<SvPV_nolen> macro.
-
- STRLEN PL_na
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_opfreehook
-X<PL_opfreehook>
-
-When non-C<NULL>, the function pointed by this variable will be called each time an OP is freed with the corresponding OP as the argument.
-This allows extensions to free any extra attribute they have locally attached to an OP.
-It is also assured to first fire for the parent OP and then for its kids.
-
-When you replace this variable, it is considered a good practice to store the possibly previously installed hook and that you recall it inside your own.
-
- Perl_ophook_t PL_opfreehook
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_peepp
-X<PL_peepp>
-
-Pointer to the per-subroutine peephole optimiser. This is a function
-that gets called at the end of compilation of a Perl subroutine (or
-equivalently independent piece of Perl code) to perform fixups of
-some ops and to perform small-scale optimisations. The function is
-called once for each subroutine that is compiled, and is passed, as sole
-parameter, a pointer to the op that is the entry point to the subroutine.
-It modifies the op tree in place.
-
-The peephole optimiser should never be completely replaced. Rather,
-add code to it by wrapping the existing optimiser. The basic way to do
-this can be seen in L<perlguts/Compile pass 3: peephole optimization>.
-If the new code wishes to operate on ops throughout the subroutine's
-structure, rather than just at the top level, it is likely to be more
-convenient to wrap the L</PL_rpeepp> hook.
-
- peep_t PL_peepp
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_rpeepp
-X<PL_rpeepp>
-
-Pointer to the recursive peephole optimiser. This is a function
-that gets called at the end of compilation of a Perl subroutine (or
-equivalently independent piece of Perl code) to perform fixups of some
-ops and to perform small-scale optimisations. The function is called
-once for each chain of ops linked through their C<op_next> fields;
-it is recursively called to handle each side chain. It is passed, as
-sole parameter, a pointer to the op that is at the head of the chain.
-It modifies the op tree in place.
-
-The peephole optimiser should never be completely replaced. Rather,
-add code to it by wrapping the existing optimiser. The basic way to do
-this can be seen in L<perlguts/Compile pass 3: peephole optimization>.
-If the new code wishes to operate only on ops at a subroutine's top level,
-rather than throughout the structure, it is likely to be more convenient
-to wrap the L</PL_peepp> hook.
-
- peep_t PL_rpeepp
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_sv_no
-X<PL_sv_no>
-
-This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
-C<&PL_sv_no>.
-
- SV PL_sv_no
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_sv_undef
-X<PL_sv_undef>
-
-This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
-
- SV PL_sv_undef
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_sv_yes
-X<PL_sv_yes>
-
-This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
-C<&PL_sv_yes>.
-
- SV PL_sv_yes
-
-=for hackers
-Found in file intrpvar.h
-
-
-=back
-
-=head1 REGEXP Functions
-
-=over 8
-
-=item SvRX
-X<SvRX>
-
-Convenience macro to get the REGEXP from a SV. This is approximately
-equivalent to the following snippet:
-
- if (SvMAGICAL(sv))
- mg_get(sv);
- if (SvROK(sv))
- sv = MUTABLE_SV(SvRV(sv));
- if (SvTYPE(sv) == SVt_REGEXP)
- return (REGEXP*) sv;
-
-NULL will be returned if a REGEXP* is not found.
-
- REGEXP * SvRX(SV *sv)
-
-=for hackers
-Found in file regexp.h
-
-=item SvRXOK
-X<SvRXOK>
-
-Returns a boolean indicating whether the SV (or the one it references)
-is a REGEXP.
-
-If you want to do something with the REGEXP* later use SvRX instead
-and check for NULL.
-
- bool SvRXOK(SV* sv)
-
-=for hackers
-Found in file regexp.h
-
-
-=back
-
-=head1 Simple Exception Handling Macros
-
-=over 8
-
-=item dXCPT
-X<dXCPT>
-
-Set up necessary local variables for exception handling.
-See L<perlguts/"Exception Handling">.
-
- dXCPT;
-
-=for hackers
-Found in file XSUB.h
-
-=item XCPT_CATCH
-X<XCPT_CATCH>
-
-Introduces a catch block. See L<perlguts/"Exception Handling">.
-
-=for hackers
-Found in file XSUB.h
-
-=item XCPT_RETHROW
-X<XCPT_RETHROW>
-
-Rethrows a previously caught exception. See L<perlguts/"Exception Handling">.
-
- XCPT_RETHROW;
-
-=for hackers
-Found in file XSUB.h
-
-=item XCPT_TRY_END
-X<XCPT_TRY_END>
-
-Ends a try block. See L<perlguts/"Exception Handling">.
-
-=for hackers
-Found in file XSUB.h
-
-=item XCPT_TRY_START
-X<XCPT_TRY_START>
-
-Starts a try block. See L<perlguts/"Exception Handling">.
-
-=for hackers
-Found in file XSUB.h
-
-
-=back
-
-=head1 Stack Manipulation Macros
-
-=over 8
-
-=item dMARK
-X<dMARK>
-
-Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
-C<dORIGMARK>.
-
- dMARK;
-
-=for hackers
-Found in file pp.h
-
-=item dORIGMARK
-X<dORIGMARK>
-
-Saves the original stack mark for the XSUB. See C<ORIGMARK>.
-
- dORIGMARK;
-
-=for hackers
-Found in file pp.h
-
-=item dSP
-X<dSP>
-
-Declares a local copy of perl's stack pointer for the XSUB, available via
-the C<SP> macro. See C<SP>.
-
- dSP;
-
-=for hackers
-Found in file pp.h
-
-=item EXTEND
-X<EXTEND>
-
-Used to extend the argument stack for an XSUB's return values. Once
-used, guarantees that there is room for at least C<nitems> to be pushed
-onto the stack.
-
- void EXTEND(SP, int nitems)
-
-=for hackers
-Found in file pp.h
-
-=item MARK
-X<MARK>
-
-Stack marker variable for the XSUB. See C<dMARK>.
-
-=for hackers
-Found in file pp.h
-
-=item mPUSHi
-X<mPUSHi>
-
-Push an integer onto the stack. The stack must have room for this element.
-Does not use C<TARG>. See also C<PUSHi>, C<mXPUSHi> and C<XPUSHi>.
-
- void mPUSHi(IV iv)
-
-=for hackers
-Found in file pp.h
-
-=item mPUSHn
-X<mPUSHn>
-
-Push a double onto the stack. The stack must have room for this element.
-Does not use C<TARG>. See also C<PUSHn>, C<mXPUSHn> and C<XPUSHn>.
-
- void mPUSHn(NV nv)
-
-=for hackers
-Found in file pp.h
-
-=item mPUSHp
-X<mPUSHp>
-
-Push a string onto the stack. The stack must have room for this element.
-The C<len> indicates the length of the string. Does not use C<TARG>.
-See also C<PUSHp>, C<mXPUSHp> and C<XPUSHp>.
-
- void mPUSHp(char* str, STRLEN len)
-
-=for hackers
-Found in file pp.h
-
-=item mPUSHs
-X<mPUSHs>
-
-Push an SV onto the stack and mortalizes the SV. The stack must have room
-for this element. Does not use C<TARG>. See also C<PUSHs> and C<mXPUSHs>.
-
- void mPUSHs(SV* sv)
-
-=for hackers
-Found in file pp.h
-
-=item mPUSHu
-X<mPUSHu>
-
-Push an unsigned integer onto the stack. The stack must have room for this
-element. Does not use C<TARG>. See also C<PUSHu>, C<mXPUSHu> and C<XPUSHu>.
-
- void mPUSHu(UV uv)
-
-=for hackers
-Found in file pp.h
-
-=item mXPUSHi
-X<mXPUSHi>
-
-Push an integer onto the stack, extending the stack if necessary.
-Does not use C<TARG>. See also C<XPUSHi>, C<mPUSHi> and C<PUSHi>.
-
- void mXPUSHi(IV iv)
-
-=for hackers
-Found in file pp.h
-
-=item mXPUSHn
-X<mXPUSHn>
-
-Push a double onto the stack, extending the stack if necessary.
-Does not use C<TARG>. See also C<XPUSHn>, C<mPUSHn> and C<PUSHn>.
-
- void mXPUSHn(NV nv)
-
-=for hackers
-Found in file pp.h
-
-=item mXPUSHp
-X<mXPUSHp>
-
-Push a string onto the stack, extending the stack if necessary. The C<len>
-indicates the length of the string. Does not use C<TARG>. See also C<XPUSHp>,
-C<mPUSHp> and C<PUSHp>.
-
- void mXPUSHp(char* str, STRLEN len)
-
-=for hackers
-Found in file pp.h
-
-=item mXPUSHs
-X<mXPUSHs>
-
-Push an SV onto the stack, extending the stack if necessary and mortalizes
-the SV. Does not use C<TARG>. See also C<XPUSHs> and C<mPUSHs>.
-
- void mXPUSHs(SV* sv)
-
-=for hackers
-Found in file pp.h
-
-=item mXPUSHu
-X<mXPUSHu>
-
-Push an unsigned integer onto the stack, extending the stack if necessary.
-Does not use C<TARG>. See also C<XPUSHu>, C<mPUSHu> and C<PUSHu>.
-
- void mXPUSHu(UV uv)
-
-=for hackers
-Found in file pp.h
-
-=item ORIGMARK
-X<ORIGMARK>
-
-The original stack mark for the XSUB. See C<dORIGMARK>.
-
-=for hackers
-Found in file pp.h
-
-=item POPi
-X<POPi>
-
-Pops an integer off the stack.
-
- IV POPi
-
-=for hackers
-Found in file pp.h
-
-=item POPl
-X<POPl>
-
-Pops a long off the stack.
-
- long POPl
-
-=for hackers
-Found in file pp.h
-
-=item POPn
-X<POPn>
-
-Pops a double off the stack.
-
- NV POPn
-
-=for hackers
-Found in file pp.h
-
-=item POPp
-X<POPp>
-
-Pops a string off the stack. Deprecated. New code should use POPpx.
-
- char* POPp
-
-=for hackers
-Found in file pp.h
-
-=item POPpbytex
-X<POPpbytex>
-
-Pops a string off the stack which must consist of bytes i.e. characters < 256.
-
- char* POPpbytex
-
-=for hackers
-Found in file pp.h
-
-=item POPpx
-X<POPpx>
-
-Pops a string off the stack.
-
- char* POPpx
-
-=for hackers
-Found in file pp.h
-
-=item POPs
-X<POPs>
-
-Pops an SV off the stack.
-
- SV* POPs
-
-=for hackers
-Found in file pp.h
-
-=item PUSHi
-X<PUSHi>
-
-Push an integer onto the stack. The stack must have room for this element.
-Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
-called to declare it. Do not call multiple C<TARG>-oriented macros to
-return lists from XSUB's - see C<mPUSHi> instead. See also C<XPUSHi> and
-C<mXPUSHi>.
-
- void PUSHi(IV iv)
-
-=for hackers
-Found in file pp.h
-
-=item PUSHMARK
-X<PUSHMARK>
-
-Opening bracket for arguments on a callback. See C<PUTBACK> and
-L<perlcall>.
-
- void PUSHMARK(SP)
-
-=for hackers
-Found in file pp.h
-
-=item PUSHmortal
-X<PUSHmortal>
-
-Push a new mortal SV onto the stack. The stack must have room for this
-element. Does not use C<TARG>. See also C<PUSHs>, C<XPUSHmortal> and C<XPUSHs>.
-
- void PUSHmortal()
-
-=for hackers
-Found in file pp.h
-
-=item PUSHn
-X<PUSHn>
-
-Push a double onto the stack. The stack must have room for this element.
-Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
-called to declare it. Do not call multiple C<TARG>-oriented macros to
-return lists from XSUB's - see C<mPUSHn> instead. See also C<XPUSHn> and
-C<mXPUSHn>.
-
- void PUSHn(NV nv)
-
-=for hackers
-Found in file pp.h
-
-=item PUSHp
-X<PUSHp>
-
-Push a string onto the stack. The stack must have room for this element.
-The C<len> indicates the length of the string. Handles 'set' magic. Uses
-C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to declare it. Do not
-call multiple C<TARG>-oriented macros to return lists from XSUB's - see
-C<mPUSHp> instead. See also C<XPUSHp> and C<mXPUSHp>.
-
- void PUSHp(char* str, STRLEN len)
-
-=for hackers
-Found in file pp.h
-
-=item PUSHs
-X<PUSHs>
-
-Push an SV onto the stack. The stack must have room for this element.
-Does not handle 'set' magic. Does not use C<TARG>. See also C<PUSHmortal>,
-C<XPUSHs> and C<XPUSHmortal>.
-
- void PUSHs(SV* sv)
-
-=for hackers
-Found in file pp.h
-
-=item PUSHu
-X<PUSHu>
-
-Push an unsigned integer onto the stack. The stack must have room for this
-element. Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG>
-should be called to declare it. Do not call multiple C<TARG>-oriented
-macros to return lists from XSUB's - see C<mPUSHu> instead. See also
-C<XPUSHu> and C<mXPUSHu>.
-
- void PUSHu(UV uv)
-
-=for hackers
-Found in file pp.h
-
-=item PUTBACK
-X<PUTBACK>
-
-Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
-See C<PUSHMARK> and L<perlcall> for other uses.
-
- PUTBACK;
-
-=for hackers
-Found in file pp.h
-
-=item SP
-X<SP>
-
-Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
-C<SPAGAIN>.
-
-=for hackers
-Found in file pp.h
-
-=item SPAGAIN
-X<SPAGAIN>
-
-Refetch the stack pointer. Used after a callback. See L<perlcall>.
-
- SPAGAIN;
-
-=for hackers
-Found in file pp.h
-
-=item XPUSHi
-X<XPUSHi>
-
-Push an integer onto the stack, extending the stack if necessary. Handles
-'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
-declare it. Do not call multiple C<TARG>-oriented macros to return lists
-from XSUB's - see C<mXPUSHi> instead. See also C<PUSHi> and C<mPUSHi>.
-
- void XPUSHi(IV iv)
-
-=for hackers
-Found in file pp.h
-
-=item XPUSHmortal
-X<XPUSHmortal>
-
-Push a new mortal SV onto the stack, extending the stack if necessary.
-Does not use C<TARG>. See also C<XPUSHs>, C<PUSHmortal> and C<PUSHs>.
-
- void XPUSHmortal()
-
-=for hackers
-Found in file pp.h
-
-=item XPUSHn
-X<XPUSHn>
-
-Push a double onto the stack, extending the stack if necessary. Handles
-'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
-declare it. Do not call multiple C<TARG>-oriented macros to return lists
-from XSUB's - see C<mXPUSHn> instead. See also C<PUSHn> and C<mPUSHn>.
-
- void XPUSHn(NV nv)
-
-=for hackers
-Found in file pp.h
-
-=item XPUSHp
-X<XPUSHp>
-
-Push a string onto the stack, extending the stack if necessary. The C<len>
-indicates the length of the string. Handles 'set' magic. Uses C<TARG>, so
-C<dTARGET> or C<dXSTARG> should be called to declare it. Do not call
-multiple C<TARG>-oriented macros to return lists from XSUB's - see
-C<mXPUSHp> instead. See also C<PUSHp> and C<mPUSHp>.
-
- void XPUSHp(char* str, STRLEN len)
-
-=for hackers
-Found in file pp.h
-
-=item XPUSHs
-X<XPUSHs>
-
-Push an SV onto the stack, extending the stack if necessary. Does not
-handle 'set' magic. Does not use C<TARG>. See also C<XPUSHmortal>,
-C<PUSHs> and C<PUSHmortal>.
-
- void XPUSHs(SV* sv)
-
-=for hackers
-Found in file pp.h
-
-=item XPUSHu
-X<XPUSHu>
-
-Push an unsigned integer onto the stack, extending the stack if necessary.
-Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
-called to declare it. Do not call multiple C<TARG>-oriented macros to
-return lists from XSUB's - see C<mXPUSHu> instead. See also C<PUSHu> and
-C<mPUSHu>.
-
- void XPUSHu(UV uv)
-
-=for hackers
-Found in file pp.h
-
-=item XSRETURN
-X<XSRETURN>
-
-Return from XSUB, indicating number of items on the stack. This is usually
-handled by C<xsubpp>.
-
- void XSRETURN(int nitems)
-
-=for hackers
-Found in file XSUB.h
-
-=item XSRETURN_EMPTY
-X<XSRETURN_EMPTY>
-
-Return an empty list from an XSUB immediately.
-
- XSRETURN_EMPTY;
-
-=for hackers
-Found in file XSUB.h
-
-=item XSRETURN_IV
-X<XSRETURN_IV>
-
-Return an integer from an XSUB immediately. Uses C<XST_mIV>.
-
- void XSRETURN_IV(IV iv)
-
-=for hackers
-Found in file XSUB.h
-
-=item XSRETURN_NO
-X<XSRETURN_NO>
-
-Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
-
- XSRETURN_NO;
-
-=for hackers
-Found in file XSUB.h
-
-=item XSRETURN_NV
-X<XSRETURN_NV>
-
-Return a double from an XSUB immediately. Uses C<XST_mNV>.
-
- void XSRETURN_NV(NV nv)
-
-=for hackers
-Found in file XSUB.h
-
-=item XSRETURN_PV
-X<XSRETURN_PV>
-
-Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
-
- void XSRETURN_PV(char* str)
-
-=for hackers
-Found in file XSUB.h
-
-=item XSRETURN_UNDEF
-X<XSRETURN_UNDEF>
-
-Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
-
- XSRETURN_UNDEF;
-
-=for hackers
-Found in file XSUB.h
-
-=item XSRETURN_UV
-X<XSRETURN_UV>
-
-Return an integer from an XSUB immediately. Uses C<XST_mUV>.
-
- void XSRETURN_UV(IV uv)
-
-=for hackers
-Found in file XSUB.h
-
-=item XSRETURN_YES
-X<XSRETURN_YES>
-
-Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
-
- XSRETURN_YES;
-
-=for hackers
-Found in file XSUB.h
-
-=item XST_mIV
-X<XST_mIV>
-
-Place an integer into the specified position C<pos> on the stack. The
-value is stored in a new mortal SV.
-
- void XST_mIV(int pos, IV iv)
-
-=for hackers
-Found in file XSUB.h
-
-=item XST_mNO
-X<XST_mNO>
-
-Place C<&PL_sv_no> into the specified position C<pos> on the
-stack.
-
- void XST_mNO(int pos)
-
-=for hackers
-Found in file XSUB.h
-
-=item XST_mNV
-X<XST_mNV>
-
-Place a double into the specified position C<pos> on the stack. The value
-is stored in a new mortal SV.
-
- void XST_mNV(int pos, NV nv)
-
-=for hackers
-Found in file XSUB.h
-
-=item XST_mPV
-X<XST_mPV>
-
-Place a copy of a string into the specified position C<pos> on the stack.
-The value is stored in a new mortal SV.
-
- void XST_mPV(int pos, char* str)
-
-=for hackers
-Found in file XSUB.h
-
-=item XST_mUNDEF
-X<XST_mUNDEF>
-
-Place C<&PL_sv_undef> into the specified position C<pos> on the
-stack.
-
- void XST_mUNDEF(int pos)
-
-=for hackers
-Found in file XSUB.h
-
-=item XST_mYES
-X<XST_mYES>
-
-Place C<&PL_sv_yes> into the specified position C<pos> on the
-stack.
-
- void XST_mYES(int pos)
-
-=for hackers
-Found in file XSUB.h
-
-
-=back
-
-=head1 SV Flags
-
-=over 8
-
-=item svtype
-X<svtype>
-
-An enum of flags for Perl types. These are found in the file B<sv.h>
-in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_IV
-X<SVt_IV>
-
-Integer type flag for scalars. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_NV
-X<SVt_NV>
-
-Double type flag for scalars. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_PV
-X<SVt_PV>
-
-Pointer type flag for scalars. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_PVAV
-X<SVt_PVAV>
-
-Type flag for arrays. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_PVCV
-X<SVt_PVCV>
-
-Type flag for code refs. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_PVHV
-X<SVt_PVHV>
-
-Type flag for hashes. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_PVMG
-X<SVt_PVMG>
-
-Type flag for blessed scalars. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-
-=back
-
-=head1 SV Manipulation Functions
-
-=over 8
-
-=item boolSV
-X<boolSV>
-
-Returns a true SV if C<b> is a true value, or a false SV if C<b> is 0.
-
-See also C<PL_sv_yes> and C<PL_sv_no>.
-
- SV * boolSV(bool b)
-
-=for hackers
-Found in file sv.h
-
-=item croak_xs_usage
-X<croak_xs_usage>
-
-A specialised variant of C<croak()> for emitting the usage message for xsubs
-
- croak_xs_usage(cv, "eee_yow");
-
-works out the package name and subroutine name from C<cv>, and then calls
-C<croak()>. Hence if C<cv> is C<&ouch::awk>, it would call C<croak> as:
-
- Perl_croak(aTHX_ "Usage: %"SVf"::%"SVf"(%s)", "ouch" "awk", "eee_yow");
-
- void croak_xs_usage(const CV *const cv,
- const char *const params)
-
-=for hackers
-Found in file universal.c
-
-=item get_sv
-X<get_sv>
-
-Returns the SV of the specified Perl scalar. C<flags> are passed to
-C<gv_fetchpv>. If C<GV_ADD> is set and the
-Perl variable does not exist then it will be created. If C<flags> is zero
-and the variable does not exist then NULL is returned.
-
-NOTE: the perl_ form of this function is deprecated.
-
- SV* get_sv(const char *name, I32 flags)
-
-=for hackers
-Found in file perl.c
-
-=item newRV_inc
-X<newRV_inc>
-
-Creates an RV wrapper for an SV. The reference count for the original SV is
-incremented.
-
- SV* newRV_inc(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item newSVpvn_utf8
-X<newSVpvn_utf8>
-
-Creates a new SV and copies a string into it. If utf8 is true, calls
-C<SvUTF8_on> on the new SV. Implemented as a wrapper around C<newSVpvn_flags>.
-
- SV* newSVpvn_utf8(NULLOK const char* s, STRLEN len,
- U32 utf8)
-
-=for hackers
-Found in file sv.h
-
-=item SvCUR
-X<SvCUR>
-
-Returns the length of the string which is in the SV. See C<SvLEN>.
-
- STRLEN SvCUR(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvCUR_set
-X<SvCUR_set>
-
-Set the current length of the string which is in the SV. See C<SvCUR>
-and C<SvIV_set>.
-
- void SvCUR_set(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvEND
-X<SvEND>
-
-Returns a pointer to the spot just after the last character in
-the string which is in the SV, where there is usually a trailing
-null (even though Perl scalars do not strictly require it).
-See C<SvCUR>. Access the character as *(SvEND(sv)).
-
-Warning: If C<SvCUR> is equal to C<SvLEN>, then C<SvEND> points to
-unallocated memory.
-
- char* SvEND(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvGAMAGIC
-X<SvGAMAGIC>
-
-Returns true if the SV has get magic or
-overloading. If either is true then
-the scalar is active data, and has the potential to return a new value every
-time it is accessed. Hence you must be careful to
-only read it once per user logical operation and work
-with that returned value. If neither is true then
-the scalar's value cannot change unless written to.
-
- U32 SvGAMAGIC(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvGROW
-X<SvGROW>
-
-Expands the character buffer in the SV so that it has room for the
-indicated number of bytes (remember to reserve space for an extra trailing
-NUL character). Calls C<sv_grow> to perform the expansion if necessary.
-Returns a pointer to the character buffer.
-
- char * SvGROW(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOK
-X<SvIOK>
-
-Returns a U32 value indicating whether the SV contains an integer.
-
- U32 SvIOK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOKp
-X<SvIOKp>
-
-Returns a U32 value indicating whether the SV contains an integer. Checks
-the B<private> setting. Use C<SvIOK> instead.
-
- U32 SvIOKp(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOK_notUV
-X<SvIOK_notUV>
-
-Returns a boolean indicating whether the SV contains a signed integer.
-
- bool SvIOK_notUV(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOK_off
-X<SvIOK_off>
-
-Unsets the IV status of an SV.
-
- void SvIOK_off(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOK_on
-X<SvIOK_on>
-
-Tells an SV that it is an integer.
-
- void SvIOK_on(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOK_only
-X<SvIOK_only>
-
-Tells an SV that it is an integer and disables all other OK bits.
-
- void SvIOK_only(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOK_only_UV
-X<SvIOK_only_UV>
-
-Tells and SV that it is an unsigned integer and disables all other OK bits.
-
- void SvIOK_only_UV(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOK_UV
-X<SvIOK_UV>
-
-Returns a boolean indicating whether the SV contains an unsigned integer.
-
- bool SvIOK_UV(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIsCOW
-X<SvIsCOW>
-
-Returns a boolean indicating whether the SV is Copy-On-Write (either shared
-hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
-COW).
-
- bool SvIsCOW(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIsCOW_shared_hash
-X<SvIsCOW_shared_hash>
-
-Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
-scalar.
-
- bool SvIsCOW_shared_hash(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIV
-X<SvIV>
-
-Coerces the given SV to an integer and returns it. See C<SvIVx> for a
-version which guarantees to evaluate sv only once.
-
- IV SvIV(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIVX
-X<SvIVX>
-
-Returns the raw value in the SV's IV slot, without checks or conversions.
-Only use when you are sure SvIOK is true. See also C<SvIV()>.
-
- IV SvIVX(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIVx
-X<SvIVx>
-
-Coerces the given SV to an integer and returns it.
-Guarantees to evaluate C<sv> only once. Only use
-this if C<sv> is an expression with side effects,
-otherwise use the more efficient C<SvIV>.
-
- IV SvIVx(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIV_nomg
-X<SvIV_nomg>
-
-Like C<SvIV> but doesn't process magic.
-
- IV SvIV_nomg(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIV_set
-X<SvIV_set>
-
-Set the value of the IV pointer in sv to val. It is possible to perform
-the same function of this macro with an lvalue assignment to C<SvIVX>.
-With future Perls, however, it will be more efficient to use
-C<SvIV_set> instead of the lvalue assignment to C<SvIVX>.
-
- void SvIV_set(SV* sv, IV val)
-
-=for hackers
-Found in file sv.h
-
-=item SvLEN
-X<SvLEN>
-
-Returns the size of the string buffer in the SV, not including any part
-attributable to C<SvOOK>. See C<SvCUR>.
-
- STRLEN SvLEN(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvLEN_set
-X<SvLEN_set>
-
-Set the actual length of the string which is in the SV. See C<SvIV_set>.
-
- void SvLEN_set(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvMAGIC_set
-X<SvMAGIC_set>
-
-Set the value of the MAGIC pointer in sv to val. See C<SvIV_set>.
-
- void SvMAGIC_set(SV* sv, MAGIC* val)
-
-=for hackers
-Found in file sv.h
-
-=item SvNIOK
-X<SvNIOK>
-
-Returns a U32 value indicating whether the SV contains a number, integer or
-double.
-
- U32 SvNIOK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNIOKp
-X<SvNIOKp>
-
-Returns a U32 value indicating whether the SV contains a number, integer or
-double. Checks the B<private> setting. Use C<SvNIOK> instead.
-
- U32 SvNIOKp(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNIOK_off
-X<SvNIOK_off>
-
-Unsets the NV/IV status of an SV.
-
- void SvNIOK_off(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNOK
-X<SvNOK>
-
-Returns a U32 value indicating whether the SV contains a double.
-
- U32 SvNOK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNOKp
-X<SvNOKp>
-
-Returns a U32 value indicating whether the SV contains a double. Checks the
-B<private> setting. Use C<SvNOK> instead.
-
- U32 SvNOKp(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNOK_off
-X<SvNOK_off>
-
-Unsets the NV status of an SV.
-
- void SvNOK_off(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNOK_on
-X<SvNOK_on>
-
-Tells an SV that it is a double.
-
- void SvNOK_on(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNOK_only
-X<SvNOK_only>
-
-Tells an SV that it is a double and disables all other OK bits.
-
- void SvNOK_only(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNV
-X<SvNV>
-
-Coerce the given SV to a double and return it. See C<SvNVx> for a version
-which guarantees to evaluate sv only once.
-
- NV SvNV(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNVX
-X<SvNVX>
-
-Returns the raw value in the SV's NV slot, without checks or conversions.
-Only use when you are sure SvNOK is true. See also C<SvNV()>.
-
- NV SvNVX(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNVx
-X<SvNVx>
-
-Coerces the given SV to a double and returns it.
-Guarantees to evaluate C<sv> only once. Only use
-this if C<sv> is an expression with side effects,
-otherwise use the more efficient C<SvNV>.
-
- NV SvNVx(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNV_nomg
-X<SvNV_nomg>
-
-Like C<SvNV> but doesn't process magic.
-
- NV SvNV_nomg(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNV_set
-X<SvNV_set>
-
-Set the value of the NV pointer in sv to val. See C<SvIV_set>.
-
- void SvNV_set(SV* sv, NV val)
-
-=for hackers
-Found in file sv.h
-
-=item SvOK
-X<SvOK>
-
-Returns a U32 value indicating whether the value is defined. This is
-only meaningful for scalars.
-
- U32 SvOK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvOOK
-X<SvOOK>
-
-Returns a U32 indicating whether the pointer to the string buffer is offset.
-This hack is used internally to speed up removal of characters from the
-beginning of a SvPV. When SvOOK is true, then the start of the
-allocated string buffer is actually C<SvOOK_offset()> bytes before SvPVX.
-This offset used to be stored in SvIVX, but is now stored within the spare
-part of the buffer.
-
- U32 SvOOK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvOOK_offset
-X<SvOOK_offset>
-
-Reads into I<len> the offset from SvPVX back to the true start of the
-allocated buffer, which will be non-zero if C<sv_chop> has been used to
-efficiently remove characters from start of the buffer. Implemented as a
-macro, which takes the address of I<len>, which must be of type C<STRLEN>.
-Evaluates I<sv> more than once. Sets I<len> to 0 if C<SvOOK(sv)> is false.
-
- void SvOOK_offset(NN SV*sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPOK
-X<SvPOK>
-
-Returns a U32 value indicating whether the SV contains a character
-string.
-
- U32 SvPOK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPOKp
-X<SvPOKp>
-
-Returns a U32 value indicating whether the SV contains a character string.
-Checks the B<private> setting. Use C<SvPOK> instead.
-
- U32 SvPOKp(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPOK_off
-X<SvPOK_off>
-
-Unsets the PV status of an SV.
-
- void SvPOK_off(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPOK_on
-X<SvPOK_on>
-
-Tells an SV that it is a string.
-
- void SvPOK_on(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPOK_only
-X<SvPOK_only>
-
-Tells an SV that it is a string and disables all other OK bits.
-Will also turn off the UTF-8 status.
-
- void SvPOK_only(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPOK_only_UTF8
-X<SvPOK_only_UTF8>
-
-Tells an SV that it is a string and disables all other OK bits,
-and leaves the UTF-8 status as it was.
-
- void SvPOK_only_UTF8(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPV
-X<SvPV>
-
-Returns a pointer to the string in the SV, or a stringified form of
-the SV if the SV does not contain a string. The SV may cache the
-stringified version becoming C<SvPOK>. Handles 'get' magic. See also
-C<SvPVx> for a version which guarantees to evaluate sv only once.
-
- char* SvPV(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVbyte
-X<SvPVbyte>
-
-Like C<SvPV>, but converts sv to byte representation first if necessary.
-
- char* SvPVbyte(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVbytex
-X<SvPVbytex>
-
-Like C<SvPV>, but converts sv to byte representation first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
-otherwise.
-
- char* SvPVbytex(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVbytex_force
-X<SvPVbytex_force>
-
-Like C<SvPV_force>, but converts sv to byte representation first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
-otherwise.
-
- char* SvPVbytex_force(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVbyte_force
-X<SvPVbyte_force>
-
-Like C<SvPV_force>, but converts sv to byte representation first if necessary.
-
- char* SvPVbyte_force(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVbyte_nolen
-X<SvPVbyte_nolen>
-
-Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
-
- char* SvPVbyte_nolen(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVutf8
-X<SvPVutf8>
-
-Like C<SvPV>, but converts sv to utf8 first if necessary.
-
- char* SvPVutf8(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVutf8x
-X<SvPVutf8x>
-
-Like C<SvPV>, but converts sv to utf8 first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
-otherwise.
-
- char* SvPVutf8x(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVutf8x_force
-X<SvPVutf8x_force>
-
-Like C<SvPV_force>, but converts sv to utf8 first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
-otherwise.
-
- char* SvPVutf8x_force(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVutf8_force
-X<SvPVutf8_force>
-
-Like C<SvPV_force>, but converts sv to utf8 first if necessary.
-
- char* SvPVutf8_force(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVutf8_nolen
-X<SvPVutf8_nolen>
-
-Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
-
- char* SvPVutf8_nolen(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVX
-X<SvPVX>
-
-Returns a pointer to the physical string in the SV. The SV must contain a
-string.
-
-This is also used to store the name of an autoloaded subroutine in an XS
-AUTOLOAD routine. See L<perlguts/Autoloading with XSUBs>.
-
- char* SvPVX(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVx
-X<SvPVx>
-
-A version of C<SvPV> which guarantees to evaluate C<sv> only once.
-Only use this if C<sv> is an expression with side effects, otherwise use the
-more efficient C<SvPV>.
-
- char* SvPVx(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPV_force
-X<SvPV_force>
-
-Like C<SvPV> but will force the SV into containing just a string
-(C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
-directly.
-
- char* SvPV_force(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPV_force_nomg
-X<SvPV_force_nomg>
-
-Like C<SvPV> but will force the SV into containing just a string
-(C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
-directly. Doesn't process magic.
-
- char* SvPV_force_nomg(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPV_nolen
-X<SvPV_nolen>
-
-Returns a pointer to the string in the SV, or a stringified form of
-the SV if the SV does not contain a string. The SV may cache the
-stringified form becoming C<SvPOK>. Handles 'get' magic.
-
- char* SvPV_nolen(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPV_nomg
-X<SvPV_nomg>
-
-Like C<SvPV> but doesn't process magic.
-
- char* SvPV_nomg(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPV_nomg_nolen
-X<SvPV_nomg_nolen>
-
-Like C<SvPV_nolen> but doesn't process magic.
-
- char* SvPV_nomg_nolen(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPV_set
-X<SvPV_set>
-
-Set the value of the PV pointer in sv to val. See C<SvIV_set>.
-
- void SvPV_set(SV* sv, char* val)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT
-X<SvREFCNT>
-
-Returns the value of the object's reference count.
-
- U32 SvREFCNT(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT_dec
-X<SvREFCNT_dec>
-
-Decrements the reference count of the given SV.
-
- void SvREFCNT_dec(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT_inc
-X<SvREFCNT_inc>
-
-Increments the reference count of the given SV.
-
-All of the following SvREFCNT_inc* macros are optimized versions of
-SvREFCNT_inc, and can be replaced with SvREFCNT_inc.
-
- SV* SvREFCNT_inc(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT_inc_NN
-X<SvREFCNT_inc_NN>
-
-Same as SvREFCNT_inc, but can only be used if you know I<sv>
-is not NULL. Since we don't have to check the NULLness, it's faster
-and smaller.
-
- SV* SvREFCNT_inc_NN(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT_inc_simple
-X<SvREFCNT_inc_simple>
-
-Same as SvREFCNT_inc, but can only be used with expressions without side
-effects. Since we don't have to store a temporary value, it's faster.
-
- SV* SvREFCNT_inc_simple(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT_inc_simple_NN
-X<SvREFCNT_inc_simple_NN>
-
-Same as SvREFCNT_inc_simple, but can only be used if you know I<sv>
-is not NULL. Since we don't have to check the NULLness, it's faster
-and smaller.
-
- SV* SvREFCNT_inc_simple_NN(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT_inc_simple_void
-X<SvREFCNT_inc_simple_void>
-
-Same as SvREFCNT_inc_simple, but can only be used if you don't need the
-return value. The macro doesn't need to return a meaningful value.
-
- void SvREFCNT_inc_simple_void(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT_inc_simple_void_NN
-X<SvREFCNT_inc_simple_void_NN>
-
-Same as SvREFCNT_inc, but can only be used if you don't need the return
-value, and you know that I<sv> is not NULL. The macro doesn't need
-to return a meaningful value, or check for NULLness, so it's smaller
-and faster.
-
- void SvREFCNT_inc_simple_void_NN(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT_inc_void
-X<SvREFCNT_inc_void>
-
-Same as SvREFCNT_inc, but can only be used if you don't need the
-return value. The macro doesn't need to return a meaningful value.
-
- void SvREFCNT_inc_void(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT_inc_void_NN
-X<SvREFCNT_inc_void_NN>
-
-Same as SvREFCNT_inc, but can only be used if you don't need the return
-value, and you know that I<sv> is not NULL. The macro doesn't need
-to return a meaningful value, or check for NULLness, so it's smaller
-and faster.
-
- void SvREFCNT_inc_void_NN(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvROK
-X<SvROK>
-
-Tests if the SV is an RV.
-
- U32 SvROK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvROK_off
-X<SvROK_off>
-
-Unsets the RV status of an SV.
-
- void SvROK_off(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvROK_on
-X<SvROK_on>
-
-Tells an SV that it is an RV.
-
- void SvROK_on(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvRV
-X<SvRV>
-
-Dereferences an RV to return the SV.
-
- SV* SvRV(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvRV_set
-X<SvRV_set>
-
-Set the value of the RV pointer in sv to val. See C<SvIV_set>.
-
- void SvRV_set(SV* sv, SV* val)
-
-=for hackers
-Found in file sv.h
-
-=item SvSTASH
-X<SvSTASH>
-
-Returns the stash of the SV.
-
- HV* SvSTASH(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvSTASH_set
-X<SvSTASH_set>
-
-Set the value of the STASH pointer in sv to val. See C<SvIV_set>.
-
- void SvSTASH_set(SV* sv, HV* val)
-
-=for hackers
-Found in file sv.h
-
-=item SvTAINT
-X<SvTAINT>
-
-Taints an SV if tainting is enabled, and if some input to the current
-expression is tainted--usually a variable, but possibly also implicit
-inputs such as locale settings. C<SvTAINT> propagates that taintedness to
-the outputs of an expression in a pessimistic fashion; i.e., without paying
-attention to precisely which outputs are influenced by which inputs.
-
- void SvTAINT(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvTAINTED
-X<SvTAINTED>
-
-Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
-not.
-
- bool SvTAINTED(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvTAINTED_off
-X<SvTAINTED_off>
-
-Untaints an SV. Be I<very> careful with this routine, as it short-circuits
-some of Perl's fundamental security features. XS module authors should not
-use this function unless they fully understand all the implications of
-unconditionally untainting the value. Untainting should be done in the
-standard perl fashion, via a carefully crafted regexp, rather than directly
-untainting variables.
-
- void SvTAINTED_off(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvTAINTED_on
-X<SvTAINTED_on>
-
-Marks an SV as tainted if tainting is enabled.
-
- void SvTAINTED_on(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvTRUE
-X<SvTRUE>
-
-Returns a boolean indicating whether Perl would evaluate the SV as true or
-false. See SvOK() for a defined/undefined test. Handles 'get' magic
-unless the scalar is already SvPOK, SvIOK or SvNOK (the public, not the
-private flags).
-
- bool SvTRUE(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvTRUE_nomg
-X<SvTRUE_nomg>
-
-Returns a boolean indicating whether Perl would evaluate the SV as true or
-false. See SvOK() for a defined/undefined test. Does not handle 'get' magic.
-
- bool SvTRUE_nomg(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvTYPE
-X<SvTYPE>
-
-Returns the type of the SV. See C<svtype>.
-
- svtype SvTYPE(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUOK
-X<SvUOK>
-
-Returns a boolean indicating whether the SV contains an unsigned integer.
-
- bool SvUOK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUPGRADE
-X<SvUPGRADE>
-
-Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
-perform the upgrade if necessary. See C<svtype>.
-
- void SvUPGRADE(SV* sv, svtype type)
-
-=for hackers
-Found in file sv.h
-
-=item SvUTF8
-X<SvUTF8>
-
-Returns a U32 value indicating the UTF-8 status of an SV. If things are set-up
-properly, this indicates whether or not the SV contains UTF-8 encoded data.
-Call this after SvPV() in case any call to string overloading updates the
-internal flag.
-
- U32 SvUTF8(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUTF8_off
-X<SvUTF8_off>
-
-Unsets the UTF-8 status of an SV (the data is not changed, just the flag).
-Do not use frivolously.
-
- void SvUTF8_off(SV *sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUTF8_on
-X<SvUTF8_on>
-
-Turn on the UTF-8 status of an SV (the data is not changed, just the flag).
-Do not use frivolously.
-
- void SvUTF8_on(SV *sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUV
-X<SvUV>
-
-Coerces the given SV to an unsigned integer and returns it. See C<SvUVx>
-for a version which guarantees to evaluate sv only once.
-
- UV SvUV(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUVX
-X<SvUVX>
-
-Returns the raw value in the SV's UV slot, without checks or conversions.
-Only use when you are sure SvIOK is true. See also C<SvUV()>.
-
- UV SvUVX(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUVx
-X<SvUVx>
-
-Coerces the given SV to an unsigned integer and
-returns it. Guarantees to C<sv> only once. Only
-use this if C<sv> is an expression with side effects,
-otherwise use the more efficient C<SvUV>.
-
- UV SvUVx(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUV_nomg
-X<SvUV_nomg>
-
-Like C<SvUV> but doesn't process magic.
-
- UV SvUV_nomg(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUV_set
-X<SvUV_set>
-
-Set the value of the UV pointer in sv to val. See C<SvIV_set>.
-
- void SvUV_set(SV* sv, UV val)
-
-=for hackers
-Found in file sv.h
-
-=item SvVOK
-X<SvVOK>
-
-Returns a boolean indicating whether the SV contains a v-string.
-
- bool SvVOK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item sv_catpvn_nomg
-X<sv_catpvn_nomg>
-
-Like C<sv_catpvn> but doesn't process magic.
-
- void sv_catpvn_nomg(SV* sv, const char* ptr,
- STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item sv_catpv_nomg
-X<sv_catpv_nomg>
-
-Like C<sv_catpv> but doesn't process magic.
-
- void sv_catpv_nomg(SV* sv, const char* ptr)
-
-=for hackers
-Found in file sv.h
-
-=item sv_catsv_nomg
-X<sv_catsv_nomg>
-
-Like C<sv_catsv> but doesn't process magic.
-
- void sv_catsv_nomg(SV* dsv, SV* ssv)
-
-=for hackers
-Found in file sv.h
-
-=item sv_derived_from
-X<sv_derived_from>
-
-Exactly like L</sv_derived_from_pv>, but doesn't take a C<flags> parameter.
-
- bool sv_derived_from(SV* sv, const char *const name)
-
-=for hackers
-Found in file universal.c
-
-=item sv_derived_from_pv
-X<sv_derived_from_pv>
-
-Exactly like L</sv_derived_from_pvn>, but takes a nul-terminated string
-instead of a string/length pair.
-
- bool sv_derived_from_pv(SV* sv,
- const char *const name,
- U32 flags)
-
-=for hackers
-Found in file universal.c
-
-=item sv_derived_from_pvn
-X<sv_derived_from_pvn>
-
-Returns a boolean indicating whether the SV is derived from the specified class
-I<at the C level>. To check derivation at the Perl level, call C<isa()> as a
-normal Perl method.
-
-Currently, the only significant value for C<flags> is SVf_UTF8.
-
- bool sv_derived_from_pvn(SV* sv,
- const char *const name,
- const STRLEN len, U32 flags)
-
-=for hackers
-Found in file universal.c
-
-=item sv_derived_from_sv
-X<sv_derived_from_sv>
-
-Exactly like L</sv_derived_from_pvn>, but takes the name string in the form
-of an SV instead of a string/length pair.
-
- bool sv_derived_from_sv(SV* sv, SV *namesv,
- U32 flags)
-
-=for hackers
-Found in file universal.c
-
-=item sv_does
-X<sv_does>
-
-Like L</sv_does_pv>, but doesn't take a C<flags> parameter.
-
- bool sv_does(SV* sv, const char *const name)
-
-=for hackers
-Found in file universal.c
-
-=item sv_does_pv
-X<sv_does_pv>
-
-Like L</sv_does_sv>, but takes a nul-terminated string instead of an SV.
-
- bool sv_does_pv(SV* sv, const char *const name,
- U32 flags)
-
-=for hackers
-Found in file universal.c
-
-=item sv_does_pvn
-X<sv_does_pvn>
-
-Like L</sv_does_sv>, but takes a string/length pair instead of an SV.
-
- bool sv_does_pvn(SV* sv, const char *const name,
- const STRLEN len, U32 flags)
-
-=for hackers
-Found in file universal.c
-
-=item sv_does_sv
-X<sv_does_sv>
-
-Returns a boolean indicating whether the SV performs a specific, named role.
-The SV can be a Perl object or the name of a Perl class.
-
- bool sv_does_sv(SV* sv, SV* namesv, U32 flags)
-
-=for hackers
-Found in file universal.c
-
-=item sv_report_used
-X<sv_report_used>
-
-Dump the contents of all SVs not yet freed (debugging aid).
-
- void sv_report_used()
-
-=for hackers
-Found in file sv.c
-
-=item sv_setsv_nomg
-X<sv_setsv_nomg>
-
-Like C<sv_setsv> but doesn't process magic.
-
- void sv_setsv_nomg(SV* dsv, SV* ssv)
-
-=for hackers
-Found in file sv.h
-
-=item sv_utf8_upgrade_nomg
-X<sv_utf8_upgrade_nomg>
-
-Like sv_utf8_upgrade, but doesn't do magic on C<sv>.
-
- STRLEN sv_utf8_upgrade_nomg(NN SV *sv)
-
-=for hackers
-Found in file sv.h
-
-
-=back
-
-=head1 SV-Body Allocation
-
-=over 8
-
-=item looks_like_number
-X<looks_like_number>
-
-Test if the content of an SV looks like a number (or is a number).
-C<Inf> and C<Infinity> are treated as numbers (so will not issue a
-non-numeric warning), even if your atof() doesn't grok them. Get-magic is
-ignored.
-
- I32 looks_like_number(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item newRV_noinc
-X<newRV_noinc>
-
-Creates an RV wrapper for an SV. The reference count for the original
-SV is B<not> incremented.
-
- SV* newRV_noinc(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item newSV
-X<newSV>
-
-Creates a new SV. A non-zero C<len> parameter indicates the number of
-bytes of preallocated string space the SV should have. An extra byte for a
-trailing NUL is also reserved. (SvPOK is not set for the SV even if string
-space is allocated.) The reference count for the new SV is set to 1.
-
-In 5.9.3, newSV() replaces the older NEWSV() API, and drops the first
-parameter, I<x>, a debug aid which allowed callers to identify themselves.
-This aid has been superseded by a new build option, PERL_MEM_LOG (see
-L<perlhacktips/PERL_MEM_LOG>). The older API is still there for use in XS
-modules supporting older perls.
-
- SV* newSV(const STRLEN len)
-
-=for hackers
-Found in file sv.c
-
-=item newSVhek
-X<newSVhek>
-
-Creates a new SV from the hash key structure. It will generate scalars that
-point to the shared string table where possible. Returns a new (undefined)
-SV if the hek is NULL.
-
- SV* newSVhek(const HEK *const hek)
-
-=for hackers
-Found in file sv.c
-
-=item newSViv
-X<newSViv>
-
-Creates a new SV and copies an integer into it. The reference count for the
-SV is set to 1.
-
- SV* newSViv(const IV i)
-
-=for hackers
-Found in file sv.c
-
-=item newSVnv
-X<newSVnv>
-
-Creates a new SV and copies a floating point value into it.
-The reference count for the SV is set to 1.
-
- SV* newSVnv(const NV n)
-
-=for hackers
-Found in file sv.c
-
-=item newSVpv
-X<newSVpv>
-
-Creates a new SV and copies a string into it. The reference count for the
-SV is set to 1. If C<len> is zero, Perl will compute the length using
-strlen(). For efficiency, consider using C<newSVpvn> instead.
-
- SV* newSVpv(const char *const s, const STRLEN len)
-
-=for hackers
-Found in file sv.c
-
-=item newSVpvf
-X<newSVpvf>
-
-Creates a new SV and initializes it with the string formatted like
-C<sprintf>.
-
- SV* newSVpvf(const char *const pat, ...)
-
-=for hackers
-Found in file sv.c
-
-=item newSVpvn
-X<newSVpvn>
-
-Creates a new SV and copies a buffer into it, which may contain NUL characters
-(C<\0>) and other binary data. The reference count for the SV is set to 1.
-Note that if C<len> is zero, Perl will create a zero length (Perl) string. You
-are responsible for ensuring that the source buffer is at least
-C<len> bytes long. If the C<buffer> argument is NULL the new SV will be
-undefined.
-
- SV* newSVpvn(const char *const s, const STRLEN len)
-
-=for hackers
-Found in file sv.c
-
-=item newSVpvn_flags
-X<newSVpvn_flags>
-
-Creates a new SV and copies a string into it. The reference count for the
-SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
-string. You are responsible for ensuring that the source string is at least
-C<len> bytes long. If the C<s> argument is NULL the new SV will be undefined.
-Currently the only flag bits accepted are C<SVf_UTF8> and C<SVs_TEMP>.
-If C<SVs_TEMP> is set, then C<sv_2mortal()> is called on the result before
-returning. If C<SVf_UTF8> is set, C<s>
-is considered to be in UTF-8 and the
-C<SVf_UTF8> flag will be set on the new SV.
-C<newSVpvn_utf8()> is a convenience wrapper for this function, defined as
-
- #define newSVpvn_utf8(s, len, u) \
- newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
-
- SV* newSVpvn_flags(const char *const s,
- const STRLEN len,
- const U32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item newSVpvn_share
-X<newSVpvn_share>
-
-Creates a new SV with its SvPVX_const pointing to a shared string in the string
-table. If the string does not already exist in the table, it is
-created first. Turns on READONLY and FAKE. If the C<hash> parameter
-is non-zero, that value is used; otherwise the hash is computed.
-The string's hash can later be retrieved from the SV
-with the C<SvSHARED_HASH()> macro. The idea here is
-that as the string table is used for shared hash keys these strings will have
-SvPVX_const == HeKEY and hash lookup will avoid string compare.
-
- SV* newSVpvn_share(const char* s, I32 len, U32 hash)
-
-=for hackers
-Found in file sv.c
-
-=item newSVpvs
-X<newSVpvs>
-
-Like C<newSVpvn>, but takes a literal string instead of a string/length pair.
-
- SV* newSVpvs(const char* s)
-
-=for hackers
-Found in file handy.h
-
-=item newSVpvs_flags
-X<newSVpvs_flags>
-
-Like C<newSVpvn_flags>, but takes a literal string instead of a string/length
-pair.
-
- SV* newSVpvs_flags(const char* s, U32 flags)
-
-=for hackers
-Found in file handy.h
-
-=item newSVpvs_share
-X<newSVpvs_share>
-
-Like C<newSVpvn_share>, but takes a literal string instead of a string/length
-pair and omits the hash parameter.
-
- SV* newSVpvs_share(const char* s)
-
-=for hackers
-Found in file handy.h
-
-=item newSVpv_share
-X<newSVpv_share>
-
-Like C<newSVpvn_share>, but takes a nul-terminated string instead of a
-string/length pair.
-
- SV* newSVpv_share(const char* s, U32 hash)
-
-=for hackers
-Found in file sv.c
-
-=item newSVrv
-X<newSVrv>
-
-Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
-it will be upgraded to one. If C<classname> is non-null then the new SV will
-be blessed in the specified package. The new SV is returned and its
-reference count is 1.
-
- SV* newSVrv(SV *const rv,
- const char *const classname)
-
-=for hackers
-Found in file sv.c
-
-=item newSVsv
-X<newSVsv>
-
-Creates a new SV which is an exact duplicate of the original SV.
-(Uses C<sv_setsv>.)
-
- SV* newSVsv(SV *const old)
-
-=for hackers
-Found in file sv.c
-
-=item newSVuv
-X<newSVuv>
-
-Creates a new SV and copies an unsigned integer into it.
-The reference count for the SV is set to 1.
-
- SV* newSVuv(const UV u)
-
-=for hackers
-Found in file sv.c
-
-=item newSV_type
-X<newSV_type>
-
-Creates a new SV, of the type specified. The reference count for the new SV
-is set to 1.
-
- SV* newSV_type(const svtype type)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2bool
-X<sv_2bool>
-
-This macro is only used by sv_true() or its macro equivalent, and only if
-the latter's argument is neither SvPOK, SvIOK nor SvNOK.
-It calls sv_2bool_flags with the SV_GMAGIC flag.
-
- bool sv_2bool(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2bool_flags
-X<sv_2bool_flags>
-
-This function is only used by sv_true() and friends, and only if
-the latter's argument is neither SvPOK, SvIOK nor SvNOK. If the flags
-contain SV_GMAGIC, then it does an mg_get() first.
-
-
- bool sv_2bool_flags(SV *const sv, const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2cv
-X<sv_2cv>
-
-Using various gambits, try to get a CV from an SV; in addition, try if
-possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
-The flags in C<lref> are passed to gv_fetchsv.
-
- CV* sv_2cv(SV* sv, HV **const st, GV **const gvp,
- const I32 lref)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2io
-X<sv_2io>
-
-Using various gambits, try to get an IO from an SV: the IO slot if its a
-GV; or the recursive result if we're an RV; or the IO slot of the symbol
-named after the PV if we're a string.
-
-'Get' magic is ignored on the sv passed in, but will be called on
-C<SvRV(sv)> if sv is an RV.
-
- IO* sv_2io(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2iv_flags
-X<sv_2iv_flags>
-
-Return the integer value of an SV, doing any necessary string
-conversion. If flags includes SV_GMAGIC, does an mg_get() first.
-Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
-
- IV sv_2iv_flags(SV *const sv, const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2mortal
-X<sv_2mortal>
-
-Marks an existing SV as mortal. The SV will be destroyed "soon", either
-by an explicit call to FREETMPS, or by an implicit call at places such as
-statement boundaries. SvTEMP() is turned on which means that the SV's
-string buffer can be "stolen" if this SV is copied. See also C<sv_newmortal>
-and C<sv_mortalcopy>.
-
- SV* sv_2mortal(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2nv_flags
-X<sv_2nv_flags>
-
-Return the num value of an SV, doing any necessary string or integer
-conversion. If flags includes SV_GMAGIC, does an mg_get() first.
-Normally used via the C<SvNV(sv)> and C<SvNVx(sv)> macros.
-
- NV sv_2nv_flags(SV *const sv, const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2pvbyte
-X<sv_2pvbyte>
-
-Return a pointer to the byte-encoded representation of the SV, and set *lp
-to its length. May cause the SV to be downgraded from UTF-8 as a
-side-effect.
-
-Usually accessed via the C<SvPVbyte> macro.
-
- char* sv_2pvbyte(SV *sv, STRLEN *const lp)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2pvutf8
-X<sv_2pvutf8>
-
-Return a pointer to the UTF-8-encoded representation of the SV, and set *lp
-to its length. May cause the SV to be upgraded to UTF-8 as a side-effect.
-
-Usually accessed via the C<SvPVutf8> macro.
-
- char* sv_2pvutf8(SV *sv, STRLEN *const lp)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2pv_flags
-X<sv_2pv_flags>
-
-Returns a pointer to the string value of an SV, and sets *lp to its length.
-If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a
-string if necessary. Normally invoked via the C<SvPV_flags> macro.
-C<sv_2pv()> and C<sv_2pv_nomg> usually end up here too.
-
- char* sv_2pv_flags(SV *const sv, STRLEN *const lp,
- const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2uv_flags
-X<sv_2uv_flags>
-
-Return the unsigned integer value of an SV, doing any necessary string
-conversion. If flags includes SV_GMAGIC, does an mg_get() first.
-Normally used via the C<SvUV(sv)> and C<SvUVx(sv)> macros.
-
- UV sv_2uv_flags(SV *const sv, const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_backoff
-X<sv_backoff>
-
-Remove any string offset. You should normally use the C<SvOOK_off> macro
-wrapper instead.
-
- int sv_backoff(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_bless
-X<sv_bless>
-
-Blesses an SV into a specified package. The SV must be an RV. The package
-must be designated by its stash (see C<gv_stashpv()>). The reference count
-of the SV is unaffected.
-
- SV* sv_bless(SV *const sv, HV *const stash)
-
-=for hackers
-Found in file sv.c
-
-=item sv_catpv
-X<sv_catpv>
-
-Concatenates the string onto the end of the string which is in the SV.
-If the SV has the UTF-8 status set, then the bytes appended should be
-valid UTF-8. Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
-
- void sv_catpv(SV *const sv, const char* ptr)
-
-=for hackers
-Found in file sv.c
-
-=item sv_catpvf
-X<sv_catpvf>
-
-Processes its arguments like C<sprintf> and appends the formatted
-output to an SV. If the appended data contains "wide" characters
-(including, but not limited to, SVs with a UTF-8 PV formatted with %s,
-and characters >255 formatted with %c), the original SV might get
-upgraded to UTF-8. Handles 'get' magic, but not 'set' magic. See
-C<sv_catpvf_mg>. If the original SV was UTF-8, the pattern should be
-valid UTF-8; if the original SV was bytes, the pattern should be too.
-
- void sv_catpvf(SV *const sv, const char *const pat,
- ...)
-
-=for hackers
-Found in file sv.c
-
-=item sv_catpvf_mg
-X<sv_catpvf_mg>
-
-Like C<sv_catpvf>, but also handles 'set' magic.
-
- void sv_catpvf_mg(SV *const sv,
- const char *const pat, ...)
-
-=for hackers
-Found in file sv.c
-
-=item sv_catpvn
-X<sv_catpvn>
-
-Concatenates the string onto the end of the string which is in the SV. The
-C<len> indicates number of bytes to copy. If the SV has the UTF-8
-status set, then the bytes appended should be valid UTF-8.
-Handles 'get' magic, but not 'set' magic. See C<sv_catpvn_mg>.
-
- void sv_catpvn(SV *dsv, const char *sstr, STRLEN len)
-
-=for hackers
-Found in file sv.c
-
-=item sv_catpvn_flags
-X<sv_catpvn_flags>
-
-Concatenates the string onto the end of the string which is in the SV. The
-C<len> indicates number of bytes to copy. If the SV has the UTF-8
-status set, then the bytes appended should be valid UTF-8.
-If C<flags> has the C<SV_SMAGIC> bit set, will
-C<mg_set> on C<dsv> afterwards if appropriate.
-C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
-in terms of this function.
-
- void sv_catpvn_flags(SV *const dstr,
- const char *sstr,
- const STRLEN len,
- const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_catpvs
-X<sv_catpvs>
-
-Like C<sv_catpvn>, but takes a literal string instead of a string/length pair.
-
- void sv_catpvs(SV* sv, const char* s)
-
-=for hackers
-Found in file handy.h
-
-=item sv_catpvs_flags
-X<sv_catpvs_flags>
-
-Like C<sv_catpvn_flags>, but takes a literal string instead of a
-string/length pair.
-
- void sv_catpvs_flags(SV* sv, const char* s,
- I32 flags)
-
-=for hackers
-Found in file handy.h
-
-=item sv_catpvs_mg
-X<sv_catpvs_mg>
-
-Like C<sv_catpvn_mg>, but takes a literal string instead of a
-string/length pair.
-
- void sv_catpvs_mg(SV* sv, const char* s)
-
-=for hackers
-Found in file handy.h
-
-=item sv_catpvs_nomg
-X<sv_catpvs_nomg>
-
-Like C<sv_catpvn_nomg>, but takes a literal string instead of a
-string/length pair.
-
- void sv_catpvs_nomg(SV* sv, const char* s)
-
-=for hackers
-Found in file handy.h
-
-=item sv_catpv_flags
-X<sv_catpv_flags>
-
-Concatenates the string onto the end of the string which is in the SV.
-If the SV has the UTF-8 status set, then the bytes appended should
-be valid UTF-8. If C<flags> has the C<SV_SMAGIC> bit set, will C<mg_set>
-on the modified SV if appropriate.
-
- void sv_catpv_flags(SV *dstr, const char *sstr,
- const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_catpv_mg
-X<sv_catpv_mg>
-
-Like C<sv_catpv>, but also handles 'set' magic.
-
- void sv_catpv_mg(SV *const sv, const char *const ptr)
-
-=for hackers
-Found in file sv.c
-
-=item sv_catsv
-X<sv_catsv>
-
-Concatenates the string from SV C<ssv> onto the end of the string in
-SV C<dsv>. Modifies C<dsv> but not C<ssv>. Handles 'get' magic, but
-not 'set' magic. See C<sv_catsv_mg>.
-
- void sv_catsv(SV *dstr, SV *sstr)
-
-=for hackers
-Found in file sv.c
-
-=item sv_catsv_flags
-X<sv_catsv_flags>
-
-Concatenates the string from SV C<ssv> onto the end of the string in
-SV C<dsv>. Modifies C<dsv> but not C<ssv>. If C<flags> has C<SV_GMAGIC>
-bit set, will C<mg_get> on the C<ssv>, if appropriate, before
-reading it. If the C<flags> contain C<SV_SMAGIC>, C<mg_set> will be
-called on the modified SV afterward, if appropriate. C<sv_catsv>
-and C<sv_catsv_nomg> are implemented in terms of this function.
-
- void sv_catsv_flags(SV *const dsv, SV *const ssv,
- const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_chop
-X<sv_chop>
-
-Efficient removal of characters from the beginning of the string buffer.
-SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
-the string buffer. The C<ptr> becomes the first character of the adjusted
-string. Uses the "OOK hack".
-
-Beware: after this function returns, C<ptr> and SvPVX_const(sv) may no longer
-refer to the same chunk of data.
-
-The unfortunate similarity of this function's name to that of Perl's C<chop>
-operator is strictly coincidental. This function works from the left;
-C<chop> works from the right.
-
- void sv_chop(SV *const sv, const char *const ptr)
-
-=for hackers
-Found in file sv.c
-
-=item sv_clear
-X<sv_clear>
-
-Clear an SV: call any destructors, free up any memory used by the body,
-and free the body itself. The SV's head is I<not> freed, although
-its type is set to all 1's so that it won't inadvertently be assumed
-to be live during global destruction etc.
-This function should only be called when REFCNT is zero. Most of the time
-you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>)
-instead.
-
- void sv_clear(SV *const orig_sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_cmp
-X<sv_cmp>
-
-Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
-string in C<sv1> is less than, equal to, or greater than the string in
-C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
-coerce its args to strings if necessary. See also C<sv_cmp_locale>.
-
- I32 sv_cmp(SV *const sv1, SV *const sv2)
-
-=for hackers
-Found in file sv.c
-
-=item sv_cmp_flags
-X<sv_cmp_flags>
-
-Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
-string in C<sv1> is less than, equal to, or greater than the string in
-C<sv2>. Is UTF-8 and 'use bytes' aware and will coerce its args to strings
-if necessary. If the flags include SV_GMAGIC, it handles get magic. See
-also C<sv_cmp_locale_flags>.
-
- I32 sv_cmp_flags(SV *const sv1, SV *const sv2,
- const U32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_cmp_locale
-X<sv_cmp_locale>
-
-Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
-'use bytes' aware, handles get magic, and will coerce its args to strings
-if necessary. See also C<sv_cmp>.
-
- I32 sv_cmp_locale(SV *const sv1, SV *const sv2)
-
-=for hackers
-Found in file sv.c
-
-=item sv_cmp_locale_flags
-X<sv_cmp_locale_flags>
-
-Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
-'use bytes' aware and will coerce its args to strings if necessary. If the
-flags contain SV_GMAGIC, it handles get magic. See also C<sv_cmp_flags>.
-
- I32 sv_cmp_locale_flags(SV *const sv1,
- SV *const sv2,
- const U32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_collxfrm
-X<sv_collxfrm>
-
-This calls C<sv_collxfrm_flags> with the SV_GMAGIC flag. See
-C<sv_collxfrm_flags>.
-
- char* sv_collxfrm(SV *const sv, STRLEN *const nxp)
-
-=for hackers
-Found in file sv.c
-
-=item sv_collxfrm_flags
-X<sv_collxfrm_flags>
-
-Add Collate Transform magic to an SV if it doesn't already have it. If the
-flags contain SV_GMAGIC, it handles get-magic.
-
-Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the
-scalar data of the variable, but transformed to such a format that a normal
-memory comparison can be used to compare the data according to the locale
-settings.
-
- char* sv_collxfrm_flags(SV *const sv,
- STRLEN *const nxp,
- I32 const flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_copypv
-X<sv_copypv>
-
-Copies a stringified representation of the source SV into the
-destination SV. Automatically performs any necessary mg_get and
-coercion of numeric values into strings. Guaranteed to preserve
-UTF8 flag even from overloaded objects. Similar in nature to
-sv_2pv[_flags] but operates directly on an SV instead of just the
-string. Mostly uses sv_2pv_flags to do its work, except when that
-would lose the UTF-8'ness of the PV.
-
- void sv_copypv(SV *const dsv, SV *const ssv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_dec
-X<sv_dec>
-
-Auto-decrement of the value in the SV, doing string to numeric conversion
-if necessary. Handles 'get' magic and operator overloading.
-
- void sv_dec(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_dec_nomg
-X<sv_dec_nomg>
-
-Auto-decrement of the value in the SV, doing string to numeric conversion
-if necessary. Handles operator overloading. Skips handling 'get' magic.
-
- void sv_dec_nomg(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_eq
-X<sv_eq>
-
-Returns a boolean indicating whether the strings in the two SVs are
-identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will
-coerce its args to strings if necessary.
-
- I32 sv_eq(SV* sv1, SV* sv2)
-
-=for hackers
-Found in file sv.c
-
-=item sv_eq_flags
-X<sv_eq_flags>
-
-Returns a boolean indicating whether the strings in the two SVs are
-identical. Is UTF-8 and 'use bytes' aware and coerces its args to strings
-if necessary. If the flags include SV_GMAGIC, it handles get-magic, too.
-
- I32 sv_eq_flags(SV* sv1, SV* sv2, const U32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_force_normal_flags
-X<sv_force_normal_flags>
-
-Undo various types of fakery on an SV: if the PV is a shared string, make
-a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
-an xpvmg; if we're a copy-on-write scalar, this is the on-write time when
-we do the copy, and is also used locally. If C<SV_COW_DROP_PV> is set
-then a copy-on-write scalar drops its PV buffer (if any) and becomes
-SvPOK_off rather than making a copy. (Used where this
-scalar is about to be set to some other value.) In addition,
-the C<flags> parameter gets passed to C<sv_unref_flags()>
-when unreffing. C<sv_force_normal> calls this function
-with flags set to 0.
-
- void sv_force_normal_flags(SV *const sv,
- const U32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_free
-X<sv_free>
-
-Decrement an SV's reference count, and if it drops to zero, call
-C<sv_clear> to invoke destructors and free up any memory used by
-the body; finally, deallocate the SV's head itself.
-Normally called via a wrapper macro C<SvREFCNT_dec>.
-
- void sv_free(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_gets
-X<sv_gets>
-
-Get a line from the filehandle and store it into the SV, optionally
-appending to the currently-stored string.
-
- char* sv_gets(SV *const sv, PerlIO *const fp,
- I32 append)
-
-=for hackers
-Found in file sv.c
-
-=item sv_grow
-X<sv_grow>
-
-Expands the character buffer in the SV. If necessary, uses C<sv_unref> and
-upgrades the SV to C<SVt_PV>. Returns a pointer to the character buffer.
-Use the C<SvGROW> wrapper instead.
-
- char* sv_grow(SV *const sv, STRLEN newlen)
-
-=for hackers
-Found in file sv.c
-
-=item sv_inc
-X<sv_inc>
-
-Auto-increment of the value in the SV, doing string to numeric conversion
-if necessary. Handles 'get' magic and operator overloading.
-
- void sv_inc(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_inc_nomg
-X<sv_inc_nomg>
-
-Auto-increment of the value in the SV, doing string to numeric conversion
-if necessary. Handles operator overloading. Skips handling 'get' magic.
-
- void sv_inc_nomg(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_insert
-X<sv_insert>
-
-Inserts a string at the specified offset/length within the SV. Similar to
-the Perl substr() function. Handles get magic.
-
- void sv_insert(SV *const bigstr, const STRLEN offset,
- const STRLEN len,
- const char *const little,
- const STRLEN littlelen)
-
-=for hackers
-Found in file sv.c
-
-=item sv_insert_flags
-X<sv_insert_flags>
-
-Same as C<sv_insert>, but the extra C<flags> are passed to the
-C<SvPV_force_flags> that applies to C<bigstr>.
-
- void sv_insert_flags(SV *const bigstr,
- const STRLEN offset,
- const STRLEN len,
- const char *const little,
- const STRLEN littlelen,
- const U32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_isa
-X<sv_isa>
-
-Returns a boolean indicating whether the SV is blessed into the specified
-class. This does not check for subtypes; use C<sv_derived_from> to verify
-an inheritance relationship.
-
- int sv_isa(SV* sv, const char *const name)
-
-=for hackers
-Found in file sv.c
-
-=item sv_isobject
-X<sv_isobject>
-
-Returns a boolean indicating whether the SV is an RV pointing to a blessed
-object. If the SV is not an RV, or if the object is not blessed, then this
-will return false.
-
- int sv_isobject(SV* sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_len
-X<sv_len>
-
-Returns the length of the string in the SV. Handles magic and type
-coercion. See also C<SvCUR>, which gives raw access to the xpv_cur slot.
-
- STRLEN sv_len(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_len_utf8
-X<sv_len_utf8>
-
-Returns the number of characters in the string in an SV, counting wide
-UTF-8 bytes as a single character. Handles magic and type coercion.
-
- STRLEN sv_len_utf8(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_magic
-X<sv_magic>
-
-Adds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if
-necessary, then adds a new magic item of type C<how> to the head of the
-magic list.
-
-See C<sv_magicext> (which C<sv_magic> now calls) for a description of the
-handling of the C<name> and C<namlen> arguments.
-
-You need to use C<sv_magicext> to add magic to SvREADONLY SVs and also
-to add more than one instance of the same 'how'.
-
- void sv_magic(SV *const sv, SV *const obj,
- const int how, const char *const name,
- const I32 namlen)
-
-=for hackers
-Found in file sv.c
-
-=item sv_magicext
-X<sv_magicext>
-
-Adds magic to an SV, upgrading it if necessary. Applies the
-supplied vtable and returns a pointer to the magic added.
-
-Note that C<sv_magicext> will allow things that C<sv_magic> will not.
-In particular, you can add magic to SvREADONLY SVs, and add more than
-one instance of the same 'how'.
-
-If C<namlen> is greater than zero then a C<savepvn> I<copy> of C<name> is
-stored, if C<namlen> is zero then C<name> is stored as-is and - as another
-special case - if C<(name && namlen == HEf_SVKEY)> then C<name> is assumed
-to contain an C<SV*> and is stored as-is with its REFCNT incremented.
-
-(This is now used as a subroutine by C<sv_magic>.)
-
- MAGIC * sv_magicext(SV *const sv, SV *const obj,
- const int how,
- const MGVTBL *const vtbl,
- const char *const name,
- const I32 namlen)
-
-=for hackers
-Found in file sv.c
-
-=item sv_mortalcopy
-X<sv_mortalcopy>
-
-Creates a new SV which is a copy of the original SV (using C<sv_setsv>).
-The new SV is marked as mortal. It will be destroyed "soon", either by an
-explicit call to FREETMPS, or by an implicit call at places such as
-statement boundaries. See also C<sv_newmortal> and C<sv_2mortal>.
-
- SV* sv_mortalcopy(SV *const oldsv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_newmortal
-X<sv_newmortal>
-
-Creates a new null SV which is mortal. The reference count of the SV is
-set to 1. It will be destroyed "soon", either by an explicit call to
-FREETMPS, or by an implicit call at places such as statement boundaries.
-See also C<sv_mortalcopy> and C<sv_2mortal>.
-
- SV* sv_newmortal()
-
-=for hackers
-Found in file sv.c
-
-=item sv_newref
-X<sv_newref>
-
-Increment an SV's reference count. Use the C<SvREFCNT_inc()> wrapper
-instead.
-
- SV* sv_newref(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_pos_b2u
-X<sv_pos_b2u>
-
-Converts the value pointed to by offsetp from a count of bytes from the
-start of the string, to a count of the equivalent number of UTF-8 chars.
-Handles magic and type coercion.
-
- void sv_pos_b2u(SV *const sv, I32 *const offsetp)
-
-=for hackers
-Found in file sv.c
-
-=item sv_pos_u2b
-X<sv_pos_u2b>
-
-Converts the value pointed to by offsetp from a count of UTF-8 chars from
-the start of the string, to a count of the equivalent number of bytes; if
-lenp is non-zero, it does the same to lenp, but this time starting from
-the offset, rather than from the start of the string. Handles magic and
-type coercion.
-
-Use C<sv_pos_u2b_flags> in preference, which correctly handles strings longer
-than 2Gb.
-
- void sv_pos_u2b(SV *const sv, I32 *const offsetp,
- I32 *const lenp)
-
-=for hackers
-Found in file sv.c
-
-=item sv_pos_u2b_flags
-X<sv_pos_u2b_flags>
-
-Converts the value pointed to by offsetp from a count of UTF-8 chars from
-the start of the string, to a count of the equivalent number of bytes; if
-lenp is non-zero, it does the same to lenp, but this time starting from
-the offset, rather than from the start
-of the string. Handles type coercion.
-I<flags> is passed to C<SvPV_flags>, and usually should be
-C<SV_GMAGIC|SV_CONST_RETURN> to handle magic.
-
- STRLEN sv_pos_u2b_flags(SV *const sv, STRLEN uoffset,
- STRLEN *const lenp, U32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_pvbyten_force
-X<sv_pvbyten_force>
-
-The backend for the C<SvPVbytex_force> macro. Always use the macro
-instead.
-
- char* sv_pvbyten_force(SV *const sv, STRLEN *const lp)
-
-=for hackers
-Found in file sv.c
-
-=item sv_pvn_force
-X<sv_pvn_force>
-
-Get a sensible string out of the SV somehow.
-A private implementation of the C<SvPV_force> macro for compilers which
-can't cope with complex macro expressions. Always use the macro instead.
-
- char* sv_pvn_force(SV* sv, STRLEN* lp)
-
-=for hackers
-Found in file sv.c
-
-=item sv_pvn_force_flags
-X<sv_pvn_force_flags>
-
-Get a sensible string out of the SV somehow.
-If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<sv> if
-appropriate, else not. C<sv_pvn_force> and C<sv_pvn_force_nomg> are
-implemented in terms of this function.
-You normally want to use the various wrapper macros instead: see
-C<SvPV_force> and C<SvPV_force_nomg>
-
- char* sv_pvn_force_flags(SV *const sv,
- STRLEN *const lp,
- const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_pvutf8n_force
-X<sv_pvutf8n_force>
-
-The backend for the C<SvPVutf8x_force> macro. Always use the macro
-instead.
-
- char* sv_pvutf8n_force(SV *const sv, STRLEN *const lp)
-
-=for hackers
-Found in file sv.c
-
-=item sv_reftype
-X<sv_reftype>
-
-Returns a string describing what the SV is a reference to.
-
- const char* sv_reftype(const SV *const sv, const int ob)
-
-=for hackers
-Found in file sv.c
-
-=item sv_replace
-X<sv_replace>
-
-Make the first argument a copy of the second, then delete the original.
-The target SV physically takes over ownership of the body of the source SV
-and inherits its flags; however, the target keeps any magic it owns,
-and any magic in the source is discarded.
-Note that this is a rather specialist SV copying operation; most of the
-time you'll want to use C<sv_setsv> or one of its many macro front-ends.
-
- void sv_replace(SV *const sv, SV *const nsv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_reset
-X<sv_reset>
-
-Underlying implementation for the C<reset> Perl function.
-Note that the perl-level function is vaguely deprecated.
-
- void sv_reset(const char* s, HV *const stash)
-
-=for hackers
-Found in file sv.c
-
-=item sv_rvweaken
-X<sv_rvweaken>
-
-Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the
-referred-to SV C<PERL_MAGIC_backref> magic if it hasn't already; and
-push a back-reference to this RV onto the array of backreferences
-associated with that magic. If the RV is magical, set magic will be
-called after the RV is cleared.
-
- SV* sv_rvweaken(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setiv
-X<sv_setiv>
-
-Copies an integer into the given SV, upgrading first if necessary.
-Does not handle 'set' magic. See also C<sv_setiv_mg>.
-
- void sv_setiv(SV *const sv, const IV num)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setiv_mg
-X<sv_setiv_mg>
-
-Like C<sv_setiv>, but also handles 'set' magic.
-
- void sv_setiv_mg(SV *const sv, const IV i)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setnv
-X<sv_setnv>
-
-Copies a double into the given SV, upgrading first if necessary.
-Does not handle 'set' magic. See also C<sv_setnv_mg>.
-
- void sv_setnv(SV *const sv, const NV num)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setnv_mg
-X<sv_setnv_mg>
-
-Like C<sv_setnv>, but also handles 'set' magic.
-
- void sv_setnv_mg(SV *const sv, const NV num)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpv
-X<sv_setpv>
-
-Copies a string into an SV. The string must be null-terminated. Does not
-handle 'set' magic. See C<sv_setpv_mg>.
-
- void sv_setpv(SV *const sv, const char *const ptr)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpvf
-X<sv_setpvf>
-
-Works like C<sv_catpvf> but copies the text into the SV instead of
-appending it. Does not handle 'set' magic. See C<sv_setpvf_mg>.
-
- void sv_setpvf(SV *const sv, const char *const pat,
- ...)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpvf_mg
-X<sv_setpvf_mg>
-
-Like C<sv_setpvf>, but also handles 'set' magic.
-
- void sv_setpvf_mg(SV *const sv,
- const char *const pat, ...)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpviv
-X<sv_setpviv>
-
-Copies an integer into the given SV, also updating its string value.
-Does not handle 'set' magic. See C<sv_setpviv_mg>.
-
- void sv_setpviv(SV *const sv, const IV num)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpviv_mg
-X<sv_setpviv_mg>
-
-Like C<sv_setpviv>, but also handles 'set' magic.
-
- void sv_setpviv_mg(SV *const sv, const IV iv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpvn
-X<sv_setpvn>
-
-Copies a string into an SV. The C<len> parameter indicates the number of
-bytes to be copied. If the C<ptr> argument is NULL the SV will become
-undefined. Does not handle 'set' magic. See C<sv_setpvn_mg>.
-
- void sv_setpvn(SV *const sv, const char *const ptr,
- const STRLEN len)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpvn_mg
-X<sv_setpvn_mg>
-
-Like C<sv_setpvn>, but also handles 'set' magic.
-
- void sv_setpvn_mg(SV *const sv,
- const char *const ptr,
- const STRLEN len)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpvs
-X<sv_setpvs>
-
-Like C<sv_setpvn>, but takes a literal string instead of a string/length pair.
-
- void sv_setpvs(SV* sv, const char* s)
-
-=for hackers
-Found in file handy.h
-
-=item sv_setpvs_mg
-X<sv_setpvs_mg>
-
-Like C<sv_setpvn_mg>, but takes a literal string instead of a
-string/length pair.
-
- void sv_setpvs_mg(SV* sv, const char* s)
-
-=for hackers
-Found in file handy.h
-
-=item sv_setpv_mg
-X<sv_setpv_mg>
-
-Like C<sv_setpv>, but also handles 'set' magic.
-
- void sv_setpv_mg(SV *const sv, const char *const ptr)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setref_iv
-X<sv_setref_iv>
-
-Copies an integer into a new SV, optionally blessing the SV. The C<rv>
-argument will be upgraded to an RV. That RV will be modified to point to
-the new SV. The C<classname> argument indicates the package for the
-blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
-will have a reference count of 1, and the RV will be returned.
-
- SV* sv_setref_iv(SV *const rv,
- const char *const classname,
- const IV iv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setref_nv
-X<sv_setref_nv>
-
-Copies a double into a new SV, optionally blessing the SV. The C<rv>
-argument will be upgraded to an RV. That RV will be modified to point to
-the new SV. The C<classname> argument indicates the package for the
-blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
-will have a reference count of 1, and the RV will be returned.
-
- SV* sv_setref_nv(SV *const rv,
- const char *const classname,
- const NV nv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setref_pv
-X<sv_setref_pv>
-
-Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
-argument will be upgraded to an RV. That RV will be modified to point to
-the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
-into the SV. The C<classname> argument indicates the package for the
-blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
-will have a reference count of 1, and the RV will be returned.
-
-Do not use with other Perl types such as HV, AV, SV, CV, because those
-objects will become corrupted by the pointer copy process.
-
-Note that C<sv_setref_pvn> copies the string while this copies the pointer.
-
- SV* sv_setref_pv(SV *const rv,
- const char *const classname,
- void *const pv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setref_pvn
-X<sv_setref_pvn>
-
-Copies a string into a new SV, optionally blessing the SV. The length of the
-string must be specified with C<n>. The C<rv> argument will be upgraded to
-an RV. That RV will be modified to point to the new SV. The C<classname>
-argument indicates the package for the blessing. Set C<classname> to
-C<NULL> to avoid the blessing. The new SV will have a reference count
-of 1, and the RV will be returned.
-
-Note that C<sv_setref_pv> copies the pointer while this copies the string.
-
- SV* sv_setref_pvn(SV *const rv,
- const char *const classname,
- const char *const pv,
- const STRLEN n)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setref_pvs
-X<sv_setref_pvs>
-
-Like C<sv_setref_pvn>, but takes a literal string instead of a
-string/length pair.
-
- SV * sv_setref_pvs(const char* s)
-
-=for hackers
-Found in file handy.h
-
-=item sv_setref_uv
-X<sv_setref_uv>
-
-Copies an unsigned integer into a new SV, optionally blessing the SV. The C<rv>
-argument will be upgraded to an RV. That RV will be modified to point to
-the new SV. The C<classname> argument indicates the package for the
-blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
-will have a reference count of 1, and the RV will be returned.
-
- SV* sv_setref_uv(SV *const rv,
- const char *const classname,
- const UV uv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setsv
-X<sv_setsv>
-
-Copies the contents of the source SV C<ssv> into the destination SV
-C<dsv>. The source SV may be destroyed if it is mortal, so don't use this
-function if the source SV needs to be reused. Does not handle 'set' magic.
-Loosely speaking, it performs a copy-by-value, obliterating any previous
-content of the destination.
-
-You probably want to use one of the assortment of wrappers, such as
-C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
-C<SvSetMagicSV_nosteal>.
-
- void sv_setsv(SV *dstr, SV *sstr)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setsv_flags
-X<sv_setsv_flags>
-
-Copies the contents of the source SV C<ssv> into the destination SV
-C<dsv>. The source SV may be destroyed if it is mortal, so don't use this
-function if the source SV needs to be reused. Does not handle 'set' magic.
-Loosely speaking, it performs a copy-by-value, obliterating any previous
-content of the destination.
-If the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on
-C<ssv> if appropriate, else not. If the C<flags>
-parameter has the C<NOSTEAL> bit set then the
-buffers of temps will not be stolen. <sv_setsv>
-and C<sv_setsv_nomg> are implemented in terms of this function.
-
-You probably want to use one of the assortment of wrappers, such as
-C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
-C<SvSetMagicSV_nosteal>.
-
-This is the primary function for copying scalars, and most other
-copy-ish functions and macros use this underneath.
-
- void sv_setsv_flags(SV *dstr, SV *sstr,
- const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setsv_mg
-X<sv_setsv_mg>
-
-Like C<sv_setsv>, but also handles 'set' magic.
-
- void sv_setsv_mg(SV *const dstr, SV *const sstr)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setuv
-X<sv_setuv>
-
-Copies an unsigned integer into the given SV, upgrading first if necessary.
-Does not handle 'set' magic. See also C<sv_setuv_mg>.
-
- void sv_setuv(SV *const sv, const UV num)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setuv_mg
-X<sv_setuv_mg>
-
-Like C<sv_setuv>, but also handles 'set' magic.
-
- void sv_setuv_mg(SV *const sv, const UV u)
-
-=for hackers
-Found in file sv.c
-
-=item sv_tainted
-X<sv_tainted>
-
-Test an SV for taintedness. Use C<SvTAINTED> instead.
-
- bool sv_tainted(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_true
-X<sv_true>
-
-Returns true if the SV has a true value by Perl's rules.
-Use the C<SvTRUE> macro instead, which may call C<sv_true()> or may
-instead use an in-line version.
-
- I32 sv_true(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_unmagic
-X<sv_unmagic>
-
-Removes all magic of type C<type> from an SV.
-
- int sv_unmagic(SV *const sv, const int type)
-
-=for hackers
-Found in file sv.c
-
-=item sv_unmagicext
-X<sv_unmagicext>
-
-Removes all magic of type C<type> with the specified C<vtbl> from an SV.
-
- int sv_unmagicext(SV *const sv, const int type,
- MGVTBL *vtbl)
-
-=for hackers
-Found in file sv.c
-
-=item sv_unref_flags
-X<sv_unref_flags>
-
-Unsets the RV status of the SV, and decrements the reference count of
-whatever was being referenced by the RV. This can almost be thought of
-as a reversal of C<newSVrv>. The C<cflags> argument can contain
-C<SV_IMMEDIATE_UNREF> to force the reference count to be decremented
-(otherwise the decrementing is conditional on the reference count being
-different from one or the reference being a readonly SV).
-See C<SvROK_off>.
-
- void sv_unref_flags(SV *const ref, const U32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_untaint
-X<sv_untaint>
-
-Untaint an SV. Use C<SvTAINTED_off> instead.
-
- void sv_untaint(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_upgrade
-X<sv_upgrade>
-
-Upgrade an SV to a more complex form. Generally adds a new body type to the
-SV, then copies across as much information as possible from the old body.
-It croaks if the SV is already in a more complex form than requested. You
-generally want to use the C<SvUPGRADE> macro wrapper, which checks the type
-before calling C<sv_upgrade>, and hence does not croak. See also
-C<svtype>.
-
- void sv_upgrade(SV *const sv, svtype new_type)
-
-=for hackers
-Found in file sv.c
-
-=item sv_usepvn_flags
-X<sv_usepvn_flags>
-
-Tells an SV to use C<ptr> to find its string value. Normally the
-string is stored inside the SV but sv_usepvn allows the SV to use an
-outside string. The C<ptr> should point to memory that was allocated
-by C<malloc>. It must be the start of a mallocked block
-of memory, and not a pointer to the middle of it. The
-string length, C<len>, must be supplied. By default
-this function will realloc (i.e. move) the memory pointed to by C<ptr>,
-so that pointer should not be freed or used by the programmer after
-giving it to sv_usepvn, and neither should any pointers from "behind"
-that pointer (e.g. ptr + 1) be used.
-
-If C<flags> & SV_SMAGIC is true, will call SvSETMAGIC. If C<flags> &
-SV_HAS_TRAILING_NUL is true, then C<ptr[len]> must be NUL, and the realloc
-will be skipped (i.e. the buffer is actually at least 1 byte longer than
-C<len>, and already meets the requirements for storing in C<SvPVX>).
-
- void sv_usepvn_flags(SV *const sv, char* ptr,
- const STRLEN len,
- const U32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_utf8_decode
-X<sv_utf8_decode>
-
-If the PV of the SV is an octet sequence in UTF-8
-and contains a multiple-byte character, the C<SvUTF8> flag is turned on
-so that it looks like a character. If the PV contains only single-byte
-characters, the C<SvUTF8> flag stays off.
-Scans PV for validity and returns false if the PV is invalid UTF-8.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- bool sv_utf8_decode(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_utf8_downgrade
-X<sv_utf8_downgrade>
-
-Attempts to convert the PV of an SV from characters to bytes.
-If the PV contains a character that cannot fit
-in a byte, this conversion will fail;
-in this case, either returns false or, if C<fail_ok> is not
-true, croaks.
-
-This is not as a general purpose Unicode to byte encoding interface:
-use the Encode extension for that.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- bool sv_utf8_downgrade(SV *const sv,
- const bool fail_ok)
-
-=for hackers
-Found in file sv.c
-
-=item sv_utf8_encode
-X<sv_utf8_encode>
-
-Converts the PV of an SV to UTF-8, but then turns the C<SvUTF8>
-flag off so that it looks like octets again.
-
- void sv_utf8_encode(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_utf8_upgrade
-X<sv_utf8_upgrade>
-
-Converts the PV of an SV to its UTF-8-encoded form.
-Forces the SV to string form if it is not already.
-Will C<mg_get> on C<sv> if appropriate.
-Always sets the SvUTF8 flag to avoid future validity checks even
-if the whole string is the same in UTF-8 as not.
-Returns the number of bytes in the converted string
-
-This is not as a general purpose byte encoding to Unicode interface:
-use the Encode extension for that.
-
- STRLEN sv_utf8_upgrade(SV *sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_utf8_upgrade_flags
-X<sv_utf8_upgrade_flags>
-
-Converts the PV of an SV to its UTF-8-encoded form.
-Forces the SV to string form if it is not already.
-Always sets the SvUTF8 flag to avoid future validity checks even
-if all the bytes are invariant in UTF-8.
-If C<flags> has C<SV_GMAGIC> bit set,
-will C<mg_get> on C<sv> if appropriate, else not.
-Returns the number of bytes in the converted string
-C<sv_utf8_upgrade> and
-C<sv_utf8_upgrade_nomg> are implemented in terms of this function.
-
-This is not as a general purpose byte encoding to Unicode interface:
-use the Encode extension for that.
-
- STRLEN sv_utf8_upgrade_flags(SV *const sv,
- const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_utf8_upgrade_nomg
-X<sv_utf8_upgrade_nomg>
-
-Like sv_utf8_upgrade, but doesn't do magic on C<sv>.
-
- STRLEN sv_utf8_upgrade_nomg(SV *sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_vcatpvf
-X<sv_vcatpvf>
-
-Processes its arguments like C<vsprintf> and appends the formatted output
-to an SV. Does not handle 'set' magic. See C<sv_vcatpvf_mg>.
-
-Usually used via its frontend C<sv_catpvf>.
-
- void sv_vcatpvf(SV *const sv, const char *const pat,
- va_list *const args)
-
-=for hackers
-Found in file sv.c
-
-=item sv_vcatpvfn
-X<sv_vcatpvfn>
-
-Processes its arguments like C<vsprintf> and appends the formatted output
-to an SV. Uses an array of SVs if the C style variable argument list is
-missing (NULL). When running with taint checks enabled, indicates via
-C<maybe_tainted> if results are untrustworthy (often due to the use of
-locales).
-
-Usually used via one of its frontends C<sv_vcatpvf> and C<sv_vcatpvf_mg>.
-
- void sv_vcatpvfn(SV *const sv, const char *const pat,
- const STRLEN patlen,
- va_list *const args,
- SV **const svargs, const I32 svmax,
- bool *const maybe_tainted)
-
-=for hackers
-Found in file sv.c
-
-=item sv_vcatpvf_mg
-X<sv_vcatpvf_mg>
-
-Like C<sv_vcatpvf>, but also handles 'set' magic.
-
-Usually used via its frontend C<sv_catpvf_mg>.
-
- void sv_vcatpvf_mg(SV *const sv,
- const char *const pat,
- va_list *const args)
-
-=for hackers
-Found in file sv.c
-
-=item sv_vsetpvf
-X<sv_vsetpvf>
-
-Works like C<sv_vcatpvf> but copies the text into the SV instead of
-appending it. Does not handle 'set' magic. See C<sv_vsetpvf_mg>.
-
-Usually used via its frontend C<sv_setpvf>.
-
- void sv_vsetpvf(SV *const sv, const char *const pat,
- va_list *const args)
-
-=for hackers
-Found in file sv.c
-
-=item sv_vsetpvfn
-X<sv_vsetpvfn>
-
-Works like C<sv_vcatpvfn> but copies the text into the SV instead of
-appending it.
-
-Usually used via one of its frontends C<sv_vsetpvf> and C<sv_vsetpvf_mg>.
-
- void sv_vsetpvfn(SV *const sv, const char *const pat,
- const STRLEN patlen,
- va_list *const args,
- SV **const svargs, const I32 svmax,
- bool *const maybe_tainted)
-
-=for hackers
-Found in file sv.c
-
-=item sv_vsetpvf_mg
-X<sv_vsetpvf_mg>
-
-Like C<sv_vsetpvf>, but also handles 'set' magic.
-
-Usually used via its frontend C<sv_setpvf_mg>.
-
- void sv_vsetpvf_mg(SV *const sv,
- const char *const pat,
- va_list *const args)
-
-=for hackers
-Found in file sv.c
-
-
-=back
-
-=head1 Unicode Support
-
-=over 8
-
-=item bytes_cmp_utf8
-X<bytes_cmp_utf8>
-
-Compares the sequence of characters (stored as octets) in C<b>, C<blen> with the
-sequence of characters (stored as UTF-8) in C<u>, C<ulen>. Returns 0 if they are
-equal, -1 or -2 if the first string is less than the second string, +1 or +2
-if the first string is greater than the second string.
-
--1 or +1 is returned if the shorter string was identical to the start of the
-longer string. -2 or +2 is returned if the was a difference between characters
-within the strings.
-
- int bytes_cmp_utf8(const U8 *b, STRLEN blen,
- const U8 *u, STRLEN ulen)
-
-=for hackers
-Found in file utf8.c
-
-=item bytes_from_utf8
-X<bytes_from_utf8>
-
-Converts a string C<s> of length C<len> from UTF-8 into native byte encoding.
-Unlike L</utf8_to_bytes> but like L</bytes_to_utf8>, returns a pointer to
-the newly-created string, and updates C<len> to contain the new
-length. Returns the original string if no conversion occurs, C<len>
-is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
-0 if C<s> is converted or consisted entirely of characters that are invariant
-in utf8 (i.e., US-ASCII on non-EBCDIC machines).
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- U8* bytes_from_utf8(const U8 *s, STRLEN *len,
- bool *is_utf8)
-
-=for hackers
-Found in file utf8.c
-
-=item bytes_to_utf8
-X<bytes_to_utf8>
-
-Converts a string C<s> of length C<len> bytes from the native encoding into
-UTF-8.
-Returns a pointer to the newly-created string, and sets C<len> to
-reflect the new length in bytes.
-
-A NUL character will be written after the end of the string.
-
-If you want to convert to UTF-8 from encodings other than
-the native (Latin1 or EBCDIC),
-see L</sv_recode_to_utf8>().
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- U8* bytes_to_utf8(const U8 *s, STRLEN *len)
-
-=for hackers
-Found in file utf8.c
-
-=item foldEQ_utf8
-X<foldEQ_utf8>
-
-Returns true if the leading portions of the strings C<s1> and C<s2> (either or both
-of which may be in UTF-8) are the same case-insensitively; false otherwise.
-How far into the strings to compare is determined by other input parameters.
-
-If C<u1> is true, the string C<s1> is assumed to be in UTF-8-encoded Unicode;
-otherwise it is assumed to be in native 8-bit encoding. Correspondingly for C<u2>
-with respect to C<s2>.
-
-If the byte length C<l1> is non-zero, it says how far into C<s1> to check for fold
-equality. In other words, C<s1>+C<l1> will be used as a goal to reach. The
-scan will not be considered to be a match unless the goal is reached, and
-scanning won't continue past that goal. Correspondingly for C<l2> with respect to
-C<s2>.
-
-If C<pe1> is non-NULL and the pointer it points to is not NULL, that pointer is
-considered an end pointer beyond which scanning of C<s1> will not continue under
-any circumstances. This means that if both C<l1> and C<pe1> are specified, and
-C<pe1>
-is less than C<s1>+C<l1>, the match will never be successful because it can
-never
-get as far as its goal (and in fact is asserted against). Correspondingly for
-C<pe2> with respect to C<s2>.
-
-At least one of C<s1> and C<s2> must have a goal (at least one of C<l1> and
-C<l2> must be non-zero), and if both do, both have to be
-reached for a successful match. Also, if the fold of a character is multiple
-characters, all of them must be matched (see tr21 reference below for
-'folding').
-
-Upon a successful match, if C<pe1> is non-NULL,
-it will be set to point to the beginning of the I<next> character of C<s1>
-beyond what was matched. Correspondingly for C<pe2> and C<s2>.
-
-For case-insensitiveness, the "casefolding" of Unicode is used
-instead of upper/lowercasing both the characters, see
-L<http://www.unicode.org/unicode/reports/tr21/> (Case Mappings).
-
- I32 foldEQ_utf8(const char *s1, char **pe1, UV l1,
- bool u1, const char *s2, char **pe2,
- UV l2, bool u2)
-
-=for hackers
-Found in file utf8.c
-
-=item is_ascii_string
-X<is_ascii_string>
-
-Returns true if the first C<len> bytes of the string C<s> are the same whether
-or not the string is encoded in UTF-8 (or UTF-EBCDIC on EBCDIC machines). That
-is, if they are invariant. On ASCII-ish machines, only ASCII characters
-fit this definition, hence the function's name.
-
-If C<len> is 0, it will be calculated using C<strlen(s)>.
-
-See also L</is_utf8_string>(), L</is_utf8_string_loclen>(), and L</is_utf8_string_loc>().
-
- bool is_ascii_string(const U8 *s, STRLEN len)
-
-=for hackers
-Found in file utf8.c
-
-=item is_utf8_char
-X<is_utf8_char>
-
-DEPRECATED!
-
-Tests if some arbitrary number of bytes begins in a valid UTF-8
-character. Note that an INVARIANT (i.e. ASCII on non-EBCDIC machines)
-character is a valid UTF-8 character. The actual number of bytes in the UTF-8
-character will be returned if it is valid, otherwise 0.
-
-This function is deprecated due to the possibility that malformed input could
-cause reading beyond the end of the input buffer. Use L</is_utf8_char_buf>
-instead.
-
- STRLEN is_utf8_char(const U8 *s)
-
-=for hackers
-Found in file utf8.c
-
-=item is_utf8_char_buf
-X<is_utf8_char_buf>
-
-Returns the number of bytes that comprise the first UTF-8 encoded character in
-buffer C<buf>. C<buf_end> should point to one position beyond the end of the
-buffer. 0 is returned if C<buf> does not point to a complete, valid UTF-8
-encoded character.
-
-Note that an INVARIANT character (i.e. ASCII on non-EBCDIC
-machines) is a valid UTF-8 character.
-
- STRLEN is_utf8_char_buf(const U8 *buf,
- const U8 *buf_end)
-
-=for hackers
-Found in file utf8.c
-
-=item is_utf8_string
-X<is_utf8_string>
-
-Returns true if the first C<len> bytes of string C<s> form a valid
-UTF-8 string, false otherwise. If C<len> is 0, it will be calculated
-using C<strlen(s)> (which means if you use this option, that C<s> has to have a
-terminating NUL byte). Note that all characters being ASCII constitute 'a
-valid UTF-8 string'.
-
-See also L</is_ascii_string>(), L</is_utf8_string_loclen>(), and L</is_utf8_string_loc>().
-
- bool is_utf8_string(const U8 *s, STRLEN len)
-
-=for hackers
-Found in file utf8.c
-
-=item is_utf8_string_loc
-X<is_utf8_string_loc>
-
-Like L</is_utf8_string> but stores the location of the failure (in the
-case of "utf8ness failure") or the location C<s>+C<len> (in the case of
-"utf8ness success") in the C<ep>.
-
-See also L</is_utf8_string_loclen>() and L</is_utf8_string>().
-
- bool is_utf8_string_loc(const U8 *s, STRLEN len,
- const U8 **p)
-
-=for hackers
-Found in file utf8.c
-
-=item is_utf8_string_loclen
-X<is_utf8_string_loclen>
-
-Like L</is_utf8_string>() but stores the location of the failure (in the
-case of "utf8ness failure") or the location C<s>+C<len> (in the case of
-"utf8ness success") in the C<ep>, and the number of UTF-8
-encoded characters in the C<el>.
-
-See also L</is_utf8_string_loc>() and L</is_utf8_string>().
-
- bool is_utf8_string_loclen(const U8 *s, STRLEN len,
- const U8 **ep, STRLEN *el)
-
-=for hackers
-Found in file utf8.c
-
-=item pv_uni_display
-X<pv_uni_display>
-
-Build to the scalar C<dsv> a displayable version of the string C<spv>,
-length C<len>, the displayable version being at most C<pvlim> bytes long
-(if longer, the rest is truncated and "..." will be appended).
-
-The C<flags> argument can have UNI_DISPLAY_ISPRINT set to display
-isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH
-to display the \\[nrfta\\] as the backslashed versions (like '\n')
-(UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\).
-UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both
-UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on.
-
-The pointer to the PV of the C<dsv> is returned.
-
- char* pv_uni_display(SV *dsv, const U8 *spv,
- STRLEN len, STRLEN pvlim,
- UV flags)
-
-=for hackers
-Found in file utf8.c
-
-=item sv_cat_decode
-X<sv_cat_decode>
-
-The encoding is assumed to be an Encode object, the PV of the ssv is
-assumed to be octets in that encoding and decoding the input starts
-from the position which (PV + *offset) pointed to. The dsv will be
-concatenated the decoded UTF-8 string from ssv. Decoding will terminate
-when the string tstr appears in decoding output or the input ends on
-the PV of the ssv. The value which the offset points will be modified
-to the last input position on the ssv.
-
-Returns TRUE if the terminator was found, else returns FALSE.
-
- bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv,
- int *offset, char* tstr, int tlen)
-
-=for hackers
-Found in file sv.c
-
-=item sv_recode_to_utf8
-X<sv_recode_to_utf8>
-
-The encoding is assumed to be an Encode object, on entry the PV
-of the sv is assumed to be octets in that encoding, and the sv
-will be converted into Unicode (and UTF-8).
-
-If the sv already is UTF-8 (or if it is not POK), or if the encoding
-is not a reference, nothing is done to the sv. If the encoding is not
-an C<Encode::XS> Encoding object, bad things will happen.
-(See F<lib/encoding.pm> and L<Encode>.)
-
-The PV of the sv is returned.
-
- char* sv_recode_to_utf8(SV* sv, SV *encoding)
-
-=for hackers
-Found in file sv.c
-
-=item sv_uni_display
-X<sv_uni_display>
-
-Build to the scalar C<dsv> a displayable version of the scalar C<sv>,
-the displayable version being at most C<pvlim> bytes long
-(if longer, the rest is truncated and "..." will be appended).
-
-The C<flags> argument is as in L</pv_uni_display>().
-
-The pointer to the PV of the C<dsv> is returned.
-
- char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim,
- UV flags)
-
-=for hackers
-Found in file utf8.c
-
-=item to_utf8_case
-X<to_utf8_case>
-
-The C<p> contains the pointer to the UTF-8 string encoding
-the character that is being converted. This routine assumes that the character
-at C<p> is well-formed.
-
-The C<ustrp> is a pointer to the character buffer to put the
-conversion result to. The C<lenp> is a pointer to the length
-of the result.
-
-The C<swashp> is a pointer to the swash to use.
-
-Both the special and normal mappings are stored in F<lib/unicore/To/Foo.pl>,
-and loaded by SWASHNEW, using F<lib/utf8_heavy.pl>. The C<special> (usually,
-but not always, a multicharacter mapping), is tried first.
-
-The C<special> is a string like "utf8::ToSpecLower", which means the
-hash %utf8::ToSpecLower. The access to the hash is through
-Perl_to_utf8_case().
-
-The C<normal> is a string like "ToLower" which means the swash
-%utf8::ToLower.
-
- UV to_utf8_case(const U8 *p, U8* ustrp,
- STRLEN *lenp, SV **swashp,
- const char *normal,
- const char *special)
-
-=for hackers
-Found in file utf8.c
-
-=item to_utf8_fold
-X<to_utf8_fold>
-
-Convert the UTF-8 encoded character at C<p> to its foldcase version and
-store that in UTF-8 in C<ustrp> and its length in bytes in C<lenp>. Note
-that the C<ustrp> needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
-foldcase version may be longer than the original character (up to
-three characters).
-
-The first character of the foldcased version is returned
-(but note, as explained above, that there may be more.)
-
-The character at C<p> is assumed by this routine to be well-formed.
-
- UV to_utf8_fold(const U8 *p, U8* ustrp,
- STRLEN *lenp)
-
-=for hackers
-Found in file utf8.c
-
-=item to_utf8_lower
-X<to_utf8_lower>
-
-Convert the UTF-8 encoded character at C<p> to its lowercase version and
-store that in UTF-8 in ustrp and its length in bytes in C<lenp>. Note
-that the C<ustrp> needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
-lowercase version may be longer than the original character.
-
-The first character of the lowercased version is returned
-(but note, as explained above, that there may be more.)
-
-The character at C<p> is assumed by this routine to be well-formed.
-
- UV to_utf8_lower(const U8 *p, U8* ustrp,
- STRLEN *lenp)
-
-=for hackers
-Found in file utf8.c
-
-=item to_utf8_title
-X<to_utf8_title>
-
-Convert the UTF-8 encoded character at C<p> to its titlecase version and
-store that in UTF-8 in C<ustrp> and its length in bytes in C<lenp>. Note
-that the C<ustrp> needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
-titlecase version may be longer than the original character.
-
-The first character of the titlecased version is returned
-(but note, as explained above, that there may be more.)
-
-The character at C<p> is assumed by this routine to be well-formed.
-
- UV to_utf8_title(const U8 *p, U8* ustrp,
- STRLEN *lenp)
-
-=for hackers
-Found in file utf8.c
-
-=item to_utf8_upper
-X<to_utf8_upper>
-
-Convert the UTF-8 encoded character at C<p> to its uppercase version and
-store that in UTF-8 in C<ustrp> and its length in bytes in C<lenp>. Note
-that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since
-the uppercase version may be longer than the original character.
-
-The first character of the uppercased version is returned
-(but note, as explained above, that there may be more.)
-
-The character at C<p> is assumed by this routine to be well-formed.
-
- UV to_utf8_upper(const U8 *p, U8* ustrp,
- STRLEN *lenp)
-
-=for hackers
-Found in file utf8.c
-
-=item utf8n_to_uvchr
-X<utf8n_to_uvchr>
-
-Returns the native character value of the first character in the string
-C<s>
-which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
-length, in bytes, of that character.
-
-C<length> and C<flags> are the same as L</utf8n_to_uvuni>().
-
- UV utf8n_to_uvchr(const U8 *s, STRLEN curlen,
- STRLEN *retlen, U32 flags)
-
-=for hackers
-Found in file utf8.c
-
-=item utf8n_to_uvuni
-X<utf8n_to_uvuni>
-
-Bottom level UTF-8 decode routine.
-Returns the code point value of the first character in the string C<s>,
-which is assumed to be in UTF-8 (or UTF-EBCDIC) encoding, and no longer than
-C<curlen> bytes; C<*retlen> (if C<retlen> isn't NULL) will be set to
-the length, in bytes, of that character.
-
-The value of C<flags> determines the behavior when C<s> does not point to a
-well-formed UTF-8 character. If C<flags> is 0, when a malformation is found,
-zero is returned and C<*retlen> is set so that (S<C<s> + C<*retlen>>) is the
-next possible position in C<s> that could begin a non-malformed character.
-Also, if UTF-8 warnings haven't been lexically disabled, a warning is raised.
-
-Various ALLOW flags can be set in C<flags> to allow (and not warn on)
-individual types of malformations, such as the sequence being overlong (that
-is, when there is a shorter sequence that can express the same code point;
-overlong sequences are expressly forbidden in the UTF-8 standard due to
-potential security issues). Another malformation example is the first byte of
-a character not being a legal first byte. See F<utf8.h> for the list of such
-flags. For allowed 0 length strings, this function returns 0; for allowed
-overlong sequences, the computed code point is returned; for all other allowed
-malformations, the Unicode REPLACEMENT CHARACTER is returned, as these have no
-determinable reasonable value.
-
-The UTF8_CHECK_ONLY flag overrides the behavior when a non-allowed (by other
-flags) malformation is found. If this flag is set, the routine assumes that
-the caller will raise a warning, and this function will silently just set
-C<retlen> to C<-1> and return zero.
-
-Certain code points are considered problematic. These are Unicode surrogates,
-Unicode non-characters, and code points above the Unicode maximum of 0x10FFFF.
-By default these are considered regular code points, but certain situations
-warrant special handling for them. If C<flags> contains
-UTF8_DISALLOW_ILLEGAL_INTERCHANGE, all three classes are treated as
-malformations and handled as such. The flags UTF8_DISALLOW_SURROGATE,
-UTF8_DISALLOW_NONCHAR, and UTF8_DISALLOW_SUPER (meaning above the legal Unicode
-maximum) can be set to disallow these categories individually.
-
-The flags UTF8_WARN_ILLEGAL_INTERCHANGE, UTF8_WARN_SURROGATE,
-UTF8_WARN_NONCHAR, and UTF8_WARN_SUPER will cause warning messages to be raised
-for their respective categories, but otherwise the code points are considered
-valid (not malformations). To get a category to both be treated as a
-malformation and raise a warning, specify both the WARN and DISALLOW flags.
-(But note that warnings are not raised if lexically disabled nor if
-UTF8_CHECK_ONLY is also specified.)
-
-Very large code points (above 0x7FFF_FFFF) are considered more problematic than
-the others that are above the Unicode legal maximum. There are several
-reasons: they requre at least 32 bits to represent them on ASCII platforms, are
-not representable at all on EBCDIC platforms, and the original UTF-8
-specification never went above this number (the current 0x10FFFF limit was
-imposed later). (The smaller ones, those that fit into 32 bits, are
-representable by a UV on ASCII platforms, but not by an IV, which means that
-the number of operations that can be performed on them is quite restricted.)
-The UTF-8 encoding on ASCII platforms for these large code points begins with a
-byte containing 0xFE or 0xFF. The UTF8_DISALLOW_FE_FF flag will cause them to
-be treated as malformations, while allowing smaller above-Unicode code points.
-(Of course UTF8_DISALLOW_SUPER will treat all above-Unicode code points,
-including these, as malformations.) Similarly, UTF8_WARN_FE_FF acts just like
-the other WARN flags, but applies just to these code points.
-
-All other code points corresponding to Unicode characters, including private
-use and those yet to be assigned, are never considered malformed and never
-warn.
-
-Most code should use L</utf8_to_uvchr_buf>() rather than call this directly.
-
- UV utf8n_to_uvuni(const U8 *s, STRLEN curlen,
- STRLEN *retlen, U32 flags)
-
-=for hackers
-Found in file utf8.c
-
-=item utf8_distance
-X<utf8_distance>
-
-Returns the number of UTF-8 characters between the UTF-8 pointers C<a>
-and C<b>.
-
-WARNING: use only if you *know* that the pointers point inside the
-same UTF-8 buffer.
-
- IV utf8_distance(const U8 *a, const U8 *b)
-
-=for hackers
-Found in file utf8.c
-
-=item utf8_hop
-X<utf8_hop>
-
-Return the UTF-8 pointer C<s> displaced by C<off> characters, either
-forward or backward.
-
-WARNING: do not use the following unless you *know* C<off> is within
-the UTF-8 data pointed to by C<s> *and* that on entry C<s> is aligned
-on the first byte of character or just after the last byte of a character.
-
- U8* utf8_hop(const U8 *s, I32 off)
-
-=for hackers
-Found in file utf8.c
-
-=item utf8_length
-X<utf8_length>
-
-Return the length of the UTF-8 char encoded string C<s> in characters.
-Stops at C<e> (inclusive). If C<e E<lt> s> or if the scan would end
-up past C<e>, croaks.
-
- STRLEN utf8_length(const U8* s, const U8 *e)
-
-=for hackers
-Found in file utf8.c
-
-=item utf8_to_bytes
-X<utf8_to_bytes>
-
-Converts a string C<s> of length C<len> from UTF-8 into native byte encoding.
-Unlike L</bytes_to_utf8>, this over-writes the original string, and
-updates C<len> to contain the new length.
-Returns zero on failure, setting C<len> to -1.
-
-If you need a copy of the string, see L</bytes_from_utf8>.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- U8* utf8_to_bytes(U8 *s, STRLEN *len)
-
-=for hackers
-Found in file utf8.c
-
-=item utf8_to_uvchr
-X<utf8_to_uvchr>
-
-DEPRECATED!
-
-Returns the native code point of the first character in the string C<s>
-which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
-length, in bytes, of that character.
-
-Some, but not all, UTF-8 malformations are detected, and in fact, some
-malformed input could cause reading beyond the end of the input buffer, which
-is why this function is deprecated. Use L</utf8_to_uvchr_buf> instead.
-
-If C<s> points to one of the detected malformations, and UTF8 warnings are
-enabled, zero is returned and C<*retlen> is set (if C<retlen> isn't
-NULL) to -1. If those warnings are off, the computed value if well-defined (or
-the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and C<*retlen>
-is set (if C<retlen> isn't NULL) so that (S<C<s> + C<*retlen>>) is the
-next possible position in C<s> that could begin a non-malformed character.
-See L</utf8n_to_uvuni> for details on when the REPLACEMENT CHARACTER is returned.
-
- UV utf8_to_uvchr(const U8 *s, STRLEN *retlen)
-
-=for hackers
-Found in file utf8.c
-
-=item utf8_to_uvchr_buf
-X<utf8_to_uvchr_buf>
-
-Returns the native code point of the first character in the string C<s> which
-is assumed to be in UTF-8 encoding; C<send> points to 1 beyond the end of C<s>.
-C<*retlen> will be set to the length, in bytes, of that character.
-
-If C<s> does not point to a well-formed UTF-8 character and UTF8 warnings are
-enabled, zero is returned and C<*retlen> is set (if C<retlen> isn't
-NULL) to -1. If those warnings are off, the computed value if well-defined (or
-the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and C<*retlen>
-is set (if C<retlen> isn't NULL) so that (S<C<s> + C<*retlen>>) is the
-next possible position in C<s> that could begin a non-malformed character.
-See L</utf8n_to_uvuni> for details on when the REPLACEMENT CHARACTER is returned.
-
- UV utf8_to_uvchr_buf(const U8 *s, const U8 *send,
- STRLEN *retlen)
-
-=for hackers
-Found in file utf8.c
-
-=item utf8_to_uvuni
-X<utf8_to_uvuni>
-
-DEPRECATED!
-
-Returns the Unicode code point of the first character in the string C<s>
-which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
-length, in bytes, of that character.
-
-This function should only be used when the returned UV is considered
-an index into the Unicode semantic tables (e.g. swashes).
-
-Some, but not all, UTF-8 malformations are detected, and in fact, some
-malformed input could cause reading beyond the end of the input buffer, which
-is why this function is deprecated. Use L</utf8_to_uvuni_buf> instead.
-
-If C<s> points to one of the detected malformations, and UTF8 warnings are
-enabled, zero is returned and C<*retlen> is set (if C<retlen> doesn't point to
-NULL) to -1. If those warnings are off, the computed value if well-defined (or
-the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and C<*retlen>
-is set (if C<retlen> isn't NULL) so that (S<C<s> + C<*retlen>>) is the
-next possible position in C<s> that could begin a non-malformed character.
-See L</utf8n_to_uvuni> for details on when the REPLACEMENT CHARACTER is returned.
-
- UV utf8_to_uvuni(const U8 *s, STRLEN *retlen)
-
-=for hackers
-Found in file utf8.c
-
-=item utf8_to_uvuni_buf
-X<utf8_to_uvuni_buf>
-
-Returns the Unicode code point of the first character in the string C<s> which
-is assumed to be in UTF-8 encoding; C<send> points to 1 beyond the end of C<s>.
-C<retlen> will be set to the length, in bytes, of that character.
-
-This function should only be used when the returned UV is considered
-an index into the Unicode semantic tables (e.g. swashes).
-
-If C<s> does not point to a well-formed UTF-8 character and UTF8 warnings are
-enabled, zero is returned and C<*retlen> is set (if C<retlen> isn't
-NULL) to -1. If those warnings are off, the computed value if well-defined (or
-the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and C<*retlen>
-is set (if C<retlen> isn't NULL) so that (S<C<s> + C<*retlen>>) is the
-next possible position in C<s> that could begin a non-malformed character.
-See L</utf8n_to_uvuni> for details on when the REPLACEMENT CHARACTER is returned.
-
- UV utf8_to_uvuni_buf(const U8 *s, const U8 *send,
- STRLEN *retlen)
-
-=for hackers
-Found in file utf8.c
-
-=item uvchr_to_utf8
-X<uvchr_to_utf8>
-
-Adds the UTF-8 representation of the Native code point C<uv> to the end
-of the string C<d>; C<d> should have at least C<UTF8_MAXBYTES+1> free
-bytes available. The return value is the pointer to the byte after the
-end of the new character. In other words,
-
- d = uvchr_to_utf8(d, uv);
-
-is the recommended wide native character-aware way of saying
-
- *(d++) = uv;
-
- U8* uvchr_to_utf8(U8 *d, UV uv)
-
-=for hackers
-Found in file utf8.c
-
-=item uvuni_to_utf8_flags
-X<uvuni_to_utf8_flags>
-
-Adds the UTF-8 representation of the code point C<uv> to the end
-of the string C<d>; C<d> should have at least C<UTF8_MAXBYTES+1> free
-bytes available. The return value is the pointer to the byte after the
-end of the new character. In other words,
-
- d = uvuni_to_utf8_flags(d, uv, flags);
-
-or, in most cases,
-
- d = uvuni_to_utf8(d, uv);
-
-(which is equivalent to)
-
- d = uvuni_to_utf8_flags(d, uv, 0);
-
-This is the recommended Unicode-aware way of saying
-
- *(d++) = uv;
-
-This function will convert to UTF-8 (and not warn) even code points that aren't
-legal Unicode or are problematic, unless C<flags> contains one or more of the
-following flags:
-
-If C<uv> is a Unicode surrogate code point and UNICODE_WARN_SURROGATE is set,
-the function will raise a warning, provided UTF8 warnings are enabled. If instead
-UNICODE_DISALLOW_SURROGATE is set, the function will fail and return NULL.
-If both flags are set, the function will both warn and return NULL.
-
-The UNICODE_WARN_NONCHAR and UNICODE_DISALLOW_NONCHAR flags correspondingly
-affect how the function handles a Unicode non-character. And, likewise for the
-UNICODE_WARN_SUPER and UNICODE_DISALLOW_SUPER flags, and code points that are
-above the Unicode maximum of 0x10FFFF. Code points above 0x7FFF_FFFF (which are
-even less portable) can be warned and/or disallowed even if other above-Unicode
-code points are accepted by the UNICODE_WARN_FE_FF and UNICODE_DISALLOW_FE_FF
-flags.
-
-And finally, the flag UNICODE_WARN_ILLEGAL_INTERCHANGE selects all four of the
-above WARN flags; and UNICODE_DISALLOW_ILLEGAL_INTERCHANGE selects all four
-DISALLOW flags.
-
-
- U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
-
-=for hackers
-Found in file utf8.c
-
-
-=back
-
-=head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
-
-=over 8
-
-=item ax
-X<ax>
-
-Variable which is setup by C<xsubpp> to indicate the stack base offset,
-used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros. The C<dMARK> macro
-must be called prior to setup the C<MARK> variable.
-
- I32 ax
-
-=for hackers
-Found in file XSUB.h
-
-=item CLASS
-X<CLASS>
-
-Variable which is setup by C<xsubpp> to indicate the
-class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>.
-
- char* CLASS
-
-=for hackers
-Found in file XSUB.h
-
-=item dAX
-X<dAX>
-
-Sets up the C<ax> variable.
-This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
-
- dAX;
-
-=for hackers
-Found in file XSUB.h
-
-=item dAXMARK
-X<dAXMARK>
-
-Sets up the C<ax> variable and stack marker variable C<mark>.
-This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
-
- dAXMARK;
-
-=for hackers
-Found in file XSUB.h
-
-=item dITEMS
-X<dITEMS>
-
-Sets up the C<items> variable.
-This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
-
- dITEMS;
-
-=for hackers
-Found in file XSUB.h
-
-=item dUNDERBAR
-X<dUNDERBAR>
-
-Sets up any variable needed by the C<UNDERBAR> macro. It used to define
-C<padoff_du>, but it is currently a noop. However, it is strongly advised
-to still use it for ensuring past and future compatibility.
-
- dUNDERBAR;
-
-=for hackers
-Found in file XSUB.h
-
-=item dXSARGS
-X<dXSARGS>
-
-Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
-Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
-This is usually handled automatically by C<xsubpp>.
-
- dXSARGS;
-
-=for hackers
-Found in file XSUB.h
-
-=item dXSI32
-X<dXSI32>
-
-Sets up the C<ix> variable for an XSUB which has aliases. This is usually
-handled automatically by C<xsubpp>.
-
- dXSI32;
-
-=for hackers
-Found in file XSUB.h
-
-=item items
-X<items>
-
-Variable which is setup by C<xsubpp> to indicate the number of
-items on the stack. See L<perlxs/"Variable-length Parameter Lists">.
-
- I32 items
-
-=for hackers
-Found in file XSUB.h
-
-=item ix
-X<ix>
-
-Variable which is setup by C<xsubpp> to indicate which of an
-XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
-
- I32 ix
-
-=for hackers
-Found in file XSUB.h
-
-=item newXSproto
-X<newXSproto>
-
-Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
-the subs.
-
-=for hackers
-Found in file XSUB.h
-
-=item RETVAL
-X<RETVAL>
-
-Variable which is setup by C<xsubpp> to hold the return value for an
-XSUB. This is always the proper type for the XSUB. See
-L<perlxs/"The RETVAL Variable">.
-
- (whatever) RETVAL
-
-=for hackers
-Found in file XSUB.h
-
-=item ST
-X<ST>
-
-Used to access elements on the XSUB's stack.
-
- SV* ST(int ix)
-
-=for hackers
-Found in file XSUB.h
-
-=item THIS
-X<THIS>
-
-Variable which is setup by C<xsubpp> to designate the object in a C++
-XSUB. This is always the proper type for the C++ object. See C<CLASS> and
-L<perlxs/"Using XS With C++">.
-
- (whatever) THIS
-
-=for hackers
-Found in file XSUB.h
-
-=item UNDERBAR
-X<UNDERBAR>
-
-The SV* corresponding to the $_ variable. Works even if there
-is a lexical $_ in scope.
-
-=for hackers
-Found in file XSUB.h
-
-=item XS
-X<XS>
-
-Macro to declare an XSUB and its C parameter list. This is handled by
-C<xsubpp>. It is the same as using the more explicit XS_EXTERNAL macro.
-
-=for hackers
-Found in file XSUB.h
-
-=item XS_APIVERSION_BOOTCHECK
-X<XS_APIVERSION_BOOTCHECK>
-
-Macro to verify that the perl api version an XS module has been compiled against
-matches the api version of the perl interpreter it's being loaded into.
-
- XS_APIVERSION_BOOTCHECK;
-
-=for hackers
-Found in file XSUB.h
-
-=item XS_EXTERNAL
-X<XS_EXTERNAL>
-
-Macro to declare an XSUB and its C parameter list explicitly exporting the symbols.
-
-=for hackers
-Found in file XSUB.h
-
-=item XS_INTERNAL
-X<XS_INTERNAL>
-
-Macro to declare an XSUB and its C parameter list without exporting the symbols.
-This is handled by C<xsubpp> and generally preferable over exporting the XSUB
-symbols unnecessarily.
-
-=for hackers
-Found in file XSUB.h
-
-=item XS_VERSION
-X<XS_VERSION>
-
-The version identifier for an XS module. This is usually
-handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
-
-=for hackers
-Found in file XSUB.h
-
-=item XS_VERSION_BOOTCHECK
-X<XS_VERSION_BOOTCHECK>
-
-Macro to verify that a PM module's $VERSION variable matches the XS
-module's C<XS_VERSION> variable. This is usually handled automatically by
-C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
-
- XS_VERSION_BOOTCHECK;
-
-=for hackers
-Found in file XSUB.h
-
-
-=back
-
-=head1 Warning and Dieing
-
-=over 8
-
-=item croak
-X<croak>
-
-This is an XS interface to Perl's C<die> function.
-
-Take a sprintf-style format pattern and argument list. These are used to
-generate a string message. If the message does not end with a newline,
-then it will be extended with some indication of the current location
-in the code, as described for L</mess_sv>.
-
-The error message will be used as an exception, by default
-returning control to the nearest enclosing C<eval>, but subject to
-modification by a C<$SIG{__DIE__}> handler. In any case, the C<croak>
-function never returns normally.
-
-For historical reasons, if C<pat> is null then the contents of C<ERRSV>
-(C<$@>) will be used as an error message or object instead of building an
-error message from arguments. If you want to throw a non-string object,
-or build an error message in an SV yourself, it is preferable to use
-the L</croak_sv> function, which does not involve clobbering C<ERRSV>.
-
- void croak(const char *pat, ...)
-
-=for hackers
-Found in file util.c
-
-=item croak_no_modify
-X<croak_no_modify>
-
-Exactly equivalent to C<Perl_croak(aTHX_ "%s", PL_no_modify)>, but generates
-terser object code than using C<Perl_croak>. Less code used on exception code
-paths reduces CPU cache pressure.
-
- void croak_no_modify()
-
-=for hackers
-Found in file util.c
-
-=item croak_sv
-X<croak_sv>
-
-This is an XS interface to Perl's C<die> function.
-
-C<baseex> is the error message or object. If it is a reference, it
-will be used as-is. Otherwise it is used as a string, and if it does
-not end with a newline then it will be extended with some indication of
-the current location in the code, as described for L</mess_sv>.
-
-The error message or object will be used as an exception, by default
-returning control to the nearest enclosing C<eval>, but subject to
-modification by a C<$SIG{__DIE__}> handler. In any case, the C<croak_sv>
-function never returns normally.
-
-To die with a simple string message, the L</croak> function may be
-more convenient.
-
- void croak_sv(SV *baseex)
-
-=for hackers
-Found in file util.c
-
-=item die
-X<die>
-
-Behaves the same as L</croak>, except for the return type.
-It should be used only where the C<OP *> return type is required.
-The function never actually returns.
-
- OP * die(const char *pat, ...)
-
-=for hackers
-Found in file util.c
-
-=item die_sv
-X<die_sv>
-
-Behaves the same as L</croak_sv>, except for the return type.
-It should be used only where the C<OP *> return type is required.
-The function never actually returns.
-
- OP * die_sv(SV *baseex)
-
-=for hackers
-Found in file util.c
-
-=item vcroak
-X<vcroak>
-
-This is an XS interface to Perl's C<die> function.
-
-C<pat> and C<args> are a sprintf-style format pattern and encapsulated
-argument list. These are used to generate a string message. If the
-message does not end with a newline, then it will be extended with
-some indication of the current location in the code, as described for
-L</mess_sv>.
-
-The error message will be used as an exception, by default
-returning control to the nearest enclosing C<eval>, but subject to
-modification by a C<$SIG{__DIE__}> handler. In any case, the C<croak>
-function never returns normally.
-
-For historical reasons, if C<pat> is null then the contents of C<ERRSV>
-(C<$@>) will be used as an error message or object instead of building an
-error message from arguments. If you want to throw a non-string object,
-or build an error message in an SV yourself, it is preferable to use
-the L</croak_sv> function, which does not involve clobbering C<ERRSV>.
-
- void vcroak(const char *pat, va_list *args)
-
-=for hackers
-Found in file util.c
-
-=item vwarn
-X<vwarn>
-
-This is an XS interface to Perl's C<warn> function.
-
-C<pat> and C<args> are a sprintf-style format pattern and encapsulated
-argument list. These are used to generate a string message. If the
-message does not end with a newline, then it will be extended with
-some indication of the current location in the code, as described for
-L</mess_sv>.
-
-The error message or object will by default be written to standard error,
-but this is subject to modification by a C<$SIG{__WARN__}> handler.
-
-Unlike with L</vcroak>, C<pat> is not permitted to be null.
-
- void vwarn(const char *pat, va_list *args)
-
-=for hackers
-Found in file util.c
-
-=item warn
-X<warn>
-
-This is an XS interface to Perl's C<warn> function.
-
-Take a sprintf-style format pattern and argument list. These are used to
-generate a string message. If the message does not end with a newline,
-then it will be extended with some indication of the current location
-in the code, as described for L</mess_sv>.
-
-The error message or object will by default be written to standard error,
-but this is subject to modification by a C<$SIG{__WARN__}> handler.
-
-Unlike with L</croak>, C<pat> is not permitted to be null.
-
- void warn(const char *pat, ...)
-
-=for hackers
-Found in file util.c
-
-=item warn_sv
-X<warn_sv>
-
-This is an XS interface to Perl's C<warn> function.
-
-C<baseex> is the error message or object. If it is a reference, it
-will be used as-is. Otherwise it is used as a string, and if it does
-not end with a newline then it will be extended with some indication of
-the current location in the code, as described for L</mess_sv>.
-
-The error message or object will by default be written to standard error,
-but this is subject to modification by a C<$SIG{__WARN__}> handler.
-
-To warn with a simple string message, the L</warn> function may be
-more convenient.
-
- void warn_sv(SV *baseex)
-
-=for hackers
-Found in file util.c
-
-
-=back
-
-=head1 Undocumented functions
-
-The following functions have been flagged as part of the public API,
-but are currently undocumented. Use them at your own risk, as the
-interfaces are subject to change.
-
-If you use one of them, you may wish to consider creating and submitting
-documentation for it. If your patch is accepted, this will indicate that
-the interface is stable (unless it is explicitly marked otherwise).
-
-=over
-
-=item GetVars
-X<GetVars>
-
-=item Gv_AMupdate
-X<Gv_AMupdate>
-
-=item PerlIO_clearerr
-X<PerlIO_clearerr>
-
-=item PerlIO_close
-X<PerlIO_close>
-
-=item PerlIO_context_layers
-X<PerlIO_context_layers>
-
-=item PerlIO_eof
-X<PerlIO_eof>
-
-=item PerlIO_error
-X<PerlIO_error>
-
-=item PerlIO_fileno
-X<PerlIO_fileno>
-
-=item PerlIO_fill
-X<PerlIO_fill>
-
-=item PerlIO_flush
-X<PerlIO_flush>
-
-=item PerlIO_get_base
-X<PerlIO_get_base>
-
-=item PerlIO_get_bufsiz
-X<PerlIO_get_bufsiz>
-
-=item PerlIO_get_cnt
-X<PerlIO_get_cnt>
-
-=item PerlIO_get_ptr
-X<PerlIO_get_ptr>
-
-=item PerlIO_read
-X<PerlIO_read>
-
-=item PerlIO_seek
-X<PerlIO_seek>
-
-=item PerlIO_set_cnt
-X<PerlIO_set_cnt>
-
-=item PerlIO_set_ptrcnt
-X<PerlIO_set_ptrcnt>
-
-=item PerlIO_setlinebuf
-X<PerlIO_setlinebuf>
-
-=item PerlIO_stderr
-X<PerlIO_stderr>
-
-=item PerlIO_stdin
-X<PerlIO_stdin>
-
-=item PerlIO_stdout
-X<PerlIO_stdout>
-
-=item PerlIO_tell
-X<PerlIO_tell>
-
-=item PerlIO_unread
-X<PerlIO_unread>
-
-=item PerlIO_write
-X<PerlIO_write>
-
-=item Slab_Alloc
-X<Slab_Alloc>
-
-=item Slab_Free
-X<Slab_Free>
-
-=item _is_utf8_quotemeta
-X<_is_utf8_quotemeta>
-
-=item amagic_call
-X<amagic_call>
-
-=item amagic_deref_call
-X<amagic_deref_call>
-
-=item any_dup
-X<any_dup>
-
-=item atfork_lock
-X<atfork_lock>
-
-=item atfork_unlock
-X<atfork_unlock>
-
-=item av_arylen_p
-X<av_arylen_p>
-
-=item av_iter_p
-X<av_iter_p>
-
-=item block_gimme
-X<block_gimme>
-
-=item call_atexit
-X<call_atexit>
-
-=item call_list
-X<call_list>
-
-=item calloc
-X<calloc>
-
-=item cast_i32
-X<cast_i32>
-
-=item cast_iv
-X<cast_iv>
-
-=item cast_ulong
-X<cast_ulong>
-
-=item cast_uv
-X<cast_uv>
-
-=item ck_warner
-X<ck_warner>
-
-=item ck_warner_d
-X<ck_warner_d>
-
-=item ckwarn
-X<ckwarn>
-
-=item ckwarn_d
-X<ckwarn_d>
-
-=item clone_params_del
-X<clone_params_del>
-
-=item clone_params_new
-X<clone_params_new>
-
-=item croak_nocontext
-X<croak_nocontext>
-
-=item csighandler
-X<csighandler>
-
-=item cx_dump
-X<cx_dump>
-
-=item cx_dup
-X<cx_dup>
-
-=item cxinc
-X<cxinc>
-
-=item deb
-X<deb>
-
-=item deb_nocontext
-X<deb_nocontext>
-
-=item debop
-X<debop>
-
-=item debprofdump
-X<debprofdump>
-
-=item debstack
-X<debstack>
-
-=item debstackptrs
-X<debstackptrs>
-
-=item delimcpy
-X<delimcpy>
-
-=item despatch_signals
-X<despatch_signals>
-
-=item die_nocontext
-X<die_nocontext>
-
-=item dirp_dup
-X<dirp_dup>
-
-=item do_aspawn
-X<do_aspawn>
-
-=item do_binmode
-X<do_binmode>
-
-=item do_close
-X<do_close>
-
-=item do_gv_dump
-X<do_gv_dump>
-
-=item do_gvgv_dump
-X<do_gvgv_dump>
-
-=item do_hv_dump
-X<do_hv_dump>
-
-=item do_join
-X<do_join>
-
-=item do_magic_dump
-X<do_magic_dump>
-
-=item do_op_dump
-X<do_op_dump>
-
-=item do_open
-X<do_open>
-
-=item do_open9
-X<do_open9>
-
-=item do_openn
-X<do_openn>
-
-=item do_pmop_dump
-X<do_pmop_dump>
-
-=item do_spawn
-X<do_spawn>
-
-=item do_spawn_nowait
-X<do_spawn_nowait>
-
-=item do_sprintf
-X<do_sprintf>
-
-=item do_sv_dump
-X<do_sv_dump>
-
-=item doing_taint
-X<doing_taint>
-
-=item doref
-X<doref>
-
-=item dounwind
-X<dounwind>
-
-=item dowantarray
-X<dowantarray>
-
-=item dump_all
-X<dump_all>
-
-=item dump_eval
-X<dump_eval>
-
-=item dump_fds
-X<dump_fds>
-
-=item dump_form
-X<dump_form>
-
-=item dump_indent
-X<dump_indent>
-
-=item dump_mstats
-X<dump_mstats>
-
-=item dump_packsubs
-X<dump_packsubs>
-
-=item dump_sub
-X<dump_sub>
-
-=item dump_vindent
-X<dump_vindent>
-
-=item filter_add
-X<filter_add>
-
-=item filter_del
-X<filter_del>
-
-=item filter_read
-X<filter_read>
-
-=item foldEQ_latin1
-X<foldEQ_latin1>
-
-=item form_nocontext
-X<form_nocontext>
-
-=item fp_dup
-X<fp_dup>
-
-=item fprintf_nocontext
-X<fprintf_nocontext>
-
-=item free_global_struct
-X<free_global_struct>
-
-=item free_tmps
-X<free_tmps>
-
-=item get_context
-X<get_context>
-
-=item get_mstats
-X<get_mstats>
-
-=item get_op_descs
-X<get_op_descs>
-
-=item get_op_names
-X<get_op_names>
-
-=item get_ppaddr
-X<get_ppaddr>
-
-=item get_vtbl
-X<get_vtbl>
-
-=item gp_dup
-X<gp_dup>
-
-=item gp_free
-X<gp_free>
-
-=item gp_ref
-X<gp_ref>
-
-=item gv_AVadd
-X<gv_AVadd>
-
-=item gv_HVadd
-X<gv_HVadd>
-
-=item gv_IOadd
-X<gv_IOadd>
-
-=item gv_SVadd
-X<gv_SVadd>
-
-=item gv_add_by_type
-X<gv_add_by_type>
-
-=item gv_autoload4
-X<gv_autoload4>
-
-=item gv_autoload_pv
-X<gv_autoload_pv>
-
-=item gv_autoload_pvn
-X<gv_autoload_pvn>
-
-=item gv_autoload_sv
-X<gv_autoload_sv>
-
-=item gv_check
-X<gv_check>
-
-=item gv_dump
-X<gv_dump>
-
-=item gv_efullname
-X<gv_efullname>
-
-=item gv_efullname3
-X<gv_efullname3>
-
-=item gv_efullname4
-X<gv_efullname4>
-
-=item gv_fetchfile
-X<gv_fetchfile>
-
-=item gv_fetchfile_flags
-X<gv_fetchfile_flags>
-
-=item gv_fetchpv
-X<gv_fetchpv>
-
-=item gv_fetchpvn_flags
-X<gv_fetchpvn_flags>
-
-=item gv_fetchsv
-X<gv_fetchsv>
-
-=item gv_fullname
-X<gv_fullname>
-
-=item gv_fullname3
-X<gv_fullname3>
-
-=item gv_fullname4
-X<gv_fullname4>
-
-=item gv_handler
-X<gv_handler>
-
-=item gv_name_set
-X<gv_name_set>
-
-=item he_dup
-X<he_dup>
-
-=item hek_dup
-X<hek_dup>
-
-=item hv_common
-X<hv_common>
-
-=item hv_common_key_len
-X<hv_common_key_len>
-
-=item hv_delayfree_ent
-X<hv_delayfree_ent>
-
-=item hv_eiter_p
-X<hv_eiter_p>
-
-=item hv_eiter_set
-X<hv_eiter_set>
-
-=item hv_free_ent
-X<hv_free_ent>
-
-=item hv_ksplit
-X<hv_ksplit>
-
-=item hv_name_set
-X<hv_name_set>
-
-=item hv_placeholders_get
-X<hv_placeholders_get>
-
-=item hv_placeholders_p
-X<hv_placeholders_p>
-
-=item hv_placeholders_set
-X<hv_placeholders_set>
-
-=item hv_riter_p
-X<hv_riter_p>
-
-=item hv_riter_set
-X<hv_riter_set>
-
-=item init_global_struct
-X<init_global_struct>
-
-=item init_i18nl10n
-X<init_i18nl10n>
-
-=item init_i18nl14n
-X<init_i18nl14n>
-
-=item init_stacks
-X<init_stacks>
-
-=item init_tm
-X<init_tm>
-
-=item instr
-X<instr>
-
-=item is_lvalue_sub
-X<is_lvalue_sub>
-
-=item is_uni_alnum
-X<is_uni_alnum>
-
-=item is_uni_alnum_lc
-X<is_uni_alnum_lc>
-
-=item is_uni_alpha
-X<is_uni_alpha>
-
-=item is_uni_alpha_lc
-X<is_uni_alpha_lc>
-
-=item is_uni_ascii
-X<is_uni_ascii>
-
-=item is_uni_ascii_lc
-X<is_uni_ascii_lc>
-
-=item is_uni_cntrl
-X<is_uni_cntrl>
-
-=item is_uni_cntrl_lc
-X<is_uni_cntrl_lc>
-
-=item is_uni_digit
-X<is_uni_digit>
-
-=item is_uni_digit_lc
-X<is_uni_digit_lc>
-
-=item is_uni_graph
-X<is_uni_graph>
-
-=item is_uni_graph_lc
-X<is_uni_graph_lc>
-
-=item is_uni_idfirst
-X<is_uni_idfirst>
-
-=item is_uni_idfirst_lc
-X<is_uni_idfirst_lc>
-
-=item is_uni_lower
-X<is_uni_lower>
-
-=item is_uni_lower_lc
-X<is_uni_lower_lc>
-
-=item is_uni_print
-X<is_uni_print>
-
-=item is_uni_print_lc
-X<is_uni_print_lc>
-
-=item is_uni_punct
-X<is_uni_punct>
-
-=item is_uni_punct_lc
-X<is_uni_punct_lc>
-
-=item is_uni_space
-X<is_uni_space>
-
-=item is_uni_space_lc
-X<is_uni_space_lc>
-
-=item is_uni_upper
-X<is_uni_upper>
-
-=item is_uni_upper_lc
-X<is_uni_upper_lc>
-
-=item is_uni_xdigit
-X<is_uni_xdigit>
-
-=item is_uni_xdigit_lc
-X<is_uni_xdigit_lc>
-
-=item is_utf8_alnum
-X<is_utf8_alnum>
-
-=item is_utf8_alpha
-X<is_utf8_alpha>
-
-=item is_utf8_ascii
-X<is_utf8_ascii>
-
-=item is_utf8_cntrl
-X<is_utf8_cntrl>
-
-=item is_utf8_digit
-X<is_utf8_digit>
-
-=item is_utf8_graph
-X<is_utf8_graph>
-
-=item is_utf8_idcont
-X<is_utf8_idcont>
-
-=item is_utf8_idfirst
-X<is_utf8_idfirst>
-
-=item is_utf8_lower
-X<is_utf8_lower>
-
-=item is_utf8_mark
-X<is_utf8_mark>
-
-=item is_utf8_perl_space
-X<is_utf8_perl_space>
-
-=item is_utf8_perl_word
-X<is_utf8_perl_word>
-
-=item is_utf8_posix_digit
-X<is_utf8_posix_digit>
-
-=item is_utf8_print
-X<is_utf8_print>
-
-=item is_utf8_punct
-X<is_utf8_punct>
-
-=item is_utf8_space
-X<is_utf8_space>
-
-=item is_utf8_upper
-X<is_utf8_upper>
-
-=item is_utf8_xdigit
-X<is_utf8_xdigit>
-
-=item is_utf8_xidcont
-X<is_utf8_xidcont>
-
-=item is_utf8_xidfirst
-X<is_utf8_xidfirst>
-
-=item leave_scope
-X<leave_scope>
-
-=item load_module_nocontext
-X<load_module_nocontext>
-
-=item magic_dump
-X<magic_dump>
-
-=item malloc
-X<malloc>
-
-=item markstack_grow
-X<markstack_grow>
-
-=item mess_nocontext
-X<mess_nocontext>
-
-=item mfree
-X<mfree>
-
-=item mg_dup
-X<mg_dup>
-
-=item mg_size
-X<mg_size>
-
-=item mini_mktime
-X<mini_mktime>
-
-=item moreswitches
-X<moreswitches>
-
-=item mro_get_from_name
-X<mro_get_from_name>
-
-=item mro_get_private_data
-X<mro_get_private_data>
-
-=item mro_set_mro
-X<mro_set_mro>
-
-=item mro_set_private_data
-X<mro_set_private_data>
-
-=item my_atof
-X<my_atof>
-
-=item my_atof2
-X<my_atof2>
-
-=item my_bcopy
-X<my_bcopy>
-
-=item my_bzero
-X<my_bzero>
-
-=item my_chsize
-X<my_chsize>
-
-=item my_cxt_index
-X<my_cxt_index>
-
-=item my_cxt_init
-X<my_cxt_init>
-
-=item my_dirfd
-X<my_dirfd>
-
-=item my_exit
-X<my_exit>
-
-=item my_failure_exit
-X<my_failure_exit>
-
-=item my_fflush_all
-X<my_fflush_all>
-
-=item my_fork
-X<my_fork>
-
-=item my_htonl
-X<my_htonl>
-
-=item my_lstat
-X<my_lstat>
-
-=item my_memcmp
-X<my_memcmp>
-
-=item my_memset
-X<my_memset>
-
-=item my_ntohl
-X<my_ntohl>
-
-=item my_pclose
-X<my_pclose>
-
-=item my_popen
-X<my_popen>
-
-=item my_popen_list
-X<my_popen_list>
-
-=item my_setenv
-X<my_setenv>
-
-=item my_socketpair
-X<my_socketpair>
-
-=item my_stat
-X<my_stat>
-
-=item my_strftime
-X<my_strftime>
-
-=item my_strlcat
-X<my_strlcat>
-
-=item my_strlcpy
-X<my_strlcpy>
-
-=item my_swap
-X<my_swap>
-
-=item newANONATTRSUB
-X<newANONATTRSUB>
-
-=item newANONHASH
-X<newANONHASH>
-
-=item newANONLIST
-X<newANONLIST>
-
-=item newANONSUB
-X<newANONSUB>
-
-=item newATTRSUB
-X<newATTRSUB>
-
-=item newAVREF
-X<newAVREF>
-
-=item newCVREF
-X<newCVREF>
-
-=item newFORM
-X<newFORM>
-
-=item newGVREF
-X<newGVREF>
-
-=item newGVgen
-X<newGVgen>
-
-=item newGVgen_flags
-X<newGVgen_flags>
-
-=item newHVREF
-X<newHVREF>
-
-=item newHVhv
-X<newHVhv>
-
-=item newIO
-X<newIO>
-
-=item newMYSUB
-X<newMYSUB>
-
-=item newPROG
-X<newPROG>
-
-=item newRV
-X<newRV>
-
-=item newSUB
-X<newSUB>
-
-=item newSVREF
-X<newSVREF>
-
-=item newSVpvf_nocontext
-X<newSVpvf_nocontext>
-
-=item new_collate
-X<new_collate>
-
-=item new_ctype
-X<new_ctype>
-
-=item new_numeric
-X<new_numeric>
-
-=item new_stackinfo
-X<new_stackinfo>
-
-=item ninstr
-X<ninstr>
-
-=item op_dump
-X<op_dump>
-
-=item op_free
-X<op_free>
-
-=item op_null
-X<op_null>
-
-=item op_refcnt_lock
-X<op_refcnt_lock>
-
-=item op_refcnt_unlock
-X<op_refcnt_unlock>
-
-=item parser_dup
-X<parser_dup>
-
-=item perl_alloc_using
-X<perl_alloc_using>
-
-=item perl_clone_using
-X<perl_clone_using>
-
-=item pmop_dump
-X<pmop_dump>
-
-=item pop_scope
-X<pop_scope>
-
-=item pregcomp
-X<pregcomp>
-
-=item pregexec
-X<pregexec>
-
-=item pregfree
-X<pregfree>
-
-=item pregfree2
-X<pregfree2>
-
-=item printf_nocontext
-X<printf_nocontext>
-
-=item ptr_table_clear
-X<ptr_table_clear>
-
-=item ptr_table_fetch
-X<ptr_table_fetch>
-
-=item ptr_table_free
-X<ptr_table_free>
-
-=item ptr_table_new
-X<ptr_table_new>
-
-=item ptr_table_split
-X<ptr_table_split>
-
-=item ptr_table_store
-X<ptr_table_store>
-
-=item push_scope
-X<push_scope>
-
-=item re_compile
-X<re_compile>
-
-=item re_dup_guts
-X<re_dup_guts>
-
-=item re_intuit_start
-X<re_intuit_start>
-
-=item re_intuit_string
-X<re_intuit_string>
-
-=item realloc
-X<realloc>
-
-=item reentrant_free
-X<reentrant_free>
-
-=item reentrant_init
-X<reentrant_init>
-
-=item reentrant_retry
-X<reentrant_retry>
-
-=item reentrant_size
-X<reentrant_size>
-
-=item ref
-X<ref>
-
-=item reg_named_buff_all
-X<reg_named_buff_all>
-
-=item reg_named_buff_exists
-X<reg_named_buff_exists>
-
-=item reg_named_buff_fetch
-X<reg_named_buff_fetch>
-
-=item reg_named_buff_firstkey
-X<reg_named_buff_firstkey>
-
-=item reg_named_buff_nextkey
-X<reg_named_buff_nextkey>
-
-=item reg_named_buff_scalar
-X<reg_named_buff_scalar>
-
-=item regclass_swash
-X<regclass_swash>
-
-=item regdump
-X<regdump>
-
-=item regdupe_internal
-X<regdupe_internal>
-
-=item regexec_flags
-X<regexec_flags>
-
-=item regfree_internal
-X<regfree_internal>
-
-=item reginitcolors
-X<reginitcolors>
-
-=item regnext
-X<regnext>
-
-=item repeatcpy
-X<repeatcpy>
-
-=item rninstr
-X<rninstr>
-
-=item rsignal
-X<rsignal>
-
-=item rsignal_state
-X<rsignal_state>
-
-=item runops_debug
-X<runops_debug>
-
-=item runops_standard
-X<runops_standard>
-
-=item rvpv_dup
-X<rvpv_dup>
-
-=item safesyscalloc
-X<safesyscalloc>
-
-=item safesysfree
-X<safesysfree>
-
-=item safesysmalloc
-X<safesysmalloc>
-
-=item safesysrealloc
-X<safesysrealloc>
-
-=item save_I16
-X<save_I16>
-
-=item save_I32
-X<save_I32>
-
-=item save_I8
-X<save_I8>
-
-=item save_adelete
-X<save_adelete>
-
-=item save_aelem
-X<save_aelem>
-
-=item save_aelem_flags
-X<save_aelem_flags>
-
-=item save_alloc
-X<save_alloc>
-
-=item save_aptr
-X<save_aptr>
-
-=item save_ary
-X<save_ary>
-
-=item save_bool
-X<save_bool>
-
-=item save_clearsv
-X<save_clearsv>
-
-=item save_delete
-X<save_delete>
-
-=item save_destructor
-X<save_destructor>
-
-=item save_destructor_x
-X<save_destructor_x>
-
-=item save_freeop
-X<save_freeop>
-
-=item save_freepv
-X<save_freepv>
-
-=item save_freesv
-X<save_freesv>
-
-=item save_generic_pvref
-X<save_generic_pvref>
-
-=item save_generic_svref
-X<save_generic_svref>
-
-=item save_gp
-X<save_gp>
-
-=item save_hash
-X<save_hash>
-
-=item save_hdelete
-X<save_hdelete>
-
-=item save_helem
-X<save_helem>
-
-=item save_helem_flags
-X<save_helem_flags>
-
-=item save_hints
-X<save_hints>
-
-=item save_hptr
-X<save_hptr>
-
-=item save_int
-X<save_int>
-
-=item save_item
-X<save_item>
-
-=item save_iv
-X<save_iv>
-
-=item save_list
-X<save_list>
-
-=item save_long
-X<save_long>
-
-=item save_mortalizesv
-X<save_mortalizesv>
-
-=item save_nogv
-X<save_nogv>
-
-=item save_op
-X<save_op>
-
-=item save_padsv_and_mortalize
-X<save_padsv_and_mortalize>
-
-=item save_pptr
-X<save_pptr>
-
-=item save_pushi32ptr
-X<save_pushi32ptr>
-
-=item save_pushptr
-X<save_pushptr>
-
-=item save_pushptrptr
-X<save_pushptrptr>
-
-=item save_re_context
-X<save_re_context>
-
-=item save_scalar
-X<save_scalar>
-
-=item save_set_svflags
-X<save_set_svflags>
-
-=item save_shared_pvref
-X<save_shared_pvref>
-
-=item save_sptr
-X<save_sptr>
-
-=item save_svref
-X<save_svref>
-
-=item save_vptr
-X<save_vptr>
-
-=item savestack_grow
-X<savestack_grow>
-
-=item savestack_grow_cnt
-X<savestack_grow_cnt>
-
-=item scan_num
-X<scan_num>
-
-=item scan_vstring
-X<scan_vstring>
-
-=item screaminstr
-X<screaminstr>
-
-=item seed
-X<seed>
-
-=item set_context
-X<set_context>
-
-=item set_numeric_local
-X<set_numeric_local>
-
-=item set_numeric_radix
-X<set_numeric_radix>
-
-=item set_numeric_standard
-X<set_numeric_standard>
-
-=item share_hek
-X<share_hek>
-
-=item si_dup
-X<si_dup>
-
-=item ss_dup
-X<ss_dup>
-
-=item stack_grow
-X<stack_grow>
-
-=item start_subparse
-X<start_subparse>
-
-=item stashpv_hvname_match
-X<stashpv_hvname_match>
-
-=item str_to_version
-X<str_to_version>
-
-=item sv_2iv
-X<sv_2iv>
-
-=item sv_2pv
-X<sv_2pv>
-
-=item sv_2uv
-X<sv_2uv>
-
-=item sv_catpvf_mg_nocontext
-X<sv_catpvf_mg_nocontext>
-
-=item sv_catpvf_nocontext
-X<sv_catpvf_nocontext>
-
-=item sv_compile_2op
-X<sv_compile_2op>
-
-=item sv_dump
-X<sv_dump>
-
-=item sv_dup
-X<sv_dup>
-
-=item sv_dup_inc
-X<sv_dup_inc>
-
-=item sv_peek
-X<sv_peek>
-
-=item sv_pvn_nomg
-X<sv_pvn_nomg>
-
-=item sv_setpvf_mg_nocontext
-X<sv_setpvf_mg_nocontext>
-
-=item sv_setpvf_nocontext
-X<sv_setpvf_nocontext>
-
-=item sv_utf8_upgrade_flags_grow
-X<sv_utf8_upgrade_flags_grow>
-
-=item swash_fetch
-X<swash_fetch>
-
-=item swash_init
-X<swash_init>
-
-=item sys_init
-X<sys_init>
-
-=item sys_init3
-X<sys_init3>
-
-=item sys_intern_clear
-X<sys_intern_clear>
-
-=item sys_intern_dup
-X<sys_intern_dup>
-
-=item sys_intern_init
-X<sys_intern_init>
-
-=item sys_term
-X<sys_term>
-
-=item taint_env
-X<taint_env>
-
-=item taint_proper
-X<taint_proper>
-
-=item tmps_grow
-X<tmps_grow>
-
-=item to_uni_fold
-X<to_uni_fold>
-
-=item to_uni_lower
-X<to_uni_lower>
-
-=item to_uni_lower_lc
-X<to_uni_lower_lc>
-
-=item to_uni_title
-X<to_uni_title>
-
-=item to_uni_title_lc
-X<to_uni_title_lc>
-
-=item to_uni_upper
-X<to_uni_upper>
-
-=item to_uni_upper_lc
-X<to_uni_upper_lc>
-
-=item unlnk
-X<unlnk>
-
-=item unsharepvn
-X<unsharepvn>
-
-=item utf16_to_utf8
-X<utf16_to_utf8>
-
-=item utf16_to_utf8_reversed
-X<utf16_to_utf8_reversed>
-
-=item uvchr_to_utf8_flags
-X<uvchr_to_utf8_flags>
-
-=item uvuni_to_utf8
-X<uvuni_to_utf8>
-
-=item vdeb
-X<vdeb>
-
-=item vform
-X<vform>
-
-=item vload_module
-X<vload_module>
-
-=item vnewSVpvf
-X<vnewSVpvf>
-
-=item vwarner
-X<vwarner>
-
-=item warn_nocontext
-X<warn_nocontext>
-
-=item warner
-X<warner>
-
-=item warner_nocontext
-X<warner_nocontext>
-
-=item whichsig
-X<whichsig>
-
-=item whichsig_pv
-X<whichsig_pv>
-
-=item whichsig_pvn
-X<whichsig_pvn>
-
-=item whichsig_sv
-X<whichsig_sv>
-
-=back
-
-
-=head1 AUTHORS
-
-Until May 1997, this document was maintained by Jeff Okamoto
-<okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
-
-With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
-Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
-Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
-Stephen McCamant, and Gurusamy Sarathy.
-
-API Listing originally by Dean Roehrich <roehrich@cray.com>.
-
-Updated to be autogenerated from comments in the source by Benjamin Stuhl.
-
-=head1 SEE ALSO
-
-L<perlguts>, L<perlxs>, L<perlxstut>, L<perlintern>
-
-=cut
-
- ex: set ro:
diff --git a/Master/tlpkg/tlperl/lib/pods/perlapio.pod b/Master/tlpkg/tlperl/lib/pods/perlapio.pod
deleted file mode 100644
index bb7115f8e8c..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlapio.pod
+++ /dev/null
@@ -1,525 +0,0 @@
-=head1 NAME
-
-perlapio - perl's IO abstraction interface.
-
-=head1 SYNOPSIS
-
- #define PERLIO_NOT_STDIO 0 /* For co-existence with stdio only */
- #include <perlio.h> /* Usually via #include <perl.h> */
-
- PerlIO *PerlIO_stdin(void);
- PerlIO *PerlIO_stdout(void);
- PerlIO *PerlIO_stderr(void);
-
- PerlIO *PerlIO_open(const char *path,const char *mode);
- PerlIO *PerlIO_fdopen(int fd, const char *mode);
- PerlIO *PerlIO_reopen(const char *path, const char *mode, PerlIO *old); /* deprecated */
- int PerlIO_close(PerlIO *f);
-
- int PerlIO_stdoutf(const char *fmt,...)
- int PerlIO_puts(PerlIO *f,const char *string);
- int PerlIO_putc(PerlIO *f,int ch);
- int PerlIO_write(PerlIO *f,const void *buf,size_t numbytes);
- int PerlIO_printf(PerlIO *f, const char *fmt,...);
- int PerlIO_vprintf(PerlIO *f, const char *fmt, va_list args);
- int PerlIO_flush(PerlIO *f);
-
- int PerlIO_eof(PerlIO *f);
- int PerlIO_error(PerlIO *f);
- void PerlIO_clearerr(PerlIO *f);
-
- int PerlIO_getc(PerlIO *d);
- int PerlIO_ungetc(PerlIO *f,int ch);
- int PerlIO_read(PerlIO *f, void *buf, size_t numbytes);
-
- int PerlIO_fileno(PerlIO *f);
-
- void PerlIO_setlinebuf(PerlIO *f);
-
- Off_t PerlIO_tell(PerlIO *f);
- int PerlIO_seek(PerlIO *f, Off_t offset, int whence);
- void PerlIO_rewind(PerlIO *f);
-
- int PerlIO_getpos(PerlIO *f, SV *save); /* prototype changed */
- int PerlIO_setpos(PerlIO *f, SV *saved); /* prototype changed */
-
- int PerlIO_fast_gets(PerlIO *f);
- int PerlIO_has_cntptr(PerlIO *f);
- int PerlIO_get_cnt(PerlIO *f);
- char *PerlIO_get_ptr(PerlIO *f);
- void PerlIO_set_ptrcnt(PerlIO *f, char *ptr, int count);
-
- int PerlIO_canset_cnt(PerlIO *f); /* deprecated */
- void PerlIO_set_cnt(PerlIO *f, int count); /* deprecated */
-
- int PerlIO_has_base(PerlIO *f);
- char *PerlIO_get_base(PerlIO *f);
- int PerlIO_get_bufsiz(PerlIO *f);
-
- PerlIO *PerlIO_importFILE(FILE *stdio, const char *mode);
- FILE *PerlIO_exportFILE(PerlIO *f, int flags);
- FILE *PerlIO_findFILE(PerlIO *f);
- void PerlIO_releaseFILE(PerlIO *f,FILE *stdio);
-
- int PerlIO_apply_layers(PerlIO *f, const char *mode, const char *layers);
- int PerlIO_binmode(PerlIO *f, int ptype, int imode, const char *layers);
- void PerlIO_debug(const char *fmt,...)
-
-=head1 DESCRIPTION
-
-Perl's source code, and extensions that want maximum portability,
-should use the above functions instead of those defined in ANSI C's
-I<stdio.h>. The perl headers (in particular "perlio.h") will
-C<#define> them to the I/O mechanism selected at Configure time.
-
-The functions are modeled on those in I<stdio.h>, but parameter order
-has been "tidied up a little".
-
-C<PerlIO *> takes the place of FILE *. Like FILE * it should be
-treated as opaque (it is probably safe to assume it is a pointer to
-something).
-
-There are currently three implementations:
-
-=over 4
-
-=item 1. USE_STDIO
-
-All above are #define'd to stdio functions or are trivial wrapper
-functions which call stdio. In this case I<only> PerlIO * is a FILE *.
-This has been the default implementation since the abstraction was
-introduced in perl5.003_02.
-
-=item 2. USE_SFIO
-
-A "legacy" implementation in terms of the "sfio" library. Used for
-some specialist applications on Unix machines ("sfio" is not widely
-ported away from Unix). Most of above are #define'd to the sfio
-functions. PerlIO * is in this case Sfio_t *.
-
-=item 3. USE_PERLIO
-
-Introduced just after perl5.7.0, this is a re-implementation of the
-above abstraction which allows perl more control over how IO is done
-as it decouples IO from the way the operating system and C library
-choose to do things. For USE_PERLIO PerlIO * has an extra layer of
-indirection - it is a pointer-to-a-pointer. This allows the PerlIO *
-to remain with a known value while swapping the implementation around
-underneath I<at run time>. In this case all the above are true (but
-very simple) functions which call the underlying implementation.
-
-This is the only implementation for which C<PerlIO_apply_layers()>
-does anything "interesting".
-
-The USE_PERLIO implementation is described in L<perliol>.
-
-=back
-
-Because "perlio.h" is a thin layer (for efficiency) the semantics of
-these functions are somewhat dependent on the underlying implementation.
-Where these variations are understood they are noted below.
-
-Unless otherwise noted, functions return 0 on success, or a negative
-value (usually C<EOF> which is usually -1) and set C<errno> on error.
-
-=over 4
-
-=item B<PerlIO_stdin()>, B<PerlIO_stdout()>, B<PerlIO_stderr()>
-
-Use these rather than C<stdin>, C<stdout>, C<stderr>. They are written
-to look like "function calls" rather than variables because this makes
-it easier to I<make them> function calls if platform cannot export data
-to loaded modules, or if (say) different "threads" might have different
-values.
-
-=item B<PerlIO_open(path, mode)>, B<PerlIO_fdopen(fd,mode)>
-
-These correspond to fopen()/fdopen() and the arguments are the same.
-Return C<NULL> and set C<errno> if there is an error. There may be an
-implementation limit on the number of open handles, which may be lower
-than the limit on the number of open files - C<errno> may not be set
-when C<NULL> is returned if this limit is exceeded.
-
-=item B<PerlIO_reopen(path,mode,f)>
-
-While this currently exists in all three implementations perl itself
-does not use it. I<As perl does not use it, it is not well tested.>
-
-Perl prefers to C<dup> the new low-level descriptor to the descriptor
-used by the existing PerlIO. This may become the behaviour of this
-function in the future.
-
-=item B<PerlIO_printf(f,fmt,...)>, B<PerlIO_vprintf(f,fmt,a)>
-
-These are fprintf()/vfprintf() equivalents.
-
-=item B<PerlIO_stdoutf(fmt,...)>
-
-This is printf() equivalent. printf is #defined to this function,
-so it is (currently) legal to use C<printf(fmt,...)> in perl sources.
-
-=item B<PerlIO_read(f,buf,count)>, B<PerlIO_write(f,buf,count)>
-
-These correspond functionally to fread() and fwrite() but the
-arguments and return values are different. The PerlIO_read() and
-PerlIO_write() signatures have been modeled on the more sane low level
-read() and write() functions instead: The "file" argument is passed
-first, there is only one "count", and the return value can distinguish
-between error and C<EOF>.
-
-Returns a byte count if successful (which may be zero or
-positive), returns negative value and sets C<errno> on error.
-Depending on implementation C<errno> may be C<EINTR> if operation was
-interrupted by a signal.
-
-=item B<PerlIO_close(f)>
-
-Depending on implementation C<errno> may be C<EINTR> if operation was
-interrupted by a signal.
-
-=item B<PerlIO_puts(f,s)>, B<PerlIO_putc(f,c)>
-
-These correspond to fputs() and fputc().
-Note that arguments have been revised to have "file" first.
-
-=item B<PerlIO_ungetc(f,c)>
-
-This corresponds to ungetc(). Note that arguments have been revised
-to have "file" first. Arranges that next read operation will return
-the byte B<c>. Despite the implied "character" in the name only
-values in the range 0..0xFF are defined. Returns the byte B<c> on
-success or -1 (C<EOF>) on error. The number of bytes that can be
-"pushed back" may vary, only 1 character is certain, and then only if
-it is the last character that was read from the handle.
-
-=item B<PerlIO_getc(f)>
-
-This corresponds to getc().
-Despite the c in the name only byte range 0..0xFF is supported.
-Returns the character read or -1 (C<EOF>) on error.
-
-=item B<PerlIO_eof(f)>
-
-This corresponds to feof(). Returns a true/false indication of
-whether the handle is at end of file. For terminal devices this may
-or may not be "sticky" depending on the implementation. The flag is
-cleared by PerlIO_seek(), or PerlIO_rewind().
-
-=item B<PerlIO_error(f)>
-
-This corresponds to ferror(). Returns a true/false indication of
-whether there has been an IO error on the handle.
-
-=item B<PerlIO_fileno(f)>
-
-This corresponds to fileno(), note that on some platforms, the meaning
-of "fileno" may not match Unix. Returns -1 if the handle has no open
-descriptor associated with it.
-
-=item B<PerlIO_clearerr(f)>
-
-This corresponds to clearerr(), i.e., clears 'error' and (usually)
-'eof' flags for the "stream". Does not return a value.
-
-=item B<PerlIO_flush(f)>
-
-This corresponds to fflush(). Sends any buffered write data to the
-underlying file. If called with C<NULL> this may flush all open
-streams (or core dump with some USE_STDIO implementations). Calling
-on a handle open for read only, or on which last operation was a read
-of some kind may lead to undefined behaviour on some USE_STDIO
-implementations. The USE_PERLIO (layers) implementation tries to
-behave better: it flushes all open streams when passed C<NULL>, and
-attempts to retain data on read streams either in the buffer or by
-seeking the handle to the current logical position.
-
-=item B<PerlIO_seek(f,offset,whence)>
-
-This corresponds to fseek(). Sends buffered write data to the
-underlying file, or discards any buffered read data, then positions
-the file descriptor as specified by B<offset> and B<whence> (sic).
-This is the correct thing to do when switching between read and write
-on the same handle (see issues with PerlIO_flush() above). Offset is
-of type C<Off_t> which is a perl Configure value which may not be same
-as stdio's C<off_t>.
-
-=item B<PerlIO_tell(f)>
-
-This corresponds to ftell(). Returns the current file position, or
-(Off_t) -1 on error. May just return value system "knows" without
-making a system call or checking the underlying file descriptor (so
-use on shared file descriptors is not safe without a
-PerlIO_seek()). Return value is of type C<Off_t> which is a perl
-Configure value which may not be same as stdio's C<off_t>.
-
-=item B<PerlIO_getpos(f,p)>, B<PerlIO_setpos(f,p)>
-
-These correspond (loosely) to fgetpos() and fsetpos(). Rather than
-stdio's Fpos_t they expect a "Perl Scalar Value" to be passed. What is
-stored there should be considered opaque. The layout of the data may
-vary from handle to handle. When not using stdio or if platform does
-not have the stdio calls then they are implemented in terms of
-PerlIO_tell() and PerlIO_seek().
-
-=item B<PerlIO_rewind(f)>
-
-This corresponds to rewind(). It is usually defined as being
-
- PerlIO_seek(f,(Off_t)0L, SEEK_SET);
- PerlIO_clearerr(f);
-
-=item B<PerlIO_tmpfile()>
-
-This corresponds to tmpfile(), i.e., returns an anonymous PerlIO or
-NULL on error. The system will attempt to automatically delete the
-file when closed. On Unix the file is usually C<unlink>-ed just after
-it is created so it does not matter how it gets closed. On other
-systems the file may only be deleted if closed via PerlIO_close()
-and/or the program exits via C<exit>. Depending on the implementation
-there may be "race conditions" which allow other processes access to
-the file, though in general it will be safer in this regard than
-ad. hoc. schemes.
-
-=item B<PerlIO_setlinebuf(f)>
-
-This corresponds to setlinebuf(). Does not return a value. What
-constitutes a "line" is implementation dependent but usually means
-that writing "\n" flushes the buffer. What happens with things like
-"this\nthat" is uncertain. (Perl core uses it I<only> when "dumping";
-it has nothing to do with $| auto-flush.)
-
-=back
-
-=head2 Co-existence with stdio
-
-There is outline support for co-existence of PerlIO with stdio.
-Obviously if PerlIO is implemented in terms of stdio there is no
-problem. However in other cases then mechanisms must exist to create a
-FILE * which can be passed to library code which is going to use stdio
-calls.
-
-The first step is to add this line:
-
- #define PERLIO_NOT_STDIO 0
-
-I<before> including any perl header files. (This will probably become
-the default at some point). That prevents "perlio.h" from attempting
-to #define stdio functions onto PerlIO functions.
-
-XS code is probably better using "typemap" if it expects FILE *
-arguments. The standard typemap will be adjusted to comprehend any
-changes in this area.
-
-=over 4
-
-=item B<PerlIO_importFILE(f,mode)>
-
-Used to get a PerlIO * from a FILE *.
-
-The mode argument should be a string as would be passed to
-fopen/PerlIO_open. If it is NULL then - for legacy support - the code
-will (depending upon the platform and the implementation) either
-attempt to empirically determine the mode in which I<f> is open, or
-use "r+" to indicate a read/write stream.
-
-Once called the FILE * should I<ONLY> be closed by calling
-C<PerlIO_close()> on the returned PerlIO *.
-
-The PerlIO is set to textmode. Use PerlIO_binmode if this is
-not the desired mode.
-
-This is B<not> the reverse of PerlIO_exportFILE().
-
-=item B<PerlIO_exportFILE(f,mode)>
-
-Given a PerlIO * create a 'native' FILE * suitable for passing to code
-expecting to be compiled and linked with ANSI C I<stdio.h>. The mode
-argument should be a string as would be passed to fopen/PerlIO_open.
-If it is NULL then - for legacy support - the FILE * is opened in same
-mode as the PerlIO *.
-
-The fact that such a FILE * has been 'exported' is recorded, (normally
-by pushing a new :stdio "layer" onto the PerlIO *), which may affect
-future PerlIO operations on the original PerlIO *. You should not
-call C<fclose()> on the file unless you call C<PerlIO_releaseFILE()>
-to disassociate it from the PerlIO *. (Do not use PerlIO_importFILE()
-for doing the disassociation.)
-
-Calling this function repeatedly will create a FILE * on each call
-(and will push an :stdio layer each time as well).
-
-=item B<PerlIO_releaseFILE(p,f)>
-
-Calling PerlIO_releaseFILE informs PerlIO that all use of FILE * is
-complete. It is removed from the list of 'exported' FILE *s, and the
-associated PerlIO * should revert to its original behaviour.
-
-Use this to disassociate a file from a PerlIO * that was associated
-using PerlIO_exportFILE().
-
-=item B<PerlIO_findFILE(f)>
-
-Returns a native FILE * used by a stdio layer. If there is none, it
-will create one with PerlIO_exportFILE. In either case the FILE *
-should be considered as belonging to PerlIO subsystem and should
-only be closed by calling C<PerlIO_close()>.
-
-
-=back
-
-=head2 "Fast gets" Functions
-
-In addition to standard-like API defined so far above there is an
-"implementation" interface which allows perl to get at internals of
-PerlIO. The following calls correspond to the various FILE_xxx macros
-determined by Configure - or their equivalent in other
-implementations. This section is really of interest to only those
-concerned with detailed perl-core behaviour, implementing a PerlIO
-mapping or writing code which can make use of the "read ahead" that
-has been done by the IO system in the same way perl does. Note that
-any code that uses these interfaces must be prepared to do things the
-traditional way if a handle does not support them.
-
-=over 4
-
-=item B<PerlIO_fast_gets(f)>
-
-Returns true if implementation has all the interfaces required to
-allow perl's C<sv_gets> to "bypass" normal IO mechanism. This can
-vary from handle to handle.
-
- PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \
- PerlIO_canset_cnt(f) && \
- 'Can set pointer into buffer'
-
-=item B<PerlIO_has_cntptr(f)>
-
-Implementation can return pointer to current position in the "buffer"
-and a count of bytes available in the buffer. Do not use this - use
-PerlIO_fast_gets.
-
-=item B<PerlIO_get_cnt(f)>
-
-Return count of readable bytes in the buffer. Zero or negative return
-means no more bytes available.
-
-=item B<PerlIO_get_ptr(f)>
-
-Return pointer to next readable byte in buffer, accessing via the
-pointer (dereferencing) is only safe if PerlIO_get_cnt() has returned
-a positive value. Only positive offsets up to value returned by
-PerlIO_get_cnt() are allowed.
-
-=item B<PerlIO_set_ptrcnt(f,p,c)>
-
-Set pointer into buffer, and a count of bytes still in the
-buffer. Should be used only to set pointer to within range implied by
-previous calls to C<PerlIO_get_ptr> and C<PerlIO_get_cnt>. The two
-values I<must> be consistent with each other (implementation may only
-use one or the other or may require both).
-
-=item B<PerlIO_canset_cnt(f)>
-
-Implementation can adjust its idea of number of bytes in the buffer.
-Do not use this - use PerlIO_fast_gets.
-
-=item B<PerlIO_set_cnt(f,c)>
-
-Obscure - set count of bytes in the buffer. Deprecated. Only usable
-if PerlIO_canset_cnt() returns true. Currently used in only doio.c to
-force count less than -1 to -1. Perhaps should be PerlIO_set_empty or
-similar. This call may actually do nothing if "count" is deduced from
-pointer and a "limit". Do not use this - use PerlIO_set_ptrcnt().
-
-=item B<PerlIO_has_base(f)>
-
-Returns true if implementation has a buffer, and can return pointer
-to whole buffer and its size. Used by perl for B<-T> / B<-B> tests.
-Other uses would be very obscure...
-
-=item B<PerlIO_get_base(f)>
-
-Return I<start> of buffer. Access only positive offsets in the buffer
-up to the value returned by PerlIO_get_bufsiz().
-
-=item B<PerlIO_get_bufsiz(f)>
-
-Return the I<total number of bytes> in the buffer, this is neither the
-number that can be read, nor the amount of memory allocated to the
-buffer. Rather it is what the operating system and/or implementation
-happened to C<read()> (or whatever) last time IO was requested.
-
-=back
-
-=head2 Other Functions
-
-=over 4
-
-=item PerlIO_apply_layers(f,mode,layers)
-
-The new interface to the USE_PERLIO implementation. The layers ":crlf"
-and ":raw" are only ones allowed for other implementations and those
-are silently ignored. (As of perl5.8 ":raw" is deprecated.) Use
-PerlIO_binmode() below for the portable case.
-
-=item PerlIO_binmode(f,ptype,imode,layers)
-
-The hook used by perl's C<binmode> operator.
-B<ptype> is perl's character for the kind of IO:
-
-=over 8
-
-=item 'E<lt>' read
-
-=item 'E<gt>' write
-
-=item '+' read/write
-
-=back
-
-B<imode> is C<O_BINARY> or C<O_TEXT>.
-
-B<layers> is a string of layers to apply, only ":crlf" makes sense in
-the non USE_PERLIO case. (As of perl5.8 ":raw" is deprecated in favour
-of passing NULL.)
-
-Portable cases are:
-
- PerlIO_binmode(f,ptype,O_BINARY,NULL);
-and
- PerlIO_binmode(f,ptype,O_TEXT,":crlf");
-
-On Unix these calls probably have no effect whatsoever. Elsewhere
-they alter "\n" to CR,LF translation and possibly cause a special text
-"end of file" indicator to be written or honoured on read. The effect
-of making the call after doing any IO to the handle depends on the
-implementation. (It may be ignored, affect any data which is already
-buffered as well, or only apply to subsequent data.)
-
-=item PerlIO_debug(fmt,...)
-
-PerlIO_debug is a printf()-like function which can be used for
-debugging. No return value. Its main use is inside PerlIO where using
-real printf, warn() etc. would recursively call PerlIO and be a
-problem.
-
-PerlIO_debug writes to the file named by $ENV{'PERLIO_DEBUG'} typical
-use might be
-
- Bourne shells (sh, ksh, bash, zsh, ash, ...):
- PERLIO_DEBUG=/dev/tty ./perl somescript some args
-
- Csh/Tcsh:
- setenv PERLIO_DEBUG /dev/tty
- ./perl somescript some args
-
- If you have the "env" utility:
- env PERLIO_DEBUG=/dev/tty ./perl somescript some args
-
- Win32:
- set PERLIO_DEBUG=CON
- perl somescript some args
-
-If $ENV{'PERLIO_DEBUG'} is not set PerlIO_debug() is a no-op.
-
-=back
diff --git a/Master/tlpkg/tlperl/lib/pods/perlartistic.pod b/Master/tlpkg/tlperl/lib/pods/perlartistic.pod
deleted file mode 100644
index 63813ff4fb9..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlartistic.pod
+++ /dev/null
@@ -1,224 +0,0 @@
-
-=head1 NAME
-
-perlartistic - the Perl Artistic License
-
-=head1 SYNOPSIS
-
- You can refer to this document in Pod via "L<perlartistic>"
- Or you can see this document by entering "perldoc perlartistic"
-
-=head1 DESCRIPTION
-
-Perl is free software; you can redistribute it and/or modify
-it under the terms of either:
-
- a) the GNU General Public License as published by the Free
- Software Foundation; either version 1, or (at your option) any
- later version, or
-
- b) the "Artistic License" which comes with this Kit.
-
-This is B<"The Artistic License">.
-It's here so that modules, programs, etc., that want to declare
-this as their distribution license can link to it.
-
-For the GNU General Public License, see L<perlgpl>.
-
-=head1 The "Artistic License"
-
-=head2 Preamble
-
-The intent of this document is to state the conditions under which a
-Package may be copied, such that the Copyright Holder maintains some
-semblance of artistic control over the development of the package,
-while giving the users of the package the right to use and distribute
-the Package in a more-or-less customary fashion, plus the right to make
-reasonable modifications.
-
-=head2 Definitions
-
-=over
-
-=item "Package"
-
-refers to the collection of files distributed by the
-Copyright Holder, and derivatives of that collection of files created
-through textual modification.
-
-=item "Standard Version"
-
-refers to such a Package if it has not been
-modified, or has been modified in accordance with the wishes of the
-Copyright Holder as specified below.
-
-=item "Copyright Holder"
-
-is whoever is named in the copyright or
-copyrights for the package.
-
-=item "You"
-
-is you, if you're thinking about copying or distributing this Package.
-
-=item "Reasonable copying fee"
-
-is whatever you can justify on the basis
-of media cost, duplication charges, time of people involved, and so on.
-(You will not be required to justify it to the Copyright Holder, but
-only to the computing community at large as a market that must bear the
-fee.)
-
-=item "Freely Available"
-
-means that no fee is charged for the item
-itself, though there may be fees involved in handling the item. It also
-means that recipients of the item may redistribute it under the same
-conditions they received it.
-
-=back
-
-=head2 Conditions
-
-=over
-
-=item 1.
-
-You may make and give away verbatim copies of the source form of the
-Standard Version of this Package without restriction, provided that you
-duplicate all of the original copyright notices and associated disclaimers.
-
-=item 2.
-
-You may apply bug fixes, portability fixes and other modifications
-derived from the Public Domain or from the Copyright Holder. A Package
-modified in such a way shall still be considered the Standard Version.
-
-=item 3.
-
-You may otherwise modify your copy of this Package in any way, provided
-that you insert a prominent notice in each changed file stating how and
-when you changed that file, and provided that you do at least ONE of the
-following:
-
-=over
-
-=item a)
-
-place your modifications in the Public Domain or otherwise make them
-Freely Available, such as by posting said modifications to Usenet or an
-equivalent medium, or placing the modifications on a major archive site
-such as uunet.uu.net, or by allowing the Copyright Holder to include
-your modifications in the Standard Version of the Package.
-
-=item b)
-
-use the modified Package only within your corporation or organization.
-
-=item c)
-
-rename any non-standard executables so the names do not conflict with
-standard executables, which must also be provided, and provide a
-separate manual page for each non-standard executable that clearly
-documents how it differs from the Standard Version.
-
-=item d)
-
-make other distribution arrangements with the Copyright Holder.
-
-=back
-
-=item 4.
-
-You may distribute the programs of this Package in object code or
-executable form, provided that you do at least ONE of the following:
-
-=over
-
-=item a)
-
-distribute a Standard Version of the executables and library files,
-together with instructions (in the manual page or equivalent) on where
-to get the Standard Version.
-
-=item b)
-
-accompany the distribution with the machine-readable source of the
-Package with your modifications.
-
-=item c)
-
-give non-standard executables non-standard names, and clearly
-document the differences in manual pages (or equivalent), together with
-instructions on where to get the Standard Version.
-
-=item d)
-
-make other distribution arrangements with the Copyright Holder.
-
-=back
-
-=item 5.
-
-You may charge a reasonable copying fee for any distribution of this
-Package. You may charge any fee you choose for support of this
-Package. You may not charge a fee for this Package itself. However,
-you may distribute this Package in aggregate with other (possibly
-commercial) programs as part of a larger (possibly commercial) software
-distribution provided that you do not advertise this Package as a
-product of your own. You may embed this Package's interpreter within
-an executable of yours (by linking); this shall be construed as a mere
-form of aggregation, provided that the complete Standard Version of the
-interpreter is so embedded.
-
-=item 6.
-
-The scripts and library files supplied as input to or produced as
-output from the programs of this Package do not automatically fall
-under the copyright of this Package, but belong to whoever generated
-them, and may be sold commercially, and may be aggregated with this
-Package. If such scripts or library files are aggregated with this
-Package via the so-called "undump" or "unexec" methods of producing a
-binary executable image, then distribution of such an image shall
-neither be construed as a distribution of this Package nor shall it
-fall under the restrictions of Paragraphs 3 and 4, provided that you do
-not represent such an executable image as a Standard Version of this
-Package.
-
-=item 7.
-
-C subroutines (or comparably compiled subroutines in other
-languages) supplied by you and linked into this Package in order to
-emulate subroutines and variables of the language defined by this
-Package shall not be considered part of this Package, but are the
-equivalent of input as in Paragraph 6, provided these subroutines do
-not change the language in any way that would cause it to fail the
-regression tests for the language.
-
-=item 8.
-
-Aggregation of this Package with a commercial distribution is always
-permitted provided that the use of this Package is embedded; that is,
-when no overt attempt is made to make this Package's interfaces visible
-to the end user of the commercial distribution. Such use shall not be
-construed as a distribution of this Package.
-
-=item 9.
-
-The name of the Copyright Holder may not be used to endorse or promote
-products derived from this software without specific prior written permission.
-
-
-=item 10.
-
-THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
-IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
-WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
-
-=back
-
-The End
-
-=cut
-
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlbeos.pod b/Master/tlpkg/tlperl/lib/pods/perlbeos.pod
deleted file mode 100644
index c72c2293a07..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlbeos.pod
+++ /dev/null
@@ -1,109 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you see.
-It is written in the POD format (see pod/perlpod.pod) which is specially
-designed to be readable as is.
-
-=head1 NAME
-
-perlbeos - Perl version 5.8+ on BeOS
-
-=head1 DESCRIPTION
-
-This file contains instructions how to build Perl under BeOS and lists
-known problems.
-
-=head1 BUILD AND INSTALL
-
-=head2 Requirements
-
-I have built and tested Perl 5.8.6 and 5.9.1 under BeOS R5 x86 net server.
-I can't say anything with regard to PPC. Since Perl 5.8.0 had been released
-for BeOS BONE, I suspect, there is a good chance, that it still compiles on
-a BONE system. The only change I've made, that affects BONE systems is the
-recognition of whether it is a BONE system or not in F<hints/beos.sh>. Now
-network socket support should remain enabled on BONE systems. This might
-as well break the build, though.
-
-As more recent versions of autoconf require flock() support, I wrote a flock()
-emulation (flock_server) and released it on BeBits:
-
- http://www.bebits.com/app/4030
-
-If you want to build a Perl with flock() support, you have to install this
-package first.
-
-=head2 Configure
-
-With flock() support:
-
- CFLAGS=-I/path/to/flock/server/headers ./configure.gnu \
- --prefix=/boot/home/config
-
-Replace C</path/to/flock/server/headers> with the path to the directory
-containing the C<flock.h> header.
-
-Without flock() support:
-
- ./configure.gnu --prefix=/boot/home/config
-
-=head2 Build
-
-With flock() support:
-
- make LDLOADLIBS="-lnet -lflock"
-
-Without flock() support:
-
- make LDLOADLIBS="-lnet"
-
-C<-lnet> is needed on net server systems only and if the compiler doesn't
-add it automatically (Be's R5 gcc does, Oliver Tappe's gcc 2.95.3 does not).
-
-=head2 Install
-
-Install all perl files:
-
- make install
-
-Create a symlink for libperl:
-
- cd ~/config/lib; ln -s perl5/5.8.6/BePC-beos/CORE/libperl.so .
-
-Replace C<5.8.6> with your respective version of Perl.
-
-=head1 KNOWN PROBLEMS
-
-=over 4
-
-=item *
-
-Network socket support is disabled for BeOS R5 net server. I didn't dare yet
-to try enabling it and see what problems occur.
-
-=item *
-
-The LFS (large file support) tests (F<t/op/lfs> and F<xt/Fcntl/t/syslfs>) are
-disabled as seeking beyond 2 GB is broken according to jhi@iki.fi who was the
-last one checking the BeOS port and updating this file before me. Haven't
-checked this myself.
-
-=item *
-
-The F<t/io/fflush> test fails at #6. As far as I can tell, this is caused by
-a bug in the BeOS pipes implementation that occurs when starting other child
-processes. In the particular test case a C<system("perl -e 0")> flushes the
-stdout pipe of another child process.
-
-=item *
-
-The F<ext/POSIX/t/waitpid> test fails at #1. After all child processes are
-gone BeOS' waitpid(-1,...) returns 0 instead of -1 (as it should). No idea
-how to fix this.
-
-=back
-
-=head1 CONTACT
-
-For BeOS specifics problems feel free to mail to:
-Ingo Weinhold <bonefish@cs.tu-berlin.de>
-
-Last update: 2004-12-16
diff --git a/Master/tlpkg/tlperl/lib/pods/perlbook.pod b/Master/tlpkg/tlperl/lib/pods/perlbook.pod
deleted file mode 100644
index 5ed6b328748..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlbook.pod
+++ /dev/null
@@ -1,292 +0,0 @@
-=head1 NAME
-
-perlbook - Books about and related to Perl
-
-=head1 DESCRIPTION
-
-There are many books on Perl and Perl-related. A few of these are
-good, some are OK, but many aren't worth your money. There is a list
-of these books, some with extensive reviews, at http://books.perl.org/
-. We list some of the books here, and while listing a book implies our
-endorsement, don't think that not including a book means anything.
-
-Most of these books are available online through Safari Books Online
-( http://safaribooksonline.com/ ).
-
-=head2 The most popular books
-
-The major reference book on Perl, written by the creator of Perl, is
-I<Programming Perl>:
-
-=over 4
-
-=item I<Programming Perl> (the "Camel Book"):
-
- by Larry Wall, Tom Christiansen, and Jon Orwant
- ISBN 978-0-596-00027-1 [3rd edition July 2000]
- http://oreilly.com/catalog/9780596000271/
-
-=back
-
-The Ram is a cookbook with hundreds of examples of using Perl to
-accomplish specific tasks:
-
-=over 4
-
-=item I<The Perl Cookbook> (the "Ram Book"):
-
- by Tom Christiansen and Nathan Torkington,
- with Foreword by Larry Wall
- ISBN 978-0-596-00313-5 [2nd Edition August 2003]
- http://oreilly.com/catalog/9780596003135/
-
-=back
-
-If you want to learn the basics of Perl, you might start with the
-Llama book, which assumes that you already know a little about
-programming:
-
-=over 4
-
-=item I<Learning Perl> (the "Llama Book")
-
- by Randal L. Schwartz, Tom Phoenix, and brian d foy
- ISBN 978-0-596-52011-3 [5th edition June 2008]
- http://oreilly.com/catalog/9780596520113
-
-=back
-
-The tutorial started in the Llama continues in the Alpaca, which
-introduces the intermediate features of references, data structures,
-object-oriented programming, and modules:
-
-=over 4
-
-=item I<Intermediate Perl> (the "Alpaca Book")
-
- by Randal L. Schwartz and brian d foy, with Tom Phoenix
- foreword by Damian Conway
- ISBN 978-0-596-00478-1 [1st edition March 2006]
- http://oreilly.com/catalog/9780596004781/
-
-=back
-
-=head2 References
-
-You might want to keep these desktop references close by your keyboard:
-
-=over 4
-
-=item I<Perl 5 Pocket Reference>
-
- by Johan Vromans
- ISBN 978-0-596-00374-6 [4th edition July 2002]
- http://oreilly.com/catalog/9780596003746/
-
-=item I<Perl Debugger Pocket Reference>
-
- by Richard Foley
- ISBN 978-0-596-00503-0 [1st edition January 2004]
- http://oreilly.com/catalog/9780596005030/
-
-=item I<Regular Expression Pocket Reference>
-
- by Tony Stubblebine
- ISBN 978-0-596-51427-3 [July 2007]
- http://oreilly.com/catalog/9780596514273/
-
-=back
-
-=head2 Tutorials
-
-=over 4
-
-=item I<Beginning Perl>
-
- by James Lee
- ISBN 1-59059-391-X [3rd edition April 2010]
- http://www.apress.com/9781430227939
-
-=item I<Learning Perl>
-
- by Randal L. Schwartz, Tom Phoenix, and brian d foy
- ISBN 978-0-596-52010-6 [5th edition June 2008]
- http://oreilly.com/catalog/9780596520106
-
-=item I<Intermediate Perl> (the "Alpaca Book")
-
- by Randal L. Schwartz and brian d foy, with Tom Phoenix
- foreword by Damian Conway
- ISBN 0-596-10206-2 [1st edition March 2006]
- http://oreilly.com/catalog/9780596102067
-
-=item I<Mastering Perl>
-
- by brian d foy
- ISBN 978-0-596-10206-7 [1st edition July 2007]
- http://www.oreilly.com/catalog/9780596527242
-
-=item I<Effective Perl Programming>
-
- by Joseph N. Hall, Joshua A. McAdams, brian d foy
- ISBN 0-321-49694-9 [2nd edition 2010]
- http://www.effectiveperlprogramming.com/
-
-=back
-
-=head2 Task-Oriented
-
-=over 4
-
-=item I<Writing Perl Modules for CPAN>
-
- by Sam Tregar
- ISBN 1-59059-018-X [1st edition August 2002]
- http://www.apress.com/9781590590188
-
-=item I<The Perl Cookbook>
-
- by Tom Christiansen and Nathan Torkington
- with foreword by Larry Wall
- ISBN 1-56592-243-3 [2nd edition August 2003]
- http://oreilly.com/catalog/9780596003135
-
-=item I<Automating System Administration with Perl>
-
- by David N. Blank-Edelman
- ISBN 978-0-596-00639-6 [2nd edition May 2009]
- http://oreilly.com/catalog/9780596006396
-
-=item I<Real World SQL Server Administration with Perl>
-
- by Linchi Shea
- ISBN 1-59059-097-X [1st edition July 2003]
- http://www.apress.com/9781590590973
-
-=back
-
-=head2 Special Topics
-
-=over 4
-
-=item I<Regular Expressions Cookbook>
-
- by Jan Goyvaerts and Steven Levithan
- ISBN 978-0-596-52069-4 [May 2009]
- http://oreilly.com/catalog/9780596520694
-
-=item I<Programming the Perl DBI>
-
- by Tim Bunce and Alligator Descartes
- ISBN 978-1-56592-699-8 [February 2000]
- http://oreilly.com/catalog/9781565926998
-
-=item I<Perl Best Practices>
-
- by Damian Conway
- ISBN: 978-0-596-00173-5 [1st edition July 2005]
- http://oreilly.com/catalog/9780596001735
-
-=item I<Higher-Order Perl>
-
- by Mark-Jason Dominus
- ISBN: 1-55860-701-3 [1st edition March 2005]
- http://hop.perl.plover.com/
-
-=item I<Mastering Regular Expressions>
-
- by Jeffrey E. F. Friedl
- ISBN 978-0-596-52812-6 [3rd edition August 2006]
- http://oreilly.com/catalog/9780596528126
-
-=item I<Network Programming with Perl>
-
- by Lincoln Stein
- ISBN 0-201-61571-1 [1st edition 2001]
- http://www.pearsonhighered.com/educator/product/Network-Programming-with-Perl/9780201615715.page
-
-=item I<Perl Template Toolkit>
-
- by Darren Chamberlain, Dave Cross, and Andy Wardley
- ISBN 978-0-596-00476-7 [December 2003]
- http://oreilly.com/catalog/9780596004767
-
-=item I<Object Oriented Perl>
-
- by Damian Conway
- with foreword by Randal L. Schwartz
- ISBN 1-884777-79-1 [1st edition August 1999]
- http://www.manning.com/conway/
-
-=item I<Data Munging with Perl>
-
- by Dave Cross
- ISBN 1-930110-00-6 [1st edition 2001]
- http://www.manning.com/cross
-
-=item I<Mastering Perl/Tk>
-
- by Steve Lidie and Nancy Walsh
- ISBN 978-1-56592-716-2 [1st edition January 2002]
- http://oreilly.com/catalog/9781565927162
-
-=item I<Extending and Embedding Perl>
-
- by Tim Jenness and Simon Cozens
- ISBN 1-930110-82-0 [1st edition August 2002]
- http://www.manning.com/jenness
-
-=item I<Pro Perl Debugging>
-
- by Richard Foley with Andy Lester
- ISBN 1-59059-454-1 [1st edition July 2005]
- http://www.apress.com/9781590594544
-
-=back
-
-=head2 Free (as in beer) books
-
-Some of these books are available as free downloads.
-
-I<Higher-Order Perl>: http://hop.perl.plover.com/
-
-=head2 Other interesting, non-Perl books
-
-You might notice several familiar Perl concepts in this collection of
-ACM columns from Jon Bentley. The similarity to the title of the major
-Perl book (which came later) is not completely accidental:
-
-=over 4
-
-=item I<Programming Pearls>
-
- by Jon Bentley
- ISBN 978-0-201-65788-3 [2 edition, October 1999]
-
-=item I<More Programming Pearls>
-
- by Jon Bentley
- ISBN 0-201-11889-0 [January 1988]
-
-=back
-
-=head2 A note on freshness
-
-Each version of Perl comes with the documentation that was current at
-the time of release. This poses a problem for content such as book
-lists. There are probably very nice books published after this list
-was included in your Perl release, and you can check the latest
-released version at http://perldoc.perl.org/perlbook.html .
-
-Some of the books we've listed appear almost ancient in internet
-scale, but we've included those books because they still describe the
-current way of doing things. Not everything in Perl changes every day.
-Many of the beginner-level books, too, go over basic features and
-techniques that are still valid today. In general though, we try to
-limit this list to books published in the past five years.
-
-=head2 Get your book listed
-
-If your Perl book isn't listed and you think it should be, let us know.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlboot.pod b/Master/tlpkg/tlperl/lib/pods/perlboot.pod
deleted file mode 100644
index 15b7117823a..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlboot.pod
+++ /dev/null
@@ -1,12 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perlboot - This document has been deleted
-
-=head1 DESCRIPTION
-
-For information on OO programming with Perl, please see L<perlootut>
-and L<perlobj>.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlbot.pod b/Master/tlpkg/tlperl/lib/pods/perlbot.pod
deleted file mode 100644
index 2e8c68021c3..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlbot.pod
+++ /dev/null
@@ -1,12 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perlbot - This document has been deleted
-
-=head1 DESCRIPTION
-
-For information on OO programming with Perl, please see L<perlootut>
-and L<perlobj>.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlbs2000.pod b/Master/tlpkg/tlperl/lib/pods/perlbs2000.pod
deleted file mode 100644
index 6868557d021..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlbs2000.pod
+++ /dev/null
@@ -1,241 +0,0 @@
-This document is written in pod format hence there are punctuation
-characters in odd places. Do not worry, you've apparently got the
-ASCII->EBCDIC translation worked out correctly. You can read more
-about pod in pod/perlpod.pod or the short summary in the INSTALL file.
-
-=head1 NAME
-
-perlbs2000 - building and installing Perl for BS2000.
-
-=head1 SYNOPSIS
-
-This document will help you Configure, build, test and install Perl
-on BS2000 in the POSIX subsystem.
-
-=head1 DESCRIPTION
-
-This is a ported perl for the POSIX subsystem in BS2000 VERSION OSD
-V3.1A or later. It may work on other versions, but we started porting
-and testing it with 3.1A and are currently using Version V4.0A.
-
-You may need the following GNU programs in order to install perl:
-
-=head2 gzip on BS2000
-
-We used version 1.2.4, which could be installed out of the box with
-one failure during 'make check'.
-
-=head2 bison on BS2000
-
-The yacc coming with BS2000 POSIX didn't work for us. So we had to
-use bison. We had to make a few changes to perl in order to use the
-pure (reentrant) parser of bison. We used version 1.25, but we had to
-add a few changes due to EBCDIC. See below for more details
-concerning yacc.
-
-=head2 Unpacking Perl Distribution on BS2000
-
-To extract an ASCII tar archive on BS2000 POSIX you need an ASCII
-filesystem (we used the mountpoint /usr/local/ascii for this). Now
-you extract the archive in the ASCII filesystem without
-I/O-conversion:
-
-cd /usr/local/ascii
-export IO_CONVERSION=NO
-gunzip < /usr/local/src/perl.tar.gz | pax -r
-
-You may ignore the error message for the first element of the archive
-(this doesn't look like a tar archive / skipping to next file...),
-it's only the directory which will be created automatically anyway.
-
-After extracting the archive you copy the whole directory tree to your
-EBCDIC filesystem. B<This time you use I/O-conversion>:
-
-cd /usr/local/src
-IO_CONVERSION=YES
-cp -r /usr/local/ascii/perl5.005_02 ./
-
-=head2 Compiling Perl on BS2000
-
-There is a "hints" file for BS2000 called hints.posix-bc (because
-posix-bc is the OS name given by `uname`) that specifies the correct
-values for most things. The major problem is (of course) the EBCDIC
-character set. We have german EBCDIC version.
-
-Because of our problems with the native yacc we used GNU bison to
-generate a pure (=reentrant) parser for perly.y. So our yacc is
-really the following script:
-
------8<-----/usr/local/bin/yacc-----8<-----
-#! /usr/bin/sh
-
-# Bison as a reentrant yacc:
-
-# save parameters:
-params=""
-while [[ $# -gt 1 ]]; do
- params="$params $1"
- shift
-done
-
-# add flag %pure_parser:
-
-tmpfile=/tmp/bison.$$.y
-echo %pure_parser > $tmpfile
-cat $1 >> $tmpfile
-
-# call bison:
-
-echo "/usr/local/bin/bison --yacc $params $1\t\t\t(Pure Parser)"
-/usr/local/bin/bison --yacc $params $tmpfile
-
-# cleanup:
-
-rm -f $tmpfile
------8<----------8<-----
-
-We still use the normal yacc for a2p.y though!!! We made a softlink
-called byacc to distinguish between the two versions:
-
-ln -s /usr/bin/yacc /usr/local/bin/byacc
-
-We build perl using GNU make. We tried the native make once and it
-worked too.
-
-=head2 Testing Perl on BS2000
-
-We still got a few errors during C<make test>. Some of them are the
-result of using bison. Bison prints I<parser error> instead of I<syntax
-error>, so we may ignore them. The following list shows
-our errors, your results may differ:
-
-op/numconvert.......FAILED tests 1409-1440
-op/regexp...........FAILED tests 483, 496
-op/regexp_noamp.....FAILED tests 483, 496
-pragma/overload.....FAILED tests 152-153, 170-171
-pragma/warnings.....FAILED tests 14, 82, 129, 155, 192, 205, 207
-lib/bigfloat........FAILED tests 351-352, 355
-lib/bigfltpm........FAILED tests 354-355, 358
-lib/complex.........FAILED tests 267, 487
-lib/dumper..........FAILED tests 43, 45
-Failed 11/231 test scripts, 95.24% okay. 57/10595 subtests failed, 99.46% okay.
-
-=head2 Installing Perl on BS2000
-
-We have no nroff on BS2000 POSIX (yet), so we ignored any errors while
-installing the documentation.
-
-
-=head2 Using Perl in the Posix-Shell of BS2000
-
-BS2000 POSIX doesn't support the shebang notation
-(C<#!/usr/local/bin/perl>), so you have to use the following lines
-instead:
-
-: # use perl
- eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
- if $running_under_some_shell;
-
-=head2 Using Perl in "native" BS2000
-
-We don't have much experience with this yet, but try the following:
-
-Copy your Perl executable to a BS2000 LLM using bs2cp:
-
-C<bs2cp /usr/local/bin/perl 'bs2:perl(perl,l)'>
-
-Now you can start it with the following (SDF) command:
-
-C</START-PROG FROM-FILE=*MODULE(PERL,PERL),PROG-MODE=*ANY,RUN-MODE=*ADV>
-
-First you get the BS2000 commandline prompt ('*'). Here you may enter
-your parameters, e.g. C<-e 'print "Hello World!\\n";'> (note the
-double backslash!) or C<-w> and the name of your Perl script.
-Filenames starting with C</> are searched in the Posix filesystem,
-others are searched in the BS2000 filesystem. You may even use
-wildcards if you put a C<%> in front of your filename (e.g. C<-w
-checkfiles.pl %*.c>). Read your C/C++ manual for additional
-possibilities of the commandline prompt (look for
-PARAMETER-PROMPTING).
-
-=head2 Floating point anomalies on BS2000
-
-There appears to be a bug in the floating point implementation on BS2000 POSIX
-systems such that calling int() on the product of a number and a small
-magnitude number is not the same as calling int() on the quotient of
-that number and a large magnitude number. For example, in the following
-Perl code:
-
- my $x = 100000.0;
- my $y = int($x * 1e-5) * 1e5; # '0'
- my $z = int($x / 1e+5) * 1e5; # '100000'
- print "\$y is $y and \$z is $z\n"; # $y is 0 and $z is 100000
-
-Although one would expect the quantities $y and $z to be the same and equal
-to 100000 they will differ and instead will be 0 and 100000 respectively.
-
-=head2 Using PerlIO and different encodings on ASCII and EBCDIC partitions
-
-Since version 5.8 Perl uses the new PerlIO on BS2000. This enables
-you using different encodings per IO channel. For example you may use
-
- use Encode;
- open($f, ">:encoding(ascii)", "test.ascii");
- print $f "Hello World!\n";
- open($f, ">:encoding(posix-bc)", "test.ebcdic");
- print $f "Hello World!\n";
- open($f, ">:encoding(latin1)", "test.latin1");
- print $f "Hello World!\n";
- open($f, ">:encoding(utf8)", "test.utf8");
- print $f "Hello World!\n";
-
-to get two files containing "Hello World!\n" in ASCII, EBCDIC, ISO
-Latin-1 (in this example identical to ASCII) respective UTF-EBCDIC (in
-this example identical to normal EBCDIC). See the documentation of
-Encode::PerlIO for details.
-
-As the PerlIO layer uses raw IO internally, all this totally ignores
-the type of your filesystem (ASCII or EBCDIC) and the IO_CONVERSION
-environment variable. If you want to get the old behavior, that the
-BS2000 IO functions determine conversion depending on the filesystem
-PerlIO still is your friend. You use IO_CONVERSION as usual and tell
-Perl, that it should use the native IO layer:
-
- export IO_CONVERSION=YES
- export PERLIO=stdio
-
-Now your IO would be ASCII on ASCII partitions and EBCDIC on EBCDIC
-partitions. See the documentation of PerlIO (without C<Encode::>!)
-for further possibilities.
-
-=head1 AUTHORS
-
-Thomas Dorner
-
-=head1 SEE ALSO
-
-L<INSTALL>, L<perlport>.
-
-=head2 Mailing list
-
-If you are interested in the VM/ESA, z/OS (formerly known as OS/390)
-and POSIX-BC (BS2000) ports of Perl then see the perl-mvs mailing list.
-To subscribe, send an empty message to perl-mvs-subscribe@perl.org.
-
-See also:
-
- http://lists.perl.org/list/perl-mvs.html
-
-There are web archives of the mailing list at:
-
- http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/
- http://archive.develooper.com/perl-mvs@perl.org/
-
-=head1 HISTORY
-
-This document was originally written by Thomas Dorner for the 5.005
-release of Perl.
-
-This document was podified for the 5.6 release of perl 11 July 2000.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlcall.pod b/Master/tlpkg/tlperl/lib/pods/perlcall.pod
deleted file mode 100644
index 4c7ffc9fb2a..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlcall.pod
+++ /dev/null
@@ -1,1936 +0,0 @@
-=head1 NAME
-
-perlcall - Perl calling conventions from C
-
-=head1 DESCRIPTION
-
-The purpose of this document is to show you how to call Perl subroutines
-directly from C, i.e., how to write I<callbacks>.
-
-Apart from discussing the C interface provided by Perl for writing
-callbacks the document uses a series of examples to show how the
-interface actually works in practice. In addition some techniques for
-coding callbacks are covered.
-
-Examples where callbacks are necessary include
-
-=over 5
-
-=item * An Error Handler
-
-You have created an XSUB interface to an application's C API.
-
-A fairly common feature in applications is to allow you to define a C
-function that will be called whenever something nasty occurs. What we
-would like is to be able to specify a Perl subroutine that will be
-called instead.
-
-=item * An Event-Driven Program
-
-The classic example of where callbacks are used is when writing an
-event driven program, such as for an X11 application. In this case
-you register functions to be called whenever specific events occur,
-e.g., a mouse button is pressed, the cursor moves into a window or a
-menu item is selected.
-
-=back
-
-Although the techniques described here are applicable when embedding
-Perl in a C program, this is not the primary goal of this document.
-There are other details that must be considered and are specific to
-embedding Perl. For details on embedding Perl in C refer to
-L<perlembed>.
-
-Before you launch yourself head first into the rest of this document,
-it would be a good idea to have read the following two documents--L<perlxs>
-and L<perlguts>.
-
-=head1 THE CALL_ FUNCTIONS
-
-Although this stuff is easier to explain using examples, you first need
-be aware of a few important definitions.
-
-Perl has a number of C functions that allow you to call Perl
-subroutines. They are
-
- I32 call_sv(SV* sv, I32 flags);
- I32 call_pv(char *subname, I32 flags);
- I32 call_method(char *methname, I32 flags);
- I32 call_argv(char *subname, I32 flags, register char **argv);
-
-The key function is I<call_sv>. All the other functions are
-fairly simple wrappers which make it easier to call Perl subroutines in
-special cases. At the end of the day they will all call I<call_sv>
-to invoke the Perl subroutine.
-
-All the I<call_*> functions have a C<flags> parameter which is
-used to pass a bit mask of options to Perl. This bit mask operates
-identically for each of the functions. The settings available in the
-bit mask are discussed in L<FLAG VALUES>.
-
-Each of the functions will now be discussed in turn.
-
-=over 5
-
-=item call_sv
-
-I<call_sv> takes two parameters. The first, C<sv>, is an SV*.
-This allows you to specify the Perl subroutine to be called either as a
-C string (which has first been converted to an SV) or a reference to a
-subroutine. The section, I<Using call_sv>, shows how you can make
-use of I<call_sv>.
-
-=item call_pv
-
-The function, I<call_pv>, is similar to I<call_sv> except it
-expects its first parameter to be a C char* which identifies the Perl
-subroutine you want to call, e.g., C<call_pv("fred", 0)>. If the
-subroutine you want to call is in another package, just include the
-package name in the string, e.g., C<"pkg::fred">.
-
-=item call_method
-
-The function I<call_method> is used to call a method from a Perl
-class. The parameter C<methname> corresponds to the name of the method
-to be called. Note that the class that the method belongs to is passed
-on the Perl stack rather than in the parameter list. This class can be
-either the name of the class (for a static method) or a reference to an
-object (for a virtual method). See L<perlobj> for more information on
-static and virtual methods and L<Using call_method> for an example
-of using I<call_method>.
-
-=item call_argv
-
-I<call_argv> calls the Perl subroutine specified by the C string
-stored in the C<subname> parameter. It also takes the usual C<flags>
-parameter. The final parameter, C<argv>, consists of a NULL-terminated
-list of C strings to be passed as parameters to the Perl subroutine.
-See I<Using call_argv>.
-
-=back
-
-All the functions return an integer. This is a count of the number of
-items returned by the Perl subroutine. The actual items returned by the
-subroutine are stored on the Perl stack.
-
-As a general rule you should I<always> check the return value from
-these functions. Even if you are expecting only a particular number of
-values to be returned from the Perl subroutine, there is nothing to
-stop someone from doing something unexpected--don't say you haven't
-been warned.
-
-=head1 FLAG VALUES
-
-The C<flags> parameter in all the I<call_*> functions is one of G_VOID,
-G_SCALAR, or G_ARRAY, which indicate the call context, OR'ed together
-with a bit mask of any combination of the other G_* symbols defined below.
-
-=head2 G_VOID
-
-Calls the Perl subroutine in a void context.
-
-This flag has 2 effects:
-
-=over 5
-
-=item 1.
-
-It indicates to the subroutine being called that it is executing in
-a void context (if it executes I<wantarray> the result will be the
-undefined value).
-
-=item 2.
-
-It ensures that nothing is actually returned from the subroutine.
-
-=back
-
-The value returned by the I<call_*> function indicates how many
-items have been returned by the Perl subroutine--in this case it will
-be 0.
-
-
-=head2 G_SCALAR
-
-Calls the Perl subroutine in a scalar context. This is the default
-context flag setting for all the I<call_*> functions.
-
-This flag has 2 effects:
-
-=over 5
-
-=item 1.
-
-It indicates to the subroutine being called that it is executing in a
-scalar context (if it executes I<wantarray> the result will be false).
-
-=item 2.
-
-It ensures that only a scalar is actually returned from the subroutine.
-The subroutine can, of course, ignore the I<wantarray> and return a
-list anyway. If so, then only the last element of the list will be
-returned.
-
-=back
-
-The value returned by the I<call_*> function indicates how many
-items have been returned by the Perl subroutine - in this case it will
-be either 0 or 1.
-
-If 0, then you have specified the G_DISCARD flag.
-
-If 1, then the item actually returned by the Perl subroutine will be
-stored on the Perl stack - the section I<Returning a Scalar> shows how
-to access this value on the stack. Remember that regardless of how
-many items the Perl subroutine returns, only the last one will be
-accessible from the stack - think of the case where only one value is
-returned as being a list with only one element. Any other items that
-were returned will not exist by the time control returns from the
-I<call_*> function. The section I<Returning a list in a scalar
-context> shows an example of this behavior.
-
-
-=head2 G_ARRAY
-
-Calls the Perl subroutine in a list context.
-
-As with G_SCALAR, this flag has 2 effects:
-
-=over 5
-
-=item 1.
-
-It indicates to the subroutine being called that it is executing in a
-list context (if it executes I<wantarray> the result will be true).
-
-=item 2.
-
-It ensures that all items returned from the subroutine will be
-accessible when control returns from the I<call_*> function.
-
-=back
-
-The value returned by the I<call_*> function indicates how many
-items have been returned by the Perl subroutine.
-
-If 0, then you have specified the G_DISCARD flag.
-
-If not 0, then it will be a count of the number of items returned by
-the subroutine. These items will be stored on the Perl stack. The
-section I<Returning a list of values> gives an example of using the
-G_ARRAY flag and the mechanics of accessing the returned items from the
-Perl stack.
-
-=head2 G_DISCARD
-
-By default, the I<call_*> functions place the items returned from
-by the Perl subroutine on the stack. If you are not interested in
-these items, then setting this flag will make Perl get rid of them
-automatically for you. Note that it is still possible to indicate a
-context to the Perl subroutine by using either G_SCALAR or G_ARRAY.
-
-If you do not set this flag then it is I<very> important that you make
-sure that any temporaries (i.e., parameters passed to the Perl
-subroutine and values returned from the subroutine) are disposed of
-yourself. The section I<Returning a Scalar> gives details of how to
-dispose of these temporaries explicitly and the section I<Using Perl to
-dispose of temporaries> discusses the specific circumstances where you
-can ignore the problem and let Perl deal with it for you.
-
-=head2 G_NOARGS
-
-Whenever a Perl subroutine is called using one of the I<call_*>
-functions, it is assumed by default that parameters are to be passed to
-the subroutine. If you are not passing any parameters to the Perl
-subroutine, you can save a bit of time by setting this flag. It has
-the effect of not creating the C<@_> array for the Perl subroutine.
-
-Although the functionality provided by this flag may seem
-straightforward, it should be used only if there is a good reason to do
-so. The reason for being cautious is that, even if you have specified
-the G_NOARGS flag, it is still possible for the Perl subroutine that
-has been called to think that you have passed it parameters.
-
-In fact, what can happen is that the Perl subroutine you have called
-can access the C<@_> array from a previous Perl subroutine. This will
-occur when the code that is executing the I<call_*> function has
-itself been called from another Perl subroutine. The code below
-illustrates this
-
- sub fred
- { print "@_\n" }
-
- sub joe
- { &fred }
-
- &joe(1,2,3);
-
-This will print
-
- 1 2 3
-
-What has happened is that C<fred> accesses the C<@_> array which
-belongs to C<joe>.
-
-
-=head2 G_EVAL
-
-It is possible for the Perl subroutine you are calling to terminate
-abnormally, e.g., by calling I<die> explicitly or by not actually
-existing. By default, when either of these events occurs, the
-process will terminate immediately. If you want to trap this
-type of event, specify the G_EVAL flag. It will put an I<eval { }>
-around the subroutine call.
-
-Whenever control returns from the I<call_*> function you need to
-check the C<$@> variable as you would in a normal Perl script.
-
-The value returned from the I<call_*> function is dependent on
-what other flags have been specified and whether an error has
-occurred. Here are all the different cases that can occur:
-
-=over 5
-
-=item *
-
-If the I<call_*> function returns normally, then the value
-returned is as specified in the previous sections.
-
-=item *
-
-If G_DISCARD is specified, the return value will always be 0.
-
-=item *
-
-If G_ARRAY is specified I<and> an error has occurred, the return value
-will always be 0.
-
-=item *
-
-If G_SCALAR is specified I<and> an error has occurred, the return value
-will be 1 and the value on the top of the stack will be I<undef>. This
-means that if you have already detected the error by checking C<$@> and
-you want the program to continue, you must remember to pop the I<undef>
-from the stack.
-
-=back
-
-See I<Using G_EVAL> for details on using G_EVAL.
-
-=head2 G_KEEPERR
-
-Using the G_EVAL flag described above will always set C<$@>: clearing
-it if there was no error, and setting it to describe the error if there
-was an error in the called code. This is what you want if your intention
-is to handle possible errors, but sometimes you just want to trap errors
-and stop them interfering with the rest of the program.
-
-This scenario will mostly be applicable to code that is meant to be called
-from within destructors, asynchronous callbacks, and signal handlers.
-In such situations, where the code being called has little relation to the
-surrounding dynamic context, the main program needs to be insulated from
-errors in the called code, even if they can't be handled intelligently.
-It may also be useful to do this with code for C<__DIE__> or C<__WARN__>
-hooks, and C<tie> functions.
-
-The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in
-I<call_*> functions that are used to implement such code, or with
-C<eval_sv>. This flag has no effect on the C<call_*> functions when
-G_EVAL is not used.
-
-When G_KEEPERR is used, any error in the called code will terminate the
-call as usual, and the error will not propagate beyond the call (as usual
-for G_EVAL), but it will not go into C<$@>. Instead the error will be
-converted into a warning, prefixed with the string "\t(in cleanup)".
-This can be disabled using C<no warnings 'misc'>. If there is no error,
-C<$@> will not be cleared.
-
-Note that the G_KEEPERR flag does not propagate into inner evals; these
-may still set C<$@>.
-
-The G_KEEPERR flag was introduced in Perl version 5.002.
-
-See I<Using G_KEEPERR> for an example of a situation that warrants the
-use of this flag.
-
-=head2 Determining the Context
-
-As mentioned above, you can determine the context of the currently
-executing subroutine in Perl with I<wantarray>. The equivalent test
-can be made in C by using the C<GIMME_V> macro, which returns
-C<G_ARRAY> if you have been called in a list context, C<G_SCALAR> if
-in a scalar context, or C<G_VOID> if in a void context (i.e., the
-return value will not be used). An older version of this macro is
-called C<GIMME>; in a void context it returns C<G_SCALAR> instead of
-C<G_VOID>. An example of using the C<GIMME_V> macro is shown in
-section I<Using GIMME_V>.
-
-=head1 EXAMPLES
-
-Enough of the definition talk! Let's have a few examples.
-
-Perl provides many macros to assist in accessing the Perl stack.
-Wherever possible, these macros should always be used when interfacing
-to Perl internals. We hope this should make the code less vulnerable
-to any changes made to Perl in the future.
-
-Another point worth noting is that in the first series of examples I
-have made use of only the I<call_pv> function. This has been done
-to keep the code simpler and ease you into the topic. Wherever
-possible, if the choice is between using I<call_pv> and
-I<call_sv>, you should always try to use I<call_sv>. See
-I<Using call_sv> for details.
-
-=head2 No Parameters, Nothing Returned
-
-This first trivial example will call a Perl subroutine, I<PrintUID>, to
-print out the UID of the process.
-
- sub PrintUID
- {
- print "UID is $<\n";
- }
-
-and here is a C function to call it
-
- static void
- call_PrintUID()
- {
- dSP;
-
- PUSHMARK(SP);
- call_pv("PrintUID", G_DISCARD|G_NOARGS);
- }
-
-Simple, eh?
-
-A few points to note about this example:
-
-=over 5
-
-=item 1.
-
-Ignore C<dSP> and C<PUSHMARK(SP)> for now. They will be discussed in
-the next example.
-
-=item 2.
-
-We aren't passing any parameters to I<PrintUID> so G_NOARGS can be
-specified.
-
-=item 3.
-
-We aren't interested in anything returned from I<PrintUID>, so
-G_DISCARD is specified. Even if I<PrintUID> was changed to
-return some value(s), having specified G_DISCARD will mean that they
-will be wiped by the time control returns from I<call_pv>.
-
-=item 4.
-
-As I<call_pv> is being used, the Perl subroutine is specified as a
-C string. In this case the subroutine name has been 'hard-wired' into the
-code.
-
-=item 5.
-
-Because we specified G_DISCARD, it is not necessary to check the value
-returned from I<call_pv>. It will always be 0.
-
-=back
-
-=head2 Passing Parameters
-
-Now let's make a slightly more complex example. This time we want to
-call a Perl subroutine, C<LeftString>, which will take 2 parameters--a
-string ($s) and an integer ($n). The subroutine will simply
-print the first $n characters of the string.
-
-So the Perl subroutine would look like this:
-
- sub LeftString
- {
- my($s, $n) = @_;
- print substr($s, 0, $n), "\n";
- }
-
-The C function required to call I<LeftString> would look like this:
-
- static void
- call_LeftString(a, b)
- char * a;
- int b;
- {
- dSP;
-
- ENTER;
- SAVETMPS;
-
- PUSHMARK(SP);
- XPUSHs(sv_2mortal(newSVpv(a, 0)));
- XPUSHs(sv_2mortal(newSViv(b)));
- PUTBACK;
-
- call_pv("LeftString", G_DISCARD);
-
- FREETMPS;
- LEAVE;
- }
-
-Here are a few notes on the C function I<call_LeftString>.
-
-=over 5
-
-=item 1.
-
-Parameters are passed to the Perl subroutine using the Perl stack.
-This is the purpose of the code beginning with the line C<dSP> and
-ending with the line C<PUTBACK>. The C<dSP> declares a local copy
-of the stack pointer. This local copy should B<always> be accessed
-as C<SP>.
-
-=item 2.
-
-If you are going to put something onto the Perl stack, you need to know
-where to put it. This is the purpose of the macro C<dSP>--it declares
-and initializes a I<local> copy of the Perl stack pointer.
-
-All the other macros which will be used in this example require you to
-have used this macro.
-
-The exception to this rule is if you are calling a Perl subroutine
-directly from an XSUB function. In this case it is not necessary to
-use the C<dSP> macro explicitly--it will be declared for you
-automatically.
-
-=item 3.
-
-Any parameters to be pushed onto the stack should be bracketed by the
-C<PUSHMARK> and C<PUTBACK> macros. The purpose of these two macros, in
-this context, is to count the number of parameters you are
-pushing automatically. Then whenever Perl is creating the C<@_> array for the
-subroutine, it knows how big to make it.
-
-The C<PUSHMARK> macro tells Perl to make a mental note of the current
-stack pointer. Even if you aren't passing any parameters (like the
-example shown in the section I<No Parameters, Nothing Returned>) you
-must still call the C<PUSHMARK> macro before you can call any of the
-I<call_*> functions--Perl still needs to know that there are no
-parameters.
-
-The C<PUTBACK> macro sets the global copy of the stack pointer to be
-the same as our local copy. If we didn't do this, I<call_pv>
-wouldn't know where the two parameters we pushed were--remember that
-up to now all the stack pointer manipulation we have done is with our
-local copy, I<not> the global copy.
-
-=item 4.
-
-Next, we come to XPUSHs. This is where the parameters actually get
-pushed onto the stack. In this case we are pushing a string and an
-integer.
-
-See L<perlguts/"XSUBs and the Argument Stack"> for details
-on how the XPUSH macros work.
-
-=item 5.
-
-Because we created temporary values (by means of sv_2mortal() calls)
-we will have to tidy up the Perl stack and dispose of mortal SVs.
-
-This is the purpose of
-
- ENTER;
- SAVETMPS;
-
-at the start of the function, and
-
- FREETMPS;
- LEAVE;
-
-at the end. The C<ENTER>/C<SAVETMPS> pair creates a boundary for any
-temporaries we create. This means that the temporaries we get rid of
-will be limited to those which were created after these calls.
-
-The C<FREETMPS>/C<LEAVE> pair will get rid of any values returned by
-the Perl subroutine (see next example), plus it will also dump the
-mortal SVs we have created. Having C<ENTER>/C<SAVETMPS> at the
-beginning of the code makes sure that no other mortals are destroyed.
-
-Think of these macros as working a bit like C<{> and C<}> in Perl
-to limit the scope of local variables.
-
-See the section I<Using Perl to Dispose of Temporaries> for details of
-an alternative to using these macros.
-
-=item 6.
-
-Finally, I<LeftString> can now be called via the I<call_pv> function.
-The only flag specified this time is G_DISCARD. Because we are passing
-2 parameters to the Perl subroutine this time, we have not specified
-G_NOARGS.
-
-=back
-
-=head2 Returning a Scalar
-
-Now for an example of dealing with the items returned from a Perl
-subroutine.
-
-Here is a Perl subroutine, I<Adder>, that takes 2 integer parameters
-and simply returns their sum.
-
- sub Adder
- {
- my($a, $b) = @_;
- $a + $b;
- }
-
-Because we are now concerned with the return value from I<Adder>, the C
-function required to call it is now a bit more complex.
-
- static void
- call_Adder(a, b)
- int a;
- int b;
- {
- dSP;
- int count;
-
- ENTER;
- SAVETMPS;
-
- PUSHMARK(SP);
- XPUSHs(sv_2mortal(newSViv(a)));
- XPUSHs(sv_2mortal(newSViv(b)));
- PUTBACK;
-
- count = call_pv("Adder", G_SCALAR);
-
- SPAGAIN;
-
- if (count != 1)
- croak("Big trouble\n");
-
- printf ("The sum of %d and %d is %d\n", a, b, POPi);
-
- PUTBACK;
- FREETMPS;
- LEAVE;
- }
-
-Points to note this time are
-
-=over 5
-
-=item 1.
-
-The only flag specified this time was G_SCALAR. That means that the C<@_>
-array will be created and that the value returned by I<Adder> will
-still exist after the call to I<call_pv>.
-
-=item 2.
-
-The purpose of the macro C<SPAGAIN> is to refresh the local copy of the
-stack pointer. This is necessary because it is possible that the memory
-allocated to the Perl stack has been reallocated during the
-I<call_pv> call.
-
-If you are making use of the Perl stack pointer in your code you must
-always refresh the local copy using SPAGAIN whenever you make use
-of the I<call_*> functions or any other Perl internal function.
-
-=item 3.
-
-Although only a single value was expected to be returned from I<Adder>,
-it is still good practice to check the return code from I<call_pv>
-anyway.
-
-Expecting a single value is not quite the same as knowing that there
-will be one. If someone modified I<Adder> to return a list and we
-didn't check for that possibility and take appropriate action the Perl
-stack would end up in an inconsistent state. That is something you
-I<really> don't want to happen ever.
-
-=item 4.
-
-The C<POPi> macro is used here to pop the return value from the stack.
-In this case we wanted an integer, so C<POPi> was used.
-
-
-Here is the complete list of POP macros available, along with the types
-they return.
-
- POPs SV
- POPp pointer
- POPn double
- POPi integer
- POPl long
-
-=item 5.
-
-The final C<PUTBACK> is used to leave the Perl stack in a consistent
-state before exiting the function. This is necessary because when we
-popped the return value from the stack with C<POPi> it updated only our
-local copy of the stack pointer. Remember, C<PUTBACK> sets the global
-stack pointer to be the same as our local copy.
-
-=back
-
-
-=head2 Returning a List of Values
-
-Now, let's extend the previous example to return both the sum of the
-parameters and the difference.
-
-Here is the Perl subroutine
-
- sub AddSubtract
- {
- my($a, $b) = @_;
- ($a+$b, $a-$b);
- }
-
-and this is the C function
-
- static void
- call_AddSubtract(a, b)
- int a;
- int b;
- {
- dSP;
- int count;
-
- ENTER;
- SAVETMPS;
-
- PUSHMARK(SP);
- XPUSHs(sv_2mortal(newSViv(a)));
- XPUSHs(sv_2mortal(newSViv(b)));
- PUTBACK;
-
- count = call_pv("AddSubtract", G_ARRAY);
-
- SPAGAIN;
-
- if (count != 2)
- croak("Big trouble\n");
-
- printf ("%d - %d = %d\n", a, b, POPi);
- printf ("%d + %d = %d\n", a, b, POPi);
-
- PUTBACK;
- FREETMPS;
- LEAVE;
- }
-
-If I<call_AddSubtract> is called like this
-
- call_AddSubtract(7, 4);
-
-then here is the output
-
- 7 - 4 = 3
- 7 + 4 = 11
-
-Notes
-
-=over 5
-
-=item 1.
-
-We wanted list context, so G_ARRAY was used.
-
-=item 2.
-
-Not surprisingly C<POPi> is used twice this time because we were
-retrieving 2 values from the stack. The important thing to note is that
-when using the C<POP*> macros they come off the stack in I<reverse>
-order.
-
-=back
-
-=head2 Returning a List in a Scalar Context
-
-Say the Perl subroutine in the previous section was called in a scalar
-context, like this
-
- static void
- call_AddSubScalar(a, b)
- int a;
- int b;
- {
- dSP;
- int count;
- int i;
-
- ENTER;
- SAVETMPS;
-
- PUSHMARK(SP);
- XPUSHs(sv_2mortal(newSViv(a)));
- XPUSHs(sv_2mortal(newSViv(b)));
- PUTBACK;
-
- count = call_pv("AddSubtract", G_SCALAR);
-
- SPAGAIN;
-
- printf ("Items Returned = %d\n", count);
-
- for (i = 1; i <= count; ++i)
- printf ("Value %d = %d\n", i, POPi);
-
- PUTBACK;
- FREETMPS;
- LEAVE;
- }
-
-The other modification made is that I<call_AddSubScalar> will print the
-number of items returned from the Perl subroutine and their value (for
-simplicity it assumes that they are integer). So if
-I<call_AddSubScalar> is called
-
- call_AddSubScalar(7, 4);
-
-then the output will be
-
- Items Returned = 1
- Value 1 = 3
-
-In this case the main point to note is that only the last item in the
-list is returned from the subroutine. I<AddSubtract> actually made it back to
-I<call_AddSubScalar>.
-
-
-=head2 Returning Data from Perl via the Parameter List
-
-It is also possible to return values directly via the parameter
-list--whether it is actually desirable to do it is another matter entirely.
-
-The Perl subroutine, I<Inc>, below takes 2 parameters and increments
-each directly.
-
- sub Inc
- {
- ++ $_[0];
- ++ $_[1];
- }
-
-and here is a C function to call it.
-
- static void
- call_Inc(a, b)
- int a;
- int b;
- {
- dSP;
- int count;
- SV * sva;
- SV * svb;
-
- ENTER;
- SAVETMPS;
-
- sva = sv_2mortal(newSViv(a));
- svb = sv_2mortal(newSViv(b));
-
- PUSHMARK(SP);
- XPUSHs(sva);
- XPUSHs(svb);
- PUTBACK;
-
- count = call_pv("Inc", G_DISCARD);
-
- if (count != 0)
- croak ("call_Inc: expected 0 values from 'Inc', got %d\n",
- count);
-
- printf ("%d + 1 = %d\n", a, SvIV(sva));
- printf ("%d + 1 = %d\n", b, SvIV(svb));
-
- FREETMPS;
- LEAVE;
- }
-
-To be able to access the two parameters that were pushed onto the stack
-after they return from I<call_pv> it is necessary to make a note
-of their addresses--thus the two variables C<sva> and C<svb>.
-
-The reason this is necessary is that the area of the Perl stack which
-held them will very likely have been overwritten by something else by
-the time control returns from I<call_pv>.
-
-
-
-
-=head2 Using G_EVAL
-
-Now an example using G_EVAL. Below is a Perl subroutine which computes
-the difference of its 2 parameters. If this would result in a negative
-result, the subroutine calls I<die>.
-
- sub Subtract
- {
- my ($a, $b) = @_;
-
- die "death can be fatal\n" if $a < $b;
-
- $a - $b;
- }
-
-and some C to call it
-
- static void
- call_Subtract(a, b)
- int a;
- int b;
- {
- dSP;
- int count;
-
- ENTER;
- SAVETMPS;
-
- PUSHMARK(SP);
- XPUSHs(sv_2mortal(newSViv(a)));
- XPUSHs(sv_2mortal(newSViv(b)));
- PUTBACK;
-
- count = call_pv("Subtract", G_EVAL|G_SCALAR);
-
- SPAGAIN;
-
- /* Check the eval first */
- if (SvTRUE(ERRSV))
- {
- printf ("Uh oh - %s\n", SvPV_nolen(ERRSV));
- POPs;
- }
- else
- {
- if (count != 1)
- croak("call_Subtract: wanted 1 value from 'Subtract', got %d\n",
- count);
-
- printf ("%d - %d = %d\n", a, b, POPi);
- }
-
- PUTBACK;
- FREETMPS;
- LEAVE;
- }
-
-If I<call_Subtract> is called thus
-
- call_Subtract(4, 5)
-
-the following will be printed
-
- Uh oh - death can be fatal
-
-Notes
-
-=over 5
-
-=item 1.
-
-We want to be able to catch the I<die> so we have used the G_EVAL
-flag. Not specifying this flag would mean that the program would
-terminate immediately at the I<die> statement in the subroutine
-I<Subtract>.
-
-=item 2.
-
-The code
-
- if (SvTRUE(ERRSV))
- {
- printf ("Uh oh - %s\n", SvPV_nolen(ERRSV));
- POPs;
- }
-
-is the direct equivalent of this bit of Perl
-
- print "Uh oh - $@\n" if $@;
-
-C<PL_errgv> is a perl global of type C<GV *> that points to the
-symbol table entry containing the error. C<ERRSV> therefore
-refers to the C equivalent of C<$@>.
-
-=item 3.
-
-Note that the stack is popped using C<POPs> in the block where
-C<SvTRUE(ERRSV)> is true. This is necessary because whenever a
-I<call_*> function invoked with G_EVAL|G_SCALAR returns an error,
-the top of the stack holds the value I<undef>. Because we want the
-program to continue after detecting this error, it is essential that
-the stack be tidied up by removing the I<undef>.
-
-=back
-
-
-=head2 Using G_KEEPERR
-
-Consider this rather facetious example, where we have used an XS
-version of the call_Subtract example above inside a destructor:
-
- package Foo;
- sub new { bless {}, $_[0] }
- sub Subtract {
- my($a,$b) = @_;
- die "death can be fatal" if $a < $b;
- $a - $b;
- }
- sub DESTROY { call_Subtract(5, 4); }
- sub foo { die "foo dies"; }
-
- package main;
- {
- my $foo = Foo->new;
- eval { $foo->foo };
- }
- print "Saw: $@" if $@; # should be, but isn't
-
-This example will fail to recognize that an error occurred inside the
-C<eval {}>. Here's why: the call_Subtract code got executed while perl
-was cleaning up temporaries when exiting the outer braced block, and because
-call_Subtract is implemented with I<call_pv> using the G_EVAL
-flag, it promptly reset C<$@>. This results in the failure of the
-outermost test for C<$@>, and thereby the failure of the error trap.
-
-Appending the G_KEEPERR flag, so that the I<call_pv> call in
-call_Subtract reads:
-
- count = call_pv("Subtract", G_EVAL|G_SCALAR|G_KEEPERR);
-
-will preserve the error and restore reliable error handling.
-
-=head2 Using call_sv
-
-In all the previous examples I have 'hard-wired' the name of the Perl
-subroutine to be called from C. Most of the time though, it is more
-convenient to be able to specify the name of the Perl subroutine from
-within the Perl script.
-
-Consider the Perl code below
-
- sub fred
- {
- print "Hello there\n";
- }
-
- CallSubPV("fred");
-
-Here is a snippet of XSUB which defines I<CallSubPV>.
-
- void
- CallSubPV(name)
- char * name
- CODE:
- PUSHMARK(SP);
- call_pv(name, G_DISCARD|G_NOARGS);
-
-That is fine as far as it goes. The thing is, the Perl subroutine
-can be specified as only a string. For Perl 4 this was adequate,
-but Perl 5 allows references to subroutines and anonymous subroutines.
-This is where I<call_sv> is useful.
-
-The code below for I<CallSubSV> is identical to I<CallSubPV> except
-that the C<name> parameter is now defined as an SV* and we use
-I<call_sv> instead of I<call_pv>.
-
- void
- CallSubSV(name)
- SV * name
- CODE:
- PUSHMARK(SP);
- call_sv(name, G_DISCARD|G_NOARGS);
-
-Because we are using an SV to call I<fred> the following can all be used:
-
- CallSubSV("fred");
- CallSubSV(\&fred);
- $ref = \&fred;
- CallSubSV($ref);
- CallSubSV( sub { print "Hello there\n" } );
-
-As you can see, I<call_sv> gives you much greater flexibility in
-how you can specify the Perl subroutine.
-
-You should note that, if it is necessary to store the SV (C<name> in the
-example above) which corresponds to the Perl subroutine so that it can
-be used later in the program, it not enough just to store a copy of the
-pointer to the SV. Say the code above had been like this:
-
- static SV * rememberSub;
-
- void
- SaveSub1(name)
- SV * name
- CODE:
- rememberSub = name;
-
- void
- CallSavedSub1()
- CODE:
- PUSHMARK(SP);
- call_sv(rememberSub, G_DISCARD|G_NOARGS);
-
-The reason this is wrong is that, by the time you come to use the
-pointer C<rememberSub> in C<CallSavedSub1>, it may or may not still refer
-to the Perl subroutine that was recorded in C<SaveSub1>. This is
-particularly true for these cases:
-
- SaveSub1(\&fred);
- CallSavedSub1();
-
- SaveSub1( sub { print "Hello there\n" } );
- CallSavedSub1();
-
-By the time each of the C<SaveSub1> statements above has been executed,
-the SV*s which corresponded to the parameters will no longer exist.
-Expect an error message from Perl of the form
-
- Can't use an undefined value as a subroutine reference at ...
-
-for each of the C<CallSavedSub1> lines.
-
-Similarly, with this code
-
- $ref = \&fred;
- SaveSub1($ref);
- $ref = 47;
- CallSavedSub1();
-
-you can expect one of these messages (which you actually get is dependent on
-the version of Perl you are using)
-
- Not a CODE reference at ...
- Undefined subroutine &main::47 called ...
-
-The variable $ref may have referred to the subroutine C<fred>
-whenever the call to C<SaveSub1> was made but by the time
-C<CallSavedSub1> gets called it now holds the number C<47>. Because we
-saved only a pointer to the original SV in C<SaveSub1>, any changes to
-$ref will be tracked by the pointer C<rememberSub>. This means that
-whenever C<CallSavedSub1> gets called, it will attempt to execute the
-code which is referenced by the SV* C<rememberSub>. In this case
-though, it now refers to the integer C<47>, so expect Perl to complain
-loudly.
-
-A similar but more subtle problem is illustrated with this code:
-
- $ref = \&fred;
- SaveSub1($ref);
- $ref = \&joe;
- CallSavedSub1();
-
-This time whenever C<CallSavedSub1> gets called it will execute the Perl
-subroutine C<joe> (assuming it exists) rather than C<fred> as was
-originally requested in the call to C<SaveSub1>.
-
-To get around these problems it is necessary to take a full copy of the
-SV. The code below shows C<SaveSub2> modified to do that.
-
- static SV * keepSub = (SV*)NULL;
-
- void
- SaveSub2(name)
- SV * name
- CODE:
- /* Take a copy of the callback */
- if (keepSub == (SV*)NULL)
- /* First time, so create a new SV */
- keepSub = newSVsv(name);
- else
- /* Been here before, so overwrite */
- SvSetSV(keepSub, name);
-
- void
- CallSavedSub2()
- CODE:
- PUSHMARK(SP);
- call_sv(keepSub, G_DISCARD|G_NOARGS);
-
-To avoid creating a new SV every time C<SaveSub2> is called,
-the function first checks to see if it has been called before. If not,
-then space for a new SV is allocated and the reference to the Perl
-subroutine C<name> is copied to the variable C<keepSub> in one
-operation using C<newSVsv>. Thereafter, whenever C<SaveSub2> is called,
-the existing SV, C<keepSub>, is overwritten with the new value using
-C<SvSetSV>.
-
-=head2 Using call_argv
-
-Here is a Perl subroutine which prints whatever parameters are passed
-to it.
-
- sub PrintList
- {
- my(@list) = @_;
-
- foreach (@list) { print "$_\n" }
- }
-
-And here is an example of I<call_argv> which will call
-I<PrintList>.
-
- static char * words[] = {"alpha", "beta", "gamma", "delta", NULL};
-
- static void
- call_PrintList()
- {
- dSP;
-
- call_argv("PrintList", G_DISCARD, words);
- }
-
-Note that it is not necessary to call C<PUSHMARK> in this instance.
-This is because I<call_argv> will do it for you.
-
-=head2 Using call_method
-
-Consider the following Perl code:
-
- {
- package Mine;
-
- sub new
- {
- my($type) = shift;
- bless [@_]
- }
-
- sub Display
- {
- my ($self, $index) = @_;
- print "$index: $$self[$index]\n";
- }
-
- sub PrintID
- {
- my($class) = @_;
- print "This is Class $class version 1.0\n";
- }
- }
-
-It implements just a very simple class to manage an array. Apart from
-the constructor, C<new>, it declares methods, one static and one
-virtual. The static method, C<PrintID>, prints out simply the class
-name and a version number. The virtual method, C<Display>, prints out a
-single element of the array. Here is an all-Perl example of using it.
-
- $a = Mine->new('red', 'green', 'blue');
- $a->Display(1);
- Mine->PrintID;
-
-will print
-
- 1: green
- This is Class Mine version 1.0
-
-Calling a Perl method from C is fairly straightforward. The following
-things are required:
-
-=over 5
-
-=item *
-
-A reference to the object for a virtual method or the name of the class
-for a static method
-
-=item *
-
-The name of the method
-
-=item *
-
-Any other parameters specific to the method
-
-=back
-
-Here is a simple XSUB which illustrates the mechanics of calling both
-the C<PrintID> and C<Display> methods from C.
-
- void
- call_Method(ref, method, index)
- SV * ref
- char * method
- int index
- CODE:
- PUSHMARK(SP);
- XPUSHs(ref);
- XPUSHs(sv_2mortal(newSViv(index)));
- PUTBACK;
-
- call_method(method, G_DISCARD);
-
- void
- call_PrintID(class, method)
- char * class
- char * method
- CODE:
- PUSHMARK(SP);
- XPUSHs(sv_2mortal(newSVpv(class, 0)));
- PUTBACK;
-
- call_method(method, G_DISCARD);
-
-
-So the methods C<PrintID> and C<Display> can be invoked like this:
-
- $a = Mine->new('red', 'green', 'blue');
- call_Method($a, 'Display', 1);
- call_PrintID('Mine', 'PrintID');
-
-The only thing to note is that, in both the static and virtual methods,
-the method name is not passed via the stack--it is used as the first
-parameter to I<call_method>.
-
-=head2 Using GIMME_V
-
-Here is a trivial XSUB which prints the context in which it is
-currently executing.
-
- void
- PrintContext()
- CODE:
- I32 gimme = GIMME_V;
- if (gimme == G_VOID)
- printf ("Context is Void\n");
- else if (gimme == G_SCALAR)
- printf ("Context is Scalar\n");
- else
- printf ("Context is Array\n");
-
-And here is some Perl to test it.
-
- PrintContext;
- $a = PrintContext;
- @a = PrintContext;
-
-The output from that will be
-
- Context is Void
- Context is Scalar
- Context is Array
-
-=head2 Using Perl to Dispose of Temporaries
-
-In the examples given to date, any temporaries created in the callback
-(i.e., parameters passed on the stack to the I<call_*> function or
-values returned via the stack) have been freed by one of these methods:
-
-=over 5
-
-=item *
-
-Specifying the G_DISCARD flag with I<call_*>
-
-=item *
-
-Explicitly using the C<ENTER>/C<SAVETMPS>--C<FREETMPS>/C<LEAVE> pairing
-
-=back
-
-There is another method which can be used, namely letting Perl do it
-for you automatically whenever it regains control after the callback
-has terminated. This is done by simply not using the
-
- ENTER;
- SAVETMPS;
- ...
- FREETMPS;
- LEAVE;
-
-sequence in the callback (and not, of course, specifying the G_DISCARD
-flag).
-
-If you are going to use this method you have to be aware of a possible
-memory leak which can arise under very specific circumstances. To
-explain these circumstances you need to know a bit about the flow of
-control between Perl and the callback routine.
-
-The examples given at the start of the document (an error handler and
-an event driven program) are typical of the two main sorts of flow
-control that you are likely to encounter with callbacks. There is a
-very important distinction between them, so pay attention.
-
-In the first example, an error handler, the flow of control could be as
-follows. You have created an interface to an external library.
-Control can reach the external library like this
-
- perl --> XSUB --> external library
-
-Whilst control is in the library, an error condition occurs. You have
-previously set up a Perl callback to handle this situation, so it will
-get executed. Once the callback has finished, control will drop back to
-Perl again. Here is what the flow of control will be like in that
-situation
-
- perl --> XSUB --> external library
- ...
- error occurs
- ...
- external library --> call_* --> perl
- |
- perl <-- XSUB <-- external library <-- call_* <----+
-
-After processing of the error using I<call_*> is completed,
-control reverts back to Perl more or less immediately.
-
-In the diagram, the further right you go the more deeply nested the
-scope is. It is only when control is back with perl on the extreme
-left of the diagram that you will have dropped back to the enclosing
-scope and any temporaries you have left hanging around will be freed.
-
-In the second example, an event driven program, the flow of control
-will be more like this
-
- perl --> XSUB --> event handler
- ...
- event handler --> call_* --> perl
- |
- event handler <-- call_* <----+
- ...
- event handler --> call_* --> perl
- |
- event handler <-- call_* <----+
- ...
- event handler --> call_* --> perl
- |
- event handler <-- call_* <----+
-
-In this case the flow of control can consist of only the repeated
-sequence
-
- event handler --> call_* --> perl
-
-for practically the complete duration of the program. This means that
-control may I<never> drop back to the surrounding scope in Perl at the
-extreme left.
-
-So what is the big problem? Well, if you are expecting Perl to tidy up
-those temporaries for you, you might be in for a long wait. For Perl
-to dispose of your temporaries, control must drop back to the
-enclosing scope at some stage. In the event driven scenario that may
-never happen. This means that, as time goes on, your program will
-create more and more temporaries, none of which will ever be freed. As
-each of these temporaries consumes some memory your program will
-eventually consume all the available memory in your system--kapow!
-
-So here is the bottom line--if you are sure that control will revert
-back to the enclosing Perl scope fairly quickly after the end of your
-callback, then it isn't absolutely necessary to dispose explicitly of
-any temporaries you may have created. Mind you, if you are at all
-uncertain about what to do, it doesn't do any harm to tidy up anyway.
-
-
-=head2 Strategies for Storing Callback Context Information
-
-
-Potentially one of the trickiest problems to overcome when designing a
-callback interface can be figuring out how to store the mapping between
-the C callback function and the Perl equivalent.
-
-To help understand why this can be a real problem first consider how a
-callback is set up in an all C environment. Typically a C API will
-provide a function to register a callback. This will expect a pointer
-to a function as one of its parameters. Below is a call to a
-hypothetical function C<register_fatal> which registers the C function
-to get called when a fatal error occurs.
-
- register_fatal(cb1);
-
-The single parameter C<cb1> is a pointer to a function, so you must
-have defined C<cb1> in your code, say something like this
-
- static void
- cb1()
- {
- printf ("Fatal Error\n");
- exit(1);
- }
-
-Now change that to call a Perl subroutine instead
-
- static SV * callback = (SV*)NULL;
-
- static void
- cb1()
- {
- dSP;
-
- PUSHMARK(SP);
-
- /* Call the Perl sub to process the callback */
- call_sv(callback, G_DISCARD);
- }
-
-
- void
- register_fatal(fn)
- SV * fn
- CODE:
- /* Remember the Perl sub */
- if (callback == (SV*)NULL)
- callback = newSVsv(fn);
- else
- SvSetSV(callback, fn);
-
- /* register the callback with the external library */
- register_fatal(cb1);
-
-where the Perl equivalent of C<register_fatal> and the callback it
-registers, C<pcb1>, might look like this
-
- # Register the sub pcb1
- register_fatal(\&pcb1);
-
- sub pcb1
- {
- die "I'm dying...\n";
- }
-
-The mapping between the C callback and the Perl equivalent is stored in
-the global variable C<callback>.
-
-This will be adequate if you ever need to have only one callback
-registered at any time. An example could be an error handler like the
-code sketched out above. Remember though, repeated calls to
-C<register_fatal> will replace the previously registered callback
-function with the new one.
-
-Say for example you want to interface to a library which allows asynchronous
-file i/o. In this case you may be able to register a callback whenever
-a read operation has completed. To be of any use we want to be able to
-call separate Perl subroutines for each file that is opened. As it
-stands, the error handler example above would not be adequate as it
-allows only a single callback to be defined at any time. What we
-require is a means of storing the mapping between the opened file and
-the Perl subroutine we want to be called for that file.
-
-Say the i/o library has a function C<asynch_read> which associates a C
-function C<ProcessRead> with a file handle C<fh>--this assumes that it
-has also provided some routine to open the file and so obtain the file
-handle.
-
- asynch_read(fh, ProcessRead)
-
-This may expect the C I<ProcessRead> function of this form
-
- void
- ProcessRead(fh, buffer)
- int fh;
- char * buffer;
- {
- ...
- }
-
-To provide a Perl interface to this library we need to be able to map
-between the C<fh> parameter and the Perl subroutine we want called. A
-hash is a convenient mechanism for storing this mapping. The code
-below shows a possible implementation
-
- static HV * Mapping = (HV*)NULL;
-
- void
- asynch_read(fh, callback)
- int fh
- SV * callback
- CODE:
- /* If the hash doesn't already exist, create it */
- if (Mapping == (HV*)NULL)
- Mapping = newHV();
-
- /* Save the fh -> callback mapping */
- hv_store(Mapping, (char*)&fh, sizeof(fh), newSVsv(callback), 0);
-
- /* Register with the C Library */
- asynch_read(fh, asynch_read_if);
-
-and C<asynch_read_if> could look like this
-
- static void
- asynch_read_if(fh, buffer)
- int fh;
- char * buffer;
- {
- dSP;
- SV ** sv;
-
- /* Get the callback associated with fh */
- sv = hv_fetch(Mapping, (char*)&fh , sizeof(fh), FALSE);
- if (sv == (SV**)NULL)
- croak("Internal error...\n");
-
- PUSHMARK(SP);
- XPUSHs(sv_2mortal(newSViv(fh)));
- XPUSHs(sv_2mortal(newSVpv(buffer, 0)));
- PUTBACK;
-
- /* Call the Perl sub */
- call_sv(*sv, G_DISCARD);
- }
-
-For completeness, here is C<asynch_close>. This shows how to remove
-the entry from the hash C<Mapping>.
-
- void
- asynch_close(fh)
- int fh
- CODE:
- /* Remove the entry from the hash */
- (void) hv_delete(Mapping, (char*)&fh, sizeof(fh), G_DISCARD);
-
- /* Now call the real asynch_close */
- asynch_close(fh);
-
-So the Perl interface would look like this
-
- sub callback1
- {
- my($handle, $buffer) = @_;
- }
-
- # Register the Perl callback
- asynch_read($fh, \&callback1);
-
- asynch_close($fh);
-
-The mapping between the C callback and Perl is stored in the global
-hash C<Mapping> this time. Using a hash has the distinct advantage that
-it allows an unlimited number of callbacks to be registered.
-
-What if the interface provided by the C callback doesn't contain a
-parameter which allows the file handle to Perl subroutine mapping? Say
-in the asynchronous i/o package, the callback function gets passed only
-the C<buffer> parameter like this
-
- void
- ProcessRead(buffer)
- char * buffer;
- {
- ...
- }
-
-Without the file handle there is no straightforward way to map from the
-C callback to the Perl subroutine.
-
-In this case a possible way around this problem is to predefine a
-series of C functions to act as the interface to Perl, thus
-
- #define MAX_CB 3
- #define NULL_HANDLE -1
- typedef void (*FnMap)();
-
- struct MapStruct {
- FnMap Function;
- SV * PerlSub;
- int Handle;
- };
-
- static void fn1();
- static void fn2();
- static void fn3();
-
- static struct MapStruct Map [MAX_CB] =
- {
- { fn1, NULL, NULL_HANDLE },
- { fn2, NULL, NULL_HANDLE },
- { fn3, NULL, NULL_HANDLE }
- };
-
- static void
- Pcb(index, buffer)
- int index;
- char * buffer;
- {
- dSP;
-
- PUSHMARK(SP);
- XPUSHs(sv_2mortal(newSVpv(buffer, 0)));
- PUTBACK;
-
- /* Call the Perl sub */
- call_sv(Map[index].PerlSub, G_DISCARD);
- }
-
- static void
- fn1(buffer)
- char * buffer;
- {
- Pcb(0, buffer);
- }
-
- static void
- fn2(buffer)
- char * buffer;
- {
- Pcb(1, buffer);
- }
-
- static void
- fn3(buffer)
- char * buffer;
- {
- Pcb(2, buffer);
- }
-
- void
- array_asynch_read(fh, callback)
- int fh
- SV * callback
- CODE:
- int index;
- int null_index = MAX_CB;
-
- /* Find the same handle or an empty entry */
- for (index = 0; index < MAX_CB; ++index)
- {
- if (Map[index].Handle == fh)
- break;
-
- if (Map[index].Handle == NULL_HANDLE)
- null_index = index;
- }
-
- if (index == MAX_CB && null_index == MAX_CB)
- croak ("Too many callback functions registered\n");
-
- if (index == MAX_CB)
- index = null_index;
-
- /* Save the file handle */
- Map[index].Handle = fh;
-
- /* Remember the Perl sub */
- if (Map[index].PerlSub == (SV*)NULL)
- Map[index].PerlSub = newSVsv(callback);
- else
- SvSetSV(Map[index].PerlSub, callback);
-
- asynch_read(fh, Map[index].Function);
-
- void
- array_asynch_close(fh)
- int fh
- CODE:
- int index;
-
- /* Find the file handle */
- for (index = 0; index < MAX_CB; ++ index)
- if (Map[index].Handle == fh)
- break;
-
- if (index == MAX_CB)
- croak ("could not close fh %d\n", fh);
-
- Map[index].Handle = NULL_HANDLE;
- SvREFCNT_dec(Map[index].PerlSub);
- Map[index].PerlSub = (SV*)NULL;
-
- asynch_close(fh);
-
-In this case the functions C<fn1>, C<fn2>, and C<fn3> are used to
-remember the Perl subroutine to be called. Each of the functions holds
-a separate hard-wired index which is used in the function C<Pcb> to
-access the C<Map> array and actually call the Perl subroutine.
-
-There are some obvious disadvantages with this technique.
-
-Firstly, the code is considerably more complex than with the previous
-example.
-
-Secondly, there is a hard-wired limit (in this case 3) to the number of
-callbacks that can exist simultaneously. The only way to increase the
-limit is by modifying the code to add more functions and then
-recompiling. None the less, as long as the number of functions is
-chosen with some care, it is still a workable solution and in some
-cases is the only one available.
-
-To summarize, here are a number of possible methods for you to consider
-for storing the mapping between C and the Perl callback
-
-=over 5
-
-=item 1. Ignore the problem - Allow only 1 callback
-
-For a lot of situations, like interfacing to an error handler, this may
-be a perfectly adequate solution.
-
-=item 2. Create a sequence of callbacks - hard wired limit
-
-If it is impossible to tell from the parameters passed back from the C
-callback what the context is, then you may need to create a sequence of C
-callback interface functions, and store pointers to each in an array.
-
-=item 3. Use a parameter to map to the Perl callback
-
-A hash is an ideal mechanism to store the mapping between C and Perl.
-
-=back
-
-
-=head2 Alternate Stack Manipulation
-
-
-Although I have made use of only the C<POP*> macros to access values
-returned from Perl subroutines, it is also possible to bypass these
-macros and read the stack using the C<ST> macro (See L<perlxs> for a
-full description of the C<ST> macro).
-
-Most of the time the C<POP*> macros should be adequate; the main
-problem with them is that they force you to process the returned values
-in sequence. This may not be the most suitable way to process the
-values in some cases. What we want is to be able to access the stack in
-a random order. The C<ST> macro as used when coding an XSUB is ideal
-for this purpose.
-
-The code below is the example given in the section I<Returning a List
-of Values> recoded to use C<ST> instead of C<POP*>.
-
- static void
- call_AddSubtract2(a, b)
- int a;
- int b;
- {
- dSP;
- I32 ax;
- int count;
-
- ENTER;
- SAVETMPS;
-
- PUSHMARK(SP);
- XPUSHs(sv_2mortal(newSViv(a)));
- XPUSHs(sv_2mortal(newSViv(b)));
- PUTBACK;
-
- count = call_pv("AddSubtract", G_ARRAY);
-
- SPAGAIN;
- SP -= count;
- ax = (SP - PL_stack_base) + 1;
-
- if (count != 2)
- croak("Big trouble\n");
-
- printf ("%d + %d = %d\n", a, b, SvIV(ST(0)));
- printf ("%d - %d = %d\n", a, b, SvIV(ST(1)));
-
- PUTBACK;
- FREETMPS;
- LEAVE;
- }
-
-Notes
-
-=over 5
-
-=item 1.
-
-Notice that it was necessary to define the variable C<ax>. This is
-because the C<ST> macro expects it to exist. If we were in an XSUB it
-would not be necessary to define C<ax> as it is already defined for
-us.
-
-=item 2.
-
-The code
-
- SPAGAIN;
- SP -= count;
- ax = (SP - PL_stack_base) + 1;
-
-sets the stack up so that we can use the C<ST> macro.
-
-=item 3.
-
-Unlike the original coding of this example, the returned
-values are not accessed in reverse order. So C<ST(0)> refers to the
-first value returned by the Perl subroutine and C<ST(count-1)>
-refers to the last.
-
-=back
-
-=head2 Creating and Calling an Anonymous Subroutine in C
-
-As we've already shown, C<call_sv> can be used to invoke an
-anonymous subroutine. However, our example showed a Perl script
-invoking an XSUB to perform this operation. Let's see how it can be
-done inside our C code:
-
- ...
-
- SV *cvrv = eval_pv("sub { print 'You will not find me cluttering any namespace!' }", TRUE);
-
- ...
-
- call_sv(cvrv, G_VOID|G_NOARGS);
-
-C<eval_pv> is used to compile the anonymous subroutine, which
-will be the return value as well (read more about C<eval_pv> in
-L<perlapi/eval_pv>). Once this code reference is in hand, it
-can be mixed in with all the previous examples we've shown.
-
-=head1 LIGHTWEIGHT CALLBACKS
-
-Sometimes you need to invoke the same subroutine repeatedly.
-This usually happens with a function that acts on a list of
-values, such as Perl's built-in sort(). You can pass a
-comparison function to sort(), which will then be invoked
-for every pair of values that needs to be compared. The first()
-and reduce() functions from L<List::Util> follow a similar
-pattern.
-
-In this case it is possible to speed up the routine (often
-quite substantially) by using the lightweight callback API.
-The idea is that the calling context only needs to be
-created and destroyed once, and the sub can be called
-arbitrarily many times in between.
-
-It is usual to pass parameters using global variables (typically
-$_ for one parameter, or $a and $b for two parameters) rather
-than via @_. (It is possible to use the @_ mechanism if you know
-what you're doing, though there is as yet no supported API for
-it. It's also inherently slower.)
-
-The pattern of macro calls is like this:
-
- dMULTICALL; /* Declare local variables */
- I32 gimme = G_SCALAR; /* context of the call: G_SCALAR,
- * G_ARRAY, or G_VOID */
-
- PUSH_MULTICALL(cv); /* Set up the context for calling cv,
- and set local vars appropriately */
-
- /* loop */ {
- /* set the value(s) af your parameter variables */
- MULTICALL; /* Make the actual call */
- } /* end of loop */
-
- POP_MULTICALL; /* Tear down the calling context */
-
-For some concrete examples, see the implementation of the
-first() and reduce() functions of List::Util 1.18. There you
-will also find a header file that emulates the multicall API
-on older versions of perl.
-
-=head1 SEE ALSO
-
-L<perlxs>, L<perlguts>, L<perlembed>
-
-=head1 AUTHOR
-
-Paul Marquess
-
-Special thanks to the following people who assisted in the creation of
-the document.
-
-Jeff Okamoto, Tim Bunce, Nick Gianniotis, Steve Kelem, Gurusamy Sarathy
-and Larry Wall.
-
-=head1 DATE
-
-Version 1.3, 14th Apr 1997
diff --git a/Master/tlpkg/tlperl/lib/pods/perlce.pod b/Master/tlpkg/tlperl/lib/pods/perlce.pod
deleted file mode 100644
index 7481badd4a0..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlce.pod
+++ /dev/null
@@ -1,306 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see pod/perlpod.pod) which is
-specifically designed to be readable as is.
-
-=head1 NAME
-
-perlce - Perl for WinCE
-
-=head1 Building Perl for WinCE
-
-=head2 DESCRIPTION
-
-This file gives the instructions for building Perl5.8 and above for
-WinCE. Please read and understand the terms under which this
-software is distributed.
-
-=head2 General explanations on cross-compiling WinCE
-
-=over
-
-=item *
-
-F<miniperl> is built. This is a single executable (without DLL), intended
-to run on Win32, and it will facilitate remaining build process; all binaries
-built after it are foreign and should not run locally.
-
-F<miniperl> is built using F<./win32/Makefile>; this is part of normal
-build process invoked as dependency from wince/Makefile.ce
-
-=item *
-
-After F<miniperl> is built, F<configpm> is invoked to create right F<Config.pm>
-in right place and its corresponding Cross.pm.
-
-Unlike Win32 build, miniperl will not have F<Config.pm> of host within reach;
-it rather will use F<Config.pm> from within cross-compilation directories.
-
-File F<Cross.pm> is dead simple: for given cross-architecture places in @INC
-a path where perl modules are, and right F<Config.pm> in that place.
-
-That said, C<miniperl -Ilib -MConfig -we 1> should report an error, because
-it can not find F<Config.pm>. If it does not give an error -- wrong F<Config.pm>
-is substituted, and resulting binaries will be a mess.
-
-C<miniperl -MCross -MConfig -we 1> should run okay, and it will provide right
-F<Config.pm> for further compilations.
-
-=item *
-
-During extensions build phase, a script F<./win32/buldext.pl> is invoked,
-which in turn steps in F<./ext> subdirectories and performs a build of
-each extension in turn.
-
-All invokes of F<Makefile.PL> are provided with C<-MCross> so to enable cross-
-compile.
-
-=back
-
-=head2 BUILD
-
-This section describes the steps to be performed to build PerlCE.
-You may find additional information about building perl for WinCE
-at L<http://perlce.sourceforge.net> and some pre-built binaries.
-
-=head3 Tools & SDK
-
-For compiling, you need following:
-
-=over 4
-
-=item * Microsoft Embedded Visual Tools
-
-=item * Microsoft Visual C++
-
-=item * Rainer Keuchel's celib-sources
-
-=item * Rainer Keuchel's console-sources
-
-=back
-
-Needed source files can be downloaded at
-L<http://perlce.sourceforge.net>
-
-=head3 Make
-
-Normally you only need to edit F<./win32/ce-helpers/compile.bat>
-to reflect your system and run it.
-
-File F<./win32/ce-helpers/compile.bat> is actually a wrapper to call
-C<nmake -f makefile.ce> with appropriate parameters and it accepts extra
-parameters and forwards them to C<nmake> command as additional
-arguments. You should pass target this way.
-
-To prepare distribution you need to do following:
-
-=over 4
-
-=item * go to F<./win32> subdirectory
-
-=item * edit file F<./win32/ce-helpers/compile.bat>
-
-=item * run
- compile.bat
-
-=item * run
- compile.bat dist
-
-=back
-
-F<Makefile.ce> has C<CROSS_NAME> macro, and it is used further to refer to
-your cross-compilation scheme. You could assign a name to it, but this
-is not necessary, because by default it is assigned after your machine
-configuration name, such as "wince-sh3-hpc-wce211", and this is enough
-to distinguish different builds at the same time. This option could be
-handy for several different builds on same platform to perform, say,
-threaded build. In a following example we assume that all required
-environment variables are set properly for C cross-compiler (a special
-*.bat file could fit perfectly to this purpose) and your F<compile.bat>
-has proper "MACHINE" parameter set, to, say, C<wince-mips-pocket-wce300>.
-
- compile.bat
- compile.bat dist
- compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" "USE_IMP_SYS=define" "USE_MULTI=define"
- compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" "USE_IMP_SYS=define" "USE_MULTI=define" dist
-
-If all goes okay and no errors during a build, you'll get two independent
-distributions: C<wince-mips-pocket-wce300> and C<mips-wce300-thr>.
-
-Target C<dist> prepares distribution file set. Target C<zipdist> performs
-same as C<dist> but additionally compresses distribution files into zip
-archive.
-
-NOTE: during a build there could be created a number (or one) of F<Config.pm>
-for cross-compilation ("foreign" F<Config.pm>) and those are hidden inside
-F<../xlib/$(CROSS_NAME)> with other auxiliary files, but, and this is important to
-note, there should be B<no> F<Config.pm> for host miniperl.
-If you'll get an error that perl could not find Config.pm somewhere in building
-process this means something went wrong. Most probably you forgot to
-specify a cross-compilation when invoking miniperl.exe to Makefile.PL
-When building an extension for cross-compilation your command line should
-look like
-
- ..\miniperl.exe -I..\lib -MCross=mips-wce300-thr Makefile.PL
-
-or just
-
- ..\miniperl.exe -I..\lib -MCross Makefile.PL
-
-to refer a cross-compilation that was created last time.
-
-All questions related to building for WinCE devices could be asked in
-F<perlce-user@lists.sourceforge.net> mailing list.
-
-=head1 Using Perl on WinCE
-
-=head2 DESCRIPTION
-
-PerlCE is currently linked with a simple console window, so it also
-works on non-hpc devices.
-
-The simple stdio implementation creates the files F<stdin.txt>,
-F<stdout.txt> and F<stderr.txt>, so you might examine them if your
-console has only a limited number of cols.
-
-When exitcode is non-zero, a message box appears, otherwise the
-console closes, so you might have to catch an exit with
-status 0 in your program to see any output.
-
-stdout/stderr now go into the files F</perl-stdout.txt> and
-F</perl-stderr.txt.>
-
-PerlIDE is handy to deal with perlce.
-
-=head2 LIMITATIONS
-
-No fork(), pipe(), popen() etc.
-
-=head2 ENVIRONMENT
-
-All environment vars must be stored in HKLM\Environment as
-strings. They are read at process startup.
-
-=over
-
-=item PERL5LIB
-
-Usual perl lib path (semi-list).
-
-=item PATH
-
-Semi-list for executables.
-
-=item TMP
-
-- Tempdir.
-
-=item UNIXROOTPATH
-
-- Root for accessing some special files, i.e. F</dev/null>, F</etc/services>.
-
-=item ROWS/COLS
-
-- Rows/cols for console.
-
-=item HOME
-
-- Home directory.
-
-=item CONSOLEFONTSIZE
-
-- Size for console font.
-
-=back
-
-You can set these with cereg.exe, a (remote) registry editor
-or via the PerlIDE.
-
-=head2 REGISTRY
-
-To start perl by clicking on a perl source file, you have
-to make the according entries in HKCR (see F<ce-helpers/wince-reg.bat>).
-cereg.exe (which must be executed on a desktop pc with
-ActiveSync) is reported not to work on some devices.
-You have to create the registry entries by hand using a
-registry editor.
-
-=head2 XS
-
-The following Win32-Methods are built-in:
-
- newXS("Win32::GetCwd", w32_GetCwd, file);
- newXS("Win32::SetCwd", w32_SetCwd, file);
- newXS("Win32::GetTickCount", w32_GetTickCount, file);
- newXS("Win32::GetOSVersion", w32_GetOSVersion, file);
- newXS("Win32::IsWinNT", w32_IsWinNT, file);
- newXS("Win32::IsWin95", w32_IsWin95, file);
- newXS("Win32::IsWinCE", w32_IsWinCE, file);
- newXS("Win32::CopyFile", w32_CopyFile, file);
- newXS("Win32::Sleep", w32_Sleep, file);
- newXS("Win32::MessageBox", w32_MessageBox, file);
- newXS("Win32::GetPowerStatus", w32_GetPowerStatus, file);
- newXS("Win32::GetOemInfo", w32_GetOemInfo, file);
- newXS("Win32::ShellEx", w32_ShellEx, file);
-
-=head2 BUGS
-
-Opening files for read-write is currently not supported if
-they use stdio (normal perl file handles).
-
-If you find bugs or if it does not work at all on your
-device, send mail to the address below. Please report
-the details of your device (processor, ceversion,
-devicetype (hpc/palm/pocket)) and the date of the downloaded
-files.
-
-=head2 INSTALLATION
-
-Currently installation instructions are at L<http://perlce.sourceforge.net/>.
-
-After installation & testing processes will stabilize, information will
-be more precise.
-
-=head1 ACKNOWLEDGEMENTS
-
-The port for Win32 was used as a reference.
-
-=head1 History of WinCE port
-
-=over
-
-=item 5.6.0
-
-Initial port of perl to WinCE. It was performed in separate directory
-named F<wince>. This port was based on contents of F<./win32> directory.
-F<miniperl> was not built, user must have HOST perl and properly edit
-F<makefile.ce> to reflect this.
-
-=item 5.8.0
-
-wince port was kept in the same F<./wince> directory, and F<wince/Makefile.ce>
-was used to invoke native compiler to create HOST miniperl, which then
-facilitates cross-compiling process.
-Extension building support was added.
-
-=item 5.9.4
-
-Two directories F<./win32> and F<./wince> were merged, so perlce build
-process comes in F<./win32> directory.
-
-=back
-
-=head1 AUTHORS
-
-=over
-
-=item Rainer Keuchel <coyxc@rainer-keuchel.de>
-
-provided initial port of Perl, which appears to be most essential work, as
-it was a breakthrough on having Perl ported at all.
-Many thanks and obligations to Rainer!
-
-=item Vadim Konovalov
-
-made further support of WinCE port.
-
-=back
diff --git a/Master/tlpkg/tlperl/lib/pods/perlcheat.pod b/Master/tlpkg/tlperl/lib/pods/perlcheat.pod
deleted file mode 100644
index deee2fecdfb..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlcheat.pod
+++ /dev/null
@@ -1,107 +0,0 @@
-=head1 NAME
-
-perlcheat - Perl 5 Cheat Sheet
-
-=head1 DESCRIPTION
-
-This 'cheat sheet' is a handy reference, meant for beginning Perl
-programmers. Not everything is mentioned, but 195 features may
-already be overwhelming.
-
-=head2 The sheet
-
- CONTEXTS SIGILS ref ARRAYS HASHES
- void $scalar SCALAR @array %hash
- scalar @array ARRAY @array[0, 2] @hash{'a', 'b'}
- list %hash HASH $array[0] $hash{'a'}
- &sub CODE
- *glob GLOB SCALAR VALUES
- FORMAT number, string, ref, glob, undef
- REFERENCES
- \ reference $$foo[1] aka $foo->[1]
- $@%&* dereference $$foo{bar} aka $foo->{bar}
- [] anon. arrayref ${$$foo[1]}[2] aka $foo->[1]->[2]
- {} anon. hashref ${$$foo[1]}[2] aka $foo->[1][2]
- \() list of refs
- NUMBERS vs STRINGS LINKS
- OPERATOR PRECEDENCE = = perldoc.perl.org
- -> + . search.cpan.org
- ++ -- == != eq ne cpan.org
- ** < > <= >= lt gt le ge pm.org
- ! ~ \ u+ u- <=> cmp p3rl.org
- =~ !~ perlmonks.org
- * / % x SYNTAX
- + - . foreach (LIST) { } for (a;b;c) { }
- << >> while (e) { } until (e) { }
- named uops if (e) { } elsif (e) { } else { }
- < > <= >= lt gt le ge unless (e) { } elsif (e) { } else { }
- == != <=> eq ne cmp ~~ given (e) { when (e) {} default {} }
- &
- | ^ REGEX METACHARS REGEX MODIFIERS
- && ^ string begin /i case insensitive
- || // $ str end (bfr \n) /m line based ^$
- .. ... + one or more /s . includes \n
- ?: * zero or more /x ignore wh.space
- = += -= *= etc ? zero or one /p preserve
- , => {3,7} repeat in range /a ASCII /aa safe
- list ops | alternation /l locale /d dual
- not [] character class /u Unicode
- and \b word boundary /e evaluate /ee rpts
- or xor \z string end /g global
- () capture /o compile pat once
- DEBUG (?:p) no capture
- -MO=Deparse (?#t) comment REGEX CHARCLASSES
- -MO=Terse (?=p) ZW pos ahead . [^\n]
- -D## (?!p) ZW neg ahead \s whitespace
- -d:Trace (?<=p) ZW pos behind \K \w word chars
- (?<!p) ZW neg behind \d digits
- CONFIGURATION (?>p) no backtrack \pP named property
- perl -V:ivsize (?|p|p)branch reset \h horiz.wh.space
- (?&NM) cap to name \R linebreak
- \S \W \D \H negate
- FUNCTION RETURN LISTS
- stat localtime caller SPECIAL VARIABLES
- 0 dev 0 second 0 package $_ default variable
- 1 ino 1 minute 1 filename $0 program name
- 2 mode 2 hour 2 line $/ input separator
- 3 nlink 3 day 3 subroutine $\ output separator
- 4 uid 4 month-1 4 hasargs $| autoflush
- 5 gid 5 year-1900 5 wantarray $! sys/libcall error
- 6 rdev 6 weekday 6 evaltext $@ eval error
- 7 size 7 yearday 7 is_require $$ process ID
- 8 atime 8 is_dst 8 hints $. line number
- 9 mtime 9 bitmask @ARGV command line args
- 10 ctime 10 hinthash @INC include paths
- 11 blksz 3..10 only @_ subroutine args
- 12 blcks with EXPR %ENV environment
-
-=head1 ACKNOWLEDGEMENTS
-
-The first version of this document appeared on Perl Monks, where several
-people had useful suggestions. Thank you, Perl Monks.
-
-A special thanks to Damian Conway, who didn't only suggest important changes,
-but also took the time to count the number of listed features and make a
-Perl 6 version to show that Perl will stay Perl.
-
-=head1 AUTHOR
-
-Juerd Waalboer <#####@juerd.nl>, with the help of many Perl Monks.
-
-=head1 SEE ALSO
-
-=over 4
-
-=item *
-
-L<http://perlmonks.org/?node_id=216602> - the original PM post
-
-=item *
-
-L<http://perlmonks.org/?node_id=238031> - Damian Conway's Perl 6 version
-
-=item *
-
-L<http://juerd.nl/site.plp/perlcheat> - home of the Perl Cheat Sheet
-
-=back
diff --git a/Master/tlpkg/tlperl/lib/pods/perlclib.pod b/Master/tlpkg/tlperl/lib/pods/perlclib.pod
deleted file mode 100644
index 0785577dace..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlclib.pod
+++ /dev/null
@@ -1,212 +0,0 @@
-=head1 NAME
-
-perlclib - Internal replacements for standard C library functions
-
-=head1 DESCRIPTION
-
-One thing Perl porters should note is that F<perl> doesn't tend to use that
-much of the C standard library internally; you'll see very little use of,
-for example, the F<ctype.h> functions in there. This is because Perl
-tends to reimplement or abstract standard library functions, so that we
-know exactly how they're going to operate.
-
-This is a reference card for people who are familiar with the C library
-and who want to do things the Perl way; to tell them which functions
-they ought to use instead of the more normal C functions.
-
-=head2 Conventions
-
-In the following tables:
-
-=over 3
-
-=item C<t>
-
-is a type.
-
-=item C<p>
-
-is a pointer.
-
-=item C<n>
-
-is a number.
-
-=item C<s>
-
-is a string.
-
-=back
-
-C<sv>, C<av>, C<hv>, etc. represent variables of their respective types.
-
-=head2 File Operations
-
-Instead of the F<stdio.h> functions, you should use the Perl abstraction
-layer. Instead of C<FILE*> types, you need to be handling C<PerlIO*>
-types. Don't forget that with the new PerlIO layered I/O abstraction
-C<FILE*> types may not even be available. See also the C<perlapio>
-documentation for more information about the following functions:
-
- Instead Of: Use:
-
- stdin PerlIO_stdin()
- stdout PerlIO_stdout()
- stderr PerlIO_stderr()
-
- fopen(fn, mode) PerlIO_open(fn, mode)
- freopen(fn, mode, stream) PerlIO_reopen(fn, mode, perlio) (Deprecated)
- fflush(stream) PerlIO_flush(perlio)
- fclose(stream) PerlIO_close(perlio)
-
-=head2 File Input and Output
-
- Instead Of: Use:
-
- fprintf(stream, fmt, ...) PerlIO_printf(perlio, fmt, ...)
-
- [f]getc(stream) PerlIO_getc(perlio)
- [f]putc(stream, n) PerlIO_putc(perlio, n)
- ungetc(n, stream) PerlIO_ungetc(perlio, n)
-
-Note that the PerlIO equivalents of C<fread> and C<fwrite> are slightly
-different from their C library counterparts:
-
- fread(p, size, n, stream) PerlIO_read(perlio, buf, numbytes)
- fwrite(p, size, n, stream) PerlIO_write(perlio, buf, numbytes)
-
- fputs(s, stream) PerlIO_puts(perlio, s)
-
-There is no equivalent to C<fgets>; one should use C<sv_gets> instead:
-
- fgets(s, n, stream) sv_gets(sv, perlio, append)
-
-=head2 File Positioning
-
- Instead Of: Use:
-
- feof(stream) PerlIO_eof(perlio)
- fseek(stream, n, whence) PerlIO_seek(perlio, n, whence)
- rewind(stream) PerlIO_rewind(perlio)
-
- fgetpos(stream, p) PerlIO_getpos(perlio, sv)
- fsetpos(stream, p) PerlIO_setpos(perlio, sv)
-
- ferror(stream) PerlIO_error(perlio)
- clearerr(stream) PerlIO_clearerr(perlio)
-
-=head2 Memory Management and String Handling
-
- Instead Of: Use:
-
- t* p = malloc(n) Newx(id, p, n, t)
- t* p = calloc(n, s) Newxz(id, p, n, t)
- p = realloc(p, n) Renew(p, n, t)
- memcpy(dst, src, n) Copy(src, dst, n, t)
- memmove(dst, src, n) Move(src, dst, n, t)
- memcpy(dst, src, sizeof(t)) StructCopy(src, dst, t)
- memset(dst, 0, n * sizeof(t)) Zero(dst, n, t)
- memzero(dst, 0) Zero(dst, n, char)
- free(p) Safefree(p)
-
- strdup(p) savepv(p)
- strndup(p, n) savepvn(p, n) (Hey, strndup doesn't exist!)
-
- strstr(big, little) instr(big, little)
- strcmp(s1, s2) strLE(s1, s2) / strEQ(s1, s2) / strGT(s1,s2)
- strncmp(s1, s2, n) strnNE(s1, s2, n) / strnEQ(s1, s2, n)
-
-Notice the different order of arguments to C<Copy> and C<Move> than used
-in C<memcpy> and C<memmove>.
-
-Most of the time, though, you'll want to be dealing with SVs internally
-instead of raw C<char *> strings:
-
- strlen(s) sv_len(sv)
- strcpy(dt, src) sv_setpv(sv, s)
- strncpy(dt, src, n) sv_setpvn(sv, s, n)
- strcat(dt, src) sv_catpv(sv, s)
- strncat(dt, src) sv_catpvn(sv, s)
- sprintf(s, fmt, ...) sv_setpvf(sv, fmt, ...)
-
-Note also the existence of C<sv_catpvf> and C<sv_vcatpvfn>, combining
-concatenation with formatting.
-
-Sometimes instead of zeroing the allocated heap by using Newxz() you
-should consider "poisoning" the data. This means writing a bit
-pattern into it that should be illegal as pointers (and floating point
-numbers), and also hopefully surprising enough as integers, so that
-any code attempting to use the data without forethought will break
-sooner rather than later. Poisoning can be done using the Poison()
-macros, which have similar arguments to Zero():
-
- PoisonWith(dst, n, t, b) scribble memory with byte b
- PoisonNew(dst, n, t) equal to PoisonWith(dst, n, t, 0xAB)
- PoisonFree(dst, n, t) equal to PoisonWith(dst, n, t, 0xEF)
- Poison(dst, n, t) equal to PoisonFree(dst, n, t)
-
-=head2 Character Class Tests
-
-There are two types of character class tests that Perl implements: one
-type deals in C<char>s and are thus B<not> Unicode aware (and hence
-deprecated unless you B<know> you should use them) and the other type
-deal in C<UV>s and know about Unicode properties. In the following
-table, C<c> is a C<char>, and C<u> is a Unicode codepoint.
-
- Instead Of: Use: But better use:
-
- isalnum(c) isALNUM(c) isALNUM_uni(u)
- isalpha(c) isALPHA(c) isALPHA_uni(u)
- iscntrl(c) isCNTRL(c) isCNTRL_uni(u)
- isdigit(c) isDIGIT(c) isDIGIT_uni(u)
- isgraph(c) isGRAPH(c) isGRAPH_uni(u)
- islower(c) isLOWER(c) isLOWER_uni(u)
- isprint(c) isPRINT(c) isPRINT_uni(u)
- ispunct(c) isPUNCT(c) isPUNCT_uni(u)
- isspace(c) isSPACE(c) isSPACE_uni(u)
- isupper(c) isUPPER(c) isUPPER_uni(u)
- isxdigit(c) isXDIGIT(c) isXDIGIT_uni(u)
-
- tolower(c) toLOWER(c) toLOWER_uni(u)
- toupper(c) toUPPER(c) toUPPER_uni(u)
-
-=head2 F<stdlib.h> functions
-
- Instead Of: Use:
-
- atof(s) Atof(s)
- atol(s) Atol(s)
- strtod(s, &p) Nothing. Just don't use it.
- strtol(s, &p, n) Strtol(s, &p, n)
- strtoul(s, &p, n) Strtoul(s, &p, n)
-
-Notice also the C<grok_bin>, C<grok_hex>, and C<grok_oct> functions in
-F<numeric.c> for converting strings representing numbers in the respective
-bases into C<NV>s.
-
-In theory C<Strtol> and C<Strtoul> may not be defined if the machine perl is
-built on doesn't actually have strtol and strtoul. But as those 2
-functions are part of the 1989 ANSI C spec we suspect you'll find them
-everywhere by now.
-
- int rand() double Drand01()
- srand(n) { seedDrand01((Rand_seed_t)n);
- PL_srand_called = TRUE; }
-
- exit(n) my_exit(n)
- system(s) Don't. Look at pp_system or use my_popen
-
- getenv(s) PerlEnv_getenv(s)
- setenv(s, val) my_putenv(s, val)
-
-=head2 Miscellaneous functions
-
-You should not even B<want> to use F<setjmp.h> functions, but if you
-think you do, use the C<JMPENV> stack in F<scope.h> instead.
-
-For C<signal>/C<sigaction>, use C<rsignal(signo, handler)>.
-
-=head1 SEE ALSO
-
-L<perlapi>, L<perlapio>, L<perlguts>
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlcn.pod b/Master/tlpkg/tlperl/lib/pods/perlcn.pod
deleted file mode 100644
index e45ebff2e70..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlcn.pod
+++ /dev/null
@@ -1,150 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see perlpod manpage) which is
-specially designed to be readable as is.
-
-The following documentation is written in EUC-CN encoding.
-
-Èç¹ûÄãÓÃÒ»°ãµÄÎÄ×ֱ༭Æ÷ÔÄÀÀÕâ·ÝÎļþ, ÇëºöÂÔÎÄÖÐÆæÌصÄ×¢¼Ç×Ö·û.
-Õâ·ÝÎļþÊÇÒÔ POD (¼òÃ÷Îļþ¸ñʽ) д³É; ÕâÖÖ¸ñʽÊÇΪÁËÄÜÈÃÈËÖ±½ÓÔĶÁ,
-¶øÌرðÉè¼ÆµÄ. ¹ØÓڴ˸ñʽµÄ½øÒ»²½ÐÅÏ¢, Çë²Î¿¼ perlpod ÏßÉÏÎļþ.
-
-=encoding euc-cn
-
-=head1 NAME
-
-perlcn - ¼òÌåÖÐÎÄ Perl Ö¸ÄÏ
-
-=head1 DESCRIPTION
-
-»¶Ó­À´µ½ Perl µÄÌìµØ!
-
-´Ó 5.8.0 °æ¿ªÊ¼, Perl ¾ß±¸ÁËÍêÉÆµÄ Unicode (ͳһÂë) Ö§Ô®,
-Ò²Á¬´øÖ§Ô®ÁËÐí¶àÀ­¶¡ÓïϵÒÔÍâµÄ±àÂ뷽ʽ; CJK (ÖÐÈÕº«) ±ãÊÇÆäÖеÄÒ»²¿·Ý.
-Unicode Êǹú¼ÊÐԵıê×¼, ÊÔͼº­¸ÇÊÀ½çÉÏËùÓеÄ×Ö·û: Î÷·½ÊÀ½ç, ¶«·½ÊÀ½ç,
-ÒÔ¼°Á½Õß¼äµÄÒ»ÇÐ (Ï£À°ÎÄ, ÐðÀûÑÇÎÄ, ÑÇÀ­²®ÎÄ, Ï£²®À´ÎÄ, Ó¡¶ÈÎÄ,
-Ó¡µØ°²ÎÄ, µÈµÈ). ËüÒ²ÈÝÄÉÁ˶àÖÖ×÷ҵϵͳÓëƽ̨ (Èç PC ¼°Âó½ðËþ).
-
-Perl ±¾ÉíÒÔ Unicode ½øÐвÙ×÷. Õâ±íʾ Perl ÄÚ²¿µÄ×Ö·û´®Êý¾Ý¿ÉÓà Unicode
-±íʾ; Perl µÄº¯Ê½ÓëËã·û (ÀýÈçÕý¹æ±íʾʽ±È¶Ô) Ò²ÄÜ¶Ô Unicode ½øÐвÙ×÷.
-ÔÚÊäÈë¼°Êä³öʱ, ΪÁË´¦ÀíÒÔ Unicode ֮ǰµÄ±àÂ뷽ʽ´æ·ÅµÄÊý¾Ý, Perl
-ÌṩÁË Encode Õâ¸öÄ£¿é, ¿ÉÒÔÈÃÄãÇáÒ׵ضÁÈ¡¼°Ð´Èë¾ÉÓеıàÂëÊý¾Ý.
-
-Encode ÑÓÉìÄ£¿éÖ§Ô®ÏÂÁмòÌåÖÐÎĵıàÂ뷽ʽ ('gb2312' ±íʾ 'euc-cn'):
-
- euc-cn Unix ÑÓÉì×Ö·û¼¯, Ò²¾ÍÊÇË׳ƵĹú±êÂë
- gb2312-raw δ¾­´¦ÀíµÄ (µÍ±ÈÌØ) GB2312 ×Ö·û±í
- gb12345 δ¾­´¦ÀíµÄÖйúÓ÷±ÌåÖÐÎıàÂë
- iso-ir-165 GB2312 + GB6345 + GB8565 + ÐÂÔö×Ö·û
- cp936 ×ÖÂëÒ³ 936, Ò²¿ÉÒÔÓà 'GBK' (À©³ä¹ú±êÂë) Ö¸Ã÷
- hz 7 ±ÈÌØÒݳöʽ GB2312 ±àÂë
-
-¾ÙÀýÀ´Ëµ, ½« EUC-CN ±àÂëµÄµµ°¸×ª³É Unicode, ìóÐè¼üÈëÏÂÁÐÖ¸Áî:
-
- perl -Mencoding=euc-cn,STDOUT,utf8 -pe1 < file.euc-cn > file.utf8
-
-Perl Ò²ÄÚ¸½ÁË "piconv", Ò»Ö§ÍêÈ«ÒÔ Perl д³ÉµÄ×Ö·ûת»»¹¤¾ß³ÌÐò, Ó÷¨ÈçÏÂ:
-
- piconv -f euc-cn -t utf8 < file.euc-cn > file.utf8
- piconv -f utf8 -t euc-cn < file.utf8 > file.euc-cn
-
-ÁíÍâ, ÀûÓà encoding Ä£¿é, Äã¿ÉÒÔÇáÒ×д³öÒÔ×Ö·ûΪµ¥Î»µÄ³ÌÐòÂë, ÈçÏÂËùʾ:
-
- #!/usr/bin/env perl
- # Æô¶¯ euc-cn ×Ö´®½âÎö; ±ê×¼Êä³öÈë¼°±ê×¼´íÎó¶¼ÉèΪ euc-cn ±àÂë
- use encoding 'euc-cn', STDIN => 'euc-cn', STDOUT => 'euc-cn';
- print length("ÂæÍÕ"); # 2 (Ë«ÒýºÅ±íʾ×Ö·û)
- print length('ÂæÍÕ'); # 4 (µ¥ÒýºÅ±íʾ×Ö½Ú)
- print index("×»×»½Ì»å", "»×»½"); # -1 (²»°üº¬´Ë×Ó×Ö·û´®)
- print index('×»×»½Ì»å', '»×»½'); # 1 (´ÓµÚ¶þ¸ö×Ö½Ú¿ªÊ¼)
-
-ÔÚ×îºóÒ»ÁÐÀý×ÓÀï, "×»" µÄµÚ¶þ¸ö×Ö½ÚÓë "×»" µÄµÚÒ»¸ö×Ö½Ú½áºÏ³É EUC-CN
-ÂëµÄ "»×"; "×»" µÄµÚ¶þ¸ö×Ö½ÚÔòÓë "½Ì" µÄµÚÒ»¸ö×Ö½Ú½áºÏ³É "»½".
-Õâ½â¾öÁËÒÔÇ° EUC-CN Âë±È¶Ô´¦ÀíÉϳ£¼ûµÄÎÊÌâ.
-
-=head2 ¶îÍâµÄÖÐÎıàÂë
-
-Èç¹ûÐèÒª¸ü¶àµÄÖÐÎıàÂë, ¿ÉÒÔ´Ó CPAN (L<http://www.cpan.org/>) ÏÂÔØ
-Encode::HanExtra Ä£¿é. ËüÄ¿Ç°ÌṩÏÂÁбàÂ뷽ʽ:
-
- gb18030 À©³ä¹ýµÄ¹ú±êÂë, °üº¬·±ÌåÖÐÎÄ
-
-ÁíÍâ, Encode::HanConvert Ä£¿éÔòÌṩÁ˼ò·±×ª»»ÓõÄÁ½ÖÖ±àÂë:
-
- big5-simp Big5 ·±ÌåÖÐÎÄÓë Unicode ¼òÌåÖÐÎÄ»¥×ª
- gbk-trad GBK ¼òÌåÖÐÎÄÓë Unicode ·±ÌåÖÐÎÄ»¥×ª
-
-ÈôÏëÔÚ GBK Óë Big5 Ö®¼ä»¥×ª, Çë²Î¿¼¸ÃÄ£¿éÄÚ¸½µÄ b2g.pl Óë g2b.pl Á½Ö§³ÌÐò,
-»òÔÚ³ÌÐòÄÚʹÓÃÏÂÁÐд·¨:
-
- use Encode::HanConvert;
- $euc_cn = big5_to_gb($big5); # ´Ó Big5 תΪ GBK
- $big5 = gb_to_big5($euc_cn); # ´Ó GBK תΪ Big5
-
-=head2 ½øÒ»²½µÄÐÅÏ¢
-
-Çë²Î¿¼ Perl ÄÚ¸½µÄ´óÁ¿ËµÃ÷Îļþ (²»ÐÒÈ«ÊÇÓÃÓ¢ÎÄдµÄ), À´Ñ§Ï°¸ü¶à¹ØÓÚ
-Perl µÄ֪ʶ, ÒÔ¼° Unicode µÄʹÓ÷½Ê½. ²»¹ý, ÍⲿµÄ×ÊÔ´Ï൱·á¸»:
-
-=head2 Ìṩ Perl ×ÊÔ´µÄÍøÖ·
-
-=over 4
-
-=item L<http://www.perl.com/>
-
-Perl µÄÊ×Ò³ (ÓÉÅ·À³Àñ¹«Ë¾Î¬»¤)
-
-=item L<http://www.cpan.org/>
-
-Perl ×ۺϵä²ØÍø (Comprehensive Perl Archive Network)
-
-=item L<http://lists.perl.org/>
-
-Perl ÓʵÝÂÛ̳һÀÀ
-
-=back
-
-=head2 ѧϰ Perl µÄÍøÖ·
-
-=over 4
-
-=item L<http://www.oreilly.com.cn/index.php?func=booklist&cat=68>
-
-¼òÌåÖÐÎÄ°æµÄÅ·À³Àñ Perl Êé½å
-
-=back
-
-=head2 Perl ʹÓÃÕß¼¯»á
-
-=over 4
-
-=item L<http://www.pm.org/groups/asia.html>
-
-Öйú Perl Íƹã×éÒ»ÀÀ
-
-=back
-
-=head2 Unicode Ïà¹ØÍøÖ·
-
-=over 4
-
-=item L<http://www.unicode.org/>
-
-Unicode ѧÊõѧ»á (Unicode ±ê×¼µÄÖƶ¨Õß)
-
-=item L<http://www.cl.cam.ac.uk/%7Emgk25/unicode.html>
-
-Unix/Linux É쵀 UTF-8 ¼° Unicode ´ð¿ÍÎÊ
-
-=back
-
-=head1 SEE ALSO
-
-L<Encode>, L<Encode::CN>, L<encoding>, L<perluniintro>, L<perlunicode>
-
-=head1 AUTHORS
-
-Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>
-
-Audrey Tang (ÌÆ·ï) E<lt>audreyt@audreyt.orgE<gt>
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlcommunity.pod b/Master/tlpkg/tlperl/lib/pods/perlcommunity.pod
deleted file mode 100644
index 96c7b85486e..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlcommunity.pod
+++ /dev/null
@@ -1,158 +0,0 @@
-=head1 NAME
-
-perlcommunity - a brief overview of the Perl community
-
-=head1 DESCRIPTION
-
-This document aims to provide an overview of the vast perl community, which is
-far too large and diverse to provide a detailed listing. If any specific niche
-has been forgotten, it is not meant as an insult but an omission for the sake
-of brevity.
-
-The Perl community is as diverse as Perl, and there is a large amount of
-evidence that the Perl users apply TMTOWTDI to all endeavors, not just
-programming. From websites, to IRC, to mailing lists, there is more than one
-way to get involved in the community.
-
-=head2 Where to Find the Community
-
-There is a central directory for the Perl community: L<http://perl.org>
-maintained by the Perl Foundation (L<http://www.perlfoundation.org/>),
-which tracks and provides services for a variety of other community sites.
-
-=head2 Mailing Lists and Newsgroups
-
-Perl runs on e-mail; there is no doubt about it. The Camel book was originally
-written mostly over e-mail and today Perl's development is co-ordinated through
-mailing lists. The largest repository of Perl mailing lists is located at
-L<http://lists.perl.org>.
-
-Most Perl-related projects set up mailing lists for both users and
-contributors. If you don't see a certain project listed at
-L<http://lists.perl.org>, check the particular website for that project.
-Most mailing lists are archived at L<http://nntp.perl.org/>.
-
-There are also plenty of Perl related newsgroups located under
-C<comp.lang.perl.*>.
-
-=head2 IRC
-
-The Perl community has a rather large IRC presence. For starters, it has its
-own IRC network, L<irc://irc.perl.org>. General (not help-oriented) chat can be
-found at L<irc://irc.perl.org/#perl>. Many other more specific chats are also
-hosted on the network. Information about irc.perl.org is located on the
-network's website: L<http://www.irc.perl.org>. For a more help-oriented #perl,
-check out L<irc://irc.freenode.net/#perl>. Perl 6 development also has a
-presence in L<irc://irc.freenode.net/#perl6>. Most Perl-related channels will
-be kind enough to point you in the right direction if you ask nicely.
-
-Any large IRC network (Dalnet, EFnet) is also likely to have a #perl channel,
-with varying activity levels.
-
-=head2 Websites
-
-Perl websites come in a variety of forms, but they fit into two large
-categories: forums and news websites. There are many Perl-related
-websites, so only a few of the community's largest are mentioned here.
-
-=head3 News sites
-
-=over 4
-
-=item L<http://perl.com/>
-
-Run by O'Reilly Media (the publisher of L<the Camel Book|perlbook>, among other
-Perl-related literature), perl.com provides current Perl news, articles, and
-resources for Perl developers as well as a directory of other useful websites.
-
-=item L<http://use.perl.org/>
-
-use Perl; provides a slashdot-style Perl news website covering all things Perl,
-from minutes of the meetings of the Perl 6 Design team to conference
-announcements with (ir)relevant discussion.
-
-=back
-
-=head3 Forums
-
-=over 4
-
-=item L<http://www.perlmonks.org/>
-
-PerlMonks is one of the largest Perl forums, and describes itself as "A place
-for individuals to polish, improve, and showcase their Perl skills." and "A
-community which allows everyone to grow and learn from each other."
-
-=back
-
-=head2 User Groups
-
-Many cities around the world have local Perl Mongers chapters. A Perl Mongers
-chapter is a local user group which typically holds regular in-person meetings,
-both social and technical; helps organize local conferences, workshops, and
-hackathons; and provides a mailing list or other continual contact method for
-its members to keep in touch.
-
-To find your local Perl Mongers (or PM as they're commonly abbreviated) group
-check the international Perl Mongers directory at L<http://www.pm.org/>.
-
-=head2 Workshops
-
-Perl workshops are, as the name might suggest, workshops where Perl is taught
-in a variety of ways. At the workshops, subjects range from a beginner's
-introduction (such as the Pittsburgh Perl Workshop's "Zero To Perl") to much
-more advanced subjects.
-
-There are several great resources for locating workshops: the
-L<websites|"Websites"> mentioned above, the
-L<calendar|"Calendar of Perl Events"> mentioned below, and the YAPC Europe
-website, L<http://www.yapceurope.org/>, which is probably the best resource for
-European Perl events.
-
-=head2 Hackathons
-
-Hackathons are a very different kind of gathering where Perl hackers gather to
-do just that, hack nonstop for an extended (several day) period on a specific
-project or projects. Information about hackathons can be located in the same
-place as information about L<workshops|"Workshops"> as well as in
-L<irc://irc.perl.org/#perl>.
-
-If you have never been to a hackathon, here are a few basic things you need to
-know before attending: have a working laptop and know how to use it; check out
-the involved projects beforehand; have the necessary version control client;
-and bring backup equipment (an extra LAN cable, additional power strips, etc.)
-because someone will forget.
-
-=head2 Conventions
-
-Perl has two major annual conventions: The Perl Conference (now part of OSCON),
-put on by O'Reilly, and Yet Another Perl Conference or YAPC (pronounced
-yap-see), which is localized into several regional YAPCs (North America,
-Europe, Asia) in a stunning grassroots display by the Perl community. For more
-information about either conference, check out their respective web pages:
-OSCON L<http://conferences.oreillynet.com/>; YAPC L<http://www.yapc.org>.
-
-A relatively new conference franchise with a large Perl portion is the
-Open Source Developers Conference or OSDC. First held in Australia it has
-recently also spread to Israel and France. More information can be found at:
-L<http://www.osdc.com.au/> for Australia, L<http://www.osdc.org.il>
-for Israel, and L<http://www.osdc.fr/> for France.
-
-=head2 Calendar of Perl Events
-
-The Perl Review, L<http://www.theperlreview.com> maintains a website
-and Google calendar
-(L<http://www.theperlreview.com/community_calendar>) for tracking
-workshops, hackathons, Perl Mongers meetings, and other events. Views
-of this calendar are at L<http://www.perl.org/events.html> and
-L<http://www.yapc.org>.
-
-Not every event or Perl Mongers group is on that calendar, so don't lose
-heart if you don't see yours posted. To have your event or group listed,
-contact brian d foy (brian@theperlreview.com).
-
-=head1 AUTHOR
-
-Edgar "Trizor" Bering <trizor@gmail.com>
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlcygwin.pod b/Master/tlpkg/tlperl/lib/pods/perlcygwin.pod
deleted file mode 100644
index 4e3e6f57ff8..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlcygwin.pod
+++ /dev/null
@@ -1,779 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see F<pod/perlpod.pod>) which is
-specially designed to be readable as is.
-
-=head1 NAME
-
-perlcygwin - Perl for Cygwin
-
-=head1 SYNOPSIS
-
-This document will help you configure, make, test and install Perl
-on Cygwin. This document also describes features of Cygwin that will
-affect how Perl behaves at runtime.
-
-B<NOTE:> There are pre-built Perl packages available for Cygwin and a
-version of Perl is provided in the normal Cygwin install. If you do
-not need to customize the configuration, consider using one of those
-packages.
-
-
-=head1 PREREQUISITES FOR COMPILING PERL ON CYGWIN
-
-=head2 Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it)
-
-The Cygwin tools are ports of the popular GNU development tools for Win32
-platforms. They run thanks to the Cygwin library which provides the UNIX
-system calls and environment these programs expect. More information
-about this project can be found at:
-
-L<http://www.cygwin.com/>
-
-A recent net or commercial release of Cygwin is required.
-
-At the time this document was last updated, Cygwin 1.7.10 was current.
-
-
-=head2 Cygwin Configuration
-
-While building Perl some changes may be necessary to your Cygwin setup so
-that Perl builds cleanly. These changes are B<not> required for normal
-Perl usage.
-
-B<NOTE:> The binaries that are built will run on all Win32 versions.
-They do not depend on your host system (WinXP/Win2K/Win7) or your
-Cygwin configuration (binary/text mounts, cvgserver).
-The only dependencies come from hard-coded pathnames like C</usr/local>.
-However, your host system and Cygwin configuration will affect Perl's
-runtime behavior (see L</"TEST">).
-
-=over 4
-
-=item * C<PATH>
-
-Set the C<PATH> environment variable so that Configure finds the Cygwin
-versions of programs. Any not-needed Windows directories should be removed or
-moved to the end of your C<PATH>.
-
-=item * I<nroff>
-
-If you do not have I<nroff> (which is part of the I<groff> package),
-Configure will B<not> prompt you to install I<man> pages.
-
-=back
-
-=head1 CONFIGURE PERL ON CYGWIN
-
-The default options gathered by Configure with the assistance of
-F<hints/cygwin.sh> will build a Perl that supports dynamic loading
-(which requires a shared F<cygperl5_16.dll>).
-
-This will run Configure and keep a record:
-
- ./Configure 2>&1 | tee log.configure
-
-If you are willing to accept all the defaults run Configure with B<-de>.
-However, several useful customizations are available.
-
-=head2 Stripping Perl Binaries on Cygwin
-
-It is possible to strip the EXEs and DLLs created by the build process.
-The resulting binaries will be significantly smaller. If you want the
-binaries to be stripped, you can either add a B<-s> option when Configure
-prompts you,
-
- Any additional ld flags (NOT including libraries)? [none] -s
- Any special flags to pass to g++ to create a dynamically loaded library?
- [none] -s
- Any special flags to pass to gcc to use dynamic linking? [none] -s
-
-or you can edit F<hints/cygwin.sh> and uncomment the relevant variables
-near the end of the file.
-
-=head2 Optional Libraries for Perl on Cygwin
-
-Several Perl functions and modules depend on the existence of
-some optional libraries. Configure will find them if they are
-installed in one of the directories listed as being used for library
-searches. Pre-built packages for most of these are available from
-the Cygwin installer.
-
-=over 4
-
-=item * C<-lcrypt>
-
-The crypt package distributed with Cygwin is a Linux compatible 56-bit
-DES crypt port by Corinna Vinschen.
-
-Alternatively, the crypt libraries in GNU libc have been ported to Cygwin.
-
-=item * C<-lgdbm_compat> (C<use GDBM_File>)
-
-GDBM is available for Cygwin.
-
-NOTE: The GDBM library only works on NTFS partitions.
-
-=item * C<-ldb> (C<use DB_File>)
-
-BerkeleyDB is available for Cygwin.
-
-NOTE: The BerkeleyDB library only completely works on NTFS partitions.
-
-=item * C<cygserver> (C<use IPC::SysV>)
-
-A port of SysV IPC is available for Cygwin.
-
-NOTE: This has B<not> been extensively tested. In particular,
-C<d_semctl_semun> is undefined because it fails a Configure test
-and on Win9x the I<shm*()> functions seem to hang. It also creates
-a compile time dependency because F<perl.h> includes F<<sys/ipc.h>>
-and F<<sys/sem.h>> (which will be required in the future when compiling
-CPAN modules). CURRENTLY NOT SUPPORTED!
-
-=item * C<-lutil>
-
-Included with the standard Cygwin netrelease is the inetutils package
-which includes libutil.a.
-
-=back
-
-=head2 Configure-time Options for Perl on Cygwin
-
-The F<INSTALL> document describes several Configure-time options. Some of
-these will work with Cygwin, others are not yet possible. Also, some of
-these are experimental. You can either select an option when Configure
-prompts you or you can define (undefine) symbols on the command line.
-
-=over 4
-
-=item * C<-Uusedl>
-
-Undefining this symbol forces Perl to be compiled statically.
-
-=item * C<-Dusemymalloc>
-
-By default Perl does not use the C<malloc()> included with the Perl source,
-because it was slower and not entirely thread-safe. If you want to force
-Perl to build with the old -Dusemymalloc define this.
-
-=item * C<-Uuseperlio>
-
-Undefining this symbol disables the PerlIO abstraction. PerlIO is now the
-default; it is not recommended to disable PerlIO.
-
-=item * C<-Dusemultiplicity>
-
-Multiplicity is required when embedding Perl in a C program and using
-more than one interpreter instance. This is only required when you build
-a not-threaded perl with C<-Uuseithreads>.
-
-=item * C<-Uuse64bitint>
-
-By default Perl uses 64 bit integers. If you want to use smaller 32 bit
-integers, define this symbol.
-
-=item * C<-Duselongdouble>
-
-I<gcc> supports long doubles (12 bytes). However, several additional
-long double math functions are necessary to use them within Perl
-(I<{atan2, cos, exp, floor, fmod, frexp, isnan, log, modf, pow, sin, sqrt}l,
-strtold>).
-These are B<not> yet available with newlib, the Cygwin libc.
-
-=item * C<-Uuseithreads>
-
-Define this symbol if you want not-threaded faster perl.
-
-=item * C<-Duselargefiles>
-
-Cygwin uses 64-bit integers for internal size and position calculations,
-this will be correctly detected and defined by Configure.
-
-=item * C<-Dmksymlinks>
-
-Use this to build perl outside of the source tree. Details can be
-found in the F<INSTALL> document. This is the recommended way to
-build perl from sources.
-
-=back
-
-=head2 Suspicious Warnings on Cygwin
-
-You may see some messages during Configure that seem suspicious.
-
-=over 4
-
-=item * Win9x and C<d_eofnblk>
-
-Win9x does not correctly report C<EOF> with a non-blocking read on a
-closed pipe. You will see the following messages:
-
- But it also returns -1 to signal EOF, so be careful!
- WARNING: you can't distinguish between EOF and no data!
-
- *** WHOA THERE!!! ***
- The recommended value for $d_eofnblk on this machine was "define"!
- Keep the recommended value? [y]
-
-At least for consistency with WinNT, you should keep the recommended
-value.
-
-=item * Compiler/Preprocessor defines
-
-The following error occurs because of the Cygwin C<#define> of
-C<_LONG_DOUBLE>:
-
- Guessing which symbols your C compiler and preprocessor define...
- try.c:<line#>: missing binary operator
-
-This failure does not seem to cause any problems. With older gcc
-versions, "parse error" is reported instead of "missing binary
-operator".
-
-=back
-
-=head1 MAKE ON CYGWIN
-
-Simply run I<make> and wait:
-
- make 2>&1 | tee log.make
-
-=head1 TEST ON CYGWIN
-
-There are two steps to running the test suite:
-
- make test 2>&1 | tee log.make-test
-
- cd t; ./perl harness 2>&1 | tee ../log.harness
-
-The same tests are run both times, but more information is provided when
-running as C<./perl harness>.
-
-Test results vary depending on your host system and your Cygwin
-configuration. If a test can pass in some Cygwin setup, it is always
-attempted and explainable test failures are documented. It is possible
-for Perl to pass all the tests, but it is more likely that some tests
-will fail for one of the reasons listed below.
-
-=head2 File Permissions on Cygwin
-
-UNIX file permissions are based on sets of mode bits for
-{read,write,execute} for each {user,group,other}. By default Cygwin
-only tracks the Win32 read-only attribute represented as the UNIX file
-user write bit (files are always readable, files are executable if they
-have a F<.{com,bat,exe}> extension or begin with C<#!>, directories are
-always readable and executable). On WinNT with the I<ntea> C<CYGWIN>
-setting, the additional mode bits are stored as extended file attributes.
-On WinNT with the default I<ntsec> C<CYGWIN> setting, permissions use the
-standard WinNT security descriptors and access control lists. Without one of
-these options, these tests will fail (listing not updated yet):
-
- Failed Test List of failed
- ------------------------------------
- io/fs.t 5, 7, 9-10
- lib/anydbm.t 2
- lib/db-btree.t 20
- lib/db-hash.t 16
- lib/db-recno.t 18
- lib/gdbm.t 2
- lib/ndbm.t 2
- lib/odbm.t 2
- lib/sdbm.t 2
- op/stat.t 9, 20 (.tmp not an executable extension)
-
-=head2 NDBM_File and ODBM_File do not work on FAT filesystems
-
-Do not use NDBM_File or ODBM_File on FAT filesystem. They can be
-built on a FAT filesystem, but many tests will fail:
-
- ../ext/NDBM_File/ndbm.t 13 3328 71 59 83.10% 1-2 4 16-71
- ../ext/ODBM_File/odbm.t 255 65280 ?? ?? % ??
- ../lib/AnyDBM_File.t 2 512 12 2 16.67% 1 4
- ../lib/Memoize/t/errors.t 0 139 11 5 45.45% 7-11
- ../lib/Memoize/t/tie_ndbm.t 13 3328 4 4 100.00% 1-4
- run/fresh_perl.t 97 1 1.03% 91
-
-If you intend to run only on FAT (or if using AnyDBM_File on FAT),
-run Configure with the -Ui_ndbm and -Ui_dbm options to prevent
-NDBM_File and ODBM_File being built.
-
-With NTFS (and no CYGWIN=nontsec), there should be no problems even if
-perl was built on FAT.
-
-=head2 C<fork()> failures in io_* tests
-
-A C<fork()> failure may result in the following tests failing:
-
- ext/IO/lib/IO/t/io_multihomed.t
- ext/IO/lib/IO/t/io_sock.t
- ext/IO/lib/IO/t/io_unix.t
-
-See comment on fork in L</Miscellaneous> below.
-
-=head1 Specific features of the Cygwin port
-
-=head2 Script Portability on Cygwin
-
-Cygwin does an outstanding job of providing UNIX-like semantics on top of
-Win32 systems. However, in addition to the items noted above, there are
-some differences that you should know about. This is a very brief guide
-to portability, more information can be found in the Cygwin documentation.
-
-=over 4
-
-=item * Pathnames
-
-Cygwin pathnames are separated by forward (F</>) slashes, Universal
-Naming Codes (F<//UNC>) are also supported Since cygwin-1.7 non-POSIX
-pathnames are disencouraged. Names may contain all printable
-characters.
-
-File names are case insensitive, but case preserving. A pathname that
-contains a backslash or drive letter is a Win32 pathname, and not
-subject to the translations applied to POSIX style pathnames, but
-cygwin will warn you, so better convert them to POSIX.
-
-For conversion we have C<Cygwin::win_to_posix_path()> and
-C<Cygwin::posix_to_win_path()>.
-
-Since cygwin-1.7 pathnames are UTF-8 encoded.
-
-=item * Text/Binary
-
-Since cywgin-1.7 textmounts are deprecated and stronlgy discouraged.
-
-When a file is opened it is in either text or binary mode. In text mode
-a file is subject to CR/LF/Ctrl-Z translations. With Cygwin, the default
-mode for an C<open()> is determined by the mode of the mount that underlies
-the file. See L</Cygwin::is_binmount>(). Perl provides a C<binmode()> function
-to set binary mode on files that otherwise would be treated as text.
-C<sysopen()> with the C<O_TEXT> flag sets text mode on files that otherwise
-would be treated as binary:
-
- sysopen(FOO, "bar", O_WRONLY|O_CREAT|O_TEXT)
-
-C<lseek()>, C<tell()> and C<sysseek()> only work with files opened in binary
-mode.
-
-The text/binary issue is covered at length in the Cygwin documentation.
-
-=item * PerlIO
-
-PerlIO overrides the default Cygwin Text/Binary behaviour. A file will
-always be treated as binary, regardless of the mode of the mount it lives
-on, just like it is in UNIX. So CR/LF translation needs to be requested in
-either the C<open()> call like this:
-
- open(FH, ">:crlf", "out.txt");
-
-which will do conversion from LF to CR/LF on the output, or in the
-environment settings (add this to your .bashrc):
-
- export PERLIO=crlf
-
-which will pull in the crlf PerlIO layer which does LF -> CRLF conversion
-on every output generated by perl.
-
-=item * F<.exe>
-
-The Cygwin C<stat()>, C<lstat()> and C<readlink()> functions make the F<.exe>
-extension transparent by looking for F<foo.exe> when you ask for F<foo>
-(unless a F<foo> also exists). Cygwin does not require a F<.exe>
-extension, but I<gcc> adds it automatically when building a program.
-However, when accessing an executable as a normal file (e.g., I<cp>
-in a makefile) the F<.exe> is not transparent. The I<install> program
-included with Cygwin automatically appends a F<.exe> when necessary.
-
-=item * Cygwin vs. Windows process ids
-
-Cygwin processes have their own pid, which is different from the
-underlying windows pid. Most posix compliant Proc functions expect
-the cygwin pid, but several Win32::Process functions expect the
-winpid. E.g. C<$$> is the cygwin pid of F</usr/bin/perl>, which is not
-the winpid. Use C<Cygwin::winpid_to_pid()> and C<Cygwin::winpid_to_pid()>
-to translate between them.
-
-=item * Cygwin vs. Windows errors
-
-Under Cygwin, $^E is the same as $!. When using L<Win32 API Functions|Win32>,
-use C<Win32::GetLastError()> to get the last Windows error.
-
-=item * rebase errors on fork or system
-
-Using C<fork()> or C<system()> out to another perl after loading multiple dlls
-may result on a DLL baseaddress conflict. The internal cygwin error
-looks like like the following:
-
- 0 [main] perl 8916 child_info_fork::abort: data segment start: parent
- (0xC1A000) != child(0xA6A000)
-
-or:
-
- 183 [main] perl 3588 C:\cygwin\bin\perl.exe: *** fatal error - unable to remap C:\cygwin\bin\cygsvn_subr-1-0.dll to same address as parent(0x6FB30000) != 0x6FE60000
- 46 [main] perl 3488 fork: child 3588 - died waiting for dll loading, errno11
-
-See L<http://cygwin.com/faq/faq-nochunks.html#faq.using.fixing-fork-failures>
-It helps if not too many DLLs are loaded in memory so the available address space is larger,
-e.g. stopping the MS Internet Explorer might help.
-
-Use the perlrebase or rebase utilities to resolve the conflicting dll addresses.
-The rebase package is included in the Cygwin setup. Use F<setup.exe>
-from L<http://www.cygwin.com/setup.exe> to install it.
-
-1. kill all perl processes and run C<perlrebase> or
-
-2. kill all cygwin processes and services, start dash from cmd.exe and run C<rebaseall>.
-
-=item * C<chown()>
-
-On WinNT C<chown()> can change a file's user and group IDs. On Win9x C<chown()>
-is a no-op, although this is appropriate since there is no security model.
-
-=item * Miscellaneous
-
-File locking using the C<F_GETLK> command to C<fcntl()> is a stub that
-returns C<ENOSYS>.
-
-Win9x can not C<rename()> an open file (although WinNT can).
-
-The Cygwin C<chroot()> implementation has holes (it can not restrict file
-access by native Win32 programs).
-
-Inplace editing C<perl -i> of files doesn't work without doing a backup
-of the file being edited C<perl -i.bak> because of windowish restrictions,
-therefore Perl adds the suffix C<.bak> automatically if you use C<perl -i>
-without specifying a backup extension.
-
-=back
-
-=head2 Prebuilt methods:
-
-=over 4
-
-=item C<Cwd::cwd>
-
-Returns the current working directory.
-
-=item C<Cygwin::pid_to_winpid>
-
-Translates a cygwin pid to the corresponding Windows pid (which may or
-may not be the same).
-
-=item C<Cygwin::winpid_to_pid>
-
-Translates a Windows pid to the corresponding cygwin pid (if any).
-
-=item C<Cygwin::win_to_posix_path>
-
-Translates a Windows path to the corresponding cygwin path respecting
-the current mount points. With a second non-null argument returns an
-absolute path. Double-byte characters will not be translated.
-
-=item C<Cygwin::posix_to_win_path>
-
-Translates a cygwin path to the corresponding cygwin path respecting
-the current mount points. With a second non-null argument returns an
-absolute path. Double-byte characters will not be translated.
-
-=item C<Cygwin::mount_table()>
-
-Returns an array of [mnt_dir, mnt_fsname, mnt_type, mnt_opts].
-
- perl -e 'for $i (Cygwin::mount_table) {print join(" ",@$i),"\n";}'
- /bin c:\cygwin\bin system binmode,cygexec
- /usr/bin c:\cygwin\bin system binmode
- /usr/lib c:\cygwin\lib system binmode
- / c:\cygwin system binmode
- /cygdrive/c c: system binmode,noumount
- /cygdrive/d d: system binmode,noumount
- /cygdrive/e e: system binmode,noumount
-
-=item C<Cygwin::mount_flags>
-
-Returns the mount type and flags for a specified mount point.
-A comma-separated string of mntent->mnt_type (always
-"system" or "user"), then the mntent->mnt_opts, where
-the first is always "binmode" or "textmode".
-
- system|user,binmode|textmode,exec,cygexec,cygdrive,mixed,
- notexec,managed,nosuid,devfs,proc,noumount
-
-If the argument is "/cygdrive", then just the volume mount settings,
-and the cygdrive mount prefix are returned.
-
-User mounts override system mounts.
-
- $ perl -e 'print Cygwin::mount_flags "/usr/bin"'
- system,binmode,cygexec
- $ perl -e 'print Cygwin::mount_flags "/cygdrive"'
- binmode,cygdrive,/cygdrive
-
-=item C<Cygwin::is_binmount>
-
-Returns true if the given cygwin path is binary mounted, false if the
-path is mounted in textmode.
-
-=item C<Cygwin::sync_winenv>
-
-Cygwin does not initialize all original Win32 environment variables.
-See the bottom of this page L<http://cygwin.com/cygwin-ug-net/setup-env.html>
-for "Restricted Win32 environment".
-
-Certain Win32 programs called from cygwin programs might need some environment
-variable, such as e.g. ADODB needs %COMMONPROGRAMFILES%.
-Call Cygwin::sync_winenv() to copy all Win32 environment variables to your
-process and note that cygwin will warn on every encounter of non-POSIX paths.
-
-=back
-
-=head1 INSTALL PERL ON CYGWIN
-
-This will install Perl, including I<man> pages.
-
- make install 2>&1 | tee log.make-install
-
-NOTE: If C<STDERR> is redirected C<make install> will B<not> prompt
-you to install I<perl> into F</usr/bin>.
-
-You may need to be I<Administrator> to run C<make install>. If you
-are not, you must have write access to the directories in question.
-
-Information on installing the Perl documentation in HTML format can be
-found in the F<INSTALL> document.
-
-=head1 MANIFEST ON CYGWIN
-
-These are the files in the Perl release that contain references to Cygwin.
-These very brief notes attempt to explain the reason for all conditional
-code. Hopefully, keeping this up to date will allow the Cygwin port to
-be kept as clean as possible.
-
-=over 4
-
-=item Documentation
-
- INSTALL README.cygwin README.win32 MANIFEST
- pod/perl.pod pod/perlport.pod pod/perlfaq3.pod
- pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod
- pod/perl561delta.pod pod/perl570delta.pod pod/perl572delta.pod
- pod/perl573delta.pod pod/perl58delta.pod pod/perl581delta.pod
- pod/perl590delta.pod pod/perlhist.pod pod/perlmodlib.pod
- pod/perltoc.pod Porting/Glossary pod/perlgit.pod
- Porting/checkAUTHORS.pl
- dist/Cwd/Changes ext/Compress-Raw-Zlib/Changes
- ext/Compress-Raw-Zlib/README ext/Compress-Zlib/Changes
- ext/DB_File/Changes ext/Encode/Changes ext/Sys-Syslog/Changes
- ext/Time-HiRes/Changes ext/Win32API-File/Changes lib/CGI/Changes
- lib/ExtUtils/CBuilder/Changes lib/ExtUtils/Changes lib/ExtUtils/NOTES
- lib/ExtUtils/PATCHING lib/ExtUtils/README lib/Module/Build/Changes
- lib/Net/Ping/Changes lib/Test/Harness/Changes
- lib/Term/ANSIColor/ChangeLog lib/Term/ANSIColor/README README.symbian
- symbian/TODO
-
-=item Build, Configure, Make, Install
-
- cygwin/Makefile.SHs
- ext/IPC/SysV/hints/cygwin.pl
- ext/NDBM_File/hints/cygwin.pl
- ext/ODBM_File/hints/cygwin.pl
- hints/cygwin.sh
- Configure - help finding hints from uname,
- shared libperl required for dynamic loading
- Makefile.SH Cross/Makefile-cross-SH
- - linklibperl
- Porting/patchls - cygwin in port list
- installman - man pages with :: translated to .
- installperl - install dll, install to 'pods'
- makedepend.SH - uwinfix
- regen_lib.pl - file permissions
-
- NetWare/Makefile
- plan9/mkfile
- symbian/sanity.pl symbian/sisify.pl
- hints/uwin.sh
- vms/descrip_mms.template
- win32/Makefile win32/makefile.mk
-
-=item Tests
-
- t/io/fs.t - no file mode checks if not ntsec
- skip rename() check when not check_case:relaxed
- t/io/tell.t - binmode
- t/lib/cygwin.t - builtin cygwin function tests
- t/op/groups.t - basegroup has ID = 0
- t/op/magic.t - $^X/symlink WORKAROUND, s/.exe//
- t/op/stat.t - no /dev, skip Win32 ftCreationTime quirk
- (cache manager sometimes preserves ctime of file
- previously created and deleted), no -u (setuid)
- t/op/taint.t - can't use empty path under Cygwin Perl
- t/op/time.t - no tzset()
-
-=item Compiled Perl Source
-
- EXTERN.h - __declspec(dllimport)
- XSUB.h - __declspec(dllexport)
- cygwin/cygwin.c - os_extras (getcwd, spawn, and several Cygwin:: functions)
- perl.c - os_extras, -i.bak
- perl.h - binmode
- doio.c - win9x can not rename a file when it is open
- pp_sys.c - do not define h_errno, init _pwent_struct.pw_comment
- util.c - use setenv
- util.h - PERL_FILE_IS_ABSOLUTE macro
- pp.c - Comment about Posix vs IEEE math under Cygwin
- perlio.c - CR/LF mode
- perliol.c - Comment about EXTCONST under Cygwin
-
-=item Compiled Module Source
-
- ext/Compress-Raw-Zlib/Makefile.PL
- - Can't install via CPAN shell under Cygwin
- ext/Compress-Raw-Zlib/zlib-src/zutil.h
- - Cygwin is Unix-like and has vsnprintf
- ext/Errno/Errno_pm.PL - Special handling for Win32 Perl under Cygwin
- ext/POSIX/POSIX.xs - tzname defined externally
- ext/SDBM_File/sdbm/pair.c
- - EXTCONST needs to be redefined from EXTERN.h
- ext/SDBM_File/sdbm/sdbm.c
- - binary open
- ext/Sys/Syslog/Syslog.xs
- - Cygwin has syslog.h
- ext/Sys/Syslog/win32/compile.pl
- - Convert paths to Windows paths
- ext/Time-HiRes/HiRes.xs
- - Various timers not available
- ext/Time-HiRes/Makefile.PL
- - Find w32api/windows.h
- ext/Win32/Makefile.PL - Use various libraries under Cygwin
- ext/Win32/Win32.xs - Child dir and child env under Cygwin
- ext/Win32API-File/File.xs
- - _open_osfhandle not implemented under Cygwin
- ext/Win32CORE/Win32CORE.c
- - __declspec(dllexport)
-
-=item Perl Modules/Scripts
-
- ext/B/t/OptreeCheck.pm - Comment about stderr/stdout order under Cygwin
- ext/Digest-SHA/bin/shasum
- - Use binary mode under Cygwin
- ext/Sys/Syslog/win32/Win32.pm
- - Convert paths to Windows paths
- ext/Time-HiRes/HiRes.pm
- - Comment about various timers not available
- ext/Win32API-File/File.pm
- - _open_osfhandle not implemented under Cygwin
- ext/Win32CORE/Win32CORE.pm
- - History of Win32CORE under Cygwin
- lib/CGI.pm - binmode and path separator
- lib/CPANPLUS/Dist/MM.pm - Commented out code that fails under Win32/Cygwin
- lib/CPANPLUS/Internals/Constants/Report.pm
- - OS classifications
- lib/CPANPLUS/Internals/Constants.pm
- - Constants for Cygwin
- lib/CPANPLUS/Internals/Report.pm
- - Example of Cygwin report
- lib/CPANPLUS/Module.pm
- - Abort if running on old Cygwin version
- lib/Cwd.pm - hook to internal Cwd::cwd
- lib/ExtUtils/CBuilder/Platform/cygwin.pm
- - use gcc for ld, and link to libperl.dll.a
- lib/ExtUtils/CBuilder.pm
- - Cygwin is Unix-like
- lib/ExtUtils/Install.pm - Install and rename issues under Cygwin
- lib/ExtUtils/MM.pm - OS classifications
- lib/ExtUtils/MM_Any.pm - Example for Cygwin
- lib/ExtUtils/MakeMaker.pm
- - require MM_Cygwin.pm
- lib/ExtUtils/MM_Cygwin.pm
- - canonpath, cflags, manifypods, perl_archive
- lib/File/Fetch.pm - Comment about quotes using a Cygwin example
- lib/File/Find.pm - on remote drives stat() always sets st_nlink to 1
- lib/File/Spec/Cygwin.pm - case_tolerant
- lib/File/Spec/Unix.pm - preserve //unc
- lib/File/Spec/Win32.pm - References a message on cygwin.com
- lib/File/Spec.pm - Pulls in lib/File/Spec/Cygwin.pm
- lib/File/Temp.pm - no directory sticky bit
- lib/Module/Build/Compat.pm - Comment references 'make' under Cygwin
- lib/Module/Build/Platform/cygwin.pm
- - Use '.' for man page separator
- lib/Module/Build.pm - Cygwin is Unix-like
- lib/Module/CoreList.pm - List of all module files and versions
- lib/Net/Domain.pm - No domainname command under Cygwin
- lib/Net/Netrc.pm - Bypass using stat() under Cygwin
- lib/Net/Ping.pm - ECONREFUSED is EAGAIN under Cygwin
- lib/Pod/Find.pm - Set 'pods' dir
- lib/Pod/Perldoc/ToMan.pm - '-c' switch for pod2man
- lib/Pod/Perldoc.pm - Use 'less' pager, and use .exe extension
- lib/Term/ANSIColor.pm - Cygwin terminal info
- lib/perl5db.pl - use stdin not /dev/tty
- utils/perlbug.PL - Add CYGWIN environment variable to report
-
-=item Perl Module Tests
-
- dist/Cwd/t/cwd.t
- ext/Compress-Zlib/t/14gzopen.t
- ext/DB_File/t/db-btree.t
- ext/DB_File/t/db-hash.t
- ext/DB_File/t/db-recno.t
- ext/DynaLoader/t/DynaLoader.t
- ext/File-Glob/t/basic.t
- ext/GDBM_File/t/gdbm.t
- ext/POSIX/t/sysconf.t
- ext/POSIX/t/time.t
- ext/SDBM_File/t/sdbm.t
- ext/Sys/Syslog/t/syslog.t
- ext/Time-HiRes/t/HiRes.t
- ext/Win32/t/Unicode.t
- ext/Win32API-File/t/file.t
- ext/Win32CORE/t/win32core.t
- lib/AnyDBM_File.t
- lib/Archive/Extract/t/01_Archive-Extract.t
- lib/Archive/Tar/t/02_methods.t
- lib/CPANPLUS/t/05_CPANPLUS-Internals-Fetch.t
- lib/CPANPLUS/t/20_CPANPLUS-Dist-MM.t
- lib/ExtUtils/t/Embed.t
- lib/ExtUtils/t/eu_command.t
- lib/ExtUtils/t/MM_Cygwin.t
- lib/ExtUtils/t/MM_Unix.t
- lib/File/Compare.t
- lib/File/Copy.t
- lib/File/Find/t/find.t
- lib/File/Path.t
- lib/File/Spec/t/crossplatform.t
- lib/File/Spec/t/Spec.t
- lib/Module/Build/t/destinations.t
- lib/Net/hostent.t
- lib/Net/Ping/t/110_icmp_inst.t
- lib/Net/Ping/t/500_ping_icmp.t
- lib/Net/t/netrc.t
- lib/Pod/Simple/t/perlcyg.pod
- lib/Pod/Simple/t/perlcygo.txt
- lib/Pod/Simple/t/perlfaq.pod
- lib/Pod/Simple/t/perlfaqo.txt
- lib/User/grent.t
- lib/User/pwent.t
-
-=back
-
-=head1 BUGS ON CYGWIN
-
-Support for swapping real and effective user and group IDs is incomplete.
-On WinNT Cygwin provides C<setuid()>, C<seteuid()>, C<setgid()> and C<setegid()>.
-However, additional Cygwin calls for manipulating WinNT access tokens
-and security contexts are required.
-
-=head1 AUTHORS
-
-Charles Wilson <cwilson@ece.gatech.edu>,
-Eric Fifer <egf7@columbia.edu>,
-alexander smishlajev <als@turnhere.com>,
-Steven Morlock <newspost@morlock.net>,
-Sebastien Barre <Sebastien.Barre@utc.fr>,
-Teun Burgers <burgers@ecn.nl>,
-Gerrit P. Haase <gp@familiehaase.de>,
-Reini Urban <rurban@cpan.org>,
-Jan Dubois <jand@activestate.com>,
-Jerry D. Hedden <jdhedden@cpan.org>.
-
-=head1 HISTORY
-
-Last updated: 2012-02-08
diff --git a/Master/tlpkg/tlperl/lib/pods/perldata.pod b/Master/tlpkg/tlperl/lib/pods/perldata.pod
deleted file mode 100644
index 876382d29fe..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perldata.pod
+++ /dev/null
@@ -1,887 +0,0 @@
-=head1 NAME
-
-perldata - Perl data types
-
-=head1 DESCRIPTION
-
-=head2 Variable names
-X<variable, name> X<variable name> X<data type> X<type>
-
-Perl has three built-in data types: scalars, arrays of scalars, and
-associative arrays of scalars, known as "hashes". A scalar is a
-single string (of any size, limited only by the available memory),
-number, or a reference to something (which will be discussed
-in L<perlref>). Normal arrays are ordered lists of scalars indexed
-by number, starting with 0. Hashes are unordered collections of scalar
-values indexed by their associated string key.
-
-Values are usually referred to by name, or through a named reference.
-The first character of the name tells you to what sort of data
-structure it refers. The rest of the name tells you the particular
-value to which it refers. Usually this name is a single I<identifier>,
-that is, a string beginning with a letter or underscore, and
-containing letters, underscores, and digits. In some cases, it may
-be a chain of identifiers, separated by C<::> (or by the slightly
-archaic C<'>); all but the last are interpreted as names of packages,
-to locate the namespace in which to look up the final identifier
-(see L<perlmod/Packages> for details). It's possible to substitute
-for a simple identifier, an expression that produces a reference
-to the value at runtime. This is described in more detail below
-and in L<perlref>.
-X<identifier>
-
-Perl also has its own built-in variables whose names don't follow
-these rules. They have strange names so they don't accidentally
-collide with one of your normal variables. Strings that match
-parenthesized parts of a regular expression are saved under names
-containing only digits after the C<$> (see L<perlop> and L<perlre>).
-In addition, several special variables that provide windows into
-the inner working of Perl have names containing punctuation characters
-and control characters. These are documented in L<perlvar>.
-X<variable, built-in>
-
-Scalar values are always named with '$', even when referring to a
-scalar that is part of an array or a hash. The '$' symbol works
-semantically like the English word "the" in that it indicates a
-single value is expected.
-X<scalar>
-
- $days # the simple scalar value "days"
- $days[28] # the 29th element of array @days
- $days{'Feb'} # the 'Feb' value from hash %days
- $#days # the last index of array @days
-
-Entire arrays (and slices of arrays and hashes) are denoted by '@',
-which works much as the word "these" or "those" does in English,
-in that it indicates multiple values are expected.
-X<array>
-
- @days # ($days[0], $days[1],... $days[n])
- @days[3,4,5] # same as ($days[3],$days[4],$days[5])
- @days{'a','c'} # same as ($days{'a'},$days{'c'})
-
-Entire hashes are denoted by '%':
-X<hash>
-
- %days # (key1, val1, key2, val2 ...)
-
-In addition, subroutines are named with an initial '&', though this
-is optional when unambiguous, just as the word "do" is often redundant
-in English. Symbol table entries can be named with an initial '*',
-but you don't really care about that yet (if ever :-).
-
-Every variable type has its own namespace, as do several
-non-variable identifiers. This means that you can, without fear
-of conflict, use the same name for a scalar variable, an array, or
-a hash--or, for that matter, for a filehandle, a directory handle, a
-subroutine name, a format name, or a label. This means that $foo
-and @foo are two different variables. It also means that C<$foo[1]>
-is a part of @foo, not a part of $foo. This may seem a bit weird,
-but that's okay, because it is weird.
-X<namespace>
-
-Because variable references always start with '$', '@', or '%', the
-"reserved" words aren't in fact reserved with respect to variable
-names. They I<are> reserved with respect to labels and filehandles,
-however, which don't have an initial special character. You can't
-have a filehandle named "log", for instance. Hint: you could say
-C<open(LOG,'logfile')> rather than C<open(log,'logfile')>. Using
-uppercase filehandles also improves readability and protects you
-from conflict with future reserved words. Case I<is> significant--"FOO",
-"Foo", and "foo" are all different names. Names that start with a
-letter or underscore may also contain digits and underscores.
-X<identifier, case sensitivity>
-X<case>
-
-It is possible to replace such an alphanumeric name with an expression
-that returns a reference to the appropriate type. For a description
-of this, see L<perlref>.
-
-Names that start with a digit may contain only more digits. Names
-that do not start with a letter, underscore, digit or a caret (i.e.
-a control character) are limited to one character, e.g., C<$%> or
-C<$$>. (Most of these one character names have a predefined
-significance to Perl. For instance, C<$$> is the current process
-id.)
-
-=head2 Context
-X<context> X<scalar context> X<list context>
-
-The interpretation of operations and values in Perl sometimes depends
-on the requirements of the context around the operation or value.
-There are two major contexts: list and scalar. Certain operations
-return list values in contexts wanting a list, and scalar values
-otherwise. If this is true of an operation it will be mentioned in
-the documentation for that operation. In other words, Perl overloads
-certain operations based on whether the expected return value is
-singular or plural. Some words in English work this way, like "fish"
-and "sheep".
-
-In a reciprocal fashion, an operation provides either a scalar or a
-list context to each of its arguments. For example, if you say
-
- int( <STDIN> )
-
-the integer operation provides scalar context for the <>
-operator, which responds by reading one line from STDIN and passing it
-back to the integer operation, which will then find the integer value
-of that line and return that. If, on the other hand, you say
-
- sort( <STDIN> )
-
-then the sort operation provides list context for <>, which
-will proceed to read every line available up to the end of file, and
-pass that list of lines back to the sort routine, which will then
-sort those lines and return them as a list to whatever the context
-of the sort was.
-
-Assignment is a little bit special in that it uses its left argument
-to determine the context for the right argument. Assignment to a
-scalar evaluates the right-hand side in scalar context, while
-assignment to an array or hash evaluates the righthand side in list
-context. Assignment to a list (or slice, which is just a list
-anyway) also evaluates the right-hand side in list context.
-
-When you use the C<use warnings> pragma or Perl's B<-w> command-line
-option, you may see warnings
-about useless uses of constants or functions in "void context".
-Void context just means the value has been discarded, such as a
-statement containing only C<"fred";> or C<getpwuid(0);>. It still
-counts as scalar context for functions that care whether or not
-they're being called in list context.
-
-User-defined subroutines may choose to care whether they are being
-called in a void, scalar, or list context. Most subroutines do not
-need to bother, though. That's because both scalars and lists are
-automatically interpolated into lists. See L<perlfunc/wantarray>
-for how you would dynamically discern your function's calling
-context.
-
-=head2 Scalar values
-X<scalar> X<number> X<string> X<reference>
-
-All data in Perl is a scalar, an array of scalars, or a hash of
-scalars. A scalar may contain one single value in any of three
-different flavors: a number, a string, or a reference. In general,
-conversion from one form to another is transparent. Although a
-scalar may not directly hold multiple values, it may contain a
-reference to an array or hash which in turn contains multiple values.
-
-Scalars aren't necessarily one thing or another. There's no place
-to declare a scalar variable to be of type "string", type "number",
-type "reference", or anything else. Because of the automatic
-conversion of scalars, operations that return scalars don't need
-to care (and in fact, cannot care) whether their caller is looking
-for a string, a number, or a reference. Perl is a contextually
-polymorphic language whose scalars can be strings, numbers, or
-references (which includes objects). Although strings and numbers
-are considered pretty much the same thing for nearly all purposes,
-references are strongly-typed, uncastable pointers with builtin
-reference-counting and destructor invocation.
-
-A scalar value is interpreted as FALSE in the Boolean sense
-if it is undefined, the null string or the number 0 (or its
-string equivalent, "0"), and TRUE if it is anything else. The
-Boolean context is just a special kind of scalar context where no
-conversion to a string or a number is ever performed.
-X<boolean> X<bool> X<true> X<false> X<truth>
-
-There are actually two varieties of null strings (sometimes referred
-to as "empty" strings), a defined one and an undefined one. The
-defined version is just a string of length zero, such as C<"">.
-The undefined version is the value that indicates that there is
-no real value for something, such as when there was an error, or
-at end of file, or when you refer to an uninitialized variable or
-element of an array or hash. Although in early versions of Perl,
-an undefined scalar could become defined when first used in a
-place expecting a defined value, this no longer happens except for
-rare cases of autovivification as explained in L<perlref>. You can
-use the defined() operator to determine whether a scalar value is
-defined (this has no meaning on arrays or hashes), and the undef()
-operator to produce an undefined value.
-X<defined> X<undefined> X<undef> X<null> X<string, null>
-
-To find out whether a given string is a valid non-zero number, it's
-sometimes enough to test it against both numeric 0 and also lexical
-"0" (although this will cause noises if warnings are on). That's
-because strings that aren't numbers count as 0, just as they do in B<awk>:
-
- if ($str == 0 && $str ne "0") {
- warn "That doesn't look like a number";
- }
-
-That method may be best because otherwise you won't treat IEEE
-notations like C<NaN> or C<Infinity> properly. At other times, you
-might prefer to determine whether string data can be used numerically
-by calling the POSIX::strtod() function or by inspecting your string
-with a regular expression (as documented in L<perlre>).
-
- warn "has nondigits" if /\D/;
- warn "not a natural number" unless /^\d+$/; # rejects -3
- warn "not an integer" unless /^-?\d+$/; # rejects +3
- warn "not an integer" unless /^[+-]?\d+$/;
- warn "not a decimal number" unless /^-?\d+\.?\d*$/; # rejects .2
- warn "not a decimal number" unless /^-?(?:\d+(?:\.\d*)?|\.\d+)$/;
- warn "not a C float"
- unless /^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/;
-
-The length of an array is a scalar value. You may find the length
-of array @days by evaluating C<$#days>, as in B<csh>. However, this
-isn't the length of the array; it's the subscript of the last element,
-which is a different value since there is ordinarily a 0th element.
-Assigning to C<$#days> actually changes the length of the array.
-Shortening an array this way destroys intervening values. Lengthening
-an array that was previously shortened does not recover values
-that were in those elements. (It used to do so in Perl 4, but we
-had to break this to make sure destructors were called when expected.)
-X<$#> X<array, length>
-
-You can also gain some minuscule measure of efficiency by pre-extending
-an array that is going to get big. You can also extend an array
-by assigning to an element that is off the end of the array. You
-can truncate an array down to nothing by assigning the null list
-() to it. The following are equivalent:
-
- @whatever = ();
- $#whatever = -1;
-
-If you evaluate an array in scalar context, it returns the length
-of the array. (Note that this is not true of lists, which return
-the last value, like the C comma operator, nor of built-in functions,
-which return whatever they feel like returning.) The following is
-always true:
-X<array, length>
-
- scalar(@whatever) == $#whatever + 1;
-
-Some programmers choose to use an explicit conversion so as to
-leave nothing to doubt:
-
- $element_count = scalar(@whatever);
-
-If you evaluate a hash in scalar context, it returns false if the
-hash is empty. If there are any key/value pairs, it returns true;
-more precisely, the value returned is a string consisting of the
-number of used buckets and the number of allocated buckets, separated
-by a slash. This is pretty much useful only to find out whether
-Perl's internal hashing algorithm is performing poorly on your data
-set. For example, you stick 10,000 things in a hash, but evaluating
-%HASH in scalar context reveals C<"1/16">, which means only one out
-of sixteen buckets has been touched, and presumably contains all
-10,000 of your items. This isn't supposed to happen. If a tied hash
-is evaluated in scalar context, the C<SCALAR> method is called (with a
-fallback to C<FIRSTKEY>).
-X<hash, scalar context> X<hash, bucket> X<bucket>
-
-You can preallocate space for a hash by assigning to the keys() function.
-This rounds up the allocated buckets to the next power of two:
-
- keys(%users) = 1000; # allocate 1024 buckets
-
-=head2 Scalar value constructors
-X<scalar, literal> X<scalar, constant>
-
-Numeric literals are specified in any of the following floating point or
-integer formats:
-
- 12345
- 12345.67
- .23E-10 # a very small number
- 3.14_15_92 # a very important number
- 4_294_967_296 # underscore for legibility
- 0xff # hex
- 0xdead_beef # more hex
- 0377 # octal (only numbers, begins with 0)
- 0b011011 # binary
-
-You are allowed to use underscores (underbars) in numeric literals
-between digits for legibility (but not multiple underscores in a row:
-C<23__500> is not legal; C<23_500> is).
-You could, for example, group binary
-digits by threes (as for a Unix-style mode argument such as 0b110_100_100)
-or by fours (to represent nibbles, as in 0b1010_0110) or in other groups.
-X<number, literal>
-
-String literals are usually delimited by either single or double
-quotes. They work much like quotes in the standard Unix shells:
-double-quoted string literals are subject to backslash and variable
-substitution; single-quoted strings are not (except for C<\'> and
-C<\\>). The usual C-style backslash rules apply for making
-characters such as newline, tab, etc., as well as some more exotic
-forms. See L<perlop/"Quote and Quote-like Operators"> for a list.
-X<string, literal>
-
-Hexadecimal, octal, or binary, representations in string literals
-(e.g. '0xff') are not automatically converted to their integer
-representation. The hex() and oct() functions make these conversions
-for you. See L<perlfunc/hex> and L<perlfunc/oct> for more details.
-
-You can also embed newlines directly in your strings, i.e., they can end
-on a different line than they begin. This is nice, but if you forget
-your trailing quote, the error will not be reported until Perl finds
-another line containing the quote character, which may be much further
-on in the script. Variable substitution inside strings is limited to
-scalar variables, arrays, and array or hash slices. (In other words,
-names beginning with $ or @, followed by an optional bracketed
-expression as a subscript.) The following code segment prints out "The
-price is $Z<>100."
-X<interpolation>
-
- $Price = '$100'; # not interpolated
- print "The price is $Price.\n"; # interpolated
-
-There is no double interpolation in Perl, so the C<$100> is left as is.
-
-By default floating point numbers substituted inside strings use the
-dot (".") as the decimal separator. If C<use locale> is in effect,
-and POSIX::setlocale() has been called, the character used for the
-decimal separator is affected by the LC_NUMERIC locale.
-See L<perllocale> and L<POSIX>.
-
-As in some shells, you can enclose the variable name in braces to
-disambiguate it from following alphanumerics (and underscores).
-You must also do
-this when interpolating a variable into a string to separate the
-variable name from a following double-colon or an apostrophe, since
-these would be otherwise treated as a package separator:
-X<interpolation>
-
- $who = "Larry";
- print PASSWD "${who}::0:0:Superuser:/:/bin/perl\n";
- print "We use ${who}speak when ${who}'s here.\n";
-
-Without the braces, Perl would have looked for a $whospeak, a
-C<$who::0>, and a C<$who's> variable. The last two would be the
-$0 and the $s variables in the (presumably) non-existent package
-C<who>.
-
-In fact, an identifier within such curlies is forced to be a string,
-as is any simple identifier within a hash subscript. Neither need
-quoting. Our earlier example, C<$days{'Feb'}> can be written as
-C<$days{Feb}> and the quotes will be assumed automatically. But
-anything more complicated in the subscript will be interpreted as an
-expression. This means for example that C<$version{2.0}++> is
-equivalent to C<$version{2}++>, not to C<$version{'2.0'}++>.
-
-=head3 Version Strings
-X<version string> X<vstring> X<v-string>
-
-A literal of the form C<v1.20.300.4000> is parsed as a string composed
-of characters with the specified ordinals. This form, known as
-v-strings, provides an alternative, more readable way to construct
-strings, rather than use the somewhat less readable interpolation form
-C<"\x{1}\x{14}\x{12c}\x{fa0}">. This is useful for representing
-Unicode strings, and for comparing version "numbers" using the string
-comparison operators, C<cmp>, C<gt>, C<lt> etc. If there are two or
-more dots in the literal, the leading C<v> may be omitted.
-
- print v9786; # prints SMILEY, "\x{263a}"
- print v102.111.111; # prints "foo"
- print 102.111.111; # same
-
-Such literals are accepted by both C<require> and C<use> for
-doing a version check. Note that using the v-strings for IPv4
-addresses is not portable unless you also use the
-inet_aton()/inet_ntoa() routines of the Socket package.
-
-Note that since Perl 5.8.1 the single-number v-strings (like C<v65>)
-are not v-strings before the C<< => >> operator (which is usually used
-to separate a hash key from a hash value); instead they are interpreted
-as literal strings ('v65'). They were v-strings from Perl 5.6.0 to
-Perl 5.8.0, but that caused more confusion and breakage than good.
-Multi-number v-strings like C<v65.66> and C<65.66.67> continue to
-be v-strings always.
-
-=head3 Special Literals
-X<special literal> X<__END__> X<__DATA__> X<END> X<DATA>
-X<end> X<data> X<^D> X<^Z>
-
-The special literals __FILE__, __LINE__, and __PACKAGE__
-represent the current filename, line number, and package name at that
-point in your program. __SUB__ gives a reference to the current
-subroutine. They may be used only as separate tokens; they
-will not be interpolated into strings. If there is no current package
-(due to an empty C<package;> directive), __PACKAGE__ is the undefined
-value. (But the empty C<package;> is no longer supported, as of version
-5.10.) Outside of a subroutine, __SUB__ is the undefined value. __SUB__
-is only available in 5.16 or higher, and only with a C<use v5.16> or
-C<use feature "current_sub"> declaration.
-X<__FILE__> X<__LINE__> X<__PACKAGE__> X<__SUB__>
-X<line> X<file> X<package>
-
-The two control characters ^D and ^Z, and the tokens __END__ and __DATA__
-may be used to indicate the logical end of the script before the actual
-end of file. Any following text is ignored.
-
-Text after __DATA__ may be read via the filehandle C<PACKNAME::DATA>,
-where C<PACKNAME> is the package that was current when the __DATA__
-token was encountered. The filehandle is left open pointing to the
-line after __DATA__. The program should C<close DATA> when it is done
-reading from it. (Leaving it open leaks filehandles if the module is
-reloaded for any reason, so it's a safer practice to close it.) For
-compatibility with older scripts written before __DATA__ was
-introduced, __END__ behaves like __DATA__ in the top level script (but
-not in files loaded with C<require> or C<do>) and leaves the remaining
-contents of the file accessible via C<main::DATA>.
-
-See L<SelfLoader> for more description of __DATA__, and
-an example of its use. Note that you cannot read from the DATA
-filehandle in a BEGIN block: the BEGIN block is executed as soon
-as it is seen (during compilation), at which point the corresponding
-__DATA__ (or __END__) token has not yet been seen.
-
-=head3 Barewords
-X<bareword>
-
-A word that has no other interpretation in the grammar will
-be treated as if it were a quoted string. These are known as
-"barewords". As with filehandles and labels, a bareword that consists
-entirely of lowercase letters risks conflict with future reserved
-words, and if you use the C<use warnings> pragma or the B<-w> switch,
-Perl will warn you about any such words. Perl limits barewords (like
-identifiers) to about 250 characters. Future versions of Perl are likely
-to eliminate these arbitrary limitations.
-
-Some people may wish to outlaw barewords entirely. If you
-say
-
- use strict 'subs';
-
-then any bareword that would NOT be interpreted as a subroutine call
-produces a compile-time error instead. The restriction lasts to the
-end of the enclosing block. An inner block may countermand this
-by saying C<no strict 'subs'>.
-
-=head3 Array Interpolation
-X<array, interpolation> X<interpolation, array> X<$">
-
-Arrays and slices are interpolated into double-quoted strings
-by joining the elements with the delimiter specified in the C<$">
-variable (C<$LIST_SEPARATOR> if "use English;" is specified),
-space by default. The following are equivalent:
-
- $temp = join($", @ARGV);
- system "echo $temp";
-
- system "echo @ARGV";
-
-Within search patterns (which also undergo double-quotish substitution)
-there is an unfortunate ambiguity: Is C</$foo[bar]/> to be interpreted as
-C</${foo}[bar]/> (where C<[bar]> is a character class for the regular
-expression) or as C</${foo[bar]}/> (where C<[bar]> is the subscript to array
-@foo)? If @foo doesn't otherwise exist, then it's obviously a
-character class. If @foo exists, Perl takes a good guess about C<[bar]>,
-and is almost always right. If it does guess wrong, or if you're just
-plain paranoid, you can force the correct interpretation with curly
-braces as above.
-
-If you're looking for the information on how to use here-documents,
-which used to be here, that's been moved to
-L<perlop/Quote and Quote-like Operators>.
-
-=head2 List value constructors
-X<list>
-
-List values are denoted by separating individual values by commas
-(and enclosing the list in parentheses where precedence requires it):
-
- (LIST)
-
-In a context not requiring a list value, the value of what appears
-to be a list literal is simply the value of the final element, as
-with the C comma operator. For example,
-
- @foo = ('cc', '-E', $bar);
-
-assigns the entire list value to array @foo, but
-
- $foo = ('cc', '-E', $bar);
-
-assigns the value of variable $bar to the scalar variable $foo.
-Note that the value of an actual array in scalar context is the
-length of the array; the following assigns the value 3 to $foo:
-
- @foo = ('cc', '-E', $bar);
- $foo = @foo; # $foo gets 3
-
-You may have an optional comma before the closing parenthesis of a
-list literal, so that you can say:
-
- @foo = (
- 1,
- 2,
- 3,
- );
-
-To use a here-document to assign an array, one line per element,
-you might use an approach like this:
-
- @sauces = <<End_Lines =~ m/(\S.*\S)/g;
- normal tomato
- spicy tomato
- green chile
- pesto
- white wine
- End_Lines
-
-LISTs do automatic interpolation of sublists. That is, when a LIST is
-evaluated, each element of the list is evaluated in list context, and
-the resulting list value is interpolated into LIST just as if each
-individual element were a member of LIST. Thus arrays and hashes lose their
-identity in a LIST--the list
-
- (@foo,@bar,&SomeSub,%glarch)
-
-contains all the elements of @foo followed by all the elements of @bar,
-followed by all the elements returned by the subroutine named SomeSub
-called in list context, followed by the key/value pairs of %glarch.
-To make a list reference that does I<NOT> interpolate, see L<perlref>.
-
-The null list is represented by (). Interpolating it in a list
-has no effect. Thus ((),(),()) is equivalent to (). Similarly,
-interpolating an array with no elements is the same as if no
-array had been interpolated at that point.
-
-This interpolation combines with the facts that the opening
-and closing parentheses are optional (except when necessary for
-precedence) and lists may end with an optional comma to mean that
-multiple commas within lists are legal syntax. The list C<1,,3> is a
-concatenation of two lists, C<1,> and C<3>, the first of which ends
-with that optional comma. C<1,,3> is C<(1,),(3)> is C<1,3> (And
-similarly for C<1,,,3> is C<(1,),(,),3> is C<1,3> and so on.) Not that
-we'd advise you to use this obfuscation.
-
-A list value may also be subscripted like a normal array. You must
-put the list in parentheses to avoid ambiguity. For example:
-
- # Stat returns list value.
- $time = (stat($file))[8];
-
- # SYNTAX ERROR HERE.
- $time = stat($file)[8]; # OOPS, FORGOT PARENTHESES
-
- # Find a hex digit.
- $hexdigit = ('a','b','c','d','e','f')[$digit-10];
-
- # A "reverse comma operator".
- return (pop(@foo),pop(@foo))[0];
-
-Lists may be assigned to only when each element of the list
-is itself legal to assign to:
-
- ($a, $b, $c) = (1, 2, 3);
-
- ($map{'red'}, $map{'blue'}, $map{'green'}) = (0x00f, 0x0f0, 0xf00);
-
-An exception to this is that you may assign to C<undef> in a list.
-This is useful for throwing away some of the return values of a
-function:
-
- ($dev, $ino, undef, undef, $uid, $gid) = stat($file);
-
-List assignment in scalar context returns the number of elements
-produced by the expression on the right side of the assignment:
-
- $x = (($foo,$bar) = (3,2,1)); # set $x to 3, not 2
- $x = (($foo,$bar) = f()); # set $x to f()'s return count
-
-This is handy when you want to do a list assignment in a Boolean
-context, because most list functions return a null list when finished,
-which when assigned produces a 0, which is interpreted as FALSE.
-
-It's also the source of a useful idiom for executing a function or
-performing an operation in list context and then counting the number of
-return values, by assigning to an empty list and then using that
-assignment in scalar context. For example, this code:
-
- $count = () = $string =~ /\d+/g;
-
-will place into $count the number of digit groups found in $string.
-This happens because the pattern match is in list context (since it
-is being assigned to the empty list), and will therefore return a list
-of all matching parts of the string. The list assignment in scalar
-context will translate that into the number of elements (here, the
-number of times the pattern matched) and assign that to $count. Note
-that simply using
-
- $count = $string =~ /\d+/g;
-
-would not have worked, since a pattern match in scalar context will
-only return true or false, rather than a count of matches.
-
-The final element of a list assignment may be an array or a hash:
-
- ($a, $b, @rest) = split;
- my($a, $b, %rest) = @_;
-
-You can actually put an array or hash anywhere in the list, but the first one
-in the list will soak up all the values, and anything after it will become
-undefined. This may be useful in a my() or local().
-
-A hash can be initialized using a literal list holding pairs of
-items to be interpreted as a key and a value:
-
- # same as map assignment above
- %map = ('red',0x00f,'blue',0x0f0,'green',0xf00);
-
-While literal lists and named arrays are often interchangeable, that's
-not the case for hashes. Just because you can subscript a list value like
-a normal array does not mean that you can subscript a list value as a
-hash. Likewise, hashes included as parts of other lists (including
-parameters lists and return lists from functions) always flatten out into
-key/value pairs. That's why it's good to use references sometimes.
-
-It is often more readable to use the C<< => >> operator between key/value
-pairs. The C<< => >> operator is mostly just a more visually distinctive
-synonym for a comma, but it also arranges for its left-hand operand to be
-interpreted as a string if it's a bareword that would be a legal simple
-identifier. C<< => >> doesn't quote compound identifiers, that contain
-double colons. This makes it nice for initializing hashes:
-
- %map = (
- red => 0x00f,
- blue => 0x0f0,
- green => 0xf00,
- );
-
-or for initializing hash references to be used as records:
-
- $rec = {
- witch => 'Mable the Merciless',
- cat => 'Fluffy the Ferocious',
- date => '10/31/1776',
- };
-
-or for using call-by-named-parameter to complicated functions:
-
- $field = $query->radio_group(
- name => 'group_name',
- values => ['eenie','meenie','minie'],
- default => 'meenie',
- linebreak => 'true',
- labels => \%labels
- );
-
-Note that just because a hash is initialized in that order doesn't
-mean that it comes out in that order. See L<perlfunc/sort> for examples
-of how to arrange for an output ordering.
-
-=head2 Subscripts
-
-An array can be accessed one scalar at a
-time by specifying a dollar sign (C<$>), then the
-name of the array (without the leading C<@>), then the subscript inside
-square brackets. For example:
-
- @myarray = (5, 50, 500, 5000);
- print "The Third Element is", $myarray[2], "\n";
-
-The array indices start with 0. A negative subscript retrieves its
-value from the end. In our example, C<$myarray[-1]> would have been
-5000, and C<$myarray[-2]> would have been 500.
-
-Hash subscripts are similar, only instead of square brackets curly brackets
-are used. For example:
-
- %scientists =
- (
- "Newton" => "Isaac",
- "Einstein" => "Albert",
- "Darwin" => "Charles",
- "Feynman" => "Richard",
- );
-
- print "Darwin's First Name is ", $scientists{"Darwin"}, "\n";
-
-You can also subscript a list to get a single element from it:
-
- $dir = (getpwnam("daemon"))[7];
-
-=head2 Multi-dimensional array emulation
-
-Multidimensional arrays may be emulated by subscripting a hash with a
-list. The elements of the list are joined with the subscript separator
-(see L<perlvar/$;>).
-
- $foo{$a,$b,$c}
-
-is equivalent to
-
- $foo{join($;, $a, $b, $c)}
-
-The default subscript separator is "\034", the same as SUBSEP in B<awk>.
-
-=head2 Slices
-X<slice> X<array, slice> X<hash, slice>
-
-A slice accesses several elements of a list, an array, or a hash
-simultaneously using a list of subscripts. It's more convenient
-than writing out the individual elements as a list of separate
-scalar values.
-
- ($him, $her) = @folks[0,-1]; # array slice
- @them = @folks[0 .. 3]; # array slice
- ($who, $home) = @ENV{"USER", "HOME"}; # hash slice
- ($uid, $dir) = (getpwnam("daemon"))[2,7]; # list slice
-
-Since you can assign to a list of variables, you can also assign to
-an array or hash slice.
-
- @days[3..5] = qw/Wed Thu Fri/;
- @colors{'red','blue','green'}
- = (0xff0000, 0x0000ff, 0x00ff00);
- @folks[0, -1] = @folks[-1, 0];
-
-The previous assignments are exactly equivalent to
-
- ($days[3], $days[4], $days[5]) = qw/Wed Thu Fri/;
- ($colors{'red'}, $colors{'blue'}, $colors{'green'})
- = (0xff0000, 0x0000ff, 0x00ff00);
- ($folks[0], $folks[-1]) = ($folks[-1], $folks[0]);
-
-Since changing a slice changes the original array or hash that it's
-slicing, a C<foreach> construct will alter some--or even all--of the
-values of the array or hash.
-
- foreach (@array[ 4 .. 10 ]) { s/peter/paul/ }
-
- foreach (@hash{qw[key1 key2]}) {
- s/^\s+//; # trim leading whitespace
- s/\s+$//; # trim trailing whitespace
- s/(\w+)/\u\L$1/g; # "titlecase" words
- }
-
-A slice of an empty list is still an empty list. Thus:
-
- @a = ()[1,0]; # @a has no elements
- @b = (@a)[0,1]; # @b has no elements
- @c = (0,1)[2,3]; # @c has no elements
-
-But:
-
- @a = (1)[1,0]; # @a has two elements
- @b = (1,undef)[1,0,2]; # @b has three elements
-
-This makes it easy to write loops that terminate when a null list
-is returned:
-
- while ( ($home, $user) = (getpwent)[7,0]) {
- printf "%-8s %s\n", $user, $home;
- }
-
-As noted earlier in this document, the scalar sense of list assignment
-is the number of elements on the right-hand side of the assignment.
-The null list contains no elements, so when the password file is
-exhausted, the result is 0, not 2.
-
-Slices in scalar context return the last item of the slice.
-
- @a = qw/first second third/;
- %h = (first => 'A', second => 'B');
- $t = @a[0, 1]; # $t is now 'second'
- $u = @h{'first', 'second'}; # $u is now 'B'
-
-If you're confused about why you use an '@' there on a hash slice
-instead of a '%', think of it like this. The type of bracket (square
-or curly) governs whether it's an array or a hash being looked at.
-On the other hand, the leading symbol ('$' or '@') on the array or
-hash indicates whether you are getting back a singular value (a
-scalar) or a plural one (a list).
-
-=head2 Typeglobs and Filehandles
-X<typeglob> X<filehandle> X<*>
-
-Perl uses an internal type called a I<typeglob> to hold an entire
-symbol table entry. The type prefix of a typeglob is a C<*>, because
-it represents all types. This used to be the preferred way to
-pass arrays and hashes by reference into a function, but now that
-we have real references, this is seldom needed.
-
-The main use of typeglobs in modern Perl is create symbol table aliases.
-This assignment:
-
- *this = *that;
-
-makes $this an alias for $that, @this an alias for @that, %this an alias
-for %that, &this an alias for &that, etc. Much safer is to use a reference.
-This:
-
- local *Here::blue = \$There::green;
-
-temporarily makes $Here::blue an alias for $There::green, but doesn't
-make @Here::blue an alias for @There::green, or %Here::blue an alias for
-%There::green, etc. See L<perlmod/"Symbol Tables"> for more examples
-of this. Strange though this may seem, this is the basis for the whole
-module import/export system.
-
-Another use for typeglobs is to pass filehandles into a function or
-to create new filehandles. If you need to use a typeglob to save away
-a filehandle, do it this way:
-
- $fh = *STDOUT;
-
-or perhaps as a real reference, like this:
-
- $fh = \*STDOUT;
-
-See L<perlsub> for examples of using these as indirect filehandles
-in functions.
-
-Typeglobs are also a way to create a local filehandle using the local()
-operator. These last until their block is exited, but may be passed back.
-For example:
-
- sub newopen {
- my $path = shift;
- local *FH; # not my!
- open (FH, $path) or return undef;
- return *FH;
- }
- $fh = newopen('/etc/passwd');
-
-Now that we have the C<*foo{THING}> notation, typeglobs aren't used as much
-for filehandle manipulations, although they're still needed to pass brand
-new file and directory handles into or out of functions. That's because
-C<*HANDLE{IO}> only works if HANDLE has already been used as a handle.
-In other words, C<*FH> must be used to create new symbol table entries;
-C<*foo{THING}> cannot. When in doubt, use C<*FH>.
-
-All functions that are capable of creating filehandles (open(),
-opendir(), pipe(), socketpair(), sysopen(), socket(), and accept())
-automatically create an anonymous filehandle if the handle passed to
-them is an uninitialized scalar variable. This allows the constructs
-such as C<open(my $fh, ...)> and C<open(local $fh,...)> to be used to
-create filehandles that will conveniently be closed automatically when
-the scope ends, provided there are no other references to them. This
-largely eliminates the need for typeglobs when opening filehandles
-that must be passed around, as in the following example:
-
- sub myopen {
- open my $fh, "@_"
- or die "Can't open '@_': $!";
- return $fh;
- }
-
- {
- my $f = myopen("</etc/motd");
- print <$f>;
- # $f implicitly closed here
- }
-
-Note that if an initialized scalar variable is used instead the
-result is different: C<my $fh='zzz'; open($fh, ...)> is equivalent
-to C<open( *{'zzz'}, ...)>.
-C<use strict 'refs'> forbids such practice.
-
-Another way to create anonymous filehandles is with the Symbol
-module or with the IO::Handle module and its ilk. These modules
-have the advantage of not hiding different types of the same name
-during the local(). See the bottom of L<perlfunc/open> for an
-example.
-
-=head1 SEE ALSO
-
-See L<perlvar> for a description of Perl's built-in variables and
-a discussion of legal variable names. See L<perlref>, L<perlsub>,
-and L<perlmod/"Symbol Tables"> for more discussion on typeglobs and
-the C<*foo{THING}> syntax.
diff --git a/Master/tlpkg/tlperl/lib/pods/perldbmfilter.pod b/Master/tlpkg/tlperl/lib/pods/perldbmfilter.pod
deleted file mode 100644
index 0413bf95f8c..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perldbmfilter.pod
+++ /dev/null
@@ -1,167 +0,0 @@
-=head1 NAME
-
-perldbmfilter - Perl DBM Filters
-
-=head1 SYNOPSIS
-
- $db = tie %hash, 'DBM', ...
-
- $old_filter = $db->filter_store_key ( sub { ... } );
- $old_filter = $db->filter_store_value( sub { ... } );
- $old_filter = $db->filter_fetch_key ( sub { ... } );
- $old_filter = $db->filter_fetch_value( sub { ... } );
-
-=head1 DESCRIPTION
-
-The four C<filter_*> methods shown above are available in all the DBM
-modules that ship with Perl, namely DB_File, GDBM_File, NDBM_File,
-ODBM_File and SDBM_File.
-
-Each of the methods works identically, and is used to install (or
-uninstall) a single DBM Filter. The only difference between them is the
-place that the filter is installed.
-
-To summarise:
-
-=over 5
-
-=item B<filter_store_key>
-
-If a filter has been installed with this method, it will be invoked
-every time you write a key to a DBM database.
-
-=item B<filter_store_value>
-
-If a filter has been installed with this method, it will be invoked
-every time you write a value to a DBM database.
-
-=item B<filter_fetch_key>
-
-If a filter has been installed with this method, it will be invoked
-every time you read a key from a DBM database.
-
-=item B<filter_fetch_value>
-
-If a filter has been installed with this method, it will be invoked
-every time you read a value from a DBM database.
-
-=back
-
-You can use any combination of the methods from none to all four.
-
-All filter methods return the existing filter, if present, or C<undef>
-if not.
-
-To delete a filter pass C<undef> to it.
-
-=head2 The Filter
-
-When each filter is called by Perl, a local copy of C<$_> will contain
-the key or value to be filtered. Filtering is achieved by modifying
-the contents of C<$_>. The return code from the filter is ignored.
-
-=head2 An Example: the NULL termination problem.
-
-DBM Filters are useful for a class of problems where you I<always>
-want to make the same transformation to all keys, all values or both.
-
-For example, consider the following scenario. You have a DBM database
-that you need to share with a third-party C application. The C application
-assumes that I<all> keys and values are NULL terminated. Unfortunately
-when Perl writes to DBM databases it doesn't use NULL termination, so
-your Perl application will have to manage NULL termination itself. When
-you write to the database you will have to use something like this:
-
- $hash{"$key\0"} = "$value\0";
-
-Similarly the NULL needs to be taken into account when you are considering
-the length of existing keys/values.
-
-It would be much better if you could ignore the NULL terminations issue
-in the main application code and have a mechanism that automatically
-added the terminating NULL to all keys and values whenever you write to
-the database and have them removed when you read from the database. As I'm
-sure you have already guessed, this is a problem that DBM Filters can
-fix very easily.
-
- use strict;
- use warnings;
- use SDBM_File;
- use Fcntl;
-
- my %hash;
- my $filename = "filt";
- unlink $filename;
-
- my $db = tie(%hash, 'SDBM_File', $filename, O_RDWR|O_CREAT, 0640)
- or die "Cannot open $filename: $!\n";
-
- # Install DBM Filters
- $db->filter_fetch_key ( sub { s/\0$// } );
- $db->filter_store_key ( sub { $_ .= "\0" } );
- $db->filter_fetch_value(
- sub { no warnings 'uninitialized'; s/\0$// } );
- $db->filter_store_value( sub { $_ .= "\0" } );
-
- $hash{"abc"} = "def";
- my $a = $hash{"ABC"};
- # ...
- undef $db;
- untie %hash;
-
-The code above uses SDBM_File, but it will work with any of the DBM
-modules.
-
-Hopefully the contents of each of the filters should be
-self-explanatory. Both "fetch" filters remove the terminating NULL,
-and both "store" filters add a terminating NULL.
-
-
-=head2 Another Example: Key is a C int.
-
-Here is another real-life example. By default, whenever Perl writes to
-a DBM database it always writes the key and value as strings. So when
-you use this:
-
- $hash{12345} = "something";
-
-the key 12345 will get stored in the DBM database as the 5 byte string
-"12345". If you actually want the key to be stored in the DBM database
-as a C int, you will have to use C<pack> when writing, and C<unpack>
-when reading.
-
-Here is a DBM Filter that does it:
-
- use strict;
- use warnings;
- use DB_File;
- my %hash;
- my $filename = "filt";
- unlink $filename;
-
-
- my $db = tie %hash, 'DB_File', $filename, O_CREAT|O_RDWR, 0666, $DB_HASH
- or die "Cannot open $filename: $!\n";
-
- $db->filter_fetch_key ( sub { $_ = unpack("i", $_) } );
- $db->filter_store_key ( sub { $_ = pack ("i", $_) } );
- $hash{123} = "def";
- # ...
- undef $db;
- untie %hash;
-
-The code above uses DB_File, but again it will work with any of the
-DBM modules.
-
-This time only two filters have been used; we only need to manipulate
-the contents of the key, so it wasn't necessary to install any value
-filters.
-
-=head1 SEE ALSO
-
-L<DB_File>, L<GDBM_File>, L<NDBM_File>, L<ODBM_File> and L<SDBM_File>.
-
-=head1 AUTHOR
-
-Paul Marquess
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perldebguts.pod b/Master/tlpkg/tlperl/lib/pods/perldebguts.pod
deleted file mode 100644
index 8ae6e7baa96..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perldebguts.pod
+++ /dev/null
@@ -1,1000 +0,0 @@
-=head1 NAME
-
-perldebguts - Guts of Perl debugging
-
-=head1 DESCRIPTION
-
-This is not L<perldebug>, which tells you how to use
-the debugger. This manpage describes low-level details concerning
-the debugger's internals, which range from difficult to impossible
-to understand for anyone who isn't incredibly intimate with Perl's guts.
-Caveat lector.
-
-=head1 Debugger Internals
-
-Perl has special debugging hooks at compile-time and run-time used
-to create debugging environments. These hooks are not to be confused
-with the I<perl -Dxxx> command described in L<perlrun>, which is
-usable only if a special Perl is built per the instructions in the
-F<INSTALL> podpage in the Perl source tree.
-
-For example, whenever you call Perl's built-in C<caller> function
-from the package C<DB>, the arguments that the corresponding stack
-frame was called with are copied to the C<@DB::args> array. These
-mechanisms are enabled by calling Perl with the B<-d> switch.
-Specifically, the following additional features are enabled
-(cf. L<perlvar/$^P>):
-
-=over 4
-
-=item *
-
-Perl inserts the contents of C<$ENV{PERL5DB}> (or C<BEGIN {require
-'perl5db.pl'}> if not present) before the first line of your program.
-
-=item *
-
-Each array C<@{"_<$filename"}> holds the lines of $filename for a
-file compiled by Perl. The same is also true for C<eval>ed strings
-that contain subroutines, or which are currently being executed.
-The $filename for C<eval>ed strings looks like C<(eval 34)>.
-Code assertions in regexes look like C<(re_eval 19)>.
-
-Values in this array are magical in numeric context: they compare
-equal to zero only if the line is not breakable.
-
-=item *
-
-Each hash C<%{"_<$filename"}> contains breakpoints and actions keyed
-by line number. Individual entries (as opposed to the whole hash)
-are settable. Perl only cares about Boolean true here, although
-the values used by F<perl5db.pl> have the form
-C<"$break_condition\0$action">.
-
-The same holds for evaluated strings that contain subroutines, or
-which are currently being executed. The $filename for C<eval>ed strings
-looks like C<(eval 34)> or C<(re_eval 19)>.
-
-=item *
-
-Each scalar C<${"_<$filename"}> contains C<"_<$filename">. This is
-also the case for evaluated strings that contain subroutines, or
-which are currently being executed. The $filename for C<eval>ed
-strings looks like C<(eval 34)> or C<(re_eval 19)>.
-
-=item *
-
-After each C<require>d file is compiled, but before it is executed,
-C<DB::postponed(*{"_<$filename"})> is called if the subroutine
-C<DB::postponed> exists. Here, the $filename is the expanded name of
-the C<require>d file, as found in the values of %INC.
-
-=item *
-
-After each subroutine C<subname> is compiled, the existence of
-C<$DB::postponed{subname}> is checked. If this key exists,
-C<DB::postponed(subname)> is called if the C<DB::postponed> subroutine
-also exists.
-
-=item *
-
-A hash C<%DB::sub> is maintained, whose keys are subroutine names
-and whose values have the form C<filename:startline-endline>.
-C<filename> has the form C<(eval 34)> for subroutines defined inside
-C<eval>s, or C<(re_eval 19)> for those within regex code assertions.
-
-=item *
-
-When the execution of your program reaches a point that can hold a
-breakpoint, the C<DB::DB()> subroutine is called if any of the variables
-C<$DB::trace>, C<$DB::single>, or C<$DB::signal> is true. These variables
-are not C<local>izable. This feature is disabled when executing
-inside C<DB::DB()>, including functions called from it
-unless C<< $^D & (1<<30) >> is true.
-
-=item *
-
-When execution of the program reaches a subroutine call, a call to
-C<&DB::sub>(I<args>) is made instead, with C<$DB::sub> holding the
-name of the called subroutine. (This doesn't happen if the subroutine
-was compiled in the C<DB> package.)
-
-=back
-
-Note that if C<&DB::sub> needs external data for it to work, no
-subroutine call is possible without it. As an example, the standard
-debugger's C<&DB::sub> depends on the C<$DB::deep> variable
-(it defines how many levels of recursion deep into the debugger you can go
-before a mandatory break). If C<$DB::deep> is not defined, subroutine
-calls are not possible, even though C<&DB::sub> exists.
-
-=head2 Writing Your Own Debugger
-
-=head3 Environment Variables
-
-The C<PERL5DB> environment variable can be used to define a debugger.
-For example, the minimal "working" debugger (it actually doesn't do anything)
-consists of one line:
-
- sub DB::DB {}
-
-It can easily be defined like this:
-
- $ PERL5DB="sub DB::DB {}" perl -d your-script
-
-Another brief debugger, slightly more useful, can be created
-with only the line:
-
- sub DB::DB {print ++$i; scalar <STDIN>}
-
-This debugger prints a number which increments for each statement
-encountered and waits for you to hit a newline before continuing
-to the next statement.
-
-The following debugger is actually useful:
-
- {
- package DB;
- sub DB {}
- sub sub {print ++$i, " $sub\n"; &$sub}
- }
-
-It prints the sequence number of each subroutine call and the name of the
-called subroutine. Note that C<&DB::sub> is being compiled into the
-package C<DB> through the use of the C<package> directive.
-
-When it starts, the debugger reads your rc file (F<./.perldb> or
-F<~/.perldb> under Unix), which can set important options.
-(A subroutine (C<&afterinit>) can be defined here as well; it is executed
-after the debugger completes its own initialization.)
-
-After the rc file is read, the debugger reads the PERLDB_OPTS
-environment variable and uses it to set debugger options. The
-contents of this variable are treated as if they were the argument
-of an C<o ...> debugger command (q.v. in L<perldebug/"Configurable Options">).
-
-=head3 Debugger Internal Variables
-
-In addition to the file and subroutine-related variables mentioned above,
-the debugger also maintains various magical internal variables.
-
-=over 4
-
-=item *
-
-C<@DB::dbline> is an alias for C<@{"::_<current_file"}>, which
-holds the lines of the currently-selected file (compiled by Perl), either
-explicitly chosen with the debugger's C<f> command, or implicitly by flow
-of execution.
-
-Values in this array are magical in numeric context: they compare
-equal to zero only if the line is not breakable.
-
-=item *
-
-C<%DB::dbline> is an alias for C<%{"::_<current_file"}>, which
-contains breakpoints and actions keyed by line number in
-the currently-selected file, either explicitly chosen with the
-debugger's C<f> command, or implicitly by flow of execution.
-
-As previously noted, individual entries (as opposed to the whole hash)
-are settable. Perl only cares about Boolean true here, although
-the values used by F<perl5db.pl> have the form
-C<"$break_condition\0$action">.
-
-=back
-
-=head3 Debugger Customization Functions
-
-Some functions are provided to simplify customization.
-
-=over 4
-
-=item *
-
-See L<perldebug/"Configurable Options"> for a description of options parsed by
-C<DB::parse_options(string)>.
-
-=item *
-
-C<DB::dump_trace(skip[,count])> skips the specified number of frames
-and returns a list containing information about the calling frames (all
-of them, if C<count> is missing). Each entry is reference to a hash
-with keys C<context> (either C<.>, C<$>, or C<@>), C<sub> (subroutine
-name, or info about C<eval>), C<args> (C<undef> or a reference to
-an array), C<file>, and C<line>.
-
-=item *
-
-C<DB::print_trace(FH, skip[, count[, short]])> prints
-formatted info about caller frames. The last two functions may be
-convenient as arguments to C<< < >>, C<< << >> commands.
-
-=back
-
-Note that any variables and functions that are not documented in
-this manpages (or in L<perldebug>) are considered for internal
-use only, and as such are subject to change without notice.
-
-=head1 Frame Listing Output Examples
-
-The C<frame> option can be used to control the output of frame
-information. For example, contrast this expression trace:
-
- $ perl -de 42
- Stack dump during die enabled outside of evals.
-
- Loading DB routines from perl5db.pl patch level 0.94
- Emacs support available.
-
- Enter h or 'h h' for help.
-
- main::(-e:1): 0
- DB<1> sub foo { 14 }
-
- DB<2> sub bar { 3 }
-
- DB<3> t print foo() * bar()
- main::((eval 172):3): print foo() + bar();
- main::foo((eval 168):2):
- main::bar((eval 170):2):
- 42
-
-with this one, once the C<o>ption C<frame=2> has been set:
-
- DB<4> o f=2
- frame = '2'
- DB<5> t print foo() * bar()
- 3: foo() * bar()
- entering main::foo
- 2: sub foo { 14 };
- exited main::foo
- entering main::bar
- 2: sub bar { 3 };
- exited main::bar
- 42
-
-By way of demonstration, we present below a laborious listing
-resulting from setting your C<PERLDB_OPTS> environment variable to
-the value C<f=n N>, and running I<perl -d -V> from the command line.
-Examples using various values of C<n> are shown to give you a feel
-for the difference between settings. Long though it may be, this
-is not a complete listing, but only excerpts.
-
-=over 4
-
-=item 1
-
- entering main::BEGIN
- entering Config::BEGIN
- Package lib/Exporter.pm.
- Package lib/Carp.pm.
- Package lib/Config.pm.
- entering Config::TIEHASH
- entering Exporter::import
- entering Exporter::export
- entering Config::myconfig
- entering Config::FETCH
- entering Config::FETCH
- entering Config::FETCH
- entering Config::FETCH
-
-=item 2
-
- entering main::BEGIN
- entering Config::BEGIN
- Package lib/Exporter.pm.
- Package lib/Carp.pm.
- exited Config::BEGIN
- Package lib/Config.pm.
- entering Config::TIEHASH
- exited Config::TIEHASH
- entering Exporter::import
- entering Exporter::export
- exited Exporter::export
- exited Exporter::import
- exited main::BEGIN
- entering Config::myconfig
- entering Config::FETCH
- exited Config::FETCH
- entering Config::FETCH
- exited Config::FETCH
- entering Config::FETCH
-
-=item 3
-
- in $=main::BEGIN() from /dev/null:0
- in $=Config::BEGIN() from lib/Config.pm:2
- Package lib/Exporter.pm.
- Package lib/Carp.pm.
- Package lib/Config.pm.
- in $=Config::TIEHASH('Config') from lib/Config.pm:644
- in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li
- in @=Config::myconfig() from /dev/null:0
- in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'osname') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'osvers') from lib/Config.pm:574
-
-=item 4
-
- in $=main::BEGIN() from /dev/null:0
- in $=Config::BEGIN() from lib/Config.pm:2
- Package lib/Exporter.pm.
- Package lib/Carp.pm.
- out $=Config::BEGIN() from lib/Config.pm:0
- Package lib/Config.pm.
- in $=Config::TIEHASH('Config') from lib/Config.pm:644
- out $=Config::TIEHASH('Config') from lib/Config.pm:644
- in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
- out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
- out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- out $=main::BEGIN() from /dev/null:0
- in @=Config::myconfig() from /dev/null:0
- in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
- out $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
- out $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
- out $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
-
-=item 5
-
- in $=main::BEGIN() from /dev/null:0
- in $=Config::BEGIN() from lib/Config.pm:2
- Package lib/Exporter.pm.
- Package lib/Carp.pm.
- out $=Config::BEGIN() from lib/Config.pm:0
- Package lib/Config.pm.
- in $=Config::TIEHASH('Config') from lib/Config.pm:644
- out $=Config::TIEHASH('Config') from lib/Config.pm:644
- in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
- out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
- out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- out $=main::BEGIN() from /dev/null:0
- in @=Config::myconfig() from /dev/null:0
- in $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
- out $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
- in $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
- out $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
-
-=item 6
-
- in $=CODE(0x15eca4)() from /dev/null:0
- in $=CODE(0x182528)() from lib/Config.pm:2
- Package lib/Exporter.pm.
- out $=CODE(0x182528)() from lib/Config.pm:0
- scalar context return from CODE(0x182528): undef
- Package lib/Config.pm.
- in $=Config::TIEHASH('Config') from lib/Config.pm:628
- out $=Config::TIEHASH('Config') from lib/Config.pm:628
- scalar context return from Config::TIEHASH: empty hash
- in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
- out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
- scalar context return from Exporter::export: ''
- out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- scalar context return from Exporter::import: ''
-
-=back
-
-In all cases shown above, the line indentation shows the call tree.
-If bit 2 of C<frame> is set, a line is printed on exit from a
-subroutine as well. If bit 4 is set, the arguments are printed
-along with the caller info. If bit 8 is set, the arguments are
-printed even if they are tied or references. If bit 16 is set, the
-return value is printed, too.
-
-When a package is compiled, a line like this
-
- Package lib/Carp.pm.
-
-is printed with proper indentation.
-
-=head1 Debugging Regular Expressions
-
-There are two ways to enable debugging output for regular expressions.
-
-If your perl is compiled with C<-DDEBUGGING>, you may use the
-B<-Dr> flag on the command line.
-
-Otherwise, one can C<use re 'debug'>, which has effects at
-compile time and run time. Since Perl 5.9.5, this pragma is lexically
-scoped.
-
-=head2 Compile-time Output
-
-The debugging output at compile time looks like this:
-
- Compiling REx '[bc]d(ef*g)+h[ij]k$'
- size 45 Got 364 bytes for offset annotations.
- first at 1
- rarest char g at 0
- rarest char d at 0
- 1: ANYOF[bc](12)
- 12: EXACT <d>(14)
- 14: CURLYX[0] {1,32767}(28)
- 16: OPEN1(18)
- 18: EXACT <e>(20)
- 20: STAR(23)
- 21: EXACT <f>(0)
- 23: EXACT <g>(25)
- 25: CLOSE1(27)
- 27: WHILEM[1/1](0)
- 28: NOTHING(29)
- 29: EXACT <h>(31)
- 31: ANYOF[ij](42)
- 42: EXACT <k>(44)
- 44: EOL(45)
- 45: END(0)
- anchored 'de' at 1 floating 'gh' at 3..2147483647 (checking floating)
- stclass 'ANYOF[bc]' minlen 7
- Offsets: [45]
- 1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
- 0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
- 11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
- 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]
- Omitting $` $& $' support.
-
-The first line shows the pre-compiled form of the regex. The second
-shows the size of the compiled form (in arbitrary units, usually
-4-byte words) and the total number of bytes allocated for the
-offset/length table, usually 4+C<size>*8. The next line shows the
-label I<id> of the first node that does a match.
-
-The
-
- anchored 'de' at 1 floating 'gh' at 3..2147483647 (checking floating)
- stclass 'ANYOF[bc]' minlen 7
-
-line (split into two lines above) contains optimizer
-information. In the example shown, the optimizer found that the match
-should contain a substring C<de> at offset 1, plus substring C<gh>
-at some offset between 3 and infinity. Moreover, when checking for
-these substrings (to abandon impossible matches quickly), Perl will check
-for the substring C<gh> before checking for the substring C<de>. The
-optimizer may also use the knowledge that the match starts (at the
-C<first> I<id>) with a character class, and no string
-shorter than 7 characters can possibly match.
-
-The fields of interest which may appear in this line are
-
-=over 4
-
-=item C<anchored> I<STRING> C<at> I<POS>
-
-=item C<floating> I<STRING> C<at> I<POS1..POS2>
-
-See above.
-
-=item C<matching floating/anchored>
-
-Which substring to check first.
-
-=item C<minlen>
-
-The minimal length of the match.
-
-=item C<stclass> I<TYPE>
-
-Type of first matching node.
-
-=item C<noscan>
-
-Don't scan for the found substrings.
-
-=item C<isall>
-
-Means that the optimizer information is all that the regular
-expression contains, and thus one does not need to enter the regex engine at
-all.
-
-=item C<GPOS>
-
-Set if the pattern contains C<\G>.
-
-=item C<plus>
-
-Set if the pattern starts with a repeated char (as in C<x+y>).
-
-=item C<implicit>
-
-Set if the pattern starts with C<.*>.
-
-=item C<with eval>
-
-Set if the pattern contain eval-groups, such as C<(?{ code })> and
-C<(??{ code })>.
-
-=item C<anchored(TYPE)>
-
-If the pattern may match only at a handful of places, with C<TYPE>
-being C<BOL>, C<MBOL>, or C<GPOS>. See the table below.
-
-=back
-
-If a substring is known to match at end-of-line only, it may be
-followed by C<$>, as in C<floating 'k'$>.
-
-The optimizer-specific information is used to avoid entering (a slow) regex
-engine on strings that will not definitely match. If the C<isall> flag
-is set, a call to the regex engine may be avoided even when the optimizer
-found an appropriate place for the match.
-
-Above the optimizer section is the list of I<nodes> of the compiled
-form of the regex. Each line has format
-
-C< >I<id>: I<TYPE> I<OPTIONAL-INFO> (I<next-id>)
-
-=head2 Types of Nodes
-
-Here are the possible types, with short descriptions:
-
- # TYPE arg-description [num-args] [longjump-len] DESCRIPTION
-
- # Exit points
- END no End of program.
- SUCCEED no Return from a subroutine, basically.
-
- # Anchors:
-
- BOL no Match "" at beginning of line.
- MBOL no Same, assuming multiline.
- SBOL no Same, assuming singleline.
- EOS no Match "" at end of string.
- EOL no Match "" at end of line.
- MEOL no Same, assuming multiline.
- SEOL no Same, assuming singleline.
- BOUND no Match "" at any word boundary using native charset
- semantics for non-utf8
- BOUNDL no Match "" at any locale word boundary
- BOUNDU no Match "" at any word boundary using Unicode semantics
- BOUNDA no Match "" at any word boundary using ASCII semantics
- NBOUND no Match "" at any word non-boundary using native charset
- semantics for non-utf8
- NBOUNDL no Match "" at any locale word non-boundary
- NBOUNDU no Match "" at any word non-boundary using Unicode semantics
- NBOUNDA no Match "" at any word non-boundary using ASCII semantics
- GPOS no Matches where last m//g left off.
-
- # [Special] alternatives:
-
- REG_ANY no Match any one character (except newline).
- SANY no Match any one character.
- CANY no Match any one byte.
- ANYOF sv Match character in (or not in) this class, single char
- match only
- ANYOFV sv Match character in (or not in) this class, can
- match-multiple chars
- ALNUM no Match any alphanumeric character using native charset
- semantics for non-utf8
- ALNUML no Match any alphanumeric char in locale
- ALNUMU no Match any alphanumeric char using Unicode semantics
- ALNUMA no Match [A-Za-z_0-9]
- NALNUM no Match any non-alphanumeric character using native charset
- semantics for non-utf8
- NALNUML no Match any non-alphanumeric char in locale
- NALNUMU no Match any non-alphanumeric char using Unicode semantics
- NALNUMA no Match [^A-Za-z_0-9]
- SPACE no Match any whitespace character using native charset
- semantics for non-utf8
- SPACEL no Match any whitespace char in locale
- SPACEU no Match any whitespace char using Unicode semantics
- SPACEA no Match [ \t\n\f\r]
- NSPACE no Match any non-whitespace character using native charset
- semantics for non-utf8
- NSPACEL no Match any non-whitespace char in locale
- NSPACEU no Match any non-whitespace char using Unicode semantics
- NSPACEA no Match [^ \t\n\f\r]
- DIGIT no Match any numeric character using native charset semantics
- for non-utf8
- DIGITL no Match any numeric character in locale
- DIGITA no Match [0-9]
- NDIGIT no Match any non-numeric character using native charset
- i semantics for non-utf8
- NDIGITL no Match any non-numeric character in locale
- NDIGITA no Match [^0-9]
- CLUMP no Match any extended grapheme cluster sequence
-
- # Alternation
-
- # BRANCH The set of branches constituting a single choice are hooked
- # together with their "next" pointers, since precedence prevents
- # anything being concatenated to any individual branch. The
- # "next" pointer of the last BRANCH in a choice points to the
- # thing following the whole choice. This is also where the
- # final "next" pointer of each individual branch points; each
- # branch starts with the operand node of a BRANCH node.
- #
- BRANCH node Match this alternative, or the next...
-
- # Back pointer
-
- # BACK Normal "next" pointers all implicitly point forward; BACK
- # exists to make loop structures possible.
- # not used
- BACK no Match "", "next" ptr points backward.
-
- # Literals
-
- EXACT str Match this string (preceded by length).
- EXACTF str Match this string, folded, native charset semantics for
- non-utf8 (prec. by length).
- EXACTFL str Match this string, folded in locale (w/len).
- EXACTFU str Match this string, folded, Unicode semantics for non-utf8
- (prec. by length).
- EXACTFA str Match this string, folded, Unicode semantics for non-utf8,
- but no ASCII-range character matches outside ASCII (prec.
- by length),.
-
- # Do nothing types
-
- NOTHING no Match empty string.
- # A variant of above which delimits a group, thus stops optimizations
- TAIL no Match empty string. Can jump here from outside.
-
- # Loops
-
- # STAR,PLUS '?', and complex '*' and '+', are implemented as circular
- # BRANCH structures using BACK. Simple cases (one character
- # per match) are implemented with STAR and PLUS for speed
- # and to minimize recursive plunges.
- #
- STAR node Match this (simple) thing 0 or more times.
- PLUS node Match this (simple) thing 1 or more times.
-
- CURLY sv 2 Match this simple thing {n,m} times.
- CURLYN no 2 Capture next-after-this simple thing
- CURLYM no 2 Capture this medium-complex thing {n,m} times.
- CURLYX sv 2 Match this complex thing {n,m} times.
-
- # This terminator creates a loop structure for CURLYX
- WHILEM no Do curly processing and see if rest matches.
-
- # Buffer related
-
- # OPEN,CLOSE,GROUPP ...are numbered at compile time.
- OPEN num 1 Mark this point in input as start of #n.
- CLOSE num 1 Analogous to OPEN.
-
- REF num 1 Match some already matched string
- REFF num 1 Match already matched string, folded using native charset
- semantics for non-utf8
- REFFL num 1 Match already matched string, folded in loc.
- REFFU num 1 Match already matched string, folded using unicode
- semantics for non-utf8
- REFFA num 1 Match already matched string, folded using unicode
- semantics for non-utf8, no mixing ASCII, non-ASCII
-
- # Named references. Code in regcomp.c assumes that these all are after the
- # numbered references
- NREF no-sv 1 Match some already matched string
- NREFF no-sv 1 Match already matched string, folded using native charset
- semantics for non-utf8
- NREFFL no-sv 1 Match already matched string, folded in loc.
- NREFFU num 1 Match already matched string, folded using unicode
- semantics for non-utf8
- NREFFA num 1 Match already matched string, folded using unicode
- semantics for non-utf8, no mixing ASCII, non-ASCII
-
- IFMATCH off 1 2 Succeeds if the following matches.
- UNLESSM off 1 2 Fails if the following matches.
- SUSPEND off 1 1 "Independent" sub-RE.
- IFTHEN off 1 1 Switch, should be preceded by switcher.
- GROUPP num 1 Whether the group matched.
-
- # Support for long RE
-
- LONGJMP off 1 1 Jump far away.
- BRANCHJ off 1 1 BRANCH with long offset.
-
- # The heavy worker
-
- EVAL evl 1 Execute some Perl code.
-
- # Modifiers
-
- MINMOD no Next operator is not greedy.
- LOGICAL no Next opcode should set the flag only.
-
- # This is not used yet
- RENUM off 1 1 Group with independently numbered parens.
-
- # Trie Related
-
- # Behave the same as A|LIST|OF|WORDS would. The '..C' variants have
- # inline charclass data (ascii only), the 'C' store it in the structure.
- # NOTE: the relative order of the TRIE-like regops is significant
-
- TRIE trie 1 Match many EXACT(F[ALU]?)? at once. flags==type
- TRIEC charclass Same as TRIE, but with embedded charclass data
-
- # For start classes, contains an added fail table.
- AHOCORASICK trie 1 Aho Corasick stclass. flags==type
- AHOCORASICKC charclass Same as AHOCORASICK, but with embedded charclass data
-
- # Regex Subroutines
- GOSUB num/ofs 2L recurse to paren arg1 at (signed) ofs arg2
- GOSTART no recurse to start of pattern
-
- # Special conditionals
- NGROUPP no-sv 1 Whether the group matched.
- INSUBP num 1 Whether we are in a specific recurse.
- DEFINEP none 1 Never execute directly.
-
- # Backtracking Verbs
- ENDLIKE none Used only for the type field of verbs
- OPFAIL none Same as (?!)
- ACCEPT parno 1 Accepts the current matched string.
-
-
- # Verbs With Arguments
- VERB no-sv 1 Used only for the type field of verbs
- PRUNE no-sv 1 Pattern fails at this startpoint if no-backtracking through this
- MARKPOINT no-sv 1 Push the current location for rollback by cut.
- SKIP no-sv 1 On failure skip forward (to the mark) before retrying
- COMMIT no-sv 1 Pattern fails outright if backtracking through this
- CUTGROUP no-sv 1 On failure go to the next alternation in the group
-
- # Control what to keep in $&.
- KEEPS no $& begins here.
-
- # New charclass like patterns
- LNBREAK none generic newline pattern
- VERTWS none vertical whitespace (Perl 6)
- NVERTWS none not vertical whitespace (Perl 6)
- HORIZWS none horizontal whitespace (Perl 6)
- NHORIZWS none not horizontal whitespace (Perl 6)
-
- FOLDCHAR codepoint 1 codepoint with tricky case folding properties.
-
- # SPECIAL REGOPS
-
- # This is not really a node, but an optimized away piece of a "long" node.
- # To simplify debugging output, we mark it as if it were a node
- OPTIMIZED off Placeholder for dump.
-
- # Special opcode with the property that no opcode in a compiled program
- # will ever be of this type. Thus it can be used as a flag value that
- # no other opcode has been seen. END is used similarly, in that an END
- # node cant be optimized. So END implies "unoptimizable" and PSEUDO mean
- # "not seen anything to optimize yet".
- PSEUDO off Pseudo opcode for internal use.
-
-=for unprinted-credits
-Next section M-J. Dominus (mjd-perl-patch+@plover.com) 20010421
-
-Following the optimizer information is a dump of the offset/length
-table, here split across several lines:
-
- Offsets: [45]
- 1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
- 0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
- 11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
- 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]
-
-The first line here indicates that the offset/length table contains 45
-entries. Each entry is a pair of integers, denoted by C<offset[length]>.
-Entries are numbered starting with 1, so entry #1 here is C<1[4]> and
-entry #12 is C<5[1]>. C<1[4]> indicates that the node labeled C<1:>
-(the C<1: ANYOF[bc]>) begins at character position 1 in the
-pre-compiled form of the regex, and has a length of 4 characters.
-C<5[1]> in position 12
-indicates that the node labeled C<12:>
-(the C<< 12: EXACT <d> >>) begins at character position 5 in the
-pre-compiled form of the regex, and has a length of 1 character.
-C<12[1]> in position 14
-indicates that the node labeled C<14:>
-(the C<< 14: CURLYX[0] {1,32767} >>) begins at character position 12 in the
-pre-compiled form of the regex, and has a length of 1 character---that
-is, it corresponds to the C<+> symbol in the precompiled regex.
-
-C<0[0]> items indicate that there is no corresponding node.
-
-=head2 Run-time Output
-
-First of all, when doing a match, one may get no run-time output even
-if debugging is enabled. This means that the regex engine was never
-entered and that all of the job was therefore done by the optimizer.
-
-If the regex engine was entered, the output may look like this:
-
- Matching '[bc]d(ef*g)+h[ij]k$' against 'abcdefg__gh__'
- Setting an EVAL scope, savestack=3
- 2 <ab> <cdefg__gh_> | 1: ANYOF
- 3 <abc> <defg__gh_> | 11: EXACT <d>
- 4 <abcd> <efg__gh_> | 13: CURLYX {1,32767}
- 4 <abcd> <efg__gh_> | 26: WHILEM
- 0 out of 1..32767 cc=effff31c
- 4 <abcd> <efg__gh_> | 15: OPEN1
- 4 <abcd> <efg__gh_> | 17: EXACT <e>
- 5 <abcde> <fg__gh_> | 19: STAR
- EXACT <f> can match 1 times out of 32767...
- Setting an EVAL scope, savestack=3
- 6 <bcdef> <g__gh__> | 22: EXACT <g>
- 7 <bcdefg> <__gh__> | 24: CLOSE1
- 7 <bcdefg> <__gh__> | 26: WHILEM
- 1 out of 1..32767 cc=effff31c
- Setting an EVAL scope, savestack=12
- 7 <bcdefg> <__gh__> | 15: OPEN1
- 7 <bcdefg> <__gh__> | 17: EXACT <e>
- restoring \1 to 4(4)..7
- failed, try continuation...
- 7 <bcdefg> <__gh__> | 27: NOTHING
- 7 <bcdefg> <__gh__> | 28: EXACT <h>
- failed...
- failed...
-
-The most significant information in the output is about the particular I<node>
-of the compiled regex that is currently being tested against the target string.
-The format of these lines is
-
-C< >I<STRING-OFFSET> <I<PRE-STRING>> <I<POST-STRING>> |I<ID>: I<TYPE>
-
-The I<TYPE> info is indented with respect to the backtracking level.
-Other incidental information appears interspersed within.
-
-=head1 Debugging Perl Memory Usage
-
-Perl is a profligate wastrel when it comes to memory use. There
-is a saying that to estimate memory usage of Perl, assume a reasonable
-algorithm for memory allocation, multiply that estimate by 10, and
-while you still may miss the mark, at least you won't be quite so
-astonished. This is not absolutely true, but may provide a good
-grasp of what happens.
-
-Assume that an integer cannot take less than 20 bytes of memory, a
-float cannot take less than 24 bytes, a string cannot take less
-than 32 bytes (all these examples assume 32-bit architectures, the
-result are quite a bit worse on 64-bit architectures). If a variable
-is accessed in two of three different ways (which require an integer,
-a float, or a string), the memory footprint may increase yet another
-20 bytes. A sloppy malloc(3) implementation can inflate these
-numbers dramatically.
-
-On the opposite end of the scale, a declaration like
-
- sub foo;
-
-may take up to 500 bytes of memory, depending on which release of Perl
-you're running.
-
-Anecdotal estimates of source-to-compiled code bloat suggest an
-eightfold increase. This means that the compiled form of reasonable
-(normally commented, properly indented etc.) code will take
-about eight times more space in memory than the code took
-on disk.
-
-The B<-DL> command-line switch is obsolete since circa Perl 5.6.0
-(it was available only if Perl was built with C<-DDEBUGGING>).
-The switch was used to track Perl's memory allocations and possible
-memory leaks. These days the use of malloc debugging tools like
-F<Purify> or F<valgrind> is suggested instead. See also
-L<perlhacktips/PERL_MEM_LOG>.
-
-One way to find out how much memory is being used by Perl data
-structures is to install the Devel::Size module from CPAN: it gives
-you the minimum number of bytes required to store a particular data
-structure. Please be mindful of the difference between the size()
-and total_size().
-
-If Perl has been compiled using Perl's malloc you can analyze Perl
-memory usage by setting $ENV{PERL_DEBUG_MSTATS}.
-
-=head2 Using C<$ENV{PERL_DEBUG_MSTATS}>
-
-If your perl is using Perl's malloc() and was compiled with the
-necessary switches (this is the default), then it will print memory
-usage statistics after compiling your code when C<< $ENV{PERL_DEBUG_MSTATS}
-> 1 >>, and before termination of the program when C<<
-$ENV{PERL_DEBUG_MSTATS} >= 1 >>. The report format is similar to
-the following example:
-
- $ PERL_DEBUG_MSTATS=2 perl -e "require Carp"
- Memory allocation statistics after compilation: (buckets 4(4)..8188(8192)
- 14216 free: 130 117 28 7 9 0 2 2 1 0 0
- 437 61 36 0 5
- 60924 used: 125 137 161 55 7 8 6 16 2 0 1
- 74 109 304 84 20
- Total sbrk(): 77824/21:119. Odd ends: pad+heads+chain+tail: 0+636+0+2048.
- Memory allocation statistics after execution: (buckets 4(4)..8188(8192)
- 30888 free: 245 78 85 13 6 2 1 3 2 0 1
- 315 162 39 42 11
- 175816 used: 265 176 1112 111 26 22 11 27 2 1 1
- 196 178 1066 798 39
- Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144.
-
-It is possible to ask for such a statistic at arbitrary points in
-your execution using the mstat() function out of the standard
-Devel::Peek module.
-
-Here is some explanation of that format:
-
-=over 4
-
-=item C<buckets SMALLEST(APPROX)..GREATEST(APPROX)>
-
-Perl's malloc() uses bucketed allocations. Every request is rounded
-up to the closest bucket size available, and a bucket is taken from
-the pool of buckets of that size.
-
-The line above describes the limits of buckets currently in use.
-Each bucket has two sizes: memory footprint and the maximal size
-of user data that can fit into this bucket. Suppose in the above
-example that the smallest bucket were size 4. The biggest bucket
-would have usable size 8188, and the memory footprint would be 8192.
-
-In a Perl built for debugging, some buckets may have negative usable
-size. This means that these buckets cannot (and will not) be used.
-For larger buckets, the memory footprint may be one page greater
-than a power of 2. If so, the corresponding power of two is
-printed in the C<APPROX> field above.
-
-=item Free/Used
-
-The 1 or 2 rows of numbers following that correspond to the number
-of buckets of each size between C<SMALLEST> and C<GREATEST>. In
-the first row, the sizes (memory footprints) of buckets are powers
-of two--or possibly one page greater. In the second row, if present,
-the memory footprints of the buckets are between the memory footprints
-of two buckets "above".
-
-For example, suppose under the previous example, the memory footprints
-were
-
- free: 8 16 32 64 128 256 512 1024 2048 4096 8192
- 4 12 24 48 80
-
-With a non-C<DEBUGGING> perl, the buckets starting from C<128> have
-a 4-byte overhead, and thus an 8192-long bucket may take up to
-8188-byte allocations.
-
-=item C<Total sbrk(): SBRKed/SBRKs:CONTINUOUS>
-
-The first two fields give the total amount of memory perl sbrk(2)ed
-(ess-broken? :-) and number of sbrk(2)s used. The third number is
-what perl thinks about continuity of returned chunks. So long as
-this number is positive, malloc() will assume that it is probable
-that sbrk(2) will provide continuous memory.
-
-Memory allocated by external libraries is not counted.
-
-=item C<pad: 0>
-
-The amount of sbrk(2)ed memory needed to keep buckets aligned.
-
-=item C<heads: 2192>
-
-Although memory overhead of bigger buckets is kept inside the bucket, for
-smaller buckets, it is kept in separate areas. This field gives the
-total size of these areas.
-
-=item C<chain: 0>
-
-malloc() may want to subdivide a bigger bucket into smaller buckets.
-If only a part of the deceased bucket is left unsubdivided, the rest
-is kept as an element of a linked list. This field gives the total
-size of these chunks.
-
-=item C<tail: 6144>
-
-To minimize the number of sbrk(2)s, malloc() asks for more memory. This
-field gives the size of the yet unused part, which is sbrk(2)ed, but
-never touched.
-
-=back
-
-=head1 SEE ALSO
-
-L<perldebug>,
-L<perlguts>,
-L<perlrun>
-L<re>,
-and
-L<Devel::DProf>.
diff --git a/Master/tlpkg/tlperl/lib/pods/perldebtut.pod b/Master/tlpkg/tlperl/lib/pods/perldebtut.pod
deleted file mode 100644
index cc4f5051e17..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perldebtut.pod
+++ /dev/null
@@ -1,722 +0,0 @@
-=head1 NAME
-
-perldebtut - Perl debugging tutorial
-
-=head1 DESCRIPTION
-
-A (very) lightweight introduction in the use of the perl debugger, and a
-pointer to existing, deeper sources of information on the subject of debugging
-perl programs.
-
-There's an extraordinary number of people out there who don't appear to know
-anything about using the perl debugger, though they use the language every
-day.
-This is for them.
-
-
-=head1 use strict
-
-First of all, there's a few things you can do to make your life a lot more
-straightforward when it comes to debugging perl programs, without using the
-debugger at all. To demonstrate, here's a simple script, named "hello", with
-a problem:
-
- #!/usr/bin/perl
-
- $var1 = 'Hello World'; # always wanted to do that :-)
- $var2 = "$varl\n";
-
- print $var2;
- exit;
-
-While this compiles and runs happily, it probably won't do what's expected,
-namely it doesn't print "Hello World\n" at all; It will on the other hand do
-exactly what it was told to do, computers being a bit that way inclined. That
-is, it will print out a newline character, and you'll get what looks like a
-blank line. It looks like there's 2 variables when (because of the typo)
-there's really 3:
-
- $var1 = 'Hello World';
- $varl = undef;
- $var2 = "\n";
-
-To catch this kind of problem, we can force each variable to be declared
-before use by pulling in the strict module, by putting 'use strict;' after the
-first line of the script.
-
-Now when you run it, perl complains about the 3 undeclared variables and we
-get four error messages because one variable is referenced twice:
-
- Global symbol "$var1" requires explicit package name at ./t1 line 4.
- Global symbol "$var2" requires explicit package name at ./t1 line 5.
- Global symbol "$varl" requires explicit package name at ./t1 line 5.
- Global symbol "$var2" requires explicit package name at ./t1 line 7.
- Execution of ./hello aborted due to compilation errors.
-
-Luvverly! and to fix this we declare all variables explicitly and now our
-script looks like this:
-
- #!/usr/bin/perl
- use strict;
-
- my $var1 = 'Hello World';
- my $varl = undef;
- my $var2 = "$varl\n";
-
- print $var2;
- exit;
-
-We then do (always a good idea) a syntax check before we try to run it again:
-
- > perl -c hello
- hello syntax OK
-
-And now when we run it, we get "\n" still, but at least we know why. Just
-getting this script to compile has exposed the '$varl' (with the letter 'l')
-variable, and simply changing $varl to $var1 solves the problem.
-
-
-=head1 Looking at data and -w and v
-
-Ok, but how about when you want to really see your data, what's in that
-dynamic variable, just before using it?
-
- #!/usr/bin/perl
- use strict;
-
- my $key = 'welcome';
- my %data = (
- 'this' => qw(that),
- 'tom' => qw(and jerry),
- 'welcome' => q(Hello World),
- 'zip' => q(welcome),
- );
- my @data = keys %data;
-
- print "$data{$key}\n";
- exit;
-
-Looks OK, after it's been through the syntax check (perl -c scriptname), we
-run it and all we get is a blank line again! Hmmmm.
-
-One common debugging approach here, would be to liberally sprinkle a few print
-statements, to add a check just before we print out our data, and another just
-after:
-
- print "All OK\n" if grep($key, keys %data);
- print "$data{$key}\n";
- print "done: '$data{$key}'\n";
-
-And try again:
-
- > perl data
- All OK
-
- done: ''
-
-After much staring at the same piece of code and not seeing the wood for the
-trees for some time, we get a cup of coffee and try another approach. That
-is, we bring in the cavalry by giving perl the 'B<-d>' switch on the command
-line:
-
- > perl -d data
- Default die handler restored.
-
- Loading DB routines from perl5db.pl version 1.07
- Editor support available.
-
- Enter h or `h h' for help, or `man perldebug' for more help.
-
- main::(./data:4): my $key = 'welcome';
-
-Now, what we've done here is to launch the built-in perl debugger on our
-script. It's stopped at the first line of executable code and is waiting for
-input.
-
-Before we go any further, you'll want to know how to quit the debugger: use
-just the letter 'B<q>', not the words 'quit' or 'exit':
-
- DB<1> q
- >
-
-That's it, you're back on home turf again.
-
-
-=head1 help
-
-Fire the debugger up again on your script and we'll look at the help menu.
-There's a couple of ways of calling help: a simple 'B<h>' will get the summary
-help list, 'B<|h>' (pipe-h) will pipe the help through your pager (which is
-(probably 'more' or 'less'), and finally, 'B<h h>' (h-space-h) will give you
-the entire help screen. Here is the summary page:
-
-DB<1>h
-
- List/search source lines: Control script execution:
- l [ln|sub] List source code T Stack trace
- - or . List previous/current line s [expr] Single step [in expr]
- v [line] View around line n [expr] Next, steps over subs
- f filename View source in file <CR/Enter> Repeat last n or s
- /pattern/ ?patt? Search forw/backw r Return from subroutine
- M Show module versions c [ln|sub] Continue until position
- Debugger controls: L List break/watch/actions
- o [...] Set debugger options t [expr] Toggle trace [trace expr]
- <[<]|{[{]|>[>] [cmd] Do pre/post-prompt b [ln|event|sub] [cnd] Set breakpoint
- ! [N|pat] Redo a previous command B ln|* Delete a/all breakpoints
- H [-num] Display last num commands a [ln] cmd Do cmd before line
- = [a val] Define/list an alias A ln|* Delete a/all actions
- h [db_cmd] Get help on command w expr Add a watch expression
- h h Complete help page W expr|* Delete a/all watch exprs
- |[|]db_cmd Send output to pager ![!] syscmd Run cmd in a subprocess
- q or ^D Quit R Attempt a restart
- Data Examination: expr Execute perl code, also see: s,n,t expr
- x|m expr Evals expr in list context, dumps the result or lists methods.
- p expr Print expression (uses script's current package).
- S [[!]pat] List subroutine names [not] matching pattern
- V [Pk [Vars]] List Variables in Package. Vars can be ~pattern or !pattern.
- X [Vars] Same as "V current_package [Vars]".
- y [n [Vars]] List lexicals in higher scope <n>. Vars same as V.
- For more help, type h cmd_letter, or run man perldebug for all docs.
-
-More confusing options than you can shake a big stick at! It's not as bad as
-it looks and it's very useful to know more about all of it, and fun too!
-
-There's a couple of useful ones to know about straight away. You wouldn't
-think we're using any libraries at all at the moment, but 'B<M>' will show
-which modules are currently loaded, and their version number, while 'B<m>'
-will show the methods, and 'B<S>' shows all subroutines (by pattern) as
-shown below. 'B<V>' and 'B<X>' show variables in the program by package
-scope and can be constrained by pattern.
-
- DB<2>S str
- dumpvar::stringify
- strict::bits
- strict::import
- strict::unimport
-
-Using 'X' and cousins requires you not to use the type identifiers ($@%), just
-the 'name':
-
- DM<3>X ~err
- FileHandle(stderr) => fileno(2)
-
-Remember we're in our tiny program with a problem, we should have a look at
-where we are, and what our data looks like. First of all let's view some code
-at our present position (the first line of code in this case), via 'B<v>':
-
- DB<4> v
- 1 #!/usr/bin/perl
- 2: use strict;
- 3
- 4==> my $key = 'welcome';
- 5: my %data = (
- 6 'this' => qw(that),
- 7 'tom' => qw(and jerry),
- 8 'welcome' => q(Hello World),
- 9 'zip' => q(welcome),
- 10 );
-
-At line number 4 is a helpful pointer, that tells you where you are now. To
-see more code, type 'v' again:
-
- DB<4> v
- 8 'welcome' => q(Hello World),
- 9 'zip' => q(welcome),
- 10 );
- 11: my @data = keys %data;
- 12: print "All OK\n" if grep($key, keys %data);
- 13: print "$data{$key}\n";
- 14: print "done: '$data{$key}'\n";
- 15: exit;
-
-And if you wanted to list line 5 again, type 'l 5', (note the space):
-
- DB<4> l 5
- 5: my %data = (
-
-In this case, there's not much to see, but of course normally there's pages of
-stuff to wade through, and 'l' can be very useful. To reset your view to the
-line we're about to execute, type a lone period '.':
-
- DB<5> .
- main::(./data_a:4): my $key = 'welcome';
-
-The line shown is the one that is about to be executed B<next>, it hasn't
-happened yet. So while we can print a variable with the letter 'B<p>', at
-this point all we'd get is an empty (undefined) value back. What we need to
-do is to step through the next executable statement with an 'B<s>':
-
- DB<6> s
- main::(./data_a:5): my %data = (
- main::(./data_a:6): 'this' => qw(that),
- main::(./data_a:7): 'tom' => qw(and jerry),
- main::(./data_a:8): 'welcome' => q(Hello World),
- main::(./data_a:9): 'zip' => q(welcome),
- main::(./data_a:10): );
-
-Now we can have a look at that first ($key) variable:
-
- DB<7> p $key
- welcome
-
-line 13 is where the action is, so let's continue down to there via the letter
-'B<c>', which by the way, inserts a 'one-time-only' breakpoint at the given
-line or sub routine:
-
- DB<8> c 13
- All OK
- main::(./data_a:13): print "$data{$key}\n";
-
-We've gone past our check (where 'All OK' was printed) and have stopped just
-before the meat of our task. We could try to print out a couple of variables
-to see what is happening:
-
- DB<9> p $data{$key}
-
-Not much in there, lets have a look at our hash:
-
- DB<10> p %data
- Hello Worldziptomandwelcomejerrywelcomethisthat
-
- DB<11> p keys %data
- Hello Worldtomwelcomejerrythis
-
-Well, this isn't very easy to read, and using the helpful manual (B<h h>), the
-'B<x>' command looks promising:
-
- DB<12> x %data
- 0 'Hello World'
- 1 'zip'
- 2 'tom'
- 3 'and'
- 4 'welcome'
- 5 undef
- 6 'jerry'
- 7 'welcome'
- 8 'this'
- 9 'that'
-
-That's not much help, a couple of welcomes in there, but no indication of
-which are keys, and which are values, it's just a listed array dump and, in
-this case, not particularly helpful. The trick here, is to use a B<reference>
-to the data structure:
-
- DB<13> x \%data
- 0 HASH(0x8194bc4)
- 'Hello World' => 'zip'
- 'jerry' => 'welcome'
- 'this' => 'that'
- 'tom' => 'and'
- 'welcome' => undef
-
-The reference is truly dumped and we can finally see what we're dealing with.
-Our quoting was perfectly valid but wrong for our purposes, with 'and jerry'
-being treated as 2 separate words rather than a phrase, thus throwing the
-evenly paired hash structure out of alignment.
-
-The 'B<-w>' switch would have told us about this, had we used it at the start,
-and saved us a lot of trouble:
-
- > perl -w data
- Odd number of elements in hash assignment at ./data line 5.
-
-We fix our quoting: 'tom' => q(and jerry), and run it again, this time we get
-our expected output:
-
- > perl -w data
- Hello World
-
-
-While we're here, take a closer look at the 'B<x>' command, it's really useful
-and will merrily dump out nested references, complete objects, partial objects
-- just about whatever you throw at it:
-
-Let's make a quick object and x-plode it, first we'll start the debugger:
-it wants some form of input from STDIN, so we give it something non-committal,
-a zero:
-
- > perl -de 0
- Default die handler restored.
-
- Loading DB routines from perl5db.pl version 1.07
- Editor support available.
-
- Enter h or `h h' for help, or `man perldebug' for more help.
-
- main::(-e:1): 0
-
-Now build an on-the-fly object over a couple of lines (note the backslash):
-
- DB<1> $obj = bless({'unique_id'=>'123', 'attr'=> \
- cont: {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
-
-And let's have a look at it:
-
- DB<2> x $obj
- 0 MY_class=HASH(0x828ad98)
- 'attr' => HASH(0x828ad68)
- 'col' => 'black'
- 'things' => ARRAY(0x828abb8)
- 0 'this'
- 1 'that'
- 2 'etc'
- 'unique_id' => 123
- DB<3>
-
-Useful, huh? You can eval nearly anything in there, and experiment with bits
-of code or regexes until the cows come home:
-
- DB<3> @data = qw(this that the other atheism leather theory scythe)
-
- DB<4> p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
- atheism
- leather
- other
- scythe
- the
- theory
- saw -> 6
-
-If you want to see the command History, type an 'B<H>':
-
- DB<5> H
- 4: p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
- 3: @data = qw(this that the other atheism leather theory scythe)
- 2: x $obj
- 1: $obj = bless({'unique_id'=>'123', 'attr'=>
- {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
- DB<5>
-
-And if you want to repeat any previous command, use the exclamation: 'B<!>':
-
- DB<5> !4
- p 'saw -> '.($cnt += map { print "$_\n" } grep(/the/, sort @data))
- atheism
- leather
- other
- scythe
- the
- theory
- saw -> 12
-
-For more on references see L<perlref> and L<perlreftut>
-
-
-=head1 Stepping through code
-
-Here's a simple program which converts between Celsius and Fahrenheit, it too
-has a problem:
-
- #!/usr/bin/perl -w
- use strict;
-
- my $arg = $ARGV[0] || '-c20';
-
- if ($arg =~ /^\-(c|f)((\-|\+)*\d+(\.\d+)*)$/) {
- my ($deg, $num) = ($1, $2);
- my ($in, $out) = ($num, $num);
- if ($deg eq 'c') {
- $deg = 'f';
- $out = &c2f($num);
- } else {
- $deg = 'c';
- $out = &f2c($num);
- }
- $out = sprintf('%0.2f', $out);
- $out =~ s/^((\-|\+)*\d+)\.0+$/$1/;
- print "$out $deg\n";
- } else {
- print "Usage: $0 -[c|f] num\n";
- }
- exit;
-
- sub f2c {
- my $f = shift;
- my $c = 5 * $f - 32 / 9;
- return $c;
- }
-
- sub c2f {
- my $c = shift;
- my $f = 9 * $c / 5 + 32;
- return $f;
- }
-
-
-For some reason, the Fahrenheit to Celsius conversion fails to return the
-expected output. This is what it does:
-
- > temp -c0.72
- 33.30 f
-
- > temp -f33.3
- 162.94 c
-
-Not very consistent! We'll set a breakpoint in the code manually and run it
-under the debugger to see what's going on. A breakpoint is a flag, to which
-the debugger will run without interruption, when it reaches the breakpoint, it
-will stop execution and offer a prompt for further interaction. In normal
-use, these debugger commands are completely ignored, and they are safe - if a
-little messy, to leave in production code.
-
- my ($in, $out) = ($num, $num);
- $DB::single=2; # insert at line 9!
- if ($deg eq 'c')
- ...
-
- > perl -d temp -f33.3
- Default die handler restored.
-
- Loading DB routines from perl5db.pl version 1.07
- Editor support available.
-
- Enter h or `h h' for help, or `man perldebug' for more help.
-
- main::(temp:4): my $arg = $ARGV[0] || '-c100';
-
-We'll simply continue down to our pre-set breakpoint with a 'B<c>':
-
- DB<1> c
- main::(temp:10): if ($deg eq 'c') {
-
-Followed by a view command to see where we are:
-
- DB<1> v
- 7: my ($deg, $num) = ($1, $2);
- 8: my ($in, $out) = ($num, $num);
- 9: $DB::single=2;
- 10==> if ($deg eq 'c') {
- 11: $deg = 'f';
- 12: $out = &c2f($num);
- 13 } else {
- 14: $deg = 'c';
- 15: $out = &f2c($num);
- 16 }
-
-And a print to show what values we're currently using:
-
- DB<1> p $deg, $num
- f33.3
-
-We can put another break point on any line beginning with a colon, we'll use
-line 17 as that's just as we come out of the subroutine, and we'd like to
-pause there later on:
-
- DB<2> b 17
-
-There's no feedback from this, but you can see what breakpoints are set by
-using the list 'L' command:
-
- DB<3> L
- temp:
- 17: print "$out $deg\n";
- break if (1)
-
-Note that to delete a breakpoint you use 'B'.
-
-Now we'll continue down into our subroutine, this time rather than by line
-number, we'll use the subroutine name, followed by the now familiar 'v':
-
- DB<3> c f2c
- main::f2c(temp:30): my $f = shift;
-
- DB<4> v
- 24: exit;
- 25
- 26 sub f2c {
- 27==> my $f = shift;
- 28: my $c = 5 * $f - 32 / 9;
- 29: return $c;
- 30 }
- 31
- 32 sub c2f {
- 33: my $c = shift;
-
-
-Note that if there was a subroutine call between us and line 29, and we wanted
-to B<single-step> through it, we could use the 'B<s>' command, and to step
-over it we would use 'B<n>' which would execute the sub, but not descend into
-it for inspection. In this case though, we simply continue down to line 29:
-
- DB<4> c 29
- main::f2c(temp:29): return $c;
-
-And have a look at the return value:
-
- DB<5> p $c
- 162.944444444444
-
-This is not the right answer at all, but the sum looks correct. I wonder if
-it's anything to do with operator precedence? We'll try a couple of other
-possibilities with our sum:
-
- DB<6> p (5 * $f - 32 / 9)
- 162.944444444444
-
- DB<7> p 5 * $f - (32 / 9)
- 162.944444444444
-
- DB<8> p (5 * $f) - 32 / 9
- 162.944444444444
-
- DB<9> p 5 * ($f - 32) / 9
- 0.722222222222221
-
-:-) that's more like it! Ok, now we can set our return variable and we'll
-return out of the sub with an 'r':
-
- DB<10> $c = 5 * ($f - 32) / 9
-
- DB<11> r
- scalar context return from main::f2c: 0.722222222222221
-
-Looks good, let's just continue off the end of the script:
-
- DB<12> c
- 0.72 c
- Debugged program terminated. Use q to quit or R to restart,
- use O inhibit_exit to avoid stopping after program termination,
- h q, h R or h O to get additional info.
-
-A quick fix to the offending line (insert the missing parentheses) in the
-actual program and we're finished.
-
-
-=head1 Placeholder for a, w, t, T
-
-Actions, watch variables, stack traces etc.: on the TODO list.
-
- a
-
- w
-
- t
-
- T
-
-
-=head1 REGULAR EXPRESSIONS
-
-Ever wanted to know what a regex looked like? You'll need perl compiled with
-the DEBUGGING flag for this one:
-
- > perl -Dr -e '/^pe(a)*rl$/i'
- Compiling REx `^pe(a)*rl$'
- size 17 first at 2
- rarest char
- at 0
- 1: BOL(2)
- 2: EXACTF <pe>(4)
- 4: CURLYN[1] {0,32767}(14)
- 6: NOTHING(8)
- 8: EXACTF <a>(0)
- 12: WHILEM(0)
- 13: NOTHING(14)
- 14: EXACTF <rl>(16)
- 16: EOL(17)
- 17: END(0)
- floating `'$ at 4..2147483647 (checking floating) stclass `EXACTF <pe>'
-anchored(BOL) minlen 4
- Omitting $` $& $' support.
-
- EXECUTING...
-
- Freeing REx: `^pe(a)*rl$'
-
-Did you really want to know? :-)
-For more gory details on getting regular expressions to work, have a look at
-L<perlre>, L<perlretut>, and to decode the mysterious labels (BOL and CURLYN,
-etc. above), see L<perldebguts>.
-
-
-=head1 OUTPUT TIPS
-
-To get all the output from your error log, and not miss any messages via
-helpful operating system buffering, insert a line like this, at the start of
-your script:
-
- $|=1;
-
-To watch the tail of a dynamically growing logfile, (from the command line):
-
- tail -f $error_log
-
-Wrapping all die calls in a handler routine can be useful to see how, and from
-where, they're being called, L<perlvar> has more information:
-
- BEGIN { $SIG{__DIE__} = sub { require Carp; Carp::confess(@_) } }
-
-Various useful techniques for the redirection of STDOUT and STDERR filehandles
-are explained in L<perlopentut> and L<perlfaq8>.
-
-
-=head1 CGI
-
-Just a quick hint here for all those CGI programmers who can't figure out how
-on earth to get past that 'waiting for input' prompt, when running their CGI
-script from the command-line, try something like this:
-
- > perl -d my_cgi.pl -nodebug
-
-Of course L<CGI> and L<perlfaq9> will tell you more.
-
-
-=head1 GUIs
-
-The command line interface is tightly integrated with an B<emacs> extension
-and there's a B<vi> interface too.
-
-You don't have to do this all on the command line, though, there are a few GUI
-options out there. The nice thing about these is you can wave a mouse over a
-variable and a dump of its data will appear in an appropriate window, or in a
-popup balloon, no more tiresome typing of 'x $varname' :-)
-
-In particular have a hunt around for the following:
-
-B<ptkdb> perlTK based wrapper for the built-in debugger
-
-B<ddd> data display debugger
-
-B<PerlDevKit> and B<PerlBuilder> are NT specific
-
-NB. (more info on these and others would be appreciated).
-
-
-=head1 SUMMARY
-
-We've seen how to encourage good coding practices with B<use strict> and
-B<-w>. We can run the perl debugger B<perl -d scriptname> to inspect your
-data from within the perl debugger with the B<p> and B<x> commands. You can
-walk through your code, set breakpoints with B<b> and step through that code
-with B<s> or B<n>, continue with B<c> and return from a sub with B<r>. Fairly
-intuitive stuff when you get down to it.
-
-There is of course lots more to find out about, this has just scratched the
-surface. The best way to learn more is to use perldoc to find out more about
-the language, to read the on-line help (L<perldebug> is probably the next
-place to go), and of course, experiment.
-
-
-=head1 SEE ALSO
-
-L<perldebug>,
-L<perldebguts>,
-L<perldiag>,
-L<perlrun>
-
-
-=head1 AUTHOR
-
-Richard Foley <richard.foley@rfi.net> Copyright (c) 2000
-
-
-=head1 CONTRIBUTORS
-
-Various people have made helpful suggestions and contributions, in particular:
-
-Ronald J Kimball <rjk@linguist.dartmouth.edu>
-
-Hugo van der Sanden <hv@crypt0.demon.co.uk>
-
-Peter Scott <Peter@PSDT.com>
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perldebug.pod b/Master/tlpkg/tlperl/lib/pods/perldebug.pod
deleted file mode 100644
index 4a2f07e8e72..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perldebug.pod
+++ /dev/null
@@ -1,1226 +0,0 @@
-=head1 NAME
-X<debug> X<debugger>
-
-perldebug - Perl debugging
-
-=head1 DESCRIPTION
-
-First of all, have you tried using the B<-w> switch?
-
-
-If you're new to the Perl debugger, you may prefer to read
-L<perldebtut>, which is a tutorial introduction to the debugger.
-
-=head1 The Perl Debugger
-
-If you invoke Perl with the B<-d> switch, your script runs under the
-Perl source debugger. This works like an interactive Perl
-environment, prompting for debugger commands that let you examine
-source code, set breakpoints, get stack backtraces, change the values of
-variables, etc. This is so convenient that you often fire up
-the debugger all by itself just to test out Perl constructs
-interactively to see what they do. For example:
-X<-d>
-
- $ perl -d -e 42
-
-In Perl, the debugger is not a separate program the way it usually is in the
-typical compiled environment. Instead, the B<-d> flag tells the compiler
-to insert source information into the parse trees it's about to hand off
-to the interpreter. That means your code must first compile correctly
-for the debugger to work on it. Then when the interpreter starts up, it
-preloads a special Perl library file containing the debugger.
-
-The program will halt I<right before> the first run-time executable
-statement (but see below regarding compile-time statements) and ask you
-to enter a debugger command. Contrary to popular expectations, whenever
-the debugger halts and shows you a line of code, it always displays the
-line it's I<about> to execute, rather than the one it has just executed.
-
-Any command not recognized by the debugger is directly executed
-(C<eval>'d) as Perl code in the current package. (The debugger
-uses the DB package for keeping its own state information.)
-
-Note that the said C<eval> is bound by an implicit scope. As a
-result any newly introduced lexical variable or any modified
-capture buffer content is lost after the eval. The debugger is a
-nice environment to learn Perl, but if you interactively experiment using
-material which should be in the same scope, stuff it in one line.
-
-For any text entered at the debugger prompt, leading and trailing whitespace
-is first stripped before further processing. If a debugger command
-coincides with some function in your own program, merely precede the
-function with something that doesn't look like a debugger command, such
-as a leading C<;> or perhaps a C<+>, or by wrapping it with parentheses
-or braces.
-
-=head2 Calling the Debugger
-
-There are several ways to call the debugger:
-
-=over 4
-
-=item perl -d program_name
-
-On the given program identified by C<program_name>.
-
-=item perl -d -e 0
-
-Interactively supply an arbitrary C<expression> using C<-e>.
-
-=item perl -d:Ptkdb program_name
-
-Debug a given program via the C<Devel::Ptkdb> GUI.
-
-=item perl -dt threaded_program_name
-
-Debug a given program using threads (experimental).
-
-=back
-
-=head2 Debugger Commands
-
-The interactive debugger understands the following commands:
-
-=over 12
-
-=item h
-X<debugger command, h>
-
-Prints out a summary help message
-
-=item h [command]
-
-Prints out a help message for the given debugger command.
-
-=item h h
-
-The special argument of C<h h> produces the entire help page, which is quite long.
-
-If the output of the C<h h> command (or any command, for that matter) scrolls
-past your screen, precede the command with a leading pipe symbol so
-that it's run through your pager, as in
-
- DB> |h h
-
-You may change the pager which is used via C<o pager=...> command.
-
-=item p expr
-X<debugger command, p>
-
-Same as C<print {$DB::OUT} expr> in the current package. In particular,
-because this is just Perl's own C<print> function, this means that nested
-data structures and objects are not dumped, unlike with the C<x> command.
-
-The C<DB::OUT> filehandle is opened to F</dev/tty>, regardless of
-where STDOUT may be redirected to.
-
-=item x [maxdepth] expr
-X<debugger command, x>
-
-Evaluates its expression in list context and dumps out the result in a
-pretty-printed fashion. Nested data structures are printed out
-recursively, unlike the real C<print> function in Perl. When dumping
-hashes, you'll probably prefer 'x \%h' rather than 'x %h'.
-See L<Dumpvalue> if you'd like to do this yourself.
-
-The output format is governed by multiple options described under
-L<"Configurable Options">.
-
-If the C<maxdepth> is included, it must be a numeral I<N>; the value is
-dumped only I<N> levels deep, as if the C<dumpDepth> option had been
-temporarily set to I<N>.
-
-=item V [pkg [vars]]
-X<debugger command, V>
-
-Display all (or some) variables in package (defaulting to C<main>)
-using a data pretty-printer (hashes show their keys and values so
-you see what's what, control characters are made printable, etc.).
-Make sure you don't put the type specifier (like C<$>) there, just
-the symbol names, like this:
-
- V DB filename line
-
-Use C<~pattern> and C<!pattern> for positive and negative regexes.
-
-This is similar to calling the C<x> command on each applicable var.
-
-=item X [vars]
-X<debugger command, X>
-
-Same as C<V currentpackage [vars]>.
-
-=item y [level [vars]]
-X<debugger command, y>
-
-Display all (or some) lexical variables (mnemonic: C<mY> variables)
-in the current scope or I<level> scopes higher. You can limit the
-variables that you see with I<vars> which works exactly as it does
-for the C<V> and C<X> commands. Requires the C<PadWalker> module
-version 0.08 or higher; will warn if this isn't installed. Output
-is pretty-printed in the same style as for C<V> and the format is
-controlled by the same options.
-
-=item T
-X<debugger command, T> X<backtrace> X<stack, backtrace>
-
-Produce a stack backtrace. See below for details on its output.
-
-=item s [expr]
-X<debugger command, s> X<step>
-
-Single step. Executes until the beginning of another
-statement, descending into subroutine calls. If an expression is
-supplied that includes function calls, it too will be single-stepped.
-
-=item n [expr]
-X<debugger command, n>
-
-Next. Executes over subroutine calls, until the beginning
-of the next statement. If an expression is supplied that includes
-function calls, those functions will be executed with stops before
-each statement.
-
-=item r
-X<debugger command, r>
-
-Continue until the return from the current subroutine.
-Dump the return value if the C<PrintRet> option is set (default).
-
-=item <CR>
-
-Repeat last C<n> or C<s> command.
-
-=item c [line|sub]
-X<debugger command, c>
-
-Continue, optionally inserting a one-time-only breakpoint
-at the specified line or subroutine.
-
-=item l
-X<debugger command, l>
-
-List next window of lines.
-
-=item l min+incr
-
-List C<incr+1> lines starting at C<min>.
-
-=item l min-max
-
-List lines C<min> through C<max>. C<l -> is synonymous to C<->.
-
-=item l line
-
-List a single line.
-
-=item l subname
-
-List first window of lines from subroutine. I<subname> may
-be a variable that contains a code reference.
-
-=item -
-X<debugger command, ->
-
-List previous window of lines.
-
-=item v [line]
-X<debugger command, v>
-
-View a few lines of code around the current line.
-
-=item .
-X<debugger command, .>
-
-Return the internal debugger pointer to the line last
-executed, and print out that line.
-
-=item f filename
-X<debugger command, f>
-
-Switch to viewing a different file or C<eval> statement. If I<filename>
-is not a full pathname found in the values of %INC, it is considered
-a regex.
-
-C<eval>ed strings (when accessible) are considered to be filenames:
-C<f (eval 7)> and C<f eval 7\b> access the body of the 7th C<eval>ed string
-(in the order of execution). The bodies of the currently executed C<eval>
-and of C<eval>ed strings that define subroutines are saved and thus
-accessible.
-
-=item /pattern/
-
-Search forwards for pattern (a Perl regex); final / is optional.
-The search is case-insensitive by default.
-
-=item ?pattern?
-
-Search backwards for pattern; final ? is optional.
-The search is case-insensitive by default.
-
-=item L [abw]
-X<debugger command, L>
-
-List (default all) actions, breakpoints and watch expressions
-
-=item S [[!]regex]
-X<debugger command, S>
-
-List subroutine names [not] matching the regex.
-
-=item t [n]
-X<debugger command, t>
-
-Toggle trace mode (see also the C<AutoTrace> option).
-Optional argument is the maximum number of levels to trace below
-the current one; anything deeper than that will be silent.
-
-=item t [n] expr
-X<debugger command, t>
-
-Trace through execution of C<expr>.
-Optional first argument is the maximum number of levels to trace below
-the current one; anything deeper than that will be silent.
-See L<perldebguts/"Frame Listing Output Examples"> for examples.
-
-=item b
-X<breakpoint>
-X<debugger command, b>
-
-Sets breakpoint on current line
-
-=item b [line] [condition]
-X<breakpoint>
-X<debugger command, b>
-
-Set a breakpoint before the given line. If a condition
-is specified, it's evaluated each time the statement is reached: a
-breakpoint is taken only if the condition is true. Breakpoints may
-only be set on lines that begin an executable statement. Conditions
-don't use C<if>:
-
- b 237 $x > 30
- b 237 ++$count237 < 11
- b 33 /pattern/i
-
-If the line number is C<.>, sets a breakpoint on the current line:
-
- b . $n > 100
-
-=item b [file]:[line] [condition]
-X<breakpoint>
-X<debugger command, b>
-
-Set a breakpoint before the given line in a (possibly different) file. If a
-condition is specified, it's evaluated each time the statement is reached: a
-breakpoint is taken only if the condition is true. Breakpoints may only be set
-on lines that begin an executable statement. Conditions don't use C<if>:
-
- b lib/MyModule.pm:237 $x > 30
- b /usr/lib/perl5/site_perl/CGI.pm:100 ++$count100 < 11
-
-=item b subname [condition]
-X<breakpoint>
-X<debugger command, b>
-
-Set a breakpoint before the first line of the named subroutine. I<subname> may
-be a variable containing a code reference (in this case I<condition>
-is not supported).
-
-=item b postpone subname [condition]
-X<breakpoint>
-X<debugger command, b>
-
-Set a breakpoint at first line of subroutine after it is compiled.
-
-=item b load filename
-X<breakpoint>
-X<debugger command, b>
-
-Set a breakpoint before the first executed line of the I<filename>,
-which should be a full pathname found amongst the %INC values.
-
-=item b compile subname
-X<breakpoint>
-X<debugger command, b>
-
-Sets a breakpoint before the first statement executed after the specified
-subroutine is compiled.
-
-=item B line
-X<breakpoint>
-X<debugger command, B>
-
-Delete a breakpoint from the specified I<line>.
-
-=item B *
-X<breakpoint>
-X<debugger command, B>
-
-Delete all installed breakpoints.
-
-=item disable [file]:[line]
-X<breakpoint>
-X<debugger command, disable>
-X<disable>
-
-Disable the breakpoint so it won't stop the execution of the program.
-Breakpoints are enabled by default and can be re-enabled using the C<enable>
-command.
-
-=item disable [line]
-X<breakpoint>
-X<debugger command, disable>
-X<disable>
-
-Disable the breakpoint so it won't stop the execution of the program.
-Breakpoints are enabled by default and can be re-enabled using the C<enable>
-command.
-
-This is done for a breakpoint in the current file.
-
-=item enable [file]:[line]
-X<breakpoint>
-X<debugger command, disable>
-X<disable>
-
-Enable the breakpoint so it will stop the execution of the program.
-
-=item enable [line]
-X<breakpoint>
-X<debugger command, disable>
-X<disable>
-
-Enable the breakpoint so it will stop the execution of the program.
-
-This is done for a breakpoint in the current file.
-
-=item a [line] command
-X<debugger command, a>
-
-Set an action to be done before the line is executed. If I<line> is
-omitted, set an action on the line about to be executed.
-The sequence of steps taken by the debugger is
-
- 1. check for a breakpoint at this line
- 2. print the line if necessary (tracing)
- 3. do any actions associated with that line
- 4. prompt user if at a breakpoint or in single-step
- 5. evaluate line
-
-For example, this will print out $foo every time line
-53 is passed:
-
- a 53 print "DB FOUND $foo\n"
-
-=item A line
-X<debugger command, A>
-
-Delete an action from the specified line.
-
-=item A *
-X<debugger command, A>
-
-Delete all installed actions.
-
-=item w expr
-X<debugger command, w>
-
-Add a global watch-expression. Whenever a watched global changes the
-debugger will stop and display the old and new values.
-
-=item W expr
-X<debugger command, W>
-
-Delete watch-expression
-
-=item W *
-X<debugger command, W>
-
-Delete all watch-expressions.
-
-=item o
-X<debugger command, o>
-
-Display all options.
-
-=item o booloption ...
-X<debugger command, o>
-
-Set each listed Boolean option to the value C<1>.
-
-=item o anyoption? ...
-X<debugger command, o>
-
-Print out the value of one or more options.
-
-=item o option=value ...
-X<debugger command, o>
-
-Set the value of one or more options. If the value has internal
-whitespace, it should be quoted. For example, you could set C<o
-pager="less -MQeicsNfr"> to call B<less> with those specific options.
-You may use either single or double quotes, but if you do, you must
-escape any embedded instances of same sort of quote you began with,
-as well as any escaping any escapes that immediately precede that
-quote but which are not meant to escape the quote itself. In other
-words, you follow single-quoting rules irrespective of the quote;
-eg: C<o option='this isn\'t bad'> or C<o option="She said, \"Isn't
-it?\"">.
-
-For historical reasons, the C<=value> is optional, but defaults to
-1 only where it is safe to do so--that is, mostly for Boolean
-options. It is always better to assign a specific value using C<=>.
-The C<option> can be abbreviated, but for clarity probably should
-not be. Several options can be set together. See L<"Configurable Options">
-for a list of these.
-
-=item < ?
-X<< debugger command, < >>
-
-List out all pre-prompt Perl command actions.
-
-=item < [ command ]
-X<< debugger command, < >>
-
-Set an action (Perl command) to happen before every debugger prompt.
-A multi-line command may be entered by backslashing the newlines.
-
-=item < *
-X<< debugger command, < >>
-
-Delete all pre-prompt Perl command actions.
-
-=item << command
-X<< debugger command, << >>
-
-Add an action (Perl command) to happen before every debugger prompt.
-A multi-line command may be entered by backwhacking the newlines.
-
-=item > ?
-X<< debugger command, > >>
-
-List out post-prompt Perl command actions.
-
-=item > command
-X<< debugger command, > >>
-
-Set an action (Perl command) to happen after the prompt when you've
-just given a command to return to executing the script. A multi-line
-command may be entered by backslashing the newlines (we bet you
-couldn't have guessed this by now).
-
-=item > *
-X<< debugger command, > >>
-
-Delete all post-prompt Perl command actions.
-
-=item >> command
-X<<< debugger command, >> >>>
-
-Adds an action (Perl command) to happen after the prompt when you've
-just given a command to return to executing the script. A multi-line
-command may be entered by backslashing the newlines.
-
-=item { ?
-X<debugger command, {>
-
-List out pre-prompt debugger commands.
-
-=item { [ command ]
-
-Set an action (debugger command) to happen before every debugger prompt.
-A multi-line command may be entered in the customary fashion.
-
-Because this command is in some senses new, a warning is issued if
-you appear to have accidentally entered a block instead. If that's
-what you mean to do, write it as with C<;{ ... }> or even
-C<do { ... }>.
-
-=item { *
-X<debugger command, {>
-
-Delete all pre-prompt debugger commands.
-
-=item {{ command
-X<debugger command, {{>
-
-Add an action (debugger command) to happen before every debugger prompt.
-A multi-line command may be entered, if you can guess how: see above.
-
-=item ! number
-X<debugger command, !>
-
-Redo a previous command (defaults to the previous command).
-
-=item ! -number
-X<debugger command, !>
-
-Redo number'th previous command.
-
-=item ! pattern
-X<debugger command, !>
-
-Redo last command that started with pattern.
-See C<o recallCommand>, too.
-
-=item !! cmd
-X<debugger command, !!>
-
-Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See
-C<o shellBang>, also. Note that the user's current shell (well,
-their C<$ENV{SHELL}> variable) will be used, which can interfere
-with proper interpretation of exit status or signal and coredump
-information.
-
-=item source file
-X<debugger command, source>
-
-Read and execute debugger commands from I<file>.
-I<file> may itself contain C<source> commands.
-
-=item H -number
-X<debugger command, H>
-
-Display last n commands. Only commands longer than one character are
-listed. If I<number> is omitted, list them all.
-
-=item q or ^D
-X<debugger command, q>
-X<debugger command, ^D>
-
-Quit. ("quit" doesn't work for this, unless you've made an alias)
-This is the only supported way to exit the debugger, though typing
-C<exit> twice might work.
-
-Set the C<inhibit_exit> option to 0 if you want to be able to step
-off the end the script. You may also need to set $finished to 0
-if you want to step through global destruction.
-
-=item R
-X<debugger command, R>
-
-Restart the debugger by C<exec()>ing a new session. We try to maintain
-your history across this, but internal settings and command-line options
-may be lost.
-
-The following setting are currently preserved: history, breakpoints,
-actions, debugger options, and the Perl command-line
-options B<-w>, B<-I>, and B<-e>.
-
-=item |dbcmd
-X<debugger command, |>
-
-Run the debugger command, piping DB::OUT into your current pager.
-
-=item ||dbcmd
-X<debugger command, ||>
-
-Same as C<|dbcmd> but DB::OUT is temporarily C<select>ed as well.
-
-=item = [alias value]
-X<debugger command, =>
-
-Define a command alias, like
-
- = quit q
-
-or list current aliases.
-
-=item command
-
-Execute command as a Perl statement. A trailing semicolon will be
-supplied. If the Perl statement would otherwise be confused for a
-Perl debugger, use a leading semicolon, too.
-
-=item m expr
-X<debugger command, m>
-
-List which methods may be called on the result of the evaluated
-expression. The expression may evaluated to a reference to a
-blessed object, or to a package name.
-
-=item M
-X<debugger command, M>
-
-Display all loaded modules and their versions.
-
-=item man [manpage]
-X<debugger command, man>
-
-Despite its name, this calls your system's default documentation
-viewer on the given page, or on the viewer itself if I<manpage> is
-omitted. If that viewer is B<man>, the current C<Config> information
-is used to invoke B<man> using the proper MANPATH or S<B<-M>
-I<manpath>> option. Failed lookups of the form C<XXX> that match
-known manpages of the form I<perlXXX> will be retried. This lets
-you type C<man debug> or C<man op> from the debugger.
-
-On systems traditionally bereft of a usable B<man> command, the
-debugger invokes B<perldoc>. Occasionally this determination is
-incorrect due to recalcitrant vendors or rather more felicitously,
-to enterprising users. If you fall into either category, just
-manually set the $DB::doccmd variable to whatever viewer to view
-the Perl documentation on your system. This may be set in an rc
-file, or through direct assignment. We're still waiting for a
-working example of something along the lines of:
-
- $DB::doccmd = 'netscape -remote http://something.here/';
-
-=back
-
-=head2 Configurable Options
-
-The debugger has numerous options settable using the C<o> command,
-either interactively or from the environment or an rc file.
-(./.perldb or ~/.perldb under Unix.)
-
-
-=over 12
-
-=item C<recallCommand>, C<ShellBang>
-X<debugger option, recallCommand>
-X<debugger option, ShellBang>
-
-The characters used to recall command or spawn shell. By
-default, both are set to C<!>, which is unfortunate.
-
-=item C<pager>
-X<debugger option, pager>
-
-Program to use for output of pager-piped commands (those beginning
-with a C<|> character.) By default, C<$ENV{PAGER}> will be used.
-Because the debugger uses your current terminal characteristics
-for bold and underlining, if the chosen pager does not pass escape
-sequences through unchanged, the output of some debugger commands
-will not be readable when sent through the pager.
-
-=item C<tkRunning>
-X<debugger option, tkRunning>
-
-Run Tk while prompting (with ReadLine).
-
-=item C<signalLevel>, C<warnLevel>, C<dieLevel>
-X<debugger option, signalLevel> X<debugger option, warnLevel>
-X<debugger option, dieLevel>
-
-Level of verbosity. By default, the debugger leaves your exceptions
-and warnings alone, because altering them can break correctly running
-programs. It will attempt to print a message when uncaught INT, BUS, or
-SEGV signals arrive. (But see the mention of signals in L</BUGS> below.)
-
-To disable this default safe mode, set these values to something higher
-than 0. At a level of 1, you get backtraces upon receiving any kind
-of warning (this is often annoying) or exception (this is
-often valuable). Unfortunately, the debugger cannot discern fatal
-exceptions from non-fatal ones. If C<dieLevel> is even 1, then your
-non-fatal exceptions are also traced and unceremoniously altered if they
-came from C<eval'ed> strings or from any kind of C<eval> within modules
-you're attempting to load. If C<dieLevel> is 2, the debugger doesn't
-care where they came from: It usurps your exception handler and prints
-out a trace, then modifies all exceptions with its own embellishments.
-This may perhaps be useful for some tracing purposes, but tends to hopelessly
-destroy any program that takes its exception handling seriously.
-
-=item C<AutoTrace>
-X<debugger option, AutoTrace>
-
-Trace mode (similar to C<t> command, but can be put into
-C<PERLDB_OPTS>).
-
-=item C<LineInfo>
-X<debugger option, LineInfo>
-
-File or pipe to print line number info to. If it is a pipe (say,
-C<|visual_perl_db>), then a short message is used. This is the
-mechanism used to interact with a slave editor or visual debugger,
-such as the special C<vi> or C<emacs> hooks, or the C<ddd> graphical
-debugger.
-
-=item C<inhibit_exit>
-X<debugger option, inhibit_exit>
-
-If 0, allows I<stepping off> the end of the script.
-
-=item C<PrintRet>
-X<debugger option, PrintRet>
-
-Print return value after C<r> command if set (default).
-
-=item C<ornaments>
-X<debugger option, ornaments>
-
-Affects screen appearance of the command line (see L<Term::ReadLine>).
-There is currently no way to disable these, which can render
-some output illegible on some displays, or with some pagers.
-This is considered a bug.
-
-=item C<frame>
-X<debugger option, frame>
-
-Affects the printing of messages upon entry and exit from subroutines. If
-C<frame & 2> is false, messages are printed on entry only. (Printing
-on exit might be useful if interspersed with other messages.)
-
-If C<frame & 4>, arguments to functions are printed, plus context
-and caller info. If C<frame & 8>, overloaded C<stringify> and
-C<tie>d C<FETCH> is enabled on the printed arguments. If C<frame
-& 16>, the return value from the subroutine is printed.
-
-The length at which the argument list is truncated is governed by the
-next option:
-
-=item C<maxTraceLen>
-X<debugger option, maxTraceLen>
-
-Length to truncate the argument list when the C<frame> option's
-bit 4 is set.
-
-=item C<windowSize>
-X<debugger option, windowSize>
-
-Change the size of code list window (default is 10 lines).
-
-=back
-
-The following options affect what happens with C<V>, C<X>, and C<x>
-commands:
-
-=over 12
-
-=item C<arrayDepth>, C<hashDepth>
-X<debugger option, arrayDepth> X<debugger option, hashDepth>
-
-Print only first N elements ('' for all).
-
-=item C<dumpDepth>
-X<debugger option, dumpDepth>
-
-Limit recursion depth to N levels when dumping structures.
-Negative values are interpreted as infinity. Default: infinity.
-
-=item C<compactDump>, C<veryCompact>
-X<debugger option, compactDump> X<debugger option, veryCompact>
-
-Change the style of array and hash output. If C<compactDump>, short array
-may be printed on one line.
-
-=item C<globPrint>
-X<debugger option, globPrint>
-
-Whether to print contents of globs.
-
-=item C<DumpDBFiles>
-X<debugger option, DumpDBFiles>
-
-Dump arrays holding debugged files.
-
-=item C<DumpPackages>
-X<debugger option, DumpPackages>
-
-Dump symbol tables of packages.
-
-=item C<DumpReused>
-X<debugger option, DumpReused>
-
-Dump contents of "reused" addresses.
-
-=item C<quote>, C<HighBit>, C<undefPrint>
-X<debugger option, quote> X<debugger option, HighBit>
-X<debugger option, undefPrint>
-
-Change the style of string dump. The default value for C<quote>
-is C<auto>; one can enable double-quotish or single-quotish format
-by setting it to C<"> or C<'>, respectively. By default, characters
-with their high bit set are printed verbatim.
-
-=item C<UsageOnly>
-X<debugger option, UsageOnly>
-
-Rudimentary per-package memory usage dump. Calculates total
-size of strings found in variables in the package. This does not
-include lexicals in a module's file scope, or lost in closures.
-
-=back
-
-After the rc file is read, the debugger reads the C<$ENV{PERLDB_OPTS}>
-environment variable and parses this as the remainder of a "O ..."
-line as one might enter at the debugger prompt. You may place the
-initialization options C<TTY>, C<noTTY>, C<ReadLine>, and C<NonStop>
-there.
-
-If your rc file contains:
-
- parse_options("NonStop=1 LineInfo=db.out AutoTrace");
-
-then your script will run without human intervention, putting trace
-information into the file I<db.out>. (If you interrupt it, you'd
-better reset C<LineInfo> to F</dev/tty> if you expect to see anything.)
-
-=over 12
-
-=item C<TTY>
-X<debugger option, TTY>
-
-The TTY to use for debugging I/O.
-
-=item C<noTTY>
-X<debugger option, noTTY>
-
-If set, the debugger goes into C<NonStop> mode and will not connect to a TTY. If
-interrupted (or if control goes to the debugger via explicit setting of
-$DB::signal or $DB::single from the Perl script), it connects to a TTY
-specified in the C<TTY> option at startup, or to a tty found at
-runtime using the C<Term::Rendezvous> module of your choice.
-
-This module should implement a method named C<new> that returns an object
-with two methods: C<IN> and C<OUT>. These should return filehandles to use
-for debugging input and output correspondingly. The C<new> method should
-inspect an argument containing the value of C<$ENV{PERLDB_NOTTY}> at
-startup, or C<"$ENV{HOME}/.perldbtty$$"> otherwise. This file is not
-inspected for proper ownership, so security hazards are theoretically
-possible.
-
-=item C<ReadLine>
-X<debugger option, ReadLine>
-
-If false, readline support in the debugger is disabled in order
-to debug applications that themselves use ReadLine.
-
-=item C<NonStop>
-X<debugger option, NonStop>
-
-If set, the debugger goes into non-interactive mode until interrupted, or
-programmatically by setting $DB::signal or $DB::single.
-
-=back
-
-Here's an example of using the C<$ENV{PERLDB_OPTS}> variable:
-
- $ PERLDB_OPTS="NonStop frame=2" perl -d myprogram
-
-That will run the script B<myprogram> without human intervention,
-printing out the call tree with entry and exit points. Note that
-C<NonStop=1 frame=2> is equivalent to C<N f=2>, and that originally,
-options could be uniquely abbreviated by the first letter (modulo
-the C<Dump*> options). It is nevertheless recommended that you
-always spell them out in full for legibility and future compatibility.
-
-Other examples include
-
- $ PERLDB_OPTS="NonStop LineInfo=listing frame=2" perl -d myprogram
-
-which runs script non-interactively, printing info on each entry
-into a subroutine and each executed line into the file named F<listing>.
-(If you interrupt it, you would better reset C<LineInfo> to something
-"interactive"!)
-
-Other examples include (using standard shell syntax to show environment
-variable settings):
-
- $ ( PERLDB_OPTS="NonStop frame=1 AutoTrace LineInfo=tperl.out"
- perl -d myprogram )
-
-which may be useful for debugging a program that uses C<Term::ReadLine>
-itself. Do not forget to detach your shell from the TTY in the window that
-corresponds to F</dev/ttyXX>, say, by issuing a command like
-
- $ sleep 1000000
-
-See L<perldebguts/"Debugger Internals"> for details.
-
-=head2 Debugger Input/Output
-
-=over 8
-
-=item Prompt
-
-The debugger prompt is something like
-
- DB<8>
-
-or even
-
- DB<<17>>
-
-where that number is the command number, and which you'd use to
-access with the built-in B<csh>-like history mechanism. For example,
-C<!17> would repeat command number 17. The depth of the angle
-brackets indicates the nesting depth of the debugger. You could
-get more than one set of brackets, for example, if you'd already
-at a breakpoint and then printed the result of a function call that
-itself has a breakpoint, or you step into an expression via C<s/n/t
-expression> command.
-
-=item Multiline commands
-
-If you want to enter a multi-line command, such as a subroutine
-definition with several statements or a format, escape the newline
-that would normally end the debugger command with a backslash.
-Here's an example:
-
- DB<1> for (1..4) { \
- cont: print "ok\n"; \
- cont: }
- ok
- ok
- ok
- ok
-
-Note that this business of escaping a newline is specific to interactive
-commands typed into the debugger.
-
-=item Stack backtrace
-X<backtrace> X<stack, backtrace>
-
-Here's an example of what a stack backtrace via C<T> command might
-look like:
-
- $ = main::infested called from file 'Ambulation.pm' line 10
- @ = Ambulation::legs(1, 2, 3, 4) called from file 'camel_flea' line 7
- $ = main::pests('bactrian', 4) called from file 'camel_flea' line 4
-
-The left-hand character up there indicates the context in which the
-function was called, with C<$> and C<@> meaning scalar or list
-contexts respectively, and C<.> meaning void context (which is
-actually a sort of scalar context). The display above says
-that you were in the function C<main::infested> when you ran the
-stack dump, and that it was called in scalar context from line
-10 of the file I<Ambulation.pm>, but without any arguments at all,
-meaning it was called as C<&infested>. The next stack frame shows
-that the function C<Ambulation::legs> was called in list context
-from the I<camel_flea> file with four arguments. The last stack
-frame shows that C<main::pests> was called in scalar context,
-also from I<camel_flea>, but from line 4.
-
-If you execute the C<T> command from inside an active C<use>
-statement, the backtrace will contain both a C<require> frame and
-an C<eval> frame.
-
-=item Line Listing Format
-
-This shows the sorts of output the C<l> command can produce:
-
- DB<<13>> l
- 101: @i{@i} = ();
- 102:b @isa{@i,$pack} = ()
- 103 if(exists $i{$prevpack} || exists $isa{$pack});
- 104 }
- 105
- 106 next
- 107==> if(exists $isa{$pack});
- 108
- 109:a if ($extra-- > 0) {
- 110: %isa = ($pack,1);
-
-Breakable lines are marked with C<:>. Lines with breakpoints are
-marked by C<b> and those with actions by C<a>. The line that's
-about to be executed is marked by C<< ==> >>.
-
-Please be aware that code in debugger listings may not look the same
-as your original source code. Line directives and external source
-filters can alter the code before Perl sees it, causing code to move
-from its original positions or take on entirely different forms.
-
-=item Frame listing
-
-When the C<frame> option is set, the debugger would print entered (and
-optionally exited) subroutines in different styles. See L<perldebguts>
-for incredibly long examples of these.
-
-=back
-
-=head2 Debugging Compile-Time Statements
-
-If you have compile-time executable statements (such as code within
-BEGIN, UNITCHECK and CHECK blocks or C<use> statements), these will
-I<not> be stopped by debugger, although C<require>s and INIT blocks
-will, and compile-time statements can be traced with the C<AutoTrace>
-option set in C<PERLDB_OPTS>). From your own Perl code, however, you
-can transfer control back to the debugger using the following
-statement, which is harmless if the debugger is not running:
-
- $DB::single = 1;
-
-If you set C<$DB::single> to 2, it's equivalent to having
-just typed the C<n> command, whereas a value of 1 means the C<s>
-command. The C<$DB::trace> variable should be set to 1 to simulate
-having typed the C<t> command.
-
-Another way to debug compile-time code is to start the debugger, set a
-breakpoint on the I<load> of some module:
-
- DB<7> b load f:/perllib/lib/Carp.pm
- Will stop on load of 'f:/perllib/lib/Carp.pm'.
-
-and then restart the debugger using the C<R> command (if possible). One can use C<b
-compile subname> for the same purpose.
-
-=head2 Debugger Customization
-
-The debugger probably contains enough configuration hooks that you
-won't ever have to modify it yourself. You may change the behaviour
-of the debugger from within the debugger using its C<o> command, from
-the command line via the C<PERLDB_OPTS> environment variable, and
-from customization files.
-
-You can do some customization by setting up a F<.perldb> file, which
-contains initialization code. For instance, you could make aliases
-like these (the last one is one people expect to be there):
-
- $DB::alias{'len'} = 's/^len(.*)/p length($1)/';
- $DB::alias{'stop'} = 's/^stop (at|in)/b/';
- $DB::alias{'ps'} = 's/^ps\b/p scalar /';
- $DB::alias{'quit'} = 's/^quit(\s*)/exit/';
-
-You can change options from F<.perldb> by using calls like this one;
-
- parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2");
-
-The code is executed in the package C<DB>. Note that F<.perldb> is
-processed before processing C<PERLDB_OPTS>. If F<.perldb> defines the
-subroutine C<afterinit>, that function is called after debugger
-initialization ends. F<.perldb> may be contained in the current
-directory, or in the home directory. Because this file is sourced
-in by Perl and may contain arbitrary commands, for security reasons,
-it must be owned by the superuser or the current user, and writable
-by no one but its owner.
-
-You can mock TTY input to debugger by adding arbitrary commands to
-@DB::typeahead. For example, your F<.perldb> file might contain:
-
- sub afterinit { push @DB::typeahead, "b 4", "b 6"; }
-
-Which would attempt to set breakpoints on lines 4 and 6 immediately
-after debugger initialization. Note that @DB::typeahead is not a supported
-interface and is subject to change in future releases.
-
-If you want to modify the debugger, copy F<perl5db.pl> from the
-Perl library to another name and hack it to your heart's content.
-You'll then want to set your C<PERL5DB> environment variable to say
-something like this:
-
- BEGIN { require "myperl5db.pl" }
-
-As a last resort, you could also use C<PERL5DB> to customize the debugger
-by directly setting internal variables or calling debugger functions.
-
-Note that any variables and functions that are not documented in
-this document (or in L<perldebguts>) are considered for internal
-use only, and as such are subject to change without notice.
-
-=head2 Readline Support / History in the Debugger
-
-As shipped, the only command-line history supplied is a simplistic one
-that checks for leading exclamation points. However, if you install
-the Term::ReadKey and Term::ReadLine modules from CPAN (such as
-Term::ReadLine::Gnu, Term::ReadLine::Perl, ...) you will
-have full editing capabilities much like those GNU I<readline>(3) provides.
-Look for these in the F<modules/by-module/Term> directory on CPAN.
-These do not support normal B<vi> command-line editing, however.
-
-A rudimentary command-line completion is also available, including
-lexical variables in the current scope if the C<PadWalker> module
-is installed.
-
-Without Readline support you may see the symbols "^[[A", "^[[C", "^[[B",
-"^[[D"", "^H", ... when using the arrow keys and/or the backspace key.
-
-=head2 Editor Support for Debugging
-
-If you have the FSF's version of B<emacs> installed on your system,
-it can interact with the Perl debugger to provide an integrated
-software development environment reminiscent of its interactions
-with C debuggers.
-
-Recent versions of Emacs come with a
-start file for making B<emacs> act like a
-syntax-directed editor that understands (some of) Perl's syntax.
-See L<perlfaq3>.
-
-A similar setup by Tom Christiansen for interacting with any
-vendor-shipped B<vi> and the X11 window system is also available.
-This works similarly to the integrated multiwindow support that
-B<emacs> provides, where the debugger drives the editor. At the
-time of this writing, however, that tool's eventual location in the
-Perl distribution was uncertain.
-
-Users of B<vi> should also look into B<vim> and B<gvim>, the mousey
-and windy version, for coloring of Perl keywords.
-
-Note that only perl can truly parse Perl, so all such CASE tools
-fall somewhat short of the mark, especially if you don't program
-your Perl as a C programmer might.
-
-=head2 The Perl Profiler
-X<profile> X<profiling> X<profiler>
-
-If you wish to supply an alternative debugger for Perl to run,
-invoke your script with a colon and a package argument given to the
-B<-d> flag. Perl's alternative debuggers include a Perl profiler,
-L<Devel::NYTProf>, which is available separately as a CPAN
-distribution. To profile your Perl program in the file F<mycode.pl>,
-just type:
-
- $ perl -d:NYTProf mycode.pl
-
-When the script terminates the profiler will create a database of the
-profile information that you can turn into reports using the profiler's
-tools. See <perlperf> for details.
-
-=head1 Debugging Regular Expressions
-X<regular expression, debugging>
-X<regex, debugging> X<regexp, debugging>
-
-C<use re 'debug'> enables you to see the gory details of how the Perl
-regular expression engine works. In order to understand this typically
-voluminous output, one must not only have some idea about how regular
-expression matching works in general, but also know how Perl's regular
-expressions are internally compiled into an automaton. These matters
-are explored in some detail in
-L<perldebguts/"Debugging Regular Expressions">.
-
-=head1 Debugging Memory Usage
-X<memory usage>
-
-Perl contains internal support for reporting its own memory usage,
-but this is a fairly advanced concept that requires some understanding
-of how memory allocation works.
-See L<perldebguts/"Debugging Perl Memory Usage"> for the details.
-
-=head1 SEE ALSO
-
-You did try the B<-w> switch, didn't you?
-
-L<perldebtut>,
-L<perldebguts>,
-L<re>,
-L<DB>,
-L<Devel::NYTProf>,
-L<Dumpvalue>,
-and
-L<perlrun>.
-
-When debugging a script that uses #! and is thus normally found in
-$PATH, the -S option causes perl to search $PATH for it, so you don't
-have to type the path or C<which $scriptname>.
-
- $ perl -Sd foo.pl
-
-=head1 BUGS
-
-You cannot get stack frame information or in any fashion debug functions
-that were not compiled by Perl, such as those from C or C++ extensions.
-
-If you alter your @_ arguments in a subroutine (such as with C<shift>
-or C<pop>), the stack backtrace will not show the original values.
-
-The debugger does not currently work in conjunction with the B<-W>
-command-line switch, because it itself is not free of warnings.
-
-If you're in a slow syscall (like C<wait>ing, C<accept>ing, or C<read>ing
-from your keyboard or a socket) and haven't set up your own C<$SIG{INT}>
-handler, then you won't be able to CTRL-C your way back to the debugger,
-because the debugger's own C<$SIG{INT}> handler doesn't understand that
-it needs to raise an exception to longjmp(3) out of slow syscalls.
diff --git a/Master/tlpkg/tlperl/lib/pods/perldelta.pod b/Master/tlpkg/tlperl/lib/pods/perldelta.pod
deleted file mode 100644
index d41e3b5cfe3..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perldelta.pod
+++ /dev/null
@@ -1,125 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perldelta - what is new for perl v5.16.2
-
-=head1 DESCRIPTION
-
-This document describes differences between the 5.16.1 release and
-the 5.16.2 release.
-
-If you are upgrading from an earlier release such as 5.16.0, first read
-L<perl5161delta>, which describes differences between 5.16.0 and
-5.16.1.
-
-=head1 Incompatible Changes
-
-There are no changes intentionally incompatible with 5.16.0
-If any exist, they are bugs, and we request that you submit a
-report. See L</Reporting Bugs> below.
-
-=head1 Modules and Pragmata
-
-=head2 Updated Modules and Pragmata
-
-=over 4
-
-=item *
-
-L<Module::CoreList> has been upgraded from version 2.70 to version 2.76.
-
-=back
-
-=head1 Configuration and Compilation
-
-=over 4
-
-=item * configuration should no longer be confused by ls colorization
-
-=back
-
-=head1 Platform Support
-
-=head2 Platform-Specific Notes
-
-=over 4
-
-=item AIX
-
-Configure now always adds -qlanglvl=extc99 to the CC flags on AIX when
-using xlC. This will make it easier to compile a number of XS-based modules
-that assume C99 [perl #113778].
-
-=back
-
-=head1 Selected Bug Fixes
-
-=over 4
-
-=item * fix /\h/ equivalence with /[\h]/
-
-see [perl #114220]
-
-=back
-
-=head1 Known Problems
-
-There are no new known problems.
-
-=head1 Acknowledgements
-
-Perl 5.16.2 represents approximately 2 months of development since Perl
-5.16.1 and contains approximately 740 lines of changes across 20 files
-from 9 authors.
-
-Perl continues to flourish into its third decade thanks to a vibrant
-community of users and developers. The following people are known to
-have contributed the improvements that became Perl 5.16.2:
-
-Andy Dougherty, Craig A. Berry, Darin McBride, Dominic Hargreaves, Karen
-Etheridge, Karl Williamson, Peter Martini, Ricardo Signes, Tony Cook.
-
-The list above is almost certainly incomplete as it is automatically
-generated from version control history. In particular, it does not
-include the names of the (very much appreciated) contributors who
-reported issues to the Perl bug tracker.
-
-For a more complete list of all of Perl's historical contributors,
-please see the F<AUTHORS> file in the Perl source distribution.
-
-=head1 Reporting Bugs
-
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://rt.perl.org/perlbug/ . There may also be
-information at http://www.perl.org/ , the Perl Home Page.
-
-If you believe you have an unreported bug, please run the L<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team.
-
-If the bug you are reporting has security implications, which make it
-inappropriate to send to a publicly archived mailing list, then please
-send it to perl5-security-report@perl.org. This points to a closed
-subscription unarchived mailing list, which includes all the core
-committers, who will be able to help assess the impact of issues, figure
-out a resolution, and help co-ordinate the release of patches to
-mitigate or fix the problem across all platforms on which Perl is
-supported. Please only use this address for security issues in the Perl
-core, not for modules independently distributed on CPAN.
-
-=head1 SEE ALSO
-
-The F<Changes> file for an explanation of how to view exhaustive details
-on what changed.
-
-The F<INSTALL> file for how to build Perl.
-
-The F<README> file for general stuff.
-
-The F<Artistic> and F<Copying> files for copyright information.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perldgux.pod b/Master/tlpkg/tlperl/lib/pods/perldgux.pod
deleted file mode 100644
index fd6eaa3baa1..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perldgux.pod
+++ /dev/null
@@ -1,117 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see perlpod manpage) which is
-specially designed to be readable as is.
-
-=head1 NAME
-
-perldgux - Perl under DG/UX.
-
-=head1 SYNOPSIS
-
-One can read this document in the following formats:
-
- man perldgux
- view perl perldgux
- explorer perldgux.html
- info perldgux
-
-to list some (not all may be available simultaneously), or it may
-be read I<as is>: as F<README.dgux>.
-
-=cut
-
-Contents
-
- perldgux - Perl under DG/UX.
-
- NAME
- SYNOPSIS
- DESCRIPTION
- BUILD
- - Non-threaded Case
- - Threaded Case
- - Testing
- - Installing the built perl
- AUTHOR
- SEE ALSO
-
-=head1 DESCRIPTION
-
-Perl 5.7/8.x for DG/UX ix86 R4.20MU0x
-
-=head1 BUILDING PERL ON DG/UX
-
-=head2 Non-threaded Perl on DG/UX
-
-Just run ./Configure script from the top directory.
-Then give "make" to compile.
-
-=head2 Threaded Perl on DG/UX
-
-If you are using as compiler GCC-2.95.x rev(DG/UX)
-an easy solution for configuring perl in your DG/UX
-machine is to run the command:
-
-./Configure -Dusethreads -Duseithreads -Dusedevel -des
-
-This will automatically accept all the defaults and
-in particular /usr/local/ as installation directory.
-Note that GCC-2.95.x rev(DG/UX) knows the switch
--pthread which allows it to link correctly DG/UX's
--lthread library.
-
-If you want to change the installation directory or
-have a standard DG/UX with C compiler GCC-2.7.2.x
-then you have no choice than to do an interactive
-build by issuing the command:
-
-./Configure -Dusethreads -Duseithreads
-
-In particular with GCC-2.7.2.x accept all the defaults
-and *watch* out for the message:
-
- Any additional ld flags (NOT including libraries)? [ -pthread]
-
-Instead of -pthread put here -lthread. CGCC-2.7.2.x
-that comes with the DG/UX OS does NOT know the -pthread
-switch. So your build will fail if you choose the defaults.
-After configuration is done correctly give "make" to compile.
-
-=head2 Testing Perl on DG/UX
-
-Issuing a "make test" will run all the tests.
-If the test lib/ftmp-security gives you as a result
-something like
-
- lib/ftmp-security....File::Temp::_gettemp:
- Parent directory (/tmp/) is not safe (sticky bit not set
- when world writable?) at lib/ftmp-security.t line 100
-
-don't panic and just set the sticky bit in your /tmp
-directory by doing the following as root:
-
-cd /
-chmod +t /tmp (=set the sticky bit to /tmp).
-
-Then rerun the tests. This time all must be OK.
-
-=head2 Installing the built perl on DG/UX
-
-Run the command "make install"
-
-=head1 AUTHOR
-
-Takis Psarogiannakopoulos
-University of Cambridge
-Centre for Mathematical Sciences
-Department of Pure Mathematics
-Wilberforce road
-Cambridge CB3 0WB , UK
-email <takis@XFree86.Org>
-
-=head1 SEE ALSO
-
-perl(1).
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perldiag.pod b/Master/tlpkg/tlperl/lib/pods/perldiag.pod
deleted file mode 100644
index 9a8c9347a88..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perldiag.pod
+++ /dev/null
@@ -1,5763 +0,0 @@
-=head1 NAME
-
-perldiag - various Perl diagnostics
-
-=head1 DESCRIPTION
-
-These messages are classified as follows (listed in increasing order of
-desperation):
-
- (W) A warning (optional).
- (D) A deprecation (enabled by default).
- (S) A severe warning (enabled by default).
- (F) A fatal error (trappable).
- (P) An internal error you should never see (trappable).
- (X) A very fatal error (nontrappable).
- (A) An alien error message (not generated by Perl).
-
-The majority of messages from the first three classifications above
-(W, D & S) can be controlled using the C<warnings> pragma.
-
-If a message can be controlled by the C<warnings> pragma, its warning
-category is included with the classification letter in the description
-below.
-
-Optional warnings are enabled by using the C<warnings> pragma or the B<-w>
-and B<-W> switches. Warnings may be captured by setting C<$SIG{__WARN__}>
-to a reference to a routine that will be called on each warning instead
-of printing it. See L<perlvar>.
-
-Severe warnings are always enabled, unless they are explicitly disabled
-with the C<warnings> pragma or the B<-X> switch.
-
-Trappable errors may be trapped using the eval operator. See
-L<perlfunc/eval>. In almost all cases, warnings may be selectively
-disabled or promoted to fatal errors using the C<warnings> pragma.
-See L<warnings>.
-
-The messages are in alphabetical order, without regard to upper or
-lower-case. Some of these messages are generic. Spots that vary are
-denoted with a %s or other printf-style escape. These escapes are
-ignored by the alphabetical order, as are all characters other than
-letters. To look up your message, just ignore anything that is not a
-letter.
-
-=over 4
-
-=item accept() on closed socket %s
-
-(W closed) You tried to do an accept on a closed socket. Did you forget
-to check the return value of your socket() call? See
-L<perlfunc/accept>.
-
-=item Allocation too large: %x
-
-(X) You can't allocate more than 64K on an MS-DOS machine.
-
-=item '%c' allowed only after types %s
-
-(F) The modifiers '!', '<' and '>' are allowed in pack() or unpack() only
-after certain types. See L<perlfunc/pack>.
-
-=item Ambiguous call resolved as CORE::%s(), qualify as such or use &
-
-(W ambiguous) A subroutine you have declared has the same name as a Perl
-keyword, and you have used the name without qualification for calling
-one or the other. Perl decided to call the builtin because the
-subroutine is not imported.
-
-To force interpretation as a subroutine call, either put an ampersand
-before the subroutine name, or qualify the name with its package.
-Alternatively, you can import the subroutine (or pretend that it's
-imported with the C<use subs> pragma).
-
-To silently interpret it as the Perl operator, use the C<CORE::> prefix
-on the operator (e.g. C<CORE::log($x)>) or declare the subroutine
-to be an object method (see L<perlsub/"Subroutine Attributes"> or
-L<attributes>).
-
-=item Ambiguous range in transliteration operator
-
-(F) You wrote something like C<tr/a-z-0//> which doesn't mean anything at
-all. To include a C<-> character in a transliteration, put it either
-first or last. (In the past, C<tr/a-z-0//> was synonymous with
-C<tr/a-y//>, which was probably not what you would have expected.)
-
-=item Ambiguous use of %s resolved as %s
-
-(W ambiguous)(S) You said something that may not be interpreted the way
-you thought. Normally it's pretty easy to disambiguate it by supplying
-a missing quote, operator, parenthesis pair or declaration.
-
-=item Ambiguous use of %c resolved as operator %c
-
-(W ambiguous) C<%>, C<&>, and C<*> are both infix operators (modulus,
-bitwise and, and multiplication) I<and> initial special characters
-(denoting hashes, subroutines and typeglobs), and you said something
-like C<*foo * foo> that might be interpreted as either of them. We
-assumed you meant the infix operator, but please try to make it more
-clear -- in the example given, you might write C<*foo * foo()> if you
-really meant to multiply a glob by the result of calling a function.
-
-=item Ambiguous use of %c{%s} resolved to %c%s
-
-(W ambiguous) You wrote something like C<@{foo}>, which might be
-asking for the variable C<@foo>, or it might be calling a function
-named foo, and dereferencing it as an array reference. If you wanted
-the variable, you can just write C<@foo>. If you wanted to call the
-function, write C<@{foo()}> ... or you could just not have a variable
-and a function with the same name, and save yourself a lot of trouble.
-
-=item Ambiguous use of %c{%s[...]} resolved to %c%s[...]
-
-=item Ambiguous use of %c{%s{...}} resolved to %c%s{...}
-
-(W ambiguous) You wrote something like C<${foo[2]}> (where foo represents
-the name of a Perl keyword), which might be looking for element number
-2 of the array named C<@foo>, in which case please write C<$foo[2]>, or you
-might have meant to pass an anonymous arrayref to the function named
-foo, and then do a scalar deref on the value it returns. If you meant
-that, write C<${foo([2])}>.
-
-In regular expressions, the C<${foo[2]}> syntax is sometimes necessary
-to disambiguate between array subscripts and character classes.
-C</$length[2345]/>, for instance, will be interpreted as C<$length> followed
-by the character class C<[2345]>. If an array subscript is what you
-want, you can avoid the warning by changing C</${length[2345]}/> to the
-unsightly C</${\$length[2345]}/>, by renaming your array to something
-that does not coincide with a built-in keyword, or by simply turning
-off warnings with C<no warnings 'ambiguous';>.
-
-=item Ambiguous use of -%s resolved as -&%s()
-
-(W ambiguous) You wrote something like C<-foo>, which might be the
-string C<"-foo">, or a call to the function C<foo>, negated. If you meant
-the string, just write C<"-foo">. If you meant the function call,
-write C<-foo()>.
-
-=item Ambiguous use of 's//le...' resolved as 's// le...'; Rewrite as 's//el' if you meant 'use locale rules and evaluate rhs as an expression'. In Perl 5.18, it will be resolved the other way
-
-(W deprecated, ambiguous) You wrote a pattern match with substitution
-immediately followed by "le". In Perl 5.16 and earlier, this is
-resolved as meaning to take the result of the substitution, and see if
-it is stringwise less-than-or-equal-to what follows in the expression.
-Having the "le" immediately following a pattern is deprecated behavior,
-so in Perl 5.18, this expression will be resolved as meaning to do the
-pattern match using the rules of the current locale, and evaluate the
-rhs as an expression when doing the substitution. In 5.14, and 5.16 if
-you want the latter interpretation, you can simply write "el" instead.
-But note that the C</l> modifier should not be used explicitly anyway;
-you should use C<use locale> instead. See L<perllocale>.
-
-=item '|' and '<' may not both be specified on command line
-
-(F) An error peculiar to VMS. Perl does its own command line
-redirection, and found that STDIN was a pipe, and that you also tried to
-redirect STDIN using '<'. Only one STDIN stream to a customer, please.
-
-=item '|' and '>' may not both be specified on command line
-
-(F) An error peculiar to VMS. Perl does its own command line
-redirection, and thinks you tried to redirect stdout both to a file and
-into a pipe to another command. You need to choose one or the other,
-though nothing's stopping you from piping into a program or Perl script
-which 'splits' output into two streams, such as
-
- open(OUT,">$ARGV[0]") or die "Can't write to $ARGV[0]: $!";
- while (<STDIN>) {
- print;
- print OUT;
- }
- close OUT;
-
-=item Applying %s to %s will act on scalar(%s)
-
-(W misc) The pattern match (C<//>), substitution (C<s///>), and
-transliteration (C<tr///>) operators work on scalar values. If you apply
-one of them to an array or a hash, it will convert the array or hash to
-a scalar value (the length of an array, or the population info of a
-hash) and then work on that scalar value. This is probably not what
-you meant to do. See L<perlfunc/grep> and L<perlfunc/map> for
-alternatives.
-
-=item Arg too short for msgsnd
-
-(F) msgsnd() requires a string at least as long as sizeof(long).
-
-=item %s argument is not a HASH or ARRAY element or a subroutine
-
-(F) The argument to exists() must be a hash or array element or a
-subroutine with an ampersand, such as:
-
- $foo{$bar}
- $ref->{"susie"}[12]
- &do_something
-
-=item %s argument is not a HASH or ARRAY element or slice
-
-(F) The argument to delete() must be either a hash or array element,
-such as:
-
- $foo{$bar}
- $ref->{"susie"}[12]
-
-or a hash or array slice, such as:
-
- @foo[$bar, $baz, $xyzzy]
- @{$ref->[12]}{"susie", "queue"}
-
-=item %s argument is not a subroutine name
-
-(F) The argument to exists() for C<exists &sub> must be a subroutine
-name, and not a subroutine call. C<exists &sub()> will generate this
-error.
-
-=item Argument "%s" isn't numeric%s
-
-(W numeric) The indicated string was fed as an argument to an operator
-that expected a numeric value instead. If you're fortunate the message
-will identify which operator was so unfortunate.
-
-=item Argument list not closed for PerlIO layer "%s"
-
-(W layer) When pushing a layer with arguments onto the Perl I/O
-system you forgot the ) that closes the argument list. (Layers
-take care of transforming data between external and internal
-representations.) Perl stopped parsing the layer list at this
-point and did not attempt to push this layer. If your program
-didn't explicitly request the failing operation, it may be the
-result of the value of the environment variable PERLIO.
-
-=item Array @%s missing the @ in argument %d of %s()
-
-(D deprecated) Really old Perl let you omit the @ on array names in some
-spots. This is now heavily deprecated.
-
-=item assertion botched: %s
-
-(X) The malloc package that comes with Perl had an internal failure.
-
-=item Assertion failed: file "%s"
-
-(X) A general assertion failed. The file in question must be examined.
-
-=item Assigning non-zero to $[ is no longer possible
-
-(F) When the "array_base" feature is disabled (e.g., under C<use v5.16;>)
-the special variable C<$[>, which is deprecated, is now a fixed zero value.
-
-=item Assignment to both a list and a scalar
-
-(F) If you assign to a conditional operator, the 2nd and 3rd arguments
-must either both be scalars or both be lists. Otherwise Perl won't
-know which context to supply to the right side.
-
-=item A thread exited while %d threads were running
-
-(W threads)(S) When using threaded Perl, a thread (not necessarily
-the main thread) exited while there were still other threads running.
-Usually it's a good idea first to collect the return values of the
-created threads by joining them, and only then to exit from the main
-thread. See L<threads>.
-
-=item Attempt to access disallowed key '%s' in a restricted hash
-
-(F) The failing code has attempted to get or set a key which is not in
-the current set of allowed keys of a restricted hash.
-
-=item Attempt to bless into a reference
-
-(F) The CLASSNAME argument to the bless() operator is expected to be
-the name of the package to bless the resulting object into. You've
-supplied instead a reference to something: perhaps you wrote
-
- bless $self, $proto;
-
-when you intended
-
- bless $self, ref($proto) || $proto;
-
-If you actually want to bless into the stringified version
-of the reference supplied, you need to stringify it yourself, for
-example by:
-
- bless $self, "$proto";
-
-=item Attempt to clear deleted array
-
-(S debugging) An array was assigned to when it was being freed.
-Freed values are not supposed to be visible to Perl code. This
-can also happen if XS code calls C<av_clear> from a custom magic
-callback on the array.
-
-=item Attempt to delete disallowed key '%s' from a restricted hash
-
-(F) The failing code attempted to delete from a restricted hash a key
-which is not in its key set.
-
-=item Attempt to delete readonly key '%s' from a restricted hash
-
-(F) The failing code attempted to delete a key whose value has been
-declared readonly from a restricted hash.
-
-=item Attempt to free non-arena SV: 0x%x
-
-(S internal) All SV objects are supposed to be allocated from arenas
-that will be garbage collected on exit. An SV was discovered to be
-outside any of those arenas.
-
-=item Attempt to free nonexistent shared string '%s'%s
-
-(S internal) Perl maintains a reference-counted internal table of
-strings to optimize the storage and access of hash keys and other
-strings. This indicates someone tried to decrement the reference count
-of a string that can no longer be found in the table.
-
-=item Attempt to free temp prematurely: SV 0x%x
-
-(S debugging) Mortalized values are supposed to be freed by the
-free_tmps() routine. This indicates that something else is freeing the
-SV before the free_tmps() routine gets a chance, which means that the
-free_tmps() routine will be freeing an unreferenced scalar when it does
-try to free it.
-
-=item Attempt to free unreferenced glob pointers
-
-(S internal) The reference counts got screwed up on symbol aliases.
-
-=item Attempt to free unreferenced scalar: SV 0x%x
-
-(W internal) Perl went to decrement the reference count of a scalar to
-see if it would go to 0, and discovered that it had already gone to 0
-earlier, and should have been freed, and in fact, probably was freed.
-This could indicate that SvREFCNT_dec() was called too many times, or
-that SvREFCNT_inc() was called too few times, or that the SV was
-mortalized when it shouldn't have been, or that memory has been
-corrupted.
-
-=item Attempt to join self
-
-(F) You tried to join a thread from within itself, which is an
-impossible task. You may be joining the wrong thread, or you may need
-to move the join() to some other thread.
-
-=item Attempt to pack pointer to temporary value
-
-(W pack) You tried to pass a temporary value (like the result of a
-function, or a computed expression) to the "p" pack() template. This
-means the result contains a pointer to a location that could become
-invalid anytime, even before the end of the current statement. Use
-literals or global values as arguments to the "p" pack() template to
-avoid this warning.
-
-=item Attempt to reload %s aborted.
-
-(F) You tried to load a file with C<use> or C<require> that failed to
-compile once already. Perl will not try to compile this file again
-unless you delete its entry from %INC. See L<perlfunc/require> and
-L<perlvar/%INC>.
-
-=item Attempt to set length of freed array
-
-(W) You tried to set the length of an array which has been freed. You
-can do this by storing a reference to the scalar representing the last index
-of an array and later assigning through that reference. For example
-
- $r = do {my @a; \$#a};
- $$r = 503
-
-=item Attempt to use reference as lvalue in substr
-
-(W substr) You supplied a reference as the first argument to substr()
-used as an lvalue, which is pretty strange. Perhaps you forgot to
-dereference it first. See L<perlfunc/substr>.
-
-=item Attribute "locked" is deprecated
-
-(D deprecated) You have used the attributes pragma to modify the
-"locked" attribute on a code reference. The :locked attribute is
-obsolete, has had no effect since 5005 threads were removed, and
-will be removed in a future release of Perl 5.
-
-=item Attribute "unique" is deprecated
-
-(D deprecated) You have used the attributes pragma to modify
-the "unique" attribute on an array, hash or scalar reference.
-The :unique attribute has had no effect since Perl 5.8.8, and
-will be removed in a future release of Perl 5.
-
-=item av_reify called on tied array
-
-(S debugging) This indicates that something went wrong and Perl got I<very>
-confused about C<@_> or C<@DB::args> being tied.
-
-=item Bad arg length for %s, is %u, should be %d
-
-(F) You passed a buffer of the wrong size to one of msgctl(), semctl()
-or shmctl(). In C parlance, the correct sizes are, respectively,
-S<sizeof(struct msqid_ds *)>, S<sizeof(struct semid_ds *)>, and
-S<sizeof(struct shmid_ds *)>.
-
-=item Bad evalled substitution pattern
-
-(F) You've used the C</e> switch to evaluate the replacement for a
-substitution, but perl found a syntax error in the code to evaluate,
-most likely an unexpected right brace '}'.
-
-=item Bad filehandle: %s
-
-(F) A symbol was passed to something wanting a filehandle, but the
-symbol has no filehandle associated with it. Perhaps you didn't do an
-open(), or did it in another package.
-
-=item Bad free() ignored
-
-(S malloc) An internal routine called free() on something that had never
-been malloc()ed in the first place. Mandatory, but can be disabled by
-setting environment variable C<PERL_BADFREE> to 0.
-
-This message can be seen quite often with DB_File on systems with "hard"
-dynamic linking, like C<AIX> and C<OS/2>. It is a bug of C<Berkeley DB>
-which is left unnoticed if C<DB> uses I<forgiving> system malloc().
-
-=item Bad hash
-
-(P) One of the internal hash routines was passed a null HV pointer.
-
-=item Badly placed ()'s
-
-(A) You've accidentally run your script through B<csh> instead
-of Perl. Check the #! line, or manually feed your script into
-Perl yourself.
-
-=item Bad name after %s
-
-(F) You started to name a symbol by using a package prefix, and then
-didn't finish the symbol. In particular, you can't interpolate outside
-of quotes, so
-
- $var = 'myvar';
- $sym = mypack::$var;
-
-is not the same as
-
- $var = 'myvar';
- $sym = "mypack::$var";
-
-=item Bad plugin affecting keyword '%s'
-
-(F) An extension using the keyword plugin mechanism violated the
-plugin API.
-
-=item Bad realloc() ignored
-
-(S malloc) An internal routine called realloc() on something that
-had never been malloc()ed in the first place. Mandatory, but can
-be disabled by setting the environment variable C<PERL_BADFREE> to 1.
-
-=item Bad symbol for array
-
-(P) An internal request asked to add an array entry to something that
-wasn't a symbol table entry.
-
-=item Bad symbol for dirhandle
-
-(P) An internal request asked to add a dirhandle entry to something
-that wasn't a symbol table entry.
-
-=item Bad symbol for filehandle
-
-(P) An internal request asked to add a filehandle entry to something
-that wasn't a symbol table entry.
-
-=item Bad symbol for hash
-
-(P) An internal request asked to add a hash entry to something that
-wasn't a symbol table entry.
-
-=item Bareword found in conditional
-
-(W bareword) The compiler found a bareword where it expected a
-conditional, which often indicates that an || or && was parsed as part
-of the last argument of the previous construct, for example:
-
- open FOO || die;
-
-It may also indicate a misspelled constant that has been interpreted as
-a bareword:
-
- use constant TYPO => 1;
- if (TYOP) { print "foo" }
-
-The C<strict> pragma is useful in avoiding such errors.
-
-=item Bareword "%s" not allowed while "strict subs" in use
-
-(F) With "strict subs" in use, a bareword is only allowed as a
-subroutine identifier, in curly brackets or to the left of the "=>"
-symbol. Perhaps you need to predeclare a subroutine?
-
-=item Bareword "%s" refers to nonexistent package
-
-(W bareword) You used a qualified bareword of the form C<Foo::>, but the
-compiler saw no other uses of that namespace before that point. Perhaps
-you need to predeclare a package?
-
-=item BEGIN failed--compilation aborted
-
-(F) An untrapped exception was raised while executing a BEGIN
-subroutine. Compilation stops immediately and the interpreter is
-exited.
-
-=item BEGIN not safe after errors--compilation aborted
-
-(F) Perl found a C<BEGIN {}> subroutine (or a C<use> directive, which
-implies a C<BEGIN {}>) after one or more compilation errors had already
-occurred. Since the intended environment for the C<BEGIN {}> could not
-be guaranteed (due to the errors), and since subsequent code likely
-depends on its correct operation, Perl just gave up.
-
-=item \1 better written as $1
-
-(W syntax) Outside of patterns, backreferences live on as variables.
-The use of backslashes is grandfathered on the right-hand side of a
-substitution, but stylistically it's better to use the variable form
-because other Perl programmers will expect it, and it works better if
-there are more than 9 backreferences.
-
-=item Binary number > 0b11111111111111111111111111111111 non-portable
-
-(W portable) The binary number you specified is larger than 2**32-1
-(4294967295) and therefore non-portable between systems. See
-L<perlport> for more on portability concerns.
-
-=item bind() on closed socket %s
-
-(W closed) You tried to do a bind on a closed socket. Did you forget to
-check the return value of your socket() call? See L<perlfunc/bind>.
-
-=item binmode() on closed filehandle %s
-
-(W unopened) You tried binmode() on a filehandle that was never opened.
-Check your control flow and number of arguments.
-
-=item "\b{" is deprecated; use "\b\{" instead
-
-=item "\B{" is deprecated; use "\B\{" instead
-
-(W deprecated, regexp) Use of an unescaped "{" immediately following a
-C<\b> or C<\B> is now deprecated so as to reserve its use for Perl
-itself in a future release.
-
-=item Bit vector size > 32 non-portable
-
-(W portable) Using bit vector sizes larger than 32 is non-portable.
-
-=item Bizarre copy of %s
-
-(P) Perl detected an attempt to copy an internal value that is not
-copiable.
-
-=item Buffer overflow in prime_env_iter: %s
-
-(W internal) A warning peculiar to VMS. While Perl was preparing to
-iterate over %ENV, it encountered a logical name or symbol definition
-which was too long, so it was truncated to the string shown.
-
-=item Bizarre SvTYPE [%d]
-
-(P) When starting a new thread or return values from a thread, Perl
-encountered an invalid data type.
-
-=item Callback called exit
-
-(F) A subroutine invoked from an external package via call_sv()
-exited by calling exit.
-
-=item %s() called too early to check prototype
-
-(W prototype) You've called a function that has a prototype before the
-parser saw a definition or declaration for it, and Perl could not check
-that the call conforms to the prototype. You need to either add an
-early prototype declaration for the subroutine in question, or move the
-subroutine definition ahead of the call to get proper prototype
-checking. Alternatively, if you are certain that you're calling the
-function correctly, you may put an ampersand before the name to avoid
-the warning. See L<perlsub>.
-
-=item Cannot compress integer in pack
-
-(F) An argument to pack("w",...) was too large to compress. The BER
-compressed integer format can only be used with positive integers, and you
-attempted to compress Infinity or a very large number (> 1e308).
-See L<perlfunc/pack>.
-
-=item Cannot compress negative numbers in pack
-
-(F) An argument to pack("w",...) was negative. The BER compressed integer
-format can only be used with positive integers. See L<perlfunc/pack>.
-
-=item Cannot convert a reference to %s to typeglob
-
-(F) You manipulated Perl's symbol table directly, stored a reference
-in it, then tried to access that symbol via conventional Perl syntax.
-The access triggers Perl to autovivify that typeglob, but it there is
-no legal conversion from that type of reference to a typeglob.
-
-=item Cannot copy to %s
-
-(P) Perl detected an attempt to copy a value to an internal type that cannot
-be directly assigned to.
-
-=item Cannot find encoding "%s"
-
-(S io) You tried to apply an encoding that did not exist to a filehandle,
-either with open() or binmode().
-
-=item Cannot set tied @DB::args
-
-(F) C<caller> tried to set C<@DB::args>, but found it tied. Tying C<@DB::args>
-is not supported. (Before this error was added, it used to crash.)
-
-=item Cannot tie unreifiable array
-
-(P) You somehow managed to call C<tie> on an array that does not
-keep a reference count on its arguments and cannot be made to
-do so. Such arrays are not even supposed to be accessible to
-Perl code, but are only used internally.
-
-=item Can only compress unsigned integers in pack
-
-(F) An argument to pack("w",...) was not an integer. The BER compressed
-integer format can only be used with positive integers, and you attempted
-to compress something else. See L<perlfunc/pack>.
-
-=item Can't bless non-reference value
-
-(F) Only hard references may be blessed. This is how Perl "enforces"
-encapsulation of objects. See L<perlobj>.
-
-=item Can't "break" in a loop topicalizer
-
-(F) You called C<break>, but you're in a C<foreach> block rather than
-a C<given> block. You probably meant to use C<next> or C<last>.
-
-=item Can't "break" outside a given block
-
-(F) You called C<break>, but you're not inside a C<given> block.
-
-=item Can't call method "%s" on an undefined value
-
-(F) You used the syntax of a method call, but the slot filled by the
-object reference or package name contains an undefined value. Something
-like this will reproduce the error:
-
- $BADREF = undef;
- process $BADREF 1,2,3;
- $BADREF->process(1,2,3);
-
-=item Can't call method "%s" on unblessed reference
-
-(F) A method call must know in what package it's supposed to run. It
-ordinarily finds this out from the object reference you supply, but you
-didn't supply an object reference in this case. A reference isn't an
-object reference until it has been blessed. See L<perlobj>.
-
-=item Can't call method "%s" without a package or object reference
-
-(F) You used the syntax of a method call, but the slot filled by the
-object reference or package name contains an expression that returns a
-defined value which is neither an object reference nor a package name.
-Something like this will reproduce the error:
-
- $BADREF = 42;
- process $BADREF 1,2,3;
- $BADREF->process(1,2,3);
-
-=item Can't chdir to %s
-
-(F) You called C<perl -x/foo/bar>, but C</foo/bar> is not a directory
-that you can chdir to, possibly because it doesn't exist.
-
-=item Can't check filesystem of script "%s" for nosuid
-
-(P) For some reason you can't check the filesystem of the script for
-nosuid.
-
-=item Can't coerce %s to %s in %s
-
-(F) Certain types of SVs, in particular real symbol table entries
-(typeglobs), can't be forced to stop being what they are. So you can't
-say things like:
-
- *foo += 1;
-
-You CAN say
-
- $foo = *foo;
- $foo += 1;
-
-but then $foo no longer contains a glob.
-
-=item Can't "continue" outside a when block
-
-(F) You called C<continue>, but you're not inside a C<when>
-or C<default> block.
-
-=item Can't create pipe mailbox
-
-(P) An error peculiar to VMS. The process is suffering from exhausted
-quotas or other plumbing problems.
-
-=item Can't declare %s in "%s"
-
-(F) Only scalar, array, and hash variables may be declared as "my", "our" or
-"state" variables. They must have ordinary identifiers as names.
-
-=item Can't "default" outside a topicalizer
-
-(F) You have used a C<default> block that is neither inside a
-C<foreach> loop nor a C<given> block. (Note that this error is
-issued on exit from the C<default> block, so you won't get the
-error if you use an explicit C<continue>.)
-
-=item Can't do inplace edit: %s is not a regular file
-
-(S inplace) You tried to use the B<-i> switch on a special file, such as
-a file in /dev, or a FIFO. The file was ignored.
-
-=item Can't do inplace edit on %s: %s
-
-(S inplace) The creation of the new file failed for the indicated
-reason.
-
-=item Can't do inplace edit without backup
-
-(F) You're on a system such as MS-DOS that gets confused if you try
-reading from a deleted (but still opened) file. You have to say
-C<-i.bak>, or some such.
-
-=item Can't do inplace edit: %s would not be unique
-
-(S inplace) Your filesystem does not support filenames longer than 14
-characters and Perl was unable to create a unique filename during
-inplace editing with the B<-i> switch. The file was ignored.
-
-=item Can't do {n,m} with n > m in regex; marked by <-- HERE in m/%s/
-
-(F) Minima must be less than or equal to maxima. If you really
-want your regexp to match something 0 times, just put {0}. The
-<-- HERE shows in the regular expression about where the problem
-was discovered. See L<perlre>.
-
-=item Can't do waitpid with flags
-
-(F) This machine doesn't have either waitpid() or wait4(), so only
-waitpid() without flags is emulated.
-
-=item Can't emulate -%s on #! line
-
-(F) The #! line specifies a switch that doesn't make sense at this
-point. For example, it'd be kind of silly to put a B<-x> on the #!
-line.
-
-=item Can't %s %s-endian %ss on this platform
-
-(F) Your platform's byte-order is neither big-endian nor little-endian,
-or it has a very strange pointer size. Packing and unpacking big- or
-little-endian floating point values and pointers may not be possible.
-See L<perlfunc/pack>.
-
-=item Can't exec "%s": %s
-
-(W exec) A system(), exec(), or piped open call could not execute the
-named program for the indicated reason. Typical reasons include: the
-permissions were wrong on the file, the file wasn't found in
-C<$ENV{PATH}>, the executable in question was compiled for another
-architecture, or the #! line in a script points to an interpreter that
-can't be run for similar reasons. (Or maybe your system doesn't support
-#! at all.)
-
-=item Can't exec %s
-
-(F) Perl was trying to execute the indicated program for you because
-that's what the #! line said. If that's not what you wanted, you may
-need to mention "perl" on the #! line somewhere.
-
-=item Can't execute %s
-
-(F) You used the B<-S> switch, but the copies of the script to execute
-found in the PATH did not have correct permissions.
-
-=item Can't find an opnumber for "%s"
-
-(F) A string of a form C<CORE::word> was given to prototype(), but there
-is no builtin with the name C<word>.
-
-=item Can't find %s character property "%s"
-
-(F) You used C<\p{}> or C<\P{}> but the character property by that name
-could not be found. Maybe you misspelled the name of the property?
-See L<perluniprops/Properties accessible through \p{} and \P{}>
-for a complete list of available properties.
-
-=item Can't find label %s
-
-(F) You said to goto a label that isn't mentioned anywhere that it's
-possible for us to go to. See L<perlfunc/goto>.
-
-=item Can't find %s on PATH
-
-(F) You used the B<-S> switch, but the script to execute could not be
-found in the PATH.
-
-=item Can't find %s on PATH, '.' not in PATH
-
-(F) You used the B<-S> switch, but the script to execute could not be
-found in the PATH, or at least not with the correct permissions. The
-script exists in the current directory, but PATH prohibits running it.
-
-=item Can't find string terminator %s anywhere before EOF
-
-(F) Perl strings can stretch over multiple lines. This message means
-that the closing delimiter was omitted. Because bracketed quotes count
-nesting levels, the following is missing its final parenthesis:
-
- print q(The character '(' starts a side comment.);
-
-If you're getting this error from a here-document, you may have
-included unseen whitespace before or after your closing tag or there
-may not be a linebreak after it. A good programmer's editor will have
-a way to help you find these characters (or lack of characters). See
-L<perlop> for the full details on here-documents.
-
-=item Can't find Unicode property definition "%s"
-
-(F) You may have tried to use C<\p> which means a Unicode
-property (for example C<\p{Lu}> matches all uppercase
-letters). If you did mean to use a Unicode property, see
-L<perluniprops/Properties accessible through \p{} and \P{}>
-for a complete list of available properties. If you didn't
-mean to use a Unicode property, escape the C<\p>, either by
-C<\\p> (just the C<\p>) or by C<\Q\p> (the rest of the string, or
-until C<\E>).
-
-=item Can't fork: %s
-
-(F) A fatal error occurred while trying to fork while opening a
-pipeline.
-
-=item Can't fork, trying again in 5 seconds
-
-(W pipe) A fork in a piped open failed with EAGAIN and will be retried
-after five seconds.
-
-=item Can't get filespec - stale stat buffer?
-
-(S) A warning peculiar to VMS. This arises because of the difference
-between access checks under VMS and under the Unix model Perl assumes.
-Under VMS, access checks are done by filename, rather than by bits in
-the stat buffer, so that ACLs and other protections can be taken into
-account. Unfortunately, Perl assumes that the stat buffer contains all
-the necessary information, and passes it, instead of the filespec, to
-the access-checking routine. It will try to retrieve the filespec using
-the device name and FID present in the stat buffer, but this works only
-if you haven't made a subsequent call to the CRTL stat() routine,
-because the device name is overwritten with each call. If this warning
-appears, the name lookup failed, and the access-checking routine gave up
-and returned FALSE, just to be conservative. (Note: The access-checking
-routine knows about the Perl C<stat> operator and file tests, so you
-shouldn't ever see this warning in response to a Perl command; it arises
-only if some internal code takes stat buffers lightly.)
-
-=item Can't get pipe mailbox device name
-
-(P) An error peculiar to VMS. After creating a mailbox to act as a
-pipe, Perl can't retrieve its name for later use.
-
-=item Can't get SYSGEN parameter value for MAXBUF
-
-(P) An error peculiar to VMS. Perl asked $GETSYI how big you want your
-mailbox buffers to be, and didn't get an answer.
-
-=item Can't "goto" into the middle of a foreach loop
-
-(F) A "goto" statement was executed to jump into the middle of a foreach
-loop. You can't get there from here. See L<perlfunc/goto>.
-
-=item Can't "goto" out of a pseudo block
-
-(F) A "goto" statement was executed to jump out of what might look like
-a block, except that it isn't a proper block. This usually occurs if
-you tried to jump out of a sort() block or subroutine, which is a no-no.
-See L<perlfunc/goto>.
-
-=item Can't goto subroutine from a sort sub (or similar callback)
-
-(F) The "goto subroutine" call can't be used to jump out of the
-comparison sub for a sort(), or from a similar callback (such
-as the reduce() function in List::Util).
-
-=item Can't goto subroutine from an eval-%s
-
-(F) The "goto subroutine" call can't be used to jump out of an eval
-"string" or block.
-
-=item Can't goto subroutine outside a subroutine
-
-(F) The deeply magical "goto subroutine" call can only replace one
-subroutine call for another. It can't manufacture one out of whole
-cloth. In general you should be calling it out of only an AUTOLOAD
-routine anyway. See L<perlfunc/goto>.
-
-=item Can't ignore signal CHLD, forcing to default
-
-(W signal) Perl has detected that it is being run with the SIGCHLD
-signal (sometimes known as SIGCLD) disabled. Since disabling this
-signal will interfere with proper determination of exit status of child
-processes, Perl has reset the signal to its default value. This
-situation typically indicates that the parent program under which Perl
-may be running (e.g. cron) is being very careless.
-
-=item Can't kill a non-numeric process ID
-
-(F) Process identifiers must be (signed) integers. It is a fatal error to
-attempt to kill() an undefined, empty-string or otherwise non-numeric
-process identifier.
-
-=item Can't "last" outside a loop block
-
-(F) A "last" statement was executed to break out of the current block,
-except that there's this itty bitty problem called there isn't a current
-block. Note that an "if" or "else" block doesn't count as a "loopish"
-block, as doesn't a block given to sort(), map() or grep(). You can
-usually double the curlies to get the same effect though, because the
-inner curlies will be considered a block that loops once. See
-L<perlfunc/last>.
-
-=item Can't linearize anonymous symbol table
-
-(F) Perl tried to calculate the method resolution order (MRO) of a
-package, but failed because the package stash has no name.
-
-=item Can't load '%s' for module %s
-
-(F) The module you tried to load failed to load a dynamic extension.
-This may either mean that you upgraded your version of perl to one
-that is incompatible with your old dynamic extensions (which is known
-to happen between major versions of perl), or (more likely) that your
-dynamic extension was built against an older version of the library
-that is installed on your system. You may need to rebuild your old
-dynamic extensions.
-
-=item Can't localize lexical variable %s
-
-(F) You used local on a variable name that was previously declared as a
-lexical variable using "my" or "state". This is not allowed. If you
-want to localize a package variable of the same name, qualify it with
-the package name.
-
-=item Can't localize through a reference
-
-(F) You said something like C<local $$ref>, which Perl can't currently
-handle, because when it goes to restore the old value of whatever $ref
-pointed to after the scope of the local() is finished, it can't be sure
-that $ref will still be a reference.
-
-=item Can't locate %s
-
-(F) You said to C<do> (or C<require>, or C<use>) a file that couldn't be found.
-Perl looks for the file in all the locations mentioned in @INC, unless
-the file name included the full path to the file. Perhaps you need
-to set the PERL5LIB or PERL5OPT environment variable to say where the
-extra library is, or maybe the script needs to add the library name
-to @INC. Or maybe you just misspelled the name of the file. See
-L<perlfunc/require> and L<lib>.
-
-=item Can't locate auto/%s.al in @INC
-
-(F) A function (or method) was called in a package which allows
-autoload, but there is no function to autoload. Most probable causes
-are a misprint in a function/method name or a failure to C<AutoSplit>
-the file, say, by doing C<make install>.
-
-=item Can't locate loadable object for module %s in @INC
-
-(F) The module you loaded is trying to load an external library, like
-for example, F<foo.so> or F<bar.dll>, but the L<DynaLoader> module was
-unable to locate this library. See L<DynaLoader>.
-
-=item Can't locate object method "%s" via package "%s"
-
-(F) You called a method correctly, and it correctly indicated a package
-functioning as a class, but that package doesn't define that particular
-method, nor does any of its base classes. See L<perlobj>.
-
-=item Can't locate package %s for @%s::ISA
-
-(W syntax) The @ISA array contained the name of another package that
-doesn't seem to exist.
-
-=item Can't locate PerlIO%s
-
-(F) You tried to use in open() a PerlIO layer that does not exist,
-e.g. open(FH, ">:nosuchlayer", "somefile").
-
-=item Can't make list assignment to %ENV on this system
-
-(F) List assignment to %ENV is not supported on some systems, notably
-VMS.
-
-=item Can't modify %s in %s
-
-(F) You aren't allowed to assign to the item indicated, or otherwise try
-to change it, such as with an auto-increment.
-
-=item Can't modify nonexistent substring
-
-(P) The internal routine that does assignment to a substr() was handed
-a NULL.
-
-=item Can't modify non-lvalue subroutine call
-
-(F) Subroutines meant to be used in lvalue context should be declared as
-such. See L<perlsub/"Lvalue subroutines">.
-
-=item Can't msgrcv to read-only var
-
-(F) The target of a msgrcv must be modifiable to be used as a receive
-buffer.
-
-=item Can't "next" outside a loop block
-
-(F) A "next" statement was executed to reiterate the current block, but
-there isn't a current block. Note that an "if" or "else" block doesn't
-count as a "loopish" block, as doesn't a block given to sort(), map() or
-grep(). You can usually double the curlies to get the same effect
-though, because the inner curlies will be considered a block that loops
-once. See L<perlfunc/next>.
-
-=item Can't open %s
-
-(F) You tried to run a perl built with MAD support with
-the PERL_XMLDUMP environment variable set, but the file
-named by that variable could not be opened.
-
-=item Can't open %s: %s
-
-(S inplace) The implicit opening of a file through use of the C<< <> >>
-filehandle, either implicitly under the C<-n> or C<-p> command-line
-switches, or explicitly, failed for the indicated reason. Usually
-this is because you don't have read permission for a file which
-you named on the command line.
-
-(F) You tried to call perl with the B<-e> switch, but F</dev/null> (or
-your operating system's equivalent) could not be opened.
-
-=item Can't open a reference
-
-(W io) You tried to open a scalar reference for reading or writing,
-using the 3-arg open() syntax:
-
- open FH, '>', $ref;
-
-but your version of perl is compiled without perlio, and this form of
-open is not supported.
-
-=item Can't open bidirectional pipe
-
-(W pipe) You tried to say C<open(CMD, "|cmd|")>, which is not supported.
-You can try any of several modules in the Perl library to do this, such
-as IPC::Open2. Alternately, direct the pipe's output to a file using
-">", and then read it in under a different file handle.
-
-=item Can't open error file %s as stderr
-
-(F) An error peculiar to VMS. Perl does its own command line
-redirection, and couldn't open the file specified after '2>' or '2>>' on
-the command line for writing.
-
-=item Can't open input file %s as stdin
-
-(F) An error peculiar to VMS. Perl does its own command line
-redirection, and couldn't open the file specified after '<' on the
-command line for reading.
-
-=item Can't open output file %s as stdout
-
-(F) An error peculiar to VMS. Perl does its own command line
-redirection, and couldn't open the file specified after '>' or '>>' on
-the command line for writing.
-
-=item Can't open output pipe (name: %s)
-
-(P) An error peculiar to VMS. Perl does its own command line
-redirection, and couldn't open the pipe into which to send data destined
-for stdout.
-
-=item Can't open perl script "%s": %s
-
-(F) The script you specified can't be opened for the indicated reason.
-
-If you're debugging a script that uses #!, and normally relies on the
-shell's $PATH search, the -S option causes perl to do that search, so
-you don't have to type the path or C<`which $scriptname`>.
-
-=item Can't read CRTL environ
-
-(S) A warning peculiar to VMS. Perl tried to read an element of %ENV
-from the CRTL's internal environment array and discovered the array was
-missing. You need to figure out where your CRTL misplaced its environ
-or define F<PERL_ENV_TABLES> (see L<perlvms>) so that environ is not
-searched.
-
-=item Can't "redo" outside a loop block
-
-(F) A "redo" statement was executed to restart the current block, but
-there isn't a current block. Note that an "if" or "else" block doesn't
-count as a "loopish" block, as doesn't a block given to sort(), map()
-or grep(). You can usually double the curlies to get the same effect
-though, because the inner curlies will be considered a block that
-loops once. See L<perlfunc/redo>.
-
-=item Can't remove %s: %s, skipping file
-
-(S inplace) You requested an inplace edit without creating a backup
-file. Perl was unable to remove the original file to replace it with
-the modified file. The file was left unmodified.
-
-=item Can't rename %s to %s: %s, skipping file
-
-(S inplace) The rename done by the B<-i> switch failed for some reason,
-probably because you don't have write permission to the directory.
-
-=item Can't reopen input pipe (name: %s) in binary mode
-
-(P) An error peculiar to VMS. Perl thought stdin was a pipe, and tried
-to reopen it to accept binary data. Alas, it failed.
-
-=item Can't reset %ENV on this system
-
-(F) You called C<reset('E')> or similar, which tried to reset
-all variables in the current package beginning with "E". In
-the main package, that includes %ENV. Resetting %ENV is not
-supported on some systems, notably VMS.
-
-=item Can't resolve method "%s" overloading "%s" in package "%s"
-
-(F)(P) Error resolving overloading specified by a method name (as
-opposed to a subroutine reference): no such method callable via the
-package. If the method name is C<???>, this is an internal error.
-
-=item Can't return %s from lvalue subroutine
-
-(F) Perl detected an attempt to return illegal lvalues (such as
-temporary or readonly values) from a subroutine used as an lvalue. This
-is not allowed.
-
-=item Can't return outside a subroutine
-
-(F) The return statement was executed in mainline code, that is, where
-there was no subroutine call to return out of. See L<perlsub>.
-
-=item Can't return %s to lvalue scalar context
-
-(F) You tried to return a complete array or hash from an lvalue
-subroutine, but you called the subroutine in a way that made Perl
-think you meant to return only one value. You probably meant to
-write parentheses around the call to the subroutine, which tell
-Perl that the call should be in list context.
-
-=item Can't stat script "%s"
-
-(P) For some reason you can't fstat() the script even though you have it
-open already. Bizarre.
-
-=item Can't take log of %g
-
-(F) For ordinary real numbers, you can't take the logarithm of a
-negative number or zero. There's a Math::Complex package that comes
-standard with Perl, though, if you really want to do that for the
-negative numbers.
-
-=item Can't take sqrt of %g
-
-(F) For ordinary real numbers, you can't take the square root of a
-negative number. There's a Math::Complex package that comes standard
-with Perl, though, if you really want to do that.
-
-=item Can't undef active subroutine
-
-(F) You can't undefine a routine that's currently running. You can,
-however, redefine it while it's running, and you can even undef the
-redefined subroutine while the old routine is running. Go figure.
-
-=item Can't upgrade %s (%d) to %d
-
-(P) The internal sv_upgrade routine adds "members" to an SV, making it
-into a more specialized kind of SV. The top several SV types are so
-specialized, however, that they cannot be interconverted. This message
-indicates that such a conversion was attempted.
-
-=item Can't use '%c' after -mname
-
-(F) You tried to call perl with the B<-m> switch, but you put something
-other than "=" after the module name.
-
-=item Can't use anonymous symbol table for method lookup
-
-(F) The internal routine that does method lookup was handed a symbol
-table that doesn't have a name. Symbol tables can become anonymous
-for example by undefining stashes: C<undef %Some::Package::>.
-
-=item Can't use an undefined value as %s reference
-
-(F) A value used as either a hard reference or a symbolic reference must
-be a defined value. This helps to delurk some insidious errors.
-
-=item Can't use bareword ("%s") as %s ref while "strict refs" in use
-
-(F) Only hard references are allowed by "strict refs". Symbolic
-references are disallowed. See L<perlref>.
-
-=item Can't use %! because Errno.pm is not available
-
-(F) The first time the C<%!> hash is used, perl automatically loads the
-Errno.pm module. The Errno module is expected to tie the %! hash to
-provide symbolic names for C<$!> errno values.
-
-=item Can't use both '<' and '>' after type '%c' in %s
-
-(F) A type cannot be forced to have both big-endian and little-endian
-byte-order at the same time, so this combination of modifiers is not
-allowed. See L<perlfunc/pack>.
-
-=item Can't use %s for loop variable
-
-(F) Only a simple scalar variable may be used as a loop variable on a
-foreach.
-
-=item Can't use global %s in "%s"
-
-(F) You tried to declare a magical variable as a lexical variable. This
-is not allowed, because the magic can be tied to only one location
-(namely the global variable) and it would be incredibly confusing to
-have variables in your program that looked like magical variables but
-weren't.
-
-=item Can't use '%c' in a group with different byte-order in %s
-
-(F) You attempted to force a different byte-order on a type
-that is already inside a group with a byte-order modifier.
-For example you cannot force little-endianness on a type that
-is inside a big-endian group.
-
-=item Can't use "my %s" in sort comparison
-
-(F) The global variables $a and $b are reserved for sort comparisons.
-You mentioned $a or $b in the same line as the <=> or cmp operator,
-and the variable had earlier been declared as a lexical variable.
-Either qualify the sort variable with the package name, or rename the
-lexical variable.
-
-=item Can't use %s ref as %s ref
-
-(F) You've mixed up your reference types. You have to dereference a
-reference of the type needed. You can use the ref() function to
-test the type of the reference, if need be.
-
-=item Can't use string ("%s") as %s ref while "strict refs" in use
-
-(F) Only hard references are allowed by "strict refs". Symbolic
-references are disallowed. See L<perlref>.
-
-=item Can't use subscript on %s
-
-(F) The compiler tried to interpret a bracketed expression as a
-subscript. But to the left of the brackets was an expression that
-didn't look like a hash or array reference, or anything else subscriptable.
-
-=item Can't use \%c to mean $%c in expression
-
-(W syntax) In an ordinary expression, backslash is a unary operator that
-creates a reference to its argument. The use of backslash to indicate a
-backreference to a matched substring is valid only as part of a regular
-expression pattern. Trying to do this in ordinary Perl code produces a
-value that prints out looking like SCALAR(0xdecaf). Use the $1 form
-instead.
-
-=item Can't weaken a nonreference
-
-(F) You attempted to weaken something that was not a reference. Only
-references can be weakened.
-
-=item Can't "when" outside a topicalizer
-
-(F) You have used a when() block that is neither inside a C<foreach>
-loop nor a C<given> block. (Note that this error is issued on exit
-from the C<when> block, so you won't get the error if the match fails,
-or if you use an explicit C<continue>.)
-
-=item Can't x= to read-only value
-
-(F) You tried to repeat a constant value (often the undefined value)
-with an assignment operator, which implies modifying the value itself.
-Perhaps you need to copy the value to a temporary, and repeat that.
-
-=item Character following "\c" must be ASCII
-
-(F)(W deprecated, syntax) In C<\cI<X>>, I<X> must be an ASCII character.
-It is planned to make this fatal in all instances in Perl 5.18. In the
-cases where it isn't fatal, the character this evaluates to is
-derived by exclusive or'ing the code point of this character with 0x40.
-
-Note that non-alphabetic ASCII characters are discouraged here as well.
-
-=item Character in 'C' format wrapped in pack
-
-(W pack) You said
-
- pack("C", $x)
-
-where $x is either less than 0 or more than 255; the C<"C"> format is
-only for encoding native operating system characters (ASCII, EBCDIC,
-and so on) and not for Unicode characters, so Perl behaved as if you meant
-
- pack("C", $x & 255)
-
-If you actually want to pack Unicode codepoints, use the C<"U"> format
-instead.
-
-=item Character in 'W' format wrapped in pack
-
-(W pack) You said
-
- pack("U0W", $x)
-
-where $x is either less than 0 or more than 255. However, C<U0>-mode
-expects all values to fall in the interval [0, 255], so Perl behaved
-as if you meant:
-
- pack("U0W", $x & 255)
-
-=item Character in 'c' format wrapped in pack
-
-(W pack) You said
-
- pack("c", $x)
-
-where $x is either less than -128 or more than 127; the C<"c"> format
-is only for encoding native operating system characters (ASCII, EBCDIC,
-and so on) and not for Unicode characters, so Perl behaved as if you meant
-
- pack("c", $x & 255);
-
-If you actually want to pack Unicode codepoints, use the C<"U"> format
-instead.
-
-=item Character in '%c' format wrapped in unpack
-
-(W unpack) You tried something like
-
- unpack("H", "\x{2a1}")
-
-where the format expects to process a byte (a character with a value
-below 256), but a higher value was provided instead. Perl uses the
-value modulus 256 instead, as if you had provided:
-
- unpack("H", "\x{a1}")
-
-=item Character(s) in '%c' format wrapped in pack
-
-(W pack) You tried something like
-
- pack("u", "\x{1f3}b")
-
-where the format expects to process a sequence of bytes (character with a
-value below 256), but some of the characters had a higher value. Perl
-uses the character values modulus 256 instead, as if you had provided:
-
- pack("u", "\x{f3}b")
-
-=item Character(s) in '%c' format wrapped in unpack
-
-(W unpack) You tried something like
-
- unpack("s", "\x{1f3}b")
-
-where the format expects to process a sequence of bytes (character with a
-value below 256), but some of the characters had a higher value. Perl
-uses the character values modulus 256 instead, as if you had provided:
-
- unpack("s", "\x{f3}b")
-
-=item "\c{" is deprecated and is more clearly written as ";"
-
-(D deprecated, syntax) The C<\cI<X>> construct is intended to be a way
-to specify non-printable characters. You used it with a "{" which
-evaluates to ";", which is printable. It is planned to remove the
-ability to specify a semi-colon this way in Perl 5.18. Just use a
-semi-colon or a backslash-semi-colon without the "\c".
-
-=item "\c%c" is more clearly written simply as "%s"
-
-(W syntax) The C<\cI<X>> construct is intended to be a way to specify
-non-printable characters. You used it for a printable one, which is better
-written as simply itself, perhaps preceded by a backslash for non-word
-characters.
-
-=item Cloning substitution context is unimplemented
-
-(F) Creating a new thread inside the C<s///> operator is not supported.
-
-=item close() on unopened filehandle %s
-
-(W unopened) You tried to close a filehandle that was never opened.
-
-=item closedir() attempted on invalid dirhandle %s
-
-(W io) The dirhandle you tried to close is either closed or not really
-a dirhandle. Check your control flow.
-
-=item Closure prototype called
-
-(F) If a closure has attributes, the subroutine passed to an attribute
-handler is the prototype that is cloned when a new closure is created.
-This subroutine cannot be called.
-
-=item Code missing after '/'
-
-(F) You had a (sub-)template that ends with a '/'. There must be
-another template code following the slash. See L<perlfunc/pack>.
-
-=item Code point 0x%X is not Unicode, may not be portable
-
-=item Code point 0x%X is not Unicode, all \p{} matches fail; all \P{} matches succeed
-
-(W utf8, non_unicode) You had a code point above the Unicode maximum
-of U+10FFFF.
-
-Perl allows strings to contain a superset of Unicode code points, up
-to the limit of what is storable in an unsigned integer on your system,
-but these may not be accepted by other languages/systems. At one time,
-it was legal in some standards to have code points up to 0x7FFF_FFFF,
-but not higher. Code points above 0xFFFF_FFFF require larger than a
-32 bit word.
-
-None of the Unicode or Perl-defined properties will match a non-Unicode
-code point. For example,
-
- chr(0x7FF_FFFF) =~ /\p{Any}/
-
-will not match, because the code point is not in Unicode. But
-
- chr(0x7FF_FFFF) =~ /\P{Any}/
-
-will match.
-
-This may be counterintuitive at times, as both these fail:
-
- chr(0x110000) =~ \p{ASCII_Hex_Digit=True} # Fails.
- chr(0x110000) =~ \p{ASCII_Hex_Digit=False} # Also fails!
-
-and both these succeed:
-
- chr(0x110000) =~ \P{ASCII_Hex_Digit=True} # Succeeds.
- chr(0x110000) =~ \P{ASCII_Hex_Digit=False} # Also succeeds!
-
-=item %s: Command not found
-
-(A) You've accidentally run your script through B<csh> or another shell
-shell instead of Perl. Check the #! line, or manually feed your script
-into Perl yourself. The #! line at the top of your file could look like
-
- #!/usr/bin/perl -w
-
-=item Compilation failed in require
-
-(F) Perl could not compile a file specified in a C<require> statement.
-Perl uses this generic message when none of the errors that it
-encountered were severe enough to halt compilation immediately.
-
-=item Complex regular subexpression recursion limit (%d) exceeded
-
-(W regexp) The regular expression engine uses recursion in complex
-situations where back-tracking is required. Recursion depth is limited
-to 32766, or perhaps less in architectures where the stack cannot grow
-arbitrarily. ("Simple" and "medium" situations are handled without
-recursion and are not subject to a limit.) Try shortening the string
-under examination; looping in Perl code (e.g. with C<while>) rather than
-in the regular expression engine; or rewriting the regular expression so
-that it is simpler or backtracks less. (See L<perlfaq2> for information
-on I<Mastering Regular Expressions>.)
-
-=item cond_broadcast() called on unlocked variable
-
-(W threads) Within a thread-enabled program, you tried to
-call cond_broadcast() on a variable which wasn't locked.
-The cond_broadcast() function is used to wake up another thread
-that is waiting in a cond_wait(). To ensure that the signal isn't
-sent before the other thread has a chance to enter the wait, it
-is usual for the signaling thread first to wait for a lock on
-variable. This lock attempt will only succeed after the other
-thread has entered cond_wait() and thus relinquished the lock.
-
-=item cond_signal() called on unlocked variable
-
-(W threads) Within a thread-enabled program, you tried to
-call cond_signal() on a variable which wasn't locked. The
-cond_signal() function is used to wake up another thread that
-is waiting in a cond_wait(). To ensure that the signal isn't
-sent before the other thread has a chance to enter the wait, it
-is usual for the signaling thread first to wait for a lock on
-variable. This lock attempt will only succeed after the other
-thread has entered cond_wait() and thus relinquished the lock.
-
-=item connect() on closed socket %s
-
-(W closed) You tried to do a connect on a closed socket. Did you forget
-to check the return value of your socket() call? See
-L<perlfunc/connect>.
-
-=item Constant(%s)%s: %s
-
-(F) The parser found inconsistencies either while attempting to define
-an overloaded constant, or when trying to find the character name
-specified in the C<\N{...}> escape. Perhaps you forgot to load the
-corresponding L<overload> pragma?.
-
-=item Constant(%s)%s: %s in regex; marked by <-- HERE in m/%s/
-
-(F) The parser found inconsistencies while attempting to find
-the character name specified in the C<\N{...}> escape.
-
-=item Constant is not %s reference
-
-(F) A constant value (perhaps declared using the C<use constant> pragma)
-is being dereferenced, but it amounts to the wrong type of reference.
-The message indicates the type of reference that was expected. This
-usually indicates a syntax error in dereferencing the constant value.
-See L<perlsub/"Constant Functions"> and L<constant>.
-
-=item Constant subroutine %s redefined
-
-(W redefine)(S) You redefined a subroutine which had previously
-been eligible for inlining. See L<perlsub/"Constant Functions">
-for commentary and workarounds.
-
-=item Constant subroutine %s undefined
-
-(W misc) You undefined a subroutine which had previously been eligible
-for inlining. See L<perlsub/"Constant Functions"> for commentary and
-workarounds.
-
-=item Copy method did not return a reference
-
-(F) The method which overloads "=" is buggy. See
-L<overload/Copy Constructor>.
-
-=item &CORE::%s cannot be called directly
-
-(F) You tried to call a subroutine in the C<CORE::> namespace
-with C<&foo> syntax or through a reference. Some subroutines
-in this package cannot yet be called that way, but must be
-called as barewords. Something like this will work:
-
- BEGIN { *shove = \&CORE::push; }
- shove @array, 1,2,3; # pushes on to @array
-
-=item CORE::%s is not a keyword
-
-(F) The CORE:: namespace is reserved for Perl keywords.
-
-=item corrupted regexp pointers
-
-(P) The regular expression engine got confused by what the regular
-expression compiler gave it.
-
-=item corrupted regexp program
-
-(P) The regular expression engine got passed a regexp program without a
-valid magic number.
-
-=item Corrupt malloc ptr 0x%x at 0x%x
-
-(P) The malloc package that comes with Perl had an internal failure.
-
-=item Count after length/code in unpack
-
-(F) You had an unpack template indicating a counted-length string, but
-you have also specified an explicit size for the string. See
-L<perlfunc/pack>.
-
-=item Deep recursion on anonymous subroutine
-
-=item Deep recursion on subroutine "%s"
-
-(W recursion) This subroutine has called itself (directly or indirectly)
-100 times more than it has returned. This probably indicates an
-infinite recursion, unless you're writing strange benchmark programs, in
-which case it indicates something else.
-
-This threshold can be changed from 100, by recompiling the F<perl> binary,
-setting the C pre-processor macro C<PERL_SUB_DEPTH_WARN> to the desired value.
-
-=item defined(@array) is deprecated
-
-(D deprecated) defined() is not usually useful on arrays because it
-checks for an undefined I<scalar> value. If you want to see if the
-array is empty, just use C<if (@array) { # not empty }> for example.
-
-=item defined(%hash) is deprecated
-
-(D deprecated) C<defined()> is not usually right on hashes and has been
-discouraged since 5.004.
-
-Although C<defined %hash> is false on a plain not-yet-used hash, it
-becomes true in several non-obvious circumstances, including iterators,
-weak references, stash names, even remaining true after C<undef %hash>.
-These things make C<defined %hash> fairly useless in practice.
-
-If a check for non-empty is what you wanted then just put it in boolean
-context (see L<perldata/Scalar values>):
-
- if (%hash) {
- # not empty
- }
-
-If you had C<defined %Foo::Bar::QUUX> to check whether such a package
-variable exists then that's never really been reliable, and isn't
-a good way to enquire about the features of a package, or whether
-it's loaded, etc.
-
-
-=item (?(DEFINE)....) does not allow branches in regex; marked by <-- HERE in m/%s/
-
-(F) You used something like C<(?(DEFINE)...|..)> which is illegal. The
-most likely cause of this error is that you left out a parenthesis inside
-of the C<....> part.
-
-The <-- HERE shows in the regular expression about where the problem was
-discovered.
-
-=item %s defines neither package nor VERSION--version check failed
-
-(F) You said something like "use Module 42" but in the Module file
-there are neither package declarations nor a C<$VERSION>.
-
-=item Delimiter for here document is too long
-
-(F) In a here document construct like C<<<FOO>, the label C<FOO> is too
-long for Perl to handle. You have to be seriously twisted to write code
-that triggers this error.
-
-=item Deprecated character in \N{...}; marked by <-- HERE in \N{%s<-- HERE %s
-
-(D deprecated) Just about anything is legal for the C<...> in C<\N{...}>.
-But starting in 5.12, non-reasonable ones that don't look like names
-are deprecated. A reasonable name begins with an alphabetic character
-and continues with any combination of alphanumerics, dashes, spaces,
-parentheses or colons.
-
-=item Deprecated use of my() in false conditional
-
-(D deprecated) You used a declaration similar to C<my $x if 0>. There
-has been a long-standing bug in Perl that causes a lexical variable
-not to be cleared at scope exit when its declaration includes a false
-conditional. Some people have exploited this bug to achieve a kind of
-static variable. Since we intend to fix this bug, we don't want people
-relying on this behavior. You can achieve a similar static effect by
-declaring the variable in a separate block outside the function, eg
-
- sub f { my $x if 0; return $x++ }
-
-becomes
-
- { my $x; sub f { return $x++ } }
-
-Beginning with perl 5.9.4, you can also use C<state> variables to have
-lexicals that are initialized only once (see L<feature>):
-
- sub f { state $x; return $x++ }
-
-=item DESTROY created new reference to dead object '%s'
-
-(F) A DESTROY() method created a new reference to the object which is
-just being DESTROYed. Perl is confused, and prefers to abort rather
-than to create a dangling reference.
-
-=item Did not produce a valid header
-
-See Server error.
-
-=item %s did not return a true value
-
-(F) A required (or used) file must return a true value to indicate that
-it compiled correctly and ran its initialization code correctly. It's
-traditional to end such a file with a "1;", though any true value would
-do. See L<perlfunc/require>.
-
-=item (Did you mean &%s instead?)
-
-(W misc) You probably referred to an imported subroutine &FOO as $FOO or
-some such.
-
-=item (Did you mean "local" instead of "our"?)
-
-(W misc) Remember that "our" does not localize the declared global
-variable. You have declared it again in the same lexical scope, which
-seems superfluous.
-
-=item (Did you mean $ or @ instead of %?)
-
-(W) You probably said %hash{$key} when you meant $hash{$key} or
-@hash{@keys}. On the other hand, maybe you just meant %hash and got
-carried away.
-
-=item Died
-
-(F) You passed die() an empty string (the equivalent of C<die "">) or
-you called it with no args and C<$@> was empty.
-
-=item Document contains no data
-
-See Server error.
-
-=item %s does not define %s::VERSION--version check failed
-
-(F) You said something like "use Module 42" but the Module did not
-define a C<$VERSION.>
-
-=item '/' does not take a repeat count
-
-(F) You cannot put a repeat count of any kind right after the '/' code.
-See L<perlfunc/pack>.
-
-=item Don't know how to handle magic of type '%s'
-
-(P) The internal handling of magical variables has been cursed.
-
-=item do_study: out of memory
-
-(P) This should have been caught by safemalloc() instead.
-
-=item (Do you need to predeclare %s?)
-
-(S syntax) This is an educated guess made in conjunction with the message
-"%s found where operator expected". It often means a subroutine or module
-name is being referenced that hasn't been declared yet. This may be
-because of ordering problems in your file, or because of a missing
-"sub", "package", "require", or "use" statement. If you're referencing
-something that isn't defined yet, you don't actually have to define the
-subroutine or package before the current location. You can use an empty
-"sub foo;" or "package FOO;" to enter a "forward" declaration.
-
-=item dump() better written as CORE::dump()
-
-(W misc) You used the obsolescent C<dump()> built-in function, without fully
-qualifying it as C<CORE::dump()>. Maybe it's a typo. See L<perlfunc/dump>.
-
-=item dump is not supported
-
-(F) Your machine doesn't support dump/undump.
-
-=item Duplicate free() ignored
-
-(S malloc) An internal routine called free() on something that had
-already been freed.
-
-=item Duplicate modifier '%c' after '%c' in %s
-
-(W) You have applied the same modifier more than once after a type
-in a pack template. See L<perlfunc/pack>.
-
-=item elseif should be elsif
-
-(S syntax) There is no keyword "elseif" in Perl because Larry thinks
-it's ugly. Your code will be interpreted as an attempt to call a method
-named "elseif" for the class returned by the following block. This is
-unlikely to be what you want.
-
-=item Empty %s
-
-(F) C<\p> and C<\P> are used to introduce a named Unicode property, as
-described in L<perlunicode> and L<perlre>. You used C<\p> or C<\P> in
-a regular expression without specifying the property name.
-
-=item entering effective %s failed
-
-(F) While under the C<use filetest> pragma, switching the real and
-effective uids or gids failed.
-
-=item %ENV is aliased to %s
-
-(F) You're running under taint mode, and the C<%ENV> variable has been
-aliased to another hash, so it doesn't reflect anymore the state of the
-program's environment. This is potentially insecure.
-
-=item Error converting file specification %s
-
-(F) An error peculiar to VMS. Because Perl may have to deal with file
-specifications in either VMS or Unix syntax, it converts them to a
-single form when it must operate on them directly. Either you've passed
-an invalid file specification to Perl, or you've found a case the
-conversion routines don't handle. Drat.
-
-=item %s: Eval-group in insecure regular expression
-
-(F) Perl detected tainted data when trying to compile a regular
-expression that contains the C<(?{ ... })> zero-width assertion, which
-is unsafe. See L<perlre/(?{ code })>, and L<perlsec>.
-
-=item %s: Eval-group not allowed at runtime, use re 'eval'
-
-(F) Perl tried to compile a regular expression containing the
-C<(?{ ... })> zero-width assertion at run time, as it would when the
-pattern contains interpolated values. Since that is a security risk,
-it is not allowed. If you insist, you may still do this by using the
-C<re 'eval'> pragma or by explicitly building the pattern from an
-interpolated string at run time and using that in an eval(). See
-L<perlre/(?{ code })>.
-
-=item %s: Eval-group not allowed, use re 'eval'
-
-(F) A regular expression contained the C<(?{ ... })> zero-width
-assertion, but that construct is only allowed when the C<use re 'eval'>
-pragma is in effect. See L<perlre/(?{ code })>.
-
-=item EVAL without pos change exceeded limit in regex; marked by <-- HERE in m/%s/
-
-(F) You used a pattern that nested too many EVAL calls without consuming
-any text. Restructure the pattern so that text is consumed.
-
-The <-- HERE shows in the regular expression about where the problem was
-discovered.
-
-=item Excessively long <> operator
-
-(F) The contents of a <> operator may not exceed the maximum size of a
-Perl identifier. If you're just trying to glob a long list of
-filenames, try using the glob() operator, or put the filenames into a
-variable and glob that.
-
-=item exec? I'm not *that* kind of operating system
-
-(F) The C<exec> function is not implemented on some systems, e.g., Symbian
-OS. See L<perlport>.
-
-=item Execution of %s aborted due to compilation errors.
-
-(F) The final summary message when a Perl compilation fails.
-
-=item Exiting eval via %s
-
-(W exiting) You are exiting an eval by unconventional means, such as a
-goto, or a loop control statement.
-
-=item Exiting format via %s
-
-(W exiting) You are exiting a format by unconventional means, such as a
-goto, or a loop control statement.
-
-=item Exiting pseudo-block via %s
-
-(W exiting) You are exiting a rather special block construct (like a
-sort block or subroutine) by unconventional means, such as a goto, or a
-loop control statement. See L<perlfunc/sort>.
-
-=item Exiting subroutine via %s
-
-(W exiting) You are exiting a subroutine by unconventional means, such
-as a goto, or a loop control statement.
-
-=item Exiting substitution via %s
-
-(W exiting) You are exiting a substitution by unconventional means, such
-as a return, a goto, or a loop control statement.
-
-=item Explicit blessing to '' (assuming package main)
-
-(W misc) You are blessing a reference to a zero length string. This has
-the effect of blessing the reference into the package main. This is
-usually not what you want. Consider providing a default target package,
-e.g. bless($ref, $p || 'MyPackage');
-
-=item %s: Expression syntax
-
-(A) You've accidentally run your script through B<csh> instead of Perl.
-Check the #! line, or manually feed your script into Perl yourself.
-
-=item %s failed--call queue aborted
-
-(F) An untrapped exception was raised while executing a UNITCHECK,
-CHECK, INIT, or END subroutine. Processing of the remainder of the
-queue of such routines has been prematurely ended.
-
-=item False [] range "%s" in regex; marked by <-- HERE in m/%s/
-
-(W regexp) A character class range must start and end at a literal
-character, not another character class like C<\d> or C<[:alpha:]>. The "-"
-in your false range is interpreted as a literal "-". Consider quoting the
-"-", "\-". The <-- HERE shows in the regular expression about where the
-problem was discovered. See L<perlre>.
-
-=item Fatal VMS error (status=%d) at %s, line %d
-
-(P) An error peculiar to VMS. Something untoward happened in a VMS
-system service or RTL routine; Perl's exit status should provide more
-details. The filename in "at %s" and the line number in "line %d" tell
-you which section of the Perl source code is distressed.
-
-=item fcntl is not implemented
-
-(F) Your machine apparently doesn't implement fcntl(). What is this, a
-PDP-11 or something?
-
-=item FETCHSIZE returned a negative value
-
-(F) A tied array claimed to have a negative number of elements, which
-is not possible.
-
-=item Field too wide in 'u' format in pack
-
-(W pack) Each line in an uuencoded string start with a length indicator
-which can't encode values above 63. So there is no point in asking for
-a line length bigger than that. Perl will behave as if you specified
-C<u63> as the format.
-
-=item Filehandle %s opened only for input
-
-(W io) You tried to write on a read-only filehandle. If you intended
-it to be a read-write filehandle, you needed to open it with "+<" or
-"+>" or "+>>" instead of with "<" or nothing. If you intended only to
-write the file, use ">" or ">>". See L<perlfunc/open>.
-
-=item Filehandle %s opened only for output
-
-(W io) You tried to read from a filehandle opened only for writing, If
-you intended it to be a read/write filehandle, you needed to open it
-with "+<" or "+>" or "+>>" instead of with ">". If you intended only to
-read from the file, use "<". See L<perlfunc/open>. Another possibility
-is that you attempted to open filedescriptor 0 (also known as STDIN) for
-output (maybe you closed STDIN earlier?).
-
-=item Filehandle %s reopened as %s only for input
-
-(W io) You opened for reading a filehandle that got the same filehandle id
-as STDOUT or STDERR. This occurred because you closed STDOUT or STDERR
-previously.
-
-=item Filehandle STDIN reopened as %s only for output
-
-(W io) You opened for writing a filehandle that got the same filehandle id
-as STDIN. This occurred because you closed STDIN previously.
-
-=item Final $ should be \$ or $name
-
-(F) You must now decide whether the final $ in a string was meant to be
-a literal dollar sign, or was meant to introduce a variable name that
-happens to be missing. So you have to put either the backslash or the
-name.
-
-=item flock() on closed filehandle %s
-
-(W closed) The filehandle you're attempting to flock() got itself closed
-some time before now. Check your control flow. flock() operates on
-filehandles. Are you attempting to call flock() on a dirhandle by the
-same name?
-
-=item Format not terminated
-
-(F) A format must be terminated by a line with a solitary dot. Perl got
-to the end of your file without finding such a line.
-
-=item Format %s redefined
-
-(W redefine) You redefined a format. To suppress this warning, say
-
- {
- no warnings 'redefine';
- eval "format NAME =...";
- }
-
-=item Found = in conditional, should be ==
-
-(W syntax) You said
-
- if ($foo = 123)
-
-when you meant
-
- if ($foo == 123)
-
-(or something like that).
-
-=item %s found where operator expected
-
-(S syntax) The Perl lexer knows whether to expect a term or an operator.
-If it sees what it knows to be a term when it was expecting to see an
-operator, it gives you this warning. Usually it indicates that an
-operator or delimiter was omitted, such as a semicolon.
-
-=item gdbm store returned %d, errno %d, key "%s"
-
-(S) A warning from the GDBM_File extension that a store failed.
-
-=item gethostent not implemented
-
-(F) Your C library apparently doesn't implement gethostent(), probably
-because if it did, it'd feel morally obligated to return every hostname
-on the Internet.
-
-=item get%sname() on closed socket %s
-
-(W closed) You tried to get a socket or peer socket name on a closed
-socket. Did you forget to check the return value of your socket() call?
-
-=item getpwnam returned invalid UIC %#o for user "%s"
-
-(S) A warning peculiar to VMS. The call to C<sys$getuai> underlying the
-C<getpwnam> operator returned an invalid UIC.
-
-=item getsockopt() on closed socket %s
-
-(W closed) You tried to get a socket option on a closed socket. Did you
-forget to check the return value of your socket() call? See
-L<perlfunc/getsockopt>.
-
-=item Global symbol "%s" requires explicit package name
-
-(F) You've said "use strict" or "use strict vars", which indicates
-that all variables must either be lexically scoped (using "my" or "state"),
-declared beforehand using "our", or explicitly qualified to say
-which package the global variable is in (using "::").
-
-=item glob failed (%s)
-
-(S glob) Something went wrong with the external program(s) used
-for C<glob> and C<< <*.c> >>. Usually, this means that you supplied a C<glob>
-pattern that caused the external program to fail and exit with a
-nonzero status. If the message indicates that the abnormal exit
-resulted in a coredump, this may also mean that your csh (C shell)
-is broken. If so, you should change all of the csh-related variables
-in config.sh: If you have tcsh, make the variables refer to it as
-if it were csh (e.g. C<full_csh='/usr/bin/tcsh'>); otherwise, make them
-all empty (except that C<d_csh> should be C<'undef'>) so that Perl will
-think csh is missing. In either case, after editing config.sh, run
-C<./Configure -S> and rebuild Perl.
-
-=item Glob not terminated
-
-(F) The lexer saw a left angle bracket in a place where it was expecting
-a term, so it's looking for the corresponding right angle bracket, and
-not finding it. Chances are you left some needed parentheses out
-earlier in the line, and you really meant a "less than".
-
-=item gmtime(%f) too large
-
-(W overflow) You called C<gmtime> with a number that was larger than
-it can reliably handle and C<gmtime> probably returned the wrong
-date. This warning is also triggered with NaN (the special
-not-a-number value).
-
-=item gmtime(%f) too small
-
-(W overflow) You called C<gmtime> with a number that was smaller than
-it can reliably handle and C<gmtime> probably returned the wrong date.
-
-=item Got an error from DosAllocMem
-
-(P) An error peculiar to OS/2. Most probably you're using an obsolete
-version of Perl, and this should not happen anyway.
-
-=item goto must have label
-
-(F) Unlike with "next" or "last", you're not allowed to goto an
-unspecified destination. See L<perlfunc/goto>.
-
-=item Goto undefined subroutine%s
-
-(F) You tried to call a subroutine with C<goto &sub> syntax, but
-the indicated subroutine hasn't been defined, or if it was, it
-has since been undefined.
-
-=item ()-group starts with a count
-
-(F) A ()-group started with a count. A count is supposed to follow
-something: a template character or a ()-group. See L<perlfunc/pack>.
-
-=item %s had compilation errors.
-
-(F) The final summary message when a C<perl -c> fails.
-
-=item Had to create %s unexpectedly
-
-(S internal) A routine asked for a symbol from a symbol table that ought
-to have existed already, but for some reason it didn't, and had to be
-created on an emergency basis to prevent a core dump.
-
-=item Hash %%s missing the % in argument %d of %s()
-
-(D deprecated) Really old Perl let you omit the % on hash names in some
-spots. This is now heavily deprecated.
-
-=item %s has too many errors
-
-(F) The parser has given up trying to parse the program after 10 errors.
-Further error messages would likely be uninformative.
-
-=item Having no space between pattern and following word is deprecated
-
-(D syntax)
-
-You had a word that isn't a regex modifier immediately following
-a pattern without an intervening space. If you are trying to use
-the C</le> flags on a substitution, use C</el> instead. Otherwise, add
-white space between the pattern and following word to eliminate
-the warning. As an example of the latter, the two constructs:
-
-
- $a =~ m/$foo/sand $bar
- $a =~ m/$foo/s and $bar
-
-both currently mean the same thing, but it is planned to disallow
-the first form in Perl 5.18. And,
-
- $a =~ m/$foo/and $bar
-
-will be disallowed too.
-
-=item Hexadecimal number > 0xffffffff non-portable
-
-(W portable) The hexadecimal number you specified is larger than 2**32-1
-(4294967295) and therefore non-portable between systems. See
-L<perlport> for more on portability concerns.
-
-=item Identifier too long
-
-(F) Perl limits identifiers (names for variables, functions, etc.) to
-about 250 characters for simple names, and somewhat more for compound
-names (like C<$A::B>). You've exceeded Perl's limits. Future versions
-of Perl are likely to eliminate these arbitrary limitations.
-
-=item Ignoring zero length \N{} in character class
-
-(W) Named Unicode character escapes C<(\N{...})> may return a zero-length
-sequence. When such an escape is used in a character class its
-behaviour is not well defined. Check that the correct escape has
-been used, and the correct charname handler is in scope.
-
-=item Illegal binary digit %s
-
-(F) You used a digit other than 0 or 1 in a binary number.
-
-=item Illegal binary digit %s ignored
-
-(W digit) You may have tried to use a digit other than 0 or 1 in a
-binary number. Interpretation of the binary number stopped before the
-offending digit.
-
-=item Illegal character after '_' in prototype for %s : %s
-
-(W illegalproto) An illegal character was found in a prototype declaration.
-Legal characters in prototypes are $, @, %, *, ;, [, ], &, \, and +.
-
-=item Illegal character \%o (carriage return)
-
-(F) Perl normally treats carriage returns in the program text as it
-would any other whitespace, which means you should never see this error
-when Perl was built using standard options. For some reason, your
-version of Perl appears to have been built without this support. Talk
-to your Perl administrator.
-
-=item Illegal character in prototype for %s : %s
-
-(W illegalproto) An illegal character was found in a prototype declaration.
-Legal characters in prototypes are $, @, %, *, ;, [, ], &, \, and +.
-
-=item Illegal declaration of anonymous subroutine
-
-(F) When using the C<sub> keyword to construct an anonymous subroutine,
-you must always specify a block of code. See L<perlsub>.
-
-=item Illegal declaration of subroutine %s
-
-(F) A subroutine was not declared correctly. See L<perlsub>.
-
-=item Illegal division by zero
-
-(F) You tried to divide a number by 0. Either something was wrong in
-your logic, or you need to put a conditional in to guard against
-meaningless input.
-
-=item Illegal hexadecimal digit %s ignored
-
-(W digit) You may have tried to use a character other than 0 - 9 or
-A - F, a - f in a hexadecimal number. Interpretation of the hexadecimal
-number stopped before the illegal character.
-
-=item Illegal modulus zero
-
-(F) You tried to divide a number by 0 to get the remainder. Most
-numbers don't take to this kindly.
-
-=item Illegal number of bits in vec
-
-(F) The number of bits in vec() (the third argument) must be a power of
-two from 1 to 32 (or 64, if your platform supports that).
-
-=item Illegal octal digit %s
-
-(F) You used an 8 or 9 in an octal number.
-
-=item Illegal octal digit %s ignored
-
-(W digit) You may have tried to use an 8 or 9 in an octal number.
-Interpretation of the octal number stopped before the 8 or 9.
-
-=item Illegal switch in PERL5OPT: -%c
-
-(X) The PERL5OPT environment variable may only be used to set the
-following switches: B<-[CDIMUdmtw]>.
-
-=item Ill-formed CRTL environ value "%s"
-
-(W internal) A warning peculiar to VMS. Perl tried to read the CRTL's
-internal environ array, and encountered an element without the C<=>
-delimiter used to separate keys from values. The element is ignored.
-
-=item Ill-formed message in prime_env_iter: |%s|
-
-(W internal) A warning peculiar to VMS. Perl tried to read a logical
-name or CLI symbol definition when preparing to iterate over %ENV, and
-didn't see the expected delimiter between key and value, so the line was
-ignored.
-
-=item (in cleanup) %s
-
-(W misc) This prefix usually indicates that a DESTROY() method raised
-the indicated exception. Since destructors are usually called by the
-system at arbitrary points during execution, and often a vast number of
-times, the warning is issued only once for any number of failures that
-would otherwise result in the same message being repeated.
-
-Failure of user callbacks dispatched using the C<G_KEEPERR> flag could
-also result in this warning. See L<perlcall/G_KEEPERR>.
-
-=item Inconsistent hierarchy during C3 merge of class '%s': merging failed on parent '%s'
-
-(F) The method resolution order (MRO) of the given class is not
-C3-consistent, and you have enabled the C3 MRO for this class. See the C3
-documentation in L<mro> for more information.
-
-=item In EBCDIC the v-string components cannot exceed 2147483647
-
-(F) An error peculiar to EBCDIC. Internally, v-strings are stored as
-Unicode code points, and encoded in EBCDIC as UTF-EBCDIC. The UTF-EBCDIC
-encoding is limited to code points no larger than 2147483647 (0x7FFFFFFF).
-
-=item Infinite recursion in regex; marked by <-- HERE in m/%s/
-
-(F) You used a pattern that references itself without consuming any input
-text. You should check the pattern to ensure that recursive patterns
-either consume text or fail.
-
-The <-- HERE shows in the regular expression about where the problem was
-discovered.
-
-=item Initialization of state variables in list context currently forbidden
-
-(F) Currently the implementation of "state" only permits the
-initialization of scalar variables in scalar context. Re-write
-C<state ($a) = 42> as C<state $a = 42> to change from list to scalar
-context. Constructions such as C<state (@a) = foo()> will be
-supported in a future perl release.
-
-=item Insecure dependency in %s
-
-(F) You tried to do something that the tainting mechanism didn't like.
-The tainting mechanism is turned on when you're running setuid or
-setgid, or when you specify B<-T> to turn it on explicitly. The
-tainting mechanism labels all data that's derived directly or indirectly
-from the user, who is considered to be unworthy of your trust. If any
-such data is used in a "dangerous" operation, you get this error. See
-L<perlsec> for more information.
-
-=item Insecure directory in %s
-
-(F) You can't use system(), exec(), or a piped open in a setuid or
-setgid script if C<$ENV{PATH}> contains a directory that is writable by
-the world. Also, the PATH must not contain any relative directory.
-See L<perlsec>.
-
-=item Insecure $ENV{%s} while running %s
-
-(F) You can't use system(), exec(), or a piped open in a setuid or
-setgid script if any of C<$ENV{PATH}>, C<$ENV{IFS}>, C<$ENV{CDPATH}>,
-C<$ENV{ENV}>, C<$ENV{BASH_ENV}> or C<$ENV{TERM}> are derived from data
-supplied (or potentially supplied) by the user. The script must set
-the path to a known value, using trustworthy data. See L<perlsec>.
-
-=item Insecure user-defined property %s
-
-(F) Perl detected tainted data when trying to compile a regular
-expression that contains a call to a user-defined character property
-function, i.e. C<\p{IsFoo}> or C<\p{InFoo}>.
-See L<perlunicode/User-Defined Character Properties> and L<perlsec>.
-
-=item Integer overflow in format string for %s
-
-(F) The indexes and widths specified in the format string of C<printf()>
-or C<sprintf()> are too large. The numbers must not overflow the size of
-integers for your architecture.
-
-=item Integer overflow in %s number
-
-(W overflow) The hexadecimal, octal or binary number you have specified
-either as a literal or as an argument to hex() or oct() is too big for
-your architecture, and has been converted to a floating point number.
-On a 32-bit architecture the largest hexadecimal, octal or binary number
-representable without overflow is 0xFFFFFFFF, 037777777777, or
-0b11111111111111111111111111111111 respectively. Note that Perl
-transparently promotes all numbers to a floating point representation
-internally--subject to loss of precision errors in subsequent
-operations.
-
-=item Integer overflow in version
-
-(F) Some portion of a version initialization is too large for the
-size of integers for your architecture. This is not a warning
-because there is no rational reason for a version to try and use a
-element larger than typically 2**32. This is usually caused by
-trying to use some odd mathematical operation as a version, like
-100/9.
-
-=item Internal disaster in regex; marked by <-- HERE in m/%s/
-
-(P) Something went badly wrong in the regular expression parser.
-The <-- HERE shows in the regular expression about where the problem was
-discovered.
-
-=item Internal inconsistency in tracking vforks
-
-(S) A warning peculiar to VMS. Perl keeps track of the number of times
-you've called C<fork> and C<exec>, to determine whether the current call
-to C<exec> should affect the current script or a subprocess (see
-L<perlvms/"exec LIST">). Somehow, this count has become scrambled, so
-Perl is making a guess and treating this C<exec> as a request to
-terminate the Perl script and execute the specified command.
-
-=item Internal urp in regex; marked by <-- HERE in m/%s/
-
-(P) Something went badly awry in the regular expression parser. The
-<-- HERE shows in the regular expression about where the problem was
-discovered.
-
-=item %s (...) interpreted as function
-
-(W syntax) You've run afoul of the rule that says that any list operator
-followed by parentheses turns into a function, with all the list
-operators arguments found inside the parentheses. See
-L<perlop/Terms and List Operators (Leftward)>.
-
-=item Invalid %s attribute: %s
-
-(F) The indicated attribute for a subroutine or variable was not recognized
-by Perl or by a user-supplied handler. See L<attributes>.
-
-=item Invalid %s attributes: %s
-
-(F) The indicated attributes for a subroutine or variable were not
-recognized by Perl or by a user-supplied handler. See L<attributes>.
-
-=item Invalid conversion in %s: "%s"
-
-(W printf) Perl does not understand the given format conversion. See
-L<perlfunc/sprintf>.
-
-=item Invalid escape in the specified encoding in regex; marked by <-- HERE in m/%s/
-
-(W regexp) The numeric escape (for example C<\xHH>) of value < 256
-didn't correspond to a single character through the conversion
-from the encoding specified by the encoding pragma.
-The escape was replaced with REPLACEMENT CHARACTER (U+FFFD) instead.
-The <-- HERE shows in the regular expression about where the
-escape was discovered.
-
-=item Invalid hexadecimal number in \N{U+...}
-
-(F) The character constant represented by C<...> is not a valid hexadecimal
-number. Either it is empty, or you tried to use a character other than
-0 - 9 or A - F, a - f in a hexadecimal number.
-
-=item Invalid module name %s with -%c option: contains single ':'
-
-(F) The module argument to perl's B<-m> and B<-M> command-line options
-cannot contain single colons in the module name, but only in the
-arguments after "=". In other words, B<-MFoo::Bar=:baz> is ok, but
-B<-MFoo:Bar=baz> is not.
-
-=item Invalid mro name: '%s'
-
-(F) You tried to C<mro::set_mro("classname", "foo")> or C<use mro 'foo'>,
-where C<foo> is not a valid method resolution order (MRO). Currently,
-the only valid ones supported are C<dfs> and C<c3>, unless you have loaded
-a module that is a MRO plugin. See L<mro> and L<perlmroapi>.
-
-=item invalid option -D%c, use -D'' to see choices
-
-(F) Perl was called with invalid debugger flags. Call perl with
-the B<-D> option with no flags to see the list of acceptable values.
-See also L<< perlrun/B<-D>I<letters> >>.
-
-=item Invalid [] range "%s" in regex; marked by <-- HERE in m/%s/
-
-(F) The range specified in a character class had a minimum character
-greater than the maximum character. One possibility is that you forgot the
-C<{}> from your ending C<\x{}> - C<\x> without the curly braces can go only
-up to C<ff>. The <-- HERE shows in the regular expression about where the
-problem was discovered. See L<perlre>.
-
-=item Invalid range "%s" in transliteration operator
-
-(F) The range specified in the tr/// or y/// operator had a minimum
-character greater than the maximum character. See L<perlop>.
-
-=item Invalid separator character %s in attribute list
-
-(F) Something other than a colon or whitespace was seen between the
-elements of an attribute list. If the previous attribute had a
-parenthesised parameter list, perhaps that list was terminated too soon.
-See L<attributes>.
-
-=item Invalid separator character %s in PerlIO layer specification %s
-
-(W layer) When pushing layers onto the Perl I/O system, something other
-than a colon or whitespace was seen between the elements of a layer list.
-If the previous attribute had a parenthesised parameter list, perhaps that
-list was terminated too soon.
-
-=item Invalid strict version format (%s)
-
-(F) A version number did not meet the "strict" criteria for versions.
-A "strict" version number is a positive decimal number (integer or
-decimal-fraction) without exponentiation or else a dotted-decimal
-v-string with a leading 'v' character and at least three components.
-The parenthesized text indicates which criteria were not met.
-See the L<version> module for more details on allowed version formats.
-
-=item Invalid type '%s' in %s
-
-(F) The given character is not a valid pack or unpack type.
-See L<perlfunc/pack>.
-
-(W) The given character is not a valid pack or unpack type but used to be
-silently ignored.
-
-=item Invalid version format (%s)
-
-(F) A version number did not meet the "lax" criteria for versions.
-A "lax" version number is a positive decimal number (integer or
-decimal-fraction) without exponentiation or else a dotted-decimal
-v-string. If the v-string has fewer than three components, it
-must have a leading 'v' character. Otherwise, the leading 'v' is
-optional. Both decimal and dotted-decimal versions may have a
-trailing "alpha" component separated by an underscore character
-after a fractional or dotted-decimal component. The parenthesized
-text indicates which criteria were not met. See the L<version> module
-for more details on allowed version formats.
-
-=item Invalid version object
-
-(F) The internal structure of the version object was invalid.
-Perhaps the internals were modified directly in some way or
-an arbitrary reference was blessed into the "version" class.
-
-=item ioctl is not implemented
-
-(F) Your machine apparently doesn't implement ioctl(), which is pretty
-strange for a machine that supports C.
-
-=item ioctl() on unopened %s
-
-(W unopened) You tried ioctl() on a filehandle that was never opened.
-Check your control flow and number of arguments.
-
-=item IO layers (like '%s') unavailable
-
-(F) Your Perl has not been configured to have PerlIO, and therefore
-you cannot use IO layers. To have PerlIO, Perl must be configured
-with 'useperlio'.
-
-=item IO::Socket::atmark not implemented on this architecture
-
-(F) Your machine doesn't implement the sockatmark() functionality,
-neither as a system call nor an ioctl call (SIOCATMARK).
-
-=item $* is no longer supported
-
-(D deprecated, syntax) The special variable C<$*>, deprecated in older
-perls, has been removed as of 5.9.0 and is no longer supported. In
-previous versions of perl the use of C<$*> enabled or disabled multi-line
-matching within a string.
-
-Instead of using C<$*> you should use the C</m> (and maybe C</s>) regexp
-modifiers. You can enable C</m> for a lexical scope (even a whole file)
-with C<use re '/m'>. (In older versions: when C<$*> was set to a true value
-then all regular expressions behaved as if they were written using C</m>.)
-
-=item $# is no longer supported
-
-(D deprecated, syntax) The special variable C<$#>, deprecated in older
-perls, has been removed as of 5.9.3 and is no longer supported. You
-should use the printf/sprintf functions instead.
-
-=item '%s' is not a code reference
-
-(W overload) The second (fourth, sixth, ...) argument of
-overload::constant needs to be a code reference. Either
-an anonymous subroutine, or a reference to a subroutine.
-
-=item '%s' is not an overloadable type
-
-(W overload) You tried to overload a constant type the overload package is
-unaware of.
-
-=item junk on end of regexp
-
-(P) The regular expression parser is confused.
-
-=item Label not found for "last %s"
-
-(F) You named a loop to break out of, but you're not currently in a loop
-of that name, not even if you count where you were called from. See
-L<perlfunc/last>.
-
-=item Label not found for "next %s"
-
-(F) You named a loop to continue, but you're not currently in a loop of
-that name, not even if you count where you were called from. See
-L<perlfunc/last>.
-
-=item Label not found for "redo %s"
-
-(F) You named a loop to restart, but you're not currently in a loop of
-that name, not even if you count where you were called from. See
-L<perlfunc/last>.
-
-=item leaving effective %s failed
-
-(F) While under the C<use filetest> pragma, switching the real and
-effective uids or gids failed.
-
-=item length/code after end of string in unpack
-
-(F) While unpacking, the string buffer was already used up when an unpack
-length/code combination tried to obtain more data. This results in
-an undefined value for the length. See L<perlfunc/pack>.
-
-=item length() used on %s
-
-(W syntax) You used length() on either an array or a hash when you
-probably wanted a count of the items.
-
-Array size can be obtained by doing:
-
- scalar(@array);
-
-The number of items in a hash can be obtained by doing:
-
- scalar(keys %hash);
-
-=item Lexing code attempted to stuff non-Latin-1 character into Latin-1 input
-
-(F) An extension is attempting to insert text into the current parse
-(using L<lex_stuff_pvn|perlapi/lex_stuff_pvn> or similar), but tried to insert a character that
-couldn't be part of the current input. This is an inherent pitfall
-of the stuffing mechanism, and one of the reasons to avoid it. Where
-it is necessary to stuff, stuffing only plain ASCII is recommended.
-
-=item Lexing code internal error (%s)
-
-(F) Lexing code supplied by an extension violated the lexer's API in a
-detectable way.
-
-=item listen() on closed socket %s
-
-(W closed) You tried to do a listen on a closed socket. Did you forget
-to check the return value of your socket() call? See
-L<perlfunc/listen>.
-
-=item List form of piped open not implemented
-
-(F) On some platforms, notably Windows, the three-or-more-arguments
-form of C<open> does not support pipes, such as C<open($pipe, '|-', @args)>.
-Use the two-argument C<open($pipe, '|prog arg1 arg2...')> form instead.
-
-=item localtime(%f) too large
-
-(W overflow) You called C<localtime> with a number that was larger
-than it can reliably handle and C<localtime> probably returned the
-wrong date. This warning is also triggered with NaN (the special
-not-a-number value).
-
-=item localtime(%f) too small
-
-(W overflow) You called C<localtime> with a number that was smaller
-than it can reliably handle and C<localtime> probably returned the
-wrong date.
-
-=item Lookbehind longer than %d not implemented in regex m/%s/
-
-(F) There is currently a limit on the length of string which lookbehind can
-handle. This restriction may be eased in a future release.
-
-=item Lost precision when %s %f by 1
-
-(W) The value you attempted to increment or decrement by one is too large
-for the underlying floating point representation to store accurately,
-hence the target of C<++> or C<--> is unchanged. Perl issues this warning
-because it has already switched from integers to floating point when values
-are too large for integers, and now even floating point is insufficient.
-You may wish to switch to using L<Math::BigInt> explicitly.
-
-=item lstat() on filehandle%s
-
-(W io) You tried to do an lstat on a filehandle. What did you mean
-by that? lstat() makes sense only on filenames. (Perl did a fstat()
-instead on the filehandle.)
-
-=item lvalue attribute %s already-defined subroutine
-
-(W misc) Although L<attributes.pm|attributes> allows this, turning the lvalue
-attribute on or off on a Perl subroutine that is already defined
-does not always work properly. It may or may not do what you
-want, depending on what code is inside the subroutine, with exact
-details subject to change between Perl versions. Only do this
-if you really know what you are doing.
-
-=item lvalue attribute ignored after the subroutine has been defined
-
-(W misc) Using the C<:lvalue> declarative syntax to make a Perl
-subroutine an lvalue subroutine after it has been defined is
-not permitted. To make the subroutine an lvalue subroutine,
-add the lvalue attribute to the definition, or put the C<sub
-foo :lvalue;> declaration before the definition.
-
-See also L<attributes.pm|attributes>.
-
-=item Malformed integer in [] in pack
-
-(F) Between the brackets enclosing a numeric repeat count only digits
-are permitted. See L<perlfunc/pack>.
-
-=item Malformed integer in [] in unpack
-
-(F) Between the brackets enclosing a numeric repeat count only digits
-are permitted. See L<perlfunc/pack>.
-
-=item Malformed PERLLIB_PREFIX
-
-(F) An error peculiar to OS/2. PERLLIB_PREFIX should be of the form
-
- prefix1;prefix2
-
-or
- prefix1 prefix2
-
-with nonempty prefix1 and prefix2. If C<prefix1> is indeed a prefix of
-a builtin library search path, prefix2 is substituted. The error may
-appear if components are not found, or are too long. See
-"PERLLIB_PREFIX" in L<perlos2>.
-
-=item Malformed prototype for %s: %s
-
-(F) You tried to use a function with a malformed prototype. The
-syntax of function prototypes is given a brief compile-time check for
-obvious errors like invalid characters. A more rigorous check is run
-when the function is called.
-
-=item Malformed UTF-8 character (%s)
-
-(S utf8)(F) Perl detected a string that didn't comply with UTF-8
-encoding rules, even though it had the UTF8 flag on.
-
-One possible cause is that you set the UTF8 flag yourself for data that
-you thought to be in UTF-8 but it wasn't (it was for example legacy
-8-bit data). To guard against this, you can use Encode::decode_utf8.
-
-If you use the C<:encoding(UTF-8)> PerlIO layer for input, invalid byte
-sequences are handled gracefully, but if you use C<:utf8>, the flag is
-set without validating the data, possibly resulting in this error
-message.
-
-See also L<Encode/"Handling Malformed Data">.
-
-=item Malformed UTF-8 returned by \N
-
-(F) The charnames handler returned malformed UTF-8.
-
-=item Malformed UTF-8 string in '%c' format in unpack
-
-(F) You tried to unpack something that didn't comply with UTF-8 encoding
-rules and perl was unable to guess how to make more progress.
-
-=item Malformed UTF-8 string in pack
-
-(F) You tried to pack something that didn't comply with UTF-8 encoding
-rules and perl was unable to guess how to make more progress.
-
-=item Malformed UTF-8 string in unpack
-
-(F) You tried to unpack something that didn't comply with UTF-8 encoding
-rules and perl was unable to guess how to make more progress.
-
-=item Malformed UTF-16 surrogate
-
-(F) Perl thought it was reading UTF-16 encoded character data but while
-doing it Perl met a malformed Unicode surrogate.
-
-=item %s matches null string many times in regex; marked by <-- HERE in m/%s/
-
-(W regexp) The pattern you've specified would be an infinite loop if the
-regular expression engine didn't specifically check for that. The <-- HERE
-shows in the regular expression about where the problem was discovered.
-See L<perlre>.
-
-=item Maximal count of pending signals (%u) exceeded
-
-(F) Perl aborted due to too high a number of signals pending. This
-usually indicates that your operating system tried to deliver signals
-too fast (with a very high priority), starving the perl process from
-resources it would need to reach a point where it can process signals
-safely. (See L<perlipc/"Deferred Signals (Safe Signals)">.)
-
-=item "%s" may clash with future reserved word
-
-(W) This warning may be due to running a perl5 script through a perl4
-interpreter, especially if the word that is being warned about is
-"use" or "my".
-
-=item '%' may not be used in pack
-
-(F) You can't pack a string by supplying a checksum, because the
-checksumming process loses information, and you can't go the other way.
-See L<perlfunc/unpack>.
-
-=item Method for operation %s not found in package %s during blessing
-
-(F) An attempt was made to specify an entry in an overloading table that
-doesn't resolve to a valid subroutine. See L<overload>.
-
-=item Method %s not permitted
-
-See Server error.
-
-=item Might be a runaway multi-line %s string starting on line %d
-
-(S) An advisory indicating that the previous error may have been caused
-by a missing delimiter on a string or pattern, because it eventually
-ended earlier on the current line.
-
-=item Misplaced _ in number
-
-(W syntax) An underscore (underbar) in a numeric constant did not
-separate two digits.
-
-=item Missing argument in %s
-
-(W uninitialized) A printf-type format required more arguments than were
-supplied.
-
-=item Missing argument to -%c
-
-(F) The argument to the indicated command line switch must follow
-immediately after the switch, without intervening spaces.
-
-=item Missing braces on \N{}
-
-(F) Wrong syntax of character name literal C<\N{charname}> within
-double-quotish context. This can also happen when there is a space
-(or comment) between the C<\N> and the C<{> in a regex with the C</x> modifier.
-This modifier does not change the requirement that the brace immediately
-follow the C<\N>.
-
-=item Missing braces on \o{}
-
-(F) A C<\o> must be followed immediately by a C<{> in double-quotish context.
-
-=item Missing comma after first argument to %s function
-
-(F) While certain functions allow you to specify a filehandle or an
-"indirect object" before the argument list, this ain't one of them.
-
-=item Missing command in piped open
-
-(W pipe) You used the C<open(FH, "| command")> or
-C<open(FH, "command |")> construction, but the command was missing or
-blank.
-
-=item Missing control char name in \c
-
-(F) A double-quoted string ended with "\c", without the required control
-character name.
-
-=item Missing name in "my sub"
-
-(F) The reserved syntax for lexically scoped subroutines requires that
-they have a name with which they can be found.
-
-=item Missing $ on loop variable
-
-(F) Apparently you've been programming in B<csh> too much. Variables
-are always mentioned with the $ in Perl, unlike in the shells, where it
-can vary from one line to the next.
-
-=item (Missing operator before %s?)
-
-(S syntax) This is an educated guess made in conjunction with the message
-"%s found where operator expected". Often the missing operator is a comma.
-
-=item Missing right brace on %s
-
-(F) Missing right brace in C<\x{...}>, C<\p{...}>, C<\P{...}>, or C<\N{...}>.
-
-=item Missing right brace on \N{} or unescaped left brace after \N
-
-(F) C<\N> has two meanings.
-
-The traditional one has it followed by a name enclosed in braces,
-meaning the character (or sequence of characters) given by that
-name. Thus C<\N{ASTERISK}> is another way of writing C<*>, valid in both
-double-quoted strings and regular expression patterns. In patterns,
-it doesn't have the meaning an unescaped C<*> does.
-
-Starting in Perl 5.12.0, C<\N> also can have an additional meaning (only)
-in patterns, namely to match a non-newline character. (This is short
-for C<[^\n]>, and like C<.> but is not affected by the C</s> regex modifier.)
-
-This can lead to some ambiguities. When C<\N> is not followed immediately
-by a left brace, Perl assumes the C<[^\n]> meaning. Also, if the braces
-form a valid quantifier such as C<\N{3}> or C<\N{5,}>, Perl assumes that this
-means to match the given quantity of non-newlines (in these examples,
-3; and 5 or more, respectively). In all other case, where there is a
-C<\N{> and a matching C<}>, Perl assumes that a character name is desired.
-
-However, if there is no matching C<}>, Perl doesn't know if it was
-mistakenly omitted, or if C<[^\n]{> was desired, and raises this error.
-If you meant the former, add the right brace; if you meant the latter,
-escape the brace with a backslash, like so: C<\N\{>
-
-=item Missing right curly or square bracket
-
-(F) The lexer counted more opening curly or square brackets than closing
-ones. As a general rule, you'll find it's missing near the place you
-were last editing.
-
-=item (Missing semicolon on previous line?)
-
-(S syntax) This is an educated guess made in conjunction with the message
-"%s found where operator expected". Don't automatically put a semicolon on
-the previous line just because you saw this message.
-
-=item Modification of a read-only value attempted
-
-(F) You tried, directly or indirectly, to change the value of a
-constant. You didn't, of course, try "2 = 1", because the compiler
-catches that. But an easy way to do the same thing is:
-
- sub mod { $_[0] = 1 }
- mod(2);
-
-Another way is to assign to a substr() that's off the end of the string.
-
-Yet another way is to assign to a C<foreach> loop I<VAR> when I<VAR>
-is aliased to a constant in the look I<LIST>:
-
- $x = 1;
- foreach my $n ($x, 2) {
- $n *= 2; # modifies the $x, but fails on attempt to
- } # modify the 2
-
-=item Modification of non-creatable array value attempted, %s
-
-(F) You tried to make an array value spring into existence, and the
-subscript was probably negative, even counting from end of the array
-backwards.
-
-=item Modification of non-creatable hash value attempted, %s
-
-(P) You tried to make a hash value spring into existence, and it
-couldn't be created for some peculiar reason.
-
-=item Module name must be constant
-
-(F) Only a bare module name is allowed as the first argument to a "use".
-
-=item Module name required with -%c option
-
-(F) The C<-M> or C<-m> options say that Perl should load some module, but
-you omitted the name of the module. Consult L<perlrun> for full details
-about C<-M> and C<-m>.
-
-=item More than one argument to '%s' open
-
-(F) The C<open> function has been asked to open multiple files. This
-can happen if you are trying to open a pipe to a command that takes a
-list of arguments, but have forgotten to specify a piped open mode.
-See L<perlfunc/open> for details.
-
-=item msg%s not implemented
-
-(F) You don't have System V message IPC on your system.
-
-=item Multidimensional syntax %s not supported
-
-(W syntax) Multidimensional arrays aren't written like C<$foo[1,2,3]>.
-They're written like C<$foo[1][2][3]>, as in C.
-
-=item '/' must follow a numeric type in unpack
-
-(F) You had an unpack template that contained a '/', but this did not
-follow some unpack specification producing a numeric value.
-See L<perlfunc/pack>.
-
-=item "my sub" not yet implemented
-
-(F) Lexically scoped subroutines are not yet implemented. Don't try
-that yet.
-
-=item "my" variable %s can't be in a package
-
-(F) Lexically scoped variables aren't in a package, so it doesn't make
-sense to try to declare one with a package qualifier on the front. Use
-local() if you want to localize a package variable.
-
-=item Name "%s::%s" used only once: possible typo
-
-(W once) Typographical errors often show up as unique variable names.
-If you had a good reason for having a unique name, then just mention it
-again somehow to suppress the message. The C<our> declaration is
-provided for this purpose.
-
-NOTE: This warning detects symbols that have been used only once so $c, @c,
-%c, *c, &c, sub c{}, c(), and c (the filehandle or format) are considered
-the same; if a program uses $c only once but also uses any of the others it
-will not trigger this warning.
-
-=item \N in a character class must be a named character: \N{...}
-
-(F) The new (5.12) meaning of C<\N> as C<[^\n]> is not valid in a bracketed
-character class, for the same reason that C<.> in a character class loses
-its specialness: it matches almost everything, which is probably not
-what you want.
-
-=item \N{NAME} must be resolved by the lexer
-
-(F) When compiling a regex pattern, an unresolved named character or
-sequence was encountered. This can happen in any of several ways that
-bypass the lexer, such as using single-quotish context, or an extra
-backslash in double-quotish:
-
- $re = '\N{SPACE}'; # Wrong!
- $re = "\\N{SPACE}"; # Wrong!
- /$re/;
-
-Instead, use double-quotes with a single backslash:
-
- $re = "\N{SPACE}"; # ok
- /$re/;
-
-The lexer can be bypassed as well by creating the pattern from smaller
-components:
-
- $re = '\N';
- /${re}{SPACE}/; # Wrong!
-
-It's not a good idea to split a construct in the middle like this, and it
-doesn't work here. Instead use the solution above.
-
-Finally, the message also can happen under the C</x> regex modifier when the
-C<\N> is separated by spaces from the C<{>, in which case, remove the spaces.
-
- /\N {SPACE}/x; # Wrong!
- /\N{SPACE}/x; # ok
-
-=item Negative '/' count in unpack
-
-(F) The length count obtained from a length/code unpack operation was
-negative. See L<perlfunc/pack>.
-
-=item Negative length
-
-(F) You tried to do a read/write/send/recv operation with a buffer
-length that is less than 0. This is difficult to imagine.
-
-=item Negative offset to vec in lvalue context
-
-(F) When C<vec> is called in an lvalue context, the second argument must be
-greater than or equal to zero.
-
-=item Nested quantifiers in regex; marked by <-- HERE in m/%s/
-
-(F) You can't quantify a quantifier without intervening parentheses.
-So things like ** or +* or ?* are illegal. The <-- HERE shows in the
-regular expression about where the problem was discovered.
-
-Note that the minimal matching quantifiers, C<*?>, C<+?>, and
-C<??> appear to be nested quantifiers, but aren't. See L<perlre>.
-
-=item %s never introduced
-
-(S internal) The symbol in question was declared but somehow went out of
-scope before it could possibly have been used.
-
-=item next::method/next::can/maybe::next::method cannot find enclosing method
-
-(F) C<next::method> needs to be called within the context of a
-real method in a real package, and it could not find such a context.
-See L<mro>.
-
-=item No %s allowed while running setuid
-
-(F) Certain operations are deemed to be too insecure for a setuid or
-setgid script to even be allowed to attempt. Generally speaking there
-will be another way to do what you want that is, if not secure, at least
-securable. See L<perlsec>.
-
-=item No code specified for -%c
-
-(F) Perl's B<-e> and B<-E> command-line options require an argument. If
-you want to run an empty program, pass the empty string as a separate
-argument or run a program consisting of a single 0 or 1:
-
- perl -e ""
- perl -e0
- perl -e1
-
-=item No comma allowed after %s
-
-(F) A list operator that has a filehandle or "indirect object" is
-not allowed to have a comma between that and the following arguments.
-Otherwise it'd be just another one of the arguments.
-
-One possible cause for this is that you expected to have imported
-a constant to your name space with B<use> or B<import> while no such
-importing took place, it may for example be that your operating
-system does not support that particular constant. Hopefully you did
-use an explicit import list for the constants you expect to see;
-please see L<perlfunc/use> and L<perlfunc/import>. While an
-explicit import list would probably have caught this error earlier
-it naturally does not remedy the fact that your operating system
-still does not support that constant. Maybe you have a typo in
-the constants of the symbol import list of B<use> or B<import> or in the
-constant name at the line where this error was triggered?
-
-=item No command into which to pipe on command line
-
-(F) An error peculiar to VMS. Perl handles its own command line
-redirection, and found a '|' at the end of the command line, so it
-doesn't know where you want to pipe the output from this command.
-
-=item No DB::DB routine defined
-
-(F) The currently executing code was compiled with the B<-d> switch, but
-for some reason the current debugger (e.g. F<perl5db.pl> or a C<Devel::>
-module) didn't define a routine to be called at the beginning of each
-statement.
-
-=item No dbm on this machine
-
-(P) This is counted as an internal error, because every machine should
-supply dbm nowadays, because Perl comes with SDBM. See L<SDBM_File>.
-
-=item No DB::sub routine defined
-
-(F) The currently executing code was compiled with the B<-d> switch, but
-for some reason the current debugger (e.g. F<perl5db.pl> or a C<Devel::>
-module) didn't define a C<DB::sub> routine to be called at the beginning
-of each ordinary subroutine call.
-
-=item No directory specified for -I
-
-(F) The B<-I> command-line switch requires a directory name as part of the
-I<same> argument. Use B<-Ilib>, for instance. B<-I lib> won't work.
-
-=item No error file after 2> or 2>> on command line
-
-(F) An error peculiar to VMS. Perl handles its own command line
-redirection, and found a '2>' or a '2>>' on the command line, but can't
-find the name of the file to which to write data destined for stderr.
-
-=item No group ending character '%c' found in template
-
-(F) A pack or unpack template has an opening '(' or '[' without its
-matching counterpart. See L<perlfunc/pack>.
-
-=item No input file after < on command line
-
-(F) An error peculiar to VMS. Perl handles its own command line
-redirection, and found a '<' on the command line, but can't find the
-name of the file from which to read data for stdin.
-
-=item No next::method '%s' found for %s
-
-(F) C<next::method> found no further instances of this method name
-in the remaining packages of the MRO of this class. If you don't want
-it throwing an exception, use C<maybe::next::method>
-or C<next::can>. See L<mro>.
-
-=item "no" not allowed in expression
-
-(F) The "no" keyword is recognized and executed at compile time, and
-returns no useful value. See L<perlmod>.
-
-=item No output file after > on command line
-
-(F) An error peculiar to VMS. Perl handles its own command line
-redirection, and found a lone '>' at the end of the command line, so it
-doesn't know where you wanted to redirect stdout.
-
-=item No output file after > or >> on command line
-
-(F) An error peculiar to VMS. Perl handles its own command line
-redirection, and found a '>' or a '>>' on the command line, but can't
-find the name of the file to which to write data destined for stdout.
-
-=item No package name allowed for variable %s in "our"
-
-(F) Fully qualified variable names are not allowed in "our"
-declarations, because that doesn't make much sense under existing
-semantics. Such syntax is reserved for future extensions.
-
-=item No Perl script found in input
-
-(F) You called C<perl -x>, but no line was found in the file beginning
-with #! and containing the word "perl".
-
-=item No setregid available
-
-(F) Configure didn't find anything resembling the setregid() call for
-your system.
-
-=item No setreuid available
-
-(F) Configure didn't find anything resembling the setreuid() call for
-your system.
-
-=item No such class field "%s" in variable %s of type %s
-
-(F) You tried to access a key from a hash through the indicated typed
-variable but that key is not allowed by the package of the same type.
-The indicated package has restricted the set of allowed keys using the
-L<fields> pragma.
-
-=item No such class %s
-
-(F) You provided a class qualifier in a "my", "our" or "state"
-declaration, but this class doesn't exist at this point in your program.
-
-=item No such hook: %s
-
-(F) You specified a signal hook that was not recognized by Perl.
-Currently, Perl accepts C<__DIE__> and C<__WARN__> as valid signal hooks.
-
-=item No such pipe open
-
-(P) An error peculiar to VMS. The internal routine my_pclose() tried to
-close a pipe which hadn't been opened. This should have been caught
-earlier as an attempt to close an unopened filehandle.
-
-=item No such signal: SIG%s
-
-(W signal) You specified a signal name as a subscript to %SIG that was
-not recognized. Say C<kill -l> in your shell to see the valid signal
-names on your system.
-
-=item Not a CODE reference
-
-(F) Perl was trying to evaluate a reference to a code value (that is, a
-subroutine), but found a reference to something else instead. You can
-use the ref() function to find out what kind of ref it really was. See
-also L<perlref>.
-
-=item Not a format reference
-
-(F) I'm not sure how you managed to generate a reference to an anonymous
-format, but this indicates you did, and that it didn't exist.
-
-=item Not a GLOB reference
-
-(F) Perl was trying to evaluate a reference to a "typeglob" (that is, a
-symbol table entry that looks like C<*foo>), but found a reference to
-something else instead. You can use the ref() function to find out what
-kind of ref it really was. See L<perlref>.
-
-=item Not a HASH reference
-
-(F) Perl was trying to evaluate a reference to a hash value, but found a
-reference to something else instead. You can use the ref() function to
-find out what kind of ref it really was. See L<perlref>.
-
-=item Not an ARRAY reference
-
-(F) Perl was trying to evaluate a reference to an array value, but found
-a reference to something else instead. You can use the ref() function
-to find out what kind of ref it really was. See L<perlref>.
-
-=item Not an unblessed ARRAY reference
-
-(F) You passed a reference to a blessed array to C<push>, C<shift> or
-another array function. These only accept unblessed array references
-or arrays beginning explicitly with C<@>.
-
-=item Not a SCALAR reference
-
-(F) Perl was trying to evaluate a reference to a scalar value, but found
-a reference to something else instead. You can use the ref() function
-to find out what kind of ref it really was. See L<perlref>.
-
-=item Not a subroutine reference
-
-(F) Perl was trying to evaluate a reference to a code value (that is, a
-subroutine), but found a reference to something else instead. You can
-use the ref() function to find out what kind of ref it really was. See
-also L<perlref>.
-
-=item Not a subroutine reference in overload table
-
-(F) An attempt was made to specify an entry in an overloading table that
-doesn't somehow point to a valid subroutine. See L<overload>.
-
-=item Not enough arguments for %s
-
-(F) The function requires more arguments than you specified.
-
-=item Not enough format arguments
-
-(W syntax) A format specified more picture fields than the next line
-supplied. See L<perlform>.
-
-=item %s: not found
-
-(A) You've accidentally run your script through the Bourne shell instead
-of Perl. Check the #! line, or manually feed your script into Perl
-yourself.
-
-=item no UTC offset information; assuming local time is UTC
-
-(S) A warning peculiar to VMS. Perl was unable to find the local
-timezone offset, so it's assuming that local system time is equivalent
-to UTC. If it's not, define the logical name
-F<SYS$TIMEZONE_DIFFERENTIAL> to translate to the number of seconds which
-need to be added to UTC to get local time.
-
-=item Non-octal character '%c'. Resolved as "%s"
-
-(W digit) In parsing an octal numeric constant, a character was
-unexpectedly encountered that isn't octal. The resulting value
-is as indicated.
-
-=item Non-string passed as bitmask
-
-(W misc) A number has been passed as a bitmask argument to select().
-Use the vec() function to construct the file descriptor bitmasks for
-select. See L<perlfunc/select>.
-
-=item Null filename used
-
-(F) You can't require the null filename, especially because on many
-machines that means the current directory! See L<perlfunc/require>.
-
-=item NULL OP IN RUN
-
-(S debugging) Some internal routine called run() with a null opcode
-pointer.
-
-=item Null picture in formline
-
-(F) The first argument to formline must be a valid format picture
-specification. It was found to be empty, which probably means you
-supplied it an uninitialized value. See L<perlform>.
-
-=item Null realloc
-
-(P) An attempt was made to realloc NULL.
-
-=item NULL regexp argument
-
-(P) The internal pattern matching routines blew it big time.
-
-=item NULL regexp parameter
-
-(P) The internal pattern matching routines are out of their gourd.
-
-=item Number too long
-
-(F) Perl limits the representation of decimal numbers in programs to
-about 250 characters. You've exceeded that length. Future
-versions of Perl are likely to eliminate this arbitrary limitation. In
-the meantime, try using scientific notation (e.g. "1e6" instead of
-"1_000_000").
-
-=item Number with no digits
-
-(F) Perl was looking for a number but found nothing that looked like
-a number. This happens, for example with C<\o{}>, with no number between
-the braces.
-
-=item Octal number > 037777777777 non-portable
-
-(W portable) The octal number you specified is larger than 2**32-1
-(4294967295) and therefore non-portable between systems. See
-L<perlport> for more on portability concerns.
-
-=item Odd number of arguments for overload::constant
-
-(W overload) The call to overload::constant contained an odd number of
-arguments. The arguments should come in pairs.
-
-=item Odd number of elements in anonymous hash
-
-(W misc) You specified an odd number of elements to initialize a hash,
-which is odd, because hashes come in key/value pairs.
-
-=item Odd number of elements in hash assignment
-
-(W misc) You specified an odd number of elements to initialize a hash,
-which is odd, because hashes come in key/value pairs.
-
-=item Offset outside string
-
-(F)(W layer) You tried to do a read/write/send/recv/seek operation
-with an offset pointing outside the buffer. This is difficult to
-imagine. The sole exceptions to this are that zero padding will
-take place when going past the end of the string when either
-C<sysread()>ing a file, or when seeking past the end of a scalar opened
-for I/O (in anticipation of future reads and to imitate the behaviour
-with real files).
-
-=item %s() on unopened %s
-
-(W unopened) An I/O operation was attempted on a filehandle that was
-never initialized. You need to do an open(), a sysopen(), or a socket()
-call, or call a constructor from the FileHandle package.
-
-=item -%s on unopened filehandle %s
-
-(W unopened) You tried to invoke a file test operator on a filehandle
-that isn't open. Check your control flow. See also L<perlfunc/-X>.
-
-=item oops: oopsAV
-
-(S internal) An internal warning that the grammar is screwed up.
-
-=item oops: oopsHV
-
-(S internal) An internal warning that the grammar is screwed up.
-
-=item Opening dirhandle %s also as a file
-
-(W io, deprecated) You used open() to associate a filehandle to
-a symbol (glob or scalar) that already holds a dirhandle.
-Although legal, this idiom might render your code confusing
-and is deprecated.
-
-=item Opening filehandle %s also as a directory
-
-(W io, deprecated) You used opendir() to associate a dirhandle to
-a symbol (glob or scalar) that already holds a filehandle.
-Although legal, this idiom might render your code confusing
-and is deprecated.
-
-=item Operation "%s": no method found, %s
-
-(F) An attempt was made to perform an overloaded operation for which no
-handler was defined. While some handlers can be autogenerated in terms
-of other handlers, there is no default handler for any operation, unless
-the C<fallback> overloading key is specified to be true. See L<overload>.
-
-=item Operation "%s" returns its argument for non-Unicode code point 0x%X
-
-(W utf8, non_unicode) You performed an operation requiring Unicode
-semantics on a code point that is not in Unicode, so what it should do
-is not defined. Perl has chosen to have it do nothing, and warn you.
-
-If the operation shown is "ToFold", it means that case-insensitive
-matching in a regular expression was done on the code point.
-
-If you know what you are doing you can turn off this warning by
-C<no warnings 'non_unicode';>.
-
-=item Operation "%s" returns its argument for UTF-16 surrogate U+%X
-
-(W utf8, surrogate) You performed an operation requiring Unicode
-semantics on a Unicode surrogate. Unicode frowns upon the use of
-surrogates for anything but storing strings in UTF-16, but semantics
-are (reluctantly) defined for the surrogates, and they are to do
-nothing for this operation. Because the use of surrogates can be
-dangerous, Perl warns.
-
-If the operation shown is "ToFold", it means that case-insensitive
-matching in a regular expression was done on the code point.
-
-If you know what you are doing you can turn off this warning by
-C<no warnings 'surrogate';>.
-
-=item Operator or semicolon missing before %s
-
-(S ambiguous) You used a variable or subroutine call where the parser
-was expecting an operator. The parser has assumed you really meant to
-use an operator, but this is highly likely to be incorrect. For
-example, if you say "*foo *foo" it will be interpreted as if you said
-"*foo * 'foo'".
-
-=item "our" variable %s redeclared
-
-(W misc) You seem to have already declared the same global once before
-in the current lexical scope.
-
-=item Out of memory!
-
-(X) The malloc() function returned 0, indicating there was insufficient
-remaining memory (or virtual memory) to satisfy the request. Perl has
-no option but to exit immediately.
-
-At least in Unix you may be able to get past this by increasing your
-process datasize limits: in csh/tcsh use C<limit> and
-C<limit datasize n> (where C<n> is the number of kilobytes) to check
-the current limits and change them, and in ksh/bash/zsh use C<ulimit -a>
-and C<ulimit -d n>, respectively.
-
-=item Out of memory during %s extend
-
-(X) An attempt was made to extend an array, a list, or a string beyond
-the largest possible memory allocation.
-
-=item Out of memory during "large" request for %s
-
-(F) The malloc() function returned 0, indicating there was insufficient
-remaining memory (or virtual memory) to satisfy the request. However,
-the request was judged large enough (compile-time default is 64K), so a
-possibility to shut down by trapping this error is granted.
-
-=item Out of memory during request for %s
-
-(X)(F) The malloc() function returned 0, indicating there was
-insufficient remaining memory (or virtual memory) to satisfy the
-request.
-
-The request was judged to be small, so the possibility to trap it
-depends on the way perl was compiled. By default it is not trappable.
-However, if compiled for this, Perl may use the contents of C<$^M> as an
-emergency pool after die()ing with this message. In this case the error
-is trappable I<once>, and the error message will include the line and file
-where the failed request happened.
-
-=item Out of memory during ridiculously large request
-
-(F) You can't allocate more than 2^31+"small amount" bytes. This error
-is most likely to be caused by a typo in the Perl program. e.g.,
-C<$arr[time]> instead of C<$arr[$time]>.
-
-=item Out of memory for yacc stack
-
-(F) The yacc parser wanted to grow its stack so it could continue
-parsing, but realloc() wouldn't give it more memory, virtual or
-otherwise.
-
-=item '.' outside of string in pack
-
-(F) The argument to a '.' in your template tried to move the working
-position to before the start of the packed string being built.
-
-=item '@' outside of string in unpack
-
-(F) You had a template that specified an absolute position outside
-the string being unpacked. See L<perlfunc/pack>.
-
-=item '@' outside of string with malformed UTF-8 in unpack
-
-(F) You had a template that specified an absolute position outside
-the string being unpacked. The string being unpacked was also invalid
-UTF-8. See L<perlfunc/pack>.
-
-=item overload arg '%s' is invalid
-
-(W overload) The L<overload> pragma was passed an argument it did not
-recognize. Did you mistype an operator?
-
-=item Overloaded dereference did not return a reference
-
-(F) An object with an overloaded dereference operator was dereferenced,
-but the overloaded operation did not return a reference. See
-L<overload>.
-
-=item Overloaded qr did not return a REGEXP
-
-(F) An object with a C<qr> overload was used as part of a match, but the
-overloaded operation didn't return a compiled regexp. See L<overload>.
-
-=item %s package attribute may clash with future reserved word: %s
-
-(W reserved) A lowercase attribute name was used that had a
-package-specific handler. That name might have a meaning to Perl itself
-some day, even though it doesn't yet. Perhaps you should use a
-mixed-case attribute name, instead. See L<attributes>.
-
-=item pack/unpack repeat count overflow
-
-(F) You can't specify a repeat count so large that it overflows your
-signed integers. See L<perlfunc/pack>.
-
-=item page overflow
-
-(W io) A single call to write() produced more lines than can fit on a
-page. See L<perlform>.
-
-=item panic: %s
-
-(P) An internal error.
-
-=item panic: attempt to call %s in %s
-
-(P) One of the file test operators entered a code branch that calls
-an ACL related-function, but that function is not available on this
-platform. Earlier checks mean that it should not be possible to
-enter this branch on this platform.
-
-=item panic: ck_grep, type=%u
-
-(P) Failed an internal consistency check trying to compile a grep.
-
-=item panic: ck_split, type=%u
-
-(P) Failed an internal consistency check trying to compile a split.
-
-=item panic: corrupt saved stack index %ld
-
-(P) The savestack was requested to restore more localized values than
-there are in the savestack.
-
-=item panic: del_backref
-
-(P) Failed an internal consistency check while trying to reset a weak
-reference.
-
-=item panic: die %s
-
-(P) We popped the context stack to an eval context, and then discovered
-it wasn't an eval context.
-
-=item panic: do_subst
-
-(P) The internal pp_subst() routine was called with invalid operational
-data.
-
-=item panic: do_trans_%s
-
-(P) The internal do_trans routines were called with invalid operational
-data.
-
-=item panic: fold_constants JMPENV_PUSH returned %d
-
-(P) While attempting folding constants an exception other than an C<eval>
-failure was caught.
-
-=item panic: frexp
-
-(P) The library function frexp() failed, making printf("%f") impossible.
-
-=item panic: goto, type=%u, ix=%ld
-
-(P) We popped the context stack to a context with the specified label,
-and then discovered it wasn't a context we know how to do a goto in.
-
-=item panic: gp_free failed to free glob pointer
-
-(P) The internal routine used to clear a typeglob's entries tried
-repeatedly, but each time something re-created entries in the glob.
-Most likely the glob contains an object with a reference back to
-the glob and a destructor that adds a new object to the glob.
-
-=item panic: INTERPCASEMOD, %s
-
-(P) The lexer got into a bad state at a case modifier.
-
-=item panic: INTERPCONCAT, %s
-
-(P) The lexer got into a bad state parsing a string with brackets.
-
-=item panic: kid popen errno read
-
-(F) forked child returned an incomprehensible message about its errno.
-
-=item panic: last, type=%u
-
-(P) We popped the context stack to a block context, and then discovered
-it wasn't a block context.
-
-=item panic: leave_scope clearsv
-
-(P) A writable lexical variable became read-only somehow within the
-scope.
-
-=item panic: leave_scope inconsistency %u
-
-(P) The savestack probably got out of sync. At least, there was an
-invalid enum on the top of it.
-
-=item panic: magic_killbackrefs
-
-(P) Failed an internal consistency check while trying to reset all weak
-references to an object.
-
-=item panic: malloc, %s
-
-(P) Something requested a negative number of bytes of malloc.
-
-=item panic: memory wrap
-
-(P) Something tried to allocate more memory than possible.
-
-=item panic: pad_alloc, %p!=%p
-
-(P) The compiler got confused about which scratch pad it was allocating
-and freeing temporaries and lexicals from.
-
-=item panic: pad_free curpad, %p!=%p
-
-(P) The compiler got confused about which scratch pad it was allocating
-and freeing temporaries and lexicals from.
-
-=item panic: pad_free po
-
-(P) An invalid scratch pad offset was detected internally.
-
-=item panic: pad_reset curpad, %p!=%p
-
-(P) The compiler got confused about which scratch pad it was allocating
-and freeing temporaries and lexicals from.
-
-=item panic: pad_sv po
-
-(P) An invalid scratch pad offset was detected internally.
-
-=item panic: pad_swipe curpad, %p!=%p
-
-(P) The compiler got confused about which scratch pad it was allocating
-and freeing temporaries and lexicals from.
-
-=item panic: pad_swipe po
-
-(P) An invalid scratch pad offset was detected internally.
-
-=item panic: pp_iter, type=%u
-
-(P) The foreach iterator got called in a non-loop context frame.
-
-=item panic: pp_match%s
-
-(P) The internal pp_match() routine was called with invalid operational
-data.
-
-=item panic: pp_split, pm=%p, s=%p
-
-(P) Something terrible went wrong in setting up for the split.
-
-=item panic: realloc, %s
-
-(P) Something requested a negative number of bytes of realloc.
-
-=item panic: reference miscount on nsv in sv_replace() (%d != 1)
-
-(P) The internal sv_replace() function was handed a new SV with a
-reference count other than 1.
-
-=item panic: restartop in %s
-
-(P) Some internal routine requested a goto (or something like it), and
-didn't supply the destination.
-
-=item panic: return, type=%u
-
-(P) We popped the context stack to a subroutine or eval context, and
-then discovered it wasn't a subroutine or eval context.
-
-=item panic: scan_num, %s
-
-(P) scan_num() got called on something that wasn't a number.
-
-=item panic: sv_chop %s
-
-(P) The sv_chop() routine was passed a position that is not within the
-scalar's string buffer.
-
-=item panic: sv_insert, midend=%p, bigend=%p
-
-(P) The sv_insert() routine was told to remove more string than there
-was string.
-
-=item panic: strxfrm() gets absurd - a => %u, ab => %u
-
-(P) The interpreter's sanity check of the C function strxfrm() failed.
-In your current locale the returned transformation of the string "ab" is
-shorter than that of the string "a", which makes no sense.
-
-=item panic: top_env
-
-(P) The compiler attempted to do a goto, or something weird like that.
-
-=item panic: unimplemented op %s (#%d) called
-
-(P) The compiler is screwed up and attempted to use an op that isn't
-permitted at run time.
-
-=item panic: utf16_to_utf8: odd bytelen
-
-(P) Something tried to call utf16_to_utf8 with an odd (as opposed
-to even) byte length.
-
-=item panic: utf16_to_utf8_reversed: odd bytelen
-
-(P) Something tried to call utf16_to_utf8_reversed with an odd (as opposed
-to even) byte length.
-
-=item panic: yylex, %s
-
-(P) The lexer got into a bad state while processing a case modifier.
-
-=item Parsing code internal error (%s)
-
-(F) Parsing code supplied by an extension violated the parser's API in
-a detectable way.
-
-=item Pattern subroutine nesting without pos change exceeded limit in regex; marked by <-- HERE in m/%s/
-
-(F) You used a pattern that uses too many nested subpattern calls without
-consuming any text. Restructure the pattern so text is consumed before
-the nesting limit is exceeded.
-
-The <-- HERE shows in the regular expression about where the problem was
-discovered.
-
-=item Parentheses missing around "%s" list
-
-(W parenthesis) You said something like
-
- my $foo, $bar = @_;
-
-when you meant
-
- my ($foo, $bar) = @_;
-
-Remember that "my", "our", "local" and "state" bind tighter than comma.
-
-=item C<-p> destination: %s
-
-(F) An error occurred during the implicit output invoked by the C<-p>
-command-line switch. (This output goes to STDOUT unless you've
-redirected it with select().)
-
-=item (perhaps you forgot to load "%s"?)
-
-(F) This is an educated guess made in conjunction with the message
-"Can't locate object method \"%s\" via package \"%s\"". It often means
-that a method requires a package that has not been loaded.
-
-=item Perl folding rules are not up-to-date for 0x%x; please use the perlbug utility to report
-
-(W regex, deprecated) You used a regular expression with
-case-insensitive matching, and there is a bug in Perl in which the
-built-in regular expression folding rules are not accurate. This may
-lead to incorrect results. Please report this as a bug using the
-"perlbug" utility. (This message is marked deprecated, so that it by
-default will be turned-on.)
-
-=item Perl_my_%s() not available
-
-(F) Your platform has very uncommon byte-order and integer size,
-so it was not possible to set up some or all fixed-width byte-order
-conversion functions. This is only a problem when you're using the
-'<' or '>' modifiers in (un)pack templates. See L<perlfunc/pack>.
-
-=item Perl %s required (did you mean %s?)--this is only %s, stopped
-
-(F) The code you are trying to run has asked for a newer version of
-Perl than you are running. Perhaps C<use 5.10> was written instead
-of C<use 5.010> or C<use v5.10>. Without the leading C<v>, the number is
-interpreted as a decimal, with every three digits after the
-decimal point representing a part of the version number. So 5.10
-is equivalent to v5.100.
-
-=item Perl %s required--this is only version %s, stopped
-
-(F) The module in question uses features of a version of Perl more
-recent than the currently running version. How long has it been since
-you upgraded, anyway? See L<perlfunc/require>.
-
-=item PERL_SH_DIR too long
-
-(F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the
-C<sh>-shell in. See "PERL_SH_DIR" in L<perlos2>.
-
-=item PERL_SIGNALS illegal: "%s"
-
-See L<perlrun/PERL_SIGNALS> for legal values.
-
-=item Perls since %s too modern--this is %s, stopped
-
-(F) The code you are trying to run claims it will not run
-on the version of Perl you are using because it is too new.
-Maybe the code needs to be updated, or maybe it is simply
-wrong and the version check should just be removed.
-
-=item perl: warning: Setting locale failed.
-
-(S) The whole warning message will look something like:
-
- perl: warning: Setting locale failed.
- perl: warning: Please check that your locale settings:
- LC_ALL = "En_US",
- LANG = (unset)
- are supported and installed on your system.
- perl: warning: Falling back to the standard locale ("C").
-
-Exactly what were the failed locale settings varies. In the above the
-settings were that the LC_ALL was "En_US" and the LANG had no value.
-This error means that Perl detected that you and/or your operating
-system supplier and/or system administrator have set up the so-called
-locale system but Perl could not use those settings. This was not
-dead serious, fortunately: there is a "default locale" called "C" that
-Perl can and will use, and the script will be run. Before you really
-fix the problem, however, you will get the same error message each
-time you run Perl. How to really fix the problem can be found in
-L<perllocale> section B<LOCALE PROBLEMS>.
-
-=item pid %x not a child
-
-(W exec) A warning peculiar to VMS. Waitpid() was asked to wait for a
-process which isn't a subprocess of the current process. While this is
-fine from VMS' perspective, it's probably not what you intended.
-
-=item 'P' must have an explicit size in unpack
-
-(F) The unpack format P must have an explicit size, not "*".
-
-=item POSIX class [:%s:] unknown in regex; marked by <-- HERE in m/%s/
-
-(F) The class in the character class [: :] syntax is unknown. The <-- HERE
-shows in the regular expression about where the problem was discovered.
-Note that the POSIX character classes do B<not> have the C<is> prefix
-the corresponding C interfaces have: in other words, it's C<[[:print:]]>,
-not C<isprint>. See L<perlre>.
-
-=item POSIX getpgrp can't take an argument
-
-(F) Your system has POSIX getpgrp(), which takes no argument, unlike
-the BSD version, which takes a pid.
-
-=item POSIX syntax [%s] belongs inside character classes in regex; marked by <-- HERE in m/%s/
-
-(W regexp) The character class constructs [: :], [= =], and [. .] go
-I<inside> character classes, the [] are part of the construct, for example:
-/[012[:alpha:]345]/. Note that [= =] and [. .] are not currently
-implemented; they are simply placeholders for future extensions and will
-cause fatal errors. The <-- HERE shows in the regular expression about
-where the problem was discovered. See L<perlre>.
-
-=item POSIX syntax [. .] is reserved for future extensions in regex; marked by <-- HERE in m/%s/
-
-(F regexp) Within regular expression character classes ([]) the syntax
-beginning with "[." and ending with ".]" is reserved for future extensions.
-If you need to represent those character sequences inside a regular
-expression character class, just quote the square brackets with the
-backslash: "\[." and ".\]". The <-- HERE shows in the regular expression
-about where the problem was discovered. See L<perlre>.
-
-=item POSIX syntax [= =] is reserved for future extensions in regex; marked by <-- HERE in m/%s/
-
-(F) Within regular expression character classes ([]) the syntax beginning
-with "[=" and ending with "=]" is reserved for future extensions. If you
-need to represent those character sequences inside a regular expression
-character class, just quote the square brackets with the backslash: "\[="
-and "=\]". The <-- HERE shows in the regular expression about where the
-problem was discovered. See L<perlre>.
-
-=item Possible attempt to put comments in qw() list
-
-(W qw) qw() lists contain items separated by whitespace; as with literal
-strings, comment characters are not ignored, but are instead treated as
-literal data. (You may have used different delimiters than the
-parentheses shown here; braces are also frequently used.)
-
-You probably wrote something like this:
-
- @list = qw(
- a # a comment
- b # another comment
- );
-
-when you should have written this:
-
- @list = qw(
- a
- b
- );
-
-If you really want comments, build your list the
-old-fashioned way, with quotes and commas:
-
- @list = (
- 'a', # a comment
- 'b', # another comment
- );
-
-=item Possible attempt to separate words with commas
-
-(W qw) qw() lists contain items separated by whitespace; therefore
-commas aren't needed to separate the items. (You may have used
-different delimiters than the parentheses shown here; braces are also
-frequently used.)
-
-You probably wrote something like this:
-
- qw! a, b, c !;
-
-which puts literal commas into some of the list items. Write it without
-commas if you don't want them to appear in your data:
-
- qw! a b c !;
-
-=item Possible memory corruption: %s overflowed 3rd argument
-
-(F) An ioctl() or fcntl() returned more than Perl was bargaining for.
-Perl guesses a reasonable buffer size, but puts a sentinel byte at the
-end of the buffer just in case. This sentinel byte got clobbered, and
-Perl assumes that memory is now corrupted. See L<perlfunc/ioctl>.
-
-=item Possible precedence problem on bitwise %c operator
-
-(W precedence) Your program uses a bitwise logical operator in conjunction
-with a numeric comparison operator, like this :
-
- if ($x & $y == 0) { ... }
-
-This expression is actually equivalent to C<$x & ($y == 0)>, due to the
-higher precedence of C<==>. This is probably not what you want. (If you
-really meant to write this, disable the warning, or, better, put the
-parentheses explicitly and write C<$x & ($y == 0)>).
-
-=item Possible unintended interpolation of $\ in regex
-
-(W ambiguous) You said something like C<m/$\/> in a regex.
-The regex C<m/foo$\s+bar/m> translates to: match the word 'foo', the output
-record separator (see L<perlvar/$\>) and the letter 's' (one time or more)
-followed by the word 'bar'.
-
-If this is what you intended then you can silence the warning by using
-C<m/${\}/> (for example: C<m/foo${\}s+bar/>).
-
-If instead you intended to match the word 'foo' at the end of the line
-followed by whitespace and the word 'bar' on the next line then you can use
-C<m/$(?)\/> (for example: C<m/foo$(?)\s+bar/>).
-
-=item Possible unintended interpolation of %s in string
-
-(W ambiguous) You said something like '@foo' in a double-quoted string
-but there was no array C<@foo> in scope at the time. If you wanted a
-literal @foo, then write it as \@foo; otherwise find out what happened
-to the array you apparently lost track of.
-
-=item Precedence problem: open %s should be open(%s)
-
-(S precedence) The old irregular construct
-
- open FOO || die;
-
-is now misinterpreted as
-
- open(FOO || die);
-
-because of the strict regularization of Perl 5's grammar into unary and
-list operators. (The old open was a little of both.) You must put
-parentheses around the filehandle, or use the new "or" operator instead
-of "||".
-
-=item Premature end of script headers
-
-See Server error.
-
-=item printf() on closed filehandle %s
-
-(W closed) The filehandle you're writing to got itself closed sometime
-before now. Check your control flow.
-
-=item print() on closed filehandle %s
-
-(W closed) The filehandle you're printing on got itself closed sometime
-before now. Check your control flow.
-
-=item Process terminated by SIG%s
-
-(W) This is a standard message issued by OS/2 applications, while *nix
-applications die in silence. It is considered a feature of the OS/2
-port. One can easily disable this by appropriate sighandlers, see
-L<perlipc/"Signals">. See also "Process terminated by SIGTERM/SIGINT"
-in L<perlos2>.
-
-=item Prototype after '%c' for %s : %s
-
-(W illegalproto) A character follows % or @ in a prototype. This is
-useless, since % and @ gobble the rest of the subroutine arguments.
-
-=item Prototype mismatch: %s vs %s
-
-(S prototype) The subroutine being declared or defined had previously been
-declared or defined with a different function prototype.
-
-=item Prototype not terminated
-
-(F) You've omitted the closing parenthesis in a function prototype
-definition.
-
-=item \p{} uses Unicode rules, not locale rules
-
-(W) You compiled a regular expression that contained a Unicode property
-match (C<\p> or C<\P>), but the regular expression is also being told to
-use the run-time locale, not Unicode. Instead, use a POSIX character
-class, which should know about the locale's rules.
-(See L<perlrecharclass/POSIX Character Classes>.)
-
-Even if the run-time locale is ISO 8859-1 (Latin1), which is a subset of
-Unicode, some properties will give results that are not valid for that
-subset.
-
-Here are a couple of examples to help you see what's going on. If the
-locale is ISO 8859-7, the character at code point 0xD7 is the "GREEK
-CAPITAL LETTER CHI". But in Unicode that code point means the
-"MULTIPLICATION SIGN" instead, and C<\p> always uses the Unicode
-meaning. That means that C<\p{Alpha}> won't match, but C<[[:alpha:]]>
-should. Only in the Latin1 locale are all the characters in the same
-positions as they are in Unicode. But, even here, some properties give
-incorrect results. An example is C<\p{Changes_When_Uppercased}> which
-is true for "LATIN SMALL LETTER Y WITH DIAERESIS", but since the upper
-case of that character is not in Latin1, in that locale it doesn't
-change when upper cased.
-
-=item Quantifier follows nothing in regex; marked by <-- HERE in m/%s/
-
-(F) You started a regular expression with a quantifier. Backslash it if
-you meant it literally. The <-- HERE shows in the regular expression
-about where the problem was discovered. See L<perlre>.
-
-=item Quantifier in {,} bigger than %d in regex; marked by <-- HERE in m/%s/
-
-(F) There is currently a limit to the size of the min and max values of
-the {min,max} construct. The <-- HERE shows in the regular expression
-about where the problem was discovered. See L<perlre>.
-
-=item Quantifier unexpected on zero-length expression; marked by <-- HERE in m/%s/
-
-(W regexp) You applied a regular expression quantifier in a place where
-it makes no sense, such as on a zero-width assertion. Try putting the
-quantifier inside the assertion instead. For example, the way to match
-"abc" provided that it is followed by three repetitions of "xyz" is
-C</abc(?=(?:xyz){3})/>, not C</abc(?=xyz){3}/>.
-
-The <-- HERE shows in the regular expression about where the problem was
-discovered.
-
-=item Range iterator outside integer range
-
-(F) One (or both) of the numeric arguments to the range operator ".."
-are outside the range which can be represented by integers internally.
-One possible workaround is to force Perl to use magical string increment
-by prepending "0" to your numbers.
-
-=item readdir() attempted on invalid dirhandle %s
-
-(W io) The dirhandle you're reading from is either closed or not really
-a dirhandle. Check your control flow.
-
-=item readline() on closed filehandle %s
-
-(W closed) The filehandle you're reading from got itself closed sometime
-before now. Check your control flow.
-
-=item read() on closed filehandle %s
-
-(W closed) You tried to read from a closed filehandle.
-
-=item read() on unopened filehandle %s
-
-(W unopened) You tried to read from a filehandle that was never opened.
-
-=item Reallocation too large: %x
-
-(F) You can't allocate more than 64K on an MS-DOS machine.
-
-=item realloc() of freed memory ignored
-
-(S malloc) An internal routine called realloc() on something that had
-already been freed.
-
-=item Recompile perl with B<-D>DEBUGGING to use B<-D> switch
-
-(F debugging) You can't use the B<-D> option unless the code to produce
-the desired output is compiled into Perl, which entails some overhead,
-which is why it's currently left out of your copy.
-
-=item Recursive call to Perl_load_module in PerlIO_find_layer
-
-(P) It is currently not permitted to load modules when creating
-a filehandle inside an %INC hook. This can happen with C<open my
-$fh, '<', \$scalar>, which implicitly loads PerlIO::scalar. Try
-loading PerlIO::scalar explicitly first.
-
-=item Recursive inheritance detected in package '%s'
-
-(F) While calculating the method resolution order (MRO) of a package, Perl
-believes it found an infinite loop in the C<@ISA> hierarchy. This is a
-crude check that bails out after 100 levels of C<@ISA> depth.
-
-=item refcnt_dec: fd %d%s
-
-=item refcnt: fd %d%s
-
-=item refcnt_inc: fd %d%s
-
-(P) Perl's I/O implementation failed an internal consistency check. If
-you see this message, something is very wrong.
-
-=item Reference found where even-sized list expected
-
-(W misc) You gave a single reference where Perl was expecting a list
-with an even number of elements (for assignment to a hash). This
-usually means that you used the anon hash constructor when you meant
-to use parens. In any case, a hash requires key/value B<pairs>.
-
- %hash = { one => 1, two => 2, }; # WRONG
- %hash = [ qw/ an anon array / ]; # WRONG
- %hash = ( one => 1, two => 2, ); # right
- %hash = qw( one 1 two 2 ); # also fine
-
-=item Reference is already weak
-
-(W misc) You have attempted to weaken a reference that is already weak.
-Doing so has no effect.
-
-=item Reference to invalid group 0
-
-(F) You used C<\g0> or similar in a regular expression. You may refer
-to capturing parentheses only with strictly positive integers
-(normal backreferences) or with strictly negative integers (relative
-backreferences). Using 0 does not make sense.
-
-=item Reference to nonexistent group in regex; marked by <-- HERE in m/%s/
-
-(F) You used something like C<\7> in your regular expression, but there are
-not at least seven sets of capturing parentheses in the expression. If
-you wanted to have the character with ordinal 7 inserted into the regular
-expression, prepend zeroes to make it three digits long: C<\007>
-
-The <-- HERE shows in the regular expression about where the problem was
-discovered.
-
-=item Reference to nonexistent named group in regex; marked by <-- HERE in m/%s/
-
-(F) You used something like C<\k'NAME'> or C<< \k<NAME> >> in your regular
-expression, but there is no corresponding named capturing parentheses
-such as C<(?'NAME'...)> or C<< (?<NAME>...) >>. Check if the name has been
-spelled correctly both in the backreference and the declaration.
-
-The <-- HERE shows in the regular expression about where the problem was
-discovered.
-
-=item Reference to nonexistent or unclosed group in regex; marked by <-- HERE in m/%s/
-
-(F) You used something like C<\g{-7}> in your regular expression, but there
-are not at least seven sets of closed capturing parentheses in the
-expression before where the C<\g{-7}> was located.
-
-The <-- HERE shows in the regular expression about where the problem was
-discovered.
-
-=item regexp memory corruption
-
-(P) The regular expression engine got confused by what the regular
-expression compiler gave it.
-
-=item Regexp modifier "/%c" may appear a maximum of twice
-
-=item Regexp modifier "/%c" may not appear twice
-
-(F syntax, regexp) The regular expression pattern had too many occurrences
-of the specified modifier. Remove the extraneous ones.
-
-=item Regexp modifier "%c" may not appear after the "-"
-
-(F regexp) Turning off the given modifier has the side effect of turning
-on another one. Perl currently doesn't allow this. Reword the regular
-expression to use the modifier you want to turn on (and place it before
-the minus), instead of the one you want to turn off.
-
-=item Regexp modifiers "/%c" and "/%c" are mutually exclusive
-
-(F syntax, regexp) The regular expression pattern had more than one of these
-mutually exclusive modifiers. Retain only the modifier that is
-supposed to be there.
-
-=item Regexp out of space
-
-(P) A "can't happen" error, because safemalloc() should have caught it
-earlier.
-
-=item Repeated format line will never terminate (~~ and @# incompatible)
-
-(F) Your format contains the ~~ repeat-until-blank sequence and a
-numeric field that will never go blank so that the repetition never
-terminates. You might use ^# instead. See L<perlform>.
-
-=item Replacement list is longer than search list
-
-(W misc) You have used a replacement list that is longer than the
-search list. So the additional elements in the replacement list
-are meaningless.
-
-=item Reversed %s= operator
-
-(W syntax) You wrote your assignment operator backwards. The = must
-always come last, to avoid ambiguity with subsequent unary operators.
-
-=item rewinddir() attempted on invalid dirhandle %s
-
-(W io) The dirhandle you tried to do a rewinddir() on is either closed or not
-really a dirhandle. Check your control flow.
-
-=item Scalars leaked: %d
-
-(P) Something went wrong in Perl's internal bookkeeping of scalars:
-not all scalar variables were deallocated by the time Perl exited.
-What this usually indicates is a memory leak, which is of course bad,
-especially if the Perl program is intended to be long-running.
-
-=item Scalar value @%s[%s] better written as $%s[%s]
-
-(W syntax) You've used an array slice (indicated by @) to select a
-single element of an array. Generally it's better to ask for a scalar
-value (indicated by $). The difference is that C<$foo[&bar]> always
-behaves like a scalar, both when assigning to it and when evaluating its
-argument, while C<@foo[&bar]> behaves like a list when you assign to it,
-and provides a list context to its subscript, which can do weird things
-if you're expecting only one subscript.
-
-On the other hand, if you were actually hoping to treat the array
-element as a list, you need to look into how references work, because
-Perl will not magically convert between scalars and lists for you. See
-L<perlref>.
-
-=item Scalar value @%s{%s} better written as $%s{%s}
-
-(W syntax) You've used a hash slice (indicated by @) to select a single
-element of a hash. Generally it's better to ask for a scalar value
-(indicated by $). The difference is that C<$foo{&bar}> always behaves
-like a scalar, both when assigning to it and when evaluating its
-argument, while C<@foo{&bar}> behaves like a list when you assign to it,
-and provides a list context to its subscript, which can do weird things
-if you're expecting only one subscript.
-
-On the other hand, if you were actually hoping to treat the hash element
-as a list, you need to look into how references work, because Perl will
-not magically convert between scalars and lists for you. See
-L<perlref>.
-
-=item Search pattern not terminated
-
-(F) The lexer couldn't find the final delimiter of a // or m{}
-construct. Remember that bracketing delimiters count nesting level.
-Missing the leading C<$> from a variable C<$m> may cause this error.
-
-Note that since Perl 5.9.0 a // can also be the I<defined-or>
-construct, not just the empty search pattern. Therefore code written
-in Perl 5.9.0 or later that uses the // as the I<defined-or> can be
-misparsed by pre-5.9.0 Perls as a non-terminated search pattern.
-
-=item Search pattern not terminated or ternary operator parsed as search pattern
-
-(F) The lexer couldn't find the final delimiter of a C<?PATTERN?>
-construct.
-
-The question mark is also used as part of the ternary operator (as in
-C<foo ? 0 : 1>) leading to some ambiguous constructions being wrongly
-parsed. One way to disambiguate the parsing is to put parentheses around
-the conditional expression, i.e. C<(foo) ? 0 : 1>.
-
-=item seekdir() attempted on invalid dirhandle %s
-
-(W io) The dirhandle you are doing a seekdir() on is either closed or not
-really a dirhandle. Check your control flow.
-
-=item %sseek() on unopened filehandle
-
-(W unopened) You tried to use the seek() or sysseek() function on a
-filehandle that was either never opened or has since been closed.
-
-=item select not implemented
-
-(F) This machine doesn't implement the select() system call.
-
-=item Self-ties of arrays and hashes are not supported
-
-(F) Self-ties are of arrays and hashes are not supported in
-the current implementation.
-
-=item Semicolon seems to be missing
-
-(W semicolon) A nearby syntax error was probably caused by a missing
-semicolon, or possibly some other missing operator, such as a comma.
-
-=item semi-panic: attempt to dup freed string
-
-(S internal) The internal newSVsv() routine was called to duplicate a
-scalar that had previously been marked as free.
-
-=item sem%s not implemented
-
-(F) You don't have System V semaphore IPC on your system.
-
-=item send() on closed socket %s
-
-(W closed) The socket you're sending to got itself closed sometime
-before now. Check your control flow.
-
-=item Sequence (? incomplete in regex; marked by <-- HERE in m/%s/
-
-(F) A regular expression ended with an incomplete extension (?. The
-<-- HERE shows in the regular expression about where the problem was
-discovered. See L<perlre>.
-
-=item Sequence (?%s...) not implemented in regex; marked by <-- HERE in m/%s/
-
-(F) A proposed regular expression extension has the character reserved
-but has not yet been written. The <-- HERE shows in the regular
-expression about where the problem was discovered. See L<perlre>.
-
-=item Sequence (?%s...) not recognized in regex; marked by <-- HERE in m/%s/
-
-(F) You used a regular expression extension that doesn't make sense. The
-<-- HERE shows in the regular expression about where the problem was
-discovered. This happens when using the C<(?^...)> construct to tell
-Perl to use the default regular expression modifiers, and you
-redundantly specify a default modifier. For other
-causes, see L<perlre>.
-
-=item Sequence \%s... not terminated in regex; marked by <-- HERE in m/%s/
-
-(F) The regular expression expects a mandatory argument following the escape
-sequence and this has been omitted or incorrectly written.
-
-=item Sequence (?#... not terminated in regex; marked by <-- HERE in m/%s/
-
-(F) A regular expression comment must be terminated by a closing
-parenthesis. Embedded parentheses aren't allowed. The <-- HERE shows in
-the regular expression about where the problem was discovered. See
-L<perlre>.
-
-=item Sequence (?{...}) not terminated or not {}-balanced in regex; marked by <-- HERE in m/%s/
-
-(F) If the contents of a (?{...}) clause contain braces, they
-must balance for Perl to detect the end of the clause properly.
-The <-- HERE shows in the regular expression about where the
-problem was discovered. See L<perlre>.
-
-=item Z<>500 Server error
-
-See Server error.
-
-=item Server error
-
-(A) This is the error message generally seen in a browser window
-when trying to run a CGI program (including SSI) over the web. The
-actual error text varies widely from server to server. The most
-frequently-seen variants are "500 Server error", "Method (something)
-not permitted", "Document contains no data", "Premature end of script
-headers", and "Did not produce a valid header".
-
-B<This is a CGI error, not a Perl error>.
-
-You need to make sure your script is executable, is accessible by
-the user CGI is running the script under (which is probably not the
-user account you tested it under), does not rely on any environment
-variables (like PATH) from the user it isn't running under, and isn't
-in a location where the CGI server can't find it, basically, more or
-less. Please see the following for more information:
-
- http://www.perl.org/CGI_MetaFAQ.html
- http://www.htmlhelp.org/faq/cgifaq.html
- http://www.w3.org/Security/Faq/
-
-You should also look at L<perlfaq9>.
-
-=item setegid() not implemented
-
-(F) You tried to assign to C<$)>, and your operating system doesn't
-support the setegid() system call (or equivalent), or at least Configure
-didn't think so.
-
-=item seteuid() not implemented
-
-(F) You tried to assign to C<< $> >>, and your operating system doesn't
-support the seteuid() system call (or equivalent), or at least Configure
-didn't think so.
-
-=item setpgrp can't take arguments
-
-(F) Your system has the setpgrp() from BSD 4.2, which takes no
-arguments, unlike POSIX setpgid(), which takes a process ID and process
-group ID.
-
-=item setrgid() not implemented
-
-(F) You tried to assign to C<$(>, and your operating system doesn't
-support the setrgid() system call (or equivalent), or at least Configure
-didn't think so.
-
-=item setruid() not implemented
-
-(F) You tried to assign to C<$<>, and your operating system doesn't
-support the setruid() system call (or equivalent), or at least Configure
-didn't think so.
-
-=item setsockopt() on closed socket %s
-
-(W closed) You tried to set a socket option on a closed socket. Did you
-forget to check the return value of your socket() call? See
-L<perlfunc/setsockopt>.
-
-=item shm%s not implemented
-
-(F) You don't have System V shared memory IPC on your system.
-
-=item !=~ should be !~
-
-(W syntax) The non-matching operator is !~, not !=~. !=~ will be
-interpreted as the != (numeric not equal) and ~ (1's complement)
-operators: probably not what you intended.
-
-=item <> should be quotes
-
-(F) You wrote C<< require <file> >> when you should have written
-C<require 'file'>.
-
-=item /%s/ should probably be written as "%s"
-
-(W syntax) You have used a pattern where Perl expected to find a string,
-as in the first argument to C<join>. Perl will treat the true or false
-result of matching the pattern against $_ as the string, which is
-probably not what you had in mind.
-
-=item shutdown() on closed socket %s
-
-(W closed) You tried to do a shutdown on a closed socket. Seems a bit
-superfluous.
-
-=item SIG%s handler "%s" not defined
-
-(W signal) The signal handler named in %SIG doesn't, in fact, exist.
-Perhaps you put it into the wrong package?
-
-=item Smart matching a non-overloaded object breaks encapsulation
-
-(F) You should not use the C<~~> operator on an object that does not
-overload it: Perl refuses to use the object's underlying structure for
-the smart match.
-
-=item sort is now a reserved word
-
-(F) An ancient error message that almost nobody ever runs into anymore.
-But before sort was a keyword, people sometimes used it as a filehandle.
-
-=item Sort subroutine didn't return single value
-
-(F) A sort comparison subroutine may not return a list value with more
-or less than one element. See L<perlfunc/sort>.
-
-=item Source filters apply only to byte streams
-
-(F) You tried to activate a source filter (usually by loading a
-source filter module) within a string passed to C<eval>. This is
-not permitted under the C<unicode_eval> feature. Consider using
-C<evalbytes> instead. See L<feature>.
-
-=item splice() offset past end of array
-
-(W misc) You attempted to specify an offset that was past the end of
-the array passed to splice(). Splicing will instead commence at the
-end of the array, rather than past it. If this isn't what you want,
-try explicitly pre-extending the array by assigning $#array = $offset.
-See L<perlfunc/splice>.
-
-=item Split loop
-
-(P) The split was looping infinitely. (Obviously, a split shouldn't
-iterate more times than there are characters of input, which is what
-happened.) See L<perlfunc/split>.
-
-=item Statement unlikely to be reached
-
-(W exec) You did an exec() with some statement after it other than a
-die(). This is almost always an error, because exec() never returns
-unless there was a failure. You probably wanted to use system()
-instead, which does return. To suppress this warning, put the exec() in
-a block by itself.
-
-=item "state" variable %s can't be in a package
-
-(F) Lexically scoped variables aren't in a package, so it doesn't make
-sense to try to declare one with a package qualifier on the front. Use
-local() if you want to localize a package variable.
-
-=item stat() on unopened filehandle %s
-
-(W unopened) You tried to use the stat() function on a filehandle that
-was either never opened or has since been closed.
-
-=item Stub found while resolving method "%s" overloading "%s" in package "%s"
-
-(P) Overloading resolution over @ISA tree may be broken by importation
-stubs. Stubs should never be implicitly created, but explicit calls to
-C<can> may break this.
-
-=item Subroutine %s redefined
-
-(W redefine) You redefined a subroutine. To suppress this warning, say
-
- {
- no warnings 'redefine';
- eval "sub name { ... }";
- }
-
-=item Substitution loop
-
-(P) The substitution was looping infinitely. (Obviously, a substitution
-shouldn't iterate more times than there are characters of input, which
-is what happened.) See the discussion of substitution in
-L<perlop/"Regexp Quote-Like Operators">.
-
-=item Substitution pattern not terminated
-
-(F) The lexer couldn't find the interior delimiter of an s/// or s{}{}
-construct. Remember that bracketing delimiters count nesting level.
-Missing the leading C<$> from variable C<$s> may cause this error.
-
-=item Substitution replacement not terminated
-
-(F) The lexer couldn't find the final delimiter of an s/// or s{}{}
-construct. Remember that bracketing delimiters count nesting level.
-Missing the leading C<$> from variable C<$s> may cause this error.
-
-=item substr outside of string
-
-(W substr)(F) You tried to reference a substr() that pointed outside of
-a string. That is, the absolute value of the offset was larger than the
-length of the string. See L<perlfunc/substr>. This warning is fatal if
-substr is used in an lvalue context (as the left hand side of an
-assignment or as a subroutine argument for example).
-
-=item sv_upgrade from type %d down to type %d
-
-(P) Perl tried to force the upgrade of an SV to a type which was actually
-inferior to its current type.
-
-=item Switch (?(condition)... contains too many branches in regex; marked by <-- HERE in m/%s/
-
-(F) A (?(condition)if-clause|else-clause) construct can have at most
-two branches (the if-clause and the else-clause). If you want one or
-both to contain alternation, such as using C<this|that|other>, enclose
-it in clustering parentheses:
-
- (?(condition)(?:this|that|other)|else-clause)
-
-The <-- HERE shows in the regular expression about where the problem
-was discovered. See L<perlre>.
-
-=item Switch condition not recognized in regex; marked by <-- HERE in m/%s/
-
-(F) If the argument to the (?(...)if-clause|else-clause) construct is
-a number, it can be only a number. The <-- HERE shows in the regular
-expression about where the problem was discovered. See L<perlre>.
-
-=item switching effective %s is not implemented
-
-(F) While under the C<use filetest> pragma, we cannot switch the real
-and effective uids or gids.
-
-=item %s syntax OK
-
-(F) The final summary message when a C<perl -c> succeeds.
-
-=item syntax error
-
-(F) Probably means you had a syntax error. Common reasons include:
-
- A keyword is misspelled.
- A semicolon is missing.
- A comma is missing.
- An opening or closing parenthesis is missing.
- An opening or closing brace is missing.
- A closing quote is missing.
-
-Often there will be another error message associated with the syntax
-error giving more information. (Sometimes it helps to turn on B<-w>.)
-The error message itself often tells you where it was in the line when
-it decided to give up. Sometimes the actual error is several tokens
-before this, because Perl is good at understanding random input.
-Occasionally the line number may be misleading, and once in a blue moon
-the only way to figure out what's triggering the error is to call
-C<perl -c> repeatedly, chopping away half the program each time to see
-if the error went away. Sort of the cybernetic version of S<20 questions>.
-
-=item syntax error at line %d: '%s' unexpected
-
-(A) You've accidentally run your script through the Bourne shell instead
-of Perl. Check the #! line, or manually feed your script into Perl
-yourself.
-
-=item syntax error in file %s at line %d, next 2 tokens "%s"
-
-(F) This error is likely to occur if you run a perl5 script through
-a perl4 interpreter, especially if the next 2 tokens are "use strict"
-or "my $var" or "our $var".
-
-=item sysread() on closed filehandle %s
-
-(W closed) You tried to read from a closed filehandle.
-
-=item sysread() on unopened filehandle %s
-
-(W unopened) You tried to read from a filehandle that was never opened.
-
-=item System V %s is not implemented on this machine
-
-(F) You tried to do something with a function beginning with "sem",
-"shm", or "msg" but that System V IPC is not implemented in your
-machine. In some machines the functionality can exist but be
-unconfigured. Consult your system support.
-
-=item syswrite() on closed filehandle %s
-
-(W closed) The filehandle you're writing to got itself closed sometime
-before now. Check your control flow.
-
-=item C<-T> and C<-B> not implemented on filehandles
-
-(F) Perl can't peek at the stdio buffer of filehandles when it doesn't
-know about your kind of stdio. You'll have to use a filename instead.
-
-=item Target of goto is too deeply nested
-
-(F) You tried to use C<goto> to reach a label that was too deeply nested
-for Perl to reach. Perl is doing you a favor by refusing.
-
-=item telldir() attempted on invalid dirhandle %s
-
-(W io) The dirhandle you tried to telldir() is either closed or not really
-a dirhandle. Check your control flow.
-
-=item tell() on unopened filehandle
-
-(W unopened) You tried to use the tell() function on a filehandle that
-was either never opened or has since been closed.
-
-=item That use of $[ is unsupported
-
-(F) Assignment to C<$[> is now strictly circumscribed, and interpreted
-as a compiler directive. You may say only one of
-
- $[ = 0;
- $[ = 1;
- ...
- local $[ = 0;
- local $[ = 1;
- ...
-
-This is to prevent the problem of one module changing the array base out
-from under another module inadvertently. See L<perlvar/$[> and L<arybase>.
-
-=item The crypt() function is unimplemented due to excessive paranoia
-
-(F) Configure couldn't find the crypt() function on your machine,
-probably because your vendor didn't supply it, probably because they
-think the U.S. Government thinks it's a secret, or at least that they
-will continue to pretend that it is. And if you quote me on that, I
-will deny it.
-
-=item The %s function is unimplemented
-
-(F) The function indicated isn't implemented on this architecture, according
-to the probings of Configure.
-
-=item The stat preceding %s wasn't an lstat
-
-(F) It makes no sense to test the current stat buffer for symbolic
-linkhood if the last stat that wrote to the stat buffer already went
-past the symlink to get to the real file. Use an actual filename
-instead.
-
-=item The 'unique' attribute may only be applied to 'our' variables
-
-(F) This attribute was never supported on C<my> or C<sub> declarations.
-
-=item This Perl can't reset CRTL environ elements (%s)
-
-=item This Perl can't set CRTL environ elements (%s=%s)
-
-(W internal) Warnings peculiar to VMS. You tried to change or delete an
-element of the CRTL's internal environ array, but your copy of Perl
-wasn't built with a CRTL that contained the setenv() function. You'll
-need to rebuild Perl with a CRTL that does, or redefine
-F<PERL_ENV_TABLES> (see L<perlvms>) so that the environ array isn't the
-target of the change to
-%ENV which produced the warning.
-
-=item thread failed to start: %s
-
-(W threads)(S) The entry point function of threads->create() failed for some reason.
-
-=item times not implemented
-
-(F) Your version of the C library apparently doesn't do times(). I
-suspect you're not running on Unix.
-
-=item "-T" is on the #! line, it must also be used on the command line
-
-(X) The #! line (or local equivalent) in a Perl script contains
-the B<-T> option (or the B<-t> option), but Perl was not invoked with
-B<-T> in its command line. This is an error because, by the time
-Perl discovers a B<-T> in a script, it's too late to properly taint
-everything from the environment. So Perl gives up.
-
-If the Perl script is being executed as a command using the #!
-mechanism (or its local equivalent), this error can usually be
-fixed by editing the #! line so that the B<-%c> option is a part of
-Perl's first argument: e.g. change C<perl -n -%c> to C<perl -%c -n>.
-
-If the Perl script is being executed as C<perl scriptname>, then the
-B<-%c> option must appear on the command line: C<perl -%c scriptname>.
-
-=item To%s: illegal mapping '%s'
-
-(F) You tried to define a customized To-mapping for lc(), lcfirst,
-uc(), or ucfirst() (or their string-inlined versions), but you
-specified an illegal mapping.
-See L<perlunicode/"User-Defined Character Properties">.
-
-=item Too deeply nested ()-groups
-
-(F) Your template contains ()-groups with a ridiculously deep nesting level.
-
-=item Too few args to syscall
-
-(F) There has to be at least one argument to syscall() to specify the
-system call to call, silly dilly.
-
-=item Too late for "-%s" option
-
-(X) The #! line (or local equivalent) in a Perl script contains the
-B<-M>, B<-m> or B<-C> option.
-
-In the case of B<-M> and B<-m>, this is an error because those options
-are not intended for use inside scripts. Use the C<use> pragma instead.
-
-The B<-C> option only works if it is specified on the command line as
-well (with the same sequence of letters or numbers following). Either
-specify this option on the command line, or, if your system supports
-it, make your script executable and run it directly instead of passing
-it to perl.
-
-=item Too late to run %s block
-
-(W void) A CHECK or INIT block is being defined during run time proper,
-when the opportunity to run them has already passed. Perhaps you are
-loading a file with C<require> or C<do> when you should be using C<use>
-instead. Or perhaps you should put the C<require> or C<do> inside a
-BEGIN block.
-
-=item Too many args to syscall
-
-(F) Perl supports a maximum of only 14 args to syscall().
-
-=item Too many arguments for %s
-
-(F) The function requires fewer arguments than you specified.
-
-=item Too many )'s
-
-(A) You've accidentally run your script through B<csh> instead of Perl.
-Check the #! line, or manually feed your script into Perl yourself.
-
-=item Too many ('s
-
-(A) You've accidentally run your script through B<csh> instead of Perl.
-Check the #! line, or manually feed your script into Perl yourself.
-
-=item Trailing \ in regex m/%s/
-
-(F) The regular expression ends with an unbackslashed backslash.
-Backslash it. See L<perlre>.
-
-=item Transliteration pattern not terminated
-
-(F) The lexer couldn't find the interior delimiter of a tr/// or tr[][]
-or y/// or y[][] construct. Missing the leading C<$> from variables
-C<$tr> or C<$y> may cause this error.
-
-=item Transliteration replacement not terminated
-
-(F) The lexer couldn't find the final delimiter of a tr///, tr[][],
-y/// or y[][] construct.
-
-=item '%s' trapped by operation mask
-
-(F) You tried to use an operator from a Safe compartment in which it's
-disallowed. See L<Safe>.
-
-=item truncate not implemented
-
-(F) Your machine doesn't implement a file truncation mechanism that
-Configure knows about.
-
-=item Type of arg %d to &CORE::%s must be %s
-
-(F) The subroutine in question in the CORE package requires its argument
-to be a hard reference to data of the specified type. Overloading is
-ignored, so a reference to an object that is not the specified type, but
-nonetheless has overloading to handle it, will still not be accepted.
-
-=item Type of arg %d to %s must be %s (not %s)
-
-(F) This function requires the argument in that position to be of a
-certain type. Arrays must be @NAME or C<@{EXPR}>. Hashes must be
-%NAME or C<%{EXPR}>. No implicit dereferencing is allowed--use the
-{EXPR} forms as an explicit dereference. See L<perlref>.
-
-=item Type of argument to %s must be unblessed hashref or arrayref
-
-(F) You called C<keys>, C<values> or C<each> with a scalar argument that
-was not a reference to an unblessed hash or array.
-
-=item umask not implemented
-
-(F) Your machine doesn't implement the umask function and you tried to
-use it to restrict permissions for yourself (EXPR & 0700).
-
-=item Unable to create sub named "%s"
-
-(F) You attempted to create or access a subroutine with an illegal name.
-
-=item Unbalanced context: %d more PUSHes than POPs
-
-(W internal) The exit code detected an internal inconsistency in how
-many execution contexts were entered and left.
-
-=item Unbalanced saves: %d more saves than restores
-
-(W internal) The exit code detected an internal inconsistency in how
-many values were temporarily localized.
-
-=item Unbalanced scopes: %d more ENTERs than LEAVEs
-
-(W internal) The exit code detected an internal inconsistency in how
-many blocks were entered and left.
-
-=item Unbalanced string table refcount: (%d) for "%s"
-
-(W internal) On exit, Perl found some strings remaining in the shared
-string table used for copy on write and for hash keys. The entries
-should have been freed, so this indicates a bug somewhere.
-
-=item Unbalanced tmps: %d more allocs than frees
-
-(W internal) The exit code detected an internal inconsistency in how
-many mortal scalars were allocated and freed.
-
-=item Undefined format "%s" called
-
-(F) The format indicated doesn't seem to exist. Perhaps it's really in
-another package? See L<perlform>.
-
-=item Undefined sort subroutine "%s" called
-
-(F) The sort comparison routine specified doesn't seem to exist.
-Perhaps it's in a different package? See L<perlfunc/sort>.
-
-=item Undefined subroutine &%s called
-
-(F) The subroutine indicated hasn't been defined, or if it was, it has
-since been undefined.
-
-=item Undefined subroutine called
-
-(F) The anonymous subroutine you're trying to call hasn't been defined,
-or if it was, it has since been undefined.
-
-=item Undefined subroutine in sort
-
-(F) The sort comparison routine specified is declared but doesn't seem
-to have been defined yet. See L<perlfunc/sort>.
-
-=item Undefined top format "%s" called
-
-(F) The format indicated doesn't seem to exist. Perhaps it's really in
-another package? See L<perlform>.
-
-=item Undefined value assigned to typeglob
-
-(W misc) An undefined value was assigned to a typeglob, a la
-C<*foo = undef>. This does nothing. It's possible that you really mean
-C<undef *foo>.
-
-=item %s: Undefined variable
-
-(A) You've accidentally run your script through B<csh> instead of Perl.
-Check the #! line, or manually feed your script into Perl yourself.
-
-=item unexec of %s into %s failed!
-
-(F) The unexec() routine failed for some reason. See your local FSF
-representative, who probably put it there in the first place.
-
-=item Unexpected constant lvalue entersub entry via type/targ %d:%d
-
-(P) When compiling a subroutine call in lvalue context, Perl failed an
-internal consistency check. It encountered a malformed op tree.
-
-=item Unicode non-character U+%X is illegal for open interchange
-
-(W utf8, nonchar) Certain codepoints, such as U+FFFE and U+FFFF, are
-defined by the Unicode standard to be non-characters. Those are
-legal codepoints, but are reserved for internal use; so, applications
-shouldn't attempt to exchange them. If you know what you are doing
-you can turn off this warning by C<no warnings 'nonchar';>.
-
-=item Unicode surrogate U+%X is illegal in UTF-8
-
-(W utf8, surrogate) You had a UTF-16 surrogate in a context where they are
-not considered acceptable. These code points, between U+D800 and
-U+DFFF (inclusive), are used by Unicode only for UTF-16. However, Perl
-internally allows all unsigned integer code points (up to the size limit
-available on your platform), including surrogates. But these can cause
-problems when being input or output, which is likely where this message
-came from. If you really really know what you are doing you can turn
-off this warning by C<no warnings 'surrogate';>.
-
-=item Unknown BYTEORDER
-
-(F) There are no byte-swapping functions for a machine with this byte
-order.
-
-=item Unknown error
-
-(P) Perl was about to print an error message in C<$@>, but the C<$@> variable
-did not exist, even after an attempt to create it.
-
-=item Unknown open() mode '%s'
-
-(F) The second argument of 3-argument open() is not among the list
-of valid modes: C<< < >>, C<< > >>, C<<< >> >>>, C<< +< >>,
-C<< +> >>, C<<< +>> >>>, C<-|>, C<|->, C<< <& >>, C<< >& >>.
-
-=item Unknown PerlIO layer "%s"
-
-(W layer) An attempt was made to push an unknown layer onto the Perl I/O
-system. (Layers take care of transforming data between external and
-internal representations.) Note that some layers, such as C<mmap>,
-are not supported in all environments. If your program didn't
-explicitly request the failing operation, it may be the result of the
-value of the environment variable PERLIO.
-
-=item Unknown process %x sent message to prime_env_iter: %s
-
-(P) An error peculiar to VMS. Perl was reading values for %ENV before
-iterating over it, and someone else stuck a message in the stream of
-data Perl expected. Someone's very confused, or perhaps trying to
-subvert Perl's population of %ENV for nefarious purposes.
-
-=item Unknown "re" subpragma '%s' (known ones are: %s)
-
-(W) You tried to use an unknown subpragma of the "re" pragma.
-
-=item Unknown switch condition (?(%s in regex; marked by <-- HERE in m/%s/
-
-(F) The condition part of a (?(condition)if-clause|else-clause) construct
-is not known. The condition must be one of the following:
-
- (1) (2) ... true if 1st, 2nd, etc., capture matched
- (<NAME>) ('NAME') true if named capture matched
- (?=...) (?<=...) true if subpattern matches
- (?!...) (?<!...) true if subpattern fails to match
- (?{ CODE }) true if code returns a true value
- (R) true if evaluating inside recursion
- (R1) (R2) ... true if directly inside capture group 1, 2, etc.
- (R&NAME) true if directly inside named capture
- (DEFINE) always false; for defining named subpatterns
-
-The <-- HERE shows in the regular expression about where the problem was
-discovered. See L<perlre>.
-
-=item Unknown Unicode option letter '%c'
-
-(F) You specified an unknown Unicode option. See L<perlrun> documentation
-of the C<-C> switch for the list of known options.
-
-=item Unknown Unicode option value %x
-
-(F) You specified an unknown Unicode option. See L<perlrun> documentation
-of the C<-C> switch for the list of known options.
-
-=item Unknown verb pattern '%s' in regex; marked by <-- HERE in m/%s/
-
-(F) You either made a typo or have incorrectly put a C<*> quantifier
-after an open brace in your pattern. Check the pattern and review
-L<perlre> for details on legal verb patterns.
-
-=item Unknown warnings category '%s'
-
-(F) An error issued by the C<warnings> pragma. You specified a warnings
-category that is unknown to perl at this point.
-
-Note that if you want to enable a warnings category registered by a
-module (e.g. C<use warnings 'File::Find'>), you must have loaded this
-module first.
-
-=item unmatched [ in regex; marked by <-- HERE in m/%s/
-
-(F) The brackets around a character class must match. If you wish to
-include a closing bracket in a character class, backslash it or put it
-first. The <-- HERE shows in the regular expression about where the
-problem was discovered. See L<perlre>.
-
-=item unmatched ( in regex; marked by <-- HERE in m/%s/
-
-(F) Unbackslashed parentheses must always be balanced in regular
-expressions. If you're a vi user, the % key is valuable for finding
-the matching parenthesis. The <-- HERE shows in the regular expression
-about where the problem was discovered. See L<perlre>.
-
-=item Unmatched right %s bracket
-
-(F) The lexer counted more closing curly or square brackets than opening
-ones, so you're probably missing a matching opening bracket. As a
-general rule, you'll find the missing one (so to speak) near the place
-you were last editing.
-
-=item Unquoted string "%s" may clash with future reserved word
-
-(W reserved) You used a bareword that might someday be claimed as a
-reserved word. It's best to put such a word in quotes, or capitalize it
-somehow, or insert an underbar into it. You might also declare it as a
-subroutine.
-
-=item Unrecognized character %s; marked by <-- HERE after %s near column %d
-
-(F) The Perl parser has no idea what to do with the specified character
-in your Perl script (or eval) near the specified column. Perhaps you tried
-to run a compressed script, a binary program, or a directory as a Perl program.
-
-=item Unrecognized escape \%c in character class passed through in regex; marked by <-- HERE in m/%s/
-
-(W regexp) You used a backslash-character combination which is not
-recognized by Perl inside character classes. The character was
-understood literally, but this may change in a future version of Perl.
-The <-- HERE shows in the regular expression about where the
-escape was discovered.
-
-=item Unrecognized escape \%c passed through
-
-(W misc) You used a backslash-character combination which is not
-recognized by Perl. The character was understood literally, but this may
-change in a future version of Perl.
-
-=item Unrecognized escape \%s passed through in regex; marked by <-- HERE in m/%s/
-
-(W regexp) You used a backslash-character combination which is not
-recognized by Perl. The character(s) were understood literally, but
-this may change in a future version of Perl. The <-- HERE shows in
-the regular expression about where the escape was discovered.
-
-=item Unrecognized signal name "%s"
-
-(F) You specified a signal name to the kill() function that was not
-recognized. Say C<kill -l> in your shell to see the valid signal names
-on your system.
-
-=item Unrecognized switch: -%s (-h will show valid options)
-
-(F) You specified an illegal option to Perl. Don't do that. (If you
-think you didn't do that, check the #! line to see if it's supplying the
-bad switch on your behalf.)
-
-=item Unsuccessful %s on filename containing newline
-
-(W newline) A file operation was attempted on a filename, and that
-operation failed, PROBABLY because the filename contained a newline,
-PROBABLY because you forgot to chomp() it off. See L<perlfunc/chomp>.
-
-=item Unsupported directory function "%s" called
-
-(F) Your machine doesn't support opendir() and readdir().
-
-=item Unsupported function %s
-
-(F) This machine doesn't implement the indicated function, apparently.
-At least, Configure doesn't think so.
-
-=item Unsupported function fork
-
-(F) Your version of executable does not support forking.
-
-Note that under some systems, like OS/2, there may be different flavors
-of Perl executables, some of which may support fork, some not. Try
-changing the name you call Perl by to C<perl_>, C<perl__>, and so on.
-
-=item Unsupported script encoding %s
-
-(F) Your program file begins with a Unicode Byte Order Mark (BOM) which
-declares it to be in a Unicode encoding that Perl cannot read.
-
-=item Unsupported socket function "%s" called
-
-(F) Your machine doesn't support the Berkeley socket mechanism, or at
-least that's what Configure thought.
-
-=item Unterminated attribute list
-
-(F) The lexer found something other than a simple identifier at the
-start of an attribute, and it wasn't a semicolon or the start of a
-block. Perhaps you terminated the parameter list of the previous
-attribute too soon. See L<attributes>.
-
-=item Unterminated attribute parameter in attribute list
-
-(F) The lexer saw an opening (left) parenthesis character while parsing
-an attribute list, but the matching closing (right) parenthesis
-character was not found. You may need to add (or remove) a backslash
-character to get your parentheses to balance. See L<attributes>.
-
-=item Unterminated compressed integer
-
-(F) An argument to unpack("w",...) was incompatible with the BER
-compressed integer format and could not be converted to an integer.
-See L<perlfunc/pack>.
-
-=item Unterminated \g{...} pattern in regex; marked by <-- HERE in m/%s/
-
-(F) You missed a close brace on a \g{..} pattern (group reference) in
-a regular expression. Fix the pattern and retry.
-
-=item Unterminated <> operator
-
-(F) The lexer saw a left angle bracket in a place where it was expecting
-a term, so it's looking for the corresponding right angle bracket, and
-not finding it. Chances are you left some needed parentheses out
-earlier in the line, and you really meant a "less than".
-
-=item Unterminated verb pattern argument in regex; marked by <-- HERE in m/%s/
-
-(F) You used a pattern of the form C<(*VERB:ARG)> but did not terminate
-the pattern with a C<)>. Fix the pattern and retry.
-
-=item Unterminated verb pattern in regex; marked by <-- HERE in m/%s/
-
-(F) You used a pattern of the form C<(*VERB)> but did not terminate
-the pattern with a C<)>. Fix the pattern and retry.
-
-=item untie attempted while %d inner references still exist
-
-(W untie) A copy of the object returned from C<tie> (or C<tied>) was
-still valid when C<untie> was called.
-
-=item Usage: POSIX::%s(%s)
-
-(F) You called a POSIX function with incorrect arguments.
-See L<POSIX/FUNCTIONS> for more information.
-
-=item Usage: Win32::%s(%s)
-
-(F) You called a Win32 function with incorrect arguments.
-See L<Win32> for more information.
-
-=item $[ used in %s (did you mean $] ?)
-
-(W syntax) You used C<$[> in a comparison, such as:
-
- if ($[ > 5.006) {
- ...
- }
-
-You probably meant to use C<$]> instead. C<$[> is the base for indexing
-arrays. C<$]> is the Perl version number in decimal.
-
-=item Useless assignment to a temporary
-
-(W misc) You assigned to an lvalue subroutine, but what
-the subroutine returned was a temporary scalar about to
-be discarded, so the assignment had no effect.
-
-=item Useless (?-%s) - don't use /%s modifier in regex; marked by <-- HERE in m/%s/
-
-(W regexp) You have used an internal modifier such as (?-o) that has no
-meaning unless removed from the entire regexp:
-
- if ($string =~ /(?-o)$pattern/o) { ... }
-
-must be written as
-
- if ($string =~ /$pattern/) { ... }
-
-The <-- HERE shows in the regular expression about
-where the problem was discovered. See L<perlre>.
-
-=item Useless localization of %s
-
-(W syntax) The localization of lvalues such as C<local($x=10)> is legal,
-but in fact the local() currently has no effect. This may change at
-some point in the future, but in the meantime such code is discouraged.
-
-=item Useless (?%s) - use /%s modifier in regex; marked by <-- HERE in m/%s/
-
-(W regexp) You have used an internal modifier such as (?o) that has no
-meaning unless applied to the entire regexp:
-
- if ($string =~ /(?o)$pattern/) { ... }
-
-must be written as
-
- if ($string =~ /$pattern/o) { ... }
-
-The <-- HERE shows in the regular expression about
-where the problem was discovered. See L<perlre>.
-
-=item Useless use of /d modifier in transliteration operator
-
-(W misc) You have used the /d modifier where the searchlist has the
-same length as the replacelist. See L<perlop> for more information
-about the /d modifier.
-
-=item Useless use of \E
-
-(W misc) You have a \E in a double-quotish string without a C<\U>,
-C<\L> or C<\Q> preceding it.
-
-=item Useless use of %s in void context
-
-(W void) You did something without a side effect in a context that does
-nothing with the return value, such as a statement that doesn't return a
-value from a block, or the left side of a scalar comma operator. Very
-often this points not to stupidity on your part, but a failure of Perl
-to parse your program the way you thought it would. For example, you'd
-get this if you mixed up your C precedence with Python precedence and
-said
-
- $one, $two = 1, 2;
-
-when you meant to say
-
- ($one, $two) = (1, 2);
-
-Another common error is to use ordinary parentheses to construct a list
-reference when you should be using square or curly brackets, for
-example, if you say
-
- $array = (1,2);
-
-when you should have said
-
- $array = [1,2];
-
-The square brackets explicitly turn a list value into a scalar value,
-while parentheses do not. So when a parenthesized list is evaluated in
-a scalar context, the comma is treated like C's comma operator, which
-throws away the left argument, which is not what you want. See
-L<perlref> for more on this.
-
-This warning will not be issued for numerical constants equal to 0 or 1
-since they are often used in statements like
-
- 1 while sub_with_side_effects();
-
-String constants that would normally evaluate to 0 or 1 are warned
-about.
-
-=item Useless use of "re" pragma
-
-(W) You did C<use re;> without any arguments. That isn't very useful.
-
-=item Useless use of sort in scalar context
-
-(W void) You used sort in scalar context, as in :
-
- my $x = sort @y;
-
-This is not very useful, and perl currently optimizes this away.
-
-=item Useless use of %s with no values
-
-(W syntax) You used the push() or unshift() function with no arguments
-apart from the array, like C<push(@x)> or C<unshift(@foo)>. That won't
-usually have any effect on the array, so is completely useless. It's
-possible in principle that push(@tied_array) could have some effect
-if the array is tied to a class which implements a PUSH method. If so,
-you can write it as C<push(@tied_array,())> to avoid this warning.
-
-=item "use" not allowed in expression
-
-(F) The "use" keyword is recognized and executed at compile time, and
-returns no useful value. See L<perlmod>.
-
-=item Use of assignment to $[ is deprecated
-
-(D deprecated) The C<$[> variable (index of the first element in an array)
-is deprecated. See L<perlvar/"$[">.
-
-=item Use of bare << to mean <<"" is deprecated
-
-(D deprecated) You are now encouraged to use the explicitly quoted
-form if you wish to use an empty line as the terminator of the here-document.
-
-=item Use of comma-less variable list is deprecated
-
-(D deprecated) The values you give to a format should be
-separated by commas, not just aligned on a line.
-
-=item Use of chdir('') or chdir(undef) as chdir() deprecated
-
-(D deprecated) chdir() with no arguments is documented to change to
-$ENV{HOME} or $ENV{LOGDIR}. chdir(undef) and chdir('') share this
-behavior, but that has been deprecated. In future versions they
-will simply fail.
-
-Be careful to check that what you pass to chdir() is defined and not
-blank, else you might find yourself in your home directory.
-
-=item Use of /c modifier is meaningless in s///
-
-(W regexp) You used the /c modifier in a substitution. The /c
-modifier is not presently meaningful in substitutions.
-
-=item Use of /c modifier is meaningless without /g
-
-(W regexp) You used the /c modifier with a regex operand, but didn't
-use the /g modifier. Currently, /c is meaningful only when /g is
-used. (This may change in the future.)
-
-=item Use of := for an empty attribute list is not allowed
-
-(F) The construction C<my $x := 42> used to parse as equivalent to
-C<my $x : = 42> (applying an empty attribute list to C<$x>).
-This construct was deprecated in 5.12.0, and has now been made a syntax
-error, so C<:=> can be reclaimed as a new operator in the future.
-
-If you need an empty attribute list, for example in a code generator, add
-a space before the C<=>.
-
-=item Use of freed value in iteration
-
-(F) Perhaps you modified the iterated array within the loop?
-This error is typically caused by code like the following:
-
- @a = (3,4);
- @a = () for (1,2,@a);
-
-You are not supposed to modify arrays while they are being iterated over.
-For speed and efficiency reasons, Perl internally does not do full
-reference-counting of iterated items, hence deleting such an item in the
-middle of an iteration causes Perl to see a freed value.
-
-=item Use of *glob{FILEHANDLE} is deprecated
-
-(D deprecated) You are now encouraged to use the shorter *glob{IO} form
-to access the filehandle slot within a typeglob.
-
-=item Use of /g modifier is meaningless in split
-
-(W regexp) You used the /g modifier on the pattern for a C<split>
-operator. Since C<split> always tries to match the pattern
-repeatedly, the C</g> has no effect.
-
-=item Use of "goto" to jump into a construct is deprecated
-
-(D deprecated) Using C<goto> to jump from an outer scope into an inner
-scope is deprecated and should be avoided.
-
-=item Use of inherited AUTOLOAD for non-method %s() is deprecated
-
-(D deprecated) As an (ahem) accidental feature, C<AUTOLOAD>
-subroutines are looked up as methods (using the C<@ISA> hierarchy)
-even when the subroutines to be autoloaded were called as plain
-functions (e.g. C<Foo::bar()>), not as methods (e.g. C<< Foo->bar() >> or
-C<< $obj->bar() >>).
-
-This bug will be rectified in future by using method lookup only for
-methods' C<AUTOLOAD>s. However, there is a significant base of existing
-code that may be using the old behavior. So, as an interim step, Perl
-currently issues an optional warning when non-methods use inherited
-C<AUTOLOAD>s.
-
-The simple rule is: Inheritance will not work when autoloading
-non-methods. The simple fix for old code is: In any module that used
-to depend on inheriting C<AUTOLOAD> for non-methods from a base class
-named C<BaseClass>, execute C<*AUTOLOAD = \&BaseClass::AUTOLOAD> during
-startup.
-
-In code that currently says C<use AutoLoader; @ISA = qw(AutoLoader);>
-you should remove AutoLoader from @ISA and change C<use AutoLoader;> to
-C<use AutoLoader 'AUTOLOAD';>.
-
-=item Use of %s in printf format not supported
-
-(F) You attempted to use a feature of printf that is accessible from
-only C. This usually means there's a better way to do it in Perl.
-
-=item Use of %s is deprecated
-
-(D deprecated) The construct indicated is no longer recommended for use,
-generally because there's a better way to do it, and also because the
-old way has bad side effects.
-
-=item Use of -l on filehandle %s
-
-(W io) A filehandle represents an opened file, and when you opened the file
-it already went past any symlink you are presumably trying to look for.
-The operation returned C<undef>. Use a filename instead.
-
-=item Use of %s on a handle without * is deprecated
-
-(D deprecated) You used C<tie>, C<tied> or C<untie> on a scalar but that scalar
-happens to hold a typeglob, which means its filehandle will be tied. If
-you mean to tie a handle, use an explicit * as in C<tie *$handle>.
-
-This was a long-standing bug that was removed in Perl 5.16, as there was
-no way to tie the scalar itself when it held a typeglob, and no way to
-untie a scalar that had had a typeglob assigned to it. If you see this
-message, you must be using an older version.
-
-=item Use of ?PATTERN? without explicit operator is deprecated
-
-(D deprecated) You have written something like C<?\w?>, for a regular
-expression that matches only once. Starting this term directly with
-the question mark delimiter is now deprecated, so that the question mark
-will be available for use in new operators in the future. Write C<m?\w?>
-instead, explicitly using the C<m> operator: the question mark delimiter
-still invokes match-once behaviour.
-
-=item Use of qw(...) as parentheses is deprecated
-
-(D deprecated) You have something like C<foreach $x qw(a b c) {...}>,
-using a C<qw(...)> list literal where a parenthesised expression is
-expected. Historically the parser fooled itself into thinking that
-C<qw(...)> literals were always enclosed in parentheses, and as a result
-you could sometimes omit parentheses around them. (You could never do
-the C<foreach qw(a b c) {...}> that you might have expected, though.)
-The parser no longer lies to itself in this way. Wrap the list literal
-in parentheses, like C<foreach $x (qw(a b c)) {...}>.
-
-=item Use of reference "%s" as array index
-
-(W misc) You tried to use a reference as an array index; this probably
-isn't what you mean, because references in numerical context tend
-to be huge numbers, and so usually indicates programmer error.
-
-If you really do mean it, explicitly numify your reference, like so:
-C<$array[0+$ref]>. This warning is not given for overloaded objects,
-however, because you can overload the numification and stringification
-operators and then you presumably know what you are doing.
-
-=item Use of reserved word "%s" is deprecated
-
-(D deprecated) The indicated bareword is a reserved word. Future
-versions of perl may use it as a keyword, so you're better off either
-explicitly quoting the word in a manner appropriate for its context of
-use, or using a different name altogether. The warning can be
-suppressed for subroutine names by either adding a C<&> prefix, or using
-a package qualifier, e.g. C<&our()>, or C<Foo::our()>.
-
-=item Use of tainted arguments in %s is deprecated
-
-(W taint, deprecated) You have supplied C<system()> or C<exec()> with multiple
-arguments and at least one of them is tainted. This used to be allowed
-but will become a fatal error in a future version of perl. Untaint your
-arguments. See L<perlsec>.
-
-=item Use of uninitialized value%s
-
-(W uninitialized) An undefined value was used as if it were already
-defined. It was interpreted as a "" or a 0, but maybe it was a mistake.
-To suppress this warning assign a defined value to your variables.
-
-To help you figure out what was undefined, perl will try to tell you
-the name of the variable (if any) that was undefined. In some cases
-it cannot do this, so it also tells you what operation you used the
-undefined value in. Note, however, that perl optimizes your program
-anid the operation displayed in the warning may not necessarily appear
-literally in your program. For example, C<"that $foo"> is usually
-optimized into C<"that " . $foo>, and the warning will refer to the
-C<concatenation (.)> operator, even though there is no C<.> in
-your program.
-
-=item Using a hash as a reference is deprecated
-
-(D deprecated) You tried to use a hash as a reference, as in
-C<< %foo->{"bar"} >> or C<< %$ref->{"hello"} >>. Versions of perl <= 5.6.1
-used to allow this syntax, but shouldn't have. It is now
-deprecated, and will be removed in a future version.
-
-=item Using an array as a reference is deprecated
-
-(D deprecated) You tried to use an array as a reference, as in
-C<< @foo->[23] >> or C<< @$ref->[99] >>. Versions of perl <= 5.6.1 used to
-allow this syntax, but shouldn't have. It is now deprecated,
-and will be removed in a future version.
-
-=item Using just the first character returned by \N{} in character class
-
-(W) A charnames handler may return a sequence of more than one character.
-Currently all but the first one are discarded when used in a regular
-expression pattern bracketed character class.
-
-=item Using !~ with %s doesn't make sense
-
-(F) Using the C<!~> operator with C<s///r>, C<tr///r> or C<y///r> is
-currently reserved for future use, as the exact behaviour has not
-been decided. (Simply returning the boolean opposite of the
-modified string is usually not particularly useful.)
-
-=item UTF-16 surrogate U+%X
-
-(W utf8, surrogate) You had a UTF-16 surrogate in a context where they are
-not considered acceptable. These code points, between U+D800 and
-U+DFFF (inclusive), are used by Unicode only for UTF-16. However, Perl
-internally allows all unsigned integer code points (up to the size limit
-available on your platform), including surrogates. But these can cause
-problems when being input or output, which is likely where this message
-came from. If you really really know what you are doing you can turn
-off this warning by C<no warnings 'surrogate';>.
-
-=item Value of %s can be "0"; test with defined()
-
-(W misc) In a conditional expression, you used <HANDLE>, <*> (glob),
-C<each()>, or C<readdir()> as a boolean value. Each of these constructs
-can return a value of "0"; that would make the conditional expression
-false, which is probably not what you intended. When using these
-constructs in conditional expressions, test their values with the
-C<defined> operator.
-
-=item Value of CLI symbol "%s" too long
-
-(W misc) A warning peculiar to VMS. Perl tried to read the value of an
-%ENV element from a CLI symbol table, and found a resultant string
-longer than 1024 characters. The return value has been truncated to
-1024 characters.
-
-=item Variable "%s" is not available
-
-(W closure) During compilation, an inner named subroutine or eval is
-attempting to capture an outer lexical that is not currently available.
-This can happen for one of two reasons. First, the outer lexical may be
-declared in an outer anonymous subroutine that has not yet been created.
-(Remember that named subs are created at compile time, while anonymous
-subs are created at run-time.) For example,
-
- sub { my $a; sub f { $a } }
-
-At the time that f is created, it can't capture the current value of $a,
-since the anonymous subroutine hasn't been created yet. Conversely,
-the following won't give a warning since the anonymous subroutine has by
-now been created and is live:
-
- sub { my $a; eval 'sub f { $a }' }->();
-
-The second situation is caused by an eval accessing a variable that has
-gone out of scope, for example,
-
- sub f {
- my $a;
- sub { eval '$a' }
- }
- f()->();
-
-Here, when the '$a' in the eval is being compiled, f() is not currently being
-executed, so its $a is not available for capture.
-
-=item Variable "%s" is not imported%s
-
-(W misc) With "use strict" in effect, you referred to a global variable
-that you apparently thought was imported from another module, because
-something else of the same name (usually a subroutine) is exported by
-that module. It usually means you put the wrong funny character on the
-front of your variable.
-
-=item Variable length lookbehind not implemented in m/%s/
-
-(F) Lookbehind is allowed only for subexpressions whose length is fixed and
-known at compile time. See L<perlre>.
-
-=item "%s" variable %s masks earlier declaration in same %s
-
-(W misc) A "my", "our" or "state" variable has been redeclared in the
-current scope or statement, effectively eliminating all access to the
-previous instance. This is almost always a typographical error. Note
-that the earlier variable will still exist until the end of the scope
-or until all closure referents to it are destroyed.
-
-=item Variable syntax
-
-(A) You've accidentally run your script through B<csh> instead
-of Perl. Check the #! line, or manually feed your script into
-Perl yourself.
-
-=item Variable "%s" will not stay shared
-
-(W closure) An inner (nested) I<named> subroutine is referencing a
-lexical variable defined in an outer named subroutine.
-
-When the inner subroutine is called, it will see the value of
-the outer subroutine's variable as it was before and during the *first*
-call to the outer subroutine; in this case, after the first call to the
-outer subroutine is complete, the inner and outer subroutines will no
-longer share a common value for the variable. In other words, the
-variable will no longer be shared.
-
-This problem can usually be solved by making the inner subroutine
-anonymous, using the C<sub {}> syntax. When inner anonymous subs that
-reference variables in outer subroutines are created, they
-are automatically rebound to the current values of such variables.
-
-=item vector argument not supported with alpha versions
-
-(W internal) The %vd (s)printf format does not support version objects
-with alpha parts.
-
-=item Verb pattern '%s' has a mandatory argument in regex; marked by <-- HERE in m/%s/
-
-(F) You used a verb pattern that requires an argument. Supply an
-argument or check that you are using the right verb.
-
-=item Verb pattern '%s' may not have an argument in regex; marked by <-- HERE in m/%s/
-
-(F) You used a verb pattern that is not allowed an argument. Remove the
-argument or check that you are using the right verb.
-
-=item Version number must be a constant number
-
-(P) The attempt to translate a C<use Module n.n LIST> statement into
-its equivalent C<BEGIN> block found an internal inconsistency with
-the version number.
-
-=item Version string '%s' contains invalid data; ignoring: '%s'
-
-(W misc) The version string contains invalid characters at the end, which
-are being ignored.
-
-=item Warning: something's wrong
-
-(W) You passed warn() an empty string (the equivalent of C<warn "">) or
-you called it with no args and C<$@> was empty.
-
-=item Warning: unable to close filehandle %s properly
-
-(S) The implicit close() done by an open() got an error indication on
-the close(). This usually indicates your file system ran out of disk
-space.
-
-=item Warning: Use of "%s" without parentheses is ambiguous
-
-(S ambiguous) You wrote a unary operator followed by something that
-looks like a binary operator that could also have been interpreted as a
-term or unary operator. For instance, if you know that the rand
-function has a default argument of 1.0, and you write
-
- rand + 5;
-
-you may THINK you wrote the same thing as
-
- rand() + 5;
-
-but in actual fact, you got
-
- rand(+5);
-
-So put in parentheses to say what you really mean.
-
-=item Wide character in %s
-
-(S utf8) Perl met a wide character (>255) when it wasn't expecting
-one. This warning is by default on for I/O (like print). The easiest
-way to quiet this warning is simply to add the C<:utf8> layer to the
-output, e.g. C<binmode STDOUT, ':utf8'>. Another way to turn off the
-warning is to add C<no warnings 'utf8';> but that is often closer to
-cheating. In general, you are supposed to explicitly mark the
-filehandle with an encoding, see L<open> and L<perlfunc/binmode>.
-
-=item Within []-length '%c' not allowed
-
-(F) The count in the (un)pack template may be replaced by C<[TEMPLATE]>
-only if C<TEMPLATE> always matches the same amount of packed bytes that
-can be determined from the template alone. This is not possible if
-it contains any of the codes @, /, U, u, w or a *-length. Redesign
-the template.
-
-=item write() on closed filehandle %s
-
-(W closed) The filehandle you're writing to got itself closed sometime
-before now. Check your control flow.
-
-=item %s "\x%X" does not map to Unicode
-
-(F) When reading in different encodings Perl tries to map everything
-into Unicode characters. The bytes you read in are not legal in
-this encoding, for example
-
- utf8 "\xE4" does not map to Unicode
-
-if you try to read in the a-diaereses Latin-1 as UTF-8.
-
-=item 'X' outside of string
-
-(F) You had a (un)pack template that specified a relative position before
-the beginning of the string being (un)packed. See L<perlfunc/pack>.
-
-=item 'x' outside of string in unpack
-
-(F) You had a pack template that specified a relative position after
-the end of the string being unpacked. See L<perlfunc/pack>.
-
-=item YOU HAVEN'T DISABLED SET-ID SCRIPTS IN THE KERNEL YET!
-
-(F) And you probably never will, because you probably don't have the
-sources to your kernel, and your vendor probably doesn't give a rip
-about what you want. Your best bet is to put a setuid C wrapper around
-your script.
-
-=item You need to quote "%s"
-
-(W syntax) You assigned a bareword as a signal handler name.
-Unfortunately, you already have a subroutine of that name declared,
-which means that Perl 5 will try to call the subroutine when the
-assignment is executed, which is probably not what you want. (If it IS
-what you want, put an & in front.)
-
-=item Your random numbers are not that random
-
-(F) When trying to initialise the random seed for hashes, Perl could
-not get any randomness out of your system. This usually indicates
-Something Very Wrong.
-
-=back
-
-=head1 SEE ALSO
-
-L<warnings>, L<perllexwarn>, L<diagnostics>.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perldoc.pod b/Master/tlpkg/tlperl/lib/pods/perldoc.pod
deleted file mode 100644
index 42a9eab4cdb..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perldoc.pod
+++ /dev/null
@@ -1,272 +0,0 @@
-
-=head1 NAME
-
-perldoc - Look up Perl documentation in Pod format.
-
-=head1 SYNOPSIS
-
- B<perldoc> [B<-h>] [B<-D>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] [B<-F>]
- [B<-i>] [B<-V>] [B<-T>] [B<-r>]
- [B<-dI<destination_file>>]
- [B<-oI<formatname>>]
- [B<-MI<FormatterClassName>>]
- [B<-wI<formatteroption:value>>]
- [B<-n>I<nroff-replacement>]
- [B<-X>]
- [B<-L> I<language_code>]
- PageName|ModuleName|ProgramName|URL
-
-Examples:
-
- B<perldoc> B<-f> BuiltinFunction
-
- B<perldoc> B<-L> it B<-f> BuiltinFunction
-
- B<perldoc> B<-q> FAQ Keyword
-
- B<perldoc> B<-L> fr B<-q> FAQ Keyword
-
- B<perldoc> B<-v> PerlVariable
-
-See below for more description of the switches.
-
-=head1 DESCRIPTION
-
-B<perldoc> looks up a piece of documentation in .pod format that is
-embedded in the perl installation tree or in a perl script, and displays
-it via C<groff -man | $PAGER>. (In addition, if running under HP-UX,
-C<col -x> will be used.) This is primarily used for the documentation for
-the perl library modules.
-
-Your system may also have man pages installed for those modules, in
-which case you can probably just use the man(1) command.
-
-If you are looking for a table of contents to the Perl library modules
-documentation, see the L<perltoc> page.
-
-=head1 OPTIONS
-
-=over 5
-
-=item B<-h>
-
-Prints out a brief B<h>elp message.
-
-=item B<-D>
-
-B<D>escribes search for the item in B<d>etail.
-
-=item B<-t>
-
-Display docs using plain B<t>ext converter, instead of nroff. This may be faster,
-but it probably won't look as nice.
-
-=item B<-u>
-
-Skip the real Pod formatting, and just show the raw Pod source (B<U>nformatted)
-
-=item B<-m> I<module>
-
-Display the entire module: both code and unformatted pod documentation.
-This may be useful if the docs don't explain a function in the detail
-you need, and you'd like to inspect the code directly; perldoc will find
-the file for you and simply hand it off for display.
-
-=item B<-l>
-
-Display onB<l>y the file name of the module found.
-
-=item B<-F>
-
-Consider arguments as file names; no search in directories will be performed.
-
-=item B<-f> I<perlfunc>
-
-The B<-f> option followed by the name of a perl built-in function will
-extract the documentation of this function from L<perlfunc>.
-
-Example:
-
- perldoc -f sprintf
-
-
-=item B<-q> I<perlfaq-search-regexp>
-
-The B<-q> option takes a regular expression as an argument. It will search
-the B<q>uestion headings in perlfaq[1-9] and print the entries matching
-the regular expression.
-
-Example:
-
- perldoc -q shuffle
-
-
-=item B<-v> I<perlvar>
-
-The B<-v> option followed by the name of a Perl predefined variable will
-extract the documentation of this variable from L<perlvar>.
-
-Examples:
-
- perldoc -v '$"'
- perldoc -v @+
- perldoc -v DATA
-
-
-=item B<-T>
-
-This specifies that the output is not to be sent to a pager, but is to
-be sent right to STDOUT.
-
-=item B<-d> I<destination-filename>
-
-This specifies that the output is to be sent neither to a pager nor
-to STDOUT, but is to be saved to the specified filename. Example:
-C<perldoc -oLaTeX -dtextwrapdocs.tex Text::Wrap>
-
-=item B<-o> I<output-formatname>
-
-This specifies that you want Perldoc to try using a Pod-formatting
-class for the output format that you specify. For example:
-C<-oman>. This is actually just a wrapper around the C<-M> switch;
-using C<-oI<formatname>> just looks for a loadable class by adding
-that format name (with different capitalizations) to the end of
-different classname prefixes.
-
-For example, C<-oLaTeX> currently tries all of the following classes:
-Pod::Perldoc::ToLaTeX Pod::Perldoc::Tolatex Pod::Perldoc::ToLatex
-Pod::Perldoc::ToLATEX Pod::Simple::LaTeX Pod::Simple::latex
-Pod::Simple::Latex Pod::Simple::LATEX Pod::LaTeX Pod::latex Pod::Latex
-Pod::LATEX.
-
-=item B<-M> I<module-name>
-
-This specifies the module that you want to try using for formatting the
-pod. The class must at least provide a C<parse_from_file> method.
-For example: C<perldoc -MPod::Perldoc::ToChecker>.
-
-You can specify several classes to try by joining them with commas
-or semicolons, as in C<-MTk::SuperPod;Tk::Pod>.
-
-=item B<-w> I<option:value> or B<-w> I<option>
-
-This specifies an option to call the formatter B<w>ith. For example,
-C<-w textsize:15> will call
-C<< $formatter->textsize(15) >> on the formatter object before it is
-used to format the object. For this to be valid, the formatter class
-must provide such a method, and the value you pass should be valid.
-(So if C<textsize> expects an integer, and you do C<-w textsize:big>,
-expect trouble.)
-
-You can use C<-w optionname> (without a value) as shorthand for
-C<-w optionname:I<TRUE>>. This is presumably useful in cases of on/off
-features like: C<-w page_numbering>.
-
-You can use an "=" instead of the ":", as in: C<-w textsize=15>. This
-might be more (or less) convenient, depending on what shell you use.
-
-=item B<-X>
-
-Use an index if it is present. The B<-X> option looks for an entry
-whose basename matches the name given on the command line in the file
-C<$Config{archlib}/pod.idx>. The F<pod.idx> file should contain fully
-qualified filenames, one per line.
-
-=item B<-L> I<language_code>
-
-This allows one to specify the I<language code> for the desired language
-translation. If the C<POD2::E<lt>language_codeE<gt>> package isn't
-installed in your system, the switch is ignored.
-All available translation packages are to be found under the C<POD2::>
-namespace. See L<POD2::IT> (or L<POD2::FR>) to see how to create new
-localized C<POD2::*> documentation packages and integrate them into
-L<Pod::Perldoc>.
-
-=item B<PageName|ModuleName|ProgramName|URL>
-
-The item you want to look up. Nested modules (such as C<File::Basename>)
-are specified either as C<File::Basename> or C<< File/Basename >>. You may also
-give a descriptive name of a page, such as C<perlfunc>. For URLs, HTTP and
-HTTPS are the only kind currently supported.
-
-For simple names like 'foo', when the normal search fails to find
-a matching page, a search with the "perl" prefix is tried as well.
-So "perldoc intro" is enough to find/render "perlintro.pod".
-
-=item B<-n> I<some-formatter>
-
-Specify replacement for groff
-
-=item B<-r>
-
-Recursive search.
-
-=item B<-i>
-
-Ignore case.
-
-=item B<-V>
-
-Displays the version of perldoc you're running.
-
-=back
-
-=head1 SECURITY
-
-Because B<perldoc> does not run properly tainted, and is known to
-have security issues, when run as the superuser it will attempt to
-drop privileges by setting the effective and real IDs to nobody's
-or nouser's account, or -2 if unavailable. If it cannot relinquish
-its privileges, it will not run.
-
-
-=head1 ENVIRONMENT
-
-Any switches in the C<PERLDOC> environment variable will be used before the
-command line arguments.
-
-Useful values for C<PERLDOC> include C<-oman>, C<-otext>, C<-otk>, C<-ortf>,
-C<-oxml>, and so on, depending on what modules you have on hand; or
-the formatter class may be specified exactly with C<-MPod::Perldoc::ToMan>
-or the like.
-
-C<perldoc> also searches directories
-specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
-defined) and C<PATH> environment variables.
-(The latter is so that embedded pods for executables, such as
-C<perldoc> itself, are available.)
-
-C<perldoc> will use, in order of preference, the pager defined in
-C<PERLDOC_PAGER>, C<MANPAGER>, or C<PAGER> before trying to find a pager
-on its own. (C<MANPAGER> is not used if C<perldoc> was told to display
-plain text or unformatted pod.)
-
-One useful value for C<PERLDOC_PAGER> is C<less -+C -E>.
-
-Having PERLDOCDEBUG set to a positive integer will make perldoc emit
-even more descriptive output than the C<-v> switch does; the higher the
-number, the more it emits.
-
-
-=head1 CHANGES
-
-Up to 3.14_05, the switch B<-v> was used to produce verbose
-messages of B<perldoc> operation, which is now enabled by B<-D>.
-
-=head1 SEE ALSO
-
-L<perlpod>, L<Pod::Perldoc>
-
-=head1 AUTHOR
-
-Current maintainer: Mark Allen C<< <mallen@cpan.org> >>
-
-Past contributors are:
-brian d foy C<< <bdfoy@cpan.org> >>
-Adriano R. Ferreira C<< <ferreira@cpan.org> >>,
-Sean M. Burke C<< <sburke@cpan.org> >>,
-Kenneth Albanowski C<< <kjahds@kjahds.com> >>,
-Andy Dougherty C<< <doughera@lafcol.lafayette.edu> >>,
-and many others.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perldos.pod b/Master/tlpkg/tlperl/lib/pods/perldos.pod
deleted file mode 100644
index ef3578f8894..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perldos.pod
+++ /dev/null
@@ -1,331 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see perlpod manpage) which is
-specially designed to be readable as is.
-
-=head1 NAME
-
-perldos - Perl under DOS, W31, W95.
-
-=head1 SYNOPSIS
-
-These are instructions for building Perl under DOS (or w??), using
-DJGPP v2.03 or later. Under w95 long filenames are supported.
-
-=head1 DESCRIPTION
-
-Before you start, you should glance through the README file
-found in the top-level directory where the Perl distribution
-was extracted. Make sure you read and understand the terms under
-which this software is being distributed.
-
-This port currently supports MakeMaker (the set of modules that
-is used to build extensions to perl). Therefore, you should be
-able to build and install most extensions found in the CPAN sites.
-
-Detailed instructions on how to build and install perl extension
-modules, including XS-type modules, is included. See 'BUILDING AND
-INSTALLING MODULES'.
-
-=head2 Prerequisites for Compiling Perl on DOS
-
-=over 4
-
-=item DJGPP
-
-DJGPP is a port of GNU C/C++ compiler and development tools to 32-bit,
-protected-mode environment on Intel 32-bit CPUs running MS-DOS and compatible
-operating systems, by DJ Delorie <dj@delorie.com> and friends.
-
-For more details (FAQ), check out the home of DJGPP at:
-
- http://www.delorie.com/djgpp/
-
-If you have questions about DJGPP, try posting to the DJGPP newsgroup:
-comp.os.msdos.djgpp, or use the email gateway djgpp@delorie.com.
-
-You can find the full DJGPP distribution on any of the mirrors listed here:
-
- http://www.delorie.com/djgpp/getting.html
-
-You need the following files to build perl (or add new modules):
-
- v2/djdev203.zip
- v2gnu/bnu2112b.zip
- v2gnu/gcc2953b.zip
- v2gnu/bsh204b.zip
- v2gnu/mak3791b.zip
- v2gnu/fil40b.zip
- v2gnu/sed3028b.zip
- v2gnu/txt20b.zip
- v2gnu/dif272b.zip
- v2gnu/grep24b.zip
- v2gnu/shl20jb.zip
- v2gnu/gwk306b.zip
- v2misc/csdpmi5b.zip
-
-or possibly any newer version.
-
-=item Pthreads
-
-Thread support is not tested in this version of the djgpp perl.
-
-=back
-
-=head2 Shortcomings of Perl under DOS
-
-Perl under DOS lacks some features of perl under UNIX because of
-deficiencies in the UNIX-emulation, most notably:
-
-=over 4
-
-=item *
-
-fork() and pipe()
-
-=item *
-
-some features of the UNIX filesystem regarding link count and file dates
-
-=item *
-
-in-place operation is a little bit broken with short filenames
-
-=item *
-
-sockets
-
-=back
-
-=head2 Building Perl on DOS
-
-=over 4
-
-=item *
-
-Unpack the source package F<perl5.8*.tar.gz> with djtarx. If you want
-to use long file names under w95 and also to get Perl to pass all its
-tests, don't forget to use
-
- set LFN=y
- set FNCASE=y
-
-before unpacking the archive.
-
-=item *
-
-Create a "symlink" or copy your bash.exe to sh.exe in your C<($DJDIR)/bin>
-directory.
-
- ln -s bash.exe sh.exe
-
-[If you have the recommended version of bash for DJGPP, this is already
-done for you.]
-
-And make the C<SHELL> environment variable point to this F<sh.exe>:
-
- set SHELL=c:/djgpp/bin/sh.exe (use full path name!)
-
-You can do this in F<djgpp.env> too. Add this line BEFORE any section
-definition:
-
- +SHELL=%DJDIR%/bin/sh.exe
-
-=item *
-
-If you have F<split.exe> and F<gsplit.exe> in your path, then rename
-F<split.exe> to F<djsplit.exe>, and F<gsplit.exe> to F<split.exe>.
-Copy or link F<gecho.exe> to F<echo.exe> if you don't have F<echo.exe>.
-Copy or link F<gawk.exe> to F<awk.exe> if you don't have F<awk.exe>.
-
-[If you have the recommended versions of djdev, shell utilities and
-gawk, all these are already done for you, and you will not need to do
-anything.]
-
-=item *
-
-Chdir to the djgpp subdirectory of perl toplevel and type the following
-commands:
-
- set FNCASE=y
- configure.bat
-
-This will do some preprocessing then run the Configure script for you.
-The Configure script is interactive, but in most cases you just need to
-press ENTER. The "set" command ensures that DJGPP preserves the letter
-case of file names when reading directories. If you already issued this
-set command when unpacking the archive, and you are in the same DOS
-session as when you unpacked the archive, you don't have to issue the
-set command again. This command is necessary *before* you start to
-(re)configure or (re)build perl in order to ensure both that perl builds
-correctly and that building XS-type modules can succeed. See the DJGPP
-info entry for "_preserve_fncase" for more information:
-
- info libc alphabetical _preserve_fncase
-
-If the script says that your package is incomplete, and asks whether
-to continue, just answer with Y (this can only happen if you don't use
-long filenames or forget to issue "set FNCASE=y" first).
-
-When Configure asks about the extensions, I suggest IO and Fcntl,
-and if you want database handling then SDBM_File or GDBM_File
-(you need to install gdbm for this one). If you want to use the
-POSIX extension (this is the default), make sure that the stack
-size of your F<cc1.exe> is at least 512kbyte (you can check this
-with: C<stubedit cc1.exe>).
-
-You can use the Configure script in non-interactive mode too.
-When I built my F<perl.exe>, I used something like this:
-
- configure.bat -des
-
-You can find more info about Configure's command line switches in
-the F<INSTALL> file.
-
-When the script ends, and you want to change some values in the
-generated F<config.sh> file, then run
-
- sh Configure -S
-
-after you made your modifications.
-
-IMPORTANT: if you use this C<-S> switch, be sure to delete the CONFIG
-environment variable before running the script:
-
- set CONFIG=
-
-=item *
-
-Now you can compile Perl. Type:
-
- make
-
-=back
-
-=head2 Testing Perl on DOS
-
-Type:
-
- make test
-
-If you're lucky you should see "All tests successful". But there can be
-a few failed subtests (less than 5 hopefully) depending on some external
-conditions (e.g. some subtests fail under linux/dosemu or plain dos
-with short filenames only).
-
-=head2 Installation of Perl on DOS
-
-Type:
-
- make install
-
-This will copy the newly compiled perl and libraries into your DJGPP
-directory structure. Perl.exe and the utilities go into C<($DJDIR)/bin>,
-and the library goes under C<($DJDIR)/lib/perl5>. The pod documentation
-goes under C<($DJDIR)/lib/perl5/pod>.
-
-=head1 BUILDING AND INSTALLING MODULES ON DOS
-
-=head2 Building Prerequisites for Perl on DOS
-
-For building and installing non-XS modules, all you need is a working
-perl under DJGPP. Non-XS modules do not require re-linking the perl
-binary, and so are simpler to build and install.
-
-XS-type modules do require re-linking the perl binary, because part of
-an XS module is written in "C", and has to be linked together with the
-perl binary to be executed. This is required because perl under DJGPP
-is built with the "static link" option, due to the lack of "dynamic
-linking" in the DJGPP environment.
-
-Because XS modules require re-linking of the perl binary, you need both
-the perl binary distribution and the perl source distribution to build
-an XS extension module. In addition, you will have to have built your
-perl binary from the source distribution so that all of the components
-of the perl binary are available for the required link step.
-
-=head2 Unpacking CPAN Modules on DOS
-
-First, download the module package from CPAN (e.g., the "Comma Separated
-Value" text package, Text-CSV-0.01.tar.gz). Then expand the contents of
-the package into some location on your disk. Most CPAN modules are
-built with an internal directory structure, so it is usually safe to
-expand it in the root of your DJGPP installation. Some people prefer to
-locate source trees under /usr/src (i.e., C<($DJDIR)/usr/src>), but you may
-put it wherever seems most logical to you, *EXCEPT* under the same
-directory as your perl source code. There are special rules that apply
-to modules which live in the perl source tree that do not apply to most
-of the modules in CPAN.
-
-Unlike other DJGPP packages, which are normal "zip" files, most CPAN
-module packages are "gzipped tarballs". Recent versions of WinZip will
-safely unpack and expand them, *UNLESS* they have zero-length files. It
-is a known WinZip bug (as of v7.0) that it will not extract zero-length
-files.
-
-From the command line, you can use the djtar utility provided with DJGPP
-to unpack and expand these files. For example:
-
- C:\djgpp>djtarx -v Text-CSV-0.01.tar.gz
-
-This will create the new directory C<($DJDIR)/Text-CSV-0.01>, filling
-it with the source for this module.
-
-=head2 Building Non-XS Modules on DOS
-
-To build a non-XS module, you can use the standard module-building
-instructions distributed with perl modules.
-
- perl Makefile.PL
- make
- make test
- make install
-
-This is sufficient because non-XS modules install only ".pm" files and
-(sometimes) pod and/or man documentation. No re-linking of the perl
-binary is needed to build, install or use non-XS modules.
-
-=head2 Building XS Modules on DOS
-
-To build an XS module, you must use the standard module-building
-instructions distributed with perl modules *PLUS* three extra
-instructions specific to the DJGPP "static link" build environment.
-
- set FNCASE=y
- perl Makefile.PL
- make
- make perl
- make test
- make -f Makefile.aperl inst_perl MAP_TARGET=perl.exe
- make install
-
-The first extra instruction sets DJGPP's FNCASE environment variable so
-that the new perl binary which you must build for an XS-type module will
-build correctly. The second extra instruction re-builds the perl binary
-in your module directory before you run "make test", so that you are
-testing with the new module code you built with "make". The third extra
-instruction installs the perl binary from your module directory into the
-standard DJGPP binary directory, C<($DJDIR)/bin>, replacing your
-previous perl binary.
-
-Note that the MAP_TARGET value *must* have the ".exe" extension or you
-will not create a "perl.exe" to replace the one in C<($DJDIR)/bin>.
-
-When you are done, the XS-module install process will have added information
-to your "perllocal" information telling that the perl binary has been replaced,
-and what module was installed. You can view this information at any time
-by using the command:
-
- perl -S perldoc perllocal
-
-=head1 AUTHOR
-
-Laszlo Molnar, F<laszlo.molnar@eth.ericsson.se> [Installing/building perl]
-
-Peter J. Farley III F<pjfarley@banet.net> [Building/installing modules]
-
-=head1 SEE ALSO
-
-perl(1).
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perldsc.pod b/Master/tlpkg/tlperl/lib/pods/perldsc.pod
deleted file mode 100644
index b30948c32ab..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perldsc.pod
+++ /dev/null
@@ -1,847 +0,0 @@
-=head1 NAME
-X<data structure> X<complex data structure> X<struct>
-
-perldsc - Perl Data Structures Cookbook
-
-=head1 DESCRIPTION
-
-The single feature most sorely lacking in the Perl programming language
-prior to its 5.0 release was complex data structures. Even without direct
-language support, some valiant programmers did manage to emulate them, but
-it was hard work and not for the faint of heart. You could occasionally
-get away with the C<$m{$AoA,$b}> notation borrowed from B<awk> in which the
-keys are actually more like a single concatenated string C<"$AoA$b">, but
-traversal and sorting were difficult. More desperate programmers even
-hacked Perl's internal symbol table directly, a strategy that proved hard
-to develop and maintain--to put it mildly.
-
-The 5.0 release of Perl let us have complex data structures. You
-may now write something like this and all of a sudden, you'd have an array
-with three dimensions!
-
- for $x (1 .. 10) {
- for $y (1 .. 10) {
- for $z (1 .. 10) {
- $AoA[$x][$y][$z] =
- $x ** $y + $z;
- }
- }
- }
-
-Alas, however simple this may appear, underneath it's a much more
-elaborate construct than meets the eye!
-
-How do you print it out? Why can't you say just C<print @AoA>? How do
-you sort it? How can you pass it to a function or get one of these back
-from a function? Is it an object? Can you save it to disk to read
-back later? How do you access whole rows or columns of that matrix? Do
-all the values have to be numeric?
-
-As you see, it's quite easy to become confused. While some small portion
-of the blame for this can be attributed to the reference-based
-implementation, it's really more due to a lack of existing documentation with
-examples designed for the beginner.
-
-This document is meant to be a detailed but understandable treatment of the
-many different sorts of data structures you might want to develop. It
-should also serve as a cookbook of examples. That way, when you need to
-create one of these complex data structures, you can just pinch, pilfer, or
-purloin a drop-in example from here.
-
-Let's look at each of these possible constructs in detail. There are separate
-sections on each of the following:
-
-=over 5
-
-=item * arrays of arrays
-
-=item * hashes of arrays
-
-=item * arrays of hashes
-
-=item * hashes of hashes
-
-=item * more elaborate constructs
-
-=back
-
-But for now, let's look at general issues common to all
-these types of data structures.
-
-=head1 REFERENCES
-X<reference> X<dereference> X<dereferencing> X<pointer>
-
-The most important thing to understand about all data structures in
-Perl--including multidimensional arrays--is that even though they might
-appear otherwise, Perl C<@ARRAY>s and C<%HASH>es are all internally
-one-dimensional. They can hold only scalar values (meaning a string,
-number, or a reference). They cannot directly contain other arrays or
-hashes, but instead contain I<references> to other arrays or hashes.
-X<multidimensional array> X<array, multidimensional>
-
-You can't use a reference to an array or hash in quite the same way that you
-would a real array or hash. For C or C++ programmers unused to
-distinguishing between arrays and pointers to the same, this can be
-confusing. If so, just think of it as the difference between a structure
-and a pointer to a structure.
-
-You can (and should) read more about references in L<perlref>.
-Briefly, references are rather like pointers that know what they
-point to. (Objects are also a kind of reference, but we won't be needing
-them right away--if ever.) This means that when you have something which
-looks to you like an access to a two-or-more-dimensional array and/or hash,
-what's really going on is that the base type is
-merely a one-dimensional entity that contains references to the next
-level. It's just that you can I<use> it as though it were a
-two-dimensional one. This is actually the way almost all C
-multidimensional arrays work as well.
-
- $array[7][12] # array of arrays
- $array[7]{string} # array of hashes
- $hash{string}[7] # hash of arrays
- $hash{string}{'another string'} # hash of hashes
-
-Now, because the top level contains only references, if you try to print
-out your array in with a simple print() function, you'll get something
-that doesn't look very nice, like this:
-
- @AoA = ( [2, 3], [4, 5, 7], [0] );
- print $AoA[1][2];
- 7
- print @AoA;
- ARRAY(0x83c38)ARRAY(0x8b194)ARRAY(0x8b1d0)
-
-
-That's because Perl doesn't (ever) implicitly dereference your variables.
-If you want to get at the thing a reference is referring to, then you have
-to do this yourself using either prefix typing indicators, like
-C<${$blah}>, C<@{$blah}>, C<@{$blah[$i]}>, or else postfix pointer arrows,
-like C<$a-E<gt>[3]>, C<$h-E<gt>{fred}>, or even C<$ob-E<gt>method()-E<gt>[3]>.
-
-=head1 COMMON MISTAKES
-
-The two most common mistakes made in constructing something like
-an array of arrays is either accidentally counting the number of
-elements or else taking a reference to the same memory location
-repeatedly. Here's the case where you just get the count instead
-of a nested array:
-
- for $i (1..10) {
- @array = somefunc($i);
- $AoA[$i] = @array; # WRONG!
- }
-
-That's just the simple case of assigning an array to a scalar and getting
-its element count. If that's what you really and truly want, then you
-might do well to consider being a tad more explicit about it, like this:
-
- for $i (1..10) {
- @array = somefunc($i);
- $counts[$i] = scalar @array;
- }
-
-Here's the case of taking a reference to the same memory location
-again and again:
-
- for $i (1..10) {
- @array = somefunc($i);
- $AoA[$i] = \@array; # WRONG!
- }
-
-So, what's the big problem with that? It looks right, doesn't it?
-After all, I just told you that you need an array of references, so by
-golly, you've made me one!
-
-Unfortunately, while this is true, it's still broken. All the references
-in @AoA refer to the I<very same place>, and they will therefore all hold
-whatever was last in @array! It's similar to the problem demonstrated in
-the following C program:
-
- #include <pwd.h>
- main() {
- struct passwd *getpwnam(), *rp, *dp;
- rp = getpwnam("root");
- dp = getpwnam("daemon");
-
- printf("daemon name is %s\nroot name is %s\n",
- dp->pw_name, rp->pw_name);
- }
-
-Which will print
-
- daemon name is daemon
- root name is daemon
-
-The problem is that both C<rp> and C<dp> are pointers to the same location
-in memory! In C, you'd have to remember to malloc() yourself some new
-memory. In Perl, you'll want to use the array constructor C<[]> or the
-hash constructor C<{}> instead. Here's the right way to do the preceding
-broken code fragments:
-X<[]> X<{}>
-
- for $i (1..10) {
- @array = somefunc($i);
- $AoA[$i] = [ @array ];
- }
-
-The square brackets make a reference to a new array with a I<copy>
-of what's in @array at the time of the assignment. This is what
-you want.
-
-Note that this will produce something similar, but it's
-much harder to read:
-
- for $i (1..10) {
- @array = 0 .. $i;
- @{$AoA[$i]} = @array;
- }
-
-Is it the same? Well, maybe so--and maybe not. The subtle difference
-is that when you assign something in square brackets, you know for sure
-it's always a brand new reference with a new I<copy> of the data.
-Something else could be going on in this new case with the C<@{$AoA[$i]}>
-dereference on the left-hand-side of the assignment. It all depends on
-whether C<$AoA[$i]> had been undefined to start with, or whether it
-already contained a reference. If you had already populated @AoA with
-references, as in
-
- $AoA[3] = \@another_array;
-
-Then the assignment with the indirection on the left-hand-side would
-use the existing reference that was already there:
-
- @{$AoA[3]} = @array;
-
-Of course, this I<would> have the "interesting" effect of clobbering
-@another_array. (Have you ever noticed how when a programmer says
-something is "interesting", that rather than meaning "intriguing",
-they're disturbingly more apt to mean that it's "annoying",
-"difficult", or both? :-)
-
-So just remember always to use the array or hash constructors with C<[]>
-or C<{}>, and you'll be fine, although it's not always optimally
-efficient.
-
-Surprisingly, the following dangerous-looking construct will
-actually work out fine:
-
- for $i (1..10) {
- my @array = somefunc($i);
- $AoA[$i] = \@array;
- }
-
-That's because my() is more of a run-time statement than it is a
-compile-time declaration I<per se>. This means that the my() variable is
-remade afresh each time through the loop. So even though it I<looks> as
-though you stored the same variable reference each time, you actually did
-not! This is a subtle distinction that can produce more efficient code at
-the risk of misleading all but the most experienced of programmers. So I
-usually advise against teaching it to beginners. In fact, except for
-passing arguments to functions, I seldom like to see the gimme-a-reference
-operator (backslash) used much at all in code. Instead, I advise
-beginners that they (and most of the rest of us) should try to use the
-much more easily understood constructors C<[]> and C<{}> instead of
-relying upon lexical (or dynamic) scoping and hidden reference-counting to
-do the right thing behind the scenes.
-
-In summary:
-
- $AoA[$i] = [ @array ]; # usually best
- $AoA[$i] = \@array; # perilous; just how my() was that array?
- @{ $AoA[$i] } = @array; # way too tricky for most programmers
-
-
-=head1 CAVEAT ON PRECEDENCE
-X<dereference, precedence> X<dereferencing, precedence>
-
-Speaking of things like C<@{$AoA[$i]}>, the following are actually the
-same thing:
-X<< -> >>
-
- $aref->[2][2] # clear
- $$aref[2][2] # confusing
-
-That's because Perl's precedence rules on its five prefix dereferencers
-(which look like someone swearing: C<$ @ * % &>) make them bind more
-tightly than the postfix subscripting brackets or braces! This will no
-doubt come as a great shock to the C or C++ programmer, who is quite
-accustomed to using C<*a[i]> to mean what's pointed to by the I<i'th>
-element of C<a>. That is, they first take the subscript, and only then
-dereference the thing at that subscript. That's fine in C, but this isn't C.
-
-The seemingly equivalent construct in Perl, C<$$aref[$i]> first does
-the deref of $aref, making it take $aref as a reference to an
-array, and then dereference that, and finally tell you the I<i'th> value
-of the array pointed to by $AoA. If you wanted the C notion, you'd have to
-write C<${$AoA[$i]}> to force the C<$AoA[$i]> to get evaluated first
-before the leading C<$> dereferencer.
-
-=head1 WHY YOU SHOULD ALWAYS C<use strict>
-
-If this is starting to sound scarier than it's worth, relax. Perl has
-some features to help you avoid its most common pitfalls. The best
-way to avoid getting confused is to start every program like this:
-
- #!/usr/bin/perl -w
- use strict;
-
-This way, you'll be forced to declare all your variables with my() and
-also disallow accidental "symbolic dereferencing". Therefore if you'd done
-this:
-
- my $aref = [
- [ "fred", "barney", "pebbles", "bambam", "dino", ],
- [ "homer", "bart", "marge", "maggie", ],
- [ "george", "jane", "elroy", "judy", ],
- ];
-
- print $aref[2][2];
-
-The compiler would immediately flag that as an error I<at compile time>,
-because you were accidentally accessing C<@aref>, an undeclared
-variable, and it would thereby remind you to write instead:
-
- print $aref->[2][2]
-
-=head1 DEBUGGING
-X<data structure, debugging> X<complex data structure, debugging>
-X<AoA, debugging> X<HoA, debugging> X<AoH, debugging> X<HoH, debugging>
-X<array of arrays, debugging> X<hash of arrays, debugging>
-X<array of hashes, debugging> X<hash of hashes, debugging>
-
-Before version 5.002, the standard Perl debugger didn't do a very nice job of
-printing out complex data structures. With 5.002 or above, the
-debugger includes several new features, including command line editing as
-well as the C<x> command to dump out complex data structures. For
-example, given the assignment to $AoA above, here's the debugger output:
-
- DB<1> x $AoA
- $AoA = ARRAY(0x13b5a0)
- 0 ARRAY(0x1f0a24)
- 0 'fred'
- 1 'barney'
- 2 'pebbles'
- 3 'bambam'
- 4 'dino'
- 1 ARRAY(0x13b558)
- 0 'homer'
- 1 'bart'
- 2 'marge'
- 3 'maggie'
- 2 ARRAY(0x13b540)
- 0 'george'
- 1 'jane'
- 2 'elroy'
- 3 'judy'
-
-=head1 CODE EXAMPLES
-
-Presented with little comment (these will get their own manpages someday)
-here are short code examples illustrating access of various
-types of data structures.
-
-=head1 ARRAYS OF ARRAYS
-X<array of arrays> X<AoA>
-
-=head2 Declaration of an ARRAY OF ARRAYS
-
- @AoA = (
- [ "fred", "barney" ],
- [ "george", "jane", "elroy" ],
- [ "homer", "marge", "bart" ],
- );
-
-=head2 Generation of an ARRAY OF ARRAYS
-
- # reading from file
- while ( <> ) {
- push @AoA, [ split ];
- }
-
- # calling a function
- for $i ( 1 .. 10 ) {
- $AoA[$i] = [ somefunc($i) ];
- }
-
- # using temp vars
- for $i ( 1 .. 10 ) {
- @tmp = somefunc($i);
- $AoA[$i] = [ @tmp ];
- }
-
- # add to an existing row
- push @{ $AoA[0] }, "wilma", "betty";
-
-=head2 Access and Printing of an ARRAY OF ARRAYS
-
- # one element
- $AoA[0][0] = "Fred";
-
- # another element
- $AoA[1][1] =~ s/(\w)/\u$1/;
-
- # print the whole thing with refs
- for $aref ( @AoA ) {
- print "\t [ @$aref ],\n";
- }
-
- # print the whole thing with indices
- for $i ( 0 .. $#AoA ) {
- print "\t [ @{$AoA[$i]} ],\n";
- }
-
- # print the whole thing one at a time
- for $i ( 0 .. $#AoA ) {
- for $j ( 0 .. $#{ $AoA[$i] } ) {
- print "elt $i $j is $AoA[$i][$j]\n";
- }
- }
-
-=head1 HASHES OF ARRAYS
-X<hash of arrays> X<HoA>
-
-=head2 Declaration of a HASH OF ARRAYS
-
- %HoA = (
- flintstones => [ "fred", "barney" ],
- jetsons => [ "george", "jane", "elroy" ],
- simpsons => [ "homer", "marge", "bart" ],
- );
-
-=head2 Generation of a HASH OF ARRAYS
-
- # reading from file
- # flintstones: fred barney wilma dino
- while ( <> ) {
- next unless s/^(.*?):\s*//;
- $HoA{$1} = [ split ];
- }
-
- # reading from file; more temps
- # flintstones: fred barney wilma dino
- while ( $line = <> ) {
- ($who, $rest) = split /:\s*/, $line, 2;
- @fields = split ' ', $rest;
- $HoA{$who} = [ @fields ];
- }
-
- # calling a function that returns a list
- for $group ( "simpsons", "jetsons", "flintstones" ) {
- $HoA{$group} = [ get_family($group) ];
- }
-
- # likewise, but using temps
- for $group ( "simpsons", "jetsons", "flintstones" ) {
- @members = get_family($group);
- $HoA{$group} = [ @members ];
- }
-
- # append new members to an existing family
- push @{ $HoA{"flintstones"} }, "wilma", "betty";
-
-=head2 Access and Printing of a HASH OF ARRAYS
-
- # one element
- $HoA{flintstones}[0] = "Fred";
-
- # another element
- $HoA{simpsons}[1] =~ s/(\w)/\u$1/;
-
- # print the whole thing
- foreach $family ( keys %HoA ) {
- print "$family: @{ $HoA{$family} }\n"
- }
-
- # print the whole thing with indices
- foreach $family ( keys %HoA ) {
- print "family: ";
- foreach $i ( 0 .. $#{ $HoA{$family} } ) {
- print " $i = $HoA{$family}[$i]";
- }
- print "\n";
- }
-
- # print the whole thing sorted by number of members
- foreach $family ( sort { @{$HoA{$b}} <=> @{$HoA{$a}} } keys %HoA ) {
- print "$family: @{ $HoA{$family} }\n"
- }
-
- # print the whole thing sorted by number of members and name
- foreach $family ( sort {
- @{$HoA{$b}} <=> @{$HoA{$a}}
- ||
- $a cmp $b
- } keys %HoA )
- {
- print "$family: ", join(", ", sort @{ $HoA{$family} }), "\n";
- }
-
-=head1 ARRAYS OF HASHES
-X<array of hashes> X<AoH>
-
-=head2 Declaration of an ARRAY OF HASHES
-
- @AoH = (
- {
- Lead => "fred",
- Friend => "barney",
- },
- {
- Lead => "george",
- Wife => "jane",
- Son => "elroy",
- },
- {
- Lead => "homer",
- Wife => "marge",
- Son => "bart",
- }
- );
-
-=head2 Generation of an ARRAY OF HASHES
-
- # reading from file
- # format: LEAD=fred FRIEND=barney
- while ( <> ) {
- $rec = {};
- for $field ( split ) {
- ($key, $value) = split /=/, $field;
- $rec->{$key} = $value;
- }
- push @AoH, $rec;
- }
-
-
- # reading from file
- # format: LEAD=fred FRIEND=barney
- # no temp
- while ( <> ) {
- push @AoH, { split /[\s+=]/ };
- }
-
- # calling a function that returns a key/value pair list, like
- # "lead","fred","daughter","pebbles"
- while ( %fields = getnextpairset() ) {
- push @AoH, { %fields };
- }
-
- # likewise, but using no temp vars
- while (<>) {
- push @AoH, { parsepairs($_) };
- }
-
- # add key/value to an element
- $AoH[0]{pet} = "dino";
- $AoH[2]{pet} = "santa's little helper";
-
-=head2 Access and Printing of an ARRAY OF HASHES
-
- # one element
- $AoH[0]{lead} = "fred";
-
- # another element
- $AoH[1]{lead} =~ s/(\w)/\u$1/;
-
- # print the whole thing with refs
- for $href ( @AoH ) {
- print "{ ";
- for $role ( keys %$href ) {
- print "$role=$href->{$role} ";
- }
- print "}\n";
- }
-
- # print the whole thing with indices
- for $i ( 0 .. $#AoH ) {
- print "$i is { ";
- for $role ( keys %{ $AoH[$i] } ) {
- print "$role=$AoH[$i]{$role} ";
- }
- print "}\n";
- }
-
- # print the whole thing one at a time
- for $i ( 0 .. $#AoH ) {
- for $role ( keys %{ $AoH[$i] } ) {
- print "elt $i $role is $AoH[$i]{$role}\n";
- }
- }
-
-=head1 HASHES OF HASHES
-X<hash of hashes> X<HoH>
-
-=head2 Declaration of a HASH OF HASHES
-
- %HoH = (
- flintstones => {
- lead => "fred",
- pal => "barney",
- },
- jetsons => {
- lead => "george",
- wife => "jane",
- "his boy" => "elroy",
- },
- simpsons => {
- lead => "homer",
- wife => "marge",
- kid => "bart",
- },
- );
-
-=head2 Generation of a HASH OF HASHES
-
- # reading from file
- # flintstones: lead=fred pal=barney wife=wilma pet=dino
- while ( <> ) {
- next unless s/^(.*?):\s*//;
- $who = $1;
- for $field ( split ) {
- ($key, $value) = split /=/, $field;
- $HoH{$who}{$key} = $value;
- }
-
-
- # reading from file; more temps
- while ( <> ) {
- next unless s/^(.*?):\s*//;
- $who = $1;
- $rec = {};
- $HoH{$who} = $rec;
- for $field ( split ) {
- ($key, $value) = split /=/, $field;
- $rec->{$key} = $value;
- }
- }
-
- # calling a function that returns a key,value hash
- for $group ( "simpsons", "jetsons", "flintstones" ) {
- $HoH{$group} = { get_family($group) };
- }
-
- # likewise, but using temps
- for $group ( "simpsons", "jetsons", "flintstones" ) {
- %members = get_family($group);
- $HoH{$group} = { %members };
- }
-
- # append new members to an existing family
- %new_folks = (
- wife => "wilma",
- pet => "dino",
- );
-
- for $what (keys %new_folks) {
- $HoH{flintstones}{$what} = $new_folks{$what};
- }
-
-=head2 Access and Printing of a HASH OF HASHES
-
- # one element
- $HoH{flintstones}{wife} = "wilma";
-
- # another element
- $HoH{simpsons}{lead} =~ s/(\w)/\u$1/;
-
- # print the whole thing
- foreach $family ( keys %HoH ) {
- print "$family: { ";
- for $role ( keys %{ $HoH{$family} } ) {
- print "$role=$HoH{$family}{$role} ";
- }
- print "}\n";
- }
-
- # print the whole thing somewhat sorted
- foreach $family ( sort keys %HoH ) {
- print "$family: { ";
- for $role ( sort keys %{ $HoH{$family} } ) {
- print "$role=$HoH{$family}{$role} ";
- }
- print "}\n";
- }
-
-
- # print the whole thing sorted by number of members
- foreach $family ( sort { keys %{$HoH{$b}} <=> keys %{$HoH{$a}} } keys %HoH ) {
- print "$family: { ";
- for $role ( sort keys %{ $HoH{$family} } ) {
- print "$role=$HoH{$family}{$role} ";
- }
- print "}\n";
- }
-
- # establish a sort order (rank) for each role
- $i = 0;
- for ( qw(lead wife son daughter pal pet) ) { $rank{$_} = ++$i }
-
- # now print the whole thing sorted by number of members
- foreach $family ( sort { keys %{ $HoH{$b} } <=> keys %{ $HoH{$a} } } keys %HoH ) {
- print "$family: { ";
- # and print these according to rank order
- for $role ( sort { $rank{$a} <=> $rank{$b} } keys %{ $HoH{$family} } ) {
- print "$role=$HoH{$family}{$role} ";
- }
- print "}\n";
- }
-
-
-=head1 MORE ELABORATE RECORDS
-X<record> X<structure> X<struct>
-
-=head2 Declaration of MORE ELABORATE RECORDS
-
-Here's a sample showing how to create and use a record whose fields are of
-many different sorts:
-
- $rec = {
- TEXT => $string,
- SEQUENCE => [ @old_values ],
- LOOKUP => { %some_table },
- THATCODE => \&some_function,
- THISCODE => sub { $_[0] ** $_[1] },
- HANDLE => \*STDOUT,
- };
-
- print $rec->{TEXT};
-
- print $rec->{SEQUENCE}[0];
- $last = pop @ { $rec->{SEQUENCE} };
-
- print $rec->{LOOKUP}{"key"};
- ($first_k, $first_v) = each %{ $rec->{LOOKUP} };
-
- $answer = $rec->{THATCODE}->($arg);
- $answer = $rec->{THISCODE}->($arg1, $arg2);
-
- # careful of extra block braces on fh ref
- print { $rec->{HANDLE} } "a string\n";
-
- use FileHandle;
- $rec->{HANDLE}->autoflush(1);
- $rec->{HANDLE}->print(" a string\n");
-
-=head2 Declaration of a HASH OF COMPLEX RECORDS
-
- %TV = (
- flintstones => {
- series => "flintstones",
- nights => [ qw(monday thursday friday) ],
- members => [
- { name => "fred", role => "lead", age => 36, },
- { name => "wilma", role => "wife", age => 31, },
- { name => "pebbles", role => "kid", age => 4, },
- ],
- },
-
- jetsons => {
- series => "jetsons",
- nights => [ qw(wednesday saturday) ],
- members => [
- { name => "george", role => "lead", age => 41, },
- { name => "jane", role => "wife", age => 39, },
- { name => "elroy", role => "kid", age => 9, },
- ],
- },
-
- simpsons => {
- series => "simpsons",
- nights => [ qw(monday) ],
- members => [
- { name => "homer", role => "lead", age => 34, },
- { name => "marge", role => "wife", age => 37, },
- { name => "bart", role => "kid", age => 11, },
- ],
- },
- );
-
-=head2 Generation of a HASH OF COMPLEX RECORDS
-
- # reading from file
- # this is most easily done by having the file itself be
- # in the raw data format as shown above. perl is happy
- # to parse complex data structures if declared as data, so
- # sometimes it's easiest to do that
-
- # here's a piece by piece build up
- $rec = {};
- $rec->{series} = "flintstones";
- $rec->{nights} = [ find_days() ];
-
- @members = ();
- # assume this file in field=value syntax
- while (<>) {
- %fields = split /[\s=]+/;
- push @members, { %fields };
- }
- $rec->{members} = [ @members ];
-
- # now remember the whole thing
- $TV{ $rec->{series} } = $rec;
-
- ###########################################################
- # now, you might want to make interesting extra fields that
- # include pointers back into the same data structure so if
- # change one piece, it changes everywhere, like for example
- # if you wanted a {kids} field that was a reference
- # to an array of the kids' records without having duplicate
- # records and thus update problems.
- ###########################################################
- foreach $family (keys %TV) {
- $rec = $TV{$family}; # temp pointer
- @kids = ();
- for $person ( @{ $rec->{members} } ) {
- if ($person->{role} =~ /kid|son|daughter/) {
- push @kids, $person;
- }
- }
- # REMEMBER: $rec and $TV{$family} point to same data!!
- $rec->{kids} = [ @kids ];
- }
-
- # you copied the array, but the array itself contains pointers
- # to uncopied objects. this means that if you make bart get
- # older via
-
- $TV{simpsons}{kids}[0]{age}++;
-
- # then this would also change in
- print $TV{simpsons}{members}[2]{age};
-
- # because $TV{simpsons}{kids}[0] and $TV{simpsons}{members}[2]
- # both point to the same underlying anonymous hash table
-
- # print the whole thing
- foreach $family ( keys %TV ) {
- print "the $family";
- print " is on during @{ $TV{$family}{nights} }\n";
- print "its members are:\n";
- for $who ( @{ $TV{$family}{members} } ) {
- print " $who->{name} ($who->{role}), age $who->{age}\n";
- }
- print "it turns out that $TV{$family}{lead} has ";
- print scalar ( @{ $TV{$family}{kids} } ), " kids named ";
- print join (", ", map { $_->{name} } @{ $TV{$family}{kids} } );
- print "\n";
- }
-
-=head1 Database Ties
-
-You cannot easily tie a multilevel data structure (such as a hash of
-hashes) to a dbm file. The first problem is that all but GDBM and
-Berkeley DB have size limitations, but beyond that, you also have problems
-with how references are to be represented on disk. One experimental
-module that does partially attempt to address this need is the MLDBM
-module. Check your nearest CPAN site as described in L<perlmodlib> for
-source code to MLDBM.
-
-=head1 SEE ALSO
-
-L<perlref>, L<perllol>, L<perldata>, L<perlobj>
-
-=head1 AUTHOR
-
-Tom Christiansen <F<tchrist@perl.com>>
-
-Last update:
-Wed Oct 23 04:57:50 MET DST 1996
diff --git a/Master/tlpkg/tlperl/lib/pods/perldtrace.pod b/Master/tlpkg/tlperl/lib/pods/perldtrace.pod
deleted file mode 100644
index 39551e17490..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perldtrace.pod
+++ /dev/null
@@ -1,179 +0,0 @@
-=head1 NAME
-
-perldtrace - Perl's support for DTrace
-
-=head1 SYNOPSIS
-
- # dtrace -Zn 'perl::sub-entry, perl::sub-return { trace(copyinstr(arg0)) }'
- dtrace: description 'perl::sub-entry, perl::sub-return ' matched 10 probes
-
- # perl -E 'sub outer { inner(@_) } sub inner { say shift } outer("hello")'
- hello
-
- (dtrace output)
- CPU ID FUNCTION:NAME
- 0 75915 Perl_pp_entersub:sub-entry BEGIN
- 0 75915 Perl_pp_entersub:sub-entry import
- 0 75922 Perl_pp_leavesub:sub-return import
- 0 75922 Perl_pp_leavesub:sub-return BEGIN
- 0 75915 Perl_pp_entersub:sub-entry outer
- 0 75915 Perl_pp_entersub:sub-entry inner
- 0 75922 Perl_pp_leavesub:sub-return inner
- 0 75922 Perl_pp_leavesub:sub-return outer
-
-=head1 DESCRIPTION
-
-DTrace is a framework for comprehensive system- and application-level
-tracing. Perl is a DTrace I<provider>, meaning it exposes several
-I<probes> for instrumentation. You can use these in conjunction
-with kernel-level probes, as well as probes from other providers
-such as MySQL, in order to diagnose software defects, or even just
-your application's bottlenecks.
-
-Perl must be compiled with the C<-Dusedtrace> option in order to
-make use of the provided probes. While DTrace aims to have no
-overhead when its instrumentation is not active, Perl's support
-itself cannot uphold that guarantee, so it is built without DTrace
-probes under most systems. One notable exception is that Mac OS X
-ships a F</usr/bin/perl> with DTrace support enabled.
-
-=head1 HISTORY
-
-=over 4
-
-=item 5.10.1
-
-Perl's initial DTrace support was added, providing C<sub-entry> and
-C<sub-return> probes.
-
-=item 5.14.0
-
-The C<sub-entry> and C<sub-return> probes gain a fourth argument: the
-package name of the function.
-
-=item 5.16.0
-
-The C<phase-change> probe was added.
-
-=back
-
-=head1 PROBES
-
-=over 4
-
-=item sub-entry(SUBNAME, FILE, LINE, PACKAGE)
-
-Traces the entry of any subroutine. Note that all of the variables
-refer to the subroutine that is being invoked; there is currently
-no way to get ahold of any information about the subroutine's
-I<caller> from a DTrace action.
-
- :*perl*::sub-entry {
- printf("%s::%s entered at %s line %d\n",
- copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg0);
- }
-
-=item sub-return(SUBNAME, FILE, LINE, PACKAGE)
-
-Traces the exit of any subroutine. Note that all of the variables
-refer to the subroutine that is returning; there is currently no
-way to get ahold of any information about the subroutine's I<caller>
-from a DTrace action.
-
- :*perl*::sub-return {
- printf("%s::%s returned at %s line %d\n",
- copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg0);
- }
-
-=item phase-change(NEWPHASE, OLDPHASE)
-
-Traces changes to Perl's interpreter state. You can internalize this
-as tracing changes to Perl's C<${^GLOBAL_PHASE}> variable, especially
-since the values for C<NEWPHASE> and C<OLDPHASE> are the strings that
-C<${^GLOBAL_PHASE}> reports.
-
- :*perl*::phase-change {
- printf("Phase changed from %s to %s\n",
- copyinstr(arg1), copyinstr(arg0));
- }
-
-=back
-
-=head1 EXAMPLES
-
-=over 4
-
-=item Most frequently called functions
-
- # dtrace -qZn 'sub-entry { @[strjoin(strjoin(copyinstr(arg3),"::"),copyinstr(arg0))] = count() } END {trunc(@, 10)}'
-
- Class::MOP::Attribute::slots 400
- Try::Tiny::catch 411
- Try::Tiny::try 411
- Class::MOP::Instance::inline_slot_access 451
- Class::MOP::Class::Immutable::Trait:::around 472
- Class::MOP::Mixin::AttributeCore::has_initializer 496
- Class::MOP::Method::Wrapped::__ANON__ 544
- Class::MOP::Package::_package_stash 737
- Class::MOP::Class::initialize 1128
- Class::MOP::get_metaclass_by_name 1204
-
-=item Trace function calls
-
- # dtrace -qFZn 'sub-entry, sub-return { trace(copyinstr(arg0)) }'
-
- 0 -> Perl_pp_entersub BEGIN
- 0 <- Perl_pp_leavesub BEGIN
- 0 -> Perl_pp_entersub BEGIN
- 0 -> Perl_pp_entersub import
- 0 <- Perl_pp_leavesub import
- 0 <- Perl_pp_leavesub BEGIN
- 0 -> Perl_pp_entersub BEGIN
- 0 -> Perl_pp_entersub dress
- 0 <- Perl_pp_leavesub dress
- 0 -> Perl_pp_entersub dirty
- 0 <- Perl_pp_leavesub dirty
- 0 -> Perl_pp_entersub whiten
- 0 <- Perl_pp_leavesub whiten
- 0 <- Perl_dounwind BEGIN
-
-=item Function calls during interpreter cleanup
-
- # dtrace -Zn 'phase-change /copyinstr(arg0) == "END"/ { self->ending = 1 } sub-entry /self->ending/ { trace(copyinstr(arg0)) }'
-
- CPU ID FUNCTION:NAME
- 1 77214 Perl_pp_entersub:sub-entry END
- 1 77214 Perl_pp_entersub:sub-entry END
- 1 77214 Perl_pp_entersub:sub-entry cleanup
- 1 77214 Perl_pp_entersub:sub-entry _force_writable
- 1 77214 Perl_pp_entersub:sub-entry _force_writable
-
-=item System calls at compile time
-
- # dtrace -qZn 'phase-change /copyinstr(arg0) == "START"/ { self->interesting = 1 } phase-change /copyinstr(arg0) == "RUN"/ { self->interesting = 0 } syscall::: /self->interesting/ { @[probefunc] = count() } END { trunc(@, 3) }'
-
- lseek 310
- read 374
- stat64 1056
-
-=back
-
-=head1 REFERENCES
-
-=over 4
-
-=item DTrace User Guide
-
-L<http://download.oracle.com/docs/cd/E19082-01/819-3620/index.html>
-
-=item DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD
-
-L<http://www.amazon.com/DTrace-Dynamic-Tracing-Solaris-FreeBSD/dp/0132091518/>
-
-=back
-
-=head1 AUTHORS
-
-Shawn M Moore C<sartak@gmail.com>
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlebcdic.pod b/Master/tlpkg/tlperl/lib/pods/perlebcdic.pod
deleted file mode 100644
index ecd0676415f..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlebcdic.pod
+++ /dev/null
@@ -1,1446 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perlebcdic - Considerations for running Perl on EBCDIC platforms
-
-=head1 DESCRIPTION
-
-An exploration of some of the issues facing Perl programmers
-on EBCDIC based computers. We do not cover localization,
-internationalization, or multi-byte character set issues other
-than some discussion of UTF-8 and UTF-EBCDIC.
-
-Portions that are still incomplete are marked with XXX.
-
-Perl used to work on EBCDIC machines, but there are now areas of the code where
-it doesn't. If you want to use Perl on an EBCDIC machine, please let us know
-by sending mail to perlbug@perl.org
-
-=head1 COMMON CHARACTER CODE SETS
-
-=head2 ASCII
-
-The American Standard Code for Information Interchange (ASCII or US-ASCII) is a
-set of
-integers running from 0 to 127 (decimal) that imply character
-interpretation by the display and other systems of computers.
-The range 0..127 can be covered by setting the bits in a 7-bit binary
-digit, hence the set is sometimes referred to as "7-bit ASCII".
-ASCII was described by the American National Standards Institute
-document ANSI X3.4-1986. It was also described by ISO 646:1991
-(with localization for currency symbols). The full ASCII set is
-given in the table below as the first 128 elements. Languages that
-can be written adequately with the characters in ASCII include
-English, Hawaiian, Indonesian, Swahili and some Native American
-languages.
-
-There are many character sets that extend the range of integers
-from 0..2**7-1 up to 2**8-1, or 8 bit bytes (octets if you prefer).
-One common one is the ISO 8859-1 character set.
-
-=head2 ISO 8859
-
-The ISO 8859-$n are a collection of character code sets from the
-International Organization for Standardization (ISO) each of which
-adds characters to the ASCII set that are typically found in European
-languages many of which are based on the Roman, or Latin, alphabet.
-
-=head2 Latin 1 (ISO 8859-1)
-
-A particular 8-bit extension to ASCII that includes grave and acute
-accented Latin characters. Languages that can employ ISO 8859-1
-include all the languages covered by ASCII as well as Afrikaans,
-Albanian, Basque, Catalan, Danish, Faroese, Finnish, Norwegian,
-Portuguese, Spanish, and Swedish. Dutch is covered albeit without
-the ij ligature. French is covered too but without the oe ligature.
-German can use ISO 8859-1 but must do so without German-style
-quotation marks. This set is based on Western European extensions
-to ASCII and is commonly encountered in world wide web work.
-In IBM character code set identification terminology ISO 8859-1 is
-also known as CCSID 819 (or sometimes 0819 or even 00819).
-
-=head2 EBCDIC
-
-The Extended Binary Coded Decimal Interchange Code refers to a
-large collection of single- and multi-byte coded character sets that are
-different from ASCII or ISO 8859-1 and are all slightly different from each
-other; they typically run on host computers. The EBCDIC encodings derive from
-8-bit byte extensions of Hollerith punched card encodings. The layout on the
-cards was such that high bits were set for the upper and lower case alphabet
-characters [a-z] and [A-Z], but there were gaps within each Latin alphabet
-range.
-
-Some IBM EBCDIC character sets may be known by character code set
-identification numbers (CCSID numbers) or code page numbers.
-
-Perl can be compiled on platforms that run any of three commonly used EBCDIC
-character sets, listed below.
-
-=head2 The 13 variant characters
-
-Among IBM EBCDIC character code sets there are 13 characters that
-are often mapped to different integer values. Those characters
-are known as the 13 "variant" characters and are:
-
- \ [ ] { } ^ ~ ! # | $ @ `
-
-When Perl is compiled for a platform, it looks at some of these characters to
-guess which EBCDIC character set the platform uses, and adapts itself
-accordingly to that platform. If the platform uses a character set that is not
-one of the three Perl knows about, Perl will either fail to compile, or
-mistakenly and silently choose one of the three.
-They are:
-
-=head2 0037
-
-Character code set ID 0037 is a mapping of the ASCII plus Latin-1
-characters (i.e. ISO 8859-1) to an EBCDIC set. 0037 is used
-in North American English locales on the OS/400 operating system
-that runs on AS/400 computers. CCSID 0037 differs from ISO 8859-1
-in 237 places, in other words they agree on only 19 code point values.
-
-=head2 1047
-
-Character code set ID 1047 is also a mapping of the ASCII plus
-Latin-1 characters (i.e. ISO 8859-1) to an EBCDIC set. 1047 is
-used under Unix System Services for OS/390 or z/OS, and OpenEdition
-for VM/ESA. CCSID 1047 differs from CCSID 0037 in eight places.
-
-=head2 POSIX-BC
-
-The EBCDIC code page in use on Siemens' BS2000 system is distinct from
-1047 and 0037. It is identified below as the POSIX-BC set.
-
-=head2 Unicode code points versus EBCDIC code points
-
-In Unicode terminology a I<code point> is the number assigned to a
-character: for example, in EBCDIC the character "A" is usually assigned
-the number 193. In Unicode the character "A" is assigned the number 65.
-This causes a problem with the semantics of the pack/unpack "U", which
-are supposed to pack Unicode code points to characters and back to numbers.
-The problem is: which code points to use for code points less than 256?
-(for 256 and over there's no problem: Unicode code points are used)
-In EBCDIC, for the low 256 the EBCDIC code points are used. This
-means that the equivalences
-
- pack("U", ord($character)) eq $character
- unpack("U", $character) == ord $character
-
-will hold. (If Unicode code points were applied consistently over
-all the possible code points, pack("U",ord("A")) would in EBCDIC
-equal I<A with acute> or chr(101), and unpack("U", "A") would equal
-65, or I<non-breaking space>, not 193, or ord "A".)
-
-=head2 Remaining Perl Unicode problems in EBCDIC
-
-=over 4
-
-=item *
-
-Many of the remaining problems seem to be related to case-insensitive matching
-
-=item *
-
-The extensions Unicode::Collate and Unicode::Normalized are not
-supported under EBCDIC, likewise for the encoding pragma.
-
-=back
-
-=head2 Unicode and UTF
-
-UTF stands for C<Unicode Transformation Format>.
-UTF-8 is an encoding of Unicode into a sequence of 8-bit byte chunks, based on
-ASCII and Latin-1.
-The length of a sequence required to represent a Unicode code point
-depends on the ordinal number of that code point,
-with larger numbers requiring more bytes.
-UTF-EBCDIC is like UTF-8, but based on EBCDIC.
-
-You may see the term C<invariant> character or code point.
-This simply means that the character has the same numeric
-value when encoded as when not.
-(Note that this is a very different concept from L</The 13 variant characters>
-mentioned above.)
-For example, the ordinal value of 'A' is 193 in most EBCDIC code pages,
-and also is 193 when encoded in UTF-EBCDIC.
-All variant code points occupy at least two bytes when encoded.
-In UTF-8, the code points corresponding to the lowest 128
-ordinal numbers (0 - 127: the ASCII characters) are invariant.
-In UTF-EBCDIC, there are 160 invariant characters.
-(If you care, the EBCDIC invariants are those characters
-which have ASCII equivalents, plus those that correspond to
-the C1 controls (80..9f on ASCII platforms).)
-
-A string encoded in UTF-EBCDIC may be longer (but never shorter) than
-one encoded in UTF-8.
-
-=head2 Using Encode
-
-Starting from Perl 5.8 you can use the standard new module Encode
-to translate from EBCDIC to Latin-1 code points.
-Encode knows about more EBCDIC character sets than Perl can currently
-be compiled to run on.
-
- use Encode 'from_to';
-
- my %ebcdic = ( 176 => 'cp37', 95 => 'cp1047', 106 => 'posix-bc' );
-
- # $a is in EBCDIC code points
- from_to($a, $ebcdic{ord '^'}, 'latin1');
- # $a is ISO 8859-1 code points
-
-and from Latin-1 code points to EBCDIC code points
-
- use Encode 'from_to';
-
- my %ebcdic = ( 176 => 'cp37', 95 => 'cp1047', 106 => 'posix-bc' );
-
- # $a is ISO 8859-1 code points
- from_to($a, 'latin1', $ebcdic{ord '^'});
- # $a is in EBCDIC code points
-
-For doing I/O it is suggested that you use the autotranslating features
-of PerlIO, see L<perluniintro>.
-
-Since version 5.8 Perl uses the new PerlIO I/O library. This enables
-you to use different encodings per IO channel. For example you may use
-
- use Encode;
- open($f, ">:encoding(ascii)", "test.ascii");
- print $f "Hello World!\n";
- open($f, ">:encoding(cp37)", "test.ebcdic");
- print $f "Hello World!\n";
- open($f, ">:encoding(latin1)", "test.latin1");
- print $f "Hello World!\n";
- open($f, ">:encoding(utf8)", "test.utf8");
- print $f "Hello World!\n";
-
-to get four files containing "Hello World!\n" in ASCII, CP 0037 EBCDIC,
-ISO 8859-1 (Latin-1) (in this example identical to ASCII since only ASCII
-characters were printed), and
-UTF-EBCDIC (in this example identical to normal EBCDIC since only characters
-that don't differ between EBCDIC and UTF-EBCDIC were printed). See the
-documentation of Encode::PerlIO for details.
-
-As the PerlIO layer uses raw IO (bytes) internally, all this totally
-ignores things like the type of your filesystem (ASCII or EBCDIC).
-
-=head1 SINGLE OCTET TABLES
-
-The following tables list the ASCII and Latin 1 ordered sets including
-the subsets: C0 controls (0..31), ASCII graphics (32..7e), delete (7f),
-C1 controls (80..9f), and Latin-1 (a.k.a. ISO 8859-1) (a0..ff). In the
-table non-printing control character names as well as the Latin 1
-extensions to ASCII have been labelled with character names roughly
-corresponding to I<The Unicode Standard, Version 3.0> albeit with
-substitutions such as s/LATIN// and s/VULGAR// in all cases,
-s/CAPITAL LETTER// in some cases, and s/SMALL LETTER ([A-Z])/\l$1/
-in some other cases. The "names" of the controls listed here are
-the Unicode Version 1 names, except for the few that don't have names, in which
-case the names in the Wikipedia article were used
-(L<http://en.wikipedia.org/wiki/C0_and_C1_control_codes>).
-The differences between the 0037 and 1047 sets are
-flagged with ***. The differences between the 1047 and POSIX-BC sets
-are flagged with ###. All ord() numbers listed are decimal. If you
-would rather see this table listing octal values then run the table
-(that is, the pod version of this document since this recipe may not
-work with a pod2_other_format translation) through:
-
-=over 4
-
-=item recipe 0
-
-=back
-
- perl -ne 'if(/(.{43})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)/)' \
- -e '{printf("%s%-9.03o%-9.03o%-9.03o%.03o\n",$1,$2,$3,$4,$5)}' \
- perlebcdic.pod
-
-If you want to retain the UTF-x code points then in script form you
-might want to write:
-
-=over 4
-
-=item recipe 1
-
-=back
-
- open(FH,"<perlebcdic.pod") or die "Could not open perlebcdic.pod: $!";
- while (<FH>) {
- if (/(.{43})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\.?(\d*)\s+(\d+)\.?(\d*)/)
- {
- if ($7 ne '' && $9 ne '') {
- printf(
- "%s%-9.03o%-9.03o%-9.03o%-9.03o%-3o.%-5o%-3o.%.03o\n",
- $1,$2,$3,$4,$5,$6,$7,$8,$9);
- }
- elsif ($7 ne '') {
- printf("%s%-9.03o%-9.03o%-9.03o%-9.03o%-3o.%-5o%.03o\n",
- $1,$2,$3,$4,$5,$6,$7,$8);
- }
- else {
- printf("%s%-9.03o%-9.03o%-9.03o%-9.03o%-9.03o%.03o\n",
- $1,$2,$3,$4,$5,$6,$8);
- }
- }
- }
-
-If you would rather see this table listing hexadecimal values then
-run the table through:
-
-=over 4
-
-=item recipe 2
-
-=back
-
- perl -ne 'if(/(.{43})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)/)' \
- -e '{printf("%s%-9.02X%-9.02X%-9.02X%.02X\n",$1,$2,$3,$4,$5)}' \
- perlebcdic.pod
-
-Or, in order to retain the UTF-x code points in hexadecimal:
-
-=over 4
-
-=item recipe 3
-
-=back
-
- open(FH,"<perlebcdic.pod") or die "Could not open perlebcdic.pod: $!";
- while (<FH>) {
- if (/(.{43})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\.?(\d*)\s+(\d+)\.?(\d*)/)
- {
- if ($7 ne '' && $9 ne '') {
- printf(
- "%s%-9.02X%-9.02X%-9.02X%-9.02X%-2X.%-6.02X%02X.%02X\n",
- $1,$2,$3,$4,$5,$6,$7,$8,$9);
- }
- elsif ($7 ne '') {
- printf("%s%-9.02X%-9.02X%-9.02X%-9.02X%-2X.%-6.02X%02X\n",
- $1,$2,$3,$4,$5,$6,$7,$8);
- }
- else {
- printf("%s%-9.02X%-9.02X%-9.02X%-9.02X%-9.02X%02X\n",
- $1,$2,$3,$4,$5,$6,$8);
- }
- }
- }
-
-
- ISO 8859-1 CCSID CCSID CCSID 1047
- chr CCSID 0819 0037 1047 POSIX-BC UTF-8 UTF-EBCDIC
- ----------------------------------------------------------------------------------------------
- <NULL> 0 0 0 0 0 0
- <START OF HEADING> 1 1 1 1 1 1
- <START OF TEXT> 2 2 2 2 2 2
- <END OF TEXT> 3 3 3 3 3 3
- <END OF TRANSMISSION> 4 55 55 55 4 55
- <ENQUIRY> 5 45 45 45 5 45
- <ACKNOWLEDGE> 6 46 46 46 6 46
- <BELL> 7 47 47 47 7 47
- <BACKSPACE> 8 22 22 22 8 22
- <HORIZONTAL TABULATION> 9 5 5 5 9 5
- <LINE FEED> 10 37 21 21 10 21 ***
- <VERTICAL TABULATION> 11 11 11 11 11 11
- <FORM FEED> 12 12 12 12 12 12
- <CARRIAGE RETURN> 13 13 13 13 13 13
- <SHIFT OUT> 14 14 14 14 14 14
- <SHIFT IN> 15 15 15 15 15 15
- <DATA LINK ESCAPE> 16 16 16 16 16 16
- <DEVICE CONTROL ONE> 17 17 17 17 17 17
- <DEVICE CONTROL TWO> 18 18 18 18 18 18
- <DEVICE CONTROL THREE> 19 19 19 19 19 19
- <DEVICE CONTROL FOUR> 20 60 60 60 20 60
- <NEGATIVE ACKNOWLEDGE> 21 61 61 61 21 61
- <SYNCHRONOUS IDLE> 22 50 50 50 22 50
- <END OF TRANSMISSION BLOCK> 23 38 38 38 23 38
- <CANCEL> 24 24 24 24 24 24
- <END OF MEDIUM> 25 25 25 25 25 25
- <SUBSTITUTE> 26 63 63 63 26 63
- <ESCAPE> 27 39 39 39 27 39
- <FILE SEPARATOR> 28 28 28 28 28 28
- <GROUP SEPARATOR> 29 29 29 29 29 29
- <RECORD SEPARATOR> 30 30 30 30 30 30
- <UNIT SEPARATOR> 31 31 31 31 31 31
- <SPACE> 32 64 64 64 32 64
- ! 33 90 90 90 33 90
- " 34 127 127 127 34 127
- # 35 123 123 123 35 123
- $ 36 91 91 91 36 91
- % 37 108 108 108 37 108
- & 38 80 80 80 38 80
- ' 39 125 125 125 39 125
- ( 40 77 77 77 40 77
- ) 41 93 93 93 41 93
- * 42 92 92 92 42 92
- + 43 78 78 78 43 78
- , 44 107 107 107 44 107
- - 45 96 96 96 45 96
- . 46 75 75 75 46 75
- / 47 97 97 97 47 97
- 0 48 240 240 240 48 240
- 1 49 241 241 241 49 241
- 2 50 242 242 242 50 242
- 3 51 243 243 243 51 243
- 4 52 244 244 244 52 244
- 5 53 245 245 245 53 245
- 6 54 246 246 246 54 246
- 7 55 247 247 247 55 247
- 8 56 248 248 248 56 248
- 9 57 249 249 249 57 249
- : 58 122 122 122 58 122
- ; 59 94 94 94 59 94
- < 60 76 76 76 60 76
- = 61 126 126 126 61 126
- > 62 110 110 110 62 110
- ? 63 111 111 111 63 111
- @ 64 124 124 124 64 124
- A 65 193 193 193 65 193
- B 66 194 194 194 66 194
- C 67 195 195 195 67 195
- D 68 196 196 196 68 196
- E 69 197 197 197 69 197
- F 70 198 198 198 70 198
- G 71 199 199 199 71 199
- H 72 200 200 200 72 200
- I 73 201 201 201 73 201
- J 74 209 209 209 74 209
- K 75 210 210 210 75 210
- L 76 211 211 211 76 211
- M 77 212 212 212 77 212
- N 78 213 213 213 78 213
- O 79 214 214 214 79 214
- P 80 215 215 215 80 215
- Q 81 216 216 216 81 216
- R 82 217 217 217 82 217
- S 83 226 226 226 83 226
- T 84 227 227 227 84 227
- U 85 228 228 228 85 228
- V 86 229 229 229 86 229
- W 87 230 230 230 87 230
- X 88 231 231 231 88 231
- Y 89 232 232 232 89 232
- Z 90 233 233 233 90 233
- [ 91 186 173 187 91 173 *** ###
- \ 92 224 224 188 92 224 ###
- ] 93 187 189 189 93 189 ***
- ^ 94 176 95 106 94 95 *** ###
- _ 95 109 109 109 95 109
- ` 96 121 121 74 96 121 ###
- a 97 129 129 129 97 129
- b 98 130 130 130 98 130
- c 99 131 131 131 99 131
- d 100 132 132 132 100 132
- e 101 133 133 133 101 133
- f 102 134 134 134 102 134
- g 103 135 135 135 103 135
- h 104 136 136 136 104 136
- i 105 137 137 137 105 137
- j 106 145 145 145 106 145
- k 107 146 146 146 107 146
- l 108 147 147 147 108 147
- m 109 148 148 148 109 148
- n 110 149 149 149 110 149
- o 111 150 150 150 111 150
- p 112 151 151 151 112 151
- q 113 152 152 152 113 152
- r 114 153 153 153 114 153
- s 115 162 162 162 115 162
- t 116 163 163 163 116 163
- u 117 164 164 164 117 164
- v 118 165 165 165 118 165
- w 119 166 166 166 119 166
- x 120 167 167 167 120 167
- y 121 168 168 168 121 168
- z 122 169 169 169 122 169
- { 123 192 192 251 123 192 ###
- | 124 79 79 79 124 79
- } 125 208 208 253 125 208 ###
- ~ 126 161 161 255 126 161 ###
- <DELETE> 127 7 7 7 127 7
- <PADDING CHARACTER> 128 32 32 32 194.128 32
- <HIGH OCTET PRESET> 129 33 33 33 194.129 33
- <BREAK PERMITTED HERE> 130 34 34 34 194.130 34
- <NO BREAK HERE> 131 35 35 35 194.131 35
- <INDEX> 132 36 36 36 194.132 36
- <NEXT LINE> 133 21 37 37 194.133 37 ***
- <START OF SELECTED AREA> 134 6 6 6 194.134 6
- <END OF SELECTED AREA> 135 23 23 23 194.135 23
- <CHARACTER TABULATION SET> 136 40 40 40 194.136 40
- <CHARACTER TABULATION WITH JUSTIFICATION> 137 41 41 41 194.137 41
- <LINE TABULATION SET> 138 42 42 42 194.138 42
- <PARTIAL LINE FORWARD> 139 43 43 43 194.139 43
- <PARTIAL LINE BACKWARD> 140 44 44 44 194.140 44
- <REVERSE LINE FEED> 141 9 9 9 194.141 9
- <SINGLE SHIFT TWO> 142 10 10 10 194.142 10
- <SINGLE SHIFT THREE> 143 27 27 27 194.143 27
- <DEVICE CONTROL STRING> 144 48 48 48 194.144 48
- <PRIVATE USE ONE> 145 49 49 49 194.145 49
- <PRIVATE USE TWO> 146 26 26 26 194.146 26
- <SET TRANSMIT STATE> 147 51 51 51 194.147 51
- <CANCEL CHARACTER> 148 52 52 52 194.148 52
- <MESSAGE WAITING> 149 53 53 53 194.149 53
- <START OF GUARDED AREA> 150 54 54 54 194.150 54
- <END OF GUARDED AREA> 151 8 8 8 194.151 8
- <START OF STRING> 152 56 56 56 194.152 56
- <SINGLE GRAPHIC CHARACTER INTRODUCER> 153 57 57 57 194.153 57
- <SINGLE CHARACTER INTRODUCER> 154 58 58 58 194.154 58
- <CONTROL SEQUENCE INTRODUCER> 155 59 59 59 194.155 59
- <STRING TERMINATOR> 156 4 4 4 194.156 4
- <OPERATING SYSTEM COMMAND> 157 20 20 20 194.157 20
- <PRIVACY MESSAGE> 158 62 62 62 194.158 62
- <APPLICATION PROGRAM COMMAND> 159 255 255 95 194.159 255 ###
- <NON-BREAKING SPACE> 160 65 65 65 194.160 128.65
- <INVERTED EXCLAMATION MARK> 161 170 170 170 194.161 128.66
- <CENT SIGN> 162 74 74 176 194.162 128.67 ###
- <POUND SIGN> 163 177 177 177 194.163 128.68
- <CURRENCY SIGN> 164 159 159 159 194.164 128.69
- <YEN SIGN> 165 178 178 178 194.165 128.70
- <BROKEN BAR> 166 106 106 208 194.166 128.71 ###
- <SECTION SIGN> 167 181 181 181 194.167 128.72
- <DIAERESIS> 168 189 187 121 194.168 128.73 *** ###
- <COPYRIGHT SIGN> 169 180 180 180 194.169 128.74
- <FEMININE ORDINAL INDICATOR> 170 154 154 154 194.170 128.81
- <LEFT POINTING GUILLEMET> 171 138 138 138 194.171 128.82
- <NOT SIGN> 172 95 176 186 194.172 128.83 *** ###
- <SOFT HYPHEN> 173 202 202 202 194.173 128.84
- <REGISTERED TRADE MARK SIGN> 174 175 175 175 194.174 128.85
- <MACRON> 175 188 188 161 194.175 128.86 ###
- <DEGREE SIGN> 176 144 144 144 194.176 128.87
- <PLUS-OR-MINUS SIGN> 177 143 143 143 194.177 128.88
- <SUPERSCRIPT TWO> 178 234 234 234 194.178 128.89
- <SUPERSCRIPT THREE> 179 250 250 250 194.179 128.98
- <ACUTE ACCENT> 180 190 190 190 194.180 128.99
- <MICRO SIGN> 181 160 160 160 194.181 128.100
- <PARAGRAPH SIGN> 182 182 182 182 194.182 128.101
- <MIDDLE DOT> 183 179 179 179 194.183 128.102
- <CEDILLA> 184 157 157 157 194.184 128.103
- <SUPERSCRIPT ONE> 185 218 218 218 194.185 128.104
- <MASC. ORDINAL INDICATOR> 186 155 155 155 194.186 128.105
- <RIGHT POINTING GUILLEMET> 187 139 139 139 194.187 128.106
- <FRACTION ONE QUARTER> 188 183 183 183 194.188 128.112
- <FRACTION ONE HALF> 189 184 184 184 194.189 128.113
- <FRACTION THREE QUARTERS> 190 185 185 185 194.190 128.114
- <INVERTED QUESTION MARK> 191 171 171 171 194.191 128.115
- <A WITH GRAVE> 192 100 100 100 195.128 138.65
- <A WITH ACUTE> 193 101 101 101 195.129 138.66
- <A WITH CIRCUMFLEX> 194 98 98 98 195.130 138.67
- <A WITH TILDE> 195 102 102 102 195.131 138.68
- <A WITH DIAERESIS> 196 99 99 99 195.132 138.69
- <A WITH RING ABOVE> 197 103 103 103 195.133 138.70
- <CAPITAL LIGATURE AE> 198 158 158 158 195.134 138.71
- <C WITH CEDILLA> 199 104 104 104 195.135 138.72
- <E WITH GRAVE> 200 116 116 116 195.136 138.73
- <E WITH ACUTE> 201 113 113 113 195.137 138.74
- <E WITH CIRCUMFLEX> 202 114 114 114 195.138 138.81
- <E WITH DIAERESIS> 203 115 115 115 195.139 138.82
- <I WITH GRAVE> 204 120 120 120 195.140 138.83
- <I WITH ACUTE> 205 117 117 117 195.141 138.84
- <I WITH CIRCUMFLEX> 206 118 118 118 195.142 138.85
- <I WITH DIAERESIS> 207 119 119 119 195.143 138.86
- <CAPITAL LETTER ETH> 208 172 172 172 195.144 138.87
- <N WITH TILDE> 209 105 105 105 195.145 138.88
- <O WITH GRAVE> 210 237 237 237 195.146 138.89
- <O WITH ACUTE> 211 238 238 238 195.147 138.98
- <O WITH CIRCUMFLEX> 212 235 235 235 195.148 138.99
- <O WITH TILDE> 213 239 239 239 195.149 138.100
- <O WITH DIAERESIS> 214 236 236 236 195.150 138.101
- <MULTIPLICATION SIGN> 215 191 191 191 195.151 138.102
- <O WITH STROKE> 216 128 128 128 195.152 138.103
- <U WITH GRAVE> 217 253 253 224 195.153 138.104 ###
- <U WITH ACUTE> 218 254 254 254 195.154 138.105
- <U WITH CIRCUMFLEX> 219 251 251 221 195.155 138.106 ###
- <U WITH DIAERESIS> 220 252 252 252 195.156 138.112
- <Y WITH ACUTE> 221 173 186 173 195.157 138.113 *** ###
- <CAPITAL LETTER THORN> 222 174 174 174 195.158 138.114
- <SMALL LETTER SHARP S> 223 89 89 89 195.159 138.115
- <a WITH GRAVE> 224 68 68 68 195.160 139.65
- <a WITH ACUTE> 225 69 69 69 195.161 139.66
- <a WITH CIRCUMFLEX> 226 66 66 66 195.162 139.67
- <a WITH TILDE> 227 70 70 70 195.163 139.68
- <a WITH DIAERESIS> 228 67 67 67 195.164 139.69
- <a WITH RING ABOVE> 229 71 71 71 195.165 139.70
- <SMALL LIGATURE ae> 230 156 156 156 195.166 139.71
- <c WITH CEDILLA> 231 72 72 72 195.167 139.72
- <e WITH GRAVE> 232 84 84 84 195.168 139.73
- <e WITH ACUTE> 233 81 81 81 195.169 139.74
- <e WITH CIRCUMFLEX> 234 82 82 82 195.170 139.81
- <e WITH DIAERESIS> 235 83 83 83 195.171 139.82
- <i WITH GRAVE> 236 88 88 88 195.172 139.83
- <i WITH ACUTE> 237 85 85 85 195.173 139.84
- <i WITH CIRCUMFLEX> 238 86 86 86 195.174 139.85
- <i WITH DIAERESIS> 239 87 87 87 195.175 139.86
- <SMALL LETTER eth> 240 140 140 140 195.176 139.87
- <n WITH TILDE> 241 73 73 73 195.177 139.88
- <o WITH GRAVE> 242 205 205 205 195.178 139.89
- <o WITH ACUTE> 243 206 206 206 195.179 139.98
- <o WITH CIRCUMFLEX> 244 203 203 203 195.180 139.99
- <o WITH TILDE> 245 207 207 207 195.181 139.100
- <o WITH DIAERESIS> 246 204 204 204 195.182 139.101
- <DIVISION SIGN> 247 225 225 225 195.183 139.102
- <o WITH STROKE> 248 112 112 112 195.184 139.103
- <u WITH GRAVE> 249 221 221 192 195.185 139.104 ###
- <u WITH ACUTE> 250 222 222 222 195.186 139.105
- <u WITH CIRCUMFLEX> 251 219 219 219 195.187 139.106
- <u WITH DIAERESIS> 252 220 220 220 195.188 139.112
- <y WITH ACUTE> 253 141 141 141 195.189 139.113
- <SMALL LETTER thorn> 254 142 142 142 195.190 139.114
- <y WITH DIAERESIS> 255 223 223 223 195.191 139.115
-
-If you would rather see the above table in CCSID 0037 order rather than
-ASCII + Latin-1 order then run the table through:
-
-=over 4
-
-=item recipe 4
-
-=back
-
- perl \
- -ne 'if(/.{43}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}/)'\
- -e '{push(@l,$_)}' \
- -e 'END{print map{$_->[0]}' \
- -e ' sort{$a->[1] <=> $b->[1]}' \
- -e ' map{[$_,substr($_,52,3)]}@l;}' perlebcdic.pod
-
-If you would rather see it in CCSID 1047 order then change the number
-52 in the last line to 61, like this:
-
-=over 4
-
-=item recipe 5
-
-=back
-
- perl \
- -ne 'if(/.{43}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}/)'\
- -e '{push(@l,$_)}' \
- -e 'END{print map{$_->[0]}' \
- -e ' sort{$a->[1] <=> $b->[1]}' \
- -e ' map{[$_,substr($_,61,3)]}@l;}' perlebcdic.pod
-
-If you would rather see it in POSIX-BC order then change the number
-61 in the last line to 70, like this:
-
-=over 4
-
-=item recipe 6
-
-=back
-
- perl \
- -ne 'if(/.{43}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}/)'\
- -e '{push(@l,$_)}' \
- -e 'END{print map{$_->[0]}' \
- -e ' sort{$a->[1] <=> $b->[1]}' \
- -e ' map{[$_,substr($_,70,3)]}@l;}' perlebcdic.pod
-
-
-=head1 IDENTIFYING CHARACTER CODE SETS
-
-To determine the character set you are running under from perl one
-could use the return value of ord() or chr() to test one or more
-character values. For example:
-
- $is_ascii = "A" eq chr(65);
- $is_ebcdic = "A" eq chr(193);
-
-Also, "\t" is a C<HORIZONTAL TABULATION> character so that:
-
- $is_ascii = ord("\t") == 9;
- $is_ebcdic = ord("\t") == 5;
-
-To distinguish EBCDIC code pages try looking at one or more of
-the characters that differ between them. For example:
-
- $is_ebcdic_37 = "\n" eq chr(37);
- $is_ebcdic_1047 = "\n" eq chr(21);
-
-Or better still choose a character that is uniquely encoded in any
-of the code sets, e.g.:
-
- $is_ascii = ord('[') == 91;
- $is_ebcdic_37 = ord('[') == 186;
- $is_ebcdic_1047 = ord('[') == 173;
- $is_ebcdic_POSIX_BC = ord('[') == 187;
-
-However, it would be unwise to write tests such as:
-
- $is_ascii = "\r" ne chr(13); # WRONG
- $is_ascii = "\n" ne chr(10); # ILL ADVISED
-
-Obviously the first of these will fail to distinguish most ASCII platforms
-from either a CCSID 0037, a 1047, or a POSIX-BC EBCDIC platform since "\r" eq
-chr(13) under all of those coded character sets. But note too that
-because "\n" is chr(13) and "\r" is chr(10) on the Macintosh (which is an
-ASCII platform) the second C<$is_ascii> test will lead to trouble there.
-
-To determine whether or not perl was built under an EBCDIC
-code page you can use the Config module like so:
-
- use Config;
- $is_ebcdic = $Config{'ebcdic'} eq 'define';
-
-=head1 CONVERSIONS
-
-=head2 tr///
-
-In order to convert a string of characters from one character set to
-another a simple list of numbers, such as in the right columns in the
-above table, along with perl's tr/// operator is all that is needed.
-The data in the table are in ASCII/Latin1 order, hence the EBCDIC columns
-provide easy-to-use ASCII/Latin1 to EBCDIC operations that are also easily
-reversed.
-
-For example, to convert ASCII/Latin1 to code page 037 take the output of the
-second numbers column from the output of recipe 2 (modified to add '\'
-characters) and use it in tr/// like so:
-
- $cp_037 =
- '\x00\x01\x02\x03\x37\x2D\x2E\x2F\x16\x05\x25\x0B\x0C\x0D\x0E\x0F' .
- '\x10\x11\x12\x13\x3C\x3D\x32\x26\x18\x19\x3F\x27\x1C\x1D\x1E\x1F' .
- '\x40\x5A\x7F\x7B\x5B\x6C\x50\x7D\x4D\x5D\x5C\x4E\x6B\x60\x4B\x61' .
- '\xF0\xF1\xF2\xF3\xF4\xF5\xF6\xF7\xF8\xF9\x7A\x5E\x4C\x7E\x6E\x6F' .
- '\x7C\xC1\xC2\xC3\xC4\xC5\xC6\xC7\xC8\xC9\xD1\xD2\xD3\xD4\xD5\xD6' .
- '\xD7\xD8\xD9\xE2\xE3\xE4\xE5\xE6\xE7\xE8\xE9\xBA\xE0\xBB\xB0\x6D' .
- '\x79\x81\x82\x83\x84\x85\x86\x87\x88\x89\x91\x92\x93\x94\x95\x96' .
- '\x97\x98\x99\xA2\xA3\xA4\xA5\xA6\xA7\xA8\xA9\xC0\x4F\xD0\xA1\x07' .
- '\x20\x21\x22\x23\x24\x15\x06\x17\x28\x29\x2A\x2B\x2C\x09\x0A\x1B' .
- '\x30\x31\x1A\x33\x34\x35\x36\x08\x38\x39\x3A\x3B\x04\x14\x3E\xFF' .
- '\x41\xAA\x4A\xB1\x9F\xB2\x6A\xB5\xBD\xB4\x9A\x8A\x5F\xCA\xAF\xBC' .
- '\x90\x8F\xEA\xFA\xBE\xA0\xB6\xB3\x9D\xDA\x9B\x8B\xB7\xB8\xB9\xAB' .
- '\x64\x65\x62\x66\x63\x67\x9E\x68\x74\x71\x72\x73\x78\x75\x76\x77' .
- '\xAC\x69\xED\xEE\xEB\xEF\xEC\xBF\x80\xFD\xFE\xFB\xFC\xAD\xAE\x59' .
- '\x44\x45\x42\x46\x43\x47\x9C\x48\x54\x51\x52\x53\x58\x55\x56\x57' .
- '\x8C\x49\xCD\xCE\xCB\xCF\xCC\xE1\x70\xDD\xDE\xDB\xDC\x8D\x8E\xDF';
-
- my $ebcdic_string = $ascii_string;
- eval '$ebcdic_string =~ tr/\000-\377/' . $cp_037 . '/';
-
-To convert from EBCDIC 037 to ASCII just reverse the order of the tr///
-arguments like so:
-
- my $ascii_string = $ebcdic_string;
- eval '$ascii_string =~ tr/' . $cp_037 . '/\000-\377/';
-
-Similarly one could take the output of the third numbers column from recipe 2
-to obtain a C<$cp_1047> table. The fourth numbers column of the output from
-recipe 2 could provide a C<$cp_posix_bc> table suitable for transcoding as
-well.
-
-If you wanted to see the inverse tables, you would first have to sort on the
-desired numbers column as in recipes 4, 5 or 6, then take the output of the
-first numbers column.
-
-=head2 iconv
-
-XPG operability often implies the presence of an I<iconv> utility
-available from the shell or from the C library. Consult your system's
-documentation for information on iconv.
-
-On OS/390 or z/OS see the iconv(1) manpage. One way to invoke the iconv
-shell utility from within perl would be to:
-
- # OS/390 or z/OS example
- $ascii_data = `echo '$ebcdic_data'| iconv -f IBM-1047 -t ISO8859-1`
-
-or the inverse map:
-
- # OS/390 or z/OS example
- $ebcdic_data = `echo '$ascii_data'| iconv -f ISO8859-1 -t IBM-1047`
-
-For other perl-based conversion options see the Convert::* modules on CPAN.
-
-=head2 C RTL
-
-The OS/390 and z/OS C run-time libraries provide _atoe() and _etoa() functions.
-
-=head1 OPERATOR DIFFERENCES
-
-The C<..> range operator treats certain character ranges with
-care on EBCDIC platforms. For example the following array
-will have twenty six elements on either an EBCDIC platform
-or an ASCII platform:
-
- @alphabet = ('A'..'Z'); # $#alphabet == 25
-
-The bitwise operators such as & ^ | may return different results
-when operating on string or character data in a perl program running
-on an EBCDIC platform than when run on an ASCII platform. Here is
-an example adapted from the one in L<perlop>:
-
- # EBCDIC-based examples
- print "j p \n" ^ " a h"; # prints "JAPH\n"
- print "JA" | " ph\n"; # prints "japh\n"
- print "JAPH\nJunk" & "\277\277\277\277\277"; # prints "japh\n";
- print 'p N$' ^ " E<H\n"; # prints "Perl\n";
-
-An interesting property of the 32 C0 control characters
-in the ASCII table is that they can "literally" be constructed
-as control characters in perl, e.g. C<(chr(0)> eq C<\c@>)>
-C<(chr(1)> eq C<\cA>)>, and so on. Perl on EBCDIC platforms has been
-ported to take C<\c@> to chr(0) and C<\cA> to chr(1), etc. as well, but the
-thirty three characters that result depend on which code page you are
-using. The table below uses the standard acronyms for the controls.
-The POSIX-BC and 1047 sets are
-identical throughout this range and differ from the 0037 set at only
-one spot (21 decimal). Note that the C<LINE FEED> character
-may be generated by C<\cJ> on ASCII platforms but by C<\cU> on 1047 or POSIX-BC
-platforms and cannot be generated as a C<"\c.letter."> control character on
-0037 platforms. Note also that C<\c\> cannot be the final element in a string
-or regex, as it will absorb the terminator. But C<\c\I<X>> is a C<FILE
-SEPARATOR> concatenated with I<X> for all I<X>.
-
- chr ord 8859-1 0037 1047 && POSIX-BC
- -----------------------------------------------------------------------
- \c? 127 <DEL> " "
- \c@ 0 <NUL> <NUL> <NUL>
- \cA 1 <SOH> <SOH> <SOH>
- \cB 2 <STX> <STX> <STX>
- \cC 3 <ETX> <ETX> <ETX>
- \cD 4 <EOT> <ST> <ST>
- \cE 5 <ENQ> <HT> <HT>
- \cF 6 <ACK> <SSA> <SSA>
- \cG 7 <BEL> <DEL> <DEL>
- \cH 8 <BS> <EPA> <EPA>
- \cI 9 <HT> <RI> <RI>
- \cJ 10 <LF> <SS2> <SS2>
- \cK 11 <VT> <VT> <VT>
- \cL 12 <FF> <FF> <FF>
- \cM 13 <CR> <CR> <CR>
- \cN 14 <SO> <SO> <SO>
- \cO 15 <SI> <SI> <SI>
- \cP 16 <DLE> <DLE> <DLE>
- \cQ 17 <DC1> <DC1> <DC1>
- \cR 18 <DC2> <DC2> <DC2>
- \cS 19 <DC3> <DC3> <DC3>
- \cT 20 <DC4> <OSC> <OSC>
- \cU 21 <NAK> <NEL> <LF> ***
- \cV 22 <SYN> <BS> <BS>
- \cW 23 <ETB> <ESA> <ESA>
- \cX 24 <CAN> <CAN> <CAN>
- \cY 25 <EOM> <EOM> <EOM>
- \cZ 26 <SUB> <PU2> <PU2>
- \c[ 27 <ESC> <SS3> <SS3>
- \c\X 28 <FS>X <FS>X <FS>X
- \c] 29 <GS> <GS> <GS>
- \c^ 30 <RS> <RS> <RS>
- \c_ 31 <US> <US> <US>
-
-=head1 FUNCTION DIFFERENCES
-
-=over 8
-
-=item chr()
-
-chr() must be given an EBCDIC code number argument to yield a desired
-character return value on an EBCDIC platform. For example:
-
- $CAPITAL_LETTER_A = chr(193);
-
-=item ord()
-
-ord() will return EBCDIC code number values on an EBCDIC platform.
-For example:
-
- $the_number_193 = ord("A");
-
-=item pack()
-
-The c and C templates for pack() are dependent upon character set
-encoding. Examples of usage on EBCDIC include:
-
- $foo = pack("CCCC",193,194,195,196);
- # $foo eq "ABCD"
- $foo = pack("C4",193,194,195,196);
- # same thing
-
- $foo = pack("ccxxcc",193,194,195,196);
- # $foo eq "AB\0\0CD"
-
-=item print()
-
-One must be careful with scalars and strings that are passed to
-print that contain ASCII encodings. One common place
-for this to occur is in the output of the MIME type header for
-CGI script writing. For example, many perl programming guides
-recommend something similar to:
-
- print "Content-type:\ttext/html\015\012\015\012";
- # this may be wrong on EBCDIC
-
-Under the IBM OS/390 USS Web Server or WebSphere on z/OS for example
-you should instead write that as:
-
- print "Content-type:\ttext/html\r\n\r\n"; # OK for DGW et al
-
-That is because the translation from EBCDIC to ASCII is done
-by the web server in this case (such code will not be appropriate for
-the Macintosh however). Consult your web server's documentation for
-further details.
-
-=item printf()
-
-The formats that can convert characters to numbers and vice versa
-will be different from their ASCII counterparts when executed
-on an EBCDIC platform. Examples include:
-
- printf("%c%c%c",193,194,195); # prints ABC
-
-=item sort()
-
-EBCDIC sort results may differ from ASCII sort results especially for
-mixed case strings. This is discussed in more detail below.
-
-=item sprintf()
-
-See the discussion of printf() above. An example of the use
-of sprintf would be:
-
- $CAPITAL_LETTER_A = sprintf("%c",193);
-
-=item unpack()
-
-See the discussion of pack() above.
-
-=back
-
-=head1 REGULAR EXPRESSION DIFFERENCES
-
-As of perl 5.005_03 the letter range regular expressions such as
-[A-Z] and [a-z] have been especially coded to not pick up gap
-characters. For example, characters such as E<ocirc> C<o WITH CIRCUMFLEX>
-that lie between I and J would not be matched by the
-regular expression range C</[H-K]/>. This works in
-the other direction, too, if either of the range end points is
-explicitly numeric: C<[\x89-\x91]> will match C<\x8e>, even
-though C<\x89> is C<i> and C<\x91 > is C<j>, and C<\x8e>
-is a gap character from the alphabetic viewpoint.
-
-If you do want to match the alphabet gap characters in a single octet
-regular expression try matching the hex or octal code such
-as C</\313/> on EBCDIC or C</\364/> on ASCII platforms to
-have your regular expression match C<o WITH CIRCUMFLEX>.
-
-Another construct to be wary of is the inappropriate use of hex or
-octal constants in regular expressions. Consider the following
-set of subs:
-
- sub is_c0 {
- my $char = substr(shift,0,1);
- $char =~ /[\000-\037]/;
- }
-
- sub is_print_ascii {
- my $char = substr(shift,0,1);
- $char =~ /[\040-\176]/;
- }
-
- sub is_delete {
- my $char = substr(shift,0,1);
- $char eq "\177";
- }
-
- sub is_c1 {
- my $char = substr(shift,0,1);
- $char =~ /[\200-\237]/;
- }
-
- sub is_latin_1 {
- my $char = substr(shift,0,1);
- $char =~ /[\240-\377]/;
- }
-
-The above would be adequate if the concern was only with numeric code points.
-However, the concern may be with characters rather than code points
-and on an EBCDIC platform it may be desirable for constructs such as
-C<if (is_print_ascii("A")) {print "A is a printable character\n";}> to print
-out the expected message. One way to represent the above collection
-of character classification subs that is capable of working across the
-four coded character sets discussed in this document is as follows:
-
- sub Is_c0 {
- my $char = substr(shift,0,1);
- if (ord('^')==94) { # ascii
- return $char =~ /[\000-\037]/;
- }
- if (ord('^')==176) { # 0037
- return $char =~ /[\000-\003\067\055-\057\026\005\045\013-\023\074\075\062\046\030\031\077\047\034-\037]/;
- }
- if (ord('^')==95 || ord('^')==106) { # 1047 || posix-bc
- return $char =~ /[\000-\003\067\055-\057\026\005\025\013-\023\074\075\062\046\030\031\077\047\034-\037]/;
- }
- }
-
- sub Is_print_ascii {
- my $char = substr(shift,0,1);
- $char =~ /[ !"\#\$%&'()*+,\-.\/0-9:;<=>?\@A-Z[\\\]^_`a-z{|}~]/;
- }
-
- sub Is_delete {
- my $char = substr(shift,0,1);
- if (ord('^')==94) { # ascii
- return $char eq "\177";
- }
- else { # ebcdic
- return $char eq "\007";
- }
- }
-
- sub Is_c1 {
- my $char = substr(shift,0,1);
- if (ord('^')==94) { # ascii
- return $char =~ /[\200-\237]/;
- }
- if (ord('^')==176) { # 0037
- return $char =~ /[\040-\044\025\006\027\050-\054\011\012\033\060\061\032\063-\066\010\070-\073\040\024\076\377]/;
- }
- if (ord('^')==95) { # 1047
- return $char =~ /[\040-\045\006\027\050-\054\011\012\033\060\061\032\063-\066\010\070-\073\040\024\076\377]/;
- }
- if (ord('^')==106) { # posix-bc
- return $char =~
- /[\040-\045\006\027\050-\054\011\012\033\060\061\032\063-\066\010\070-\073\040\024\076\137]/;
- }
- }
-
- sub Is_latin_1 {
- my $char = substr(shift,0,1);
- if (ord('^')==94) { # ascii
- return $char =~ /[\240-\377]/;
- }
- if (ord('^')==176) { # 0037
- return $char =~
- /[\101\252\112\261\237\262\152\265\275\264\232\212\137\312\257\274\220\217\352\372\276\240\266\263\235\332\233\213\267\270\271\253\144\145\142\146\143\147\236\150\164\161-\163\170\165-\167\254\151\355\356\353\357\354\277\200\375\376\373\374\255\256\131\104\105\102\106\103\107\234\110\124\121-\123\130\125-\127\214\111\315\316\313\317\314\341\160\335\336\333\334\215\216\337]/;
- }
- if (ord('^')==95) { # 1047
- return $char =~
- /[\101\252\112\261\237\262\152\265\273\264\232\212\260\312\257\274\220\217\352\372\276\240\266\263\235\332\233\213\267\270\271\253\144\145\142\146\143\147\236\150\164\161-\163\170\165-\167\254\151\355\356\353\357\354\277\200\375\376\373\374\272\256\131\104\105\102\106\103\107\234\110\124\121-\123\130\125-\127\214\111\315\316\313\317\314\341\160\335\336\333\334\215\216\337]/;
- }
- if (ord('^')==106) { # posix-bc
- return $char =~
- /[\101\252\260\261\237\262\320\265\171\264\232\212\272\312\257\241\220\217\352\372\276\240\266\263\235\332\233\213\267\270\271\253\144\145\142\146\143\147\236\150\164\161-\163\170\165-\167\254\151\355\356\353\357\354\277\200\340\376\335\374\255\256\131\104\105\102\106\103\107\234\110\124\121-\123\130\125-\127\214\111\315\316\313\317\314\341\160\300\336\333\334\215\216\337]/;
- }
- }
-
-Note however that only the C<Is_ascii_print()> sub is really independent
-of coded character set. Another way to write C<Is_latin_1()> would be
-to use the characters in the range explicitly:
-
- sub Is_latin_1 {
- my $char = substr(shift,0,1);
- $char =~ /[ ¡¢£¤¥¦§¨©ª«¬­®¯°±²³´µ¶·¸¹º»¼½¾¿ÀÃÂÃÄÅÆÇÈÉÊËÌÃÃŽÃÃÑÒÓÔÕÖ×ØÙÚÛÜÃÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ]/;
- }
-
-Although that form may run into trouble in network transit (due to the
-presence of 8 bit characters) or on non ISO-Latin character sets.
-
-=head1 SOCKETS
-
-Most socket programming assumes ASCII character encodings in network
-byte order. Exceptions can include CGI script writing under a
-host web server where the server may take care of translation for you.
-Most host web servers convert EBCDIC data to ISO-8859-1 or Unicode on
-output.
-
-=head1 SORTING
-
-One big difference between ASCII-based character sets and EBCDIC ones
-are the relative positions of upper and lower case letters and the
-letters compared to the digits. If sorted on an ASCII-based platform the
-two-letter abbreviation for a physician comes before the two letter
-abbreviation for drive; that is:
-
- @sorted = sort(qw(Dr. dr.)); # @sorted holds ('Dr.','dr.') on ASCII,
- # but ('dr.','Dr.') on EBCDIC
-
-The property of lowercase before uppercase letters in EBCDIC is
-even carried to the Latin 1 EBCDIC pages such as 0037 and 1047.
-An example would be that E<Euml> C<E WITH DIAERESIS> (203) comes
-before E<euml> C<e WITH DIAERESIS> (235) on an ASCII platform, but
-the latter (83) comes before the former (115) on an EBCDIC platform.
-(Astute readers will note that the uppercase version of E<szlig>
-C<SMALL LETTER SHARP S> is simply "SS" and that the upper case version of
-E<yuml> C<y WITH DIAERESIS> is not in the 0..255 range but it is
-at U+x0178 in Unicode, or C<"\x{178}"> in a Unicode enabled Perl).
-
-The sort order will cause differences between results obtained on
-ASCII platforms versus EBCDIC platforms. What follows are some suggestions
-on how to deal with these differences.
-
-=head2 Ignore ASCII vs. EBCDIC sort differences.
-
-This is the least computationally expensive strategy. It may require
-some user education.
-
-=head2 MONO CASE then sort data.
-
-In order to minimize the expense of mono casing mixed-case text, try to
-C<tr///> towards the character set case most employed within the data.
-If the data are primarily UPPERCASE non Latin 1 then apply tr/[a-z]/[A-Z]/
-then sort(). If the data are primarily lowercase non Latin 1 then
-apply tr/[A-Z]/[a-z]/ before sorting. If the data are primarily UPPERCASE
-and include Latin-1 characters then apply:
-
- tr/[a-z]/[A-Z]/;
- tr/[àáâãäåæçèéêëìíîïðñòóôõöøùúûüýþ]/[ÀÃÂÃÄÅÆÇÈÉÊËÌÃÃŽÃÃÑÒÓÔÕÖØÙÚÛÜÃÞ/;
- s/ß/SS/g;
-
-then sort(). Do note however that such Latin-1 manipulation does not
-address the E<yuml> C<y WITH DIAERESIS> character that will remain at
-code point 255 on ASCII platforms, but 223 on most EBCDIC platforms
-where it will sort to a place less than the EBCDIC numerals. With a
-Unicode-enabled Perl you might try:
-
- tr/^?/\x{178}/;
-
-The strategy of mono casing data before sorting does not preserve the case
-of the data and may not be acceptable for that reason.
-
-=head2 Convert, sort data, then re convert.
-
-This is the most expensive proposition that does not employ a network
-connection.
-
-=head2 Perform sorting on one type of platform only.
-
-This strategy can employ a network connection. As such
-it would be computationally expensive.
-
-=head1 TRANSFORMATION FORMATS
-
-There are a variety of ways of transforming data with an intra character set
-mapping that serve a variety of purposes. Sorting was discussed in the
-previous section and a few of the other more popular mapping techniques are
-discussed next.
-
-=head2 URL decoding and encoding
-
-Note that some URLs have hexadecimal ASCII code points in them in an
-attempt to overcome character or protocol limitation issues. For example
-the tilde character is not on every keyboard hence a URL of the form:
-
- http://www.pvhp.com/~pvhp/
-
-may also be expressed as either of:
-
- http://www.pvhp.com/%7Epvhp/
-
- http://www.pvhp.com/%7epvhp/
-
-where 7E is the hexadecimal ASCII code point for '~'. Here is an example
-of decoding such a URL under CCSID 1047:
-
- $url = 'http://www.pvhp.com/%7Epvhp/';
- # this array assumes code page 1047
- my @a2e_1047 = (
- 0, 1, 2, 3, 55, 45, 46, 47, 22, 5, 21, 11, 12, 13, 14, 15,
- 16, 17, 18, 19, 60, 61, 50, 38, 24, 25, 63, 39, 28, 29, 30, 31,
- 64, 90,127,123, 91,108, 80,125, 77, 93, 92, 78,107, 96, 75, 97,
- 240,241,242,243,244,245,246,247,248,249,122, 94, 76,126,110,111,
- 124,193,194,195,196,197,198,199,200,201,209,210,211,212,213,214,
- 215,216,217,226,227,228,229,230,231,232,233,173,224,189, 95,109,
- 121,129,130,131,132,133,134,135,136,137,145,146,147,148,149,150,
- 151,152,153,162,163,164,165,166,167,168,169,192, 79,208,161, 7,
- 32, 33, 34, 35, 36, 37, 6, 23, 40, 41, 42, 43, 44, 9, 10, 27,
- 48, 49, 26, 51, 52, 53, 54, 8, 56, 57, 58, 59, 4, 20, 62,255,
- 65,170, 74,177,159,178,106,181,187,180,154,138,176,202,175,188,
- 144,143,234,250,190,160,182,179,157,218,155,139,183,184,185,171,
- 100,101, 98,102, 99,103,158,104,116,113,114,115,120,117,118,119,
- 172,105,237,238,235,239,236,191,128,253,254,251,252,186,174, 89,
- 68, 69, 66, 70, 67, 71,156, 72, 84, 81, 82, 83, 88, 85, 86, 87,
- 140, 73,205,206,203,207,204,225,112,221,222,219,220,141,142,223
- );
- $url =~ s/%([0-9a-fA-F]{2})/pack("c",$a2e_1047[hex($1)])/ge;
-
-Conversely, here is a partial solution for the task of encoding such
-a URL under the 1047 code page:
-
- $url = 'http://www.pvhp.com/~pvhp/';
- # this array assumes code page 1047
- my @e2a_1047 = (
- 0, 1, 2, 3,156, 9,134,127,151,141,142, 11, 12, 13, 14, 15,
- 16, 17, 18, 19,157, 10, 8,135, 24, 25,146,143, 28, 29, 30, 31,
- 128,129,130,131,132,133, 23, 27,136,137,138,139,140, 5, 6, 7,
- 144,145, 22,147,148,149,150, 4,152,153,154,155, 20, 21,158, 26,
- 32,160,226,228,224,225,227,229,231,241,162, 46, 60, 40, 43,124,
- 38,233,234,235,232,237,238,239,236,223, 33, 36, 42, 41, 59, 94,
- 45, 47,194,196,192,193,195,197,199,209,166, 44, 37, 95, 62, 63,
- 248,201,202,203,200,205,206,207,204, 96, 58, 35, 64, 39, 61, 34,
- 216, 97, 98, 99,100,101,102,103,104,105,171,187,240,253,254,177,
- 176,106,107,108,109,110,111,112,113,114,170,186,230,184,198,164,
- 181,126,115,116,117,118,119,120,121,122,161,191,208, 91,222,174,
- 172,163,165,183,169,167,182,188,189,190,221,168,175, 93,180,215,
- 123, 65, 66, 67, 68, 69, 70, 71, 72, 73,173,244,246,242,243,245,
- 125, 74, 75, 76, 77, 78, 79, 80, 81, 82,185,251,252,249,250,255,
- 92,247, 83, 84, 85, 86, 87, 88, 89, 90,178,212,214,210,211,213,
- 48, 49, 50, 51, 52, 53, 54, 55, 56, 57,179,219,220,217,218,159
- );
- # The following regular expression does not address the
- # mappings for: ('.' => '%2E', '/' => '%2F', ':' => '%3A')
- $url =~ s/([\t "#%&\(\),;<=>\?\@\[\\\]^`{|}~])/sprintf("%%%02X",$e2a_1047[ord($1)])/ge;
-
-where a more complete solution would split the URL into components
-and apply a full s/// substitution only to the appropriate parts.
-
-In the remaining examples a @e2a or @a2e array may be employed
-but the assignment will not be shown explicitly. For code page 1047
-you could use the @a2e_1047 or @e2a_1047 arrays just shown.
-
-=head2 uu encoding and decoding
-
-The C<u> template to pack() or unpack() will render EBCDIC data in EBCDIC
-characters equivalent to their ASCII counterparts. For example, the
-following will print "Yes indeed\n" on either an ASCII or EBCDIC computer:
-
- $all_byte_chrs = '';
- for (0..255) { $all_byte_chrs .= chr($_); }
- $uuencode_byte_chrs = pack('u', $all_byte_chrs);
- ($uu = <<'ENDOFHEREDOC') =~ s/^\s*//gm;
- M``$"`P0%!@<("0H+#`T.#Q`1$A,4%187&!D:&QP='A\@(2(C)"4F)R@I*BLL
- M+2XO,#$R,S0U-C<X.3H[/#T^/T!!0D-$149'2$E*2TQ-3D]045)35%565UA9
- M6EM<75Y?8&%B8V1E9F=H:6IK;&UN;W!Q<G-T=79W>'EZ>WQ]?G^`@8*#A(6&
- MAXB)BHN,C8Z/D)&2DY25EI>8F9J;G)V>GZ"AHJ.DI::GJ*FJJZRMKJ^PL;*S
- MM+6VM[BYNKN\O;Z_P,'"P\3%QL?(R<K+S,W.S]#1TM/4U=;7V-G:V]S=WM_@
- ?X>+CY.7FY^CIZNOL[>[O\/'R\_3U]O?X^?K[_/W^_P``
- ENDOFHEREDOC
- if ($uuencode_byte_chrs eq $uu) {
- print "Yes ";
- }
- $uudecode_byte_chrs = unpack('u', $uuencode_byte_chrs);
- if ($uudecode_byte_chrs eq $all_byte_chrs) {
- print "indeed\n";
- }
-
-Here is a very spartan uudecoder that will work on EBCDIC provided
-that the @e2a array is filled in appropriately:
-
- #!/usr/local/bin/perl
- @e2a = ( # this must be filled in
- );
- $_ = <> until ($mode,$file) = /^begin\s*(\d*)\s*(\S*)/;
- open(OUT, "> $file") if $file ne "";
- while(<>) {
- last if /^end/;
- next if /[a-z]/;
- next unless int(((($e2a[ord()] - 32 ) & 077) + 2) / 3) ==
- int(length() / 4);
- print OUT unpack("u", $_);
- }
- close(OUT);
- chmod oct($mode), $file;
-
-
-=head2 Quoted-Printable encoding and decoding
-
-On ASCII-encoded platforms it is possible to strip characters outside of
-the printable set using:
-
- # This QP encoder works on ASCII only
- $qp_string =~ s/([=\x00-\x1F\x80-\xFF])/sprintf("=%02X",ord($1))/ge;
-
-Whereas a QP encoder that works on both ASCII and EBCDIC platforms
-would look somewhat like the following (where the EBCDIC branch @e2a
-array is omitted for brevity):
-
- if (ord('A') == 65) { # ASCII
- $delete = "\x7F"; # ASCII
- @e2a = (0 .. 255) # ASCII to ASCII identity map
- }
- else { # EBCDIC
- $delete = "\x07"; # EBCDIC
- @e2a = # EBCDIC to ASCII map (as shown above)
- }
- $qp_string =~
- s/([^ !"\#\$%&'()*+,\-.\/0-9:;<>?\@A-Z[\\\]^_`a-z{|}~$delete])/sprintf("=%02X",$e2a[ord($1)])/ge;
-
-(although in production code the substitutions might be done
-in the EBCDIC branch with the @e2a array and separately in the
-ASCII branch without the expense of the identity map).
-
-Such QP strings can be decoded with:
-
- # This QP decoder is limited to ASCII only
- $string =~ s/=([0-9A-Fa-f][0-9A-Fa-f])/chr hex $1/ge;
- $string =~ s/=[\n\r]+$//;
-
-Whereas a QP decoder that works on both ASCII and EBCDIC platforms
-would look somewhat like the following (where the @a2e array is
-omitted for brevity):
-
- $string =~ s/=([0-9A-Fa-f][0-9A-Fa-f])/chr $a2e[hex $1]/ge;
- $string =~ s/=[\n\r]+$//;
-
-=head2 Caesarean ciphers
-
-The practice of shifting an alphabet one or more characters for encipherment
-dates back thousands of years and was explicitly detailed by Gaius Julius
-Caesar in his B<Gallic Wars> text. A single alphabet shift is sometimes
-referred to as a rotation and the shift amount is given as a number $n after
-the string 'rot' or "rot$n". Rot0 and rot26 would designate identity maps
-on the 26-letter English version of the Latin alphabet. Rot13 has the
-interesting property that alternate subsequent invocations are identity maps
-(thus rot13 is its own non-trivial inverse in the group of 26 alphabet
-rotations). Hence the following is a rot13 encoder and decoder that will
-work on ASCII and EBCDIC platforms:
-
- #!/usr/local/bin/perl
-
- while(<>){
- tr/n-za-mN-ZA-M/a-zA-Z/;
- print;
- }
-
-In one-liner form:
-
- perl -ne 'tr/n-za-mN-ZA-M/a-zA-Z/;print'
-
-
-=head1 Hashing order and checksums
-
-To the extent that it is possible to write code that depends on
-hashing order there may be differences between hashes as stored
-on an ASCII-based platform and hashes stored on an EBCDIC-based platform.
-XXX
-
-=head1 I18N AND L10N
-
-Internationalization (I18N) and localization (L10N) are supported at least
-in principle even on EBCDIC platforms. The details are system-dependent
-and discussed under the L<perlebcdic/OS ISSUES> section below.
-
-=head1 MULTI-OCTET CHARACTER SETS
-
-Perl may work with an internal UTF-EBCDIC encoding form for wide characters
-on EBCDIC platforms in a manner analogous to the way that it works with
-the UTF-8 internal encoding form on ASCII based platforms.
-
-Legacy multi byte EBCDIC code pages XXX.
-
-=head1 OS ISSUES
-
-There may be a few system-dependent issues
-of concern to EBCDIC Perl programmers.
-
-=head2 OS/400
-
-=over 8
-
-=item PASE
-
-The PASE environment is a runtime environment for OS/400 that can run
-executables built for PowerPC AIX in OS/400; see L<perlos400>. PASE
-is ASCII-based, not EBCDIC-based as the ILE.
-
-=item IFS access
-
-XXX.
-
-=back
-
-=head2 OS/390, z/OS
-
-Perl runs under Unix Systems Services or USS.
-
-=over 8
-
-=item chcp
-
-B<chcp> is supported as a shell utility for displaying and changing
-one's code page. See also L<chcp(1)>.
-
-=item dataset access
-
-For sequential data set access try:
-
- my @ds_records = `cat //DSNAME`;
-
-or:
-
- my @ds_records = `cat //'HLQ.DSNAME'`;
-
-See also the OS390::Stdio module on CPAN.
-
-=item OS/390, z/OS iconv
-
-B<iconv> is supported as both a shell utility and a C RTL routine.
-See also the iconv(1) and iconv(3) manual pages.
-
-=item locales
-
-On OS/390 or z/OS see L<locale> for information on locales. The L10N files
-are in F</usr/nls/locale>. $Config{d_setlocale} is 'define' on OS/390
-or z/OS.
-
-=back
-
-=head2 VM/ESA?
-
-XXX.
-
-=head2 POSIX-BC?
-
-XXX.
-
-=head1 BUGS
-
-This pod document contains literal Latin 1 characters and may encounter
-translation difficulties. In particular one popular nroff implementation
-was known to strip accented characters to their unaccented counterparts
-while attempting to view this document through the B<pod2man> program
-(for example, you may see a plain C<y> rather than one with a diaeresis
-as in E<yuml>). Another nroff truncated the resultant manpage at
-the first occurrence of 8 bit characters.
-
-Not all shells will allow multiple C<-e> string arguments to perl to
-be concatenated together properly as recipes 0, 2, 4, 5, and 6 might
-seem to imply.
-
-=head1 SEE ALSO
-
-L<perllocale>, L<perlfunc>, L<perlunicode>, L<utf8>.
-
-=head1 REFERENCES
-
-L<http://anubis.dkuug.dk/i18n/charmaps>
-
-L<http://www.unicode.org/>
-
-L<http://www.unicode.org/unicode/reports/tr16/>
-
-L<http://www.wps.com/projects/codes/>
-B<ASCII: American Standard Code for Information Infiltration> Tom Jennings,
-September 1999.
-
-B<The Unicode Standard, Version 3.0> The Unicode Consortium, Lisa Moore ed.,
-ISBN 0-201-61633-5, Addison Wesley Developers Press, February 2000.
-
-B<CDRA: IBM - Character Data Representation Architecture -
-Reference and Registry>, IBM SC09-2190-00, December 1996.
-
-"Demystifying Character Sets", Andrea Vine, Multilingual Computing
-& Technology, B<#26 Vol. 10 Issue 4>, August/September 1999;
-ISSN 1523-0309; Multilingual Computing Inc. Sandpoint ID, USA.
-
-B<Codes, Ciphers, and Other Cryptic and Clandestine Communication>
-Fred B. Wrixon, ISBN 1-57912-040-7, Black Dog & Leventhal Publishers,
-1998.
-
-L<http://www.bobbemer.com/P-BIT.HTM>
-B<IBM - EBCDIC and the P-bit; The biggest Computer Goof Ever> Robert Bemer.
-
-=head1 HISTORY
-
-15 April 2001: added UTF-8 and UTF-EBCDIC to main table, pvhp.
-
-=head1 AUTHOR
-
-Peter Prymmer pvhp@best.com wrote this in 1999 and 2000
-with CCSID 0819 and 0037 help from Chris Leach and
-AndrE<eacute> Pirard A.Pirard@ulg.ac.be as well as POSIX-BC
-help from Thomas Dorner Thomas.Dorner@start.de.
-Thanks also to Vickie Cooper, Philip Newton, William Raffloer, and
-Joe Smith. Trademarks, registered trademarks, service marks and
-registered service marks used in this document are the property of
-their respective owners.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlembed.pod b/Master/tlpkg/tlperl/lib/pods/perlembed.pod
deleted file mode 100644
index e40035eb71a..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlembed.pod
+++ /dev/null
@@ -1,1117 +0,0 @@
-=head1 NAME
-
-perlembed - how to embed perl in your C program
-
-=head1 DESCRIPTION
-
-=head2 PREAMBLE
-
-Do you want to:
-
-=over 5
-
-=item B<Use C from Perl?>
-
-Read L<perlxstut>, L<perlxs>, L<h2xs>, L<perlguts>, and L<perlapi>.
-
-=item B<Use a Unix program from Perl?>
-
-Read about back-quotes and about C<system> and C<exec> in L<perlfunc>.
-
-=item B<Use Perl from Perl?>
-
-Read about L<perlfunc/do> and L<perlfunc/eval> and L<perlfunc/require>
-and L<perlfunc/use>.
-
-=item B<Use C from C?>
-
-Rethink your design.
-
-=item B<Use Perl from C?>
-
-Read on...
-
-=back
-
-=head2 ROADMAP
-
-=over 5
-
-=item *
-
-Compiling your C program
-
-=item *
-
-Adding a Perl interpreter to your C program
-
-=item *
-
-Calling a Perl subroutine from your C program
-
-=item *
-
-Evaluating a Perl statement from your C program
-
-=item *
-
-Performing Perl pattern matches and substitutions from your C program
-
-=item *
-
-Fiddling with the Perl stack from your C program
-
-=item *
-
-Maintaining a persistent interpreter
-
-=item *
-
-Maintaining multiple interpreter instances
-
-=item *
-
-Using Perl modules, which themselves use C libraries, from your C program
-
-=item *
-
-Embedding Perl under Win32
-
-=back
-
-=head2 Compiling your C program
-
-If you have trouble compiling the scripts in this documentation,
-you're not alone. The cardinal rule: COMPILE THE PROGRAMS IN EXACTLY
-THE SAME WAY THAT YOUR PERL WAS COMPILED. (Sorry for yelling.)
-
-Also, every C program that uses Perl must link in the I<perl library>.
-What's that, you ask? Perl is itself written in C; the perl library
-is the collection of compiled C programs that were used to create your
-perl executable (I</usr/bin/perl> or equivalent). (Corollary: you
-can't use Perl from your C program unless Perl has been compiled on
-your machine, or installed properly--that's why you shouldn't blithely
-copy Perl executables from machine to machine without also copying the
-I<lib> directory.)
-
-When you use Perl from C, your C program will--usually--allocate,
-"run", and deallocate a I<PerlInterpreter> object, which is defined by
-the perl library.
-
-If your copy of Perl is recent enough to contain this documentation
-(version 5.002 or later), then the perl library (and I<EXTERN.h> and
-I<perl.h>, which you'll also need) will reside in a directory
-that looks like this:
-
- /usr/local/lib/perl5/your_architecture_here/CORE
-
-or perhaps just
-
- /usr/local/lib/perl5/CORE
-
-or maybe something like
-
- /usr/opt/perl5/CORE
-
-Execute this statement for a hint about where to find CORE:
-
- perl -MConfig -e 'print $Config{archlib}'
-
-Here's how you'd compile the example in the next section,
-L<Adding a Perl interpreter to your C program>, on my Linux box:
-
- % gcc -O2 -Dbool=char -DHAS_BOOL -I/usr/local/include
- -I/usr/local/lib/perl5/i586-linux/5.003/CORE
- -L/usr/local/lib/perl5/i586-linux/5.003/CORE
- -o interp interp.c -lperl -lm
-
-(That's all one line.) On my DEC Alpha running old 5.003_05, the
-incantation is a bit different:
-
- % cc -O2 -Olimit 2900 -DSTANDARD_C -I/usr/local/include
- -I/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE
- -L/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE -L/usr/local/lib
- -D__LANGUAGE_C__ -D_NO_PROTO -o interp interp.c -lperl -lm
-
-How can you figure out what to add? Assuming your Perl is post-5.001,
-execute a C<perl -V> command and pay special attention to the "cc" and
-"ccflags" information.
-
-You'll have to choose the appropriate compiler (I<cc>, I<gcc>, et al.) for
-your machine: C<perl -MConfig -e 'print $Config{cc}'> will tell you what
-to use.
-
-You'll also have to choose the appropriate library directory
-(I</usr/local/lib/...>) for your machine. If your compiler complains
-that certain functions are undefined, or that it can't locate
-I<-lperl>, then you need to change the path following the C<-L>. If it
-complains that it can't find I<EXTERN.h> and I<perl.h>, you need to
-change the path following the C<-I>.
-
-You may have to add extra libraries as well. Which ones?
-Perhaps those printed by
-
- perl -MConfig -e 'print $Config{libs}'
-
-Provided your perl binary was properly configured and installed the
-B<ExtUtils::Embed> module will determine all of this information for
-you:
-
- % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
-
-If the B<ExtUtils::Embed> module isn't part of your Perl distribution,
-you can retrieve it from
-http://www.perl.com/perl/CPAN/modules/by-module/ExtUtils/
-(If this documentation came from your Perl distribution, then you're
-running 5.004 or better and you already have it.)
-
-The B<ExtUtils::Embed> kit on CPAN also contains all source code for
-the examples in this document, tests, additional examples and other
-information you may find useful.
-
-=head2 Adding a Perl interpreter to your C program
-
-In a sense, perl (the C program) is a good example of embedding Perl
-(the language), so I'll demonstrate embedding with I<miniperlmain.c>,
-included in the source distribution. Here's a bastardized, non-portable
-version of I<miniperlmain.c> containing the essentials of embedding:
-
- #include <EXTERN.h> /* from the Perl distribution */
- #include <perl.h> /* from the Perl distribution */
-
- static PerlInterpreter *my_perl; /*** The Perl interpreter ***/
-
- int main(int argc, char **argv, char **env)
- {
- PERL_SYS_INIT3(&argc,&argv,&env);
- my_perl = perl_alloc();
- perl_construct(my_perl);
- PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
- perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
- perl_run(my_perl);
- perl_destruct(my_perl);
- perl_free(my_perl);
- PERL_SYS_TERM();
- }
-
-Notice that we don't use the C<env> pointer. Normally handed to
-C<perl_parse> as its final argument, C<env> here is replaced by
-C<NULL>, which means that the current environment will be used.
-
-The macros PERL_SYS_INIT3() and PERL_SYS_TERM() provide system-specific
-tune up of the C runtime environment necessary to run Perl interpreters;
-they should only be called once regardless of how many interpreters you
-create or destroy. Call PERL_SYS_INIT3() before you create your first
-interpreter, and PERL_SYS_TERM() after you free your last interpreter.
-
-Since PERL_SYS_INIT3() may change C<env>, it may be more appropriate to
-provide C<env> as an argument to perl_parse().
-
-Also notice that no matter what arguments you pass to perl_parse(),
-PERL_SYS_INIT3() must be invoked on the C main() argc, argv and env and
-only once.
-
-Now compile this program (I'll call it I<interp.c>) into an executable:
-
- % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
-
-After a successful compilation, you'll be able to use I<interp> just
-like perl itself:
-
- % interp
- print "Pretty Good Perl \n";
- print "10890 - 9801 is ", 10890 - 9801;
- <CTRL-D>
- Pretty Good Perl
- 10890 - 9801 is 1089
-
-or
-
- % interp -e 'printf("%x", 3735928559)'
- deadbeef
-
-You can also read and execute Perl statements from a file while in the
-midst of your C program, by placing the filename in I<argv[1]> before
-calling I<perl_run>.
-
-=head2 Calling a Perl subroutine from your C program
-
-To call individual Perl subroutines, you can use any of the B<call_*>
-functions documented in L<perlcall>.
-In this example we'll use C<call_argv>.
-
-That's shown below, in a program I'll call I<showtime.c>.
-
- #include <EXTERN.h>
- #include <perl.h>
-
- static PerlInterpreter *my_perl;
-
- int main(int argc, char **argv, char **env)
- {
- char *args[] = { NULL };
- PERL_SYS_INIT3(&argc,&argv,&env);
- my_perl = perl_alloc();
- perl_construct(my_perl);
-
- perl_parse(my_perl, NULL, argc, argv, NULL);
- PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
-
- /*** skipping perl_run() ***/
-
- call_argv("showtime", G_DISCARD | G_NOARGS, args);
-
- perl_destruct(my_perl);
- perl_free(my_perl);
- PERL_SYS_TERM();
- }
-
-where I<showtime> is a Perl subroutine that takes no arguments (that's the
-I<G_NOARGS>) and for which I'll ignore the return value (that's the
-I<G_DISCARD>). Those flags, and others, are discussed in L<perlcall>.
-
-I'll define the I<showtime> subroutine in a file called I<showtime.pl>:
-
- print "I shan't be printed.";
-
- sub showtime {
- print time;
- }
-
-Simple enough. Now compile and run:
-
- % cc -o showtime showtime.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
-
- % showtime showtime.pl
- 818284590
-
-yielding the number of seconds that elapsed between January 1, 1970
-(the beginning of the Unix epoch), and the moment I began writing this
-sentence.
-
-In this particular case we don't have to call I<perl_run>, as we set
-the PL_exit_flag PERL_EXIT_DESTRUCT_END which executes END blocks in
-perl_destruct.
-
-If you want to pass arguments to the Perl subroutine, you can add
-strings to the C<NULL>-terminated C<args> list passed to
-I<call_argv>. For other data types, or to examine return values,
-you'll need to manipulate the Perl stack. That's demonstrated in
-L<Fiddling with the Perl stack from your C program>.
-
-=head2 Evaluating a Perl statement from your C program
-
-Perl provides two API functions to evaluate pieces of Perl code.
-These are L<perlapi/eval_sv> and L<perlapi/eval_pv>.
-
-Arguably, these are the only routines you'll ever need to execute
-snippets of Perl code from within your C program. Your code can be as
-long as you wish; it can contain multiple statements; it can employ
-L<perlfunc/use>, L<perlfunc/require>, and L<perlfunc/do> to
-include external Perl files.
-
-I<eval_pv> lets us evaluate individual Perl strings, and then
-extract variables for coercion into C types. The following program,
-I<string.c>, executes three Perl strings, extracting an C<int> from
-the first, a C<float> from the second, and a C<char *> from the third.
-
- #include <EXTERN.h>
- #include <perl.h>
-
- static PerlInterpreter *my_perl;
-
- main (int argc, char **argv, char **env)
- {
- char *embedding[] = { "", "-e", "0" };
-
- PERL_SYS_INIT3(&argc,&argv,&env);
- my_perl = perl_alloc();
- perl_construct( my_perl );
-
- perl_parse(my_perl, NULL, 3, embedding, NULL);
- PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
- perl_run(my_perl);
-
- /** Treat $a as an integer **/
- eval_pv("$a = 3; $a **= 2", TRUE);
- printf("a = %d\n", SvIV(get_sv("a", 0)));
-
- /** Treat $a as a float **/
- eval_pv("$a = 3.14; $a **= 2", TRUE);
- printf("a = %f\n", SvNV(get_sv("a", 0)));
-
- /** Treat $a as a string **/
- eval_pv("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE);
- printf("a = %s\n", SvPV_nolen(get_sv("a", 0)));
-
- perl_destruct(my_perl);
- perl_free(my_perl);
- PERL_SYS_TERM();
- }
-
-All of those strange functions with I<sv> in their names help convert Perl scalars to C types. They're described in L<perlguts> and L<perlapi>.
-
-If you compile and run I<string.c>, you'll see the results of using
-I<SvIV()> to create an C<int>, I<SvNV()> to create a C<float>, and
-I<SvPV()> to create a string:
-
- a = 9
- a = 9.859600
- a = Just Another Perl Hacker
-
-In the example above, we've created a global variable to temporarily
-store the computed value of our eval'ed expression. It is also
-possible and in most cases a better strategy to fetch the return value
-from I<eval_pv()> instead. Example:
-
- ...
- SV *val = eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE);
- printf("%s\n", SvPV_nolen(val));
- ...
-
-This way, we avoid namespace pollution by not creating global
-variables and we've simplified our code as well.
-
-=head2 Performing Perl pattern matches and substitutions from your C program
-
-The I<eval_sv()> function lets us evaluate strings of Perl code, so we can
-define some functions that use it to "specialize" in matches and
-substitutions: I<match()>, I<substitute()>, and I<matches()>.
-
- I32 match(SV *string, char *pattern);
-
-Given a string and a pattern (e.g., C<m/clasp/> or C</\b\w*\b/>, which
-in your C program might appear as "/\\b\\w*\\b/"), match()
-returns 1 if the string matches the pattern and 0 otherwise.
-
- int substitute(SV **string, char *pattern);
-
-Given a pointer to an C<SV> and an C<=~> operation (e.g.,
-C<s/bob/robert/g> or C<tr[A-Z][a-z]>), substitute() modifies the string
-within the C<SV> as according to the operation, returning the number of substitutions
-made.
-
- int matches(SV *string, char *pattern, AV **matches);
-
-Given an C<SV>, a pattern, and a pointer to an empty C<AV>,
-matches() evaluates C<$string =~ $pattern> in a list context, and
-fills in I<matches> with the array elements, returning the number of matches found.
-
-Here's a sample program, I<match.c>, that uses all three (long lines have
-been wrapped here):
-
- #include <EXTERN.h>
- #include <perl.h>
-
- static PerlInterpreter *my_perl;
-
- /** my_eval_sv(code, error_check)
- ** kinda like eval_sv(),
- ** but we pop the return value off the stack
- **/
- SV* my_eval_sv(SV *sv, I32 croak_on_error)
- {
- dSP;
- SV* retval;
-
-
- PUSHMARK(SP);
- eval_sv(sv, G_SCALAR);
-
- SPAGAIN;
- retval = POPs;
- PUTBACK;
-
- if (croak_on_error && SvTRUE(ERRSV))
- croak(SvPVx_nolen(ERRSV));
-
- return retval;
- }
-
- /** match(string, pattern)
- **
- ** Used for matches in a scalar context.
- **
- ** Returns 1 if the match was successful; 0 otherwise.
- **/
-
- I32 match(SV *string, char *pattern)
- {
- SV *command = newSV(0), *retval;
-
- sv_setpvf(command, "my $string = '%s'; $string =~ %s",
- SvPV_nolen(string), pattern);
-
- retval = my_eval_sv(command, TRUE);
- SvREFCNT_dec(command);
-
- return SvIV(retval);
- }
-
- /** substitute(string, pattern)
- **
- ** Used for =~ operations that modify their left-hand side (s/// and tr///)
- **
- ** Returns the number of successful matches, and
- ** modifies the input string if there were any.
- **/
-
- I32 substitute(SV **string, char *pattern)
- {
- SV *command = newSV(0), *retval;
-
- sv_setpvf(command, "$string = '%s'; ($string =~ %s)",
- SvPV_nolen(*string), pattern);
-
- retval = my_eval_sv(command, TRUE);
- SvREFCNT_dec(command);
-
- *string = get_sv("string", 0);
- return SvIV(retval);
- }
-
- /** matches(string, pattern, matches)
- **
- ** Used for matches in a list context.
- **
- ** Returns the number of matches,
- ** and fills in **matches with the matching substrings
- **/
-
- I32 matches(SV *string, char *pattern, AV **match_list)
- {
- SV *command = newSV(0);
- I32 num_matches;
-
- sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)",
- SvPV_nolen(string), pattern);
-
- my_eval_sv(command, TRUE);
- SvREFCNT_dec(command);
-
- *match_list = get_av("array", 0);
- num_matches = av_len(*match_list) + 1;
-
- return num_matches;
- }
-
- main (int argc, char **argv, char **env)
- {
- char *embedding[] = { "", "-e", "0" };
- AV *match_list;
- I32 num_matches, i;
- SV *text;
-
- PERL_SYS_INIT3(&argc,&argv,&env);
- my_perl = perl_alloc();
- perl_construct(my_perl);
- perl_parse(my_perl, NULL, 3, embedding, NULL);
- PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
-
- text = newSV(0);
- sv_setpv(text, "When he is at a convenience store and the "
- "bill comes to some amount like 76 cents, Maynard is "
- "aware that there is something he *should* do, something "
- "that will enable him to get back a quarter, but he has "
- "no idea *what*. He fumbles through his red squeezey "
- "changepurse and gives the boy three extra pennies with "
- "his dollar, hoping that he might luck into the correct "
- "amount. The boy gives him back two of his own pennies "
- "and then the big shiny quarter that is his prize. "
- "-RICHH");
-
- if (match(text, "m/quarter/")) /** Does text contain 'quarter'? **/
- printf("match: Text contains the word 'quarter'.\n\n");
- else
- printf("match: Text doesn't contain the word 'quarter'.\n\n");
-
- if (match(text, "m/eighth/")) /** Does text contain 'eighth'? **/
- printf("match: Text contains the word 'eighth'.\n\n");
- else
- printf("match: Text doesn't contain the word 'eighth'.\n\n");
-
- /** Match all occurrences of /wi../ **/
- num_matches = matches(text, "m/(wi..)/g", &match_list);
- printf("matches: m/(wi..)/g found %d matches...\n", num_matches);
-
- for (i = 0; i < num_matches; i++)
- printf("match: %s\n", SvPV_nolen(*av_fetch(match_list, i, FALSE)));
- printf("\n");
-
- /** Remove all vowels from text **/
- num_matches = substitute(&text, "s/[aeiou]//gi");
- if (num_matches) {
- printf("substitute: s/[aeiou]//gi...%d substitutions made.\n",
- num_matches);
- printf("Now text is: %s\n\n", SvPV_nolen(text));
- }
-
- /** Attempt a substitution **/
- if (!substitute(&text, "s/Perl/C/")) {
- printf("substitute: s/Perl/C...No substitution made.\n\n");
- }
-
- SvREFCNT_dec(text);
- PL_perl_destruct_level = 1;
- perl_destruct(my_perl);
- perl_free(my_perl);
- PERL_SYS_TERM();
- }
-
-which produces the output (again, long lines have been wrapped here)
-
- match: Text contains the word 'quarter'.
-
- match: Text doesn't contain the word 'eighth'.
-
- matches: m/(wi..)/g found 2 matches...
- match: will
- match: with
-
- substitute: s/[aeiou]//gi...139 substitutions made.
- Now text is: Whn h s t cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
- Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt bck
- qrtr, bt h hs n d *wht*. H fmbls thrgh hs rd sqzy chngprs nd gvs th by
- thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct mnt. Th by gvs
- hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s hs prz. -RCHH
-
- substitute: s/Perl/C...No substitution made.
-
-=head2 Fiddling with the Perl stack from your C program
-
-When trying to explain stacks, most computer science textbooks mumble
-something about spring-loaded columns of cafeteria plates: the last
-thing you pushed on the stack is the first thing you pop off. That'll
-do for our purposes: your C program will push some arguments onto "the Perl
-stack", shut its eyes while some magic happens, and then pop the
-results--the return value of your Perl subroutine--off the stack.
-
-First you'll need to know how to convert between C types and Perl
-types, with newSViv() and sv_setnv() and newAV() and all their
-friends. They're described in L<perlguts> and L<perlapi>.
-
-Then you'll need to know how to manipulate the Perl stack. That's
-described in L<perlcall>.
-
-Once you've understood those, embedding Perl in C is easy.
-
-Because C has no builtin function for integer exponentiation, let's
-make Perl's ** operator available to it (this is less useful than it
-sounds, because Perl implements ** with C's I<pow()> function). First
-I'll create a stub exponentiation function in I<power.pl>:
-
- sub expo {
- my ($a, $b) = @_;
- return $a ** $b;
- }
-
-Now I'll create a C program, I<power.c>, with a function
-I<PerlPower()> that contains all the perlguts necessary to push the
-two arguments into I<expo()> and to pop the return value out. Take a
-deep breath...
-
- #include <EXTERN.h>
- #include <perl.h>
-
- static PerlInterpreter *my_perl;
-
- static void
- PerlPower(int a, int b)
- {
- dSP; /* initialize stack pointer */
- ENTER; /* everything created after here */
- SAVETMPS; /* ...is a temporary variable. */
- PUSHMARK(SP); /* remember the stack pointer */
- XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack */
- XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack */
- PUTBACK; /* make local stack pointer global */
- call_pv("expo", G_SCALAR); /* call the function */
- SPAGAIN; /* refresh stack pointer */
- /* pop the return value from stack */
- printf ("%d to the %dth power is %d.\n", a, b, POPi);
- PUTBACK;
- FREETMPS; /* free that return value */
- LEAVE; /* ...and the XPUSHed "mortal" args.*/
- }
-
- int main (int argc, char **argv, char **env)
- {
- char *my_argv[] = { "", "power.pl" };
-
- PERL_SYS_INIT3(&argc,&argv,&env);
- my_perl = perl_alloc();
- perl_construct( my_perl );
-
- perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL);
- PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
- perl_run(my_perl);
-
- PerlPower(3, 4); /*** Compute 3 ** 4 ***/
-
- perl_destruct(my_perl);
- perl_free(my_perl);
- PERL_SYS_TERM();
- }
-
-
-
-Compile and run:
-
- % cc -o power power.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
-
- % power
- 3 to the 4th power is 81.
-
-=head2 Maintaining a persistent interpreter
-
-When developing interactive and/or potentially long-running
-applications, it's a good idea to maintain a persistent interpreter
-rather than allocating and constructing a new interpreter multiple
-times. The major reason is speed: since Perl will only be loaded into
-memory once.
-
-However, you have to be more cautious with namespace and variable
-scoping when using a persistent interpreter. In previous examples
-we've been using global variables in the default package C<main>. We
-knew exactly what code would be run, and assumed we could avoid
-variable collisions and outrageous symbol table growth.
-
-Let's say your application is a server that will occasionally run Perl
-code from some arbitrary file. Your server has no way of knowing what
-code it's going to run. Very dangerous.
-
-If the file is pulled in by C<perl_parse()>, compiled into a newly
-constructed interpreter, and subsequently cleaned out with
-C<perl_destruct()> afterwards, you're shielded from most namespace
-troubles.
-
-One way to avoid namespace collisions in this scenario is to translate
-the filename into a guaranteed-unique package name, and then compile
-the code into that package using L<perlfunc/eval>. In the example
-below, each file will only be compiled once. Or, the application
-might choose to clean out the symbol table associated with the file
-after it's no longer needed. Using L<perlapi/call_argv>, We'll
-call the subroutine C<Embed::Persistent::eval_file> which lives in the
-file C<persistent.pl> and pass the filename and boolean cleanup/cache
-flag as arguments.
-
-Note that the process will continue to grow for each file that it
-uses. In addition, there might be C<AUTOLOAD>ed subroutines and other
-conditions that cause Perl's symbol table to grow. You might want to
-add some logic that keeps track of the process size, or restarts
-itself after a certain number of requests, to ensure that memory
-consumption is minimized. You'll also want to scope your variables
-with L<perlfunc/my> whenever possible.
-
-
- package Embed::Persistent;
- #persistent.pl
-
- use strict;
- our %Cache;
- use Symbol qw(delete_package);
-
- sub valid_package_name {
- my($string) = @_;
- $string =~ s/([^A-Za-z0-9\/])/sprintf("_%2x",unpack("C",$1))/eg;
- # second pass only for words starting with a digit
- $string =~ s|/(\d)|sprintf("/_%2x",unpack("C",$1))|eg;
-
- # Dress it up as a real package name
- $string =~ s|/|::|g;
- return "Embed" . $string;
- }
-
- sub eval_file {
- my($filename, $delete) = @_;
- my $package = valid_package_name($filename);
- my $mtime = -M $filename;
- if(defined $Cache{$package}{mtime}
- &&
- $Cache{$package}{mtime} <= $mtime)
- {
- # we have compiled this subroutine already,
- # it has not been updated on disk, nothing left to do
- print STDERR "already compiled $package->handler\n";
- }
- else {
- local *FH;
- open FH, $filename or die "open '$filename' $!";
- local($/) = undef;
- my $sub = <FH>;
- close FH;
-
- #wrap the code into a subroutine inside our unique package
- my $eval = qq{package $package; sub handler { $sub; }};
- {
- # hide our variables within this block
- my($filename,$mtime,$package,$sub);
- eval $eval;
- }
- die $@ if $@;
-
- #cache it unless we're cleaning out each time
- $Cache{$package}{mtime} = $mtime unless $delete;
- }
-
- eval {$package->handler;};
- die $@ if $@;
-
- delete_package($package) if $delete;
-
- #take a look if you want
- #print Devel::Symdump->rnew($package)->as_string, $/;
- }
-
- 1;
-
- __END__
-
- /* persistent.c */
- #include <EXTERN.h>
- #include <perl.h>
-
- /* 1 = clean out filename's symbol table after each request, 0 = don't */
- #ifndef DO_CLEAN
- #define DO_CLEAN 0
- #endif
-
- #define BUFFER_SIZE 1024
-
- static PerlInterpreter *my_perl = NULL;
-
- int
- main(int argc, char **argv, char **env)
- {
- char *embedding[] = { "", "persistent.pl" };
- char *args[] = { "", DO_CLEAN, NULL };
- char filename[BUFFER_SIZE];
- int exitstatus = 0;
-
- PERL_SYS_INIT3(&argc,&argv,&env);
- if((my_perl = perl_alloc()) == NULL) {
- fprintf(stderr, "no memory!");
- exit(1);
- }
- perl_construct(my_perl);
-
- PL_origalen = 1; /* don't let $0 assignment update the proctitle or embedding[0] */
- exitstatus = perl_parse(my_perl, NULL, 2, embedding, NULL);
- PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
- if(!exitstatus) {
- exitstatus = perl_run(my_perl);
-
- while(printf("Enter file name: ") &&
- fgets(filename, BUFFER_SIZE, stdin)) {
-
- filename[strlen(filename)-1] = '\0'; /* strip \n */
- /* call the subroutine, passing it the filename as an argument */
- args[0] = filename;
- call_argv("Embed::Persistent::eval_file",
- G_DISCARD | G_EVAL, args);
-
- /* check $@ */
- if(SvTRUE(ERRSV))
- fprintf(stderr, "eval error: %s\n", SvPV_nolen(ERRSV));
- }
- }
-
- PL_perl_destruct_level = 0;
- perl_destruct(my_perl);
- perl_free(my_perl);
- PERL_SYS_TERM();
- exit(exitstatus);
- }
-
-Now compile:
-
- % cc -o persistent persistent.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
-
-Here's an example script file:
-
- #test.pl
- my $string = "hello";
- foo($string);
-
- sub foo {
- print "foo says: @_\n";
- }
-
-Now run:
-
- % persistent
- Enter file name: test.pl
- foo says: hello
- Enter file name: test.pl
- already compiled Embed::test_2epl->handler
- foo says: hello
- Enter file name: ^C
-
-=head2 Execution of END blocks
-
-Traditionally END blocks have been executed at the end of the perl_run.
-This causes problems for applications that never call perl_run. Since
-perl 5.7.2 you can specify C<PL_exit_flags |= PERL_EXIT_DESTRUCT_END>
-to get the new behaviour. This also enables the running of END blocks if
-the perl_parse fails and C<perl_destruct> will return the exit value.
-
-=head2 $0 assignments
-
-When a perl script assigns a value to $0 then the perl runtime will
-try to make this value show up as the program name reported by "ps" by
-updating the memory pointed to by the argv passed to perl_parse() and
-also calling API functions like setproctitle() where available. This
-behaviour might not be appropriate when embedding perl and can be
-disabled by assigning the value C<1> to the variable C<PL_origalen>
-before perl_parse() is called.
-
-The F<persistent.c> example above is for instance likely to segfault
-when $0 is assigned to if the C<PL_origalen = 1;> assignment is
-removed. This because perl will try to write to the read only memory
-of the C<embedding[]> strings.
-
-=head2 Maintaining multiple interpreter instances
-
-Some rare applications will need to create more than one interpreter
-during a session. Such an application might sporadically decide to
-release any resources associated with the interpreter.
-
-The program must take care to ensure that this takes place I<before>
-the next interpreter is constructed. By default, when perl is not
-built with any special options, the global variable
-C<PL_perl_destruct_level> is set to C<0>, since extra cleaning isn't
-usually needed when a program only ever creates a single interpreter
-in its entire lifetime.
-
-Setting C<PL_perl_destruct_level> to C<1> makes everything squeaky clean:
-
- while(1) {
- ...
- /* reset global variables here with PL_perl_destruct_level = 1 */
- PL_perl_destruct_level = 1;
- perl_construct(my_perl);
- ...
- /* clean and reset _everything_ during perl_destruct */
- PL_perl_destruct_level = 1;
- perl_destruct(my_perl);
- perl_free(my_perl);
- ...
- /* let's go do it again! */
- }
-
-When I<perl_destruct()> is called, the interpreter's syntax parse tree
-and symbol tables are cleaned up, and global variables are reset. The
-second assignment to C<PL_perl_destruct_level> is needed because
-perl_construct resets it to C<0>.
-
-Now suppose we have more than one interpreter instance running at the
-same time. This is feasible, but only if you used the Configure option
-C<-Dusemultiplicity> or the options C<-Dusethreads -Duseithreads> when
-building perl. By default, enabling one of these Configure options
-sets the per-interpreter global variable C<PL_perl_destruct_level> to
-C<1>, so that thorough cleaning is automatic and interpreter variables
-are initialized correctly. Even if you don't intend to run two or
-more interpreters at the same time, but to run them sequentially, like
-in the above example, it is recommended to build perl with the
-C<-Dusemultiplicity> option otherwise some interpreter variables may
-not be initialized correctly between consecutive runs and your
-application may crash.
-
-See also L<perlxs/Thread-aware system interfaces>.
-
-Using C<-Dusethreads -Duseithreads> rather than C<-Dusemultiplicity>
-is more appropriate if you intend to run multiple interpreters
-concurrently in different threads, because it enables support for
-linking in the thread libraries of your system with the interpreter.
-
-Let's give it a try:
-
-
- #include <EXTERN.h>
- #include <perl.h>
-
- /* we're going to embed two interpreters */
-
- #define SAY_HELLO "-e", "print qq(Hi, I'm $^X\n)"
-
- int main(int argc, char **argv, char **env)
- {
- PerlInterpreter *one_perl, *two_perl;
- char *one_args[] = { "one_perl", SAY_HELLO };
- char *two_args[] = { "two_perl", SAY_HELLO };
-
- PERL_SYS_INIT3(&argc,&argv,&env);
- one_perl = perl_alloc();
- two_perl = perl_alloc();
-
- PERL_SET_CONTEXT(one_perl);
- perl_construct(one_perl);
- PERL_SET_CONTEXT(two_perl);
- perl_construct(two_perl);
-
- PERL_SET_CONTEXT(one_perl);
- perl_parse(one_perl, NULL, 3, one_args, (char **)NULL);
- PERL_SET_CONTEXT(two_perl);
- perl_parse(two_perl, NULL, 3, two_args, (char **)NULL);
-
- PERL_SET_CONTEXT(one_perl);
- perl_run(one_perl);
- PERL_SET_CONTEXT(two_perl);
- perl_run(two_perl);
-
- PERL_SET_CONTEXT(one_perl);
- perl_destruct(one_perl);
- PERL_SET_CONTEXT(two_perl);
- perl_destruct(two_perl);
-
- PERL_SET_CONTEXT(one_perl);
- perl_free(one_perl);
- PERL_SET_CONTEXT(two_perl);
- perl_free(two_perl);
- PERL_SYS_TERM();
- }
-
-Note the calls to PERL_SET_CONTEXT(). These are necessary to initialize
-the global state that tracks which interpreter is the "current" one on
-the particular process or thread that may be running it. It should
-always be used if you have more than one interpreter and are making
-perl API calls on both interpreters in an interleaved fashion.
-
-PERL_SET_CONTEXT(interp) should also be called whenever C<interp> is
-used by a thread that did not create it (using either perl_alloc(), or
-the more esoteric perl_clone()).
-
-Compile as usual:
-
- % cc -o multiplicity multiplicity.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
-
-Run it, Run it:
-
- % multiplicity
- Hi, I'm one_perl
- Hi, I'm two_perl
-
-=head2 Using Perl modules, which themselves use C libraries, from your C program
-
-If you've played with the examples above and tried to embed a script
-that I<use()>s a Perl module (such as I<Socket>) which itself uses a C or C++ library,
-this probably happened:
-
-
- Can't load module Socket, dynamic loading not available in this perl.
- (You may need to build a new perl executable which either supports
- dynamic loading or has the Socket module statically linked into it.)
-
-
-What's wrong?
-
-Your interpreter doesn't know how to communicate with these extensions
-on its own. A little glue will help. Up until now you've been
-calling I<perl_parse()>, handing it NULL for the second argument:
-
- perl_parse(my_perl, NULL, argc, my_argv, NULL);
-
-That's where the glue code can be inserted to create the initial contact between
-Perl and linked C/C++ routines. Let's take a look some pieces of I<perlmain.c>
-to see how Perl does this:
-
- static void xs_init (pTHX);
-
- EXTERN_C void boot_DynaLoader (pTHX_ CV* cv);
- EXTERN_C void boot_Socket (pTHX_ CV* cv);
-
-
- EXTERN_C void
- xs_init(pTHX)
- {
- char *file = __FILE__;
- /* DynaLoader is a special case */
- newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file);
- newXS("Socket::bootstrap", boot_Socket, file);
- }
-
-Simply put: for each extension linked with your Perl executable
-(determined during its initial configuration on your
-computer or when adding a new extension),
-a Perl subroutine is created to incorporate the extension's
-routines. Normally, that subroutine is named
-I<Module::bootstrap()> and is invoked when you say I<use Module>. In
-turn, this hooks into an XSUB, I<boot_Module>, which creates a Perl
-counterpart for each of the extension's XSUBs. Don't worry about this
-part; leave that to the I<xsubpp> and extension authors. If your
-extension is dynamically loaded, DynaLoader creates I<Module::bootstrap()>
-for you on the fly. In fact, if you have a working DynaLoader then there
-is rarely any need to link in any other extensions statically.
-
-
-Once you have this code, slap it into the second argument of I<perl_parse()>:
-
-
- perl_parse(my_perl, xs_init, argc, my_argv, NULL);
-
-
-Then compile:
-
- % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
-
- % interp
- use Socket;
- use SomeDynamicallyLoadedModule;
-
- print "Now I can use extensions!\n"'
-
-B<ExtUtils::Embed> can also automate writing the I<xs_init> glue code.
-
- % perl -MExtUtils::Embed -e xsinit -- -o perlxsi.c
- % cc -c perlxsi.c `perl -MExtUtils::Embed -e ccopts`
- % cc -c interp.c `perl -MExtUtils::Embed -e ccopts`
- % cc -o interp perlxsi.o interp.o `perl -MExtUtils::Embed -e ldopts`
-
-Consult L<perlxs>, L<perlguts>, and L<perlapi> for more details.
-
-=head1 Hiding Perl_
-
-If you completely hide the short forms of the Perl public API,
-add -DPERL_NO_SHORT_NAMES to the compilation flags. This means that
-for example instead of writing
-
- warn("%d bottles of beer on the wall", bottlecount);
-
-you will have to write the explicit full form
-
- Perl_warn(aTHX_ "%d bottles of beer on the wall", bottlecount);
-
-(See L<perlguts/"Background and PERL_IMPLICIT_CONTEXT"> for the explanation
-of the C<aTHX_>. ) Hiding the short forms is very useful for avoiding
-all sorts of nasty (C preprocessor or otherwise) conflicts with other
-software packages (Perl defines about 2400 APIs with these short names,
-take or leave few hundred, so there certainly is room for conflict.)
-
-=head1 MORAL
-
-You can sometimes I<write faster code> in C, but
-you can always I<write code faster> in Perl. Because you can use
-each from the other, combine them as you wish.
-
-
-=head1 AUTHOR
-
-Jon Orwant <F<orwant@media.mit.edu>> and Doug MacEachern
-<F<dougm@covalent.net>>, with small contributions from Tim Bunce, Tom
-Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya
-Zakharevich.
-
-Doug MacEachern has an article on embedding in Volume 1, Issue 4 of
-The Perl Journal ( http://www.tpj.com/ ). Doug is also the developer of the
-most widely-used Perl embedding: the mod_perl system
-(perl.apache.org), which embeds Perl in the Apache web server.
-Oracle, Binary Evolution, ActiveState, and Ben Sugars's nsapi_perl
-have used this model for Oracle, Netscape and Internet Information
-Server Perl plugins.
-
-=head1 COPYRIGHT
-
-Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant. All
-Rights Reserved.
-
-This document may be distributed under the same terms as Perl itself.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlepoc.pod b/Master/tlpkg/tlperl/lib/pods/perlepoc.pod
deleted file mode 100644
index f5773506ff4..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlepoc.pod
+++ /dev/null
@@ -1,154 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see pod/perlpod.pod) which is
-specially designed to be readable as is.
-
-=head1 NAME
-
-perlepoc - Perl for EPOC
-
-=head1 SYNOPSIS
-
-Perl 5 README file for the EPOC Release 5 operating system.
-
-=head1 INTRODUCTION
-
-EPOC is an OS for palmtops and mobile phones. For more information look
-at: L<http://www.symbian.com/>
-
-This is a port of perl to the epocemx SDK by Eberhard Mattes, which
-itself uses the SDK by symbian. Essentially epocemx it is a POSIX
-look alike environment for the EPOC OS. For more information look at:
-L<http://epocemx.sourceforge.net/>
-
-perl and epocemx runs on Epoc Release 5 machines: Psion 5mx, 5mx Pro,
-Psion Revo, Psion Netbook and on the Ericsson M128. It may run on Epoc
-Release 3 Hardware (Series 5 classic), too. For more information about
-this hardware please refer to L<http://www.psion.com/>
-
-Vendors which like to have support for their devices are free to send
-me a sample.
-
-=head1 INSTALLING PERL ON EPOC
-
-You can download a ready-to-install version from
-L<http://www.oflebbe.de/perl/perl5.html>
-
-You will need at least ~6MB free space in order to install and run perl.
-
-Please install the emxusr.sis package from
-L<http://epocemx.sourceforge.net/> first.
-
-Install perl.sis on the EPOC machine. If you do not know how to do
-that, consult your PsiWin documentation.
-
-Perl itself and its standard library is using 4 MB disk space.
-Unicode support and some other modules are left out. (For details,
-please look into epoc/createpkg.pl). If you like to use these modules,
-you are free to copy them from a current perl release.
-
-=head1 STARTING PERL ON EPOC
-
-Please use the epocemx shell to start perl. perl integrates with the
-conventions of epocemx.
-
-=head2 Features of Perl on Epoc
-
-The built-in function EPOC::getcwd returns the current directory.
-
-=head2 Restrictions of Perl on Epoc
-
-Features are left out, because of restrictions of the POSIX support in
-EPOC:
-
-=over 4
-
-=item *
-
-socket IO is only implemented poorly. You can only use sysread and
-syswrite on them. The commands read, write, print, <> do not work for
-sockets. This may change iff epocemx supports sockets.
-
-=item *
-
-kill, alarm and signals. Do not try to use them. This may be
-impossible to implement on EPOC.
-
-=item *
-
-select is missing.
-
-=item *
-
-binmode does not exist. (No CR LF to LF translation for text files)
-
-=item *
-
-EPOC does not handle the notion of current drive and current
-directory very well (i.e. not at all, but it tries hard to emulate
-one). See PATH.
-
-=item *
-
-Heap is limited to 4MB.
-
-=item *
-
-Dynamic loading is not implemented.
-
-=back
-
-=head2 Compiling Perl 5 on the EPOC cross compiling environment
-
-Sorry, this is far too short.
-
-=over 4
-
-=item *
-
-You will need the epocemx SDK from Eberhard Mattes.
-
-=item *
-
-Get the Perl sources from your nearest CPAN site.
-
-=item *
-
-Unpack the sources.
-
-=item *
-
-Build a native perl from this sources... Make sure to save the
-miniperl executable as miniperl.native.
-
-Start again from scratch
-
- cp epoc/* .
- ./Configure -S
- make
- cp miniperl.native miniperl
- touch miniperl.exe
- make
- perl createpkg.pl
-
- emxsis perl.pkg perl.sis
-
-=back
-
-=head1 SUPPORT STATUS OF PERL ON EPOC
-
-I'm offering this port "as is". You can ask me questions, but I can't
-guarantee I'll be able to answer them. Since the port to epocemx is
-quite new, please check the web for updates first.
-
-Very special thanks to Eberhard Mattes for epocemx.
-
-=head1 AUTHOR
-
-Olaf Flebbe <olaf@oflebbe.de>
-L<http://www.oflebbe.de/perl/perl5.html>
-
-=head1 LAST UPDATE
-
-2003-01-18
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlexperiment.pod b/Master/tlpkg/tlperl/lib/pods/perlexperiment.pod
deleted file mode 100644
index f304120bc66..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlexperiment.pod
+++ /dev/null
@@ -1,305 +0,0 @@
-=head1 NAME
-
-perlexperiment - A listing of experimental features in Perl
-
-=head1 DESCRIPTION
-
-This document lists the current and past experimental features in the perl
-core. Although all of these are documented with their appropriate topics,
-this succinct listing gives you an overview and basic facts about their
-status.
-
-So far I've merely tried to find and list the experimental features and infer
-their inception, versions, etc. There's a lot of speculation here.
-
-=head2 Current experiments
-
-=over 8
-
-=item fork() emulation
-
-Introduced in Perl 5.6.1
-
-See also L<perlfork>
-
-=item Weak references
-
-Introduced in Perl 5.6.0
-
-=item Internal file glob
-
-Introduced in Perl 5.6.0
-
-Accepted in XXX
-
-=item 64-bit support
-
-Introduced in Perl 5.005
-
-Accepted in XXX
-
-=item die accepts a reference
-
-Introduced in Perl 5.005
-
-Accepted in Perl XXX
-
-=item Unicode support
-
-Introduced in Perl 5.6.0
-
-Accepted in Perl 5.8.0 XXX
-
-=item -Dusemultiplicity -Dusethreads
-
-Introduced in Perl 5.6.0
-
-=item Long Doubles Still Don't Work In Solaris
-
-Introduced in Perl 5.7.0
-
-=item GetOpt::Long Options can now take multiple values at once (experimental)
-
-C<Getopt::Long> upgraded to version 2.35
-
-Removed in Perl 5.8.8
-
-=item 5.005-style threading
-
-Introduced in Perl 5.005
-
-Removed in Perl 5.10 XXX
-
-=item Test::Harness::Straps
-
-Removed in Perl 5.10.1
-
-=item perlcc
-
-Introduced in Perl 5.005
-
-Removed in Perl 5.9.0
-
-=item C<our> can now have an experimental optional attribute C<unique>
-
-Introduced in Perl 5.8.0
-
-Deprecated in Perl 5.10.0
-
-=item Assertions
-
-The C<-A> command line switch
-
-Introduced in Perl 5.9.0
-
-Removed in Perl 5.9.5
-
-=item Linux abstract Unix domain sockets
-
-Introduced in Perl 5.9.2
-
-See also L<Socket>
-
-=item L<Pod::HTML2Pod|Pod::HTML2Pod>
-
-=item L<Pod::PXML|Pod::PXML>
-
-=item threads
-
-=item The <:pop> IO pseudolayer
-
-See also L<perlrun>
-
-=item The <:win32> IO pseudolayer
-
-See also L<perlrun>
-
-=item MLDBM
-
-See also L<perldsc>
-
-=item internal functions with M flag
-
-See also L<perlguts>
-
-=item lex_start API
-
-Introduced in Perl 5.13.7
-
-=item internal API for C<%H>
-
-Introduced in Perl 5.13.7
-
-See also C<cophh_> in L<perlapi>.
-
-=item av_create_and_push
-
-=item av_create_and_unshift_one
-
-=item av_create_and_unshift_one
-
-=item PL_keyword_plugin
-
-=item hv_iternext_flags
-
-=item lex_bufutf8
-
-=item lex_discard_to
-
-=item lex_grow_linestr
-
-=item lex_next_chunk
-
-=item lex_peek_unichar
-
-=item lex_read_space
-
-=item lex_read_to
-
-=item lex_read_unichar
-
-=item lex_stuff_pv
-
-=item lex_stuff_pvn
-
-=item lex_stuff_pvs
-
-=item lex_stuff_sv
-
-=item lex_unstuff
-
-=item parse_fullstmt
-
-=item parse_stmtseq
-
-=item PL_parser-E<gt>bufend
-
-=item PL_parser-E<gt>bufptr
-
-=item PL_parser-E<gt>linestart
-
-=item PL_parser-E<gt>linestr
-
-=item Perl_signbit
-
-=item pad_findmy
-
-=item sv_utf8_decode
-
-=item sv_utf8_downgrade
-
-=item bytes_from_utf8
-
-=item bytes_to_utf8
-
-=item utf8_to_bytes
-
-=item DB module
-
-Introduced in Perl 5.6.0
-
-See also L<perldebug>, L<perldebtut>
-
-=item The pseudo-hash data type
-
-Introduced in Perl 5.6.0
-
-=item Lvalue subroutines
-
-Introduced in Perl 5.6.0
-
-See also L<perlsub>
-
-=item There is an C<installhtml> target in the Makefile.
-
-=item Unicode in Perl on EBCDIC
-
-=item C<(?{code})>
-
-See also L<perlre>
-
-=item C<(??{ code })>
-
-See also L<perlre>
-
-=item Backtracking control verbs
-
-C<(*ACCEPT)>
-
-Introduced in: Perl 5.10
-
-See also: L<perlre/"Special Backtracking Control Verbs">
-
-=item Code expressions, conditional expressions, and independent expressions in regexes
-
-=item The C<\N> regex character class
-
-The C<\N> character class, not to be confused with the named character
-sequence C<\N{NAME}>, denotes any non-newline character in a regular
-expression.
-
-Introduced in: Perl 5.12
-
-See also:
-
-=item gv_try_downgrade
-
-See also L<perlintern>
-
-=item Experimental Support for Sun Studio Compilers for Linux OS
-
-See also L<perllinux>
-
-=item Pluggable keywords
-
-See L<perlapi/PL_keyword_plugin> for the mechanism.
-
-Introduced in: Perl 5.11.2
-
-=back
-
-=head2 Accepted features
-
-These features were so wildly successful and played so well with others that
-we decided to remove their experimental status and admit them as full, stable
-features in the world of Perl, lavishing all the benefits and luxuries thereof.
-They are also awarded +5 Stability and +3 Charisma.
-
-=over 8
-
-=item (none yet identified)
-
-=back
-
-=head2 Removed features
-
-These features are no longer considered experimental and their functionality
-has disappeared. It's your own fault if you wrote production programs using
-these features after we explicitly told you not to (see L<perlpolicy>).
-
-=over 8
-
-=item C<legacy>
-
-The experimental C<legacy> pragma was swallowed by the C<feature> pragma.
-
-Introduced in: 5.11.2
-
-Removed in: 5.11.3
-
-=back
-
-=head1 AUTHORS
-
-brian d foy C<< <brian.d.foy@gmail.com> >>
-
-=head1 COPYRIGHT
-
-Copyright 2010, brian d foy C<< <brian.d.foy@gmail.com> >>
-
-=head1 LICENSE
-
-You can use and redistribute this document under the same terms as Perl
-itself.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq.pod
deleted file mode 100644
index 449c0a2de84..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlfaq.pod
+++ /dev/null
@@ -1,1373 +0,0 @@
-=head1 NAME
-
-perlfaq - frequently asked questions about Perl
-
-=head1 DESCRIPTION
-
-The perlfaq comprises several documents that answer the most commonly
-asked questions about Perl and Perl programming. It's divided by topic
-into nine major sections outlined in this document.
-
-=head2 Where to find the perlfaq
-
-The perlfaq is an evolving document. Read the latest version at
-L<http://learn.perl.org/faq/>. It is also included in the standard Perl
-distribution.
-
-=head2 How to use the perlfaq
-
-The C<perldoc> command line tool is part of the standard Perl distribution. To
-read the perlfaq:
-
- $ perldoc perlfaq
-
-To search the perlfaq question headings:
-
- $ perldoc -q open
-
-=head2 How to contribute to the perlfaq
-
-Review L<https://github.com/perl-doc-cats/perlfaq/wiki>. If you don't find
-your suggestion create an issue or pull request against
-L<https://github.com/perl-doc-cats/perlfaq>.
-
-Once approved, changes are merged into L<https://github.com/tpf/perlfaq>, the
-repository which drives L<http://learn.perl.org/faq/>, and they are
-distributed with the next Perl 5 release.
-
-=head2 What if my question isn't answered in the FAQ?
-
-Try the resources in L<perlfaq2>.
-
-=head1 TABLE OF CONTENTS
-
-=over 4
-
-=item perlfaq1 - General Questions About Perl
-
-=item perlfaq2 - Obtaining and Learning about Perl
-
-=item perlfaq3 - Programming Tools
-
-=item perlfaq4 - Data Manipulation
-
-=item perlfaq5 - Files and Formats
-
-=item perlfaq6 - Regular Expressions
-
-=item perlfaq7 - General Perl Language Issues
-
-=item perlfaq8 - System Interaction
-
-=item perlfaq9 - Web, Email and Networking
-
-=back
-
-=head1 THE QUESTIONS
-
-=head2 L<perlfaq1>: General Questions About Perl
-
-This section of the FAQ answers very general, high-level questions about Perl.
-
-=over 4
-
-=item *
-
-What is Perl?
-
-=item *
-
-Who supports Perl? Who develops it? Why is it free?
-
-=item *
-
-Which version of Perl should I use?
-
-=item *
-
-What are Perl 4, Perl 5, or Perl 6?
-
-=item *
-
-What is Perl 6?
-
-=item *
-
-How stable is Perl?
-
-=item *
-
-Is Perl difficult to learn?
-
-=item *
-
-How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl?
-
-=item *
-
-Can I do [task] in Perl?
-
-=item *
-
-When shouldn't I program in Perl?
-
-=item *
-
-What's the difference between "perl" and "Perl"?
-
-=item *
-
-What is a JAPH?
-
-=item *
-
-How can I convince others to use Perl?
-
-=back
-
-
-=head2 L<perlfaq2>: Obtaining and Learning about Perl
-
-This section of the FAQ answers questions about where to find source and documentation for Perl, support, and related matters.
-
-=over 4
-
-=item *
-
-What machines support Perl? Where do I get it?
-
-=item *
-
-How can I get a binary version of Perl?
-
-=item *
-
-I don't have a C compiler. How can I build my own Perl interpreter?
-
-=item *
-
-I copied the Perl binary from one machine to another, but scripts don't work.
-
-=item *
-
-I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work?
-
-=item *
-
-What modules and extensions are available for Perl? What is CPAN?
-
-=item *
-
-Where can I get information on Perl?
-
-=item *
-
-What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?
-
-=item *
-
-Where can I post questions?
-
-=item *
-
-Perl Books
-
-=item *
-
-Which magazines have Perl content?
-
-=item *
-
-Which Perl blogs should I read?
-
-=item *
-
-What mailing lists are there for Perl?
-
-=item *
-
-Where can I buy a commercial version of Perl?
-
-=item *
-
-Where do I send bug reports?
-
-=back
-
-
-=head2 L<perlfaq3>: Programming Tools
-
-This section of the FAQ answers questions related to programmer tools and programming support.
-
-=over 4
-
-=item *
-
-How do I do (anything)?
-
-=item *
-
-How can I use Perl interactively?
-
-=item *
-
-How do I find which modules are installed on my system?
-
-=item *
-
-How do I debug my Perl programs?
-
-=item *
-
-How do I profile my Perl programs?
-
-=item *
-
-How do I cross-reference my Perl programs?
-
-=item *
-
-Is there a pretty-printer (formatter) for Perl?
-
-=item *
-
-Is there an IDE or Windows Perl Editor?
-
-=item *
-
-Where can I get Perl macros for vi?
-
-=item *
-
-Where can I get perl-mode or cperl-mode for emacs?
-
-=item *
-
-How can I use curses with Perl?
-
-=item *
-
-How can I write a GUI (X, Tk, Gtk, etc.) in Perl?
-
-=item *
-
-How can I make my Perl program run faster?
-
-=item *
-
-How can I make my Perl program take less memory?
-
-=item *
-
-Is it safe to return a reference to local or lexical data?
-
-=item *
-
-How can I free an array or hash so my program shrinks?
-
-=item *
-
-How can I make my CGI script more efficient?
-
-=item *
-
-How can I hide the source for my Perl program?
-
-=item *
-
-How can I compile my Perl program into byte code or C?
-
-=item *
-
-How can I get C<#!perl> to work on [MS-DOS,NT,...]?
-
-=item *
-
-Can I write useful Perl programs on the command line?
-
-=item *
-
-Why don't Perl one-liners work on my DOS/Mac/VMS system?
-
-=item *
-
-Where can I learn about CGI or Web programming in Perl?
-
-=item *
-
-Where can I learn about object-oriented Perl programming?
-
-=item *
-
-Where can I learn about linking C with Perl?
-
-=item *
-
-I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong?
-
-=item *
-
-When I tried to run my script, I got this message. What does it mean?
-
-=item *
-
-What's MakeMaker?
-
-=back
-
-
-=head2 L<perlfaq4>: Data Manipulation
-
-This section of the FAQ answers questions related to manipulating numbers, dates, strings, arrays, hashes, and miscellaneous data issues.
-
-=over 4
-
-=item *
-
-Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?
-
-=item *
-
-Why is int() broken?
-
-=item *
-
-Why isn't my octal data interpreted correctly?
-
-=item *
-
-Does Perl have a round() function? What about ceil() and floor()? Trig functions?
-
-=item *
-
-How do I convert between numeric representations/bases/radixes?
-
-=item *
-
-Why doesn't & work the way I want it to?
-
-=item *
-
-How do I multiply matrices?
-
-=item *
-
-How do I perform an operation on a series of integers?
-
-=item *
-
-How can I output Roman numerals?
-
-=item *
-
-Why aren't my random numbers random?
-
-=item *
-
-How do I get a random number between X and Y?
-
-=item *
-
-How do I find the day or week of the year?
-
-=item *
-
-How do I find the current century or millennium?
-
-=item *
-
-How can I compare two dates and find the difference?
-
-=item *
-
-How can I take a string and turn it into epoch seconds?
-
-=item *
-
-How can I find the Julian Day?
-
-=item *
-
-How do I find yesterday's date?
-
-=item *
-
-Does Perl have a Year 2000 or 2038 problem? Is Perl Y2K compliant?
-
-=item *
-
-How do I validate input?
-
-=item *
-
-How do I unescape a string?
-
-=item *
-
-How do I remove consecutive pairs of characters?
-
-=item *
-
-How do I expand function calls in a string?
-
-=item *
-
-How do I find matching/nesting anything?
-
-=item *
-
-How do I reverse a string?
-
-=item *
-
-How do I expand tabs in a string?
-
-=item *
-
-How do I reformat a paragraph?
-
-=item *
-
-How can I access or change N characters of a string?
-
-=item *
-
-How do I change the Nth occurrence of something?
-
-=item *
-
-How can I count the number of occurrences of a substring within a string?
-
-=item *
-
-How do I capitalize all the words on one line?
-
-=item *
-
-How can I split a [character]-delimited string except when inside [character]?
-
-=item *
-
-How do I strip blank space from the beginning/end of a string?
-
-=item *
-
-How do I pad a string with blanks or pad a number with zeroes?
-
-=item *
-
-How do I extract selected columns from a string?
-
-=item *
-
-How do I find the soundex value of a string?
-
-=item *
-
-How can I expand variables in text strings?
-
-=item *
-
-What's wrong with always quoting "$vars"?
-
-=item *
-
-Why don't my E<lt>E<lt>HERE documents work?
-
-=item *
-
-What is the difference between a list and an array?
-
-=item *
-
-What is the difference between $array[1] and @array[1]?
-
-=item *
-
-How can I remove duplicate elements from a list or array?
-
-=item *
-
-How can I tell whether a certain element is contained in a list or array?
-
-=item *
-
-How do I compute the difference of two arrays? How do I compute the intersection of two arrays?
-
-=item *
-
-How do I test whether two arrays or hashes are equal?
-
-=item *
-
-How do I find the first array element for which a condition is true?
-
-=item *
-
-How do I handle linked lists?
-
-=item *
-
-How do I handle circular lists?
-
-=item *
-
-How do I shuffle an array randomly?
-
-=item *
-
-How do I process/modify each element of an array?
-
-=item *
-
-How do I select a random element from an array?
-
-=item *
-
-How do I permute N elements of a list?
-
-=item *
-
-How do I sort an array by (anything)?
-
-=item *
-
-How do I manipulate arrays of bits?
-
-=item *
-
-Why does defined() return true on empty arrays and hashes?
-
-=item *
-
-How do I process an entire hash?
-
-=item *
-
-How do I merge two hashes?
-
-=item *
-
-What happens if I add or remove keys from a hash while iterating over it?
-
-=item *
-
-How do I look up a hash element by value?
-
-=item *
-
-How can I know how many entries are in a hash?
-
-=item *
-
-How do I sort a hash (optionally by value instead of key)?
-
-=item *
-
-How can I always keep my hash sorted?
-
-=item *
-
-What's the difference between "delete" and "undef" with hashes?
-
-=item *
-
-Why don't my tied hashes make the defined/exists distinction?
-
-=item *
-
-How do I reset an each() operation part-way through?
-
-=item *
-
-How can I get the unique keys from two hashes?
-
-=item *
-
-How can I store a multidimensional array in a DBM file?
-
-=item *
-
-How can I make my hash remember the order I put elements into it?
-
-=item *
-
-Why does passing a subroutine an undefined element in a hash create it?
-
-=item *
-
-How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays?
-
-=item *
-
-How can I use a reference as a hash key?
-
-=item *
-
-How can I check if a key exists in a multilevel hash?
-
-=item *
-
-How can I prevent addition of unwanted keys into a hash?
-
-=item *
-
-How do I handle binary data correctly?
-
-=item *
-
-How do I determine whether a scalar is a number/whole/integer/float?
-
-=item *
-
-How do I keep persistent data across program calls?
-
-=item *
-
-How do I print out or copy a recursive data structure?
-
-=item *
-
-How do I define methods for every class/object?
-
-=item *
-
-How do I verify a credit card checksum?
-
-=item *
-
-How do I pack arrays of doubles or floats for XS code?
-
-=back
-
-
-=head2 L<perlfaq5>: Files and Formats
-
-This section deals with I/O and the "f" issues: filehandles, flushing, formats, and footers.
-
-=over 4
-
-=item *
-
-How do I flush/unbuffer an output filehandle? Why must I do this?
-
-=item *
-
-How do I change, delete, or insert a line in a file, or append to the beginning of a file?
-
-=item *
-
-How do I count the number of lines in a file?
-
-=item *
-
-How do I delete the last N lines from a file?
-
-=item *
-
-How can I use Perl's C<-i> option from within a program?
-
-=item *
-
-How can I copy a file?
-
-=item *
-
-How do I make a temporary file name?
-
-=item *
-
-How can I manipulate fixed-record-length files?
-
-=item *
-
-How can I make a filehandle local to a subroutine? How do I pass filehandles between subroutines? How do I make an array of filehandles?
-
-=item *
-
-How can I use a filehandle indirectly?
-
-=item *
-
-How can I set up a footer format to be used with write()?
-
-=item *
-
-How can I write() into a string?
-
-=item *
-
-How can I open a filehandle to a string?
-
-=item *
-
-How can I output my numbers with commas added?
-
-=item *
-
-How can I translate tildes (~) in a filename?
-
-=item *
-
-How come when I open a file read-write it wipes it out?
-
-=item *
-
-Why do I sometimes get an "Argument list too long" when I use E<lt>*E<gt>?
-
-=item *
-
-How can I open a file with a leading "E<gt>" or trailing blanks?
-
-=item *
-
-How can I reliably rename a file?
-
-=item *
-
-How can I lock a file?
-
-=item *
-
-Why can't I just open(FH, "E<gt>file.lock")?
-
-=item *
-
-I still don't get locking. I just want to increment the number in the file. How can I do this?
-
-=item *
-
-All I want to do is append a small amount of text to the end of a file. Do I still have to use locking?
-
-=item *
-
-How do I randomly update a binary file?
-
-=item *
-
-How do I get a file's timestamp in perl?
-
-=item *
-
-How do I set a file's timestamp in perl?
-
-=item *
-
-How do I print to more than one file at once?
-
-=item *
-
-How can I read in an entire file all at once?
-
-=item *
-
-How can I read in a file by paragraphs?
-
-=item *
-
-How can I read a single character from a file? From the keyboard?
-
-=item *
-
-How can I tell whether there's a character waiting on a filehandle?
-
-=item *
-
-How do I do a C<tail -f> in perl?
-
-=item *
-
-How do I dup() a filehandle in Perl?
-
-=item *
-
-How do I close a file descriptor by number?
-
-=item *
-
-Why can't I use "C:\temp\foo" in DOS paths? Why doesn't `C:\temp\foo.exe` work?
-
-=item *
-
-Why doesn't glob("*.*") get all the files?
-
-=item *
-
-Why does Perl let me delete read-only files? Why does C<-i> clobber protected files? Isn't this a bug in Perl?
-
-=item *
-
-How do I select a random line from a file?
-
-=item *
-
-Why do I get weird spaces when I print an array of lines?
-
-=item *
-
-How do I traverse a directory tree?
-
-=item *
-
-How do I delete a directory tree?
-
-=item *
-
-How do I copy an entire directory?
-
-=back
-
-
-=head2 L<perlfaq6>: Regular Expressions
-
-This section is surprisingly small because the rest of the FAQ is littered with answers involving regular expressions. For example, decoding a URL and checking whether something is a number can be handled with regular expressions, but those answers are found elsewhere in this document (in perlfaq9 : "How do I decode or create those %-encodings on the web" and perlfaq4 : "How do I determine whether a scalar is a number/whole/integer/float", to be precise).
-
-=over 4
-
-=item *
-
-How can I hope to use regular expressions without creating illegible and unmaintainable code?
-
-=item *
-
-I'm having trouble matching over more than one line. What's wrong?
-
-=item *
-
-How can I pull out lines between two patterns that are themselves on different lines?
-
-=item *
-
-How do I match XML, HTML, or other nasty, ugly things with a regex?
-
-=item *
-
-I put a regular expression into $/ but it didn't work. What's wrong?
-
-=item *
-
-How do I substitute case-insensitively on the LHS while preserving case on the RHS?
-
-=item *
-
-How can I make C<\w> match national character sets?
-
-=item *
-
-How can I match a locale-smart version of C</[a-zA-Z]/> ?
-
-=item *
-
-How can I quote a variable to use in a regex?
-
-=item *
-
-What is C</o> really for?
-
-=item *
-
-How do I use a regular expression to strip C-style comments from a file?
-
-=item *
-
-Can I use Perl regular expressions to match balanced text?
-
-=item *
-
-What does it mean that regexes are greedy? How can I get around it?
-
-=item *
-
-How do I process each word on each line?
-
-=item *
-
-How can I print out a word-frequency or line-frequency summary?
-
-=item *
-
-How can I do approximate matching?
-
-=item *
-
-How do I efficiently match many regular expressions at once?
-
-=item *
-
-Why don't word-boundary searches with C<\b> work for me?
-
-=item *
-
-Why does using $&, $`, or $' slow my program down?
-
-=item *
-
-What good is C<\G> in a regular expression?
-
-=item *
-
-Are Perl regexes DFAs or NFAs? Are they POSIX compliant?
-
-=item *
-
-What's wrong with using grep in a void context?
-
-=item *
-
-How can I match strings with multibyte characters?
-
-=item *
-
-How do I match a regular expression that's in a variable?
-
-=back
-
-
-=head2 L<perlfaq7>: General Perl Language Issues
-
-This section deals with general Perl language issues that don't clearly fit into any of the other sections.
-
-=over 4
-
-=item *
-
-Can I get a BNF/yacc/RE for the Perl language?
-
-=item *
-
-What are all these $@%&* punctuation signs, and how do I know when to use them?
-
-=item *
-
-Do I always/never have to quote my strings or use semicolons and commas?
-
-=item *
-
-How do I skip some return values?
-
-=item *
-
-How do I temporarily block warnings?
-
-=item *
-
-What's an extension?
-
-=item *
-
-Why do Perl operators have different precedence than C operators?
-
-=item *
-
-How do I declare/create a structure?
-
-=item *
-
-How do I create a module?
-
-=item *
-
-How do I adopt or take over a module already on CPAN?
-
-=item *
-
-How do I create a class?
-
-=item *
-
-How can I tell if a variable is tainted?
-
-=item *
-
-What's a closure?
-
-=item *
-
-What is variable suicide and how can I prevent it?
-
-=item *
-
-How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?
-
-=item *
-
-How do I create a static variable?
-
-=item *
-
-What's the difference between dynamic and lexical (static) scoping? Between local() and my()?
-
-=item *
-
-How can I access a dynamic variable while a similarly named lexical is in scope?
-
-=item *
-
-What's the difference between deep and shallow binding?
-
-=item *
-
-Why doesn't "my($foo) = E<lt>$fhE<gt>;" work right?
-
-=item *
-
-How do I redefine a builtin function, operator, or method?
-
-=item *
-
-What's the difference between calling a function as &foo and foo()?
-
-=item *
-
-How do I create a switch or case statement?
-
-=item *
-
-How can I catch accesses to undefined variables, functions, or methods?
-
-=item *
-
-Why can't a method included in this same file be found?
-
-=item *
-
-How can I find out my current or calling package?
-
-=item *
-
-How can I comment out a large block of Perl code?
-
-=item *
-
-How do I clear a package?
-
-=item *
-
-How can I use a variable as a variable name?
-
-=item *
-
-What does "bad interpreter" mean?
-
-=back
-
-
-=head2 L<perlfaq8>: System Interaction
-
-This section of the Perl FAQ covers questions involving operating system interaction. Topics include interprocess communication (IPC), control over the user-interface (keyboard, screen and pointing devices), and most anything else not related to data manipulation.
-
-=over 4
-
-=item *
-
-How do I find out which operating system I'm running under?
-
-=item *
-
-How come exec() doesn't return?
-
-=item *
-
-How do I do fancy stuff with the keyboard/screen/mouse?
-
-=item *
-
-How do I print something out in color?
-
-=item *
-
-How do I read just one key without waiting for a return key?
-
-=item *
-
-How do I check whether input is ready on the keyboard?
-
-=item *
-
-How do I clear the screen?
-
-=item *
-
-How do I get the screen size?
-
-=item *
-
-How do I ask the user for a password?
-
-=item *
-
-How do I read and write the serial port?
-
-=item *
-
-How do I decode encrypted password files?
-
-=item *
-
-How do I start a process in the background?
-
-=item *
-
-How do I trap control characters/signals?
-
-=item *
-
-How do I modify the shadow password file on a Unix system?
-
-=item *
-
-How do I set the time and date?
-
-=item *
-
-How can I sleep() or alarm() for under a second?
-
-=item *
-
-How can I measure time under a second?
-
-=item *
-
-How can I do an atexit() or setjmp()/longjmp()? (Exception handling)
-
-=item *
-
-Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean?
-
-=item *
-
-How can I call my system's unique C functions from Perl?
-
-=item *
-
-Where do I get the include files to do ioctl() or syscall()?
-
-=item *
-
-Why do setuid perl scripts complain about kernel problems?
-
-=item *
-
-How can I open a pipe both to and from a command?
-
-=item *
-
-Why can't I get the output of a command with system()?
-
-=item *
-
-How can I capture STDERR from an external command?
-
-=item *
-
-Why doesn't open() return an error when a pipe open fails?
-
-=item *
-
-What's wrong with using backticks in a void context?
-
-=item *
-
-How can I call backticks without shell processing?
-
-=item *
-
-Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?
-
-=item *
-
-How can I convert my shell script to perl?
-
-=item *
-
-Can I use perl to run a telnet or ftp session?
-
-=item *
-
-How can I write expect in Perl?
-
-=item *
-
-Is there a way to hide perl's command line from programs such as "ps"?
-
-=item *
-
-I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible?
-
-=item *
-
-How do I close a process's filehandle without waiting for it to complete?
-
-=item *
-
-How do I fork a daemon process?
-
-=item *
-
-How do I find out if I'm running interactively or not?
-
-=item *
-
-How do I timeout a slow event?
-
-=item *
-
-How do I set CPU limits?
-
-=item *
-
-How do I avoid zombies on a Unix system?
-
-=item *
-
-How do I use an SQL database?
-
-=item *
-
-How do I make a system() exit on control-C?
-
-=item *
-
-How do I open a file without blocking?
-
-=item *
-
-How do I tell the difference between errors from the shell and perl?
-
-=item *
-
-How do I install a module from CPAN?
-
-=item *
-
-What's the difference between require and use?
-
-=item *
-
-How do I keep my own module/library directory?
-
-=item *
-
-How do I add the directory my program lives in to the module/library search path?
-
-=item *
-
-How do I add a directory to my include path (@INC) at runtime?
-
-=item *
-
-What is socket.ph and where do I get it?
-
-=back
-
-
-=head2 L<perlfaq9>: Web, Email and Networking
-
-This section deals with questions related to running web sites, sending and receiving email as well as general networking.
-
-=over 4
-
-=item *
-
-Should I use a web framework?
-
-=item *
-
-Which web framework should I use?
-
-=item *
-
-What is Plack and PSGI?
-
-=item *
-
-How do I remove HTML from a string?
-
-=item *
-
-How do I extract URLs?
-
-=item *
-
-How do I fetch an HTML file?
-
-=item *
-
-How do I automate an HTML form submission?
-
-=item *
-
-How do I decode or create those %-encodings on the web?
-
-=item *
-
-How do I redirect to another page?
-
-=item *
-
-How do I put a password on my web pages?
-
-=item *
-
-How do I make sure users can't enter values into a form that causes my CGI script to do bad things?
-
-=item *
-
-How do I parse a mail header?
-
-=item *
-
-How do I check a valid mail address?
-
-=item *
-
-How do I decode a MIME/BASE64 string?
-
-=item *
-
-How do I find the user's mail address?
-
-=item *
-
-How do I send email?
-
-=item *
-
-How do I use MIME to make an attachment to a mail message?
-
-=item *
-
-How do I read email?
-
-=item *
-
-How do I find out my hostname, domainname, or IP address?
-
-=item *
-
-How do I fetch/put an (S)FTP file?
-
-=item *
-
-How can I do RPC in Perl?
-
-=back
-
-
-
-=head1 CREDITS
-
-Tom Christiansen wrote the original perlfaq then expanded it with the
-help of Nat Torkington. brian d foy substantialy edited and expanded
-the perlfaq. perlfaq-workers and others have also supplied feedback,
-patches and corrections over the years.
-
-=head1 AUTHOR AND COPYRIGHT
-
-Tom Christiansen wrote the original version of this document.
-brian d foy C<< <bdfoy@cpan.org> >> wrote this version. See the
-individual perlfaq documents for additional copyright information.
-
-This document is available under the same terms as Perl itself. Code
-examples in all the perlfaq documents are in the public domain. Use
-them as you see fit (and at your own risk with no warranty from anyone).
diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq1.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq1.pod
deleted file mode 100644
index a02fae6a707..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlfaq1.pod
+++ /dev/null
@@ -1,332 +0,0 @@
-=head1 NAME
-
-perlfaq1 - General Questions About Perl
-
-=head1 DESCRIPTION
-
-This section of the FAQ answers very general, high-level questions
-about Perl.
-
-=head2 What is Perl?
-
-Perl is a high-level programming language with an eclectic heritage
-written by Larry Wall and a cast of thousands.
-
-Perl's process, file, and text manipulation facilities make it
-particularly well-suited for tasks involving quick prototyping, system
-utilities, software tools, system management tasks, database access,
-graphical programming, networking, and web programming.
-
-Perl derives from the ubiquitous C programming language and to a
-lesser extent from sed, awk, the Unix shell, and many other tools
-and languages.
-
-These strengths make it especially popular with web developers
-and system administrators. Mathematicians, geneticists, journalists,
-managers and many other people also use Perl.
-
-=head2 Who supports Perl? Who develops it? Why is it free?
-
-The original culture of the pre-populist Internet and the deeply-held
-beliefs of Perl's author, Larry Wall, gave rise to the free and open
-distribution policy of Perl. Perl is supported by its users. The
-core, the standard Perl library, the optional modules, and the
-documentation you're reading now were all written by volunteers.
-
-The core development team (known as the Perl Porters)
-are a group of highly altruistic individuals committed to
-producing better software for free than you could hope to purchase for
-money. You may snoop on pending developments via the
-L<archives|http://www.nntp.perl.org/group/perl.perl5.porters/>
-or read the L<faq|http://dev.perl.org/perl5/docs/p5p-faq.html>,
-or you can subscribe to the mailing list by sending
-perl5-porters-subscribe@perl.org a subscription request
-(an empty message with no subject is fine).
-
-While the GNU project includes Perl in its distributions, there's no
-such thing as "GNU Perl". Perl is not produced nor maintained by the
-Free Software Foundation. Perl's licensing terms are also more open
-than GNU software's tend to be.
-
-You can get commercial support of Perl if you wish, although for most
-users the informal support will more than suffice. See the answer to
-"Where can I buy a commercial version of Perl?" for more information.
-
-=head2 Which version of Perl should I use?
-
-(contributed by brian d foy)
-
-There is often a matter of opinion and taste, and there isn't any one
-answer that fits everyone. In general, you want to use either the current
-stable release, or the stable release immediately prior to that one.
-Currently, those are perl5.14.x and perl5.12.x, respectively.
-
-Beyond that, you have to consider several things and decide which is best
-for you.
-
-=over 4
-
-=item *
-
-If things aren't broken, upgrading perl may break them (or at least issue
-new warnings).
-
-=item *
-
-The latest versions of perl have more bug fixes.
-
-=item *
-
-The Perl community is geared toward supporting the most recent releases,
-so you'll have an easier time finding help for those.
-
-=item *
-
-Versions prior to perl5.004 had serious security problems with buffer
-overflows, and in some cases have CERT advisories (for instance,
-L<http://www.cert.org/advisories/CA-1997-17.html> ).
-
-=item *
-
-The latest versions are probably the least deployed and widely tested, so
-you may want to wait a few months after their release and see what
-problems others have if you are risk averse.
-
-=item *
-
-The immediate, previous releases (i.e. perl5.8.x ) are usually maintained
-for a while, although not at the same level as the current releases.
-
-=item *
-
-No one is actively supporting Perl 4. Ten years ago it was a dead
-camel carcass (according to this document). Now it's barely a skeleton
-as its whitewashed bones have fractured or eroded.
-
-=item *
-
-The current leading implementation of Perl 6, Rakudo, released a "useful,
-usable, 'early adopter'" distribution of Perl 6 (called Rakudo Star) in July of
-2010. Please see L<http://rakudo.org/> for more information.
-
-=item *
-
-There are really two tracks of perl development: a maintenance version
-and an experimental version. The maintenance versions are stable, and
-have an even number as the minor release (i.e. perl5.10.x, where 10 is the
-minor release). The experimental versions may include features that
-don't make it into the stable versions, and have an odd number as the
-minor release (i.e. perl5.9.x, where 9 is the minor release).
-
-=back
-
-=head2 What are Perl 4, Perl 5, or Perl 6?
-
-In short, Perl 4 is the parent to both Perl 5 and Perl 6. Perl 5 is the older
-sibling, and though they are different languages, someone who knows one will
-spot many similarities in the other.
-
-The number after Perl (i.e. the 5 after Perl 5) is the major release
-of the perl interpreter as well as the version of the language. Each
-major version has significant differences that earlier versions cannot
-support.
-
-The current major release of Perl is Perl 5, first released in
-1994. It can run scripts from the previous major release, Perl 4
-(March 1991), but has significant differences.
-
-Perl 6 is a reinvention of Perl, it is a language in the same lineage but
-not compatible. The two are complementary, not mutually exclusive. Perl 6 is
-not meant to replace Perl 5, and vice versa. See L</"What is Perl 6?"> below
-to find out more.
-
-See L<perlhist> for a history of Perl revisions.
-
-=head2 What is Perl 6?
-
-Perl 6 was I<originally> described as the community's rewrite of Perl 5.
-Development started in 2002; syntax and design work continue to this day.
-As the language has evolved, it has become clear that it is a separate
-language, incompatible with Perl 5 but in the same language family.
-
-Contrary to popular belief, Perl 6 and Perl 5 peacefully coexist with one
-another. Perl 6 has proven to be a fascinating source of ideas for those
-using Perl 5 (the L<Moose> object system is a well-known example). There is
-overlap in the communities, and this overlap fosters the tradition of sharing
-and borrowing that have been instrumental to Perl's success. The current
-leading implementation of Perl 6 is Rakudo, and you can learn more about
-it at L<http://rakudo.org>.
-
-If you want to learn more about Perl 6, or have a desire to help in
-the crusade to make Perl a better place then read the Perl 6 developers
-page at L<http://www.perl6.org/> and get involved.
-
-"We're really serious about reinventing everything that needs reinventing."
---Larry Wall
-
-=head2 How stable is Perl?
-
-Production releases, which incorporate bug fixes and new functionality,
-are widely tested before release. Since the 5.000 release, we have
-averaged about one production release per year.
-
-The Perl development team occasionally make changes to the
-internal core of the language, but all possible efforts are made toward
-backward compatibility.
-
-=head2 Is Perl difficult to learn?
-
-No, Perl is easy to start L<learning|http://learn.perl.org/> --and easy to keep learning. It looks
-like most programming languages you're likely to have experience
-with, so if you've ever written a C program, an awk script, a shell
-script, or even a BASIC program, you're already partway there.
-
-Most tasks only require a small subset of the Perl language. One of
-the guiding mottos for Perl development is "there's more than one way
-to do it" (TMTOWTDI, sometimes pronounced "tim toady"). Perl's
-learning curve is therefore shallow (easy to learn) and long (there's
-a whole lot you can do if you really want).
-
-Finally, because Perl is frequently (but not always, and certainly not by
-definition) an interpreted language, you can write your programs and test
-them without an intermediate compilation step, allowing you to experiment
-and test/debug quickly and easily. This ease of experimentation flattens
-the learning curve even more.
-
-Things that make Perl easier to learn: Unix experience, almost any kind
-of programming experience, an understanding of regular expressions, and
-the ability to understand other people's code. If there's something you
-need to do, then it's probably already been done, and a working example is
-usually available for free. Don't forget Perl modules, either.
-They're discussed in Part 3 of this FAQ, along with L<CPAN|http://www.cpan.org/>, which is
-discussed in Part 2.
-
-=head2 How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl?
-
-Perl can be used for almost any coding problem, even ones which require
-integrating specialist C code for extra speed. As with any tool it can
-be used well or badly. Perl has many strengths, and a few weaknesses,
-precisely which areas are good and bad is often a personal choice.
-
-When choosing a language you should also be influenced by the
-L<resources|http://www.cpan.org/>, L<testing culture|http://www.cpantesters.org/>
-and L<community|http://www.perl.org/community.html> which surrounds it.
-
-For comparisons to a specific language it is often best to create
-a small project in both languages and compare the results, make sure
-to use all the L<resources|http://www.cpan.org/> of each language,
-as a language is far more than just it's syntax.
-
-=head2 Can I do [task] in Perl?
-
-Perl is flexible and extensible enough for you to use on virtually any
-task, from one-line file-processing tasks to large, elaborate systems.
-
-For many people, Perl serves as a great replacement for shell scripting.
-For others, it serves as a convenient, high-level replacement for most of
-what they'd program in low-level languages like C or C++. It's ultimately
-up to you (and possibly your management) which tasks you'll use Perl
-for and which you won't.
-
-If you have a library that provides an API, you can make any component
-of it available as just another Perl function or variable using a Perl
-extension written in C or C++ and dynamically linked into your main
-perl interpreter. You can also go the other direction, and write your
-main program in C or C++, and then link in some Perl code on the fly,
-to create a powerful application. See L<perlembed>.
-
-That said, there will always be small, focused, special-purpose
-languages dedicated to a specific problem domain that are simply more
-convenient for certain kinds of problems. Perl tries to be all things
-to all people, but nothing special to anyone. Examples of specialized
-languages that come to mind include prolog and matlab.
-
-=head2 When shouldn't I program in Perl?
-
-One good reason is when you already have an existing
-application written in another language that's all done (and done
-well), or you have an application language specifically designed for a
-certain task (e.g. prolog, make).
-
-If you find that you need to speed up a specific part of a Perl
-application (not something you often need) you may want to use C,
-but you can access this from your Perl code with L<perlxs>.
-
-=head2 What's the difference between "perl" and "Perl"?
-
-"Perl" is the name of the language. Only the "P" is capitalized.
-The name of the interpreter (the program which runs the Perl script)
-is "perl" with a lowercase "p".
-
-You may or may not choose to follow this usage. But never write "PERL",
-because perl is not an acronym.
-
-=head2 What is a JAPH?
-
-(contributed by brian d foy)
-
-JAPH stands for "Just another Perl hacker,", which Randal Schwartz used
-to sign email and usenet messages starting in the late 1980s. He
-previously used the phrase with many subjects ("Just another x hacker,"),
-so to distinguish his JAPH, he started to write them as Perl programs:
-
- print "Just another Perl hacker,";
-
-Other people picked up on this and started to write clever or obfuscated
-programs to produce the same output, spinning things quickly out of
-control while still providing hours of amusement for their creators and
-readers.
-
-CPAN has several JAPH programs at L<http://www.cpan.org/misc/japh>.
-
-=head2 How can I convince others to use Perl?
-
-(contributed by brian d foy)
-
-Appeal to their self interest! If Perl is new (and thus scary) to them,
-find something that Perl can do to solve one of their problems. That
-might mean that Perl either saves them something (time, headaches, money)
-or gives them something (flexibility, power, testability).
-
-In general, the benefit of a language is closely related to the skill of
-the people using that language. If you or your team can be faster,
-better, and stronger through Perl, you'll deliver more value. Remember,
-people often respond better to what they get out of it. If you run
-into resistance, figure out what those people get out of the other
-choice and how Perl might satisfy that requirement.
-
-You don't have to worry about finding or paying for Perl; it's freely
-available and several popular operating systems come with Perl. Community
-support in places such as Perlmonks ( L<http://www.perlmonks.com> )
-and the various Perl mailing lists ( L<http://lists.perl.org> ) means that
-you can usually get quick answers to your problems.
-
-Finally, keep in mind that Perl might not be the right tool for every
-job. You're a much better advocate if your claims are reasonable and
-grounded in reality. Dogmatically advocating anything tends to make
-people discount your message. Be honest about possible disadvantages
-to your choice of Perl since any choice has trade-offs.
-
-You might find these links useful:
-
-=over 4
-
-=item * L<http://www.perl.org/about.html>
-
-=item * L<http://perltraining.com.au/whyperl.html>
-
-=back
-
-=head1 AUTHOR AND COPYRIGHT
-
-Copyright (c) 1997-2010 Tom Christiansen, Nathan Torkington, and
-other authors as noted. All rights reserved.
-
-This documentation is free; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-Irrespective of its distribution, all code examples here are in the public
-domain. You are permitted and encouraged to use this code and any
-derivatives thereof in your own programs for fun or for profit as you
-see fit. A simple comment in the code giving credit to the FAQ would
-be courteous but is not required.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq2.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq2.pod
deleted file mode 100644
index e890cc34a1a..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlfaq2.pod
+++ /dev/null
@@ -1,246 +0,0 @@
-=head1 NAME
-
-perlfaq2 - Obtaining and Learning about Perl
-
-=head1 DESCRIPTION
-
-This section of the FAQ answers questions about where to find
-source and documentation for Perl, support, and
-related matters.
-
-=head2 What machines support Perl? Where do I get it?
-
-The standard release of Perl (the one maintained by the Perl
-development team) is distributed only in source code form. You
-can find the latest releases at L<http://www.cpan.org/src/>.
-
-Perl builds and runs on a bewildering number of platforms. Virtually
-all known and current Unix derivatives are supported (perl's native
-platform), as are other systems like VMS, DOS, OS/2, Windows,
-QNX, BeOS, OS X, MPE/iX and the Amiga.
-
-Binary distributions for some proprietary platforms can be found
-L<http://www.cpan.org/ports/> directory. Because these are not part of
-the standard distribution, they may and in fact do differ from the
-base perl port in a variety of ways. You'll have to check their
-respective release notes to see just what the differences are. These
-differences can be either positive (e.g. extensions for the features
-of the particular platform that are not supported in the source
-release of perl) or negative (e.g. might be based upon a less current
-source release of perl).
-
-=head2 How can I get a binary version of Perl?
-
-See L<CPAN Ports|http://www.cpan.org/ports/>
-
-=head2 I don't have a C compiler. How can I build my own Perl interpreter?
-
-For Windows, use a binary version of Perl,
-L<Strawberry Perl|http://strawberryperl.com/> and
-L<ActivePerl|http://www.activestate.com/activeperl> come with a
-bundled C compiler.
-
-Otherwise if you really do want to build Perl, you need to get a
-binary version of C<gcc> for your system first. Use a search
-engine to find out how to do this for your operating system.
-
-=head2 I copied the Perl binary from one machine to another, but scripts don't work.
-
-That's probably because you forgot libraries, or library paths differ.
-You really should build the whole distribution on the machine it will
-eventually live on, and then type C<make install>. Most other
-approaches are doomed to failure.
-
-One simple way to check that things are in the right place is to print out
-the hard-coded C<@INC> that perl looks through for libraries:
-
- % perl -le 'print for @INC'
-
-If this command lists any paths that don't exist on your system, then you
-may need to move the appropriate libraries to these locations, or create
-symbolic links, aliases, or shortcuts appropriately. C<@INC> is also printed as
-part of the output of
-
- % perl -V
-
-You might also want to check out
-L<perlfaq8/"How do I keep my own module/library directory?">.
-
-=head2 I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work?
-
-Read the F<INSTALL> file, which is part of the source distribution.
-It describes in detail how to cope with most idiosyncrasies that the
-C<Configure> script can't work around for any given system or
-architecture.
-
-=head2 What modules and extensions are available for Perl? What is CPAN?
-
-CPAN stands for Comprehensive Perl Archive Network, a multi-gigabyte
-archive replicated on hundreds of machines all over the world. CPAN
-contains tens of thousands of modules and extensions, source code
-and documentation, designed for I<everything> from commercial
-database interfaces to keyboard/screen control and running large web sites.
-
-You can search CPAN on L<http://metacpan.org> or
-L<http://search.cpan.org/>.
-
-The master web site for CPAN is L<http://www.cpan.org/>,
-L<http://www.cpan.org/SITES.html> lists all mirrors.
-
-See the CPAN FAQ at L<http://www.cpan.org/misc/cpan-faq.html> for answers
-to the most frequently asked questions about CPAN.
-
-The L<Task::Kensho> module has a list of recommended modules which
-you should review as a good starting point.
-
-=head2 Where can I get information on Perl?
-
-=over 4
-
-=item * L<http://www.perl.org/>
-
-=item * L<http://perldoc.perl.org/>
-
-=item * L<http://learn.perl.org/>
-
-=back
-
-The complete Perl documentation is available with the Perl distribution.
-If you have Perl installed locally, you probably have the documentation
-installed as well: type C<perldoc perl> in a terminal or
-L<view online|http://perldoc.perl.org/perl.html>.
-
-(Some operating system distributions may ship the documentation in a different
-package; for instance, on Debian, you need to install the C<perl-doc> package.)
-
-Many good books have been written about Perl--see the section later in
-L<perlfaq2> for more details.
-
-=head2 What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?
-
-L<Perl.com|http://www.perl.com/> used to be part of the O'Reilly
-Network, a subsidiary of O'Reilly Media. Although it retains most of
-the original content from its O'Reilly Network, it is now hosted by
-L<The Perl Foundation|http://www.perlfoundation.org/>.
-
-The Perl Foundation is an advocacy organization for the Perl language
-which maintains the web site L<http://www.perl.org/> as a general
-advocacy site for the Perl language. It uses the domain to provide
-general support services to the Perl community, including the hosting
-of mailing lists, web sites, and other services. There are also many
-other sub-domains for special topics like learning Perl and jobs in Perl,
-such as:
-
-=over 4
-
-=item * L<http://www.perl.org/>
-
-=item * L<http://learn.perl.org/>
-
-=item * L<http://jobs.perl.org/>
-
-=item * L<http://lists.perl.org/>
-
-=back
-
-L<Perl Mongers|http://www.pm.org/> uses the pm.org domain for services
-related to local Perl user groups, including the hosting of mailing lists
-and web sites. See the L<Perl Mongers web site|http://www.pm.org/> for more
-information about joining, starting, or requesting services for a
-Perl user group.
-
-CPAN, or the Comprehensive Perl Archive Network L<http://www.cpan.org/>,
-is a replicated, worldwide repository of Perl software.
-See L<What is CPAN?|/"What modules and extensions are available for Perl? What is CPAN? What does CPANE<sol>srcE<sol>... mean?">.
-
-=head2 Where can I post questions?
-
-There are many Perl L<mailing lists|lists.perl.org> for various
-topics, specifically the L<beginners list|http://lists.perl.org/list/beginners.html>
-may be of use.
-
-Other places to ask questions are on the
-L<PerlMonks site|http://www.perlmonks.org/> or
-L<stackoverflow|http://stackoverflow.com/questions/tagged/perl>.
-
-=head2 Perl Books
-
-There are many good L<books on Perl|http://www.perl.org/books/library.html>.
-
-=head2 Which magazines have Perl content?
-
-There's also I<$foo Magazin>, a German magazine dedicated to Perl, at
-( L<http://www.foo-magazin.de> ). The I<Perl-Zeitung> is another
-German-speaking magazine for Perl beginners (see
-L<http://perl-zeitung.at.tf> ).
-
-Several unix/linux releated magazines frequently includes articles on Perl.
-
-=head2 Which Perl blogs should I read?
-
-L<Perl News|http://perlnews.org/> covers some of the major events in the Perl
-world, L<Perl Weekly|http://perlweekly.com/> is a weekly e-mail
-(and RSS feed) of hand-picked Perl articles.
-
-L<http://blogs.perl.org/> hosts many Perl blogs, there are also
-several blog aggregators: L<Perlsphere|http://perlsphere.net/> and
-L<IronMan|http://ironman.enlightenedperl.org/> are two of them.
-
-=head2 What mailing lists are there for Perl?
-
-A comprehensive list of Perl-related mailing lists can be found at
-L<http://lists.perl.org/>
-
-=head2 Where can I buy a commercial version of Perl?
-
-Perl already I<is> commercial software: it has a license
-that you can grab and carefully read to your manager. It is distributed
-in releases and comes in well-defined packages. There is a very large
-and supportive user community and an extensive literature.
-
-If you still need commercial support
-L<ActiveState|http://www.activestate.com/activeperl> offers
-this.
-
-=head2 Where do I send bug reports?
-
-(contributed by brian d foy)
-
-First, ensure that you've found an actual bug. Second, ensure you've
-found an actual bug.
-
-If you've found a bug with the perl interpreter or one of the modules
-in the standard library (those that come with Perl), you can use the
-L<perlbug> utility that comes with Perl (>= 5.004). It collects
-information about your installation to include with your message, then
-sends the message to the right place.
-
-To determine if a module came with your version of Perl, you can
-install and use the L<Module::CoreList> module. It has the information
-about the modules (with their versions) included with each release
-of Perl.
-
-Every CPAN module has a bug tracker set up in RT, L<http://rt.cpan.org>.
-You can submit bugs to RT either through its web interface or by
-email. To email a bug report, send it to
-bug-E<lt>distribution-nameE<gt>@rt.cpan.org . For example, if you
-wanted to report a bug in L<Business::ISBN>, you could send a message to
-bug-Business-ISBN@rt.cpan.org .
-
-Some modules might have special reporting requirements, such as a
-Github or Google Code tracking system, so you should check the
-module documentation too.
-
-=head1 AUTHOR AND COPYRIGHT
-
-Copyright (c) 1997-2010 Tom Christiansen, Nathan Torkington, and
-other authors as noted. All rights reserved.
-
-This documentation is free; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-Irrespective of its distribution, all code examples here are in the public
-domain. You are permitted and encouraged to use this code and any
-derivatives thereof in your own programs for fun or for profit as you
-see fit. A simple comment in the code giving credit to the FAQ would
-be courteous but is not required.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq3.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq3.pod
deleted file mode 100644
index 9e9ae8d906f..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlfaq3.pod
+++ /dev/null
@@ -1,1160 +0,0 @@
-=head1 NAME
-
-perlfaq3 - Programming Tools
-
-=head1 DESCRIPTION
-
-This section of the FAQ answers questions related to programmer tools
-and programming support.
-
-=head2 How do I do (anything)?
-
-Have you looked at CPAN (see L<perlfaq2>)? The chances are that
-someone has already written a module that can solve your problem.
-Have you read the appropriate manpages? Here's a brief index:
-
-=over 4
-
-=item Basics
-
-=over 4
-
-=item L<perldata> - Perl data types
-
-=item L<perlvar> - Perl pre-defined variables
-
-=item L<perlsyn> - Perl syntax
-
-=item L<perlop> - Perl operators and precedence
-
-=item L<perlsub> - Perl subroutines
-
-=back
-
-
-=item Execution
-
-=over 4
-
-=item L<perlrun> - how to execute the Perl interpreter
-
-=item L<perldebug> - Perl debugging
-
-=back
-
-
-=item Functions
-
-=over 4
-
-=item L<perlfunc> - Perl builtin functions
-
-=back
-
-=item Objects
-
-=over 4
-
-=item L<perlref> - Perl references and nested data structures
-
-=item L<perlmod> - Perl modules (packages and symbol tables)
-
-=item L<perlobj> - Perl objects
-
-=item L<perltie> - how to hide an object class in a simple variable
-
-=back
-
-
-=item Data Structures
-
-=over 4
-
-=item L<perlref> - Perl references and nested data structures
-
-=item L<perllol> - Manipulating arrays of arrays in Perl
-
-=item L<perldsc> - Perl Data Structures Cookbook
-
-=back
-
-=item Modules
-
-=over 4
-
-=item L<perlmod> - Perl modules (packages and symbol tables)
-
-=item L<perlmodlib> - constructing new Perl modules and finding existing ones
-
-=back
-
-
-=item Regexes
-
-=over 4
-
-=item L<perlre> - Perl regular expressions
-
-=item L<perlfunc> - Perl builtin functions>
-
-=item L<perlop> - Perl operators and precedence
-
-=item L<perllocale> - Perl locale handling (internationalization and localization)
-
-=back
-
-
-=item Moving to perl5
-
-=over 4
-
-=item L<perltrap> - Perl traps for the unwary
-
-=item L<perl>
-
-=back
-
-
-=item Linking with C
-
-=over 4
-
-=item L<perlxstut> - Tutorial for writing XSUBs
-
-=item L<perlxs> - XS language reference manual
-
-=item L<perlcall> - Perl calling conventions from C
-
-=item L<perlguts> - Introduction to the Perl API
-
-=item L<perlembed> - how to embed perl in your C program
-
-=back
-
-=item Various
-
-L<http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz>
-(not a man-page but still useful, a collection of various essays on
-Perl techniques)
-
-=back
-
-A crude table of contents for the Perl manpage set is found in L<perltoc>.
-
-=head2 How can I use Perl interactively?
-
-The typical approach uses the Perl debugger, described in the
-L<perldebug(1)> manpage, on an "empty" program, like this:
-
- perl -de 42
-
-Now just type in any legal Perl code, and it will be immediately
-evaluated. You can also examine the symbol table, get stack
-backtraces, check variable values, set breakpoints, and other
-operations typically found in symbolic debuggers.
-
-You can also use L<Devel::REPL> which is an interactive shell for Perl,
-commonly known as a REPL - Read, Evaluate, Print, Loop. It provides
-various handy features.
-
-=head2 How do I find which modules are installed on my system?
-
-From the command line, you can use the C<cpan> command's C<-l> switch:
-
- $ cpan -l
-
-You can also use C<cpan>'s C<-a> switch to create an autobundle file
-that C<CPAN.pm> understands and can use to re-install every module:
-
- $ cpan -a
-
-Inside a Perl program, you can use the L<ExtUtils::Installed> module to
-show all installed distributions, although it can take awhile to do
-its magic. The standard library which comes with Perl just shows up
-as "Perl" (although you can get those with L<Module::CoreList>).
-
- use ExtUtils::Installed;
-
- my $inst = ExtUtils::Installed->new();
- my @modules = $inst->modules();
-
-If you want a list of all of the Perl module filenames, you
-can use L<File::Find::Rule>:
-
- use File::Find::Rule;
-
- my @files = File::Find::Rule->
- extras({follow => 1})->
- file()->
- name( '*.pm' )->
- in( @INC )
- ;
-
-If you do not have that module, you can do the same thing
-with L<File::Find> which is part of the standard library:
-
- use File::Find;
- my @files;
-
- find(
- {
- wanted => sub {
- push @files, $File::Find::fullname
- if -f $File::Find::fullname && /\.pm$/
- },
- follow => 1,
- follow_skip => 2,
- },
- @INC
- );
-
- print join "\n", @files;
-
-If you simply need to check quickly to see if a module is
-available, you can check for its documentation. If you can
-read the documentation the module is most likely installed.
-If you cannot read the documentation, the module might not
-have any (in rare cases):
-
- $ perldoc Module::Name
-
-You can also try to include the module in a one-liner to see if
-perl finds it:
-
- $ perl -MModule::Name -e1
-
-(If you don't receive a "Can't locate ... in @INC" error message, then Perl
-found the module name you asked for.)
-
-=head2 How do I debug my Perl programs?
-
-(contributed by brian d foy)
-
-Before you do anything else, you can help yourself by ensuring that
-you let Perl tell you about problem areas in your code. By turning
-on warnings and strictures, you can head off many problems before
-they get too big. You can find out more about these in L<strict>
-and L<warnings>.
-
- #!/usr/bin/perl
- use strict;
- use warnings;
-
-Beyond that, the simplest debugger is the C<print> function. Use it
-to look at values as you run your program:
-
- print STDERR "The value is [$value]\n";
-
-The L<Data::Dumper> module can pretty-print Perl data structures:
-
- use Data::Dumper qw( Dumper );
- print STDERR "The hash is " . Dumper( \%hash ) . "\n";
-
-Perl comes with an interactive debugger, which you can start with the
-C<-d> switch. It's fully explained in L<perldebug>.
-
-If you'd like a graphical user interface and you have L<Tk>, you can use
-C<ptkdb>. It's on CPAN and available for free.
-
-If you need something much more sophisticated and controllable, Leon
-Brocard's L<Devel::ebug> (which you can call with the C<-D> switch as C<-Debug>)
-gives you the programmatic hooks into everything you need to write your
-own (without too much pain and suffering).
-
-You can also use a commercial debugger such as Affrus (Mac OS X), Komodo
-from Activestate (Windows and Mac OS X), or EPIC (most platforms).
-
-=head2 How do I profile my Perl programs?
-
-(contributed by brian d foy, updated Fri Jul 25 12:22:26 PDT 2008)
-
-The C<Devel> namespace has several modules which you can use to
-profile your Perl programs.
-
-The L<Devel::NYTProf> (New York Times Profiler) does both statement
-and subroutine profiling. It's available from CPAN and you also invoke
-it with the C<-d> switch:
-
- perl -d:NYTProf some_perl.pl
-
-It creates a database of the profile information that you can turn into
-reports. The C<nytprofhtml> command turns the data into an HTML report
-similar to the L<Devel::Cover> report:
-
- nytprofhtml
-
-You might also be interested in using the L<Benchmark> to
-measure and compare code snippets.
-
-You can read more about profiling in I<Programming Perl>, chapter 20,
-or I<Mastering Perl>, chapter 5.
-
-L<perldebguts> documents creating a custom debugger if you need to
-create a special sort of profiler. brian d foy describes the process
-in I<The Perl Journal>, "Creating a Perl Debugger",
-L<http://www.ddj.com/184404522> , and "Profiling in Perl"
-L<http://www.ddj.com/184404580> .
-
-Perl.com has two interesting articles on profiling: "Profiling Perl",
-by Simon Cozens, L<http://www.perl.com/lpt/a/850> and "Debugging and
-Profiling mod_perl Applications", by Frank Wiles,
-L<http://www.perl.com/pub/a/2006/02/09/debug_mod_perl.html> .
-
-Randal L. Schwartz writes about profiling in "Speeding up Your Perl
-Programs" for I<Unix Review>,
-L<http://www.stonehenge.com/merlyn/UnixReview/col49.html> , and "Profiling
-in Template Toolkit via Overriding" for I<Linux Magazine>,
-L<http://www.stonehenge.com/merlyn/LinuxMag/col75.html> .
-
-=head2 How do I cross-reference my Perl programs?
-
-The L<B::Xref> module can be used to generate cross-reference reports
-for Perl programs.
-
- perl -MO=Xref[,OPTIONS] scriptname.plx
-
-=head2 Is there a pretty-printer (formatter) for Perl?
-
-L<Perl::Tidy> comes with a perl script L<perltidy> which indents and
-reformats Perl scripts to make them easier to read by trying to follow
-the rules of the L<perlstyle>. If you write Perl, or spend much time reading
-Perl, you will probably find it useful.
-
-Of course, if you simply follow the guidelines in L<perlstyle>,
-you shouldn't need to reformat. The habit of formatting your code
-as you write it will help prevent bugs. Your editor can and should
-help you with this. The perl-mode or newer cperl-mode for emacs
-can provide remarkable amounts of help with most (but not all)
-code, and even less programmable editors can provide significant
-assistance. Tom Christiansen and many other VI users swear by
-the following settings in vi and its clones:
-
- set ai sw=4
- map! ^O {^M}^[O^T
-
-Put that in your F<.exrc> file (replacing the caret characters
-with control characters) and away you go. In insert mode, ^T is
-for indenting, ^D is for undenting, and ^O is for blockdenting--as
-it were. A more complete example, with comments, can be found at
-L<http://www.cpan.org/authors/id/TOMC/scripts/toms.exrc.gz>
-
-=head2 Is there an IDE or Windows Perl Editor?
-
-Perl programs are just plain text, so any editor will do.
-
-If you're on Unix, you already have an IDE--Unix itself. The Unix
-philosophy is the philosophy of several small tools that each do one
-thing and do it well. It's like a carpenter's toolbox.
-
-If you want an IDE, check the following (in alphabetical order, not
-order of preference):
-
-=over 4
-
-=item Eclipse
-
-L<http://e-p-i-c.sf.net/>
-
-The Eclipse Perl Integration Project integrates Perl
-editing/debugging with Eclipse.
-
-=item Enginsite
-
-L<http://www.enginsite.com/>
-
-Perl Editor by EngInSite is a complete integrated development
-environment (IDE) for creating, testing, and debugging Perl scripts;
-the tool runs on Windows 9x/NT/2000/XP or later.
-
-=item Komodo
-
-L<http://www.ActiveState.com/Products/Komodo/>
-
-ActiveState's cross-platform (as of October 2004, that's Windows, Linux,
-and Solaris), multi-language IDE has Perl support, including a regular expression
-debugger and remote debugging.
-
-=item Notepad++
-
-L<http://notepad-plus.sourceforge.net/>
-
-=item Open Perl IDE
-
-L<http://open-perl-ide.sourceforge.net/>
-
-Open Perl IDE is an integrated development environment for writing
-and debugging Perl scripts with ActiveState's ActivePerl distribution
-under Windows 95/98/NT/2000.
-
-=item OptiPerl
-
-L<http://www.optiperl.com/>
-
-OptiPerl is a Windows IDE with simulated CGI environment, including
-debugger and syntax-highlighting editor.
-
-=item Padre
-
-L<http://padre.perlide.org/>
-
-Padre is cross-platform IDE for Perl written in Perl using wxWidgets to provide
-a native look and feel. It's open source under the Artistic License. It
-is one of the newer Perl IDEs.
-
-=item PerlBuilder
-
-L<http://www.solutionsoft.com/perl.htm>
-
-PerlBuilder is an integrated development environment for Windows that
-supports Perl development.
-
-=item visiPerl+
-
-L<http://helpconsulting.net/visiperl/index.html>
-
-From Help Consulting, for Windows.
-
-=item Visual Perl
-
-L<http://www.activestate.com/Products/Visual_Perl/>
-
-Visual Perl is a Visual Studio.NET plug-in from ActiveState.
-
-=item Zeus
-
-L<http://www.zeusedit.com/lookmain.html>
-
-Zeus for Window is another Win32 multi-language editor/IDE
-that comes with support for Perl.
-
-=back
-
-For editors: if you're on Unix you probably have vi or a vi clone
-already, and possibly an emacs too, so you may not need to download
-anything. In any emacs the cperl-mode (M-x cperl-mode) gives you
-perhaps the best available Perl editing mode in any editor.
-
-If you are using Windows, you can use any editor that lets you work
-with plain text, such as NotePad or WordPad. Word processors, such as
-Microsoft Word or WordPerfect, typically do not work since they insert
-all sorts of behind-the-scenes information, although some allow you to
-save files as "Text Only". You can also download text editors designed
-specifically for programming, such as Textpad (
-L<http://www.textpad.com/> ) and UltraEdit ( L<http://www.ultraedit.com/> ),
-among others.
-
-If you are using MacOS, the same concerns apply. MacPerl (for Classic
-environments) comes with a simple editor. Popular external editors are
-BBEdit ( L<http://www.bbedit.com/> ) or Alpha (
-L<http://www.his.com/~jguyer/Alpha/Alpha8.html> ). MacOS X users can use
-Unix editors as well.
-
-=over 4
-
-=item GNU Emacs
-
-L<http://www.gnu.org/software/emacs/windows/ntemacs.html>
-
-=item MicroEMACS
-
-L<http://www.microemacs.de/>
-
-=item XEmacs
-
-L<http://www.xemacs.org/Download/index.html>
-
-=item Jed
-
-L<http://space.mit.edu/~davis/jed/>
-
-=back
-
-or a vi clone such as
-
-=over 4
-
-=item Vim
-
-L<http://www.vim.org/>
-
-=item Vile
-
-L<http://dickey.his.com/vile/vile.html>
-
-=back
-
-The following are Win32 multilanguage editor/IDEs that support Perl:
-
-=over 4
-
-=item Codewright
-
-L<http://www.borland.com/codewright/>
-
-=item MultiEdit
-
-L<http://www.MultiEdit.com/>
-
-=item SlickEdit
-
-L<http://www.slickedit.com/>
-
-=item ConTEXT
-
-L<http://www.contexteditor.org/>
-
-=back
-
-There is also a toyedit Text widget based editor written in Perl
-that is distributed with the Tk module on CPAN. The ptkdb
-( L<http://ptkdb.sourceforge.net/> ) is a Perl/Tk-based debugger that
-acts as a development environment of sorts. Perl Composer
-( L<http://perlcomposer.sourceforge.net/> ) is an IDE for Perl/Tk
-GUI creation.
-
-In addition to an editor/IDE you might be interested in a more
-powerful shell environment for Win32. Your options include
-
-=over 4
-
-=item Bash
-
-from the Cygwin package ( L<http://sources.redhat.com/cygwin/> )
-
-=item Ksh
-
-from the MKS Toolkit ( L<http://www.mkssoftware.com/> ), or the Bourne shell of
-the U/WIN environment ( L<http://www.research.att.com/sw/tools/uwin/> )
-
-=item Tcsh
-
-L<ftp://ftp.astron.com/pub/tcsh/> , see also
-L<http://www.primate.wisc.edu/software/csh-tcsh-book/>
-
-=item Zsh
-
-L<http://www.zsh.org/>
-
-=back
-
-MKS and U/WIN are commercial (U/WIN is free for educational and
-research purposes), Cygwin is covered by the GNU General Public
-License (but that shouldn't matter for Perl use). The Cygwin, MKS,
-and U/WIN all contain (in addition to the shells) a comprehensive set
-of standard Unix toolkit utilities.
-
-If you're transferring text files between Unix and Windows using FTP
-be sure to transfer them in ASCII mode so the ends of lines are
-appropriately converted.
-
-On Mac OS the MacPerl Application comes with a simple 32k text editor
-that behaves like a rudimentary IDE. In contrast to the MacPerl Application
-the MPW Perl tool can make use of the MPW Shell itself as an editor (with
-no 32k limit).
-
-=over 4
-
-=item Affrus
-
-is a full Perl development environment with full debugger support
-( L<http://www.latenightsw.com> ).
-
-=item Alpha
-
-is an editor, written and extensible in Tcl, that nonetheless has
-built-in support for several popular markup and programming languages,
-including Perl and HTML ( L<http://www.his.com/~jguyer/Alpha/Alpha8.html> ).
-
-=item BBEdit and BBEdit Lite
-
-are text editors for Mac OS that have a Perl sensitivity mode
-( L<http://web.barebones.com/> ).
-
-=back
-
-=head2 Where can I get Perl macros for vi?
-
-For a complete version of Tom Christiansen's vi configuration file,
-see L<http://www.cpan.org/authors/Tom_Christiansen/scripts/toms.exrc.gz> ,
-the standard benchmark file for vi emulators. The file runs best with nvi,
-the current version of vi out of Berkeley, which incidentally can be built
-with an embedded Perl interpreter--see L<http://www.cpan.org/src/misc/> .
-
-=head2 Where can I get perl-mode or cperl-mode for emacs?
-X<emacs>
-
-Since Emacs version 19 patchlevel 22 or so, there have been both a
-perl-mode.el and support for the Perl debugger built in. These should
-come with the standard Emacs 19 distribution.
-
-Note that the perl-mode of emacs will have fits with C<"main'foo">
-(single quote), and mess up the indentation and highlighting. You
-are probably using C<"main::foo"> in new Perl code anyway, so this
-shouldn't be an issue.
-
-For CPerlMode, see L<http://www.emacswiki.org/cgi-bin/wiki/CPerlMode>
-
-=head2 How can I use curses with Perl?
-
-The Curses module from CPAN provides a dynamically loadable object
-module interface to a curses library. A small demo can be found at the
-directory L<http://www.cpan.org/authors/Tom_Christiansen/scripts/rep.gz> ;
-this program repeats a command and updates the screen as needed, rendering
-B<rep ps axu> similar to B<top>.
-
-=head2 How can I write a GUI (X, Tk, Gtk, etc.) in Perl?
-X<GUI> X<Tk> X<Wx> X<WxWidgets> X<Gtk> X<Gtk2> X<CamelBones> X<Qt>
-
-(contributed by Ben Morrow)
-
-There are a number of modules which let you write GUIs in Perl. Most
-GUI toolkits have a perl interface: an incomplete list follows.
-
-=over 4
-
-=item Tk
-
-This works under Unix and Windows, and the current version doesn't
-look half as bad under Windows as it used to. Some of the gui elements
-still don't 'feel' quite right, though. The interface is very natural
-and 'perlish', making it easy to use in small scripts that just need a
-simple gui. It hasn't been updated in a while.
-
-=item Wx
-
-This is a Perl binding for the cross-platform wxWidgets toolkit
-( L<http://www.wxwidgets.org> ). It works under Unix, Win32 and Mac OS X,
-using native widgets (Gtk under Unix). The interface follows the C++
-interface closely, but the documentation is a little sparse for someone
-who doesn't know the library, mostly just referring you to the C++
-documentation.
-
-=item Gtk and Gtk2
-
-These are Perl bindings for the Gtk toolkit ( L<http://www.gtk.org> ). The
-interface changed significantly between versions 1 and 2 so they have
-separate Perl modules. It runs under Unix, Win32 and Mac OS X (currently
-it requires an X server on Mac OS, but a 'native' port is underway), and
-the widgets look the same on every platform: i.e., they don't match the
-native widgets. As with Wx, the Perl bindings follow the C API closely,
-and the documentation requires you to read the C documentation to
-understand it.
-
-=item Win32::GUI
-
-This provides access to most of the Win32 GUI widgets from Perl.
-Obviously, it only runs under Win32, and uses native widgets. The Perl
-interface doesn't really follow the C interface: it's been made more
-Perlish, and the documentation is pretty good. More advanced stuff may
-require familiarity with the C Win32 APIs, or reference to MSDN.
-
-=item CamelBones
-
-CamelBones ( L<http://camelbones.sourceforge.net> ) is a Perl interface to
-Mac OS X's Cocoa GUI toolkit, and as such can be used to produce native
-GUIs on Mac OS X. It's not on CPAN, as it requires frameworks that
-CPAN.pm doesn't know how to install, but installation is via the
-standard OSX package installer. The Perl API is, again, very close to
-the ObjC API it's wrapping, and the documentation just tells you how to
-translate from one to the other.
-
-=item Qt
-
-There is a Perl interface to TrollTech's Qt toolkit, but it does not
-appear to be maintained.
-
-=item Athena
-
-Sx is an interface to the Athena widget set which comes with X, but
-again it appears not to be much used nowadays.
-
-=back
-
-=head2 How can I make my Perl program run faster?
-
-The best way to do this is to come up with a better algorithm. This
-can often make a dramatic difference. Jon Bentley's book
-I<Programming Pearls> (that's not a misspelling!) has some good tips
-on optimization, too. Advice on benchmarking boils down to: benchmark
-and profile to make sure you're optimizing the right part, look for
-better algorithms instead of microtuning your code, and when all else
-fails consider just buying faster hardware. You will probably want to
-read the answer to the earlier question "How do I profile my Perl
-programs?" if you haven't done so already.
-
-A different approach is to autoload seldom-used Perl code. See the
-AutoSplit and AutoLoader modules in the standard distribution for
-that. Or you could locate the bottleneck and think about writing just
-that part in C, the way we used to take bottlenecks in C code and
-write them in assembler. Similar to rewriting in C, modules that have
-critical sections can be written in C (for instance, the PDL module
-from CPAN).
-
-If you're currently linking your perl executable to a shared
-I<libc.so>, you can often gain a 10-25% performance benefit by
-rebuilding it to link with a static libc.a instead. This will make a
-bigger perl executable, but your Perl programs (and programmers) may
-thank you for it. See the F<INSTALL> file in the source distribution
-for more information.
-
-The undump program was an ancient attempt to speed up Perl program by
-storing the already-compiled form to disk. This is no longer a viable
-option, as it only worked on a few architectures, and wasn't a good
-solution anyway.
-
-=head2 How can I make my Perl program take less memory?
-
-When it comes to time-space tradeoffs, Perl nearly always prefers to
-throw memory at a problem. Scalars in Perl use more memory than
-strings in C, arrays take more than that, and hashes use even more. While
-there's still a lot to be done, recent releases have been addressing
-these issues. For example, as of 5.004, duplicate hash keys are
-shared amongst all hashes using them, so require no reallocation.
-
-In some cases, using substr() or vec() to simulate arrays can be
-highly beneficial. For example, an array of a thousand booleans will
-take at least 20,000 bytes of space, but it can be turned into one
-125-byte bit vector--a considerable memory savings. The standard
-Tie::SubstrHash module can also help for certain types of data
-structure. If you're working with specialist data structures
-(matrices, for instance) modules that implement these in C may use
-less memory than equivalent Perl modules.
-
-Another thing to try is learning whether your Perl was compiled with
-the system malloc or with Perl's builtin malloc. Whichever one it
-is, try using the other one and see whether this makes a difference.
-Information about malloc is in the F<INSTALL> file in the source
-distribution. You can find out whether you are using perl's malloc by
-typing C<perl -V:usemymalloc>.
-
-Of course, the best way to save memory is to not do anything to waste
-it in the first place. Good programming practices can go a long way
-toward this:
-
-=over 4
-
-=item Don't slurp!
-
-Don't read an entire file into memory if you can process it line
-by line. Or more concretely, use a loop like this:
-
- #
- # Good Idea
- #
- while (my $line = <$file_handle>) {
- # ...
- }
-
-instead of this:
-
- #
- # Bad Idea
- #
- my @data = <$file_handle>;
- foreach (@data) {
- # ...
- }
-
-When the files you're processing are small, it doesn't much matter which
-way you do it, but it makes a huge difference when they start getting
-larger.
-
-=item Use map and grep selectively
-
-Remember that both map and grep expect a LIST argument, so doing this:
-
- @wanted = grep {/pattern/} <$file_handle>;
-
-will cause the entire file to be slurped. For large files, it's better
-to loop:
-
- while (<$file_handle>) {
- push(@wanted, $_) if /pattern/;
- }
-
-=item Avoid unnecessary quotes and stringification
-
-Don't quote large strings unless absolutely necessary:
-
- my $copy = "$large_string";
-
-makes 2 copies of $large_string (one for $copy and another for the
-quotes), whereas
-
- my $copy = $large_string;
-
-only makes one copy.
-
-Ditto for stringifying large arrays:
-
- {
- local $, = "\n";
- print @big_array;
- }
-
-is much more memory-efficient than either
-
- print join "\n", @big_array;
-
-or
-
- {
- local $" = "\n";
- print "@big_array";
- }
-
-
-=item Pass by reference
-
-Pass arrays and hashes by reference, not by value. For one thing, it's
-the only way to pass multiple lists or hashes (or both) in a single
-call/return. It also avoids creating a copy of all the contents. This
-requires some judgement, however, because any changes will be propagated
-back to the original data. If you really want to mangle (er, modify) a
-copy, you'll have to sacrifice the memory needed to make one.
-
-=item Tie large variables to disk
-
-For "big" data stores (i.e. ones that exceed available memory) consider
-using one of the DB modules to store it on disk instead of in RAM. This
-will incur a penalty in access time, but that's probably better than
-causing your hard disk to thrash due to massive swapping.
-
-=back
-
-=head2 Is it safe to return a reference to local or lexical data?
-
-Yes. Perl's garbage collection system takes care of this so
-everything works out right.
-
- sub makeone {
- my @a = ( 1 .. 10 );
- return \@a;
- }
-
- for ( 1 .. 10 ) {
- push @many, makeone();
- }
-
- print $many[4][5], "\n";
-
- print "@many\n";
-
-=head2 How can I free an array or hash so my program shrinks?
-
-(contributed by Michael Carman)
-
-You usually can't. Memory allocated to lexicals (i.e. my() variables)
-cannot be reclaimed or reused even if they go out of scope. It is
-reserved in case the variables come back into scope. Memory allocated
-to global variables can be reused (within your program) by using
-undef() and/or delete().
-
-On most operating systems, memory allocated to a program can never be
-returned to the system. That's why long-running programs sometimes re-
-exec themselves. Some operating systems (notably, systems that use
-mmap(2) for allocating large chunks of memory) can reclaim memory that
-is no longer used, but on such systems, perl must be configured and
-compiled to use the OS's malloc, not perl's.
-
-In general, memory allocation and de-allocation isn't something you can
-or should be worrying about much in Perl.
-
-See also "How can I make my Perl program take less memory?"
-
-=head2 How can I make my CGI script more efficient?
-
-Beyond the normal measures described to make general Perl programs
-faster or smaller, a CGI program has additional issues. It may be run
-several times per second. Given that each time it runs it will need
-to be re-compiled and will often allocate a megabyte or more of system
-memory, this can be a killer. Compiling into C B<isn't going to help
-you> because the process start-up overhead is where the bottleneck is.
-
-There are three popular ways to avoid this overhead. One solution
-involves running the Apache HTTP server (available from
-L<http://www.apache.org/> ) with either of the mod_perl or mod_fastcgi
-plugin modules.
-
-With mod_perl and the Apache::Registry module (distributed with
-mod_perl), httpd will run with an embedded Perl interpreter which
-pre-compiles your script and then executes it within the same address
-space without forking. The Apache extension also gives Perl access to
-the internal server API, so modules written in Perl can do just about
-anything a module written in C can. For more on mod_perl, see
-L<http://perl.apache.org/>
-
-With the FCGI module (from CPAN) and the mod_fastcgi
-module (available from L<http://www.fastcgi.com/> ) each of your Perl
-programs becomes a permanent CGI daemon process.
-
-Finally, L<Plack> is a Perl module and toolkit that contains PSGI middleware,
-helpers and adapters to web servers, allowing you to easily deploy scripts which
-can continue running, and provides flexibility with regards to which web server
-you use. It can allow existing CGI scripts to enjoy this flexibility and
-performance with minimal changes, or can be used along with modern Perl web
-frameworks to make writing and deploying web services with Perl a breeze.
-
-These solutions can have far-reaching effects on your system and on the way you
-write your CGI programs, so investigate them with care.
-
-See also
-L<http://www.cpan.org/modules/by-category/15_World_Wide_Web_HTML_HTTP_CGI/> .
-
-=head2 How can I hide the source for my Perl program?
-
-Delete it. :-) Seriously, there are a number of (mostly
-unsatisfactory) solutions with varying levels of "security".
-
-First of all, however, you I<can't> take away read permission, because
-the source code has to be readable in order to be compiled and
-interpreted. (That doesn't mean that a CGI script's source is
-readable by people on the web, though--only by people with access to
-the filesystem.) So you have to leave the permissions at the socially
-friendly 0755 level.
-
-Some people regard this as a security problem. If your program does
-insecure things and relies on people not knowing how to exploit those
-insecurities, it is not secure. It is often possible for someone to
-determine the insecure things and exploit them without viewing the
-source. Security through obscurity, the name for hiding your bugs
-instead of fixing them, is little security indeed.
-
-You can try using encryption via source filters (Starting from Perl
-5.8 the Filter::Simple and Filter::Util::Call modules are included in
-the standard distribution), but any decent programmer will be able to
-decrypt it. You can try using the byte code compiler and interpreter
-described later in L<perlfaq3>, but the curious might still be able to
-de-compile it. You can try using the native-code compiler described
-later, but crackers might be able to disassemble it. These pose
-varying degrees of difficulty to people wanting to get at your code,
-but none can definitively conceal it (true of every language, not just
-Perl).
-
-It is very easy to recover the source of Perl programs. You simply
-feed the program to the perl interpreter and use the modules in
-the B:: hierarchy. The B::Deparse module should be able to
-defeat most attempts to hide source. Again, this is not
-unique to Perl.
-
-If you're concerned about people profiting from your code, then the
-bottom line is that nothing but a restrictive license will give you
-legal security. License your software and pepper it with threatening
-statements like "This is unpublished proprietary software of XYZ Corp.
-Your access to it does not give you permission to use it blah blah
-blah." We are not lawyers, of course, so you should see a lawyer if
-you want to be sure your license's wording will stand up in court.
-
-=head2 How can I compile my Perl program into byte code or C?
-
-(contributed by brian d foy)
-
-In general, you can't do this. There are some things that may work
-for your situation though. People usually ask this question
-because they want to distribute their works without giving away
-the source code, and most solutions trade disk space for convenience.
-You probably won't see much of a speed increase either, since most
-solutions simply bundle a Perl interpreter in the final product
-(but see L<How can I make my Perl program run faster?>).
-
-The Perl Archive Toolkit ( L<http://par.perl.org/> ) is Perl's
-analog to Java's JAR. It's freely available and on CPAN (
-L<http://search.cpan.org/dist/PAR/> ).
-
-There are also some commercial products that may work for you, although
-you have to buy a license for them.
-
-The Perl Dev Kit ( L<http://www.activestate.com/Products/Perl_Dev_Kit/> )
-from ActiveState can "Turn your Perl programs into ready-to-run
-executables for HP-UX, Linux, Solaris and Windows."
-
-Perl2Exe ( L<http://www.indigostar.com/perl2exe.htm> ) is a command line
-program for converting perl scripts to executable files. It targets both
-Windows and Unix platforms.
-
-=head2 How can I get C<#!perl> to work on [MS-DOS,NT,...]?
-
-For OS/2 just use
-
- extproc perl -S -your_switches
-
-as the first line in C<*.cmd> file (C<-S> due to a bug in cmd.exe's
-"extproc" handling). For DOS one should first invent a corresponding
-batch file and codify it in C<ALTERNATE_SHEBANG> (see the
-F<dosish.h> file in the source distribution for more information).
-
-The Win95/NT installation, when using the ActiveState port of Perl,
-will modify the Registry to associate the C<.pl> extension with the
-perl interpreter. If you install another port, perhaps even building
-your own Win95/NT Perl from the standard sources by using a Windows port
-of gcc (e.g., with cygwin or mingw32), then you'll have to modify
-the Registry yourself. In addition to associating C<.pl> with the
-interpreter, NT people can use: C<SET PATHEXT=%PATHEXT%;.PL> to let them
-run the program C<install-linux.pl> merely by typing C<install-linux>.
-
-Under "Classic" MacOS, a perl program will have the appropriate Creator and
-Type, so that double-clicking them will invoke the MacPerl application.
-Under Mac OS X, clickable apps can be made from any C<#!> script using Wil
-Sanchez' DropScript utility: L<http://www.wsanchez.net/software/> .
-
-I<IMPORTANT!>: Whatever you do, PLEASE don't get frustrated, and just
-throw the perl interpreter into your cgi-bin directory, in order to
-get your programs working for a web server. This is an EXTREMELY big
-security risk. Take the time to figure out how to do it correctly.
-
-=head2 Can I write useful Perl programs on the command line?
-
-Yes. Read L<perlrun> for more information. Some examples follow.
-(These assume standard Unix shell quoting rules.)
-
- # sum first and last fields
- perl -lane 'print $F[0] + $F[-1]' *
-
- # identify text files
- perl -le 'for(@ARGV) {print if -f && -T _}' *
-
- # remove (most) comments from C program
- perl -0777 -pe 's{/\*.*?\*/}{}gs' foo.c
-
- # make file a month younger than today, defeating reaper daemons
- perl -e '$X=24*60*60; utime(time(),time() + 30 * $X,@ARGV)' *
-
- # find first unused uid
- perl -le '$i++ while getpwuid($i); print $i'
-
- # display reasonable manpath
- echo $PATH | perl -nl -072 -e '
- s![^/+]*$!man!&&-d&&!$s{$_}++&&push@m,$_;END{print"@m"}'
-
-OK, the last one was actually an Obfuscated Perl Contest entry. :-)
-
-=head2 Why don't Perl one-liners work on my DOS/Mac/VMS system?
-
-The problem is usually that the command interpreters on those systems
-have rather different ideas about quoting than the Unix shells under
-which the one-liners were created. On some systems, you may have to
-change single-quotes to double ones, which you must I<NOT> do on Unix
-or Plan9 systems. You might also have to change a single % to a %%.
-
-For example:
-
- # Unix (including Mac OS X)
- perl -e 'print "Hello world\n"'
-
- # DOS, etc.
- perl -e "print \"Hello world\n\""
-
- # Mac Classic
- print "Hello world\n"
- (then Run "Myscript" or Shift-Command-R)
-
- # MPW
- perl -e 'print "Hello world\n"'
-
- # VMS
- perl -e "print ""Hello world\n"""
-
-The problem is that none of these examples are reliable: they depend on the
-command interpreter. Under Unix, the first two often work. Under DOS,
-it's entirely possible that neither works. If 4DOS was the command shell,
-you'd probably have better luck like this:
-
- perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>""
-
-Under the Mac, it depends which environment you are using. The MacPerl
-shell, or MPW, is much like Unix shells in its support for several
-quoting variants, except that it makes free use of the Mac's non-ASCII
-characters as control characters.
-
-Using qq(), q(), and qx(), instead of "double quotes", 'single
-quotes', and `backticks`, may make one-liners easier to write.
-
-There is no general solution to all of this. It is a mess.
-
-[Some of this answer was contributed by Kenneth Albanowski.]
-
-=head2 Where can I learn about CGI or Web programming in Perl?
-
-For modules, get the CGI or LWP modules from CPAN. For textbooks,
-see the two especially dedicated to web stuff in the question on
-books. For problems and questions related to the web, like "Why
-do I get 500 Errors" or "Why doesn't it run from the browser right
-when it runs fine on the command line", see the troubleshooting
-guides and references in L<perlfaq9> or in the CGI MetaFAQ:
-
- L<http://www.perl.org/CGI_MetaFAQ.html>
-
-Looking in to L<Plack> and modern Perl web frameworks is highly recommended,
-though; web programming in Perl has evolved a long way from the old days of
-simple CGI scripts.
-
-=head2 Where can I learn about object-oriented Perl programming?
-
-A good place to start is L<perltoot>, and you can use L<perlobj>,
-L<perlboot>, L<perltoot>, L<perltooc>, and L<perlbot> for reference.
-
-A good book on OO on Perl is the "Object-Oriented Perl"
-by Damian Conway from Manning Publications, or "Intermediate Perl"
-by Randal Schwartz, brian d foy, and Tom Phoenix from O'Reilly Media.
-
-=head2 Where can I learn about linking C with Perl?
-
-If you want to call C from Perl, start with L<perlxstut>,
-moving on to L<perlxs>, L<xsubpp>, and L<perlguts>. If you want to
-call Perl from C, then read L<perlembed>, L<perlcall>, and
-L<perlguts>. Don't forget that you can learn a lot from looking at
-how the authors of existing extension modules wrote their code and
-solved their problems.
-
-You might not need all the power of XS. The Inline::C module lets
-you put C code directly in your Perl source. It handles all the
-magic to make it work. You still have to learn at least some of
-the perl API but you won't have to deal with the complexity of the
-XS support files.
-
-=head2 I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong?
-
-Download the ExtUtils::Embed kit from CPAN and run `make test'. If
-the tests pass, read the pods again and again and again. If they
-fail, see L<perlbug> and send a bug report with the output of
-C<make test TEST_VERBOSE=1> along with C<perl -V>.
-
-=head2 When I tried to run my script, I got this message. What does it mean?
-
-A complete list of Perl's error messages and warnings with explanatory
-text can be found in L<perldiag>. You can also use the splain program
-(distributed with Perl) to explain the error messages:
-
- perl program 2>diag.out
- splain [-v] [-p] diag.out
-
-or change your program to explain the messages for you:
-
- use diagnostics;
-
-or
-
- use diagnostics -verbose;
-
-=head2 What's MakeMaker?
-
-(contributed by brian d foy)
-
-The L<ExtUtils::MakeMaker> module, better known simply as "MakeMaker",
-turns a Perl script, typically called C<Makefile.PL>, into a Makefile.
-The Unix tool C<make> uses this file to manage dependencies and actions
-to process and install a Perl distribution.
-
-=head1 AUTHOR AND COPYRIGHT
-
-Copyright (c) 1997-2010 Tom Christiansen, Nathan Torkington, and
-other authors as noted. All rights reserved.
-
-This documentation is free; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-Irrespective of its distribution, all code examples here are in the public
-domain. You are permitted and encouraged to use this code and any
-derivatives thereof in your own programs for fun or for profit as you
-see fit. A simple comment in the code giving credit to the FAQ would
-be courteous but is not required.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq4.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq4.pod
deleted file mode 100644
index e5de15385a5..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlfaq4.pod
+++ /dev/null
@@ -1,2679 +0,0 @@
-=head1 NAME
-
-perlfaq4 - Data Manipulation
-
-=head1 DESCRIPTION
-
-This section of the FAQ answers questions related to manipulating
-numbers, dates, strings, arrays, hashes, and miscellaneous data issues.
-
-=head1 Data: Numbers
-
-=head2 Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?
-
-For the long explanation, see David Goldberg's "What Every Computer
-Scientist Should Know About Floating-Point Arithmetic"
-(L<http://web.cse.msu.edu/~cse320/Documents/FloatingPoint.pdf>).
-
-Internally, your computer represents floating-point numbers in binary.
-Digital (as in powers of two) computers cannot store all numbers
-exactly. Some real numbers lose precision in the process. This is a
-problem with how computers store numbers and affects all computer
-languages, not just Perl.
-
-L<perlnumber> shows the gory details of number representations and
-conversions.
-
-To limit the number of decimal places in your numbers, you can use the
-C<printf> or C<sprintf> function. See
-L<perlop/"Floating-point Arithmetic"> for more details.
-
- printf "%.2f", 10/3;
-
- my $number = sprintf "%.2f", 10/3;
-
-=head2 Why is int() broken?
-
-Your C<int()> is most probably working just fine. It's the numbers that
-aren't quite what you think.
-
-First, see the answer to "Why am I getting long decimals
-(eg, 19.9499999999999) instead of the numbers I should be getting
-(eg, 19.95)?".
-
-For example, this
-
- print int(0.6/0.2-2), "\n";
-
-will in most computers print 0, not 1, because even such simple
-numbers as 0.6 and 0.2 cannot be presented exactly by floating-point
-numbers. What you think in the above as 'three' is really more like
-2.9999999999999995559.
-
-=head2 Why isn't my octal data interpreted correctly?
-
-(contributed by brian d foy)
-
-You're probably trying to convert a string to a number, which Perl only
-converts as a decimal number. When Perl converts a string to a number, it
-ignores leading spaces and zeroes, then assumes the rest of the digits
-are in base 10:
-
- my $string = '0644';
-
- print $string + 0; # prints 644
-
- print $string + 44; # prints 688, certainly not octal!
-
-This problem usually involves one of the Perl built-ins that has the
-same name a Unix command that uses octal numbers as arguments on the
-command line. In this example, C<chmod> on the command line knows that
-its first argument is octal because that's what it does:
-
- %prompt> chmod 644 file
-
-If you want to use the same literal digits (644) in Perl, you have to tell
-Perl to treat them as octal numbers either by prefixing the digits with
-a C<0> or using C<oct>:
-
- chmod( 0644, $filename ); # right, has leading zero
- chmod( oct(644), $filename ); # also correct
-
-The problem comes in when you take your numbers from something that Perl
-thinks is a string, such as a command line argument in C<@ARGV>:
-
- chmod( $ARGV[0], $filename ); # wrong, even if "0644"
-
- chmod( oct($ARGV[0]), $filename ); # correct, treat string as octal
-
-You can always check the value you're using by printing it in octal
-notation to ensure it matches what you think it should be. Print it
-in octal and decimal format:
-
- printf "0%o %d", $number, $number;
-
-=head2 Does Perl have a round() function? What about ceil() and floor()? Trig functions?
-
-Remember that C<int()> merely truncates toward 0. For rounding to a
-certain number of digits, C<sprintf()> or C<printf()> is usually the
-easiest route.
-
- printf("%.3f", 3.1415926535); # prints 3.142
-
-The L<POSIX> module (part of the standard Perl distribution)
-implements C<ceil()>, C<floor()>, and a number of other mathematical
-and trigonometric functions.
-
- use POSIX;
- my $ceil = ceil(3.5); # 4
- my $floor = floor(3.5); # 3
-
-In 5.000 to 5.003 perls, trigonometry was done in the L<Math::Complex>
-module. With 5.004, the L<Math::Trig> module (part of the standard Perl
-distribution) implements the trigonometric functions. Internally it
-uses the L<Math::Complex> module and some functions can break out from
-the real axis into the complex plane, for example the inverse sine of
-2.
-
-Rounding in financial applications can have serious implications, and
-the rounding method used should be specified precisely. In these
-cases, it probably pays not to trust whichever system of rounding is
-being used by Perl, but instead to implement the rounding function you
-need yourself.
-
-To see why, notice how you'll still have an issue on half-way-point
-alternation:
-
- for (my $i = 0; $i < 1.01; $i += 0.05) { printf "%.1f ",$i}
-
- 0.0 0.1 0.1 0.2 0.2 0.2 0.3 0.3 0.4 0.4 0.5 0.5 0.6 0.7 0.7
- 0.8 0.8 0.9 0.9 1.0 1.0
-
-Don't blame Perl. It's the same as in C. IEEE says we have to do
-this. Perl numbers whose absolute values are integers under 2**31 (on
-32-bit machines) will work pretty much like mathematical integers.
-Other numbers are not guaranteed.
-
-=head2 How do I convert between numeric representations/bases/radixes?
-
-As always with Perl there is more than one way to do it. Below are a
-few examples of approaches to making common conversions between number
-representations. This is intended to be representational rather than
-exhaustive.
-
-Some of the examples later in L<perlfaq4> use the L<Bit::Vector>
-module from CPAN. The reason you might choose L<Bit::Vector> over the
-perl built-in functions is that it works with numbers of ANY size,
-that it is optimized for speed on some operations, and for at least
-some programmers the notation might be familiar.
-
-=over 4
-
-=item How do I convert hexadecimal into decimal
-
-Using perl's built in conversion of C<0x> notation:
-
- my $dec = 0xDEADBEEF;
-
-Using the C<hex> function:
-
- my $dec = hex("DEADBEEF");
-
-Using C<pack>:
-
- my $dec = unpack("N", pack("H8", substr("0" x 8 . "DEADBEEF", -8)));
-
-Using the CPAN module C<Bit::Vector>:
-
- use Bit::Vector;
- my $vec = Bit::Vector->new_Hex(32, "DEADBEEF");
- my $dec = $vec->to_Dec();
-
-=item How do I convert from decimal to hexadecimal
-
-Using C<sprintf>:
-
- my $hex = sprintf("%X", 3735928559); # upper case A-F
- my $hex = sprintf("%x", 3735928559); # lower case a-f
-
-Using C<unpack>:
-
- my $hex = unpack("H*", pack("N", 3735928559));
-
-Using L<Bit::Vector>:
-
- use Bit::Vector;
- my $vec = Bit::Vector->new_Dec(32, -559038737);
- my $hex = $vec->to_Hex();
-
-And L<Bit::Vector> supports odd bit counts:
-
- use Bit::Vector;
- my $vec = Bit::Vector->new_Dec(33, 3735928559);
- $vec->Resize(32); # suppress leading 0 if unwanted
- my $hex = $vec->to_Hex();
-
-=item How do I convert from octal to decimal
-
-Using Perl's built in conversion of numbers with leading zeros:
-
- my $dec = 033653337357; # note the leading 0!
-
-Using the C<oct> function:
-
- my $dec = oct("33653337357");
-
-Using L<Bit::Vector>:
-
- use Bit::Vector;
- my $vec = Bit::Vector->new(32);
- $vec->Chunk_List_Store(3, split(//, reverse "33653337357"));
- my $dec = $vec->to_Dec();
-
-=item How do I convert from decimal to octal
-
-Using C<sprintf>:
-
- my $oct = sprintf("%o", 3735928559);
-
-Using L<Bit::Vector>:
-
- use Bit::Vector;
- my $vec = Bit::Vector->new_Dec(32, -559038737);
- my $oct = reverse join('', $vec->Chunk_List_Read(3));
-
-=item How do I convert from binary to decimal
-
-Perl 5.6 lets you write binary numbers directly with
-the C<0b> notation:
-
- my $number = 0b10110110;
-
-Using C<oct>:
-
- my $input = "10110110";
- my $decimal = oct( "0b$input" );
-
-Using C<pack> and C<ord>:
-
- my $decimal = ord(pack('B8', '10110110'));
-
-Using C<pack> and C<unpack> for larger strings:
-
- my $int = unpack("N", pack("B32",
- substr("0" x 32 . "11110101011011011111011101111", -32)));
- my $dec = sprintf("%d", $int);
-
- # substr() is used to left-pad a 32-character string with zeros.
-
-Using L<Bit::Vector>:
-
- my $vec = Bit::Vector->new_Bin(32, "11011110101011011011111011101111");
- my $dec = $vec->to_Dec();
-
-=item How do I convert from decimal to binary
-
-Using C<sprintf> (perl 5.6+):
-
- my $bin = sprintf("%b", 3735928559);
-
-Using C<unpack>:
-
- my $bin = unpack("B*", pack("N", 3735928559));
-
-Using L<Bit::Vector>:
-
- use Bit::Vector;
- my $vec = Bit::Vector->new_Dec(32, -559038737);
- my $bin = $vec->to_Bin();
-
-The remaining transformations (e.g. hex -> oct, bin -> hex, etc.)
-are left as an exercise to the inclined reader.
-
-=back
-
-=head2 Why doesn't & work the way I want it to?
-
-The behavior of binary arithmetic operators depends on whether they're
-used on numbers or strings. The operators treat a string as a series
-of bits and work with that (the string C<"3"> is the bit pattern
-C<00110011>). The operators work with the binary form of a number
-(the number C<3> is treated as the bit pattern C<00000011>).
-
-So, saying C<11 & 3> performs the "and" operation on numbers (yielding
-C<3>). Saying C<"11" & "3"> performs the "and" operation on strings
-(yielding C<"1">).
-
-Most problems with C<&> and C<|> arise because the programmer thinks
-they have a number but really it's a string or vice versa. To avoid this,
-stringify the arguments explicitly (using C<""> or C<qq()>) or convert them
-to numbers explicitly (using C<0+$arg>). The rest arise because
-the programmer says:
-
- if ("\020\020" & "\101\101") {
- # ...
- }
-
-but a string consisting of two null bytes (the result of C<"\020\020"
-& "\101\101">) is not a false value in Perl. You need:
-
- if ( ("\020\020" & "\101\101") !~ /[^\000]/) {
- # ...
- }
-
-=head2 How do I multiply matrices?
-
-Use the L<Math::Matrix> or L<Math::MatrixReal> modules (available from CPAN)
-or the L<PDL> extension (also available from CPAN).
-
-=head2 How do I perform an operation on a series of integers?
-
-To call a function on each element in an array, and collect the
-results, use:
-
- my @results = map { my_func($_) } @array;
-
-For example:
-
- my @triple = map { 3 * $_ } @single;
-
-To call a function on each element of an array, but ignore the
-results:
-
- foreach my $iterator (@array) {
- some_func($iterator);
- }
-
-To call a function on each integer in a (small) range, you B<can> use:
-
- my @results = map { some_func($_) } (5 .. 25);
-
-but you should be aware that in this form, the C<..> operator
-creates a list of all integers in the range, which can take a lot of
-memory for large ranges. However, the problem does not occur when
-using C<..> within a C<for> loop, because in that case the range
-operator is optimized to I<iterate> over the range, without creating
-the entire list. So
-
- my @results = ();
- for my $i (5 .. 500_005) {
- push(@results, some_func($i));
- }
-
-or even
-
- push(@results, some_func($_)) for 5 .. 500_005;
-
-will not create an intermediate list of 500,000 integers.
-
-=head2 How can I output Roman numerals?
-
-Get the L<http://www.cpan.org/modules/by-module/Roman> module.
-
-=head2 Why aren't my random numbers random?
-
-If you're using a version of Perl before 5.004, you must call C<srand>
-once at the start of your program to seed the random number generator.
-
- BEGIN { srand() if $] < 5.004 }
-
-5.004 and later automatically call C<srand> at the beginning. Don't
-call C<srand> more than once--you make your numbers less random,
-rather than more.
-
-Computers are good at being predictable and bad at being random
-(despite appearances caused by bugs in your programs :-). The
-F<random> article in the "Far More Than You Ever Wanted To Know"
-collection in L<http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz>, courtesy
-of Tom Phoenix, talks more about this. John von Neumann said, "Anyone
-who attempts to generate random numbers by deterministic means is, of
-course, living in a state of sin."
-
-Perl relies on the underlying system for the implementation of
-C<rand> and C<srand>; on some systems, the generated numbers are
-not random enough (especially on Windows : see
-L<http://www.perlmonks.org/?node_id=803632>).
-Several CPAN modules in the C<Math> namespace implement better
-pseudorandom generators; see for example
-L<Math::Random::MT> ("Mersenne Twister", fast), or
-L<Math::TrulyRandom> (uses the imperfections in the system's
-timer to generate random numbers, which is rather slow).
-More algorithms for random numbers are described in
-"Numerical Recipes in C" at L<http://www.nr.com/>
-
-=head2 How do I get a random number between X and Y?
-
-To get a random number between two values, you can use the C<rand()>
-built-in to get a random number between 0 and 1. From there, you shift
-that into the range that you want.
-
-C<rand($x)> returns a number such that C<< 0 <= rand($x) < $x >>. Thus
-what you want to have perl figure out is a random number in the range
-from 0 to the difference between your I<X> and I<Y>.
-
-That is, to get a number between 10 and 15, inclusive, you want a
-random number between 0 and 5 that you can then add to 10.
-
- my $number = 10 + int rand( 15-10+1 ); # ( 10,11,12,13,14, or 15 )
-
-Hence you derive the following simple function to abstract
-that. It selects a random integer between the two given
-integers (inclusive), For example: C<random_int_between(50,120)>.
-
- sub random_int_between {
- my($min, $max) = @_;
- # Assumes that the two arguments are integers themselves!
- return $min if $min == $max;
- ($min, $max) = ($max, $min) if $min > $max;
- return $min + int rand(1 + $max - $min);
- }
-
-=head1 Data: Dates
-
-=head2 How do I find the day or week of the year?
-
-The day of the year is in the list returned
-by the C<localtime> function. Without an
-argument C<localtime> uses the current time.
-
- my $day_of_year = (localtime)[7];
-
-The L<POSIX> module can also format a date as the day of the year or
-week of the year.
-
- use POSIX qw/strftime/;
- my $day_of_year = strftime "%j", localtime;
- my $week_of_year = strftime "%W", localtime;
-
-To get the day of year for any date, use L<POSIX>'s C<mktime> to get
-a time in epoch seconds for the argument to C<localtime>.
-
- use POSIX qw/mktime strftime/;
- my $week_of_year = strftime "%W",
- localtime( mktime( 0, 0, 0, 18, 11, 87 ) );
-
-You can also use L<Time::Piece>, which comes with Perl and provides a
-C<localtime> that returns an object:
-
- use Time::Piece;
- my $day_of_year = localtime->yday;
- my $week_of_year = localtime->week;
-
-The L<Date::Calc> module provides two functions to calculate these, too:
-
- use Date::Calc;
- my $day_of_year = Day_of_Year( 1987, 12, 18 );
- my $week_of_year = Week_of_Year( 1987, 12, 18 );
-
-=head2 How do I find the current century or millennium?
-
-Use the following simple functions:
-
- sub get_century {
- return int((((localtime(shift || time))[5] + 1999))/100);
- }
-
- sub get_millennium {
- return 1+int((((localtime(shift || time))[5] + 1899))/1000);
- }
-
-On some systems, the L<POSIX> module's C<strftime()> function has been
-extended in a non-standard way to use a C<%C> format, which they
-sometimes claim is the "century". It isn't, because on most such
-systems, this is only the first two digits of the four-digit year, and
-thus cannot be used to determine reliably the current century or
-millennium.
-
-=head2 How can I compare two dates and find the difference?
-
-(contributed by brian d foy)
-
-You could just store all your dates as a number and then subtract.
-Life isn't always that simple though.
-
-The L<Time::Piece> module, which comes with Perl, replaces L<localtime>
-with a version that returns an object. It also overloads the comparison
-operators so you can compare them directly:
-
- use Time::Piece;
- my $date1 = localtime( $some_time );
- my $date2 = localtime( $some_other_time );
-
- if( $date1 < $date2 ) {
- print "The date was in the past\n";
- }
-
-You can also get differences with a subtraction, which returns a
-L<Time::Seconds> object:
-
- my $diff = $date1 - $date2;
- print "The difference is ", $date_diff->days, " days\n";
-
-If you want to work with formatted dates, the L<Date::Manip>,
-L<Date::Calc>, or L<DateTime> modules can help you.
-
-=head2 How can I take a string and turn it into epoch seconds?
-
-If it's a regular enough string that it always has the same format,
-you can split it up and pass the parts to C<timelocal> in the standard
-L<Time::Local> module. Otherwise, you should look into the L<Date::Calc>,
-L<Date::Parse>, and L<Date::Manip> modules from CPAN.
-
-=head2 How can I find the Julian Day?
-
-(contributed by brian d foy and Dave Cross)
-
-You can use the L<Time::Piece> module, part of the Standard Library,
-which can convert a date/time to a Julian Day:
-
- $ perl -MTime::Piece -le 'print localtime->julian_day'
- 2455607.7959375
-
-Or the modified Julian Day:
-
- $ perl -MTime::Piece -le 'print localtime->mjd'
- 55607.2961226851
-
-Or even the day of the year (which is what some people think of as a
-Julian day):
-
- $ perl -MTime::Piece -le 'print localtime->yday'
- 45
-
-You can also do the same things with the L<DateTime> module:
-
- $ perl -MDateTime -le'print DateTime->today->jd'
- 2453401.5
- $ perl -MDateTime -le'print DateTime->today->mjd'
- 53401
- $ perl -MDateTime -le'print DateTime->today->doy'
- 31
-
-You can use the L<Time::JulianDay> module available on CPAN. Ensure
-that you really want to find a Julian day, though, as many people have
-different ideas about Julian days (see L<http://www.hermetic.ch/cal_stud/jdn.htm>
-for instance):
-
- $ perl -MTime::JulianDay -le 'print local_julian_day( time )'
- 55608
-
-=head2 How do I find yesterday's date?
-X<date> X<yesterday> X<DateTime> X<Date::Calc> X<Time::Local>
-X<daylight saving time> X<day> X<Today_and_Now> X<localtime>
-X<timelocal>
-
-(contributed by brian d foy)
-
-To do it correctly, you can use one of the C<Date> modules since they
-work with calendars instead of times. The L<DateTime> module makes it
-simple, and give you the same time of day, only the day before,
-despite daylight saving time changes:
-
- use DateTime;
-
- my $yesterday = DateTime->now->subtract( days => 1 );
-
- print "Yesterday was $yesterday\n";
-
-You can also use the L<Date::Calc> module using its C<Today_and_Now>
-function.
-
- use Date::Calc qw( Today_and_Now Add_Delta_DHMS );
-
- my @date_time = Add_Delta_DHMS( Today_and_Now(), -1, 0, 0, 0 );
-
- print "@date_time\n";
-
-Most people try to use the time rather than the calendar to figure out
-dates, but that assumes that days are twenty-four hours each. For
-most people, there are two days a year when they aren't: the switch to
-and from summer time throws this off. For example, the rest of the
-suggestions will be wrong sometimes:
-
-Starting with Perl 5.10, L<Time::Piece> and L<Time::Seconds> are part
-of the standard distribution, so you might think that you could do
-something like this:
-
- use Time::Piece;
- use Time::Seconds;
-
- my $yesterday = localtime() - ONE_DAY; # WRONG
- print "Yesterday was $yesterday\n";
-
-The L<Time::Piece> module exports a new C<localtime> that returns an
-object, and L<Time::Seconds> exports the C<ONE_DAY> constant that is a
-set number of seconds. This means that it always gives the time 24
-hours ago, which is not always yesterday. This can cause problems
-around the end of daylight saving time when there's one day that is 25
-hours long.
-
-You have the same problem with L<Time::Local>, which will give the wrong
-answer for those same special cases:
-
- # contributed by Gunnar Hjalmarsson
- use Time::Local;
- my $today = timelocal 0, 0, 12, ( localtime )[3..5];
- my ($d, $m, $y) = ( localtime $today-86400 )[3..5]; # WRONG
- printf "Yesterday: %d-%02d-%02d\n", $y+1900, $m+1, $d;
-
-=head2 Does Perl have a Year 2000 or 2038 problem? Is Perl Y2K compliant?
-
-(contributed by brian d foy)
-
-Perl itself never had a Y2K problem, although that never stopped people
-from creating Y2K problems on their own. See the documentation for
-C<localtime> for its proper use.
-
-Starting with Perl 5.12, C<localtime> and C<gmtime> can handle dates past
-03:14:08 January 19, 2038, when a 32-bit based time would overflow. You
-still might get a warning on a 32-bit C<perl>:
-
- % perl5.12 -E 'say scalar localtime( 0x9FFF_FFFFFFFF )'
- Integer overflow in hexadecimal number at -e line 1.
- Wed Nov 1 19:42:39 5576711
-
-On a 64-bit C<perl>, you can get even larger dates for those really long
-running projects:
-
- % perl5.12 -E 'say scalar gmtime( 0x9FFF_FFFFFFFF )'
- Thu Nov 2 00:42:39 5576711
-
-You're still out of luck if you need to keep track of decaying protons
-though.
-
-=head1 Data: Strings
-
-=head2 How do I validate input?
-
-(contributed by brian d foy)
-
-There are many ways to ensure that values are what you expect or
-want to accept. Besides the specific examples that we cover in the
-perlfaq, you can also look at the modules with "Assert" and "Validate"
-in their names, along with other modules such as L<Regexp::Common>.
-
-Some modules have validation for particular types of input, such
-as L<Business::ISBN>, L<Business::CreditCard>, L<Email::Valid>,
-and L<Data::Validate::IP>.
-
-=head2 How do I unescape a string?
-
-It depends just what you mean by "escape". URL escapes are dealt
-with in L<perlfaq9>. Shell escapes with the backslash (C<\>)
-character are removed with
-
- s/\\(.)/$1/g;
-
-This won't expand C<"\n"> or C<"\t"> or any other special escapes.
-
-=head2 How do I remove consecutive pairs of characters?
-
-(contributed by brian d foy)
-
-You can use the substitution operator to find pairs of characters (or
-runs of characters) and replace them with a single instance. In this
-substitution, we find a character in C<(.)>. The memory parentheses
-store the matched character in the back-reference C<\g1> and we use
-that to require that the same thing immediately follow it. We replace
-that part of the string with the character in C<$1>.
-
- s/(.)\g1/$1/g;
-
-We can also use the transliteration operator, C<tr///>. In this
-example, the search list side of our C<tr///> contains nothing, but
-the C<c> option complements that so it contains everything. The
-replacement list also contains nothing, so the transliteration is
-almost a no-op since it won't do any replacements (or more exactly,
-replace the character with itself). However, the C<s> option squashes
-duplicated and consecutive characters in the string so a character
-does not show up next to itself
-
- my $str = 'Haarlem'; # in the Netherlands
- $str =~ tr///cs; # Now Harlem, like in New York
-
-=head2 How do I expand function calls in a string?
-
-(contributed by brian d foy)
-
-This is documented in L<perlref>, and although it's not the easiest
-thing to read, it does work. In each of these examples, we call the
-function inside the braces used to dereference a reference. If we
-have more than one return value, we can construct and dereference an
-anonymous array. In this case, we call the function in list context.
-
- print "The time values are @{ [localtime] }.\n";
-
-If we want to call the function in scalar context, we have to do a bit
-more work. We can really have any code we like inside the braces, so
-we simply have to end with the scalar reference, although how you do
-that is up to you, and you can use code inside the braces. Note that
-the use of parens creates a list context, so we need C<scalar> to
-force the scalar context on the function:
-
- print "The time is ${\(scalar localtime)}.\n"
-
- print "The time is ${ my $x = localtime; \$x }.\n";
-
-If your function already returns a reference, you don't need to create
-the reference yourself.
-
- sub timestamp { my $t = localtime; \$t }
-
- print "The time is ${ timestamp() }.\n";
-
-The C<Interpolation> module can also do a lot of magic for you. You can
-specify a variable name, in this case C<E>, to set up a tied hash that
-does the interpolation for you. It has several other methods to do this
-as well.
-
- use Interpolation E => 'eval';
- print "The time values are $E{localtime()}.\n";
-
-In most cases, it is probably easier to simply use string concatenation,
-which also forces scalar context.
-
- print "The time is " . localtime() . ".\n";
-
-=head2 How do I find matching/nesting anything?
-
-To find something between two single
-characters, a pattern like C</x([^x]*)x/> will get the intervening
-bits in $1. For multiple ones, then something more like
-C</alpha(.*?)omega/> would be needed. For nested patterns
-and/or balanced expressions, see the so-called
-L<< (?PARNO)|perlre/C<(?PARNO)> C<(?-PARNO)> C<(?+PARNO)> C<(?R)> C<(?0)> >>
-construct (available since perl 5.10).
-The CPAN module L<Regexp::Common> can help to build such
-regular expressions (see in particular
-L<Regexp::Common::balanced> and L<Regexp::Common::delimited>).
-
-More complex cases will require to write a parser, probably
-using a parsing module from CPAN, like
-L<Regexp::Grammars>, L<Parse::RecDescent>, L<Parse::Yapp>,
-L<Text::Balanced>, or L<Marpa::XS>.
-
-=head2 How do I reverse a string?
-
-Use C<reverse()> in scalar context, as documented in
-L<perlfunc/reverse>.
-
- my $reversed = reverse $string;
-
-=head2 How do I expand tabs in a string?
-
-You can do it yourself:
-
- 1 while $string =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e;
-
-Or you can just use the L<Text::Tabs> module (part of the standard Perl
-distribution).
-
- use Text::Tabs;
- my @expanded_lines = expand(@lines_with_tabs);
-
-=head2 How do I reformat a paragraph?
-
-Use L<Text::Wrap> (part of the standard Perl distribution):
-
- use Text::Wrap;
- print wrap("\t", ' ', @paragraphs);
-
-The paragraphs you give to L<Text::Wrap> should not contain embedded
-newlines. L<Text::Wrap> doesn't justify the lines (flush-right).
-
-Or use the CPAN module L<Text::Autoformat>. Formatting files can be
-easily done by making a shell alias, like so:
-
- alias fmt="perl -i -MText::Autoformat -n0777 \
- -e 'print autoformat $_, {all=>1}' $*"
-
-See the documentation for L<Text::Autoformat> to appreciate its many
-capabilities.
-
-=head2 How can I access or change N characters of a string?
-
-You can access the first characters of a string with substr().
-To get the first character, for example, start at position 0
-and grab the string of length 1.
-
-
- my $string = "Just another Perl Hacker";
- my $first_char = substr( $string, 0, 1 ); # 'J'
-
-To change part of a string, you can use the optional fourth
-argument which is the replacement string.
-
- substr( $string, 13, 4, "Perl 5.8.0" );
-
-You can also use substr() as an lvalue.
-
- substr( $string, 13, 4 ) = "Perl 5.8.0";
-
-=head2 How do I change the Nth occurrence of something?
-
-You have to keep track of N yourself. For example, let's say you want
-to change the fifth occurrence of C<"whoever"> or C<"whomever"> into
-C<"whosoever"> or C<"whomsoever">, case insensitively. These
-all assume that $_ contains the string to be altered.
-
- $count = 0;
- s{((whom?)ever)}{
- ++$count == 5 # is it the 5th?
- ? "${2}soever" # yes, swap
- : $1 # renege and leave it there
- }ige;
-
-In the more general case, you can use the C</g> modifier in a C<while>
-loop, keeping count of matches.
-
- $WANT = 3;
- $count = 0;
- $_ = "One fish two fish red fish blue fish";
- while (/(\w+)\s+fish\b/gi) {
- if (++$count == $WANT) {
- print "The third fish is a $1 one.\n";
- }
- }
-
-That prints out: C<"The third fish is a red one."> You can also use a
-repetition count and repeated pattern like this:
-
- /(?:\w+\s+fish\s+){2}(\w+)\s+fish/i;
-
-=head2 How can I count the number of occurrences of a substring within a string?
-
-There are a number of ways, with varying efficiency. If you want a
-count of a certain single character (X) within a string, you can use the
-C<tr///> function like so:
-
- my $string = "ThisXlineXhasXsomeXx'sXinXit";
- my $count = ($string =~ tr/X//);
- print "There are $count X characters in the string";
-
-This is fine if you are just looking for a single character. However,
-if you are trying to count multiple character substrings within a
-larger string, C<tr///> won't work. What you can do is wrap a while()
-loop around a global pattern match. For example, let's count negative
-integers:
-
- my $string = "-9 55 48 -2 23 -76 4 14 -44";
- my $count = 0;
- while ($string =~ /-\d+/g) { $count++ }
- print "There are $count negative numbers in the string";
-
-Another version uses a global match in list context, then assigns the
-result to a scalar, producing a count of the number of matches.
-
- my $count = () = $string =~ /-\d+/g;
-
-=head2 How do I capitalize all the words on one line?
-X<Text::Autoformat> X<capitalize> X<case, title> X<case, sentence>
-
-(contributed by brian d foy)
-
-Damian Conway's L<Text::Autoformat> handles all of the thinking
-for you.
-
- use Text::Autoformat;
- my $x = "Dr. Strangelove or: How I Learned to Stop ".
- "Worrying and Love the Bomb";
-
- print $x, "\n";
- for my $style (qw( sentence title highlight )) {
- print autoformat($x, { case => $style }), "\n";
- }
-
-How do you want to capitalize those words?
-
- FRED AND BARNEY'S LODGE # all uppercase
- Fred And Barney's Lodge # title case
- Fred and Barney's Lodge # highlight case
-
-It's not as easy a problem as it looks. How many words do you think
-are in there? Wait for it... wait for it.... If you answered 5
-you're right. Perl words are groups of C<\w+>, but that's not what
-you want to capitalize. How is Perl supposed to know not to capitalize
-that C<s> after the apostrophe? You could try a regular expression:
-
- $string =~ s/ (
- (^\w) #at the beginning of the line
- | # or
- (\s\w) #preceded by whitespace
- )
- /\U$1/xg;
-
- $string =~ s/([\w']+)/\u\L$1/g;
-
-Now, what if you don't want to capitalize that "and"? Just use
-L<Text::Autoformat> and get on with the next problem. :)
-
-=head2 How can I split a [character]-delimited string except when inside [character]?
-
-Several modules can handle this sort of parsing--L<Text::Balanced>,
-L<Text::CSV>, L<Text::CSV_XS>, and L<Text::ParseWords>, among others.
-
-Take the example case of trying to split a string that is
-comma-separated into its different fields. You can't use C<split(/,/)>
-because you shouldn't split if the comma is inside quotes. For
-example, take a data line like this:
-
- SAR001,"","Cimetrix, Inc","Bob Smith","CAM",N,8,1,0,7,"Error, Core Dumped"
-
-Due to the restriction of the quotes, this is a fairly complex
-problem. Thankfully, we have Jeffrey Friedl, author of
-I<Mastering Regular Expressions>, to handle these for us. He
-suggests (assuming your string is contained in C<$text>):
-
- my @new = ();
- push(@new, $+) while $text =~ m{
- "([^\"\\]*(?:\\.[^\"\\]*)*)",? # groups the phrase inside the quotes
- | ([^,]+),?
- | ,
- }gx;
- push(@new, undef) if substr($text,-1,1) eq ',';
-
-If you want to represent quotation marks inside a
-quotation-mark-delimited field, escape them with backslashes (eg,
-C<"like \"this\"">.
-
-Alternatively, the L<Text::ParseWords> module (part of the standard
-Perl distribution) lets you say:
-
- use Text::ParseWords;
- @new = quotewords(",", 0, $text);
-
-For parsing or generating CSV, though, using L<Text::CSV> rather than
-implementing it yourself is highly recommended; you'll save yourself odd bugs
-popping up later by just using code which has already been tried and tested in
-production for years.
-
-=head2 How do I strip blank space from the beginning/end of a string?
-
-(contributed by brian d foy)
-
-A substitution can do this for you. For a single line, you want to
-replace all the leading or trailing whitespace with nothing. You
-can do that with a pair of substitutions:
-
- s/^\s+//;
- s/\s+$//;
-
-You can also write that as a single substitution, although it turns
-out the combined statement is slower than the separate ones. That
-might not matter to you, though:
-
- s/^\s+|\s+$//g;
-
-In this regular expression, the alternation matches either at the
-beginning or the end of the string since the anchors have a lower
-precedence than the alternation. With the C</g> flag, the substitution
-makes all possible matches, so it gets both. Remember, the trailing
-newline matches the C<\s+>, and the C<$> anchor can match to the
-absolute end of the string, so the newline disappears too. Just add
-the newline to the output, which has the added benefit of preserving
-"blank" (consisting entirely of whitespace) lines which the C<^\s+>
-would remove all by itself:
-
- while( <> ) {
- s/^\s+|\s+$//g;
- print "$_\n";
- }
-
-For a multi-line string, you can apply the regular expression to each
-logical line in the string by adding the C</m> flag (for
-"multi-line"). With the C</m> flag, the C<$> matches I<before> an
-embedded newline, so it doesn't remove it. This pattern still removes
-the newline at the end of the string:
-
- $string =~ s/^\s+|\s+$//gm;
-
-Remember that lines consisting entirely of whitespace will disappear,
-since the first part of the alternation can match the entire string
-and replace it with nothing. If you need to keep embedded blank lines,
-you have to do a little more work. Instead of matching any whitespace
-(since that includes a newline), just match the other whitespace:
-
- $string =~ s/^[\t\f ]+|[\t\f ]+$//mg;
-
-=head2 How do I pad a string with blanks or pad a number with zeroes?
-
-In the following examples, C<$pad_len> is the length to which you wish
-to pad the string, C<$text> or C<$num> contains the string to be padded,
-and C<$pad_char> contains the padding character. You can use a single
-character string constant instead of the C<$pad_char> variable if you
-know what it is in advance. And in the same way you can use an integer in
-place of C<$pad_len> if you know the pad length in advance.
-
-The simplest method uses the C<sprintf> function. It can pad on the left
-or right with blanks and on the left with zeroes and it will not
-truncate the result. The C<pack> function can only pad strings on the
-right with blanks and it will truncate the result to a maximum length of
-C<$pad_len>.
-
- # Left padding a string with blanks (no truncation):
- my $padded = sprintf("%${pad_len}s", $text);
- my $padded = sprintf("%*s", $pad_len, $text); # same thing
-
- # Right padding a string with blanks (no truncation):
- my $padded = sprintf("%-${pad_len}s", $text);
- my $padded = sprintf("%-*s", $pad_len, $text); # same thing
-
- # Left padding a number with 0 (no truncation):
- my $padded = sprintf("%0${pad_len}d", $num);
- my $padded = sprintf("%0*d", $pad_len, $num); # same thing
-
- # Right padding a string with blanks using pack (will truncate):
- my $padded = pack("A$pad_len",$text);
-
-If you need to pad with a character other than blank or zero you can use
-one of the following methods. They all generate a pad string with the
-C<x> operator and combine that with C<$text>. These methods do
-not truncate C<$text>.
-
-Left and right padding with any character, creating a new string:
-
- my $padded = $pad_char x ( $pad_len - length( $text ) ) . $text;
- my $padded = $text . $pad_char x ( $pad_len - length( $text ) );
-
-Left and right padding with any character, modifying C<$text> directly:
-
- substr( $text, 0, 0 ) = $pad_char x ( $pad_len - length( $text ) );
- $text .= $pad_char x ( $pad_len - length( $text ) );
-
-=head2 How do I extract selected columns from a string?
-
-(contributed by brian d foy)
-
-If you know the columns that contain the data, you can
-use C<substr> to extract a single column.
-
- my $column = substr( $line, $start_column, $length );
-
-You can use C<split> if the columns are separated by whitespace or
-some other delimiter, as long as whitespace or the delimiter cannot
-appear as part of the data.
-
- my $line = ' fred barney betty ';
- my @columns = split /\s+/, $line;
- # ( '', 'fred', 'barney', 'betty' );
-
- my $line = 'fred||barney||betty';
- my @columns = split /\|/, $line;
- # ( 'fred', '', 'barney', '', 'betty' );
-
-If you want to work with comma-separated values, don't do this since
-that format is a bit more complicated. Use one of the modules that
-handle that format, such as L<Text::CSV>, L<Text::CSV_XS>, or
-L<Text::CSV_PP>.
-
-If you want to break apart an entire line of fixed columns, you can use
-C<unpack> with the A (ASCII) format. By using a number after the format
-specifier, you can denote the column width. See the C<pack> and C<unpack>
-entries in L<perlfunc> for more details.
-
- my @fields = unpack( $line, "A8 A8 A8 A16 A4" );
-
-Note that spaces in the format argument to C<unpack> do not denote literal
-spaces. If you have space separated data, you may want C<split> instead.
-
-=head2 How do I find the soundex value of a string?
-
-(contributed by brian d foy)
-
-You can use the C<Text::Soundex> module. If you want to do fuzzy or close
-matching, you might also try the L<String::Approx>, and
-L<Text::Metaphone>, and L<Text::DoubleMetaphone> modules.
-
-=head2 How can I expand variables in text strings?
-
-(contributed by brian d foy)
-
-If you can avoid it, don't, or if you can use a templating system,
-such as L<Text::Template> or L<Template> Toolkit, do that instead. You
-might even be able to get the job done with C<sprintf> or C<printf>:
-
- my $string = sprintf 'Say hello to %s and %s', $foo, $bar;
-
-However, for the one-off simple case where I don't want to pull out a
-full templating system, I'll use a string that has two Perl scalar
-variables in it. In this example, I want to expand C<$foo> and C<$bar>
-to their variable's values:
-
- my $foo = 'Fred';
- my $bar = 'Barney';
- $string = 'Say hello to $foo and $bar';
-
-One way I can do this involves the substitution operator and a double
-C</e> flag. The first C</e> evaluates C<$1> on the replacement side and
-turns it into C<$foo>. The second /e starts with C<$foo> and replaces
-it with its value. C<$foo>, then, turns into 'Fred', and that's finally
-what's left in the string:
-
- $string =~ s/(\$\w+)/$1/eeg; # 'Say hello to Fred and Barney'
-
-The C</e> will also silently ignore violations of strict, replacing
-undefined variable names with the empty string. Since I'm using the
-C</e> flag (twice even!), I have all of the same security problems I
-have with C<eval> in its string form. If there's something odd in
-C<$foo>, perhaps something like C<@{[ system "rm -rf /" ]}>, then
-I could get myself in trouble.
-
-To get around the security problem, I could also pull the values from
-a hash instead of evaluating variable names. Using a single C</e>, I
-can check the hash to ensure the value exists, and if it doesn't, I
-can replace the missing value with a marker, in this case C<???> to
-signal that I missed something:
-
- my $string = 'This has $foo and $bar';
-
- my %Replacements = (
- foo => 'Fred',
- );
-
- # $string =~ s/\$(\w+)/$Replacements{$1}/g;
- $string =~ s/\$(\w+)/
- exists $Replacements{$1} ? $Replacements{$1} : '???'
- /eg;
-
- print $string;
-
-=head2 What's wrong with always quoting "$vars"?
-
-The problem is that those double-quotes force
-stringification--coercing numbers and references into strings--even
-when you don't want them to be strings. Think of it this way:
-double-quote expansion is used to produce new strings. If you already
-have a string, why do you need more?
-
-If you get used to writing odd things like these:
-
- print "$var"; # BAD
- my $new = "$old"; # BAD
- somefunc("$var"); # BAD
-
-You'll be in trouble. Those should (in 99.8% of the cases) be
-the simpler and more direct:
-
- print $var;
- my $new = $old;
- somefunc($var);
-
-Otherwise, besides slowing you down, you're going to break code when
-the thing in the scalar is actually neither a string nor a number, but
-a reference:
-
- func(\@array);
- sub func {
- my $aref = shift;
- my $oref = "$aref"; # WRONG
- }
-
-You can also get into subtle problems on those few operations in Perl
-that actually do care about the difference between a string and a
-number, such as the magical C<++> autoincrement operator or the
-syscall() function.
-
-Stringification also destroys arrays.
-
- my @lines = `command`;
- print "@lines"; # WRONG - extra blanks
- print @lines; # right
-
-=head2 Why don't my E<lt>E<lt>HERE documents work?
-
-Here documents are found in L<perlop>. Check for these three things:
-
-=over 4
-
-=item There must be no space after the E<lt>E<lt> part.
-
-=item There (probably) should be a semicolon at the end of the opening token
-
-=item You can't (easily) have any space in front of the tag.
-
-=item There needs to be at least a line separator after the end token.
-
-=back
-
-If you want to indent the text in the here document, you
-can do this:
-
- # all in one
- (my $VAR = <<HERE_TARGET) =~ s/^\s+//gm;
- your text
- goes here
- HERE_TARGET
-
-But the HERE_TARGET must still be flush against the margin.
-If you want that indented also, you'll have to quote
-in the indentation.
-
- (my $quote = <<' FINIS') =~ s/^\s+//gm;
- ...we will have peace, when you and all your works have
- perished--and the works of your dark master to whom you
- would deliver us. You are a liar, Saruman, and a corrupter
- of men's hearts. --Theoden in /usr/src/perl/taint.c
- FINIS
- $quote =~ s/\s+--/\n--/;
-
-A nice general-purpose fixer-upper function for indented here documents
-follows. It expects to be called with a here document as its argument.
-It looks to see whether each line begins with a common substring, and
-if so, strips that substring off. Otherwise, it takes the amount of leading
-whitespace found on the first line and removes that much off each
-subsequent line.
-
- sub fix {
- local $_ = shift;
- my ($white, $leader); # common whitespace and common leading string
- if (/^\s*(?:([^\w\s]+)(\s*).*\n)(?:\s*\g1\g2?.*\n)+$/) {
- ($white, $leader) = ($2, quotemeta($1));
- } else {
- ($white, $leader) = (/^(\s+)/, '');
- }
- s/^\s*?$leader(?:$white)?//gm;
- return $_;
- }
-
-This works with leading special strings, dynamically determined:
-
- my $remember_the_main = fix<<' MAIN_INTERPRETER_LOOP';
- @@@ int
- @@@ runops() {
- @@@ SAVEI32(runlevel);
- @@@ runlevel++;
- @@@ while ( op = (*op->op_ppaddr)() );
- @@@ TAINT_NOT;
- @@@ return 0;
- @@@ }
- MAIN_INTERPRETER_LOOP
-
-Or with a fixed amount of leading whitespace, with remaining
-indentation correctly preserved:
-
- my $poem = fix<<EVER_ON_AND_ON;
- Now far ahead the Road has gone,
- And I must follow, if I can,
- Pursuing it with eager feet,
- Until it joins some larger way
- Where many paths and errands meet.
- And whither then? I cannot say.
- --Bilbo in /usr/src/perl/pp_ctl.c
- EVER_ON_AND_ON
-
-=head1 Data: Arrays
-
-=head2 What is the difference between a list and an array?
-
-(contributed by brian d foy)
-
-A list is a fixed collection of scalars. An array is a variable that
-holds a variable collection of scalars. An array can supply its collection
-for list operations, so list operations also work on arrays:
-
- # slices
- ( 'dog', 'cat', 'bird' )[2,3];
- @animals[2,3];
-
- # iteration
- foreach ( qw( dog cat bird ) ) { ... }
- foreach ( @animals ) { ... }
-
- my @three = grep { length == 3 } qw( dog cat bird );
- my @three = grep { length == 3 } @animals;
-
- # supply an argument list
- wash_animals( qw( dog cat bird ) );
- wash_animals( @animals );
-
-Array operations, which change the scalars, rearranges them, or adds
-or subtracts some scalars, only work on arrays. These can't work on a
-list, which is fixed. Array operations include C<shift>, C<unshift>,
-C<push>, C<pop>, and C<splice>.
-
-An array can also change its length:
-
- $#animals = 1; # truncate to two elements
- $#animals = 10000; # pre-extend to 10,001 elements
-
-You can change an array element, but you can't change a list element:
-
- $animals[0] = 'Rottweiler';
- qw( dog cat bird )[0] = 'Rottweiler'; # syntax error!
-
- foreach ( @animals ) {
- s/^d/fr/; # works fine
- }
-
- foreach ( qw( dog cat bird ) ) {
- s/^d/fr/; # Error! Modification of read only value!
- }
-
-However, if the list element is itself a variable, it appears that you
-can change a list element. However, the list element is the variable, not
-the data. You're not changing the list element, but something the list
-element refers to. The list element itself doesn't change: it's still
-the same variable.
-
-You also have to be careful about context. You can assign an array to
-a scalar to get the number of elements in the array. This only works
-for arrays, though:
-
- my $count = @animals; # only works with arrays
-
-If you try to do the same thing with what you think is a list, you
-get a quite different result. Although it looks like you have a list
-on the righthand side, Perl actually sees a bunch of scalars separated
-by a comma:
-
- my $scalar = ( 'dog', 'cat', 'bird' ); # $scalar gets bird
-
-Since you're assigning to a scalar, the righthand side is in scalar
-context. The comma operator (yes, it's an operator!) in scalar
-context evaluates its lefthand side, throws away the result, and
-evaluates it's righthand side and returns the result. In effect,
-that list-lookalike assigns to C<$scalar> it's rightmost value. Many
-people mess this up because they choose a list-lookalike whose
-last element is also the count they expect:
-
- my $scalar = ( 1, 2, 3 ); # $scalar gets 3, accidentally
-
-=head2 What is the difference between $array[1] and @array[1]?
-
-(contributed by brian d foy)
-
-The difference is the sigil, that special character in front of the
-array name. The C<$> sigil means "exactly one item", while the C<@>
-sigil means "zero or more items". The C<$> gets you a single scalar,
-while the C<@> gets you a list.
-
-The confusion arises because people incorrectly assume that the sigil
-denotes the variable type.
-
-The C<$array[1]> is a single-element access to the array. It's going
-to return the item in index 1 (or undef if there is no item there).
-If you intend to get exactly one element from the array, this is the
-form you should use.
-
-The C<@array[1]> is an array slice, although it has only one index.
-You can pull out multiple elements simultaneously by specifying
-additional indices as a list, like C<@array[1,4,3,0]>.
-
-Using a slice on the lefthand side of the assignment supplies list
-context to the righthand side. This can lead to unexpected results.
-For instance, if you want to read a single line from a filehandle,
-assigning to a scalar value is fine:
-
- $array[1] = <STDIN>;
-
-However, in list context, the line input operator returns all of the
-lines as a list. The first line goes into C<@array[1]> and the rest
-of the lines mysteriously disappear:
-
- @array[1] = <STDIN>; # most likely not what you want
-
-Either the C<use warnings> pragma or the B<-w> flag will warn you when
-you use an array slice with a single index.
-
-=head2 How can I remove duplicate elements from a list or array?
-
-(contributed by brian d foy)
-
-Use a hash. When you think the words "unique" or "duplicated", think
-"hash keys".
-
-If you don't care about the order of the elements, you could just
-create the hash then extract the keys. It's not important how you
-create that hash: just that you use C<keys> to get the unique
-elements.
-
- my %hash = map { $_, 1 } @array;
- # or a hash slice: @hash{ @array } = ();
- # or a foreach: $hash{$_} = 1 foreach ( @array );
-
- my @unique = keys %hash;
-
-If you want to use a module, try the C<uniq> function from
-L<List::MoreUtils>. In list context it returns the unique elements,
-preserving their order in the list. In scalar context, it returns the
-number of unique elements.
-
- use List::MoreUtils qw(uniq);
-
- my @unique = uniq( 1, 2, 3, 4, 4, 5, 6, 5, 7 ); # 1,2,3,4,5,6,7
- my $unique = uniq( 1, 2, 3, 4, 4, 5, 6, 5, 7 ); # 7
-
-You can also go through each element and skip the ones you've seen
-before. Use a hash to keep track. The first time the loop sees an
-element, that element has no key in C<%Seen>. The C<next> statement
-creates the key and immediately uses its value, which is C<undef>, so
-the loop continues to the C<push> and increments the value for that
-key. The next time the loop sees that same element, its key exists in
-the hash I<and> the value for that key is true (since it's not 0 or
-C<undef>), so the next skips that iteration and the loop goes to the
-next element.
-
- my @unique = ();
- my %seen = ();
-
- foreach my $elem ( @array ) {
- next if $seen{ $elem }++;
- push @unique, $elem;
- }
-
-You can write this more briefly using a grep, which does the
-same thing.
-
- my %seen = ();
- my @unique = grep { ! $seen{ $_ }++ } @array;
-
-=head2 How can I tell whether a certain element is contained in a list or array?
-
-(portions of this answer contributed by Anno Siegel and brian d foy)
-
-Hearing the word "in" is an I<in>dication that you probably should have
-used a hash, not a list or array, to store your data. Hashes are
-designed to answer this question quickly and efficiently. Arrays aren't.
-
-That being said, there are several ways to approach this. In Perl 5.10
-and later, you can use the smart match operator to check that an item is
-contained in an array or a hash:
-
- use 5.010;
-
- if( $item ~~ @array ) {
- say "The array contains $item"
- }
-
- if( $item ~~ %hash ) {
- say "The hash contains $item"
- }
-
-With earlier versions of Perl, you have to do a bit more work. If you
-are going to make this query many times over arbitrary string values,
-the fastest way is probably to invert the original array and maintain a
-hash whose keys are the first array's values:
-
- my @blues = qw/azure cerulean teal turquoise lapis-lazuli/;
- my %is_blue = ();
- for (@blues) { $is_blue{$_} = 1 }
-
-Now you can check whether C<$is_blue{$some_color}>. It might have
-been a good idea to keep the blues all in a hash in the first place.
-
-If the values are all small integers, you could use a simple indexed
-array. This kind of an array will take up less space:
-
- my @primes = (2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31);
- my @is_tiny_prime = ();
- for (@primes) { $is_tiny_prime[$_] = 1 }
- # or simply @istiny_prime[@primes] = (1) x @primes;
-
-Now you check whether $is_tiny_prime[$some_number].
-
-If the values in question are integers instead of strings, you can save
-quite a lot of space by using bit strings instead:
-
- my @articles = ( 1..10, 150..2000, 2017 );
- undef $read;
- for (@articles) { vec($read,$_,1) = 1 }
-
-Now check whether C<vec($read,$n,1)> is true for some C<$n>.
-
-These methods guarantee fast individual tests but require a re-organization
-of the original list or array. They only pay off if you have to test
-multiple values against the same array.
-
-If you are testing only once, the standard module L<List::Util> exports
-the function C<first> for this purpose. It works by stopping once it
-finds the element. It's written in C for speed, and its Perl equivalent
-looks like this subroutine:
-
- sub first (&@) {
- my $code = shift;
- foreach (@_) {
- return $_ if &{$code}();
- }
- undef;
- }
-
-If speed is of little concern, the common idiom uses grep in scalar context
-(which returns the number of items that passed its condition) to traverse the
-entire list. This does have the benefit of telling you how many matches it
-found, though.
-
- my $is_there = grep $_ eq $whatever, @array;
-
-If you want to actually extract the matching elements, simply use grep in
-list context.
-
- my @matches = grep $_ eq $whatever, @array;
-
-=head2 How do I compute the difference of two arrays? How do I compute the intersection of two arrays?
-
-Use a hash. Here's code to do both and more. It assumes that each
-element is unique in a given array:
-
- my (@union, @intersection, @difference);
- my %count = ();
- foreach my $element (@array1, @array2) { $count{$element}++ }
- foreach my $element (keys %count) {
- push @union, $element;
- push @{ $count{$element} > 1 ? \@intersection : \@difference }, $element;
- }
-
-Note that this is the I<symmetric difference>, that is, all elements
-in either A or in B but not in both. Think of it as an xor operation.
-
-=head2 How do I test whether two arrays or hashes are equal?
-
-With Perl 5.10 and later, the smart match operator can give you the answer
-with the least amount of work:
-
- use 5.010;
-
- if( @array1 ~~ @array2 ) {
- say "The arrays are the same";
- }
-
- if( %hash1 ~~ %hash2 ) # doesn't check values! {
- say "The hash keys are the same";
- }
-
-The following code works for single-level arrays. It uses a
-stringwise comparison, and does not distinguish defined versus
-undefined empty strings. Modify if you have other needs.
-
- $are_equal = compare_arrays(\@frogs, \@toads);
-
- sub compare_arrays {
- my ($first, $second) = @_;
- no warnings; # silence spurious -w undef complaints
- return 0 unless @$first == @$second;
- for (my $i = 0; $i < @$first; $i++) {
- return 0 if $first->[$i] ne $second->[$i];
- }
- return 1;
- }
-
-For multilevel structures, you may wish to use an approach more
-like this one. It uses the CPAN module L<FreezeThaw>:
-
- use FreezeThaw qw(cmpStr);
- my @a = my @b = ( "this", "that", [ "more", "stuff" ] );
-
- printf "a and b contain %s arrays\n",
- cmpStr(\@a, \@b) == 0
- ? "the same"
- : "different";
-
-This approach also works for comparing hashes. Here we'll demonstrate
-two different answers:
-
- use FreezeThaw qw(cmpStr cmpStrHard);
-
- my %a = my %b = ( "this" => "that", "extra" => [ "more", "stuff" ] );
- $a{EXTRA} = \%b;
- $b{EXTRA} = \%a;
-
- printf "a and b contain %s hashes\n",
- cmpStr(\%a, \%b) == 0 ? "the same" : "different";
-
- printf "a and b contain %s hashes\n",
- cmpStrHard(\%a, \%b) == 0 ? "the same" : "different";
-
-
-The first reports that both those the hashes contain the same data,
-while the second reports that they do not. Which you prefer is left as
-an exercise to the reader.
-
-=head2 How do I find the first array element for which a condition is true?
-
-To find the first array element which satisfies a condition, you can
-use the C<first()> function in the L<List::Util> module, which comes
-with Perl 5.8. This example finds the first element that contains
-"Perl".
-
- use List::Util qw(first);
-
- my $element = first { /Perl/ } @array;
-
-If you cannot use L<List::Util>, you can make your own loop to do the
-same thing. Once you find the element, you stop the loop with last.
-
- my $found;
- foreach ( @array ) {
- if( /Perl/ ) { $found = $_; last }
- }
-
-If you want the array index, use the C<firstidx()> function from
-C<List::MoreUtils>:
-
- use List::MoreUtils qw(firstidx);
- my $index = firstidx { /Perl/ } @array;
-
-Or write it yourself, iterating through the indices
-and checking the array element at each index until you find one
-that satisfies the condition:
-
- my( $found, $index ) = ( undef, -1 );
- for( $i = 0; $i < @array; $i++ ) {
- if( $array[$i] =~ /Perl/ ) {
- $found = $array[$i];
- $index = $i;
- last;
- }
- }
-
-=head2 How do I handle linked lists?
-
-(contributed by brian d foy)
-
-Perl's arrays do not have a fixed size, so you don't need linked lists
-if you just want to add or remove items. You can use array operations
-such as C<push>, C<pop>, C<shift>, C<unshift>, or C<splice> to do
-that.
-
-Sometimes, however, linked lists can be useful in situations where you
-want to "shard" an array so you have have many small arrays instead of
-a single big array. You can keep arrays longer than Perl's largest
-array index, lock smaller arrays separately in threaded programs,
-reallocate less memory, or quickly insert elements in the middle of
-the chain.
-
-Steve Lembark goes through the details in his YAPC::NA 2009 talk "Perly
-Linked Lists" ( L<http://www.slideshare.net/lembark/perly-linked-lists> ),
-although you can just use his L<LinkedList::Single> module.
-
-=head2 How do I handle circular lists?
-X<circular> X<array> X<Tie::Cycle> X<Array::Iterator::Circular>
-X<cycle> X<modulus>
-
-(contributed by brian d foy)
-
-If you want to cycle through an array endlessly, you can increment the
-index modulo the number of elements in the array:
-
- my @array = qw( a b c );
- my $i = 0;
-
- while( 1 ) {
- print $array[ $i++ % @array ], "\n";
- last if $i > 20;
- }
-
-You can also use L<Tie::Cycle> to use a scalar that always has the
-next element of the circular array:
-
- use Tie::Cycle;
-
- tie my $cycle, 'Tie::Cycle', [ qw( FFFFFF 000000 FFFF00 ) ];
-
- print $cycle; # FFFFFF
- print $cycle; # 000000
- print $cycle; # FFFF00
-
-The L<Array::Iterator::Circular> creates an iterator object for
-circular arrays:
-
- use Array::Iterator::Circular;
-
- my $color_iterator = Array::Iterator::Circular->new(
- qw(red green blue orange)
- );
-
- foreach ( 1 .. 20 ) {
- print $color_iterator->next, "\n";
- }
-
-=head2 How do I shuffle an array randomly?
-
-If you either have Perl 5.8.0 or later installed, or if you have
-Scalar-List-Utils 1.03 or later installed, you can say:
-
- use List::Util 'shuffle';
-
- @shuffled = shuffle(@list);
-
-If not, you can use a Fisher-Yates shuffle.
-
- sub fisher_yates_shuffle {
- my $deck = shift; # $deck is a reference to an array
- return unless @$deck; # must not be empty!
-
- my $i = @$deck;
- while (--$i) {
- my $j = int rand ($i+1);
- @$deck[$i,$j] = @$deck[$j,$i];
- }
- }
-
- # shuffle my mpeg collection
- #
- my @mpeg = <audio/*/*.mp3>;
- fisher_yates_shuffle( \@mpeg ); # randomize @mpeg in place
- print @mpeg;
-
-Note that the above implementation shuffles an array in place,
-unlike the C<List::Util::shuffle()> which takes a list and returns
-a new shuffled list.
-
-You've probably seen shuffling algorithms that work using splice,
-randomly picking another element to swap the current element with
-
- srand;
- @new = ();
- @old = 1 .. 10; # just a demo
- while (@old) {
- push(@new, splice(@old, rand @old, 1));
- }
-
-This is bad because splice is already O(N), and since you do it N
-times, you just invented a quadratic algorithm; that is, O(N**2).
-This does not scale, although Perl is so efficient that you probably
-won't notice this until you have rather largish arrays.
-
-=head2 How do I process/modify each element of an array?
-
-Use C<for>/C<foreach>:
-
- for (@lines) {
- s/foo/bar/; # change that word
- tr/XZ/ZX/; # swap those letters
- }
-
-Here's another; let's compute spherical volumes:
-
- my @volumes = @radii;
- for (@volumes) { # @volumes has changed parts
- $_ **= 3;
- $_ *= (4/3) * 3.14159; # this will be constant folded
- }
-
-which can also be done with C<map()> which is made to transform
-one list into another:
-
- my @volumes = map {$_ ** 3 * (4/3) * 3.14159} @radii;
-
-If you want to do the same thing to modify the values of the
-hash, you can use the C<values> function. As of Perl 5.6
-the values are not copied, so if you modify $orbit (in this
-case), you modify the value.
-
- for my $orbit ( values %orbits ) {
- ($orbit **= 3) *= (4/3) * 3.14159;
- }
-
-Prior to perl 5.6 C<values> returned copies of the values,
-so older perl code often contains constructions such as
-C<@orbits{keys %orbits}> instead of C<values %orbits> where
-the hash is to be modified.
-
-=head2 How do I select a random element from an array?
-
-Use the C<rand()> function (see L<perlfunc/rand>):
-
- my $index = rand @array;
- my $element = $array[$index];
-
-Or, simply:
-
- my $element = $array[ rand @array ];
-
-=head2 How do I permute N elements of a list?
-X<List::Permutor> X<permute> X<Algorithm::Loops> X<Knuth>
-X<The Art of Computer Programming> X<Fischer-Krause>
-
-Use the L<List::Permutor> module on CPAN. If the list is actually an
-array, try the L<Algorithm::Permute> module (also on CPAN). It's
-written in XS code and is very efficient:
-
- use Algorithm::Permute;
-
- my @array = 'a'..'d';
- my $p_iterator = Algorithm::Permute->new ( \@array );
-
- while (my @perm = $p_iterator->next) {
- print "next permutation: (@perm)\n";
- }
-
-For even faster execution, you could do:
-
- use Algorithm::Permute;
-
- my @array = 'a'..'d';
-
- Algorithm::Permute::permute {
- print "next permutation: (@array)\n";
- } @array;
-
-Here's a little program that generates all permutations of all the
-words on each line of input. The algorithm embodied in the
-C<permute()> function is discussed in Volume 4 (still unpublished) of
-Knuth's I<The Art of Computer Programming> and will work on any list:
-
- #!/usr/bin/perl -n
- # Fischer-Krause ordered permutation generator
-
- sub permute (&@) {
- my $code = shift;
- my @idx = 0..$#_;
- while ( $code->(@_[@idx]) ) {
- my $p = $#idx;
- --$p while $idx[$p-1] > $idx[$p];
- my $q = $p or return;
- push @idx, reverse splice @idx, $p;
- ++$q while $idx[$p-1] > $idx[$q];
- @idx[$p-1,$q]=@idx[$q,$p-1];
- }
- }
-
- permute { print "@_\n" } split;
-
-The L<Algorithm::Loops> module also provides the C<NextPermute> and
-C<NextPermuteNum> functions which efficiently find all unique permutations
-of an array, even if it contains duplicate values, modifying it in-place:
-if its elements are in reverse-sorted order then the array is reversed,
-making it sorted, and it returns false; otherwise the next
-permutation is returned.
-
-C<NextPermute> uses string order and C<NextPermuteNum> numeric order, so
-you can enumerate all the permutations of C<0..9> like this:
-
- use Algorithm::Loops qw(NextPermuteNum);
-
- my @list= 0..9;
- do { print "@list\n" } while NextPermuteNum @list;
-
-=head2 How do I sort an array by (anything)?
-
-Supply a comparison function to sort() (described in L<perlfunc/sort>):
-
- @list = sort { $a <=> $b } @list;
-
-The default sort function is cmp, string comparison, which would
-sort C<(1, 2, 10)> into C<(1, 10, 2)>. C<< <=> >>, used above, is
-the numerical comparison operator.
-
-If you have a complicated function needed to pull out the part you
-want to sort on, then don't do it inside the sort function. Pull it
-out first, because the sort BLOCK can be called many times for the
-same element. Here's an example of how to pull out the first word
-after the first number on each item, and then sort those words
-case-insensitively.
-
- my @idx;
- for (@data) {
- my $item;
- ($item) = /\d+\s*(\S+)/;
- push @idx, uc($item);
- }
- my @sorted = @data[ sort { $idx[$a] cmp $idx[$b] } 0 .. $#idx ];
-
-which could also be written this way, using a trick
-that's come to be known as the Schwartzian Transform:
-
- my @sorted = map { $_->[0] }
- sort { $a->[1] cmp $b->[1] }
- map { [ $_, uc( (/\d+\s*(\S+)/)[0]) ] } @data;
-
-If you need to sort on several fields, the following paradigm is useful.
-
- my @sorted = sort {
- field1($a) <=> field1($b) ||
- field2($a) cmp field2($b) ||
- field3($a) cmp field3($b)
- } @data;
-
-This can be conveniently combined with precalculation of keys as given
-above.
-
-See the F<sort> article in the "Far More Than You Ever Wanted
-To Know" collection in L<http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz> for
-more about this approach.
-
-See also the question later in L<perlfaq4> on sorting hashes.
-
-=head2 How do I manipulate arrays of bits?
-
-Use C<pack()> and C<unpack()>, or else C<vec()> and the bitwise
-operations.
-
-For example, you don't have to store individual bits in an array
-(which would mean that you're wasting a lot of space). To convert an
-array of bits to a string, use C<vec()> to set the right bits. This
-sets C<$vec> to have bit N set only if C<$ints[N]> was set:
-
- my @ints = (...); # array of bits, e.g. ( 1, 0, 0, 1, 1, 0 ... )
- my $vec = '';
- foreach( 0 .. $#ints ) {
- vec($vec,$_,1) = 1 if $ints[$_];
- }
-
-The string C<$vec> only takes up as many bits as it needs. For
-instance, if you had 16 entries in C<@ints>, C<$vec> only needs two
-bytes to store them (not counting the scalar variable overhead).
-
-Here's how, given a vector in C<$vec>, you can get those bits into
-your C<@ints> array:
-
- sub bitvec_to_list {
- my $vec = shift;
- my @ints;
- # Find null-byte density then select best algorithm
- if ($vec =~ tr/\0// / length $vec > 0.95) {
- use integer;
- my $i;
-
- # This method is faster with mostly null-bytes
- while($vec =~ /[^\0]/g ) {
- $i = -9 + 8 * pos $vec;
- push @ints, $i if vec($vec, ++$i, 1);
- push @ints, $i if vec($vec, ++$i, 1);
- push @ints, $i if vec($vec, ++$i, 1);
- push @ints, $i if vec($vec, ++$i, 1);
- push @ints, $i if vec($vec, ++$i, 1);
- push @ints, $i if vec($vec, ++$i, 1);
- push @ints, $i if vec($vec, ++$i, 1);
- push @ints, $i if vec($vec, ++$i, 1);
- }
- }
- else {
- # This method is a fast general algorithm
- use integer;
- my $bits = unpack "b*", $vec;
- push @ints, 0 if $bits =~ s/^(\d)// && $1;
- push @ints, pos $bits while($bits =~ /1/g);
- }
-
- return \@ints;
- }
-
-This method gets faster the more sparse the bit vector is.
-(Courtesy of Tim Bunce and Winfried Koenig.)
-
-You can make the while loop a lot shorter with this suggestion
-from Benjamin Goldberg:
-
- while($vec =~ /[^\0]+/g ) {
- push @ints, grep vec($vec, $_, 1), $-[0] * 8 .. $+[0] * 8;
- }
-
-Or use the CPAN module L<Bit::Vector>:
-
- my $vector = Bit::Vector->new($num_of_bits);
- $vector->Index_List_Store(@ints);
- my @ints = $vector->Index_List_Read();
-
-L<Bit::Vector> provides efficient methods for bit vector, sets of
-small integers and "big int" math.
-
-Here's a more extensive illustration using vec():
-
- # vec demo
- my $vector = "\xff\x0f\xef\xfe";
- print "Ilya's string \\xff\\x0f\\xef\\xfe represents the number ",
- unpack("N", $vector), "\n";
- my $is_set = vec($vector, 23, 1);
- print "Its 23rd bit is ", $is_set ? "set" : "clear", ".\n";
- pvec($vector);
-
- set_vec(1,1,1);
- set_vec(3,1,1);
- set_vec(23,1,1);
-
- set_vec(3,1,3);
- set_vec(3,2,3);
- set_vec(3,4,3);
- set_vec(3,4,7);
- set_vec(3,8,3);
- set_vec(3,8,7);
-
- set_vec(0,32,17);
- set_vec(1,32,17);
-
- sub set_vec {
- my ($offset, $width, $value) = @_;
- my $vector = '';
- vec($vector, $offset, $width) = $value;
- print "offset=$offset width=$width value=$value\n";
- pvec($vector);
- }
-
- sub pvec {
- my $vector = shift;
- my $bits = unpack("b*", $vector);
- my $i = 0;
- my $BASE = 8;
-
- print "vector length in bytes: ", length($vector), "\n";
- @bytes = unpack("A8" x length($vector), $bits);
- print "bits are: @bytes\n\n";
- }
-
-=head2 Why does defined() return true on empty arrays and hashes?
-
-The short story is that you should probably only use defined on scalars or
-functions, not on aggregates (arrays and hashes). See L<perlfunc/defined>
-in the 5.004 release or later of Perl for more detail.
-
-=head1 Data: Hashes (Associative Arrays)
-
-=head2 How do I process an entire hash?
-
-(contributed by brian d foy)
-
-There are a couple of ways that you can process an entire hash. You
-can get a list of keys, then go through each key, or grab a one
-key-value pair at a time.
-
-To go through all of the keys, use the C<keys> function. This extracts
-all of the keys of the hash and gives them back to you as a list. You
-can then get the value through the particular key you're processing:
-
- foreach my $key ( keys %hash ) {
- my $value = $hash{$key}
- ...
- }
-
-Once you have the list of keys, you can process that list before you
-process the hash elements. For instance, you can sort the keys so you
-can process them in lexical order:
-
- foreach my $key ( sort keys %hash ) {
- my $value = $hash{$key}
- ...
- }
-
-Or, you might want to only process some of the items. If you only want
-to deal with the keys that start with C<text:>, you can select just
-those using C<grep>:
-
- foreach my $key ( grep /^text:/, keys %hash ) {
- my $value = $hash{$key}
- ...
- }
-
-If the hash is very large, you might not want to create a long list of
-keys. To save some memory, you can grab one key-value pair at a time using
-C<each()>, which returns a pair you haven't seen yet:
-
- while( my( $key, $value ) = each( %hash ) ) {
- ...
- }
-
-The C<each> operator returns the pairs in apparently random order, so if
-ordering matters to you, you'll have to stick with the C<keys> method.
-
-The C<each()> operator can be a bit tricky though. You can't add or
-delete keys of the hash while you're using it without possibly
-skipping or re-processing some pairs after Perl internally rehashes
-all of the elements. Additionally, a hash has only one iterator, so if
-you mix C<keys>, C<values>, or C<each> on the same hash, you risk resetting
-the iterator and messing up your processing. See the C<each> entry in
-L<perlfunc> for more details.
-
-=head2 How do I merge two hashes?
-X<hash> X<merge> X<slice, hash>
-
-(contributed by brian d foy)
-
-Before you decide to merge two hashes, you have to decide what to do
-if both hashes contain keys that are the same and if you want to leave
-the original hashes as they were.
-
-If you want to preserve the original hashes, copy one hash (C<%hash1>)
-to a new hash (C<%new_hash>), then add the keys from the other hash
-(C<%hash2> to the new hash. Checking that the key already exists in
-C<%new_hash> gives you a chance to decide what to do with the
-duplicates:
-
- my %new_hash = %hash1; # make a copy; leave %hash1 alone
-
- foreach my $key2 ( keys %hash2 ) {
- if( exists $new_hash{$key2} ) {
- warn "Key [$key2] is in both hashes!";
- # handle the duplicate (perhaps only warning)
- ...
- next;
- }
- else {
- $new_hash{$key2} = $hash2{$key2};
- }
- }
-
-If you don't want to create a new hash, you can still use this looping
-technique; just change the C<%new_hash> to C<%hash1>.
-
- foreach my $key2 ( keys %hash2 ) {
- if( exists $hash1{$key2} ) {
- warn "Key [$key2] is in both hashes!";
- # handle the duplicate (perhaps only warning)
- ...
- next;
- }
- else {
- $hash1{$key2} = $hash2{$key2};
- }
- }
-
-If you don't care that one hash overwrites keys and values from the other, you
-could just use a hash slice to add one hash to another. In this case, values
-from C<%hash2> replace values from C<%hash1> when they have keys in common:
-
- @hash1{ keys %hash2 } = values %hash2;
-
-=head2 What happens if I add or remove keys from a hash while iterating over it?
-
-(contributed by brian d foy)
-
-The easy answer is "Don't do that!"
-
-If you iterate through the hash with each(), you can delete the key
-most recently returned without worrying about it. If you delete or add
-other keys, the iterator may skip or double up on them since perl
-may rearrange the hash table. See the
-entry for C<each()> in L<perlfunc>.
-
-=head2 How do I look up a hash element by value?
-
-Create a reverse hash:
-
- my %by_value = reverse %by_key;
- my $key = $by_value{$value};
-
-That's not particularly efficient. It would be more space-efficient
-to use:
-
- while (my ($key, $value) = each %by_key) {
- $by_value{$value} = $key;
- }
-
-If your hash could have repeated values, the methods above will only find
-one of the associated keys. This may or may not worry you. If it does
-worry you, you can always reverse the hash into a hash of arrays instead:
-
- while (my ($key, $value) = each %by_key) {
- push @{$key_list_by_value{$value}}, $key;
- }
-
-=head2 How can I know how many entries are in a hash?
-
-(contributed by brian d foy)
-
-This is very similar to "How do I process an entire hash?", also in
-L<perlfaq4>, but a bit simpler in the common cases.
-
-You can use the C<keys()> built-in function in scalar context to find out
-have many entries you have in a hash:
-
- my $key_count = keys %hash; # must be scalar context!
-
-If you want to find out how many entries have a defined value, that's
-a bit different. You have to check each value. A C<grep> is handy:
-
- my $defined_value_count = grep { defined } values %hash;
-
-You can use that same structure to count the entries any way that
-you like. If you want the count of the keys with vowels in them,
-you just test for that instead:
-
- my $vowel_count = grep { /[aeiou]/ } keys %hash;
-
-The C<grep> in scalar context returns the count. If you want the list
-of matching items, just use it in list context instead:
-
- my @defined_values = grep { defined } values %hash;
-
-The C<keys()> function also resets the iterator, which means that you may
-see strange results if you use this between uses of other hash operators
-such as C<each()>.
-
-=head2 How do I sort a hash (optionally by value instead of key)?
-
-(contributed by brian d foy)
-
-To sort a hash, start with the keys. In this example, we give the list of
-keys to the sort function which then compares them ASCIIbetically (which
-might be affected by your locale settings). The output list has the keys
-in ASCIIbetical order. Once we have the keys, we can go through them to
-create a report which lists the keys in ASCIIbetical order.
-
- my @keys = sort { $a cmp $b } keys %hash;
-
- foreach my $key ( @keys ) {
- printf "%-20s %6d\n", $key, $hash{$key};
- }
-
-We could get more fancy in the C<sort()> block though. Instead of
-comparing the keys, we can compute a value with them and use that
-value as the comparison.
-
-For instance, to make our report order case-insensitive, we use
-C<lc> to lowercase the keys before comparing them:
-
- my @keys = sort { lc $a cmp lc $b } keys %hash;
-
-Note: if the computation is expensive or the hash has many elements,
-you may want to look at the Schwartzian Transform to cache the
-computation results.
-
-If we want to sort by the hash value instead, we use the hash key
-to look it up. We still get out a list of keys, but this time they
-are ordered by their value.
-
- my @keys = sort { $hash{$a} <=> $hash{$b} } keys %hash;
-
-From there we can get more complex. If the hash values are the same,
-we can provide a secondary sort on the hash key.
-
- my @keys = sort {
- $hash{$a} <=> $hash{$b}
- or
- "\L$a" cmp "\L$b"
- } keys %hash;
-
-=head2 How can I always keep my hash sorted?
-X<hash tie sort DB_File Tie::IxHash>
-
-You can look into using the C<DB_File> module and C<tie()> using the
-C<$DB_BTREE> hash bindings as documented in L<DB_File/"In Memory
-Databases">. The L<Tie::IxHash> module from CPAN might also be
-instructive. Although this does keep your hash sorted, you might not
-like the slowdown you suffer from the tie interface. Are you sure you
-need to do this? :)
-
-=head2 What's the difference between "delete" and "undef" with hashes?
-
-Hashes contain pairs of scalars: the first is the key, the
-second is the value. The key will be coerced to a string,
-although the value can be any kind of scalar: string,
-number, or reference. If a key C<$key> is present in
-%hash, C<exists($hash{$key})> will return true. The value
-for a given key can be C<undef>, in which case
-C<$hash{$key}> will be C<undef> while C<exists $hash{$key}>
-will return true. This corresponds to (C<$key>, C<undef>)
-being in the hash.
-
-Pictures help... Here's the C<%hash> table:
-
- keys values
- +------+------+
- | a | 3 |
- | x | 7 |
- | d | 0 |
- | e | 2 |
- +------+------+
-
-And these conditions hold
-
- $hash{'a'} is true
- $hash{'d'} is false
- defined $hash{'d'} is true
- defined $hash{'a'} is true
- exists $hash{'a'} is true (Perl 5 only)
- grep ($_ eq 'a', keys %hash) is true
-
-If you now say
-
- undef $hash{'a'}
-
-your table now reads:
-
-
- keys values
- +------+------+
- | a | undef|
- | x | 7 |
- | d | 0 |
- | e | 2 |
- +------+------+
-
-and these conditions now hold; changes in caps:
-
- $hash{'a'} is FALSE
- $hash{'d'} is false
- defined $hash{'d'} is true
- defined $hash{'a'} is FALSE
- exists $hash{'a'} is true (Perl 5 only)
- grep ($_ eq 'a', keys %hash) is true
-
-Notice the last two: you have an undef value, but a defined key!
-
-Now, consider this:
-
- delete $hash{'a'}
-
-your table now reads:
-
- keys values
- +------+------+
- | x | 7 |
- | d | 0 |
- | e | 2 |
- +------+------+
-
-and these conditions now hold; changes in caps:
-
- $hash{'a'} is false
- $hash{'d'} is false
- defined $hash{'d'} is true
- defined $hash{'a'} is false
- exists $hash{'a'} is FALSE (Perl 5 only)
- grep ($_ eq 'a', keys %hash) is FALSE
-
-See, the whole entry is gone!
-
-=head2 Why don't my tied hashes make the defined/exists distinction?
-
-This depends on the tied hash's implementation of EXISTS().
-For example, there isn't the concept of undef with hashes
-that are tied to DBM* files. It also means that exists() and
-defined() do the same thing with a DBM* file, and what they
-end up doing is not what they do with ordinary hashes.
-
-=head2 How do I reset an each() operation part-way through?
-
-(contributed by brian d foy)
-
-You can use the C<keys> or C<values> functions to reset C<each>. To
-simply reset the iterator used by C<each> without doing anything else,
-use one of them in void context:
-
- keys %hash; # resets iterator, nothing else.
- values %hash; # resets iterator, nothing else.
-
-See the documentation for C<each> in L<perlfunc>.
-
-=head2 How can I get the unique keys from two hashes?
-
-First you extract the keys from the hashes into lists, then solve
-the "removing duplicates" problem described above. For example:
-
- my %seen = ();
- for my $element (keys(%foo), keys(%bar)) {
- $seen{$element}++;
- }
- my @uniq = keys %seen;
-
-Or more succinctly:
-
- my @uniq = keys %{{%foo,%bar}};
-
-Or if you really want to save space:
-
- my %seen = ();
- while (defined ($key = each %foo)) {
- $seen{$key}++;
- }
- while (defined ($key = each %bar)) {
- $seen{$key}++;
- }
- my @uniq = keys %seen;
-
-=head2 How can I store a multidimensional array in a DBM file?
-
-Either stringify the structure yourself (no fun), or else
-get the MLDBM (which uses Data::Dumper) module from CPAN and layer
-it on top of either DB_File or GDBM_File. You might also try DBM::Deep, but
-it can be a bit slow.
-
-=head2 How can I make my hash remember the order I put elements into it?
-
-Use the L<Tie::IxHash> from CPAN.
-
- use Tie::IxHash;
-
- tie my %myhash, 'Tie::IxHash';
-
- for (my $i=0; $i<20; $i++) {
- $myhash{$i} = 2*$i;
- }
-
- my @keys = keys %myhash;
- # @keys = (0,1,2,3,...)
-
-=head2 Why does passing a subroutine an undefined element in a hash create it?
-
-(contributed by brian d foy)
-
-Are you using a really old version of Perl?
-
-Normally, accessing a hash key's value for a nonexistent key will
-I<not> create the key.
-
- my %hash = ();
- my $value = $hash{ 'foo' };
- print "This won't print\n" if exists $hash{ 'foo' };
-
-Passing C<$hash{ 'foo' }> to a subroutine used to be a special case, though.
-Since you could assign directly to C<$_[0]>, Perl had to be ready to
-make that assignment so it created the hash key ahead of time:
-
- my_sub( $hash{ 'foo' } );
- print "This will print before 5.004\n" if exists $hash{ 'foo' };
-
- sub my_sub {
- # $_[0] = 'bar'; # create hash key in case you do this
- 1;
- }
-
-Since Perl 5.004, however, this situation is a special case and Perl
-creates the hash key only when you make the assignment:
-
- my_sub( $hash{ 'foo' } );
- print "This will print, even after 5.004\n" if exists $hash{ 'foo' };
-
- sub my_sub {
- $_[0] = 'bar';
- }
-
-However, if you want the old behavior (and think carefully about that
-because it's a weird side effect), you can pass a hash slice instead.
-Perl 5.004 didn't make this a special case:
-
- my_sub( @hash{ qw/foo/ } );
-
-=head2 How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays?
-
-Usually a hash ref, perhaps like this:
-
- $record = {
- NAME => "Jason",
- EMPNO => 132,
- TITLE => "deputy peon",
- AGE => 23,
- SALARY => 37_000,
- PALS => [ "Norbert", "Rhys", "Phineas"],
- };
-
-References are documented in L<perlref> and L<perlreftut>.
-Examples of complex data structures are given in L<perldsc> and
-L<perllol>. Examples of structures and object-oriented classes are
-in L<perltoot>.
-
-=head2 How can I use a reference as a hash key?
-
-(contributed by brian d foy and Ben Morrow)
-
-Hash keys are strings, so you can't really use a reference as the key.
-When you try to do that, perl turns the reference into its stringified
-form (for instance, C<HASH(0xDEADBEEF)>). From there you can't get
-back the reference from the stringified form, at least without doing
-some extra work on your own.
-
-Remember that the entry in the hash will still be there even if
-the referenced variable goes out of scope, and that it is entirely
-possible for Perl to subsequently allocate a different variable at
-the same address. This will mean a new variable might accidentally
-be associated with the value for an old.
-
-If you have Perl 5.10 or later, and you just want to store a value
-against the reference for lookup later, you can use the core
-Hash::Util::Fieldhash module. This will also handle renaming the
-keys if you use multiple threads (which causes all variables to be
-reallocated at new addresses, changing their stringification), and
-garbage-collecting the entries when the referenced variable goes out
-of scope.
-
-If you actually need to be able to get a real reference back from
-each hash entry, you can use the Tie::RefHash module, which does the
-required work for you.
-
-=head2 How can I check if a key exists in a multilevel hash?
-
-(contributed by brian d foy)
-
-The trick to this problem is avoiding accidental autovivification. If
-you want to check three keys deep, you might naE<0xEF>vely try this:
-
- my %hash;
- if( exists $hash{key1}{key2}{key3} ) {
- ...;
- }
-
-Even though you started with a completely empty hash, after that call to
-C<exists> you've created the structure you needed to check for C<key3>:
-
- %hash = (
- 'key1' => {
- 'key2' => {}
- }
- );
-
-That's autovivification. You can get around this in a few ways. The
-easiest way is to just turn it off. The lexical C<autovivification>
-pragma is available on CPAN. Now you don't add to the hash:
-
- {
- no autovivification;
- my %hash;
- if( exists $hash{key1}{key2}{key3} ) {
- ...;
- }
- }
-
-The L<Data::Diver> module on CPAN can do it for you too. Its C<Dive>
-subroutine can tell you not only if the keys exist but also get the
-value:
-
- use Data::Diver qw(Dive);
-
- my @exists = Dive( \%hash, qw(key1 key2 key3) );
- if( ! @exists ) {
- ...; # keys do not exist
- }
- elsif( ! defined $exists[0] ) {
- ...; # keys exist but value is undef
- }
-
-You can easily do this yourself too by checking each level of the hash
-before you move onto the next level. This is essentially what
-L<Data::Diver> does for you:
-
- if( check_hash( \%hash, qw(key1 key2 key3) ) ) {
- ...;
- }
-
- sub check_hash {
- my( $hash, @keys ) = @_;
-
- return unless @keys;
-
- foreach my $key ( @keys ) {
- return unless eval { exists $hash->{$key} };
- $hash = $hash->{$key};
- }
-
- return 1;
- }
-
-=head2 How can I prevent addition of unwanted keys into a hash?
-
-Since version 5.8.0, hashes can be I<restricted> to a fixed number
-of given keys. Methods for creating and dealing with restricted hashes
-are exported by the L<Hash::Util> module.
-
-=head1 Data: Misc
-
-=head2 How do I handle binary data correctly?
-
-Perl is binary-clean, so it can handle binary data just fine.
-On Windows or DOS, however, you have to use C<binmode> for binary
-files to avoid conversions for line endings. In general, you should
-use C<binmode> any time you want to work with binary data.
-
-Also see L<perlfunc/"binmode"> or L<perlopentut>.
-
-If you're concerned about 8-bit textual data then see L<perllocale>.
-If you want to deal with multibyte characters, however, there are
-some gotchas. See the section on Regular Expressions.
-
-=head2 How do I determine whether a scalar is a number/whole/integer/float?
-
-Assuming that you don't care about IEEE notations like "NaN" or
-"Infinity", you probably just want to use a regular expression:
-
- use 5.010;
-
- given( $number ) {
- when( /\D/ )
- { say "\thas nondigits"; continue }
- when( /^\d+\z/ )
- { say "\tis a whole number"; continue }
- when( /^-?\d+\z/ )
- { say "\tis an integer"; continue }
- when( /^[+-]?\d+\z/ )
- { say "\tis a +/- integer"; continue }
- when( /^-?(?:\d+\.?|\.\d)\d*\z/ )
- { say "\tis a real number"; continue }
- when( /^[+-]?(?=\.?\d)\d*\.?\d*(?:e[+-]?\d+)?\z/i)
- { say "\tis a C float" }
- }
-
-There are also some commonly used modules for the task.
-L<Scalar::Util> (distributed with 5.8) provides access to perl's
-internal function C<looks_like_number> for determining whether a
-variable looks like a number. L<Data::Types> exports functions that
-validate data types using both the above and other regular
-expressions. Thirdly, there is L<Regexp::Common> which has regular
-expressions to match various types of numbers. Those three modules are
-available from the CPAN.
-
-If you're on a POSIX system, Perl supports the C<POSIX::strtod>
-function for converting strings to doubles (and also C<POSIX::strtol>
-for longs). Its semantics are somewhat cumbersome, so here's a
-C<getnum> wrapper function for more convenient access. This function
-takes a string and returns the number it found, or C<undef> for input
-that isn't a C float. The C<is_numeric> function is a front end to
-C<getnum> if you just want to say, "Is this a float?"
-
- sub getnum {
- use POSIX qw(strtod);
- my $str = shift;
- $str =~ s/^\s+//;
- $str =~ s/\s+$//;
- $! = 0;
- my($num, $unparsed) = strtod($str);
- if (($str eq '') || ($unparsed != 0) || $!) {
- return undef;
- }
- else {
- return $num;
- }
- }
-
- sub is_numeric { defined getnum($_[0]) }
-
-Or you could check out the L<String::Scanf> module on the CPAN
-instead.
-
-=head2 How do I keep persistent data across program calls?
-
-For some specific applications, you can use one of the DBM modules.
-See L<AnyDBM_File>. More generically, you should consult the L<FreezeThaw>
-or L<Storable> modules from CPAN. Starting from Perl 5.8, L<Storable> is part
-of the standard distribution. Here's one example using L<Storable>'s C<store>
-and C<retrieve> functions:
-
- use Storable;
- store(\%hash, "filename");
-
- # later on...
- $href = retrieve("filename"); # by ref
- %hash = %{ retrieve("filename") }; # direct to hash
-
-=head2 How do I print out or copy a recursive data structure?
-
-The L<Data::Dumper> module on CPAN (or the 5.005 release of Perl) is great
-for printing out data structures. The L<Storable> module on CPAN (or the
-5.8 release of Perl), provides a function called C<dclone> that recursively
-copies its argument.
-
- use Storable qw(dclone);
- $r2 = dclone($r1);
-
-Where C<$r1> can be a reference to any kind of data structure you'd like.
-It will be deeply copied. Because C<dclone> takes and returns references,
-you'd have to add extra punctuation if you had a hash of arrays that
-you wanted to copy.
-
- %newhash = %{ dclone(\%oldhash) };
-
-=head2 How do I define methods for every class/object?
-
-(contributed by Ben Morrow)
-
-You can use the C<UNIVERSAL> class (see L<UNIVERSAL>). However, please
-be very careful to consider the consequences of doing this: adding
-methods to every object is very likely to have unintended
-consequences. If possible, it would be better to have all your object
-inherit from some common base class, or to use an object system like
-Moose that supports roles.
-
-=head2 How do I verify a credit card checksum?
-
-Get the L<Business::CreditCard> module from CPAN.
-
-=head2 How do I pack arrays of doubles or floats for XS code?
-
-The arrays.h/arrays.c code in the L<PGPLOT> module on CPAN does just this.
-If you're doing a lot of float or double processing, consider using
-the L<PDL> module from CPAN instead--it makes number-crunching easy.
-
-See L<http://search.cpan.org/dist/PGPLOT> for the code.
-
-
-=head1 AUTHOR AND COPYRIGHT
-
-Copyright (c) 1997-2010 Tom Christiansen, Nathan Torkington, and
-other authors as noted. All rights reserved.
-
-This documentation is free; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-Irrespective of its distribution, all code examples in this file
-are hereby placed into the public domain. You are permitted and
-encouraged to use this code in your own programs for fun
-or for profit as you see fit. A simple comment in the code giving
-credit would be courteous but is not required.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq5.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq5.pod
deleted file mode 100644
index 60bd08306d5..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlfaq5.pod
+++ /dev/null
@@ -1,1574 +0,0 @@
-=head1 NAME
-
-perlfaq5 - Files and Formats
-
-=head1 DESCRIPTION
-
-This section deals with I/O and the "f" issues: filehandles, flushing,
-formats, and footers.
-
-=head2 How do I flush/unbuffer an output filehandle? Why must I do this?
-X<flush> X<buffer> X<unbuffer> X<autoflush>
-
-(contributed by brian d foy)
-
-You might like to read Mark Jason Dominus's "Suffering From Buffering"
-at L<http://perl.plover.com/FAQs/Buffering.html> .
-
-Perl normally buffers output so it doesn't make a system call for every
-bit of output. By saving up output, it makes fewer expensive system calls.
-For instance, in this little bit of code, you want to print a dot to the
-screen for every line you process to watch the progress of your program.
-Instead of seeing a dot for every line, Perl buffers the output and you
-have a long wait before you see a row of 50 dots all at once:
-
- # long wait, then row of dots all at once
- while( <> ) {
- print ".";
- print "\n" unless ++$count % 50;
-
- #... expensive line processing operations
- }
-
-To get around this, you have to unbuffer the output filehandle, in this
-case, C<STDOUT>. You can set the special variable C<$|> to a true value
-(mnemonic: making your filehandles "piping hot"):
-
- $|++;
-
- # dot shown immediately
- while( <> ) {
- print ".";
- print "\n" unless ++$count % 50;
-
- #... expensive line processing operations
- }
-
-The C<$|> is one of the per-filehandle special variables, so each
-filehandle has its own copy of its value. If you want to merge
-standard output and standard error for instance, you have to unbuffer
-each (although STDERR might be unbuffered by default):
-
- {
- my $previous_default = select(STDOUT); # save previous default
- $|++; # autoflush STDOUT
- select(STDERR);
- $|++; # autoflush STDERR, to be sure
- select($previous_default); # restore previous default
- }
-
- # now should alternate . and +
- while( 1 ) {
- sleep 1;
- print STDOUT ".";
- print STDERR "+";
- print STDOUT "\n" unless ++$count % 25;
- }
-
-Besides the C<$|> special variable, you can use C<binmode> to give
-your filehandle a C<:unix> layer, which is unbuffered:
-
- binmode( STDOUT, ":unix" );
-
- while( 1 ) {
- sleep 1;
- print ".";
- print "\n" unless ++$count % 50;
- }
-
-For more information on output layers, see the entries for C<binmode>
-and L<open> in L<perlfunc>, and the L<PerlIO> module documentation.
-
-If you are using L<IO::Handle> or one of its subclasses, you can
-call the C<autoflush> method to change the settings of the
-filehandle:
-
- use IO::Handle;
- open my( $io_fh ), ">", "output.txt";
- $io_fh->autoflush(1);
-
-The L<IO::Handle> objects also have a C<flush> method. You can flush
-the buffer any time you want without auto-buffering
-
- $io_fh->flush;
-
-=head2 How do I change, delete, or insert a line in a file, or append to the beginning of a file?
-X<file, editing>
-
-(contributed by brian d foy)
-
-The basic idea of inserting, changing, or deleting a line from a text
-file involves reading and printing the file to the point you want to
-make the change, making the change, then reading and printing the rest
-of the file. Perl doesn't provide random access to lines (especially
-since the record input separator, C<$/>, is mutable), although modules
-such as L<Tie::File> can fake it.
-
-A Perl program to do these tasks takes the basic form of opening a
-file, printing its lines, then closing the file:
-
- open my $in, '<', $file or die "Can't read old file: $!";
- open my $out, '>', "$file.new" or die "Can't write new file: $!";
-
- while( <$in> ) {
- print $out $_;
- }
-
- close $out;
-
-Within that basic form, add the parts that you need to insert, change,
-or delete lines.
-
-To prepend lines to the beginning, print those lines before you enter
-the loop that prints the existing lines.
-
- open my $in, '<', $file or die "Can't read old file: $!";
- open my $out, '>', "$file.new" or die "Can't write new file: $!";
-
- print $out "# Add this line to the top\n"; # <--- HERE'S THE MAGIC
-
- while( <$in> ) {
- print $out $_;
- }
-
- close $out;
-
-To change existing lines, insert the code to modify the lines inside
-the C<while> loop. In this case, the code finds all lowercased
-versions of "perl" and uppercases them. The happens for every line, so
-be sure that you're supposed to do that on every line!
-
- open my $in, '<', $file or die "Can't read old file: $!";
- open my $out, '>', "$file.new" or die "Can't write new file: $!";
-
- print $out "# Add this line to the top\n";
-
- while( <$in> ) {
- s/\b(perl)\b/Perl/g;
- print $out $_;
- }
-
- close $out;
-
-To change only a particular line, the input line number, C<$.>, is
-useful. First read and print the lines up to the one you want to
-change. Next, read the single line you want to change, change it, and
-print it. After that, read the rest of the lines and print those:
-
- while( <$in> ) { # print the lines before the change
- print $out $_;
- last if $. == 4; # line number before change
- }
-
- my $line = <$in>;
- $line =~ s/\b(perl)\b/Perl/g;
- print $out $line;
-
- while( <$in> ) { # print the rest of the lines
- print $out $_;
- }
-
-To skip lines, use the looping controls. The C<next> in this example
-skips comment lines, and the C<last> stops all processing once it
-encounters either C<__END__> or C<__DATA__>.
-
- while( <$in> ) {
- next if /^\s+#/; # skip comment lines
- last if /^__(END|DATA)__$/; # stop at end of code marker
- print $out $_;
- }
-
-Do the same sort of thing to delete a particular line by using C<next>
-to skip the lines you don't want to show up in the output. This
-example skips every fifth line:
-
- while( <$in> ) {
- next unless $. % 5;
- print $out $_;
- }
-
-If, for some odd reason, you really want to see the whole file at once
-rather than processing line-by-line, you can slurp it in (as long as
-you can fit the whole thing in memory!):
-
- open my $in, '<', $file or die "Can't read old file: $!"
- open my $out, '>', "$file.new" or die "Can't write new file: $!";
-
- my @lines = do { local $/; <$in> }; # slurp!
-
- # do your magic here
-
- print $out @lines;
-
-Modules such as L<File::Slurp> and L<Tie::File> can help with that
-too. If you can, however, avoid reading the entire file at once. Perl
-won't give that memory back to the operating system until the process
-finishes.
-
-You can also use Perl one-liners to modify a file in-place. The
-following changes all 'Fred' to 'Barney' in F<inFile.txt>, overwriting
-the file with the new contents. With the C<-p> switch, Perl wraps a
-C<while> loop around the code you specify with C<-e>, and C<-i> turns
-on in-place editing. The current line is in C<$_>. With C<-p>, Perl
-automatically prints the value of C<$_> at the end of the loop. See
-L<perlrun> for more details.
-
- perl -pi -e 's/Fred/Barney/' inFile.txt
-
-To make a backup of C<inFile.txt>, give C<-i> a file extension to add:
-
- perl -pi.bak -e 's/Fred/Barney/' inFile.txt
-
-To change only the fifth line, you can add a test checking C<$.>, the
-input line number, then only perform the operation when the test
-passes:
-
- perl -pi -e 's/Fred/Barney/ if $. == 5' inFile.txt
-
-To add lines before a certain line, you can add a line (or lines!)
-before Perl prints C<$_>:
-
- perl -pi -e 'print "Put before third line\n" if $. == 3' inFile.txt
-
-You can even add a line to the beginning of a file, since the current
-line prints at the end of the loop:
-
- perl -pi -e 'print "Put before first line\n" if $. == 1' inFile.txt
-
-To insert a line after one already in the file, use the C<-n> switch.
-It's just like C<-p> except that it doesn't print C<$_> at the end of
-the loop, so you have to do that yourself. In this case, print C<$_>
-first, then print the line that you want to add.
-
- perl -ni -e 'print; print "Put after fifth line\n" if $. == 5' inFile.txt
-
-To delete lines, only print the ones that you want.
-
- perl -ni -e 'print if /d/' inFile.txt
-
-=head2 How do I count the number of lines in a file?
-X<file, counting lines> X<lines> X<line>
-
-(contributed by brian d foy)
-
-Conceptually, the easiest way to count the lines in a file is to
-simply read them and count them:
-
- my $count = 0;
- while( <$fh> ) { $count++; }
-
-You don't really have to count them yourself, though, since Perl
-already does that with the C<$.> variable, which is the current line
-number from the last filehandle read:
-
- 1 while( <$fh> );
- my $count = $.;
-
-If you want to use C<$.>, you can reduce it to a simple one-liner,
-like one of these:
-
- % perl -lne '} print $.; {' file
-
- % perl -lne 'END { print $. }' file
-
-Those can be rather inefficient though. If they aren't fast enough for
-you, you might just read chunks of data and count the number of
-newlines:
-
- my $lines = 0;
- open my($fh), '<:raw', $filename or die "Can't open $filename: $!";
- while( sysread $fh, $buffer, 4096 ) {
- $lines += ( $buffer =~ tr/\n// );
- }
- close FILE;
-
-However, that doesn't work if the line ending isn't a newline. You
-might change that C<tr///> to a C<s///> so you can count the number of
-times the input record separator, C<$/>, shows up:
-
- my $lines = 0;
- open my($fh), '<:raw', $filename or die "Can't open $filename: $!";
- while( sysread $fh, $buffer, 4096 ) {
- $lines += ( $buffer =~ s|$/||g; );
- }
- close FILE;
-
-If you don't mind shelling out, the C<wc> command is usually the
-fastest, even with the extra interprocess overhead. Ensure that you
-have an untainted filename though:
-
- #!perl -T
-
- $ENV{PATH} = undef;
-
- my $lines;
- if( $filename =~ /^([0-9a-z_.]+)\z/ ) {
- $lines = `/usr/bin/wc -l $1`
- chomp $lines;
- }
-
-=head2 How do I delete the last N lines from a file?
-X<lines> X<file>
-
-(contributed by brian d foy)
-
-The easiest conceptual solution is to count the lines in the
-file then start at the beginning and print the number of lines
-(minus the last N) to a new file.
-
-Most often, the real question is how you can delete the last N lines
-without making more than one pass over the file, or how to do it
-without a lot of copying. The easy concept is the hard reality when
-you might have millions of lines in your file.
-
-One trick is to use L<File::ReadBackwards>, which starts at the end of
-the file. That module provides an object that wraps the real filehandle
-to make it easy for you to move around the file. Once you get to the
-spot you need, you can get the actual filehandle and work with it as
-normal. In this case, you get the file position at the end of the last
-line you want to keep and truncate the file to that point:
-
- use File::ReadBackwards;
-
- my $filename = 'test.txt';
- my $Lines_to_truncate = 2;
-
- my $bw = File::ReadBackwards->new( $filename )
- or die "Could not read backwards in [$filename]: $!";
-
- my $lines_from_end = 0;
- until( $bw->eof or $lines_from_end == $Lines_to_truncate ) {
- print "Got: ", $bw->readline;
- $lines_from_end++;
- }
-
- truncate( $filename, $bw->tell );
-
-The L<File::ReadBackwards> module also has the advantage of setting
-the input record separator to a regular expression.
-
-You can also use the L<Tie::File> module which lets you access
-the lines through a tied array. You can use normal array operations
-to modify your file, including setting the last index and using
-C<splice>.
-
-=head2 How can I use Perl's C<-i> option from within a program?
-X<-i> X<in-place>
-
-C<-i> sets the value of Perl's C<$^I> variable, which in turn affects
-the behavior of C<< <> >>; see L<perlrun> for more details. By
-modifying the appropriate variables directly, you can get the same
-behavior within a larger program. For example:
-
- # ...
- {
- local($^I, @ARGV) = ('.orig', glob("*.c"));
- while (<>) {
- if ($. == 1) {
- print "This line should appear at the top of each file\n";
- }
- s/\b(p)earl\b/${1}erl/i; # Correct typos, preserving case
- print;
- close ARGV if eof; # Reset $.
- }
- }
- # $^I and @ARGV return to their old values here
-
-This block modifies all the C<.c> files in the current directory,
-leaving a backup of the original data from each file in a new
-C<.c.orig> file.
-
-=head2 How can I copy a file?
-X<copy> X<file, copy> X<File::Copy>
-
-(contributed by brian d foy)
-
-Use the L<File::Copy> module. It comes with Perl and can do a
-true copy across file systems, and it does its magic in
-a portable fashion.
-
- use File::Copy;
-
- copy( $original, $new_copy ) or die "Copy failed: $!";
-
-If you can't use L<File::Copy>, you'll have to do the work yourself:
-open the original file, open the destination file, then print
-to the destination file as you read the original. You also have to
-remember to copy the permissions, owner, and group to the new file.
-
-=head2 How do I make a temporary file name?
-X<file, temporary>
-
-If you don't need to know the name of the file, you can use C<open()>
-with C<undef> in place of the file name. In Perl 5.8 or later, the
-C<open()> function creates an anonymous temporary file:
-
- open my $tmp, '+>', undef or die $!;
-
-Otherwise, you can use the File::Temp module.
-
- use File::Temp qw/ tempfile tempdir /;
-
- my $dir = tempdir( CLEANUP => 1 );
- ($fh, $filename) = tempfile( DIR => $dir );
-
- # or if you don't need to know the filename
-
- my $fh = tempfile( DIR => $dir );
-
-The File::Temp has been a standard module since Perl 5.6.1. If you
-don't have a modern enough Perl installed, use the C<new_tmpfile>
-class method from the IO::File module to get a filehandle opened for
-reading and writing. Use it if you don't need to know the file's name:
-
- use IO::File;
- my $fh = IO::File->new_tmpfile()
- or die "Unable to make new temporary file: $!";
-
-If you're committed to creating a temporary file by hand, use the
-process ID and/or the current time-value. If you need to have many
-temporary files in one process, use a counter:
-
- BEGIN {
- use Fcntl;
- my $temp_dir = -d '/tmp' ? '/tmp' : $ENV{TMPDIR} || $ENV{TEMP};
- my $base_name = sprintf "%s/%d-%d-0000", $temp_dir, $$, time;
-
- sub temp_file {
- my $fh;
- my $count = 0;
- until( defined(fileno($fh)) || $count++ > 100 ) {
- $base_name =~ s/-(\d+)$/"-" . (1 + $1)/e;
- # O_EXCL is required for security reasons.
- sysopen $fh, $base_name, O_WRONLY|O_EXCL|O_CREAT;
- }
-
- if( defined fileno($fh) ) {
- return ($fh, $base_name);
- }
- else {
- return ();
- }
- }
- }
-
-=head2 How can I manipulate fixed-record-length files?
-X<fixed-length> X<file, fixed-length records>
-
-The most efficient way is using L<pack()|perlfunc/"pack"> and
-L<unpack()|perlfunc/"unpack">. This is faster than using
-L<substr()|perlfunc/"substr"> when taking many, many strings. It is
-slower for just a few.
-
-Here is a sample chunk of code to break up and put back together again
-some fixed-format input lines, in this case from the output of a normal,
-Berkeley-style ps:
-
- # sample input line:
- # 15158 p5 T 0:00 perl /home/tchrist/scripts/now-what
- my $PS_T = 'A6 A4 A7 A5 A*';
- open my $ps, '-|', 'ps';
- print scalar <$ps>;
- my @fields = qw( pid tt stat time command );
- while (<$ps>) {
- my %process;
- @process{@fields} = unpack($PS_T, $_);
- for my $field ( @fields ) {
- print "$field: <$process{$field}>\n";
- }
- print 'line=', pack($PS_T, @process{@fields} ), "\n";
- }
-
-We've used a hash slice in order to easily handle the fields of each row.
-Storing the keys in an array makes it easy to operate on them as a
-group or loop over them with C<for>. It also avoids polluting the program
-with global variables and using symbolic references.
-
-=head2 How can I make a filehandle local to a subroutine? How do I pass filehandles between subroutines? How do I make an array of filehandles?
-X<filehandle, local> X<filehandle, passing> X<filehandle, reference>
-
-As of perl5.6, open() autovivifies file and directory handles
-as references if you pass it an uninitialized scalar variable.
-You can then pass these references just like any other scalar,
-and use them in the place of named handles.
-
- open my $fh, $file_name;
-
- open local $fh, $file_name;
-
- print $fh "Hello World!\n";
-
- process_file( $fh );
-
-If you like, you can store these filehandles in an array or a hash.
-If you access them directly, they aren't simple scalars and you
-need to give C<print> a little help by placing the filehandle
-reference in braces. Perl can only figure it out on its own when
-the filehandle reference is a simple scalar.
-
- my @fhs = ( $fh1, $fh2, $fh3 );
-
- for( $i = 0; $i <= $#fhs; $i++ ) {
- print {$fhs[$i]} "just another Perl answer, \n";
- }
-
-Before perl5.6, you had to deal with various typeglob idioms
-which you may see in older code.
-
- open FILE, "> $filename";
- process_typeglob( *FILE );
- process_reference( \*FILE );
-
- sub process_typeglob { local *FH = shift; print FH "Typeglob!" }
- sub process_reference { local $fh = shift; print $fh "Reference!" }
-
-If you want to create many anonymous handles, you should
-check out the Symbol or IO::Handle modules.
-
-=head2 How can I use a filehandle indirectly?
-X<filehandle, indirect>
-
-An indirect filehandle is the use of something other than a symbol
-in a place that a filehandle is expected. Here are ways
-to get indirect filehandles:
-
- $fh = SOME_FH; # bareword is strict-subs hostile
- $fh = "SOME_FH"; # strict-refs hostile; same package only
- $fh = *SOME_FH; # typeglob
- $fh = \*SOME_FH; # ref to typeglob (bless-able)
- $fh = *SOME_FH{IO}; # blessed IO::Handle from *SOME_FH typeglob
-
-Or, you can use the C<new> method from one of the IO::* modules to
-create an anonymous filehandle and store that in a scalar variable.
-
- use IO::Handle; # 5.004 or higher
- my $fh = IO::Handle->new();
-
-Then use any of those as you would a normal filehandle. Anywhere that
-Perl is expecting a filehandle, an indirect filehandle may be used
-instead. An indirect filehandle is just a scalar variable that contains
-a filehandle. Functions like C<print>, C<open>, C<seek>, or
-the C<< <FH> >> diamond operator will accept either a named filehandle
-or a scalar variable containing one:
-
- ($ifh, $ofh, $efh) = (*STDIN, *STDOUT, *STDERR);
- print $ofh "Type it: ";
- my $got = <$ifh>
- print $efh "What was that: $got";
-
-If you're passing a filehandle to a function, you can write
-the function in two ways:
-
- sub accept_fh {
- my $fh = shift;
- print $fh "Sending to indirect filehandle\n";
- }
-
-Or it can localize a typeglob and use the filehandle directly:
-
- sub accept_fh {
- local *FH = shift;
- print FH "Sending to localized filehandle\n";
- }
-
-Both styles work with either objects or typeglobs of real filehandles.
-(They might also work with strings under some circumstances, but this
-is risky.)
-
- accept_fh(*STDOUT);
- accept_fh($handle);
-
-In the examples above, we assigned the filehandle to a scalar variable
-before using it. That is because only simple scalar variables, not
-expressions or subscripts of hashes or arrays, can be used with
-built-ins like C<print>, C<printf>, or the diamond operator. Using
-something other than a simple scalar variable as a filehandle is
-illegal and won't even compile:
-
- my @fd = (*STDIN, *STDOUT, *STDERR);
- print $fd[1] "Type it: "; # WRONG
- my $got = <$fd[0]> # WRONG
- print $fd[2] "What was that: $got"; # WRONG
-
-With C<print> and C<printf>, you get around this by using a block and
-an expression where you would place the filehandle:
-
- print { $fd[1] } "funny stuff\n";
- printf { $fd[1] } "Pity the poor %x.\n", 3_735_928_559;
- # Pity the poor deadbeef.
-
-That block is a proper block like any other, so you can put more
-complicated code there. This sends the message out to one of two places:
-
- my $ok = -x "/bin/cat";
- print { $ok ? $fd[1] : $fd[2] } "cat stat $ok\n";
- print { $fd[ 1+ ($ok || 0) ] } "cat stat $ok\n";
-
-This approach of treating C<print> and C<printf> like object methods
-calls doesn't work for the diamond operator. That's because it's a
-real operator, not just a function with a comma-less argument. Assuming
-you've been storing typeglobs in your structure as we did above, you
-can use the built-in function named C<readline> to read a record just
-as C<< <> >> does. Given the initialization shown above for @fd, this
-would work, but only because readline() requires a typeglob. It doesn't
-work with objects or strings, which might be a bug we haven't fixed yet.
-
- $got = readline($fd[0]);
-
-Let it be noted that the flakiness of indirect filehandles is not
-related to whether they're strings, typeglobs, objects, or anything else.
-It's the syntax of the fundamental operators. Playing the object
-game doesn't help you at all here.
-
-=head2 How can I set up a footer format to be used with write()?
-X<footer>
-
-There's no builtin way to do this, but L<perlform> has a couple of
-techniques to make it possible for the intrepid hacker.
-
-=head2 How can I write() into a string?
-X<write, into a string>
-
-(contributed by brian d foy)
-
-If you want to C<write> into a string, you just have to <open> a
-filehandle to a string, which Perl has been able to do since Perl 5.6:
-
- open FH, '>', \my $string;
- write( FH );
-
-Since you want to be a good programmer, you probably want to use a lexical
-filehandle, even though formats are designed to work with bareword filehandles
-since the default format names take the filehandle name. However, you can
-control this with some Perl special per-filehandle variables: C<$^>, which
-names the top-of-page format, and C<$~> which shows the line format. You have
-to change the default filehandle to set these variables:
-
- open my($fh), '>', \my $string;
-
- { # set per-filehandle variables
- my $old_fh = select( $fh );
- $~ = 'ANIMAL';
- $^ = 'ANIMAL_TOP';
- select( $old_fh );
- }
-
- format ANIMAL_TOP =
- ID Type Name
- .
-
- format ANIMAL =
- @## @<<< @<<<<<<<<<<<<<<
- $id, $type, $name
- .
-
-Although write can work with lexical or package variables, whatever variables
-you use have to scope in the format. That most likely means you'll want to
-localize some package variables:
-
- {
- local( $id, $type, $name ) = qw( 12 cat Buster );
- write( $fh );
- }
-
- print $string;
-
-There are also some tricks that you can play with C<formline> and the
-accumulator variable C<$^A>, but you lose a lot of the value of formats
-since C<formline> won't handle paging and so on. You end up reimplementing
-formats when you use them.
-
-=head2 How can I open a filehandle to a string?
-X<string> X<open> X<IO::String> X<filehandle>
-
-(contributed by Peter J. Holzer, hjp-usenet2@hjp.at)
-
-Since Perl 5.8.0 a file handle referring to a string can be created by
-calling open with a reference to that string instead of the filename.
-This file handle can then be used to read from or write to the string:
-
- open(my $fh, '>', \$string) or die "Could not open string for writing";
- print $fh "foo\n";
- print $fh "bar\n"; # $string now contains "foo\nbar\n"
-
- open(my $fh, '<', \$string) or die "Could not open string for reading";
- my $x = <$fh>; # $x now contains "foo\n"
-
-With older versions of Perl, the L<IO::String> module provides similar
-functionality.
-
-=head2 How can I output my numbers with commas added?
-X<number, commify>
-
-(contributed by brian d foy and Benjamin Goldberg)
-
-You can use L<Number::Format> to separate places in a number.
-It handles locale information for those of you who want to insert
-full stops instead (or anything else that they want to use,
-really).
-
-This subroutine will add commas to your number:
-
- sub commify {
- local $_ = shift;
- 1 while s/^([-+]?\d+)(\d{3})/$1,$2/;
- return $_;
- }
-
-This regex from Benjamin Goldberg will add commas to numbers:
-
- s/(^[-+]?\d+?(?=(?>(?:\d{3})+)(?!\d))|\G\d{3}(?=\d))/$1,/g;
-
-It is easier to see with comments:
-
- s/(
- ^[-+]? # beginning of number.
- \d+? # first digits before first comma
- (?= # followed by, (but not included in the match) :
- (?>(?:\d{3})+) # some positive multiple of three digits.
- (?!\d) # an *exact* multiple, not x * 3 + 1 or whatever.
- )
- | # or:
- \G\d{3} # after the last group, get three digits
- (?=\d) # but they have to have more digits after them.
- )/$1,/xg;
-
-=head2 How can I translate tildes (~) in a filename?
-X<tilde> X<tilde expansion>
-
-Use the E<lt>E<gt> (C<glob()>) operator, documented in L<perlfunc>.
-Versions of Perl older than 5.6 require that you have a shell
-installed that groks tildes. Later versions of Perl have this feature
-built in. The L<File::KGlob> module (available from CPAN) gives more
-portable glob functionality.
-
-Within Perl, you may use this directly:
-
- $filename =~ s{
- ^ ~ # find a leading tilde
- ( # save this in $1
- [^/] # a non-slash character
- * # repeated 0 or more times (0 means me)
- )
- }{
- $1
- ? (getpwnam($1))[7]
- : ( $ENV{HOME} || $ENV{LOGDIR} )
- }ex;
-
-=head2 How come when I open a file read-write it wipes it out?
-X<clobber> X<read-write> X<clobbering> X<truncate> X<truncating>
-
-Because you're using something like this, which truncates the file
-I<then> gives you read-write access:
-
- open my $fh, '+>', '/path/name'; # WRONG (almost always)
-
-Whoops. You should instead use this, which will fail if the file
-doesn't exist:
-
- open my $fh, '+<', '/path/name'; # open for update
-
-Using ">" always clobbers or creates. Using "<" never does
-either. The "+" doesn't change this.
-
-Here are examples of many kinds of file opens. Those using C<sysopen>
-all assume that you've pulled in the constants from L<Fcntl>:
-
- use Fcntl;
-
-To open file for reading:
-
- open my $fh, '<', $path or die $!;
- sysopen my $fh, $path, O_RDONLY or die $!;
-
-To open file for writing, create new file if needed or else truncate old file:
-
- open my $fh, '>', $path or die $!;
- sysopen my $fh, $path, O_WRONLY|O_TRUNC|O_CREAT or die $!;
- sysopen my $fh, $path, O_WRONLY|O_TRUNC|O_CREAT, 0666 or die $!;
-
-To open file for writing, create new file, file must not exist:
-
- sysopen my $fh, $path, O_WRONLY|O_EXCL|O_CREAT or die $!;
- sysopen my $fh, $path, O_WRONLY|O_EXCL|O_CREAT, 0666 or die $!;
-
-To open file for appending, create if necessary:
-
- open my $fh, '>>' $path or die $!;
- sysopen my $fh, $path, O_WRONLY|O_APPEND|O_CREAT or die $!;
- sysopen my $fh, $path, O_WRONLY|O_APPEND|O_CREAT, 0666 or die $!;
-
-To open file for appending, file must exist:
-
- sysopen my $fh, $path, O_WRONLY|O_APPEND or die $!;
-
-To open file for update, file must exist:
-
- open my $fh, '+<', $path or die $!;
- sysopen my $fh, $path, O_RDWR or die $!;
-
-To open file for update, create file if necessary:
-
- sysopen my $fh, $path, O_RDWR|O_CREAT or die $!;
- sysopen my $fh, $path, O_RDWR|O_CREAT, 0666 or die $!;
-
-To open file for update, file must not exist:
-
- sysopen my $fh, $path, O_RDWR|O_EXCL|O_CREAT or die $!;
- sysopen my $fh, $path, O_RDWR|O_EXCL|O_CREAT, 0666 or die $!;
-
-To open a file without blocking, creating if necessary:
-
- sysopen my $fh, '/foo/somefile', O_WRONLY|O_NDELAY|O_CREAT
- or die "can't open /foo/somefile: $!":
-
-Be warned that neither creation nor deletion of files is guaranteed to
-be an atomic operation over NFS. That is, two processes might both
-successfully create or unlink the same file! Therefore O_EXCL
-isn't as exclusive as you might wish.
-
-See also L<perlopentut>.
-
-=head2 Why do I sometimes get an "Argument list too long" when I use E<lt>*E<gt>?
-X<argument list too long>
-
-The C<< <> >> operator performs a globbing operation (see above).
-In Perl versions earlier than v5.6.0, the internal glob() operator forks
-csh(1) to do the actual glob expansion, but
-csh can't handle more than 127 items and so gives the error message
-C<Argument list too long>. People who installed tcsh as csh won't
-have this problem, but their users may be surprised by it.
-
-To get around this, either upgrade to Perl v5.6.0 or later, do the glob
-yourself with readdir() and patterns, or use a module like L<File::Glob>,
-one that doesn't use the shell to do globbing.
-
-=head2 How can I open a file with a leading ">" or trailing blanks?
-X<filename, special characters>
-
-(contributed by Brian McCauley)
-
-The special two-argument form of Perl's open() function ignores
-trailing blanks in filenames and infers the mode from certain leading
-characters (or a trailing "|"). In older versions of Perl this was the
-only version of open() and so it is prevalent in old code and books.
-
-Unless you have a particular reason to use the two-argument form you
-should use the three-argument form of open() which does not treat any
-characters in the filename as special.
-
- open my $fh, "<", " file "; # filename is " file "
- open my $fh, ">", ">file"; # filename is ">file"
-
-=head2 How can I reliably rename a file?
-X<rename> X<mv> X<move> X<file, rename>
-
-If your operating system supports a proper mv(1) utility or its
-functional equivalent, this works:
-
- rename($old, $new) or system("mv", $old, $new);
-
-It may be more portable to use the L<File::Copy> module instead.
-You just copy to the new file to the new name (checking return
-values), then delete the old one. This isn't really the same
-semantically as a C<rename()>, which preserves meta-information like
-permissions, timestamps, inode info, etc.
-
-=head2 How can I lock a file?
-X<lock> X<file, lock> X<flock>
-
-Perl's builtin flock() function (see L<perlfunc> for details) will call
-flock(2) if that exists, fcntl(2) if it doesn't (on perl version 5.004 and
-later), and lockf(3) if neither of the two previous system calls exists.
-On some systems, it may even use a different form of native locking.
-Here are some gotchas with Perl's flock():
-
-=over 4
-
-=item 1
-
-Produces a fatal error if none of the three system calls (or their
-close equivalent) exists.
-
-=item 2
-
-lockf(3) does not provide shared locking, and requires that the
-filehandle be open for writing (or appending, or read/writing).
-
-=item 3
-
-Some versions of flock() can't lock files over a network (e.g. on NFS file
-systems), so you'd need to force the use of fcntl(2) when you build Perl.
-But even this is dubious at best. See the flock entry of L<perlfunc>
-and the F<INSTALL> file in the source distribution for information on
-building Perl to do this.
-
-Two potentially non-obvious but traditional flock semantics are that
-it waits indefinitely until the lock is granted, and that its locks are
-I<merely advisory>. Such discretionary locks are more flexible, but
-offer fewer guarantees. This means that files locked with flock() may
-be modified by programs that do not also use flock(). Cars that stop
-for red lights get on well with each other, but not with cars that don't
-stop for red lights. See the perlport manpage, your port's specific
-documentation, or your system-specific local manpages for details. It's
-best to assume traditional behavior if you're writing portable programs.
-(If you're not, you should as always feel perfectly free to write
-for your own system's idiosyncrasies (sometimes called "features").
-Slavish adherence to portability concerns shouldn't get in the way of
-your getting your job done.)
-
-For more information on file locking, see also
-L<perlopentut/"File Locking"> if you have it (new for 5.6).
-
-=back
-
-=head2 Why can't I just open(FH, "E<gt>file.lock")?
-X<lock, lockfile race condition>
-
-A common bit of code B<NOT TO USE> is this:
-
- sleep(3) while -e 'file.lock'; # PLEASE DO NOT USE
- open my $lock, '>', 'file.lock'; # THIS BROKEN CODE
-
-This is a classic race condition: you take two steps to do something
-which must be done in one. That's why computer hardware provides an
-atomic test-and-set instruction. In theory, this "ought" to work:
-
- sysopen my $fh, "file.lock", O_WRONLY|O_EXCL|O_CREAT
- or die "can't open file.lock: $!";
-
-except that lamentably, file creation (and deletion) is not atomic
-over NFS, so this won't work (at least, not every time) over the net.
-Various schemes involving link() have been suggested, but
-these tend to involve busy-wait, which is also less than desirable.
-
-=head2 I still don't get locking. I just want to increment the number in the file. How can I do this?
-X<counter> X<file, counter>
-
-Didn't anyone ever tell you web-page hit counters were useless?
-They don't count number of hits, they're a waste of time, and they serve
-only to stroke the writer's vanity. It's better to pick a random number;
-they're more realistic.
-
-Anyway, this is what you can do if you can't help yourself.
-
- use Fcntl qw(:DEFAULT :flock);
- sysopen my $fh, "numfile", O_RDWR|O_CREAT or die "can't open numfile: $!";
- flock $fh, LOCK_EX or die "can't flock numfile: $!";
- my $num = <$fh> || 0;
- seek $fh, 0, 0 or die "can't rewind numfile: $!";
- truncate $fh, 0 or die "can't truncate numfile: $!";
- (print $fh $num+1, "\n") or die "can't write numfile: $!";
- close $fh or die "can't close numfile: $!";
-
-Here's a much better web-page hit counter:
-
- $hits = int( (time() - 850_000_000) / rand(1_000) );
-
-If the count doesn't impress your friends, then the code might. :-)
-
-=head2 All I want to do is append a small amount of text to the end of a file. Do I still have to use locking?
-X<append> X<file, append>
-
-If you are on a system that correctly implements C<flock> and you use
-the example appending code from "perldoc -f flock" everything will be
-OK even if the OS you are on doesn't implement append mode correctly
-(if such a system exists). So if you are happy to restrict yourself to
-OSs that implement C<flock> (and that's not really much of a
-restriction) then that is what you should do.
-
-If you know you are only going to use a system that does correctly
-implement appending (i.e. not Win32) then you can omit the C<seek>
-from the code in the previous answer.
-
-If you know you are only writing code to run on an OS and filesystem
-that does implement append mode correctly (a local filesystem on a
-modern Unix for example), and you keep the file in block-buffered mode
-and you write less than one buffer-full of output between each manual
-flushing of the buffer then each bufferload is almost guaranteed to be
-written to the end of the file in one chunk without getting
-intermingled with anyone else's output. You can also use the
-C<syswrite> function which is simply a wrapper around your system's
-C<write(2)> system call.
-
-There is still a small theoretical chance that a signal will interrupt
-the system-level C<write()> operation before completion. There is also
-a possibility that some STDIO implementations may call multiple system
-level C<write()>s even if the buffer was empty to start. There may be
-some systems where this probability is reduced to zero, and this is
-not a concern when using C<:perlio> instead of your system's STDIO.
-
-=head2 How do I randomly update a binary file?
-X<file, binary patch>
-
-If you're just trying to patch a binary, in many cases something as
-simple as this works:
-
- perl -i -pe 's{window manager}{window mangler}g' /usr/bin/emacs
-
-However, if you have fixed sized records, then you might do something more
-like this:
-
- my $RECSIZE = 220; # size of record, in bytes
- my $recno = 37; # which record to update
- open my $fh, '+<', 'somewhere' or die "can't update somewhere: $!";
- seek $fh, $recno * $RECSIZE, 0;
- read $fh, $record, $RECSIZE == $RECSIZE or die "can't read record $recno: $!";
- # munge the record
- seek $fh, -$RECSIZE, 1;
- print $fh $record;
- close $fh;
-
-Locking and error checking are left as an exercise for the reader.
-Don't forget them or you'll be quite sorry.
-
-=head2 How do I get a file's timestamp in perl?
-X<timestamp> X<file, timestamp>
-
-If you want to retrieve the time at which the file was last read,
-written, or had its meta-data (owner, etc) changed, you use the B<-A>,
-B<-M>, or B<-C> file test operations as documented in L<perlfunc>.
-These retrieve the age of the file (measured against the start-time of
-your program) in days as a floating point number. Some platforms may
-not have all of these times. See L<perlport> for details. To retrieve
-the "raw" time in seconds since the epoch, you would call the stat
-function, then use C<localtime()>, C<gmtime()>, or
-C<POSIX::strftime()> to convert this into human-readable form.
-
-Here's an example:
-
- my $write_secs = (stat($file))[9];
- printf "file %s updated at %s\n", $file,
- scalar localtime($write_secs);
-
-If you prefer something more legible, use the File::stat module
-(part of the standard distribution in version 5.004 and later):
-
- # error checking left as an exercise for reader.
- use File::stat;
- use Time::localtime;
- my $date_string = ctime(stat($file)->mtime);
- print "file $file updated at $date_string\n";
-
-The POSIX::strftime() approach has the benefit of being,
-in theory, independent of the current locale. See L<perllocale>
-for details.
-
-=head2 How do I set a file's timestamp in perl?
-X<timestamp> X<file, timestamp>
-
-You use the utime() function documented in L<perlfunc/utime>.
-By way of example, here's a little program that copies the
-read and write times from its first argument to all the rest
-of them.
-
- if (@ARGV < 2) {
- die "usage: cptimes timestamp_file other_files ...\n";
- }
- my $timestamp = shift;
- my($atime, $mtime) = (stat($timestamp))[8,9];
- utime $atime, $mtime, @ARGV;
-
-Error checking is, as usual, left as an exercise for the reader.
-
-The perldoc for utime also has an example that has the same
-effect as touch(1) on files that I<already exist>.
-
-Certain file systems have a limited ability to store the times
-on a file at the expected level of precision. For example, the
-FAT and HPFS filesystem are unable to create dates on files with
-a finer granularity than two seconds. This is a limitation of
-the filesystems, not of utime().
-
-=head2 How do I print to more than one file at once?
-X<print, to multiple files>
-
-To connect one filehandle to several output filehandles,
-you can use the L<IO::Tee> or L<Tie::FileHandle::Multiplex> modules.
-
-If you only have to do this once, you can print individually
-to each filehandle.
-
- for my $fh ($fh1, $fh2, $fh3) { print $fh "whatever\n" }
-
-=head2 How can I read in an entire file all at once?
-X<slurp> X<file, slurping>
-
-The customary Perl approach for processing all the lines in a file is to
-do so one line at a time:
-
- open my $input, '<', $file or die "can't open $file: $!";
- while (<$input>) {
- chomp;
- # do something with $_
- }
- close $input or die "can't close $file: $!";
-
-This is tremendously more efficient than reading the entire file into
-memory as an array of lines and then processing it one element at a time,
-which is often--if not almost always--the wrong approach. Whenever
-you see someone do this:
-
- my @lines = <INPUT>;
-
-You should think long and hard about why you need everything loaded at
-once. It's just not a scalable solution.
-
-If you "mmap" the file with the File::Map module from
-CPAN, you can virtually load the entire file into a
-string without actually storing it in memory:
-
- use File::Map qw(map_file);
-
- map_file my $string, $filename;
-
-Once mapped, you can treat C<$string> as you would any other string.
-Since you don't necessarily have to load the data, mmap-ing can be
-very fast and may not increase your memory footprint.
-
-You might also find it more
-fun to use the standard L<Tie::File> module, or the L<DB_File> module's
-C<$DB_RECNO> bindings, which allow you to tie an array to a file so that
-accessing an element of the array actually accesses the corresponding
-line in the file.
-
-If you want to load the entire file, you can use the L<File::Slurp>
-module to do it in one one simple and efficient step:
-
- use File::Slurp;
-
- my $all_of_it = read_file($filename); # entire file in scalar
- my @all_lines = read_file($filename); # one line per element
-
-Or you can read the entire file contents into a scalar like this:
-
- my $var;
- {
- local $/;
- open my $fh, '<', $file or die "can't open $file: $!";
- $var = <$fh>;
- }
-
-That temporarily undefs your record separator, and will automatically
-close the file at block exit. If the file is already open, just use this:
-
- my $var = do { local $/; <$fh> };
-
-You can also use a localized C<@ARGV> to eliminate the C<open>:
-
- my $var = do { local( @ARGV, $/ ) = $file; <> };
-
-For ordinary files you can also use the C<read> function.
-
- read( $fh, $var, -s $fh );
-
-That third argument tests the byte size of the data on the C<$fh> filehandle
-and reads that many bytes into the buffer C<$var>.
-
-=head2 How can I read in a file by paragraphs?
-X<file, reading by paragraphs>
-
-Use the C<$/> variable (see L<perlvar> for details). You can either
-set it to C<""> to eliminate empty paragraphs (C<"abc\n\n\n\ndef">,
-for instance, gets treated as two paragraphs and not three), or
-C<"\n\n"> to accept empty paragraphs.
-
-Note that a blank line must have no blanks in it. Thus
-S<C<"fred\n \nstuff\n\n">> is one paragraph, but C<"fred\n\nstuff\n\n"> is two.
-
-=head2 How can I read a single character from a file? From the keyboard?
-X<getc> X<file, reading one character at a time>
-
-You can use the builtin C<getc()> function for most filehandles, but
-it won't (easily) work on a terminal device. For STDIN, either use
-the Term::ReadKey module from CPAN or use the sample code in
-L<perlfunc/getc>.
-
-If your system supports the portable operating system programming
-interface (POSIX), you can use the following code, which you'll note
-turns off echo processing as well.
-
- #!/usr/bin/perl -w
- use strict;
- $| = 1;
- for (1..4) {
- print "gimme: ";
- my $got = getone();
- print "--> $got\n";
- }
- exit;
-
- BEGIN {
- use POSIX qw(:termios_h);
-
- my ($term, $oterm, $echo, $noecho, $fd_stdin);
-
- my $fd_stdin = fileno(STDIN);
-
- $term = POSIX::Termios->new();
- $term->getattr($fd_stdin);
- $oterm = $term->getlflag();
-
- $echo = ECHO | ECHOK | ICANON;
- $noecho = $oterm & ~$echo;
-
- sub cbreak {
- $term->setlflag($noecho);
- $term->setcc(VTIME, 1);
- $term->setattr($fd_stdin, TCSANOW);
- }
-
- sub cooked {
- $term->setlflag($oterm);
- $term->setcc(VTIME, 0);
- $term->setattr($fd_stdin, TCSANOW);
- }
-
- sub getone {
- my $key = '';
- cbreak();
- sysread(STDIN, $key, 1);
- cooked();
- return $key;
- }
- }
-
- END { cooked() }
-
-The Term::ReadKey module from CPAN may be easier to use. Recent versions
-include also support for non-portable systems as well.
-
- use Term::ReadKey;
- open my $tty, '<', '/dev/tty';
- print "Gimme a char: ";
- ReadMode "raw";
- my $key = ReadKey 0, $tty;
- ReadMode "normal";
- printf "\nYou said %s, char number %03d\n",
- $key, ord $key;
-
-=head2 How can I tell whether there's a character waiting on a filehandle?
-
-The very first thing you should do is look into getting the Term::ReadKey
-extension from CPAN. As we mentioned earlier, it now even has limited
-support for non-portable (read: not open systems, closed, proprietary,
-not POSIX, not Unix, etc.) systems.
-
-You should also check out the Frequently Asked Questions list in
-comp.unix.* for things like this: the answer is essentially the same.
-It's very system-dependent. Here's one solution that works on BSD
-systems:
-
- sub key_ready {
- my($rin, $nfd);
- vec($rin, fileno(STDIN), 1) = 1;
- return $nfd = select($rin,undef,undef,0);
- }
-
-If you want to find out how many characters are waiting, there's
-also the FIONREAD ioctl call to be looked at. The I<h2ph> tool that
-comes with Perl tries to convert C include files to Perl code, which
-can be C<require>d. FIONREAD ends up defined as a function in the
-I<sys/ioctl.ph> file:
-
- require 'sys/ioctl.ph';
-
- $size = pack("L", 0);
- ioctl(FH, FIONREAD(), $size) or die "Couldn't call ioctl: $!\n";
- $size = unpack("L", $size);
-
-If I<h2ph> wasn't installed or doesn't work for you, you can
-I<grep> the include files by hand:
-
- % grep FIONREAD /usr/include/*/*
- /usr/include/asm/ioctls.h:#define FIONREAD 0x541B
-
-Or write a small C program using the editor of champions:
-
- % cat > fionread.c
- #include <sys/ioctl.h>
- main() {
- printf("%#08x\n", FIONREAD);
- }
- ^D
- % cc -o fionread fionread.c
- % ./fionread
- 0x4004667f
-
-And then hard-code it, leaving porting as an exercise to your successor.
-
- $FIONREAD = 0x4004667f; # XXX: opsys dependent
-
- $size = pack("L", 0);
- ioctl(FH, $FIONREAD, $size) or die "Couldn't call ioctl: $!\n";
- $size = unpack("L", $size);
-
-FIONREAD requires a filehandle connected to a stream, meaning that sockets,
-pipes, and tty devices work, but I<not> files.
-
-=head2 How do I do a C<tail -f> in perl?
-X<tail> X<IO::Handle> X<File::Tail> X<clearerr>
-
-First try
-
- seek($gw_fh, 0, 1);
-
-The statement C<seek($gw_fh, 0, 1)> doesn't change the current position,
-but it does clear the end-of-file condition on the handle, so that the
-next C<< <$gw_fh> >> makes Perl try again to read something.
-
-If that doesn't work (it relies on features of your stdio implementation),
-then you need something more like this:
-
- for (;;) {
- for ($curpos = tell($gw_fh); <$gw_fh>; $curpos =tell($gw_fh)) {
- # search for some stuff and put it into files
- }
- # sleep for a while
- seek($gw_fh, $curpos, 0); # seek to where we had been
- }
-
-If this still doesn't work, look into the C<clearerr> method
-from L<IO::Handle>, which resets the error and end-of-file states
-on the handle.
-
-There's also a L<File::Tail> module from CPAN.
-
-=head2 How do I dup() a filehandle in Perl?
-X<dup>
-
-If you check L<perlfunc/open>, you'll see that several of the ways
-to call open() should do the trick. For example:
-
- open my $log, '>>', '/foo/logfile';
- open STDERR, '>&', $log;
-
-Or even with a literal numeric descriptor:
-
- my $fd = $ENV{MHCONTEXTFD};
- open $mhcontext, "<&=$fd"; # like fdopen(3S)
-
-Note that "<&STDIN" makes a copy, but "<&=STDIN" makes
-an alias. That means if you close an aliased handle, all
-aliases become inaccessible. This is not true with
-a copied one.
-
-Error checking, as always, has been left as an exercise for the reader.
-
-=head2 How do I close a file descriptor by number?
-X<file, closing file descriptors> X<POSIX> X<close>
-
-If, for some reason, you have a file descriptor instead of a
-filehandle (perhaps you used C<POSIX::open>), you can use the
-C<close()> function from the L<POSIX> module:
-
- use POSIX ();
-
- POSIX::close( $fd );
-
-This should rarely be necessary, as the Perl C<close()> function is to be
-used for things that Perl opened itself, even if it was a dup of a
-numeric descriptor as with C<MHCONTEXT> above. But if you really have
-to, you may be able to do this:
-
- require 'sys/syscall.ph';
- my $rc = syscall(&SYS_close, $fd + 0); # must force numeric
- die "can't sysclose $fd: $!" unless $rc == -1;
-
-Or, just use the fdopen(3S) feature of C<open()>:
-
- {
- open my $fh, "<&=$fd" or die "Cannot reopen fd=$fd: $!";
- close $fh;
- }
-
-=head2 Why can't I use "C:\temp\foo" in DOS paths? Why doesn't `C:\temp\foo.exe` work?
-X<filename, DOS issues>
-
-Whoops! You just put a tab and a formfeed into that filename!
-Remember that within double quoted strings ("like\this"), the
-backslash is an escape character. The full list of these is in
-L<perlop/Quote and Quote-like Operators>. Unsurprisingly, you don't
-have a file called "c:(tab)emp(formfeed)oo" or
-"c:(tab)emp(formfeed)oo.exe" on your legacy DOS filesystem.
-
-Either single-quote your strings, or (preferably) use forward slashes.
-Since all DOS and Windows versions since something like MS-DOS 2.0 or so
-have treated C</> and C<\> the same in a path, you might as well use the
-one that doesn't clash with Perl--or the POSIX shell, ANSI C and C++,
-awk, Tcl, Java, or Python, just to mention a few. POSIX paths
-are more portable, too.
-
-=head2 Why doesn't glob("*.*") get all the files?
-X<glob>
-
-Because even on non-Unix ports, Perl's glob function follows standard
-Unix globbing semantics. You'll need C<glob("*")> to get all (non-hidden)
-files. This makes glob() portable even to legacy systems. Your
-port may include proprietary globbing functions as well. Check its
-documentation for details.
-
-=head2 Why does Perl let me delete read-only files? Why does C<-i> clobber protected files? Isn't this a bug in Perl?
-
-This is elaborately and painstakingly described in the
-F<file-dir-perms> article in the "Far More Than You Ever Wanted To
-Know" collection in L<http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz> .
-
-The executive summary: learn how your filesystem works. The
-permissions on a file say what can happen to the data in that file.
-The permissions on a directory say what can happen to the list of
-files in that directory. If you delete a file, you're removing its
-name from the directory (so the operation depends on the permissions
-of the directory, not of the file). If you try to write to the file,
-the permissions of the file govern whether you're allowed to.
-
-=head2 How do I select a random line from a file?
-X<file, selecting a random line>
-
-Short of loading the file into a database or pre-indexing the lines in
-the file, there are a couple of things that you can do.
-
-Here's a reservoir-sampling algorithm from the Camel Book:
-
- srand;
- rand($.) < 1 && ($line = $_) while <>;
-
-This has a significant advantage in space over reading the whole file
-in. You can find a proof of this method in I<The Art of Computer
-Programming>, Volume 2, Section 3.4.2, by Donald E. Knuth.
-
-You can use the L<File::Random> module which provides a function
-for that algorithm:
-
- use File::Random qw/random_line/;
- my $line = random_line($filename);
-
-Another way is to use the L<Tie::File> module, which treats the entire
-file as an array. Simply access a random array element.
-
-=head2 Why do I get weird spaces when I print an array of lines?
-
-(contributed by brian d foy)
-
-If you are seeing spaces between the elements of your array when
-you print the array, you are probably interpolating the array in
-double quotes:
-
- my @animals = qw(camel llama alpaca vicuna);
- print "animals are: @animals\n";
-
-It's the double quotes, not the C<print>, doing this. Whenever you
-interpolate an array in a double quote context, Perl joins the
-elements with spaces (or whatever is in C<$">, which is a space by
-default):
-
- animals are: camel llama alpaca vicuna
-
-This is different than printing the array without the interpolation:
-
- my @animals = qw(camel llama alpaca vicuna);
- print "animals are: ", @animals, "\n";
-
-Now the output doesn't have the spaces between the elements because
-the elements of C<@animals> simply become part of the list to
-C<print>:
-
- animals are: camelllamaalpacavicuna
-
-You might notice this when each of the elements of C<@array> end with
-a newline. You expect to print one element per line, but notice that
-every line after the first is indented:
-
- this is a line
- this is another line
- this is the third line
-
-That extra space comes from the interpolation of the array. If you
-don't want to put anything between your array elements, don't use the
-array in double quotes. You can send it to print without them:
-
- print @lines;
-
-=head2 How do I traverse a directory tree?
-
-(contributed by brian d foy)
-
-The L<File::Find> module, which comes with Perl, does all of the hard
-work to traverse a directory structure. It comes with Perl. You simply
-call the C<find> subroutine with a callback subroutine and the
-directories you want to traverse:
-
- use File::Find;
-
- find( \&wanted, @directories );
-
- sub wanted {
- # full path in $File::Find::name
- # just filename in $_
- ... do whatever you want to do ...
- }
-
-The L<File::Find::Closures>, which you can download from CPAN, provides
-many ready-to-use subroutines that you can use with L<File::Find>.
-
-The L<File::Finder>, which you can download from CPAN, can help you
-create the callback subroutine using something closer to the syntax of
-the C<find> command-line utility:
-
- use File::Find;
- use File::Finder;
-
- my $deep_dirs = File::Finder->depth->type('d')->ls->exec('rmdir','{}');
-
- find( $deep_dirs->as_options, @places );
-
-The L<File::Find::Rule> module, which you can download from CPAN, has
-a similar interface, but does the traversal for you too:
-
- use File::Find::Rule;
-
- my @files = File::Find::Rule->file()
- ->name( '*.pm' )
- ->in( @INC );
-
-=head2 How do I delete a directory tree?
-
-(contributed by brian d foy)
-
-If you have an empty directory, you can use Perl's built-in C<rmdir>.
-If the directory is not empty (so, no files or subdirectories), you
-either have to empty it yourself (a lot of work) or use a module to
-help you.
-
-The L<File::Path> module, which comes with Perl, has a C<remove_tree>
-which can take care of all of the hard work for you:
-
- use File::Path qw(remove_tree);
-
- remove_tree( @directories );
-
-The L<File::Path> module also has a legacy interface to the older
-C<rmtree> subroutine.
-
-=head2 How do I copy an entire directory?
-
-(contributed by Shlomi Fish)
-
-To do the equivalent of C<cp -R> (i.e. copy an entire directory tree
-recursively) in portable Perl, you'll either need to write something yourself
-or find a good CPAN module such as L<File::Copy::Recursive>.
-
-=head1 AUTHOR AND COPYRIGHT
-
-Copyright (c) 1997-2010 Tom Christiansen, Nathan Torkington, and
-other authors as noted. All rights reserved.
-
-This documentation is free; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-Irrespective of its distribution, all code examples here are in the public
-domain. You are permitted and encouraged to use this code and any
-derivatives thereof in your own programs for fun or for profit as you
-see fit. A simple comment in the code giving credit to the FAQ would
-be courteous but is not required.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq6.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq6.pod
deleted file mode 100644
index 40c2b07c3dc..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlfaq6.pod
+++ /dev/null
@@ -1,1124 +0,0 @@
-=head1 NAME
-
-perlfaq6 - Regular Expressions
-
-=head1 DESCRIPTION
-
-This section is surprisingly small because the rest of the FAQ is
-littered with answers involving regular expressions. For example,
-decoding a URL and checking whether something is a number can be handled
-with regular expressions, but those answers are found elsewhere in
-this document (in L<perlfaq9>: "How do I decode or create those %-encodings
-on the web" and L<perlfaq4>: "How do I determine whether a scalar is
-a number/whole/integer/float", to be precise).
-
-=head2 How can I hope to use regular expressions without creating illegible and unmaintainable code?
-X<regex, legibility> X<regexp, legibility>
-X<regular expression, legibility> X</x>
-
-Three techniques can make regular expressions maintainable and
-understandable.
-
-=over 4
-
-=item Comments Outside the Regex
-
-Describe what you're doing and how you're doing it, using normal Perl
-comments.
-
- # turn the line into the first word, a colon, and the
- # number of characters on the rest of the line
- s/^(\w+)(.*)/ lc($1) . ":" . length($2) /meg;
-
-=item Comments Inside the Regex
-
-The C</x> modifier causes whitespace to be ignored in a regex pattern
-(except in a character class and a few other places), and also allows you to
-use normal comments there, too. As you can imagine, whitespace and comments
-help a lot.
-
-C</x> lets you turn this:
-
- s{<(?:[^>'"]*|".*?"|'.*?')+>}{}gs;
-
-into this:
-
- s{ < # opening angle bracket
- (?: # Non-backreffing grouping paren
- [^>'"] * # 0 or more things that are neither > nor ' nor "
- | # or else
- ".*?" # a section between double quotes (stingy match)
- | # or else
- '.*?' # a section between single quotes (stingy match)
- ) + # all occurring one or more times
- > # closing angle bracket
- }{}gsx; # replace with nothing, i.e. delete
-
-It's still not quite so clear as prose, but it is very useful for
-describing the meaning of each part of the pattern.
-
-=item Different Delimiters
-
-While we normally think of patterns as being delimited with C</>
-characters, they can be delimited by almost any character. L<perlre>
-describes this. For example, the C<s///> above uses braces as
-delimiters. Selecting another delimiter can avoid quoting the
-delimiter within the pattern:
-
- s/\/usr\/local/\/usr\/share/g; # bad delimiter choice
- s#/usr/local#/usr/share#g; # better
-
-Using logically paired delimiters can be even more readable:
-
- s{/usr/local/}{/usr/share}g; # better still
-
-=back
-
-=head2 I'm having trouble matching over more than one line. What's wrong?
-X<regex, multiline> X<regexp, multiline> X<regular expression, multiline>
-
-Either you don't have more than one line in the string you're looking
-at (probably), or else you aren't using the correct modifier(s) on
-your pattern (possibly).
-
-There are many ways to get multiline data into a string. If you want
-it to happen automatically while reading input, you'll want to set $/
-(probably to '' for paragraphs or C<undef> for the whole file) to
-allow you to read more than one line at a time.
-
-Read L<perlre> to help you decide which of C</s> and C</m> (or both)
-you might want to use: C</s> allows dot to include newline, and C</m>
-allows caret and dollar to match next to a newline, not just at the
-end of the string. You do need to make sure that you've actually
-got a multiline string in there.
-
-For example, this program detects duplicate words, even when they span
-line breaks (but not paragraph ones). For this example, we don't need
-C</s> because we aren't using dot in a regular expression that we want
-to cross line boundaries. Neither do we need C</m> because we don't
-want caret or dollar to match at any point inside the record next
-to newlines. But it's imperative that $/ be set to something other
-than the default, or else we won't actually ever have a multiline
-record read in.
-
- $/ = ''; # read in whole paragraph, not just one line
- while ( <> ) {
- while ( /\b([\w'-]+)(\s+\g1)+\b/gi ) { # word starts alpha
- print "Duplicate $1 at paragraph $.\n";
- }
- }
-
-Here's some code that finds sentences that begin with "From " (which would
-be mangled by many mailers):
-
- $/ = ''; # read in whole paragraph, not just one line
- while ( <> ) {
- while ( /^From /gm ) { # /m makes ^ match next to \n
- print "leading from in paragraph $.\n";
- }
- }
-
-Here's code that finds everything between START and END in a paragraph:
-
- undef $/; # read in whole file, not just one line or paragraph
- while ( <> ) {
- while ( /START(.*?)END/sgm ) { # /s makes . cross line boundaries
- print "$1\n";
- }
- }
-
-=head2 How can I pull out lines between two patterns that are themselves on different lines?
-X<..>
-
-You can use Perl's somewhat exotic C<..> operator (documented in
-L<perlop>):
-
- perl -ne 'print if /START/ .. /END/' file1 file2 ...
-
-If you wanted text and not lines, you would use
-
- perl -0777 -ne 'print "$1\n" while /START(.*?)END/gs' file1 file2 ...
-
-But if you want nested occurrences of C<START> through C<END>, you'll
-run up against the problem described in the question in this section
-on matching balanced text.
-
-Here's another example of using C<..>:
-
- while (<>) {
- my $in_header = 1 .. /^$/;
- my $in_body = /^$/ .. eof;
- # now choose between them
- } continue {
- $. = 0 if eof; # fix $.
- }
-
-=head2 How do I match XML, HTML, or other nasty, ugly things with a regex?
-X<regex, XML> X<regex, HTML> X<XML> X<HTML> X<pain> X<frustration>
-X<sucking out, will to live>
-
-Do not use regexes. Use a module and forget about the
-regular expressions. The L<XML::LibXML>, L<HTML::TokeParser> and
-L<HTML::TreeBuilder> modules are good starts, although each namespace
-has other parsing modules specialized for certain tasks and different
-ways of doing it. Start at CPAN Search ( L<http://metacpan.org/> )
-and wonder at all the work people have done for you already! :)
-
-=head2 I put a regular expression into $/ but it didn't work. What's wrong?
-X<$/, regexes in> X<$INPUT_RECORD_SEPARATOR, regexes in>
-X<$RS, regexes in>
-
-$/ has to be a string. You can use these examples if you really need to
-do this.
-
-If you have L<File::Stream>, this is easy.
-
- use File::Stream;
-
- my $stream = File::Stream->new(
- $filehandle,
- separator => qr/\s*,\s*/,
- );
-
- print "$_\n" while <$stream>;
-
-If you don't have File::Stream, you have to do a little more work.
-
-You can use the four-argument form of sysread to continually add to
-a buffer. After you add to the buffer, you check if you have a
-complete line (using your regular expression).
-
- local $_ = "";
- while( sysread FH, $_, 8192, length ) {
- while( s/^((?s).*?)your_pattern// ) {
- my $record = $1;
- # do stuff here.
- }
- }
-
-You can do the same thing with foreach and a match using the
-c flag and the \G anchor, if you do not mind your entire file
-being in memory at the end.
-
- local $_ = "";
- while( sysread FH, $_, 8192, length ) {
- foreach my $record ( m/\G((?s).*?)your_pattern/gc ) {
- # do stuff here.
- }
- substr( $_, 0, pos ) = "" if pos;
- }
-
-
-=head2 How do I substitute case-insensitively on the LHS while preserving case on the RHS?
-X<replace, case preserving> X<substitute, case preserving>
-X<substitution, case preserving> X<s, case preserving>
-
-Here's a lovely Perlish solution by Larry Rosler. It exploits
-properties of bitwise xor on ASCII strings.
-
- $_= "this is a TEsT case";
-
- $old = 'test';
- $new = 'success';
-
- s{(\Q$old\E)}
- { uc $new | (uc $1 ^ $1) .
- (uc(substr $1, -1) ^ substr $1, -1) x
- (length($new) - length $1)
- }egi;
-
- print;
-
-And here it is as a subroutine, modeled after the above:
-
- sub preserve_case($$) {
- my ($old, $new) = @_;
- my $mask = uc $old ^ $old;
-
- uc $new | $mask .
- substr($mask, -1) x (length($new) - length($old))
- }
-
- $string = "this is a TEsT case";
- $string =~ s/(test)/preserve_case($1, "success")/egi;
- print "$string\n";
-
-This prints:
-
- this is a SUcCESS case
-
-As an alternative, to keep the case of the replacement word if it is
-longer than the original, you can use this code, by Jeff Pinyan:
-
- sub preserve_case {
- my ($from, $to) = @_;
- my ($lf, $lt) = map length, @_;
-
- if ($lt < $lf) { $from = substr $from, 0, $lt }
- else { $from .= substr $to, $lf }
-
- return uc $to | ($from ^ uc $from);
- }
-
-This changes the sentence to "this is a SUcCess case."
-
-Just to show that C programmers can write C in any programming language,
-if you prefer a more C-like solution, the following script makes the
-substitution have the same case, letter by letter, as the original.
-(It also happens to run about 240% slower than the Perlish solution runs.)
-If the substitution has more characters than the string being substituted,
-the case of the last character is used for the rest of the substitution.
-
- # Original by Nathan Torkington, massaged by Jeffrey Friedl
- #
- sub preserve_case($$)
- {
- my ($old, $new) = @_;
- my $state = 0; # 0 = no change; 1 = lc; 2 = uc
- my ($i, $oldlen, $newlen, $c) = (0, length($old), length($new));
- my $len = $oldlen < $newlen ? $oldlen : $newlen;
-
- for ($i = 0; $i < $len; $i++) {
- if ($c = substr($old, $i, 1), $c =~ /[\W\d_]/) {
- $state = 0;
- } elsif (lc $c eq $c) {
- substr($new, $i, 1) = lc(substr($new, $i, 1));
- $state = 1;
- } else {
- substr($new, $i, 1) = uc(substr($new, $i, 1));
- $state = 2;
- }
- }
- # finish up with any remaining new (for when new is longer than old)
- if ($newlen > $oldlen) {
- if ($state == 1) {
- substr($new, $oldlen) = lc(substr($new, $oldlen));
- } elsif ($state == 2) {
- substr($new, $oldlen) = uc(substr($new, $oldlen));
- }
- }
- return $new;
- }
-
-=head2 How can I make C<\w> match national character sets?
-X<\w>
-
-Put C<use locale;> in your script. The \w character class is taken
-from the current locale.
-
-See L<perllocale> for details.
-
-=head2 How can I match a locale-smart version of C</[a-zA-Z]/>?
-X<alpha>
-
-You can use the POSIX character class syntax C</[[:alpha:]]/>
-documented in L<perlre>.
-
-No matter which locale you are in, the alphabetic characters are
-the characters in \w without the digits and the underscore.
-As a regex, that looks like C</[^\W\d_]/>. Its complement,
-the non-alphabetics, is then everything in \W along with
-the digits and the underscore, or C</[\W\d_]/>.
-
-=head2 How can I quote a variable to use in a regex?
-X<regex, escaping> X<regexp, escaping> X<regular expression, escaping>
-
-The Perl parser will expand $variable and @variable references in
-regular expressions unless the delimiter is a single quote. Remember,
-too, that the right-hand side of a C<s///> substitution is considered
-a double-quoted string (see L<perlop> for more details). Remember
-also that any regex special characters will be acted on unless you
-precede the substitution with \Q. Here's an example:
-
- $string = "Placido P. Octopus";
- $regex = "P.";
-
- $string =~ s/$regex/Polyp/;
- # $string is now "Polypacido P. Octopus"
-
-Because C<.> is special in regular expressions, and can match any
-single character, the regex C<P.> here has matched the <Pl> in the
-original string.
-
-To escape the special meaning of C<.>, we use C<\Q>:
-
- $string = "Placido P. Octopus";
- $regex = "P.";
-
- $string =~ s/\Q$regex/Polyp/;
- # $string is now "Placido Polyp Octopus"
-
-The use of C<\Q> causes the <.> in the regex to be treated as a
-regular character, so that C<P.> matches a C<P> followed by a dot.
-
-=head2 What is C</o> really for?
-X</o, regular expressions> X<compile, regular expressions>
-
-(contributed by brian d foy)
-
-The C</o> option for regular expressions (documented in L<perlop> and
-L<perlreref>) tells Perl to compile the regular expression only once.
-This is only useful when the pattern contains a variable. Perls 5.6
-and later handle this automatically if the pattern does not change.
-
-Since the match operator C<m//>, the substitution operator C<s///>,
-and the regular expression quoting operator C<qr//> are double-quotish
-constructs, you can interpolate variables into the pattern. See the
-answer to "How can I quote a variable to use in a regex?" for more
-details.
-
-This example takes a regular expression from the argument list and
-prints the lines of input that match it:
-
- my $pattern = shift @ARGV;
-
- while( <> ) {
- print if m/$pattern/;
- }
-
-Versions of Perl prior to 5.6 would recompile the regular expression
-for each iteration, even if C<$pattern> had not changed. The C</o>
-would prevent this by telling Perl to compile the pattern the first
-time, then reuse that for subsequent iterations:
-
- my $pattern = shift @ARGV;
-
- while( <> ) {
- print if m/$pattern/o; # useful for Perl < 5.6
- }
-
-In versions 5.6 and later, Perl won't recompile the regular expression
-if the variable hasn't changed, so you probably don't need the C</o>
-option. It doesn't hurt, but it doesn't help either. If you want any
-version of Perl to compile the regular expression only once even if
-the variable changes (thus, only using its initial value), you still
-need the C</o>.
-
-You can watch Perl's regular expression engine at work to verify for
-yourself if Perl is recompiling a regular expression. The C<use re
-'debug'> pragma (comes with Perl 5.005 and later) shows the details.
-With Perls before 5.6, you should see C<re> reporting that its
-compiling the regular expression on each iteration. With Perl 5.6 or
-later, you should only see C<re> report that for the first iteration.
-
- use re 'debug';
-
- my $regex = 'Perl';
- foreach ( qw(Perl Java Ruby Python) ) {
- print STDERR "-" x 73, "\n";
- print STDERR "Trying $_...\n";
- print STDERR "\t$_ is good!\n" if m/$regex/;
- }
-
-=head2 How do I use a regular expression to strip C-style comments from a file?
-
-While this actually can be done, it's much harder than you'd think.
-For example, this one-liner
-
- perl -0777 -pe 's{/\*.*?\*/}{}gs' foo.c
-
-will work in many but not all cases. You see, it's too simple-minded for
-certain kinds of C programs, in particular, those with what appear to be
-comments in quoted strings. For that, you'd need something like this,
-created by Jeffrey Friedl and later modified by Fred Curtis.
-
- $/ = undef;
- $_ = <>;
- s#/\*[^*]*\*+([^/*][^*]*\*+)*/|("(\\.|[^"\\])*"|'(\\.|[^'\\])*'|.[^/"'\\]*)#defined $2 ? $2 : ""#gse;
- print;
-
-This could, of course, be more legibly written with the C</x> modifier, adding
-whitespace and comments. Here it is expanded, courtesy of Fred Curtis.
-
- s{
- /\* ## Start of /* ... */ comment
- [^*]*\*+ ## Non-* followed by 1-or-more *'s
- (
- [^/*][^*]*\*+
- )* ## 0-or-more things which don't start with /
- ## but do end with '*'
- / ## End of /* ... */ comment
-
- | ## OR various things which aren't comments:
-
- (
- " ## Start of " ... " string
- (
- \\. ## Escaped char
- | ## OR
- [^"\\] ## Non "\
- )*
- " ## End of " ... " string
-
- | ## OR
-
- ' ## Start of ' ... ' string
- (
- \\. ## Escaped char
- | ## OR
- [^'\\] ## Non '\
- )*
- ' ## End of ' ... ' string
-
- | ## OR
-
- . ## Anything other char
- [^/"'\\]* ## Chars which doesn't start a comment, string or escape
- )
- }{defined $2 ? $2 : ""}gxse;
-
-A slight modification also removes C++ comments, possibly spanning multiple lines
-using a continuation character:
-
- s#/\*[^*]*\*+([^/*][^*]*\*+)*/|//([^\\]|[^\n][\n]?)*?\n|("(\\.|[^"\\])*"|'(\\.|[^'\\])*'|.[^/"'\\]*)#defined $3 ? $3 : ""#gse;
-
-=head2 Can I use Perl regular expressions to match balanced text?
-X<regex, matching balanced test> X<regexp, matching balanced test>
-X<regular expression, matching balanced test> X<possessive> X<PARNO>
-X<Text::Balanced> X<Regexp::Common> X<backtracking> X<recursion>
-
-(contributed by brian d foy)
-
-Your first try should probably be the L<Text::Balanced> module, which
-is in the Perl standard library since Perl 5.8. It has a variety of
-functions to deal with tricky text. The L<Regexp::Common> module can
-also help by providing canned patterns you can use.
-
-As of Perl 5.10, you can match balanced text with regular expressions
-using recursive patterns. Before Perl 5.10, you had to resort to
-various tricks such as using Perl code in C<(??{})> sequences.
-
-Here's an example using a recursive regular expression. The goal is to
-capture all of the text within angle brackets, including the text in
-nested angle brackets. This sample text has two "major" groups: a
-group with one level of nesting and a group with two levels of
-nesting. There are five total groups in angle brackets:
-
- I have some <brackets in <nested brackets> > and
- <another group <nested once <nested twice> > >
- and that's it.
-
-The regular expression to match the balanced text uses two new (to
-Perl 5.10) regular expression features. These are covered in L<perlre>
-and this example is a modified version of one in that documentation.
-
-First, adding the new possessive C<+> to any quantifier finds the
-longest match and does not backtrack. That's important since you want
-to handle any angle brackets through the recursion, not backtracking.
-The group C<< [^<>]++ >> finds one or more non-angle brackets without
-backtracking.
-
-Second, the new C<(?PARNO)> refers to the sub-pattern in the
-particular capture group given by C<PARNO>. In the following regex,
-the first capture group finds (and remembers) the balanced text, and
-you need that same pattern within the first buffer to get past the
-nested text. That's the recursive part. The C<(?1)> uses the pattern
-in the outer capture group as an independent part of the regex.
-
-Putting it all together, you have:
-
- #!/usr/local/bin/perl5.10.0
-
- my $string =<<"HERE";
- I have some <brackets in <nested brackets> > and
- <another group <nested once <nested twice> > >
- and that's it.
- HERE
-
- my @groups = $string =~ m/
- ( # start of capture group 1
- < # match an opening angle bracket
- (?:
- [^<>]++ # one or more non angle brackets, non backtracking
- |
- (?1) # found < or >, so recurse to capture group 1
- )*
- > # match a closing angle bracket
- ) # end of capture group 1
- /xg;
-
- $" = "\n\t";
- print "Found:\n\t@groups\n";
-
-The output shows that Perl found the two major groups:
-
- Found:
- <brackets in <nested brackets> >
- <another group <nested once <nested twice> > >
-
-With a little extra work, you can get the all of the groups in angle
-brackets even if they are in other angle brackets too. Each time you
-get a balanced match, remove its outer delimiter (that's the one you
-just matched so don't match it again) and add it to a queue of strings
-to process. Keep doing that until you get no matches:
-
- #!/usr/local/bin/perl5.10.0
-
- my @queue =<<"HERE";
- I have some <brackets in <nested brackets> > and
- <another group <nested once <nested twice> > >
- and that's it.
- HERE
-
- my $regex = qr/
- ( # start of bracket 1
- < # match an opening angle bracket
- (?:
- [^<>]++ # one or more non angle brackets, non backtracking
- |
- (?1) # recurse to bracket 1
- )*
- > # match a closing angle bracket
- ) # end of bracket 1
- /x;
-
- $" = "\n\t";
-
- while( @queue ) {
- my $string = shift @queue;
-
- my @groups = $string =~ m/$regex/g;
- print "Found:\n\t@groups\n\n" if @groups;
-
- unshift @queue, map { s/^<//; s/>$//; $_ } @groups;
- }
-
-The output shows all of the groups. The outermost matches show up
-first and the nested matches so up later:
-
- Found:
- <brackets in <nested brackets> >
- <another group <nested once <nested twice> > >
-
- Found:
- <nested brackets>
-
- Found:
- <nested once <nested twice> >
-
- Found:
- <nested twice>
-
-=head2 What does it mean that regexes are greedy? How can I get around it?
-X<greedy> X<greediness>
-
-Most people mean that greedy regexes match as much as they can.
-Technically speaking, it's actually the quantifiers (C<?>, C<*>, C<+>,
-C<{}>) that are greedy rather than the whole pattern; Perl prefers local
-greed and immediate gratification to overall greed. To get non-greedy
-versions of the same quantifiers, use (C<??>, C<*?>, C<+?>, C<{}?>).
-
-An example:
-
- my $s1 = my $s2 = "I am very very cold";
- $s1 =~ s/ve.*y //; # I am cold
- $s2 =~ s/ve.*?y //; # I am very cold
-
-Notice how the second substitution stopped matching as soon as it
-encountered "y ". The C<*?> quantifier effectively tells the regular
-expression engine to find a match as quickly as possible and pass
-control on to whatever is next in line, as you would if you were
-playing hot potato.
-
-=head2 How do I process each word on each line?
-X<word>
-
-Use the split function:
-
- while (<>) {
- foreach my $word ( split ) {
- # do something with $word here
- }
- }
-
-Note that this isn't really a word in the English sense; it's just
-chunks of consecutive non-whitespace characters.
-
-To work with only alphanumeric sequences (including underscores), you
-might consider
-
- while (<>) {
- foreach $word (m/(\w+)/g) {
- # do something with $word here
- }
- }
-
-=head2 How can I print out a word-frequency or line-frequency summary?
-
-To do this, you have to parse out each word in the input stream. We'll
-pretend that by word you mean chunk of alphabetics, hyphens, or
-apostrophes, rather than the non-whitespace chunk idea of a word given
-in the previous question:
-
- my (%seen);
- while (<>) {
- while ( /(\b[^\W_\d][\w'-]+\b)/g ) { # misses "`sheep'"
- $seen{$1}++;
- }
- }
-
- while ( my ($word, $count) = each %seen ) {
- print "$count $word\n";
- }
-
-If you wanted to do the same thing for lines, you wouldn't need a
-regular expression:
-
- my (%seen);
-
- while (<>) {
- $seen{$_}++;
- }
-
- while ( my ($line, $count) = each %seen ) {
- print "$count $line";
- }
-
-If you want these output in a sorted order, see L<perlfaq4>: "How do I
-sort a hash (optionally by value instead of key)?".
-
-=head2 How can I do approximate matching?
-X<match, approximate> X<matching, approximate>
-
-See the module L<String::Approx> available from CPAN.
-
-=head2 How do I efficiently match many regular expressions at once?
-X<regex, efficiency> X<regexp, efficiency>
-X<regular expression, efficiency>
-
-(contributed by brian d foy)
-
-If you have Perl 5.10 or later, this is almost trivial. You just smart
-match against an array of regular expression objects:
-
- my @patterns = ( qr/Fr.d/, qr/B.rn.y/, qr/W.lm./ );
-
- if( $string ~~ @patterns ) {
- ...
- };
-
-The smart match stops when it finds a match, so it doesn't have to try
-every expression.
-
-Earlier than Perl 5.10, you have a bit of work to do. You want to
-avoid compiling a regular expression every time you want to match it.
-In this example, perl must recompile the regular expression for every
-iteration of the C<foreach> loop since it has no way to know what
-C<$pattern> will be:
-
- my @patterns = qw( foo bar baz );
-
- LINE: while( <DATA> ) {
- foreach $pattern ( @patterns ) {
- if( /\b$pattern\b/i ) {
- print;
- next LINE;
- }
- }
- }
-
-The C<qr//> operator showed up in perl 5.005. It compiles a regular
-expression, but doesn't apply it. When you use the pre-compiled
-version of the regex, perl does less work. In this example, I inserted
-a C<map> to turn each pattern into its pre-compiled form. The rest of
-the script is the same, but faster:
-
- my @patterns = map { qr/\b$_\b/i } qw( foo bar baz );
-
- LINE: while( <> ) {
- foreach $pattern ( @patterns ) {
- if( /$pattern/ ) {
- print;
- next LINE;
- }
- }
- }
-
-In some cases, you may be able to make several patterns into a single
-regular expression. Beware of situations that require backtracking
-though.
-
- my $regex = join '|', qw( foo bar baz );
-
- LINE: while( <> ) {
- print if /\b(?:$regex)\b/i;
- }
-
-For more details on regular expression efficiency, see I<Mastering
-Regular Expressions> by Jeffrey Friedl. He explains how the regular
-expressions engine works and why some patterns are surprisingly
-inefficient. Once you understand how perl applies regular expressions,
-you can tune them for individual situations.
-
-=head2 Why don't word-boundary searches with C<\b> work for me?
-X<\b>
-
-(contributed by brian d foy)
-
-Ensure that you know what \b really does: it's the boundary between a
-word character, \w, and something that isn't a word character. That
-thing that isn't a word character might be \W, but it can also be the
-start or end of the string.
-
-It's not (not!) the boundary between whitespace and non-whitespace,
-and it's not the stuff between words we use to create sentences.
-
-In regex speak, a word boundary (\b) is a "zero width assertion",
-meaning that it doesn't represent a character in the string, but a
-condition at a certain position.
-
-For the regular expression, /\bPerl\b/, there has to be a word
-boundary before the "P" and after the "l". As long as something other
-than a word character precedes the "P" and succeeds the "l", the
-pattern will match. These strings match /\bPerl\b/.
-
- "Perl" # no word char before P or after l
- "Perl " # same as previous (space is not a word char)
- "'Perl'" # the ' char is not a word char
- "Perl's" # no word char before P, non-word char after "l"
-
-These strings do not match /\bPerl\b/.
-
- "Perl_" # _ is a word char!
- "Perler" # no word char before P, but one after l
-
-You don't have to use \b to match words though. You can look for
-non-word characters surrounded by word characters. These strings
-match the pattern /\b'\b/.
-
- "don't" # the ' char is surrounded by "n" and "t"
- "qep'a'" # the ' char is surrounded by "p" and "a"
-
-These strings do not match /\b'\b/.
-
- "foo'" # there is no word char after non-word '
-
-You can also use the complement of \b, \B, to specify that there
-should not be a word boundary.
-
-In the pattern /\Bam\B/, there must be a word character before the "a"
-and after the "m". These patterns match /\Bam\B/:
-
- "llama" # "am" surrounded by word chars
- "Samuel" # same
-
-These strings do not match /\Bam\B/
-
- "Sam" # no word boundary before "a", but one after "m"
- "I am Sam" # "am" surrounded by non-word chars
-
-
-=head2 Why does using $&, $`, or $' slow my program down?
-X<$MATCH> X<$&> X<$POSTMATCH> X<$'> X<$PREMATCH> X<$`>
-
-(contributed by Anno Siegel)
-
-Once Perl sees that you need one of these variables anywhere in the
-program, it provides them on each and every pattern match. That means
-that on every pattern match the entire string will be copied, part of it
-to $`, part to $&, and part to $'. Thus the penalty is most severe with
-long strings and patterns that match often. Avoid $&, $', and $` if you
-can, but if you can't, once you've used them at all, use them at will
-because you've already paid the price. Remember that some algorithms
-really appreciate them. As of the 5.005 release, the $& variable is no
-longer "expensive" the way the other two are.
-
-Since Perl 5.6.1 the special variables @- and @+ can functionally replace
-$`, $& and $'. These arrays contain pointers to the beginning and end
-of each match (see perlvar for the full story), so they give you
-essentially the same information, but without the risk of excessive
-string copying.
-
-Perl 5.10 added three specials, C<${^MATCH}>, C<${^PREMATCH}>, and
-C<${^POSTMATCH}> to do the same job but without the global performance
-penalty. Perl 5.10 only sets these variables if you compile or execute the
-regular expression with the C</p> modifier.
-
-=head2 What good is C<\G> in a regular expression?
-X<\G>
-
-You use the C<\G> anchor to start the next match on the same
-string where the last match left off. The regular
-expression engine cannot skip over any characters to find
-the next match with this anchor, so C<\G> is similar to the
-beginning of string anchor, C<^>. The C<\G> anchor is typically
-used with the C<g> flag. It uses the value of C<pos()>
-as the position to start the next match. As the match
-operator makes successive matches, it updates C<pos()> with the
-position of the next character past the last match (or the
-first character of the next match, depending on how you like
-to look at it). Each string has its own C<pos()> value.
-
-Suppose you want to match all of consecutive pairs of digits
-in a string like "1122a44" and stop matching when you
-encounter non-digits. You want to match C<11> and C<22> but
-the letter <a> shows up between C<22> and C<44> and you want
-to stop at C<a>. Simply matching pairs of digits skips over
-the C<a> and still matches C<44>.
-
- $_ = "1122a44";
- my @pairs = m/(\d\d)/g; # qw( 11 22 44 )
-
-If you use the C<\G> anchor, you force the match after C<22> to
-start with the C<a>. The regular expression cannot match
-there since it does not find a digit, so the next match
-fails and the match operator returns the pairs it already
-found.
-
- $_ = "1122a44";
- my @pairs = m/\G(\d\d)/g; # qw( 11 22 )
-
-You can also use the C<\G> anchor in scalar context. You
-still need the C<g> flag.
-
- $_ = "1122a44";
- while( m/\G(\d\d)/g ) {
- print "Found $1\n";
- }
-
-After the match fails at the letter C<a>, perl resets C<pos()>
-and the next match on the same string starts at the beginning.
-
- $_ = "1122a44";
- while( m/\G(\d\d)/g ) {
- print "Found $1\n";
- }
-
- print "Found $1 after while" if m/(\d\d)/g; # finds "11"
-
-You can disable C<pos()> resets on fail with the C<c> flag, documented
-in L<perlop> and L<perlreref>. Subsequent matches start where the last
-successful match ended (the value of C<pos()>) even if a match on the
-same string has failed in the meantime. In this case, the match after
-the C<while()> loop starts at the C<a> (where the last match stopped),
-and since it does not use any anchor it can skip over the C<a> to find
-C<44>.
-
- $_ = "1122a44";
- while( m/\G(\d\d)/gc ) {
- print "Found $1\n";
- }
-
- print "Found $1 after while" if m/(\d\d)/g; # finds "44"
-
-Typically you use the C<\G> anchor with the C<c> flag
-when you want to try a different match if one fails,
-such as in a tokenizer. Jeffrey Friedl offers this example
-which works in 5.004 or later.
-
- while (<>) {
- chomp;
- PARSER: {
- m/ \G( \d+\b )/gcx && do { print "number: $1\n"; redo; };
- m/ \G( \w+ )/gcx && do { print "word: $1\n"; redo; };
- m/ \G( \s+ )/gcx && do { print "space: $1\n"; redo; };
- m/ \G( [^\w\d]+ )/gcx && do { print "other: $1\n"; redo; };
- }
- }
-
-For each line, the C<PARSER> loop first tries to match a series
-of digits followed by a word boundary. This match has to
-start at the place the last match left off (or the beginning
-of the string on the first match). Since C<m/ \G( \d+\b
-)/gcx> uses the C<c> flag, if the string does not match that
-regular expression, perl does not reset pos() and the next
-match starts at the same position to try a different
-pattern.
-
-=head2 Are Perl regexes DFAs or NFAs? Are they POSIX compliant?
-X<DFA> X<NFA> X<POSIX>
-
-While it's true that Perl's regular expressions resemble the DFAs
-(deterministic finite automata) of the egrep(1) program, they are in
-fact implemented as NFAs (non-deterministic finite automata) to allow
-backtracking and backreferencing. And they aren't POSIX-style either,
-because those guarantee worst-case behavior for all cases. (It seems
-that some people prefer guarantees of consistency, even when what's
-guaranteed is slowness.) See the book "Mastering Regular Expressions"
-(from O'Reilly) by Jeffrey Friedl for all the details you could ever
-hope to know on these matters (a full citation appears in
-L<perlfaq2>).
-
-=head2 What's wrong with using grep in a void context?
-X<grep>
-
-The problem is that grep builds a return list, regardless of the context.
-This means you're making Perl go to the trouble of building a list that
-you then just throw away. If the list is large, you waste both time and space.
-If your intent is to iterate over the list, then use a for loop for this
-purpose.
-
-In perls older than 5.8.1, map suffers from this problem as well.
-But since 5.8.1, this has been fixed, and map is context aware - in void
-context, no lists are constructed.
-
-=head2 How can I match strings with multibyte characters?
-X<regex, and multibyte characters> X<regexp, and multibyte characters>
-X<regular expression, and multibyte characters> X<martian> X<encoding, Martian>
-
-Starting from Perl 5.6 Perl has had some level of multibyte character
-support. Perl 5.8 or later is recommended. Supported multibyte
-character repertoires include Unicode, and legacy encodings
-through the Encode module. See L<perluniintro>, L<perlunicode>,
-and L<Encode>.
-
-If you are stuck with older Perls, you can do Unicode with the
-L<Unicode::String> module, and character conversions using the
-L<Unicode::Map8> and L<Unicode::Map> modules. If you are using
-Japanese encodings, you might try using the jperl 5.005_03.
-
-Finally, the following set of approaches was offered by Jeffrey
-Friedl, whose article in issue #5 of The Perl Journal talks about
-this very matter.
-
-Let's suppose you have some weird Martian encoding where pairs of
-ASCII uppercase letters encode single Martian letters (i.e. the two
-bytes "CV" make a single Martian letter, as do the two bytes "SG",
-"VS", "XX", etc.). Other bytes represent single characters, just like
-ASCII.
-
-So, the string of Martian "I am CVSGXX!" uses 12 bytes to encode the
-nine characters 'I', ' ', 'a', 'm', ' ', 'CV', 'SG', 'XX', '!'.
-
-Now, say you want to search for the single character C</GX/>. Perl
-doesn't know about Martian, so it'll find the two bytes "GX" in the "I
-am CVSGXX!" string, even though that character isn't there: it just
-looks like it is because "SG" is next to "XX", but there's no real
-"GX". This is a big problem.
-
-Here are a few ways, all painful, to deal with it:
-
- # Make sure adjacent "martian" bytes are no longer adjacent.
- $martian =~ s/([A-Z][A-Z])/ $1 /g;
-
- print "found GX!\n" if $martian =~ /GX/;
-
-Or like this:
-
- my @chars = $martian =~ m/([A-Z][A-Z]|[^A-Z])/g;
- # above is conceptually similar to: my @chars = $text =~ m/(.)/g;
- #
- foreach my $char (@chars) {
- print "found GX!\n", last if $char eq 'GX';
- }
-
-Or like this:
-
- while ($martian =~ m/\G([A-Z][A-Z]|.)/gs) { # \G probably unneeded
- if ($1 eq 'GX') {
- print "found GX!\n";
- last;
- }
- }
-
-Here's another, slightly less painful, way to do it from Benjamin
-Goldberg, who uses a zero-width negative look-behind assertion.
-
- print "found GX!\n" if $martian =~ m/
- (?<![A-Z])
- (?:[A-Z][A-Z])*?
- GX
- /x;
-
-This succeeds if the "martian" character GX is in the string, and fails
-otherwise. If you don't like using (?<!), a zero-width negative
-look-behind assertion, you can replace (?<![A-Z]) with (?:^|[^A-Z]).
-
-It does have the drawback of putting the wrong thing in $-[0] and $+[0],
-but this usually can be worked around.
-
-=head2 How do I match a regular expression that's in a variable?
-X<regex, in variable> X<eval> X<regex> X<quotemeta> X<\Q, regex>
-X<\E, regex> X<qr//>
-
-(contributed by brian d foy)
-
-We don't have to hard-code patterns into the match operator (or
-anything else that works with regular expressions). We can put the
-pattern in a variable for later use.
-
-The match operator is a double quote context, so you can interpolate
-your variable just like a double quoted string. In this case, you
-read the regular expression as user input and store it in C<$regex>.
-Once you have the pattern in C<$regex>, you use that variable in the
-match operator.
-
- chomp( my $regex = <STDIN> );
-
- if( $string =~ m/$regex/ ) { ... }
-
-Any regular expression special characters in C<$regex> are still
-special, and the pattern still has to be valid or Perl will complain.
-For instance, in this pattern there is an unpaired parenthesis.
-
- my $regex = "Unmatched ( paren";
-
- "Two parens to bind them all" =~ m/$regex/;
-
-When Perl compiles the regular expression, it treats the parenthesis
-as the start of a memory match. When it doesn't find the closing
-parenthesis, it complains:
-
- Unmatched ( in regex; marked by <-- HERE in m/Unmatched ( <-- HERE paren/ at script line 3.
-
-You can get around this in several ways depending on our situation.
-First, if you don't want any of the characters in the string to be
-special, you can escape them with C<quotemeta> before you use the string.
-
- chomp( my $regex = <STDIN> );
- $regex = quotemeta( $regex );
-
- if( $string =~ m/$regex/ ) { ... }
-
-You can also do this directly in the match operator using the C<\Q>
-and C<\E> sequences. The C<\Q> tells Perl where to start escaping
-special characters, and the C<\E> tells it where to stop (see L<perlop>
-for more details).
-
- chomp( my $regex = <STDIN> );
-
- if( $string =~ m/\Q$regex\E/ ) { ... }
-
-Alternately, you can use C<qr//>, the regular expression quote operator (see
-L<perlop> for more details). It quotes and perhaps compiles the pattern,
-and you can apply regular expression flags to the pattern.
-
- chomp( my $input = <STDIN> );
-
- my $regex = qr/$input/is;
-
- $string =~ m/$regex/ # same as m/$input/is;
-
-You might also want to trap any errors by wrapping an C<eval> block
-around the whole thing.
-
- chomp( my $input = <STDIN> );
-
- eval {
- if( $string =~ m/\Q$input\E/ ) { ... }
- };
- warn $@ if $@;
-
-Or...
-
- my $regex = eval { qr/$input/is };
- if( defined $regex ) {
- $string =~ m/$regex/;
- }
- else {
- warn $@;
- }
-
-=head1 AUTHOR AND COPYRIGHT
-
-Copyright (c) 1997-2010 Tom Christiansen, Nathan Torkington, and
-other authors as noted. All rights reserved.
-
-This documentation is free; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-Irrespective of its distribution, all code examples in this file
-are hereby placed into the public domain. You are permitted and
-encouraged to use this code in your own programs for fun
-or for profit as you see fit. A simple comment in the code giving
-credit would be courteous but is not required.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq7.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq7.pod
deleted file mode 100644
index 35c9330f2dc..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlfaq7.pod
+++ /dev/null
@@ -1,1061 +0,0 @@
-=head1 NAME
-
-perlfaq7 - General Perl Language Issues
-
-=head1 DESCRIPTION
-
-This section deals with general Perl language issues that don't
-clearly fit into any of the other sections.
-
-=head2 Can I get a BNF/yacc/RE for the Perl language?
-
-There is no BNF, but you can paw your way through the yacc grammar in
-perly.y in the source distribution if you're particularly brave. The
-grammar relies on very smart tokenizing code, so be prepared to
-venture into toke.c as well.
-
-In the words of Chaim Frenkel: "Perl's grammar can not be reduced to BNF.
-The work of parsing perl is distributed between yacc, the lexer, smoke
-and mirrors."
-
-=head2 What are all these $@%&* punctuation signs, and how do I know when to use them?
-
-They are type specifiers, as detailed in L<perldata>:
-
- $ for scalar values (number, string or reference)
- @ for arrays
- % for hashes (associative arrays)
- & for subroutines (aka functions, procedures, methods)
- * for all types of that symbol name. In version 4 you used them like
- pointers, but in modern perls you can just use references.
-
-There are a couple of other symbols that
-you're likely to encounter that aren't
-really type specifiers:
-
- <> are used for inputting a record from a filehandle.
- \ takes a reference to something.
-
-Note that <FILE> is I<neither> the type specifier for files
-nor the name of the handle. It is the C<< <> >> operator applied
-to the handle FILE. It reads one line (well, record--see
-L<perlvar/$E<sol>>) from the handle FILE in scalar context, or I<all> lines
-in list context. When performing open, close, or any other operation
-besides C<< <> >> on files, or even when talking about the handle, do
-I<not> use the brackets. These are correct: C<eof(FH)>, C<seek(FH, 0,
-2)> and "copying from STDIN to FILE".
-
-=head2 Do I always/never have to quote my strings or use semicolons and commas?
-
-Normally, a bareword doesn't need to be quoted, but in most cases
-probably should be (and must be under C<use strict>). But a hash key
-consisting of a simple word and the left-hand
-operand to the C<< => >> operator both
-count as though they were quoted:
-
- This is like this
- ------------ ---------------
- $foo{line} $foo{'line'}
- bar => stuff 'bar' => stuff
-
-The final semicolon in a block is optional, as is the final comma in a
-list. Good style (see L<perlstyle>) says to put them in except for
-one-liners:
-
- if ($whoops) { exit 1 }
- my @nums = (1, 2, 3);
-
- if ($whoops) {
- exit 1;
- }
-
- my @lines = (
- "There Beren came from mountains cold",
- "And lost he wandered under leaves",
- );
-
-=head2 How do I skip some return values?
-
-One way is to treat the return values as a list and index into it:
-
- $dir = (getpwnam($user))[7];
-
-Another way is to use undef as an element on the left-hand-side:
-
- ($dev, $ino, undef, undef, $uid, $gid) = stat($file);
-
-You can also use a list slice to select only the elements that
-you need:
-
- ($dev, $ino, $uid, $gid) = ( stat($file) )[0,1,4,5];
-
-=head2 How do I temporarily block warnings?
-
-If you are running Perl 5.6.0 or better, the C<use warnings> pragma
-allows fine control of what warnings are produced.
-See L<perllexwarn> for more details.
-
- {
- no warnings; # temporarily turn off warnings
- $x = $y + $z; # I know these might be undef
- }
-
-Additionally, you can enable and disable categories of warnings.
-You turn off the categories you want to ignore and you can still
-get other categories of warnings. See L<perllexwarn> for the
-complete details, including the category names and hierarchy.
-
- {
- no warnings 'uninitialized';
- $x = $y + $z;
- }
-
-If you have an older version of Perl, the C<$^W> variable (documented
-in L<perlvar>) controls runtime warnings for a block:
-
- {
- local $^W = 0; # temporarily turn off warnings
- $x = $y + $z; # I know these might be undef
- }
-
-Note that like all the punctuation variables, you cannot currently
-use my() on C<$^W>, only local().
-
-=head2 What's an extension?
-
-An extension is a way of calling compiled C code from Perl. Reading
-L<perlxstut> is a good place to learn more about extensions.
-
-=head2 Why do Perl operators have different precedence than C operators?
-
-Actually, they don't. All C operators that Perl copies have the same
-precedence in Perl as they do in C. The problem is with operators that C
-doesn't have, especially functions that give a list context to everything
-on their right, eg. print, chmod, exec, and so on. Such functions are
-called "list operators" and appear as such in the precedence table in
-L<perlop>.
-
-A common mistake is to write:
-
- unlink $file || die "snafu";
-
-This gets interpreted as:
-
- unlink ($file || die "snafu");
-
-To avoid this problem, either put in extra parentheses or use the
-super low precedence C<or> operator:
-
- (unlink $file) || die "snafu";
- unlink $file or die "snafu";
-
-The "English" operators (C<and>, C<or>, C<xor>, and C<not>)
-deliberately have precedence lower than that of list operators for
-just such situations as the one above.
-
-Another operator with surprising precedence is exponentiation. It
-binds more tightly even than unary minus, making C<-2**2> produce a
-negative four and not a positive one. It is also right-associating, meaning
-that C<2**3**2> is two raised to the ninth power, not eight squared.
-
-Although it has the same precedence as in C, Perl's C<?:> operator
-produces an lvalue. This assigns $x to either $if_true or $if_false, depending
-on the trueness of $maybe:
-
- ($maybe ? $if_true : $if_false) = $x;
-
-=head2 How do I declare/create a structure?
-
-In general, you don't "declare" a structure. Just use a (probably
-anonymous) hash reference. See L<perlref> and L<perldsc> for details.
-Here's an example:
-
- $person = {}; # new anonymous hash
- $person->{AGE} = 24; # set field AGE to 24
- $person->{NAME} = "Nat"; # set field NAME to "Nat"
-
-If you're looking for something a bit more rigorous, try L<perltoot>.
-
-=head2 How do I create a module?
-
-L<perlnewmod> is a good place to start, ignore the bits
-about uploading to CPAN if you don't want to make your
-module publicly available.
-
-L<ExtUtils::ModuleMaker> and L<Module::Starter> are also
-good places to start. Many CPAN authors now use L<Dist::Zilla>
-to automate as much as possible.
-
-Detailed documentation about modules can be found at:
-L<perlmod>, L<perlmodlib>, L<perlmodstyle>.
-
-If you need to include C code or C library interfaces
-use h2xs. h2xs will create the module distribution structure
-and the initial interface files.
-L<perlxs> and L<perlxstut> explain the details.
-
-=head2 How do I adopt or take over a module already on CPAN?
-
-Ask the current maintainer to make you a co-maintainer or
-transfer the module to you.
-
-If you can not reach the author for some reason contact
-the PAUSE admins at modules@perl.org who may be able to help,
-but each case it treated seperatly.
-
-=over 4
-
-=item *
-
-Get a login for the Perl Authors Upload Server (PAUSE) if you don't
-already have one: L<http://pause.perl.org>
-
-=item *
-
-Write to modules@perl.org explaining what you did to contact the
-current maintainer. The PAUSE admins will also try to reach the
-maintainer.
-
-=item *
-
-Post a public message in a heavily trafficked site announcing your
-intention to take over the module.
-
-=item *
-
-Wait a bit. The PAUSE admins don't want to act too quickly in case
-the current maintainer is on holiday. If there's no response to
-private communication or the public post, a PAUSE admin can transfer
-it to you.
-
-=back
-
-=head2 How do I create a class?
-X<class, creation> X<package>
-
-(contributed by brian d foy)
-
-In Perl, a class is just a package, and methods are just subroutines.
-Perl doesn't get more formal than that and lets you set up the package
-just the way that you like it (that is, it doesn't set up anything for
-you).
-
-The Perl documentation has several tutorials that cover class
-creation, including L<perlboot> (Barnyard Object Oriented Tutorial),
-L<perltoot> (Tom's Object Oriented Tutorial), L<perlbot> (Bag o'
-Object Tricks), and L<perlobj>.
-
-=head2 How can I tell if a variable is tainted?
-
-You can use the tainted() function of the Scalar::Util module, available
-from CPAN (or included with Perl since release 5.8.0).
-See also L<perlsec/"Laundering and Detecting Tainted Data">.
-
-=head2 What's a closure?
-
-Closures are documented in L<perlref>.
-
-I<Closure> is a computer science term with a precise but
-hard-to-explain meaning. Usually, closures are implemented in Perl as
-anonymous subroutines with lasting references to lexical variables
-outside their own scopes. These lexicals magically refer to the
-variables that were around when the subroutine was defined (deep
-binding).
-
-Closures are most often used in programming languages where you can
-have the return value of a function be itself a function, as you can
-in Perl. Note that some languages provide anonymous functions but are
-not capable of providing proper closures: the Python language, for
-example. For more information on closures, check out any textbook on
-functional programming. Scheme is a language that not only supports
-but encourages closures.
-
-Here's a classic non-closure function-generating function:
-
- sub add_function_generator {
- return sub { shift() + shift() };
- }
-
- my $add_sub = add_function_generator();
- my $sum = $add_sub->(4,5); # $sum is 9 now.
-
-The anonymous subroutine returned by add_function_generator() isn't
-technically a closure because it refers to no lexicals outside its own
-scope. Using a closure gives you a I<function template> with some
-customization slots left out to be filled later.
-
-Contrast this with the following make_adder() function, in which the
-returned anonymous function contains a reference to a lexical variable
-outside the scope of that function itself. Such a reference requires
-that Perl return a proper closure, thus locking in for all time the
-value that the lexical had when the function was created.
-
- sub make_adder {
- my $addpiece = shift;
- return sub { shift() + $addpiece };
- }
-
- my $f1 = make_adder(20);
- my $f2 = make_adder(555);
-
-Now C<< $f1->($n) >> is always 20 plus whatever $n you pass in, whereas
-C<< $f2->($n) >> is always 555 plus whatever $n you pass in. The $addpiece
-in the closure sticks around.
-
-Closures are often used for less esoteric purposes. For example, when
-you want to pass in a bit of code into a function:
-
- my $line;
- timeout( 30, sub { $line = <STDIN> } );
-
-If the code to execute had been passed in as a string,
-C<< '$line = <STDIN>' >>, there would have been no way for the
-hypothetical timeout() function to access the lexical variable
-$line back in its caller's scope.
-
-Another use for a closure is to make a variable I<private> to a
-named subroutine, e.g. a counter that gets initialized at creation
-time of the sub and can only be modified from within the sub.
-This is sometimes used with a BEGIN block in package files to make
-sure a variable doesn't get meddled with during the lifetime of the
-package:
-
- BEGIN {
- my $id = 0;
- sub next_id { ++$id }
- }
-
-This is discussed in more detail in L<perlsub>; see the entry on
-I<Persistent Private Variables>.
-
-=head2 What is variable suicide and how can I prevent it?
-
-This problem was fixed in perl 5.004_05, so preventing it means upgrading
-your version of perl. ;)
-
-Variable suicide is when you (temporarily or permanently) lose the value
-of a variable. It is caused by scoping through my() and local()
-interacting with either closures or aliased foreach() iterator variables
-and subroutine arguments. It used to be easy to inadvertently lose a
-variable's value this way, but now it's much harder. Take this code:
-
- my $f = 'foo';
- sub T {
- while ($i++ < 3) { my $f = $f; $f .= "bar"; print $f, "\n" }
- }
-
- T;
- print "Finally $f\n";
-
-If you are experiencing variable suicide, that C<my $f> in the subroutine
-doesn't pick up a fresh copy of the C<$f> whose value is C<'foo'>. The
-output shows that inside the subroutine the value of C<$f> leaks through
-when it shouldn't, as in this output:
-
- foobar
- foobarbar
- foobarbarbar
- Finally foo
-
-The $f that has "bar" added to it three times should be a new C<$f>
-C<my $f> should create a new lexical variable each time through the loop.
-The expected output is:
-
- foobar
- foobar
- foobar
- Finally foo
-
-=head2 How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?
-
-You need to pass references to these objects. See L<perlsub/"Pass by
-Reference"> for this particular question, and L<perlref> for
-information on references.
-
-=over 4
-
-=item Passing Variables and Functions
-
-Regular variables and functions are quite easy to pass: just pass in a
-reference to an existing or anonymous variable or function:
-
- func( \$some_scalar );
-
- func( \@some_array );
- func( [ 1 .. 10 ] );
-
- func( \%some_hash );
- func( { this => 10, that => 20 } );
-
- func( \&some_func );
- func( sub { $_[0] ** $_[1] } );
-
-=item Passing Filehandles
-
-As of Perl 5.6, you can represent filehandles with scalar variables
-which you treat as any other scalar.
-
- open my $fh, $filename or die "Cannot open $filename! $!";
- func( $fh );
-
- sub func {
- my $passed_fh = shift;
-
- my $line = <$passed_fh>;
- }
-
-Before Perl 5.6, you had to use the C<*FH> or C<\*FH> notations.
-These are "typeglobs"--see L<perldata/"Typeglobs and Filehandles">
-and especially L<perlsub/"Pass by Reference"> for more information.
-
-=item Passing Regexes
-
-Here's an example of how to pass in a string and a regular expression
-for it to match against. You construct the pattern with the C<qr//>
-operator:
-
- sub compare($$) {
- my ($val1, $regex) = @_;
- my $retval = $val1 =~ /$regex/;
- return $retval;
- }
- $match = compare("old McDonald", qr/d.*D/i);
-
-=item Passing Methods
-
-To pass an object method into a subroutine, you can do this:
-
- call_a_lot(10, $some_obj, "methname")
- sub call_a_lot {
- my ($count, $widget, $trick) = @_;
- for (my $i = 0; $i < $count; $i++) {
- $widget->$trick();
- }
- }
-
-Or, you can use a closure to bundle up the object, its
-method call, and arguments:
-
- my $whatnot = sub { $some_obj->obfuscate(@args) };
- func($whatnot);
- sub func {
- my $code = shift;
- &$code();
- }
-
-You could also investigate the can() method in the UNIVERSAL class
-(part of the standard perl distribution).
-
-=back
-
-=head2 How do I create a static variable?
-
-(contributed by brian d foy)
-
-In Perl 5.10, declare the variable with C<state>. The C<state>
-declaration creates the lexical variable that persists between calls
-to the subroutine:
-
- sub counter { state $count = 1; $count++ }
-
-You can fake a static variable by using a lexical variable which goes
-out of scope. In this example, you define the subroutine C<counter>, and
-it uses the lexical variable C<$count>. Since you wrap this in a BEGIN
-block, C<$count> is defined at compile-time, but also goes out of
-scope at the end of the BEGIN block. The BEGIN block also ensures that
-the subroutine and the value it uses is defined at compile-time so the
-subroutine is ready to use just like any other subroutine, and you can
-put this code in the same place as other subroutines in the program
-text (i.e. at the end of the code, typically). The subroutine
-C<counter> still has a reference to the data, and is the only way you
-can access the value (and each time you do, you increment the value).
-The data in chunk of memory defined by C<$count> is private to
-C<counter>.
-
- BEGIN {
- my $count = 1;
- sub counter { $count++ }
- }
-
- my $start = counter();
-
- .... # code that calls counter();
-
- my $end = counter();
-
-In the previous example, you created a function-private variable
-because only one function remembered its reference. You could define
-multiple functions while the variable is in scope, and each function
-can share the "private" variable. It's not really "static" because you
-can access it outside the function while the lexical variable is in
-scope, and even create references to it. In this example,
-C<increment_count> and C<return_count> share the variable. One
-function adds to the value and the other simply returns the value.
-They can both access C<$count>, and since it has gone out of scope,
-there is no other way to access it.
-
- BEGIN {
- my $count = 1;
- sub increment_count { $count++ }
- sub return_count { $count }
- }
-
-To declare a file-private variable, you still use a lexical variable.
-A file is also a scope, so a lexical variable defined in the file
-cannot be seen from any other file.
-
-See L<perlsub/"Persistent Private Variables"> for more information.
-The discussion of closures in L<perlref> may help you even though we
-did not use anonymous subroutines in this answer. See
-L<perlsub/"Persistent Private Variables"> for details.
-
-=head2 What's the difference between dynamic and lexical (static) scoping? Between local() and my()?
-
-C<local($x)> saves away the old value of the global variable C<$x>
-and assigns a new value for the duration of the subroutine I<which is
-visible in other functions called from that subroutine>. This is done
-at run-time, so is called dynamic scoping. local() always affects global
-variables, also called package variables or dynamic variables.
-
-C<my($x)> creates a new variable that is only visible in the current
-subroutine. This is done at compile-time, so it is called lexical or
-static scoping. my() always affects private variables, also called
-lexical variables or (improperly) static(ly scoped) variables.
-
-For instance:
-
- sub visible {
- print "var has value $var\n";
- }
-
- sub dynamic {
- local $var = 'local'; # new temporary value for the still-global
- visible(); # variable called $var
- }
-
- sub lexical {
- my $var = 'private'; # new private variable, $var
- visible(); # (invisible outside of sub scope)
- }
-
- $var = 'global';
-
- visible(); # prints global
- dynamic(); # prints local
- lexical(); # prints global
-
-Notice how at no point does the value "private" get printed. That's
-because $var only has that value within the block of the lexical()
-function, and it is hidden from the called subroutine.
-
-In summary, local() doesn't make what you think of as private, local
-variables. It gives a global variable a temporary value. my() is
-what you're looking for if you want private variables.
-
-See L<perlsub/"Private Variables via my()"> and
-L<perlsub/"Temporary Values via local()"> for excruciating details.
-
-=head2 How can I access a dynamic variable while a similarly named lexical is in scope?
-
-If you know your package, you can just mention it explicitly, as in
-$Some_Pack::var. Note that the notation $::var is B<not> the dynamic $var
-in the current package, but rather the one in the "main" package, as
-though you had written $main::var.
-
- use vars '$var';
- local $var = "global";
- my $var = "lexical";
-
- print "lexical is $var\n";
- print "global is $main::var\n";
-
-Alternatively you can use the compiler directive our() to bring a
-dynamic variable into the current lexical scope.
-
- require 5.006; # our() did not exist before 5.6
- use vars '$var';
-
- local $var = "global";
- my $var = "lexical";
-
- print "lexical is $var\n";
-
- {
- our $var;
- print "global is $var\n";
- }
-
-=head2 What's the difference between deep and shallow binding?
-
-In deep binding, lexical variables mentioned in anonymous subroutines
-are the same ones that were in scope when the subroutine was created.
-In shallow binding, they are whichever variables with the same names
-happen to be in scope when the subroutine is called. Perl always uses
-deep binding of lexical variables (i.e., those created with my()).
-However, dynamic variables (aka global, local, or package variables)
-are effectively shallowly bound. Consider this just one more reason
-not to use them. See the answer to L<"What's a closure?">.
-
-=head2 Why doesn't "my($foo) = E<lt>$fhE<gt>;" work right?
-
-C<my()> and C<local()> give list context to the right hand side
-of C<=>. The <$fh> read operation, like so many of Perl's
-functions and operators, can tell which context it was called in and
-behaves appropriately. In general, the scalar() function can help.
-This function does nothing to the data itself (contrary to popular myth)
-but rather tells its argument to behave in whatever its scalar fashion is.
-If that function doesn't have a defined scalar behavior, this of course
-doesn't help you (such as with sort()).
-
-To enforce scalar context in this particular case, however, you need
-merely omit the parentheses:
-
- local($foo) = <$fh>; # WRONG
- local($foo) = scalar(<$fh>); # ok
- local $foo = <$fh>; # right
-
-You should probably be using lexical variables anyway, although the
-issue is the same here:
-
- my($foo) = <$fh>; # WRONG
- my $foo = <$fh>; # right
-
-=head2 How do I redefine a builtin function, operator, or method?
-
-Why do you want to do that? :-)
-
-If you want to override a predefined function, such as open(),
-then you'll have to import the new definition from a different
-module. See L<perlsub/"Overriding Built-in Functions">.
-
-If you want to overload a Perl operator, such as C<+> or C<**>,
-then you'll want to use the C<use overload> pragma, documented
-in L<overload>.
-
-If you're talking about obscuring method calls in parent classes,
-see L<perltoot/"Overridden Methods">.
-
-=head2 What's the difference between calling a function as &foo and foo()?
-
-(contributed by brian d foy)
-
-Calling a subroutine as C<&foo> with no trailing parentheses ignores
-the prototype of C<foo> and passes it the current value of the argument
-list, C<@_>. Here's an example; the C<bar> subroutine calls C<&foo>,
-which prints its arguments list:
-
- sub bar { &foo }
-
- sub foo { print "Args in foo are: @_\n" }
-
- bar( qw( a b c ) );
-
-When you call C<bar> with arguments, you see that C<foo> got the same C<@_>:
-
- Args in foo are: a b c
-
-Calling the subroutine with trailing parentheses, with or without arguments,
-does not use the current C<@_> and respects the subroutine prototype. Changing
-the example to put parentheses after the call to C<foo> changes the program:
-
- sub bar { &foo() }
-
- sub foo { print "Args in foo are: @_\n" }
-
- bar( qw( a b c ) );
-
-Now the output shows that C<foo> doesn't get the C<@_> from its caller.
-
- Args in foo are:
-
-The main use of the C<@_> pass-through feature is to write subroutines
-whose main job it is to call other subroutines for you. For further
-details, see L<perlsub>.
-
-=head2 How do I create a switch or case statement?
-
-In Perl 5.10, use the C<given-when> construct described in L<perlsyn>:
-
- use 5.010;
-
- given ( $string ) {
- when( 'Fred' ) { say "I found Fred!" }
- when( 'Barney' ) { say "I found Barney!" }
- when( /Bamm-?Bamm/ ) { say "I found Bamm-Bamm!" }
- default { say "I don't recognize the name!" }
- };
-
-If one wants to use pure Perl and to be compatible with Perl versions
-prior to 5.10, the general answer is to use C<if-elsif-else>:
-
- for ($variable_to_test) {
- if (/pat1/) { } # do something
- elsif (/pat2/) { } # do something else
- elsif (/pat3/) { } # do something else
- else { } # default
- }
-
-Here's a simple example of a switch based on pattern matching,
-lined up in a way to make it look more like a switch statement.
-We'll do a multiway conditional based on the type of reference stored
-in $whatchamacallit:
-
- SWITCH: for (ref $whatchamacallit) {
-
- /^$/ && die "not a reference";
-
- /SCALAR/ && do {
- print_scalar($$ref);
- last SWITCH;
- };
-
- /ARRAY/ && do {
- print_array(@$ref);
- last SWITCH;
- };
-
- /HASH/ && do {
- print_hash(%$ref);
- last SWITCH;
- };
-
- /CODE/ && do {
- warn "can't print function ref";
- last SWITCH;
- };
-
- # DEFAULT
-
- warn "User defined type skipped";
-
- }
-
-See L<perlsyn> for other examples in this style.
-
-Sometimes you should change the positions of the constant and the variable.
-For example, let's say you wanted to test which of many answers you were
-given, but in a case-insensitive way that also allows abbreviations.
-You can use the following technique if the strings all start with
-different characters or if you want to arrange the matches so that
-one takes precedence over another, as C<"SEND"> has precedence over
-C<"STOP"> here:
-
- chomp($answer = <>);
- if ("SEND" =~ /^\Q$answer/i) { print "Action is send\n" }
- elsif ("STOP" =~ /^\Q$answer/i) { print "Action is stop\n" }
- elsif ("ABORT" =~ /^\Q$answer/i) { print "Action is abort\n" }
- elsif ("LIST" =~ /^\Q$answer/i) { print "Action is list\n" }
- elsif ("EDIT" =~ /^\Q$answer/i) { print "Action is edit\n" }
-
-A totally different approach is to create a hash of function references.
-
- my %commands = (
- "happy" => \&joy,
- "sad", => \&sullen,
- "done" => sub { die "See ya!" },
- "mad" => \&angry,
- );
-
- print "How are you? ";
- chomp($string = <STDIN>);
- if ($commands{$string}) {
- $commands{$string}->();
- } else {
- print "No such command: $string\n";
- }
-
-Starting from Perl 5.8, a source filter module, C<Switch>, can also be
-used to get switch and case. Its use is now discouraged, because it's
-not fully compatible with the native switch of Perl 5.10, and because,
-as it's implemented as a source filter, it doesn't always work as intended
-when complex syntax is involved.
-
-=head2 How can I catch accesses to undefined variables, functions, or methods?
-
-The AUTOLOAD method, discussed in L<perlsub/"Autoloading"> and
-L<perltoot/"AUTOLOAD: Proxy Methods">, lets you capture calls to
-undefined functions and methods.
-
-When it comes to undefined variables that would trigger a warning
-under C<use warnings>, you can promote the warning to an error.
-
- use warnings FATAL => qw(uninitialized);
-
-=head2 Why can't a method included in this same file be found?
-
-Some possible reasons: your inheritance is getting confused, you've
-misspelled the method name, or the object is of the wrong type. Check
-out L<perltoot> for details about any of the above cases. You may
-also use C<print ref($object)> to find out the class C<$object> was
-blessed into.
-
-Another possible reason for problems is that you've used the
-indirect object syntax (eg, C<find Guru "Samy">) on a class name
-before Perl has seen that such a package exists. It's wisest to make
-sure your packages are all defined before you start using them, which
-will be taken care of if you use the C<use> statement instead of
-C<require>. If not, make sure to use arrow notation (eg.,
-C<< Guru->find("Samy") >>) instead. Object notation is explained in
-L<perlobj>.
-
-Make sure to read about creating modules in L<perlmod> and
-the perils of indirect objects in L<perlobj/"Method Invocation">.
-
-=head2 How can I find out my current or calling package?
-
-(contributed by brian d foy)
-
-To find the package you are currently in, use the special literal
-C<__PACKAGE__>, as documented in L<perldata>. You can only use the
-special literals as separate tokens, so you can't interpolate them
-into strings like you can with variables:
-
- my $current_package = __PACKAGE__;
- print "I am in package $current_package\n";
-
-If you want to find the package calling your code, perhaps to give better
-diagnostics as L<Carp> does, use the C<caller> built-in:
-
- sub foo {
- my @args = ...;
- my( $package, $filename, $line ) = caller;
-
- print "I was called from package $package\n";
- );
-
-By default, your program starts in package C<main>, so you will
-always be in some package.
-
-This is different from finding out the package an object is blessed
-into, which might not be the current package. For that, use C<blessed>
-from L<Scalar::Util>, part of the Standard Library since Perl 5.8:
-
- use Scalar::Util qw(blessed);
- my $object_package = blessed( $object );
-
-Most of the time, you shouldn't care what package an object is blessed
-into, however, as long as it claims to inherit from that class:
-
- my $is_right_class = eval { $object->isa( $package ) }; # true or false
-
-And, with Perl 5.10 and later, you don't have to check for an
-inheritance to see if the object can handle a role. For that, you can
-use C<DOES>, which comes from C<UNIVERSAL>:
-
- my $class_does_it = eval { $object->DOES( $role ) }; # true or false
-
-You can safely replace C<isa> with C<DOES> (although the converse is not true).
-
-=head2 How can I comment out a large block of Perl code?
-
-(contributed by brian d foy)
-
-The quick-and-dirty way to comment out more than one line of Perl is
-to surround those lines with Pod directives. You have to put these
-directives at the beginning of the line and somewhere where Perl
-expects a new statement (so not in the middle of statements like the C<#>
-comments). You end the comment with C<=cut>, ending the Pod section:
-
- =pod
-
- my $object = NotGonnaHappen->new();
-
- ignored_sub();
-
- $wont_be_assigned = 37;
-
- =cut
-
-The quick-and-dirty method only works well when you don't plan to
-leave the commented code in the source. If a Pod parser comes along,
-you're multiline comment is going to show up in the Pod translation.
-A better way hides it from Pod parsers as well.
-
-The C<=begin> directive can mark a section for a particular purpose.
-If the Pod parser doesn't want to handle it, it just ignores it. Label
-the comments with C<comment>. End the comment using C<=end> with the
-same label. You still need the C<=cut> to go back to Perl code from
-the Pod comment:
-
- =begin comment
-
- my $object = NotGonnaHappen->new();
-
- ignored_sub();
-
- $wont_be_assigned = 37;
-
- =end comment
-
- =cut
-
-For more information on Pod, check out L<perlpod> and L<perlpodspec>.
-
-=head2 How do I clear a package?
-
-Use this code, provided by Mark-Jason Dominus:
-
- sub scrub_package {
- no strict 'refs';
- my $pack = shift;
- die "Shouldn't delete main package"
- if $pack eq "" || $pack eq "main";
- my $stash = *{$pack . '::'}{HASH};
- my $name;
- foreach $name (keys %$stash) {
- my $fullname = $pack . '::' . $name;
- # Get rid of everything with that name.
- undef $$fullname;
- undef @$fullname;
- undef %$fullname;
- undef &$fullname;
- undef *$fullname;
- }
- }
-
-Or, if you're using a recent release of Perl, you can
-just use the Symbol::delete_package() function instead.
-
-=head2 How can I use a variable as a variable name?
-
-Beginners often think they want to have a variable contain the name
-of a variable.
-
- $fred = 23;
- $varname = "fred";
- ++$$varname; # $fred now 24
-
-This works I<sometimes>, but it is a very bad idea for two reasons.
-
-The first reason is that this technique I<only works on global
-variables>. That means that if $fred is a lexical variable created
-with my() in the above example, the code wouldn't work at all: you'd
-accidentally access the global and skip right over the private lexical
-altogether. Global variables are bad because they can easily collide
-accidentally and in general make for non-scalable and confusing code.
-
-Symbolic references are forbidden under the C<use strict> pragma.
-They are not true references and consequently are not reference-counted
-or garbage-collected.
-
-The other reason why using a variable to hold the name of another
-variable is a bad idea is that the question often stems from a lack of
-understanding of Perl data structures, particularly hashes. By using
-symbolic references, you are just using the package's symbol-table hash
-(like C<%main::>) instead of a user-defined hash. The solution is to
-use your own hash or a real reference instead.
-
- $USER_VARS{"fred"} = 23;
- my $varname = "fred";
- $USER_VARS{$varname}++; # not $$varname++
-
-There we're using the %USER_VARS hash instead of symbolic references.
-Sometimes this comes up in reading strings from the user with variable
-references and wanting to expand them to the values of your perl
-program's variables. This is also a bad idea because it conflates the
-program-addressable namespace and the user-addressable one. Instead of
-reading a string and expanding it to the actual contents of your program's
-own variables:
-
- $str = 'this has a $fred and $barney in it';
- $str =~ s/(\$\w+)/$1/eeg; # need double eval
-
-it would be better to keep a hash around like %USER_VARS and have
-variable references actually refer to entries in that hash:
-
- $str =~ s/\$(\w+)/$USER_VARS{$1}/g; # no /e here at all
-
-That's faster, cleaner, and safer than the previous approach. Of course,
-you don't need to use a dollar sign. You could use your own scheme to
-make it less confusing, like bracketed percent symbols, etc.
-
- $str = 'this has a %fred% and %barney% in it';
- $str =~ s/%(\w+)%/$USER_VARS{$1}/g; # no /e here at all
-
-Another reason that folks sometimes think they want a variable to
-contain the name of a variable is that they don't know how to build
-proper data structures using hashes. For example, let's say they
-wanted two hashes in their program: %fred and %barney, and that they
-wanted to use another scalar variable to refer to those by name.
-
- $name = "fred";
- $$name{WIFE} = "wilma"; # set %fred
-
- $name = "barney";
- $$name{WIFE} = "betty"; # set %barney
-
-This is still a symbolic reference, and is still saddled with the
-problems enumerated above. It would be far better to write:
-
- $folks{"fred"}{WIFE} = "wilma";
- $folks{"barney"}{WIFE} = "betty";
-
-And just use a multilevel hash to start with.
-
-The only times that you absolutely I<must> use symbolic references are
-when you really must refer to the symbol table. This may be because it's
-something that one can't take a real reference to, such as a format name.
-Doing so may also be important for method calls, since these always go
-through the symbol table for resolution.
-
-In those cases, you would turn off C<strict 'refs'> temporarily so you
-can play around with the symbol table. For example:
-
- @colors = qw(red blue green yellow orange purple violet);
- for my $name (@colors) {
- no strict 'refs'; # renege for the block
- *$name = sub { "<FONT COLOR='$name'>@_</FONT>" };
- }
-
-All those functions (red(), blue(), green(), etc.) appear to be separate,
-but the real code in the closure actually was compiled only once.
-
-So, sometimes you might want to use symbolic references to manipulate
-the symbol table directly. This doesn't matter for formats, handles, and
-subroutines, because they are always global--you can't use my() on them.
-For scalars, arrays, and hashes, though--and usually for subroutines--
-you probably only want to use hard references.
-
-=head2 What does "bad interpreter" mean?
-
-(contributed by brian d foy)
-
-The "bad interpreter" message comes from the shell, not perl. The
-actual message may vary depending on your platform, shell, and locale
-settings.
-
-If you see "bad interpreter - no such file or directory", the first
-line in your perl script (the "shebang" line) does not contain the
-right path to perl (or any other program capable of running scripts).
-Sometimes this happens when you move the script from one machine to
-another and each machine has a different path to perl--/usr/bin/perl
-versus /usr/local/bin/perl for instance. It may also indicate
-that the source machine has CRLF line terminators and the
-destination machine has LF only: the shell tries to find
-/usr/bin/perl<CR>, but can't.
-
-If you see "bad interpreter: Permission denied", you need to make your
-script executable.
-
-In either case, you should still be able to run the scripts with perl
-explicitly:
-
- % perl script.pl
-
-If you get a message like "perl: command not found", perl is not in
-your PATH, which might also mean that the location of perl is not
-where you expect it so you need to adjust your shebang line.
-
-=head1 AUTHOR AND COPYRIGHT
-
-Copyright (c) 1997-2010 Tom Christiansen, Nathan Torkington, and
-other authors as noted. All rights reserved.
-
-This documentation is free; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-Irrespective of its distribution, all code examples in this file
-are hereby placed into the public domain. You are permitted and
-encouraged to use this code in your own programs for fun
-or for profit as you see fit. A simple comment in the code giving
-credit would be courteous but is not required.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq8.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq8.pod
deleted file mode 100644
index 1c7793e3558..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlfaq8.pod
+++ /dev/null
@@ -1,1422 +0,0 @@
-=head1 NAME
-
-perlfaq8 - System Interaction
-
-=head1 DESCRIPTION
-
-This section of the Perl FAQ covers questions involving operating
-system interaction. Topics include interprocess communication (IPC),
-control over the user-interface (keyboard, screen and pointing
-devices), and most anything else not related to data manipulation.
-
-Read the FAQs and documentation specific to the port of perl to your
-operating system (eg, L<perlvms>, L<perlplan9>, ...). These should
-contain more detailed information on the vagaries of your perl.
-
-=head2 How do I find out which operating system I'm running under?
-
-The C<$^O> variable (C<$OSNAME> if you use C<English>) contains an
-indication of the name of the operating system (not its release
-number) that your perl binary was built for.
-
-=head2 How come exec() doesn't return?
-X<exec> X<system> X<fork> X<open> X<pipe>
-
-(contributed by brian d foy)
-
-The C<exec> function's job is to turn your process into another
-command and never to return. If that's not what you want to do, don't
-use C<exec>. :)
-
-If you want to run an external command and still keep your Perl process
-going, look at a piped C<open>, C<fork>, or C<system>.
-
-=head2 How do I do fancy stuff with the keyboard/screen/mouse?
-
-How you access/control keyboards, screens, and pointing devices
-("mice") is system-dependent. Try the following modules:
-
-=over 4
-
-=item Keyboard
-
- Term::Cap Standard perl distribution
- Term::ReadKey CPAN
- Term::ReadLine::Gnu CPAN
- Term::ReadLine::Perl CPAN
- Term::Screen CPAN
-
-=item Screen
-
- Term::Cap Standard perl distribution
- Curses CPAN
- Term::ANSIColor CPAN
-
-=item Mouse
-
- Tk CPAN
- Wx CPAN
- Gtk2 CPAN
- Qt4 kdebindings4 package
-
-=back
-
-Some of these specific cases are shown as examples in other answers
-in this section of the perlfaq.
-
-=head2 How do I print something out in color?
-
-In general, you don't, because you don't know whether
-the recipient has a color-aware display device. If you
-know that they have an ANSI terminal that understands
-color, you can use the L<Term::ANSIColor> module from CPAN:
-
- use Term::ANSIColor;
- print color("red"), "Stop!\n", color("reset");
- print color("green"), "Go!\n", color("reset");
-
-Or like this:
-
- use Term::ANSIColor qw(:constants);
- print RED, "Stop!\n", RESET;
- print GREEN, "Go!\n", RESET;
-
-=head2 How do I read just one key without waiting for a return key?
-
-Controlling input buffering is a remarkably system-dependent matter.
-On many systems, you can just use the B<stty> command as shown in
-L<perlfunc/getc>, but as you see, that's already getting you into
-portability snags.
-
- open(TTY, "+</dev/tty") or die "no tty: $!";
- system "stty cbreak </dev/tty >/dev/tty 2>&1";
- $key = getc(TTY); # perhaps this works
- # OR ELSE
- sysread(TTY, $key, 1); # probably this does
- system "stty -cbreak </dev/tty >/dev/tty 2>&1";
-
-The L<Term::ReadKey> module from CPAN offers an easy-to-use interface that
-should be more efficient than shelling out to B<stty> for each key.
-It even includes limited support for Windows.
-
- use Term::ReadKey;
- ReadMode('cbreak');
- $key = ReadKey(0);
- ReadMode('normal');
-
-However, using the code requires that you have a working C compiler
-and can use it to build and install a CPAN module. Here's a solution
-using the standard L<POSIX> module, which is already on your system
-(assuming your system supports POSIX).
-
- use HotKey;
- $key = readkey();
-
-And here's the C<HotKey> module, which hides the somewhat mystifying calls
-to manipulate the POSIX termios structures.
-
- # HotKey.pm
- package HotKey;
-
- use strict;
- use warnings;
-
- use parent 'Exporter';
- our @EXPORT = qw(cbreak cooked readkey);
-
- use POSIX qw(:termios_h);
- my ($term, $oterm, $echo, $noecho, $fd_stdin);
-
- $fd_stdin = fileno(STDIN);
- $term = POSIX::Termios->new();
- $term->getattr($fd_stdin);
- $oterm = $term->getlflag();
-
- $echo = ECHO | ECHOK | ICANON;
- $noecho = $oterm & ~$echo;
-
- sub cbreak {
- $term->setlflag($noecho); # ok, so i don't want echo either
- $term->setcc(VTIME, 1);
- $term->setattr($fd_stdin, TCSANOW);
- }
-
- sub cooked {
- $term->setlflag($oterm);
- $term->setcc(VTIME, 0);
- $term->setattr($fd_stdin, TCSANOW);
- }
-
- sub readkey {
- my $key = '';
- cbreak();
- sysread(STDIN, $key, 1);
- cooked();
- return $key;
- }
-
- END { cooked() }
-
- 1;
-
-=head2 How do I check whether input is ready on the keyboard?
-
-The easiest way to do this is to read a key in nonblocking mode with the
-L<Term::ReadKey> module from CPAN, passing it an argument of -1 to indicate
-not to block:
-
- use Term::ReadKey;
-
- ReadMode('cbreak');
-
- if (defined (my $char = ReadKey(-1)) ) {
- # input was waiting and it was $char
- } else {
- # no input was waiting
- }
-
- ReadMode('normal'); # restore normal tty settings
-
-=head2 How do I clear the screen?
-
-(contributed by brian d foy)
-
-To clear the screen, you just have to print the special sequence
-that tells the terminal to clear the screen. Once you have that
-sequence, output it when you want to clear the screen.
-
-You can use the L<Term::ANSIScreen> module to get the special
-sequence. Import the C<cls> function (or the C<:screen> tag):
-
- use Term::ANSIScreen qw(cls);
- my $clear_screen = cls();
-
- print $clear_screen;
-
-The L<Term::Cap> module can also get the special sequence if you want
-to deal with the low-level details of terminal control. The C<Tputs>
-method returns the string for the given capability:
-
- use Term::Cap;
-
- my $terminal = Term::Cap->Tgetent( { OSPEED => 9600 } );
- my $clear_string = $terminal->Tputs('cl');
-
- print $clear_screen;
-
-On Windows, you can use the L<Win32::Console> module. After creating
-an object for the output filehandle you want to affect, call the
-C<Cls> method:
-
- Win32::Console;
-
- my $OUT = Win32::Console->new(STD_OUTPUT_HANDLE);
- my $clear_string = $OUT->Cls;
-
- print $clear_screen;
-
-If you have a command-line program that does the job, you can call
-it in backticks to capture whatever it outputs so you can use it
-later:
-
- my $clear_string = `clear`;
-
- print $clear_string;
-
-=head2 How do I get the screen size?
-
-If you have L<Term::ReadKey> module installed from CPAN,
-you can use it to fetch the width and height in characters
-and in pixels:
-
- use Term::ReadKey;
- my ($wchar, $hchar, $wpixels, $hpixels) = GetTerminalSize();
-
-This is more portable than the raw C<ioctl>, but not as
-illustrative:
-
- require 'sys/ioctl.ph';
- die "no TIOCGWINSZ " unless defined &TIOCGWINSZ;
- open(my $tty_fh, "+</dev/tty") or die "No tty: $!";
- unless (ioctl($tty_fh, &TIOCGWINSZ, $winsize='')) {
- die sprintf "$0: ioctl TIOCGWINSZ (%08x: $!)\n", &TIOCGWINSZ;
- }
- my ($row, $col, $xpixel, $ypixel) = unpack('S4', $winsize);
- print "(row,col) = ($row,$col)";
- print " (xpixel,ypixel) = ($xpixel,$ypixel)" if $xpixel || $ypixel;
- print "\n";
-
-=head2 How do I ask the user for a password?
-
-(This question has nothing to do with the web. See a different
-FAQ for that.)
-
-There's an example of this in L<perlfunc/crypt>). First, you put the
-terminal into "no echo" mode, then just read the password normally.
-You may do this with an old-style C<ioctl()> function, POSIX terminal
-control (see L<POSIX> or its documentation the Camel Book), or a call
-to the B<stty> program, with varying degrees of portability.
-
-You can also do this for most systems using the L<Term::ReadKey> module
-from CPAN, which is easier to use and in theory more portable.
-
- use Term::ReadKey;
-
- ReadMode('noecho');
- my $password = ReadLine(0);
-
-=head2 How do I read and write the serial port?
-
-This depends on which operating system your program is running on. In
-the case of Unix, the serial ports will be accessible through files in
-C</dev>; on other systems, device names will doubtless differ.
-Several problem areas common to all device interaction are the
-following:
-
-=over 4
-
-=item lockfiles
-
-Your system may use lockfiles to control multiple access. Make sure
-you follow the correct protocol. Unpredictable behavior can result
-from multiple processes reading from one device.
-
-=item open mode
-
-If you expect to use both read and write operations on the device,
-you'll have to open it for update (see L<perlfunc/"open"> for
-details). You may wish to open it without running the risk of
-blocking by using C<sysopen()> and C<O_RDWR|O_NDELAY|O_NOCTTY> from the
-L<Fcntl> module (part of the standard perl distribution). See
-L<perlfunc/"sysopen"> for more on this approach.
-
-=item end of line
-
-Some devices will be expecting a "\r" at the end of each line rather
-than a "\n". In some ports of perl, "\r" and "\n" are different from
-their usual (Unix) ASCII values of "\015" and "\012". You may have to
-give the numeric values you want directly, using octal ("\015"), hex
-("0x0D"), or as a control-character specification ("\cM").
-
- print DEV "atv1\012"; # wrong, for some devices
- print DEV "atv1\015"; # right, for some devices
-
-Even though with normal text files a "\n" will do the trick, there is
-still no unified scheme for terminating a line that is portable
-between Unix, DOS/Win, and Macintosh, except to terminate I<ALL> line
-ends with "\015\012", and strip what you don't need from the output.
-This applies especially to socket I/O and autoflushing, discussed
-next.
-
-=item flushing output
-
-If you expect characters to get to your device when you C<print()> them,
-you'll want to autoflush that filehandle. You can use C<select()>
-and the C<$|> variable to control autoflushing (see L<perlvar/$E<verbar>>
-and L<perlfunc/select>, or L<perlfaq5>, "How do I flush/unbuffer an
-output filehandle? Why must I do this?"):
-
- my $old_handle = select($dev_fh);
- $| = 1;
- select($old_handle);
-
-You'll also see code that does this without a temporary variable, as in
-
- select((select($deb_handle), $| = 1)[0]);
-
-Or if you don't mind pulling in a few thousand lines
-of code just because you're afraid of a little C<$|> variable:
-
- use IO::Handle;
- $dev_fh->autoflush(1);
-
-As mentioned in the previous item, this still doesn't work when using
-socket I/O between Unix and Macintosh. You'll need to hard code your
-line terminators, in that case.
-
-=item non-blocking input
-
-If you are doing a blocking C<read()> or C<sysread()>, you'll have to
-arrange for an alarm handler to provide a timeout (see
-L<perlfunc/alarm>). If you have a non-blocking open, you'll likely
-have a non-blocking read, which means you may have to use a 4-arg
-C<select()> to determine whether I/O is ready on that device (see
-L<perlfunc/"select">.
-
-=back
-
-While trying to read from his caller-id box, the notorious Jamie
-Zawinski C<< <jwz@netscape.com> >>, after much gnashing of teeth and
-fighting with C<sysread>, C<sysopen>, POSIX's C<tcgetattr> business,
-and various other functions that go bump in the night, finally came up
-with this:
-
- sub open_modem {
- use IPC::Open2;
- my $stty = `/bin/stty -g`;
- open2( \*MODEM_IN, \*MODEM_OUT, "cu -l$modem_device -s2400 2>&1");
- # starting cu hoses /dev/tty's stty settings, even when it has
- # been opened on a pipe...
- system("/bin/stty $stty");
- $_ = <MODEM_IN>;
- chomp;
- if ( !m/^Connected/ ) {
- print STDERR "$0: cu printed `$_' instead of `Connected'\n";
- }
- }
-
-=head2 How do I decode encrypted password files?
-
-You spend lots and lots of money on dedicated hardware, but this is
-bound to get you talked about.
-
-Seriously, you can't if they are Unix password files--the Unix
-password system employs one-way encryption. It's more like hashing
-than encryption. The best you can do is check whether something else
-hashes to the same string. You can't turn a hash back into the
-original string. Programs like Crack can forcibly (and intelligently)
-try to guess passwords, but don't (can't) guarantee quick success.
-
-If you're worried about users selecting bad passwords, you should
-proactively check when they try to change their password (by modifying
-L<passwd(1)>, for example).
-
-=head2 How do I start a process in the background?
-
-(contributed by brian d foy)
-
-There's not a single way to run code in the background so you don't
-have to wait for it to finish before your program moves on to other
-tasks. Process management depends on your particular operating system,
-and many of the techniques are covered in L<perlipc>.
-
-Several CPAN modules may be able to help, including L<IPC::Open2> or
-L<IPC::Open3>, L<IPC::Run>, L<Parallel::Jobs>,
-L<Parallel::ForkManager>, L<POE>, L<Proc::Background>, and
-L<Win32::Process>. There are many other modules you might use, so
-check those namespaces for other options too.
-
-If you are on a Unix-like system, you might be able to get away with a
-system call where you put an C<&> on the end of the command:
-
- system("cmd &")
-
-You can also try using C<fork>, as described in L<perlfunc> (although
-this is the same thing that many of the modules will do for you).
-
-=over 4
-
-=item STDIN, STDOUT, and STDERR are shared
-
-Both the main process and the backgrounded one (the "child" process)
-share the same STDIN, STDOUT and STDERR filehandles. If both try to
-access them at once, strange things can happen. You may want to close
-or reopen these for the child. You can get around this with
-C<open>ing a pipe (see L<perlfunc/"open">) but on some systems this
-means that the child process cannot outlive the parent.
-
-=item Signals
-
-You'll have to catch the SIGCHLD signal, and possibly SIGPIPE too.
-SIGCHLD is sent when the backgrounded process finishes. SIGPIPE is
-sent when you write to a filehandle whose child process has closed (an
-untrapped SIGPIPE can cause your program to silently die). This is
-not an issue with C<system("cmd&")>.
-
-=item Zombies
-
-You have to be prepared to "reap" the child process when it finishes.
-
- $SIG{CHLD} = sub { wait };
-
- $SIG{CHLD} = 'IGNORE';
-
-You can also use a double fork. You immediately C<wait()> for your
-first child, and the init daemon will C<wait()> for your grandchild once
-it exits.
-
- unless ($pid = fork) {
- unless (fork) {
- exec "what you really wanna do";
- die "exec failed!";
- }
- exit 0;
- }
- waitpid($pid, 0);
-
-See L<perlipc/"Signals"> for other examples of code to do this.
-Zombies are not an issue with C<system("prog &")>.
-
-=back
-
-=head2 How do I trap control characters/signals?
-
-You don't actually "trap" a control character. Instead, that character
-generates a signal which is sent to your terminal's currently
-foregrounded process group, which you then trap in your process.
-Signals are documented in L<perlipc/"Signals"> and the
-section on "Signals" in the Camel.
-
-You can set the values of the C<%SIG> hash to be the functions you want
-to handle the signal. After perl catches the signal, it looks in C<%SIG>
-for a key with the same name as the signal, then calls the subroutine
-value for that key.
-
- # as an anonymous subroutine
-
- $SIG{INT} = sub { syswrite(STDERR, "ouch\n", 5 ) };
-
- # or a reference to a function
-
- $SIG{INT} = \&ouch;
-
- # or the name of the function as a string
-
- $SIG{INT} = "ouch";
-
-Perl versions before 5.8 had in its C source code signal handlers which
-would catch the signal and possibly run a Perl function that you had set
-in C<%SIG>. This violated the rules of signal handling at that level
-causing perl to dump core. Since version 5.8.0, perl looks at C<%SIG>
-B<after> the signal has been caught, rather than while it is being caught.
-Previous versions of this answer were incorrect.
-
-=head2 How do I modify the shadow password file on a Unix system?
-
-If perl was installed correctly and your shadow library was written
-properly, the C<getpw*()> functions described in L<perlfunc> should in
-theory provide (read-only) access to entries in the shadow password
-file. To change the file, make a new shadow password file (the format
-varies from system to system--see L<passwd(1)> for specifics) and use
-C<pwd_mkdb(8)> to install it (see L<pwd_mkdb(8)> for more details).
-
-=head2 How do I set the time and date?
-
-Assuming you're running under sufficient permissions, you should be
-able to set the system-wide date and time by running the C<date(1)>
-program. (There is no way to set the time and date on a per-process
-basis.) This mechanism will work for Unix, MS-DOS, Windows, and NT;
-the VMS equivalent is C<set time>.
-
-However, if all you want to do is change your time zone, you can
-probably get away with setting an environment variable:
-
- $ENV{TZ} = "MST7MDT"; # Unixish
- $ENV{'SYS$TIMEZONE_DIFFERENTIAL'}="-5" # vms
- system('trn', 'comp.lang.perl.misc');
-
-=head2 How can I sleep() or alarm() for under a second?
-X<Time::HiRes> X<BSD::Itimer> X<sleep> X<select>
-
-If you want finer granularity than the 1 second that the C<sleep()>
-function provides, the easiest way is to use the C<select()> function as
-documented in L<perlfunc/"select">. Try the L<Time::HiRes> and
-the L<BSD::Itimer> modules (available from CPAN, and starting from
-Perl 5.8 L<Time::HiRes> is part of the standard distribution).
-
-=head2 How can I measure time under a second?
-X<Time::HiRes> X<BSD::Itimer> X<sleep> X<select>
-
-(contributed by brian d foy)
-
-The L<Time::HiRes> module (part of the standard distribution as of
-Perl 5.8) measures time with the C<gettimeofday()> system call, which
-returns the time in microseconds since the epoch. If you can't install
-L<Time::HiRes> for older Perls and you are on a Unixish system, you
-may be able to call C<gettimeofday(2)> directly. See
-L<perlfunc/syscall>.
-
-=head2 How can I do an atexit() or setjmp()/longjmp()? (Exception handling)
-
-You can use the C<END> block to simulate C<atexit()>. Each package's
-C<END> block is called when the program or thread ends. See the L<perlmod>
-manpage for more details about C<END> blocks.
-
-For example, you can use this to make sure your filter program managed
-to finish its output without filling up the disk:
-
- END {
- close(STDOUT) || die "stdout close failed: $!";
- }
-
-The C<END> block isn't called when untrapped signals kill the program,
-though, so if you use C<END> blocks you should also use
-
- use sigtrap qw(die normal-signals);
-
-Perl's exception-handling mechanism is its C<eval()> operator. You
-can use C<eval()> as C<setjmp> and C<die()> as C<longjmp>. For
-details of this, see the section on signals, especially the time-out
-handler for a blocking C<flock()> in L<perlipc/"Signals"> or the
-section on "Signals" in I<Programming Perl>.
-
-If exception handling is all you're interested in, use one of the
-many CPAN modules that handle exceptions, such as L<Try::Tiny>.
-
-If you want the C<atexit()> syntax (and an C<rmexit()> as well), try the
-C<AtExit> module available from CPAN.
-
-=head2 Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean?
-
-Some Sys-V based systems, notably Solaris 2.X, redefined some of the
-standard socket constants. Since these were constant across all
-architectures, they were often hardwired into perl code. The proper
-way to deal with this is to "use Socket" to get the correct values.
-
-Note that even though SunOS and Solaris are binary compatible, these
-values are different. Go figure.
-
-=head2 How can I call my system's unique C functions from Perl?
-
-In most cases, you write an external module to do it--see the answer
-to "Where can I learn about linking C with Perl? [h2xs, xsubpp]".
-However, if the function is a system call, and your system supports
-C<syscall()>, you can use the C<syscall> function (documented in
-L<perlfunc>).
-
-Remember to check the modules that came with your distribution, and
-CPAN as well--someone may already have written a module to do it. On
-Windows, try L<Win32::API>. On Macs, try L<Mac::Carbon>. If no module
-has an interface to the C function, you can inline a bit of C in your
-Perl source with L<Inline::C>.
-
-=head2 Where do I get the include files to do ioctl() or syscall()?
-
-Historically, these would be generated by the L<h2ph> tool, part of the
-standard perl distribution. This program converts C<cpp(1)> directives
-in C header files to files containing subroutine definitions, like
-C<&SYS_getitimer>, which you can use as arguments to your functions.
-It doesn't work perfectly, but it usually gets most of the job done.
-Simple files like F<errno.h>, F<syscall.h>, and F<socket.h> were fine,
-but the hard ones like F<ioctl.h> nearly always need to be hand-edited.
-Here's how to install the *.ph files:
-
- 1. Become the super-user
- 2. cd /usr/include
- 3. h2ph *.h */*.h
-
-If your system supports dynamic loading, for reasons of portability and
-sanity you probably ought to use L<h2xs> (also part of the standard perl
-distribution). This tool converts C header files to Perl extensions.
-See L<perlxstut> for how to get started with L<h2xs>.
-
-If your system doesn't support dynamic loading, you still probably
-ought to use L<h2xs>. See L<perlxstut> and L<ExtUtils::MakeMaker> for
-more information (in brief, just use B<make perl> instead of a plain
-B<make> to rebuild perl with a new static extension).
-
-=head2 Why do setuid perl scripts complain about kernel problems?
-
-Some operating systems have bugs in the kernel that make setuid
-scripts inherently insecure. Perl gives you a number of options
-(described in L<perlsec>) to work around such systems.
-
-=head2 How can I open a pipe both to and from a command?
-
-The L<IPC::Open2> module (part of the standard perl distribution) is
-an easy-to-use approach that internally uses C<pipe()>, C<fork()>, and
-C<exec()> to do the job. Make sure you read the deadlock warnings in
-its documentation, though (see L<IPC::Open2>). See
-L<perlipc/"Bidirectional Communication with Another Process"> and
-L<perlipc/"Bidirectional Communication with Yourself">
-
-You may also use the L<IPC::Open3> module (part of the standard perl
-distribution), but be warned that it has a different order of
-arguments from L<IPC::Open2> (see L<IPC::Open3>).
-
-=head2 Why can't I get the output of a command with system()?
-
-You're confusing the purpose of C<system()> and backticks (``). C<system()>
-runs a command and returns exit status information (as a 16 bit value:
-the low 7 bits are the signal the process died from, if any, and
-the high 8 bits are the actual exit value). Backticks (``) run a
-command and return what it sent to STDOUT.
-
- my $exit_status = system("mail-users");
- my $output_string = `ls`;
-
-=head2 How can I capture STDERR from an external command?
-
-There are three basic ways of running external commands:
-
- system $cmd; # using system()
- my $output = `$cmd`; # using backticks (``)
- open (my $pipe_fh, "$cmd |"); # using open()
-
-With C<system()>, both STDOUT and STDERR will go the same place as the
-script's STDOUT and STDERR, unless the C<system()> command redirects them.
-Backticks and C<open()> read B<only> the STDOUT of your command.
-
-You can also use the C<open3()> function from L<IPC::Open3>. Benjamin
-Goldberg provides some sample code:
-
-To capture a program's STDOUT, but discard its STDERR:
-
- use IPC::Open3;
- use File::Spec;
- use Symbol qw(gensym);
- open(NULL, ">", File::Spec->devnull);
- my $pid = open3(gensym, \*PH, ">&NULL", "cmd");
- while( <PH> ) { }
- waitpid($pid, 0);
-
-To capture a program's STDERR, but discard its STDOUT:
-
- use IPC::Open3;
- use File::Spec;
- use Symbol qw(gensym);
- open(NULL, ">", File::Spec->devnull);
- my $pid = open3(gensym, ">&NULL", \*PH, "cmd");
- while( <PH> ) { }
- waitpid($pid, 0);
-
-To capture a program's STDERR, and let its STDOUT go to our own STDERR:
-
- use IPC::Open3;
- use Symbol qw(gensym);
- my $pid = open3(gensym, ">&STDERR", \*PH, "cmd");
- while( <PH> ) { }
- waitpid($pid, 0);
-
-To read both a command's STDOUT and its STDERR separately, you can
-redirect them to temp files, let the command run, then read the temp
-files:
-
- use IPC::Open3;
- use Symbol qw(gensym);
- use IO::File;
- local *CATCHOUT = IO::File->new_tmpfile;
- local *CATCHERR = IO::File->new_tmpfile;
- my $pid = open3(gensym, ">&CATCHOUT", ">&CATCHERR", "cmd");
- waitpid($pid, 0);
- seek $_, 0, 0 for \*CATCHOUT, \*CATCHERR;
- while( <CATCHOUT> ) {}
- while( <CATCHERR> ) {}
-
-But there's no real need for B<both> to be tempfiles... the following
-should work just as well, without deadlocking:
-
- use IPC::Open3;
- use Symbol qw(gensym);
- use IO::File;
- local *CATCHERR = IO::File->new_tmpfile;
- my $pid = open3(gensym, \*CATCHOUT, ">&CATCHERR", "cmd");
- while( <CATCHOUT> ) {}
- waitpid($pid, 0);
- seek CATCHERR, 0, 0;
- while( <CATCHERR> ) {}
-
-And it'll be faster, too, since we can begin processing the program's
-stdout immediately, rather than waiting for the program to finish.
-
-With any of these, you can change file descriptors before the call:
-
- open(STDOUT, ">logfile");
- system("ls");
-
-or you can use Bourne shell file-descriptor redirection:
-
- $output = `$cmd 2>some_file`;
- open (PIPE, "cmd 2>some_file |");
-
-You can also use file-descriptor redirection to make STDERR a
-duplicate of STDOUT:
-
- $output = `$cmd 2>&1`;
- open (PIPE, "cmd 2>&1 |");
-
-Note that you I<cannot> simply open STDERR to be a dup of STDOUT
-in your Perl program and avoid calling the shell to do the redirection.
-This doesn't work:
-
- open(STDERR, ">&STDOUT");
- $alloutput = `cmd args`; # stderr still escapes
-
-This fails because the C<open()> makes STDERR go to where STDOUT was
-going at the time of the C<open()>. The backticks then make STDOUT go to
-a string, but don't change STDERR (which still goes to the old
-STDOUT).
-
-Note that you I<must> use Bourne shell (C<sh(1)>) redirection syntax in
-backticks, not C<csh(1)>! Details on why Perl's C<system()> and backtick
-and pipe opens all use the Bourne shell are in the
-F<versus/csh.whynot> article in the "Far More Than You Ever Wanted To
-Know" collection in L<http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz> . To
-capture a command's STDERR and STDOUT together:
-
- $output = `cmd 2>&1`; # either with backticks
- $pid = open(PH, "cmd 2>&1 |"); # or with an open pipe
- while (<PH>) { } # plus a read
-
-To capture a command's STDOUT but discard its STDERR:
-
- $output = `cmd 2>/dev/null`; # either with backticks
- $pid = open(PH, "cmd 2>/dev/null |"); # or with an open pipe
- while (<PH>) { } # plus a read
-
-To capture a command's STDERR but discard its STDOUT:
-
- $output = `cmd 2>&1 1>/dev/null`; # either with backticks
- $pid = open(PH, "cmd 2>&1 1>/dev/null |"); # or with an open pipe
- while (<PH>) { } # plus a read
-
-To exchange a command's STDOUT and STDERR in order to capture the STDERR
-but leave its STDOUT to come out our old STDERR:
-
- $output = `cmd 3>&1 1>&2 2>&3 3>&-`; # either with backticks
- $pid = open(PH, "cmd 3>&1 1>&2 2>&3 3>&-|");# or with an open pipe
- while (<PH>) { } # plus a read
-
-To read both a command's STDOUT and its STDERR separately, it's easiest
-to redirect them separately to files, and then read from those files
-when the program is done:
-
- system("program args 1>program.stdout 2>program.stderr");
-
-Ordering is important in all these examples. That's because the shell
-processes file descriptor redirections in strictly left to right order.
-
- system("prog args 1>tmpfile 2>&1");
- system("prog args 2>&1 1>tmpfile");
-
-The first command sends both standard out and standard error to the
-temporary file. The second command sends only the old standard output
-there, and the old standard error shows up on the old standard out.
-
-=head2 Why doesn't open() return an error when a pipe open fails?
-
-If the second argument to a piped C<open()> contains shell
-metacharacters, perl C<fork()>s, then C<exec()>s a shell to decode the
-metacharacters and eventually run the desired program. If the program
-couldn't be run, it's the shell that gets the message, not Perl. All
-your Perl program can find out is whether the shell itself could be
-successfully started. You can still capture the shell's STDERR and
-check it for error messages. See L<"How can I capture STDERR from an
-external command?"> elsewhere in this document, or use the
-L<IPC::Open3> module.
-
-If there are no shell metacharacters in the argument of C<open()>, Perl
-runs the command directly, without using the shell, and can correctly
-report whether the command started.
-
-=head2 What's wrong with using backticks in a void context?
-
-Strictly speaking, nothing. Stylistically speaking, it's not a good
-way to write maintainable code. Perl has several operators for
-running external commands. Backticks are one; they collect the output
-from the command for use in your program. The C<system> function is
-another; it doesn't do this.
-
-Writing backticks in your program sends a clear message to the readers
-of your code that you wanted to collect the output of the command.
-Why send a clear message that isn't true?
-
-Consider this line:
-
- `cat /etc/termcap`;
-
-You forgot to check C<$?> to see whether the program even ran
-correctly. Even if you wrote
-
- print `cat /etc/termcap`;
-
-this code could and probably should be written as
-
- system("cat /etc/termcap") == 0
- or die "cat program failed!";
-
-which will echo the cat command's output as it is generated, instead
-of waiting until the program has completed to print it out. It also
-checks the return value.
-
-C<system> also provides direct control over whether shell wildcard
-processing may take place, whereas backticks do not.
-
-=head2 How can I call backticks without shell processing?
-
-This is a bit tricky. You can't simply write the command
-like this:
-
- @ok = `grep @opts '$search_string' @filenames`;
-
-As of Perl 5.8.0, you can use C<open()> with multiple arguments.
-Just like the list forms of C<system()> and C<exec()>, no shell
-escapes happen.
-
- open( GREP, "-|", 'grep', @opts, $search_string, @filenames );
- chomp(@ok = <GREP>);
- close GREP;
-
-You can also:
-
- my @ok = ();
- if (open(GREP, "-|")) {
- while (<GREP>) {
- chomp;
- push(@ok, $_);
- }
- close GREP;
- } else {
- exec 'grep', @opts, $search_string, @filenames;
- }
-
-Just as with C<system()>, no shell escapes happen when you C<exec()> a
-list. Further examples of this can be found in L<perlipc/"Safe Pipe
-Opens">.
-
-Note that if you're using Windows, no solution to this vexing issue is
-even possible. Even though Perl emulates C<fork()>, you'll still be
-stuck, because Windows does not have an argc/argv-style API.
-
-=head2 Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?
-
-This happens only if your perl is compiled to use stdio instead of
-perlio, which is the default. Some (maybe all?) stdios set error and
-eof flags that you may need to clear. The L<POSIX> module defines
-C<clearerr()> that you can use. That is the technically correct way to
-do it. Here are some less reliable workarounds:
-
-=over 4
-
-=item 1
-
-Try keeping around the seekpointer and go there, like this:
-
- my $where = tell($log_fh);
- seek($log_fh, $where, 0);
-
-=item 2
-
-If that doesn't work, try seeking to a different part of the file and
-then back.
-
-=item 3
-
-If that doesn't work, try seeking to a different part of
-the file, reading something, and then seeking back.
-
-=item 4
-
-If that doesn't work, give up on your stdio package and use sysread.
-
-=back
-
-=head2 How can I convert my shell script to perl?
-
-Learn Perl and rewrite it. Seriously, there's no simple converter.
-Things that are awkward to do in the shell are easy to do in Perl, and
-this very awkwardness is what would make a shell->perl converter
-nigh-on impossible to write. By rewriting it, you'll think about what
-you're really trying to do, and hopefully will escape the shell's
-pipeline datastream paradigm, which while convenient for some matters,
-causes many inefficiencies.
-
-=head2 Can I use perl to run a telnet or ftp session?
-
-Try the L<Net::FTP>, L<TCP::Client>, and L<Net::Telnet> modules
-(available from CPAN).
-L<http://www.cpan.org/scripts/netstuff/telnet.emul.shar> will also help
-for emulating the telnet protocol, but L<Net::Telnet> is quite
-probably easier to use.
-
-If all you want to do is pretend to be telnet but don't need
-the initial telnet handshaking, then the standard dual-process
-approach will suffice:
-
- use IO::Socket; # new in 5.004
- my $handle = IO::Socket::INET->new('www.perl.com:80')
- or die "can't connect to port 80 on www.perl.com $!";
- $handle->autoflush(1);
- if (fork()) { # XXX: undef means failure
- select($handle);
- print while <STDIN>; # everything from stdin to socket
- } else {
- print while <$handle>; # everything from socket to stdout
- }
- close $handle;
- exit;
-
-=head2 How can I write expect in Perl?
-
-Once upon a time, there was a library called F<chat2.pl> (part of the
-standard perl distribution), which never really got finished. If you
-find it somewhere, I<don't use it>. These days, your best bet is to
-look at the L<Expect> module available from CPAN, which also requires two
-other modules from CPAN, L<IO::Pty> and L<IO::Stty>.
-
-=head2 Is there a way to hide perl's command line from programs such as "ps"?
-
-First of all note that if you're doing this for security reasons (to
-avoid people seeing passwords, for example) then you should rewrite
-your program so that critical information is never given as an
-argument. Hiding the arguments won't make your program completely
-secure.
-
-To actually alter the visible command line, you can assign to the
-variable $0 as documented in L<perlvar>. This won't work on all
-operating systems, though. Daemon programs like sendmail place their
-state there, as in:
-
- $0 = "orcus [accepting connections]";
-
-=head2 I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible?
-
-=over 4
-
-=item Unix
-
-In the strictest sense, it can't be done--the script executes as a
-different process from the shell it was started from. Changes to a
-process are not reflected in its parent--only in any children
-created after the change. There is shell magic that may allow you to
-fake it by C<eval()>ing the script's output in your shell; check out the
-comp.unix.questions FAQ for details.
-
-=back
-
-=head2 How do I close a process's filehandle without waiting for it to complete?
-
-Assuming your system supports such things, just send an appropriate signal
-to the process (see L<perlfunc/"kill">). It's common to first send a TERM
-signal, wait a little bit, and then send a KILL signal to finish it off.
-
-=head2 How do I fork a daemon process?
-
-If by daemon process you mean one that's detached (disassociated from
-its tty), then the following process is reported to work on most
-Unixish systems. Non-Unix users should check their Your_OS::Process
-module for other solutions.
-
-=over 4
-
-=item *
-
-Open /dev/tty and use the TIOCNOTTY ioctl on it. See L<tty(1)>
-for details. Or better yet, you can just use the C<POSIX::setsid()>
-function, so you don't have to worry about process groups.
-
-=item *
-
-Change directory to /
-
-=item *
-
-Reopen STDIN, STDOUT, and STDERR so they're not connected to the old
-tty.
-
-=item *
-
-Background yourself like this:
-
- fork && exit;
-
-=back
-
-The L<Proc::Daemon> module, available from CPAN, provides a function to
-perform these actions for you.
-
-=head2 How do I find out if I'm running interactively or not?
-
-(contributed by brian d foy)
-
-This is a difficult question to answer, and the best answer is
-only a guess.
-
-What do you really want to know? If you merely want to know if one of
-your filehandles is connected to a terminal, you can try the C<-t>
-file test:
-
- if( -t STDOUT ) {
- print "I'm connected to a terminal!\n";
- }
-
-However, you might be out of luck if you expect that means there is a
-real person on the other side. With the L<Expect> module, another
-program can pretend to be a person. The program might even come close
-to passing the Turing test.
-
-The L<IO::Interactive> module does the best it can to give you an
-answer. Its C<is_interactive> function returns an output filehandle;
-that filehandle points to standard output if the module thinks the
-session is interactive. Otherwise, the filehandle is a null handle
-that simply discards the output:
-
- use IO::Interactive;
-
- print { is_interactive } "I might go to standard output!\n";
-
-This still doesn't guarantee that a real person is answering your
-prompts or reading your output.
-
-If you want to know how to handle automated testing for your
-distribution, you can check the environment. The CPAN
-Testers, for instance, set the value of C<AUTOMATED_TESTING>:
-
- unless( $ENV{AUTOMATED_TESTING} ) {
- print "Hello interactive tester!\n";
- }
-
-=head2 How do I timeout a slow event?
-
-Use the C<alarm()> function, probably in conjunction with a signal
-handler, as documented in L<perlipc/"Signals"> and the section on
-"Signals" in the Camel. You may instead use the more flexible
-L<Sys::AlarmCall> module available from CPAN.
-
-The C<alarm()> function is not implemented on all versions of Windows.
-Check the documentation for your specific version of Perl.
-
-=head2 How do I set CPU limits?
-X<BSD::Resource> X<limit> X<CPU>
-
-(contributed by Xho)
-
-Use the L<BSD::Resource> module from CPAN. As an example:
-
- use BSD::Resource;
- setrlimit(RLIMIT_CPU,10,20) or die $!;
-
-This sets the soft and hard limits to 10 and 20 seconds, respectively.
-After 10 seconds of time spent running on the CPU (not "wall" time),
-the process will be sent a signal (XCPU on some systems) which, if not
-trapped, will cause the process to terminate. If that signal is
-trapped, then after 10 more seconds (20 seconds in total) the process
-will be killed with a non-trappable signal.
-
-See the L<BSD::Resource> and your systems documentation for the gory
-details.
-
-=head2 How do I avoid zombies on a Unix system?
-
-Use the reaper code from L<perlipc/"Signals"> to call C<wait()> when a
-SIGCHLD is received, or else use the double-fork technique described
-in L<perlfaq8/"How do I start a process in the background?">.
-
-=head2 How do I use an SQL database?
-
-The L<DBI> module provides an abstract interface to most database
-servers and types, including Oracle, DB2, Sybase, mysql, Postgresql,
-ODBC, and flat files. The DBI module accesses each database type
-through a database driver, or DBD. You can see a complete list of
-available drivers on CPAN: L<http://www.cpan.org/modules/by-module/DBD/> .
-You can read more about DBI on L<http://dbi.perl.org/> .
-
-Other modules provide more specific access: L<Win32::ODBC>, L<Alzabo>,
-C<iodbc>, and others found on CPAN Search: L<http://search.cpan.org/> .
-
-=head2 How do I make a system() exit on control-C?
-
-You can't. You need to imitate the C<system()> call (see L<perlipc> for
-sample code) and then have a signal handler for the INT signal that
-passes the signal on to the subprocess. Or you can check for it:
-
- $rc = system($cmd);
- if ($rc & 127) { die "signal death" }
-
-=head2 How do I open a file without blocking?
-
-If you're lucky enough to be using a system that supports
-non-blocking reads (most Unixish systems do), you need only to use the
-C<O_NDELAY> or C<O_NONBLOCK> flag from the C<Fcntl> module in conjunction with
-C<sysopen()>:
-
- use Fcntl;
- sysopen(my $fh, "/foo/somefile", O_WRONLY|O_NDELAY|O_CREAT, 0644)
- or die "can't open /foo/somefile: $!":
-
-=head2 How do I tell the difference between errors from the shell and perl?
-
-(answer contributed by brian d foy)
-
-When you run a Perl script, something else is running the script for you,
-and that something else may output error messages. The script might
-emit its own warnings and error messages. Most of the time you cannot
-tell who said what.
-
-You probably cannot fix the thing that runs perl, but you can change how
-perl outputs its warnings by defining a custom warning and die functions.
-
-Consider this script, which has an error you may not notice immediately.
-
- #!/usr/locl/bin/perl
-
- print "Hello World\n";
-
-I get an error when I run this from my shell (which happens to be
-bash). That may look like perl forgot it has a C<print()> function,
-but my shebang line is not the path to perl, so the shell runs the
-script, and I get the error.
-
- $ ./test
- ./test: line 3: print: command not found
-
-A quick and dirty fix involves a little bit of code, but this may be all
-you need to figure out the problem.
-
- #!/usr/bin/perl -w
-
- BEGIN {
- $SIG{__WARN__} = sub{ print STDERR "Perl: ", @_; };
- $SIG{__DIE__} = sub{ print STDERR "Perl: ", @_; exit 1};
- }
-
- $a = 1 + undef;
- $x / 0;
- __END__
-
-The perl message comes out with "Perl" in front. The C<BEGIN> block
-works at compile time so all of the compilation errors and warnings
-get the "Perl:" prefix too.
-
- Perl: Useless use of division (/) in void context at ./test line 9.
- Perl: Name "main::a" used only once: possible typo at ./test line 8.
- Perl: Name "main::x" used only once: possible typo at ./test line 9.
- Perl: Use of uninitialized value in addition (+) at ./test line 8.
- Perl: Use of uninitialized value in division (/) at ./test line 9.
- Perl: Illegal division by zero at ./test line 9.
- Perl: Illegal division by zero at -e line 3.
-
-If I don't see that "Perl:", it's not from perl.
-
-You could also just know all the perl errors, and although there are
-some people who may know all of them, you probably don't. However, they
-all should be in the L<perldiag> manpage. If you don't find the error in
-there, it probably isn't a perl error.
-
-Looking up every message is not the easiest way, so let perl to do it
-for you. Use the diagnostics pragma with turns perl's normal messages
-into longer discussions on the topic.
-
- use diagnostics;
-
-If you don't get a paragraph or two of expanded discussion, it
-might not be perl's message.
-
-=head2 How do I install a module from CPAN?
-
-(contributed by brian d foy)
-
-The easiest way is to have a module also named CPAN do it for you by using
-the C<cpan> command that comes with Perl. You can give it a list of modules
-to install:
-
- $ cpan IO::Interactive Getopt::Whatever
-
-If you prefer C<CPANPLUS>, it's just as easy:
-
- $ cpanp i IO::Interactive Getopt::Whatever
-
-If you want to install a distribution from the current directory, you can
-tell C<CPAN.pm> to install C<.> (the full stop):
-
- $ cpan .
-
-See the documentation for either of those commands to see what else
-you can do.
-
-If you want to try to install a distribution by yourself, resolving
-all dependencies on your own, you follow one of two possible build
-paths.
-
-For distributions that use I<Makefile.PL>:
-
- $ perl Makefile.PL
- $ make test install
-
-For distributions that use I<Build.PL>:
-
- $ perl Build.PL
- $ ./Build test
- $ ./Build install
-
-Some distributions may need to link to libraries or other third-party
-code and their build and installation sequences may be more complicated.
-Check any I<README> or I<INSTALL> files that you may find.
-
-=head2 What's the difference between require and use?
-
-(contributed by brian d foy)
-
-Perl runs C<require> statement at run-time. Once Perl loads, compiles,
-and runs the file, it doesn't do anything else. The C<use> statement
-is the same as a C<require> run at compile-time, but Perl also calls the
-C<import> method for the loaded package. These two are the same:
-
- use MODULE qw(import list);
-
- BEGIN {
- require MODULE;
- MODULE->import(import list);
- }
-
-However, you can suppress the C<import> by using an explicit, empty
-import list. Both of these still happen at compile-time:
-
- use MODULE ();
-
- BEGIN {
- require MODULE;
- }
-
-Since C<use> will also call the C<import> method, the actual value
-for C<MODULE> must be a bareword. That is, C<use> cannot load files
-by name, although C<require> can:
-
- require "$ENV{HOME}/lib/Foo.pm"; # no @INC searching!
-
-See the entry for C<use> in L<perlfunc> for more details.
-
-=head2 How do I keep my own module/library directory?
-
-When you build modules, tell Perl where to install the modules.
-
-If you want to install modules for your own use, the easiest way might
-be L<local::lib>, which you can download from CPAN. It sets various
-installation settings for you, and uses those same settings within
-your programs.
-
-If you want more flexibility, you need to configure your CPAN client
-for your particular situation.
-
-For C<Makefile.PL>-based distributions, use the INSTALL_BASE option
-when generating Makefiles:
-
- perl Makefile.PL INSTALL_BASE=/mydir/perl
-
-You can set this in your C<CPAN.pm> configuration so modules
-automatically install in your private library directory when you use
-the CPAN.pm shell:
-
- % cpan
- cpan> o conf makepl_arg INSTALL_BASE=/mydir/perl
- cpan> o conf commit
-
-For C<Build.PL>-based distributions, use the --install_base option:
-
- perl Build.PL --install_base /mydir/perl
-
-You can configure C<CPAN.pm> to automatically use this option too:
-
- % cpan
- cpan> o conf mbuild_arg "--install_base /mydir/perl"
- cpan> o conf commit
-
-INSTALL_BASE tells these tools to put your modules into
-F</mydir/perl/lib/perl5>. See L<How do I add a directory to my
-include path (@INC) at runtime?> for details on how to run your newly
-installed modules.
-
-There is one caveat with INSTALL_BASE, though, since it acts
-differently from the PREFIX and LIB settings that older versions of
-L<ExtUtils::MakeMaker> advocated. INSTALL_BASE does not support
-installing modules for multiple versions of Perl or different
-architectures under the same directory. You should consider whether you
-really want that and, if you do, use the older PREFIX and LIB
-settings. See the L<ExtUtils::Makemaker> documentation for more details.
-
-=head2 How do I add the directory my program lives in to the module/library search path?
-
-(contributed by brian d foy)
-
-If you know the directory already, you can add it to C<@INC> as you would
-for any other directory. You might <use lib> if you know the directory
-at compile time:
-
- use lib $directory;
-
-The trick in this task is to find the directory. Before your script does
-anything else (such as a C<chdir>), you can get the current working
-directory with the C<Cwd> module, which comes with Perl:
-
- BEGIN {
- use Cwd;
- our $directory = cwd;
- }
-
- use lib $directory;
-
-You can do a similar thing with the value of C<$0>, which holds the
-script name. That might hold a relative path, but C<rel2abs> can turn
-it into an absolute path. Once you have the
-
- BEGIN {
- use File::Spec::Functions qw(rel2abs);
- use File::Basename qw(dirname);
-
- my $path = rel2abs( $0 );
- our $directory = dirname( $path );
- }
-
- use lib $directory;
-
-The L<FindBin> module, which comes with Perl, might work. It finds the
-directory of the currently running script and puts it in C<$Bin>, which
-you can then use to construct the right library path:
-
- use FindBin qw($Bin);
-
-You can also use L<local::lib> to do much of the same thing. Install
-modules using L<local::lib>'s settings then use the module in your
-program:
-
- use local::lib; # sets up a local lib at ~/perl5
-
-See the L<local::lib> documentation for more details.
-
-=head2 How do I add a directory to my include path (@INC) at runtime?
-
-Here are the suggested ways of modifying your include path, including
-environment variables, run-time switches, and in-code statements:
-
-=over 4
-
-=item the C<PERLLIB> environment variable
-
- $ export PERLLIB=/path/to/my/dir
- $ perl program.pl
-
-=item the C<PERL5LIB> environment variable
-
- $ export PERL5LIB=/path/to/my/dir
- $ perl program.pl
-
-=item the C<perl -Idir> command line flag
-
- $ perl -I/path/to/my/dir program.pl
-
-=item the C<lib> pragma:
-
- use lib "$ENV{HOME}/myown_perllib";
-
-=item the L<local::lib> module:
-
- use local::lib;
-
- use local::lib "~/myown_perllib";
-
-=back
-
-The last is particularly useful because it knows about machine-dependent
-architectures. The C<lib.pm> pragmatic module was first
-included with the 5.002 release of Perl.
-
-=head2 What is socket.ph and where do I get it?
-
-It's a Perl 4 style file defining values for system networking
-constants. Sometimes it is built using L<h2ph> when Perl is installed,
-but other times it is not. Modern programs should use C<use Socket;>
-instead.
-
-=head1 AUTHOR AND COPYRIGHT
-
-Copyright (c) 1997-2010 Tom Christiansen, Nathan Torkington, and
-other authors as noted. All rights reserved.
-
-This documentation is free; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-Irrespective of its distribution, all code examples in this file
-are hereby placed into the public domain. You are permitted and
-encouraged to use this code in your own programs for fun
-or for profit as you see fit. A simple comment in the code giving
-credit would be courteous but is not required.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq9.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq9.pod
deleted file mode 100644
index b42755efe0a..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlfaq9.pod
+++ /dev/null
@@ -1,426 +0,0 @@
-=head1 NAME
-
-perlfaq9 - Web, Email and Networking
-
-=head1 DESCRIPTION
-
-This section deals with questions related to running web sites,
-sending and receiving email as well as general networking.
-
-=head2 Should I use a web framework?
-
-Yes. If you are building a web site with any level of interactivity
-(forms / users / databases), you
-will want to use a framework to make handling requests
-and responses easier.
-
-If there is no interactivity then you may still want
-to look at using something like L<Template Toolkit|https://metacpan.org/module/Template>
-or L<Plack::Middleware::TemplateToolkit>
-so maintenance of your HTML files (and other assets) is easier.
-
-=head2 Which web framework should I use?
-X<framework> X<CGI.pm> X<CGI> X<Catalyst> X<Dancer>
-
-There is no simple answer to this question. Perl frameworks can run everything
-from basic file servers and small scale intranets to massive multinational
-multilingual websites that are the core to international businesses.
-
-Below is a list of a few frameworks with comments which might help you in
-making a decision, depending on your specific requirements. Start by reading
-the docs, then ask questions on the relevant mailing list or IRC channel.
-
-=over 4
-
-=item L<Catalyst>
-
-Strongly object-oriented and fully-featured with a long development history and
-a large community and addon ecosystem. It is excellent for large and complex
-applications, where you have full control over the server.
-
-=item L<Dancer>
-
-Young and free of legacy weight, providing a lightweight and easy to learn API.
-Has a growing addon ecosystem. It is best used for smaller projects and
-very easy to learn for beginners.
-
-=item L<Mojolicious>
-
-Fairly young with a focus on HTML5 and real-time web technologies such as
-WebSockets.
-
-=item L<Web::Simple>
-
-Currently experimental, strongly object-oriented, built for speed and intended
-as a toolkit for building micro web apps, custom frameworks or for tieing
-together existing Plack-compatible web applications with one central dispatcher.
-
-=back
-
-All of these interact with or use L<Plack> which is worth understanding
-the basics of when building a website in Perl (there is a lot of useful
-L<Plack::Middleware|https://metacpan.org/search?q=plack%3A%3Amiddleware>).
-
-=head2 What is Plack and PSGI?
-
-L<PSGI> is the Perl Web Server Gateway Interface Specification, it is
-a standard that many Perl web frameworks use, you should not need to
-understand it to build a web site, the part you might want to use is L<Plack>.
-
-L<Plack> is a set of tools for using the PSGI stack. It contains
-L<middleware|https://metacpan.org/search?q=plack%3A%3Amiddleware>
-components, a reference server and utilities for Web application frameworks.
-Plack is like Ruby's Rack or Python's Paste for WSGI.
-
-You could build a web site using L<Plack> and your own code,
-but for anything other than a very basic web site, using a web framework
-(that uses L<Plack>) is a better option.
-
-=head2 How do I remove HTML from a string?
-
-Use L<HTML::Strip>, or L<HTML::FormatText> which not only removes HTML
-but also attempts to do a little simple formatting of the resulting
-plain text.
-
-=head2 How do I extract URLs?
-
-L<HTML::SimpleLinkExtor> will extract URLs from HTML, it handles anchors,
-images, objects, frames, and many other tags that can contain a URL.
-If you need anything more complex, you can create your own subclass of
-L<HTML::LinkExtor> or L<HTML::Parser>. You might even use
-L<HTML::SimpleLinkExtor> as an example for something specifically
-suited to your needs.
-
-You can use L<URI::Find> to extract URLs from an arbitrary text document.
-
-=head2 How do I fetch an HTML file?
-
-(contributed by brian d foy)
-
-Use the libwww-perl distribution. The L<LWP::Simple> module can fetch web
-resources and give their content back to you as a string:
-
- use LWP::Simple qw(get);
-
- my $html = get( "http://www.example.com/index.html" );
-
-It can also store the resource directly in a file:
-
- use LWP::Simple qw(getstore);
-
- getstore( "http://www.example.com/index.html", "foo.html" );
-
-If you need to do something more complicated, you can use
-L<LWP::UserAgent> module to create your own user-agent (e.g. browser)
-to get the job done. If you want to simulate an interactive web
-browser, you can use the L<WWW::Mechanize> module.
-
-=head2 How do I automate an HTML form submission?
-
-If you are doing something complex, such as moving through many pages
-and forms or a web site, you can use L<WWW::Mechanize>. See its
-documentation for all the details.
-
-If you're submitting values using the GET method, create a URL and encode
-the form using the C<query_form> method:
-
- use LWP::Simple;
- use URI::URL;
-
- my $url = url('L<http://www.perl.com/cgi-bin/cpan_mod')>;
- $url->query_form(module => 'DB_File', readme => 1);
- $content = get($url);
-
-If you're using the POST method, create your own user agent and encode
-the content appropriately.
-
- use HTTP::Request::Common qw(POST);
- use LWP::UserAgent;
-
- my $ua = LWP::UserAgent->new();
- my $req = POST 'L<http://www.perl.com/cgi-bin/cpan_mod'>,
- [ module => 'DB_File', readme => 1 ];
- my $content = $ua->request($req)->as_string;
-
-=head2 How do I decode or create those %-encodings on the web?
-X<URI> X<URI::Escape> X<RFC 2396>
-
-Most of the time you should not need to do this as
-your web framework, or if you are making a request,
-the L<LWP> or other module would handle it for you.
-
-To encode a string yourself, use the L<URI::Escape> module. The C<uri_escape>
-function returns the escaped string:
-
- my $original = "Colon : Hash # Percent %";
-
- my $escaped = uri_escape( $original );
-
- print "$escaped\n"; # 'Colon%20%3A%20Hash%20%23%20Percent%20%25'
-
-To decode the string, use the C<uri_unescape> function:
-
- my $unescaped = uri_unescape( $escaped );
-
- print $unescaped; # back to original
-
-Remember not to encode a full URI, you need to escape each
-component separately and then join them together.
-
-=head2 How do I redirect to another page?
-
-Most Perl Web Frameworks will have a mechanism for doing this,
-using the L<Catalyst> framework it would be:
-
- $c->res->redirect($url);
- $c->detach();
-
-If you are using Plack (which most frameworks do), then
-L<Plack::Middleware::Rewrite> is worth looking at if you
-are migrating from Apache or have URL's you want to always
-redirect.
-
-=head2 How do I put a password on my web pages?
-
-See if the web framework you are using has an
-authentication system and if that fits your needs.
-
-Alternativly look at L<Plack::Middleware::Auth::Basic>,
-or one of the other L<Plack authentication|https://metacpan.org/search?q=plack+auth>
-options.
-
-=head2 How do I make sure users can't enter values into a form that causes my CGI script to do bad things?
-
-(contributed by brian d foy)
-
-You can't prevent people from sending your script bad data. Even if
-you add some client-side checks, people may disable them or bypass
-them completely. For instance, someone might use a module such as
-L<LWP> to submit to your web site. If you want to prevent data that
-try to use SQL injection or other sorts of attacks (and you should
-want to), you have to not trust any data that enter your program.
-
-The L<perlsec> documentation has general advice about data security.
-If you are using the L<DBI> module, use placeholder to fill in data.
-If you are running external programs with C<system> or C<exec>, use
-the list forms. There are many other precautions that you should take,
-too many to list here, and most of them fall under the category of not
-using any data that you don't intend to use. Trust no one.
-
-=head2 How do I parse a mail header?
-
-Use the L<Email::MIME> module. It's well-tested and supports all the
-craziness that you'll see in the real world (comment-folding whitespace,
-encodings, comments, etc.).
-
- use Email::MIME;
-
- my $message = Email::MIME->new($rfc2822);
- my $subject = $message->header('Subject');
- my $from = $message->header('From');
-
-If you've already got some other kind of email object, consider passing
-it to L<Email::Abstract> and then using its cast method to get an
-L<Email::MIME> object:
-
- my $mail_message_object = read_message();
- my $abstract = Email::Abstract->new($mail_message_object);
- my $email_mime_object = $abstract->cast('Email::MIME');
-
-=head2 How do I check a valid mail address?
-
-(partly contributed by Aaron Sherman)
-
-This isn't as simple a question as it sounds. There are two parts:
-
-a) How do I verify that an email address is correctly formatted?
-
-b) How do I verify that an email address targets a valid recipient?
-
-Without sending mail to the address and seeing whether there's a human
-on the other end to answer you, you cannot fully answer part I<b>, but
-the L<Email::Valid> module will do both part I<a> and part I<b> as far
-as you can in real-time.
-
-Our best advice for verifying a person's mail address is to have them
-enter their address twice, just as you normally do to change a
-password. This usually weeds out typos. If both versions match, send
-mail to that address with a personal message. If you get the message
-back and they've followed your directions, you can be reasonably
-assured that it's real.
-
-A related strategy that's less open to forgery is to give them a PIN
-(personal ID number). Record the address and PIN (best that it be a
-random one) for later processing. In the mail you send, include a link to
-your site with the PIN included. If the mail bounces, you know it's not
-valid. If they don't click on the link, either they forged the address or
-(assuming they got the message) following through wasn't important so you
-don't need to worry about it.
-
-=head2 How do I decode a MIME/BASE64 string?
-
-The L<MIME::Base64> package handles this as well as the MIME/QP encoding.
-Decoding base 64 becomes as simple as:
-
- use MIME::Base64;
- my $decoded = decode_base64($encoded);
-
-The L<Email::MIME> module can decode base 64-encoded email message parts
-transparently so the developer doesn't need to worry about it.
-
-=head2 How do I find the user's mail address?
-
-Ask them for it. There are so many email providers available that it's
-unlikely the local system has any idea how to determine a user's email address.
-
-The exception is for organization-specific email (e.g. foo@yourcompany.com)
-where policy can be codified in your program. In that case, you could look at
-$ENV{USER}, $ENV{LOGNAME}, and getpwuid($<) in scalar context, like so:
-
- my $user_name = getpwuid($<)
-
-But you still cannot make assumptions about whether this is correct, unless
-your policy says it is. You really are best off asking the user.
-
-=head2 How do I send email?
-
-Use the L<Email::MIME> and L<Email::Sender::Simple> modules, like so:
-
- # first, create your message
- my $message = Email::MIME->create(
- header_str => [
- From => 'you@example.com',
- To => 'friend@example.com',
- Subject => 'Happy birthday!',
- ],
- attributes => {
- encoding => 'quoted-printable',
- charset => 'ISO-8859-1',
- },
- body_str => "Happy birthday to you!\n",
- );
-
- use Email::Sender::Simple qw(sendmail);
- sendmail($message);
-
-By default, L<Email::Sender::Simple> will try `sendmail` first, if it exists
-in your $PATH. This generally isn't the case. If there's a remote mail
-server you use to send mail, consider investigating one of the Transport
-classes. At time of writing, the available transports include:
-
-=over 4
-
-=item L<Email::Sender::Transport::Sendmail>
-
-This is the default. If you can use the L<mail(1)> or L<mailx(1)>
-program to send mail from the machine where your code runs, you should
-be able to use this.
-
-=item L<Email::Sender::Transport::SMTP>
-
-This transport contacts a remote SMTP server over TCP. It optionally
-uses SSL and can authenticate to the server via SASL.
-
-=item L<Email::Sender::Transport::SMTP::TLS>
-
-This is like the SMTP transport, but uses TLS security. You can
-authenticate with this module as well, using any mechanisms your server
-supports after STARTTLS.
-
-=back
-
-Telling L<Email::Sender::Simple> to use your transport is straightforward.
-
- sendmail(
- $message,
- {
- transport => $email_sender_transport_object,
- }
- );
-
-=head2 How do I use MIME to make an attachment to a mail message?
-
-L<Email::MIME> directly supports multipart messages. L<Email::MIME>
-objects themselves are parts and can be attached to other L<Email::MIME>
-objects. Consult the L<Email::MIME> documentation for more information,
-including all of the supported methods and examples of their use.
-
-=head2 How do I read email?
-
-Use the L<Email::Folder> module, like so:
-
- use Email::Folder;
-
- my $folder = Email::Folder->new('/path/to/email/folder');
- while(my $message = $folder->next_message) {
- # next_message returns Email::Simple objects, but we want
- # Email::MIME objects as they're more robust
- my $mime = Email::MIME->new($message->as_string);
- }
-
-There are different classes in the L<Email::Folder> namespace for
-supporting various mailbox types. Note that these modules are generally
-rather limited and only support B<reading> rather than writing.
-
-=head2 How do I find out my hostname, domainname, or IP address?
-X<hostname, domainname, IP address, host, domain, hostfqdn, inet_ntoa,
-gethostbyname, Socket, Net::Domain, Sys::Hostname>
-
-(contributed by brian d foy)
-
-The L<Net::Domain> module, which is part of the Standard Library starting
-in Perl 5.7.3, can get you the fully qualified domain name (FQDN), the host
-name, or the domain name.
-
- use Net::Domain qw(hostname hostfqdn hostdomain);
-
- my $host = hostfqdn();
-
-The L<Sys::Hostname> module, part of the Standard Library, can also get the
-hostname:
-
- use Sys::Hostname;
-
- $host = hostname();
-
-
-The L<Sys::Hostname::Long> module takes a different approach and tries
-harder to return the fully qualified hostname:
-
- use Sys::Hostname::Long 'hostname_long';
-
- my $hostname = hostname_long();
-
-To get the IP address, you can use the C<gethostbyname> built-in function
-to turn the name into a number. To turn that number into the dotted octet
-form (a.b.c.d) that most people expect, use the C<inet_ntoa> function
-from the L<Socket> module, which also comes with perl.
-
- use Socket;
-
- my $address = inet_ntoa(
- scalar gethostbyname( $host || 'localhost' )
- );
-
-=head2 How do I fetch/put an (S)FTP file?
-
-L<Net::FTP>, and L<Net::SFTP> allow you to interact with FTP and SFTP (Secure
-FTP) servers.
-
-=head2 How can I do RPC in Perl?
-
-Use one of the RPC modules( L<https://metacpan.org/search?q=RPC> ).
-
-=head1 AUTHOR AND COPYRIGHT
-
-Copyright (c) 1997-2010 Tom Christiansen, Nathan Torkington, and
-other authors as noted. All rights reserved.
-
-This documentation is free; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-Irrespective of its distribution, all code examples in this file
-are hereby placed into the public domain. You are permitted and
-encouraged to use this code in your own programs for fun
-or for profit as you see fit. A simple comment in the code giving
-credit would be courteous but is not required.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlfilter.pod b/Master/tlpkg/tlperl/lib/pods/perlfilter.pod
deleted file mode 100644
index 27061883c1f..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlfilter.pod
+++ /dev/null
@@ -1,587 +0,0 @@
-=head1 NAME
-
-perlfilter - Source Filters
-
-=head1 DESCRIPTION
-
-This article is about a little-known feature of Perl called
-I<source filters>. Source filters alter the program text of a module
-before Perl sees it, much as a C preprocessor alters the source text of
-a C program before the compiler sees it. This article tells you more
-about what source filters are, how they work, and how to write your
-own.
-
-The original purpose of source filters was to let you encrypt your
-program source to prevent casual piracy. This isn't all they can do, as
-you'll soon learn. But first, the basics.
-
-=head1 CONCEPTS
-
-Before the Perl interpreter can execute a Perl script, it must first
-read it from a file into memory for parsing and compilation. If that
-script itself includes other scripts with a C<use> or C<require>
-statement, then each of those scripts will have to be read from their
-respective files as well.
-
-Now think of each logical connection between the Perl parser and an
-individual file as a I<source stream>. A source stream is created when
-the Perl parser opens a file, it continues to exist as the source code
-is read into memory, and it is destroyed when Perl is finished parsing
-the file. If the parser encounters a C<require> or C<use> statement in
-a source stream, a new and distinct stream is created just for that
-file.
-
-The diagram below represents a single source stream, with the flow of
-source from a Perl script file on the left into the Perl parser on the
-right. This is how Perl normally operates.
-
- file -------> parser
-
-There are two important points to remember:
-
-=over 5
-
-=item 1.
-
-Although there can be any number of source streams in existence at any
-given time, only one will be active.
-
-=item 2.
-
-Every source stream is associated with only one file.
-
-=back
-
-A source filter is a special kind of Perl module that intercepts and
-modifies a source stream before it reaches the parser. A source filter
-changes our diagram like this:
-
- file ----> filter ----> parser
-
-If that doesn't make much sense, consider the analogy of a command
-pipeline. Say you have a shell script stored in the compressed file
-I<trial.gz>. The simple pipeline command below runs the script without
-needing to create a temporary file to hold the uncompressed file.
-
- gunzip -c trial.gz | sh
-
-In this case, the data flow from the pipeline can be represented as follows:
-
- trial.gz ----> gunzip ----> sh
-
-With source filters, you can store the text of your script compressed and use a source filter to uncompress it for Perl's parser:
-
- compressed gunzip
- Perl program ---> source filter ---> parser
-
-=head1 USING FILTERS
-
-So how do you use a source filter in a Perl script? Above, I said that
-a source filter is just a special kind of module. Like all Perl
-modules, a source filter is invoked with a use statement.
-
-Say you want to pass your Perl source through the C preprocessor before
-execution. As it happens, the source filters distribution comes with a C
-preprocessor filter module called Filter::cpp.
-
-Below is an example program, C<cpp_test>, which makes use of this filter.
-Line numbers have been added to allow specific lines to be referenced
-easily.
-
- 1: use Filter::cpp;
- 2: #define TRUE 1
- 3: $a = TRUE;
- 4: print "a = $a\n";
-
-When you execute this script, Perl creates a source stream for the
-file. Before the parser processes any of the lines from the file, the
-source stream looks like this:
-
- cpp_test ---------> parser
-
-Line 1, C<use Filter::cpp>, includes and installs the C<cpp> filter
-module. All source filters work this way. The use statement is compiled
-and executed at compile time, before any more of the file is read, and
-it attaches the cpp filter to the source stream behind the scenes. Now
-the data flow looks like this:
-
- cpp_test ----> cpp filter ----> parser
-
-As the parser reads the second and subsequent lines from the source
-stream, it feeds those lines through the C<cpp> source filter before
-processing them. The C<cpp> filter simply passes each line through the
-real C preprocessor. The output from the C preprocessor is then
-inserted back into the source stream by the filter.
-
- .-> cpp --.
- | |
- | |
- | <-'
- cpp_test ----> cpp filter ----> parser
-
-The parser then sees the following code:
-
- use Filter::cpp;
- $a = 1;
- print "a = $a\n";
-
-Let's consider what happens when the filtered code includes another
-module with use:
-
- 1: use Filter::cpp;
- 2: #define TRUE 1
- 3: use Fred;
- 4: $a = TRUE;
- 5: print "a = $a\n";
-
-The C<cpp> filter does not apply to the text of the Fred module, only
-to the text of the file that used it (C<cpp_test>). Although the use
-statement on line 3 will pass through the cpp filter, the module that
-gets included (C<Fred>) will not. The source streams look like this
-after line 3 has been parsed and before line 4 is parsed:
-
- cpp_test ---> cpp filter ---> parser (INACTIVE)
-
- Fred.pm ----> parser
-
-As you can see, a new stream has been created for reading the source
-from C<Fred.pm>. This stream will remain active until all of C<Fred.pm>
-has been parsed. The source stream for C<cpp_test> will still exist,
-but is inactive. Once the parser has finished reading Fred.pm, the
-source stream associated with it will be destroyed. The source stream
-for C<cpp_test> then becomes active again and the parser reads line 4
-and subsequent lines from C<cpp_test>.
-
-You can use more than one source filter on a single file. Similarly,
-you can reuse the same filter in as many files as you like.
-
-For example, if you have a uuencoded and compressed source file, it is
-possible to stack a uudecode filter and an uncompression filter like
-this:
-
- use Filter::uudecode; use Filter::uncompress;
- M'XL(".H<US4''V9I;F%L')Q;>7/;1I;_>_I3=&E=%:F*I"T?22Q/
- M6]9*<IQCO*XFT"0[PL%%'Y+IG?WN^ZYN-$'J.[.JE$,20/?K=_[>
- ...
-
-Once the first line has been processed, the flow will look like this:
-
- file ---> uudecode ---> uncompress ---> parser
- filter filter
-
-Data flows through filters in the same order they appear in the source
-file. The uudecode filter appeared before the uncompress filter, so the
-source file will be uudecoded before it's uncompressed.
-
-=head1 WRITING A SOURCE FILTER
-
-There are three ways to write your own source filter. You can write it
-in C, use an external program as a filter, or write the filter in Perl.
-I won't cover the first two in any great detail, so I'll get them out
-of the way first. Writing the filter in Perl is most convenient, so
-I'll devote the most space to it.
-
-=head1 WRITING A SOURCE FILTER IN C
-
-The first of the three available techniques is to write the filter
-completely in C. The external module you create interfaces directly
-with the source filter hooks provided by Perl.
-
-The advantage of this technique is that you have complete control over
-the implementation of your filter. The big disadvantage is the
-increased complexity required to write the filter - not only do you
-need to understand the source filter hooks, but you also need a
-reasonable knowledge of Perl guts. One of the few times it is worth
-going to this trouble is when writing a source scrambler. The
-C<decrypt> filter (which unscrambles the source before Perl parses it)
-included with the source filter distribution is an example of a C
-source filter (see Decryption Filters, below).
-
-
-=over 5
-
-=item B<Decryption Filters>
-
-All decryption filters work on the principle of "security through
-obscurity." Regardless of how well you write a decryption filter and
-how strong your encryption algorithm is, anyone determined enough can
-retrieve the original source code. The reason is quite simple - once
-the decryption filter has decrypted the source back to its original
-form, fragments of it will be stored in the computer's memory as Perl
-parses it. The source might only be in memory for a short period of
-time, but anyone possessing a debugger, skill, and lots of patience can
-eventually reconstruct your program.
-
-That said, there are a number of steps that can be taken to make life
-difficult for the potential cracker. The most important: Write your
-decryption filter in C and statically link the decryption module into
-the Perl binary. For further tips to make life difficult for the
-potential cracker, see the file I<decrypt.pm> in the source filters
-distribution.
-
-=back
-
-=head1 CREATING A SOURCE FILTER AS A SEPARATE EXECUTABLE
-
-An alternative to writing the filter in C is to create a separate
-executable in the language of your choice. The separate executable
-reads from standard input, does whatever processing is necessary, and
-writes the filtered data to standard output. C<Filter::cpp> is an
-example of a source filter implemented as a separate executable - the
-executable is the C preprocessor bundled with your C compiler.
-
-The source filter distribution includes two modules that simplify this
-task: C<Filter::exec> and C<Filter::sh>. Both allow you to run any
-external executable. Both use a coprocess to control the flow of data
-into and out of the external executable. (For details on coprocesses,
-see Stephens, W.R., "Advanced Programming in the UNIX Environment."
-Addison-Wesley, ISBN 0-210-56317-7, pages 441-445.) The difference
-between them is that C<Filter::exec> spawns the external command
-directly, while C<Filter::sh> spawns a shell to execute the external
-command. (Unix uses the Bourne shell; NT uses the cmd shell.) Spawning
-a shell allows you to make use of the shell metacharacters and
-redirection facilities.
-
-Here is an example script that uses C<Filter::sh>:
-
- use Filter::sh 'tr XYZ PQR';
- $a = 1;
- print "XYZ a = $a\n";
-
-The output you'll get when the script is executed:
-
- PQR a = 1
-
-Writing a source filter as a separate executable works fine, but a
-small performance penalty is incurred. For example, if you execute the
-small example above, a separate subprocess will be created to run the
-Unix C<tr> command. Each use of the filter requires its own subprocess.
-If creating subprocesses is expensive on your system, you might want to
-consider one of the other options for creating source filters.
-
-=head1 WRITING A SOURCE FILTER IN PERL
-
-The easiest and most portable option available for creating your own
-source filter is to write it completely in Perl. To distinguish this
-from the previous two techniques, I'll call it a Perl source filter.
-
-To help understand how to write a Perl source filter we need an example
-to study. Here is a complete source filter that performs rot13
-decoding. (Rot13 is a very simple encryption scheme used in Usenet
-postings to hide the contents of offensive posts. It moves every letter
-forward thirteen places, so that A becomes N, B becomes O, and Z
-becomes M.)
-
-
- package Rot13;
-
- use Filter::Util::Call;
-
- sub import {
- my ($type) = @_;
- my ($ref) = [];
- filter_add(bless $ref);
- }
-
- sub filter {
- my ($self) = @_;
- my ($status);
-
- tr/n-za-mN-ZA-M/a-zA-Z/
- if ($status = filter_read()) > 0;
- $status;
- }
-
- 1;
-
-All Perl source filters are implemented as Perl classes and have the
-same basic structure as the example above.
-
-First, we include the C<Filter::Util::Call> module, which exports a
-number of functions into your filter's namespace. The filter shown
-above uses two of these functions, C<filter_add()> and
-C<filter_read()>.
-
-Next, we create the filter object and associate it with the source
-stream by defining the C<import> function. If you know Perl well
-enough, you know that C<import> is called automatically every time a
-module is included with a use statement. This makes C<import> the ideal
-place to both create and install a filter object.
-
-In the example filter, the object (C<$ref>) is blessed just like any
-other Perl object. Our example uses an anonymous array, but this isn't
-a requirement. Because this example doesn't need to store any context
-information, we could have used a scalar or hash reference just as
-well. The next section demonstrates context data.
-
-The association between the filter object and the source stream is made
-with the C<filter_add()> function. This takes a filter object as a
-parameter (C<$ref> in this case) and installs it in the source stream.
-
-Finally, there is the code that actually does the filtering. For this
-type of Perl source filter, all the filtering is done in a method
-called C<filter()>. (It is also possible to write a Perl source filter
-using a closure. See the C<Filter::Util::Call> manual page for more
-details.) It's called every time the Perl parser needs another line of
-source to process. The C<filter()> method, in turn, reads lines from
-the source stream using the C<filter_read()> function.
-
-If a line was available from the source stream, C<filter_read()>
-returns a status value greater than zero and appends the line to C<$_>.
-A status value of zero indicates end-of-file, less than zero means an
-error. The filter function itself is expected to return its status in
-the same way, and put the filtered line it wants written to the source
-stream in C<$_>. The use of C<$_> accounts for the brevity of most Perl
-source filters.
-
-In order to make use of the rot13 filter we need some way of encoding
-the source file in rot13 format. The script below, C<mkrot13>, does
-just that.
-
- die "usage mkrot13 filename\n" unless @ARGV;
- my $in = $ARGV[0];
- my $out = "$in.tmp";
- open(IN, "<$in") or die "Cannot open file $in: $!\n";
- open(OUT, ">$out") or die "Cannot open file $out: $!\n";
-
- print OUT "use Rot13;\n";
- while (<IN>) {
- tr/a-zA-Z/n-za-mN-ZA-M/;
- print OUT;
- }
-
- close IN;
- close OUT;
- unlink $in;
- rename $out, $in;
-
-If we encrypt this with C<mkrot13>:
-
- print " hello fred \n";
-
-the result will be this:
-
- use Rot13;
- cevag "uryyb serq\a";
-
-Running it produces this output:
-
- hello fred
-
-=head1 USING CONTEXT: THE DEBUG FILTER
-
-The rot13 example was a trivial example. Here's another demonstration
-that shows off a few more features.
-
-Say you wanted to include a lot of debugging code in your Perl script
-during development, but you didn't want it available in the released
-product. Source filters offer a solution. In order to keep the example
-simple, let's say you wanted the debugging output to be controlled by
-an environment variable, C<DEBUG>. Debugging code is enabled if the
-variable exists, otherwise it is disabled.
-
-Two special marker lines will bracket debugging code, like this:
-
- ## DEBUG_BEGIN
- if ($year > 1999) {
- warn "Debug: millennium bug in year $year\n";
- }
- ## DEBUG_END
-
-The filter ensures that Perl parses the code between the <DEBUG_BEGIN>
-and C<DEBUG_END> markers only when the C<DEBUG> environment variable
-exists. That means that when C<DEBUG> does exist, the code above
-should be passed through the filter unchanged. The marker lines can
-also be passed through as-is, because the Perl parser will see them as
-comment lines. When C<DEBUG> isn't set, we need a way to disable the
-debug code. A simple way to achieve that is to convert the lines
-between the two markers into comments:
-
- ## DEBUG_BEGIN
- #if ($year > 1999) {
- # warn "Debug: millennium bug in year $year\n";
- #}
- ## DEBUG_END
-
-Here is the complete Debug filter:
-
- package Debug;
-
- use strict;
- use warnings;
- use Filter::Util::Call;
-
- use constant TRUE => 1;
- use constant FALSE => 0;
-
- sub import {
- my ($type) = @_;
- my (%context) = (
- Enabled => defined $ENV{DEBUG},
- InTraceBlock => FALSE,
- Filename => (caller)[1],
- LineNo => 0,
- LastBegin => 0,
- );
- filter_add(bless \%context);
- }
-
- sub Die {
- my ($self) = shift;
- my ($message) = shift;
- my ($line_no) = shift || $self->{LastBegin};
- die "$message at $self->{Filename} line $line_no.\n"
- }
-
- sub filter {
- my ($self) = @_;
- my ($status);
- $status = filter_read();
- ++ $self->{LineNo};
-
- # deal with EOF/error first
- if ($status <= 0) {
- $self->Die("DEBUG_BEGIN has no DEBUG_END")
- if $self->{InTraceBlock};
- return $status;
- }
-
- if ($self->{InTraceBlock}) {
- if (/^\s*##\s*DEBUG_BEGIN/ ) {
- $self->Die("Nested DEBUG_BEGIN", $self->{LineNo})
- } elsif (/^\s*##\s*DEBUG_END/) {
- $self->{InTraceBlock} = FALSE;
- }
-
- # comment out the debug lines when the filter is disabled
- s/^/#/ if ! $self->{Enabled};
- } elsif ( /^\s*##\s*DEBUG_BEGIN/ ) {
- $self->{InTraceBlock} = TRUE;
- $self->{LastBegin} = $self->{LineNo};
- } elsif ( /^\s*##\s*DEBUG_END/ ) {
- $self->Die("DEBUG_END has no DEBUG_BEGIN", $self->{LineNo});
- }
- return $status;
- }
-
- 1;
-
-The big difference between this filter and the previous example is the
-use of context data in the filter object. The filter object is based on
-a hash reference, and is used to keep various pieces of context
-information between calls to the filter function. All but two of the
-hash fields are used for error reporting. The first of those two,
-Enabled, is used by the filter to determine whether the debugging code
-should be given to the Perl parser. The second, InTraceBlock, is true
-when the filter has encountered a C<DEBUG_BEGIN> line, but has not yet
-encountered the following C<DEBUG_END> line.
-
-If you ignore all the error checking that most of the code does, the
-essence of the filter is as follows:
-
- sub filter {
- my ($self) = @_;
- my ($status);
- $status = filter_read();
-
- # deal with EOF/error first
- return $status if $status <= 0;
- if ($self->{InTraceBlock}) {
- if (/^\s*##\s*DEBUG_END/) {
- $self->{InTraceBlock} = FALSE
- }
-
- # comment out debug lines when the filter is disabled
- s/^/#/ if ! $self->{Enabled};
- } elsif ( /^\s*##\s*DEBUG_BEGIN/ ) {
- $self->{InTraceBlock} = TRUE;
- }
- return $status;
- }
-
-Be warned: just as the C-preprocessor doesn't know C, the Debug filter
-doesn't know Perl. It can be fooled quite easily:
-
- print <<EOM;
- ##DEBUG_BEGIN
- EOM
-
-Such things aside, you can see that a lot can be achieved with a modest
-amount of code.
-
-=head1 CONCLUSION
-
-You now have better understanding of what a source filter is, and you
-might even have a possible use for them. If you feel like playing with
-source filters but need a bit of inspiration, here are some extra
-features you could add to the Debug filter.
-
-First, an easy one. Rather than having debugging code that is
-all-or-nothing, it would be much more useful to be able to control
-which specific blocks of debugging code get included. Try extending the
-syntax for debug blocks to allow each to be identified. The contents of
-the C<DEBUG> environment variable can then be used to control which
-blocks get included.
-
-Once you can identify individual blocks, try allowing them to be
-nested. That isn't difficult either.
-
-Here is an interesting idea that doesn't involve the Debug filter.
-Currently Perl subroutines have fairly limited support for formal
-parameter lists. You can specify the number of parameters and their
-type, but you still have to manually take them out of the C<@_> array
-yourself. Write a source filter that allows you to have a named
-parameter list. Such a filter would turn this:
-
- sub MySub ($first, $second, @rest) { ... }
-
-into this:
-
- sub MySub($$@) {
- my ($first) = shift;
- my ($second) = shift;
- my (@rest) = @_;
- ...
- }
-
-Finally, if you feel like a real challenge, have a go at writing a
-full-blown Perl macro preprocessor as a source filter. Borrow the
-useful features from the C preprocessor and any other macro processors
-you know. The tricky bit will be choosing how much knowledge of Perl's
-syntax you want your filter to have.
-
-=head1 THINGS TO LOOK OUT FOR
-
-=over 5
-
-=item Some Filters Clobber the C<DATA> Handle
-
-Some source filters use the C<DATA> handle to read the calling program.
-When using these source filters you cannot rely on this handle, nor expect
-any particular kind of behavior when operating on it. Filters based on
-Filter::Util::Call (and therefore Filter::Simple) do not alter the C<DATA>
-filehandle.
-
-=back
-
-=head1 REQUIREMENTS
-
-The Source Filters distribution is available on CPAN, in
-
- CPAN/modules/by-module/Filter
-
-Starting from Perl 5.8 Filter::Util::Call (the core part of the
-Source Filters distribution) is part of the standard Perl distribution.
-Also included is a friendlier interface called Filter::Simple, by
-Damian Conway.
-
-=head1 AUTHOR
-
-Paul Marquess E<lt>Paul.Marquess@btinternet.comE<gt>
-
-=head1 Copyrights
-
-This article originally appeared in The Perl Journal #11, and is
-copyright 1998 The Perl Journal. It appears courtesy of Jon Orwant and
-The Perl Journal. This document may be distributed under the same terms
-as Perl itself.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlfork.pod b/Master/tlpkg/tlperl/lib/pods/perlfork.pod
deleted file mode 100644
index 7729444c40b..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlfork.pod
+++ /dev/null
@@ -1,357 +0,0 @@
-=head1 NAME
-
-perlfork - Perl's fork() emulation
-
-=head1 SYNOPSIS
-
- NOTE: As of the 5.8.0 release, fork() emulation has considerably
- matured. However, there are still a few known bugs and differences
- from real fork() that might affect you. See the "BUGS" and
- "CAVEATS AND LIMITATIONS" sections below.
-
-Perl provides a fork() keyword that corresponds to the Unix system call
-of the same name. On most Unix-like platforms where the fork() system
-call is available, Perl's fork() simply calls it.
-
-On some platforms such as Windows where the fork() system call is not
-available, Perl can be built to emulate fork() at the interpreter level.
-While the emulation is designed to be as compatible as possible with the
-real fork() at the level of the Perl program, there are certain
-important differences that stem from the fact that all the pseudo child
-"processes" created this way live in the same real process as far as the
-operating system is concerned.
-
-This document provides a general overview of the capabilities and
-limitations of the fork() emulation. Note that the issues discussed here
-are not applicable to platforms where a real fork() is available and Perl
-has been configured to use it.
-
-=head1 DESCRIPTION
-
-The fork() emulation is implemented at the level of the Perl interpreter.
-What this means in general is that running fork() will actually clone the
-running interpreter and all its state, and run the cloned interpreter in
-a separate thread, beginning execution in the new thread just after the
-point where the fork() was called in the parent. We will refer to the
-thread that implements this child "process" as the pseudo-process.
-
-To the Perl program that called fork(), all this is designed to be
-transparent. The parent returns from the fork() with a pseudo-process
-ID that can be subsequently used in any process-manipulation functions;
-the child returns from the fork() with a value of C<0> to signify that
-it is the child pseudo-process.
-
-=head2 Behavior of other Perl features in forked pseudo-processes
-
-Most Perl features behave in a natural way within pseudo-processes.
-
-=over 8
-
-=item $$ or $PROCESS_ID
-
-This special variable is correctly set to the pseudo-process ID.
-It can be used to identify pseudo-processes within a particular
-session. Note that this value is subject to recycling if any
-pseudo-processes are launched after others have been wait()-ed on.
-
-=item %ENV
-
-Each pseudo-process maintains its own virtual environment. Modifications
-to %ENV affect the virtual environment, and are only visible within that
-pseudo-process, and in any processes (or pseudo-processes) launched from
-it.
-
-=item chdir() and all other builtins that accept filenames
-
-Each pseudo-process maintains its own virtual idea of the current directory.
-Modifications to the current directory using chdir() are only visible within
-that pseudo-process, and in any processes (or pseudo-processes) launched from
-it. All file and directory accesses from the pseudo-process will correctly
-map the virtual working directory to the real working directory appropriately.
-
-=item wait() and waitpid()
-
-wait() and waitpid() can be passed a pseudo-process ID returned by fork().
-These calls will properly wait for the termination of the pseudo-process
-and return its status.
-
-=item kill()
-
-C<kill('KILL', ...)> can be used to terminate a pseudo-process by
-passing it the ID returned by fork(). The outcome of kill on a pseudo-process
-is unpredictable and it should not be used except
-under dire circumstances, because the operating system may not
-guarantee integrity of the process resources when a running thread is
-terminated. The process which implements the pseudo-processes can be blocked
-and the Perl interpreter hangs. Note that using C<kill('KILL', ...)> on a
-pseudo-process() may typically cause memory leaks, because the thread
-that implements the pseudo-process does not get a chance to clean up
-its resources.
-
-C<kill('TERM', ...)> can also be used on pseudo-processes, but the
-signal will not be delivered while the pseudo-process is blocked by a
-system call, e.g. waiting for a socket to connect, or trying to read
-from a socket with no data available. Starting in Perl 5.14 the
-parent process will not wait for children to exit once they have been
-signalled with C<kill('TERM', ...)> to avoid deadlock during process
-exit. You will have to explicitly call waitpid() to make sure the
-child has time to clean-up itself, but you are then also responsible
-that the child is not blocking on I/O either.
-
-=item exec()
-
-Calling exec() within a pseudo-process actually spawns the requested
-executable in a separate process and waits for it to complete before
-exiting with the same exit status as that process. This means that the
-process ID reported within the running executable will be different from
-what the earlier Perl fork() might have returned. Similarly, any process
-manipulation functions applied to the ID returned by fork() will affect the
-waiting pseudo-process that called exec(), not the real process it is
-waiting for after the exec().
-
-When exec() is called inside a pseudo-process then DESTROY methods and
-END blocks will still be called after the external process returns.
-
-=item exit()
-
-exit() always exits just the executing pseudo-process, after automatically
-wait()-ing for any outstanding child pseudo-processes. Note that this means
-that the process as a whole will not exit unless all running pseudo-processes
-have exited. See below for some limitations with open filehandles.
-
-=item Open handles to files, directories and network sockets
-
-All open handles are dup()-ed in pseudo-processes, so that closing
-any handles in one process does not affect the others. See below for
-some limitations.
-
-=back
-
-=head2 Resource limits
-
-In the eyes of the operating system, pseudo-processes created via the fork()
-emulation are simply threads in the same process. This means that any
-process-level limits imposed by the operating system apply to all
-pseudo-processes taken together. This includes any limits imposed by the
-operating system on the number of open file, directory and socket handles,
-limits on disk space usage, limits on memory size, limits on CPU utilization
-etc.
-
-=head2 Killing the parent process
-
-If the parent process is killed (either using Perl's kill() builtin, or
-using some external means) all the pseudo-processes are killed as well,
-and the whole process exits.
-
-=head2 Lifetime of the parent process and pseudo-processes
-
-During the normal course of events, the parent process and every
-pseudo-process started by it will wait for their respective pseudo-children
-to complete before they exit. This means that the parent and every
-pseudo-child created by it that is also a pseudo-parent will only exit
-after their pseudo-children have exited.
-
-Starting with Perl 5.14 a parent will not wait() automatically
-for any child that has been signalled with C<sig('TERM', ...)>
-to avoid a deadlock in case the child is blocking on I/O and
-never receives the signal.
-
-=head1 CAVEATS AND LIMITATIONS
-
-=over 8
-
-=item BEGIN blocks
-
-The fork() emulation will not work entirely correctly when called from
-within a BEGIN block. The forked copy will run the contents of the
-BEGIN block, but will not continue parsing the source stream after the
-BEGIN block. For example, consider the following code:
-
- BEGIN {
- fork and exit; # fork child and exit the parent
- print "inner\n";
- }
- print "outer\n";
-
-This will print:
-
- inner
-
-rather than the expected:
-
- inner
- outer
-
-This limitation arises from fundamental technical difficulties in
-cloning and restarting the stacks used by the Perl parser in the
-middle of a parse.
-
-=item Open filehandles
-
-Any filehandles open at the time of the fork() will be dup()-ed. Thus,
-the files can be closed independently in the parent and child, but beware
-that the dup()-ed handles will still share the same seek pointer. Changing
-the seek position in the parent will change it in the child and vice-versa.
-One can avoid this by opening files that need distinct seek pointers
-separately in the child.
-
-On some operating systems, notably Solaris and Unixware, calling C<exit()>
-from a child process will flush and close open filehandles in the parent,
-thereby corrupting the filehandles. On these systems, calling C<_exit()>
-is suggested instead. C<_exit()> is available in Perl through the
-C<POSIX> module. Please consult your system's manpages for more information
-on this.
-
-=item Open directory handles
-
-Perl will completely read from all open directory handles until they
-reach the end of the stream. It will then seekdir() back to the
-original location and all future readdir() requests will be fulfilled
-from the cache buffer. That means that neither the directory handle held
-by the parent process nor the one held by the child process will see
-any changes made to the directory after the fork() call.
-
-Note that rewinddir() has a similar limitation on Windows and will not
-force readdir() to read the directory again either. Only a newly
-opened directory handle will reflect changes to the directory.
-
-=item Forking pipe open() not yet implemented
-
-The C<open(FOO, "|-")> and C<open(BAR, "-|")> constructs are not yet
-implemented. This limitation can be easily worked around in new code
-by creating a pipe explicitly. The following example shows how to
-write to a forked child:
-
- # simulate open(FOO, "|-")
- sub pipe_to_fork ($) {
- my $parent = shift;
- pipe my $child, $parent or die;
- my $pid = fork();
- die "fork() failed: $!" unless defined $pid;
- if ($pid) {
- close $child;
- }
- else {
- close $parent;
- open(STDIN, "<&=" . fileno($child)) or die;
- }
- $pid;
- }
-
- if (pipe_to_fork('FOO')) {
- # parent
- print FOO "pipe_to_fork\n";
- close FOO;
- }
- else {
- # child
- while (<STDIN>) { print; }
- exit(0);
- }
-
-And this one reads from the child:
-
- # simulate open(FOO, "-|")
- sub pipe_from_fork ($) {
- my $parent = shift;
- pipe $parent, my $child or die;
- my $pid = fork();
- die "fork() failed: $!" unless defined $pid;
- if ($pid) {
- close $child;
- }
- else {
- close $parent;
- open(STDOUT, ">&=" . fileno($child)) or die;
- }
- $pid;
- }
-
- if (pipe_from_fork('BAR')) {
- # parent
- while (<BAR>) { print; }
- close BAR;
- }
- else {
- # child
- print "pipe_from_fork\n";
- exit(0);
- }
-
-Forking pipe open() constructs will be supported in future.
-
-=item Global state maintained by XSUBs
-
-External subroutines (XSUBs) that maintain their own global state may
-not work correctly. Such XSUBs will either need to maintain locks to
-protect simultaneous access to global data from different pseudo-processes,
-or maintain all their state on the Perl symbol table, which is copied
-naturally when fork() is called. A callback mechanism that provides
-extensions an opportunity to clone their state will be provided in the
-near future.
-
-=item Interpreter embedded in larger application
-
-The fork() emulation may not behave as expected when it is executed in an
-application which embeds a Perl interpreter and calls Perl APIs that can
-evaluate bits of Perl code. This stems from the fact that the emulation
-only has knowledge about the Perl interpreter's own data structures and
-knows nothing about the containing application's state. For example, any
-state carried on the application's own call stack is out of reach.
-
-=item Thread-safety of extensions
-
-Since the fork() emulation runs code in multiple threads, extensions
-calling into non-thread-safe libraries may not work reliably when
-calling fork(). As Perl's threading support gradually becomes more
-widely adopted even on platforms with a native fork(), such extensions
-are expected to be fixed for thread-safety.
-
-=back
-
-=head1 PORTABILITY CAVEATS
-
-In portable Perl code, C<kill(9, $child)> must not be used on forked processes.
-Killing a forked process is unsafe and has unpredictable results.
-See L</kill()>, above.
-
-=head1 BUGS
-
-=over 8
-
-=item *
-
-Having pseudo-process IDs be negative integers breaks down for the integer
-C<-1> because the wait() and waitpid() functions treat this number as
-being special. The tacit assumption in the current implementation is that
-the system never allocates a thread ID of C<1> for user threads. A better
-representation for pseudo-process IDs will be implemented in future.
-
-=item *
-
-In certain cases, the OS-level handles created by the pipe(), socket(),
-and accept() operators are apparently not duplicated accurately in
-pseudo-processes. This only happens in some situations, but where it
-does happen, it may result in deadlocks between the read and write ends
-of pipe handles, or inability to send or receive data across socket
-handles.
-
-=item *
-
-This document may be incomplete in some respects.
-
-=back
-
-=head1 AUTHOR
-
-Support for concurrent interpreters and the fork() emulation was implemented
-by ActiveState, with funding from Microsoft Corporation.
-
-This document is authored and maintained by Gurusamy Sarathy
-E<lt>gsar@activestate.comE<gt>.
-
-=head1 SEE ALSO
-
-L<perlfunc/"fork">, L<perlipc>
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlform.pod b/Master/tlpkg/tlperl/lib/pods/perlform.pod
deleted file mode 100644
index b00d394296e..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlform.pod
+++ /dev/null
@@ -1,455 +0,0 @@
-=head1 NAME
-X<format> X<report> X<chart>
-
-perlform - Perl formats
-
-=head1 DESCRIPTION
-
-Perl has a mechanism to help you generate simple reports and charts. To
-facilitate this, Perl helps you code up your output page close to how it
-will look when it's printed. It can keep track of things like how many
-lines are on a page, what page you're on, when to print page headers,
-etc. Keywords are borrowed from FORTRAN: format() to declare and write()
-to execute; see their entries in L<perlfunc>. Fortunately, the layout is
-much more legible, more like BASIC's PRINT USING statement. Think of it
-as a poor man's nroff(1).
-X<nroff>
-
-Formats, like packages and subroutines, are declared rather than
-executed, so they may occur at any point in your program. (Usually it's
-best to keep them all together though.) They have their own namespace
-apart from all the other "types" in Perl. This means that if you have a
-function named "Foo", it is not the same thing as having a format named
-"Foo". However, the default name for the format associated with a given
-filehandle is the same as the name of the filehandle. Thus, the default
-format for STDOUT is named "STDOUT", and the default format for filehandle
-TEMP is named "TEMP". They just look the same. They aren't.
-
-Output record formats are declared as follows:
-
- format NAME =
- FORMLIST
- .
-
-If the name is omitted, format "STDOUT" is defined. A single "." in
-column 1 is used to terminate a format. FORMLIST consists of a sequence
-of lines, each of which may be one of three types:
-
-=over 4
-
-=item 1.
-
-A comment, indicated by putting a '#' in the first column.
-
-=item 2.
-
-A "picture" line giving the format for one output line.
-
-=item 3.
-
-An argument line supplying values to plug into the previous picture line.
-
-=back
-
-Picture lines contain output field definitions, intermingled with
-literal text. These lines do not undergo any kind of variable interpolation.
-Field definitions are made up from a set of characters, for starting and
-extending a field to its desired width. This is the complete set of
-characters for field definitions:
-X<format, picture line>
-X<@> X<^> X<< < >> X<< | >> X<< > >> X<#> X<0> X<.> X<...>
-X<@*> X<^*> X<~> X<~~>
-
- @ start of regular field
- ^ start of special field
- < pad character for left justification
- | pad character for centering
- > pad character for right justification
- # pad character for a right-justified numeric field
- 0 instead of first #: pad number with leading zeroes
- . decimal point within a numeric field
- ... terminate a text field, show "..." as truncation evidence
- @* variable width field for a multi-line value
- ^* variable width field for next line of a multi-line value
- ~ suppress line with all fields empty
- ~~ repeat line until all fields are exhausted
-
-Each field in a picture line starts with either "@" (at) or "^" (caret),
-indicating what we'll call, respectively, a "regular" or "special" field.
-The choice of pad characters determines whether a field is textual or
-numeric. The tilde operators are not part of a field. Let's look at
-the various possibilities in detail.
-
-
-=head2 Text Fields
-X<format, text field>
-
-The length of the field is supplied by padding out the field with multiple
-"E<lt>", "E<gt>", or "|" characters to specify a non-numeric field with,
-respectively, left justification, right justification, or centering.
-For a regular field, the value (up to the first newline) is taken and
-printed according to the selected justification, truncating excess characters.
-If you terminate a text field with "...", three dots will be shown if
-the value is truncated. A special text field may be used to do rudimentary
-multi-line text block filling; see L</Using Fill Mode> for details.
-
- Example:
- format STDOUT =
- @<<<<<< @|||||| @>>>>>>
- "left", "middle", "right"
- .
- Output:
- left middle right
-
-
-=head2 Numeric Fields
-X<#> X<format, numeric field>
-
-Using "#" as a padding character specifies a numeric field, with
-right justification. An optional "." defines the position of the
-decimal point. With a "0" (zero) instead of the first "#", the
-formatted number will be padded with leading zeroes if necessary.
-A special numeric field is blanked out if the value is undefined.
-If the resulting value would exceed the width specified the field is
-filled with "#" as overflow evidence.
-
- Example:
- format STDOUT =
- @### @.### @##.### @### @### ^####
- 42, 3.1415, undef, 0, 10000, undef
- .
- Output:
- 42 3.142 0.000 0 ####
-
-
-=head2 The Field @* for Variable-Width Multi-Line Text
-X<@*>
-
-The field "@*" can be used for printing multi-line, nontruncated
-values; it should (but need not) appear by itself on a line. A final
-line feed is chomped off, but all other characters are emitted verbatim.
-
-
-=head2 The Field ^* for Variable-Width One-line-at-a-time Text
-X<^*>
-
-Like "@*", this is a variable-width field. The value supplied must be a
-scalar variable. Perl puts the first line (up to the first "\n") of the
-text into the field, and then chops off the front of the string so that
-the next time the variable is referenced, more of the text can be printed.
-The variable will I<not> be restored.
-
- Example:
- $text = "line 1\nline 2\nline 3";
- format STDOUT =
- Text: ^*
- $text
- ~~ ^*
- $text
- .
- Output:
- Text: line 1
- line 2
- line 3
-
-
-=head2 Specifying Values
-X<format, specifying values>
-
-The values are specified on the following format line in the same order as
-the picture fields. The expressions providing the values must be
-separated by commas. They are all evaluated in a list context
-before the line is processed, so a single list expression could produce
-multiple list elements. The expressions may be spread out to more than
-one line if enclosed in braces. If so, the opening brace must be the first
-token on the first line. If an expression evaluates to a number with a
-decimal part, and if the corresponding picture specifies that the decimal
-part should appear in the output (that is, any picture except multiple "#"
-characters B<without> an embedded "."), the character used for the decimal
-point is determined by the current LC_NUMERIC locale if C<use locale> is in
-effect. This means that, if, for example, the run-time environment happens
-to specify a German locale, "," will be used instead of the default ".". See
-L<perllocale> and L<"WARNINGS"> for more information.
-
-
-=head2 Using Fill Mode
-X<format, fill mode>
-
-On text fields the caret enables a kind of fill mode. Instead of an
-arbitrary expression, the value supplied must be a scalar variable
-that contains a text string. Perl puts the next portion of the text into
-the field, and then chops off the front of the string so that the next time
-the variable is referenced, more of the text can be printed. (Yes, this
-means that the variable itself is altered during execution of the write()
-call, and is not restored.) The next portion of text is determined by
-a crude line-breaking algorithm. You may use the carriage return character
-(C<\r>) to force a line break. You can change which characters are legal
-to break on by changing the variable C<$:> (that's
-$FORMAT_LINE_BREAK_CHARACTERS if you're using the English module) to a
-list of the desired characters.
-
-Normally you would use a sequence of fields in a vertical stack associated
-with the same scalar variable to print out a block of text. You might wish
-to end the final field with the text "...", which will appear in the output
-if the text was too long to appear in its entirety.
-
-
-=head2 Suppressing Lines Where All Fields Are Void
-X<format, suppressing lines>
-
-Using caret fields can produce lines where all fields are blank. You can
-suppress such lines by putting a "~" (tilde) character anywhere in the
-line. The tilde will be translated to a space upon output.
-
-
-=head2 Repeating Format Lines
-X<format, repeating lines>
-
-If you put two contiguous tilde characters "~~" anywhere into a line,
-the line will be repeated until all the fields on the line are exhausted,
-i.e. undefined. For special (caret) text fields this will occur sooner or
-later, but if you use a text field of the at variety, the expression you
-supply had better not give the same value every time forever! (C<shift(@f)>
-is a simple example that would work.) Don't use a regular (at) numeric
-field in such lines, because it will never go blank.
-
-
-=head2 Top of Form Processing
-X<format, top of form> X<top> X<header>
-
-Top-of-form processing is by default handled by a format with the
-same name as the current filehandle with "_TOP" concatenated to it.
-It's triggered at the top of each page. See L<perlfunc/write>.
-
-Examples:
-
- # a report on the /etc/passwd file
- format STDOUT_TOP =
- Passwd File
- Name Login Office Uid Gid Home
- ------------------------------------------------------------------
- .
- format STDOUT =
- @<<<<<<<<<<<<<<<<<< @||||||| @<<<<<<@>>>> @>>>> @<<<<<<<<<<<<<<<<<
- $name, $login, $office,$uid,$gid, $home
- .
-
-
- # a report from a bug report form
- format STDOUT_TOP =
- Bug Reports
- @<<<<<<<<<<<<<<<<<<<<<<< @||| @>>>>>>>>>>>>>>>>>>>>>>>
- $system, $%, $date
- ------------------------------------------------------------------
- .
- format STDOUT =
- Subject: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $subject
- Index: @<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $index, $description
- Priority: @<<<<<<<<<< Date: @<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $priority, $date, $description
- From: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $from, $description
- Assigned to: @<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $programmer, $description
- ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $description
- ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $description
- ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $description
- ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $description
- ~ ^<<<<<<<<<<<<<<<<<<<<<<<...
- $description
- .
-
-It is possible to intermix print()s with write()s on the same output
-channel, but you'll have to handle C<$-> (C<$FORMAT_LINES_LEFT>)
-yourself.
-
-=head2 Format Variables
-X<format variables>
-X<format, variables>
-
-The current format name is stored in the variable C<$~> (C<$FORMAT_NAME>),
-and the current top of form format name is in C<$^> (C<$FORMAT_TOP_NAME>).
-The current output page number is stored in C<$%> (C<$FORMAT_PAGE_NUMBER>),
-and the number of lines on the page is in C<$=> (C<$FORMAT_LINES_PER_PAGE>).
-Whether to autoflush output on this handle is stored in C<$|>
-(C<$OUTPUT_AUTOFLUSH>). The string output before each top of page (except
-the first) is stored in C<$^L> (C<$FORMAT_FORMFEED>). These variables are
-set on a per-filehandle basis, so you'll need to select() into a different
-one to affect them:
-
- select((select(OUTF),
- $~ = "My_Other_Format",
- $^ = "My_Top_Format"
- )[0]);
-
-Pretty ugly, eh? It's a common idiom though, so don't be too surprised
-when you see it. You can at least use a temporary variable to hold
-the previous filehandle: (this is a much better approach in general,
-because not only does legibility improve, you now have an intermediary
-stage in the expression to single-step the debugger through):
-
- $ofh = select(OUTF);
- $~ = "My_Other_Format";
- $^ = "My_Top_Format";
- select($ofh);
-
-If you use the English module, you can even read the variable names:
-
- use English '-no_match_vars';
- $ofh = select(OUTF);
- $FORMAT_NAME = "My_Other_Format";
- $FORMAT_TOP_NAME = "My_Top_Format";
- select($ofh);
-
-But you still have those funny select()s. So just use the FileHandle
-module. Now, you can access these special variables using lowercase
-method names instead:
-
- use FileHandle;
- format_name OUTF "My_Other_Format";
- format_top_name OUTF "My_Top_Format";
-
-Much better!
-
-=head1 NOTES
-
-Because the values line may contain arbitrary expressions (for at fields,
-not caret fields), you can farm out more sophisticated processing
-to other functions, like sprintf() or one of your own. For example:
-
- format Ident =
- @<<<<<<<<<<<<<<<
- &commify($n)
- .
-
-To get a real at or caret into the field, do this:
-
- format Ident =
- I have an @ here.
- "@"
- .
-
-To center a whole line of text, do something like this:
-
- format Ident =
- @|||||||||||||||||||||||||||||||||||||||||||||||
- "Some text line"
- .
-
-There is no builtin way to say "float this to the right hand side
-of the page, however wide it is." You have to specify where it goes.
-The truly desperate can generate their own format on the fly, based
-on the current number of columns, and then eval() it:
-
- $format = "format STDOUT = \n"
- . '^' . '<' x $cols . "\n"
- . '$entry' . "\n"
- . "\t^" . "<" x ($cols-8) . "~~\n"
- . '$entry' . "\n"
- . ".\n";
- print $format if $Debugging;
- eval $format;
- die $@ if $@;
-
-Which would generate a format looking something like this:
-
- format STDOUT =
- ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $entry
- ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~
- $entry
- .
-
-Here's a little program that's somewhat like fmt(1):
-
- format =
- ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~
- $_
-
- .
-
- $/ = '';
- while (<>) {
- s/\s*\n\s*/ /g;
- write;
- }
-
-=head2 Footers
-X<format, footer> X<footer>
-
-While $FORMAT_TOP_NAME contains the name of the current header format,
-there is no corresponding mechanism to automatically do the same thing
-for a footer. Not knowing how big a format is going to be until you
-evaluate it is one of the major problems. It's on the TODO list.
-
-Here's one strategy: If you have a fixed-size footer, you can get footers
-by checking $FORMAT_LINES_LEFT before each write() and print the footer
-yourself if necessary.
-
-Here's another strategy: Open a pipe to yourself, using C<open(MYSELF, "|-")>
-(see L<perlfunc/open>) and always write() to MYSELF instead of STDOUT.
-Have your child process massage its STDIN to rearrange headers and footers
-however you like. Not very convenient, but doable.
-
-=head2 Accessing Formatting Internals
-X<format, internals>
-
-For low-level access to the formatting mechanism. you may use formline()
-and access C<$^A> (the $ACCUMULATOR variable) directly.
-
-For example:
-
- $str = formline <<'END', 1,2,3;
- @<<< @||| @>>>
- END
-
- print "Wow, I just stored '$^A' in the accumulator!\n";
-
-Or to make an swrite() subroutine, which is to write() what sprintf()
-is to printf(), do this:
-
- use Carp;
- sub swrite {
- croak "usage: swrite PICTURE ARGS" unless @_;
- my $format = shift;
- $^A = "";
- formline($format,@_);
- return $^A;
- }
-
- $string = swrite(<<'END', 1, 2, 3);
- Check me out
- @<<< @||| @>>>
- END
- print $string;
-
-=head1 WARNINGS
-
-The lone dot that ends a format can also prematurely end a mail
-message passing through a misconfigured Internet mailer (and based on
-experience, such misconfiguration is the rule, not the exception). So
-when sending format code through mail, you should indent it so that
-the format-ending dot is not on the left margin; this will prevent
-SMTP cutoff.
-
-Lexical variables (declared with "my") are not visible within a
-format unless the format is declared within the scope of the lexical
-variable. (They weren't visible at all before version 5.001.)
-
-If a program's environment specifies an LC_NUMERIC locale and C<use
-locale> is in effect when the format is declared, the locale is used
-to specify the decimal point character in formatted output. Formatted
-output cannot be controlled by C<use locale> at the time when write()
-is called. See L<perllocale> for further discussion of locale handling.
-
-Within strings that are to be displayed in a fixed-length text field,
-each control character is substituted by a space. (But remember the
-special meaning of C<\r> when using fill mode.) This is done to avoid
-misalignment when control characters "disappear" on some output media.
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlfreebsd.pod b/Master/tlpkg/tlperl/lib/pods/perlfreebsd.pod
deleted file mode 100644
index 4bfe9741373..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlfreebsd.pod
+++ /dev/null
@@ -1,40 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see pod/perlpod.pod) which is
-specifically designed to be readable as is.
-
-=head1 NAME
-
-perlfreebsd - Perl version 5 on FreeBSD systems
-
-=head1 DESCRIPTION
-
-This document describes various features of FreeBSD that will affect how Perl
-version 5 (hereafter just Perl) is compiled and/or runs.
-
-=head2 FreeBSD core dumps from readdir_r with ithreads
-
-When perl is configured to use ithreads, it will use re-entrant library calls
-in preference to non-re-entrant versions. There is a bug in FreeBSD's
-C<readdir_r> function in versions 4.5 and earlier that can cause a SEGV when
-reading large directories. A patch for FreeBSD libc is available
-(see http://www.freebsd.org/cgi/query-pr.cgi?pr=misc/30631 )
-which has been integrated into FreeBSD 4.6.
-
-=head2 $^X doesn't always contain a full path in FreeBSD
-
-perl sets C<$^X> where possible to a full path by asking the operating
-system. On FreeBSD the full path of the perl interpreter is found by using
-C<sysctl> with C<KERN_PROC_PATHNAME> if that is supported, else by reading
-the symlink F</proc/curproc/file>. FreeBSD 7 and earlier has a bug where
-either approach sometimes returns an incorrect value
-(see http://www.freebsd.org/cgi/query-pr.cgi?pr=35703 ).
-In these cases perl will fall back to the old behaviour of using C's
-argv[0] value for C<$^X>.
-
-=head1 AUTHOR
-
-Nicholas Clark <nick@ccl4.org>, collating wisdom supplied by Slaven Rezic
-and Tim Bunce.
-
-Please report any errors, updates, or suggestions to F<perlbug@perl.org>.
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlfunc.pod b/Master/tlpkg/tlperl/lib/pods/perlfunc.pod
deleted file mode 100644
index c9307f342fc..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlfunc.pod
+++ /dev/null
@@ -1,9088 +0,0 @@
-=head1 NAME
-X<function>
-
-perlfunc - Perl builtin functions
-
-=head1 DESCRIPTION
-
-The functions in this section can serve as terms in an expression.
-They fall into two major categories: list operators and named unary
-operators. These differ in their precedence relationship with a
-following comma. (See the precedence table in L<perlop>.) List
-operators take more than one argument, while unary operators can never
-take more than one argument. Thus, a comma terminates the argument of
-a unary operator, but merely separates the arguments of a list
-operator. A unary operator generally provides scalar context to its
-argument, while a list operator may provide either scalar or list
-contexts for its arguments. If it does both, scalar arguments
-come first and list argument follow, and there can only ever
-be one such list argument. For instance, splice() has three scalar
-arguments followed by a list, whereas gethostbyname() has four scalar
-arguments.
-
-In the syntax descriptions that follow, list operators that expect a
-list (and provide list context for elements of the list) are shown
-with LIST as an argument. Such a list may consist of any combination
-of scalar arguments or list values; the list values will be included
-in the list as if each individual element were interpolated at that
-point in the list, forming a longer single-dimensional list value.
-Commas should separate literal elements of the LIST.
-
-Any function in the list below may be used either with or without
-parentheses around its arguments. (The syntax descriptions omit the
-parentheses.) If you use parentheses, the simple but occasionally
-surprising rule is this: It I<looks> like a function, therefore it I<is> a
-function, and precedence doesn't matter. Otherwise it's a list
-operator or unary operator, and precedence does matter. Whitespace
-between the function and left parenthesis doesn't count, so sometimes
-you need to be careful:
-
- print 1+2+4; # Prints 7.
- print(1+2) + 4; # Prints 3.
- print (1+2)+4; # Also prints 3!
- print +(1+2)+4; # Prints 7.
- print ((1+2)+4); # Prints 7.
-
-If you run Perl with the B<-w> switch it can warn you about this. For
-example, the third line above produces:
-
- print (...) interpreted as function at - line 1.
- Useless use of integer addition in void context at - line 1.
-
-A few functions take no arguments at all, and therefore work as neither
-unary nor list operators. These include such functions as C<time>
-and C<endpwent>. For example, C<time+86_400> always means
-C<time() + 86_400>.
-
-For functions that can be used in either a scalar or list context,
-nonabortive failure is generally indicated in scalar context by
-returning the undefined value, and in list context by returning the
-empty list.
-
-Remember the following important rule: There is B<no rule> that relates
-the behavior of an expression in list context to its behavior in scalar
-context, or vice versa. It might do two totally different things.
-Each operator and function decides which sort of value would be most
-appropriate to return in scalar context. Some operators return the
-length of the list that would have been returned in list context. Some
-operators return the first value in the list. Some operators return the
-last value in the list. Some operators return a count of successful
-operations. In general, they do what you want, unless you want
-consistency.
-X<context>
-
-A named array in scalar context is quite different from what would at
-first glance appear to be a list in scalar context. You can't get a list
-like C<(1,2,3)> into being in scalar context, because the compiler knows
-the context at compile time. It would generate the scalar comma operator
-there, not the list construction version of the comma. That means it
-was never a list to start with.
-
-In general, functions in Perl that serve as wrappers for system calls ("syscalls")
-of the same name (like chown(2), fork(2), closedir(2), etc.) return
-true when they succeed and C<undef> otherwise, as is usually mentioned
-in the descriptions below. This is different from the C interfaces,
-which return C<-1> on failure. Exceptions to this rule include C<wait>,
-C<waitpid>, and C<syscall>. System calls also set the special C<$!>
-variable on failure. Other functions do not, except accidentally.
-
-Extension modules can also hook into the Perl parser to define new
-kinds of keyword-headed expression. These may look like functions, but
-may also look completely different. The syntax following the keyword
-is defined entirely by the extension. If you are an implementor, see
-L<perlapi/PL_keyword_plugin> for the mechanism. If you are using such
-a module, see the module's documentation for details of the syntax that
-it defines.
-
-=head2 Perl Functions by Category
-X<function>
-
-Here are Perl's functions (including things that look like
-functions, like some keywords and named operators)
-arranged by category. Some functions appear in more
-than one place.
-
-=over 4
-
-=item Functions for SCALARs or strings
-X<scalar> X<string> X<character>
-
-=for Pod::Functions =String
-
-C<chomp>, C<chop>, C<chr>, C<crypt>, C<fc>, C<hex>, C<index>, C<lc>,
-C<lcfirst>, C<length>, C<oct>, C<ord>, C<pack>, C<q//>, C<qq//>, C<reverse>,
-C<rindex>, C<sprintf>, C<substr>, C<tr///>, C<uc>, C<ucfirst>, C<y///>
-
-C<fc> is available only if the C<"fc"> feature is enabled or if it is
-prefixed with C<CORE::>. The C<"fc"> feature is enabled automatically
-with a C<use v5.16> (or higher) declaration in the current scope.
-
-
-=item Regular expressions and pattern matching
-X<regular expression> X<regex> X<regexp>
-
-=for Pod::Functions =Regexp
-
-C<m//>, C<pos>, C<qr//>, C<quotemeta>, C<s///>, C<split>, C<study>
-
-=item Numeric functions
-X<numeric> X<number> X<trigonometric> X<trigonometry>
-
-=for Pod::Functions =Math
-
-C<abs>, C<atan2>, C<cos>, C<exp>, C<hex>, C<int>, C<log>, C<oct>, C<rand>,
-C<sin>, C<sqrt>, C<srand>
-
-=item Functions for real @ARRAYs
-X<array>
-
-=for Pod::Functions =ARRAY
-
-C<each>, C<keys>, C<pop>, C<push>, C<shift>, C<splice>, C<unshift>, C<values>
-
-=item Functions for list data
-X<list>
-
-=for Pod::Functions =LIST
-
-C<grep>, C<join>, C<map>, C<qw//>, C<reverse>, C<sort>, C<unpack>
-
-=item Functions for real %HASHes
-X<hash>
-
-=for Pod::Functions =HASH
-
-C<delete>, C<each>, C<exists>, C<keys>, C<values>
-
-=item Input and output functions
-X<I/O> X<input> X<output> X<dbm>
-
-=for Pod::Functions =I/O
-
-C<binmode>, C<close>, C<closedir>, C<dbmclose>, C<dbmopen>, C<die>, C<eof>,
-C<fileno>, C<flock>, C<format>, C<getc>, C<print>, C<printf>, C<read>,
-C<readdir>, C<readline> C<rewinddir>, C<say>, C<seek>, C<seekdir>, C<select>,
-C<syscall>, C<sysread>, C<sysseek>, C<syswrite>, C<tell>, C<telldir>,
-C<truncate>, C<warn>, C<write>
-
-C<say> is available only if the C<"say"> feature is enabled or if it is
-prefixed with C<CORE::>. The C<"say"> feature is enabled automatically
-with a C<use v5.10> (or higher) declaration in the current scope.
-
-=item Functions for fixed-length data or records
-
-=for Pod::Functions =Binary
-
-C<pack>, C<read>, C<syscall>, C<sysread>, C<sysseek>, C<syswrite>, C<unpack>,
-C<vec>
-
-=item Functions for filehandles, files, or directories
-X<file> X<filehandle> X<directory> X<pipe> X<link> X<symlink>
-
-=for Pod::Functions =File
-
-C<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>,
-C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>,
-C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<sysopen>,
-C<umask>, C<unlink>, C<utime>
-
-=item Keywords related to the control flow of your Perl program
-X<control flow>
-
-=for Pod::Functions =Flow
-
-C<break>, C<caller>, C<continue>, C<die>, C<do>,
-C<dump>, C<eval>, C<evalbytes> C<exit>,
-C<__FILE__>, C<goto>, C<last>, C<__LINE__>, C<next>, C<__PACKAGE__>,
-C<redo>, C<return>, C<sub>, C<__SUB__>, C<wantarray>
-
-C<break> is available only if you enable the experimental C<"switch">
-feature or use the C<CORE::> prefix. The C<"switch"> feature also enables
-the C<default>, C<given> and C<when> statements, which are documented in
-L<perlsyn/"Switch Statements">. The C<"switch"> feature is enabled
-automatically with a C<use v5.10> (or higher) declaration in the current
-scope. In Perl v5.14 and earlier, C<continue> required the C<"switch">
-feature, like the other keywords.
-
-C<evalbytes> is only available with with the C<"evalbytes"> feature (see
-L<feature>) or if prefixed with C<CORE::>. C<__SUB__> is only available
-with with the C<"current_sub"> feature or if prefixed with C<CORE::>. Both
-the C<"evalbytes"> and C<"current_sub"> features are enabled automatically
-with a C<use v5.16> (or higher) declaration in the current scope.
-
-=item Keywords related to scoping
-
-=for Pod::Functions =Namespace
-
-C<caller>, C<import>, C<local>, C<my>, C<our>, C<package>, C<state>, C<use>
-
-C<state> is available only if the C<"state"> feature is enabled or if it is
-prefixed with C<CORE::>. The C<"state"> feature is enabled automatically
-with a C<use v5.10> (or higher) declaration in the current scope.
-
-=item Miscellaneous functions
-
-=for Pod::Functions =Misc
-
-C<defined>, C<formline>, C<lock>, C<prototype>, C<reset>, C<scalar>, C<undef>
-
-=item Functions for processes and process groups
-X<process> X<pid> X<process id>
-
-=for Pod::Functions =Process
-
-C<alarm>, C<exec>, C<fork>, C<getpgrp>, C<getppid>, C<getpriority>, C<kill>,
-C<pipe>, C<qx//>, C<readpipe>, C<setpgrp>,
-C<setpriority>, C<sleep>, C<system>,
-C<times>, C<wait>, C<waitpid>
-
-=item Keywords related to Perl modules
-X<module>
-
-=for Pod::Functions =Modules
-
-C<do>, C<import>, C<no>, C<package>, C<require>, C<use>
-
-=item Keywords related to classes and object-orientation
-X<object> X<class> X<package>
-
-=for Pod::Functions =Objects
-
-C<bless>, C<dbmclose>, C<dbmopen>, C<package>, C<ref>, C<tie>, C<tied>,
-C<untie>, C<use>
-
-=item Low-level socket functions
-X<socket> X<sock>
-
-=for Pod::Functions =Socket
-
-C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>,
-C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>,
-C<socket>, C<socketpair>
-
-=item System V interprocess communication functions
-X<IPC> X<System V> X<semaphore> X<shared memory> X<memory> X<message>
-
-=for Pod::Functions =SysV
-
-C<msgctl>, C<msgget>, C<msgrcv>, C<msgsnd>, C<semctl>, C<semget>, C<semop>,
-C<shmctl>, C<shmget>, C<shmread>, C<shmwrite>
-
-=item Fetching user and group info
-X<user> X<group> X<password> X<uid> X<gid> X<passwd> X</etc/passwd>
-
-=for Pod::Functions =User
-
-C<endgrent>, C<endhostent>, C<endnetent>, C<endpwent>, C<getgrent>,
-C<getgrgid>, C<getgrnam>, C<getlogin>, C<getpwent>, C<getpwnam>,
-C<getpwuid>, C<setgrent>, C<setpwent>
-
-=item Fetching network info
-X<network> X<protocol> X<host> X<hostname> X<IP> X<address> X<service>
-
-=for Pod::Functions =Network
-
-C<endprotoent>, C<endservent>, C<gethostbyaddr>, C<gethostbyname>,
-C<gethostent>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
-C<getprotobyname>, C<getprotobynumber>, C<getprotoent>,
-C<getservbyname>, C<getservbyport>, C<getservent>, C<sethostent>,
-C<setnetent>, C<setprotoent>, C<setservent>
-
-=item Time-related functions
-X<time> X<date>
-
-=for Pod::Functions =Time
-
-C<gmtime>, C<localtime>, C<time>, C<times>
-
-=item Non-function keywords
-
-=for Pod::Functions =!Non-functions
-
-C<and>, C<AUTOLOAD>, C<BEGIN>, C<CHECK>, C<cmp>, C<CORE>, C<__DATA__>,
-C<default>, C<DESTROY>, C<else>, C<elseif>, C<elsif>, C<END>, C<__END__>,
-C<eq>, C<for>, C<foreach>, C<ge>, C<given>, C<gt>, C<if>, C<INIT>, C<le>,
-C<lt>, C<ne>, C<not>, C<or>, C<UNITCHECK>, C<unless>, C<until>, C<when>,
-C<while>, C<x>, C<xor>
-
-=back
-
-=head2 Portability
-X<portability> X<Unix> X<portable>
-
-Perl was born in Unix and can therefore access all common Unix
-system calls. In non-Unix environments, the functionality of some
-Unix system calls may not be available or details of the available
-functionality may differ slightly. The Perl functions affected
-by this are:
-
-C<-X>, C<binmode>, C<chmod>, C<chown>, C<chroot>, C<crypt>,
-C<dbmclose>, C<dbmopen>, C<dump>, C<endgrent>, C<endhostent>,
-C<endnetent>, C<endprotoent>, C<endpwent>, C<endservent>, C<exec>,
-C<fcntl>, C<flock>, C<fork>, C<getgrent>, C<getgrgid>, C<gethostbyname>,
-C<gethostent>, C<getlogin>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
-C<getppid>, C<getpgrp>, C<getpriority>, C<getprotobynumber>,
-C<getprotoent>, C<getpwent>, C<getpwnam>, C<getpwuid>,
-C<getservbyport>, C<getservent>, C<getsockopt>, C<glob>, C<ioctl>,
-C<kill>, C<link>, C<lstat>, C<msgctl>, C<msgget>, C<msgrcv>,
-C<msgsnd>, C<open>, C<pipe>, C<readlink>, C<rename>, C<select>, C<semctl>,
-C<semget>, C<semop>, C<setgrent>, C<sethostent>, C<setnetent>,
-C<setpgrp>, C<setpriority>, C<setprotoent>, C<setpwent>,
-C<setservent>, C<setsockopt>, C<shmctl>, C<shmget>, C<shmread>,
-C<shmwrite>, C<socket>, C<socketpair>,
-C<stat>, C<symlink>, C<syscall>, C<sysopen>, C<system>,
-C<times>, C<truncate>, C<umask>, C<unlink>,
-C<utime>, C<wait>, C<waitpid>
-
-For more information about the portability of these functions, see
-L<perlport> and other available platform-specific documentation.
-
-=head2 Alphabetical Listing of Perl Functions
-
-=over
-
-=item -X FILEHANDLE
-X<-r>X<-w>X<-x>X<-o>X<-R>X<-W>X<-X>X<-O>X<-e>X<-z>X<-s>X<-f>X<-d>X<-l>X<-p>
-X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>
-
-=item -X EXPR
-
-=item -X DIRHANDLE
-
-=item -X
-
-=for Pod::Functions a file test (-r, -x, etc)
-
-A file test, where X is one of the letters listed below. This unary
-operator takes one argument, either a filename, a filehandle, or a dirhandle,
-and tests the associated file to see if something is true about it. If the
-argument is omitted, tests C<$_>, except for C<-t>, which tests STDIN.
-Unless otherwise documented, it returns C<1> for true and C<''> for false, or
-the undefined value if the file doesn't exist. Despite the funny
-names, precedence is the same as any other named unary operator. The
-operator may be any of:
-
- -r File is readable by effective uid/gid.
- -w File is writable by effective uid/gid.
- -x File is executable by effective uid/gid.
- -o File is owned by effective uid.
-
- -R File is readable by real uid/gid.
- -W File is writable by real uid/gid.
- -X File is executable by real uid/gid.
- -O File is owned by real uid.
-
- -e File exists.
- -z File has zero size (is empty).
- -s File has nonzero size (returns size in bytes).
-
- -f File is a plain file.
- -d File is a directory.
- -l File is a symbolic link.
- -p File is a named pipe (FIFO), or Filehandle is a pipe.
- -S File is a socket.
- -b File is a block special file.
- -c File is a character special file.
- -t Filehandle is opened to a tty.
-
- -u File has setuid bit set.
- -g File has setgid bit set.
- -k File has sticky bit set.
-
- -T File is an ASCII text file (heuristic guess).
- -B File is a "binary" file (opposite of -T).
-
- -M Script start time minus file modification time, in days.
- -A Same for access time.
- -C Same for inode change time (Unix, may differ for other platforms)
-
-Example:
-
- while (<>) {
- chomp;
- next unless -f $_; # ignore specials
- #...
- }
-
-Note that C<-s/a/b/> does not do a negated substitution. Saying
-C<-exp($foo)> still works as expected, however: only single letters
-following a minus are interpreted as file tests.
-
-These operators are exempt from the "looks like a function rule" described
-above. That is, an opening parenthesis after the operator does not affect
-how much of the following code constitutes the argument. Put the opening
-parentheses before the operator to separate it from code that follows (this
-applies only to operators with higher precedence than unary operators, of
-course):
-
- -s($file) + 1024 # probably wrong; same as -s($file + 1024)
- (-s $file) + 1024 # correct
-
-The interpretation of the file permission operators C<-r>, C<-R>,
-C<-w>, C<-W>, C<-x>, and C<-X> is by default based solely on the mode
-of the file and the uids and gids of the user. There may be other
-reasons you can't actually read, write, or execute the file: for
-example network filesystem access controls, ACLs (access control lists),
-read-only filesystems, and unrecognized executable formats. Note
-that the use of these six specific operators to verify if some operation
-is possible is usually a mistake, because it may be open to race
-conditions.
-
-Also note that, for the superuser on the local filesystems, the C<-r>,
-C<-R>, C<-w>, and C<-W> tests always return 1, and C<-x> and C<-X> return 1
-if any execute bit is set in the mode. Scripts run by the superuser
-may thus need to do a stat() to determine the actual mode of the file,
-or temporarily set their effective uid to something else.
-
-If you are using ACLs, there is a pragma called C<filetest> that may
-produce more accurate results than the bare stat() mode bits.
-When under C<use filetest 'access'> the above-mentioned filetests
-test whether the permission can(not) be granted using the
-access(2) family of system calls. Also note that the C<-x> and C<-X> may
-under this pragma return true even if there are no execute permission
-bits set (nor any extra execute permission ACLs). This strangeness is
-due to the underlying system calls' definitions. Note also that, due to
-the implementation of C<use filetest 'access'>, the C<_> special
-filehandle won't cache the results of the file tests when this pragma is
-in effect. Read the documentation for the C<filetest> pragma for more
-information.
-
-The C<-T> and C<-B> switches work as follows. The first block or so of the
-file is examined for odd characters such as strange control codes or
-characters with the high bit set. If too many strange characters (>30%)
-are found, it's a C<-B> file; otherwise it's a C<-T> file. Also, any file
-containing a zero byte in the first block is considered a binary file. If C<-T>
-or C<-B> is used on a filehandle, the current IO buffer is examined
-rather than the first block. Both C<-T> and C<-B> return true on an empty
-file, or a file at EOF when testing a filehandle. Because you have to
-read a file to do the C<-T> test, on most occasions you want to use a C<-f>
-against the file first, as in C<next unless -f $file && -T $file>.
-
-If any of the file tests (or either the C<stat> or C<lstat> operator) is given
-the special filehandle consisting of a solitary underline, then the stat
-structure of the previous file test (or stat operator) is used, saving
-a system call. (This doesn't work with C<-t>, and you need to remember
-that lstat() and C<-l> leave values in the stat structure for the
-symbolic link, not the real file.) (Also, if the stat buffer was filled by
-an C<lstat> call, C<-T> and C<-B> will reset it with the results of C<stat _>).
-Example:
-
- print "Can do.\n" if -r $a || -w _ || -x _;
-
- stat($filename);
- print "Readable\n" if -r _;
- print "Writable\n" if -w _;
- print "Executable\n" if -x _;
- print "Setuid\n" if -u _;
- print "Setgid\n" if -g _;
- print "Sticky\n" if -k _;
- print "Text\n" if -T _;
- print "Binary\n" if -B _;
-
-As of Perl 5.9.1, as a form of purely syntactic sugar, you can stack file
-test operators, in a way that C<-f -w -x $file> is equivalent to
-C<-x $file && -w _ && -f _>. (This is only fancy fancy: if you use
-the return value of C<-f $file> as an argument to another filetest
-operator, no special magic will happen.)
-
-Portability issues: L<perlport/-X>.
-
-To avoid confusing would-be users of your code with mysterious
-syntax errors, put something like this at the top of your script:
-
- use 5.010; # so filetest ops can stack
-
-=item abs VALUE
-X<abs> X<absolute>
-
-=item abs
-
-=for Pod::Functions absolute value function
-
-Returns the absolute value of its argument.
-If VALUE is omitted, uses C<$_>.
-
-=item accept NEWSOCKET,GENERICSOCKET
-X<accept>
-
-=for Pod::Functions accept an incoming socket connect
-
-Accepts an incoming socket connect, just as accept(2)
-does. Returns the packed address if it succeeded, false otherwise.
-See the example in L<perlipc/"Sockets: Client/Server Communication">.
-
-On systems that support a close-on-exec flag on files, the flag will
-be set for the newly opened file descriptor, as determined by the
-value of $^F. See L<perlvar/$^F>.
-
-=item alarm SECONDS
-X<alarm>
-X<SIGALRM>
-X<timer>
-
-=item alarm
-
-=for Pod::Functions schedule a SIGALRM
-
-Arranges to have a SIGALRM delivered to this process after the
-specified number of wallclock seconds has elapsed. If SECONDS is not
-specified, the value stored in C<$_> is used. (On some machines,
-unfortunately, the elapsed time may be up to one second less or more
-than you specified because of how seconds are counted, and process
-scheduling may delay the delivery of the signal even further.)
-
-Only one timer may be counting at once. Each call disables the
-previous timer, and an argument of C<0> may be supplied to cancel the
-previous timer without starting a new one. The returned value is the
-amount of time remaining on the previous timer.
-
-For delays of finer granularity than one second, the Time::HiRes module
-(from CPAN, and starting from Perl 5.8 part of the standard
-distribution) provides ualarm(). You may also use Perl's four-argument
-version of select() leaving the first three arguments undefined, or you
-might be able to use the C<syscall> interface to access setitimer(2) if
-your system supports it. See L<perlfaq8> for details.
-
-It is usually a mistake to intermix C<alarm> and C<sleep> calls, because
-C<sleep> may be internally implemented on your system with C<alarm>.
-
-If you want to use C<alarm> to time out a system call you need to use an
-C<eval>/C<die> pair. You can't rely on the alarm causing the system call to
-fail with C<$!> set to C<EINTR> because Perl sets up signal handlers to
-restart system calls on some systems. Using C<eval>/C<die> always works,
-modulo the caveats given in L<perlipc/"Signals">.
-
- eval {
- local $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required
- alarm $timeout;
- $nread = sysread SOCKET, $buffer, $size;
- alarm 0;
- };
- if ($@) {
- die unless $@ eq "alarm\n"; # propagate unexpected errors
- # timed out
- }
- else {
- # didn't
- }
-
-For more information see L<perlipc>.
-
-Portability issues: L<perlport/alarm>.
-
-=item atan2 Y,X
-X<atan2> X<arctangent> X<tan> X<tangent>
-
-=for Pod::Functions arctangent of Y/X in the range -PI to PI
-
-Returns the arctangent of Y/X in the range -PI to PI.
-
-For the tangent operation, you may use the C<Math::Trig::tan>
-function, or use the familiar relation:
-
- sub tan { sin($_[0]) / cos($_[0]) }
-
-The return value for C<atan2(0,0)> is implementation-defined; consult
-your atan2(3) manpage for more information.
-
-Portability issues: L<perlport/atan2>.
-
-=item bind SOCKET,NAME
-X<bind>
-
-=for Pod::Functions binds an address to a socket
-
-Binds a network address to a socket, just as bind(2)
-does. Returns true if it succeeded, false otherwise. NAME should be a
-packed address of the appropriate type for the socket. See the examples in
-L<perlipc/"Sockets: Client/Server Communication">.
-
-=item binmode FILEHANDLE, LAYER
-X<binmode> X<binary> X<text> X<DOS> X<Windows>
-
-=item binmode FILEHANDLE
-
-=for Pod::Functions prepare binary files for I/O
-
-Arranges for FILEHANDLE to be read or written in "binary" or "text"
-mode on systems where the run-time libraries distinguish between
-binary and text files. If FILEHANDLE is an expression, the value is
-taken as the name of the filehandle. Returns true on success,
-otherwise it returns C<undef> and sets C<$!> (errno).
-
-On some systems (in general, DOS- and Windows-based systems) binmode()
-is necessary when you're not working with a text file. For the sake
-of portability it is a good idea always to use it when appropriate,
-and never to use it when it isn't appropriate. Also, people can
-set their I/O to be by default UTF8-encoded Unicode, not bytes.
-
-In other words: regardless of platform, use binmode() on binary data,
-like images, for example.
-
-If LAYER is present it is a single string, but may contain multiple
-directives. The directives alter the behaviour of the filehandle.
-When LAYER is present, using binmode on a text file makes sense.
-
-If LAYER is omitted or specified as C<:raw> the filehandle is made
-suitable for passing binary data. This includes turning off possible CRLF
-translation and marking it as bytes (as opposed to Unicode characters).
-Note that, despite what may be implied in I<"Programming Perl"> (the
-Camel, 3rd edition) or elsewhere, C<:raw> is I<not> simply the inverse of C<:crlf>.
-Other layers that would affect the binary nature of the stream are
-I<also> disabled. See L<PerlIO>, L<perlrun>, and the discussion about the
-PERLIO environment variable.
-
-The C<:bytes>, C<:crlf>, C<:utf8>, and any other directives of the
-form C<:...>, are called I/O I<layers>. The C<open> pragma can be used to
-establish default I/O layers. See L<open>.
-
-I<The LAYER parameter of the binmode() function is described as "DISCIPLINE"
-in "Programming Perl, 3rd Edition". However, since the publishing of this
-book, by many known as "Camel III", the consensus of the naming of this
-functionality has moved from "discipline" to "layer". All documentation
-of this version of Perl therefore refers to "layers" rather than to
-"disciplines". Now back to the regularly scheduled documentation...>
-
-To mark FILEHANDLE as UTF-8, use C<:utf8> or C<:encoding(UTF-8)>.
-C<:utf8> just marks the data as UTF-8 without further checking,
-while C<:encoding(UTF-8)> checks the data for actually being valid
-UTF-8. More details can be found in L<PerlIO::encoding>.
-
-In general, binmode() should be called after open() but before any I/O
-is done on the filehandle. Calling binmode() normally flushes any
-pending buffered output data (and perhaps pending input data) on the
-handle. An exception to this is the C<:encoding> layer that
-changes the default character encoding of the handle; see L</open>.
-The C<:encoding> layer sometimes needs to be called in
-mid-stream, and it doesn't flush the stream. The C<:encoding>
-also implicitly pushes on top of itself the C<:utf8> layer because
-internally Perl operates on UTF8-encoded Unicode characters.
-
-The operating system, device drivers, C libraries, and Perl run-time
-system all conspire to let the programmer treat a single
-character (C<\n>) as the line terminator, irrespective of external
-representation. On many operating systems, the native text file
-representation matches the internal representation, but on some
-platforms the external representation of C<\n> is made up of more than
-one character.
-
-All variants of Unix, Mac OS (old and new), and Stream_LF files on VMS use
-a single character to end each line in the external representation of text
-(even though that single character is CARRIAGE RETURN on old, pre-Darwin
-flavors of Mac OS, and is LINE FEED on Unix and most VMS files). In other
-systems like OS/2, DOS, and the various flavors of MS-Windows, your program
-sees a C<\n> as a simple C<\cJ>, but what's stored in text files are the
-two characters C<\cM\cJ>. That means that if you don't use binmode() on
-these systems, C<\cM\cJ> sequences on disk will be converted to C<\n> on
-input, and any C<\n> in your program will be converted back to C<\cM\cJ> on
-output. This is what you want for text files, but it can be disastrous for
-binary files.
-
-Another consequence of using binmode() (on some systems) is that
-special end-of-file markers will be seen as part of the data stream.
-For systems from the Microsoft family this means that, if your binary
-data contain C<\cZ>, the I/O subsystem will regard it as the end of
-the file, unless you use binmode().
-
-binmode() is important not only for readline() and print() operations,
-but also when using read(), seek(), sysread(), syswrite() and tell()
-(see L<perlport> for more details). See the C<$/> and C<$\> variables
-in L<perlvar> for how to manually set your input and output
-line-termination sequences.
-
-Portability issues: L<perlport/binmode>.
-
-=item bless REF,CLASSNAME
-X<bless>
-
-=item bless REF
-
-=for Pod::Functions create an object
-
-This function tells the thingy referenced by REF that it is now an object
-in the CLASSNAME package. If CLASSNAME is omitted, the current package
-is used. Because a C<bless> is often the last thing in a constructor,
-it returns the reference for convenience. Always use the two-argument
-version if a derived class might inherit the function doing the blessing.
-SeeL<perlobj> for more about the blessing (and blessings) of objects.
-
-Consider always blessing objects in CLASSNAMEs that are mixed case.
-Namespaces with all lowercase names are considered reserved for
-Perl pragmata. Builtin types have all uppercase names. To prevent
-confusion, you may wish to avoid such package names as well. Make sure
-that CLASSNAME is a true value.
-
-See L<perlmod/"Perl Modules">.
-
-=item break
-
-=for Pod::Functions +switch break out of a C<given> block
-
-Break out of a C<given()> block.
-
-This keyword is enabled by the C<"switch"> feature: see
-L<feature> for more information. You can also access it by
-prefixing it with C<CORE::>. Alternately, include a C<use
-v5.10> or later to the current scope.
-
-=item caller EXPR
-X<caller> X<call stack> X<stack> X<stack trace>
-
-=item caller
-
-=for Pod::Functions get context of the current subroutine call
-
-Returns the context of the current subroutine call. In scalar context,
-returns the caller's package name if there I<is> a caller (that is, if
-we're in a subroutine or C<eval> or C<require>) and the undefined value
-otherwise. In list context, returns
-
- # 0 1 2
- ($package, $filename, $line) = caller;
-
-With EXPR, it returns some extra information that the debugger uses to
-print a stack trace. The value of EXPR indicates how many call frames
-to go back before the current one.
-
- # 0 1 2 3 4
- ($package, $filename, $line, $subroutine, $hasargs,
-
- # 5 6 7 8 9 10
- $wantarray, $evaltext, $is_require, $hints, $bitmask, $hinthash)
- = caller($i);
-
-Here $subroutine may be C<(eval)> if the frame is not a subroutine
-call, but an C<eval>. In such a case additional elements $evaltext and
-C<$is_require> are set: C<$is_require> is true if the frame is created by a
-C<require> or C<use> statement, $evaltext contains the text of the
-C<eval EXPR> statement. In particular, for an C<eval BLOCK> statement,
-$subroutine is C<(eval)>, but $evaltext is undefined. (Note also that
-each C<use> statement creates a C<require> frame inside an C<eval EXPR>
-frame.) $subroutine may also be C<(unknown)> if this particular
-subroutine happens to have been deleted from the symbol table.
-C<$hasargs> is true if a new instance of C<@_> was set up for the frame.
-C<$hints> and C<$bitmask> contain pragmatic hints that the caller was
-compiled with. The C<$hints> and C<$bitmask> values are subject to change
-between versions of Perl, and are not meant for external use.
-
-C<$hinthash> is a reference to a hash containing the value of C<%^H> when the
-caller was compiled, or C<undef> if C<%^H> was empty. Do not modify the values
-of this hash, as they are the actual values stored in the optree.
-
-Furthermore, when called from within the DB package in
-list context, and with an argument, caller returns more
-detailed information: it sets the list variable C<@DB::args> to be the
-arguments with which the subroutine was invoked.
-
-Be aware that the optimizer might have optimized call frames away before
-C<caller> had a chance to get the information. That means that C<caller(N)>
-might not return information about the call frame you expect it to, for
-C<< N > 1 >>. In particular, C<@DB::args> might have information from the
-previous time C<caller> was called.
-
-Be aware that setting C<@DB::args> is I<best effort>, intended for
-debugging or generating backtraces, and should not be relied upon. In
-particular, as C<@_> contains aliases to the caller's arguments, Perl does
-not take a copy of C<@_>, so C<@DB::args> will contain modifications the
-subroutine makes to C<@_> or its contents, not the original values at call
-time. C<@DB::args>, like C<@_>, does not hold explicit references to its
-elements, so under certain cases its elements may have become freed and
-reallocated for other variables or temporary values. Finally, a side effect
-of the current implementation is that the effects of C<shift @_> can
-I<normally> be undone (but not C<pop @_> or other splicing, I<and> not if a
-reference to C<@_> has been taken, I<and> subject to the caveat about reallocated
-elements), so C<@DB::args> is actually a hybrid of the current state and
-initial state of C<@_>. Buyer beware.
-
-=item chdir EXPR
-X<chdir>
-X<cd>
-X<directory, change>
-
-=item chdir FILEHANDLE
-
-=item chdir DIRHANDLE
-
-=item chdir
-
-=for Pod::Functions change your current working directory
-
-Changes the working directory to EXPR, if possible. If EXPR is omitted,
-changes to the directory specified by C<$ENV{HOME}>, if set; if not,
-changes to the directory specified by C<$ENV{LOGDIR}>. (Under VMS, the
-variable C<$ENV{SYS$LOGIN}> is also checked, and used if it is set.) If
-neither is set, C<chdir> does nothing. It returns true on success,
-false otherwise. See the example under C<die>.
-
-On systems that support fchdir(2), you may pass a filehandle or
-directory handle as the argument. On systems that don't support fchdir(2),
-passing handles raises an exception.
-
-=item chmod LIST
-X<chmod> X<permission> X<mode>
-
-=for Pod::Functions changes the permissions on a list of files
-
-Changes the permissions of a list of files. The first element of the
-list must be the numeric mode, which should probably be an octal
-number, and which definitely should I<not> be a string of octal digits:
-C<0644> is okay, but C<"0644"> is not. Returns the number of files
-successfully changed. See also L</oct> if all you have is a string.
-
- $cnt = chmod 0755, "foo", "bar";
- chmod 0755, @executables;
- $mode = "0644"; chmod $mode, "foo"; # !!! sets mode to
- # --w----r-T
- $mode = "0644"; chmod oct($mode), "foo"; # this is better
- $mode = 0644; chmod $mode, "foo"; # this is best
-
-On systems that support fchmod(2), you may pass filehandles among the
-files. On systems that don't support fchmod(2), passing filehandles raises
-an exception. Filehandles must be passed as globs or glob references to be
-recognized; barewords are considered filenames.
-
- open(my $fh, "<", "foo");
- my $perm = (stat $fh)[2] & 07777;
- chmod($perm | 0600, $fh);
-
-You can also import the symbolic C<S_I*> constants from the C<Fcntl>
-module:
-
- use Fcntl qw( :mode );
- chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables;
- # Identical to the chmod 0755 of the example above.
-
-Portability issues: L<perlport/chmod>.
-
-=item chomp VARIABLE
-X<chomp> X<INPUT_RECORD_SEPARATOR> X<$/> X<newline> X<eol>
-
-=item chomp( LIST )
-
-=item chomp
-
-=for Pod::Functions remove a trailing record separator from a string
-
-This safer version of L</chop> removes any trailing string
-that corresponds to the current value of C<$/> (also known as
-$INPUT_RECORD_SEPARATOR in the C<English> module). It returns the total
-number of characters removed from all its arguments. It's often used to
-remove the newline from the end of an input record when you're worried
-that the final record may be missing its newline. When in paragraph
-mode (C<$/ = "">), it removes all trailing newlines from the string.
-When in slurp mode (C<$/ = undef>) or fixed-length record mode (C<$/> is
-a reference to an integer or the like; see L<perlvar>) chomp() won't
-remove anything.
-If VARIABLE is omitted, it chomps C<$_>. Example:
-
- while (<>) {
- chomp; # avoid \n on last field
- @array = split(/:/);
- # ...
- }
-
-If VARIABLE is a hash, it chomps the hash's values, but not its keys.
-
-You can actually chomp anything that's an lvalue, including an assignment:
-
- chomp($cwd = `pwd`);
- chomp($answer = <STDIN>);
-
-If you chomp a list, each element is chomped, and the total number of
-characters removed is returned.
-
-Note that parentheses are necessary when you're chomping anything
-that is not a simple variable. This is because C<chomp $cwd = `pwd`;>
-is interpreted as C<(chomp $cwd) = `pwd`;>, rather than as
-C<chomp( $cwd = `pwd` )> which you might expect. Similarly,
-C<chomp $a, $b> is interpreted as C<chomp($a), $b> rather than
-as C<chomp($a, $b)>.
-
-=item chop VARIABLE
-X<chop>
-
-=item chop( LIST )
-
-=item chop
-
-=for Pod::Functions remove the last character from a string
-
-Chops off the last character of a string and returns the character
-chopped. It is much more efficient than C<s/.$//s> because it neither
-scans nor copies the string. If VARIABLE is omitted, chops C<$_>.
-If VARIABLE is a hash, it chops the hash's values, but not its keys.
-
-You can actually chop anything that's an lvalue, including an assignment.
-
-If you chop a list, each element is chopped. Only the value of the
-last C<chop> is returned.
-
-Note that C<chop> returns the last character. To return all but the last
-character, use C<substr($string, 0, -1)>.
-
-See also L</chomp>.
-
-=item chown LIST
-X<chown> X<owner> X<user> X<group>
-
-=for Pod::Functions change the ownership on a list of files
-
-Changes the owner (and group) of a list of files. The first two
-elements of the list must be the I<numeric> uid and gid, in that
-order. A value of -1 in either position is interpreted by most
-systems to leave that value unchanged. Returns the number of files
-successfully changed.
-
- $cnt = chown $uid, $gid, 'foo', 'bar';
- chown $uid, $gid, @filenames;
-
-On systems that support fchown(2), you may pass filehandles among the
-files. On systems that don't support fchown(2), passing filehandles raises
-an exception. Filehandles must be passed as globs or glob references to be
-recognized; barewords are considered filenames.
-
-Here's an example that looks up nonnumeric uids in the passwd file:
-
- print "User: ";
- chomp($user = <STDIN>);
- print "Files: ";
- chomp($pattern = <STDIN>);
-
- ($login,$pass,$uid,$gid) = getpwnam($user)
- or die "$user not in passwd file";
-
- @ary = glob($pattern); # expand filenames
- chown $uid, $gid, @ary;
-
-On most systems, you are not allowed to change the ownership of the
-file unless you're the superuser, although you should be able to change
-the group to any of your secondary groups. On insecure systems, these
-restrictions may be relaxed, but this is not a portable assumption.
-On POSIX systems, you can detect this condition this way:
-
- use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
- $can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
-
-Portability issues: L<perlport/chmod>.
-
-=item chr NUMBER
-X<chr> X<character> X<ASCII> X<Unicode>
-
-=item chr
-
-=for Pod::Functions get character this number represents
-
-Returns the character represented by that NUMBER in the character set.
-For example, C<chr(65)> is C<"A"> in either ASCII or Unicode, and
-chr(0x263a) is a Unicode smiley face.
-
-Negative values give the Unicode replacement character (chr(0xfffd)),
-except under the L<bytes> pragma, where the low eight bits of the value
-(truncated to an integer) are used.
-
-If NUMBER is omitted, uses C<$_>.
-
-For the reverse, use L</ord>.
-
-Note that characters from 128 to 255 (inclusive) are by default
-internally not encoded as UTF-8 for backward compatibility reasons.
-
-See L<perlunicode> for more about Unicode.
-
-=item chroot FILENAME
-X<chroot> X<root>
-
-=item chroot
-
-=for Pod::Functions make directory new root for path lookups
-
-This function works like the system call by the same name: it makes the
-named directory the new root directory for all further pathnames that
-begin with a C</> by your process and all its children. (It doesn't
-change your current working directory, which is unaffected.) For security
-reasons, this call is restricted to the superuser. If FILENAME is
-omitted, does a C<chroot> to C<$_>.
-
-Portability issues: L<perlport/chroot>.
-
-=item close FILEHANDLE
-X<close>
-
-=item close
-
-=for Pod::Functions close file (or pipe or socket) handle
-
-Closes the file or pipe associated with the filehandle, flushes the IO
-buffers, and closes the system file descriptor. Returns true if those
-operations succeed and if no error was reported by any PerlIO
-layer. Closes the currently selected filehandle if the argument is
-omitted.
-
-You don't have to close FILEHANDLE if you are immediately going to do
-another C<open> on it, because C<open> closes it for you. (See
-L<open|/open FILEHANDLE>.) However, an explicit C<close> on an input file resets the line
-counter (C<$.>), while the implicit close done by C<open> does not.
-
-If the filehandle came from a piped open, C<close> returns false if one of
-the other syscalls involved fails or if its program exits with non-zero
-status. If the only problem was that the program exited non-zero, C<$!>
-will be set to C<0>. Closing a pipe also waits for the process executing
-on the pipe to exit--in case you wish to look at the output of the pipe
-afterwards--and implicitly puts the exit status value of that command into
-C<$?> and C<${^CHILD_ERROR_NATIVE}>.
-
-If there are multiple threads running, C<close> on a filehandle from a
-piped open returns true without waiting for the child process to terminate,
-if the filehandle is still open in another thread.
-
-Closing the read end of a pipe before the process writing to it at the
-other end is done writing results in the writer receiving a SIGPIPE. If
-the other end can't handle that, be sure to read all the data before
-closing the pipe.
-
-Example:
-
- open(OUTPUT, '|sort >foo') # pipe to sort
- or die "Can't start sort: $!";
- #... # print stuff to output
- close OUTPUT # wait for sort to finish
- or warn $! ? "Error closing sort pipe: $!"
- : "Exit status $? from sort";
- open(INPUT, 'foo') # get sort's results
- or die "Can't open 'foo' for input: $!";
-
-FILEHANDLE may be an expression whose value can be used as an indirect
-filehandle, usually the real filehandle name or an autovivified handle.
-
-=item closedir DIRHANDLE
-X<closedir>
-
-=for Pod::Functions close directory handle
-
-Closes a directory opened by C<opendir> and returns the success of that
-system call.
-
-=item connect SOCKET,NAME
-X<connect>
-
-=for Pod::Functions connect to a remote socket
-
-Attempts to connect to a remote socket, just like connect(2).
-Returns true if it succeeded, false otherwise. NAME should be a
-packed address of the appropriate type for the socket. See the examples in
-L<perlipc/"Sockets: Client/Server Communication">.
-
-=item continue BLOCK
-X<continue>
-
-=item continue
-
-=for Pod::Functions optional trailing block in a while or foreach
-
-When followed by a BLOCK, C<continue> is actually a
-flow control statement rather than a function. If
-there is a C<continue> BLOCK attached to a BLOCK (typically in a C<while> or
-C<foreach>), it is always executed just before the conditional is about to
-be evaluated again, just like the third part of a C<for> loop in C. Thus
-it can be used to increment a loop variable, even when the loop has been
-continued via the C<next> statement (which is similar to the C C<continue>
-statement).
-
-C<last>, C<next>, or C<redo> may appear within a C<continue>
-block; C<last> and C<redo> behave as if they had been executed within
-the main block. So will C<next>, but since it will execute a C<continue>
-block, it may be more entertaining.
-
- while (EXPR) {
- ### redo always comes here
- do_something;
- } continue {
- ### next always comes here
- do_something_else;
- # then back the top to re-check EXPR
- }
- ### last always comes here
-
-Omitting the C<continue> section is equivalent to using an
-empty one, logically enough, so C<next> goes directly back
-to check the condition at the top of the loop.
-
-When there is no BLOCK, C<continue> is a function that
-falls through the current C<when> or C<default> block instead of iterating
-a dynamically enclosing C<foreach> or exiting a lexically enclosing C<given>.
-In Perl 5.14 and earlier, this form of C<continue> was
-only available when the C<"switch"> feature was enabled.
-See L<feature> and L<perlsyn/"Switch Statements"> for more
-information.
-
-=item cos EXPR
-X<cos> X<cosine> X<acos> X<arccosine>
-
-=item cos
-
-=for Pod::Functions cosine function
-
-Returns the cosine of EXPR (expressed in radians). If EXPR is omitted,
-takes the cosine of C<$_>.
-
-For the inverse cosine operation, you may use the C<Math::Trig::acos()>
-function, or use this relation:
-
- sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
-
-=item crypt PLAINTEXT,SALT
-X<crypt> X<digest> X<hash> X<salt> X<plaintext> X<password>
-X<decrypt> X<cryptography> X<passwd> X<encrypt>
-
-=for Pod::Functions one-way passwd-style encryption
-
-Creates a digest string exactly like the crypt(3) function in the C
-library (assuming that you actually have a version there that has not
-been extirpated as a potential munition).
-
-crypt() is a one-way hash function. The PLAINTEXT and SALT are turned
-into a short string, called a digest, which is returned. The same
-PLAINTEXT and SALT will always return the same string, but there is no
-(known) way to get the original PLAINTEXT from the hash. Small
-changes in the PLAINTEXT or SALT will result in large changes in the
-digest.
-
-There is no decrypt function. This function isn't all that useful for
-cryptography (for that, look for F<Crypt> modules on your nearby CPAN
-mirror) and the name "crypt" is a bit of a misnomer. Instead it is
-primarily used to check if two pieces of text are the same without
-having to transmit or store the text itself. An example is checking
-if a correct password is given. The digest of the password is stored,
-not the password itself. The user types in a password that is
-crypt()'d with the same salt as the stored digest. If the two digests
-match, the password is correct.
-
-When verifying an existing digest string you should use the digest as
-the salt (like C<crypt($plain, $digest) eq $digest>). The SALT used
-to create the digest is visible as part of the digest. This ensures
-crypt() will hash the new string with the same salt as the digest.
-This allows your code to work with the standard L<crypt|/crypt> and
-with more exotic implementations. In other words, assume
-nothing about the returned string itself nor about how many bytes
-of SALT may matter.
-
-Traditionally the result is a string of 13 bytes: two first bytes of
-the salt, followed by 11 bytes from the set C<[./0-9A-Za-z]>, and only
-the first eight bytes of PLAINTEXT mattered. But alternative
-hashing schemes (like MD5), higher level security schemes (like C2),
-and implementations on non-Unix platforms may produce different
-strings.
-
-When choosing a new salt create a random two character string whose
-characters come from the set C<[./0-9A-Za-z]> (like C<join '', ('.',
-'/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]>). This set of
-characters is just a recommendation; the characters allowed in
-the salt depend solely on your system's crypt library, and Perl can't
-restrict what salts C<crypt()> accepts.
-
-Here's an example that makes sure that whoever runs this program knows
-their password:
-
- $pwd = (getpwuid($<))[1];
-
- system "stty -echo";
- print "Password: ";
- chomp($word = <STDIN>);
- print "\n";
- system "stty echo";
-
- if (crypt($word, $pwd) ne $pwd) {
- die "Sorry...\n";
- } else {
- print "ok\n";
- }
-
-Of course, typing in your own password to whoever asks you
-for it is unwise.
-
-The L<crypt|/crypt> function is unsuitable for hashing large quantities
-of data, not least of all because you can't get the information
-back. Look at the L<Digest> module for more robust algorithms.
-
-If using crypt() on a Unicode string (which I<potentially> has
-characters with codepoints above 255), Perl tries to make sense
-of the situation by trying to downgrade (a copy of)
-the string back to an eight-bit byte string before calling crypt()
-(on that copy). If that works, good. If not, crypt() dies with
-C<Wide character in crypt>.
-
-Portability issues: L<perlport/crypt>.
-
-=item dbmclose HASH
-X<dbmclose>
-
-=for Pod::Functions breaks binding on a tied dbm file
-
-[This function has been largely superseded by the C<untie> function.]
-
-Breaks the binding between a DBM file and a hash.
-
-Portability issues: L<perlport/dbmclose>.
-
-=item dbmopen HASH,DBNAME,MASK
-X<dbmopen> X<dbm> X<ndbm> X<sdbm> X<gdbm>
-
-=for Pod::Functions create binding on a tied dbm file
-
-[This function has been largely superseded by the
-L<tie|/tie VARIABLE,CLASSNAME,LIST> function.]
-
-This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or Berkeley DB file to a
-hash. HASH is the name of the hash. (Unlike normal C<open>, the first
-argument is I<not> a filehandle, even though it looks like one). DBNAME
-is the name of the database (without the F<.dir> or F<.pag> extension if
-any). If the database does not exist, it is created with protection
-specified by MASK (as modified by the C<umask>). To prevent creation of
-the database if it doesn't exist, you may specify a MODE
-of 0, and the function will return a false value if it
-can't find an existing database. If your system supports
-only the older DBM functions, you may make only one C<dbmopen> call in your
-program. In older versions of Perl, if your system had neither DBM nor
-ndbm, calling C<dbmopen> produced a fatal error; it now falls back to
-sdbm(3).
-
-If you don't have write access to the DBM file, you can only read hash
-variables, not set them. If you want to test whether you can write,
-either use file tests or try setting a dummy hash entry inside an C<eval>
-to trap the error.
-
-Note that functions such as C<keys> and C<values> may return huge lists
-when used on large DBM files. You may prefer to use the C<each>
-function to iterate over large DBM files. Example:
-
- # print out history file offsets
- dbmopen(%HIST,'/usr/lib/news/history',0666);
- while (($key,$val) = each %HIST) {
- print $key, ' = ', unpack('L',$val), "\n";
- }
- dbmclose(%HIST);
-
-See also L<AnyDBM_File> for a more general description of the pros and
-cons of the various dbm approaches, as well as L<DB_File> for a particularly
-rich implementation.
-
-You can control which DBM library you use by loading that library
-before you call dbmopen():
-
- use DB_File;
- dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db")
- or die "Can't open netscape history file: $!";
-
-Portability issues: L<perlport/dbmopen>.
-
-=item defined EXPR
-X<defined> X<undef> X<undefined>
-
-=item defined
-
-=for Pod::Functions test whether a value, variable, or function is defined
-
-Returns a Boolean value telling whether EXPR has a value other than
-the undefined value C<undef>. If EXPR is not present, C<$_> is
-checked.
-
-Many operations return C<undef> to indicate failure, end of file,
-system error, uninitialized variable, and other exceptional
-conditions. This function allows you to distinguish C<undef> from
-other values. (A simple Boolean test will not distinguish among
-C<undef>, zero, the empty string, and C<"0">, which are all equally
-false.) Note that since C<undef> is a valid scalar, its presence
-doesn't I<necessarily> indicate an exceptional condition: C<pop>
-returns C<undef> when its argument is an empty array, I<or> when the
-element to return happens to be C<undef>.
-
-You may also use C<defined(&func)> to check whether subroutine C<&func>
-has ever been defined. The return value is unaffected by any forward
-declarations of C<&func>. A subroutine that is not defined
-may still be callable: its package may have an C<AUTOLOAD> method that
-makes it spring into existence the first time that it is called; see
-L<perlsub>.
-
-Use of C<defined> on aggregates (hashes and arrays) is deprecated. It
-used to report whether memory for that aggregate had ever been
-allocated. This behavior may disappear in future versions of Perl.
-You should instead use a simple test for size:
-
- if (@an_array) { print "has array elements\n" }
- if (%a_hash) { print "has hash members\n" }
-
-When used on a hash element, it tells you whether the value is defined,
-not whether the key exists in the hash. Use L</exists> for the latter
-purpose.
-
-Examples:
-
- print if defined $switch{D};
- print "$val\n" while defined($val = pop(@ary));
- die "Can't readlink $sym: $!"
- unless defined($value = readlink $sym);
- sub foo { defined &$bar ? &$bar(@_) : die "No bar"; }
- $debugging = 0 unless defined $debugging;
-
-Note: Many folks tend to overuse C<defined> and are then surprised to
-discover that the number C<0> and C<""> (the zero-length string) are, in fact,
-defined values. For example, if you say
-
- "ab" =~ /a(.*)b/;
-
-The pattern match succeeds and C<$1> is defined, although it
-matched "nothing". It didn't really fail to match anything. Rather, it
-matched something that happened to be zero characters long. This is all
-very above-board and honest. When a function returns an undefined value,
-it's an admission that it couldn't give you an honest answer. So you
-should use C<defined> only when questioning the integrity of what
-you're trying to do. At other times, a simple comparison to C<0> or C<""> is
-what you want.
-
-See also L</undef>, L</exists>, L</ref>.
-
-=item delete EXPR
-X<delete>
-
-=for Pod::Functions deletes a value from a hash
-
-Given an expression that specifies an element or slice of a hash, C<delete>
-deletes the specified elements from that hash so that exists() on that element
-no longer returns true. Setting a hash element to the undefined value does
-not remove its key, but deleting it does; see L</exists>.
-
-In list context, returns the value or values deleted, or the last such
-element in scalar context. The return list's length always matches that of
-the argument list: deleting non-existent elements returns the undefined value
-in their corresponding positions.
-
-delete() may also be used on arrays and array slices, but its behavior is less
-straightforward. Although exists() will return false for deleted entries,
-deleting array elements never changes indices of existing values; use shift()
-or splice() for that. However, if all deleted elements fall at the end of an
-array, the array's size shrinks to the position of the highest element that
-still tests true for exists(), or to 0 if none do.
-
-B<WARNING:> Calling delete on array values is deprecated and likely to
-be removed in a future version of Perl.
-
-Deleting from C<%ENV> modifies the environment. Deleting from a hash tied to
-a DBM file deletes the entry from the DBM file. Deleting from a C<tied> hash
-or array may not necessarily return anything; it depends on the implementation
-of the C<tied> package's DELETE method, which may do whatever it pleases.
-
-The C<delete local EXPR> construct localizes the deletion to the current
-block at run time. Until the block exits, elements locally deleted
-temporarily no longer exist. See L<perlsub/"Localized deletion of elements
-of composite types">.
-
- %hash = (foo => 11, bar => 22, baz => 33);
- $scalar = delete $hash{foo}; # $scalar is 11
- $scalar = delete @hash{qw(foo bar)}; # $scalar is 22
- @array = delete @hash{qw(foo bar baz)}; # @array is (undef,undef,33)
-
-The following (inefficiently) deletes all the values of %HASH and @ARRAY:
-
- foreach $key (keys %HASH) {
- delete $HASH{$key};
- }
-
- foreach $index (0 .. $#ARRAY) {
- delete $ARRAY[$index];
- }
-
-And so do these:
-
- delete @HASH{keys %HASH};
-
- delete @ARRAY[0 .. $#ARRAY];
-
-But both are slower than assigning the empty list
-or undefining %HASH or @ARRAY, which is the customary
-way to empty out an aggregate:
-
- %HASH = (); # completely empty %HASH
- undef %HASH; # forget %HASH ever existed
-
- @ARRAY = (); # completely empty @ARRAY
- undef @ARRAY; # forget @ARRAY ever existed
-
-The EXPR can be arbitrarily complicated provided its
-final operation is an element or slice of an aggregate:
-
- delete $ref->[$x][$y]{$key};
- delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys};
-
- delete $ref->[$x][$y][$index];
- delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
-
-=item die LIST
-X<die> X<throw> X<exception> X<raise> X<$@> X<abort>
-
-=for Pod::Functions raise an exception or bail out
-
-C<die> raises an exception. Inside an C<eval> the error message is stuffed
-into C<$@> and the C<eval> is terminated with the undefined value.
-If the exception is outside of all enclosing C<eval>s, then the uncaught
-exception prints LIST to C<STDERR> and exits with a non-zero value. If you
-need to exit the process with a specific exit code, see L</exit>.
-
-Equivalent examples:
-
- die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
- chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"
-
-If the last element of LIST does not end in a newline, the current
-script line number and input line number (if any) are also printed,
-and a newline is supplied. Note that the "input line number" (also
-known as "chunk") is subject to whatever notion of "line" happens to
-be currently in effect, and is also available as the special variable
-C<$.>. See L<perlvar/"$/"> and L<perlvar/"$.">.
-
-Hint: sometimes appending C<", stopped"> to your message will cause it
-to make better sense when the string C<"at foo line 123"> is appended.
-Suppose you are running script "canasta".
-
- die "/etc/games is no good";
- die "/etc/games is no good, stopped";
-
-produce, respectively
-
- /etc/games is no good at canasta line 123.
- /etc/games is no good, stopped at canasta line 123.
-
-If the output is empty and C<$@> already contains a value (typically from a
-previous eval) that value is reused after appending C<"\t...propagated">.
-This is useful for propagating exceptions:
-
- eval { ... };
- die unless $@ =~ /Expected exception/;
-
-If the output is empty and C<$@> contains an object reference that has a
-C<PROPAGATE> method, that method will be called with additional file
-and line number parameters. The return value replaces the value in
-C<$@>; i.e., as if C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >>
-were called.
-
-If C<$@> is empty then the string C<"Died"> is used.
-
-If an uncaught exception results in interpreter exit, the exit code is
-determined from the values of C<$!> and C<$?> with this pseudocode:
-
- exit $! if $!; # errno
- exit $? >> 8 if $? >> 8; # child exit status
- exit 255; # last resort
-
-The intent is to squeeze as much possible information about the likely cause
-into the limited space of the system exit
-code. However, as C<$!> is the value
-of C's C<errno>, which can be set by any system call, this means that the value
-of the exit code used by C<die> can be non-predictable, so should not be relied
-upon, other than to be non-zero.
-
-You can also call C<die> with a reference argument, and if this is trapped
-within an C<eval>, C<$@> contains that reference. This permits more
-elaborate exception handling using objects that maintain arbitrary state
-about the exception. Such a scheme is sometimes preferable to matching
-particular string values of C<$@> with regular expressions. Because C<$@>
-is a global variable and C<eval> may be used within object implementations,
-be careful that analyzing the error object doesn't replace the reference in
-the global variable. It's easiest to make a local copy of the reference
-before any manipulations. Here's an example:
-
- use Scalar::Util "blessed";
-
- eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
- if (my $ev_err = $@) {
- if (blessed($ev_err) && $ev_err->isa("Some::Module::Exception")) {
- # handle Some::Module::Exception
- }
- else {
- # handle all other possible exceptions
- }
- }
-
-Because Perl stringifies uncaught exception messages before display,
-you'll probably want to overload stringification operations on
-exception objects. See L<overload> for details about that.
-
-You can arrange for a callback to be run just before the C<die>
-does its deed, by setting the C<$SIG{__DIE__}> hook. The associated
-handler is called with the error text and can change the error
-message, if it sees fit, by calling C<die> again. See
-L<perlvar/%SIG> for details on setting C<%SIG> entries, and
-L<"eval BLOCK"> for some examples. Although this feature was
-to be run only right before your program was to exit, this is not
-currently so: the C<$SIG{__DIE__}> hook is currently called
-even inside eval()ed blocks/strings! If one wants the hook to do
-nothing in such situations, put
-
- die @_ if $^S;
-
-as the first line of the handler (see L<perlvar/$^S>). Because
-this promotes strange action at a distance, this counterintuitive
-behavior may be fixed in a future release.
-
-See also exit(), warn(), and the Carp module.
-
-=item do BLOCK
-X<do> X<block>
-
-=for Pod::Functions turn a BLOCK into a TERM
-
-Not really a function. Returns the value of the last command in the
-sequence of commands indicated by BLOCK. When modified by the C<while> or
-C<until> loop modifier, executes the BLOCK once before testing the loop
-condition. (On other statements the loop modifiers test the conditional
-first.)
-
-C<do BLOCK> does I<not> count as a loop, so the loop control statements
-C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
-See L<perlsyn> for alternative strategies.
-
-=item do SUBROUTINE(LIST)
-X<do>
-
-This form of subroutine call is deprecated. SUBROUTINE can be a bareword,
-a scalar variable or a subroutine beginning with C<&>.
-
-=item do EXPR
-X<do>
-
-Uses the value of EXPR as a filename and executes the contents of the
-file as a Perl script.
-
- do 'stat.pl';
-
-is just like
-
- eval `cat stat.pl`;
-
-except that it's more efficient and concise, keeps track of the current
-filename for error messages, searches the C<@INC> directories, and updates
-C<%INC> if the file is found. See L<perlvar/@INC> and L<perlvar/%INC> for
-these variables. It also differs in that code evaluated with C<do FILENAME>
-cannot see lexicals in the enclosing scope; C<eval STRING> does. It's the
-same, however, in that it does reparse the file every time you call it,
-so you probably don't want to do this inside a loop.
-
-If C<do> can read the file but cannot compile it, it returns C<undef> and sets
-an error message in C<$@>. If C<do> cannot read the file, it returns undef
-and sets C<$!> to the error. Always check C<$@> first, as compilation
-could fail in a way that also sets C<$!>. If the file is successfully
-compiled, C<do> returns the value of the last expression evaluated.
-
-Inclusion of library modules is better done with the
-C<use> and C<require> operators, which also do automatic error checking
-and raise an exception if there's a problem.
-
-You might like to use C<do> to read in a program configuration
-file. Manual error checking can be done this way:
-
- # read in config files: system first, then user
- for $file ("/share/prog/defaults.rc",
- "$ENV{HOME}/.someprogrc")
- {
- unless ($return = do $file) {
- warn "couldn't parse $file: $@" if $@;
- warn "couldn't do $file: $!" unless defined $return;
- warn "couldn't run $file" unless $return;
- }
- }
-
-=item dump LABEL
-X<dump> X<core> X<undump>
-
-=item dump
-
-=for Pod::Functions create an immediate core dump
-
-This function causes an immediate core dump. See also the B<-u>
-command-line switch in L<perlrun>, which does the same thing.
-Primarily this is so that you can use the B<undump> program (not
-supplied) to turn your core dump into an executable binary after
-having initialized all your variables at the beginning of the
-program. When the new binary is executed it will begin by executing
-a C<goto LABEL> (with all the restrictions that C<goto> suffers).
-Think of it as a goto with an intervening core dump and reincarnation.
-If C<LABEL> is omitted, restarts the program from the top.
-
-B<WARNING>: Any files opened at the time of the dump will I<not>
-be open any more when the program is reincarnated, with possible
-resulting confusion by Perl.
-
-This function is now largely obsolete, mostly because it's very hard to
-convert a core file into an executable. That's why you should now invoke
-it as C<CORE::dump()>, if you don't want to be warned against a possible
-typo.
-
-Portability issues: L<perlport/dump>.
-
-=item each HASH
-X<each> X<hash, iterator>
-
-=item each ARRAY
-X<array, iterator>
-
-=item each EXPR
-
-=for Pod::Functions retrieve the next key/value pair from a hash
-
-When called on a hash in list context, returns a 2-element list
-consisting of the key and value for the next element of a hash. In Perl
-5.12 and later only, it will also return the index and value for the next
-element of an array so that you can iterate over it; older Perls consider
-this a syntax error. When called in scalar context, returns only the key
-(not the value) in a hash, or the index in an array.
-
-Hash entries are returned in an apparently random order. The actual random
-order is subject to change in future versions of Perl, but it is
-guaranteed to be in the same order as either the C<keys> or C<values>
-function would produce on the same (unmodified) hash. Since Perl
-5.8.2 the ordering can be different even between different runs of Perl
-for security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
-
-After C<each> has returned all entries from the hash or array, the next
-call to C<each> returns the empty list in list context and C<undef> in
-scalar context; the next call following I<that> one restarts iteration.
-Each hash or array has its own internal iterator, accessed by C<each>,
-C<keys>, and C<values>. The iterator is implicitly reset when C<each> has
-reached the end as just described; it can be explicitly reset by calling
-C<keys> or C<values> on the hash or array. If you add or delete a hash's
-elements while iterating over it, entries may be skipped or duplicated--so
-don't do that. Exception: In the current implementation, it is always safe
-to delete the item most recently returned by C<each()>, so the following
-code works properly:
-
- while (($key, $value) = each %hash) {
- print $key, "\n";
- delete $hash{$key}; # This is safe
- }
-
-This prints out your environment like the printenv(1) program,
-but in a different order:
-
- while (($key,$value) = each %ENV) {
- print "$key=$value\n";
- }
-
-Starting with Perl 5.14, C<each> can take a scalar EXPR, which must hold
-reference to an unblessed hash or array. The argument will be dereferenced
-automatically. This aspect of C<each> is considered highly experimental.
-The exact behaviour may change in a future version of Perl.
-
- while (($key,$value) = each $hashref) { ... }
-
-To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work I<only> on Perls of
-a recent vintage:
-
- use 5.012; # so keys/values/each work on arrays
- use 5.014; # so keys/values/each work on scalars (experimental)
-
-See also C<keys>, C<values>, and C<sort>.
-
-=item eof FILEHANDLE
-X<eof>
-X<end of file>
-X<end-of-file>
-
-=item eof ()
-
-=item eof
-
-=for Pod::Functions test a filehandle for its end
-
-Returns 1 if the next read on FILEHANDLE will return end of file I<or> if
-FILEHANDLE is not open. FILEHANDLE may be an expression whose value
-gives the real filehandle. (Note that this function actually
-reads a character and then C<ungetc>s it, so isn't useful in an
-interactive context.) Do not read from a terminal file (or call
-C<eof(FILEHANDLE)> on it) after end-of-file is reached. File types such
-as terminals may lose the end-of-file condition if you do.
-
-An C<eof> without an argument uses the last file read. Using C<eof()>
-with empty parentheses is different. It refers to the pseudo file
-formed from the files listed on the command line and accessed via the
-C<< <> >> operator. Since C<< <> >> isn't explicitly opened,
-as a normal filehandle is, an C<eof()> before C<< <> >> has been
-used will cause C<@ARGV> to be examined to determine if input is
-available. Similarly, an C<eof()> after C<< <> >> has returned
-end-of-file will assume you are processing another C<@ARGV> list,
-and if you haven't set C<@ARGV>, will read input from C<STDIN>;
-see L<perlop/"I/O Operators">.
-
-In a C<< while (<>) >> loop, C<eof> or C<eof(ARGV)> can be used to
-detect the end of each file, whereas C<eof()> will detect the end
-of the very last file only. Examples:
-
- # reset line numbering on each input file
- while (<>) {
- next if /^\s*#/; # skip comments
- print "$.\t$_";
- } continue {
- close ARGV if eof; # Not eof()!
- }
-
- # insert dashes just before last line of last file
- while (<>) {
- if (eof()) { # check for end of last file
- print "--------------\n";
- }
- print;
- last if eof(); # needed if we're reading from a terminal
- }
-
-Practical hint: you almost never need to use C<eof> in Perl, because the
-input operators typically return C<undef> when they run out of data or
-encounter an error.
-
-=item eval EXPR
-X<eval> X<try> X<catch> X<evaluate> X<parse> X<execute>
-X<error, handling> X<exception, handling>
-
-=item eval BLOCK
-
-=item eval
-
-=for Pod::Functions catch exceptions or compile and run code
-
-In the first form, the return value of EXPR is parsed and executed as if it
-were a little Perl program. The value of the expression (which is itself
-determined within scalar context) is first parsed, and if there were no
-errors, executed as a block within the lexical context of the current Perl
-program. This means, that in particular, any outer lexical variables are
-visible to it, and any package variable settings or subroutine and format
-definitions remain afterwards.
-
-Note that the value is parsed every time the C<eval> executes.
-If EXPR is omitted, evaluates C<$_>. This form is typically used to
-delay parsing and subsequent execution of the text of EXPR until run time.
-
-If the C<unicode_eval> feature is enabled (which is the default under a
-C<use 5.16> or higher declaration), EXPR or C<$_> is treated as a string of
-characters, so C<use utf8> declarations have no effect, and source filters
-are forbidden. In the absence of the C<unicode_eval> feature, the string
-will sometimes be treated as characters and sometimes as bytes, depending
-on the internal encoding, and source filters activated within the C<eval>
-exhibit the erratic, but historical, behaviour of affecting some outer file
-scope that is still compiling. See also the L</evalbytes> keyword, which
-always treats its input as a byte stream and works properly with source
-filters, and the L<feature> pragma.
-
-In the second form, the code within the BLOCK is parsed only once--at the
-same time the code surrounding the C<eval> itself was parsed--and executed
-within the context of the current Perl program. This form is typically
-used to trap exceptions more efficiently than the first (see below), while
-also providing the benefit of checking the code within BLOCK at compile
-time.
-
-The final semicolon, if any, may be omitted from the value of EXPR or within
-the BLOCK.
-
-In both forms, the value returned is the value of the last expression
-evaluated inside the mini-program; a return statement may be also used, just
-as with subroutines. The expression providing the return value is evaluated
-in void, scalar, or list context, depending on the context of the C<eval>
-itself. See L</wantarray> for more on how the evaluation context can be
-determined.
-
-If there is a syntax error or runtime error, or a C<die> statement is
-executed, C<eval> returns C<undef> in scalar context
-or an empty list in list context, and C<$@> is set to the error
-message. (Prior to 5.16, a bug caused C<undef> to be returned
-in list context for syntax errors, but not for runtime errors.)
-If there was no error, C<$@> is set to the empty string. A
-control flow operator like C<last> or C<goto> can bypass the setting of
-C<$@>. Beware that using C<eval> neither silences Perl from printing
-warnings to STDERR, nor does it stuff the text of warning messages into C<$@>.
-To do either of those, you have to use the C<$SIG{__WARN__}> facility, or
-turn off warnings inside the BLOCK or EXPR using S<C<no warnings 'all'>>.
-See L</warn>, L<perlvar>, L<warnings> and L<perllexwarn>.
-
-Note that, because C<eval> traps otherwise-fatal errors, it is useful for
-determining whether a particular feature (such as C<socket> or C<symlink>)
-is implemented. It is also Perl's exception-trapping mechanism, where
-the die operator is used to raise exceptions.
-
-If you want to trap errors when loading an XS module, some problems with
-the binary interface (such as Perl version skew) may be fatal even with
-C<eval> unless C<$ENV{PERL_DL_NONLAZY}> is set. See L<perlrun>.
-
-If the code to be executed doesn't vary, you may use the eval-BLOCK
-form to trap run-time errors without incurring the penalty of
-recompiling each time. The error, if any, is still returned in C<$@>.
-Examples:
-
- # make divide-by-zero nonfatal
- eval { $answer = $a / $b; }; warn $@ if $@;
-
- # same thing, but less efficient
- eval '$answer = $a / $b'; warn $@ if $@;
-
- # a compile-time error
- eval { $answer = }; # WRONG
-
- # a run-time error
- eval '$answer ='; # sets $@
-
-Using the C<eval{}> form as an exception trap in libraries does have some
-issues. Due to the current arguably broken state of C<__DIE__> hooks, you
-may wish not to trigger any C<__DIE__> hooks that user code may have installed.
-You can use the C<local $SIG{__DIE__}> construct for this purpose,
-as this example shows:
-
- # a private exception trap for divide-by-zero
- eval { local $SIG{'__DIE__'}; $answer = $a / $b; };
- warn $@ if $@;
-
-This is especially significant, given that C<__DIE__> hooks can call
-C<die> again, which has the effect of changing their error messages:
-
- # __DIE__ hooks may modify error messages
- {
- local $SIG{'__DIE__'} =
- sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
- eval { die "foo lives here" };
- print $@ if $@; # prints "bar lives here"
- }
-
-Because this promotes action at a distance, this counterintuitive behavior
-may be fixed in a future release.
-
-With an C<eval>, you should be especially careful to remember what's
-being looked at when:
-
- eval $x; # CASE 1
- eval "$x"; # CASE 2
-
- eval '$x'; # CASE 3
- eval { $x }; # CASE 4
-
- eval "\$$x++"; # CASE 5
- $$x++; # CASE 6
-
-Cases 1 and 2 above behave identically: they run the code contained in
-the variable $x. (Although case 2 has misleading double quotes making
-the reader wonder what else might be happening (nothing is).) Cases 3
-and 4 likewise behave in the same way: they run the code C<'$x'>, which
-does nothing but return the value of $x. (Case 4 is preferred for
-purely visual reasons, but it also has the advantage of compiling at
-compile-time instead of at run-time.) Case 5 is a place where
-normally you I<would> like to use double quotes, except that in this
-particular situation, you can just use symbolic references instead, as
-in case 6.
-
-Before Perl 5.14, the assignment to C<$@> occurred before restoration
-of localized variables, which means that for your code to run on older
-versions, a temporary is required if you want to mask some but not all
-errors:
-
- # alter $@ on nefarious repugnancy only
- {
- my $e;
- {
- local $@; # protect existing $@
- eval { test_repugnancy() };
- # $@ =~ /nefarious/ and die $@; # Perl 5.14 and higher only
- $@ =~ /nefarious/ and $e = $@;
- }
- die $e if defined $e
- }
-
-C<eval BLOCK> does I<not> count as a loop, so the loop control statements
-C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
-
-An C<eval ''> executed within the C<DB> package doesn't see the usual
-surrounding lexical scope, but rather the scope of the first non-DB piece
-of code that called it. You don't normally need to worry about this unless
-you are writing a Perl debugger.
-
-=item evalbytes EXPR
-X<evalbytes>
-
-=item evalbytes
-
-=for Pod::Functions +evalbytes similar to string eval, but intend to parse a bytestream
-
-This function is like L</eval> with a string argument, except it always
-parses its argument, or C<$_> if EXPR is omitted, as a string of bytes. A
-string containing characters whose ordinal value exceeds 255 results in an
-error. Source filters activated within the evaluated code apply to the
-code itself.
-
-This function is only available under the C<evalbytes> feature, a
-C<use v5.16> (or higher) declaration, or with a C<CORE::> prefix. See
-L<feature> for more information.
-
-=item exec LIST
-X<exec> X<execute>
-
-=item exec PROGRAM LIST
-
-=for Pod::Functions abandon this program to run another
-
-The C<exec> function executes a system command I<and never returns>;
-use C<system> instead of C<exec> if you want it to return. It fails and
-returns false only if the command does not exist I<and> it is executed
-directly instead of via your system's command shell (see below).
-
-Since it's a common mistake to use C<exec> instead of C<system>, Perl
-warns you if C<exec> is called in void context and if there is a following
-statement that isn't C<die>, C<warn>, or C<exit> (if C<-w> is set--but
-you always do that, right?). If you I<really> want to follow an C<exec>
-with some other statement, you can use one of these styles to avoid the warning:
-
- exec ('foo') or print STDERR "couldn't exec foo: $!";
- { exec ('foo') }; print STDERR "couldn't exec foo: $!";
-
-If there is more than one argument in LIST, or if LIST is an array
-with more than one value, calls execvp(3) with the arguments in LIST.
-If there is only one scalar argument or an array with one element in it,
-the argument is checked for shell metacharacters, and if there are any,
-the entire argument is passed to the system's command shell for parsing
-(this is C</bin/sh -c> on Unix platforms, but varies on other platforms).
-If there are no shell metacharacters in the argument, it is split into
-words and passed directly to C<execvp>, which is more efficient.
-Examples:
-
- exec '/bin/echo', 'Your arguments are: ', @ARGV;
- exec "sort $outfile | uniq";
-
-If you don't really want to execute the first argument, but want to lie
-to the program you are executing about its own name, you can specify
-the program you actually want to run as an "indirect object" (without a
-comma) in front of the LIST. (This always forces interpretation of the
-LIST as a multivalued list, even if there is only a single scalar in
-the list.) Example:
-
- $shell = '/bin/csh';
- exec $shell '-sh'; # pretend it's a login shell
-
-or, more directly,
-
- exec {'/bin/csh'} '-sh'; # pretend it's a login shell
-
-When the arguments get executed via the system shell, results are
-subject to its quirks and capabilities. See L<perlop/"`STRING`">
-for details.
-
-Using an indirect object with C<exec> or C<system> is also more
-secure. This usage (which also works fine with system()) forces
-interpretation of the arguments as a multivalued list, even if the
-list had just one argument. That way you're safe from the shell
-expanding wildcards or splitting up words with whitespace in them.
-
- @args = ( "echo surprise" );
-
- exec @args; # subject to shell escapes
- # if @args == 1
- exec { $args[0] } @args; # safe even with one-arg list
-
-The first version, the one without the indirect object, ran the I<echo>
-program, passing it C<"surprise"> an argument. The second version didn't;
-it tried to run a program named I<"echo surprise">, didn't find it, and set
-C<$?> to a non-zero value indicating failure.
-
-Beginning with v5.6.0, Perl attempts to flush all files opened for
-output before the exec, but this may not be supported on some platforms
-(see L<perlport>). To be safe, you may need to set C<$|> ($AUTOFLUSH
-in English) or call the C<autoflush()> method of C<IO::Handle> on any
-open handles to avoid lost output.
-
-Note that C<exec> will not call your C<END> blocks, nor will it invoke
-C<DESTROY> methods on your objects.
-
-Portability issues: L<perlport/exec>.
-
-=item exists EXPR
-X<exists> X<autovivification>
-
-=for Pod::Functions test whether a hash key is present
-
-Given an expression that specifies an element of a hash, returns true if the
-specified element in the hash has ever been initialized, even if the
-corresponding value is undefined.
-
- print "Exists\n" if exists $hash{$key};
- print "Defined\n" if defined $hash{$key};
- print "True\n" if $hash{$key};
-
-exists may also be called on array elements, but its behavior is much less
-obvious and is strongly tied to the use of L</delete> on arrays. B<Be aware>
-that calling exists on array values is deprecated and likely to be removed in
-a future version of Perl.
-
- print "Exists\n" if exists $array[$index];
- print "Defined\n" if defined $array[$index];
- print "True\n" if $array[$index];
-
-A hash or array element can be true only if it's defined and defined only if
-it exists, but the reverse doesn't necessarily hold true.
-
-Given an expression that specifies the name of a subroutine,
-returns true if the specified subroutine has ever been declared, even
-if it is undefined. Mentioning a subroutine name for exists or defined
-does not count as declaring it. Note that a subroutine that does not
-exist may still be callable: its package may have an C<AUTOLOAD>
-method that makes it spring into existence the first time that it is
-called; see L<perlsub>.
-
- print "Exists\n" if exists &subroutine;
- print "Defined\n" if defined &subroutine;
-
-Note that the EXPR can be arbitrarily complicated as long as the final
-operation is a hash or array key lookup or subroutine name:
-
- if (exists $ref->{A}->{B}->{$key}) { }
- if (exists $hash{A}{B}{$key}) { }
-
- if (exists $ref->{A}->{B}->[$ix]) { }
- if (exists $hash{A}{B}[$ix]) { }
-
- if (exists &{$ref->{A}{B}{$key}}) { }
-
-Although the most deeply nested array or hash element will not spring into
-existence just because its existence was tested, any intervening ones will.
-Thus C<< $ref->{"A"} >> and C<< $ref->{"A"}->{"B"} >> will spring
-into existence due to the existence test for the $key element above.
-This happens anywhere the arrow operator is used, including even here:
-
- undef $ref;
- if (exists $ref->{"Some key"}) { }
- print $ref; # prints HASH(0x80d3d5c)
-
-This surprising autovivification in what does not at first--or even
-second--glance appear to be an lvalue context may be fixed in a future
-release.
-
-Use of a subroutine call, rather than a subroutine name, as an argument
-to exists() is an error.
-
- exists &sub; # OK
- exists &sub(); # Error
-
-=item exit EXPR
-X<exit> X<terminate> X<abort>
-
-=item exit
-
-=for Pod::Functions terminate this program
-
-Evaluates EXPR and exits immediately with that value. Example:
-
- $ans = <STDIN>;
- exit 0 if $ans =~ /^[Xx]/;
-
-See also C<die>. If EXPR is omitted, exits with C<0> status. The only
-universally recognized values for EXPR are C<0> for success and C<1>
-for error; other values are subject to interpretation depending on the
-environment in which the Perl program is running. For example, exiting
-69 (EX_UNAVAILABLE) from a I<sendmail> incoming-mail filter will cause
-the mailer to return the item undelivered, but that's not true everywhere.
-
-Don't use C<exit> to abort a subroutine if there's any chance that
-someone might want to trap whatever error happened. Use C<die> instead,
-which can be trapped by an C<eval>.
-
-The exit() function does not always exit immediately. It calls any
-defined C<END> routines first, but these C<END> routines may not
-themselves abort the exit. Likewise any object destructors that need to
-be called are called before the real exit. C<END> routines and destructors
-can change the exit status by modifying C<$?>. If this is a problem, you
-can call C<POSIX::_exit($status)> to avoid END and destructor processing.
-See L<perlmod> for details.
-
-Portability issues: L<perlport/exit>.
-
-=item exp EXPR
-X<exp> X<exponential> X<antilog> X<antilogarithm> X<e>
-
-=item exp
-
-=for Pod::Functions raise I<e> to a power
-
-Returns I<e> (the natural logarithm base) to the power of EXPR.
-If EXPR is omitted, gives C<exp($_)>.
-
-=item fc EXPR
-X<fc> X<foldcase> X<casefold> X<fold-case> X<case-fold>
-
-=item fc
-
-=for Pod::Functions +fc return casefolded version of a string
-
-Returns the casefolded version of EXPR. This is the internal function
-implementing the C<\F> escape in double-quoted strings.
-
-Casefolding is the process of mapping strings to a form where case
-differences are erased; comparing two strings in their casefolded
-form is effectively a way of asking if two strings are equal,
-regardless of case.
-
-Roughly, if you ever found yourself writing this
-
- lc($this) eq lc($that) # Wrong!
- # or
- uc($this) eq uc($that) # Also wrong!
- # or
- $this =~ /\Q$that/i # Right!
-
-Now you can write
-
- fc($this) eq fc($that)
-
-And get the correct results.
-
-Perl only implements the full form of casefolding.
-For further information on casefolding, refer to
-the Unicode Standard, specifically sections 3.13 C<Default Case Operations>,
-4.2 C<Case-Normative>, and 5.18 C<Case Mappings>,
-available at L<http://www.unicode.org/versions/latest/>, as well as the
-Case Charts available at L<http://www.unicode.org/charts/case/>.
-
-If EXPR is omitted, uses C<$_>.
-
-This function behaves the same way under various pragma, such as in a locale,
-as L</lc> does.
-
-While the Unicode Standard defines two additional forms of casefolding,
-one for Turkic languages and one that never maps one character into multiple
-characters, these are not provided by the Perl core; However, the CPAN module
-C<Unicode::Casing> may be used to provide an implementation.
-
-This keyword is available only when the C<"fc"> feature is enabled,
-or when prefixed with C<CORE::>; See L<feature>. Alternately,
-include a C<use v5.16> or later to the current scope.
-
-=item fcntl FILEHANDLE,FUNCTION,SCALAR
-X<fcntl>
-
-=for Pod::Functions file control system call
-
-Implements the fcntl(2) function. You'll probably have to say
-
- use Fcntl;
-
-first to get the correct constant definitions. Argument processing and
-value returned work just like C<ioctl> below.
-For example:
-
- use Fcntl;
- fcntl($filehandle, F_GETFL, $packed_return_buffer)
- or die "can't fcntl F_GETFL: $!";
-
-You don't have to check for C<defined> on the return from C<fcntl>.
-Like C<ioctl>, it maps a C<0> return from the system call into
-C<"0 but true"> in Perl. This string is true in boolean context and C<0>
-in numeric context. It is also exempt from the normal B<-w> warnings
-on improper numeric conversions.
-
-Note that C<fcntl> raises an exception if used on a machine that
-doesn't implement fcntl(2). See the Fcntl module or your fcntl(2)
-manpage to learn what functions are available on your system.
-
-Here's an example of setting a filehandle named C<REMOTE> to be
-non-blocking at the system level. You'll have to negotiate C<$|>
-on your own, though.
-
- use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
-
- $flags = fcntl(REMOTE, F_GETFL, 0)
- or die "Can't get flags for the socket: $!\n";
-
- $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK)
- or die "Can't set flags for the socket: $!\n";
-
-Portability issues: L<perlport/fcntl>.
-
-=item __FILE__
-X<__FILE__>
-
-=for Pod::Functions the name of the current source file
-
-A special token that returns the name of the file in which it occurs.
-
-=item fileno FILEHANDLE
-X<fileno>
-
-=for Pod::Functions return file descriptor from filehandle
-
-Returns the file descriptor for a filehandle, or undefined if the
-filehandle is not open. If there is no real file descriptor at the OS
-level, as can happen with filehandles connected to memory objects via
-C<open> with a reference for the third argument, -1 is returned.
-
-This is mainly useful for constructing
-bitmaps for C<select> and low-level POSIX tty-handling operations.
-If FILEHANDLE is an expression, the value is taken as an indirect
-filehandle, generally its name.
-
-You can use this to find out whether two handles refer to the
-same underlying descriptor:
-
- if (fileno(THIS) == fileno(THAT)) {
- print "THIS and THAT are dups\n";
- }
-
-=item flock FILEHANDLE,OPERATION
-X<flock> X<lock> X<locking>
-
-=for Pod::Functions lock an entire file with an advisory lock
-
-Calls flock(2), or an emulation of it, on FILEHANDLE. Returns true
-for success, false on failure. Produces a fatal error if used on a
-machine that doesn't implement flock(2), fcntl(2) locking, or lockf(3).
-C<flock> is Perl's portable file-locking interface, although it locks
-entire files only, not records.
-
-Two potentially non-obvious but traditional C<flock> semantics are
-that it waits indefinitely until the lock is granted, and that its locks
-are B<merely advisory>. Such discretionary locks are more flexible, but
-offer fewer guarantees. This means that programs that do not also use
-C<flock> may modify files locked with C<flock>. See L<perlport>,
-your port's specific documentation, and your system-specific local manpages
-for details. It's best to assume traditional behavior if you're writing
-portable programs. (But if you're not, you should as always feel perfectly
-free to write for your own system's idiosyncrasies (sometimes called
-"features"). Slavish adherence to portability concerns shouldn't get
-in the way of your getting your job done.)
-
-OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with
-LOCK_NB. These constants are traditionally valued 1, 2, 8 and 4, but
-you can use the symbolic names if you import them from the L<Fcntl> module,
-either individually, or as a group using the C<:flock> tag. LOCK_SH
-requests a shared lock, LOCK_EX requests an exclusive lock, and LOCK_UN
-releases a previously requested lock. If LOCK_NB is bitwise-or'ed with
-LOCK_SH or LOCK_EX, then C<flock> returns immediately rather than blocking
-waiting for the lock; check the return status to see if you got it.
-
-To avoid the possibility of miscoordination, Perl now flushes FILEHANDLE
-before locking or unlocking it.
-
-Note that the emulation built with lockf(3) doesn't provide shared
-locks, and it requires that FILEHANDLE be open with write intent. These
-are the semantics that lockf(3) implements. Most if not all systems
-implement lockf(3) in terms of fcntl(2) locking, though, so the
-differing semantics shouldn't bite too many people.
-
-Note that the fcntl(2) emulation of flock(3) requires that FILEHANDLE
-be open with read intent to use LOCK_SH and requires that it be open
-with write intent to use LOCK_EX.
-
-Note also that some versions of C<flock> cannot lock things over the
-network; you would need to use the more system-specific C<fcntl> for
-that. If you like you can force Perl to ignore your system's flock(2)
-function, and so provide its own fcntl(2)-based emulation, by passing
-the switch C<-Ud_flock> to the F<Configure> program when you configure
-and build a new Perl.
-
-Here's a mailbox appender for BSD systems.
-
- use Fcntl qw(:flock SEEK_END); # import LOCK_* and SEEK_END constants
-
- sub lock {
- my ($fh) = @_;
- flock($fh, LOCK_EX) or die "Cannot lock mailbox - $!\n";
-
- # and, in case someone appended while we were waiting...
- seek($fh, 0, SEEK_END) or die "Cannot seek - $!\n";
- }
-
- sub unlock {
- my ($fh) = @_;
- flock($fh, LOCK_UN) or die "Cannot unlock mailbox - $!\n";
- }
-
- open(my $mbox, ">>", "/usr/spool/mail/$ENV{'USER'}")
- or die "Can't open mailbox: $!";
-
- lock($mbox);
- print $mbox $msg,"\n\n";
- unlock($mbox);
-
-On systems that support a real flock(2), locks are inherited across fork()
-calls, whereas those that must resort to the more capricious fcntl(2)
-function lose their locks, making it seriously harder to write servers.
-
-See also L<DB_File> for other flock() examples.
-
-Portability issues: L<perlport/flock>.
-
-=item fork
-X<fork> X<child> X<parent>
-
-=for Pod::Functions create a new process just like this one
-
-Does a fork(2) system call to create a new process running the
-same program at the same point. It returns the child pid to the
-parent process, C<0> to the child process, or C<undef> if the fork is
-unsuccessful. File descriptors (and sometimes locks on those descriptors)
-are shared, while everything else is copied. On most systems supporting
-fork(), great care has gone into making it extremely efficient (for
-example, using copy-on-write technology on data pages), making it the
-dominant paradigm for multitasking over the last few decades.
-
-Beginning with v5.6.0, Perl attempts to flush all files opened for
-output before forking the child process, but this may not be supported
-on some platforms (see L<perlport>). To be safe, you may need to set
-C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of
-C<IO::Handle> on any open handles to avoid duplicate output.
-
-If you C<fork> without ever waiting on your children, you will
-accumulate zombies. On some systems, you can avoid this by setting
-C<$SIG{CHLD}> to C<"IGNORE">. See also L<perlipc> for more examples of
-forking and reaping moribund children.
-
-Note that if your forked child inherits system file descriptors like
-STDIN and STDOUT that are actually connected by a pipe or socket, even
-if you exit, then the remote server (such as, say, a CGI script or a
-backgrounded job launched from a remote shell) won't think you're done.
-You should reopen those to F</dev/null> if it's any issue.
-
-On some platforms such as Windows, where the fork() system call is not available,
-Perl can be built to emulate fork() in the Perl interpreter.
-The emulation is designed, at the level of the Perl program,
-to be as compatible as possible with the "Unix" fork().
-However it has limitations that have to be considered in code intended to be portable.
-See L<perlfork> for more details.
-
-Portability issues: L<perlport/fork>.
-
-=item format
-X<format>
-
-=for Pod::Functions declare a picture format with use by the write() function
-
-Declare a picture format for use by the C<write> function. For
-example:
-
- format Something =
- Test: @<<<<<<<< @||||| @>>>>>
- $str, $%, '$' . int($num)
- .
-
- $str = "widget";
- $num = $cost/$quantity;
- $~ = 'Something';
- write;
-
-See L<perlform> for many details and examples.
-
-=item formline PICTURE,LIST
-X<formline>
-
-=for Pod::Functions internal function used for formats
-
-This is an internal function used by C<format>s, though you may call it,
-too. It formats (see L<perlform>) a list of values according to the
-contents of PICTURE, placing the output into the format output
-accumulator, C<$^A> (or C<$ACCUMULATOR> in English).
-Eventually, when a C<write> is done, the contents of
-C<$^A> are written to some filehandle. You could also read C<$^A>
-and then set C<$^A> back to C<"">. Note that a format typically
-does one C<formline> per line of form, but the C<formline> function itself
-doesn't care how many newlines are embedded in the PICTURE. This means
-that the C<~> and C<~~> tokens treat the entire PICTURE as a single line.
-You may therefore need to use multiple formlines to implement a single
-record format, just like the C<format> compiler.
-
-Be careful if you put double quotes around the picture, because an C<@>
-character may be taken to mean the beginning of an array name.
-C<formline> always returns true. See L<perlform> for other examples.
-
-If you are trying to use this instead of C<write> to capture the output,
-you may find it easier to open a filehandle to a scalar
-(C<< open $fh, ">", \$output >>) and write to that instead.
-
-=item getc FILEHANDLE
-X<getc> X<getchar> X<character> X<file, read>
-
-=item getc
-
-=for Pod::Functions get the next character from the filehandle
-
-Returns the next character from the input file attached to FILEHANDLE,
-or the undefined value at end of file or if there was an error (in
-the latter case C<$!> is set). If FILEHANDLE is omitted, reads from
-STDIN. This is not particularly efficient. However, it cannot be
-used by itself to fetch single characters without waiting for the user
-to hit enter. For that, try something more like:
-
- if ($BSD_STYLE) {
- system "stty cbreak </dev/tty >/dev/tty 2>&1";
- }
- else {
- system "stty", '-icanon', 'eol', "\001";
- }
-
- $key = getc(STDIN);
-
- if ($BSD_STYLE) {
- system "stty -cbreak </dev/tty >/dev/tty 2>&1";
- }
- else {
- system 'stty', 'icanon', 'eol', '^@'; # ASCII NUL
- }
- print "\n";
-
-Determination of whether $BSD_STYLE should be set
-is left as an exercise to the reader.
-
-The C<POSIX::getattr> function can do this more portably on
-systems purporting POSIX compliance. See also the C<Term::ReadKey>
-module from your nearest CPAN site; details on CPAN can be found under
-L<perlmodlib/CPAN>.
-
-=item getlogin
-X<getlogin> X<login>
-
-=for Pod::Functions return who logged in at this tty
-
-This implements the C library function of the same name, which on most
-systems returns the current login from F</etc/utmp>, if any. If it
-returns the empty string, use C<getpwuid>.
-
- $login = getlogin || getpwuid($<) || "Kilroy";
-
-Do not consider C<getlogin> for authentication: it is not as
-secure as C<getpwuid>.
-
-Portability issues: L<perlport/getlogin>.
-
-=item getpeername SOCKET
-X<getpeername> X<peer>
-
-=for Pod::Functions find the other end of a socket connection
-
-Returns the packed sockaddr address of the other end of the SOCKET
-connection.
-
- use Socket;
- $hersockaddr = getpeername(SOCK);
- ($port, $iaddr) = sockaddr_in($hersockaddr);
- $herhostname = gethostbyaddr($iaddr, AF_INET);
- $herstraddr = inet_ntoa($iaddr);
-
-=item getpgrp PID
-X<getpgrp> X<group>
-
-=for Pod::Functions get process group
-
-Returns the current process group for the specified PID. Use
-a PID of C<0> to get the current process group for the
-current process. Will raise an exception if used on a machine that
-doesn't implement getpgrp(2). If PID is omitted, returns the process
-group of the current process. Note that the POSIX version of C<getpgrp>
-does not accept a PID argument, so only C<PID==0> is truly portable.
-
-Portability issues: L<perlport/getpgrp>.
-
-=item getppid
-X<getppid> X<parent> X<pid>
-
-=for Pod::Functions get parent process ID
-
-Returns the process id of the parent process.
-
-Note for Linux users: Between v5.8.1 and v5.16.0 Perl would work
-around non-POSIX thread semantics the minority of Linux systems (and
-Debian GNU/kFreeBSD systems) that used LinuxThreads, this emulation
-has since been removed. See the documentation for L<$$|perlvar/$$> for
-details.
-
-Portability issues: L<perlport/getppid>.
-
-=item getpriority WHICH,WHO
-X<getpriority> X<priority> X<nice>
-
-=for Pod::Functions get current nice value
-
-Returns the current priority for a process, a process group, or a user.
-(See L<getpriority(2)>.) Will raise a fatal exception if used on a
-machine that doesn't implement getpriority(2).
-
-Portability issues: L<perlport/getpriority>.
-
-=item getpwnam NAME
-X<getpwnam> X<getgrnam> X<gethostbyname> X<getnetbyname> X<getprotobyname>
-X<getpwuid> X<getgrgid> X<getservbyname> X<gethostbyaddr> X<getnetbyaddr>
-X<getprotobynumber> X<getservbyport> X<getpwent> X<getgrent> X<gethostent>
-X<getnetent> X<getprotoent> X<getservent> X<setpwent> X<setgrent> X<sethostent>
-X<setnetent> X<setprotoent> X<setservent> X<endpwent> X<endgrent> X<endhostent>
-X<endnetent> X<endprotoent> X<endservent>
-
-=for Pod::Functions get passwd record given user login name
-
-=item getgrnam NAME
-
-=for Pod::Functions get group record given group name
-
-=item gethostbyname NAME
-
-=for Pod::Functions get host record given name
-
-=item getnetbyname NAME
-
-=for Pod::Functions get networks record given name
-
-=item getprotobyname NAME
-
-=for Pod::Functions get protocol record given name
-
-=item getpwuid UID
-
-=for Pod::Functions get passwd record given user ID
-
-=item getgrgid GID
-
-=for Pod::Functions get group record given group user ID
-
-=item getservbyname NAME,PROTO
-
-=for Pod::Functions get services record given its name
-
-=item gethostbyaddr ADDR,ADDRTYPE
-
-=for Pod::Functions get host record given its address
-
-=item getnetbyaddr ADDR,ADDRTYPE
-
-=for Pod::Functions get network record given its address
-
-=item getprotobynumber NUMBER
-
-=for Pod::Functions get protocol record numeric protocol
-
-=item getservbyport PORT,PROTO
-
-=for Pod::Functions get services record given numeric port
-
-=item getpwent
-
-=for Pod::Functions get next passwd record
-
-=item getgrent
-
-=for Pod::Functions get next group record
-
-=item gethostent
-
-=for Pod::Functions get next hosts record
-
-=item getnetent
-
-=for Pod::Functions get next networks record
-
-=item getprotoent
-
-=for Pod::Functions get next protocols record
-
-=item getservent
-
-=for Pod::Functions get next services record
-
-=item setpwent
-
-=for Pod::Functions prepare passwd file for use
-
-=item setgrent
-
-=for Pod::Functions prepare group file for use
-
-=item sethostent STAYOPEN
-
-=for Pod::Functions prepare hosts file for use
-
-=item setnetent STAYOPEN
-
-=for Pod::Functions prepare networks file for use
-
-=item setprotoent STAYOPEN
-
-=for Pod::Functions prepare protocols file for use
-
-=item setservent STAYOPEN
-
-=for Pod::Functions prepare services file for use
-
-=item endpwent
-
-=for Pod::Functions be done using passwd file
-
-=item endgrent
-
-=for Pod::Functions be done using group file
-
-=item endhostent
-
-=for Pod::Functions be done using hosts file
-
-=item endnetent
-
-=for Pod::Functions be done using networks file
-
-=item endprotoent
-
-=for Pod::Functions be done using protocols file
-
-=item endservent
-
-=for Pod::Functions be done using services file
-
-These routines are the same as their counterparts in the
-system C library. In list context, the return values from the
-various get routines are as follows:
-
- ($name,$passwd,$uid,$gid,
- $quota,$comment,$gcos,$dir,$shell,$expire) = getpw*
- ($name,$passwd,$gid,$members) = getgr*
- ($name,$aliases,$addrtype,$length,@addrs) = gethost*
- ($name,$aliases,$addrtype,$net) = getnet*
- ($name,$aliases,$proto) = getproto*
- ($name,$aliases,$port,$proto) = getserv*
-
-(If the entry doesn't exist you get an empty list.)
-
-The exact meaning of the $gcos field varies but it usually contains
-the real name of the user (as opposed to the login name) and other
-information pertaining to the user. Beware, however, that in many
-system users are able to change this information and therefore it
-cannot be trusted and therefore the $gcos is tainted (see
-L<perlsec>). The $passwd and $shell, user's encrypted password and
-login shell, are also tainted, for the same reason.
-
-In scalar context, you get the name, unless the function was a
-lookup by name, in which case you get the other thing, whatever it is.
-(If the entry doesn't exist you get the undefined value.) For example:
-
- $uid = getpwnam($name);
- $name = getpwuid($num);
- $name = getpwent();
- $gid = getgrnam($name);
- $name = getgrgid($num);
- $name = getgrent();
- #etc.
-
-In I<getpw*()> the fields $quota, $comment, and $expire are special
-in that they are unsupported on many systems. If the
-$quota is unsupported, it is an empty scalar. If it is supported, it
-usually encodes the disk quota. If the $comment field is unsupported,
-it is an empty scalar. If it is supported it usually encodes some
-administrative comment about the user. In some systems the $quota
-field may be $change or $age, fields that have to do with password
-aging. In some systems the $comment field may be $class. The $expire
-field, if present, encodes the expiration period of the account or the
-password. For the availability and the exact meaning of these fields
-in your system, please consult getpwnam(3) and your system's
-F<pwd.h> file. You can also find out from within Perl what your
-$quota and $comment fields mean and whether you have the $expire field
-by using the C<Config> module and the values C<d_pwquota>, C<d_pwage>,
-C<d_pwchange>, C<d_pwcomment>, and C<d_pwexpire>. Shadow password
-files are supported only if your vendor has implemented them in the
-intuitive fashion that calling the regular C library routines gets the
-shadow versions if you're running under privilege or if there exists
-the shadow(3) functions as found in System V (this includes Solaris
-and Linux). Those systems that implement a proprietary shadow password
-facility are unlikely to be supported.
-
-The $members value returned by I<getgr*()> is a space-separated list of
-the login names of the members of the group.
-
-For the I<gethost*()> functions, if the C<h_errno> variable is supported in
-C, it will be returned to you via C<$?> if the function call fails. The
-C<@addrs> value returned by a successful call is a list of raw
-addresses returned by the corresponding library call. In the
-Internet domain, each address is four bytes long; you can unpack it
-by saying something like:
-
- ($a,$b,$c,$d) = unpack('W4',$addr[0]);
-
-The Socket library makes this slightly easier:
-
- use Socket;
- $iaddr = inet_aton("127.1"); # or whatever address
- $name = gethostbyaddr($iaddr, AF_INET);
-
- # or going the other way
- $straddr = inet_ntoa($iaddr);
-
-In the opposite way, to resolve a hostname to the IP address
-you can write this:
-
- use Socket;
- $packed_ip = gethostbyname("www.perl.org");
- if (defined $packed_ip) {
- $ip_address = inet_ntoa($packed_ip);
- }
-
-Make sure C<gethostbyname()> is called in SCALAR context and that
-its return value is checked for definedness.
-
-The C<getprotobynumber> function, even though it only takes one argument,
-has the precedence of a list operator, so beware:
-
- getprotobynumber $number eq 'icmp' # WRONG
- getprotobynumber($number eq 'icmp') # actually means this
- getprotobynumber($number) eq 'icmp' # better this way
-
-If you get tired of remembering which element of the return list
-contains which return value, by-name interfaces are provided
-in standard modules: C<File::stat>, C<Net::hostent>, C<Net::netent>,
-C<Net::protoent>, C<Net::servent>, C<Time::gmtime>, C<Time::localtime>,
-and C<User::grent>. These override the normal built-ins, supplying
-versions that return objects with the appropriate names
-for each field. For example:
-
- use File::stat;
- use User::pwent;
- $is_his = (stat($filename)->uid == pwent($whoever)->uid);
-
-Even though it looks as though they're the same method calls (uid),
-they aren't, because a C<File::stat> object is different from
-a C<User::pwent> object.
-
-Portability issues: L<perlport/getpwnam> to L<perlport/endservent>.
-
-=item getsockname SOCKET
-X<getsockname>
-
-=for Pod::Functions retrieve the sockaddr for a given socket
-
-Returns the packed sockaddr address of this end of the SOCKET connection,
-in case you don't know the address because you have several different
-IPs that the connection might have come in on.
-
- use Socket;
- $mysockaddr = getsockname(SOCK);
- ($port, $myaddr) = sockaddr_in($mysockaddr);
- printf "Connect to %s [%s]\n",
- scalar gethostbyaddr($myaddr, AF_INET),
- inet_ntoa($myaddr);
-
-=item getsockopt SOCKET,LEVEL,OPTNAME
-X<getsockopt>
-
-=for Pod::Functions get socket options on a given socket
-
-Queries the option named OPTNAME associated with SOCKET at a given LEVEL.
-Options may exist at multiple protocol levels depending on the socket
-type, but at least the uppermost socket level SOL_SOCKET (defined in the
-C<Socket> module) will exist. To query options at another level the
-protocol number of the appropriate protocol controlling the option
-should be supplied. For example, to indicate that an option is to be
-interpreted by the TCP protocol, LEVEL should be set to the protocol
-number of TCP, which you can get using C<getprotobyname>.
-
-The function returns a packed string representing the requested socket
-option, or C<undef> on error, with the reason for the error placed in
-C<$!>. Just what is in the packed string depends on LEVEL and OPTNAME;
-consult getsockopt(2) for details. A common case is that the option is an
-integer, in which case the result is a packed integer, which you can decode
-using C<unpack> with the C<i> (or C<I>) format.
-
-Here's an example to test whether Nagle's algorithm is enabled on a socket:
-
- use Socket qw(:all);
-
- defined(my $tcp = getprotobyname("tcp"))
- or die "Could not determine the protocol number for tcp";
- # my $tcp = IPPROTO_TCP; # Alternative
- my $packed = getsockopt($socket, $tcp, TCP_NODELAY)
- or die "getsockopt TCP_NODELAY: $!";
- my $nodelay = unpack("I", $packed);
- print "Nagle's algorithm is turned ", $nodelay ? "off\n" : "on\n";
-
-Portability issues: L<perlport/getsockopt>.
-
-=item glob EXPR
-X<glob> X<wildcard> X<filename, expansion> X<expand>
-
-=item glob
-
-=for Pod::Functions expand filenames using wildcards
-
-In list context, returns a (possibly empty) list of filename expansions on
-the value of EXPR such as the standard Unix shell F</bin/csh> would do. In
-scalar context, glob iterates through such filename expansions, returning
-undef when the list is exhausted. This is the internal function
-implementing the C<< <*.c> >> operator, but you can use it directly. If
-EXPR is omitted, C<$_> is used. The C<< <*.c> >> operator is discussed in
-more detail in L<perlop/"I/O Operators">.
-
-Note that C<glob> splits its arguments on whitespace and treats
-each segment as separate pattern. As such, C<glob("*.c *.h")>
-matches all files with a F<.c> or F<.h> extension. The expression
-C<glob(".* *")> matches all files in the current working directory.
-If you want to glob filenames that might contain whitespace, you'll
-have to use extra quotes around the spacey filename to protect it.
-For example, to glob filenames that have an C<e> followed by a space
-followed by an C<f>, use either of:
-
- @spacies = <"*e f*">;
- @spacies = glob '"*e f*"';
- @spacies = glob q("*e f*");
-
-If you had to get a variable through, you could do this:
-
- @spacies = glob "'*${var}e f*'";
- @spacies = glob qq("*${var}e f*");
-
-If non-empty braces are the only wildcard characters used in the
-C<glob>, no filenames are matched, but potentially many strings
-are returned. For example, this produces nine strings, one for
-each pairing of fruits and colors:
-
- @many = glob "{apple,tomato,cherry}={green,yellow,red}";
-
-Beginning with v5.6.0, this operator is implemented using the standard
-C<File::Glob> extension. See L<File::Glob> for details, including
-C<bsd_glob> which does not treat whitespace as a pattern separator.
-
-Portability issues: L<perlport/glob>.
-
-=item gmtime EXPR
-X<gmtime> X<UTC> X<Greenwich>
-
-=item gmtime
-
-=for Pod::Functions convert UNIX time into record or string using Greenwich time
-
-Works just like L</localtime> but the returned values are
-localized for the standard Greenwich time zone.
-
-Note: When called in list context, $isdst, the last value
-returned by gmtime, is always C<0>. There is no
-Daylight Saving Time in GMT.
-
-Portability issues: L<perlport/gmtime>.
-
-=item goto LABEL
-X<goto> X<jump> X<jmp>
-
-=item goto EXPR
-
-=item goto &NAME
-
-=for Pod::Functions create spaghetti code
-
-The C<goto-LABEL> form finds the statement labeled with LABEL and
-resumes execution there. It can't be used to get out of a block or
-subroutine given to C<sort>. It can be used to go almost anywhere
-else within the dynamic scope, including out of subroutines, but it's
-usually better to use some other construct such as C<last> or C<die>.
-The author of Perl has never felt the need to use this form of C<goto>
-(in Perl, that is; C is another matter). (The difference is that C
-does not offer named loops combined with loop control. Perl does, and
-this replaces most structured uses of C<goto> in other languages.)
-
-The C<goto-EXPR> form expects a label name, whose scope will be resolved
-dynamically. This allows for computed C<goto>s per FORTRAN, but isn't
-necessarily recommended if you're optimizing for maintainability:
-
- goto ("FOO", "BAR", "GLARCH")[$i];
-
-As shown in this example, C<goto-EXPR> is exempt from the "looks like a
-function" rule. A pair of parentheses following it does not (necessarily)
-delimit its argument. C<goto("NE")."XT"> is equivalent to C<goto NEXT>.
-
-Use of C<goto-LABEL> or C<goto-EXPR> to jump into a construct is
-deprecated and will issue a warning. Even then, it may not be used to
-go into any construct that requires initialization, such as a
-subroutine or a C<foreach> loop. It also can't be used to go into a
-construct that is optimized away.
-
-The C<goto-&NAME> form is quite different from the other forms of
-C<goto>. In fact, it isn't a goto in the normal sense at all, and
-doesn't have the stigma associated with other gotos. Instead, it
-exits the current subroutine (losing any changes set by local()) and
-immediately calls in its place the named subroutine using the current
-value of @_. This is used by C<AUTOLOAD> subroutines that wish to
-load another subroutine and then pretend that the other subroutine had
-been called in the first place (except that any modifications to C<@_>
-in the current subroutine are propagated to the other subroutine.)
-After the C<goto>, not even C<caller> will be able to tell that this
-routine was called first.
-
-NAME needn't be the name of a subroutine; it can be a scalar variable
-containing a code reference or a block that evaluates to a code
-reference.
-
-=item grep BLOCK LIST
-X<grep>
-
-=item grep EXPR,LIST
-
-=for Pod::Functions locate elements in a list test true against a given criterion
-
-This is similar in spirit to, but not the same as, grep(1) and its
-relatives. In particular, it is not limited to using regular expressions.
-
-Evaluates the BLOCK or EXPR for each element of LIST (locally setting
-C<$_> to each element) and returns the list value consisting of those
-elements for which the expression evaluated to true. In scalar
-context, returns the number of times the expression was true.
-
- @foo = grep(!/^#/, @bar); # weed out comments
-
-or equivalently,
-
- @foo = grep {!/^#/} @bar; # weed out comments
-
-Note that C<$_> is an alias to the list value, so it can be used to
-modify the elements of the LIST. While this is useful and supported,
-it can cause bizarre results if the elements of LIST are not variables.
-Similarly, grep returns aliases into the original list, much as a for
-loop's index variable aliases the list elements. That is, modifying an
-element of a list returned by grep (for example, in a C<foreach>, C<map>
-or another C<grep>) actually modifies the element in the original list.
-This is usually something to be avoided when writing clear code.
-
-If C<$_> is lexical in the scope where the C<grep> appears (because it has
-been declared with C<my $_>) then, in addition to being locally aliased to
-the list elements, C<$_> keeps being lexical inside the block; i.e., it
-can't be seen from the outside, avoiding any potential side-effects.
-
-See also L</map> for a list composed of the results of the BLOCK or EXPR.
-
-=item hex EXPR
-X<hex> X<hexadecimal>
-
-=item hex
-
-=for Pod::Functions convert a string to a hexadecimal number
-
-Interprets EXPR as a hex string and returns the corresponding value.
-(To convert strings that might start with either C<0>, C<0x>, or C<0b>, see
-L</oct>.) If EXPR is omitted, uses C<$_>.
-
- print hex '0xAf'; # prints '175'
- print hex 'aF'; # same
-
-Hex strings may only represent integers. Strings that would cause
-integer overflow trigger a warning. Leading whitespace is not stripped,
-unlike oct(). To present something as hex, look into L</printf>,
-L</sprintf>, and L</unpack>.
-
-=item import LIST
-X<import>
-
-=for Pod::Functions patch a module's namespace into your own
-
-There is no builtin C<import> function. It is just an ordinary
-method (subroutine) defined (or inherited) by modules that wish to export
-names to another module. The C<use> function calls the C<import> method
-for the package used. See also L</use>, L<perlmod>, and L<Exporter>.
-
-=item index STR,SUBSTR,POSITION
-X<index> X<indexOf> X<InStr>
-
-=item index STR,SUBSTR
-
-=for Pod::Functions find a substring within a string
-
-The index function searches for one string within another, but without
-the wildcard-like behavior of a full regular-expression pattern match.
-It returns the position of the first occurrence of SUBSTR in STR at
-or after POSITION. If POSITION is omitted, starts searching from the
-beginning of the string. POSITION before the beginning of the string
-or after its end is treated as if it were the beginning or the end,
-respectively. POSITION and the return value are based at zero.
-If the substring is not found, C<index> returns -1.
-
-=item int EXPR
-X<int> X<integer> X<truncate> X<trunc> X<floor>
-
-=item int
-
-=for Pod::Functions get the integer portion of a number
-
-Returns the integer portion of EXPR. If EXPR is omitted, uses C<$_>.
-You should not use this function for rounding: one because it truncates
-towards C<0>, and two because machine representations of floating-point
-numbers can sometimes produce counterintuitive results. For example,
-C<int(-6.725/0.025)> produces -268 rather than the correct -269; that's
-because it's really more like -268.99999999999994315658 instead. Usually,
-the C<sprintf>, C<printf>, or the C<POSIX::floor> and C<POSIX::ceil>
-functions will serve you better than will int().
-
-=item ioctl FILEHANDLE,FUNCTION,SCALAR
-X<ioctl>
-
-=for Pod::Functions system-dependent device control system call
-
-Implements the ioctl(2) function. You'll probably first have to say
-
- require "sys/ioctl.ph"; # probably in $Config{archlib}/sys/ioctl.ph
-
-to get the correct function definitions. If F<sys/ioctl.ph> doesn't
-exist or doesn't have the correct definitions you'll have to roll your
-own, based on your C header files such as F<< <sys/ioctl.h> >>.
-(There is a Perl script called B<h2ph> that comes with the Perl kit that
-may help you in this, but it's nontrivial.) SCALAR will be read and/or
-written depending on the FUNCTION; a C pointer to the string value of SCALAR
-will be passed as the third argument of the actual C<ioctl> call. (If SCALAR
-has no string value but does have a numeric value, that value will be
-passed rather than a pointer to the string value. To guarantee this to be
-true, add a C<0> to the scalar before using it.) The C<pack> and C<unpack>
-functions may be needed to manipulate the values of structures used by
-C<ioctl>.
-
-The return value of C<ioctl> (and C<fcntl>) is as follows:
-
- if OS returns: then Perl returns:
- -1 undefined value
- 0 string "0 but true"
- anything else that number
-
-Thus Perl returns true on success and false on failure, yet you can
-still easily determine the actual value returned by the operating
-system:
-
- $retval = ioctl(...) || -1;
- printf "System returned %d\n", $retval;
-
-The special string C<"0 but true"> is exempt from B<-w> complaints
-about improper numeric conversions.
-
-Portability issues: L<perlport/ioctl>.
-
-=item join EXPR,LIST
-X<join>
-
-=for Pod::Functions join a list into a string using a separator
-
-Joins the separate strings of LIST into a single string with fields
-separated by the value of EXPR, and returns that new string. Example:
-
- $rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
-
-Beware that unlike C<split>, C<join> doesn't take a pattern as its
-first argument. Compare L</split>.
-
-=item keys HASH
-X<keys> X<key>
-
-=item keys ARRAY
-
-=item keys EXPR
-
-=for Pod::Functions retrieve list of indices from a hash
-
-Called in list context, returns a list consisting of all the keys of the
-named hash, or in Perl 5.12 or later only, the indices of an array. Perl
-releases prior to 5.12 will produce a syntax error if you try to use an
-array argument. In scalar context, returns the number of keys or indices.
-
-The keys of a hash are returned in an apparently random order. The actual
-random order is subject to change in future versions of Perl, but it
-is guaranteed to be the same order as either the C<values> or C<each>
-function produces (given that the hash has not been modified). Since
-Perl 5.8.1 the ordering can be different even between different runs of
-Perl for security reasons (see L<perlsec/"Algorithmic Complexity
-Attacks">).
-
-As a side effect, calling keys() resets the internal interator of the HASH or ARRAY
-(see L</each>). In particular, calling keys() in void context resets
-the iterator with no other overhead.
-
-Here is yet another way to print your environment:
-
- @keys = keys %ENV;
- @values = values %ENV;
- while (@keys) {
- print pop(@keys), '=', pop(@values), "\n";
- }
-
-or how about sorted by key:
-
- foreach $key (sort(keys %ENV)) {
- print $key, '=', $ENV{$key}, "\n";
- }
-
-The returned values are copies of the original keys in the hash, so
-modifying them will not affect the original hash. Compare L</values>.
-
-To sort a hash by value, you'll need to use a C<sort> function.
-Here's a descending numeric sort of a hash by its values:
-
- foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) {
- printf "%4d %s\n", $hash{$key}, $key;
- }
-
-Used as an lvalue, C<keys> allows you to increase the number of hash buckets
-allocated for the given hash. This can gain you a measure of efficiency if
-you know the hash is going to get big. (This is similar to pre-extending
-an array by assigning a larger number to $#array.) If you say
-
- keys %hash = 200;
-
-then C<%hash> will have at least 200 buckets allocated for it--256 of them,
-in fact, since it rounds up to the next power of two. These
-buckets will be retained even if you do C<%hash = ()>, use C<undef
-%hash> if you want to free the storage while C<%hash> is still in scope.
-You can't shrink the number of buckets allocated for the hash using
-C<keys> in this way (but you needn't worry about doing this by accident,
-as trying has no effect). C<keys @array> in an lvalue context is a syntax
-error.
-
-Starting with Perl 5.14, C<keys> can take a scalar EXPR, which must contain
-a reference to an unblessed hash or array. The argument will be
-dereferenced automatically. This aspect of C<keys> is considered highly
-experimental. The exact behaviour may change in a future version of Perl.
-
- for (keys $hashref) { ... }
- for (keys $obj->get_arrayref) { ... }
-
-To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work I<only> on Perls of
-a recent vintage:
-
- use 5.012; # so keys/values/each work on arrays
- use 5.014; # so keys/values/each work on scalars (experimental)
-
-See also C<each>, C<values>, and C<sort>.
-
-=item kill SIGNAL, LIST
-
-=item kill SIGNAL
-X<kill> X<signal>
-
-=for Pod::Functions send a signal to a process or process group
-
-Sends a signal to a list of processes. Returns the number of
-processes successfully signaled (which is not necessarily the
-same as the number actually killed).
-
- $cnt = kill 1, $child1, $child2;
- kill 9, @goners;
-
-If SIGNAL is zero, no signal is sent to the process, but C<kill>
-checks whether it's I<possible> to send a signal to it (that
-means, to be brief, that the process is owned by the same user, or we are
-the super-user). This is useful to check that a child process is still
-alive (even if only as a zombie) and hasn't changed its UID. See
-L<perlport> for notes on the portability of this construct.
-
-Unlike in the shell, if SIGNAL is negative, it kills process groups instead
-of processes. That means you usually
-want to use positive not negative signals.
-You may also use a signal name in quotes.
-
-The behavior of kill when a I<PROCESS> number is zero or negative depends on
-the operating system. For example, on POSIX-conforming systems, zero will
-signal the current process group and -1 will signal all processes.
-
-See L<perlipc/"Signals"> for more details.
-
-On some platforms such as Windows where the fork() system call is not available.
-Perl can be built to emulate fork() at the interpreter level.
-This emulation has limitations related to kill that have to be considered,
-for code running on Windows and in code intended to be portable.
-
-See L<perlfork> for more details.
-
-If there is no I<LIST> of processes, no signal is sent, and the return
-value is 0. This form is sometimes used, however, because it causes
-tainting checks to be run. But see
-L<perlsec/Laundering and Detecting Tainted Data>.
-
-Portability issues: L<perlport/kill>.
-
-=item last LABEL
-X<last> X<break>
-
-=item last
-
-=for Pod::Functions exit a block prematurely
-
-The C<last> command is like the C<break> statement in C (as used in
-loops); it immediately exits the loop in question. If the LABEL is
-omitted, the command refers to the innermost enclosing loop. The
-C<continue> block, if any, is not executed:
-
- LINE: while (<STDIN>) {
- last LINE if /^$/; # exit when done with header
- #...
- }
-
-C<last> cannot be used to exit a block that returns a value such as
-C<eval {}>, C<sub {}>, or C<do {}>, and should not be used to exit
-a grep() or map() operation.
-
-Note that a block by itself is semantically identical to a loop
-that executes once. Thus C<last> can be used to effect an early
-exit out of such a block.
-
-See also L</continue> for an illustration of how C<last>, C<next>, and
-C<redo> work.
-
-=item lc EXPR
-X<lc> X<lowercase>
-
-=item lc
-
-=for Pod::Functions return lower-case version of a string
-
-Returns a lowercased version of EXPR. This is the internal function
-implementing the C<\L> escape in double-quoted strings.
-
-If EXPR is omitted, uses C<$_>.
-
-What gets returned depends on several factors:
-
-=over
-
-=item If C<use bytes> is in effect:
-
-=over
-
-=item On EBCDIC platforms
-
-The results are what the C language system call C<tolower()> returns.
-
-=item On ASCII platforms
-
-The results follow ASCII semantics. Only characters C<A-Z> change, to C<a-z>
-respectively.
-
-=back
-
-=item Otherwise, if C<use locale> (but not C<use locale ':not_characters'>) is in effect:
-
-Respects current LC_CTYPE locale for code points < 256; and uses Unicode
-semantics for the remaining code points (this last can only happen if
-the UTF8 flag is also set). See L<perllocale>.
-
-A deficiency in this is that case changes that cross the 255/256
-boundary are not well-defined. For example, the lower case of LATIN CAPITAL
-LETTER SHARP S (U+1E9E) in Unicode semantics is U+00DF (on ASCII
-platforms). But under C<use locale>, the lower case of U+1E9E is
-itself, because 0xDF may not be LATIN SMALL LETTER SHARP S in the
-current locale, and Perl has no way of knowing if that character even
-exists in the locale, much less what code point it is. Perl returns
-the input character unchanged, for all instances (and there aren't
-many) where the 255/256 boundary would otherwise be crossed.
-
-=item Otherwise, If EXPR has the UTF8 flag set:
-
-Unicode semantics are used for the case change.
-
-=item Otherwise, if C<use feature 'unicode_strings'> or C<use locale ':not_characters'>) is in effect:
-
-Unicode semantics are used for the case change.
-
-=item Otherwise:
-
-=over
-
-=item On EBCDIC platforms
-
-The results are what the C language system call C<tolower()> returns.
-
-=item On ASCII platforms
-
-ASCII semantics are used for the case change. The lowercase of any character
-outside the ASCII range is the character itself.
-
-=back
-
-=back
-
-=item lcfirst EXPR
-X<lcfirst> X<lowercase>
-
-=item lcfirst
-
-=for Pod::Functions return a string with just the next letter in lower case
-
-Returns the value of EXPR with the first character lowercased. This
-is the internal function implementing the C<\l> escape in
-double-quoted strings.
-
-If EXPR is omitted, uses C<$_>.
-
-This function behaves the same way under various pragmata, such as in a locale,
-as L</lc> does.
-
-=item length EXPR
-X<length> X<size>
-
-=item length
-
-=for Pod::Functions return the number of bytes in a string
-
-Returns the length in I<characters> of the value of EXPR. If EXPR is
-omitted, returns the length of C<$_>. If EXPR is undefined, returns
-C<undef>.
-
-This function cannot be used on an entire array or hash to find out how
-many elements these have. For that, use C<scalar @array> and C<scalar keys
-%hash>, respectively.
-
-Like all Perl character operations, length() normally deals in logical
-characters, not physical bytes. For how many bytes a string encoded as
-UTF-8 would take up, use C<length(Encode::encode_utf8(EXPR))> (you'll have
-to C<use Encode> first). See L<Encode> and L<perlunicode>.
-
-=item __LINE__
-X<__LINE__>
-
-=for Pod::Functions the current source line number
-
-A special token that compiles to the current line number.
-
-=item link OLDFILE,NEWFILE
-X<link>
-
-=for Pod::Functions create a hard link in the filesystem
-
-Creates a new filename linked to the old filename. Returns true for
-success, false otherwise.
-
-Portability issues: L<perlport/link>.
-
-=item listen SOCKET,QUEUESIZE
-X<listen>
-
-=for Pod::Functions register your socket as a server
-
-Does the same thing that the listen(2) system call does. Returns true if
-it succeeded, false otherwise. See the example in
-L<perlipc/"Sockets: Client/Server Communication">.
-
-=item local EXPR
-X<local>
-
-=for Pod::Functions create a temporary value for a global variable (dynamic scoping)
-
-You really probably want to be using C<my> instead, because C<local> isn't
-what most people think of as "local". See
-L<perlsub/"Private Variables via my()"> for details.
-
-A local modifies the listed variables to be local to the enclosing
-block, file, or eval. If more than one value is listed, the list must
-be placed in parentheses. See L<perlsub/"Temporary Values via local()">
-for details, including issues with tied arrays and hashes.
-
-The C<delete local EXPR> construct can also be used to localize the deletion
-of array/hash elements to the current block.
-See L<perlsub/"Localized deletion of elements of composite types">.
-
-=item localtime EXPR
-X<localtime> X<ctime>
-
-=item localtime
-
-=for Pod::Functions convert UNIX time into record or string using local time
-
-Converts a time as returned by the time function to a 9-element list
-with the time analyzed for the local time zone. Typically used as
-follows:
-
- # 0 1 2 3 4 5 6 7 8
- ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
- localtime(time);
-
-All list elements are numeric and come straight out of the C `struct
-tm'. C<$sec>, C<$min>, and C<$hour> are the seconds, minutes, and hours
-of the specified time.
-
-C<$mday> is the day of the month and C<$mon> the month in
-the range C<0..11>, with 0 indicating January and 11 indicating December.
-This makes it easy to get a month name from a list:
-
- my @abbr = qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec );
- print "$abbr[$mon] $mday";
- # $mon=9, $mday=18 gives "Oct 18"
-
-C<$year> contains the number of years since 1900. To get a 4-digit
-year write:
-
- $year += 1900;
-
-To get the last two digits of the year (e.g., "01" in 2001) do:
-
- $year = sprintf("%02d", $year % 100);
-
-C<$wday> is the day of the week, with 0 indicating Sunday and 3 indicating
-Wednesday. C<$yday> is the day of the year, in the range C<0..364>
-(or C<0..365> in leap years.)
-
-C<$isdst> is true if the specified time occurs during Daylight Saving
-Time, false otherwise.
-
-If EXPR is omitted, C<localtime()> uses the current time (as returned
-by time(3)).
-
-In scalar context, C<localtime()> returns the ctime(3) value:
-
- $now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994"
-
-The format of this scalar value is B<not> locale-dependent
-but built into Perl. For GMT instead of local
-time use the L</gmtime> builtin. See also the
-C<Time::Local> module (for converting seconds, minutes, hours, and such back to
-the integer value returned by time()), and the L<POSIX> module's strftime(3)
-and mktime(3) functions.
-
-To get somewhat similar but locale-dependent date strings, set up your
-locale environment variables appropriately (please see L<perllocale>) and
-try for example:
-
- use POSIX qw(strftime);
- $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
- # or for GMT formatted appropriately for your locale:
- $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;
-
-Note that the C<%a> and C<%b>, the short forms of the day of the week
-and the month of the year, may not necessarily be three characters wide.
-
-The L<Time::gmtime> and L<Time::localtime> modules provide a convenient,
-by-name access mechanism to the gmtime() and localtime() functions,
-respectively.
-
-For a comprehensive date and time representation look at the
-L<DateTime> module on CPAN.
-
-Portability issues: L<perlport/localtime>.
-
-=item lock THING
-X<lock>
-
-=for Pod::Functions +5.005 get a thread lock on a variable, subroutine, or method
-
-This function places an advisory lock on a shared variable or referenced
-object contained in I<THING> until the lock goes out of scope.
-
-The value returned is the scalar itself, if the argument is a scalar, or a
-reference, if the argument is a hash, array or subroutine.
-
-lock() is a "weak keyword" : this means that if you've defined a function
-by this name (before any calls to it), that function will be called
-instead. If you are not under C<use threads::shared> this does nothing.
-See L<threads::shared>.
-
-=item log EXPR
-X<log> X<logarithm> X<e> X<ln> X<base>
-
-=item log
-
-=for Pod::Functions retrieve the natural logarithm for a number
-
-Returns the natural logarithm (base I<e>) of EXPR. If EXPR is omitted,
-returns the log of C<$_>. To get the
-log of another base, use basic algebra:
-The base-N log of a number is equal to the natural log of that number
-divided by the natural log of N. For example:
-
- sub log10 {
- my $n = shift;
- return log($n)/log(10);
- }
-
-See also L</exp> for the inverse operation.
-
-=item lstat FILEHANDLE
-X<lstat>
-
-=item lstat EXPR
-
-=item lstat DIRHANDLE
-
-=item lstat
-
-=for Pod::Functions stat a symbolic link
-
-Does the same thing as the C<stat> function (including setting the
-special C<_> filehandle) but stats a symbolic link instead of the file
-the symbolic link points to. If symbolic links are unimplemented on
-your system, a normal C<stat> is done. For much more detailed
-information, please see the documentation for C<stat>.
-
-If EXPR is omitted, stats C<$_>.
-
-Portability issues: L<perlport/lstat>.
-
-=item m//
-
-=for Pod::Functions match a string with a regular expression pattern
-
-The match operator. See L<perlop/"Regexp Quote-Like Operators">.
-
-=item map BLOCK LIST
-X<map>
-
-=item map EXPR,LIST
-
-=for Pod::Functions apply a change to a list to get back a new list with the changes
-
-Evaluates the BLOCK or EXPR for each element of LIST (locally setting
-C<$_> to each element) and returns the list value composed of the
-results of each such evaluation. In scalar context, returns the
-total number of elements so generated. Evaluates BLOCK or EXPR in
-list context, so each element of LIST may produce zero, one, or
-more elements in the returned value.
-
- @chars = map(chr, @numbers);
-
-translates a list of numbers to the corresponding characters.
-
- my @squares = map { $_ * $_ } @numbers;
-
-translates a list of numbers to their squared values.
-
- my @squares = map { $_ > 5 ? ($_ * $_) : () } @numbers;
-
-shows that number of returned elements can differ from the number of
-input elements. To omit an element, return an empty list ().
-This could also be achieved by writing
-
- my @squares = map { $_ * $_ } grep { $_ > 5 } @numbers;
-
-which makes the intention more clear.
-
-Map always returns a list, which can be
-assigned to a hash such that the elements
-become key/value pairs. See L<perldata> for more details.
-
- %hash = map { get_a_key_for($_) => $_ } @array;
-
-is just a funny way to write
-
- %hash = ();
- foreach (@array) {
- $hash{get_a_key_for($_)} = $_;
- }
-
-Note that C<$_> is an alias to the list value, so it can be used to
-modify the elements of the LIST. While this is useful and supported,
-it can cause bizarre results if the elements of LIST are not variables.
-Using a regular C<foreach> loop for this purpose would be clearer in
-most cases. See also L</grep> for an array composed of those items of
-the original list for which the BLOCK or EXPR evaluates to true.
-
-If C<$_> is lexical in the scope where the C<map> appears (because it has
-been declared with C<my $_>), then, in addition to being locally aliased to
-the list elements, C<$_> keeps being lexical inside the block; that is, it
-can't be seen from the outside, avoiding any potential side-effects.
-
-C<{> starts both hash references and blocks, so C<map { ...> could be either
-the start of map BLOCK LIST or map EXPR, LIST. Because Perl doesn't look
-ahead for the closing C<}> it has to take a guess at which it's dealing with
-based on what it finds just after the
-C<{>. Usually it gets it right, but if it
-doesn't it won't realize something is wrong until it gets to the C<}> and
-encounters the missing (or unexpected) comma. The syntax error will be
-reported close to the C<}>, but you'll need to change something near the C<{>
-such as using a unary C<+> to give Perl some help:
-
- %hash = map { "\L$_" => 1 } @array # perl guesses EXPR. wrong
- %hash = map { +"\L$_" => 1 } @array # perl guesses BLOCK. right
- %hash = map { ("\L$_" => 1) } @array # this also works
- %hash = map { lc($_) => 1 } @array # as does this.
- %hash = map +( lc($_) => 1 ), @array # this is EXPR and works!
-
- %hash = map ( lc($_), 1 ), @array # evaluates to (1, @array)
-
-or to force an anon hash constructor use C<+{>:
-
- @hashes = map +{ lc($_) => 1 }, @array # EXPR, so needs comma at end
-
-to get a list of anonymous hashes each with only one entry apiece.
-
-=item mkdir FILENAME,MASK
-X<mkdir> X<md> X<directory, create>
-
-=item mkdir FILENAME
-
-=item mkdir
-
-=for Pod::Functions create a directory
-
-Creates the directory specified by FILENAME, with permissions
-specified by MASK (as modified by C<umask>). If it succeeds it
-returns true; otherwise it returns false and sets C<$!> (errno).
-MASK defaults to 0777 if omitted, and FILENAME defaults
-to C<$_> if omitted.
-
-In general, it is better to create directories with a permissive MASK
-and let the user modify that with their C<umask> than it is to supply
-a restrictive MASK and give the user no way to be more permissive.
-The exceptions to this rule are when the file or directory should be
-kept private (mail files, for instance). The perlfunc(1) entry on
-C<umask> discusses the choice of MASK in more detail.
-
-Note that according to the POSIX 1003.1-1996 the FILENAME may have any
-number of trailing slashes. Some operating and filesystems do not get
-this right, so Perl automatically removes all trailing slashes to keep
-everyone happy.
-
-To recursively create a directory structure, look at
-the C<mkpath> function of the L<File::Path> module.
-
-=item msgctl ID,CMD,ARG
-X<msgctl>
-
-=for Pod::Functions SysV IPC message control operations
-
-Calls the System V IPC function msgctl(2). You'll probably have to say
-
- use IPC::SysV;
-
-first to get the correct constant definitions. If CMD is C<IPC_STAT>,
-then ARG must be a variable that will hold the returned C<msqid_ds>
-structure. Returns like C<ioctl>: the undefined value for error,
-C<"0 but true"> for zero, or the actual return value otherwise. See also
-L<perlipc/"SysV IPC"> and the documentation for C<IPC::SysV> and
-C<IPC::Semaphore>.
-
-Portability issues: L<perlport/msgctl>.
-
-=item msgget KEY,FLAGS
-X<msgget>
-
-=for Pod::Functions get SysV IPC message queue
-
-Calls the System V IPC function msgget(2). Returns the message queue
-id, or C<undef> on error. See also
-L<perlipc/"SysV IPC"> and the documentation for C<IPC::SysV> and
-C<IPC::Msg>.
-
-Portability issues: L<perlport/msgget>.
-
-=item msgrcv ID,VAR,SIZE,TYPE,FLAGS
-X<msgrcv>
-
-=for Pod::Functions receive a SysV IPC message from a message queue
-
-Calls the System V IPC function msgrcv to receive a message from
-message queue ID into variable VAR with a maximum message size of
-SIZE. Note that when a message is received, the message type as a
-native long integer will be the first thing in VAR, followed by the
-actual message. This packing may be opened with C<unpack("l! a*")>.
-Taints the variable. Returns true if successful, false
-on error. See also L<perlipc/"SysV IPC"> and the documentation for
-C<IPC::SysV> and C<IPC::SysV::Msg>.
-
-Portability issues: L<perlport/msgrcv>.
-
-=item msgsnd ID,MSG,FLAGS
-X<msgsnd>
-
-=for Pod::Functions send a SysV IPC message to a message queue
-
-Calls the System V IPC function msgsnd to send the message MSG to the
-message queue ID. MSG must begin with the native long integer message
-type, be followed by the length of the actual message, and then finally
-the message itself. This kind of packing can be achieved with
-C<pack("l! a*", $type, $message)>. Returns true if successful,
-false on error. See also the C<IPC::SysV>
-and C<IPC::SysV::Msg> documentation.
-
-Portability issues: L<perlport/msgsnd>.
-
-=item my EXPR
-X<my>
-
-=item my TYPE EXPR
-
-=item my EXPR : ATTRS
-
-=item my TYPE EXPR : ATTRS
-
-=for Pod::Functions declare and assign a local variable (lexical scoping)
-
-A C<my> declares the listed variables to be local (lexically) to the
-enclosing block, file, or C<eval>. If more than one value is listed,
-the list must be placed in parentheses.
-
-The exact semantics and interface of TYPE and ATTRS are still
-evolving. TYPE is currently bound to the use of the C<fields> pragma,
-and attributes are handled using the C<attributes> pragma, or starting
-from Perl 5.8.0 also via the C<Attribute::Handlers> module. See
-L<perlsub/"Private Variables via my()"> for details, and L<fields>,
-L<attributes>, and L<Attribute::Handlers>.
-
-=item next LABEL
-X<next> X<continue>
-
-=item next
-
-=for Pod::Functions iterate a block prematurely
-
-The C<next> command is like the C<continue> statement in C; it starts
-the next iteration of the loop:
-
- LINE: while (<STDIN>) {
- next LINE if /^#/; # discard comments
- #...
- }
-
-Note that if there were a C<continue> block on the above, it would get
-executed even on discarded lines. If LABEL is omitted, the command
-refers to the innermost enclosing loop.
-
-C<next> cannot be used to exit a block which returns a value such as
-C<eval {}>, C<sub {}>, or C<do {}>, and should not be used to exit
-a grep() or map() operation.
-
-Note that a block by itself is semantically identical to a loop
-that executes once. Thus C<next> will exit such a block early.
-
-See also L</continue> for an illustration of how C<last>, C<next>, and
-C<redo> work.
-
-=item no MODULE VERSION LIST
-X<no declarations>
-X<unimporting>
-
-=item no MODULE VERSION
-
-=item no MODULE LIST
-
-=item no MODULE
-
-=item no VERSION
-
-=for Pod::Functions unimport some module symbols or semantics at compile time
-
-See the C<use> function, of which C<no> is the opposite.
-
-=item oct EXPR
-X<oct> X<octal> X<hex> X<hexadecimal> X<binary> X<bin>
-
-=item oct
-
-=for Pod::Functions convert a string to an octal number
-
-Interprets EXPR as an octal string and returns the corresponding
-value. (If EXPR happens to start off with C<0x>, interprets it as a
-hex string. If EXPR starts off with C<0b>, it is interpreted as a
-binary string. Leading whitespace is ignored in all three cases.)
-The following will handle decimal, binary, octal, and hex in standard
-Perl notation:
-
- $val = oct($val) if $val =~ /^0/;
-
-If EXPR is omitted, uses C<$_>. To go the other way (produce a number
-in octal), use sprintf() or printf():
-
- $dec_perms = (stat("filename"))[2] & 07777;
- $oct_perm_str = sprintf "%o", $perms;
-
-The oct() function is commonly used when a string such as C<644> needs
-to be converted into a file mode, for example. Although Perl
-automatically converts strings into numbers as needed, this automatic
-conversion assumes base 10.
-
-Leading white space is ignored without warning, as too are any trailing
-non-digits, such as a decimal point (C<oct> only handles non-negative
-integers, not negative integers or floating point).
-
-=item open FILEHANDLE,EXPR
-X<open> X<pipe> X<file, open> X<fopen>
-
-=item open FILEHANDLE,MODE,EXPR
-
-=item open FILEHANDLE,MODE,EXPR,LIST
-
-=item open FILEHANDLE,MODE,REFERENCE
-
-=item open FILEHANDLE
-
-=for Pod::Functions open a file, pipe, or descriptor
-
-Opens the file whose filename is given by EXPR, and associates it with
-FILEHANDLE.
-
-Simple examples to open a file for reading:
-
- open(my $fh, "<", "input.txt")
- or die "cannot open < input.txt: $!";
-
-and for writing:
-
- open(my $fh, ">", "output.txt")
- or die "cannot open > output.txt: $!";
-
-(The following is a comprehensive reference to open(): for a gentler
-introduction you may consider L<perlopentut>.)
-
-If FILEHANDLE is an undefined scalar variable (or array or hash element), a
-new filehandle is autovivified, meaning that the variable is assigned a
-reference to a newly allocated anonymous filehandle. Otherwise if
-FILEHANDLE is an expression, its value is the real filehandle. (This is
-considered a symbolic reference, so C<use strict "refs"> should I<not> be
-in effect.)
-
-If EXPR is omitted, the global (package) scalar variable of the same
-name as the FILEHANDLE contains the filename. (Note that lexical
-variables--those declared with C<my> or C<state>--will not work for this
-purpose; so if you're using C<my> or C<state>, specify EXPR in your
-call to open.)
-
-If three (or more) arguments are specified, the open mode (including
-optional encoding) in the second argument are distinct from the filename in
-the third. If MODE is C<< < >> or nothing, the file is opened for input.
-If MODE is C<< > >>, the file is opened for output, with existing files
-first being truncated ("clobbered") and nonexisting files newly created.
-If MODE is C<<< >> >>>, the file is opened for appending, again being
-created if necessary.
-
-You can put a C<+> in front of the C<< > >> or C<< < >> to
-indicate that you want both read and write access to the file; thus
-C<< +< >> is almost always preferred for read/write updates--the
-C<< +> >> mode would clobber the file first. You can't usually use
-either read-write mode for updating textfiles, since they have
-variable-length records. See the B<-i> switch in L<perlrun> for a
-better approach. The file is created with permissions of C<0666>
-modified by the process's C<umask> value.
-
-These various prefixes correspond to the fopen(3) modes of C<r>,
-C<r+>, C<w>, C<w+>, C<a>, and C<a+>.
-
-In the one- and two-argument forms of the call, the mode and filename
-should be concatenated (in that order), preferably separated by white
-space. You can--but shouldn't--omit the mode in these forms when that mode
-is C<< < >>. It is always safe to use the two-argument form of C<open> if
-the filename argument is a known literal.
-
-For three or more arguments if MODE is C<|->, the filename is
-interpreted as a command to which output is to be piped, and if MODE
-is C<-|>, the filename is interpreted as a command that pipes
-output to us. In the two-argument (and one-argument) form, one should
-replace dash (C<->) with the command.
-See L<perlipc/"Using open() for IPC"> for more examples of this.
-(You are not allowed to C<open> to a command that pipes both in I<and>
-out, but see L<IPC::Open2>, L<IPC::Open3>, and
-L<perlipc/"Bidirectional Communication with Another Process"> for
-alternatives.)
-
-In the form of pipe opens taking three or more arguments, if LIST is specified
-(extra arguments after the command name) then LIST becomes arguments
-to the command invoked if the platform supports it. The meaning of
-C<open> with more than three arguments for non-pipe modes is not yet
-defined, but experimental "layers" may give extra LIST arguments
-meaning.
-
-In the two-argument (and one-argument) form, opening C<< <- >>
-or C<-> opens STDIN and opening C<< >- >> opens STDOUT.
-
-You may (and usually should) use the three-argument form of open to specify
-I/O layers (sometimes referred to as "disciplines") to apply to the handle
-that affect how the input and output are processed (see L<open> and
-L<PerlIO> for more details). For example:
-
- open(my $fh, "<:encoding(UTF-8)", "filename")
- || die "can't open UTF-8 encoded filename: $!";
-
-opens the UTF8-encoded file containing Unicode characters;
-see L<perluniintro>. Note that if layers are specified in the
-three-argument form, then default layers stored in ${^OPEN} (see L<perlvar>;
-usually set by the B<open> pragma or the switch B<-CioD>) are ignored.
-Those layers will also be ignored if you specifying a colon with no name
-following it. In that case the default layer for the operating system
-(:raw on Unix, :crlf on Windows) is used.
-
-Open returns nonzero on success, the undefined value otherwise. If
-the C<open> involved a pipe, the return value happens to be the pid of
-the subprocess.
-
-If you're running Perl on a system that distinguishes between text
-files and binary files, then you should check out L</binmode> for tips
-for dealing with this. The key distinction between systems that need
-C<binmode> and those that don't is their text file formats. Systems
-like Unix, Mac OS, and Plan 9, that end lines with a single
-character and encode that character in C as C<"\n"> do not
-need C<binmode>. The rest need it.
-
-When opening a file, it's seldom a good idea to continue
-if the request failed, so C<open> is frequently used with
-C<die>. Even if C<die> won't do what you want (say, in a CGI script,
-where you want to format a suitable error message (but there are
-modules that can help with that problem)) always check
-the return value from opening a file.
-
-As a special case the three-argument form with a read/write mode and the third
-argument being C<undef>:
-
- open(my $tmp, "+>", undef) or die ...
-
-opens a filehandle to an anonymous temporary file. Also using C<< +< >>
-works for symmetry, but you really should consider writing something
-to the temporary file first. You will need to seek() to do the
-reading.
-
-Since v5.8.0, Perl has built using PerlIO by default. Unless you've
-changed this (such as building Perl with C<Configure -Uuseperlio>), you can
-open filehandles directly to Perl scalars via:
-
- open($fh, ">", \$variable) || ..
-
-To (re)open C<STDOUT> or C<STDERR> as an in-memory file, close it first:
-
- close STDOUT;
- open(STDOUT, ">", \$variable)
- or die "Can't open STDOUT: $!";
-
-General examples:
-
- $ARTICLE = 100;
- open(ARTICLE) or die "Can't find article $ARTICLE: $!\n";
- while (<ARTICLE>) {...
-
- open(LOG, ">>/usr/spool/news/twitlog"); # (log is reserved)
- # if the open fails, output is discarded
-
- open(my $dbase, "+<", "dbase.mine") # open for update
- or die "Can't open 'dbase.mine' for update: $!";
-
- open(my $dbase, "+<dbase.mine") # ditto
- or die "Can't open 'dbase.mine' for update: $!";
-
- open(ARTICLE, "-|", "caesar <$article") # decrypt article
- or die "Can't start caesar: $!";
-
- open(ARTICLE, "caesar <$article |") # ditto
- or die "Can't start caesar: $!";
-
- open(EXTRACT, "|sort >Tmp$$") # $$ is our process id
- or die "Can't start sort: $!";
-
- # in-memory files
- open(MEMORY, ">", \$var)
- or die "Can't open memory file: $!";
- print MEMORY "foo!\n"; # output will appear in $var
-
- # process argument list of files along with any includes
-
- foreach $file (@ARGV) {
- process($file, "fh00");
- }
-
- sub process {
- my($filename, $input) = @_;
- $input++; # this is a string increment
- unless (open($input, "<", $filename)) {
- print STDERR "Can't open $filename: $!\n";
- return;
- }
-
- local $_;
- while (<$input>) { # note use of indirection
- if (/^#include "(.*)"/) {
- process($1, $input);
- next;
- }
- #... # whatever
- }
- }
-
-See L<perliol> for detailed info on PerlIO.
-
-You may also, in the Bourne shell tradition, specify an EXPR beginning
-with C<< >& >>, in which case the rest of the string is interpreted
-as the name of a filehandle (or file descriptor, if numeric) to be
-duped (as C<dup(2)>) and opened. You may use C<&> after C<< > >>,
-C<<< >> >>>, C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>.
-The mode you specify should match the mode of the original filehandle.
-(Duping a filehandle does not take into account any existing contents
-of IO buffers.) If you use the three-argument
-form, then you can pass either a
-number, the name of a filehandle, or the normal "reference to a glob".
-
-Here is a script that saves, redirects, and restores C<STDOUT> and
-C<STDERR> using various methods:
-
- #!/usr/bin/perl
- open(my $oldout, ">&STDOUT") or die "Can't dup STDOUT: $!";
- open(OLDERR, ">&", \*STDERR) or die "Can't dup STDERR: $!";
-
- open(STDOUT, '>', "foo.out") or die "Can't redirect STDOUT: $!";
- open(STDERR, ">&STDOUT") or die "Can't dup STDOUT: $!";
-
- select STDERR; $| = 1; # make unbuffered
- select STDOUT; $| = 1; # make unbuffered
-
- print STDOUT "stdout 1\n"; # this works for
- print STDERR "stderr 1\n"; # subprocesses too
-
- open(STDOUT, ">&", $oldout) or die "Can't dup \$oldout: $!";
- open(STDERR, ">&OLDERR") or die "Can't dup OLDERR: $!";
-
- print STDOUT "stdout 2\n";
- print STDERR "stderr 2\n";
-
-If you specify C<< '<&=X' >>, where C<X> is a file descriptor number
-or a filehandle, then Perl will do an equivalent of C's C<fdopen> of
-that file descriptor (and not call C<dup(2)>); this is more
-parsimonious of file descriptors. For example:
-
- # open for input, reusing the fileno of $fd
- open(FILEHANDLE, "<&=$fd")
-
-or
-
- open(FILEHANDLE, "<&=", $fd)
-
-or
-
- # open for append, using the fileno of OLDFH
- open(FH, ">>&=", OLDFH)
-
-or
-
- open(FH, ">>&=OLDFH")
-
-Being parsimonious on filehandles is also useful (besides being
-parsimonious) for example when something is dependent on file
-descriptors, like for example locking using flock(). If you do just
-C<< open(A, ">>&B") >>, the filehandle A will not have the same file
-descriptor as B, and therefore flock(A) will not flock(B) nor vice
-versa. But with C<< open(A, ">>&=B") >>, the filehandles will share
-the same underlying system file descriptor.
-
-Note that under Perls older than 5.8.0, Perl uses the standard C library's'
-fdopen() to implement the C<=> functionality. On many Unix systems,
-fdopen() fails when file descriptors exceed a certain value, typically 255.
-For Perls 5.8.0 and later, PerlIO is (most often) the default.
-
-You can see whether your Perl was built with PerlIO by running C<perl -V>
-and looking for the C<useperlio=> line. If C<useperlio> is C<define>, you
-have PerlIO; otherwise you don't.
-
-If you open a pipe on the command C<-> (that is, specify either C<|-> or C<-|>
-with the one- or two-argument forms of C<open>),
-an implicit C<fork> is done, so C<open> returns twice: in the parent
-process it returns the pid
-of the child process, and in the child process it returns (a defined) C<0>.
-Use C<defined($pid)> or C<//> to determine whether the open was successful.
-
-For example, use either
-
- $child_pid = open(FROM_KID, "-|") // die "can't fork: $!";
-
-or
- $child_pid = open(TO_KID, "|-") // die "can't fork: $!";
-
-followed by
-
- if ($child_pid) {
- # am the parent:
- # either write TO_KID or else read FROM_KID
- ...
- wait $child_pid;
- } else {
- # am the child; use STDIN/STDOUT normally
- ...
- exit;
- }
-
-The filehandle behaves normally for the parent, but I/O to that
-filehandle is piped from/to the STDOUT/STDIN of the child process.
-In the child process, the filehandle isn't opened--I/O happens from/to
-the new STDOUT/STDIN. Typically this is used like the normal
-piped open when you want to exercise more control over just how the
-pipe command gets executed, such as when running setuid and
-you don't want to have to scan shell commands for metacharacters.
-
-The following blocks are more or less equivalent:
-
- open(FOO, "|tr '[a-z]' '[A-Z]'");
- open(FOO, "|-", "tr '[a-z]' '[A-Z]'");
- open(FOO, "|-") || exec 'tr', '[a-z]', '[A-Z]';
- open(FOO, "|-", "tr", '[a-z]', '[A-Z]');
-
- open(FOO, "cat -n '$file'|");
- open(FOO, "-|", "cat -n '$file'");
- open(FOO, "-|") || exec "cat", "-n", $file;
- open(FOO, "-|", "cat", "-n", $file);
-
-The last two examples in each block show the pipe as "list form", which is
-not yet supported on all platforms. A good rule of thumb is that if
-your platform has a real C<fork()> (in other words, if your platform is
-Unix, including Linux and MacOS X), you can use the list form. You would
-want to use the list form of the pipe so you can pass literal arguments
-to the command without risk of the shell interpreting any shell metacharacters
-in them. However, this also bars you from opening pipes to commands
-that intentionally contain shell metacharacters, such as:
-
- open(FOO, "|cat -n | expand -4 | lpr")
- // die "Can't open pipeline to lpr: $!";
-
-See L<perlipc/"Safe Pipe Opens"> for more examples of this.
-
-Beginning with v5.6.0, Perl will attempt to flush all files opened for
-output before any operation that may do a fork, but this may not be
-supported on some platforms (see L<perlport>). To be safe, you may need
-to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
-of C<IO::Handle> on any open handles.
-
-On systems that support a close-on-exec flag on files, the flag will
-be set for the newly opened file descriptor as determined by the value
-of C<$^F>. See L<perlvar/$^F>.
-
-Closing any piped filehandle causes the parent process to wait for the
-child to finish, then returns the status value in C<$?> and
-C<${^CHILD_ERROR_NATIVE}>.
-
-The filename passed to the one- and two-argument forms of open() will
-have leading and trailing whitespace deleted and normal
-redirection characters honored. This property, known as "magic open",
-can often be used to good effect. A user could specify a filename of
-F<"rsh cat file |">, or you could change certain filenames as needed:
-
- $filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/;
- open(FH, $filename) or die "Can't open $filename: $!";
-
-Use the three-argument form to open a file with arbitrary weird characters in it,
-
- open(FOO, "<", $file)
- || die "can't open < $file: $!";
-
-otherwise it's necessary to protect any leading and trailing whitespace:
-
- $file =~ s#^(\s)#./$1#;
- open(FOO, "< $file\0")
- || die "open failed: $!";
-
-(this may not work on some bizarre filesystems). One should
-conscientiously choose between the I<magic> and I<three-argument> form
-of open():
-
- open(IN, $ARGV[0]) || die "can't open $ARGV[0]: $!";
-
-will allow the user to specify an argument of the form C<"rsh cat file |">,
-but will not work on a filename that happens to have a trailing space, while
-
- open(IN, "<", $ARGV[0])
- || die "can't open < $ARGV[0]: $!";
-
-will have exactly the opposite restrictions.
-
-If you want a "real" C C<open> (see L<open(2)> on your system), then you
-should use the C<sysopen> function, which involves no such magic (but may
-use subtly different filemodes than Perl open(), which is mapped to C
-fopen()). This is another way to protect your filenames from
-interpretation. For example:
-
- use IO::Handle;
- sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL)
- or die "sysopen $path: $!";
- $oldfh = select(HANDLE); $| = 1; select($oldfh);
- print HANDLE "stuff $$\n";
- seek(HANDLE, 0, 0);
- print "File contains: ", <HANDLE>;
-
-Using the constructor from the C<IO::Handle> package (or one of its
-subclasses, such as C<IO::File> or C<IO::Socket>), you can generate anonymous
-filehandles that have the scope of the variables used to hold them, then
-automatically (but silently) close once their reference counts become
-zero, typically at scope exit:
-
- use IO::File;
- #...
- sub read_myfile_munged {
- my $ALL = shift;
- # or just leave it undef to autoviv
- my $handle = IO::File->new;
- open($handle, "<", "myfile") or die "myfile: $!";
- $first = <$handle>
- or return (); # Automatically closed here.
- mung($first) or die "mung failed"; # Or here.
- return (first, <$handle>) if $ALL; # Or here.
- return $first; # Or here.
- }
-
-B<WARNING:> The previous example has a bug because the automatic
-close that happens when the refcount on C<handle> does not
-properly detect and report failures. I<Always> close the handle
-yourself and inspect the return value.
-
- close($handle)
- || warn "close failed: $!";
-
-See L</seek> for some details about mixing reading and writing.
-
-Portability issues: L<perlport/open>.
-
-=item opendir DIRHANDLE,EXPR
-X<opendir>
-
-=for Pod::Functions open a directory
-
-Opens a directory named EXPR for processing by C<readdir>, C<telldir>,
-C<seekdir>, C<rewinddir>, and C<closedir>. Returns true if successful.
-DIRHANDLE may be an expression whose value can be used as an indirect
-dirhandle, usually the real dirhandle name. If DIRHANDLE is an undefined
-scalar variable (or array or hash element), the variable is assigned a
-reference to a new anonymous dirhandle; that is, it's autovivified.
-DIRHANDLEs have their own namespace separate from FILEHANDLEs.
-
-See the example at C<readdir>.
-
-=item ord EXPR
-X<ord> X<encoding>
-
-=item ord
-
-=for Pod::Functions find a character's numeric representation
-
-Returns the numeric value of the first character of EXPR.
-If EXPR is an empty string, returns 0. If EXPR is omitted, uses C<$_>.
-(Note I<character>, not byte.)
-
-For the reverse, see L</chr>.
-See L<perlunicode> for more about Unicode.
-
-=item our EXPR
-X<our> X<global>
-
-=item our TYPE EXPR
-
-=item our EXPR : ATTRS
-
-=item our TYPE EXPR : ATTRS
-
-=for Pod::Functions +5.6.0 declare and assign a package variable (lexical scoping)
-
-C<our> associates a simple name with a package variable in the current
-package for use within the current scope. When C<use strict 'vars'> is in
-effect, C<our> lets you use declared global variables without qualifying
-them with package names, within the lexical scope of the C<our> declaration.
-In this way C<our> differs from C<use vars>, which is package-scoped.
-
-Unlike C<my> or C<state>, which allocates storage for a variable and
-associates a simple name with that storage for use within the current
-scope, C<our> associates a simple name with a package (read: global)
-variable in the current package, for use within the current lexical scope.
-In other words, C<our> has the same scoping rules as C<my> or C<state>, but
-does not necessarily create a variable.
-
-If more than one value is listed, the list must be placed
-in parentheses.
-
- our $foo;
- our($bar, $baz);
-
-An C<our> declaration declares a global variable that will be visible
-across its entire lexical scope, even across package boundaries. The
-package in which the variable is entered is determined at the point
-of the declaration, not at the point of use. This means the following
-behavior holds:
-
- package Foo;
- our $bar; # declares $Foo::bar for rest of lexical scope
- $bar = 20;
-
- package Bar;
- print $bar; # prints 20, as it refers to $Foo::bar
-
-Multiple C<our> declarations with the same name in the same lexical
-scope are allowed if they are in different packages. If they happen
-to be in the same package, Perl will emit warnings if you have asked
-for them, just like multiple C<my> declarations. Unlike a second
-C<my> declaration, which will bind the name to a fresh variable, a
-second C<our> declaration in the same package, in the same scope, is
-merely redundant.
-
- use warnings;
- package Foo;
- our $bar; # declares $Foo::bar for rest of lexical scope
- $bar = 20;
-
- package Bar;
- our $bar = 30; # declares $Bar::bar for rest of lexical scope
- print $bar; # prints 30
-
- our $bar; # emits warning but has no other effect
- print $bar; # still prints 30
-
-An C<our> declaration may also have a list of attributes associated
-with it.
-
-The exact semantics and interface of TYPE and ATTRS are still
-evolving. TYPE is currently bound to the use of the C<fields> pragma,
-and attributes are handled using the C<attributes> pragma, or, starting
-from Perl 5.8.0, also via the C<Attribute::Handlers> module. See
-L<perlsub/"Private Variables via my()"> for details, and L<fields>,
-L<attributes>, and L<Attribute::Handlers>.
-
-=item pack TEMPLATE,LIST
-X<pack>
-
-=for Pod::Functions convert a list into a binary representation
-
-Takes a LIST of values and converts it into a string using the rules
-given by the TEMPLATE. The resulting string is the concatenation of
-the converted values. Typically, each converted value looks
-like its machine-level representation. For example, on 32-bit machines
-an integer may be represented by a sequence of 4 bytes, which will in
-Perl be presented as a string that's 4 characters long.
-
-See L<perlpacktut> for an introduction to this function.
-
-The TEMPLATE is a sequence of characters that give the order and type
-of values, as follows:
-
- a A string with arbitrary binary data, will be null padded.
- A A text (ASCII) string, will be space padded.
- Z A null-terminated (ASCIZ) string, will be null padded.
-
- b A bit string (ascending bit order inside each byte,
- like vec()).
- B A bit string (descending bit order inside each byte).
- h A hex string (low nybble first).
- H A hex string (high nybble first).
-
- c A signed char (8-bit) value.
- C An unsigned char (octet) value.
- W An unsigned char value (can be greater than 255).
-
- s A signed short (16-bit) value.
- S An unsigned short value.
-
- l A signed long (32-bit) value.
- L An unsigned long value.
-
- q A signed quad (64-bit) value.
- Q An unsigned quad value.
- (Quads are available only if your system supports 64-bit
- integer values _and_ if Perl has been compiled to support
- those. Raises an exception otherwise.)
-
- i A signed integer value.
- I A unsigned integer value.
- (This 'integer' is _at_least_ 32 bits wide. Its exact
- size depends on what a local C compiler calls 'int'.)
-
- n An unsigned short (16-bit) in "network" (big-endian) order.
- N An unsigned long (32-bit) in "network" (big-endian) order.
- v An unsigned short (16-bit) in "VAX" (little-endian) order.
- V An unsigned long (32-bit) in "VAX" (little-endian) order.
-
- j A Perl internal signed integer value (IV).
- J A Perl internal unsigned integer value (UV).
-
- f A single-precision float in native format.
- d A double-precision float in native format.
-
- F A Perl internal floating-point value (NV) in native format
- D A float of long-double precision in native format.
- (Long doubles are available only if your system supports
- long double values _and_ if Perl has been compiled to
- support those. Raises an exception otherwise.)
-
- p A pointer to a null-terminated string.
- P A pointer to a structure (fixed-length string).
-
- u A uuencoded string.
- U A Unicode character number. Encodes to a character in char-
- acter mode and UTF-8 (or UTF-EBCDIC in EBCDIC platforms) in
- byte mode.
-
- w A BER compressed integer (not an ASN.1 BER, see perlpacktut
- for details). Its bytes represent an unsigned integer in
- base 128, most significant digit first, with as few digits
- as possible. Bit eight (the high bit) is set on each byte
- except the last.
-
- x A null byte (a.k.a ASCII NUL, "\000", chr(0))
- X Back up a byte.
- @ Null-fill or truncate to absolute position, counted from the
- start of the innermost ()-group.
- . Null-fill or truncate to absolute position specified by
- the value.
- ( Start of a ()-group.
-
-One or more modifiers below may optionally follow certain letters in the
-TEMPLATE (the second column lists letters for which the modifier is valid):
-
- ! sSlLiI Forces native (short, long, int) sizes instead
- of fixed (16-/32-bit) sizes.
-
- xX Make x and X act as alignment commands.
-
- nNvV Treat integers as signed instead of unsigned.
-
- @. Specify position as byte offset in the internal
- representation of the packed string. Efficient
- but dangerous.
-
- > sSiIlLqQ Force big-endian byte-order on the type.
- jJfFdDpP (The "big end" touches the construct.)
-
- < sSiIlLqQ Force little-endian byte-order on the type.
- jJfFdDpP (The "little end" touches the construct.)
-
-The C<< > >> and C<< < >> modifiers can also be used on C<()> groups
-to force a particular byte-order on all components in that group,
-including all its subgroups.
-
-The following rules apply:
-
-=over
-
-=item *
-
-Each letter may optionally be followed by a number indicating the repeat
-count. A numeric repeat count may optionally be enclosed in brackets, as
-in C<pack("C[80]", @arr)>. The repeat count gobbles that many values from
-the LIST when used with all format types other than C<a>, C<A>, C<Z>, C<b>,
-C<B>, C<h>, C<H>, C<@>, C<.>, C<x>, C<X>, and C<P>, where it means
-something else, described below. Supplying a C<*> for the repeat count
-instead of a number means to use however many items are left, except for:
-
-=over
-
-=item *
-
-C<@>, C<x>, and C<X>, where it is equivalent to C<0>.
-
-=item *
-
-<.>, where it means relative to the start of the string.
-
-=item *
-
-C<u>, where it is equivalent to 1 (or 45, which here is equivalent).
-
-=back
-
-One can replace a numeric repeat count with a template letter enclosed in
-brackets to use the packed byte length of the bracketed template for the
-repeat count.
-
-For example, the template C<x[L]> skips as many bytes as in a packed long,
-and the template C<"$t X[$t] $t"> unpacks twice whatever $t (when
-variable-expanded) unpacks. If the template in brackets contains alignment
-commands (such as C<x![d]>), its packed length is calculated as if the
-start of the template had the maximal possible alignment.
-
-When used with C<Z>, a C<*> as the repeat count is guaranteed to add a
-trailing null byte, so the resulting string is always one byte longer than
-the byte length of the item itself.
-
-When used with C<@>, the repeat count represents an offset from the start
-of the innermost C<()> group.
-
-When used with C<.>, the repeat count determines the starting position to
-calculate the value offset as follows:
-
-=over
-
-=item *
-
-If the repeat count is C<0>, it's relative to the current position.
-
-=item *
-
-If the repeat count is C<*>, the offset is relative to the start of the
-packed string.
-
-=item *
-
-And if it's an integer I<n>, the offset is relative to the start of the
-I<n>th innermost C<( )> group, or to the start of the string if I<n> is
-bigger then the group level.
-
-=back
-
-The repeat count for C<u> is interpreted as the maximal number of bytes
-to encode per line of output, with 0, 1 and 2 replaced by 45. The repeat
-count should not be more than 65.
-
-=item *
-
-The C<a>, C<A>, and C<Z> types gobble just one value, but pack it as a
-string of length count, padding with nulls or spaces as needed. When
-unpacking, C<A> strips trailing whitespace and nulls, C<Z> strips everything
-after the first null, and C<a> returns data with no stripping at all.
-
-If the value to pack is too long, the result is truncated. If it's too
-long and an explicit count is provided, C<Z> packs only C<$count-1> bytes,
-followed by a null byte. Thus C<Z> always packs a trailing null, except
-when the count is 0.
-
-=item *
-
-Likewise, the C<b> and C<B> formats pack a string that's that many bits long.
-Each such format generates 1 bit of the result. These are typically followed
-by a repeat count like C<B8> or C<B64>.
-
-Each result bit is based on the least-significant bit of the corresponding
-input character, i.e., on C<ord($char)%2>. In particular, characters C<"0">
-and C<"1"> generate bits 0 and 1, as do characters C<"\000"> and C<"\001">.
-
-Starting from the beginning of the input string, each 8-tuple
-of characters is converted to 1 character of output. With format C<b>,
-the first character of the 8-tuple determines the least-significant bit of a
-character; with format C<B>, it determines the most-significant bit of
-a character.
-
-If the length of the input string is not evenly divisible by 8, the
-remainder is packed as if the input string were padded by null characters
-at the end. Similarly during unpacking, "extra" bits are ignored.
-
-If the input string is longer than needed, remaining characters are ignored.
-
-A C<*> for the repeat count uses all characters of the input field.
-On unpacking, bits are converted to a string of C<0>s and C<1>s.
-
-=item *
-
-The C<h> and C<H> formats pack a string that many nybbles (4-bit groups,
-representable as hexadecimal digits, C<"0".."9"> C<"a".."f">) long.
-
-For each such format, pack() generates 4 bits of result.
-With non-alphabetical characters, the result is based on the 4 least-significant
-bits of the input character, i.e., on C<ord($char)%16>. In particular,
-characters C<"0"> and C<"1"> generate nybbles 0 and 1, as do bytes
-C<"\000"> and C<"\001">. For characters C<"a".."f"> and C<"A".."F">, the result
-is compatible with the usual hexadecimal digits, so that C<"a"> and
-C<"A"> both generate the nybble C<0xA==10>. Use only these specific hex
-characters with this format.
-
-Starting from the beginning of the template to pack(), each pair
-of characters is converted to 1 character of output. With format C<h>, the
-first character of the pair determines the least-significant nybble of the
-output character; with format C<H>, it determines the most-significant
-nybble.
-
-If the length of the input string is not even, it behaves as if padded by
-a null character at the end. Similarly, "extra" nybbles are ignored during
-unpacking.
-
-If the input string is longer than needed, extra characters are ignored.
-
-A C<*> for the repeat count uses all characters of the input field. For
-unpack(), nybbles are converted to a string of hexadecimal digits.
-
-=item *
-
-The C<p> format packs a pointer to a null-terminated string. You are
-responsible for ensuring that the string is not a temporary value, as that
-could potentially get deallocated before you got around to using the packed
-result. The C<P> format packs a pointer to a structure of the size indicated
-by the length. A null pointer is created if the corresponding value for
-C<p> or C<P> is C<undef>; similarly with unpack(), where a null pointer
-unpacks into C<undef>.
-
-If your system has a strange pointer size--meaning a pointer is neither as
-big as an int nor as big as a long--it may not be possible to pack or
-unpack pointers in big- or little-endian byte order. Attempting to do
-so raises an exception.
-
-=item *
-
-The C</> template character allows packing and unpacking of a sequence of
-items where the packed structure contains a packed item count followed by
-the packed items themselves. This is useful when the structure you're
-unpacking has encoded the sizes or repeat counts for some of its fields
-within the structure itself as separate fields.
-
-For C<pack>, you write I<length-item>C</>I<sequence-item>, and the
-I<length-item> describes how the length value is packed. Formats likely
-to be of most use are integer-packing ones like C<n> for Java strings,
-C<w> for ASN.1 or SNMP, and C<N> for Sun XDR.
-
-For C<pack>, I<sequence-item> may have a repeat count, in which case
-the minimum of that and the number of available items is used as the argument
-for I<length-item>. If it has no repeat count or uses a '*', the number
-of available items is used.
-
-For C<unpack>, an internal stack of integer arguments unpacked so far is
-used. You write C</>I<sequence-item> and the repeat count is obtained by
-popping off the last element from the stack. The I<sequence-item> must not
-have a repeat count.
-
-If I<sequence-item> refers to a string type (C<"A">, C<"a">, or C<"Z">),
-the I<length-item> is the string length, not the number of strings. With
-an explicit repeat count for pack, the packed string is adjusted to that
-length. For example:
-
- This code: gives this result:
-
- unpack("W/a", "\004Gurusamy") ("Guru")
- unpack("a3/A A*", "007 Bond J ") (" Bond", "J")
- unpack("a3 x2 /A A*", "007: Bond, J.") ("Bond, J", ".")
-
- pack("n/a* w/a","hello,","world") "\000\006hello,\005world"
- pack("a/W2", ord("a") .. ord("z")) "2ab"
-
-The I<length-item> is not returned explicitly from C<unpack>.
-
-Supplying a count to the I<length-item> format letter is only useful with
-C<A>, C<a>, or C<Z>. Packing with a I<length-item> of C<a> or C<Z> may
-introduce C<"\000"> characters, which Perl does not regard as legal in
-numeric strings.
-
-=item *
-
-The integer types C<s>, C<S>, C<l>, and C<L> may be
-followed by a C<!> modifier to specify native shorts or
-longs. As shown in the example above, a bare C<l> means
-exactly 32 bits, although the native C<long> as seen by the local C compiler
-may be larger. This is mainly an issue on 64-bit platforms. You can
-see whether using C<!> makes any difference this way:
-
- printf "format s is %d, s! is %d\n",
- length pack("s"), length pack("s!");
-
- printf "format l is %d, l! is %d\n",
- length pack("l"), length pack("l!");
-
-
-C<i!> and C<I!> are also allowed, but only for completeness' sake:
-they are identical to C<i> and C<I>.
-
-The actual sizes (in bytes) of native shorts, ints, longs, and long
-longs on the platform where Perl was built are also available from
-the command line:
-
- $ perl -V:{short,int,long{,long}}size
- shortsize='2';
- intsize='4';
- longsize='4';
- longlongsize='8';
-
-or programmatically via the C<Config> module:
-
- use Config;
- print $Config{shortsize}, "\n";
- print $Config{intsize}, "\n";
- print $Config{longsize}, "\n";
- print $Config{longlongsize}, "\n";
-
-C<$Config{longlongsize}> is undefined on systems without
-long long support.
-
-=item *
-
-The integer formats C<s>, C<S>, C<i>, C<I>, C<l>, C<L>, C<j>, and C<J> are
-inherently non-portable between processors and operating systems because
-they obey native byteorder and endianness. For example, a 4-byte integer
-0x12345678 (305419896 decimal) would be ordered natively (arranged in and
-handled by the CPU registers) into bytes as
-
- 0x12 0x34 0x56 0x78 # big-endian
- 0x78 0x56 0x34 0x12 # little-endian
-
-Basically, Intel and VAX CPUs are little-endian, while everybody else,
-including Motorola m68k/88k, PPC, Sparc, HP PA, Power, and Cray, are
-big-endian. Alpha and MIPS can be either: Digital/Compaq uses (well, used)
-them in little-endian mode, but SGI/Cray uses them in big-endian mode.
-
-The names I<big-endian> and I<little-endian> are comic references to the
-egg-eating habits of the little-endian Lilliputians and the big-endian
-Blefuscudians from the classic Jonathan Swift satire, I<Gulliver's Travels>.
-This entered computer lingo via the paper "On Holy Wars and a Plea for
-Peace" by Danny Cohen, USC/ISI IEN 137, April 1, 1980.
-
-Some systems may have even weirder byte orders such as
-
- 0x56 0x78 0x12 0x34
- 0x34 0x12 0x78 0x56
-
-You can determine your system endianness with this incantation:
-
- printf("%#02x ", $_) for unpack("W*", pack L=>0x12345678);
-
-The byteorder on the platform where Perl was built is also available
-via L<Config>:
-
- use Config;
- print "$Config{byteorder}\n";
-
-or from the command line:
-
- $ perl -V:byteorder
-
-Byteorders C<"1234"> and C<"12345678"> are little-endian; C<"4321">
-and C<"87654321"> are big-endian.
-
-For portably packed integers, either use the formats C<n>, C<N>, C<v>,
-and C<V> or else use the C<< > >> and C<< < >> modifiers described
-immediately below. See also L<perlport>.
-
-=item *
-
-Starting with Perl 5.9.2, integer and floating-point formats, along with
-the C<p> and C<P> formats and C<()> groups, may all be followed by the
-C<< > >> or C<< < >> endianness modifiers to respectively enforce big-
-or little-endian byte-order. These modifiers are especially useful
-given how C<n>, C<N>, C<v>, and C<V> don't cover signed integers,
-64-bit integers, or floating-point values.
-
-Here are some concerns to keep in mind when using an endianness modifier:
-
-=over
-
-=item *
-
-Exchanging signed integers between different platforms works only
-when all platforms store them in the same format. Most platforms store
-signed integers in two's-complement notation, so usually this is not an issue.
-
-=item *
-
-The C<< > >> or C<< < >> modifiers can only be used on floating-point
-formats on big- or little-endian machines. Otherwise, attempting to
-use them raises an exception.
-
-=item *
-
-Forcing big- or little-endian byte-order on floating-point values for
-data exchange can work only if all platforms use the same
-binary representation such as IEEE floating-point. Even if all
-platforms are using IEEE, there may still be subtle differences. Being able
-to use C<< > >> or C<< < >> on floating-point values can be useful,
-but also dangerous if you don't know exactly what you're doing.
-It is not a general way to portably store floating-point values.
-
-=item *
-
-When using C<< > >> or C<< < >> on a C<()> group, this affects
-all types inside the group that accept byte-order modifiers,
-including all subgroups. It is silently ignored for all other
-types. You are not allowed to override the byte-order within a group
-that already has a byte-order modifier suffix.
-
-=back
-
-=item *
-
-Real numbers (floats and doubles) are in native machine format only.
-Due to the multiplicity of floating-point formats and the lack of a
-standard "network" representation for them, no facility for interchange has been
-made. This means that packed floating-point data written on one machine
-may not be readable on another, even if both use IEEE floating-point
-arithmetic (because the endianness of the memory representation is not part
-of the IEEE spec). See also L<perlport>.
-
-If you know I<exactly> what you're doing, you can use the C<< > >> or C<< < >>
-modifiers to force big- or little-endian byte-order on floating-point values.
-
-Because Perl uses doubles (or long doubles, if configured) internally for
-all numeric calculation, converting from double into float and thence
-to double again loses precision, so C<unpack("f", pack("f", $foo)>)
-will not in general equal $foo.
-
-=item *
-
-Pack and unpack can operate in two modes: character mode (C<C0> mode) where
-the packed string is processed per character, and UTF-8 mode (C<U0> mode)
-where the packed string is processed in its UTF-8-encoded Unicode form on
-a byte-by-byte basis. Character mode is the default
-unless the format string starts with C<U>. You
-can always switch mode mid-format with an explicit
-C<C0> or C<U0> in the format. This mode remains in effect until the next
-mode change, or until the end of the C<()> group it (directly) applies to.
-
-Using C<C0> to get Unicode characters while using C<U0> to get I<non>-Unicode
-bytes is not necessarily obvious. Probably only the first of these
-is what you want:
-
- $ perl -CS -E 'say "\x{3B1}\x{3C9}"' |
- perl -CS -ne 'printf "%v04X\n", $_ for unpack("C0A*", $_)'
- 03B1.03C9
- $ perl -CS -E 'say "\x{3B1}\x{3C9}"' |
- perl -CS -ne 'printf "%v02X\n", $_ for unpack("U0A*", $_)'
- CE.B1.CF.89
- $ perl -CS -E 'say "\x{3B1}\x{3C9}"' |
- perl -C0 -ne 'printf "%v02X\n", $_ for unpack("C0A*", $_)'
- CE.B1.CF.89
- $ perl -CS -E 'say "\x{3B1}\x{3C9}"' |
- perl -C0 -ne 'printf "%v02X\n", $_ for unpack("U0A*", $_)'
- C3.8E.C2.B1.C3.8F.C2.89
-
-Those examples also illustrate that you should not try to use
-C<pack>/C<unpack> as a substitute for the L<Encode> module.
-
-=item *
-
-You must yourself do any alignment or padding by inserting, for example,
-enough C<"x">es while packing. There is no way for pack() and unpack()
-to know where characters are going to or coming from, so they
-handle their output and input as flat sequences of characters.
-
-=item *
-
-A C<()> group is a sub-TEMPLATE enclosed in parentheses. A group may
-take a repeat count either as postfix, or for unpack(), also via the C</>
-template character. Within each repetition of a group, positioning with
-C<@> starts over at 0. Therefore, the result of
-
- pack("@1A((@2A)@3A)", qw[X Y Z])
-
-is the string C<"\0X\0\0YZ">.
-
-=item *
-
-C<x> and C<X> accept the C<!> modifier to act as alignment commands: they
-jump forward or back to the closest position aligned at a multiple of C<count>
-characters. For example, to pack() or unpack() a C structure like
-
- struct {
- char c; /* one signed, 8-bit character */
- double d;
- char cc[2];
- }
-
-one may need to use the template C<c x![d] d c[2]>. This assumes that
-doubles must be aligned to the size of double.
-
-For alignment commands, a C<count> of 0 is equivalent to a C<count> of 1;
-both are no-ops.
-
-=item *
-
-C<n>, C<N>, C<v> and C<V> accept the C<!> modifier to
-represent signed 16-/32-bit integers in big-/little-endian order.
-This is portable only when all platforms sharing packed data use the
-same binary representation for signed integers; for example, when all
-platforms use two's-complement representation.
-
-=item *
-
-Comments can be embedded in a TEMPLATE using C<#> through the end of line.
-White space can separate pack codes from each other, but modifiers and
-repeat counts must follow immediately. Breaking complex templates into
-individual line-by-line components, suitably annotated, can do as much to
-improve legibility and maintainability of pack/unpack formats as C</x> can
-for complicated pattern matches.
-
-=item *
-
-If TEMPLATE requires more arguments than pack() is given, pack()
-assumes additional C<""> arguments. If TEMPLATE requires fewer arguments
-than given, extra arguments are ignored.
-
-=back
-
-Examples:
-
- $foo = pack("WWWW",65,66,67,68);
- # foo eq "ABCD"
- $foo = pack("W4",65,66,67,68);
- # same thing
- $foo = pack("W4",0x24b6,0x24b7,0x24b8,0x24b9);
- # same thing with Unicode circled letters.
- $foo = pack("U4",0x24b6,0x24b7,0x24b8,0x24b9);
- # same thing with Unicode circled letters. You don't get the
- # UTF-8 bytes because the U at the start of the format caused
- # a switch to U0-mode, so the UTF-8 bytes get joined into
- # characters
- $foo = pack("C0U4",0x24b6,0x24b7,0x24b8,0x24b9);
- # foo eq "\xe2\x92\xb6\xe2\x92\xb7\xe2\x92\xb8\xe2\x92\xb9"
- # This is the UTF-8 encoding of the string in the
- # previous example
-
- $foo = pack("ccxxcc",65,66,67,68);
- # foo eq "AB\0\0CD"
-
- # NOTE: The examples above featuring "W" and "c" are true
- # only on ASCII and ASCII-derived systems such as ISO Latin 1
- # and UTF-8. On EBCDIC systems, the first example would be
- # $foo = pack("WWWW",193,194,195,196);
-
- $foo = pack("s2",1,2);
- # "\001\000\002\000" on little-endian
- # "\000\001\000\002" on big-endian
-
- $foo = pack("a4","abcd","x","y","z");
- # "abcd"
-
- $foo = pack("aaaa","abcd","x","y","z");
- # "axyz"
-
- $foo = pack("a14","abcdefg");
- # "abcdefg\0\0\0\0\0\0\0"
-
- $foo = pack("i9pl", gmtime);
- # a real struct tm (on my system anyway)
-
- $utmp_template = "Z8 Z8 Z16 L";
- $utmp = pack($utmp_template, @utmp1);
- # a struct utmp (BSDish)
-
- @utmp2 = unpack($utmp_template, $utmp);
- # "@utmp1" eq "@utmp2"
-
- sub bintodec {
- unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
- }
-
- $foo = pack('sx2l', 12, 34);
- # short 12, two zero bytes padding, long 34
- $bar = pack('s@4l', 12, 34);
- # short 12, zero fill to position 4, long 34
- # $foo eq $bar
- $baz = pack('s.l', 12, 4, 34);
- # short 12, zero fill to position 4, long 34
-
- $foo = pack('nN', 42, 4711);
- # pack big-endian 16- and 32-bit unsigned integers
- $foo = pack('S>L>', 42, 4711);
- # exactly the same
- $foo = pack('s<l<', -42, 4711);
- # pack little-endian 16- and 32-bit signed integers
- $foo = pack('(sl)<', -42, 4711);
- # exactly the same
-
-The same template may generally also be used in unpack().
-
-=item package NAMESPACE
-
-=item package NAMESPACE VERSION
-X<package> X<module> X<namespace> X<version>
-
-=item package NAMESPACE BLOCK
-
-=item package NAMESPACE VERSION BLOCK
-X<package> X<module> X<namespace> X<version>
-
-=for Pod::Functions declare a separate global namespace
-
-Declares the BLOCK or the rest of the compilation unit as being in the
-given namespace. The scope of the package declaration is either the
-supplied code BLOCK or, in the absence of a BLOCK, from the declaration
-itself through the end of current scope (the enclosing block, file, or
-C<eval>). That is, the forms without a BLOCK are operative through the end
-of the current scope, just like the C<my>, C<state>, and C<our> operators.
-All unqualified dynamic identifiers in this scope will be in the given
-namespace, except where overridden by another C<package> declaration or
-when they're one of the special identifiers that qualify into C<main::>,
-like C<STDOUT>, C<ARGV>, C<ENV>, and the punctuation variables.
-
-A package statement affects dynamic variables only, including those
-you've used C<local> on, but I<not> lexical variables, which are created
-with C<my>, C<state>, or C<our>. Typically it would be the first
-declaration in a file included by C<require> or C<use>. You can switch into a
-package in more than one place, since this only determines which default
-symbol table the compiler uses for the rest of that block. You can refer to
-identifiers in other packages than the current one by prefixing the identifier
-with the package name and a double colon, as in C<$SomePack::var>
-or C<ThatPack::INPUT_HANDLE>. If package name is omitted, the C<main>
-package as assumed. That is, C<$::sail> is equivalent to
-C<$main::sail> (as well as to C<$main'sail>, still seen in ancient
-code, mostly from Perl 4).
-
-If VERSION is provided, C<package> sets the C<$VERSION> variable in the given
-namespace to a L<version> object with the VERSION provided. VERSION must be a
-"strict" style version number as defined by the L<version> module: a positive
-decimal number (integer or decimal-fraction) without exponentiation or else a
-dotted-decimal v-string with a leading 'v' character and at least three
-components. You should set C<$VERSION> only once per package.
-
-See L<perlmod/"Packages"> for more information about packages, modules,
-and classes. See L<perlsub> for other scoping issues.
-
-=item __PACKAGE__
-X<__PACKAGE__>
-
-=for Pod::Functions +5.004 the current package
-
-A special token that returns the name of the package in which it occurs.
-
-=item pipe READHANDLE,WRITEHANDLE
-X<pipe>
-
-=for Pod::Functions open a pair of connected filehandles
-
-Opens a pair of connected pipes like the corresponding system call.
-Note that if you set up a loop of piped processes, deadlock can occur
-unless you are very careful. In addition, note that Perl's pipes use
-IO buffering, so you may need to set C<$|> to flush your WRITEHANDLE
-after each command, depending on the application.
-
-See L<IPC::Open2>, L<IPC::Open3>, and
-L<perlipc/"Bidirectional Communication with Another Process">
-for examples of such things.
-
-On systems that support a close-on-exec flag on files, that flag is set
-on all newly opened file descriptors whose C<fileno>s are I<higher> than
-the current value of $^F (by default 2 for C<STDERR>). See L<perlvar/$^F>.
-
-=item pop ARRAY
-X<pop> X<stack>
-
-=item pop EXPR
-
-=item pop
-
-=for Pod::Functions remove the last element from an array and return it
-
-Pops and returns the last value of the array, shortening the array by
-one element.
-
-Returns the undefined value if the array is empty, although this may also
-happen at other times. If ARRAY is omitted, pops the C<@ARGV> array in the
-main program, but the C<@_> array in subroutines, just like C<shift>.
-
-Starting with Perl 5.14, C<pop> can take a scalar EXPR, which must hold a
-reference to an unblessed array. The argument will be dereferenced
-automatically. This aspect of C<pop> is considered highly experimental.
-The exact behaviour may change in a future version of Perl.
-
-To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work I<only> on Perls of
-a recent vintage:
-
- use 5.014; # so push/pop/etc work on scalars (experimental)
-
-=item pos SCALAR
-X<pos> X<match, position>
-
-=item pos
-
-=for Pod::Functions find or set the offset for the last/next m//g search
-
-Returns the offset of where the last C<m//g> search left off for the
-variable in question (C<$_> is used when the variable is not
-specified). Note that 0 is a valid match offset. C<undef> indicates
-that the search position is reset (usually due to match failure, but
-can also be because no match has yet been run on the scalar).
-
-C<pos> directly accesses the location used by the regexp engine to
-store the offset, so assigning to C<pos> will change that offset, and
-so will also influence the C<\G> zero-width assertion in regular
-expressions. Both of these effects take place for the next match, so
-you can't affect the position with C<pos> during the current match,
-such as in C<(?{pos() = 5})> or C<s//pos() = 5/e>.
-
-Setting C<pos> also resets the I<matched with zero-length> flag, described
-under L<perlre/"Repeated Patterns Matching a Zero-length Substring">.
-
-Because a failed C<m//gc> match doesn't reset the offset, the return
-from C<pos> won't change either in this case. See L<perlre> and
-L<perlop>.
-
-=item print FILEHANDLE LIST
-X<print>
-
-=item print FILEHANDLE
-
-=item print LIST
-
-=item print
-
-=for Pod::Functions output a list to a filehandle
-
-Prints a string or a list of strings. Returns true if successful.
-FILEHANDLE may be a scalar variable containing the name of or a reference
-to the filehandle, thus introducing one level of indirection. (NOTE: If
-FILEHANDLE is a variable and the next token is a term, it may be
-misinterpreted as an operator unless you interpose a C<+> or put
-parentheses around the arguments.) If FILEHANDLE is omitted, prints to the
-last selected (see L</select>) output handle. If LIST is omitted, prints
-C<$_> to the currently selected output handle. To use FILEHANDLE alone to
-print the content of C<$_> to it, you must use a real filehandle like
-C<FH>, not an indirect one like C<$fh>. To set the default output handle
-to something other than STDOUT, use the select operation.
-
-The current value of C<$,> (if any) is printed between each LIST item. The
-current value of C<$\> (if any) is printed after the entire LIST has been
-printed. Because print takes a LIST, anything in the LIST is evaluated in
-list context, including any subroutines whose return lists you pass to
-C<print>. Be careful not to follow the print keyword with a left
-parenthesis unless you want the corresponding right parenthesis to
-terminate the arguments to the print; put parentheses around all arguments
-(or interpose a C<+>, but that doesn't look as good).
-
-If you're storing handles in an array or hash, or in general whenever
-you're using any expression more complex than a bareword handle or a plain,
-unsubscripted scalar variable to retrieve it, you will have to use a block
-returning the filehandle value instead, in which case the LIST may not be
-omitted:
-
- print { $files[$i] } "stuff\n";
- print { $OK ? STDOUT : STDERR } "stuff\n";
-
-Printing to a closed pipe or socket will generate a SIGPIPE signal. See
-L<perlipc> for more on signal handling.
-
-=item printf FILEHANDLE FORMAT, LIST
-X<printf>
-
-=item printf FILEHANDLE
-
-=item printf FORMAT, LIST
-
-=item printf
-
-=for Pod::Functions output a formatted list to a filehandle
-
-Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>, except that C<$\>
-(the output record separator) is not appended. The first argument of the
-list will be interpreted as the C<printf> format. See
-L<sprintf|/sprintf FORMAT, LIST> for an
-explanation of the format argument. If you omit the LIST, C<$_> is used;
-to use FILEHANDLE without a LIST, you must use a real filehandle like
-C<FH>, not an indirect one like C<$fh>. If C<use locale> (including
-C<use locale ':not_characters'>) is in effect and
-POSIX::setlocale() has been called, the character used for the decimal
-separator in formatted floating-point numbers is affected by the LC_NUMERIC
-locale setting. See L<perllocale> and L<POSIX>.
-
-Don't fall into the trap of using a C<printf> when a simple
-C<print> would do. The C<print> is more efficient and less
-error prone.
-
-=item prototype FUNCTION
-X<prototype>
-
-=for Pod::Functions +5.002 get the prototype (if any) of a subroutine
-
-Returns the prototype of a function as a string (or C<undef> if the
-function has no prototype). FUNCTION is a reference to, or the name of,
-the function whose prototype you want to retrieve.
-
-If FUNCTION is a string starting with C<CORE::>, the rest is taken as a
-name for a Perl builtin. If the builtin is not I<overridable> (such as
-C<qw//>) or if its arguments cannot be adequately expressed by a prototype
-(such as C<system>), prototype() returns C<undef>, because the builtin
-does not really behave like a Perl function. Otherwise, the string
-describing the equivalent prototype is returned.
-
-=item push ARRAY,LIST
-X<push> X<stack>
-
-=item push EXPR,LIST
-
-=for Pod::Functions append one or more elements to an array
-
-Treats ARRAY as a stack by appending the values of LIST to the end of
-ARRAY. The length of ARRAY increases by the length of LIST. Has the same
-effect as
-
- for $value (LIST) {
- $ARRAY[++$#ARRAY] = $value;
- }
-
-but is more efficient. Returns the number of elements in the array following
-the completed C<push>.
-
-Starting with Perl 5.14, C<push> can take a scalar EXPR, which must hold a
-reference to an unblessed array. The argument will be dereferenced
-automatically. This aspect of C<push> is considered highly experimental.
-The exact behaviour may change in a future version of Perl.
-
-To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work I<only> on Perls of
-a recent vintage:
-
- use 5.014; # so push/pop/etc work on scalars (experimental)
-
-=item q/STRING/
-
-=for Pod::Functions singly quote a string
-
-=item qq/STRING/
-
-=for Pod::Functions doubly quote a string
-
-=item qw/STRING/
-
-=for Pod::Functions quote a list of words
-
-=item qx/STRING/
-
-=for Pod::Functions backquote quote a string
-
-Generalized quotes. See L<perlop/"Quote-Like Operators">.
-
-=item qr/STRING/
-
-=for Pod::Functions +5.005 compile pattern
-
-Regexp-like quote. See L<perlop/"Regexp Quote-Like Operators">.
-
-=item quotemeta EXPR
-X<quotemeta> X<metacharacter>
-
-=item quotemeta
-
-=for Pod::Functions quote regular expression magic characters
-
-Returns the value of EXPR with all the ASCII non-"word"
-characters backslashed. (That is, all ASCII characters not matching
-C</[A-Za-z_0-9]/> will be preceded by a backslash in the
-returned string, regardless of any locale settings.)
-This is the internal function implementing
-the C<\Q> escape in double-quoted strings.
-(See below for the behavior on non-ASCII code points.)
-
-If EXPR is omitted, uses C<$_>.
-
-quotemeta (and C<\Q> ... C<\E>) are useful when interpolating strings into
-regular expressions, because by default an interpolated variable will be
-considered a mini-regular expression. For example:
-
- my $sentence = 'The quick brown fox jumped over the lazy dog';
- my $substring = 'quick.*?fox';
- $sentence =~ s{$substring}{big bad wolf};
-
-Will cause C<$sentence> to become C<'The big bad wolf jumped over...'>.
-
-On the other hand:
-
- my $sentence = 'The quick brown fox jumped over the lazy dog';
- my $substring = 'quick.*?fox';
- $sentence =~ s{\Q$substring\E}{big bad wolf};
-
-Or:
-
- my $sentence = 'The quick brown fox jumped over the lazy dog';
- my $substring = 'quick.*?fox';
- my $quoted_substring = quotemeta($substring);
- $sentence =~ s{$quoted_substring}{big bad wolf};
-
-Will both leave the sentence as is.
-Normally, when accepting literal string
-input from the user, quotemeta() or C<\Q> must be used.
-
-In Perl v5.14, all non-ASCII characters are quoted in non-UTF-8-encoded
-strings, but not quoted in UTF-8 strings.
-
-Starting in Perl v5.16, Perl adopted a Unicode-defined strategy for
-quoting non-ASCII characters; the quoting of ASCII characters is
-unchanged.
-
-Also unchanged is the quoting of non-UTF-8 strings when outside the
-scope of a C<use feature 'unicode_strings'>, which is to quote all
-characters in the upper Latin1 range. This provides complete backwards
-compatibility for old programs which do not use Unicode. (Note that
-C<unicode_strings> is automatically enabled within the scope of a
-S<C<use v5.12>> or greater.)
-
-Within the scope of C<use locale>, all non-ASCII Latin1 code points
-are quoted whether the string is encoded as UTF-8 or not. As mentioned
-above, locale does not affect the quoting of ASCII-range characters.
-This protects against those locales where characters such as C<"|"> are
-considered to be word characters.
-
-Otherwise, Perl quotes non-ASCII characters using an adaptation from
-Unicode (see L<http://www.unicode.org/reports/tr31/>.)
-The only code points that are quoted are those that have any of the
-Unicode properties: Pattern_Syntax, Pattern_White_Space, White_Space,
-Default_Ignorable_Code_Point, or General_Category=Control.
-
-Of these properties, the two important ones are Pattern_Syntax and
-Pattern_White_Space. They have been set up by Unicode for exactly this
-purpose of deciding which characters in a regular expression pattern
-should be quoted. No character that can be in an identifier has these
-properties.
-
-Perl promises, that if we ever add regular expression pattern
-metacharacters to the dozen already defined
-(C<\ E<verbar> ( ) [ { ^ $ * + ? .>), that we will only use ones that have the
-Pattern_Syntax property. Perl also promises, that if we ever add
-characters that are considered to be white space in regular expressions
-(currently mostly affected by C</x>), they will all have the
-Pattern_White_Space property.
-
-Unicode promises that the set of code points that have these two
-properties will never change, so something that is not quoted in v5.16
-will never need to be quoted in any future Perl release. (Not all the
-code points that match Pattern_Syntax have actually had characters
-assigned to them; so there is room to grow, but they are quoted
-whether assigned or not. Perl, of course, would never use an
-unassigned code point as an actual metacharacter.)
-
-Quoting characters that have the other 3 properties is done to enhance
-the readability of the regular expression and not because they actually
-need to be quoted for regular expression purposes (characters with the
-White_Space property are likely to be indistinguishable on the page or
-screen from those with the Pattern_White_Space property; and the other
-two properties contain non-printing characters).
-
-=item rand EXPR
-X<rand> X<random>
-
-=item rand
-
-=for Pod::Functions retrieve the next pseudorandom number
-
-Returns a random fractional number greater than or equal to C<0> and less
-than the value of EXPR. (EXPR should be positive.) If EXPR is
-omitted, the value C<1> is used. Currently EXPR with the value C<0> is
-also special-cased as C<1> (this was undocumented before Perl 5.8.0
-and is subject to change in future versions of Perl). Automatically calls
-C<srand> unless C<srand> has already been called. See also C<srand>.
-
-Apply C<int()> to the value returned by C<rand()> if you want random
-integers instead of random fractional numbers. For example,
-
- int(rand(10))
-
-returns a random integer between C<0> and C<9>, inclusive.
-
-(Note: If your rand function consistently returns numbers that are too
-large or too small, then your version of Perl was probably compiled
-with the wrong number of RANDBITS.)
-
-B<C<rand()> is not cryptographically secure. You should not rely
-on it in security-sensitive situations.> As of this writing, a
-number of third-party CPAN modules offer random number generators
-intended by their authors to be cryptographically secure,
-including: L<Data::Entropy>, L<Crypt::Random>, L<Math::Random::Secure>,
-and L<Math::TrulyRandom>.
-
-=item read FILEHANDLE,SCALAR,LENGTH,OFFSET
-X<read> X<file, read>
-
-=item read FILEHANDLE,SCALAR,LENGTH
-
-=for Pod::Functions fixed-length buffered input from a filehandle
-
-Attempts to read LENGTH I<characters> of data into variable SCALAR
-from the specified FILEHANDLE. Returns the number of characters
-actually read, C<0> at end of file, or undef if there was an error (in
-the latter case C<$!> is also set). SCALAR will be grown or shrunk
-so that the last character actually read is the last character of the
-scalar after the read.
-
-An OFFSET may be specified to place the read data at some place in the
-string other than the beginning. A negative OFFSET specifies
-placement at that many characters counting backwards from the end of
-the string. A positive OFFSET greater than the length of SCALAR
-results in the string being padded to the required size with C<"\0">
-bytes before the result of the read is appended.
-
-The call is implemented in terms of either Perl's or your system's native
-fread(3) library function. To get a true read(2) system call, see
-L<sysread|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET>.
-
-Note the I<characters>: depending on the status of the filehandle,
-either (8-bit) bytes or characters are read. By default, all
-filehandles operate on bytes, but for example if the filehandle has
-been opened with the C<:utf8> I/O layer (see L</open>, and the C<open>
-pragma, L<open>), the I/O will operate on UTF8-encoded Unicode
-characters, not bytes. Similarly for the C<:encoding> pragma:
-in that case pretty much any characters can be read.
-
-=item readdir DIRHANDLE
-X<readdir>
-
-=for Pod::Functions get a directory from a directory handle
-
-Returns the next directory entry for a directory opened by C<opendir>.
-If used in list context, returns all the rest of the entries in the
-directory. If there are no more entries, returns the undefined value in
-scalar context and the empty list in list context.
-
-If you're planning to filetest the return values out of a C<readdir>, you'd
-better prepend the directory in question. Otherwise, because we didn't
-C<chdir> there, it would have been testing the wrong file.
-
- opendir(my $dh, $some_dir) || die "can't opendir $some_dir: $!";
- @dots = grep { /^\./ && -f "$some_dir/$_" } readdir($dh);
- closedir $dh;
-
-As of Perl 5.11.2 you can use a bare C<readdir> in a C<while> loop,
-which will set C<$_> on every iteration.
-
- opendir(my $dh, $some_dir) || die;
- while(readdir $dh) {
- print "$some_dir/$_\n";
- }
- closedir $dh;
-
-To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious failures, put this sort of thing at the
-top of your file to signal that your code will work I<only> on Perls of a
-recent vintage:
-
- use 5.012; # so readdir assigns to $_ in a lone while test
-
-=item readline EXPR
-
-=item readline
-X<readline> X<gets> X<fgets>
-
-=for Pod::Functions fetch a record from a file
-
-Reads from the filehandle whose typeglob is contained in EXPR (or from
-C<*ARGV> if EXPR is not provided). In scalar context, each call reads and
-returns the next line until end-of-file is reached, whereupon the
-subsequent call returns C<undef>. In list context, reads until end-of-file
-is reached and returns a list of lines. Note that the notion of "line"
-used here is whatever you may have defined with C<$/> or
-C<$INPUT_RECORD_SEPARATOR>). See L<perlvar/"$/">.
-
-When C<$/> is set to C<undef>, when C<readline> is in scalar
-context (i.e., file slurp mode), and when an empty file is read, it
-returns C<''> the first time, followed by C<undef> subsequently.
-
-This is the internal function implementing the C<< <EXPR> >>
-operator, but you can use it directly. The C<< <EXPR> >>
-operator is discussed in more detail in L<perlop/"I/O Operators">.
-
- $line = <STDIN>;
- $line = readline(*STDIN); # same thing
-
-If C<readline> encounters an operating system error, C<$!> will be set
-with the corresponding error message. It can be helpful to check
-C<$!> when you are reading from filehandles you don't trust, such as a
-tty or a socket. The following example uses the operator form of
-C<readline> and dies if the result is not defined.
-
- while ( ! eof($fh) ) {
- defined( $_ = <$fh> ) or die "readline failed: $!";
- ...
- }
-
-Note that you have can't handle C<readline> errors that way with the
-C<ARGV> filehandle. In that case, you have to open each element of
-C<@ARGV> yourself since C<eof> handles C<ARGV> differently.
-
- foreach my $arg (@ARGV) {
- open(my $fh, $arg) or warn "Can't open $arg: $!";
-
- while ( ! eof($fh) ) {
- defined( $_ = <$fh> )
- or die "readline failed for $arg: $!";
- ...
- }
- }
-
-=item readlink EXPR
-X<readlink>
-
-=item readlink
-
-=for Pod::Functions determine where a symbolic link is pointing
-
-Returns the value of a symbolic link, if symbolic links are
-implemented. If not, raises an exception. If there is a system
-error, returns the undefined value and sets C<$!> (errno). If EXPR is
-omitted, uses C<$_>.
-
-Portability issues: L<perlport/readlink>.
-
-=item readpipe EXPR
-
-=item readpipe
-X<readpipe>
-
-=for Pod::Functions execute a system command and collect standard output
-
-EXPR is executed as a system command.
-The collected standard output of the command is returned.
-In scalar context, it comes back as a single (potentially
-multi-line) string. In list context, returns a list of lines
-(however you've defined lines with C<$/> or C<$INPUT_RECORD_SEPARATOR>).
-This is the internal function implementing the C<qx/EXPR/>
-operator, but you can use it directly. The C<qx/EXPR/>
-operator is discussed in more detail in L<perlop/"I/O Operators">.
-If EXPR is omitted, uses C<$_>.
-
-=item recv SOCKET,SCALAR,LENGTH,FLAGS
-X<recv>
-
-=for Pod::Functions receive a message over a Socket
-
-Receives a message on a socket. Attempts to receive LENGTH characters
-of data into variable SCALAR from the specified SOCKET filehandle.
-SCALAR will be grown or shrunk to the length actually read. Takes the
-same flags as the system call of the same name. Returns the address
-of the sender if SOCKET's protocol supports this; returns an empty
-string otherwise. If there's an error, returns the undefined value.
-This call is actually implemented in terms of recvfrom(2) system call.
-See L<perlipc/"UDP: Message Passing"> for examples.
-
-Note the I<characters>: depending on the status of the socket, either
-(8-bit) bytes or characters are received. By default all sockets
-operate on bytes, but for example if the socket has been changed using
-binmode() to operate with the C<:encoding(utf8)> I/O layer (see the
-C<open> pragma, L<open>), the I/O will operate on UTF8-encoded Unicode
-characters, not bytes. Similarly for the C<:encoding> pragma: in that
-case pretty much any characters can be read.
-
-=item redo LABEL
-X<redo>
-
-=item redo
-
-=for Pod::Functions start this loop iteration over again
-
-The C<redo> command restarts the loop block without evaluating the
-conditional again. The C<continue> block, if any, is not executed. If
-the LABEL is omitted, the command refers to the innermost enclosing
-loop. Programs that want to lie to themselves about what was just input
-normally use this command:
-
- # a simpleminded Pascal comment stripper
- # (warning: assumes no { or } in strings)
- LINE: while (<STDIN>) {
- while (s|({.*}.*){.*}|$1 |) {}
- s|{.*}| |;
- if (s|{.*| |) {
- $front = $_;
- while (<STDIN>) {
- if (/}/) { # end of comment?
- s|^|$front\{|;
- redo LINE;
- }
- }
- }
- print;
- }
-
-C<redo> cannot be used to retry a block that returns a value such as
-C<eval {}>, C<sub {}>, or C<do {}>, and should not be used to exit
-a grep() or map() operation.
-
-Note that a block by itself is semantically identical to a loop
-that executes once. Thus C<redo> inside such a block will effectively
-turn it into a looping construct.
-
-See also L</continue> for an illustration of how C<last>, C<next>, and
-C<redo> work.
-
-=item ref EXPR
-X<ref> X<reference>
-
-=item ref
-
-=for Pod::Functions find out the type of thing being referenced
-
-Returns a non-empty string if EXPR is a reference, the empty
-string otherwise. If EXPR
-is not specified, C<$_> will be used. The value returned depends on the
-type of thing the reference is a reference to.
-Builtin types include:
-
- SCALAR
- ARRAY
- HASH
- CODE
- REF
- GLOB
- LVALUE
- FORMAT
- IO
- VSTRING
- Regexp
-
-If the referenced object has been blessed into a package, then that package
-name is returned instead. You can think of C<ref> as a C<typeof> operator.
-
- if (ref($r) eq "HASH") {
- print "r is a reference to a hash.\n";
- }
- unless (ref($r)) {
- print "r is not a reference at all.\n";
- }
-
-The return value C<LVALUE> indicates a reference to an lvalue that is not
-a variable. You get this from taking the reference of function calls like
-C<pos()> or C<substr()>. C<VSTRING> is returned if the reference points
-to a L<version string|perldata/"Version Strings">.
-
-The result C<Regexp> indicates that the argument is a regular expression
-resulting from C<qr//>.
-
-See also L<perlref>.
-
-=item rename OLDNAME,NEWNAME
-X<rename> X<move> X<mv> X<ren>
-
-=for Pod::Functions change a filename
-
-Changes the name of a file; an existing file NEWNAME will be
-clobbered. Returns true for success, false otherwise.
-
-Behavior of this function varies wildly depending on your system
-implementation. For example, it will usually not work across file system
-boundaries, even though the system I<mv> command sometimes compensates
-for this. Other restrictions include whether it works on directories,
-open files, or pre-existing files. Check L<perlport> and either the
-rename(2) manpage or equivalent system documentation for details.
-
-For a platform independent C<move> function look at the L<File::Copy>
-module.
-
-Portability issues: L<perlport/rename>.
-
-=item require VERSION
-X<require>
-
-=item require EXPR
-
-=item require
-
-=for Pod::Functions load in external functions from a library at runtime
-
-Demands a version of Perl specified by VERSION, or demands some semantics
-specified by EXPR or by C<$_> if EXPR is not supplied.
-
-VERSION may be either a numeric argument such as 5.006, which will be
-compared to C<$]>, or a literal of the form v5.6.1, which will be compared
-to C<$^V> (aka $PERL_VERSION). An exception is raised if
-VERSION is greater than the version of the current Perl interpreter.
-Compare with L</use>, which can do a similar check at compile time.
-
-Specifying VERSION as a literal of the form v5.6.1 should generally be
-avoided, because it leads to misleading error messages under earlier
-versions of Perl that do not support this syntax. The equivalent numeric
-version should be used instead.
-
- require v5.6.1; # run time version check
- require 5.6.1; # ditto
- require 5.006_001; # ditto; preferred for backwards compatibility
-
-Otherwise, C<require> demands that a library file be included if it
-hasn't already been included. The file is included via the do-FILE
-mechanism, which is essentially just a variety of C<eval> with the
-caveat that lexical variables in the invoking script will be invisible
-to the included code. Has semantics similar to the following subroutine:
-
- sub require {
- my ($filename) = @_;
- if (exists $INC{$filename}) {
- return 1 if $INC{$filename};
- die "Compilation failed in require";
- }
- my ($realfilename,$result);
- ITER: {
- foreach $prefix (@INC) {
- $realfilename = "$prefix/$filename";
- if (-f $realfilename) {
- $INC{$filename} = $realfilename;
- $result = do $realfilename;
- last ITER;
- }
- }
- die "Can't find $filename in \@INC";
- }
- if ($@) {
- $INC{$filename} = undef;
- die $@;
- } elsif (!$result) {
- delete $INC{$filename};
- die "$filename did not return true value";
- } else {
- return $result;
- }
- }
-
-Note that the file will not be included twice under the same specified
-name.
-
-The file must return true as the last statement to indicate
-successful execution of any initialization code, so it's customary to
-end such a file with C<1;> unless you're sure it'll return true
-otherwise. But it's better just to put the C<1;>, in case you add more
-statements.
-
-If EXPR is a bareword, the require assumes a "F<.pm>" extension and
-replaces "F<::>" with "F</>" in the filename for you,
-to make it easy to load standard modules. This form of loading of
-modules does not risk altering your namespace.
-
-In other words, if you try this:
-
- require Foo::Bar; # a splendid bareword
-
-The require function will actually look for the "F<Foo/Bar.pm>" file in the
-directories specified in the C<@INC> array.
-
-But if you try this:
-
- $class = 'Foo::Bar';
- require $class; # $class is not a bareword
- #or
- require "Foo::Bar"; # not a bareword because of the ""
-
-The require function will look for the "F<Foo::Bar>" file in the @INC array and
-will complain about not finding "F<Foo::Bar>" there. In this case you can do:
-
- eval "require $class";
-
-Now that you understand how C<require> looks for files with a
-bareword argument, there is a little extra functionality going on behind
-the scenes. Before C<require> looks for a "F<.pm>" extension, it will
-first look for a similar filename with a "F<.pmc>" extension. If this file
-is found, it will be loaded in place of any file ending in a "F<.pm>"
-extension.
-
-You can also insert hooks into the import facility by putting Perl code
-directly into the @INC array. There are three forms of hooks: subroutine
-references, array references, and blessed objects.
-
-Subroutine references are the simplest case. When the inclusion system
-walks through @INC and encounters a subroutine, this subroutine gets
-called with two parameters, the first a reference to itself, and the
-second the name of the file to be included (e.g., "F<Foo/Bar.pm>"). The
-subroutine should return either nothing or else a list of up to three
-values in the following order:
-
-=over
-
-=item 1
-
-A filehandle, from which the file will be read.
-
-=item 2
-
-A reference to a subroutine. If there is no filehandle (previous item),
-then this subroutine is expected to generate one line of source code per
-call, writing the line into C<$_> and returning 1, then finally at end of
-file returning 0. If there is a filehandle, then the subroutine will be
-called to act as a simple source filter, with the line as read in C<$_>.
-Again, return 1 for each valid line, and 0 after all lines have been
-returned.
-
-=item 3
-
-Optional state for the subroutine. The state is passed in as C<$_[1]>. A
-reference to the subroutine itself is passed in as C<$_[0]>.
-
-=back
-
-If an empty list, C<undef>, or nothing that matches the first 3 values above
-is returned, then C<require> looks at the remaining elements of @INC.
-Note that this filehandle must be a real filehandle (strictly a typeglob
-or reference to a typeglob, whether blessed or unblessed); tied filehandles
-will be ignored and processing will stop there.
-
-If the hook is an array reference, its first element must be a subroutine
-reference. This subroutine is called as above, but the first parameter is
-the array reference. This lets you indirectly pass arguments to
-the subroutine.
-
-In other words, you can write:
-
- push @INC, \&my_sub;
- sub my_sub {
- my ($coderef, $filename) = @_; # $coderef is \&my_sub
- ...
- }
-
-or:
-
- push @INC, [ \&my_sub, $x, $y, ... ];
- sub my_sub {
- my ($arrayref, $filename) = @_;
- # Retrieve $x, $y, ...
- my @parameters = @$arrayref[1..$#$arrayref];
- ...
- }
-
-If the hook is an object, it must provide an INC method that will be
-called as above, the first parameter being the object itself. (Note that
-you must fully qualify the sub's name, as unqualified C<INC> is always forced
-into package C<main>.) Here is a typical code layout:
-
- # In Foo.pm
- package Foo;
- sub new { ... }
- sub Foo::INC {
- my ($self, $filename) = @_;
- ...
- }
-
- # In the main program
- push @INC, Foo->new(...);
-
-These hooks are also permitted to set the %INC entry
-corresponding to the files they have loaded. See L<perlvar/%INC>.
-
-For a yet-more-powerful import facility, see L</use> and L<perlmod>.
-
-=item reset EXPR
-X<reset>
-
-=item reset
-
-=for Pod::Functions clear all variables of a given name
-
-Generally used in a C<continue> block at the end of a loop to clear
-variables and reset C<??> searches so that they work again. The
-expression is interpreted as a list of single characters (hyphens
-allowed for ranges). All variables and arrays beginning with one of
-those letters are reset to their pristine state. If the expression is
-omitted, one-match searches (C<?pattern?>) are reset to match again.
-Only resets variables or searches in the current package. Always returns
-1. Examples:
-
- reset 'X'; # reset all X variables
- reset 'a-z'; # reset lower case variables
- reset; # just reset ?one-time? searches
-
-Resetting C<"A-Z"> is not recommended because you'll wipe out your
-C<@ARGV> and C<@INC> arrays and your C<%ENV> hash. Resets only package
-variables; lexical variables are unaffected, but they clean themselves
-up on scope exit anyway, so you'll probably want to use them instead.
-See L</my>.
-
-=item return EXPR
-X<return>
-
-=item return
-
-=for Pod::Functions get out of a function early
-
-Returns from a subroutine, C<eval>, or C<do FILE> with the value
-given in EXPR. Evaluation of EXPR may be in list, scalar, or void
-context, depending on how the return value will be used, and the context
-may vary from one execution to the next (see L</wantarray>). If no EXPR
-is given, returns an empty list in list context, the undefined value in
-scalar context, and (of course) nothing at all in void context.
-
-(In the absence of an explicit C<return>, a subroutine, eval,
-or do FILE automatically returns the value of the last expression
-evaluated.)
-
-=item reverse LIST
-X<reverse> X<rev> X<invert>
-
-=for Pod::Functions flip a string or a list
-
-In list context, returns a list value consisting of the elements
-of LIST in the opposite order. In scalar context, concatenates the
-elements of LIST and returns a string value with all characters
-in the opposite order.
-
- print join(", ", reverse "world", "Hello"); # Hello, world
-
- print scalar reverse "dlrow ,", "olleH"; # Hello, world
-
-Used without arguments in scalar context, reverse() reverses C<$_>.
-
- $_ = "dlrow ,olleH";
- print reverse; # No output, list context
- print scalar reverse; # Hello, world
-
-Note that reversing an array to itself (as in C<@a = reverse @a>) will
-preserve non-existent elements whenever possible, i.e., for non magical
-arrays or tied arrays with C<EXISTS> and C<DELETE> methods.
-
-This operator is also handy for inverting a hash, although there are some
-caveats. If a value is duplicated in the original hash, only one of those
-can be represented as a key in the inverted hash. Also, this has to
-unwind one hash and build a whole new one, which may take some time
-on a large hash, such as from a DBM file.
-
- %by_name = reverse %by_address; # Invert the hash
-
-=item rewinddir DIRHANDLE
-X<rewinddir>
-
-=for Pod::Functions reset directory handle
-
-Sets the current position to the beginning of the directory for the
-C<readdir> routine on DIRHANDLE.
-
-Portability issues: L<perlport/rewinddir>.
-
-=item rindex STR,SUBSTR,POSITION
-X<rindex>
-
-=item rindex STR,SUBSTR
-
-=for Pod::Functions right-to-left substring search
-
-Works just like index() except that it returns the position of the I<last>
-occurrence of SUBSTR in STR. If POSITION is specified, returns the
-last occurrence beginning at or before that position.
-
-=item rmdir FILENAME
-X<rmdir> X<rd> X<directory, remove>
-
-=item rmdir
-
-=for Pod::Functions remove a directory
-
-Deletes the directory specified by FILENAME if that directory is
-empty. If it succeeds it returns true; otherwise it returns false and
-sets C<$!> (errno). If FILENAME is omitted, uses C<$_>.
-
-To remove a directory tree recursively (C<rm -rf> on Unix) look at
-the C<rmtree> function of the L<File::Path> module.
-
-=item s///
-
-=for Pod::Functions replace a pattern with a string
-
-The substitution operator. See L<perlop/"Regexp Quote-Like Operators">.
-
-=item say FILEHANDLE LIST
-X<say>
-
-=item say FILEHANDLE
-
-=item say LIST
-
-=item say
-
-=for Pod::Functions +say output a list to a filehandle, appending a newline
-
-Just like C<print>, but implicitly appends a newline. C<say LIST> is
-simply an abbreviation for C<{ local $\ = "\n"; print LIST }>. To use
-FILEHANDLE without a LIST to print the contents of C<$_> to it, you must
-use a real filehandle like C<FH>, not an indirect one like C<$fh>.
-
-This keyword is available only when the C<"say"> feature
-is enabled, or when prefixed with C<CORE::>; see
-L<feature>. Alternately, include a C<use v5.10> or later to the current
-scope.
-
-=item scalar EXPR
-X<scalar> X<context>
-
-=for Pod::Functions force a scalar context
-
-Forces EXPR to be interpreted in scalar context and returns the value
-of EXPR.
-
- @counts = ( scalar @a, scalar @b, scalar @c );
-
-There is no equivalent operator to force an expression to
-be interpolated in list context because in practice, this is never
-needed. If you really wanted to do so, however, you could use
-the construction C<@{[ (some expression) ]}>, but usually a simple
-C<(some expression)> suffices.
-
-Because C<scalar> is a unary operator, if you accidentally use a
-parenthesized list for the EXPR, this behaves as a scalar comma expression,
-evaluating all but the last element in void context and returning the final
-element evaluated in scalar context. This is seldom what you want.
-
-The following single statement:
-
- print uc(scalar(&foo,$bar)),$baz;
-
-is the moral equivalent of these two:
-
- &foo;
- print(uc($bar),$baz);
-
-See L<perlop> for more details on unary operators and the comma operator.
-
-=item seek FILEHANDLE,POSITION,WHENCE
-X<seek> X<fseek> X<filehandle, position>
-
-=for Pod::Functions reposition file pointer for random-access I/O
-
-Sets FILEHANDLE's position, just like the C<fseek> call of C<stdio>.
-FILEHANDLE may be an expression whose value gives the name of the
-filehandle. The values for WHENCE are C<0> to set the new position
-I<in bytes> to POSITION; C<1> to set it to the current position plus
-POSITION; and C<2> to set it to EOF plus POSITION, typically
-negative. For WHENCE you may use the constants C<SEEK_SET>,
-C<SEEK_CUR>, and C<SEEK_END> (start of the file, current position, end
-of the file) from the L<Fcntl> module. Returns C<1> on success, false
-otherwise.
-
-Note the I<in bytes>: even if the filehandle has been set to
-operate on characters (for example by using the C<:encoding(utf8)> open
-layer), tell() will return byte offsets, not character offsets
-(because implementing that would render seek() and tell() rather slow).
-
-If you want to position the file for C<sysread> or C<syswrite>, don't use
-C<seek>, because buffering makes its effect on the file's read-write position
-unpredictable and non-portable. Use C<sysseek> instead.
-
-Due to the rules and rigors of ANSI C, on some systems you have to do a
-seek whenever you switch between reading and writing. Amongst other
-things, this may have the effect of calling stdio's clearerr(3).
-A WHENCE of C<1> (C<SEEK_CUR>) is useful for not moving the file position:
-
- seek(TEST,0,1);
-
-This is also useful for applications emulating C<tail -f>. Once you hit
-EOF on your read and then sleep for a while, you (probably) have to stick in a
-dummy seek() to reset things. The C<seek> doesn't change the position,
-but it I<does> clear the end-of-file condition on the handle, so that the
-next C<< <FILE> >> makes Perl try again to read something. (We hope.)
-
-If that doesn't work (some I/O implementations are particularly
-cantankerous), you might need something like this:
-
- for (;;) {
- for ($curpos = tell(FILE); $_ = <FILE>;
- $curpos = tell(FILE)) {
- # search for some stuff and put it into files
- }
- sleep($for_a_while);
- seek(FILE, $curpos, 0);
- }
-
-=item seekdir DIRHANDLE,POS
-X<seekdir>
-
-=for Pod::Functions reposition directory pointer
-
-Sets the current position for the C<readdir> routine on DIRHANDLE. POS
-must be a value returned by C<telldir>. C<seekdir> also has the same caveats
-about possible directory compaction as the corresponding system library
-routine.
-
-=item select FILEHANDLE
-X<select> X<filehandle, default>
-
-=item select
-
-=for Pod::Functions reset default output or do I/O multiplexing
-
-Returns the currently selected filehandle. If FILEHANDLE is supplied,
-sets the new current default filehandle for output. This has two
-effects: first, a C<write> or a C<print> without a filehandle
-default to this FILEHANDLE. Second, references to variables related to
-output will refer to this output channel.
-
-For example, to set the top-of-form format for more than one
-output channel, you might do the following:
-
- select(REPORT1);
- $^ = 'report1_top';
- select(REPORT2);
- $^ = 'report2_top';
-
-FILEHANDLE may be an expression whose value gives the name of the
-actual filehandle. Thus:
-
- $oldfh = select(STDERR); $| = 1; select($oldfh);
-
-Some programmers may prefer to think of filehandles as objects with
-methods, preferring to write the last example as:
-
- use IO::Handle;
- STDERR->autoflush(1);
-
-Portability issues: L<perlport/select>.
-
-=item select RBITS,WBITS,EBITS,TIMEOUT
-X<select>
-
-This calls the select(2) syscall with the bit masks specified, which
-can be constructed using C<fileno> and C<vec>, along these lines:
-
- $rin = $win = $ein = '';
- vec($rin, fileno(STDIN), 1) = 1;
- vec($win, fileno(STDOUT), 1) = 1;
- $ein = $rin | $win;
-
-If you want to select on many filehandles, you may wish to write a
-subroutine like this:
-
- sub fhbits {
- my @fhlist = @_;
- my $bits = "";
- for my $fh (@fhlist) {
- vec($bits, fileno($fh), 1) = 1;
- }
- return $bits;
- }
- $rin = fhbits(*STDIN, *TTY, *MYSOCK);
-
-The usual idiom is:
-
- ($nfound,$timeleft) =
- select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
-
-or to block until something becomes ready just do this
-
- $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
-
-Most systems do not bother to return anything useful in $timeleft, so
-calling select() in scalar context just returns $nfound.
-
-Any of the bit masks can also be undef. The timeout, if specified, is
-in seconds, which may be fractional. Note: not all implementations are
-capable of returning the $timeleft. If not, they always return
-$timeleft equal to the supplied $timeout.
-
-You can effect a sleep of 250 milliseconds this way:
-
- select(undef, undef, undef, 0.25);
-
-Note that whether C<select> gets restarted after signals (say, SIGALRM)
-is implementation-dependent. See also L<perlport> for notes on the
-portability of C<select>.
-
-On error, C<select> behaves just like select(2): it returns
--1 and sets C<$!>.
-
-On some Unixes, select(2) may report a socket file descriptor as "ready for
-reading" even when no data is available, and thus any subsequent C<read>
-would block. This can be avoided if you always use O_NONBLOCK on the
-socket. See select(2) and fcntl(2) for further details.
-
-The standard C<IO::Select> module provides a user-friendlier interface
-to C<select>, mostly because it does all the bit-mask work for you.
-
-B<WARNING>: One should not attempt to mix buffered I/O (like C<read>
-or <FH>) with C<select>, except as permitted by POSIX, and even
-then only on POSIX systems. You have to use C<sysread> instead.
-
-Portability issues: L<perlport/select>.
-
-=item semctl ID,SEMNUM,CMD,ARG
-X<semctl>
-
-=for Pod::Functions SysV semaphore control operations
-
-Calls the System V IPC function semctl(2). You'll probably have to say
-
- use IPC::SysV;
-
-first to get the correct constant definitions. If CMD is IPC_STAT or
-GETALL, then ARG must be a variable that will hold the returned
-semid_ds structure or semaphore value array. Returns like C<ioctl>:
-the undefined value for error, "C<0 but true>" for zero, or the actual
-return value otherwise. The ARG must consist of a vector of native
-short integers, which may be created with C<pack("s!",(0)x$nsem)>.
-See also L<perlipc/"SysV IPC">, C<IPC::SysV>, C<IPC::Semaphore>
-documentation.
-
-Portability issues: L<perlport/semctl>.
-
-=item semget KEY,NSEMS,FLAGS
-X<semget>
-
-=for Pod::Functions get set of SysV semaphores
-
-Calls the System V IPC function semget(2). Returns the semaphore id, or
-the undefined value on error. See also
-L<perlipc/"SysV IPC">, C<IPC::SysV>, C<IPC::SysV::Semaphore>
-documentation.
-
-Portability issues: L<perlport/semget>.
-
-=item semop KEY,OPSTRING
-X<semop>
-
-=for Pod::Functions SysV semaphore operations
-
-Calls the System V IPC function semop(2) for semaphore operations
-such as signalling and waiting. OPSTRING must be a packed array of
-semop structures. Each semop structure can be generated with
-C<pack("s!3", $semnum, $semop, $semflag)>. The length of OPSTRING
-implies the number of semaphore operations. Returns true if
-successful, false on error. As an example, the
-following code waits on semaphore $semnum of semaphore id $semid:
-
- $semop = pack("s!3", $semnum, -1, 0);
- die "Semaphore trouble: $!\n" unless semop($semid, $semop);
-
-To signal the semaphore, replace C<-1> with C<1>. See also
-L<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::SysV::Semaphore>
-documentation.
-
-Portability issues: L<perlport/semop>.
-
-=item send SOCKET,MSG,FLAGS,TO
-X<send>
-
-=item send SOCKET,MSG,FLAGS
-
-=for Pod::Functions send a message over a socket
-
-Sends a message on a socket. Attempts to send the scalar MSG to the SOCKET
-filehandle. Takes the same flags as the system call of the same name. On
-unconnected sockets, you must specify a destination to I<send to>, in which
-case it does a sendto(2) syscall. Returns the number of characters sent,
-or the undefined value on error. The sendmsg(2) syscall is currently
-unimplemented. See L<perlipc/"UDP: Message Passing"> for examples.
-
-Note the I<characters>: depending on the status of the socket, either
-(8-bit) bytes or characters are sent. By default all sockets operate
-on bytes, but for example if the socket has been changed using
-binmode() to operate with the C<:encoding(utf8)> I/O layer (see
-L</open>, or the C<open> pragma, L<open>), the I/O will operate on UTF-8
-encoded Unicode characters, not bytes. Similarly for the C<:encoding>
-pragma: in that case pretty much any characters can be sent.
-
-=item setpgrp PID,PGRP
-X<setpgrp> X<group>
-
-=for Pod::Functions set the process group of a process
-
-Sets the current process group for the specified PID, C<0> for the current
-process. Raises an exception when used on a machine that doesn't
-implement POSIX setpgid(2) or BSD setpgrp(2). If the arguments are omitted,
-it defaults to C<0,0>. Note that the BSD 4.2 version of C<setpgrp> does not
-accept any arguments, so only C<setpgrp(0,0)> is portable. See also
-C<POSIX::setsid()>.
-
-Portability issues: L<perlport/setpgrp>.
-
-=item setpriority WHICH,WHO,PRIORITY
-X<setpriority> X<priority> X<nice> X<renice>
-
-=for Pod::Functions set a process's nice value
-
-Sets the current priority for a process, a process group, or a user.
-(See setpriority(2).) Raises an exception when used on a machine
-that doesn't implement setpriority(2).
-
-Portability issues: L<perlport/setpriority>.
-
-=item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
-X<setsockopt>
-
-=for Pod::Functions set some socket options
-
-Sets the socket option requested. Returns C<undef> on error.
-Use integer constants provided by the C<Socket> module for
-LEVEL and OPNAME. Values for LEVEL can also be obtained from
-getprotobyname. OPTVAL might either be a packed string or an integer.
-An integer OPTVAL is shorthand for pack("i", OPTVAL).
-
-An example disabling Nagle's algorithm on a socket:
-
- use Socket qw(IPPROTO_TCP TCP_NODELAY);
- setsockopt($socket, IPPROTO_TCP, TCP_NODELAY, 1);
-
-Portability issues: L<perlport/setsockopt>.
-
-=item shift ARRAY
-X<shift>
-
-=item shift EXPR
-
-=item shift
-
-=for Pod::Functions remove the first element of an array, and return it
-
-Shifts the first value of the array off and returns it, shortening the
-array by 1 and moving everything down. If there are no elements in the
-array, returns the undefined value. If ARRAY is omitted, shifts the
-C<@_> array within the lexical scope of subroutines and formats, and the
-C<@ARGV> array outside a subroutine and also within the lexical scopes
-established by the C<eval STRING>, C<BEGIN {}>, C<INIT {}>, C<CHECK {}>,
-C<UNITCHECK {}>, and C<END {}> constructs.
-
-Starting with Perl 5.14, C<shift> can take a scalar EXPR, which must hold a
-reference to an unblessed array. The argument will be dereferenced
-automatically. This aspect of C<shift> is considered highly experimental.
-The exact behaviour may change in a future version of Perl.
-
-To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work I<only> on Perls of
-a recent vintage:
-
- use 5.014; # so push/pop/etc work on scalars (experimental)
-
-See also C<unshift>, C<push>, and C<pop>. C<shift> and C<unshift> do the
-same thing to the left end of an array that C<pop> and C<push> do to the
-right end.
-
-=item shmctl ID,CMD,ARG
-X<shmctl>
-
-=for Pod::Functions SysV shared memory operations
-
-Calls the System V IPC function shmctl. You'll probably have to say
-
- use IPC::SysV;
-
-first to get the correct constant definitions. If CMD is C<IPC_STAT>,
-then ARG must be a variable that will hold the returned C<shmid_ds>
-structure. Returns like ioctl: C<undef> for error; "C<0> but
-true" for zero; and the actual return value otherwise.
-See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
-
-Portability issues: L<perlport/shmctl>.
-
-=item shmget KEY,SIZE,FLAGS
-X<shmget>
-
-=for Pod::Functions get SysV shared memory segment identifier
-
-Calls the System V IPC function shmget. Returns the shared memory
-segment id, or C<undef> on error.
-See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
-
-Portability issues: L<perlport/shmget>.
-
-=item shmread ID,VAR,POS,SIZE
-X<shmread>
-X<shmwrite>
-
-=for Pod::Functions read SysV shared memory
-
-=item shmwrite ID,STRING,POS,SIZE
-
-=for Pod::Functions write SysV shared memory
-
-Reads or writes the System V shared memory segment ID starting at
-position POS for size SIZE by attaching to it, copying in/out, and
-detaching from it. When reading, VAR must be a variable that will
-hold the data read. When writing, if STRING is too long, only SIZE
-bytes are used; if STRING is too short, nulls are written to fill out
-SIZE bytes. Return true if successful, false on error.
-shmread() taints the variable. See also L<perlipc/"SysV IPC">,
-C<IPC::SysV>, and the C<IPC::Shareable> module from CPAN.
-
-Portability issues: L<perlport/shmread> and L<perlport/shmwrite>.
-
-=item shutdown SOCKET,HOW
-X<shutdown>
-
-=for Pod::Functions close down just half of a socket connection
-
-Shuts down a socket connection in the manner indicated by HOW, which
-has the same interpretation as in the syscall of the same name.
-
- shutdown(SOCKET, 0); # I/we have stopped reading data
- shutdown(SOCKET, 1); # I/we have stopped writing data
- shutdown(SOCKET, 2); # I/we have stopped using this socket
-
-This is useful with sockets when you want to tell the other
-side you're done writing but not done reading, or vice versa.
-It's also a more insistent form of close because it also
-disables the file descriptor in any forked copies in other
-processes.
-
-Returns C<1> for success; on error, returns C<undef> if
-the first argument is not a valid filehandle, or returns C<0> and sets
-C<$!> for any other failure.
-
-=item sin EXPR
-X<sin> X<sine> X<asin> X<arcsine>
-
-=item sin
-
-=for Pod::Functions return the sine of a number
-
-Returns the sine of EXPR (expressed in radians). If EXPR is omitted,
-returns sine of C<$_>.
-
-For the inverse sine operation, you may use the C<Math::Trig::asin>
-function, or use this relation:
-
- sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
-
-=item sleep EXPR
-X<sleep> X<pause>
-
-=item sleep
-
-=for Pod::Functions block for some number of seconds
-
-Causes the script to sleep for (integer) EXPR seconds, or forever if no
-argument is given. Returns the integer number of seconds actually slept.
-
-May be interrupted if the process receives a signal such as C<SIGALRM>.
-
- eval {
- local $SIG{ALARM} = sub { die "Alarm!\n" };
- sleep;
- };
- die $@ unless $@ eq "Alarm!\n";
-
-You probably cannot mix C<alarm> and C<sleep> calls, because C<sleep>
-is often implemented using C<alarm>.
-
-On some older systems, it may sleep up to a full second less than what
-you requested, depending on how it counts seconds. Most modern systems
-always sleep the full amount. They may appear to sleep longer than that,
-however, because your process might not be scheduled right away in a
-busy multitasking system.
-
-For delays of finer granularity than one second, the Time::HiRes module
-(from CPAN, and starting from Perl 5.8 part of the standard
-distribution) provides usleep(). You may also use Perl's four-argument
-version of select() leaving the first three arguments undefined, or you
-might be able to use the C<syscall> interface to access setitimer(2) if
-your system supports it. See L<perlfaq8> for details.
-
-See also the POSIX module's C<pause> function.
-
-=item socket SOCKET,DOMAIN,TYPE,PROTOCOL
-X<socket>
-
-=for Pod::Functions create a socket
-
-Opens a socket of the specified kind and attaches it to filehandle
-SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as for
-the syscall of the same name. You should C<use Socket> first
-to get the proper definitions imported. See the examples in
-L<perlipc/"Sockets: Client/Server Communication">.
-
-On systems that support a close-on-exec flag on files, the flag will
-be set for the newly opened file descriptor, as determined by the
-value of $^F. See L<perlvar/$^F>.
-
-=item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
-X<socketpair>
-
-=for Pod::Functions create a pair of sockets
-
-Creates an unnamed pair of sockets in the specified domain, of the
-specified type. DOMAIN, TYPE, and PROTOCOL are specified the same as
-for the syscall of the same name. If unimplemented, raises an exception.
-Returns true if successful.
-
-On systems that support a close-on-exec flag on files, the flag will
-be set for the newly opened file descriptors, as determined by the value
-of $^F. See L<perlvar/$^F>.
-
-Some systems defined C<pipe> in terms of C<socketpair>, in which a call
-to C<pipe(Rdr, Wtr)> is essentially:
-
- use Socket;
- socketpair(Rdr, Wtr, AF_UNIX, SOCK_STREAM, PF_UNSPEC);
- shutdown(Rdr, 1); # no more writing for reader
- shutdown(Wtr, 0); # no more reading for writer
-
-See L<perlipc> for an example of socketpair use. Perl 5.8 and later will
-emulate socketpair using IP sockets to localhost if your system implements
-sockets but not socketpair.
-
-Portability issues: L<perlport/socketpair>.
-
-=item sort SUBNAME LIST
-X<sort> X<qsort> X<quicksort> X<mergesort>
-
-=item sort BLOCK LIST
-
-=item sort LIST
-
-=for Pod::Functions sort a list of values
-
-In list context, this sorts the LIST and returns the sorted list value.
-In scalar context, the behaviour of C<sort()> is undefined.
-
-If SUBNAME or BLOCK is omitted, C<sort>s in standard string comparison
-order. If SUBNAME is specified, it gives the name of a subroutine
-that returns an integer less than, equal to, or greater than C<0>,
-depending on how the elements of the list are to be ordered. (The
-C<< <=> >> and C<cmp> operators are extremely useful in such routines.)
-SUBNAME may be a scalar variable name (unsubscripted), in which case
-the value provides the name of (or a reference to) the actual
-subroutine to use. In place of a SUBNAME, you can provide a BLOCK as
-an anonymous, in-line sort subroutine.
-
-If the subroutine's prototype is C<($$)>, the elements to be compared are
-passed by reference in C<@_>, as for a normal subroutine. This is slower
-than unprototyped subroutines, where the elements to be compared are passed
-into the subroutine as the package global variables $a and $b (see example
-below). Note that in the latter case, it is usually highly counter-productive
-to declare $a and $b as lexicals.
-
-If the subroutine is an XSUB, the elements to be compared are pushed on to
-the stack, the way arguments are usually passed to XSUBs. $a and $b are
-not set.
-
-The values to be compared are always passed by reference and should not
-be modified.
-
-You also cannot exit out of the sort block or subroutine using any of the
-loop control operators described in L<perlsyn> or with C<goto>.
-
-When C<use locale> (but not C<use locale 'not_characters'>) is in
-effect, C<sort LIST> sorts LIST according to the
-current collation locale. See L<perllocale>.
-
-sort() returns aliases into the original list, much as a for loop's index
-variable aliases the list elements. That is, modifying an element of a
-list returned by sort() (for example, in a C<foreach>, C<map> or C<grep>)
-actually modifies the element in the original list. This is usually
-something to be avoided when writing clear code.
-
-Perl 5.6 and earlier used a quicksort algorithm to implement sort.
-That algorithm was not stable, so I<could> go quadratic. (A I<stable> sort
-preserves the input order of elements that compare equal. Although
-quicksort's run time is O(NlogN) when averaged over all arrays of
-length N, the time can be O(N**2), I<quadratic> behavior, for some
-inputs.) In 5.7, the quicksort implementation was replaced with
-a stable mergesort algorithm whose worst-case behavior is O(NlogN).
-But benchmarks indicated that for some inputs, on some platforms,
-the original quicksort was faster. 5.8 has a sort pragma for
-limited control of the sort. Its rather blunt control of the
-underlying algorithm may not persist into future Perls, but the
-ability to characterize the input or output in implementation
-independent ways quite probably will. See L<the sort pragma|sort>.
-
-Examples:
-
- # sort lexically
- @articles = sort @files;
-
- # same thing, but with explicit sort routine
- @articles = sort {$a cmp $b} @files;
-
- # now case-insensitively
- @articles = sort {fc($a) cmp fc($b)} @files;
-
- # same thing in reversed order
- @articles = sort {$b cmp $a} @files;
-
- # sort numerically ascending
- @articles = sort {$a <=> $b} @files;
-
- # sort numerically descending
- @articles = sort {$b <=> $a} @files;
-
- # this sorts the %age hash by value instead of key
- # using an in-line function
- @eldest = sort { $age{$b} <=> $age{$a} } keys %age;
-
- # sort using explicit subroutine name
- sub byage {
- $age{$a} <=> $age{$b}; # presuming numeric
- }
- @sortedclass = sort byage @class;
-
- sub backwards { $b cmp $a }
- @harry = qw(dog cat x Cain Abel);
- @george = qw(gone chased yz Punished Axed);
- print sort @harry;
- # prints AbelCaincatdogx
- print sort backwards @harry;
- # prints xdogcatCainAbel
- print sort @george, 'to', @harry;
- # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
-
- # inefficiently sort by descending numeric compare using
- # the first integer after the first = sign, or the
- # whole record case-insensitively otherwise
-
- my @new = sort {
- ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0]
- ||
- fc($a) cmp fc($b)
- } @old;
-
- # same thing, but much more efficiently;
- # we'll build auxiliary indices instead
- # for speed
- my @nums = @caps = ();
- for (@old) {
- push @nums, ( /=(\d+)/ ? $1 : undef );
- push @caps, fc($_);
- }
-
- my @new = @old[ sort {
- $nums[$b] <=> $nums[$a]
- ||
- $caps[$a] cmp $caps[$b]
- } 0..$#old
- ];
-
- # same thing, but without any temps
- @new = map { $_->[0] }
- sort { $b->[1] <=> $a->[1]
- ||
- $a->[2] cmp $b->[2]
- } map { [$_, /=(\d+)/, fc($_)] } @old;
-
- # using a prototype allows you to use any comparison subroutine
- # as a sort subroutine (including other package's subroutines)
- package other;
- sub backwards ($$) { $_[1] cmp $_[0]; } # $a and $b are not set here
-
- package main;
- @new = sort other::backwards @old;
-
- # guarantee stability, regardless of algorithm
- use sort 'stable';
- @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
-
- # force use of mergesort (not portable outside Perl 5.8)
- use sort '_mergesort'; # note discouraging _
- @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
-
-Warning: syntactical care is required when sorting the list returned from
-a function. If you want to sort the list returned by the function call
-C<find_records(@key)>, you can use:
-
- @contact = sort { $a cmp $b } find_records @key;
- @contact = sort +find_records(@key);
- @contact = sort &find_records(@key);
- @contact = sort(find_records(@key));
-
-If instead you want to sort the array @key with the comparison routine
-C<find_records()> then you can use:
-
- @contact = sort { find_records() } @key;
- @contact = sort find_records(@key);
- @contact = sort(find_records @key);
- @contact = sort(find_records (@key));
-
-If you're using strict, you I<must not> declare $a
-and $b as lexicals. They are package globals. That means
-that if you're in the C<main> package and type
-
- @articles = sort {$b <=> $a} @files;
-
-then C<$a> and C<$b> are C<$main::a> and C<$main::b> (or C<$::a> and C<$::b>),
-but if you're in the C<FooPack> package, it's the same as typing
-
- @articles = sort {$FooPack::b <=> $FooPack::a} @files;
-
-The comparison function is required to behave. If it returns
-inconsistent results (sometimes saying C<$x[1]> is less than C<$x[2]> and
-sometimes saying the opposite, for example) the results are not
-well-defined.
-
-Because C<< <=> >> returns C<undef> when either operand is C<NaN>
-(not-a-number), be careful when sorting with a
-comparison function like C<< $a <=> $b >> any lists that might contain a
-C<NaN>. The following example takes advantage that C<NaN != NaN> to
-eliminate any C<NaN>s from the input list.
-
- @result = sort { $a <=> $b } grep { $_ == $_ } @input;
-
-=item splice ARRAY or EXPR,OFFSET,LENGTH,LIST
-X<splice>
-
-=item splice ARRAY or EXPR,OFFSET,LENGTH
-
-=item splice ARRAY or EXPR,OFFSET
-
-=item splice ARRAY or EXPR
-
-=for Pod::Functions add or remove elements anywhere in an array
-
-Removes the elements designated by OFFSET and LENGTH from an array, and
-replaces them with the elements of LIST, if any. In list context,
-returns the elements removed from the array. In scalar context,
-returns the last element removed, or C<undef> if no elements are
-removed. The array grows or shrinks as necessary.
-If OFFSET is negative then it starts that far from the end of the array.
-If LENGTH is omitted, removes everything from OFFSET onward.
-If LENGTH is negative, removes the elements from OFFSET onward
-except for -LENGTH elements at the end of the array.
-If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is
-past the end of the array, Perl issues a warning, and splices at the
-end of the array.
-
-The following equivalences hold (assuming C<< $#a >= $i >> )
-
- push(@a,$x,$y) splice(@a,@a,0,$x,$y)
- pop(@a) splice(@a,-1)
- shift(@a) splice(@a,0,1)
- unshift(@a,$x,$y) splice(@a,0,0,$x,$y)
- $a[$i] = $y splice(@a,$i,1,$y)
-
-Example, assuming array lengths are passed before arrays:
-
- sub aeq { # compare two list values
- my(@a) = splice(@_,0,shift);
- my(@b) = splice(@_,0,shift);
- return 0 unless @a == @b; # same len?
- while (@a) {
- return 0 if pop(@a) ne pop(@b);
- }
- return 1;
- }
- if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
-
-Starting with Perl 5.14, C<splice> can take scalar EXPR, which must hold a
-reference to an unblessed array. The argument will be dereferenced
-automatically. This aspect of C<splice> is considered highly experimental.
-The exact behaviour may change in a future version of Perl.
-
-To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work I<only> on Perls of
-a recent vintage:
-
- use 5.014; # so push/pop/etc work on scalars (experimental)
-
-=item split /PATTERN/,EXPR,LIMIT
-X<split>
-
-=item split /PATTERN/,EXPR
-
-=item split /PATTERN/
-
-=item split
-
-=for Pod::Functions split up a string using a regexp delimiter
-
-Splits the string EXPR into a list of strings and returns the
-list in list context, or the size of the list in scalar context.
-
-If only PATTERN is given, EXPR defaults to C<$_>.
-
-Anything in EXPR that matches PATTERN is taken to be a separator
-that separates the EXPR into substrings (called "I<fields>") that
-do B<not> include the separator. Note that a separator may be
-longer than one character or even have no characters at all (the
-empty string, which is a zero-width match).
-
-The PATTERN need not be constant; an expression may be used
-to specify a pattern that varies at runtime.
-
-If PATTERN matches the empty string, the EXPR is split at the match
-position (between characters). As an example, the following:
-
- print join(':', split('b', 'abc')), "\n";
-
-uses the 'b' in 'abc' as a separator to produce the output 'a:c'.
-However, this:
-
- print join(':', split('', 'abc')), "\n";
-
-uses empty string matches as separators to produce the output
-'a:b:c'; thus, the empty string may be used to split EXPR into a
-list of its component characters.
-
-As a special case for C<split>, the empty pattern given in
-L<match operator|perlop/"m/PATTERN/msixpodualgc"> syntax (C<//>) specifically matches the empty string, which is contrary to its usual
-interpretation as the last successful match.
-
-If PATTERN is C</^/>, then it is treated as if it used the
-L<multiline modifier|perlreref/OPERATORS> (C</^/m>), since it
-isn't much use otherwise.
-
-As another special case, C<split> emulates the default behavior of the
-command line tool B<awk> when the PATTERN is either omitted or a I<literal
-string> composed of a single space character (such as S<C<' '>> or
-S<C<"\x20">>, but not e.g. S<C</ />>). In this case, any leading
-whitespace in EXPR is removed before splitting occurs, and the PATTERN is
-instead treated as if it were C</\s+/>; in particular, this means that
-I<any> contiguous whitespace (not just a single space character) is used as
-a separator. However, this special treatment can be avoided by specifying
-the pattern S<C</ />> instead of the string S<C<" ">>, thereby allowing
-only a single space character to be a separator.
-
-If omitted, PATTERN defaults to a single space, S<C<" ">>, triggering
-the previously described I<awk> emulation.
-
-If LIMIT is specified and positive, it represents the maximum number
-of fields into which the EXPR may be split; in other words, LIMIT is
-one greater than the maximum number of times EXPR may be split. Thus,
-the LIMIT value C<1> means that EXPR may be split a maximum of zero
-times, producing a maximum of one field (namely, the entire value of
-EXPR). For instance:
-
- print join(':', split(//, 'abc', 1)), "\n";
-
-produces the output 'abc', and this:
-
- print join(':', split(//, 'abc', 2)), "\n";
-
-produces the output 'a:bc', and each of these:
-
- print join(':', split(//, 'abc', 3)), "\n";
- print join(':', split(//, 'abc', 4)), "\n";
-
-produces the output 'a:b:c'.
-
-If LIMIT is negative, it is treated as if it were instead arbitrarily
-large; as many fields as possible are produced.
-
-If LIMIT is omitted (or, equivalently, zero), then it is usually
-treated as if it were instead negative but with the exception that
-trailing empty fields are stripped (empty leading fields are always
-preserved); if all fields are empty, then all fields are considered to
-be trailing (and are thus stripped in this case). Thus, the following:
-
- print join(':', split(',', 'a,b,c,,,')), "\n";
-
-produces the output 'a:b:c', but the following:
-
- print join(':', split(',', 'a,b,c,,,', -1)), "\n";
-
-produces the output 'a:b:c:::'.
-
-In time-critical applications, it is worthwhile to avoid splitting
-into more fields than necessary. Thus, when assigning to a list,
-if LIMIT is omitted (or zero), then LIMIT is treated as though it
-were one larger than the number of variables in the list; for the
-following, LIMIT is implicitly 4:
-
- ($login, $passwd, $remainder) = split(/:/);
-
-Note that splitting an EXPR that evaluates to the empty string always
-produces zero fields, regardless of the LIMIT specified.
-
-An empty leading field is produced when there is a positive-width
-match at the beginning of EXPR. For instance:
-
- print join(':', split(/ /, ' abc')), "\n";
-
-produces the output ':abc'. However, a zero-width match at the
-beginning of EXPR never produces an empty field, so that:
-
- print join(':', split(//, ' abc'));
-
-produces the output S<' :a:b:c'> (rather than S<': :a:b:c'>).
-
-An empty trailing field, on the other hand, is produced when there is a
-match at the end of EXPR, regardless of the length of the match
-(of course, unless a non-zero LIMIT is given explicitly, such fields are
-removed, as in the last example). Thus:
-
- print join(':', split(//, ' abc', -1)), "\n";
-
-produces the output S<' :a:b:c:'>.
-
-If the PATTERN contains
-L<capturing groups|perlretut/Grouping things and hierarchical matching>,
-then for each separator, an additional field is produced for each substring
-captured by a group (in the order in which the groups are specified,
-as per L<backreferences|perlretut/Backreferences>); if any group does not
-match, then it captures the C<undef> value instead of a substring. Also,
-note that any such additional field is produced whenever there is a
-separator (that is, whenever a split occurs), and such an additional field
-does B<not> count towards the LIMIT. Consider the following expressions
-evaluated in list context (each returned list is provided in the associated
-comment):
-
- split(/-|,/, "1-10,20", 3)
- # ('1', '10', '20')
-
- split(/(-|,)/, "1-10,20", 3)
- # ('1', '-', '10', ',', '20')
-
- split(/-|(,)/, "1-10,20", 3)
- # ('1', undef, '10', ',', '20')
-
- split(/(-)|,/, "1-10,20", 3)
- # ('1', '-', '10', undef, '20')
-
- split(/(-)|(,)/, "1-10,20", 3)
- # ('1', '-', undef, '10', undef, ',', '20')
-
-=item sprintf FORMAT, LIST
-X<sprintf>
-
-=for Pod::Functions formatted print into a string
-
-Returns a string formatted by the usual C<printf> conventions of the C
-library function C<sprintf>. See below for more details
-and see L<sprintf(3)> or L<printf(3)> on your system for an explanation of
-the general principles.
-
-For example:
-
- # Format number with up to 8 leading zeroes
- $result = sprintf("%08d", $number);
-
- # Round number to 3 digits after decimal point
- $rounded = sprintf("%.3f", $number);
-
-Perl does its own C<sprintf> formatting: it emulates the C
-function sprintf(3), but doesn't use it except for floating-point
-numbers, and even then only standard modifiers are allowed.
-Non-standard extensions in your local sprintf(3) are
-therefore unavailable from Perl.
-
-Unlike C<printf>, C<sprintf> does not do what you probably mean when you
-pass it an array as your first argument.
-The array is given scalar context,
-and instead of using the 0th element of the array as the format, Perl will
-use the count of elements in the array as the format, which is almost never
-useful.
-
-Perl's C<sprintf> permits the following universally-known conversions:
-
- %% a percent sign
- %c a character with the given number
- %s a string
- %d a signed integer, in decimal
- %u an unsigned integer, in decimal
- %o an unsigned integer, in octal
- %x an unsigned integer, in hexadecimal
- %e a floating-point number, in scientific notation
- %f a floating-point number, in fixed decimal notation
- %g a floating-point number, in %e or %f notation
-
-In addition, Perl permits the following widely-supported conversions:
-
- %X like %x, but using upper-case letters
- %E like %e, but using an upper-case "E"
- %G like %g, but with an upper-case "E" (if applicable)
- %b an unsigned integer, in binary
- %B like %b, but using an upper-case "B" with the # flag
- %p a pointer (outputs the Perl value's address in hexadecimal)
- %n special: *stores* the number of characters output so far
- into the next argument in the parameter list
-
-Finally, for backward (and we do mean "backward") compatibility, Perl
-permits these unnecessary but widely-supported conversions:
-
- %i a synonym for %d
- %D a synonym for %ld
- %U a synonym for %lu
- %O a synonym for %lo
- %F a synonym for %f
-
-Note that the number of exponent digits in the scientific notation produced
-by C<%e>, C<%E>, C<%g> and C<%G> for numbers with the modulus of the
-exponent less than 100 is system-dependent: it may be three or less
-(zero-padded as necessary). In other words, 1.23 times ten to the
-99th may be either "1.23e99" or "1.23e099".
-
-Between the C<%> and the format letter, you may specify several
-additional attributes controlling the interpretation of the format.
-In order, these are:
-
-=over 4
-
-=item format parameter index
-
-An explicit format parameter index, such as C<2$>. By default sprintf
-will format the next unused argument in the list, but this allows you
-to take the arguments out of order:
-
- printf '%2$d %1$d', 12, 34; # prints "34 12"
- printf '%3$d %d %1$d', 1, 2, 3; # prints "3 1 1"
-
-=item flags
-
-one or more of:
-
- space prefix non-negative number with a space
- + prefix non-negative number with a plus sign
- - left-justify within the field
- 0 use zeros, not spaces, to right-justify
- # ensure the leading "0" for any octal,
- prefix non-zero hexadecimal with "0x" or "0X",
- prefix non-zero binary with "0b" or "0B"
-
-For example:
-
- printf '<% d>', 12; # prints "< 12>"
- printf '<%+d>', 12; # prints "<+12>"
- printf '<%6s>', 12; # prints "< 12>"
- printf '<%-6s>', 12; # prints "<12 >"
- printf '<%06s>', 12; # prints "<000012>"
- printf '<%#o>', 12; # prints "<014>"
- printf '<%#x>', 12; # prints "<0xc>"
- printf '<%#X>', 12; # prints "<0XC>"
- printf '<%#b>', 12; # prints "<0b1100>"
- printf '<%#B>', 12; # prints "<0B1100>"
-
-When a space and a plus sign are given as the flags at once,
-a plus sign is used to prefix a positive number.
-
- printf '<%+ d>', 12; # prints "<+12>"
- printf '<% +d>', 12; # prints "<+12>"
-
-When the # flag and a precision are given in the %o conversion,
-the precision is incremented if it's necessary for the leading "0".
-
- printf '<%#.5o>', 012; # prints "<00012>"
- printf '<%#.5o>', 012345; # prints "<012345>"
- printf '<%#.0o>', 0; # prints "<0>"
-
-=item vector flag
-
-This flag tells Perl to interpret the supplied string as a vector of
-integers, one for each character in the string. Perl applies the format to
-each integer in turn, then joins the resulting strings with a separator (a
-dot C<.> by default). This can be useful for displaying ordinal values of
-characters in arbitrary strings:
-
- printf "%vd", "AB\x{100}"; # prints "65.66.256"
- printf "version is v%vd\n", $^V; # Perl's version
-
-Put an asterisk C<*> before the C<v> to override the string to
-use to separate the numbers:
-
- printf "address is %*vX\n", ":", $addr; # IPv6 address
- printf "bits are %0*v8b\n", " ", $bits; # random bitstring
-
-You can also explicitly specify the argument number to use for
-the join string using something like C<*2$v>; for example:
-
- printf '%*4$vX %*4$vX %*4$vX', @addr[1..3], ":"; # 3 IPv6 addresses
-
-=item (minimum) width
-
-Arguments are usually formatted to be only as wide as required to
-display the given value. You can override the width by putting
-a number here, or get the width from the next argument (with C<*>)
-or from a specified argument (e.g., with C<*2$>):
-
- printf "<%s>", "a"; # prints "<a>"
- printf "<%6s>", "a"; # prints "< a>"
- printf "<%*s>", 6, "a"; # prints "< a>"
- printf "<%*2$s>", "a", 6; # prints "< a>"
- printf "<%2s>", "long"; # prints "<long>" (does not truncate)
-
-If a field width obtained through C<*> is negative, it has the same
-effect as the C<-> flag: left-justification.
-
-=item precision, or maximum width
-X<precision>
-
-You can specify a precision (for numeric conversions) or a maximum
-width (for string conversions) by specifying a C<.> followed by a number.
-For floating-point formats except C<g> and C<G>, this specifies
-how many places right of the decimal point to show (the default being 6).
-For example:
-
- # these examples are subject to system-specific variation
- printf '<%f>', 1; # prints "<1.000000>"
- printf '<%.1f>', 1; # prints "<1.0>"
- printf '<%.0f>', 1; # prints "<1>"
- printf '<%e>', 10; # prints "<1.000000e+01>"
- printf '<%.1e>', 10; # prints "<1.0e+01>"
-
-For "g" and "G", this specifies the maximum number of digits to show,
-including those prior to the decimal point and those after it; for
-example:
-
- # These examples are subject to system-specific variation.
- printf '<%g>', 1; # prints "<1>"
- printf '<%.10g>', 1; # prints "<1>"
- printf '<%g>', 100; # prints "<100>"
- printf '<%.1g>', 100; # prints "<1e+02>"
- printf '<%.2g>', 100.01; # prints "<1e+02>"
- printf '<%.5g>', 100.01; # prints "<100.01>"
- printf '<%.4g>', 100.01; # prints "<100>"
-
-For integer conversions, specifying a precision implies that the
-output of the number itself should be zero-padded to this width,
-where the 0 flag is ignored:
-
- printf '<%.6d>', 1; # prints "<000001>"
- printf '<%+.6d>', 1; # prints "<+000001>"
- printf '<%-10.6d>', 1; # prints "<000001 >"
- printf '<%10.6d>', 1; # prints "< 000001>"
- printf '<%010.6d>', 1; # prints "< 000001>"
- printf '<%+10.6d>', 1; # prints "< +000001>"
-
- printf '<%.6x>', 1; # prints "<000001>"
- printf '<%#.6x>', 1; # prints "<0x000001>"
- printf '<%-10.6x>', 1; # prints "<000001 >"
- printf '<%10.6x>', 1; # prints "< 000001>"
- printf '<%010.6x>', 1; # prints "< 000001>"
- printf '<%#10.6x>', 1; # prints "< 0x000001>"
-
-For string conversions, specifying a precision truncates the string
-to fit the specified width:
-
- printf '<%.5s>', "truncated"; # prints "<trunc>"
- printf '<%10.5s>', "truncated"; # prints "< trunc>"
-
-You can also get the precision from the next argument using C<.*>:
-
- printf '<%.6x>', 1; # prints "<000001>"
- printf '<%.*x>', 6, 1; # prints "<000001>"
-
-If a precision obtained through C<*> is negative, it counts
-as having no precision at all.
-
- printf '<%.*s>', 7, "string"; # prints "<string>"
- printf '<%.*s>', 3, "string"; # prints "<str>"
- printf '<%.*s>', 0, "string"; # prints "<>"
- printf '<%.*s>', -1, "string"; # prints "<string>"
-
- printf '<%.*d>', 1, 0; # prints "<0>"
- printf '<%.*d>', 0, 0; # prints "<>"
- printf '<%.*d>', -1, 0; # prints "<0>"
-
-You cannot currently get the precision from a specified number,
-but it is intended that this will be possible in the future, for
-example using C<.*2$>:
-
- printf "<%.*2$x>", 1, 6; # INVALID, but in future will print "<000001>"
-
-=item size
-
-For numeric conversions, you can specify the size to interpret the
-number as using C<l>, C<h>, C<V>, C<q>, C<L>, or C<ll>. For integer
-conversions (C<d u o x X b i D U O>), numbers are usually assumed to be
-whatever the default integer size is on your platform (usually 32 or 64
-bits), but you can override this to use instead one of the standard C types,
-as supported by the compiler used to build Perl:
-
- hh interpret integer as C type "char" or "unsigned char"
- on Perl 5.14 or later
- h interpret integer as C type "short" or "unsigned short"
- j interpret integer as C type "intmax_t" on Perl 5.14
- or later, and only with a C99 compiler (unportable)
- l interpret integer as C type "long" or "unsigned long"
- q, L, or ll interpret integer as C type "long long", "unsigned long long",
- or "quad" (typically 64-bit integers)
- t interpret integer as C type "ptrdiff_t" on Perl 5.14 or later
- z interpret integer as C type "size_t" on Perl 5.14 or later
-
-As of 5.14, none of these raises an exception if they are not supported on
-your platform. However, if warnings are enabled, a warning of the
-C<printf> warning class is issued on an unsupported conversion flag.
-Should you instead prefer an exception, do this:
-
- use warnings FATAL => "printf";
-
-If you would like to know about a version dependency before you
-start running the program, put something like this at its top:
-
- use 5.014; # for hh/j/t/z/ printf modifiers
-
-You can find out whether your Perl supports quads via L<Config>:
-
- use Config;
- if ($Config{use64bitint} eq "define" || $Config{longsize} >= 8) {
- print "Nice quads!\n";
- }
-
-For floating-point conversions (C<e f g E F G>), numbers are usually assumed
-to be the default floating-point size on your platform (double or long double),
-but you can force "long double" with C<q>, C<L>, or C<ll> if your
-platform supports them. You can find out whether your Perl supports long
-doubles via L<Config>:
-
- use Config;
- print "long doubles\n" if $Config{d_longdbl} eq "define";
-
-You can find out whether Perl considers "long double" to be the default
-floating-point size to use on your platform via L<Config>:
-
- use Config;
- if ($Config{uselongdouble} eq "define") {
- print "long doubles by default\n";
- }
-
-It can also be that long doubles and doubles are the same thing:
-
- use Config;
- ($Config{doublesize} == $Config{longdblsize}) &&
- print "doubles are long doubles\n";
-
-The size specifier C<V> has no effect for Perl code, but is supported for
-compatibility with XS code. It means "use the standard size for a Perl
-integer or floating-point number", which is the default.
-
-=item order of arguments
-
-Normally, sprintf() takes the next unused argument as the value to
-format for each format specification. If the format specification
-uses C<*> to require additional arguments, these are consumed from
-the argument list in the order they appear in the format
-specification I<before> the value to format. Where an argument is
-specified by an explicit index, this does not affect the normal
-order for the arguments, even when the explicitly specified index
-would have been the next argument.
-
-So:
-
- printf "<%*.*s>", $a, $b, $c;
-
-uses C<$a> for the width, C<$b> for the precision, and C<$c>
-as the value to format; while:
-
- printf "<%*1$.*s>", $a, $b;
-
-would use C<$a> for the width and precision, and C<$b> as the
-value to format.
-
-Here are some more examples; be aware that when using an explicit
-index, the C<$> may need escaping:
-
- printf "%2\$d %d\n", 12, 34; # will print "34 12\n"
- printf "%2\$d %d %d\n", 12, 34; # will print "34 12 34\n"
- printf "%3\$d %d %d\n", 12, 34, 56; # will print "56 12 34\n"
- printf "%2\$*3\$d %d\n", 12, 34, 3; # will print " 34 12\n"
-
-=back
-
-If C<use locale> (including C<use locale 'not_characters'>) is in effect
-and POSIX::setlocale() has been called,
-the character used for the decimal separator in formatted floating-point
-numbers is affected by the LC_NUMERIC locale. See L<perllocale>
-and L<POSIX>.
-
-=item sqrt EXPR
-X<sqrt> X<root> X<square root>
-
-=item sqrt
-
-=for Pod::Functions square root function
-
-Return the positive square root of EXPR. If EXPR is omitted, uses
-C<$_>. Works only for non-negative operands unless you've
-loaded the C<Math::Complex> module.
-
- use Math::Complex;
- print sqrt(-4); # prints 2i
-
-=item srand EXPR
-X<srand> X<seed> X<randseed>
-
-=item srand
-
-=for Pod::Functions seed the random number generator
-
-Sets and returns the random number seed for the C<rand> operator.
-
-The point of the function is to "seed" the C<rand> function so that C<rand>
-can produce a different sequence each time you run your program. When
-called with a parameter, C<srand> uses that for the seed; otherwise it
-(semi-)randomly chooses a seed. In either case, starting with Perl 5.14,
-it returns the seed. To signal that your code will work I<only> on Perls
-of a recent vintage:
-
- use 5.014; # so srand returns the seed
-
-If C<srand()> is not called explicitly, it is called implicitly without a
-parameter at the first use of the C<rand> operator. However, this was not true
-of versions of Perl before 5.004, so if your script will run under older
-Perl versions, it should call C<srand>; otherwise most programs won't call
-C<srand()> at all.
-
-But there are a few situations in recent Perls where programs are likely to
-want to call C<srand>. One is for generating predictable results generally for
-testing or debugging. There, you use C<srand($seed)>, with the same C<$seed>
-each time. Another case is that you may want to call C<srand()>
-after a C<fork()> to avoid child processes sharing the same seed value as the
-parent (and consequently each other).
-
-Do B<not> call C<srand()> (i.e., without an argument) more than once per
-process. The internal state of the random number generator should
-contain more entropy than can be provided by any seed, so calling
-C<srand()> again actually I<loses> randomness.
-
-Most implementations of C<srand> take an integer and will silently
-truncate decimal numbers. This means C<srand(42)> will usually
-produce the same results as C<srand(42.1)>. To be safe, always pass
-C<srand> an integer.
-
-In versions of Perl prior to 5.004 the default seed was just the
-current C<time>. This isn't a particularly good seed, so many old
-programs supply their own seed value (often C<time ^ $$> or C<time ^
-($$ + ($$ << 15))>), but that isn't necessary any more.
-
-Frequently called programs (like CGI scripts) that simply use
-
- time ^ $$
-
-for a seed can fall prey to the mathematical property that
-
- a^b == (a+1)^(b+1)
-
-one-third of the time. So don't do that.
-
-A typical use of the returned seed is for a test program which has too many
-combinations to test comprehensively in the time available to it each run. It
-can test a random subset each time, and should there be a failure, log the seed
-used for that run so that it can later be used to reproduce the same results.
-
-B<C<rand()> is not cryptographically secure. You should not rely
-on it in security-sensitive situations.> As of this writing, a
-number of third-party CPAN modules offer random number generators
-intended by their authors to be cryptographically secure,
-including: L<Data::Entropy>, L<Crypt::Random>, L<Math::Random::Secure>,
-and L<Math::TrulyRandom>.
-
-=item stat FILEHANDLE
-X<stat> X<file, status> X<ctime>
-
-=item stat EXPR
-
-=item stat DIRHANDLE
-
-=item stat
-
-=for Pod::Functions get a file's status information
-
-Returns a 13-element list giving the status info for a file, either
-the file opened via FILEHANDLE or DIRHANDLE, or named by EXPR. If EXPR is
-omitted, it stats C<$_> (not C<_>!). Returns the empty list if C<stat> fails. Typically
-used as follows:
-
- ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
- $atime,$mtime,$ctime,$blksize,$blocks)
- = stat($filename);
-
-Not all fields are supported on all filesystem types. Here are the
-meanings of the fields:
-
- 0 dev device number of filesystem
- 1 ino inode number
- 2 mode file mode (type and permissions)
- 3 nlink number of (hard) links to the file
- 4 uid numeric user ID of file's owner
- 5 gid numeric group ID of file's owner
- 6 rdev the device identifier (special files only)
- 7 size total size of file, in bytes
- 8 atime last access time in seconds since the epoch
- 9 mtime last modify time in seconds since the epoch
- 10 ctime inode change time in seconds since the epoch (*)
- 11 blksize preferred block size for file system I/O
- 12 blocks actual number of blocks allocated
-
-(The epoch was at 00:00 January 1, 1970 GMT.)
-
-(*) Not all fields are supported on all filesystem types. Notably, the
-ctime field is non-portable. In particular, you cannot expect it to be a
-"creation time"; see L<perlport/"Files and Filesystems"> for details.
-
-If C<stat> is passed the special filehandle consisting of an underline, no
-stat is done, but the current contents of the stat structure from the
-last C<stat>, C<lstat>, or filetest are returned. Example:
-
- if (-x $file && (($d) = stat(_)) && $d < 0) {
- print "$file is executable NFS file\n";
- }
-
-(This works on machines only for which the device number is negative
-under NFS.)
-
-Because the mode contains both the file type and its permissions, you
-should mask off the file type portion and (s)printf using a C<"%o">
-if you want to see the real permissions.
-
- $mode = (stat($filename))[2];
- printf "Permissions are %04o\n", $mode & 07777;
-
-In scalar context, C<stat> returns a boolean value indicating success
-or failure, and, if successful, sets the information associated with
-the special filehandle C<_>.
-
-The L<File::stat> module provides a convenient, by-name access mechanism:
-
- use File::stat;
- $sb = stat($filename);
- printf "File is %s, size is %s, perm %04o, mtime %s\n",
- $filename, $sb->size, $sb->mode & 07777,
- scalar localtime $sb->mtime;
-
-You can import symbolic mode constants (C<S_IF*>) and functions
-(C<S_IS*>) from the Fcntl module:
-
- use Fcntl ':mode';
-
- $mode = (stat($filename))[2];
-
- $user_rwx = ($mode & S_IRWXU) >> 6;
- $group_read = ($mode & S_IRGRP) >> 3;
- $other_execute = $mode & S_IXOTH;
-
- printf "Permissions are %04o\n", S_IMODE($mode), "\n";
-
- $is_setuid = $mode & S_ISUID;
- $is_directory = S_ISDIR($mode);
-
-You could write the last two using the C<-u> and C<-d> operators.
-Commonly available C<S_IF*> constants are:
-
- # Permissions: read, write, execute, for user, group, others.
-
- S_IRWXU S_IRUSR S_IWUSR S_IXUSR
- S_IRWXG S_IRGRP S_IWGRP S_IXGRP
- S_IRWXO S_IROTH S_IWOTH S_IXOTH
-
- # Setuid/Setgid/Stickiness/SaveText.
- # Note that the exact meaning of these is system-dependent.
-
- S_ISUID S_ISGID S_ISVTX S_ISTXT
-
- # File types. Not all are necessarily available on
- # your system.
-
- S_IFREG S_IFDIR S_IFLNK S_IFBLK S_IFCHR
- S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
-
- # The following are compatibility aliases for S_IRUSR,
- # S_IWUSR, and S_IXUSR.
-
- S_IREAD S_IWRITE S_IEXEC
-
-and the C<S_IF*> functions are
-
- S_IMODE($mode) the part of $mode containing the permission
- bits and the setuid/setgid/sticky bits
-
- S_IFMT($mode) the part of $mode containing the file type
- which can be bit-anded with (for example)
- S_IFREG or with the following functions
-
- # The operators -f, -d, -l, -b, -c, -p, and -S.
-
- S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)
- S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)
-
- # No direct -X operator counterpart, but for the first one
- # the -g operator is often equivalent. The ENFMT stands for
- # record flocking enforcement, a platform-dependent feature.
-
- S_ISENFMT($mode) S_ISWHT($mode)
-
-See your native chmod(2) and stat(2) documentation for more details
-about the C<S_*> constants. To get status info for a symbolic link
-instead of the target file behind the link, use the C<lstat> function.
-
-Portability issues: L<perlport/stat>.
-
-=item state EXPR
-X<state>
-
-=item state TYPE EXPR
-
-=item state EXPR : ATTRS
-
-=item state TYPE EXPR : ATTRS
-
-=for Pod::Functions +state declare and assign a persistent lexical variable
-
-C<state> declares a lexically scoped variable, just like C<my>.
-However, those variables will never be reinitialized, contrary to
-lexical variables that are reinitialized each time their enclosing block
-is entered.
-See L<perlsub/"Persistent Private Variables"> for details.
-
-C<state> variables are enabled only when the C<use feature "state"> pragma
-is in effect, unless the keyword is written as C<CORE::state>.
-See also L<feature>.
-
-=item study SCALAR
-X<study>
-
-=item study
-
-=for Pod::Functions optimize input data for repeated searches
-
-Takes extra time to study SCALAR (C<$_> if unspecified) in anticipation of
-doing many pattern matches on the string before it is next modified.
-This may or may not save time, depending on the nature and number of
-patterns you are searching and the distribution of character
-frequencies in the string to be searched; you probably want to compare
-run times with and without it to see which is faster. Those loops
-that scan for many short constant strings (including the constant
-parts of more complex patterns) will benefit most.
-(The way C<study> works is this: a linked list of every
-character in the string to be searched is made, so we know, for
-example, where all the C<'k'> characters are. From each search string,
-the rarest character is selected, based on some static frequency tables
-constructed from some C programs and English text. Only those places
-that contain this "rarest" character are examined.)
-
-For example, here is a loop that inserts index producing entries
-before any line containing a certain pattern:
-
- while (<>) {
- study;
- print ".IX foo\n" if /\bfoo\b/;
- print ".IX bar\n" if /\bbar\b/;
- print ".IX blurfl\n" if /\bblurfl\b/;
- # ...
- print;
- }
-
-In searching for C</\bfoo\b/>, only locations in C<$_> that contain C<f>
-will be looked at, because C<f> is rarer than C<o>. In general, this is
-a big win except in pathological cases. The only question is whether
-it saves you more time than it took to build the linked list in the
-first place.
-
-Note that if you have to look for strings that you don't know till
-runtime, you can build an entire loop as a string and C<eval> that to
-avoid recompiling all your patterns all the time. Together with
-undefining C<$/> to input entire files as one record, this can be quite
-fast, often faster than specialized programs like fgrep(1). The following
-scans a list of files (C<@files>) for a list of words (C<@words>), and prints
-out the names of those files that contain a match:
-
- $search = 'while (<>) { study;';
- foreach $word (@words) {
- $search .= "++\$seen{\$ARGV} if /\\b$word\\b/;\n";
- }
- $search .= "}";
- @ARGV = @files;
- undef $/;
- eval $search; # this screams
- $/ = "\n"; # put back to normal input delimiter
- foreach $file (sort keys(%seen)) {
- print $file, "\n";
- }
-
-=item sub NAME BLOCK
-X<sub>
-
-=item sub NAME (PROTO) BLOCK
-
-=item sub NAME : ATTRS BLOCK
-
-=item sub NAME (PROTO) : ATTRS BLOCK
-
-=for Pod::Functions declare a subroutine, possibly anonymously
-
-This is subroutine definition, not a real function I<per se>. Without a
-BLOCK it's just a forward declaration. Without a NAME, it's an anonymous
-function declaration, so does return a value: the CODE ref of the closure
-just created.
-
-See L<perlsub> and L<perlref> for details about subroutines and
-references; see L<attributes> and L<Attribute::Handlers> for more
-information about attributes.
-
-=item __SUB__
-X<__SUB__>
-
-=for Pod::Functions +current_sub the current subroutine, or C<undef> if not in a subroutine
-
-A special token that returns the a reference to the current subroutine, or
-C<undef> outside of a subroutine.
-
-This token is only available under C<use v5.16> or the "current_sub"
-feature. See L<feature>.
-
-=item substr EXPR,OFFSET,LENGTH,REPLACEMENT
-X<substr> X<substring> X<mid> X<left> X<right>
-
-=item substr EXPR,OFFSET,LENGTH
-
-=item substr EXPR,OFFSET
-
-=for Pod::Functions get or alter a portion of a string
-
-Extracts a substring out of EXPR and returns it. First character is at
-offset zero. If OFFSET is negative, starts
-that far back from the end of the string. If LENGTH is omitted, returns
-everything through the end of the string. If LENGTH is negative, leaves that
-many characters off the end of the string.
-
- my $s = "The black cat climbed the green tree";
- my $color = substr $s, 4, 5; # black
- my $middle = substr $s, 4, -11; # black cat climbed the
- my $end = substr $s, 14; # climbed the green tree
- my $tail = substr $s, -4; # tree
- my $z = substr $s, -4, 2; # tr
-
-You can use the substr() function as an lvalue, in which case EXPR
-must itself be an lvalue. If you assign something shorter than LENGTH,
-the string will shrink, and if you assign something longer than LENGTH,
-the string will grow to accommodate it. To keep the string the same
-length, you may need to pad or chop your value using C<sprintf>.
-
-If OFFSET and LENGTH specify a substring that is partly outside the
-string, only the part within the string is returned. If the substring
-is beyond either end of the string, substr() returns the undefined
-value and produces a warning. When used as an lvalue, specifying a
-substring that is entirely outside the string raises an exception.
-Here's an example showing the behavior for boundary cases:
-
- my $name = 'fred';
- substr($name, 4) = 'dy'; # $name is now 'freddy'
- my $null = substr $name, 6, 2; # returns "" (no warning)
- my $oops = substr $name, 7; # returns undef, with warning
- substr($name, 7) = 'gap'; # raises an exception
-
-An alternative to using substr() as an lvalue is to specify the
-replacement string as the 4th argument. This allows you to replace
-parts of the EXPR and return what was there before in one operation,
-just as you can with splice().
-
- my $s = "The black cat climbed the green tree";
- my $z = substr $s, 14, 7, "jumped from"; # climbed
- # $s is now "The black cat jumped from the green tree"
-
-Note that the lvalue returned by the three-argument version of substr() acts as
-a 'magic bullet'; each time it is assigned to, it remembers which part
-of the original string is being modified; for example:
-
- $x = '1234';
- for (substr($x,1,2)) {
- $_ = 'a'; print $x,"\n"; # prints 1a4
- $_ = 'xyz'; print $x,"\n"; # prints 1xyz4
- $x = '56789';
- $_ = 'pq'; print $x,"\n"; # prints 5pq9
- }
-
-With negative offsets, it remembers its position from the end of the string
-when the target string is modified:
-
- $x = '1234';
- for (substr($x, -3, 2)) {
- $_ = 'a'; print $x,"\n"; # prints 1a4, as above
- $x = 'abcdefg';
- print $_,"\n"; # prints f
- }
-
-Prior to Perl version 5.10, the result of using an lvalue multiple times was
-unspecified. Prior to 5.16, the result with negative offsets was
-unspecified.
-
-=item symlink OLDFILE,NEWFILE
-X<symlink> X<link> X<symbolic link> X<link, symbolic>
-
-=for Pod::Functions create a symbolic link to a file
-
-Creates a new filename symbolically linked to the old filename.
-Returns C<1> for success, C<0> otherwise. On systems that don't support
-symbolic links, raises an exception. To check for that,
-use eval:
-
- $symlink_exists = eval { symlink("",""); 1 };
-
-Portability issues: L<perlport/symlink>.
-
-=item syscall NUMBER, LIST
-X<syscall> X<system call>
-
-=for Pod::Functions execute an arbitrary system call
-
-Calls the system call specified as the first element of the list,
-passing the remaining elements as arguments to the system call. If
-unimplemented, raises an exception. The arguments are interpreted
-as follows: if a given argument is numeric, the argument is passed as
-an int. If not, the pointer to the string value is passed. You are
-responsible to make sure a string is pre-extended long enough to
-receive any result that might be written into a string. You can't use a
-string literal (or other read-only string) as an argument to C<syscall>
-because Perl has to assume that any string pointer might be written
-through. If your
-integer arguments are not literals and have never been interpreted in a
-numeric context, you may need to add C<0> to them to force them to look
-like numbers. This emulates the C<syswrite> function (or vice versa):
-
- require 'syscall.ph'; # may need to run h2ph
- $s = "hi there\n";
- syscall(&SYS_write, fileno(STDOUT), $s, length $s);
-
-Note that Perl supports passing of up to only 14 arguments to your syscall,
-which in practice should (usually) suffice.
-
-Syscall returns whatever value returned by the system call it calls.
-If the system call fails, C<syscall> returns C<-1> and sets C<$!> (errno).
-Note that some system calls I<can> legitimately return C<-1>. The proper
-way to handle such calls is to assign C<$!=0> before the call, then
-check the value of C<$!> if C<syscall> returns C<-1>.
-
-There's a problem with C<syscall(&SYS_pipe)>: it returns the file
-number of the read end of the pipe it creates, but there is no way
-to retrieve the file number of the other end. You can avoid this
-problem by using C<pipe> instead.
-
-Portability issues: L<perlport/syscall>.
-
-=item sysopen FILEHANDLE,FILENAME,MODE
-X<sysopen>
-
-=item sysopen FILEHANDLE,FILENAME,MODE,PERMS
-
-=for Pod::Functions +5.002 open a file, pipe, or descriptor
-
-Opens the file whose filename is given by FILENAME, and associates it with
-FILEHANDLE. If FILEHANDLE is an expression, its value is used as the real
-filehandle wanted; an undefined scalar will be suitably autovivified. This
-function calls the underlying operating system's I<open>(2) function with the
-parameters FILENAME, MODE, and PERMS.
-
-The possible values and flag bits of the MODE parameter are
-system-dependent; they are available via the standard module C<Fcntl>. See
-the documentation of your operating system's I<open>(2) syscall to see
-which values and flag bits are available. You may combine several flags
-using the C<|>-operator.
-
-Some of the most common values are C<O_RDONLY> for opening the file in
-read-only mode, C<O_WRONLY> for opening the file in write-only mode,
-and C<O_RDWR> for opening the file in read-write mode.
-X<O_RDONLY> X<O_RDWR> X<O_WRONLY>
-
-For historical reasons, some values work on almost every system
-supported by Perl: 0 means read-only, 1 means write-only, and 2
-means read/write. We know that these values do I<not> work under
-OS/390 & VM/ESA Unix and on the Macintosh; you probably don't want to
-use them in new code.
-
-If the file named by FILENAME does not exist and the C<open> call creates
-it (typically because MODE includes the C<O_CREAT> flag), then the value of
-PERMS specifies the permissions of the newly created file. If you omit
-the PERMS argument to C<sysopen>, Perl uses the octal value C<0666>.
-These permission values need to be in octal, and are modified by your
-process's current C<umask>.
-X<O_CREAT>
-
-In many systems the C<O_EXCL> flag is available for opening files in
-exclusive mode. This is B<not> locking: exclusiveness means here that
-if the file already exists, sysopen() fails. C<O_EXCL> may not work
-on network filesystems, and has no effect unless the C<O_CREAT> flag
-is set as well. Setting C<O_CREAT|O_EXCL> prevents the file from
-being opened if it is a symbolic link. It does not protect against
-symbolic links in the file's path.
-X<O_EXCL>
-
-Sometimes you may want to truncate an already-existing file. This
-can be done using the C<O_TRUNC> flag. The behavior of
-C<O_TRUNC> with C<O_RDONLY> is undefined.
-X<O_TRUNC>
-
-You should seldom if ever use C<0644> as argument to C<sysopen>, because
-that takes away the user's option to have a more permissive umask.
-Better to omit it. See the perlfunc(1) entry on C<umask> for more
-on this.
-
-Note that C<sysopen> depends on the fdopen() C library function.
-On many Unix systems, fdopen() is known to fail when file descriptors
-exceed a certain value, typically 255. If you need more file
-descriptors than that, consider rebuilding Perl to use the C<sfio>
-library, or perhaps using the POSIX::open() function.
-
-See L<perlopentut> for a kinder, gentler explanation of opening files.
-
-Portability issues: L<perlport/sysopen>.
-
-=item sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
-X<sysread>
-
-=item sysread FILEHANDLE,SCALAR,LENGTH
-
-=for Pod::Functions fixed-length unbuffered input from a filehandle
-
-Attempts to read LENGTH bytes of data into variable SCALAR from the
-specified FILEHANDLE, using the read(2). It bypasses
-buffered IO, so mixing this with other kinds of reads, C<print>,
-C<write>, C<seek>, C<tell>, or C<eof> can cause confusion because the
-perlio or stdio layers usually buffers data. Returns the number of
-bytes actually read, C<0> at end of file, or undef if there was an
-error (in the latter case C<$!> is also set). SCALAR will be grown or
-shrunk so that the last byte actually read is the last byte of the
-scalar after the read.
-
-An OFFSET may be specified to place the read data at some place in the
-string other than the beginning. A negative OFFSET specifies
-placement at that many characters counting backwards from the end of
-the string. A positive OFFSET greater than the length of SCALAR
-results in the string being padded to the required size with C<"\0">
-bytes before the result of the read is appended.
-
-There is no syseof() function, which is ok, since eof() doesn't work
-well on device files (like ttys) anyway. Use sysread() and check
-for a return value for 0 to decide whether you're done.
-
-Note that if the filehandle has been marked as C<:utf8> Unicode
-characters are read instead of bytes (the LENGTH, OFFSET, and the
-return value of sysread() are in Unicode characters).
-The C<:encoding(...)> layer implicitly introduces the C<:utf8> layer.
-See L</binmode>, L</open>, and the C<open> pragma, L<open>.
-
-=item sysseek FILEHANDLE,POSITION,WHENCE
-X<sysseek> X<lseek>
-
-=for Pod::Functions +5.004 position I/O pointer on handle used with sysread and syswrite
-
-Sets FILEHANDLE's system position in bytes using lseek(2). FILEHANDLE may
-be an expression whose value gives the name of the filehandle. The values
-for WHENCE are C<0> to set the new position to POSITION; C<1> to set the it
-to the current position plus POSITION; and C<2> to set it to EOF plus
-POSITION, typically negative.
-
-Note the I<in bytes>: even if the filehandle has been set to operate
-on characters (for example by using the C<:encoding(utf8)> I/O layer),
-tell() will return byte offsets, not character offsets (because
-implementing that would render sysseek() unacceptably slow).
-
-sysseek() bypasses normal buffered IO, so mixing it with reads other
-than C<sysread> (for example C<< <> >> or read()) C<print>, C<write>,
-C<seek>, C<tell>, or C<eof> may cause confusion.
-
-For WHENCE, you may also use the constants C<SEEK_SET>, C<SEEK_CUR>,
-and C<SEEK_END> (start of the file, current position, end of the file)
-from the Fcntl module. Use of the constants is also more portable
-than relying on 0, 1, and 2. For example to define a "systell" function:
-
- use Fcntl 'SEEK_CUR';
- sub systell { sysseek($_[0], 0, SEEK_CUR) }
-
-Returns the new position, or the undefined value on failure. A position
-of zero is returned as the string C<"0 but true">; thus C<sysseek> returns
-true on success and false on failure, yet you can still easily determine
-the new position.
-
-=item system LIST
-X<system> X<shell>
-
-=item system PROGRAM LIST
-
-=for Pod::Functions run a separate program
-
-Does exactly the same thing as C<exec LIST>, except that a fork is
-done first and the parent process waits for the child process to
-exit. Note that argument processing varies depending on the
-number of arguments. If there is more than one argument in LIST,
-or if LIST is an array with more than one value, starts the program
-given by the first element of the list with arguments given by the
-rest of the list. If there is only one scalar argument, the argument
-is checked for shell metacharacters, and if there are any, the
-entire argument is passed to the system's command shell for parsing
-(this is C</bin/sh -c> on Unix platforms, but varies on other
-platforms). If there are no shell metacharacters in the argument,
-it is split into words and passed directly to C<execvp>, which is
-more efficient.
-
-Beginning with v5.6.0, Perl will attempt to flush all files opened for
-output before any operation that may do a fork, but this may not be
-supported on some platforms (see L<perlport>). To be safe, you may need
-to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
-of C<IO::Handle> on any open handles.
-
-The return value is the exit status of the program as returned by the
-C<wait> call. To get the actual exit value, shift right by eight (see
-below). See also L</exec>. This is I<not> what you want to use to capture
-the output from a command; for that you should use merely backticks or
-C<qx//>, as described in L<perlop/"`STRING`">. Return value of -1
-indicates a failure to start the program or an error of the wait(2) system
-call (inspect $! for the reason).
-
-If you'd like to make C<system> (and many other bits of Perl) die on error,
-have a look at the L<autodie> pragma.
-
-Like C<exec>, C<system> allows you to lie to a program about its name if
-you use the C<system PROGRAM LIST> syntax. Again, see L</exec>.
-
-Since C<SIGINT> and C<SIGQUIT> are ignored during the execution of
-C<system>, if you expect your program to terminate on receipt of these
-signals you will need to arrange to do so yourself based on the return
-value.
-
- @args = ("command", "arg1", "arg2");
- system(@args) == 0
- or die "system @args failed: $?"
-
-If you'd like to manually inspect C<system>'s failure, you can check all
-possible failure modes by inspecting C<$?> like this:
-
- if ($? == -1) {
- print "failed to execute: $!\n";
- }
- elsif ($? & 127) {
- printf "child died with signal %d, %s coredump\n",
- ($? & 127), ($? & 128) ? 'with' : 'without';
- }
- else {
- printf "child exited with value %d\n", $? >> 8;
- }
-
-Alternatively, you may inspect the value of C<${^CHILD_ERROR_NATIVE}>
-with the C<W*()> calls from the POSIX module.
-
-When C<system>'s arguments are executed indirectly by the shell,
-results and return codes are subject to its quirks.
-See L<perlop/"`STRING`"> and L</exec> for details.
-
-Since C<system> does a C<fork> and C<wait> it may affect a C<SIGCHLD>
-handler. See L<perlipc> for details.
-
-Portability issues: L<perlport/system>.
-
-=item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
-X<syswrite>
-
-=item syswrite FILEHANDLE,SCALAR,LENGTH
-
-=item syswrite FILEHANDLE,SCALAR
-
-=for Pod::Functions fixed-length unbuffered output to a filehandle
-
-Attempts to write LENGTH bytes of data from variable SCALAR to the
-specified FILEHANDLE, using write(2). If LENGTH is
-not specified, writes whole SCALAR. It bypasses buffered IO, so
-mixing this with reads (other than C<sysread())>, C<print>, C<write>,
-C<seek>, C<tell>, or C<eof> may cause confusion because the perlio and
-stdio layers usually buffer data. Returns the number of bytes
-actually written, or C<undef> if there was an error (in this case the
-errno variable C<$!> is also set). If the LENGTH is greater than the
-data available in the SCALAR after the OFFSET, only as much data as is
-available will be written.
-
-An OFFSET may be specified to write the data from some part of the
-string other than the beginning. A negative OFFSET specifies writing
-that many characters counting backwards from the end of the string.
-If SCALAR is of length zero, you can only use an OFFSET of 0.
-
-B<WARNING>: If the filehandle is marked C<:utf8>, Unicode characters
-encoded in UTF-8 are written instead of bytes, and the LENGTH, OFFSET, and
-return value of syswrite() are in (UTF8-encoded Unicode) characters.
-The C<:encoding(...)> layer implicitly introduces the C<:utf8> layer.
-Alternately, if the handle is not marked with an encoding but you
-attempt to write characters with code points over 255, raises an exception.
-See L</binmode>, L</open>, and the C<open> pragma, L<open>.
-
-=item tell FILEHANDLE
-X<tell>
-
-=item tell
-
-=for Pod::Functions get current seekpointer on a filehandle
-
-Returns the current position I<in bytes> for FILEHANDLE, or -1 on
-error. FILEHANDLE may be an expression whose value gives the name of
-the actual filehandle. If FILEHANDLE is omitted, assumes the file
-last read.
-
-Note the I<in bytes>: even if the filehandle has been set to
-operate on characters (for example by using the C<:encoding(utf8)> open
-layer), tell() will return byte offsets, not character offsets (because
-that would render seek() and tell() rather slow).
-
-The return value of tell() for the standard streams like the STDIN
-depends on the operating system: it may return -1 or something else.
-tell() on pipes, fifos, and sockets usually returns -1.
-
-There is no C<systell> function. Use C<sysseek(FH, 0, 1)> for that.
-
-Do not use tell() (or other buffered I/O operations) on a filehandle
-that has been manipulated by sysread(), syswrite(), or sysseek().
-Those functions ignore the buffering, while tell() does not.
-
-=item telldir DIRHANDLE
-X<telldir>
-
-=for Pod::Functions get current seekpointer on a directory handle
-
-Returns the current position of the C<readdir> routines on DIRHANDLE.
-Value may be given to C<seekdir> to access a particular location in a
-directory. C<telldir> has the same caveats about possible directory
-compaction as the corresponding system library routine.
-
-=item tie VARIABLE,CLASSNAME,LIST
-X<tie>
-
-=for Pod::Functions +5.002 bind a variable to an object class
-
-This function binds a variable to a package class that will provide the
-implementation for the variable. VARIABLE is the name of the variable
-to be enchanted. CLASSNAME is the name of a class implementing objects
-of correct type. Any additional arguments are passed to the C<new>
-method of the class (meaning C<TIESCALAR>, C<TIEHANDLE>, C<TIEARRAY>,
-or C<TIEHASH>). Typically these are arguments such as might be passed
-to the C<dbm_open()> function of C. The object returned by the C<new>
-method is also returned by the C<tie> function, which would be useful
-if you want to access other methods in CLASSNAME.
-
-Note that functions such as C<keys> and C<values> may return huge lists
-when used on large objects, like DBM files. You may prefer to use the
-C<each> function to iterate over such. Example:
-
- # print out history file offsets
- use NDBM_File;
- tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
- while (($key,$val) = each %HIST) {
- print $key, ' = ', unpack('L',$val), "\n";
- }
- untie(%HIST);
-
-A class implementing a hash should have the following methods:
-
- TIEHASH classname, LIST
- FETCH this, key
- STORE this, key, value
- DELETE this, key
- CLEAR this
- EXISTS this, key
- FIRSTKEY this
- NEXTKEY this, lastkey
- SCALAR this
- DESTROY this
- UNTIE this
-
-A class implementing an ordinary array should have the following methods:
-
- TIEARRAY classname, LIST
- FETCH this, key
- STORE this, key, value
- FETCHSIZE this
- STORESIZE this, count
- CLEAR this
- PUSH this, LIST
- POP this
- SHIFT this
- UNSHIFT this, LIST
- SPLICE this, offset, length, LIST
- EXTEND this, count
- DESTROY this
- UNTIE this
-
-A class implementing a filehandle should have the following methods:
-
- TIEHANDLE classname, LIST
- READ this, scalar, length, offset
- READLINE this
- GETC this
- WRITE this, scalar, length, offset
- PRINT this, LIST
- PRINTF this, format, LIST
- BINMODE this
- EOF this
- FILENO this
- SEEK this, position, whence
- TELL this
- OPEN this, mode, LIST
- CLOSE this
- DESTROY this
- UNTIE this
-
-A class implementing a scalar should have the following methods:
-
- TIESCALAR classname, LIST
- FETCH this,
- STORE this, value
- DESTROY this
- UNTIE this
-
-Not all methods indicated above need be implemented. See L<perltie>,
-L<Tie::Hash>, L<Tie::Array>, L<Tie::Scalar>, and L<Tie::Handle>.
-
-Unlike C<dbmopen>, the C<tie> function will not C<use> or C<require> a module
-for you; you need to do that explicitly yourself. See L<DB_File>
-or the F<Config> module for interesting C<tie> implementations.
-
-For further details see L<perltie>, L<"tied VARIABLE">.
-
-=item tied VARIABLE
-X<tied>
-
-=for Pod::Functions get a reference to the object underlying a tied variable
-
-Returns a reference to the object underlying VARIABLE (the same value
-that was originally returned by the C<tie> call that bound the variable
-to a package.) Returns the undefined value if VARIABLE isn't tied to a
-package.
-
-=item time
-X<time> X<epoch>
-
-=for Pod::Functions return number of seconds since 1970
-
-Returns the number of non-leap seconds since whatever time the system
-considers to be the epoch, suitable for feeding to C<gmtime> and
-C<localtime>. On most systems the epoch is 00:00:00 UTC, January 1, 1970;
-a prominent exception being Mac OS Classic which uses 00:00:00, January 1,
-1904 in the current local time zone for its epoch.
-
-For measuring time in better granularity than one second, use the
-L<Time::HiRes> module from Perl 5.8 onwards (or from CPAN before then), or,
-if you have gettimeofday(2), you may be able to use the C<syscall>
-interface of Perl. See L<perlfaq8> for details.
-
-For date and time processing look at the many related modules on CPAN.
-For a comprehensive date and time representation look at the
-L<DateTime> module.
-
-=item times
-X<times>
-
-=for Pod::Functions return elapsed time for self and child processes
-
-Returns a four-element list giving the user and system times in
-seconds for this process and any exited children of this process.
-
- ($user,$system,$cuser,$csystem) = times;
-
-In scalar context, C<times> returns C<$user>.
-
-Children's times are only included for terminated children.
-
-Portability issues: L<perlport/times>.
-
-=item tr///
-
-=for Pod::Functions transliterate a string
-
-The transliteration operator. Same as C<y///>. See
-L<perlop/"Quote and Quote-like Operators">.
-
-=item truncate FILEHANDLE,LENGTH
-X<truncate>
-
-=item truncate EXPR,LENGTH
-
-=for Pod::Functions shorten a file
-
-Truncates the file opened on FILEHANDLE, or named by EXPR, to the
-specified length. Raises an exception if truncate isn't implemented
-on your system. Returns true if successful, C<undef> on error.
-
-The behavior is undefined if LENGTH is greater than the length of the
-file.
-
-The position in the file of FILEHANDLE is left unchanged. You may want to
-call L<seek|/"seek FILEHANDLE,POSITION,WHENCE"> before writing to the file.
-
-Portability issues: L<perlport/truncate>.
-
-=item uc EXPR
-X<uc> X<uppercase> X<toupper>
-
-=item uc
-
-=for Pod::Functions return upper-case version of a string
-
-Returns an uppercased version of EXPR. This is the internal function
-implementing the C<\U> escape in double-quoted strings.
-It does not attempt to do titlecase mapping on initial letters. See
-L</ucfirst> for that.
-
-If EXPR is omitted, uses C<$_>.
-
-This function behaves the same way under various pragma, such as in a locale,
-as L</lc> does.
-
-=item ucfirst EXPR
-X<ucfirst> X<uppercase>
-
-=item ucfirst
-
-=for Pod::Functions return a string with just the next letter in upper case
-
-Returns the value of EXPR with the first character in uppercase
-(titlecase in Unicode). This is the internal function implementing
-the C<\u> escape in double-quoted strings.
-
-If EXPR is omitted, uses C<$_>.
-
-This function behaves the same way under various pragma, such as in a locale,
-as L</lc> does.
-
-=item umask EXPR
-X<umask>
-
-=item umask
-
-=for Pod::Functions set file creation mode mask
-
-Sets the umask for the process to EXPR and returns the previous value.
-If EXPR is omitted, merely returns the current umask.
-
-The Unix permission C<rwxr-x---> is represented as three sets of three
-bits, or three octal digits: C<0750> (the leading 0 indicates octal
-and isn't one of the digits). The C<umask> value is such a number
-representing disabled permissions bits. The permission (or "mode")
-values you pass C<mkdir> or C<sysopen> are modified by your umask, so
-even if you tell C<sysopen> to create a file with permissions C<0777>,
-if your umask is C<0022>, then the file will actually be created with
-permissions C<0755>. If your C<umask> were C<0027> (group can't
-write; others can't read, write, or execute), then passing
-C<sysopen> C<0666> would create a file with mode C<0640> (because
-C<0666 &~ 027> is C<0640>).
-
-Here's some advice: supply a creation mode of C<0666> for regular
-files (in C<sysopen>) and one of C<0777> for directories (in
-C<mkdir>) and executable files. This gives users the freedom of
-choice: if they want protected files, they might choose process umasks
-of C<022>, C<027>, or even the particularly antisocial mask of C<077>.
-Programs should rarely if ever make policy decisions better left to
-the user. The exception to this is when writing files that should be
-kept private: mail files, web browser cookies, I<.rhosts> files, and
-so on.
-
-If umask(2) is not implemented on your system and you are trying to
-restrict access for I<yourself> (i.e., C<< (EXPR & 0700) > 0 >>),
-raises an exception. If umask(2) is not implemented and you are
-not trying to restrict access for yourself, returns C<undef>.
-
-Remember that a umask is a number, usually given in octal; it is I<not> a
-string of octal digits. See also L</oct>, if all you have is a string.
-
-Portability issues: L<perlport/umask>.
-
-=item undef EXPR
-X<undef> X<undefine>
-
-=item undef
-
-=for Pod::Functions remove a variable or function definition
-
-Undefines the value of EXPR, which must be an lvalue. Use only on a
-scalar value, an array (using C<@>), a hash (using C<%>), a subroutine
-(using C<&>), or a typeglob (using C<*>). Saying C<undef $hash{$key}>
-will probably not do what you expect on most predefined variables or
-DBM list values, so don't do that; see L</delete>. Always returns the
-undefined value. You can omit the EXPR, in which case nothing is
-undefined, but you still get an undefined value that you could, for
-instance, return from a subroutine, assign to a variable, or pass as a
-parameter. Examples:
-
- undef $foo;
- undef $bar{'blurfl'}; # Compare to: delete $bar{'blurfl'};
- undef @ary;
- undef %hash;
- undef &mysub;
- undef *xyz; # destroys $xyz, @xyz, %xyz, &xyz, etc.
- return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it;
- select undef, undef, undef, 0.25;
- ($a, $b, undef, $c) = &foo; # Ignore third value returned
-
-Note that this is a unary operator, not a list operator.
-
-=item unlink LIST
-X<unlink> X<delete> X<remove> X<rm> X<del>
-
-=item unlink
-
-=for Pod::Functions remove one link to a file
-
-Deletes a list of files. On success, it returns the number of files
-it successfully deleted. On failure, it returns false and sets C<$!>
-(errno):
-
- my $unlinked = unlink 'a', 'b', 'c';
- unlink @goners;
- unlink glob "*.bak";
-
-On error, C<unlink> will not tell you which files it could not remove.
-If you want to know which files you could not remove, try them one
-at a time:
-
- foreach my $file ( @goners ) {
- unlink $file or warn "Could not unlink $file: $!";
- }
-
-Note: C<unlink> will not attempt to delete directories unless you are
-superuser and the B<-U> flag is supplied to Perl. Even if these
-conditions are met, be warned that unlinking a directory can inflict
-damage on your filesystem. Finally, using C<unlink> on directories is
-not supported on many operating systems. Use C<rmdir> instead.
-
-If LIST is omitted, C<unlink> uses C<$_>.
-
-=item unpack TEMPLATE,EXPR
-X<unpack>
-
-=item unpack TEMPLATE
-
-=for Pod::Functions convert binary structure into normal perl variables
-
-C<unpack> does the reverse of C<pack>: it takes a string
-and expands it out into a list of values.
-(In scalar context, it returns merely the first value produced.)
-
-If EXPR is omitted, unpacks the C<$_> string.
-See L<perlpacktut> for an introduction to this function.
-
-The string is broken into chunks described by the TEMPLATE. Each chunk
-is converted separately to a value. Typically, either the string is a result
-of C<pack>, or the characters of the string represent a C structure of some
-kind.
-
-The TEMPLATE has the same format as in the C<pack> function.
-Here's a subroutine that does substring:
-
- sub substr {
- my($what,$where,$howmuch) = @_;
- unpack("x$where a$howmuch", $what);
- }
-
-and then there's
-
- sub ordinal { unpack("W",$_[0]); } # same as ord()
-
-In addition to fields allowed in pack(), you may prefix a field with
-a %<number> to indicate that
-you want a <number>-bit checksum of the items instead of the items
-themselves. Default is a 16-bit checksum. Checksum is calculated by
-summing numeric values of expanded values (for string fields the sum of
-C<ord($char)> is taken; for bit fields the sum of zeroes and ones).
-
-For example, the following
-computes the same number as the System V sum program:
-
- $checksum = do {
- local $/; # slurp!
- unpack("%32W*",<>) % 65535;
- };
-
-The following efficiently counts the number of set bits in a bit vector:
-
- $setbits = unpack("%32b*", $selectmask);
-
-The C<p> and C<P> formats should be used with care. Since Perl
-has no way of checking whether the value passed to C<unpack()>
-corresponds to a valid memory location, passing a pointer value that's
-not known to be valid is likely to have disastrous consequences.
-
-If there are more pack codes or if the repeat count of a field or a group
-is larger than what the remainder of the input string allows, the result
-is not well defined: the repeat count may be decreased, or
-C<unpack()> may produce empty strings or zeros, or it may raise an exception.
-If the input string is longer than one described by the TEMPLATE,
-the remainder of that input string is ignored.
-
-See L</pack> for more examples and notes.
-
-=item unshift ARRAY,LIST
-X<unshift>
-
-=item unshift EXPR,LIST
-
-=for Pod::Functions prepend more elements to the beginning of a list
-
-Does the opposite of a C<shift>. Or the opposite of a C<push>,
-depending on how you look at it. Prepends list to the front of the
-array and returns the new number of elements in the array.
-
- unshift(@ARGV, '-e') unless $ARGV[0] =~ /^-/;
-
-Note the LIST is prepended whole, not one element at a time, so the
-prepended elements stay in the same order. Use C<reverse> to do the
-reverse.
-
-Starting with Perl 5.14, C<unshift> can take a scalar EXPR, which must hold
-a reference to an unblessed array. The argument will be dereferenced
-automatically. This aspect of C<unshift> is considered highly
-experimental. The exact behaviour may change in a future version of Perl.
-
-To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work I<only> on Perls of
-a recent vintage:
-
- use 5.014; # so push/pop/etc work on scalars (experimental)
-
-=item untie VARIABLE
-X<untie>
-
-=for Pod::Functions break a tie binding to a variable
-
-Breaks the binding between a variable and a package.
-(See L<tie|/tie VARIABLE,CLASSNAME,LIST>.)
-Has no effect if the variable is not tied.
-
-=item use Module VERSION LIST
-X<use> X<module> X<import>
-
-=item use Module VERSION
-
-=item use Module LIST
-
-=item use Module
-
-=item use VERSION
-
-=for Pod::Functions load in a module at compile time and import its namespace
-
-Imports some semantics into the current package from the named module,
-generally by aliasing certain subroutine or variable names into your
-package. It is exactly equivalent to
-
- BEGIN { require Module; Module->import( LIST ); }
-
-except that Module I<must> be a bareword.
-The importation can be made conditional; see L<if>.
-
-In the peculiar C<use VERSION> form, VERSION may be either a positive
-decimal fraction such as 5.006, which will be compared to C<$]>, or a v-string
-of the form v5.6.1, which will be compared to C<$^V> (aka $PERL_VERSION). An
-exception is raised if VERSION is greater than the version of the
-current Perl interpreter; Perl will not attempt to parse the rest of the
-file. Compare with L</require>, which can do a similar check at run time.
-Symmetrically, C<no VERSION> allows you to specify that you want a version
-of Perl older than the specified one.
-
-Specifying VERSION as a literal of the form v5.6.1 should generally be
-avoided, because it leads to misleading error messages under earlier
-versions of Perl (that is, prior to 5.6.0) that do not support this
-syntax. The equivalent numeric version should be used instead.
-
- use v5.6.1; # compile time version check
- use 5.6.1; # ditto
- use 5.006_001; # ditto; preferred for backwards compatibility
-
-This is often useful if you need to check the current Perl version before
-C<use>ing library modules that won't work with older versions of Perl.
-(We try not to do this more than we have to.)
-
-C<use VERSION> also enables all features available in the requested
-version as defined by the C<feature> pragma, disabling any features
-not in the requested version's feature bundle. See L<feature>.
-Similarly, if the specified Perl version is greater than or equal to
-5.11.0, strictures are enabled lexically as
-with C<use strict>. Any explicit use of
-C<use strict> or C<no strict> overrides C<use VERSION>, even if it comes
-before it. In both cases, the F<feature.pm> and F<strict.pm> files are
-not actually loaded.
-
-The C<BEGIN> forces the C<require> and C<import> to happen at compile time. The
-C<require> makes sure the module is loaded into memory if it hasn't been
-yet. The C<import> is not a builtin; it's just an ordinary static method
-call into the C<Module> package to tell the module to import the list of
-features back into the current package. The module can implement its
-C<import> method any way it likes, though most modules just choose to
-derive their C<import> method via inheritance from the C<Exporter> class that
-is defined in the C<Exporter> module. See L<Exporter>. If no C<import>
-method can be found then the call is skipped, even if there is an AUTOLOAD
-method.
-
-If you do not want to call the package's C<import> method (for instance,
-to stop your namespace from being altered), explicitly supply the empty list:
-
- use Module ();
-
-That is exactly equivalent to
-
- BEGIN { require Module }
-
-If the VERSION argument is present between Module and LIST, then the
-C<use> will call the VERSION method in class Module with the given
-version as an argument. The default VERSION method, inherited from
-the UNIVERSAL class, croaks if the given version is larger than the
-value of the variable C<$Module::VERSION>.
-
-Again, there is a distinction between omitting LIST (C<import> called
-with no arguments) and an explicit empty LIST C<()> (C<import> not
-called). Note that there is no comma after VERSION!
-
-Because this is a wide-open interface, pragmas (compiler directives)
-are also implemented this way. Currently implemented pragmas are:
-
- use constant;
- use diagnostics;
- use integer;
- use sigtrap qw(SEGV BUS);
- use strict qw(subs vars refs);
- use subs qw(afunc blurfl);
- use warnings qw(all);
- use sort qw(stable _quicksort _mergesort);
-
-Some of these pseudo-modules import semantics into the current
-block scope (like C<strict> or C<integer>, unlike ordinary modules,
-which import symbols into the current package (which are effective
-through the end of the file).
-
-Because C<use> takes effect at compile time, it doesn't respect the
-ordinary flow control of the code being compiled. In particular, putting
-a C<use> inside the false branch of a conditional doesn't prevent it
-from being processed. If a module or pragma only needs to be loaded
-conditionally, this can be done using the L<if> pragma:
-
- use if $] < 5.008, "utf8";
- use if WANT_WARNINGS, warnings => qw(all);
-
-There's a corresponding C<no> declaration that unimports meanings imported
-by C<use>, i.e., it calls C<unimport Module LIST> instead of C<import>.
-It behaves just as C<import> does with VERSION, an omitted or empty LIST,
-or no unimport method being found.
-
- no integer;
- no strict 'refs';
- no warnings;
-
-Care should be taken when using the C<no VERSION> form of C<no>. It is
-I<only> meant to be used to assert that the running Perl is of a earlier
-version than its argument and I<not> to undo the feature-enabling side effects
-of C<use VERSION>.
-
-See L<perlmodlib> for a list of standard modules and pragmas. See L<perlrun>
-for the C<-M> and C<-m> command-line options to Perl that give C<use>
-functionality from the command-line.
-
-=item utime LIST
-X<utime>
-
-=for Pod::Functions set a file's last access and modify times
-
-Changes the access and modification times on each file of a list of
-files. The first two elements of the list must be the NUMERIC access
-and modification times, in that order. Returns the number of files
-successfully changed. The inode change time of each file is set
-to the current time. For example, this code has the same effect as the
-Unix touch(1) command when the files I<already exist> and belong to
-the user running the program:
-
- #!/usr/bin/perl
- $atime = $mtime = time;
- utime $atime, $mtime, @ARGV;
-
-Since Perl 5.7.2, if the first two elements of the list are C<undef>,
-the utime(2) syscall from your C library is called with a null second
-argument. On most systems, this will set the file's access and
-modification times to the current time (i.e., equivalent to the example
-above) and will work even on files you don't own provided you have write
-permission:
-
- for $file (@ARGV) {
- utime(undef, undef, $file)
- || warn "couldn't touch $file: $!";
- }
-
-Under NFS this will use the time of the NFS server, not the time of
-the local machine. If there is a time synchronization problem, the
-NFS server and local machine will have different times. The Unix
-touch(1) command will in fact normally use this form instead of the
-one shown in the first example.
-
-Passing only one of the first two elements as C<undef> is
-equivalent to passing a 0 and will not have the effect
-described when both are C<undef>. This also triggers an
-uninitialized warning.
-
-On systems that support futimes(2), you may pass filehandles among the
-files. On systems that don't support futimes(2), passing filehandles raises
-an exception. Filehandles must be passed as globs or glob references to be
-recognized; barewords are considered filenames.
-
-Portability issues: L<perlport/utime>.
-
-=item values HASH
-X<values>
-
-=item values ARRAY
-
-=item values EXPR
-
-=for Pod::Functions return a list of the values in a hash
-
-In list context, returns a list consisting of all the values of the named
-hash. In Perl 5.12 or later only, will also return a list of the values of
-an array; prior to that release, attempting to use an array argument will
-produce a syntax error. In scalar context, returns the number of values.
-
-When called on a hash, the values are returned in an apparently random
-order. The actual random order is subject to change in future versions of
-Perl, but it is guaranteed to be the same order as either the C<keys> or
-C<each> function would produce on the same (unmodified) hash. Since Perl
-5.8.1 the ordering is different even between different runs of Perl for
-security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
-
-As a side effect, calling values() resets the HASH or ARRAY's internal
-iterator, see L</each>. (In particular, calling values() in void context
-resets the iterator with no other overhead. Apart from resetting the
-iterator, C<values @array> in list context is the same as plain C<@array>.
-(We recommend that you use void context C<keys @array> for this, but
-reasoned that taking C<values @array> out would require more
-documentation than leaving it in.)
-
-Note that the values are not copied, which means modifying them will
-modify the contents of the hash:
-
- for (values %hash) { s/foo/bar/g } # modifies %hash values
- for (@hash{keys %hash}) { s/foo/bar/g } # same
-
-Starting with Perl 5.14, C<values> can take a scalar EXPR, which must hold
-a reference to an unblessed hash or array. The argument will be
-dereferenced automatically. This aspect of C<values> is considered highly
-experimental. The exact behaviour may change in a future version of Perl.
-
- for (values $hashref) { ... }
- for (values $obj->get_arrayref) { ... }
-
-To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work I<only> on Perls of
-a recent vintage:
-
- use 5.012; # so keys/values/each work on arrays
- use 5.014; # so keys/values/each work on scalars (experimental)
-
-See also C<keys>, C<each>, and C<sort>.
-
-=item vec EXPR,OFFSET,BITS
-X<vec> X<bit> X<bit vector>
-
-=for Pod::Functions test or set particular bits in a string
-
-Treats the string in EXPR as a bit vector made up of elements of
-width BITS and returns the value of the element specified by OFFSET
-as an unsigned integer. BITS therefore specifies the number of bits
-that are reserved for each element in the bit vector. This must
-be a power of two from 1 to 32 (or 64, if your platform supports
-that).
-
-If BITS is 8, "elements" coincide with bytes of the input string.
-
-If BITS is 16 or more, bytes of the input string are grouped into chunks
-of size BITS/8, and each group is converted to a number as with
-pack()/unpack() with big-endian formats C<n>/C<N> (and analogously
-for BITS==64). See L<"pack"> for details.
-
-If bits is 4 or less, the string is broken into bytes, then the bits
-of each byte are broken into 8/BITS groups. Bits of a byte are
-numbered in a little-endian-ish way, as in C<0x01>, C<0x02>,
-C<0x04>, C<0x08>, C<0x10>, C<0x20>, C<0x40>, C<0x80>. For example,
-breaking the single input byte C<chr(0x36)> into two groups gives a list
-C<(0x6, 0x3)>; breaking it into 4 groups gives C<(0x2, 0x1, 0x3, 0x0)>.
-
-C<vec> may also be assigned to, in which case parentheses are needed
-to give the expression the correct precedence as in
-
- vec($image, $max_x * $x + $y, 8) = 3;
-
-If the selected element is outside the string, the value 0 is returned.
-If an element off the end of the string is written to, Perl will first
-extend the string with sufficiently many zero bytes. It is an error
-to try to write off the beginning of the string (i.e., negative OFFSET).
-
-If the string happens to be encoded as UTF-8 internally (and thus has
-the UTF8 flag set), this is ignored by C<vec>, and it operates on the
-internal byte string, not the conceptual character string, even if you
-only have characters with values less than 256.
-
-Strings created with C<vec> can also be manipulated with the logical
-operators C<|>, C<&>, C<^>, and C<~>. These operators will assume a bit
-vector operation is desired when both operands are strings.
-See L<perlop/"Bitwise String Operators">.
-
-The following code will build up an ASCII string saying C<'PerlPerlPerl'>.
-The comments show the string after each step. Note that this code works
-in the same way on big-endian or little-endian machines.
-
- my $foo = '';
- vec($foo, 0, 32) = 0x5065726C; # 'Perl'
-
- # $foo eq "Perl" eq "\x50\x65\x72\x6C", 32 bits
- print vec($foo, 0, 8); # prints 80 == 0x50 == ord('P')
-
- vec($foo, 2, 16) = 0x5065; # 'PerlPe'
- vec($foo, 3, 16) = 0x726C; # 'PerlPerl'
- vec($foo, 8, 8) = 0x50; # 'PerlPerlP'
- vec($foo, 9, 8) = 0x65; # 'PerlPerlPe'
- vec($foo, 20, 4) = 2; # 'PerlPerlPe' . "\x02"
- vec($foo, 21, 4) = 7; # 'PerlPerlPer'
- # 'r' is "\x72"
- vec($foo, 45, 2) = 3; # 'PerlPerlPer' . "\x0c"
- vec($foo, 93, 1) = 1; # 'PerlPerlPer' . "\x2c"
- vec($foo, 94, 1) = 1; # 'PerlPerlPerl'
- # 'l' is "\x6c"
-
-To transform a bit vector into a string or list of 0's and 1's, use these:
-
- $bits = unpack("b*", $vector);
- @bits = split(//, unpack("b*", $vector));
-
-If you know the exact length in bits, it can be used in place of the C<*>.
-
-Here is an example to illustrate how the bits actually fall in place:
-
- #!/usr/bin/perl -wl
-
- print <<'EOT';
- 0 1 2 3
- unpack("V",$_) 01234567890123456789012345678901
- ------------------------------------------------------------------
- EOT
-
- for $w (0..3) {
- $width = 2**$w;
- for ($shift=0; $shift < $width; ++$shift) {
- for ($off=0; $off < 32/$width; ++$off) {
- $str = pack("B*", "0"x32);
- $bits = (1<<$shift);
- vec($str, $off, $width) = $bits;
- $res = unpack("b*",$str);
- $val = unpack("V", $str);
- write;
- }
- }
- }
-
- format STDOUT =
- vec($_,@#,@#) = @<< == @######### @>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
- $off, $width, $bits, $val, $res
- .
- __END__
-
-Regardless of the machine architecture on which it runs, the
-example above should print the following table:
-
- 0 1 2 3
- unpack("V",$_) 01234567890123456789012345678901
- ------------------------------------------------------------------
- vec($_, 0, 1) = 1 == 1 10000000000000000000000000000000
- vec($_, 1, 1) = 1 == 2 01000000000000000000000000000000
- vec($_, 2, 1) = 1 == 4 00100000000000000000000000000000
- vec($_, 3, 1) = 1 == 8 00010000000000000000000000000000
- vec($_, 4, 1) = 1 == 16 00001000000000000000000000000000
- vec($_, 5, 1) = 1 == 32 00000100000000000000000000000000
- vec($_, 6, 1) = 1 == 64 00000010000000000000000000000000
- vec($_, 7, 1) = 1 == 128 00000001000000000000000000000000
- vec($_, 8, 1) = 1 == 256 00000000100000000000000000000000
- vec($_, 9, 1) = 1 == 512 00000000010000000000000000000000
- vec($_,10, 1) = 1 == 1024 00000000001000000000000000000000
- vec($_,11, 1) = 1 == 2048 00000000000100000000000000000000
- vec($_,12, 1) = 1 == 4096 00000000000010000000000000000000
- vec($_,13, 1) = 1 == 8192 00000000000001000000000000000000
- vec($_,14, 1) = 1 == 16384 00000000000000100000000000000000
- vec($_,15, 1) = 1 == 32768 00000000000000010000000000000000
- vec($_,16, 1) = 1 == 65536 00000000000000001000000000000000
- vec($_,17, 1) = 1 == 131072 00000000000000000100000000000000
- vec($_,18, 1) = 1 == 262144 00000000000000000010000000000000
- vec($_,19, 1) = 1 == 524288 00000000000000000001000000000000
- vec($_,20, 1) = 1 == 1048576 00000000000000000000100000000000
- vec($_,21, 1) = 1 == 2097152 00000000000000000000010000000000
- vec($_,22, 1) = 1 == 4194304 00000000000000000000001000000000
- vec($_,23, 1) = 1 == 8388608 00000000000000000000000100000000
- vec($_,24, 1) = 1 == 16777216 00000000000000000000000010000000
- vec($_,25, 1) = 1 == 33554432 00000000000000000000000001000000
- vec($_,26, 1) = 1 == 67108864 00000000000000000000000000100000
- vec($_,27, 1) = 1 == 134217728 00000000000000000000000000010000
- vec($_,28, 1) = 1 == 268435456 00000000000000000000000000001000
- vec($_,29, 1) = 1 == 536870912 00000000000000000000000000000100
- vec($_,30, 1) = 1 == 1073741824 00000000000000000000000000000010
- vec($_,31, 1) = 1 == 2147483648 00000000000000000000000000000001
- vec($_, 0, 2) = 1 == 1 10000000000000000000000000000000
- vec($_, 1, 2) = 1 == 4 00100000000000000000000000000000
- vec($_, 2, 2) = 1 == 16 00001000000000000000000000000000
- vec($_, 3, 2) = 1 == 64 00000010000000000000000000000000
- vec($_, 4, 2) = 1 == 256 00000000100000000000000000000000
- vec($_, 5, 2) = 1 == 1024 00000000001000000000000000000000
- vec($_, 6, 2) = 1 == 4096 00000000000010000000000000000000
- vec($_, 7, 2) = 1 == 16384 00000000000000100000000000000000
- vec($_, 8, 2) = 1 == 65536 00000000000000001000000000000000
- vec($_, 9, 2) = 1 == 262144 00000000000000000010000000000000
- vec($_,10, 2) = 1 == 1048576 00000000000000000000100000000000
- vec($_,11, 2) = 1 == 4194304 00000000000000000000001000000000
- vec($_,12, 2) = 1 == 16777216 00000000000000000000000010000000
- vec($_,13, 2) = 1 == 67108864 00000000000000000000000000100000
- vec($_,14, 2) = 1 == 268435456 00000000000000000000000000001000
- vec($_,15, 2) = 1 == 1073741824 00000000000000000000000000000010
- vec($_, 0, 2) = 2 == 2 01000000000000000000000000000000
- vec($_, 1, 2) = 2 == 8 00010000000000000000000000000000
- vec($_, 2, 2) = 2 == 32 00000100000000000000000000000000
- vec($_, 3, 2) = 2 == 128 00000001000000000000000000000000
- vec($_, 4, 2) = 2 == 512 00000000010000000000000000000000
- vec($_, 5, 2) = 2 == 2048 00000000000100000000000000000000
- vec($_, 6, 2) = 2 == 8192 00000000000001000000000000000000
- vec($_, 7, 2) = 2 == 32768 00000000000000010000000000000000
- vec($_, 8, 2) = 2 == 131072 00000000000000000100000000000000
- vec($_, 9, 2) = 2 == 524288 00000000000000000001000000000000
- vec($_,10, 2) = 2 == 2097152 00000000000000000000010000000000
- vec($_,11, 2) = 2 == 8388608 00000000000000000000000100000000
- vec($_,12, 2) = 2 == 33554432 00000000000000000000000001000000
- vec($_,13, 2) = 2 == 134217728 00000000000000000000000000010000
- vec($_,14, 2) = 2 == 536870912 00000000000000000000000000000100
- vec($_,15, 2) = 2 == 2147483648 00000000000000000000000000000001
- vec($_, 0, 4) = 1 == 1 10000000000000000000000000000000
- vec($_, 1, 4) = 1 == 16 00001000000000000000000000000000
- vec($_, 2, 4) = 1 == 256 00000000100000000000000000000000
- vec($_, 3, 4) = 1 == 4096 00000000000010000000000000000000
- vec($_, 4, 4) = 1 == 65536 00000000000000001000000000000000
- vec($_, 5, 4) = 1 == 1048576 00000000000000000000100000000000
- vec($_, 6, 4) = 1 == 16777216 00000000000000000000000010000000
- vec($_, 7, 4) = 1 == 268435456 00000000000000000000000000001000
- vec($_, 0, 4) = 2 == 2 01000000000000000000000000000000
- vec($_, 1, 4) = 2 == 32 00000100000000000000000000000000
- vec($_, 2, 4) = 2 == 512 00000000010000000000000000000000
- vec($_, 3, 4) = 2 == 8192 00000000000001000000000000000000
- vec($_, 4, 4) = 2 == 131072 00000000000000000100000000000000
- vec($_, 5, 4) = 2 == 2097152 00000000000000000000010000000000
- vec($_, 6, 4) = 2 == 33554432 00000000000000000000000001000000
- vec($_, 7, 4) = 2 == 536870912 00000000000000000000000000000100
- vec($_, 0, 4) = 4 == 4 00100000000000000000000000000000
- vec($_, 1, 4) = 4 == 64 00000010000000000000000000000000
- vec($_, 2, 4) = 4 == 1024 00000000001000000000000000000000
- vec($_, 3, 4) = 4 == 16384 00000000000000100000000000000000
- vec($_, 4, 4) = 4 == 262144 00000000000000000010000000000000
- vec($_, 5, 4) = 4 == 4194304 00000000000000000000001000000000
- vec($_, 6, 4) = 4 == 67108864 00000000000000000000000000100000
- vec($_, 7, 4) = 4 == 1073741824 00000000000000000000000000000010
- vec($_, 0, 4) = 8 == 8 00010000000000000000000000000000
- vec($_, 1, 4) = 8 == 128 00000001000000000000000000000000
- vec($_, 2, 4) = 8 == 2048 00000000000100000000000000000000
- vec($_, 3, 4) = 8 == 32768 00000000000000010000000000000000
- vec($_, 4, 4) = 8 == 524288 00000000000000000001000000000000
- vec($_, 5, 4) = 8 == 8388608 00000000000000000000000100000000
- vec($_, 6, 4) = 8 == 134217728 00000000000000000000000000010000
- vec($_, 7, 4) = 8 == 2147483648 00000000000000000000000000000001
- vec($_, 0, 8) = 1 == 1 10000000000000000000000000000000
- vec($_, 1, 8) = 1 == 256 00000000100000000000000000000000
- vec($_, 2, 8) = 1 == 65536 00000000000000001000000000000000
- vec($_, 3, 8) = 1 == 16777216 00000000000000000000000010000000
- vec($_, 0, 8) = 2 == 2 01000000000000000000000000000000
- vec($_, 1, 8) = 2 == 512 00000000010000000000000000000000
- vec($_, 2, 8) = 2 == 131072 00000000000000000100000000000000
- vec($_, 3, 8) = 2 == 33554432 00000000000000000000000001000000
- vec($_, 0, 8) = 4 == 4 00100000000000000000000000000000
- vec($_, 1, 8) = 4 == 1024 00000000001000000000000000000000
- vec($_, 2, 8) = 4 == 262144 00000000000000000010000000000000
- vec($_, 3, 8) = 4 == 67108864 00000000000000000000000000100000
- vec($_, 0, 8) = 8 == 8 00010000000000000000000000000000
- vec($_, 1, 8) = 8 == 2048 00000000000100000000000000000000
- vec($_, 2, 8) = 8 == 524288 00000000000000000001000000000000
- vec($_, 3, 8) = 8 == 134217728 00000000000000000000000000010000
- vec($_, 0, 8) = 16 == 16 00001000000000000000000000000000
- vec($_, 1, 8) = 16 == 4096 00000000000010000000000000000000
- vec($_, 2, 8) = 16 == 1048576 00000000000000000000100000000000
- vec($_, 3, 8) = 16 == 268435456 00000000000000000000000000001000
- vec($_, 0, 8) = 32 == 32 00000100000000000000000000000000
- vec($_, 1, 8) = 32 == 8192 00000000000001000000000000000000
- vec($_, 2, 8) = 32 == 2097152 00000000000000000000010000000000
- vec($_, 3, 8) = 32 == 536870912 00000000000000000000000000000100
- vec($_, 0, 8) = 64 == 64 00000010000000000000000000000000
- vec($_, 1, 8) = 64 == 16384 00000000000000100000000000000000
- vec($_, 2, 8) = 64 == 4194304 00000000000000000000001000000000
- vec($_, 3, 8) = 64 == 1073741824 00000000000000000000000000000010
- vec($_, 0, 8) = 128 == 128 00000001000000000000000000000000
- vec($_, 1, 8) = 128 == 32768 00000000000000010000000000000000
- vec($_, 2, 8) = 128 == 8388608 00000000000000000000000100000000
- vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
-
-=item wait
-X<wait>
-
-=for Pod::Functions wait for any child process to die
-
-Behaves like wait(2) on your system: it waits for a child
-process to terminate and returns the pid of the deceased process, or
-C<-1> if there are no child processes. The status is returned in C<$?>
-and C<${^CHILD_ERROR_NATIVE}>.
-Note that a return value of C<-1> could mean that child processes are
-being automatically reaped, as described in L<perlipc>.
-
-If you use wait in your handler for $SIG{CHLD} it may accidentally for the
-child created by qx() or system(). See L<perlipc> for details.
-
-Portability issues: L<perlport/wait>.
-
-=item waitpid PID,FLAGS
-X<waitpid>
-
-=for Pod::Functions wait for a particular child process to die
-
-Waits for a particular child process to terminate and returns the pid of
-the deceased process, or C<-1> if there is no such child process. On some
-systems, a value of 0 indicates that there are processes still running.
-The status is returned in C<$?> and C<${^CHILD_ERROR_NATIVE}>. If you say
-
- use POSIX ":sys_wait_h";
- #...
- do {
- $kid = waitpid(-1, WNOHANG);
- } while $kid > 0;
-
-then you can do a non-blocking wait for all pending zombie processes.
-Non-blocking wait is available on machines supporting either the
-waitpid(2) or wait4(2) syscalls. However, waiting for a particular
-pid with FLAGS of C<0> is implemented everywhere. (Perl emulates the
-system call by remembering the status values of processes that have
-exited but have not been harvested by the Perl script yet.)
-
-Note that on some systems, a return value of C<-1> could mean that child
-processes are being automatically reaped. See L<perlipc> for details,
-and for other examples.
-
-Portability issues: L<perlport/waitpid>.
-
-=item wantarray
-X<wantarray> X<context>
-
-=for Pod::Functions get void vs scalar vs list context of current subroutine call
-
-Returns true if the context of the currently executing subroutine or
-C<eval> is looking for a list value. Returns false if the context is
-looking for a scalar. Returns the undefined value if the context is
-looking for no value (void context).
-
- return unless defined wantarray; # don't bother doing more
- my @a = complex_calculation();
- return wantarray ? @a : "@a";
-
-C<wantarray()>'s result is unspecified in the top level of a file,
-in a C<BEGIN>, C<UNITCHECK>, C<CHECK>, C<INIT> or C<END> block, or
-in a C<DESTROY> method.
-
-This function should have been named wantlist() instead.
-
-=item warn LIST
-X<warn> X<warning> X<STDERR>
-
-=for Pod::Functions print debugging info
-
-Prints the value of LIST to STDERR. If the last element of LIST does
-not end in a newline, it appends the same file/line number text as C<die>
-does.
-
-If the output is empty and C<$@> already contains a value (typically from a
-previous eval) that value is used after appending C<"\t...caught">
-to C<$@>. This is useful for staying almost, but not entirely similar to
-C<die>.
-
-If C<$@> is empty then the string C<"Warning: Something's wrong"> is used.
-
-No message is printed if there is a C<$SIG{__WARN__}> handler
-installed. It is the handler's responsibility to deal with the message
-as it sees fit (like, for instance, converting it into a C<die>). Most
-handlers must therefore arrange to actually display the
-warnings that they are not prepared to deal with, by calling C<warn>
-again in the handler. Note that this is quite safe and will not
-produce an endless loop, since C<__WARN__> hooks are not called from
-inside one.
-
-You will find this behavior is slightly different from that of
-C<$SIG{__DIE__}> handlers (which don't suppress the error text, but can
-instead call C<die> again to change it).
-
-Using a C<__WARN__> handler provides a powerful way to silence all
-warnings (even the so-called mandatory ones). An example:
-
- # wipe out *all* compile-time warnings
- BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN } }
- my $foo = 10;
- my $foo = 20; # no warning about duplicate my $foo,
- # but hey, you asked for it!
- # no compile-time or run-time warnings before here
- $DOWARN = 1;
-
- # run-time warnings enabled after here
- warn "\$foo is alive and $foo!"; # does show up
-
-See L<perlvar> for details on setting C<%SIG> entries and for more
-examples. See the Carp module for other kinds of warnings using its
-carp() and cluck() functions.
-
-=item write FILEHANDLE
-X<write>
-
-=item write EXPR
-
-=item write
-
-=for Pod::Functions print a picture record
-
-Writes a formatted record (possibly multi-line) to the specified FILEHANDLE,
-using the format associated with that file. By default the format for
-a file is the one having the same name as the filehandle, but the
-format for the current output channel (see the C<select> function) may be set
-explicitly by assigning the name of the format to the C<$~> variable.
-
-Top of form processing is handled automatically: if there is insufficient
-room on the current page for the formatted record, the page is advanced by
-writing a form feed, a special top-of-page format is used to format the new
-page header before the record is written. By default, the top-of-page
-format is the name of the filehandle with "_TOP" appended. This would be a
-problem with autovivified filehandles, but it may be dynamically set to the
-format of your choice by assigning the name to the C<$^> variable while
-that filehandle is selected. The number of lines remaining on the current
-page is in variable C<$->, which can be set to C<0> to force a new page.
-
-If FILEHANDLE is unspecified, output goes to the current default output
-channel, which starts out as STDOUT but may be changed by the
-C<select> operator. If the FILEHANDLE is an EXPR, then the expression
-is evaluated and the resulting string is used to look up the name of
-the FILEHANDLE at run time. For more on formats, see L<perlform>.
-
-Note that write is I<not> the opposite of C<read>. Unfortunately.
-
-=item y///
-
-=for Pod::Functions transliterate a string
-
-The transliteration operator. Same as C<tr///>. See
-L<perlop/"Quote and Quote-like Operators">.
-
-=back
-
-=head2 Non-function Keywords by Cross-reference
-
-=head3 perldata
-
-=over
-
-=item __DATA__
-
-=item __END__
-
-These keywords are documented in L<perldata/"Special Literals">.
-
-=back
-
-=head3 perlmod
-
-=over
-
-=item BEGIN
-
-=item CHECK
-
-=item END
-
-=item INIT
-
-=item UNITCHECK
-
-These compile phase keywords are documented in L<perlmod/"BEGIN, UNITCHECK, CHECK, INIT and END">.
-
-=back
-
-=head3 perlobj
-
-=over
-
-=item DESTROY
-
-This method keyword is documented in L<perlobj/"Destructors">.
-
-=back
-
-=head3 perlop
-
-=over
-
-=item and
-
-=item cmp
-
-=item eq
-
-=item ge
-
-=item gt
-
-=item if
-
-=item le
-
-=item lt
-
-=item ne
-
-=item not
-
-=item or
-
-=item x
-
-=item xor
-
-These operators are documented in L<perlop>.
-
-=back
-
-=head3 perlsub
-
-=over
-
-=item AUTOLOAD
-
-This keyword is documented in L<perlsub/"Autoloading">.
-
-=back
-
-=head3 perlsyn
-
-=over
-
-=item else
-
-=item elseif
-
-=item elsif
-
-=item for
-
-=item foreach
-
-=item unless
-
-=item until
-
-=item while
-
-These flow-control keywords are documented in L<perlsyn/"Compound Statements">.
-
-=back
-
-=over
-
-=item default
-
-=item given
-
-=item when
-
-These flow-control keywords related to the experimental switch feature are
-documented in L<perlsyn/"Switch Statements"> .
-
-=back
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlgit.pod b/Master/tlpkg/tlperl/lib/pods/perlgit.pod
deleted file mode 100644
index 1d2df2ed5e9..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlgit.pod
+++ /dev/null
@@ -1,850 +0,0 @@
-=encoding utf8
-
-=for comment
-Consistent formatting of this file is achieved with:
- perl ./Porting/podtidy pod/perlgit.pod
-
-=head1 NAME
-
-perlgit - Detailed information about git and the Perl repository
-
-=head1 DESCRIPTION
-
-This document provides details on using git to develop Perl. If you are
-just interested in working on a quick patch, see L<perlhack> first.
-This document is intended for people who are regular contributors to
-Perl, including those with write access to the git repository.
-
-=head1 CLONING THE REPOSITORY
-
-All of Perl's source code is kept centrally in a Git repository at
-I<perl5.git.perl.org>.
-
-You can make a read-only clone of the repository by running:
-
- % git clone git://perl5.git.perl.org/perl.git perl
-
-This uses the git protocol (port 9418).
-
-If you cannot use the git protocol for firewall reasons, you can also
-clone via http, though this is much slower:
-
- % git clone http://perl5.git.perl.org/perl.git perl
-
-=head1 WORKING WITH THE REPOSITORY
-
-Once you have changed into the repository directory, you can inspect
-it. After a clone the repository will contain a single local branch,
-which will be the current branch as well, as indicated by the asterisk.
-
- % git branch
- * blead
-
-Using the -a switch to C<branch> will also show the remote tracking
-branches in the repository:
-
- % git branch -a
- * blead
- origin/HEAD
- origin/blead
- ...
-
-The branches that begin with "origin" correspond to the "git remote"
-that you cloned from (which is named "origin"). Each branch on the
-remote will be exactly tracked by these branches. You should NEVER do
-work on these remote tracking branches. You only ever do work in a
-local branch. Local branches can be configured to automerge (on pull)
-from a designated remote tracking branch. This is the case with the
-default branch C<blead> which will be configured to merge from the
-remote tracking branch C<origin/blead>.
-
-You can see recent commits:
-
- % git log
-
-And pull new changes from the repository, and update your local
-repository (must be clean first)
-
- % git pull
-
-Assuming we are on the branch C<blead> immediately after a pull, this
-command would be more or less equivalent to:
-
- % git fetch
- % git merge origin/blead
-
-In fact if you want to update your local repository without touching
-your working directory you do:
-
- % git fetch
-
-And if you want to update your remote-tracking branches for all defined
-remotes simultaneously you can do
-
- % git remote update
-
-Neither of these last two commands will update your working directory,
-however both will update the remote-tracking branches in your
-repository.
-
-To make a local branch of a remote branch:
-
- % git checkout -b maint-5.10 origin/maint-5.10
-
-To switch back to blead:
-
- % git checkout blead
-
-=head2 Finding out your status
-
-The most common git command you will use will probably be
-
- % git status
-
-This command will produce as output a description of the current state
-of the repository, including modified files and unignored untracked
-files, and in addition it will show things like what files have been
-staged for the next commit, and usually some useful information about
-how to change things. For instance the following:
-
- $ git status
- # On branch blead
- # Your branch is ahead of 'origin/blead' by 1 commit.
- #
- # Changes to be committed:
- # (use "git reset HEAD <file>..." to unstage)
- #
- # modified: pod/perlgit.pod
- #
- # Changed but not updated:
- # (use "git add <file>..." to update what will be committed)
- #
- # modified: pod/perlgit.pod
- #
- # Untracked files:
- # (use "git add <file>..." to include in what will be committed)
- #
- # deliberate.untracked
-
-This shows that there were changes to this document staged for commit,
-and that there were further changes in the working directory not yet
-staged. It also shows that there was an untracked file in the working
-directory, and as you can see shows how to change all of this. It also
-shows that there is one commit on the working branch C<blead> which has
-not been pushed to the C<origin> remote yet. B<NOTE>: that this output
-is also what you see as a template if you do not provide a message to
-C<git commit>.
-
-=head2 Patch workflow
-
-First, please read L<perlhack> for details on hacking the Perl core.
-That document covers many details on how to create a good patch.
-
-If you already have a Perl repository, you should ensure that you're on
-the I<blead> branch, and your repository is up to date:
-
- % git checkout blead
- % git pull
-
-It's preferable to patch against the latest blead version, since this
-is where new development occurs for all changes other than critical bug
-fixes. Critical bug fix patches should be made against the relevant
-maint branches, or should be submitted with a note indicating all the
-branches where the fix should be applied.
-
-Now that we have everything up to date, we need to create a temporary
-new branch for these changes and switch into it:
-
- % git checkout -b orange
-
-which is the short form of
-
- % git branch orange
- % git checkout orange
-
-Creating a topic branch makes it easier for the maintainers to rebase
-or merge back into the master blead for a more linear history. If you
-don't work on a topic branch the maintainer has to manually cherry pick
-your changes onto blead before they can be applied.
-
-That'll get you scolded on perl5-porters, so don't do that. Be Awesome.
-
-Then make your changes. For example, if Leon Brocard changes his name
-to Orange Brocard, we should change his name in the AUTHORS file:
-
- % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
-
-You can see what files are changed:
-
- % git status
- # On branch orange
- # Changes to be committed:
- # (use "git reset HEAD <file>..." to unstage)
- #
- # modified: AUTHORS
- #
-
-And you can see the changes:
-
- % git diff
- diff --git a/AUTHORS b/AUTHORS
- index 293dd70..722c93e 100644
- --- a/AUTHORS
- +++ b/AUTHORS
- @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
- Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
- Leif Huhn <leif@hale.dkstat.com>
- Len Johnson <lenjay@ibm.net>
- -Leon Brocard <acme@astray.com>
- +Orange Brocard <acme@astray.com>
- Les Peters <lpeters@aol.net>
- Lesley Binks <lesley.binks@gmail.com>
- Lincoln D. Stein <lstein@cshl.org>
-
-Now commit your change locally:
-
- % git commit -a -m 'Rename Leon Brocard to Orange Brocard'
- Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
- 1 files changed, 1 insertions(+), 1 deletions(-)
-
-The C<-a> option is used to include all files that git tracks that you
-have changed. If at this time, you only want to commit some of the
-files you have worked on, you can omit the C<-a> and use the command
-C<S<git add I<FILE ...>>> before doing the commit. C<S<git add
---interactive>> allows you to even just commit portions of files
-instead of all the changes in them.
-
-The C<-m> option is used to specify the commit message. If you omit it,
-git will open a text editor for you to compose the message
-interactively. This is useful when the changes are more complex than
-the sample given here, and, depending on the editor, to know that the
-first line of the commit message doesn't exceed the 50 character legal
-maximum.
-
-Once you've finished writing your commit message and exited your
-editor, git will write your change to disk and tell you something like
-this:
-
- Created commit daf8e63: explain git status and stuff about remotes
- 1 files changed, 83 insertions(+), 3 deletions(-)
-
-If you re-run C<git status>, you should see something like this:
-
- % git status
- # On branch blead
- # Your branch is ahead of 'origin/blead' by 2 commits.
- #
- # Untracked files:
- # (use "git add <file>..." to include in what will be committed)
- #
- # deliberate.untracked
- nothing added to commit but untracked files present (use "git add" to track)
-
-When in doubt, before you do anything else, check your status and read
-it carefully, many questions are answered directly by the git status
-output.
-
-You can examine your last commit with:
-
- % git show HEAD
-
-and if you are not happy with either the description or the patch
-itself you can fix it up by editing the files once more and then issue:
-
- % git commit -a --amend
-
-Now you should create a patch file for all your local changes:
-
- % git format-patch -M origin..
- 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
-
-You should now send an email to
-L<perlbug@perl.org|mailto:perlbug@perl.org> with a description of your
-changes, and include this patch file as an attachment. In addition to
-being tracked by RT, mail to perlbug will automatically be forwarded to
-perl5-porters (with manual moderation, so please be patient). You
-should only send patches to
-L<perl5-porters@perl.org|mailto:perl5-porters@perl.org> directly if the
-patch is not ready to be applied, but intended for discussion.
-
-See the next section for how to configure and use git to send these
-emails for you.
-
-If you want to delete your temporary branch, you may do so with:
-
- % git checkout blead
- % git branch -d orange
- error: The branch 'orange' is not an ancestor of your current HEAD.
- If you are sure you want to delete it, run 'git branch -D orange'.
- % git branch -D orange
- Deleted branch orange.
-
-=head2 Committing your changes
-
-Assuming that you'd like to commit all the changes you've made as a
-single atomic unit, run this command:
-
- % git commit -a
-
-(That C<-a> tells git to add every file you've changed to this commit.
-New files aren't automatically added to your commit when you use
-C<commit -a> If you want to add files or to commit some, but not all of
-your changes, have a look at the documentation for C<git add>.)
-
-Git will start up your favorite text editor, so that you can craft a
-commit message for your change. See L<perlhack/Commit message> for more
-information about what makes a good commit message.
-
-Once you've finished writing your commit message and exited your
-editor, git will write your change to disk and tell you something like
-this:
-
- Created commit daf8e63: explain git status and stuff about remotes
- 1 files changed, 83 insertions(+), 3 deletions(-)
-
-If you re-run C<git status>, you should see something like this:
-
- % git status
- # On branch blead
- # Your branch is ahead of 'origin/blead' by 2 commits.
- #
- # Untracked files:
- # (use "git add <file>..." to include in what will be committed)
- #
- # deliberate.untracked
- nothing added to commit but untracked files present (use "git add" to track)
-
-When in doubt, before you do anything else, check your status and read
-it carefully, many questions are answered directly by the git status
-output.
-
-=head2 Using git to send patch emails
-
-Please read L<perlhack> first in order to figure out where your patches
-should be sent.
-
-In your ~/git/perl repository, set the destination email to perl's bug
-tracker:
-
- $ git config sendemail.to perlbug@perl.org
-
-Or maybe perl5-porters:
-
- $ git config sendemail.to perl5-porters@perl.org
-
-Then you can use git directly to send your patch emails:
-
- $ git send-email 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
-
-You may need to set some configuration variables for your particular
-email service provider. For example, to set your global git config to
-send email via a gmail account:
-
- $ git config --global sendemail.smtpserver smtp.gmail.com
- $ git config --global sendemail.smtpssl 1
- $ git config --global sendemail.smtpuser YOURUSERNAME@gmail.com
-
-With this configuration, you will be prompted for your gmail password
-when you run 'git send-email'. You can also configure
-C<sendemail.smtppass> with your password if you don't care about having
-your password in the .gitconfig file.
-
-=head2 A note on derived files
-
-Be aware that many files in the distribution are derivative--avoid
-patching them, because git won't see the changes to them, and the build
-process will overwrite them. Patch the originals instead. Most
-utilities (like perldoc) are in this category, i.e. patch
-F<utils/perldoc.PL> rather than F<utils/perldoc>. Similarly, don't
-create patches for files under $src_root/ext from their copies found in
-$install_root/lib. If you are unsure about the proper location of a
-file that may have gotten copied while building the source
-distribution, consult the C<MANIFEST>.
-
-=head2 Cleaning a working directory
-
-The command C<git clean> can with varying arguments be used as a
-replacement for C<make clean>.
-
-To reset your working directory to a pristine condition you can do:
-
- % git clean -dxf
-
-However, be aware this will delete ALL untracked content. You can use
-
- % git clean -Xf
-
-to remove all ignored untracked files, such as build and test
-byproduct, but leave any manually created files alone.
-
-If you only want to cancel some uncommitted edits, you can use C<git
-checkout> and give it a list of files to be reverted, or C<git checkout
--f> to revert them all.
-
-If you want to cancel one or several commits, you can use C<git reset>.
-
-=head2 Bisecting
-
-C<git> provides a built-in way to determine which commit should be blamed
-for introducing a given bug. C<git bisect> performs a binary search of
-history to locate the first failing commit. It is fast, powerful and
-flexible, but requires some setup and to automate the process an auxiliary
-shell script is needed.
-
-The core provides a wrapper program, F<Porting/bisect.pl>, which attempts to
-simplify as much as possible, making bisecting as simple as running a Perl
-one-liner. For example, if you want to know when this became an error:
-
- perl -e 'my $a := 2'
-
-you simply run this:
-
- .../Porting/bisect.pl -e 'my $a := 2;'
-
-Using C<bisect.pl>, with one command (and no other files) it's easy to find
-out
-
-=over 4
-
-=item *
-
-Which commit caused this example code to break?
-
-=item *
-
-Which commit caused this example code to start working?
-
-=item *
-
-Which commit added the first file to match this regex?
-
-=item *
-
-Which commit removed the last file to match this regex?
-
-=back
-
-usually without needing to know which versions of perl to use as start and
-end revisions, as F<bisect.pl> automatically searches to find the earliest
-stable version for which the test case passes. Run
-C<Porting/bisect.pl --help> for the full documentation, including how to
-set the C<Configure> and build time options.
-
-If you require more flexibility than F<Porting/bisect.pl> has to offer, you'll
-need to run C<git bisect> yourself. It's most useful to use C<git bisect run>
-to automate the building and testing of perl revisions. For this you'll need
-a shell script for C<git> to call to test a particular revision. An example
-script is F<Porting/bisect-example.sh>, which you should copy B<outside> of
-the repository, as the bisect process will reset the state to a clean checkout
-as it runs. The instructions below assume that you copied it as F<~/run> and
-then edited it as appropriate.
-
-You first enter in bisect mode with:
-
- % git bisect start
-
-For example, if the bug is present on C<HEAD> but wasn't in 5.10.0,
-C<git> will learn about this when you enter:
-
- % git bisect bad
- % git bisect good perl-5.10.0
- Bisecting: 853 revisions left to test after this
-
-This results in checking out the median commit between C<HEAD> and
-C<perl-5.10.0>. You can then run the bisecting process with:
-
- % git bisect run ~/run
-
-When the first bad commit is isolated, C<git bisect> will tell you so:
-
- ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit
- commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5
- Author: Dave Mitchell <davem@fdisolutions.com>
- Date: Sat Feb 9 14:56:23 2008 +0000
-
- [perl #49472] Attributes + Unknown Error
- ...
-
- bisect run success
-
-You can peek into the bisecting process with C<git bisect log> and
-C<git bisect visualize>. C<git bisect reset> will get you out of bisect
-mode.
-
-Please note that the first C<good> state must be an ancestor of the
-first C<bad> state. If you want to search for the commit that I<solved>
-some bug, you have to negate your test case (i.e. exit with C<1> if OK
-and C<0> if not) and still mark the lower bound as C<good> and the
-upper as C<bad>. The "first bad commit" has then to be understood as
-the "first commit where the bug is solved".
-
-C<git help bisect> has much more information on how you can tweak your
-binary searches.
-
-=head1 Topic branches and rewriting history
-
-Individual committers should create topic branches under
-B<yourname>/B<some_descriptive_name>. Other committers should check
-with a topic branch's creator before making any change to it.
-
-The simplest way to create a remote topic branch that works on all
-versions of git is to push the current head as a new branch on the
-remote, then check it out locally:
-
- $ branch="$yourname/$some_descriptive_name"
- $ git push origin HEAD:$branch
- $ git checkout -b $branch origin/$branch
-
-Users of git 1.7 or newer can do it in a more obvious manner:
-
- $ branch="$yourname/$some_descriptive_name"
- $ git checkout -b $branch
- $ git push origin -u $branch
-
-If you are not the creator of B<yourname>/B<some_descriptive_name>, you
-might sometimes find that the original author has edited the branch's
-history. There are lots of good reasons for this. Sometimes, an author
-might simply be rebasing the branch onto a newer source point.
-Sometimes, an author might have found an error in an early commit which
-they wanted to fix before merging the branch to blead.
-
-Currently the master repository is configured to forbid
-non-fast-forward merges. This means that the branches within can not be
-rebased and pushed as a single step.
-
-The only way you will ever be allowed to rebase or modify the history
-of a pushed branch is to delete it and push it as a new branch under
-the same name. Please think carefully about doing this. It may be
-better to sequentially rename your branches so that it is easier for
-others working with you to cherry-pick their local changes onto the new
-version. (XXX: needs explanation).
-
-If you want to rebase a personal topic branch, you will have to delete
-your existing topic branch and push as a new version of it. You can do
-this via the following formula (see the explanation about C<refspec>'s
-in the git push documentation for details) after you have rebased your
-branch:
-
- # first rebase
- $ git checkout $user/$topic
- $ git fetch
- $ git rebase origin/blead
-
- # then "delete-and-push"
- $ git push origin :$user/$topic
- $ git push origin $user/$topic
-
-B<NOTE:> it is forbidden at the repository level to delete any of the
-"primary" branches. That is any branch matching
-C<m!^(blead|maint|perl)!>. Any attempt to do so will result in git
-producing an error like this:
-
- $ git push origin :blead
- *** It is forbidden to delete blead/maint branches in this repository
- error: hooks/update exited with error code 1
- error: hook declined to update refs/heads/blead
- To ssh://perl5.git.perl.org/perl
- ! [remote rejected] blead (hook declined)
- error: failed to push some refs to 'ssh://perl5.git.perl.org/perl'
-
-As a matter of policy we do B<not> edit the history of the blead and
-maint-* branches. If a typo (or worse) sneaks into a commit to blead or
-maint-*, we'll fix it in another commit. The only types of updates
-allowed on these branches are "fast-forward's", where all history is
-preserved.
-
-Annotated tags in the canonical perl.git repository will never be
-deleted or modified. Think long and hard about whether you want to push
-a local tag to perl.git before doing so. (Pushing unannotated tags is
-not allowed.)
-
-=head2 Grafts
-
-The perl history contains one mistake which was not caught in the
-conversion: a merge was recorded in the history between blead and
-maint-5.10 where no merge actually occurred. Due to the nature of git,
-this is now impossible to fix in the public repository. You can remove
-this mis-merge locally by adding the following line to your
-C<.git/info/grafts> file:
-
- 296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930
-
-It is particularly important to have this graft line if any bisecting
-is done in the area of the "merge" in question.
-
-=head1 WRITE ACCESS TO THE GIT REPOSITORY
-
-Once you have write access, you will need to modify the URL for the
-origin remote to enable pushing. Edit F<.git/config> with the
-git-config(1) command:
-
- % git config remote.origin.url ssh://perl5.git.perl.org/perl.git
-
-You can also set up your user name and e-mail address. Most people do
-this once globally in their F<~/.gitconfig> by doing something like:
-
- % git config --global user.name "Ævar Arnfjörð Bjarmason"
- % git config --global user.email avarab@gmail.com
-
-However if you'd like to override that just for perl then execute then
-execute something like the following in F<perl>:
-
- % git config user.email avar@cpan.org
-
-It is also possible to keep C<origin> as a git remote, and add a new
-remote for ssh access:
-
- % git remote add camel perl5.git.perl.org:/perl.git
-
-This allows you to update your local repository by pulling from
-C<origin>, which is faster and doesn't require you to authenticate, and
-to push your changes back with the C<camel> remote:
-
- % git fetch camel
- % git push camel
-
-The C<fetch> command just updates the C<camel> refs, as the objects
-themselves should have been fetched when pulling from C<origin>.
-
-=head1 Accepting a patch
-
-If you have received a patch file generated using the above section,
-you should try out the patch.
-
-First we need to create a temporary new branch for these changes and
-switch into it:
-
- % git checkout -b experimental
-
-Patches that were formatted by C<git format-patch> are applied with
-C<git am>:
-
- % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
- Applying Rename Leon Brocard to Orange Brocard
-
-If just a raw diff is provided, it is also possible use this two-step
-process:
-
- % git apply bugfix.diff
- % git commit -a -m "Some fixing" --author="That Guy <that.guy@internets.com>"
-
-Now we can inspect the change:
-
- % git show HEAD
- commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
- Author: Leon Brocard <acme@astray.com>
- Date: Fri Dec 19 17:02:59 2008 +0000
-
- Rename Leon Brocard to Orange Brocard
-
- diff --git a/AUTHORS b/AUTHORS
- index 293dd70..722c93e 100644
- --- a/AUTHORS
- +++ b/AUTHORS
- @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
- Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
- Leif Huhn <leif@hale.dkstat.com>
- Len Johnson <lenjay@ibm.net>
- -Leon Brocard <acme@astray.com>
- +Orange Brocard <acme@astray.com>
- Les Peters <lpeters@aol.net>
- Lesley Binks <lesley.binks@gmail.com>
- Lincoln D. Stein <lstein@cshl.org>
-
-If you are a committer to Perl and you think the patch is good, you can
-then merge it into blead then push it out to the main repository:
-
- % git checkout blead
- % git merge experimental
- % git push
-
-If you want to delete your temporary branch, you may do so with:
-
- % git checkout blead
- % git branch -d experimental
- error: The branch 'experimental' is not an ancestor of your current HEAD.
- If you are sure you want to delete it, run 'git branch -D experimental'.
- % git branch -D experimental
- Deleted branch experimental.
-
-=head2 Committing to blead
-
-The 'blead' branch will become the next production release of Perl.
-
-Before pushing I<any> local change to blead, it's incredibly important
-that you do a few things, lest other committers come after you with
-pitchforks and torches:
-
-=over
-
-=item *
-
-Make sure you have a good commit message. See L<perlhack/Commit
-message> for details.
-
-=item *
-
-Run the test suite. You might not think that one typo fix would break a
-test file. You'd be wrong. Here's an example of where not running the
-suite caused problems. A patch was submitted that added a couple of
-tests to an existing .t. It couldn't possibly affect anything else, so
-no need to test beyond the single affected .t, right? But, the
-submitter's email address had changed since the last of their
-submissions, and this caused other tests to fail. Running the test
-target given in the next item would have caught this problem.
-
-=item *
-
-If you don't run the full test suite, at least C<make test_porting>.
-This will run basic sanity checks. To see which sanity checks, have a
-look in F<t/porting>.
-
-=item *
-
-If you make any changes that affect miniperl or core routines that have
-different code paths for miniperl, be sure to run C<make minitest>.
-This will catch problems that even the full test suite will not catch
-because it runs a subset of tests under miniperl rather than perl.
-
-=back
-
-=head3 On merging and rebasing
-
-Simple, one-off commits pushed to the 'blead' branch should be simple
-commits that apply cleanly. In other words, you should make sure your
-work is committed against the current position of blead, so that you can
-push back to the master repository without merging.
-
-Sometimes, blead will move while you're building or testing your
-changes. When this happens, your push will be rejected with a message
-like this:
-
- To ssh://perl5.git.perl.org/perl.git
- ! [rejected] blead -> blead (non-fast-forward)
- error: failed to push some refs to 'ssh://perl5.git.perl.org/perl.git'
- To prevent you from losing history, non-fast-forward updates were rejected
- Merge the remote changes (e.g. 'git pull') before pushing again. See the
- 'Note about fast-forwards' section of 'git push --help' for details.
-
-When this happens, you can just I<rebase> your work against the new
-position of blead, like this (assuming your remote for the master
-repository is "p5p"):
-
- $ git fetch p5p
- $ git rebase p5p/blead
-
-You will see your commits being re-applied, and you will then be able to
-push safely. More information about rebasing can be found in the
-documentation for the git-rebase(1) command.
-
-For larger sets of commits that only make sense together, or that would
-benefit from a summary of the set's purpose, you should use a merge
-commit. You should perform your work on a L<topic branch|/Topic
-branches and rewriting history>, which you should regularly rebase
-against blead to ensure that your code is not broken by blead moving.
-When you have finished your work, please perform a final rebase and
-test. Linear history is something that gets lost with every
-commit on blead, but a final rebase makes the history linear
-again, making it easier for future maintainers to see what has
-happened. Rebase as follows (assuming your work was on the
-branch C<< committer/somework >>):
-
- $ git checkout committer/somework
- $ git rebase blead
-
-Then you can merge it into master like this:
-
- $ git checkout blead
- $ git merge --no-ff --no-commit committer/somework
- $ git commit -a
-
-The switches above deserve explanation. C<--no-ff> indicates that even
-if all your work can be applied linearly against blead, a merge commit
-should still be prepared. This ensures that all your work will be shown
-as a side branch, with all its commits merged into the mainstream blead
-by the merge commit.
-
-C<--no-commit> means that the merge commit will be I<prepared> but not
-I<committed>. The commit is then actually performed when you run the
-next command, which will bring up your editor to describe the commit.
-Without C<--no-commit>, the commit would be made with nearly no useful
-message, which would greatly diminish the value of the merge commit as a
-placeholder for the work's description.
-
-When describing the merge commit, explain the purpose of the branch, and
-keep in mind that this description will probably be used by the
-eventual release engineer when reviewing the next perldelta document.
-
-=head2 Committing to maintenance versions
-
-Maintenance versions should only be altered to add critical bug fixes,
-see L<perlpolicy>.
-
-To commit to a maintenance version of perl, you need to create a local
-tracking branch:
-
- % git checkout --track -b maint-5.005 origin/maint-5.005
-
-This creates a local branch named C<maint-5.005>, which tracks the
-remote branch C<origin/maint-5.005>. Then you can pull, commit, merge
-and push as before.
-
-You can also cherry-pick commits from blead and another branch, by
-using the C<git cherry-pick> command. It is recommended to use the
-B<-x> option to C<git cherry-pick> in order to record the SHA1 of the
-original commit in the new commit message.
-
-Before pushing any change to a maint version, make sure you've
-satisfied the steps in L</Committing to blead> above.
-
-=head2 Merging from a branch via GitHub
-
-While we don't encourage the submission of patches via GitHub, that
-will still happen. Here is a guide to merging patches from a GitHub
-repository.
-
- % git remote add avar git://github.com/avar/perl.git
- % git fetch avar
-
-Now you can see the differences between the branch and blead:
-
- % git diff avar/orange
-
-And you can see the commits:
-
- % git log avar/orange
-
-If you approve of a specific commit, you can cherry pick it:
-
- % git cherry-pick 0c24b290ae02b2ab3304f51d5e11e85eb3659eae
-
-Or you could just merge the whole branch if you like it all:
-
- % git merge avar/orange
-
-And then push back to the repository:
-
- % git push
-
-=head2 A note on camel and dromedary
-
-The committers have SSH access to the two servers that serve
-C<perl5.git.perl.org>. One is C<perl5.git.perl.org> itself (I<camel>),
-which is the 'master' repository. The second one is
-C<users.perl5.git.perl.org> (I<dromedary>), which can be used for
-general testing and development. Dromedary syncs the git tree from
-camel every few minutes, you should not push there. Both machines also
-have a full CPAN mirror in /srv/CPAN, please use this. To share files
-with the general public, dromedary serves your ~/public_html/ as
-C<http://users.perl5.git.perl.org/~yourlogin/>
-
-These hosts have fairly strict firewalls to the outside. Outgoing, only
-rsync, ssh and git are allowed. For http and ftp, you can use
-http://webproxy:3128 as proxy. Incoming, the firewall tries to detect
-attacks and blocks IP addresses with suspicious activity. This
-sometimes (but very rarely) has false positives and you might get
-blocked. The quickest way to get unblocked is to notify the admins.
-
-These two boxes are owned, hosted, and operated by booking.com. You can
-reach the sysadmins in #p5p on irc.perl.org or via mail to
-C<perl5-porters@perl.org>.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlglossary.pod b/Master/tlpkg/tlperl/lib/pods/perlglossary.pod
deleted file mode 100644
index 5adef04b397..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlglossary.pod
+++ /dev/null
@@ -1,3442 +0,0 @@
-=head1 NAME
-
-perlglossary - Perl Glossary
-
-=head1 DESCRIPTION
-
-A glossary of terms (technical and otherwise) used in the Perl documentation.
-Other useful sources include the Free On-Line Dictionary of Computing
-L<http://foldoc.org/>, the Jargon File
-L<http://catb.org/~esr/jargon/>, and Wikipedia L<http://www.wikipedia.org/>.
-
-=head2 A
-
-=over 4
-
-=item accessor methods
-
-A L</method> used to indirectly inspect or update an L</object>'s
-state (its L<instance variables|/instance variable>).
-
-=item actual arguments
-
-The L<scalar values|/scalar value> that you supply to a L</function>
-or L</subroutine> when you call it. For instance, when you call
-C<power("puff")>, the string C<"puff"> is the actual argument. See
-also L</argument> and L</formal arguments>.
-
-=item address operator
-
-Some languages work directly with the memory addresses of values, but
-this can be like playing with fire. Perl provides a set of asbestos
-gloves for handling all memory management. The closest to an address
-operator in Perl is the backslash operator, but it gives you a L</hard
-reference>, which is much safer than a memory address.
-
-=item algorithm
-
-A well-defined sequence of steps, clearly enough explained that even a
-computer could do them.
-
-=item alias
-
-A nickname for something, which behaves in all ways as though you'd
-used the original name instead of the nickname. Temporary aliases are
-implicitly created in the loop variable for C<foreach> loops, in the
-C<$_> variable for L<map|perlfunc/map> or L<grep|perlfunc/grep>
-operators, in C<$a> and C<$b> during L<sort|perlfunc/sort>'s
-comparison function, and in each element of C<@_> for the L</actual
-arguments> of a subroutine call. Permanent aliases are explicitly
-created in L<packages|/package> by L<importing|/import> symbols or by
-assignment to L<typeglobs|/typeglob>. Lexically scoped aliases for
-package variables are explicitly created by the L<our|perlfunc/our>
-declaration.
-
-=item alternatives
-
-A list of possible choices from which you may select only one, as in
-"Would you like door A, B, or C?" Alternatives in regular expressions
-are separated with a single vertical bar: C<|>. Alternatives in
-normal Perl expressions are separated with a double vertical bar:
-C<||>. Logical alternatives in L</Boolean> expressions are separated
-with either C<||> or C<or>.
-
-=item anonymous
-
-Used to describe a L</referent> that is not directly accessible
-through a named L</variable>. Such a referent must be indirectly
-accessible through at least one L</hard reference>. When the last
-hard reference goes away, the anonymous referent is destroyed without
-pity.
-
-=item architecture
-
-The kind of computer you're working on, where one "kind" of computer
-means all those computers sharing a compatible machine language.
-Since Perl programs are (typically) simple text files, not executable
-images, a Perl program is much less sensitive to the architecture it's
-running on than programs in other languages, such as C, that are
-compiled into machine code. See also L</platform> and L</operating
-system>.
-
-=item argument
-
-A piece of data supplied to a L<program|/executable file>,
-L</subroutine>, L</function>, or L</method> to tell it what it's
-supposed to do. Also called a "parameter".
-
-=item ARGV
-
-The name of the array containing the L</argument> L</vector> from the
-command line. If you use the empty C<< E<lt>E<gt> >> operator, L</ARGV> is
-the name of both the L</filehandle> used to traverse the arguments and
-the L</scalar> containing the name of the current input file.
-
-=item arithmetical operator
-
-A L</symbol> such as C<+> or C</> that tells Perl to do the arithmetic
-you were supposed to learn in grade school.
-
-=item array
-
-An ordered sequence of L<values|/value>, stored such that you can
-easily access any of the values using an integer L</subscript>
-that specifies the value's L</offset> in the sequence.
-
-=item array context
-
-An archaic expression for what is more correctly referred to as
-L</list context>.
-
-=item ASCII
-
-The American Standard Code for Information Interchange (a 7-bit
-character set adequate only for poorly representing English text).
-Often used loosely to describe the lowest 128 values of the various
-ISO-8859-X character sets, a bunch of mutually incompatible 8-bit
-codes sometimes described as half ASCII. See also L</Unicode>.
-
-=item assertion
-
-A component of a L</regular expression> that must be true for the
-pattern to match but does not necessarily match any characters itself.
-Often used specifically to mean a L</zero width> assertion.
-
-=item assignment
-
-An L</operator> whose assigned mission in life is to change the value
-of a L</variable>.
-
-=item assignment operator
-
-Either a regular L</assignment>, or a compound L</operator> composed
-of an ordinary assignment and some other operator, that changes the
-value of a variable in place, that is, relative to its old value. For
-example, C<$a += 2> adds C<2> to C<$a>.
-
-=item associative array
-
-See L</hash>. Please.
-
-=item associativity
-
-Determines whether you do the left L</operator> first or the right
-L</operator> first when you have "A L</operator> B L</operator> C" and
-the two operators are of the same precedence. Operators like C<+> are
-left associative, while operators like C<**> are right associative.
-See L<perlop> for a list of operators and their associativity.
-
-=item asynchronous
-
-Said of events or activities whose relative temporal ordering is
-indeterminate because too many things are going on at once. Hence, an
-asynchronous event is one you didn't know when to expect.
-
-=item atom
-
-A L</regular expression> component potentially matching a
-L</substring> containing one or more characters and treated as an
-indivisible syntactic unit by any following L</quantifier>. (Contrast
-with an L</assertion> that matches something of L</zero width> and may
-not be quantified.)
-
-=item atomic operation
-
-When Democritus gave the word "atom" to the indivisible bits of
-matter, he meant literally something that could not be cut: I<a->
-(not) + I<tomos> (cuttable). An atomic operation is an action that
-can't be interrupted, not one forbidden in a nuclear-free zone.
-
-=item attribute
-
-A new feature that allows the declaration of L<variables|/variable>
-and L<subroutines|/subroutine> with modifiers as in C<sub foo : locked
-method>. Also, another name for an L</instance variable> of an
-L</object>.
-
-=item autogeneration
-
-A feature of L</operator overloading> of L<objects|/object>, whereby
-the behavior of certain L<operators|/operator> can be reasonably
-deduced using more fundamental operators. This assumes that the
-overloaded operators will often have the same relationships as the
-regular operators. See L<perlop>.
-
-=item autoincrement
-
-To add one to something automatically, hence the name of the C<++>
-operator. To instead subtract one from something automatically is
-known as an "autodecrement".
-
-=item autoload
-
-To load on demand. (Also called "lazy" loading.) Specifically, to
-call an L<AUTOLOAD|perlsub/Autoloading> subroutine on behalf of an
-undefined subroutine.
-
-=item autosplit
-
-To split a string automatically, as the B<-a> L</switch> does when
-running under B<-p> or B<-n> in order to emulate L</awk>. (See also
-the L<AutoSplit> module, which has nothing to do with the B<-a>
-switch, but a lot to do with autoloading.)
-
-=item autovivification
-
-A Greco-Roman word meaning "to bring oneself to life". In Perl,
-storage locations (L<lvalues|/lvalue>) spontaneously generate
-themselves as needed, including the creation of any L</hard reference>
-values to point to the next level of storage. The assignment
-C<$a[5][5][5][5][5] = "quintet"> potentially creates five scalar
-storage locations, plus four references (in the first four scalar
-locations) pointing to four new anonymous arrays (to hold the last
-four scalar locations). But the point of autovivification is that you
-don't have to worry about it.
-
-=item AV
-
-Short for "array value", which refers to one of Perl's internal data
-types that holds an L</array>. The L</AV> type is a subclass of
-L</SV>.
-
-=item awk
-
-Descriptive editing term--short for "awkward". Also coincidentally
-refers to a venerable text-processing language from which Perl derived
-some of its high-level ideas.
-
-=back
-
-=head2 B
-
-=over 4
-
-=item backreference
-
-A substring L<captured|/capturing> by a subpattern within
-unadorned parentheses in a L</regex>, also referred to as a capture group. The
-sequences (C<\g1>, C<\g2>, etc.) later in the same pattern refer back to
-the corresponding subpattern in the current match. Outside the pattern,
-the numbered variables (C<$1>, C<$2>, etc.) continue to refer to these
-same values, as long as the pattern was the last successful match of
-the current dynamic scope. C<\g{-1}> can be used to refer to a group by
-relative rather than absolute position; and groups can be also be named, and
-referred to later by name rather than number. See L<perlre/"Capture groups">.
-
-=item backtracking
-
-The practice of saying, "If I had to do it all over, I'd do it
-differently," and then actually going back and doing it all over
-differently. Mathematically speaking, it's returning from an
-unsuccessful recursion on a tree of possibilities. Perl backtracks
-when it attempts to match patterns with a L</regular expression>, and
-its earlier attempts don't pan out. See L<perlre/Backtracking>.
-
-=item backward compatibility
-
-Means you can still run your old program because we didn't break any
-of the features or bugs it was relying on.
-
-=item bareword
-
-A word sufficiently ambiguous to be deemed illegal under L<use strict
-'subs'|strict/strict subs>. In the absence of that stricture, a
-bareword is treated as if quotes were around it.
-
-=item base class
-
-A generic L</object> type; that is, a L</class> from which other, more
-specific classes are derived genetically by L</inheritance>. Also
-called a "superclass" by people who respect their ancestors.
-
-=item big-endian
-
-From Swift: someone who eats eggs big end first. Also used of
-computers that store the most significant L</byte> of a word at a
-lower byte address than the least significant byte. Often considered
-superior to little-endian machines. See also L</little-endian>.
-
-=item binary
-
-Having to do with numbers represented in base 2. That means there's
-basically two numbers, 0 and 1. Also used to describe a "non-text
-file", presumably because such a file makes full use of all the binary
-bits in its bytes. With the advent of L</Unicode>, this distinction,
-already suspect, loses even more of its meaning.
-
-=item binary operator
-
-An L</operator> that takes two L<operands|/operand>.
-
-=item bind
-
-To assign a specific L</network address> to a L</socket>.
-
-=item bit
-
-An integer in the range from 0 to 1, inclusive. The smallest possible
-unit of information storage. An eighth of a L</byte> or of a dollar.
-(The term "Pieces of Eight" comes from being able to split the old
-Spanish dollar into 8 bits, each of which still counted for money.
-That's why a 25-cent piece today is still "two bits".)
-
-=item bit shift
-
-The movement of bits left or right in a computer word, which has the
-effect of multiplying or dividing by a power of 2.
-
-=item bit string
-
-A sequence of L<bits|/bit> that is actually being thought of as a
-sequence of bits, for once.
-
-=item bless
-
-In corporate life, to grant official approval to a thing, as in, "The
-VP of Engineering has blessed our WebCruncher project." Similarly in
-Perl, to grant official approval to a L</referent> so that it can
-function as an L</object>, such as a WebCruncher object. See
-L<perlfunc/"bless">.
-
-=item block
-
-What a L</process> does when it has to wait for something: "My process
-blocked waiting for the disk." As an unrelated noun, it refers to a
-large chunk of data, of a size that the L</operating system> likes to
-deal with (normally a power of two such as 512 or 8192). Typically
-refers to a chunk of data that's coming from or going to a disk file.
-
-=item BLOCK
-
-A syntactic construct consisting of a sequence of Perl
-L<statements|/statement> that is delimited by braces. The C<if> and
-C<while> statements are defined in terms of L<BLOCKs|/BLOCK>, for instance.
-Sometimes we also say "block" to mean a lexical scope; that is, a
-sequence of statements that act like a L</BLOCK>, such as within an
-L<eval|perlfunc/eval> or a file, even though the statements aren't
-delimited by braces.
-
-=item block buffering
-
-A method of making input and output efficient by passing one L</block>
-at a time. By default, Perl does block buffering to disk files. See
-L</buffer> and L</command buffering>.
-
-=item Boolean
-
-A value that is either L</true> or L</false>.
-
-=item Boolean context
-
-A special kind of L</scalar context> used in conditionals to decide
-whether the L</scalar value> returned by an expression is L</true> or
-L</false>. Does not evaluate as either a string or a number. See
-L</context>.
-
-=item breakpoint
-
-A spot in your program where you've told the debugger to stop
-L<execution|/execute> so you can poke around and see whether anything
-is wrong yet.
-
-=item broadcast
-
-To send a L</datagram> to multiple destinations simultaneously.
-
-=item BSD
-
-A psychoactive drug, popular in the 80s, probably developed at
-U. C. Berkeley or thereabouts. Similar in many ways to the
-prescription-only medication called "System V", but infinitely more
-useful. (Or, at least, more fun.) The full chemical name is
-"Berkeley Standard Distribution".
-
-=item bucket
-
-A location in a L</hash table> containing (potentially) multiple
-entries whose keys "hash" to the same hash value according to its hash
-function. (As internal policy, you don't have to worry about it,
-unless you're into internals, or policy.)
-
-=item buffer
-
-A temporary holding location for data. L<Block buffering|/block
-buffering> means that the data is passed on to its destination
-whenever the buffer is full. L<Line buffering|/line buffering> means
-that it's passed on whenever a complete line is received. L<Command
-buffering|/command buffering> means that it's passed every time you do
-a L<print|perlfunc/print> command (or equivalent). If your output is
-unbuffered, the system processes it one byte at a time without the use
-of a holding area. This can be rather inefficient.
-
-=item built-in
-
-A L</function> that is predefined in the language. Even when hidden
-by L</overriding>, you can always get at a built-in function by
-L<qualifying|/qualified> its name with the C<CORE::> pseudo-package.
-
-=item bundle
-
-A group of related modules on L</CPAN>. (Also, sometimes refers to a
-group of command-line switches grouped into one L</switch cluster>.)
-
-=item byte
-
-A piece of data worth eight L<bits|/bit> in most places.
-
-=item bytecode
-
-A pidgin-like language spoken among 'droids when they don't wish to
-reveal their orientation (see L</endian>). Named after some similar
-languages spoken (for similar reasons) between compilers and
-interpreters in the late 20th century. These languages are
-characterized by representing everything as a
-non-architecture-dependent sequence of bytes.
-
-=back
-
-=head2 C
-
-=over 4
-
-=item C
-
-A language beloved by many for its inside-out L</type> definitions,
-inscrutable L</precedence> rules, and heavy L</overloading> of the
-function-call mechanism. (Well, actually, people first switched to C
-because they found lowercase identifiers easier to read than upper.)
-Perl is written in C, so it's not surprising that Perl borrowed a few
-ideas from it.
-
-=item C preprocessor
-
-The typical C compiler's first pass, which processes lines beginning
-with C<#> for conditional compilation and macro definition and does
-various manipulations of the program text based on the current
-definitions. Also known as I<cpp>(1).
-
-=item call by reference
-
-An L</argument>-passing mechanism in which the L</formal arguments>
-refer directly to the L</actual arguments>, and the L</subroutine> can
-change the actual arguments by changing the formal arguments. That
-is, the formal argument is an L</alias> for the actual argument. See
-also L</call by value>.
-
-=item call by value
-
-An L</argument>-passing mechanism in which the L</formal arguments>
-refer to a copy of the L</actual arguments>, and the L</subroutine>
-cannot change the actual arguments by changing the formal arguments.
-See also L</call by reference>.
-
-=item callback
-
-A L</handler> that you register with some other part of your program
-in the hope that the other part of your program will L</trigger> your
-handler when some event of interest transpires.
-
-=item canonical
-
-Reduced to a standard form to facilitate comparison.
-
-=item capture buffer, capture group
-
-These two terms are synonymous:
-a L<captured substring|/capturing> by a regex subpattern.
-
-=item capturing
-
-The use of parentheses around a L</subpattern> in a L</regular
-expression> to store the matched L</substring> as a L</backreference>
-or L<capture group|/capture buffer, capture group>.
-(Captured strings are also returned as a list in L</list context>.)
-
-=item character
-
-A small integer representative of a unit of orthography.
-Historically, characters were usually stored as fixed-width integers
-(typically in a byte, or maybe two, depending on the character set),
-but with the advent of UTF-8, characters are often stored in a
-variable number of bytes depending on the size of the integer that
-represents the character. Perl manages this transparently for you,
-for the most part.
-
-=item character class
-
-A square-bracketed list of characters used in a L</regular expression>
-to indicate that any character of the set may occur at a given point.
-Loosely, any predefined set of characters so used.
-
-=item character property
-
-A predefined L</character class> matchable by the C<\p>
-L</metasymbol>. Many standard properties are defined for L</Unicode>.
-
-=item circumfix operator
-
-An L</operator> that surrounds its L</operand>, like the angle
-operator, or parentheses, or a hug.
-
-=item class
-
-A user-defined L</type>, implemented in Perl via a L</package> that
-provides (either directly or by inheritance) L<methods|/method> (that
-is, L<subroutines|/subroutine>) to handle L<instances|/instance> of
-the class (its L<objects|/object>). See also L</inheritance>.
-
-=item class method
-
-A L</method> whose L</invocant> is a L</package> name, not an
-L</object> reference. A method associated with the class as a whole.
-
-=item client
-
-In networking, a L</process> that initiates contact with a L</server>
-process in order to exchange data and perhaps receive a service.
-
-=item cloister
-
-A L</cluster> used to restrict the scope of a L</regular expression
-modifier>.
-
-=item closure
-
-An L</anonymous> subroutine that, when a reference to it is generated
-at run time, keeps track of the identities of externally visible
-L<lexical variables|/lexical variable> even after those lexical
-variables have supposedly gone out of L</scope>. They're called
-"closures" because this sort of behavior gives mathematicians a sense
-of closure.
-
-=item cluster
-
-A parenthesized L</subpattern> used to group parts of a L</regular
-expression> into a single L</atom>.
-
-=item CODE
-
-The word returned by the L<ref|perlfunc/ref> function when you apply
-it to a reference to a subroutine. See also L</CV>.
-
-=item code generator
-
-A system that writes code for you in a low-level language, such as
-code to implement the backend of a compiler. See L</program
-generator>.
-
-=item code point
-
-The position of a character in a character set encoding. The character
-C<NULL> is almost certainly at the zeroth position in all character
-sets, so its code point is 0. The code point for the C<SPACE>
-character in the ASCII character set is 0x20, or 32 decimal; in EBCDIC
-it is 0x40, or 64 decimal. The L<ord|perlfunc/ord> function returns
-the code point of a character.
-
-"code position" and "ordinal" mean the same thing as "code point".
-
-=item code subpattern
-
-A L</regular expression> subpattern whose real purpose is to execute
-some Perl code, for example, the C<(?{...})> and C<(??{...})>
-subpatterns.
-
-=item collating sequence
-
-The order into which L<characters|/character> sort. This is used by
-L</string> comparison routines to decide, for example, where in this
-glossary to put "collating sequence".
-
-=item command
-
-In L</shell> programming, the syntactic combination of a program name
-and its arguments. More loosely, anything you type to a shell (a
-command interpreter) that starts it doing something. Even more
-loosely, a Perl L</statement>, which might start with a L</label> and
-typically ends with a semicolon.
-
-=item command buffering
-
-A mechanism in Perl that lets you store up the output of each Perl
-L</command> and then flush it out as a single request to the
-L</operating system>. It's enabled by setting the C<$|>
-(C<$AUTOFLUSH>) variable to a true value. It's used when you don't
-want data sitting around not going where it's supposed to, which may
-happen because the default on a L</file> or L</pipe> is to use
-L</block buffering>.
-
-=item command name
-
-The name of the program currently executing, as typed on the command
-line. In C, the L</command> name is passed to the program as the
-first command-line argument. In Perl, it comes in separately as
-C<$0>.
-
-=item command-line arguments
-
-The L<values|/value> you supply along with a program name when you
-tell a L</shell> to execute a L</command>. These values are passed to
-a Perl program through C<@ARGV>.
-
-=item comment
-
-A remark that doesn't affect the meaning of the program. In Perl, a
-comment is introduced by a C<#> character and continues to the end of
-the line.
-
-=item compilation unit
-
-The L</file> (or L</string>, in the case of L<eval|perlfunc/eval>)
-that is currently being compiled.
-
-=item compile phase
-
-Any time before Perl starts running your main program. See also
-L</run phase>. Compile phase is mostly spent in L</compile time>, but
-may also be spent in L</run time> when C<BEGIN> blocks,
-L<use|perlfunc/use> declarations, or constant subexpressions are being
-evaluated. The startup and import code of any L<use|perlfunc/use>
-declaration is also run during compile phase.
-
-=item compile time
-
-The time when Perl is trying to make sense of your code, as opposed to
-when it thinks it knows what your code means and is merely trying to
-do what it thinks your code says to do, which is L</run time>.
-
-=item compiler
-
-Strictly speaking, a program that munches up another program and spits
-out yet another file containing the program in a "more executable"
-form, typically containing native machine instructions. The I<perl>
-program is not a compiler by this definition, but it does contain a
-kind of compiler that takes a program and turns it into a more
-executable form (L<syntax trees|/syntax tree>) within the I<perl>
-process itself, which the L</interpreter> then interprets. There are,
-however, extension L<modules|/module> to get Perl to act more like a
-"real" compiler. See L<O>.
-
-=item composer
-
-A "constructor" for a L</referent> that isn't really an L</object>,
-like an anonymous array or a hash (or a sonata, for that matter). For
-example, a pair of braces acts as a composer for a hash, and a pair of
-brackets acts as a composer for an array. See L<perlref/Making
-References>.
-
-=item concatenation
-
-The process of gluing one cat's nose to another cat's tail. Also, a
-similar operation on two L<strings|/string>.
-
-=item conditional
-
-Something "iffy". See L</Boolean context>.
-
-=item connection
-
-In telephony, the temporary electrical circuit between the caller's
-and the callee's phone. In networking, the same kind of temporary
-circuit between a L</client> and a L</server>.
-
-=item construct
-
-As a noun, a piece of syntax made up of smaller pieces. As a
-transitive verb, to create an L</object> using a L</constructor>.
-
-=item constructor
-
-Any L</class method>, instance L</method>, or L</subroutine>
-that composes, initializes, blesses, and returns an L</object>.
-Sometimes we use the term loosely to mean a L</composer>.
-
-=item context
-
-The surroundings, or environment. The context given by the
-surrounding code determines what kind of data a particular
-L</expression> is expected to return. The three primary contexts are
-L</list context>, L</scalar context>, and L</void context>. Scalar
-context is sometimes subdivided into L</Boolean context>, L</numeric
-context>, L</string context>, and L</void context>. There's also a
-"don't care" scalar context (which is dealt with in Programming Perl,
-Third Edition, Chapter 2, "Bits and Pieces" if you care).
-
-=item continuation
-
-The treatment of more than one physical L</line> as a single logical
-line. L</Makefile> lines are continued by putting a backslash before
-the L</newline>. Mail headers as defined by RFC 822 are continued by
-putting a space or tab I<after> the newline. In general, lines in
-Perl do not need any form of continuation mark, because L</whitespace>
-(including newlines) is gleefully ignored. Usually.
-
-=item core dump
-
-The corpse of a L</process>, in the form of a file left in the
-L</working directory> of the process, usually as a result of certain
-kinds of fatal error.
-
-=item CPAN
-
-The Comprehensive Perl Archive Network. (See L<perlfaq2/What modules and extensions are available for Perl? What is CPAN?>).
-
-=item cracker
-
-Someone who breaks security on computer systems. A cracker may be a
-true L</hacker> or only a L</script kiddie>.
-
-=item current package
-
-The L</package> in which the current statement is compiled. Scan
-backwards in the text of your program through the current L<lexical
-scope|/lexical scoping> or any enclosing lexical scopes till you find
-a package declaration. That's your current package name.
-
-=item current working directory
-
-See L</working directory>.
-
-=item currently selected output channel
-
-The last L</filehandle> that was designated with
-L<select|perlfunc/select>(C<FILEHANDLE>); L</STDOUT>, if no filehandle
-has been selected.
-
-=item CV
-
-An internal "code value" typedef, holding a L</subroutine>. The L</CV>
-type is a subclass of L</SV>.
-
-=back
-
-=head2 D
-
-=over 4
-
-=item dangling statement
-
-A bare, single L</statement>, without any braces, hanging off an C<if>
-or C<while> conditional. C allows them. Perl doesn't.
-
-=item data structure
-
-How your various pieces of data relate to each other and what shape
-they make when you put them all together, as in a rectangular table or
-a triangular-shaped tree.
-
-=item data type
-
-A set of possible values, together with all the operations that know
-how to deal with those values. For example, a numeric data type has a
-certain set of numbers that you can work with and various mathematical
-operations that you can do on the numbers but would make little sense
-on, say, a string such as C<"Kilroy">. Strings have their own
-operations, such as L</concatenation>. Compound types made of a
-number of smaller pieces generally have operations to compose and
-decompose them, and perhaps to rearrange them. L<Objects|/object>
-that model things in the real world often have operations that
-correspond to real activities. For instance, if you model an
-elevator, your elevator object might have an C<open_door()>
-L</method>.
-
-=item datagram
-
-A packet of data, such as a L</UDP> message, that (from the viewpoint
-of the programs involved) can be sent independently over the network.
-(In fact, all packets are sent independently at the L</IP> level, but
-L</stream> protocols such as L</TCP> hide this from your program.)
-
-=item DBM
-
-Stands for "Data Base Management" routines, a set of routines that
-emulate an L</associative array> using disk files. The routines use a
-dynamic hashing scheme to locate any entry with only two disk
-accesses. DBM files allow a Perl program to keep a persistent
-L</hash> across multiple invocations. You can L<tie|perlfunc/tie>
-your hash variables to various DBM implementations--see L<AnyDBM_File>
-and L<DB_File>.
-
-=item declaration
-
-An L</assertion> that states something exists and perhaps describes
-what it's like, without giving any commitment as to how or where
-you'll use it. A declaration is like the part of your recipe that
-says, "two cups flour, one large egg, four or five tadpoles..." See
-L</statement> for its opposite. Note that some declarations also
-function as statements. Subroutine declarations also act as
-definitions if a body is supplied.
-
-=item decrement
-
-To subtract a value from a variable, as in "decrement C<$x>" (meaning
-to remove 1 from its value) or "decrement C<$x> by 3".
-
-=item default
-
-A L</value> chosen for you if you don't supply a value of your own.
-
-=item defined
-
-Having a meaning. Perl thinks that some of the things people try to
-do are devoid of meaning, in particular, making use of variables that
-have never been given a L</value> and performing certain operations on
-data that isn't there. For example, if you try to read data past the
-end of a file, Perl will hand you back an undefined value. See also
-L</false> and L<perlfunc/defined>.
-
-=item delimiter
-
-A L</character> or L</string> that sets bounds to an arbitrarily-sized
-textual object, not to be confused with a L</separator> or
-L</terminator>. "To delimit" really just means "to surround" or "to
-enclose" (like these parentheses are doing).
-
-=item deprecated modules and features
-
-Deprecated modules and features are those which were part of a stable
-release, but later found to be subtly flawed, and which should be avoided.
-They are subject to removal and/or bug-incompatible reimplementation in
-the next major release (but they will be preserved through maintenance
-releases). Deprecation warnings are issued under B<-w> or C<use
-diagnostics>, and notices are found in L<perldelta>s, as well as various
-other PODs. Coding practices that misuse features, such as C<my $foo if
-0>, can also be deprecated.
-
-=item dereference
-
-A fancy computer science term meaning "to follow a L</reference> to
-what it points to". The "de" part of it refers to the fact that
-you're taking away one level of L</indirection>.
-
-=item derived class
-
-A L</class> that defines some of its L<methods|/method> in terms of a
-more generic class, called a L</base class>. Note that classes aren't
-classified exclusively into base classes or derived classes: a class
-can function as both a derived class and a base class simultaneously,
-which is kind of classy.
-
-=item descriptor
-
-See L</file descriptor>.
-
-=item destroy
-
-To deallocate the memory of a L</referent> (first triggering its
-C<DESTROY> method, if it has one).
-
-=item destructor
-
-A special L</method> that is called when an L</object> is thinking
-about L<destroying|/destroy> itself. A Perl program's C<DESTROY>
-method doesn't do the actual destruction; Perl just
-L<triggers|/trigger> the method in case the L</class> wants to do any
-associated cleanup.
-
-=item device
-
-A whiz-bang hardware gizmo (like a disk or tape drive or a modem or a
-joystick or a mouse) attached to your computer, that the L</operating
-system> tries to make look like a L</file> (or a bunch of files).
-Under Unix, these fake files tend to live in the I</dev> directory.
-
-=item directive
-
-A L</pod> directive. See L<perlpod>.
-
-=item directory
-
-A special file that contains other files. Some L<operating
-systems|/operating system> call these "folders", "drawers", or
-"catalogs".
-
-=item directory handle
-
-A name that represents a particular instance of opening a directory to
-read it, until you close it. See the L<opendir|perlfunc/opendir>
-function.
-
-=item dispatch
-
-To send something to its correct destination. Often used
-metaphorically to indicate a transfer of programmatic control to a
-destination selected algorithmically, often by lookup in a table of
-function L<references|/reference> or, in the case of object
-L<methods|/method>, by traversing the inheritance tree looking for the
-most specific definition for the method.
-
-=item distribution
-
-A standard, bundled release of a system of software. The default
-usage implies source code is included. If that is not the case, it
-will be called a "binary-only" distribution.
-
-=item (to be) dropped modules
-
-When Perl 5 was first released (see L<perlhist>), several modules were
-included, which have now fallen out of common use. It has been suggested
-that these modules should be removed, since the distribution became rather
-large, and the common criterion for new module additions is now limited to
-modules that help to build, test, and extend perl itself. Furthermore,
-the CPAN (which didn't exist at the time of Perl 5.0) can become the new
-home of dropped modules. Dropping modules is currently not an option, but
-further developments may clear the last barriers.
-
-=item dweomer
-
-An enchantment, illusion, phantasm, or jugglery. Said when Perl's
-magical L</dwimmer> effects don't do what you expect, but rather seem
-to be the product of arcane dweomercraft, sorcery, or wonder working.
-[From Old English]
-
-=item dwimmer
-
-DWIM is an acronym for "Do What I Mean", the principle that something
-should just do what you want it to do without an undue amount of fuss.
-A bit of code that does "dwimming" is a "dwimmer". Dwimming can
-require a great deal of behind-the-scenes magic, which (if it doesn't
-stay properly behind the scenes) is called a L</dweomer> instead.
-
-=item dynamic scoping
-
-Dynamic scoping works over a dynamic scope, making variables visible
-throughout the rest of the L</block> in which they are first used and
-in any L<subroutines|/subroutine> that are called by the rest of the
-block. Dynamically scoped variables can have their values temporarily
-changed (and implicitly restored later) by a L<local|perlfunc/local>
-operator. (Compare L</lexical scoping>.) Used more loosely to mean
-how a subroutine that is in the middle of calling another subroutine
-"contains" that subroutine at L</run time>.
-
-=back
-
-=head2 E
-
-=over 4
-
-=item eclectic
-
-Derived from many sources. Some would say I<too> many.
-
-=item element
-
-A basic building block. When you're talking about an L</array>, it's
-one of the items that make up the array.
-
-=item embedding
-
-When something is contained in something else, particularly when that
-might be considered surprising: "I've embedded a complete Perl
-interpreter in my editor!"
-
-=item empty list
-
-See </null list>.
-
-=item empty subclass test
-
-The notion that an empty L</derived class> should behave exactly like
-its L</base class>.
-
-=item en passant
-
-When you change a L</value> as it is being copied. [From French, "in
-passing", as in the exotic pawn-capturing maneuver in chess.]
-
-=item encapsulation
-
-The veil of abstraction separating the L</interface> from the
-L</implementation> (whether enforced or not), which mandates that all
-access to an L</object>'s state be through L<methods|/method> alone.
-
-=item endian
-
-See L</little-endian> and L</big-endian>.
-
-=item environment
-
-The collective set of L<environment variables|/environment variable>
-your L</process> inherits from its parent. Accessed via C<%ENV>.
-
-=item environment variable
-
-A mechanism by which some high-level agent such as a user can pass its
-preferences down to its future offspring (child L<processes|/process>,
-grandchild processes, great-grandchild processes, and so on). Each
-environment variable is a L</key>/L</value> pair, like one entry in a
-L</hash>.
-
-=item EOF
-
-End of File. Sometimes used metaphorically as the terminating string
-of a L</here document>.
-
-=item errno
-
-The error number returned by a L</syscall> when it fails. Perl refers
-to the error by the name C<$!> (or C<$OS_ERROR> if you use the English
-module).
-
-=item error
-
-See L</exception> or L</fatal error>.
-
-=item escape sequence
-
-See L</metasymbol>.
-
-=item exception
-
-A fancy term for an error. See L</fatal error>.
-
-=item exception handling
-
-The way a program responds to an error. The exception handling
-mechanism in Perl is the L<eval|perlfunc/eval> operator.
-
-=item exec
-
-To throw away the current L</process>'s program and replace it with
-another without exiting the process or relinquishing any resources
-held (apart from the old memory image).
-
-=item executable file
-
-A L</file> that is specially marked to tell the L</operating system>
-that it's okay to run this file as a program. Usually shortened to
-"executable".
-
-=item execute
-
-To run a L<program|/executable file> or L</subroutine>. (Has nothing
-to do with the L<kill|perlfunc/kill> built-in, unless you're trying to
-run a L</signal handler>.)
-
-=item execute bit
-
-The special mark that tells the operating system it can run this
-program. There are actually three execute bits under Unix, and which
-bit gets used depends on whether you own the file singularly,
-collectively, or not at all.
-
-=item exit status
-
-See L</status>.
-
-=item export
-
-To make symbols from a L</module> available for L</import> by other modules.
-
-=item expression
-
-Anything you can legally say in a spot where a L</value> is required.
-Typically composed of L<literals|/literal>, L<variables|/variable>,
-L<operators|/operator>, L<functions|/function>, and L</subroutine>
-calls, not necessarily in that order.
-
-=item extension
-
-A Perl module that also pulls in compiled C or C++ code. More
-generally, any experimental option that can be compiled into Perl,
-such as multithreading.
-
-=back
-
-=head2 F
-
-=over 4
-
-=item false
-
-In Perl, any value that would look like C<""> or C<"0"> if evaluated
-in a string context. Since undefined values evaluate to C<"">, all
-undefined values are false (including the L</null list>), but not all
-false values are undefined.
-
-=item FAQ
-
-Frequently Asked Question (although not necessarily frequently
-answered, especially if the answer appears in the Perl FAQ shipped
-standard with Perl).
-
-=item fatal error
-
-An uncaught L</exception>, which causes termination of the L</process>
-after printing a message on your L</standard error> stream. Errors
-that happen inside an L<eval|perlfunc/eval> are not fatal. Instead,
-the L<eval|perlfunc/eval> terminates after placing the exception
-message in the C<$@> (C<$EVAL_ERROR>) variable. You can try to
-provoke a fatal error with the L<die|perlfunc/die> operator (known as
-throwing or raising an exception), but this may be caught by a
-dynamically enclosing L<eval|perlfunc/eval>. If not caught, the
-L<die|perlfunc/die> becomes a fatal error.
-
-=item field
-
-A single piece of numeric or string data that is part of a longer
-L</string>, L</record>, or L</line>. Variable-width fields are usually
-split up by L<separators|/separator> (so use L<split|perlfunc/split> to
-extract the fields), while fixed-width fields are usually at fixed
-positions (so use L<unpack|perlfunc/unpack>). L<Instance
-variables|/instance variable> are also known as fields.
-
-=item FIFO
-
-First In, First Out. See also L</LIFO>. Also, a nickname for a
-L</named pipe>.
-
-=item file
-
-A named collection of data, usually stored on disk in a L</directory>
-in a L</filesystem>. Roughly like a document, if you're into office
-metaphors. In modern filesystems, you can actually give a file more
-than one name. Some files have special properties, like directories
-and devices.
-
-=item file descriptor
-
-The little number the L</operating system> uses to keep track of which
-opened L</file> you're talking about. Perl hides the file descriptor
-inside a L</standard IE<sol>O> stream and then attaches the stream to
-a L</filehandle>.
-
-=item file test operator
-
-A built-in unary operator that you use to determine whether something
-is L</true> about a file, such as C<-o $filename> to test whether
-you're the owner of the file.
-
-=item fileglob
-
-A "wildcard" match on L<filenames|/filename>. See the
-L<glob|perlfunc/glob> function.
-
-=item filehandle
-
-An identifier (not necessarily related to the real name of a file)
-that represents a particular instance of opening a file until you
-close it. If you're going to open and close several different files
-in succession, it's fine to open each of them with the same
-filehandle, so you don't have to write out separate code to process
-each file.
-
-=item filename
-
-One name for a file. This name is listed in a L</directory>, and you
-can use it in an L<open|perlfunc/open> to tell the L</operating
-system> exactly which file you want to open, and associate the file
-with a L</filehandle> which will carry the subsequent identity of that
-file in your program, until you close it.
-
-=item filesystem
-
-A set of L<directories|/directory> and L<files|/file> residing on a
-partition of the disk. Sometimes known as a "partition". You can
-change the file's name or even move a file around from directory to
-directory within a filesystem without actually moving the file itself,
-at least under Unix.
-
-=item filter
-
-A program designed to take a L</stream> of input and transform it into
-a stream of output.
-
-=item flag
-
-We tend to avoid this term because it means so many things. It may
-mean a command-line L</switch> that takes no argument
-itself (such as Perl's B<-n> and B<-p>
-flags) or, less frequently, a single-bit indicator (such as the
-C<O_CREAT> and C<O_EXCL> flags used in
-L<sysopen|perlfunc/sysopen>).
-
-=item floating point
-
-A method of storing numbers in "scientific notation", such that the
-precision of the number is independent of its magnitude (the decimal
-point "floats"). Perl does its numeric work with floating-point
-numbers (sometimes called "floats"), when it can't get away with
-using L<integers|/integer>. Floating-point numbers are mere
-approximations of real numbers.
-
-=item flush
-
-The act of emptying a L</buffer>, often before it's full.
-
-=item FMTEYEWTK
-
-Far More Than Everything You Ever Wanted To Know. An exhaustive
-treatise on one narrow topic, something of a super-L</FAQ>. See Tom
-for far more.
-
-=item fork
-
-To create a child L</process> identical to the parent process at its
-moment of conception, at least until it gets ideas of its own. A
-thread with protected memory.
-
-=item formal arguments
-
-The generic names by which a L</subroutine> knows its
-L<arguments|/argument>. In many languages, formal arguments are
-always given individual names, but in Perl, the formal arguments are
-just the elements of an array. The formal arguments to a Perl program
-are C<$ARGV[0]>, C<$ARGV[1]>, and so on. Similarly, the formal
-arguments to a Perl subroutine are C<$_[0]>, C<$_[1]>, and so on. You
-may give the arguments individual names by assigning the values to a
-L<my|perlfunc/my> list. See also L</actual arguments>.
-
-=item format
-
-A specification of how many spaces and digits and things to put
-somewhere so that whatever you're printing comes out nice and pretty.
-
-=item freely available
-
-Means you don't have to pay money to get it, but the copyright on it
-may still belong to someone else (like Larry).
-
-=item freely redistributable
-
-Means you're not in legal trouble if you give a bootleg copy of it to
-your friends and we find out about it. In fact, we'd rather you gave
-a copy to all your friends.
-
-=item freeware
-
-Historically, any software that you give away, particularly if you
-make the source code available as well. Now often called C<open
-source software>. Recently there has been a trend to use the term in
-contradistinction to L</open source software>, to refer only to free
-software released under the Free Software Foundation's GPL (General
-Public License), but this is difficult to justify etymologically.
-
-=item function
-
-Mathematically, a mapping of each of a set of input values to a
-particular output value. In computers, refers to a L</subroutine> or
-L</operator> that returns a L</value>. It may or may not have input
-values (called L<arguments|/argument>).
-
-=item funny character
-
-Someone like Larry, or one of his peculiar friends. Also refers to
-the strange prefixes that Perl requires as noun markers on its
-variables.
-
-=back
-
-=head2 G
-
-=over 4
-
-=item garbage collection
-
-A misnamed feature--it should be called, "expecting your mother to
-pick up after you". Strictly speaking, Perl doesn't do this, but it
-relies on a reference-counting mechanism to keep things tidy.
-However, we rarely speak strictly and will often refer to the
-reference-counting scheme as a form of garbage collection. (If it's
-any comfort, when your interpreter exits, a "real" garbage collector
-runs to make sure everything is cleaned up if you've been messy with
-circular references and such.)
-
-=item GID
-
-Group ID--in Unix, the numeric group ID that the L</operating system>
-uses to identify you and members of your L</group>.
-
-=item glob
-
-Strictly, the shell's C<*> character, which will match a "glob" of
-characters when you're trying to generate a list of filenames.
-Loosely, the act of using globs and similar symbols to do pattern
-matching. See also L</fileglob> and L</typeglob>.
-
-=item global
-
-Something you can see from anywhere, usually used of
-L<variables|/variable> and L<subroutines|/subroutine> that are visible
-everywhere in your program. In Perl, only certain special variables
-are truly global--most variables (and all subroutines) exist only in
-the current L</package>. Global variables can be declared with
-L<our|perlfunc/our>. See L<perlfunc/our>.
-
-=item global destruction
-
-The L</garbage collection> of globals (and the running of any
-associated object destructors) that takes place when a Perl
-L</interpreter> is being shut down. Global destruction should not be
-confused with the Apocalypse, except perhaps when it should.
-
-=item glue language
-
-A language such as Perl that is good at hooking things together that
-weren't intended to be hooked together.
-
-=item granularity
-
-The size of the pieces you're dealing with, mentally speaking.
-
-=item greedy
-
-A L</subpattern> whose L</quantifier> wants to match as many things as
-possible.
-
-=item grep
-
-Originally from the old Unix editor command for "Globally search for a
-Regular Expression and Print it", now used in the general sense of any
-kind of search, especially text searches. Perl has a built-in
-L<grep|perlfunc/grep> function that searches a list for elements
-matching any given criterion, whereas the I<grep>(1) program searches
-for lines matching a L</regular expression> in one or more files.
-
-=item group
-
-A set of users of which you are a member. In some operating systems
-(like Unix), you can give certain file access permissions to other
-members of your group.
-
-=item GV
-
-An internal "glob value" typedef, holding a L</typeglob>. The L</GV>
-type is a subclass of L</SV>.
-
-=back
-
-=head2 H
-
-=over 4
-
-=item hacker
-
-Someone who is brilliantly persistent in solving technical problems,
-whether these involve golfing, fighting orcs, or programming. Hacker
-is a neutral term, morally speaking. Good hackers are not to be
-confused with evil L<crackers|/cracker> or clueless L<script
-kiddies|/script kiddie>. If you confuse them, we will presume that
-you are either evil or clueless.
-
-=item handler
-
-A L</subroutine> or L</method> that is called by Perl when your
-program needs to respond to some internal event, such as a L</signal>,
-or an encounter with an operator subject to L</operator overloading>.
-See also L</callback>.
-
-=item hard reference
-
-A L</scalar> L</value> containing the actual address of a
-L</referent>, such that the referent's L</reference> count accounts
-for it. (Some hard references are held internally, such as the
-implicit reference from one of a L</typeglob>'s variable slots to its
-corresponding referent.) A hard reference is different from a
-L</symbolic reference>.
-
-=item hash
-
-An unordered association of L</key>/L</value> pairs, stored such that
-you can easily use a string L</key> to look up its associated data
-L</value>. This glossary is like a hash, where the word to be defined
-is the key, and the definition is the value. A hash is also sometimes
-septisyllabically called an "associative array", which is a pretty
-good reason for simply calling it a "hash" instead. A hash can optionally
-be L<restricted|/restricted hash> to a fixed set of keys.
-
-=item hash table
-
-A data structure used internally by Perl for implementing associative
-arrays (hashes) efficiently. See also L</bucket>.
-
-=item header file
-
-A file containing certain required definitions that you must include
-"ahead" of the rest of your program to do certain obscure operations.
-A C header file has a I<.h> extension. Perl doesn't really have
-header files, though historically Perl has sometimes used translated
-I<.h> files with a I<.ph> extension. See L<perlfunc/require>.
-(Header files have been superseded by the L</module> mechanism.)
-
-=item here document
-
-So called because of a similar construct in L<shells|/shell> that
-pretends that the L<lines|/line> following the L</command> are a
-separate L</file> to be fed to the command, up to some terminating
-string. In Perl, however, it's just a fancy form of quoting.
-
-=item hexadecimal
-
-A number in base 16, "hex" for short. The digits for 10 through 16
-are customarily represented by the letters C<a> through C<f>.
-Hexadecimal constants in Perl start with C<0x>. See also
-L<perlfunc/hex>.
-
-=item home directory
-
-The directory you are put into when you log in. On a Unix system, the
-name is often placed into C<$ENV{HOME}> or C<$ENV{LOGDIR}> by
-I<login>, but you can also find it with C<(getpwuid($E<lt>))[7]>.
-(Some platforms do not have a concept of a home directory.)
-
-=item host
-
-The computer on which a program or other data resides.
-
-=item hubris
-
-Excessive pride, the sort of thing Zeus zaps you for. Also the
-quality that makes you write (and maintain) programs that other people
-won't want to say bad things about. Hence, the third great virtue of
-a programmer. See also L</laziness> and L</impatience>.
-
-=item HV
-
-Short for a "hash value" typedef, which holds Perl's internal
-representation of a hash. The L</HV> type is a subclass of L</SV>.
-
-=back
-
-=head2 I
-
-=over 4
-
-=item identifier
-
-A legally formed name for most anything in which a computer program
-might be interested. Many languages (including Perl) allow
-identifiers that start with a letter and contain letters and digits.
-Perl also counts the underscore character as a valid letter. (Perl
-also has more complicated names, such as L</qualified> names.)
-
-=item impatience
-
-The anger you feel when the computer is being lazy. This makes you
-write programs that don't just react to your needs, but actually
-anticipate them. Or at least that pretend to. Hence, the second
-great virtue of a programmer. See also L</laziness> and L</hubris>.
-
-=item implementation
-
-How a piece of code actually goes about doing its job. Users of the
-code should not count on implementation details staying the same
-unless they are part of the published L</interface>.
-
-=item import
-
-To gain access to symbols that are exported from another module. See
-L<perlfunc/use>.
-
-=item increment
-
-To increase the value of something by 1 (or by some other number, if
-so specified).
-
-=item indexing
-
-In olden days, the act of looking up a L</key> in an actual index
-(such as a phone book), but now merely the act of using any kind of
-key or position to find the corresponding L</value>, even if no index
-is involved. Things have degenerated to the point that Perl's
-L<index|perlfunc/index> function merely locates the position (index)
-of one string in another.
-
-=item indirect filehandle
-
-An L</expression> that evaluates to something that can be used as a
-L</filehandle>: a L</string> (filehandle name), a L</typeglob>, a
-typeglob L</reference>, or a low-level L</IO> object.
-
-=item indirect object
-
-In English grammar, a short noun phrase between a verb and its direct
-object indicating the beneficiary or recipient of the action. In
-Perl, C<print STDOUT "$foo\n";> can be understood as "verb
-indirect-object object" where L</STDOUT> is the recipient of the
-L<print|perlfunc/print> action, and C<"$foo"> is the object being
-printed. Similarly, when invoking a L</method>, you might place the
-invocant between the method and its arguments:
-
- $gollum = new Pathetic::Creature "Smeagol";
- give $gollum "Fisssssh!";
- give $gollum "Precious!";
-
-In modern Perl, calling methods this way is often considered bad practice and
-to be avoided.
-
-=item indirect object slot
-
-The syntactic position falling between a method call and its arguments
-when using the indirect object invocation syntax. (The slot is
-distinguished by the absence of a comma between it and the next
-argument.) L</STDERR> is in the indirect object slot here:
-
- print STDERR "Awake! Awake! Fear, Fire,
- Foes! Awake!\n";
-
-=item indirection
-
-If something in a program isn't the value you're looking for but
-indicates where the value is, that's indirection. This can be done
-with either L<symbolic references|/symbolic reference> or L<hard
-references|/hard reference>.
-
-=item infix
-
-An L</operator> that comes in between its L<operands|/operand>, such
-as multiplication in C<24 * 7>.
-
-=item inheritance
-
-What you get from your ancestors, genetically or otherwise. If you
-happen to be a L</class>, your ancestors are called L<base
-classes|/base class> and your descendants are called L<derived
-classes|/derived class>. See L</single inheritance> and L</multiple
-inheritance>.
-
-=item instance
-
-Short for "an instance of a class", meaning an L</object> of that L</class>.
-
-=item instance variable
-
-An L</attribute> of an L</object>; data stored with the particular
-object rather than with the class as a whole.
-
-=item integer
-
-A number with no fractional (decimal) part. A counting number, like
-1, 2, 3, and so on, but including 0 and the negatives.
-
-=item interface
-
-The services a piece of code promises to provide forever, in contrast to
-its L</implementation>, which it should feel free to change whenever it
-likes.
-
-=item interpolation
-
-The insertion of a scalar or list value somewhere in the middle of
-another value, such that it appears to have been there all along. In
-Perl, variable interpolation happens in double-quoted strings and
-patterns, and list interpolation occurs when constructing the list of
-values to pass to a list operator or other such construct that takes a
-L</LIST>.
-
-=item interpreter
-
-Strictly speaking, a program that reads a second program and does what
-the second program says directly without turning the program into a
-different form first, which is what L<compilers|/compiler> do. Perl
-is not an interpreter by this definition, because it contains a kind
-of compiler that takes a program and turns it into a more executable
-form (L<syntax trees|/syntax tree>) within the I<perl> process itself,
-which the Perl L</run time> system then interprets.
-
-=item invocant
-
-The agent on whose behalf a L</method> is invoked. In a L</class>
-method, the invocant is a package name. In an L</instance> method,
-the invocant is an object reference.
-
-=item invocation
-
-The act of calling up a deity, daemon, program, method, subroutine, or
-function to get it do what you think it's supposed to do. We usually
-"call" subroutines but "invoke" methods, since it sounds cooler.
-
-=item I/O
-
-Input from, or output to, a L</file> or L</device>.
-
-=item IO
-
-An internal I/O object. Can also mean L</indirect object>.
-
-=item IP
-
-Internet Protocol, or Intellectual Property.
-
-=item IPC
-
-Interprocess Communication.
-
-=item is-a
-
-A relationship between two L<objects|/object> in which one object is
-considered to be a more specific version of the other, generic object:
-"A camel is a mammal." Since the generic object really only exists in
-a Platonic sense, we usually add a little abstraction to the notion of
-objects and think of the relationship as being between a generic
-L</base class> and a specific L</derived class>. Oddly enough,
-Platonic classes don't always have Platonic relationships--see
-L</inheritance>.
-
-=item iteration
-
-Doing something repeatedly.
-
-=item iterator
-
-A special programming gizmo that keeps track of where you are in
-something that you're trying to iterate over. The C<foreach> loop in
-Perl contains an iterator; so does a hash, allowing you to
-L<each|perlfunc/each> through it.
-
-=item IV
-
-The integer four, not to be confused with six, Tom's favorite editor.
-IV also means an internal Integer Value of the type a L</scalar> can
-hold, not to be confused with an L</NV>.
-
-=back
-
-=head2 J
-
-=over 4
-
-=item JAPH
-
-"Just Another Perl Hacker," a clever but cryptic bit of Perl code that
-when executed, evaluates to that string. Often used to illustrate a
-particular Perl feature, and something of an ongoing Obfuscated Perl
-Contest seen in Usenix signatures.
-
-=back
-
-=head2 K
-
-=over 4
-
-=item key
-
-The string index to a L</hash>, used to look up the L</value>
-associated with that key.
-
-=item keyword
-
-See L</reserved words>.
-
-=back
-
-=head2 L
-
-=over 4
-
-=item label
-
-A name you give to a L</statement> so that you can talk about that
-statement elsewhere in the program.
-
-=item laziness
-
-The quality that makes you go to great effort to reduce overall energy
-expenditure. It makes you write labor-saving programs that other
-people will find useful, and document what you wrote so you don't have
-to answer so many questions about it. Hence, the first great virtue
-of a programmer. Also hence, this book. See also L</impatience> and
-L</hubris>.
-
-=item left shift
-
-A L</bit shift> that multiplies the number by some power of 2.
-
-=item leftmost longest
-
-The preference of the L</regular expression> engine to match the
-leftmost occurrence of a L</pattern>, then given a position at which a
-match will occur, the preference for the longest match (presuming the
-use of a L</greedy> quantifier). See L<perlre> for I<much> more on
-this subject.
-
-=item lexeme
-
-Fancy term for a L</token>.
-
-=item lexer
-
-Fancy term for a L</tokener>.
-
-=item lexical analysis
-
-Fancy term for L</tokenizing>.
-
-=item lexical scoping
-
-Looking at your I<Oxford English Dictionary> through a microscope.
-(Also known as L</static scoping>, because dictionaries don't change
-very fast.) Similarly, looking at variables stored in a private
-dictionary (namespace) for each scope, which are visible only from
-their point of declaration down to the end of the lexical scope in
-which they are declared. --Syn. L</static scoping>.
---Ant. L</dynamic scoping>.
-
-=item lexical variable
-
-A L</variable> subject to L</lexical scoping>, declared by
-L<my|perlfunc/my>. Often just called a "lexical". (The
-L<our|perlfunc/our> declaration declares a lexically scoped name for a
-global variable, which is not itself a lexical variable.)
-
-=item library
-
-Generally, a collection of procedures. In ancient days, referred to a
-collection of subroutines in a I<.pl> file. In modern times, refers
-more often to the entire collection of Perl L<modules|/module> on your
-system.
-
-=item LIFO
-
-Last In, First Out. See also L</FIFO>. A LIFO is usually called a
-L</stack>.
-
-=item line
-
-In Unix, a sequence of zero or more non-newline characters terminated
-with a L</newline> character. On non-Unix machines, this is emulated
-by the C library even if the underlying L</operating system> has
-different ideas.
-
-=item line buffering
-
-Used by a L</standard IE<sol>O> output stream that flushes its
-L</buffer> after every L</newline>. Many standard I/O libraries
-automatically set up line buffering on output that is going to the
-terminal.
-
-=item line number
-
-The number of lines read previous to this one, plus 1. Perl keeps a
-separate line number for each source or input file it opens. The
-current source file's line number is represented by C<__LINE__>. The
-current input line number (for the file that was most recently read
-via C<< E<lt>FHE<gt> >>) is represented by the C<$.>
-(C<$INPUT_LINE_NUMBER>) variable. Many error messages report both
-values, if available.
-
-=item link
-
-Used as a noun, a name in a L</directory>, representing a L</file>. A
-given file can have multiple links to it. It's like having the same
-phone number listed in the phone directory under different names. As
-a verb, to resolve a partially compiled file's unresolved symbols into
-a (nearly) executable image. Linking can generally be static or
-dynamic, which has nothing to do with static or dynamic scoping.
-
-=item LIST
-
-A syntactic construct representing a comma-separated list of
-expressions, evaluated to produce a L</list value>. Each
-L</expression> in a L</LIST> is evaluated in L</list context> and
-interpolated into the list value.
-
-=item list
-
-An ordered set of scalar values.
-
-=item list context
-
-The situation in which an L</expression> is expected by its
-surroundings (the code calling it) to return a list of values rather
-than a single value. Functions that want a L</LIST> of arguments tell
-those arguments that they should produce a list value. See also
-L</context>.
-
-=item list operator
-
-An L</operator> that does something with a list of values, such as
-L<join|perlfunc/join> or L<grep|perlfunc/grep>. Usually used for
-named built-in operators (such as L<print|perlfunc/print>,
-L<unlink|perlfunc/unlink>, and L<system|perlfunc/system>) that do not
-require parentheses around their L</argument> list.
-
-=item list value
-
-An unnamed list of temporary scalar values that may be passed around
-within a program from any list-generating function to any function or
-construct that provides a L</list context>.
-
-=item literal
-
-A token in a programming language such as a number or L</string> that
-gives you an actual L</value> instead of merely representing possible
-values as a L</variable> does.
-
-=item little-endian
-
-From Swift: someone who eats eggs little end first. Also used of
-computers that store the least significant L</byte> of a word at a
-lower byte address than the most significant byte. Often considered
-superior to big-endian machines. See also L</big-endian>.
-
-=item local
-
-Not meaning the same thing everywhere. A global variable in Perl can
-be localized inside a L<dynamic scope|/dynamic scoping> via the
-L<local|perlfunc/local> operator.
-
-=item logical operator
-
-Symbols representing the concepts "and", "or", "xor", and "not".
-
-=item lookahead
-
-An L</assertion> that peeks at the string to the right of the current
-match location.
-
-=item lookbehind
-
-An L</assertion> that peeks at the string to the left of the current
-match location.
-
-=item loop
-
-A construct that performs something repeatedly, like a roller coaster.
-
-=item loop control statement
-
-Any statement within the body of a loop that can make a loop
-prematurely stop looping or skip an L</iteration>. Generally you
-shouldn't try this on roller coasters.
-
-=item loop label
-
-A kind of key or name attached to a loop (or roller coaster) so that
-loop control statements can talk about which loop they want to
-control.
-
-=item lvaluable
-
-Able to serve as an L</lvalue>.
-
-=item lvalue
-
-Term used by language lawyers for a storage location you can assign a
-new L</value> to, such as a L</variable> or an element of an
-L</array>. The "l" is short for "left", as in the left side of an
-assignment, a typical place for lvalues. An L</lvaluable> function or
-expression is one to which a value may be assigned, as in C<pos($x) =
-10>.
-
-=item lvalue modifier
-
-An adjectival pseudofunction that warps the meaning of an L</lvalue>
-in some declarative fashion. Currently there are three lvalue
-modifiers: L<my|perlfunc/my>, L<our|perlfunc/our>, and
-L<local|perlfunc/local>.
-
-=back
-
-=head2 M
-
-=over 4
-
-=item magic
-
-Technically speaking, any extra semantics attached to a variable such
-as C<$!>, C<$0>, C<%ENV>, or C<%SIG>, or to any tied variable.
-Magical things happen when you diddle those variables.
-
-=item magical increment
-
-An L</increment> operator that knows how to bump up alphabetics as
-well as numbers.
-
-=item magical variables
-
-Special variables that have side effects when you access them or
-assign to them. For example, in Perl, changing elements of the
-C<%ENV> array also changes the corresponding environment variables
-that subprocesses will use. Reading the C<$!> variable gives you the
-current system error number or message.
-
-=item Makefile
-
-A file that controls the compilation of a program. Perl programs
-don't usually need a L</Makefile> because the Perl compiler has plenty
-of self-control.
-
-=item man
-
-The Unix program that displays online documentation (manual pages) for
-you.
-
-=item manpage
-
-A "page" from the manuals, typically accessed via the I<man>(1)
-command. A manpage contains a SYNOPSIS, a DESCRIPTION, a list of
-BUGS, and so on, and is typically longer than a page. There are
-manpages documenting L<commands|/command>, L<syscalls|/syscall>,
-L</library> L<functions|/function>, L<devices|/device>,
-L<protocols|/protocol>, L<files|/file>, and such. In this book, we
-call any piece of standard Perl documentation (like I<perlop> or
-I<perldelta>) a manpage, no matter what format it's installed in on
-your system.
-
-=item matching
-
-See L</pattern matching>.
-
-=item member data
-
-See L</instance variable>.
-
-=item memory
-
-This always means your main memory, not your disk. Clouding the issue
-is the fact that your machine may implement L</virtual> memory; that
-is, it will pretend that it has more memory than it really does, and
-it'll use disk space to hold inactive bits. This can make it seem
-like you have a little more memory than you really do, but it's not a
-substitute for real memory. The best thing that can be said about
-virtual memory is that it lets your performance degrade gradually
-rather than suddenly when you run out of real memory. But your
-program can die when you run out of virtual memory too, if you haven't
-thrashed your disk to death first.
-
-=item metacharacter
-
-A L</character> that is I<not> supposed to be treated normally. Which
-characters are to be treated specially as metacharacters varies
-greatly from context to context. Your L</shell> will have certain
-metacharacters, double-quoted Perl L<strings|/string> have other
-metacharacters, and L</regular expression> patterns have all the
-double-quote metacharacters plus some extra ones of their own.
-
-=item metasymbol
-
-Something we'd call a L</metacharacter> except that it's a sequence of
-more than one character. Generally, the first character in the
-sequence must be a true metacharacter to get the other characters in
-the metasymbol to misbehave along with it.
-
-=item method
-
-A kind of action that an L</object> can take if you tell it to. See
-L<perlobj>.
-
-=item minimalism
-
-The belief that "small is beautiful." Paradoxically, if you say
-something in a small language, it turns out big, and if you say it in
-a big language, it turns out small. Go figure.
-
-=item mode
-
-In the context of the L<stat(2)> syscall, refers to the field holding
-the L</permission bits> and the type of the L</file>.
-
-=item modifier
-
-See L</statement modifier>, L</regular expression modifier>, and
-L</lvalue modifier>, not necessarily in that order.
-
-=item module
-
-A L</file> that defines a L</package> of (almost) the same name, which
-can either L</export> symbols or function as an L</object> class. (A
-module's main I<.pm> file may also load in other files in support of
-the module.) See the L<use|perlfunc/use> built-in.
-
-=item modulus
-
-An integer divisor when you're interested in the remainder instead of
-the quotient.
-
-=item monger
-
-Short for Perl Monger, a purveyor of Perl.
-
-=item mortal
-
-A temporary value scheduled to die when the current statement
-finishes.
-
-=item multidimensional array
-
-An array with multiple subscripts for finding a single element. Perl
-implements these using L<references|/reference>--see L<perllol> and
-L<perldsc>.
-
-=item multiple inheritance
-
-The features you got from your mother and father, mixed together
-unpredictably. (See also L</inheritance>, and L</single
-inheritance>.) In computer languages (including Perl), the notion
-that a given class may have multiple direct ancestors or L<base
-classes|/base class>.
-
-=back
-
-=head2 N
-
-=over 4
-
-=item named pipe
-
-A L</pipe> with a name embedded in the L</filesystem> so that it can
-be accessed by two unrelated L<processes|/process>.
-
-=item namespace
-
-A domain of names. You needn't worry about whether the names in one
-such domain have been used in another. See L</package>.
-
-=item network address
-
-The most important attribute of a socket, like your telephone's
-telephone number. Typically an IP address. See also L</port>.
-
-=item newline
-
-A single character that represents the end of a line, with the ASCII
-value of 012 octal under Unix (but 015 on a Mac), and represented by
-C<\n> in Perl strings. For Windows machines writing text files, and
-for certain physical devices like terminals, the single newline gets
-automatically translated by your C library into a line feed and a
-carriage return, but normally, no translation is done.
-
-=item NFS
-
-Network File System, which allows you to mount a remote filesystem as
-if it were local.
-
-=item null character
-
-A character with the ASCII value of zero. It's used by C to terminate
-strings, but Perl allows strings to contain a null.
-
-=item null list
-
-A valueless value represented in Perl by C<()>. It is not really a
-L</LIST>, but an expression that yields C<undef> in L</scalar context> and
-a L</list value> with zero elements in L</list context>.
-
-=item null string
-
-A L</string> containing no characters, not to be confused with a
-string containing a L</null character>, which has a positive length
-and is L</true>.
-
-=item numeric context
-
-The situation in which an expression is expected by its surroundings
-(the code calling it) to return a number. See also L</context> and
-L</string context>.
-
-=item NV
-
-Short for Nevada, no part of which will ever be confused with
-civilization. NV also means an internal floating-point Numeric Value
-of the type a L</scalar> can hold, not to be confused with an L</IV>.
-
-=item nybble
-
-Half a L</byte>, equivalent to one L</hexadecimal> digit, and worth
-four L<bits|/bit>.
-
-=back
-
-=head2 O
-
-=over 4
-
-=item object
-
-An L</instance> of a L</class>. Something that "knows" what
-user-defined type (class) it is, and what it can do because of what
-class it is. Your program can request an object to do things, but the
-object gets to decide whether it wants to do them or not. Some
-objects are more accommodating than others.
-
-=item octal
-
-A number in base 8. Only the digits 0 through 7 are allowed. Octal
-constants in Perl start with 0, as in 013. See also the
-L<oct|perlfunc/oct> function.
-
-=item offset
-
-How many things you have to skip over when moving from the beginning
-of a string or array to a specific position within it. Thus, the
-minimum offset is zero, not one, because you don't skip anything to
-get to the first item.
-
-=item one-liner
-
-An entire computer program crammed into one line of text.
-
-=item open source software
-
-Programs for which the source code is freely available and freely
-redistributable, with no commercial strings attached. For a more
-detailed definition, see L<http://www.opensource.org/osd.html>.
-
-=item operand
-
-An L</expression> that yields a L</value> that an L</operator>
-operates on. See also L</precedence>.
-
-=item operating system
-
-A special program that runs on the bare machine and hides the gory
-details of managing L<processes|/process> and L<devices|/device>.
-Usually used in a looser sense to indicate a particular culture of
-programming. The loose sense can be used at varying levels of
-specificity. At one extreme, you might say that all versions of Unix
-and Unix-lookalikes are the same operating system (upsetting many
-people, especially lawyers and other advocates). At the other
-extreme, you could say this particular version of this particular
-vendor's operating system is different from any other version of this
-or any other vendor's operating system. Perl is much more portable
-across operating systems than many other languages. See also
-L</architecture> and L</platform>.
-
-=item operator
-
-A gizmo that transforms some number of input values to some number of
-output values, often built into a language with a special syntax or
-symbol. A given operator may have specific expectations about what
-L<types|/type> of data you give as its arguments
-(L<operands|/operand>) and what type of data you want back from it.
-
-=item operator overloading
-
-A kind of L</overloading> that you can do on built-in
-L<operators|/operator> to make them work on L<objects|/object> as if
-the objects were ordinary scalar values, but with the actual semantics
-supplied by the object class. This is set up with the L<overload>
-L</pragma>.
-
-=item options
-
-See either L<switches|/switch> or L</regular expression modifier>.
-
-=item ordinal
-
-Another name for L</code point>
-
-=item overloading
-
-Giving additional meanings to a symbol or construct. Actually, all
-languages do overloading to one extent or another, since people are
-good at figuring out things from L</context>.
-
-=item overriding
-
-Hiding or invalidating some other definition of the same name. (Not
-to be confused with L</overloading>, which adds definitions that must
-be disambiguated some other way.) To confuse the issue further, we use
-the word with two overloaded definitions: to describe how you can
-define your own L</subroutine> to hide a built-in L</function> of the
-same name (see L<perlsub/Overriding Built-in Functions>) and to
-describe how you can define a replacement L</method> in a L</derived
-class> to hide a L</base class>'s method of the same name (see
-L<perlobj>).
-
-=item owner
-
-The one user (apart from the superuser) who has absolute control over
-a L</file>. A file may also have a L</group> of users who may
-exercise joint ownership if the real owner permits it. See
-L</permission bits>.
-
-=back
-
-=head2 P
-
-=over 4
-
-=item package
-
-A L</namespace> for global L<variables|/variable>,
-L<subroutines|/subroutine>, and the like, such that they can be kept
-separate from like-named L<symbols|/symbol> in other namespaces. In a
-sense, only the package is global, since the symbols in the package's
-symbol table are only accessible from code compiled outside the
-package by naming the package. But in another sense, all package
-symbols are also globals--they're just well-organized globals.
-
-=item pad
-
-Short for L</scratchpad>.
-
-=item parameter
-
-See L</argument>.
-
-=item parent class
-
-See L</base class>.
-
-=item parse tree
-
-See L</syntax tree>.
-
-=item parsing
-
-The subtle but sometimes brutal art of attempting to turn your
-possibly malformed program into a valid L</syntax tree>.
-
-=item patch
-
-To fix by applying one, as it were. In the realm of hackerdom, a
-listing of the differences between two versions of a program as might
-be applied by the I<patch>(1) program when you want to fix a bug or
-upgrade your old version.
-
-=item PATH
-
-The list of L<directories|/directory> the system searches to find a
-program you want to L</execute>. The list is stored as one of your
-L<environment variables|/environment variable>, accessible in Perl as
-C<$ENV{PATH}>.
-
-=item pathname
-
-A fully qualified filename such as I</usr/bin/perl>. Sometimes
-confused with L</PATH>.
-
-=item pattern
-
-A template used in L</pattern matching>.
-
-=item pattern matching
-
-Taking a pattern, usually a L</regular expression>, and trying the
-pattern various ways on a string to see whether there's any way to
-make it fit. Often used to pick interesting tidbits out of a file.
-
-=item permission bits
-
-Bits that the L</owner> of a file sets or unsets to allow or disallow
-access to other people. These flag bits are part of the L</mode> word
-returned by the L<stat|perlfunc/stat> built-in when you ask about a
-file. On Unix systems, you can check the I<ls>(1) manpage for more
-information.
-
-=item Pern
-
-What you get when you do C<Perl++> twice. Doing it only once will
-curl your hair. You have to increment it eight times to shampoo your
-hair. Lather, rinse, iterate.
-
-=item pipe
-
-A direct L</connection> that carries the output of one L</process> to
-the input of another without an intermediate temporary file. Once the
-pipe is set up, the two processes in question can read and write as if
-they were talking to a normal file, with some caveats.
-
-=item pipeline
-
-A series of L<processes|/process> all in a row, linked by
-L<pipes|/pipe>, where each passes its output stream to the next.
-
-=item platform
-
-The entire hardware and software context in which a program runs. A
- program written in a platform-dependent language might break if you
-change any of: machine, operating system, libraries, compiler, or
-system configuration. The I<perl> interpreter has to be compiled
-differently for each platform because it is implemented in C, but
-programs written in the Perl language are largely
-platform-independent.
-
-=item pod
-
-The markup used to embed documentation into your Perl code. See
-L<perlpod>.
-
-=item pointer
-
-A L</variable> in a language like C that contains the exact memory
-location of some other item. Perl handles pointers internally so you
-don't have to worry about them. Instead, you just use symbolic
-pointers in the form of L<keys|/key> and L</variable> names, or L<hard
-references|/hard reference>, which aren't pointers (but act like
-pointers and do in fact contain pointers).
-
-=item polymorphism
-
-The notion that you can tell an L</object> to do something generic,
-and the object will interpret the command in different ways depending
-on its type. [E<lt>Gk many shapes]
-
-=item port
-
-The part of the address of a TCP or UDP socket that directs packets to
-the correct process after finding the right machine, something like
-the phone extension you give when you reach the company operator.
-Also, the result of converting code to run on a different platform
-than originally intended, or the verb denoting this conversion.
-
-=item portable
-
-Once upon a time, C code compilable under both BSD and SysV. In
-general, code that can be easily converted to run on another
-L</platform>, where "easily" can be defined however you like, and
-usually is. Anything may be considered portable if you try hard
-enough. See I<mobile home> or I<London Bridge>.
-
-=item porter
-
-Someone who "carries" software from one L</platform> to another.
-Porting programs written in platform-dependent languages such as C can
-be difficult work, but porting programs like Perl is very much worth
-the agony.
-
-=item POSIX
-
-The Portable Operating System Interface specification.
-
-=item postfix
-
-An L</operator> that follows its L</operand>, as in C<$x++>.
-
-=item pp
-
-An internal shorthand for a "push-pop" code, that is, C code
-implementing Perl's stack machine.
-
-=item pragma
-
-A standard module whose practical hints and suggestions are received
-(and possibly ignored) at compile time. Pragmas are named in all
-lowercase.
-
-=item precedence
-
-The rules of conduct that, in the absence of other guidance, determine
-what should happen first. For example, in the absence of parentheses,
-you always do multiplication before addition.
-
-=item prefix
-
-An L</operator> that precedes its L</operand>, as in C<++$x>.
-
-=item preprocessing
-
-What some helper L</process> did to transform the incoming data into a
-form more suitable for the current process. Often done with an
-incoming L</pipe>. See also L</C preprocessor>.
-
-=item procedure
-
-A L</subroutine>.
-
-=item process
-
-An instance of a running program. Under multitasking systems like
-Unix, two or more separate processes could be running the same program
-independently at the same time--in fact, the L<fork|perlfunc/fork>
-function is designed to bring about this happy state of affairs.
-Under other operating systems, processes are sometimes called
-"threads", "tasks", or "jobs", often with slight nuances in meaning.
-
-=item program generator
-
-A system that algorithmically writes code for you in a high-level
-language. See also L</code generator>.
-
-=item progressive matching
-
-L<Pattern matching|/pattern matching> that picks up where it left off before.
-
-=item property
-
-See either L</instance variable> or L</character property>.
-
-=item protocol
-
-In networking, an agreed-upon way of sending messages back and forth
-so that neither correspondent will get too confused.
-
-=item prototype
-
-An optional part of a L</subroutine> declaration telling the Perl
-compiler how many and what flavor of arguments may be passed as
-L</actual arguments>, so that you can write subroutine calls that
-parse much like built-in functions. (Or don't parse, as the case may
-be.)
-
-=item pseudofunction
-
-A construct that sometimes looks like a function but really isn't.
-Usually reserved for L</lvalue> modifiers like L<my|perlfunc/my>, for
-L</context> modifiers like L<scalar|perlfunc/scalar>, and for the
-pick-your-own-quotes constructs, C<q//>, C<qq//>, C<qx//>, C<qw//>,
-C<qr//>, C<m//>, C<s///>, C<y///>, and C<tr///>.
-
-=item pseudohash
-
-A reference to an array whose initial element happens to hold a
-reference to a hash. You can treat a pseudohash reference as either
-an array reference or a hash reference.
-
-=item pseudoliteral
-
-An L</operator> that looks something like a L</literal>, such as the
-output-grabbing operator, C<`>I<C<command>>C<`>.
-
-=item public domain
-
-Something not owned by anybody. Perl is copyrighted and is thus
-I<not> in the public domain--it's just L</freely available> and
-L</freely redistributable>.
-
-=item pumpkin
-
-A notional "baton" handed around the Perl community indicating who is
-the lead integrator in some arena of development.
-
-=item pumpking
-
-A L</pumpkin> holder, the person in charge of pumping the pump, or at
-least priming it. Must be willing to play the part of the Great
-Pumpkin now and then.
-
-=item PV
-
-A "pointer value", which is Perl Internals Talk for a C<char*>.
-
-=back
-
-=head2 Q
-
-=over 4
-
-=item qualified
-
-Possessing a complete name. The symbol C<$Ent::moot> is qualified;
-C<$moot> is unqualified. A fully qualified filename is specified from
-the top-level directory.
-
-=item quantifier
-
-A component of a L</regular expression> specifying how many times the
-foregoing L</atom> may occur.
-
-=back
-
-=head2 R
-
-=over 4
-
-=item readable
-
-With respect to files, one that has the proper permission bit set to
-let you access the file. With respect to computer programs, one
-that's written well enough that someone has a chance of figuring out
-what it's trying to do.
-
-=item reaping
-
-The last rites performed by a parent L</process> on behalf of a
-deceased child process so that it doesn't remain a L</zombie>. See
-the L<wait|perlfunc/wait> and L<waitpid|perlfunc/waitpid> function
-calls.
-
-=item record
-
-A set of related data values in a L</file> or L</stream>, often
-associated with a unique L</key> field. In Unix, often commensurate
-with a L</line>, or a blank-line-terminated set of lines (a
-"paragraph"). Each line of the I</etc/passwd> file is a record, keyed
-on login name, containing information about that user.
-
-=item recursion
-
-The art of defining something (at least partly) in terms of itself,
-which is a naughty no-no in dictionaries but often works out okay in
-computer programs if you're careful not to recurse forever, which is
-like an infinite loop with more spectacular failure modes.
-
-=item reference
-
-Where you look to find a pointer to information somewhere else. (See
-L</indirection>.) References come in two flavors, L<symbolic
-references|/symbolic reference> and L<hard references|/hard
-reference>.
-
-=item referent
-
-Whatever a reference refers to, which may or may not have a name.
-Common types of referents include scalars, arrays, hashes, and
-subroutines.
-
-=item regex
-
-See L</regular expression>.
-
-=item regular expression
-
-A single entity with various interpretations, like an elephant. To a
-computer scientist, it's a grammar for a little language in which some
-strings are legal and others aren't. To normal people, it's a pattern
-you can use to find what you're looking for when it varies from case
-to case. Perl's regular expressions are far from regular in the
-theoretical sense, but in regular use they work quite well. Here's a
-regular expression: C</Oh s.*t./>. This will match strings like "C<Oh
-say can you see by the dawn's early light>" and "C<Oh sit!>". See
-L<perlre>.
-
-=item regular expression modifier
-
-An option on a pattern or substitution, such as C</i> to render the
-pattern case insensitive. See also L</cloister>.
-
-=item regular file
-
-A L</file> that's not a L</directory>, a L</device>, a named L</pipe>
-or L</socket>, or a L</symbolic link>. Perl uses the C<-f> file test
-operator to identify regular files. Sometimes called a "plain" file.
-
-=item relational operator
-
-An L</operator> that says whether a particular ordering relationship
-is L</true> about a pair of L<operands|/operand>. Perl has both
-numeric and string relational operators. See L</collating sequence>.
-
-=item reserved words
-
-A word with a specific, built-in meaning to a L</compiler>, such as
-C<if> or L<delete|perlfunc/delete>. In many languages (not Perl),
-it's illegal to use reserved words to name anything else. (Which is
-why they're reserved, after all.) In Perl, you just can't use them to
-name L<labels|/label> or L<filehandles|/filehandle>. Also called
-"keywords".
-
-=item restricted hash
-
-A L</hash> with a closed set of allowed keys. See L<Hash::Util>.
-
-=item return value
-
-The L</value> produced by a L</subroutine> or L</expression> when
-evaluated. In Perl, a return value may be either a L</list> or a
-L</scalar>.
-
-=item RFC
-
-Request For Comment, which despite the timid connotations is the name
-of a series of important standards documents.
-
-=item right shift
-
-A L</bit shift> that divides a number by some power of 2.
-
-=item root
-
-The superuser (UID == 0). Also, the top-level directory of the
-filesystem.
-
-=item RTFM
-
-What you are told when someone thinks you should Read The Fine Manual.
-
-=item run phase
-
-Any time after Perl starts running your main program. See also
-L</compile phase>. Run phase is mostly spent in L</run time> but may
-also be spent in L</compile time> when L<require|perlfunc/require>,
-L<do|perlfunc/do> C<FILE>, or L<eval|perlfunc/eval> C<STRING>
-operators are executed or when a substitution uses the C</ee>
-modifier.
-
-=item run time
-
-The time when Perl is actually doing what your code says to do, as
-opposed to the earlier period of time when it was trying to figure out
-whether what you said made any sense whatsoever, which is L</compile
-time>.
-
-=item run-time pattern
-
-A pattern that contains one or more variables to be interpolated
-before parsing the pattern as a L</regular expression>, and that
-therefore cannot be analyzed at compile time, but must be re-analyzed
-each time the pattern match operator is evaluated. Run-time patterns
-are useful but expensive.
-
-=item RV
-
-A recreational vehicle, not to be confused with vehicular recreation.
-RV also means an internal Reference Value of the type a L</scalar> can
-hold. See also L</IV> and L</NV> if you're not confused yet.
-
-=item rvalue
-
-A L</value> that you might find on the right side of an
-L</assignment>. See also L</lvalue>.
-
-=back
-
-=head2 S
-
-=over 4
-
-=item scalar
-
-A simple, singular value; a number, L</string>, or L</reference>.
-
-=item scalar context
-
-The situation in which an L</expression> is expected by its
-surroundings (the code calling it) to return a single L</value> rather
-than a L</list> of values. See also L</context> and L</list context>.
-A scalar context sometimes imposes additional constraints on the
-return value--see L</string context> and L</numeric context>.
-Sometimes we talk about a L</Boolean context> inside conditionals, but
-this imposes no additional constraints, since any scalar value,
-whether numeric or L</string>, is already true or false.
-
-=item scalar literal
-
-A number or quoted L</string>--an actual L</value> in the text of your
-program, as opposed to a L</variable>.
-
-=item scalar value
-
-A value that happens to be a L</scalar> as opposed to a L</list>.
-
-=item scalar variable
-
-A L</variable> prefixed with C<$> that holds a single value.
-
-=item scope
-
-How far away you can see a variable from, looking through one. Perl
-has two visibility mechanisms: it does L</dynamic scoping> of
-L<local|perlfunc/local> L<variables|/variable>, meaning that the rest
-of the L</block>, and any L<subroutines|/subroutine> that are called
-by the rest of the block, can see the variables that are local to the
-block. Perl does L</lexical scoping> of L<my|perlfunc/my> variables,
-meaning that the rest of the block can see the variable, but other
-subroutines called by the block I<cannot> see the variable.
-
-=item scratchpad
-
-The area in which a particular invocation of a particular file or
-subroutine keeps some of its temporary values, including any lexically
-scoped variables.
-
-=item script
-
-A text L</file> that is a program intended to be L<executed|/execute>
-directly rather than L<compiled|/compiler> to another form of file
-before execution. Also, in the context of L</Unicode>, a writing
-system for a particular language or group of languages, such as Greek,
-Bengali, or Klingon.
-
-=item script kiddie
-
-A L</cracker> who is not a L</hacker>, but knows just enough to run
-canned scripts. A cargo-cult programmer.
-
-=item sed
-
-A venerable Stream EDitor from which Perl derives some of its ideas.
-
-=item semaphore
-
-A fancy kind of interlock that prevents multiple L<threads|/thread> or
-L<processes|/process> from using up the same resources simultaneously.
-
-=item separator
-
-A L</character> or L</string> that keeps two surrounding strings from
-being confused with each other. The L<split|perlfunc/split> function
-works on separators. Not to be confused with L<delimiters|/delimiter>
-or L<terminators|/terminator>. The "or" in the previous sentence
-separated the two alternatives.
-
-=item serialization
-
-Putting a fancy L</data structure> into linear order so that it can be
-stored as a L</string> in a disk file or database or sent through a
-L</pipe>. Also called marshalling.
-
-=item server
-
-In networking, a L</process> that either advertises a L</service> or
-just hangs around at a known location and waits for L<clients|/client>
-who need service to get in touch with it.
-
-=item service
-
-Something you do for someone else to make them happy, like giving them
-the time of day (or of their life). On some machines, well-known
-services are listed by the L<getservent|perlfunc/getservent> function.
-
-=item setgid
-
-Same as L</setuid>, only having to do with giving away L</group>
-privileges.
-
-=item setuid
-
-Said of a program that runs with the privileges of its L</owner>
-rather than (as is usually the case) the privileges of whoever is
-running it. Also describes the bit in the mode word (L</permission
-bits>) that controls the feature. This bit must be explicitly set by
-the owner to enable this feature, and the program must be carefully
-written not to give away more privileges than it ought to.
-
-=item shared memory
-
-A piece of L</memory> accessible by two different
-L<processes|/process> who otherwise would not see each other's memory.
-
-=item shebang
-
-Irish for the whole McGillicuddy. In Perl culture, a portmanteau of
-"sharp" and "bang", meaning the C<#!> sequence that tells the system
-where to find the interpreter.
-
-=item shell
-
-A L</command>-line L</interpreter>. The program that interactively
-gives you a prompt, accepts one or more L<lines|/line> of input, and
-executes the programs you mentioned, feeding each of them their proper
-L<arguments|/argument> and input data. Shells can also execute
-scripts containing such commands. Under Unix, typical shells include
-the Bourne shell (I</bin/sh>), the C shell (I</bin/csh>), and the Korn
-shell (I</bin/ksh>). Perl is not strictly a shell because it's not
-interactive (although Perl programs can be interactive).
-
-=item side effects
-
-Something extra that happens when you evaluate an L</expression>.
-Nowadays it can refer to almost anything. For example, evaluating a
-simple assignment statement typically has the "side effect" of
-assigning a value to a variable. (And you thought assigning the value
-was your primary intent in the first place!) Likewise, assigning a
-value to the special variable C<$|> (C<$AUTOFLUSH>) has the side
-effect of forcing a flush after every L<write|perlfunc/write> or
-L<print|perlfunc/print> on the currently selected filehandle.
-
-=item signal
-
-A bolt out of the blue; that is, an event triggered by the
-L</operating system>, probably when you're least expecting it.
-
-=item signal handler
-
-A L</subroutine> that, instead of being content to be called in the
-normal fashion, sits around waiting for a bolt out of the blue before
-it will deign to L</execute>. Under Perl, bolts out of the blue are
-called signals, and you send them with the L<kill|perlfunc/kill>
-built-in. See L<perlvar/%SIG> and L<perlipc/Signals>.
-
-=item single inheritance
-
-The features you got from your mother, if she told you that you don't
-have a father. (See also L</inheritance> and L</multiple
-inheritance>.) In computer languages, the notion that
-L<classes|/class> reproduce asexually so that a given class can only
-have one direct ancestor or L</base class>. Perl supplies no such
-restriction, though you may certainly program Perl that way if you
-like.
-
-=item slice
-
-A selection of any number of L<elements|/element> from a L</list>,
-L</array>, or L</hash>.
-
-=item slurp
-
-To read an entire L</file> into a L</string> in one operation.
-
-=item socket
-
-An endpoint for network communication among multiple
-L<processes|/process> that works much like a telephone or a post
-office box. The most important thing about a socket is its L</network
-address> (like a phone number). Different kinds of sockets have
-different kinds of addresses--some look like filenames, and some
-don't.
-
-=item soft reference
-
-See L</symbolic reference>.
-
-=item source filter
-
-A special kind of L</module> that does L</preprocessing> on your
-script just before it gets to the L</tokener>.
-
-=item stack
-
-A device you can put things on the top of, and later take them back
-off in the opposite order in which you put them on. See L</LIFO>.
-
-=item standard
-
-Included in the official Perl distribution, as in a standard module, a
-standard tool, or a standard Perl L</manpage>.
-
-=item standard error
-
-The default output L</stream> for nasty remarks that don't belong in
-L</standard output>. Represented within a Perl program by the
-L</filehandle> L</STDERR>. You can use this stream explicitly, but the
-L<die|perlfunc/die> and L<warn|perlfunc/warn> built-ins write to your
-standard error stream automatically.
-
-=item standard I/O
-
-A standard C library for doing L<buffered|/buffer> input and output to
-the L</operating system>. (The "standard" of standard I/O is only
-marginally related to the "standard" of standard input and output.)
-In general, Perl relies on whatever implementation of standard I/O a
-given operating system supplies, so the buffering characteristics of a
-Perl program on one machine may not exactly match those on another
-machine. Normally this only influences efficiency, not semantics. If
-your standard I/O package is doing block buffering and you want it to
-L</flush> the buffer more often, just set the C<$|> variable to a true
-value.
-
-=item standard input
-
-The default input L</stream> for your program, which if possible
-shouldn't care where its data is coming from. Represented within a
-Perl program by the L</filehandle> L</STDIN>.
-
-=item standard output
-
-The default output L</stream> for your program, which if possible
-shouldn't care where its data is going. Represented within a Perl
-program by the L</filehandle> L</STDOUT>.
-
-=item stat structure
-
-A special internal spot in which Perl keeps the information about the
-last L</file> on which you requested information.
-
-=item statement
-
-A L</command> to the computer about what to do next, like a step in a
-recipe: "Add marmalade to batter and mix until mixed." A statement is
-distinguished from a L</declaration>, which doesn't tell the computer
-to do anything, but just to learn something.
-
-=item statement modifier
-
-A L</conditional> or L</loop> that you put after the L</statement>
-instead of before, if you know what we mean.
-
-=item static
-
-Varying slowly compared to something else. (Unfortunately, everything
-is relatively stable compared to something else, except for certain
-elementary particles, and we're not so sure about them.) In
-computers, where things are supposed to vary rapidly, "static" has a
-derogatory connotation, indicating a slightly dysfunctional
-L</variable>, L</subroutine>, or L</method>. In Perl culture, the
-word is politely avoided.
-
-=item static method
-
-No such thing. See L</class method>.
-
-=item static scoping
-
-No such thing. See L</lexical scoping>.
-
-=item static variable
-
-No such thing. Just use a L</lexical variable> in a scope larger than
-your L</subroutine>.
-
-=item status
-
-The L</value> returned to the parent L</process> when one of its child
-processes dies. This value is placed in the special variable C<$?>.
-Its upper eight L<bits|/bit> are the exit status of the defunct
-process, and its lower eight bits identify the signal (if any) that
-the process died from. On Unix systems, this status value is the same
-as the status word returned by I<wait>(2). See L<perlfunc/system>.
-
-=item STDERR
-
-See L</standard error>.
-
-=item STDIN
-
-See L</standard input>.
-
-=item STDIO
-
-See L</standard IE<sol>O>.
-
-=item STDOUT
-
-See L</standard output>.
-
-=item stream
-
-A flow of data into or out of a process as a steady sequence of bytes
-or characters, without the appearance of being broken up into packets.
-This is a kind of L</interface>--the underlying L</implementation> may
-well break your data up into separate packets for delivery, but this
-is hidden from you.
-
-=item string
-
-A sequence of characters such as "He said !@#*&%@#*?!". A string does
-not have to be entirely printable.
-
-=item string context
-
-The situation in which an expression is expected by its surroundings
-(the code calling it) to return a L</string>. See also L</context>
-and L</numeric context>.
-
-=item stringification
-
-The process of producing a L</string> representation of an abstract
-object.
-
-=item struct
-
-C keyword introducing a structure definition or name.
-
-=item structure
-
-See L</data structure>.
-
-=item subclass
-
-See L</derived class>.
-
-=item subpattern
-
-A component of a L</regular expression> pattern.
-
-=item subroutine
-
-A named or otherwise accessible piece of program that can be invoked
-from elsewhere in the program in order to accomplish some sub-goal of
-the program. A subroutine is often parameterized to accomplish
-different but related things depending on its input
-L<arguments|/argument>. If the subroutine returns a meaningful
-L</value>, it is also called a L</function>.
-
-=item subscript
-
-A L</value> that indicates the position of a particular L</array>
-L</element> in an array.
-
-=item substitution
-
-Changing parts of a string via the C<s///> operator. (We avoid use of
-this term to mean L</variable interpolation>.)
-
-=item substring
-
-A portion of a L</string>, starting at a certain L</character>
-position (L</offset>) and proceeding for a certain number of
-characters.
-
-=item superclass
-
-See L</base class>.
-
-=item superuser
-
-The person whom the L</operating system> will let do almost anything.
-Typically your system administrator or someone pretending to be your
-system administrator. On Unix systems, the L</root> user. On Windows
-systems, usually the Administrator user.
-
-=item SV
-
-Short for "scalar value". But within the Perl interpreter every
-L</referent> is treated as a member of a class derived from SV, in an
-object-oriented sort of way. Every L</value> inside Perl is passed
-around as a C language C<SV*> pointer. The SV L</struct> knows its
-own "referent type", and the code is smart enough (we hope) not to try
-to call a L</hash> function on a L</subroutine>.
-
-=item switch
-
-An option you give on a command line to influence the way your program
-works, usually introduced with a minus sign. The word is also used as
-a nickname for a L</switch statement>.
-
-=item switch cluster
-
-The combination of multiple command-line switches (e.g., B<-a -b -c>)
-into one switch (e.g., B<-abc>). Any switch with an additional
-L</argument> must be the last switch in a cluster.
-
-=item switch statement
-
-A program technique that lets you evaluate an L</expression> and then,
-based on the value of the expression, do a multiway branch to the
-appropriate piece of code for that value. Also called a "case
-structure", named after the similar Pascal construct. See
-See L<perlsyn/Basic BLOCKs>.
-
-=item symbol
-
-Generally, any L</token> or L</metasymbol>. Often used more
-specifically to mean the sort of name you might find in a L</symbol
-table>.
-
-=item symbol table
-
-Where a L</compiler> remembers symbols. A program like Perl must
-somehow remember all the names of all the L<variables|/variable>,
-L<filehandles|/filehandle>, and L<subroutines|/subroutine> you've
-used. It does this by placing the names in a symbol table, which is
-implemented in Perl using a L</hash table>. There is a separate
-symbol table for each L</package> to give each package its own
-L</namespace>.
-
-=item symbolic debugger
-
-A program that lets you step through the L<execution|/execute> of your
-program, stopping or printing things out here and there to see whether
-anything has gone wrong, and if so, what. The "symbolic" part just
-means that you can talk to the debugger using the same symbols with
-which your program is written.
-
-=item symbolic link
-
-An alternate filename that points to the real L</filename>, which in
-turn points to the real L</file>. Whenever the L</operating system>
-is trying to parse a L</pathname> containing a symbolic link, it
-merely substitutes the new name and continues parsing.
-
-=item symbolic reference
-
-A variable whose value is the name of another variable or subroutine.
-By L<dereferencing|/dereference> the first variable, you can get at
-the second one. Symbolic references are illegal under L<use strict
-'refs'|strict/strict refs>.
-
-=item synchronous
-
-Programming in which the orderly sequence of events can be determined;
-that is, when things happen one after the other, not at the same time.
-
-=item syntactic sugar
-
-An alternative way of writing something more easily; a shortcut.
-
-=item syntax
-
-From Greek, "with-arrangement". How things (particularly symbols) are
-put together with each other.
-
-=item syntax tree
-
-An internal representation of your program wherein lower-level
-L<constructs|/construct> dangle off the higher-level constructs
-enclosing them.
-
-=item syscall
-
-A L</function> call directly to the L</operating system>. Many of the
-important subroutines and functions you use aren't direct system
-calls, but are built up in one or more layers above the system call
-level. In general, Perl programmers don't need to worry about the
-distinction. However, if you do happen to know which Perl functions
-are really syscalls, you can predict which of these will set the C<$!>
-(C<$ERRNO>) variable on failure. Unfortunately, beginning programmers
-often confusingly employ the term "system call" to mean what happens
-when you call the Perl L<system|perlfunc/system> function, which
-actually involves many syscalls. To avoid any confusion, we nearly
-always use say "syscall" for something you could call indirectly via
-Perl's L<syscall|perlfunc/syscall> function, and never for something
-you would call with Perl's L<system|perlfunc/system> function.
-
-=back
-
-=head2 T
-
-=over 4
-
-=item tainted
-
-Said of data derived from the grubby hands of a user and thus unsafe
-for a secure program to rely on. Perl does taint checks if you run a
-L</setuid> (or L</setgid>) program, or if you use the B<-T> switch.
-
-=item TCP
-
-Short for Transmission Control Protocol. A protocol wrapped around
-the Internet Protocol to make an unreliable packet transmission
-mechanism appear to the application program to be a reliable
-L</stream> of bytes. (Usually.)
-
-=item term
-
-Short for a "terminal", that is, a leaf node of a L</syntax tree>. A
-thing that functions grammatically as an L</operand> for the operators
-in an expression.
-
-=item terminator
-
-A L</character> or L</string> that marks the end of another string.
-The C<$/> variable contains the string that terminates a
-L<readline|perlfunc/readline> operation, which L<chomp|perlfunc/chomp>
-deletes from the end. Not to be confused with
-L<delimiters|/delimiter> or L<separators|/separator>. The period at
-the end of this sentence is a terminator.
-
-=item ternary
-
-An L</operator> taking three L<operands|/operand>. Sometimes
-pronounced L</trinary>.
-
-=item text
-
-A L</string> or L</file> containing primarily printable characters.
-
-=item thread
-
-Like a forked process, but without L</fork>'s inherent memory
-protection. A thread is lighter weight than a full process, in that a
-process could have multiple threads running around in it, all fighting
-over the same process's memory space unless steps are taken to protect
-threads from each other. See L<threads>.
-
-=item tie
-
-The bond between a magical variable and its implementation class. See
-L<perlfunc/tie> and L<perltie>.
-
-=item TMTOWTDI
-
-There's More Than One Way To Do It, the Perl Motto. The notion that
-there can be more than one valid path to solving a programming problem
-in context. (This doesn't mean that more ways are always better or
-that all possible paths are equally desirable--just that there need
-not be One True Way.) Pronounced TimToady.
-
-=item token
-
-A morpheme in a programming language, the smallest unit of text with
-semantic significance.
-
-=item tokener
-
-A module that breaks a program text into a sequence of
-L<tokens|/token> for later analysis by a parser.
-
-=item tokenizing
-
-Splitting up a program text into L<tokens|/token>. Also known as
-"lexing", in which case you get "lexemes" instead of tokens.
-
-=item toolbox approach
-
-The notion that, with a complete set of simple tools that work well
-together, you can build almost anything you want. Which is fine if
-you're assembling a tricycle, but if you're building a defranishizing
-comboflux regurgalator, you really want your own machine shop in which
-to build special tools. Perl is sort of a machine shop.
-
-=item transliterate
-
-To turn one string representation into another by mapping each
-character of the source string to its corresponding character in the
-result string. See
-L<perlop/trE<sol>SEARCHLISTE<sol>REPLACEMENTLISTE<sol>cdsr>.
-
-=item trigger
-
-An event that causes a L</handler> to be run.
-
-=item trinary
-
-Not a stellar system with three stars, but an L</operator> taking
-three L<operands|/operand>. Sometimes pronounced L</ternary>.
-
-=item troff
-
-A venerable typesetting language from which Perl derives the name of
-its C<$%> variable and which is secretly used in the production of
-Camel books.
-
-=item true
-
-Any scalar value that doesn't evaluate to 0 or C<"">.
-
-=item truncating
-
-Emptying a file of existing contents, either automatically when
-opening a file for writing or explicitly via the
-L<truncate|perlfunc/truncate> function.
-
-=item type
-
-See L</data type> and L</class>.
-
-=item type casting
-
-Converting data from one type to another. C permits this. Perl does
-not need it. Nor want it.
-
-=item typed lexical
-
-A L</lexical variable> that is declared with a L</class> type: C<my
-Pony $bill>.
-
-=item typedef
-
-A type definition in the C language.
-
-=item typeglob
-
-Use of a single identifier, prefixed with C<*>. For example, C<*name>
-stands for any or all of C<$name>, C<@name>, C<%name>, C<&name>, or
-just C<name>. How you use it determines whether it is interpreted as
-all or only one of them. See L<perldata/Typeglobs and Filehandles>.
-
-=item typemap
-
-A description of how C types may be transformed to and from Perl types
-within an L</extension> module written in L</XS>.
-
-=back
-
-=head2 U
-
-=over 4
-
-=item UDP
-
-User Datagram Protocol, the typical way to send L<datagrams|/datagram>
-over the Internet.
-
-=item UID
-
-A user ID. Often used in the context of L</file> or L</process>
-ownership.
-
-=item umask
-
-A mask of those L</permission bits> that should be forced off when
-creating files or directories, in order to establish a policy of whom
-you'll ordinarily deny access to. See the L<umask|perlfunc/umask>
-function.
-
-=item unary operator
-
-An operator with only one L</operand>, like C<!> or
-L<chdir|perlfunc/chdir>. Unary operators are usually prefix
-operators; that is, they precede their operand. The C<++> and C<-->
-operators can be either prefix or postfix. (Their position I<does>
-change their meanings.)
-
-=item Unicode
-
-A character set comprising all the major character sets of the world,
-more or less. See L<perlunicode> and L<http://www.unicode.org>.
-
-=item Unix
-
-A very large and constantly evolving language with several alternative
-and largely incompatible syntaxes, in which anyone can define anything
-any way they choose, and usually do. Speakers of this language think
-it's easy to learn because it's so easily twisted to one's own ends,
-but dialectical differences make tribal intercommunication nearly
-impossible, and travelers are often reduced to a pidgin-like subset of
-the language. To be universally understood, a Unix shell programmer
-must spend years of study in the art. Many have abandoned this
-discipline and now communicate via an Esperanto-like language called
-Perl.
-
-In ancient times, Unix was also used to refer to some code that a
-couple of people at Bell Labs wrote to make use of a PDP-7 computer
-that wasn't doing much of anything else at the time.
-
-=back
-
-=head2 V
-
-=over 4
-
-=item value
-
-An actual piece of data, in contrast to all the variables, references,
-keys, indexes, operators, and whatnot that you need to access the
-value.
-
-=item variable
-
-A named storage location that can hold any of various kinds of
-L</value>, as your program sees fit.
-
-=item variable interpolation
-
-The L</interpolation> of a scalar or array variable into a string.
-
-=item variadic
-
-Said of a L</function> that happily receives an indeterminate number
-of L</actual arguments>.
-
-=item vector
-
-Mathematical jargon for a list of L<scalar values|/scalar value>.
-
-=item virtual
-
-Providing the appearance of something without the reality, as in:
-virtual memory is not real memory. (See also L</memory>.) The
-opposite of "virtual" is "transparent", which means providing the
-reality of something without the appearance, as in: Perl handles the
-variable-length UTF-8 character encoding transparently.
-
-=item void context
-
-A form of L</scalar context> in which an L</expression> is not
-expected to return any L</value> at all and is evaluated for its
-L</side effects> alone.
-
-=item v-string
-
-A "version" or "vector" L</string> specified with a C<v> followed by a
-series of decimal integers in dot notation, for instance,
-C<v1.20.300.4000>. Each number turns into a L</character> with the
-specified ordinal value. (The C<v> is optional when there are at
-least three integers.)
-
-=back
-
-=head2 W
-
-=over 4
-
-=item warning
-
-A message printed to the L</STDERR> stream to the effect that something
-might be wrong but isn't worth blowing up over. See L<perlfunc/warn>
-and the L<warnings> pragma.
-
-=item watch expression
-
-An expression which, when its value changes, causes a breakpoint in
-the Perl debugger.
-
-=item whitespace
-
-A L</character> that moves your cursor but doesn't otherwise put
-anything on your screen. Typically refers to any of: space, tab, line
-feed, carriage return, or form feed.
-
-=item word
-
-In normal "computerese", the piece of data of the size most
-efficiently handled by your computer, typically 32 bits or so, give or
-take a few powers of 2. In Perl culture, it more often refers to an
-alphanumeric L</identifier> (including underscores), or to a string of
-nonwhitespace L<characters|/character> bounded by whitespace or string
-boundaries.
-
-=item working directory
-
-Your current L</directory>, from which relative pathnames are
-interpreted by the L</operating system>. The operating system knows
-your current directory because you told it with a
-L<chdir|perlfunc/chdir> or because you started out in the place where
-your parent L</process> was when you were born.
-
-=item wrapper
-
-A program or subroutine that runs some other program or subroutine for
-you, modifying some of its input or output to better suit your
-purposes.
-
-=item WYSIWYG
-
-What You See Is What You Get. Usually used when something that
-appears on the screen matches how it will eventually look, like Perl's
-L<format|perlfunc/format> declarations. Also used to mean the
-opposite of magic because everything works exactly as it appears, as
-in the three-argument form of L<open|perlfunc/open>.
-
-=back
-
-=head2 X
-
-=over 4
-
-=item XS
-
-A language to extend Perl with L<C> and C++. XS is an interface description
-file format used to create an extension interface between
-Perl and C code (or a C library) which one wishes to use with Perl.
-See L<perlxs> for the exact explanation or read the L<perlxstut>
-tutorial.
-
-=item XSUB
-
-An external L</subroutine> defined in L</XS>.
-
-=back
-
-=head2 Y
-
-=over 4
-
-=item yacc
-
-Yet Another Compiler Compiler. A parser generator without which Perl
-probably would not have existed. See the file I<perly.y> in the Perl
-source distribution.
-
-=back
-
-=head2 Z
-
-=over 4
-
-=item zero width
-
-A subpattern L</assertion> matching the L</null string> between
-L<characters|/character>.
-
-=item zombie
-
-A process that has died (exited) but whose parent has not yet received
-proper notification of its demise by virtue of having called
-L<wait|perlfunc/wait> or L<waitpid|perlfunc/waitpid>. If you
-L<fork|perlfunc/fork>, you must clean up after your child processes
-when they exit, or else the process table will fill up and your system
-administrator will Not Be Happy with you.
-
-=back
-
-=head1 AUTHOR AND COPYRIGHT
-
-Based on the Glossary of Programming Perl, Third Edition,
-by Larry Wall, Tom Christiansen & Jon Orwant.
-Copyright (c) 2000, 1996, 1991 O'Reilly Media, Inc.
-This document may be distributed under the same terms as Perl itself.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlgpl.pod b/Master/tlpkg/tlperl/lib/pods/perlgpl.pod
deleted file mode 100644
index 82a8f5a9dd1..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlgpl.pod
+++ /dev/null
@@ -1,288 +0,0 @@
-
-=head1 NAME
-
-perlgpl - the GNU General Public License, version 1
-
-=head1 SYNOPSIS
-
- You can refer to this document in Pod via "L<perlgpl>"
- Or you can see this document by entering "perldoc perlgpl"
-
-=head1 DESCRIPTION
-
-Perl is free software; you can redistribute it and/or modify
-it under the terms of either:
-
- a) the GNU General Public License as published by the Free
- Software Foundation; either version 1, or (at your option) any
- later version, or
-
- b) the "Artistic License" which comes with this Kit.
-
-This is the B<"GNU General Public License, version 1">.
-It's here so that modules, programs, etc., that want to declare
-this as their distribution license can link to it.
-
-For the Perl Artistic License, see L<perlartistic>.
-
-=cut
-
-# Because the following document's language disallows "changing"
-# it, we haven't gone thru and prettied it up with =item's or
-# anything. It's good enough the way it is.
-
-=head1 GNU GENERAL PUBLIC LICENSE
-
- GNU GENERAL PUBLIC LICENSE
- Version 1, February 1989
-
- Copyright (C) 1989 Free Software Foundation, Inc.
- 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
- Preamble
-
- The license agreements of most software companies try to keep users
- at the mercy of those companies. By contrast, our General Public
- License is intended to guarantee your freedom to share and change free
- software--to make sure the software is free for all its users. The
- General Public License applies to the Free Software Foundation's
- software and to any other program whose authors commit to using it.
- You can use it for your programs, too.
-
- When we speak of free software, we are referring to freedom, not
- price. Specifically, the General Public License is designed to make
- sure that you have the freedom to give away or sell copies of free
- software, that you receive source code or can get it if you want it,
- that you can change the software or use pieces of it in new free
- programs; and that you know you can do these things.
-
- To protect your rights, we need to make restrictions that forbid
- anyone to deny you these rights or to ask you to surrender the rights.
- These restrictions translate to certain responsibilities for you if you
- distribute copies of the software, or if you modify it.
-
- For example, if you distribute copies of a such a program, whether
- gratis or for a fee, you must give the recipients all the rights that
- you have. You must make sure that they, too, receive or can get the
- source code. And you must tell them their rights.
-
- We protect your rights with two steps: (1) copyright the software, and
- (2) offer you this license which gives you legal permission to copy,
- distribute and/or modify the software.
-
- Also, for each author's protection and ours, we want to make certain
- that everyone understands that there is no warranty for this free
- software. If the software is modified by someone else and passed on, we
- want its recipients to know that what they have is not the original, so
- that any problems introduced by others will not reflect on the original
- authors' reputations.
-
- The precise terms and conditions for copying, distribution and
- modification follow.
-
- GNU GENERAL PUBLIC LICENSE
- TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
- 0. This License Agreement applies to any program or other work which
- contains a notice placed by the copyright holder saying it may be
- distributed under the terms of this General Public License. The
- "Program", below, refers to any such program or work, and a "work based
- on the Program" means either the Program or any work containing the
- Program or a portion of it, either verbatim or with modifications. Each
- licensee is addressed as "you".
-
- 1. You may copy and distribute verbatim copies of the Program's source
- code as you receive it, in any medium, provided that you conspicuously and
- appropriately publish on each copy an appropriate copyright notice and
- disclaimer of warranty; keep intact all the notices that refer to this
- General Public License and to the absence of any warranty; and give any
- other recipients of the Program a copy of this General Public License
- along with the Program. You may charge a fee for the physical act of
- transferring a copy.
-
- 2. You may modify your copy or copies of the Program or any portion of
- it, and copy and distribute such modifications under the terms of Paragraph
- 1 above, provided that you also do the following:
-
- a) cause the modified files to carry prominent notices stating that
- you changed the files and the date of any change; and
-
- b) cause the whole of any work that you distribute or publish, that
- in whole or in part contains the Program or any part thereof, either
- with or without modifications, to be licensed at no charge to all
- third parties under the terms of this General Public License (except
- that you may choose to grant warranty protection to some or all
- third parties, at your option).
-
- c) If the modified program normally reads commands interactively when
- run, you must cause it, when started running for such interactive use
- in the simplest and most usual way, to print or display an
- announcement including an appropriate copyright notice and a notice
- that there is no warranty (or else, saying that you provide a
- warranty) and that users may redistribute the program under these
- conditions, and telling the user how to view a copy of this General
- Public License.
-
- d) You may charge a fee for the physical act of transferring a
- copy, and you may at your option offer warranty protection in
- exchange for a fee.
-
- Mere aggregation of another independent work with the Program (or its
- derivative) on a volume of a storage or distribution medium does not bring
- the other work under the scope of these terms.
-
- 3. You may copy and distribute the Program (or a portion or derivative of
- it, under Paragraph 2) in object code or executable form under the terms of
- Paragraphs 1 and 2 above provided that you also do one of the following:
-
- a) accompany it with the complete corresponding machine-readable
- source code, which must be distributed under the terms of
- Paragraphs 1 and 2 above; or,
-
- b) accompany it with a written offer, valid for at least three
- years, to give any third party free (except for a nominal charge
- for the cost of distribution) a complete machine-readable copy of the
- corresponding source code, to be distributed under the terms of
- Paragraphs 1 and 2 above; or,
-
- c) accompany it with the information you received as to where the
- corresponding source code may be obtained. (This alternative is
- allowed only for noncommercial distribution and only if you
- received the program in object code or executable form alone.)
-
- Source code for a work means the preferred form of the work for making
- modifications to it. For an executable file, complete source code means
- all the source code for all modules it contains; but, as a special
- exception, it need not include source code for modules which are standard
- libraries that accompany the operating system on which the executable
- file runs, or for standard header files or definitions files that
- accompany that operating system.
-
- 4. You may not copy, modify, sublicense, distribute or transfer the
- Program except as expressly provided under this General Public License.
- Any attempt otherwise to copy, modify, sublicense, distribute or transfer
- the Program is void, and will automatically terminate your rights to use
- the Program under this License. However, parties who have received
- copies, or rights to use copies, from you under this General Public
- License will not have their licenses terminated so long as such parties
- remain in full compliance.
-
- 5. By copying, distributing or modifying the Program (or any work based
- on the Program) you indicate your acceptance of this license to do so,
- and all its terms and conditions.
-
- 6. Each time you redistribute the Program (or any work based on the
- Program), the recipient automatically receives a license from the original
- licensor to copy, distribute or modify the Program subject to these
- terms and conditions. You may not impose any further restrictions on the
- recipients' exercise of the rights granted herein.
-
- 7. The Free Software Foundation may publish revised and/or new versions
- of the General Public License from time to time. Such new versions will
- be similar in spirit to the present version, but may differ in detail to
- address new problems or concerns.
-
- Each version is given a distinguishing version number. If the Program
- specifies a version number of the license which applies to it and "any
- later version", you have the option of following the terms and conditions
- either of that version or of any later version published by the Free
- Software Foundation. If the Program does not specify a version number of
- the license, you may choose any version ever published by the Free Software
- Foundation.
-
- 8. If you wish to incorporate parts of the Program into other free
- programs whose distribution conditions are different, write to the author
- to ask for permission. For software which is copyrighted by the Free
- Software Foundation, write to the Free Software Foundation; we sometimes
- make exceptions for this. Our decision will be guided by the two goals
- of preserving the free status of all derivatives of our free software and
- of promoting the sharing and reuse of software generally.
-
- NO WARRANTY
-
- 9. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
- FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
- OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
- PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
- OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
- MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
- TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
- PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
- REPAIR OR CORRECTION.
-
- 10. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
- WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
- REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
- INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
- OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
- TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
- YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
- PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
- POSSIBILITY OF SUCH DAMAGES.
-
- END OF TERMS AND CONDITIONS
-
- Appendix: How to Apply These Terms to Your New Programs
-
- If you develop a new program, and you want it to be of the greatest
- possible use to humanity, the best way to achieve this is to make it
- free software which everyone can redistribute and change under these
- terms.
-
- To do so, attach the following notices to the program. It is safest to
- attach them to the start of each source file to most effectively convey
- the exclusion of warranty; and each file should have at least the
- "copyright" line and a pointer to where the full notice is found.
-
- <one line to give the program's name and a brief idea of what it does.>
- Copyright (C) 19yy <name of author>
-
- This program is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 1, or (at your option)
- any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
- You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA
- 02110-1301 USA
-
-
- Also add information on how to contact you by electronic and paper mail.
-
- If the program is interactive, make it output a short notice like this
- when it starts in an interactive mode:
-
- Gnomovision version 69, Copyright (C) 19xx name of author
- Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
- This is free software, and you are welcome to redistribute it
- under certain conditions; type 'show c' for details.
-
- The hypothetical commands 'show w' and 'show c' should show the
- appropriate parts of the General Public License. Of course, the
- commands you use may be called something other than 'show w' and 'show
- c'; they could even be mouse-clicks or menu items--whatever suits your
- program.
-
- You should also get your employer (if you work as a programmer) or your
- school, if any, to sign a "copyright disclaimer" for the program, if
- necessary. Here a sample; alter the names:
-
- Yoyodyne, Inc., hereby disclaims all copyright interest in the
- program 'Gnomovision' (a program to direct compilers to make passes
- at assemblers) written by James Hacker.
-
- <signature of Ty Coon>, 1 April 1989
- Ty Coon, President of Vice
-
- That's all there is to it!
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlguts.pod b/Master/tlpkg/tlperl/lib/pods/perlguts.pod
deleted file mode 100644
index 908fa1f0bd3..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlguts.pod
+++ /dev/null
@@ -1,2934 +0,0 @@
-=head1 NAME
-
-perlguts - Introduction to the Perl API
-
-=head1 DESCRIPTION
-
-This document attempts to describe how to use the Perl API, as well as
-to provide some info on the basic workings of the Perl core. It is far
-from complete and probably contains many errors. Please refer any
-questions or comments to the author below.
-
-=head1 Variables
-
-=head2 Datatypes
-
-Perl has three typedefs that handle Perl's three main data types:
-
- SV Scalar Value
- AV Array Value
- HV Hash Value
-
-Each typedef has specific routines that manipulate the various data types.
-
-=head2 What is an "IV"?
-
-Perl uses a special typedef IV which is a simple signed integer type that is
-guaranteed to be large enough to hold a pointer (as well as an integer).
-Additionally, there is the UV, which is simply an unsigned IV.
-
-Perl also uses two special typedefs, I32 and I16, which will always be at
-least 32-bits and 16-bits long, respectively. (Again, there are U32 and U16,
-as well.) They will usually be exactly 32 and 16 bits long, but on Crays
-they will both be 64 bits.
-
-=head2 Working with SVs
-
-An SV can be created and loaded with one command. There are five types of
-values that can be loaded: an integer value (IV), an unsigned integer
-value (UV), a double (NV), a string (PV), and another scalar (SV).
-
-The seven routines are:
-
- SV* newSViv(IV);
- SV* newSVuv(UV);
- SV* newSVnv(double);
- SV* newSVpv(const char*, STRLEN);
- SV* newSVpvn(const char*, STRLEN);
- SV* newSVpvf(const char*, ...);
- SV* newSVsv(SV*);
-
-C<STRLEN> is an integer type (Size_t, usually defined as size_t in
-F<config.h>) guaranteed to be large enough to represent the size of
-any string that perl can handle.
-
-In the unlikely case of a SV requiring more complex initialisation, you
-can create an empty SV with newSV(len). If C<len> is 0 an empty SV of
-type NULL is returned, else an SV of type PV is returned with len + 1 (for
-the NUL) bytes of storage allocated, accessible via SvPVX. In both cases
-the SV has the undef value.
-
- SV *sv = newSV(0); /* no storage allocated */
- SV *sv = newSV(10); /* 10 (+1) bytes of uninitialised storage
- * allocated */
-
-To change the value of an I<already-existing> SV, there are eight routines:
-
- void sv_setiv(SV*, IV);
- void sv_setuv(SV*, UV);
- void sv_setnv(SV*, double);
- void sv_setpv(SV*, const char*);
- void sv_setpvn(SV*, const char*, STRLEN)
- void sv_setpvf(SV*, const char*, ...);
- void sv_vsetpvfn(SV*, const char*, STRLEN, va_list *,
- SV **, I32, bool *);
- void sv_setsv(SV*, SV*);
-
-Notice that you can choose to specify the length of the string to be
-assigned by using C<sv_setpvn>, C<newSVpvn>, or C<newSVpv>, or you may
-allow Perl to calculate the length by using C<sv_setpv> or by specifying
-0 as the second argument to C<newSVpv>. Be warned, though, that Perl will
-determine the string's length by using C<strlen>, which depends on the
-string terminating with a NUL character, and not otherwise containing
-NULs.
-
-The arguments of C<sv_setpvf> are processed like C<sprintf>, and the
-formatted output becomes the value.
-
-C<sv_vsetpvfn> is an analogue of C<vsprintf>, but it allows you to specify
-either a pointer to a variable argument list or the address and length of
-an array of SVs. The last argument points to a boolean; on return, if that
-boolean is true, then locale-specific information has been used to format
-the string, and the string's contents are therefore untrustworthy (see
-L<perlsec>). This pointer may be NULL if that information is not
-important. Note that this function requires you to specify the length of
-the format.
-
-The C<sv_set*()> functions are not generic enough to operate on values
-that have "magic". See L<Magic Virtual Tables> later in this document.
-
-All SVs that contain strings should be terminated with a NUL character.
-If it is not NUL-terminated there is a risk of
-core dumps and corruptions from code which passes the string to C
-functions or system calls which expect a NUL-terminated string.
-Perl's own functions typically add a trailing NUL for this reason.
-Nevertheless, you should be very careful when you pass a string stored
-in an SV to a C function or system call.
-
-To access the actual value that an SV points to, you can use the macros:
-
- SvIV(SV*)
- SvUV(SV*)
- SvNV(SV*)
- SvPV(SV*, STRLEN len)
- SvPV_nolen(SV*)
-
-which will automatically coerce the actual scalar type into an IV, UV, double,
-or string.
-
-In the C<SvPV> macro, the length of the string returned is placed into the
-variable C<len> (this is a macro, so you do I<not> use C<&len>). If you do
-not care what the length of the data is, use the C<SvPV_nolen> macro.
-Historically the C<SvPV> macro with the global variable C<PL_na> has been
-used in this case. But that can be quite inefficient because C<PL_na> must
-be accessed in thread-local storage in threaded Perl. In any case, remember
-that Perl allows arbitrary strings of data that may both contain NULs and
-might not be terminated by a NUL.
-
-Also remember that C doesn't allow you to safely say C<foo(SvPV(s, len),
-len);>. It might work with your compiler, but it won't work for everyone.
-Break this sort of statement up into separate assignments:
-
- SV *s;
- STRLEN len;
- char *ptr;
- ptr = SvPV(s, len);
- foo(ptr, len);
-
-If you want to know if the scalar value is TRUE, you can use:
-
- SvTRUE(SV*)
-
-Although Perl will automatically grow strings for you, if you need to force
-Perl to allocate more memory for your SV, you can use the macro
-
- SvGROW(SV*, STRLEN newlen)
-
-which will determine if more memory needs to be allocated. If so, it will
-call the function C<sv_grow>. Note that C<SvGROW> can only increase, not
-decrease, the allocated memory of an SV and that it does not automatically
-add space for the trailing NUL byte (perl's own string functions typically do
-C<SvGROW(sv, len + 1)>).
-
-If you have an SV and want to know what kind of data Perl thinks is stored
-in it, you can use the following macros to check the type of SV you have.
-
- SvIOK(SV*)
- SvNOK(SV*)
- SvPOK(SV*)
-
-You can get and set the current length of the string stored in an SV with
-the following macros:
-
- SvCUR(SV*)
- SvCUR_set(SV*, I32 val)
-
-You can also get a pointer to the end of the string stored in the SV
-with the macro:
-
- SvEND(SV*)
-
-But note that these last three macros are valid only if C<SvPOK()> is true.
-
-If you want to append something to the end of string stored in an C<SV*>,
-you can use the following functions:
-
- void sv_catpv(SV*, const char*);
- void sv_catpvn(SV*, const char*, STRLEN);
- void sv_catpvf(SV*, const char*, ...);
- void sv_vcatpvfn(SV*, const char*, STRLEN, va_list *, SV **,
- I32, bool);
- void sv_catsv(SV*, SV*);
-
-The first function calculates the length of the string to be appended by
-using C<strlen>. In the second, you specify the length of the string
-yourself. The third function processes its arguments like C<sprintf> and
-appends the formatted output. The fourth function works like C<vsprintf>.
-You can specify the address and length of an array of SVs instead of the
-va_list argument. The fifth function extends the string stored in the first
-SV with the string stored in the second SV. It also forces the second SV
-to be interpreted as a string.
-
-The C<sv_cat*()> functions are not generic enough to operate on values that
-have "magic". See L<Magic Virtual Tables> later in this document.
-
-If you know the name of a scalar variable, you can get a pointer to its SV
-by using the following:
-
- SV* get_sv("package::varname", 0);
-
-This returns NULL if the variable does not exist.
-
-If you want to know if this variable (or any other SV) is actually C<defined>,
-you can call:
-
- SvOK(SV*)
-
-The scalar C<undef> value is stored in an SV instance called C<PL_sv_undef>.
-
-Its address can be used whenever an C<SV*> is needed. Make sure that
-you don't try to compare a random sv with C<&PL_sv_undef>. For example
-when interfacing Perl code, it'll work correctly for:
-
- foo(undef);
-
-But won't work when called as:
-
- $x = undef;
- foo($x);
-
-So to repeat always use SvOK() to check whether an sv is defined.
-
-Also you have to be careful when using C<&PL_sv_undef> as a value in
-AVs or HVs (see L<AVs, HVs and undefined values>).
-
-There are also the two values C<PL_sv_yes> and C<PL_sv_no>, which contain
-boolean TRUE and FALSE values, respectively. Like C<PL_sv_undef>, their
-addresses can be used whenever an C<SV*> is needed.
-
-Do not be fooled into thinking that C<(SV *) 0> is the same as C<&PL_sv_undef>.
-Take this code:
-
- SV* sv = (SV*) 0;
- if (I-am-to-return-a-real-value) {
- sv = sv_2mortal(newSViv(42));
- }
- sv_setsv(ST(0), sv);
-
-This code tries to return a new SV (which contains the value 42) if it should
-return a real value, or undef otherwise. Instead it has returned a NULL
-pointer which, somewhere down the line, will cause a segmentation violation,
-bus error, or just weird results. Change the zero to C<&PL_sv_undef> in the
-first line and all will be well.
-
-To free an SV that you've created, call C<SvREFCNT_dec(SV*)>. Normally this
-call is not necessary (see L<Reference Counts and Mortality>).
-
-=head2 Offsets
-
-Perl provides the function C<sv_chop> to efficiently remove characters
-from the beginning of a string; you give it an SV and a pointer to
-somewhere inside the PV, and it discards everything before the
-pointer. The efficiency comes by means of a little hack: instead of
-actually removing the characters, C<sv_chop> sets the flag C<OOK>
-(offset OK) to signal to other functions that the offset hack is in
-effect, and it puts the number of bytes chopped off into the IV field
-of the SV. It then moves the PV pointer (called C<SvPVX>) forward that
-many bytes, and adjusts C<SvCUR> and C<SvLEN>.
-
-Hence, at this point, the start of the buffer that we allocated lives
-at C<SvPVX(sv) - SvIV(sv)> in memory and the PV pointer is pointing
-into the middle of this allocated storage.
-
-This is best demonstrated by example:
-
- % ./perl -Ilib -MDevel::Peek -le '$a="12345"; $a=~s/.//; Dump($a)'
- SV = PVIV(0x8128450) at 0x81340f0
- REFCNT = 1
- FLAGS = (POK,OOK,pPOK)
- IV = 1 (OFFSET)
- PV = 0x8135781 ( "1" . ) "2345"\0
- CUR = 4
- LEN = 5
-
-Here the number of bytes chopped off (1) is put into IV, and
-C<Devel::Peek::Dump> helpfully reminds us that this is an offset. The
-portion of the string between the "real" and the "fake" beginnings is
-shown in parentheses, and the values of C<SvCUR> and C<SvLEN> reflect
-the fake beginning, not the real one.
-
-Something similar to the offset hack is performed on AVs to enable
-efficient shifting and splicing off the beginning of the array; while
-C<AvARRAY> points to the first element in the array that is visible from
-Perl, C<AvALLOC> points to the real start of the C array. These are
-usually the same, but a C<shift> operation can be carried out by
-increasing C<AvARRAY> by one and decreasing C<AvFILL> and C<AvMAX>.
-Again, the location of the real start of the C array only comes into
-play when freeing the array. See C<av_shift> in F<av.c>.
-
-=head2 What's Really Stored in an SV?
-
-Recall that the usual method of determining the type of scalar you have is
-to use C<Sv*OK> macros. Because a scalar can be both a number and a string,
-usually these macros will always return TRUE and calling the C<Sv*V>
-macros will do the appropriate conversion of string to integer/double or
-integer/double to string.
-
-If you I<really> need to know if you have an integer, double, or string
-pointer in an SV, you can use the following three macros instead:
-
- SvIOKp(SV*)
- SvNOKp(SV*)
- SvPOKp(SV*)
-
-These will tell you if you truly have an integer, double, or string pointer
-stored in your SV. The "p" stands for private.
-
-There are various ways in which the private and public flags may differ.
-For example, a tied SV may have a valid underlying value in the IV slot
-(so SvIOKp is true), but the data should be accessed via the FETCH
-routine rather than directly, so SvIOK is false. Another is when
-numeric conversion has occurred and precision has been lost: only the
-private flag is set on 'lossy' values. So when an NV is converted to an
-IV with loss, SvIOKp, SvNOKp and SvNOK will be set, while SvIOK wont be.
-
-In general, though, it's best to use the C<Sv*V> macros.
-
-=head2 Working with AVs
-
-There are two ways to create and load an AV. The first method creates an
-empty AV:
-
- AV* newAV();
-
-The second method both creates the AV and initially populates it with SVs:
-
- AV* av_make(I32 num, SV **ptr);
-
-The second argument points to an array containing C<num> C<SV*>'s. Once the
-AV has been created, the SVs can be destroyed, if so desired.
-
-Once the AV has been created, the following operations are possible on it:
-
- void av_push(AV*, SV*);
- SV* av_pop(AV*);
- SV* av_shift(AV*);
- void av_unshift(AV*, I32 num);
-
-These should be familiar operations, with the exception of C<av_unshift>.
-This routine adds C<num> elements at the front of the array with the C<undef>
-value. You must then use C<av_store> (described below) to assign values
-to these new elements.
-
-Here are some other functions:
-
- I32 av_len(AV*);
- SV** av_fetch(AV*, I32 key, I32 lval);
- SV** av_store(AV*, I32 key, SV* val);
-
-The C<av_len> function returns the highest index value in an array (just
-like $#array in Perl). If the array is empty, -1 is returned. The
-C<av_fetch> function returns the value at index C<key>, but if C<lval>
-is non-zero, then C<av_fetch> will store an undef value at that index.
-The C<av_store> function stores the value C<val> at index C<key>, and does
-not increment the reference count of C<val>. Thus the caller is responsible
-for taking care of that, and if C<av_store> returns NULL, the caller will
-have to decrement the reference count to avoid a memory leak. Note that
-C<av_fetch> and C<av_store> both return C<SV**>'s, not C<SV*>'s as their
-return value.
-
-A few more:
-
- void av_clear(AV*);
- void av_undef(AV*);
- void av_extend(AV*, I32 key);
-
-The C<av_clear> function deletes all the elements in the AV* array, but
-does not actually delete the array itself. The C<av_undef> function will
-delete all the elements in the array plus the array itself. The
-C<av_extend> function extends the array so that it contains at least C<key+1>
-elements. If C<key+1> is less than the currently allocated length of the array,
-then nothing is done.
-
-If you know the name of an array variable, you can get a pointer to its AV
-by using the following:
-
- AV* get_av("package::varname", 0);
-
-This returns NULL if the variable does not exist.
-
-See L<Understanding the Magic of Tied Hashes and Arrays> for more
-information on how to use the array access functions on tied arrays.
-
-=head2 Working with HVs
-
-To create an HV, you use the following routine:
-
- HV* newHV();
-
-Once the HV has been created, the following operations are possible on it:
-
- SV** hv_store(HV*, const char* key, U32 klen, SV* val, U32 hash);
- SV** hv_fetch(HV*, const char* key, U32 klen, I32 lval);
-
-The C<klen> parameter is the length of the key being passed in (Note that
-you cannot pass 0 in as a value of C<klen> to tell Perl to measure the
-length of the key). The C<val> argument contains the SV pointer to the
-scalar being stored, and C<hash> is the precomputed hash value (zero if
-you want C<hv_store> to calculate it for you). The C<lval> parameter
-indicates whether this fetch is actually a part of a store operation, in
-which case a new undefined value will be added to the HV with the supplied
-key and C<hv_fetch> will return as if the value had already existed.
-
-Remember that C<hv_store> and C<hv_fetch> return C<SV**>'s and not just
-C<SV*>. To access the scalar value, you must first dereference the return
-value. However, you should check to make sure that the return value is
-not NULL before dereferencing it.
-
-The first of these two functions checks if a hash table entry exists, and the
-second deletes it.
-
- bool hv_exists(HV*, const char* key, U32 klen);
- SV* hv_delete(HV*, const char* key, U32 klen, I32 flags);
-
-If C<flags> does not include the C<G_DISCARD> flag then C<hv_delete> will
-create and return a mortal copy of the deleted value.
-
-And more miscellaneous functions:
-
- void hv_clear(HV*);
- void hv_undef(HV*);
-
-Like their AV counterparts, C<hv_clear> deletes all the entries in the hash
-table but does not actually delete the hash table. The C<hv_undef> deletes
-both the entries and the hash table itself.
-
-Perl keeps the actual data in a linked list of structures with a typedef of HE.
-These contain the actual key and value pointers (plus extra administrative
-overhead). The key is a string pointer; the value is an C<SV*>. However,
-once you have an C<HE*>, to get the actual key and value, use the routines
-specified below.
-
- I32 hv_iterinit(HV*);
- /* Prepares starting point to traverse hash table */
- HE* hv_iternext(HV*);
- /* Get the next entry, and return a pointer to a
- structure that has both the key and value */
- char* hv_iterkey(HE* entry, I32* retlen);
- /* Get the key from an HE structure and also return
- the length of the key string */
- SV* hv_iterval(HV*, HE* entry);
- /* Return an SV pointer to the value of the HE
- structure */
- SV* hv_iternextsv(HV*, char** key, I32* retlen);
- /* This convenience routine combines hv_iternext,
- hv_iterkey, and hv_iterval. The key and retlen
- arguments are return values for the key and its
- length. The value is returned in the SV* argument */
-
-If you know the name of a hash variable, you can get a pointer to its HV
-by using the following:
-
- HV* get_hv("package::varname", 0);
-
-This returns NULL if the variable does not exist.
-
-The hash algorithm is defined in the C<PERL_HASH(hash, key, klen)> macro:
-
- hash = 0;
- while (klen--)
- hash = (hash * 33) + *key++;
- hash = hash + (hash >> 5); /* after 5.6 */
-
-The last step was added in version 5.6 to improve distribution of
-lower bits in the resulting hash value.
-
-See L<Understanding the Magic of Tied Hashes and Arrays> for more
-information on how to use the hash access functions on tied hashes.
-
-=head2 Hash API Extensions
-
-Beginning with version 5.004, the following functions are also supported:
-
- HE* hv_fetch_ent (HV* tb, SV* key, I32 lval, U32 hash);
- HE* hv_store_ent (HV* tb, SV* key, SV* val, U32 hash);
-
- bool hv_exists_ent (HV* tb, SV* key, U32 hash);
- SV* hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash);
-
- SV* hv_iterkeysv (HE* entry);
-
-Note that these functions take C<SV*> keys, which simplifies writing
-of extension code that deals with hash structures. These functions
-also allow passing of C<SV*> keys to C<tie> functions without forcing
-you to stringify the keys (unlike the previous set of functions).
-
-They also return and accept whole hash entries (C<HE*>), making their
-use more efficient (since the hash number for a particular string
-doesn't have to be recomputed every time). See L<perlapi> for detailed
-descriptions.
-
-The following macros must always be used to access the contents of hash
-entries. Note that the arguments to these macros must be simple
-variables, since they may get evaluated more than once. See
-L<perlapi> for detailed descriptions of these macros.
-
- HePV(HE* he, STRLEN len)
- HeVAL(HE* he)
- HeHASH(HE* he)
- HeSVKEY(HE* he)
- HeSVKEY_force(HE* he)
- HeSVKEY_set(HE* he, SV* sv)
-
-These two lower level macros are defined, but must only be used when
-dealing with keys that are not C<SV*>s:
-
- HeKEY(HE* he)
- HeKLEN(HE* he)
-
-Note that both C<hv_store> and C<hv_store_ent> do not increment the
-reference count of the stored C<val>, which is the caller's responsibility.
-If these functions return a NULL value, the caller will usually have to
-decrement the reference count of C<val> to avoid a memory leak.
-
-=head2 AVs, HVs and undefined values
-
-Sometimes you have to store undefined values in AVs or HVs. Although
-this may be a rare case, it can be tricky. That's because you're
-used to using C<&PL_sv_undef> if you need an undefined SV.
-
-For example, intuition tells you that this XS code:
-
- AV *av = newAV();
- av_store( av, 0, &PL_sv_undef );
-
-is equivalent to this Perl code:
-
- my @av;
- $av[0] = undef;
-
-Unfortunately, this isn't true. AVs use C<&PL_sv_undef> as a marker
-for indicating that an array element has not yet been initialized.
-Thus, C<exists $av[0]> would be true for the above Perl code, but
-false for the array generated by the XS code.
-
-Other problems can occur when storing C<&PL_sv_undef> in HVs:
-
- hv_store( hv, "key", 3, &PL_sv_undef, 0 );
-
-This will indeed make the value C<undef>, but if you try to modify
-the value of C<key>, you'll get the following error:
-
- Modification of non-creatable hash value attempted
-
-In perl 5.8.0, C<&PL_sv_undef> was also used to mark placeholders
-in restricted hashes. This caused such hash entries not to appear
-when iterating over the hash or when checking for the keys
-with the C<hv_exists> function.
-
-You can run into similar problems when you store C<&PL_sv_yes> or
-C<&PL_sv_no> into AVs or HVs. Trying to modify such elements
-will give you the following error:
-
- Modification of a read-only value attempted
-
-To make a long story short, you can use the special variables
-C<&PL_sv_undef>, C<&PL_sv_yes> and C<&PL_sv_no> with AVs and
-HVs, but you have to make sure you know what you're doing.
-
-Generally, if you want to store an undefined value in an AV
-or HV, you should not use C<&PL_sv_undef>, but rather create a
-new undefined value using the C<newSV> function, for example:
-
- av_store( av, 42, newSV(0) );
- hv_store( hv, "foo", 3, newSV(0), 0 );
-
-=head2 References
-
-References are a special type of scalar that point to other data types
-(including other references).
-
-To create a reference, use either of the following functions:
-
- SV* newRV_inc((SV*) thing);
- SV* newRV_noinc((SV*) thing);
-
-The C<thing> argument can be any of an C<SV*>, C<AV*>, or C<HV*>. The
-functions are identical except that C<newRV_inc> increments the reference
-count of the C<thing>, while C<newRV_noinc> does not. For historical
-reasons, C<newRV> is a synonym for C<newRV_inc>.
-
-Once you have a reference, you can use the following macro to dereference
-the reference:
-
- SvRV(SV*)
-
-then call the appropriate routines, casting the returned C<SV*> to either an
-C<AV*> or C<HV*>, if required.
-
-To determine if an SV is a reference, you can use the following macro:
-
- SvROK(SV*)
-
-To discover what type of value the reference refers to, use the following
-macro and then check the return value.
-
- SvTYPE(SvRV(SV*))
-
-The most useful types that will be returned are:
-
- SVt_IV Scalar
- SVt_NV Scalar
- SVt_PV Scalar
- SVt_RV Scalar
- SVt_PVAV Array
- SVt_PVHV Hash
- SVt_PVCV Code
- SVt_PVGV Glob (possibly a file handle)
- SVt_PVMG Blessed or Magical Scalar
-
-See the F<sv.h> header file for more details.
-
-=head2 Blessed References and Class Objects
-
-References are also used to support object-oriented programming. In perl's
-OO lexicon, an object is simply a reference that has been blessed into a
-package (or class). Once blessed, the programmer may now use the reference
-to access the various methods in the class.
-
-A reference can be blessed into a package with the following function:
-
- SV* sv_bless(SV* sv, HV* stash);
-
-The C<sv> argument must be a reference value. The C<stash> argument
-specifies which class the reference will belong to. See
-L<Stashes and Globs> for information on converting class names into stashes.
-
-/* Still under construction */
-
-The following function upgrades rv to reference if not already one.
-Creates a new SV for rv to point to. If C<classname> is non-null, the SV
-is blessed into the specified class. SV is returned.
-
- SV* newSVrv(SV* rv, const char* classname);
-
-The following three functions copy integer, unsigned integer or double
-into an SV whose reference is C<rv>. SV is blessed if C<classname> is
-non-null.
-
- SV* sv_setref_iv(SV* rv, const char* classname, IV iv);
- SV* sv_setref_uv(SV* rv, const char* classname, UV uv);
- SV* sv_setref_nv(SV* rv, const char* classname, NV iv);
-
-The following function copies the pointer value (I<the address, not the
-string!>) into an SV whose reference is rv. SV is blessed if C<classname>
-is non-null.
-
- SV* sv_setref_pv(SV* rv, const char* classname, void* pv);
-
-The following function copies a string into an SV whose reference is C<rv>.
-Set length to 0 to let Perl calculate the string length. SV is blessed if
-C<classname> is non-null.
-
- SV* sv_setref_pvn(SV* rv, const char* classname, char* pv,
- STRLEN length);
-
-The following function tests whether the SV is blessed into the specified
-class. It does not check inheritance relationships.
-
- int sv_isa(SV* sv, const char* name);
-
-The following function tests whether the SV is a reference to a blessed object.
-
- int sv_isobject(SV* sv);
-
-The following function tests whether the SV is derived from the specified
-class. SV can be either a reference to a blessed object or a string
-containing a class name. This is the function implementing the
-C<UNIVERSAL::isa> functionality.
-
- bool sv_derived_from(SV* sv, const char* name);
-
-To check if you've got an object derived from a specific class you have
-to write:
-
- if (sv_isobject(sv) && sv_derived_from(sv, class)) { ... }
-
-=head2 Creating New Variables
-
-To create a new Perl variable with an undef value which can be accessed from
-your Perl script, use the following routines, depending on the variable type.
-
- SV* get_sv("package::varname", GV_ADD);
- AV* get_av("package::varname", GV_ADD);
- HV* get_hv("package::varname", GV_ADD);
-
-Notice the use of GV_ADD as the second parameter. The new variable can now
-be set, using the routines appropriate to the data type.
-
-There are additional macros whose values may be bitwise OR'ed with the
-C<GV_ADD> argument to enable certain extra features. Those bits are:
-
-=over
-
-=item GV_ADDMULTI
-
-Marks the variable as multiply defined, thus preventing the:
-
- Name <varname> used only once: possible typo
-
-warning.
-
-=item GV_ADDWARN
-
-Issues the warning:
-
- Had to create <varname> unexpectedly
-
-if the variable did not exist before the function was called.
-
-=back
-
-If you do not specify a package name, the variable is created in the current
-package.
-
-=head2 Reference Counts and Mortality
-
-Perl uses a reference count-driven garbage collection mechanism. SVs,
-AVs, or HVs (xV for short in the following) start their life with a
-reference count of 1. If the reference count of an xV ever drops to 0,
-then it will be destroyed and its memory made available for reuse.
-
-This normally doesn't happen at the Perl level unless a variable is
-undef'ed or the last variable holding a reference to it is changed or
-overwritten. At the internal level, however, reference counts can be
-manipulated with the following macros:
-
- int SvREFCNT(SV* sv);
- SV* SvREFCNT_inc(SV* sv);
- void SvREFCNT_dec(SV* sv);
-
-However, there is one other function which manipulates the reference
-count of its argument. The C<newRV_inc> function, you will recall,
-creates a reference to the specified argument. As a side effect,
-it increments the argument's reference count. If this is not what
-you want, use C<newRV_noinc> instead.
-
-For example, imagine you want to return a reference from an XSUB function.
-Inside the XSUB routine, you create an SV which initially has a reference
-count of one. Then you call C<newRV_inc>, passing it the just-created SV.
-This returns the reference as a new SV, but the reference count of the
-SV you passed to C<newRV_inc> has been incremented to two. Now you
-return the reference from the XSUB routine and forget about the SV.
-But Perl hasn't! Whenever the returned reference is destroyed, the
-reference count of the original SV is decreased to one and nothing happens.
-The SV will hang around without any way to access it until Perl itself
-terminates. This is a memory leak.
-
-The correct procedure, then, is to use C<newRV_noinc> instead of
-C<newRV_inc>. Then, if and when the last reference is destroyed,
-the reference count of the SV will go to zero and it will be destroyed,
-stopping any memory leak.
-
-There are some convenience functions available that can help with the
-destruction of xVs. These functions introduce the concept of "mortality".
-An xV that is mortal has had its reference count marked to be decremented,
-but not actually decremented, until "a short time later". Generally the
-term "short time later" means a single Perl statement, such as a call to
-an XSUB function. The actual determinant for when mortal xVs have their
-reference count decremented depends on two macros, SAVETMPS and FREETMPS.
-See L<perlcall> and L<perlxs> for more details on these macros.
-
-"Mortalization" then is at its simplest a deferred C<SvREFCNT_dec>.
-However, if you mortalize a variable twice, the reference count will
-later be decremented twice.
-
-"Mortal" SVs are mainly used for SVs that are placed on perl's stack.
-For example an SV which is created just to pass a number to a called sub
-is made mortal to have it cleaned up automatically when it's popped off
-the stack. Similarly, results returned by XSUBs (which are pushed on the
-stack) are often made mortal.
-
-To create a mortal variable, use the functions:
-
- SV* sv_newmortal()
- SV* sv_2mortal(SV*)
- SV* sv_mortalcopy(SV*)
-
-The first call creates a mortal SV (with no value), the second converts an existing
-SV to a mortal SV (and thus defers a call to C<SvREFCNT_dec>), and the
-third creates a mortal copy of an existing SV.
-Because C<sv_newmortal> gives the new SV no value, it must normally be given one
-via C<sv_setpv>, C<sv_setiv>, etc. :
-
- SV *tmp = sv_newmortal();
- sv_setiv(tmp, an_integer);
-
-As that is multiple C statements it is quite common so see this idiom instead:
-
- SV *tmp = sv_2mortal(newSViv(an_integer));
-
-
-You should be careful about creating mortal variables. Strange things
-can happen if you make the same value mortal within multiple contexts,
-or if you make a variable mortal multiple times. Thinking of "Mortalization"
-as deferred C<SvREFCNT_dec> should help to minimize such problems.
-For example if you are passing an SV which you I<know> has a high enough REFCNT
-to survive its use on the stack you need not do any mortalization.
-If you are not sure then doing an C<SvREFCNT_inc> and C<sv_2mortal>, or
-making a C<sv_mortalcopy> is safer.
-
-The mortal routines are not just for SVs; AVs and HVs can be
-made mortal by passing their address (type-casted to C<SV*>) to the
-C<sv_2mortal> or C<sv_mortalcopy> routines.
-
-=head2 Stashes and Globs
-
-A B<stash> is a hash that contains all variables that are defined
-within a package. Each key of the stash is a symbol
-name (shared by all the different types of objects that have the same
-name), and each value in the hash table is a GV (Glob Value). This GV
-in turn contains references to the various objects of that name,
-including (but not limited to) the following:
-
- Scalar Value
- Array Value
- Hash Value
- I/O Handle
- Format
- Subroutine
-
-There is a single stash called C<PL_defstash> that holds the items that exist
-in the C<main> package. To get at the items in other packages, append the
-string "::" to the package name. The items in the C<Foo> package are in
-the stash C<Foo::> in PL_defstash. The items in the C<Bar::Baz> package are
-in the stash C<Baz::> in C<Bar::>'s stash.
-
-To get the stash pointer for a particular package, use the function:
-
- HV* gv_stashpv(const char* name, I32 flags)
- HV* gv_stashsv(SV*, I32 flags)
-
-The first function takes a literal string, the second uses the string stored
-in the SV. Remember that a stash is just a hash table, so you get back an
-C<HV*>. The C<flags> flag will create a new package if it is set to GV_ADD.
-
-The name that C<gv_stash*v> wants is the name of the package whose symbol table
-you want. The default package is called C<main>. If you have multiply nested
-packages, pass their names to C<gv_stash*v>, separated by C<::> as in the Perl
-language itself.
-
-Alternately, if you have an SV that is a blessed reference, you can find
-out the stash pointer by using:
-
- HV* SvSTASH(SvRV(SV*));
-
-then use the following to get the package name itself:
-
- char* HvNAME(HV* stash);
-
-If you need to bless or re-bless an object you can use the following
-function:
-
- SV* sv_bless(SV*, HV* stash)
-
-where the first argument, an C<SV*>, must be a reference, and the second
-argument is a stash. The returned C<SV*> can now be used in the same way
-as any other SV.
-
-For more information on references and blessings, consult L<perlref>.
-
-=head2 Double-Typed SVs
-
-Scalar variables normally contain only one type of value, an integer,
-double, pointer, or reference. Perl will automatically convert the
-actual scalar data from the stored type into the requested type.
-
-Some scalar variables contain more than one type of scalar data. For
-example, the variable C<$!> contains either the numeric value of C<errno>
-or its string equivalent from either C<strerror> or C<sys_errlist[]>.
-
-To force multiple data values into an SV, you must do two things: use the
-C<sv_set*v> routines to add the additional scalar type, then set a flag
-so that Perl will believe it contains more than one type of data. The
-four macros to set the flags are:
-
- SvIOK_on
- SvNOK_on
- SvPOK_on
- SvROK_on
-
-The particular macro you must use depends on which C<sv_set*v> routine
-you called first. This is because every C<sv_set*v> routine turns on
-only the bit for the particular type of data being set, and turns off
-all the rest.
-
-For example, to create a new Perl variable called "dberror" that contains
-both the numeric and descriptive string error values, you could use the
-following code:
-
- extern int dberror;
- extern char *dberror_list;
-
- SV* sv = get_sv("dberror", GV_ADD);
- sv_setiv(sv, (IV) dberror);
- sv_setpv(sv, dberror_list[dberror]);
- SvIOK_on(sv);
-
-If the order of C<sv_setiv> and C<sv_setpv> had been reversed, then the
-macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>.
-
-=head2 Magic Variables
-
-[This section still under construction. Ignore everything here. Post no
-bills. Everything not permitted is forbidden.]
-
-Any SV may be magical, that is, it has special features that a normal
-SV does not have. These features are stored in the SV structure in a
-linked list of C<struct magic>'s, typedef'ed to C<MAGIC>.
-
- struct magic {
- MAGIC* mg_moremagic;
- MGVTBL* mg_virtual;
- U16 mg_private;
- char mg_type;
- U8 mg_flags;
- I32 mg_len;
- SV* mg_obj;
- char* mg_ptr;
- };
-
-Note this is current as of patchlevel 0, and could change at any time.
-
-=head2 Assigning Magic
-
-Perl adds magic to an SV using the sv_magic function:
-
- void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen);
-
-The C<sv> argument is a pointer to the SV that is to acquire a new magical
-feature.
-
-If C<sv> is not already magical, Perl uses the C<SvUPGRADE> macro to
-convert C<sv> to type C<SVt_PVMG>. Perl then continues by adding new magic
-to the beginning of the linked list of magical features. Any prior entry
-of the same type of magic is deleted. Note that this can be overridden,
-and multiple instances of the same type of magic can be associated with an
-SV.
-
-The C<name> and C<namlen> arguments are used to associate a string with
-the magic, typically the name of a variable. C<namlen> is stored in the
-C<mg_len> field and if C<name> is non-null then either a C<savepvn> copy of
-C<name> or C<name> itself is stored in the C<mg_ptr> field, depending on
-whether C<namlen> is greater than zero or equal to zero respectively. As a
-special case, if C<(name && namlen == HEf_SVKEY)> then C<name> is assumed
-to contain an C<SV*> and is stored as-is with its REFCNT incremented.
-
-The sv_magic function uses C<how> to determine which, if any, predefined
-"Magic Virtual Table" should be assigned to the C<mg_virtual> field.
-See the L<Magic Virtual Tables> section below. The C<how> argument is also
-stored in the C<mg_type> field. The value of C<how> should be chosen
-from the set of macros C<PERL_MAGIC_foo> found in F<perl.h>. Note that before
-these macros were added, Perl internals used to directly use character
-literals, so you may occasionally come across old code or documentation
-referring to 'U' magic rather than C<PERL_MAGIC_uvar> for example.
-
-The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC>
-structure. If it is not the same as the C<sv> argument, the reference
-count of the C<obj> object is incremented. If it is the same, or if
-the C<how> argument is C<PERL_MAGIC_arylen>, or if it is a NULL pointer,
-then C<obj> is merely stored, without the reference count being incremented.
-
-See also C<sv_magicext> in L<perlapi> for a more flexible way to add magic
-to an SV.
-
-There is also a function to add magic to an C<HV>:
-
- void hv_magic(HV *hv, GV *gv, int how);
-
-This simply calls C<sv_magic> and coerces the C<gv> argument into an C<SV>.
-
-To remove the magic from an SV, call the function sv_unmagic:
-
- int sv_unmagic(SV *sv, int type);
-
-The C<type> argument should be equal to the C<how> value when the C<SV>
-was initially made magical.
-
-However, note that C<sv_unmagic> removes all magic of a certain C<type> from the
-C<SV>. If you want to remove only certain magic of a C<type> based on the magic
-virtual table, use C<sv_unmagicext> instead:
-
- int sv_unmagicext(SV *sv, int type, MGVTBL *vtbl);
-
-=head2 Magic Virtual Tables
-
-The C<mg_virtual> field in the C<MAGIC> structure is a pointer to an
-C<MGVTBL>, which is a structure of function pointers and stands for
-"Magic Virtual Table" to handle the various operations that might be
-applied to that variable.
-
-The C<MGVTBL> has five (or sometimes eight) pointers to the following
-routine types:
-
- int (*svt_get)(SV* sv, MAGIC* mg);
- int (*svt_set)(SV* sv, MAGIC* mg);
- U32 (*svt_len)(SV* sv, MAGIC* mg);
- int (*svt_clear)(SV* sv, MAGIC* mg);
- int (*svt_free)(SV* sv, MAGIC* mg);
-
- int (*svt_copy)(SV *sv, MAGIC* mg, SV *nsv,
- const char *name, I32 namlen);
- int (*svt_dup)(MAGIC *mg, CLONE_PARAMS *param);
- int (*svt_local)(SV *nsv, MAGIC *mg);
-
-
-This MGVTBL structure is set at compile-time in F<perl.h> and there are
-currently 32 types. These different structures contain pointers to various
-routines that perform additional actions depending on which function is
-being called.
-
- Function pointer Action taken
- ---------------- ------------
- svt_get Do something before the value of the SV is
- retrieved.
- svt_set Do something after the SV is assigned a value.
- svt_len Report on the SV's length.
- svt_clear Clear something the SV represents.
- svt_free Free any extra storage associated with the SV.
-
- svt_copy copy tied variable magic to a tied element
- svt_dup duplicate a magic structure during thread cloning
- svt_local copy magic to local value during 'local'
-
-For instance, the MGVTBL structure called C<vtbl_sv> (which corresponds
-to an C<mg_type> of C<PERL_MAGIC_sv>) contains:
-
- { magic_get, magic_set, magic_len, 0, 0 }
-
-Thus, when an SV is determined to be magical and of type C<PERL_MAGIC_sv>,
-if a get operation is being performed, the routine C<magic_get> is
-called. All the various routines for the various magical types begin
-with C<magic_>. NOTE: the magic routines are not considered part of
-the Perl API, and may not be exported by the Perl library.
-
-The last three slots are a recent addition, and for source code
-compatibility they are only checked for if one of the three flags
-MGf_COPY, MGf_DUP or MGf_LOCAL is set in mg_flags. This means that most
-code can continue declaring a vtable as a 5-element value. These three are
-currently used exclusively by the threading code, and are highly subject
-to change.
-
-The current kinds of Magic Virtual Tables are:
-
-=for comment
-This table is generated by regen/mg_vtable.pl. Any changes made here
-will be lost.
-
-=for mg_vtable.pl begin
-
- mg_type
- (old-style char and macro) MGVTBL Type of magic
- -------------------------- ------ -------------
- \0 PERL_MAGIC_sv vtbl_sv Special scalar variable
- # PERL_MAGIC_arylen vtbl_arylen Array length ($#ary)
- % PERL_MAGIC_rhash (none) extra data for restricted
- hashes
- . PERL_MAGIC_pos vtbl_pos pos() lvalue
- : PERL_MAGIC_symtab (none) extra data for symbol
- tables
- < PERL_MAGIC_backref vtbl_backref for weak ref data
- @ PERL_MAGIC_arylen_p (none) to move arylen out of
- XPVAV
- A PERL_MAGIC_overload vtbl_amagic %OVERLOAD hash
- a PERL_MAGIC_overload_elem vtbl_amagicelem %OVERLOAD hash element
- B PERL_MAGIC_bm vtbl_regexp Boyer-Moore
- (fast string search)
- c PERL_MAGIC_overload_table vtbl_ovrld Holds overload table
- (AMT) on stash
- D PERL_MAGIC_regdata vtbl_regdata Regex match position data
- (@+ and @- vars)
- d PERL_MAGIC_regdatum vtbl_regdatum Regex match position data
- element
- E PERL_MAGIC_env vtbl_env %ENV hash
- e PERL_MAGIC_envelem vtbl_envelem %ENV hash element
- f PERL_MAGIC_fm vtbl_regdata Formline
- ('compiled' format)
- G PERL_MAGIC_study vtbl_regexp study()ed string
- g PERL_MAGIC_regex_global vtbl_mglob m//g target
- H PERL_MAGIC_hints vtbl_hints %^H hash
- h PERL_MAGIC_hintselem vtbl_hintselem %^H hash element
- I PERL_MAGIC_isa vtbl_isa @ISA array
- i PERL_MAGIC_isaelem vtbl_isaelem @ISA array element
- k PERL_MAGIC_nkeys vtbl_nkeys scalar(keys()) lvalue
- L PERL_MAGIC_dbfile (none) Debugger %_<filename
- l PERL_MAGIC_dbline vtbl_dbline Debugger %_<filename
- element
- N PERL_MAGIC_shared (none) Shared between threads
- n PERL_MAGIC_shared_scalar (none) Shared between threads
- o PERL_MAGIC_collxfrm vtbl_collxfrm Locale transformation
- P PERL_MAGIC_tied vtbl_pack Tied array or hash
- p PERL_MAGIC_tiedelem vtbl_packelem Tied array or hash element
- q PERL_MAGIC_tiedscalar vtbl_packelem Tied scalar or handle
- r PERL_MAGIC_qr vtbl_regexp precompiled qr// regex
- S PERL_MAGIC_sig (none) %SIG hash
- s PERL_MAGIC_sigelem vtbl_sigelem %SIG hash element
- t PERL_MAGIC_taint vtbl_taint Taintedness
- U PERL_MAGIC_uvar vtbl_uvar Available for use by
- extensions
- u PERL_MAGIC_uvar_elem (none) Reserved for use by
- extensions
- V PERL_MAGIC_vstring vtbl_vstring SV was vstring literal
- v PERL_MAGIC_vec vtbl_vec vec() lvalue
- w PERL_MAGIC_utf8 vtbl_utf8 Cached UTF-8 information
- x PERL_MAGIC_substr vtbl_substr substr() lvalue
- y PERL_MAGIC_defelem vtbl_defelem Shadow "foreach" iterator
- variable / smart parameter
- vivification
- ] PERL_MAGIC_checkcall (none) inlining/mutation of call
- to this CV
- ~ PERL_MAGIC_ext (none) Available for use by
- extensions
-
-=for mg_vtable.pl end
-
-When an uppercase and lowercase letter both exist in the table, then the
-uppercase letter is typically used to represent some kind of composite type
-(a list or a hash), and the lowercase letter is used to represent an element
-of that composite type. Some internals code makes use of this case
-relationship. However, 'v' and 'V' (vec and v-string) are in no way related.
-
-The C<PERL_MAGIC_ext> and C<PERL_MAGIC_uvar> magic types are defined
-specifically for use by extensions and will not be used by perl itself.
-Extensions can use C<PERL_MAGIC_ext> magic to 'attach' private information
-to variables (typically objects). This is especially useful because
-there is no way for normal perl code to corrupt this private information
-(unlike using extra elements of a hash object).
-
-Similarly, C<PERL_MAGIC_uvar> magic can be used much like tie() to call a
-C function any time a scalar's value is used or changed. The C<MAGIC>'s
-C<mg_ptr> field points to a C<ufuncs> structure:
-
- struct ufuncs {
- I32 (*uf_val)(pTHX_ IV, SV*);
- I32 (*uf_set)(pTHX_ IV, SV*);
- IV uf_index;
- };
-
-When the SV is read from or written to, the C<uf_val> or C<uf_set>
-function will be called with C<uf_index> as the first arg and a pointer to
-the SV as the second. A simple example of how to add C<PERL_MAGIC_uvar>
-magic is shown below. Note that the ufuncs structure is copied by
-sv_magic, so you can safely allocate it on the stack.
-
- void
- Umagic(sv)
- SV *sv;
- PREINIT:
- struct ufuncs uf;
- CODE:
- uf.uf_val = &my_get_fn;
- uf.uf_set = &my_set_fn;
- uf.uf_index = 0;
- sv_magic(sv, 0, PERL_MAGIC_uvar, (char*)&uf, sizeof(uf));
-
-Attaching C<PERL_MAGIC_uvar> to arrays is permissible but has no effect.
-
-For hashes there is a specialized hook that gives control over hash
-keys (but not values). This hook calls C<PERL_MAGIC_uvar> 'get' magic
-if the "set" function in the C<ufuncs> structure is NULL. The hook
-is activated whenever the hash is accessed with a key specified as
-an C<SV> through the functions C<hv_store_ent>, C<hv_fetch_ent>,
-C<hv_delete_ent>, and C<hv_exists_ent>. Accessing the key as a string
-through the functions without the C<..._ent> suffix circumvents the
-hook. See L<Hash::Util::FieldHash/GUTS> for a detailed description.
-
-Note that because multiple extensions may be using C<PERL_MAGIC_ext>
-or C<PERL_MAGIC_uvar> magic, it is important for extensions to take
-extra care to avoid conflict. Typically only using the magic on
-objects blessed into the same class as the extension is sufficient.
-For C<PERL_MAGIC_ext> magic, it is usually a good idea to define an
-C<MGVTBL>, even if all its fields will be C<0>, so that individual
-C<MAGIC> pointers can be identified as a particular kind of magic
-using their magic virtual table. C<mg_findext> provides an easy way
-to do that:
-
- STATIC MGVTBL my_vtbl = { 0, 0, 0, 0, 0, 0, 0, 0 };
-
- MAGIC *mg;
- if ((mg = mg_findext(sv, PERL_MAGIC_ext, &my_vtbl))) {
- /* this is really ours, not another module's PERL_MAGIC_ext */
- my_priv_data_t *priv = (my_priv_data_t *)mg->mg_ptr;
- ...
- }
-
-Also note that the C<sv_set*()> and C<sv_cat*()> functions described
-earlier do B<not> invoke 'set' magic on their targets. This must
-be done by the user either by calling the C<SvSETMAGIC()> macro after
-calling these functions, or by using one of the C<sv_set*_mg()> or
-C<sv_cat*_mg()> functions. Similarly, generic C code must call the
-C<SvGETMAGIC()> macro to invoke any 'get' magic if they use an SV
-obtained from external sources in functions that don't handle magic.
-See L<perlapi> for a description of these functions.
-For example, calls to the C<sv_cat*()> functions typically need to be
-followed by C<SvSETMAGIC()>, but they don't need a prior C<SvGETMAGIC()>
-since their implementation handles 'get' magic.
-
-=head2 Finding Magic
-
- MAGIC *mg_find(SV *sv, int type); /* Finds the magic pointer of that
- * type */
-
-This routine returns a pointer to a C<MAGIC> structure stored in the SV.
-If the SV does not have that magical feature, C<NULL> is returned. If the
-SV has multiple instances of that magical feature, the first one will be
-returned. C<mg_findext> can be used to find a C<MAGIC> structure of an SV
-based on both its magic type and its magic virtual table:
-
- MAGIC *mg_findext(SV *sv, int type, MGVTBL *vtbl);
-
-Also, if the SV passed to C<mg_find> or C<mg_findext> is not of type
-SVt_PVMG, Perl may core dump.
-
- int mg_copy(SV* sv, SV* nsv, const char* key, STRLEN klen);
-
-This routine checks to see what types of magic C<sv> has. If the mg_type
-field is an uppercase letter, then the mg_obj is copied to C<nsv>, but
-the mg_type field is changed to be the lowercase letter.
-
-=head2 Understanding the Magic of Tied Hashes and Arrays
-
-Tied hashes and arrays are magical beasts of the C<PERL_MAGIC_tied>
-magic type.
-
-WARNING: As of the 5.004 release, proper usage of the array and hash
-access functions requires understanding a few caveats. Some
-of these caveats are actually considered bugs in the API, to be fixed
-in later releases, and are bracketed with [MAYCHANGE] below. If
-you find yourself actually applying such information in this section, be
-aware that the behavior may change in the future, umm, without warning.
-
-The perl tie function associates a variable with an object that implements
-the various GET, SET, etc methods. To perform the equivalent of the perl
-tie function from an XSUB, you must mimic this behaviour. The code below
-carries out the necessary steps - firstly it creates a new hash, and then
-creates a second hash which it blesses into the class which will implement
-the tie methods. Lastly it ties the two hashes together, and returns a
-reference to the new tied hash. Note that the code below does NOT call the
-TIEHASH method in the MyTie class -
-see L<Calling Perl Routines from within C Programs> for details on how
-to do this.
-
- SV*
- mytie()
- PREINIT:
- HV *hash;
- HV *stash;
- SV *tie;
- CODE:
- hash = newHV();
- tie = newRV_noinc((SV*)newHV());
- stash = gv_stashpv("MyTie", GV_ADD);
- sv_bless(tie, stash);
- hv_magic(hash, (GV*)tie, PERL_MAGIC_tied);
- RETVAL = newRV_noinc(hash);
- OUTPUT:
- RETVAL
-
-The C<av_store> function, when given a tied array argument, merely
-copies the magic of the array onto the value to be "stored", using
-C<mg_copy>. It may also return NULL, indicating that the value did not
-actually need to be stored in the array. [MAYCHANGE] After a call to
-C<av_store> on a tied array, the caller will usually need to call
-C<mg_set(val)> to actually invoke the perl level "STORE" method on the
-TIEARRAY object. If C<av_store> did return NULL, a call to
-C<SvREFCNT_dec(val)> will also be usually necessary to avoid a memory
-leak. [/MAYCHANGE]
-
-The previous paragraph is applicable verbatim to tied hash access using the
-C<hv_store> and C<hv_store_ent> functions as well.
-
-C<av_fetch> and the corresponding hash functions C<hv_fetch> and
-C<hv_fetch_ent> actually return an undefined mortal value whose magic
-has been initialized using C<mg_copy>. Note the value so returned does not
-need to be deallocated, as it is already mortal. [MAYCHANGE] But you will
-need to call C<mg_get()> on the returned value in order to actually invoke
-the perl level "FETCH" method on the underlying TIE object. Similarly,
-you may also call C<mg_set()> on the return value after possibly assigning
-a suitable value to it using C<sv_setsv>, which will invoke the "STORE"
-method on the TIE object. [/MAYCHANGE]
-
-[MAYCHANGE]
-In other words, the array or hash fetch/store functions don't really
-fetch and store actual values in the case of tied arrays and hashes. They
-merely call C<mg_copy> to attach magic to the values that were meant to be
-"stored" or "fetched". Later calls to C<mg_get> and C<mg_set> actually
-do the job of invoking the TIE methods on the underlying objects. Thus
-the magic mechanism currently implements a kind of lazy access to arrays
-and hashes.
-
-Currently (as of perl version 5.004), use of the hash and array access
-functions requires the user to be aware of whether they are operating on
-"normal" hashes and arrays, or on their tied variants. The API may be
-changed to provide more transparent access to both tied and normal data
-types in future versions.
-[/MAYCHANGE]
-
-You would do well to understand that the TIEARRAY and TIEHASH interfaces
-are mere sugar to invoke some perl method calls while using the uniform hash
-and array syntax. The use of this sugar imposes some overhead (typically
-about two to four extra opcodes per FETCH/STORE operation, in addition to
-the creation of all the mortal variables required to invoke the methods).
-This overhead will be comparatively small if the TIE methods are themselves
-substantial, but if they are only a few statements long, the overhead
-will not be insignificant.
-
-=head2 Localizing changes
-
-Perl has a very handy construction
-
- {
- local $var = 2;
- ...
- }
-
-This construction is I<approximately> equivalent to
-
- {
- my $oldvar = $var;
- $var = 2;
- ...
- $var = $oldvar;
- }
-
-The biggest difference is that the first construction would
-reinstate the initial value of $var, irrespective of how control exits
-the block: C<goto>, C<return>, C<die>/C<eval>, etc. It is a little bit
-more efficient as well.
-
-There is a way to achieve a similar task from C via Perl API: create a
-I<pseudo-block>, and arrange for some changes to be automatically
-undone at the end of it, either explicit, or via a non-local exit (via
-die()). A I<block>-like construct is created by a pair of
-C<ENTER>/C<LEAVE> macros (see L<perlcall/"Returning a Scalar">).
-Such a construct may be created specially for some important localized
-task, or an existing one (like boundaries of enclosing Perl
-subroutine/block, or an existing pair for freeing TMPs) may be
-used. (In the second case the overhead of additional localization must
-be almost negligible.) Note that any XSUB is automatically enclosed in
-an C<ENTER>/C<LEAVE> pair.
-
-Inside such a I<pseudo-block> the following service is available:
-
-=over 4
-
-=item C<SAVEINT(int i)>
-
-=item C<SAVEIV(IV i)>
-
-=item C<SAVEI32(I32 i)>
-
-=item C<SAVELONG(long i)>
-
-These macros arrange things to restore the value of integer variable
-C<i> at the end of enclosing I<pseudo-block>.
-
-=item C<SAVESPTR(s)>
-
-=item C<SAVEPPTR(p)>
-
-These macros arrange things to restore the value of pointers C<s> and
-C<p>. C<s> must be a pointer of a type which survives conversion to
-C<SV*> and back, C<p> should be able to survive conversion to C<char*>
-and back.
-
-=item C<SAVEFREESV(SV *sv)>
-
-The refcount of C<sv> would be decremented at the end of
-I<pseudo-block>. This is similar to C<sv_2mortal> in that it is also a
-mechanism for doing a delayed C<SvREFCNT_dec>. However, while C<sv_2mortal>
-extends the lifetime of C<sv> until the beginning of the next statement,
-C<SAVEFREESV> extends it until the end of the enclosing scope. These
-lifetimes can be wildly different.
-
-Also compare C<SAVEMORTALIZESV>.
-
-=item C<SAVEMORTALIZESV(SV *sv)>
-
-Just like C<SAVEFREESV>, but mortalizes C<sv> at the end of the current
-scope instead of decrementing its reference count. This usually has the
-effect of keeping C<sv> alive until the statement that called the currently
-live scope has finished executing.
-
-=item C<SAVEFREEOP(OP *op)>
-
-The C<OP *> is op_free()ed at the end of I<pseudo-block>.
-
-=item C<SAVEFREEPV(p)>
-
-The chunk of memory which is pointed to by C<p> is Safefree()ed at the
-end of I<pseudo-block>.
-
-=item C<SAVECLEARSV(SV *sv)>
-
-Clears a slot in the current scratchpad which corresponds to C<sv> at
-the end of I<pseudo-block>.
-
-=item C<SAVEDELETE(HV *hv, char *key, I32 length)>
-
-The key C<key> of C<hv> is deleted at the end of I<pseudo-block>. The
-string pointed to by C<key> is Safefree()ed. If one has a I<key> in
-short-lived storage, the corresponding string may be reallocated like
-this:
-
- SAVEDELETE(PL_defstash, savepv(tmpbuf), strlen(tmpbuf));
-
-=item C<SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)>
-
-At the end of I<pseudo-block> the function C<f> is called with the
-only argument C<p>.
-
-=item C<SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)>
-
-At the end of I<pseudo-block> the function C<f> is called with the
-implicit context argument (if any), and C<p>.
-
-=item C<SAVESTACK_POS()>
-
-The current offset on the Perl internal stack (cf. C<SP>) is restored
-at the end of I<pseudo-block>.
-
-=back
-
-The following API list contains functions, thus one needs to
-provide pointers to the modifiable data explicitly (either C pointers,
-or Perlish C<GV *>s). Where the above macros take C<int>, a similar
-function takes C<int *>.
-
-=over 4
-
-=item C<SV* save_scalar(GV *gv)>
-
-Equivalent to Perl code C<local $gv>.
-
-=item C<AV* save_ary(GV *gv)>
-
-=item C<HV* save_hash(GV *gv)>
-
-Similar to C<save_scalar>, but localize C<@gv> and C<%gv>.
-
-=item C<void save_item(SV *item)>
-
-Duplicates the current value of C<SV>, on the exit from the current
-C<ENTER>/C<LEAVE> I<pseudo-block> will restore the value of C<SV>
-using the stored value. It doesn't handle magic. Use C<save_scalar> if
-magic is affected.
-
-=item C<void save_list(SV **sarg, I32 maxsarg)>
-
-A variant of C<save_item> which takes multiple arguments via an array
-C<sarg> of C<SV*> of length C<maxsarg>.
-
-=item C<SV* save_svref(SV **sptr)>
-
-Similar to C<save_scalar>, but will reinstate an C<SV *>.
-
-=item C<void save_aptr(AV **aptr)>
-
-=item C<void save_hptr(HV **hptr)>
-
-Similar to C<save_svref>, but localize C<AV *> and C<HV *>.
-
-=back
-
-The C<Alias> module implements localization of the basic types within the
-I<caller's scope>. People who are interested in how to localize things in
-the containing scope should take a look there too.
-
-=head1 Subroutines
-
-=head2 XSUBs and the Argument Stack
-
-The XSUB mechanism is a simple way for Perl programs to access C subroutines.
-An XSUB routine will have a stack that contains the arguments from the Perl
-program, and a way to map from the Perl data structures to a C equivalent.
-
-The stack arguments are accessible through the C<ST(n)> macro, which returns
-the C<n>'th stack argument. Argument 0 is the first argument passed in the
-Perl subroutine call. These arguments are C<SV*>, and can be used anywhere
-an C<SV*> is used.
-
-Most of the time, output from the C routine can be handled through use of
-the RETVAL and OUTPUT directives. However, there are some cases where the
-argument stack is not already long enough to handle all the return values.
-An example is the POSIX tzname() call, which takes no arguments, but returns
-two, the local time zone's standard and summer time abbreviations.
-
-To handle this situation, the PPCODE directive is used and the stack is
-extended using the macro:
-
- EXTEND(SP, num);
-
-where C<SP> is the macro that represents the local copy of the stack pointer,
-and C<num> is the number of elements the stack should be extended by.
-
-Now that there is room on the stack, values can be pushed on it using C<PUSHs>
-macro. The pushed values will often need to be "mortal" (See
-L</Reference Counts and Mortality>):
-
- PUSHs(sv_2mortal(newSViv(an_integer)))
- PUSHs(sv_2mortal(newSVuv(an_unsigned_integer)))
- PUSHs(sv_2mortal(newSVnv(a_double)))
- PUSHs(sv_2mortal(newSVpv("Some String",0)))
- /* Although the last example is better written as the more
- * efficient: */
- PUSHs(newSVpvs_flags("Some String", SVs_TEMP))
-
-And now the Perl program calling C<tzname>, the two values will be assigned
-as in:
-
- ($standard_abbrev, $summer_abbrev) = POSIX::tzname;
-
-An alternate (and possibly simpler) method to pushing values on the stack is
-to use the macro:
-
- XPUSHs(SV*)
-
-This macro automatically adjusts the stack for you, if needed. Thus, you
-do not need to call C<EXTEND> to extend the stack.
-
-Despite their suggestions in earlier versions of this document the macros
-C<(X)PUSH[iunp]> are I<not> suited to XSUBs which return multiple results.
-For that, either stick to the C<(X)PUSHs> macros shown above, or use the new
-C<m(X)PUSH[iunp]> macros instead; see L</Putting a C value on Perl stack>.
-
-For more information, consult L<perlxs> and L<perlxstut>.
-
-=head2 Autoloading with XSUBs
-
-If an AUTOLOAD routine is an XSUB, as with Perl subroutines, Perl puts the
-fully-qualified name of the autoloaded subroutine in the $AUTOLOAD variable
-of the XSUB's package.
-
-But it also puts the same information in certain fields of the XSUB itself:
-
- HV *stash = CvSTASH(cv);
- const char *subname = SvPVX(cv);
- STRLEN name_length = SvCUR(cv); /* in bytes */
- U32 is_utf8 = SvUTF8(cv);
-
-C<SvPVX(cv)> contains just the sub name itself, not including the package.
-For an AUTOLOAD routine in UNIVERSAL or one of its superclasses,
-C<CvSTASH(cv)> returns NULL during a method call on a nonexistent package.
-
-B<Note>: Setting $AUTOLOAD stopped working in 5.6.1, which did not support
-XS AUTOLOAD subs at all. Perl 5.8.0 introduced the use of fields in the
-XSUB itself. Perl 5.16.0 restored the setting of $AUTOLOAD. If you need
-to support 5.8-5.14, use the XSUB's fields.
-
-=head2 Calling Perl Routines from within C Programs
-
-There are four routines that can be used to call a Perl subroutine from
-within a C program. These four are:
-
- I32 call_sv(SV*, I32);
- I32 call_pv(const char*, I32);
- I32 call_method(const char*, I32);
- I32 call_argv(const char*, I32, register char**);
-
-The routine most often used is C<call_sv>. The C<SV*> argument
-contains either the name of the Perl subroutine to be called, or a
-reference to the subroutine. The second argument consists of flags
-that control the context in which the subroutine is called, whether
-or not the subroutine is being passed arguments, how errors should be
-trapped, and how to treat return values.
-
-All four routines return the number of arguments that the subroutine returned
-on the Perl stack.
-
-These routines used to be called C<perl_call_sv>, etc., before Perl v5.6.0,
-but those names are now deprecated; macros of the same name are provided for
-compatibility.
-
-When using any of these routines (except C<call_argv>), the programmer
-must manipulate the Perl stack. These include the following macros and
-functions:
-
- dSP
- SP
- PUSHMARK()
- PUTBACK
- SPAGAIN
- ENTER
- SAVETMPS
- FREETMPS
- LEAVE
- XPUSH*()
- POP*()
-
-For a detailed description of calling conventions from C to Perl,
-consult L<perlcall>.
-
-=head2 Memory Allocation
-
-=head3 Allocation
-
-All memory meant to be used with the Perl API functions should be manipulated
-using the macros described in this section. The macros provide the necessary
-transparency between differences in the actual malloc implementation that is
-used within perl.
-
-It is suggested that you enable the version of malloc that is distributed
-with Perl. It keeps pools of various sizes of unallocated memory in
-order to satisfy allocation requests more quickly. However, on some
-platforms, it may cause spurious malloc or free errors.
-
-The following three macros are used to initially allocate memory :
-
- Newx(pointer, number, type);
- Newxc(pointer, number, type, cast);
- Newxz(pointer, number, type);
-
-The first argument C<pointer> should be the name of a variable that will
-point to the newly allocated memory.
-
-The second and third arguments C<number> and C<type> specify how many of
-the specified type of data structure should be allocated. The argument
-C<type> is passed to C<sizeof>. The final argument to C<Newxc>, C<cast>,
-should be used if the C<pointer> argument is different from the C<type>
-argument.
-
-Unlike the C<Newx> and C<Newxc> macros, the C<Newxz> macro calls C<memzero>
-to zero out all the newly allocated memory.
-
-=head3 Reallocation
-
- Renew(pointer, number, type);
- Renewc(pointer, number, type, cast);
- Safefree(pointer)
-
-These three macros are used to change a memory buffer size or to free a
-piece of memory no longer needed. The arguments to C<Renew> and C<Renewc>
-match those of C<New> and C<Newc> with the exception of not needing the
-"magic cookie" argument.
-
-=head3 Moving
-
- Move(source, dest, number, type);
- Copy(source, dest, number, type);
- Zero(dest, number, type);
-
-These three macros are used to move, copy, or zero out previously allocated
-memory. The C<source> and C<dest> arguments point to the source and
-destination starting points. Perl will move, copy, or zero out C<number>
-instances of the size of the C<type> data structure (using the C<sizeof>
-function).
-
-=head2 PerlIO
-
-The most recent development releases of Perl have been experimenting with
-removing Perl's dependency on the "normal" standard I/O suite and allowing
-other stdio implementations to be used. This involves creating a new
-abstraction layer that then calls whichever implementation of stdio Perl
-was compiled with. All XSUBs should now use the functions in the PerlIO
-abstraction layer and not make any assumptions about what kind of stdio
-is being used.
-
-For a complete description of the PerlIO abstraction, consult L<perlapio>.
-
-=head2 Putting a C value on Perl stack
-
-A lot of opcodes (this is an elementary operation in the internal perl
-stack machine) put an SV* on the stack. However, as an optimization
-the corresponding SV is (usually) not recreated each time. The opcodes
-reuse specially assigned SVs (I<target>s) which are (as a corollary)
-not constantly freed/created.
-
-Each of the targets is created only once (but see
-L<Scratchpads and recursion> below), and when an opcode needs to put
-an integer, a double, or a string on stack, it just sets the
-corresponding parts of its I<target> and puts the I<target> on stack.
-
-The macro to put this target on stack is C<PUSHTARG>, and it is
-directly used in some opcodes, as well as indirectly in zillions of
-others, which use it via C<(X)PUSH[iunp]>.
-
-Because the target is reused, you must be careful when pushing multiple
-values on the stack. The following code will not do what you think:
-
- XPUSHi(10);
- XPUSHi(20);
-
-This translates as "set C<TARG> to 10, push a pointer to C<TARG> onto
-the stack; set C<TARG> to 20, push a pointer to C<TARG> onto the stack".
-At the end of the operation, the stack does not contain the values 10
-and 20, but actually contains two pointers to C<TARG>, which we have set
-to 20.
-
-If you need to push multiple different values then you should either use
-the C<(X)PUSHs> macros, or else use the new C<m(X)PUSH[iunp]> macros,
-none of which make use of C<TARG>. The C<(X)PUSHs> macros simply push an
-SV* on the stack, which, as noted under L</XSUBs and the Argument Stack>,
-will often need to be "mortal". The new C<m(X)PUSH[iunp]> macros make
-this a little easier to achieve by creating a new mortal for you (via
-C<(X)PUSHmortal>), pushing that onto the stack (extending it if necessary
-in the case of the C<mXPUSH[iunp]> macros), and then setting its value.
-Thus, instead of writing this to "fix" the example above:
-
- XPUSHs(sv_2mortal(newSViv(10)))
- XPUSHs(sv_2mortal(newSViv(20)))
-
-you can simply write:
-
- mXPUSHi(10)
- mXPUSHi(20)
-
-On a related note, if you do use C<(X)PUSH[iunp]>, then you're going to
-need a C<dTARG> in your variable declarations so that the C<*PUSH*>
-macros can make use of the local variable C<TARG>. See also C<dTARGET>
-and C<dXSTARG>.
-
-=head2 Scratchpads
-
-The question remains on when the SVs which are I<target>s for opcodes
-are created. The answer is that they are created when the current
-unit--a subroutine or a file (for opcodes for statements outside of
-subroutines)--is compiled. During this time a special anonymous Perl
-array is created, which is called a scratchpad for the current unit.
-
-A scratchpad keeps SVs which are lexicals for the current unit and are
-targets for opcodes. One can deduce that an SV lives on a scratchpad
-by looking on its flags: lexicals have C<SVs_PADMY> set, and
-I<target>s have C<SVs_PADTMP> set.
-
-The correspondence between OPs and I<target>s is not 1-to-1. Different
-OPs in the compile tree of the unit can use the same target, if this
-would not conflict with the expected life of the temporary.
-
-=head2 Scratchpads and recursion
-
-In fact it is not 100% true that a compiled unit contains a pointer to
-the scratchpad AV. In fact it contains a pointer to an AV of
-(initially) one element, and this element is the scratchpad AV. Why do
-we need an extra level of indirection?
-
-The answer is B<recursion>, and maybe B<threads>. Both
-these can create several execution pointers going into the same
-subroutine. For the subroutine-child not write over the temporaries
-for the subroutine-parent (lifespan of which covers the call to the
-child), the parent and the child should have different
-scratchpads. (I<And> the lexicals should be separate anyway!)
-
-So each subroutine is born with an array of scratchpads (of length 1).
-On each entry to the subroutine it is checked that the current
-depth of the recursion is not more than the length of this array, and
-if it is, new scratchpad is created and pushed into the array.
-
-The I<target>s on this scratchpad are C<undef>s, but they are already
-marked with correct flags.
-
-=head1 Compiled code
-
-=head2 Code tree
-
-Here we describe the internal form your code is converted to by
-Perl. Start with a simple example:
-
- $a = $b + $c;
-
-This is converted to a tree similar to this one:
-
- assign-to
- / \
- + $a
- / \
- $b $c
-
-(but slightly more complicated). This tree reflects the way Perl
-parsed your code, but has nothing to do with the execution order.
-There is an additional "thread" going through the nodes of the tree
-which shows the order of execution of the nodes. In our simplified
-example above it looks like:
-
- $b ---> $c ---> + ---> $a ---> assign-to
-
-But with the actual compile tree for C<$a = $b + $c> it is different:
-some nodes I<optimized away>. As a corollary, though the actual tree
-contains more nodes than our simplified example, the execution order
-is the same as in our example.
-
-=head2 Examining the tree
-
-If you have your perl compiled for debugging (usually done with
-C<-DDEBUGGING> on the C<Configure> command line), you may examine the
-compiled tree by specifying C<-Dx> on the Perl command line. The
-output takes several lines per node, and for C<$b+$c> it looks like
-this:
-
- 5 TYPE = add ===> 6
- TARG = 1
- FLAGS = (SCALAR,KIDS)
- {
- TYPE = null ===> (4)
- (was rv2sv)
- FLAGS = (SCALAR,KIDS)
- {
- 3 TYPE = gvsv ===> 4
- FLAGS = (SCALAR)
- GV = main::b
- }
- }
- {
- TYPE = null ===> (5)
- (was rv2sv)
- FLAGS = (SCALAR,KIDS)
- {
- 4 TYPE = gvsv ===> 5
- FLAGS = (SCALAR)
- GV = main::c
- }
- }
-
-This tree has 5 nodes (one per C<TYPE> specifier), only 3 of them are
-not optimized away (one per number in the left column). The immediate
-children of the given node correspond to C<{}> pairs on the same level
-of indentation, thus this listing corresponds to the tree:
-
- add
- / \
- null null
- | |
- gvsv gvsv
-
-The execution order is indicated by C<===E<gt>> marks, thus it is C<3
-4 5 6> (node C<6> is not included into above listing), i.e.,
-C<gvsv gvsv add whatever>.
-
-Each of these nodes represents an op, a fundamental operation inside the
-Perl core. The code which implements each operation can be found in the
-F<pp*.c> files; the function which implements the op with type C<gvsv>
-is C<pp_gvsv>, and so on. As the tree above shows, different ops have
-different numbers of children: C<add> is a binary operator, as one would
-expect, and so has two children. To accommodate the various different
-numbers of children, there are various types of op data structure, and
-they link together in different ways.
-
-The simplest type of op structure is C<OP>: this has no children. Unary
-operators, C<UNOP>s, have one child, and this is pointed to by the
-C<op_first> field. Binary operators (C<BINOP>s) have not only an
-C<op_first> field but also an C<op_last> field. The most complex type of
-op is a C<LISTOP>, which has any number of children. In this case, the
-first child is pointed to by C<op_first> and the last child by
-C<op_last>. The children in between can be found by iteratively
-following the C<op_sibling> pointer from the first child to the last.
-
-There are also two other op types: a C<PMOP> holds a regular expression,
-and has no children, and a C<LOOP> may or may not have children. If the
-C<op_children> field is non-zero, it behaves like a C<LISTOP>. To
-complicate matters, if a C<UNOP> is actually a C<null> op after
-optimization (see L</Compile pass 2: context propagation>) it will still
-have children in accordance with its former type.
-
-Another way to examine the tree is to use a compiler back-end module, such
-as L<B::Concise>.
-
-=head2 Compile pass 1: check routines
-
-The tree is created by the compiler while I<yacc> code feeds it
-the constructions it recognizes. Since I<yacc> works bottom-up, so does
-the first pass of perl compilation.
-
-What makes this pass interesting for perl developers is that some
-optimization may be performed on this pass. This is optimization by
-so-called "check routines". The correspondence between node names
-and corresponding check routines is described in F<opcode.pl> (do not
-forget to run C<make regen_headers> if you modify this file).
-
-A check routine is called when the node is fully constructed except
-for the execution-order thread. Since at this time there are no
-back-links to the currently constructed node, one can do most any
-operation to the top-level node, including freeing it and/or creating
-new nodes above/below it.
-
-The check routine returns the node which should be inserted into the
-tree (if the top-level node was not modified, check routine returns
-its argument).
-
-By convention, check routines have names C<ck_*>. They are usually
-called from C<new*OP> subroutines (or C<convert>) (which in turn are
-called from F<perly.y>).
-
-=head2 Compile pass 1a: constant folding
-
-Immediately after the check routine is called the returned node is
-checked for being compile-time executable. If it is (the value is
-judged to be constant) it is immediately executed, and a I<constant>
-node with the "return value" of the corresponding subtree is
-substituted instead. The subtree is deleted.
-
-If constant folding was not performed, the execution-order thread is
-created.
-
-=head2 Compile pass 2: context propagation
-
-When a context for a part of compile tree is known, it is propagated
-down through the tree. At this time the context can have 5 values
-(instead of 2 for runtime context): void, boolean, scalar, list, and
-lvalue. In contrast with the pass 1 this pass is processed from top
-to bottom: a node's context determines the context for its children.
-
-Additional context-dependent optimizations are performed at this time.
-Since at this moment the compile tree contains back-references (via
-"thread" pointers), nodes cannot be free()d now. To allow
-optimized-away nodes at this stage, such nodes are null()ified instead
-of free()ing (i.e. their type is changed to OP_NULL).
-
-=head2 Compile pass 3: peephole optimization
-
-After the compile tree for a subroutine (or for an C<eval> or a file)
-is created, an additional pass over the code is performed. This pass
-is neither top-down or bottom-up, but in the execution order (with
-additional complications for conditionals). Optimizations performed
-at this stage are subject to the same restrictions as in the pass 2.
-
-Peephole optimizations are done by calling the function pointed to
-by the global variable C<PL_peepp>. By default, C<PL_peepp> just
-calls the function pointed to by the global variable C<PL_rpeepp>.
-By default, that performs some basic op fixups and optimisations along
-the execution-order op chain, and recursively calls C<PL_rpeepp> for
-each side chain of ops (resulting from conditionals). Extensions may
-provide additional optimisations or fixups, hooking into either the
-per-subroutine or recursive stage, like this:
-
- static peep_t prev_peepp;
- static void my_peep(pTHX_ OP *o)
- {
- /* custom per-subroutine optimisation goes here */
- prev_peepp(o);
- /* custom per-subroutine optimisation may also go here */
- }
- BOOT:
- prev_peepp = PL_peepp;
- PL_peepp = my_peep;
-
- static peep_t prev_rpeepp;
- static void my_rpeep(pTHX_ OP *o)
- {
- OP *orig_o = o;
- for(; o; o = o->op_next) {
- /* custom per-op optimisation goes here */
- }
- prev_rpeepp(orig_o);
- }
- BOOT:
- prev_rpeepp = PL_rpeepp;
- PL_rpeepp = my_rpeep;
-
-=head2 Pluggable runops
-
-The compile tree is executed in a runops function. There are two runops
-functions, in F<run.c> and in F<dump.c>. C<Perl_runops_debug> is used
-with DEBUGGING and C<Perl_runops_standard> is used otherwise. For fine
-control over the execution of the compile tree it is possible to provide
-your own runops function.
-
-It's probably best to copy one of the existing runops functions and
-change it to suit your needs. Then, in the BOOT section of your XS
-file, add the line:
-
- PL_runops = my_runops;
-
-This function should be as efficient as possible to keep your programs
-running as fast as possible.
-
-=head2 Compile-time scope hooks
-
-As of perl 5.14 it is possible to hook into the compile-time lexical
-scope mechanism using C<Perl_blockhook_register>. This is used like
-this:
-
- STATIC void my_start_hook(pTHX_ int full);
- STATIC BHK my_hooks;
-
- BOOT:
- BhkENTRY_set(&my_hooks, bhk_start, my_start_hook);
- Perl_blockhook_register(aTHX_ &my_hooks);
-
-This will arrange to have C<my_start_hook> called at the start of
-compiling every lexical scope. The available hooks are:
-
-=over 4
-
-=item C<void bhk_start(pTHX_ int full)>
-
-This is called just after starting a new lexical scope. Note that Perl
-code like
-
- if ($x) { ... }
-
-creates two scopes: the first starts at the C<(> and has C<full == 1>,
-the second starts at the C<{> and has C<full == 0>. Both end at the
-C<}>, so calls to C<start> and C<pre/post_end> will match. Anything
-pushed onto the save stack by this hook will be popped just before the
-scope ends (between the C<pre_> and C<post_end> hooks, in fact).
-
-=item C<void bhk_pre_end(pTHX_ OP **o)>
-
-This is called at the end of a lexical scope, just before unwinding the
-stack. I<o> is the root of the optree representing the scope; it is a
-double pointer so you can replace the OP if you need to.
-
-=item C<void bhk_post_end(pTHX_ OP **o)>
-
-This is called at the end of a lexical scope, just after unwinding the
-stack. I<o> is as above. Note that it is possible for calls to C<pre_>
-and C<post_end> to nest, if there is something on the save stack that
-calls string eval.
-
-=item C<void bhk_eval(pTHX_ OP *const o)>
-
-This is called just before starting to compile an C<eval STRING>, C<do
-FILE>, C<require> or C<use>, after the eval has been set up. I<o> is the
-OP that requested the eval, and will normally be an C<OP_ENTEREVAL>,
-C<OP_DOFILE> or C<OP_REQUIRE>.
-
-=back
-
-Once you have your hook functions, you need a C<BHK> structure to put
-them in. It's best to allocate it statically, since there is no way to
-free it once it's registered. The function pointers should be inserted
-into this structure using the C<BhkENTRY_set> macro, which will also set
-flags indicating which entries are valid. If you do need to allocate
-your C<BHK> dynamically for some reason, be sure to zero it before you
-start.
-
-Once registered, there is no mechanism to switch these hooks off, so if
-that is necessary you will need to do this yourself. An entry in C<%^H>
-is probably the best way, so the effect is lexically scoped; however it
-is also possible to use the C<BhkDISABLE> and C<BhkENABLE> macros to
-temporarily switch entries on and off. You should also be aware that
-generally speaking at least one scope will have opened before your
-extension is loaded, so you will see some C<pre/post_end> pairs that
-didn't have a matching C<start>.
-
-=head1 Examining internal data structures with the C<dump> functions
-
-To aid debugging, the source file F<dump.c> contains a number of
-functions which produce formatted output of internal data structures.
-
-The most commonly used of these functions is C<Perl_sv_dump>; it's used
-for dumping SVs, AVs, HVs, and CVs. The C<Devel::Peek> module calls
-C<sv_dump> to produce debugging output from Perl-space, so users of that
-module should already be familiar with its format.
-
-C<Perl_op_dump> can be used to dump an C<OP> structure or any of its
-derivatives, and produces output similar to C<perl -Dx>; in fact,
-C<Perl_dump_eval> will dump the main root of the code being evaluated,
-exactly like C<-Dx>.
-
-Other useful functions are C<Perl_dump_sub>, which turns a C<GV> into an
-op tree, C<Perl_dump_packsubs> which calls C<Perl_dump_sub> on all the
-subroutines in a package like so: (Thankfully, these are all xsubs, so
-there is no op tree)
-
- (gdb) print Perl_dump_packsubs(PL_defstash)
-
- SUB attributes::bootstrap = (xsub 0x811fedc 0)
-
- SUB UNIVERSAL::can = (xsub 0x811f50c 0)
-
- SUB UNIVERSAL::isa = (xsub 0x811f304 0)
-
- SUB UNIVERSAL::VERSION = (xsub 0x811f7ac 0)
-
- SUB DynaLoader::boot_DynaLoader = (xsub 0x805b188 0)
-
-and C<Perl_dump_all>, which dumps all the subroutines in the stash and
-the op tree of the main root.
-
-=head1 How multiple interpreters and concurrency are supported
-
-=head2 Background and PERL_IMPLICIT_CONTEXT
-
-The Perl interpreter can be regarded as a closed box: it has an API
-for feeding it code or otherwise making it do things, but it also has
-functions for its own use. This smells a lot like an object, and
-there are ways for you to build Perl so that you can have multiple
-interpreters, with one interpreter represented either as a C structure,
-or inside a thread-specific structure. These structures contain all
-the context, the state of that interpreter.
-
-One macro controls the major Perl build flavor: MULTIPLICITY. The
-MULTIPLICITY build has a C structure that packages all the interpreter
-state. With multiplicity-enabled perls, PERL_IMPLICIT_CONTEXT is also
-normally defined, and enables the support for passing in a "hidden" first
-argument that represents all three data structures. MULTIPLICITY makes
-multi-threaded perls possible (with the ithreads threading model, related
-to the macro USE_ITHREADS.)
-
-Two other "encapsulation" macros are the PERL_GLOBAL_STRUCT and
-PERL_GLOBAL_STRUCT_PRIVATE (the latter turns on the former, and the
-former turns on MULTIPLICITY.) The PERL_GLOBAL_STRUCT causes all the
-internal variables of Perl to be wrapped inside a single global struct,
-struct perl_vars, accessible as (globals) &PL_Vars or PL_VarsPtr or
-the function Perl_GetVars(). The PERL_GLOBAL_STRUCT_PRIVATE goes
-one step further, there is still a single struct (allocated in main()
-either from heap or from stack) but there are no global data symbols
-pointing to it. In either case the global struct should be initialised
-as the very first thing in main() using Perl_init_global_struct() and
-correspondingly tear it down after perl_free() using Perl_free_global_struct(),
-please see F<miniperlmain.c> for usage details. You may also need
-to use C<dVAR> in your coding to "declare the global variables"
-when you are using them. dTHX does this for you automatically.
-
-To see whether you have non-const data you can use a BSD-compatible C<nm>:
-
- nm libperl.a | grep -v ' [TURtr] '
-
-If this displays any C<D> or C<d> symbols, you have non-const data.
-
-For backward compatibility reasons defining just PERL_GLOBAL_STRUCT
-doesn't actually hide all symbols inside a big global struct: some
-PerlIO_xxx vtables are left visible. The PERL_GLOBAL_STRUCT_PRIVATE
-then hides everything (see how the PERLIO_FUNCS_DECL is used).
-
-All this obviously requires a way for the Perl internal functions to be
-either subroutines taking some kind of structure as the first
-argument, or subroutines taking nothing as the first argument. To
-enable these two very different ways of building the interpreter,
-the Perl source (as it does in so many other situations) makes heavy
-use of macros and subroutine naming conventions.
-
-First problem: deciding which functions will be public API functions and
-which will be private. All functions whose names begin C<S_> are private
-(think "S" for "secret" or "static"). All other functions begin with
-"Perl_", but just because a function begins with "Perl_" does not mean it is
-part of the API. (See L</Internal Functions>.) The easiest way to be B<sure> a
-function is part of the API is to find its entry in L<perlapi>.
-If it exists in L<perlapi>, it's part of the API. If it doesn't, and you
-think it should be (i.e., you need it for your extension), send mail via
-L<perlbug> explaining why you think it should be.
-
-Second problem: there must be a syntax so that the same subroutine
-declarations and calls can pass a structure as their first argument,
-or pass nothing. To solve this, the subroutines are named and
-declared in a particular way. Here's a typical start of a static
-function used within the Perl guts:
-
- STATIC void
- S_incline(pTHX_ char *s)
-
-STATIC becomes "static" in C, and may be #define'd to nothing in some
-configurations in the future.
-
-A public function (i.e. part of the internal API, but not necessarily
-sanctioned for use in extensions) begins like this:
-
- void
- Perl_sv_setiv(pTHX_ SV* dsv, IV num)
-
-C<pTHX_> is one of a number of macros (in F<perl.h>) that hide the
-details of the interpreter's context. THX stands for "thread", "this",
-or "thingy", as the case may be. (And no, George Lucas is not involved. :-)
-The first character could be 'p' for a B<p>rototype, 'a' for B<a>rgument,
-or 'd' for B<d>eclaration, so we have C<pTHX>, C<aTHX> and C<dTHX>, and
-their variants.
-
-When Perl is built without options that set PERL_IMPLICIT_CONTEXT, there is no
-first argument containing the interpreter's context. The trailing underscore
-in the pTHX_ macro indicates that the macro expansion needs a comma
-after the context argument because other arguments follow it. If
-PERL_IMPLICIT_CONTEXT is not defined, pTHX_ will be ignored, and the
-subroutine is not prototyped to take the extra argument. The form of the
-macro without the trailing underscore is used when there are no additional
-explicit arguments.
-
-When a core function calls another, it must pass the context. This
-is normally hidden via macros. Consider C<sv_setiv>. It expands into
-something like this:
-
- #ifdef PERL_IMPLICIT_CONTEXT
- #define sv_setiv(a,b) Perl_sv_setiv(aTHX_ a, b)
- /* can't do this for vararg functions, see below */
- #else
- #define sv_setiv Perl_sv_setiv
- #endif
-
-This works well, and means that XS authors can gleefully write:
-
- sv_setiv(foo, bar);
-
-and still have it work under all the modes Perl could have been
-compiled with.
-
-This doesn't work so cleanly for varargs functions, though, as macros
-imply that the number of arguments is known in advance. Instead we
-either need to spell them out fully, passing C<aTHX_> as the first
-argument (the Perl core tends to do this with functions like
-Perl_warner), or use a context-free version.
-
-The context-free version of Perl_warner is called
-Perl_warner_nocontext, and does not take the extra argument. Instead
-it does dTHX; to get the context from thread-local storage. We
-C<#define warner Perl_warner_nocontext> so that extensions get source
-compatibility at the expense of performance. (Passing an arg is
-cheaper than grabbing it from thread-local storage.)
-
-You can ignore [pad]THXx when browsing the Perl headers/sources.
-Those are strictly for use within the core. Extensions and embedders
-need only be aware of [pad]THX.
-
-=head2 So what happened to dTHR?
-
-C<dTHR> was introduced in perl 5.005 to support the older thread model.
-The older thread model now uses the C<THX> mechanism to pass context
-pointers around, so C<dTHR> is not useful any more. Perl 5.6.0 and
-later still have it for backward source compatibility, but it is defined
-to be a no-op.
-
-=head2 How do I use all this in extensions?
-
-When Perl is built with PERL_IMPLICIT_CONTEXT, extensions that call
-any functions in the Perl API will need to pass the initial context
-argument somehow. The kicker is that you will need to write it in
-such a way that the extension still compiles when Perl hasn't been
-built with PERL_IMPLICIT_CONTEXT enabled.
-
-There are three ways to do this. First, the easy but inefficient way,
-which is also the default, in order to maintain source compatibility
-with extensions: whenever F<XSUB.h> is #included, it redefines the aTHX
-and aTHX_ macros to call a function that will return the context.
-Thus, something like:
-
- sv_setiv(sv, num);
-
-in your extension will translate to this when PERL_IMPLICIT_CONTEXT is
-in effect:
-
- Perl_sv_setiv(Perl_get_context(), sv, num);
-
-or to this otherwise:
-
- Perl_sv_setiv(sv, num);
-
-You don't have to do anything new in your extension to get this; since
-the Perl library provides Perl_get_context(), it will all just
-work.
-
-The second, more efficient way is to use the following template for
-your Foo.xs:
-
- #define PERL_NO_GET_CONTEXT /* we want efficiency */
- #include "EXTERN.h"
- #include "perl.h"
- #include "XSUB.h"
-
- STATIC void my_private_function(int arg1, int arg2);
-
- STATIC void
- my_private_function(int arg1, int arg2)
- {
- dTHX; /* fetch context */
- ... call many Perl API functions ...
- }
-
- [... etc ...]
-
- MODULE = Foo PACKAGE = Foo
-
- /* typical XSUB */
-
- void
- my_xsub(arg)
- int arg
- CODE:
- my_private_function(arg, 10);
-
-Note that the only two changes from the normal way of writing an
-extension is the addition of a C<#define PERL_NO_GET_CONTEXT> before
-including the Perl headers, followed by a C<dTHX;> declaration at
-the start of every function that will call the Perl API. (You'll
-know which functions need this, because the C compiler will complain
-that there's an undeclared identifier in those functions.) No changes
-are needed for the XSUBs themselves, because the XS() macro is
-correctly defined to pass in the implicit context if needed.
-
-The third, even more efficient way is to ape how it is done within
-the Perl guts:
-
-
- #define PERL_NO_GET_CONTEXT /* we want efficiency */
- #include "EXTERN.h"
- #include "perl.h"
- #include "XSUB.h"
-
- /* pTHX_ only needed for functions that call Perl API */
- STATIC void my_private_function(pTHX_ int arg1, int arg2);
-
- STATIC void
- my_private_function(pTHX_ int arg1, int arg2)
- {
- /* dTHX; not needed here, because THX is an argument */
- ... call Perl API functions ...
- }
-
- [... etc ...]
-
- MODULE = Foo PACKAGE = Foo
-
- /* typical XSUB */
-
- void
- my_xsub(arg)
- int arg
- CODE:
- my_private_function(aTHX_ arg, 10);
-
-This implementation never has to fetch the context using a function
-call, since it is always passed as an extra argument. Depending on
-your needs for simplicity or efficiency, you may mix the previous
-two approaches freely.
-
-Never add a comma after C<pTHX> yourself--always use the form of the
-macro with the underscore for functions that take explicit arguments,
-or the form without the argument for functions with no explicit arguments.
-
-If one is compiling Perl with the C<-DPERL_GLOBAL_STRUCT> the C<dVAR>
-definition is needed if the Perl global variables (see F<perlvars.h>
-or F<globvar.sym>) are accessed in the function and C<dTHX> is not
-used (the C<dTHX> includes the C<dVAR> if necessary). One notices
-the need for C<dVAR> only with the said compile-time define, because
-otherwise the Perl global variables are visible as-is.
-
-=head2 Should I do anything special if I call perl from multiple threads?
-
-If you create interpreters in one thread and then proceed to call them in
-another, you need to make sure perl's own Thread Local Storage (TLS) slot is
-initialized correctly in each of those threads.
-
-The C<perl_alloc> and C<perl_clone> API functions will automatically set
-the TLS slot to the interpreter they created, so that there is no need to do
-anything special if the interpreter is always accessed in the same thread that
-created it, and that thread did not create or call any other interpreters
-afterwards. If that is not the case, you have to set the TLS slot of the
-thread before calling any functions in the Perl API on that particular
-interpreter. This is done by calling the C<PERL_SET_CONTEXT> macro in that
-thread as the first thing you do:
-
- /* do this before doing anything else with some_perl */
- PERL_SET_CONTEXT(some_perl);
-
- ... other Perl API calls on some_perl go here ...
-
-=head2 Future Plans and PERL_IMPLICIT_SYS
-
-Just as PERL_IMPLICIT_CONTEXT provides a way to bundle up everything
-that the interpreter knows about itself and pass it around, so too are
-there plans to allow the interpreter to bundle up everything it knows
-about the environment it's running on. This is enabled with the
-PERL_IMPLICIT_SYS macro. Currently it only works with USE_ITHREADS on
-Windows.
-
-This allows the ability to provide an extra pointer (called the "host"
-environment) for all the system calls. This makes it possible for
-all the system stuff to maintain their own state, broken down into
-seven C structures. These are thin wrappers around the usual system
-calls (see F<win32/perllib.c>) for the default perl executable, but for a
-more ambitious host (like the one that would do fork() emulation) all
-the extra work needed to pretend that different interpreters are
-actually different "processes", would be done here.
-
-The Perl engine/interpreter and the host are orthogonal entities.
-There could be one or more interpreters in a process, and one or
-more "hosts", with free association between them.
-
-=head1 Internal Functions
-
-All of Perl's internal functions which will be exposed to the outside
-world are prefixed by C<Perl_> so that they will not conflict with XS
-functions or functions used in a program in which Perl is embedded.
-Similarly, all global variables begin with C<PL_>. (By convention,
-static functions start with C<S_>.)
-
-Inside the Perl core (C<PERL_CORE> defined), you can get at the functions
-either with or without the C<Perl_> prefix, thanks to a bunch of defines
-that live in F<embed.h>. Note that extension code should I<not> set
-C<PERL_CORE>; this exposes the full perl internals, and is likely to cause
-breakage of the XS in each new perl release.
-
-The file F<embed.h> is generated automatically from
-F<embed.pl> and F<embed.fnc>. F<embed.pl> also creates the prototyping
-header files for the internal functions, generates the documentation
-and a lot of other bits and pieces. It's important that when you add
-a new function to the core or change an existing one, you change the
-data in the table in F<embed.fnc> as well. Here's a sample entry from
-that table:
-
- Apd |SV** |av_fetch |AV* ar|I32 key|I32 lval
-
-The second column is the return type, the third column the name. Columns
-after that are the arguments. The first column is a set of flags:
-
-=over 3
-
-=item A
-
-This function is a part of the public API. All such functions should also
-have 'd', very few do not.
-
-=item p
-
-This function has a C<Perl_> prefix; i.e. it is defined as
-C<Perl_av_fetch>.
-
-=item d
-
-This function has documentation using the C<apidoc> feature which we'll
-look at in a second. Some functions have 'd' but not 'A'; docs are good.
-
-=back
-
-Other available flags are:
-
-=over 3
-
-=item s
-
-This is a static function and is defined as C<STATIC S_whatever>, and
-usually called within the sources as C<whatever(...)>.
-
-=item n
-
-This does not need an interpreter context, so the definition has no
-C<pTHX>, and it follows that callers don't use C<aTHX>. (See
-L</Background and PERL_IMPLICIT_CONTEXT>.)
-
-=item r
-
-This function never returns; C<croak>, C<exit> and friends.
-
-=item f
-
-This function takes a variable number of arguments, C<printf> style.
-The argument list should end with C<...>, like this:
-
- Afprd |void |croak |const char* pat|...
-
-=item M
-
-This function is part of the experimental development API, and may change
-or disappear without notice.
-
-=item o
-
-This function should not have a compatibility macro to define, say,
-C<Perl_parse> to C<parse>. It must be called as C<Perl_parse>.
-
-=item x
-
-This function isn't exported out of the Perl core.
-
-=item m
-
-This is implemented as a macro.
-
-=item X
-
-This function is explicitly exported.
-
-=item E
-
-This function is visible to extensions included in the Perl core.
-
-=item b
-
-Binary backward compatibility; this function is a macro but also has
-a C<Perl_> implementation (which is exported).
-
-=item others
-
-See the comments at the top of C<embed.fnc> for others.
-
-=back
-
-If you edit F<embed.pl> or F<embed.fnc>, you will need to run
-C<make regen_headers> to force a rebuild of F<embed.h> and other
-auto-generated files.
-
-=head2 Formatted Printing of IVs, UVs, and NVs
-
-If you are printing IVs, UVs, or NVS instead of the stdio(3) style
-formatting codes like C<%d>, C<%ld>, C<%f>, you should use the
-following macros for portability
-
- IVdf IV in decimal
- UVuf UV in decimal
- UVof UV in octal
- UVxf UV in hexadecimal
- NVef NV %e-like
- NVff NV %f-like
- NVgf NV %g-like
-
-These will take care of 64-bit integers and long doubles.
-For example:
-
- printf("IV is %"IVdf"\n", iv);
-
-The IVdf will expand to whatever is the correct format for the IVs.
-
-If you are printing addresses of pointers, use UVxf combined
-with PTR2UV(), do not use %lx or %p.
-
-=head2 Pointer-To-Integer and Integer-To-Pointer
-
-Because pointer size does not necessarily equal integer size,
-use the follow macros to do it right.
-
- PTR2UV(pointer)
- PTR2IV(pointer)
- PTR2NV(pointer)
- INT2PTR(pointertotype, integer)
-
-For example:
-
- IV iv = ...;
- SV *sv = INT2PTR(SV*, iv);
-
-and
-
- AV *av = ...;
- UV uv = PTR2UV(av);
-
-=head2 Exception Handling
-
-There are a couple of macros to do very basic exception handling in XS
-modules. You have to define C<NO_XSLOCKS> before including F<XSUB.h> to
-be able to use these macros:
-
- #define NO_XSLOCKS
- #include "XSUB.h"
-
-You can use these macros if you call code that may croak, but you need
-to do some cleanup before giving control back to Perl. For example:
-
- dXCPT; /* set up necessary variables */
-
- XCPT_TRY_START {
- code_that_may_croak();
- } XCPT_TRY_END
-
- XCPT_CATCH
- {
- /* do cleanup here */
- XCPT_RETHROW;
- }
-
-Note that you always have to rethrow an exception that has been
-caught. Using these macros, it is not possible to just catch the
-exception and ignore it. If you have to ignore the exception, you
-have to use the C<call_*> function.
-
-The advantage of using the above macros is that you don't have
-to setup an extra function for C<call_*>, and that using these
-macros is faster than using C<call_*>.
-
-=head2 Source Documentation
-
-There's an effort going on to document the internal functions and
-automatically produce reference manuals from them - L<perlapi> is one
-such manual which details all the functions which are available to XS
-writers. L<perlintern> is the autogenerated manual for the functions
-which are not part of the API and are supposedly for internal use only.
-
-Source documentation is created by putting POD comments into the C
-source, like this:
-
- /*
- =for apidoc sv_setiv
-
- Copies an integer into the given SV. Does not handle 'set' magic. See
- C<sv_setiv_mg>.
-
- =cut
- */
-
-Please try and supply some documentation if you add functions to the
-Perl core.
-
-=head2 Backwards compatibility
-
-The Perl API changes over time. New functions are added or the interfaces
-of existing functions are changed. The C<Devel::PPPort> module tries to
-provide compatibility code for some of these changes, so XS writers don't
-have to code it themselves when supporting multiple versions of Perl.
-
-C<Devel::PPPort> generates a C header file F<ppport.h> that can also
-be run as a Perl script. To generate F<ppport.h>, run:
-
- perl -MDevel::PPPort -eDevel::PPPort::WriteFile
-
-Besides checking existing XS code, the script can also be used to retrieve
-compatibility information for various API calls using the C<--api-info>
-command line switch. For example:
-
- % perl ppport.h --api-info=sv_magicext
-
-For details, see C<perldoc ppport.h>.
-
-=head1 Unicode Support
-
-Perl 5.6.0 introduced Unicode support. It's important for porters and XS
-writers to understand this support and make sure that the code they
-write does not corrupt Unicode data.
-
-=head2 What B<is> Unicode, anyway?
-
-In the olden, less enlightened times, we all used to use ASCII. Most of
-us did, anyway. The big problem with ASCII is that it's American. Well,
-no, that's not actually the problem; the problem is that it's not
-particularly useful for people who don't use the Roman alphabet. What
-used to happen was that particular languages would stick their own
-alphabet in the upper range of the sequence, between 128 and 255. Of
-course, we then ended up with plenty of variants that weren't quite
-ASCII, and the whole point of it being a standard was lost.
-
-Worse still, if you've got a language like Chinese or
-Japanese that has hundreds or thousands of characters, then you really
-can't fit them into a mere 256, so they had to forget about ASCII
-altogether, and build their own systems using pairs of numbers to refer
-to one character.
-
-To fix this, some people formed Unicode, Inc. and
-produced a new character set containing all the characters you can
-possibly think of and more. There are several ways of representing these
-characters, and the one Perl uses is called UTF-8. UTF-8 uses
-a variable number of bytes to represent a character. You can learn more
-about Unicode and Perl's Unicode model in L<perlunicode>.
-
-=head2 How can I recognise a UTF-8 string?
-
-You can't. This is because UTF-8 data is stored in bytes just like
-non-UTF-8 data. The Unicode character 200, (C<0xC8> for you hex types)
-capital E with a grave accent, is represented by the two bytes
-C<v196.172>. Unfortunately, the non-Unicode string C<chr(196).chr(172)>
-has that byte sequence as well. So you can't tell just by looking - this
-is what makes Unicode input an interesting problem.
-
-In general, you either have to know what you're dealing with, or you
-have to guess. The API function C<is_utf8_string> can help; it'll tell
-you if a string contains only valid UTF-8 characters. However, it can't
-do the work for you. On a character-by-character basis, C<is_utf8_char>
-will tell you whether the current character in a string is valid UTF-8.
-
-=head2 How does UTF-8 represent Unicode characters?
-
-As mentioned above, UTF-8 uses a variable number of bytes to store a
-character. Characters with values 0...127 are stored in one byte, just
-like good ol' ASCII. Character 128 is stored as C<v194.128>; this
-continues up to character 191, which is C<v194.191>. Now we've run out of
-bits (191 is binary C<10111111>) so we move on; 192 is C<v195.128>. And
-so it goes on, moving to three bytes at character 2048.
-
-Assuming you know you're dealing with a UTF-8 string, you can find out
-how long the first character in it is with the C<UTF8SKIP> macro:
-
- char *utf = "\305\233\340\240\201";
- I32 len;
-
- len = UTF8SKIP(utf); /* len is 2 here */
- utf += len;
- len = UTF8SKIP(utf); /* len is 3 here */
-
-Another way to skip over characters in a UTF-8 string is to use
-C<utf8_hop>, which takes a string and a number of characters to skip
-over. You're on your own about bounds checking, though, so don't use it
-lightly.
-
-All bytes in a multi-byte UTF-8 character will have the high bit set,
-so you can test if you need to do something special with this
-character like this (the UTF8_IS_INVARIANT() is a macro that tests
-whether the byte can be encoded as a single byte even in UTF-8):
-
- U8 *utf;
- U8 *utf_end; /* 1 beyond buffer pointed to by utf */
- UV uv; /* Note: a UV, not a U8, not a char */
- STRLEN len; /* length of character in bytes */
-
- if (!UTF8_IS_INVARIANT(*utf))
- /* Must treat this as UTF-8 */
- uv = utf8_to_uvchr_buf(utf, utf_end, &len);
- else
- /* OK to treat this character as a byte */
- uv = *utf;
-
-You can also see in that example that we use C<utf8_to_uvchr_buf> to get the
-value of the character; the inverse function C<uvchr_to_utf8> is available
-for putting a UV into UTF-8:
-
- if (!UTF8_IS_INVARIANT(uv))
- /* Must treat this as UTF8 */
- utf8 = uvchr_to_utf8(utf8, uv);
- else
- /* OK to treat this character as a byte */
- *utf8++ = uv;
-
-You B<must> convert characters to UVs using the above functions if
-you're ever in a situation where you have to match UTF-8 and non-UTF-8
-characters. You may not skip over UTF-8 characters in this case. If you
-do this, you'll lose the ability to match hi-bit non-UTF-8 characters;
-for instance, if your UTF-8 string contains C<v196.172>, and you skip
-that character, you can never match a C<chr(200)> in a non-UTF-8 string.
-So don't do that!
-
-=head2 How does Perl store UTF-8 strings?
-
-Currently, Perl deals with Unicode strings and non-Unicode strings
-slightly differently. A flag in the SV, C<SVf_UTF8>, indicates that the
-string is internally encoded as UTF-8. Without it, the byte value is the
-codepoint number and vice versa (in other words, the string is encoded
-as iso-8859-1, but C<use feature 'unicode_strings'> is needed to get iso-8859-1
-semantics). You can check and manipulate this flag with the
-following macros:
-
- SvUTF8(sv)
- SvUTF8_on(sv)
- SvUTF8_off(sv)
-
-This flag has an important effect on Perl's treatment of the string: if
-Unicode data is not properly distinguished, regular expressions,
-C<length>, C<substr> and other string handling operations will have
-undesirable results.
-
-The problem comes when you have, for instance, a string that isn't
-flagged as UTF-8, and contains a byte sequence that could be UTF-8 -
-especially when combining non-UTF-8 and UTF-8 strings.
-
-Never forget that the C<SVf_UTF8> flag is separate to the PV value; you
-need be sure you don't accidentally knock it off while you're
-manipulating SVs. More specifically, you cannot expect to do this:
-
- SV *sv;
- SV *nsv;
- STRLEN len;
- char *p;
-
- p = SvPV(sv, len);
- frobnicate(p);
- nsv = newSVpvn(p, len);
-
-The C<char*> string does not tell you the whole story, and you can't
-copy or reconstruct an SV just by copying the string value. Check if the
-old SV has the UTF8 flag set, and act accordingly:
-
- p = SvPV(sv, len);
- frobnicate(p);
- nsv = newSVpvn(p, len);
- if (SvUTF8(sv))
- SvUTF8_on(nsv);
-
-In fact, your C<frobnicate> function should be made aware of whether or
-not it's dealing with UTF-8 data, so that it can handle the string
-appropriately.
-
-Since just passing an SV to an XS function and copying the data of
-the SV is not enough to copy the UTF8 flags, even less right is just
-passing a C<char *> to an XS function.
-
-=head2 How do I convert a string to UTF-8?
-
-If you're mixing UTF-8 and non-UTF-8 strings, it is necessary to upgrade
-one of the strings to UTF-8. If you've got an SV, the easiest way to do
-this is:
-
- sv_utf8_upgrade(sv);
-
-However, you must not do this, for example:
-
- if (!SvUTF8(left))
- sv_utf8_upgrade(left);
-
-If you do this in a binary operator, you will actually change one of the
-strings that came into the operator, and, while it shouldn't be noticeable
-by the end user, it can cause problems in deficient code.
-
-Instead, C<bytes_to_utf8> will give you a UTF-8-encoded B<copy> of its
-string argument. This is useful for having the data available for
-comparisons and so on, without harming the original SV. There's also
-C<utf8_to_bytes> to go the other way, but naturally, this will fail if
-the string contains any characters above 255 that can't be represented
-in a single byte.
-
-=head2 Is there anything else I need to know?
-
-Not really. Just remember these things:
-
-=over 3
-
-=item *
-
-There's no way to tell if a string is UTF-8 or not. You can tell if an SV
-is UTF-8 by looking at its C<SvUTF8> flag. Don't forget to set the flag if
-something should be UTF-8. Treat the flag as part of the PV, even though
-it's not - if you pass on the PV to somewhere, pass on the flag too.
-
-=item *
-
-If a string is UTF-8, B<always> use C<utf8_to_uvchr_buf> to get at the value,
-unless C<UTF8_IS_INVARIANT(*s)> in which case you can use C<*s>.
-
-=item *
-
-When writing a character C<uv> to a UTF-8 string, B<always> use
-C<uvchr_to_utf8>, unless C<UTF8_IS_INVARIANT(uv))> in which case
-you can use C<*s = uv>.
-
-=item *
-
-Mixing UTF-8 and non-UTF-8 strings is tricky. Use C<bytes_to_utf8> to get
-a new string which is UTF-8 encoded, and then combine them.
-
-=back
-
-=head1 Custom Operators
-
-Custom operator support is a new experimental feature that allows you to
-define your own ops. This is primarily to allow the building of
-interpreters for other languages in the Perl core, but it also allows
-optimizations through the creation of "macro-ops" (ops which perform the
-functions of multiple ops which are usually executed together, such as
-C<gvsv, gvsv, add>.)
-
-This feature is implemented as a new op type, C<OP_CUSTOM>. The Perl
-core does not "know" anything special about this op type, and so it will
-not be involved in any optimizations. This also means that you can
-define your custom ops to be any op structure - unary, binary, list and
-so on - you like.
-
-It's important to know what custom operators won't do for you. They
-won't let you add new syntax to Perl, directly. They won't even let you
-add new keywords, directly. In fact, they won't change the way Perl
-compiles a program at all. You have to do those changes yourself, after
-Perl has compiled the program. You do this either by manipulating the op
-tree using a C<CHECK> block and the C<B::Generate> module, or by adding
-a custom peephole optimizer with the C<optimize> module.
-
-When you do this, you replace ordinary Perl ops with custom ops by
-creating ops with the type C<OP_CUSTOM> and the C<pp_addr> of your own
-PP function. This should be defined in XS code, and should look like
-the PP ops in C<pp_*.c>. You are responsible for ensuring that your op
-takes the appropriate number of values from the stack, and you are
-responsible for adding stack marks if necessary.
-
-You should also "register" your op with the Perl interpreter so that it
-can produce sensible error and warning messages. Since it is possible to
-have multiple custom ops within the one "logical" op type C<OP_CUSTOM>,
-Perl uses the value of C<< o->op_ppaddr >> to determine which custom op
-it is dealing with. You should create an C<XOP> structure for each
-ppaddr you use, set the properties of the custom op with
-C<XopENTRY_set>, and register the structure against the ppaddr using
-C<Perl_custom_op_register>. A trivial example might look like:
-
- static XOP my_xop;
- static OP *my_pp(pTHX);
-
- BOOT:
- XopENTRY_set(&my_xop, xop_name, "myxop");
- XopENTRY_set(&my_xop, xop_desc, "Useless custom op");
- Perl_custom_op_register(aTHX_ my_pp, &my_xop);
-
-The available fields in the structure are:
-
-=over 4
-
-=item xop_name
-
-A short name for your op. This will be included in some error messages,
-and will also be returned as C<< $op->name >> by the L<B|B> module, so
-it will appear in the output of module like L<B::Concise|B::Concise>.
-
-=item xop_desc
-
-A short description of the function of the op.
-
-=item xop_class
-
-Which of the various C<*OP> structures this op uses. This should be one of
-the C<OA_*> constants from F<op.h>, namely
-
-=over 4
-
-=item OA_BASEOP
-
-=item OA_UNOP
-
-=item OA_BINOP
-
-=item OA_LOGOP
-
-=item OA_LISTOP
-
-=item OA_PMOP
-
-=item OA_SVOP
-
-=item OA_PADOP
-
-=item OA_PVOP_OR_SVOP
-
-This should be interpreted as 'C<PVOP>' only. The C<_OR_SVOP> is because
-the only core C<PVOP>, C<OP_TRANS>, can sometimes be a C<SVOP> instead.
-
-=item OA_LOOP
-
-=item OA_COP
-
-=back
-
-The other C<OA_*> constants should not be used.
-
-=item xop_peep
-
-This member is of type C<Perl_cpeep_t>, which expands to C<void
-(*Perl_cpeep_t)(aTHX_ OP *o, OP *oldop)>. If it is set, this function
-will be called from C<Perl_rpeep> when ops of this type are encountered
-by the peephole optimizer. I<o> is the OP that needs optimizing;
-I<oldop> is the previous OP optimized, whose C<op_next> points to I<o>.
-
-=back
-
-C<B::Generate> directly supports the creation of custom ops by name.
-
-=head1 AUTHORS
-
-Until May 1997, this document was maintained by Jeff Okamoto
-E<lt>okamoto@corp.hp.comE<gt>. It is now maintained as part of Perl
-itself by the Perl 5 Porters E<lt>perl5-porters@perl.orgE<gt>.
-
-With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
-Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
-Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
-Stephen McCamant, and Gurusamy Sarathy.
-
-=head1 SEE ALSO
-
-L<perlapi>, L<perlintern>, L<perlxs>, L<perlembed>
diff --git a/Master/tlpkg/tlperl/lib/pods/perlhack.pod b/Master/tlpkg/tlperl/lib/pods/perlhack.pod
deleted file mode 100644
index 63df5d5dfc3..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlhack.pod
+++ /dev/null
@@ -1,1144 +0,0 @@
-=encoding utf8
-
-=for comment
-Consistent formatting of this file is achieved with:
- perl ./Porting/podtidy pod/perlhack.pod
-
-=head1 NAME
-
-perlhack - How to hack on Perl
-
-=head1 DESCRIPTION
-
-This document explains how Perl development works. It includes details
-about the Perl 5 Porters email list, the Perl repository, the Perlbug
-bug tracker, patch guidelines, and commentary on Perl development
-philosophy.
-
-=head1 SUPER QUICK PATCH GUIDE
-
-If you just want to submit a single small patch like a pod fix, a test
-for a bug, comment fixes, etc., it's easy! Here's how:
-
-=over 4
-
-=item * Check out the source repository
-
-The perl source is in a git repository. You can clone the repository
-with the following command:
-
- % git clone git://perl5.git.perl.org/perl.git perl
-
-=item * Make your change
-
-Hack, hack, hack.
-
-=item * Test your change
-
-You can run all the tests with the following commands:
-
- % ./Configure -des -Dusedevel
- % make test
-
-Keep hacking until the tests pass.
-
-=item * Commit your change
-
-Committing your work will save the change I<on your local system>:
-
- % git commit -a -m 'Commit message goes here'
-
-Make sure the commit message describes your change in a single
-sentence. For example, "Fixed spelling errors in perlhack.pod".
-
-=item * Send your change to perlbug
-
-The next step is to submit your patch to the Perl core ticket system
-via email.
-
-Assuming your patch consists of a single git commit, the following
-writes the file as a MIME attachment, and sends it with a meaningful
-subject:
-
- % git format-patch -1 --attach
- % perlbug -s "[PATCH] $(git log -1 --oneline HEAD)" -f 0001-*.patch
-
-The perlbug program will ask you a few questions about your email
-address and the patch you're submitting. Once you've answered them it
-will submit your patch via email.
-
-=item * Thank you
-
-The porters appreciate the time you spent helping to make Perl better.
-Thank you!
-
-=back
-
-=head1 BUG REPORTING
-
-If you want to report a bug in Perl, you must use the F<perlbug>
-command line tool. This tool will ensure that your bug report includes
-all the relevant system and configuration information.
-
-To browse existing Perl bugs and patches, you can use the web interface
-at L<http://rt.perl.org/>.
-
-Please check the archive of the perl5-porters list (see below) and/or
-the bug tracking system before submitting a bug report. Often, you'll
-find that the bug has been reported already.
-
-You can log in to the bug tracking system and comment on existing bug
-reports. If you have additional information regarding an existing bug,
-please add it. This will help the porters fix the bug.
-
-=head1 PERL 5 PORTERS
-
-The perl5-porters (p5p) mailing list is where the Perl standard
-distribution is maintained and developed. The people who maintain Perl
-are also referred to as the "Perl 5 Porters", "p5p" or just the
-"porters".
-
-A searchable archive of the list is available at
-L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>. There is
-also another archive at
-L<http://archive.develooper.com/perl5-porters@perl.org/>.
-
-=head2 perl-changes mailing list
-
-The perl5-changes mailing list receives a copy of each patch that gets
-submitted to the maintenance and development branches of the perl
-repository. See L<http://lists.perl.org/list/perl5-changes.html> for
-subscription and archive information.
-
-=head2 #p5p on IRC
-
-Many porters are also active on the L<irc://irc.perl.org/#p5p> channel.
-Feel free to join the channel and ask questions about hacking on the
-Perl core.
-
-=head1 GETTING THE PERL SOURCE
-
-All of Perl's source code is kept centrally in a Git repository at
-I<perl5.git.perl.org>. The repository contains many Perl revisions from
-Perl 1 onwards and all the revisions from Perforce, the previous
-version control system.
-
-For much more detail on using git with the Perl repository, please see
-L<perlgit>.
-
-=head2 Read access via Git
-
-You will need a copy of Git for your computer. You can fetch a copy of
-the repository using the git protocol:
-
- % git clone git://perl5.git.perl.org/perl.git perl
-
-This clones the repository and makes a local copy in the F<perl>
-directory.
-
-If you cannot use the git protocol for firewall reasons, you can also
-clone via http, though this is much slower:
-
- % git clone http://perl5.git.perl.org/perl.git perl
-
-=head2 Read access via the web
-
-You may access the repository over the web. This allows you to browse
-the tree, see recent commits, subscribe to RSS feeds for the changes,
-search for particular commits and more. You may access it at
-L<http://perl5.git.perl.org/perl.git>. A mirror of the repository is
-found at L<http://github.com/mirrors/perl>.
-
-=head2 Read access via rsync
-
-You can also choose to use rsync to get a copy of the current source
-tree for the bleadperl branch and all maintenance branches:
-
- % rsync -avz rsync://perl5.git.perl.org/perl-current .
- % rsync -avz rsync://perl5.git.perl.org/perl-5.12.x .
- % rsync -avz rsync://perl5.git.perl.org/perl-5.10.x .
- % rsync -avz rsync://perl5.git.perl.org/perl-5.8.x .
- % rsync -avz rsync://perl5.git.perl.org/perl-5.6.x .
- % rsync -avz rsync://perl5.git.perl.org/perl-5.005xx .
-
-(Add the C<--delete> option to remove leftover files.)
-
-To get a full list of the available sync points:
-
- % rsync perl5.git.perl.org::
-
-=head2 Write access via git
-
-If you have a commit bit, please see L<perlgit> for more details on
-using git.
-
-=head1 PATCHING PERL
-
-If you're planning to do more extensive work than a single small fix,
-we encourage you to read the documentation below. This will help you
-focus your work and make your patches easier to incorporate into the
-Perl source.
-
-=head2 Submitting patches
-
-If you have a small patch to submit, please submit it via perlbug. You
-can also send email directly to perlbug@perl.org. Please note that
-messages sent to perlbug may be held in a moderation queue, so you
-won't receive a response immediately.
-
-You'll know your submission has been processed when you receive an
-email from our ticket tracking system. This email will give you a
-ticket number. Once your patch has made it to the ticket tracking
-system, it will also be sent to the perl5-porters@perl.org list.
-
-Patches are reviewed and discussed on the p5p list. Simple,
-uncontroversial patches will usually be applied without any discussion.
-When the patch is applied, the ticket will be updated and you will
-receive email. In addition, an email will be sent to the p5p list.
-
-In other cases, the patch will need more work or discussion. That will
-happen on the p5p list.
-
-You are encouraged to participate in the discussion and advocate for
-your patch. Sometimes your patch may get lost in the shuffle. It's
-appropriate to send a reminder email to p5p if no action has been taken
-in a month. Please remember that the Perl 5 developers are all
-volunteers, and be polite.
-
-Changes are always applied directly to the main development branch,
-called "blead". Some patches may be backported to a maintenance branch.
-If you think your patch is appropriate for the maintenance branch,
-please explain why when you submit it.
-
-=head2 Getting your patch accepted
-
-If you are submitting a code patch there are several things that you
-can do to help the Perl 5 Porters accept your patch.
-
-=head3 Patch style
-
-If you used git to check out the Perl source, then using C<git
-format-patch> will produce a patch in a style suitable for Perl. The
-C<format-patch> command produces one patch file for each commit you
-made. If you prefer to send a single patch for all commits, you can use
-C<git diff>.
-
- % git checkout blead
- % git pull
- % git diff blead my-branch-name
-
-This produces a patch based on the difference between blead and your
-current branch. It's important to make sure that blead is up to date
-before producing the diff, that's why we call C<git pull> first.
-
-We strongly recommend that you use git if possible. It will make your
-life easier, and ours as well.
-
-However, if you're not using git, you can still produce a suitable
-patch. You'll need a pristine copy of the Perl source to diff against.
-The porters prefer unified diffs. Using GNU C<diff>, you can produce a
-diff like this:
-
- % diff -Npurd perl.pristine perl.mine
-
-Make sure that you C<make realclean> in your copy of Perl to remove any
-build artifacts, or you may get a confusing result.
-
-=head3 Commit message
-
-As you craft each patch you intend to submit to the Perl core, it's
-important to write a good commit message. This is especially important
-if your submission will consist of a series of commits.
-
-The first line of the commit message should be a short description
-without a period. It should be no longer than the subject line of an
-email, 50 characters being a good rule of thumb.
-
-A lot of Git tools (Gitweb, GitHub, git log --pretty=oneline, ...) will
-only display the first line (cut off at 50 characters) when presenting
-commit summaries.
-
-The commit message should include a description of the problem that the
-patch corrects or new functionality that the patch adds.
-
-As a general rule of thumb, your commit message should help a
-programmer who knows the Perl core quickly understand what you were
-trying to do, how you were trying to do it, and why the change matters
-to Perl.
-
-=over 4
-
-=item * Why
-
-Your commit message should describe why the change you are making is
-important. When someone looks at your change in six months or six
-years, your intent should be clear.
-
-If you're deprecating a feature with the intent of later simplifying
-another bit of code, say so. If you're fixing a performance problem or
-adding a new feature to support some other bit of the core, mention
-that.
-
-=item * What
-
-Your commit message should describe what part of the Perl core you're
-changing and what you expect your patch to do.
-
-=item * How
-
-While it's not necessary for documentation changes, new tests or
-trivial patches, it's often worth explaining how your change works.
-Even if it's clear to you today, it may not be clear to a porter next
-month or next year.
-
-=back
-
-A commit message isn't intended to take the place of comments in your
-code. Commit messages should describe the change you made, while code
-comments should describe the current state of the code.
-
-If you've just implemented a new feature, complete with doc, tests and
-well-commented code, a brief commit message will often suffice. If,
-however, you've just changed a single character deep in the parser or
-lexer, you might need to write a small novel to ensure that future
-readers understand what you did and why you did it.
-
-=head3 Comments, Comments, Comments
-
-Be sure to adequately comment your code. While commenting every line is
-unnecessary, anything that takes advantage of side effects of
-operators, that creates changes that will be felt outside of the
-function being patched, or that others may find confusing should be
-documented. If you are going to err, it is better to err on the side of
-adding too many comments than too few.
-
-The best comments explain I<why> the code does what it does, not I<what
-it does>.
-
-=head3 Style
-
-In general, please follow the particular style of the code you are
-patching.
-
-In particular, follow these general guidelines for patching Perl
-sources:
-
-=over 4
-
-=item *
-
-8-wide tabs (no exceptions!)
-
-=item *
-
-4-wide indents for code, 2-wide indents for nested CPP #defines
-
-=item *
-
-Try hard not to exceed 79-columns
-
-=item *
-
-ANSI C prototypes
-
-=item *
-
-Uncuddled elses and "K&R" style for indenting control constructs
-
-=item *
-
-No C++ style (//) comments
-
-=item *
-
-Mark places that need to be revisited with XXX (and revisit often!)
-
-=item *
-
-Opening brace lines up with "if" when conditional spans multiple lines;
-should be at end-of-line otherwise
-
-=item *
-
-In function definitions, name starts in column 0 (return value is on
-previous line)
-
-=item *
-
-Single space after keywords that are followed by parens, no space
-between function name and following paren
-
-=item *
-
-Avoid assignments in conditionals, but if they're unavoidable, use
-extra paren, e.g. "if (a && (b = c)) ..."
-
-=item *
-
-"return foo;" rather than "return(foo);"
-
-=item *
-
-"if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
-
-=back
-
-=head3 Test suite
-
-If your patch changes code (rather than just changing documentation),
-you should also include one or more test cases which illustrate the bug
-you're fixing or validate the new functionality you're adding. In
-general, you should update an existing test file rather than create a
-new one.
-
-Your test suite additions should generally follow these guidelines
-(courtesy of Gurusamy Sarathy <gsar@activestate.com>):
-
-=over 4
-
-=item *
-
-Know what you're testing. Read the docs, and the source.
-
-=item *
-
-Tend to fail, not succeed.
-
-=item *
-
-Interpret results strictly.
-
-=item *
-
-Use unrelated features (this will flush out bizarre interactions).
-
-=item *
-
-Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
-
-=item *
-
-Avoid using hardcoded test numbers whenever possible (the EXPECTED/GOT
-found in t/op/tie.t is much more maintainable, and gives better failure
-reports).
-
-=item *
-
-Give meaningful error messages when a test fails.
-
-=item *
-
-Avoid using qx// and system() unless you are testing for them. If you
-do use them, make sure that you cover _all_ perl platforms.
-
-=item *
-
-Unlink any temporary files you create.
-
-=item *
-
-Promote unforeseen warnings to errors with $SIG{__WARN__}.
-
-=item *
-
-Be sure to use the libraries and modules shipped with the version being
-tested, not those that were already installed.
-
-=item *
-
-Add comments to the code explaining what you are testing for.
-
-=item *
-
-Make updating the '1..42' string unnecessary. Or make sure that you
-update it.
-
-=item *
-
-Test _all_ behaviors of a given operator, library, or function.
-
-Test all optional arguments.
-
-Test return values in various contexts (boolean, scalar, list, lvalue).
-
-Use both global and lexical variables.
-
-Don't forget the exceptional, pathological cases.
-
-=back
-
-=head2 Patching a core module
-
-This works just like patching anything else, with one extra
-consideration.
-
-Modules in the F<cpan/> directory of the source tree are maintained
-outside of the Perl core. When the author updates the module, the
-updates are simply copied into the core. See that module's
-documentation or its listing on L<http://search.cpan.org/> for more
-information on reporting bugs and submitting patches.
-
-In most cases, patches to modules in F<cpan/> should be sent upstream
-and should not be applied to the Perl core individually. If a patch to
-a file in F<cpan/> absolutely cannot wait for the fix to be made
-upstream, released to CPAN and copied to blead, you must add (or
-update) a C<CUSTOMIZED> entry in the F<"Porting/Maintainers.pl"> file
-to flag that a local modification has been made. See
-F<"Porting/Maintainers.pl"> for more details.
-
-In contrast, modules in the F<dist/> directory are maintained in the
-core.
-
-=head2 Updating perldelta
-
-For changes significant enough to warrant a F<pod/perldelta.pod> entry,
-the porters will greatly appreciate it if you submit a delta entry
-along with your actual change. Significant changes include, but are not
-limited to:
-
-=over 4
-
-=item *
-
-Adding, deprecating, or removing core features
-
-=item *
-
-Adding, deprecating, removing, or upgrading core or dual-life modules
-
-=item *
-
-Adding new core tests
-
-=item *
-
-Fixing security issues and user-visible bugs in the core
-
-=item *
-
-Changes that might break existing code, either on the perl or C level
-
-=item *
-
-Significant performance improvements
-
-=item *
-
-Adding, removing, or significantly changing documentation in the
-F<pod/> directory
-
-=item *
-
-Important platform-specific changes
-
-=back
-
-Please make sure you add the perldelta entry to the right section
-within F<pod/perldelta.pod>. More information on how to write good
-perldelta entries is available in the C<Style> section of
-F<Porting/how_to_write_a_perldelta.pod>.
-
-=head2 What makes for a good patch?
-
-New features and extensions to the language can be contentious. There
-is no specific set of criteria which determine what features get added,
-but here are some questions to consider when developing a patch:
-
-=head3 Does the concept match the general goals of Perl?
-
-Our goals include, but are not limited to:
-
-=over 4
-
-=item 1.
-
-Keep it fast, simple, and useful.
-
-=item 2.
-
-Keep features/concepts as orthogonal as possible.
-
-=item 3.
-
-No arbitrary limits (platforms, data sizes, cultures).
-
-=item 4.
-
-Keep it open and exciting to use/patch/advocate Perl everywhere.
-
-=item 5.
-
-Either assimilate new technologies, or build bridges to them.
-
-=back
-
-=head3 Where is the implementation?
-
-All the talk in the world is useless without an implementation. In
-almost every case, the person or people who argue for a new feature
-will be expected to be the ones who implement it. Porters capable of
-coding new features have their own agendas, and are not available to
-implement your (possibly good) idea.
-
-=head3 Backwards compatibility
-
-It's a cardinal sin to break existing Perl programs. New warnings can
-be contentious--some say that a program that emits warnings is not
-broken, while others say it is. Adding keywords has the potential to
-break programs, changing the meaning of existing token sequences or
-functions might break programs.
-
-The Perl 5 core includes mechanisms to help porters make backwards
-incompatible changes more compatible such as the L<feature> and
-L<deprecate> modules. Please use them when appropriate.
-
-=head3 Could it be a module instead?
-
-Perl 5 has extension mechanisms, modules and XS, specifically to avoid
-the need to keep changing the Perl interpreter. You can write modules
-that export functions, you can give those functions prototypes so they
-can be called like built-in functions, you can even write XS code to
-mess with the runtime data structures of the Perl interpreter if you
-want to implement really complicated things.
-
-Whenever possible, new features should be prototyped in a CPAN module
-before they will be considered for the core.
-
-=head3 Is the feature generic enough?
-
-Is this something that only the submitter wants added to the language,
-or is it broadly useful? Sometimes, instead of adding a feature with a
-tight focus, the porters might decide to wait until someone implements
-the more generalized feature.
-
-=head3 Does it potentially introduce new bugs?
-
-Radical rewrites of large chunks of the Perl interpreter have the
-potential to introduce new bugs.
-
-=head3 How big is it?
-
-The smaller and more localized the change, the better. Similarly, a
-series of small patches is greatly preferred over a single large patch.
-
-=head3 Does it preclude other desirable features?
-
-A patch is likely to be rejected if it closes off future avenues of
-development. For instance, a patch that placed a true and final
-interpretation on prototypes is likely to be rejected because there are
-still options for the future of prototypes that haven't been addressed.
-
-=head3 Is the implementation robust?
-
-Good patches (tight code, complete, correct) stand more chance of going
-in. Sloppy or incorrect patches might be placed on the back burner
-until the pumpking has time to fix, or might be discarded altogether
-without further notice.
-
-=head3 Is the implementation generic enough to be portable?
-
-The worst patches make use of system-specific features. It's highly
-unlikely that non-portable additions to the Perl language will be
-accepted.
-
-=head3 Is the implementation tested?
-
-Patches which change behaviour (fixing bugs or introducing new
-features) must include regression tests to verify that everything works
-as expected.
-
-Without tests provided by the original author, how can anyone else
-changing perl in the future be sure that they haven't unwittingly
-broken the behaviour the patch implements? And without tests, how can
-the patch's author be confident that his/her hard work put into the
-patch won't be accidentally thrown away by someone in the future?
-
-=head3 Is there enough documentation?
-
-Patches without documentation are probably ill-thought out or
-incomplete. No features can be added or changed without documentation,
-so submitting a patch for the appropriate pod docs as well as the
-source code is important.
-
-=head3 Is there another way to do it?
-
-Larry said "Although the Perl Slogan is I<There's More Than One Way to
-Do It>, I hesitate to make 10 ways to do something". This is a tricky
-heuristic to navigate, though--one man's essential addition is another
-man's pointless cruft.
-
-=head3 Does it create too much work?
-
-Work for the pumpking, work for Perl programmers, work for module
-authors, ... Perl is supposed to be easy.
-
-=head3 Patches speak louder than words
-
-Working code is always preferred to pie-in-the-sky ideas. A patch to
-add a feature stands a much higher chance of making it to the language
-than does a random feature request, no matter how fervently argued the
-request might be. This ties into "Will it be useful?", as the fact that
-someone took the time to make the patch demonstrates a strong desire
-for the feature.
-
-=head1 TESTING
-
-The core uses the same testing style as the rest of Perl, a simple
-"ok/not ok" run through Test::Harness, but there are a few special
-considerations.
-
-There are three ways to write a test in the core. L<Test::More>,
-F<t/test.pl> and ad hoc C<print $test ? "ok 42\n" : "not ok 42\n">. The
-decision of which to use depends on what part of the test suite you're
-working on. This is a measure to prevent a high-level failure (such as
-Config.pm breaking) from causing basic functionality tests to fail.
-
-The F<t/test.pl> library provides some of the features of
-L<Test::More>, but avoids loading most modules and uses as few core
-features as possible.
-
-If you write your own test, use the L<Test Anything
-Protocol|http://testanything.org>.
-
-=over 4
-
-=item * F<t/base> and F<t/comp>
-
-Since we don't know if require works, or even subroutines, use ad hoc
-tests for these two. Step carefully to avoid using the feature being
-tested.
-
-=item * F<t/cmd>, F<t/run>, F<t/io> and F<t/op>
-
-Now that basic require() and subroutines are tested, you can use the
-F<t/test.pl> library.
-
-You can also use certain libraries like Config conditionally, but be
-sure to skip the test gracefully if it's not there.
-
-=item * Everything else
-
-Now that the core of Perl is tested, L<Test::More> can and should be
-used. You can also use the full suite of core modules in the tests.
-
-=back
-
-When you say "make test", Perl uses the F<t/TEST> program to run the
-test suite (except under Win32 where it uses F<t/harness> instead). All
-tests are run from the F<t/> directory, B<not> the directory which
-contains the test. This causes some problems with the tests in F<lib/>,
-so here's some opportunity for some patching.
-
-You must be triply conscious of cross-platform concerns. This usually
-boils down to using L<File::Spec> and avoiding things like C<fork()>
-and C<system()> unless absolutely necessary.
-
-=head2 Special C<make test> targets
-
-There are various special make targets that can be used to test Perl
-slightly differently than the standard "test" target. Not all them are
-expected to give a 100% success rate. Many of them have several
-aliases, and many of them are not available on certain operating
-systems.
-
-=over 4
-
-=item * test_porting
-
-This runs some basic sanity tests on the source tree and helps catch
-basic errors before you submit a patch.
-
-=item * coretest
-
-Run F<perl> on all core tests (F<t/*> and F<lib/[a-z]*> pragma tests).
-
-(Not available on Win32)
-
-=item * test.deparse
-
-Run all the tests through L<B::Deparse>. Not all tests will succeed.
-
-(Not available on Win32)
-
-=item * test.taintwarn
-
-Run all tests with the B<-t> command-line switch. Not all tests are
-expected to succeed (until they're specifically fixed, of course).
-
-(Not available on Win32)
-
-=item * minitest
-
-Run F<miniperl> on F<t/base>, F<t/comp>, F<t/cmd>, F<t/run>, F<t/io>,
-F<t/op>, F<t/uni> and F<t/mro> tests.
-
-=item * test.valgrind check.valgrind utest.valgrind ucheck.valgrind
-
-(Only in Linux) Run all the tests using the memory leak + naughty
-memory access tool "valgrind". The log files will be named
-F<testname.valgrind>.
-
-=item * test.torture torturetest
-
-Run all the usual tests and some extra tests. As of Perl 5.8.0, the
-only extra tests are Abigail's JAPHs, F<t/japh/abigail.t>.
-
-You can also run the torture test with F<t/harness> by giving
-C<-torture> argument to F<t/harness>.
-
-=item * utest ucheck test.utf8 check.utf8
-
-Run all the tests with -Mutf8. Not all tests will succeed.
-
-(Not available on Win32)
-
-=item * minitest.utf16 test.utf16
-
-Runs the tests with UTF-16 encoded scripts, encoded with different
-versions of this encoding.
-
-C<make utest.utf16> runs the test suite with a combination of C<-utf8>
-and C<-utf16> arguments to F<t/TEST>.
-
-(Not available on Win32)
-
-=item * test_harness
-
-Run the test suite with the F<t/harness> controlling program, instead
-of F<t/TEST>. F<t/harness> is more sophisticated, and uses the
-L<Test::Harness> module, thus using this test target supposes that perl
-mostly works. The main advantage for our purposes is that it prints a
-detailed summary of failed tests at the end. Also, unlike F<t/TEST>, it
-doesn't redirect stderr to stdout.
-
-Note that under Win32 F<t/harness> is always used instead of F<t/TEST>,
-so there is no special "test_harness" target.
-
-Under Win32's "test" target you may use the TEST_SWITCHES and
-TEST_FILES environment variables to control the behaviour of
-F<t/harness>. This means you can say
-
- nmake test TEST_FILES="op/*.t"
- nmake test TEST_SWITCHES="-torture" TEST_FILES="op/*.t"
-
-=item * test-notty test_notty
-
-Sets PERL_SKIP_TTY_TEST to true before running normal test.
-
-=back
-
-=head2 Parallel tests
-
-The core distribution can now run its regression tests in parallel on
-Unix-like platforms. Instead of running C<make test>, set C<TEST_JOBS>
-in your environment to the number of tests to run in parallel, and run
-C<make test_harness>. On a Bourne-like shell, this can be done as
-
- TEST_JOBS=3 make test_harness # Run 3 tests in parallel
-
-An environment variable is used, rather than parallel make itself,
-because L<TAP::Harness> needs to be able to schedule individual
-non-conflicting test scripts itself, and there is no standard interface
-to C<make> utilities to interact with their job schedulers.
-
-Note that currently some test scripts may fail when run in parallel
-(most notably F<ext/IO/t/io_dir.t>). If necessary, run just the failing
-scripts again sequentially and see if the failures go away.
-
-=head2 Running tests by hand
-
-You can run part of the test suite by hand by using one of the
-following commands from the F<t/> directory:
-
- ./perl -I../lib TEST list-of-.t-files
-
-or
-
- ./perl -I../lib harness list-of-.t-files
-
-(If you don't specify test scripts, the whole test suite will be run.)
-
-=head2 Using F<t/harness> for testing
-
-If you use C<harness> for testing, you have several command line
-options available to you. The arguments are as follows, and are in the
-order that they must appear if used together.
-
- harness -v -torture -re=pattern LIST OF FILES TO TEST
- harness -v -torture -re LIST OF PATTERNS TO MATCH
-
-If C<LIST OF FILES TO TEST> is omitted, the file list is obtained from
-the manifest. The file list may include shell wildcards which will be
-expanded out.
-
-=over 4
-
-=item * -v
-
-Run the tests under verbose mode so you can see what tests were run,
-and debug output.
-
-=item * -torture
-
-Run the torture tests as well as the normal set.
-
-=item * -re=PATTERN
-
-Filter the file list so that all the test files run match PATTERN. Note
-that this form is distinct from the B<-re LIST OF PATTERNS> form below
-in that it allows the file list to be provided as well.
-
-=item * -re LIST OF PATTERNS
-
-Filter the file list so that all the test files run match
-/(LIST|OF|PATTERNS)/. Note that with this form the patterns are joined
-by '|' and you cannot supply a list of files, instead the test files
-are obtained from the MANIFEST.
-
-=back
-
-You can run an individual test by a command similar to
-
- ./perl -I../lib path/to/foo.t
-
-except that the harnesses set up some environment variables that may
-affect the execution of the test:
-
-=over 4
-
-=item * PERL_CORE=1
-
-indicates that we're running this test as part of the perl core test
-suite. This is useful for modules that have a dual life on CPAN.
-
-=item * PERL_DESTRUCT_LEVEL=2
-
-is set to 2 if it isn't set already (see
-L<perlhacktips/PERL_DESTRUCT_LEVEL>).
-
-=item * PERL
-
-(used only by F<t/TEST>) if set, overrides the path to the perl
-executable that should be used to run the tests (the default being
-F<./perl>).
-
-=item * PERL_SKIP_TTY_TEST
-
-if set, tells to skip the tests that need a terminal. It's actually set
-automatically by the Makefile, but can also be forced artificially by
-running 'make test_notty'.
-
-=back
-
-=head3 Other environment variables that may influence tests
-
-=over 4
-
-=item * PERL_TEST_Net_Ping
-
-Setting this variable runs all the Net::Ping modules tests, otherwise
-some tests that interact with the outside world are skipped. See
-L<perl58delta>.
-
-=item * PERL_TEST_NOVREXX
-
-Setting this variable skips the vrexx.t tests for OS2::REXX.
-
-=item * PERL_TEST_NUMCONVERTS
-
-This sets a variable in op/numconvert.t.
-
-=back
-
-See also the documentation for the Test and Test::Harness modules, for
-more environment variables that affect testing.
-
-=head1 MORE READING FOR GUTS HACKERS
-
-To hack on the Perl guts, you'll need to read the following things:
-
-=over 4
-
-=item * L<perlsource>
-
-An overview of the Perl source tree. This will help you find the files
-you're looking for.
-
-=item * L<perlinterp>
-
-An overview of the Perl interpreter source code and some details on how
-Perl does what it does.
-
-=item * L<perlhacktut>
-
-This document walks through the creation of a small patch to Perl's C
-code. If you're just getting started with Perl core hacking, this will
-help you understand how it works.
-
-=item * L<perlhacktips>
-
-More details on hacking the Perl core. This document focuses on lower
-level details such as how to write tests, compilation issues,
-portability, debugging, etc.
-
-If you plan on doing serious C hacking, make sure to read this.
-
-=item * L<perlguts>
-
-This is of paramount importance, since it's the documentation of what
-goes where in the Perl source. Read it over a couple of times and it
-might start to make sense - don't worry if it doesn't yet, because the
-best way to study it is to read it in conjunction with poking at Perl
-source, and we'll do that later on.
-
-Gisle Aas's "illustrated perlguts", also known as I<illguts>, has very
-helpful pictures:
-
-L<http://search.cpan.org/dist/illguts/>
-
-=item * L<perlxstut> and L<perlxs>
-
-A working knowledge of XSUB programming is incredibly useful for core
-hacking; XSUBs use techniques drawn from the PP code, the portion of
-the guts that actually executes a Perl program. It's a lot gentler to
-learn those techniques from simple examples and explanation than from
-the core itself.
-
-=item * L<perlapi>
-
-The documentation for the Perl API explains what some of the internal
-functions do, as well as the many macros used in the source.
-
-=item * F<Porting/pumpkin.pod>
-
-This is a collection of words of wisdom for a Perl porter; some of it
-is only useful to the pumpkin holder, but most of it applies to anyone
-wanting to go about Perl development.
-
-=item * The perl5-porters FAQ
-
-This should be available from
-http://dev.perl.org/perl5/docs/p5p-faq.html . It contains hints on
-reading perl5-porters, information on how perl5-porters works and how
-Perl development in general works.
-
-=back
-
-=head1 CPAN TESTERS AND PERL SMOKERS
-
-The CPAN testers ( http://testers.cpan.org/ ) are a group of volunteers
-who test CPAN modules on a variety of platforms.
-
-Perl Smokers ( http://www.nntp.perl.org/group/perl.daily-build/ and
-http://www.nntp.perl.org/group/perl.daily-build.reports/ )
-automatically test Perl source releases on platforms with various
-configurations.
-
-Both efforts welcome volunteers. In order to get involved in smoke
-testing of the perl itself visit
-L<http://search.cpan.org/dist/Test-Smoke/>. In order to start smoke
-testing CPAN modules visit
-L<http://search.cpan.org/dist/CPANPLUS-YACSmoke/> or
-L<http://search.cpan.org/dist/minismokebox/> or
-L<http://search.cpan.org/dist/CPAN-Reporter/>.
-
-=head1 WHAT NEXT?
-
-If you've read all the documentation in the document and the ones
-listed above, you're more than ready to hack on Perl.
-
-Here's some more recommendations
-
-=over 4
-
-=item *
-
-Subscribe to perl5-porters, follow the patches and try and understand
-them; don't be afraid to ask if there's a portion you're not clear on -
-who knows, you may unearth a bug in the patch...
-
-=item *
-
-Do read the README associated with your operating system, e.g.
-README.aix on the IBM AIX OS. Don't hesitate to supply patches to that
-README if you find anything missing or changed over a new OS release.
-
-=item *
-
-Find an area of Perl that seems interesting to you, and see if you can
-work out how it works. Scan through the source, and step over it in the
-debugger. Play, poke, investigate, fiddle! You'll probably get to
-understand not just your chosen area but a much wider range of
-F<perl>'s activity as well, and probably sooner than you'd think.
-
-=back
-
-=head2 "The Road goes ever on and on, down from the door where it began."
-
-If you can do these things, you've started on the long road to Perl
-porting. Thanks for wanting to help make Perl better - and happy
-hacking!
-
-=head2 Metaphoric Quotations
-
-If you recognized the quote about the Road above, you're in luck.
-
-Most software projects begin each file with a literal description of
-each file's purpose. Perl instead begins each with a literary allusion
-to that file's purpose.
-
-Like chapters in many books, all top-level Perl source files (along
-with a few others here and there) begin with an epigrammatic
-inscription that alludes, indirectly and metaphorically, to the
-material you're about to read.
-
-Quotations are taken from writings of J.R.R. Tolkien pertaining to his
-Legendarium, almost always from I<The Lord of the Rings>. Chapters and
-page numbers are given using the following editions:
-
-=over 4
-
-=item *
-
-I<The Hobbit>, by J.R.R. Tolkien. The hardcover, 70th-anniversary
-edition of 2007 was used, published in the UK by Harper Collins
-Publishers and in the US by the Houghton Mifflin Company.
-
-=item *
-
-I<The Lord of the Rings>, by J.R.R. Tolkien. The hardcover,
-50th-anniversary edition of 2004 was used, published in the UK by
-Harper Collins Publishers and in the US by the Houghton Mifflin
-Company.
-
-=item *
-
-I<The Lays of Beleriand>, by J.R.R. Tolkien and published posthumously
-by his son and literary executor, C.J.R. Tolkien, being the 3rd of the
-12 volumes in Christopher's mammoth I<History of Middle Earth>. Page
-numbers derive from the hardcover edition, first published in 1983 by
-George Allen & Unwin; no page numbers changed for the special 3-volume
-omnibus edition of 2002 or the various trade-paper editions, all again
-now by Harper Collins or Houghton Mifflin.
-
-=back
-
-Other JRRT books fair game for quotes would thus include I<The
-Adventures of Tom Bombadil>, I<The Silmarillion>, I<Unfinished Tales>,
-and I<The Tale of the Children of Hurin>, all but the first
-posthumously assembled by CJRT. But I<The Lord of the Rings> itself is
-perfectly fine and probably best to quote from, provided you can find a
-suitable quote there.
-
-So if you were to supply a new, complete, top-level source file to add
-to Perl, you should conform to this peculiar practice by yourself
-selecting an appropriate quotation from Tolkien, retaining the original
-spelling and punctuation and using the same format the rest of the
-quotes are in. Indirect and oblique is just fine; remember, it's a
-metaphor, so being meta is, after all, what it's for.
-
-=head1 AUTHOR
-
-This document was originally written by Nathan Torkington, and is
-maintained by the perl5-porters mailing list.
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlhacktips.pod b/Master/tlpkg/tlperl/lib/pods/perlhacktips.pod
deleted file mode 100644
index bb995f33005..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlhacktips.pod
+++ /dev/null
@@ -1,1461 +0,0 @@
-
-=encoding utf8
-
-=for comment
-Consistent formatting of this file is achieved with:
- perl ./Porting/podtidy pod/perlhacktips.pod
-
-=head1 NAME
-
-perlhacktips - Tips for Perl core C code hacking
-
-=head1 DESCRIPTION
-
-This document will help you learn the best way to go about hacking on
-the Perl core C code. It covers common problems, debugging, profiling,
-and more.
-
-If you haven't read L<perlhack> and L<perlhacktut> yet, you might want
-to do that first.
-
-=head1 COMMON PROBLEMS
-
-Perl source plays by ANSI C89 rules: no C99 (or C++) extensions. In
-some cases we have to take pre-ANSI requirements into consideration.
-You don't care about some particular platform having broken Perl? I
-hear there is still a strong demand for J2EE programmers.
-
-=head2 Perl environment problems
-
-=over 4
-
-=item *
-
-Not compiling with threading
-
-Compiling with threading (-Duseithreads) completely rewrites the
-function prototypes of Perl. You better try your changes with that.
-Related to this is the difference between "Perl_-less" and "Perl_-ly"
-APIs, for example:
-
- Perl_sv_setiv(aTHX_ ...);
- sv_setiv(...);
-
-The first one explicitly passes in the context, which is needed for
-e.g. threaded builds. The second one does that implicitly; do not get
-them mixed. If you are not passing in a aTHX_, you will need to do a
-dTHX (or a dVAR) as the first thing in the function.
-
-See L<perlguts/"How multiple interpreters and concurrency are
-supported"> for further discussion about context.
-
-=item *
-
-Not compiling with -DDEBUGGING
-
-The DEBUGGING define exposes more code to the compiler, therefore more
-ways for things to go wrong. You should try it.
-
-=item *
-
-Introducing (non-read-only) globals
-
-Do not introduce any modifiable globals, truly global or file static.
-They are bad form and complicate multithreading and other forms of
-concurrency. The right way is to introduce them as new interpreter
-variables, see F<intrpvar.h> (at the very end for binary
-compatibility).
-
-Introducing read-only (const) globals is okay, as long as you verify
-with e.g. C<nm libperl.a|egrep -v ' [TURtr] '> (if your C<nm> has
-BSD-style output) that the data you added really is read-only. (If it
-is, it shouldn't show up in the output of that command.)
-
-If you want to have static strings, make them constant:
-
- static const char etc[] = "...";
-
-If you want to have arrays of constant strings, note carefully the
-right combination of C<const>s:
-
- static const char * const yippee[] =
- {"hi", "ho", "silver"};
-
-There is a way to completely hide any modifiable globals (they are all
-moved to heap), the compilation setting
-C<-DPERL_GLOBAL_STRUCT_PRIVATE>. It is not normally used, but can be
-used for testing, read more about it in L<perlguts/"Background and
-PERL_IMPLICIT_CONTEXT">.
-
-=item *
-
-Not exporting your new function
-
-Some platforms (Win32, AIX, VMS, OS/2, to name a few) require any
-function that is part of the public API (the shared Perl library) to be
-explicitly marked as exported. See the discussion about F<embed.pl> in
-L<perlguts>.
-
-=item *
-
-Exporting your new function
-
-The new shiny result of either genuine new functionality or your
-arduous refactoring is now ready and correctly exported. So what could
-possibly go wrong?
-
-Maybe simply that your function did not need to be exported in the
-first place. Perl has a long and not so glorious history of exporting
-functions that it should not have.
-
-If the function is used only inside one source code file, make it
-static. See the discussion about F<embed.pl> in L<perlguts>.
-
-If the function is used across several files, but intended only for
-Perl's internal use (and this should be the common case), do not export
-it to the public API. See the discussion about F<embed.pl> in
-L<perlguts>.
-
-=back
-
-=head2 Portability problems
-
-The following are common causes of compilation and/or execution
-failures, not common to Perl as such. The C FAQ is good bedtime
-reading. Please test your changes with as many C compilers and
-platforms as possible; we will, anyway, and it's nice to save oneself
-from public embarrassment.
-
-If using gcc, you can add the C<-std=c89> option which will hopefully
-catch most of these unportabilities. (However it might also catch
-incompatibilities in your system's header files.)
-
-Use the Configure C<-Dgccansipedantic> flag to enable the gcc C<-ansi
--pedantic> flags which enforce stricter ANSI rules.
-
-If using the C<gcc -Wall> note that not all the possible warnings (like
-C<-Wunitialized>) are given unless you also compile with C<-O>.
-
-Note that if using gcc, starting from Perl 5.9.5 the Perl core source
-code files (the ones at the top level of the source code distribution,
-but not e.g. the extensions under ext/) are automatically compiled with
-as many as possible of the C<-std=c89>, C<-ansi>, C<-pedantic>, and a
-selection of C<-W> flags (see cflags.SH).
-
-Also study L<perlport> carefully to avoid any bad assumptions about the
-operating system, filesystems, and so forth.
-
-You may once in a while try a "make microperl" to see whether we can
-still compile Perl with just the bare minimum of interfaces. (See
-README.micro.)
-
-Do not assume an operating system indicates a certain compiler.
-
-=over 4
-
-=item *
-
-Casting pointers to integers or casting integers to pointers
-
- void castaway(U8* p)
- {
- IV i = p;
-
-or
-
- void castaway(U8* p)
- {
- IV i = (IV)p;
-
-Both are bad, and broken, and unportable. Use the PTR2IV() macro that
-does it right. (Likewise, there are PTR2UV(), PTR2NV(), INT2PTR(), and
-NUM2PTR().)
-
-=item *
-
-Casting between data function pointers and data pointers
-
-Technically speaking casting between function pointers and data
-pointers is unportable and undefined, but practically speaking it seems
-to work, but you should use the FPTR2DPTR() and DPTR2FPTR() macros.
-Sometimes you can also play games with unions.
-
-=item *
-
-Assuming sizeof(int) == sizeof(long)
-
-There are platforms where longs are 64 bits, and platforms where ints
-are 64 bits, and while we are out to shock you, even platforms where
-shorts are 64 bits. This is all legal according to the C standard. (In
-other words, "long long" is not a portable way to specify 64 bits, and
-"long long" is not even guaranteed to be any wider than "long".)
-
-Instead, use the definitions IV, UV, IVSIZE, I32SIZE, and so forth.
-Avoid things like I32 because they are B<not> guaranteed to be
-I<exactly> 32 bits, they are I<at least> 32 bits, nor are they
-guaranteed to be B<int> or B<long>. If you really explicitly need
-64-bit variables, use I64 and U64, but only if guarded by HAS_QUAD.
-
-=item *
-
-Assuming one can dereference any type of pointer for any type of data
-
- char *p = ...;
- long pony = *p; /* BAD */
-
-Many platforms, quite rightly so, will give you a core dump instead of
-a pony if the p happens not to be correctly aligned.
-
-=item *
-
-Lvalue casts
-
- (int)*p = ...; /* BAD */
-
-Simply not portable. Get your lvalue to be of the right type, or maybe
-use temporary variables, or dirty tricks with unions.
-
-=item *
-
-Assume B<anything> about structs (especially the ones you don't
-control, like the ones coming from the system headers)
-
-=over 8
-
-=item *
-
-That a certain field exists in a struct
-
-=item *
-
-That no other fields exist besides the ones you know of
-
-=item *
-
-That a field is of certain signedness, sizeof, or type
-
-=item *
-
-That the fields are in a certain order
-
-=over 8
-
-=item *
-
-While C guarantees the ordering specified in the struct definition,
-between different platforms the definitions might differ
-
-=back
-
-=item *
-
-That the sizeof(struct) or the alignments are the same everywhere
-
-=over 8
-
-=item *
-
-There might be padding bytes between the fields to align the fields -
-the bytes can be anything
-
-=item *
-
-Structs are required to be aligned to the maximum alignment required by
-the fields - which for native types is for usually equivalent to
-sizeof() of the field
-
-=back
-
-=back
-
-=item *
-
-Assuming the character set is ASCIIish
-
-Perl can compile and run under EBCDIC platforms. See L<perlebcdic>.
-This is transparent for the most part, but because the character sets
-differ, you shouldn't use numeric (decimal, octal, nor hex) constants
-to refer to characters. You can safely say 'A', but not 0x41. You can
-safely say '\n', but not \012. If a character doesn't have a trivial
-input form, you can create a #define for it in both C<utfebcdic.h> and
-C<utf8.h>, so that it resolves to different values depending on the
-character set being used. (There are three different EBCDIC character
-sets defined in C<utfebcdic.h>, so it might be best to insert the
-#define three times in that file.)
-
-Also, the range 'A' - 'Z' in ASCII is an unbroken sequence of 26 upper
-case alphabetic characters. That is not true in EBCDIC. Nor for 'a' to
-'z'. But '0' - '9' is an unbroken range in both systems. Don't assume
-anything about other ranges.
-
-Many of the comments in the existing code ignore the possibility of
-EBCDIC, and may be wrong therefore, even if the code works. This is
-actually a tribute to the successful transparent insertion of being
-able to handle EBCDIC without having to change pre-existing code.
-
-UTF-8 and UTF-EBCDIC are two different encodings used to represent
-Unicode code points as sequences of bytes. Macros with the same names
-(but different definitions) in C<utf8.h> and C<utfebcdic.h> are used to
-allow the calling code to think that there is only one such encoding.
-This is almost always referred to as C<utf8>, but it means the EBCDIC
-version as well. Again, comments in the code may well be wrong even if
-the code itself is right. For example, the concept of C<invariant
-characters> differs between ASCII and EBCDIC. On ASCII platforms, only
-characters that do not have the high-order bit set (i.e. whose ordinals
-are strict ASCII, 0 - 127) are invariant, and the documentation and
-comments in the code may assume that, often referring to something
-like, say, C<hibit>. The situation differs and is not so simple on
-EBCDIC machines, but as long as the code itself uses the
-C<NATIVE_IS_INVARIANT()> macro appropriately, it works, even if the
-comments are wrong.
-
-=item *
-
-Assuming the character set is just ASCII
-
-ASCII is a 7 bit encoding, but bytes have 8 bits in them. The 128 extra
-characters have different meanings depending on the locale. Absent a
-locale, currently these extra characters are generally considered to be
-unassigned, and this has presented some problems. This is being changed
-starting in 5.12 so that these characters will be considered to be
-Latin-1 (ISO-8859-1).
-
-=item *
-
-Mixing #define and #ifdef
-
- #define BURGLE(x) ... \
- #ifdef BURGLE_OLD_STYLE /* BAD */
- ... do it the old way ... \
- #else
- ... do it the new way ... \
- #endif
-
-You cannot portably "stack" cpp directives. For example in the above
-you need two separate BURGLE() #defines, one for each #ifdef branch.
-
-=item *
-
-Adding non-comment stuff after #endif or #else
-
- #ifdef SNOSH
- ...
- #else !SNOSH /* BAD */
- ...
- #endif SNOSH /* BAD */
-
-The #endif and #else cannot portably have anything non-comment after
-them. If you want to document what is going (which is a good idea
-especially if the branches are long), use (C) comments:
-
- #ifdef SNOSH
- ...
- #else /* !SNOSH */
- ...
- #endif /* SNOSH */
-
-The gcc option C<-Wendif-labels> warns about the bad variant (by
-default on starting from Perl 5.9.4).
-
-=item *
-
-Having a comma after the last element of an enum list
-
- enum color {
- CERULEAN,
- CHARTREUSE,
- CINNABAR, /* BAD */
- };
-
-is not portable. Leave out the last comma.
-
-Also note that whether enums are implicitly morphable to ints varies
-between compilers, you might need to (int).
-
-=item *
-
-Using //-comments
-
- // This function bamfoodles the zorklator. /* BAD */
-
-That is C99 or C++. Perl is C89. Using the //-comments is silently
-allowed by many C compilers but cranking up the ANSI C89 strictness
-(which we like to do) causes the compilation to fail.
-
-=item *
-
-Mixing declarations and code
-
- void zorklator()
- {
- int n = 3;
- set_zorkmids(n); /* BAD */
- int q = 4;
-
-That is C99 or C++. Some C compilers allow that, but you shouldn't.
-
-The gcc option C<-Wdeclaration-after-statements> scans for such
-problems (by default on starting from Perl 5.9.4).
-
-=item *
-
-Introducing variables inside for()
-
- for(int i = ...; ...; ...) { /* BAD */
-
-That is C99 or C++. While it would indeed be awfully nice to have that
-also in C89, to limit the scope of the loop variable, alas, we cannot.
-
-=item *
-
-Mixing signed char pointers with unsigned char pointers
-
- int foo(char *s) { ... }
- ...
- unsigned char *t = ...; /* Or U8* t = ... */
- foo(t); /* BAD */
-
-While this is legal practice, it is certainly dubious, and downright
-fatal in at least one platform: for example VMS cc considers this a
-fatal error. One cause for people often making this mistake is that a
-"naked char" and therefore dereferencing a "naked char pointer" have an
-undefined signedness: it depends on the compiler and the flags of the
-compiler and the underlying platform whether the result is signed or
-unsigned. For this very same reason using a 'char' as an array index is
-bad.
-
-=item *
-
-Macros that have string constants and their arguments as substrings of
-the string constants
-
- #define FOO(n) printf("number = %d\n", n) /* BAD */
- FOO(10);
-
-Pre-ANSI semantics for that was equivalent to
-
- printf("10umber = %d\10");
-
-which is probably not what you were expecting. Unfortunately at least
-one reasonably common and modern C compiler does "real backward
-compatibility" here, in AIX that is what still happens even though the
-rest of the AIX compiler is very happily C89.
-
-=item *
-
-Using printf formats for non-basic C types
-
- IV i = ...;
- printf("i = %d\n", i); /* BAD */
-
-While this might by accident work in some platform (where IV happens to
-be an C<int>), in general it cannot. IV might be something larger. Even
-worse the situation is with more specific types (defined by Perl's
-configuration step in F<config.h>):
-
- Uid_t who = ...;
- printf("who = %d\n", who); /* BAD */
-
-The problem here is that Uid_t might be not only not C<int>-wide but it
-might also be unsigned, in which case large uids would be printed as
-negative values.
-
-There is no simple solution to this because of printf()'s limited
-intelligence, but for many types the right format is available as with
-either 'f' or '_f' suffix, for example:
-
- IVdf /* IV in decimal */
- UVxf /* UV is hexadecimal */
-
- printf("i = %"IVdf"\n", i); /* The IVdf is a string constant. */
-
- Uid_t_f /* Uid_t in decimal */
-
- printf("who = %"Uid_t_f"\n", who);
-
-Or you can try casting to a "wide enough" type:
-
- printf("i = %"IVdf"\n", (IV)something_very_small_and_signed);
-
-Also remember that the C<%p> format really does require a void pointer:
-
- U8* p = ...;
- printf("p = %p\n", (void*)p);
-
-The gcc option C<-Wformat> scans for such problems.
-
-=item *
-
-Blindly using variadic macros
-
-gcc has had them for a while with its own syntax, and C99 brought them
-with a standardized syntax. Don't use the former, and use the latter
-only if the HAS_C99_VARIADIC_MACROS is defined.
-
-=item *
-
-Blindly passing va_list
-
-Not all platforms support passing va_list to further varargs (stdarg)
-functions. The right thing to do is to copy the va_list using the
-Perl_va_copy() if the NEED_VA_COPY is defined.
-
-=item *
-
-Using gcc statement expressions
-
- val = ({...;...;...}); /* BAD */
-
-While a nice extension, it's not portable. The Perl code does
-admittedly use them if available to gain some extra speed (essentially
-as a funky form of inlining), but you shouldn't.
-
-=item *
-
-Binding together several statements in a macro
-
-Use the macros STMT_START and STMT_END.
-
- STMT_START {
- ...
- } STMT_END
-
-=item *
-
-Testing for operating systems or versions when should be testing for
-features
-
- #ifdef __FOONIX__ /* BAD */
- foo = quux();
- #endif
-
-Unless you know with 100% certainty that quux() is only ever available
-for the "Foonix" operating system B<and> that is available B<and>
-correctly working for B<all> past, present, B<and> future versions of
-"Foonix", the above is very wrong. This is more correct (though still
-not perfect, because the below is a compile-time check):
-
- #ifdef HAS_QUUX
- foo = quux();
- #endif
-
-How does the HAS_QUUX become defined where it needs to be? Well, if
-Foonix happens to be Unixy enough to be able to run the Configure
-script, and Configure has been taught about detecting and testing
-quux(), the HAS_QUUX will be correctly defined. In other platforms, the
-corresponding configuration step will hopefully do the same.
-
-In a pinch, if you cannot wait for Configure to be educated, or if you
-have a good hunch of where quux() might be available, you can
-temporarily try the following:
-
- #if (defined(__FOONIX__) || defined(__BARNIX__))
- # define HAS_QUUX
- #endif
-
- ...
-
- #ifdef HAS_QUUX
- foo = quux();
- #endif
-
-But in any case, try to keep the features and operating systems
-separate.
-
-=back
-
-=head2 Problematic System Interfaces
-
-=over 4
-
-=item *
-
-malloc(0), realloc(0), calloc(0, 0) are non-portable. To be portable
-allocate at least one byte. (In general you should rarely need to work
-at this low level, but instead use the various malloc wrappers.)
-
-=item *
-
-snprintf() - the return type is unportable. Use my_snprintf() instead.
-
-=back
-
-=head2 Security problems
-
-Last but not least, here are various tips for safer coding.
-
-=over 4
-
-=item *
-
-Do not use gets()
-
-Or we will publicly ridicule you. Seriously.
-
-=item *
-
-Do not use strcpy() or strcat() or strncpy() or strncat()
-
-Use my_strlcpy() and my_strlcat() instead: they either use the native
-implementation, or Perl's own implementation (borrowed from the public
-domain implementation of INN).
-
-=item *
-
-Do not use sprintf() or vsprintf()
-
-If you really want just plain byte strings, use my_snprintf() and
-my_vsnprintf() instead, which will try to use snprintf() and
-vsnprintf() if those safer APIs are available. If you want something
-fancier than a plain byte string, use SVs and Perl_sv_catpvf().
-
-=back
-
-=head1 DEBUGGING
-
-You can compile a special debugging version of Perl, which allows you
-to use the C<-D> option of Perl to tell more about what Perl is doing.
-But sometimes there is no alternative than to dive in with a debugger,
-either to see the stack trace of a core dump (very useful in a bug
-report), or trying to figure out what went wrong before the core dump
-happened, or how did we end up having wrong or unexpected results.
-
-=head2 Poking at Perl
-
-To really poke around with Perl, you'll probably want to build Perl for
-debugging, like this:
-
- ./Configure -d -D optimize=-g
- make
-
-C<-g> is a flag to the C compiler to have it produce debugging
-information which will allow us to step through a running program, and
-to see in which C function we are at (without the debugging information
-we might see only the numerical addresses of the functions, which is
-not very helpful).
-
-F<Configure> will also turn on the C<DEBUGGING> compilation symbol
-which enables all the internal debugging code in Perl. There are a
-whole bunch of things you can debug with this: L<perlrun> lists them
-all, and the best way to find out about them is to play about with
-them. The most useful options are probably
-
- l Context (loop) stack processing
- t Trace execution
- o Method and overloading resolution
- c String/numeric conversions
-
-Some of the functionality of the debugging code can be achieved using
-XS modules.
-
- -Dr => use re 'debug'
- -Dx => use O 'Debug'
-
-=head2 Using a source-level debugger
-
-If the debugging output of C<-D> doesn't help you, it's time to step
-through perl's execution with a source-level debugger.
-
-=over 3
-
-=item *
-
-We'll use C<gdb> for our examples here; the principles will apply to
-any debugger (many vendors call their debugger C<dbx>), but check the
-manual of the one you're using.
-
-=back
-
-To fire up the debugger, type
-
- gdb ./perl
-
-Or if you have a core dump:
-
- gdb ./perl core
-
-You'll want to do that in your Perl source tree so the debugger can
-read the source code. You should see the copyright message, followed by
-the prompt.
-
- (gdb)
-
-C<help> will get you into the documentation, but here are the most
-useful commands:
-
-=over 3
-
-=item * run [args]
-
-Run the program with the given arguments.
-
-=item * break function_name
-
-=item * break source.c:xxx
-
-Tells the debugger that we'll want to pause execution when we reach
-either the named function (but see L<perlguts/Internal Functions>!) or
-the given line in the named source file.
-
-=item * step
-
-Steps through the program a line at a time.
-
-=item * next
-
-Steps through the program a line at a time, without descending into
-functions.
-
-=item * continue
-
-Run until the next breakpoint.
-
-=item * finish
-
-Run until the end of the current function, then stop again.
-
-=item * 'enter'
-
-Just pressing Enter will do the most recent operation again - it's a
-blessing when stepping through miles of source code.
-
-=item * print
-
-Execute the given C code and print its results. B<WARNING>: Perl makes
-heavy use of macros, and F<gdb> does not necessarily support macros
-(see later L</"gdb macro support">). You'll have to substitute them
-yourself, or to invoke cpp on the source code files (see L</"The .i
-Targets">) So, for instance, you can't say
-
- print SvPV_nolen(sv)
-
-but you have to say
-
- print Perl_sv_2pv_nolen(sv)
-
-=back
-
-You may find it helpful to have a "macro dictionary", which you can
-produce by saying C<cpp -dM perl.c | sort>. Even then, F<cpp> won't
-recursively apply those macros for you.
-
-=head2 gdb macro support
-
-Recent versions of F<gdb> have fairly good macro support, but in order
-to use it you'll need to compile perl with macro definitions included
-in the debugging information. Using F<gcc> version 3.1, this means
-configuring with C<-Doptimize=-g3>. Other compilers might use a
-different switch (if they support debugging macros at all).
-
-=head2 Dumping Perl Data Structures
-
-One way to get around this macro hell is to use the dumping functions
-in F<dump.c>; these work a little like an internal
-L<Devel::Peek|Devel::Peek>, but they also cover OPs and other
-structures that you can't get at from Perl. Let's take an example.
-We'll use the C<$a = $b + $c> we used before, but give it a bit of
-context: C<$b = "6XXXX"; $c = 2.3;>. Where's a good place to stop and
-poke around?
-
-What about C<pp_add>, the function we examined earlier to implement the
-C<+> operator:
-
- (gdb) break Perl_pp_add
- Breakpoint 1 at 0x46249f: file pp_hot.c, line 309.
-
-Notice we use C<Perl_pp_add> and not C<pp_add> - see
-L<perlguts/Internal Functions>. With the breakpoint in place, we can
-run our program:
-
- (gdb) run -e '$b = "6XXXX"; $c = 2.3; $a = $b + $c'
-
-Lots of junk will go past as gdb reads in the relevant source files and
-libraries, and then:
-
- Breakpoint 1, Perl_pp_add () at pp_hot.c:309
- 309 dSP; dATARGET; tryAMAGICbin(add,opASSIGN);
- (gdb) step
- 311 dPOPTOPnnrl_ul;
- (gdb)
-
-We looked at this bit of code before, and we said that
-C<dPOPTOPnnrl_ul> arranges for two C<NV>s to be placed into C<left> and
-C<right> - let's slightly expand it:
-
- #define dPOPTOPnnrl_ul NV right = POPn; \
- SV *leftsv = TOPs; \
- NV left = USE_LEFT(leftsv) ? SvNV(leftsv) : 0.0
-
-C<POPn> takes the SV from the top of the stack and obtains its NV
-either directly (if C<SvNOK> is set) or by calling the C<sv_2nv>
-function. C<TOPs> takes the next SV from the top of the stack - yes,
-C<POPn> uses C<TOPs> - but doesn't remove it. We then use C<SvNV> to
-get the NV from C<leftsv> in the same way as before - yes, C<POPn> uses
-C<SvNV>.
-
-Since we don't have an NV for C<$b>, we'll have to use C<sv_2nv> to
-convert it. If we step again, we'll find ourselves there:
-
- Perl_sv_2nv (sv=0xa0675d0) at sv.c:1669
- 1669 if (!sv)
- (gdb)
-
-We can now use C<Perl_sv_dump> to investigate the SV:
-
- SV = PV(0xa057cc0) at 0xa0675d0
- REFCNT = 1
- FLAGS = (POK,pPOK)
- PV = 0xa06a510 "6XXXX"\0
- CUR = 5
- LEN = 6
- $1 = void
-
-We know we're going to get C<6> from this, so let's finish the
-subroutine:
-
- (gdb) finish
- Run till exit from #0 Perl_sv_2nv (sv=0xa0675d0) at sv.c:1671
- 0x462669 in Perl_pp_add () at pp_hot.c:311
- 311 dPOPTOPnnrl_ul;
-
-We can also dump out this op: the current op is always stored in
-C<PL_op>, and we can dump it with C<Perl_op_dump>. This'll give us
-similar output to L<B::Debug|B::Debug>.
-
- {
- 13 TYPE = add ===> 14
- TARG = 1
- FLAGS = (SCALAR,KIDS)
- {
- TYPE = null ===> (12)
- (was rv2sv)
- FLAGS = (SCALAR,KIDS)
- {
- 11 TYPE = gvsv ===> 12
- FLAGS = (SCALAR)
- GV = main::b
- }
- }
-
-# finish this later #
-
-=head1 SOURCE CODE STATIC ANALYSIS
-
-Various tools exist for analysing C source code B<statically>, as
-opposed to B<dynamically>, that is, without executing the code. It is
-possible to detect resource leaks, undefined behaviour, type
-mismatches, portability problems, code paths that would cause illegal
-memory accesses, and other similar problems by just parsing the C code
-and looking at the resulting graph, what does it tell about the
-execution and data flows. As a matter of fact, this is exactly how C
-compilers know to give warnings about dubious code.
-
-=head2 lint, splint
-
-The good old C code quality inspector, C<lint>, is available in several
-platforms, but please be aware that there are several different
-implementations of it by different vendors, which means that the flags
-are not identical across different platforms.
-
-There is a lint variant called C<splint> (Secure Programming Lint)
-available from http://www.splint.org/ that should compile on any
-Unix-like platform.
-
-There are C<lint> and <splint> targets in Makefile, but you may have to
-diddle with the flags (see above).
-
-=head2 Coverity
-
-Coverity (http://www.coverity.com/) is a product similar to lint and as
-a testbed for their product they periodically check several open source
-projects, and they give out accounts to open source developers to the
-defect databases.
-
-=head2 cpd (cut-and-paste detector)
-
-The cpd tool detects cut-and-paste coding. If one instance of the
-cut-and-pasted code changes, all the other spots should probably be
-changed, too. Therefore such code should probably be turned into a
-subroutine or a macro.
-
-cpd (http://pmd.sourceforge.net/cpd.html) is part of the pmd project
-(http://pmd.sourceforge.net/). pmd was originally written for static
-analysis of Java code, but later the cpd part of it was extended to
-parse also C and C++.
-
-Download the pmd-bin-X.Y.zip () from the SourceForge site, extract the
-pmd-X.Y.jar from it, and then run that on source code thusly:
-
- java -cp pmd-X.Y.jar net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /some/where/src --language c > cpd.txt
-
-You may run into memory limits, in which case you should use the -Xmx
-option:
-
- java -Xmx512M ...
-
-=head2 gcc warnings
-
-Though much can be written about the inconsistency and coverage
-problems of gcc warnings (like C<-Wall> not meaning "all the warnings",
-or some common portability problems not being covered by C<-Wall>, or
-C<-ansi> and C<-pedantic> both being a poorly defined collection of
-warnings, and so forth), gcc is still a useful tool in keeping our
-coding nose clean.
-
-The C<-Wall> is by default on.
-
-The C<-ansi> (and its sidekick, C<-pedantic>) would be nice to be on
-always, but unfortunately they are not safe on all platforms, they can
-for example cause fatal conflicts with the system headers (Solaris
-being a prime example). If Configure C<-Dgccansipedantic> is used, the
-C<cflags> frontend selects C<-ansi -pedantic> for the platforms where
-they are known to be safe.
-
-Starting from Perl 5.9.4 the following extra flags are added:
-
-=over 4
-
-=item *
-
-C<-Wendif-labels>
-
-=item *
-
-C<-Wextra>
-
-=item *
-
-C<-Wdeclaration-after-statement>
-
-=back
-
-The following flags would be nice to have but they would first need
-their own Augean stablemaster:
-
-=over 4
-
-=item *
-
-C<-Wpointer-arith>
-
-=item *
-
-C<-Wshadow>
-
-=item *
-
-C<-Wstrict-prototypes>
-
-=back
-
-The C<-Wtraditional> is another example of the annoying tendency of gcc
-to bundle a lot of warnings under one switch (it would be impossible to
-deploy in practice because it would complain a lot) but it does contain
-some warnings that would be beneficial to have available on their own,
-such as the warning about string constants inside macros containing the
-macro arguments: this behaved differently pre-ANSI than it does in
-ANSI, and some C compilers are still in transition, AIX being an
-example.
-
-=head2 Warnings of other C compilers
-
-Other C compilers (yes, there B<are> other C compilers than gcc) often
-have their "strict ANSI" or "strict ANSI with some portability
-extensions" modes on, like for example the Sun Workshop has its C<-Xa>
-mode on (though implicitly), or the DEC (these days, HP...) has its
-C<-std1> mode on.
-
-=head1 MEMORY DEBUGGERS
-
-B<NOTE 1>: Running under memory debuggers such as Purify, valgrind, or
-Third Degree greatly slows down the execution: seconds become minutes,
-minutes become hours. For example as of Perl 5.8.1, the
-ext/Encode/t/Unicode.t takes extraordinarily long to complete under
-e.g. Purify, Third Degree, and valgrind. Under valgrind it takes more
-than six hours, even on a snappy computer. The said test must be doing
-something that is quite unfriendly for memory debuggers. If you don't
-feel like waiting, that you can simply kill away the perl process.
-
-B<NOTE 2>: To minimize the number of memory leak false alarms (see
-L</PERL_DESTRUCT_LEVEL> for more information), you have to set the
-environment variable PERL_DESTRUCT_LEVEL to 2.
-
-For csh-like shells:
-
- setenv PERL_DESTRUCT_LEVEL 2
-
-For Bourne-type shells:
-
- PERL_DESTRUCT_LEVEL=2
- export PERL_DESTRUCT_LEVEL
-
-In Unixy environments you can also use the C<env> command:
-
- env PERL_DESTRUCT_LEVEL=2 valgrind ./perl -Ilib ...
-
-B<NOTE 3>: There are known memory leaks when there are compile-time
-errors within eval or require, seeing C<S_doeval> in the call stack is
-a good sign of these. Fixing these leaks is non-trivial, unfortunately,
-but they must be fixed eventually.
-
-B<NOTE 4>: L<DynaLoader> will not clean up after itself completely
-unless Perl is built with the Configure option
-C<-Accflags=-DDL_UNLOAD_ALL_AT_EXIT>.
-
-=head2 Rational Software's Purify
-
-Purify is a commercial tool that is helpful in identifying memory
-overruns, wild pointers, memory leaks and other such badness. Perl must
-be compiled in a specific way for optimal testing with Purify. Purify
-is available under Windows NT, Solaris, HP-UX, SGI, and Siemens Unix.
-
-=head3 Purify on Unix
-
-On Unix, Purify creates a new Perl binary. To get the most benefit out
-of Purify, you should create the perl to Purify using:
-
- sh Configure -Accflags=-DPURIFY -Doptimize='-g' \
- -Uusemymalloc -Dusemultiplicity
-
-where these arguments mean:
-
-=over 4
-
-=item * -Accflags=-DPURIFY
-
-Disables Perl's arena memory allocation functions, as well as forcing
-use of memory allocation functions derived from the system malloc.
-
-=item * -Doptimize='-g'
-
-Adds debugging information so that you see the exact source statements
-where the problem occurs. Without this flag, all you will see is the
-source filename of where the error occurred.
-
-=item * -Uusemymalloc
-
-Disable Perl's malloc so that Purify can more closely monitor
-allocations and leaks. Using Perl's malloc will make Purify report most
-leaks in the "potential" leaks category.
-
-=item * -Dusemultiplicity
-
-Enabling the multiplicity option allows perl to clean up thoroughly
-when the interpreter shuts down, which reduces the number of bogus leak
-reports from Purify.
-
-=back
-
-Once you've compiled a perl suitable for Purify'ing, then you can just:
-
- make pureperl
-
-which creates a binary named 'pureperl' that has been Purify'ed. This
-binary is used in place of the standard 'perl' binary when you want to
-debug Perl memory problems.
-
-As an example, to show any memory leaks produced during the standard
-Perl testset you would create and run the Purify'ed perl as:
-
- make pureperl
- cd t
- ../pureperl -I../lib harness
-
-which would run Perl on test.pl and report any memory problems.
-
-Purify outputs messages in "Viewer" windows by default. If you don't
-have a windowing environment or if you simply want the Purify output to
-unobtrusively go to a log file instead of to the interactive window,
-use these following options to output to the log file "perl.log":
-
- setenv PURIFYOPTIONS "-chain-length=25 -windows=no \
- -log-file=perl.log -append-logfile=yes"
-
-If you plan to use the "Viewer" windows, then you only need this
-option:
-
- setenv PURIFYOPTIONS "-chain-length=25"
-
-In Bourne-type shells:
-
- PURIFYOPTIONS="..."
- export PURIFYOPTIONS
-
-or if you have the "env" utility:
-
- env PURIFYOPTIONS="..." ../pureperl ...
-
-=head3 Purify on NT
-
-Purify on Windows NT instruments the Perl binary 'perl.exe' on the fly.
- There are several options in the makefile you should change to get the
-most use out of Purify:
-
-=over 4
-
-=item * DEFINES
-
-You should add -DPURIFY to the DEFINES line so the DEFINES line looks
-something like:
-
- DEFINES = -DWIN32 -D_CONSOLE -DNO_STRICT $(CRYPT_FLAG) -DPURIFY=1
-
-to disable Perl's arena memory allocation functions, as well as to
-force use of memory allocation functions derived from the system
-malloc.
-
-=item * USE_MULTI = define
-
-Enabling the multiplicity option allows perl to clean up thoroughly
-when the interpreter shuts down, which reduces the number of bogus leak
-reports from Purify.
-
-=item * #PERL_MALLOC = define
-
-Disable Perl's malloc so that Purify can more closely monitor
-allocations and leaks. Using Perl's malloc will make Purify report most
-leaks in the "potential" leaks category.
-
-=item * CFG = Debug
-
-Adds debugging information so that you see the exact source statements
-where the problem occurs. Without this flag, all you will see is the
-source filename of where the error occurred.
-
-=back
-
-As an example, to show any memory leaks produced during the standard
-Perl testset you would create and run Purify as:
-
- cd win32
- make
- cd ../t
- purify ../perl -I../lib harness
-
-which would instrument Perl in memory, run Perl on test.pl, then
-finally report any memory problems.
-
-=head2 valgrind
-
-The excellent valgrind tool can be used to find out both memory leaks
-and illegal memory accesses. As of version 3.3.0, Valgrind only
-supports Linux on x86, x86-64 and PowerPC and Darwin (OS X) on x86 and
-x86-64). The special "test.valgrind" target can be used to run the
-tests under valgrind. Found errors and memory leaks are logged in
-files named F<testfile.valgrind>.
-
-Valgrind also provides a cachegrind tool, invoked on perl as:
-
- VG_OPTS=--tool=cachegrind make test.valgrind
-
-As system libraries (most notably glibc) are also triggering errors,
-valgrind allows to suppress such errors using suppression files. The
-default suppression file that comes with valgrind already catches a lot
-of them. Some additional suppressions are defined in F<t/perl.supp>.
-
-To get valgrind and for more information see
-
- http://valgrind.org/
-
-=head1 PROFILING
-
-Depending on your platform there are various ways of profiling Perl.
-
-There are two commonly used techniques of profiling executables:
-I<statistical time-sampling> and I<basic-block counting>.
-
-The first method takes periodically samples of the CPU program counter,
-and since the program counter can be correlated with the code generated
-for functions, we get a statistical view of in which functions the
-program is spending its time. The caveats are that very small/fast
-functions have lower probability of showing up in the profile, and that
-periodically interrupting the program (this is usually done rather
-frequently, in the scale of milliseconds) imposes an additional
-overhead that may skew the results. The first problem can be alleviated
-by running the code for longer (in general this is a good idea for
-profiling), the second problem is usually kept in guard by the
-profiling tools themselves.
-
-The second method divides up the generated code into I<basic blocks>.
-Basic blocks are sections of code that are entered only in the
-beginning and exited only at the end. For example, a conditional jump
-starts a basic block. Basic block profiling usually works by
-I<instrumenting> the code by adding I<enter basic block #nnnn>
-book-keeping code to the generated code. During the execution of the
-code the basic block counters are then updated appropriately. The
-caveat is that the added extra code can skew the results: again, the
-profiling tools usually try to factor their own effects out of the
-results.
-
-=head2 Gprof Profiling
-
-gprof is a profiling tool available in many Unix platforms, it uses
-F<statistical time-sampling>.
-
-You can build a profiled version of perl called "perl.gprof" by
-invoking the make target "perl.gprof" (What is required is that Perl
-must be compiled using the C<-pg> flag, you may need to re-Configure).
-Running the profiled version of Perl will create an output file called
-F<gmon.out> is created which contains the profiling data collected
-during the execution.
-
-The gprof tool can then display the collected data in various ways.
-Usually gprof understands the following options:
-
-=over 4
-
-=item * -a
-
-Suppress statically defined functions from the profile.
-
-=item * -b
-
-Suppress the verbose descriptions in the profile.
-
-=item * -e routine
-
-Exclude the given routine and its descendants from the profile.
-
-=item * -f routine
-
-Display only the given routine and its descendants in the profile.
-
-=item * -s
-
-Generate a summary file called F<gmon.sum> which then may be given to
-subsequent gprof runs to accumulate data over several runs.
-
-=item * -z
-
-Display routines that have zero usage.
-
-=back
-
-For more detailed explanation of the available commands and output
-formats, see your own local documentation of gprof.
-
-quick hint:
-
- $ sh Configure -des -Dusedevel -Doptimize='-pg' && make perl.gprof
- $ ./perl.gprof someprog # creates gmon.out in current directory
- $ gprof ./perl.gprof > out
- $ view out
-
-=head2 GCC gcov Profiling
-
-Starting from GCC 3.0 I<basic block profiling> is officially available
-for the GNU CC.
-
-You can build a profiled version of perl called F<perl.gcov> by
-invoking the make target "perl.gcov" (what is required that Perl must
-be compiled using gcc with the flags C<-fprofile-arcs -ftest-coverage>,
-you may need to re-Configure).
-
-Running the profiled version of Perl will cause profile output to be
-generated. For each source file an accompanying ".da" file will be
-created.
-
-To display the results you use the "gcov" utility (which should be
-installed if you have gcc 3.0 or newer installed). F<gcov> is run on
-source code files, like this
-
- gcov sv.c
-
-which will cause F<sv.c.gcov> to be created. The F<.gcov> files contain
-the source code annotated with relative frequencies of execution
-indicated by "#" markers.
-
-Useful options of F<gcov> include C<-b> which will summarise the basic
-block, branch, and function call coverage, and C<-c> which instead of
-relative frequencies will use the actual counts. For more information
-on the use of F<gcov> and basic block profiling with gcc, see the
-latest GNU CC manual, as of GCC 3.0 see
-
- http://gcc.gnu.org/onlinedocs/gcc-3.0/gcc.html
-
-and its section titled "8. gcov: a Test Coverage Program"
-
- http://gcc.gnu.org/onlinedocs/gcc-3.0/gcc_8.html#SEC132
-
-quick hint:
-
- $ sh Configure -des -Dusedevel -Doptimize='-g' \
- -Accflags='-fprofile-arcs -ftest-coverage' \
- -Aldflags='-fprofile-arcs -ftest-coverage' && make perl.gcov
- $ rm -f regexec.c.gcov regexec.gcda
- $ ./perl.gcov
- $ gcov regexec.c
- $ view regexec.c.gcov
-
-=head1 MISCELLANEOUS TRICKS
-
-=head2 PERL_DESTRUCT_LEVEL
-
-If you want to run any of the tests yourself manually using e.g.
-valgrind, or the pureperl or perl.third executables, please note that
-by default perl B<does not> explicitly cleanup all the memory it has
-allocated (such as global memory arenas) but instead lets the exit() of
-the whole program "take care" of such allocations, also known as
-"global destruction of objects".
-
-There is a way to tell perl to do complete cleanup: set the environment
-variable PERL_DESTRUCT_LEVEL to a non-zero value. The t/TEST wrapper
-does set this to 2, and this is what you need to do too, if you don't
-want to see the "global leaks": For example, for "third-degreed" Perl:
-
- env PERL_DESTRUCT_LEVEL=2 ./perl.third -Ilib t/foo/bar.t
-
-(Note: the mod_perl apache module uses also this environment variable
-for its own purposes and extended its semantics. Refer to the mod_perl
-documentation for more information. Also, spawned threads do the
-equivalent of setting this variable to the value 1.)
-
-If, at the end of a run you get the message I<N scalars leaked>, you
-can recompile with C<-DDEBUG_LEAKING_SCALARS>, which will cause the
-addresses of all those leaked SVs to be dumped along with details as to
-where each SV was originally allocated. This information is also
-displayed by Devel::Peek. Note that the extra details recorded with
-each SV increases memory usage, so it shouldn't be used in production
-environments. It also converts C<new_SV()> from a macro into a real
-function, so you can use your favourite debugger to discover where
-those pesky SVs were allocated.
-
-If you see that you're leaking memory at runtime, but neither valgrind
-nor C<-DDEBUG_LEAKING_SCALARS> will find anything, you're probably
-leaking SVs that are still reachable and will be properly cleaned up
-during destruction of the interpreter. In such cases, using the C<-Dm>
-switch can point you to the source of the leak. If the executable was
-built with C<-DDEBUG_LEAKING_SCALARS>, C<-Dm> will output SV
-allocations in addition to memory allocations. Each SV allocation has a
-distinct serial number that will be written on creation and destruction
-of the SV. So if you're executing the leaking code in a loop, you need
-to look for SVs that are created, but never destroyed between each
-cycle. If such an SV is found, set a conditional breakpoint within
-C<new_SV()> and make it break only when C<PL_sv_serial> is equal to the
-serial number of the leaking SV. Then you will catch the interpreter in
-exactly the state where the leaking SV is allocated, which is
-sufficient in many cases to find the source of the leak.
-
-As C<-Dm> is using the PerlIO layer for output, it will by itself
-allocate quite a bunch of SVs, which are hidden to avoid recursion. You
-can bypass the PerlIO layer if you use the SV logging provided by
-C<-DPERL_MEM_LOG> instead.
-
-=head2 PERL_MEM_LOG
-
-If compiled with C<-DPERL_MEM_LOG>, both memory and SV allocations go
-through logging functions, which is handy for breakpoint setting.
-
-Unless C<-DPERL_MEM_LOG_NOIMPL> is also compiled, the logging functions
-read $ENV{PERL_MEM_LOG} to determine whether to log the event, and if
-so how:
-
- $ENV{PERL_MEM_LOG} =~ /m/ Log all memory ops
- $ENV{PERL_MEM_LOG} =~ /s/ Log all SV ops
- $ENV{PERL_MEM_LOG} =~ /t/ include timestamp in Log
- $ENV{PERL_MEM_LOG} =~ /^(\d+)/ write to FD given (default is 2)
-
-Memory logging is somewhat similar to C<-Dm> but is independent of
-C<-DDEBUGGING>, and at a higher level; all uses of Newx(), Renew(), and
-Safefree() are logged with the caller's source code file and line
-number (and C function name, if supported by the C compiler). In
-contrast, C<-Dm> is directly at the point of C<malloc()>. SV logging is
-similar.
-
-Since the logging doesn't use PerlIO, all SV allocations are logged and
-no extra SV allocations are introduced by enabling the logging. If
-compiled with C<-DDEBUG_LEAKING_SCALARS>, the serial number for each SV
-allocation is also logged.
-
-=head2 DDD over gdb
-
-Those debugging perl with the DDD frontend over gdb may find the
-following useful:
-
-You can extend the data conversion shortcuts menu, so for example you
-can display an SV's IV value with one click, without doing any typing.
-To do that simply edit ~/.ddd/init file and add after:
-
- ! Display shortcuts.
- Ddd*gdbDisplayShortcuts: \
- /t () // Convert to Bin\n\
- /d () // Convert to Dec\n\
- /x () // Convert to Hex\n\
- /o () // Convert to Oct(\n\
-
-the following two lines:
-
- ((XPV*) (())->sv_any )->xpv_pv // 2pvx\n\
- ((XPVIV*) (())->sv_any )->xiv_iv // 2ivx
-
-so now you can do ivx and pvx lookups or you can plug there the sv_peek
-"conversion":
-
- Perl_sv_peek(my_perl, (SV*)()) // sv_peek
-
-(The my_perl is for threaded builds.) Just remember that every line,
-but the last one, should end with \n\
-
-Alternatively edit the init file interactively via: 3rd mouse button ->
-New Display -> Edit Menu
-
-Note: you can define up to 20 conversion shortcuts in the gdb section.
-
-=head2 Poison
-
-If you see in a debugger a memory area mysteriously full of 0xABABABAB
-or 0xEFEFEFEF, you may be seeing the effect of the Poison() macros, see
-L<perlclib>.
-
-=head2 Read-only optrees
-
-Under ithreads the optree is read only. If you want to enforce this, to
-check for write accesses from buggy code, compile with
-C<-DPL_OP_SLAB_ALLOC> to enable the OP slab allocator and
-C<-DPERL_DEBUG_READONLY_OPS> to enable code that allocates op memory
-via C<mmap>, and sets it read-only at run time. Any write access to an
-op results in a C<SIGBUS> and abort.
-
-This code is intended for development only, and may not be portable
-even to all Unix variants. Also, it is an 80% solution, in that it
-isn't able to make all ops read only. Specifically it
-
-=over
-
-=item * 1
-
-Only sets read-only on all slabs of ops at C<CHECK> time, hence ops
-allocated later via C<require> or C<eval> will be re-write
-
-=item * 2
-
-Turns an entire slab of ops read-write if the refcount of any op in the
-slab needs to be decreased.
-
-=item * 3
-
-Turns an entire slab of ops read-write if any op from the slab is
-freed.
-
-=back
-
-It's not possible to turn the slabs to read-only after an action
-requiring read-write access, as either can happen during op tree
-building time, so there may still be legitimate write access.
-
-However, as an 80% solution it is still effective, as currently it
-catches a write access during the generation of F<Config.pm>, which
-means that we can't yet build F<perl> with this enabled.
-
-=head2 The .i Targets
-
-You can expand the macros in a F<foo.c> file by saying
-
- make foo.i
-
-which will expand the macros using cpp. Don't be scared by the results.
-
-=head1 AUTHOR
-
-This document was originally written by Nathan Torkington, and is
-maintained by the perl5-porters mailing list.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlhacktut.pod b/Master/tlpkg/tlperl/lib/pods/perlhacktut.pod
deleted file mode 100644
index 33a9ef23e8d..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlhacktut.pod
+++ /dev/null
@@ -1,188 +0,0 @@
-=encoding utf8
-
-=for comment
-Consistent formatting of this file is achieved with:
- perl ./Porting/podtidy pod/perlhacktut.pod
-
-=head1 NAME
-
-perlhacktut - Walk through the creation of a simple C code patch
-
-=head1 DESCRIPTION
-
-This document takes you through a simple patch example.
-
-If you haven't read L<perlhack> yet, go do that first! You might also
-want to read through L<perlsource> too.
-
-Once you're done here, check out L<perlhacktips> next.
-
-=head1 EXAMPLE OF A SIMPLE PATCH
-
-Let's take a simple patch from start to finish.
-
-Here's something Larry suggested: if a C<U> is the first active format
-during a C<pack>, (for example, C<pack "U3C8", @stuff>) then the
-resulting string should be treated as UTF-8 encoded.
-
-If you are working with a git clone of the Perl repository, you will
-want to create a branch for your changes. This will make creating a
-proper patch much simpler. See the L<perlgit> for details on how to do
-this.
-
-=head2 Writing the patch
-
-How do we prepare to fix this up? First we locate the code in question
-- the C<pack> happens at runtime, so it's going to be in one of the
-F<pp> files. Sure enough, C<pp_pack> is in F<pp.c>. Since we're going
-to be altering this file, let's copy it to F<pp.c~>.
-
-[Well, it was in F<pp.c> when this tutorial was written. It has now
-been split off with C<pp_unpack> to its own file, F<pp_pack.c>]
-
-Now let's look over C<pp_pack>: we take a pattern into C<pat>, and then
-loop over the pattern, taking each format character in turn into
-C<datum_type>. Then for each possible format character, we swallow up
-the other arguments in the pattern (a field width, an asterisk, and so
-on) and convert the next chunk input into the specified format, adding
-it onto the output SV C<cat>.
-
-How do we know if the C<U> is the first format in the C<pat>? Well, if
-we have a pointer to the start of C<pat> then, if we see a C<U> we can
-test whether we're still at the start of the string. So, here's where
-C<pat> is set up:
-
- STRLEN fromlen;
- register char *pat = SvPVx(*++MARK, fromlen);
- register char *patend = pat + fromlen;
- register I32 len;
- I32 datumtype;
- SV *fromstr;
-
-We'll have another string pointer in there:
-
- STRLEN fromlen;
- register char *pat = SvPVx(*++MARK, fromlen);
- register char *patend = pat + fromlen;
- + char *patcopy;
- register I32 len;
- I32 datumtype;
- SV *fromstr;
-
-And just before we start the loop, we'll set C<patcopy> to be the start
-of C<pat>:
-
- items = SP - MARK;
- MARK++;
- sv_setpvn(cat, "", 0);
- + patcopy = pat;
- while (pat < patend) {
-
-Now if we see a C<U> which was at the start of the string, we turn on
-the C<UTF8> flag for the output SV, C<cat>:
-
- + if (datumtype == 'U' && pat==patcopy+1)
- + SvUTF8_on(cat);
- if (datumtype == '#') {
- while (pat < patend && *pat != '\n')
- pat++;
-
-Remember that it has to be C<patcopy+1> because the first character of
-the string is the C<U> which has been swallowed into C<datumtype!>
-
-Oops, we forgot one thing: what if there are spaces at the start of the
-pattern? C<pack(" U*", @stuff)> will have C<U> as the first active
-character, even though it's not the first thing in the pattern. In this
-case, we have to advance C<patcopy> along with C<pat> when we see
-spaces:
-
- if (isSPACE(datumtype))
- continue;
-
-needs to become
-
- if (isSPACE(datumtype)) {
- patcopy++;
- continue;
- }
-
-OK. That's the C part done. Now we must do two additional things before
-this patch is ready to go: we've changed the behaviour of Perl, and so
-we must document that change. We must also provide some more regression
-tests to make sure our patch works and doesn't create a bug somewhere
-else along the line.
-
-=head2 Testing the patch
-
-The regression tests for each operator live in F<t/op/>, and so we make
-a copy of F<t/op/pack.t> to F<t/op/pack.t~>. Now we can add our tests
-to the end. First, we'll test that the C<U> does indeed create Unicode
-strings.
-
-t/op/pack.t has a sensible ok() function, but if it didn't we could use
-the one from t/test.pl.
-
- require './test.pl';
- plan( tests => 159 );
-
-so instead of this:
-
- print 'not ' unless "1.20.300.4000" eq sprintf "%vd",
- pack("U*",1,20,300,4000);
- print "ok $test\n"; $test++;
-
-we can write the more sensible (see L<Test::More> for a full
-explanation of is() and other testing functions).
-
- is( "1.20.300.4000", sprintf "%vd", pack("U*",1,20,300,4000),
- "U* produces Unicode" );
-
-Now we'll test that we got that space-at-the-beginning business right:
-
- is( "1.20.300.4000", sprintf "%vd", pack(" U*",1,20,300,4000),
- " with spaces at the beginning" );
-
-And finally we'll test that we don't make Unicode strings if C<U> is
-B<not> the first active format:
-
- isnt( v1.20.300.4000, sprintf "%vd", pack("C0U*",1,20,300,4000),
- "U* not first isn't Unicode" );
-
-Mustn't forget to change the number of tests which appears at the top,
-or else the automated tester will get confused. This will either look
-like this:
-
- print "1..156\n";
-
-or this:
-
- plan( tests => 156 );
-
-We now compile up Perl, and run it through the test suite. Our new
-tests pass, hooray!
-
-=head2 Documenting the patch
-
-Finally, the documentation. The job is never done until the paperwork
-is over, so let's describe the change we've just made. The relevant
-place is F<pod/perlfunc.pod>; again, we make a copy, and then we'll
-insert this text in the description of C<pack>:
-
- =item *
-
- If the pattern begins with a C<U>, the resulting string will be treated
- as UTF-8-encoded Unicode. You can force UTF-8 encoding on in a string
- with an initial C<U0>, and the bytes that follow will be interpreted as
- Unicode characters. If you don't want this to happen, you can begin
- your pattern with C<C0> (or anything else) to force Perl not to UTF-8
- encode your string, and then follow this with a C<U*> somewhere in your
- pattern.
-
-=head2 Submit
-
-See L<perlhack> for details on how to submit this patch.
-
-=head1 AUTHOR
-
-This document was originally written by Nathan Torkington, and is
-maintained by the perl5-porters mailing list.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlhaiku.pod b/Master/tlpkg/tlperl/lib/pods/perlhaiku.pod
deleted file mode 100644
index fa22d96d2e8..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlhaiku.pod
+++ /dev/null
@@ -1,64 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you see.
-It is written in the POD format (see pod/perlpod.pod) which is specially
-designed to be readable as is.
-
-=head1 NAME
-
-perlhaiku - Perl version 5.10+ on Haiku
-
-=head1 DESCRIPTION
-
-This file contains instructions how to build Perl for Haiku and lists
-known problems.
-
-=head1 BUILD AND INSTALL
-
-The build procedure is completely standard:
-
- ./Configure -de
- make
- make install
-
-Make perl executable and create a symlink for libperl:
-
- chmod a+x /boot/common/bin/perl
- cd /boot/common/lib; ln -s perl5/5.16.2/BePC-haiku/CORE/libperl.so .
-
-Replace C<5.16.2> with your respective version of Perl.
-
-=head1 KNOWN PROBLEMS
-
-The following problems are encountered with Haiku revision 28311:
-
-=over 4
-
-=item *
-
-Perl cannot be compiled with threading support ATM.
-
-=item *
-
-The F<ext/Socket/t/socketpair.t> test fails. More precisely: the subtests
-using datagram sockets fail. Unix datagram sockets aren't implemented in
-Haiku yet.
-
-=item *
-
-A subtest of the F<ext/Sys/Syslog/t/syslog.t> test fails. This is due to Haiku
-not implementing C</dev/log> support yet.
-
-=item *
-
-The tests F<lib/Net/Ping/t/450_service.t> and F<lib/Net/Ping/t/510_ping_udp.t>
-fail. This is due to bugs in Haiku's network stack implementation.
-
-=back
-
-=head1 CONTACT
-
-For Haiku specific problems contact the HaikuPorts developers:
-L<http://ports.haiku-files.org/>
-
-The initial Haiku port was done by Ingo Weinhold <ingo_weinhold@gmx.de>.
-
-Last update: 2008-10-29
diff --git a/Master/tlpkg/tlperl/lib/pods/perlhist.pod b/Master/tlpkg/tlperl/lib/pods/perlhist.pod
deleted file mode 100644
index fbd4d2d64c4..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlhist.pod
+++ /dev/null
@@ -1,981 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perlhist - the Perl history records
-
-=head1 DESCRIPTION
-
-This document aims to record the Perl source code releases.
-
-=head1 INTRODUCTION
-
-Perl history in brief, by Larry Wall:
-
- Perl 0 introduced Perl to my officemates.
- Perl 1 introduced Perl to the world, and changed /\(...\|...\)/ to
- /(...|...)/. \(Dan Faigin still hasn't forgiven me. :-\)
- Perl 2 introduced Henry Spencer's regular expression package.
- Perl 3 introduced the ability to handle binary data (embedded nulls).
- Perl 4 introduced the first Camel book. Really. We mostly just
- switched version numbers so the book could refer to 4.000.
- Perl 5 introduced everything else, including the ability to
- introduce everything else.
-
-=head1 THE KEEPERS OF THE PUMPKIN
-
-Larry Wall, Andy Dougherty, Tom Christiansen, Charles Bailey, Nick
-Ing-Simmons, Chip Salzenberg, Tim Bunce, Malcolm Beattie, Gurusamy
-Sarathy, Graham Barr, Jarkko Hietaniemi, Hugo van der Sanden,
-Michael Schwern, Rafael Garcia-Suarez, Nicholas Clark, Richard Clamp,
-Leon Brocard, Dave Mitchell, Jesse Vincent, Ricardo Signes, Steve Hay,
-Matt S Trout, David Golden, Florian Ragwitz, Tatsuhiko Miyagawa,
-Chris C<BinGOs> Williams, Zefram, Ævar Arnfjörð Bjarmason, Stevan
-Little, Dave Rolsky, Max Maischein, Abigail, Jesse Luehrs and Tony
-Cook.
-
-=head2 PUMPKIN?
-
-[from Porting/pumpkin.pod in the Perl source code distribution]
-
-=for disclaimer orking cows is hazardous, and not legal in all jurisdictions
-
-Chip Salzenberg gets credit for that, with a nod to his cow orker,
-David Croy. We had passed around various names (baton, token, hot
-potato) but none caught on. Then, Chip asked:
-
-[begin quote]
-
- Who has the patch pumpkin?
-
-To explain: David Croy once told me that at a previous job,
-there was one tape drive and multiple systems that used it for backups.
-But instead of some high-tech exclusion software, they used a low-tech
-method to prevent multiple simultaneous backups: a stuffed pumpkin.
-No one was allowed to make backups unless they had the "backup pumpkin".
-
-[end quote]
-
-The name has stuck. The holder of the pumpkin is sometimes called
-the pumpking (keeping the source afloat?) or the pumpkineer (pulling
-the strings?).
-
-=head1 THE RECORDS
-
- Pump- Release Date Notes
- king (by no means
- comprehensive,
- see Changes*
- for details)
- ======================================================================
-
- Larry 0 Classified. Don't ask.
-
- Larry 1.000 1987-Dec-18
-
- 1.001..10 1988-Jan-30
- 1.011..14 1988-Feb-02
- Schwern 1.0.15 2002-Dec-18 Modernization
- Richard 1.0_16 2003-Dec-18
-
- Larry 2.000 1988-Jun-05
-
- 2.001 1988-Jun-28
-
- Larry 3.000 1989-Oct-18
-
- 3.001 1989-Oct-26
- 3.002..4 1989-Nov-11
- 3.005 1989-Nov-18
- 3.006..8 1989-Dec-22
- 3.009..13 1990-Mar-02
- 3.014 1990-Mar-13
- 3.015 1990-Mar-14
- 3.016..18 1990-Mar-28
- 3.019..27 1990-Aug-10 User subs.
- 3.028 1990-Aug-14
- 3.029..36 1990-Oct-17
- 3.037 1990-Oct-20
- 3.040 1990-Nov-10
- 3.041 1990-Nov-13
- 3.042..43 1991-Jan-??
- 3.044 1991-Jan-12
-
- Larry 4.000 1991-Mar-21
-
- 4.001..3 1991-Apr-12
- 4.004..9 1991-Jun-07
- 4.010 1991-Jun-10
- 4.011..18 1991-Nov-05
- 4.019 1991-Nov-11 Stable.
- 4.020..33 1992-Jun-08
- 4.034 1992-Jun-11
- 4.035 1992-Jun-23
- Larry 4.036 1993-Feb-05 Very stable.
-
- 5.000alpha1 1993-Jul-31
- 5.000alpha2 1993-Aug-16
- 5.000alpha3 1993-Oct-10
- 5.000alpha4 1993-???-??
- 5.000alpha5 1993-???-??
- 5.000alpha6 1994-Mar-18
- 5.000alpha7 1994-Mar-25
- Andy 5.000alpha8 1994-Apr-04
- Larry 5.000alpha9 1994-May-05 ext appears.
- 5.000alpha10 1994-Jun-11
- 5.000alpha11 1994-Jul-01
- Andy 5.000a11a 1994-Jul-07 To fit 14.
- 5.000a11b 1994-Jul-14
- 5.000a11c 1994-Jul-19
- 5.000a11d 1994-Jul-22
- Larry 5.000alpha12 1994-Aug-04
- Andy 5.000a12a 1994-Aug-08
- 5.000a12b 1994-Aug-15
- 5.000a12c 1994-Aug-22
- 5.000a12d 1994-Aug-22
- 5.000a12e 1994-Aug-22
- 5.000a12f 1994-Aug-24
- 5.000a12g 1994-Aug-24
- 5.000a12h 1994-Aug-24
- Larry 5.000beta1 1994-Aug-30
- Andy 5.000b1a 1994-Sep-06
- Larry 5.000beta2 1994-Sep-14 Core slushified.
- Andy 5.000b2a 1994-Sep-14
- 5.000b2b 1994-Sep-17
- 5.000b2c 1994-Sep-17
- Larry 5.000beta3 1994-Sep-??
- Andy 5.000b3a 1994-Sep-18
- 5.000b3b 1994-Sep-22
- 5.000b3c 1994-Sep-23
- 5.000b3d 1994-Sep-27
- 5.000b3e 1994-Sep-28
- 5.000b3f 1994-Sep-30
- 5.000b3g 1994-Oct-04
- Andy 5.000b3h 1994-Oct-07
- Larry? 5.000gamma 1994-Oct-13?
-
- Larry 5.000 1994-Oct-17
-
- Andy 5.000a 1994-Dec-19
- 5.000b 1995-Jan-18
- 5.000c 1995-Jan-18
- 5.000d 1995-Jan-18
- 5.000e 1995-Jan-18
- 5.000f 1995-Jan-18
- 5.000g 1995-Jan-18
- 5.000h 1995-Jan-18
- 5.000i 1995-Jan-26
- 5.000j 1995-Feb-07
- 5.000k 1995-Feb-11
- 5.000l 1995-Feb-21
- 5.000m 1995-Feb-28
- 5.000n 1995-Mar-07
- 5.000o 1995-Mar-13?
-
- Larry 5.001 1995-Mar-13
-
- Andy 5.001a 1995-Mar-15
- 5.001b 1995-Mar-31
- 5.001c 1995-Apr-07
- 5.001d 1995-Apr-14
- 5.001e 1995-Apr-18 Stable.
- 5.001f 1995-May-31
- 5.001g 1995-May-25
- 5.001h 1995-May-25
- 5.001i 1995-May-30
- 5.001j 1995-Jun-05
- 5.001k 1995-Jun-06
- 5.001l 1995-Jun-06 Stable.
- 5.001m 1995-Jul-02 Very stable.
- 5.001n 1995-Oct-31 Very unstable.
- 5.002beta1 1995-Nov-21
- 5.002b1a 1995-Dec-04
- 5.002b1b 1995-Dec-04
- 5.002b1c 1995-Dec-04
- 5.002b1d 1995-Dec-04
- 5.002b1e 1995-Dec-08
- 5.002b1f 1995-Dec-08
- Tom 5.002b1g 1995-Dec-21 Doc release.
- Andy 5.002b1h 1996-Jan-05
- 5.002b2 1996-Jan-14
- Larry 5.002b3 1996-Feb-02
- Andy 5.002gamma 1996-Feb-11
- Larry 5.002delta 1996-Feb-27
-
- Larry 5.002 1996-Feb-29 Prototypes.
-
- Charles 5.002_01 1996-Mar-25
-
- 5.003 1996-Jun-25 Security release.
-
- 5.003_01 1996-Jul-31
- Nick 5.003_02 1996-Aug-10
- Andy 5.003_03 1996-Aug-28
- 5.003_04 1996-Sep-02
- 5.003_05 1996-Sep-12
- 5.003_06 1996-Oct-07
- 5.003_07 1996-Oct-10
- Chip 5.003_08 1996-Nov-19
- 5.003_09 1996-Nov-26
- 5.003_10 1996-Nov-29
- 5.003_11 1996-Dec-06
- 5.003_12 1996-Dec-19
- 5.003_13 1996-Dec-20
- 5.003_14 1996-Dec-23
- 5.003_15 1996-Dec-23
- 5.003_16 1996-Dec-24
- 5.003_17 1996-Dec-27
- 5.003_18 1996-Dec-31
- 5.003_19 1997-Jan-04
- 5.003_20 1997-Jan-07
- 5.003_21 1997-Jan-15
- 5.003_22 1997-Jan-16
- 5.003_23 1997-Jan-25
- 5.003_24 1997-Jan-29
- 5.003_25 1997-Feb-04
- 5.003_26 1997-Feb-10
- 5.003_27 1997-Feb-18
- 5.003_28 1997-Feb-21
- 5.003_90 1997-Feb-25 Ramping up to the 5.004 release.
- 5.003_91 1997-Mar-01
- 5.003_92 1997-Mar-06
- 5.003_93 1997-Mar-10
- 5.003_94 1997-Mar-22
- 5.003_95 1997-Mar-25
- 5.003_96 1997-Apr-01
- 5.003_97 1997-Apr-03 Fairly widely used.
- 5.003_97a 1997-Apr-05
- 5.003_97b 1997-Apr-08
- 5.003_97c 1997-Apr-10
- 5.003_97d 1997-Apr-13
- 5.003_97e 1997-Apr-15
- 5.003_97f 1997-Apr-17
- 5.003_97g 1997-Apr-18
- 5.003_97h 1997-Apr-24
- 5.003_97i 1997-Apr-25
- 5.003_97j 1997-Apr-28
- 5.003_98 1997-Apr-30
- 5.003_99 1997-May-01
- 5.003_99a 1997-May-09
- p54rc1 1997-May-12 Release Candidates.
- p54rc2 1997-May-14
-
- Chip 5.004 1997-May-15 A major maintenance release.
-
- Tim 5.004_01-t1 1997-???-?? The 5.004 maintenance track.
- 5.004_01-t2 1997-Jun-11 aka perl5.004m1t2
- 5.004_01 1997-Jun-13
- 5.004_01_01 1997-Jul-29 aka perl5.004m2t1
- 5.004_01_02 1997-Aug-01 aka perl5.004m2t2
- 5.004_01_03 1997-Aug-05 aka perl5.004m2t3
- 5.004_02 1997-Aug-07
- 5.004_02_01 1997-Aug-12 aka perl5.004m3t1
- 5.004_03-t2 1997-Aug-13 aka perl5.004m3t2
- 5.004_03 1997-Sep-05
- 5.004_04-t1 1997-Sep-19 aka perl5.004m4t1
- 5.004_04-t2 1997-Sep-23 aka perl5.004m4t2
- 5.004_04-t3 1997-Oct-10 aka perl5.004m4t3
- 5.004_04-t4 1997-Oct-14 aka perl5.004m4t4
- 5.004_04 1997-Oct-15
- 5.004_04-m1 1998-Mar-04 (5.004m5t1) Maint. trials for 5.004_05.
- 5.004_04-m2 1998-May-01
- 5.004_04-m3 1998-May-15
- 5.004_04-m4 1998-May-19
- 5.004_05-MT5 1998-Jul-21
- 5.004_05-MT6 1998-Oct-09
- 5.004_05-MT7 1998-Nov-22
- 5.004_05-MT8 1998-Dec-03
- Chip 5.004_05-MT9 1999-Apr-26
- 5.004_05 1999-Apr-29
-
- Malcolm 5.004_50 1997-Sep-09 The 5.005 development track.
- 5.004_51 1997-Oct-02
- 5.004_52 1997-Oct-15
- 5.004_53 1997-Oct-16
- 5.004_54 1997-Nov-14
- 5.004_55 1997-Nov-25
- 5.004_56 1997-Dec-18
- 5.004_57 1998-Feb-03
- 5.004_58 1998-Feb-06
- 5.004_59 1998-Feb-13
- 5.004_60 1998-Feb-20
- 5.004_61 1998-Feb-27
- 5.004_62 1998-Mar-06
- 5.004_63 1998-Mar-17
- 5.004_64 1998-Apr-03
- 5.004_65 1998-May-15
- 5.004_66 1998-May-29
- Sarathy 5.004_67 1998-Jun-15
- 5.004_68 1998-Jun-23
- 5.004_69 1998-Jun-29
- 5.004_70 1998-Jul-06
- 5.004_71 1998-Jul-09
- 5.004_72 1998-Jul-12
- 5.004_73 1998-Jul-13
- 5.004_74 1998-Jul-14 5.005 beta candidate.
- 5.004_75 1998-Jul-15 5.005 beta1.
- 5.004_76 1998-Jul-21 5.005 beta2.
-
- Sarathy 5.005 1998-Jul-22 Oneperl.
-
- Sarathy 5.005_01 1998-Jul-27 The 5.005 maintenance track.
- 5.005_02-T1 1998-Aug-02
- 5.005_02-T2 1998-Aug-05
- 5.005_02 1998-Aug-08
- Graham 5.005_03-MT1 1998-Nov-30
- 5.005_03-MT2 1999-Jan-04
- 5.005_03-MT3 1999-Jan-17
- 5.005_03-MT4 1999-Jan-26
- 5.005_03-MT5 1999-Jan-28
- 5.005_03-MT6 1999-Mar-05
- 5.005_03 1999-Mar-28
- Leon 5.005_04-RC1 2004-Feb-05
- 5.005_04-RC2 2004-Feb-18
- 5.005_04 2004-Feb-23
- 5.005_05-RC1 2009-Feb-16
-
- Sarathy 5.005_50 1998-Jul-26 The 5.6 development track.
- 5.005_51 1998-Aug-10
- 5.005_52 1998-Sep-25
- 5.005_53 1998-Oct-31
- 5.005_54 1998-Nov-30
- 5.005_55 1999-Feb-16
- 5.005_56 1999-Mar-01
- 5.005_57 1999-May-25
- 5.005_58 1999-Jul-27
- 5.005_59 1999-Aug-02
- 5.005_60 1999-Aug-02
- 5.005_61 1999-Aug-20
- 5.005_62 1999-Oct-15
- 5.005_63 1999-Dec-09
- 5.5.640 2000-Feb-02
- 5.5.650 2000-Feb-08 beta1
- 5.5.660 2000-Feb-22 beta2
- 5.5.670 2000-Feb-29 beta3
- 5.6.0-RC1 2000-Mar-09 Release candidate 1.
- 5.6.0-RC2 2000-Mar-14 Release candidate 2.
- 5.6.0-RC3 2000-Mar-21 Release candidate 3.
-
- Sarathy 5.6.0 2000-Mar-22
-
- Sarathy 5.6.1-TRIAL1 2000-Dec-18 The 5.6 maintenance track.
- 5.6.1-TRIAL2 2001-Jan-31
- 5.6.1-TRIAL3 2001-Mar-19
- 5.6.1-foolish 2001-Apr-01 The "fools-gold" release.
- 5.6.1 2001-Apr-08
- Rafael 5.6.2-RC1 2003-Nov-08
- 5.6.2 2003-Nov-15 Fix new build issues
-
- Jarkko 5.7.0 2000-Sep-02 The 5.7 track: Development.
- 5.7.1 2001-Apr-09
- 5.7.2 2001-Jul-13 Virtual release candidate 0.
- 5.7.3 2002-Mar-05
- 5.8.0-RC1 2002-Jun-01
- 5.8.0-RC2 2002-Jun-21
- 5.8.0-RC3 2002-Jul-13
-
- Jarkko 5.8.0 2002-Jul-18
-
- Jarkko 5.8.1-RC1 2003-Jul-10 The 5.8 maintenance track
- 5.8.1-RC2 2003-Jul-11
- 5.8.1-RC3 2003-Jul-30
- 5.8.1-RC4 2003-Aug-01
- 5.8.1-RC5 2003-Sep-22
- 5.8.1 2003-Sep-25
- Nicholas 5.8.2-RC1 2003-Oct-27
- 5.8.2-RC2 2003-Nov-03
- 5.8.2 2003-Nov-05
- 5.8.3-RC1 2004-Jan-07
- 5.8.3 2004-Jan-14
- 5.8.4-RC1 2004-Apr-05
- 5.8.4-RC2 2004-Apr-15
- 5.8.4 2004-Apr-21
- 5.8.5-RC1 2004-Jul-06
- 5.8.5-RC2 2004-Jul-08
- 5.8.5 2004-Jul-19
- 5.8.6-RC1 2004-Nov-11
- 5.8.6 2004-Nov-27
- 5.8.7-RC1 2005-May-18
- 5.8.7 2005-May-30
- 5.8.8-RC1 2006-Jan-20
- 5.8.8 2006-Jan-31
- 5.8.9-RC1 2008-Nov-10
- 5.8.9-RC2 2008-Dec-06
- 5.8.9 2008-Dec-14
-
- Hugo 5.9.0 2003-Oct-27 The 5.9 development track
- Rafael 5.9.1 2004-Mar-16
- 5.9.2 2005-Apr-01
- 5.9.3 2006-Jan-28
- 5.9.4 2006-Aug-15
- 5.9.5 2007-Jul-07
- 5.10.0-RC1 2007-Nov-17
- 5.10.0-RC2 2007-Nov-25
-
- Rafael 5.10.0 2007-Dec-18
-
- David M 5.10.1-RC1 2009-Aug-06 The 5.10 maintenance track
- 5.10.1-RC2 2009-Aug-18
- 5.10.1 2009-Aug-22
-
- Jesse 5.11.0 2009-Oct-02 The 5.11 development track
- 5.11.1 2009-Oct-20
- Leon 5.11.2 2009-Nov-20
- Jesse 5.11.3 2009-Dec-20
- Ricardo 5.11.4 2010-Jan-20
- Steve 5.11.5 2010-Feb-20
- Jesse 5.12.0-RC0 2010-Mar-21
- 5.12.0-RC1 2010-Mar-29
- 5.12.0-RC2 2010-Apr-01
- 5.12.0-RC3 2010-Apr-02
- 5.12.0-RC4 2010-Apr-06
- 5.12.0-RC5 2010-Apr-09
-
- Jesse 5.12.0 2010-Apr-12
-
- Jesse 5.12.1-RC2 2010-May-13 The 5.12 maintenance track
- 5.12.1-RC1 2010-May-09
- 5.12.1 2010-May-16
- 5.12.2-RC2 2010-Aug-31
- 5.12.2 2010-Sep-06
- Ricardo 5.12.3-RC1 2011-Jan-09
- Ricardo 5.12.3-RC2 2011-Jan-14
- Ricardo 5.12.3-RC3 2011-Jan-17
- Ricardo 5.12.3 2011-Jan-21
- Leon 5.12.4-RC1 2011-Jun-08
- Leon 5.12.4 2011-Jun-20
-
- Leon 5.13.0 2010-Apr-20 The 5.13 development track
- Ricardo 5.13.1 2010-May-20
- Matt 5.13.2 2010-Jun-22
- David G 5.13.3 2010-Jul-20
- Florian 5.13.4 2010-Aug-20
- Steve 5.13.5 2010-Sep-19
- Miyagawa 5.13.6 2010-Oct-20
- BinGOs 5.13.7 2010-Nov-20
- Zefram 5.13.8 2010-Dec-20
- Jesse 5.13.9 2011-Jan-20
- Ævar 5.13.10 2011-Feb-20
- Florian 5.13.11 2011-Mar-20
- Jesse 5.14.0RC1 2011-Apr-20
- Jesse 5.14.0RC2 2011-May-04
- Jesse 5.14.0RC3 2011-May-11
-
- Jesse 5.14.0 2011-May-14 The 5.14 maintenance track
- Jesse 5.14.1 2011-Jun-16
- Florian 5.14.2-RC1 2011-Sep-19
- 5.14.2 2011-Sep-26
-
- David G 5.15.0 2011-Jun-20 The 5.15 development track
- Zefram 5.15.1 2011-Jul-20
- Ricardo 5.15.2 2011-Aug-20
- Stevan 5.15.3 2011-Sep-20
- Florian 5.15.4 2011-Oct-20
- Steve 5.15.5 2011-Nov-20
- Dave R 5.15.6 2011-Dec-20
- BinGOs 5.15.7 2012-Jan-20
- Max M 5.15.8 2012-Feb-20
- Abigail 5.15.9 2012-Mar-20
- Ricardo 5.16.0-RC0 2012-May-10
- Ricardo 5.16.0-RC1 2012-May-14
- Ricardo 5.16.0-RC2 2012-May-15
-
- Ricardo 5.16.0 2012-May-20 The 5.16 maintenance track
- Ricardo 5.16.1-RC1 2012-Aug-03
- Ricardo 5.16.1 2012-Aug-08
- Ricardo 5.16.2 2012-Nov-01
-
- Zefram 5.17.0 2012-May-26 The 5.17 development track
- Jesse L 5.17.1 2012-Jun-20
- TonyC 5.17.2 2012-Jul-20
-
-=head2 SELECTED RELEASE SIZES
-
-For example the notation "core: 212 29" in the release 1.000 means that
-it had in the core 212 kilobytes, in 29 files. The "core".."doc" are
-explained below.
-
- release core lib ext t doc
- ======================================================================
-
- 1.000 212 29 - - - - 38 51 62 3
- 1.014 219 29 - - - - 39 52 68 4
- 2.000 309 31 2 3 - - 55 57 92 4
- 2.001 312 31 2 3 - - 55 57 94 4
- 3.000 508 36 24 11 - - 79 73 156 5
- 3.044 645 37 61 20 - - 90 74 190 6
- 4.000 635 37 59 20 - - 91 75 198 4
- 4.019 680 37 85 29 - - 98 76 199 4
- 4.036 709 37 89 30 - - 98 76 208 5
- 5.000alpha2 785 50 114 32 - - 112 86 209 5
- 5.000alpha3 801 50 117 33 - - 121 87 209 5
- 5.000alpha9 1022 56 149 43 116 29 125 90 217 6
- 5.000a12h 978 49 140 49 205 46 152 97 228 9
- 5.000b3h 1035 53 232 70 216 38 162 94 218 21
- 5.000 1038 53 250 76 216 38 154 92 536 62
- 5.001m 1071 54 388 82 240 38 159 95 544 29
- 5.002 1121 54 661 101 287 43 155 94 847 35
- 5.003 1129 54 680 102 291 43 166 100 853 35
- 5.003_07 1231 60 748 106 396 53 213 137 976 39
- 5.004 1351 60 1230 136 408 51 355 161 1587 55
- 5.004_01 1356 60 1258 138 410 51 358 161 1587 55
- 5.004_04 1375 60 1294 139 413 51 394 162 1629 55
- 5.004_05 1463 60 1435 150 394 50 445 175 1855 59
- 5.004_51 1401 61 1260 140 413 53 358 162 1594 56
- 5.004_53 1422 62 1295 141 438 70 394 162 1637 56
- 5.004_56 1501 66 1301 140 447 74 408 165 1648 57
- 5.004_59 1555 72 1317 142 448 74 424 171 1678 58
- 5.004_62 1602 77 1327 144 629 92 428 173 1674 58
- 5.004_65 1626 77 1358 146 615 92 446 179 1698 60
- 5.004_68 1856 74 1382 152 619 92 463 187 1784 60
- 5.004_70 1863 75 1456 154 675 92 494 194 1809 60
- 5.004_73 1874 76 1467 152 762 102 506 196 1883 61
- 5.004_75 1877 76 1467 152 770 103 508 196 1896 62
- 5.005 1896 76 1469 152 795 103 509 197 1945 63
- 5.005_03 1936 77 1541 153 813 104 551 201 2176 72
- 5.005_50 1969 78 1842 301 795 103 514 198 1948 63
- 5.005_53 1999 79 1885 303 806 104 602 224 2002 67
- 5.005_56 2086 79 1970 307 866 113 672 238 2221 75
- 5.6.0 2820 79 2626 364 1096 129 863 280 2840 93
- 5.6.1 2946 78 2921 430 1171 132 1024 304 3330 102
- 5.6.2 2947 78 3143 451 1247 127 1303 387 3406 102
- 5.7.0 2977 80 2801 425 1250 132 975 307 3206 100
- 5.7.1 3351 84 3442 455 1944 167 1334 357 3698 124
- 5.7.2 3491 87 4858 618 3290 298 1598 449 3910 139
- 5.7.3 3299 85 4295 537 2196 300 2176 626 4171 120
- 5.8.0 3489 87 4533 585 2437 331 2588 726 4368 125
- 5.8.1 3674 90 5104 623 2604 353 2983 836 4625 134
- 5.8.2 3633 90 5111 623 2623 357 3019 848 4634 135
- 5.8.3 3625 90 5141 624 2660 363 3083 869 4669 136
- 5.8.4 3653 90 5170 634 2684 368 3148 885 4689 137
- 5.8.5 3664 90 4260 303 2707 369 3208 898 4689 138
- 5.8.6 3690 90 4271 303 3141 396 3411 925 4709 139
- 5.8.7 3788 90 4322 307 3297 401 3485 964 4744 141
- 5.8.8 3895 90 4357 314 3409 431 3622 1017 4979 144
- 5.8.9 4132 93 5508 330 3826 529 4364 1234 5348 152
- 5.9.0 3657 90 4951 626 2603 354 3011 841 4609 135
- 5.9.1 3580 90 5196 634 2665 367 3186 889 4725 138
- 5.9.2 3863 90 4654 312 3283 403 3551 973 4800 142
- 5.9.3 4096 91 5318 381 4806 597 4272 1214 5139 147
- 5.9.4 4393 94 5718 415 4578 642 4646 1310 5335 153
- 5.9.5 4681 96 6849 479 4827 671 5155 1490 5572 159
- 5.10.0 4710 97 7050 486 4899 673 5275 1503 5673 160
- 5.10.1 4858 98 7440 519 6195 921 6147 1751 5151 163
- 5.12.0 4999 100 1146 121 15227 2176 6400 1843 5342 168
- 5.12.1 5000 100 1146 121 15283 2178 6407 1846 5354 169
- 5.12.2 5003 100 1146 121 15404 2178 6413 1846 5376 170
- 5.12.3 5004 100 1146 121 15529 2180 6417 1848 5391 171
-
-The "core"..."doc" mean the following files from the Perl source code
-distribution. The glob notation ** means recursively, (.) means
-regular files.
-
- core *.[hcy]
- lib lib/**/*.p[ml]
- ext ext/**/*.{[hcyt],xs,pm} (for -5.10.1) or
- {dist,ext,cpan}/**/*.{[hcyt],xs,pm} (for 5.12.0-)
- t t/**/*(.) (for 1-5.005_56) or **/*.t (for 5.6.0-5.7.3)
- doc {README*,INSTALL,*[_.]man{,.?},pod/**/*.pod}
-
-Here are some statistics for the other subdirectories and one file in
-the Perl source distribution for somewhat more selected releases.
-
- ======================================================================
- Legend: kB #
-
- 1.014 2.001 3.044
-
- Configure 31 1 37 1 62 1
- eg - - 34 28 47 39
- h2pl - - - - 12 12
- msdos - - - - 41 13
- os2 - - - - 63 22
- usub - - - - 21 16
- x2p 103 17 104 17 137 17
-
- ======================================================================
-
- 4.000 4.019 4.036
-
- atarist - - - - 113 31
- Configure 73 1 83 1 86 1
- eg 47 39 47 39 47 39
- emacs 67 4 67 4 67 4
- h2pl 12 12 12 12 12 12
- hints - - 5 42 11 56
- msdos 57 15 58 15 60 15
- os2 81 29 81 29 113 31
- usub 25 7 43 8 43 8
- x2p 147 18 152 19 154 19
-
- ======================================================================
-
- 5.000a2 5.000a12h 5.000b3h 5.000 5.001m
-
- apollo 8 3 8 3 8 3 8 3 8 3
- atarist 113 31 113 31 - - - - - -
- bench - - 0 1 - - - - - -
- Bugs 2 5 26 1 - - - - - -
- dlperl 40 5 - - - - - - - -
- do 127 71 - - - - - - - -
- Configure - - 153 1 159 1 160 1 180 1
- Doc - - 26 1 75 7 11 1 11 1
- eg 79 58 53 44 51 43 54 44 54 44
- emacs 67 4 104 6 104 6 104 1 104 6
- h2pl 12 12 12 12 12 12 12 12 12 12
- hints 11 56 12 46 18 48 18 48 44 56
- msdos 60 15 60 15 - - - - - -
- os2 113 31 113 31 - - - - - -
- U - - 62 8 112 42 - - - -
- usub 43 8 - - - - - - - -
- vms - - 80 7 123 9 184 15 304 20
- x2p 171 22 171 21 162 20 162 20 279 20
-
- ======================================================================
-
- 5.002 5.003 5.003_07
-
- Configure 201 1 201 1 217 1
- eg 54 44 54 44 54 44
- emacs 108 1 108 1 143 1
- h2pl 12 12 12 12 12 12
- hints 73 59 77 60 90 62
- os2 84 17 56 10 117 42
- plan9 - - - - 79 15
- Porting - - - - 51 1
- utils 87 7 88 7 97 7
- vms 500 24 475 26 505 27
- x2p 280 20 280 20 280 19
-
- ======================================================================
-
- 5.004 5.004_04 5.004_62 5.004_65 5.004_68
-
- beos - - - - - - 1 1 1 1
- Configure 225 1 225 1 240 1 248 1 256 1
- cygwin32 23 5 23 5 23 5 24 5 24 5
- djgpp - - - - 14 5 14 5 14 5
- eg 81 62 81 62 81 62 81 62 81 62
- emacs 194 1 204 1 212 2 212 2 212 2
- h2pl 12 12 12 12 12 12 12 12 12 12
- hints 129 69 132 71 144 72 151 74 155 74
- os2 121 42 127 42 127 44 129 44 129 44
- plan9 82 15 82 15 82 15 82 15 82 15
- Porting 94 2 109 4 203 6 234 8 241 9
- qnx 1 2 1 2 1 2 1 2 1 2
- utils 112 8 118 8 124 8 156 9 159 9
- vms 518 34 524 34 538 34 569 34 569 34
- win32 285 33 378 36 470 39 493 39 575 41
- x2p 281 19 281 19 281 19 282 19 281 19
-
- ======================================================================
-
- 5.004_70 5.004_73 5.004_75 5.005 5.005_03
-
- apollo - - - - - - - - 0 1
- beos 1 1 1 1 1 1 1 1 1 1
- Configure 256 1 256 1 264 1 264 1 270 1
- cygwin32 24 5 24 5 24 5 24 5 24 5
- djgpp 14 5 14 5 14 5 14 5 15 5
- eg 86 65 86 65 86 65 86 65 86 65
- emacs 262 2 262 2 262 2 262 2 274 2
- h2pl 12 12 12 12 12 12 12 12 12 12
- hints 157 74 157 74 159 74 160 74 179 77
- mint - - - - - - - - 4 7
- mpeix - - - - 5 3 5 3 5 3
- os2 129 44 139 44 142 44 143 44 148 44
- plan9 82 15 82 15 82 15 82 15 82 15
- Porting 241 9 253 9 259 10 264 12 272 13
- qnx 1 2 1 2 1 2 1 2 1 2
- utils 160 9 160 9 160 9 160 9 164 9
- vms 570 34 572 34 573 34 575 34 583 34
- vos - - - - - - - - 156 10
- win32 577 41 585 41 585 41 587 41 600 42
- x2p 281 19 281 19 281 19 281 19 281 19
-
- ======================================================================
-
- 5.6.0 5.6.1 5.6.2 5.7.3
-
- apollo 8 3 8 3 8 3 8 3
- beos 5 2 5 2 5 2 6 4
- Configure 346 1 361 1 363 1 394 1
- Cross - - - - - - 4 2
- djgpp 19 6 19 6 19 6 21 7
- eg 112 71 112 71 112 71 - -
- emacs 303 4 319 4 319 4 319 4
- epoc 29 8 35 8 35 8 36 8
- h2pl 24 15 24 15 24 15 24 15
- hints 242 83 250 84 321 89 272 87
- mint 11 9 11 9 11 9 11 9
- mpeix 9 4 9 4 9 4 9 4
- NetWare - - - - - - 423 57
- os2 214 59 224 60 224 60 357 66
- plan9 92 17 92 17 92 17 85 15
- Porting 361 15 390 16 390 16 425 21
- qnx 5 3 5 3 5 3 5 3
- utils 228 12 221 11 222 11 267 13
- uts - - - - - - 12 3
- vmesa 25 4 25 4 25 4 25 4
- vms 686 38 627 38 627 38 649 36
- vos 227 12 249 15 248 15 281 17
- win32 755 41 782 42 801 42 1006 50
- x2p 307 20 307 20 307 20 345 20
-
- ======================================================================
-
- 5.8.0 5.8.1 5.8.2 5.8.3 5.8.4
-
- apollo 8 3 8 3 8 3 8 3 8 3
- beos 6 4 6 4 6 4 6 4 6 4
- Configure 472 1 493 1 493 1 493 1 494 1
- Cross 4 2 45 10 45 10 45 10 45 10
- djgpp 21 7 21 7 21 7 21 7 21 7
- emacs 319 4 329 4 329 4 329 4 329 4
- epoc 33 8 33 8 33 8 33 8 33 8
- h2pl 24 15 24 15 24 15 24 15 24 15
- hints 294 88 321 89 321 89 321 89 348 91
- mint 11 9 11 9 11 9 11 9 11 9
- mpeix 24 5 25 5 25 5 25 5 25 5
- NetWare 488 61 490 61 490 61 490 61 488 61
- os2 361 66 445 67 450 67 488 67 488 67
- plan9 85 15 325 17 325 17 325 17 321 17
- Porting 479 22 537 32 538 32 539 32 538 33
- qnx 5 3 5 3 5 3 5 3 5 3
- utils 275 15 258 16 258 16 263 19 263 19
- uts 12 3 12 3 12 3 12 3 12 3
- vmesa 25 4 25 4 25 4 25 4 25 4
- vms 648 36 654 36 654 36 656 36 656 36
- vos 330 20 335 20 335 20 335 20 335 20
- win32 1062 49 1125 49 1127 49 1126 49 1181 56
- x2p 347 20 348 20 348 20 348 20 348 20
-
- ======================================================================
-
- 5.8.5 5.8.6 5.8.7 5.8.8 5.8.9
-
- apollo 8 3 8 3 8 3 8 3 8 3
- beos 6 4 6 4 8 4 8 4 8 4
- Configure 494 1 494 1 495 1 506 1 520 1
- Cross 45 10 45 10 45 10 45 10 46 10
- djgpp 21 7 21 7 21 7 21 7 21 7
- emacs 329 4 329 4 329 4 329 4 406 4
- epoc 33 8 33 8 33 8 34 8 35 8
- h2pl 24 15 24 15 24 15 24 15 24 15
- hints 350 91 352 91 355 94 360 94 387 99
- mint 11 9 11 9 11 9 11 9 11 9
- mpeix 25 5 25 5 25 5 49 6 49 6
- NetWare 488 61 488 61 488 61 490 61 491 61
- os2 488 67 488 67 488 67 488 67 552 70
- plan9 321 17 321 17 321 17 322 17 324 17
- Porting 538 34 548 35 549 35 564 37 625 41
- qnx 5 3 5 3 5 3 5 3 5 3
- utils 265 19 265 19 266 19 267 19 281 21
- uts 12 3 12 3 12 3 12 3 12 3
- vmesa 25 4 25 4 25 4 25 4 25 4
- vms 657 36 658 36 662 36 664 36 716 35
- vos 335 20 335 20 335 20 336 21 345 22
- win32 1183 56 1190 56 1199 56 1219 56 1484 68
- x2p 349 20 349 20 349 20 349 19 350 19
-
- ======================================================================
-
- 5.9.0 5.9.1 5.9.2 5.9.3 5.9.4
-
- apollo 8 3 8 3 8 3 8 3 8 3
- beos 6 4 6 4 8 4 8 4 8 4
- Configure 493 1 493 1 495 1 508 1 512 1
- Cross 45 10 45 10 45 10 45 10 46 10
- djgpp 21 7 21 7 21 7 21 7 21 7
- emacs 329 4 329 4 329 4 329 4 329 4
- epoc 33 8 33 8 33 8 34 8 34 8
- h2pl 24 15 24 15 24 15 24 15 24 15
- hints 321 89 346 91 355 94 359 94 366 96
- mad - - - - - - - - 174 6
- mint 11 9 11 9 11 9 11 9 11 9
- mpeix 25 5 25 5 25 5 49 6 49 6
- NetWare 489 61 487 61 487 61 489 61 489 61
- os2 444 67 488 67 488 67 488 67 488 67
- plan9 325 17 321 17 321 17 322 17 323 17
- Porting 537 32 536 33 549 36 564 38 576 38
- qnx 5 3 5 3 5 3 5 3 5 3
- symbian - - - - - - 293 53 293 53
- utils 258 16 263 19 268 20 273 23 275 24
- uts 12 3 12 3 12 3 12 3 12 3
- vmesa 25 4 25 4 25 4 25 4 25 4
- vms 660 36 547 33 553 33 661 33 696 33
- vos 11 7 11 7 11 7 11 7 11 7
- win32 1120 49 1124 51 1191 56 1209 56 1719 90
- x2p 348 20 348 20 349 20 349 19 349 19
-
- ======================================================================
-
- 5.9.5 5.10.0 5.10.1 5.12.0 5.12.1
-
- apollo 8 3 8 3 0 3 0 3 0 3
- beos 8 4 8 4 4 4 4 4 4 4
- Configure 518 1 518 1 533 1 536 1 536 1
- Cross 122 15 122 15 119 15 118 15 118 15
- djgpp 21 7 21 7 17 7 17 7 17 7
- emacs 329 4 406 4 402 4 402 4 402 4
- epoc 34 8 35 8 31 8 31 8 31 8
- h2pl 24 15 24 15 12 15 12 15 12 15
- hints 377 98 381 98 385 100 368 97 368 97
- mad 182 8 182 8 174 8 174 8 174 8
- mint 11 9 11 9 3 9 - - - -
- mpeix 49 6 49 6 45 6 45 6 45 6
- NetWare 489 61 489 61 465 61 466 61 466 61
- os2 552 70 552 70 507 70 507 70 507 70
- plan9 324 17 324 17 316 17 316 17 316 17
- Porting 627 40 632 40 933 53 749 54 749 54
- qnx 5 3 5 4 1 4 1 4 1 4
- symbian 300 54 300 54 290 54 288 54 288 54
- utils 260 26 264 27 268 27 269 27 269 27
- uts 12 3 12 3 8 3 8 3 8 3
- vmesa 25 4 25 4 21 4 21 4 21 4
- vms 690 32 722 32 693 30 645 18 645 18
- vos 19 8 19 8 16 8 16 8 16 8
- win32 1482 68 1485 68 1497 70 1841 73 1841 73
- x2p 349 19 349 19 345 19 345 19 345 19
-
- ======================================================================
-
- 5.12.2 5.12.3
-
- apollo 0 3 0 3
- beos 4 4 4 4
- Configure 536 1 536 1
- Cross 118 15 118 15
- djgpp 17 7 17 7
- emacs 402 4 402 4
- epoc 31 8 31 8
- h2pl 12 15 12 15
- hints 368 97 368 97
- mad 174 8 174 8
- mpeix 45 6 45 6
- NetWare 466 61 466 61
- os2 507 70 507 70
- plan9 316 17 316 17
- Porting 750 54 750 54
- qnx 1 4 1 4
- symbian 288 54 288 54
- utils 269 27 269 27
- uts 8 3 8 3
- vmesa 21 4 21 4
- vms 646 18 644 18
- vos 16 8 16 8
- win32 1841 73 1841 73
- x2p 345 19 345 19
-
-=head2 SELECTED PATCH SIZES
-
-The "diff lines kB" means that for example the patch 5.003_08, to be
-applied on top of the 5.003_07 (or whatever was before the 5.003_08)
-added lines for 110 kilobytes, it removed lines for 19 kilobytes, and
-changed lines for 424 kilobytes. Just the lines themselves are
-counted, not their context. The "+ - !" become from the diff(1)
-context diff output format.
-
- Pump- Release Date diff lines kB
- king -------------
- + - !
- ======================================================================
-
- Chip 5.003_08 1996-Nov-19 110 19 424
- 5.003_09 1996-Nov-26 38 9 248
- 5.003_10 1996-Nov-29 29 2 27
- 5.003_11 1996-Dec-06 73 12 165
- 5.003_12 1996-Dec-19 275 6 436
- 5.003_13 1996-Dec-20 95 1 56
- 5.003_14 1996-Dec-23 23 7 333
- 5.003_15 1996-Dec-23 0 0 1
- 5.003_16 1996-Dec-24 12 3 50
- 5.003_17 1996-Dec-27 19 1 14
- 5.003_18 1996-Dec-31 21 1 32
- 5.003_19 1997-Jan-04 80 3 85
- 5.003_20 1997-Jan-07 18 1 146
- 5.003_21 1997-Jan-15 38 10 221
- 5.003_22 1997-Jan-16 4 0 18
- 5.003_23 1997-Jan-25 71 15 119
- 5.003_24 1997-Jan-29 426 1 20
- 5.003_25 1997-Feb-04 21 8 169
- 5.003_26 1997-Feb-10 16 1 15
- 5.003_27 1997-Feb-18 32 10 38
- 5.003_28 1997-Feb-21 58 4 66
- 5.003_90 1997-Feb-25 22 2 34
- 5.003_91 1997-Mar-01 37 1 39
- 5.003_92 1997-Mar-06 16 3 69
- 5.003_93 1997-Mar-10 12 3 15
- 5.003_94 1997-Mar-22 407 7 200
- 5.003_95 1997-Mar-25 41 1 37
- 5.003_96 1997-Apr-01 283 5 261
- 5.003_97 1997-Apr-03 13 2 34
- 5.003_97a 1997-Apr-05 57 1 27
- 5.003_97b 1997-Apr-08 14 1 20
- 5.003_97c 1997-Apr-10 20 1 16
- 5.003_97d 1997-Apr-13 8 0 16
- 5.003_97e 1997-Apr-15 15 4 46
- 5.003_97f 1997-Apr-17 7 1 33
- 5.003_97g 1997-Apr-18 6 1 42
- 5.003_97h 1997-Apr-24 23 3 68
- 5.003_97i 1997-Apr-25 23 1 31
- 5.003_97j 1997-Apr-28 36 1 49
- 5.003_98 1997-Apr-30 171 12 539
- 5.003_99 1997-May-01 6 0 7
- 5.003_99a 1997-May-09 36 2 61
- p54rc1 1997-May-12 8 1 11
- p54rc2 1997-May-14 6 0 40
-
- 5.004 1997-May-15 4 0 4
-
- Tim 5.004_01 1997-Jun-13 222 14 57
- 5.004_02 1997-Aug-07 112 16 119
- 5.004_03 1997-Sep-05 109 0 17
- 5.004_04 1997-Oct-15 66 8 173
-
-=head3 The patch-free era
-
-In more modern times, named releases don't come as often, and as progress
-can be followed (nearly) instantly (with rsync, and since late 2008, git)
-patches between versions are no longer provided. However, that doesn't
-keep us from calculating how large a patch could have been. Which is
-shown in the table below. Unless noted otherwise, the size mentioned is
-the patch to bring version x.y.z to x.y.z+1.
-
- Sarathy 5.6.1 2001-Apr-08 531 44 651
- Rafael 5.6.2 2003-Nov-15 20 11 1819
-
- Jarkko 5.8.0 2002-Jul-18 1205 31 471 From 5.7.3
-
- 5.8.1 2003-Sep-25 243 102 6162
- Nicholas 5.8.2 2003-Nov-05 10 50 788
- 5.8.3 2004-Jan-14 31 13 360
- 5.8.4 2004-Apr-21 33 8 299
- 5.8.5 2004-Jul-19 11 19 255
- 5.8.6 2004-Nov-27 35 3 192
- 5.8.7 2005-May-30 75 34 778
- 5.8.8 2006-Jan-31 131 42 1251
- 5.8.9 2008-Dec-14 340 132 12988
-
- Hugo 5.9.0 2003-Oct-27 281 168 7132 From 5.8.0
- Rafael 5.9.1 2004-Mar-16 57 250 2107
- 5.9.2 2005-Apr-01 720 57 858
- 5.9.3 2006-Jan-28 1124 102 1906
- 5.9.4 2006-Aug-15 896 60 862
- 5.9.5 2007-Jul-07 1149 128 1062
-
- 5.10.0 2007-Dec-18 50 31 13111 From 5.9.5
-
-
-=head1 THE KEEPERS OF THE RECORDS
-
-Jarkko Hietaniemi <F<jhi@iki.fi>>.
-
-Thanks to the collective memory of the Perlfolk. In addition to the
-Keepers of the Pumpkin also Alan Champion, Mark Dominus,
-Andreas KE<0xf6>nig, John Macdonald, Matthias Neeracher, Jeff Okamoto,
-Michael Peppler, Randal Schwartz, and Paul D. Smith sent corrections
-and additions. Abigail added file and patch size data for the 5.6.0 - 5.10
-era.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlhpux.pod b/Master/tlpkg/tlperl/lib/pods/perlhpux.pod
deleted file mode 100644
index 7bd4b93299d..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlhpux.pod
+++ /dev/null
@@ -1,674 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you see.
-It is written in the POD format (see pod/perlpod.pod) which is specially
-designed to be readable as is.
-
-=head1 NAME
-
-perlhpux - Perl version 5 on Hewlett-Packard Unix (HP-UX) systems
-
-=head1 DESCRIPTION
-
-This document describes various features of HP's Unix operating system
-(HP-UX) that will affect how Perl version 5 (hereafter just Perl) is
-compiled and/or runs.
-
-=head2 Using perl as shipped with HP-UX
-
-Application release September 2001, HP-UX 11.00 is the first to ship
-with Perl. By the time it was perl-5.6.1 in /opt/perl. The first
-occurrence is on CD 5012-7954 and can be installed using
-
- swinstall -s /cdrom perl
-
-assuming you have mounted that CD on /cdrom. In this version the
-following modules were installed:
-
- ActivePerl::DocTools-0.04 HTML::Parser-3.19 XML::DOM-1.25
- Archive::Tar-0.072 HTML::Tagset-3.03 XML::Parser-2.27
- Compress::Zlib-1.08 MIME::Base64-2.11 XML::Simple-1.05
- Convert::ASN1-0.10 Net-1.07 XML::XPath-1.09
- Digest::MD5-2.11 PPM-2.1.5 XML::XSLT-0.32
- File::CounterFile-0.12 SOAP::Lite-0.46 libwww-perl-5.51
- Font::AFM-1.18 Storable-1.011 libxml-perl-0.07
- HTML-Tree-3.11 URI-1.11 perl-ldap-0.23
-
-That build was a portable hppa-1.1 multithread build that supports large
-files compiled with gcc-2.9-hppa-991112.
-
-If you perform a new installation, then (a newer) Perl will be installed
-automatically. Preinstalled HP-UX systems now slao have more recent versions
-of Perl and the updated modules.
-
-The official (threaded) builds from HP, as they are shipped on the
-Application DVD/CD's are available on
-L<http://www.software.hp.com/portal/swdepot/displayProductInfo.do?productNumber=PERL>
-for both PA-RISC and IPF (Itanium Processor Family). They are built
-with the HP ANSI-C compiler. Up till 5.8.8 that was done by ActiveState.
-
-To see what version is included on the DVD (assumed here to be mounted
-on /cdrom), issue this command:
-
- # swlist -s /cdrom perl
- # perl D.5.8.8.B 5.8.8 Perl Programming Language
- perl.Perl5-32 D.5.8.8.B 32-bit 5.8.8 Perl Programming Language with Extensions
- perl.Perl5-64 D.5.8.8.B 64-bit 5.8.8 Perl Programming Language with Extensions
-
-=head2 Using perl from HP's porting centre
-
-HP porting centre tries very hard to keep up with customer demand and
-release updates from the Open Source community. Having precompiled
-Perl binaries available is obvious.
-
-The HP porting centres are limited in what systems they are allowed
-to port to and they usually choose the two most recent OS versions
-available. This means that at the moment of writing, there are only
-HP-UX 11.11 (pa-risc 2.0) and HP-UX 11.23 (Itanium 2) ports available
-on the porting centres.
-
-HP has asked the porting centre to move Open Source binaries
-from /opt to /usr/local, so binaries produced since the start
-of July 2002 are located in /usr/local.
-
-One of HP porting centres URL's is L<http://hpux.connect.org.uk/>
-The port currently available is built with GNU gcc.
-
-=head2 Compiling Perl 5 on HP-UX
-
-When compiling Perl, you must use an ANSI C compiler. The C compiler
-that ships with all HP-UX systems is a K&R compiler that should only be
-used to build new kernels.
-
-Perl can be compiled with either HP's ANSI C compiler or with gcc. The
-former is recommended, as not only can it compile Perl with no
-difficulty, but also can take advantage of features listed later that
-require the use of HP compiler-specific command-line flags.
-
-If you decide to use gcc, make sure your installation is recent and
-complete, and be sure to read the Perl INSTALL file for more gcc-specific
-details.
-
-=head2 PA-RISC
-
-HP's HP9000 Unix systems run on HP's own Precision Architecture
-(PA-RISC) chip. HP-UX used to run on the Motorola MC68000 family of
-chips, but any machine with this chip in it is quite obsolete and this
-document will not attempt to address issues for compiling Perl on the
-Motorola chipset.
-
-The version of PA-RISC at the time of this document's last update is 2.0,
-which is also the last there will be. HP PA-RISC systems are usually
-refered to with model description "HP 9000". The last CPU in this series
-is the PA-8900. Support for PA-RISC architectured machines officially
-ends as shown in the following table:
-
- PA-RISC End-of-Life Roadmap
- +--------+----------------+----------------+-----------------+
- | HP9000 | Superdome | PA-8700 | Spring 2011 |
- | 4-128 | | PA-8800/sx1000 | Summer 2012 |
- | cores | | PA-8900/sx1000 | 2014 |
- | | | PA-8900/sx2000 | 2015 |
- +--------+----------------+----------------+-----------------+
- | HP9000 | rp7410, rp8400 | PA-8700 | Spring 2011 |
- | 2-32 | rp7420, rp8420 | PA-8800/sx1000 | 2012 |
- | cores | rp7440, rp8440 | PA-8900/sx1000 | Autumn 2013 |
- | | | PA-8900/sx2000 | 2015 |
- +--------+----------------+----------------+-----------------+
- | HP9000 | rp44x0 | PA-8700 | Spring 2011 |
- | 1-8 | | PA-8800/rp44x0 | 2012 |
- | cores | | PA-8900/rp44x0 | 2014 |
- +--------+----------------+----------------+-----------------+
- | HP9000 | rp34x0 | PA-8700 | Spring 2011 |
- | 1-4 | | PA-8800/rp34x0 | 2012 |
- | cores | | PA-8900/rp34x0 | 2014 |
- +--------+----------------+----------------+-----------------+
-
-From L<http://www.hp.com/products1/evolution/9000/faqs.html>
-
- The last order date for HP 9000 systems was December 31, 2008.
-
-A complete list of models at the time the OS was built is in the file
-/usr/sam/lib/mo/sched.models. The first column corresponds to the last
-part of the output of the "model" command. The second column is the
-PA-RISC version and the third column is the exact chip type used.
-(Start browsing at the bottom to prevent confusion ;-)
-
- # model
- 9000/800/L1000-44
- # grep L1000-44 /usr/sam/lib/mo/sched.models
- L1000-44 2.0 PA8500
-
-=head2 Portability Between PA-RISC Versions
-
-An executable compiled on a PA-RISC 2.0 platform will not execute on a
-PA-RISC 1.1 platform, even if they are running the same version of
-HP-UX. If you are building Perl on a PA-RISC 2.0 platform and want that
-Perl to also run on a PA-RISC 1.1, the compiler flags +DAportable and
-+DS32 should be used.
-
-It is no longer possible to compile PA-RISC 1.0 executables on either
-the PA-RISC 1.1 or 2.0 platforms. The command-line flags are accepted,
-but the resulting executable will not run when transferred to a PA-RISC
-1.0 system.
-
-=head2 PA-RISC 1.0
-
-The original version of PA-RISC, HP no longer sells any system with this chip.
-
-The following systems contained PA-RISC 1.0 chips:
-
- 600, 635, 645, 808, 815, 822, 825, 832, 834, 835, 840, 842, 845, 850,
- 852, 855, 860, 865, 870, 890
-
-=head2 PA-RISC 1.1
-
-An upgrade to the PA-RISC design, it shipped for many years in many different
-system.
-
-The following systems contain with PA-RISC 1.1 chips:
-
- 705, 710, 712, 715, 720, 722, 725, 728, 730, 735, 742, 743, 744, 745,
- 747, 750, 755, 770, 777, 778, 779, 800, 801, 803, 806, 807, 809, 811,
- 813, 816, 817, 819, 821, 826, 827, 829, 831, 837, 839, 841, 847, 849,
- 851, 856, 857, 859, 867, 869, 877, 887, 891, 892, 897, A180, A180C,
- B115, B120, B132L, B132L+, B160L, B180L, C100, C110, C115, C120,
- C160L, D200, D210, D220, D230, D250, D260, D310, D320, D330, D350,
- D360, D410, DX0, DX5, DXO, E25, E35, E45, E55, F10, F20, F30, G30,
- G40, G50, G60, G70, H20, H30, H40, H50, H60, H70, I30, I40, I50, I60,
- I70, J200, J210, J210XC, K100, K200, K210, K220, K230, K400, K410,
- K420, S700i, S715, S744, S760, T500, T520
-
-=head2 PA-RISC 2.0
-
-The most recent upgrade to the PA-RISC design, it added support for
-64-bit integer data.
-
-As of the date of this document's last update, the following systems
-contain PA-RISC 2.0 chips:
-
- 700, 780, 781, 782, 783, 785, 802, 804, 810, 820, 861, 871, 879, 889,
- 893, 895, 896, 898, 899, A400, A500, B1000, B2000, C130, C140, C160,
- C180, C180+, C180-XP, C200+, C400+, C3000, C360, C3600, CB260, D270,
- D280, D370, D380, D390, D650, J220, J2240, J280, J282, J400, J410,
- J5000, J5500XM, J5600, J7000, J7600, K250, K260, K260-EG, K270, K360,
- K370, K380, K450, K460, K460-EG, K460-XP, K470, K570, K580, L1000,
- L2000, L3000, N4000, R380, R390, SD16000, SD32000, SD64000, T540,
- T600, V2000, V2200, V2250, V2500, V2600
-
-Just before HP took over Compaq, some systems were renamed. the link
-that contained the explanation is dead, so here's a short summary:
-
- HP 9000 A-Class servers, now renamed HP Server rp2400 series.
- HP 9000 L-Class servers, now renamed HP Server rp5400 series.
- HP 9000 N-Class servers, now renamed HP Server rp7400.
-
- rp2400, rp2405, rp2430, rp2450, rp2470, rp3410, rp3440, rp4410,
- rp4440, rp5400, rp5405, rp5430, rp5450, rp5470, rp7400, rp7405,
- rp7410, rp7420, rp7440, rp8400, rp8420, rp8440, Superdome
-
-The current naming convention is:
-
- aadddd
- ||||`+- 00 - 99 relative capacity & newness (upgrades, etc.)
- |||`--- unique number for each architecture to ensure different
- ||| systems do not have the same numbering across
- ||| architectures
- ||`---- 1 - 9 identifies family and/or relative positioning
- ||
- |`----- c = ia32 (cisc)
- | p = pa-risc
- | x = ia-64 (Itanium & Itanium 2)
- | h = housing
- `------ t = tower
- r = rack optimized
- s = super scalable
- b = blade
- sa = appliance
-
-=head2 Itanium Processor Family (IPF) and HP-UX
-
-HP-UX also runs on the new Itanium processor. This requires the use
-of a different version of HP-UX (currently 11.23 or 11i v2), and with
-the exception of a few differences detailed below and in later sections,
-Perl should compile with no problems.
-
-Although PA-RISC binaries can run on Itanium systems, you should not
-attempt to use a PA-RISC version of Perl on an Itanium system. This is
-because shared libraries created on an Itanium system cannot be loaded
-while running a PA-RISC executable.
-
-HP Itanium 2 systems are usually refered to with model description
-"HP Integrity".
-
-=head2 Itanium, Itanium 2 & Madison 6
-
-HP also ships servers with the 128-bit Itanium processor(s). The cx26x0
-is told to have Madison 6. As of the date of this document's last update,
-the following systems contain Itanium or Itanium 2 chips (this is likely
-to be out of date):
-
- BL60p, BL860c, BL870c, cx2600, cx2620, rx1600, rx1620, rx2600,
- rx2600hptc, rx2620, rx2660, rx3600, rx4610, rx4640, rx5670,
- rx6600, rx7420, rx7620, rx7640, rx8420, rx8620, rx8640, rx9610,
- sx1000, sx2000
-
-To see all about your machine, type
-
- # model
- ia64 hp server rx2600
- # /usr/contrib/bin/machinfo
-
-=head2 HP-UX versions
-
-Not all architectures (PA = PA-RISC, IPF = Itanium Processor Family)
-support all versions of HP-UX, here is a short list
-
- HP-UX version Kernel Architecture
- ------------- ------ ------------
- 10.20 32 bit PA
- 11.00 32/64 PA
- 11.11 11i v1 32/64 PA
- 11.22 11i v2 64 IPF
- 11.23 11i v2 64 PA & IPF
- 11.31 11i v3 64 PA & IPF
-
-See for the full list of hardware/OS support and expected end-of-life
-L<http://www.hp.com/go/hpuxservermatrix>
-
-=head2 Building Dynamic Extensions on HP-UX
-
-HP-UX supports dynamically loadable libraries (shared libraries).
-Shared libraries end with the suffix .sl. On Itanium systems,
-they end with the suffix .so.
-
-Shared libraries created on a platform using a particular PA-RISC
-version are not usable on platforms using an earlier PA-RISC version by
-default. However, this backwards compatibility may be enabled using the
-same +DAportable compiler flag (with the same PA-RISC 1.0 caveat
-mentioned above).
-
-Shared libraries created on an Itanium platform cannot be loaded on
-a PA-RISC platform. Shared libraries created on a PA-RISC platform
-can only be loaded on an Itanium platform if it is a PA-RISC executable
-that is attempting to load the PA-RISC library. A PA-RISC shared
-library cannot be loaded into an Itanium executable nor vice-versa.
-
-To create a shared library, the following steps must be performed:
-
- 1. Compile source modules with +z or +Z flag to create a .o module
- which contains Position-Independent Code (PIC). The linker will
- tell you in the next step if +Z was needed.
- (For gcc, the appropriate flag is -fpic or -fPIC.)
-
- 2. Link the shared library using the -b flag. If the code calls
- any functions in other system libraries (e.g., libm), it must
- be included on this line.
-
-(Note that these steps are usually handled automatically by the extension's
-Makefile).
-
-If these dependent libraries are not listed at shared library creation
-time, you will get fatal "Unresolved symbol" errors at run time when the
-library is loaded.
-
-You may create a shared library that refers to another library, which
-may be either an archive library or a shared library. If this second
-library is a shared library, this is called a "dependent library". The
-dependent library's name is recorded in the main shared library, but it
-is not linked into the shared library. Instead, it is loaded when the
-main shared library is loaded. This can cause problems if you build an
-extension on one system and move it to another system where the
-libraries may not be located in the same place as on the first system.
-
-If the referred library is an archive library, then it is treated as a
-simple collection of .o modules (all of which must contain PIC). These
-modules are then linked into the shared library.
-
-Note that it is okay to create a library which contains a dependent
-library that is already linked into perl.
-
-Some extensions, like DB_File and Compress::Zlib use/require prebuilt
-libraries for the perl extensions/modules to work. If these libraries
-are built using the default configuration, it might happen that you
-run into an error like "invalid loader fixup" during load phase.
-HP is aware of this problem. Search the HP-UX cxx-dev forums for
-discussions about the subject. The short answer is that B<everything>
-(all libraries, everything) must be compiled with C<+z> or C<+Z> to be
-PIC (position independent code). (For gcc, that would be
-C<-fpic> or C<-fPIC>). In HP-UX 11.00 or newer the linker
-error message should tell the name of the offending object file.
-
-A more general approach is to intervene manually, as with an example for
-the DB_File module, which requires SleepyCat's libdb.sl:
-
- # cd .../db-3.2.9/build_unix
- # vi Makefile
- ... add +Z to all cflags to create shared objects
- CFLAGS= -c $(CPPFLAGS) +Z -Ae +O2 +Onolimit \
- -I/usr/local/include -I/usr/include/X11R6
- CXXFLAGS= -c $(CPPFLAGS) +Z -Ae +O2 +Onolimit \
- -I/usr/local/include -I/usr/include/X11R6
-
- # make clean
- # make
- # mkdir tmp
- # cd tmp
- # ar x ../libdb.a
- # ld -b -o libdb-3.2.sl *.o
- # mv libdb-3.2.sl /usr/local/lib
- # rm *.o
- # cd /usr/local/lib
- # rm -f libdb.sl
- # ln -s libdb-3.2.sl libdb.sl
-
- # cd .../DB_File-1.76
- # make distclean
- # perl Makefile.PL
- # make
- # make test
- # make install
-
-As of db-4.2.x it is no longer needed to do this by hand. Sleepycat
-has changed the configuration process to add +z on HP-UX automatically.
-
- # cd .../db-4.2.25/build_unix
- # env CFLAGS=+DD64 LDFLAGS=+DD64 ../dist/configure
-
-should work to generate 64bit shared libraries for HP-UX 11.00 and 11i.
-
-It is no longer possible to link PA-RISC 1.0 shared libraries (even
-though the command-line flags are still present).
-
-PA-RISC and Itanium object files are not interchangeable. Although
-you may be able to use ar to create an archive library of PA-RISC
-object files on an Itanium system, you cannot link against it using
-an Itanium link editor.
-
-=head2 The HP ANSI C Compiler
-
-When using this compiler to build Perl, you should make sure that the
-flag -Aa is added to the cpprun and cppstdin variables in the config.sh
-file (though see the section on 64-bit perl below). If you are using a
-recent version of the Perl distribution, these flags are set automatically.
-
-Even though HP-UX 10.20 and 11.00 are not actively maintained by HP
-anymore, updates for the HP ANSI C compiler are still available from
-time to time, and it might be advisable to see if updates are applicable.
-At the moment of writing, the latests available patches for 11.00 that
-should be applied are PHSS_35098, PHSS_35175, PHSS_35100, PHSS_33036,
-and PHSS_33902). If you have a SUM account, you can use it to search
-for updates/patches. Enter "ANSI" as keyword.
-
-=head2 The GNU C Compiler
-
-When you are going to use the GNU C compiler (gcc), and you don't have
-gcc yet, you can either build it yourself from the sources (available
-from e.g. L<http://gcc.gnu.org/mirrors.html>) or fetch
-a prebuilt binary from the HP porting center. gcc prebuilds can be
-fetched from
-L<http://h21007.www2.hp.com/dspp/tech/tech_TechSoftwareDetailPage_IDX/1,1703,547,00.html>
-(Browse through the list, because there are often multiple versions of
-the same package available).
-
-Above mentioned distributions are depots. H.Merijn Brand has made prebuilt
-gcc binaries available on L<http://mirrors.develooper.com/hpux/> and/or
-L<http://www.cmve.net/~merijn/> for HP-UX 10.20, HP-UX 11.00, HP-UX 11.11
-(HP-UX 11i v1), and HP-UX 11.23 (HP-UX 11i v2) in both 32- and 64-bit
-versions. These are bzipped tar archives that also include recent GNU
-binutils and GNU gdb. Read the instructions on that page to rebuild gcc
-using itself.
-
-On PA-RISC you need a different compiler for 32-bit applications and for
-64-bit applications. On PA-RISC, 32-bit objects and 64-bit objects do
-not mix. Period. There is no different behaviour for HP C-ANSI-C or GNU
-gcc. So if you require your perl binary to use 64-bit libraries, like
-Oracle-64bit, you MUST build a 64-bit perl.
-
-Building a 64-bit capable gcc on PA-RISC from source is possible only when
-you have the HP C-ANSI C compiler or an already working 64-bit binary of
-gcc available. Best performance for perl is achieved with HP's native
-compiler.
-
-=head2 Using Large Files with Perl on HP-UX
-
-Beginning with HP-UX version 10.20, files larger than 2GB (2^31 bytes)
-may be created and manipulated. Three separate methods of doing this
-are available. Of these methods, the best method for Perl is to compile
-using the -Duselargefiles flag to Configure. This causes Perl to be
-compiled using structures and functions in which these are 64 bits wide,
-rather than 32 bits wide. (Note that this will only work with HP's ANSI
-C compiler. If you want to compile Perl using gcc, you will have to get
-a version of the compiler that supports 64-bit operations. See above for
-where to find it.)
-
-There are some drawbacks to this approach. One is that any extension
-which calls any file-manipulating C function will need to be recompiled
-(just follow the usual "perl Makefile.PL; make; make test; make install"
-procedure).
-
-The list of functions that will need to recompiled is:
- creat, fgetpos, fopen,
- freopen, fsetpos, fstat,
- fstatvfs, fstatvfsdev, ftruncate,
- ftw, lockf, lseek,
- lstat, mmap, nftw,
- open, prealloc, stat,
- statvfs, statvfsdev, tmpfile,
- truncate, getrlimit, setrlimit
-
-Another drawback is only valid for Perl versions before 5.6.0. This
-drawback is that the seek and tell functions (both the builtin version
-and POSIX module version) will not perform correctly.
-
-It is strongly recommended that you use this flag when you run
-Configure. If you do not do this, but later answer the question about
-large files when Configure asks you, you may get a configuration that
-cannot be compiled, or that does not function as expected.
-
-=head2 Threaded Perl on HP-UX
-
-It is possible to compile a version of threaded Perl on any version of
-HP-UX before 10.30, but it is strongly suggested that you be running on
-HP-UX 11.00 at least.
-
-To compile Perl with threads, add -Dusethreads to the arguments of
-Configure. Verify that the -D_POSIX_C_SOURCE=199506L compiler flag is
-automatically added to the list of flags. Also make sure that -lpthread
-is listed before -lc in the list of libraries to link Perl with. The
-hints provided for HP-UX during Configure will try very hard to get
-this right for you.
-
-HP-UX versions before 10.30 require a separate installation of a POSIX
-threads library package. Two examples are the HP DCE package, available
-on "HP-UX Hardware Extensions 3.0, Install and Core OS, Release 10.20,
-April 1999 (B3920-13941)" or the Freely available PTH package, available
-on H.Merijn's site (L<http://mirrors.develooper.com/hpux/>). The use of PTH
-will be unsupported in perl-5.12 and up and is rather buggy in 5.11.x.
-
-If you are going to use the HP DCE package, the library used for threading
-is /usr/lib/libcma.sl, but there have been multiple updates of that
-library over time. Perl will build with the first version, but it
-will not pass the test suite. Older Oracle versions might be a compelling
-reason not to update that library, otherwise please find a newer version
-in one of the following patches: PHSS_19739, PHSS_20608, or PHSS_23672
-
-reformatted output:
-
- d3:/usr/lib 106 > what libcma-*.1
- libcma-00000.1:
- HP DCE/9000 1.5 Module: libcma.sl (Export)
- Date: Apr 29 1996 22:11:24
- libcma-19739.1:
- HP DCE/9000 1.5 PHSS_19739-40 Module: libcma.sl (Export)
- Date: Sep 4 1999 01:59:07
- libcma-20608.1:
- HP DCE/9000 1.5 PHSS_20608 Module: libcma.1 (Export)
- Date: Dec 8 1999 18:41:23
- libcma-23672.1:
- HP DCE/9000 1.5 PHSS_23672 Module: libcma.1 (Export)
- Date: Apr 9 2001 10:01:06
- d3:/usr/lib 107 >
-
-If you choose for the PTH package, use swinstall to install pth in
-the default location (/opt/pth), and then make symbolic links to the
-libraries from /usr/lib
-
- # cd /usr/lib
- # ln -s /opt/pth/lib/libpth* .
-
-For building perl to support Oracle, it needs to be linked with libcl
-and libpthread. So even if your perl is an unthreaded build, these
-libraries might be required. See "Oracle on HP-UX" below.
-
-=head2 64-bit Perl on HP-UX
-
-Beginning with HP-UX 11.00, programs compiled under HP-UX can take
-advantage of the LP64 programming environment (LP64 means Longs and
-Pointers are 64 bits wide), in which scalar variables will be able
-to hold numbers larger than 2^32 with complete precision. Perl has
-proven to be consistent and reliable in 64bit mode since 5.8.1 on
-all HP-UX 11.xx.
-
-As of the date of this document, Perl is fully 64-bit compliant on
-HP-UX 11.00 and up for both cc- and gcc builds. If you are about to
-build a 64-bit perl with GNU gcc, please read the gcc section carefully.
-
-Should a user have the need for compiling Perl in the LP64 environment,
-use the -Duse64bitall flag to Configure. This will force Perl to be
-compiled in a pure LP64 environment (with the +DD64 flag for HP C-ANSI-C,
-with no additional options for GNU gcc 64-bit on PA-RISC, and with
--mlp64 for GNU gcc on Itanium).
-If you want to compile Perl using gcc, you will have to get a version of
-the compiler that supports 64-bit operations.)
-
-You can also use the -Duse64bitint flag to Configure. Although there
-are some minor differences between compiling Perl with this flag versus
-the -Duse64bitall flag, they should not be noticeable from a Perl user's
-perspective. When configuring -Duse64bitint using a 64bit gcc on a
-pa-risc architecture, -Duse64bitint is silently promoted to -Duse64bitall.
-
-In both cases, it is strongly recommended that you use these flags when
-you run Configure. If you do not use do this, but later answer the
-questions about 64-bit numbers when Configure asks you, you may get a
-configuration that cannot be compiled, or that does not function as
-expected.
-
-=head2 Oracle on HP-UX
-
-Using perl to connect to Oracle databases through DBI and DBD::Oracle
-has caused a lot of people many headaches. Read README.hpux in the
-DBD::Oracle for much more information. The reason to mention it here
-is that Oracle requires a perl built with libcl and libpthread, the
-latter even when perl is build without threads. Building perl using
-all defaults, but still enabling to build DBD::Oracle later on can be
-achieved using
-
- Configure -A prepend:libswanted='cl pthread ' ...
-
-Do not forget the space before the trailing quote.
-
-Also note that this does not (yet) work with all configurations,
-it is known to fail with 64-bit versions of GCC.
-
-=head2 GDBM and Threads on HP-UX
-
-If you attempt to compile Perl with (POSIX) threads on an 11.X system
-and also link in the GDBM library, then Perl will immediately core dump
-when it starts up. The only workaround at this point is to relink the
-GDBM library under 11.X, then relink it into Perl.
-
-the error might show something like:
-
-Pthread internal error: message: __libc_reinit() failed, file: ../pthreads/pthread.c, line: 1096
-Return Pointer is 0xc082bf33
-sh: 5345 Quit(coredump)
-
-and Configure will give up.
-
-=head2 NFS filesystems and utime(2) on HP-UX
-
-If you are compiling Perl on a remotely-mounted NFS filesystem, the test
-io/fs.t may fail on test #18. This appears to be a bug in HP-UX and no
-fix is currently available.
-
-=head2 HP-UX Kernel Parameters (maxdsiz) for Compiling Perl
-
-By default, HP-UX comes configured with a maximum data segment size of
-64MB. This is too small to correctly compile Perl with the maximum
-optimization levels. You can increase the size of the maxdsiz kernel
-parameter through the use of SAM.
-
-When using the GUI version of SAM, click on the Kernel Configuration
-icon, then the Configurable Parameters icon. Scroll down and select
-the maxdsiz line. From the Actions menu, select the Modify Configurable
-Parameter item. Insert the new formula into the Formula/Value box.
-Then follow the instructions to rebuild your kernel and reboot your
-system.
-
-In general, a value of 256MB (or "256*1024*1024") is sufficient for
-Perl to compile at maximum optimization.
-
-=head1 nss_delete core dump from op/pwent or op/grent
-
-You may get a bus error core dump from the op/pwent or op/grent
-tests. If compiled with -g you will see a stack trace much like
-the following:
-
- #0 0xc004216c in () from /usr/lib/libc.2
- #1 0xc00d7550 in __nss_src_state_destr () from /usr/lib/libc.2
- #2 0xc00d7768 in __nss_src_state_destr () from /usr/lib/libc.2
- #3 0xc00d78a8 in nss_delete () from /usr/lib/libc.2
- #4 0xc01126d8 in endpwent () from /usr/lib/libc.2
- #5 0xd1950 in Perl_pp_epwent () from ./perl
- #6 0x94d3c in Perl_runops_standard () from ./perl
- #7 0x23728 in S_run_body () from ./perl
- #8 0x23428 in perl_run () from ./perl
- #9 0x2005c in main () from ./perl
-
-The key here is the C<nss_delete> call. One workaround for this
-bug seems to be to create add to the file F</etc/nsswitch.conf>
-(at least) the following lines
-
- group: files
- passwd: files
-
-Whether you are using NIS does not matter. Amazingly enough,
-the same bug also affects Solaris.
-
-=head1 error: pasting ")" and "l" does not give a valid preprocessing token
-
-There seems to be a broken system header file in HP-UX 11.00 that
-breaks perl building in 32bit mode with GNU gcc-4.x causing this
-error. The same file for HP-UX 11.11 (even though the file is older)
-does not show this failure, and has the correct definition, so the
-best fix is to patch the header to match:
-
- --- /usr/include/inttypes.h 2001-04-20 18:42:14 +0200
- +++ /usr/include/inttypes.h 2000-11-14 09:00:00 +0200
- @@ -72,7 +72,7 @@
- #define UINT32_C(__c) __CONCAT_U__(__c)
- #else /* __LP64 */
- #define INT32_C(__c) __CONCAT__(__c,l)
- -#define UINT32_C(__c) __CONCAT__(__CONCAT_U__(__c),l)
- +#define UINT32_C(__c) __CONCAT__(__c,ul)
- #endif /* __LP64 */
-
- #define INT64_C(__c) __CONCAT_L__(__c,l)
-
-
-=head1 Miscellaneous
-
-HP-UX 11 Y2K patch "Y2K-1100 B.11.00.B0125 HP-UX Core OS Year 2000
-Patch Bundle" has been reported to break the io/fs test #18 which
-tests whether utime() can change timestamps. The Y2K patch seems to
-break utime() so that over NFS the timestamps do not get changed
-(on local filesystems utime() still works). This has probably been
-fixed on your system by now.
-
-=head1 AUTHOR
-
-H.Merijn Brand <h.m.brand@xs4all.nl>
-Jeff Okamoto <okamoto@corp.hp.com>
-
-With much assistance regarding shared libraries from Marc Sabatella.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlhurd.pod b/Master/tlpkg/tlperl/lib/pods/perlhurd.pod
deleted file mode 100644
index 7f9b4a98868..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlhurd.pod
+++ /dev/null
@@ -1,54 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you see.
-It is written in the POD format (see pod/perlpod.pod) which is specially
-designed to be readable as is.
-
-=head1 NAME
-
-perlhurd - Perl version 5 on Hurd
-
-=head1 DESCRIPTION
-
-If you want to use Perl on the Hurd, I recommend using the Debian
-GNU/Hurd distribution ( see http://www.debian.org/ ), even if an
-official, stable release has not yet been made. The old "gnu-0.2"
-binary distribution will most certainly have additional problems.
-
-=head2 Known Problems with Perl on Hurd
-
-The Perl test suite may still report some errors on the Hurd. The
-"lib/anydbm" and "pragma/warnings" tests will almost certainly fail.
-Both failures are not really specific to the Hurd, as indicated by the
-test suite output.
-
-The socket tests may fail if the network is not configured. You have
-to make "/hurd/pfinet" the translator for "/servers/socket/2", giving
-it the right arguments. Try "/hurd/pfinet --help" for more
-information.
-
-Here are the statistics for Perl 5.005_62 on my system:
-
- Failed Test Status Wstat Total Fail Failed List of failed
- -------------------------------------------------------------------------
- lib/anydbm.t 12 1 8.33% 12
- pragma/warnings 333 1 0.30% 215
-
- 8 tests and 24 subtests skipped.
- Failed 2/229 test scripts, 99.13% okay. 2/10850 subtests failed, 99.98% okay.
-
-There are quite a few systems out there that do worse!
-
-However, since I am running a very recent Hurd snapshot, in which a lot of
-bugs that were exposed by the Perl test suite have been fixed, you may
-encounter more failures. Likely candidates are: "op/stat", "lib/io_pipe",
-"lib/io_sock", "lib/io_udp" and "lib/time".
-
-In any way, if you're seeing failures beyond those mentioned in this
-document, please consider upgrading to the latest Hurd before reporting
-the failure as a bug.
-
-=head1 AUTHOR
-
-Mark Kettenis <kettenis@gnu.org>
-
-Last Updated: Fri, 29 Oct 1999 22:50:30 +0200
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlintern.pod b/Master/tlpkg/tlperl/lib/pods/perlintern.pod
deleted file mode 100644
index 3d7c86639ec..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlintern.pod
+++ /dev/null
@@ -1,2276 +0,0 @@
--*- buffer-read-only: t -*-
-
-!!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-This file is built by ..\autodoc.pl extracting documentation from the C source
-files.
-
-=head1 NAME
-
-perlintern - autogenerated documentation of purely B<internal>
- Perl functions
-
-=head1 DESCRIPTION
-X<internal Perl functions> X<interpreter functions>
-
-This file is the autogenerated documentation of functions in the
-Perl interpreter that are documented using Perl's internal documentation
-format but are not marked as part of the Perl API. In other words,
-B<they are not for use in extensions>!
-
-
-=head1 Compile-time scope hooks
-
-=over 8
-
-=item BhkENTRY
-X<BhkENTRY>
-
-Return an entry from the BHK structure. I<which> is a preprocessor token
-indicating which entry to return. If the appropriate flag is not set
-this will return NULL. The type of the return value depends on which
-entry you ask for.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void * BhkENTRY(BHK *hk, which)
-
-=for hackers
-Found in file op.h
-
-=item BhkFLAGS
-X<BhkFLAGS>
-
-Return the BHK's flags.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- U32 BhkFLAGS(BHK *hk)
-
-=for hackers
-Found in file op.h
-
-=item CALL_BLOCK_HOOKS
-X<CALL_BLOCK_HOOKS>
-
-Call all the registered block hooks for type I<which>. I<which> is a
-preprocessing token; the type of I<arg> depends on I<which>.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void CALL_BLOCK_HOOKS(which, arg)
-
-=for hackers
-Found in file op.h
-
-
-=back
-
-=head1 CV reference counts and CvOUTSIDE
-
-=over 8
-
-=item CvWEAKOUTSIDE
-X<CvWEAKOUTSIDE>
-
-Each CV has a pointer, C<CvOUTSIDE()>, to its lexically enclosing
-CV (if any). Because pointers to anonymous sub prototypes are
-stored in C<&> pad slots, it is a possible to get a circular reference,
-with the parent pointing to the child and vice-versa. To avoid the
-ensuing memory leak, we do not increment the reference count of the CV
-pointed to by C<CvOUTSIDE> in the I<one specific instance> that the parent
-has a C<&> pad slot pointing back to us. In this case, we set the
-C<CvWEAKOUTSIDE> flag in the child. This allows us to determine under what
-circumstances we should decrement the refcount of the parent when freeing
-the child.
-
-There is a further complication with non-closure anonymous subs (i.e. those
-that do not refer to any lexicals outside that sub). In this case, the
-anonymous prototype is shared rather than being cloned. This has the
-consequence that the parent may be freed while there are still active
-children, eg
-
- BEGIN { $a = sub { eval '$x' } }
-
-In this case, the BEGIN is freed immediately after execution since there
-are no active references to it: the anon sub prototype has
-C<CvWEAKOUTSIDE> set since it's not a closure, and $a points to the same
-CV, so it doesn't contribute to BEGIN's refcount either. When $a is
-executed, the C<eval '$x'> causes the chain of C<CvOUTSIDE>s to be followed,
-and the freed BEGIN is accessed.
-
-To avoid this, whenever a CV and its associated pad is freed, any
-C<&> entries in the pad are explicitly removed from the pad, and if the
-refcount of the pointed-to anon sub is still positive, then that
-child's C<CvOUTSIDE> is set to point to its grandparent. This will only
-occur in the single specific case of a non-closure anon prototype
-having one or more active references (such as C<$a> above).
-
-One other thing to consider is that a CV may be merely undefined
-rather than freed, eg C<undef &foo>. In this case, its refcount may
-not have reached zero, but we still delete its pad and its C<CvROOT> etc.
-Since various children may still have their C<CvOUTSIDE> pointing at this
-undefined CV, we keep its own C<CvOUTSIDE> for the time being, so that
-the chain of lexical scopes is unbroken. For example, the following
-should print 123:
-
- my $x = 123;
- sub tmp { sub { eval '$x' } }
- my $a = tmp();
- undef &tmp;
- print $a->();
-
- bool CvWEAKOUTSIDE(CV *cv)
-
-=for hackers
-Found in file cv.h
-
-
-=back
-
-=head1 Embedding Functions
-
-=over 8
-
-=item cv_dump
-X<cv_dump>
-
-dump the contents of a CV
-
- void cv_dump(CV *cv, const char *title)
-
-=for hackers
-Found in file pad.c
-
-=item do_dump_pad
-X<do_dump_pad>
-
-Dump the contents of a padlist
-
- void do_dump_pad(I32 level, PerlIO *file,
- PADLIST *padlist, int full)
-
-=for hackers
-Found in file pad.c
-
-=item intro_my
-X<intro_my>
-
-"Introduce" my variables to visible status.
-
- U32 intro_my()
-
-=for hackers
-Found in file pad.c
-
-=item padlist_dup
-X<padlist_dup>
-
-Duplicates a pad.
-
- AV * padlist_dup(AV *srcpad, CLONE_PARAMS *param)
-
-=for hackers
-Found in file pad.c
-
-=item pad_alloc_name
-X<pad_alloc_name>
-
-Allocates a place in the currently-compiling
-pad (via L<perlapi/pad_alloc>) and
-then stores a name for that entry. I<namesv> is adopted and becomes the
-name entry; it must already contain the name string and be sufficiently
-upgraded. I<typestash> and I<ourstash> and the C<padadd_STATE> flag get
-added to I<namesv>. None of the other
-processing of L<perlapi/pad_add_name_pvn>
-is done. Returns the offset of the allocated pad slot.
-
- PADOFFSET pad_alloc_name(SV *namesv, U32 flags,
- HV *typestash, HV *ourstash)
-
-=for hackers
-Found in file pad.c
-
-=item pad_block_start
-X<pad_block_start>
-
-Update the pad compilation state variables on entry to a new block
-
- void pad_block_start(int full)
-
-=for hackers
-Found in file pad.c
-
-=item pad_check_dup
-X<pad_check_dup>
-
-Check for duplicate declarations: report any of:
-
- * a my in the current scope with the same name;
- * an our (anywhere in the pad) with the same name and the
- same stash as C<ourstash>
-
-C<is_our> indicates that the name to check is an 'our' declaration.
-
- void pad_check_dup(SV *name, U32 flags,
- const HV *ourstash)
-
-=for hackers
-Found in file pad.c
-
-=item pad_findlex
-X<pad_findlex>
-
-Find a named lexical anywhere in a chain of nested pads. Add fake entries
-in the inner pads if it's found in an outer one.
-
-Returns the offset in the bottom pad of the lex or the fake lex.
-cv is the CV in which to start the search, and seq is the current cop_seq
-to match against. If warn is true, print appropriate warnings. The out_*
-vars return values, and so are pointers to where the returned values
-should be stored. out_capture, if non-null, requests that the innermost
-instance of the lexical is captured; out_name_sv is set to the innermost
-matched namesv or fake namesv; out_flags returns the flags normally
-associated with the IVX field of a fake namesv.
-
-Note that pad_findlex() is recursive; it recurses up the chain of CVs,
-then comes back down, adding fake entries as it goes. It has to be this way
-because fake namesvs in anon protoypes have to store in xlow the index into
-the parent pad.
-
- PADOFFSET pad_findlex(const char *namepv,
- STRLEN namelen, U32 flags,
- const CV* cv, U32 seq, int warn,
- SV** out_capture,
- SV** out_name_sv, int *out_flags)
-
-=for hackers
-Found in file pad.c
-
-=item pad_fixup_inner_anons
-X<pad_fixup_inner_anons>
-
-For any anon CVs in the pad, change CvOUTSIDE of that CV from
-old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be
-moved to a pre-existing CV struct.
-
- void pad_fixup_inner_anons(PADLIST *padlist,
- CV *old_cv, CV *new_cv)
-
-=for hackers
-Found in file pad.c
-
-=item pad_free
-X<pad_free>
-
-Free the SV at offset po in the current pad.
-
- void pad_free(PADOFFSET po)
-
-=for hackers
-Found in file pad.c
-
-=item pad_leavemy
-X<pad_leavemy>
-
-Cleanup at end of scope during compilation: set the max seq number for
-lexicals in this scope and warn of any lexicals that never got introduced.
-
- void pad_leavemy()
-
-=for hackers
-Found in file pad.c
-
-=item pad_push
-X<pad_push>
-
-Push a new pad frame onto the padlist, unless there's already a pad at
-this depth, in which case don't bother creating a new one. Then give
-the new pad an @_ in slot zero.
-
- void pad_push(PADLIST *padlist, int depth)
-
-=for hackers
-Found in file pad.c
-
-=item pad_reset
-X<pad_reset>
-
-Mark all the current temporaries for reuse
-
- void pad_reset()
-
-=for hackers
-Found in file pad.c
-
-=item pad_swipe
-X<pad_swipe>
-
-Abandon the tmp in the current pad at offset po and replace with a
-new one.
-
- void pad_swipe(PADOFFSET po, bool refadjust)
-
-=for hackers
-Found in file pad.c
-
-
-=back
-
-=head1 Functions in file op.c
-
-=over 8
-
-=item core_prototype
-X<core_prototype>
-
-This function assigns the prototype of the named core function to C<sv>, or
-to a new mortal SV if C<sv> is NULL. It returns the modified C<sv>, or
-NULL if the core function has no prototype. C<code> is a code as returned
-by C<keyword()>. It must be negative and unequal to -KEY_CORE.
-
- SV * core_prototype(SV *sv, const char *name,
- const int code,
- int * const opnum)
-
-=for hackers
-Found in file op.c
-
-
-=back
-
-=head1 Functions in file pp_ctl.c
-
-
-=over 8
-
-=item docatch
-X<docatch>
-
-Check for the cases 0 or 3 of cur_env.je_ret, only used inside an eval context.
-
-0 is used as continue inside eval,
-
-3 is used for a die caught by an inner eval - continue inner loop
-
-See cop.h: je_mustcatch, when set at any runlevel to TRUE, means eval ops must
-establish a local jmpenv to handle exception traps.
-
- OP* docatch(OP *o)
-
-=for hackers
-Found in file pp_ctl.c
-
-
-=back
-
-=head1 GV Functions
-
-=over 8
-
-=item gv_try_downgrade
-X<gv_try_downgrade>
-
-If the typeglob C<gv> can be expressed more succinctly, by having
-something other than a real GV in its place in the stash, replace it
-with the optimised form. Basic requirements for this are that C<gv>
-is a real typeglob, is sufficiently ordinary, and is only referenced
-from its package. This function is meant to be used when a GV has been
-looked up in part to see what was there, causing upgrading, but based
-on what was found it turns out that the real GV isn't required after all.
-
-If C<gv> is a completely empty typeglob, it is deleted from the stash.
-
-If C<gv> is a typeglob containing only a sufficiently-ordinary constant
-sub, the typeglob is replaced with a scalar-reference placeholder that
-more compactly represents the same thing.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void gv_try_downgrade(GV* gv)
-
-=for hackers
-Found in file gv.c
-
-
-=back
-
-=head1 Hash Manipulation Functions
-
-=over 8
-
-=item hv_ename_add
-X<hv_ename_add>
-
-Adds a name to a stash's internal list of effective names. See
-C<hv_ename_delete>.
-
-This is called when a stash is assigned to a new location in the symbol
-table.
-
- void hv_ename_add(HV *hv, const char *name, U32 len,
- U32 flags)
-
-=for hackers
-Found in file hv.c
-
-=item hv_ename_delete
-X<hv_ename_delete>
-
-Removes a name from a stash's internal list of effective names. If this is
-the name returned by C<HvENAME>, then another name in the list will take
-its place (C<HvENAME> will use it).
-
-This is called when a stash is deleted from the symbol table.
-
- void hv_ename_delete(HV *hv, const char *name,
- U32 len, U32 flags)
-
-=for hackers
-Found in file hv.c
-
-=item refcounted_he_chain_2hv
-X<refcounted_he_chain_2hv>
-
-Generates and returns a C<HV *> representing the content of a
-C<refcounted_he> chain.
-I<flags> is currently unused and must be zero.
-
- HV * refcounted_he_chain_2hv(
- const struct refcounted_he *c, U32 flags
- )
-
-=for hackers
-Found in file hv.c
-
-=item refcounted_he_fetch_pv
-X<refcounted_he_fetch_pv>
-
-Like L</refcounted_he_fetch_pvn>, but takes a nul-terminated string
-instead of a string/length pair.
-
- SV * refcounted_he_fetch_pv(
- const struct refcounted_he *chain,
- const char *key, U32 hash, U32 flags
- )
-
-=for hackers
-Found in file hv.c
-
-=item refcounted_he_fetch_pvn
-X<refcounted_he_fetch_pvn>
-
-Search along a C<refcounted_he> chain for an entry with the key specified
-by I<keypv> and I<keylen>. If I<flags> has the C<REFCOUNTED_HE_KEY_UTF8>
-bit set, the key octets are interpreted as UTF-8, otherwise they
-are interpreted as Latin-1. I<hash> is a precomputed hash of the key
-string, or zero if it has not been precomputed. Returns a mortal scalar
-representing the value associated with the key, or C<&PL_sv_placeholder>
-if there is no value associated with the key.
-
- SV * refcounted_he_fetch_pvn(
- const struct refcounted_he *chain,
- const char *keypv, STRLEN keylen, U32 hash,
- U32 flags
- )
-
-=for hackers
-Found in file hv.c
-
-=item refcounted_he_fetch_pvs
-X<refcounted_he_fetch_pvs>
-
-Like L</refcounted_he_fetch_pvn>, but takes a literal string instead of
-a string/length pair, and no precomputed hash.
-
- SV * refcounted_he_fetch_pvs(
- const struct refcounted_he *chain,
- const char *key, U32 flags
- )
-
-=for hackers
-Found in file hv.h
-
-=item refcounted_he_fetch_sv
-X<refcounted_he_fetch_sv>
-
-Like L</refcounted_he_fetch_pvn>, but takes a Perl scalar instead of a
-string/length pair.
-
- SV * refcounted_he_fetch_sv(
- const struct refcounted_he *chain, SV *key,
- U32 hash, U32 flags
- )
-
-=for hackers
-Found in file hv.c
-
-=item refcounted_he_free
-X<refcounted_he_free>
-
-Decrements the reference count of a C<refcounted_he> by one. If the
-reference count reaches zero the structure's memory is freed, which
-(recursively) causes a reduction of its parent C<refcounted_he>'s
-reference count. It is safe to pass a null pointer to this function:
-no action occurs in this case.
-
- void refcounted_he_free(struct refcounted_he *he)
-
-=for hackers
-Found in file hv.c
-
-=item refcounted_he_inc
-X<refcounted_he_inc>
-
-Increment the reference count of a C<refcounted_he>. The pointer to the
-C<refcounted_he> is also returned. It is safe to pass a null pointer
-to this function: no action occurs and a null pointer is returned.
-
- struct refcounted_he * refcounted_he_inc(
- struct refcounted_he *he
- )
-
-=for hackers
-Found in file hv.c
-
-=item refcounted_he_new_pv
-X<refcounted_he_new_pv>
-
-Like L</refcounted_he_new_pvn>, but takes a nul-terminated string instead
-of a string/length pair.
-
- struct refcounted_he * refcounted_he_new_pv(
- struct refcounted_he *parent,
- const char *key, U32 hash,
- SV *value, U32 flags
- )
-
-=for hackers
-Found in file hv.c
-
-=item refcounted_he_new_pvn
-X<refcounted_he_new_pvn>
-
-Creates a new C<refcounted_he>. This consists of a single key/value
-pair and a reference to an existing C<refcounted_he> chain (which may
-be empty), and thus forms a longer chain. When using the longer chain,
-the new key/value pair takes precedence over any entry for the same key
-further along the chain.
-
-The new key is specified by I<keypv> and I<keylen>. If I<flags> has
-the C<REFCOUNTED_HE_KEY_UTF8> bit set, the key octets are interpreted
-as UTF-8, otherwise they are interpreted as Latin-1. I<hash> is
-a precomputed hash of the key string, or zero if it has not been
-precomputed.
-
-I<value> is the scalar value to store for this key. I<value> is copied
-by this function, which thus does not take ownership of any reference
-to it, and later changes to the scalar will not be reflected in the
-value visible in the C<refcounted_he>. Complex types of scalar will not
-be stored with referential integrity, but will be coerced to strings.
-I<value> may be either null or C<&PL_sv_placeholder> to indicate that no
-value is to be associated with the key; this, as with any non-null value,
-takes precedence over the existence of a value for the key further along
-the chain.
-
-I<parent> points to the rest of the C<refcounted_he> chain to be
-attached to the new C<refcounted_he>. This function takes ownership
-of one reference to I<parent>, and returns one reference to the new
-C<refcounted_he>.
-
- struct refcounted_he * refcounted_he_new_pvn(
- struct refcounted_he *parent,
- const char *keypv,
- STRLEN keylen, U32 hash,
- SV *value, U32 flags
- )
-
-=for hackers
-Found in file hv.c
-
-=item refcounted_he_new_pvs
-X<refcounted_he_new_pvs>
-
-Like L</refcounted_he_new_pvn>, but takes a literal string instead of
-a string/length pair, and no precomputed hash.
-
- struct refcounted_he * refcounted_he_new_pvs(
- struct refcounted_he *parent,
- const char *key, SV *value,
- U32 flags
- )
-
-=for hackers
-Found in file hv.h
-
-=item refcounted_he_new_sv
-X<refcounted_he_new_sv>
-
-Like L</refcounted_he_new_pvn>, but takes a Perl scalar instead of a
-string/length pair.
-
- struct refcounted_he * refcounted_he_new_sv(
- struct refcounted_he *parent,
- SV *key, U32 hash, SV *value,
- U32 flags
- )
-
-=for hackers
-Found in file hv.c
-
-
-=back
-
-=head1 IO Functions
-
-=over 8
-
-=item start_glob
-X<start_glob>
-
-Function called by C<do_readline> to spawn a glob (or do the glob inside
-perl on VMS). This code used to be inline, but now perl uses C<File::Glob>
-this glob starter is only used by miniperl during the build process.
-Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- PerlIO* start_glob(SV *tmpglob, IO *io)
-
-=for hackers
-Found in file doio.c
-
-
-=back
-
-=head1 Magical Functions
-
-=over 8
-
-=item magic_clearhint
-X<magic_clearhint>
-
-Triggered by a delete from %^H, records the key to
-C<PL_compiling.cop_hints_hash>.
-
- int magic_clearhint(SV* sv, MAGIC* mg)
-
-=for hackers
-Found in file mg.c
-
-=item magic_clearhints
-X<magic_clearhints>
-
-Triggered by clearing %^H, resets C<PL_compiling.cop_hints_hash>.
-
- int magic_clearhints(SV* sv, MAGIC* mg)
-
-=for hackers
-Found in file mg.c
-
-=item magic_methcall
-X<magic_methcall>
-
-Invoke a magic method (like FETCH).
-
-C<sv> and C<mg> are the tied thingy and the tie magic.
-
-C<meth> is the name of the method to call.
-
-C<argc> is the number of args (in addition to $self) to pass to the method.
-
-The C<flags> can be:
-
- G_DISCARD invoke method with G_DISCARD flag and don't
- return a value
- G_UNDEF_FILL fill the stack with argc pointers to
- PL_sv_undef
-
-The arguments themselves are any values following the C<flags> argument.
-
-Returns the SV (if any) returned by the method, or NULL on failure.
-
-
- SV* magic_methcall(SV *sv, const MAGIC *mg,
- const char *meth, U32 flags,
- U32 argc, ...)
-
-=for hackers
-Found in file mg.c
-
-=item magic_sethint
-X<magic_sethint>
-
-Triggered by a store to %^H, records the key/value pair to
-C<PL_compiling.cop_hints_hash>. It is assumed that hints aren't storing
-anything that would need a deep copy. Maybe we should warn if we find a
-reference.
-
- int magic_sethint(SV* sv, MAGIC* mg)
-
-=for hackers
-Found in file mg.c
-
-=item mg_localize
-X<mg_localize>
-
-Copy some of the magic from an existing SV to new localized version of that
-SV. Container magic (eg %ENV, $1, tie) gets copied, value magic doesn't (eg
-taint, pos).
-
-If setmagic is false then no set magic will be called on the new (empty) SV.
-This typically means that assignment will soon follow (e.g. 'local $x = $y'),
-and that will handle the magic.
-
- void mg_localize(SV* sv, SV* nsv, bool setmagic)
-
-=for hackers
-Found in file mg.c
-
-
-=back
-
-=head1 MRO Functions
-
-=over 8
-
-=item mro_get_linear_isa_dfs
-X<mro_get_linear_isa_dfs>
-
-Returns the Depth-First Search linearization of @ISA
-the given stash. The return value is a read-only AV*.
-C<level> should be 0 (it is used internally in this
-function's recursion).
-
-You are responsible for C<SvREFCNT_inc()> on the
-return value if you plan to store it anywhere
-semi-permanently (otherwise it might be deleted
-out from under you the next time the cache is
-invalidated).
-
- AV* mro_get_linear_isa_dfs(HV* stash, U32 level)
-
-=for hackers
-Found in file mro.c
-
-=item mro_isa_changed_in
-X<mro_isa_changed_in>
-
-Takes the necessary steps (cache invalidations, mostly)
-when the @ISA of the given package has changed. Invoked
-by the C<setisa> magic, should not need to invoke directly.
-
- void mro_isa_changed_in(HV* stash)
-
-=for hackers
-Found in file mro.c
-
-=item mro_package_moved
-X<mro_package_moved>
-
-Call this function to signal to a stash that it has been assigned to
-another spot in the stash hierarchy. C<stash> is the stash that has been
-assigned. C<oldstash> is the stash it replaces, if any. C<gv> is the glob
-that is actually being assigned to.
-
-This can also be called with a null first argument to
-indicate that C<oldstash> has been deleted.
-
-This function invalidates isa caches on the old stash, on all subpackages
-nested inside it, and on the subclasses of all those, including
-non-existent packages that have corresponding entries in C<stash>.
-
-It also sets the effective names (C<HvENAME>) on all the stashes as
-appropriate.
-
-If the C<gv> is present and is not in the symbol table, then this function
-simply returns. This checked will be skipped if C<flags & 1>.
-
- void mro_package_moved(HV * const stash,
- HV * const oldstash,
- const GV * const gv,
- U32 flags)
-
-=for hackers
-Found in file mro.c
-
-
-=back
-
-=head1 Optree Manipulation Functions
-
-=over 8
-
-=item finalize_optree
-X<finalize_optree>
-
-This function finalizes the optree. Should be called directly after
-the complete optree is built. It does some additional
-checking which can't be done in the normal ck_xxx functions and makes
-the tree thread-safe.
-
- void finalize_optree(OP* o)
-
-=for hackers
-Found in file op.c
-
-
-=back
-
-=head1 Pad Data Structures
-
-=over 8
-
-=item CX_CURPAD_SAVE
-X<CX_CURPAD_SAVE>
-
-Save the current pad in the given context block structure.
-
- void CX_CURPAD_SAVE(struct context)
-
-=for hackers
-Found in file pad.h
-
-=item CX_CURPAD_SV
-X<CX_CURPAD_SV>
-
-Access the SV at offset po in the saved current pad in the given
-context block structure (can be used as an lvalue).
-
- SV * CX_CURPAD_SV(struct context, PADOFFSET po)
-
-=for hackers
-Found in file pad.h
-
-=item PAD_BASE_SV
-X<PAD_BASE_SV>
-
-Get the value from slot C<po> in the base (DEPTH=1) pad of a padlist
-
- SV * PAD_BASE_SV(PADLIST padlist, PADOFFSET po)
-
-=for hackers
-Found in file pad.h
-
-=item PAD_CLONE_VARS
-X<PAD_CLONE_VARS>
-
-Clone the state variables associated with running and compiling pads.
-
- void PAD_CLONE_VARS(PerlInterpreter *proto_perl,
- CLONE_PARAMS* param)
-
-=for hackers
-Found in file pad.h
-
-=item PAD_COMPNAME_FLAGS
-X<PAD_COMPNAME_FLAGS>
-
-Return the flags for the current compiling pad name
-at offset C<po>. Assumes a valid slot entry.
-
- U32 PAD_COMPNAME_FLAGS(PADOFFSET po)
-
-=for hackers
-Found in file pad.h
-
-=item PAD_COMPNAME_GEN
-X<PAD_COMPNAME_GEN>
-
-The generation number of the name at offset C<po> in the current
-compiling pad (lvalue). Note that C<SvUVX> is hijacked for this purpose.
-
- STRLEN PAD_COMPNAME_GEN(PADOFFSET po)
-
-=for hackers
-Found in file pad.h
-
-=item PAD_COMPNAME_GEN_set
-X<PAD_COMPNAME_GEN_set>
-
-Sets the generation number of the name at offset C<po> in the current
-ling pad (lvalue) to C<gen>. Note that C<SvUV_set> is hijacked for this purpose.
-
- STRLEN PAD_COMPNAME_GEN_set(PADOFFSET po, int gen)
-
-=for hackers
-Found in file pad.h
-
-=item PAD_COMPNAME_OURSTASH
-X<PAD_COMPNAME_OURSTASH>
-
-Return the stash associated with an C<our> variable.
-Assumes the slot entry is a valid C<our> lexical.
-
- HV * PAD_COMPNAME_OURSTASH(PADOFFSET po)
-
-=for hackers
-Found in file pad.h
-
-=item PAD_COMPNAME_PV
-X<PAD_COMPNAME_PV>
-
-Return the name of the current compiling pad name
-at offset C<po>. Assumes a valid slot entry.
-
- char * PAD_COMPNAME_PV(PADOFFSET po)
-
-=for hackers
-Found in file pad.h
-
-=item PAD_COMPNAME_TYPE
-X<PAD_COMPNAME_TYPE>
-
-Return the type (stash) of the current compiling pad name at offset
-C<po>. Must be a valid name. Returns null if not typed.
-
- HV * PAD_COMPNAME_TYPE(PADOFFSET po)
-
-=for hackers
-Found in file pad.h
-
-=item pad_peg
-X<pad_peg>
-
-When PERL_MAD is enabled, this is a small no-op function that gets called
-at the start of each pad-related function. It can be breakpointed to
-track all pad operations. The parameter is a string indicating the type
-of pad operation being performed.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void pad_peg(const char *s)
-
-=for hackers
-Found in file pad.c
-
-=item PAD_RESTORE_LOCAL
-X<PAD_RESTORE_LOCAL>
-
-Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL()
-
- void PAD_RESTORE_LOCAL(PAD *opad)
-
-=for hackers
-Found in file pad.h
-
-=item PAD_SAVE_LOCAL
-X<PAD_SAVE_LOCAL>
-
-Save the current pad to the local variable opad, then make the
-current pad equal to npad
-
- void PAD_SAVE_LOCAL(PAD *opad, PAD *npad)
-
-=for hackers
-Found in file pad.h
-
-=item PAD_SAVE_SETNULLPAD
-X<PAD_SAVE_SETNULLPAD>
-
-Save the current pad then set it to null.
-
- void PAD_SAVE_SETNULLPAD()
-
-=for hackers
-Found in file pad.h
-
-=item PAD_SETSV
-X<PAD_SETSV>
-
-Set the slot at offset C<po> in the current pad to C<sv>
-
- SV * PAD_SETSV(PADOFFSET po, SV* sv)
-
-=for hackers
-Found in file pad.h
-
-=item PAD_SET_CUR
-X<PAD_SET_CUR>
-
-Set the current pad to be pad C<n> in the padlist, saving
-the previous current pad. NB currently this macro expands to a string too
-long for some compilers, so it's best to replace it with
-
- SAVECOMPPAD();
- PAD_SET_CUR_NOSAVE(padlist,n);
-
-
- void PAD_SET_CUR(PADLIST padlist, I32 n)
-
-=for hackers
-Found in file pad.h
-
-=item PAD_SET_CUR_NOSAVE
-X<PAD_SET_CUR_NOSAVE>
-
-like PAD_SET_CUR, but without the save
-
- void PAD_SET_CUR_NOSAVE(PADLIST padlist, I32 n)
-
-=for hackers
-Found in file pad.h
-
-=item PAD_SV
-X<PAD_SV>
-
-Get the value at offset C<po> in the current pad
-
- void PAD_SV(PADOFFSET po)
-
-=for hackers
-Found in file pad.h
-
-=item PAD_SVl
-X<PAD_SVl>
-
-Lightweight and lvalue version of C<PAD_SV>.
-Get or set the value at offset C<po> in the current pad.
-Unlike C<PAD_SV>, does not print diagnostics with -DX.
-For internal use only.
-
- SV * PAD_SVl(PADOFFSET po)
-
-=for hackers
-Found in file pad.h
-
-=item SAVECLEARSV
-X<SAVECLEARSV>
-
-Clear the pointed to pad value on scope exit. (i.e. the runtime action of 'my')
-
- void SAVECLEARSV(SV **svp)
-
-=for hackers
-Found in file pad.h
-
-=item SAVECOMPPAD
-X<SAVECOMPPAD>
-
-save PL_comppad and PL_curpad
-
-
-
-
-
- void SAVECOMPPAD()
-
-=for hackers
-Found in file pad.h
-
-=item SAVEPADSV
-X<SAVEPADSV>
-
-Save a pad slot (used to restore after an iteration)
-
-XXX DAPM it would make more sense to make the arg a PADOFFSET
- void SAVEPADSV(PADOFFSET po)
-
-=for hackers
-Found in file pad.h
-
-
-=back
-
-=head1 Per-Interpreter Variables
-
-=over 8
-
-=item PL_DBsingle
-X<PL_DBsingle>
-
-When Perl is run in debugging mode, with the B<-d> switch, this SV is a
-boolean which indicates whether subs are being single-stepped.
-Single-stepping is automatically turned on after every step. This is the C
-variable which corresponds to Perl's $DB::single variable. See
-C<PL_DBsub>.
-
- SV * PL_DBsingle
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_DBsub
-X<PL_DBsub>
-
-When Perl is run in debugging mode, with the B<-d> switch, this GV contains
-the SV which holds the name of the sub being debugged. This is the C
-variable which corresponds to Perl's $DB::sub variable. See
-C<PL_DBsingle>.
-
- GV * PL_DBsub
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_DBtrace
-X<PL_DBtrace>
-
-Trace variable used when Perl is run in debugging mode, with the B<-d>
-switch. This is the C variable which corresponds to Perl's $DB::trace
-variable. See C<PL_DBsingle>.
-
- SV * PL_DBtrace
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_dowarn
-X<PL_dowarn>
-
-The C variable which corresponds to Perl's $^W warning variable.
-
- bool PL_dowarn
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_last_in_gv
-X<PL_last_in_gv>
-
-The GV which was last used for a filehandle input operation. (C<< <FH> >>)
-
- GV* PL_last_in_gv
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_ofsgv
-X<PL_ofsgv>
-
-The glob containing the output field separator - C<*,> in Perl space.
-
- GV* PL_ofsgv
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_rs
-X<PL_rs>
-
-The input record separator - C<$/> in Perl space.
-
- SV* PL_rs
-
-=for hackers
-Found in file intrpvar.h
-
-
-=back
-
-=head1 Stack Manipulation Macros
-
-=over 8
-
-=item djSP
-X<djSP>
-
-Declare Just C<SP>. This is actually identical to C<dSP>, and declares
-a local copy of perl's stack pointer, available via the C<SP> macro.
-See C<SP>. (Available for backward source code compatibility with the
-old (Perl 5.005) thread model.)
-
- djSP;
-
-=for hackers
-Found in file pp.h
-
-=item LVRET
-X<LVRET>
-
-True if this op will be the return value of an lvalue subroutine
-
-=for hackers
-Found in file pp.h
-
-
-=back
-
-=head1 SV Manipulation Functions
-
-=over 8
-
-=item sv_add_arena
-X<sv_add_arena>
-
-Given a chunk of memory, link it to the head of the list of arenas,
-and split it into a list of free SVs.
-
- void sv_add_arena(char *const ptr, const U32 size,
- const U32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_clean_all
-X<sv_clean_all>
-
-Decrement the refcnt of each remaining SV, possibly triggering a
-cleanup. This function may have to be called multiple times to free
-SVs which are in complex self-referential hierarchies.
-
- I32 sv_clean_all()
-
-=for hackers
-Found in file sv.c
-
-=item sv_clean_objs
-X<sv_clean_objs>
-
-Attempt to destroy all objects not yet freed.
-
- void sv_clean_objs()
-
-=for hackers
-Found in file sv.c
-
-=item sv_free_arenas
-X<sv_free_arenas>
-
-Deallocate the memory used by all arenas. Note that all the individual SV
-heads and bodies within the arenas must already have been freed.
-
- void sv_free_arenas()
-
-=for hackers
-Found in file sv.c
-
-
-=back
-
-=head1 SV-Body Allocation
-
-=over 8
-
-=item sv_2num
-X<sv_2num>
-
-Return an SV with the numeric value of the source SV, doing any necessary
-reference or overload conversion. You must use the C<SvNUM(sv)> macro to
-access this function.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- SV* sv_2num(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_ref
-X<sv_ref>
-
-Returns a SV describing what the SV passed in is a reference to.
-
- SV* sv_ref(SV *dst, const SV *const sv,
- const int ob)
-
-=for hackers
-Found in file sv.c
-
-
-=back
-
-=head1 Unicode Support
-
-=over 8
-
-=item find_uninit_var
-X<find_uninit_var>
-
-Find the name of the undefined variable (if any) that caused the operator
-to issue a "Use of uninitialized value" warning.
-If match is true, only return a name if its value matches uninit_sv.
-So roughly speaking, if a unary operator (such as OP_COS) generates a
-warning, then following the direct child of the op may yield an
-OP_PADSV or OP_GV that gives the name of the undefined variable. On the
-other hand, with OP_ADD there are two branches to follow, so we only print
-the variable name if we get an exact match.
-
-The name is returned as a mortal SV.
-
-Assumes that PL_op is the op that originally triggered the error, and that
-PL_comppad/PL_curpad points to the currently executing pad.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- SV* find_uninit_var(const OP *const obase,
- const SV *const uninit_sv,
- bool top)
-
-=for hackers
-Found in file sv.c
-
-=item report_uninit
-X<report_uninit>
-
-Print appropriate "Use of uninitialized variable" warning.
-
- void report_uninit(const SV *uninit_sv)
-
-=for hackers
-Found in file sv.c
-
-
-=back
-
-=head1 Undocumented functions
-
-The following functions are currently undocumented. If you use one of
-them, you may wish to consider creating and submitting documentation for
-it.
-
-=over
-
-=item _add_range_to_invlist
-X<_add_range_to_invlist>
-
-=item _core_swash_init
-X<_core_swash_init>
-
-=item _invlist_array_init
-X<_invlist_array_init>
-
-=item _invlist_contents
-X<_invlist_contents>
-
-=item _invlist_intersection
-X<_invlist_intersection>
-
-=item _invlist_intersection_maybe_complement_2nd
-X<_invlist_intersection_maybe_complement_2nd>
-
-=item _invlist_invert
-X<_invlist_invert>
-
-=item _invlist_invert_prop
-X<_invlist_invert_prop>
-
-=item _invlist_populate_swatch
-X<_invlist_populate_swatch>
-
-=item _invlist_subtract
-X<_invlist_subtract>
-
-=item _invlist_union
-X<_invlist_union>
-
-=item _invlist_union_maybe_complement_2nd
-X<_invlist_union_maybe_complement_2nd>
-
-=item _is_utf8__perl_idstart
-X<_is_utf8__perl_idstart>
-
-=item _new_invlist
-X<_new_invlist>
-
-=item _swash_inversion_hash
-X<_swash_inversion_hash>
-
-=item _swash_to_invlist
-X<_swash_to_invlist>
-
-=item _to_fold_latin1
-X<_to_fold_latin1>
-
-=item _to_upper_title_latin1
-X<_to_upper_title_latin1>
-
-=item aassign_common_vars
-X<aassign_common_vars>
-
-=item add_cp_to_invlist
-X<add_cp_to_invlist>
-
-=item addmad
-X<addmad>
-
-=item allocmy
-X<allocmy>
-
-=item amagic_is_enabled
-X<amagic_is_enabled>
-
-=item append_madprops
-X<append_madprops>
-
-=item apply
-X<apply>
-
-=item av_reify
-X<av_reify>
-
-=item bind_match
-X<bind_match>
-
-=item block_end
-X<block_end>
-
-=item block_start
-X<block_start>
-
-=item boot_core_PerlIO
-X<boot_core_PerlIO>
-
-=item boot_core_UNIVERSAL
-X<boot_core_UNIVERSAL>
-
-=item boot_core_mro
-X<boot_core_mro>
-
-=item cando
-X<cando>
-
-=item check_utf8_print
-X<check_utf8_print>
-
-=item ck_entersub_args_core
-X<ck_entersub_args_core>
-
-=item convert
-X<convert>
-
-=item coresub_op
-X<coresub_op>
-
-=item create_eval_scope
-X<create_eval_scope>
-
-=item cv_ckproto_len_flags
-X<cv_ckproto_len_flags>
-
-=item cvgv_set
-X<cvgv_set>
-
-=item cvstash_set
-X<cvstash_set>
-
-=item deb_stack_all
-X<deb_stack_all>
-
-=item delete_eval_scope
-X<delete_eval_scope>
-
-=item die_unwind
-X<die_unwind>
-
-=item do_aexec
-X<do_aexec>
-
-=item do_aexec5
-X<do_aexec5>
-
-=item do_eof
-X<do_eof>
-
-=item do_exec
-X<do_exec>
-
-=item do_exec3
-X<do_exec3>
-
-=item do_execfree
-X<do_execfree>
-
-=item do_ipcctl
-X<do_ipcctl>
-
-=item do_ipcget
-X<do_ipcget>
-
-=item do_msgrcv
-X<do_msgrcv>
-
-=item do_msgsnd
-X<do_msgsnd>
-
-=item do_ncmp
-X<do_ncmp>
-
-=item do_op_xmldump
-X<do_op_xmldump>
-
-=item do_pmop_xmldump
-X<do_pmop_xmldump>
-
-=item do_print
-X<do_print>
-
-=item do_readline
-X<do_readline>
-
-=item do_seek
-X<do_seek>
-
-=item do_semop
-X<do_semop>
-
-=item do_shmio
-X<do_shmio>
-
-=item do_sysseek
-X<do_sysseek>
-
-=item do_tell
-X<do_tell>
-
-=item do_trans
-X<do_trans>
-
-=item do_vecget
-X<do_vecget>
-
-=item do_vecset
-X<do_vecset>
-
-=item do_vop
-X<do_vop>
-
-=item dofile
-X<dofile>
-
-=item dump_all_perl
-X<dump_all_perl>
-
-=item dump_packsubs_perl
-X<dump_packsubs_perl>
-
-=item dump_sub_perl
-X<dump_sub_perl>
-
-=item dump_sv_child
-X<dump_sv_child>
-
-=item emulate_cop_io
-X<emulate_cop_io>
-
-=item feature_is_enabled
-X<feature_is_enabled>
-
-=item find_rundefsv2
-X<find_rundefsv2>
-
-=item find_script
-X<find_script>
-
-=item free_tied_hv_pool
-X<free_tied_hv_pool>
-
-=item get_db_sub
-X<get_db_sub>
-
-=item get_debug_opts
-X<get_debug_opts>
-
-=item get_hash_seed
-X<get_hash_seed>
-
-=item get_invlist_iter_addr
-X<get_invlist_iter_addr>
-
-=item get_invlist_len_addr
-X<get_invlist_len_addr>
-
-=item get_invlist_version_id_addr
-X<get_invlist_version_id_addr>
-
-=item get_invlist_zero_addr
-X<get_invlist_zero_addr>
-
-=item get_no_modify
-X<get_no_modify>
-
-=item get_opargs
-X<get_opargs>
-
-=item get_re_arg
-X<get_re_arg>
-
-=item getenv_len
-X<getenv_len>
-
-=item hfree_next_entry
-X<hfree_next_entry>
-
-=item hv_backreferences_p
-X<hv_backreferences_p>
-
-=item hv_kill_backrefs
-X<hv_kill_backrefs>
-
-=item hv_undef_flags
-X<hv_undef_flags>
-
-=item init_argv_symbols
-X<init_argv_symbols>
-
-=item init_dbargs
-X<init_dbargs>
-
-=item init_debugger
-X<init_debugger>
-
-=item invert
-X<invert>
-
-=item invlist_array
-X<invlist_array>
-
-=item invlist_clone
-X<invlist_clone>
-
-=item invlist_iterinit
-X<invlist_iterinit>
-
-=item invlist_len
-X<invlist_len>
-
-=item invlist_max
-X<invlist_max>
-
-=item invlist_set_len
-X<invlist_set_len>
-
-=item invlist_trim
-X<invlist_trim>
-
-=item io_close
-X<io_close>
-
-=item is_utf8_X_L
-X<is_utf8_X_L>
-
-=item is_utf8_X_LV
-X<is_utf8_X_LV>
-
-=item is_utf8_X_LVT
-X<is_utf8_X_LVT>
-
-=item is_utf8_X_LV_LVT_V
-X<is_utf8_X_LV_LVT_V>
-
-=item is_utf8_X_T
-X<is_utf8_X_T>
-
-=item is_utf8_X_V
-X<is_utf8_X_V>
-
-=item is_utf8_X_begin
-X<is_utf8_X_begin>
-
-=item is_utf8_X_extend
-X<is_utf8_X_extend>
-
-=item is_utf8_X_non_hangul
-X<is_utf8_X_non_hangul>
-
-=item is_utf8_X_prepend
-X<is_utf8_X_prepend>
-
-=item jmaybe
-X<jmaybe>
-
-=item keyword
-X<keyword>
-
-=item keyword_plugin_standard
-X<keyword_plugin_standard>
-
-=item list
-X<list>
-
-=item localize
-X<localize>
-
-=item mad_free
-X<mad_free>
-
-=item madlex
-X<madlex>
-
-=item madparse
-X<madparse>
-
-=item magic_clear_all_env
-X<magic_clear_all_env>
-
-=item magic_clearenv
-X<magic_clearenv>
-
-=item magic_clearisa
-X<magic_clearisa>
-
-=item magic_clearpack
-X<magic_clearpack>
-
-=item magic_clearsig
-X<magic_clearsig>
-
-=item magic_existspack
-X<magic_existspack>
-
-=item magic_freearylen_p
-X<magic_freearylen_p>
-
-=item magic_freeovrld
-X<magic_freeovrld>
-
-=item magic_get
-X<magic_get>
-
-=item magic_getarylen
-X<magic_getarylen>
-
-=item magic_getdefelem
-X<magic_getdefelem>
-
-=item magic_getnkeys
-X<magic_getnkeys>
-
-=item magic_getpack
-X<magic_getpack>
-
-=item magic_getpos
-X<magic_getpos>
-
-=item magic_getsig
-X<magic_getsig>
-
-=item magic_getsubstr
-X<magic_getsubstr>
-
-=item magic_gettaint
-X<magic_gettaint>
-
-=item magic_getuvar
-X<magic_getuvar>
-
-=item magic_getvec
-X<magic_getvec>
-
-=item magic_killbackrefs
-X<magic_killbackrefs>
-
-=item magic_len
-X<magic_len>
-
-=item magic_nextpack
-X<magic_nextpack>
-
-=item magic_regdata_cnt
-X<magic_regdata_cnt>
-
-=item magic_regdatum_get
-X<magic_regdatum_get>
-
-=item magic_regdatum_set
-X<magic_regdatum_set>
-
-=item magic_scalarpack
-X<magic_scalarpack>
-
-=item magic_set
-X<magic_set>
-
-=item magic_set_all_env
-X<magic_set_all_env>
-
-=item magic_setamagic
-X<magic_setamagic>
-
-=item magic_setarylen
-X<magic_setarylen>
-
-=item magic_setcollxfrm
-X<magic_setcollxfrm>
-
-=item magic_setdbline
-X<magic_setdbline>
-
-=item magic_setdefelem
-X<magic_setdefelem>
-
-=item magic_setenv
-X<magic_setenv>
-
-=item magic_setisa
-X<magic_setisa>
-
-=item magic_setmglob
-X<magic_setmglob>
-
-=item magic_setnkeys
-X<magic_setnkeys>
-
-=item magic_setpack
-X<magic_setpack>
-
-=item magic_setpos
-X<magic_setpos>
-
-=item magic_setregexp
-X<magic_setregexp>
-
-=item magic_setsig
-X<magic_setsig>
-
-=item magic_setsubstr
-X<magic_setsubstr>
-
-=item magic_settaint
-X<magic_settaint>
-
-=item magic_setutf8
-X<magic_setutf8>
-
-=item magic_setuvar
-X<magic_setuvar>
-
-=item magic_setvec
-X<magic_setvec>
-
-=item magic_setvstring
-X<magic_setvstring>
-
-=item magic_sizepack
-X<magic_sizepack>
-
-=item magic_wipepack
-X<magic_wipepack>
-
-=item malloc_good_size
-X<malloc_good_size>
-
-=item malloced_size
-X<malloced_size>
-
-=item mem_collxfrm
-X<mem_collxfrm>
-
-=item mode_from_discipline
-X<mode_from_discipline>
-
-=item more_bodies
-X<more_bodies>
-
-=item mro_meta_dup
-X<mro_meta_dup>
-
-=item mro_meta_init
-X<mro_meta_init>
-
-=item munge_qwlist_to_paren_list
-X<munge_qwlist_to_paren_list>
-
-=item my_attrs
-X<my_attrs>
-
-=item my_betoh16
-X<my_betoh16>
-
-=item my_betoh32
-X<my_betoh32>
-
-=item my_betoh64
-X<my_betoh64>
-
-=item my_betohi
-X<my_betohi>
-
-=item my_betohl
-X<my_betohl>
-
-=item my_betohs
-X<my_betohs>
-
-=item my_clearenv
-X<my_clearenv>
-
-=item my_htobe16
-X<my_htobe16>
-
-=item my_htobe32
-X<my_htobe32>
-
-=item my_htobe64
-X<my_htobe64>
-
-=item my_htobei
-X<my_htobei>
-
-=item my_htobel
-X<my_htobel>
-
-=item my_htobes
-X<my_htobes>
-
-=item my_htole16
-X<my_htole16>
-
-=item my_htole32
-X<my_htole32>
-
-=item my_htole64
-X<my_htole64>
-
-=item my_htolei
-X<my_htolei>
-
-=item my_htolel
-X<my_htolel>
-
-=item my_htoles
-X<my_htoles>
-
-=item my_letoh16
-X<my_letoh16>
-
-=item my_letoh32
-X<my_letoh32>
-
-=item my_letoh64
-X<my_letoh64>
-
-=item my_letohi
-X<my_letohi>
-
-=item my_letohl
-X<my_letohl>
-
-=item my_letohs
-X<my_letohs>
-
-=item my_lstat_flags
-X<my_lstat_flags>
-
-=item my_stat_flags
-X<my_stat_flags>
-
-=item my_swabn
-X<my_swabn>
-
-=item my_unexec
-X<my_unexec>
-
-=item newATTRSUB_flags
-X<newATTRSUB_flags>
-
-=item newGP
-X<newGP>
-
-=item newMADPROP
-X<newMADPROP>
-
-=item newMADsv
-X<newMADsv>
-
-=item newTOKEN
-X<newTOKEN>
-
-=item newXS_len_flags
-X<newXS_len_flags>
-
-=item new_warnings_bitfield
-X<new_warnings_bitfield>
-
-=item nextargv
-X<nextargv>
-
-=item oopsAV
-X<oopsAV>
-
-=item oopsHV
-X<oopsHV>
-
-=item op_clear
-X<op_clear>
-
-=item op_const_sv
-X<op_const_sv>
-
-=item op_getmad
-X<op_getmad>
-
-=item op_getmad_weak
-X<op_getmad_weak>
-
-=item op_integerize
-X<op_integerize>
-
-=item op_lvalue_flags
-X<op_lvalue_flags>
-
-=item op_refcnt_dec
-X<op_refcnt_dec>
-
-=item op_refcnt_inc
-X<op_refcnt_inc>
-
-=item op_std_init
-X<op_std_init>
-
-=item op_xmldump
-X<op_xmldump>
-
-=item package
-X<package>
-
-=item package_version
-X<package_version>
-
-=item parse_unicode_opts
-X<parse_unicode_opts>
-
-=item parser_free
-X<parser_free>
-
-=item peep
-X<peep>
-
-=item pending_Slabs_to_ro
-X<pending_Slabs_to_ro>
-
-=item pmop_xmldump
-X<pmop_xmldump>
-
-=item pmruntime
-X<pmruntime>
-
-=item populate_isa
-X<populate_isa>
-
-=item prepend_madprops
-X<prepend_madprops>
-
-=item qerror
-X<qerror>
-
-=item reg_named_buff
-X<reg_named_buff>
-
-=item reg_named_buff_iter
-X<reg_named_buff_iter>
-
-=item reg_numbered_buff_fetch
-X<reg_numbered_buff_fetch>
-
-=item reg_numbered_buff_length
-X<reg_numbered_buff_length>
-
-=item reg_numbered_buff_store
-X<reg_numbered_buff_store>
-
-=item reg_qr_package
-X<reg_qr_package>
-
-=item reg_temp_copy
-X<reg_temp_copy>
-
-=item regcurly
-X<regcurly>
-
-=item regprop
-X<regprop>
-
-=item report_evil_fh
-X<report_evil_fh>
-
-=item report_redefined_cv
-X<report_redefined_cv>
-
-=item report_wrongway_fh
-X<report_wrongway_fh>
-
-=item rpeep
-X<rpeep>
-
-=item rsignal_restore
-X<rsignal_restore>
-
-=item rsignal_save
-X<rsignal_save>
-
-=item rxres_save
-X<rxres_save>
-
-=item same_dirent
-X<same_dirent>
-
-=item sawparens
-X<sawparens>
-
-=item scalar
-X<scalar>
-
-=item scalarvoid
-X<scalarvoid>
-
-=item set_regclass_bit
-X<set_regclass_bit>
-
-=item sighandler
-X<sighandler>
-
-=item softref2xv
-X<softref2xv>
-
-=item sub_crush_depth
-X<sub_crush_depth>
-
-=item sv_add_backref
-X<sv_add_backref>
-
-=item sv_catxmlpv
-X<sv_catxmlpv>
-
-=item sv_catxmlpvn
-X<sv_catxmlpvn>
-
-=item sv_catxmlsv
-X<sv_catxmlsv>
-
-=item sv_compile_2op_is_broken
-X<sv_compile_2op_is_broken>
-
-=item sv_del_backref
-X<sv_del_backref>
-
-=item sv_free2
-X<sv_free2>
-
-=item sv_kill_backrefs
-X<sv_kill_backrefs>
-
-=item sv_sethek
-X<sv_sethek>
-
-=item sv_setsv_cow
-X<sv_setsv_cow>
-
-=item sv_unglob
-X<sv_unglob>
-
-=item sv_xmlpeek
-X<sv_xmlpeek>
-
-=item tied_method
-X<tied_method>
-
-=item token_free
-X<token_free>
-
-=item token_getmad
-X<token_getmad>
-
-=item translate_substr_offsets
-X<translate_substr_offsets>
-
-=item try_amagic_bin
-X<try_amagic_bin>
-
-=item try_amagic_un
-X<try_amagic_un>
-
-=item unshare_hek
-X<unshare_hek>
-
-=item utilize
-X<utilize>
-
-=item varname
-X<varname>
-
-=item vivify_defelem
-X<vivify_defelem>
-
-=item vivify_ref
-X<vivify_ref>
-
-=item wait4pid
-X<wait4pid>
-
-=item was_lvalue_sub
-X<was_lvalue_sub>
-
-=item watch
-X<watch>
-
-=item write_to_stderr
-X<write_to_stderr>
-
-=item xmldump_all
-X<xmldump_all>
-
-=item xmldump_all_perl
-X<xmldump_all_perl>
-
-=item xmldump_eval
-X<xmldump_eval>
-
-=item xmldump_form
-X<xmldump_form>
-
-=item xmldump_indent
-X<xmldump_indent>
-
-=item xmldump_packsubs
-X<xmldump_packsubs>
-
-=item xmldump_packsubs_perl
-X<xmldump_packsubs_perl>
-
-=item xmldump_sub
-X<xmldump_sub>
-
-=item xmldump_sub_perl
-X<xmldump_sub_perl>
-
-=item xmldump_vindent
-X<xmldump_vindent>
-
-=item xs_apiversion_bootcheck
-X<xs_apiversion_bootcheck>
-
-=item xs_version_bootcheck
-X<xs_version_bootcheck>
-
-=item yyerror
-X<yyerror>
-
-=item yyerror_pv
-X<yyerror_pv>
-
-=item yyerror_pvn
-X<yyerror_pvn>
-
-=item yylex
-X<yylex>
-
-=item yyparse
-X<yyparse>
-
-=item yyunlex
-X<yyunlex>
-
-=back
-
-
-=head1 AUTHORS
-
-The autodocumentation system was originally added to the Perl core by
-Benjamin Stuhl. Documentation is by whoever was kind enough to
-document their functions.
-
-=head1 SEE ALSO
-
-L<perlguts>, L<perlapi>
-
-=cut
-
- ex: set ro:
diff --git a/Master/tlpkg/tlperl/lib/pods/perlinterp.pod b/Master/tlpkg/tlperl/lib/pods/perlinterp.pod
deleted file mode 100644
index c7f21209de5..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlinterp.pod
+++ /dev/null
@@ -1,742 +0,0 @@
-=encoding utf8
-
-=for comment
-Consistent formatting of this file is achieved with:
- perl ./Porting/podtidy pod/perlinterp.pod
-
-=head1 NAME
-
-perlinterp - An overview of the Perl interpreter
-
-=head1 DESCRIPTION
-
-This document provides an overview of how the Perl interpreter works at
-the level of C code, along with pointers to the relevant C source code
-files.
-
-=head1 ELEMENTS OF THE INTERPRETER
-
-The work of the interpreter has two main stages: compiling the code
-into the internal representation, or bytecode, and then executing it.
-L<perlguts/Compiled code> explains exactly how the compilation stage
-happens.
-
-Here is a short breakdown of perl's operation:
-
-=head2 Startup
-
-The action begins in F<perlmain.c>. (or F<miniperlmain.c> for miniperl)
-This is very high-level code, enough to fit on a single screen, and it
-resembles the code found in L<perlembed>; most of the real action takes
-place in F<perl.c>
-
-F<perlmain.c> is generated by C<ExtUtils::Miniperl> from
-F<miniperlmain.c> at make time, so you should make perl to follow this
-along.
-
-First, F<perlmain.c> allocates some memory and constructs a Perl
-interpreter, along these lines:
-
- 1 PERL_SYS_INIT3(&argc,&argv,&env);
- 2
- 3 if (!PL_do_undump) {
- 4 my_perl = perl_alloc();
- 5 if (!my_perl)
- 6 exit(1);
- 7 perl_construct(my_perl);
- 8 PL_perl_destruct_level = 0;
- 9 }
-
-Line 1 is a macro, and its definition is dependent on your operating
-system. Line 3 references C<PL_do_undump>, a global variable - all
-global variables in Perl start with C<PL_>. This tells you whether the
-current running program was created with the C<-u> flag to perl and
-then F<undump>, which means it's going to be false in any sane context.
-
-Line 4 calls a function in F<perl.c> to allocate memory for a Perl
-interpreter. It's quite a simple function, and the guts of it looks
-like this:
-
- my_perl = (PerlInterpreter*)PerlMem_malloc(sizeof(PerlInterpreter));
-
-Here you see an example of Perl's system abstraction, which we'll see
-later: C<PerlMem_malloc> is either your system's C<malloc>, or Perl's
-own C<malloc> as defined in F<malloc.c> if you selected that option at
-configure time.
-
-Next, in line 7, we construct the interpreter using perl_construct,
-also in F<perl.c>; this sets up all the special variables that Perl
-needs, the stacks, and so on.
-
-Now we pass Perl the command line options, and tell it to go:
-
- exitstatus = perl_parse(my_perl, xs_init, argc, argv, (char **)NULL);
- if (!exitstatus)
- perl_run(my_perl);
-
- exitstatus = perl_destruct(my_perl);
-
- perl_free(my_perl);
-
-C<perl_parse> is actually a wrapper around C<S_parse_body>, as defined
-in F<perl.c>, which processes the command line options, sets up any
-statically linked XS modules, opens the program and calls C<yyparse> to
-parse it.
-
-=head2 Parsing
-
-The aim of this stage is to take the Perl source, and turn it into an
-op tree. We'll see what one of those looks like later. Strictly
-speaking, there's three things going on here.
-
-C<yyparse>, the parser, lives in F<perly.c>, although you're better off
-reading the original YACC input in F<perly.y>. (Yes, Virginia, there
-B<is> a YACC grammar for Perl!) The job of the parser is to take your
-code and "understand" it, splitting it into sentences, deciding which
-operands go with which operators and so on.
-
-The parser is nobly assisted by the lexer, which chunks up your input
-into tokens, and decides what type of thing each token is: a variable
-name, an operator, a bareword, a subroutine, a core function, and so
-on. The main point of entry to the lexer is C<yylex>, and that and its
-associated routines can be found in F<toke.c>. Perl isn't much like
-other computer languages; it's highly context sensitive at times, it
-can be tricky to work out what sort of token something is, or where a
-token ends. As such, there's a lot of interplay between the tokeniser
-and the parser, which can get pretty frightening if you're not used to
-it.
-
-As the parser understands a Perl program, it builds up a tree of
-operations for the interpreter to perform during execution. The
-routines which construct and link together the various operations are
-to be found in F<op.c>, and will be examined later.
-
-=head2 Optimization
-
-Now the parsing stage is complete, and the finished tree represents the
-operations that the Perl interpreter needs to perform to execute our
-program. Next, Perl does a dry run over the tree looking for
-optimisations: constant expressions such as C<3 + 4> will be computed
-now, and the optimizer will also see if any multiple operations can be
-replaced with a single one. For instance, to fetch the variable
-C<$foo>, instead of grabbing the glob C<*foo> and looking at the scalar
-component, the optimizer fiddles the op tree to use a function which
-directly looks up the scalar in question. The main optimizer is C<peep>
-in F<op.c>, and many ops have their own optimizing functions.
-
-=head2 Running
-
-Now we're finally ready to go: we have compiled Perl byte code, and all
-that's left to do is run it. The actual execution is done by the
-C<runops_standard> function in F<run.c>; more specifically, it's done
-by these three innocent looking lines:
-
- while ((PL_op = PL_op->op_ppaddr(aTHX))) {
- PERL_ASYNC_CHECK();
- }
-
-You may be more comfortable with the Perl version of that:
-
- PERL_ASYNC_CHECK() while $Perl::op = &{$Perl::op->{function}};
-
-Well, maybe not. Anyway, each op contains a function pointer, which
-stipulates the function which will actually carry out the operation.
-This function will return the next op in the sequence - this allows for
-things like C<if> which choose the next op dynamically at run time. The
-C<PERL_ASYNC_CHECK> makes sure that things like signals interrupt
-execution if required.
-
-The actual functions called are known as PP code, and they're spread
-between four files: F<pp_hot.c> contains the "hot" code, which is most
-often used and highly optimized, F<pp_sys.c> contains all the
-system-specific functions, F<pp_ctl.c> contains the functions which
-implement control structures (C<if>, C<while> and the like) and F<pp.c>
-contains everything else. These are, if you like, the C code for Perl's
-built-in functions and operators.
-
-Note that each C<pp_> function is expected to return a pointer to the
-next op. Calls to perl subs (and eval blocks) are handled within the
-same runops loop, and do not consume extra space on the C stack. For
-example, C<pp_entersub> and C<pp_entertry> just push a C<CxSUB> or
-C<CxEVAL> block struct onto the context stack which contain the address
-of the op following the sub call or eval. They then return the first op
-of that sub or eval block, and so execution continues of that sub or
-block. Later, a C<pp_leavesub> or C<pp_leavetry> op pops the C<CxSUB>
-or C<CxEVAL>, retrieves the return op from it, and returns it.
-
-=head2 Exception handing
-
-Perl's exception handing (i.e. C<die> etc.) is built on top of the
-low-level C<setjmp()>/C<longjmp()> C-library functions. These basically
-provide a way to capture the current PC and SP registers and later
-restore them; i.e. a C<longjmp()> continues at the point in code where
-a previous C<setjmp()> was done, with anything further up on the C
-stack being lost. This is why code should always save values using
-C<SAVE_FOO> rather than in auto variables.
-
-The perl core wraps C<setjmp()> etc in the macros C<JMPENV_PUSH> and
-C<JMPENV_JUMP>. The basic rule of perl exceptions is that C<exit>, and
-C<die> (in the absence of C<eval>) perform a C<JMPENV_JUMP(2)>, while
-C<die> within C<eval> does a C<JMPENV_JUMP(3)>.
-
-At entry points to perl, such as C<perl_parse()>, C<perl_run()> and
-C<call_sv(cv, G_EVAL)> each does a C<JMPENV_PUSH>, then enter a runops
-loop or whatever, and handle possible exception returns. For a 2
-return, final cleanup is performed, such as popping stacks and calling
-C<CHECK> or C<END> blocks. Amongst other things, this is how scope
-cleanup still occurs during an C<exit>.
-
-If a C<die> can find a C<CxEVAL> block on the context stack, then the
-stack is popped to that level and the return op in that block is
-assigned to C<PL_restartop>; then a C<JMPENV_JUMP(3)> is performed.
-This normally passes control back to the guard. In the case of
-C<perl_run> and C<call_sv>, a non-null C<PL_restartop> triggers
-re-entry to the runops loop. The is the normal way that C<die> or
-C<croak> is handled within an C<eval>.
-
-Sometimes ops are executed within an inner runops loop, such as tie,
-sort or overload code. In this case, something like
-
- sub FETCH { eval { die } }
-
-would cause a longjmp right back to the guard in C<perl_run>, popping
-both runops loops, which is clearly incorrect. One way to avoid this is
-for the tie code to do a C<JMPENV_PUSH> before executing C<FETCH> in
-the inner runops loop, but for efficiency reasons, perl in fact just
-sets a flag, using C<CATCH_SET(TRUE)>. The C<pp_require>,
-C<pp_entereval> and C<pp_entertry> ops check this flag, and if true,
-they call C<docatch>, which does a C<JMPENV_PUSH> and starts a new
-runops level to execute the code, rather than doing it on the current
-loop.
-
-As a further optimisation, on exit from the eval block in the C<FETCH>,
-execution of the code following the block is still carried on in the
-inner loop. When an exception is raised, C<docatch> compares the
-C<JMPENV> level of the C<CxEVAL> with C<PL_top_env> and if they differ,
-just re-throws the exception. In this way any inner loops get popped.
-
-Here's an example.
-
- 1: eval { tie @a, 'A' };
- 2: sub A::TIEARRAY {
- 3: eval { die };
- 4: die;
- 5: }
-
-To run this code, C<perl_run> is called, which does a C<JMPENV_PUSH>
-then enters a runops loop. This loop executes the eval and tie ops on
-line 1, with the eval pushing a C<CxEVAL> onto the context stack.
-
-The C<pp_tie> does a C<CATCH_SET(TRUE)>, then starts a second runops
-loop to execute the body of C<TIEARRAY>. When it executes the entertry
-op on line 3, C<CATCH_GET> is true, so C<pp_entertry> calls C<docatch>
-which does a C<JMPENV_PUSH> and starts a third runops loop, which then
-executes the die op. At this point the C call stack looks like this:
-
- Perl_pp_die
- Perl_runops # third loop
- S_docatch_body
- S_docatch
- Perl_pp_entertry
- Perl_runops # second loop
- S_call_body
- Perl_call_sv
- Perl_pp_tie
- Perl_runops # first loop
- S_run_body
- perl_run
- main
-
-and the context and data stacks, as shown by C<-Dstv>, look like:
-
- STACK 0: MAIN
- CX 0: BLOCK =>
- CX 1: EVAL => AV() PV("A"\0)
- retop=leave
- STACK 1: MAGIC
- CX 0: SUB =>
- retop=(null)
- CX 1: EVAL => *
- retop=nextstate
-
-The die pops the first C<CxEVAL> off the context stack, sets
-C<PL_restartop> from it, does a C<JMPENV_JUMP(3)>, and control returns
-to the top C<docatch>. This then starts another third-level runops
-level, which executes the nextstate, pushmark and die ops on line 4. At
-the point that the second C<pp_die> is called, the C call stack looks
-exactly like that above, even though we are no longer within an inner
-eval; this is because of the optimization mentioned earlier. However,
-the context stack now looks like this, ie with the top CxEVAL popped:
-
- STACK 0: MAIN
- CX 0: BLOCK =>
- CX 1: EVAL => AV() PV("A"\0)
- retop=leave
- STACK 1: MAGIC
- CX 0: SUB =>
- retop=(null)
-
-The die on line 4 pops the context stack back down to the CxEVAL,
-leaving it as:
-
- STACK 0: MAIN
- CX 0: BLOCK =>
-
-As usual, C<PL_restartop> is extracted from the C<CxEVAL>, and a
-C<JMPENV_JUMP(3)> done, which pops the C stack back to the docatch:
-
- S_docatch
- Perl_pp_entertry
- Perl_runops # second loop
- S_call_body
- Perl_call_sv
- Perl_pp_tie
- Perl_runops # first loop
- S_run_body
- perl_run
- main
-
-In this case, because the C<JMPENV> level recorded in the C<CxEVAL>
-differs from the current one, C<docatch> just does a C<JMPENV_JUMP(3)>
-and the C stack unwinds to:
-
- perl_run
- main
-
-Because C<PL_restartop> is non-null, C<run_body> starts a new runops
-loop and execution continues.
-
-=head2 INTERNAL VARIABLE TYPES
-
-You should by now have had a look at L<perlguts>, which tells you about
-Perl's internal variable types: SVs, HVs, AVs and the rest. If not, do
-that now.
-
-These variables are used not only to represent Perl-space variables,
-but also any constants in the code, as well as some structures
-completely internal to Perl. The symbol table, for instance, is an
-ordinary Perl hash. Your code is represented by an SV as it's read into
-the parser; any program files you call are opened via ordinary Perl
-filehandles, and so on.
-
-The core L<Devel::Peek|Devel::Peek> module lets us examine SVs from a
-Perl program. Let's see, for instance, how Perl treats the constant
-C<"hello">.
-
- % perl -MDevel::Peek -e 'Dump("hello")'
- 1 SV = PV(0xa041450) at 0xa04ecbc
- 2 REFCNT = 1
- 3 FLAGS = (POK,READONLY,pPOK)
- 4 PV = 0xa0484e0 "hello"\0
- 5 CUR = 5
- 6 LEN = 6
-
-Reading C<Devel::Peek> output takes a bit of practise, so let's go
-through it line by line.
-
-Line 1 tells us we're looking at an SV which lives at C<0xa04ecbc> in
-memory. SVs themselves are very simple structures, but they contain a
-pointer to a more complex structure. In this case, it's a PV, a
-structure which holds a string value, at location C<0xa041450>. Line 2
-is the reference count; there are no other references to this data, so
-it's 1.
-
-Line 3 are the flags for this SV - it's OK to use it as a PV, it's a
-read-only SV (because it's a constant) and the data is a PV internally.
-Next we've got the contents of the string, starting at location
-C<0xa0484e0>.
-
-Line 5 gives us the current length of the string - note that this does
-B<not> include the null terminator. Line 6 is not the length of the
-string, but the length of the currently allocated buffer; as the string
-grows, Perl automatically extends the available storage via a routine
-called C<SvGROW>.
-
-You can get at any of these quantities from C very easily; just add
-C<Sv> to the name of the field shown in the snippet, and you've got a
-macro which will return the value: C<SvCUR(sv)> returns the current
-length of the string, C<SvREFCOUNT(sv)> returns the reference count,
-C<SvPV(sv, len)> returns the string itself with its length, and so on.
-More macros to manipulate these properties can be found in L<perlguts>.
-
-Let's take an example of manipulating a PV, from C<sv_catpvn>, in
-F<sv.c>
-
- 1 void
- 2 Perl_sv_catpvn(pTHX_ register SV *sv, register const char *ptr, register STRLEN len)
- 3 {
- 4 STRLEN tlen;
- 5 char *junk;
-
- 6 junk = SvPV_force(sv, tlen);
- 7 SvGROW(sv, tlen + len + 1);
- 8 if (ptr == junk)
- 9 ptr = SvPVX(sv);
- 10 Move(ptr,SvPVX(sv)+tlen,len,char);
- 11 SvCUR(sv) += len;
- 12 *SvEND(sv) = '\0';
- 13 (void)SvPOK_only_UTF8(sv); /* validate pointer */
- 14 SvTAINT(sv);
- 15 }
-
-This is a function which adds a string, C<ptr>, of length C<len> onto
-the end of the PV stored in C<sv>. The first thing we do in line 6 is
-make sure that the SV B<has> a valid PV, by calling the C<SvPV_force>
-macro to force a PV. As a side effect, C<tlen> gets set to the current
-value of the PV, and the PV itself is returned to C<junk>.
-
-In line 7, we make sure that the SV will have enough room to
-accommodate the old string, the new string and the null terminator. If
-C<LEN> isn't big enough, C<SvGROW> will reallocate space for us.
-
-Now, if C<junk> is the same as the string we're trying to add, we can
-grab the string directly from the SV; C<SvPVX> is the address of the PV
-in the SV.
-
-Line 10 does the actual catenation: the C<Move> macro moves a chunk of
-memory around: we move the string C<ptr> to the end of the PV - that's
-the start of the PV plus its current length. We're moving C<len> bytes
-of type C<char>. After doing so, we need to tell Perl we've extended
-the string, by altering C<CUR> to reflect the new length. C<SvEND> is a
-macro which gives us the end of the string, so that needs to be a
-C<"\0">.
-
-Line 13 manipulates the flags; since we've changed the PV, any IV or NV
-values will no longer be valid: if we have C<$a=10; $a.="6";> we don't
-want to use the old IV of 10. C<SvPOK_only_utf8> is a special
-UTF-8-aware version of C<SvPOK_only>, a macro which turns off the IOK
-and NOK flags and turns on POK. The final C<SvTAINT> is a macro which
-launders tainted data if taint mode is turned on.
-
-AVs and HVs are more complicated, but SVs are by far the most common
-variable type being thrown around. Having seen something of how we
-manipulate these, let's go on and look at how the op tree is
-constructed.
-
-=head1 OP TREES
-
-First, what is the op tree, anyway? The op tree is the parsed
-representation of your program, as we saw in our section on parsing,
-and it's the sequence of operations that Perl goes through to execute
-your program, as we saw in L</Running>.
-
-An op is a fundamental operation that Perl can perform: all the
-built-in functions and operators are ops, and there are a series of ops
-which deal with concepts the interpreter needs internally - entering
-and leaving a block, ending a statement, fetching a variable, and so
-on.
-
-The op tree is connected in two ways: you can imagine that there are
-two "routes" through it, two orders in which you can traverse the tree.
-First, parse order reflects how the parser understood the code, and
-secondly, execution order tells perl what order to perform the
-operations in.
-
-The easiest way to examine the op tree is to stop Perl after it has
-finished parsing, and get it to dump out the tree. This is exactly what
-the compiler backends L<B::Terse|B::Terse>, L<B::Concise|B::Concise>
-and L<B::Debug|B::Debug> do.
-
-Let's have a look at how Perl sees C<$a = $b + $c>:
-
- % perl -MO=Terse -e '$a=$b+$c'
- 1 LISTOP (0x8179888) leave
- 2 OP (0x81798b0) enter
- 3 COP (0x8179850) nextstate
- 4 BINOP (0x8179828) sassign
- 5 BINOP (0x8179800) add [1]
- 6 UNOP (0x81796e0) null [15]
- 7 SVOP (0x80fafe0) gvsv GV (0x80fa4cc) *b
- 8 UNOP (0x81797e0) null [15]
- 9 SVOP (0x8179700) gvsv GV (0x80efeb0) *c
- 10 UNOP (0x816b4f0) null [15]
- 11 SVOP (0x816dcf0) gvsv GV (0x80fa460) *a
-
-Let's start in the middle, at line 4. This is a BINOP, a binary
-operator, which is at location C<0x8179828>. The specific operator in
-question is C<sassign> - scalar assignment - and you can find the code
-which implements it in the function C<pp_sassign> in F<pp_hot.c>. As a
-binary operator, it has two children: the add operator, providing the
-result of C<$b+$c>, is uppermost on line 5, and the left hand side is
-on line 10.
-
-Line 10 is the null op: this does exactly nothing. What is that doing
-there? If you see the null op, it's a sign that something has been
-optimized away after parsing. As we mentioned in L</Optimization>, the
-optimization stage sometimes converts two operations into one, for
-example when fetching a scalar variable. When this happens, instead of
-rewriting the op tree and cleaning up the dangling pointers, it's
-easier just to replace the redundant operation with the null op.
-Originally, the tree would have looked like this:
-
- 10 SVOP (0x816b4f0) rv2sv [15]
- 11 SVOP (0x816dcf0) gv GV (0x80fa460) *a
-
-That is, fetch the C<a> entry from the main symbol table, and then look
-at the scalar component of it: C<gvsv> (C<pp_gvsv> into F<pp_hot.c>)
-happens to do both these things.
-
-The right hand side, starting at line 5 is similar to what we've just
-seen: we have the C<add> op (C<pp_add> also in F<pp_hot.c>) add
-together two C<gvsv>s.
-
-Now, what's this about?
-
- 1 LISTOP (0x8179888) leave
- 2 OP (0x81798b0) enter
- 3 COP (0x8179850) nextstate
-
-C<enter> and C<leave> are scoping ops, and their job is to perform any
-housekeeping every time you enter and leave a block: lexical variables
-are tidied up, unreferenced variables are destroyed, and so on. Every
-program will have those first three lines: C<leave> is a list, and its
-children are all the statements in the block. Statements are delimited
-by C<nextstate>, so a block is a collection of C<nextstate> ops, with
-the ops to be performed for each statement being the children of
-C<nextstate>. C<enter> is a single op which functions as a marker.
-
-That's how Perl parsed the program, from top to bottom:
-
- Program
- |
- Statement
- |
- =
- / \
- / \
- $a +
- / \
- $b $c
-
-However, it's impossible to B<perform> the operations in this order:
-you have to find the values of C<$b> and C<$c> before you add them
-together, for instance. So, the other thread that runs through the op
-tree is the execution order: each op has a field C<op_next> which
-points to the next op to be run, so following these pointers tells us
-how perl executes the code. We can traverse the tree in this order
-using the C<exec> option to C<B::Terse>:
-
- % perl -MO=Terse,exec -e '$a=$b+$c'
- 1 OP (0x8179928) enter
- 2 COP (0x81798c8) nextstate
- 3 SVOP (0x81796c8) gvsv GV (0x80fa4d4) *b
- 4 SVOP (0x8179798) gvsv GV (0x80efeb0) *c
- 5 BINOP (0x8179878) add [1]
- 6 SVOP (0x816dd38) gvsv GV (0x80fa468) *a
- 7 BINOP (0x81798a0) sassign
- 8 LISTOP (0x8179900) leave
-
-This probably makes more sense for a human: enter a block, start a
-statement. Get the values of C<$b> and C<$c>, and add them together.
-Find C<$a>, and assign one to the other. Then leave.
-
-The way Perl builds up these op trees in the parsing process can be
-unravelled by examining F<perly.y>, the YACC grammar. Let's take the
-piece we need to construct the tree for C<$a = $b + $c>
-
- 1 term : term ASSIGNOP term
- 2 { $$ = newASSIGNOP(OPf_STACKED, $1, $2, $3); }
- 3 | term ADDOP term
- 4 { $$ = newBINOP($2, 0, scalar($1), scalar($3)); }
-
-If you're not used to reading BNF grammars, this is how it works:
-You're fed certain things by the tokeniser, which generally end up in
-upper case. Here, C<ADDOP>, is provided when the tokeniser sees C<+> in
-your code. C<ASSIGNOP> is provided when C<=> is used for assigning.
-These are "terminal symbols", because you can't get any simpler than
-them.
-
-The grammar, lines one and three of the snippet above, tells you how to
-build up more complex forms. These complex forms, "non-terminal
-symbols" are generally placed in lower case. C<term> here is a
-non-terminal symbol, representing a single expression.
-
-The grammar gives you the following rule: you can make the thing on the
-left of the colon if you see all the things on the right in sequence.
-This is called a "reduction", and the aim of parsing is to completely
-reduce the input. There are several different ways you can perform a
-reduction, separated by vertical bars: so, C<term> followed by C<=>
-followed by C<term> makes a C<term>, and C<term> followed by C<+>
-followed by C<term> can also make a C<term>.
-
-So, if you see two terms with an C<=> or C<+>, between them, you can
-turn them into a single expression. When you do this, you execute the
-code in the block on the next line: if you see C<=>, you'll do the code
-in line 2. If you see C<+>, you'll do the code in line 4. It's this
-code which contributes to the op tree.
-
- | term ADDOP term
- { $$ = newBINOP($2, 0, scalar($1), scalar($3)); }
-
-What this does is creates a new binary op, and feeds it a number of
-variables. The variables refer to the tokens: C<$1> is the first token
-in the input, C<$2> the second, and so on - think regular expression
-backreferences. C<$$> is the op returned from this reduction. So, we
-call C<newBINOP> to create a new binary operator. The first parameter
-to C<newBINOP>, a function in F<op.c>, is the op type. It's an addition
-operator, so we want the type to be C<ADDOP>. We could specify this
-directly, but it's right there as the second token in the input, so we
-use C<$2>. The second parameter is the op's flags: 0 means "nothing
-special". Then the things to add: the left and right hand side of our
-expression, in scalar context.
-
-=head1 STACKS
-
-When perl executes something like C<addop>, how does it pass on its
-results to the next op? The answer is, through the use of stacks. Perl
-has a number of stacks to store things it's currently working on, and
-we'll look at the three most important ones here.
-
-=head2 Argument stack
-
-Arguments are passed to PP code and returned from PP code using the
-argument stack, C<ST>. The typical way to handle arguments is to pop
-them off the stack, deal with them how you wish, and then push the
-result back onto the stack. This is how, for instance, the cosine
-operator works:
-
- NV value;
- value = POPn;
- value = Perl_cos(value);
- XPUSHn(value);
-
-We'll see a more tricky example of this when we consider Perl's macros
-below. C<POPn> gives you the NV (floating point value) of the top SV on
-the stack: the C<$x> in C<cos($x)>. Then we compute the cosine, and
-push the result back as an NV. The C<X> in C<XPUSHn> means that the
-stack should be extended if necessary - it can't be necessary here,
-because we know there's room for one more item on the stack, since
-we've just removed one! The C<XPUSH*> macros at least guarantee safety.
-
-Alternatively, you can fiddle with the stack directly: C<SP> gives you
-the first element in your portion of the stack, and C<TOP*> gives you
-the top SV/IV/NV/etc. on the stack. So, for instance, to do unary
-negation of an integer:
-
- SETi(-TOPi);
-
-Just set the integer value of the top stack entry to its negation.
-
-Argument stack manipulation in the core is exactly the same as it is in
-XSUBs - see L<perlxstut>, L<perlxs> and L<perlguts> for a longer
-description of the macros used in stack manipulation.
-
-=head2 Mark stack
-
-I say "your portion of the stack" above because PP code doesn't
-necessarily get the whole stack to itself: if your function calls
-another function, you'll only want to expose the arguments aimed for
-the called function, and not (necessarily) let it get at your own data.
-The way we do this is to have a "virtual" bottom-of-stack, exposed to
-each function. The mark stack keeps bookmarks to locations in the
-argument stack usable by each function. For instance, when dealing with
-a tied variable, (internally, something with "P" magic) Perl has to
-call methods for accesses to the tied variables. However, we need to
-separate the arguments exposed to the method to the argument exposed to
-the original function - the store or fetch or whatever it may be.
-Here's roughly how the tied C<push> is implemented; see C<av_push> in
-F<av.c>:
-
- 1 PUSHMARK(SP);
- 2 EXTEND(SP,2);
- 3 PUSHs(SvTIED_obj((SV*)av, mg));
- 4 PUSHs(val);
- 5 PUTBACK;
- 6 ENTER;
- 7 call_method("PUSH", G_SCALAR|G_DISCARD);
- 8 LEAVE;
-
-Let's examine the whole implementation, for practice:
-
- 1 PUSHMARK(SP);
-
-Push the current state of the stack pointer onto the mark stack. This
-is so that when we've finished adding items to the argument stack, Perl
-knows how many things we've added recently.
-
- 2 EXTEND(SP,2);
- 3 PUSHs(SvTIED_obj((SV*)av, mg));
- 4 PUSHs(val);
-
-We're going to add two more items onto the argument stack: when you
-have a tied array, the C<PUSH> subroutine receives the object and the
-value to be pushed, and that's exactly what we have here - the tied
-object, retrieved with C<SvTIED_obj>, and the value, the SV C<val>.
-
- 5 PUTBACK;
-
-Next we tell Perl to update the global stack pointer from our internal
-variable: C<dSP> only gave us a local copy, not a reference to the
-global.
-
- 6 ENTER;
- 7 call_method("PUSH", G_SCALAR|G_DISCARD);
- 8 LEAVE;
-
-C<ENTER> and C<LEAVE> localise a block of code - they make sure that
-all variables are tidied up, everything that has been localised gets
-its previous value returned, and so on. Think of them as the C<{> and
-C<}> of a Perl block.
-
-To actually do the magic method call, we have to call a subroutine in
-Perl space: C<call_method> takes care of that, and it's described in
-L<perlcall>. We call the C<PUSH> method in scalar context, and we're
-going to discard its return value. The call_method() function removes
-the top element of the mark stack, so there is nothing for the caller
-to clean up.
-
-=head2 Save stack
-
-C doesn't have a concept of local scope, so perl provides one. We've
-seen that C<ENTER> and C<LEAVE> are used as scoping braces; the save
-stack implements the C equivalent of, for example:
-
- {
- local $foo = 42;
- ...
- }
-
-See L<perlguts/"Localizing changes"> for how to use the save stack.
-
-=head1 MILLIONS OF MACROS
-
-One thing you'll notice about the Perl source is that it's full of
-macros. Some have called the pervasive use of macros the hardest thing
-to understand, others find it adds to clarity. Let's take an example,
-the code which implements the addition operator:
-
- 1 PP(pp_add)
- 2 {
- 3 dSP; dATARGET; tryAMAGICbin(add,opASSIGN);
- 4 {
- 5 dPOPTOPnnrl_ul;
- 6 SETn( left + right );
- 7 RETURN;
- 8 }
- 9 }
-
-Every line here (apart from the braces, of course) contains a macro.
-The first line sets up the function declaration as Perl expects for PP
-code; line 3 sets up variable declarations for the argument stack and
-the target, the return value of the operation. Finally, it tries to see
-if the addition operation is overloaded; if so, the appropriate
-subroutine is called.
-
-Line 5 is another variable declaration - all variable declarations
-start with C<d> - which pops from the top of the argument stack two NVs
-(hence C<nn>) and puts them into the variables C<right> and C<left>,
-hence the C<rl>. These are the two operands to the addition operator.
-Next, we call C<SETn> to set the NV of the return value to the result
-of adding the two values. This done, we return - the C<RETURN> macro
-makes sure that our return value is properly handled, and we pass the
-next operator to run back to the main run loop.
-
-Most of these macros are explained in L<perlapi>, and some of the more
-important ones are explained in L<perlxs> as well. Pay special
-attention to L<perlguts/Background and PERL_IMPLICIT_CONTEXT> for
-information on the C<[pad]THX_?> macros.
-
-=head1 FURTHER READING
-
-For more information on the Perl internals, please see the documents
-listed at L<perl/Internals and C Language Interface>.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlintro.pod b/Master/tlpkg/tlperl/lib/pods/perlintro.pod
deleted file mode 100644
index afce360a2ac..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlintro.pod
+++ /dev/null
@@ -1,700 +0,0 @@
-=head1 NAME
-
-perlintro -- a brief introduction and overview of Perl
-
-=head1 DESCRIPTION
-
-This document is intended to give you a quick overview of the Perl
-programming language, along with pointers to further documentation. It
-is intended as a "bootstrap" guide for those who are new to the
-language, and provides just enough information for you to be able to
-read other peoples' Perl and understand roughly what it's doing, or
-write your own simple scripts.
-
-This introductory document does not aim to be complete. It does not
-even aim to be entirely accurate. In some cases perfection has been
-sacrificed in the goal of getting the general idea across. You are
-I<strongly> advised to follow this introduction with more information
-from the full Perl manual, the table of contents to which can be found
-in L<perltoc>.
-
-Throughout this document you'll see references to other parts of the
-Perl documentation. You can read that documentation using the C<perldoc>
-command or whatever method you're using to read this document.
-
-Throughout Perl's documentation, you'll find numerous examples intended
-to help explain the discussed features. Please keep in mind that many
-of them are code fragments rather than complete programs.
-
-These examples often reflect the style and preference of the author of
-that piece of the documentation, and may be briefer than a corresponding
-line of code in a real program. Except where otherwise noted, you
-should assume that C<use strict> and C<use warnings> statements
-appear earlier in the "program", and that any variables used have
-already been declared, even if those declarations have been omitted
-to make the example easier to read.
-
-Do note that the examples have been written by many different authors over
-a period of several decades. Styles and techniques will therefore differ,
-although some effort has been made to not vary styles too widely in the
-same sections. Do not consider one style to be better than others - "There's
-More Than One Way To Do It" is one of Perl's mottos. After all, in your
-journey as a programmer, you are likely to encounter different styles.
-
-=head2 What is Perl?
-
-Perl is a general-purpose programming language originally developed for
-text manipulation and now used for a wide range of tasks including
-system administration, web development, network programming, GUI
-development, and more.
-
-The language is intended to be practical (easy to use, efficient,
-complete) rather than beautiful (tiny, elegant, minimal). Its major
-features are that it's easy to use, supports both procedural and
-object-oriented (OO) programming, has powerful built-in support for text
-processing, and has one of the world's most impressive collections of
-third-party modules.
-
-Different definitions of Perl are given in L<perl>, L<perlfaq1> and
-no doubt other places. From this we can determine that Perl is different
-things to different people, but that lots of people think it's at least
-worth writing about.
-
-=head2 Running Perl programs
-
-To run a Perl program from the Unix command line:
-
- perl progname.pl
-
-Alternatively, put this as the first line of your script:
-
- #!/usr/bin/env perl
-
-... and run the script as C</path/to/script.pl>. Of course, it'll need
-to be executable first, so C<chmod 755 script.pl> (under Unix).
-
-(This start line assumes you have the B<env> program. You can also put
-directly the path to your perl executable, like in C<#!/usr/bin/perl>).
-
-For more information, including instructions for other platforms such as
-Windows and Mac OS, read L<perlrun>.
-
-=head2 Safety net
-
-Perl by default is very forgiving. In order to make it more robust
-it is recommended to start every program with the following lines:
-
- #!/usr/bin/perl
- use strict;
- use warnings;
-
-The two additional lines request from perl to catch various common
-problems in your code. They check different things so you need both. A
-potential problem caught by C<use strict;> will cause your code to stop
-immediately when it is encountered, while C<use warnings;> will merely
-give a warning (like the command-line switch B<-w>) and let your code run.
-To read more about them check their respective manual pages at L<strict>
-and L<warnings>.
-
-=head2 Basic syntax overview
-
-A Perl script or program consists of one or more statements. These
-statements are simply written in the script in a straightforward
-fashion. There is no need to have a C<main()> function or anything of
-that kind.
-
-Perl statements end in a semi-colon:
-
- print "Hello, world";
-
-Comments start with a hash symbol and run to the end of the line
-
- # This is a comment
-
-Whitespace is irrelevant:
-
- print
- "Hello, world"
- ;
-
-... except inside quoted strings:
-
- # this would print with a linebreak in the middle
- print "Hello
- world";
-
-Double quotes or single quotes may be used around literal strings:
-
- print "Hello, world";
- print 'Hello, world';
-
-However, only double quotes "interpolate" variables and special
-characters such as newlines (C<\n>):
-
- print "Hello, $name\n"; # works fine
- print 'Hello, $name\n'; # prints $name\n literally
-
-Numbers don't need quotes around them:
-
- print 42;
-
-You can use parentheses for functions' arguments or omit them
-according to your personal taste. They are only required
-occasionally to clarify issues of precedence.
-
- print("Hello, world\n");
- print "Hello, world\n";
-
-More detailed information about Perl syntax can be found in L<perlsyn>.
-
-=head2 Perl variable types
-
-Perl has three main variable types: scalars, arrays, and hashes.
-
-=over 4
-
-=item Scalars
-
-A scalar represents a single value:
-
- my $animal = "camel";
- my $answer = 42;
-
-Scalar values can be strings, integers or floating point numbers, and Perl
-will automatically convert between them as required. There is no need
-to pre-declare your variable types, but you have to declare them using
-the C<my> keyword the first time you use them. (This is one of the
-requirements of C<use strict;>.)
-
-Scalar values can be used in various ways:
-
- print $animal;
- print "The animal is $animal\n";
- print "The square of $answer is ", $answer * $answer, "\n";
-
-There are a number of "magic" scalars with names that look like
-punctuation or line noise. These special variables are used for all
-kinds of purposes, and are documented in L<perlvar>. The only one you
-need to know about for now is C<$_> which is the "default variable".
-It's used as the default argument to a number of functions in Perl, and
-it's set implicitly by certain looping constructs.
-
- print; # prints contents of $_ by default
-
-=item Arrays
-
-An array represents a list of values:
-
- my @animals = ("camel", "llama", "owl");
- my @numbers = (23, 42, 69);
- my @mixed = ("camel", 42, 1.23);
-
-Arrays are zero-indexed. Here's how you get at elements in an array:
-
- print $animals[0]; # prints "camel"
- print $animals[1]; # prints "llama"
-
-The special variable C<$#array> tells you the index of the last element
-of an array:
-
- print $mixed[$#mixed]; # last element, prints 1.23
-
-You might be tempted to use C<$#array + 1> to tell you how many items there
-are in an array. Don't bother. As it happens, using C<@array> where Perl
-expects to find a scalar value ("in scalar context") will give you the number
-of elements in the array:
-
- if (@animals < 5) { ... }
-
-The elements we're getting from the array start with a C<$> because
-we're getting just a single value out of the array; you ask for a scalar,
-you get a scalar.
-
-To get multiple values from an array:
-
- @animals[0,1]; # gives ("camel", "llama");
- @animals[0..2]; # gives ("camel", "llama", "owl");
- @animals[1..$#animals]; # gives all except the first element
-
-This is called an "array slice".
-
-You can do various useful things to lists:
-
- my @sorted = sort @animals;
- my @backwards = reverse @numbers;
-
-There are a couple of special arrays too, such as C<@ARGV> (the command
-line arguments to your script) and C<@_> (the arguments passed to a
-subroutine). These are documented in L<perlvar>.
-
-=item Hashes
-
-A hash represents a set of key/value pairs:
-
- my %fruit_color = ("apple", "red", "banana", "yellow");
-
-You can use whitespace and the C<< => >> operator to lay them out more
-nicely:
-
- my %fruit_color = (
- apple => "red",
- banana => "yellow",
- );
-
-To get at hash elements:
-
- $fruit_color{"apple"}; # gives "red"
-
-You can get at lists of keys and values with C<keys()> and
-C<values()>.
-
- my @fruits = keys %fruit_colors;
- my @colors = values %fruit_colors;
-
-Hashes have no particular internal order, though you can sort the keys
-and loop through them.
-
-Just like special scalars and arrays, there are also special hashes.
-The most well known of these is C<%ENV> which contains environment
-variables. Read all about it (and other special variables) in
-L<perlvar>.
-
-=back
-
-Scalars, arrays and hashes are documented more fully in L<perldata>.
-
-More complex data types can be constructed using references, which allow
-you to build lists and hashes within lists and hashes.
-
-A reference is a scalar value and can refer to any other Perl data
-type. So by storing a reference as the value of an array or hash
-element, you can easily create lists and hashes within lists and
-hashes. The following example shows a 2 level hash of hash
-structure using anonymous hash references.
-
- my $variables = {
- scalar => {
- description => "single item",
- sigil => '$',
- },
- array => {
- description => "ordered list of items",
- sigil => '@',
- },
- hash => {
- description => "key/value pairs",
- sigil => '%',
- },
- };
-
- print "Scalars begin with a $variables->{'scalar'}->{'sigil'}\n";
-
-Exhaustive information on the topic of references can be found in
-L<perlreftut>, L<perllol>, L<perlref> and L<perldsc>.
-
-=head2 Variable scoping
-
-Throughout the previous section all the examples have used the syntax:
-
- my $var = "value";
-
-The C<my> is actually not required; you could just use:
-
- $var = "value";
-
-However, the above usage will create global variables throughout your
-program, which is bad programming practice. C<my> creates lexically
-scoped variables instead. The variables are scoped to the block
-(i.e. a bunch of statements surrounded by curly-braces) in which they
-are defined.
-
- my $x = "foo";
- my $some_condition = 1;
- if ($some_condition) {
- my $y = "bar";
- print $x; # prints "foo"
- print $y; # prints "bar"
- }
- print $x; # prints "foo"
- print $y; # prints nothing; $y has fallen out of scope
-
-Using C<my> in combination with a C<use strict;> at the top of
-your Perl scripts means that the interpreter will pick up certain common
-programming errors. For instance, in the example above, the final
-C<print $y> would cause a compile-time error and prevent you from
-running the program. Using C<strict> is highly recommended.
-
-=head2 Conditional and looping constructs
-
-Perl has most of the usual conditional and looping constructs. As of Perl
-5.10, it even has a case/switch statement (spelled C<given>/C<when>). See
-L<perlsyn/"Switch Statements"> for more details.
-
-The conditions can be any Perl expression. See the list of operators in
-the next section for information on comparison and boolean logic operators,
-which are commonly used in conditional statements.
-
-=over 4
-
-=item if
-
- if ( condition ) {
- ...
- } elsif ( other condition ) {
- ...
- } else {
- ...
- }
-
-There's also a negated version of it:
-
- unless ( condition ) {
- ...
- }
-
-This is provided as a more readable version of C<if (!I<condition>)>.
-
-Note that the braces are required in Perl, even if you've only got one
-line in the block. However, there is a clever way of making your one-line
-conditional blocks more English like:
-
- # the traditional way
- if ($zippy) {
- print "Yow!";
- }
-
- # the Perlish post-condition way
- print "Yow!" if $zippy;
- print "We have no bananas" unless $bananas;
-
-=item while
-
- while ( condition ) {
- ...
- }
-
-There's also a negated version, for the same reason we have C<unless>:
-
- until ( condition ) {
- ...
- }
-
-You can also use C<while> in a post-condition:
-
- print "LA LA LA\n" while 1; # loops forever
-
-=item for
-
-Exactly like C:
-
- for ($i = 0; $i <= $max; $i++) {
- ...
- }
-
-The C style for loop is rarely needed in Perl since Perl provides
-the more friendly list scanning C<foreach> loop.
-
-=item foreach
-
- foreach (@array) {
- print "This element is $_\n";
- }
-
- print $list[$_] foreach 0 .. $max;
-
- # you don't have to use the default $_ either...
- foreach my $key (keys %hash) {
- print "The value of $key is $hash{$key}\n";
- }
-
-The C<foreach> keyword is actually a synonym for the C<for>
-keyword. See C<L<perlsyn/"Foreach Loops">>.
-
-=back
-
-For more detail on looping constructs (and some that weren't mentioned in
-this overview) see L<perlsyn>.
-
-=head2 Builtin operators and functions
-
-Perl comes with a wide selection of builtin functions. Some of the ones
-we've already seen include C<print>, C<sort> and C<reverse>. A list of
-them is given at the start of L<perlfunc> and you can easily read
-about any given function by using C<perldoc -f I<functionname>>.
-
-Perl operators are documented in full in L<perlop>, but here are a few
-of the most common ones:
-
-=over 4
-
-=item Arithmetic
-
- + addition
- - subtraction
- * multiplication
- / division
-
-=item Numeric comparison
-
- == equality
- != inequality
- < less than
- > greater than
- <= less than or equal
- >= greater than or equal
-
-=item String comparison
-
- eq equality
- ne inequality
- lt less than
- gt greater than
- le less than or equal
- ge greater than or equal
-
-(Why do we have separate numeric and string comparisons? Because we don't
-have special variable types, and Perl needs to know whether to sort
-numerically (where 99 is less than 100) or alphabetically (where 100 comes
-before 99).
-
-=item Boolean logic
-
- && and
- || or
- ! not
-
-(C<and>, C<or> and C<not> aren't just in the above table as descriptions
-of the operators. They're also supported as operators in their own
-right. They're more readable than the C-style operators, but have
-different precedence to C<&&> and friends. Check L<perlop> for more
-detail.)
-
-=item Miscellaneous
-
- = assignment
- . string concatenation
- x string multiplication
- .. range operator (creates a list of numbers)
-
-=back
-
-Many operators can be combined with a C<=> as follows:
-
- $a += 1; # same as $a = $a + 1
- $a -= 1; # same as $a = $a - 1
- $a .= "\n"; # same as $a = $a . "\n";
-
-=head2 Files and I/O
-
-You can open a file for input or output using the C<open()> function.
-It's documented in extravagant detail in L<perlfunc> and L<perlopentut>,
-but in short:
-
- open(my $in, "<", "input.txt") or die "Can't open input.txt: $!";
- open(my $out, ">", "output.txt") or die "Can't open output.txt: $!";
- open(my $log, ">>", "my.log") or die "Can't open my.log: $!";
-
-You can read from an open filehandle using the C<< <> >> operator. In
-scalar context it reads a single line from the filehandle, and in list
-context it reads the whole file in, assigning each line to an element of
-the list:
-
- my $line = <$in>;
- my @lines = <$in>;
-
-Reading in the whole file at one time is called slurping. It can
-be useful but it may be a memory hog. Most text file processing
-can be done a line at a time with Perl's looping constructs.
-
-The C<< <> >> operator is most often seen in a C<while> loop:
-
- while (<$in>) { # assigns each line in turn to $_
- print "Just read in this line: $_";
- }
-
-We've already seen how to print to standard output using C<print()>.
-However, C<print()> can also take an optional first argument specifying
-which filehandle to print to:
-
- print STDERR "This is your final warning.\n";
- print $out $record;
- print $log $logmessage;
-
-When you're done with your filehandles, you should C<close()> them
-(though to be honest, Perl will clean up after you if you forget):
-
- close $in or die "$in: $!";
-
-=head2 Regular expressions
-
-Perl's regular expression support is both broad and deep, and is the
-subject of lengthy documentation in L<perlrequick>, L<perlretut>, and
-elsewhere. However, in short:
-
-=over 4
-
-=item Simple matching
-
- if (/foo/) { ... } # true if $_ contains "foo"
- if ($a =~ /foo/) { ... } # true if $a contains "foo"
-
-The C<//> matching operator is documented in L<perlop>. It operates on
-C<$_> by default, or can be bound to another variable using the C<=~>
-binding operator (also documented in L<perlop>).
-
-=item Simple substitution
-
- s/foo/bar/; # replaces foo with bar in $_
- $a =~ s/foo/bar/; # replaces foo with bar in $a
- $a =~ s/foo/bar/g; # replaces ALL INSTANCES of foo with bar in $a
-
-The C<s///> substitution operator is documented in L<perlop>.
-
-=item More complex regular expressions
-
-You don't just have to match on fixed strings. In fact, you can match
-on just about anything you could dream of by using more complex regular
-expressions. These are documented at great length in L<perlre>, but for
-the meantime, here's a quick cheat sheet:
-
- . a single character
- \s a whitespace character (space, tab, newline, ...)
- \S non-whitespace character
- \d a digit (0-9)
- \D a non-digit
- \w a word character (a-z, A-Z, 0-9, _)
- \W a non-word character
- [aeiou] matches a single character in the given set
- [^aeiou] matches a single character outside the given set
- (foo|bar|baz) matches any of the alternatives specified
-
- ^ start of string
- $ end of string
-
-Quantifiers can be used to specify how many of the previous thing you
-want to match on, where "thing" means either a literal character, one
-of the metacharacters listed above, or a group of characters or
-metacharacters in parentheses.
-
- * zero or more of the previous thing
- + one or more of the previous thing
- ? zero or one of the previous thing
- {3} matches exactly 3 of the previous thing
- {3,6} matches between 3 and 6 of the previous thing
- {3,} matches 3 or more of the previous thing
-
-Some brief examples:
-
- /^\d+/ string starts with one or more digits
- /^$/ nothing in the string (start and end are adjacent)
- /(\d\s){3}/ a three digits, each followed by a whitespace
- character (eg "3 4 5 ")
- /(a.)+/ matches a string in which every odd-numbered letter
- is a (eg "abacadaf")
-
- # This loop reads from STDIN, and prints non-blank lines:
- while (<>) {
- next if /^$/;
- print;
- }
-
-=item Parentheses for capturing
-
-As well as grouping, parentheses serve a second purpose. They can be
-used to capture the results of parts of the regexp match for later use.
-The results end up in C<$1>, C<$2> and so on.
-
- # a cheap and nasty way to break an email address up into parts
-
- if ($email =~ /([^@]+)@(.+)/) {
- print "Username is $1\n";
- print "Hostname is $2\n";
- }
-
-=item Other regexp features
-
-Perl regexps also support backreferences, lookaheads, and all kinds of
-other complex details. Read all about them in L<perlrequick>,
-L<perlretut>, and L<perlre>.
-
-=back
-
-=head2 Writing subroutines
-
-Writing subroutines is easy:
-
- sub logger {
- my $logmessage = shift;
- open my $logfile, ">>", "my.log" or die "Could not open my.log: $!";
- print $logfile $logmessage;
- }
-
-Now we can use the subroutine just as any other built-in function:
-
- logger("We have a logger subroutine!");
-
-What's that C<shift>? Well, the arguments to a subroutine are available
-to us as a special array called C<@_> (see L<perlvar> for more on that).
-The default argument to the C<shift> function just happens to be C<@_>.
-So C<my $logmessage = shift;> shifts the first item off the list of
-arguments and assigns it to C<$logmessage>.
-
-We can manipulate C<@_> in other ways too:
-
- my ($logmessage, $priority) = @_; # common
- my $logmessage = $_[0]; # uncommon, and ugly
-
-Subroutines can also return values:
-
- sub square {
- my $num = shift;
- my $result = $num * $num;
- return $result;
- }
-
-Then use it like:
-
- $sq = square(8);
-
-For more information on writing subroutines, see L<perlsub>.
-
-=head2 OO Perl
-
-OO Perl is relatively simple and is implemented using references which
-know what sort of object they are based on Perl's concept of packages.
-However, OO Perl is largely beyond the scope of this document.
-Read L<perlootut> and L<perlobj>.
-
-As a beginning Perl programmer, your most common use of OO Perl will be
-in using third-party modules, which are documented below.
-
-=head2 Using Perl modules
-
-Perl modules provide a range of features to help you avoid reinventing
-the wheel, and can be downloaded from CPAN ( http://www.cpan.org/ ). A
-number of popular modules are included with the Perl distribution
-itself.
-
-Categories of modules range from text manipulation to network protocols
-to database integration to graphics. A categorized list of modules is
-also available from CPAN.
-
-To learn how to install modules you download from CPAN, read
-L<perlmodinstall>.
-
-To learn how to use a particular module, use C<perldoc I<Module::Name>>.
-Typically you will want to C<use I<Module::Name>>, which will then give
-you access to exported functions or an OO interface to the module.
-
-L<perlfaq> contains questions and answers related to many common
-tasks, and often provides suggestions for good CPAN modules to use.
-
-L<perlmod> describes Perl modules in general. L<perlmodlib> lists the
-modules which came with your Perl installation.
-
-If you feel the urge to write Perl modules, L<perlnewmod> will give you
-good advice.
-
-=head1 AUTHOR
-
-Kirrily "Skud" Robert <skud@cpan.org>
diff --git a/Master/tlpkg/tlperl/lib/pods/perliol.pod b/Master/tlpkg/tlperl/lib/pods/perliol.pod
deleted file mode 100644
index 767fabdd7ff..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perliol.pod
+++ /dev/null
@@ -1,1040 +0,0 @@
-=head1 NAME
-
-perliol - C API for Perl's implementation of IO in Layers.
-
-=head1 SYNOPSIS
-
- /* Defining a layer ... */
- #include <perliol.h>
-
-=head1 DESCRIPTION
-
-This document describes the behavior and implementation of the PerlIO
-abstraction described in L<perlapio> when C<USE_PERLIO> is defined (and
-C<USE_SFIO> is not).
-
-=head2 History and Background
-
-The PerlIO abstraction was introduced in perl5.003_02 but languished as
-just an abstraction until perl5.7.0. However during that time a number
-of perl extensions switched to using it, so the API is mostly fixed to
-maintain (source) compatibility.
-
-The aim of the implementation is to provide the PerlIO API in a flexible
-and platform neutral manner. It is also a trial of an "Object Oriented
-C, with vtables" approach which may be applied to Perl 6.
-
-=head2 Basic Structure
-
-PerlIO is a stack of layers.
-
-The low levels of the stack work with the low-level operating system
-calls (file descriptors in C) getting bytes in and out, the higher
-layers of the stack buffer, filter, and otherwise manipulate the I/O,
-and return characters (or bytes) to Perl. Terms I<above> and I<below>
-are used to refer to the relative positioning of the stack layers.
-
-A layer contains a "vtable", the table of I/O operations (at C level
-a table of function pointers), and status flags. The functions in the
-vtable implement operations like "open", "read", and "write".
-
-When I/O, for example "read", is requested, the request goes from Perl
-first down the stack using "read" functions of each layer, then at the
-bottom the input is requested from the operating system services, then
-the result is returned up the stack, finally being interpreted as Perl
-data.
-
-The requests do not necessarily go always all the way down to the
-operating system: that's where PerlIO buffering comes into play.
-
-When you do an open() and specify extra PerlIO layers to be deployed,
-the layers you specify are "pushed" on top of the already existing
-default stack. One way to see it is that "operating system is
-on the left" and "Perl is on the right".
-
-What exact layers are in this default stack depends on a lot of
-things: your operating system, Perl version, Perl compile time
-configuration, and Perl runtime configuration. See L<PerlIO>,
-L<perlrun/PERLIO>, and L<open> for more information.
-
-binmode() operates similarly to open(): by default the specified
-layers are pushed on top of the existing stack.
-
-However, note that even as the specified layers are "pushed on top"
-for open() and binmode(), this doesn't mean that the effects are
-limited to the "top": PerlIO layers can be very 'active' and inspect
-and affect layers also deeper in the stack. As an example there
-is a layer called "raw" which repeatedly "pops" layers until
-it reaches the first layer that has declared itself capable of
-handling binary data. The "pushed" layers are processed in left-to-right
-order.
-
-sysopen() operates (unsurprisingly) at a lower level in the stack than
-open(). For example in Unix or Unix-like systems sysopen() operates
-directly at the level of file descriptors: in the terms of PerlIO
-layers, it uses only the "unix" layer, which is a rather thin wrapper
-on top of the Unix file descriptors.
-
-=head2 Layers vs Disciplines
-
-Initial discussion of the ability to modify IO streams behaviour used
-the term "discipline" for the entities which were added. This came (I
-believe) from the use of the term in "sfio", which in turn borrowed it
-from "line disciplines" on Unix terminals. However, this document (and
-the C code) uses the term "layer".
-
-This is, I hope, a natural term given the implementation, and should
-avoid connotations that are inherent in earlier uses of "discipline"
-for things which are rather different.
-
-=head2 Data Structures
-
-The basic data structure is a PerlIOl:
-
- typedef struct _PerlIO PerlIOl;
- typedef struct _PerlIO_funcs PerlIO_funcs;
- typedef PerlIOl *PerlIO;
-
- struct _PerlIO
- {
- PerlIOl * next; /* Lower layer */
- PerlIO_funcs * tab; /* Functions for this layer */
- IV flags; /* Various flags for state */
- };
-
-A C<PerlIOl *> is a pointer to the struct, and the I<application>
-level C<PerlIO *> is a pointer to a C<PerlIOl *> - i.e. a pointer
-to a pointer to the struct. This allows the application level C<PerlIO *>
-to remain constant while the actual C<PerlIOl *> underneath
-changes. (Compare perl's C<SV *> which remains constant while its
-C<sv_any> field changes as the scalar's type changes.) An IO stream is
-then in general represented as a pointer to this linked-list of
-"layers".
-
-It should be noted that because of the double indirection in a C<PerlIO *>,
-a C<< &(perlio->next) >> "is" a C<PerlIO *>, and so to some degree
-at least one layer can use the "standard" API on the next layer down.
-
-A "layer" is composed of two parts:
-
-=over 4
-
-=item 1.
-
-The functions and attributes of the "layer class".
-
-=item 2.
-
-The per-instance data for a particular handle.
-
-=back
-
-=head2 Functions and Attributes
-
-The functions and attributes are accessed via the "tab" (for table)
-member of C<PerlIOl>. The functions (methods of the layer "class") are
-fixed, and are defined by the C<PerlIO_funcs> type. They are broadly the
-same as the public C<PerlIO_xxxxx> functions:
-
- struct _PerlIO_funcs
- {
- Size_t fsize;
- char * name;
- Size_t size;
- IV kind;
- IV (*Pushed)(pTHX_ PerlIO *f,const char *mode,SV *arg, PerlIO_funcs *tab);
- IV (*Popped)(pTHX_ PerlIO *f);
- PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab,
- PerlIO_list_t *layers, IV n,
- const char *mode,
- int fd, int imode, int perm,
- PerlIO *old,
- int narg, SV **args);
- IV (*Binmode)(pTHX_ PerlIO *f);
- SV * (*Getarg)(pTHX_ PerlIO *f, CLONE_PARAMS *param, int flags)
- IV (*Fileno)(pTHX_ PerlIO *f);
- PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o, CLONE_PARAMS *param, int flags)
- /* Unix-like functions - cf sfio line disciplines */
- SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count);
- SSize_t (*Unread)(pTHX_ PerlIO *f, const void *vbuf, Size_t count);
- SSize_t (*Write)(pTHX_ PerlIO *f, const void *vbuf, Size_t count);
- IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence);
- Off_t (*Tell)(pTHX_ PerlIO *f);
- IV (*Close)(pTHX_ PerlIO *f);
- /* Stdio-like buffered IO functions */
- IV (*Flush)(pTHX_ PerlIO *f);
- IV (*Fill)(pTHX_ PerlIO *f);
- IV (*Eof)(pTHX_ PerlIO *f);
- IV (*Error)(pTHX_ PerlIO *f);
- void (*Clearerr)(pTHX_ PerlIO *f);
- void (*Setlinebuf)(pTHX_ PerlIO *f);
- /* Perl's snooping functions */
- STDCHAR * (*Get_base)(pTHX_ PerlIO *f);
- Size_t (*Get_bufsiz)(pTHX_ PerlIO *f);
- STDCHAR * (*Get_ptr)(pTHX_ PerlIO *f);
- SSize_t (*Get_cnt)(pTHX_ PerlIO *f);
- void (*Set_ptrcnt)(pTHX_ PerlIO *f,STDCHAR *ptr,SSize_t cnt);
- };
-
-The first few members of the struct give a function table size for
-compatibility check "name" for the layer, the size to C<malloc> for the per-instance data,
-and some flags which are attributes of the class as whole (such as whether it is a buffering
-layer), then follow the functions which fall into four basic groups:
-
-=over 4
-
-=item 1.
-
-Opening and setup functions
-
-=item 2.
-
-Basic IO operations
-
-=item 3.
-
-Stdio class buffering options.
-
-=item 4.
-
-Functions to support Perl's traditional "fast" access to the buffer.
-
-=back
-
-A layer does not have to implement all the functions, but the whole
-table has to be present. Unimplemented slots can be NULL (which will
-result in an error when called) or can be filled in with stubs to
-"inherit" behaviour from a "base class". This "inheritance" is fixed
-for all instances of the layer, but as the layer chooses which stubs
-to populate the table, limited "multiple inheritance" is possible.
-
-=head2 Per-instance Data
-
-The per-instance data are held in memory beyond the basic PerlIOl
-struct, by making a PerlIOl the first member of the layer's struct
-thus:
-
- typedef struct
- {
- struct _PerlIO base; /* Base "class" info */
- STDCHAR * buf; /* Start of buffer */
- STDCHAR * end; /* End of valid part of buffer */
- STDCHAR * ptr; /* Current position in buffer */
- Off_t posn; /* Offset of buf into the file */
- Size_t bufsiz; /* Real size of buffer */
- IV oneword; /* Emergency buffer */
- } PerlIOBuf;
-
-In this way (as for perl's scalars) a pointer to a PerlIOBuf can be
-treated as a pointer to a PerlIOl.
-
-=head2 Layers in action.
-
- table perlio unix
- | |
- +-----------+ +----------+ +--------+
- PerlIO ->| |--->| next |--->| NULL |
- +-----------+ +----------+ +--------+
- | | | buffer | | fd |
- +-----------+ | | +--------+
- | | +----------+
-
-
-The above attempts to show how the layer scheme works in a simple case.
-The application's C<PerlIO *> points to an entry in the table(s)
-representing open (allocated) handles. For example the first three slots
-in the table correspond to C<stdin>,C<stdout> and C<stderr>. The table
-in turn points to the current "top" layer for the handle - in this case
-an instance of the generic buffering layer "perlio". That layer in turn
-points to the next layer down - in this case the low-level "unix" layer.
-
-The above is roughly equivalent to a "stdio" buffered stream, but with
-much more flexibility:
-
-=over 4
-
-=item *
-
-If Unix level C<read>/C<write>/C<lseek> is not appropriate for (say)
-sockets then the "unix" layer can be replaced (at open time or even
-dynamically) with a "socket" layer.
-
-=item *
-
-Different handles can have different buffering schemes. The "top"
-layer could be the "mmap" layer if reading disk files was quicker
-using C<mmap> than C<read>. An "unbuffered" stream can be implemented
-simply by not having a buffer layer.
-
-=item *
-
-Extra layers can be inserted to process the data as it flows through.
-This was the driving need for including the scheme in perl 5.7.0+ - we
-needed a mechanism to allow data to be translated between perl's
-internal encoding (conceptually at least Unicode as UTF-8), and the
-"native" format used by the system. This is provided by the
-":encoding(xxxx)" layer which typically sits above the buffering layer.
-
-=item *
-
-A layer can be added that does "\n" to CRLF translation. This layer
-can be used on any platform, not just those that normally do such
-things.
-
-=back
-
-=head2 Per-instance flag bits
-
-The generic flag bits are a hybrid of C<O_XXXXX> style flags deduced
-from the mode string passed to C<PerlIO_open()>, and state bits for
-typical buffer layers.
-
-=over 4
-
-=item PERLIO_F_EOF
-
-End of file.
-
-=item PERLIO_F_CANWRITE
-
-Writes are permitted, i.e. opened as "w" or "r+" or "a", etc.
-
-=item PERLIO_F_CANREAD
-
-Reads are permitted i.e. opened "r" or "w+" (or even "a+" - ick).
-
-=item PERLIO_F_ERROR
-
-An error has occurred (for C<PerlIO_error()>).
-
-=item PERLIO_F_TRUNCATE
-
-Truncate file suggested by open mode.
-
-=item PERLIO_F_APPEND
-
-All writes should be appends.
-
-=item PERLIO_F_CRLF
-
-Layer is performing Win32-like "\n" mapped to CR,LF for output and CR,LF
-mapped to "\n" for input. Normally the provided "crlf" layer is the only
-layer that need bother about this. C<PerlIO_binmode()> will mess with this
-flag rather than add/remove layers if the C<PERLIO_K_CANCRLF> bit is set
-for the layers class.
-
-=item PERLIO_F_UTF8
-
-Data written to this layer should be UTF-8 encoded; data provided
-by this layer should be considered UTF-8 encoded. Can be set on any layer
-by ":utf8" dummy layer. Also set on ":encoding" layer.
-
-=item PERLIO_F_UNBUF
-
-Layer is unbuffered - i.e. write to next layer down should occur for
-each write to this layer.
-
-=item PERLIO_F_WRBUF
-
-The buffer for this layer currently holds data written to it but not sent
-to next layer.
-
-=item PERLIO_F_RDBUF
-
-The buffer for this layer currently holds unconsumed data read from
-layer below.
-
-=item PERLIO_F_LINEBUF
-
-Layer is line buffered. Write data should be passed to next layer down
-whenever a "\n" is seen. Any data beyond the "\n" should then be
-processed.
-
-=item PERLIO_F_TEMP
-
-File has been C<unlink()>ed, or should be deleted on C<close()>.
-
-=item PERLIO_F_OPEN
-
-Handle is open.
-
-=item PERLIO_F_FASTGETS
-
-This instance of this layer supports the "fast C<gets>" interface.
-Normally set based on C<PERLIO_K_FASTGETS> for the class and by the
-existence of the function(s) in the table. However a class that
-normally provides that interface may need to avoid it on a
-particular instance. The "pending" layer needs to do this when
-it is pushed above a layer which does not support the interface.
-(Perl's C<sv_gets()> does not expect the streams fast C<gets> behaviour
-to change during one "get".)
-
-=back
-
-=head2 Methods in Detail
-
-=over 4
-
-=item fsize
-
- Size_t fsize;
-
-Size of the function table. This is compared against the value PerlIO
-code "knows" as a compatibility check. Future versions I<may> be able
-to tolerate layers compiled against an old version of the headers.
-
-=item name
-
- char * name;
-
-The name of the layer whose open() method Perl should invoke on
-open(). For example if the layer is called APR, you will call:
-
- open $fh, ">:APR", ...
-
-and Perl knows that it has to invoke the PerlIOAPR_open() method
-implemented by the APR layer.
-
-=item size
-
- Size_t size;
-
-The size of the per-instance data structure, e.g.:
-
- sizeof(PerlIOAPR)
-
-If this field is zero then C<PerlIO_pushed> does not malloc anything
-and assumes layer's Pushed function will do any required layer stack
-manipulation - used to avoid malloc/free overhead for dummy layers.
-If the field is non-zero it must be at least the size of C<PerlIOl>,
-C<PerlIO_pushed> will allocate memory for the layer's data structures
-and link new layer onto the stream's stack. (If the layer's Pushed
-method returns an error indication the layer is popped again.)
-
-=item kind
-
- IV kind;
-
-=over 4
-
-=item * PERLIO_K_BUFFERED
-
-The layer is buffered.
-
-=item * PERLIO_K_RAW
-
-The layer is acceptable to have in a binmode(FH) stack - i.e. it does not
-(or will configure itself not to) transform bytes passing through it.
-
-=item * PERLIO_K_CANCRLF
-
-Layer can translate between "\n" and CRLF line ends.
-
-=item * PERLIO_K_FASTGETS
-
-Layer allows buffer snooping.
-
-=item * PERLIO_K_MULTIARG
-
-Used when the layer's open() accepts more arguments than usual. The
-extra arguments should come not before the C<MODE> argument. When this
-flag is used it's up to the layer to validate the args.
-
-=back
-
-=item Pushed
-
- IV (*Pushed)(pTHX_ PerlIO *f,const char *mode, SV *arg);
-
-The only absolutely mandatory method. Called when the layer is pushed
-onto the stack. The C<mode> argument may be NULL if this occurs
-post-open. The C<arg> will be non-C<NULL> if an argument string was
-passed. In most cases this should call C<PerlIOBase_pushed()> to
-convert C<mode> into the appropriate C<PERLIO_F_XXXXX> flags in
-addition to any actions the layer itself takes. If a layer is not
-expecting an argument it need neither save the one passed to it, nor
-provide C<Getarg()> (it could perhaps C<Perl_warn> that the argument
-was un-expected).
-
-Returns 0 on success. On failure returns -1 and should set errno.
-
-=item Popped
-
- IV (*Popped)(pTHX_ PerlIO *f);
-
-Called when the layer is popped from the stack. A layer will normally
-be popped after C<Close()> is called. But a layer can be popped
-without being closed if the program is dynamically managing layers on
-the stream. In such cases C<Popped()> should free any resources
-(buffers, translation tables, ...) not held directly in the layer's
-struct. It should also C<Unread()> any unconsumed data that has been
-read and buffered from the layer below back to that layer, so that it
-can be re-provided to what ever is now above.
-
-Returns 0 on success and failure. If C<Popped()> returns I<true> then
-I<perlio.c> assumes that either the layer has popped itself, or the
-layer is super special and needs to be retained for other reasons.
-In most cases it should return I<false>.
-
-=item Open
-
- PerlIO * (*Open)(...);
-
-The C<Open()> method has lots of arguments because it combines the
-functions of perl's C<open>, C<PerlIO_open>, perl's C<sysopen>,
-C<PerlIO_fdopen> and C<PerlIO_reopen>. The full prototype is as
-follows:
-
- PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab,
- PerlIO_list_t *layers, IV n,
- const char *mode,
- int fd, int imode, int perm,
- PerlIO *old,
- int narg, SV **args);
-
-Open should (perhaps indirectly) call C<PerlIO_allocate()> to allocate
-a slot in the table and associate it with the layers information for
-the opened file, by calling C<PerlIO_push>. The I<layers> is an
-array of all the layers destined for the C<PerlIO *>, and any
-arguments passed to them, I<n> is the index into that array of the
-layer being called. The macro C<PerlIOArg> will return a (possibly
-C<NULL>) SV * for the argument passed to the layer.
-
-The I<mode> string is an "C<fopen()>-like" string which would match
-the regular expression C</^[I#]?[rwa]\+?[bt]?$/>.
-
-The C<'I'> prefix is used during creation of C<stdin>..C<stderr> via
-special C<PerlIO_fdopen> calls; the C<'#'> prefix means that this is
-C<sysopen> and that I<imode> and I<perm> should be passed to
-C<PerlLIO_open3>; C<'r'> means B<r>ead, C<'w'> means B<w>rite and
-C<'a'> means B<a>ppend. The C<'+'> suffix means that both reading and
-writing/appending are permitted. The C<'b'> suffix means file should
-be binary, and C<'t'> means it is text. (Almost all layers should do
-the IO in binary mode, and ignore the b/t bits. The C<:crlf> layer
-should be pushed to handle the distinction.)
-
-If I<old> is not C<NULL> then this is a C<PerlIO_reopen>. Perl itself
-does not use this (yet?) and semantics are a little vague.
-
-If I<fd> not negative then it is the numeric file descriptor I<fd>,
-which will be open in a manner compatible with the supplied mode
-string, the call is thus equivalent to C<PerlIO_fdopen>. In this case
-I<nargs> will be zero.
-
-If I<nargs> is greater than zero then it gives the number of arguments
-passed to C<open>, otherwise it will be 1 if for example
-C<PerlIO_open> was called. In simple cases SvPV_nolen(*args) is the
-pathname to open.
-
-If a layer provides C<Open()> it should normally call the C<Open()>
-method of next layer down (if any) and then push itself on top if that
-succeeds. C<PerlIOBase_open> is provided to do exactly that, so in
-most cases you don't have to write your own C<Open()> method. If this
-method is not defined, other layers may have difficulty pushing
-themselves on top of it during open.
-
-If C<PerlIO_push> was performed and open has failed, it must
-C<PerlIO_pop> itself, since if it's not, the layer won't be removed
-and may cause bad problems.
-
-Returns C<NULL> on failure.
-
-=item Binmode
-
- IV (*Binmode)(pTHX_ PerlIO *f);
-
-Optional. Used when C<:raw> layer is pushed (explicitly or as a result
-of binmode(FH)). If not present layer will be popped. If present
-should configure layer as binary (or pop itself) and return 0.
-If it returns -1 for error C<binmode> will fail with layer
-still on the stack.
-
-=item Getarg
-
- SV * (*Getarg)(pTHX_ PerlIO *f,
- CLONE_PARAMS *param, int flags);
-
-Optional. If present should return an SV * representing the string
-argument passed to the layer when it was
-pushed. e.g. ":encoding(ascii)" would return an SvPV with value
-"ascii". (I<param> and I<flags> arguments can be ignored in most
-cases)
-
-C<Dup> uses C<Getarg> to retrieve the argument originally passed to
-C<Pushed>, so you must implement this function if your layer has an
-extra argument to C<Pushed> and will ever be C<Dup>ed.
-
-=item Fileno
-
- IV (*Fileno)(pTHX_ PerlIO *f);
-
-Returns the Unix/Posix numeric file descriptor for the handle. Normally
-C<PerlIOBase_fileno()> (which just asks next layer down) will suffice
-for this.
-
-Returns -1 on error, which is considered to include the case where the
-layer cannot provide such a file descriptor.
-
-=item Dup
-
- PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o,
- CLONE_PARAMS *param, int flags);
-
-XXX: Needs more docs.
-
-Used as part of the "clone" process when a thread is spawned (in which
-case param will be non-NULL) and when a stream is being duplicated via
-'&' in the C<open>.
-
-Similar to C<Open>, returns PerlIO* on success, C<NULL> on failure.
-
-=item Read
-
- SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count);
-
-Basic read operation.
-
-Typically will call C<Fill> and manipulate pointers (possibly via the
-API). C<PerlIOBuf_read()> may be suitable for derived classes which
-provide "fast gets" methods.
-
-Returns actual bytes read, or -1 on an error.
-
-=item Unread
-
- SSize_t (*Unread)(pTHX_ PerlIO *f,
- const void *vbuf, Size_t count);
-
-A superset of stdio's C<ungetc()>. Should arrange for future reads to
-see the bytes in C<vbuf>. If there is no obviously better implementation
-then C<PerlIOBase_unread()> provides the function by pushing a "fake"
-"pending" layer above the calling layer.
-
-Returns the number of unread chars.
-
-=item Write
-
- SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count);
-
-Basic write operation.
-
-Returns bytes written or -1 on an error.
-
-=item Seek
-
- IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence);
-
-Position the file pointer. Should normally call its own C<Flush>
-method and then the C<Seek> method of next layer down.
-
-Returns 0 on success, -1 on failure.
-
-=item Tell
-
- Off_t (*Tell)(pTHX_ PerlIO *f);
-
-Return the file pointer. May be based on layers cached concept of
-position to avoid overhead.
-
-Returns -1 on failure to get the file pointer.
-
-=item Close
-
- IV (*Close)(pTHX_ PerlIO *f);
-
-Close the stream. Should normally call C<PerlIOBase_close()> to flush
-itself and close layers below, and then deallocate any data structures
-(buffers, translation tables, ...) not held directly in the data
-structure.
-
-Returns 0 on success, -1 on failure.
-
-=item Flush
-
- IV (*Flush)(pTHX_ PerlIO *f);
-
-Should make stream's state consistent with layers below. That is, any
-buffered write data should be written, and file position of lower layers
-adjusted for data read from below but not actually consumed.
-(Should perhaps C<Unread()> such data to the lower layer.)
-
-Returns 0 on success, -1 on failure.
-
-=item Fill
-
- IV (*Fill)(pTHX_ PerlIO *f);
-
-The buffer for this layer should be filled (for read) from layer
-below. When you "subclass" PerlIOBuf layer, you want to use its
-I<_read> method and to supply your own fill method, which fills the
-PerlIOBuf's buffer.
-
-Returns 0 on success, -1 on failure.
-
-=item Eof
-
- IV (*Eof)(pTHX_ PerlIO *f);
-
-Return end-of-file indicator. C<PerlIOBase_eof()> is normally sufficient.
-
-Returns 0 on end-of-file, 1 if not end-of-file, -1 on error.
-
-=item Error
-
- IV (*Error)(pTHX_ PerlIO *f);
-
-Return error indicator. C<PerlIOBase_error()> is normally sufficient.
-
-Returns 1 if there is an error (usually when C<PERLIO_F_ERROR> is set,
-0 otherwise.
-
-=item Clearerr
-
- void (*Clearerr)(pTHX_ PerlIO *f);
-
-Clear end-of-file and error indicators. Should call C<PerlIOBase_clearerr()>
-to set the C<PERLIO_F_XXXXX> flags, which may suffice.
-
-=item Setlinebuf
-
- void (*Setlinebuf)(pTHX_ PerlIO *f);
-
-Mark the stream as line buffered. C<PerlIOBase_setlinebuf()> sets the
-PERLIO_F_LINEBUF flag and is normally sufficient.
-
-=item Get_base
-
- STDCHAR * (*Get_base)(pTHX_ PerlIO *f);
-
-Allocate (if not already done so) the read buffer for this layer and
-return pointer to it. Return NULL on failure.
-
-=item Get_bufsiz
-
- Size_t (*Get_bufsiz)(pTHX_ PerlIO *f);
-
-Return the number of bytes that last C<Fill()> put in the buffer.
-
-=item Get_ptr
-
- STDCHAR * (*Get_ptr)(pTHX_ PerlIO *f);
-
-Return the current read pointer relative to this layer's buffer.
-
-=item Get_cnt
-
- SSize_t (*Get_cnt)(pTHX_ PerlIO *f);
-
-Return the number of bytes left to be read in the current buffer.
-
-=item Set_ptrcnt
-
- void (*Set_ptrcnt)(pTHX_ PerlIO *f,
- STDCHAR *ptr, SSize_t cnt);
-
-Adjust the read pointer and count of bytes to match C<ptr> and/or C<cnt>.
-The application (or layer above) must ensure they are consistent.
-(Checking is allowed by the paranoid.)
-
-=back
-
-=head2 Utilities
-
-To ask for the next layer down use PerlIONext(PerlIO *f).
-
-To check that a PerlIO* is valid use PerlIOValid(PerlIO *f). (All
-this does is really just to check that the pointer is non-NULL and
-that the pointer behind that is non-NULL.)
-
-PerlIOBase(PerlIO *f) returns the "Base" pointer, or in other words,
-the C<PerlIOl*> pointer.
-
-PerlIOSelf(PerlIO* f, type) return the PerlIOBase cast to a type.
-
-Perl_PerlIO_or_Base(PerlIO* f, callback, base, failure, args) either
-calls the I<callback> from the functions of the layer I<f> (just by
-the name of the IO function, like "Read") with the I<args>, or if
-there is no such callback, calls the I<base> version of the callback
-with the same args, or if the f is invalid, set errno to EBADF and
-return I<failure>.
-
-Perl_PerlIO_or_fail(PerlIO* f, callback, failure, args) either calls
-the I<callback> of the functions of the layer I<f> with the I<args>,
-or if there is no such callback, set errno to EINVAL. Or if the f is
-invalid, set errno to EBADF and return I<failure>.
-
-Perl_PerlIO_or_Base_void(PerlIO* f, callback, base, args) either calls
-the I<callback> of the functions of the layer I<f> with the I<args>,
-or if there is no such callback, calls the I<base> version of the
-callback with the same args, or if the f is invalid, set errno to
-EBADF.
-
-Perl_PerlIO_or_fail_void(PerlIO* f, callback, args) either calls the
-I<callback> of the functions of the layer I<f> with the I<args>, or if
-there is no such callback, set errno to EINVAL. Or if the f is
-invalid, set errno to EBADF.
-
-=head2 Implementing PerlIO Layers
-
-If you find the implementation document unclear or not sufficient,
-look at the existing PerlIO layer implementations, which include:
-
-=over
-
-=item * C implementations
-
-The F<perlio.c> and F<perliol.h> in the Perl core implement the
-"unix", "perlio", "stdio", "crlf", "utf8", "byte", "raw", "pending"
-layers, and also the "mmap" and "win32" layers if applicable.
-(The "win32" is currently unfinished and unused, to see what is used
-instead in Win32, see L<PerlIO/"Querying the layers of filehandles"> .)
-
-PerlIO::encoding, PerlIO::scalar, PerlIO::via in the Perl core.
-
-PerlIO::gzip and APR::PerlIO (mod_perl 2.0) on CPAN.
-
-=item * Perl implementations
-
-PerlIO::via::QuotedPrint in the Perl core and PerlIO::via::* on CPAN.
-
-=back
-
-If you are creating a PerlIO layer, you may want to be lazy, in other
-words, implement only the methods that interest you. The other methods
-you can either replace with the "blank" methods
-
- PerlIOBase_noop_ok
- PerlIOBase_noop_fail
-
-(which do nothing, and return zero and -1, respectively) or for
-certain methods you may assume a default behaviour by using a NULL
-method. The Open method looks for help in the 'parent' layer.
-The following table summarizes the behaviour:
-
- method behaviour with NULL
-
- Clearerr PerlIOBase_clearerr
- Close PerlIOBase_close
- Dup PerlIOBase_dup
- Eof PerlIOBase_eof
- Error PerlIOBase_error
- Fileno PerlIOBase_fileno
- Fill FAILURE
- Flush SUCCESS
- Getarg SUCCESS
- Get_base FAILURE
- Get_bufsiz FAILURE
- Get_cnt FAILURE
- Get_ptr FAILURE
- Open INHERITED
- Popped SUCCESS
- Pushed SUCCESS
- Read PerlIOBase_read
- Seek FAILURE
- Set_cnt FAILURE
- Set_ptrcnt FAILURE
- Setlinebuf PerlIOBase_setlinebuf
- Tell FAILURE
- Unread PerlIOBase_unread
- Write FAILURE
-
- FAILURE Set errno (to EINVAL in Unixish, to LIB$_INVARG in VMS) and
- return -1 (for numeric return values) or NULL (for pointers)
- INHERITED Inherited from the layer below
- SUCCESS Return 0 (for numeric return values) or a pointer
-
-=head2 Core Layers
-
-The file C<perlio.c> provides the following layers:
-
-=over 4
-
-=item "unix"
-
-A basic non-buffered layer which calls Unix/POSIX C<read()>, C<write()>,
-C<lseek()>, C<close()>. No buffering. Even on platforms that distinguish
-between O_TEXT and O_BINARY this layer is always O_BINARY.
-
-=item "perlio"
-
-A very complete generic buffering layer which provides the whole of
-PerlIO API. It is also intended to be used as a "base class" for other
-layers. (For example its C<Read()> method is implemented in terms of
-the C<Get_cnt()>/C<Get_ptr()>/C<Set_ptrcnt()> methods).
-
-"perlio" over "unix" provides a complete replacement for stdio as seen
-via PerlIO API. This is the default for USE_PERLIO when system's stdio
-does not permit perl's "fast gets" access, and which do not
-distinguish between C<O_TEXT> and C<O_BINARY>.
-
-=item "stdio"
-
-A layer which provides the PerlIO API via the layer scheme, but
-implements it by calling system's stdio. This is (currently) the default
-if system's stdio provides sufficient access to allow perl's "fast gets"
-access and which do not distinguish between C<O_TEXT> and C<O_BINARY>.
-
-=item "crlf"
-
-A layer derived using "perlio" as a base class. It provides Win32-like
-"\n" to CR,LF translation. Can either be applied above "perlio" or serve
-as the buffer layer itself. "crlf" over "unix" is the default if system
-distinguishes between C<O_TEXT> and C<O_BINARY> opens. (At some point
-"unix" will be replaced by a "native" Win32 IO layer on that platform,
-as Win32's read/write layer has various drawbacks.) The "crlf" layer is
-a reasonable model for a layer which transforms data in some way.
-
-=item "mmap"
-
-If Configure detects C<mmap()> functions this layer is provided (with
-"perlio" as a "base") which does "read" operations by mmap()ing the
-file. Performance improvement is marginal on modern systems, so it is
-mainly there as a proof of concept. It is likely to be unbundled from
-the core at some point. The "mmap" layer is a reasonable model for a
-minimalist "derived" layer.
-
-=item "pending"
-
-An "internal" derivative of "perlio" which can be used to provide
-Unread() function for layers which have no buffer or cannot be
-bothered. (Basically this layer's C<Fill()> pops itself off the stack
-and so resumes reading from layer below.)
-
-=item "raw"
-
-A dummy layer which never exists on the layer stack. Instead when
-"pushed" it actually pops the stack removing itself, it then calls
-Binmode function table entry on all the layers in the stack - normally
-this (via PerlIOBase_binmode) removes any layers which do not have
-C<PERLIO_K_RAW> bit set. Layers can modify that behaviour by defining
-their own Binmode entry.
-
-=item "utf8"
-
-Another dummy layer. When pushed it pops itself and sets the
-C<PERLIO_F_UTF8> flag on the layer which was (and now is once more)
-the top of the stack.
-
-=back
-
-In addition F<perlio.c> also provides a number of C<PerlIOBase_xxxx()>
-functions which are intended to be used in the table slots of classes
-which do not need to do anything special for a particular method.
-
-=head2 Extension Layers
-
-Layers can be made available by extension modules. When an unknown layer
-is encountered the PerlIO code will perform the equivalent of :
-
- use PerlIO 'layer';
-
-Where I<layer> is the unknown layer. F<PerlIO.pm> will then attempt to:
-
- require PerlIO::layer;
-
-If after that process the layer is still not defined then the C<open>
-will fail.
-
-The following extension layers are bundled with perl:
-
-=over 4
-
-=item ":encoding"
-
- use Encoding;
-
-makes this layer available, although F<PerlIO.pm> "knows" where to
-find it. It is an example of a layer which takes an argument as it is
-called thus:
-
- open( $fh, "<:encoding(iso-8859-7)", $pathname );
-
-=item ":scalar"
-
-Provides support for reading data from and writing data to a scalar.
-
- open( $fh, "+<:scalar", \$scalar );
-
-When a handle is so opened, then reads get bytes from the string value
-of I<$scalar>, and writes change the value. In both cases the position
-in I<$scalar> starts as zero but can be altered via C<seek>, and
-determined via C<tell>.
-
-Please note that this layer is implied when calling open() thus:
-
- open( $fh, "+<", \$scalar );
-
-=item ":via"
-
-Provided to allow layers to be implemented as Perl code. For instance:
-
- use PerlIO::via::StripHTML;
- open( my $fh, "<:via(StripHTML)", "index.html" );
-
-See L<PerlIO::via> for details.
-
-=back
-
-=head1 TODO
-
-Things that need to be done to improve this document.
-
-=over
-
-=item *
-
-Explain how to make a valid fh without going through open()(i.e. apply
-a layer). For example if the file is not opened through perl, but we
-want to get back a fh, like it was opened by Perl.
-
-How PerlIO_apply_layera fits in, where its docs, was it made public?
-
-Currently the example could be something like this:
-
- PerlIO *foo_to_PerlIO(pTHX_ char *mode, ...)
- {
- char *mode; /* "w", "r", etc */
- const char *layers = ":APR"; /* the layer name */
- PerlIO *f = PerlIO_allocate(aTHX);
- if (!f) {
- return NULL;
- }
-
- PerlIO_apply_layers(aTHX_ f, mode, layers);
-
- if (f) {
- PerlIOAPR *st = PerlIOSelf(f, PerlIOAPR);
- /* fill in the st struct, as in _open() */
- st->file = file;
- PerlIOBase(f)->flags |= PERLIO_F_OPEN;
-
- return f;
- }
- return NULL;
- }
-
-=item *
-
-fix/add the documentation in places marked as XXX.
-
-=item *
-
-The handling of errors by the layer is not specified. e.g. when $!
-should be set explicitly, when the error handling should be just
-delegated to the top layer.
-
-Probably give some hints on using SETERRNO() or pointers to where they
-can be found.
-
-=item *
-
-I think it would help to give some concrete examples to make it easier
-to understand the API. Of course I agree that the API has to be
-concise, but since there is no second document that is more of a
-guide, I think that it'd make it easier to start with the doc which is
-an API, but has examples in it in places where things are unclear, to
-a person who is not a PerlIO guru (yet).
-
-=back
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlipc.pod b/Master/tlpkg/tlperl/lib/pods/perlipc.pod
deleted file mode 100644
index 76508388fee..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlipc.pod
+++ /dev/null
@@ -1,1833 +0,0 @@
-=head1 NAME
-
-perlipc - Perl interprocess communication (signals, fifos, pipes, safe subprocesses, sockets, and semaphores)
-
-=head1 DESCRIPTION
-
-The basic IPC facilities of Perl are built out of the good old Unix
-signals, named pipes, pipe opens, the Berkeley socket routines, and SysV
-IPC calls. Each is used in slightly different situations.
-
-=head1 Signals
-
-Perl uses a simple signal handling model: the %SIG hash contains names
-or references of user-installed signal handlers. These handlers will
-be called with an argument which is the name of the signal that
-triggered it. A signal may be generated intentionally from a
-particular keyboard sequence like control-C or control-Z, sent to you
-from another process, or triggered automatically by the kernel when
-special events transpire, like a child process exiting, your own process
-running out of stack space, or hitting a process file-size limit.
-
-For example, to trap an interrupt signal, set up a handler like this:
-
- our $shucks;
-
- sub catch_zap {
- my $signame = shift;
- $shucks++;
- die "Somebody sent me a SIG$signame";
- }
- $SIG{INT} = __PACKAGE__ . "::catch_zap";
- $SIG{INT} = \&catch_zap; # best strategy
-
-Prior to Perl 5.7.3 it was necessary to do as little as you possibly
-could in your handler; notice how all we do is set a global variable
-and then raise an exception. That's because on most systems,
-libraries are not re-entrant; particularly, memory allocation and I/O
-routines are not. That meant that doing nearly I<anything> in your
-handler could in theory trigger a memory fault and subsequent core
-dump - see L</Deferred Signals (Safe Signals)> below.
-
-The names of the signals are the ones listed out by C<kill -l> on your
-system, or you can retrieve them using the CPAN module L<IPC::Signal>.
-
-You may also choose to assign the strings C<"IGNORE"> or C<"DEFAULT"> as
-the handler, in which case Perl will try to discard the signal or do the
-default thing.
-
-On most Unix platforms, the C<CHLD> (sometimes also known as C<CLD>) signal
-has special behavior with respect to a value of C<"IGNORE">.
-Setting C<$SIG{CHLD}> to C<"IGNORE"> on such a platform has the effect of
-not creating zombie processes when the parent process fails to C<wait()>
-on its child processes (i.e., child processes are automatically reaped).
-Calling C<wait()> with C<$SIG{CHLD}> set to C<"IGNORE"> usually returns
-C<-1> on such platforms.
-
-Some signals can be neither trapped nor ignored, such as the KILL and STOP
-(but not the TSTP) signals. Note that ignoring signals makes them disappear.
-If you only want them blocked temporarily without them getting lost you'll
-have to use POSIX' sigprocmask.
-
-Sending a signal to a negative process ID means that you send the signal
-to the entire Unix process group. This code sends a hang-up signal to all
-processes in the current process group, and also sets $SIG{HUP} to C<"IGNORE">
-so it doesn't kill itself:
-
- # block scope for local
- {
- local $SIG{HUP} = "IGNORE";
- kill HUP => -$$;
- # snazzy writing of: kill("HUP", -$$)
- }
-
-Another interesting signal to send is signal number zero. This doesn't
-actually affect a child process, but instead checks whether it's alive
-or has changed its UIDs.
-
- unless (kill 0 => $kid_pid) {
- warn "something wicked happened to $kid_pid";
- }
-
-Signal number zero may fail because you lack permission to send the
-signal when directed at a process whose real or saved UID is not
-identical to the real or effective UID of the sending process, even
-though the process is alive. You may be able to determine the cause of
-failure using C<$!> or C<%!>.
-
- unless (kill(0 => $pid) || $!{EPERM}) {
- warn "$pid looks dead";
- }
-
-You might also want to employ anonymous functions for simple signal
-handlers:
-
- $SIG{INT} = sub { die "\nOutta here!\n" };
-
-SIGCHLD handlers require some special care. If a second child dies
-while in the signal handler caused by the first death, we won't get
-another signal. So must loop here else we will leave the unreaped child
-as a zombie. And the next time two children die we get another zombie.
-And so on.
-
- use POSIX ":sys_wait_h";
- $SIG{CHLD} = sub {
- while ((my $child = waitpid(-1, WNOHANG)) > 0) {
- $Kid_Status{$child} = $?;
- }
- };
- # do something that forks...
-
-Be careful: qx(), system(), and some modules for calling external commands
-do a fork(), then wait() for the result. Thus, your signal handler
-will be called. Because wait() was already called by system() or qx(),
-the wait() in the signal handler will see no more zombies and will
-therefore block.
-
-The best way to prevent this issue is to use waitpid(), as in the following
-example:
-
- use POSIX ":sys_wait_h"; # for nonblocking read
-
- my %children;
-
- $SIG{CHLD} = sub {
- # don't change $! and $? outside handler
- local ($!, $?);
- my $pid = waitpid(-1, WNOHANG);
- return if $pid == -1;
- return unless defined $children{$pid};
- delete $children{$pid};
- cleanup_child($pid, $?);
- };
-
- while (1) {
- my $pid = fork();
- die "cannot fork" unless defined $pid;
- if ($pid == 0) {
- # ...
- exit 0;
- } else {
- $children{$pid}=1;
- # ...
- system($command);
- # ...
- }
- }
-
-Signal handling is also used for timeouts in Unix. While safely
-protected within an C<eval{}> block, you set a signal handler to trap
-alarm signals and then schedule to have one delivered to you in some
-number of seconds. Then try your blocking operation, clearing the alarm
-when it's done but not before you've exited your C<eval{}> block. If it
-goes off, you'll use die() to jump out of the block.
-
-Here's an example:
-
- my $ALARM_EXCEPTION = "alarm clock restart";
- eval {
- local $SIG{ALRM} = sub { die $ALARM_EXCEPTION };
- alarm 10;
- flock(FH, 2) # blocking write lock
- || die "cannot flock: $!";
- alarm 0;
- };
- if ($@ && $@ !~ quotemeta($ALARM_EXCEPTION)) { die }
-
-If the operation being timed out is system() or qx(), this technique
-is liable to generate zombies. If this matters to you, you'll
-need to do your own fork() and exec(), and kill the errant child process.
-
-For more complex signal handling, you might see the standard POSIX
-module. Lamentably, this is almost entirely undocumented, but
-the F<t/lib/posix.t> file from the Perl source distribution has some
-examples in it.
-
-=head2 Handling the SIGHUP Signal in Daemons
-
-A process that usually starts when the system boots and shuts down
-when the system is shut down is called a daemon (Disk And Execution
-MONitor). If a daemon process has a configuration file which is
-modified after the process has been started, there should be a way to
-tell that process to reread its configuration file without stopping
-the process. Many daemons provide this mechanism using a C<SIGHUP>
-signal handler. When you want to tell the daemon to reread the file,
-simply send it the C<SIGHUP> signal.
-
-The following example implements a simple daemon, which restarts
-itself every time the C<SIGHUP> signal is received. The actual code is
-located in the subroutine C<code()>, which just prints some debugging
-info to show that it works; it should be replaced with the real code.
-
- #!/usr/bin/perl -w
-
- use POSIX ();
- use FindBin ();
- use File::Basename ();
- use File::Spec::Functions;
-
- $| = 1;
-
- # make the daemon cross-platform, so exec always calls the script
- # itself with the right path, no matter how the script was invoked.
- my $script = File::Basename::basename($0);
- my $SELF = catfile($FindBin::Bin, $script);
-
- # POSIX unmasks the sigprocmask properly
- $SIG{HUP} = sub {
- print "got SIGHUP\n";
- exec($SELF, @ARGV) || die "$0: couldn't restart: $!";
- };
-
- code();
-
- sub code {
- print "PID: $$\n";
- print "ARGV: @ARGV\n";
- my $count = 0;
- while (++$count) {
- sleep 2;
- print "$count\n";
- }
- }
-
-
-=head2 Deferred Signals (Safe Signals)
-
-Before Perl 5.7.3, installing Perl code to deal with signals exposed you to
-danger from two things. First, few system library functions are
-re-entrant. If the signal interrupts while Perl is executing one function
-(like malloc(3) or printf(3)), and your signal handler then calls the same
-function again, you could get unpredictable behavior--often, a core dump.
-Second, Perl isn't itself re-entrant at the lowest levels. If the signal
-interrupts Perl while Perl is changing its own internal data structures,
-similarly unpredictable behavior may result.
-
-There were two things you could do, knowing this: be paranoid or be
-pragmatic. The paranoid approach was to do as little as possible in your
-signal handler. Set an existing integer variable that already has a
-value, and return. This doesn't help you if you're in a slow system call,
-which will just restart. That means you have to C<die> to longjmp(3) out
-of the handler. Even this is a little cavalier for the true paranoiac,
-who avoids C<die> in a handler because the system I<is> out to get you.
-The pragmatic approach was to say "I know the risks, but prefer the
-convenience", and to do anything you wanted in your signal handler,
-and be prepared to clean up core dumps now and again.
-
-Perl 5.7.3 and later avoid these problems by "deferring" signals. That is,
-when the signal is delivered to the process by the system (to the C code
-that implements Perl) a flag is set, and the handler returns immediately.
-Then at strategic "safe" points in the Perl interpreter (e.g. when it is
-about to execute a new opcode) the flags are checked and the Perl level
-handler from %SIG is executed. The "deferred" scheme allows much more
-flexibility in the coding of signal handlers as we know the Perl
-interpreter is in a safe state, and that we are not in a system library
-function when the handler is called. However the implementation does
-differ from previous Perls in the following ways:
-
-=over 4
-
-=item Long-running opcodes
-
-As the Perl interpreter looks at signal flags only when it is about
-to execute a new opcode, a signal that arrives during a long-running
-opcode (e.g. a regular expression operation on a very large string) will
-not be seen until the current opcode completes.
-
-If a signal of any given type fires multiple times during an opcode
-(such as from a fine-grained timer), the handler for that signal will
-be called only once, after the opcode completes; all other
-instances will be discarded. Furthermore, if your system's signal queue
-gets flooded to the point that there are signals that have been raised
-but not yet caught (and thus not deferred) at the time an opcode
-completes, those signals may well be caught and deferred during
-subsequent opcodes, with sometimes surprising results. For example, you
-may see alarms delivered even after calling C<alarm(0)> as the latter
-stops the raising of alarms but does not cancel the delivery of alarms
-raised but not yet caught. Do not depend on the behaviors described in
-this paragraph as they are side effects of the current implementation and
-may change in future versions of Perl.
-
-=item Interrupting IO
-
-When a signal is delivered (e.g., SIGINT from a control-C) the operating
-system breaks into IO operations like I<read>(2), which is used to
-implement Perl's readline() function, the C<< <> >> operator. On older
-Perls the handler was called immediately (and as C<read> is not "unsafe",
-this worked well). With the "deferred" scheme the handler is I<not> called
-immediately, and if Perl is using the system's C<stdio> library that
-library may restart the C<read> without returning to Perl to give it a
-chance to call the %SIG handler. If this happens on your system the
-solution is to use the C<:perlio> layer to do IO--at least on those handles
-that you want to be able to break into with signals. (The C<:perlio> layer
-checks the signal flags and calls %SIG handlers before resuming IO
-operation.)
-
-The default in Perl 5.7.3 and later is to automatically use
-the C<:perlio> layer.
-
-Note that it is not advisable to access a file handle within a signal
-handler where that signal has interrupted an I/O operation on that same
-handle. While perl will at least try hard not to crash, there are no
-guarantees of data integrity; for example, some data might get dropped or
-written twice.
-
-Some networking library functions like gethostbyname() are known to have
-their own implementations of timeouts which may conflict with your
-timeouts. If you have problems with such functions, try using the POSIX
-sigaction() function, which bypasses Perl safe signals. Be warned that
-this does subject you to possible memory corruption, as described above.
-
-Instead of setting C<$SIG{ALRM}>:
-
- local $SIG{ALRM} = sub { die "alarm" };
-
-try something like the following:
-
- use POSIX qw(SIGALRM);
- POSIX::sigaction(SIGALRM, POSIX::SigAction->new(sub { die "alarm" }))
- || die "Error setting SIGALRM handler: $!\n";
-
-Another way to disable the safe signal behavior locally is to use
-the C<Perl::Unsafe::Signals> module from CPAN, which affects
-all signals.
-
-=item Restartable system calls
-
-On systems that supported it, older versions of Perl used the
-SA_RESTART flag when installing %SIG handlers. This meant that
-restartable system calls would continue rather than returning when
-a signal arrived. In order to deliver deferred signals promptly,
-Perl 5.7.3 and later do I<not> use SA_RESTART. Consequently,
-restartable system calls can fail (with $! set to C<EINTR>) in places
-where they previously would have succeeded.
-
-The default C<:perlio> layer retries C<read>, C<write>
-and C<close> as described above; interrupted C<wait> and
-C<waitpid> calls will always be retried.
-
-=item Signals as "faults"
-
-Certain signals like SEGV, ILL, and BUS are generated by virtual memory
-addressing errors and similar "faults". These are normally fatal: there is
-little a Perl-level handler can do with them. So Perl delivers them
-immediately rather than attempting to defer them.
-
-=item Signals triggered by operating system state
-
-On some operating systems certain signal handlers are supposed to "do
-something" before returning. One example can be CHLD or CLD, which
-indicates a child process has completed. On some operating systems the
-signal handler is expected to C<wait> for the completed child
-process. On such systems the deferred signal scheme will not work for
-those signals: it does not do the C<wait>. Again the failure will
-look like a loop as the operating system will reissue the signal because
-there are completed child processes that have not yet been C<wait>ed for.
-
-=back
-
-If you want the old signal behavior back despite possible
-memory corruption, set the environment variable C<PERL_SIGNALS> to
-C<"unsafe">. This feature first appeared in Perl 5.8.1.
-
-=head1 Named Pipes
-
-A named pipe (often referred to as a FIFO) is an old Unix IPC
-mechanism for processes communicating on the same machine. It works
-just like regular anonymous pipes, except that the
-processes rendezvous using a filename and need not be related.
-
-To create a named pipe, use the C<POSIX::mkfifo()> function.
-
- use POSIX qw(mkfifo);
- mkfifo($path, 0700) || die "mkfifo $path failed: $!";
-
-You can also use the Unix command mknod(1), or on some
-systems, mkfifo(1). These may not be in your normal path, though.
-
- # system return val is backwards, so && not ||
- #
- $ENV{PATH} .= ":/etc:/usr/etc";
- if ( system("mknod", $path, "p")
- && system("mkfifo", $path) )
- {
- die "mk{nod,fifo} $path failed";
- }
-
-
-A fifo is convenient when you want to connect a process to an unrelated
-one. When you open a fifo, the program will block until there's something
-on the other end.
-
-For example, let's say you'd like to have your F<.signature> file be a
-named pipe that has a Perl program on the other end. Now every time any
-program (like a mailer, news reader, finger program, etc.) tries to read
-from that file, the reading program will read the new signature from your
-program. We'll use the pipe-checking file-test operator, B<-p>, to find
-out whether anyone (or anything) has accidentally removed our fifo.
-
- chdir(); # go home
- my $FIFO = ".signature";
-
- while (1) {
- unless (-p $FIFO) {
- unlink $FIFO; # discard any failure, will catch later
- require POSIX; # delayed loading of heavy module
- POSIX::mkfifo($FIFO, 0700)
- || die "can't mkfifo $FIFO: $!";
- }
-
- # next line blocks till there's a reader
- open (FIFO, "> $FIFO") || die "can't open $FIFO: $!";
- print FIFO "John Smith (smith\@host.org)\n", `fortune -s`;
- close(FIFO) || die "can't close $FIFO: $!";
- sleep 2; # to avoid dup signals
- }
-
-=head1 Using open() for IPC
-
-Perl's basic open() statement can also be used for unidirectional
-interprocess communication by either appending or prepending a pipe
-symbol to the second argument to open(). Here's how to start
-something up in a child process you intend to write to:
-
- open(SPOOLER, "| cat -v | lpr -h 2>/dev/null")
- || die "can't fork: $!";
- local $SIG{PIPE} = sub { die "spooler pipe broke" };
- print SPOOLER "stuff\n";
- close SPOOLER || die "bad spool: $! $?";
-
-And here's how to start up a child process you intend to read from:
-
- open(STATUS, "netstat -an 2>&1 |")
- || die "can't fork: $!";
- while (<STATUS>) {
- next if /^(tcp|udp)/;
- print;
- }
- close STATUS || die "bad netstat: $! $?";
-
-If one can be sure that a particular program is a Perl script expecting
-filenames in @ARGV, the clever programmer can write something like this:
-
- % program f1 "cmd1|" - f2 "cmd2|" f3 < tmpfile
-
-and no matter which sort of shell it's called from, the Perl program will
-read from the file F<f1>, the process F<cmd1>, standard input (F<tmpfile>
-in this case), the F<f2> file, the F<cmd2> command, and finally the F<f3>
-file. Pretty nifty, eh?
-
-You might notice that you could use backticks for much the
-same effect as opening a pipe for reading:
-
- print grep { !/^(tcp|udp)/ } `netstat -an 2>&1`;
- die "bad netstatus ($?)" if $?;
-
-While this is true on the surface, it's much more efficient to process the
-file one line or record at a time because then you don't have to read the
-whole thing into memory at once. It also gives you finer control of the
-whole process, letting you kill off the child process early if you'd like.
-
-Be careful to check the return values from both open() and close(). If
-you're I<writing> to a pipe, you should also trap SIGPIPE. Otherwise,
-think of what happens when you start up a pipe to a command that doesn't
-exist: the open() will in all likelihood succeed (it only reflects the
-fork()'s success), but then your output will fail--spectacularly. Perl
-can't know whether the command worked, because your command is actually
-running in a separate process whose exec() might have failed. Therefore,
-while readers of bogus commands return just a quick EOF, writers
-to bogus commands will get hit with a signal, which they'd best be prepared
-to handle. Consider:
-
- open(FH, "|bogus") || die "can't fork: $!";
- print FH "bang\n"; # neither necessary nor sufficient
- # to check print retval!
- close(FH) || die "can't close: $!";
-
-The reason for not checking the return value from print() is because of
-pipe buffering; physical writes are delayed. That won't blow up until the
-close, and it will blow up with a SIGPIPE. To catch it, you could use
-this:
-
- $SIG{PIPE} = "IGNORE";
- open(FH, "|bogus") || die "can't fork: $!";
- print FH "bang\n";
- close(FH) || die "can't close: status=$?";
-
-=head2 Filehandles
-
-Both the main process and any child processes it forks share the same
-STDIN, STDOUT, and STDERR filehandles. If both processes try to access
-them at once, strange things can happen. You may also want to close
-or reopen the filehandles for the child. You can get around this by
-opening your pipe with open(), but on some systems this means that the
-child process cannot outlive the parent.
-
-=head2 Background Processes
-
-You can run a command in the background with:
-
- system("cmd &");
-
-The command's STDOUT and STDERR (and possibly STDIN, depending on your
-shell) will be the same as the parent's. You won't need to catch
-SIGCHLD because of the double-fork taking place; see below for details.
-
-=head2 Complete Dissociation of Child from Parent
-
-In some cases (starting server processes, for instance) you'll want to
-completely dissociate the child process from the parent. This is
-often called daemonization. A well-behaved daemon will also chdir()
-to the root directory so it doesn't prevent unmounting the filesystem
-containing the directory from which it was launched, and redirect its
-standard file descriptors from and to F</dev/null> so that random
-output doesn't wind up on the user's terminal.
-
- use POSIX "setsid";
-
- sub daemonize {
- chdir("/") || die "can't chdir to /: $!";
- open(STDIN, "< /dev/null") || die "can't read /dev/null: $!";
- open(STDOUT, "> /dev/null") || die "can't write to /dev/null: $!";
- defined(my $pid = fork()) || die "can't fork: $!";
- exit if $pid; # non-zero now means I am the parent
- (setsid() != -1) || die "Can't start a new session: $!"
- open(STDERR, ">&STDOUT") || die "can't dup stdout: $!";
- }
-
-The fork() has to come before the setsid() to ensure you aren't a
-process group leader; the setsid() will fail if you are. If your
-system doesn't have the setsid() function, open F</dev/tty> and use the
-C<TIOCNOTTY> ioctl() on it instead. See tty(4) for details.
-
-Non-Unix users should check their C<< I<Your_OS>::Process >> module for
-other possible solutions.
-
-=head2 Safe Pipe Opens
-
-Another interesting approach to IPC is making your single program go
-multiprocess and communicate between--or even amongst--yourselves. The
-open() function will accept a file argument of either C<"-|"> or C<"|-">
-to do a very interesting thing: it forks a child connected to the
-filehandle you've opened. The child is running the same program as the
-parent. This is useful for safely opening a file when running under an
-assumed UID or GID, for example. If you open a pipe I<to> minus, you can
-write to the filehandle you opened and your kid will find it in I<his>
-STDIN. If you open a pipe I<from> minus, you can read from the filehandle
-you opened whatever your kid writes to I<his> STDOUT.
-
- use English qw[ -no_match_vars ];
- my $PRECIOUS = "/path/to/some/safe/file";
- my $sleep_count;
- my $pid;
-
- do {
- $pid = open(KID_TO_WRITE, "|-");
- unless (defined $pid) {
- warn "cannot fork: $!";
- die "bailing out" if $sleep_count++ > 6;
- sleep 10;
- }
- } until defined $pid;
-
- if ($pid) { # I am the parent
- print KID_TO_WRITE @some_data;
- close(KID_TO_WRITE) || warn "kid exited $?";
- } else { # I am the child
- # drop permissions in setuid and/or setgid programs:
- ($EUID, $EGID) = ($UID, $GID);
- open (OUTFILE, "> $PRECIOUS")
- || die "can't open $PRECIOUS: $!";
- while (<STDIN>) {
- print OUTFILE; # child's STDIN is parent's KID_TO_WRITE
- }
- close(OUTFILE) || die "can't close $PRECIOUS: $!";
- exit(0); # don't forget this!!
- }
-
-Another common use for this construct is when you need to execute
-something without the shell's interference. With system(), it's
-straightforward, but you can't use a pipe open or backticks safely.
-That's because there's no way to stop the shell from getting its hands on
-your arguments. Instead, use lower-level control to call exec() directly.
-
-Here's a safe backtick or pipe open for read:
-
- my $pid = open(KID_TO_READ, "-|");
- defined($pid) || die "can't fork: $!";
-
- if ($pid) { # parent
- while (<KID_TO_READ>) {
- # do something interesting
- }
- close(KID_TO_READ) || warn "kid exited $?";
-
- } else { # child
- ($EUID, $EGID) = ($UID, $GID); # suid only
- exec($program, @options, @args)
- || die "can't exec program: $!";
- # NOTREACHED
- }
-
-And here's a safe pipe open for writing:
-
- my $pid = open(KID_TO_WRITE, "|-");
- defined($pid) || die "can't fork: $!";
-
- $SIG{PIPE} = sub { die "whoops, $program pipe broke" };
-
- if ($pid) { # parent
- print KID_TO_WRITE @data;
- close(KID_TO_WRITE) || warn "kid exited $?";
-
- } else { # child
- ($EUID, $EGID) = ($UID, $GID);
- exec($program, @options, @args)
- || die "can't exec program: $!";
- # NOTREACHED
- }
-
-It is very easy to dead-lock a process using this form of open(), or
-indeed with any use of pipe() with multiple subprocesses. The
-example above is "safe" because it is simple and calls exec(). See
-L</"Avoiding Pipe Deadlocks"> for general safety principles, but there
-are extra gotchas with Safe Pipe Opens.
-
-In particular, if you opened the pipe using C<open FH, "|-">, then you
-cannot simply use close() in the parent process to close an unwanted
-writer. Consider this code:
-
- my $pid = open(WRITER, "|-"); # fork open a kid
- defined($pid) || die "first fork failed: $!";
- if ($pid) {
- if (my $sub_pid = fork()) {
- defined($sub_pid) || die "second fork failed: $!";
- close(WRITER) || die "couldn't close WRITER: $!";
- # now do something else...
- }
- else {
- # first write to WRITER
- # ...
- # then when finished
- close(WRITER) || die "couldn't close WRITER: $!";
- exit(0);
- }
- }
- else {
- # first do something with STDIN, then
- exit(0);
- }
-
-In the example above, the true parent does not want to write to the WRITER
-filehandle, so it closes it. However, because WRITER was opened using
-C<open FH, "|-">, it has a special behavior: closing it calls
-waitpid() (see L<perlfunc/waitpid>), which waits for the subprocess
-to exit. If the child process ends up waiting for something happening
-in the section marked "do something else", you have deadlock.
-
-This can also be a problem with intermediate subprocesses in more
-complicated code, which will call waitpid() on all open filehandles
-during global destruction--in no predictable order.
-
-To solve this, you must manually use pipe(), fork(), and the form of
-open() which sets one file descriptor to another, as shown below:
-
- pipe(READER, WRITER) || die "pipe failed: $!";
- $pid = fork();
- defined($pid) || die "first fork failed: $!";
- if ($pid) {
- close READER;
- if (my $sub_pid = fork()) {
- defined($sub_pid) || die "first fork failed: $!";
- close(WRITER) || die "can't close WRITER: $!";
- }
- else {
- # write to WRITER...
- # ...
- # then when finished
- close(WRITER) || die "can't close WRITER: $!";
- exit(0);
- }
- # write to WRITER...
- }
- else {
- open(STDIN, "<&READER") || die "can't reopen STDIN: $!";
- close(WRITER) || die "can't close WRITER: $!";
- # do something...
- exit(0);
- }
-
-Since Perl 5.8.0, you can also use the list form of C<open> for pipes.
-This is preferred when you wish to avoid having the shell interpret
-metacharacters that may be in your command string.
-
-So for example, instead of using:
-
- open(PS_PIPE, "ps aux|") || die "can't open ps pipe: $!";
-
-One would use either of these:
-
- open(PS_PIPE, "-|", "ps", "aux")
- || die "can't open ps pipe: $!";
-
- @ps_args = qw[ ps aux ];
- open(PS_PIPE, "-|", @ps_args)
- || die "can't open @ps_args|: $!";
-
-Because there are more than three arguments to open(), forks the ps(1)
-command I<without> spawning a shell, and reads its standard output via the
-C<PS_PIPE> filehandle. The corresponding syntax to I<write> to command
-pipes is to use C<"|-"> in place of C<"-|">.
-
-This was admittedly a rather silly example, because you're using string
-literals whose content is perfectly safe. There is therefore no cause to
-resort to the harder-to-read, multi-argument form of pipe open(). However,
-whenever you cannot be assured that the program arguments are free of shell
-metacharacters, the fancier form of open() should be used. For example:
-
- @grep_args = ("egrep", "-i", $some_pattern, @many_files);
- open(GREP_PIPE, "-|", @grep_args)
- || die "can't open @grep_args|: $!";
-
-Here the multi-argument form of pipe open() is preferred because the
-pattern and indeed even the filenames themselves might hold metacharacters.
-
-Be aware that these operations are full Unix forks, which means they may
-not be correctly implemented on all alien systems. Additionally, these are
-not true multithreading. To learn more about threading, see the F<modules>
-file mentioned below in the SEE ALSO section.
-
-=head2 Avoiding Pipe Deadlocks
-
-Whenever you have more than one subprocess, you must be careful that each
-closes whichever half of any pipes created for interprocess communication
-it is not using. This is because any child process reading from the pipe
-and expecting an EOF will never receive it, and therefore never exit. A
-single process closing a pipe is not enough to close it; the last process
-with the pipe open must close it for it to read EOF.
-
-Certain built-in Unix features help prevent this most of the time. For
-instance, filehandles have a "close on exec" flag, which is set I<en masse>
-under control of the C<$^F> variable. This is so any filehandles you
-didn't explicitly route to the STDIN, STDOUT or STDERR of a child
-I<program> will be automatically closed.
-
-Always explicitly and immediately call close() on the writable end of any
-pipe, unless that process is actually writing to it. Even if you don't
-explicitly call close(), Perl will still close() all filehandles during
-global destruction. As previously discussed, if those filehandles have
-been opened with Safe Pipe Open, this will result in calling waitpid(),
-which may again deadlock.
-
-=head2 Bidirectional Communication with Another Process
-
-While this works reasonably well for unidirectional communication, what
-about bidirectional communication? The most obvious approach doesn't work:
-
- # THIS DOES NOT WORK!!
- open(PROG_FOR_READING_AND_WRITING, "| some program |")
-
-If you forget to C<use warnings>, you'll miss out entirely on the
-helpful diagnostic message:
-
- Can't do bidirectional pipe at -e line 1.
-
-If you really want to, you can use the standard open2() from the
-C<IPC::Open2> module to catch both ends. There's also an open3() in
-C<IPC::Open3> for tridirectional I/O so you can also catch your child's
-STDERR, but doing so would then require an awkward select() loop and
-wouldn't allow you to use normal Perl input operations.
-
-If you look at its source, you'll see that open2() uses low-level
-primitives like the pipe() and exec() syscalls to create all the
-connections. Although it might have been more efficient by using
-socketpair(), this would have been even less portable than it already
-is. The open2() and open3() functions are unlikely to work anywhere
-except on a Unix system, or at least one purporting POSIX compliance.
-
-=for TODO
-Hold on, is this even true? First it says that socketpair() is avoided
-for portability, but then it says it probably won't work except on
-Unixy systems anyway. Which one of those is true?
-
-Here's an example of using open2():
-
- use FileHandle;
- use IPC::Open2;
- $pid = open2(*Reader, *Writer, "cat -un");
- print Writer "stuff\n";
- $got = <Reader>;
-
-The problem with this is that buffering is really going to ruin your
-day. Even though your C<Writer> filehandle is auto-flushed so the process
-on the other end gets your data in a timely manner, you can't usually do
-anything to force that process to give its data to you in a similarly quick
-fashion. In this special case, we could actually so, because we gave
-I<cat> a B<-u> flag to make it unbuffered. But very few commands are
-designed to operate over pipes, so this seldom works unless you yourself
-wrote the program on the other end of the double-ended pipe.
-
-A solution to this is to use a library which uses pseudottys to make your
-program behave more reasonably. This way you don't have to have control
-over the source code of the program you're using. The C<Expect> module
-from CPAN also addresses this kind of thing. This module requires two
-other modules from CPAN, C<IO::Pty> and C<IO::Stty>. It sets up a pseudo
-terminal to interact with programs that insist on talking to the terminal
-device driver. If your system is supported, this may be your best bet.
-
-=head2 Bidirectional Communication with Yourself
-
-If you want, you may make low-level pipe() and fork() syscalls to stitch
-this together by hand. This example only talks to itself, but you could
-reopen the appropriate handles to STDIN and STDOUT and call other processes.
-(The following example lacks proper error checking.)
-
- #!/usr/bin/perl -w
- # pipe1 - bidirectional communication using two pipe pairs
- # designed for the socketpair-challenged
- use IO::Handle; # thousands of lines just for autoflush :-(
- pipe(PARENT_RDR, CHILD_WTR); # XXX: check failure?
- pipe(CHILD_RDR, PARENT_WTR); # XXX: check failure?
- CHILD_WTR->autoflush(1);
- PARENT_WTR->autoflush(1);
-
- if ($pid = fork()) {
- close PARENT_RDR;
- close PARENT_WTR;
- print CHILD_WTR "Parent Pid $$ is sending this\n";
- chomp($line = <CHILD_RDR>);
- print "Parent Pid $$ just read this: '$line'\n";
- close CHILD_RDR; close CHILD_WTR;
- waitpid($pid, 0);
- } else {
- die "cannot fork: $!" unless defined $pid;
- close CHILD_RDR;
- close CHILD_WTR;
- chomp($line = <PARENT_RDR>);
- print "Child Pid $$ just read this: '$line'\n";
- print PARENT_WTR "Child Pid $$ is sending this\n";
- close PARENT_RDR;
- close PARENT_WTR;
- exit(0);
- }
-
-But you don't actually have to make two pipe calls. If you
-have the socketpair() system call, it will do this all for you.
-
- #!/usr/bin/perl -w
- # pipe2 - bidirectional communication using socketpair
- # "the best ones always go both ways"
-
- use Socket;
- use IO::Handle; # thousands of lines just for autoflush :-(
-
- # We say AF_UNIX because although *_LOCAL is the
- # POSIX 1003.1g form of the constant, many machines
- # still don't have it.
- socketpair(CHILD, PARENT, AF_UNIX, SOCK_STREAM, PF_UNSPEC)
- || die "socketpair: $!";
-
- CHILD->autoflush(1);
- PARENT->autoflush(1);
-
- if ($pid = fork()) {
- close PARENT;
- print CHILD "Parent Pid $$ is sending this\n";
- chomp($line = <CHILD>);
- print "Parent Pid $$ just read this: '$line'\n";
- close CHILD;
- waitpid($pid, 0);
- } else {
- die "cannot fork: $!" unless defined $pid;
- close CHILD;
- chomp($line = <PARENT>);
- print "Child Pid $$ just read this: '$line'\n";
- print PARENT "Child Pid $$ is sending this\n";
- close PARENT;
- exit(0);
- }
-
-=head1 Sockets: Client/Server Communication
-
-While not entirely limited to Unix-derived operating systems (e.g., WinSock
-on PCs provides socket support, as do some VMS libraries), you might not have
-sockets on your system, in which case this section probably isn't going to
-do you much good. With sockets, you can do both virtual circuits like TCP
-streams and datagrams like UDP packets. You may be able to do even more
-depending on your system.
-
-The Perl functions for dealing with sockets have the same names as
-the corresponding system calls in C, but their arguments tend to differ
-for two reasons. First, Perl filehandles work differently than C file
-descriptors. Second, Perl already knows the length of its strings, so you
-don't need to pass that information.
-
-One of the major problems with ancient, antemillennial socket code in Perl
-was that it used hard-coded values for some of the constants, which
-severely hurt portability. If you ever see code that does anything like
-explicitly setting C<$AF_INET = 2>, you know you're in for big trouble.
-An immeasurably superior approach is to use the C<Socket> module, which more
-reliably grants access to the various constants and functions you'll need.
-
-If you're not writing a server/client for an existing protocol like
-NNTP or SMTP, you should give some thought to how your server will
-know when the client has finished talking, and vice-versa. Most
-protocols are based on one-line messages and responses (so one party
-knows the other has finished when a "\n" is received) or multi-line
-messages and responses that end with a period on an empty line
-("\n.\n" terminates a message/response).
-
-=head2 Internet Line Terminators
-
-The Internet line terminator is "\015\012". Under ASCII variants of
-Unix, that could usually be written as "\r\n", but under other systems,
-"\r\n" might at times be "\015\015\012", "\012\012\015", or something
-completely different. The standards specify writing "\015\012" to be
-conformant (be strict in what you provide), but they also recommend
-accepting a lone "\012" on input (be lenient in what you require).
-We haven't always been very good about that in the code in this manpage,
-but unless you're on a Mac from way back in its pre-Unix dark ages, you'll
-probably be ok.
-
-=head2 Internet TCP Clients and Servers
-
-Use Internet-domain sockets when you want to do client-server
-communication that might extend to machines outside of your own system.
-
-Here's a sample TCP client using Internet-domain sockets:
-
- #!/usr/bin/perl -w
- use strict;
- use Socket;
- my ($remote, $port, $iaddr, $paddr, $proto, $line);
-
- $remote = shift || "localhost";
- $port = shift || 2345; # random port
- if ($port =~ /\D/) { $port = getservbyname($port, "tcp") }
- die "No port" unless $port;
- $iaddr = inet_aton($remote) || die "no host: $remote";
- $paddr = sockaddr_in($port, $iaddr);
-
- $proto = getprotobyname("tcp");
- socket(SOCK, PF_INET, SOCK_STREAM, $proto) || die "socket: $!";
- connect(SOCK, $paddr) || die "connect: $!";
- while ($line = <SOCK>) {
- print $line;
- }
-
- close (SOCK) || die "close: $!";
- exit(0);
-
-And here's a corresponding server to go along with it. We'll
-leave the address as C<INADDR_ANY> so that the kernel can choose
-the appropriate interface on multihomed hosts. If you want sit
-on a particular interface (like the external side of a gateway
-or firewall machine), fill this in with your real address instead.
-
- #!/usr/bin/perl -Tw
- use strict;
- BEGIN { $ENV{PATH} = "/usr/bin:/bin" }
- use Socket;
- use Carp;
- my $EOL = "\015\012";
-
- sub logmsg { print "$0 $$: @_ at ", scalar localtime(), "\n" }
-
- my $port = shift || 2345;
- die "invalid port" unless if $port =~ /^ \d+ $/x;
-
- my $proto = getprotobyname("tcp");
-
- socket(Server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!";
- setsockopt(Server, SOL_SOCKET, SO_REUSEADDR, pack("l", 1))
- || die "setsockopt: $!";
- bind(Server, sockaddr_in($port, INADDR_ANY)) || die "bind: $!";
- listen(Server, SOMAXCONN) || die "listen: $!";
-
- logmsg "server started on port $port";
-
- my $paddr;
-
- $SIG{CHLD} = \&REAPER;
-
- for ( ; $paddr = accept(Client, Server); close Client) {
- my($port, $iaddr) = sockaddr_in($paddr);
- my $name = gethostbyaddr($iaddr, AF_INET);
-
- logmsg "connection from $name [",
- inet_ntoa($iaddr), "]
- at port $port";
-
- print Client "Hello there, $name, it's now ",
- scalar localtime(), $EOL;
- }
-
-And here's a multithreaded version. It's multithreaded in that
-like most typical servers, it spawns (fork()s) a slave server to
-handle the client request so that the master server can quickly
-go back to service a new client.
-
- #!/usr/bin/perl -Tw
- use strict;
- BEGIN { $ENV{PATH} = "/usr/bin:/bin" }
- use Socket;
- use Carp;
- my $EOL = "\015\012";
-
- sub spawn; # forward declaration
- sub logmsg { print "$0 $$: @_ at ", scalar localtime(), "\n" }
-
- my $port = shift || 2345;
- die "invalid port" unless if $port =~ /^ \d+ $/x;
-
- my $proto = getprotobyname("tcp");
-
- socket(Server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!";
- setsockopt(Server, SOL_SOCKET, SO_REUSEADDR, pack("l", 1))
- || die "setsockopt: $!";
- bind(Server, sockaddr_in($port, INADDR_ANY)) || die "bind: $!";
- listen(Server, SOMAXCONN) || die "listen: $!";
-
- logmsg "server started on port $port";
-
- my $waitedpid = 0;
- my $paddr;
-
- use POSIX ":sys_wait_h";
- use Errno;
-
- sub REAPER {
- local $!; # don't let waitpid() overwrite current error
- while ((my $pid = waitpid(-1, WNOHANG)) > 0 && WIFEXITED($?)) {
- logmsg "reaped $waitedpid" . ($? ? " with exit $?" : "");
- }
- $SIG{CHLD} = \&REAPER; # loathe SysV
- }
-
- $SIG{CHLD} = \&REAPER;
-
- while (1) {
- $paddr = accept(Client, Server) || do {
- # try again if accept() returned because got a signal
- next if $!{EINTR};
- die "accept: $!";
- };
- my ($port, $iaddr) = sockaddr_in($paddr);
- my $name = gethostbyaddr($iaddr, AF_INET);
-
- logmsg "connection from $name [",
- inet_ntoa($iaddr),
- "] at port $port";
-
- spawn sub {
- $| = 1;
- print "Hello there, $name, it's now ", scalar localtime(), $EOL;
- exec "/usr/games/fortune" # XXX: "wrong" line terminators
- or confess "can't exec fortune: $!";
- };
- close Client;
- }
-
- sub spawn {
- my $coderef = shift;
-
- unless (@_ == 0 && $coderef && ref($coderef) eq "CODE") {
- confess "usage: spawn CODEREF";
- }
-
- my $pid;
- unless (defined($pid = fork())) {
- logmsg "cannot fork: $!";
- return;
- }
- elsif ($pid) {
- logmsg "begat $pid";
- return; # I'm the parent
- }
- # else I'm the child -- go spawn
-
- open(STDIN, "<&Client") || die "can't dup client to stdin";
- open(STDOUT, ">&Client") || die "can't dup client to stdout";
- ## open(STDERR, ">&STDOUT") || die "can't dup stdout to stderr";
- exit($coderef->());
- }
-
-This server takes the trouble to clone off a child version via fork()
-for each incoming request. That way it can handle many requests at
-once, which you might not always want. Even if you don't fork(), the
-listen() will allow that many pending connections. Forking servers
-have to be particularly careful about cleaning up their dead children
-(called "zombies" in Unix parlance), because otherwise you'll quickly
-fill up your process table. The REAPER subroutine is used here to
-call waitpid() for any child processes that have finished, thereby
-ensuring that they terminate cleanly and don't join the ranks of the
-living dead.
-
-Within the while loop we call accept() and check to see if it returns
-a false value. This would normally indicate a system error needs
-to be reported. However, the introduction of safe signals (see
-L</Deferred Signals (Safe Signals)> above) in Perl 5.7.3 means that
-accept() might also be interrupted when the process receives a signal.
-This typically happens when one of the forked subprocesses exits and
-notifies the parent process with a CHLD signal.
-
-If accept() is interrupted by a signal, $! will be set to EINTR.
-If this happens, we can safely continue to the next iteration of
-the loop and another call to accept(). It is important that your
-signal handling code not modify the value of $!, or else this test
-will likely fail. In the REAPER subroutine we create a local version
-of $! before calling waitpid(). When waitpid() sets $! to ECHILD as
-it inevitably does when it has no more children waiting, it
-updates the local copy and leaves the original unchanged.
-
-You should use the B<-T> flag to enable taint checking (see L<perlsec>)
-even if we aren't running setuid or setgid. This is always a good idea
-for servers or any program run on behalf of someone else (like CGI
-scripts), because it lessens the chances that people from the outside will
-be able to compromise your system.
-
-Let's look at another TCP client. This one connects to the TCP "time"
-service on a number of different machines and shows how far their clocks
-differ from the system on which it's being run:
-
- #!/usr/bin/perl -w
- use strict;
- use Socket;
-
- my $SECS_OF_70_YEARS = 2208988800;
- sub ctime { scalar localtime(shift() || time()) }
-
- my $iaddr = gethostbyname("localhost");
- my $proto = getprotobyname("tcp");
- my $port = getservbyname("time", "tcp");
- my $paddr = sockaddr_in(0, $iaddr);
- my($host);
-
- $| = 1;
- printf "%-24s %8s %s\n", "localhost", 0, ctime();
-
- foreach $host (@ARGV) {
- printf "%-24s ", $host;
- my $hisiaddr = inet_aton($host) || die "unknown host";
- my $hispaddr = sockaddr_in($port, $hisiaddr);
- socket(SOCKET, PF_INET, SOCK_STREAM, $proto)
- || die "socket: $!";
- connect(SOCKET, $hispaddr) || die "connect: $!";
- my $rtime = pack("C4", ());
- read(SOCKET, $rtime, 4);
- close(SOCKET);
- my $histime = unpack("N", $rtime) - $SECS_OF_70_YEARS;
- printf "%8d %s\n", $histime - time(), ctime($histime);
- }
-
-=head2 Unix-Domain TCP Clients and Servers
-
-That's fine for Internet-domain clients and servers, but what about local
-communications? While you can use the same setup, sometimes you don't
-want to. Unix-domain sockets are local to the current host, and are often
-used internally to implement pipes. Unlike Internet domain sockets, Unix
-domain sockets can show up in the file system with an ls(1) listing.
-
- % ls -l /dev/log
- srw-rw-rw- 1 root 0 Oct 31 07:23 /dev/log
-
-You can test for these with Perl's B<-S> file test:
-
- unless (-S "/dev/log") {
- die "something's wicked with the log system";
- }
-
-Here's a sample Unix-domain client:
-
- #!/usr/bin/perl -w
- use Socket;
- use strict;
- my ($rendezvous, $line);
-
- $rendezvous = shift || "catsock";
- socket(SOCK, PF_UNIX, SOCK_STREAM, 0) || die "socket: $!";
- connect(SOCK, sockaddr_un($rendezvous)) || die "connect: $!";
- while (defined($line = <SOCK>)) {
- print $line;
- }
- exit(0);
-
-And here's a corresponding server. You don't have to worry about silly
-network terminators here because Unix domain sockets are guaranteed
-to be on the localhost, and thus everything works right.
-
- #!/usr/bin/perl -Tw
- use strict;
- use Socket;
- use Carp;
-
- BEGIN { $ENV{PATH} = "/usr/bin:/bin" }
- sub spawn; # forward declaration
- sub logmsg { print "$0 $$: @_ at ", scalar localtime(), "\n" }
-
- my $NAME = "catsock";
- my $uaddr = sockaddr_un($NAME);
- my $proto = getprotobyname("tcp");
-
- socket(Server, PF_UNIX, SOCK_STREAM, 0) || die "socket: $!";
- unlink($NAME);
- bind (Server, $uaddr) || die "bind: $!";
- listen(Server, SOMAXCONN) || die "listen: $!";
-
- logmsg "server started on $NAME";
-
- my $waitedpid;
-
- use POSIX ":sys_wait_h";
- sub REAPER {
- my $child;
- while (($waitedpid = waitpid(-1, WNOHANG)) > 0) {
- logmsg "reaped $waitedpid" . ($? ? " with exit $?" : "");
- }
- $SIG{CHLD} = \&REAPER; # loathe SysV
- }
-
- $SIG{CHLD} = \&REAPER;
-
-
- for ( $waitedpid = 0;
- accept(Client, Server) || $waitedpid;
- $waitedpid = 0, close Client)
- {
- next if $waitedpid;
- logmsg "connection on $NAME";
- spawn sub {
- print "Hello there, it's now ", scalar localtime(), "\n";
- exec("/usr/games/fortune") || die "can't exec fortune: $!";
- };
- }
-
- sub spawn {
- my $coderef = shift();
-
- unless (@_ == 0 && $coderef && ref($coderef) eq "CODE") {
- confess "usage: spawn CODEREF";
- }
-
- my $pid;
- unless (defined($pid = fork())) {
- logmsg "cannot fork: $!";
- return;
- }
- elsif ($pid) {
- logmsg "begat $pid";
- return; # I'm the parent
- }
- else {
- # I'm the child -- go spawn
- }
-
- open(STDIN, "<&Client") || die "can't dup client to stdin";
- open(STDOUT, ">&Client") || die "can't dup client to stdout";
- ## open(STDERR, ">&STDOUT") || die "can't dup stdout to stderr";
- exit($coderef->());
- }
-
-As you see, it's remarkably similar to the Internet domain TCP server, so
-much so, in fact, that we've omitted several duplicate functions--spawn(),
-logmsg(), ctime(), and REAPER()--which are the same as in the other server.
-
-So why would you ever want to use a Unix domain socket instead of a
-simpler named pipe? Because a named pipe doesn't give you sessions. You
-can't tell one process's data from another's. With socket programming,
-you get a separate session for each client; that's why accept() takes two
-arguments.
-
-For example, let's say that you have a long-running database server daemon
-that you want folks to be able to access from the Web, but only
-if they go through a CGI interface. You'd have a small, simple CGI
-program that does whatever checks and logging you feel like, and then acts
-as a Unix-domain client and connects to your private server.
-
-=head1 TCP Clients with IO::Socket
-
-For those preferring a higher-level interface to socket programming, the
-IO::Socket module provides an object-oriented approach. IO::Socket has
-been included in the standard Perl distribution ever since Perl 5.004. If
-you're running an earlier version of Perl (in which case, how are you
-reading this manpage?), just fetch IO::Socket from CPAN, where you'll also
-find modules providing easy interfaces to the following systems: DNS, FTP,
-Ident (RFC 931), NIS and NISPlus, NNTP, Ping, POP3, SMTP, SNMP, SSLeay,
-Telnet, and Time--to name just a few.
-
-=head2 A Simple Client
-
-Here's a client that creates a TCP connection to the "daytime"
-service at port 13 of the host name "localhost" and prints out everything
-that the server there cares to provide.
-
- #!/usr/bin/perl -w
- use IO::Socket;
- $remote = IO::Socket::INET->new(
- Proto => "tcp",
- PeerAddr => "localhost",
- PeerPort => "daytime(13)",
- )
- || die "can't connect to daytime service on localhost";
- while (<$remote>) { print }
-
-When you run this program, you should get something back that
-looks like this:
-
- Wed May 14 08:40:46 MDT 1997
-
-Here are what those parameters to the new() constructor mean:
-
-=over 4
-
-=item C<Proto>
-
-This is which protocol to use. In this case, the socket handle returned
-will be connected to a TCP socket, because we want a stream-oriented
-connection, that is, one that acts pretty much like a plain old file.
-Not all sockets are this of this type. For example, the UDP protocol
-can be used to make a datagram socket, used for message-passing.
-
-=item C<PeerAddr>
-
-This is the name or Internet address of the remote host the server is
-running on. We could have specified a longer name like C<"www.perl.com">,
-or an address like C<"207.171.7.72">. For demonstration purposes, we've
-used the special hostname C<"localhost">, which should always mean the
-current machine you're running on. The corresponding Internet address
-for localhost is C<"127.0.0.1">, if you'd rather use that.
-
-=item C<PeerPort>
-
-This is the service name or port number we'd like to connect to.
-We could have gotten away with using just C<"daytime"> on systems with a
-well-configured system services file,[FOOTNOTE: The system services file
-is found in I</etc/services> under Unixy systems.] but here we've specified the
-port number (13) in parentheses. Using just the number would have also
-worked, but numeric literals make careful programmers nervous.
-
-=back
-
-Notice how the return value from the C<new> constructor is used as
-a filehandle in the C<while> loop? That's what's called an I<indirect
-filehandle>, a scalar variable containing a filehandle. You can use
-it the same way you would a normal filehandle. For example, you
-can read one line from it this way:
-
- $line = <$handle>;
-
-all remaining lines from is this way:
-
- @lines = <$handle>;
-
-and send a line of data to it this way:
-
- print $handle "some data\n";
-
-=head2 A Webget Client
-
-Here's a simple client that takes a remote host to fetch a document
-from, and then a list of files to get from that host. This is a
-more interesting client than the previous one because it first sends
-something to the server before fetching the server's response.
-
- #!/usr/bin/perl -w
- use IO::Socket;
- unless (@ARGV > 1) { die "usage: $0 host url ..." }
- $host = shift(@ARGV);
- $EOL = "\015\012";
- $BLANK = $EOL x 2;
- for my $document (@ARGV) {
- $remote = IO::Socket::INET->new( Proto => "tcp",
- PeerAddr => $host,
- PeerPort => "http(80)",
- ) || die "cannot connect to httpd on $host";
- $remote->autoflush(1);
- print $remote "GET $document HTTP/1.0" . $BLANK;
- while ( <$remote> ) { print }
- close $remote;
- }
-
-The web server handling the HTTP service is assumed to be at
-its standard port, number 80. If the server you're trying to
-connect to is at a different port, like 1080 or 8080, you should specify it
-as the named-parameter pair, C<< PeerPort => 8080 >>. The C<autoflush>
-method is used on the socket because otherwise the system would buffer
-up the output we sent it. (If you're on a prehistoric Mac, you'll also
-need to change every C<"\n"> in your code that sends data over the network
-to be a C<"\015\012"> instead.)
-
-Connecting to the server is only the first part of the process: once you
-have the connection, you have to use the server's language. Each server
-on the network has its own little command language that it expects as
-input. The string that we send to the server starting with "GET" is in
-HTTP syntax. In this case, we simply request each specified document.
-Yes, we really are making a new connection for each document, even though
-it's the same host. That's the way you always used to have to speak HTTP.
-Recent versions of web browsers may request that the remote server leave
-the connection open a little while, but the server doesn't have to honor
-such a request.
-
-Here's an example of running that program, which we'll call I<webget>:
-
- % webget www.perl.com /guanaco.html
- HTTP/1.1 404 File Not Found
- Date: Thu, 08 May 1997 18:02:32 GMT
- Server: Apache/1.2b6
- Connection: close
- Content-type: text/html
-
- <HEAD><TITLE>404 File Not Found</TITLE></HEAD>
- <BODY><H1>File Not Found</H1>
- The requested URL /guanaco.html was not found on this server.<P>
- </BODY>
-
-Ok, so that's not very interesting, because it didn't find that
-particular document. But a long response wouldn't have fit on this page.
-
-For a more featureful version of this program, you should look to
-the I<lwp-request> program included with the LWP modules from CPAN.
-
-=head2 Interactive Client with IO::Socket
-
-Well, that's all fine if you want to send one command and get one answer,
-but what about setting up something fully interactive, somewhat like
-the way I<telnet> works? That way you can type a line, get the answer,
-type a line, get the answer, etc.
-
-This client is more complicated than the two we've done so far, but if
-you're on a system that supports the powerful C<fork> call, the solution
-isn't that rough. Once you've made the connection to whatever service
-you'd like to chat with, call C<fork> to clone your process. Each of
-these two identical process has a very simple job to do: the parent
-copies everything from the socket to standard output, while the child
-simultaneously copies everything from standard input to the socket.
-To accomplish the same thing using just one process would be I<much>
-harder, because it's easier to code two processes to do one thing than it
-is to code one process to do two things. (This keep-it-simple principle
-a cornerstones of the Unix philosophy, and good software engineering as
-well, which is probably why it's spread to other systems.)
-
-Here's the code:
-
- #!/usr/bin/perl -w
- use strict;
- use IO::Socket;
- my ($host, $port, $kidpid, $handle, $line);
-
- unless (@ARGV == 2) { die "usage: $0 host port" }
- ($host, $port) = @ARGV;
-
- # create a tcp connection to the specified host and port
- $handle = IO::Socket::INET->new(Proto => "tcp",
- PeerAddr => $host,
- PeerPort => $port)
- || die "can't connect to port $port on $host: $!";
-
- $handle->autoflush(1); # so output gets there right away
- print STDERR "[Connected to $host:$port]\n";
-
- # split the program into two processes, identical twins
- die "can't fork: $!" unless defined($kidpid = fork());
-
- # the if{} block runs only in the parent process
- if ($kidpid) {
- # copy the socket to standard output
- while (defined ($line = <$handle>)) {
- print STDOUT $line;
- }
- kill("TERM", $kidpid); # send SIGTERM to child
- }
- # the else{} block runs only in the child process
- else {
- # copy standard input to the socket
- while (defined ($line = <STDIN>)) {
- print $handle $line;
- }
- exit(0); # just in case
- }
-
-The C<kill> function in the parent's C<if> block is there to send a
-signal to our child process, currently running in the C<else> block,
-as soon as the remote server has closed its end of the connection.
-
-If the remote server sends data a byte at time, and you need that
-data immediately without waiting for a newline (which might not happen),
-you may wish to replace the C<while> loop in the parent with the
-following:
-
- my $byte;
- while (sysread($handle, $byte, 1) == 1) {
- print STDOUT $byte;
- }
-
-Making a system call for each byte you want to read is not very efficient
-(to put it mildly) but is the simplest to explain and works reasonably
-well.
-
-=head1 TCP Servers with IO::Socket
-
-As always, setting up a server is little bit more involved than running a client.
-The model is that the server creates a special kind of socket that
-does nothing but listen on a particular port for incoming connections.
-It does this by calling the C<< IO::Socket::INET->new() >> method with
-slightly different arguments than the client did.
-
-=over 4
-
-=item Proto
-
-This is which protocol to use. Like our clients, we'll
-still specify C<"tcp"> here.
-
-=item LocalPort
-
-We specify a local
-port in the C<LocalPort> argument, which we didn't do for the client.
-This is service name or port number for which you want to be the
-server. (Under Unix, ports under 1024 are restricted to the
-superuser.) In our sample, we'll use port 9000, but you can use
-any port that's not currently in use on your system. If you try
-to use one already in used, you'll get an "Address already in use"
-message. Under Unix, the C<netstat -a> command will show
-which services current have servers.
-
-=item Listen
-
-The C<Listen> parameter is set to the maximum number of
-pending connections we can accept until we turn away incoming clients.
-Think of it as a call-waiting queue for your telephone.
-The low-level Socket module has a special symbol for the system maximum, which
-is SOMAXCONN.
-
-=item Reuse
-
-The C<Reuse> parameter is needed so that we restart our server
-manually without waiting a few minutes to allow system buffers to
-clear out.
-
-=back
-
-Once the generic server socket has been created using the parameters
-listed above, the server then waits for a new client to connect
-to it. The server blocks in the C<accept> method, which eventually accepts a
-bidirectional connection from the remote client. (Make sure to autoflush
-this handle to circumvent buffering.)
-
-To add to user-friendliness, our server prompts the user for commands.
-Most servers don't do this. Because of the prompt without a newline,
-you'll have to use the C<sysread> variant of the interactive client above.
-
-This server accepts one of five different commands, sending output back to
-the client. Unlike most network servers, this one handles only one
-incoming client at a time. Multithreaded servers are covered in
-Chapter 16 of the Camel.
-
-Here's the code. We'll
-
- #!/usr/bin/perl -w
- use IO::Socket;
- use Net::hostent; # for OOish version of gethostbyaddr
-
- $PORT = 9000; # pick something not in use
-
- $server = IO::Socket::INET->new( Proto => "tcp",
- LocalPort => $PORT,
- Listen => SOMAXCONN,
- Reuse => 1);
-
- die "can't setup server" unless $server;
- print "[Server $0 accepting clients]\n";
-
- while ($client = $server->accept()) {
- $client->autoflush(1);
- print $client "Welcome to $0; type help for command list.\n";
- $hostinfo = gethostbyaddr($client->peeraddr);
- printf "[Connect from %s]\n", $hostinfo ? $hostinfo->name : $client->peerhost;
- print $client "Command? ";
- while ( <$client>) {
- next unless /\S/; # blank line
- if (/quit|exit/i) { last }
- elsif (/date|time/i) { printf $client "%s\n", scalar localtime() }
- elsif (/who/i ) { print $client `who 2>&1` }
- elsif (/cookie/i ) { print $client `/usr/games/fortune 2>&1` }
- elsif (/motd/i ) { print $client `cat /etc/motd 2>&1` }
- else {
- print $client "Commands: quit date who cookie motd\n";
- }
- } continue {
- print $client "Command? ";
- }
- close $client;
- }
-
-=head1 UDP: Message Passing
-
-Another kind of client-server setup is one that uses not connections, but
-messages. UDP communications involve much lower overhead but also provide
-less reliability, as there are no promises that messages will arrive at
-all, let alone in order and unmangled. Still, UDP offers some advantages
-over TCP, including being able to "broadcast" or "multicast" to a whole
-bunch of destination hosts at once (usually on your local subnet). If you
-find yourself overly concerned about reliability and start building checks
-into your message system, then you probably should use just TCP to start
-with.
-
-UDP datagrams are I<not> a bytestream and should not be treated as such.
-This makes using I/O mechanisms with internal buffering like stdio (i.e.
-print() and friends) especially cumbersome. Use syswrite(), or better
-send(), like in the example below.
-
-Here's a UDP program similar to the sample Internet TCP client given
-earlier. However, instead of checking one host at a time, the UDP version
-will check many of them asynchronously by simulating a multicast and then
-using select() to do a timed-out wait for I/O. To do something similar
-with TCP, you'd have to use a different socket handle for each host.
-
- #!/usr/bin/perl -w
- use strict;
- use Socket;
- use Sys::Hostname;
-
- my ( $count, $hisiaddr, $hispaddr, $histime,
- $host, $iaddr, $paddr, $port, $proto,
- $rin, $rout, $rtime, $SECS_OF_70_YEARS);
-
- $SECS_OF_70_YEARS = 2_208_988_800;
-
- $iaddr = gethostbyname(hostname());
- $proto = getprotobyname("udp");
- $port = getservbyname("time", "udp");
- $paddr = sockaddr_in(0, $iaddr); # 0 means let kernel pick
-
- socket(SOCKET, PF_INET, SOCK_DGRAM, $proto) || die "socket: $!";
- bind(SOCKET, $paddr) || die "bind: $!";
-
- $| = 1;
- printf "%-12s %8s %s\n", "localhost", 0, scalar localtime();
- $count = 0;
- for $host (@ARGV) {
- $count++;
- $hisiaddr = inet_aton($host) || die "unknown host";
- $hispaddr = sockaddr_in($port, $hisiaddr);
- defined(send(SOCKET, 0, 0, $hispaddr)) || die "send $host: $!";
- }
-
- $rin = "";
- vec($rin, fileno(SOCKET), 1) = 1;
-
- # timeout after 10.0 seconds
- while ($count && select($rout = $rin, undef, undef, 10.0)) {
- $rtime = "";
- $hispaddr = recv(SOCKET, $rtime, 4, 0) || die "recv: $!";
- ($port, $hisiaddr) = sockaddr_in($hispaddr);
- $host = gethostbyaddr($hisiaddr, AF_INET);
- $histime = unpack("N", $rtime) - $SECS_OF_70_YEARS;
- printf "%-12s ", $host;
- printf "%8d %s\n", $histime - time(), scalar localtime($histime);
- $count--;
- }
-
-This example does not include any retries and may consequently fail to
-contact a reachable host. The most prominent reason for this is congestion
-of the queues on the sending host if the number of hosts to contact is
-sufficiently large.
-
-=head1 SysV IPC
-
-While System V IPC isn't so widely used as sockets, it still has some
-interesting uses. However, you cannot use SysV IPC or Berkeley mmap() to
-have a variable shared amongst several processes. That's because Perl
-would reallocate your string when you weren't wanting it to. You might
-look into the C<IPC::Shareable> or C<threads::shared> modules for that.
-
-Here's a small example showing shared memory usage.
-
- use IPC::SysV qw(IPC_PRIVATE IPC_RMID S_IRUSR S_IWUSR);
-
- $size = 2000;
- $id = shmget(IPC_PRIVATE, $size, S_IRUSR | S_IWUSR);
- defined($id) || die "shmget: $!";
- print "shm key $id\n";
-
- $message = "Message #1";
- shmwrite($id, $message, 0, 60) || die "shmwrite: $!";
- print "wrote: '$message'\n";
- shmread($id, $buff, 0, 60) || die "shmread: $!";
- print "read : '$buff'\n";
-
- # the buffer of shmread is zero-character end-padded.
- substr($buff, index($buff, "\0")) = "";
- print "un" unless $buff eq $message;
- print "swell\n";
-
- print "deleting shm $id\n";
- shmctl($id, IPC_RMID, 0) || die "shmctl: $!";
-
-Here's an example of a semaphore:
-
- use IPC::SysV qw(IPC_CREAT);
-
- $IPC_KEY = 1234;
- $id = semget($IPC_KEY, 10, 0666 | IPC_CREAT);
- defined($id) || die "shmget: $!";
- print "shm key $id\n";
-
-Put this code in a separate file to be run in more than one process.
-Call the file F<take>:
-
- # create a semaphore
-
- $IPC_KEY = 1234;
- $id = semget($IPC_KEY, 0, 0);
- defined($id) || die "shmget: $!";
-
- $semnum = 0;
- $semflag = 0;
-
- # "take" semaphore
- # wait for semaphore to be zero
- $semop = 0;
- $opstring1 = pack("s!s!s!", $semnum, $semop, $semflag);
-
- # Increment the semaphore count
- $semop = 1;
- $opstring2 = pack("s!s!s!", $semnum, $semop, $semflag);
- $opstring = $opstring1 . $opstring2;
-
- semop($id, $opstring) || die "semop: $!";
-
-Put this code in a separate file to be run in more than one process.
-Call this file F<give>:
-
- # "give" the semaphore
- # run this in the original process and you will see
- # that the second process continues
-
- $IPC_KEY = 1234;
- $id = semget($IPC_KEY, 0, 0);
- die unless defined($id);
-
- $semnum = 0;
- $semflag = 0;
-
- # Decrement the semaphore count
- $semop = -1;
- $opstring = pack("s!s!s!", $semnum, $semop, $semflag);
-
- semop($id, $opstring) || die "semop: $!";
-
-The SysV IPC code above was written long ago, and it's definitely
-clunky looking. For a more modern look, see the IPC::SysV module
-which is included with Perl starting from Perl 5.005.
-
-A small example demonstrating SysV message queues:
-
- use IPC::SysV qw(IPC_PRIVATE IPC_RMID IPC_CREAT S_IRUSR S_IWUSR);
-
- my $id = msgget(IPC_PRIVATE, IPC_CREAT | S_IRUSR | S_IWUSR);
- defined($id) || die "msgget failed: $!";
-
- my $sent = "message";
- my $type_sent = 1234;
-
- msgsnd($id, pack("l! a*", $type_sent, $sent), 0)
- || die "msgsnd failed: $!";
-
- msgrcv($id, my $rcvd_buf, 60, 0, 0)
- || die "msgrcv failed: $!";
-
- my($type_rcvd, $rcvd) = unpack("l! a*", $rcvd_buf);
-
- if ($rcvd eq $sent) {
- print "okay\n";
- } else {
- print "not okay\n";
- }
-
- msgctl($id, IPC_RMID, 0) || die "msgctl failed: $!\n";
-
-=head1 NOTES
-
-Most of these routines quietly but politely return C<undef> when they
-fail instead of causing your program to die right then and there due to
-an uncaught exception. (Actually, some of the new I<Socket> conversion
-functions do croak() on bad arguments.) It is therefore essential to
-check return values from these functions. Always begin your socket
-programs this way for optimal success, and don't forget to add the B<-T>
-taint-checking flag to the C<#!> line for servers:
-
- #!/usr/bin/perl -Tw
- use strict;
- use sigtrap;
- use Socket;
-
-=head1 BUGS
-
-These routines all create system-specific portability problems. As noted
-elsewhere, Perl is at the mercy of your C libraries for much of its system
-behavior. It's probably safest to assume broken SysV semantics for
-signals and to stick with simple TCP and UDP socket operations; e.g., don't
-try to pass open file descriptors over a local UDP datagram socket if you
-want your code to stand a chance of being portable.
-
-=head1 AUTHOR
-
-Tom Christiansen, with occasional vestiges of Larry Wall's original
-version and suggestions from the Perl Porters.
-
-=head1 SEE ALSO
-
-There's a lot more to networking than this, but this should get you
-started.
-
-For intrepid programmers, the indispensable textbook is I<Unix Network
-Programming, 2nd Edition, Volume 1> by W. Richard Stevens (published by
-Prentice-Hall). Most books on networking address the subject from the
-perspective of a C programmer; translation to Perl is left as an exercise
-for the reader.
-
-The IO::Socket(3) manpage describes the object library, and the Socket(3)
-manpage describes the low-level interface to sockets. Besides the obvious
-functions in L<perlfunc>, you should also check out the F<modules> file at
-your nearest CPAN site, especially
-L<http://www.cpan.org/modules/00modlist.long.html#ID5_Networking_>.
-See L<perlmodlib> or best yet, the F<Perl FAQ> for a description
-of what CPAN is and where to get it if the previous link doesn't work
-for you.
-
-Section 5 of CPAN's F<modules> file is devoted to "Networking, Device
-Control (modems), and Interprocess Communication", and contains numerous
-unbundled modules numerous networking modules, Chat and Expect operations,
-CGI programming, DCE, FTP, IPC, NNTP, Proxy, Ptty, RPC, SNMP, SMTP, Telnet,
-Threads, and ToolTalk--to name just a few.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlirix.pod b/Master/tlpkg/tlperl/lib/pods/perlirix.pod
deleted file mode 100644
index 23cc17bd79f..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlirix.pod
+++ /dev/null
@@ -1,137 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see pod/perlpod.pod) which is
-specifically designed to be readable as is.
-
-=head1 NAME
-
-perlirix - Perl version 5 on Irix systems
-
-=head1 DESCRIPTION
-
-This document describes various features of Irix that will affect how Perl
-version 5 (hereafter just Perl) is compiled and/or runs.
-
-=head2 Building 32-bit Perl in Irix
-
-Use
-
- sh Configure -Dcc='cc -n32'
-
-to compile Perl 32-bit. Don't bother with -n32 unless you have 7.1
-or later compilers (use cc -version to check).
-
-(Building 'cc -n32' is the default.)
-
-=head2 Building 64-bit Perl in Irix
-
-Use
-
- sh Configure -Dcc='cc -64' -Duse64bitint
-
-This requires require a 64-bit MIPS CPU (R8000, R10000, ...)
-
-You can also use
-
- sh Configure -Dcc='cc -64' -Duse64bitall
-
-but that makes no difference compared with the -Duse64bitint because
-of the C<cc -64>.
-
-You can also do
-
- sh Configure -Dcc='cc -n32' -Duse64bitint
-
-to use long longs for the 64-bit integer type, in case you don't
-have a 64-bit CPU.
-
-If you are using gcc, just
-
- sh Configure -Dcc=gcc -Duse64bitint
-
-should be enough, the Configure should automatically probe for the
-correct 64-bit settings.
-
-=head2 About Compiler Versions of Irix
-
-Some Irix cc versions, e.g. 7.3.1.1m (try cc -version) have been known
-to have issues (coredumps) when compiling perl.c. If you've used
--OPT:fast_io=ON and this happens, try removing it. If that fails, or
-you didn't use that, then try adjusting other optimization options
-(-LNO, -INLINE, -O3 to -O2, etcetera). The compiler bug has been
-reported to SGI. (Allen Smith <easmith@beatrice.rutgers.edu>)
-
-=head2 Linker Problems in Irix
-
-If you get complaints about so_locations then search in the file
-hints/irix_6.sh for "lddflags" and do the suggested adjustments.
-(David Billinghurst <David.Billinghurst@riotinto.com.au>)
-
-=head2 Malloc in Irix
-
-Do not try to use Perl's malloc, this will lead into very mysterious
-errors (especially with -Duse64bitall).
-
-=head2 Building with threads in Irix
-
-Run Configure with -Duseithreads which will configure Perl with
-the Perl 5.8.0 "interpreter threads", see L<threads>.
-
-For Irix 6.2 with perl threads, you have to have the following
-patches installed:
-
- 1404 Irix 6.2 Posix 1003.1b man pages
- 1645 Irix 6.2 & 6.3 POSIX header file updates
- 2000 Irix 6.2 Posix 1003.1b support modules
- 2254 Pthread library fixes
- 2401 6.2 all platform kernel rollup
-
-B<IMPORTANT>: Without patch 2401, a kernel bug in Irix 6.2 will cause
-your machine to panic and crash when running threaded perl. Irix 6.3
-and later are okay.
-
- Thanks to Hannu Napari <Hannu.Napari@hut.fi> for the IRIX
- pthreads patches information.
-
-=head2 Irix 5.3
-
-While running Configure and when building, you are likely to get
-quite a few of these warnings:
-
- ld:
- The shared object /usr/lib/libm.so did not resolve any symbols.
- You may want to remove it from your link line.
-
-Ignore them: in IRIX 5.3 there is no way to quieten ld about this.
-
-During compilation you will see this warning from toke.c:
-
- uopt: Warning: Perl_yylex: this procedure not optimized because it
- exceeds size threshold; to optimize this procedure, use -Olimit option
- with value >= 4252.
-
-Ignore the warning.
-
-In IRIX 5.3 and with Perl 5.8.1 (Perl 5.8.0 didn't compile in IRIX 5.3)
-the following failures are known.
-
- Failed Test Stat Wstat Total Fail Failed List of Failed
- --------------------------------------------------------------------------
- ../ext/List/Util/t/shuffle.t 0 139 ?? ?? % ??
- ../lib/Math/Trig.t 255 65280 29 12 41.38% 24-29
- ../lib/sort.t 0 138 119 72 60.50% 48-119
- 56 tests and 474 subtests skipped.
- Failed 3/811 test scripts, 99.63% okay. 78/75813 subtests failed, 99.90% okay.
-
-They are suspected to be compiler errors (at least the shuffle.t
-failure is known from some IRIX 6 setups) and math library errors
-(the Trig.t failure), but since IRIX 5 is long since end-of-lifed,
-further fixes for the IRIX are unlikely. If you can get gcc for 5.3,
-you could try that, too, since gcc in IRIX 6 is a known workaround for
-at least the shuffle.t and sort.t failures.
-
-=head1 AUTHOR
-
-Jarkko Hietaniemi <jhi@iki.fi>
-
-Please report any errors, updates, or suggestions to F<perlbug@perl.org>.
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perljp.pod b/Master/tlpkg/tlperl/lib/pods/perljp.pod
deleted file mode 100644
index 934a91f9180..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perljp.pod
+++ /dev/null
@@ -1,192 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see perlpod manpage) which is
-specially designed to be readable as is.
-
-The following documentation is written in euc-jp encoding.
-
-=encoding euc-jp
-
-=head1 NAME
-
-perljp - ÆüËܸì Perl ¥¬¥¤¥É
-
-=head1 ÀâÌÀ
-
-Perl ¤ÎÀ¤³¦¤Ø¤è¤¦¤³¤½!
-
-Perl 5.8.0 ¤è¤ê¡¢Unicode¥µ¥Ý¡¼¥È¤¬ÂçÉý¤Ë¶¯²½¤µ¤ì¡¢¤½¤Î·ë²Ì¥é¥Æ¥óʸ»ú°Ê³°¤Îʸ»ú¥³¡¼¥É¤Î¥µ¥Ý¡¼¥È¤¬ CJK (Ãæ¹ñ¸ì¡¢ÆüËܸ졢¥Ï¥ó¥°¥ë)¤ò´Þ¤á¤Æ²Ã¤ï¤ê¤Þ¤·¤¿¡£Unicode¤ÏÀ¤³¦Ãæ¤Îʸ»ú¤ò°ì¤Ä¤Îʸ»ú¥³¡¼¥É¤Ç°·¤¦¤³¤È¤òÌܻؤ·¤¿É¸½àµ¬³Ê¤Ç¤¢¤ê¡¢Å줫¤éÀ¾¡¢¤Ï¤¿¤Þ¤¿¤½¤Î´Ö¤Îʸ»ú¡Ê¥®¥ê¥·¥ãʸ»ú¡¢¥­¥ê¡¼¥ëʸ»ú¡¢¥¢¥é¥Ó¥¢Ê¸»ú¡¢¥Ø¥Ö¥é¥¤Ê¸»ú¡¢¥Ç¥£¡¼¥ô¥¡¥Ê¥¬¡¼¥êʸ»ú¡¢¤Ê¤É¤Ê¤É¡Ë¤ä¡¢¤³¤ì¤Þ¤Ç¤ÏOS¥Ù¥ó¥À¡¼¤¬Æȼ«¤ËÄê¤á¤Æ¤¤¤¿Ê¸»ú(PC¤ª¤è¤ÓMacintosh)¤¬¤¹¤Ç¤Ë´Þ¤Þ¤ì¤Æ¤¤¤Þ¤¹¡£
-
-Perl ¼«¿È¤Ï Unicode ¤ÇÆ°ºî¤·¤Þ¤¹¡£Perl ¥¹¥¯¥ê¥×¥ÈÆâ¤Îʸ»úÎó¥ê¥Æ¥é¥ë¤äÀµµ¬É½¸½¤Ï Unicode ¤òÁ°Äó¤È¤·¤Æ¤¤¤Þ¤¹¡£¤½¤·¤ÆÆþ½ÐÎϤΤ¿¤á¤Ë¤Ï¡¢¤³¤ì¤Þ¤Ç»È¤ï¤ì¤Æ¤­¤¿¤µ¤Þ¤¶¤Þ¤Êʸ»ú¥³¡¼¥É¤ËÂбþ¤¹¤ë¥â¥¸¥å¡¼¥ë¡¢¡Ö Encode ¡×¤¬É¸½àÁõÈ÷¤µ¤ì¤Æ¤ª¤ê¡¢Unicode ¤È¤³¤ì¤é¤Îʸ»ú¥³¡¼¥É¤ÎÁê¸ßÊÑ´¹¤â´Êñ¤Ë¹Ô¤¨¤ë¤è¤¦¤Ë¤Ê¤Ã¤Æ¤¤¤Þ¤¹¡£
-
-¸½»þÅÀ¤Ç Encode ¤¬¥µ¥Ý¡¼¥È¤¹¤ëʸ»ú¥³¡¼¥É¤Ï°Ê²¼¤Î¤È¤ª¤ê¤Ç¤¹¡£
-
- 7bit-jis AdobeStandardEncoding AdobeSymbol AdobeZdingbat
- ascii big5 big5-hkscs cp1006
- cp1026 cp1047 cp1250 cp1251
- cp1252 cp1253 cp1254 cp1255
- cp1256 cp1257 cp1258 cp37
- cp424 cp437 cp500 cp737
- cp775 cp850 cp852 cp855
- cp856 cp857 cp860 cp861
- cp862 cp863 cp864 cp865
- cp866 cp869 cp874 cp875
- cp932 cp936 cp949 cp950
- dingbats euc-cn euc-jp euc-kr
- gb12345-raw gb2312-raw gsm0338 hp-roman8
- hz iso-2022-jp iso-2022-jp-1 iso-8859-1
- iso-8859-10 iso-8859-11 iso-8859-13 iso-8859-14
- iso-8859-15 iso-8859-16 iso-8859-2 iso-8859-3
- iso-8859-4 iso-8859-5 iso-8859-6 iso-8859-7
- iso-8859-8 iso-8859-9 iso-ir-165 jis0201-raw
- jis0208-raw jis0212-raw johab koi8-f
- koi8-r koi8-u ksc5601-raw MacArabic
- MacCentralEurRoman MacChineseSimp MacChineseTrad MacCroatian
- MacCyrillic MacDingbats MacFarsi MacGreek
- MacHebrew MacIcelandic MacJapanese MacKorean
- MacRoman MacRomanian MacRumanian MacSami
- MacSymbol MacThai MacTurkish MacUkrainian
- nextstep posix-bc shiftjis symbol
- UCS-2BE UCS-2LE UTF-16 UTF-16BE
- UTF-16LE UTF-32 UTF-32BE UTF-32LE
- utf8 viscii
-
-(Á´114¼ïÎà)
-
-Î㤨¤Ð¡¢Ê¸»ú¥³¡¼¥ÉFOO¤Î¥Õ¥¡¥¤¥ë¤òUTF-8¤ËÊÑ´¹¤¹¤ë¤Ë¤Ï¡¢°Ê²¼¤Î¤è¤¦¤Ë¤·¤Þ¤¹¡£
-
- perl -Mencoding=FOO,STDOUT,utf8 -pe1 < file.FOO > file.utf8
-
-¤Þ¤¿¡¢Perl¤Ë¤Ï¡¢Á´Éô¤¬Perl¤Ç½ñ¤«¤ì¤¿Ê¸»ú¥³¡¼¥ÉÊÑ´¹¥æ¡¼¥Æ¥£¥ê¥Æ¥£¡¢piconv¤âÉÕ°¤·¤Æ¤¤¤ë¤Î¤Ç¡¢°Ê²¼¤Î¤è¤¦¤Ë¤¹¤ë¤³¤È¤â¤Ç¤­¤Þ¤¹¡£
-
- piconv -f FOO -t utf8 < file.FOO > file.utf8
- piconv -f utf8 -t FOO < file.utf8 > file.FOO
-
-=head2 About (jcode.pl|Jcode.pm|JPerl)
-
-5.8°ÊÁ°¤Î¡¢¥¹¥¯¥ê¥×¥È¤¬EUC-JP¤Ç¤¢¤ì¤Ð¥ê¥Æ¥é¥ë¤À¤±¤Ï°·¤¦¤³¤È¤¬¤Ç¤­¤Þ¤·¤¿¡£¤Þ¤¿¡¢Æþ½ÐÎϤò°·¤¦¥â¥¸¥å¡¼¥ë¤È¤·¤Æ¤ÏJcode.pm¤¬( http://openlab.ring.gr.jp/Jcode/ )¡¢perl4ÍѤΥ桼¥Æ¥£¥ê¥Æ¥£¤È¤·¤Æ¤Ïjcode.pl¤¬¤½¤ì¤¾¤ì¸ºß¤·¡¢ÆüËܸì¤Î°·¤¨¤ëCGI¤Ç¤è¤¯ÍøÍѤµ¤ì¤Æ¤¤¤ë¤³¤È¤ò¸æ¸¤¸¤ÎÊý¤â¾¯¤Ê¤¯¤Ê¤¤¤«¤È»×¤ï¤ì¤Þ¤¹¡£¤¿¤À¤·¡¢ÆüËܸì¤Ë¤è¤ëÀµµ¬É½¸½¤ò¤¦¤Þ¤¯°·¤¦¤³¤È¤ÏÉÔ²Äǽ¤Ç¤·¤¿¡£
-
-5.005°ÊÁ°¤ÎPerl¤Ë¤Ï¡¢ÆüËܸì¤ËÆò½¤·¤¿¥í¡¼¥«¥é¥¤¥ºÈÇ¡¢Jperl¤¬Â¸ºß¤·¤Þ¤·¤¿( http://homepage2.nifty.com/kipp/perl/jperl/index.html )¡£¤Þ¤¿¡¢Mac OS 9.x/ClassicÍѤÎPerl¡¢MacPerl¤ÎÆüËܸìÈǤâMacJPerl¤È¤·¤Æ¸ºß¤·¤Æ¤Þ¤·¤¿¡£( http://habilis.net/macjperl/ ).¤³¤ì¤é¤Ç¤Ïʸ»ú¥³¡¼¥É¤È¤·¤ÆEUC-JP¤Ë²Ã¤¨Shift_JIS¤â¤½¤Î¤Þ¤Þ°·¤¦¤³¤È¤¬¤Ç¤­¡¢¤Þ¤¿ÆüËܸì¤Ë¤è¤ëÀµµ¬É½¸½¤ò°·¤¦¤³¤È¤â²Äǽ¤Ç¤·¤¿¡£
-
-Perl5.8¤Ç¤Ï¡¢¤³¤ì¤é¤Îµ¡Ç½¤¬¤¹¤Ù¤ÆPerlËÜÂΤÀ¤±¤Ç¼Â¸½¤Ç¤­¤ë¾å¤Ë¡¢ÆüËܸì¤Î¤ß¤Ê¤é¤º¾åµ­114¤Îʸ»ú¥³¡¼¥É¤ò¤¹¤Ù¤Æ¡¢¤·¤«¤âƱ»þ¤Ë°·¤¦¤³¤È¤¬¤Ç¤­¤Þ¤¹¡£¤µ¤é¤Ë¡¢CPAN¤Ê¤É¤«¤é¿·¤·¤¤Ê¸»ú¥³¡¼¥ÉÍѤΥ⥸¥å¡¼¥ë¤òÆþ¼ê¤¹¤ë¤³¤È¤â´Êñ¤Ë¤Ç¤­¤ë¤è¤¦¤Ë¤Ê¤Ã¤Æ¤¤¤Þ¤¹¡£
-
-=over 4
-
-=item *
-
-Æþ½ÐÎÏ
-
-°Ê²¼¤ÎÎã¤Ï¤¤¤Å¤ì¤âShift_JIS¤ÎÆþÎϤòEUC-JP¤ËÊÑ´¹¤·¤Æ½ÐÎϤ·¤Þ¤¹¡£
-
- # jcode.pl
- require "jcode.pl";
- while(<>){
- jcode::convert(*_, 'euc', 'sjis');
- print;
- }
- # Jcode.pm
- use Jcode;
- while(<>){
- print Jcode->new($_, 'sjis')->euc;
- }
- # Perl 5.8
- use Encode;
- while(<>){
- from_to($_, 'shiftjis', 'euc-jp');
- print;
- }
- # Perl 5.8 - encoding ¤òÍøÍѤ·¤Æ
- use encoding 'euc-jp', STDIN => 'shiftjis';
- while(<>){
- print;
- }
-
-=item *
-
-Jperl ¸ß´¹¥¹¥¯¥ê¥×¥È
-
- ¤¤¤ï¤æ¤ë"shebang"¤òÊѹ¹¤¹¤ë¤À¤±¤Ç¡¢JperlÍѤÎscript¤Î¤Û¤È¤ó¤É¤ÏÊѹ¹¤Ê¤·¤ËÍøÍѲÄǽ¤À¤È»×¤ï¤ì¤Þ¤¹¡£
-
- #!/path/to/jperl
- ¢­
- #!/path/to/perl -Mencoding=euc-jp
-
- ¾Ü¤·¤¯¤Ï perldoc encoding ¤ò»²¾È¤·¤Æ¤¯¤À¤µ¤¤¡£
-
-=back
-
-=head2 ¤µ¤é¤Ë¾Ü¤·¤¯
-
-Perl¤Ë¤ÏËÄÂç¤Ê»ñÎÁ¤¬ÉÕ°¤·¤Æ¤ª¤ê¡¢Perl¤Î¿·µ¡Ç½¤äUnicode¥µ¥Ý¡¼¥È¡¢¤½¤·¤ÆEncode¥â¥¸¥å¡¼¥ë¤Î»ÈÍÑË¡¤Ê¤É¤¬ºÙ¤«¤¯ÌÖÍ夵¤ì¤Æ¤¤¤Þ¤¹¡Ê»ÄÇ°¤Ê¤¬¤é¡¢¤Û¤È¤ó¤É±Ñ¸ì¤Ç¤Ï¤¢¤ê¤Þ¤¹¤¬¡Ë¡£°Ê²¼¤Î¥³¥Þ¥ó¥É¤Ç¤½¤ì¤é¤Î°ìÉô¤ò±ÜÍ÷¤¹¤ë¤³¤È¤¬²Äǽ¤Ç¤¹¡£
-
- perldoc perlunicode # Perl¤ÎUnicode¥µ¥Ý¡¼¥ÈÁ´ÈÌ
- perldoc Encode # Encode¥â¥¸¥å¡¼¥ë¤Ë´Ø¤·¤Æ
- perldoc Encode::JP # ¤¦¤ÁÆüËܸìʸ»ú¥³¡¼¥É¤Ë´Ø¤·¤Æ
-
-=head2 PerlÁ´È̤˴ؤ¹¤ë URL
-
-=over 4
-
-=item L<http://www.perl.com/>
-
-Perl ¥Û¡¼¥à¥Ú¡¼¥¸ (O'Reilly and Associates)
-
-=item L<http://www.cpan.org/>
-
-CPAN (Comprehensive Perl Archive Network)
-
-=item L<http://lists.perl.org/>
-
-Perl ¥á¡¼¥ê¥ó¥°¥ê¥¹¥È½¸
-
-=back
-
-=head2 Perl¤Î½¤ÆÀ¤ËÌòΩ¤Ä URL
-
-=over 4
-
-=item L<http://www.oreilly.com.tw/>
-
-O'Reilly ¼Ò¤ÎPerl´ØÏ¢½ñÀÒ(ÈËÂλúÃæ¹ñ¸ì)
-
-=item L<http://www.oreilly.com.cn/>
-
-O'Reilly ¼Ò¤ÎPerl´ØÏ¢½ñÀÒ(´ÊÂλúÃæ¹ñ¸ì)
-
-=item L<http://www.oreilly.co.jp/catalog/>
-
-¥ª¥é¥¤¥ê¡¼¼Ò¤ÎPerl´ØÏ¢½ñÀÒ(ÆüËܸì)
-
-=back
-
-=head2 Perl ¥æ¡¼¥¶¡¼¥°¥ë¡¼¥×
-
-=over 4
-
-=item L<http://www.pm.org/groups/asia.html>
-
-=back
-
-=head2 Unicode´ØÏ¢¤ÎURL
-
-=over 4
-
-=item L<http://www.unicode.org/>
-
-Unicode ¥³¥ó¥½¡¼¥·¥¢¥à (Unicodeµ¬³Ê¤ÎÁªÄêÃÄÂÎ)
-
-=item L<http://www.cl.cam.ac.uk/%7Emgk25/unicode.html>
-
-UTF-8 and Unicode FAQ for Unix/Linux
-
-=item L<http://wiki.kldp.org/Translations/html/UTF8-Unicode-KLDP/UTF8-Unicode-KLDP.html>
-
-UTF-8 and Unicode FAQ for Unix/Linux (¥Ï¥ó¥°¥ëÌõ)
-
-=back
-
-=head1 AUTHORS
-
-Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>
-Dan Kogai (¾®»ô¡¡ÃÆ) E<lt>dankogai@dan.co.jpE<gt>
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlko.pod b/Master/tlpkg/tlperl/lib/pods/perlko.pod
deleted file mode 100644
index 4f23ea9a14c..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlko.pod
+++ /dev/null
@@ -1,207 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see perlpod manpage) which is
-specially designed to be readable as is.
-
-This file is in Korean encoded in EUC-KR.
-
-ÀÌ ¹®¼­¸¦ perldocÀ» ½á¼­ º¸Áö ¾Ê°í Á÷Á¢ º¸´Â °æ¿ì¿¡´Â °¢ ºÎºÐÀÇ
-¿ªÇÒÀ» Ç¥½ÃÇϱâ À§ÇØ ¾²ÀÎ =head, =item, 'L' µîÀº ¹«½ÃÇϽʽÿÀ.
-ÀÌ ¹®¼­´Â µû·Î perldocÀ» ¾²Áö ¾Ê°í º¸´õ¶óµµ Àдµ¥ º° ÁöÀåÀÌ
-¾ø´Â POD Çü½ÄÀ¸·Î Â¥¿© ÀÖ½À´Ï´Ù. ´õ ÀÚ¼¼ÇÑ °ÍÀº perlpod
-¸Å´º¾óÀ» Âü°íÇϽʽÿÀ.
-
-=encoding euc-kr
-
-=head1 NAME
-
-perlko - Perl°ú Çѱ¹¾î ÀÎÄÚµù
-
-=head1 DESCRIPTION
-
-PerlÀÇ ¼¼°è¿¡ ¿À½Å °ÍÀ» ȯ¿µÇÕ´Ï´Ù !
-
-
-PerlÀº 5.8.0ÆǺÎÅÍ À¯´ÏÄÚµå/ISO 10646¿¡ ´ëÇÑ ±¤¹üÀ§ÇÑ Áö¿øÀ» ÇÕ´Ï´Ù.
-À¯´ÏÄÚµå Áö¿øÀÇ ÀÏȯÀ¸·Î ÇÑÁßÀÏÀ» ºñ·ÔÇÑ ¼¼°è °¢±¹¿¡¼­
-À¯´ÏÄÚµå ÀÌÀü¿¡ ¾²°í ÀÖ¾ú°í Áö±Ýµµ ³Î¸® ¾²ÀÌ°í ÀÖ´Â ¼ö¸¹Àº ÀÎÄÚµùÀ»
-Áö¿øÇÕ´Ï´Ù. À¯´ÏÄÚµå´Â Àü ¼¼°è¿¡¼­ ¾²ÀÌ´Â ¸ðµç ¾ð¾î¸¦ À§ÇÑ Ç¥±â ü°è -
-À¯·´ÀÇ ¶óƾ ¾ËÆĺª, Å°¸± ¾ËÆĺª, ±×¸®½º ¾ËÆĺª, Àεµ¿Í µ¿³² ¾Æ½Ã¾ÆÀÇ
-ºê¶ó¹Ì °è¿­ ½ºÅ©¸³Æ®, ¾Æ¶ø ¹®ÀÚ, È÷ºê¸® ¹®ÀÚ, ÇÑÁßÀÏÀÇ ÇÑÀÚ, Çѱ¹¾îÀÇ ÇѱÛ,
-ÀϺ»¾îÀÇ °¡³ª, ºÏ¹Ì Àεð¾ÈÀÇ Ç¥±â ü°è µî-¸¦ ¼ö¿ëÇÏ´Â °ÍÀ» ¸ñÇ¥·Î ÇÏ°í
-Àֱ⠶§¹®¿¡ ±âÁ¸¿¡ ¾²ÀÌ´ø °¢ ¾ð¾î ¹× ±¹°¡ ±×¸®°í ¿î¿µ ü°è¿¡ °íÀ¯ÇÑ
-¹®ÀÚ ÁýÇÕ°ú ÀÎÄÚµù¿¡ ¾µ ¼ö ÀÖ´Â ¸ðµç ±ÛÀÚ´Â ¹°·ÐÀÌ°í ±âÁ¸ ¹®ÀÚ ÁýÇÕ¿¡¼­
-Áö¿øÇÏ°í ÀÖÁö ¾Ê´ø ¾ÆÁÖ ¸¹Àº ±ÛÀÚ¸¦ Æ÷ÇÔÇÏ°í ÀÖ½À´Ï´Ù.
-
-
-PerlÀº ³»ºÎÀûÀ¸·Î À¯´ÏÄڵ带 ¹®ÀÚ Ç¥ÇöÀ» À§ÇØ »ç¿ëÇÕ´Ï´Ù. º¸´Ù ±¸Ã¼ÀûÀ¸·Î
-¸»Çϸé Perl ½ºÅ©¸³Æ® ¾È¿¡¼­ UTF-8 ¹®ÀÚ¿­À» ¾µ ¼ö ÀÖ°í,
-°¢Á¾ ÇÔ¼ö¿Í ¿¬»êÀÚ(¿¹¸¦ µé¾î, Á¤±Ô½Ä, index, substr)°¡ ¹ÙÀÌÆ® ´ÜÀ§
-´ë½Å À¯´ÏÄÚµå ±ÛÀÚ ´ÜÀ§·Î µ¿ÀÛÇÕ´Ï´Ù. (´õ ÀÚ¼¼ÇÑ °ÍÀº
-perlunicode ¸Å´º¾óÀ» Âü°íÇϽʽÿÀ.) À¯´ÏÄڵ尡 ³Î¸® º¸±ÞµÇ±â Àü¿¡
-³Î¸® ¾²ÀÌ°í ÀÖ¾ú°í, ¿©ÀüÈ÷ ³Î¸® ¾²ÀÌ°í ÀÖ´Â °¢±¹/°¢ ¾ð¾îº° ÀÎÄÚµùÀ¸·Î
-ÀÔÃâ·ÂÀ» ÇÏ°í À̵é ÀÎÄÚµùÀ¸·Î µÈ µ¥ÀÌÅÍ¿Í ¹®¼­¸¦ ´Ù·ç´Â °ÍÀ» µ½±â À§ÇØ
-'Encode'°¡ ¾²¿´½À´Ï´Ù. ¹«¾ùº¸´Ù 'Encode'¸¦ ½á¼­ ¼ö¸¹Àº ÀÎÄÚµù »çÀÌÀÇ
-º¯È¯À» ½±°Ô ÇÒ ¼ö ÀÖ½À´Ï´Ù.
-
-'Encode'´Â ´ÙÀ½°ú °°Àº Çѱ¹¾î ÀÎÄÚµùÀ» Áö¿øÇÕ´Ï´Ù.
-
-=over 4
-
-=item euc-kr
-
- US-ASCII¿Í KS X 1001À» °°ÀÌ ¾²´Â ¸ÖƼ¹ÙÀÌÆ® ÀÎÄÚµù (ÈçÈ÷ ¿Ï¼ºÇüÀ̶ó°í
- ºÒ¸².) KS X 2901°ú RFC 1557 Âü°í.
-
-=item cp949
-
- MS-Windows 9x/ME¿¡¼­ ¾²ÀÌ´Â È®Àå ¿Ï¼ºÇü. euc-kr¿¡ 8,822ÀÚÀÇ
- ÇÑ±Û À½ÀýÀ» ´õÇÑ °ÍÀÓ. alias´Â uhc, windows-949, x-windows-949,
- ks_c_5601-1987. ¸Ç ¸¶Áö¸· À̸§Àº ÀûÀýÇÏÁö ¾ÊÀº À̸§ÀÌÁö¸¸, Microsoft
- Á¦Ç°¿¡¼­ CP949ÀÇ Àǹ̷Π¾²ÀÌ°í ÀÖÀ½.
-
-=item johab
-
- KS X 1001:1998 ºÎ·Ï 3¿¡¼­ ±ÔÁ¤ÇÑ Á¶ÇÕÇü. ¹®ÀÚ ·¹ÆÛÅ丮´Â cp949¿Í
- ¸¶Âù°¡Áö·Î US-ASCII¿Í KS X 1001¿¡ 8,822ÀÚÀÇ ÇÑ±Û À½ÀýÀ» ´õÇÑ °ÍÀÓ.
- ÀÎÄÚµù ¹æ½ÄÀº ÀüÇô ´Ù¸§.
-
-=item iso-2022-kr
-
- RFC 1557¿¡¼­ ±ÔÁ¤ÇÑ Çѱ¹¾î ÀÎÅÍ³Ý ¸ÞÀÏ ±³È¯¿ë ÀÎÄÚµùÀ¸·Î US-ASCII¿Í
- KS X 1001À» ·¹ÆÛÅ丮·Î ÇÏ´Â Á¡¿¡¼­ euc-kr°ú °°Áö¸¸ ÀÎÄÚµù ¹æ½ÄÀÌ ´Ù¸§.
- 1997-8³â °æ±îÁö ¾²¿´À¸³ª ´õ ÀÌ»ó ¸ÞÀÏ ±³È¯¿¡ ¾²ÀÌÁö ¾ÊÀ½.
-
-=item ksc5601-raw
-
- KS X 1001(KS C 5601)À» GL(Áï, MSB¸¦ 0À¸·Î ÇÑ °æ¿ì) ¿¡ ³õ¾ÒÀ» ¶§ÀÇ
- ÀÎÄÚµù. US-ASCII¿Í °áÇÕÇÏÁö ¾Ê°í ´Üµ¶À¸·Î ¾²ÀÌ´Â ÀÏÀº X11 µî¿¡¼­ ±Û²Ã
- ÀÎÄÚµù (ksc5601.1987-0. '0'Àº GLÀ» ÀǹÌÇÔ.)À¸·Î ¾²ÀÌ´Â °ÍÀ» Á¦¿ÜÇÏ°í´Â
- °ÅÀÇ ¾øÀ½. KS C 5601Àº 1997³â KS X 1001·Î À̸§À» ¹Ù²Ù¾úÀ½. 1998³â¿¡´Â µÎ
- ±ÛÀÚ (À¯·ÎÈ­ ºÎÈ£¿Í µî·Ï »óÇ¥ ºÎÈ£)°¡ ´õÇØÁ³À½.
-
-=back
-
- ¸î °¡Áö »ç¿ë ¿¹Á¦¸¦ ¾Æ·¡¿¡ º¸ÀÔ´Ï´Ù.
-
-¿¹¸¦ µé¾î, euc-kr ÀÎÄÚµùÀ¸·Î µÈ ÆÄÀÏÀ» UTF-8·Î º¯È¯ÇÏ·Á¸é ´ÙÀ½°ú
-°°ÀÌ ÇÏ¸é µË´Ï´Ù.
-
-
- perl -Mencoding=euc-kr,STDOUT,utf8 -pe1 < file.euckr > file.utf8
-
-¿ªº¯È¯Àº ´ÙÀ½°ú °°ÀÌ ÇÒ ¼ö ÀÖ½À´Ï´Ù.
-
- perl -Mencoding=utf8,STDOUT,euc-kr -pe1 < file.utf8 > file.euckr
-
- ÀÌ·± º¯È¯À» Á»´õ Æí¸®ÇÏ°Ô ÇÒ ¼ö ÀÖµµ·Ï Encode ¸ðµâÀ» ½á¼­
-¼ø¼öÇÏ°Ô Perl·Î¸¸ ¾²ÀÎ piconv°¡ Perl¿¡ µé¾î ÀÖ½À´Ï´Ù.
-±× À̸§¿¡¼­ ¾Ë ¼ö ÀÖµíÀÌ piconv´Â Unix¿¡ ÀÖ´Â iconv¸¦
-¸ðµ¨·Î ÇÑ °ÍÀÔ´Ï´Ù. ±× »ç¿ë¹ýÀº ¾Æ·¡¿Í °°½À´Ï´Ù.
-
- piconv -f euc-kr -t utf8 < file.euckr > file.utf8
- piconv -f utf8 -t euc-kr < file.utf8 > file.euckr
-
- ¶Ç, 'PerlIO::encoding' ¸ðµâÀ» ½á¼­ Çѱ¹¾î ÀÎÄÚµùÀ» ¾²¸é¼­ ±ÛÀÚ ´ÜÀ§
-(¹ÙÀÌÆ® ´ÜÀ§°¡ ¾Æ´Ï¶ó) 󸮸¦ ½±°Ô ÇÒ ¼ö ÀÖ½À´Ï´Ù.
-
- #!/path/to/perl
-
- use encoding 'euc-kr', STDIN => 'euc-kr',
- STDOUT-> 'euc-kr', STDERR=>'euc-kr';
-
- print length("°¡³ª"); # 2 (Å« µû¿ÈÇ¥´Â ±ÛÀÚ ´ÜÀ§ 󸮸¦ Áö½Ã)
- print length('°¡³ª'); # 4 (ÀÛÀº µû¿ÈÇ¥´Â ¹ÙÀÌÆ® ´ÜÀ§ 󸮸¦ Áö½Ã)
- print index("ÇÑ°­, ´ëµ¿°­", "¿°"); # -1 ('¿°'ÀÌ ¾øÀ½)
- print index('ÇÑ°­, ´ëµ¿°­', '¿°'); # 7 (8¹ø°¿Í 9¹ø° ¹ÙÀÌÆ®°¡ '¿°'ÀÇ
- Äڵ尪°ú ÀÏÄ¡ÇÔ.)
-
-
-=head2 ´õ ÀÚ¼¼È÷ ¾Ë°í ½ÍÀ¸¸é...
-
- PerlÀ» ¼³Ä¡ÇÏ¸é ´ë´ÜÈ÷ ÀÚ¼¼ÇÑ ¹®¼­°¡ °°ÀÌ µû¶ó ¿À¸ç, ÀÌ ¹®¼­¸¦ ÅëÇØ
-Perl Àü¹Ý »Ó ¾Æ´Ï¶ó À¯´ÏÄÚµå Áö¿ø, EncodeÀÇ »ç¿ë¹ý µî¿¡ ¸¹Àº °ÍÀ»
-¹è¿ï ¼ö ÀÖ½À´Ï´Ù. ¾ÆÁ÷ ÀÌ ¹®¼­´Â ÇöÀç ¸ðµÎ ¿µ¾î·Î ¾²¿© ÀÖ½À´Ï´Ù.
-
-
-=head2 Perl °ü·Ã ÀÚ·á
-
-À§¿¡¼­ ¾ð±ÞÇÑ ¹®¼­ ¿Ü¿¡µµ ´ÙÀ½°ú °°Àº ÀÚ·á°¡ ÀÖ½À´Ï´Ù. ÀÌ ¸ñ·ÏÀº °áÄÚ
-¿ÏÀüÇÑ °ÍÀÌ ¾Æ´Ï°í ÀϺΠ´ëÇ¥ÀûÀÎ °Í¸¸ ¸ðÀº °ÍÀÔ´Ï´Ù.
-
-=over 4
-
-=item L<http://www.perl.com/>
-
- O'ReillyÀÇ Perl À¥ ÆäÀÌÁö
-
-=item L<http://www.cpan.org/>
-
- Comprehensive Perl Archive Network
-
-=item L<http://lists.perl.org/>
-
- Perl ¸ÞÀϸµ ¸®½ºÆ®. ¸¹Àº ¸®½ºÆ® °¡¿îµ¥
- perl-unicode¿¡¼­ 'Encode'¿¡ ´ëÇØ ³íÀÇÇÔ.
-
-=back
-
-=head2 PerlÀ» ´õ ±í°Ô °øºÎÇϴµ¥ µµ¿òÀ» ÁÙ ¼ö ÀÖ´Â Çѱ¹¾î °ü·Ã »çÀÌÆ®
-
-=over 4
-
-=item L<http://www.perl.or.kr/>
-
- Perl Çѱ¹ »ç¿ëÀÚ ¸ðÀÓ
-
-=item L<news:han.comp.lang.perl/>
-
- Çѱ¹¾î Perl ´º½º ±×·ì
-
-=item L<http://www.hanb.co.kr/search/searchResult.html?keyword=perl>
-
- O'Reilly¿¡¼­ ³ª¿Â Çѱ¹¾î Perl ¼­Àû ¸ñ·Ï
-
-=item L<http://www.perlschool.net/>
-
- Perl ±âÃÊ °­Á ¹× ¼Ò½º, ÃÖ±Ù µ¿Çâ, °ü·Ã ÇØ¿Ü »çÀÌÆ® ¸µÅ©
-
-=item L<http://www.perl.co.kr>
-
- Perl¿¡ °ü·ÃµÈ CGI, DB, ¿¬µ¿ µî¿¡ ´ëÇÑ Á¤º¸ ¹× ´º½º Á¦°ø
-
-=back
-
-=head2 À¯´ÏÄÚµå ¹× Çѱ¹¾î ÀÎÄÚµù °ü·Ã ÀÚ·á
-
-=over 4
-
-=item L<http://www.unicode.org/>
-
- À¯´ÏÄÚµå ÄÁ¼Ò½Ã¾ö.
-
-=item L<http://std.dkuug.dk/JTC1/SC2/WG2>
-
-±âº»ÀûÀ¸·Î Unicode¿Í °°Àº ISO Ç¥ÁØÀÎ ISO/IEC 10646 UCS(Universal
-Character Set)À» ¸¸µå´Â ISO/IEC JTC1/SC2/WG2ÀÇ À¥ ÆäÀÌÁö.
-
-=item L<http://www.cl.cam.ac.uk/~mgk25/unicode.html>
-
- À¯´Ð½º/¸®´ª½º¿¡¼­ À¯´ÏÄÚµå¿Í UTF-8 »ç¿ë¿¡ ´ëÇÑ ¹®´äÁý(FAQ)
-
-=item L<http://wiki.kldp.org/Translations/html/UTF8-Unicode-KLDP/UTF8-Unicode-KLDP.html>
-
- À¯´Ð½º/¸®´ª½º¿¡¼­ À¯´ÏÄÚµå¿Í UTF-8 »ç¿ë¿¡ ´ëÇÑ ¹®´äÁý(FAQ)ÀÇ Çѱ¹¾î ¹ø¿ª
-
-=back
-
-=head1 SEE ALSO
-
-L<Encode>, L<Encode::KR>, L<encoding>, L<perluniintro>, L<perlunicode>
-
-
-=head1 AUTHORS
-
-Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>
-½ÅÁ¤½Ä E<lt>jshin@mailaps.orgE<gt>
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perllexwarn.pod b/Master/tlpkg/tlperl/lib/pods/perllexwarn.pod
deleted file mode 100644
index e63135915b9..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perllexwarn.pod
+++ /dev/null
@@ -1,545 +0,0 @@
-=head1 NAME
-X<warning, lexical> X<warnings> X<warning>
-
-perllexwarn - Perl Lexical Warnings
-
-=head1 DESCRIPTION
-
-The C<use warnings> pragma enables to control precisely what warnings are
-to be enabled in which parts of a Perl program. It's a more flexible
-alternative for both the command line flag B<-w> and the equivalent Perl
-variable, C<$^W>.
-
-This pragma works just like the C<strict> pragma.
-This means that the scope of the warning pragma is limited to the
-enclosing block. It also means that the pragma setting will not
-leak across files (via C<use>, C<require> or C<do>). This allows
-authors to independently define the degree of warning checks that will
-be applied to their module.
-
-By default, optional warnings are disabled, so any legacy code that
-doesn't attempt to control the warnings will work unchanged.
-
-All warnings are enabled in a block by either of these:
-
- use warnings;
- use warnings 'all';
-
-Similarly all warnings are disabled in a block by either of these:
-
- no warnings;
- no warnings 'all';
-
-For example, consider the code below:
-
- use warnings;
- my @a;
- {
- no warnings;
- my $b = @a[0];
- }
- my $c = @a[0];
-
-The code in the enclosing block has warnings enabled, but the inner
-block has them disabled. In this case that means the assignment to the
-scalar C<$c> will trip the C<"Scalar value @a[0] better written as $a[0]">
-warning, but the assignment to the scalar C<$b> will not.
-
-=head2 Default Warnings and Optional Warnings
-
-Before the introduction of lexical warnings, Perl had two classes of
-warnings: mandatory and optional.
-
-As its name suggests, if your code tripped a mandatory warning, you
-would get a warning whether you wanted it or not.
-For example, the code below would always produce an C<"isn't numeric">
-warning about the "2:".
-
- my $a = "2:" + 3;
-
-With the introduction of lexical warnings, mandatory warnings now become
-I<default> warnings. The difference is that although the previously
-mandatory warnings are still enabled by default, they can then be
-subsequently enabled or disabled with the lexical warning pragma. For
-example, in the code below, an C<"isn't numeric"> warning will only
-be reported for the C<$a> variable.
-
- my $a = "2:" + 3;
- no warnings;
- my $b = "2:" + 3;
-
-Note that neither the B<-w> flag or the C<$^W> can be used to
-disable/enable default warnings. They are still mandatory in this case.
-
-=head2 What's wrong with B<-w> and C<$^W>
-
-Although very useful, the big problem with using B<-w> on the command
-line to enable warnings is that it is all or nothing. Take the typical
-scenario when you are writing a Perl program. Parts of the code you
-will write yourself, but it's very likely that you will make use of
-pre-written Perl modules. If you use the B<-w> flag in this case, you
-end up enabling warnings in pieces of code that you haven't written.
-
-Similarly, using C<$^W> to either disable or enable blocks of code is
-fundamentally flawed. For a start, say you want to disable warnings in
-a block of code. You might expect this to be enough to do the trick:
-
- {
- local ($^W) = 0;
- my $a =+ 2;
- my $b; chop $b;
- }
-
-When this code is run with the B<-w> flag, a warning will be produced
-for the C<$a> line: C<"Reversed += operator">.
-
-The problem is that Perl has both compile-time and run-time warnings. To
-disable compile-time warnings you need to rewrite the code like this:
-
- {
- BEGIN { $^W = 0 }
- my $a =+ 2;
- my $b; chop $b;
- }
-
-The other big problem with C<$^W> is the way you can inadvertently
-change the warning setting in unexpected places in your code. For example,
-when the code below is run (without the B<-w> flag), the second call
-to C<doit> will trip a C<"Use of uninitialized value"> warning, whereas
-the first will not.
-
- sub doit
- {
- my $b; chop $b;
- }
-
- doit();
-
- {
- local ($^W) = 1;
- doit()
- }
-
-This is a side-effect of C<$^W> being dynamically scoped.
-
-Lexical warnings get around these limitations by allowing finer control
-over where warnings can or can't be tripped.
-
-=head2 Controlling Warnings from the Command Line
-
-There are three Command Line flags that can be used to control when
-warnings are (or aren't) produced:
-
-=over 5
-
-=item B<-w>
-X<-w>
-
-This is the existing flag. If the lexical warnings pragma is B<not>
-used in any of you code, or any of the modules that you use, this flag
-will enable warnings everywhere. See L<Backward Compatibility> for
-details of how this flag interacts with lexical warnings.
-
-=item B<-W>
-X<-W>
-
-If the B<-W> flag is used on the command line, it will enable all warnings
-throughout the program regardless of whether warnings were disabled
-locally using C<no warnings> or C<$^W =0>. This includes all files that get
-included via C<use>, C<require> or C<do>.
-Think of it as the Perl equivalent of the "lint" command.
-
-=item B<-X>
-X<-X>
-
-Does the exact opposite to the B<-W> flag, i.e. it disables all warnings.
-
-=back
-
-=head2 Backward Compatibility
-
-If you are used to working with a version of Perl prior to the
-introduction of lexically scoped warnings, or have code that uses both
-lexical warnings and C<$^W>, this section will describe how they interact.
-
-How Lexical Warnings interact with B<-w>/C<$^W>:
-
-=over 5
-
-=item 1.
-
-If none of the three command line flags (B<-w>, B<-W> or B<-X>) that
-control warnings is used and neither C<$^W> nor the C<warnings> pragma
-are used, then default warnings will be enabled and optional warnings
-disabled.
-This means that legacy code that doesn't attempt to control the warnings
-will work unchanged.
-
-=item 2.
-
-The B<-w> flag just sets the global C<$^W> variable as in 5.005. This
-means that any legacy code that currently relies on manipulating C<$^W>
-to control warning behavior will still work as is.
-
-=item 3.
-
-Apart from now being a boolean, the C<$^W> variable operates in exactly
-the same horrible uncontrolled global way, except that it cannot
-disable/enable default warnings.
-
-=item 4.
-
-If a piece of code is under the control of the C<warnings> pragma,
-both the C<$^W> variable and the B<-w> flag will be ignored for the
-scope of the lexical warning.
-
-=item 5.
-
-The only way to override a lexical warnings setting is with the B<-W>
-or B<-X> command line flags.
-
-=back
-
-The combined effect of 3 & 4 is that it will allow code which uses
-the C<warnings> pragma to control the warning behavior of $^W-type
-code (using a C<local $^W=0>) if it really wants to, but not vice-versa.
-
-=head2 Category Hierarchy
-X<warning, categories>
-
-A hierarchy of "categories" have been defined to allow groups of warnings
-to be enabled/disabled in isolation.
-
-The current hierarchy is:
-
- all -+
- |
- +- closure
- |
- +- deprecated
- |
- +- exiting
- |
- +- glob
- |
- +- io -----------+
- | |
- | +- closed
- | |
- | +- exec
- | |
- | +- layer
- | |
- | +- newline
- | |
- | +- pipe
- | |
- | +- unopened
- |
- +- imprecision
- |
- +- misc
- |
- +- numeric
- |
- +- once
- |
- +- overflow
- |
- +- pack
- |
- +- portable
- |
- +- recursion
- |
- +- redefine
- |
- +- regexp
- |
- +- severe -------+
- | |
- | +- debugging
- | |
- | +- inplace
- | |
- | +- internal
- | |
- | +- malloc
- |
- +- signal
- |
- +- substr
- |
- +- syntax -------+
- | |
- | +- ambiguous
- | |
- | +- bareword
- | |
- | +- digit
- | |
- | +- illegalproto
- | |
- | +- parenthesis
- | |
- | +- precedence
- | |
- | +- printf
- | |
- | +- prototype
- | |
- | +- qw
- | |
- | +- reserved
- | |
- | +- semicolon
- |
- +- taint
- |
- +- threads
- |
- +- uninitialized
- |
- +- unpack
- |
- +- untie
- |
- +- utf8----------+
- | |
- | +- surrogate
- | |
- | +- non_unicode
- | |
- | +- nonchar
- |
- +- void
-
-Just like the "strict" pragma any of these categories can be combined
-
- use warnings qw(void redefine);
- no warnings qw(io syntax untie);
-
-Also like the "strict" pragma, if there is more than one instance of the
-C<warnings> pragma in a given scope the cumulative effect is additive.
-
- use warnings qw(void); # only "void" warnings enabled
- ...
- use warnings qw(io); # only "void" & "io" warnings enabled
- ...
- no warnings qw(void); # only "io" warnings enabled
-
-To determine which category a specific warning has been assigned to see
-L<perldiag>.
-
-Note: In Perl 5.6.1, the lexical warnings category "deprecated" was a
-sub-category of the "syntax" category. It is now a top-level category
-in its own right.
-
-
-=head2 Fatal Warnings
-X<warning, fatal>
-
-The presence of the word "FATAL" in the category list will escalate any
-warnings detected from the categories specified in the lexical scope
-into fatal errors. In the code below, the use of C<time>, C<length>
-and C<join> can all produce a C<"Useless use of xxx in void context">
-warning.
-
- use warnings;
-
- time;
-
- {
- use warnings FATAL => qw(void);
- length "abc";
- }
-
- join "", 1,2,3;
-
- print "done\n";
-
-When run it produces this output
-
- Useless use of time in void context at fatal line 3.
- Useless use of length in void context at fatal line 7.
-
-The scope where C<length> is used has escalated the C<void> warnings
-category into a fatal error, so the program terminates immediately it
-encounters the warning.
-
-To explicitly turn off a "FATAL" warning you just disable the warning
-it is associated with. So, for example, to disable the "void" warning
-in the example above, either of these will do the trick:
-
- no warnings qw(void);
- no warnings FATAL => qw(void);
-
-If you want to downgrade a warning that has been escalated into a fatal
-error back to a normal warning, you can use the "NONFATAL" keyword. For
-example, the code below will promote all warnings into fatal errors,
-except for those in the "syntax" category.
-
- use warnings FATAL => 'all', NONFATAL => 'syntax';
-
-=head2 Reporting Warnings from a Module
-X<warning, reporting> X<warning, registering>
-
-The C<warnings> pragma provides a number of functions that are useful for
-module authors. These are used when you want to report a module-specific
-warning to a calling module has enabled warnings via the C<warnings>
-pragma.
-
-Consider the module C<MyMod::Abc> below.
-
- package MyMod::Abc;
-
- use warnings::register;
-
- sub open {
- my $path = shift;
- if ($path !~ m#^/#) {
- warnings::warn("changing relative path to /var/abc")
- if warnings::enabled();
- $path = "/var/abc/$path";
- }
- }
-
- 1;
-
-The call to C<warnings::register> will create a new warnings category
-called "MyMod::Abc", i.e. the new category name matches the current
-package name. The C<open> function in the module will display a warning
-message if it gets given a relative path as a parameter. This warnings
-will only be displayed if the code that uses C<MyMod::Abc> has actually
-enabled them with the C<warnings> pragma like below.
-
- use MyMod::Abc;
- use warnings 'MyMod::Abc';
- ...
- abc::open("../fred.txt");
-
-It is also possible to test whether the pre-defined warnings categories are
-set in the calling module with the C<warnings::enabled> function. Consider
-this snippet of code:
-
- package MyMod::Abc;
-
- sub open {
- warnings::warnif("deprecated",
- "open is deprecated, use new instead");
- new(@_);
- }
-
- sub new
- ...
- 1;
-
-The function C<open> has been deprecated, so code has been included to
-display a warning message whenever the calling module has (at least) the
-"deprecated" warnings category enabled. Something like this, say.
-
- use warnings 'deprecated';
- use MyMod::Abc;
- ...
- MyMod::Abc::open($filename);
-
-Either the C<warnings::warn> or C<warnings::warnif> function should be
-used to actually display the warnings message. This is because they can
-make use of the feature that allows warnings to be escalated into fatal
-errors. So in this case
-
- use MyMod::Abc;
- use warnings FATAL => 'MyMod::Abc';
- ...
- MyMod::Abc::open('../fred.txt');
-
-the C<warnings::warnif> function will detect this and die after
-displaying the warning message.
-
-The three warnings functions, C<warnings::warn>, C<warnings::warnif>
-and C<warnings::enabled> can optionally take an object reference in place
-of a category name. In this case the functions will use the class name
-of the object as the warnings category.
-
-Consider this example:
-
- package Original;
-
- no warnings;
- use warnings::register;
-
- sub new
- {
- my $class = shift;
- bless [], $class;
- }
-
- sub check
- {
- my $self = shift;
- my $value = shift;
-
- if ($value % 2 && warnings::enabled($self))
- { warnings::warn($self, "Odd numbers are unsafe") }
- }
-
- sub doit
- {
- my $self = shift;
- my $value = shift;
- $self->check($value);
- # ...
- }
-
- 1;
-
- package Derived;
-
- use warnings::register;
- use Original;
- our @ISA = qw( Original );
- sub new
- {
- my $class = shift;
- bless [], $class;
- }
-
-
- 1;
-
-The code below makes use of both modules, but it only enables warnings from
-C<Derived>.
-
- use Original;
- use Derived;
- use warnings 'Derived';
- my $a = Original->new();
- $a->doit(1);
- my $b = Derived->new();
- $a->doit(1);
-
-When this code is run only the C<Derived> object, C<$b>, will generate
-a warning.
-
- Odd numbers are unsafe at main.pl line 7
-
-Notice also that the warning is reported at the line where the object is first
-used.
-
-When registering new categories of warning, you can supply more names to
-warnings::register like this:
-
- package MyModule;
- use warnings::register qw(format precision);
-
- ...
-
- warnings::warnif('MyModule::format', '...');
-
-=head1 SEE ALSO
-
-L<warnings>, L<perldiag>.
-
-=head1 AUTHOR
-
-Paul Marquess
diff --git a/Master/tlpkg/tlperl/lib/pods/perllinux.pod b/Master/tlpkg/tlperl/lib/pods/perllinux.pod
deleted file mode 100644
index a191c520592..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perllinux.pod
+++ /dev/null
@@ -1,39 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see pod/perlpod.pod) which is
-specifically designed to be readable as is.
-
-=head1 NAME
-
-perllinux - Perl version 5 on Linux systems
-
-=head1 DESCRIPTION
-
-This document describes various features of Linux that will affect how Perl
-version 5 (hereafter just Perl) is compiled and/or runs.
-
-=head2 Experimental Support for Sun Studio Compilers for Linux OS
-
-Sun Microsystems has released a port of their Sun Studio compilers for
-Linux. As of November 2005, only an alpha version has been released.
-Until a release of these compilers is made, support for compiling Perl with
-these compiler experimental.
-
-Also, some special instructions for building Perl with Sun Studio on Linux.
-Following the normal C<Configure>, you have to run make as follows:
-
- LDLOADLIBS=-lc make
-
-C<LDLOADLIBS> is an environment variable used by the linker to link modules
-C</ext> modules to glibc. Currently, that environment variable is not getting
-populated by a combination of C<Config> entries and C<ExtUtil::MakeMaker>.
-While there may be a bug somewhere in Perl's configuration or
-C<ExtUtil::MakeMaker> causing the problem, the most likely cause is an
-incomplete understanding of Sun Studio by this author. Further investigation
-is needed to get this working better.
-
-=head1 AUTHOR
-
-Steve Peters <steve@fisharerojo.org>
-
-Please report any errors, updates, or suggestions to F<perlbug@perl.org>.
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perllocale.pod b/Master/tlpkg/tlperl/lib/pods/perllocale.pod
deleted file mode 100644
index 90543efa582..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perllocale.pod
+++ /dev/null
@@ -1,1281 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perllocale - Perl locale handling (internationalization and localization)
-
-=head1 DESCRIPTION
-
-In the beginning there was ASCII, the "American Standard Code for
-Information Interchange", which works quite well for Americans with
-their English alphabet and dollar-denominated currency. But it doesn't
-work so well even for other English speakers, who may use different
-currencies, such as the pound sterling (as the symbol for that currency
-is not in ASCII); and it's hopelessly inadequate for many of the
-thousands of the world's other languages.
-
-To address these deficiencies, the concept of locales was invented
-(formally the ISO C, XPG4, POSIX 1.c "locale system"). And applications
-were and are being written that use the locale mechanism. The process of
-making such an application take account of its users' preferences in
-these kinds of matters is called B<internationalization> (often
-abbreviated as B<i18n>); telling such an application about a particular
-set of preferences is known as B<localization> (B<l10n>).
-
-Perl was extended, starting in 5.004, to support the locale system. This
-is controlled per application by using one pragma, one function call,
-and several environment variables.
-
-Unfortunately, there are quite a few deficiencies with the design (and
-often, the implementations) of locales, and their use for character sets
-has mostly been supplanted by Unicode (see L<perlunitut> for an
-introduction to that, and keep on reading here for how Unicode interacts
-with locales in Perl).
-
-Perl continues to support the old locale system, and starting in v5.16,
-provides a hybrid way to use the Unicode character set, along with the
-other portions of locales that may not be so problematic.
-(Unicode is also creating C<CLDR>, the "Common Locale Data Repository",
-L<http://cldr.unicode.org/> which includes more types of information than
-are available in the POSIX locale system. At the time of this writing,
-there was no CPAN module that provides access to this XML-encoded data.
-However, many of its locales have the POSIX-only data extracted, and are
-available at L<http://unicode.org/Public/cldr/latest/>.)
-
-=head1 WHAT IS A LOCALE
-
-A locale is a set of data that describes various aspects of how various
-communities in the world categorize their world. These categories are
-broken down into the following types (some of which include a brief
-note here):
-
-=over
-
-=item Category LC_NUMERIC: Numeric formatting
-
-This indicates how numbers should be formatted for human readability,
-for example the character used as the decimal point.
-
-=item Category LC_MONETARY: Formatting of monetary amounts
-
-=for comment
-The nbsp below makes this look better
-
-E<160>
-
-=item Category LC_TIME: Date/Time formatting
-
-=for comment
-The nbsp below makes this look better
-
-E<160>
-
-=item Category LC_MESSAGES: Error and other messages
-
-This for the most part is beyond the scope of Perl
-
-=item Category LC_COLLATE: Collation
-
-This indicates the ordering of letters for comparision and sorting.
-In Latin alphabets, for example, "b", generally follows "a".
-
-=item Category LC_CTYPE: Character Types
-
-This indicates, for example if a character is an uppercase letter.
-
-=back
-
-More details on the categories are given below in L</LOCALE CATEGORIES>.
-
-Together, these categories go a long way towards being able to customize
-a single program to run in many different locations. But there are
-deficiencies, so keep reading.
-
-=head1 PREPARING TO USE LOCALES
-
-Perl will not use locales unless specifically requested to (see L</NOTES> below
-for the partial exception of C<write()>). But even if there is such a
-request, B<all> of the following must be true for it to work properly:
-
-=over 4
-
-=item *
-
-B<Your operating system must support the locale system>. If it does,
-you should find that the setlocale() function is a documented part of
-its C library.
-
-=item *
-
-B<Definitions for locales that you use must be installed>. You, or
-your system administrator, must make sure that this is the case. The
-available locales, the location in which they are kept, and the manner
-in which they are installed all vary from system to system. Some systems
-provide only a few, hard-wired locales and do not allow more to be
-added. Others allow you to add "canned" locales provided by the system
-supplier. Still others allow you or the system administrator to define
-and add arbitrary locales. (You may have to ask your supplier to
-provide canned locales that are not delivered with your operating
-system.) Read your system documentation for further illumination.
-
-=item *
-
-B<Perl must believe that the locale system is supported>. If it does,
-C<perl -V:d_setlocale> will say that the value for C<d_setlocale> is
-C<define>.
-
-=back
-
-If you want a Perl application to process and present your data
-according to a particular locale, the application code should include
-the S<C<use locale>> pragma (see L<The use locale pragma>) where
-appropriate, and B<at least one> of the following must be true:
-
-=over 4
-
-=item 1
-
-B<The locale-determining environment variables (see L</"ENVIRONMENT">)
-must be correctly set up> at the time the application is started, either
-by yourself or by whomever set up your system account; or
-
-=item 2
-
-B<The application must set its own locale> using the method described in
-L<The setlocale function>.
-
-=back
-
-=head1 USING LOCALES
-
-=head2 The use locale pragma
-
-By default, Perl ignores the current locale. The S<C<use locale>>
-pragma tells Perl to use the current locale for some operations.
-Starting in v5.16, there is an optional parameter to this pragma:
-
- use locale ':not_characters';
-
-This parameter allows better mixing of locales and Unicode, and is
-described fully in L</Unicode and UTF-8>, but briefly, it tells Perl to
-not use the character portions of the locale definition, that is
-the C<LC_CTYPE> and C<LC_COLLATE> categories. Instead it will use the
-native (extended by Unicode) character set. When using this parameter,
-you are responsible for getting the external character set translated
-into the native/Unicode one (which it already will be if it is one of
-the increasingly popular UTF-8 locales). There are convenient ways of
-doing this, as described in L</Unicode and UTF-8>.
-
-The current locale is set at execution time by
-L<setlocale()|/The setlocale function> described below. If that function
-hasn't yet been called in the course of the program's execution, the
-current locale is that which was determined by the L</"ENVIRONMENT"> in
-effect at the start of the program, except that
-C<L<LC_NUMERIC|/Category LC_NUMERIC: Numeric Formatting>> is always
-initialized to the C locale (mentioned under L<Finding locales>).
-If there is no valid environment, the current locale is undefined. It
-is likely, but not necessarily, the "C" locale.
-
-The operations that are affected by locale are:
-
-=over 4
-
-=item B<Under C<use locale ':not_characters';>>
-
-=over 4
-
-=item *
-
-B<Format declarations> (format()) use C<LC_NUMERIC>
-
-=item *
-
-B<The POSIX date formatting function> (strftime()) uses C<LC_TIME>.
-
-=back
-
-=for comment
-The nbsp below makes this look better
-
-E<160>
-
-=item B<Under just plain C<use locale;>>
-
-The above operations are affected, as well as the following:
-
-=over 4
-
-=item *
-
-B<The comparison operators> (C<lt>, C<le>, C<cmp>, C<ge>, and C<gt>) and
-the POSIX string collation functions strcoll() and strxfrm() use
-C<LC_COLLATE>. sort() is also affected if used without an
-explicit comparison function, because it uses C<cmp> by default.
-
-B<Note:> C<eq> and C<ne> are unaffected by locale: they always
-perform a char-by-char comparison of their scalar operands. What's
-more, if C<cmp> finds that its operands are equal according to the
-collation sequence specified by the current locale, it goes on to
-perform a char-by-char comparison, and only returns I<0> (equal) if the
-operands are char-for-char identical. If you really want to know whether
-two strings--which C<eq> and C<cmp> may consider different--are equal
-as far as collation in the locale is concerned, see the discussion in
-L<Category LC_COLLATE: Collation>.
-
-=item *
-
-B<Regular expressions and case-modification functions> (uc(), lc(),
-ucfirst(), and lcfirst()) use C<LC_CTYPE>
-
-=back
-
-=back
-
-The default behavior is restored with the S<C<no locale>> pragma, or
-upon reaching the end of the block enclosing C<use locale>.
-Note that C<use locale> and C<use locale ':not_characters'> may be
-nested, and that what is in effect within an inner scope will revert to
-the outer scope's rules at the end of the inner scope.
-
-The string result of any operation that uses locale
-information is tainted, as it is possible for a locale to be
-untrustworthy. See L<"SECURITY">.
-
-=head2 The setlocale function
-
-You can switch locales as often as you wish at run time with the
-POSIX::setlocale() function:
-
- # This functionality not usable prior to Perl 5.004
- require 5.004;
-
- # Import locale-handling tool set from POSIX module.
- # This example uses: setlocale -- the function call
- # LC_CTYPE -- explained below
- use POSIX qw(locale_h);
-
- # query and save the old locale
- $old_locale = setlocale(LC_CTYPE);
-
- setlocale(LC_CTYPE, "fr_CA.ISO8859-1");
- # LC_CTYPE now in locale "French, Canada, codeset ISO 8859-1"
-
- setlocale(LC_CTYPE, "");
- # LC_CTYPE now reset to default defined by LC_ALL/LC_CTYPE/LANG
- # environment variables. See below for documentation.
-
- # restore the old locale
- setlocale(LC_CTYPE, $old_locale);
-
-The first argument of setlocale() gives the B<category>, the second the
-B<locale>. The category tells in what aspect of data processing you
-want to apply locale-specific rules. Category names are discussed in
-L</LOCALE CATEGORIES> and L</"ENVIRONMENT">. The locale is the name of a
-collection of customization information corresponding to a particular
-combination of language, country or territory, and codeset. Read on for
-hints on the naming of locales: not all systems name locales as in the
-example.
-
-If no second argument is provided and the category is something else
-than LC_ALL, the function returns a string naming the current locale
-for the category. You can use this value as the second argument in a
-subsequent call to setlocale().
-
-If no second argument is provided and the category is LC_ALL, the
-result is implementation-dependent. It may be a string of
-concatenated locale names (separator also implementation-dependent)
-or a single locale name. Please consult your setlocale(3) man page for
-details.
-
-If a second argument is given and it corresponds to a valid locale,
-the locale for the category is set to that value, and the function
-returns the now-current locale value. You can then use this in yet
-another call to setlocale(). (In some implementations, the return
-value may sometimes differ from the value you gave as the second
-argument--think of it as an alias for the value you gave.)
-
-As the example shows, if the second argument is an empty string, the
-category's locale is returned to the default specified by the
-corresponding environment variables. Generally, this results in a
-return to the default that was in force when Perl started up: changes
-to the environment made by the application after startup may or may not
-be noticed, depending on your system's C library.
-
-If the second argument does not correspond to a valid locale, the locale
-for the category is not changed, and the function returns I<undef>.
-
-Note that Perl ignores the current C<LC_CTYPE> and C<LC_COLLATE> locales
-within the scope of a C<use locale ':not_characters'>.
-
-For further information about the categories, consult setlocale(3).
-
-=head2 Finding locales
-
-For locales available in your system, consult also setlocale(3) to
-see whether it leads to the list of available locales (search for the
-I<SEE ALSO> section). If that fails, try the following command lines:
-
- locale -a
-
- nlsinfo
-
- ls /usr/lib/nls/loc
-
- ls /usr/lib/locale
-
- ls /usr/lib/nls
-
- ls /usr/share/locale
-
-and see whether they list something resembling these
-
- en_US.ISO8859-1 de_DE.ISO8859-1 ru_RU.ISO8859-5
- en_US.iso88591 de_DE.iso88591 ru_RU.iso88595
- en_US de_DE ru_RU
- en de ru
- english german russian
- english.iso88591 german.iso88591 russian.iso88595
- english.roman8 russian.koi8r
-
-Sadly, even though the calling interface for setlocale() has been
-standardized, names of locales and the directories where the
-configuration resides have not been. The basic form of the name is
-I<language_territory>B<.>I<codeset>, but the latter parts after
-I<language> are not always present. The I<language> and I<country>
-are usually from the standards B<ISO 3166> and B<ISO 639>, the
-two-letter abbreviations for the countries and the languages of the
-world, respectively. The I<codeset> part often mentions some B<ISO
-8859> character set, the Latin codesets. For example, C<ISO 8859-1>
-is the so-called "Western European codeset" that can be used to encode
-most Western European languages adequately. Again, there are several
-ways to write even the name of that one standard. Lamentably.
-
-Two special locales are worth particular mention: "C" and "POSIX".
-Currently these are effectively the same locale: the difference is
-mainly that the first one is defined by the C standard, the second by
-the POSIX standard. They define the B<default locale> in which
-every program starts in the absence of locale information in its
-environment. (The I<default> default locale, if you will.) Its language
-is (American) English and its character codeset ASCII.
-B<Warning>. The C locale delivered by some vendors may not
-actually exactly match what the C standard calls for. So beware.
-
-B<NOTE>: Not all systems have the "POSIX" locale (not all systems are
-POSIX-conformant), so use "C" when you need explicitly to specify this
-default locale.
-
-=head2 LOCALE PROBLEMS
-
-You may encounter the following warning message at Perl startup:
-
- perl: warning: Setting locale failed.
- perl: warning: Please check that your locale settings:
- LC_ALL = "En_US",
- LANG = (unset)
- are supported and installed on your system.
- perl: warning: Falling back to the standard locale ("C").
-
-This means that your locale settings had LC_ALL set to "En_US" and
-LANG exists but has no value. Perl tried to believe you but could not.
-Instead, Perl gave up and fell back to the "C" locale, the default locale
-that is supposed to work no matter what. This usually means your locale
-settings were wrong, they mention locales your system has never heard
-of, or the locale installation in your system has problems (for example,
-some system files are broken or missing). There are quick and temporary
-fixes to these problems, as well as more thorough and lasting fixes.
-
-=head2 Temporarily fixing locale problems
-
-The two quickest fixes are either to render Perl silent about any
-locale inconsistencies or to run Perl under the default locale "C".
-
-Perl's moaning about locale problems can be silenced by setting the
-environment variable PERL_BADLANG to a zero value, for example "0".
-This method really just sweeps the problem under the carpet: you tell
-Perl to shut up even when Perl sees that something is wrong. Do not
-be surprised if later something locale-dependent misbehaves.
-
-Perl can be run under the "C" locale by setting the environment
-variable LC_ALL to "C". This method is perhaps a bit more civilized
-than the PERL_BADLANG approach, but setting LC_ALL (or
-other locale variables) may affect other programs as well, not just
-Perl. In particular, external programs run from within Perl will see
-these changes. If you make the new settings permanent (read on), all
-programs you run see the changes. See L<"ENVIRONMENT"> for
-the full list of relevant environment variables and L<USING LOCALES>
-for their effects in Perl. Effects in other programs are
-easily deducible. For example, the variable LC_COLLATE may well affect
-your B<sort> program (or whatever the program that arranges "records"
-alphabetically in your system is called).
-
-You can test out changing these variables temporarily, and if the
-new settings seem to help, put those settings into your shell startup
-files. Consult your local documentation for the exact details. For in
-Bourne-like shells (B<sh>, B<ksh>, B<bash>, B<zsh>):
-
- LC_ALL=en_US.ISO8859-1
- export LC_ALL
-
-This assumes that we saw the locale "en_US.ISO8859-1" using the commands
-discussed above. We decided to try that instead of the above faulty
-locale "En_US"--and in Cshish shells (B<csh>, B<tcsh>)
-
- setenv LC_ALL en_US.ISO8859-1
-
-or if you have the "env" application you can do in any shell
-
- env LC_ALL=en_US.ISO8859-1 perl ...
-
-If you do not know what shell you have, consult your local
-helpdesk or the equivalent.
-
-=head2 Permanently fixing locale problems
-
-The slower but superior fixes are when you may be able to yourself
-fix the misconfiguration of your own environment variables. The
-mis(sing)configuration of the whole system's locales usually requires
-the help of your friendly system administrator.
-
-First, see earlier in this document about L<Finding locales>. That tells
-how to find which locales are really supported--and more importantly,
-installed--on your system. In our example error message, environment
-variables affecting the locale are listed in the order of decreasing
-importance (and unset variables do not matter). Therefore, having
-LC_ALL set to "En_US" must have been the bad choice, as shown by the
-error message. First try fixing locale settings listed first.
-
-Second, if using the listed commands you see something B<exactly>
-(prefix matches do not count and case usually counts) like "En_US"
-without the quotes, then you should be okay because you are using a
-locale name that should be installed and available in your system.
-In this case, see L<Permanently fixing your system's locale configuration>.
-
-=head2 Permanently fixing your system's locale configuration
-
-This is when you see something like:
-
- perl: warning: Please check that your locale settings:
- LC_ALL = "En_US",
- LANG = (unset)
- are supported and installed on your system.
-
-but then cannot see that "En_US" listed by the above-mentioned
-commands. You may see things like "en_US.ISO8859-1", but that isn't
-the same. In this case, try running under a locale
-that you can list and which somehow matches what you tried. The
-rules for matching locale names are a bit vague because
-standardization is weak in this area. See again the
-L<Finding locales> about general rules.
-
-=head2 Fixing system locale configuration
-
-Contact a system administrator (preferably your own) and report the exact
-error message you get, and ask them to read this same documentation you
-are now reading. They should be able to check whether there is something
-wrong with the locale configuration of the system. The L<Finding locales>
-section is unfortunately a bit vague about the exact commands and places
-because these things are not that standardized.
-
-=head2 The localeconv function
-
-The POSIX::localeconv() function allows you to get particulars of the
-locale-dependent numeric formatting information specified by the current
-C<LC_NUMERIC> and C<LC_MONETARY> locales. (If you just want the name of
-the current locale for a particular category, use POSIX::setlocale()
-with a single parameter--see L<The setlocale function>.)
-
- use POSIX qw(locale_h);
-
- # Get a reference to a hash of locale-dependent info
- $locale_values = localeconv();
-
- # Output sorted list of the values
- for (sort keys %$locale_values) {
- printf "%-20s = %s\n", $_, $locale_values->{$_}
- }
-
-localeconv() takes no arguments, and returns B<a reference to> a hash.
-The keys of this hash are variable names for formatting, such as
-C<decimal_point> and C<thousands_sep>. The values are the
-corresponding, er, values. See L<POSIX/localeconv> for a longer
-example listing the categories an implementation might be expected to
-provide; some provide more and others fewer. You don't need an
-explicit C<use locale>, because localeconv() always observes the
-current locale.
-
-Here's a simple-minded example program that rewrites its command-line
-parameters as integers correctly formatted in the current locale:
-
- # See comments in previous example
- require 5.004;
- use POSIX qw(locale_h);
-
- # Get some of locale's numeric formatting parameters
- my ($thousands_sep, $grouping) =
- @{localeconv()}{'thousands_sep', 'grouping'};
-
- # Apply defaults if values are missing
- $thousands_sep = ',' unless $thousands_sep;
-
- # grouping and mon_grouping are packed lists
- # of small integers (characters) telling the
- # grouping (thousand_seps and mon_thousand_seps
- # being the group dividers) of numbers and
- # monetary quantities. The integers' meanings:
- # 255 means no more grouping, 0 means repeat
- # the previous grouping, 1-254 means use that
- # as the current grouping. Grouping goes from
- # right to left (low to high digits). In the
- # below we cheat slightly by never using anything
- # else than the first grouping (whatever that is).
- if ($grouping) {
- @grouping = unpack("C*", $grouping);
- } else {
- @grouping = (3);
- }
-
- # Format command line params for current locale
- for (@ARGV) {
- $_ = int; # Chop non-integer part
- 1 while
- s/(\d)(\d{$grouping[0]}($|$thousands_sep))/$1$thousands_sep$2/;
- print "$_";
- }
- print "\n";
-
-=head2 I18N::Langinfo
-
-Another interface for querying locale-dependent information is the
-I18N::Langinfo::langinfo() function, available at least in Unix-like
-systems and VMS.
-
-The following example will import the langinfo() function itself and
-three constants to be used as arguments to langinfo(): a constant for
-the abbreviated first day of the week (the numbering starts from
-Sunday = 1) and two more constants for the affirmative and negative
-answers for a yes/no question in the current locale.
-
- use I18N::Langinfo qw(langinfo ABDAY_1 YESSTR NOSTR);
-
- my ($abday_1, $yesstr, $nostr)
- = map { langinfo } qw(ABDAY_1 YESSTR NOSTR);
-
- print "$abday_1? [$yesstr/$nostr] ";
-
-In other words, in the "C" (or English) locale the above will probably
-print something like:
-
- Sun? [yes/no]
-
-See L<I18N::Langinfo> for more information.
-
-=head1 LOCALE CATEGORIES
-
-The following subsections describe basic locale categories. Beyond these,
-some combination categories allow manipulation of more than one
-basic category at a time. See L<"ENVIRONMENT"> for a discussion of these.
-
-=head2 Category LC_COLLATE: Collation
-
-In the scope of S<C<use locale>> (but not a
-C<use locale ':not_characters'>), Perl looks to the C<LC_COLLATE>
-environment variable to determine the application's notions on collation
-(ordering) of characters. For example, "b" follows "a" in Latin
-alphabets, but where do "E<aacute>" and "E<aring>" belong? And while
-"color" follows "chocolate" in English, what about in Spanish?
-
-The following collations all make sense and you may meet any of them
-if you "use locale".
-
- A B C D E a b c d e
- A a B b C c D d E e
- a A b B c C d D e E
- a b c d e A B C D E
-
-Here is a code snippet to tell what "word"
-characters are in the current locale, in that locale's order:
-
- use locale;
- print +(sort grep /\w/, map { chr } 0..255), "\n";
-
-Compare this with the characters that you see and their order if you
-state explicitly that the locale should be ignored:
-
- no locale;
- print +(sort grep /\w/, map { chr } 0..255), "\n";
-
-This machine-native collation (which is what you get unless S<C<use
-locale>> has appeared earlier in the same block) must be used for
-sorting raw binary data, whereas the locale-dependent collation of the
-first example is useful for natural text.
-
-As noted in L<USING LOCALES>, C<cmp> compares according to the current
-collation locale when C<use locale> is in effect, but falls back to a
-char-by-char comparison for strings that the locale says are equal. You
-can use POSIX::strcoll() if you don't want this fall-back:
-
- use POSIX qw(strcoll);
- $equal_in_locale =
- !strcoll("space and case ignored", "SpaceAndCaseIgnored");
-
-$equal_in_locale will be true if the collation locale specifies a
-dictionary-like ordering that ignores space characters completely and
-which folds case.
-
-If you have a single string that you want to check for "equality in
-locale" against several others, you might think you could gain a little
-efficiency by using POSIX::strxfrm() in conjunction with C<eq>:
-
- use POSIX qw(strxfrm);
- $xfrm_string = strxfrm("Mixed-case string");
- print "locale collation ignores spaces\n"
- if $xfrm_string eq strxfrm("Mixed-casestring");
- print "locale collation ignores hyphens\n"
- if $xfrm_string eq strxfrm("Mixedcase string");
- print "locale collation ignores case\n"
- if $xfrm_string eq strxfrm("mixed-case string");
-
-strxfrm() takes a string and maps it into a transformed string for use
-in char-by-char comparisons against other transformed strings during
-collation. "Under the hood", locale-affected Perl comparison operators
-call strxfrm() for both operands, then do a char-by-char
-comparison of the transformed strings. By calling strxfrm() explicitly
-and using a non locale-affected comparison, the example attempts to save
-a couple of transformations. But in fact, it doesn't save anything: Perl
-magic (see L<perlguts/Magic Variables>) creates the transformed version of a
-string the first time it's needed in a comparison, then keeps this version around
-in case it's needed again. An example rewritten the easy way with
-C<cmp> runs just about as fast. It also copes with null characters
-embedded in strings; if you call strxfrm() directly, it treats the first
-null it finds as a terminator. don't expect the transformed strings
-it produces to be portable across systems--or even from one revision
-of your operating system to the next. In short, don't call strxfrm()
-directly: let Perl do it for you.
-
-Note: C<use locale> isn't shown in some of these examples because it isn't
-needed: strcoll() and strxfrm() exist only to generate locale-dependent
-results, and so always obey the current C<LC_COLLATE> locale.
-
-=head2 Category LC_CTYPE: Character Types
-
-In the scope of S<C<use locale>> (but not a
-C<use locale ':not_characters'>), Perl obeys the C<LC_CTYPE> locale
-setting. This controls the application's notion of which characters are
-alphabetic. This affects Perl's C<\w> regular expression metanotation,
-which stands for alphanumeric characters--that is, alphabetic,
-numeric, and including other special characters such as the underscore or
-hyphen. (Consult L<perlre> for more information about
-regular expressions.) Thanks to C<LC_CTYPE>, depending on your locale
-setting, characters like "E<aelig>", "E<eth>", "E<szlig>", and
-"E<oslash>" may be understood as C<\w> characters.
-
-The C<LC_CTYPE> locale also provides the map used in transliterating
-characters between lower and uppercase. This affects the case-mapping
-functions--lc(), lcfirst, uc(), and ucfirst(); case-mapping
-interpolation with C<\l>, C<\L>, C<\u>, or C<\U> in double-quoted strings
-and C<s///> substitutions; and case-independent regular expression
-pattern matching using the C<i> modifier.
-
-Finally, C<LC_CTYPE> affects the POSIX character-class test
-functions--isalpha(), islower(), and so on. For example, if you move
-from the "C" locale to a 7-bit Scandinavian one, you may find--possibly
-to your surprise--that "|" moves from the ispunct() class to isalpha().
-Unfortunately, this creates big problems for regular expressions. "|" still
-means alternation even though it matches C<\w>.
-
-B<Note:> A broken or malicious C<LC_CTYPE> locale definition may result
-in clearly ineligible characters being considered to be alphanumeric by
-your application. For strict matching of (mundane) ASCII letters and
-digits--for example, in command strings--locale-aware applications
-should use C<\w> with the C</a> regular expression modifier. See L<"SECURITY">.
-
-=head2 Category LC_NUMERIC: Numeric Formatting
-
-After a proper POSIX::setlocale() call, Perl obeys the C<LC_NUMERIC>
-locale information, which controls an application's idea of how numbers
-should be formatted for human readability by the printf(), sprintf(), and
-write() functions. String-to-numeric conversion by the POSIX::strtod()
-function is also affected. In most implementations the only effect is to
-change the character used for the decimal point--perhaps from "." to ",".
-These functions aren't aware of such niceties as thousands separation and
-so on. (See L<The localeconv function> if you care about these things.)
-
-Output produced by print() is also affected by the current locale: it
-corresponds to what you'd get from printf() in the "C" locale. The
-same is true for Perl's internal conversions between numeric and
-string formats:
-
- use POSIX qw(strtod setlocale LC_NUMERIC);
-
- setlocale LC_NUMERIC, "";
-
- $n = 5/2; # Assign numeric 2.5 to $n
-
- $a = " $n"; # Locale-dependent conversion to string
-
- print "half five is $n\n"; # Locale-dependent output
-
- printf "half five is %g\n", $n; # Locale-dependent output
-
- print "DECIMAL POINT IS COMMA\n"
- if $n == (strtod("2,5"))[0]; # Locale-dependent conversion
-
-See also L<I18N::Langinfo> and C<RADIXCHAR>.
-
-=head2 Category LC_MONETARY: Formatting of monetary amounts
-
-The C standard defines the C<LC_MONETARY> category, but not a function
-that is affected by its contents. (Those with experience of standards
-committees will recognize that the working group decided to punt on the
-issue.) Consequently, Perl takes no notice of it. If you really want
-to use C<LC_MONETARY>, you can query its contents--see
-L<The localeconv function>--and use the information that it returns in your
-application's own formatting of currency amounts. However, you may well
-find that the information, voluminous and complex though it may be, still
-does not quite meet your requirements: currency formatting is a hard nut
-to crack.
-
-See also L<I18N::Langinfo> and C<CRNCYSTR>.
-
-=head2 LC_TIME
-
-Output produced by POSIX::strftime(), which builds a formatted
-human-readable date/time string, is affected by the current C<LC_TIME>
-locale. Thus, in a French locale, the output produced by the C<%B>
-format element (full month name) for the first month of the year would
-be "janvier". Here's how to get a list of long month names in the
-current locale:
-
- use POSIX qw(strftime);
- for (0..11) {
- $long_month_name[$_] =
- strftime("%B", 0, 0, 0, 1, $_, 96);
- }
-
-Note: C<use locale> isn't needed in this example: as a function that
-exists only to generate locale-dependent results, strftime() always
-obeys the current C<LC_TIME> locale.
-
-See also L<I18N::Langinfo> and C<ABDAY_1>..C<ABDAY_7>, C<DAY_1>..C<DAY_7>,
-C<ABMON_1>..C<ABMON_12>, and C<ABMON_1>..C<ABMON_12>.
-
-=head2 Other categories
-
-The remaining locale category, C<LC_MESSAGES> (possibly supplemented
-by others in particular implementations) is not currently used by
-Perl--except possibly to affect the behavior of library functions
-called by extensions outside the standard Perl distribution and by the
-operating system and its utilities. Note especially that the string
-value of C<$!> and the error messages given by external utilities may
-be changed by C<LC_MESSAGES>. If you want to have portable error
-codes, use C<%!>. See L<Errno>.
-
-=head1 SECURITY
-
-Although the main discussion of Perl security issues can be found in
-L<perlsec>, a discussion of Perl's locale handling would be incomplete
-if it did not draw your attention to locale-dependent security issues.
-Locales--particularly on systems that allow unprivileged users to
-build their own locales--are untrustworthy. A malicious (or just plain
-broken) locale can make a locale-aware application give unexpected
-results. Here are a few possibilities:
-
-=over 4
-
-=item *
-
-Regular expression checks for safe file names or mail addresses using
-C<\w> may be spoofed by an C<LC_CTYPE> locale that claims that
-characters such as "E<gt>" and "|" are alphanumeric.
-
-=item *
-
-String interpolation with case-mapping, as in, say, C<$dest =
-"C:\U$name.$ext">, may produce dangerous results if a bogus LC_CTYPE
-case-mapping table is in effect.
-
-=item *
-
-A sneaky C<LC_COLLATE> locale could result in the names of students with
-"D" grades appearing ahead of those with "A"s.
-
-=item *
-
-An application that takes the trouble to use information in
-C<LC_MONETARY> may format debits as if they were credits and vice versa
-if that locale has been subverted. Or it might make payments in US
-dollars instead of Hong Kong dollars.
-
-=item *
-
-The date and day names in dates formatted by strftime() could be
-manipulated to advantage by a malicious user able to subvert the
-C<LC_DATE> locale. ("Look--it says I wasn't in the building on
-Sunday.")
-
-=back
-
-Such dangers are not peculiar to the locale system: any aspect of an
-application's environment which may be modified maliciously presents
-similar challenges. Similarly, they are not specific to Perl: any
-programming language that allows you to write programs that take
-account of their environment exposes you to these issues.
-
-Perl cannot protect you from all possibilities shown in the
-examples--there is no substitute for your own vigilance--but, when
-C<use locale> is in effect, Perl uses the tainting mechanism (see
-L<perlsec>) to mark string results that become locale-dependent, and
-which may be untrustworthy in consequence. Here is a summary of the
-tainting behavior of operators and functions that may be affected by
-the locale:
-
-=over 4
-
-=item *
-
-B<Comparison operators> (C<lt>, C<le>, C<ge>, C<gt> and C<cmp>):
-
-Scalar true/false (or less/equal/greater) result is never tainted.
-
-=item *
-
-B<Case-mapping interpolation> (with C<\l>, C<\L>, C<\u> or C<\U>)
-
-Result string containing interpolated material is tainted if
-C<use locale> (but not S<C<use locale ':not_characters'>>) is in effect.
-
-=item *
-
-B<Matching operator> (C<m//>):
-
-Scalar true/false result never tainted.
-
-Subpatterns, either delivered as a list-context result or as $1 etc.
-are tainted if C<use locale> (but not S<C<use locale ':not_characters'>>)
-is in effect, and the subpattern regular
-expression contains C<\w> (to match an alphanumeric character), C<\W>
-(non-alphanumeric character), C<\s> (whitespace character), or C<\S>
-(non whitespace character). The matched-pattern variable, $&, $`
-(pre-match), $' (post-match), and $+ (last match) are also tainted if
-C<use locale> is in effect and the regular expression contains C<\w>,
-C<\W>, C<\s>, or C<\S>.
-
-=item *
-
-B<Substitution operator> (C<s///>):
-
-Has the same behavior as the match operator. Also, the left
-operand of C<=~> becomes tainted when C<use locale>
-(but not S<C<use locale ':not_characters'>>) is in effect if modified as
-a result of a substitution based on a regular
-expression match involving C<\w>, C<\W>, C<\s>, or C<\S>; or of
-case-mapping with C<\l>, C<\L>,C<\u> or C<\U>.
-
-=item *
-
-B<Output formatting functions> (printf() and write()):
-
-Results are never tainted because otherwise even output from print,
-for example C<print(1/7)>, should be tainted if C<use locale> is in
-effect.
-
-=item *
-
-B<Case-mapping functions> (lc(), lcfirst(), uc(), ucfirst()):
-
-Results are tainted if C<use locale> (but not
-S<C<use locale ':not_characters'>>) is in effect.
-
-=item *
-
-B<POSIX locale-dependent functions> (localeconv(), strcoll(),
-strftime(), strxfrm()):
-
-Results are never tainted.
-
-=item *
-
-B<POSIX character class tests> (isalnum(), isalpha(), isdigit(),
-isgraph(), islower(), isprint(), ispunct(), isspace(), isupper(),
-isxdigit()):
-
-True/false results are never tainted.
-
-=back
-
-Three examples illustrate locale-dependent tainting.
-The first program, which ignores its locale, won't run: a value taken
-directly from the command line may not be used to name an output file
-when taint checks are enabled.
-
- #/usr/local/bin/perl -T
- # Run with taint checking
-
- # Command line sanity check omitted...
- $tainted_output_file = shift;
-
- open(F, ">$tainted_output_file")
- or warn "Open of $untainted_output_file failed: $!\n";
-
-The program can be made to run by "laundering" the tainted value through
-a regular expression: the second example--which still ignores locale
-information--runs, creating the file named on its command line
-if it can.
-
- #/usr/local/bin/perl -T
-
- $tainted_output_file = shift;
- $tainted_output_file =~ m%[\w/]+%;
- $untainted_output_file = $&;
-
- open(F, ">$untainted_output_file")
- or warn "Open of $untainted_output_file failed: $!\n";
-
-Compare this with a similar but locale-aware program:
-
- #/usr/local/bin/perl -T
-
- $tainted_output_file = shift;
- use locale;
- $tainted_output_file =~ m%[\w/]+%;
- $localized_output_file = $&;
-
- open(F, ">$localized_output_file")
- or warn "Open of $localized_output_file failed: $!\n";
-
-This third program fails to run because $& is tainted: it is the result
-of a match involving C<\w> while C<use locale> is in effect.
-
-=head1 ENVIRONMENT
-
-=over 12
-
-=item PERL_BADLANG
-
-A string that can suppress Perl's warning about failed locale settings
-at startup. Failure can occur if the locale support in the operating
-system is lacking (broken) in some way--or if you mistyped the name of
-a locale when you set up your environment. If this environment
-variable is absent, or has a value that does not evaluate to integer
-zero--that is, "0" or ""-- Perl will complain about locale setting
-failures.
-
-B<NOTE>: PERL_BADLANG only gives you a way to hide the warning message.
-The message tells about some problem in your system's locale support,
-and you should investigate what the problem is.
-
-=back
-
-The following environment variables are not specific to Perl: They are
-part of the standardized (ISO C, XPG4, POSIX 1.c) setlocale() method
-for controlling an application's opinion on data.
-
-=over 12
-
-=item LC_ALL
-
-C<LC_ALL> is the "override-all" locale environment variable. If
-set, it overrides all the rest of the locale environment variables.
-
-=item LANGUAGE
-
-B<NOTE>: C<LANGUAGE> is a GNU extension, it affects you only if you
-are using the GNU libc. This is the case if you are using e.g. Linux.
-If you are using "commercial" Unixes you are most probably I<not>
-using GNU libc and you can ignore C<LANGUAGE>.
-
-However, in the case you are using C<LANGUAGE>: it affects the
-language of informational, warning, and error messages output by
-commands (in other words, it's like C<LC_MESSAGES>) but it has higher
-priority than C<LC_ALL>. Moreover, it's not a single value but
-instead a "path" (":"-separated list) of I<languages> (not locales).
-See the GNU C<gettext> library documentation for more information.
-
-=item LC_CTYPE
-
-In the absence of C<LC_ALL>, C<LC_CTYPE> chooses the character type
-locale. In the absence of both C<LC_ALL> and C<LC_CTYPE>, C<LANG>
-chooses the character type locale.
-
-=item LC_COLLATE
-
-In the absence of C<LC_ALL>, C<LC_COLLATE> chooses the collation
-(sorting) locale. In the absence of both C<LC_ALL> and C<LC_COLLATE>,
-C<LANG> chooses the collation locale.
-
-=item LC_MONETARY
-
-In the absence of C<LC_ALL>, C<LC_MONETARY> chooses the monetary
-formatting locale. In the absence of both C<LC_ALL> and C<LC_MONETARY>,
-C<LANG> chooses the monetary formatting locale.
-
-=item LC_NUMERIC
-
-In the absence of C<LC_ALL>, C<LC_NUMERIC> chooses the numeric format
-locale. In the absence of both C<LC_ALL> and C<LC_NUMERIC>, C<LANG>
-chooses the numeric format.
-
-=item LC_TIME
-
-In the absence of C<LC_ALL>, C<LC_TIME> chooses the date and time
-formatting locale. In the absence of both C<LC_ALL> and C<LC_TIME>,
-C<LANG> chooses the date and time formatting locale.
-
-=item LANG
-
-C<LANG> is the "catch-all" locale environment variable. If it is set, it
-is used as the last resort after the overall C<LC_ALL> and the
-category-specific C<LC_...>.
-
-=back
-
-=head2 Examples
-
-The LC_NUMERIC controls the numeric output:
-
- use locale;
- use POSIX qw(locale_h); # Imports setlocale() and the LC_ constants.
- setlocale(LC_NUMERIC, "fr_FR") or die "Pardon";
- printf "%g\n", 1.23; # If the "fr_FR" succeeded, probably shows 1,23.
-
-and also how strings are parsed by POSIX::strtod() as numbers:
-
- use locale;
- use POSIX qw(locale_h strtod);
- setlocale(LC_NUMERIC, "de_DE") or die "Entschuldigung";
- my $x = strtod("2,34") + 5;
- print $x, "\n"; # Probably shows 7,34.
-
-=head1 NOTES
-
-=head2 Backward compatibility
-
-Versions of Perl prior to 5.004 B<mostly> ignored locale information,
-generally behaving as if something similar to the C<"C"> locale were
-always in force, even if the program environment suggested otherwise
-(see L<The setlocale function>). By default, Perl still behaves this
-way for backward compatibility. If you want a Perl application to pay
-attention to locale information, you B<must> use the S<C<use locale>>
-pragma (see L<The use locale pragma>) or, in the unlikely event
-that you want to do so for just pattern matching, the
-C</l> regular expression modifier (see L<perlre/Character set
-modifiers>) to instruct it to do so.
-
-Versions of Perl from 5.002 to 5.003 did use the C<LC_CTYPE>
-information if available; that is, C<\w> did understand what
-were the letters according to the locale environment variables.
-The problem was that the user had no control over the feature:
-if the C library supported locales, Perl used them.
-
-=head2 I18N:Collate obsolete
-
-In versions of Perl prior to 5.004, per-locale collation was possible
-using the C<I18N::Collate> library module. This module is now mildly
-obsolete and should be avoided in new applications. The C<LC_COLLATE>
-functionality is now integrated into the Perl core language: One can
-use locale-specific scalar data completely normally with C<use locale>,
-so there is no longer any need to juggle with the scalar references of
-C<I18N::Collate>.
-
-=head2 Sort speed and memory use impacts
-
-Comparing and sorting by locale is usually slower than the default
-sorting; slow-downs of two to four times have been observed. It will
-also consume more memory: once a Perl scalar variable has participated
-in any string comparison or sorting operation obeying the locale
-collation rules, it will take 3-15 times more memory than before. (The
-exact multiplier depends on the string's contents, the operating system
-and the locale.) These downsides are dictated more by the operating
-system's implementation of the locale system than by Perl.
-
-=head2 write() and LC_NUMERIC
-
-If a program's environment specifies an LC_NUMERIC locale and C<use
-locale> is in effect when the format is declared, the locale is used
-to specify the decimal point character in formatted output. Formatted
-output cannot be controlled by C<use locale> at the time when write()
-is called.
-
-=head2 Freely available locale definitions
-
-The Unicode CLDR project extracts the POSIX portion of many of its
-locales, available at
-
- http://unicode.org/Public/cldr/latest/
-
-There is a large collection of locale definitions at:
-
- http://std.dkuug.dk/i18n/WG15-collection/locales/
-
-You should be aware that it is
-unsupported, and is not claimed to be fit for any purpose. If your
-system allows installation of arbitrary locales, you may find the
-definitions useful as they are, or as a basis for the development of
-your own locales.
-
-=head2 I18n and l10n
-
-"Internationalization" is often abbreviated as B<i18n> because its first
-and last letters are separated by eighteen others. (You may guess why
-the internalin ... internaliti ... i18n tends to get abbreviated.) In
-the same way, "localization" is often abbreviated to B<l10n>.
-
-=head2 An imperfect standard
-
-Internationalization, as defined in the C and POSIX standards, can be
-criticized as incomplete, ungainly, and having too large a granularity.
-(Locales apply to a whole process, when it would arguably be more useful
-to have them apply to a single thread, window group, or whatever.) They
-also have a tendency, like standards groups, to divide the world into
-nations, when we all know that the world can equally well be divided
-into bankers, bikers, gamers, and so on.
-
-=head1 Unicode and UTF-8
-
-The support of Unicode is new starting from Perl version v5.6, and more fully
-implemented in version v5.8 and later. See L<perluniintro>. It is
-strongly recommended that when combining Unicode and locale (starting in
-v5.16), you use
-
- use locale ':not_characters';
-
-When this form of the pragma is used, only the non-character portions of
-locales are used by Perl, for example C<LC_NUMERIC>. Perl assumes that
-you have translated all the characters it is to operate on into Unicode
-(actually the platform's native character set (ASCII or EBCDIC) plus
-Unicode). For data in files, this can conveniently be done by also
-specifying
-
- use open ':locale';
-
-This pragma arranges for all inputs from files to be translated into
-Unicode from the current locale as specified in the environment (see
-L</ENVIRONMENT>), and all outputs to files to be translated back
-into the locale. (See L<open>). On a per-filehandle basis, you can
-instead use the L<PerlIO::locale> module, or the L<Encode::Locale>
-module, both available from CPAN. The latter module also has methods to
-ease the handling of C<ARGV> and environment variables, and can be used
-on individual strings. Also, if you know that all your locales will be
-UTF-8, as many are these days, you can use the L<B<-C>|perlrun/-C>
-command line switch.
-
-This form of the pragma allows essentially seamless handling of locales
-with Unicode. The collation order will be Unicode's. It is strongly
-recommended that when you need to order and sort strings that you use
-the standard module L<Unicode::Collate> which gives much better results
-in many instances than you can get with the old-style locale handling.
-
-For pre-v5.16 Perls, or if you use the locale pragma without the
-C<:not_characters> parameter, Perl tries to work with both Unicode and
-locales--but there are problems.
-
-Perl does not handle multi-byte locales in this case, such as have been
-used for various
-Asian languages, such as Big5 or Shift JIS. However, the increasingly
-common multi-byte UTF-8 locales, if properly implemented, may work
-reasonably well (depending on your C library implementation) in this
-form of the locale pragma, simply because both
-they and Perl store characters that take up multiple bytes the same way.
-However, some, if not most, C library implementations may not process
-the characters in the upper half of the Latin-1 range (128 - 255)
-properly under LC_CTYPE. To see if a character is a particular type
-under a locale, Perl uses the functions like C<isalnum()>. Your C
-library may not work for UTF-8 locales with those functions, instead
-only working under the newer wide library functions like C<iswalnum()>.
-
-Perl generally takes the tack to use locale rules on code points that can fit
-in a single byte, and Unicode rules for those that can't (though this
-isn't uniformly applied, see the note at the end of this section). This
-prevents many problems in locales that aren't UTF-8. Suppose the locale
-is ISO8859-7, Greek. The character at 0xD7 there is a capital Chi. But
-in the ISO8859-1 locale, Latin1, it is a multiplication sign. The POSIX
-regular expression character class C<[[:alpha:]]> will magically match
-0xD7 in the Greek locale but not in the Latin one.
-
-However, there are places where this breaks down. Certain constructs are
-for Unicode only, such as C<\p{Alpha}>. They assume that 0xD7 always has its
-Unicode meaning (or the equivalent on EBCDIC platforms). Since Latin1 is a
-subset of Unicode and 0xD7 is the multiplication sign in both Latin1 and
-Unicode, C<\p{Alpha}> will never match it, regardless of locale. A similar
-issue occurs with C<\N{...}>. It is therefore a bad idea to use C<\p{}> or
-C<\N{}> under plain C<use locale>--I<unless> you can guarantee that the
-locale will be a ISO8859-1. Use POSIX character classes instead.
-
-Another problem with this approach is that operations that cross the
-single byte/multiple byte boundary are not well-defined, and so are
-disallowed. (This boundary is between the codepoints at 255/256.).
-For example, lower casing LATIN CAPITAL LETTER Y WITH DIAERESIS (U+0178)
-should return LATIN SMALL LETTER Y WITH DIAERESIS (U+00FF). But in the
-Greek locale, for example, there is no character at 0xFF, and Perl
-has no way of knowing what the character at 0xFF is really supposed to
-represent. Thus it disallows the operation. In this mode, the
-lowercase of U+0178 is itself.
-
-The same problems ensue if you enable automatic UTF-8-ification of your
-standard file handles, default C<open()> layer, and C<@ARGV> on non-ISO8859-1,
-non-UTF-8 locales (by using either the B<-C> command line switch or the
-C<PERL_UNICODE> environment variable; see L<perlrun>).
-Things are read in as UTF-8, which would normally imply a Unicode
-interpretation, but the presence of a locale causes them to be interpreted
-in that locale instead. For example, a 0xD7 code point in the Unicode
-input, which should mean the multiplication sign, won't be interpreted by
-Perl that way under the Greek locale. This is not a problem
-I<provided> you make certain that all locales will always and only be either
-an ISO8859-1, or, if you don't have a deficient C library, a UTF-8 locale.
-
-Vendor locales are notoriously buggy, and it is difficult for Perl to test
-its locale-handling code because this interacts with code that Perl has no
-control over; therefore the locale-handling code in Perl may be buggy as
-well. (However, the Unicode-supplied locales should be better, and
-there is a feed back mechanism to correct any problems. See
-L</Freely available locale definitions>.)
-
-If you have Perl v5.16, the problems mentioned above go away if you use
-the C<:not_characters> parameter to the locale pragma (except for vendor
-bugs in the non-character portions). If you don't have v5.16, and you
-I<do> have locales that work, using them may be worthwhile for certain
-specific purposes, as long as you keep in mind the gotchas already
-mentioned. For example, if the collation for your locales works, it
-runs faster under locales than under L<Unicode::Collate>; and you gain
-access to such things as the local currency symbol and the names of the
-months and days of the week. (But to hammer home the point, in v5.16,
-you get this access without the downsides of locales by using the
-C<:not_characters> form of the pragma.)
-
-Note: The policy of using locale rules for code points that can fit in a
-byte, and Unicode rules for those that can't is not uniformly applied.
-Pre-v5.12, it was somewhat haphazard; in v5.12 it was applied fairly
-consistently to regular expression matching except for bracketed
-character classes; in v5.14 it was extended to all regex matches; and in
-v5.16 to the casing operations such as C<"\L"> and C<uc()>. For
-collation, in all releases, the system's C<strxfrm()> function is called,
-and whatever it does is what you get.
-
-=head1 BUGS
-
-=head2 Broken systems
-
-In certain systems, the operating system's locale support
-is broken and cannot be fixed or used by Perl. Such deficiencies can
-and will result in mysterious hangs and/or Perl core dumps when
-C<use locale> is in effect. When confronted with such a system,
-please report in excruciating detail to <F<perlbug@perl.org>>, and
-also contact your vendor: bug fixes may exist for these problems
-in your operating system. Sometimes such bug fixes are called an
-operating system upgrade.
-
-=head1 SEE ALSO
-
-L<I18N::Langinfo>, L<perluniintro>, L<perlunicode>, L<open>,
-L<POSIX/isalnum>, L<POSIX/isalpha>,
-L<POSIX/isdigit>, L<POSIX/isgraph>, L<POSIX/islower>,
-L<POSIX/isprint>, L<POSIX/ispunct>, L<POSIX/isspace>,
-L<POSIX/isupper>, L<POSIX/isxdigit>, L<POSIX/localeconv>,
-L<POSIX/setlocale>, L<POSIX/strcoll>, L<POSIX/strftime>,
-L<POSIX/strtod>, L<POSIX/strxfrm>.
-
-=head1 HISTORY
-
-Jarkko Hietaniemi's original F<perli18n.pod> heavily hacked by Dominic
-Dunlop, assisted by the perl5-porters. Prose worked over a bit by
-Tom Christiansen, and updated by Perl 5 porters.
diff --git a/Master/tlpkg/tlperl/lib/pods/perllol.pod b/Master/tlpkg/tlperl/lib/pods/perllol.pod
deleted file mode 100644
index b35a0febb31..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perllol.pod
+++ /dev/null
@@ -1,388 +0,0 @@
-=head1 NAME
-
-perllol - Manipulating Arrays of Arrays in Perl
-
-=head1 DESCRIPTION
-
-=head2 Declaration and Access of Arrays of Arrays
-
-The simplest two-level data structure to build in Perl is an array of
-arrays, sometimes casually called a list of lists. It's reasonably easy to
-understand, and almost everything that applies here will also be applicable
-later on with the fancier data structures.
-
-An array of an array is just a regular old array @AoA that you can
-get at with two subscripts, like C<$AoA[3][2]>. Here's a declaration
-of the array:
-
- use 5.010; # so we can use say()
-
- # assign to our array, an array of array references
- @AoA = (
- [ "fred", "barney", "pebbles", "bambam", "dino", ],
- [ "george", "jane", "elroy", "judy", ],
- [ "homer", "bart", "marge", "maggie", ],
- );
- say $AoA[2][1];
- bart
-
-Now you should be very careful that the outer bracket type
-is a round one, that is, a parenthesis. That's because you're assigning to
-an @array, so you need parentheses. If you wanted there I<not> to be an @AoA,
-but rather just a reference to it, you could do something more like this:
-
- # assign a reference to array of array references
- $ref_to_AoA = [
- [ "fred", "barney", "pebbles", "bambam", "dino", ],
- [ "george", "jane", "elroy", "judy", ],
- [ "homer", "bart", "marge", "maggie", ],
- ];
- say $ref_to_AoA->[2][1];
- bart
-
-Notice that the outer bracket type has changed, and so our access syntax
-has also changed. That's because unlike C, in perl you can't freely
-interchange arrays and references thereto. $ref_to_AoA is a reference to an
-array, whereas @AoA is an array proper. Likewise, C<$AoA[2]> is not an
-array, but an array ref. So how come you can write these:
-
- $AoA[2][2]
- $ref_to_AoA->[2][2]
-
-instead of having to write these:
-
- $AoA[2]->[2]
- $ref_to_AoA->[2]->[2]
-
-Well, that's because the rule is that on adjacent brackets only (whether
-square or curly), you are free to omit the pointer dereferencing arrow.
-But you cannot do so for the very first one if it's a scalar containing
-a reference, which means that $ref_to_AoA always needs it.
-
-=head2 Growing Your Own
-
-That's all well and good for declaration of a fixed data structure,
-but what if you wanted to add new elements on the fly, or build
-it up entirely from scratch?
-
-First, let's look at reading it in from a file. This is something like
-adding a row at a time. We'll assume that there's a flat file in which
-each line is a row and each word an element. If you're trying to develop an
-@AoA array containing all these, here's the right way to do that:
-
- while (<>) {
- @tmp = split;
- push @AoA, [ @tmp ];
- }
-
-You might also have loaded that from a function:
-
- for $i ( 1 .. 10 ) {
- $AoA[$i] = [ somefunc($i) ];
- }
-
-Or you might have had a temporary variable sitting around with the
-array in it.
-
- for $i ( 1 .. 10 ) {
- @tmp = somefunc($i);
- $AoA[$i] = [ @tmp ];
- }
-
-It's important you make sure to use the C<[ ]> array reference
-constructor. That's because this wouldn't work:
-
- $AoA[$i] = @tmp; # WRONG!
-
-The reason that doesn't do what you want is because assigning a
-named array like that to a scalar is taking an array in scalar
-context, which means just counts the number of elements in @tmp.
-
-If you are running under C<use strict> (and if you aren't, why in
-the world aren't you?), you'll have to add some declarations to
-make it happy:
-
- use strict;
- my(@AoA, @tmp);
- while (<>) {
- @tmp = split;
- push @AoA, [ @tmp ];
- }
-
-Of course, you don't need the temporary array to have a name at all:
-
- while (<>) {
- push @AoA, [ split ];
- }
-
-You also don't have to use push(). You could just make a direct assignment
-if you knew where you wanted to put it:
-
- my (@AoA, $i, $line);
- for $i ( 0 .. 10 ) {
- $line = <>;
- $AoA[$i] = [ split " ", $line ];
- }
-
-or even just
-
- my (@AoA, $i);
- for $i ( 0 .. 10 ) {
- $AoA[$i] = [ split " ", <> ];
- }
-
-You should in general be leery of using functions that could
-potentially return lists in scalar context without explicitly stating
-such. This would be clearer to the casual reader:
-
- my (@AoA, $i);
- for $i ( 0 .. 10 ) {
- $AoA[$i] = [ split " ", scalar(<>) ];
- }
-
-If you wanted to have a $ref_to_AoA variable as a reference to an array,
-you'd have to do something like this:
-
- while (<>) {
- push @$ref_to_AoA, [ split ];
- }
-
-Now you can add new rows. What about adding new columns? If you're
-dealing with just matrices, it's often easiest to use simple assignment:
-
- for $x (1 .. 10) {
- for $y (1 .. 10) {
- $AoA[$x][$y] = func($x, $y);
- }
- }
-
- for $x ( 3, 7, 9 ) {
- $AoA[$x][20] += func2($x);
- }
-
-It doesn't matter whether those elements are already
-there or not: it'll gladly create them for you, setting
-intervening elements to C<undef> as need be.
-
-If you wanted just to append to a row, you'd have
-to do something a bit funnier looking:
-
- # add new columns to an existing row
- push @{ $AoA[0] }, "wilma", "betty"; # explicit deref
-
-Prior to Perl 5.14, this wouldn't even compile:
-
- push $AoA[0], "wilma", "betty"; # implicit deref
-
-How come? Because once upon a time, the argument to push() had to be a
-real array, not just a reference to one. That's no longer true. In fact,
-the line marked "implicit deref" above works just fine--in this
-instance--to do what the one that says explicit deref did.
-
-The reason I said "in this instance" is because that I<only> works
-because C<$AoA[0]> already held an array reference. If you try that on an
-undefined variable, you'll take an exception. That's because the implicit
-derefererence will never autovivify an undefined variable the way C<@{ }>
-always will:
-
- my $aref = undef;
- push $aref, qw(some more values); # WRONG!
- push @$aref, qw(a few more); # ok
-
-If you want to take advantage of this new implicit dereferencing behavior,
-go right ahead: it makes code easier on the eye and wrist. Just understand
-that older releases will choke on it during compilation. Whenever you make
-use of something that works only in some given release of Perl and later,
-but not earlier, you should place a prominent
-
- use v5.14; # needed for implicit deref of array refs by array ops
-
-directive at the top of the file that needs it. That way when somebody
-tries to run the new code under an old perl, rather than getting an error like
-
- Type of arg 1 to push must be array (not array element) at /tmp/a line 8, near ""betty";"
- Execution of /tmp/a aborted due to compilation errors.
-
-they'll be politely informed that
-
- Perl v5.14.0 required--this is only v5.12.3, stopped at /tmp/a line 1.
- BEGIN failed--compilation aborted at /tmp/a line 1.
-
-=head2 Access and Printing
-
-Now it's time to print your data structure out. How
-are you going to do that? Well, if you want only one
-of the elements, it's trivial:
-
- print $AoA[0][0];
-
-If you want to print the whole thing, though, you can't
-say
-
- print @AoA; # WRONG
-
-because you'll get just references listed, and perl will never
-automatically dereference things for you. Instead, you have to
-roll yourself a loop or two. This prints the whole structure,
-using the shell-style for() construct to loop across the outer
-set of subscripts.
-
- for $aref ( @AoA ) {
- say "\t [ @$aref ],";
- }
-
-If you wanted to keep track of subscripts, you might do this:
-
- for $i ( 0 .. $#AoA ) {
- say "\t elt $i is [ @{$AoA[$i]} ],";
- }
-
-or maybe even this. Notice the inner loop.
-
- for $i ( 0 .. $#AoA ) {
- for $j ( 0 .. $#{$AoA[$i]} ) {
- say "elt $i $j is $AoA[$i][$j]";
- }
- }
-
-As you can see, it's getting a bit complicated. That's why
-sometimes is easier to take a temporary on your way through:
-
- for $i ( 0 .. $#AoA ) {
- $aref = $AoA[$i];
- for $j ( 0 .. $#{$aref} ) {
- say "elt $i $j is $AoA[$i][$j]";
- }
- }
-
-Hmm... that's still a bit ugly. How about this:
-
- for $i ( 0 .. $#AoA ) {
- $aref = $AoA[$i];
- $n = @$aref - 1;
- for $j ( 0 .. $n ) {
- say "elt $i $j is $AoA[$i][$j]";
- }
- }
-
-When you get tired of writing a custom print for your data structures,
-you might look at the standard L<Dumpvalue> or L<Data::Dumper> modules.
-The former is what the Perl debugger uses, while the latter generates
-parsable Perl code. For example:
-
- use v5.14; # using the + prototype, new to v5.14
-
- sub show(+) {
- require Dumpvalue;
- state $prettily = new Dumpvalue::
- tick => q("),
- compactDump => 1, # comment these two lines out
- veryCompact => 1, # if you want a bigger dump
- ;
- dumpValue $prettily @_;
- }
-
- # Assign a list of array references to an array.
- my @AoA = (
- [ "fred", "barney" ],
- [ "george", "jane", "elroy" ],
- [ "homer", "marge", "bart" ],
- );
- push $AoA[0], "wilma", "betty";
- show @AoA;
-
-will print out:
-
- 0 0..3 "fred" "barney" "wilma" "betty"
- 1 0..2 "george" "jane" "elroy"
- 2 0..2 "homer" "marge" "bart"
-
-Whereas if you comment out the two lines I said you might wish to,
-then it shows it to you this way instead:
-
- 0 ARRAY(0x8031d0)
- 0 "fred"
- 1 "barney"
- 2 "wilma"
- 3 "betty"
- 1 ARRAY(0x803d40)
- 0 "george"
- 1 "jane"
- 2 "elroy"
- 2 ARRAY(0x803e10)
- 0 "homer"
- 1 "marge"
- 2 "bart"
-
-=head2 Slices
-
-If you want to get at a slice (part of a row) in a multidimensional
-array, you're going to have to do some fancy subscripting. That's
-because while we have a nice synonym for single elements via the
-pointer arrow for dereferencing, no such convenience exists for slices.
-
-Here's how to do one operation using a loop. We'll assume an @AoA
-variable as before.
-
- @part = ();
- $x = 4;
- for ($y = 7; $y < 13; $y++) {
- push @part, $AoA[$x][$y];
- }
-
-That same loop could be replaced with a slice operation:
-
- @part = @{$AoA[4]}[7..12];
-
-or spaced out a bit:
-
- @part = @{ $AoA[4] } [ 7..12 ];
-
-But as you might well imagine, this can get pretty rough on the reader.
-
-Ah, but what if you wanted a I<two-dimensional slice>, such as having
-$x run from 4..8 and $y run from 7 to 12? Hmm... here's the simple way:
-
- @newAoA = ();
- for ($startx = $x = 4; $x <= 8; $x++) {
- for ($starty = $y = 7; $y <= 12; $y++) {
- $newAoA[$x - $startx][$y - $starty] = $AoA[$x][$y];
- }
- }
-
-We can reduce some of the looping through slices
-
- for ($x = 4; $x <= 8; $x++) {
- push @newAoA, [ @{ $AoA[$x] } [ 7..12 ] ];
- }
-
-If you were into Schwartzian Transforms, you would probably
-have selected map for that
-
- @newAoA = map { [ @{ $AoA[$_] } [ 7..12 ] ] } 4 .. 8;
-
-Although if your manager accused you of seeking job security (or rapid
-insecurity) through inscrutable code, it would be hard to argue. :-)
-If I were you, I'd put that in a function:
-
- @newAoA = splice_2D( \@AoA, 4 => 8, 7 => 12 );
- sub splice_2D {
- my $lrr = shift; # ref to array of array refs!
- my ($x_lo, $x_hi,
- $y_lo, $y_hi) = @_;
-
- return map {
- [ @{ $lrr->[$_] } [ $y_lo .. $y_hi ] ]
- } $x_lo .. $x_hi;
- }
-
-
-=head1 SEE ALSO
-
-L<perldata>, L<perlref>, L<perldsc>
-
-=head1 AUTHOR
-
-Tom Christiansen <F<tchrist@perl.com>>
-
-Last update: Tue Apr 26 18:30:55 MDT 2011
diff --git a/Master/tlpkg/tlperl/lib/pods/perlmacos.pod b/Master/tlpkg/tlperl/lib/pods/perlmacos.pod
deleted file mode 100644
index 3482800691b..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlmacos.pod
+++ /dev/null
@@ -1,30 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you see.
-It is written in the POD format (see pod/perlpod.pod) which is specially
-designed to be readable as is.
-
-=head1 NAME
-
-perlmacos - Perl under Mac OS (Classic)
-
-=head1 SYNOPSIS
-
-For Mac OS X see README.macosx
-
-Perl under Mac OS Classic has not been supported since before Perl 5.10
-(April 2004).
-
-When we say "Mac OS" below, we mean Mac OS 7, 8, and 9, and I<not>
-Mac OS X.
-
-=head1 DESCRIPTION
-
-The port of Perl to to Mac OS was officially removed as of Perl 5.12,
-though the last official production release of MacPerl corresponded to
-Perl 5.6. While Perl 5.10 included the port to Mac OS, ExtUtils::MakeMaker,
-a core part of Perl's module installation infrastructure officially dropped support for Mac OS in April 2004.
-
-=head1 AUTHOR
-
-Perl was ported to Mac OS by Matthias Neeracher
-E<lt>neeracher@mac.comE<gt>. Chris Nandor E<lt>pudge@pobox.comE<gt>
-continued development and maintenance for the duration of the port's life.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlmacosx.pod b/Master/tlpkg/tlperl/lib/pods/perlmacosx.pod
deleted file mode 100644
index 0501b1ff649..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlmacosx.pod
+++ /dev/null
@@ -1,256 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you see.
-It is written in the POD format (see pod/perlpod.pod) which is specially
-designed to be readable as is.
-
-=head1 NAME
-
-perlmacosx - Perl under Mac OS X
-
-=head1 SYNOPSIS
-
-This document briefly describes Perl under Mac OS X.
-
- curl http://www.cpan.org/src/perl-5.12.3.tar.gz > perl-5.12.3.tar.gz
- tar -xzf perl-5.12.3.tar.gz
- cd perl-5.12.3
- ./Configure -des -Dprefix=/usr/local/
- make
- make test
- sudo make install
-
-=head1 DESCRIPTION
-
-The latest Perl release (5.12.3 as of this writing) builds without changes
-under all versions of Mac OS X from 10.3 "Panther" onwards.
-
-In order to build your own version of Perl you will need 'make'
-this is part of the Apples developer tools (you only need the 'unix tools'),
-usually supplied with Mac OS install DVDs. You do not need the latest
-version of Xcode (which is now charged for) in order to install make.
-
-Earlier Mac OS X releases (10.2 "Jaguar" and older) did not include a
-completely thread-safe libc, so threading is not fully supported. Also,
-earlier releases included a buggy libdb, so some of the DB_File tests
-are known to fail on those releases.
-
-
-=head2 Installation Prefix
-
-The default installation location for this release uses the traditional
-UNIX directory layout under /usr/local. This is the recommended location
-for most users, and will leave the Apple-supplied Perl and its modules
-undisturbed.
-
-Using an installation prefix of '/usr' will result in a directory layout
-that mirrors that of Apple's default Perl, with core modules stored in
-'/System/Library/Perl/${version}', CPAN modules stored in
-'/Library/Perl/${version}', and the addition of
-'/Network/Library/Perl/${version}' to @INC for modules that are stored
-on a file server and used by many Macs.
-
-
-=head2 SDK support
-
-First, export the path to the SDK into the build environment:
-
- export SDK=/Developer/SDKs/MacOSX10.3.9.sdk
-
-Use an SDK by exporting some additions to Perl's 'ccflags' and '..flags'
-config variables:
-
- ./Configure -Accflags="-nostdinc -B$SDK/usr/include/gcc \
- -B$SDK/usr/lib/gcc -isystem$SDK/usr/include \
- -F$SDK/System/Library/Frameworks" \
- -Aldflags="-Wl,-syslibroot,$SDK" \
- -de
-
-=head2 Universal Binary support
-
-To compile perl as a universal binary (built for both ppc and intel), export
-the SDK variable as above, selecting the 10.4u SDK:
-
- export SDK=/Developer/SDKs/MacOSX10.4u.sdk
-
-In addition to the compiler flags used to select the SDK, also add the flags
-for creating a universal binary:
-
- ./Configure -Accflags="-arch i686 -arch ppc -nostdinc -B$SDK/usr/include/gcc \
- -B$SDK/usr/lib/gcc -isystem$SDK/usr/include \
- -F$SDK/System/Library/Frameworks" \
- -Aldflags="-arch i686 -arch ppc -Wl,-syslibroot,$SDK" \
- -de
-
-In Leopard (MacOSX 10.5.6 at the time of this writing) you must use the 10.5 SDK:
-
- export SDK=/Developer/SDKs/MacOSX10.5.sdk
-
-You can use the same compiler flags you would use with the 10.4u SDK.
-
-Keep in mind that these compiler and linker settings will also be used when
-building CPAN modules. For XS modules to be compiled as a universal binary, any
-libraries it links to must also be universal binaries. The system libraries that
-Apple includes with the 10.4u SDK are all universal, but user-installed libraries
-may need to be re-installed as universal binaries.
-
-=head2 64-bit PPC support
-
-Follow the instructions in F<INSTALL> to build perl with support for 64-bit
-integers (C<use64bitint>) or both 64-bit integers and 64-bit addressing
-(C<use64bitall>). In the latter case, the resulting binary will run only
-on G5-based hosts.
-
-Support for 64-bit addressing is experimental: some aspects of Perl may be
-omitted or buggy. Note the messages output by F<Configure> for further
-information. Please use C<perlbug> to submit a problem report in the
-event that you encounter difficulties.
-
-When building 64-bit modules, it is your responsibility to ensure that linked
-external libraries and frameworks provide 64-bit support: if they do not,
-module building may appear to succeed, but attempts to use the module will
-result in run-time dynamic linking errors, and subsequent test failures.
-You can use C<file> to discover the architectures supported by a library:
-
- $ file libgdbm.3.0.0.dylib
- libgdbm.3.0.0.dylib: Mach-O fat file with 2 architectures
- libgdbm.3.0.0.dylib (for architecture ppc): Mach-O dynamically linked shared library ppc
- libgdbm.3.0.0.dylib (for architecture ppc64): Mach-O 64-bit dynamically linked shared library ppc64
-
-Note that this issue precludes the building of many Macintosh-specific CPAN
-modules (C<Mac::*>), as the required Apple frameworks do not provide PPC64
-support. Similarly, downloads from Fink or Darwinports are unlikely to provide
-64-bit support; the libraries must be rebuilt from source with the appropriate
-compiler and linker flags. For further information, see Apple's
-I<64-Bit Transition Guide> at
-L<http://developer.apple.com/documentation/Darwin/Conceptual/64bitPorting/index.html>.
-
-=head2 libperl and Prebinding
-
-Mac OS X ships with a dynamically-loaded libperl, but the default for
-this release is to compile a static libperl. The reason for this is
-pre-binding. Dynamic libraries can be pre-bound to a specific address in
-memory in order to decrease load time. To do this, one needs to be aware
-of the location and size of all previously-loaded libraries. Apple
-collects this information as part of their overall OS build process, and
-thus has easy access to it when building Perl, but ordinary users would
-need to go to a great deal of effort to obtain the information needed
-for pre-binding.
-
-You can override the default and build a shared libperl if you wish
-(S<Configure ... -Duseshrplib>), but the load time on pre-10.4 OS
-releases will be greater than either the static library, or Apple's
-pre-bound dynamic library.
-
-With 10.4 "Tiger" and newer, Apple has all but eliminated the performance
-penalty for non-prebound libraries.
-
-
-=head2 Updating Apple's Perl
-
-In a word - don't, at least without a *very* good reason. Your scripts
-can just as easily begin with "#!/usr/local/bin/perl" as with
-"#!/usr/bin/perl". Scripts supplied by Apple and other third parties as
-part of installation packages and such have generally only been tested
-with the /usr/bin/perl that's installed by Apple.
-
-If you find that you do need to update the system Perl, one issue worth
-keeping in mind is the question of static vs. dynamic libraries. If you
-upgrade using the default static libperl, you will find that the dynamic
-libperl supplied by Apple will not be deleted. If both libraries are
-present when an application that links against libperl is built, ld will
-link against the dynamic library by default. So, if you need to replace
-Apple's dynamic libperl with a static libperl, you need to be sure to
-delete the older dynamic library after you've installed the update.
-
-
-=head2 Known problems
-
-If you have installed extra libraries such as GDBM through Fink
-(in other words, you have libraries under F</sw/lib>), or libdlcompat
-to F</usr/local/lib>, you may need to be extra careful when running
-Configure to not to confuse Configure and Perl about which libraries
-to use. Being confused will show up for example as "dyld" errors about
-symbol problems, for example during "make test". The safest bet is to run
-Configure as
-
- Configure ... -Uloclibpth -Dlibpth=/usr/lib
-
-to make Configure look only into the system libraries. If you have some
-extra library directories that you really want to use (such as newer
-Berkeley DB libraries in pre-Panther systems), add those to the libpth:
-
- Configure ... -Uloclibpth -Dlibpth='/usr/lib /opt/lib'
-
-The default of building Perl statically may cause problems with complex
-applications like Tk: in that case consider building shared Perl
-
- Configure ... -Duseshrplib
-
-but remember that there's a startup cost to pay in that case (see above
-"libperl and Prebinding").
-
-Starting with Tiger (Mac OS X 10.4), Apple shipped broken locale files for
-the eu_ES locale (Basque-Spain). In previous releases of Perl, this resulted in
-failures in the F<lib/locale> test. These failures have been suppressed
-in the current release of Perl by making the test ignore the broken locale.
-If you need to use the eu_ES locale, you should contact Apple support.
-
-
-=head2 Cocoa
-
-There are two ways to use Cocoa from Perl. Apple's PerlObjCBridge
-module, included with Mac OS X, can be used by standalone scripts to
-access Foundation (i.e. non-GUI) classes and objects.
-
-An alternative is CamelBones, a framework that allows access to both
-Foundation and AppKit classes and objects, so that full GUI applications
-can be built in Perl. CamelBones can be found on SourceForge, at
-L<http://www.sourceforge.net/projects/camelbones/>.
-
-
-=head1 Starting From Scratch
-
-Unfortunately it is not that difficult somehow manage to break one's
-Mac OS X Perl rather severely. If all else fails and you want to
-really, B<REALLY>, start from scratch and remove even your Apple Perl
-installation (which has become corrupted somehow), the following
-instructions should do it. B<Please think twice before following
-these instructions: they are much like conducting brain surgery to
-yourself. Without anesthesia.> We will B<not> come to fix your system
-if you do this.
-
-First, get rid of the libperl.dylib:
-
- # cd /System/Library/Perl/darwin/CORE
- # rm libperl.dylib
-
-Then delete every .bundle file found anywhere in the folders:
-
- /System/Library/Perl
- /Library/Perl
-
-You can find them for example by
-
- # find /System/Library/Perl /Library/Perl -name '*.bundle' -print
-
-After this you can either copy Perl from your operating system media
-(you will need at least the /System/Library/Perl and /usr/bin/perl),
-or rebuild Perl from the source code with C<Configure -Dprefix=/usr
--Duseshrplib> NOTE: the C<-Dprefix=/usr> to replace the system Perl
-works much better with Perl 5.8.1 and later, in Perl 5.8.0 the
-settings were not quite right.
-
-"Pacifist" from CharlesSoft (L<http://www.charlessoft.com/>) is a nice
-way to extract the Perl binaries from the OS media, without having to
-reinstall the entire OS.
-
-
-=head1 AUTHOR
-
-This README was written by Sherm Pendley E<lt>sherm@dot-app.orgE<gt>,
-and subsequently updated by Dominic Dunlop E<lt>domo@computer.orgE<gt>.
-The "Starting From Scratch" recipe was contributed by John Montbriand
-E<lt>montbriand@apple.comE<gt>.
-
-=head1 DATE
-
-Last modified 2006-02-24.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlmod.pod b/Master/tlpkg/tlperl/lib/pods/perlmod.pod
deleted file mode 100644
index 33f098d0228..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlmod.pod
+++ /dev/null
@@ -1,598 +0,0 @@
-=head1 NAME
-
-perlmod - Perl modules (packages and symbol tables)
-
-=head1 DESCRIPTION
-
-=head2 Packages
-X<package> X<namespace> X<variable, global> X<global variable> X<global>
-
-Perl provides a mechanism for alternative namespaces to protect
-packages from stomping on each other's variables. In fact, there's
-really no such thing as a global variable in Perl. The package
-statement declares the compilation unit as being in the given
-namespace. The scope of the package declaration is from the
-declaration itself through the end of the enclosing block, C<eval>,
-or file, whichever comes first (the same scope as the my() and
-local() operators). Unqualified dynamic identifiers will be in
-this namespace, except for those few identifiers that if unqualified,
-default to the main package instead of the current one as described
-below. A package statement affects only dynamic variables--including
-those you've used local() on--but I<not> lexical variables created
-with my(). Typically it would be the first declaration in a file
-included by the C<do>, C<require>, or C<use> operators. You can
-switch into a package in more than one place; it merely influences
-which symbol table is used by the compiler for the rest of that
-block. You can refer to variables and filehandles in other packages
-by prefixing the identifier with the package name and a double
-colon: C<$Package::Variable>. If the package name is null, the
-C<main> package is assumed. That is, C<$::sail> is equivalent to
-C<$main::sail>.
-
-The old package delimiter was a single quote, but double colon is now the
-preferred delimiter, in part because it's more readable to humans, and
-in part because it's more readable to B<emacs> macros. It also makes C++
-programmers feel like they know what's going on--as opposed to using the
-single quote as separator, which was there to make Ada programmers feel
-like they knew what was going on. Because the old-fashioned syntax is still
-supported for backwards compatibility, if you try to use a string like
-C<"This is $owner's house">, you'll be accessing C<$owner::s>; that is,
-the $s variable in package C<owner>, which is probably not what you meant.
-Use braces to disambiguate, as in C<"This is ${owner}'s house">.
-X<::> X<'>
-
-Packages may themselves contain package separators, as in
-C<$OUTER::INNER::var>. This implies nothing about the order of
-name lookups, however. There are no relative packages: all symbols
-are either local to the current package, or must be fully qualified
-from the outer package name down. For instance, there is nowhere
-within package C<OUTER> that C<$INNER::var> refers to
-C<$OUTER::INNER::var>. C<INNER> refers to a totally
-separate global package.
-
-Only identifiers starting with letters (or underscore) are stored
-in a package's symbol table. All other symbols are kept in package
-C<main>, including all punctuation variables, like $_. In addition,
-when unqualified, the identifiers STDIN, STDOUT, STDERR, ARGV,
-ARGVOUT, ENV, INC, and SIG are forced to be in package C<main>,
-even when used for other purposes than their built-in ones. If you
-have a package called C<m>, C<s>, or C<y>, then you can't use the
-qualified form of an identifier because it would be instead interpreted
-as a pattern match, a substitution, or a transliteration.
-X<variable, punctuation>
-
-Variables beginning with underscore used to be forced into package
-main, but we decided it was more useful for package writers to be able
-to use leading underscore to indicate private variables and method names.
-However, variables and functions named with a single C<_>, such as
-$_ and C<sub _>, are still forced into the package C<main>. See also
-L<perlvar/"The Syntax of Variable Names">.
-
-C<eval>ed strings are compiled in the package in which the eval() was
-compiled. (Assignments to C<$SIG{}>, however, assume the signal
-handler specified is in the C<main> package. Qualify the signal handler
-name if you wish to have a signal handler in a package.) For an
-example, examine F<perldb.pl> in the Perl library. It initially switches
-to the C<DB> package so that the debugger doesn't interfere with variables
-in the program you are trying to debug. At various points, however, it
-temporarily switches back to the C<main> package to evaluate various
-expressions in the context of the C<main> package (or wherever you came
-from). See L<perldebug>.
-
-The special symbol C<__PACKAGE__> contains the current package, but cannot
-(easily) be used to construct variable names.
-
-See L<perlsub> for other scoping issues related to my() and local(),
-and L<perlref> regarding closures.
-
-=head2 Symbol Tables
-X<symbol table> X<stash> X<%::> X<%main::> X<typeglob> X<glob> X<alias>
-
-The symbol table for a package happens to be stored in the hash of that
-name with two colons appended. The main symbol table's name is thus
-C<%main::>, or C<%::> for short. Likewise the symbol table for the nested
-package mentioned earlier is named C<%OUTER::INNER::>.
-
-The value in each entry of the hash is what you are referring to when you
-use the C<*name> typeglob notation.
-
- local *main::foo = *main::bar;
-
-You can use this to print out all the variables in a package, for
-instance. The standard but antiquated F<dumpvar.pl> library and
-the CPAN module Devel::Symdump make use of this.
-
-The results of creating new symbol table entries directly or modifying any
-entries that are not already typeglobs are undefined and subject to change
-between releases of perl.
-
-Assignment to a typeglob performs an aliasing operation, i.e.,
-
- *dick = *richard;
-
-causes variables, subroutines, formats, and file and directory handles
-accessible via the identifier C<richard> also to be accessible via the
-identifier C<dick>. If you want to alias only a particular variable or
-subroutine, assign a reference instead:
-
- *dick = \$richard;
-
-Which makes $richard and $dick the same variable, but leaves
-@richard and @dick as separate arrays. Tricky, eh?
-
-There is one subtle difference between the following statements:
-
- *foo = *bar;
- *foo = \$bar;
-
-C<*foo = *bar> makes the typeglobs themselves synonymous while
-C<*foo = \$bar> makes the SCALAR portions of two distinct typeglobs
-refer to the same scalar value. This means that the following code:
-
- $bar = 1;
- *foo = \$bar; # Make $foo an alias for $bar
-
- {
- local $bar = 2; # Restrict changes to block
- print $foo; # Prints '1'!
- }
-
-Would print '1', because C<$foo> holds a reference to the I<original>
-C<$bar>. The one that was stuffed away by C<local()> and which will be
-restored when the block ends. Because variables are accessed through the
-typeglob, you can use C<*foo = *bar> to create an alias which can be
-localized. (But be aware that this means you can't have a separate
-C<@foo> and C<@bar>, etc.)
-
-What makes all of this important is that the Exporter module uses glob
-aliasing as the import/export mechanism. Whether or not you can properly
-localize a variable that has been exported from a module depends on how
-it was exported:
-
- @EXPORT = qw($FOO); # Usual form, can't be localized
- @EXPORT = qw(*FOO); # Can be localized
-
-You can work around the first case by using the fully qualified name
-(C<$Package::FOO>) where you need a local value, or by overriding it
-by saying C<*FOO = *Package::FOO> in your script.
-
-The C<*x = \$y> mechanism may be used to pass and return cheap references
-into or from subroutines if you don't want to copy the whole
-thing. It only works when assigning to dynamic variables, not
-lexicals.
-
- %some_hash = (); # can't be my()
- *some_hash = fn( \%another_hash );
- sub fn {
- local *hashsym = shift;
- # now use %hashsym normally, and you
- # will affect the caller's %another_hash
- my %nhash = (); # do what you want
- return \%nhash;
- }
-
-On return, the reference will overwrite the hash slot in the
-symbol table specified by the *some_hash typeglob. This
-is a somewhat tricky way of passing around references cheaply
-when you don't want to have to remember to dereference variables
-explicitly.
-
-Another use of symbol tables is for making "constant" scalars.
-X<constant> X<scalar, constant>
-
- *PI = \3.14159265358979;
-
-Now you cannot alter C<$PI>, which is probably a good thing all in all.
-This isn't the same as a constant subroutine, which is subject to
-optimization at compile-time. A constant subroutine is one prototyped
-to take no arguments and to return a constant expression. See
-L<perlsub> for details on these. The C<use constant> pragma is a
-convenient shorthand for these.
-
-You can say C<*foo{PACKAGE}> and C<*foo{NAME}> to find out what name and
-package the *foo symbol table entry comes from. This may be useful
-in a subroutine that gets passed typeglobs as arguments:
-
- sub identify_typeglob {
- my $glob = shift;
- print 'You gave me ', *{$glob}{PACKAGE}, '::', *{$glob}{NAME}, "\n";
- }
- identify_typeglob *foo;
- identify_typeglob *bar::baz;
-
-This prints
-
- You gave me main::foo
- You gave me bar::baz
-
-The C<*foo{THING}> notation can also be used to obtain references to the
-individual elements of *foo. See L<perlref>.
-
-Subroutine definitions (and declarations, for that matter) need
-not necessarily be situated in the package whose symbol table they
-occupy. You can define a subroutine outside its package by
-explicitly qualifying the name of the subroutine:
-
- package main;
- sub Some_package::foo { ... } # &foo defined in Some_package
-
-This is just a shorthand for a typeglob assignment at compile time:
-
- BEGIN { *Some_package::foo = sub { ... } }
-
-and is I<not> the same as writing:
-
- {
- package Some_package;
- sub foo { ... }
- }
-
-In the first two versions, the body of the subroutine is
-lexically in the main package, I<not> in Some_package. So
-something like this:
-
- package main;
-
- $Some_package::name = "fred";
- $main::name = "barney";
-
- sub Some_package::foo {
- print "in ", __PACKAGE__, ": \$name is '$name'\n";
- }
-
- Some_package::foo();
-
-prints:
-
- in main: $name is 'barney'
-
-rather than:
-
- in Some_package: $name is 'fred'
-
-This also has implications for the use of the SUPER:: qualifier
-(see L<perlobj>).
-
-=head2 BEGIN, UNITCHECK, CHECK, INIT and END
-X<BEGIN> X<UNITCHECK> X<CHECK> X<INIT> X<END>
-
-Five specially named code blocks are executed at the beginning and at
-the end of a running Perl program. These are the C<BEGIN>,
-C<UNITCHECK>, C<CHECK>, C<INIT>, and C<END> blocks.
-
-These code blocks can be prefixed with C<sub> to give the appearance of a
-subroutine (although this is not considered good style). One should note
-that these code blocks don't really exist as named subroutines (despite
-their appearance). The thing that gives this away is the fact that you can
-have B<more than one> of these code blocks in a program, and they will get
-B<all> executed at the appropriate moment. So you can't execute any of
-these code blocks by name.
-
-A C<BEGIN> code block is executed as soon as possible, that is, the moment
-it is completely defined, even before the rest of the containing file (or
-string) is parsed. You may have multiple C<BEGIN> blocks within a file (or
-eval'ed string); they will execute in order of definition. Because a C<BEGIN>
-code block executes immediately, it can pull in definitions of subroutines
-and such from other files in time to be visible to the rest of the compile
-and run time. Once a C<BEGIN> has run, it is immediately undefined and any
-code it used is returned to Perl's memory pool.
-
-An C<END> code block is executed as late as possible, that is, after
-perl has finished running the program and just before the interpreter
-is being exited, even if it is exiting as a result of a die() function.
-(But not if it's morphing into another program via C<exec>, or
-being blown out of the water by a signal--you have to trap that yourself
-(if you can).) You may have multiple C<END> blocks within a file--they
-will execute in reverse order of definition; that is: last in, first
-out (LIFO). C<END> blocks are not executed when you run perl with the
-C<-c> switch, or if compilation fails.
-
-Note that C<END> code blocks are B<not> executed at the end of a string
-C<eval()>: if any C<END> code blocks are created in a string C<eval()>,
-they will be executed just as any other C<END> code block of that package
-in LIFO order just before the interpreter is being exited.
-
-Inside an C<END> code block, C<$?> contains the value that the program is
-going to pass to C<exit()>. You can modify C<$?> to change the exit
-value of the program. Beware of changing C<$?> by accident (e.g. by
-running something via C<system>).
-X<$?>
-
-Inside of a C<END> block, the value of C<${^GLOBAL_PHASE}> will be
-C<"END">.
-
-C<UNITCHECK>, C<CHECK> and C<INIT> code blocks are useful to catch the
-transition between the compilation phase and the execution phase of
-the main program.
-
-C<UNITCHECK> blocks are run just after the unit which defined them has
-been compiled. The main program file and each module it loads are
-compilation units, as are string C<eval>s, code compiled using the
-C<(?{ })> construct in a regex, calls to C<do FILE>, C<require FILE>,
-and code after the C<-e> switch on the command line.
-
-C<BEGIN> and C<UNITCHECK> blocks are not directly related to the phase of
-the interpreter. They can be created and executed during any phase.
-
-C<CHECK> code blocks are run just after the B<initial> Perl compile phase ends
-and before the run time begins, in LIFO order. C<CHECK> code blocks are used
-in the Perl compiler suite to save the compiled state of the program.
-
-Inside of a C<CHECK> block, the value of C<${^GLOBAL_PHASE}> will be
-C<"CHECK">.
-
-C<INIT> blocks are run just before the Perl runtime begins execution, in
-"first in, first out" (FIFO) order.
-
-Inside of an C<INIT> block, the value of C<${^GLOBAL_PHASE}> will be C<"INIT">.
-
-The C<CHECK> and C<INIT> blocks in code compiled by C<require>, string C<do>,
-or string C<eval> will not be executed if they occur after the end of the
-main compilation phase; that can be a problem in mod_perl and other persistent
-environments which use those functions to load code at runtime.
-
-When you use the B<-n> and B<-p> switches to Perl, C<BEGIN> and
-C<END> work just as they do in B<awk>, as a degenerate case.
-Both C<BEGIN> and C<CHECK> blocks are run when you use the B<-c>
-switch for a compile-only syntax check, although your main code
-is not.
-
-The B<begincheck> program makes it all clear, eventually:
-
- #!/usr/bin/perl
-
- # begincheck
-
- print "10. Ordinary code runs at runtime.\n";
-
- END { print "16. So this is the end of the tale.\n" }
- INIT { print " 7. INIT blocks run FIFO just before runtime.\n" }
- UNITCHECK {
- print " 4. And therefore before any CHECK blocks.\n"
- }
- CHECK { print " 6. So this is the sixth line.\n" }
-
- print "11. It runs in order, of course.\n";
-
- BEGIN { print " 1. BEGIN blocks run FIFO during compilation.\n" }
- END { print "15. Read perlmod for the rest of the story.\n" }
- CHECK { print " 5. CHECK blocks run LIFO after all compilation.\n" }
- INIT { print " 8. Run this again, using Perl's -c switch.\n" }
-
- print "12. This is anti-obfuscated code.\n";
-
- END { print "14. END blocks run LIFO at quitting time.\n" }
- BEGIN { print " 2. So this line comes out second.\n" }
- UNITCHECK {
- print " 3. UNITCHECK blocks run LIFO after each file is compiled.\n"
- }
- INIT { print " 9. You'll see the difference right away.\n" }
-
- print "13. It merely _looks_ like it should be confusing.\n";
-
- __END__
-
-=head2 Perl Classes
-X<class> X<@ISA>
-
-There is no special class syntax in Perl, but a package may act
-as a class if it provides subroutines to act as methods. Such a
-package may also derive some of its methods from another class (package)
-by listing the other package name(s) in its global @ISA array (which
-must be a package global, not a lexical).
-
-For more on this, see L<perlootut> and L<perlobj>.
-
-=head2 Perl Modules
-X<module>
-
-A module is just a set of related functions in a library file, i.e.,
-a Perl package with the same name as the file. It is specifically
-designed to be reusable by other modules or programs. It may do this
-by providing a mechanism for exporting some of its symbols into the
-symbol table of any package using it, or it may function as a class
-definition and make its semantics available implicitly through
-method calls on the class and its objects, without explicitly
-exporting anything. Or it can do a little of both.
-
-For example, to start a traditional, non-OO module called Some::Module,
-create a file called F<Some/Module.pm> and start with this template:
-
- package Some::Module; # assumes Some/Module.pm
-
- use strict;
- use warnings;
-
- BEGIN {
- require Exporter;
-
- # set the version for version checking
- our $VERSION = 1.00;
-
- # Inherit from Exporter to export functions and variables
- our @ISA = qw(Exporter);
-
- # Functions and variables which are exported by default
- our @EXPORT = qw(func1 func2);
-
- # Functions and variables which can be optionally exported
- our @EXPORT_OK = qw($Var1 %Hashit func3);
- }
-
- # exported package globals go here
- our $Var1 = '';
- our %Hashit = ();
-
- # non-exported package globals go here
- # (they are still accessible as $Some::Module::stuff)
- our @more = ();
- our $stuff = '';
-
- # file-private lexicals go here, before any functions which use them
- my $priv_var = '';
- my %secret_hash = ();
-
- # here's a file-private function as a closure,
- # callable as $priv_func->();
- my $priv_func = sub {
- ...
- };
-
- # make all your functions, whether exported or not;
- # remember to put something interesting in the {} stubs
- sub func1 { ... }
- sub func2 { ... }
-
- # this one isn't exported, but could be called directly
- # as Some::Module::func3()
- sub func3 { ... }
-
- END { ... } # module clean-up code here (global destructor)
-
- 1; # don't forget to return a true value from the file
-
-Then go on to declare and use your variables in functions without
-any qualifications. See L<Exporter> and the L<perlmodlib> for
-details on mechanics and style issues in module creation.
-
-Perl modules are included into your program by saying
-
- use Module;
-
-or
-
- use Module LIST;
-
-This is exactly equivalent to
-
- BEGIN { require 'Module.pm'; 'Module'->import; }
-
-or
-
- BEGIN { require 'Module.pm'; 'Module'->import( LIST ); }
-
-As a special case
-
- use Module ();
-
-is exactly equivalent to
-
- BEGIN { require 'Module.pm'; }
-
-All Perl module files have the extension F<.pm>. The C<use> operator
-assumes this so you don't have to spell out "F<Module.pm>" in quotes.
-This also helps to differentiate new modules from old F<.pl> and
-F<.ph> files. Module names are also capitalized unless they're
-functioning as pragmas; pragmas are in effect compiler directives,
-and are sometimes called "pragmatic modules" (or even "pragmata"
-if you're a classicist).
-
-The two statements:
-
- require SomeModule;
- require "SomeModule.pm";
-
-differ from each other in two ways. In the first case, any double
-colons in the module name, such as C<Some::Module>, are translated
-into your system's directory separator, usually "/". The second
-case does not, and would have to be specified literally. The other
-difference is that seeing the first C<require> clues in the compiler
-that uses of indirect object notation involving "SomeModule", as
-in C<$ob = purge SomeModule>, are method calls, not function calls.
-(Yes, this really can make a difference.)
-
-Because the C<use> statement implies a C<BEGIN> block, the importing
-of semantics happens as soon as the C<use> statement is compiled,
-before the rest of the file is compiled. This is how it is able
-to function as a pragma mechanism, and also how modules are able to
-declare subroutines that are then visible as list or unary operators for
-the rest of the current file. This will not work if you use C<require>
-instead of C<use>. With C<require> you can get into this problem:
-
- require Cwd; # make Cwd:: accessible
- $here = Cwd::getcwd();
-
- use Cwd; # import names from Cwd::
- $here = getcwd();
-
- require Cwd; # make Cwd:: accessible
- $here = getcwd(); # oops! no main::getcwd()
-
-In general, C<use Module ()> is recommended over C<require Module>,
-because it determines module availability at compile time, not in the
-middle of your program's execution. An exception would be if two modules
-each tried to C<use> each other, and each also called a function from
-that other module. In that case, it's easy to use C<require> instead.
-
-Perl packages may be nested inside other package names, so we can have
-package names containing C<::>. But if we used that package name
-directly as a filename it would make for unwieldy or impossible
-filenames on some systems. Therefore, if a module's name is, say,
-C<Text::Soundex>, then its definition is actually found in the library
-file F<Text/Soundex.pm>.
-
-Perl modules always have a F<.pm> file, but there may also be
-dynamically linked executables (often ending in F<.so>) or autoloaded
-subroutine definitions (often ending in F<.al>) associated with the
-module. If so, these will be entirely transparent to the user of
-the module. It is the responsibility of the F<.pm> file to load
-(or arrange to autoload) any additional functionality. For example,
-although the POSIX module happens to do both dynamic loading and
-autoloading, the user can say just C<use POSIX> to get it all.
-
-=head2 Making your module threadsafe
-X<threadsafe> X<thread safe>
-X<module, threadsafe> X<module, thread safe>
-X<CLONE> X<CLONE_SKIP> X<thread> X<threads> X<ithread>
-
-Since 5.6.0, Perl has had support for a new type of threads called
-interpreter threads (ithreads). These threads can be used explicitly
-and implicitly.
-
-Ithreads work by cloning the data tree so that no data is shared
-between different threads. These threads can be used by using the C<threads>
-module or by doing fork() on win32 (fake fork() support). When a
-thread is cloned all Perl data is cloned, however non-Perl data cannot
-be cloned automatically. Perl after 5.7.2 has support for the C<CLONE>
-special subroutine. In C<CLONE> you can do whatever
-you need to do,
-like for example handle the cloning of non-Perl data, if necessary.
-C<CLONE> will be called once as a class method for every package that has it
-defined (or inherits it). It will be called in the context of the new thread,
-so all modifications are made in the new area. Currently CLONE is called with
-no parameters other than the invocant package name, but code should not assume
-that this will remain unchanged, as it is likely that in future extra parameters
-will be passed in to give more information about the state of cloning.
-
-If you want to CLONE all objects you will need to keep track of them per
-package. This is simply done using a hash and Scalar::Util::weaken().
-
-Perl after 5.8.7 has support for the C<CLONE_SKIP> special subroutine.
-Like C<CLONE>, C<CLONE_SKIP> is called once per package; however, it is
-called just before cloning starts, and in the context of the parent
-thread. If it returns a true value, then no objects of that class will
-be cloned; or rather, they will be copied as unblessed, undef values.
-For example: if in the parent there are two references to a single blessed
-hash, then in the child there will be two references to a single undefined
-scalar value instead.
-This provides a simple mechanism for making a module threadsafe; just add
-C<sub CLONE_SKIP { 1 }> at the top of the class, and C<DESTROY()> will
-now only be called once per object. Of course, if the child thread needs
-to make use of the objects, then a more sophisticated approach is
-needed.
-
-Like C<CLONE>, C<CLONE_SKIP> is currently called with no parameters other
-than the invocant package name, although that may change. Similarly, to
-allow for future expansion, the return value should be a single C<0> or
-C<1> value.
-
-=head1 SEE ALSO
-
-See L<perlmodlib> for general style issues related to building Perl
-modules and classes, as well as descriptions of the standard library
-and CPAN, L<Exporter> for how Perl's standard import/export mechanism
-works, L<perlootut> and L<perlobj> for in-depth information on
-creating classes, L<perlobj> for a hard-core reference document on
-objects, L<perlsub> for an explanation of functions and scoping,
-and L<perlxstut> and L<perlguts> for more information on writing
-extension modules.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlmodinstall.pod b/Master/tlpkg/tlperl/lib/pods/perlmodinstall.pod
deleted file mode 100644
index f4694cc9a76..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlmodinstall.pod
+++ /dev/null
@@ -1,439 +0,0 @@
-=head1 NAME
-
-perlmodinstall - Installing CPAN Modules
-
-=head1 DESCRIPTION
-
-You can think of a module as the fundamental unit of reusable Perl
-code; see L<perlmod> for details. Whenever anyone creates a chunk of
-Perl code that they think will be useful to the world, they register
-as a Perl developer at http://www.cpan.org/modules/04pause.html
-so that they can then upload their code to the CPAN. The CPAN is the
-Comprehensive Perl Archive Network and can be accessed at
-http://www.cpan.org/ , and searched at http://search.cpan.org/ .
-
-This documentation is for people who want to download CPAN modules
-and install them on their own computer.
-
-=head2 PREAMBLE
-
-First, are you sure that the module isn't already on your system? Try
-C<perl -MFoo -e 1>. (Replace "Foo" with the name of the module; for
-instance, C<perl -MCGI::Carp -e 1>.
-
-If you don't see an error message, you have the module. (If you do
-see an error message, it's still possible you have the module, but
-that it's not in your path, which you can display with C<perl -e
-"print qq(@INC)">.) For the remainder of this document, we'll assume
-that you really honestly truly lack an installed module, but have
-found it on the CPAN.
-
-So now you have a file ending in .tar.gz (or, less often, .zip). You
-know there's a tasty module inside. There are four steps you must now
-take:
-
-=over 5
-
-=item B<DECOMPRESS> the file
-
-=item B<UNPACK> the file into a directory
-
-=item B<BUILD> the module (sometimes unnecessary)
-
-=item B<INSTALL> the module.
-
-=back
-
-Here's how to perform each step for each operating system. This is
-<not> a substitute for reading the README and INSTALL files that
-might have come with your module!
-
-Also note that these instructions are tailored for installing the
-module into your system's repository of Perl modules, but you can
-install modules into any directory you wish. For instance, where I
-say C<perl Makefile.PL>, you can substitute C<perl Makefile.PL
-PREFIX=/my/perl_directory> to install the modules into
-C</my/perl_directory>. Then you can use the modules from your Perl
-programs with C<use lib "/my/perl_directory/lib/site_perl";> or
-sometimes just C<use "/my/perl_directory";>. If you're on a system
-that requires superuser/root access to install modules into the
-directories you see when you type C<perl -e "print qq(@INC)">, you'll
-want to install them into a local directory (such as your home
-directory) and use this approach.
-
-=over 4
-
-=item *
-
-B<If you're on a Unix or Unix-like system,>
-
-You can use Andreas Koenig's CPAN module
-( http://www.cpan.org/modules/by-module/CPAN )
-to automate the following steps, from DECOMPRESS through INSTALL.
-
-A. DECOMPRESS
-
-Decompress the file with C<gzip -d yourmodule.tar.gz>
-
-You can get gzip from ftp://prep.ai.mit.edu/pub/gnu/
-
-Or, you can combine this step with the next to save disk space:
-
- gzip -dc yourmodule.tar.gz | tar -xof -
-
-B. UNPACK
-
-Unpack the result with C<tar -xof yourmodule.tar>
-
-C. BUILD
-
-Go into the newly-created directory and type:
-
- perl Makefile.PL
- make test
-
-or
-
- perl Makefile.PL PREFIX=/my/perl_directory
-
-to install it locally. (Remember that if you do this, you'll have to
-put C<use lib "/my/perl_directory";> near the top of the program that
-is to use this module.
-
-D. INSTALL
-
-While still in that directory, type:
-
- make install
-
-Make sure you have the appropriate permissions to install the module
-in your Perl 5 library directory. Often, you'll need to be root.
-
-That's all you need to do on Unix systems with dynamic linking.
-Most Unix systems have dynamic linking. If yours doesn't, or if for
-another reason you have a statically-linked perl, B<and> the
-module requires compilation, you'll need to build a new Perl binary
-that includes the module. Again, you'll probably need to be root.
-
-=item *
-
-B<If you're running ActivePerl (Win95/98/2K/NT/XP, Linux, Solaris)>
-
-First, type C<ppm> from a shell and see whether ActiveState's PPM
-repository has your module. If so, you can install it with C<ppm> and
-you won't have to bother with any of the other steps here. You might
-be able to use the CPAN instructions from the "Unix or Linux" section
-above as well; give it a try. Otherwise, you'll have to follow the
-steps below.
-
- A. DECOMPRESS
-
-You can use the shareware Winzip ( http://www.winzip.com ) to
-decompress and unpack modules.
-
- B. UNPACK
-
-If you used WinZip, this was already done for you.
-
- C. BUILD
-
-You'll need the C<nmake> utility, available at
-http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe
-or dmake, available on CPAN.
-http://search.cpan.org/dist/dmake/
-
-Does the module require compilation (i.e. does it have files that end
-in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it does, life is now
-officially tough for you, because you have to compile the module
-yourself (no easy feat on Windows). You'll need a compiler such as
-Visual C++. Alternatively, you can download a pre-built PPM package
-from ActiveState.
-http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/
-
-Go into the newly-created directory and type:
-
- perl Makefile.PL
- nmake test
-
-
- D. INSTALL
-
-While still in that directory, type:
-
- nmake install
-
-=item *
-
-B<If you're using a Macintosh with "Classic" MacOS and MacPerl,>
-
-
-A. DECOMPRESS
-
-First, make sure you have the latest B<cpan-mac> distribution (
-http://www.cpan.org/authors/id/CNANDOR/ ), which has utilities for
-doing all of the steps. Read the cpan-mac directions carefully and
-install it. If you choose not to use cpan-mac for some reason, there
-are alternatives listed here.
-
-After installing cpan-mac, drop the module archive on the
-B<untarzipme> droplet, which will decompress and unpack for you.
-
-B<Or>, you can either use the shareware B<StuffIt Expander> program
-( http://my.smithmicro.com/mac/stuffit/ )
-or the freeware B<MacGzip> program (
-http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
-
-B. UNPACK
-
-If you're using untarzipme or StuffIt, the archive should be extracted
-now. B<Or>, you can use the freeware B<suntar> or I<Tar> (
-http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/ ).
-
-C. BUILD
-
-Check the contents of the distribution.
-Read the module's documentation, looking for
-reasons why you might have trouble using it with MacPerl. Look for
-F<.xs> and F<.c> files, which normally denote that the distribution
-must be compiled, and you cannot install it "out of the box."
-(See L<"PORTABILITY">.)
-
-D. INSTALL
-
-If you are using cpan-mac, just drop the folder on the
-B<installme> droplet, and use the module.
-
-B<Or>, if you aren't using cpan-mac, do some manual labor.
-
-Make sure the newlines for the modules are in Mac format, not Unix format.
-If they are not then you might have decompressed them incorrectly. Check
-your decompression and unpacking utilities settings to make sure they are
-translating text files properly.
-
-As a last resort, you can use the perl one-liner:
-
- perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames>
-
-on the source files.
-
-Then move the files (probably just the F<.pm> files, though there
-may be some additional ones, too; check the module documentation)
-to their final destination: This will
-most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
-C<HD:MacPerl folder:site_lib:>). You can add new paths to
-the default C<@INC> in the Preferences menu item in the
-MacPerl application (C<$ENV{MACPERL}site_lib:> is added
-automagically). Create whatever directory structures are required
-(i.e., for C<Some::Module>, create
-C<$ENV{MACPERL}site_lib:Some:> and put
-C<Module.pm> in that directory).
-
-Then run the following script (or something like it):
-
- #!perl -w
- use AutoSplit;
- my $dir = "${MACPERL}site_perl";
- autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
-
-=item *
-
-B<If you're on the DJGPP port of DOS,>
-
- A. DECOMPRESS
-
-djtarx ( ftp://ftp.delorie.com/pub/djgpp/current/v2/ )
-will both uncompress and unpack.
-
- B. UNPACK
-
-See above.
-
- C. BUILD
-
-Go into the newly-created directory and type:
-
- perl Makefile.PL
- make test
-
-You will need the packages mentioned in F<README.dos>
-in the Perl distribution.
-
- D. INSTALL
-
-While still in that directory, type:
-
- make install
-
-You will need the packages mentioned in F<README.dos> in the Perl distribution.
-
-=item *
-
-B<If you're on OS/2,>
-
-Get the EMX development suite and gzip/tar, from either Hobbes (
-http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
-the instructions for Unix.
-
-=item *
-
-B<If you're on VMS,>
-
-When downloading from CPAN, save your file with a C<.tgz>
-extension instead of C<.tar.gz>. All other periods in the
-filename should be replaced with underscores. For example,
-C<Your-Module-1.33.tar.gz> should be downloaded as
-C<Your-Module-1_33.tgz>.
-
-A. DECOMPRESS
-
-Type
-
- gzip -d Your-Module.tgz
-
-or, for zipped modules, type
-
- unzip Your-Module.zip
-
-Executables for gzip, zip, and VMStar:
-
- http://www.hp.com/go/openvms/freeware/
-
-and their source code:
-
- http://www.fsf.org/order/ftp.html
-
-Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
-package. The former is a simple compression tool; the latter permits
-creation of multi-file archives.
-
-B. UNPACK
-
-If you're using VMStar:
-
- VMStar xf Your-Module.tar
-
-Or, if you're fond of VMS command syntax:
-
- tar/extract/verbose Your_Module.tar
-
-C. BUILD
-
-Make sure you have MMS (from Digital) or the freeware MMK ( available
-from MadGoat at http://www.madgoat.com ). Then type this to create
-the DESCRIP.MMS for the module:
-
- perl Makefile.PL
-
-Now you're ready to build:
-
- mms test
-
-Substitute C<mmk> for C<mms> above if you're using MMK.
-
-D. INSTALL
-
-Type
-
- mms install
-
-Substitute C<mmk> for C<mms> above if you're using MMK.
-
-=item *
-
-B<If you're on MVS>,
-
-Introduce the F<.tar.gz> file into an HFS as binary; don't translate from
-ASCII to EBCDIC.
-
-A. DECOMPRESS
-
-Decompress the file with C<gzip -d yourmodule.tar.gz>
-
-You can get gzip from
-http://www.s390.ibm.com/products/oe/bpxqp1.html
-
-B. UNPACK
-
-Unpack the result with
-
- pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
-
-The BUILD and INSTALL steps are identical to those for Unix. Some
-modules generate Makefiles that work better with GNU make, which is
-available from http://www.mks.com/s390/gnu/
-
-=back
-
-=head1 PORTABILITY
-
-Note that not all modules will work with on all platforms.
-See L<perlport> for more information on portability issues.
-Read the documentation to see if the module will work on your
-system. There are basically three categories
-of modules that will not work "out of the box" with all
-platforms (with some possibility of overlap):
-
-=over 4
-
-=item *
-
-B<Those that should, but don't.> These need to be fixed; consider
-contacting the author and possibly writing a patch.
-
-=item *
-
-B<Those that need to be compiled, where the target platform
-doesn't have compilers readily available.> (These modules contain
-F<.xs> or F<.c> files, usually.) You might be able to find
-existing binaries on the CPAN or elsewhere, or you might
-want to try getting compilers and building it yourself, and then
-release the binary for other poor souls to use.
-
-=item *
-
-B<Those that are targeted at a specific platform.>
-(Such as the Win32:: modules.) If the module is targeted
-specifically at a platform other than yours, you're out
-of luck, most likely.
-
-=back
-
-
-
-Check the CPAN Testers if a module should work with your platform
-but it doesn't behave as you'd expect, or you aren't sure whether or
-not a module will work under your platform. If the module you want
-isn't listed there, you can test it yourself and let CPAN Testers know,
-you can join CPAN Testers, or you can request it be tested.
-
- http://testers.cpan.org/
-
-
-=head1 HEY
-
-If you have any suggested changes for this page, let me know. Please
-don't send me mail asking for help on how to install your modules.
-There are too many modules, and too few Orwants, for me to be able to
-answer or even acknowledge all your questions. Contact the module
-author instead, or post to comp.lang.perl.modules, or ask someone
-familiar with Perl on your operating system.
-
-=head1 AUTHOR
-
-Jon Orwant
-
-orwant@medita.mit.edu
-
-with invaluable help from Chris Nandor, and valuable help from Brandon
-Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
-Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas
-J. Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
-Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
-
-First version July 22, 1998; last revised November 21, 2001.
-
-=head1 COPYRIGHT
-
-Copyright (C) 1998, 2002, 2003 Jon Orwant. All Rights Reserved.
-
-This document may be distributed under the same terms as Perl itself.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlmodlib.pod b/Master/tlpkg/tlperl/lib/pods/perlmodlib.pod
deleted file mode 100644
index ce94dc46060..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlmodlib.pod
+++ /dev/null
@@ -1,3920 +0,0 @@
-=for maintainers
-Generated by perlmodlib.PL -- DO NOT EDIT!
-
-=head1 NAME
-
-perlmodlib - constructing new Perl modules and finding existing ones
-
-=head1 THE PERL MODULE LIBRARY
-
-Many modules are included in the Perl distribution. These are described
-below, and all end in F<.pm>. You may discover compiled library
-files (usually ending in F<.so>) or small pieces of modules to be
-autoloaded (ending in F<.al>); these were automatically generated
-by the installation process. You may also discover files in the
-library directory that end in either F<.pl> or F<.ph>. These are
-old libraries supplied so that old programs that use them still
-run. The F<.pl> files will all eventually be converted into standard
-modules, and the F<.ph> files made by B<h2ph> will probably end up
-as extension modules made by B<h2xs>. (Some F<.ph> values may
-already be available through the POSIX, Errno, or Fcntl modules.)
-The B<pl2pm> file in the distribution may help in your conversion,
-but it's just a mechanical process and therefore far from bulletproof.
-
-=head2 Pragmatic Modules
-
-They work somewhat like compiler directives (pragmata) in that they
-tend to affect the compilation of your program, and thus will usually
-work well only when used within a C<use>, or C<no>. Most of these
-are lexically scoped, so an inner BLOCK may countermand them
-by saying:
-
- no integer;
- no strict 'refs';
- no warnings;
-
-which lasts until the end of that BLOCK.
-
-Some pragmas are lexically scoped--typically those that affect the
-C<$^H> hints variable. Others affect the current package instead,
-like C<use vars> and C<use subs>, which allow you to predeclare a
-variables or subroutines within a particular I<file> rather than
-just a block. Such declarations are effective for the entire file
-for which they were declared. You cannot rescind them with C<no
-vars> or C<no subs>.
-
-The following pragmas are defined (and have their own documentation).
-
-=over 12
-
-=item arybase
-
-Set indexing base via $[
-
-=item attributes
-
-Get/set subroutine or variable attributes
-
-=item autodie
-
-Replace functions with ones that succeed or die with lexical scope
-
-=item autodie::exception
-
-Exceptions from autodying functions.
-
-=item autodie::exception::system
-
-Exceptions from autodying system().
-
-=item autodie::hints
-
-Provide hints about user subroutines to autodie
-
-=item autouse
-
-Postpone load of modules until a function is used
-
-=item base
-
-Establish an ISA relationship with base classes at compile time
-
-=item bigint
-
-Transparent BigInteger support for Perl
-
-=item bignum
-
-Transparent BigNumber support for Perl
-
-=item bigrat
-
-Transparent BigNumber/BigRational support for Perl
-
-=item blib
-
-Use MakeMaker's uninstalled version of a package
-
-=item bytes
-
-Force byte semantics rather than character semantics
-
-=item charnames
-
-Access to Unicode character names and named character sequences; also define character names
-
-=item constant
-
-Declare constants
-
-=item deprecate
-
-Perl pragma for deprecating the core version of a module
-
-=item diagnostics
-
-Produce verbose warning diagnostics
-
-=item encoding
-
-Allows you to write your script in non-ascii or non-utf8
-
-=item encoding::warnings
-
-Warn on implicit encoding conversions
-
-=item feature
-
-Enable new features
-
-=item fields
-
-Compile-time class fields
-
-=item filetest
-
-Control the filetest permission operators
-
-=item if
-
-C<use> a Perl module if a condition holds
-
-=item inc::latest
-
-Use modules bundled in inc/ if they are newer than installed ones
-
-=item integer
-
-Use integer arithmetic instead of floating point
-
-=item less
-
-Request less of something
-
-=item lib
-
-Manipulate @INC at compile time
-
-=item locale
-
-Use or avoid POSIX locales for built-in operations
-
-=item mro
-
-Method Resolution Order
-
-=item open
-
-Set default PerlIO layers for input and output
-
-=item ops
-
-Restrict unsafe operations when compiling
-
-=item overload
-
-Package for overloading Perl operations
-
-=item overloading
-
-Lexically control overloading
-
-=item parent
-
-Establish an ISA relationship with base classes at compile time
-
-=item perldoc
-
-Look up Perl documentation in Pod format.
-
-=item perlfaq
-
-Frequently asked questions about Perl
-
-=item perlfaq1
-
-General Questions About Perl
-
-=item perlfaq2
-
-Obtaining and Learning about Perl
-
-=item perlfaq3
-
-Programming Tools
-
-=item perlfaq4
-
-Data Manipulation
-
-=item perlfaq5
-
-Files and Formats
-
-=item perlfaq6
-
-Regular Expressions
-
-=item perlfaq7
-
-General Perl Language Issues
-
-=item perlfaq8
-
-System Interaction
-
-=item perlfaq9
-
-Web, Email and Networking
-
-=item perlfunc
-
-Perl builtin functions
-
-=item perlglossary
-
-Perl Glossary
-
-=item perlpodspeccopy
-
-Plain Old Documentation: format specification and notes
-
-=item perlvarcopy
-
-Perl predefined variables
-
-=item perlxs
-
-XS language reference manual
-
-=item perlxstut
-
-Tutorial for writing XSUBs
-
-=item perlxstypemap
-
-Perl XS C/Perl type mapping
-
-=item re
-
-Alter regular expression behaviour
-
-=item sigtrap
-
-Enable simple signal handling
-
-=item sort
-
-Control sort() behaviour
-
-=item strict
-
-Restrict unsafe constructs
-
-=item subs
-
-Predeclare sub names
-
-=item threads
-
-Perl interpreter-based threads
-
-=item threads::shared
-
-Perl extension for sharing data structures between threads
-
-=item utf8
-
-Enable/disable UTF-8 (or UTF-EBCDIC) in source code
-
-=item vars
-
-Predeclare global variable names (obsolete)
-
-=item version
-
-Perl extension for Version Objects
-
-=item vmsish
-
-Control VMS-specific language features
-
-=item warnings
-
-Control optional warnings
-
-=item warnings::register
-
-Warnings import function
-
-
-=back
-
-=head2 Standard Modules
-
-Standard, bundled modules are all expected to behave in a well-defined
-manner with respect to namespace pollution because they use the
-Exporter module. See their own documentation for details.
-
-It's possible that not all modules listed below are installed on your
-system. For example, the GDBM_File module will not be installed if you
-don't have the gdbm library.
-
-=over 12
-
-=item AnyDBM_File
-
-Provide framework for multiple DBMs
-
-=item App::Cpan
-
-Easily interact with CPAN from the command line
-
-=item App::Prove
-
-Implements the C<prove> command.
-
-=item App::Prove::State
-
-State storage for the C<prove> command.
-
-=item App::Prove::State::Result
-
-Individual test suite results.
-
-=item App::Prove::State::Result::Test
-
-Individual test results.
-
-=item Archive::Extract
-
-A generic archive extracting mechanism
-
-=item Archive::Tar
-
-Module for manipulations of tar archives
-
-=item Archive::Tar::File
-
-A subclass for in-memory extracted file from Archive::Tar
-
-=item Attribute::Handlers
-
-Simpler definition of attribute handlers
-
-=item AutoLoader
-
-Load subroutines only on demand
-
-=item AutoSplit
-
-Split a package for autoloading
-
-=item B
-
-The Perl Compiler Backend
-
-=item B::Concise
-
-Walk Perl syntax tree, printing concise info about ops
-
-=item B::Debug
-
-Walk Perl syntax tree, printing debug info about ops
-
-=item B::Deparse
-
-Perl compiler backend to produce perl code
-
-=item B::Lint
-
-Perl lint
-
-=item B::Lint::Debug
-
-Adds debugging stringification to B::
-
-=item B::Showlex
-
-Show lexical variables used in functions or files
-
-=item B::Terse
-
-Walk Perl syntax tree, printing terse info about ops
-
-=item B::Xref
-
-Generates cross reference reports for Perl programs
-
-=item Benchmark
-
-Benchmark running times of Perl code
-
-=item C<Socket>
-
-Networking constants and support functions
-
-=item CGI
-
-Handle Common Gateway Interface requests and responses
-
-=item CGI::Apache
-
-Backward compatibility module for CGI.pm
-
-=item CGI::Carp
-
-CGI routines for writing to the HTTPD (or other) error log
-
-=item CGI::Cookie
-
-Interface to HTTP Cookies
-
-=item CGI::Fast
-
-CGI Interface for Fast CGI
-
-=item CGI::Pretty
-
-Module to produce nicely formatted HTML code
-
-=item CGI::Push
-
-Simple Interface to Server Push
-
-=item CGI::Switch
-
-Backward compatibility module for defunct CGI::Switch
-
-=item CGI::Util
-
-Internal utilities used by CGI module
-
-=item CORE
-
-Namespace for Perl's core routines
-
-=item CPAN
-
-Query, download and build perl modules from CPAN sites
-
-=item CPAN::API::HOWTO
-
-A recipe book for programming with CPAN.pm
-
-=item CPAN::Distroprefs
-
-Read and match distroprefs
-
-=item CPAN::FirstTime
-
-Utility for CPAN::Config file Initialization
-
-=item CPAN::Kwalify
-
-Interface between CPAN.pm and Kwalify.pm
-
-=item CPAN::Meta
-
-The distribution metadata for a CPAN dist
-
-=item CPAN::Meta::Converter
-
-Convert CPAN distribution metadata structures
-
-=item CPAN::Meta::Feature
-
-An optional feature provided by a CPAN distribution
-
-=item CPAN::Meta::History
-
-History of CPAN Meta Spec changes
-
-=item CPAN::Meta::Prereqs
-
-A set of distribution prerequisites by phase and type
-
-=item CPAN::Meta::Requirements
-
-A set of version requirements for a CPAN dist
-
-=item CPAN::Meta::Spec
-
-Specification for CPAN distribution metadata
-
-=item CPAN::Meta::Validator
-
-Validate CPAN distribution metadata structures
-
-=item CPAN::Meta::YAML
-
-Read and write a subset of YAML for CPAN Meta files
-
-=item CPAN::Nox
-
-Wrapper around CPAN.pm without using any XS module
-
-=item CPAN::Version
-
-Utility functions to compare CPAN versions
-
-=item CPANPLUS
-
-API & CLI access to the CPAN mirrors
-
-=item CPANPLUS::Backend
-
-Programmer's interface to CPANPLUS
-
-=item CPANPLUS::Backend::RV
-
-Return value objects
-
-=item CPANPLUS::Config
-
-Configuration defaults and heuristics for CPANPLUS
-
-=item CPANPLUS::Configure
-
-Configuration for CPANPLUS
-
-=item CPANPLUS::Dist
-
-Base class for plugins
-
-=item CPANPLUS::Dist::Autobundle
-
-Distribution class for installation snapshots
-
-=item CPANPLUS::Dist::Base
-
-Base class for custom distribution classes
-
-=item CPANPLUS::Dist::Build
-
-CPANPLUS plugin to install packages that use Build.PL
-
-=item CPANPLUS::Dist::Build::Constants
-
-Constants for CPANPLUS::Dist::Build
-
-=item CPANPLUS::Dist::MM
-
-Distribution class for MakeMaker related modules
-
-=item CPANPLUS::Dist::Sample
-
-Sample code to create your own Dist::* plugin
-
-=item CPANPLUS::Error
-
-Error handling for CPANPLUS
-
-=item CPANPLUS::FAQ
-
-CPANPLUS Frequently Asked Questions
-
-=item CPANPLUS::Hacking
-
-Developing CPANPLUS
-
-=item CPANPLUS::Internals
-
-CPANPLUS internals
-
-=item CPANPLUS::Internals::Extract
-
-Internals for archive extraction
-
-=item CPANPLUS::Internals::Fetch
-
-Internals for fetching files
-
-=item CPANPLUS::Internals::Report
-
-Internals for sending test reports
-
-=item CPANPLUS::Internals::Search
-
-Internals for searching for modules
-
-=item CPANPLUS::Internals::Source
-
-Internals for updating source files
-
-=item CPANPLUS::Internals::Source::Memory
-
-In memory implementation
-
-=item CPANPLUS::Internals::Source::SQLite
-
-SQLite implementation
-
-=item CPANPLUS::Internals::Utils
-
-Convenience functions for CPANPLUS
-
-=item CPANPLUS::Module
-
-CPAN module objects for CPANPLUS
-
-=item CPANPLUS::Module::Author
-
-CPAN author object for CPANPLUS
-
-=item CPANPLUS::Module::Author::Fake
-
-Dummy author object for CPANPLUS
-
-=item CPANPLUS::Module::Checksums
-
-Checking the checksum of a distribution
-
-=item CPANPLUS::Module::Fake
-
-Fake module object for internal use
-
-=item CPANPLUS::Selfupdate
-
-Self-updating for CPANPLUS
-
-=item CPANPLUS::Shell
-
-Base class for CPANPLUS shells
-
-=item CPANPLUS::Shell::Classic
-
-CPAN.pm emulation for CPANPLUS
-
-=item CPANPLUS::Shell::Default
-
-The default CPANPLUS shell
-
-=item CPANPLUS::Shell::Default::Plugins::CustomSource
-
-Add custom sources to CPANPLUS
-
-=item CPANPLUS::Shell::Default::Plugins::HOWTO
-
-Documentation on how to write your own plugins
-
-=item CPANPLUS::Shell::Default::Plugins::Remote
-
-Connect to a remote CPANPLUS
-
-=item CPANPLUS::Shell::Default::Plugins::Source
-
-Read in CPANPLUS commands
-
-=item Carp
-
-Alternative warn and die for modules
-
-=item Class::Struct
-
-Declare struct-like datatypes as Perl classes
-
-=item Compress::Raw::Bzip2
-
-Low-Level Interface to bzip2 compression library
-
-=item Compress::Raw::Zlib
-
-Low-Level Interface to zlib compression library
-
-=item Compress::Zlib
-
-Interface to zlib compression library
-
-=item Config
-
-Access Perl configuration information
-
-=item Cwd
-
-Get pathname of current working directory
-
-=item DB
-
-Programmatic interface to the Perl debugging API
-
-=item DBM_Filter
-
-Filter DBM keys/values
-
-=item DBM_Filter::compress
-
-Filter for DBM_Filter
-
-=item DBM_Filter::encode
-
-Filter for DBM_Filter
-
-=item DBM_Filter::int32
-
-Filter for DBM_Filter
-
-=item DBM_Filter::null
-
-Filter for DBM_Filter
-
-=item DBM_Filter::utf8
-
-Filter for DBM_Filter
-
-=item DB_File
-
-Perl5 access to Berkeley DB version 1.x
-
-=item Data::Dumper
-
-Stringified perl data structures, suitable for both printing and C<eval>
-
-=item Devel::InnerPackage
-
-Find all the inner packages of a package
-
-=item Devel::PPPort
-
-Perl/Pollution/Portability
-
-=item Devel::Peek
-
-A data debugging tool for the XS programmer
-
-=item Devel::SelfStubber
-
-Generate stubs for a SelfLoading module
-
-=item Digest
-
-Modules that calculate message digests
-
-=item Digest::MD5
-
-Perl interface to the MD5 Algorithm
-
-=item Digest::SHA
-
-Perl extension for SHA-1/224/256/384/512
-
-=item Digest::base
-
-Digest base class
-
-=item Digest::file
-
-Calculate digests of files
-
-=item DirHandle
-
-Supply object methods for directory handles
-
-=item Dumpvalue
-
-Provides screen dump of Perl data.
-
-=item DynaLoader
-
-Dynamically load C libraries into Perl code
-
-=item Encode
-
-Character encodings in Perl
-
-=item Encode::Alias
-
-Alias definitions to encodings
-
-=item Encode::Byte
-
-Single Byte Encodings
-
-=item Encode::CJKConstants
-
-Internally used by Encode::??::ISO_2022_*
-
-=item Encode::CN
-
-China-based Chinese Encodings
-
-=item Encode::CN::HZ
-
-Internally used by Encode::CN
-
-=item Encode::Config
-
-Internally used by Encode
-
-=item Encode::EBCDIC
-
-EBCDIC Encodings
-
-=item Encode::Encoder
-
-Object Oriented Encoder
-
-=item Encode::Encoding
-
-Encode Implementation Base Class
-
-=item Encode::GSM0338
-
-ESTI GSM 03.38 Encoding
-
-=item Encode::Guess
-
-Guesses encoding from data
-
-=item Encode::JP
-
-Japanese Encodings
-
-=item Encode::JP::H2Z
-
-Internally used by Encode::JP::2022_JP*
-
-=item Encode::JP::JIS7
-
-Internally used by Encode::JP
-
-=item Encode::KR
-
-Korean Encodings
-
-=item Encode::KR::2022_KR
-
-Internally used by Encode::KR
-
-=item Encode::MIME::Header
-
-MIME 'B' and 'Q' header encoding
-
-=item Encode::MIME::Name
-
-Internally used by Encode
-
-=item Encode::PerlIO
-
-A detailed document on Encode and PerlIO
-
-=item Encode::Supported
-
-Encodings supported by Encode
-
-=item Encode::Symbol
-
-Symbol Encodings
-
-=item Encode::TW
-
-Taiwan-based Chinese Encodings
-
-=item Encode::Unicode
-
-Various Unicode Transformation Formats
-
-=item Encode::Unicode::UTF7
-
-UTF-7 encoding
-
-=item English
-
-Use nice English (or awk) names for ugly punctuation variables
-
-=item Env
-
-Perl module that imports environment variables as scalars or arrays
-
-=item Errno
-
-System errno constants
-
-=item Exporter
-
-Implements default import method for modules
-
-=item Exporter::Heavy
-
-Exporter guts
-
-=item ExtUtils::CBuilder
-
-Compile and link C code for Perl modules
-
-=item ExtUtils::CBuilder::Platform::Windows
-
-Builder class for Windows platforms
-
-=item ExtUtils::Command
-
-Utilities to replace common UNIX commands in Makefiles etc.
-
-=item ExtUtils::Command::MM
-
-Commands for the MM's to use in Makefiles
-
-=item ExtUtils::Constant
-
-Generate XS code to import C header constants
-
-=item ExtUtils::Constant::Base
-
-Base class for ExtUtils::Constant objects
-
-=item ExtUtils::Constant::Utils
-
-Helper functions for ExtUtils::Constant
-
-=item ExtUtils::Constant::XS
-
-Generate C code for XS modules' constants.
-
-=item ExtUtils::Embed
-
-Utilities for embedding Perl in C/C++ applications
-
-=item ExtUtils::Install
-
-Install files from here to there
-
-=item ExtUtils::Installed
-
-Inventory management of installed modules
-
-=item ExtUtils::Liblist
-
-Determine libraries to use and how to use them
-
-=item ExtUtils::MM
-
-OS adjusted ExtUtils::MakeMaker subclass
-
-=item ExtUtils::MM_AIX
-
-AIX specific subclass of ExtUtils::MM_Unix
-
-=item ExtUtils::MM_Any
-
-Platform-agnostic MM methods
-
-=item ExtUtils::MM_BeOS
-
-Methods to override UN*X behaviour in ExtUtils::MakeMaker
-
-=item ExtUtils::MM_Cygwin
-
-Methods to override UN*X behaviour in ExtUtils::MakeMaker
-
-=item ExtUtils::MM_DOS
-
-DOS specific subclass of ExtUtils::MM_Unix
-
-=item ExtUtils::MM_Darwin
-
-Special behaviors for OS X
-
-=item ExtUtils::MM_MacOS
-
-Once produced Makefiles for MacOS Classic
-
-=item ExtUtils::MM_NW5
-
-Methods to override UN*X behaviour in ExtUtils::MakeMaker
-
-=item ExtUtils::MM_OS2
-
-Methods to override UN*X behaviour in ExtUtils::MakeMaker
-
-=item ExtUtils::MM_QNX
-
-QNX specific subclass of ExtUtils::MM_Unix
-
-=item ExtUtils::MM_UWIN
-
-U/WIN specific subclass of ExtUtils::MM_Unix
-
-=item ExtUtils::MM_Unix
-
-Methods used by ExtUtils::MakeMaker
-
-=item ExtUtils::MM_VMS
-
-Methods to override UN*X behaviour in ExtUtils::MakeMaker
-
-=item ExtUtils::MM_VOS
-
-VOS specific subclass of ExtUtils::MM_Unix
-
-=item ExtUtils::MM_Win32
-
-Methods to override UN*X behaviour in ExtUtils::MakeMaker
-
-=item ExtUtils::MM_Win95
-
-Method to customize MakeMaker for Win9X
-
-=item ExtUtils::MY
-
-ExtUtils::MakeMaker subclass for customization
-
-=item ExtUtils::MakeMaker
-
-Create a module Makefile
-
-=item ExtUtils::MakeMaker::Config
-
-Wrapper around Config.pm
-
-=item ExtUtils::MakeMaker::FAQ
-
-Frequently Asked Questions About MakeMaker
-
-=item ExtUtils::MakeMaker::Tutorial
-
-Writing a module with MakeMaker
-
-=item ExtUtils::Manifest
-
-Utilities to write and check a MANIFEST file
-
-=item ExtUtils::Mkbootstrap
-
-Make a bootstrap file for use by DynaLoader
-
-=item ExtUtils::Mksymlists
-
-Write linker options files for dynamic extension
-
-=item ExtUtils::Packlist
-
-Manage .packlist files
-
-=item ExtUtils::ParseXS
-
-Converts Perl XS code into C code
-
-=item ExtUtils::ParseXS::Constants
-
-Initialization values for some globals
-
-=item ExtUtils::ParseXS::Utilities
-
-Subroutines used with ExtUtils::ParseXS
-
-=item ExtUtils::Typemaps
-
-Read/Write/Modify Perl/XS typemap files
-
-=item ExtUtils::Typemaps::Cmd
-
-Quick commands for handling typemaps
-
-=item ExtUtils::Typemaps::InputMap
-
-Entry in the INPUT section of a typemap
-
-=item ExtUtils::Typemaps::OutputMap
-
-Entry in the OUTPUT section of a typemap
-
-=item ExtUtils::Typemaps::Type
-
-Entry in the TYPEMAP section of a typemap
-
-=item ExtUtils::XSSymSet
-
-Keep sets of symbol names palatable to the VMS linker
-
-=item ExtUtils::testlib
-
-Add blib/* directories to @INC
-
-=item Fatal
-
-Replace functions with equivalents which succeed or die
-
-=item Fcntl
-
-Load the C Fcntl.h defines
-
-=item File::Basename
-
-Parse file paths into directory, filename and suffix.
-
-=item File::CheckTree
-
-Run many filetest checks on a tree
-
-=item File::Compare
-
-Compare files or filehandles
-
-=item File::Copy
-
-Copy files or filehandles
-
-=item File::DosGlob
-
-DOS like globbing and then some
-
-=item File::Fetch
-
-A generic file fetching mechanism
-
-=item File::Find
-
-Traverse a directory tree.
-
-=item File::Glob
-
-Perl extension for BSD glob routine
-
-=item File::GlobMapper
-
-Extend File Glob to Allow Input and Output Files
-
-=item File::Path
-
-Create or remove directory trees
-
-=item File::Spec
-
-Portably perform operations on file names
-
-=item File::Spec::Cygwin
-
-Methods for Cygwin file specs
-
-=item File::Spec::Epoc
-
-Methods for Epoc file specs
-
-=item File::Spec::Functions
-
-Portably perform operations on file names
-
-=item File::Spec::Mac
-
-File::Spec for Mac OS (Classic)
-
-=item File::Spec::OS2
-
-Methods for OS/2 file specs
-
-=item File::Spec::Unix
-
-File::Spec for Unix, base for other File::Spec modules
-
-=item File::Spec::VMS
-
-Methods for VMS file specs
-
-=item File::Spec::Win32
-
-Methods for Win32 file specs
-
-=item File::Temp
-
-Return name and handle of a temporary file safely
-
-=item File::stat
-
-By-name interface to Perl's built-in stat() functions
-
-=item FileCache
-
-Keep more files open than the system permits
-
-=item FileHandle
-
-Supply object methods for filehandles
-
-=item Filter::Simple
-
-Simplified source filtering
-
-=item Filter::Util::Call
-
-Perl Source Filter Utility Module
-
-=item FindBin
-
-Locate directory of original perl script
-
-=item GDBM_File
-
-Perl5 access to the gdbm library.
-
-=item Getopt::Long
-
-Extended processing of command line options
-
-=item Getopt::Std
-
-Process single-character switches with switch clustering
-
-=item HTTP::Tiny
-
-A small, simple, correct HTTP/1.1 client
-
-=item Hash::Util
-
-A selection of general-utility hash subroutines
-
-=item Hash::Util::FieldHash
-
-Support for Inside-Out Classes
-
-=item I18N::Collate
-
-Compare 8-bit scalar data according to the current locale
-
-=item I18N::LangTags
-
-Functions for dealing with RFC3066-style language tags
-
-=item I18N::LangTags::Detect
-
-Detect the user's language preferences
-
-=item I18N::LangTags::List
-
-Tags and names for human languages
-
-=item I18N::Langinfo
-
-Query locale information
-
-=item IO
-
-Load various IO modules
-
-=item IO::Compress::Base
-
-Base Class for IO::Compress modules
-
-=item IO::Compress::Bzip2
-
-Write bzip2 files/buffers
-
-=item IO::Compress::Deflate
-
-Write RFC 1950 files/buffers
-
-=item IO::Compress::FAQ
-
-Frequently Asked Questions about IO::Compress
-
-=item IO::Compress::Gzip
-
-Write RFC 1952 files/buffers
-
-=item IO::Compress::RawDeflate
-
-Write RFC 1951 files/buffers
-
-=item IO::Compress::Zip
-
-Write zip files/buffers
-
-=item IO::Dir
-
-Supply object methods for directory handles
-
-=item IO::File
-
-Supply object methods for filehandles
-
-=item IO::Handle
-
-Supply object methods for I/O handles
-
-=item IO::Pipe
-
-Supply object methods for pipes
-
-=item IO::Poll
-
-Object interface to system poll call
-
-=item IO::Seekable
-
-Supply seek based methods for I/O objects
-
-=item IO::Select
-
-OO interface to the select system call
-
-=item IO::Socket
-
-Object interface to socket communications
-
-=item IO::Socket::INET
-
-Object interface for AF_INET domain sockets
-
-=item IO::Socket::UNIX
-
-Object interface for AF_UNIX domain sockets
-
-=item IO::Uncompress::AnyInflate
-
-Uncompress zlib-based (zip, gzip) file/buffer
-
-=item IO::Uncompress::AnyUncompress
-
-Uncompress gzip, zip, bzip2 or lzop file/buffer
-
-=item IO::Uncompress::Base
-
-Base Class for IO::Uncompress modules
-
-=item IO::Uncompress::Bunzip2
-
-Read bzip2 files/buffers
-
-=item IO::Uncompress::Gunzip
-
-Read RFC 1952 files/buffers
-
-=item IO::Uncompress::Inflate
-
-Read RFC 1950 files/buffers
-
-=item IO::Uncompress::RawInflate
-
-Read RFC 1951 files/buffers
-
-=item IO::Uncompress::Unzip
-
-Read zip files/buffers
-
-=item IO::Zlib
-
-IO:: style interface to L<Compress::Zlib>
-
-=item IPC::Cmd
-
-Finding and running system commands made easy
-
-=item IPC::Msg
-
-SysV Msg IPC object class
-
-=item IPC::Open2
-
-Open a process for both reading and writing using open2()
-
-=item IPC::Open3
-
-Open a process for reading, writing, and error handling using open3()
-
-=item IPC::Semaphore
-
-SysV Semaphore IPC object class
-
-=item IPC::SharedMem
-
-SysV Shared Memory IPC object class
-
-=item IPC::SysV
-
-System V IPC constants and system calls
-
-=item JSON::PP
-
-JSON::XS compatible pure-Perl module.
-
-=item JSON::PP::Boolean
-
-Dummy module providing JSON::PP::Boolean
-
-=item List::Util
-
-A selection of general-utility list subroutines
-
-=item List::Util::XS
-
-Indicate if List::Util was compiled with a C compiler
-
-=item Locale::Codes
-
-A distribution of modules to handle locale codes
-
-=item Locale::Codes::API
-
-A description of the callable function in each module
-
-=item Locale::Codes::Changes
-
-Details changes to Locale::Codes
-
-=item Locale::Codes::Constants
-
-Constants for Locale codes
-
-=item Locale::Codes::Country
-
-Standard codes for country identification
-
-=item Locale::Codes::Country_Codes
-
-Country codes for the Locale::Codes::Country module
-
-=item Locale::Codes::Country_Retired
-
-Retired country codes for the Locale::Codes::Country module
-
-=item Locale::Codes::Currency
-
-Standard codes for currency identification
-
-=item Locale::Codes::Currency_Codes
-
-Currency codes for the Locale::Codes::Currency module
-
-=item Locale::Codes::Currency_Retired
-
-Retired currency codes for the Locale::Codes::Currency module
-
-=item Locale::Codes::LangExt
-
-Standard codes for language extension identification
-
-=item Locale::Codes::LangExt_Codes
-
-Langext codes for the Locale::Codes::LangExt module
-
-=item Locale::Codes::LangExt_Retired
-
-Retired langext codes for the Locale::Codes::LangExt module
-
-=item Locale::Codes::LangFam
-
-Standard codes for language extension identification
-
-=item Locale::Codes::LangFam_Codes
-
-Langfam codes for the Locale::Codes::LangFam module
-
-=item Locale::Codes::LangFam_Retired
-
-Retired langfam codes for the Locale::Codes::LangFam module
-
-=item Locale::Codes::LangVar
-
-Standard codes for language variation identification
-
-=item Locale::Codes::LangVar_Codes
-
-Langvar codes for the Locale::Codes::LangVar module
-
-=item Locale::Codes::LangVar_Retired
-
-Retired langvar codes for the Locale::Codes::LangVar module
-
-=item Locale::Codes::Language
-
-Standard codes for language identification
-
-=item Locale::Codes::Language_Codes
-
-Language codes for the Locale::Codes::Language module
-
-=item Locale::Codes::Language_Retired
-
-Retired language codes for the Locale::Codes::Language module
-
-=item Locale::Codes::Script
-
-Standard codes for script identification
-
-=item Locale::Codes::Script_Codes
-
-Script codes for the Locale::Codes::Script module
-
-=item Locale::Codes::Script_Retired
-
-Retired script codes for the Locale::Codes::Script module
-
-=item Locale::Country
-
-Standard codes for country identification
-
-=item Locale::Currency
-
-Standard codes for currency identification
-
-=item Locale::Language
-
-Standard codes for language identification
-
-=item Locale::Maketext
-
-Framework for localization
-
-=item Locale::Maketext::Cookbook
-
-Recipes for using Locale::Maketext
-
-=item Locale::Maketext::Guts
-
-Deprecated module to load Locale::Maketext utf8 code
-
-=item Locale::Maketext::GutsLoader
-
-Deprecated module to load Locale::Maketext utf8 code
-
-=item Locale::Maketext::Simple
-
-Simple interface to Locale::Maketext::Lexicon
-
-=item Locale::Maketext::TPJ13
-
-Article about software localization
-
-=item Locale::Script
-
-Standard codes for script identification
-
-=item Log::Message
-
-A generic message storing mechanism;
-
-=item Log::Message::Config
-
-Configuration options for Log::Message
-
-=item Log::Message::Handlers
-
-Message handlers for Log::Message
-
-=item Log::Message::Item
-
-Message objects for Log::Message
-
-=item Log::Message::Simple
-
-Simplified interface to Log::Message
-
-=item MIME::Base64
-
-Encoding and decoding of base64 strings
-
-=item MIME::QuotedPrint
-
-Encoding and decoding of quoted-printable strings
-
-=item Math::BigFloat
-
-Arbitrary size floating point math package
-
-=item Math::BigInt
-
-Arbitrary size integer/float math package
-
-=item Math::BigInt::Calc
-
-Pure Perl module to support Math::BigInt
-
-=item Math::BigInt::CalcEmu
-
-Emulate low-level math with BigInt code
-
-=item Math::BigInt::FastCalc
-
-Math::BigInt::Calc with some XS for more speed
-
-=item Math::BigRat
-
-Arbitrary big rational numbers
-
-=item Math::Complex
-
-Complex numbers and associated mathematical functions
-
-=item Math::Trig
-
-Trigonometric functions
-
-=item Memoize
-
-Make functions faster by trading space for time
-
-=item Memoize::AnyDBM_File
-
-Glue to provide EXISTS for AnyDBM_File for Storable use
-
-=item Memoize::Expire
-
-Plug-in module for automatic expiration of memoized values
-
-=item Memoize::ExpireFile
-
-Test for Memoize expiration semantics
-
-=item Memoize::ExpireTest
-
-Test for Memoize expiration semantics
-
-=item Memoize::NDBM_File
-
-Glue to provide EXISTS for NDBM_File for Storable use
-
-=item Memoize::SDBM_File
-
-Glue to provide EXISTS for SDBM_File for Storable use
-
-=item Memoize::Storable
-
-Store Memoized data in Storable database
-
-=item Module::Build
-
-Build and install Perl modules
-
-=item Module::Build::API
-
-API Reference for Module Authors
-
-=item Module::Build::Authoring
-
-Authoring Module::Build modules
-
-=item Module::Build::Base
-
-Default methods for Module::Build
-
-=item Module::Build::Bundling
-
-How to bundle Module::Build with a distribution
-
-=item Module::Build::Compat
-
-Compatibility with ExtUtils::MakeMaker
-
-=item Module::Build::ConfigData
-
-Configuration for Module::Build
-
-=item Module::Build::Cookbook
-
-Examples of Module::Build Usage
-
-=item Module::Build::ModuleInfo
-
-DEPRECATED
-
-=item Module::Build::Notes
-
-Create persistent distribution configuration modules
-
-=item Module::Build::PPMMaker
-
-Perl Package Manager file creation
-
-=item Module::Build::Platform::Amiga
-
-Builder class for Amiga platforms
-
-=item Module::Build::Platform::Default
-
-Stub class for unknown platforms
-
-=item Module::Build::Platform::EBCDIC
-
-Builder class for EBCDIC platforms
-
-=item Module::Build::Platform::MPEiX
-
-Builder class for MPEiX platforms
-
-=item Module::Build::Platform::MacOS
-
-Builder class for MacOS platforms
-
-=item Module::Build::Platform::RiscOS
-
-Builder class for RiscOS platforms
-
-=item Module::Build::Platform::Unix
-
-Builder class for Unix platforms
-
-=item Module::Build::Platform::VMS
-
-Builder class for VMS platforms
-
-=item Module::Build::Platform::VOS
-
-Builder class for VOS platforms
-
-=item Module::Build::Platform::Windows
-
-Builder class for Windows platforms
-
-=item Module::Build::Platform::aix
-
-Builder class for AIX platform
-
-=item Module::Build::Platform::cygwin
-
-Builder class for Cygwin platform
-
-=item Module::Build::Platform::darwin
-
-Builder class for Mac OS X platform
-
-=item Module::Build::Platform::os2
-
-Builder class for OS/2 platform
-
-=item Module::Build::Version
-
-DEPRECATED
-
-=item Module::Build::YAML
-
-DEPRECATED
-
-=item Module::CoreList
-
-What modules shipped with versions of perl
-
-=item Module::Load
-
-Runtime require of both modules and files
-
-=item Module::Load::Conditional
-
-Looking up module information / loading at runtime
-
-=item Module::Loaded
-
-Mark modules as loaded or unloaded
-
-=item Module::Metadata
-
-Gather package and POD information from perl module files
-
-=item Module::Pluggable
-
-Automatically give your module the ability to have plugins
-
-=item Module::Pluggable::Object
-
-Automatically give your module the ability to have plugins
-
-=item NDBM_File
-
-Tied access to ndbm files
-
-=item NEXT
-
-Provide a pseudo-class NEXT (et al) that allows method redispatch
-
-=item Net::Cmd
-
-Network Command class (as used by FTP, SMTP etc)
-
-=item Net::Config
-
-Local configuration data for libnet
-
-=item Net::Domain
-
-Attempt to evaluate the current host's internet name and domain
-
-=item Net::FTP
-
-FTP Client class
-
-=item Net::NNTP
-
-NNTP Client class
-
-=item Net::Netrc
-
-OO interface to users netrc file
-
-=item Net::POP3
-
-Post Office Protocol 3 Client class (RFC1939)
-
-=item Net::Ping
-
-Check a remote host for reachability
-
-=item Net::SMTP
-
-Simple Mail Transfer Protocol Client
-
-=item Net::Time
-
-Time and daytime network client interface
-
-=item Net::hostent
-
-By-name interface to Perl's built-in gethost*() functions
-
-=item Net::libnetFAQ
-
-Libnet Frequently Asked Questions
-
-=item Net::netent
-
-By-name interface to Perl's built-in getnet*() functions
-
-=item Net::protoent
-
-By-name interface to Perl's built-in getproto*() functions
-
-=item Net::servent
-
-By-name interface to Perl's built-in getserv*() functions
-
-=item O
-
-Generic interface to Perl Compiler backends
-
-=item ODBM_File
-
-Tied access to odbm files
-
-=item Object::Accessor
-
-Interface to create per object accessors
-
-=item Opcode
-
-Disable named opcodes when compiling perl code
-
-=item POSIX
-
-Perl interface to IEEE Std 1003.1
-
-=item Package::Constants
-
-List all constants declared in a package
-
-=item Params::Check
-
-A generic input parsing/checking mechanism.
-
-=item Parse::CPAN::Meta
-
-Parse META.yml and META.json CPAN metadata files
-
-=item Perl::OSType
-
-Map Perl operating system names to generic types
-
-=item PerlIO
-
-On demand loader for PerlIO layers and root of PerlIO::* name space
-
-=item PerlIO::encoding
-
-Encoding layer
-
-=item PerlIO::mmap
-
-Memory mapped IO
-
-=item PerlIO::scalar
-
-In-memory IO, scalar IO
-
-=item PerlIO::via
-
-Helper class for PerlIO layers implemented in perl
-
-=item PerlIO::via::QuotedPrint
-
-PerlIO layer for quoted-printable strings
-
-=item Pod::Checker
-
-Check pod documents for syntax errors
-
-=item Pod::Escapes
-
-For resolving Pod EE<lt>...E<gt> sequences
-
-=item Pod::Find
-
-Find POD documents in directory trees
-
-=item Pod::Functions
-
-Group Perl's functions a la perlfunc.pod
-
-=item Pod::Html
-
-Module to convert pod files to HTML
-
-=item Pod::InputObjects
-
-Objects representing POD input paragraphs, commands, etc.
-
-=item Pod::LaTeX
-
-Convert Pod data to formatted Latex
-
-=item Pod::Man
-
-Convert POD data to formatted *roff input
-
-=item Pod::ParseLink
-
-Parse an LE<lt>E<gt> formatting code in POD text
-
-=item Pod::ParseUtils
-
-Helpers for POD parsing and conversion
-
-=item Pod::Parser
-
-Base class for creating POD filters and translators
-
-=item Pod::Perldoc
-
-Look up Perl documentation in Pod format.
-
-=item Pod::Perldoc::BaseTo
-
-Base for Pod::Perldoc formatters
-
-=item Pod::Perldoc::GetOptsOO
-
-Customized option parser for Pod::Perldoc
-
-=item Pod::Perldoc::ToANSI
-
-Render Pod with ANSI color escapes
-
-=item Pod::Perldoc::ToChecker
-
-Let Perldoc check Pod for errors
-
-=item Pod::Perldoc::ToMan
-
-Let Perldoc render Pod as man pages
-
-=item Pod::Perldoc::ToNroff
-
-Let Perldoc convert Pod to nroff
-
-=item Pod::Perldoc::ToPod
-
-Let Perldoc render Pod as ... Pod!
-
-=item Pod::Perldoc::ToRtf
-
-Let Perldoc render Pod as RTF
-
-=item Pod::Perldoc::ToTerm
-
-Render Pod with terminal escapes
-
-=item Pod::Perldoc::ToText
-
-Let Perldoc render Pod as plaintext
-
-=item Pod::Perldoc::ToTk
-
-Let Perldoc use Tk::Pod to render Pod
-
-=item Pod::Perldoc::ToXml
-
-Let Perldoc render Pod as XML
-
-=item Pod::PlainText
-
-Convert POD data to formatted ASCII text
-
-=item Pod::Select
-
-Extract selected sections of POD from input
-
-=item Pod::Simple
-
-Framework for parsing Pod
-
-=item Pod::Simple::Checker
-
-Check the Pod syntax of a document
-
-=item Pod::Simple::Debug
-
-Put Pod::Simple into trace/debug mode
-
-=item Pod::Simple::DumpAsText
-
-Dump Pod-parsing events as text
-
-=item Pod::Simple::DumpAsXML
-
-Turn Pod into XML
-
-=item Pod::Simple::HTML
-
-Convert Pod to HTML
-
-=item Pod::Simple::HTMLBatch
-
-Convert several Pod files to several HTML files
-
-=item Pod::Simple::LinkSection
-
-Represent "section" attributes of L codes
-
-=item Pod::Simple::Methody
-
-Turn Pod::Simple events into method calls
-
-=item Pod::Simple::PullParser
-
-A pull-parser interface to parsing Pod
-
-=item Pod::Simple::PullParserEndToken
-
-End-tokens from Pod::Simple::PullParser
-
-=item Pod::Simple::PullParserStartToken
-
-Start-tokens from Pod::Simple::PullParser
-
-=item Pod::Simple::PullParserTextToken
-
-Text-tokens from Pod::Simple::PullParser
-
-=item Pod::Simple::PullParserToken
-
-Tokens from Pod::Simple::PullParser
-
-=item Pod::Simple::RTF
-
-Format Pod as RTF
-
-=item Pod::Simple::Search
-
-Find POD documents in directory trees
-
-=item Pod::Simple::SimpleTree
-
-Parse Pod into a simple parse tree
-
-=item Pod::Simple::Subclassing
-
-Write a formatter as a Pod::Simple subclass
-
-=item Pod::Simple::Text
-
-Format Pod as plaintext
-
-=item Pod::Simple::TextContent
-
-Get the text content of Pod
-
-=item Pod::Simple::XHTML
-
-Format Pod as validating XHTML
-
-=item Pod::Simple::XMLOutStream
-
-Turn Pod into XML
-
-=item Pod::Text
-
-Convert POD data to formatted ASCII text
-
-=item Pod::Text::Color
-
-Convert POD data to formatted color ASCII text
-
-=item Pod::Text::Termcap
-
-Convert POD data to ASCII text with format escapes
-
-=item Pod::Usage
-
-Print a usage message from embedded pod documentation
-
-=item SDBM_File
-
-Tied access to sdbm files
-
-=item Safe
-
-Compile and execute code in restricted compartments
-
-=item Scalar::Util
-
-A selection of general-utility scalar subroutines
-
-=item Search::Dict
-
-Look - search for key in dictionary file
-
-=item SelectSaver
-
-Save and restore selected file handle
-
-=item SelfLoader
-
-Load functions only on demand
-
-=item Storable
-
-Persistence for Perl data structures
-
-=item Symbol
-
-Manipulate Perl symbols and their names
-
-=item Sys::Hostname
-
-Try every conceivable way to get hostname
-
-=item Sys::Syslog
-
-Perl interface to the UNIX syslog(3) calls
-
-=item Sys::Syslog::Win32
-
-Win32 support for Sys::Syslog
-
-=item TAP::Base
-
-Base class that provides common functionality to L<TAP::Parser>
-
-=item TAP::Formatter::Base
-
-Base class for harness output delegates
-
-=item TAP::Formatter::Color
-
-Run Perl test scripts with color
-
-=item TAP::Formatter::Console
-
-Harness output delegate for default console output
-
-=item TAP::Formatter::Console::ParallelSession
-
-Harness output delegate for parallel console output
-
-=item TAP::Formatter::Console::Session
-
-Harness output delegate for default console output
-
-=item TAP::Formatter::File
-
-Harness output delegate for file output
-
-=item TAP::Formatter::File::Session
-
-Harness output delegate for file output
-
-=item TAP::Formatter::Session
-
-Abstract base class for harness output delegate
-
-=item TAP::Harness
-
-Run test scripts with statistics
-
-=item TAP::Object
-
-Base class that provides common functionality to all C<TAP::*> modules
-
-=item TAP::Parser
-
-Parse L<TAP|Test::Harness::TAP> output
-
-=item TAP::Parser::Aggregator
-
-Aggregate TAP::Parser results
-
-=item TAP::Parser::Grammar
-
-A grammar for the Test Anything Protocol.
-
-=item TAP::Parser::Iterator
-
-Base class for TAP source iterators
-
-=item TAP::Parser::Iterator::Array
-
-Iterator for array-based TAP sources
-
-=item TAP::Parser::Iterator::Process
-
-Iterator for process-based TAP sources
-
-=item TAP::Parser::Iterator::Stream
-
-Iterator for filehandle-based TAP sources
-
-=item TAP::Parser::IteratorFactory
-
-Figures out which SourceHandler objects to use for a given Source
-
-=item TAP::Parser::Multiplexer
-
-Multiplex multiple TAP::Parsers
-
-=item TAP::Parser::Result
-
-Base class for TAP::Parser output objects
-
-=item TAP::Parser::Result::Bailout
-
-Bailout result token.
-
-=item TAP::Parser::Result::Comment
-
-Comment result token.
-
-=item TAP::Parser::Result::Plan
-
-Plan result token.
-
-=item TAP::Parser::Result::Pragma
-
-TAP pragma token.
-
-=item TAP::Parser::Result::Test
-
-Test result token.
-
-=item TAP::Parser::Result::Unknown
-
-Unknown result token.
-
-=item TAP::Parser::Result::Version
-
-TAP syntax version token.
-
-=item TAP::Parser::Result::YAML
-
-YAML result token.
-
-=item TAP::Parser::ResultFactory
-
-Factory for creating TAP::Parser output objects
-
-=item TAP::Parser::Scheduler
-
-Schedule tests during parallel testing
-
-=item TAP::Parser::Scheduler::Job
-
-A single testing job.
-
-=item TAP::Parser::Scheduler::Spinner
-
-A no-op job.
-
-=item TAP::Parser::Source
-
-A TAP source & meta data about it
-
-=item TAP::Parser::SourceHandler
-
-Base class for different TAP source handlers
-
-=item TAP::Parser::SourceHandler::Executable
-
-Stream output from an executable TAP source
-
-=item TAP::Parser::SourceHandler::File
-
-Stream TAP from a text file.
-
-=item TAP::Parser::SourceHandler::Handle
-
-Stream TAP from an IO::Handle or a GLOB.
-
-=item TAP::Parser::SourceHandler::Perl
-
-Stream TAP from a Perl executable
-
-=item TAP::Parser::SourceHandler::RawTAP
-
-Stream output from raw TAP in a scalar/array ref.
-
-=item TAP::Parser::Utils
-
-Internal TAP::Parser utilities
-
-=item TAP::Parser::YAMLish::Reader
-
-Read YAMLish data from iterator
-
-=item TAP::Parser::YAMLish::Writer
-
-Write YAMLish data
-
-=item Term::ANSIColor
-
-Color screen output using ANSI escape sequences
-
-=item Term::Cap
-
-Perl termcap interface
-
-=item Term::Complete
-
-Perl word completion module
-
-=item Term::ReadLine
-
-Perl interface to various C<readline> packages.
-
-=item Term::UI
-
-Term::ReadLine UI made easy
-
-=item Term::UI::History
-
-History function
-
-=item Test
-
-Provides a simple framework for writing test scripts
-
-=item Test::Builder
-
-Backend for building test libraries
-
-=item Test::Builder::Module
-
-Base class for test modules
-
-=item Test::Builder::Tester
-
-Test testsuites that have been built with
-
-=item Test::Builder::Tester::Color
-
-Turn on colour in Test::Builder::Tester
-
-=item Test::Harness
-
-Run Perl standard test scripts with statistics
-
-=item Test::More
-
-Yet another framework for writing test scripts
-
-=item Test::Simple
-
-Basic utilities for writing tests.
-
-=item Test::Tutorial
-
-A tutorial about writing really basic tests
-
-=item Text::Abbrev
-
-Abbrev - create an abbreviation table from a list
-
-=item Text::Balanced
-
-Extract delimited text sequences from strings.
-
-=item Text::ParseWords
-
-Parse text into an array of tokens or array of arrays
-
-=item Text::Soundex
-
-Implementation of the soundex algorithm.
-
-=item Text::Tabs
-
-Expand and unexpand tabs per the unix expand(1) and unexpand(1)
-
-=item Text::Wrap
-
-Line wrapping to form simple paragraphs
-
-=item Thread
-
-Manipulate threads in Perl (for old code only)
-
-=item Thread::Queue
-
-Thread-safe queues
-
-=item Thread::Semaphore
-
-Thread-safe semaphores
-
-=item Tie::Array
-
-Base class for tied arrays
-
-=item Tie::File
-
-Access the lines of a disk file via a Perl array
-
-=item Tie::Handle
-
-Base class definitions for tied handles
-
-=item Tie::Hash
-
-Base class definitions for tied hashes
-
-=item Tie::Hash::NamedCapture
-
-Named regexp capture buffers
-
-=item Tie::Memoize
-
-Add data to hash when needed
-
-=item Tie::RefHash
-
-Use references as hash keys
-
-=item Tie::Scalar
-
-Base class definitions for tied scalars
-
-=item Tie::StdHandle
-
-Base class definitions for tied handles
-
-=item Tie::SubstrHash
-
-Fixed-table-size, fixed-key-length hashing
-
-=item Time::HiRes
-
-High resolution alarm, sleep, gettimeofday, interval timers
-
-=item Time::Local
-
-Efficiently compute time from local and GMT time
-
-=item Time::Piece
-
-Object Oriented time objects
-
-=item Time::Seconds
-
-A simple API to convert seconds to other date values
-
-=item Time::gmtime
-
-By-name interface to Perl's built-in gmtime() function
-
-=item Time::localtime
-
-By-name interface to Perl's built-in localtime() function
-
-=item Time::tm
-
-Internal object used by Time::gmtime and Time::localtime
-
-=item UNIVERSAL
-
-Base class for ALL classes (blessed references)
-
-=item Unicode::Collate
-
-Unicode Collation Algorithm
-
-=item Unicode::Collate::CJK::Big5
-
-Weighting CJK Unified Ideographs
-
-=item Unicode::Collate::CJK::GB2312
-
-Weighting CJK Unified Ideographs
-
-=item Unicode::Collate::CJK::JISX0208
-
-Weighting JIS KANJI for Unicode::Collate
-
-=item Unicode::Collate::CJK::Korean
-
-Weighting CJK Unified Ideographs
-
-=item Unicode::Collate::CJK::Pinyin
-
-Weighting CJK Unified Ideographs
-
-=item Unicode::Collate::CJK::Stroke
-
-Weighting CJK Unified Ideographs
-
-=item Unicode::Collate::Locale
-
-Linguistic tailoring for DUCET via Unicode::Collate
-
-=item Unicode::Normalize
-
-Unicode Normalization Forms
-
-=item Unicode::UCD
-
-Unicode character database
-
-=item User::grent
-
-By-name interface to Perl's built-in getgr*() functions
-
-=item User::pwent
-
-By-name interface to Perl's built-in getpw*() functions
-
-=item VMS::DCLsym
-
-Perl extension to manipulate DCL symbols
-
-=item VMS::Stdio
-
-Standard I/O functions via VMS extensions
-
-=item Version::Requirements
-
-A set of version requirements for a CPAN dist
-
-=item Win32
-
-Interfaces to some Win32 API Functions
-
-=item Win32API::File
-
-Low-level access to Win32 system API calls for files/dirs.
-
-=item Win32CORE
-
-Win32 CORE function stubs
-
-=item XS::APItest
-
-Test the perl C API
-
-=item XS::Typemap
-
-Module to test the XS typemaps distributed with perl
-
-=item XSLoader
-
-Dynamically load C libraries into Perl code
-
-=item version::Internals
-
-Perl extension for Version Objects
-
-
-=back
-
-To find out I<all> modules installed on your system, including
-those without documentation or outside the standard release,
-just use the following command (under the default win32 shell,
-double quotes should be used instead of single quotes).
-
- % perl -MFile::Find=find -MFile::Spec::Functions -Tlwe \
- 'find { wanted => sub { print canonpath $_ if /\.pm\z/ },
- no_chdir => 1 }, @INC'
-
-(The -T is here to prevent '.' from being listed in @INC.)
-They should all have their own documentation installed and accessible
-via your system man(1) command. If you do not have a B<find>
-program, you can use the Perl B<find2perl> program instead, which
-generates Perl code as output you can run through perl. If you
-have a B<man> program but it doesn't find your modules, you'll have
-to fix your manpath. See L<perl> for details. If you have no
-system B<man> command, you might try the B<perldoc> program.
-
-Note also that the command C<perldoc perllocal> gives you a (possibly
-incomplete) list of the modules that have been further installed on
-your system. (The perllocal.pod file is updated by the standard MakeMaker
-install process.)
-
-=head2 Extension Modules
-
-Extension modules are written in C (or a mix of Perl and C). They
-are usually dynamically loaded into Perl if and when you need them,
-but may also be linked in statically. Supported extension modules
-include Socket, Fcntl, and POSIX.
-
-Many popular C extension modules do not come bundled (at least, not
-completely) due to their sizes, volatility, or simply lack of time
-for adequate testing and configuration across the multitude of
-platforms on which Perl was beta-tested. You are encouraged to
-look for them on CPAN (described below), or using web search engines
-like Alta Vista or Google.
-
-=head1 CPAN
-
-CPAN stands for Comprehensive Perl Archive Network; it's a globally
-replicated trove of Perl materials, including documentation, style
-guides, tricks and traps, alternate ports to non-Unix systems and
-occasional binary distributions for these. Search engines for
-CPAN can be found at http://www.cpan.org/
-
-Most importantly, CPAN includes around a thousand unbundled modules,
-some of which require a C compiler to build. Major categories of
-modules are:
-
-=over
-
-=item *
-
-Language Extensions and Documentation Tools
-
-=item *
-
-Development Support
-
-=item *
-
-Operating System Interfaces
-
-=item *
-
-Networking, Device Control (modems) and InterProcess Communication
-
-=item *
-
-Data Types and Data Type Utilities
-
-=item *
-
-Database Interfaces
-
-=item *
-
-User Interfaces
-
-=item *
-
-Interfaces to / Emulations of Other Programming Languages
-
-=item *
-
-File Names, File Systems and File Locking (see also File Handles)
-
-=item *
-
-String Processing, Language Text Processing, Parsing, and Searching
-
-=item *
-
-Option, Argument, Parameter, and Configuration File Processing
-
-=item *
-
-Internationalization and Locale
-
-=item *
-
-Authentication, Security, and Encryption
-
-=item *
-
-World Wide Web, HTML, HTTP, CGI, MIME
-
-=item *
-
-Server and Daemon Utilities
-
-=item *
-
-Archiving and Compression
-
-=item *
-
-Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
-
-=item *
-
-Mail and Usenet News
-
-=item *
-
-Control Flow Utilities (callbacks and exceptions etc)
-
-=item *
-
-File Handle and Input/Output Stream Utilities
-
-=item *
-
-Miscellaneous Modules
-
-=back
-
-The list of the registered CPAN sites follows.
-Please note that the sorting order is alphabetical on fields:
-
-Continent
- |
- |-->Country
- |
- |-->[state/province]
- |
- |-->ftp
- |
- |-->[http]
-
-and thus the North American servers happen to be listed between the
-European and the South American sites.
-
-Registered CPAN sites
-
-=for maintainers
-Generated by Porting/make_modlib_cpan.pl
-
-=head2 Africa
-
-=over 4
-
-=item South Africa
-
- http://cpan.mirror.ac.za/
- ftp://cpan.mirror.ac.za/
- http://mirror.is.co.za/pub/cpan/
- ftp://ftp.is.co.za/pub/cpan/
- ftp://ftp.saix.net/pub/CPAN/
-
-=back
-
-=head2 Asia
-
-=over 4
-
-=item China
-
- http://cpan.wenzk.com/
-
-=item Hong Kong
-
- http://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/
- ftp://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/
- http://mirrors.geoexpat.com/cpan/
-
-=item India
-
- http://perlmirror.indialinks.com/
-
-=item Indonesia
-
- http://cpan.biz.net.id/
- http://komo.vlsm.org/CPAN/
- ftp://komo.vlsm.org/CPAN/
- http://cpan.cermin.lipi.go.id/
- ftp://cermin.lipi.go.id/pub/CPAN/
- http://cpan.pesat.net.id/
-
-=item Japan
-
- ftp://ftp.u-aizu.ac.jp/pub/CPAN
- ftp://ftp.kddilabs.jp/CPAN/
- http://ftp.nara.wide.ad.jp/pub/CPAN/
- ftp://ftp.nara.wide.ad.jp/pub/CPAN/
- http://ftp.jaist.ac.jp/pub/CPAN/
- ftp://ftp.jaist.ac.jp/pub/CPAN/
- ftp://ftp.dti.ad.jp/pub/lang/CPAN/
- ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
- http://ftp.riken.jp/lang/CPAN/
- ftp://ftp.riken.jp/lang/CPAN/
- http://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/
- ftp://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/
-
-=item Republic of Korea
-
- http://ftp.kaist.ac.kr/pub/CPAN
- ftp://ftp.kaist.ac.kr/pub/CPAN
- http://cpan.mirror.cdnetworks.com/
- ftp://cpan.mirror.cdnetworks.com/CPAN/
- http://cpan.sarang.net/
- ftp://cpan.sarang.net/CPAN/
-
-=item Russia
-
- http://cpan.tomsk.ru/
- ftp://cpan.tomsk.ru/
-
-=item Singapore
-
- http://mirror.averse.net/pub/CPAN
- ftp://mirror.averse.net/pub/CPAN
- http://cpan.mirror.choon.net/
- http://cpan.oss.eznetsols.org
- ftp://ftp.oss.eznetsols.org/cpan
-
-=item Taiwan
-
- http://ftp.cse.yzu.edu.tw/pub/CPAN/
- ftp://ftp.cse.yzu.edu.tw/pub/CPAN/
- http://cpan.nctu.edu.tw/
- ftp://cpan.nctu.edu.tw/
- ftp://ftp.ncu.edu.tw/CPAN/
- http://cpan.cdpa.nsysu.edu.tw/
- ftp://cpan.cdpa.nsysu.edu.tw/Unix/Lang/CPAN/
- http://cpan.stu.edu.tw
- ftp://ftp.stu.edu.tw/CPAN
- http://ftp.stu.edu.tw/CPAN
- ftp://ftp.stu.edu.tw/pub/CPAN
- http://cpan.cs.pu.edu.tw/
- ftp://cpan.cs.pu.edu.tw/pub/CPAN
-
-=item Thailand
-
- http://mirrors.issp.co.th/cpan/
- ftp://mirrors.issp.co.th/cpan/
- http://mirror.yourconnect.com/CPAN/
- ftp://mirror.yourconnect.com/CPAN/
-
-=item Turkey
-
- http://cpan.gazi.edu.tr/
-
-=back
-
-=head2 Central America
-
-=over 4
-
-=item Costa Rica
-
- http://mirrors.ucr.ac.cr/CPAN/
- ftp://mirrors.ucr.ac.cr/CPAN/
-
-=back
-
-=head2 Europe
-
-=over 4
-
-=item Austria
-
- http://cpan.inode.at/
- ftp://cpan.inode.at
- http://gd.tuwien.ac.at/languages/perl/CPAN/
- ftp://gd.tuwien.ac.at/pub/CPAN/
-
-=item Belgium
-
- http://ftp.belnet.be/mirror/ftp.cpan.org/
- ftp://ftp.belnet.be/mirror/ftp.cpan.org/
- http://ftp.easynet.be/pub/CPAN/
- http://cpan.weepee.org/
-
-=item Bosnia and Herzegovina
-
- http://cpan.blic.net/
-
-=item Bulgaria
-
- http://cpan.cbox.biz/
- ftp://cpan.cbox.biz/cpan/
- http://cpan.digsys.bg/
- ftp://ftp.digsys.bg/pub/CPAN
-
-=item Croatia
-
- http://ftp.carnet.hr/pub/CPAN/
- ftp://ftp.carnet.hr/pub/CPAN/
-
-=item Czech Republic
-
- ftp://ftp.fi.muni.cz/pub/CPAN/
- http://archive.cpan.cz/
-
-=item Denmark
-
- http://mirrors.dotsrc.org/cpan
- ftp://mirrors.dotsrc.org/cpan/
- http://www.cpan.dk/
- http://mirror.uni-c.dk/pub/CPAN/
-
-=item Finland
-
- ftp://ftp.funet.fi/pub/languages/perl/CPAN/
- http://mirror.eunet.fi/CPAN
-
-=item France
-
- http://cpan.enstimac.fr/
- ftp://ftp.inria.fr/pub/CPAN/
- http://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
- ftp://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
- ftp://ftp.lip6.fr/pub/perl/CPAN/
- http://mir2.ovh.net/ftp.cpan.org
- ftp://mir1.ovh.net/ftp.cpan.org
- ftp://ftp.oleane.net/pub/CPAN/
- http://ftp.crihan.fr/mirrors/ftp.cpan.org/
- ftp://ftp.crihan.fr/mirrors/ftp.cpan.org/
- http://ftp.u-strasbg.fr/CPAN
- ftp://ftp.u-strasbg.fr/CPAN
- http://cpan.cict.fr/
- ftp://cpan.cict.fr/pub/CPAN/
-
-=item Germany
-
- ftp://ftp.fu-berlin.de/unix/languages/perl/
- http://mirrors.softliste.de/cpan/
- ftp://ftp.rub.de/pub/CPAN/
- http://www.planet-elektronik.de/CPAN/
- http://ftp.hosteurope.de/pub/CPAN/
- ftp://ftp.hosteurope.de/pub/CPAN/
- http://www.mirrorspace.org/cpan/
- http://mirror.netcologne.de/cpan/
- ftp://mirror.netcologne.de/cpan/
- ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
- http://ftp-stud.hs-esslingen.de/pub/Mirrors/CPAN/
- ftp://ftp-stud.hs-esslingen.de/pub/Mirrors/CPAN/
- http://mirrors.zerg.biz/cpan/
- http://ftp.gwdg.de/pub/languages/perl/CPAN/
- ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
- http://dl.ambiweb.de/mirrors/ftp.cpan.org/
- http://cpan.mirror.clusters.kg/
- http://cpan.mirror.iphh.net/
- ftp://cpan.mirror.iphh.net/pub/CPAN/
- http://cpan.mirroring.de/
- http://mirror.informatik.uni-mannheim.de/pub/mirrors/CPAN/
- ftp://mirror.informatik.uni-mannheim.de/pub/mirrors/CPAN/
- http://www.chemmedia.de/mirrors/CPAN/
- http://ftp.cw.net/pub/CPAN/
- ftp://ftp.cw.net/pub/CPAN/
- http://cpan.cpantesters.org/
- ftp://cpan.cpantesters.org/CPAN/
- http://cpan.mirrored.de/
- ftp://mirror.petamem.com/CPAN/
- http://cpan.noris.de/
- ftp://cpan.noris.de/pub/CPAN/
- ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
- ftp://ftp.gmd.de/mirrors/CPAN/
-
-=item Greece
-
- ftp://ftp.forthnet.gr/pub/languages/perl/CPAN
- ftp://ftp.ntua.gr/pub/lang/perl/
- http://cpan.cc.uoc.gr/
- ftp://ftp.cc.uoc.gr/mirrors/CPAN/
-
-=item Hungary
-
- http://cpan.mirrors.enexis.hu/
- ftp://cpan.mirrors.enexis.hu/mirrors/cpan/
- http://cpan.hu/
-
-=item Iceland
-
- http://ftp.rhnet.is/pub/CPAN/
- ftp://ftp.rhnet.is/pub/CPAN/
-
-=item Ireland
-
- http://ftp.esat.net/pub/languages/perl/CPAN/
- ftp://ftp.esat.net/pub/languages/perl/CPAN/
- http://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
- ftp://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
-
-=item Italy
-
- http://bo.mirror.garr.it/mirrors/CPAN/
- http://cpan.panu.it/
- ftp://ftp.panu.it/pub/mirrors/perl/CPAN/
-
-=item Latvia
-
- http://kvin.lv/pub/CPAN/
-
-=item Lithuania
-
- http://ftp.litnet.lt/pub/CPAN/
- ftp://ftp.litnet.lt/pub/CPAN/
-
-=item Malta
-
- http://cpan.waldonet.net.mt/
-
-=item Netherlands
-
- ftp://ftp.quicknet.nl/pub/CPAN/
- http://mirror.hostfuss.com/CPAN/
- ftp://mirror.hostfuss.com/CPAN/
- http://mirrors3.kernel.org/cpan/
- ftp://mirrors3.kernel.org/pub/CPAN/
- http://cpan.mirror.versatel.nl/
- ftp://ftp.mirror.versatel.nl/cpan/
- ftp://download.xs4all.nl/pub/mirror/CPAN/
- http://mirror.leaseweb.com/CPAN/
- ftp://mirror.leaseweb.com/CPAN/
- ftp://ftp.cpan.nl/pub/CPAN/
- http://archive.cs.uu.nl/mirror/CPAN/
- ftp://ftp.cs.uu.nl/mirror/CPAN/
- http://luxitude.net/cpan/
-
-=item Norway
-
- ftp://ftp.uninett.no/pub/languages/perl/CPAN
- ftp://ftp.uit.no/pub/languages/perl/cpan/
-
-=item Poland
-
- http://piotrkosoft.net/pub/mirrors/CPAN/
- ftp://ftp.piotrkosoft.net/pub/mirrors/CPAN/
- http://ftp.man.poznan.pl/pub/CPAN
- ftp://ftp.man.poznan.pl/pub/CPAN
- ftp://ftp.ps.pl/pub/CPAN/
- ftp://sunsite.icm.edu.pl/pub/CPAN/
- ftp://ftp.tpnet.pl/d4/CPAN/
-
-=item Portugal
-
- http://cpan.dei.uc.pt/
- ftp://ftp.dei.uc.pt/pub/CPAN
- ftp://ftp.ist.utl.pt/pub/CPAN/
- http://cpan.perl.pt/
- http://cpan.ip.pt/
- ftp://cpan.ip.pt/pub/cpan/
- http://mirrors.nfsi.pt/CPAN/
- ftp://mirrors.nfsi.pt/pub/CPAN/
- http://cpan.dcc.fc.up.pt/
-
-=item Romania
-
- http://ftp.astral.ro/pub/CPAN/
- ftp://ftp.astral.ro/pub/CPAN/
- ftp://ftp.lug.ro/CPAN
- http://mirrors.xservers.ro/CPAN/
- http://mirrors.hostingromania.ro/ftp.cpan.org/
- ftp://ftp.hostingromania.ro/mirrors/ftp.cpan.org/
- ftp://ftp.iasi.roedu.net/pub/mirrors/ftp.cpan.org/
-
-=item Russia
-
- ftp://ftp.aha.ru/CPAN/
- http://cpan.rinet.ru/
- ftp://cpan.rinet.ru/pub/mirror/CPAN/
- ftp://ftp.SpringDaemons.com/pub/CPAN/
- http://mirror.rol.ru/CPAN/
- http://ftp.silvernet.ru/CPAN/
- http://ftp.spbu.ru/CPAN/
- ftp://ftp.spbu.ru/CPAN/
-
-=item Slovakia
-
- http://cpan.fyxm.net/
-
-=item Slovenia
-
- http://www.klevze.si/cpan
-
-=item Spain
-
- http://osl.ugr.es/CPAN/
- ftp://ftp.rediris.es/mirror/CPAN/
- http://ftp.gui.uva.es/sites/cpan.org/
- ftp://ftp.gui.uva.es/sites/cpan.org/
-
-=item Sweden
-
- http://mirrors4.kernel.org/cpan/
- ftp://mirrors4.kernel.org/pub/CPAN/
-
-=item Switzerland
-
- http://cpan.mirror.solnet.ch/
- ftp://ftp.solnet.ch/mirror/CPAN/
- ftp://ftp.adwired.ch/CPAN/
- http://mirror.switch.ch/ftp/mirror/CPAN/
- ftp://mirror.switch.ch/mirror/CPAN/
-
-=item Ukraine
-
- http://cpan.makeperl.org/
- ftp://cpan.makeperl.org/pub/CPAN
- http://cpan.org.ua/
- http://cpan.gafol.net/
- ftp://ftp.gafol.net/pub/cpan/
-
-=item United Kingdom
-
- http://www.mirrorservice.org/sites/ftp.funet.fi/pub/languages/perl/CPAN/
- ftp://ftp.mirrorservice.org/sites/ftp.funet.fi/pub/languages/perl/CPAN/
- http://mirror.tje.me.uk/pub/mirrors/ftp.cpan.org/
- ftp://mirror.tje.me.uk/pub/mirrors/ftp.cpan.org/
- http://www.mirror.8086.net/sites/CPAN/
- ftp://ftp.mirror.8086.net/sites/CPAN/
- http://cpan.mirror.anlx.net/
- ftp://ftp.mirror.anlx.net/CPAN/
- http://mirror.bytemark.co.uk/CPAN/
- ftp://mirror.bytemark.co.uk/CPAN/
- http://cpan.etla.org/
- ftp://cpan.etla.org/pub/CPAN
- ftp://ftp.demon.co.uk/pub/CPAN/
- http://mirror.sov.uk.goscomb.net/CPAN/
- ftp://mirror.sov.uk.goscomb.net/pub/CPAN/
- http://ftp.plig.net/pub/CPAN/
- ftp://ftp.plig.net/pub/CPAN/
- http://ftp.ticklers.org/pub/CPAN/
- ftp://ftp.ticklers.org/pub/CPAN/
- http://cpan.mirrors.uk2.net/
- ftp://mirrors.uk2.net/pub/CPAN/
- http://mirror.ox.ac.uk/sites/www.cpan.org/
- ftp://mirror.ox.ac.uk/sites/www.cpan.org/
-
-=back
-
-=head2 North America
-
-=over 4
-
-=item Bahamas
-
- http://www.securehost.com/mirror/CPAN/
-
-=item Canada
-
- http://cpan.arcticnetwork.ca
- ftp://mirror.arcticnetwork.ca/pub/CPAN
- http://cpan.sunsite.ualberta.ca/
- ftp://cpan.sunsite.ualberta.ca/pub/CPAN/
- http://theoryx5.uwinnipeg.ca/pub/CPAN/
- ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
- http://arwen.cs.dal.ca/mirror/CPAN/
- ftp://arwen.cs.dal.ca/pub/mirror/CPAN/
- http://CPAN.mirror.rafal.ca/
- ftp://CPAN.mirror.rafal.ca/pub/CPAN/
- ftp://ftp.nrc.ca/pub/CPAN/
- http://mirror.csclub.uwaterloo.ca/pub/CPAN/
- ftp://mirror.csclub.uwaterloo.ca/pub/CPAN/
-
-=item Mexico
-
- http://www.msg.com.mx/CPAN/
- ftp://ftp.msg.com.mx/pub/CPAN/
-
-=item United States
-
-=over 8
-
-=item Alabama
-
- http://mirror.hiwaay.net/CPAN/
- ftp://mirror.hiwaay.net/CPAN/
-
-=item Arizona
-
- http://cpan.ezarticleinformation.com/
-
-=item California
-
- http://cpan.knowledgematters.net/
- http://cpan.binkerton.com/
- http://cpan.develooper.com/
- http://mirrors.gossamer-threads.com/CPAN
- http://cpan.schatt.com/
- http://mirrors.kernel.org/cpan/
- ftp://mirrors.kernel.org/pub/CPAN
- http://mirrors2.kernel.org/cpan/
- ftp://mirrors2.kernel.org/pub/CPAN/
- http://cpan.mirror.facebook.net/
- http://mirrors1.kernel.org/cpan/
- ftp://mirrors1.kernel.org/pub/CPAN/
- http://cpan-sj.viaverio.com/
- ftp://cpan-sj.viaverio.com/pub/CPAN/
- http://www.perl.com/CPAN/
-
-=item Florida
-
- ftp://ftp.cise.ufl.edu/pub/mirrors/CPAN/
- http://mirror.atlantic.net/pub/CPAN/
- ftp://mirror.atlantic.net/pub/CPAN/
-
-=item Idaho
-
- http://mirror.its.uidaho.edu/pub/cpan/
- ftp://mirror.its.uidaho.edu/cpan/
-
-=item Illinois
-
- http://cpan.mirrors.hoobly.com/
- http://cpan.uchicago.edu/pub/CPAN/
- ftp://cpan.uchicago.edu/pub/CPAN/
- http://mirrors.servercentral.net/CPAN/
- http://www.stathy.com/CPAN/
- ftp://www.stathy.com/CPAN/
-
-=item Indiana
-
- ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/
- http://cpan.netnitco.net/
- ftp://cpan.netnitco.net/pub/mirrors/CPAN/
- http://ftp.ndlug.nd.edu/pub/perl/
- ftp://ftp.ndlug.nd.edu/pub/perl/
-
-=item Massachusetts
-
- http://mirrors.ccs.neu.edu/CPAN/
-
-=item Michigan
-
- http://ftp.wayne.edu/cpan/
- ftp://ftp.wayne.edu/cpan/
-
-=item Minnesota
-
- http://cpan.msi.umn.edu/
-
-=item New Jersey
-
- http://mirror.datapipe.net/CPAN/
- ftp://mirror.datapipe.net/pub/CPAN/
-
-=item New York
-
- http://mirrors.24-7-solutions.net/pub/CPAN/
- ftp://mirrors.24-7-solutions.net/pub/CPAN/
- http://mirror.cc.columbia.edu/pub/software/cpan/
- ftp://mirror.cc.columbia.edu/pub/software/cpan/
- http://cpan.belfry.net/
- http://cpan.erlbaum.net/
- ftp://cpan.erlbaum.net/CPAN/
- http://cpan.hexten.net/
- ftp://cpan.hexten.net/
- ftp://mirror.nyi.net/CPAN/
- http://mirror.rit.edu/CPAN/
- ftp://mirror.rit.edu/CPAN/
-
-=item North Carolina
-
- http://www.ibiblio.org/pub/mirrors/CPAN
- ftp://ftp.ncsu.edu/pub/mirror/CPAN/
-
-=item Oregon
-
- http://ftp.osuosl.org/pub/CPAN/
- ftp://ftp.osuosl.org/pub/CPAN/
-
-=item Pennsylvania
-
- http://ftp.epix.net/CPAN/
- ftp://ftp.epix.net/pub/languages/perl/
- http://cpan.pair.com/
- ftp://cpan.pair.com/pub/CPAN/
-
-=item South Carolina
-
- http://cpan.mirror.clemson.edu/
-
-=item Tennessee
-
- http://mira.sunsite.utk.edu/CPAN/
-
-=item Texas
-
- http://mirror.uta.edu/CPAN
-
-=item Utah
-
- ftp://mirror.xmission.com/CPAN/
-
-=item Virginia
-
- http://cpan-du.viaverio.com/
- ftp://cpan-du.viaverio.com/pub/CPAN/
- http://perl.secsup.org/
- ftp://perl.secsup.org/pub/perl/
- ftp://mirror.cogentco.com/pub/CPAN/
-
-=item Washington
-
- http://cpan.llarian.net/
- ftp://cpan.llarian.net/pub/CPAN/
- ftp://ftp-mirror.internap.com/pub/CPAN/
-
-=item Wisconsin
-
- http://cpan.mirrors.tds.net
- ftp://cpan.mirrors.tds.net/pub/CPAN
- http://mirror.sit.wisc.edu/pub/CPAN/
- ftp://mirror.sit.wisc.edu/pub/CPAN/
-
-=back
-
-=back
-
-=head2 Oceania
-
-=over 4
-
-=item Australia
-
- http://mirror.internode.on.net/pub/cpan/
- ftp://mirror.internode.on.net/pub/cpan/
- http://cpan.mirror.aussiehq.net.au/
- http://mirror.as24220.net/cpan/
- ftp://mirror.as24220.net/cpan/
-
-=item New Zealand
-
- ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
- http://cpan.inspire.net.nz
- ftp://cpan.inspire.net.nz/cpan
- http://cpan.catalyst.net.nz/CPAN/
- ftp://cpan.catalyst.net.nz/pub/CPAN/
-
-=back
-
-=head2 South America
-
-=over 4
-
-=item Argentina
-
- http://cpan.patan.com.ar/
- http://cpan.localhost.net.ar
- ftp://mirrors.localhost.net.ar/pub/mirrors/CPAN
-
-=item Brazil
-
- ftp://cpan.pop-mg.com.br/pub/CPAN/
- http://ftp.pucpr.br/CPAN
- ftp://ftp.pucpr.br/CPAN
- http://cpan.kinghost.net/
-
-=item Chile
-
- http://cpan.dcc.uchile.cl/
- ftp://cpan.dcc.uchile.cl/pub/lang/cpan/
-
-=item Colombia
-
- http://www.laqee.unal.edu.co/CPAN/
-
-=back
-
-=head2 RSYNC Mirrors
-
- mirror.as24220.net::cpan
- cpan.inode.at::CPAN
- gd.tuwien.ac.at::CPAN
- ftp.belnet.be::packages/cpan
- rsync.linorg.usp.br::CPAN
- rsync.arcticnetwork.ca::CPAN
- CPAN.mirror.rafal.ca::CPAN
- mirror.csclub.uwaterloo.ca::CPAN
- theoryx5.uwinnipeg.ca::CPAN
- www.laqee.unal.edu.co::CPAN
- mirror.uni-c.dk::CPAN
- rsync.nic.funet.fi::CPAN
- rsync://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
- mir1.ovh.net::CPAN
- miroir-francais.fr::cpan
- ftp.crihan.fr::CPAN
- rsync://mirror.cict.fr/cpan/
- rsync://mirror.netcologne.de/cpan/
- ftp-stud.hs-esslingen.de::CPAN/
- ftp.gwdg.de::FTP/languages/perl/CPAN/
- cpan.mirror.iphh.net::CPAN
- cpan.cpantesters.org::cpan
- cpan.hu::CPAN
- komo.vlsm.org::CPAN
- mirror.unej.ac.id::cpan
- ftp.esat.net::/pub/languages/perl/CPAN
- ftp.heanet.ie::mirrors/ftp.perl.org/pub/CPAN
- rsync.panu.it::CPAN
- cpan.fastbull.org::CPAN
- ftp.kddilabs.jp::cpan
- ftp.nara.wide.ad.jp::cpan/
- rsync://ftp.jaist.ac.jp/pub/CPAN/
- rsync://ftp.riken.jp/cpan/
- mirror.linuxiso.kz::CPAN
- rsync://mirrors3.kernel.org/mirrors/CPAN/
- rsync://rsync.osmirror.nl/cpan/
- mirror.leaseweb.com::CPAN
- cpan.nautile.nc::CPAN
- mirror.icis.pcz.pl::CPAN
- piotrkosoft.net::mirrors/CPAN
- rsync://cpan.perl.pt/
- ftp.kaist.ac.kr::cpan
- cpan.sarang.net::CPAN
- mirror.averse.net::cpan
- rsync.oss.eznetsols.org
- mirror.ac.za::cpan
- ftp.is.co.za::IS-Mirror/ftp.cpan.org/
- rsync://ftp.gui.uva.es/cpan/
- rsync://mirrors4.kernel.org/mirrors/CPAN/
- ftp.solnet.ch::CPAN
- ftp.ulak.net.tr::CPAN
- gafol.net::cpan
- rsync.mirrorservice.org::ftp.funet.fi/pub/
- rsync://rsync.mirror.8086.net/CPAN/
- rsync.mirror.anlx.net::CPAN
- mirror.bytemark.co.uk::CPAN
- ftp.plig.net::CPAN
- rsync://ftp.ticklers.org:CPAN/
- mirrors.ibiblio.org::CPAN
- cpan-du.viaverio.com::CPAN
- mirror.hiwaay.net::CPAN
- rsync://mira.sunsite.utk.edu/CPAN/
- cpan.mirrors.tds.net::CPAN
- mirror.its.uidaho.edu::cpan
- rsync://mirror.cc.columbia.edu::cpan/
- ftp.fxcorporate.com::CPAN
- rsync.atlantic.net::CPAN
- mirrors.kernel.org::mirrors/CPAN
- rsync://mirrors2.kernel.org/mirrors/CPAN/
- cpan.pair.com::CPAN
- rsync://mirror.rit.edu/CPAN/
- rsync://mirror.facebook.net/cpan/
- rsync://mirrors1.kernel.org/mirrors/CPAN/
- cpan-sj.viaverio.com::CPAN
-
-For an up-to-date listing of CPAN sites,
-see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES .
-
-=head1 Modules: Creation, Use, and Abuse
-
-(The following section is borrowed directly from Tim Bunce's modules
-file, available at your nearest CPAN site.)
-
-Perl implements a class using a package, but the presence of a
-package doesn't imply the presence of a class. A package is just a
-namespace. A class is a package that provides subroutines that can be
-used as methods. A method is just a subroutine that expects, as its
-first argument, either the name of a package (for "static" methods),
-or a reference to something (for "virtual" methods).
-
-A module is a file that (by convention) provides a class of the same
-name (sans the .pm), plus an import method in that class that can be
-called to fetch exported symbols. This module may implement some of
-its methods by loading dynamic C or C++ objects, but that should be
-totally transparent to the user of the module. Likewise, the module
-might set up an AUTOLOAD function to slurp in subroutine definitions on
-demand, but this is also transparent. Only the F<.pm> file is required to
-exist. See L<perlsub>, L<perlobj>, and L<AutoLoader> for details about
-the AUTOLOAD mechanism.
-
-=head2 Guidelines for Module Creation
-
-=over 4
-
-=item *
-
-Do similar modules already exist in some form?
-
-If so, please try to reuse the existing modules either in whole or
-by inheriting useful features into a new class. If this is not
-practical try to get together with the module authors to work on
-extending or enhancing the functionality of the existing modules.
-A perfect example is the plethora of packages in perl4 for dealing
-with command line options.
-
-If you are writing a module to expand an already existing set of
-modules, please coordinate with the author of the package. It
-helps if you follow the same naming scheme and module interaction
-scheme as the original author.
-
-=item *
-
-Try to design the new module to be easy to extend and reuse.
-
-Try to C<use warnings;> (or C<use warnings qw(...);>).
-Remember that you can add C<no warnings qw(...);> to individual blocks
-of code that need less warnings.
-
-Use blessed references. Use the two argument form of bless to bless
-into the class name given as the first parameter of the constructor,
-e.g.,:
-
- sub new {
- my $class = shift;
- return bless {}, $class;
- }
-
-or even this if you'd like it to be used as either a static
-or a virtual method.
-
- sub new {
- my $self = shift;
- my $class = ref($self) || $self;
- return bless {}, $class;
- }
-
-Pass arrays as references so more parameters can be added later
-(it's also faster). Convert functions into methods where
-appropriate. Split large methods into smaller more flexible ones.
-Inherit methods from other modules if appropriate.
-
-Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
-Generally you can delete the C<eq 'FOO'> part with no harm at all.
-Let the objects look after themselves! Generally, avoid hard-wired
-class names as far as possible.
-
-Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
-C<< $r->func() >> would work.
-
-Use autosplit so little used or newly added functions won't be a
-burden to programs that don't use them. Add test functions to
-the module after __END__ either using AutoSplit or by saying:
-
- eval join('',<main::DATA>) || die $@ unless caller();
-
-Does your module pass the 'empty subclass' test? If you say
-C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
-to use SUBCLASS in exactly the same way as YOURCLASS. For example,
-does your application still work if you change: C<< $obj = YOURCLASS->new(); >>
-into: C<< $obj = SUBCLASS->new(); >> ?
-
-Avoid keeping any state information in your packages. It makes it
-difficult for multiple other packages to use yours. Keep state
-information in objects.
-
-Always use B<-w>.
-
-Try to C<use strict;> (or C<use strict qw(...);>).
-Remember that you can add C<no strict qw(...);> to individual blocks
-of code that need less strictness.
-
-Always use B<-w>.
-
-Follow the guidelines in L<perlstyle>.
-
-Always use B<-w>.
-
-=item *
-
-Some simple style guidelines
-
-The perlstyle manual supplied with Perl has many helpful points.
-
-Coding style is a matter of personal taste. Many people evolve their
-style over several years as they learn what helps them write and
-maintain good code. Here's one set of assorted suggestions that
-seem to be widely used by experienced developers:
-
-Use underscores to separate words. It is generally easier to read
-$var_names_like_this than $VarNamesLikeThis, especially for
-non-native speakers of English. It's also a simple rule that works
-consistently with VAR_NAMES_LIKE_THIS.
-
-Package/Module names are an exception to this rule. Perl informally
-reserves lowercase module names for 'pragma' modules like integer
-and strict. Other modules normally begin with a capital letter and
-use mixed case with no underscores (need to be short and portable).
-
-You may find it helpful to use letter case to indicate the scope
-or nature of a variable. For example:
-
- $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
- $Some_Caps_Here package-wide global/static
- $no_caps_here function scope my() or local() variables
-
-Function and method names seem to work best as all lowercase.
-e.g., C<< $obj->as_string() >>.
-
-You can use a leading underscore to indicate that a variable or
-function should not be used outside the package that defined it.
-
-=item *
-
-Select what to export.
-
-Do NOT export method names!
-
-Do NOT export anything else by default without a good reason!
-
-Exports pollute the namespace of the module user. If you must
-export try to use @EXPORT_OK in preference to @EXPORT and avoid
-short or common names to reduce the risk of name clashes.
-
-Generally anything not exported is still accessible from outside the
-module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
-syntax. By convention you can use a leading underscore on names to
-indicate informally that they are 'internal' and not for public use.
-
-(It is actually possible to get private functions by saying:
-C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
-directly as a method, because a method must have a name in the symbol
-table.)
-
-As a general rule, if the module is trying to be object oriented
-then export nothing. If it's just a collection of functions then
-@EXPORT_OK anything but use @EXPORT with caution.
-
-=item *
-
-Select a name for the module.
-
-This name should be as descriptive, accurate, and complete as
-possible. Avoid any risk of ambiguity. Always try to use two or
-more whole words. Generally the name should reflect what is special
-about what the module does rather than how it does it. Please use
-nested module names to group informally or categorize a module.
-There should be a very good reason for a module not to have a nested name.
-Module names should begin with a capital letter.
-
-Having 57 modules all called Sort will not make life easy for anyone
-(though having 23 called Sort::Quick is only marginally better :-).
-Imagine someone trying to install your module alongside many others.
-If in any doubt ask for suggestions in comp.lang.perl.misc.
-
-If you are developing a suite of related modules/classes it's good
-practice to use nested classes with a common prefix as this will
-avoid namespace clashes. For example: Xyz::Control, Xyz::View,
-Xyz::Model etc. Use the modules in this list as a naming guide.
-
-If adding a new module to a set, follow the original author's
-standards for naming modules and the interface to methods in
-those modules.
-
-If developing modules for private internal or project specific use,
-that will never be released to the public, then you should ensure
-that their names will not clash with any future public module. You
-can do this either by using the reserved Local::* category or by
-using a category name that includes an underscore like Foo_Corp::*.
-
-To be portable each component of a module name should be limited to
-11 characters. If it might be used on MS-DOS then try to ensure each is
-unique in the first 8 characters. Nested modules make this easier.
-
-=item *
-
-Have you got it right?
-
-How do you know that you've made the right decisions? Have you
-picked an interface design that will cause problems later? Have
-you picked the most appropriate name? Do you have any questions?
-
-The best way to know for sure, and pick up many helpful suggestions,
-is to ask someone who knows. Comp.lang.perl.misc is read by just about
-all the people who develop modules and it's the best place to ask.
-
-All you need to do is post a short summary of the module, its
-purpose and interfaces. A few lines on each of the main methods is
-probably enough. (If you post the whole module it might be ignored
-by busy people - generally the very people you want to read it!)
-
-Don't worry about posting if you can't say when the module will be
-ready - just say so in the message. It might be worth inviting
-others to help you, they may be able to complete it for you!
-
-=item *
-
-README and other Additional Files.
-
-It's well known that software developers usually fully document the
-software they write. If, however, the world is in urgent need of
-your software and there is not enough time to write the full
-documentation please at least provide a README file containing:
-
-=over 10
-
-=item *
-
-A description of the module/package/extension etc.
-
-=item *
-
-A copyright notice - see below.
-
-=item *
-
-Prerequisites - what else you may need to have.
-
-=item *
-
-How to build it - possible changes to Makefile.PL etc.
-
-=item *
-
-How to install it.
-
-=item *
-
-Recent changes in this release, especially incompatibilities
-
-=item *
-
-Changes / enhancements you plan to make in the future.
-
-=back
-
-If the README file seems to be getting too large you may wish to
-split out some of the sections into separate files: INSTALL,
-Copying, ToDo etc.
-
-=over 4
-
-=item *
-
-Adding a Copyright Notice.
-
-How you choose to license your work is a personal decision.
-The general mechanism is to assert your Copyright and then make
-a declaration of how others may copy/use/modify your work.
-
-Perl, for example, is supplied with two types of licence: The GNU GPL
-and The Artistic Licence (see the files README, Copying, and Artistic,
-or L<perlgpl> and L<perlartistic>). Larry has good reasons for NOT
-just using the GNU GPL.
-
-My personal recommendation, out of respect for Larry, Perl, and the
-Perl community at large is to state something simply like:
-
- Copyright (c) 1995 Your Name. All rights reserved.
- This program is free software; you can redistribute it and/or
- modify it under the same terms as Perl itself.
-
-This statement should at least appear in the README file. You may
-also wish to include it in a Copying file and your source files.
-Remember to include the other words in addition to the Copyright.
-
-=item *
-
-Give the module a version/issue/release number.
-
-To be fully compatible with the Exporter and MakeMaker modules you
-should store your module's version number in a non-my package
-variable called $VERSION. This should be a positive floating point
-number with at least two digits after the decimal (i.e., hundredths,
-e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
-See L<Exporter> for details.
-
-It may be handy to add a function or method to retrieve the number.
-Use the number in announcements and archive file names when
-releasing the module (ModuleName-1.02.tar.Z).
-See perldoc ExtUtils::MakeMaker.pm for details.
-
-=item *
-
-How to release and distribute a module.
-
-It's good idea to post an announcement of the availability of your
-module (or the module itself if small) to the comp.lang.perl.announce
-Usenet newsgroup. This will at least ensure very wide once-off
-distribution.
-
-If possible, register the module with CPAN. You should
-include details of its location in your announcement.
-
-Some notes about ftp archives: Please use a long descriptive file
-name that includes the version number. Most incoming directories
-will not be readable/listable, i.e., you won't be able to see your
-file after uploading it. Remember to send your email notification
-message as soon as possible after uploading else your file may get
-deleted automatically. Allow time for the file to be processed
-and/or check the file has been processed before announcing its
-location.
-
-FTP Archives for Perl Modules:
-
-Follow the instructions and links on:
-
- http://www.cpan.org/modules/00modlist.long.html
- http://www.cpan.org/modules/04pause.html
-
-or upload to one of these sites:
-
- https://pause.kbx.de/pause/
- http://pause.perl.org/
-
-and notify <modules@perl.org>.
-
-By using the WWW interface you can ask the Upload Server to mirror
-your modules from your ftp or WWW site into your own directory on
-CPAN!
-
-Please remember to send me an updated entry for the Module list!
-
-=item *
-
-Take care when changing a released module.
-
-Always strive to remain compatible with previous released versions.
-Otherwise try to add a mechanism to revert to the
-old behavior if people rely on it. Document incompatible changes.
-
-=back
-
-=back
-
-=head2 Guidelines for Converting Perl 4 Library Scripts into Modules
-
-=over 4
-
-=item *
-
-There is no requirement to convert anything.
-
-If it ain't broke, don't fix it! Perl 4 library scripts should
-continue to work with no problems. You may need to make some minor
-changes (like escaping non-array @'s in double quoted strings) but
-there is no need to convert a .pl file into a Module for just that.
-
-=item *
-
-Consider the implications.
-
-All Perl applications that make use of the script will need to
-be changed (slightly) if the script is converted into a module. Is
-it worth it unless you plan to make other changes at the same time?
-
-=item *
-
-Make the most of the opportunity.
-
-If you are going to convert the script to a module you can use the
-opportunity to redesign the interface. The guidelines for module
-creation above include many of the issues you should consider.
-
-=item *
-
-The pl2pm utility will get you started.
-
-This utility will read *.pl files (given as parameters) and write
-corresponding *.pm files. The pl2pm utilities does the following:
-
-=over 10
-
-=item *
-
-Adds the standard Module prologue lines
-
-=item *
-
-Converts package specifiers from ' to ::
-
-=item *
-
-Converts die(...) to croak(...)
-
-=item *
-
-Several other minor changes
-
-=back
-
-Being a mechanical process pl2pm is not bullet proof. The converted
-code will need careful checking, especially any package statements.
-Don't delete the original .pl file till the new .pm one works!
-
-=back
-
-=head2 Guidelines for Reusing Application Code
-
-=over 4
-
-=item *
-
-Complete applications rarely belong in the Perl Module Library.
-
-=item *
-
-Many applications contain some Perl code that could be reused.
-
-Help save the world! Share your code in a form that makes it easy
-to reuse.
-
-=item *
-
-Break-out the reusable code into one or more separate module files.
-
-=item *
-
-Take the opportunity to reconsider and redesign the interfaces.
-
-=item *
-
-In some cases the 'application' can then be reduced to a small
-
-fragment of code built on top of the reusable modules. In these cases
-the application could invoked as:
-
- % perl -e 'use Module::Name; method(@ARGV)' ...
-or
- % perl -mModule::Name ... (in perl5.002 or higher)
-
-=back
-
-=head1 NOTE
-
-Perl does not enforce private and public parts of its modules as you may
-have been used to in other languages like C++, Ada, or Modula-17. Perl
-doesn't have an infatuation with enforced privacy. It would prefer
-that you stayed out of its living room because you weren't invited, not
-because it has a shotgun.
-
-The module and its user have a contract, part of which is common law,
-and part of which is "written". Part of the common law contract is
-that a module doesn't pollute any namespace it wasn't asked to. The
-written contract for the module (A.K.A. documentation) may make other
-provisions. But then you know when you C<use RedefineTheWorld> that
-you're redefining the world and willing to take the consequences.
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlmodstyle.pod b/Master/tlpkg/tlperl/lib/pods/perlmodstyle.pod
deleted file mode 100644
index df813a0f3dd..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlmodstyle.pod
+++ /dev/null
@@ -1,783 +0,0 @@
-=head1 NAME
-
-perlmodstyle - Perl module style guide
-
-=head1 INTRODUCTION
-
-This document attempts to describe the Perl Community's "best practice"
-for writing Perl modules. It extends the recommendations found in
-L<perlstyle> , which should be considered required reading
-before reading this document.
-
-While this document is intended to be useful to all module authors, it is
-particularly aimed at authors who wish to publish their modules on CPAN.
-
-The focus is on elements of style which are visible to the users of a
-module, rather than those parts which are only seen by the module's
-developers. However, many of the guidelines presented in this document
-can be extrapolated and applied successfully to a module's internals.
-
-This document differs from L<perlnewmod> in that it is a style guide
-rather than a tutorial on creating CPAN modules. It provides a
-checklist against which modules can be compared to determine whether
-they conform to best practice, without necessarily describing in detail
-how to achieve this.
-
-All the advice contained in this document has been gleaned from
-extensive conversations with experienced CPAN authors and users. Every
-piece of advice given here is the result of previous mistakes. This
-information is here to help you avoid the same mistakes and the extra
-work that would inevitably be required to fix them.
-
-The first section of this document provides an itemized checklist;
-subsequent sections provide a more detailed discussion of the items on
-the list. The final section, "Common Pitfalls", describes some of the
-most popular mistakes made by CPAN authors.
-
-=head1 QUICK CHECKLIST
-
-For more detail on each item in this checklist, see below.
-
-=head2 Before you start
-
-=over 4
-
-=item *
-
-Don't re-invent the wheel
-
-=item *
-
-Patch, extend or subclass an existing module where possible
-
-=item *
-
-Do one thing and do it well
-
-=item *
-
-Choose an appropriate name
-
-=back
-
-=head2 The API
-
-=over 4
-
-=item *
-
-API should be understandable by the average programmer
-
-=item *
-
-Simple methods for simple tasks
-
-=item *
-
-Separate functionality from output
-
-=item *
-
-Consistent naming of subroutines or methods
-
-=item *
-
-Use named parameters (a hash or hashref) when there are more than two
-parameters
-
-=back
-
-=head2 Stability
-
-=over 4
-
-=item *
-
-Ensure your module works under C<use strict> and C<-w>
-
-=item *
-
-Stable modules should maintain backwards compatibility
-
-=back
-
-=head2 Documentation
-
-=over 4
-
-=item *
-
-Write documentation in POD
-
-=item *
-
-Document purpose, scope and target applications
-
-=item *
-
-Document each publically accessible method or subroutine, including params and return values
-
-=item *
-
-Give examples of use in your documentation
-
-=item *
-
-Provide a README file and perhaps also release notes, changelog, etc
-
-=item *
-
-Provide links to further information (URL, email)
-
-=back
-
-=head2 Release considerations
-
-=over 4
-
-=item *
-
-Specify pre-requisites in Makefile.PL or Build.PL
-
-=item *
-
-Specify Perl version requirements with C<use>
-
-=item *
-
-Include tests with your module
-
-=item *
-
-Choose a sensible and consistent version numbering scheme (X.YY is the common Perl module numbering scheme)
-
-=item *
-
-Increment the version number for every change, no matter how small
-
-=item *
-
-Package the module using "make dist"
-
-=item *
-
-Choose an appropriate license (GPL/Artistic is a good default)
-
-=back
-
-=head1 BEFORE YOU START WRITING A MODULE
-
-Try not to launch headlong into developing your module without spending
-some time thinking first. A little forethought may save you a vast
-amount of effort later on.
-
-=head2 Has it been done before?
-
-You may not even need to write the module. Check whether it's already
-been done in Perl, and avoid re-inventing the wheel unless you have a
-good reason.
-
-Good places to look for pre-existing modules include
-http://search.cpan.org/ and asking on modules@perl.org
-
-If an existing module B<almost> does what you want, consider writing a
-patch, writing a subclass, or otherwise extending the existing module
-rather than rewriting it.
-
-=head2 Do one thing and do it well
-
-At the risk of stating the obvious, modules are intended to be modular.
-A Perl developer should be able to use modules to put together the
-building blocks of their application. However, it's important that the
-blocks are the right shape, and that the developer shouldn't have to use
-a big block when all they need is a small one.
-
-Your module should have a clearly defined scope which is no longer than
-a single sentence. Can your module be broken down into a family of
-related modules?
-
-Bad example:
-
-"FooBar.pm provides an implementation of the FOO protocol and the
-related BAR standard."
-
-Good example:
-
-"Foo.pm provides an implementation of the FOO protocol. Bar.pm
-implements the related BAR protocol."
-
-This means that if a developer only needs a module for the BAR standard,
-they should not be forced to install libraries for FOO as well.
-
-=head2 What's in a name?
-
-Make sure you choose an appropriate name for your module early on. This
-will help people find and remember your module, and make programming
-with your module more intuitive.
-
-When naming your module, consider the following:
-
-=over 4
-
-=item *
-
-Be descriptive (i.e. accurately describes the purpose of the module).
-
-=item *
-
-Be consistent with existing modules.
-
-=item *
-
-Reflect the functionality of the module, not the implementation.
-
-=item *
-
-Avoid starting a new top-level hierarchy, especially if a suitable
-hierarchy already exists under which you could place your module.
-
-=back
-
-You should contact modules@perl.org to ask them about your module name
-before publishing your module. You should also try to ask people who
-are already familiar with the module's application domain and the CPAN
-naming system. Authors of similar modules, or modules with similar
-names, may be a good place to start.
-
-=head1 DESIGNING AND WRITING YOUR MODULE
-
-Considerations for module design and coding:
-
-=head2 To OO or not to OO?
-
-Your module may be object oriented (OO) or not, or it may have both kinds
-of interfaces available. There are pros and cons of each technique, which
-should be considered when you design your API.
-
-In I<Perl Best Practices> (copyright 2004, Published by O'Reilly Media, Inc.),
-Damian Conway provides a list of criteria to use when deciding if OO is the
-right fit for your problem:
-
-=over 4
-
-=item *
-
-The system being designed is large, or is likely to become large.
-
-=item *
-
-The data can be aggregated into obvious structures, especially if
-there's a large amount of data in each aggregate.
-
-=item *
-
-The various types of data aggregate form a natural hierarchy that
-facilitates the use of inheritance and polymorphism.
-
-=item *
-
-You have a piece of data on which many different operations are
-applied.
-
-=item *
-
-You need to perform the same general operations on related types of
-data, but with slight variations depending on the specific type of data
-the operations are applied to.
-
-=item *
-
-It's likely you'll have to add new data types later.
-
-=item *
-
-The typical interactions between pieces of data are best represented by
-operators.
-
-=item *
-
-The implementation of individual components of the system is likely to
-change over time.
-
-=item *
-
-The system design is already object-oriented.
-
-=item *
-
-Large numbers of other programmers will be using your code modules.
-
-=back
-
-Think carefully about whether OO is appropriate for your module.
-Gratuitous object orientation results in complex APIs which are
-difficult for the average module user to understand or use.
-
-=head2 Designing your API
-
-Your interfaces should be understandable by an average Perl programmer.
-The following guidelines may help you judge whether your API is
-sufficiently straightforward:
-
-=over 4
-
-=item Write simple routines to do simple things.
-
-It's better to have numerous simple routines than a few monolithic ones.
-If your routine changes its behaviour significantly based on its
-arguments, it's a sign that you should have two (or more) separate
-routines.
-
-=item Separate functionality from output.
-
-Return your results in the most generic form possible and allow the user
-to choose how to use them. The most generic form possible is usually a
-Perl data structure which can then be used to generate a text report,
-HTML, XML, a database query, or whatever else your users require.
-
-If your routine iterates through some kind of list (such as a list of
-files, or records in a database) you may consider providing a callback
-so that users can manipulate each element of the list in turn.
-File::Find provides an example of this with its
-C<find(\&wanted, $dir)> syntax.
-
-=item Provide sensible shortcuts and defaults.
-
-Don't require every module user to jump through the same hoops to achieve a
-simple result. You can always include optional parameters or routines for
-more complex or non-standard behaviour. If most of your users have to
-type a few almost identical lines of code when they start using your
-module, it's a sign that you should have made that behaviour a default.
-Another good indicator that you should use defaults is if most of your
-users call your routines with the same arguments.
-
-=item Naming conventions
-
-Your naming should be consistent. For instance, it's better to have:
-
- display_day();
- display_week();
- display_year();
-
-than
-
- display_day();
- week_display();
- show_year();
-
-This applies equally to method names, parameter names, and anything else
-which is visible to the user (and most things that aren't!)
-
-=item Parameter passing
-
-Use named parameters. It's easier to use a hash like this:
-
- $obj->do_something(
- name => "wibble",
- type => "text",
- size => 1024,
- );
-
-... than to have a long list of unnamed parameters like this:
-
- $obj->do_something("wibble", "text", 1024);
-
-While the list of arguments might work fine for one, two or even three
-arguments, any more arguments become hard for the module user to
-remember, and hard for the module author to manage. If you want to add
-a new parameter you will have to add it to the end of the list for
-backward compatibility, and this will probably make your list order
-unintuitive. Also, if many elements may be undefined you may see the
-following unattractive method calls:
-
- $obj->do_something(undef, undef, undef, undef, undef, undef, 1024);
-
-Provide sensible defaults for parameters which have them. Don't make
-your users specify parameters which will almost always be the same.
-
-The issue of whether to pass the arguments in a hash or a hashref is
-largely a matter of personal style.
-
-The use of hash keys starting with a hyphen (C<-name>) or entirely in
-upper case (C<NAME>) is a relic of older versions of Perl in which
-ordinary lower case strings were not handled correctly by the C<=E<gt>>
-operator. While some modules retain uppercase or hyphenated argument
-keys for historical reasons or as a matter of personal style, most new
-modules should use simple lower case keys. Whatever you choose, be
-consistent!
-
-=back
-
-=head2 Strictness and warnings
-
-Your module should run successfully under the strict pragma and should
-run without generating any warnings. Your module should also handle
-taint-checking where appropriate, though this can cause difficulties in
-many cases.
-
-=head2 Backwards compatibility
-
-Modules which are "stable" should not break backwards compatibility
-without at least a long transition phase and a major change in version
-number.
-
-=head2 Error handling and messages
-
-When your module encounters an error it should do one or more of:
-
-=over 4
-
-=item *
-
-Return an undefined value.
-
-=item *
-
-set C<$Module::errstr> or similar (C<errstr> is a common name used by
-DBI and other popular modules; if you choose something else, be sure to
-document it clearly).
-
-=item *
-
-C<warn()> or C<carp()> a message to STDERR.
-
-=item *
-
-C<croak()> only when your module absolutely cannot figure out what to
-do. (C<croak()> is a better version of C<die()> for use within
-modules, which reports its errors from the perspective of the caller.
-See L<Carp> for details of C<croak()>, C<carp()> and other useful
-routines.)
-
-=item *
-
-As an alternative to the above, you may prefer to throw exceptions using
-the Error module.
-
-=back
-
-Configurable error handling can be very useful to your users. Consider
-offering a choice of levels for warning and debug messages, an option to
-send messages to a separate file, a way to specify an error-handling
-routine, or other such features. Be sure to default all these options
-to the commonest use.
-
-=head1 DOCUMENTING YOUR MODULE
-
-=head2 POD
-
-Your module should include documentation aimed at Perl developers.
-You should use Perl's "plain old documentation" (POD) for your general
-technical documentation, though you may wish to write additional
-documentation (white papers, tutorials, etc) in some other format.
-You need to cover the following subjects:
-
-=over 4
-
-=item *
-
-A synopsis of the common uses of the module
-
-=item *
-
-The purpose, scope and target applications of your module
-
-=item *
-
-Use of each publically accessible method or subroutine, including
-parameters and return values
-
-=item *
-
-Examples of use
-
-=item *
-
-Sources of further information
-
-=item *
-
-A contact email address for the author/maintainer
-
-=back
-
-The level of detail in Perl module documentation generally goes from
-less detailed to more detailed. Your SYNOPSIS section should contain a
-minimal example of use (perhaps as little as one line of code; skip the
-unusual use cases or anything not needed by most users); the
-DESCRIPTION should describe your module in broad terms, generally in
-just a few paragraphs; more detail of the module's routines or methods,
-lengthy code examples, or other in-depth material should be given in
-subsequent sections.
-
-Ideally, someone who's slightly familiar with your module should be able
-to refresh their memory without hitting "page down". As your reader
-continues through the document, they should receive a progressively
-greater amount of knowledge.
-
-The recommended order of sections in Perl module documentation is:
-
-=over 4
-
-=item *
-
-NAME
-
-=item *
-
-SYNOPSIS
-
-=item *
-
-DESCRIPTION
-
-=item *
-
-One or more sections or subsections giving greater detail of available
-methods and routines and any other relevant information.
-
-=item *
-
-BUGS/CAVEATS/etc
-
-=item *
-
-AUTHOR
-
-=item *
-
-SEE ALSO
-
-=item *
-
-COPYRIGHT and LICENSE
-
-=back
-
-Keep your documentation near the code it documents ("inline"
-documentation). Include POD for a given method right above that
-method's subroutine. This makes it easier to keep the documentation up
-to date, and avoids having to document each piece of code twice (once in
-POD and once in comments).
-
-=head2 README, INSTALL, release notes, changelogs
-
-Your module should also include a README file describing the module and
-giving pointers to further information (website, author email).
-
-An INSTALL file should be included, and should contain simple installation
-instructions. When using ExtUtils::MakeMaker this will usually be:
-
-=over 4
-
-=item perl Makefile.PL
-
-=item make
-
-=item make test
-
-=item make install
-
-=back
-
-When using Module::Build, this will usually be:
-
-=over 4
-
-=item perl Build.PL
-
-=item perl Build
-
-=item perl Build test
-
-=item perl Build install
-
-=back
-
-Release notes or changelogs should be produced for each release of your
-software describing user-visible changes to your module, in terms
-relevant to the user.
-
-=head1 RELEASE CONSIDERATIONS
-
-=head2 Version numbering
-
-Version numbers should indicate at least major and minor releases, and
-possibly sub-minor releases. A major release is one in which most of
-the functionality has changed, or in which major new functionality is
-added. A minor release is one in which a small amount of functionality
-has been added or changed. Sub-minor version numbers are usually used
-for changes which do not affect functionality, such as documentation
-patches.
-
-The most common CPAN version numbering scheme looks like this:
-
- 1.00, 1.10, 1.11, 1.20, 1.30, 1.31, 1.32
-
-A correct CPAN version number is a floating point number with at least
-2 digits after the decimal. You can test whether it conforms to CPAN by
-using
-
- perl -MExtUtils::MakeMaker -le 'print MM->parse_version(shift)' 'Foo.pm'
-
-If you want to release a 'beta' or 'alpha' version of a module but
-don't want CPAN.pm to list it as most recent use an '_' after the
-regular version number followed by at least 2 digits, eg. 1.20_01. If
-you do this, the following idiom is recommended:
-
- $VERSION = "1.12_01";
- $XS_VERSION = $VERSION; # only needed if you have XS code
- $VERSION = eval $VERSION;
-
-With that trick MakeMaker will only read the first line and thus read
-the underscore, while the perl interpreter will evaluate the $VERSION
-and convert the string into a number. Later operations that treat
-$VERSION as a number will then be able to do so without provoking a
-warning about $VERSION not being a number.
-
-Never release anything (even a one-word documentation patch) without
-incrementing the number. Even a one-word documentation patch should
-result in a change in version at the sub-minor level.
-
-=head2 Pre-requisites
-
-Module authors should carefully consider whether to rely on other
-modules, and which modules to rely on.
-
-Most importantly, choose modules which are as stable as possible. In
-order of preference:
-
-=over 4
-
-=item *
-
-Core Perl modules
-
-=item *
-
-Stable CPAN modules
-
-=item *
-
-Unstable CPAN modules
-
-=item *
-
-Modules not available from CPAN
-
-=back
-
-Specify version requirements for other Perl modules in the
-pre-requisites in your Makefile.PL or Build.PL.
-
-Be sure to specify Perl version requirements both in Makefile.PL or
-Build.PL and with C<require 5.6.1> or similar. See the section on
-C<use VERSION> of L<perlfunc/require> for details.
-
-=head2 Testing
-
-All modules should be tested before distribution (using "make disttest"),
-and the tests should also be available to people installing the modules
-(using "make test").
-For Module::Build you would use the C<make test> equivalent C<perl Build test>.
-
-The importance of these tests is proportional to the alleged stability of a
-module. A module which purports to be stable or which hopes to achieve wide
-use should adhere to as strict a testing regime as possible.
-
-Useful modules to help you write tests (with minimum impact on your
-development process or your time) include Test::Simple, Carp::Assert
-and Test::Inline.
-For more sophisticated test suites there are Test::More and Test::MockObject.
-
-=head2 Packaging
-
-Modules should be packaged using one of the standard packaging tools.
-Currently you have the choice between ExtUtils::MakeMaker and the
-more platform independent Module::Build, allowing modules to be installed in a
-consistent manner.
-When using ExtUtils::MakeMaker, you can use "make dist" to create your
-package. Tools exist to help you to build your module in a MakeMaker-friendly
-style. These include ExtUtils::ModuleMaker and h2xs. See also L<perlnewmod>.
-
-=head2 Licensing
-
-Make sure that your module has a license, and that the full text of it
-is included in the distribution (unless it's a common one and the terms
-of the license don't require you to include it).
-
-If you don't know what license to use, dual licensing under the GPL
-and Artistic licenses (the same as Perl itself) is a good idea.
-See L<perlgpl> and L<perlartistic>.
-
-=head1 COMMON PITFALLS
-
-=head2 Reinventing the wheel
-
-There are certain application spaces which are already very, very well
-served by CPAN. One example is templating systems, another is date and
-time modules, and there are many more. While it is a rite of passage to
-write your own version of these things, please consider carefully
-whether the Perl world really needs you to publish it.
-
-=head2 Trying to do too much
-
-Your module will be part of a developer's toolkit. It will not, in
-itself, form the B<entire> toolkit. It's tempting to add extra features
-until your code is a monolithic system rather than a set of modular
-building blocks.
-
-=head2 Inappropriate documentation
-
-Don't fall into the trap of writing for the wrong audience. Your
-primary audience is a reasonably experienced developer with at least
-a moderate understanding of your module's application domain, who's just
-downloaded your module and wants to start using it as quickly as possible.
-
-Tutorials, end-user documentation, research papers, FAQs etc are not
-appropriate in a module's main documentation. If you really want to
-write these, include them as sub-documents such as C<My::Module::Tutorial> or
-C<My::Module::FAQ> and provide a link in the SEE ALSO section of the
-main documentation.
-
-=head1 SEE ALSO
-
-=over 4
-
-=item L<perlstyle>
-
-General Perl style guide
-
-=item L<perlnewmod>
-
-How to create a new module
-
-=item L<perlpod>
-
-POD documentation
-
-=item L<podchecker>
-
-Verifies your POD's correctness
-
-=item Packaging Tools
-
-L<ExtUtils::MakeMaker>, L<Module::Build>
-
-=item Testing tools
-
-L<Test::Simple>, L<Test::Inline>, L<Carp::Assert>, L<Test::More>, L<Test::MockObject>
-
-=item http://pause.perl.org/
-
-Perl Authors Upload Server. Contains links to information for module
-authors.
-
-=item Any good book on software engineering
-
-=back
-
-=head1 AUTHOR
-
-Kirrily "Skud" Robert <skud@cpan.org>
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlmpeix.pod b/Master/tlpkg/tlperl/lib/pods/perlmpeix.pod
deleted file mode 100644
index c382c466920..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlmpeix.pod
+++ /dev/null
@@ -1,711 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see perlpod manpage) which is
-specially designed to be readable as is.
-
-=head1 NAME
-
-perlmpeix - Perl/iX for HP e3000 MPE
-
-=head1 SYNOPSIS
-
- http://www.bixby.org/mark/perlix.html
- Perl language for MPE
- Last updated January 12, 2006 @ 2100 UTC
-
-
-=head1 NOTE
-
-This is a podified version of what used to be on the above-mentioned web page,
-podified by Jarkko Hietaniemi 2001-Jan-01.
-
-=head1 What's New in Perl for MPE/iX
-
-January 12, 2006
-
-=over 4
-
-=item *
-
-Updated for perl-5.8.8 and perl-5.9.3 by Ken Hirsch.
-
-Simplified the build process by using the MPEAUTOCONF
-functionality in Mark Klein's ld.
-
-If you build this from scratch, make sure you have a version
-of ld which supports it. In the shell, type
-
- ld --help
- and look for AUTOCONF or MPEAUTOCONF near the bottom
-
- or do this:
- ld --help 2>&1 | grep AUTOCONF
-
-If you see don't see AUTOCONF or MPEAUTOCONF, make sure you get a new
-version.
-
-You also do not have to use mpeix/relink after building, so the
-recommend sequence is:
-
- ./Configure -de
-
- # or ./Configure -de -Dusedevel
- # if you're building a development version
-
- make
- make test
- # if you run this in a job, do "make test_notty"
-
- make install
-
-Be prepared for a wait. These take much longer on MPE/iX than on a Unix
-system, because of a slow forking, mostly. On a lightly-loaded HP3000
-Series 979 running MPE/iX 7.5:
-
- Configure: 1 hour
- make: 1 hour 15 minutes
- make test 1 hour 45 minutes
-
-Various socket problems were fixed in mpeix.c.
-
-Mark Klein provided a fixed sigsetjmp (that works with dynamic
-libraries) in mpeix_setjmp.c
-
-=back
-
-June 1, 2000
-
-=over 4
-
-=item *
-
-Rebuilt to be compatible with mod_perl. If you plan on using
-mod_perl, you MUST download and install this version of Perl/iX!
-
-=item *
-
-uselargefiles="undef": not available in MPE for POSIX files yet.
-
-=item *
-
-Now bundled with various add-on packages:
-
-=over 8
-
-=item *
-
-libnet (as seen on CPAN)
-
-=item *
-
-libwww-perl (LWP) which lets Perl programs behave like web browsers:
-
-=item *
-
-mod_perl (just the perl portion; the actual DSO will be released
-soon with Apache/iX 1.3.12 from bixby.org). This module allows you to
-write high performance persistent Perl CGI scripts and all sorts of
-cool things. (L<http://perl.apache.org/>)
-
-and much much more hiding under /PERL/PUB/.cpan/
-
-=item *
-
-The CPAN module now works for automatic downloading and
-installing of add-on packages:
-
- 1. export FTP_PASSIVE=1
- 2. perl -MCPAN -e shell
- 3. Ignore any terminal I/O related complaints!
-
-(L<http://search.cpan.org/dist/CPAN/>)
-
-=back
-
-=back
-
-May 20, 2000
-
-=over 4
-
-=item *
-
-Updated to version 5.6.0. Builds straight out of the box on MPE/iX.
-
-=item *
-
-Perl's getpwnam() function which had regressed to being
-unimplemented on MPE is now implemented once again.
-
-=back
-
-September 17, 1999
-
-=over 4
-
-=item *
-
-Migrated from cccd.edu to bixby.org.
-
-=back
-
-=head1 Welcome to Perl/iX
-
-This is the official home page for the HP e3000 MPE/iX
-( L<http://www.hp.com/go/e3000> ) port of the Perl scripting
-language ( L<http://www.perl.com/> ) which gives you all of the power of C,
-awk, sed, and sh in a single language. Check here for the latest news,
-implemented functionality, known bugs, to-do list, etc. Status reports
-about major milestones will also be posted to the HP3000-L mailing list
-( L<http://www.lsoft.com/scripts/wl.exe?SL1=HP3000-L&H=RAVEN.UTC.EDU> ) and
-its associated gatewayed newsgroup comp.sys.hp.mpe.
-
-I'm doing this port because I can't live without Perl on the Unix
-machines that I administer, and I want to have the same power
-available to me on MPE.
-
-Please send your comments, questions, and bug reports directly to me,
-Mark Bixby ( L<http://www.bixby.org/mark/> ). Or just post them to HP3000-L.
-
-The platform I'm using to do this port is an HP 3000 957RX running
-MPE/iX 6.0 and using the GNU gcc C compiler
-( L<http://jazz.external.hp.com/src/gnu/gnuframe.html> ).
-
-The combined porting wisdom from all of my ports can be found in my
-MPE/iX Porting Guide (L<http://www.bixby.org/mark/porting.html>).
-
-IMPORTANT NOTICE: Yes, I do work for the HP CSY R&D lab, but ALL of
-the software you download from bixby.org is my personal freeware that
-is NOT supported by HP.
-
-=head1 System Requirements for Perl/iX
-
-=over 4
-
-=item *
-
-MPE/iX 5.5 or later. This version of Perl/iX does NOT run on
-MPE/iX 5.0 or earlier, nor does it run on "classic" MPE/V machines.
-
-=item *
-
-If you wish to recompile Perl, you must install both GNUCORE and
-GNUGCC from jazz (L<http://jazz.external.hp.com/src/gnu/gnuframe.html>).
-
-=item *
-
-Perl/iX will be happier on MPE/iX 5.5 if you install the MPEKX40B
-extended POSIX filename characters patch, but this is optional.
-
-=item *
-
-Patch LBCJXT6A is required on MPE/iX 5.5 machines in order to
-prevent Perl/iX from dying with an unresolved external reference
-to _getenv_libc.
-
-=item *
-
-If you will be compiling Perl/iX yourself, you will also need
-Syslog/iX ( L<http://www.bixby.org/mark/syslogix.html> ) and the
-/BIND/PUB/include and /BIND/PUB/lib portions of BIND/iX
-( L<http://www.bixby.org/mark/bindix.html> ).
-
-=back
-
-=head1 How to Obtain Perl/iX
-
-=over 4
-
-=item 1.
-
-Download Perl using either FTP.ARPA.SYS or some other client
-
-=item 2.
-
-Extract the installation script
-
-=item 3.
-
-Edit the installation script
-
-=item 4.
-
-Run the installation script
-
-=item 5.
-
-Convert your *.a system archive libraries to *.sl shared libraries
-
-=back
-
-Download Perl using FTP.ARPA.SYS from your HP 3000 (the preferred
-method).....
-
- :HELLO MANAGER.SYS
- :XEQ FTP.ARPA.SYS
- open ftp.bixby.org
- anonymous
- your@email.address
- bytestream
- cd /pub/mpe
- get perl-5.6.0-mpe.tar.Z /tmp/perl.tar.Z;disc=2147483647
- exit
-
-.....Or download using some other generic web or ftp client (the alternate
-method)
-
-Download the following files (make sure that you use "binary mode" or
-whatever client feature that is 8-bit clean):
-
-=over 4
-
-=item *
-
-Perl from
-
- http://www.bixby.org/ftp/pub/mpe/perl-5.6.0-mpe.tar.Z
-
-or
-
- ftp://ftp.bixby.org/pub/mpe/perl-5.6.0-mpe.tar.Z
-
-=item *
-
-Upload those files to your HP 3000 in an 8-bit clean bytestream manner to:
-
- /tmp/perl.tar.Z
-
-=item *
-
-Then extract the installation script (after both download methods)
-
- :CHDIR /tmp
- :XEQ TAR.HPBIN.SYS 'xvfopz /tmp/perl.tar.Z INSTALL'
-
-=item *
-
-Edit the installation script
-
-Examine the accounting structure creation commands and modify if
-necessary (adding additional capabilities, choosing a non-system
-volume set, etc).
-
- :XEQ VI.HPBIN.SYS /tmp/INSTALL
-
-=item *
-
-Run the installation script.
-
-The accounting structure will be created and then all files will be
-extracted from the archive.
-
- :XEQ SH.HPBIN.SYS /tmp/INSTALL
-
-=item *
-
-Convert your *.a system archive libraries to *.sl shared libraries
-
-You only have to do this ONCE on your MPE/iX 5.5 machine in order to
-convert /lib/lib*.a and /usr/lib/lib*.a libraries to their *.sl
-equivalents. This step should not be necessary on MPE/iX 6.0 or later
-machines because the 6.0 or later update process does it for you.
-
- :XEQ SH.HPBIN.SYS /PERL/PUB/LIBSHP3K
-
-=back
-
-=head1 Perl/iX Distribution Contents Highlights
-
-=over 4
-
-=item README
-
-The file you're reading now.
-
-=item INSTALL
-
-Perl/iX Installation script.
-
-=item LIBSHP3K
-
-Script to convert *.a system archive libraries to *.sl shared libraries.
-
-=item PERL
-
-Perl NMPRG executable. A version-numbered backup copy also
-exists. You might wish to "ln -s /PERL/PUB/PERL /usr/local/bin/perl".
-
-=item .cpan/
-
-Much add-on source code downloaded with the CPAN module.
-
-=item lib/
-
-Perl libraries, both core and add-on.
-
-=item man/
-
-Perl man page documentation.
-
-=item public_html/feedback.cgi
-
-Sample feedback CGI form written in Perl.
-
-=item src/perl-5.6.0-mpe
-
-Source code.
-
-=back
-
-=head1 How to Compile Perl/iX
-
-=over 4
-
-=item 1.
-
-cd src/perl-5.6.0-mpe
-
-=item 2.
-
-Read the INSTALL file for the official instructions
-
-=item 3.
-
-./Configure -d
-
-=item 4.
-
-make
-
-=item 5.
-
-./mpeix/relink
-
-=item 6.
-
-make test (expect approximately 15 out of 11306 subtests to fail,
-mostly due to MPE not supporting hard links, UDP socket problems,
-and handling exit() return codes improperly)
-
-=item 7.
-
-make install
-
-=item 8.
-
-Optionally create symbolic links that point to the Perl
-executable, i.e. ln -s /PERL/PUB/PERL /usr/local/bin/perl
-
-=back
-
-The summary test results from "cd t; ./perl -I../lib harness":
-
- Failed Test Status Wstat Total Fail Failed List of failed
- ---------------------------------------------------------------------------
- io/fs.t 29 8 27.59% 2-5, 7-9, 11
- io/openpid.t 10 1 10.00% 7
- lib/io_sock.t 14 1 7.14% 13
- lib/io_udp.t 7 2 28.57% 3, 5
- lib/posix.t 27 1 3.70% 12
- op/lex_assign.t 187 1 0.53% 13
- op/stat.t 58 1 1.72% 3
- 15 tests and 94 subtests skipped.
- Failed 7/236 test scripts, 97.03% okay. 15/11306 subtests failed, 99.87% okay.
-
-=head1 Getting Started with Perl/iX
-
-Create your Perl script files with "#!/PERL/PUB/perl" (or an
-equivalent symbolic link) as the first line. Use the chmod command to
-make sure that your script has execute permission. Run your script!
-
-Be sure to take a look at the CPAN module list
-( L<http://www.cpan.org/CPAN.html> ). A wide variety of free Perl software
-is available. You can automatically download these packages by using
-the CPAN module ( L<http://search.cpan.org/dist/CPAN/> ).
-
-=head1 MPE/iX Implementation Considerations
-
-There some minor functionality issues to be aware of when comparing
-Perl for Unix (Perl/UX) to Perl/iX:
-
-=over 4
-
-=item *
-
-MPE gcc/ld doesn't properly support linking NMPRG executables against
-NMXL dynamic libraries, so you must manually run mpeix/relink after
-each re-build of Perl.
-
-=item *
-
-Perl/iX File::Copy will use MPE's /bin/cp command to copy files by
-name in order to preserve file attributes like file code.
-
-=item *
-
-MPE (and thus Perl/iX) lacks support for setgrent(), endgrent(),
-setpwent(), endpwent().
-
-=item *
-
-MPE (and thus Perl/iX) lacks support for hard links.
-
-=item *
-
-MPE requires GETPRIVMODE() in order to bind() to ports less than 1024.
-Perl/iX will call GETPRIVMODE() automatically on your behalf if you
-attempt to bind() to these low-numbered ports. Note that the Perl/iX
-executable and the PERL account do not normally have CAP=PM, so if you
-will be bind()-ing to these privileged ports, you will manually need
-to add PM capability as appropriate.
-
-=item *
-
-MPE requires that you bind() to an IP address of zero. Perl/iX
-automatically replaces the IP address that you pass to bind() with
-a zero.
-
-=item *
-
-MPE requires GETPRIVMODE() in order to setuid(). There are too many
-calls to setuid() within Perl/iX, so I have not attempted an automatic
-GETPRIVMODE() solution similar to bind().
-
-=back
-
-=head1 Known Perl/iX Bugs Under Investigation
-
-None.
-
-=head1 Perl/iX To-Do List
-
-=over 4
-
-=item *
-
-Make setuid()/setgid() support work.
-
-=item *
-
-Make sure that fcntl() against a socket descriptor is redirected to sfcntl().
-
-=item *
-
-Add support for Berkeley DB once I've finished porting Berkeley DB.
-
-=item *
-
-Write an MPE XS extension library containing miscellaneous important
-MPE functions like GETPRIVMODE(), GETUSERMODE(), and sfcntl().
-
-=back
-
-=head1 Perl/iX Change History
-
-May 6, 1999
-
-=over 4
-
-=item *
-
-Patch LBCJXT6A is required on MPE/iX 5.5 machines in order to prevent
-Perl/iX from dying with an unresolved external reference to _getenv_libc.
-
-=back
-
-April 7, 1999
-
-=over 4
-
-=item *
-
-Updated to version 5.005_03.
-
-=item *
-
-The official source distribution once again compiles "straight out
-of the box" for MPE.
-
-=item *
-
-The current incarnation of the 5.5 POSIX filename extended
-characters patch is now MPEKX40B.
-
-=item *
-
-The LIBSHP3K *.a -> *.sl library conversion script is now included
-as /PERL/PUB/LIBSHP3K.
-
-=back
-
-November 20, 1998
-
-=over 4
-
-=item *
-
-Updated to version 5.005_02.
-
-=item *
-
-Fixed a DynaLoader bug that was unable to load symbols from relative
-path name libraries.
-
-=item *
-
-Fixed a .xs compilation bug where the mpeixish.sh include file wasn't
-being installed into the proper directory.
-
-=item *
-
-All bugfixes will be submitted back to the official Perl developers.
-
-=item *
-
-The current incarnation of the POSIX filename extended characters
-patch is now MPEKXJ3A.
-
-=back
-
-August 14, 1998
-
-=over 4
-
-=item *
-
-The previous POSIX filename extended characters patch MPEKX44C has
-been superseded by MPEKXB5A.
-
-=back
-
-August 7, 1998
-
-=over 4
-
-=item *
-
-The previous POSIX filename extended characters patch MPEKX76A has
-been superseded by MPEKX44C.
-
-=back
-
-July 28, 1998
-
-=over 4
-
-=item *
-
-Updated to version 5.005_01.
-
-=back
-
-July 23, 1998
-
-=over 4
-
-=item *
-
-Updated to version 5.005 (production release). The public
-freeware sources are now 100% MPE-ready "straight out of the box".
-
-=back
-
-July 17, 1998
-
-=over 4
-
-=item *
-
-Updated to version 5.005b1 (public beta release). The public
-freeware sources are now 99.9% MPE-ready. By installing and
-testing this beta on your own HP3000, you will be helping to
-insure that the final release of 5.005 will be 100% MPE-ready and
-100% bug free.
-
-=item *
-
-My MPE binary release is now extracted using my standard INSTALL script.
-
-=back
-
-July 15, 1998
-
-=over 4
-
-=item *
-
-Changed startperl to #!/PERL/PUB/perl so that Perl will recognize
-scripts more easily and efficiently.
-
-=back
-
-July 8, 1998
-
-=over 4
-
-=item *
-
-Updated to version 5.004_70 (internal developer release) which is now
-MPE-ready. The next public freeware release of Perl should compile
-"straight out of the box" on MPE. Note that this version of Perl/iX
-was strictly internal to me and never publicly released. Note that
-[21]BIND/iX is now required (well, the include files and libbind.a) if
-you wish to compile Perl/iX.
-
-=back
-
-November 6, 1997
-
-=over 4
-
-=item *
-
-Updated to version 5.004_04. No changes in MPE-specific functionality.
-
-=back
-
-October 16, 1997
-
-=over 4
-
-=item *
-
-Added Demos section to the Perl/iX home page so you can see some
-sample Perl applications running on my 3000.
-
-=back
-
-October 3, 1997
-
-=over 4
-
-=item *
-
-Added System Requirements section to the Perl/iX home page just so the
-prerequisites stand out more. Various other home page tweaks.
-
-=back
-
-October 2, 1997
-
-=over 4
-
-=item *
-
-Initial public release.
-
-=back
-
-September 1997
-
-=over 4
-
-=item *
-
-Porting begins.
-
-=back
-
-=head1 AUTHOR
-
-Mark Bixby, L<http://www.bixby.org/mark/>
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlmroapi.pod b/Master/tlpkg/tlperl/lib/pods/perlmroapi.pod
deleted file mode 100644
index 54da7dded25..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlmroapi.pod
+++ /dev/null
@@ -1,102 +0,0 @@
-=head1 NAME
-
-perlmroapi - Perl method resolution plugin interface
-
-=head1 DESCRIPTION
-
-As of Perl 5.10.1 there is a new interface for plugging and using method
-resolution orders other than the default (linear depth first search).
-The C3 method resolution order added in 5.10.0 has been re-implemented as
-a plugin, without changing its Perl-space interface.
-
-Each plugin should register itself by providing
-the following structure
-
- struct mro_alg {
- AV *(*resolve)(pTHX_ HV *stash, U32 level);
- const char *name;
- U16 length;
- U16 kflags;
- U32 hash;
- };
-
-and calling C<Perl_mro_register>:
-
- Perl_mro_register(aTHX_ &my_mro_alg);
-
-=over 4
-
-=item resolve
-
-Pointer to the linearisation function, described below.
-
-=item name
-
-Name of the MRO, either in ISO-8859-1 or UTF-8.
-
-=item length
-
-Length of the name.
-
-=item kflags
-
-If the name is given in UTF-8, set this to C<HVhek_UTF8>. The value is passed
-direct as the parameter I<kflags> to C<hv_common()>.
-
-=item hash
-
-A precomputed hash value for the MRO's name, or 0.
-
-=back
-
-=head1 Callbacks
-
-The C<resolve> function is called to generate a linearised ISA for the
-given stash, using this MRO. It is called with a pointer to the stash, and
-a I<level> of 0. The core always sets I<level> to 0 when it calls your
-function - the parameter is provided to allow your implementation to track
-depth if it needs to recurse.
-
-The function should return a reference to an array containing the parent
-classes in order. The names of the classes should be the result of calling
-C<HvENAME()> on the stash. In those cases where C<HvENAME()> returns null,
-C<HvNAME()> should be used instead.
-
-The caller is responsible for incrementing the reference count of the array
-returned if it wants to keep the structure. Hence, if you have created a
-temporary value that you keep no pointer to, C<sv_2mortal()> to ensure that
-it is disposed of correctly. If you have cached your return value, then
-return a pointer to it without changing the reference count.
-
-=head1 Caching
-
-Computing MROs can be expensive. The implementation provides a cache, in
-which you can store a single C<SV *>, or anything that can be cast to
-C<SV *>, such as C<AV *>. To read your private value, use the macro
-C<MRO_GET_PRIVATE_DATA()>, passing it the C<mro_meta> structure from the
-stash, and a pointer to your C<mro_alg> structure:
-
- meta = HvMROMETA(stash);
- private_sv = MRO_GET_PRIVATE_DATA(meta, &my_mro_alg);
-
-To set your private value, call C<Perl_mro_set_private_data()>:
-
- Perl_mro_set_private_data(aTHX_ meta, &c3_alg, private_sv);
-
-The private data cache will take ownership of a reference to private_sv,
-much the same way that C<hv_store()> takes ownership of a reference to the
-value that you pass it.
-
-=head1 Examples
-
-For examples of MRO implementations, see C<S_mro_get_linear_isa_c3()>
-and the C<BOOT:> section of F<mro/mro.xs>, and C<S_mro_get_linear_isa_dfs()>
-in F<mro.c>
-
-=head1 AUTHORS
-
-The implementation of the C3 MRO and switchable MROs within the perl core was
-written by Brandon L Black. Nicholas Clark created the pluggable interface,
-refactored Brandon's implementation to work with it, and wrote this document.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlnetware.pod b/Master/tlpkg/tlperl/lib/pods/perlnetware.pod
deleted file mode 100644
index 6720a58212a..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlnetware.pod
+++ /dev/null
@@ -1,225 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see pod/perlpod.pod) which is
-specifically designed to be readable as is.
-
-=head1 NAME
-
-perlnetware - Perl for NetWare
-
-=head1 DESCRIPTION
-
-This file gives instructions for building Perl 5.7 and above, and also
-Perl modules for NetWare. Before you start, you may want to read the
-README file found in the top level directory into which the Perl source
-code distribution was extracted. Make sure you read and understand
-the terms under which the software is being distributed.
-
-=head1 BUILD
-
-This section describes the steps to be performed to build a Perl NLM
-and other associated NLMs.
-
-=head2 Tools & SDK
-
-The build requires CodeWarrior compiler and linker. In addition,
-the "NetWare SDK", "NLM & NetWare Libraries for C" and
-"NetWare Server Protocol Libraries for C", all available at
-L<http://developer.novell.com/wiki/index.php/Category:Novell_Developer_Kit>,
-are required. Microsoft Visual C++ version 4.2 or later is also
-required.
-
-=head2 Setup
-
-The build process is dependent on the location of the NetWare SDK.
-Once the Tools & SDK are installed, the build environment has to
-be setup. The following batch files setup the environment.
-
-=over 4
-
-=item SetNWBld.bat
-
-The Execution of this file takes 2 parameters as input. The first
-being the NetWare SDK path, second being the path for CodeWarrior
-Compiler & tools. Execution of this file sets these paths and also
-sets the build type to Release by default.
-
-=item Buildtype.bat
-
-This is used to set the build type to debug or release. Change the
-build type only after executing SetNWBld.bat
-
-Example:
-
-=over
-
-=item 1.
-
-Typing "buildtype d on" at the command prompt causes the buildtype
-to be set to Debug type with D2 flag set.
-
-=item 2.
-
-Typing "buildtype d off" or "buildtype d" at the command prompt causes
-the buildtype to be set to Debug type with D1 flag set.
-
-=item 3.
-
-Typing "buildtype r" at the command prompt sets it to Release Build type.
-
-=back
-
-=back
-
-=head2 Make
-
-The make process runs only under WinNT shell. The NetWare makefile is
-located under the NetWare folder. This makes use of miniperl.exe to
-run some of the Perl scripts. To create miniperl.exe, first set the
-required paths for Visual c++ compiler (specify vcvars32 location) at
-the command prompt. Then run nmake from win32 folder through WinNT
-command prompt. The build process can be stopped after miniperl.exe
-is created. Then run nmake from NetWare folder through WinNT command
-prompt.
-
-Currently the following two build types are tested on NetWare:
-
-=over 4
-
-=item *
-
-USE_MULTI, USE_ITHREADS & USE_IMP_SYS defined
-
-=item *
-
-USE_MULTI & USE_IMP_SYS defined and USE_ITHREADS not defined
-
-=back
-
-=head2 Interpreter
-
-Once miniperl.exe creation is over, run nmake from the NetWare folder.
-This will build the Perl interpreter for NetWare as I<perl.nlm>.
-This is copied under the I<Release> folder if you are doing
-a release build, else will be copied under I<Debug> folder for debug builds.
-
-=head2 Extensions
-
-The make process also creates the Perl extensions as I<<Extension>.nlm>
-
-=head1 INSTALL
-
-To install NetWare Perl onto a NetWare server, first map the Sys
-volume of a NetWare server to I<i:>. This is because the makefile by
-default sets the drive letter to I<i:>. Type I<nmake nwinstall> from
-NetWare folder on a WinNT command prompt. This will copy the binaries
-and module files onto the NetWare server under I<sys:\Perl>
-folder. The Perl interpreter, I<perl.nlm>, is copied under
-I<sys:\perl\system> folder. Copy this to I<sys:\system> folder.
-
-Example: At the command prompt Type "nmake nwinstall".
- This will install NetWare Perl on the NetWare Server.
- Similarly, if you type "nmake install",
- this will cause the binaries to be installed on the local machine.
- (Typically under the c:\perl folder)
-
-=head1 BUILD NEW EXTENSIONS
-
-To build extensions other than standard extensions, NetWare Perl has
-to be installed on Windows along with Windows Perl. The Perl for
-Windows can be either downloaded from the CPAN site and built using
-the sources, or the binaries can be directly downloaded from the
-ActiveState site. Installation can be done by invoking I<nmake
-install> from the NetWare folder on a WinNT command prompt after
-building NetWare Perl by following steps given above. This will copy
-all the *.pm files and other required files. Documentation files are
-not copied. Thus one must first install Windows Perl, Then install
-NetWare Perl.
-
-Once this is done, do the following to build any extension:
-
-=over 4
-
-=item *
-
-Change to the extension directory where its source files are present.
-
-=item *
-
-Run the following command at the command prompt:
-
- perl -II<path to NetWare lib dir> -II<path to lib> Makefile.pl
-
-Example:
-
- perl -Ic:/perl/5.6.1/lib/NetWare-x86-multi-thread -Ic:\perl\5.6.1\lib MakeFile.pl
-
-or
-
- perl -Ic:/perl/5.8.0/lib/NetWare-x86-multi-thread -Ic:\perl\5.8.0\lib MakeFile.pl
-
-=item *
-
-nmake
-
-=item *
-
-nmake install
-
-Install will copy the files into the Windows machine where NetWare
-Perl is installed and these files may have to be copied to the NetWare
-server manually. Alternatively, pass I<INSTALLSITELIB=i:\perl\lib> as
-an input to makefile.pl above. Here I<i:> is the mapped drive to the
-sys: volume of the server where Perl on NetWare is installed. Now
-typing I<nmake install>, will copy the files onto the NetWare server.
-
-Example: You can execute the following on the command prompt.
-
- perl -Ic:/perl/5.6.1/lib/NetWare-x86-multi-thread -Ic:\perl\5.6.1\lib MakeFile.pl
- INSTALLSITELIB=i:\perl\lib
-
-or
-
- perl -Ic:/perl/5.8.0/lib/NetWare-x86-multi-thread -Ic:\perl\5.8.0\lib MakeFile.pl
- INSTALLSITELIB=i:\perl\lib
-
-=item *
-
-Note: Some modules downloaded from CPAN may require NetWare related
-API in order to build on NetWare. Other modules may however build
-smoothly with or without minor changes depending on the type of
-module.
-
-=back
-
-=head1 ACKNOWLEDGEMENTS
-
-The makefile for Win32 is used as a reference to create the makefile
-for NetWare. Also, the make process for NetWare port uses
-miniperl.exe to run scripts during the make and installation process.
-
-=head1 AUTHORS
-
-Anantha Kesari H Y (hyanantha@novell.com)
-Aditya C (caditya@novell.com)
-
-=head1 DATE
-
-=over 4
-
-=item *
-
-Created - 18 Jan 2001
-
-=item *
-
-Modified - 25 June 2001
-
-=item *
-
-Modified - 13 July 2001
-
-=item *
-
-Modified - 28 May 2002
-
-=back
diff --git a/Master/tlpkg/tlperl/lib/pods/perlnewmod.pod b/Master/tlpkg/tlperl/lib/pods/perlnewmod.pod
deleted file mode 100644
index 7555f974a80..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlnewmod.pod
+++ /dev/null
@@ -1,280 +0,0 @@
-=head1 NAME
-
-perlnewmod - preparing a new module for distribution
-
-=head1 DESCRIPTION
-
-This document gives you some suggestions about how to go about writing
-Perl modules, preparing them for distribution, and making them available
-via CPAN.
-
-One of the things that makes Perl really powerful is the fact that Perl
-hackers tend to want to share the solutions to problems they've faced,
-so you and I don't have to battle with the same problem again.
-
-The main way they do this is by abstracting the solution into a Perl
-module. If you don't know what one of these is, the rest of this
-document isn't going to be much use to you. You're also missing out on
-an awful lot of useful code; consider having a look at L<perlmod>,
-L<perlmodlib> and L<perlmodinstall> before coming back here.
-
-When you've found that there isn't a module available for what you're
-trying to do, and you've had to write the code yourself, consider
-packaging up the solution into a module and uploading it to CPAN so that
-others can benefit.
-
-=head2 Warning
-
-We're going to primarily concentrate on Perl-only modules here, rather
-than XS modules. XS modules serve a rather different purpose, and
-you should consider different things before distributing them - the
-popularity of the library you are gluing, the portability to other
-operating systems, and so on. However, the notes on preparing the Perl
-side of the module and packaging and distributing it will apply equally
-well to an XS module as a pure-Perl one.
-
-=head2 What should I make into a module?
-
-You should make a module out of any code that you think is going to be
-useful to others. Anything that's likely to fill a hole in the communal
-library and which someone else can slot directly into their program. Any
-part of your code which you can isolate and extract and plug into
-something else is a likely candidate.
-
-Let's take an example. Suppose you're reading in data from a local
-format into a hash-of-hashes in Perl, turning that into a tree, walking
-the tree and then piping each node to an Acme Transmogrifier Server.
-
-Now, quite a few people have the Acme Transmogrifier, and you've had to
-write something to talk the protocol from scratch - you'd almost
-certainly want to make that into a module. The level at which you pitch
-it is up to you: you might want protocol-level modules analogous to
-L<Net::SMTP|Net::SMTP> which then talk to higher level modules analogous
-to L<Mail::Send|Mail::Send>. The choice is yours, but you do want to get
-a module out for that server protocol.
-
-Nobody else on the planet is going to talk your local data format, so we
-can ignore that. But what about the thing in the middle? Building tree
-structures from Perl variables and then traversing them is a nice,
-general problem, and if nobody's already written a module that does
-that, you might want to modularise that code too.
-
-So hopefully you've now got a few ideas about what's good to modularise.
-Let's now see how it's done.
-
-=head2 Step-by-step: Preparing the ground
-
-Before we even start scraping out the code, there are a few things we'll
-want to do in advance.
-
-=over 3
-
-=item Look around
-
-Dig into a bunch of modules to see how they're written. I'd suggest
-starting with L<Text::Tabs|Text::Tabs>, since it's in the standard
-library and is nice and simple, and then looking at something a little
-more complex like L<File::Copy|File::Copy>. For object oriented
-code, C<WWW::Mechanize> or the C<Email::*> modules provide some good
-examples.
-
-These should give you an overall feel for how modules are laid out and
-written.
-
-=item Check it's new
-
-There are a lot of modules on CPAN, and it's easy to miss one that's
-similar to what you're planning on contributing. Have a good plough
-through the L<http://search.cpan.org> and make sure you're not the one
-reinventing the wheel!
-
-=item Discuss the need
-
-You might love it. You might feel that everyone else needs it. But there
-might not actually be any real demand for it out there. If you're unsure
-about the demand your module will have, consider sending out feelers
-on the C<comp.lang.perl.modules> newsgroup, or as a last resort, ask the
-modules list at C<modules@perl.org>. Remember that this is a closed list
-with a very long turn-around time - be prepared to wait a good while for
-a response from them.
-
-=item Choose a name
-
-Perl modules included on CPAN have a naming hierarchy you should try to
-fit in with. See L<perlmodlib> for more details on how this works, and
-browse around CPAN and the modules list to get a feel of it. At the very
-least, remember this: modules should be title capitalised, (This::Thing)
-fit in with a category, and explain their purpose succinctly.
-
-=item Check again
-
-While you're doing that, make really sure you haven't missed a module
-similar to the one you're about to write.
-
-When you've got your name sorted out and you're sure that your module is
-wanted and not currently available, it's time to start coding.
-
-=back
-
-=head2 Step-by-step: Making the module
-
-=over 3
-
-=item Start with F<module-starter> or F<h2xs>
-
-The F<module-starter> utility is distributed as part of the
-L<Module::Starter|Module::Starter> CPAN package. It creates a directory
-with stubs of all the necessary files to start a new module, according
-to recent "best practice" for module development, and is invoked from
-the command line, thus:
-
- module-starter --module=Foo::Bar \
- --author="Your Name" --email=yourname@cpan.org
-
-If you do not wish to install the L<Module::Starter|Module::Starter>
-package from CPAN, F<h2xs> is an older tool, originally intended for the
-development of XS modules, which comes packaged with the Perl
-distribution.
-
-A typical invocation of L<h2xs|h2xs> for a pure Perl module is:
-
- h2xs -AX --skip-exporter --use-new-tests -n Foo::Bar
-
-The C<-A> omits the Autoloader code, C<-X> omits XS elements,
-C<--skip-exporter> omits the Exporter code, C<--use-new-tests> sets up a
-modern testing environment, and C<-n> specifies the name of the module.
-
-=item Use L<strict|strict> and L<warnings|warnings>
-
-A module's code has to be warning and strict-clean, since you can't
-guarantee the conditions that it'll be used under. Besides, you wouldn't
-want to distribute code that wasn't warning or strict-clean anyway,
-right?
-
-=item Use L<Carp|Carp>
-
-The L<Carp|Carp> module allows you to present your error messages from
-the caller's perspective; this gives you a way to signal a problem with
-the caller and not your module. For instance, if you say this:
-
- warn "No hostname given";
-
-the user will see something like this:
-
- No hostname given at /usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm
- line 123.
-
-which looks like your module is doing something wrong. Instead, you want
-to put the blame on the user, and say this:
-
- No hostname given at bad_code, line 10.
-
-You do this by using L<Carp|Carp> and replacing your C<warn>s with
-C<carp>s. If you need to C<die>, say C<croak> instead. However, keep
-C<warn> and C<die> in place for your sanity checks - where it really is
-your module at fault.
-
-=item Use L<Exporter|Exporter> - wisely!
-
-L<Exporter|Exporter> gives you a standard way of exporting symbols and
-subroutines from your module into the caller's namespace. For instance,
-saying C<use Net::Acme qw(&frob)> would import the C<frob> subroutine.
-
-The package variable C<@EXPORT> will determine which symbols will get
-exported when the caller simply says C<use Net::Acme> - you will hardly
-ever want to put anything in there. C<@EXPORT_OK>, on the other hand,
-specifies which symbols you're willing to export. If you do want to
-export a bunch of symbols, use the C<%EXPORT_TAGS> and define a standard
-export set - look at L<Exporter> for more details.
-
-=item Use L<plain old documentation|perlpod>
-
-The work isn't over until the paperwork is done, and you're going to
-need to put in some time writing some documentation for your module.
-C<module-starter> or C<h2xs> will provide a stub for you to fill in; if
-you're not sure about the format, look at L<perlpod> for an
-introduction. Provide a good synopsis of how your module is used in
-code, a description, and then notes on the syntax and function of the
-individual subroutines or methods. Use Perl comments for developer notes
-and POD for end-user notes.
-
-=item Write tests
-
-You're encouraged to create self-tests for your module to ensure it's
-working as intended on the myriad platforms Perl supports; if you upload
-your module to CPAN, a host of testers will build your module and send
-you the results of the tests. Again, C<module-starter> and C<h2xs>
-provide a test framework which you can extend - you should do something
-more than just checking your module will compile.
-L<Test::Simple|Test::Simple> and L<Test::More|Test::More> are good
-places to start when writing a test suite.
-
-=item Write the README
-
-If you're uploading to CPAN, the automated gremlins will extract the
-README file and place that in your CPAN directory. It'll also appear in
-the main F<by-module> and F<by-category> directories if you make it onto
-the modules list. It's a good idea to put here what the module actually
-does in detail, and the user-visible changes since the last release.
-
-=back
-
-=head2 Step-by-step: Distributing your module
-
-=over 3
-
-=item Get a CPAN user ID
-
-Every developer publishing modules on CPAN needs a CPAN ID. Visit
-C<http://pause.perl.org/>, select "Request PAUSE Account", and wait for
-your request to be approved by the PAUSE administrators.
-
-=item C<perl Makefile.PL; make test; make dist>
-
-Once again, C<module-starter> or C<h2xs> has done all the work for you.
-They produce the standard C<Makefile.PL> you see when you download and
-install modules, and this produces a Makefile with a C<dist> target.
-
-Once you've ensured that your module passes its own tests - always a
-good thing to make sure - you can C<make dist>, and the Makefile will
-hopefully produce you a nice tarball of your module, ready for upload.
-
-=item Upload the tarball
-
-The email you got when you received your CPAN ID will tell you how to
-log in to PAUSE, the Perl Authors Upload SErver. From the menus there,
-you can upload your module to CPAN.
-
-=item Announce to the modules list
-
-Once uploaded, it'll sit unnoticed in your author directory. If you want
-it connected to the rest of the CPAN, you'll need to go to "Register
-Namespace" on PAUSE. Once registered, your module will appear in the
-by-module and by-category listings on CPAN.
-
-=item Announce to clpa
-
-If you have a burning desire to tell the world about your release, post
-an announcement to the moderated C<comp.lang.perl.announce> newsgroup.
-
-=item Fix bugs!
-
-Once you start accumulating users, they'll send you bug reports. If
-you're lucky, they'll even send you patches. Welcome to the joys of
-maintaining a software project...
-
-=back
-
-=head1 AUTHOR
-
-Simon Cozens, C<simon@cpan.org>
-
-Updated by Kirrily "Skud" Robert, C<skud@cpan.org>
-
-=head1 SEE ALSO
-
-L<perlmod>, L<perlmodlib>, L<perlmodinstall>, L<h2xs>, L<strict>,
-L<Carp>, L<Exporter>, L<perlpod>, L<Test::Simple>, L<Test::More>
-L<ExtUtils::MakeMaker>, L<Module::Build>, L<Module::Starter>
-http://www.cpan.org/ , Ken Williams's tutorial on building your own
-module at http://mathforum.org/~ken/perl_modules.html
diff --git a/Master/tlpkg/tlperl/lib/pods/perlnumber.pod b/Master/tlpkg/tlperl/lib/pods/perlnumber.pod
deleted file mode 100644
index ffe3ed5b432..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlnumber.pod
+++ /dev/null
@@ -1,209 +0,0 @@
-=head1 NAME
-
-perlnumber - semantics of numbers and numeric operations in Perl
-
-=head1 SYNOPSIS
-
- $n = 1234; # decimal integer
- $n = 0b1110011; # binary integer
- $n = 01234; # octal integer
- $n = 0x1234; # hexadecimal integer
- $n = 12.34e-56; # exponential notation
- $n = "-12.34e56"; # number specified as a string
- $n = "1234"; # number specified as a string
-
-=head1 DESCRIPTION
-
-This document describes how Perl internally handles numeric values.
-
-Perl's operator overloading facility is completely ignored here. Operator
-overloading allows user-defined behaviors for numbers, such as operations
-over arbitrarily large integers, floating points numbers with arbitrary
-precision, operations over "exotic" numbers such as modular arithmetic or
-p-adic arithmetic, and so on. See L<overload> for details.
-
-=head1 Storing numbers
-
-Perl can internally represent numbers in 3 different ways: as native
-integers, as native floating point numbers, and as decimal strings.
-Decimal strings may have an exponential notation part, as in C<"12.34e-56">.
-I<Native> here means "a format supported by the C compiler which was used
-to build perl".
-
-The term "native" does not mean quite as much when we talk about native
-integers, as it does when native floating point numbers are involved.
-The only implication of the term "native" on integers is that the limits for
-the maximal and the minimal supported true integral quantities are close to
-powers of 2. However, "native" floats have a most fundamental
-restriction: they may represent only those numbers which have a relatively
-"short" representation when converted to a binary fraction. For example,
-0.9 cannot be represented by a native float, since the binary fraction
-for 0.9 is infinite:
-
- binary0.1110011001100...
-
-with the sequence C<1100> repeating again and again. In addition to this
-limitation, the exponent of the binary number is also restricted when it
-is represented as a floating point number. On typical hardware, floating
-point values can store numbers with up to 53 binary digits, and with binary
-exponents between -1024 and 1024. In decimal representation this is close
-to 16 decimal digits and decimal exponents in the range of -304..304.
-The upshot of all this is that Perl cannot store a number like
-12345678901234567 as a floating point number on such architectures without
-loss of information.
-
-Similarly, decimal strings can represent only those numbers which have a
-finite decimal expansion. Being strings, and thus of arbitrary length, there
-is no practical limit for the exponent or number of decimal digits for these
-numbers. (But realize that what we are discussing the rules for just the
-I<storage> of these numbers. The fact that you can store such "large" numbers
-does not mean that the I<operations> over these numbers will use all
-of the significant digits.
-See L<"Numeric operators and numeric conversions"> for details.)
-
-In fact numbers stored in the native integer format may be stored either
-in the signed native form, or in the unsigned native form. Thus the limits
-for Perl numbers stored as native integers would typically be -2**31..2**32-1,
-with appropriate modifications in the case of 64-bit integers. Again, this
-does not mean that Perl can do operations only over integers in this range:
-it is possible to store many more integers in floating point format.
-
-Summing up, Perl numeric values can store only those numbers which have
-a finite decimal expansion or a "short" binary expansion.
-
-=head1 Numeric operators and numeric conversions
-
-As mentioned earlier, Perl can store a number in any one of three formats,
-but most operators typically understand only one of those formats. When
-a numeric value is passed as an argument to such an operator, it will be
-converted to the format understood by the operator.
-
-Six such conversions are possible:
-
- native integer --> native floating point (*)
- native integer --> decimal string
- native floating_point --> native integer (*)
- native floating_point --> decimal string (*)
- decimal string --> native integer
- decimal string --> native floating point (*)
-
-These conversions are governed by the following general rules:
-
-=over 4
-
-=item *
-
-If the source number can be represented in the target form, that
-representation is used.
-
-=item *
-
-If the source number is outside of the limits representable in the target form,
-a representation of the closest limit is used. (I<Loss of information>)
-
-=item *
-
-If the source number is between two numbers representable in the target form,
-a representation of one of these numbers is used. (I<Loss of information>)
-
-=item *
-
-In C<< native floating point --> native integer >> conversions the magnitude
-of the result is less than or equal to the magnitude of the source.
-(I<"Rounding to zero".>)
-
-=item *
-
-If the C<< decimal string --> native integer >> conversion cannot be done
-without loss of information, the result is compatible with the conversion
-sequence C<< decimal_string --> native_floating_point --> native_integer >>.
-In particular, rounding is strongly biased to 0, though a number like
-C<"0.99999999999999999999"> has a chance of being rounded to 1.
-
-=back
-
-B<RESTRICTION>: The conversions marked with C<(*)> above involve steps
-performed by the C compiler. In particular, bugs/features of the compiler
-used may lead to breakage of some of the above rules.
-
-=head1 Flavors of Perl numeric operations
-
-Perl operations which take a numeric argument treat that argument in one
-of four different ways: they may force it to one of the integer/floating/
-string formats, or they may behave differently depending on the format of
-the operand. Forcing a numeric value to a particular format does not
-change the number stored in the value.
-
-All the operators which need an argument in the integer format treat the
-argument as in modular arithmetic, e.g., C<mod 2**32> on a 32-bit
-architecture. C<sprintf "%u", -1> therefore provides the same result as
-C<sprintf "%u", ~0>.
-
-=over 4
-
-=item Arithmetic operators
-
-The binary operators C<+> C<-> C<*> C</> C<%> C<==> C<!=> C<E<gt>> C<E<lt>>
-C<E<gt>=> C<E<lt>=> and the unary operators C<-> C<abs> and C<--> will
-attempt to convert arguments to integers. If both conversions are possible
-without loss of precision, and the operation can be performed without
-loss of precision then the integer result is used. Otherwise arguments are
-converted to floating point format and the floating point result is used.
-The caching of conversions (as described above) means that the integer
-conversion does not throw away fractional parts on floating point numbers.
-
-=item ++
-
-C<++> behaves as the other operators above, except that if it is a string
-matching the format C</^[a-zA-Z]*[0-9]*\z/> the string increment described
-in L<perlop> is used.
-
-=item Arithmetic operators during C<use integer>
-
-In scopes where C<use integer;> is in force, nearly all the operators listed
-above will force their argument(s) into integer format, and return an integer
-result. The exceptions, C<abs>, C<++> and C<-->, do not change their
-behavior with C<use integer;>
-
-=item Other mathematical operators
-
-Operators such as C<**>, C<sin> and C<exp> force arguments to floating point
-format.
-
-=item Bitwise operators
-
-Arguments are forced into the integer format if not strings.
-
-=item Bitwise operators during C<use integer>
-
-forces arguments to integer format. Also shift operations internally use
-signed integers rather than the default unsigned.
-
-=item Operators which expect an integer
-
-force the argument into the integer format. This is applicable
-to the third and fourth arguments of C<sysread>, for example.
-
-=item Operators which expect a string
-
-force the argument into the string format. For example, this is
-applicable to C<printf "%s", $value>.
-
-=back
-
-Though forcing an argument into a particular form does not change the
-stored number, Perl remembers the result of such conversions. In
-particular, though the first such conversion may be time-consuming,
-repeated operations will not need to redo the conversion.
-
-=head1 AUTHOR
-
-Ilya Zakharevich C<ilya@math.ohio-state.edu>
-
-Editorial adjustments by Gurusamy Sarathy <gsar@ActiveState.com>
-
-Updates for 5.8.0 by Nicholas Clark <nick@ccl4.org>
-
-=head1 SEE ALSO
-
-L<overload>, L<perlop>
diff --git a/Master/tlpkg/tlperl/lib/pods/perlobj.pod b/Master/tlpkg/tlperl/lib/pods/perlobj.pod
deleted file mode 100644
index 015b1c966c0..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlobj.pod
+++ /dev/null
@@ -1,1049 +0,0 @@
-=encoding utf8
-
-=for comment
-Consistent formatting of this file is achieved with:
- perl ./Porting/podtidy pod/perlobj.pod
-
-=head1 NAME
-X<object> X<OOP>
-
-perlobj - Perl object reference
-
-=head1 DESCRIPTION
-
-This document provides a reference for Perl's object orientation
-features. If you're looking for an introduction to object-oriented
-programming in Perl, please see L<perlootut>.
-
-In order to understand Perl objects, you first need to understand
-references in Perl. See L<perlref> for details.
-
-This document describes all of Perl's object-oriented (OO) features
-from the ground up. If you're just looking to write some
-object-oriented code of your own, you are probably better served by
-using one of the object systems from CPAN described in L<perlootut>.
-
-If you're looking to write your own object system, or you need to
-maintain code which implements objects from scratch then this document
-will help you understand exactly how Perl does object orientation.
-
-There are a few basic principles which define object oriented Perl:
-
-=over 4
-
-=item 1.
-
-An object is simply a data structure that knows to which class it
-belongs.
-
-=item 2.
-
-A class is simply a package. A class provides methods that expect to
-operate on objects.
-
-=item 3.
-
-A method is simply a subroutine that expects a reference to an object
-(or a package name, for class methods) as the first argument.
-
-=back
-
-Let's look at each of these principles in depth.
-
-=head2 An Object is Simply a Data Structure
-X<object> X<bless> X<constructor> X<new>
-
-Unlike many other languages which support object orientation, Perl does
-not provide any special syntax for constructing an object. Objects are
-merely Perl data structures (hashes, arrays, scalars, filehandles,
-etc.) that have been explicitly associated with a particular class.
-
-That explicit association is created by the built-in C<bless> function,
-which is typically used within the I<constructor> subroutine of the
-class.
-
-Here is a simple constructor:
-
- package File;
-
- sub new {
- my $class = shift;
-
- return bless {}, $class;
- }
-
-The name C<new> isn't special. We could name our constructor something
-else:
-
- package File;
-
- sub load {
- my $class = shift;
-
- return bless {}, $class;
- }
-
-The modern convention for OO modules is to always use C<new> as the
-name for the constructor, but there is no requirement to do so. Any
-subroutine that blesses a data structure into a class is a valid
-constructor in Perl.
-
-In the previous examples, the C<{}> code creates a reference to an
-empty anonymous hash. The C<bless> function then takes that reference
-and associates the hash with the class in C<$class>. In the simplest
-case, the C<$class> variable will end up containing the string "File".
-
-We can also use a variable to store a reference to the data structure
-that is being blessed as our object:
-
- sub new {
- my $class = shift;
-
- my $self = {};
- bless $self, $class;
-
- return $self;
- }
-
-Once we've blessed the hash referred to by C<$self> we can start
-calling methods on it. This is useful if you want to put object
-initialization in its own separate method:
-
- sub new {
- my $class = shift;
-
- my $self = {};
- bless $self, $class;
-
- $self->_initialize();
-
- return $self;
- }
-
-Since the object is also a hash, you can treat it as one, using it to
-store data associated with the object. Typically, code inside the class
-can treat the hash as an accessible data structure, while code outside
-the class should always treat the object as opaque. This is called
-B<encapsulation>. Encapsulation means that the user of an object does
-not have to know how it is implemented. The user simply calls
-documented methods on the object.
-
-Note, however, that (unlike most other OO languages) Perl does not
-ensure or enforce encapsulation in any way. If you want objects to
-actually I<be> opaque you need to arrange for that yourself. This can
-be done in a varierty of ways, including using L<"Inside-Out objects">
-or modules from CPAN.
-
-=head3 Objects Are Blessed; Variables Are Not
-
-When we bless something, we are not blessing the variable which
-contains a reference to that thing, nor are we blessing the reference
-that the variable stores; we are blessing the thing that the variable
-refers to (sometimes known as the I<referent>). This is best
-demonstrated with this code:
-
- use Scalar::Util 'blessed';
-
- my $foo = {};
- my $bar = $foo;
-
- bless $foo, 'Class';
- print blessed( $bar ); # prints "Class"
-
- $bar = "some other value";
- print blessed( $bar ); # prints undef
-
-When we call C<bless> on a variable, we are actually blessing the
-underlying data structure that the variable refers to. We are not
-blessing the reference itself, nor the variable that contains that
-reference. That's why the second call to C<blessed( $bar )> returns
-false. At that point C<$bar> is no longer storing a reference to an
-object.
-
-You will sometimes see older books or documentation mention "blessing a
-reference" or describe an object as a "blessed reference", but this is
-incorrect. It isn't the reference that is blessed as an object; it's
-the thing the reference refers to (i.e. the referent).
-
-=head2 A Class is Simply a Package
-X<class> X<package> X<@ISA> X<inheritance>
-
-Perl does not provide any special syntax for class definitions. A
-package is simply a namespace containing variables and subroutines. The
-only difference is that in a class, the subroutines may expect a
-reference to an object or the name of a class as the first argument.
-This is purely a matter of convention, so a class may contain both
-methods and subroutines which I<don't> operate on an object or class.
-
-Each package contains a special array called C<@ISA>. The C<@ISA> array
-contains a list of that class's parent classes, if any. This array is
-examined when Perl does method resolution, which we will cover later.
-
-It is possible to manually set C<@ISA>, and you may see this in older
-Perl code. Much older code also uses the L<base> pragma. For new code,
-we recommend that you use the L<parent> pragma to declare your parents.
-This pragma will take care of setting C<@ISA>. It will also load the
-parent classes and make sure that the package doesn't inherit from
-itself.
-
-However the parent classes are set, the package's C<@ISA> variable will
-contain a list of those parents. This is simply a list of scalars, each
-of which is a string that corresponds to a package name.
-
-All classes inherit from the L<UNIVERSAL> class implicitly. The
-L<UNIVERSAL> class is implemented by the Perl core, and provides
-several default methods, such as C<isa()>, C<can()>, and C<VERSION()>.
-The C<UNIVERSAL> class will I<never> appear in a package's C<@ISA>
-variable.
-
-Perl I<only> provides method inheritance as a built-in feature.
-Attribute inheritance is left up the class to implement. See the
-L</Writing Accessors> section for details.
-
-=head2 A Method is Simply a Subroutine
-X<method>
-
-Perl does not provide any special syntax for defining a method. A
-method is simply a regular subroutine, and is declared with C<sub>.
-What makes a method special is that it expects to receive either an
-object or a class name as its first argument.
-
-Perl I<does> provide special syntax for method invocation, the C<< ->
->> operator. We will cover this in more detail later.
-
-Most methods you write will expect to operate on objects:
-
- sub save {
- my $self = shift;
-
- open my $fh, '>', $self->path() or die $!;
- print {$fh} $self->data() or die $!;
- close $fh or die $!;
- }
-
-=head2 Method Invocation
-X<invocation> X<method> X<arrow> X<< -> >>
-
-Calling a method on an object is written as C<< $object->method >>.
-
-The left hand side of the method invocation (or arrow) operator is the
-object (or class name), and the right hand side is the method name.
-
- my $pod = File->new( 'perlobj.pod', $data );
- $pod->save();
-
-The C<< -> >> syntax is also used when dereferencing a reference. It
-looks like the same operator, but these are two different operations.
-
-When you call a method, the thing on the left side of the arrow is
-passed as the first argument to the method. That means when we call C<<
-Critter->new() >>, the C<new()> method receives the string C<"Critter">
-as its first argument. When we call C<< $fred->speak() >>, the C<$fred>
-variable is passed as the first argument to C<speak()>.
-
-Just as with any Perl subroutine, all of the arguments passed in C<@_>
-are aliases to the original argument. This includes the object itself.
-If you assign directly to C<$_[0]> you will change the contents of the
-variable that holds the reference to the object. We recommend that you
-don't do this unless you know exactly what you're doing.
-
-Perl knows what package the method is in by looking at the left side of
-the arrow. If the left hand side is a package name, it looks for the
-method in that package. If the left hand side is an object, then Perl
-looks for the method in the package that the object has been blessed
-into.
-
-If the left hand side is neither a package name nor an object, then the
-method call will cause an error, but see the section on L</Method Call
-Variations> for more nuances.
-
-=head2 Inheritance
-X<inheritance>
-
-We already talked about the special C<@ISA> array and the L<parent>
-pragma.
-
-When a class inherits from another class, any methods defined in the
-parent class are available to the child class. If you attempt to call a
-method on an object that isn't defined in its own class, Perl will also
-look for that method in any parent classes it may have.
-
- package File::MP3;
- use parent 'File'; # sets @File::MP3::ISA = ('File');
-
- my $mp3 = File::MP3->new( 'Andvari.mp3', $data );
- $mp3->save();
-
-Since we didn't define a C<save()> method in the C<File::MP3> class,
-Perl will look at the C<File::MP3> class's parent classes to find the
-C<save()> method. If Perl cannot find a C<save()> method anywhere in
-the inheritance hierarchy, it will die.
-
-In this case, it finds a C<save()> method in the C<File> class. Note
-that the object passed to C<save()> in this case is still a
-C<File::MP3> object, even though the method is found in the C<File>
-class.
-
-We can override a parent's method in a child class. When we do so, we
-can still call the parent class's method with the C<SUPER>
-pseudo-class.
-
- sub save {
- my $self = shift;
-
- say 'Prepare to rock';
- $self->SUPER::save();
- }
-
-The C<SUPER> modifier can I<only> be used for method calls. You can't
-use it for regular subroutine calls or class methods:
-
- SUPER::save($thing); # FAIL: looks for save() sub in package SUPER
-
- SUPER->save($thing); # FAIL: looks for save() method in class
- # SUPER
-
- $thing->SUPER::save(); # Okay: looks for save() method in parent
- # classes
-
-
-=head3 How SUPER is Resolved
-X<SUPER>
-
-The C<SUPER> pseudo-class is resolved from the package where the call
-is made. It is I<not> resolved based on the object's class. This is
-important, because it lets methods at different levels within a deep
-inheritance hierarchy each correctly call their respective parent
-methods.
-
- package A;
-
- sub new {
- return bless {}, shift;
- }
-
- sub speak {
- my $self = shift;
-
- $self->SUPER::speak();
-
- say 'A';
- }
-
- package B;
-
- use parent 'A';
-
- sub speak {
- my $self = shift;
-
- $self->SUPER::speak();
-
- say 'B';
- }
-
- package C;
-
- use parent 'B';
-
- sub speak {
- my $self = shift;
-
- $self->SUPER::speak();
-
- say 'C';
- }
-
- my $c = C->new();
- $c->speak();
-
-In this example, we will get the following output:
-
- A
- B
- C
-
-This demonstrates how C<SUPER> is resolved. Even though the object is
-blessed into the C<C> class, the C<speak()> method in the C<B> class
-can still call C<SUPER::speak()> and expect it to correctly look in the
-parent class of C<B> (i.e the class the method call is in), not in the
-parent class of C<C> (i.e. the class the object belongs to).
-
-There are rare cases where this package-based resolution can be a
-problem. If you copy a subroutine from one package to another, C<SUPER>
-resolution will be done based on the original package.
-
-=head3 Multiple Inheritance
-X<multiple inheritance>
-
-Multiple inheritance often indicates a design problem, but Perl always
-gives you enough rope to hang yourself with if you ask for it.
-
-To declare multiple parents, you simply need to pass multiple class
-names to C<use parent>:
-
- package MultiChild;
-
- use parent 'Parent1', 'Parent2';
-
-=head3 Method Resolution Order
-X<method resolution order> X<mro>
-
-Method resolution order only matters in the case of multiple
-inheritance. In the case of single inheritance, Perl simply looks up
-the inheritance chain to find a method:
-
- Grandparent
- |
- Parent
- |
- Child
-
-If we call a method on a C<Child> object and that method is not defined
-in the C<Child> class, Perl will look for that method in the C<Parent>
-class and then, if necessary, in the C<Grandparent> class.
-
-If Perl cannot find the method in any of these classes, it will die
-with an error message.
-
-When a class has multiple parents, the method lookup order becomes more
-complicated.
-
-By default, Perl does a depth-first left-to-right search for a method.
-That means it starts with the first parent in the C<@ISA> array, and
-then searches all of its parents, grandparents, etc. If it fails to
-find the method, it then goes to the next parent in the original
-class's C<@ISA> array and searches from there.
-
- SharedGreatGrandParent
- / \
- PaternalGrandparent MaternalGrandparent
- \ /
- Father Mother
- \ /
- Child
-
-So given the diagram above, Perl will search C<Child>, C<Father>,
-C<PaternalGrandparent>, C<SharedGreatGrandParent>, C<Mother>, and
-finally C<MaternalGrandparent>. This may be a problem because now we're
-looking in C<SharedGreatGrandParent> I<before> we've checked all its
-derived classes (i.e. before we tried C<Mother> and
-C<MaternalGrandparent>).
-
-It is possible to ask for a different method resolution order with the
-L<mro> pragma.
-
- package Child;
-
- use mro 'c3';
- use parent 'Father', 'Mother';
-
-This pragma lets you switch to the "C3" resolution order. In simple
-terms, "C3" order ensures that shared parent classes are never searched
-before child classes, so Perl will now search: C<Child>, C<Father>,
-C<PaternalGrandparent>, C<Mother> C<MaternalGrandparent>, and finally
-C<SharedGreatGrandParent>. Note however that this is not
-"breadth-first" searching: All the C<Father> ancestors (except the
-common ancestor) are searched before any of the C<Mother> ancestors are
-considered.
-
-The C3 order also lets you call methods in sibling classes with the
-C<next> pseudo-class. See the L<mro> documentation for more details on
-this feature.
-
-=head3 Method Resolution Caching
-
-When Perl searches for a method, it caches the lookup so that future
-calls to the method do not need to search for it again. Changing a
-class's parent class or adding subroutines to a class will invalidate
-the cache for that class.
-
-The L<mro> pragma provides some functions for manipulating the method
-cache directly.
-
-=head2 Writing Constructors
-X<constructor>
-
-As we mentioned earlier, Perl provides no special constructor syntax.
-This means that a class must implement its own constructor. A
-constructor is simply a class method that returns a reference to a new
-object.
-
-The constructor can also accept additional parameters that define the
-object. Let's write a real constructor for the C<File> class we used
-earlier:
-
- package File;
-
- sub new {
- my $class = shift;
- my ( $path, $data ) = @_;
-
- my $self = bless {
- path => $path,
- data => $data,
- }, $class;
-
- return $self;
- }
-
-As you can see, we've stored the path and file data in the object
-itself. Remember, under the hood, this object is still just a hash.
-Later, we'll write accessors to manipulate this data.
-
-For our File::MP3 class, we can check to make sure that the path we're
-given ends with ".mp3":
-
- package File::MP3;
-
- sub new {
- my $class = shift;
- my ( $path, $data ) = @_;
-
- die "You cannot create a File::MP3 without an mp3 extension\n"
- unless $path =~ /\.mp3\z/;
-
- return $class->SUPER::new(@_);
- }
-
-This constructor lets its parent class do the actual object
-construction.
-
-=head2 Attributes
-X<attribute>
-
-An attribute is a piece of data belonging to a particular object.
-Unlike most object-oriented languages, Perl provides no special syntax
-or support for declaring and manipulating attributes.
-
-Attributes are often stored in the object itself. For example, if the
-object is an anonymous hash, we can store the attribute values in the
-hash using the attribute name as the key.
-
-While it's possible to refer directly to these hash keys outside of the
-class, it's considered a best practice to wrap all access to the
-attribute with accessor methods.
-
-This has several advantages. Accessors make it easier to change the
-implementation of an object later while still preserving the original
-API.
-
-An accessor lets you add additional code around attribute access. For
-example, you could apply a default to an attribute that wasn't set in
-the constructor, or you could validate that a new value for the
-attribute is acceptable.
-
-Finally, using accessors makes inheritance much simpler. Subclasses can
-use the accessors rather than having to know how a parent class is
-implemented internally.
-
-=head3 Writing Accessors
-X<accessor>
-
-As with constructors, Perl provides no special accessor declaration
-syntax, so classes must provide explicitly written accessor methods.
-There are two common types of accessors, read-only and read-write.
-
-A simple read-only accessor simply gets the value of a single
-attribute:
-
- sub path {
- my $self = shift;
-
- return $self->{path};
- }
-
-A read-write accessor will allow the caller to set the value as well as
-get it:
-
- sub path {
- my $self = shift;
-
- if (@_) {
- $self->{path} = shift;
- }
-
- return $self->{path};
- }
-
-=head2 An Aside About Smarter and Safer Code
-
-Our constructor and accessors are not very smart. They don't check that
-a C<$path> is defined, nor do they check that a C<$path> is a valid
-filesystem path.
-
-Doing these checks by hand can quickly become tedious. Writing a bunch
-of accessors by hand is also incredibly tedious. There are a lot of
-modules on CPAN that can help you write safer and more concise code,
-including the modules we recommend in L<perlootut>.
-
-=head2 Method Call Variations
-X<method>
-
-Perl supports several other ways to call methods besides the C<<
-$object->method() >> usage we've seen so far.
-
-=head3 Method Names as Strings
-
-Perl lets you use a scalar variable containing a string as a method
-name:
-
- my $file = File->new( $path, $data );
-
- my $method = 'save';
- $file->$method();
-
-This works exactly like calling C<< $file->save() >>. This can be very
-useful for writing dynamic code. For example, it allows you to pass a
-method name to be called as a parameter to another method.
-
-=head3 Class Names as Strings
-
-Perl also lets you use a scalar containing a string as a class name:
-
- my $class = 'File';
-
- my $file = $class->new( $path, $data );
-
-Again, this allows for very dynamic code.
-
-=head3 Subroutine References as Methods
-
-You can also use a subroutine reference as a method:
-
- my $sub = sub {
- my $self = shift;
-
- $self->save();
- };
-
- $file->$sub();
-
-This is exactly equivalent to writing C<< $sub->($file) >>. You may see
-this idiom in the wild combined with a call to C<can>:
-
- if ( my $meth = $object->can('foo') ) {
- $object->$meth();
- }
-
-=head3 Deferencing Method Call
-
-Perl also lets you use a dereferenced scalar reference in a method
-call. That's a mouthful, so let's look at some code:
-
- $file->${ \'save' };
- $file->${ returns_scalar_ref() };
- $file->${ \( returns_scalar() ) };
- $file->${ returns_sub_ref() };
-
-This works if the dereference produces a string I<or> a subroutine
-reference.
-
-=head3 Method Calls on Filehandles
-
-Under the hood, Perl filehandles are instances of the C<IO::Handle> or
-C<IO::File> class. Once you have an open filehandle, you can call
-methods on it. Additionally, you can call methods on the C<STDIN>,
-C<STDOUT>, and C<STDERR> filehandles.
-
- open my $fh, '>', 'path/to/file';
- $fh->autoflush();
- $fh->print('content');
-
- STDOUT->autoflush();
-
-=head2 Invoking Class Methods
-X<invocation>
-
-Because Perl allows you to use barewords for package names and
-subroutine names, it sometimes interprets a bareword's meaning
-incorrectly. For example, the construct C<< Class->new() >> can be
-interpreted as either C<< 'Class'->new() >> or C<< Class()->new() >>.
-In English, that second interpretation reads as "call a subroutine
-named Class(), then call new() as a method on the return value of
-Class()". If there is a subroutine named C<Class()> in the current
-namespace, Perl will always interpret C<< Class->new() >> as the second
-alternative: a call to C<new()> on the object returned by a call to
-C<Class()>
-
-You can force Perl to use the first interpretation (i.e. as a method
-call on the class named "Class") in two ways. First, you can append a
-C<::> to the class name:
-
- Class::->new()
-
-Perl will always interpret this as a method call.
-
-Alternatively, you can quote the class name:
-
- 'Class'->new()
-
-Of course, if the class name is in a scalar Perl will do the right
-thing as well:
-
- my $class = 'Class';
- $class->new();
-
-=head3 Indirect Object Syntax
-X<indirect object>
-
-B<Outside of the file handle case, use of this syntax is discouraged,
-as it can confuse the Perl interpreter. See below for more details.>
-
-Perl suports another method invocation syntax called "indirect object"
-notation. This syntax is called "indirect" because the method comes
-before the object it is being invoked on.
-
-This syntax can be used with any class or object method:
-
- my $file = new File $path, $data;
- save $file;
-
-We recommend that you avoid this syntax, for several reasons.
-
-First, it can be confusing to read. In the above example, it's not
-clear if C<save> is a method provided by the C<File> class or simply a
-subroutine that expects a file object as its first argument.
-
-When used with class methods, the problem is even worse. Because Perl
-allows subroutine names to be written as barewords, Perl has to guess
-whether the bareword after the method is a class name or subroutine
-name. In other words, Perl can resolve the syntax as either C<<
-File->new( $path, $data ) >> B<or> C<< new( File( $path, $data ) ) >>.
-
-To parse this code, Perl uses a heuristic based on what package names
-it has seen, what subroutines exist in the current package, what
-barewords it has previously seen, and other input. Needless to say,
-heuristics can produce very surprising results!
-
-Older documentation (and some CPAN modules) encouraged this syntax,
-particularly for constructors, so you may still find it in the wild.
-However, we encourage you to avoid using it in new code.
-
-You can force Perl to interpret the bareword as a class name by
-appending "::" to it, like we saw earlier:
-
- my $file = new File:: $path, $data;
-
-=head2 C<bless>, C<blessed>, and C<ref>
-
-As we saw earlier, an object is simply a data structure that has been
-blessed into a class via the C<bless> function. The C<bless> function
-can take either one or two arguments:
-
- my $object = bless {}, $class;
- my $object = bless {};
-
-In the first form, the anonymous hash is being blessed into the class
-in C<$class>. In the second form, the anonymous hash is blessed into
-the current package.
-
-The second form is strongly discouraged, because it breaks the ability
-of a subclass to reuse the parent's constructor, but you may still run
-across it in existing code.
-
-If you want to know whether a particular scalar refers to an object,
-you can use the C<blessed> function exported by L<Scalar::Util>, which
-is shipped with the Perl core.
-
- use Scalar::Util 'blessed';
-
- if ( defined blessed($thing) ) { ... }
-
-If C<$thing> refers to an object, then this function returns the name
-of the package the object has been blessed into. If C<$thing> doesn't
-contain a reference to a blessed object, the C<blessed> function
-returns C<undef>.
-
-Note that C<blessed($thing)> will also return false if C<$thing> has
-been blessed into a class named "0". This is a possible, but quite
-pathological. Don't create a class named "0" unless you know what
-you're doing.
-
-Similarly, Perl's built-in C<ref> function treats a reference to a
-blessed object specially. If you call C<ref($thing)> and C<$thing>
-holds a reference to an object, it will return the name of the class
-that the object has been blessed into.
-
-If you simply want to check that a variable contains an object
-reference, we recommend that you use C<defined blessed($object)>, since
-C<ref> returns true values for all references, not just objects.
-
-=head2 The UNIVERSAL Class
-X<UNIVERSAL>
-
-All classes automatically inherit from the L<UNIVERSAL> class, which is
-built-in to the Perl core. This class provides a number of methods, all
-of which can be called on either a class or an object. You can also
-choose to override some of these methods in your class. If you do so,
-we recommend that you follow the built-in semantics described below.
-
-=over 4
-
-=item isa($class)
-X<isa>
-
-The C<isa> method returns I<true> if the object is a member of the
-class in C<$class>, or a member of a subclass of C<$class>.
-
-If you override this method, it should never throw an exception.
-
-=item DOES($role)
-X<DOES>
-
-The C<DOES> method returns I<true> if its object claims to perform the
-role C<$role>. By default, this is equivalent to C<isa>. This method is
-provided for use by object system extensions that implement roles, like
-C<Moose> and C<Role::Tiny>.
-
-You can also override C<DOES> directly in your own classes. If you
-override this method, it should never throw an exception.
-
-=item can($method)
-X<can>
-
-The C<can> method checks to see if the class or object it was called on
-has a method named C<$method>. This checks for the method in the class
-and all of its parents. If the method exists, then a reference to the
-subroutine is returned. If it does not then C<undef> is returned.
-
-If your class responds to method calls via C<AUTOLOAD>, you may want to
-overload C<can> to return a subroutine reference for methods which your
-C<AUTOLOAD> method handles.
-
-If you override this method, it should never throw an exception.
-
-=item VERSION($need)
-X<VERSION>
-
-The C<VERSION> method returns the version number of the class
-(package).
-
-If the C<$need> argument is given then it will check that the current
-version (as defined by the $VERSION variable in the package) is greater
-than or equal to C<$need>; it will die if this is not the case. This
-method is called automatically by the C<VERSION> form of C<use>.
-
- use Package 1.2 qw(some imported subs);
- # implies:
- Package->VERSION(1.2);
-
-We recommend that you use this method to access another package's
-version, rather than looking directly at C<$Package::VERSION>. The
-package you are looking at could have overridden the C<VERSION> method.
-
-We also recommend using this method to check whether a module has a
-sufficient version. The internal implementation uses the L<version>
-module to make sure that different types of version numbers are
-compared correctly.
-
-=back
-
-=head2 AUTOLOAD
-X<AUTOLOAD>
-
-If you call a method that doesn't exist in a class, Perl will throw an
-error. However, if that class or any of its parent classes defines an
-C<AUTOLOAD> method, that C<AUTOLOAD> method is called instead.
-
-C<AUTOLOAD> is called as a regular method, and the caller will not know
-the difference. Whatever value your C<AUTOLOAD> method returns is
-returned to the caller.
-
-The fully qualified method name that was called is available in the
-C<$AUTOLOAD> package global for your class. Since this is a global, if
-you want to refer to do it without a package name prefix under C<strict
-'vars'>, you need to declare it.
-
- # XXX - this is a terrible way to implement accessors, but it makes
- # for a simple example.
- our $AUTOLOAD;
- sub AUTOLOAD {
- my $self = shift;
-
- # Remove qualifier from original method name...
- my $called = $AUTOLOAD =~ s/.*:://r;
-
- # Is there an attribute of that name?
- die "No such attribute: $called"
- unless exists $self->{$called};
-
- # If so, return it...
- return $self->{$called};
- }
-
- sub DESTROY { } # see below
-
-Without the C<our $AUTOLOAD> declaration, this code will not compile
-under the L<strict> pragma.
-
-As the comment says, this is not a good way to implement accessors.
-It's slow and too clever by far. However, you may see this as a way to
-provide accessors in older Perl code. See L<perlootut> for
-recommendations on OO coding in Perl.
-
-If your class does have an C<AUTOLOAD> method, we strongly recommend
-that you override C<can> in your class as well. Your overridden C<can>
-method should return a subroutine reference for any method that your
-C<AUTOLOAD> responds to.
-
-=head2 Destructors
-X<destructor> X<DESTROY>
-
-When the last reference to an object goes away, the object is
-destroyed. If you only have one reference to an object stored in a
-lexical scalar, the object is destroyed when that scalar goes out of
-scope. If you store the object in a package global, that object may not
-go out of scope until the program exits.
-
-If you want to do something when the object is destroyed, you can
-define a C<DESTROY> method in your class. This method will always be
-called by Perl at the appropriate time, unless the method is empty.
-
-This is called just like any other method, with the object as the first
-argument. It does not receive any additional arguments. However, the
-C<$_[0]> variable will be read-only in the destructor, so you cannot
-assign a value to it.
-
-If your C<DESTROY> method throws an error, this error will be ignored.
-It will not be sent to C<STDERR> and it will not cause the program to
-die. However, if your destructor is running inside an C<eval {}> block,
-then the error will change the value of C<$@>.
-
-Because C<DESTROY> methods can be called at any time, you should
-localize any global variables you might update in your C<DESTROY>. In
-particular, if you use C<eval {}> you should localize C<$@>, and if you
-use C<system> or backticks, you should localize C<$?>.
-
-If you define an C<AUTOLOAD> in your class, then Perl will call your
-C<AUTOLOAD> to handle the C<DESTROY> method. You can prevent this by
-defining an empty C<DESTROY>, like we did in the autoloading example.
-You can also check the value of C<$AUTOLOAD> and return without doing
-anything when called to handle C<DESTROY>.
-
-=head3 Global Destruction
-
-The order in which objects are destroyed during the global destruction
-before the program exits is unpredictable. This means that any objects
-contained by your object may already have been destroyed. You should
-check that a contained object is defined before calling a method on it:
-
- sub DESTROY {
- my $self = shift;
-
- $self->{handle}->close() if $self->{handle};
- }
-
-You can use the C<${^GLOBAL_PHASE}> variable to detect if you are
-currently in the global destruction phase:
-
- sub DESTROY {
- my $self = shift;
-
- return if ${^GLOBAL_PHASE} eq 'DESTRUCT';
-
- $self->{handle}->close();
- }
-
-Note that this variable was added in Perl 5.14.0. If you want to detect
-the global destruction phase on older versions of Perl, you can use the
-C<Devel::GlobalDestruction> module on CPAN.
-
-If your C<DESTROY> method issues a warning during global destruction,
-the Perl interpreter will append the string " during global
-destruction" the warning.
-
-During global destruction, Perl will always garbage collect objects
-before unblessed references. See L<perlhacktips/PERL_DESTRUCT_LEVEL>
-for more information about global destruction.
-
-=head2 Non-Hash Objects
-
-All the examples so far have shown objects based on a blessed hash.
-However, it's possible to bless any type of data structure or referent,
-including scalars, globs, and subroutines. You may see this sort of
-thing when looking at code in the wild.
-
-Here's an example of a module as a blessed scalar:
-
- package Time;
-
- use strict;
- use warnings;
-
- sub new {
- my $class = shift;
-
- my $time = time;
- return bless \$time, $class;
- }
-
- sub epoch {
- my $self = shift;
- return ${ $self };
- }
-
- my $time = Time->new();
- print $time->epoch();
-
-=head2 Inside-Out objects
-
-In the past, the Perl community experimented with a technique called
-"inside-out objects". An inside-out object stores its data outside of
-the object's reference, indexed on a unique property of the object,
-such as its memory address, rather than in the object itself. This has
-the advantage of enforcing the encapsulation of object attributes,
-since their data is not stored in the object itself.
-
-This technique was popular for a while (and was recommended in Damian
-Conway's I<Perl Best Practices>), but never achieved universal
-adoption. The L<Object::InsideOut> module on CPAN provides a
-comprehensive implementation of this technique, and you may see it or
-other inside-out modules in the wild.
-
-Here is a simple example of the technique, using the
-L<Hash::Util::FieldHash> core module. This module was added to the core
-to support inside-out object implementations.
-
- package Time;
-
- use strict;
- use warnings;
-
- use Hash::Util::FieldHash 'fieldhash';
-
- fieldhash my %time_for;
-
- sub new {
- my $class = shift;
-
- my $self = bless \( my $object ), $class;
-
- $time_for{$self} = time;
-
- return $self;
- }
-
- sub epoch {
- my $self = shift;
-
- return $time_for{$self};
- }
-
- my $time = Time->new;
- print $time->epoch;
-
-=head2 Pseudo-hashes
-
-The pseudo-hash feature was an experimental feature introduced in
-earlier versions of Perl and removed in 5.10.0. A pseudo-hash is an
-array reference which can be accessed using named keys like a hash. You
-may run in to some code in the wild which uses it. See the L<fields>
-pragma for more information.
-
-=head1 SEE ALSO
-
-A kinder, gentler tutorial on object-oriented programming in Perl can
-be found in L<perlootut>. You should also check out L<perlmodlib> for
-some style guides on constructing both modules and classes.
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlootut.pod b/Master/tlpkg/tlperl/lib/pods/perlootut.pod
deleted file mode 100644
index b2e3500b358..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlootut.pod
+++ /dev/null
@@ -1,741 +0,0 @@
-=encoding utf8
-
-=for comment
-Consistent formatting of this file is achieved with:
- perl ./Porting/podtidy pod/perlootut.pod
-
-=head1 NAME
-
-perlootut - Object-Oriented Programming in Perl Tutorial
-
-=head1 DATE
-
-This document was created in February, 2011.
-
-=head1 DESCRIPTION
-
-This document provides an introduction to object-oriented programming
-in Perl. It begins with a brief overview of the concepts behind object
-oriented design. Then it introduces several different OO systems from
-L<CPAN|http://search.cpan.org> which build on top of what Perl
-provides.
-
-By default, Perl's built-in OO system is very minimal, leaving you to
-do most of the work. This minimalism made a lot of sense in 1994, but
-in the years since Perl 5.0 we've seen a number of common patterns
-emerge in Perl OO. Fortunately, Perl's flexibility has allowed a rich
-ecosystem of Perl OO systems to flourish.
-
-If you want to know how Perl OO works under the hood, the L<perlobj>
-document explains the nitty gritty details.
-
-This document assumes that you already understand the basics of Perl
-syntax, variable types, operators, and subroutine calls. If you don't
-understand these concepts yet, please read L<perlintro> first. You
-should also read the L<perlsyn>, L<perlop>, and L<perlsub> documents.
-
-=head1 OBJECT-ORIENTED FUNDAMENTALS
-
-Most object systems share a number of common concepts. You've probably
-heard terms like "class", "object, "method", and "attribute" before.
-Understanding the concepts will make it much easier to read and write
-object-oriented code. If you're already familiar with these terms, you
-should still skim this section, since it explains each concept in terms
-of Perl's OO implementation.
-
-Perl's OO system is class-based. Class-based OO is fairly common. It's
-used by Java, C++, C#, Python, Ruby, and many other languages. There
-are other object orientation paradigms as well. JavaScript is the most
-popular language to use another paradigm. JavaScript's OO system is
-prototype-based.
-
-=head2 Object
-
-An B<object> is a data structure that bundles together data and
-subroutines which operate on that data. An object's data is called
-B<attributes>, and its subroutines are called B<methods>. An object can
-be thought of as a noun (a person, a web service, a computer).
-
-An object represents a single discrete thing. For example, an object
-might represent a file. The attributes for a file object might include
-its path, content, and last modification time. If we created an object
-to represent F</etc/hostname> on a machine named "foo.example.com",
-that object's path would be "/etc/hostname", its content would be
-"foo\n", and it's last modification time would be 1304974868 seconds
-since the beginning of the epoch.
-
-The methods associated with a file might include C<rename()> and
-C<write()>.
-
-In Perl most objects are hashes, but the OO systems we recommend keep
-you from having to worry about this. In practice, it's best to consider
-an object's internal data structure opaque.
-
-=head2 Class
-
-A B<class> defines the behavior of a category of objects. A class is a
-name for a category (like "File"), and a class also defines the
-behavior of objects in that category.
-
-All objects belong to a specific class. For example, our
-F</etc/hostname> object belongs to the C<File> class. When we want to
-create a specific object, we start with its class, and B<construct> or
-B<instantiate> an object. A specific object is often referred to as an
-B<instance> of a class.
-
-In Perl, any package can be a class. The difference between a package
-which is a class and one which isn't is based on how the package is
-used. Here's our "class declaration" for the C<File> class:
-
- package File;
-
-In Perl, there is no special keyword for constructing an object.
-However, most OO modules on CPAN use a method named C<new()> to
-construct a new object:
-
- my $hostname = File->new(
- path => '/etc/hostname',
- content => "foo\n",
- last_mod_time => 1304974868,
- );
-
-(Don't worry about that C<< -> >> operator, it will be explained
-later.)
-
-=head3 Blessing
-
-As we said earlier, most Perl objects are hashes, but an object can be
-an instance of any Perl data type (scalar, array, etc.). Turning a
-plain data structure into an object is done by B<blessing> that data
-structure using Perl's C<bless> function.
-
-While we strongly suggest you don't build your objects from scratch,
-you should know the term B<bless>. A B<blessed> data structure (aka "a
-referent") is an object. We sometimes say that an object has been
-"blessed into a class".
-
-Once a referent has been blessed, the C<blessed> function from the
-L<Scalar::Util> core module can tell us its class name. This subroutine
-returns an object's class when passed an object, and false otherwise.
-
- use Scalar::Util 'blessed';
-
- print blessed($hash); # undef
- print blessed($hostname); # File
-
-=head3 Constructor
-
-A B<constructor> creates a new object. In Perl, a class's constructor
-is just another method, unlike some other languages, which provide
-syntax for constructors. Most Perl classes use C<new> as the name for
-their constructor:
-
- my $file = File->new(...);
-
-=head2 Methods
-
-You already learned that a B<method> is a subroutine that operates on
-an object. You can think of a method as the things that an object can
-I<do>. If an object is a noun, then methods are its verbs (save, print,
-open).
-
-In Perl, methods are simply subroutines that live in a class's package.
-Methods are always written to receive the object as their first
-argument:
-
- sub print_info {
- my $self = shift;
-
- print "This file is at ", $self->path, "\n";
- }
-
- $file->print_info;
- # The file is at /etc/hostname
-
-What makes a method special is I<how it's called>. The arrow operator
-(C<< -> >>) tells Perl that we are calling a method.
-
-When we make a method call, Perl arranges for the method's B<invocant>
-to be passed as the first argument. B<Invocant> is a fancy name for the
-thing on the left side of the arrow. The invocant can either be a class
-name or an object. We can also pass additional arguments to the method:
-
- sub print_info {
- my $self = shift;
- my $prefix = shift // "This file is at ";
-
- print $prefix, ", ", $self->path, "\n";
- }
-
- $file->print_info("The file is located at ");
- # The file is located at /etc/hostname
-
-=head2 Attributes
-
-Each class can define its B<attributes>. When we instantiate an object,
-we assign values to those attributes. For example, every C<File> object
-has a path. Attributes are sometimes called B<properties>.
-
-Perl has no special syntax for attributes. Under the hood, attributes
-are often stored as keys in the object's underlying hash, but don't
-worry about this.
-
-We recommend that you only access attributes via B<accessor> methods.
-These are methods that can get or set the value of each attribute. We
-saw this earlier in the C<print_info()> example, which calls C<<
-$self->path >>.
-
-You might also see the terms B<getter> and B<setter>. These are two
-types of accessors. A getter gets the attribute's value, while a setter
-sets it. Another term for a setter is B<mutator>
-
-Attributes are typically defined as read-only or read-write. Read-only
-attributes can only be set when the object is first created, while
-read-write attributes can be altered at any time.
-
-The value of an attribute may itself be another object. For example,
-instead of returning its last mod time as a number, the C<File> class
-could return a L<DateTime> object representing that value.
-
-It's possible to have a class that does not expose any publicly
-settable attributes. Not every class has attributes and methods.
-
-=head2 Polymorphism
-
-B<Polymorphism> is a fancy way of saying that objects from two
-different classes share an API. For example, we could have C<File> and
-C<WebPage> classes which both have a C<print_content()> method. This
-method might produce different output for each class, but they share a
-common interface.
-
-While the two classes may differ in many ways, when it comes to the
-C<print_content()> method, they are the same. This means that we can
-try to call the C<print_content()> method on an object of either class,
-and B<we don't have to know what class the object belongs to!>
-
-Polymorphism is one of the key concepts of object-oriented design.
-
-=head2 Inheritance
-
-B<Inheritance> lets you create a specialized version of an existing
-class. Inheritance lets the new class to reuse the methods and
-attributes of another class.
-
-For example, we could create an C<File::MP3> class which B<inherits>
-from C<File>. An C<File::MP3> B<is-a> I<more specific> type of C<File>.
-All mp3 files are files, but not all files are mp3 files.
-
-We often refer to inheritance relationships as B<parent-child> or
-C<superclass/subclass> relationships. Sometimes we say that the child
-has an B<is-a> relationship with its parent class.
-
-C<File> is a B<superclass> of C<File::MP3>, and C<File::MP3> is a
-B<subclass> of C<File>.
-
- package File::MP3;
-
- use parent 'File';
-
-The L<parent> module is one of several ways that Perl lets you define
-inheritance relationships.
-
-Perl allows multiple inheritance, which means that a class can inherit
-from multiple parents. While this is possible, we strongly recommend
-against it. Generally, you can use B<roles> to do everything you can do
-with multiple inheritance, but in a cleaner way.
-
-Note that there's nothing wrong with defining multiple subclasses of a
-given class. This is both common and safe. For example, we might define
-C<File::MP3::FixedBitrate> and C<File::MP3::VariableBitrate> classes to
-distinguish between different types of mp3 file.
-
-=head3 Overriding methods and method resolution
-
-Inheritance allows two classes to share code. By default, every method
-in the parent class is also available in the child. The child can
-explicitly B<override> a parent's method to provide its own
-implementation. For example, if we have an C<File::MP3> object, it has
-the C<print_info()> method from C<File>:
-
- my $cage = File::MP3->new(
- path => 'mp3s/My-Body-Is-a-Cage.mp3',
- content => $mp3_data,
- last_mod_time => 1304974868,
- title => 'My Body Is a Cage',
- );
-
- $cage->print_info;
- # The file is at mp3s/My-Body-Is-a-Cage.mp3
-
-If we wanted to include the mp3's title in the greeting, we could
-override the method:
-
- package File::MP3;
-
- use parent 'File';
-
- sub print_info {
- my $self = shift;
-
- print "This file is at ", $self->path, "\n";
- print "Its title is ", $self->title, "\n";
- }
-
- $cage->print_info;
- # The file is at mp3s/My-Body-Is-a-Cage.mp3
- # Its title is My Body Is a Cage
-
-The process of determining what method should be used is called
-B<method resolution>. What Perl does is look at the object's class
-first (C<File::MP3> in this case). If that class defines the method,
-then that class's version of the method is called. If not, Perl looks
-at each parent class in turn. For C<File::MP3>, its only parent is
-C<File>. If C<File::MP3> does not define the method, but C<File> does,
-then Perl calls the method in C<File>.
-
-If C<File> inherited from C<DataSource>, which inherited from C<Thing>,
-then Perl would keep looking "up the chain" if necessary.
-
-It is possible to explicitly call a parent method from a child:
-
- package File::MP3;
-
- use parent 'File';
-
- sub print_info {
- my $self = shift;
-
- $self->SUPER::print_info();
- print "Its title is ", $self->title, "\n";
- }
-
-The C<SUPER::> bit tells Perl to look for the C<print_info()> in the
-C<File::MP3> class's inheritance chain. When it finds the parent class
-that implements this method, the method is called.
-
-We mentioned multiple inheritance earlier. The main problem with
-multiple inheritance is that it greatly complicates method resolution.
-See L<perlobj> for more details.
-
-=head2 Encapsulation
-
-B<Encapsulation> is the idea that an object is opaque. When another
-developer uses your class, they don't need to know I<how> it is
-implemented, they just need to know I<what> it does.
-
-Encapsulation is important for several reasons. First, it allows you to
-separate the public API from the private implementation. This means you
-can change that implementation without breaking the API.
-
-Second, when classes are well encapsulated, they become easier to
-subclass. Ideally, a subclass uses the same APIs to access object data
-that its parent class uses. In reality, subclassing sometimes involves
-violating encapsulation, but a good API can minimize the need to do
-this.
-
-We mentioned earlier that most Perl objects are implemented as hashes
-under the hood. The principle of encapsulation tells us that we should
-not rely on this. Instead, we should use accessor methods to access the
-data in that hash. The object systems that we recommend below all
-automate the generation of accessor methods. If you use one of them,
-you should never have to access the object as a hash directly.
-
-=head2 Composition
-
-In object-oriented code, we often find that one object references
-another object. This is called B<composition>, or a B<has-a>
-relationship.
-
-Earlier, we mentioned that the C<File> class's C<last_mod_time>
-accessor could return a L<DateTime> object. This is a perfect example
-of composition. We could go even further, and make the C<path> and
-C<content> accessors return objects as well. The C<File> class would
-then be B<composed> of several other objects.
-
-=head2 Roles
-
-B<Roles> are something that a class I<does>, rather than something that
-it I<is>. Roles are relatively new to Perl, but have become rather
-popular. Roles are B<applied> to classes. Sometimes we say that classes
-B<consume> roles.
-
-Roles are an alternative to inheritance for providing polymorphism.
-Let's assume we have two classes, C<Radio> and C<Computer>. Both of
-these things have on/off switches. We want to model that in our class
-definitions.
-
-We could have both classes inherit from a common parent, like
-C<Machine>, but not all machines have on/off switches. We could create
-a parent class called C<HasOnOffSwitch>, but that is very artificial.
-Radios and computers are not specializations of this parent. This
-parent is really a rather ridiculous creation.
-
-This is where roles come in. It makes a lot of sense to create a
-C<HasOnOffSwitch> role and apply it to both classes. This role would
-define a known API like providing C<turn_on()> and C<turn_off()>
-methods.
-
-Perl does not have any built-in way to express roles. In the past,
-people just bit the bullet and used multiple inheritance. Nowadays,
-there are several good choices on CPAN for using roles.
-
-=head2 When to Use OO
-
-Object Orientation is not the best solution to every problem. In I<Perl
-Best Practices> (copyright 2004, Published by O'Reilly Media, Inc.),
-Damian Conway provides a list of criteria to use when deciding if OO is
-the right fit for your problem:
-
-=over 4
-
-=item *
-
-The system being designed is large, or is likely to become large.
-
-=item *
-
-The data can be aggregated into obvious structures, especially if
-there's a large amount of data in each aggregate.
-
-=item *
-
-The various types of data aggregate form a natural hierarchy that
-facilitates the use of inheritance and polymorphism.
-
-=item *
-
-You have a piece of data on which many different operations are
-applied.
-
-=item *
-
-You need to perform the same general operations on related types of
-data, but with slight variations depending on the specific type of data
-the operations are applied to.
-
-=item *
-
-It's likely you'll have to add new data types later.
-
-=item *
-
-The typical interactions between pieces of data are best represented by
-operators.
-
-=item *
-
-The implementation of individual components of the system is likely to
-change over time.
-
-=item *
-
-The system design is already object-oriented.
-
-=item *
-
-Large numbers of other programmers will be using your code modules.
-
-=back
-
-=head1 PERL OO SYSTEMS
-
-As we mentioned before, Perl's built-in OO system is very minimal, but
-also quite flexible. Over the years, many people have developed systems
-which build on top of Perl's built-in system to provide more features
-and convenience.
-
-We strongly recommend that you use one of these systems. Even the most
-minimal of them eliminates a lot of repetitive boilerplate. There's
-really no good reason to write your classes from scratch in Perl.
-
-If you are interested in the guts underlying these systems, check out
-L<perlobj>.
-
-=head2 Moose
-
-L<Moose> bills itself as a "postmodern object system for Perl 5". Don't
-be scared, the "postmodern" label is a callback to Larry's description
-of Perl as "the first postmodern computer language".
-
-C<Moose> provides a complete, modern OO system. Its biggest influence
-is the Common Lisp Object System, but it also borrows ideas from
-Smalltalk and several other languages. C<Moose> was created by Stevan
-Little, and draws heavily from his work on the Perl 6 OO design.
-
-Here is our C<File> class using C<Moose>:
-
- package File;
- use Moose;
-
- has path => ( is => 'ro' );
- has content => ( is => 'ro' );
- has last_mod_time => ( is => 'ro' );
-
- sub print_info {
- my $self = shift;
-
- print "This file is at ", $self->path, "\n";
- }
-
-C<Moose> provides a number of features:
-
-=over 4
-
-=item * Declarative sugar
-
-C<Moose> provides a layer of declarative "sugar" for defining classes.
-That sugar is just a set of exported functions that make declaring how
-your class works simpler and more palatable. This lets you describe
-I<what> your class is, rather than having to tell Perl I<how> to
-implement your class.
-
-The C<has()> subroutine declares an attribute, and C<Moose>
-automatically creates accessors for these attributes. It also takes
-care of creating a C<new()> method for you. This constructor knows
-about the attributes you declared, so you can set them when creating a
-new C<File>.
-
-=item * Roles built-in
-
-C<Moose> lets you define roles the same way you define classes:
-
- package HasOnOfSwitch;
- use Moose::Role;
-
- has is_on => (
- is => 'rw',
- isa => 'Bool',
- );
-
- sub turn_on {
- my $self = shift;
- $self->is_on(1);
- }
-
- sub turn_off {
- my $self = shift;
- $self->is_on(0);
- }
-
-=item * A miniature type system
-
-In the example above, you can see that we passed C<< isa => 'Bool' >>
-to C<has()> when creating our C<is_on> attribute. This tells C<Moose>
-that this attribute must be a boolean value. If we try to set it to an
-invalid value, our code will throw an error.
-
-=item * Full introspection and manipulation
-
-Perl's built-in introspection features are fairly minimal. C<Moose>
-builds on top of them and creates a full introspection layer for your
-classes. This lets you ask questions like "what methods does the File
-class implement?" It also lets you modify your classes
-programmatically.
-
-=item * Self-hosted and extensible
-
-C<Moose> describes itself using its own introspection API. Besides
-being a cool trick, this means that you can extend C<Moose> using
-C<Moose> itself.
-
-=item * Rich ecosystem
-
-There is a rich ecosystem of C<Moose> extensions on CPAN under the
-L<MooseX|http://search.cpan.org/search?query=MooseX&mode=dist>
-namespace. In addition, many modules on CPAN already use C<Moose>,
-providing you with lots of examples to learn from.
-
-=item * Many more features
-
-C<Moose> is a very powerful tool, and we can't cover all of its
-features here. We encourage you to learn more by reading the C<Moose>
-documentation, starting with
-L<Moose::Manual|http://search.cpan.org/perldoc?Moose::Manual>.
-
-=back
-
-Of course, C<Moose> isn't perfect.
-
-C<Moose> can make your code slower to load. C<Moose> itself is not
-small, and it does a I<lot> of code generation when you define your
-class. This code generation means that your runtime code is as fast as
-it can be, but you pay for this when your modules are first loaded.
-
-This load time hit can be a problem when startup speed is important,
-such as with a command-line script or a "plain vanilla" CGI script that
-must be loaded each time it is executed.
-
-Before you panic, know that many people do use C<Moose> for
-command-line tools and other startup-sensitive code. We encourage you
-to try C<Moose> out first before worrying about startup speed.
-
-C<Moose> also has several dependencies on other modules. Most of these
-are small stand-alone modules, a number of which have been spun off
-from C<Moose>. C<Moose> itself, and some of its dependencies, require a
-compiler. If you need to install your software on a system without a
-compiler, or if having I<any> dependencies is a problem, then C<Moose>
-may not be right for you.
-
-=head3 Mouse
-
-If you try C<Moose> and find that one of these issues is preventing you
-from using C<Moose>, we encourage you to consider L<Mouse> next.
-C<Mouse> implements a subset of C<Moose>'s functionality in a simpler
-package. For all features that it does implement, the end-user API is
-I<identical> to C<Moose>, meaning you can switch from C<Mouse> to
-C<Moose> quite easily.
-
-C<Mouse> does not implement most of C<Moose>'s introspection API, so
-it's often faster when loading your modules. Additionally, all of its
-I<required> dependencies ship with the Perl core, and it can run
-without a compiler. If you do have a compiler, C<Mouse> will use it to
-compile some of its code for a speed boost.
-
-Finally, it ships with a C<Mouse::Tiny> module that takes most of
-C<Mouse>'s features and bundles them up in a single module file. You
-can copy this module file into your application's library directory for
-easy bundling.
-
-The C<Moose> authors hope that one day C<Mouse> can be made obsolete by
-improving C<Moose> enough, but for now it provides a worthwhile
-alternative to C<Moose>.
-
-=head2 Class::Accessor
-
-L<Class::Accessor> is the polar opposite of C<Moose>. It provides very
-few features, nor is it self-hosting.
-
-It is, however, very simple, pure Perl, and it has no non-core
-dependencies. It also provides a "Moose-like" API on demand for the
-features it supports.
-
-Even though it doesn't do much, it is still preferable to writing your
-own classes from scratch.
-
-Here's our C<File> class with C<Class::Accessor>:
-
- package File;
- use Class::Accessor 'antlers';
-
- has path => ( is => 'ro' );
- has content => ( is => 'ro' );
- has last_mod_time => ( is => 'ro' );
-
- sub print_info {
- my $self = shift;
-
- print "This file is at ", $self->path, "\n";
- }
-
-The C<antlers> import flag tells C<Class::Accessor> that you want to
-define your attributes using C<Moose>-like syntax. The only parameter
-that you can pass to C<has> is C<is>. We recommend that you use this
-Moose-like syntax if you choose C<Class::Accessor> since it means you
-will have a smoother upgrade path if you later decide to move to
-C<Moose>.
-
-Like C<Moose>, C<Class::Accessor> generates accessor methods and a
-constructor for your class.
-
-=head2 Object::Tiny
-
-Finally, we have L<Object::Tiny>. This module truly lives up to its
-name. It has an incredibly minimal API and absolutely no dependencies
-(core or not). Still, we think it's a lot easier to use than writing
-your own OO code from scratch.
-
-Here's our C<File> class once more:
-
- package File;
- use Object::Tiny qw( path content last_mod_time );
-
- sub print_info {
- my $self = shift;
-
- print "This file is at ", $self->path, "\n";
- }
-
-That's it!
-
-With C<Object::Tiny>, all accessors are read-only. It generates a
-constructor for you, as well as the accessors you define.
-
-=head2 Role::Tiny
-
-As we mentioned before, roles provide an alternative to inheritance,
-but Perl does not have any built-in role support. If you choose to use
-Moose, it comes with a full-fledged role implementation. However, if
-you use one of our other recommended OO modules, you can still use
-roles with L<Role::Tiny>
-
-C<Role::Tiny> provides some of the same features as Moose's role
-system, but in a much smaller package. Most notably, it doesn't support
-any sort of attribute declaration, so you have to do that by hand.
-Still, it's useful, and works well with C<Class::Accessor> and
-C<Object::Tiny>
-
-=head2 OO System Summary
-
-Here's a brief recap of the options we covered:
-
-=over 4
-
-=item * L<Moose>
-
-C<Moose> is the maximal option. It has a lot of features, a big
-ecosystem, and a thriving user base. We also covered L<Mouse> briefly.
-C<Mouse> is C<Moose> lite, and a reasonable alternative when Moose
-doesn't work for your application.
-
-=item * L<Class::Accessor>
-
-C<Class::Accessor> does a lot less than C<Moose>, and is a nice
-alternative if you find C<Moose> overwhelming. It's been around a long
-time and is well battle-tested. It also has a minimal C<Moose>
-compatibility mode which makes moving from C<Class::Accessor> to
-C<Moose> easy.
-
-=item * L<Object::Tiny>
-
-C<Object::Tiny> is the absolute minimal option. It has no dependencies,
-and almost no syntax to learn. It's a good option for a super minimal
-environment and for throwing something together quickly without having
-to worry about details.
-
-=item * L<Role::Tiny>
-
-Use C<Role::Tiny> with C<Class::Accessor> or C<Object::Tiny> if you
-find yourself considering multiple inheritance. If you go with
-C<Moose>, it comes with its own role implementation.
-
-=back
-
-=head2 Other OO Systems
-
-There are literally dozens of other OO-related modules on CPAN besides
-those covered here, and you're likely to run across one or more of them
-if you work with other people's code.
-
-In addition, plenty of code in the wild does all of its OO "by hand",
-using just the Perl built-in OO features. If you need to maintain such
-code, you should read L<perlobj> to understand exactly how Perl's
-built-in OO works.
-
-=head1 CONCLUSION
-
-As we said before, Perl's minimal OO system has led to a profusion of
-OO systems on CPAN. While you can still drop down to the bare metal and
-write your classes by hand, there's really no reason to do that with
-modern Perl.
-
-For small systems, L<Object::Tiny> and L<Class::Accessor> both provide
-minimal object systems that take care of basic boilerplate for you.
-
-For bigger projects, L<Moose> provides a rich set of features that will
-let you focus on implementing your business logic.
-
-We encourage you to play with and evaluate L<Moose>,
-L<Class::Accessor>, and L<Object::Tiny> to see which OO system is right
-for you.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlop.pod b/Master/tlpkg/tlperl/lib/pods/perlop.pod
deleted file mode 100644
index 7b2d0a3acd0..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlop.pod
+++ /dev/null
@@ -1,3215 +0,0 @@
-=head1 NAME
-X<operator>
-
-perlop - Perl operators and precedence
-
-=head1 DESCRIPTION
-
-=head2 Operator Precedence and Associativity
-X<operator, precedence> X<precedence> X<associativity>
-
-Operator precedence and associativity work in Perl more or less like
-they do in mathematics.
-
-I<Operator precedence> means some operators are evaluated before
-others. For example, in C<2 + 4 * 5>, the multiplication has higher
-precedence so C<4 * 5> is evaluated first yielding C<2 + 20 ==
-22> and not C<6 * 5 == 30>.
-
-I<Operator associativity> defines what happens if a sequence of the
-same operators is used one after another: whether the evaluator will
-evaluate the left operations first or the right. For example, in C<8
-- 4 - 2>, subtraction is left associative so Perl evaluates the
-expression left to right. C<8 - 4> is evaluated first making the
-expression C<4 - 2 == 2> and not C<8 - 2 == 6>.
-
-Perl operators have the following associativity and precedence,
-listed from highest precedence to lowest. Operators borrowed from
-C keep the same precedence relationship with each other, even where
-C's precedence is slightly screwy. (This makes learning Perl easier
-for C folks.) With very few exceptions, these all operate on scalar
-values only, not array values.
-
- left terms and list operators (leftward)
- left ->
- nonassoc ++ --
- right **
- right ! ~ \ and unary + and -
- left =~ !~
- left * / % x
- left + - .
- left << >>
- nonassoc named unary operators
- nonassoc < > <= >= lt gt le ge
- nonassoc == != <=> eq ne cmp ~~
- left &
- left | ^
- left &&
- left || //
- nonassoc .. ...
- right ?:
- right = += -= *= etc.
- left , =>
- nonassoc list operators (rightward)
- right not
- left and
- left or xor
-
-In the following sections, these operators are covered in precedence order.
-
-Many operators can be overloaded for objects. See L<overload>.
-
-=head2 Terms and List Operators (Leftward)
-X<list operator> X<operator, list> X<term>
-
-A TERM has the highest precedence in Perl. They include variables,
-quote and quote-like operators, any expression in parentheses,
-and any function whose arguments are parenthesized. Actually, there
-aren't really functions in this sense, just list operators and unary
-operators behaving as functions because you put parentheses around
-the arguments. These are all documented in L<perlfunc>.
-
-If any list operator (print(), etc.) or any unary operator (chdir(), etc.)
-is followed by a left parenthesis as the next token, the operator and
-arguments within parentheses are taken to be of highest precedence,
-just like a normal function call.
-
-In the absence of parentheses, the precedence of list operators such as
-C<print>, C<sort>, or C<chmod> is either very high or very low depending on
-whether you are looking at the left side or the right side of the operator.
-For example, in
-
- @ary = (1, 3, sort 4, 2);
- print @ary; # prints 1324
-
-the commas on the right of the sort are evaluated before the sort,
-but the commas on the left are evaluated after. In other words,
-list operators tend to gobble up all arguments that follow, and
-then act like a simple TERM with regard to the preceding expression.
-Be careful with parentheses:
-
- # These evaluate exit before doing the print:
- print($foo, exit); # Obviously not what you want.
- print $foo, exit; # Nor is this.
-
- # These do the print before evaluating exit:
- (print $foo), exit; # This is what you want.
- print($foo), exit; # Or this.
- print ($foo), exit; # Or even this.
-
-Also note that
-
- print ($foo & 255) + 1, "\n";
-
-probably doesn't do what you expect at first glance. The parentheses
-enclose the argument list for C<print> which is evaluated (printing
-the result of C<$foo & 255>). Then one is added to the return value
-of C<print> (usually 1). The result is something like this:
-
- 1 + 1, "\n"; # Obviously not what you meant.
-
-To do what you meant properly, you must write:
-
- print(($foo & 255) + 1, "\n");
-
-See L<Named Unary Operators> for more discussion of this.
-
-Also parsed as terms are the C<do {}> and C<eval {}> constructs, as
-well as subroutine and method calls, and the anonymous
-constructors C<[]> and C<{}>.
-
-See also L<Quote and Quote-like Operators> toward the end of this section,
-as well as L</"I/O Operators">.
-
-=head2 The Arrow Operator
-X<arrow> X<dereference> X<< -> >>
-
-"C<< -> >>" is an infix dereference operator, just as it is in C
-and C++. If the right side is either a C<[...]>, C<{...}>, or a
-C<(...)> subscript, then the left side must be either a hard or
-symbolic reference to an array, a hash, or a subroutine respectively.
-(Or technically speaking, a location capable of holding a hard
-reference, if it's an array or hash reference being used for
-assignment.) See L<perlreftut> and L<perlref>.
-
-Otherwise, the right side is a method name or a simple scalar
-variable containing either the method name or a subroutine reference,
-and the left side must be either an object (a blessed reference)
-or a class name (that is, a package name). See L<perlobj>.
-
-=head2 Auto-increment and Auto-decrement
-X<increment> X<auto-increment> X<++> X<decrement> X<auto-decrement> X<-->
-
-"++" and "--" work as in C. That is, if placed before a variable,
-they increment or decrement the variable by one before returning the
-value, and if placed after, increment or decrement after returning the
-value.
-
- $i = 0; $j = 0;
- print $i++; # prints 0
- print ++$j; # prints 1
-
-Note that just as in C, Perl doesn't define B<when> the variable is
-incremented or decremented. You just know it will be done sometime
-before or after the value is returned. This also means that modifying
-a variable twice in the same statement will lead to undefined behavior.
-Avoid statements like:
-
- $i = $i ++;
- print ++ $i + $i ++;
-
-Perl will not guarantee what the result of the above statements is.
-
-The auto-increment operator has a little extra builtin magic to it. If
-you increment a variable that is numeric, or that has ever been used in
-a numeric context, you get a normal increment. If, however, the
-variable has been used in only string contexts since it was set, and
-has a value that is not the empty string and matches the pattern
-C</^[a-zA-Z]*[0-9]*\z/>, the increment is done as a string, preserving each
-character within its range, with carry:
-
- print ++($foo = "99"); # prints "100"
- print ++($foo = "a0"); # prints "a1"
- print ++($foo = "Az"); # prints "Ba"
- print ++($foo = "zz"); # prints "aaa"
-
-C<undef> is always treated as numeric, and in particular is changed
-to C<0> before incrementing (so that a post-increment of an undef value
-will return C<0> rather than C<undef>).
-
-The auto-decrement operator is not magical.
-
-=head2 Exponentiation
-X<**> X<exponentiation> X<power>
-
-Binary "**" is the exponentiation operator. It binds even more
-tightly than unary minus, so -2**4 is -(2**4), not (-2)**4. (This is
-implemented using C's pow(3) function, which actually works on doubles
-internally.)
-
-=head2 Symbolic Unary Operators
-X<unary operator> X<operator, unary>
-
-Unary "!" performs logical negation, that is, "not". See also C<not> for a lower
-precedence version of this.
-X<!>
-
-Unary "-" performs arithmetic negation if the operand is numeric,
-including any string that looks like a number. If the operand is
-an identifier, a string consisting of a minus sign concatenated
-with the identifier is returned. Otherwise, if the string starts
-with a plus or minus, a string starting with the opposite sign is
-returned. One effect of these rules is that -bareword is equivalent
-to the string "-bareword". If, however, the string begins with a
-non-alphabetic character (excluding "+" or "-"), Perl will attempt to convert
-the string to a numeric and the arithmetic negation is performed. If the
-string cannot be cleanly converted to a numeric, Perl will give the warning
-B<Argument "the string" isn't numeric in negation (-) at ...>.
-X<-> X<negation, arithmetic>
-
-Unary "~" performs bitwise negation, that is, 1's complement. For
-example, C<0666 & ~027> is 0640. (See also L<Integer Arithmetic> and
-L<Bitwise String Operators>.) Note that the width of the result is
-platform-dependent: ~0 is 32 bits wide on a 32-bit platform, but 64
-bits wide on a 64-bit platform, so if you are expecting a certain bit
-width, remember to use the "&" operator to mask off the excess bits.
-X<~> X<negation, binary>
-
-When complementing strings, if all characters have ordinal values under
-256, then their complements will, also. But if they do not, all
-characters will be in either 32- or 64-bit complements, depending on your
-architecture. So for example, C<~"\x{3B1}"> is C<"\x{FFFF_FC4E}"> on
-32-bit machines and C<"\x{FFFF_FFFF_FFFF_FC4E}"> on 64-bit machines.
-
-Unary "+" has no effect whatsoever, even on strings. It is useful
-syntactically for separating a function name from a parenthesized expression
-that would otherwise be interpreted as the complete list of function
-arguments. (See examples above under L<Terms and List Operators (Leftward)>.)
-X<+>
-
-Unary "\" creates a reference to whatever follows it. See L<perlreftut>
-and L<perlref>. Do not confuse this behavior with the behavior of
-backslash within a string, although both forms do convey the notion
-of protecting the next thing from interpolation.
-X<\> X<reference> X<backslash>
-
-=head2 Binding Operators
-X<binding> X<operator, binding> X<=~> X<!~>
-
-Binary "=~" binds a scalar expression to a pattern match. Certain operations
-search or modify the string $_ by default. This operator makes that kind
-of operation work on some other string. The right argument is a search
-pattern, substitution, or transliteration. The left argument is what is
-supposed to be searched, substituted, or transliterated instead of the default
-$_. When used in scalar context, the return value generally indicates the
-success of the operation. The exceptions are substitution (s///)
-and transliteration (y///) with the C</r> (non-destructive) option,
-which cause the B<r>eturn value to be the result of the substitution.
-Behavior in list context depends on the particular operator.
-See L</"Regexp Quote-Like Operators"> for details and L<perlretut> for
-examples using these operators.
-
-If the right argument is an expression rather than a search pattern,
-substitution, or transliteration, it is interpreted as a search pattern at run
-time. Note that this means that its contents will be interpolated twice, so
-
- '\\' =~ q'\\';
-
-is not ok, as the regex engine will end up trying to compile the
-pattern C<\>, which it will consider a syntax error.
-
-Binary "!~" is just like "=~" except the return value is negated in
-the logical sense.
-
-Binary "!~" with a non-destructive substitution (s///r) or transliteration
-(y///r) is a syntax error.
-
-=head2 Multiplicative Operators
-X<operator, multiplicative>
-
-Binary "*" multiplies two numbers.
-X<*>
-
-Binary "/" divides two numbers.
-X</> X<slash>
-
-Binary "%" is the modulo operator, which computes the division
-remainder of its first argument with respect to its second argument.
-Given integer
-operands C<$a> and C<$b>: If C<$b> is positive, then C<$a % $b> is
-C<$a> minus the largest multiple of C<$b> less than or equal to
-C<$a>. If C<$b> is negative, then C<$a % $b> is C<$a> minus the
-smallest multiple of C<$b> that is not less than C<$a> (that is, the
-result will be less than or equal to zero). If the operands
-C<$a> and C<$b> are floating point values and the absolute value of
-C<$b> (that is C<abs($b)>) is less than C<(UV_MAX + 1)>, only
-the integer portion of C<$a> and C<$b> will be used in the operation
-(Note: here C<UV_MAX> means the maximum of the unsigned integer type).
-If the absolute value of the right operand (C<abs($b)>) is greater than
-or equal to C<(UV_MAX + 1)>, "%" computes the floating-point remainder
-C<$r> in the equation C<($r = $a - $i*$b)> where C<$i> is a certain
-integer that makes C<$r> have the same sign as the right operand
-C<$b> (B<not> as the left operand C<$a> like C function C<fmod()>)
-and the absolute value less than that of C<$b>.
-Note that when C<use integer> is in scope, "%" gives you direct access
-to the modulo operator as implemented by your C compiler. This
-operator is not as well defined for negative operands, but it will
-execute faster.
-X<%> X<remainder> X<modulo> X<mod>
-
-Binary "x" is the repetition operator. In scalar context or if the left
-operand is not enclosed in parentheses, it returns a string consisting
-of the left operand repeated the number of times specified by the right
-operand. In list context, if the left operand is enclosed in
-parentheses or is a list formed by C<qw/STRING/>, it repeats the list.
-If the right operand is zero or negative, it returns an empty string
-or an empty list, depending on the context.
-X<x>
-
- print '-' x 80; # print row of dashes
-
- print "\t" x ($tab/8), ' ' x ($tab%8); # tab over
-
- @ones = (1) x 80; # a list of 80 1's
- @ones = (5) x @ones; # set all elements to 5
-
-
-=head2 Additive Operators
-X<operator, additive>
-
-Binary C<+> returns the sum of two numbers.
-X<+>
-
-Binary C<-> returns the difference of two numbers.
-X<->
-
-Binary C<.> concatenates two strings.
-X<string, concatenation> X<concatenation>
-X<cat> X<concat> X<concatenate> X<.>
-
-=head2 Shift Operators
-X<shift operator> X<operator, shift> X<<< << >>>
-X<<< >> >>> X<right shift> X<left shift> X<bitwise shift>
-X<shl> X<shr> X<shift, right> X<shift, left>
-
-Binary C<<< << >>> returns the value of its left argument shifted left by the
-number of bits specified by the right argument. Arguments should be
-integers. (See also L<Integer Arithmetic>.)
-
-Binary C<<< >> >>> returns the value of its left argument shifted right by
-the number of bits specified by the right argument. Arguments should
-be integers. (See also L<Integer Arithmetic>.)
-
-Note that both C<<< << >>> and C<<< >> >>> in Perl are implemented directly using
-C<<< << >>> and C<<< >> >>> in C. If C<use integer> (see L<Integer Arithmetic>) is
-in force then signed C integers are used, else unsigned C integers are
-used. Either way, the implementation isn't going to generate results
-larger than the size of the integer type Perl was built with (32 bits
-or 64 bits).
-
-The result of overflowing the range of the integers is undefined
-because it is undefined also in C. In other words, using 32-bit
-integers, C<< 1 << 32 >> is undefined. Shifting by a negative number
-of bits is also undefined.
-
-If you get tired of being subject to your platform's native integers,
-the C<use bigint> pragma neatly sidesteps the issue altogether:
-
- print 20 << 20; # 20971520
- print 20 << 40; # 5120 on 32-bit machines,
- # 21990232555520 on 64-bit machines
- use bigint;
- print 20 << 100; # 25353012004564588029934064107520
-
-=head2 Named Unary Operators
-X<operator, named unary>
-
-The various named unary operators are treated as functions with one
-argument, with optional parentheses.
-
-If any list operator (print(), etc.) or any unary operator (chdir(), etc.)
-is followed by a left parenthesis as the next token, the operator and
-arguments within parentheses are taken to be of highest precedence,
-just like a normal function call. For example,
-because named unary operators are higher precedence than C<||>:
-
- chdir $foo || die; # (chdir $foo) || die
- chdir($foo) || die; # (chdir $foo) || die
- chdir ($foo) || die; # (chdir $foo) || die
- chdir +($foo) || die; # (chdir $foo) || die
-
-but, because * is higher precedence than named operators:
-
- chdir $foo * 20; # chdir ($foo * 20)
- chdir($foo) * 20; # (chdir $foo) * 20
- chdir ($foo) * 20; # (chdir $foo) * 20
- chdir +($foo) * 20; # chdir ($foo * 20)
-
- rand 10 * 20; # rand (10 * 20)
- rand(10) * 20; # (rand 10) * 20
- rand (10) * 20; # (rand 10) * 20
- rand +(10) * 20; # rand (10 * 20)
-
-Regarding precedence, the filetest operators, like C<-f>, C<-M>, etc. are
-treated like named unary operators, but they don't follow this functional
-parenthesis rule. That means, for example, that C<-f($file).".bak"> is
-equivalent to C<-f "$file.bak">.
-X<-X> X<filetest> X<operator, filetest>
-
-See also L<"Terms and List Operators (Leftward)">.
-
-=head2 Relational Operators
-X<relational operator> X<operator, relational>
-
-Perl operators that return true or false generally return values
-that can be safely used as numbers. For example, the relational
-operators in this section and the equality operators in the next
-one return C<1> for true and a special version of the defined empty
-string, C<"">, which counts as a zero but is exempt from warnings
-about improper numeric conversions, just as C<"0 but true"> is.
-
-Binary "<" returns true if the left argument is numerically less than
-the right argument.
-X<< < >>
-
-Binary ">" returns true if the left argument is numerically greater
-than the right argument.
-X<< > >>
-
-Binary "<=" returns true if the left argument is numerically less than
-or equal to the right argument.
-X<< <= >>
-
-Binary ">=" returns true if the left argument is numerically greater
-than or equal to the right argument.
-X<< >= >>
-
-Binary "lt" returns true if the left argument is stringwise less than
-the right argument.
-X<< lt >>
-
-Binary "gt" returns true if the left argument is stringwise greater
-than the right argument.
-X<< gt >>
-
-Binary "le" returns true if the left argument is stringwise less than
-or equal to the right argument.
-X<< le >>
-
-Binary "ge" returns true if the left argument is stringwise greater
-than or equal to the right argument.
-X<< ge >>
-
-=head2 Equality Operators
-X<equality> X<equal> X<equals> X<operator, equality>
-
-Binary "==" returns true if the left argument is numerically equal to
-the right argument.
-X<==>
-
-Binary "!=" returns true if the left argument is numerically not equal
-to the right argument.
-X<!=>
-
-Binary "<=>" returns -1, 0, or 1 depending on whether the left
-argument is numerically less than, equal to, or greater than the right
-argument. If your platform supports NaNs (not-a-numbers) as numeric
-values, using them with "<=>" returns undef. NaN is not "<", "==", ">",
-"<=" or ">=" anything (even NaN), so those 5 return false. NaN != NaN
-returns true, as does NaN != anything else. If your platform doesn't
-support NaNs then NaN is just a string with numeric value 0.
-X<< <=> >> X<spaceship>
-
- $ perl -le '$a = "NaN"; print "No NaN support here" if $a == $a'
- $ perl -le '$a = "NaN"; print "NaN support here" if $a != $a'
-
-(Note that the L<bigint>, L<bigrat>, and L<bignum> pragmas all
-support "NaN".)
-
-Binary "eq" returns true if the left argument is stringwise equal to
-the right argument.
-X<eq>
-
-Binary "ne" returns true if the left argument is stringwise not equal
-to the right argument.
-X<ne>
-
-Binary "cmp" returns -1, 0, or 1 depending on whether the left
-argument is stringwise less than, equal to, or greater than the right
-argument.
-X<cmp>
-
-Binary "~~" does a smartmatch between its arguments. Smart matching
-is described in the next section.
-X<~~>
-
-"lt", "le", "ge", "gt" and "cmp" use the collation (sort) order specified
-by the current locale if a legacy C<use locale> (but not
-C<use locale ':not_characters'>) is in effect. See
-L<perllocale>. Do not mix these with Unicode, only with legacy binary
-encodings. The standard L<Unicode::Collate> and
-L<Unicode::Collate::Locale> modules offer much more powerful solutions to
-collation issues.
-
-=head2 Smartmatch Operator
-
-First available in Perl 5.10.1 (the 5.10.0 version behaved differently),
-binary C<~~> does a "smartmatch" between its arguments. This is mostly
-used implicitly in the C<when> construct described in L<perlsyn>, although
-not all C<when> clauses call the smartmatch operator. Unique among all of
-Perl's operators, the smartmatch operator can recurse.
-
-It is also unique in that all other Perl operators impose a context
-(usually string or numeric context) on their operands, autoconverting
-those operands to those imposed contexts. In contrast, smartmatch
-I<infers> contexts from the actual types of its operands and uses that
-type information to select a suitable comparison mechanism.
-
-The C<~~> operator compares its operands "polymorphically", determining how
-to compare them according to their actual types (numeric, string, array,
-hash, etc.) Like the equality operators with which it shares the same
-precedence, C<~~> returns 1 for true and C<""> for false. It is often best
-read aloud as "in", "inside of", or "is contained in", because the left
-operand is often looked for I<inside> the right operand. That makes the
-order of the operands to the smartmatch operand often opposite that of
-the regular match operator. In other words, the "smaller" thing is usually
-placed in the left operand and the larger one in the right.
-
-The behavior of a smartmatch depends on what type of things its arguments
-are, as determined by the following table. The first row of the table
-whose types apply determines the smartmatch behavior. Because what
-actually happens is mostly determined by the type of the second operand,
-the table is sorted on the right operand instead of on the left.
-
- Left Right Description and pseudocode
- ===============================================================
- Any undef check whether Any is undefined
- like: !defined Any
-
- Any Object invoke ~~ overloading on Object, or die
-
- Right operand is an ARRAY:
-
- Left Right Description and pseudocode
- ===============================================================
- ARRAY1 ARRAY2 recurse on paired elements of ARRAY1 and ARRAY2[2]
- like: (ARRAY1[0] ~~ ARRAY2[0])
- && (ARRAY1[1] ~~ ARRAY2[1]) && ...
- HASH ARRAY any ARRAY elements exist as HASH keys
- like: grep { exists HASH->{$_} } ARRAY
- Regexp ARRAY any ARRAY elements pattern match Regexp
- like: grep { /Regexp/ } ARRAY
- undef ARRAY undef in ARRAY
- like: grep { !defined } ARRAY
- Any ARRAY smartmatch each ARRAY element[3]
- like: grep { Any ~~ $_ } ARRAY
-
- Right operand is a HASH:
-
- Left Right Description and pseudocode
- ===============================================================
- HASH1 HASH2 all same keys in both HASHes
- like: keys HASH1 ==
- grep { exists HASH2->{$_} } keys HASH1
- ARRAY HASH any ARRAY elements exist as HASH keys
- like: grep { exists HASH->{$_} } ARRAY
- Regexp HASH any HASH keys pattern match Regexp
- like: grep { /Regexp/ } keys HASH
- undef HASH always false (undef can't be a key)
- like: 0 == 1
- Any HASH HASH key existence
- like: exists HASH->{Any}
-
- Right operand is CODE:
-
- Left Right Description and pseudocode
- ===============================================================
- ARRAY CODE sub returns true on all ARRAY elements[1]
- like: !grep { !CODE->($_) } ARRAY
- HASH CODE sub returns true on all HASH keys[1]
- like: !grep { !CODE->($_) } keys HASH
- Any CODE sub passed Any returns true
- like: CODE->(Any)
-
-Right operand is a Regexp:
-
- Left Right Description and pseudocode
- ===============================================================
- ARRAY Regexp any ARRAY elements match Regexp
- like: grep { /Regexp/ } ARRAY
- HASH Regexp any HASH keys match Regexp
- like: grep { /Regexp/ } keys HASH
- Any Regexp pattern match
- like: Any =~ /Regexp/
-
- Other:
-
- Left Right Description and pseudocode
- ===============================================================
- Object Any invoke ~~ overloading on Object,
- or fall back to...
-
- Any Num numeric equality
- like: Any == Num
- Num nummy[4] numeric equality
- like: Num == nummy
- undef Any check whether undefined
- like: !defined(Any)
- Any Any string equality
- like: Any eq Any
-
-
-Notes:
-
-=over
-
-=item 1.
-Empty hashes or arrays match.
-
-=item 2.
-That is, each element smartmatches the element of the same index in the other array.[3]
-
-=item 3.
-If a circular reference is found, fall back to referential equality.
-
-=item 4.
-Either an actual number, or a string that looks like one.
-
-=back
-
-The smartmatch implicitly dereferences any non-blessed hash or array
-reference, so the C<I<HASH>> and C<I<ARRAY>> entries apply in those cases.
-For blessed references, the C<I<Object>> entries apply. Smartmatches
-involving hashes only consider hash keys, never hash values.
-
-The "like" code entry is not always an exact rendition. For example, the
-smartmatch operator short-circuits whenever possible, but C<grep> does
-not. Also, C<grep> in scalar context returns the number of matches, but
-C<~~> returns only true or false.
-
-Unlike most operators, the smartmatch operator knows to treat C<undef>
-specially:
-
- use v5.10.1;
- @array = (1, 2, 3, undef, 4, 5);
- say "some elements undefined" if undef ~~ @array;
-
-Each operand is considered in a modified scalar context, the modification
-being that array and hash variables are passed by reference to the
-operator, which implicitly dereferences them. Both elements
-of each pair are the same:
-
- use v5.10.1;
-
- my %hash = (red => 1, blue => 2, green => 3,
- orange => 4, yellow => 5, purple => 6,
- black => 7, grey => 8, white => 9);
-
- my @array = qw(red blue green);
-
- say "some array elements in hash keys" if @array ~~ %hash;
- say "some array elements in hash keys" if \@array ~~ \%hash;
-
- say "red in array" if "red" ~~ @array;
- say "red in array" if "red" ~~ \@array;
-
- say "some keys end in e" if /e$/ ~~ %hash;
- say "some keys end in e" if /e$/ ~~ \%hash;
-
-Two arrays smartmatch if each element in the first array smartmatches
-(that is, is "in") the corresponding element in the second array,
-recursively.
-
- use v5.10.1;
- my @little = qw(red blue green);
- my @bigger = ("red", "blue", [ "orange", "green" ] );
- if (@little ~~ @bigger) { # true!
- say "little is contained in bigger";
- }
-
-Because the smartmatch operator recurses on nested arrays, this
-will still report that "red" is in the array.
-
- use v5.10.1;
- my @array = qw(red blue green);
- my $nested_array = [[[[[[[ @array ]]]]]]];
- say "red in array" if "red" ~~ $nested_array;
-
-If two arrays smartmatch each other, then they are deep
-copies of each others' values, as this example reports:
-
- use v5.12.0;
- my @a = (0, 1, 2, [3, [4, 5], 6], 7);
- my @b = (0, 1, 2, [3, [4, 5], 6], 7);
-
- if (@a ~~ @b && @b ~~ @a) {
- say "a and b are deep copies of each other";
- }
- elsif (@a ~~ @b) {
- say "a smartmatches in b";
- }
- elsif (@b ~~ @a) {
- say "b smartmatches in a";
- }
- else {
- say "a and b don't smartmatch each other at all";
- }
-
-
-If you were to set C<$b[3] = 4>, then instead of reporting that "a and b
-are deep copies of each other", it now reports that "b smartmatches in a".
-That because the corresponding position in C<@a> contains an array that
-(eventually) has a 4 in it.
-
-Smartmatching one hash against another reports whether both contain the
-same keys, no more and no less. This could be used to see whether two
-records have the same field names, without caring what values those fields
-might have. For example:
-
- use v5.10.1;
- sub make_dogtag {
- state $REQUIRED_FIELDS = { name=>1, rank=>1, serial_num=>1 };
-
- my ($class, $init_fields) = @_;
-
- die "Must supply (only) name, rank, and serial number"
- unless $init_fields ~~ $REQUIRED_FIELDS;
-
- ...
- }
-
-or, if other non-required fields are allowed, use ARRAY ~~ HASH:
-
- use v5.10.1;
- sub make_dogtag {
- state $REQUIRED_FIELDS = { name=>1, rank=>1, serial_num=>1 };
-
- my ($class, $init_fields) = @_;
-
- die "Must supply (at least) name, rank, and serial number"
- unless [keys %{$init_fields}] ~~ $REQUIRED_FIELDS;
-
- ...
- }
-
-The smartmatch operator is most often used as the implicit operator of a
-C<when> clause. See the section on "Switch Statements" in L<perlsyn>.
-
-=head3 Smartmatching of Objects
-
-To avoid relying on an object's underlying representation, if the
-smartmatch's right operand is an object that doesn't overload C<~~>,
-it raises the exception "C<Smartmatching a non-overloaded object
-breaks encapsulation>". That's because one has no business digging
-around to see whether something is "in" an object. These are all
-illegal on objects without a C<~~> overload:
-
- %hash ~~ $object
- 42 ~~ $object
- "fred" ~~ $object
-
-However, you can change the way an object is smartmatched by overloading
-the C<~~> operator. This is allowed to extend the usual smartmatch semantics.
-For objects that do have an C<~~> overload, see L<overload>.
-
-Using an object as the left operand is allowed, although not very useful.
-Smartmatching rules take precedence over overloading, so even if the
-object in the left operand has smartmatch overloading, this will be
-ignored. A left operand that is a non-overloaded object falls back on a
-string or numeric comparison of whatever the C<ref> operator returns. That
-means that
-
- $object ~~ X
-
-does I<not> invoke the overload method with C<I<X>> as an argument.
-Instead the above table is consulted as normal, and based on the type of
-C<I<X>>, overloading may or may not be invoked. For simple strings or
-numbers, in becomes equivalent to this:
-
- $object ~~ $number ref($object) == $number
- $object ~~ $string ref($object) eq $string
-
-For example, this reports that the handle smells IOish
-(but please don't really do this!):
-
- use IO::Handle;
- my $fh = IO::Handle->new();
- if ($fh ~~ /\bIO\b/) {
- say "handle smells IOish";
- }
-
-That's because it treats C<$fh> as a string like
-C<"IO::Handle=GLOB(0x8039e0)">, then pattern matches against that.
-
-=head2 Bitwise And
-X<operator, bitwise, and> X<bitwise and> X<&>
-
-Binary "&" returns its operands ANDed together bit by bit.
-(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
-
-Note that "&" has lower priority than relational operators, so for example
-the parentheses are essential in a test like
-
- print "Even\n" if ($x & 1) == 0;
-
-=head2 Bitwise Or and Exclusive Or
-X<operator, bitwise, or> X<bitwise or> X<|> X<operator, bitwise, xor>
-X<bitwise xor> X<^>
-
-Binary "|" returns its operands ORed together bit by bit.
-(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
-
-Binary "^" returns its operands XORed together bit by bit.
-(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
-
-Note that "|" and "^" have lower priority than relational operators, so
-for example the brackets are essential in a test like
-
- print "false\n" if (8 | 2) != 10;
-
-=head2 C-style Logical And
-X<&&> X<logical and> X<operator, logical, and>
-
-Binary "&&" performs a short-circuit logical AND operation. That is,
-if the left operand is false, the right operand is not even evaluated.
-Scalar or list context propagates down to the right operand if it
-is evaluated.
-
-=head2 C-style Logical Or
-X<||> X<operator, logical, or>
-
-Binary "||" performs a short-circuit logical OR operation. That is,
-if the left operand is true, the right operand is not even evaluated.
-Scalar or list context propagates down to the right operand if it
-is evaluated.
-
-=head2 Logical Defined-Or
-X<//> X<operator, logical, defined-or>
-
-Although it has no direct equivalent in C, Perl's C<//> operator is related
-to its C-style or. In fact, it's exactly the same as C<||>, except that it
-tests the left hand side's definedness instead of its truth. Thus,
-C<< EXPR1 // EXPR2 >> returns the value of C<< EXPR1 >> if it's defined,
-otherwise, the value of C<< EXPR2 >> is returned. (C<< EXPR1 >> is evaluated
-in scalar context, C<< EXPR2 >> in the context of C<< // >> itself). Usually,
-this is the same result as C<< defined(EXPR1) ? EXPR1 : EXPR2 >> (except that
-the ternary-operator form can be used as a lvalue, while C<< EXPR1 // EXPR2 >>
-cannot). This is very useful for
-providing default values for variables. If you actually want to test if
-at least one of C<$a> and C<$b> is defined, use C<defined($a // $b)>.
-
-The C<||>, C<//> and C<&&> operators return the last value evaluated
-(unlike C's C<||> and C<&&>, which return 0 or 1). Thus, a reasonably
-portable way to find out the home directory might be:
-
- $home = $ENV{HOME}
- // $ENV{LOGDIR}
- // (getpwuid($<))[7]
- // die "You're homeless!\n";
-
-In particular, this means that you shouldn't use this
-for selecting between two aggregates for assignment:
-
- @a = @b || @c; # this is wrong
- @a = scalar(@b) || @c; # really meant this
- @a = @b ? @b : @c; # this works fine, though
-
-As alternatives to C<&&> and C<||> when used for
-control flow, Perl provides the C<and> and C<or> operators (see below).
-The short-circuit behavior is identical. The precedence of "and"
-and "or" is much lower, however, so that you can safely use them after a
-list operator without the need for parentheses:
-
- unlink "alpha", "beta", "gamma"
- or gripe(), next LINE;
-
-With the C-style operators that would have been written like this:
-
- unlink("alpha", "beta", "gamma")
- || (gripe(), next LINE);
-
-It would be even more readable to write that this way:
-
- unless(unlink("alpha", "beta", "gamma")) {
- gripe();
- next LINE;
- }
-
-Using "or" for assignment is unlikely to do what you want; see below.
-
-=head2 Range Operators
-X<operator, range> X<range> X<..> X<...>
-
-Binary ".." is the range operator, which is really two different
-operators depending on the context. In list context, it returns a
-list of values counting (up by ones) from the left value to the right
-value. If the left value is greater than the right value then it
-returns the empty list. The range operator is useful for writing
-C<foreach (1..10)> loops and for doing slice operations on arrays. In
-the current implementation, no temporary array is created when the
-range operator is used as the expression in C<foreach> loops, but older
-versions of Perl might burn a lot of memory when you write something
-like this:
-
- for (1 .. 1_000_000) {
- # code
- }
-
-The range operator also works on strings, using the magical
-auto-increment, see below.
-
-In scalar context, ".." returns a boolean value. The operator is
-bistable, like a flip-flop, and emulates the line-range (comma)
-operator of B<sed>, B<awk>, and various editors. Each ".." operator
-maintains its own boolean state, even across calls to a subroutine
-that contains it. It is false as long as its left operand is false.
-Once the left operand is true, the range operator stays true until the
-right operand is true, I<AFTER> which the range operator becomes false
-again. It doesn't become false till the next time the range operator
-is evaluated. It can test the right operand and become false on the
-same evaluation it became true (as in B<awk>), but it still returns
-true once. If you don't want it to test the right operand until the
-next evaluation, as in B<sed>, just use three dots ("...") instead of
-two. In all other regards, "..." behaves just like ".." does.
-
-The right operand is not evaluated while the operator is in the
-"false" state, and the left operand is not evaluated while the
-operator is in the "true" state. The precedence is a little lower
-than || and &&. The value returned is either the empty string for
-false, or a sequence number (beginning with 1) for true. The sequence
-number is reset for each range encountered. The final sequence number
-in a range has the string "E0" appended to it, which doesn't affect
-its numeric value, but gives you something to search for if you want
-to exclude the endpoint. You can exclude the beginning point by
-waiting for the sequence number to be greater than 1.
-
-If either operand of scalar ".." is a constant expression,
-that operand is considered true if it is equal (C<==>) to the current
-input line number (the C<$.> variable).
-
-To be pedantic, the comparison is actually C<int(EXPR) == int(EXPR)>,
-but that is only an issue if you use a floating point expression; when
-implicitly using C<$.> as described in the previous paragraph, the
-comparison is C<int(EXPR) == int($.)> which is only an issue when C<$.>
-is set to a floating point value and you are not reading from a file.
-Furthermore, C<"span" .. "spat"> or C<2.18 .. 3.14> will not do what
-you want in scalar context because each of the operands are evaluated
-using their integer representation.
-
-Examples:
-
-As a scalar operator:
-
- if (101 .. 200) { print; } # print 2nd hundred lines, short for
- # if ($. == 101 .. $. == 200) { print; }
-
- next LINE if (1 .. /^$/); # skip header lines, short for
- # next LINE if ($. == 1 .. /^$/);
- # (typically in a loop labeled LINE)
-
- s/^/> / if (/^$/ .. eof()); # quote body
-
- # parse mail messages
- while (<>) {
- $in_header = 1 .. /^$/;
- $in_body = /^$/ .. eof;
- if ($in_header) {
- # do something
- } else { # in body
- # do something else
- }
- } continue {
- close ARGV if eof; # reset $. each file
- }
-
-Here's a simple example to illustrate the difference between
-the two range operators:
-
- @lines = (" - Foo",
- "01 - Bar",
- "1 - Baz",
- " - Quux");
-
- foreach (@lines) {
- if (/0/ .. /1/) {
- print "$_\n";
- }
- }
-
-This program will print only the line containing "Bar". If
-the range operator is changed to C<...>, it will also print the
-"Baz" line.
-
-And now some examples as a list operator:
-
- for (101 .. 200) { print } # print $_ 100 times
- @foo = @foo[0 .. $#foo]; # an expensive no-op
- @foo = @foo[$#foo-4 .. $#foo]; # slice last 5 items
-
-The range operator (in list context) makes use of the magical
-auto-increment algorithm if the operands are strings. You
-can say
-
- @alphabet = ("A" .. "Z");
-
-to get all normal letters of the English alphabet, or
-
- $hexdigit = (0 .. 9, "a" .. "f")[$num & 15];
-
-to get a hexadecimal digit, or
-
- @z2 = ("01" .. "31");
- print $z2[$mday];
-
-to get dates with leading zeros.
-
-If the final value specified is not in the sequence that the magical
-increment would produce, the sequence goes until the next value would
-be longer than the final value specified.
-
-If the initial value specified isn't part of a magical increment
-sequence (that is, a non-empty string matching C</^[a-zA-Z]*[0-9]*\z/>),
-only the initial value will be returned. So the following will only
-return an alpha:
-
- use charnames "greek";
- my @greek_small = ("\N{alpha}" .. "\N{omega}");
-
-To get the 25 traditional lowercase Greek letters, including both sigmas,
-you could use this instead:
-
- use charnames "greek";
- my @greek_small = map { chr } ( ord("\N{alpha}")
- ..
- ord("\N{omega}")
- );
-
-However, because there are I<many> other lowercase Greek characters than
-just those, to match lowercase Greek characters in a regular expression,
-you would use the pattern C</(?:(?=\p{Greek})\p{Lower})+/>.
-
-Because each operand is evaluated in integer form, C<2.18 .. 3.14> will
-return two elements in list context.
-
- @list = (2.18 .. 3.14); # same as @list = (2 .. 3);
-
-=head2 Conditional Operator
-X<operator, conditional> X<operator, ternary> X<ternary> X<?:>
-
-Ternary "?:" is the conditional operator, just as in C. It works much
-like an if-then-else. If the argument before the ? is true, the
-argument before the : is returned, otherwise the argument after the :
-is returned. For example:
-
- printf "I have %d dog%s.\n", $n,
- ($n == 1) ? "" : "s";
-
-Scalar or list context propagates downward into the 2nd
-or 3rd argument, whichever is selected.
-
- $a = $ok ? $b : $c; # get a scalar
- @a = $ok ? @b : @c; # get an array
- $a = $ok ? @b : @c; # oops, that's just a count!
-
-The operator may be assigned to if both the 2nd and 3rd arguments are
-legal lvalues (meaning that you can assign to them):
-
- ($a_or_b ? $a : $b) = $c;
-
-Because this operator produces an assignable result, using assignments
-without parentheses will get you in trouble. For example, this:
-
- $a % 2 ? $a += 10 : $a += 2
-
-Really means this:
-
- (($a % 2) ? ($a += 10) : $a) += 2
-
-Rather than this:
-
- ($a % 2) ? ($a += 10) : ($a += 2)
-
-That should probably be written more simply as:
-
- $a += ($a % 2) ? 10 : 2;
-
-=head2 Assignment Operators
-X<assignment> X<operator, assignment> X<=> X<**=> X<+=> X<*=> X<&=>
-X<<< <<= >>> X<&&=> X<-=> X</=> X<|=> X<<< >>= >>> X<||=> X<//=> X<.=>
-X<%=> X<^=> X<x=>
-
-"=" is the ordinary assignment operator.
-
-Assignment operators work as in C. That is,
-
- $a += 2;
-
-is equivalent to
-
- $a = $a + 2;
-
-although without duplicating any side effects that dereferencing the lvalue
-might trigger, such as from tie(). Other assignment operators work similarly.
-The following are recognized:
-
- **= += *= &= <<= &&=
- -= /= |= >>= ||=
- .= %= ^= //=
- x=
-
-Although these are grouped by family, they all have the precedence
-of assignment.
-
-Unlike in C, the scalar assignment operator produces a valid lvalue.
-Modifying an assignment is equivalent to doing the assignment and
-then modifying the variable that was assigned to. This is useful
-for modifying a copy of something, like this:
-
- ($tmp = $global) =~ tr/13579/24680/;
-
-Although as of 5.14, that can be also be accomplished this way:
-
- use v5.14;
- $tmp = ($global =~ tr/13579/24680/r);
-
-Likewise,
-
- ($a += 2) *= 3;
-
-is equivalent to
-
- $a += 2;
- $a *= 3;
-
-Similarly, a list assignment in list context produces the list of
-lvalues assigned to, and a list assignment in scalar context returns
-the number of elements produced by the expression on the right hand
-side of the assignment.
-
-=head2 Comma Operator
-X<comma> X<operator, comma> X<,>
-
-Binary "," is the comma operator. In scalar context it evaluates
-its left argument, throws that value away, then evaluates its right
-argument and returns that value. This is just like C's comma operator.
-
-In list context, it's just the list argument separator, and inserts
-both its arguments into the list. These arguments are also evaluated
-from left to right.
-
-The C<< => >> operator is a synonym for the comma except that it causes a
-word on its left to be interpreted as a string if it begins with a letter
-or underscore and is composed only of letters, digits and underscores.
-This includes operands that might otherwise be interpreted as operators,
-constants, single number v-strings or function calls. If in doubt about
-this behavior, the left operand can be quoted explicitly.
-
-Otherwise, the C<< => >> operator behaves exactly as the comma operator
-or list argument separator, according to context.
-
-For example:
-
- use constant FOO => "something";
-
- my %h = ( FOO => 23 );
-
-is equivalent to:
-
- my %h = ("FOO", 23);
-
-It is I<NOT>:
-
- my %h = ("something", 23);
-
-The C<< => >> operator is helpful in documenting the correspondence
-between keys and values in hashes, and other paired elements in lists.
-
- %hash = ( $key => $value );
- login( $username => $password );
-
-The special quoting behavior ignores precedence, and hence may apply to
-I<part> of the left operand:
-
- print time.shift => "bbb";
-
-That example prints something like "1314363215shiftbbb", because the
-C<< => >> implicitly quotes the C<shift> immediately on its left, ignoring
-the fact that C<time.shift> is the entire left operand.
-
-=head2 List Operators (Rightward)
-X<operator, list, rightward> X<list operator>
-
-On the right side of a list operator, the comma has very low precedence,
-such that it controls all comma-separated expressions found there.
-The only operators with lower precedence are the logical operators
-"and", "or", and "not", which may be used to evaluate calls to list
-operators without the need for parentheses:
-
- open HANDLE, "< :utf8", "filename" or die "Can't open: $!\n";
-
-However, some people find that code harder to read than writing
-it with parentheses:
-
- open(HANDLE, "< :utf8", "filename") or die "Can't open: $!\n";
-
-in which case you might as well just use the more customary "||" operator:
-
- open(HANDLE, "< :utf8", "filename") || die "Can't open: $!\n";
-
-See also discussion of list operators in L<Terms and List Operators (Leftward)>.
-
-=head2 Logical Not
-X<operator, logical, not> X<not>
-
-Unary "not" returns the logical negation of the expression to its right.
-It's the equivalent of "!" except for the very low precedence.
-
-=head2 Logical And
-X<operator, logical, and> X<and>
-
-Binary "and" returns the logical conjunction of the two surrounding
-expressions. It's equivalent to C<&&> except for the very low
-precedence. This means that it short-circuits: the right
-expression is evaluated only if the left expression is true.
-
-=head2 Logical or and Exclusive Or
-X<operator, logical, or> X<operator, logical, xor>
-X<operator, logical, exclusive or>
-X<or> X<xor>
-
-Binary "or" returns the logical disjunction of the two surrounding
-expressions. It's equivalent to C<||> except for the very low precedence.
-This makes it useful for control flow:
-
- print FH $data or die "Can't write to FH: $!";
-
-This means that it short-circuits: the right expression is evaluated
-only if the left expression is false. Due to its precedence, you must
-be careful to avoid using it as replacement for the C<||> operator.
-It usually works out better for flow control than in assignments:
-
- $a = $b or $c; # bug: this is wrong
- ($a = $b) or $c; # really means this
- $a = $b || $c; # better written this way
-
-However, when it's a list-context assignment and you're trying to use
-C<||> for control flow, you probably need "or" so that the assignment
-takes higher precedence.
-
- @info = stat($file) || die; # oops, scalar sense of stat!
- @info = stat($file) or die; # better, now @info gets its due
-
-Then again, you could always use parentheses.
-
-Binary C<xor> returns the exclusive-OR of the two surrounding expressions.
-It cannot short-circuit (of course).
-
-There is no low precedence operator for defined-OR.
-
-=head2 C Operators Missing From Perl
-X<operator, missing from perl> X<&> X<*>
-X<typecasting> X<(TYPE)>
-
-Here is what C has that Perl doesn't:
-
-=over 8
-
-=item unary &
-
-Address-of operator. (But see the "\" operator for taking a reference.)
-
-=item unary *
-
-Dereference-address operator. (Perl's prefix dereferencing
-operators are typed: $, @, %, and &.)
-
-=item (TYPE)
-
-Type-casting operator.
-
-=back
-
-=head2 Quote and Quote-like Operators
-X<operator, quote> X<operator, quote-like> X<q> X<qq> X<qx> X<qw> X<m>
-X<qr> X<s> X<tr> X<'> X<''> X<"> X<""> X<//> X<`> X<``> X<<< << >>>
-X<escape sequence> X<escape>
-
-While we usually think of quotes as literal values, in Perl they
-function as operators, providing various kinds of interpolating and
-pattern matching capabilities. Perl provides customary quote characters
-for these behaviors, but also provides a way for you to choose your
-quote character for any of them. In the following table, a C<{}> represents
-any pair of delimiters you choose.
-
- Customary Generic Meaning Interpolates
- '' q{} Literal no
- "" qq{} Literal yes
- `` qx{} Command yes*
- qw{} Word list no
- // m{} Pattern match yes*
- qr{} Pattern yes*
- s{}{} Substitution yes*
- tr{}{} Transliteration no (but see below)
- y{}{} Transliteration no (but see below)
- <<EOF here-doc yes*
-
- * unless the delimiter is ''.
-
-Non-bracketing delimiters use the same character fore and aft, but the four
-sorts of ASCII brackets (round, angle, square, curly) all nest, which means
-that
-
- q{foo{bar}baz}
-
-is the same as
-
- 'foo{bar}baz'
-
-Note, however, that this does not always work for quoting Perl code:
-
- $s = q{ if($a eq "}") ... }; # WRONG
-
-is a syntax error. The C<Text::Balanced> module (standard as of v5.8,
-and from CPAN before then) is able to do this properly.
-
-There can be whitespace between the operator and the quoting
-characters, except when C<#> is being used as the quoting character.
-C<q#foo#> is parsed as the string C<foo>, while C<q #foo#> is the
-operator C<q> followed by a comment. Its argument will be taken
-from the next line. This allows you to write:
-
- s {foo} # Replace foo
- {bar} # with bar.
-
-The following escape sequences are available in constructs that interpolate,
-and in transliterations:
-X<\t> X<\n> X<\r> X<\f> X<\b> X<\a> X<\e> X<\x> X<\0> X<\c> X<\N> X<\N{}>
-X<\o{}>
-
- Sequence Note Description
- \t tab (HT, TAB)
- \n newline (NL)
- \r return (CR)
- \f form feed (FF)
- \b backspace (BS)
- \a alarm (bell) (BEL)
- \e escape (ESC)
- \x{263A} [1,8] hex char (example: SMILEY)
- \x1b [2,8] restricted range hex char (example: ESC)
- \N{name} [3] named Unicode character or character sequence
- \N{U+263D} [4,8] Unicode character (example: FIRST QUARTER MOON)
- \c[ [5] control char (example: chr(27))
- \o{23072} [6,8] octal char (example: SMILEY)
- \033 [7,8] restricted range octal char (example: ESC)
-
-=over 4
-
-=item [1]
-
-The result is the character specified by the hexadecimal number between
-the braces. See L</[8]> below for details on which character.
-
-Only hexadecimal digits are valid between the braces. If an invalid
-character is encountered, a warning will be issued and the invalid
-character and all subsequent characters (valid or invalid) within the
-braces will be discarded.
-
-If there are no valid digits between the braces, the generated character is
-the NULL character (C<\x{00}>). However, an explicit empty brace (C<\x{}>)
-will not cause a warning (currently).
-
-=item [2]
-
-The result is the character specified by the hexadecimal number in the range
-0x00 to 0xFF. See L</[8]> below for details on which character.
-
-Only hexadecimal digits are valid following C<\x>. When C<\x> is followed
-by fewer than two valid digits, any valid digits will be zero-padded. This
-means that C<\x7> will be interpreted as C<\x07>, and a lone <\x> will be
-interpreted as C<\x00>. Except at the end of a string, having fewer than
-two valid digits will result in a warning. Note that although the warning
-says the illegal character is ignored, it is only ignored as part of the
-escape and will still be used as the subsequent character in the string.
-For example:
-
- Original Result Warns?
- "\x7" "\x07" no
- "\x" "\x00" no
- "\x7q" "\x07q" yes
- "\xq" "\x00q" yes
-
-=item [3]
-
-The result is the Unicode character or character sequence given by I<name>.
-See L<charnames>.
-
-=item [4]
-
-C<\N{U+I<hexadecimal number>}> means the Unicode character whose Unicode code
-point is I<hexadecimal number>.
-
-=item [5]
-
-The character following C<\c> is mapped to some other character as shown in the
-table:
-
- Sequence Value
- \c@ chr(0)
- \cA chr(1)
- \ca chr(1)
- \cB chr(2)
- \cb chr(2)
- ...
- \cZ chr(26)
- \cz chr(26)
- \c[ chr(27)
- \c] chr(29)
- \c^ chr(30)
- \c? chr(127)
-
-In other words, it's the character whose code point has had 64 xor'd with
-its uppercase. C<\c?> is DELETE because C<ord("@") ^ 64> is 127, and
-C<\c@> is NULL because the ord of "@" is 64, so xor'ing 64 itself produces 0.
-
-Also, C<\c\I<X>> yields C< chr(28) . "I<X>"> for any I<X>, but cannot come at the
-end of a string, because the backslash would be parsed as escaping the end
-quote.
-
-On ASCII platforms, the resulting characters from the list above are the
-complete set of ASCII controls. This isn't the case on EBCDIC platforms; see
-L<perlebcdic/OPERATOR DIFFERENCES> for the complete list of what these
-sequences mean on both ASCII and EBCDIC platforms.
-
-Use of any other character following the "c" besides those listed above is
-discouraged, and some are deprecated with the intention of removing
-those in a later Perl version. What happens for any of these
-other characters currently though, is that the value is derived by xor'ing
-with the seventh bit, which is 64.
-
-To get platform independent controls, you can use C<\N{...}>.
-
-=item [6]
-
-The result is the character specified by the octal number between the braces.
-See L</[8]> below for details on which character.
-
-If a character that isn't an octal digit is encountered, a warning is raised,
-and the value is based on the octal digits before it, discarding it and all
-following characters up to the closing brace. It is a fatal error if there are
-no octal digits at all.
-
-=item [7]
-
-The result is the character specified by the three-digit octal number in the
-range 000 to 777 (but best to not use above 077, see next paragraph). See
-L</[8]> below for details on which character.
-
-Some contexts allow 2 or even 1 digit, but any usage without exactly
-three digits, the first being a zero, may give unintended results. (For
-example, in a regular expression it may be confused with a backreference;
-see L<perlrebackslash/Octal escapes>.) Starting in Perl 5.14, you may
-use C<\o{}> instead, which avoids all these problems. Otherwise, it is best to
-use this construct only for ordinals C<\077> and below, remembering to pad to
-the left with zeros to make three digits. For larger ordinals, either use
-C<\o{}>, or convert to something else, such as to hex and use C<\x{}>
-instead.
-
-Having fewer than 3 digits may lead to a misleading warning message that says
-that what follows is ignored. For example, C<"\128"> in the ASCII character set
-is equivalent to the two characters C<"\n8">, but the warning C<Illegal octal
-digit '8' ignored> will be thrown. If C<"\n8"> is what you want, you can
-avoid this warning by padding your octal number with C<0>'s: C<"\0128">.
-
-=item [8]
-
-Several constructs above specify a character by a number. That number
-gives the character's position in the character set encoding (indexed from 0).
-This is called synonymously its ordinal, code position, or code point. Perl
-works on platforms that have a native encoding currently of either ASCII/Latin1
-or EBCDIC, each of which allow specification of 256 characters. In general, if
-the number is 255 (0xFF, 0377) or below, Perl interprets this in the platform's
-native encoding. If the number is 256 (0x100, 0400) or above, Perl interprets
-it as a Unicode code point and the result is the corresponding Unicode
-character. For example C<\x{50}> and C<\o{120}> both are the number 80 in
-decimal, which is less than 256, so the number is interpreted in the native
-character set encoding. In ASCII the character in the 80th position (indexed
-from 0) is the letter "P", and in EBCDIC it is the ampersand symbol "&".
-C<\x{100}> and C<\o{400}> are both 256 in decimal, so the number is interpreted
-as a Unicode code point no matter what the native encoding is. The name of the
-character in the 256th position (indexed by 0) in Unicode is
-C<LATIN CAPITAL LETTER A WITH MACRON>.
-
-There are a couple of exceptions to the above rule. S<C<\N{U+I<hex number>}>> is
-always interpreted as a Unicode code point, so that C<\N{U+0050}> is "P" even
-on EBCDIC platforms. And if L<C<S<use encoding>>|encoding> is in effect, the
-number is considered to be in that encoding, and is translated from that into
-the platform's native encoding if there is a corresponding native character;
-otherwise to Unicode.
-
-=back
-
-B<NOTE>: Unlike C and other languages, Perl has no C<\v> escape sequence for
-the vertical tab (VT - ASCII 11), but you may use C<\ck> or C<\x0b>. (C<\v>
-does have meaning in regular expression patterns in Perl, see L<perlre>.)
-
-The following escape sequences are available in constructs that interpolate,
-but not in transliterations.
-X<\l> X<\u> X<\L> X<\U> X<\E> X<\Q> X<\F>
-
- \l lowercase next character only
- \u titlecase (not uppercase!) next character only
- \L lowercase all characters till \E or end of string
- \U uppercase all characters till \E or end of string
- \F foldcase all characters till \E or end of string
- \Q quote (disable) pattern metacharacters till \E or
- end of string
- \E end either case modification or quoted section
- (whichever was last seen)
-
-See L<perlfunc/quotemeta> for the exact definition of characters that
-are quoted by C<\Q>.
-
-C<\L>, C<\U>, C<\F>, and C<\Q> can stack, in which case you need one
-C<\E> for each. For example:
-
- say"This \Qquoting \ubusiness \Uhere isn't quite\E done yet,\E is it?";
- This quoting\ Business\ HERE\ ISN\'T\ QUITE\ done\ yet\, is it?
-
-If C<use locale> is in effect (but not C<use locale ':not_characters'>),
-the case map used by C<\l>, C<\L>,
-C<\u>, and C<\U> is taken from the current locale. See L<perllocale>.
-If Unicode (for example, C<\N{}> or code points of 0x100 or
-beyond) is being used, the case map used by C<\l>, C<\L>, C<\u>, and
-C<\U> is as defined by Unicode. That means that case-mapping
-a single character can sometimes produce several characters.
-Under C<use locale>, C<\F> produces the same results as C<\L>.
-
-All systems use the virtual C<"\n"> to represent a line terminator,
-called a "newline". There is no such thing as an unvarying, physical
-newline character. It is only an illusion that the operating system,
-device drivers, C libraries, and Perl all conspire to preserve. Not all
-systems read C<"\r"> as ASCII CR and C<"\n"> as ASCII LF. For example,
-on the ancient Macs (pre-MacOS X) of yesteryear, these used to be reversed,
-and on systems without line terminator,
-printing C<"\n"> might emit no actual data. In general, use C<"\n"> when
-you mean a "newline" for your system, but use the literal ASCII when you
-need an exact character. For example, most networking protocols expect
-and prefer a CR+LF (C<"\015\012"> or C<"\cM\cJ">) for line terminators,
-and although they often accept just C<"\012">, they seldom tolerate just
-C<"\015">. If you get in the habit of using C<"\n"> for networking,
-you may be burned some day.
-X<newline> X<line terminator> X<eol> X<end of line>
-X<\n> X<\r> X<\r\n>
-
-For constructs that do interpolate, variables beginning with "C<$>"
-or "C<@>" are interpolated. Subscripted variables such as C<$a[3]> or
-C<< $href->{key}[0] >> are also interpolated, as are array and hash slices.
-But method calls such as C<< $obj->meth >> are not.
-
-Interpolating an array or slice interpolates the elements in order,
-separated by the value of C<$">, so is equivalent to interpolating
-C<join $", @array>. "Punctuation" arrays such as C<@*> are usually
-interpolated only if the name is enclosed in braces C<@{*}>, but the
-arrays C<@_>, C<@+>, and C<@-> are interpolated even without braces.
-
-For double-quoted strings, the quoting from C<\Q> is applied after
-interpolation and escapes are processed.
-
- "abc\Qfoo\tbar$s\Exyz"
-
-is equivalent to
-
- "abc" . quotemeta("foo\tbar$s") . "xyz"
-
-For the pattern of regex operators (C<qr//>, C<m//> and C<s///>),
-the quoting from C<\Q> is applied after interpolation is processed,
-but before escapes are processed. This allows the pattern to match
-literally (except for C<$> and C<@>). For example, the following matches:
-
- '\s\t' =~ /\Q\s\t/
-
-Because C<$> or C<@> trigger interpolation, you'll need to use something
-like C</\Quser\E\@\Qhost/> to match them literally.
-
-Patterns are subject to an additional level of interpretation as a
-regular expression. This is done as a second pass, after variables are
-interpolated, so that regular expressions may be incorporated into the
-pattern from the variables. If this is not what you want, use C<\Q> to
-interpolate a variable literally.
-
-Apart from the behavior described above, Perl does not expand
-multiple levels of interpolation. In particular, contrary to the
-expectations of shell programmers, back-quotes do I<NOT> interpolate
-within double quotes, nor do single quotes impede evaluation of
-variables when used within double quotes.
-
-=head2 Regexp Quote-Like Operators
-X<operator, regexp>
-
-Here are the quote-like operators that apply to pattern
-matching and related activities.
-
-=over 8
-
-=item qr/STRING/msixpodual
-X<qr> X</i> X</m> X</o> X</s> X</x> X</p>
-
-This operator quotes (and possibly compiles) its I<STRING> as a regular
-expression. I<STRING> is interpolated the same way as I<PATTERN>
-in C<m/PATTERN/>. If "'" is used as the delimiter, no interpolation
-is done. Returns a Perl value which may be used instead of the
-corresponding C</STRING/msixpodual> expression. The returned value is a
-normalized version of the original pattern. It magically differs from
-a string containing the same characters: C<ref(qr/x/)> returns "Regexp";
-however, dereferencing it is not well defined (you currently get the
-normalized version of the original pattern, but this may change).
-
-
-For example,
-
- $rex = qr/my.STRING/is;
- print $rex; # prints (?si-xm:my.STRING)
- s/$rex/foo/;
-
-is equivalent to
-
- s/my.STRING/foo/is;
-
-The result may be used as a subpattern in a match:
-
- $re = qr/$pattern/;
- $string =~ /foo${re}bar/; # can be interpolated in other patterns
- $string =~ $re; # or used standalone
- $string =~ /$re/; # or this way
-
-Since Perl may compile the pattern at the moment of execution of the qr()
-operator, using qr() may have speed advantages in some situations,
-notably if the result of qr() is used standalone:
-
- sub match {
- my $patterns = shift;
- my @compiled = map qr/$_/i, @$patterns;
- grep {
- my $success = 0;
- foreach my $pat (@compiled) {
- $success = 1, last if /$pat/;
- }
- $success;
- } @_;
- }
-
-Precompilation of the pattern into an internal representation at
-the moment of qr() avoids a need to recompile the pattern every
-time a match C</$pat/> is attempted. (Perl has many other internal
-optimizations, but none would be triggered in the above example if
-we did not use qr() operator.)
-
-Options (specified by the following modifiers) are:
-
- m Treat string as multiple lines.
- s Treat string as single line. (Make . match a newline)
- i Do case-insensitive pattern matching.
- x Use extended regular expressions.
- p When matching preserve a copy of the matched string so
- that ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be defined.
- o Compile pattern only once.
- a ASCII-restrict: Use ASCII for \d, \s, \w; specifying two a's
- further restricts /i matching so that no ASCII character will
- match a non-ASCII one
- l Use the locale
- u Use Unicode rules
- d Use Unicode or native charset, as in 5.12 and earlier
-
-If a precompiled pattern is embedded in a larger pattern then the effect
-of "msixpluad" will be propagated appropriately. The effect the "o"
-modifier has is not propagated, being restricted to those patterns
-explicitly using it.
-
-The last four modifiers listed above, added in Perl 5.14,
-control the character set semantics, but C</a> is the only one you are likely
-to want to specify explicitly; the other three are selected
-automatically by various pragmas.
-
-See L<perlre> for additional information on valid syntax for STRING, and
-for a detailed look at the semantics of regular expressions. In
-particular, all modifiers except the largely obsolete C</o> are further
-explained in L<perlre/Modifiers>. C</o> is described in the next section.
-
-=item m/PATTERN/msixpodualgc
-X<m> X<operator, match>
-X<regexp, options> X<regexp> X<regex, options> X<regex>
-X</m> X</s> X</i> X</x> X</p> X</o> X</g> X</c>
-
-=item /PATTERN/msixpodualgc
-
-Searches a string for a pattern match, and in scalar context returns
-true if it succeeds, false if it fails. If no string is specified
-via the C<=~> or C<!~> operator, the $_ string is searched. (The
-string specified with C<=~> need not be an lvalue--it may be the
-result of an expression evaluation, but remember the C<=~> binds
-rather tightly.) See also L<perlre>.
-
-Options are as described in C<qr//> above; in addition, the following match
-process modifiers are available:
-
- g Match globally, i.e., find all occurrences.
- c Do not reset search position on a failed match when /g is in effect.
-
-If "/" is the delimiter then the initial C<m> is optional. With the C<m>
-you can use any pair of non-whitespace (ASCII) characters
-as delimiters. This is particularly useful for matching path names
-that contain "/", to avoid LTS (leaning toothpick syndrome). If "?" is
-the delimiter, then a match-only-once rule applies,
-described in C<m?PATTERN?> below.
-If "'" is the delimiter, no interpolation is performed on the PATTERN.
-When using a character valid in an identifier, whitespace is required
-after the C<m>.
-
-PATTERN may contain variables, which will be interpolated
-every time the pattern search is evaluated, except
-for when the delimiter is a single quote. (Note that C<$(>, C<$)>, and
-C<$|> are not interpolated because they look like end-of-string tests.)
-Perl will not recompile the pattern unless an interpolated
-variable that it contains changes. You can force Perl to skip the
-test and never recompile by adding a C</o> (which stands for "once")
-after the trailing delimiter.
-Once upon a time, Perl would recompile regular expressions
-unnecessarily, and this modifier was useful to tell it not to do so, in the
-interests of speed. But now, the only reasons to use C</o> are either:
-
-=over
-
-=item 1
-
-The variables are thousands of characters long and you know that they
-don't change, and you need to wring out the last little bit of speed by
-having Perl skip testing for that. (There is a maintenance penalty for
-doing this, as mentioning C</o> constitutes a promise that you won't
-change the variables in the pattern. If you do change them, Perl won't
-even notice.)
-
-=item 2
-
-you want the pattern to use the initial values of the variables
-regardless of whether they change or not. (But there are saner ways
-of accomplishing this than using C</o>.)
-
-=back
-
-The bottom line is that using C</o> is almost never a good idea.
-
-=item The empty pattern //
-
-If the PATTERN evaluates to the empty string, the last
-I<successfully> matched regular expression is used instead. In this
-case, only the C<g> and C<c> flags on the empty pattern are honored;
-the other flags are taken from the original pattern. If no match has
-previously succeeded, this will (silently) act instead as a genuine
-empty pattern (which will always match).
-
-Note that it's possible to confuse Perl into thinking C<//> (the empty
-regex) is really C<//> (the defined-or operator). Perl is usually pretty
-good about this, but some pathological cases might trigger this, such as
-C<$a///> (is that C<($a) / (//)> or C<$a // />?) and C<print $fh //>
-(C<print $fh(//> or C<print($fh //>?). In all of these examples, Perl
-will assume you meant defined-or. If you meant the empty regex, just
-use parentheses or spaces to disambiguate, or even prefix the empty
-regex with an C<m> (so C<//> becomes C<m//>).
-
-=item Matching in list context
-
-If the C</g> option is not used, C<m//> in list context returns a
-list consisting of the subexpressions matched by the parentheses in the
-pattern, that is, (C<$1>, C<$2>, C<$3>...). (Note that here C<$1> etc. are
-also set, and that this differs from Perl 4's behavior.) When there are
-no parentheses in the pattern, the return value is the list C<(1)> for
-success. With or without parentheses, an empty list is returned upon
-failure.
-
-Examples:
-
- open(TTY, "+</dev/tty")
- || die "can't access /dev/tty: $!";
-
- <TTY> =~ /^y/i && foo(); # do foo if desired
-
- if (/Version: *([0-9.]*)/) { $version = $1; }
-
- next if m#^/usr/spool/uucp#;
-
- # poor man's grep
- $arg = shift;
- while (<>) {
- print if /$arg/o; # compile only once (no longer needed!)
- }
-
- if (($F1, $F2, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/))
-
-This last example splits $foo into the first two words and the
-remainder of the line, and assigns those three fields to $F1, $F2, and
-$Etc. The conditional is true if any variables were assigned; that is,
-if the pattern matched.
-
-The C</g> modifier specifies global pattern matching--that is,
-matching as many times as possible within the string. How it behaves
-depends on the context. In list context, it returns a list of the
-substrings matched by any capturing parentheses in the regular
-expression. If there are no parentheses, it returns a list of all
-the matched strings, as if there were parentheses around the whole
-pattern.
-
-In scalar context, each execution of C<m//g> finds the next match,
-returning true if it matches, and false if there is no further match.
-The position after the last match can be read or set using the C<pos()>
-function; see L<perlfunc/pos>. A failed match normally resets the
-search position to the beginning of the string, but you can avoid that
-by adding the C</c> modifier (for example, C<m//gc>). Modifying the target
-string also resets the search position.
-
-=item \G assertion
-
-You can intermix C<m//g> matches with C<m/\G.../g>, where C<\G> is a
-zero-width assertion that matches the exact position where the
-previous C<m//g>, if any, left off. Without the C</g> modifier, the
-C<\G> assertion still anchors at C<pos()> as it was at the start of
-the operation (see L<perlfunc/pos>), but the match is of course only
-attempted once. Using C<\G> without C</g> on a target string that has
-not previously had a C</g> match applied to it is the same as using
-the C<\A> assertion to match the beginning of the string. Note also
-that, currently, C<\G> is only properly supported when anchored at the
-very beginning of the pattern.
-
-Examples:
-
- # list context
- ($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g);
-
- # scalar context
- local $/ = "";
- while ($paragraph = <>) {
- while ($paragraph =~ /\p{Ll}['")]*[.!?]+['")]*\s/g) {
- $sentences++;
- }
- }
- say $sentences;
-
-Here's another way to check for sentences in a paragraph:
-
- my $sentence_rx = qr{
- (?: (?<= ^ ) | (?<= \s ) ) # after start-of-string or whitespace
- \p{Lu} # capital letter
- .*? # a bunch of anything
- (?<= \S ) # that ends in non-whitespace
- (?<! \b [DMS]r ) # but isn't a common abbreviation
- (?<! \b Mrs )
- (?<! \b Sra )
- (?<! \b St )
- [.?!] # followed by a sentence ender
- (?= $ | \s ) # in front of end-of-string or whitespace
- }sx;
- local $/ = "";
- while (my $paragraph = <>) {
- say "NEW PARAGRAPH";
- my $count = 0;
- while ($paragraph =~ /($sentence_rx)/g) {
- printf "\tgot sentence %d: <%s>\n", ++$count, $1;
- }
- }
-
-Here's how to use C<m//gc> with C<\G>:
-
- $_ = "ppooqppqq";
- while ($i++ < 2) {
- print "1: '";
- print $1 while /(o)/gc; print "', pos=", pos, "\n";
- print "2: '";
- print $1 if /\G(q)/gc; print "', pos=", pos, "\n";
- print "3: '";
- print $1 while /(p)/gc; print "', pos=", pos, "\n";
- }
- print "Final: '$1', pos=",pos,"\n" if /\G(.)/;
-
-The last example should print:
-
- 1: 'oo', pos=4
- 2: 'q', pos=5
- 3: 'pp', pos=7
- 1: '', pos=7
- 2: 'q', pos=8
- 3: '', pos=8
- Final: 'q', pos=8
-
-Notice that the final match matched C<q> instead of C<p>, which a match
-without the C<\G> anchor would have done. Also note that the final match
-did not update C<pos>. C<pos> is only updated on a C</g> match. If the
-final match did indeed match C<p>, it's a good bet that you're running a
-very old (pre-5.6.0) version of Perl.
-
-A useful idiom for C<lex>-like scanners is C</\G.../gc>. You can
-combine several regexps like this to process a string part-by-part,
-doing different actions depending on which regexp matched. Each
-regexp tries to match where the previous one leaves off.
-
- $_ = <<'EOL';
- $url = URI::URL->new( "http://example.com/" ); die if $url eq "xXx";
- EOL
-
- LOOP: {
- print(" digits"), redo LOOP if /\G\d+\b[,.;]?\s*/gc;
- print(" lowercase"), redo LOOP if /\G\p{Ll}+\b[,.;]?\s*/gc;
- print(" UPPERCASE"), redo LOOP if /\G\p{Lu}+\b[,.;]?\s*/gc;
- print(" Capitalized"), redo LOOP if /\G\p{Lu}\p{Ll}+\b[,.;]?\s*/gc;
- print(" MiXeD"), redo LOOP if /\G\pL+\b[,.;]?\s*/gc;
- print(" alphanumeric"), redo LOOP if /\G[\p{Alpha}\pN]+\b[,.;]?\s*/gc;
- print(" line-noise"), redo LOOP if /\G\W+/gc;
- print ". That's all!\n";
- }
-
-Here is the output (split into several lines):
-
- line-noise lowercase line-noise UPPERCASE line-noise UPPERCASE
- line-noise lowercase line-noise lowercase line-noise lowercase
- lowercase line-noise lowercase lowercase line-noise lowercase
- lowercase line-noise MiXeD line-noise. That's all!
-
-=item m?PATTERN?msixpodualgc
-X<?> X<operator, match-once>
-
-=item ?PATTERN?msixpodualgc
-
-This is just like the C<m/PATTERN/> search, except that it matches
-only once between calls to the reset() operator. This is a useful
-optimization when you want to see only the first occurrence of
-something in each file of a set of files, for instance. Only C<m??>
-patterns local to the current package are reset.
-
- while (<>) {
- if (m?^$?) {
- # blank line between header and body
- }
- } continue {
- reset if eof; # clear m?? status for next file
- }
-
-Another example switched the first "latin1" encoding it finds
-to "utf8" in a pod file:
-
- s//utf8/ if m? ^ =encoding \h+ \K latin1 ?x;
-
-The match-once behavior is controlled by the match delimiter being
-C<?>; with any other delimiter this is the normal C<m//> operator.
-
-For historical reasons, the leading C<m> in C<m?PATTERN?> is optional,
-but the resulting C<?PATTERN?> syntax is deprecated, will warn on
-usage and might be removed from a future stable release of Perl (without
-further notice!).
-
-=item s/PATTERN/REPLACEMENT/msixpodualgcer
-X<substitute> X<substitution> X<replace> X<regexp, replace>
-X<regexp, substitute> X</m> X</s> X</i> X</x> X</p> X</o> X</g> X</c> X</e> X</r>
-
-Searches a string for a pattern, and if found, replaces that pattern
-with the replacement text and returns the number of substitutions
-made. Otherwise it returns false (specifically, the empty string).
-
-If the C</r> (non-destructive) option is used then it runs the
-substitution on a copy of the string and instead of returning the
-number of substitutions, it returns the copy whether or not a
-substitution occurred. The original string is never changed when
-C</r> is used. The copy will always be a plain string, even if the
-input is an object or a tied variable.
-
-If no string is specified via the C<=~> or C<!~> operator, the C<$_>
-variable is searched and modified. Unless the C</r> option is used,
-the string specified must be a scalar variable, an array element, a
-hash element, or an assignment to one of those; that is, some sort of
-scalar lvalue.
-
-If the delimiter chosen is a single quote, no interpolation is
-done on either the PATTERN or the REPLACEMENT. Otherwise, if the
-PATTERN contains a $ that looks like a variable rather than an
-end-of-string test, the variable will be interpolated into the pattern
-at run-time. If you want the pattern compiled only once the first time
-the variable is interpolated, use the C</o> option. If the pattern
-evaluates to the empty string, the last successfully executed regular
-expression is used instead. See L<perlre> for further explanation on these.
-
-Options are as with m// with the addition of the following replacement
-specific options:
-
- e Evaluate the right side as an expression.
- ee Evaluate the right side as a string then eval the result.
- r Return substitution and leave the original string untouched.
-
-Any non-whitespace delimiter may replace the slashes. Add space after
-the C<s> when using a character allowed in identifiers. If single quotes
-are used, no interpretation is done on the replacement string (the C</e>
-modifier overrides this, however). Unlike Perl 4, Perl 5 treats backticks
-as normal delimiters; the replacement text is not evaluated as a command.
-If the PATTERN is delimited by bracketing quotes, the REPLACEMENT has
-its own pair of quotes, which may or may not be bracketing quotes, for example,
-C<s(foo)(bar)> or C<< s<foo>/bar/ >>. A C</e> will cause the
-replacement portion to be treated as a full-fledged Perl expression
-and evaluated right then and there. It is, however, syntax checked at
-compile-time. A second C<e> modifier will cause the replacement portion
-to be C<eval>ed before being run as a Perl expression.
-
-Examples:
-
- s/\bgreen\b/mauve/g; # don't change wintergreen
-
- $path =~ s|/usr/bin|/usr/local/bin|;
-
- s/Login: $foo/Login: $bar/; # run-time pattern
-
- ($foo = $bar) =~ s/this/that/; # copy first, then change
- ($foo = "$bar") =~ s/this/that/; # convert to string, copy, then change
- $foo = $bar =~ s/this/that/r; # Same as above using /r
- $foo = $bar =~ s/this/that/r
- =~ s/that/the other/r; # Chained substitutes using /r
- @foo = map { s/this/that/r } @bar # /r is very useful in maps
-
- $count = ($paragraph =~ s/Mister\b/Mr./g); # get change-count
-
- $_ = 'abc123xyz';
- s/\d+/$&*2/e; # yields 'abc246xyz'
- s/\d+/sprintf("%5d",$&)/e; # yields 'abc 246xyz'
- s/\w/$& x 2/eg; # yields 'aabbcc 224466xxyyzz'
-
- s/%(.)/$percent{$1}/g; # change percent escapes; no /e
- s/%(.)/$percent{$1} || $&/ge; # expr now, so /e
- s/^=(\w+)/pod($1)/ge; # use function call
-
- $_ = 'abc123xyz';
- $a = s/abc/def/r; # $a is 'def123xyz' and
- # $_ remains 'abc123xyz'.
-
- # expand variables in $_, but dynamics only, using
- # symbolic dereferencing
- s/\$(\w+)/${$1}/g;
-
- # Add one to the value of any numbers in the string
- s/(\d+)/1 + $1/eg;
-
- # Titlecase words in the last 30 characters only
- substr($str, -30) =~ s/\b(\p{Alpha}+)\b/\u\L$1/g;
-
- # This will expand any embedded scalar variable
- # (including lexicals) in $_ : First $1 is interpolated
- # to the variable name, and then evaluated
- s/(\$\w+)/$1/eeg;
-
- # Delete (most) C comments.
- $program =~ s {
- /\* # Match the opening delimiter.
- .*? # Match a minimal number of characters.
- \*/ # Match the closing delimiter.
- } []gsx;
-
- s/^\s*(.*?)\s*$/$1/; # trim whitespace in $_, expensively
-
- for ($variable) { # trim whitespace in $variable, cheap
- s/^\s+//;
- s/\s+$//;
- }
-
- s/([^ ]*) *([^ ]*)/$2 $1/; # reverse 1st two fields
-
-Note the use of $ instead of \ in the last example. Unlike
-B<sed>, we use the \<I<digit>> form in only the left hand side.
-Anywhere else it's $<I<digit>>.
-
-Occasionally, you can't use just a C</g> to get all the changes
-to occur that you might want. Here are two common cases:
-
- # put commas in the right places in an integer
- 1 while s/(\d)(\d\d\d)(?!\d)/$1,$2/g;
-
- # expand tabs to 8-column spacing
- 1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e;
-
-C<s///le> is treated as a substitution followed by the C<le> operator, not
-the C</le> flags. This may change in a future version of Perl. It
-produces a warning if warnings are enabled. To disambiguate, use a space
-or change the order of the flags:
-
- s/foo/bar/ le 5; # "le" infix operator
- s/foo/bar/el; # "e" and "l" flags
-
-=back
-
-=head2 Quote-Like Operators
-X<operator, quote-like>
-
-=over 4
-
-=item q/STRING/
-X<q> X<quote, single> X<'> X<''>
-
-=item 'STRING'
-
-A single-quoted, literal string. A backslash represents a backslash
-unless followed by the delimiter or another backslash, in which case
-the delimiter or backslash is interpolated.
-
- $foo = q!I said, "You said, 'She said it.'"!;
- $bar = q('This is it.');
- $baz = '\n'; # a two-character string
-
-=item qq/STRING/
-X<qq> X<quote, double> X<"> X<"">
-
-=item "STRING"
-
-A double-quoted, interpolated string.
-
- $_ .= qq
- (*** The previous line contains the naughty word "$1".\n)
- if /\b(tcl|java|python)\b/i; # :-)
- $baz = "\n"; # a one-character string
-
-=item qx/STRING/
-X<qx> X<`> X<``> X<backtick>
-
-=item `STRING`
-
-A string which is (possibly) interpolated and then executed as a
-system command with C</bin/sh> or its equivalent. Shell wildcards,
-pipes, and redirections will be honored. The collected standard
-output of the command is returned; standard error is unaffected. In
-scalar context, it comes back as a single (potentially multi-line)
-string, or undef if the command failed. In list context, returns a
-list of lines (however you've defined lines with $/ or
-$INPUT_RECORD_SEPARATOR), or an empty list if the command failed.
-
-Because backticks do not affect standard error, use shell file descriptor
-syntax (assuming the shell supports this) if you care to address this.
-To capture a command's STDERR and STDOUT together:
-
- $output = `cmd 2>&1`;
-
-To capture a command's STDOUT but discard its STDERR:
-
- $output = `cmd 2>/dev/null`;
-
-To capture a command's STDERR but discard its STDOUT (ordering is
-important here):
-
- $output = `cmd 2>&1 1>/dev/null`;
-
-To exchange a command's STDOUT and STDERR in order to capture the STDERR
-but leave its STDOUT to come out the old STDERR:
-
- $output = `cmd 3>&1 1>&2 2>&3 3>&-`;
-
-To read both a command's STDOUT and its STDERR separately, it's easiest
-to redirect them separately to files, and then read from those files
-when the program is done:
-
- system("program args 1>program.stdout 2>program.stderr");
-
-The STDIN filehandle used by the command is inherited from Perl's STDIN.
-For example:
-
- open(SPLAT, "stuff") || die "can't open stuff: $!";
- open(STDIN, "<&SPLAT") || die "can't dupe SPLAT: $!";
- print STDOUT `sort`;
-
-will print the sorted contents of the file named F<"stuff">.
-
-Using single-quote as a delimiter protects the command from Perl's
-double-quote interpolation, passing it on to the shell instead:
-
- $perl_info = qx(ps $$); # that's Perl's $$
- $shell_info = qx'ps $$'; # that's the new shell's $$
-
-How that string gets evaluated is entirely subject to the command
-interpreter on your system. On most platforms, you will have to protect
-shell metacharacters if you want them treated literally. This is in
-practice difficult to do, as it's unclear how to escape which characters.
-See L<perlsec> for a clean and safe example of a manual fork() and exec()
-to emulate backticks safely.
-
-On some platforms (notably DOS-like ones), the shell may not be
-capable of dealing with multiline commands, so putting newlines in
-the string may not get you what you want. You may be able to evaluate
-multiple commands in a single line by separating them with the command
-separator character, if your shell supports that (for example, C<;> on
-many Unix shells and C<&> on the Windows NT C<cmd> shell).
-
-Beginning with v5.6.0, Perl will attempt to flush all files opened for
-output before starting the child process, but this may not be supported
-on some platforms (see L<perlport>). To be safe, you may need to set
-C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of
-C<IO::Handle> on any open handles.
-
-Beware that some command shells may place restrictions on the length
-of the command line. You must ensure your strings don't exceed this
-limit after any necessary interpolations. See the platform-specific
-release notes for more details about your particular environment.
-
-Using this operator can lead to programs that are difficult to port,
-because the shell commands called vary between systems, and may in
-fact not be present at all. As one example, the C<type> command under
-the POSIX shell is very different from the C<type> command under DOS.
-That doesn't mean you should go out of your way to avoid backticks
-when they're the right way to get something done. Perl was made to be
-a glue language, and one of the things it glues together is commands.
-Just understand what you're getting yourself into.
-
-See L</"I/O Operators"> for more discussion.
-
-=item qw/STRING/
-X<qw> X<quote, list> X<quote, words>
-
-Evaluates to a list of the words extracted out of STRING, using embedded
-whitespace as the word delimiters. It can be understood as being roughly
-equivalent to:
-
- split(" ", q/STRING/);
-
-the differences being that it generates a real list at compile time, and
-in scalar context it returns the last element in the list. So
-this expression:
-
- qw(foo bar baz)
-
-is semantically equivalent to the list:
-
- "foo", "bar", "baz"
-
-Some frequently seen examples:
-
- use POSIX qw( setlocale localeconv )
- @EXPORT = qw( foo bar baz );
-
-A common mistake is to try to separate the words with comma or to
-put comments into a multi-line C<qw>-string. For this reason, the
-C<use warnings> pragma and the B<-w> switch (that is, the C<$^W> variable)
-produces warnings if the STRING contains the "," or the "#" character.
-
-=item tr/SEARCHLIST/REPLACEMENTLIST/cdsr
-X<tr> X<y> X<transliterate> X</c> X</d> X</s>
-
-=item y/SEARCHLIST/REPLACEMENTLIST/cdsr
-
-Transliterates all occurrences of the characters found in the search list
-with the corresponding character in the replacement list. It returns
-the number of characters replaced or deleted. If no string is
-specified via the C<=~> or C<!~> operator, the $_ string is transliterated.
-
-If the C</r> (non-destructive) option is present, a new copy of the string
-is made and its characters transliterated, and this copy is returned no
-matter whether it was modified or not: the original string is always
-left unchanged. The new copy is always a plain string, even if the input
-string is an object or a tied variable.
-
-Unless the C</r> option is used, the string specified with C<=~> must be a
-scalar variable, an array element, a hash element, or an assignment to one
-of those; in other words, an lvalue.
-
-A character range may be specified with a hyphen, so C<tr/A-J/0-9/>
-does the same replacement as C<tr/ACEGIBDFHJ/0246813579/>.
-For B<sed> devotees, C<y> is provided as a synonym for C<tr>. If the
-SEARCHLIST is delimited by bracketing quotes, the REPLACEMENTLIST has
-its own pair of quotes, which may or may not be bracketing quotes;
-for example, C<tr[aeiouy][yuoiea]> or C<tr(+\-*/)/ABCD/>.
-
-Note that C<tr> does B<not> do regular expression character classes such as
-C<\d> or C<\pL>. The C<tr> operator is not equivalent to the tr(1)
-utility. If you want to map strings between lower/upper cases, see
-L<perlfunc/lc> and L<perlfunc/uc>, and in general consider using the C<s>
-operator if you need regular expressions. The C<\U>, C<\u>, C<\L>, and
-C<\l> string-interpolation escapes on the right side of a substitution
-operator will perform correct case-mappings, but C<tr[a-z][A-Z]> will not
-(except sometimes on legacy 7-bit data).
-
-Note also that the whole range idea is rather unportable between
-character sets--and even within character sets they may cause results
-you probably didn't expect. A sound principle is to use only ranges
-that begin from and end at either alphabets of equal case (a-e, A-E),
-or digits (0-4). Anything else is unsafe. If in doubt, spell out the
-character sets in full.
-
-Options:
-
- c Complement the SEARCHLIST.
- d Delete found but unreplaced characters.
- s Squash duplicate replaced characters.
- r Return the modified string and leave the original string
- untouched.
-
-If the C</c> modifier is specified, the SEARCHLIST character set
-is complemented. If the C</d> modifier is specified, any characters
-specified by SEARCHLIST not found in REPLACEMENTLIST are deleted.
-(Note that this is slightly more flexible than the behavior of some
-B<tr> programs, which delete anything they find in the SEARCHLIST,
-period.) If the C</s> modifier is specified, sequences of characters
-that were transliterated to the same character are squashed down
-to a single instance of the character.
-
-If the C</d> modifier is used, the REPLACEMENTLIST is always interpreted
-exactly as specified. Otherwise, if the REPLACEMENTLIST is shorter
-than the SEARCHLIST, the final character is replicated till it is long
-enough. If the REPLACEMENTLIST is empty, the SEARCHLIST is replicated.
-This latter is useful for counting characters in a class or for
-squashing character sequences in a class.
-
-Examples:
-
- $ARGV[1] =~ tr/A-Z/a-z/; # canonicalize to lower case ASCII
-
- $cnt = tr/*/*/; # count the stars in $_
-
- $cnt = $sky =~ tr/*/*/; # count the stars in $sky
-
- $cnt = tr/0-9//; # count the digits in $_
-
- tr/a-zA-Z//s; # bookkeeper -> bokeper
-
- ($HOST = $host) =~ tr/a-z/A-Z/;
- $HOST = $host =~ tr/a-z/A-Z/r; # same thing
-
- $HOST = $host =~ tr/a-z/A-Z/r # chained with s///r
- =~ s/:/ -p/r;
-
- tr/a-zA-Z/ /cs; # change non-alphas to single space
-
- @stripped = map tr/a-zA-Z/ /csr, @original;
- # /r with map
-
- tr [\200-\377]
- [\000-\177]; # wickedly delete 8th bit
-
-If multiple transliterations are given for a character, only the
-first one is used:
-
- tr/AAA/XYZ/
-
-will transliterate any A to X.
-
-Because the transliteration table is built at compile time, neither
-the SEARCHLIST nor the REPLACEMENTLIST are subjected to double quote
-interpolation. That means that if you want to use variables, you
-must use an eval():
-
- eval "tr/$oldlist/$newlist/";
- die $@ if $@;
-
- eval "tr/$oldlist/$newlist/, 1" or die $@;
-
-=item <<EOF
-X<here-doc> X<heredoc> X<here-document> X<<< << >>>
-
-A line-oriented form of quoting is based on the shell "here-document"
-syntax. Following a C<< << >> you specify a string to terminate
-the quoted material, and all lines following the current line down to
-the terminating string are the value of the item.
-
-The terminating string may be either an identifier (a word), or some
-quoted text. An unquoted identifier works like double quotes.
-There may not be a space between the C<< << >> and the identifier,
-unless the identifier is explicitly quoted. (If you put a space it
-will be treated as a null identifier, which is valid, and matches the
-first empty line.) The terminating string must appear by itself
-(unquoted and with no surrounding whitespace) on the terminating line.
-
-If the terminating string is quoted, the type of quotes used determine
-the treatment of the text.
-
-=over 4
-
-=item Double Quotes
-
-Double quotes indicate that the text will be interpolated using exactly
-the same rules as normal double quoted strings.
-
- print <<EOF;
- The price is $Price.
- EOF
-
- print << "EOF"; # same as above
- The price is $Price.
- EOF
-
-
-=item Single Quotes
-
-Single quotes indicate the text is to be treated literally with no
-interpolation of its content. This is similar to single quoted
-strings except that backslashes have no special meaning, with C<\\>
-being treated as two backslashes and not one as they would in every
-other quoting construct.
-
-Just as in the shell, a backslashed bareword following the C<<< << >>>
-means the same thing as a single-quoted string does:
-
- $cost = <<'VISTA'; # hasta la ...
- That'll be $10 please, ma'am.
- VISTA
-
- $cost = <<\VISTA; # Same thing!
- That'll be $10 please, ma'am.
- VISTA
-
-This is the only form of quoting in perl where there is no need
-to worry about escaping content, something that code generators
-can and do make good use of.
-
-=item Backticks
-
-The content of the here doc is treated just as it would be if the
-string were embedded in backticks. Thus the content is interpolated
-as though it were double quoted and then executed via the shell, with
-the results of the execution returned.
-
- print << `EOC`; # execute command and get results
- echo hi there
- EOC
-
-=back
-
-It is possible to stack multiple here-docs in a row:
-
- print <<"foo", <<"bar"; # you can stack them
- I said foo.
- foo
- I said bar.
- bar
-
- myfunc(<< "THIS", 23, <<'THAT');
- Here's a line
- or two.
- THIS
- and here's another.
- THAT
-
-Just don't forget that you have to put a semicolon on the end
-to finish the statement, as Perl doesn't know you're not going to
-try to do this:
-
- print <<ABC
- 179231
- ABC
- + 20;
-
-If you want to remove the line terminator from your here-docs,
-use C<chomp()>.
-
- chomp($string = <<'END');
- This is a string.
- END
-
-If you want your here-docs to be indented with the rest of the code,
-you'll need to remove leading whitespace from each line manually:
-
- ($quote = <<'FINIS') =~ s/^\s+//gm;
- The Road goes ever on and on,
- down from the door where it began.
- FINIS
-
-If you use a here-doc within a delimited construct, such as in C<s///eg>,
-the quoted material must come on the lines following the final delimiter.
-So instead of
-
- s/this/<<E . 'that'
- the other
- E
- . 'more '/eg;
-
-you have to write
-
- s/this/<<E . 'that'
- . 'more '/eg;
- the other
- E
-
-If the terminating identifier is on the last line of the program, you
-must be sure there is a newline after it; otherwise, Perl will give the
-warning B<Can't find string terminator "END" anywhere before EOF...>.
-
-Additionally, quoting rules for the end-of-string identifier are
-unrelated to Perl's quoting rules. C<q()>, C<qq()>, and the like are not
-supported in place of C<''> and C<"">, and the only interpolation is for
-backslashing the quoting character:
-
- print << "abc\"def";
- testing...
- abc"def
-
-Finally, quoted strings cannot span multiple lines. The general rule is
-that the identifier must be a string literal. Stick with that, and you
-should be safe.
-
-=back
-
-=head2 Gory details of parsing quoted constructs
-X<quote, gory details>
-
-When presented with something that might have several different
-interpretations, Perl uses the B<DWIM> (that's "Do What I Mean")
-principle to pick the most probable interpretation. This strategy
-is so successful that Perl programmers often do not suspect the
-ambivalence of what they write. But from time to time, Perl's
-notions differ substantially from what the author honestly meant.
-
-This section hopes to clarify how Perl handles quoted constructs.
-Although the most common reason to learn this is to unravel labyrinthine
-regular expressions, because the initial steps of parsing are the
-same for all quoting operators, they are all discussed together.
-
-The most important Perl parsing rule is the first one discussed
-below: when processing a quoted construct, Perl first finds the end
-of that construct, then interprets its contents. If you understand
-this rule, you may skip the rest of this section on the first
-reading. The other rules are likely to contradict the user's
-expectations much less frequently than this first one.
-
-Some passes discussed below are performed concurrently, but because
-their results are the same, we consider them individually. For different
-quoting constructs, Perl performs different numbers of passes, from
-one to four, but these passes are always performed in the same order.
-
-=over 4
-
-=item Finding the end
-
-The first pass is finding the end of the quoted construct, where
-the information about the delimiters is used in parsing.
-During this search, text between the starting and ending delimiters
-is copied to a safe location. The text copied gets delimiter-independent.
-
-If the construct is a here-doc, the ending delimiter is a line
-that has a terminating string as the content. Therefore C<<<EOF> is
-terminated by C<EOF> immediately followed by C<"\n"> and starting
-from the first column of the terminating line.
-When searching for the terminating line of a here-doc, nothing
-is skipped. In other words, lines after the here-doc syntax
-are compared with the terminating string line by line.
-
-For the constructs except here-docs, single characters are used as starting
-and ending delimiters. If the starting delimiter is an opening punctuation
-(that is C<(>, C<[>, C<{>, or C<< < >>), the ending delimiter is the
-corresponding closing punctuation (that is C<)>, C<]>, C<}>, or C<< > >>).
-If the starting delimiter is an unpaired character like C</> or a closing
-punctuation, the ending delimiter is same as the starting delimiter.
-Therefore a C</> terminates a C<qq//> construct, while a C<]> terminates
-C<qq[]> and C<qq]]> constructs.
-
-When searching for single-character delimiters, escaped delimiters
-and C<\\> are skipped. For example, while searching for terminating C</>,
-combinations of C<\\> and C<\/> are skipped. If the delimiters are
-bracketing, nested pairs are also skipped. For example, while searching
-for closing C<]> paired with the opening C<[>, combinations of C<\\>, C<\]>,
-and C<\[> are all skipped, and nested C<[> and C<]> are skipped as well.
-However, when backslashes are used as the delimiters (like C<qq\\> and
-C<tr\\\>), nothing is skipped.
-During the search for the end, backslashes that escape delimiters or
-backslashes are removed (exactly speaking, they are not copied to the
-safe location).
-
-For constructs with three-part delimiters (C<s///>, C<y///>, and
-C<tr///>), the search is repeated once more.
-If the first delimiter is not an opening punctuation, three delimiters must
-be same such as C<s!!!> and C<tr)))>, in which case the second delimiter
-terminates the left part and starts the right part at once.
-If the left part is delimited by bracketing punctuation (that is C<()>,
-C<[]>, C<{}>, or C<< <> >>), the right part needs another pair of
-delimiters such as C<s(){}> and C<tr[]//>. In these cases, whitespace
-and comments are allowed between both parts, though the comment must follow
-at least one whitespace character; otherwise a character expected as the
-start of the comment may be regarded as the starting delimiter of the right part.
-
-During this search no attention is paid to the semantics of the construct.
-Thus:
-
- "$hash{"$foo/$bar"}"
-
-or:
-
- m/
- bar # NOT a comment, this slash / terminated m//!
- /x
-
-do not form legal quoted expressions. The quoted part ends on the
-first C<"> and C</>, and the rest happens to be a syntax error.
-Because the slash that terminated C<m//> was followed by a C<SPACE>,
-the example above is not C<m//x>, but rather C<m//> with no C</x>
-modifier. So the embedded C<#> is interpreted as a literal C<#>.
-
-Also no attention is paid to C<\c\> (multichar control char syntax) during
-this search. Thus the second C<\> in C<qq/\c\/> is interpreted as a part
-of C<\/>, and the following C</> is not recognized as a delimiter.
-Instead, use C<\034> or C<\x1c> at the end of quoted constructs.
-
-=item Interpolation
-X<interpolation>
-
-The next step is interpolation in the text obtained, which is now
-delimiter-independent. There are multiple cases.
-
-=over 4
-
-=item C<<<'EOF'>
-
-No interpolation is performed.
-Note that the combination C<\\> is left intact, since escaped delimiters
-are not available for here-docs.
-
-=item C<m''>, the pattern of C<s'''>
-
-No interpolation is performed at this stage.
-Any backslashed sequences including C<\\> are treated at the stage
-to L</"parsing regular expressions">.
-
-=item C<''>, C<q//>, C<tr'''>, C<y'''>, the replacement of C<s'''>
-
-The only interpolation is removal of C<\> from pairs of C<\\>.
-Therefore C<-> in C<tr'''> and C<y'''> is treated literally
-as a hyphen and no character range is available.
-C<\1> in the replacement of C<s'''> does not work as C<$1>.
-
-=item C<tr///>, C<y///>
-
-No variable interpolation occurs. String modifying combinations for
-case and quoting such as C<\Q>, C<\U>, and C<\E> are not recognized.
-The other escape sequences such as C<\200> and C<\t> and backslashed
-characters such as C<\\> and C<\-> are converted to appropriate literals.
-The character C<-> is treated specially and therefore C<\-> is treated
-as a literal C<->.
-
-=item C<"">, C<``>, C<qq//>, C<qx//>, C<< <file*glob> >>, C<<<"EOF">
-
-C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, C<\F> (possibly paired with C<\E>) are
-converted to corresponding Perl constructs. Thus, C<"$foo\Qbaz$bar">
-is converted to C<$foo . (quotemeta("baz" . $bar))> internally.
-The other escape sequences such as C<\200> and C<\t> and backslashed
-characters such as C<\\> and C<\-> are replaced with appropriate
-expansions.
-
-Let it be stressed that I<whatever falls between C<\Q> and C<\E>>
-is interpolated in the usual way. Something like C<"\Q\\E"> has
-no C<\E> inside. instead, it has C<\Q>, C<\\>, and C<E>, so the
-result is the same as for C<"\\\\E">. As a general rule, backslashes
-between C<\Q> and C<\E> may lead to counterintuitive results. So,
-C<"\Q\t\E"> is converted to C<quotemeta("\t")>, which is the same
-as C<"\\\t"> (since TAB is not alphanumeric). Note also that:
-
- $str = '\t';
- return "\Q$str";
-
-may be closer to the conjectural I<intention> of the writer of C<"\Q\t\E">.
-
-Interpolated scalars and arrays are converted internally to the C<join> and
-C<.> catenation operations. Thus, C<"$foo XXX '@arr'"> becomes:
-
- $foo . " XXX '" . (join $", @arr) . "'";
-
-All operations above are performed simultaneously, left to right.
-
-Because the result of C<"\Q STRING \E"> has all metacharacters
-quoted, there is no way to insert a literal C<$> or C<@> inside a
-C<\Q\E> pair. If protected by C<\>, C<$> will be quoted to became
-C<"\\\$">; if not, it is interpreted as the start of an interpolated
-scalar.
-
-Note also that the interpolation code needs to make a decision on
-where the interpolated scalar ends. For instance, whether
-C<< "a $b -> {c}" >> really means:
-
- "a " . $b . " -> {c}";
-
-or:
-
- "a " . $b -> {c};
-
-Most of the time, the longest possible text that does not include
-spaces between components and which contains matching braces or
-brackets. because the outcome may be determined by voting based
-on heuristic estimators, the result is not strictly predictable.
-Fortunately, it's usually correct for ambiguous cases.
-
-=item the replacement of C<s///>
-
-Processing of C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, C<\F> and interpolation
-happens as with C<qq//> constructs.
-
-It is at this step that C<\1> is begrudgingly converted to C<$1> in
-the replacement text of C<s///>, in order to correct the incorrigible
-I<sed> hackers who haven't picked up the saner idiom yet. A warning
-is emitted if the C<use warnings> pragma or the B<-w> command-line flag
-(that is, the C<$^W> variable) was set.
-
-=item C<RE> in C<?RE?>, C</RE/>, C<m/RE/>, C<s/RE/foo/>,
-
-Processing of C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, C<\F>, C<\E>,
-and interpolation happens (almost) as with C<qq//> constructs.
-
-Processing of C<\N{...}> is also done here, and compiled into an intermediate
-form for the regex compiler. (This is because, as mentioned below, the regex
-compilation may be done at execution time, and C<\N{...}> is a compile-time
-construct.)
-
-However any other combinations of C<\> followed by a character
-are not substituted but only skipped, in order to parse them
-as regular expressions at the following step.
-As C<\c> is skipped at this step, C<@> of C<\c@> in RE is possibly
-treated as an array symbol (for example C<@foo>),
-even though the same text in C<qq//> gives interpolation of C<\c@>.
-
-Moreover, inside C<(?{BLOCK})>, C<(?# comment )>, and
-a C<#>-comment in a C<//x>-regular expression, no processing is
-performed whatsoever. This is the first step at which the presence
-of the C<//x> modifier is relevant.
-
-Interpolation in patterns has several quirks: C<$|>, C<$(>, C<$)>, C<@+>
-and C<@-> are not interpolated, and constructs C<$var[SOMETHING]> are
-voted (by several different estimators) to be either an array element
-or C<$var> followed by an RE alternative. This is where the notation
-C<${arr[$bar]}> comes handy: C</${arr[0-9]}/> is interpreted as
-array element C<-9>, not as a regular expression from the variable
-C<$arr> followed by a digit, which would be the interpretation of
-C</$arr[0-9]/>. Since voting among different estimators may occur,
-the result is not predictable.
-
-The lack of processing of C<\\> creates specific restrictions on
-the post-processed text. If the delimiter is C</>, one cannot get
-the combination C<\/> into the result of this step. C</> will
-finish the regular expression, C<\/> will be stripped to C</> on
-the previous step, and C<\\/> will be left as is. Because C</> is
-equivalent to C<\/> inside a regular expression, this does not
-matter unless the delimiter happens to be character special to the
-RE engine, such as in C<s*foo*bar*>, C<m[foo]>, or C<?foo?>; or an
-alphanumeric char, as in:
-
- m m ^ a \s* b mmx;
-
-In the RE above, which is intentionally obfuscated for illustration, the
-delimiter is C<m>, the modifier is C<mx>, and after delimiter-removal the
-RE is the same as for C<m/ ^ a \s* b /mx>. There's more than one
-reason you're encouraged to restrict your delimiters to non-alphanumeric,
-non-whitespace choices.
-
-=back
-
-This step is the last one for all constructs except regular expressions,
-which are processed further.
-
-=item parsing regular expressions
-X<regexp, parse>
-
-Previous steps were performed during the compilation of Perl code,
-but this one happens at run time, although it may be optimized to
-be calculated at compile time if appropriate. After preprocessing
-described above, and possibly after evaluation if concatenation,
-joining, casing translation, or metaquoting are involved, the
-resulting I<string> is passed to the RE engine for compilation.
-
-Whatever happens in the RE engine might be better discussed in L<perlre>,
-but for the sake of continuity, we shall do so here.
-
-This is another step where the presence of the C<//x> modifier is
-relevant. The RE engine scans the string from left to right and
-converts it to a finite automaton.
-
-Backslashed characters are either replaced with corresponding
-literal strings (as with C<\{>), or else they generate special nodes
-in the finite automaton (as with C<\b>). Characters special to the
-RE engine (such as C<|>) generate corresponding nodes or groups of
-nodes. C<(?#...)> comments are ignored. All the rest is either
-converted to literal strings to match, or else is ignored (as is
-whitespace and C<#>-style comments if C<//x> is present).
-
-Parsing of the bracketed character class construct, C<[...]>, is
-rather different than the rule used for the rest of the pattern.
-The terminator of this construct is found using the same rules as
-for finding the terminator of a C<{}>-delimited construct, the only
-exception being that C<]> immediately following C<[> is treated as
-though preceded by a backslash. Similarly, the terminator of
-C<(?{...})> is found using the same rules as for finding the
-terminator of a C<{}>-delimited construct.
-
-It is possible to inspect both the string given to RE engine and the
-resulting finite automaton. See the arguments C<debug>/C<debugcolor>
-in the C<use L<re>> pragma, as well as Perl's B<-Dr> command-line
-switch documented in L<perlrun/"Command Switches">.
-
-=item Optimization of regular expressions
-X<regexp, optimization>
-
-This step is listed for completeness only. Since it does not change
-semantics, details of this step are not documented and are subject
-to change without notice. This step is performed over the finite
-automaton that was generated during the previous pass.
-
-It is at this stage that C<split()> silently optimizes C</^/> to
-mean C</^/m>.
-
-=back
-
-=head2 I/O Operators
-X<operator, i/o> X<operator, io> X<io> X<while> X<filehandle>
-X<< <> >> X<@ARGV>
-
-There are several I/O operators you should know about.
-
-A string enclosed by backticks (grave accents) first undergoes
-double-quote interpolation. It is then interpreted as an external
-command, and the output of that command is the value of the
-backtick string, like in a shell. In scalar context, a single string
-consisting of all output is returned. In list context, a list of
-values is returned, one per line of output. (You can set C<$/> to use
-a different line terminator.) The command is executed each time the
-pseudo-literal is evaluated. The status value of the command is
-returned in C<$?> (see L<perlvar> for the interpretation of C<$?>).
-Unlike in B<csh>, no translation is done on the return data--newlines
-remain newlines. Unlike in any of the shells, single quotes do not
-hide variable names in the command from interpretation. To pass a
-literal dollar-sign through to the shell you need to hide it with a
-backslash. The generalized form of backticks is C<qx//>. (Because
-backticks always undergo shell expansion as well, see L<perlsec> for
-security concerns.)
-X<qx> X<`> X<``> X<backtick> X<glob>
-
-In scalar context, evaluating a filehandle in angle brackets yields
-the next line from that file (the newline, if any, included), or
-C<undef> at end-of-file or on error. When C<$/> is set to C<undef>
-(sometimes known as file-slurp mode) and the file is empty, it
-returns C<''> the first time, followed by C<undef> subsequently.
-
-Ordinarily you must assign the returned value to a variable, but
-there is one situation where an automatic assignment happens. If
-and only if the input symbol is the only thing inside the conditional
-of a C<while> statement (even if disguised as a C<for(;;)> loop),
-the value is automatically assigned to the global variable $_,
-destroying whatever was there previously. (This may seem like an
-odd thing to you, but you'll use the construct in almost every Perl
-script you write.) The $_ variable is not implicitly localized.
-You'll have to put a C<local $_;> before the loop if you want that
-to happen.
-
-The following lines are equivalent:
-
- while (defined($_ = <STDIN>)) { print; }
- while ($_ = <STDIN>) { print; }
- while (<STDIN>) { print; }
- for (;<STDIN>;) { print; }
- print while defined($_ = <STDIN>);
- print while ($_ = <STDIN>);
- print while <STDIN>;
-
-This also behaves similarly, but assigns to a lexical variable
-instead of to C<$_>:
-
- while (my $line = <STDIN>) { print $line }
-
-In these loop constructs, the assigned value (whether assignment
-is automatic or explicit) is then tested to see whether it is
-defined. The defined test avoids problems where the line has a string
-value that would be treated as false by Perl; for example a "" or
-a "0" with no trailing newline. If you really mean for such values
-to terminate the loop, they should be tested for explicitly:
-
- while (($_ = <STDIN>) ne '0') { ... }
- while (<STDIN>) { last unless $_; ... }
-
-In other boolean contexts, C<< <FILEHANDLE> >> without an
-explicit C<defined> test or comparison elicits a warning if the
-C<use warnings> pragma or the B<-w>
-command-line switch (the C<$^W> variable) is in effect.
-
-The filehandles STDIN, STDOUT, and STDERR are predefined. (The
-filehandles C<stdin>, C<stdout>, and C<stderr> will also work except
-in packages, where they would be interpreted as local identifiers
-rather than global.) Additional filehandles may be created with
-the open() function, amongst others. See L<perlopentut> and
-L<perlfunc/open> for details on this.
-X<stdin> X<stdout> X<sterr>
-
-If a <FILEHANDLE> is used in a context that is looking for
-a list, a list comprising all input lines is returned, one line per
-list element. It's easy to grow to a rather large data space this
-way, so use with care.
-
-<FILEHANDLE> may also be spelled C<readline(*FILEHANDLE)>.
-See L<perlfunc/readline>.
-
-The null filehandle <> is special: it can be used to emulate the
-behavior of B<sed> and B<awk>, and any other Unix filter program
-that takes a list of filenames, doing the same to each line
-of input from all of them. Input from <> comes either from
-standard input, or from each file listed on the command line. Here's
-how it works: the first time <> is evaluated, the @ARGV array is
-checked, and if it is empty, C<$ARGV[0]> is set to "-", which when opened
-gives you standard input. The @ARGV array is then processed as a list
-of filenames. The loop
-
- while (<>) {
- ... # code for each line
- }
-
-is equivalent to the following Perl-like pseudo code:
-
- unshift(@ARGV, '-') unless @ARGV;
- while ($ARGV = shift) {
- open(ARGV, $ARGV);
- while (<ARGV>) {
- ... # code for each line
- }
- }
-
-except that it isn't so cumbersome to say, and will actually work.
-It really does shift the @ARGV array and put the current filename
-into the $ARGV variable. It also uses filehandle I<ARGV>
-internally. <> is just a synonym for <ARGV>, which
-is magical. (The pseudo code above doesn't work because it treats
-<ARGV> as non-magical.)
-
-Since the null filehandle uses the two argument form of L<perlfunc/open>
-it interprets special characters, so if you have a script like this:
-
- while (<>) {
- print;
- }
-
-and call it with C<perl dangerous.pl 'rm -rfv *|'>, it actually opens a
-pipe, executes the C<rm> command and reads C<rm>'s output from that pipe.
-If you want all items in C<@ARGV> to be interpreted as file names, you
-can use the module C<ARGV::readonly> from CPAN.
-
-You can modify @ARGV before the first <> as long as the array ends up
-containing the list of filenames you really want. Line numbers (C<$.>)
-continue as though the input were one big happy file. See the example
-in L<perlfunc/eof> for how to reset line numbers on each file.
-
-If you want to set @ARGV to your own list of files, go right ahead.
-This sets @ARGV to all plain text files if no @ARGV was given:
-
- @ARGV = grep { -f && -T } glob('*') unless @ARGV;
-
-You can even set them to pipe commands. For example, this automatically
-filters compressed arguments through B<gzip>:
-
- @ARGV = map { /\.(gz|Z)$/ ? "gzip -dc < $_ |" : $_ } @ARGV;
-
-If you want to pass switches into your script, you can use one of the
-Getopts modules or put a loop on the front like this:
-
- while ($_ = $ARGV[0], /^-/) {
- shift;
- last if /^--$/;
- if (/^-D(.*)/) { $debug = $1 }
- if (/^-v/) { $verbose++ }
- # ... # other switches
- }
-
- while (<>) {
- # ... # code for each line
- }
-
-The <> symbol will return C<undef> for end-of-file only once.
-If you call it again after this, it will assume you are processing another
-@ARGV list, and if you haven't set @ARGV, will read input from STDIN.
-
-If what the angle brackets contain is a simple scalar variable (for example,
-<$foo>), then that variable contains the name of the
-filehandle to input from, or its typeglob, or a reference to the
-same. For example:
-
- $fh = \*STDIN;
- $line = <$fh>;
-
-If what's within the angle brackets is neither a filehandle nor a simple
-scalar variable containing a filehandle name, typeglob, or typeglob
-reference, it is interpreted as a filename pattern to be globbed, and
-either a list of filenames or the next filename in the list is returned,
-depending on context. This distinction is determined on syntactic
-grounds alone. That means C<< <$x> >> is always a readline() from
-an indirect handle, but C<< <$hash{key}> >> is always a glob().
-That's because $x is a simple scalar variable, but C<$hash{key}> is
-not--it's a hash element. Even C<< <$x > >> (note the extra space)
-is treated as C<glob("$x ")>, not C<readline($x)>.
-
-One level of double-quote interpretation is done first, but you can't
-say C<< <$foo> >> because that's an indirect filehandle as explained
-in the previous paragraph. (In older versions of Perl, programmers
-would insert curly brackets to force interpretation as a filename glob:
-C<< <${foo}> >>. These days, it's considered cleaner to call the
-internal function directly as C<glob($foo)>, which is probably the right
-way to have done it in the first place.) For example:
-
- while (<*.c>) {
- chmod 0644, $_;
- }
-
-is roughly equivalent to:
-
- open(FOO, "echo *.c | tr -s ' \t\r\f' '\\012\\012\\012\\012'|");
- while (<FOO>) {
- chomp;
- chmod 0644, $_;
- }
-
-except that the globbing is actually done internally using the standard
-C<File::Glob> extension. Of course, the shortest way to do the above is:
-
- chmod 0644, <*.c>;
-
-A (file)glob evaluates its (embedded) argument only when it is
-starting a new list. All values must be read before it will start
-over. In list context, this isn't important because you automatically
-get them all anyway. However, in scalar context the operator returns
-the next value each time it's called, or C<undef> when the list has
-run out. As with filehandle reads, an automatic C<defined> is
-generated when the glob occurs in the test part of a C<while>,
-because legal glob returns (for example,
-a file called F<0>) would otherwise
-terminate the loop. Again, C<undef> is returned only once. So if
-you're expecting a single value from a glob, it is much better to
-say
-
- ($file) = <blurch*>;
-
-than
-
- $file = <blurch*>;
-
-because the latter will alternate between returning a filename and
-returning false.
-
-If you're trying to do variable interpolation, it's definitely better
-to use the glob() function, because the older notation can cause people
-to become confused with the indirect filehandle notation.
-
- @files = glob("$dir/*.[ch]");
- @files = glob($files[$i]);
-
-=head2 Constant Folding
-X<constant folding> X<folding>
-
-Like C, Perl does a certain amount of expression evaluation at
-compile time whenever it determines that all arguments to an
-operator are static and have no side effects. In particular, string
-concatenation happens at compile time between literals that don't do
-variable substitution. Backslash interpolation also happens at
-compile time. You can say
-
- 'Now is the time for all'
- . "\n"
- . 'good men to come to.'
-
-and this all reduces to one string internally. Likewise, if
-you say
-
- foreach $file (@filenames) {
- if (-s $file > 5 + 100 * 2**16) { }
- }
-
-the compiler precomputes the number which that expression
-represents so that the interpreter won't have to.
-
-=head2 No-ops
-X<no-op> X<nop>
-
-Perl doesn't officially have a no-op operator, but the bare constants
-C<0> and C<1> are special-cased not to produce a warning in void
-context, so you can for example safely do
-
- 1 while foo();
-
-=head2 Bitwise String Operators
-X<operator, bitwise, string>
-
-Bitstrings of any size may be manipulated by the bitwise operators
-(C<~ | & ^>).
-
-If the operands to a binary bitwise op are strings of different
-sizes, B<|> and B<^> ops act as though the shorter operand had
-additional zero bits on the right, while the B<&> op acts as though
-the longer operand were truncated to the length of the shorter.
-The granularity for such extension or truncation is one or more
-bytes.
-
- # ASCII-based examples
- print "j p \n" ^ " a h"; # prints "JAPH\n"
- print "JA" | " ph\n"; # prints "japh\n"
- print "japh\nJunk" & '_____'; # prints "JAPH\n";
- print 'p N$' ^ " E<H\n"; # prints "Perl\n";
-
-If you are intending to manipulate bitstrings, be certain that
-you're supplying bitstrings: If an operand is a number, that will imply
-a B<numeric> bitwise operation. You may explicitly show which type of
-operation you intend by using C<""> or C<0+>, as in the examples below.
-
- $foo = 150 | 105; # yields 255 (0x96 | 0x69 is 0xFF)
- $foo = '150' | 105; # yields 255
- $foo = 150 | '105'; # yields 255
- $foo = '150' | '105'; # yields string '155' (under ASCII)
-
- $baz = 0+$foo & 0+$bar; # both ops explicitly numeric
- $biz = "$foo" ^ "$bar"; # both ops explicitly stringy
-
-See L<perlfunc/vec> for information on how to manipulate individual bits
-in a bit vector.
-
-=head2 Integer Arithmetic
-X<integer>
-
-By default, Perl assumes that it must do most of its arithmetic in
-floating point. But by saying
-
- use integer;
-
-you may tell the compiler to use integer operations
-(see L<integer> for a detailed explanation) from here to the end of
-the enclosing BLOCK. An inner BLOCK may countermand this by saying
-
- no integer;
-
-which lasts until the end of that BLOCK. Note that this doesn't
-mean everything is an integer, merely that Perl will use integer
-operations for arithmetic, comparison, and bitwise operators. For
-example, even under C<use integer>, if you take the C<sqrt(2)>, you'll
-still get C<1.4142135623731> or so.
-
-Used on numbers, the bitwise operators ("&", "|", "^", "~", "<<",
-and ">>") always produce integral results. (But see also
-L<Bitwise String Operators>.) However, C<use integer> still has meaning for
-them. By default, their results are interpreted as unsigned integers, but
-if C<use integer> is in effect, their results are interpreted
-as signed integers. For example, C<~0> usually evaluates to a large
-integral value. However, C<use integer; ~0> is C<-1> on two's-complement
-machines.
-
-=head2 Floating-point Arithmetic
-
-X<floating-point> X<floating point> X<float> X<real>
-
-While C<use integer> provides integer-only arithmetic, there is no
-analogous mechanism to provide automatic rounding or truncation to a
-certain number of decimal places. For rounding to a certain number
-of digits, sprintf() or printf() is usually the easiest route.
-See L<perlfaq4>.
-
-Floating-point numbers are only approximations to what a mathematician
-would call real numbers. There are infinitely more reals than floats,
-so some corners must be cut. For example:
-
- printf "%.20g\n", 123456789123456789;
- # produces 123456789123456784
-
-Testing for exact floating-point equality or inequality is not a
-good idea. Here's a (relatively expensive) work-around to compare
-whether two floating-point numbers are equal to a particular number of
-decimal places. See Knuth, volume II, for a more robust treatment of
-this topic.
-
- sub fp_equal {
- my ($X, $Y, $POINTS) = @_;
- my ($tX, $tY);
- $tX = sprintf("%.${POINTS}g", $X);
- $tY = sprintf("%.${POINTS}g", $Y);
- return $tX eq $tY;
- }
-
-The POSIX module (part of the standard perl distribution) implements
-ceil(), floor(), and other mathematical and trigonometric functions.
-The Math::Complex module (part of the standard perl distribution)
-defines mathematical functions that work on both the reals and the
-imaginary numbers. Math::Complex not as efficient as POSIX, but
-POSIX can't work with complex numbers.
-
-Rounding in financial applications can have serious implications, and
-the rounding method used should be specified precisely. In these
-cases, it probably pays not to trust whichever system rounding is
-being used by Perl, but to instead implement the rounding function you
-need yourself.
-
-=head2 Bigger Numbers
-X<number, arbitrary precision>
-
-The standard C<Math::BigInt>, C<Math::BigRat>, and C<Math::BigFloat> modules,
-along with the C<bigint>, C<bigrat>, and C<bitfloat> pragmas, provide
-variable-precision arithmetic and overloaded operators, although
-they're currently pretty slow. At the cost of some space and
-considerable speed, they avoid the normal pitfalls associated with
-limited-precision representations.
-
- use 5.010;
- use bigint; # easy interface to Math::BigInt
- $x = 123456789123456789;
- say $x * $x;
- +15241578780673678515622620750190521
-
-Or with rationals:
-
- use 5.010;
- use bigrat;
- $a = 3/22;
- $b = 4/6;
- say "a/b is ", $a/$b;
- say "a*b is ", $a*$b;
- a/b is 9/44
- a*b is 1/11
-
-Several modules let you calculate with (bound only by memory and CPU time)
-unlimited or fixed precision. There are also some non-standard modules that
-provide faster implementations via external C libraries.
-
-Here is a short, but incomplete summary:
-
- Math::Fraction big, unlimited fractions like 9973 / 12967
- Math::String treat string sequences like numbers
- Math::FixedPrecision calculate with a fixed precision
- Math::Currency for currency calculations
- Bit::Vector manipulate bit vectors fast (uses C)
- Math::BigIntFast Bit::Vector wrapper for big numbers
- Math::Pari provides access to the Pari C library
- Math::BigInteger uses an external C library
- Math::Cephes uses external Cephes C library (no big numbers)
- Math::Cephes::Fraction fractions via the Cephes library
- Math::GMP another one using an external C library
-
-Choose wisely.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlopenbsd.pod b/Master/tlpkg/tlperl/lib/pods/perlopenbsd.pod
deleted file mode 100644
index 8126ce3eb71..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlopenbsd.pod
+++ /dev/null
@@ -1,30 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see pod/perlpod.pod) which is
-specifically designed to be readable as is.
-
-=head1 NAME
-
-perlopenbsd - Perl version 5 on OpenBSD systems
-
-=head1 DESCRIPTION
-
-This document describes various features of OpenBSD that will affect how Perl
-version 5 (hereafter just Perl) is compiled and/or runs.
-
-=head2 OpenBSD core dumps from getprotobyname_r and getservbyname_r with ithreads
-
-When Perl is configured to use ithreads, it will use re-entrant library calls
-in preference to non-re-entrant versions. There is an incompatibility in
-OpenBSD's C<getprotobyname_r> and C<getservbyname_r> function in versions 3.7
-and later that will cause a SEGV when called without doing a C<bzero> on
-their return structs prior to calling these functions. Current Perl's
-should handle this problem correctly. Older threaded Perls (5.8.6 or earlier)
-will run into this problem. If you want to run a threaded Perl on OpenBSD
-3.7 or higher, you will need to upgrade to at least Perl 5.8.7.
-
-=head1 AUTHOR
-
-Steve Peters <steve@fisharerojo.org>
-
-Please report any errors, updates, or suggestions to F<perlbug@perl.org>.
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlopentut.pod b/Master/tlpkg/tlperl/lib/pods/perlopentut.pod
deleted file mode 100644
index 4bb43bffd76..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlopentut.pod
+++ /dev/null
@@ -1,998 +0,0 @@
-=head1 NAME
-
-perlopentut - tutorial on opening things in Perl
-
-=head1 DESCRIPTION
-
-Perl has two simple, built-in ways to open files: the shell way for
-convenience, and the C way for precision. The shell way also has 2- and
-3-argument forms, which have different semantics for handling the filename.
-The choice is yours.
-
-=head1 Open E<agrave> la shell
-
-Perl's C<open> function was designed to mimic the way command-line
-redirection in the shell works. Here are some basic examples
-from the shell:
-
- $ myprogram file1 file2 file3
- $ myprogram < inputfile
- $ myprogram > outputfile
- $ myprogram >> outputfile
- $ myprogram | otherprogram
- $ otherprogram | myprogram
-
-And here are some more advanced examples:
-
- $ otherprogram | myprogram f1 - f2
- $ otherprogram 2>&1 | myprogram -
- $ myprogram <&3
- $ myprogram >&4
-
-Programmers accustomed to constructs like those above can take comfort
-in learning that Perl directly supports these familiar constructs using
-virtually the same syntax as the shell.
-
-=head2 Simple Opens
-
-The C<open> function takes two arguments: the first is a filehandle,
-and the second is a single string comprising both what to open and how
-to open it. C<open> returns true when it works, and when it fails,
-returns a false value and sets the special variable C<$!> to reflect
-the system error. If the filehandle was previously opened, it will
-be implicitly closed first.
-
-For example:
-
- open(INFO, "datafile") || die("can't open datafile: $!");
- open(INFO, "< datafile") || die("can't open datafile: $!");
- open(RESULTS,"> runstats") || die("can't open runstats: $!");
- open(LOG, ">> logfile ") || die("can't open logfile: $!");
-
-If you prefer the low-punctuation version, you could write that this way:
-
- open INFO, "< datafile" or die "can't open datafile: $!";
- open RESULTS,"> runstats" or die "can't open runstats: $!";
- open LOG, ">> logfile " or die "can't open logfile: $!";
-
-A few things to notice. First, the leading C<< < >> is optional.
-If omitted, Perl assumes that you want to open the file for reading.
-
-Note also that the first example uses the C<||> logical operator, and the
-second uses C<or>, which has lower precedence. Using C<||> in the latter
-examples would effectively mean
-
- open INFO, ( "< datafile" || die "can't open datafile: $!" );
-
-which is definitely not what you want.
-
-The other important thing to notice is that, just as in the shell,
-any whitespace before or after the filename is ignored. This is good,
-because you wouldn't want these to do different things:
-
- open INFO, "<datafile"
- open INFO, "< datafile"
- open INFO, "< datafile"
-
-Ignoring surrounding whitespace also helps for when you read a filename
-in from a different file, and forget to trim it before opening:
-
- $filename = <INFO>; # oops, \n still there
- open(EXTRA, "< $filename") || die "can't open $filename: $!";
-
-This is not a bug, but a feature. Because C<open> mimics the shell in
-its style of using redirection arrows to specify how to open the file, it
-also does so with respect to extra whitespace around the filename itself
-as well. For accessing files with naughty names, see
-L<"Dispelling the Dweomer">.
-
-There is also a 3-argument version of C<open>, which lets you put the
-special redirection characters into their own argument:
-
- open( INFO, ">", $datafile ) || die "Can't create $datafile: $!";
-
-In this case, the filename to open is the actual string in C<$datafile>,
-so you don't have to worry about C<$datafile> containing characters
-that might influence the open mode, or whitespace at the beginning of
-the filename that would be absorbed in the 2-argument version. Also,
-any reduction of unnecessary string interpolation is a good thing.
-
-=head2 Indirect Filehandles
-
-C<open>'s first argument can be a reference to a filehandle. As of
-perl 5.6.0, if the argument is uninitialized, Perl will automatically
-create a filehandle and put a reference to it in the first argument,
-like so:
-
- open( my $in, $infile ) or die "Couldn't read $infile: $!";
- while ( <$in> ) {
- # do something with $_
- }
- close $in;
-
-Indirect filehandles make namespace management easier. Since filehandles
-are global to the current package, two subroutines trying to open
-C<INFILE> will clash. With two functions opening indirect filehandles
-like C<my $infile>, there's no clash and no need to worry about future
-conflicts.
-
-Another convenient behavior is that an indirect filehandle automatically
-closes when there are no more references to it:
-
- sub firstline {
- open( my $in, shift ) && return scalar <$in>;
- # no close() required
- }
-
-Indirect filehandles also make it easy to pass filehandles to and return
-filehandles from subroutines:
-
- for my $file ( qw(this.conf that.conf) ) {
- my $fin = open_or_throw('<', $file);
- process_conf( $fin );
- # no close() needed
- }
-
- use Carp;
- sub open_or_throw {
- my ($mode, $filename) = @_;
- open my $h, $mode, $filename
- or croak "Could not open '$filename': $!";
- return $h;
- }
-
-=head2 Pipe Opens
-
-In C, when you want to open a file using the standard I/O library,
-you use the C<fopen> function, but when opening a pipe, you use the
-C<popen> function. But in the shell, you just use a different redirection
-character. That's also the case for Perl. The C<open> call
-remains the same--just its argument differs.
-
-If the leading character is a pipe symbol, C<open> starts up a new
-command and opens a write-only filehandle leading into that command.
-This lets you write into that handle and have what you write show up on
-that command's standard input. For example:
-
- open(PRINTER, "| lpr -Plp1") || die "can't run lpr: $!";
- print PRINTER "stuff\n";
- close(PRINTER) || die "can't close lpr: $!";
-
-If the trailing character is a pipe, you start up a new command and open a
-read-only filehandle leading out of that command. This lets whatever that
-command writes to its standard output show up on your handle for reading.
-For example:
-
- open(NET, "netstat -i -n |") || die "can't fork netstat: $!";
- while (<NET>) { } # do something with input
- close(NET) || die "can't close netstat: $!";
-
-What happens if you try to open a pipe to or from a non-existent
-command? If possible, Perl will detect the failure and set C<$!> as
-usual. But if the command contains special shell characters, such as
-C<E<gt>> or C<*>, called 'metacharacters', Perl does not execute the
-command directly. Instead, Perl runs the shell, which then tries to
-run the command. This means that it's the shell that gets the error
-indication. In such a case, the C<open> call will only indicate
-failure if Perl can't even run the shell. See L<perlfaq8/"How can I
-capture STDERR from an external command?"> to see how to cope with
-this. There's also an explanation in L<perlipc>.
-
-If you would like to open a bidirectional pipe, the IPC::Open2
-library will handle this for you. Check out
-L<perlipc/"Bidirectional Communication with Another Process">
-
-perl-5.6.x introduced a version of piped open that executes a process
-based on its command line arguments without relying on the shell. (Similar
-to the C<system(@LIST)> notation.) This is safer and faster than executing
-a single argument pipe-command, but does not allow special shell
-constructs. (It is also not supported on Microsoft Windows, Mac OS Classic
-or RISC OS.)
-
-Here's an example of C<open '-|'>, which prints a random Unix
-fortune cookie as uppercase:
-
- my $collection = shift(@ARGV);
- open my $fortune, '-|', 'fortune', $collection
- or die "Could not find fortune - $!";
- while (<$fortune>)
- {
- print uc($_);
- }
- close($fortune);
-
-And this C<open '|-'> pipes into lpr:
-
- open my $printer, '|-', 'lpr', '-Plp1'
- or die "can't run lpr: $!";
- print {$printer} "stuff\n";
- close($printer)
- or die "can't close lpr: $!";
-
-=head2 The Minus File
-
-Again following the lead of the standard shell utilities, Perl's
-C<open> function treats a file whose name is a single minus, "-", in a
-special way. If you open minus for reading, it really means to access
-the standard input. If you open minus for writing, it really means to
-access the standard output.
-
-If minus can be used as the default input or default output, what happens
-if you open a pipe into or out of minus? What's the default command it
-would run? The same script as you're currently running! This is actually
-a stealth C<fork> hidden inside an C<open> call. See
-L<perlipc/"Safe Pipe Opens"> for details.
-
-=head2 Mixing Reads and Writes
-
-It is possible to specify both read and write access. All you do is
-add a "+" symbol in front of the redirection. But as in the shell,
-using a less-than on a file never creates a new file; it only opens an
-existing one. On the other hand, using a greater-than always clobbers
-(truncates to zero length) an existing file, or creates a brand-new one
-if there isn't an old one. Adding a "+" for read-write doesn't affect
-whether it only works on existing files or always clobbers existing ones.
-
- open(WTMP, "+< /usr/adm/wtmp")
- || die "can't open /usr/adm/wtmp: $!";
-
- open(SCREEN, "+> lkscreen")
- || die "can't open lkscreen: $!";
-
- open(LOGFILE, "+>> /var/log/applog")
- || die "can't open /var/log/applog: $!";
-
-The first one won't create a new file, and the second one will always
-clobber an old one. The third one will create a new file if necessary
-and not clobber an old one, and it will allow you to read at any point
-in the file, but all writes will always go to the end. In short,
-the first case is substantially more common than the second and third
-cases, which are almost always wrong. (If you know C, the plus in
-Perl's C<open> is historically derived from the one in C's fopen(3S),
-which it ultimately calls.)
-
-In fact, when it comes to updating a file, unless you're working on
-a binary file as in the WTMP case above, you probably don't want to
-use this approach for updating. Instead, Perl's B<-i> flag comes to
-the rescue. The following command takes all the C, C++, or yacc source
-or header files and changes all their foo's to bar's, leaving
-the old version in the original filename with a ".orig" tacked
-on the end:
-
- $ perl -i.orig -pe 's/\bfoo\b/bar/g' *.[Cchy]
-
-This is a short cut for some renaming games that are really
-the best way to update textfiles. See the second question in
-L<perlfaq5> for more details.
-
-=head2 Filters
-
-One of the most common uses for C<open> is one you never
-even notice. When you process the ARGV filehandle using
-C<< <ARGV> >>, Perl actually does an implicit open
-on each file in @ARGV. Thus a program called like this:
-
- $ myprogram file1 file2 file3
-
-can have all its files opened and processed one at a time
-using a construct no more complex than:
-
- while (<>) {
- # do something with $_
- }
-
-If @ARGV is empty when the loop first begins, Perl pretends you've opened
-up minus, that is, the standard input. In fact, $ARGV, the currently
-open file during C<< <ARGV> >> processing, is even set to "-"
-in these circumstances.
-
-You are welcome to pre-process your @ARGV before starting the loop to
-make sure it's to your liking. One reason to do this might be to remove
-command options beginning with a minus. While you can always roll the
-simple ones by hand, the Getopts modules are good for this:
-
- use Getopt::Std;
-
- # -v, -D, -o ARG, sets $opt_v, $opt_D, $opt_o
- getopts("vDo:");
-
- # -v, -D, -o ARG, sets $args{v}, $args{D}, $args{o}
- getopts("vDo:", \%args);
-
-Or the standard Getopt::Long module to permit named arguments:
-
- use Getopt::Long;
- GetOptions( "verbose" => \$verbose, # --verbose
- "Debug" => \$debug, # --Debug
- "output=s" => \$output );
- # --output=somestring or --output somestring
-
-Another reason for preprocessing arguments is to make an empty
-argument list default to all files:
-
- @ARGV = glob("*") unless @ARGV;
-
-You could even filter out all but plain, text files. This is a bit
-silent, of course, and you might prefer to mention them on the way.
-
- @ARGV = grep { -f && -T } @ARGV;
-
-If you're using the B<-n> or B<-p> command-line options, you
-should put changes to @ARGV in a C<BEGIN{}> block.
-
-Remember that a normal C<open> has special properties, in that it might
-call fopen(3S) or it might called popen(3S), depending on what its
-argument looks like; that's why it's sometimes called "magic open".
-Here's an example:
-
- $pwdinfo = `domainname` =~ /^(\(none\))?$/
- ? '< /etc/passwd'
- : 'ypcat passwd |';
-
- open(PWD, $pwdinfo)
- or die "can't open $pwdinfo: $!";
-
-This sort of thing also comes into play in filter processing. Because
-C<< <ARGV> >> processing employs the normal, shell-style Perl C<open>,
-it respects all the special things we've already seen:
-
- $ myprogram f1 "cmd1|" - f2 "cmd2|" f3 < tmpfile
-
-That program will read from the file F<f1>, the process F<cmd1>, standard
-input (F<tmpfile> in this case), the F<f2> file, the F<cmd2> command,
-and finally the F<f3> file.
-
-Yes, this also means that if you have files named "-" (and so on) in
-your directory, they won't be processed as literal files by C<open>.
-You'll need to pass them as "./-", much as you would for the I<rm> program,
-or you could use C<sysopen> as described below.
-
-One of the more interesting applications is to change files of a certain
-name into pipes. For example, to autoprocess gzipped or compressed
-files by decompressing them with I<gzip>:
-
- @ARGV = map { /\.(gz|Z)$/ ? "gzip -dc $_ |" : $_ } @ARGV;
-
-Or, if you have the I<GET> program installed from LWP,
-you can fetch URLs before processing them:
-
- @ARGV = map { m#^\w+://# ? "GET $_ |" : $_ } @ARGV;
-
-It's not for nothing that this is called magic C<< <ARGV> >>.
-Pretty nifty, eh?
-
-=head1 Open E<agrave> la C
-
-If you want the convenience of the shell, then Perl's C<open> is
-definitely the way to go. On the other hand, if you want finer precision
-than C's simplistic fopen(3S) provides you should look to Perl's
-C<sysopen>, which is a direct hook into the open(2) system call.
-That does mean it's a bit more involved, but that's the price of
-precision.
-
-C<sysopen> takes 3 (or 4) arguments.
-
- sysopen HANDLE, PATH, FLAGS, [MASK]
-
-The HANDLE argument is a filehandle just as with C<open>. The PATH is
-a literal path, one that doesn't pay attention to any greater-thans or
-less-thans or pipes or minuses, nor ignore whitespace. If it's there,
-it's part of the path. The FLAGS argument contains one or more values
-derived from the Fcntl module that have been or'd together using the
-bitwise "|" operator. The final argument, the MASK, is optional; if
-present, it is combined with the user's current umask for the creation
-mode of the file. You should usually omit this.
-
-Although the traditional values of read-only, write-only, and read-write
-are 0, 1, and 2 respectively, this is known not to hold true on some
-systems. Instead, it's best to load in the appropriate constants first
-from the Fcntl module, which supplies the following standard flags:
-
- O_RDONLY Read only
- O_WRONLY Write only
- O_RDWR Read and write
- O_CREAT Create the file if it doesn't exist
- O_EXCL Fail if the file already exists
- O_APPEND Append to the file
- O_TRUNC Truncate the file
- O_NONBLOCK Non-blocking access
-
-Less common flags that are sometimes available on some operating
-systems include C<O_BINARY>, C<O_TEXT>, C<O_SHLOCK>, C<O_EXLOCK>,
-C<O_DEFER>, C<O_SYNC>, C<O_ASYNC>, C<O_DSYNC>, C<O_RSYNC>,
-C<O_NOCTTY>, C<O_NDELAY> and C<O_LARGEFILE>. Consult your open(2)
-manpage or its local equivalent for details. (Note: starting from
-Perl release 5.6 the C<O_LARGEFILE> flag, if available, is automatically
-added to the sysopen() flags because large files are the default.)
-
-Here's how to use C<sysopen> to emulate the simple C<open> calls we had
-before. We'll omit the C<|| die $!> checks for clarity, but make sure
-you always check the return values in real code. These aren't quite
-the same, since C<open> will trim leading and trailing whitespace,
-but you'll get the idea.
-
-To open a file for reading:
-
- open(FH, "< $path");
- sysopen(FH, $path, O_RDONLY);
-
-To open a file for writing, creating a new file if needed or else truncating
-an old file:
-
- open(FH, "> $path");
- sysopen(FH, $path, O_WRONLY | O_TRUNC | O_CREAT);
-
-To open a file for appending, creating one if necessary:
-
- open(FH, ">> $path");
- sysopen(FH, $path, O_WRONLY | O_APPEND | O_CREAT);
-
-To open a file for update, where the file must already exist:
-
- open(FH, "+< $path");
- sysopen(FH, $path, O_RDWR);
-
-And here are things you can do with C<sysopen> that you cannot do with
-a regular C<open>. As you'll see, it's just a matter of controlling the
-flags in the third argument.
-
-To open a file for writing, creating a new file which must not previously
-exist:
-
- sysopen(FH, $path, O_WRONLY | O_EXCL | O_CREAT);
-
-To open a file for appending, where that file must already exist:
-
- sysopen(FH, $path, O_WRONLY | O_APPEND);
-
-To open a file for update, creating a new file if necessary:
-
- sysopen(FH, $path, O_RDWR | O_CREAT);
-
-To open a file for update, where that file must not already exist:
-
- sysopen(FH, $path, O_RDWR | O_EXCL | O_CREAT);
-
-To open a file without blocking, creating one if necessary:
-
- sysopen(FH, $path, O_WRONLY | O_NONBLOCK | O_CREAT);
-
-=head2 Permissions E<agrave> la mode
-
-If you omit the MASK argument to C<sysopen>, Perl uses the octal value
-0666. The normal MASK to use for executables and directories should
-be 0777, and for anything else, 0666.
-
-Why so permissive? Well, it isn't really. The MASK will be modified
-by your process's current C<umask>. A umask is a number representing
-I<disabled> permissions bits; that is, bits that will not be turned on
-in the created file's permissions field.
-
-For example, if your C<umask> were 027, then the 020 part would
-disable the group from writing, and the 007 part would disable others
-from reading, writing, or executing. Under these conditions, passing
-C<sysopen> 0666 would create a file with mode 0640, since C<0666 & ~027>
-is 0640.
-
-You should seldom use the MASK argument to C<sysopen()>. That takes
-away the user's freedom to choose what permission new files will have.
-Denying choice is almost always a bad thing. One exception would be for
-cases where sensitive or private data is being stored, such as with mail
-folders, cookie files, and internal temporary files.
-
-=head1 Obscure Open Tricks
-
-=head2 Re-Opening Files (dups)
-
-Sometimes you already have a filehandle open, and want to make another
-handle that's a duplicate of the first one. In the shell, we place an
-ampersand in front of a file descriptor number when doing redirections.
-For example, C<< 2>&1 >> makes descriptor 2 (that's STDERR in Perl)
-be redirected into descriptor 1 (which is usually Perl's STDOUT).
-The same is essentially true in Perl: a filename that begins with an
-ampersand is treated instead as a file descriptor if a number, or as a
-filehandle if a string.
-
- open(SAVEOUT, ">&SAVEERR") || die "couldn't dup SAVEERR: $!";
- open(MHCONTEXT, "<&4") || die "couldn't dup fd4: $!";
-
-That means that if a function is expecting a filename, but you don't
-want to give it a filename because you already have the file open, you
-can just pass the filehandle with a leading ampersand. It's best to
-use a fully qualified handle though, just in case the function happens
-to be in a different package:
-
- somefunction("&main::LOGFILE");
-
-This way if somefunction() is planning on opening its argument, it can
-just use the already opened handle. This differs from passing a handle,
-because with a handle, you don't open the file. Here you have something
-you can pass to open.
-
-If you have one of those tricky, newfangled I/O objects that the C++
-folks are raving about, then this doesn't work because those aren't a
-proper filehandle in the native Perl sense. You'll have to use fileno()
-to pull out the proper descriptor number, assuming you can:
-
- use IO::Socket;
- $handle = IO::Socket::INET->new("www.perl.com:80");
- $fd = $handle->fileno;
- somefunction("&$fd"); # not an indirect function call
-
-It can be easier (and certainly will be faster) just to use real
-filehandles though:
-
- use IO::Socket;
- local *REMOTE = IO::Socket::INET->new("www.perl.com:80");
- die "can't connect" unless defined(fileno(REMOTE));
- somefunction("&main::REMOTE");
-
-If the filehandle or descriptor number is preceded not just with a simple
-"&" but rather with a "&=" combination, then Perl will not create a
-completely new descriptor opened to the same place using the dup(2)
-system call. Instead, it will just make something of an alias to the
-existing one using the fdopen(3S) library call. This is slightly more
-parsimonious of systems resources, although this is less a concern
-these days. Here's an example of that:
-
- $fd = $ENV{"MHCONTEXTFD"};
- open(MHCONTEXT, "<&=$fd") or die "couldn't fdopen $fd: $!";
-
-If you're using magic C<< <ARGV> >>, you could even pass in as a
-command line argument in @ARGV something like C<"<&=$MHCONTEXTFD">,
-but we've never seen anyone actually do this.
-
-=head2 Dispelling the Dweomer
-
-Perl is more of a DWIMmer language than something like Java--where DWIM
-is an acronym for "do what I mean". But this principle sometimes leads
-to more hidden magic than one knows what to do with. In this way, Perl
-is also filled with I<dweomer>, an obscure word meaning an enchantment.
-Sometimes, Perl's DWIMmer is just too much like dweomer for comfort.
-
-If magic C<open> is a bit too magical for you, you don't have to turn
-to C<sysopen>. To open a file with arbitrary weird characters in
-it, it's necessary to protect any leading and trailing whitespace.
-Leading whitespace is protected by inserting a C<"./"> in front of a
-filename that starts with whitespace. Trailing whitespace is protected
-by appending an ASCII NUL byte (C<"\0">) at the end of the string.
-
- $file =~ s#^(\s)#./$1#;
- open(FH, "< $file\0") || die "can't open $file: $!";
-
-This assumes, of course, that your system considers dot the current
-working directory, slash the directory separator, and disallows ASCII
-NULs within a valid filename. Most systems follow these conventions,
-including all POSIX systems as well as proprietary Microsoft systems.
-The only vaguely popular system that doesn't work this way is the
-"Classic" Macintosh system, which uses a colon where the rest of us
-use a slash. Maybe C<sysopen> isn't such a bad idea after all.
-
-If you want to use C<< <ARGV> >> processing in a totally boring
-and non-magical way, you could do this first:
-
- # "Sam sat on the ground and put his head in his hands.
- # 'I wish I had never come here, and I don't want to see
- # no more magic,' he said, and fell silent."
- for (@ARGV) {
- s#^([^./])#./$1#;
- $_ .= "\0";
- }
- while (<>) {
- # now process $_
- }
-
-But be warned that users will not appreciate being unable to use "-"
-to mean standard input, per the standard convention.
-
-=head2 Paths as Opens
-
-You've probably noticed how Perl's C<warn> and C<die> functions can
-produce messages like:
-
- Some warning at scriptname line 29, <FH> line 7.
-
-That's because you opened a filehandle FH, and had read in seven records
-from it. But what was the name of the file, rather than the handle?
-
-If you aren't running with C<strict refs>, or if you've turned them off
-temporarily, then all you have to do is this:
-
- open($path, "< $path") || die "can't open $path: $!";
- while (<$path>) {
- # whatever
- }
-
-Since you're using the pathname of the file as its handle,
-you'll get warnings more like
-
- Some warning at scriptname line 29, </etc/motd> line 7.
-
-=head2 Single Argument Open
-
-Remember how we said that Perl's open took two arguments? That was a
-passive prevarication. You see, it can also take just one argument.
-If and only if the variable is a global variable, not a lexical, you
-can pass C<open> just one argument, the filehandle, and it will
-get the path from the global scalar variable of the same name.
-
- $FILE = "/etc/motd";
- open FILE or die "can't open $FILE: $!";
- while (<FILE>) {
- # whatever
- }
-
-Why is this here? Someone has to cater to the hysterical porpoises.
-It's something that's been in Perl since the very beginning, if not
-before.
-
-=head2 Playing with STDIN and STDOUT
-
-One clever move with STDOUT is to explicitly close it when you're done
-with the program.
-
- END { close(STDOUT) || die "can't close stdout: $!" }
-
-If you don't do this, and your program fills up the disk partition due
-to a command line redirection, it won't report the error exit with a
-failure status.
-
-You don't have to accept the STDIN and STDOUT you were given. You are
-welcome to reopen them if you'd like.
-
- open(STDIN, "< datafile")
- || die "can't open datafile: $!";
-
- open(STDOUT, "> output")
- || die "can't open output: $!";
-
-And then these can be accessed directly or passed on to subprocesses.
-This makes it look as though the program were initially invoked
-with those redirections from the command line.
-
-It's probably more interesting to connect these to pipes. For example:
-
- $pager = $ENV{PAGER} || "(less || more)";
- open(STDOUT, "| $pager")
- || die "can't fork a pager: $!";
-
-This makes it appear as though your program were called with its stdout
-already piped into your pager. You can also use this kind of thing
-in conjunction with an implicit fork to yourself. You might do this
-if you would rather handle the post processing in your own program,
-just in a different process:
-
- head(100);
- while (<>) {
- print;
- }
-
- sub head {
- my $lines = shift || 20;
- return if $pid = open(STDOUT, "|-"); # return if parent
- die "cannot fork: $!" unless defined $pid;
- while (<STDIN>) {
- last if --$lines < 0;
- print;
- }
- exit;
- }
-
-This technique can be applied to repeatedly push as many filters on your
-output stream as you wish.
-
-=head1 Other I/O Issues
-
-These topics aren't really arguments related to C<open> or C<sysopen>,
-but they do affect what you do with your open files.
-
-=head2 Opening Non-File Files
-
-When is a file not a file? Well, you could say when it exists but
-isn't a plain file. We'll check whether it's a symbolic link first,
-just in case.
-
- if (-l $file || ! -f _) {
- print "$file is not a plain file\n";
- }
-
-What other kinds of files are there than, well, files? Directories,
-symbolic links, named pipes, Unix-domain sockets, and block and character
-devices. Those are all files, too--just not I<plain> files. This isn't
-the same issue as being a text file. Not all text files are plain files.
-Not all plain files are text files. That's why there are separate C<-f>
-and C<-T> file tests.
-
-To open a directory, you should use the C<opendir> function, then
-process it with C<readdir>, carefully restoring the directory
-name if necessary:
-
- opendir(DIR, $dirname) or die "can't opendir $dirname: $!";
- while (defined($file = readdir(DIR))) {
- # do something with "$dirname/$file"
- }
- closedir(DIR);
-
-If you want to process directories recursively, it's better to use the
-File::Find module. For example, this prints out all files recursively
-and adds a slash to their names if the file is a directory.
-
- @ARGV = qw(.) unless @ARGV;
- use File::Find;
- find sub { print $File::Find::name, -d && '/', "\n" }, @ARGV;
-
-This finds all bogus symbolic links beneath a particular directory:
-
- find sub { print "$File::Find::name\n" if -l && !-e }, $dir;
-
-As you see, with symbolic links, you can just pretend that it is
-what it points to. Or, if you want to know I<what> it points to, then
-C<readlink> is called for:
-
- if (-l $file) {
- if (defined($whither = readlink($file))) {
- print "$file points to $whither\n";
- } else {
- print "$file points nowhere: $!\n";
- }
- }
-
-=head2 Opening Named Pipes
-
-Named pipes are a different matter. You pretend they're regular files,
-but their opens will normally block until there is both a reader and
-a writer. You can read more about them in L<perlipc/"Named Pipes">.
-Unix-domain sockets are rather different beasts as well; they're
-described in L<perlipc/"Unix-Domain TCP Clients and Servers">.
-
-When it comes to opening devices, it can be easy and it can be tricky.
-We'll assume that if you're opening up a block device, you know what
-you're doing. The character devices are more interesting. These are
-typically used for modems, mice, and some kinds of printers. This is
-described in L<perlfaq8/"How do I read and write the serial port?">
-It's often enough to open them carefully:
-
- sysopen(TTYIN, "/dev/ttyS1", O_RDWR | O_NDELAY | O_NOCTTY)
- # (O_NOCTTY no longer needed on POSIX systems)
- or die "can't open /dev/ttyS1: $!";
- open(TTYOUT, "+>&TTYIN")
- or die "can't dup TTYIN: $!";
-
- $ofh = select(TTYOUT); $| = 1; select($ofh);
-
- print TTYOUT "+++at\015";
- $answer = <TTYIN>;
-
-With descriptors that you haven't opened using C<sysopen>, such as
-sockets, you can set them to be non-blocking using C<fcntl>:
-
- use Fcntl;
- my $old_flags = fcntl($handle, F_GETFL, 0)
- or die "can't get flags: $!";
- fcntl($handle, F_SETFL, $old_flags | O_NONBLOCK)
- or die "can't set non blocking: $!";
-
-Rather than losing yourself in a morass of twisting, turning C<ioctl>s,
-all dissimilar, if you're going to manipulate ttys, it's best to
-make calls out to the stty(1) program if you have it, or else use the
-portable POSIX interface. To figure this all out, you'll need to read the
-termios(3) manpage, which describes the POSIX interface to tty devices,
-and then L<POSIX>, which describes Perl's interface to POSIX. There are
-also some high-level modules on CPAN that can help you with these games.
-Check out Term::ReadKey and Term::ReadLine.
-
-=head2 Opening Sockets
-
-What else can you open? To open a connection using sockets, you won't use
-one of Perl's two open functions. See
-L<perlipc/"Sockets: Client/Server Communication"> for that. Here's an
-example. Once you have it, you can use FH as a bidirectional filehandle.
-
- use IO::Socket;
- local *FH = IO::Socket::INET->new("www.perl.com:80");
-
-For opening up a URL, the LWP modules from CPAN are just what
-the doctor ordered. There's no filehandle interface, but
-it's still easy to get the contents of a document:
-
- use LWP::Simple;
- $doc = get('http://www.cpan.org/');
-
-=head2 Binary Files
-
-On certain legacy systems with what could charitably be called terminally
-convoluted (some would say broken) I/O models, a file isn't a file--at
-least, not with respect to the C standard I/O library. On these old
-systems whose libraries (but not kernels) distinguish between text and
-binary streams, to get files to behave properly you'll have to bend over
-backwards to avoid nasty problems. On such infelicitous systems, sockets
-and pipes are already opened in binary mode, and there is currently no
-way to turn that off. With files, you have more options.
-
-Another option is to use the C<binmode> function on the appropriate
-handles before doing regular I/O on them:
-
- binmode(STDIN);
- binmode(STDOUT);
- while (<STDIN>) { print }
-
-Passing C<sysopen> a non-standard flag option will also open the file in
-binary mode on those systems that support it. This is the equivalent of
-opening the file normally, then calling C<binmode> on the handle.
-
- sysopen(BINDAT, "records.data", O_RDWR | O_BINARY)
- || die "can't open records.data: $!";
-
-Now you can use C<read> and C<print> on that handle without worrying
-about the non-standard system I/O library breaking your data. It's not
-a pretty picture, but then, legacy systems seldom are. CP/M will be
-with us until the end of days, and after.
-
-On systems with exotic I/O systems, it turns out that, astonishingly
-enough, even unbuffered I/O using C<sysread> and C<syswrite> might do
-sneaky data mutilation behind your back.
-
- while (sysread(WHENCE, $buf, 1024)) {
- syswrite(WHITHER, $buf, length($buf));
- }
-
-Depending on the vicissitudes of your runtime system, even these calls
-may need C<binmode> or C<O_BINARY> first. Systems known to be free of
-such difficulties include Unix, the Mac OS, Plan 9, and Inferno.
-
-=head2 File Locking
-
-In a multitasking environment, you may need to be careful not to collide
-with other processes who want to do I/O on the same files as you
-are working on. You'll often need shared or exclusive locks
-on files for reading and writing respectively. You might just
-pretend that only exclusive locks exist.
-
-Never use the existence of a file C<-e $file> as a locking indication,
-because there is a race condition between the test for the existence of
-the file and its creation. It's possible for another process to create
-a file in the slice of time between your existence check and your attempt
-to create the file. Atomicity is critical.
-
-Perl's most portable locking interface is via the C<flock> function,
-whose simplicity is emulated on systems that don't directly support it
-such as SysV or Windows. The underlying semantics may affect how
-it all works, so you should learn how C<flock> is implemented on your
-system's port of Perl.
-
-File locking I<does not> lock out another process that would like to
-do I/O. A file lock only locks out others trying to get a lock, not
-processes trying to do I/O. Because locks are advisory, if one process
-uses locking and another doesn't, all bets are off.
-
-By default, the C<flock> call will block until a lock is granted.
-A request for a shared lock will be granted as soon as there is no
-exclusive locker. A request for an exclusive lock will be granted as
-soon as there is no locker of any kind. Locks are on file descriptors,
-not file names. You can't lock a file until you open it, and you can't
-hold on to a lock once the file has been closed.
-
-Here's how to get a blocking shared lock on a file, typically used
-for reading:
-
- use 5.004;
- use Fcntl qw(:DEFAULT :flock);
- open(FH, "< filename") or die "can't open filename: $!";
- flock(FH, LOCK_SH) or die "can't lock filename: $!";
- # now read from FH
-
-You can get a non-blocking lock by using C<LOCK_NB>.
-
- flock(FH, LOCK_SH | LOCK_NB)
- or die "can't lock filename: $!";
-
-This can be useful for producing more user-friendly behaviour by warning
-if you're going to be blocking:
-
- use 5.004;
- use Fcntl qw(:DEFAULT :flock);
- open(FH, "< filename") or die "can't open filename: $!";
- unless (flock(FH, LOCK_SH | LOCK_NB)) {
- $| = 1;
- print "Waiting for lock...";
- flock(FH, LOCK_SH) or die "can't lock filename: $!";
- print "got it.\n"
- }
- # now read from FH
-
-To get an exclusive lock, typically used for writing, you have to be
-careful. We C<sysopen> the file so it can be locked before it gets
-emptied. You can get a nonblocking version using C<LOCK_EX | LOCK_NB>.
-
- use 5.004;
- use Fcntl qw(:DEFAULT :flock);
- sysopen(FH, "filename", O_WRONLY | O_CREAT)
- or die "can't open filename: $!";
- flock(FH, LOCK_EX)
- or die "can't lock filename: $!";
- truncate(FH, 0)
- or die "can't truncate filename: $!";
- # now write to FH
-
-Finally, due to the uncounted millions who cannot be dissuaded from
-wasting cycles on useless vanity devices called hit counters, here's
-how to increment a number in a file safely:
-
- use Fcntl qw(:DEFAULT :flock);
-
- sysopen(FH, "numfile", O_RDWR | O_CREAT)
- or die "can't open numfile: $!";
- # autoflush FH
- $ofh = select(FH); $| = 1; select ($ofh);
- flock(FH, LOCK_EX)
- or die "can't write-lock numfile: $!";
-
- $num = <FH> || 0;
- seek(FH, 0, 0)
- or die "can't rewind numfile : $!";
- print FH $num+1, "\n"
- or die "can't write numfile: $!";
-
- truncate(FH, tell(FH))
- or die "can't truncate numfile: $!";
- close(FH)
- or die "can't close numfile: $!";
-
-=head2 IO Layers
-
-In Perl 5.8.0 a new I/O framework called "PerlIO" was introduced.
-This is a new "plumbing" for all the I/O happening in Perl; for the
-most part everything will work just as it did, but PerlIO also brought
-in some new features such as the ability to think of I/O as "layers".
-One I/O layer may in addition to just moving the data also do
-transformations on the data. Such transformations may include
-compression and decompression, encryption and decryption, and transforming
-between various character encodings.
-
-Full discussion about the features of PerlIO is out of scope for this
-tutorial, but here is how to recognize the layers being used:
-
-=over 4
-
-=item *
-
-The three-(or more)-argument form of C<open> is being used and the
-second argument contains something else in addition to the usual
-C<< '<' >>, C<< '>' >>, C<< '>>' >>, C<< '|' >> and their variants,
-for example:
-
- open(my $fh, "<:crlf", $fn);
-
-=item *
-
-The two-argument form of C<binmode> is being used, for example
-
- binmode($fh, ":encoding(utf16)");
-
-=back
-
-For more detailed discussion about PerlIO see L<PerlIO>;
-for more detailed discussion about Unicode and I/O see L<perluniintro>.
-
-=head1 SEE ALSO
-
-The C<open> and C<sysopen> functions in perlfunc(1);
-the system open(2), dup(2), fopen(3), and fdopen(3) manpages;
-the POSIX documentation.
-
-=head1 AUTHOR and COPYRIGHT
-
-Copyright 1998 Tom Christiansen.
-
-This documentation is free; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-Irrespective of its distribution, all code examples in these files are
-hereby placed into the public domain. You are permitted and
-encouraged to use this code in your own programs for fun or for profit
-as you see fit. A simple comment in the code giving credit would be
-courteous but is not required.
-
-=head1 HISTORY
-
-First release: Sat Jan 9 08:09:11 MST 1999
diff --git a/Master/tlpkg/tlperl/lib/pods/perlos2.pod b/Master/tlpkg/tlperl/lib/pods/perlos2.pod
deleted file mode 100644
index 7fc9b63d2cd..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlos2.pod
+++ /dev/null
@@ -1,2741 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see perlpod manpage) which is
-specially designed to be readable as is.
-
-=head1 NAME
-
-perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
-
-=head1 SYNOPSIS
-
-One can read this document in the following formats:
-
- man perlos2
- view perl perlos2
- explorer perlos2.html
- info perlos2
-
-to list some (not all may be available simultaneously), or it may
-be read I<as is>: either as F<README.os2>, or F<pod/perlos2.pod>.
-
-To read the F<.INF> version of documentation (B<very> recommended)
-outside of OS/2, one needs an IBM's reader (may be available on IBM
-ftp sites (?) (URL anyone?)) or shipped with PC DOS 7.0 and IBM's
-Visual Age C++ 3.5.
-
-A copy of a Win* viewer is contained in the "Just add OS/2 Warp" package
-
- ftp://ftp.software.ibm.com/ps/products/os2/tools/jaow/jaow.zip
-
-in F<?:\JUST_ADD\view.exe>. This gives one an access to EMX's
-F<.INF> docs as well (text form is available in F</emx/doc> in
-EMX's distribution). There is also a different viewer named xview.
-
-Note that if you have F<lynx.exe> or F<netscape.exe> installed, you can follow WWW links
-from this document in F<.INF> format. If you have EMX docs installed
-correctly, you can follow library links (you need to have C<view emxbook>
-working by setting C<EMXBOOK> environment variable as it is described
-in EMX docs).
-
-=cut
-
-Contents (This may be a little bit obsolete)
-
- perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
-
- NAME
- SYNOPSIS
- DESCRIPTION
- - Target
- - Other OSes
- - Prerequisites
- - Starting Perl programs under OS/2 (and DOS and...)
- - Starting OS/2 (and DOS) programs under Perl
- Frequently asked questions
- - "It does not work"
- - I cannot run external programs
- - I cannot embed perl into my program, or use perl.dll from my
- - `` and pipe-open do not work under DOS.
- - Cannot start find.exe "pattern" file
- INSTALLATION
- - Automatic binary installation
- - Manual binary installation
- - Warning
- Accessing documentation
- - OS/2 .INF file
- - Plain text
- - Manpages
- - HTML
- - GNU info files
- - PDF files
- - LaTeX docs
- BUILD
- - The short story
- - Prerequisites
- - Getting perl source
- - Application of the patches
- - Hand-editing
- - Making
- - Testing
- - Installing the built perl
- - a.out-style build
- Build FAQ
- - Some / became \ in pdksh.
- - 'errno' - unresolved external
- - Problems with tr or sed
- - Some problem (forget which ;-)
- - Library ... not found
- - Segfault in make
- - op/sprintf test failure
- Specific (mis)features of OS/2 port
- - setpriority, getpriority
- - system()
- - extproc on the first line
- - Additional modules:
- - Prebuilt methods:
- - Prebuilt variables:
- - Misfeatures
- - Modifications
- - Identifying DLLs
- - Centralized management of resources
- Perl flavors
- - perl.exe
- - perl_.exe
- - perl__.exe
- - perl___.exe
- - Why strange names?
- - Why dynamic linking?
- - Why chimera build?
- ENVIRONMENT
- - PERLLIB_PREFIX
- - PERL_BADLANG
- - PERL_BADFREE
- - PERL_SH_DIR
- - USE_PERL_FLOCK
- - TMP or TEMP
- Evolution
- - Text-mode filehandles
- - Priorities
- - DLL name mangling: pre 5.6.2
- - DLL name mangling: 5.6.2 and beyond
- - DLL forwarder generation
- - Threading
- - Calls to external programs
- - Memory allocation
- - Threads
- BUGS
- AUTHOR
- SEE ALSO
-
-=head1 DESCRIPTION
-
-=head2 Target
-
-The target is to make OS/2 one of the best supported platform for
-using/building/developing Perl and I<Perl applications>, as well as
-make Perl the best language to use under OS/2. The secondary target is
-to try to make this work under DOS and Win* as well (but not B<too> hard).
-
-The current state is quite close to this target. Known limitations:
-
-=over 5
-
-=item *
-
-Some *nix programs use fork() a lot; with the mostly useful flavors of
-perl for OS/2 (there are several built simultaneously) this is
-supported; but some flavors do not support this (e.g., when Perl is
-called from inside REXX). Using fork() after
-I<use>ing dynamically loading extensions would not work with I<very> old
-versions of EMX.
-
-=item *
-
-You need a separate perl executable F<perl__.exe> (see L</perl__.exe>)
-if you want to use PM code in your application (as Perl/Tk or OpenGL
-Perl modules do) without having a text-mode window present.
-
-While using the standard F<perl.exe> from a text-mode window is possible
-too, I have seen cases when this causes degradation of the system stability.
-Using F<perl__.exe> avoids such a degradation.
-
-=item *
-
-There is no simple way to access WPS objects. The only way I know
-is via C<OS2::REXX> and C<SOM> extensions (see L<OS2::REXX>, L<SOM>).
-However, we do not have access to
-convenience methods of Object-REXX. (Is it possible at all? I know
-of no Object-REXX API.) The C<SOM> extension (currently in alpha-text)
-may eventually remove this shortcoming; however, due to the fact that
-DII is not supported by the C<SOM> module, using C<SOM> is not as
-convenient as one would like it.
-
-=back
-
-Please keep this list up-to-date by informing me about other items.
-
-=head2 Other OSes
-
-Since OS/2 port of perl uses a remarkable EMX environment, it can
-run (and build extensions, and - possibly - be built itself) under any
-environment which can run EMX. The current list is DOS,
-DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors,
-only one works, see L<"perl_.exe">.
-
-Note that not all features of Perl are available under these
-environments. This depends on the features the I<extender> - most
-probably RSX - decided to implement.
-
-Cf. L</Prerequisites>.
-
-=head2 Prerequisites
-
-=over 6
-
-=item EMX
-
-EMX runtime is required (may be substituted by RSX). Note that
-it is possible to make F<perl_.exe> to run under DOS without any
-external support by binding F<emx.exe>/F<rsx.exe> to it, see C<emxbind>. Note
-that under DOS for best results one should use RSX runtime, which
-has much more functions working (like C<fork>, C<popen> and so on). In
-fact RSX is required if there is no VCPI present. Note the
-RSX requires DPMI. Many implementations of DPMI are known to be very
-buggy, beware!
-
-Only the latest runtime is supported, currently C<0.9d fix 03>. Perl may run
-under earlier versions of EMX, but this is not tested.
-
-One can get different parts of EMX from, say
-
- ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/emx+gcc/
- http://hobbes.nmsu.edu/h-browse.php?dir=/pub/os2/dev/emx/v0.9d/
-
-The runtime component should have the name F<emxrt.zip>.
-
-B<NOTE>. When using F<emx.exe>/F<rsx.exe>, it is enough to have them on your path. One
-does not need to specify them explicitly (though this
-
- emx perl_.exe -de 0
-
-will work as well.)
-
-=item RSX
-
-To run Perl on DPMI platforms one needs RSX runtime. This is
-needed under DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see
-L<"Other OSes">). RSX would not work with VCPI
-only, as EMX would, it requires DMPI.
-
-Having RSX and the latest F<sh.exe> one gets a fully functional
-B<*nix>-ish environment under DOS, say, C<fork>, C<``> and
-pipe-C<open> work. In fact, MakeMaker works (for static build), so one
-can have Perl development environment under DOS.
-
-One can get RSX from, say
-
- http://cd.textfiles.com/hobbesos29804/disk1/EMX09C/
- ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/emx+gcc/contrib/
-
-Contact the author on C<rainer@mathematik.uni-bielefeld.de>.
-
-The latest F<sh.exe> with DOS hooks is available in
-
- http://www.ilyaz.org/software/os2/
-
-as F<sh_dos.zip> or under similar names starting with C<sh>, C<pdksh> etc.
-
-=item HPFS
-
-Perl does not care about file systems, but the perl library contains
-many files with long names, so to install it intact one needs a file
-system which supports long file names.
-
-Note that if you do not plan to build the perl itself, it may be
-possible to fool EMX to truncate file names. This is not supported,
-read EMX docs to see how to do it.
-
-=item pdksh
-
-To start external programs with complicated command lines (like with
-pipes in between, and/or quoting of arguments), Perl uses an external
-shell. With EMX port such shell should be named F<sh.exe>, and located
-either in the wired-in-during-compile locations (usually F<F:/bin>),
-or in configurable location (see L<"PERL_SH_DIR">).
-
-For best results use EMX pdksh. The standard binary (5.2.14 or later) runs
-under DOS (with L</RSX>) as well, see
-
- http://www.ilyaz.org/software/os2/
-
-=back
-
-=head2 Starting Perl programs under OS/2 (and DOS and...)
-
-Start your Perl program F<foo.pl> with arguments C<arg1 arg2 arg3> the
-same way as on any other platform, by
-
- perl foo.pl arg1 arg2 arg3
-
-If you want to specify perl options C<-my_opts> to the perl itself (as
-opposed to your program), use
-
- perl -my_opts foo.pl arg1 arg2 arg3
-
-Alternately, if you use OS/2-ish shell, like CMD or 4os2, put
-the following at the start of your perl script:
-
- extproc perl -S -my_opts
-
-rename your program to F<foo.cmd>, and start it by typing
-
- foo arg1 arg2 arg3
-
-Note that because of stupid OS/2 limitations the full path of the perl
-script is not available when you use C<extproc>, thus you are forced to
-use C<-S> perl switch, and your script should be on the C<PATH>. As a plus
-side, if you know a full path to your script, you may still start it
-with
-
- perl ../../blah/foo.cmd arg1 arg2 arg3
-
-(note that the argument C<-my_opts> is taken care of by the C<extproc> line
-in your script, see L<C<extproc> on the first line>).
-
-To understand what the above I<magic> does, read perl docs about C<-S>
-switch - see L<perlrun>, and cmdref about C<extproc>:
-
- view perl perlrun
- man perlrun
- view cmdref extproc
- help extproc
-
-or whatever method you prefer.
-
-There are also endless possibilities to use I<executable extensions> of
-4os2, I<associations> of WPS and so on... However, if you use
-*nixish shell (like F<sh.exe> supplied in the binary distribution),
-you need to follow the syntax specified in L<perlrun/"Command Switches">.
-
-Note that B<-S> switch supports scripts with additional extensions
-F<.cmd>, F<.btm>, F<.bat>, F<.pl> as well.
-
-=head2 Starting OS/2 (and DOS) programs under Perl
-
-This is what system() (see L<perlfunc/system>), C<``> (see
-L<perlop/"I/O Operators">), and I<open pipe> (see L<perlfunc/open>)
-are for. (Avoid exec() (see L<perlfunc/exec>) unless you know what you
-do).
-
-Note however that to use some of these operators you need to have a
-sh-syntax shell installed (see L<"Pdksh">,
-L<"Frequently asked questions">), and perl should be able to find it
-(see L<"PERL_SH_DIR">).
-
-The cases when the shell is used are:
-
-=over
-
-=item 1
-
-One-argument system() (see L<perlfunc/system>), exec() (see L<perlfunc/exec>)
-with redirection or shell meta-characters;
-
-=item 2
-
-Pipe-open (see L<perlfunc/open>) with the command which contains redirection
-or shell meta-characters;
-
-=item 3
-
-Backticks C<``> (see L<perlop/"I/O Operators">) with the command which contains
-redirection or shell meta-characters;
-
-=item 4
-
-If the executable called by system()/exec()/pipe-open()/C<``> is a script
-with the "magic" C<#!> line or C<extproc> line which specifies shell;
-
-=item 5
-
-If the executable called by system()/exec()/pipe-open()/C<``> is a script
-without "magic" line, and C<$ENV{EXECSHELL}> is set to shell;
-
-=item 6
-
-If the executable called by system()/exec()/pipe-open()/C<``> is not
-found (is not this remark obsolete?);
-
-=item 7
-
-For globbing (see L<perlfunc/glob>, L<perlop/"I/O Operators">)
-(obsolete? Perl uses builtin globbing nowadays...).
-
-=back
-
-For the sake of speed for a common case, in the above algorithms
-backslashes in the command name are not considered as shell metacharacters.
-
-Perl starts scripts which begin with cookies
-C<extproc> or C<#!> directly, without an intervention of shell. Perl uses the
-same algorithm to find the executable as F<pdksh>: if the path
-on C<#!> line does not work, and contains C</>, then the directory
-part of the executable is ignored, and the executable
-is searched in F<.> and on C<PATH>. To find arguments for these scripts
-Perl uses a different algorithm than F<pdksh>: up to 3 arguments are
-recognized, and trailing whitespace is stripped.
-
-If a script
-does not contain such a cooky, then to avoid calling F<sh.exe>, Perl uses
-the same algorithm as F<pdksh>: if C<$ENV{EXECSHELL}> is set, the
-script is given as the first argument to this command, if not set, then
-C<$ENV{COMSPEC} /c> is used (or a hardwired guess if C<$ENV{COMSPEC}> is
-not set).
-
-When starting scripts directly, Perl uses exactly the same algorithm as for
-the search of script given by B<-S> command-line option: it will look in
-the current directory, then on components of C<$ENV{PATH}> using the
-following order of appended extensions: no extension, F<.cmd>, F<.btm>,
-F<.bat>, F<.pl>.
-
-Note that Perl will start to look for scripts only if OS/2 cannot start the
-specified application, thus C<system 'blah'> will not look for a script if
-there is an executable file F<blah.exe> I<anywhere> on C<PATH>. In
-other words, C<PATH> is essentially searched twice: once by the OS for
-an executable, then by Perl for scripts.
-
-Note also that executable files on OS/2 can have an arbitrary extension,
-but F<.exe> will be automatically appended if no dot is present in the name.
-The workaround is as simple as that: since F<blah.> and F<blah> denote the
-same file (at list on FAT and HPFS file systems), to start an executable residing in file F<n:/bin/blah> (no
-extension) give an argument C<n:/bin/blah.> (dot appended) to system().
-
-Perl will start PM programs from VIO (=text-mode) Perl process in a
-separate PM session;
-the opposite is not true: when you start a non-PM program from a PM
-Perl process, Perl would not run it in a separate session. If a separate
-session is desired, either ensure
-that shell will be used, as in C<system 'cmd /c myprog'>, or start it using
-optional arguments to system() documented in C<OS2::Process> module. This
-is considered to be a feature.
-
-=head1 Frequently asked questions
-
-=head2 "It does not work"
-
-Perl binary distributions come with a F<testperl.cmd> script which tries
-to detect common problems with misconfigured installations. There is a
-pretty large chance it will discover which step of the installation you
-managed to goof. C<;-)>
-
-=head2 I cannot run external programs
-
-=over 4
-
-=item *
-
-Did you run your programs with C<-w> switch? See
-L<Starting OSE<sol>2 (and DOS) programs under Perl>.
-
-=item *
-
-Do you try to run I<internal> shell commands, like C<`copy a b`>
-(internal for F<cmd.exe>), or C<`glob a*b`> (internal for ksh)? You
-need to specify your shell explicitly, like C<`cmd /c copy a b`>,
-since Perl cannot deduce which commands are internal to your shell.
-
-=back
-
-=head2 I cannot embed perl into my program, or use F<perl.dll> from my
-program.
-
-=over 4
-
-=item Is your program EMX-compiled with C<-Zmt -Zcrtdll>?
-
-Well, nowadays Perl DLL should be usable from a differently compiled
-program too... If you can run Perl code from REXX scripts (see
-L<OS2::REXX>), then there are some other aspect of interaction which
-are overlooked by the current hackish code to support
-differently-compiled principal programs.
-
-If everything else fails, you need to build a stand-alone DLL for
-perl. Contact me, I did it once. Sockets would not work, as a lot of
-other stuff.
-
-=item Did you use L<ExtUtils::Embed>?
-
-Some time ago I had reports it does not work. Nowadays it is checked
-in the Perl test suite, so grep F<./t> subdirectory of the build tree
-(as well as F<*.t> files in the F<./lib> subdirectory) to find how it
-should be done "correctly".
-
-=back
-
-=head2 C<``> and pipe-C<open> do not work under DOS.
-
-This may a variant of just L<"I cannot run external programs">, or a
-deeper problem. Basically: you I<need> RSX (see L</Prerequisites>)
-for these commands to work, and you may need a port of F<sh.exe> which
-understands command arguments. One of such ports is listed in
-L</Prerequisites> under RSX. Do not forget to set variable
-C<L<"PERL_SH_DIR">> as well.
-
-DPMI is required for RSX.
-
-=head2 Cannot start C<find.exe "pattern" file>
-
-The whole idea of the "standard C API to start applications" is that
-the forms C<foo> and C<"foo"> of program arguments are completely
-interchangeable. F<find> breaks this paradigm;
-
- find "pattern" file
- find pattern file
-
-are not equivalent; F<find> cannot be started directly using the above
-API. One needs a way to surround the doublequotes in some other
-quoting construction, necessarily having an extra non-Unixish shell in
-between.
-
-Use one of
-
- system 'cmd', '/c', 'find "pattern" file';
- `cmd /c 'find "pattern" file'`
-
-This would start F<find.exe> via F<cmd.exe> via C<sh.exe> via
-C<perl.exe>, but this is a price to pay if you want to use
-non-conforming program.
-
-=head1 INSTALLATION
-
-=head2 Automatic binary installation
-
-The most convenient way of installing a binary distribution of perl is via perl installer
-F<install.exe>. Just follow the instructions, and 99% of the
-installation blues would go away.
-
-Note however, that you need to have F<unzip.exe> on your path, and
-EMX environment I<running>. The latter means that if you just
-installed EMX, and made all the needed changes to F<Config.sys>,
-you may need to reboot in between. Check EMX runtime by running
-
- emxrev
-
-Binary installer also creates a folder on your desktop with some useful
-objects. If you need to change some aspects of the work of the binary
-installer, feel free to edit the file F<Perl.pkg>. This may be useful
-e.g., if you need to run the installer many times and do not want to
-make many interactive changes in the GUI.
-
-B<Things not taken care of by automatic binary installation:>
-
-=over 15
-
-=item C<PERL_BADLANG>
-
-may be needed if you change your codepage I<after> perl installation,
-and the new value is not supported by EMX. See L<"PERL_BADLANG">.
-
-=item C<PERL_BADFREE>
-
-see L<"PERL_BADFREE">.
-
-=item F<Config.pm>
-
-This file resides somewhere deep in the location you installed your
-perl library, find it out by
-
- perl -MConfig -le "print $INC{'Config.pm'}"
-
-While most important values in this file I<are> updated by the binary
-installer, some of them may need to be hand-edited. I know no such
-data, please keep me informed if you find one. Moreover, manual
-changes to the installed version may need to be accompanied by an edit
-of this file.
-
-=back
-
-B<NOTE>. Because of a typo the binary installer of 5.00305
-would install a variable C<PERL_SHPATH> into F<Config.sys>. Please
-remove this variable and put C<L</PERL_SH_DIR>> instead.
-
-=head2 Manual binary installation
-
-As of version 5.00305, OS/2 perl binary distribution comes split
-into 11 components. Unfortunately, to enable configurable binary
-installation, the file paths in the zip files are not absolute, but
-relative to some directory.
-
-Note that the extraction with the stored paths is still necessary
-(default with unzip, specify C<-d> to pkunzip). However, you
-need to know where to extract the files. You need also to manually
-change entries in F<Config.sys> to reflect where did you put the
-files. Note that if you have some primitive unzipper (like
-C<pkunzip>), you may get a lot of warnings/errors during
-unzipping. Upgrade to C<(w)unzip>.
-
-Below is the sample of what to do to reproduce the configuration on my
-machine. In F<VIEW.EXE> you can press C<Ctrl-Insert> now, and
-cut-and-paste from the resulting file - created in the directory you
-started F<VIEW.EXE> from.
-
-For each component, we mention environment variables related to each
-installation directory. Either choose directories to match your
-values of the variables, or create/append-to variables to take into
-account the directories.
-
-=over 3
-
-=item Perl VIO and PM executables (dynamically linked)
-
- unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin
- unzip perl_exc.zip *.dll -d f:/emx.add/dll
-
-(have the directories with C<*.exe> on PATH, and C<*.dll> on
-LIBPATH);
-
-=item Perl_ VIO executable (statically linked)
-
- unzip perl_aou.zip -d f:/emx.add/bin
-
-(have the directory on PATH);
-
-=item Executables for Perl utilities
-
- unzip perl_utl.zip -d f:/emx.add/bin
-
-(have the directory on PATH);
-
-=item Main Perl library
-
- unzip perl_mlb.zip -d f:/perllib/lib
-
-If this directory is exactly the same as the prefix which was compiled
-into F<perl.exe>, you do not need to change
-anything. However, for perl to find the library if you use a different
-path, you need to
-C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
-
-=item Additional Perl modules
-
- unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.16.2/
-
-Same remark as above applies. Additionally, if this directory is not
-one of directories on @INC (and @INC is influenced by C<PERLLIB_PREFIX>), you
-need to put this
-directory and subdirectory F<./os2> in C<PERLLIB> or C<PERL5LIB>
-variable. Do not use C<PERL5LIB> unless you have it set already. See
-L<perl/"ENVIRONMENT">.
-
-B<[Check whether this extraction directory is still applicable with
-the new directory structure layout!]>
-
-=item Tools to compile Perl modules
-
- unzip perl_blb.zip -d f:/perllib/lib
-
-Same remark as for F<perl_ste.zip>.
-
-=item Manpages for Perl and utilities
-
- unzip perl_man.zip -d f:/perllib/man
-
-This directory should better be on C<MANPATH>. You need to have a
-working F<man> to access these files.
-
-=item Manpages for Perl modules
-
- unzip perl_mam.zip -d f:/perllib/man
-
-This directory should better be on C<MANPATH>. You need to have a
-working man to access these files.
-
-=item Source for Perl documentation
-
- unzip perl_pod.zip -d f:/perllib/lib
-
-This is used by the C<perldoc> program (see L<perldoc>), and may be used to
-generate HTML documentation usable by WWW browsers, and
-documentation in zillions of other formats: C<info>, C<LaTeX>,
-C<Acrobat>, C<FrameMaker> and so on. [Use programs such as
-F<pod2latex> etc.]
-
-=item Perl manual in F<.INF> format
-
- unzip perl_inf.zip -d d:/os2/book
-
-This directory should better be on C<BOOKSHELF>.
-
-=item Pdksh
-
- unzip perl_sh.zip -d f:/bin
-
-This is used by perl to run external commands which explicitly
-require shell, like the commands using I<redirection> and I<shell
-metacharacters>. It is also used instead of explicit F</bin/sh>.
-
-Set C<PERL_SH_DIR> (see L<"PERL_SH_DIR">) if you move F<sh.exe> from
-the above location.
-
-B<Note.> It may be possible to use some other sh-compatible shell (untested).
-
-=back
-
-After you installed the components you needed and updated the
-F<Config.sys> correspondingly, you need to hand-edit
-F<Config.pm>. This file resides somewhere deep in the location you
-installed your perl library, find it out by
-
- perl -MConfig -le "print $INC{'Config.pm'}"
-
-You need to correct all the entries which look like file paths (they
-currently start with C<f:/>).
-
-=head2 B<Warning>
-
-The automatic and manual perl installation leave precompiled paths
-inside perl executables. While these paths are overwriteable (see
-L<"PERLLIB_PREFIX">, L<"PERL_SH_DIR">), some people may prefer
-binary editing of paths inside the executables/DLLs.
-
-=head1 Accessing documentation
-
-Depending on how you built/installed perl you may have (otherwise
-identical) Perl documentation in the following formats:
-
-=head2 OS/2 F<.INF> file
-
-Most probably the most convenient form. Under OS/2 view it as
-
- view perl
- view perl perlfunc
- view perl less
- view perl ExtUtils::MakeMaker
-
-(currently the last two may hit a wrong location, but this may improve
-soon). Under Win* see L<"SYNOPSIS">.
-
-If you want to build the docs yourself, and have I<OS/2 toolkit>, run
-
- pod2ipf > perl.ipf
-
-in F</perllib/lib/pod> directory, then
-
- ipfc /inf perl.ipf
-
-(Expect a lot of errors during the both steps.) Now move it on your
-BOOKSHELF path.
-
-=head2 Plain text
-
-If you have perl documentation in the source form, perl utilities
-installed, and GNU groff installed, you may use
-
- perldoc perlfunc
- perldoc less
- perldoc ExtUtils::MakeMaker
-
-to access the perl documentation in the text form (note that you may get
-better results using perl manpages).
-
-Alternately, try running pod2text on F<.pod> files.
-
-=head2 Manpages
-
-If you have F<man> installed on your system, and you installed perl
-manpages, use something like this:
-
- man perlfunc
- man 3 less
- man ExtUtils.MakeMaker
-
-to access documentation for different components of Perl. Start with
-
- man perl
-
-Note that dot (F<.>) is used as a package separator for documentation
-for packages, and as usual, sometimes you need to give the section - C<3>
-above - to avoid shadowing by the I<less(1) manpage>.
-
-Make sure that the directory B<above> the directory with manpages is
-on our C<MANPATH>, like this
-
- set MANPATH=c:/man;f:/perllib/man
-
-for Perl manpages in C<f:/perllib/man/man1/> etc.
-
-=head2 HTML
-
-If you have some WWW browser available, installed the Perl
-documentation in the source form, and Perl utilities, you can build
-HTML docs. Cd to directory with F<.pod> files, and do like this
-
- cd f:/perllib/lib/pod
- pod2html
-
-After this you can direct your browser the file F<perl.html> in this
-directory, and go ahead with reading docs, like this:
-
- explore file:///f:/perllib/lib/pod/perl.html
-
-Alternatively you may be able to get these docs prebuilt from CPAN.
-
-=head2 GNU C<info> files
-
-Users of Emacs would appreciate it very much, especially with
-C<CPerl> mode loaded. You need to get latest C<pod2texi> from C<CPAN>,
-or, alternately, the prebuilt info pages.
-
-=head2 F<PDF> files
-
-for C<Acrobat> are available on CPAN (may be for slightly older version of
-perl).
-
-=head2 C<LaTeX> docs
-
-can be constructed using C<pod2latex>.
-
-=head1 BUILD
-
-Here we discuss how to build Perl under OS/2.
-
-=head2 The short story
-
-Assume that you are a seasoned porter, so are sure that all the necessary
-tools are already present on your system, and you know how to get the Perl
-source distribution. Untar it, change to the extract directory, and
-
- gnupatch -p0 < os2\diff.configure
- sh Configure -des -D prefix=f:/perllib
- make
- make test
- make install
- make aout_test
- make aout_install
-
-This puts the executables in f:/perllib/bin. Manually move them to the
-C<PATH>, manually move the built F<perl*.dll> to C<LIBPATH> (here for
-Perl DLL F<*> is a not-very-meaningful hex checksum), and run
-
- make installcmd INSTALLCMDDIR=d:/ir/on/path
-
-Assuming that the C<man>-files were put on an appropriate location,
-this completes the installation of minimal Perl system. (The binary
-distribution contains also a lot of additional modules, and the
-documentation in INF format.)
-
-What follows is a detailed guide through these steps.
-
-=head2 Prerequisites
-
-You need to have the latest EMX development environment, the full
-GNU tool suite (gawk renamed to awk, and GNU F<find.exe>
-earlier on path than the OS/2 F<find.exe>, same with F<sort.exe>, to
-check use
-
- find --version
- sort --version
-
-). You need the latest version of F<pdksh> installed as F<sh.exe>.
-
-Check that you have B<BSD> libraries and headers installed, and -
-optionally - Berkeley DB headers and libraries, and crypt.
-
-Possible locations to get the files:
-
-
- ftp://ftp.uni-heidelberg.de/pub/os2/unix/
- http://hobbes.nmsu.edu/h-browse.php?dir=/pub/os2
- http://cd.textfiles.com/hobbesos29804/disk1/DEV32/
- http://cd.textfiles.com/hobbesos29804/disk1/EMX09C/
-
-It is reported that the following archives contain enough utils to
-build perl: F<gnufutil.zip>, F<gnusutil.zip>, F<gnututil.zip>, F<gnused.zip>,
-F<gnupatch.zip>, F<gnuawk.zip>, F<gnumake.zip>, F<gnugrep.zip>, F<bsddev.zip> and
-F<ksh527rt.zip> (or a later version). Note that all these utilities are
-known to be available from LEO:
-
- ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/
-
-Note also that the F<db.lib> and F<db.a> from the EMX distribution
-are not suitable for multi-threaded compile (even single-threaded
-flavor of Perl uses multi-threaded C RTL, for
-compatibility with XFree86-OS/2). Get a corrected one from
-
- http://www.ilyaz.org/software/os2/db_mt.zip
-
-If you have I<exactly the same version of Perl> installed already,
-make sure that no copies or perl are currently running. Later steps
-of the build may fail since an older version of F<perl.dll> loaded into
-memory may be found. Running C<make test> becomes meaningless, since
-the test are checking a previous build of perl (this situation is detected
-and reported by F<lib/os2_base.t> test). Do not forget to unset
-C<PERL_EMXLOAD_SEC> in environment.
-
-Also make sure that you have F</tmp> directory on the current drive,
-and F<.> directory in your C<LIBPATH>. One may try to correct the
-latter condition by
-
- set BEGINLIBPATH .\.
-
-if you use something like F<CMD.EXE> or latest versions of
-F<4os2.exe>. (Setting BEGINLIBPATH to just C<.> is ignored by the
-OS/2 kernel.)
-
-Make sure your gcc is good for C<-Zomf> linking: run C<omflibs>
-script in F</emx/lib> directory.
-
-Check that you have link386 installed. It comes standard with OS/2,
-but may be not installed due to customization. If typing
-
- link386
-
-shows you do not have it, do I<Selective install>, and choose C<Link
-object modules> in I<Optional system utilities/More>. If you get into
-link386 prompts, press C<Ctrl-C> to exit.
-
-=head2 Getting perl source
-
-You need to fetch the latest perl source (including developers
-releases). With some probability it is located in
-
- http://www.cpan.org/src/
- http://www.cpan.org/src/unsupported
-
-If not, you may need to dig in the indices to find it in the directory
-of the current maintainer.
-
-Quick cycle of developers release may break the OS/2 build time to
-time, looking into
-
- http://www.cpan.org/ports/os2/
-
-may indicate the latest release which was publicly released by the
-maintainer. Note that the release may include some additional patches
-to apply to the current source of perl.
-
-Extract it like this
-
- tar vzxf perl5.00409.tar.gz
-
-You may see a message about errors while extracting F<Configure>. This is
-because there is a conflict with a similarly-named file F<configure>.
-
-Change to the directory of extraction.
-
-=head2 Application of the patches
-
-You need to apply the patches in F<./os2/diff.*> like this:
-
- gnupatch -p0 < os2\diff.configure
-
-You may also need to apply the patches supplied with the binary
-distribution of perl. It also makes sense to look on the
-perl5-porters mailing list for the latest OS/2-related patches (see
-L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>). Such
-patches usually contain strings C</os2/> and C<patch>, so it makes
-sense looking for these strings.
-
-=head2 Hand-editing
-
-You may look into the file F<./hints/os2.sh> and correct anything
-wrong you find there. I do not expect it is needed anywhere.
-
-=head2 Making
-
- sh Configure -des -D prefix=f:/perllib
-
-C<prefix> means: where to install the resulting perl library. Giving
-correct prefix you may avoid the need to specify C<PERLLIB_PREFIX>,
-see L<"PERLLIB_PREFIX">.
-
-I<Ignore the message about missing C<ln>, and about C<-c> option to
-tr>. The latter is most probably already fixed, if you see it and can trace
-where the latter spurious warning comes from, please inform me.
-
-Now
-
- make
-
-At some moment the built may die, reporting a I<version mismatch> or
-I<unable to run F<perl>>. This means that you do not have F<.> in
-your LIBPATH, so F<perl.exe> cannot find the needed F<perl67B2.dll> (treat
-these hex digits as line noise). After this is fixed the build
-should finish without a lot of fuss.
-
-=head2 Testing
-
-Now run
-
- make test
-
-All tests should succeed (with some of them skipped). If you have the
-same version of Perl installed, it is crucial that you have C<.> early
-in your LIBPATH (or in BEGINLIBPATH), otherwise your tests will most
-probably test the wrong version of Perl.
-
-Some tests may generate extra messages similar to
-
-=over 4
-
-=item A lot of C<bad free>
-
-in database tests related to Berkeley DB. I<This should be fixed already.>
-If it persists, you may disable this warnings, see L<"PERL_BADFREE">.
-
-=item Process terminated by SIGTERM/SIGINT
-
-This is a standard message issued by OS/2 applications. *nix
-applications die in silence. It is considered to be a feature. One can
-easily disable this by appropriate sighandlers.
-
-However the test engine bleeds these message to screen in unexpected
-moments. Two messages of this kind I<should> be present during
-testing.
-
-=back
-
-To get finer test reports, call
-
- perl t/harness
-
-The report with F<io/pipe.t> failing may look like this:
-
- Failed Test Status Wstat Total Fail Failed List of failed
- ------------------------------------------------------------
- io/pipe.t 12 1 8.33% 9
- 7 tests skipped, plus 56 subtests skipped.
- Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed, 99.98% okay.
-
-The reasons for most important skipped tests are:
-
-=over 8
-
-=item F<op/fs.t>
-
-=over 4
-
-=item 18
-
-Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS
-provides only 2sec time granularity (for compatibility with FAT?).
-
-=item 25
-
-Checks C<truncate()> on a filehandle just opened for write - I do not
-know why this should or should not work.
-
-=back
-
-=item F<op/stat.t>
-
-Checks C<stat()>. Tests:
-
-=over 4
-
-=item 4
-
-Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS
-provides only 2sec time granularity (for compatibility with FAT?).
-
-=back
-
-=back
-
-=head2 Installing the built perl
-
-If you haven't yet moved C<perl*.dll> onto LIBPATH, do it now.
-
-Run
-
- make install
-
-It would put the generated files into needed locations. Manually put
-F<perl.exe>, F<perl__.exe> and F<perl___.exe> to a location on your
-PATH, F<perl.dll> to a location on your LIBPATH.
-
-Run
-
- make installcmd INSTALLCMDDIR=d:/ir/on/path
-
-to convert perl utilities to F<.cmd> files and put them on
-PATH. You need to put F<.EXE>-utilities on path manually. They are
-installed in C<$prefix/bin>, here C<$prefix> is what you gave to
-F<Configure>, see L</Making>.
-
-If you use C<man>, either move the installed F<*/man/> directories to
-your C<MANPATH>, or modify C<MANPATH> to match the location. (One
-could have avoided this by providing a correct C<manpath> option to
-F<./Configure>, or editing F<./config.sh> between configuring and
-making steps.)
-
-=head2 C<a.out>-style build
-
-Proceed as above, but make F<perl_.exe> (see L<"perl_.exe">) by
-
- make perl_
-
-test and install by
-
- make aout_test
- make aout_install
-
-Manually put F<perl_.exe> to a location on your PATH.
-
-B<Note.> The build process for C<perl_> I<does not know> about all the
-dependencies, so you should make sure that anything is up-to-date,
-say, by doing
-
- make perl_dll
-
-first.
-
-=head1 Building a binary distribution
-
-[This section provides a short overview only...]
-
-Building should proceed differently depending on whether the version of perl
-you install is already present and used on your system, or is a new version
-not yet used. The description below assumes that the version is new, so
-installing its DLLs and F<.pm> files will not disrupt the operation of your
-system even if some intermediate steps are not yet fully working.
-
-The other cases require a little bit more convoluted procedures. Below I
-suppose that the current version of Perl is C<5.8.2>, so the executables are
-named accordingly.
-
-=over
-
-=item 1.
-
-Fully build and test the Perl distribution. Make sure that no tests are
-failing with C<test> and C<aout_test> targets; fix the bugs in Perl and
-the Perl test suite detected by these tests. Make sure that C<all_test>
-make target runs as clean as possible. Check that F<os2/perlrexx.cmd>
-runs fine.
-
-=item 2.
-
-Fully install Perl, including C<installcmd> target. Copy the generated DLLs
-to C<LIBPATH>; copy the numbered Perl executables (as in F<perl5.8.2.exe>)
-to C<PATH>; copy C<perl_.exe> to C<PATH> as C<perl_5.8.2.exe>. Think whether
-you need backward-compatibility DLLs. In most cases you do not need to install
-them yet; but sometime this may simplify the following steps.
-
-=item 3.
-
-Make sure that C<CPAN.pm> can download files from CPAN. If not, you may need
-to manually install C<Net::FTP>.
-
-=item 4.
-
-Install the bundle C<Bundle::OS2_default>
-
- perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_1
-
-This may take a couple of hours on 1GHz processor (when run the first time).
-And this should not be necessarily a smooth procedure. Some modules may not
-specify required dependencies, so one may need to repeat this procedure several
-times until the results stabilize.
-
- perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_2
- perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_3
-
-Even after they stabilize, some tests may fail.
-
-Fix as many discovered bugs as possible. Document all the bugs which are not
-fixed, and all the failures with unknown reasons. Inspect the produced logs
-F<00cpan_i_1> to find suspiciously skipped tests, and other fishy events.
-
-Keep in mind that I<installation> of some modules may fail too: for example,
-the DLLs to update may be already loaded by F<CPAN.pm>. Inspect the C<install>
-logs (in the example above F<00cpan_i_1> etc) for errors, and install things
-manually, as in
-
- cd $CPANHOME/.cpan/build/Digest-MD5-2.31
- make install
-
-Some distributions may fail some tests, but you may want to install them
-anyway (as above, or via C<force install> command of C<CPAN.pm> shell-mode).
-
-Since this procedure may take quite a long time to complete, it makes sense
-to "freeze" your CPAN configuration by disabling periodic updates of the
-local copy of CPAN index: set C<index_expire> to some big value (I use 365),
-then save the settings
-
- CPAN> o conf index_expire 365
- CPAN> o conf commit
-
-Reset back to the default value C<1> when you are finished.
-
-=item 5.
-
-When satisfied with the results, rerun the C<installcmd> target. Now you
-can copy C<perl5.8.2.exe> to C<perl.exe>, and install the other OMF-build
-executables: C<perl__.exe> etc. They are ready to be used.
-
-=item 6.
-
-Change to the C<./pod> directory of the build tree, download the Perl logo
-F<CamelGrayBig.BMP>, and run
-
- ( perl2ipf > perl.ipf ) |& tee 00ipf
- ipfc /INF perl.ipf |& tee 00inf
-
-This produces the Perl docs online book C<perl.INF>. Install in on
-C<BOOKSHELF> path.
-
-=item 7.
-
-Now is the time to build statically linked executable F<perl_.exe> which
-includes newly-installed via C<Bundle::OS2_default> modules. Doing testing
-via C<CPAN.pm> is going to be painfully slow, since it statically links
-a new executable per XS extension.
-
-Here is a possible workaround: create a toplevel F<Makefile.PL> in
-F<$CPANHOME/.cpan/build/> with contents being (compare with L<Making
-executables with a custom collection of statically loaded extensions>)
-
- use ExtUtils::MakeMaker;
- WriteMakefile NAME => 'dummy';
-
-execute this as
-
- perl_5.8.2.exe Makefile.PL <nul |& tee 00aout_c1
- make -k all test <nul |& 00aout_t1
-
-Again, this procedure should not be absolutely smooth. Some C<Makefile.PL>'s
-in subdirectories may be buggy, and would not run as "child" scripts. The
-interdependency of modules can strike you; however, since non-XS modules
-are already installed, the prerequisites of most modules have a very good
-chance to be present.
-
-If you discover some glitches, move directories of problematic modules to a
-different location; if these modules are non-XS modules, you may just ignore
-them - they are already installed; the remaining, XS, modules you need to
-install manually one by one.
-
-After each such removal you need to rerun the C<Makefile.PL>/C<make> process;
-usually this procedure converges soon. (But be sure to convert all the
-necessary external C libraries from F<.lib> format to F<.a> format: run one of
-
- emxaout foo.lib
- emximp -o foo.a foo.lib
-
-whichever is appropriate.) Also, make sure that the DLLs for external
-libraries are usable with with executables compiled without C<-Zmtd> options.
-
-When you are sure that only a few subdirectories
-lead to failures, you may want to add C<-j4> option to C<make> to speed up
-skipping subdirectories with already finished build.
-
-When you are satisfied with the results of tests, install the build C libraries
-for extensions:
-
- make install |& tee 00aout_i
-
-Now you can rename the file F<./perl.exe> generated during the last phase
-to F<perl_5.8.2.exe>; place it on C<PATH>; if there is an inter-dependency
-between some XS modules, you may need to repeat the C<test>/C<install> loop
-with this new executable and some excluded modules - until the procedure
-converges.
-
-Now you have all the necessary F<.a> libraries for these Perl modules in the
-places where Perl builder can find it. Use the perl builder: change to an
-empty directory, create a "dummy" F<Makefile.PL> again, and run
-
- perl_5.8.2.exe Makefile.PL |& tee 00c
- make perl |& tee 00p
-
-This should create an executable F<./perl.exe> with all the statically loaded
-extensions built in. Compare the generated F<perlmain.c> files to make sure
-that during the iterations the number of loaded extensions only increases.
-Rename F<./perl.exe> to F<perl_5.8.2.exe> on C<PATH>.
-
-When it converges, you got a functional variant of F<perl_5.8.2.exe>; copy it
-to C<perl_.exe>. You are done with generation of the local Perl installation.
-
-=item 8.
-
-Make sure that the installed modules are actually installed in the location
-of the new Perl, and are not inherited from entries of @INC given for
-inheritance from the older versions of Perl: set C<PERLLIB_582_PREFIX> to
-redirect the new version of Perl to a new location, and copy the installed
-files to this new location. Redo the tests to make sure that the versions of
-modules inherited from older versions of Perl are not needed.
-
-Actually, the log output of L<pod2ipf(1)> during the step 6 gives a very detailed
-info about which modules are loaded from which place; so you may use it as
-an additional verification tool.
-
-Check that some temporary files did not make into the perl install tree.
-Run something like this
-
- pfind . -f "!(/\.(pm|pl|ix|al|h|a|lib|txt|pod|imp|bs|dll|ld|bs|inc|xbm|yml|cgi|uu|e2x|skip|packlist|eg|cfg|html|pub|enc|all|ini|po|pot)$/i or /^\w+$/") | less
-
-in the install tree (both top one and F<sitelib> one).
-
-Compress all the DLLs with F<lxlite>. The tiny F<.exe> can be compressed with
-C</c:max> (the bug only appears when there is a fixup in the last 6 bytes of a
-page (?); since the tiny executables are much smaller than a page, the bug
-will not hit). Do not compress C<perl_.exe> - it would not work under DOS.
-
-=item 9.
-
-Now you can generate the binary distribution. This is done by running the
-test of the CPAN distribution C<OS2::SoftInstaller>. Tune up the file
-F<test.pl> to suit the layout of current version of Perl first. Do not
-forget to pack the necessary external DLLs accordingly. Include the
-description of the bugs and test suite failures you could not fix. Include
-the small-stack versions of Perl executables from Perl build directory.
-
-Include F<perl5.def> so that people can relink the perl DLL preserving
-the binary compatibility, or can create compatibility DLLs. Include the diff
-files (C<diff -pu old new>) of fixes you did so that people can rebuild your
-version. Include F<perl5.map> so that one can use remote debugging.
-
-=item 10.
-
-Share what you did with the other people. Relax. Enjoy fruits of your work.
-
-=item 11.
-
-Brace yourself for thanks, bug reports, hate mail and spam coming as result
-of the previous step. No good deed should remain unpunished!
-
-=back
-
-=head1 Building custom F<.EXE> files
-
-The Perl executables can be easily rebuilt at any moment. Moreover, one can
-use the I<embedding> interface (see L<perlembed>) to make very customized
-executables.
-
-=head2 Making executables with a custom collection of statically loaded extensions
-
-It is a little bit easier to do so while I<decreasing> the list of statically
-loaded extensions. We discuss this case only here.
-
-=over
-
-=item 1.
-
-Change to an empty directory, and create a placeholder <Makefile.PL>:
-
- use ExtUtils::MakeMaker;
- WriteMakefile NAME => 'dummy';
-
-=item 2.
-
-Run it with the flavor of Perl (F<perl.exe> or F<perl_.exe>) you want to
-rebuild.
-
- perl_ Makefile.PL
-
-=item 3.
-
-Ask it to create new Perl executable:
-
- make perl
-
-(you may need to manually add C<PERLTYPE=-DPERL_CORE> to this commandline on
-some versions of Perl; the symptom is that the command-line globbing does not
-work from OS/2 shells with the newly-compiled executable; check with
-
- .\perl.exe -wle "print for @ARGV" *
-
-).
-
-=item 4.
-
-The previous step created F<perlmain.c> which contains a list of newXS() calls
-near the end. Removing unnecessary calls, and rerunning
-
- make perl
-
-will produce a customized executable.
-
-=back
-
-=head2 Making executables with a custom search-paths
-
-The default perl executable is flexible enough to support most usages.
-However, one may want something yet more flexible; for example, one may want
-to find Perl DLL relatively to the location of the EXE file; or one may want
-to ignore the environment when setting the Perl-library search patch, etc.
-
-If you fill comfortable with I<embedding> interface (see L<perlembed>), such
-things are easy to do repeating the steps outlined in L<Making
-executables with a custom collection of statically loaded extensions>, and
-doing more comprehensive edits to main() of F<perlmain.c>. The people with
-little desire to understand Perl can just rename main(), and do necessary
-modification in a custom main() which calls the renamed function in appropriate
-time.
-
-However, there is a third way: perl DLL exports the main() function and several
-callbacks to customize the search path. Below is a complete example of a
-"Perl loader" which
-
-=over
-
-=item 1.
-
-Looks for Perl DLL in the directory C<$exedir/../dll>;
-
-=item 2.
-
-Prepends the above directory to C<BEGINLIBPATH>;
-
-=item 3.
-
-Fails if the Perl DLL found via C<BEGINLIBPATH> is different from what was
-loaded on step 1; e.g., another process could have loaded it from C<LIBPATH>
-or from a different value of C<BEGINLIBPATH>. In these cases one needs to
-modify the setting of the system so that this other process either does not
-run, or loads the DLL from C<BEGINLIBPATH> with C<LIBPATHSTRICT=T> (available
-with kernels after September 2000).
-
-=item 4.
-
-Loads Perl library from C<$exedir/../dll/lib/>.
-
-=item 5.
-
-Uses Bourne shell from C<$exedir/../dll/sh/ksh.exe>.
-
-=back
-
-For best results compile the C file below with the same options as the Perl
-DLL. However, a lot of functionality will work even if the executable is not
-an EMX applications, e.g., if compiled with
-
- gcc -Wall -DDOSISH -DOS2=1 -O2 -s -Zomf -Zsys perl-starter.c -DPERL_DLL_BASENAME=\"perl312F\" -Zstack 8192 -Zlinker /PM:VIO
-
-Here is the sample C file:
-
- #define INCL_DOS
- #define INCL_NOPM
- /* These are needed for compile if os2.h includes os2tk.h, not os2emx.h */
- #define INCL_DOSPROCESS
- #include <os2.h>
-
- #include "EXTERN.h"
- #define PERL_IN_MINIPERLMAIN_C
- #include "perl.h"
-
- static char *me;
- HMODULE handle;
-
- static void
- die_with(char *msg1, char *msg2, char *msg3, char *msg4)
- {
- ULONG c;
- char *s = " error: ";
-
- DosWrite(2, me, strlen(me), &c);
- DosWrite(2, s, strlen(s), &c);
- DosWrite(2, msg1, strlen(msg1), &c);
- DosWrite(2, msg2, strlen(msg2), &c);
- DosWrite(2, msg3, strlen(msg3), &c);
- DosWrite(2, msg4, strlen(msg4), &c);
- DosWrite(2, "\r\n", 2, &c);
- exit(255);
- }
-
- typedef ULONG (*fill_extLibpath_t)(int type, char *pre, char *post, int replace, char *msg);
- typedef int (*main_t)(int type, char *argv[], char *env[]);
- typedef int (*handler_t)(void* data, int which);
-
- #ifndef PERL_DLL_BASENAME
- # define PERL_DLL_BASENAME "perl"
- #endif
-
- static HMODULE
- load_perl_dll(char *basename)
- {
- char buf[300], fail[260];
- STRLEN l, dirl;
- fill_extLibpath_t f;
- ULONG rc_fullname;
- HMODULE handle, handle1;
-
- if (_execname(buf, sizeof(buf) - 13) != 0)
- die_with("Can't find full path: ", strerror(errno), "", "");
- /* XXXX Fill 'me' with new value */
- l = strlen(buf);
- while (l && buf[l-1] != '/' && buf[l-1] != '\\')
- l--;
- dirl = l - 1;
- strcpy(buf + l, basename);
- l += strlen(basename);
- strcpy(buf + l, ".dll");
- if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle)) != 0
- && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 )
- die_with("Can't load DLL ", buf, "", "");
- if (rc_fullname)
- return handle; /* was loaded with short name; all is fine */
- if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f))
- die_with(buf, ": DLL exports no symbol ", "fill_extLibpath", "");
- buf[dirl] = 0;
- if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */,
- 0 /* keep old value */, me))
- die_with(me, ": prepending BEGINLIBPATH", "", "");
- if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0)
- die_with(me, ": finding perl DLL again via BEGINLIBPATH", "", "");
- buf[dirl] = '\\';
- if (handle1 != handle) {
- if (DosQueryModuleName(handle1, sizeof(fail), fail))
- strcpy(fail, "???");
- die_with(buf, ":\n\tperl DLL via BEGINLIBPATH is different: \n\t",
- fail,
- "\n\tYou may need to manipulate global BEGINLIBPATH and LIBPATHSTRICT"
- "\n\tso that the other copy is loaded via BEGINLIBPATH.");
- }
- return handle;
- }
-
- int
- main(int argc, char **argv, char **env)
- {
- main_t f;
- handler_t h;
-
- me = argv[0];
- /**/
- handle = load_perl_dll(PERL_DLL_BASENAME);
-
- if (DosQueryProcAddr(handle, 0, "Perl_OS2_handler_install", (PFN*)&h))
- die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "Perl_OS2_handler_install", "");
- if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from)
- || !h((void *)"~dll", Perlos2_handler_perllib_to)
- || !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) )
- die_with(PERL_DLL_BASENAME, ": Can't install @INC manglers", "", "");
-
- if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f))
- die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "dll_perlmain", "");
- return f(argc, argv, env);
- }
-
-
-=head1 Build FAQ
-
-=head2 Some C</> became C<\> in pdksh.
-
-You have a very old pdksh. See L</Prerequisites>.
-
-=head2 C<'errno'> - unresolved external
-
-You do not have MT-safe F<db.lib>. See L</Prerequisites>.
-
-=head2 Problems with tr or sed
-
-reported with very old version of tr and sed.
-
-=head2 Some problem (forget which ;-)
-
-You have an older version of F<perl.dll> on your LIBPATH, which
-broke the build of extensions.
-
-=head2 Library ... not found
-
-You did not run C<omflibs>. See L</Prerequisites>.
-
-=head2 Segfault in make
-
-You use an old version of GNU make. See L</Prerequisites>.
-
-=head2 op/sprintf test failure
-
-This can result from a bug in emx sprintf which was fixed in 0.9d fix 03.
-
-=head1 Specific (mis)features of OS/2 port
-
-=head2 C<setpriority>, C<getpriority>
-
-Note that these functions are compatible with *nix, not with the older
-ports of '94 - 95. The priorities are absolute, go from 32 to -95,
-lower is quicker. 0 is the default priority.
-
-B<WARNING>. Calling C<getpriority> on a non-existing process could lock
-the system before Warp3 fixpak22. Starting with Warp3, Perl will use
-a workaround: it aborts getpriority() if the process is not present.
-This is not possible on older versions C<2.*>, and has a race
-condition anyway.
-
-=head2 C<system()>
-
-Multi-argument form of C<system()> allows an additional numeric
-argument. The meaning of this argument is described in
-L<OS2::Process>.
-
-When finding a program to run, Perl first asks the OS to look for executables
-on C<PATH> (OS/2 adds extension F<.exe> if no extension is present).
-If not found, it looks for a script with possible extensions
-added in this order: no extension, F<.cmd>, F<.btm>,
-F<.bat>, F<.pl>. If found, Perl checks the start of the file for magic
-strings C<"#!"> and C<"extproc ">. If found, Perl uses the rest of the
-first line as the beginning of the command line to run this script. The
-only mangling done to the first line is extraction of arguments (currently
-up to 3), and ignoring of the path-part of the "interpreter" name if it can't
-be found using the full path.
-
-E.g., C<system 'foo', 'bar', 'baz'> may lead Perl to finding
-F<C:/emx/bin/foo.cmd> with the first line being
-
- extproc /bin/bash -x -c
-
-If F</bin/bash.exe> is not found, then Perl looks for an executable F<bash.exe> on
-C<PATH>. If found in F<C:/emx.add/bin/bash.exe>, then the above system() is
-translated to
-
- system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz)
-
-One additional translation is performed: instead of F</bin/sh> Perl uses
-the hardwired-or-customized shell (see C<L<"PERL_SH_DIR">>).
-
-The above search for "interpreter" is recursive: if F<bash> executable is not
-found, but F<bash.btm> is found, Perl will investigate its first line etc.
-The only hardwired limit on the recursion depth is implicit: there is a limit
-4 on the number of additional arguments inserted before the actual arguments
-given to system(). In particular, if no additional arguments are specified
-on the "magic" first lines, then the limit on the depth is 4.
-
-If Perl finds that the found executable is of PM type when the
-current session is not, it will start the new process in a separate session of
-necessary type. Call via C<OS2::Process> to disable this magic.
-
-B<WARNING>. Due to the described logic, you need to explicitly
-specify F<.com> extension if needed. Moreover, if the executable
-F<perl5.6.1> is requested, Perl will not look for F<perl5.6.1.exe>.
-[This may change in the future.]
-
-=head2 C<extproc> on the first line
-
-If the first chars of a Perl script are C<"extproc ">, this line is treated
-as C<#!>-line, thus all the switches on this line are processed (twice
-if script was started via cmd.exe). See L<perlrun/DESCRIPTION>.
-
-=head2 Additional modules:
-
-L<OS2::Process>, L<OS2::DLL>, L<OS2::REXX>, L<OS2::PrfDB>, L<OS2::ExtAttr>. These
-modules provide access to additional numeric argument for C<system>
-and to the information about the running process,
-to DLLs having functions with REXX signature and to the REXX runtime, to
-OS/2 databases in the F<.INI> format, and to Extended Attributes.
-
-Two additional extensions by Andreas Kaiser, C<OS2::UPM>, and
-C<OS2::FTP>, are included into C<ILYAZ> directory, mirrored on CPAN.
-Other OS/2-related extensions are available too.
-
-=head2 Prebuilt methods:
-
-=over 4
-
-=item C<File::Copy::syscopy>
-
-used by C<File::Copy::copy>, see L<File::Copy>.
-
-=item C<DynaLoader::mod2fname>
-
-used by C<DynaLoader> for DLL name mangling.
-
-=item C<Cwd::current_drive()>
-
-Self explanatory.
-
-=item C<Cwd::sys_chdir(name)>
-
-leaves drive as it is.
-
-=item C<Cwd::change_drive(name)>
-
-changes the "current" drive.
-
-=item C<Cwd::sys_is_absolute(name)>
-
-means has drive letter and is_rooted.
-
-=item C<Cwd::sys_is_rooted(name)>
-
-means has leading C<[/\\]> (maybe after a drive-letter:).
-
-=item C<Cwd::sys_is_relative(name)>
-
-means changes with current dir.
-
-=item C<Cwd::sys_cwd(name)>
-
-Interface to cwd from EMX. Used by C<Cwd::cwd>.
-
-=item C<Cwd::sys_abspath(name, dir)>
-
-Really really odious function to implement. Returns absolute name of
-file which would have C<name> if CWD were C<dir>. C<Dir> defaults to the
-current dir.
-
-=item C<Cwd::extLibpath([type])>
-
-Get current value of extended library search path. If C<type> is
-present and positive, works with C<END_LIBPATH>, if negative, works
-with C<LIBPATHSTRICT>, otherwise with C<BEGIN_LIBPATH>.
-
-=item C<Cwd::extLibpath_set( path [, type ] )>
-
-Set current value of extended library search path. If C<type> is
-present and positive, works with <END_LIBPATH>, if negative, works
-with C<LIBPATHSTRICT>, otherwise with C<BEGIN_LIBPATH>.
-
-=item C<OS2::Error(do_harderror,do_exception)>
-
-Returns C<undef> if it was not called yet, otherwise bit 1 is
-set if on the previous call do_harderror was enabled, bit
-2 is set if on previous call do_exception was enabled.
-
-This function enables/disables error popups associated with
-hardware errors (Disk not ready etc.) and software exceptions.
-
-I know of no way to find out the state of popups I<before> the first call
-to this function.
-
-=item C<OS2::Errors2Drive(drive)>
-
-Returns C<undef> if it was not called yet, otherwise return false if errors
-were not requested to be written to a hard drive, or the drive letter if
-this was requested.
-
-This function may redirect error popups associated with hardware errors
-(Disk not ready etc.) and software exceptions to the file POPUPLOG.OS2 at
-the root directory of the specified drive. Overrides OS2::Error() specified
-by individual programs. Given argument undef will disable redirection.
-
-Has global effect, persists after the application exits.
-
-I know of no way to find out the state of redirection of popups to the disk
-I<before> the first call to this function.
-
-=item OS2::SysInfo()
-
-Returns a hash with system information. The keys of the hash are
-
- MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS,
- MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION,
- MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE,
- VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION,
- MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM,
- TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL,
- MAX_COMP_LENGTH, FOREGROUND_FS_SESSION,
- FOREGROUND_PROCESS
-
-=item OS2::BootDrive()
-
-Returns a letter without colon.
-
-=item C<OS2::MorphPM(serve)>, C<OS2::UnMorphPM(serve)>
-
-Transforms the current application into a PM application and back.
-The argument true means that a real message loop is going to be served.
-OS2::MorphPM() returns the PM message queue handle as an integer.
-
-See L<"Centralized management of resources"> for additional details.
-
-=item C<OS2::Serve_Messages(force)>
-
-Fake on-demand retrieval of outstanding PM messages. If C<force> is false,
-will not dispatch messages if a real message loop is known to
-be present. Returns number of messages retrieved.
-
-Dies with "QUITing..." if WM_QUIT message is obtained.
-
-=item C<OS2::Process_Messages(force [, cnt])>
-
-Retrieval of PM messages until window creation/destruction.
-If C<force> is false, will not dispatch messages if a real message loop
-is known to be present.
-
-Returns change in number of windows. If C<cnt> is given,
-it is incremented by the number of messages retrieved.
-
-Dies with "QUITing..." if WM_QUIT message is obtained.
-
-=item C<OS2::_control87(new,mask)>
-
-the same as L<_control87(3)> of EMX. Takes integers as arguments, returns
-the previous coprocessor control word as an integer. Only bits in C<new> which
-are present in C<mask> are changed in the control word.
-
-=item OS2::get_control87()
-
-gets the coprocessor control word as an integer.
-
-=item C<OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)>
-
-The variant of OS2::_control87() with default values good for
-handling exception mask: if no C<mask>, uses exception mask part of C<new>
-only. If no C<new>, disables all the floating point exceptions.
-
-See L<"Misfeatures"> for details.
-
-=item C<OS2::DLLname([how [, \&xsub]])>
-
-Gives the information about the Perl DLL or the DLL containing the C
-function bound to by C<&xsub>. The meaning of C<how> is: default (2):
-full name; 0: handle; 1: module name.
-
-=back
-
-(Note that some of these may be moved to different libraries -
-eventually).
-
-
-=head2 Prebuilt variables:
-
-=over 4
-
-=item $OS2::emx_rev
-
-numeric value is the same as _emx_rev of EMX, a string value the same
-as _emx_vprt (similar to C<0.9c>).
-
-=item $OS2::emx_env
-
-same as _emx_env of EMX, a number similar to 0x8001.
-
-=item $OS2::os_ver
-
-a number C<OS_MAJOR + 0.001 * OS_MINOR>.
-
-=item $OS2::is_aout
-
-true if the Perl library was compiled in AOUT format.
-
-=item $OS2::can_fork
-
-true if the current executable is an AOUT EMX executable, so Perl can
-fork. Do not use this, use the portable check for
-$Config::Config{dfork}.
-
-=item $OS2::nsyserror
-
-This variable (default is 1) controls whether to enforce the contents
-of $^E to start with C<SYS0003>-like id. If set to 0, then the string
-value of $^E is what is available from the OS/2 message file. (Some
-messages in this file have an C<SYS0003>-like id prepended, some not.)
-
-=back
-
-=head2 Misfeatures
-
-=over 4
-
-=item *
-
-Since L<flock(3)> is present in EMX, but is not functional, it is
-emulated by perl. To disable the emulations, set environment variable
-C<USE_PERL_FLOCK=0>.
-
-=item *
-
-Here is the list of things which may be "broken" on
-EMX (from EMX docs):
-
-=over 4
-
-=item *
-
-The functions L<recvmsg(3)>, L<sendmsg(3)>, and L<socketpair(3)> are not
-implemented.
-
-=item *
-
-L<sock_init(3)> is not required and not implemented.
-
-=item *
-
-L<flock(3)> is not yet implemented (dummy function). (Perl has a workaround.)
-
-=item *
-
-L<kill(3)>: Special treatment of PID=0, PID=1 and PID=-1 is not implemented.
-
-=item *
-
-L<waitpid(3)>:
-
- WUNTRACED
- Not implemented.
- waitpid() is not implemented for negative values of PID.
-
-=back
-
-Note that C<kill -9> does not work with the current version of EMX.
-
-=item *
-
-See L<"Text-mode filehandles">.
-
-=item *
-
-Unix-domain sockets on OS/2 live in a pseudo-file-system C</sockets/...>.
-To avoid a failure to create a socket with a name of a different form,
-C<"/socket/"> is prepended to the socket name (unless it starts with this
-already).
-
-This may lead to problems later in case the socket is accessed via the
-"usual" file-system calls using the "initial" name.
-
-=item *
-
-Apparently, IBM used a compiler (for some period of time around '95?) which
-changes FP mask right and left. This is not I<that> bad for IBM's
-programs, but the same compiler was used for DLLs which are used with
-general-purpose applications. When these DLLs are used, the state of
-floating-point flags in the application is not predictable.
-
-What is much worse, some DLLs change the floating point flags when in
-_DLLInitTerm() (e.g., F<TCP32IP>). This means that even if you do not I<call>
-any function in the DLL, just the act of loading this DLL will reset your
-flags. What is worse, the same compiler was used to compile some HOOK DLLs.
-Given that HOOK dlls are executed in the context of I<all> the applications
-in the system, this means a complete unpredictability of floating point
-flags on systems using such HOOK DLLs. E.g., F<GAMESRVR.DLL> of B<DIVE>
-origin changes the floating point flags on each write to the TTY of a VIO
-(windowed text-mode) applications.
-
-Some other (not completely debugged) situations when FP flags change include
-some video drivers (?), and some operations related to creation of the windows.
-People who code B<OpenGL> may have more experience on this.
-
-Perl is generally used in the situation when all the floating-point
-exceptions are ignored, as is the default under EMX. If they are not ignored,
-some benign Perl programs would get a C<SIGFPE> and would die a horrible death.
-
-To circumvent this, Perl uses two hacks. They help against I<one> type of
-damage only: FP flags changed when loading a DLL.
-
-One of the hacks is to disable floating point exceptions on Perl startup (as
-is the default with EMX). This helps only with compile-time-linked DLLs
-changing the flags before main() had a chance to be called.
-
-The other hack is to restore FP flags after a call to dlopen(). This helps
-against similar damage done by DLLs _DLLInitTerm() at runtime. Currently
-no way to switch these hacks off is provided.
-
-=back
-
-=head2 Modifications
-
-Perl modifies some standard C library calls in the following ways:
-
-=over 9
-
-=item C<popen>
-
-C<my_popen> uses F<sh.exe> if shell is required, cf. L<"PERL_SH_DIR">.
-
-=item C<tmpnam>
-
-is created using C<TMP> or C<TEMP> environment variable, via
-C<tempnam>.
-
-=item C<tmpfile>
-
-If the current directory is not writable, file is created using modified
-C<tmpnam>, so there may be a race condition.
-
-=item C<ctermid>
-
-a dummy implementation.
-
-=item C<stat>
-
-C<os2_stat> special-cases F</dev/tty> and F</dev/con>.
-
-=item C<mkdir>, C<rmdir>
-
-these EMX functions do not work if the path contains a trailing C</>.
-Perl contains a workaround for this.
-
-=item C<flock>
-
-Since L<flock(3)> is present in EMX, but is not functional, it is
-emulated by perl. To disable the emulations, set environment variable
-C<USE_PERL_FLOCK=0>.
-
-=back
-
-=head2 Identifying DLLs
-
-All the DLLs built with the current versions of Perl have ID strings
-identifying the name of the extension, its version, and the version
-of Perl required for this DLL. Run C<bldlevel DLL-name> to find this
-info.
-
-=head2 Centralized management of resources
-
-Since to call certain OS/2 API one needs to have a correctly initialized
-C<Win> subsystem, OS/2-specific extensions may require getting C<HAB>s and
-C<HMQ>s. If an extension would do it on its own, another extension could
-fail to initialize.
-
-Perl provides a centralized management of these resources:
-
-=over
-
-=item C<HAB>
-
-To get the HAB, the extension should call C<hab = perl_hab_GET()> in C. After
-this call is performed, C<hab> may be accessed as C<Perl_hab>. There is
-no need to release the HAB after it is used.
-
-If by some reasons F<perl.h> cannot be included, use
-
- extern int Perl_hab_GET(void);
-
-instead.
-
-=item C<HMQ>
-
-There are two cases:
-
-=over
-
-=item *
-
-the extension needs an C<HMQ> only because some API will not work otherwise.
-Use C<serve = 0> below.
-
-=item *
-
-the extension needs an C<HMQ> since it wants to engage in a PM event loop.
-Use C<serve = 1> below.
-
-=back
-
-To get an C<HMQ>, the extension should call C<hmq = perl_hmq_GET(serve)> in C.
-After this call is performed, C<hmq> may be accessed as C<Perl_hmq>.
-
-To signal to Perl that HMQ is not needed any more, call
-C<perl_hmq_UNSET(serve)>. Perl process will automatically morph/unmorph itself
-into/from a PM process if HMQ is needed/not-needed. Perl will automatically
-enable/disable C<WM_QUIT> message during shutdown if the message queue is
-served/not-served.
-
-B<NOTE>. If during a shutdown there is a message queue which did not disable
-WM_QUIT, and which did not process the received WM_QUIT message, the
-shutdown will be automatically cancelled. Do not call C<perl_hmq_GET(1)>
-unless you are going to process messages on an orderly basis.
-
-=item Treating errors reported by OS/2 API
-
-There are two principal conventions (it is useful to call them C<Dos*>
-and C<Win*> - though this part of the function signature is not always
-determined by the name of the API) of reporting the error conditions
-of OS/2 API. Most of C<Dos*> APIs report the error code as the result
-of the call (so 0 means success, and there are many types of errors).
-Most of C<Win*> API report success/fail via the result being
-C<TRUE>/C<FALSE>; to find the reason for the failure one should call
-WinGetLastError() API.
-
-Some C<Win*> entry points also overload a "meaningful" return value
-with the error indicator; having a 0 return value indicates an error.
-Yet some other C<Win*> entry points overload things even more, and 0
-return value may mean a successful call returning a valid value 0, as
-well as an error condition; in the case of a 0 return value one should
-call WinGetLastError() API to distinguish a successful call from a
-failing one.
-
-By convention, all the calls to OS/2 API should indicate their
-failures by resetting $^E. All the Perl-accessible functions which
-call OS/2 API may be broken into two classes: some die()s when an API
-error is encountered, the other report the error via a false return
-value (of course, this does not concern Perl-accessible functions
-which I<expect> a failure of the OS/2 API call, having some workarounds
-coded).
-
-Obviously, in the situation of the last type of the signature of an OS/2
-API, it is must more convenient for the users if the failure is
-indicated by die()ing: one does not need to check $^E to know that
-something went wrong. If, however, this solution is not desirable by
-some reason, the code in question should reset $^E to 0 before making
-this OS/2 API call, so that the caller of this Perl-accessible
-function has a chance to distinguish a success-but-0-return value from
-a failure. (One may return undef as an alternative way of reporting
-an error.)
-
-The macros to simplify this type of error propagation are
-
-=over
-
-=item C<CheckOSError(expr)>
-
-Returns true on error, sets $^E. Expects expr() be a call of
-C<Dos*>-style API.
-
-=item C<CheckWinError(expr)>
-
-Returns true on error, sets $^E. Expects expr() be a call of
-C<Win*>-style API.
-
-=item C<SaveWinError(expr)>
-
-Returns C<expr>, sets $^E from WinGetLastError() if C<expr> is false.
-
-=item C<SaveCroakWinError(expr,die,name1,name2)>
-
-Returns C<expr>, sets $^E from WinGetLastError() if C<expr> is false,
-and die()s if C<die> and $^E are true. The message to die is the
-concatenated strings C<name1> and C<name2>, separated by C<": "> from
-the contents of $^E.
-
-=item C<WinError_2_Perl_rc>
-
-Sets C<Perl_rc> to the return value of WinGetLastError().
-
-=item C<FillWinError>
-
-Sets C<Perl_rc> to the return value of WinGetLastError(), and sets $^E
-to the corresponding value.
-
-=item C<FillOSError(rc)>
-
-Sets C<Perl_rc> to C<rc>, and sets $^E to the corresponding value.
-
-=back
-
-=item Loading DLLs and ordinals in DLLs
-
-Some DLLs are only present in some versions of OS/2, or in some
-configurations of OS/2. Some exported entry points are present only
-in DLLs shipped with some versions of OS/2. If these DLLs and entry
-points were linked directly for a Perl executable/DLL or from a Perl
-extensions, this binary would work only with the specified
-versions/setups. Even if these entry points were not needed, the
-I<load> of the executable (or DLL) would fail.
-
-For example, many newer useful APIs are not present in OS/2 v2; many
-PM-related APIs require DLLs not available on floppy-boot setup.
-
-To make these calls fail I<only when the calls are executed>, one
-should call these API via a dynamic linking API. There is a subsystem
-in Perl to simplify such type of calls. A large number of entry
-points available for such linking is provided (see C<entries_ordinals>
-- and also C<PMWIN_entries> - in F<os2ish.h>). These ordinals can be
-accessed via the APIs:
-
- CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(),
- DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(),
- DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(),
- DeclWinFuncByORD_CACHE_resetError_survive(),
- DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(),
- DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive()
-
-See the header files and the C code in the supplied OS/2-related
-modules for the details on usage of these functions.
-
-Some of these functions also combine dynaloading semantic with the
-error-propagation semantic discussed above.
-
-=back
-
-=head1 Perl flavors
-
-Because of idiosyncrasies of OS/2 one cannot have all the eggs in the
-same basket (though EMX environment tries hard to overcome this
-limitations, so the situation may somehow improve). There are 4
-executables for Perl provided by the distribution:
-
-=head2 F<perl.exe>
-
-The main workhorse. This is a chimera executable: it is compiled as an
-C<a.out>-style executable, but is linked with C<omf>-style dynamic
-library F<perl.dll>, and with dynamic CRT DLL. This executable is a
-VIO application.
-
-It can load perl dynamic extensions, and it can fork().
-
-B<Note.> Keep in mind that fork() is needed to open a pipe to yourself.
-
-=head2 F<perl_.exe>
-
-This is a statically linked C<a.out>-style executable. It cannot
-load dynamic Perl extensions. The executable supplied in binary
-distributions has a lot of extensions prebuilt, thus the above restriction is
-important only if you use custom-built extensions. This executable is a VIO
-application.
-
-I<This is the only executable with does not require OS/2.> The
-friends locked into C<M$> world would appreciate the fact that this
-executable runs under DOS, Win0.3*, Win0.95 and WinNT with an
-appropriate extender. See L<"Other OSes">.
-
-=head2 F<perl__.exe>
-
-This is the same executable as F<perl___.exe>, but it is a PM
-application.
-
-B<Note.> Usually (unless explicitly redirected during the startup)
-STDIN, STDERR, and STDOUT of a PM
-application are redirected to F<nul>. However, it is possible to I<see>
-them if you start C<perl__.exe> from a PM program which emulates a
-console window, like I<Shell mode> of Emacs or EPM. Thus it I<is
-possible> to use Perl debugger (see L<perldebug>) to debug your PM
-application (but beware of the message loop lockups - this will not
-work if you have a message queue to serve, unless you hook the serving
-into the getc() function of the debugger).
-
-Another way to see the output of a PM program is to run it as
-
- pm_prog args 2>&1 | cat -
-
-with a shell I<different> from F<cmd.exe>, so that it does not create
-a link between a VIO session and the session of C<pm_porg>. (Such a link
-closes the VIO window.) E.g., this works with F<sh.exe> - or with Perl!
-
- open P, 'pm_prog args 2>&1 |' or die;
- print while <P>;
-
-The flavor F<perl__.exe> is required if you want to start your program without
-a VIO window present, but not C<detach>ed (run C<help detach> for more info).
-Very useful for extensions which use PM, like C<Perl/Tk> or C<OpenGL>.
-
-Note also that the differences between PM and VIO executables are only
-in the I<default> behaviour. One can start I<any> executable in
-I<any> kind of session by using the arguments C</fs>, C</pm> or
-C</win> switches of the command C<start> (of F<CMD.EXE> or a similar
-shell). Alternatively, one can use the numeric first argument of the
-C<system> Perl function (see L<OS2::Process>).
-
-=head2 F<perl___.exe>
-
-This is an C<omf>-style executable which is dynamically linked to
-F<perl.dll> and CRT DLL. I know no advantages of this executable
-over C<perl.exe>, but it cannot fork() at all. Well, one advantage is
-that the build process is not so convoluted as with C<perl.exe>.
-
-It is a VIO application.
-
-=head2 Why strange names?
-
-Since Perl processes the C<#!>-line (cf.
-L<perlrun/DESCRIPTION>, L<perlrun/Command Switches>,
-L<perldiag/"No Perl script found in input">), it should know when a
-program I<is a Perl>. There is some naming convention which allows
-Perl to distinguish correct lines from wrong ones. The above names are
-almost the only names allowed by this convention which do not contain
-digits (which have absolutely different semantics).
-
-=head2 Why dynamic linking?
-
-Well, having several executables dynamically linked to the same huge
-library has its advantages, but this would not substantiate the
-additional work to make it compile. The reason is the complicated-to-developers
-but very quick and convenient-to-users "hard" dynamic linking used by OS/2.
-
-There are two distinctive features of the dyna-linking model of OS/2:
-first, all the references to external functions are resolved at the compile time;
-second, there is no runtime fixup of the DLLs after they are loaded into memory.
-The first feature is an enormous advantage over other models: it avoids
-conflicts when several DLLs used by an application export entries with
-the same name. In such cases "other" models of dyna-linking just choose
-between these two entry points using some random criterion - with predictable
-disasters as results. But it is the second feature which requires the build
-of F<perl.dll>.
-
-The address tables of DLLs are patched only once, when they are
-loaded. The addresses of the entry points into DLLs are guaranteed to be
-the same for all the programs which use the same DLL. This removes the
-runtime fixup - once DLL is loaded, its code is read-only.
-
-While this allows some (significant?) performance advantages, this makes life
-much harder for developers, since the above scheme makes it impossible
-for a DLL to be "linked" to a symbol in the F<.EXE> file. Indeed, this
-would need a DLL to have different relocations tables for the
-(different) executables which use this DLL.
-
-However, a dynamically loaded Perl extension is forced to use some symbols
-from the perl
-executable, e.g., to know how to find the arguments to the functions:
-the arguments live on the perl
-internal evaluation stack. The solution is to put the main code of
-the interpreter into a DLL, and make the F<.EXE> file which just loads
-this DLL into memory and supplies command-arguments. The extension DLL
-cannot link to symbols in F<.EXE>, but it has no problem linking
-to symbols in the F<.DLL>.
-
-This I<greatly> increases the load time for the application (as well as
-complexity of the compilation). Since interpreter is in a DLL,
-the C RTL is basically forced to reside in a DLL as well (otherwise
-extensions would not be able to use CRT). There are some advantages if
-you use different flavors of perl, such as running F<perl.exe> and
-F<perl__.exe> simultaneously: they share the memory of F<perl.dll>.
-
-B<NOTE>. There is one additional effect which makes DLLs more wasteful:
-DLLs are loaded in the shared memory region, which is a scarse resource
-given the 512M barrier of the "standard" OS/2 virtual memory. The code of
-F<.EXE> files is also shared by all the processes which use the particular
-F<.EXE>, but they are "shared in the private address space of the process";
-this is possible because the address at which different sections
-of the F<.EXE> file are loaded is decided at compile-time, thus all the
-processes have these sections loaded at same addresses, and no fixup
-of internal links inside the F<.EXE> is needed.
-
-Since DLLs may be loaded at run time, to have the same mechanism for DLLs
-one needs to have the address range of I<any of the loaded> DLLs in the
-system to be available I<in all the processes> which did not load a particular
-DLL yet. This is why the DLLs are mapped to the shared memory region.
-
-=head2 Why chimera build?
-
-Current EMX environment does not allow DLLs compiled using Unixish
-C<a.out> format to export symbols for data (or at least some types of
-data). This forces C<omf>-style compile of F<perl.dll>.
-
-Current EMX environment does not allow F<.EXE> files compiled in
-C<omf> format to fork(). fork() is needed for exactly three Perl
-operations:
-
-=over 4
-
-=item *
-
-explicit fork() in the script,
-
-=item *
-
-C<open FH, "|-">
-
-=item *
-
-C<open FH, "-|">, in other words, opening pipes to itself.
-
-=back
-
-While these operations are not questions of life and death, they are
-needed for a lot of
-useful scripts. This forces C<a.out>-style compile of
-F<perl.exe>.
-
-
-=head1 ENVIRONMENT
-
-Here we list environment variables with are either OS/2- and DOS- and
-Win*-specific, or are more important under OS/2 than under other OSes.
-
-=head2 C<PERLLIB_PREFIX>
-
-Specific for EMX port. Should have the form
-
- path1;path2
-
-or
-
- path1 path2
-
-If the beginning of some prebuilt path matches F<path1>, it is
-substituted with F<path2>.
-
-Should be used if the perl library is moved from the default
-location in preference to C<PERL(5)LIB>, since this would not leave wrong
-entries in @INC. For example, if the compiled version of perl looks for @INC
-in F<f:/perllib/lib>, and you want to install the library in
-F<h:/opt/gnu>, do
-
- set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu
-
-This will cause Perl with the prebuilt @INC of
-
- f:/perllib/lib/5.00553/os2
- f:/perllib/lib/5.00553
- f:/perllib/lib/site_perl/5.00553/os2
- f:/perllib/lib/site_perl/5.00553
- .
-
-to use the following @INC:
-
- h:/opt/gnu/5.00553/os2
- h:/opt/gnu/5.00553
- h:/opt/gnu/site_perl/5.00553/os2
- h:/opt/gnu/site_perl/5.00553
- .
-
-=head2 C<PERL_BADLANG>
-
-If 0, perl ignores setlocale() failing. May be useful with some
-strange I<locale>s.
-
-=head2 C<PERL_BADFREE>
-
-If 0, perl would not warn of in case of unwarranted free(). With older
-perls this might be
-useful in conjunction with the module DB_File, which was buggy when
-dynamically linked and OMF-built.
-
-Should not be set with newer Perls, since this may hide some I<real> problems.
-
-=head2 C<PERL_SH_DIR>
-
-Specific for EMX port. Gives the directory part of the location for
-F<sh.exe>.
-
-=head2 C<USE_PERL_FLOCK>
-
-Specific for EMX port. Since L<flock(3)> is present in EMX, but is not
-functional, it is emulated by perl. To disable the emulations, set
-environment variable C<USE_PERL_FLOCK=0>.
-
-=head2 C<TMP> or C<TEMP>
-
-Specific for EMX port. Used as storage place for temporary files.
-
-=head1 Evolution
-
-Here we list major changes which could make you by surprise.
-
-=head2 Text-mode filehandles
-
-Starting from version 5.8, Perl uses a builtin translation layer for
-text-mode files. This replaces the efficient well-tested EMX layer by
-some code which should be best characterized as a "quick hack".
-
-In addition to possible bugs and an inability to follow changes to the
-translation policy with off/on switches of TERMIO translation, this
-introduces a serious incompatible change: before sysread() on
-text-mode filehandles would go through the translation layer, now it
-would not.
-
-=head2 Priorities
-
-C<setpriority> and C<getpriority> are not compatible with earlier
-ports by Andreas Kaiser. See C<"setpriority, getpriority">.
-
-=head2 DLL name mangling: pre 5.6.2
-
-With the release 5.003_01 the dynamically loadable libraries
-should be rebuilt when a different version of Perl is compiled. In particular,
-DLLs (including F<perl.dll>) are now created with the names
-which contain a checksum, thus allowing workaround for OS/2 scheme of
-caching DLLs.
-
-It may be possible to code a simple workaround which would
-
-=over
-
-=item *
-
-find the old DLLs looking through the old @INC;
-
-=item *
-
-mangle the names according to the scheme of new perl and copy the DLLs to
-these names;
-
-=item *
-
-edit the internal C<LX> tables of DLL to reflect the change of the name
-(probably not needed for Perl extension DLLs, since the internally coded names
-are not used for "specific" DLLs, they used only for "global" DLLs).
-
-=item *
-
-edit the internal C<IMPORT> tables and change the name of the "old"
-F<perl????.dll> to the "new" F<perl????.dll>.
-
-=back
-
-=head2 DLL name mangling: 5.6.2 and beyond
-
-In fact mangling of I<extension> DLLs was done due to misunderstanding
-of the OS/2 dynaloading model. OS/2 (effectively) maintains two
-different tables of loaded DLL:
-
-=over
-
-=item Global DLLs
-
-those loaded by the base name from C<LIBPATH>; including those
-associated at link time;
-
-=item specific DLLs
-
-loaded by the full name.
-
-=back
-
-When resolving a request for a global DLL, the table of already-loaded
-specific DLLs is (effectively) ignored; moreover, specific DLLs are
-I<always> loaded from the prescribed path.
-
-There is/was a minor twist which makes this scheme fragile: what to do
-with DLLs loaded from
-
-=over
-
-=item C<BEGINLIBPATH> and C<ENDLIBPATH>
-
-(which depend on the process)
-
-=item F<.> from C<LIBPATH>
-
-which I<effectively> depends on the process (although C<LIBPATH> is the
-same for all the processes).
-
-=back
-
-Unless C<LIBPATHSTRICT> is set to C<T> (and the kernel is after
-2000/09/01), such DLLs are considered to be global. When loading a
-global DLL it is first looked in the table of already-loaded global
-DLLs. Because of this the fact that one executable loaded a DLL from
-C<BEGINLIBPATH> and C<ENDLIBPATH>, or F<.> from C<LIBPATH> may affect
-I<which> DLL is loaded when I<another> executable requests a DLL with
-the same name. I<This> is the reason for version-specific mangling of
-the DLL name for perl DLL.
-
-Since the Perl extension DLLs are always loaded with the full path,
-there is no need to mangle their names in a version-specific ways:
-their directory already reflects the corresponding version of perl,
-and @INC takes into account binary compatibility with older version.
-Starting from C<5.6.2> the name mangling scheme is fixed to be the
-same as for Perl 5.005_53 (same as in a popular binary release). Thus
-new Perls will be able to I<resolve the names> of old extension DLLs
-if @INC allows finding their directories.
-
-However, this still does not guarantee that these DLL may be loaded.
-The reason is the mangling of the name of the I<Perl DLL>. And since
-the extension DLLs link with the Perl DLL, extension DLLs for older
-versions would load an older Perl DLL, and would most probably
-segfault (since the data in this DLL is not properly initialized).
-
-There is a partial workaround (which can be made complete with newer
-OS/2 kernels): create a forwarder DLL with the same name as the DLL of
-the older version of Perl, which forwards the entry points to the
-newer Perl's DLL. Make this DLL accessible on (say) the C<BEGINLIBPATH> of
-the new Perl executable. When the new executable accesses old Perl's
-extension DLLs, they would request the old Perl's DLL by name, get the
-forwarder instead, so effectively will link with the currently running
-(new) Perl DLL.
-
-This may break in two ways:
-
-=over
-
-=item *
-
-Old perl executable is started when a new executable is running has
-loaded an extension compiled for the old executable (ouph!). In this
-case the old executable will get a forwarder DLL instead of the old
-perl DLL, so would link with the new perl DLL. While not directly
-fatal, it will behave the same as new executable. This beats the whole
-purpose of explicitly starting an old executable.
-
-=item *
-
-A new executable loads an extension compiled for the old executable
-when an old perl executable is running. In this case the extension
-will not pick up the forwarder - with fatal results.
-
-=back
-
-With support for C<LIBPATHSTRICT> this may be circumvented - unless
-one of DLLs is started from F<.> from C<LIBPATH> (I do not know
-whether C<LIBPATHSTRICT> affects this case).
-
-B<REMARK>. Unless newer kernels allow F<.> in C<BEGINLIBPATH> (older
-do not), this mess cannot be completely cleaned. (It turns out that
-as of the beginning of 2002, F<.> is not allowed, but F<.\.> is - and
-it has the same effect.)
-
-
-B<REMARK>. C<LIBPATHSTRICT>, C<BEGINLIBPATH> and C<ENDLIBPATH> are
-not environment variables, although F<cmd.exe> emulates them on C<SET
-...> lines. From Perl they may be accessed by
-L<Cwd::extLibpath|/Cwd::extLibpath([type])> and
-L<Cwd::extLibpath_set|/Cwd::extLibpath_set( path [, type ] )>.
-
-=head2 DLL forwarder generation
-
-Assume that the old DLL is named F<perlE0AC.dll> (as is one for
-5.005_53), and the new version is 5.6.1. Create a file
-F<perl5shim.def-leader> with
-
- LIBRARY 'perlE0AC' INITINSTANCE TERMINSTANCE
- DESCRIPTION '@#perl5-porters@perl.org:5.006001#@ Perl module for 5.00553 -> Perl 5.6.1 forwarder'
- CODE LOADONCALL
- DATA LOADONCALL NONSHARED MULTIPLE
- EXPORTS
-
-modifying the versions/names as needed. Run
-
- perl -wnle "next if 0../EXPORTS/; print qq( \"$1\") if /\"(\w+)\"/" perl5.def >lst
-
-in the Perl build directory (to make the DLL smaller replace perl5.def
-with the definition file for the older version of Perl if present).
-
- cat perl5shim.def-leader lst >perl5shim.def
- gcc -Zomf -Zdll -o perlE0AC.dll perl5shim.def -s -llibperl
-
-(ignore multiple C<warning L4085>).
-
-=head2 Threading
-
-As of release 5.003_01 perl is linked to multithreaded C RTL
-DLL. If perl itself is not compiled multithread-enabled, so will not be perl's
-malloc(). However, extensions may use multiple thread on their own
-risk.
-
-This was needed to compile C<Perl/Tk> for XFree86-OS/2 out-of-the-box, and
-link with DLLs for other useful libraries, which typically are compiled
-with C<-Zmt -Zcrtdll>.
-
-=head2 Calls to external programs
-
-Due to a popular demand the perl external program calling has been
-changed wrt Andreas Kaiser's port. I<If> perl needs to call an
-external program I<via shell>, the F<f:/bin/sh.exe> will be called, or
-whatever is the override, see L<"PERL_SH_DIR">.
-
-Thus means that you need to get some copy of a F<sh.exe> as well (I
-use one from pdksh). The path F<F:/bin> above is set up automatically during
-the build to a correct value on the builder machine, but is
-overridable at runtime,
-
-B<Reasons:> a consensus on C<perl5-porters> was that perl should use
-one non-overridable shell per platform. The obvious choices for OS/2
-are F<cmd.exe> and F<sh.exe>. Having perl build itself would be impossible
-with F<cmd.exe> as a shell, thus I picked up C<sh.exe>. This assures almost
-100% compatibility with the scripts coming from *nix. As an added benefit
-this works as well under DOS if you use DOS-enabled port of pdksh
-(see L</Prerequisites>).
-
-B<Disadvantages:> currently F<sh.exe> of pdksh calls external programs
-via fork()/exec(), and there is I<no> functioning exec() on
-OS/2. exec() is emulated by EMX by an asynchronous call while the caller
-waits for child completion (to pretend that the C<pid> did not change). This
-means that 1 I<extra> copy of F<sh.exe> is made active via fork()/exec(),
-which may lead to some resources taken from the system (even if we do
-not count extra work needed for fork()ing).
-
-Note that this a lesser issue now when we do not spawn F<sh.exe>
-unless needed (metachars found).
-
-One can always start F<cmd.exe> explicitly via
-
- system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ...
-
-If you need to use F<cmd.exe>, and do not want to hand-edit thousands of your
-scripts, the long-term solution proposed on p5-p is to have a directive
-
- use OS2::Cmd;
-
-which will override system(), exec(), C<``>, and
-C<open(,'...|')>. With current perl you may override only system(),
-readpipe() - the explicit version of C<``>, and maybe exec(). The code
-will substitute the one-argument call to system() by
-C<CORE::system('cmd.exe', '/c', shift)>.
-
-If you have some working code for C<OS2::Cmd>, please send it to me,
-I will include it into distribution. I have no need for such a module, so
-cannot test it.
-
-For the details of the current situation with calling external programs,
-see L<Starting OSE<sol>2 (and DOS) programs under Perl>. Set us mention a couple
-of features:
-
-=over 4
-
-=item *
-
-External scripts may be called by their basename. Perl will try the same
-extensions as when processing B<-S> command-line switch.
-
-=item *
-
-External scripts starting with C<#!> or C<extproc > will be executed directly,
-without calling the shell, by calling the program specified on the rest of
-the first line.
-
-=back
-
-=head2 Memory allocation
-
-Perl uses its own malloc() under OS/2 - interpreters are usually malloc-bound
-for speed, but perl is not, since its malloc is lightning-fast.
-Perl-memory-usage-tuned benchmarks show that Perl's malloc is 5 times quicker
-than EMX one. I do not have convincing data about memory footprint, but
-a (pretty random) benchmark showed that Perl's one is 5% better.
-
-Combination of perl's malloc() and rigid DLL name resolution creates
-a special problem with library functions which expect their return value to
-be free()d by system's free(). To facilitate extensions which need to call
-such functions, system memory-allocation functions are still available with
-the prefix C<emx_> added. (Currently only DLL perl has this, it should
-propagate to F<perl_.exe> shortly.)
-
-=head2 Threads
-
-One can build perl with thread support enabled by providing C<-D usethreads>
-option to F<Configure>. Currently OS/2 support of threads is very
-preliminary.
-
-Most notable problems:
-
-=over 4
-
-=item C<COND_WAIT>
-
-may have a race condition (but probably does not due to edge-triggered
-nature of OS/2 Event semaphores). (Needs a reimplementation (in terms of chaining
-waiting threads, with the linked list stored in per-thread structure?)?)
-
-=item F<os2.c>
-
-has a couple of static variables used in OS/2-specific functions. (Need to be
-moved to per-thread structure, or serialized?)
-
-=back
-
-Note that these problems should not discourage experimenting, since they
-have a low probability of affecting small programs.
-
-=head1 BUGS
-
-This description is not updated often (since 5.6.1?), see F<./os2/Changes>
-for more info.
-
-=cut
-
-OS/2 extensions
-~~~~~~~~~~~~~~~
-I include 3 extensions by Andreas Kaiser, OS2::REXX, OS2::UPM, and OS2::FTP,
-into my ftp directory, mirrored on CPAN. I made
-some minor changes needed to compile them by standard tools. I cannot
-test UPM and FTP, so I will appreciate your feedback. Other extensions
-there are OS2::ExtAttr, OS2::PrfDB for tied access to EAs and .INI
-files - and maybe some other extensions at the time you read it.
-
-Note that OS2 perl defines 2 pseudo-extension functions
-OS2::Copy::copy and DynaLoader::mod2fname (many more now, see
-L<Prebuilt methods>).
-
-The -R switch of older perl is deprecated. If you need to call a REXX code
-which needs access to variables, include the call into a REXX compartment
-created by
- REXX_call {...block...};
-
-Two new functions are supported by REXX code,
- REXX_eval 'string';
- REXX_eval_with 'string', REXX_function_name => \&perl_sub_reference;
-
-If you have some other extensions you want to share, send the code to
-me. At least two are available: tied access to EA's, and tied access
-to system databases.
-
-=head1 AUTHOR
-
-Ilya Zakharevich, cpan@ilyaz.org
-
-=head1 SEE ALSO
-
-perl(1).
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlos390.pod b/Master/tlpkg/tlperl/lib/pods/perlos390.pod
deleted file mode 100644
index 6e2d49e7317..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlos390.pod
+++ /dev/null
@@ -1,444 +0,0 @@
-This document is written in pod format hence there are punctuation
-characters in odd places. Do not worry, you've apparently got the
-ASCII->EBCDIC translation worked out correctly. You can read more
-about pod in pod/perlpod.pod or the short summary in the INSTALL file.
-
-=head1 NAME
-
-perlos390 - building and installing Perl for OS/390 and z/OS
-
-=head1 SYNOPSIS
-
-This document will help you Configure, build, test and install Perl
-on OS/390 (aka z/OS) Unix System Services.
-
-=head1 DESCRIPTION
-
-This is a fully ported Perl for OS/390 Version 2 Release 3, 5, 6, 7,
-8, and 9. It may work on other versions or releases, but those are
-the ones we've tested it on.
-
-You may need to carry out some system configuration tasks before
-running the Configure script for Perl.
-
-
-=head2 Tools
-
-The z/OS Unix Tools and Toys list may prove helpful and contains links
-to ports of much of the software helpful for building Perl.
-http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1toy.html
-
-
-=head2 Unpacking Perl distribution on OS/390
-
-If using ftp remember to transfer the distribution in binary format.
-
-Gunzip/gzip for OS/390 is discussed at:
-
- http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1ty1.html
-
-to extract an ASCII tar archive on OS/390, try this:
-
- pax -o to=IBM-1047,from=ISO8859-1 -r < latest.tar
-
-or
-
- zcat latest.tar.Z | pax -o to=IBM-1047,from=ISO8859-1 -r
-
-If you get lots of errors of the form
-
- tar: FSUM7171 ...: cannot set uid/gid: EDC5139I Operation not permitted.
-
-you didn't read the above and tried to use tar instead of pax, you'll
-first have to remove the (now corrupt) perl directory
-
- rm -rf perl-...
-
-and then use pax.
-
-=head2 Setup and utilities for Perl on OS/390
-
-Be sure that your yacc installation is in place including any necessary
-parser template files. If you have not already done so then be sure to:
-
- cp /samples/yyparse.c /etc
-
-This may also be a good time to ensure that your /etc/protocol file
-and either your /etc/resolv.conf or /etc/hosts files are in place.
-The IBM document that described such USS system setup issues was
-SC28-1890-07 "OS/390 UNIX System Services Planning", in particular
-Chapter 6 on customizing the OE shell.
-
-GNU make for OS/390, which is recommended for the build of perl (as
-well as building CPAN modules and extensions), is available from the
-L</Tools>.
-
-Some people have reported encountering "Out of memory!" errors while
-trying to build Perl using GNU make binaries. If you encounter such
-trouble then try to download the source code kit and build GNU make
-from source to eliminate any such trouble. You might also find GNU make
-(as well as Perl and Apache) in the red-piece/book "Open Source Software
-for OS/390 UNIX", SG24-5944-00 from IBM.
-
-If instead of the recommended GNU make you would like to use the system
-supplied make program then be sure to install the default rules file
-properly via the shell command:
-
- cp /samples/startup.mk /etc
-
-and be sure to also set the environment variable _C89_CCMODE=1 (exporting
-_C89_CCMODE=1 is also a good idea for users of GNU make).
-
-You might also want to have GNU groff for OS/390 installed before
-running the "make install" step for Perl.
-
-There is a syntax error in the /usr/include/sys/socket.h header file
-that IBM supplies with USS V2R7, V2R8, and possibly V2R9. The problem with
-the header file is that near the definition of the SO_REUSEPORT constant
-there is a spurious extra '/' character outside of a comment like so:
-
- #define SO_REUSEPORT 0x0200 /* allow local address & port
- reuse */ /
-
-You could edit that header yourself to remove that last '/', or you might
-note that Language Environment (LE) APAR PQ39997 describes the problem
-and PTF's UQ46272 and UQ46271 are the (R8 at least) fixes and apply them.
-If left unattended that syntax error will turn up as an inability for Perl
-to build its "Socket" extension.
-
-For successful testing you may need to turn on the sticky bit for your
-world readable /tmp directory if you have not already done so (see man chmod).
-
-=head2 Configure Perl on OS/390
-
-Once you've unpacked the distribution, run "sh Configure" (see INSTALL
-for a full discussion of the Configure options). There is a "hints" file
-for os390 that specifies the correct values for most things. Some things
-to watch out for include:
-
-=over 4
-
-=item *
-
-A message of the form:
-
- (I see you are using the Korn shell. Some ksh's blow up on Configure,
- mainly on older exotic systems. If yours does, try the Bourne shell instead.)
-
-is nothing to worry about at all.
-
-=item *
-
-Some of the parser default template files in /samples are needed in /etc.
-In particular be sure that you at least copy /samples/yyparse.c to /etc
-before running Perl's Configure. This step ensures successful extraction
-of EBCDIC versions of parser files such as perly.c, perly.h, and x2p/a2p.c.
-This has to be done before running Configure the first time. If you failed
-to do so then the easiest way to re-Configure Perl is to delete your
-misconfigured build root and re-extract the source from the tar ball.
-Then you must ensure that /etc/yyparse.c is properly in place before
-attempting to re-run Configure.
-
-=item *
-
-This port will support dynamic loading, but it is not selected by
-default. If you would like to experiment with dynamic loading then
-be sure to specify -Dusedl in the arguments to the Configure script.
-See the comments in hints/os390.sh for more information on dynamic loading.
-If you build with dynamic loading then you will need to add the
-$archlibexp/CORE directory to your LIBPATH environment variable in order
-for perl to work. See the config.sh file for the value of $archlibexp.
-If in trying to use Perl you see an error message similar to:
-
- CEE3501S The module libperl.dll was not found.
- From entry point __dllstaticinit at compile unit offset +00000194 at
-
-then your LIBPATH does not have the location of libperl.x and either
-libperl.dll or libperl.so in it. Add that directory to your LIBPATH and
-proceed.
-
-=item *
-
-Do not turn on the compiler optimization flag "-O". There is
-a bug in either the optimizer or perl that causes perl to
-not work correctly when the optimizer is on.
-
-=item *
-
-Some of the configuration files in /etc used by the
-networking APIs are either missing or have the wrong
-names. In particular, make sure that there's either
-an /etc/resolv.conf or an /etc/hosts, so that
-gethostbyname() works, and make sure that the file
-/etc/proto has been renamed to /etc/protocol (NOT
-/etc/protocols, as used by other Unix systems).
-You may have to look for things like HOSTNAME and DOMAINORIGIN
-in the "//'SYS1.TCPPARMS(TCPDATA)'" PDS member in order to
-properly set up your /etc networking files.
-
-=back
-
-=head2 Build, Test, Install Perl on OS/390
-
-Simply put:
-
- sh Configure
- make
- make test
-
-if everything looks ok (see the next section for test/IVP diagnosis) then:
-
- make install
-
-this last step may or may not require UID=0 privileges depending
-on how you answered the questions that Configure asked and whether
-or not you have write access to the directories you specified.
-
-=head2 Build Anomalies with Perl on OS/390
-
-"Out of memory!" messages during the build of Perl are most often fixed
-by re building the GNU make utility for OS/390 from a source code kit.
-
-Another memory limiting item to check is your MAXASSIZE parameter in your
-'SYS1.PARMLIB(BPXPRMxx)' data set (note too that as of V2R8 address space
-limits can be set on a per user ID basis in the USS segment of a RACF
-profile). People have reported successful builds of Perl with MAXASSIZE
-parameters as small as 503316480 (and it may be possible to build Perl
-with a MAXASSIZE smaller than that).
-
-Within USS your /etc/profile or $HOME/.profile may limit your ulimit
-settings. Check that the following command returns reasonable values:
-
- ulimit -a
-
-To conserve memory you should have your compiler modules loaded into the
-Link Pack Area (LPA/ELPA) rather than in a link list or step lib.
-
-If the c89 compiler complains of syntax errors during the build of the
-Socket extension then be sure to fix the syntax error in the system
-header /usr/include/sys/socket.h.
-
-=head2 Testing Anomalies with Perl on OS/390
-
-The "make test" step runs a Perl Verification Procedure, usually before
-installation. You might encounter STDERR messages even during a successful
-run of "make test". Here is a guide to some of the more commonly seen
-anomalies:
-
-=over 4
-
-=item *
-
-A message of the form:
-
- io/openpid...........CEE5210S The signal SIGHUP was received.
- CEE5210S The signal SIGHUP was received.
- CEE5210S The signal SIGHUP was received.
- ok
-
-indicates that the t/io/openpid.t test of Perl has passed but done so
-with extraneous messages on stderr from CEE.
-
-=item *
-
-A message of the form:
-
- lib/ftmp-security....File::Temp::_gettemp: Parent directory (/tmp/) is not safe
- (sticky bit not set when world writable?) at lib/ftmp-security.t line 100
- File::Temp::_gettemp: Parent directory (/tmp/) is not safe (sticky bit not
- set when world writable?) at lib/ftmp-security.t line 100
- ok
-
-indicates a problem with the permissions on your /tmp directory within the HFS.
-To correct that problem issue the command:
-
- chmod a+t /tmp
-
-from an account with write access to the directory entry for /tmp.
-
-=item *
-
-Out of Memory!
-
-Recent perl test suite is quite memory hungry. In addition to the comments
-above on memory limitations it is also worth checking for _CEE_RUNOPTS
-in your environment. Perl now has (in miniperlmain.c) a C #pragma
-to set CEE run options, but the environment variable wins.
-
-The C code asks for:
-
- #pragma runopts(HEAP(2M,500K,ANYWHERE,KEEP,8K,4K) STACK(,,ANY,) ALL31(ON))
-
-The important parts of that are the second argument (the increment) to HEAP,
-and allowing the stack to be "Above the (16M) line". If the heap
-increment is too small then when perl (for example loading unicode/Name.pl) tries
-to create a "big" (400K+) string it cannot fit in a single segment
-and you get "Out of Memory!" - even if there is still plenty of memory
-available.
-
-A related issue is use with perl's malloc. Perl's malloc uses C<sbrk()>
-to get memory, and C<sbrk()> is limited to the first allocation so in this
-case something like:
-
- HEAP(8M,500K,ANYWHERE,KEEP,8K,4K)
-
-is needed to get through the test suite.
-
-
-=back
-
-=head2 Installation Anomalies with Perl on OS/390
-
-The installman script will try to run on OS/390. There will be fewer errors
-if you have a roff utility installed. You can obtain GNU groff from the
-Redbook SG24-5944-00 ftp site.
-
-=head2 Usage Hints for Perl on OS/390
-
-When using perl on OS/390 please keep in mind that the EBCDIC and ASCII
-character sets are different. See perlebcdic.pod for more on such character
-set issues. Perl builtin functions that may behave differently under
-EBCDIC are also mentioned in the perlport.pod document.
-
-Open Edition (UNIX System Services) from V2R8 onward does support
-#!/path/to/perl script invocation. There is a PTF available from
-IBM for V2R7 that will allow shell/kernel support for #!. USS
-releases prior to V2R7 did not support the #! means of script invocation.
-If you are running V2R6 or earlier then see:
-
- head `whence perldoc`
-
-for an example of how to use the "eval exec" trick to ask the shell to
-have Perl run your scripts on those older releases of Unix System Services.
-
-If you are having trouble with square brackets then consider switching your
-rlogin or telnet client. Try to avoid older 3270 emulators and ISHELL for
-working with Perl on USS.
-
-=head2 Floating Point Anomalies with Perl on OS/390
-
-There appears to be a bug in the floating point implementation on S/390
-systems such that calling int() on the product of a number and a small
-magnitude number is not the same as calling int() on the quotient of
-that number and a large magnitude number. For example, in the following
-Perl code:
-
- my $x = 100000.0;
- my $y = int($x * 1e-5) * 1e5; # '0'
- my $z = int($x / 1e+5) * 1e5; # '100000'
- print "\$y is $y and \$z is $z\n"; # $y is 0 and $z is 100000
-
-Although one would expect the quantities $y and $z to be the same and equal
-to 100000 they will differ and instead will be 0 and 100000 respectively.
-
-The problem can be further examined in a roughly equivalent C program:
-
- #include <stdio.h>
- #include <math.h>
- main()
- {
- double r1,r2;
- double x = 100000.0;
- double y = 0.0;
- double z = 0.0;
- x = 100000.0 * 1e-5;
- r1 = modf (x,&y);
- x = 100000.0 / 1e+5;
- r2 = modf (x,&z);
- printf("y is %e and z is %e\n",y*1e5,z*1e5);
- /* y is 0.000000e+00 and z is 1.000000e+05 (with c89) */
- }
-
-=head2 Modules and Extensions for Perl on OS/390
-
-Pure pure (that is non xs) modules may be installed via the usual:
-
- perl Makefile.PL
- make
- make test
- make install
-
-If you built perl with dynamic loading capability then that would also
-be the way to build xs based extensions. However, if you built perl with
-the default static linking you can still build xs based extensions for OS/390
-but you will need to follow the instructions in ExtUtils::MakeMaker for
-building statically linked perl binaries. In the simplest configurations
-building a static perl + xs extension boils down to:
-
- perl Makefile.PL
- make
- make perl
- make test
- make install
- make -f Makefile.aperl inst_perl MAP_TARGET=perl
-
-In most cases people have reported better results with GNU make rather
-than the system's /bin/make program, whether for plain modules or for
-xs based extensions.
-
-If the make process encounters trouble with either compilation or
-linking then try setting the _C89_CCMODE to 1. Assuming sh is your
-login shell then run:
-
- export _C89_CCMODE=1
-
-If tcsh is your login shell then use the setenv command.
-
-=head1 AUTHORS
-
-David Fiander and Peter Prymmer with thanks to Dennis Longnecker
-and William Raffloer for valuable reports, LPAR and PTF feedback.
-Thanks to Mike MacIsaac and Egon Terwedow for SG24-5944-00.
-Thanks to Ignasi Roca for pointing out the floating point problems.
-Thanks to John Goodyear for dynamic loading help.
-
-=head1 SEE ALSO
-
-L<INSTALL>, L<perlport>, L<perlebcdic>, L<ExtUtils::MakeMaker>.
-
- http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1toy.html
-
- http://www.redbooks.ibm.com/redbooks/SG245944.html
-
- http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1ty1.html#opensrc
-
- http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/
-
- http://publibz.boulder.ibm.com:80/cgi-bin/bookmgr_OS390/BOOKS/ceea3030/
-
- http://publibz.boulder.ibm.com:80/cgi-bin/bookmgr_OS390/BOOKS/CBCUG030/
-
-=head2 Mailing list for Perl on OS/390
-
-If you are interested in the VM/ESA, z/OS (formerly known as OS/390)
-and POSIX-BC (BS2000) ports of Perl then see the perl-mvs mailing list.
-To subscribe, send an empty message to perl-mvs-subscribe@perl.org.
-
-See also:
-
- http://lists.perl.org/list/perl-mvs.html
-
-There are web archives of the mailing list at:
-
- http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/
- http://archive.develooper.com/perl-mvs@perl.org/
-
-=head1 HISTORY
-
-This document was originally written by David Fiander for the 5.005
-release of Perl.
-
-This document was podified for the 5.005_03 release of Perl 11 March 1999.
-
-Updated 28 November 2001 for broken URLs.
-
-Updated 12 November 2000 for the 5.7.1 release of Perl.
-
-Updated 15 January 2001 for the 5.7.1 release of Perl.
-
-Updated 24 January 2001 to mention dynamic loading.
-
-Updated 12 March 2001 to mention //'SYS1.TCPPARMS(TCPDATA)'.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlos400.pod b/Master/tlpkg/tlperl/lib/pods/perlos400.pod
deleted file mode 100644
index e720f2d6e1a..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlos400.pod
+++ /dev/null
@@ -1,120 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you see.
-It is written in the POD format (see pod/perlpod.pod) which is specially
-designed to be readable as is.
-
-=head1 NAME
-
-perlos400 - Perl version 5 on OS/400
-
-=head1 DESCRIPTION
-
-This document describes various features of IBM's OS/400 operating
-system that will affect how Perl version 5 (hereafter just Perl) is
-compiled and/or runs.
-
-By far the easiest way to build Perl for OS/400 is to use the PASE
-(Portable Application Solutions Environment), for more information see
-L<http://www.iseries.ibm.com/developer/factory/pase/index.html>
-This environment allows one to use AIX APIs while programming, and it
-provides a runtime that allows AIX binaries to execute directly on the
-PowerPC iSeries.
-
-=head2 Compiling Perl for OS/400 PASE
-
-The recommended way to build Perl for the OS/400 PASE is to build the
-Perl 5 source code (release 5.8.1 or later) under AIX.
-
-The trick is to give a special parameter to the Configure shell script
-when running it on AIX:
-
- sh Configure -DPASE ...
-
-The default installation directory of Perl under PASE is /QOpenSys/perl.
-This can be modified if needed with Configure parameter -Dprefix=/some/dir.
-
-Starting from OS/400 V5R2 the IBM Visual Age compiler is supported
-on OS/400 PASE, so it is possible to build Perl natively on OS/400.
-The easier way, however, is to compile in AIX, as just described.
-
-If you don't want to install the compiled Perl in AIX into /QOpenSys
-(for packaging it before copying it to PASE), you can use a Configure
-parameter: -Dinstallprefix=/tmp/QOpenSys/perl. This will cause the
-"make install" to install everything into that directory, while the
-installed files still think they are (will be) in /QOpenSys/perl.
-
-If building natively on PASE, please do the build under the /QOpenSys
-directory, since Perl is happier when built on a case sensitive filesystem.
-
-=head2 Installing Perl in OS/400 PASE
-
-If you are compiling on AIX, simply do a "make install" on the AIX box.
-Once the install finishes, tar up the /QOpenSys/perl directory. Transfer
-the tarball to the OS/400 using FTP with the following commands:
-
- > binary
- > site namefmt 1
- > put perl.tar /QOpenSys
-
-Once you have it on, simply bring up a PASE shell and extract the tarball.
-
-If you are compiling in PASE, then "make install" is the only thing you
-will need to do.
-
-The default path for perl binary is /QOpenSys/perl/bin/perl. You'll
-want to symlink /QOpenSys/usr/bin/perl to this file so you don't have
-to modify your path.
-
-=head2 Using Perl in OS/400 PASE
-
-Perl in PASE may be used in the same manner as you would use Perl on AIX.
-
-Scripts starting with #!/usr/bin/perl should work if you have
-/QOpenSys/usr/bin/perl symlinked to your perl binary. This will not
-work if you've done a setuid/setgid or have environment variable
-PASE_EXEC_QOPENSYS="N". If you have V5R1, you'll need to get the
-latest PTFs to have this feature. Scripts starting with
-#!/QOpenSys/perl/bin/perl should always work.
-
-=head2 Known Problems
-
-When compiling in PASE, there is no "oslevel" command. Therefore,
-you may want to create a script called "oslevel" that echoes the
-level of AIX that your version of PASE runtime supports. If you're
-unsure, consult your documentation or use "4.3.3.0".
-
-If you have test cases that fail, check for the existence of spool files.
-The test case may be trying to use a syscall that is not implemented
-in PASE. To avoid the SIGILL, try setting the PASE_SYSCALL_NOSIGILL
-environment variable or have a handler for the SIGILL. If you can
-compile programs for PASE, run the config script and edit config.sh
-when it gives you the option. If you want to remove fchdir(), which
-isn't implement in V5R1, simply change the line that says:
-
-d_fchdir='define'
-
-to
-
-d_fchdir='undef'
-
-and then compile Perl. The places where fchdir() is used have
-alternatives for systems that do not have fchdir() available.
-
-=head2 Perl on ILE
-
-There exists a port of Perl to the ILE environment. This port, however,
-is based quite an old release of Perl, Perl 5.00502 (August 1998).
-(As of July 2002 the latest release of Perl is 5.8.0, and even 5.6.1
-has been out since April 2001.) If you need to run Perl on ILE, though,
-you may need this older port: L<http://www.cpan.org/ports/#os400>
-Note that any Perl release later than 5.00502 has not been ported to ILE.
-
-If you need to use Perl in the ILE environment, you may want to consider
-using Qp2RunPase() to call the PASE version of Perl.
-
-=head1 AUTHORS
-
-Jarkko Hietaniemi <jhi@iki.fi>
-Bryan Logan <bryanlog@us.ibm.com>
-David Larson <larson1@us.ibm.com>
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlpacktut.pod b/Master/tlpkg/tlperl/lib/pods/perlpacktut.pod
deleted file mode 100644
index 2ce56622b75..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlpacktut.pod
+++ /dev/null
@@ -1,1265 +0,0 @@
-=head1 NAME
-
-perlpacktut - tutorial on C<pack> and C<unpack>
-
-=head1 DESCRIPTION
-
-C<pack> and C<unpack> are two functions for transforming data according
-to a user-defined template, between the guarded way Perl stores values
-and some well-defined representation as might be required in the
-environment of a Perl program. Unfortunately, they're also two of
-the most misunderstood and most often overlooked functions that Perl
-provides. This tutorial will demystify them for you.
-
-
-=head1 The Basic Principle
-
-Most programming languages don't shelter the memory where variables are
-stored. In C, for instance, you can take the address of some variable,
-and the C<sizeof> operator tells you how many bytes are allocated to
-the variable. Using the address and the size, you may access the storage
-to your heart's content.
-
-In Perl, you just can't access memory at random, but the structural and
-representational conversion provided by C<pack> and C<unpack> is an
-excellent alternative. The C<pack> function converts values to a byte
-sequence containing representations according to a given specification,
-the so-called "template" argument. C<unpack> is the reverse process,
-deriving some values from the contents of a string of bytes. (Be cautioned,
-however, that not all that has been packed together can be neatly unpacked -
-a very common experience as seasoned travellers are likely to confirm.)
-
-Why, you may ask, would you need a chunk of memory containing some values
-in binary representation? One good reason is input and output accessing
-some file, a device, or a network connection, whereby this binary
-representation is either forced on you or will give you some benefit
-in processing. Another cause is passing data to some system call that
-is not available as a Perl function: C<syscall> requires you to provide
-parameters stored in the way it happens in a C program. Even text processing
-(as shown in the next section) may be simplified with judicious usage
-of these two functions.
-
-To see how (un)packing works, we'll start with a simple template
-code where the conversion is in low gear: between the contents of a byte
-sequence and a string of hexadecimal digits. Let's use C<unpack>, since
-this is likely to remind you of a dump program, or some desperate last
-message unfortunate programs are wont to throw at you before they expire
-into the wild blue yonder. Assuming that the variable C<$mem> holds a
-sequence of bytes that we'd like to inspect without assuming anything
-about its meaning, we can write
-
- my( $hex ) = unpack( 'H*', $mem );
- print "$hex\n";
-
-whereupon we might see something like this, with each pair of hex digits
-corresponding to a byte:
-
- 41204d414e204120504c414e20412043414e414c2050414e414d41
-
-What was in this chunk of memory? Numbers, characters, or a mixture of
-both? Assuming that we're on a computer where ASCII (or some similar)
-encoding is used: hexadecimal values in the range C<0x40> - C<0x5A>
-indicate an uppercase letter, and C<0x20> encodes a space. So we might
-assume it is a piece of text, which some are able to read like a tabloid;
-but others will have to get hold of an ASCII table and relive that
-firstgrader feeling. Not caring too much about which way to read this,
-we note that C<unpack> with the template code C<H> converts the contents
-of a sequence of bytes into the customary hexadecimal notation. Since
-"a sequence of" is a pretty vague indication of quantity, C<H> has been
-defined to convert just a single hexadecimal digit unless it is followed
-by a repeat count. An asterisk for the repeat count means to use whatever
-remains.
-
-The inverse operation - packing byte contents from a string of hexadecimal
-digits - is just as easily written. For instance:
-
- my $s = pack( 'H2' x 10, 30..39 );
- print "$s\n";
-
-Since we feed a list of ten 2-digit hexadecimal strings to C<pack>, the
-pack template should contain ten pack codes. If this is run on a computer
-with ASCII character coding, it will print C<0123456789>.
-
-=head1 Packing Text
-
-Let's suppose you've got to read in a data file like this:
-
- Date |Description | Income|Expenditure
- 01/24/2001 Ahmed's Camel Emporium 1147.99
- 01/28/2001 Flea spray 24.99
- 01/29/2001 Camel rides to tourists 235.00
-
-How do we do it? You might think first to use C<split>; however, since
-C<split> collapses blank fields, you'll never know whether a record was
-income or expenditure. Oops. Well, you could always use C<substr>:
-
- while (<>) {
- my $date = substr($_, 0, 11);
- my $desc = substr($_, 12, 27);
- my $income = substr($_, 40, 7);
- my $expend = substr($_, 52, 7);
- ...
- }
-
-It's not really a barrel of laughs, is it? In fact, it's worse than it
-may seem; the eagle-eyed may notice that the first field should only be
-10 characters wide, and the error has propagated right through the other
-numbers - which we've had to count by hand. So it's error-prone as well
-as horribly unfriendly.
-
-Or maybe we could use regular expressions:
-
- while (<>) {
- my($date, $desc, $income, $expend) =
- m|(\d\d/\d\d/\d{4}) (.{27}) (.{7})(.*)|;
- ...
- }
-
-Urgh. Well, it's a bit better, but - well, would you want to maintain
-that?
-
-Hey, isn't Perl supposed to make this sort of thing easy? Well, it does,
-if you use the right tools. C<pack> and C<unpack> are designed to help
-you out when dealing with fixed-width data like the above. Let's have a
-look at a solution with C<unpack>:
-
- while (<>) {
- my($date, $desc, $income, $expend) = unpack("A10xA27xA7A*", $_);
- ...
- }
-
-That looks a bit nicer; but we've got to take apart that weird template.
-Where did I pull that out of?
-
-OK, let's have a look at some of our data again; in fact, we'll include
-the headers, and a handy ruler so we can keep track of where we are.
-
- 1 2 3 4 5
- 1234567890123456789012345678901234567890123456789012345678
- Date |Description | Income|Expenditure
- 01/28/2001 Flea spray 24.99
- 01/29/2001 Camel rides to tourists 235.00
-
-From this, we can see that the date column stretches from column 1 to
-column 10 - ten characters wide. The C<pack>-ese for "character" is
-C<A>, and ten of them are C<A10>. So if we just wanted to extract the
-dates, we could say this:
-
- my($date) = unpack("A10", $_);
-
-OK, what's next? Between the date and the description is a blank column;
-we want to skip over that. The C<x> template means "skip forward", so we
-want one of those. Next, we have another batch of characters, from 12 to
-38. That's 27 more characters, hence C<A27>. (Don't make the fencepost
-error - there are 27 characters between 12 and 38, not 26. Count 'em!)
-
-Now we skip another character and pick up the next 7 characters:
-
- my($date,$description,$income) = unpack("A10xA27xA7", $_);
-
-Now comes the clever bit. Lines in our ledger which are just income and
-not expenditure might end at column 46. Hence, we don't want to tell our
-C<unpack> pattern that we B<need> to find another 12 characters; we'll
-just say "if there's anything left, take it". As you might guess from
-regular expressions, that's what the C<*> means: "use everything
-remaining".
-
-=over 3
-
-=item *
-
-Be warned, though, that unlike regular expressions, if the C<unpack>
-template doesn't match the incoming data, Perl will scream and die.
-
-=back
-
-
-Hence, putting it all together:
-
- my($date,$description,$income,$expend) = unpack("A10xA27xA7xA*", $_);
-
-Now, that's our data parsed. I suppose what we might want to do now is
-total up our income and expenditure, and add another line to the end of
-our ledger - in the same format - saying how much we've brought in and
-how much we've spent:
-
- while (<>) {
- my($date, $desc, $income, $expend) = unpack("A10xA27xA7xA*", $_);
- $tot_income += $income;
- $tot_expend += $expend;
- }
-
- $tot_income = sprintf("%.2f", $tot_income); # Get them into
- $tot_expend = sprintf("%.2f", $tot_expend); # "financial" format
-
- $date = POSIX::strftime("%m/%d/%Y", localtime);
-
- # OK, let's go:
-
- print pack("A10xA27xA7xA*", $date, "Totals", $tot_income, $tot_expend);
-
-Oh, hmm. That didn't quite work. Let's see what happened:
-
- 01/24/2001 Ahmed's Camel Emporium 1147.99
- 01/28/2001 Flea spray 24.99
- 01/29/2001 Camel rides to tourists 1235.00
- 03/23/2001Totals 1235.001172.98
-
-OK, it's a start, but what happened to the spaces? We put C<x>, didn't
-we? Shouldn't it skip forward? Let's look at what L<perlfunc/pack> says:
-
- x A null byte.
-
-Urgh. No wonder. There's a big difference between "a null byte",
-character zero, and "a space", character 32. Perl's put something
-between the date and the description - but unfortunately, we can't see
-it!
-
-What we actually need to do is expand the width of the fields. The C<A>
-format pads any non-existent characters with spaces, so we can use the
-additional spaces to line up our fields, like this:
-
- print pack("A11 A28 A8 A*", $date, "Totals", $tot_income, $tot_expend);
-
-(Note that you can put spaces in the template to make it more readable,
-but they don't translate to spaces in the output.) Here's what we got
-this time:
-
- 01/24/2001 Ahmed's Camel Emporium 1147.99
- 01/28/2001 Flea spray 24.99
- 01/29/2001 Camel rides to tourists 1235.00
- 03/23/2001 Totals 1235.00 1172.98
-
-That's a bit better, but we still have that last column which needs to
-be moved further over. There's an easy way to fix this up:
-unfortunately, we can't get C<pack> to right-justify our fields, but we
-can get C<sprintf> to do it:
-
- $tot_income = sprintf("%.2f", $tot_income);
- $tot_expend = sprintf("%12.2f", $tot_expend);
- $date = POSIX::strftime("%m/%d/%Y", localtime);
- print pack("A11 A28 A8 A*", $date, "Totals", $tot_income, $tot_expend);
-
-This time we get the right answer:
-
- 01/28/2001 Flea spray 24.99
- 01/29/2001 Camel rides to tourists 1235.00
- 03/23/2001 Totals 1235.00 1172.98
-
-So that's how we consume and produce fixed-width data. Let's recap what
-we've seen of C<pack> and C<unpack> so far:
-
-=over 3
-
-=item *
-
-Use C<pack> to go from several pieces of data to one fixed-width
-version; use C<unpack> to turn a fixed-width-format string into several
-pieces of data.
-
-=item *
-
-The pack format C<A> means "any character"; if you're C<pack>ing and
-you've run out of things to pack, C<pack> will fill the rest up with
-spaces.
-
-=item *
-
-C<x> means "skip a byte" when C<unpack>ing; when C<pack>ing, it means
-"introduce a null byte" - that's probably not what you mean if you're
-dealing with plain text.
-
-=item *
-
-You can follow the formats with numbers to say how many characters
-should be affected by that format: C<A12> means "take 12 characters";
-C<x6> means "skip 6 bytes" or "character 0, 6 times".
-
-=item *
-
-Instead of a number, you can use C<*> to mean "consume everything else
-left".
-
-B<Warning>: when packing multiple pieces of data, C<*> only means
-"consume all of the current piece of data". That's to say
-
- pack("A*A*", $one, $two)
-
-packs all of C<$one> into the first C<A*> and then all of C<$two> into
-the second. This is a general principle: each format character
-corresponds to one piece of data to be C<pack>ed.
-
-=back
-
-
-
-=head1 Packing Numbers
-
-So much for textual data. Let's get onto the meaty stuff that C<pack>
-and C<unpack> are best at: handling binary formats for numbers. There is,
-of course, not just one binary format - life would be too simple - but
-Perl will do all the finicky labor for you.
-
-
-=head2 Integers
-
-Packing and unpacking numbers implies conversion to and from some
-I<specific> binary representation. Leaving floating point numbers
-aside for the moment, the salient properties of any such representation
-are:
-
-=over 4
-
-=item *
-
-the number of bytes used for storing the integer,
-
-=item *
-
-whether the contents are interpreted as a signed or unsigned number,
-
-=item *
-
-the byte ordering: whether the first byte is the least or most
-significant byte (or: little-endian or big-endian, respectively).
-
-=back
-
-So, for instance, to pack 20302 to a signed 16 bit integer in your
-computer's representation you write
-
- my $ps = pack( 's', 20302 );
-
-Again, the result is a string, now containing 2 bytes. If you print
-this string (which is, generally, not recommended) you might see
-C<ON> or C<NO> (depending on your system's byte ordering) - or something
-entirely different if your computer doesn't use ASCII character encoding.
-Unpacking C<$ps> with the same template returns the original integer value:
-
- my( $s ) = unpack( 's', $ps );
-
-This is true for all numeric template codes. But don't expect miracles:
-if the packed value exceeds the allotted byte capacity, high order bits
-are silently discarded, and unpack certainly won't be able to pull them
-back out of some magic hat. And, when you pack using a signed template
-code such as C<s>, an excess value may result in the sign bit
-getting set, and unpacking this will smartly return a negative value.
-
-16 bits won't get you too far with integers, but there is C<l> and C<L>
-for signed and unsigned 32-bit integers. And if this is not enough and
-your system supports 64 bit integers you can push the limits much closer
-to infinity with pack codes C<q> and C<Q>. A notable exception is provided
-by pack codes C<i> and C<I> for signed and unsigned integers of the
-"local custom" variety: Such an integer will take up as many bytes as
-a local C compiler returns for C<sizeof(int)>, but it'll use I<at least>
-32 bits.
-
-Each of the integer pack codes C<sSlLqQ> results in a fixed number of bytes,
-no matter where you execute your program. This may be useful for some
-applications, but it does not provide for a portable way to pass data
-structures between Perl and C programs (bound to happen when you call
-XS extensions or the Perl function C<syscall>), or when you read or
-write binary files. What you'll need in this case are template codes that
-depend on what your local C compiler compiles when you code C<short> or
-C<unsigned long>, for instance. These codes and their corresponding
-byte lengths are shown in the table below. Since the C standard leaves
-much leeway with respect to the relative sizes of these data types, actual
-values may vary, and that's why the values are given as expressions in
-C and Perl. (If you'd like to use values from C<%Config> in your program
-you have to import it with C<use Config>.)
-
- signed unsigned byte length in C byte length in Perl
- s! S! sizeof(short) $Config{shortsize}
- i! I! sizeof(int) $Config{intsize}
- l! L! sizeof(long) $Config{longsize}
- q! Q! sizeof(long long) $Config{longlongsize}
-
-The C<i!> and C<I!> codes aren't different from C<i> and C<I>; they are
-tolerated for completeness' sake.
-
-
-=head2 Unpacking a Stack Frame
-
-Requesting a particular byte ordering may be necessary when you work with
-binary data coming from some specific architecture whereas your program could
-run on a totally different system. As an example, assume you have 24 bytes
-containing a stack frame as it happens on an Intel 8086:
-
- +---------+ +----+----+ +---------+
- TOS: | IP | TOS+4:| FL | FH | FLAGS TOS+14:| SI |
- +---------+ +----+----+ +---------+
- | CS | | AL | AH | AX | DI |
- +---------+ +----+----+ +---------+
- | BL | BH | BX | BP |
- +----+----+ +---------+
- | CL | CH | CX | DS |
- +----+----+ +---------+
- | DL | DH | DX | ES |
- +----+----+ +---------+
-
-First, we note that this time-honored 16-bit CPU uses little-endian order,
-and that's why the low order byte is stored at the lower address. To
-unpack such a (unsigned) short we'll have to use code C<v>. A repeat
-count unpacks all 12 shorts:
-
- my( $ip, $cs, $flags, $ax, $bx, $cd, $dx, $si, $di, $bp, $ds, $es ) =
- unpack( 'v12', $frame );
-
-Alternatively, we could have used C<C> to unpack the individually
-accessible byte registers FL, FH, AL, AH, etc.:
-
- my( $fl, $fh, $al, $ah, $bl, $bh, $cl, $ch, $dl, $dh ) =
- unpack( 'C10', substr( $frame, 4, 10 ) );
-
-It would be nice if we could do this in one fell swoop: unpack a short,
-back up a little, and then unpack 2 bytes. Since Perl I<is> nice, it
-proffers the template code C<X> to back up one byte. Putting this all
-together, we may now write:
-
- my( $ip, $cs,
- $flags,$fl,$fh,
- $ax,$al,$ah, $bx,$bl,$bh, $cx,$cl,$ch, $dx,$dl,$dh,
- $si, $di, $bp, $ds, $es ) =
- unpack( 'v2' . ('vXXCC' x 5) . 'v5', $frame );
-
-(The clumsy construction of the template can be avoided - just read on!)
-
-We've taken some pains to construct the template so that it matches
-the contents of our frame buffer. Otherwise we'd either get undefined values,
-or C<unpack> could not unpack all. If C<pack> runs out of items, it will
-supply null strings (which are coerced into zeroes whenever the pack code
-says so).
-
-
-=head2 How to Eat an Egg on a Net
-
-The pack code for big-endian (high order byte at the lowest address) is
-C<n> for 16 bit and C<N> for 32 bit integers. You use these codes
-if you know that your data comes from a compliant architecture, but,
-surprisingly enough, you should also use these pack codes if you
-exchange binary data, across the network, with some system that you
-know next to nothing about. The simple reason is that this
-order has been chosen as the I<network order>, and all standard-fearing
-programs ought to follow this convention. (This is, of course, a stern
-backing for one of the Lilliputian parties and may well influence the
-political development there.) So, if the protocol expects you to send
-a message by sending the length first, followed by just so many bytes,
-you could write:
-
- my $buf = pack( 'N', length( $msg ) ) . $msg;
-
-or even:
-
- my $buf = pack( 'NA*', length( $msg ), $msg );
-
-and pass C<$buf> to your send routine. Some protocols demand that the
-count should include the length of the count itself: then just add 4
-to the data length. (But make sure to read L<"Lengths and Widths"> before
-you really code this!)
-
-
-=head2 Byte-order modifiers
-
-In the previous sections we've learned how to use C<n>, C<N>, C<v> and
-C<V> to pack and unpack integers with big- or little-endian byte-order.
-While this is nice, it's still rather limited because it leaves out all
-kinds of signed integers as well as 64-bit integers. For example, if you
-wanted to unpack a sequence of signed big-endian 16-bit integers in a
-platform-independent way, you would have to write:
-
- my @data = unpack 's*', pack 'S*', unpack 'n*', $buf;
-
-This is ugly. As of Perl 5.9.2, there's a much nicer way to express your
-desire for a certain byte-order: the C<E<gt>> and C<E<lt>> modifiers.
-C<E<gt>> is the big-endian modifier, while C<E<lt>> is the little-endian
-modifier. Using them, we could rewrite the above code as:
-
- my @data = unpack 's>*', $buf;
-
-As you can see, the "big end" of the arrow touches the C<s>, which is a
-nice way to remember that C<E<gt>> is the big-endian modifier. The same
-obviously works for C<E<lt>>, where the "little end" touches the code.
-
-You will probably find these modifiers even more useful if you have
-to deal with big- or little-endian C structures. Be sure to read
-L<"Packing and Unpacking C Structures"> for more on that.
-
-
-=head2 Floating point Numbers
-
-For packing floating point numbers you have the choice between the
-pack codes C<f>, C<d>, C<F> and C<D>. C<f> and C<d> pack into (or unpack
-from) single-precision or double-precision representation as it is provided
-by your system. If your systems supports it, C<D> can be used to pack and
-unpack extended-precision floating point values (C<long double>), which
-can offer even more resolution than C<f> or C<d>. C<F> packs an C<NV>,
-which is the floating point type used by Perl internally. (There
-is no such thing as a network representation for reals, so if you want
-to send your real numbers across computer boundaries, you'd better stick
-to ASCII representation, unless you're absolutely sure what's on the other
-end of the line. For the even more adventuresome, you can use the byte-order
-modifiers from the previous section also on floating point codes.)
-
-
-
-=head1 Exotic Templates
-
-
-=head2 Bit Strings
-
-Bits are the atoms in the memory world. Access to individual bits may
-have to be used either as a last resort or because it is the most
-convenient way to handle your data. Bit string (un)packing converts
-between strings containing a series of C<0> and C<1> characters and
-a sequence of bytes each containing a group of 8 bits. This is almost
-as simple as it sounds, except that there are two ways the contents of
-a byte may be written as a bit string. Let's have a look at an annotated
-byte:
-
- 7 6 5 4 3 2 1 0
- +-----------------+
- | 1 0 0 0 1 1 0 0 |
- +-----------------+
- MSB LSB
-
-It's egg-eating all over again: Some think that as a bit string this should
-be written "10001100" i.e. beginning with the most significant bit, others
-insist on "00110001". Well, Perl isn't biased, so that's why we have two bit
-string codes:
-
- $byte = pack( 'B8', '10001100' ); # start with MSB
- $byte = pack( 'b8', '00110001' ); # start with LSB
-
-It is not possible to pack or unpack bit fields - just integral bytes.
-C<pack> always starts at the next byte boundary and "rounds up" to the
-next multiple of 8 by adding zero bits as required. (If you do want bit
-fields, there is L<perlfunc/vec>. Or you could implement bit field
-handling at the character string level, using split, substr, and
-concatenation on unpacked bit strings.)
-
-To illustrate unpacking for bit strings, we'll decompose a simple
-status register (a "-" stands for a "reserved" bit):
-
- +-----------------+-----------------+
- | S Z - A - P - C | - - - - O D I T |
- +-----------------+-----------------+
- MSB LSB MSB LSB
-
-Converting these two bytes to a string can be done with the unpack
-template C<'b16'>. To obtain the individual bit values from the bit
-string we use C<split> with the "empty" separator pattern which dissects
-into individual characters. Bit values from the "reserved" positions are
-simply assigned to C<undef>, a convenient notation for "I don't care where
-this goes".
-
- ($carry, undef, $parity, undef, $auxcarry, undef, $zero, $sign,
- $trace, $interrupt, $direction, $overflow) =
- split( //, unpack( 'b16', $status ) );
-
-We could have used an unpack template C<'b12'> just as well, since the
-last 4 bits can be ignored anyway.
-
-
-=head2 Uuencoding
-
-Another odd-man-out in the template alphabet is C<u>, which packs an
-"uuencoded string". ("uu" is short for Unix-to-Unix.) Chances are that
-you won't ever need this encoding technique which was invented to overcome
-the shortcomings of old-fashioned transmission mediums that do not support
-other than simple ASCII data. The essential recipe is simple: Take three
-bytes, or 24 bits. Split them into 4 six-packs, adding a space (0x20) to
-each. Repeat until all of the data is blended. Fold groups of 4 bytes into
-lines no longer than 60 and garnish them in front with the original byte count
-(incremented by 0x20) and a C<"\n"> at the end. - The C<pack> chef will
-prepare this for you, a la minute, when you select pack code C<u> on the menu:
-
- my $uubuf = pack( 'u', $bindat );
-
-A repeat count after C<u> sets the number of bytes to put into an
-uuencoded line, which is the maximum of 45 by default, but could be
-set to some (smaller) integer multiple of three. C<unpack> simply ignores
-the repeat count.
-
-
-=head2 Doing Sums
-
-An even stranger template code is C<%>E<lt>I<number>E<gt>. First, because
-it's used as a prefix to some other template code. Second, because it
-cannot be used in C<pack> at all, and third, in C<unpack>, doesn't return the
-data as defined by the template code it precedes. Instead it'll give you an
-integer of I<number> bits that is computed from the data value by
-doing sums. For numeric unpack codes, no big feat is achieved:
-
- my $buf = pack( 'iii', 100, 20, 3 );
- print unpack( '%32i3', $buf ), "\n"; # prints 123
-
-For string values, C<%> returns the sum of the byte values saving
-you the trouble of a sum loop with C<substr> and C<ord>:
-
- print unpack( '%32A*', "\x01\x10" ), "\n"; # prints 17
-
-Although the C<%> code is documented as returning a "checksum":
-don't put your trust in such values! Even when applied to a small number
-of bytes, they won't guarantee a noticeable Hamming distance.
-
-In connection with C<b> or C<B>, C<%> simply adds bits, and this can be put
-to good use to count set bits efficiently:
-
- my $bitcount = unpack( '%32b*', $mask );
-
-And an even parity bit can be determined like this:
-
- my $evenparity = unpack( '%1b*', $mask );
-
-
-=head2 Unicode
-
-Unicode is a character set that can represent most characters in most of
-the world's languages, providing room for over one million different
-characters. Unicode 3.1 specifies 94,140 characters: The Basic Latin
-characters are assigned to the numbers 0 - 127. The Latin-1 Supplement with
-characters that are used in several European languages is in the next
-range, up to 255. After some more Latin extensions we find the character
-sets from languages using non-Roman alphabets, interspersed with a
-variety of symbol sets such as currency symbols, Zapf Dingbats or Braille.
-(You might want to visit L<http://www.unicode.org/> for a look at some of
-them - my personal favourites are Telugu and Kannada.)
-
-The Unicode character sets associates characters with integers. Encoding
-these numbers in an equal number of bytes would more than double the
-requirements for storing texts written in Latin alphabets.
-The UTF-8 encoding avoids this by storing the most common (from a western
-point of view) characters in a single byte while encoding the rarer
-ones in three or more bytes.
-
-Perl uses UTF-8, internally, for most Unicode strings.
-
-So what has this got to do with C<pack>? Well, if you want to compose a
-Unicode string (that is internally encoded as UTF-8), you can do so by
-using template code C<U>. As an example, let's produce the Euro currency
-symbol (code number 0x20AC):
-
- $UTF8{Euro} = pack( 'U', 0x20AC );
- # Equivalent to: $UTF8{Euro} = "\x{20ac}";
-
-Inspecting C<$UTF8{Euro}> shows that it contains 3 bytes:
-"\xe2\x82\xac". However, it contains only 1 character, number 0x20AC.
-The round trip can be completed with C<unpack>:
-
- $Unicode{Euro} = unpack( 'U', $UTF8{Euro} );
-
-Unpacking using the C<U> template code also works on UTF-8 encoded byte
-strings.
-
-Usually you'll want to pack or unpack UTF-8 strings:
-
- # pack and unpack the Hebrew alphabet
- my $alefbet = pack( 'U*', 0x05d0..0x05ea );
- my @hebrew = unpack( 'U*', $utf );
-
-Please note: in the general case, you're better off using
-Encode::decode_utf8 to decode a UTF-8 encoded byte string to a Perl
-Unicode string, and Encode::encode_utf8 to encode a Perl Unicode string
-to UTF-8 bytes. These functions provide means of handling invalid byte
-sequences and generally have a friendlier interface.
-
-=head2 Another Portable Binary Encoding
-
-The pack code C<w> has been added to support a portable binary data
-encoding scheme that goes way beyond simple integers. (Details can
-be found at L<http://Casbah.org/>, the Scarab project.) A BER (Binary Encoded
-Representation) compressed unsigned integer stores base 128
-digits, most significant digit first, with as few digits as possible.
-Bit eight (the high bit) is set on each byte except the last. There
-is no size limit to BER encoding, but Perl won't go to extremes.
-
- my $berbuf = pack( 'w*', 1, 128, 128+1, 128*128+127 );
-
-A hex dump of C<$berbuf>, with spaces inserted at the right places,
-shows 01 8100 8101 81807F. Since the last byte is always less than
-128, C<unpack> knows where to stop.
-
-
-=head1 Template Grouping
-
-Prior to Perl 5.8, repetitions of templates had to be made by
-C<x>-multiplication of template strings. Now there is a better way as
-we may use the pack codes C<(> and C<)> combined with a repeat count.
-The C<unpack> template from the Stack Frame example can simply
-be written like this:
-
- unpack( 'v2 (vXXCC)5 v5', $frame )
-
-Let's explore this feature a little more. We'll begin with the equivalent of
-
- join( '', map( substr( $_, 0, 1 ), @str ) )
-
-which returns a string consisting of the first character from each string.
-Using pack, we can write
-
- pack( '(A)'.@str, @str )
-
-or, because a repeat count C<*> means "repeat as often as required",
-simply
-
- pack( '(A)*', @str )
-
-(Note that the template C<A*> would only have packed C<$str[0]> in full
-length.)
-
-To pack dates stored as triplets ( day, month, year ) in an array C<@dates>
-into a sequence of byte, byte, short integer we can write
-
- $pd = pack( '(CCS)*', map( @$_, @dates ) );
-
-To swap pairs of characters in a string (with even length) one could use
-several techniques. First, let's use C<x> and C<X> to skip forward and back:
-
- $s = pack( '(A)*', unpack( '(xAXXAx)*', $s ) );
-
-We can also use C<@> to jump to an offset, with 0 being the position where
-we were when the last C<(> was encountered:
-
- $s = pack( '(A)*', unpack( '(@1A @0A @2)*', $s ) );
-
-Finally, there is also an entirely different approach by unpacking big
-endian shorts and packing them in the reverse byte order:
-
- $s = pack( '(v)*', unpack( '(n)*', $s );
-
-
-=head1 Lengths and Widths
-
-=head2 String Lengths
-
-In the previous section we've seen a network message that was constructed
-by prefixing the binary message length to the actual message. You'll find
-that packing a length followed by so many bytes of data is a
-frequently used recipe since appending a null byte won't work
-if a null byte may be part of the data. Here is an example where both
-techniques are used: after two null terminated strings with source and
-destination address, a Short Message (to a mobile phone) is sent after
-a length byte:
-
- my $msg = pack( 'Z*Z*CA*', $src, $dst, length( $sm ), $sm );
-
-Unpacking this message can be done with the same template:
-
- ( $src, $dst, $len, $sm ) = unpack( 'Z*Z*CA*', $msg );
-
-There's a subtle trap lurking in the offing: Adding another field after
-the Short Message (in variable C<$sm>) is all right when packing, but this
-cannot be unpacked naively:
-
- # pack a message
- my $msg = pack( 'Z*Z*CA*C', $src, $dst, length( $sm ), $sm, $prio );
-
- # unpack fails - $prio remains undefined!
- ( $src, $dst, $len, $sm, $prio ) = unpack( 'Z*Z*CA*C', $msg );
-
-The pack code C<A*> gobbles up all remaining bytes, and C<$prio> remains
-undefined! Before we let disappointment dampen the morale: Perl's got
-the trump card to make this trick too, just a little further up the sleeve.
-Watch this:
-
- # pack a message: ASCIIZ, ASCIIZ, length/string, byte
- my $msg = pack( 'Z* Z* C/A* C', $src, $dst, $sm, $prio );
-
- # unpack
- ( $src, $dst, $sm, $prio ) = unpack( 'Z* Z* C/A* C', $msg );
-
-Combining two pack codes with a slash (C</>) associates them with a single
-value from the argument list. In C<pack>, the length of the argument is
-taken and packed according to the first code while the argument itself
-is added after being converted with the template code after the slash.
-This saves us the trouble of inserting the C<length> call, but it is
-in C<unpack> where we really score: The value of the length byte marks the
-end of the string to be taken from the buffer. Since this combination
-doesn't make sense except when the second pack code isn't C<a*>, C<A*>
-or C<Z*>, Perl won't let you.
-
-The pack code preceding C</> may be anything that's fit to represent a
-number: All the numeric binary pack codes, and even text codes such as
-C<A4> or C<Z*>:
-
- # pack/unpack a string preceded by its length in ASCII
- my $buf = pack( 'A4/A*', "Humpty-Dumpty" );
- # unpack $buf: '13 Humpty-Dumpty'
- my $txt = unpack( 'A4/A*', $buf );
-
-C</> is not implemented in Perls before 5.6, so if your code is required to
-work on older Perls you'll need to C<unpack( 'Z* Z* C')> to get the length,
-then use it to make a new unpack string. For example
-
- # pack a message: ASCIIZ, ASCIIZ, length, string, byte (5.005 compatible)
- my $msg = pack( 'Z* Z* C A* C', $src, $dst, length $sm, $sm, $prio );
-
- # unpack
- ( undef, undef, $len) = unpack( 'Z* Z* C', $msg );
- ($src, $dst, $sm, $prio) = unpack ( "Z* Z* x A$len C", $msg );
-
-But that second C<unpack> is rushing ahead. It isn't using a simple literal
-string for the template. So maybe we should introduce...
-
-=head2 Dynamic Templates
-
-So far, we've seen literals used as templates. If the list of pack
-items doesn't have fixed length, an expression constructing the
-template is required (whenever, for some reason, C<()*> cannot be used).
-Here's an example: To store named string values in a way that can be
-conveniently parsed by a C program, we create a sequence of names and
-null terminated ASCII strings, with C<=> between the name and the value,
-followed by an additional delimiting null byte. Here's how:
-
- my $env = pack( '(A*A*Z*)' . keys( %Env ) . 'C',
- map( { ( $_, '=', $Env{$_} ) } keys( %Env ) ), 0 );
-
-Let's examine the cogs of this byte mill, one by one. There's the C<map>
-call, creating the items we intend to stuff into the C<$env> buffer:
-to each key (in C<$_>) it adds the C<=> separator and the hash entry value.
-Each triplet is packed with the template code sequence C<A*A*Z*> that
-is repeated according to the number of keys. (Yes, that's what the C<keys>
-function returns in scalar context.) To get the very last null byte,
-we add a C<0> at the end of the C<pack> list, to be packed with C<C>.
-(Attentive readers may have noticed that we could have omitted the 0.)
-
-For the reverse operation, we'll have to determine the number of items
-in the buffer before we can let C<unpack> rip it apart:
-
- my $n = $env =~ tr/\0// - 1;
- my %env = map( split( /=/, $_ ), unpack( "(Z*)$n", $env ) );
-
-The C<tr> counts the null bytes. The C<unpack> call returns a list of
-name-value pairs each of which is taken apart in the C<map> block.
-
-
-=head2 Counting Repetitions
-
-Rather than storing a sentinel at the end of a data item (or a list of items),
-we could precede the data with a count. Again, we pack keys and values of
-a hash, preceding each with an unsigned short length count, and up front
-we store the number of pairs:
-
- my $env = pack( 'S(S/A* S/A*)*', scalar keys( %Env ), %Env );
-
-This simplifies the reverse operation as the number of repetitions can be
-unpacked with the C</> code:
-
- my %env = unpack( 'S/(S/A* S/A*)', $env );
-
-Note that this is one of the rare cases where you cannot use the same
-template for C<pack> and C<unpack> because C<pack> can't determine
-a repeat count for a C<()>-group.
-
-
-=head2 Intel HEX
-
-Intel HEX is a file format for representing binary data, mostly for
-programming various chips, as a text file. (See
-L<http://en.wikipedia.org/wiki/.hex> for a detailed description, and
-L<http://en.wikipedia.org/wiki/SREC_(file_format)> for the Motorola
-S-record format, which can be unravelled using the same technique.)
-Each line begins with a colon (':') and is followed by a sequence of
-hexadecimal characters, specifying a byte count I<n> (8 bit),
-an address (16 bit, big endian), a record type (8 bit), I<n> data bytes
-and a checksum (8 bit) computed as the least significant byte of the two's
-complement sum of the preceding bytes. Example: C<:0300300002337A1E>.
-
-The first step of processing such a line is the conversion, to binary,
-of the hexadecimal data, to obtain the four fields, while checking the
-checksum. No surprise here: we'll start with a simple C<pack> call to
-convert everything to binary:
-
- my $binrec = pack( 'H*', substr( $hexrec, 1 ) );
-
-The resulting byte sequence is most convenient for checking the checksum.
-Don't slow your program down with a for loop adding the C<ord> values
-of this string's bytes - the C<unpack> code C<%> is the thing to use
-for computing the 8-bit sum of all bytes, which must be equal to zero:
-
- die unless unpack( "%8C*", $binrec ) == 0;
-
-Finally, let's get those four fields. By now, you shouldn't have any
-problems with the first three fields - but how can we use the byte count
-of the data in the first field as a length for the data field? Here
-the codes C<x> and C<X> come to the rescue, as they permit jumping
-back and forth in the string to unpack.
-
- my( $addr, $type, $data ) = unpack( "x n C X4 C x3 /a", $bin );
-
-Code C<x> skips a byte, since we don't need the count yet. Code C<n> takes
-care of the 16-bit big-endian integer address, and C<C> unpacks the
-record type. Being at offset 4, where the data begins, we need the count.
-C<X4> brings us back to square one, which is the byte at offset 0.
-Now we pick up the count, and zoom forth to offset 4, where we are
-now fully furnished to extract the exact number of data bytes, leaving
-the trailing checksum byte alone.
-
-
-
-=head1 Packing and Unpacking C Structures
-
-In previous sections we have seen how to pack numbers and character
-strings. If it were not for a couple of snags we could conclude this
-section right away with the terse remark that C structures don't
-contain anything else, and therefore you already know all there is to it.
-Sorry, no: read on, please.
-
-If you have to deal with a lot of C structures, and don't want to
-hack all your template strings manually, you'll probably want to have
-a look at the CPAN module C<Convert::Binary::C>. Not only can it parse
-your C source directly, but it also has built-in support for all the
-odds and ends described further on in this section.
-
-=head2 The Alignment Pit
-
-In the consideration of speed against memory requirements the balance
-has been tilted in favor of faster execution. This has influenced the
-way C compilers allocate memory for structures: On architectures
-where a 16-bit or 32-bit operand can be moved faster between places in
-memory, or to or from a CPU register, if it is aligned at an even or
-multiple-of-four or even at a multiple-of eight address, a C compiler
-will give you this speed benefit by stuffing extra bytes into structures.
-If you don't cross the C shoreline this is not likely to cause you any
-grief (although you should care when you design large data structures,
-or you want your code to be portable between architectures (you do want
-that, don't you?)).
-
-To see how this affects C<pack> and C<unpack>, we'll compare these two
-C structures:
-
- typedef struct {
- char c1;
- short s;
- char c2;
- long l;
- } gappy_t;
-
- typedef struct {
- long l;
- short s;
- char c1;
- char c2;
- } dense_t;
-
-Typically, a C compiler allocates 12 bytes to a C<gappy_t> variable, but
-requires only 8 bytes for a C<dense_t>. After investigating this further,
-we can draw memory maps, showing where the extra 4 bytes are hidden:
-
- 0 +4 +8 +12
- +--+--+--+--+--+--+--+--+--+--+--+--+
- |c1|xx| s |c2|xx|xx|xx| l | xx = fill byte
- +--+--+--+--+--+--+--+--+--+--+--+--+
- gappy_t
-
- 0 +4 +8
- +--+--+--+--+--+--+--+--+
- | l | h |c1|c2|
- +--+--+--+--+--+--+--+--+
- dense_t
-
-And that's where the first quirk strikes: C<pack> and C<unpack>
-templates have to be stuffed with C<x> codes to get those extra fill bytes.
-
-The natural question: "Why can't Perl compensate for the gaps?" warrants
-an answer. One good reason is that C compilers might provide (non-ANSI)
-extensions permitting all sorts of fancy control over the way structures
-are aligned, even at the level of an individual structure field. And, if
-this were not enough, there is an insidious thing called C<union> where
-the amount of fill bytes cannot be derived from the alignment of the next
-item alone.
-
-OK, so let's bite the bullet. Here's one way to get the alignment right
-by inserting template codes C<x>, which don't take a corresponding item
-from the list:
-
- my $gappy = pack( 'cxs cxxx l!', $c1, $s, $c2, $l );
-
-Note the C<!> after C<l>: We want to make sure that we pack a long
-integer as it is compiled by our C compiler. And even now, it will only
-work for the platforms where the compiler aligns things as above.
-And somebody somewhere has a platform where it doesn't.
-[Probably a Cray, where C<short>s, C<int>s and C<long>s are all 8 bytes. :-)]
-
-Counting bytes and watching alignments in lengthy structures is bound to
-be a drag. Isn't there a way we can create the template with a simple
-program? Here's a C program that does the trick:
-
- #include <stdio.h>
- #include <stddef.h>
-
- typedef struct {
- char fc1;
- short fs;
- char fc2;
- long fl;
- } gappy_t;
-
- #define Pt(struct,field,tchar) \
- printf( "@%d%s ", offsetof(struct,field), # tchar );
-
- int main() {
- Pt( gappy_t, fc1, c );
- Pt( gappy_t, fs, s! );
- Pt( gappy_t, fc2, c );
- Pt( gappy_t, fl, l! );
- printf( "\n" );
- }
-
-The output line can be used as a template in a C<pack> or C<unpack> call:
-
- my $gappy = pack( '@0c @2s! @4c @8l!', $c1, $s, $c2, $l );
-
-Gee, yet another template code - as if we hadn't plenty. But
-C<@> saves our day by enabling us to specify the offset from the beginning
-of the pack buffer to the next item: This is just the value
-the C<offsetof> macro (defined in C<E<lt>stddef.hE<gt>>) returns when
-given a C<struct> type and one of its field names ("member-designator" in
-C standardese).
-
-Neither using offsets nor adding C<x>'s to bridge the gaps is satisfactory.
-(Just imagine what happens if the structure changes.) What we really need
-is a way of saying "skip as many bytes as required to the next multiple of N".
-In fluent Templatese, you say this with C<x!N> where N is replaced by the
-appropriate value. Here's the next version of our struct packaging:
-
- my $gappy = pack( 'c x!2 s c x!4 l!', $c1, $s, $c2, $l );
-
-That's certainly better, but we still have to know how long all the
-integers are, and portability is far away. Rather than C<2>,
-for instance, we want to say "however long a short is". But this can be
-done by enclosing the appropriate pack code in brackets: C<[s]>. So, here's
-the very best we can do:
-
- my $gappy = pack( 'c x![s] s c x![l!] l!', $c1, $s, $c2, $l );
-
-
-=head2 Dealing with Endian-ness
-
-Now, imagine that we want to pack the data for a machine with a
-different byte-order. First, we'll have to figure out how big the data
-types on the target machine really are. Let's assume that the longs are
-32 bits wide and the shorts are 16 bits wide. You can then rewrite the
-template as:
-
- my $gappy = pack( 'c x![s] s c x![l] l', $c1, $s, $c2, $l );
-
-If the target machine is little-endian, we could write:
-
- my $gappy = pack( 'c x![s] s< c x![l] l<', $c1, $s, $c2, $l );
-
-This forces the short and the long members to be little-endian, and is
-just fine if you don't have too many struct members. But we could also
-use the byte-order modifier on a group and write the following:
-
- my $gappy = pack( '( c x![s] s c x![l] l )<', $c1, $s, $c2, $l );
-
-This is not as short as before, but it makes it more obvious that we
-intend to have little-endian byte-order for a whole group, not only
-for individual template codes. It can also be more readable and easier
-to maintain.
-
-
-=head2 Alignment, Take 2
-
-I'm afraid that we're not quite through with the alignment catch yet. The
-hydra raises another ugly head when you pack arrays of structures:
-
- typedef struct {
- short count;
- char glyph;
- } cell_t;
-
- typedef cell_t buffer_t[BUFLEN];
-
-Where's the catch? Padding is neither required before the first field C<count>,
-nor between this and the next field C<glyph>, so why can't we simply pack
-like this:
-
- # something goes wrong here:
- pack( 's!a' x @buffer,
- map{ ( $_->{count}, $_->{glyph} ) } @buffer );
-
-This packs C<3*@buffer> bytes, but it turns out that the size of
-C<buffer_t> is four times C<BUFLEN>! The moral of the story is that
-the required alignment of a structure or array is propagated to the
-next higher level where we have to consider padding I<at the end>
-of each component as well. Thus the correct template is:
-
- pack( 's!ax' x @buffer,
- map{ ( $_->{count}, $_->{glyph} ) } @buffer );
-
-=head2 Alignment, Take 3
-
-And even if you take all the above into account, ANSI still lets this:
-
- typedef struct {
- char foo[2];
- } foo_t;
-
-vary in size. The alignment constraint of the structure can be greater than
-any of its elements. [And if you think that this doesn't affect anything
-common, dismember the next cellphone that you see. Many have ARM cores, and
-the ARM structure rules make C<sizeof (foo_t)> == 4]
-
-=head2 Pointers for How to Use Them
-
-The title of this section indicates the second problem you may run into
-sooner or later when you pack C structures. If the function you intend
-to call expects a, say, C<void *> value, you I<cannot> simply take
-a reference to a Perl variable. (Although that value certainly is a
-memory address, it's not the address where the variable's contents are
-stored.)
-
-Template code C<P> promises to pack a "pointer to a fixed length string".
-Isn't this what we want? Let's try:
-
- # allocate some storage and pack a pointer to it
- my $memory = "\x00" x $size;
- my $memptr = pack( 'P', $memory );
-
-But wait: doesn't C<pack> just return a sequence of bytes? How can we pass this
-string of bytes to some C code expecting a pointer which is, after all,
-nothing but a number? The answer is simple: We have to obtain the numeric
-address from the bytes returned by C<pack>.
-
- my $ptr = unpack( 'L!', $memptr );
-
-Obviously this assumes that it is possible to typecast a pointer
-to an unsigned long and vice versa, which frequently works but should not
-be taken as a universal law. - Now that we have this pointer the next question
-is: How can we put it to good use? We need a call to some C function
-where a pointer is expected. The read(2) system call comes to mind:
-
- ssize_t read(int fd, void *buf, size_t count);
-
-After reading L<perlfunc> explaining how to use C<syscall> we can write
-this Perl function copying a file to standard output:
-
- require 'syscall.ph';
- sub cat($){
- my $path = shift();
- my $size = -s $path;
- my $memory = "\x00" x $size; # allocate some memory
- my $ptr = unpack( 'L', pack( 'P', $memory ) );
- open( F, $path ) || die( "$path: cannot open ($!)\n" );
- my $fd = fileno(F);
- my $res = syscall( &SYS_read, fileno(F), $ptr, $size );
- print $memory;
- close( F );
- }
-
-This is neither a specimen of simplicity nor a paragon of portability but
-it illustrates the point: We are able to sneak behind the scenes and
-access Perl's otherwise well-guarded memory! (Important note: Perl's
-C<syscall> does I<not> require you to construct pointers in this roundabout
-way. You simply pass a string variable, and Perl forwards the address.)
-
-How does C<unpack> with C<P> work? Imagine some pointer in the buffer
-about to be unpacked: If it isn't the null pointer (which will smartly
-produce the C<undef> value) we have a start address - but then what?
-Perl has no way of knowing how long this "fixed length string" is, so
-it's up to you to specify the actual size as an explicit length after C<P>.
-
- my $mem = "abcdefghijklmn";
- print unpack( 'P5', pack( 'P', $mem ) ); # prints "abcde"
-
-As a consequence, C<pack> ignores any number or C<*> after C<P>.
-
-
-Now that we have seen C<P> at work, we might as well give C<p> a whirl.
-Why do we need a second template code for packing pointers at all? The
-answer lies behind the simple fact that an C<unpack> with C<p> promises
-a null-terminated string starting at the address taken from the buffer,
-and that implies a length for the data item to be returned:
-
- my $buf = pack( 'p', "abc\x00efhijklmn" );
- print unpack( 'p', $buf ); # prints "abc"
-
-
-
-Albeit this is apt to be confusing: As a consequence of the length being
-implied by the string's length, a number after pack code C<p> is a repeat
-count, not a length as after C<P>.
-
-
-Using C<pack(..., $x)> with C<P> or C<p> to get the address where C<$x> is
-actually stored must be used with circumspection. Perl's internal machinery
-considers the relation between a variable and that address as its very own
-private matter and doesn't really care that we have obtained a copy. Therefore:
-
-=over 4
-
-=item *
-
-Do not use C<pack> with C<p> or C<P> to obtain the address of variable
-that's bound to go out of scope (and thereby freeing its memory) before you
-are done with using the memory at that address.
-
-=item *
-
-Be very careful with Perl operations that change the value of the
-variable. Appending something to the variable, for instance, might require
-reallocation of its storage, leaving you with a pointer into no-man's land.
-
-=item *
-
-Don't think that you can get the address of a Perl variable
-when it is stored as an integer or double number! C<pack('P', $x)> will
-force the variable's internal representation to string, just as if you
-had written something like C<$x .= ''>.
-
-=back
-
-It's safe, however, to P- or p-pack a string literal, because Perl simply
-allocates an anonymous variable.
-
-
-
-=head1 Pack Recipes
-
-Here are a collection of (possibly) useful canned recipes for C<pack>
-and C<unpack>:
-
- # Convert IP address for socket functions
- pack( "C4", split /\./, "123.4.5.6" );
-
- # Count the bits in a chunk of memory (e.g. a select vector)
- unpack( '%32b*', $mask );
-
- # Determine the endianness of your system
- $is_little_endian = unpack( 'c', pack( 's', 1 ) );
- $is_big_endian = unpack( 'xc', pack( 's', 1 ) );
-
- # Determine the number of bits in a native integer
- $bits = unpack( '%32I!', ~0 );
-
- # Prepare argument for the nanosleep system call
- my $timespec = pack( 'L!L!', $secs, $nanosecs );
-
-For a simple memory dump we unpack some bytes into just as
-many pairs of hex digits, and use C<map> to handle the traditional
-spacing - 16 bytes to a line:
-
- my $i;
- print map( ++$i % 16 ? "$_ " : "$_\n",
- unpack( 'H2' x length( $mem ), $mem ) ),
- length( $mem ) % 16 ? "\n" : '';
-
-
-=head1 Funnies Section
-
- # Pulling digits out of nowhere...
- print unpack( 'C', pack( 'x' ) ),
- unpack( '%B*', pack( 'A' ) ),
- unpack( 'H', pack( 'A' ) ),
- unpack( 'A', unpack( 'C', pack( 'A' ) ) ), "\n";
-
- # One for the road ;-)
- my $advice = pack( 'all u can in a van' );
-
-
-=head1 Authors
-
-Simon Cozens and Wolfgang Laun.
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlperf.pod b/Master/tlpkg/tlperl/lib/pods/perlperf.pod
deleted file mode 100644
index 007a02bc876..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlperf.pod
+++ /dev/null
@@ -1,1179 +0,0 @@
-=head1 NAME
-
-perlperf - Perl Performance and Optimization Techniques
-
-=head1 DESCRIPTION
-
-This is an introduction to the use of performance and optimization techniques
-which can be used with particular reference to perl programs. While many perl
-developers have come from other languages, and can use their prior knowledge
-where appropriate, there are many other people who might benefit from a few
-perl specific pointers. If you want the condensed version, perhaps the best
-advice comes from the renowned Japanese Samurai, Miyamoto Musashi, who said:
-
- "Do Not Engage in Useless Activity"
-
-in 1645.
-
-=head1 OVERVIEW
-
-Perhaps the most common mistake programmers make is to attempt to optimize
-their code before a program actually does anything useful - this is a bad idea.
-There's no point in having an extremely fast program that doesn't work. The
-first job is to get a program to I<correctly> do something B<useful>, (not to
-mention ensuring the test suite is fully functional), and only then to consider
-optimizing it. Having decided to optimize existing working code, there are
-several simple but essential steps to consider which are intrinsic to any
-optimization process.
-
-=head2 ONE STEP SIDEWAYS
-
-Firstly, you need to establish a baseline time for the existing code, which
-timing needs to be reliable and repeatable. You'll probably want to use the
-C<Benchmark> or C<Devel::NYTProf> modules, or something similar, for this step,
-or perhaps the Unix system C<time> utility, whichever is appropriate. See the
-base of this document for a longer list of benchmarking and profiling modules,
-and recommended further reading.
-
-=head2 ONE STEP FORWARD
-
-Next, having examined the program for I<hot spots>, (places where the code
-seems to run slowly), change the code with the intention of making it run
-faster. Using version control software, like C<subversion>, will ensure no
-changes are irreversible. It's too easy to fiddle here and fiddle there -
-don't change too much at any one time or you might not discover which piece of
-code B<really> was the slow bit.
-
-=head2 ANOTHER STEP SIDEWAYS
-
-It's not enough to say: "that will make it run faster", you have to check it.
-Rerun the code under control of the benchmarking or profiling modules, from the
-first step above, and check that the new code executed the B<same task> in
-I<less time>. Save your work and repeat...
-
-=head1 GENERAL GUIDELINES
-
-The critical thing when considering performance is to remember there is no such
-thing as a C<Golden Bullet>, which is why there are no rules, only guidelines.
-
-It is clear that inline code is going to be faster than subroutine or method
-calls, because there is less overhead, but this approach has the disadvantage
-of being less maintainable and comes at the cost of greater memory usage -
-there is no such thing as a free lunch. If you are searching for an element in
-a list, it can be more efficient to store the data in a hash structure, and
-then simply look to see whether the key is defined, rather than to loop through
-the entire array using grep() for instance. substr() may be (a lot) faster
-than grep() but not as flexible, so you have another trade-off to access. Your
-code may contain a line which takes 0.01 of a second to execute which if you
-call it 1,000 times, quite likely in a program parsing even medium sized files
-for instance, you already have a 10 second delay, in just one single code
-location, and if you call that line 100,000 times, your entire program will
-slow down to an unbearable crawl.
-
-Using a subroutine as part of your sort is a powerful way to get exactly what
-you want, but will usually be slower than the built-in I<alphabetic> C<cmp> and
-I<numeric> C<E<lt>=E<gt>> sort operators. It is possible to make multiple
-passes over your data, building indices to make the upcoming sort more
-efficient, and to use what is known as the C<OM> (Orcish Maneuver) to cache the
-sort keys in advance. The cache lookup, while a good idea, can itself be a
-source of slowdown by enforcing a double pass over the data - once to setup the
-cache, and once to sort the data. Using C<pack()> to extract the required sort
-key into a consistent string can be an efficient way to build a single string
-to compare, instead of using multiple sort keys, which makes it possible to use
-the standard, written in C<c> and fast, perl C<sort()> function on the output,
-and is the basis of the C<GRT> (Guttman Rossler Transform). Some string
-combinations can slow the C<GRT> down, by just being too plain complex for it's
-own good.
-
-For applications using database backends, the standard C<DBIx> namespace has
-tries to help with keeping things nippy, not least because it tries to I<not>
-query the database until the latest possible moment, but always read the docs
-which come with your choice of libraries. Among the many issues facing
-developers dealing with databases should remain aware of is to always use
-C<SQL> placeholders and to consider pre-fetching data sets when this might
-prove advantageous. Splitting up a large file by assigning multiple processes
-to parsing a single file, using say C<POE>, C<threads> or C<fork> can also be a
-useful way of optimizing your usage of the available C<CPU> resources, though
-this technique is fraught with concurrency issues and demands high attention to
-detail.
-
-Every case has a specific application and one or more exceptions, and there is
-no replacement for running a few tests and finding out which method works best
-for your particular environment, this is why writing optimal code is not an
-exact science, and why we love using Perl so much - TMTOWTDI.
-
-=head1 BENCHMARKS
-
-Here are a few examples to demonstrate usage of Perl's benchmarking tools.
-
-=head2 Assigning and Dereferencing Variables.
-
-I'm sure most of us have seen code which looks like, (or worse than), this:
-
- if ( $obj->{_ref}->{_myscore} >= $obj->{_ref}->{_yourscore} ) {
- ...
-
-This sort of code can be a real eyesore to read, as well as being very
-sensitive to typos, and it's much clearer to dereference the variable
-explicitly. We're side-stepping the issue of working with object-oriented
-programming techniques to encapsulate variable access via methods, only
-accessible through an object. Here we're just discussing the technical
-implementation of choice, and whether this has an effect on performance. We
-can see whether this dereferencing operation, has any overhead by putting
-comparative code in a file and running a C<Benchmark> test.
-
-# dereference
-
- #!/usr/bin/perl
-
- use strict;
- use warnings;
-
- use Benchmark;
-
- my $ref = {
- 'ref' => {
- _myscore => '100 + 1',
- _yourscore => '102 - 1',
- },
- };
-
- timethese(1000000, {
- 'direct' => sub {
- my $x = $ref->{ref}->{_myscore} . $ref->{ref}->{_yourscore} ;
- },
- 'dereference' => sub {
- my $ref = $ref->{ref};
- my $myscore = $ref->{_myscore};
- my $yourscore = $ref->{_yourscore};
- my $x = $myscore . $yourscore;
- },
- });
-
-It's essential to run any timing measurements a sufficient number of times so
-the numbers settle on a numerical average, otherwise each run will naturally
-fluctuate due to variations in the environment, to reduce the effect of
-contention for C<CPU> resources and network bandwidth for instance. Running
-the above code for one million iterations, we can take a look at the report
-output by the C<Benchmark> module, to see which approach is the most effective.
-
- $> perl dereference
-
- Benchmark: timing 1000000 iterations of dereference, direct...
- dereference: 2 wallclock secs ( 1.59 usr + 0.00 sys = 1.59 CPU) @ 628930.82/s (n=1000000)
- direct: 1 wallclock secs ( 1.20 usr + 0.00 sys = 1.20 CPU) @ 833333.33/s (n=1000000)
-
-The difference is clear to see and the dereferencing approach is slower. While
-it managed to execute an average of 628,930 times a second during our test, the
-direct approach managed to run an additional 204,403 times, unfortunately.
-Unfortunately, because there are many examples of code written using the
-multiple layer direct variable access, and it's usually horrible. It is,
-however, minusculy faster. The question remains whether the minute gain is
-actually worth the eyestrain, or the loss of maintainability.
-
-=head2 Search and replace or tr
-
-If we have a string which needs to be modified, while a regex will almost
-always be much more flexible, C<tr>, an oft underused tool, can still be a
-useful. One scenario might be replace all vowels with another character. The
-regex solution might look like this:
-
- $str =~ s/[aeiou]/x/g
-
-The C<tr> alternative might look like this:
-
- $str =~ tr/aeiou/xxxxx/
-
-We can put that into a test file which we can run to check which approach is
-the fastest, using a global C<$STR> variable to assign to the C<my $str>
-variable so as to avoid perl trying to optimize any of the work away by
-noticing it's assigned only the once.
-
-# regex-transliterate
-
- #!/usr/bin/perl
-
- use strict;
- use warnings;
-
- use Benchmark;
-
- my $STR = "$$-this and that";
-
- timethese( 1000000, {
- 'sr' => sub { my $str = $STR; $str =~ s/[aeiou]/x/g; return $str; },
- 'tr' => sub { my $str = $STR; $str =~ tr/aeiou/xxxxx/; return $str; },
- });
-
-Running the code gives us our results:
-
- $> perl regex-transliterate
-
- Benchmark: timing 1000000 iterations of sr, tr...
- sr: 2 wallclock secs ( 1.19 usr + 0.00 sys = 1.19 CPU) @ 840336.13/s (n=1000000)
- tr: 0 wallclock secs ( 0.49 usr + 0.00 sys = 0.49 CPU) @ 2040816.33/s (n=1000000)
-
-The C<tr> version is a clear winner. One solution is flexible, the other is
-fast - and it's appropriately the programmer's choice which to use.
-
-Check the C<Benchmark> docs for further useful techniques.
-
-=head1 PROFILING TOOLS
-
-A slightly larger piece of code will provide something on which a profiler can
-produce more extensive reporting statistics. This example uses the simplistic
-C<wordmatch> program which parses a given input file and spews out a short
-report on the contents.
-
-# wordmatch
-
- #!/usr/bin/perl
-
- use strict;
- use warnings;
-
- =head1 NAME
-
- filewords - word analysis of input file
-
- =head1 SYNOPSIS
-
- filewords -f inputfilename [-d]
-
- =head1 DESCRIPTION
-
- This program parses the given filename, specified with C<-f>, and displays a
- simple analysis of the words found therein. Use the C<-d> switch to enable
- debugging messages.
-
- =cut
-
- use FileHandle;
- use Getopt::Long;
-
- my $debug = 0;
- my $file = '';
-
- my $result = GetOptions (
- 'debug' => \$debug,
- 'file=s' => \$file,
- );
- die("invalid args") unless $result;
-
- unless ( -f $file ) {
- die("Usage: $0 -f filename [-d]");
- }
- my $FH = FileHandle->new("< $file") or die("unable to open file($file): $!");
-
- my $i_LINES = 0;
- my $i_WORDS = 0;
- my %count = ();
-
- my @lines = <$FH>;
- foreach my $line ( @lines ) {
- $i_LINES++;
- $line =~ s/\n//;
- my @words = split(/ +/, $line);
- my $i_words = scalar(@words);
- $i_WORDS = $i_WORDS + $i_words;
- debug("line: $i_LINES supplying $i_words words: @words");
- my $i_word = 0;
- foreach my $word ( @words ) {
- $i_word++;
- $count{$i_LINES}{spec} += matches($i_word, $word, '[^a-zA-Z0-9]');
- $count{$i_LINES}{only} += matches($i_word, $word, '^[^a-zA-Z0-9]+$');
- $count{$i_LINES}{cons} += matches($i_word, $word, '^[(?i:bcdfghjklmnpqrstvwxyz)]+$');
- $count{$i_LINES}{vows} += matches($i_word, $word, '^[(?i:aeiou)]+$');
- $count{$i_LINES}{caps} += matches($i_word, $word, '^[(A-Z)]+$');
- }
- }
-
- print report( %count );
-
- sub matches {
- my $i_wd = shift;
- my $word = shift;
- my $regex = shift;
- my $has = 0;
-
- if ( $word =~ /($regex)/ ) {
- $has++ if $1;
- }
-
- debug("word: $i_wd ".($has ? 'matches' : 'does not match')." chars: /$regex/");
-
- return $has;
- }
-
- sub report {
- my %report = @_;
- my %rep;
-
- foreach my $line ( keys %report ) {
- foreach my $key ( keys %{ $report{$line} } ) {
- $rep{$key} += $report{$line}{$key};
- }
- }
-
- my $report = qq|
- $0 report for $file:
- lines in file: $i_LINES
- words in file: $i_WORDS
- words with special (non-word) characters: $i_spec
- words with only special (non-word) characters: $i_only
- words with only consonants: $i_cons
- words with only capital letters: $i_caps
- words with only vowels: $i_vows
- |;
-
- return $report;
- }
-
- sub debug {
- my $message = shift;
-
- if ( $debug ) {
- print STDERR "DBG: $message\n";
- }
- }
-
- exit 0;
-
-=head2 Devel::DProf
-
-This venerable module has been the de-facto standard for Perl code profiling
-for more than a decade, but has been replaced by a number of other modules
-which have brought us back to the 21st century. Although you're recommended to
-evaluate your tool from the several mentioned here and from the CPAN list at
-the base of this document, (and currently L<Devel::NYTProf> seems to be the
-weapon of choice - see below), we'll take a quick look at the output from
-L<Devel::DProf> first, to set a baseline for Perl profiling tools. Run the
-above program under the control of C<Devel::DProf> by using the C<-d> switch on
-the command-line.
-
- $> perl -d:DProf wordmatch -f perl5db.pl
-
- <...multiple lines snipped...>
-
- wordmatch report for perl5db.pl:
- lines in file: 9428
- words in file: 50243
- words with special (non-word) characters: 20480
- words with only special (non-word) characters: 7790
- words with only consonants: 4801
- words with only capital letters: 1316
- words with only vowels: 1701
-
-C<Devel::DProf> produces a special file, called F<tmon.out> by default, and
-this file is read by the C<dprofpp> program, which is already installed as part
-of the C<Devel::DProf> distribution. If you call C<dprofpp> with no options,
-it will read the F<tmon.out> file in the current directory and produce a human
-readable statistics report of the run of your program. Note that this may take
-a little time.
-
- $> dprofpp
-
- Total Elapsed Time = 2.951677 Seconds
- User+System Time = 2.871677 Seconds
- Exclusive Times
- %Time ExclSec CumulS #Calls sec/call Csec/c Name
- 102. 2.945 3.003 251215 0.0000 0.0000 main::matches
- 2.40 0.069 0.069 260643 0.0000 0.0000 main::debug
- 1.74 0.050 0.050 1 0.0500 0.0500 main::report
- 1.04 0.030 0.049 4 0.0075 0.0123 main::BEGIN
- 0.35 0.010 0.010 3 0.0033 0.0033 Exporter::as_heavy
- 0.35 0.010 0.010 7 0.0014 0.0014 IO::File::BEGIN
- 0.00 - -0.000 1 - - Getopt::Long::FindOption
- 0.00 - -0.000 1 - - Symbol::BEGIN
- 0.00 - -0.000 1 - - Fcntl::BEGIN
- 0.00 - -0.000 1 - - Fcntl::bootstrap
- 0.00 - -0.000 1 - - warnings::BEGIN
- 0.00 - -0.000 1 - - IO::bootstrap
- 0.00 - -0.000 1 - - Getopt::Long::ConfigDefaults
- 0.00 - -0.000 1 - - Getopt::Long::Configure
- 0.00 - -0.000 1 - - Symbol::gensym
-
-C<dprofpp> will produce some quite detailed reporting on the activity of the
-C<wordmatch> program. The wallclock, user and system, times are at the top of
-the analysis, and after this are the main columns defining which define the
-report. Check the C<dprofpp> docs for details of the many options it supports.
-
-See also C<Apache::DProf> which hooks C<Devel::DProf> into C<mod_perl>.
-
-=head2 Devel::Profiler
-
-Let's take a look at the same program using a different profiler:
-C<Devel::Profiler>, a drop-in Perl-only replacement for C<Devel::DProf>. The
-usage is very slightly different in that instead of using the special C<-d:>
-flag, you pull C<Devel::Profiler> in directly as a module using C<-M>.
-
- $> perl -MDevel::Profiler wordmatch -f perl5db.pl
-
- <...multiple lines snipped...>
-
- wordmatch report for perl5db.pl:
- lines in file: 9428
- words in file: 50243
- words with special (non-word) characters: 20480
- words with only special (non-word) characters: 7790
- words with only consonants: 4801
- words with only capital letters: 1316
- words with only vowels: 1701
-
-
-C<Devel::Profiler> generates a tmon.out file which is compatible with the
-C<dprofpp> program, thus saving the construction of a dedicated statistics
-reader program. C<dprofpp> usage is therefore identical to the above example.
-
- $> dprofpp
-
- Total Elapsed Time = 20.984 Seconds
- User+System Time = 19.981 Seconds
- Exclusive Times
- %Time ExclSec CumulS #Calls sec/call Csec/c Name
- 49.0 9.792 14.509 251215 0.0000 0.0001 main::matches
- 24.4 4.887 4.887 260643 0.0000 0.0000 main::debug
- 0.25 0.049 0.049 1 0.0490 0.0490 main::report
- 0.00 0.000 0.000 1 0.0000 0.0000 Getopt::Long::GetOptions
- 0.00 0.000 0.000 2 0.0000 0.0000 Getopt::Long::ParseOptionSpec
- 0.00 0.000 0.000 1 0.0000 0.0000 Getopt::Long::FindOption
- 0.00 0.000 0.000 1 0.0000 0.0000 IO::File::new
- 0.00 0.000 0.000 1 0.0000 0.0000 IO::Handle::new
- 0.00 0.000 0.000 1 0.0000 0.0000 Symbol::gensym
- 0.00 0.000 0.000 1 0.0000 0.0000 IO::File::open
-
-Interestingly we get slightly different results, which is mostly because the
-algorithm which generates the report is different, even though the output file
-format was allegedly identical. The elapsed, user and system times are clearly
-showing the time it took for C<Devel::Profiler> to execute its own run, but
-the column listings feel more accurate somehow than the ones we had earlier
-from C<Devel::DProf>. The 102% figure has disappeared, for example. This is
-where we have to use the tools at our disposal, and recognise their pros and
-cons, before using them. Interestingly, the numbers of calls for each
-subroutine are identical in the two reports, it's the percentages which differ.
-As the author of C<Devel::Proviler> writes:
-
- ...running HTML::Template's test suite under Devel::DProf shows output()
- taking NO time but Devel::Profiler shows around 10% of the time is in output().
- I don't know which to trust but my gut tells me something is wrong with
- Devel::DProf. HTML::Template::output() is a big routine that's called for
- every test. Either way, something needs fixing.
-
-YMMV.
-
-See also C<Devel::Apache::Profiler> which hooks C<Devel::Profiler> into C<mod_perl>.
-
-=head2 Devel::SmallProf
-
-The C<Devel::SmallProf> profiler examines the runtime of your Perl program and
-produces a line-by-line listing to show how many times each line was called,
-and how long each line took to execute. It is called by supplying the familiar
-C<-d> flag to Perl at runtime.
-
- $> perl -d:SmallProf wordmatch -f perl5db.pl
-
- <...multiple lines snipped...>
-
- wordmatch report for perl5db.pl:
- lines in file: 9428
- words in file: 50243
- words with special (non-word) characters: 20480
- words with only special (non-word) characters: 7790
- words with only consonants: 4801
- words with only capital letters: 1316
- words with only vowels: 1701
-
-C<Devel::SmallProf> writes it's output into a file called F<smallprof.out>, by
-default. The format of the file looks like this:
-
- <num> <time> <ctime> <line>:<text>
-
-When the program has terminated, the output may be examined and sorted using
-any standard text filtering utilities. Something like the following may be
-sufficient:
-
- $> cat smallprof.out | grep \d*: | sort -k3 | tac | head -n20
-
- 251215 1.65674 7.68000 75: if ( $word =~ /($regex)/ ) {
- 251215 0.03264 4.40000 79: debug("word: $i_wd ".($has ? 'matches' :
- 251215 0.02693 4.10000 81: return $has;
- 260643 0.02841 4.07000 128: if ( $debug ) {
- 260643 0.02601 4.04000 126: my $message = shift;
- 251215 0.02641 3.91000 73: my $has = 0;
- 251215 0.03311 3.71000 70: my $i_wd = shift;
- 251215 0.02699 3.69000 72: my $regex = shift;
- 251215 0.02766 3.68000 71: my $word = shift;
- 50243 0.59726 1.00000 59: $count{$i_LINES}{cons} =
- 50243 0.48175 0.92000 61: $count{$i_LINES}{spec} =
- 50243 0.00644 0.89000 56: my $i_cons = matches($i_word, $word,
- 50243 0.48837 0.88000 63: $count{$i_LINES}{caps} =
- 50243 0.00516 0.88000 58: my $i_caps = matches($i_word, $word, '^[(A-
- 50243 0.00631 0.81000 54: my $i_spec = matches($i_word, $word, '[^a-
- 50243 0.00496 0.80000 57: my $i_vows = matches($i_word, $word,
- 50243 0.00688 0.80000 53: $i_word++;
- 50243 0.48469 0.79000 62: $count{$i_LINES}{only} =
- 50243 0.48928 0.77000 60: $count{$i_LINES}{vows} =
- 50243 0.00683 0.75000 55: my $i_only = matches($i_word, $word, '^[^a-
-
-You can immediately see a slightly different focus to the subroutine profiling
-modules, and we start to see exactly which line of code is taking the most
-time. That regex line is looking a bit suspicious, for example. Remember that
-these tools are supposed to be used together, there is no single best way to
-profile your code, you need to use the best tools for the job.
-
-See also C<Apache::SmallProf> which hooks C<Devel::SmallProf> into C<mod_perl>.
-
-=head2 Devel::FastProf
-
-C<Devel::FastProf> is another Perl line profiler. This was written with a view
-to getting a faster line profiler, than is possible with for example
-C<Devel::SmallProf>, because it's written in C<C>. To use C<Devel::FastProf>,
-supply the C<-d> argument to Perl:
-
- $> perl -d:FastProf wordmatch -f perl5db.pl
-
- <...multiple lines snipped...>
-
- wordmatch report for perl5db.pl:
- lines in file: 9428
- words in file: 50243
- words with special (non-word) characters: 20480
- words with only special (non-word) characters: 7790
- words with only consonants: 4801
- words with only capital letters: 1316
- words with only vowels: 1701
-
-C<Devel::FastProf> writes statistics to the file F<fastprof.out> in the current
-directory. The output file, which can be specified, can be interpreted by using
-the C<fprofpp> command-line program.
-
- $> fprofpp | head -n20
-
- # fprofpp output format is:
- # filename:line time count: source
- wordmatch:75 3.93338 251215: if ( $word =~ /($regex)/ ) {
- wordmatch:79 1.77774 251215: debug("word: $i_wd ".($has ? 'matches' : 'does not match')." chars: /$regex/");
- wordmatch:81 1.47604 251215: return $has;
- wordmatch:126 1.43441 260643: my $message = shift;
- wordmatch:128 1.42156 260643: if ( $debug ) {
- wordmatch:70 1.36824 251215: my $i_wd = shift;
- wordmatch:71 1.36739 251215: my $word = shift;
- wordmatch:72 1.35939 251215: my $regex = shift;
-
-Straightaway we can see that the number of times each line has been called is
-identical to the C<Devel::SmallProf> output, and the sequence is only very
-slightly different based on the ordering of the amount of time each line took
-to execute, C<if ( $debug ) { > and C<my $message = shift;>, for example. The
-differences in the actual times recorded might be in the algorithm used
-internally, or it could be due to system resource limitations or contention.
-
-See also the L<DBIx::Profile> which will profile database queries running
-under the C<DBIx::*> namespace.
-
-=head2 Devel::NYTProf
-
-C<Devel::NYTProf> is the B<next generation> of Perl code profiler, fixing many
-shortcomings in other tools and implementing many cool features. First of all it
-can be used as either a I<line> profiler, a I<block> or a I<subroutine>
-profiler, all at once. It can also use sub-microsecond (100ns) resolution on
-systems which provide C<clock_gettime()>. It can be started and stopped even
-by the program being profiled. It's a one-line entry to profile C<mod_perl>
-applications. It's written in C<c> and is probably the fastest profiler
-available for Perl. The list of coolness just goes on. Enough of that, let's
-see how to it works - just use the familiar C<-d> switch to plug it in and run
-the code.
-
- $> perl -d:NYTProf wordmatch -f perl5db.pl
-
- wordmatch report for perl5db.pl:
- lines in file: 9427
- words in file: 50243
- words with special (non-word) characters: 20480
- words with only special (non-word) characters: 7790
- words with only consonants: 4801
- words with only capital letters: 1316
- words with only vowels: 1701
-
-C<NYTProf> will generate a report database into the file F<nytprof.out> by
-default. Human readable reports can be generated from here by using the
-supplied C<nytprofhtml> (HTML output) and C<nytprofcsv> (CSV output) programs.
-We've used the Unix system C<html2text> utility to convert the
-F<nytprof/index.html> file for convenience here.
-
- $> html2text nytprof/index.html
-
- Performance Profile Index
- For wordmatch
- Run on Fri Sep 26 13:46:39 2008
- Reported on Fri Sep 26 13:47:23 2008
-
- Top 15 Subroutines -- ordered by exclusive time
- |Calls |P |F |Inclusive|Exclusive|Subroutine |
- | | | |Time |Time | |
- |251215|5 |1 |13.09263 |10.47692 |main:: |matches |
- |260642|2 |1 |2.71199 |2.71199 |main:: |debug |
- |1 |1 |1 |0.21404 |0.21404 |main:: |report |
- |2 |2 |2 |0.00511 |0.00511 |XSLoader:: |load (xsub) |
- |14 |14|7 |0.00304 |0.00298 |Exporter:: |import |
- |3 |1 |1 |0.00265 |0.00254 |Exporter:: |as_heavy |
- |10 |10|4 |0.00140 |0.00140 |vars:: |import |
- |13 |13|1 |0.00129 |0.00109 |constant:: |import |
- |1 |1 |1 |0.00360 |0.00096 |FileHandle:: |import |
- |3 |3 |3 |0.00086 |0.00074 |warnings::register::|import |
- |9 |3 |1 |0.00036 |0.00036 |strict:: |bits |
- |13 |13|13|0.00032 |0.00029 |strict:: |import |
- |2 |2 |2 |0.00020 |0.00020 |warnings:: |import |
- |2 |1 |1 |0.00020 |0.00020 |Getopt::Long:: |ParseOptionSpec|
- |7 |7 |6 |0.00043 |0.00020 |strict:: |unimport |
-
- For more information see the full list of 189 subroutines.
-
-The first part of the report already shows the critical information regarding
-which subroutines are using the most time. The next gives some statistics
-about the source files profiled.
-
- Source Code Files -- ordered by exclusive time then name
- |Stmts |Exclusive|Avg. |Reports |Source File |
- | |Time | | | |
- |2699761|15.66654 |6e-06 |line . block . sub|wordmatch |
- |35 |0.02187 |0.00062|line . block . sub|IO/Handle.pm |
- |274 |0.01525 |0.00006|line . block . sub|Getopt/Long.pm |
- |20 |0.00585 |0.00029|line . block . sub|Fcntl.pm |
- |128 |0.00340 |0.00003|line . block . sub|Exporter/Heavy.pm |
- |42 |0.00332 |0.00008|line . block . sub|IO/File.pm |
- |261 |0.00308 |0.00001|line . block . sub|Exporter.pm |
- |323 |0.00248 |8e-06 |line . block . sub|constant.pm |
- |12 |0.00246 |0.00021|line . block . sub|File/Spec/Unix.pm |
- |191 |0.00240 |0.00001|line . block . sub|vars.pm |
- |77 |0.00201 |0.00003|line . block . sub|FileHandle.pm |
- |12 |0.00198 |0.00016|line . block . sub|Carp.pm |
- |14 |0.00175 |0.00013|line . block . sub|Symbol.pm |
- |15 |0.00130 |0.00009|line . block . sub|IO.pm |
- |22 |0.00120 |0.00005|line . block . sub|IO/Seekable.pm |
- |198 |0.00085 |4e-06 |line . block . sub|warnings/register.pm|
- |114 |0.00080 |7e-06 |line . block . sub|strict.pm |
- |47 |0.00068 |0.00001|line . block . sub|warnings.pm |
- |27 |0.00054 |0.00002|line . block . sub|overload.pm |
- |9 |0.00047 |0.00005|line . block . sub|SelectSaver.pm |
- |13 |0.00045 |0.00003|line . block . sub|File/Spec.pm |
- |2701595|15.73869 | |Total |
- |128647 |0.74946 | |Average |
- | |0.00201 |0.00003|Median |
- | |0.00121 |0.00003|Deviation |
-
- Report produced by the NYTProf 2.03 Perl profiler, developed by Tim Bunce and
- Adam Kaplan.
-
-At this point, if you're using the I<html> report, you can click through the
-various links to bore down into each subroutine and each line of code. Because
-we're using the text reporting here, and there's a whole directory full of
-reports built for each source file, we'll just display a part of the
-corresponding F<wordmatch-line.html> file, sufficient to give an idea of the
-sort of output you can expect from this cool tool.
-
- $> html2text nytprof/wordmatch-line.html
-
- Performance Profile -- -block view-.-line view-.-sub view-
- For wordmatch
- Run on Fri Sep 26 13:46:39 2008
- Reported on Fri Sep 26 13:47:22 2008
-
- File wordmatch
-
- Subroutines -- ordered by exclusive time
- |Calls |P|F|Inclusive|Exclusive|Subroutine |
- | | | |Time |Time | |
- |251215|5|1|13.09263 |10.47692 |main::|matches|
- |260642|2|1|2.71199 |2.71199 |main::|debug |
- |1 |1|1|0.21404 |0.21404 |main::|report |
- |0 |0|0|0 |0 |main::|BEGIN |
-
-
- |Line|Stmts.|Exclusive|Avg. |Code |
- | | |Time | | |
- |1 | | | |#!/usr/bin/perl |
- |2 | | | | |
- | | | | |use strict; |
- |3 |3 |0.00086 |0.00029|# spent 0.00003s making 1 calls to strict:: |
- | | | | |import |
- | | | | |use warnings; |
- |4 |3 |0.01563 |0.00521|# spent 0.00012s making 1 calls to warnings:: |
- | | | | |import |
- |5 | | | | |
- |6 | | | |=head1 NAME |
- |7 | | | | |
- |8 | | | |filewords - word analysis of input file |
- <...snip...>
- |62 |1 |0.00445 |0.00445|print report( %count ); |
- | | | | |# spent 0.21404s making 1 calls to main::report|
- |63 | | | | |
- | | | | |# spent 23.56955s (10.47692+2.61571) within |
- | | | | |main::matches which was called 251215 times, |
- | | | | |avg 0.00005s/call: # 50243 times |
- | | | | |(2.12134+0.51939s) at line 57 of wordmatch, avg|
- | | | | |0.00005s/call # 50243 times (2.17735+0.54550s) |
- |64 | | | |at line 56 of wordmatch, avg 0.00005s/call # |
- | | | | |50243 times (2.10992+0.51797s) at line 58 of |
- | | | | |wordmatch, avg 0.00005s/call # 50243 times |
- | | | | |(2.12696+0.51598s) at line 55 of wordmatch, avg|
- | | | | |0.00005s/call # 50243 times (1.94134+0.51687s) |
- | | | | |at line 54 of wordmatch, avg 0.00005s/call |
- | | | | |sub matches { |
- <...snip...>
- |102 | | | | |
- | | | | |# spent 2.71199s within main::debug which was |
- | | | | |called 260642 times, avg 0.00001s/call: # |
- | | | | |251215 times (2.61571+0s) by main::matches at |
- |103 | | | |line 74 of wordmatch, avg 0.00001s/call # 9427 |
- | | | | |times (0.09628+0s) at line 50 of wordmatch, avg|
- | | | | |0.00001s/call |
- | | | | |sub debug { |
- |104 |260642|0.58496 |2e-06 |my $message = shift; |
- |105 | | | | |
- |106 |260642|1.09917 |4e-06 |if ( $debug ) { |
- |107 | | | |print STDERR "DBG: $message\n"; |
- |108 | | | |} |
- |109 | | | |} |
- |110 | | | | |
- |111 |1 |0.01501 |0.01501|exit 0; |
- |112 | | | | |
-
-Oodles of very useful information in there - this seems to be the way forward.
-
-See also C<Devel::NYTProf::Apache> which hooks C<Devel::NYTProf> into C<mod_perl>.
-
-=head1 SORTING
-
-Perl modules are not the only tools a performance analyst has at their
-disposal, system tools like C<time> should not be overlooked as the next
-example shows, where we take a quick look at sorting. Many books, theses and
-articles, have been written about efficient sorting algorithms, and this is not
-the place to repeat such work, there's several good sorting modules which
-deserve taking a look at too: C<Sort::Maker>, C<Sort::Key> spring to mind.
-However, it's still possible to make some observations on certain Perl specific
-interpretations on issues relating to sorting data sets and give an example or
-two with regard to how sorting large data volumes can effect performance.
-Firstly, an often overlooked point when sorting large amounts of data, one can
-attempt to reduce the data set to be dealt with and in many cases C<grep()> can
-be quite useful as a simple filter:
-
- @data = sort grep { /$filter/ } @incoming
-
-A command such as this can vastly reduce the volume of material to actually
-sort through in the first place, and should not be too lightly disregarded
-purely on the basis of its simplicity. The C<KISS> principle is too often
-overlooked - the next example uses the simple system C<time> utility to
-demonstrate. Let's take a look at an actual example of sorting the contents of
-a large file, an apache logfile would do. This one has over a quarter of a
-million lines, is 50M in size, and a snippet of it looks like this:
-
-# logfile
-
- 188.209-65-87.adsl-dyn.isp.belgacom.be - - [08/Feb/2007:12:57:16 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
- 188.209-65-87.adsl-dyn.isp.belgacom.be - - [08/Feb/2007:12:57:16 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
- 151.56.71.198 - - [08/Feb/2007:12:57:41 +0000] "GET /suse-on-vaio.html HTTP/1.1" 200 2858 "http://www.linux-on-laptops.com/sony.html" "Mozilla/5.0 (Windows; U; Windows NT 5.2; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1"
- 151.56.71.198 - - [08/Feb/2007:12:57:42 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/suse-on-vaio.html" "Mozilla/5.0 (Windows; U; Windows NT 5.2; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1"
- 151.56.71.198 - - [08/Feb/2007:12:57:43 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "-" "Mozilla/5.0 (Windows; U; Windows NT 5.2; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1"
- 217.113.68.60 - - [08/Feb/2007:13:02:15 +0000] "GET / HTTP/1.1" 304 - "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
- 217.113.68.60 - - [08/Feb/2007:13:02:16 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
- debora.to.isac.cnr.it - - [08/Feb/2007:13:03:58 +0000] "GET /suse-on-vaio.html HTTP/1.1" 200 2858 "http://www.linux-on-laptops.com/sony.html" "Mozilla/5.0 (compatible; Konqueror/3.4; Linux) KHTML/3.4.0 (like Gecko)"
- debora.to.isac.cnr.it - - [08/Feb/2007:13:03:58 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/suse-on-vaio.html" "Mozilla/5.0 (compatible; Konqueror/3.4; Linux) KHTML/3.4.0 (like Gecko)"
- debora.to.isac.cnr.it - - [08/Feb/2007:13:03:58 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "-" "Mozilla/5.0 (compatible; Konqueror/3.4; Linux) KHTML/3.4.0 (like Gecko)"
- 195.24.196.99 - - [08/Feb/2007:13:26:48 +0000] "GET / HTTP/1.0" 200 3309 "-" "Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.8.0.9) Gecko/20061206 Firefox/1.5.0.9"
- 195.24.196.99 - - [08/Feb/2007:13:26:58 +0000] "GET /data/css HTTP/1.0" 404 206 "http://www.rfi.net/" "Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.8.0.9) Gecko/20061206 Firefox/1.5.0.9"
- 195.24.196.99 - - [08/Feb/2007:13:26:59 +0000] "GET /favicon.ico HTTP/1.0" 404 209 "-" "Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.8.0.9) Gecko/20061206 Firefox/1.5.0.9"
- crawl1.cosmixcorp.com - - [08/Feb/2007:13:27:57 +0000] "GET /robots.txt HTTP/1.0" 200 179 "-" "voyager/1.0"
- crawl1.cosmixcorp.com - - [08/Feb/2007:13:28:25 +0000] "GET /links.html HTTP/1.0" 200 3413 "-" "voyager/1.0"
- fhm226.internetdsl.tpnet.pl - - [08/Feb/2007:13:37:32 +0000] "GET /suse-on-vaio.html HTTP/1.1" 200 2858 "http://www.linux-on-laptops.com/sony.html" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
- fhm226.internetdsl.tpnet.pl - - [08/Feb/2007:13:37:34 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/suse-on-vaio.html" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
- 80.247.140.134 - - [08/Feb/2007:13:57:35 +0000] "GET / HTTP/1.1" 200 3309 "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)"
- 80.247.140.134 - - [08/Feb/2007:13:57:37 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)"
- pop.compuscan.co.za - - [08/Feb/2007:14:10:43 +0000] "GET / HTTP/1.1" 200 3309 "-" "www.clamav.net"
- livebot-207-46-98-57.search.live.com - - [08/Feb/2007:14:12:04 +0000] "GET /robots.txt HTTP/1.0" 200 179 "-" "msnbot/1.0 (+http://search.msn.com/msnbot.htm)"
- livebot-207-46-98-57.search.live.com - - [08/Feb/2007:14:12:04 +0000] "GET /html/oracle.html HTTP/1.0" 404 214 "-" "msnbot/1.0 (+http://search.msn.com/msnbot.htm)"
- dslb-088-064-005-154.pools.arcor-ip.net - - [08/Feb/2007:14:12:15 +0000] "GET / HTTP/1.1" 200 3309 "-" "www.clamav.net"
- 196.201.92.41 - - [08/Feb/2007:14:15:01 +0000] "GET / HTTP/1.1" 200 3309 "-" "MOT-L7/08.B7.DCR MIB/2.2.1 Profile/MIDP-2.0 Configuration/CLDC-1.1"
-
-The specific task here is to sort the 286,525 lines of this file by Response
-Code, Query, Browser, Referring Url, and lastly Date. One solution might be to
-use the following code, which iterates over the files given on the
-command-line.
-
-# sort-apache-log
-
- #!/usr/bin/perl -n
-
- use strict;
- use warnings;
-
- my @data;
-
- LINE:
- while ( <> ) {
- my $line = $_;
- if (
- $line =~ m/^(
- ([\w\.\-]+) # client
- \s*-\s*-\s*\[
- ([^]]+) # date
- \]\s*"\w+\s*
- (\S+) # query
- [^"]+"\s*
- (\d+) # status
- \s+\S+\s+"[^"]*"\s+"
- ([^"]*) # browser
- "
- .*
- )$/x
- ) {
- my @chunks = split(/ +/, $line);
- my $ip = $1;
- my $date = $2;
- my $query = $3;
- my $status = $4;
- my $browser = $5;
-
- push(@data, [$ip, $date, $query, $status, $browser, $line]);
- }
- }
-
- my @sorted = sort {
- $a->[3] cmp $b->[3]
- ||
- $a->[2] cmp $b->[2]
- ||
- $a->[0] cmp $b->[0]
- ||
- $a->[1] cmp $b->[1]
- ||
- $a->[4] cmp $b->[4]
- } @data;
-
- foreach my $data ( @sorted ) {
- print $data->[5];
- }
-
- exit 0;
-
-When running this program, redirect C<STDOUT> so it is possible to check the
-output is correct from following test runs and use the system C<time> utility
-to check the overall runtime.
-
- $> time ./sort-apache-log logfile > out-sort
-
- real 0m17.371s
- user 0m15.757s
- sys 0m0.592s
-
-The program took just over 17 wallclock seconds to run. Note the different
-values C<time> outputs, it's important to always use the same one, and to not
-confuse what each one means.
-
-=over 4
-
-=item Elapsed Real Time
-
-The overall, or wallclock, time between when C<time> was called, and when it
-terminates. The elapsed time includes both user and system times, and time
-spent waiting for other users and processes on the system. Inevitably, this is
-the most approximate of the measurements given.
-
-=item User CPU Time
-
-The user time is the amount of time the entire process spent on behalf of the
-user on this system executing this program.
-
-=item System CPU Time
-
-The system time is the amount of time the kernel itself spent executing
-routines, or system calls, on behalf of this process user.
-
-=back
-
-Running this same process as a C<Schwarzian Transform> it is possible to
-eliminate the input and output arrays for storing all the data, and work on the
-input directly as it arrives too. Otherwise, the code looks fairly similar:
-
-# sort-apache-log-schwarzian
-
- #!/usr/bin/perl -n
-
- use strict;
- use warnings;
-
- print
-
- map $_->[0] =>
-
- sort {
- $a->[4] cmp $b->[4]
- ||
- $a->[3] cmp $b->[3]
- ||
- $a->[1] cmp $b->[1]
- ||
- $a->[2] cmp $b->[2]
- ||
- $a->[5] cmp $b->[5]
- }
- map [ $_, m/^(
- ([\w\.\-]+) # client
- \s*-\s*-\s*\[
- ([^]]+) # date
- \]\s*"\w+\s*
- (\S+) # query
- [^"]+"\s*
- (\d+) # status
- \s+\S+\s+"[^"]*"\s+"
- ([^"]*) # browser
- "
- .*
- )$/xo ]
-
- => <>;
-
- exit 0;
-
-Run the new code against the same logfile, as above, to check the new time.
-
- $> time ./sort-apache-log-schwarzian logfile > out-schwarz
-
- real 0m9.664s
- user 0m8.873s
- sys 0m0.704s
-
-The time has been cut in half, which is a respectable speed improvement by any
-standard. Naturally, it is important to check the output is consistent with
-the first program run, this is where the Unix system C<cksum> utility comes in.
-
- $> cksum out-sort out-schwarz
- 3044173777 52029194 out-sort
- 3044173777 52029194 out-schwarz
-
-BTW. Beware too of pressure from managers who see you speed a program up by 50%
-of the runtime once, only to get a request one month later to do the same again
-(true story) - you'll just have to point out your only human, even if you are a
-Perl programmer, and you'll see what you can do...
-
-=head1 LOGGING
-
-An essential part of any good development process is appropriate error handling
-with appropriately informative messages, however there exists a school of
-thought which suggests that log files should be I<chatty>, as if the chain of
-unbroken output somehow ensures the survival of the program. If speed is in
-any way an issue, this approach is wrong.
-
-A common sight is code which looks something like this:
-
- logger->debug( "A logging message via process-id: $$ INC: " . Dumper(\%INC) )
-
-The problem is that this code will always be parsed and executed, even when the
-debug level set in the logging configuration file is zero. Once the debug()
-subroutine has been entered, and the internal C<$debug> variable confirmed to
-be zero, for example, the message which has been sent in will be discarded and
-the program will continue. In the example given though, the \%INC hash will
-already have been dumped, and the message string constructed, all of which work
-could be bypassed by a debug variable at the statement level, like this:
-
- logger->debug( "A logging message via process-id: $$ INC: " . Dumper(\%INC) ) if $DEBUG;
-
-This effect can be demonstrated by setting up a test script with both forms,
-including a C<debug()> subroutine to emulate typical C<logger()> functionality.
-
-# ifdebug
-
- #!/usr/bin/perl
-
- use strict;
- use warnings;
-
- use Benchmark;
- use Data::Dumper;
- my $DEBUG = 0;
-
- sub debug {
- my $msg = shift;
-
- if ( $DEBUG ) {
- print "DEBUG: $msg\n";
- }
- };
-
- timethese(100000, {
- 'debug' => sub {
- debug( "A $0 logging message via process-id: $$" . Dumper(\%INC) )
- },
- 'ifdebug' => sub {
- debug( "A $0 logging message via process-id: $$" . Dumper(\%INC) ) if $DEBUG
- },
- });
-
-Let's see what C<Benchmark> makes of this:
-
- $> perl ifdebug
- Benchmark: timing 100000 iterations of constant, sub...
- ifdebug: 0 wallclock secs ( 0.01 usr + 0.00 sys = 0.01 CPU) @ 10000000.00/s (n=100000)
- (warning: too few iterations for a reliable count)
- debug: 14 wallclock secs (13.18 usr + 0.04 sys = 13.22 CPU) @ 7564.30/s (n=100000)
-
-In the one case the code, which does exactly the same thing as far as
-outputting any debugging information is concerned, in other words nothing,
-takes 14 seconds, and in the other case the code takes one hundredth of a
-second. Looks fairly definitive. Use a C<$DEBUG> variable BEFORE you call the
-subroutine, rather than relying on the smart functionality inside it.
-
-=head2 Logging if DEBUG (constant)
-
-It's possible to take the previous idea a little further, by using a compile
-time C<DEBUG> constant.
-
-# ifdebug-constant
-
- #!/usr/bin/perl
-
- use strict;
- use warnings;
-
- use Benchmark;
- use Data::Dumper;
- use constant
- DEBUG => 0
- ;
-
- sub debug {
- if ( DEBUG ) {
- my $msg = shift;
- print "DEBUG: $msg\n";
- }
- };
-
- timethese(100000, {
- 'debug' => sub {
- debug( "A $0 logging message via process-id: $$" . Dumper(\%INC) )
- },
- 'constant' => sub {
- debug( "A $0 logging message via process-id: $$" . Dumper(\%INC) ) if DEBUG
- },
- });
-
-Running this program produces the following output:
-
- $> perl ifdebug-constant
- Benchmark: timing 100000 iterations of constant, sub...
- constant: 0 wallclock secs (-0.00 usr + 0.00 sys = -0.00 CPU) @ -7205759403792793600000.00/s (n=100000)
- (warning: too few iterations for a reliable count)
- sub: 14 wallclock secs (13.09 usr + 0.00 sys = 13.09 CPU) @ 7639.42/s (n=100000)
-
-The C<DEBUG> constant wipes the floor with even the C<$debug> variable,
-clocking in at minus zero seconds, and generates a "warning: too few iterations
-for a reliable count" message into the bargain. To see what is really going
-on, and why we had too few iterations when we thought we asked for 100000, we
-can use the very useful C<B::Deparse> to inspect the new code:
-
- $> perl -MO=Deparse ifdebug-constant
-
- use Benchmark;
- use Data::Dumper;
- use constant ('DEBUG', 0);
- sub debug {
- use warnings;
- use strict 'refs';
- 0;
- }
- use warnings;
- use strict 'refs';
- timethese(100000, {'sub', sub {
- debug "A $0 logging message via process-id: $$" . Dumper(\%INC);
- }
- , 'constant', sub {
- 0;
- }
- });
- ifdebug-constant syntax OK
-
-The output shows the constant() subroutine we're testing being replaced with
-the value of the C<DEBUG> constant: zero. The line to be tested has been
-completely optimized away, and you can't get much more efficient than that.
-
-=head1 POSTSCRIPT
-
-This document has provided several way to go about identifying hot-spots, and
-checking whether any modifications have improved the runtime of the code.
-
-As a final thought, remember that it's not (at the time of writing) possible to
-produce a useful program which will run in zero or negative time and this basic
-principle can be written as: I<useful programs are slow> by their very
-definition. It is of course possible to write a nearly instantaneous program,
-but it's not going to do very much, here's a very efficient one:
-
- $> perl -e 0
-
-Optimizing that any further is a job for C<p5p>.
-
-=head1 SEE ALSO
-
-Further reading can be found using the modules and links below.
-
-=head2 PERLDOCS
-
-For example: C<perldoc -f sort>.
-
-L<perlfaq4>.
-
-L<perlfork>, L<perlfunc>, L<perlretut>, L<perlthrtut>.
-
-L<threads>.
-
-=head2 MAN PAGES
-
-C<time>.
-
-=head2 MODULES
-
-It's not possible to individually showcase all the performance related code for
-Perl here, naturally, but here's a short list of modules from the CPAN which
-deserve further attention.
-
- Apache::DProf
- Apache::SmallProf
- Benchmark
- DBIx::Profile
- Devel::AutoProfiler
- Devel::DProf
- Devel::DProfLB
- Devel::FastProf
- Devel::GraphVizProf
- Devel::NYTProf
- Devel::NYTProf::Apache
- Devel::Profiler
- Devel::Profile
- Devel::Profit
- Devel::SmallProf
- Devel::WxProf
- POE::Devel::Profiler
- Sort::Key
- Sort::Maker
-
-=head2 URLS
-
-Very useful online reference material:
-
- http://www.ccl4.org/~nick/P/Fast_Enough/
-
- http://www-128.ibm.com/developerworks/library/l-optperl.html
-
- http://perlbuzz.com/2007/11/bind-output-variables-in-dbi-for-speed-and-safety.html
-
- http://en.wikipedia.org/wiki/Performance_analysis
-
- http://apache.perl.org/docs/1.0/guide/performance.html
-
- http://perlgolf.sourceforge.net/
-
- http://www.sysarch.com/Perl/sort_paper.html
-
-=head1 AUTHOR
-
-Richard Foley <richard.foley@rfi.net> Copyright (c) 2008
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlplan9.pod b/Master/tlpkg/tlperl/lib/pods/perlplan9.pod
deleted file mode 100644
index 5e53c05bdb9..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlplan9.pod
+++ /dev/null
@@ -1,146 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you see.
-It is written in the POD format (see pod/perlpod.pod) which is specially
-designed to be readable as is.
-
-=head1 NAME
-
-perlplan9 - Plan 9-specific documentation for Perl
-
-=head1 DESCRIPTION
-
-These are a few notes describing features peculiar to
-Plan 9 Perl. As such, it is not intended to be a replacement
-for the rest of the Perl 5 documentation (which is both
-copious and excellent). If you have any questions to
-which you can't find answers in these man pages, contact
-Luther Huffman at lutherh@stratcom.com and we'll try to
-answer them.
-
-=head2 Invoking Perl
-
-Perl is invoked from the command line as described in
-L<perl>. Most perl scripts, however, do have a first line
-such as "#!/usr/local/bin/perl". This is known as a shebang
-(shell-bang) statement and tells the OS shell where to find
-the perl interpreter. In Plan 9 Perl this statement should be
-"#!/bin/perl" if you wish to be able to directly invoke the
-script by its name.
- Alternatively, you may invoke perl with the command "Perl"
-instead of "perl". This will produce Acme-friendly error
-messages of the form "filename:18".
-
-Some scripts, usually identified with a *.PL extension, are
-self-configuring and are able to correctly create their own
-shebang path from config information located in Plan 9
-Perl. These you won't need to be worried about.
-
-=head2 What's in Plan 9 Perl
-
-Although Plan 9 Perl currently only provides static
-loading, it is built with a number of useful extensions.
-These include Opcode, FileHandle, Fcntl, and POSIX. Expect
-to see others (and DynaLoading!) in the future.
-
-=head2 What's not in Plan 9 Perl
-
-As mentioned previously, dynamic loading isn't currently
-available nor is MakeMaker. Both are high-priority items.
-
-=head2 Perl5 Functions not currently supported in Plan 9 Perl
-
-Some, such as C<chown> and C<umask> aren't provided
-because the concept does not exist within Plan 9. Others,
-such as some of the socket-related functions, simply
-haven't been written yet. Many in the latter category
-may be supported in the future.
-
-The functions not currently implemented include:
-
- chown, chroot, dbmclose, dbmopen, getsockopt,
- setsockopt, recvmsg, sendmsg, getnetbyname,
- getnetbyaddr, getnetent, getprotoent, getservent,
- sethostent, setnetent, setprotoent, setservent,
- endservent, endnetent, endprotoent, umask
-
-There may be several other functions that have undefined
-behavior so this list shouldn't be considered complete.
-
-=head2 Signals in Plan 9 Perl
-
-For compatibility with perl scripts written for the Unix
-environment, Plan 9 Perl uses the POSIX signal emulation
-provided in Plan 9's ANSI POSIX Environment (APE). Signal stacking
-isn't supported. The signals provided are:
-
- SIGHUP, SIGINT, SIGQUIT, SIGILL, SIGABRT,
- SIGFPE, SIGKILL, SIGSEGV, SIGPIPE, SIGPIPE, SIGALRM,
- SIGTERM, SIGUSR1, SIGUSR2, SIGCHLD, SIGCONT,
- SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU
-
-=head1 COMPILING AND INSTALLING PERL ON PLAN 9
-
-WELCOME to Plan 9 Perl, brave soul!
-
- This is a preliminary alpha version of Plan 9 Perl. Still to be
-implemented are MakeMaker and DynaLoader. Many perl commands are
-missing or currently behave in an inscrutable manner. These gaps will,
-with perseverance and a modicum of luck, be remedied in the near
-future.To install this software:
-
-1. Create the source directories and libraries for perl by running the
-plan9/setup.rc command (i.e., located in the plan9 subdirectory).
-Note: the setup routine assumes that you haven't dearchived these
-files into /sys/src/cmd/perl. After running setup.rc you may delete
-the copy of the source you originally detarred, as source code has now
-been installed in /sys/src/cmd/perl. If you plan on installing perl
-binaries for all architectures, run "setup.rc -a".
-
-2. After making sure that you have adequate privileges to build system
-software, from /sys/src/cmd/perl/5.00301 (adjust version
-appropriately) run:
-
- mk install
-
-If you wish to install perl versions for all architectures (68020,
-mips, sparc and 386) run:
-
- mk installall
-
-3. Wait. The build process will take a *long* time because perl
-bootstraps itself. A 75MHz Pentium, 16MB RAM machine takes roughly 30
-minutes to build the distribution from scratch.
-
-=head2 Installing Perl Documentation on Plan 9
-
-This perl distribution comes with a tremendous amount of
-documentation. To add these to the built-in manuals that come with
-Plan 9, from /sys/src/cmd/perl/5.00301 (adjust version appropriately)
-run:
-
- mk man
-
-To begin your reading, start with:
-
- man perl
-
-This is a good introduction and will direct you towards other man
-pages that may interest you.
-
-(Note: "mk man" may produce some extraneous noise. Fear not.)
-
-=head1 BUGS
-
-"As many as there are grains of sand on all the beaches of the
-world . . ." - Carl Sagan
-
-=head1 Revision date
-
-This document was revised 09-October-1996 for Perl 5.003_7.
-
-=head1 AUTHOR
-
-Direct questions, comments, and the unlikely bug report (ahem) direct
-comments toward:
-
-Luther Huffman, lutherh@stratcom.com,
-Strategic Computer Solutions, Inc.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlpod.pod b/Master/tlpkg/tlperl/lib/pods/perlpod.pod
deleted file mode 100644
index 0491dec1b7b..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlpod.pod
+++ /dev/null
@@ -1,737 +0,0 @@
-
-=for comment
-This document is in Pod format. To read this, use a Pod formatter,
-like "perldoc perlpod".
-
-=head1 NAME
-X<POD> X<plain old documentation>
-
-perlpod - the Plain Old Documentation format
-
-=head1 DESCRIPTION
-
-Pod is a simple-to-use markup language used for writing documentation
-for Perl, Perl programs, and Perl modules.
-
-Translators are available for converting Pod to various formats
-like plain text, HTML, man pages, and more.
-
-Pod markup consists of three basic kinds of paragraphs:
-L<ordinary|/"Ordinary Paragraph">,
-L<verbatim|/"Verbatim Paragraph">, and
-L<command|/"Command Paragraph">.
-
-
-=head2 Ordinary Paragraph
-X<POD, ordinary paragraph>
-
-Most paragraphs in your documentation will be ordinary blocks
-of text, like this one. You can simply type in your text without
-any markup whatsoever, and with just a blank line before and
-after. When it gets formatted, it will undergo minimal formatting,
-like being rewrapped, probably put into a proportionally spaced
-font, and maybe even justified.
-
-You can use formatting codes in ordinary paragraphs, for B<bold>,
-I<italic>, C<code-style>, L<hyperlinks|perlfaq>, and more. Such
-codes are explained in the "L<Formatting Codes|/"Formatting Codes">"
-section, below.
-
-
-=head2 Verbatim Paragraph
-X<POD, verbatim paragraph> X<verbatim>
-
-Verbatim paragraphs are usually used for presenting a codeblock or
-other text which does not require any special parsing or formatting,
-and which shouldn't be wrapped.
-
-A verbatim paragraph is distinguished by having its first character
-be a space or a tab. (And commonly, all its lines begin with spaces
-and/or tabs.) It should be reproduced exactly, with tabs assumed to
-be on 8-column boundaries. There are no special formatting codes,
-so you can't italicize or anything like that. A \ means \, and
-nothing else.
-
-
-=head2 Command Paragraph
-X<POD, command>
-
-A command paragraph is used for special treatment of whole chunks
-of text, usually as headings or parts of lists.
-
-All command paragraphs (which are typically only one line long) start
-with "=", followed by an identifier, followed by arbitrary text that
-the command can use however it pleases. Currently recognized commands
-are
-
- =pod
- =head1 Heading Text
- =head2 Heading Text
- =head3 Heading Text
- =head4 Heading Text
- =over indentlevel
- =item stuff
- =back
- =begin format
- =end format
- =for format text...
- =encoding type
- =cut
-
-To explain them each in detail:
-
-=over
-
-=item C<=head1 I<Heading Text>>
-X<=head1> X<=head2> X<=head3> X<=head4>
-X<head1> X<head2> X<head3> X<head4>
-
-=item C<=head2 I<Heading Text>>
-
-=item C<=head3 I<Heading Text>>
-
-=item C<=head4 I<Heading Text>>
-
-Head1 through head4 produce headings, head1 being the highest
-level. The text in the rest of this paragraph is the content of the
-heading. For example:
-
- =head2 Object Attributes
-
-The text "Object Attributes" comprises the heading there. (Note that
-head3 and head4 are recent additions, not supported in older Pod
-translators.) The text in these heading commands can use
-formatting codes, as seen here:
-
- =head2 Possible Values for C<$/>
-
-Such commands are explained in the
-"L<Formatting Codes|/"Formatting Codes">" section, below.
-
-=item C<=over I<indentlevel>>
-X<=over> X<=item> X<=back> X<over> X<item> X<back>
-
-=item C<=item I<stuff...>>
-
-=item C<=back>
-
-Item, over, and back require a little more explanation: "=over" starts
-a region specifically for the generation of a list using "=item"
-commands, or for indenting (groups of) normal paragraphs. At the end
-of your list, use "=back" to end it. The I<indentlevel> option to
-"=over" indicates how far over to indent, generally in ems (where
-one em is the width of an "M" in the document's base font) or roughly
-comparable units; if there is no I<indentlevel> option, it defaults
-to four. (And some formatters may just ignore whatever I<indentlevel>
-you provide.) In the I<stuff> in C<=item I<stuff...>>, you may
-use formatting codes, as seen here:
-
- =item Using C<$|> to Control Buffering
-
-Such commands are explained in the
-"L<Formatting Codes|/"Formatting Codes">" section, below.
-
-Note also that there are some basic rules to using "=over" ...
-"=back" regions:
-
-=over
-
-=item *
-
-Don't use "=item"s outside of an "=over" ... "=back" region.
-
-=item *
-
-The first thing after the "=over" command should be an "=item", unless
-there aren't going to be any items at all in this "=over" ... "=back"
-region.
-
-=item *
-
-Don't put "=headI<n>" commands inside an "=over" ... "=back" region.
-
-=item *
-
-And perhaps most importantly, keep the items consistent: either use
-"=item *" for all of them, to produce bullets; or use "=item 1.",
-"=item 2.", etc., to produce numbered lists; or use "=item foo",
-"=item bar", etc.--namely, things that look nothing like bullets or
-numbers.
-
-If you start with bullets or numbers, stick with them, as
-formatters use the first "=item" type to decide how to format the
-list.
-
-=back
-
-=item C<=cut>
-X<=cut> X<cut>
-
-To end a Pod block, use a blank line,
-then a line beginning with "=cut", and a blank
-line after it. This lets Perl (and the Pod formatter) know that
-this is where Perl code is resuming. (The blank line before the "=cut"
-is not technically necessary, but many older Pod processors require it.)
-
-=item C<=pod>
-X<=pod> X<pod>
-
-The "=pod" command by itself doesn't do much of anything, but it
-signals to Perl (and Pod formatters) that a Pod block starts here. A
-Pod block starts with I<any> command paragraph, so a "=pod" command is
-usually used just when you want to start a Pod block with an ordinary
-paragraph or a verbatim paragraph. For example:
-
- =item stuff()
-
- This function does stuff.
-
- =cut
-
- sub stuff {
- ...
- }
-
- =pod
-
- Remember to check its return value, as in:
-
- stuff() || die "Couldn't do stuff!";
-
- =cut
-
-=item C<=begin I<formatname>>
-X<=begin> X<=end> X<=for> X<begin> X<end> X<for>
-
-=item C<=end I<formatname>>
-
-=item C<=for I<formatname> I<text...>>
-
-For, begin, and end will let you have regions of text/code/data that
-are not generally interpreted as normal Pod text, but are passed
-directly to particular formatters, or are otherwise special. A
-formatter that can use that format will use the region, otherwise it
-will be completely ignored.
-
-A command "=begin I<formatname>", some paragraphs, and a
-command "=end I<formatname>", mean that the text/data in between
-is meant for formatters that understand the special format
-called I<formatname>. For example,
-
- =begin html
-
- <hr> <img src="thang.png">
- <p> This is a raw HTML paragraph </p>
-
- =end html
-
-The command "=for I<formatname> I<text...>"
-specifies that the remainder of just this paragraph (starting
-right after I<formatname>) is in that special format.
-
- =for html <hr> <img src="thang.png">
- <p> This is a raw HTML paragraph </p>
-
-This means the same thing as the above "=begin html" ... "=end html"
-region.
-
-That is, with "=for", you can have only one paragraph's worth
-of text (i.e., the text in "=foo targetname text..."), but with
-"=begin targetname" ... "=end targetname", you can have any amount
-of stuff in between. (Note that there still must be a blank line
-after the "=begin" command and a blank line before the "=end"
-command.
-
-Here are some examples of how to use these:
-
- =begin html
-
- <br>Figure 1.<br><IMG SRC="figure1.png"><br>
-
- =end html
-
- =begin text
-
- ---------------
- | foo |
- | bar |
- ---------------
-
- ^^^^ Figure 1. ^^^^
-
- =end text
-
-Some format names that formatters currently are known to accept
-include "roff", "man", "latex", "tex", "text", and "html". (Some
-formatters will treat some of these as synonyms.)
-
-A format name of "comment" is common for just making notes (presumably
-to yourself) that won't appear in any formatted version of the Pod
-document:
-
- =for comment
- Make sure that all the available options are documented!
-
-Some I<formatnames> will require a leading colon (as in
-C<"=for :formatname">, or
-C<"=begin :formatname" ... "=end :formatname">),
-to signal that the text is not raw data, but instead I<is> Pod text
-(i.e., possibly containing formatting codes) that's just not for
-normal formatting (e.g., may not be a normal-use paragraph, but might
-be for formatting as a footnote).
-
-=item C<=encoding I<encodingname>>
-X<=encoding> X<encoding>
-
-This command is used for declaring the encoding of a document. Most
-users won't need this; but if your encoding isn't US-ASCII or Latin-1,
-then put a C<=encoding I<encodingname>> command early in the document so
-that pod formatters will know how to decode the document. For
-I<encodingname>, use a name recognized by the L<Encode::Supported>
-module. Examples:
-
- =encoding utf8
-
- =encoding koi8-r
-
- =encoding ShiftJIS
-
- =encoding big5
-
-=back
-
-C<=encoding> affects the whole document, and must occur only once.
-
-And don't forget, when using any other command, that the command lasts up
-until the end of its I<paragraph>, not its line. So in the
-examples below, you can see that every command needs the blank
-line after it, to end its paragraph.
-
-Some examples of lists include:
-
- =over
-
- =item *
-
- First item
-
- =item *
-
- Second item
-
- =back
-
- =over
-
- =item Foo()
-
- Description of Foo function
-
- =item Bar()
-
- Description of Bar function
-
- =back
-
-
-=head2 Formatting Codes
-X<POD, formatting code> X<formatting code>
-X<POD, interior sequence> X<interior sequence>
-
-In ordinary paragraphs and in some command paragraphs, various
-formatting codes (a.k.a. "interior sequences") can be used:
-
-=for comment
- "interior sequences" is such an opaque term.
- Prefer "formatting codes" instead.
-
-=over
-
-=item C<IE<lt>textE<gt>> -- italic text
-X<I> X<< IZ<><> >> X<POD, formatting code, italic> X<italic>
-
-Used for emphasis ("C<be IE<lt>careful!E<gt>>") and parameters
-("C<redo IE<lt>LABELE<gt>>")
-
-=item C<BE<lt>textE<gt>> -- bold text
-X<B> X<< BZ<><> >> X<POD, formatting code, bold> X<bold>
-
-Used for switches ("C<perl's BE<lt>-nE<gt> switch>"), programs
-("C<some systems provide a BE<lt>chfnE<gt> for that>"),
-emphasis ("C<be BE<lt>careful!E<gt>>"), and so on
-("C<and that feature is known as BE<lt>autovivificationE<gt>>").
-
-=item C<CE<lt>codeE<gt>> -- code text
-X<C> X<< CZ<><> >> X<POD, formatting code, code> X<code>
-
-Renders code in a typewriter font, or gives some other indication that
-this represents program text ("C<CE<lt>gmtime($^T)E<gt>>") or some other
-form of computerese ("C<CE<lt>drwxr-xr-xE<gt>>").
-
-=item C<LE<lt>nameE<gt>> -- a hyperlink
-X<L> X<< LZ<><> >> X<POD, formatting code, hyperlink> X<hyperlink>
-
-There are various syntaxes, listed below. In the syntaxes given,
-C<text>, C<name>, and C<section> cannot contain the characters
-'/' and '|'; and any '<' or '>' should be matched.
-
-=over
-
-=item *
-
-C<LE<lt>nameE<gt>>
-
-Link to a Perl manual page (e.g., C<LE<lt>Net::PingE<gt>>). Note
-that C<name> should not contain spaces. This syntax
-is also occasionally used for references to Unix man pages, as in
-C<LE<lt>crontab(5)E<gt>>.
-
-=item *
-
-C<LE<lt>name/"sec"E<gt>> or C<LE<lt>name/secE<gt>>
-
-Link to a section in other manual page. E.g.,
-C<LE<lt>perlsyn/"For Loops"E<gt>>
-
-=item *
-
-C<LE<lt>/"sec"E<gt>> or C<LE<lt>/secE<gt>>
-
-Link to a section in this manual page. E.g.,
-C<LE<lt>/"Object Methods"E<gt>>
-
-=back
-
-A section is started by the named heading or item. For
-example, C<LE<lt>perlvar/$.E<gt>> or C<LE<lt>perlvar/"$."E<gt>> both
-link to the section started by "C<=item $.>" in perlvar. And
-C<LE<lt>perlsyn/For LoopsE<gt>> or C<LE<lt>perlsyn/"For Loops"E<gt>>
-both link to the section started by "C<=head2 For Loops>"
-in perlsyn.
-
-To control what text is used for display, you
-use "C<LE<lt>text|...E<gt>>", as in:
-
-=over
-
-=item *
-
-C<LE<lt>text|nameE<gt>>
-
-Link this text to that manual page. E.g.,
-C<LE<lt>Perl Error Messages|perldiagE<gt>>
-
-=item *
-
-C<LE<lt>text|name/"sec"E<gt>> or C<LE<lt>text|name/secE<gt>>
-
-Link this text to that section in that manual page. E.g.,
-C<LE<lt>postfix "if"|perlsyn/"Statement Modifiers"E<gt>>
-
-=item *
-
-C<LE<lt>text|/"sec"E<gt>> or C<LE<lt>text|/secE<gt>>
-or C<LE<lt>text|"sec"E<gt>>
-
-Link this text to that section in this manual page. E.g.,
-C<LE<lt>the various attributes|/"Member Data"E<gt>>
-
-=back
-
-Or you can link to a web page:
-
-=over
-
-=item *
-
-C<LE<lt>scheme:...E<gt>>
-
-C<LE<lt>text|scheme:...E<gt>>
-
-Links to an absolute URL. For example, C<LE<lt>http://www.perl.org/E<gt>> or
-C<LE<lt>The Perl Home Page|http://www.perl.org/E<gt>>.
-
-=back
-
-=item C<EE<lt>escapeE<gt>> -- a character escape
-X<E> X<< EZ<><> >> X<POD, formatting code, escape> X<escape>
-
-Very similar to HTML/XML C<&I<foo>;> "entity references":
-
-=over
-
-=item *
-
-C<EE<lt>ltE<gt>> -- a literal E<lt> (less than)
-
-=item *
-
-C<EE<lt>gtE<gt>> -- a literal E<gt> (greater than)
-
-=item *
-
-C<EE<lt>verbarE<gt>> -- a literal | (I<ver>tical I<bar>)
-
-=item *
-
-C<EE<lt>solE<gt>> -- a literal / (I<sol>idus)
-
-The above four are optional except in other formatting codes,
-notably C<LE<lt>...E<gt>>, and when preceded by a
-capital letter.
-
-=item *
-
-C<EE<lt>htmlnameE<gt>>
-
-Some non-numeric HTML entity name, such as C<EE<lt>eacuteE<gt>>,
-meaning the same thing as C<&eacute;> in HTML -- i.e., a lowercase
-e with an acute (/-shaped) accent.
-
-=item *
-
-C<EE<lt>numberE<gt>>
-
-The ASCII/Latin-1/Unicode character with that number. A
-leading "0x" means that I<number> is hex, as in
-C<EE<lt>0x201EE<gt>>. A leading "0" means that I<number> is octal,
-as in C<EE<lt>075E<gt>>. Otherwise I<number> is interpreted as being
-in decimal, as in C<EE<lt>181E<gt>>.
-
-Note that older Pod formatters might not recognize octal or
-hex numeric escapes, and that many formatters cannot reliably
-render characters above 255. (Some formatters may even have
-to use compromised renderings of Latin-1 characters, like
-rendering C<EE<lt>eacuteE<gt>> as just a plain "e".)
-
-=back
-
-=item C<FE<lt>filenameE<gt>> -- used for filenames
-X<F> X<< FZ<><> >> X<POD, formatting code, filename> X<filename>
-
-Typically displayed in italics. Example: "C<FE<lt>.cshrcE<gt>>"
-
-=item C<SE<lt>textE<gt>> -- text contains non-breaking spaces
-X<S> X<< SZ<><> >> X<POD, formatting code, non-breaking space>
-X<non-breaking space>
-
-This means that the words in I<text> should not be broken
-across lines. Example: S<C<SE<lt>$x ? $y : $zE<gt>>>.
-
-=item C<XE<lt>topic nameE<gt>> -- an index entry
-X<X> X<< XZ<><> >> X<POD, formatting code, index entry> X<index entry>
-
-This is ignored by most formatters, but some may use it for building
-indexes. It always renders as empty-string.
-Example: C<XE<lt>absolutizing relative URLsE<gt>>
-
-=item C<ZE<lt>E<gt>> -- a null (zero-effect) formatting code
-X<Z> X<< ZZ<><> >> X<POD, formatting code, null> X<null>
-
-This is rarely used. It's one way to get around using an
-EE<lt>...E<gt> code sometimes. For example, instead of
-"C<NEE<lt>ltE<gt>3>" (for "NE<lt>3") you could write
-"C<NZE<lt>E<gt>E<lt>3>" (the "ZE<lt>E<gt>" breaks up the "N" and
-the "E<lt>" so they can't be considered
-the part of a (fictitious) "NE<lt>...E<gt>" code.
-
-=for comment
- This was formerly explained as a "zero-width character". But it in
- most parser models, it parses to nothing at all, as opposed to parsing
- as if it were a E<zwnj> or E<zwj>, which are REAL zero-width characters.
- So "width" and "character" are exactly the wrong words.
-
-=back
-
-Most of the time, you will need only a single set of angle brackets to
-delimit the beginning and end of formatting codes. However,
-sometimes you will want to put a real right angle bracket (a
-greater-than sign, '>') inside of a formatting code. This is particularly
-common when using a formatting code to provide a different font-type for a
-snippet of code. As with all things in Perl, there is more than
-one way to do it. One way is to simply escape the closing bracket
-using an C<E> code:
-
- C<$a E<lt>=E<gt> $b>
-
-This will produce: "C<$a E<lt>=E<gt> $b>"
-
-A more readable, and perhaps more "plain" way is to use an alternate
-set of delimiters that doesn't require a single ">" to be escaped.
-Doubled angle brackets ("<<" and ">>") may be used I<if and only if there is
-whitespace right after the opening delimiter and whitespace right
-before the closing delimiter!> For example, the following will
-do the trick:
-X<POD, formatting code, escaping with multiple brackets>
-
- C<< $a <=> $b >>
-
-In fact, you can use as many repeated angle-brackets as you like so
-long as you have the same number of them in the opening and closing
-delimiters, and make sure that whitespace immediately follows the last
-'<' of the opening delimiter, and immediately precedes the first '>'
-of the closing delimiter. (The whitespace is ignored.) So the
-following will also work:
-X<POD, formatting code, escaping with multiple brackets>
-
- C<<< $a <=> $b >>>
- C<<<< $a <=> $b >>>>
-
-And they all mean exactly the same as this:
-
- C<$a E<lt>=E<gt> $b>
-
-The multiple-bracket form does not affect the interpretation of the contents of
-the formatting code, only how it must end. That means that the examples above
-are also exactly the same as this:
-
- C<< $a E<lt>=E<gt> $b >>
-
-As a further example, this means that if you wanted to put these bits of
-code in C<C> (code) style:
-
- open(X, ">>thing.dat") || die $!
- $foo->bar();
-
-you could do it like so:
-
- C<<< open(X, ">>thing.dat") || die $! >>>
- C<< $foo->bar(); >>
-
-which is presumably easier to read than the old way:
-
- C<open(X, "E<gt>E<gt>thing.dat") || die $!>
- C<$foo-E<gt>bar();>
-
-This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man),
-and any other pod2xxx or Pod::Xxxx translators that use
-Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later.
-
-=head2 The Intent
-X<POD, intent of>
-
-The intent is simplicity of use, not power of expression. Paragraphs
-look like paragraphs (block format), so that they stand out
-visually, and so that I could run them through C<fmt> easily to reformat
-them (that's F7 in my version of B<vi>, or Esc Q in my version of
-B<emacs>). I wanted the translator to always leave the C<'> and C<`> and
-C<"> quotes alone, in verbatim mode, so I could slurp in a
-working program, shift it over four spaces, and have it print out, er,
-verbatim. And presumably in a monospace font.
-
-The Pod format is not necessarily sufficient for writing a book. Pod
-is just meant to be an idiot-proof common source for nroff, HTML,
-TeX, and other markup languages, as used for online
-documentation. Translators exist for B<pod2text>, B<pod2html>,
-B<pod2man> (that's for nroff(1) and troff(1)), B<pod2latex>, and
-B<pod2fm>. Various others are available in CPAN.
-
-
-=head2 Embedding Pods in Perl Modules
-X<POD, embedding>
-
-You can embed Pod documentation in your Perl modules and scripts.
-Start your documentation with an empty line, a "=head1" command at the
-beginning, and end it with a "=cut" command and an empty line. Perl
-will ignore the Pod text. See any of the supplied library modules for
-examples. If you're going to put your Pod at the end of the file, and
-you're using an __END__ or __DATA__ cut mark, make sure to put an
-empty line there before the first Pod command.
-
- __END__
-
- =head1 NAME
-
- Time::Local - efficiently compute time from local and GMT time
-
-Without that empty line before the "=head1", many translators wouldn't
-have recognized the "=head1" as starting a Pod block.
-
-=head2 Hints for Writing Pod
-
-=over
-
-=item *
-X<podchecker> X<POD, validating>
-
-The B<podchecker> command is provided for checking Pod syntax for errors
-and warnings. For example, it checks for completely blank lines in
-Pod blocks and for unknown commands and formatting codes. You should
-still also pass your document through one or more translators and proofread
-the result, or print out the result and proofread that. Some of the
-problems found may be bugs in the translators, which you may or may not
-wish to work around.
-
-=item *
-
-If you're more familiar with writing in HTML than with writing in Pod, you
-can try your hand at writing documentation in simple HTML, and converting
-it to Pod with the experimental L<Pod::HTML2Pod|Pod::HTML2Pod> module,
-(available in CPAN), and looking at the resulting code. The experimental
-L<Pod::PXML|Pod::PXML> module in CPAN might also be useful.
-
-=item *
-
-Many older Pod translators require the lines before every Pod
-command and after every Pod command (including "=cut"!) to be a blank
-line. Having something like this:
-
- # - - - - - - - - - - - -
- =item $firecracker->boom()
-
- This noisily detonates the firecracker object.
- =cut
- sub boom {
- ...
-
-...will make such Pod translators completely fail to see the Pod block
-at all.
-
-Instead, have it like this:
-
- # - - - - - - - - - - - -
-
- =item $firecracker->boom()
-
- This noisily detonates the firecracker object.
-
- =cut
-
- sub boom {
- ...
-
-=item *
-
-Some older Pod translators require paragraphs (including command
-paragraphs like "=head2 Functions") to be separated by I<completely>
-empty lines. If you have an apparently empty line with some spaces
-on it, this might not count as a separator for those translators, and
-that could cause odd formatting.
-
-=item *
-
-Older translators might add wording around an LE<lt>E<gt> link, so that
-C<LE<lt>Foo::BarE<gt>> may become "the Foo::Bar manpage", for example.
-So you shouldn't write things like C<the LE<lt>fooE<gt>
-documentation>, if you want the translated document to read sensibly.
-Instead, write C<the LE<lt>Foo::Bar|Foo::BarE<gt> documentation> or
-C<LE<lt>the Foo::Bar documentation|Foo::BarE<gt>>, to control how the
-link comes out.
-
-=item *
-
-Going past the 70th column in a verbatim block might be ungracefully
-wrapped by some formatters.
-
-=back
-
-=head1 SEE ALSO
-
-L<perlpodspec>, L<perlsyn/"PODs: Embedded Documentation">,
-L<perlnewmod>, L<perldoc>, L<pod2html>, L<pod2man>, L<podchecker>.
-
-=head1 AUTHOR
-
-Larry Wall, Sean M. Burke
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlpodspec.pod b/Master/tlpkg/tlperl/lib/pods/perlpodspec.pod
deleted file mode 100644
index 89fd9ba6f81..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlpodspec.pod
+++ /dev/null
@@ -1,1916 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perlpodspec - Plain Old Documentation: format specification and notes
-
-=head1 DESCRIPTION
-
-This document is detailed notes on the Pod markup language. Most
-people will only have to read L<perlpod|perlpod> to know how to write
-in Pod, but this document may answer some incidental questions to do
-with parsing and rendering Pod.
-
-In this document, "must" / "must not", "should" /
-"should not", and "may" have their conventional (cf. RFC 2119)
-meanings: "X must do Y" means that if X doesn't do Y, it's against
-this specification, and should really be fixed. "X should do Y"
-means that it's recommended, but X may fail to do Y, if there's a
-good reason. "X may do Y" is merely a note that X can do Y at
-will (although it is up to the reader to detect any connotation of
-"and I think it would be I<nice> if X did Y" versus "it wouldn't
-really I<bother> me if X did Y").
-
-Notably, when I say "the parser should do Y", the
-parser may fail to do Y, if the calling application explicitly
-requests that the parser I<not> do Y. I often phrase this as
-"the parser should, by default, do Y." This doesn't I<require>
-the parser to provide an option for turning off whatever
-feature Y is (like expanding tabs in verbatim paragraphs), although
-it implicates that such an option I<may> be provided.
-
-=head1 Pod Definitions
-
-Pod is embedded in files, typically Perl source files, although you
-can write a file that's nothing but Pod.
-
-A B<line> in a file consists of zero or more non-newline characters,
-terminated by either a newline or the end of the file.
-
-A B<newline sequence> is usually a platform-dependent concept, but
-Pod parsers should understand it to mean any of CR (ASCII 13), LF
-(ASCII 10), or a CRLF (ASCII 13 followed immediately by ASCII 10), in
-addition to any other system-specific meaning. The first CR/CRLF/LF
-sequence in the file may be used as the basis for identifying the
-newline sequence for parsing the rest of the file.
-
-A B<blank line> is a line consisting entirely of zero or more spaces
-(ASCII 32) or tabs (ASCII 9), and terminated by a newline or end-of-file.
-A B<non-blank line> is a line containing one or more characters other
-than space or tab (and terminated by a newline or end-of-file).
-
-(I<Note:> Many older Pod parsers did not accept a line consisting of
-spaces/tabs and then a newline as a blank line. The only lines they
-considered blank were lines consisting of I<no characters at all>,
-terminated by a newline.)
-
-B<Whitespace> is used in this document as a blanket term for spaces,
-tabs, and newline sequences. (By itself, this term usually refers
-to literal whitespace. That is, sequences of whitespace characters
-in Pod source, as opposed to "EE<lt>32>", which is a formatting
-code that I<denotes> a whitespace character.)
-
-A B<Pod parser> is a module meant for parsing Pod (regardless of
-whether this involves calling callbacks or building a parse tree or
-directly formatting it). A B<Pod formatter> (or B<Pod translator>)
-is a module or program that converts Pod to some other format (HTML,
-plaintext, TeX, PostScript, RTF). A B<Pod processor> might be a
-formatter or translator, or might be a program that does something
-else with the Pod (like counting words, scanning for index points,
-etc.).
-
-Pod content is contained in B<Pod blocks>. A Pod block starts with a
-line that matches <m/\A=[a-zA-Z]/>, and continues up to the next line
-that matches C<m/\A=cut/> or up to the end of the file if there is
-no C<m/\A=cut/> line.
-
-=for comment
- The current perlsyn says:
- [beginquote]
- Note that pod translators should look at only paragraphs beginning
- with a pod directive (it makes parsing easier), whereas the compiler
- actually knows to look for pod escapes even in the middle of a
- paragraph. This means that the following secret stuff will be ignored
- by both the compiler and the translators.
- $a=3;
- =secret stuff
- warn "Neither POD nor CODE!?"
- =cut back
- print "got $a\n";
- You probably shouldn't rely upon the warn() being podded out forever.
- Not all pod translators are well-behaved in this regard, and perhaps
- the compiler will become pickier.
- [endquote]
- I think that those paragraphs should just be removed; paragraph-based
- parsing seems to have been largely abandoned, because of the hassle
- with non-empty blank lines messing up what people meant by "paragraph".
- Even if the "it makes parsing easier" bit were especially true,
- it wouldn't be worth the confusion of having perl and pod2whatever
- actually disagree on what can constitute a Pod block.
-
-Within a Pod block, there are B<Pod paragraphs>. A Pod paragraph
-consists of non-blank lines of text, separated by one or more blank
-lines.
-
-For purposes of Pod processing, there are four types of paragraphs in
-a Pod block:
-
-=over
-
-=item *
-
-A command paragraph (also called a "directive"). The first line of
-this paragraph must match C<m/\A=[a-zA-Z]/>. Command paragraphs are
-typically one line, as in:
-
- =head1 NOTES
-
- =item *
-
-But they may span several (non-blank) lines:
-
- =for comment
- Hm, I wonder what it would look like if
- you tried to write a BNF for Pod from this.
-
- =head3 Dr. Strangelove, or: How I Learned to
- Stop Worrying and Love the Bomb
-
-I<Some> command paragraphs allow formatting codes in their content
-(i.e., after the part that matches C<m/\A=[a-zA-Z]\S*\s*/>), as in:
-
- =head1 Did You Remember to C<use strict;>?
-
-In other words, the Pod processing handler for "head1" will apply the
-same processing to "Did You Remember to CE<lt>use strict;>?" that it
-would to an ordinary paragraph (i.e., formatting codes like
-"CE<lt>...>") are parsed and presumably formatted appropriately, and
-whitespace in the form of literal spaces and/or tabs is not
-significant.
-
-=item *
-
-A B<verbatim paragraph>. The first line of this paragraph must be a
-literal space or tab, and this paragraph must not be inside a "=begin
-I<identifier>", ... "=end I<identifier>" sequence unless
-"I<identifier>" begins with a colon (":"). That is, if a paragraph
-starts with a literal space or tab, but I<is> inside a
-"=begin I<identifier>", ... "=end I<identifier>" region, then it's
-a data paragraph, unless "I<identifier>" begins with a colon.
-
-Whitespace I<is> significant in verbatim paragraphs (although, in
-processing, tabs are probably expanded).
-
-=item *
-
-An B<ordinary paragraph>. A paragraph is an ordinary paragraph
-if its first line matches neither C<m/\A=[a-zA-Z]/> nor
-C<m/\A[ \t]/>, I<and> if it's not inside a "=begin I<identifier>",
-... "=end I<identifier>" sequence unless "I<identifier>" begins with
-a colon (":").
-
-=item *
-
-A B<data paragraph>. This is a paragraph that I<is> inside a "=begin
-I<identifier>" ... "=end I<identifier>" sequence where
-"I<identifier>" does I<not> begin with a literal colon (":"). In
-some sense, a data paragraph is not part of Pod at all (i.e.,
-effectively it's "out-of-band"), since it's not subject to most kinds
-of Pod parsing; but it is specified here, since Pod
-parsers need to be able to call an event for it, or store it in some
-form in a parse tree, or at least just parse I<around> it.
-
-=back
-
-For example: consider the following paragraphs:
-
- # <- that's the 0th column
-
- =head1 Foo
-
- Stuff
-
- $foo->bar
-
- =cut
-
-Here, "=head1 Foo" and "=cut" are command paragraphs because the first
-line of each matches C<m/\A=[a-zA-Z]/>. "I<[space][space]>$foo->bar"
-is a verbatim paragraph, because its first line starts with a literal
-whitespace character (and there's no "=begin"..."=end" region around).
-
-The "=begin I<identifier>" ... "=end I<identifier>" commands stop
-paragraphs that they surround from being parsed as ordinary or verbatim
-paragraphs, if I<identifier> doesn't begin with a colon. This
-is discussed in detail in the section
-L</About Data Paragraphs and "=beginE<sol>=end" Regions>.
-
-=head1 Pod Commands
-
-This section is intended to supplement and clarify the discussion in
-L<perlpod/"Command Paragraph">. These are the currently recognized
-Pod commands:
-
-=over
-
-=item "=head1", "=head2", "=head3", "=head4"
-
-This command indicates that the text in the remainder of the paragraph
-is a heading. That text may contain formatting codes. Examples:
-
- =head1 Object Attributes
-
- =head3 What B<Not> to Do!
-
-=item "=pod"
-
-This command indicates that this paragraph begins a Pod block. (If we
-are already in the middle of a Pod block, this command has no effect at
-all.) If there is any text in this command paragraph after "=pod",
-it must be ignored. Examples:
-
- =pod
-
- This is a plain Pod paragraph.
-
- =pod This text is ignored.
-
-=item "=cut"
-
-This command indicates that this line is the end of this previously
-started Pod block. If there is any text after "=cut" on the line, it must be
-ignored. Examples:
-
- =cut
-
- =cut The documentation ends here.
-
- =cut
- # This is the first line of program text.
- sub foo { # This is the second.
-
-It is an error to try to I<start> a Pod block with a "=cut" command. In
-that case, the Pod processor must halt parsing of the input file, and
-must by default emit a warning.
-
-=item "=over"
-
-This command indicates that this is the start of a list/indent
-region. If there is any text following the "=over", it must consist
-of only a nonzero positive numeral. The semantics of this numeral is
-explained in the L</"About =over...=back Regions"> section, further
-below. Formatting codes are not expanded. Examples:
-
- =over 3
-
- =over 3.5
-
- =over
-
-=item "=item"
-
-This command indicates that an item in a list begins here. Formatting
-codes are processed. The semantics of the (optional) text in the
-remainder of this paragraph are
-explained in the L</"About =over...=back Regions"> section, further
-below. Examples:
-
- =item
-
- =item *
-
- =item *
-
- =item 14
-
- =item 3.
-
- =item C<< $thing->stuff(I<dodad>) >>
-
- =item For transporting us beyond seas to be tried for pretended
- offenses
-
- =item He is at this time transporting large armies of foreign
- mercenaries to complete the works of death, desolation and
- tyranny, already begun with circumstances of cruelty and perfidy
- scarcely paralleled in the most barbarous ages, and totally
- unworthy the head of a civilized nation.
-
-=item "=back"
-
-This command indicates that this is the end of the region begun
-by the most recent "=over" command. It permits no text after the
-"=back" command.
-
-=item "=begin formatname"
-
-=item "=begin formatname parameter"
-
-This marks the following paragraphs (until the matching "=end
-formatname") as being for some special kind of processing. Unless
-"formatname" begins with a colon, the contained non-command
-paragraphs are data paragraphs. But if "formatname" I<does> begin
-with a colon, then non-command paragraphs are ordinary paragraphs
-or data paragraphs. This is discussed in detail in the section
-L</About Data Paragraphs and "=beginE<sol>=end" Regions>.
-
-It is advised that formatnames match the regexp
-C<m/\A:?[-a-zA-Z0-9_]+\z/>. Everything following whitespace after the
-formatname is a parameter that may be used by the formatter when dealing
-with this region. This parameter must not be repeated in the "=end"
-paragraph. Implementors should anticipate future expansion in the
-semantics and syntax of the first parameter to "=begin"/"=end"/"=for".
-
-=item "=end formatname"
-
-This marks the end of the region opened by the matching
-"=begin formatname" region. If "formatname" is not the formatname
-of the most recent open "=begin formatname" region, then this
-is an error, and must generate an error message. This
-is discussed in detail in the section
-L</About Data Paragraphs and "=beginE<sol>=end" Regions>.
-
-=item "=for formatname text..."
-
-This is synonymous with:
-
- =begin formatname
-
- text...
-
- =end formatname
-
-That is, it creates a region consisting of a single paragraph; that
-paragraph is to be treated as a normal paragraph if "formatname"
-begins with a ":"; if "formatname" I<doesn't> begin with a colon,
-then "text..." will constitute a data paragraph. There is no way
-to use "=for formatname text..." to express "text..." as a verbatim
-paragraph.
-
-=item "=encoding encodingname"
-
-This command, which should occur early in the document (at least
-before any non-US-ASCII data!), declares that this document is
-encoded in the encoding I<encodingname>, which must be
-an encoding name that L<Encode> recognizes. (Encode's list
-of supported encodings, in L<Encode::Supported>, is useful here.)
-If the Pod parser cannot decode the declared encoding, it
-should emit a warning and may abort parsing the document
-altogether.
-
-A document having more than one "=encoding" line should be
-considered an error. Pod processors may silently tolerate this if
-the not-first "=encoding" lines are just duplicates of the
-first one (e.g., if there's a "=encoding utf8" line, and later on
-another "=encoding utf8" line). But Pod processors should complain if
-there are contradictory "=encoding" lines in the same document
-(e.g., if there is a "=encoding utf8" early in the document and
-"=encoding big5" later). Pod processors that recognize BOMs
-may also complain if they see an "=encoding" line
-that contradicts the BOM (e.g., if a document with a UTF-16LE
-BOM has an "=encoding shiftjis" line).
-
-=back
-
-If a Pod processor sees any command other than the ones listed
-above (like "=head", or "=haed1", or "=stuff", or "=cuttlefish",
-or "=w123"), that processor must by default treat this as an
-error. It must not process the paragraph beginning with that
-command, must by default warn of this as an error, and may
-abort the parse. A Pod parser may allow a way for particular
-applications to add to the above list of known commands, and to
-stipulate, for each additional command, whether formatting
-codes should be processed.
-
-Future versions of this specification may add additional
-commands.
-
-
-
-=head1 Pod Formatting Codes
-
-(Note that in previous drafts of this document and of perlpod,
-formatting codes were referred to as "interior sequences", and
-this term may still be found in the documentation for Pod parsers,
-and in error messages from Pod processors.)
-
-There are two syntaxes for formatting codes:
-
-=over
-
-=item *
-
-A formatting code starts with a capital letter (just US-ASCII [A-Z])
-followed by a "<", any number of characters, and ending with the first
-matching ">". Examples:
-
- That's what I<you> think!
-
- What's C<dump()> for?
-
- X<C<chmod> and C<unlink()> Under Different Operating Systems>
-
-=item *
-
-A formatting code starts with a capital letter (just US-ASCII [A-Z])
-followed by two or more "<"'s, one or more whitespace characters,
-any number of characters, one or more whitespace characters,
-and ending with the first matching sequence of two or more ">"'s, where
-the number of ">"'s equals the number of "<"'s in the opening of this
-formatting code. Examples:
-
- That's what I<< you >> think!
-
- C<<< open(X, ">>thing.dat") || die $! >>>
-
- B<< $foo->bar(); >>
-
-With this syntax, the whitespace character(s) after the "CE<lt><<"
-and before the ">>" (or whatever letter) are I<not> renderable. They
-do not signify whitespace, are merely part of the formatting codes
-themselves. That is, these are all synonymous:
-
- C<thing>
- C<< thing >>
- C<< thing >>
- C<<< thing >>>
- C<<<<
- thing
- >>>>
-
-and so on.
-
-Finally, the multiple-angle-bracket form does I<not> alter the interpretation
-of nested formatting codes, meaning that the following four example lines are
-identical in meaning:
-
- B<example: C<$a E<lt>=E<gt> $b>>
-
- B<example: C<< $a <=> $b >>>
-
- B<example: C<< $a E<lt>=E<gt> $b >>>
-
- B<<< example: C<< $a E<lt>=E<gt> $b >> >>>
-
-=back
-
-In parsing Pod, a notably tricky part is the correct parsing of
-(potentially nested!) formatting codes. Implementors should
-consult the code in the C<parse_text> routine in Pod::Parser as an
-example of a correct implementation.
-
-=over
-
-=item C<IE<lt>textE<gt>> -- italic text
-
-See the brief discussion in L<perlpod/"Formatting Codes">.
-
-=item C<BE<lt>textE<gt>> -- bold text
-
-See the brief discussion in L<perlpod/"Formatting Codes">.
-
-=item C<CE<lt>codeE<gt>> -- code text
-
-See the brief discussion in L<perlpod/"Formatting Codes">.
-
-=item C<FE<lt>filenameE<gt>> -- style for filenames
-
-See the brief discussion in L<perlpod/"Formatting Codes">.
-
-=item C<XE<lt>topic nameE<gt>> -- an index entry
-
-See the brief discussion in L<perlpod/"Formatting Codes">.
-
-This code is unusual in that most formatters completely discard
-this code and its content. Other formatters will render it with
-invisible codes that can be used in building an index of
-the current document.
-
-=item C<ZE<lt>E<gt>> -- a null (zero-effect) formatting code
-
-Discussed briefly in L<perlpod/"Formatting Codes">.
-
-This code is unusual is that it should have no content. That is,
-a processor may complain if it sees C<ZE<lt>potatoesE<gt>>. Whether
-or not it complains, the I<potatoes> text should ignored.
-
-=item C<LE<lt>nameE<gt>> -- a hyperlink
-
-The complicated syntaxes of this code are discussed at length in
-L<perlpod/"Formatting Codes">, and implementation details are
-discussed below, in L</"About LE<lt>...E<gt> Codes">. Parsing the
-contents of LE<lt>content> is tricky. Notably, the content has to be
-checked for whether it looks like a URL, or whether it has to be split
-on literal "|" and/or "/" (in the right order!), and so on,
-I<before> EE<lt>...> codes are resolved.
-
-=item C<EE<lt>escapeE<gt>> -- a character escape
-
-See L<perlpod/"Formatting Codes">, and several points in
-L</Notes on Implementing Pod Processors>.
-
-=item C<SE<lt>textE<gt>> -- text contains non-breaking spaces
-
-This formatting code is syntactically simple, but semantically
-complex. What it means is that each space in the printable
-content of this code signifies a non-breaking space.
-
-Consider:
-
- C<$x ? $y : $z>
-
- S<C<$x ? $y : $z>>
-
-Both signify the monospace (c[ode] style) text consisting of
-"$x", one space, "?", one space, ":", one space, "$z". The
-difference is that in the latter, with the S code, those spaces
-are not "normal" spaces, but instead are non-breaking spaces.
-
-=back
-
-
-If a Pod processor sees any formatting code other than the ones
-listed above (as in "NE<lt>...>", or "QE<lt>...>", etc.), that
-processor must by default treat this as an error.
-A Pod parser may allow a way for particular
-applications to add to the above list of known formatting codes;
-a Pod parser might even allow a way to stipulate, for each additional
-command, whether it requires some form of special processing, as
-LE<lt>...> does.
-
-Future versions of this specification may add additional
-formatting codes.
-
-Historical note: A few older Pod processors would not see a ">" as
-closing a "CE<lt>" code, if the ">" was immediately preceded by
-a "-". This was so that this:
-
- C<$foo->bar>
-
-would parse as equivalent to this:
-
- C<$foo-E<gt>bar>
-
-instead of as equivalent to a "C" formatting code containing
-only "$foo-", and then a "bar>" outside the "C" formatting code. This
-problem has since been solved by the addition of syntaxes like this:
-
- C<< $foo->bar >>
-
-Compliant parsers must not treat "->" as special.
-
-Formatting codes absolutely cannot span paragraphs. If a code is
-opened in one paragraph, and no closing code is found by the end of
-that paragraph, the Pod parser must close that formatting code,
-and should complain (as in "Unterminated I code in the paragraph
-starting at line 123: 'Time objects are not...'"). So these
-two paragraphs:
-
- I<I told you not to do this!
-
- Don't make me say it again!>
-
-...must I<not> be parsed as two paragraphs in italics (with the I
-code starting in one paragraph and starting in another.) Instead,
-the first paragraph should generate a warning, but that aside, the
-above code must parse as if it were:
-
- I<I told you not to do this!>
-
- Don't make me say it again!E<gt>
-
-(In SGMLish jargon, all Pod commands are like block-level
-elements, whereas all Pod formatting codes are like inline-level
-elements.)
-
-
-
-=head1 Notes on Implementing Pod Processors
-
-The following is a long section of miscellaneous requirements
-and suggestions to do with Pod processing.
-
-=over
-
-=item *
-
-Pod formatters should tolerate lines in verbatim blocks that are of
-any length, even if that means having to break them (possibly several
-times, for very long lines) to avoid text running off the side of the
-page. Pod formatters may warn of such line-breaking. Such warnings
-are particularly appropriate for lines are over 100 characters long, which
-are usually not intentional.
-
-=item *
-
-Pod parsers must recognize I<all> of the three well-known newline
-formats: CR, LF, and CRLF. See L<perlport|perlport>.
-
-=item *
-
-Pod parsers should accept input lines that are of any length.
-
-=item *
-
-Since Perl recognizes a Unicode Byte Order Mark at the start of files
-as signaling that the file is Unicode encoded as in UTF-16 (whether
-big-endian or little-endian) or UTF-8, Pod parsers should do the
-same. Otherwise, the character encoding should be understood as
-being UTF-8 if the first highbit byte sequence in the file seems
-valid as a UTF-8 sequence, or otherwise as Latin-1.
-
-Future versions of this specification may specify
-how Pod can accept other encodings. Presumably treatment of other
-encodings in Pod parsing would be as in XML parsing: whatever the
-encoding declared by a particular Pod file, content is to be
-stored in memory as Unicode characters.
-
-=item *
-
-The well known Unicode Byte Order Marks are as follows: if the
-file begins with the two literal byte values 0xFE 0xFF, this is
-the BOM for big-endian UTF-16. If the file begins with the two
-literal byte value 0xFF 0xFE, this is the BOM for little-endian
-UTF-16. If the file begins with the three literal byte values
-0xEF 0xBB 0xBF, this is the BOM for UTF-8.
-
-=for comment
- use bytes; print map sprintf(" 0x%02X", ord $_), split '', "\x{feff}";
- 0xEF 0xBB 0xBF
-
-=for comment
- If toke.c is modified to support UTF-32, add mention of those here.
-
-=item *
-
-A naive but sufficient heuristic for testing the first highbit
-byte-sequence in a BOM-less file (whether in code or in Pod!), to see
-whether that sequence is valid as UTF-8 (RFC 2279) is to check whether
-that the first byte in the sequence is in the range 0xC0 - 0xFD
-I<and> whether the next byte is in the range
-0x80 - 0xBF. If so, the parser may conclude that this file is in
-UTF-8, and all highbit sequences in the file should be assumed to
-be UTF-8. Otherwise the parser should treat the file as being
-in Latin-1. In the unlikely circumstance that the first highbit
-sequence in a truly non-UTF-8 file happens to appear to be UTF-8, one
-can cater to our heuristic (as well as any more intelligent heuristic)
-by prefacing that line with a comment line containing a highbit
-sequence that is clearly I<not> valid as UTF-8. A line consisting
-of simply "#", an e-acute, and any non-highbit byte,
-is sufficient to establish this file's encoding.
-
-=for comment
- If/WHEN some brave soul makes these heuristics into a generic
- text-file class (or PerlIO layer?), we can presumably delete
- mention of these icky details from this file, and can instead
- tell people to just use appropriate class/layer.
- Auto-recognition of newline sequences would be another desirable
- feature of such a class/layer.
- HINT HINT HINT.
-
-=for comment
- "The probability that a string of characters
- in any other encoding appears as valid UTF-8 is low" - RFC2279
-
-=item *
-
-This document's requirements and suggestions about encodings
-do not apply to Pod processors running on non-ASCII platforms,
-notably EBCDIC platforms.
-
-=item *
-
-Pod processors must treat a "=for [label] [content...]" paragraph as
-meaning the same thing as a "=begin [label]" paragraph, content, and
-an "=end [label]" paragraph. (The parser may conflate these two
-constructs, or may leave them distinct, in the expectation that the
-formatter will nevertheless treat them the same.)
-
-=item *
-
-When rendering Pod to a format that allows comments (i.e., to nearly
-any format other than plaintext), a Pod formatter must insert comment
-text identifying its name and version number, and the name and
-version numbers of any modules it might be using to process the Pod.
-Minimal examples:
-
- %% POD::Pod2PS v3.14159, using POD::Parser v1.92
-
- <!-- Pod::HTML v3.14159, using POD::Parser v1.92 -->
-
- {\doccomm generated by Pod::Tree::RTF 3.14159 using Pod::Tree 1.08}
-
- .\" Pod::Man version 3.14159, using POD::Parser version 1.92
-
-Formatters may also insert additional comments, including: the
-release date of the Pod formatter program, the contact address for
-the author(s) of the formatter, the current time, the name of input
-file, the formatting options in effect, version of Perl used, etc.
-
-Formatters may also choose to note errors/warnings as comments,
-besides or instead of emitting them otherwise (as in messages to
-STDERR, or C<die>ing).
-
-=item *
-
-Pod parsers I<may> emit warnings or error messages ("Unknown E code
-EE<lt>zslig>!") to STDERR (whether through printing to STDERR, or
-C<warn>ing/C<carp>ing, or C<die>ing/C<croak>ing), but I<must> allow
-suppressing all such STDERR output, and instead allow an option for
-reporting errors/warnings
-in some other way, whether by triggering a callback, or noting errors
-in some attribute of the document object, or some similarly unobtrusive
-mechanism -- or even by appending a "Pod Errors" section to the end of
-the parsed form of the document.
-
-=item *
-
-In cases of exceptionally aberrant documents, Pod parsers may abort the
-parse. Even then, using C<die>ing/C<croak>ing is to be avoided; where
-possible, the parser library may simply close the input file
-and add text like "*** Formatting Aborted ***" to the end of the
-(partial) in-memory document.
-
-=item *
-
-In paragraphs where formatting codes (like EE<lt>...>, BE<lt>...>)
-are understood (i.e., I<not> verbatim paragraphs, but I<including>
-ordinary paragraphs, and command paragraphs that produce renderable
-text, like "=head1"), literal whitespace should generally be considered
-"insignificant", in that one literal space has the same meaning as any
-(nonzero) number of literal spaces, literal newlines, and literal tabs
-(as long as this produces no blank lines, since those would terminate
-the paragraph). Pod parsers should compact literal whitespace in each
-processed paragraph, but may provide an option for overriding this
-(since some processing tasks do not require it), or may follow
-additional special rules (for example, specially treating
-period-space-space or period-newline sequences).
-
-=item *
-
-Pod parsers should not, by default, try to coerce apostrophe (') and
-quote (") into smart quotes (little 9's, 66's, 99's, etc), nor try to
-turn backtick (`) into anything else but a single backtick character
-(distinct from an open quote character!), nor "--" into anything but
-two minus signs. They I<must never> do any of those things to text
-in CE<lt>...> formatting codes, and never I<ever> to text in verbatim
-paragraphs.
-
-=item *
-
-When rendering Pod to a format that has two kinds of hyphens (-), one
-that's a non-breaking hyphen, and another that's a breakable hyphen
-(as in "object-oriented", which can be split across lines as
-"object-", newline, "oriented"), formatters are encouraged to
-generally translate "-" to non-breaking hyphen, but may apply
-heuristics to convert some of these to breaking hyphens.
-
-=item *
-
-Pod formatters should make reasonable efforts to keep words of Perl
-code from being broken across lines. For example, "Foo::Bar" in some
-formatting systems is seen as eligible for being broken across lines
-as "Foo::" newline "Bar" or even "Foo::-" newline "Bar". This should
-be avoided where possible, either by disabling all line-breaking in
-mid-word, or by wrapping particular words with internal punctuation
-in "don't break this across lines" codes (which in some formats may
-not be a single code, but might be a matter of inserting non-breaking
-zero-width spaces between every pair of characters in a word.)
-
-=item *
-
-Pod parsers should, by default, expand tabs in verbatim paragraphs as
-they are processed, before passing them to the formatter or other
-processor. Parsers may also allow an option for overriding this.
-
-=item *
-
-Pod parsers should, by default, remove newlines from the end of
-ordinary and verbatim paragraphs before passing them to the
-formatter. For example, while the paragraph you're reading now
-could be considered, in Pod source, to end with (and contain)
-the newline(s) that end it, it should be processed as ending with
-(and containing) the period character that ends this sentence.
-
-=item *
-
-Pod parsers, when reporting errors, should make some effort to report
-an approximate line number ("Nested EE<lt>>'s in Paragraph #52, near
-line 633 of Thing/Foo.pm!"), instead of merely noting the paragraph
-number ("Nested EE<lt>>'s in Paragraph #52 of Thing/Foo.pm!"). Where
-this is problematic, the paragraph number should at least be
-accompanied by an excerpt from the paragraph ("Nested EE<lt>>'s in
-Paragraph #52 of Thing/Foo.pm, which begins 'Read/write accessor for
-the CE<lt>interest rate> attribute...'").
-
-=item *
-
-Pod parsers, when processing a series of verbatim paragraphs one
-after another, should consider them to be one large verbatim
-paragraph that happens to contain blank lines. I.e., these two
-lines, which have a blank line between them:
-
- use Foo;
-
- print Foo->VERSION
-
-should be unified into one paragraph ("\tuse Foo;\n\n\tprint
-Foo->VERSION") before being passed to the formatter or other
-processor. Parsers may also allow an option for overriding this.
-
-While this might be too cumbersome to implement in event-based Pod
-parsers, it is straightforward for parsers that return parse trees.
-
-=item *
-
-Pod formatters, where feasible, are advised to avoid splitting short
-verbatim paragraphs (under twelve lines, say) across pages.
-
-=item *
-
-Pod parsers must treat a line with only spaces and/or tabs on it as a
-"blank line" such as separates paragraphs. (Some older parsers
-recognized only two adjacent newlines as a "blank line" but would not
-recognize a newline, a space, and a newline, as a blank line. This
-is noncompliant behavior.)
-
-=item *
-
-Authors of Pod formatters/processors should make every effort to
-avoid writing their own Pod parser. There are already several in
-CPAN, with a wide range of interface styles -- and one of them,
-Pod::Parser, comes with modern versions of Perl.
-
-=item *
-
-Characters in Pod documents may be conveyed either as literals, or by
-number in EE<lt>n> codes, or by an equivalent mnemonic, as in
-EE<lt>eacute> which is exactly equivalent to EE<lt>233>.
-
-Characters in the range 32-126 refer to those well known US-ASCII
-characters (also defined there by Unicode, with the same meaning),
-which all Pod formatters must render faithfully. Characters
-in the ranges 0-31 and 127-159 should not be used (neither as
-literals, nor as EE<lt>number> codes), except for the
-literal byte-sequences for newline (13, 13 10, or 10), and tab (9).
-
-Characters in the range 160-255 refer to Latin-1 characters (also
-defined there by Unicode, with the same meaning). Characters above
-255 should be understood to refer to Unicode characters.
-
-=item *
-
-Be warned
-that some formatters cannot reliably render characters outside 32-126;
-and many are able to handle 32-126 and 160-255, but nothing above
-255.
-
-=item *
-
-Besides the well-known "EE<lt>lt>" and "EE<lt>gt>" codes for
-less-than and greater-than, Pod parsers must understand "EE<lt>sol>"
-for "/" (solidus, slash), and "EE<lt>verbar>" for "|" (vertical bar,
-pipe). Pod parsers should also understand "EE<lt>lchevron>" and
-"EE<lt>rchevron>" as legacy codes for characters 171 and 187, i.e.,
-"left-pointing double angle quotation mark" = "left pointing
-guillemet" and "right-pointing double angle quotation mark" = "right
-pointing guillemet". (These look like little "<<" and ">>", and they
-are now preferably expressed with the HTML/XHTML codes "EE<lt>laquo>"
-and "EE<lt>raquo>".)
-
-=item *
-
-Pod parsers should understand all "EE<lt>html>" codes as defined
-in the entity declarations in the most recent XHTML specification at
-C<www.W3.org>. Pod parsers must understand at least the entities
-that define characters in the range 160-255 (Latin-1). Pod parsers,
-when faced with some unknown "EE<lt>I<identifier>>" code,
-shouldn't simply replace it with nullstring (by default, at least),
-but may pass it through as a string consisting of the literal characters
-E, less-than, I<identifier>, greater-than. Or Pod parsers may offer the
-alternative option of processing such unknown
-"EE<lt>I<identifier>>" codes by firing an event especially
-for such codes, or by adding a special node-type to the in-memory
-document tree. Such "EE<lt>I<identifier>>" may have special meaning
-to some processors, or some processors may choose to add them to
-a special error report.
-
-=item *
-
-Pod parsers must also support the XHTML codes "EE<lt>quot>" for
-character 34 (doublequote, "), "EE<lt>amp>" for character 38
-(ampersand, &), and "EE<lt>apos>" for character 39 (apostrophe, ').
-
-=item *
-
-Note that in all cases of "EE<lt>whatever>", I<whatever> (whether
-an htmlname, or a number in any base) must consist only of
-alphanumeric characters -- that is, I<whatever> must watch
-C<m/\A\w+\z/>. So "EE<lt> 0 1 2 3 >" is invalid, because
-it contains spaces, which aren't alphanumeric characters. This
-presumably does not I<need> special treatment by a Pod processor;
-" 0 1 2 3 " doesn't look like a number in any base, so it would
-presumably be looked up in the table of HTML-like names. Since
-there isn't (and cannot be) an HTML-like entity called " 0 1 2 3 ",
-this will be treated as an error. However, Pod processors may
-treat "EE<lt> 0 1 2 3 >" or "EE<lt>e-acute>" as I<syntactically>
-invalid, potentially earning a different error message than the
-error message (or warning, or event) generated by a merely unknown
-(but theoretically valid) htmlname, as in "EE<lt>qacute>"
-[sic]. However, Pod parsers are not required to make this
-distinction.
-
-=item *
-
-Note that EE<lt>number> I<must not> be interpreted as simply
-"codepoint I<number> in the current/native character set". It always
-means only "the character represented by codepoint I<number> in
-Unicode." (This is identical to the semantics of &#I<number>; in XML.)
-
-This will likely require many formatters to have tables mapping from
-treatable Unicode codepoints (such as the "\xE9" for the e-acute
-character) to the escape sequences or codes necessary for conveying
-such sequences in the target output format. A converter to *roff
-would, for example know that "\xE9" (whether conveyed literally, or via
-a EE<lt>...> sequence) is to be conveyed as "e\\*'".
-Similarly, a program rendering Pod in a Mac OS application window, would
-presumably need to know that "\xE9" maps to codepoint 142 in MacRoman
-encoding that (at time of writing) is native for Mac OS. Such
-Unicode2whatever mappings are presumably already widely available for
-common output formats. (Such mappings may be incomplete! Implementers
-are not expected to bend over backwards in an attempt to render
-Cherokee syllabics, Etruscan runes, Byzantine musical symbols, or any
-of the other weird things that Unicode can encode.) And
-if a Pod document uses a character not found in such a mapping, the
-formatter should consider it an unrenderable character.
-
-=item *
-
-If, surprisingly, the implementor of a Pod formatter can't find a
-satisfactory pre-existing table mapping from Unicode characters to
-escapes in the target format (e.g., a decent table of Unicode
-characters to *roff escapes), it will be necessary to build such a
-table. If you are in this circumstance, you should begin with the
-characters in the range 0x00A0 - 0x00FF, which is mostly the heavily
-used accented characters. Then proceed (as patience permits and
-fastidiousness compels) through the characters that the (X)HTML
-standards groups judged important enough to merit mnemonics
-for. These are declared in the (X)HTML specifications at the
-www.W3.org site. At time of writing (September 2001), the most recent
-entity declaration files are:
-
- http://www.w3.org/TR/xhtml1/DTD/xhtml-lat1.ent
- http://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent
- http://www.w3.org/TR/xhtml1/DTD/xhtml-symbol.ent
-
-Then you can progress through any remaining notable Unicode characters
-in the range 0x2000-0x204D (consult the character tables at
-www.unicode.org), and whatever else strikes your fancy. For example,
-in F<xhtml-symbol.ent>, there is the entry:
-
- <!ENTITY infin "&#8734;"> <!-- infinity, U+221E ISOtech -->
-
-While the mapping "infin" to the character "\x{221E}" will (hopefully)
-have been already handled by the Pod parser, the presence of the
-character in this file means that it's reasonably important enough to
-include in a formatter's table that maps from notable Unicode characters
-to the codes necessary for rendering them. So for a Unicode-to-*roff
-mapping, for example, this would merit the entry:
-
- "\x{221E}" => '\(in',
-
-It is eagerly hoped that in the future, increasing numbers of formats
-(and formatters) will support Unicode characters directly (as (X)HTML
-does with C<&infin;>, C<&#8734;>, or C<&#x221E;>), reducing the need
-for idiosyncratic mappings of Unicode-to-I<my_escapes>.
-
-=item *
-
-It is up to individual Pod formatter to display good judgement when
-confronted with an unrenderable character (which is distinct from an
-unknown EE<lt>thing> sequence that the parser couldn't resolve to
-anything, renderable or not). It is good practice to map Latin letters
-with diacritics (like "EE<lt>eacute>"/"EE<lt>233>") to the corresponding
-unaccented US-ASCII letters (like a simple character 101, "e"), but
-clearly this is often not feasible, and an unrenderable character may
-be represented as "?", or the like. In attempting a sane fallback
-(as from EE<lt>233> to "e"), Pod formatters may use the
-%Latin1Code_to_fallback table in L<Pod::Escapes|Pod::Escapes>, or
-L<Text::Unidecode|Text::Unidecode>, if available.
-
-For example, this Pod text:
-
- magic is enabled if you set C<$Currency> to 'E<euro>'.
-
-may be rendered as:
-"magic is enabled if you set C<$Currency> to 'I<?>'" or as
-"magic is enabled if you set C<$Currency> to 'B<[euro]>'", or as
-"magic is enabled if you set C<$Currency> to '[x20AC]', etc.
-
-A Pod formatter may also note, in a comment or warning, a list of what
-unrenderable characters were encountered.
-
-=item *
-
-EE<lt>...> may freely appear in any formatting code (other than
-in another EE<lt>...> or in an ZE<lt>>). That is, "XE<lt>The
-EE<lt>euro>1,000,000 Solution>" is valid, as is "LE<lt>The
-EE<lt>euro>1,000,000 Solution|Million::Euros>".
-
-=item *
-
-Some Pod formatters output to formats that implement non-breaking
-spaces as an individual character (which I'll call "NBSP"), and
-others output to formats that implement non-breaking spaces just as
-spaces wrapped in a "don't break this across lines" code. Note that
-at the level of Pod, both sorts of codes can occur: Pod can contain a
-NBSP character (whether as a literal, or as a "EE<lt>160>" or
-"EE<lt>nbsp>" code); and Pod can contain "SE<lt>foo
-IE<lt>barE<gt> baz>" codes, where "mere spaces" (character 32) in
-such codes are taken to represent non-breaking spaces. Pod
-parsers should consider supporting the optional parsing of "SE<lt>foo
-IE<lt>barE<gt> baz>" as if it were
-"fooI<NBSP>IE<lt>barE<gt>I<NBSP>baz", and, going the other way, the
-optional parsing of groups of words joined by NBSP's as if each group
-were in a SE<lt>...> code, so that formatters may use the
-representation that maps best to what the output format demands.
-
-=item *
-
-Some processors may find that the C<SE<lt>...E<gt>> code is easiest to
-implement by replacing each space in the parse tree under the content
-of the S, with an NBSP. But note: the replacement should apply I<not> to
-spaces in I<all> text, but I<only> to spaces in I<printable> text. (This
-distinction may or may not be evident in the particular tree/event
-model implemented by the Pod parser.) For example, consider this
-unusual case:
-
- S<L</Autoloaded Functions>>
-
-This means that the space in the middle of the visible link text must
-not be broken across lines. In other words, it's the same as this:
-
- L<"AutoloadedE<160>Functions"/Autoloaded Functions>
-
-However, a misapplied space-to-NBSP replacement could (wrongly)
-produce something equivalent to this:
-
- L<"AutoloadedE<160>Functions"/AutoloadedE<160>Functions>
-
-...which is almost definitely not going to work as a hyperlink (assuming
-this formatter outputs a format supporting hypertext).
-
-Formatters may choose to just not support the S format code,
-especially in cases where the output format simply has no NBSP
-character/code and no code for "don't break this stuff across lines".
-
-=item *
-
-Besides the NBSP character discussed above, implementors are reminded
-of the existence of the other "special" character in Latin-1, the
-"soft hyphen" character, also known as "discretionary hyphen",
-i.e. C<EE<lt>173E<gt>> = C<EE<lt>0xADE<gt>> =
-C<EE<lt>shyE<gt>>). This character expresses an optional hyphenation
-point. That is, it normally renders as nothing, but may render as a
-"-" if a formatter breaks the word at that point. Pod formatters
-should, as appropriate, do one of the following: 1) render this with
-a code with the same meaning (e.g., "\-" in RTF), 2) pass it through
-in the expectation that the formatter understands this character as
-such, or 3) delete it.
-
-For example:
-
- sigE<shy>action
- manuE<shy>script
- JarkE<shy>ko HieE<shy>taE<shy>nieE<shy>mi
-
-These signal to a formatter that if it is to hyphenate "sigaction"
-or "manuscript", then it should be done as
-"sig-I<[linebreak]>action" or "manu-I<[linebreak]>script"
-(and if it doesn't hyphenate it, then the C<EE<lt>shyE<gt>> doesn't
-show up at all). And if it is
-to hyphenate "Jarkko" and/or "Hietaniemi", it can do
-so only at the points where there is a C<EE<lt>shyE<gt>> code.
-
-In practice, it is anticipated that this character will not be used
-often, but formatters should either support it, or delete it.
-
-=item *
-
-If you think that you want to add a new command to Pod (like, say, a
-"=biblio" command), consider whether you could get the same
-effect with a for or begin/end sequence: "=for biblio ..." or "=begin
-biblio" ... "=end biblio". Pod processors that don't understand
-"=for biblio", etc, will simply ignore it, whereas they may complain
-loudly if they see "=biblio".
-
-=item *
-
-Throughout this document, "Pod" has been the preferred spelling for
-the name of the documentation format. One may also use "POD" or
-"pod". For the documentation that is (typically) in the Pod
-format, you may use "pod", or "Pod", or "POD". Understanding these
-distinctions is useful; but obsessing over how to spell them, usually
-is not.
-
-=back
-
-
-
-
-
-=head1 About LE<lt>...E<gt> Codes
-
-As you can tell from a glance at L<perlpod|perlpod>, the LE<lt>...>
-code is the most complex of the Pod formatting codes. The points below
-will hopefully clarify what it means and how processors should deal
-with it.
-
-=over
-
-=item *
-
-In parsing an LE<lt>...> code, Pod parsers must distinguish at least
-four attributes:
-
-=over
-
-=item First:
-
-The link-text. If there is none, this must be undef. (E.g., in
-"LE<lt>Perl Functions|perlfunc>", the link-text is "Perl Functions".
-In "LE<lt>Time::HiRes>" and even "LE<lt>|Time::HiRes>", there is no
-link text. Note that link text may contain formatting.)
-
-=item Second:
-
-The possibly inferred link-text; i.e., if there was no real link
-text, then this is the text that we'll infer in its place. (E.g., for
-"LE<lt>Getopt::Std>", the inferred link text is "Getopt::Std".)
-
-=item Third:
-
-The name or URL, or undef if none. (E.g., in "LE<lt>Perl
-Functions|perlfunc>", the name (also sometimes called the page)
-is "perlfunc". In "LE<lt>/CAVEATS>", the name is undef.)
-
-=item Fourth:
-
-The section (AKA "item" in older perlpods), or undef if none. E.g.,
-in "LE<lt>Getopt::Std/DESCRIPTIONE<gt>", "DESCRIPTION" is the section. (Note
-that this is not the same as a manpage section like the "5" in "man 5
-crontab". "Section Foo" in the Pod sense means the part of the text
-that's introduced by the heading or item whose text is "Foo".)
-
-=back
-
-Pod parsers may also note additional attributes including:
-
-=over
-
-=item Fifth:
-
-A flag for whether item 3 (if present) is a URL (like
-"http://lists.perl.org" is), in which case there should be no section
-attribute; a Pod name (like "perldoc" and "Getopt::Std" are); or
-possibly a man page name (like "crontab(5)" is).
-
-=item Sixth:
-
-The raw original LE<lt>...> content, before text is split on
-"|", "/", etc, and before EE<lt>...> codes are expanded.
-
-=back
-
-(The above were numbered only for concise reference below. It is not
-a requirement that these be passed as an actual list or array.)
-
-For example:
-
- L<Foo::Bar>
- => undef, # link text
- "Foo::Bar", # possibly inferred link text
- "Foo::Bar", # name
- undef, # section
- 'pod', # what sort of link
- "Foo::Bar" # original content
-
- L<Perlport's section on NL's|perlport/Newlines>
- => "Perlport's section on NL's", # link text
- "Perlport's section on NL's", # possibly inferred link text
- "perlport", # name
- "Newlines", # section
- 'pod', # what sort of link
- "Perlport's section on NL's|perlport/Newlines" # orig. content
-
- L<perlport/Newlines>
- => undef, # link text
- '"Newlines" in perlport', # possibly inferred link text
- "perlport", # name
- "Newlines", # section
- 'pod', # what sort of link
- "perlport/Newlines" # original content
-
- L<crontab(5)/"DESCRIPTION">
- => undef, # link text
- '"DESCRIPTION" in crontab(5)', # possibly inferred link text
- "crontab(5)", # name
- "DESCRIPTION", # section
- 'man', # what sort of link
- 'crontab(5)/"DESCRIPTION"' # original content
-
- L</Object Attributes>
- => undef, # link text
- '"Object Attributes"', # possibly inferred link text
- undef, # name
- "Object Attributes", # section
- 'pod', # what sort of link
- "/Object Attributes" # original content
-
- L<http://www.perl.org/>
- => undef, # link text
- "http://www.perl.org/", # possibly inferred link text
- "http://www.perl.org/", # name
- undef, # section
- 'url', # what sort of link
- "http://www.perl.org/" # original content
-
- L<Perl.org|http://www.perl.org/>
- => "Perl.org", # link text
- "http://www.perl.org/", # possibly inferred link text
- "http://www.perl.org/", # name
- undef, # section
- 'url', # what sort of link
- "Perl.org|http://www.perl.org/" # original content
-
-Note that you can distinguish URL-links from anything else by the
-fact that they match C<m/\A\w+:[^:\s]\S*\z/>. So
-C<LE<lt>http://www.perl.comE<gt>> is a URL, but
-C<LE<lt>HTTP::ResponseE<gt>> isn't.
-
-=item *
-
-In case of LE<lt>...> codes with no "text|" part in them,
-older formatters have exhibited great variation in actually displaying
-the link or cross reference. For example, LE<lt>crontab(5)> would render
-as "the C<crontab(5)> manpage", or "in the C<crontab(5)> manpage"
-or just "C<crontab(5)>".
-
-Pod processors must now treat "text|"-less links as follows:
-
- L<name> => L<name|name>
- L</section> => L<"section"|/section>
- L<name/section> => L<"section" in name|name/section>
-
-=item *
-
-Note that section names might contain markup. I.e., if a section
-starts with:
-
- =head2 About the C<-M> Operator
-
-or with:
-
- =item About the C<-M> Operator
-
-then a link to it would look like this:
-
- L<somedoc/About the C<-M> Operator>
-
-Formatters may choose to ignore the markup for purposes of resolving
-the link and use only the renderable characters in the section name,
-as in:
-
- <h1><a name="About_the_-M_Operator">About the <code>-M</code>
- Operator</h1>
-
- ...
-
- <a href="somedoc#About_the_-M_Operator">About the <code>-M</code>
- Operator" in somedoc</a>
-
-=item *
-
-Previous versions of perlpod distinguished C<LE<lt>name/"section"E<gt>>
-links from C<LE<lt>name/itemE<gt>> links (and their targets). These
-have been merged syntactically and semantically in the current
-specification, and I<section> can refer either to a "=headI<n> Heading
-Content" command or to a "=item Item Content" command. This
-specification does not specify what behavior should be in the case
-of a given document having several things all seeming to produce the
-same I<section> identifier (e.g., in HTML, several things all producing
-the same I<anchorname> in <a name="I<anchorname>">...</a>
-elements). Where Pod processors can control this behavior, they should
-use the first such anchor. That is, C<LE<lt>Foo/BarE<gt>> refers to the
-I<first> "Bar" section in Foo.
-
-But for some processors/formats this cannot be easily controlled; as
-with the HTML example, the behavior of multiple ambiguous
-<a name="I<anchorname>">...</a> is most easily just left up to
-browsers to decide.
-
-=item *
-
-In a C<LE<lt>text|...E<gt>> code, text may contain formatting codes
-for formatting or for EE<lt>...> escapes, as in:
-
- L<B<ummE<234>stuff>|...>
-
-For C<LE<lt>...E<gt>> codes without a "name|" part, only
-C<EE<lt>...E<gt>> and C<ZE<lt>E<gt>> codes may occur. That is,
-authors should not use "C<LE<lt>BE<lt>Foo::BarE<gt>E<gt>>".
-
-Note, however, that formatting codes and ZE<lt>>'s can occur in any
-and all parts of an LE<lt>...> (i.e., in I<name>, I<section>, I<text>,
-and I<url>).
-
-Authors must not nest LE<lt>...> codes. For example, "LE<lt>The
-LE<lt>Foo::Bar> man page>" should be treated as an error.
-
-=item *
-
-Note that Pod authors may use formatting codes inside the "text"
-part of "LE<lt>text|name>" (and so on for LE<lt>text|/"sec">).
-
-In other words, this is valid:
-
- Go read L<the docs on C<$.>|perlvar/"$.">
-
-Some output formats that do allow rendering "LE<lt>...>" codes as
-hypertext, might not allow the link-text to be formatted; in
-that case, formatters will have to just ignore that formatting.
-
-=item *
-
-At time of writing, C<LE<lt>nameE<gt>> values are of two types:
-either the name of a Pod page like C<LE<lt>Foo::BarE<gt>> (which
-might be a real Perl module or program in an @INC / PATH
-directory, or a .pod file in those places); or the name of a Unix
-man page, like C<LE<lt>crontab(5)E<gt>>. In theory, C<LE<lt>chmodE<gt>>
-in ambiguous between a Pod page called "chmod", or the Unix man page
-"chmod" (in whatever man-section). However, the presence of a string
-in parens, as in "crontab(5)", is sufficient to signal that what
-is being discussed is not a Pod page, and so is presumably a
-Unix man page. The distinction is of no importance to many
-Pod processors, but some processors that render to hypertext formats
-may need to distinguish them in order to know how to render a
-given C<LE<lt>fooE<gt>> code.
-
-=item *
-
-Previous versions of perlpod allowed for a C<LE<lt>sectionE<gt>> syntax (as in
-C<LE<lt>Object AttributesE<gt>>), which was not easily distinguishable from
-C<LE<lt>nameE<gt>> syntax and for C<LE<lt>"section"E<gt>> which was only
-slightly less ambiguous. This syntax is no longer in the specification, and
-has been replaced by the C<LE<lt>/sectionE<gt>> syntax (where the slash was
-formerly optional). Pod parsers should tolerate the C<LE<lt>"section"E<gt>>
-syntax, for a while at least. The suggested heuristic for distinguishing
-C<LE<lt>sectionE<gt>> from C<LE<lt>nameE<gt>> is that if it contains any
-whitespace, it's a I<section>. Pod processors should warn about this being
-deprecated syntax.
-
-=back
-
-=head1 About =over...=back Regions
-
-"=over"..."=back" regions are used for various kinds of list-like
-structures. (I use the term "region" here simply as a collective
-term for everything from the "=over" to the matching "=back".)
-
-=over
-
-=item *
-
-The non-zero numeric I<indentlevel> in "=over I<indentlevel>" ...
-"=back" is used for giving the formatter a clue as to how many
-"spaces" (ems, or roughly equivalent units) it should tab over,
-although many formatters will have to convert this to an absolute
-measurement that may not exactly match with the size of spaces (or M's)
-in the document's base font. Other formatters may have to completely
-ignore the number. The lack of any explicit I<indentlevel> parameter is
-equivalent to an I<indentlevel> value of 4. Pod processors may
-complain if I<indentlevel> is present but is not a positive number
-matching C<m/\A(\d*\.)?\d+\z/>.
-
-=item *
-
-Authors of Pod formatters are reminded that "=over" ... "=back" may
-map to several different constructs in your output format. For
-example, in converting Pod to (X)HTML, it can map to any of
-<ul>...</ul>, <ol>...</ol>, <dl>...</dl>, or
-<blockquote>...</blockquote>. Similarly, "=item" can map to <li> or
-<dt>.
-
-=item *
-
-Each "=over" ... "=back" region should be one of the following:
-
-=over
-
-=item *
-
-An "=over" ... "=back" region containing only "=item *" commands,
-each followed by some number of ordinary/verbatim paragraphs, other
-nested "=over" ... "=back" regions, "=for..." paragraphs, and
-"=begin"..."=end" regions.
-
-(Pod processors must tolerate a bare "=item" as if it were "=item
-*".) Whether "*" is rendered as a literal asterisk, an "o", or as
-some kind of real bullet character, is left up to the Pod formatter,
-and may depend on the level of nesting.
-
-=item *
-
-An "=over" ... "=back" region containing only
-C<m/\A=item\s+\d+\.?\s*\z/> paragraphs, each one (or each group of them)
-followed by some number of ordinary/verbatim paragraphs, other nested
-"=over" ... "=back" regions, "=for..." paragraphs, and/or
-"=begin"..."=end" codes. Note that the numbers must start at 1
-in each section, and must proceed in order and without skipping
-numbers.
-
-(Pod processors must tolerate lines like "=item 1" as if they were
-"=item 1.", with the period.)
-
-=item *
-
-An "=over" ... "=back" region containing only "=item [text]"
-commands, each one (or each group of them) followed by some number of
-ordinary/verbatim paragraphs, other nested "=over" ... "=back"
-regions, or "=for..." paragraphs, and "=begin"..."=end" regions.
-
-The "=item [text]" paragraph should not match
-C<m/\A=item\s+\d+\.?\s*\z/> or C<m/\A=item\s+\*\s*\z/>, nor should it
-match just C<m/\A=item\s*\z/>.
-
-=item *
-
-An "=over" ... "=back" region containing no "=item" paragraphs at
-all, and containing only some number of
-ordinary/verbatim paragraphs, and possibly also some nested "=over"
-... "=back" regions, "=for..." paragraphs, and "=begin"..."=end"
-regions. Such an itemless "=over" ... "=back" region in Pod is
-equivalent in meaning to a "<blockquote>...</blockquote>" element in
-HTML.
-
-=back
-
-Note that with all the above cases, you can determine which type of
-"=over" ... "=back" you have, by examining the first (non-"=cut",
-non-"=pod") Pod paragraph after the "=over" command.
-
-=item *
-
-Pod formatters I<must> tolerate arbitrarily large amounts of text
-in the "=item I<text...>" paragraph. In practice, most such
-paragraphs are short, as in:
-
- =item For cutting off our trade with all parts of the world
-
-But they may be arbitrarily long:
-
- =item For transporting us beyond seas to be tried for pretended
- offenses
-
- =item He is at this time transporting large armies of foreign
- mercenaries to complete the works of death, desolation and
- tyranny, already begun with circumstances of cruelty and perfidy
- scarcely paralleled in the most barbarous ages, and totally
- unworthy the head of a civilized nation.
-
-=item *
-
-Pod processors should tolerate "=item *" / "=item I<number>" commands
-with no accompanying paragraph. The middle item is an example:
-
- =over
-
- =item 1
-
- Pick up dry cleaning.
-
- =item 2
-
- =item 3
-
- Stop by the store. Get Abba Zabas, Stoli, and cheap lawn chairs.
-
- =back
-
-=item *
-
-No "=over" ... "=back" region can contain headings. Processors may
-treat such a heading as an error.
-
-=item *
-
-Note that an "=over" ... "=back" region should have some
-content. That is, authors should not have an empty region like this:
-
- =over
-
- =back
-
-Pod processors seeing such a contentless "=over" ... "=back" region,
-may ignore it, or may report it as an error.
-
-=item *
-
-Processors must tolerate an "=over" list that goes off the end of the
-document (i.e., which has no matching "=back"), but they may warn
-about such a list.
-
-=item *
-
-Authors of Pod formatters should note that this construct:
-
- =item Neque
-
- =item Porro
-
- =item Quisquam Est
-
- Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
- velit, sed quia non numquam eius modi tempora incidunt ut
- labore et dolore magnam aliquam quaerat voluptatem.
-
- =item Ut Enim
-
-is semantically ambiguous, in a way that makes formatting decisions
-a bit difficult. On the one hand, it could be mention of an item
-"Neque", mention of another item "Porro", and mention of another
-item "Quisquam Est", with just the last one requiring the explanatory
-paragraph "Qui dolorem ipsum quia dolor..."; and then an item
-"Ut Enim". In that case, you'd want to format it like so:
-
- Neque
-
- Porro
-
- Quisquam Est
- Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
- velit, sed quia non numquam eius modi tempora incidunt ut
- labore et dolore magnam aliquam quaerat voluptatem.
-
- Ut Enim
-
-But it could equally well be a discussion of three (related or equivalent)
-items, "Neque", "Porro", and "Quisquam Est", followed by a paragraph
-explaining them all, and then a new item "Ut Enim". In that case, you'd
-probably want to format it like so:
-
- Neque
- Porro
- Quisquam Est
- Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
- velit, sed quia non numquam eius modi tempora incidunt ut
- labore et dolore magnam aliquam quaerat voluptatem.
-
- Ut Enim
-
-But (for the foreseeable future), Pod does not provide any way for Pod
-authors to distinguish which grouping is meant by the above
-"=item"-cluster structure. So formatters should format it like so:
-
- Neque
-
- Porro
-
- Quisquam Est
-
- Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
- velit, sed quia non numquam eius modi tempora incidunt ut
- labore et dolore magnam aliquam quaerat voluptatem.
-
- Ut Enim
-
-That is, there should be (at least roughly) equal spacing between
-items as between paragraphs (although that spacing may well be less
-than the full height of a line of text). This leaves it to the reader
-to use (con)textual cues to figure out whether the "Qui dolorem
-ipsum..." paragraph applies to the "Quisquam Est" item or to all three
-items "Neque", "Porro", and "Quisquam Est". While not an ideal
-situation, this is preferable to providing formatting cues that may
-be actually contrary to the author's intent.
-
-=back
-
-
-
-=head1 About Data Paragraphs and "=begin/=end" Regions
-
-Data paragraphs are typically used for inlining non-Pod data that is
-to be used (typically passed through) when rendering the document to
-a specific format:
-
- =begin rtf
-
- \par{\pard\qr\sa4500{\i Printed\~\chdate\~\chtime}\par}
-
- =end rtf
-
-The exact same effect could, incidentally, be achieved with a single
-"=for" paragraph:
-
- =for rtf \par{\pard\qr\sa4500{\i Printed\~\chdate\~\chtime}\par}
-
-(Although that is not formally a data paragraph, it has the same
-meaning as one, and Pod parsers may parse it as one.)
-
-Another example of a data paragraph:
-
- =begin html
-
- I like <em>PIE</em>!
-
- <hr>Especially pecan pie!
-
- =end html
-
-If these were ordinary paragraphs, the Pod parser would try to
-expand the "EE<lt>/em>" (in the first paragraph) as a formatting
-code, just like "EE<lt>lt>" or "EE<lt>eacute>". But since this
-is in a "=begin I<identifier>"..."=end I<identifier>" region I<and>
-the identifier "html" doesn't begin have a ":" prefix, the contents
-of this region are stored as data paragraphs, instead of being
-processed as ordinary paragraphs (or if they began with a spaces
-and/or tabs, as verbatim paragraphs).
-
-As a further example: At time of writing, no "biblio" identifier is
-supported, but suppose some processor were written to recognize it as
-a way of (say) denoting a bibliographic reference (necessarily
-containing formatting codes in ordinary paragraphs). The fact that
-"biblio" paragraphs were meant for ordinary processing would be
-indicated by prefacing each "biblio" identifier with a colon:
-
- =begin :biblio
-
- Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
- Programs.> Prentice-Hall, Englewood Cliffs, NJ.
-
- =end :biblio
-
-This would signal to the parser that paragraphs in this begin...end
-region are subject to normal handling as ordinary/verbatim paragraphs
-(while still tagged as meant only for processors that understand the
-"biblio" identifier). The same effect could be had with:
-
- =for :biblio
- Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
- Programs.> Prentice-Hall, Englewood Cliffs, NJ.
-
-The ":" on these identifiers means simply "process this stuff
-normally, even though the result will be for some special target".
-I suggest that parser APIs report "biblio" as the target identifier,
-but also report that it had a ":" prefix. (And similarly, with the
-above "html", report "html" as the target identifier, and note the
-I<lack> of a ":" prefix.)
-
-Note that a "=begin I<identifier>"..."=end I<identifier>" region where
-I<identifier> begins with a colon, I<can> contain commands. For example:
-
- =begin :biblio
-
- Wirth's classic is available in several editions, including:
-
- =for comment
- hm, check abebooks.com for how much used copies cost.
-
- =over
-
- =item
-
- Wirth, Niklaus. 1975. I<Algorithmen und Datenstrukturen.>
- Teubner, Stuttgart. [Yes, it's in German.]
-
- =item
-
- Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
- Programs.> Prentice-Hall, Englewood Cliffs, NJ.
-
- =back
-
- =end :biblio
-
-Note, however, a "=begin I<identifier>"..."=end I<identifier>"
-region where I<identifier> does I<not> begin with a colon, should not
-directly contain "=head1" ... "=head4" commands, nor "=over", nor "=back",
-nor "=item". For example, this may be considered invalid:
-
- =begin somedata
-
- This is a data paragraph.
-
- =head1 Don't do this!
-
- This is a data paragraph too.
-
- =end somedata
-
-A Pod processor may signal that the above (specifically the "=head1"
-paragraph) is an error. Note, however, that the following should
-I<not> be treated as an error:
-
- =begin somedata
-
- This is a data paragraph.
-
- =cut
-
- # Yup, this isn't Pod anymore.
- sub excl { (rand() > .5) ? "hoo!" : "hah!" }
-
- =pod
-
- This is a data paragraph too.
-
- =end somedata
-
-And this too is valid:
-
- =begin someformat
-
- This is a data paragraph.
-
- And this is a data paragraph.
-
- =begin someotherformat
-
- This is a data paragraph too.
-
- And this is a data paragraph too.
-
- =begin :yetanotherformat
-
- =head2 This is a command paragraph!
-
- This is an ordinary paragraph!
-
- And this is a verbatim paragraph!
-
- =end :yetanotherformat
-
- =end someotherformat
-
- Another data paragraph!
-
- =end someformat
-
-The contents of the above "=begin :yetanotherformat" ...
-"=end :yetanotherformat" region I<aren't> data paragraphs, because
-the immediately containing region's identifier (":yetanotherformat")
-begins with a colon. In practice, most regions that contain
-data paragraphs will contain I<only> data paragraphs; however,
-the above nesting is syntactically valid as Pod, even if it is
-rare. However, the handlers for some formats, like "html",
-will accept only data paragraphs, not nested regions; and they may
-complain if they see (targeted for them) nested regions, or commands,
-other than "=end", "=pod", and "=cut".
-
-Also consider this valid structure:
-
- =begin :biblio
-
- Wirth's classic is available in several editions, including:
-
- =over
-
- =item
-
- Wirth, Niklaus. 1975. I<Algorithmen und Datenstrukturen.>
- Teubner, Stuttgart. [Yes, it's in German.]
-
- =item
-
- Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
- Programs.> Prentice-Hall, Englewood Cliffs, NJ.
-
- =back
-
- Buy buy buy!
-
- =begin html
-
- <img src='wirth_spokesmodeling_book.png'>
-
- <hr>
-
- =end html
-
- Now now now!
-
- =end :biblio
-
-There, the "=begin html"..."=end html" region is nested inside
-the larger "=begin :biblio"..."=end :biblio" region. Note that the
-content of the "=begin html"..."=end html" region is data
-paragraph(s), because the immediately containing region's identifier
-("html") I<doesn't> begin with a colon.
-
-Pod parsers, when processing a series of data paragraphs one
-after another (within a single region), should consider them to
-be one large data paragraph that happens to contain blank lines. So
-the content of the above "=begin html"..."=end html" I<may> be stored
-as two data paragraphs (one consisting of
-"<img src='wirth_spokesmodeling_book.png'>\n"
-and another consisting of "<hr>\n"), but I<should> be stored as
-a single data paragraph (consisting of
-"<img src='wirth_spokesmodeling_book.png'>\n\n<hr>\n").
-
-Pod processors should tolerate empty
-"=begin I<something>"..."=end I<something>" regions,
-empty "=begin :I<something>"..."=end :I<something>" regions, and
-contentless "=for I<something>" and "=for :I<something>"
-paragraphs. I.e., these should be tolerated:
-
- =for html
-
- =begin html
-
- =end html
-
- =begin :biblio
-
- =end :biblio
-
-Incidentally, note that there's no easy way to express a data
-paragraph starting with something that looks like a command. Consider:
-
- =begin stuff
-
- =shazbot
-
- =end stuff
-
-There, "=shazbot" will be parsed as a Pod command "shazbot", not as a data
-paragraph "=shazbot\n". However, you can express a data paragraph consisting
-of "=shazbot\n" using this code:
-
- =for stuff =shazbot
-
-The situation where this is necessary, is presumably quite rare.
-
-Note that =end commands must match the currently open =begin command. That
-is, they must properly nest. For example, this is valid:
-
- =begin outer
-
- X
-
- =begin inner
-
- Y
-
- =end inner
-
- Z
-
- =end outer
-
-while this is invalid:
-
- =begin outer
-
- X
-
- =begin inner
-
- Y
-
- =end outer
-
- Z
-
- =end inner
-
-This latter is improper because when the "=end outer" command is seen, the
-currently open region has the formatname "inner", not "outer". (It just
-happens that "outer" is the format name of a higher-up region.) This is
-an error. Processors must by default report this as an error, and may halt
-processing the document containing that error. A corollary of this is that
-regions cannot "overlap". That is, the latter block above does not represent
-a region called "outer" which contains X and Y, overlapping a region called
-"inner" which contains Y and Z. But because it is invalid (as all
-apparently overlapping regions would be), it doesn't represent that, or
-anything at all.
-
-Similarly, this is invalid:
-
- =begin thing
-
- =end hting
-
-This is an error because the region is opened by "thing", and the "=end"
-tries to close "hting" [sic].
-
-This is also invalid:
-
- =begin thing
-
- =end
-
-This is invalid because every "=end" command must have a formatname
-parameter.
-
-=head1 SEE ALSO
-
-L<perlpod>, L<perlsyn/"PODs: Embedded Documentation">,
-L<podchecker>
-
-=head1 AUTHOR
-
-Sean M. Burke
-
-=cut
-
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlpodstyle.pod b/Master/tlpkg/tlperl/lib/pods/perlpodstyle.pod
deleted file mode 100644
index 850f38dc8d9..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlpodstyle.pod
+++ /dev/null
@@ -1,338 +0,0 @@
-=head1 NAME
-
-perlpodstyle - Perl POD style guide
-
-=head1 DESCRIPTION
-
-These are general guidelines for how to write POD documentation for Perl
-scripts and modules, based on general guidelines for writing good Unix man
-pages. All of these guidelines are, of course, optional, but following
-them will make your documentation more consistent with other documentation
-on the system.
-
-Here are some simple guidelines for markup; see L<perlpod> for details.
-
-=over
-
-=item bold (BE<lt>E<gt>)
-
-B<NOTE: Use extremely rarely.> Do I<not> use bold for emphasis; that's
-what italics are for. Restrict bold for notices like B<NOTE:> and
-B<WARNING:>. However, program arguments and options--but I<not> their
-names!--are written in bold (using BE<lt>E<gt>) to distinguish the B<-f>
-command-line option from the C<-f> filetest operator.
-
-=item italic (IE<lt>E<gt>)
-
-Use italic to emphasize text, like I<this>. Function names are
-traditionally written in italics; if you write a function as function(),
-Pod::Man will take care of this for you. Names of programs, including the
-name of the program being documented, are conventionally written in italics
-(using IE<lt>E<gt>) wherever they occur in normal roman text.
-
-=item code (CE<lt>E<gt>)
-
-Literal code should be in CE<lt>E<gt>. However metasyntactic placeholders
-should furthermore be nested in "italics" (actually, oblique) like
-CE<lt>IE<lt>E<gt>E<gt>. That way
-CE<lt>accept(IE<lt>NEWSOCKETE<gt>, E<lt>GENERICSOCKETE<gt>)E<gt>
-renders as C<accept(I<NEWSOCKET>, I<GENERICSOCKET>)>.
-
-=item files (FE<lt>E<gt>)
-
-Filenames, whether absolute or relative, are specified with the FE<lt>E<gt>
-markup. This will render as italics, but has other semantic connotations.
-
-=back
-
-References to other man pages should be in the form "manpage(section)" or
-"C<LE<lt>manpage(section)E<gt>>", and Pod::Man will automatically format
-those appropriately. Both will render as I<manpage>(section). The second
-form, with LE<lt>E<gt>, is used to request that a POD formatter make a link
-to the man page if possible. As an exception, one normally omits the
-section when referring to module documentation because not all systems
-place it in section 3, although that is the default. You may use
-C<LE<lt>Module::NameE<gt>> for module references instead, but this is
-optional because the translators are supposed to recognize module
-references in pod, just as they do variable references like $foo and such.
-
-References to other programs or functions are normally in the form of man
-page references so that cross-referencing tools can provide the user with
-links and the like. It's possible to overdo this, though, so be careful not
-to clutter your documentation with too much markup. References to other
-programs that are not given as man page references should be enclosed in
-italics via IE<lt>E<gt>.
-
-Major headers should be set out using a C<=head1> directive, and are
-historically written in the rather startling ALL UPPER CASE format; this is
-not mandatory, but it's strongly recommended so that sections have
-consistent naming across different software packages. The translators are
-supposed to translate all caps into small caps. Minor headers may be
-included using C<=head2>, and are typically in mixed case.
-
-The standard sections of a manual page are:
-
-=over 4
-
-=item NAME
-
-Mandatory section; should be a comma-separated list of programs or
-functions documented by this POD page, such as:
-
- foo, bar - programs to do something
-
-Manual page indexers are often extremely picky about the format of this
-section, so don't put anything in it except this line. Every program or
-function documented by this POD page should be listed, separated by a
-comma and a space. For a Perl module, just give the module name. A
-single dash, and only a single dash, should separate the list of programs
-or functions from the description. Do not use any markup such as
-CE<lt>E<gt> or IE<lt>E<gt> anywhere in this line. Functions should not be
-qualified with C<()> or the like. The description should ideally fit on a
-single line, even if a man program replaces the dash with a few tabs.
-
-=item SYNOPSIS
-
-A short usage summary for programs and functions. This section is
-mandatory for section 3 pages. For Perl module documentation, it's
-usually convenient to have the contents of this section be a verbatim
-block showing some (brief) examples of typical ways the module is used.
-
-=item DESCRIPTION
-
-Extended description and discussion of the program or functions, or the
-body of the documentation for man pages that document something else. If
-particularly long, it's a good idea to break this up into subsections
-C<=head2> directives like:
-
- =head2 Normal Usage
-
- =head2 Advanced Features
-
- =head2 Writing Configuration Files
-
-or whatever is appropriate for your documentation.
-
-For a module, this is generally where the documentation of the interfaces
-provided by the module goes, usually in the form of a list with an
-C<=item> for each interface. Depending on how many interfaces there are,
-you may want to put that documentation in separate METHODS, FUNCTIONS,
-CLASS METHODS, or INSTANCE METHODS sections instead and save the
-DESCRIPTION section for an overview.
-
-=item OPTIONS
-
-Detailed description of each of the command-line options taken by the
-program. This should be separate from the description for the use of
-parsers like L<Pod::Usage>. This is normally presented as a list, with
-each option as a separate C<=item>. The specific option string should be
-enclosed in BE<lt>E<gt>. Any values that the option takes should be
-enclosed in IE<lt>E<gt>. For example, the section for the option
-B<--section>=I<manext> would be introduced with:
-
- =item B<--section>=I<manext>
-
-Synonymous options (like both the short and long forms) are separated by a
-comma and a space on the same C<=item> line, or optionally listed as their
-own item with a reference to the canonical name. For example, since
-B<--section> can also be written as B<-s>, the above would be:
-
- =item B<-s> I<manext>, B<--section>=I<manext>
-
-Writing the short option first is recommended because it's easier to read.
-The long option is long enough to draw the eye to it anyway and the short
-option can otherwise get lost in visual noise.
-
-=item RETURN VALUE
-
-What the program or function returns, if successful. This section can be
-omitted for programs whose precise exit codes aren't important, provided
-they return 0 on success and non-zero on failure as is standard. It
-should always be present for functions. For modules, it may be useful to
-summarize return values from the module interface here, or it may be more
-useful to discuss return values separately in the documentation of each
-function or method the module provides.
-
-=item ERRORS
-
-Exceptions, error return codes, exit statuses, and errno settings.
-Typically used for function or module documentation; program documentation
-uses DIAGNOSTICS instead. The general rule of thumb is that errors
-printed to C<STDOUT> or C<STDERR> and intended for the end user are
-documented in DIAGNOSTICS while errors passed internal to the calling
-program and intended for other programmers are documented in ERRORS. When
-documenting a function that sets errno, a full list of the possible errno
-values should be given here.
-
-=item DIAGNOSTICS
-
-All possible messages the program can print out and what they mean. You
-may wish to follow the same documentation style as the Perl documentation;
-see perldiag(1) for more details (and look at the POD source as well).
-
-If applicable, please include details on what the user should do to
-correct the error; documenting an error as indicating "the input buffer is
-too small" without telling the user how to increase the size of the input
-buffer (or at least telling them that it isn't possible) aren't very
-useful.
-
-=item EXAMPLES
-
-Give some example uses of the program or function. Don't skimp; users
-often find this the most useful part of the documentation. The examples
-are generally given as verbatim paragraphs.
-
-Don't just present an example without explaining what it does. Adding a
-short paragraph saying what the example will do can increase the value of
-the example immensely.
-
-=item ENVIRONMENT
-
-Environment variables that the program cares about, normally presented as
-a list using C<=over>, C<=item>, and C<=back>. For example:
-
- =over 6
-
- =item HOME
-
- Used to determine the user's home directory. F<.foorc> in this
- directory is read for configuration details, if it exists.
-
- =back
-
-Since environment variables are normally in all uppercase, no additional
-special formatting is generally needed; they're glaring enough as it is.
-
-=item FILES
-
-All files used by the program or function, normally presented as a list,
-and what it uses them for. File names should be enclosed in FE<lt>E<gt>.
-It's particularly important to document files that will be potentially
-modified.
-
-=item CAVEATS
-
-Things to take special care with, sometimes called WARNINGS.
-
-=item BUGS
-
-Things that are broken or just don't work quite right.
-
-=item RESTRICTIONS
-
-Bugs you don't plan to fix. :-)
-
-=item NOTES
-
-Miscellaneous commentary.
-
-=item AUTHOR
-
-Who wrote it (use AUTHORS for multiple people). It's a good idea to
-include your current email address (or some email address to which bug
-reports should be sent) or some other contact information so that users
-have a way of contacting you. Remember that program documentation tends
-to roam the wild for far longer than you expect and pick a contact method
-that's likely to last.
-
-=item HISTORY
-
-Programs derived from other sources sometimes have this. Some people keep
-a modification log here, but that usually gets long and is normally better
-maintained in a separate file.
-
-=item COPYRIGHT AND LICENSE
-
-For copyright
-
- Copyright YEAR(s) YOUR NAME(s)
-
-(No, (C) is not needed. No, "all rights reserved" is not needed.)
-
-For licensing the easiest way is to use the same licensing as Perl itself:
-
- This library is free software; you may redistribute it and/or modify
- it under the same terms as Perl itself.
-
-This makes it easy for people to use your module with Perl. Note that
-this licensing example is neither an endorsement or a requirement, you are
-of course free to choose any licensing.
-
-=item SEE ALSO
-
-Other man pages to check out, like man(1), man(7), makewhatis(8), or
-catman(8). Normally a simple list of man pages separated by commas, or a
-paragraph giving the name of a reference work. Man page references, if
-they use the standard C<name(section)> form, don't have to be enclosed in
-LE<lt>E<gt> (although it's recommended), but other things in this section
-probably should be when appropriate.
-
-If the package has a mailing list, include a URL or subscription
-instructions here.
-
-If the package has a web site, include a URL here.
-
-=back
-
-Documentation of object-oriented libraries or modules may want to use
-CONSTRUCTORS and METHODS sections, or CLASS METHODS and INSTANCE METHODS
-sections, for detailed documentation of the parts of the library and save
-the DESCRIPTION section for an overview. Large modules with a function
-interface may want to use FUNCTIONS for similar reasons. Some people use
-OVERVIEW to summarize the description if it's quite long.
-
-Section ordering varies, although NAME must always be the first section
-(you'll break some man page systems otherwise), and NAME, SYNOPSIS,
-DESCRIPTION, and OPTIONS generally always occur first and in that order if
-present. In general, SEE ALSO, AUTHOR, and similar material should be
-left for last. Some systems also move WARNINGS and NOTES to last. The
-order given above should be reasonable for most purposes.
-
-Some systems use CONFORMING TO to note conformance to relevant standards
-and MT-LEVEL to note safeness for use in threaded programs or signal
-handlers. These headings are primarily useful when documenting parts of a
-C library.
-
-Finally, as a general note, try not to use an excessive amount of markup.
-As documented here and in L<Pod::Man>, you can safely leave Perl variables,
-module names, function names, man page references, and the like unadorned
-by markup, and the POD translators will figure it all out for you. This
-makes it much easier to later edit the documentation. Note that many
-existing translators will do the wrong thing with email addresses when
-wrapped in LE<lt>E<gt>, so don't do that.
-
-You can check whether your documentation looks right by running
-
- % pod2text -o something.pod | less
-
-If you have I<groff> installed, you can get an even better look this way:
-
- % pod2man something.pod | groff -Tps -mandoc > something.ps
-
-Now view the resulting Postscript file to see whether everything checks out.
-
-=head1 SEE ALSO
-
-For additional information that may be more accurate for your specific
-system, see either L<man(5)> or L<man(7)> depending on your system manual
-section numbering conventions.
-
-This documentation is maintained as part of the podlators distribution.
-The current version is always available from its web site at
-<http://www.eyrie.org/~eagle/software/podlators/>.
-
-=head1 AUTHOR
-
-Russ Allbery <rra@stanford.edu>, with large portions of this documentation
-taken from the documentation of the original B<pod2man> implementation by
-Larry Wall and Tom Christiansen.
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010 Russ Allbery
-<rra@stanford.edu>.
-
-This documentation is free software; you may redistribute it and/or modify
-it under the same terms as Perl itself.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlpolicy.pod b/Master/tlpkg/tlperl/lib/pods/perlpolicy.pod
deleted file mode 100644
index 7e713b4920a..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlpolicy.pod
+++ /dev/null
@@ -1,479 +0,0 @@
-=head1 NAME
-
-perlpolicy - Various and sundry policies and commitments related to the Perl core
-
-=head1 DESCRIPTION
-
-This document is the master document which records all written
-policies about how the Perl 5 Porters collectively develop and maintain
-the Perl core.
-
-=head1 GOVERNANCE
-
-=head2 Perl 5 Porters
-
-Subscribers to perl5-porters (the porters themselves) come in several flavours.
-Some are quiet curious lurkers, who rarely pitch in and instead watch
-the ongoing development to ensure they're forewarned of new changes or
-features in Perl. Some are representatives of vendors, who are there
-to make sure that Perl continues to compile and work on their
-platforms. Some patch any reported bug that they know how to fix,
-some are actively patching their pet area (threads, Win32, the regexp
--engine), while others seem to do nothing but complain. In other
-words, it's your usual mix of technical people.
-
-Over this group of porters presides Larry Wall. He has the final word
-in what does and does not change in any of the Perl programming languages.
-These days, Larry spends most of his time on Perl 6, while Perl 5 is
-shepherded by a "pumpking", a porter responsible for deciding what
-goes into each release and ensuring that releases happen on a regular
-basis.
-
-Larry sees Perl development along the lines of the US government:
-there's the Legislature (the porters), the Executive branch (the
--pumpking), and the Supreme Court (Larry). The legislature can
-discuss and submit patches to the executive branch all they like, but
-the executive branch is free to veto them. Rarely, the Supreme Court
-will side with the executive branch over the legislature, or the
-legislature over the executive branch. Mostly, however, the
-legislature and the executive branch are supposed to get along and
-work out their differences without impeachment or court cases.
-
-You might sometimes see reference to Rule 1 and Rule 2. Larry's power
-as Supreme Court is expressed in The Rules:
-
-=over 4
-
-=item 1
-
-Larry is always by definition right about how Perl should behave.
-This means he has final veto power on the core functionality.
-
-=item 2
-
-Larry is allowed to change his mind about any matter at a later date,
-regardless of whether he previously invoked Rule 1.
-
-=back
-
-Got that? Larry is always right, even when he was wrong. It's rare
-to see either Rule exercised, but they are often alluded to.
-
-=head1 MAINTENANCE AND SUPPORT
-
-Perl 5 is developed by a community, not a corporate entity. Every change
-contributed to the Perl core is the result of a donation. Typically, these
-donations are contributions of code or time by individual members of our
-community. On occasion, these donations come in the form of corporate
-or organizational sponsorship of a particular individual or project.
-
-As a volunteer organization, the commitments we make are heavily dependent
-on the goodwill and hard work of individuals who have no obligation to
-contribute to Perl.
-
-That being said, we value Perl's stability and security and have long
-had an unwritten covenant with the broader Perl community to support
-and maintain releases of Perl.
-
-This document codifies the support and maintenance commitments that
-the Perl community should expect from Perl's developers:
-
-=over
-
-=item *
-
-We "officially" support the two most recent stable release series. 5.12.x
-and earlier are now out of support. As of the release of 5.18.0, we will
-"officially" end support for Perl 5.14.x, other than providing security
-updates as described below.
-
-=item *
-
-To the best of our ability, we will attempt to fix critical issues
-in the two most recent stable 5.x release series. Fixes for the
-current release series take precedence over fixes for the previous
-release series.
-
-=item *
-
-To the best of our ability, we will provide "critical" security patches
-/ releases for any major version of Perl whose 5.x.0 release was within
-the past three years. We can only commit to providing these for the
-most recent .y release in any 5.x.y series.
-
-=item *
-
-We will not provide security updates or bug fixes for development
-releases of Perl.
-
-=item *
-
-We encourage vendors to ship the most recent supported release of
-Perl at the time of their code freeze.
-
-=item *
-
-As a vendor, you may have a requirement to backport security fixes
-beyond our 3 year support commitment. We can provide limited support and
-advice to you as you do so and, where possible will try to apply
-those patches to the relevant -maint branches in git, though we may or
-may not choose to make numbered releases or "official" patches
-available. Contact us at E<lt>perl5-security-report@perl.orgE<gt>
-to begin that process.
-
-=back
-
-=head1 BACKWARD COMPATIBILITY AND DEPRECATION
-
-Our community has a long-held belief that backward-compatibility is a
-virtue, even when the functionality in question is a design flaw.
-
-We would all love to unmake some mistakes we've made over the past
-decades. Living with every design error we've ever made can lead
-to painful stagnation. Unwinding our mistakes is very, very
-difficult. Doing so without actively harming our users is
-nearly impossible.
-
-Lately, ignoring or actively opposing compatibility with earlier versions
-of Perl has come into vogue. Sometimes, a change is proposed which
-wants to usurp syntax which previously had another meaning. Sometimes,
-a change wants to improve previously-crazy semantics.
-
-Down this road lies madness.
-
-Requiring end-user programmers to change just a few language constructs,
-even language constructs which no well-educated developer would ever
-intentionally use is tantamount to saying "you should not upgrade to
-a new release of Perl unless you have 100% test coverage and can do a
-full manual audit of your codebase." If we were to have tools capable of
-reliably upgrading Perl source code from one version of Perl to another,
-this concern could be significantly mitigated.
-
-We want to ensure that Perl continues to grow and flourish in the coming
-years and decades, but not at the expense of our user community.
-
-Existing syntax and semantics should only be marked for destruction in
-very limited circumstances. If a given language feature's continued
-inclusion in the language will cause significant harm to the language
-or prevent us from making needed changes to the runtime, then it may
-be considered for deprecation.
-
-Any language change which breaks backward-compatibility should be able to
-be enabled or disabled lexically. Unless code at a given scope declares
-that it wants the new behavior, that new behavior should be disabled.
-Which backward-incompatible changes are controlled implicitly by a
-'use v5.x.y' is a decision which should be made by the pumpking in
-consultation with the community.
-
-When a backward-incompatible change can't be toggled lexically, the decision
-to change the language must be considered very, very carefully. If it's
-possible to move the old syntax or semantics out of the core language
-and into XS-land, that XS module should be enabled by default unless
-the user declares that they want a newer revision of Perl.
-
-Historically, we've held ourselves to a far higher standard than
-backward-compatibility -- bugward-compatibility. Any accident of
-implementation or unintentional side-effect of running some bit of code
-has been considered to be a feature of the language to be defended with
-the same zeal as any other feature or functionality. No matter how
-frustrating these unintentional features may be to us as we continue
-to improve Perl, these unintentional features often deserve our
-protection. It is very important that existing software written in
-Perl continue to work correctly. If end-user developers have adopted a
-bug as a feature, we need to treat it as such.
-
-New syntax and semantics which don't break existing language constructs
-and syntax have a much lower bar. They merely need to prove themselves
-to be useful, elegant, well designed, and well tested.
-
-=head2 Terminology
-
-To make sure we're talking about the same thing when we discuss the removal
-of features or functionality from the Perl core, we have specific definitions
-for a few words and phrases.
-
-=over
-
-=item experimental
-
-If something in the Perl core is marked as B<experimental>, we may change
-its behaviour, deprecate or remove it without notice. While we'll always
-do our best to smooth the transition path for users of experimental
-features, you should contact the perl5-porters mailinglist if you find
-an experimental feature useful and want to help shape its future.
-
-=item deprecated
-
-If something in the Perl core is marked as B<deprecated>, we may remove it
-from the core in the next stable release series, though we may not. As of
-Perl 5.12, deprecated features and modules warn the user as they're used.
-If you use a deprecated feature and believe that its removal from the Perl
-core would be a mistake, please contact the perl5-porters mailinglist and
-plead your case. We don't deprecate things without a good reason, but
-sometimes there's a counterargument we haven't considered. Historically,
-we did not distinguish between "deprecated" and "discouraged" features.
-
-=item discouraged
-
-From time to time, we may mark language constructs and features which we
-consider to have been mistakes as B<discouraged>. Discouraged features
-aren't candidates for removal in the next major release series, but
-we may later deprecate them if they're found to stand in the way of a
-significant improvement to the Perl core.
-
-=item removed
-
-Once a feature, construct or module has been marked as deprecated for a
-stable release cycle, we may remove it from the Perl core. Unsurprisingly,
-we say we've B<removed> these things.
-
-=back
-
-=head1 MAINTENANCE BRANCHES
-
-=over
-
-=item *
-
-New releases of maint should contain as few changes as possible.
-If there is any question about whether a given patch might merit
-inclusion in a maint release, then it almost certainly should not
-be included.
-
-=item *
-
-Portability fixes, such as changes to Configure and the files in
-hints/ are acceptable. Ports of Perl to a new platform, architecture
-or OS release that involve changes to the implementation are NOT
-acceptable.
-
-=item *
-
-Acceptable documentation updates are those that correct factual errors,
-explain significant bugs or deficiencies in the current implementation,
-or fix broken markup.
-
-=item *
-
-Patches that add new warnings or errors or deprecate features
-are not acceptable.
-
-=item *
-
-Patches that fix crashing bugs that do not otherwise change Perl's
-functionality or negatively impact performance are acceptable.
-
-=item *
-
-Patches that fix CVEs or security issues are acceptable, but should
-be run through the perl5-security-report@perl.org mailing list
-rather than applied directly.
-
-=item *
-
-Patches that fix regressions in perl's behavior relative to previous
-releases are acceptable.
-
-=item *
-
-Updates to dual-life modules should consist of minimal patches to
-fix crashing or security issues (as above).
-
-=item *
-
-Minimal patches that fix platform-specific test failures or
-installation issues are acceptable. When these changes are made
-to dual-life modules for which CPAN is canonical, any changes
-should be coordinated with the upstream author.
-
-=item *
-
-New versions of dual-life modules should NOT be imported into maint.
-Those belong in the next stable series.
-
-=item *
-
-Patches that add or remove features are not acceptable.
-
-=item *
-
-Patches that break binary compatibility are not acceptable. (Please
-talk to a pumpking.)
-
-=back
-
-
-=head2 Getting changes into a maint branch
-
-Historically, only the pumpking cherry-picked changes from bleadperl
-into maintperl. This has...scaling problems. At the same time,
-maintenance branches of stable versions of Perl need to be treated with
-great care. To that end, we're going to try out a new process for
-maint-5.12.
-
-Any committer may cherry-pick any commit from blead to maint-5.12 if
-they send mail to perl5-porters announcing their intent to cherry-pick
-a specific commit along with a rationale for doing so and at least two
-other committers respond to the list giving their assent. (This policy
-applies to current and former pumpkings, as well as other committers.)
-
-=head1 CONTRIBUTED MODULES
-
-
-=head2 A Social Contract about Artistic Control
-
-What follows is a statement about artistic control, defined as the ability
-of authors of packages to guide the future of their code and maintain
-control over their work. It is a recognition that authors should have
-control over their work, and that it is a responsibility of the rest of
-the Perl community to ensure that they retain this control. It is an
-attempt to document the standards to which we, as Perl developers, intend
-to hold ourselves. It is an attempt to write down rough guidelines about
-the respect we owe each other as Perl developers.
-
-This statement is not a legal contract. This statement is not a legal
-document in any way, shape, or form. Perl is distributed under the GNU
-Public License and under the Artistic License; those are the precise legal
-terms. This statement isn't about the law or licenses. It's about
-community, mutual respect, trust, and good-faith cooperation.
-
-We recognize that the Perl core, defined as the software distributed with
-the heart of Perl itself, is a joint project on the part of all of us.
-From time to time, a script, module, or set of modules (hereafter referred
-to simply as a "module") will prove so widely useful and/or so integral to
-the correct functioning of Perl itself that it should be distributed with
-the Perl core. This should never be done without the author's explicit
-consent, and a clear recognition on all parts that this means the module
-is being distributed under the same terms as Perl itself. A module author
-should realize that inclusion of a module into the Perl core will
-necessarily mean some loss of control over it, since changes may
-occasionally have to be made on short notice or for consistency with the
-rest of Perl.
-
-Once a module has been included in the Perl core, however, everyone
-involved in maintaining Perl should be aware that the module is still the
-property of the original author unless the original author explicitly
-gives up their ownership of it. In particular:
-
-=over
-
-=item *
-
-The version of the module in the Perl core should still be considered the
-work of the original author. All patches, bug reports, and so
-forth should be fed back to them. Their development directions
-should be respected whenever possible.
-
-=item *
-
-Patches may be applied by the pumpkin holder without the explicit
-cooperation of the module author if and only if they are very minor,
-time-critical in some fashion (such as urgent security fixes), or if
-the module author cannot be reached. Those patches must still be
-given back to the author when possible, and if the author decides on
-an alternate fix in their version, that fix should be strongly
-preferred unless there is a serious problem with it. Any changes not
-endorsed by the author should be marked as such, and the contributor
-of the change acknowledged.
-
-=item *
-
-The version of the module distributed with Perl should, whenever
-possible, be the latest version of the module as distributed by the
-author (the latest non-beta version in the case of public Perl
-releases), although the pumpkin holder may hold off on upgrading the
-version of the module distributed with Perl to the latest version
-until the latest version has had sufficient testing.
-
-=back
-
-In other words, the author of a module should be considered to have final
-say on modifications to their module whenever possible (bearing in mind
-that it's expected that everyone involved will work together and arrive at
-reasonable compromises when there are disagreements).
-
-As a last resort, however:
-
-
-If the author's vision of the future of their module is sufficiently
-different from the vision of the pumpkin holder and perl5-porters as a
-whole so as to cause serious problems for Perl, the pumpkin holder may
-choose to formally fork the version of the module in the Perl core from the
-one maintained by the author. This should not be done lightly and
-should B<always> if at all possible be done only after direct input
-from Larry. If this is done, it must then be made explicit in the
-module as distributed with the Perl core that it is a forked version and
-that while it is based on the original author's work, it is no longer
-maintained by them. This must be noted in both the documentation and
-in the comments in the source of the module.
-
-Again, this should be a last resort only. Ideally, this should never
-happen, and every possible effort at cooperation and compromise should be
-made before doing this. If it does prove necessary to fork a module for
-the overall health of Perl, proper credit must be given to the original
-author in perpetuity and the decision should be constantly re-evaluated to
-see if a remerging of the two branches is possible down the road.
-
-In all dealings with contributed modules, everyone maintaining Perl should
-keep in mind that the code belongs to the original author, that they may
-not be on perl5-porters at any given time, and that a patch is not
-official unless it has been integrated into the author's copy of the
-module. To aid with this, and with points #1, #2, and #3 above, contact
-information for the authors of all contributed modules should be kept with
-the Perl distribution.
-
-Finally, the Perl community as a whole recognizes that respect for
-ownership of code, respect for artistic control, proper credit, and active
-effort to prevent unintentional code skew or communication gaps is vital
-to the health of the community and Perl itself. Members of a community
-should not normally have to resort to rules and laws to deal with each
-other, and this document, although it contains rules so as to be clear, is
-about an attitude and general approach. The first step in any dispute
-should be open communication, respect for opposing views, and an attempt
-at a compromise. In nearly every circumstance nothing more will be
-necessary, and certainly no more drastic measure should be used until
-every avenue of communication and discussion has failed.
-
-
-=head1 DOCUMENTATION
-
-Perl's documentation is an important resource for our users. It's
-incredibly important for Perl's documentation to be reasonably coherent
-and to accurately reflect the current implementation.
-
-Just as P5P collectively maintains the codebase, we collectively
-maintain the documentation. Writing a particular bit of documentation
-doesn't give an author control of the future of that documentation.
-At the same time, just as source code changes should match the style
-of their surrounding blocks, so should documentation changes.
-
-Examples in documentation should be illustrative of the concept
-they're explaining. Sometimes, the best way to show how a
-language feature works is with a small program the reader can
-run without modification. More often, examples will consist
-of a snippet of code containing only the "important" bits.
-The definition of "important" varies from snippet to snippet.
-Sometimes it's important to declare C<use strict> and C<use warnings>,
-initialize all variables and fully catch every error condition.
-More often than not, though, those things obscure the lesson
-the example was intended to teach.
-
-As Perl is developed by a global team of volunteers, our
-documentation often contains spellings which look funny
-to I<somebody>. Choice of American/British/Other spellings
-is left as an exercise for the author of each bit of
-documentation. When patching documentation, try to emulate
-the documentation around you, rather than changing the existing
-prose.
-
-In general, documentation should describe what Perl does "now" rather
-than what it used to do. It's perfectly reasonable to include notes
-in documentation about how behaviour has changed from previous releases,
-but, with very few exceptions, documentation isn't "dual-life" --
-it doesn't need to fully describe how all old versions used to work.
-
-
-=head1 CREDITS
-
-"Social Contract about Contributed Modules" originally by Russ Allbery E<lt>rra@stanford.eduE<gt> and the perl5-porters.
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlport.pod b/Master/tlpkg/tlperl/lib/pods/perlport.pod
deleted file mode 100644
index 867b66e2915..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlport.pod
+++ /dev/null
@@ -1,2359 +0,0 @@
-=head1 NAME
-
-perlport - Writing portable Perl
-
-=head1 DESCRIPTION
-
-Perl runs on numerous operating systems. While most of them share
-much in common, they also have their own unique features.
-
-This document is meant to help you to find out what constitutes portable
-Perl code. That way once you make a decision to write portably,
-you know where the lines are drawn, and you can stay within them.
-
-There is a tradeoff between taking full advantage of one particular
-type of computer and taking advantage of a full range of them.
-Naturally, as you broaden your range and become more diverse, the
-common factors drop, and you are left with an increasingly smaller
-area of common ground in which you can operate to accomplish a
-particular task. Thus, when you begin attacking a problem, it is
-important to consider under which part of the tradeoff curve you
-want to operate. Specifically, you must decide whether it is
-important that the task that you are coding have the full generality
-of being portable, or whether to just get the job done right now.
-This is the hardest choice to be made. The rest is easy, because
-Perl provides many choices, whichever way you want to approach your
-problem.
-
-Looking at it another way, writing portable code is usually about
-willfully limiting your available choices. Naturally, it takes
-discipline and sacrifice to do that. The product of portability
-and convenience may be a constant. You have been warned.
-
-Be aware of two important points:
-
-=over 4
-
-=item Not all Perl programs have to be portable
-
-There is no reason you should not use Perl as a language to glue Unix
-tools together, or to prototype a Macintosh application, or to manage the
-Windows registry. If it makes no sense to aim for portability for one
-reason or another in a given program, then don't bother.
-
-=item Nearly all of Perl already I<is> portable
-
-Don't be fooled into thinking that it is hard to create portable Perl
-code. It isn't. Perl tries its level-best to bridge the gaps between
-what's available on different platforms, and all the means available to
-use those features. Thus almost all Perl code runs on any machine
-without modification. But there are some significant issues in
-writing portable code, and this document is entirely about those issues.
-
-=back
-
-Here's the general rule: When you approach a task commonly done
-using a whole range of platforms, think about writing portable
-code. That way, you don't sacrifice much by way of the implementation
-choices you can avail yourself of, and at the same time you can give
-your users lots of platform choices. On the other hand, when you have to
-take advantage of some unique feature of a particular platform, as is
-often the case with systems programming (whether for Unix, Windows,
-VMS, etc.), consider writing platform-specific code.
-
-When the code will run on only two or three operating systems, you
-may need to consider only the differences of those particular systems.
-The important thing is to decide where the code will run and to be
-deliberate in your decision.
-
-The material below is separated into three main sections: main issues of
-portability (L<"ISSUES">), platform-specific issues (L<"PLATFORMS">), and
-built-in perl functions that behave differently on various ports
-(L<"FUNCTION IMPLEMENTATIONS">).
-
-This information should not be considered complete; it includes possibly
-transient information about idiosyncrasies of some of the ports, almost
-all of which are in a state of constant evolution. Thus, this material
-should be considered a perpetual work in progress
-(C<< <IMG SRC="yellow_sign.gif" ALT="Under Construction"> >>).
-
-=head1 ISSUES
-
-=head2 Newlines
-
-In most operating systems, lines in files are terminated by newlines.
-Just what is used as a newline may vary from OS to OS. Unix
-traditionally uses C<\012>, one type of DOSish I/O uses C<\015\012>,
-and S<Mac OS> uses C<\015>.
-
-Perl uses C<\n> to represent the "logical" newline, where what is
-logical may depend on the platform in use. In MacPerl, C<\n> always
-means C<\015>. In DOSish perls, C<\n> usually means C<\012>, but when
-accessing a file in "text" mode, perl uses the C<:crlf> layer that
-translates it to (or from) C<\015\012>, depending on whether you're
-reading or writing. Unix does the same thing on ttys in canonical
-mode. C<\015\012> is commonly referred to as CRLF.
-
-To trim trailing newlines from text lines use chomp(). With default
-settings that function looks for a trailing C<\n> character and thus
-trims in a portable way.
-
-When dealing with binary files (or text files in binary mode) be sure
-to explicitly set $/ to the appropriate value for your file format
-before using chomp().
-
-Because of the "text" mode translation, DOSish perls have limitations
-in using C<seek> and C<tell> on a file accessed in "text" mode.
-Stick to C<seek>-ing to locations you got from C<tell> (and no
-others), and you are usually free to use C<seek> and C<tell> even
-in "text" mode. Using C<seek> or C<tell> or other file operations
-may be non-portable. If you use C<binmode> on a file, however, you
-can usually C<seek> and C<tell> with arbitrary values in safety.
-
-A common misconception in socket programming is that C<\n> eq C<\012>
-everywhere. When using protocols such as common Internet protocols,
-C<\012> and C<\015> are called for specifically, and the values of
-the logical C<\n> and C<\r> (carriage return) are not reliable.
-
- print SOCKET "Hi there, client!\r\n"; # WRONG
- print SOCKET "Hi there, client!\015\012"; # RIGHT
-
-However, using C<\015\012> (or C<\cM\cJ>, or C<\x0D\x0A>) can be tedious
-and unsightly, as well as confusing to those maintaining the code. As
-such, the Socket module supplies the Right Thing for those who want it.
-
- use Socket qw(:DEFAULT :crlf);
- print SOCKET "Hi there, client!$CRLF" # RIGHT
-
-When reading from a socket, remember that the default input record
-separator C<$/> is C<\n>, but robust socket code will recognize as
-either C<\012> or C<\015\012> as end of line:
-
- while (<SOCKET>) {
- # ...
- }
-
-Because both CRLF and LF end in LF, the input record separator can
-be set to LF and any CR stripped later. Better to write:
-
- use Socket qw(:DEFAULT :crlf);
- local($/) = LF; # not needed if $/ is already \012
-
- while (<SOCKET>) {
- s/$CR?$LF/\n/; # not sure if socket uses LF or CRLF, OK
- # s/\015?\012/\n/; # same thing
- }
-
-This example is preferred over the previous one--even for Unix
-platforms--because now any C<\015>'s (C<\cM>'s) are stripped out
-(and there was much rejoicing).
-
-Similarly, functions that return text data--such as a function that
-fetches a web page--should sometimes translate newlines before
-returning the data, if they've not yet been translated to the local
-newline representation. A single line of code will often suffice:
-
- $data =~ s/\015?\012/\n/g;
- return $data;
-
-Some of this may be confusing. Here's a handy reference to the ASCII CR
-and LF characters. You can print it out and stick it in your wallet.
-
- LF eq \012 eq \x0A eq \cJ eq chr(10) eq ASCII 10
- CR eq \015 eq \x0D eq \cM eq chr(13) eq ASCII 13
-
- | Unix | DOS | Mac |
- ---------------------------
- \n | LF | LF | CR |
- \r | CR | CR | LF |
- \n * | LF | CRLF | CR |
- \r * | CR | CR | LF |
- ---------------------------
- * text-mode STDIO
-
-The Unix column assumes that you are not accessing a serial line
-(like a tty) in canonical mode. If you are, then CR on input becomes
-"\n", and "\n" on output becomes CRLF.
-
-These are just the most common definitions of C<\n> and C<\r> in Perl.
-There may well be others. For example, on an EBCDIC implementation
-such as z/OS (OS/390) or OS/400 (using the ILE, the PASE is ASCII-based)
-the above material is similar to "Unix" but the code numbers change:
-
- LF eq \025 eq \x15 eq \cU eq chr(21) eq CP-1047 21
- LF eq \045 eq \x25 eq chr(37) eq CP-0037 37
- CR eq \015 eq \x0D eq \cM eq chr(13) eq CP-1047 13
- CR eq \015 eq \x0D eq \cM eq chr(13) eq CP-0037 13
-
- | z/OS | OS/400 |
- ----------------------
- \n | LF | LF |
- \r | CR | CR |
- \n * | LF | LF |
- \r * | CR | CR |
- ----------------------
- * text-mode STDIO
-
-=head2 Numbers endianness and Width
-
-Different CPUs store integers and floating point numbers in different
-orders (called I<endianness>) and widths (32-bit and 64-bit being the
-most common today). This affects your programs when they attempt to transfer
-numbers in binary format from one CPU architecture to another,
-usually either "live" via network connection, or by storing the
-numbers to secondary storage such as a disk file or tape.
-
-Conflicting storage orders make utter mess out of the numbers. If a
-little-endian host (Intel, VAX) stores 0x12345678 (305419896 in
-decimal), a big-endian host (Motorola, Sparc, PA) reads it as
-0x78563412 (2018915346 in decimal). Alpha and MIPS can be either:
-Digital/Compaq used/uses them in little-endian mode; SGI/Cray uses
-them in big-endian mode. To avoid this problem in network (socket)
-connections use the C<pack> and C<unpack> formats C<n> and C<N>, the
-"network" orders. These are guaranteed to be portable.
-
-As of perl 5.9.2, you can also use the C<E<gt>> and C<E<lt>> modifiers
-to force big- or little-endian byte-order. This is useful if you want
-to store signed integers or 64-bit integers, for example.
-
-You can explore the endianness of your platform by unpacking a
-data structure packed in native format such as:
-
- print unpack("h*", pack("s2", 1, 2)), "\n";
- # '10002000' on e.g. Intel x86 or Alpha 21064 in little-endian mode
- # '00100020' on e.g. Motorola 68040
-
-If you need to distinguish between endian architectures you could use
-either of the variables set like so:
-
- $is_big_endian = unpack("h*", pack("s", 1)) =~ /01/;
- $is_little_endian = unpack("h*", pack("s", 1)) =~ /^1/;
-
-Differing widths can cause truncation even between platforms of equal
-endianness. The platform of shorter width loses the upper parts of the
-number. There is no good solution for this problem except to avoid
-transferring or storing raw binary numbers.
-
-One can circumnavigate both these problems in two ways. Either
-transfer and store numbers always in text format, instead of raw
-binary, or else consider using modules like Data::Dumper (included in
-the standard distribution as of Perl 5.005) and Storable (included as
-of perl 5.8). Keeping all data as text significantly simplifies matters.
-
-The v-strings are portable only up to v2147483647 (0x7FFFFFFF), that's
-how far EBCDIC, or more precisely UTF-EBCDIC will go.
-
-=head2 Files and Filesystems
-
-Most platforms these days structure files in a hierarchical fashion.
-So, it is reasonably safe to assume that all platforms support the
-notion of a "path" to uniquely identify a file on the system. How
-that path is really written, though, differs considerably.
-
-Although similar, file path specifications differ between Unix,
-Windows, S<Mac OS>, OS/2, VMS, VOS, S<RISC OS>, and probably others.
-Unix, for example, is one of the few OSes that has the elegant idea
-of a single root directory.
-
-DOS, OS/2, VMS, VOS, and Windows can work similarly to Unix with C</>
-as path separator, or in their own idiosyncratic ways (such as having
-several root directories and various "unrooted" device files such NIL:
-and LPT:).
-
-S<Mac OS> 9 and earlier used C<:> as a path separator instead of C</>.
-
-The filesystem may support neither hard links (C<link>) nor
-symbolic links (C<symlink>, C<readlink>, C<lstat>).
-
-The filesystem may support neither access timestamp nor change
-timestamp (meaning that about the only portable timestamp is the
-modification timestamp), or one second granularity of any timestamps
-(e.g. the FAT filesystem limits the time granularity to two seconds).
-
-The "inode change timestamp" (the C<-C> filetest) may really be the
-"creation timestamp" (which it is not in Unix).
-
-VOS perl can emulate Unix filenames with C</> as path separator. The
-native pathname characters greater-than, less-than, number-sign, and
-percent-sign are always accepted.
-
-S<RISC OS> perl can emulate Unix filenames with C</> as path
-separator, or go native and use C<.> for path separator and C<:> to
-signal filesystems and disk names.
-
-Don't assume Unix filesystem access semantics: that read, write,
-and execute are all the permissions there are, and even if they exist,
-that their semantics (for example what do r, w, and x mean on
-a directory) are the Unix ones. The various Unix/POSIX compatibility
-layers usually try to make interfaces like chmod() work, but sometimes
-there simply is no good mapping.
-
-If all this is intimidating, have no (well, maybe only a little)
-fear. There are modules that can help. The File::Spec modules
-provide methods to do the Right Thing on whatever platform happens
-to be running the program.
-
- use File::Spec::Functions;
- chdir(updir()); # go up one directory
- my $file = catfile(curdir(), 'temp', 'file.txt');
- # on Unix and Win32, './temp/file.txt'
- # on Mac OS Classic, ':temp:file.txt'
- # on VMS, '[.temp]file.txt'
-
-File::Spec is available in the standard distribution as of version
-5.004_05. File::Spec::Functions is only in File::Spec 0.7 and later,
-and some versions of perl come with version 0.6. If File::Spec
-is not updated to 0.7 or later, you must use the object-oriented
-interface from File::Spec (or upgrade File::Spec).
-
-In general, production code should not have file paths hardcoded.
-Making them user-supplied or read from a configuration file is
-better, keeping in mind that file path syntax varies on different
-machines.
-
-This is especially noticeable in scripts like Makefiles and test suites,
-which often assume C</> as a path separator for subdirectories.
-
-Also of use is File::Basename from the standard distribution, which
-splits a pathname into pieces (base filename, full path to directory,
-and file suffix).
-
-Even when on a single platform (if you can call Unix a single platform),
-remember not to count on the existence or the contents of particular
-system-specific files or directories, like F</etc/passwd>,
-F</etc/sendmail.conf>, F</etc/resolv.conf>, or even F</tmp/>. For
-example, F</etc/passwd> may exist but not contain the encrypted
-passwords, because the system is using some form of enhanced security.
-Or it may not contain all the accounts, because the system is using NIS.
-If code does need to rely on such a file, include a description of the
-file and its format in the code's documentation, then make it easy for
-the user to override the default location of the file.
-
-Don't assume a text file will end with a newline. They should,
-but people forget.
-
-Do not have two files or directories of the same name with different
-case, like F<test.pl> and F<Test.pl>, as many platforms have
-case-insensitive (or at least case-forgiving) filenames. Also, try
-not to have non-word characters (except for C<.>) in the names, and
-keep them to the 8.3 convention, for maximum portability, onerous a
-burden though this may appear.
-
-Likewise, when using the AutoSplit module, try to keep your functions to
-8.3 naming and case-insensitive conventions; or, at the least,
-make it so the resulting files have a unique (case-insensitively)
-first 8 characters.
-
-Whitespace in filenames is tolerated on most systems, but not all,
-and even on systems where it might be tolerated, some utilities
-might become confused by such whitespace.
-
-Many systems (DOS, VMS ODS-2) cannot have more than one C<.> in their
-filenames.
-
-Don't assume C<< > >> won't be the first character of a filename.
-Always use C<< < >> explicitly to open a file for reading, or even
-better, use the three-arg version of open, unless you want the user to
-be able to specify a pipe open.
-
- open my $fh, '<', $existing_file) or die $!;
-
-If filenames might use strange characters, it is safest to open it
-with C<sysopen> instead of C<open>. C<open> is magic and can
-translate characters like C<< > >>, C<< < >>, and C<|>, which may
-be the wrong thing to do. (Sometimes, though, it's the right thing.)
-Three-arg open can also help protect against this translation in cases
-where it is undesirable.
-
-Don't use C<:> as a part of a filename since many systems use that for
-their own semantics (Mac OS Classic for separating pathname components,
-many networking schemes and utilities for separating the nodename and
-the pathname, and so on). For the same reasons, avoid C<@>, C<;> and
-C<|>.
-
-Don't assume that in pathnames you can collapse two leading slashes
-C<//> into one: some networking and clustering filesystems have special
-semantics for that. Let the operating system to sort it out.
-
-The I<portable filename characters> as defined by ANSI C are
-
- a b c d e f g h i j k l m n o p q r t u v w x y z
- A B C D E F G H I J K L M N O P Q R T U V W X Y Z
- 0 1 2 3 4 5 6 7 8 9
- . _ -
-
-and the "-" shouldn't be the first character. If you want to be
-hypercorrect, stay case-insensitive and within the 8.3 naming
-convention (all the files and directories have to be unique within one
-directory if their names are lowercased and truncated to eight
-characters before the C<.>, if any, and to three characters after the
-C<.>, if any). (And do not use C<.>s in directory names.)
-
-=head2 System Interaction
-
-Not all platforms provide a command line. These are usually platforms
-that rely primarily on a Graphical User Interface (GUI) for user
-interaction. A program requiring a command line interface might
-not work everywhere. This is probably for the user of the program
-to deal with, so don't stay up late worrying about it.
-
-Some platforms can't delete or rename files held open by the system,
-this limitation may also apply to changing filesystem metainformation
-like file permissions or owners. Remember to C<close> files when you
-are done with them. Don't C<unlink> or C<rename> an open file. Don't
-C<tie> or C<open> a file already tied or opened; C<untie> or C<close>
-it first.
-
-Don't open the same file more than once at a time for writing, as some
-operating systems put mandatory locks on such files.
-
-Don't assume that write/modify permission on a directory gives the
-right to add or delete files/directories in that directory. That is
-filesystem specific: in some filesystems you need write/modify
-permission also (or even just) in the file/directory itself. In some
-filesystems (AFS, DFS) the permission to add/delete directory entries
-is a completely separate permission.
-
-Don't assume that a single C<unlink> completely gets rid of the file:
-some filesystems (most notably the ones in VMS) have versioned
-filesystems, and unlink() removes only the most recent one (it doesn't
-remove all the versions because by default the native tools on those
-platforms remove just the most recent version, too). The portable
-idiom to remove all the versions of a file is
-
- 1 while unlink "file";
-
-This will terminate if the file is undeleteable for some reason
-(protected, not there, and so on).
-
-Don't count on a specific environment variable existing in C<%ENV>.
-Don't count on C<%ENV> entries being case-sensitive, or even
-case-preserving. Don't try to clear %ENV by saying C<%ENV = ();>, or,
-if you really have to, make it conditional on C<$^O ne 'VMS'> since in
-VMS the C<%ENV> table is much more than a per-process key-value string
-table.
-
-On VMS, some entries in the %ENV hash are dynamically created when
-their key is used on a read if they did not previously exist. The
-values for C<$ENV{HOME}>, C<$ENV{TERM}>, C<$ENV{HOME}>, and C<$ENV{USER}>,
-are known to be dynamically generated. The specific names that are
-dynamically generated may vary with the version of the C library on VMS,
-and more may exist than is documented.
-
-On VMS by default, changes to the %ENV hash are persistent after the process
-exits. This can cause unintended issues.
-
-Don't count on signals or C<%SIG> for anything.
-
-Don't count on filename globbing. Use C<opendir>, C<readdir>, and
-C<closedir> instead.
-
-Don't count on per-program environment variables, or per-program current
-directories.
-
-Don't count on specific values of C<$!>, neither numeric nor
-especially the strings values. Users may switch their locales causing
-error messages to be translated into their languages. If you can
-trust a POSIXish environment, you can portably use the symbols defined
-by the Errno module, like ENOENT. And don't trust on the values of C<$!>
-at all except immediately after a failed system call.
-
-=head2 Command names versus file pathnames
-
-Don't assume that the name used to invoke a command or program with
-C<system> or C<exec> can also be used to test for the existence of the
-file that holds the executable code for that command or program.
-First, many systems have "internal" commands that are built-in to the
-shell or OS and while these commands can be invoked, there is no
-corresponding file. Second, some operating systems (e.g., Cygwin,
-DJGPP, OS/2, and VOS) have required suffixes for executable files;
-these suffixes are generally permitted on the command name but are not
-required. Thus, a command like "perl" might exist in a file named
-"perl", "perl.exe", or "perl.pm", depending on the operating system.
-The variable "_exe" in the Config module holds the executable suffix,
-if any. Third, the VMS port carefully sets up $^X and
-$Config{perlpath} so that no further processing is required. This is
-just as well, because the matching regular expression used below would
-then have to deal with a possible trailing version number in the VMS
-file name.
-
-To convert $^X to a file pathname, taking account of the requirements
-of the various operating system possibilities, say:
-
- use Config;
- my $thisperl = $^X;
- if ($^O ne 'VMS')
- {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;}
-
-To convert $Config{perlpath} to a file pathname, say:
-
- use Config;
- my $thisperl = $Config{perlpath};
- if ($^O ne 'VMS')
- {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;}
-
-=head2 Networking
-
-Don't assume that you can reach the public Internet.
-
-Don't assume that there is only one way to get through firewalls
-to the public Internet.
-
-Don't assume that you can reach outside world through any other port
-than 80, or some web proxy. ftp is blocked by many firewalls.
-
-Don't assume that you can send email by connecting to the local SMTP port.
-
-Don't assume that you can reach yourself or any node by the name
-'localhost'. The same goes for '127.0.0.1'. You will have to try both.
-
-Don't assume that the host has only one network card, or that it
-can't bind to many virtual IP addresses.
-
-Don't assume a particular network device name.
-
-Don't assume a particular set of ioctl()s will work.
-
-Don't assume that you can ping hosts and get replies.
-
-Don't assume that any particular port (service) will respond.
-
-Don't assume that Sys::Hostname (or any other API or command) returns
-either a fully qualified hostname or a non-qualified hostname: it all
-depends on how the system had been configured. Also remember that for
-things such as DHCP and NAT, the hostname you get back might not be
-very useful.
-
-All the above "don't":s may look daunting, and they are, but the key
-is to degrade gracefully if one cannot reach the particular network
-service one wants. Croaking or hanging do not look very professional.
-
-=head2 Interprocess Communication (IPC)
-
-In general, don't directly access the system in code meant to be
-portable. That means, no C<system>, C<exec>, C<fork>, C<pipe>,
-C<``>, C<qx//>, C<open> with a C<|>, nor any of the other things
-that makes being a perl hacker worth being.
-
-Commands that launch external processes are generally supported on
-most platforms (though many of them do not support any type of
-forking). The problem with using them arises from what you invoke
-them on. External tools are often named differently on different
-platforms, may not be available in the same location, might accept
-different arguments, can behave differently, and often present their
-results in a platform-dependent way. Thus, you should seldom depend
-on them to produce consistent results. (Then again, if you're calling
-I<netstat -a>, you probably don't expect it to run on both Unix and CP/M.)
-
-One especially common bit of Perl code is opening a pipe to B<sendmail>:
-
- open(MAIL, '|/usr/lib/sendmail -t')
- or die "cannot fork sendmail: $!";
-
-This is fine for systems programming when sendmail is known to be
-available. But it is not fine for many non-Unix systems, and even
-some Unix systems that may not have sendmail installed. If a portable
-solution is needed, see the various distributions on CPAN that deal
-with it. Mail::Mailer and Mail::Send in the MailTools distribution are
-commonly used, and provide several mailing methods, including mail,
-sendmail, and direct SMTP (via Net::SMTP) if a mail transfer agent is
-not available. Mail::Sendmail is a standalone module that provides
-simple, platform-independent mailing.
-
-The Unix System V IPC (C<msg*(), sem*(), shm*()>) is not available
-even on all Unix platforms.
-
-Do not use either the bare result of C<pack("N", 10, 20, 30, 40)> or
-bare v-strings (such as C<v10.20.30.40>) to represent IPv4 addresses:
-both forms just pack the four bytes into network order. That this
-would be equal to the C language C<in_addr> struct (which is what the
-socket code internally uses) is not guaranteed. To be portable use
-the routines of the Socket extension, such as C<inet_aton()>,
-C<inet_ntoa()>, and C<sockaddr_in()>.
-
-The rule of thumb for portable code is: Do it all in portable Perl, or
-use a module (that may internally implement it with platform-specific
-code, but expose a common interface).
-
-=head2 External Subroutines (XS)
-
-XS code can usually be made to work with any platform, but dependent
-libraries, header files, etc., might not be readily available or
-portable, or the XS code itself might be platform-specific, just as Perl
-code might be. If the libraries and headers are portable, then it is
-normally reasonable to make sure the XS code is portable, too.
-
-A different type of portability issue arises when writing XS code:
-availability of a C compiler on the end-user's system. C brings
-with it its own portability issues, and writing XS code will expose
-you to some of those. Writing purely in Perl is an easier way to
-achieve portability.
-
-=head2 Standard Modules
-
-In general, the standard modules work across platforms. Notable
-exceptions are the CPAN module (which currently makes connections to external
-programs that may not be available), platform-specific modules (like
-ExtUtils::MM_VMS), and DBM modules.
-
-There is no one DBM module available on all platforms.
-SDBM_File and the others are generally available on all Unix and DOSish
-ports, but not in MacPerl, where only NBDM_File and DB_File are
-available.
-
-The good news is that at least some DBM module should be available, and
-AnyDBM_File will use whichever module it can find. Of course, then
-the code needs to be fairly strict, dropping to the greatest common
-factor (e.g., not exceeding 1K for each record), so that it will
-work with any DBM module. See L<AnyDBM_File> for more details.
-
-=head2 Time and Date
-
-The system's notion of time of day and calendar date is controlled in
-widely different ways. Don't assume the timezone is stored in C<$ENV{TZ}>,
-and even if it is, don't assume that you can control the timezone through
-that variable. Don't assume anything about the three-letter timezone
-abbreviations (for example that MST would be the Mountain Standard Time,
-it's been known to stand for Moscow Standard Time). If you need to
-use timezones, express them in some unambiguous format like the
-exact number of minutes offset from UTC, or the POSIX timezone
-format.
-
-Don't assume that the epoch starts at 00:00:00, January 1, 1970,
-because that is OS- and implementation-specific. It is better to
-store a date in an unambiguous representation. The ISO 8601 standard
-defines YYYY-MM-DD as the date format, or YYYY-MM-DDTHH:MM:SS
-(that's a literal "T" separating the date from the time).
-Please do use the ISO 8601 instead of making us guess what
-date 02/03/04 might be. ISO 8601 even sorts nicely as-is.
-A text representation (like "1987-12-18") can be easily converted
-into an OS-specific value using a module like Date::Parse.
-An array of values, such as those returned by C<localtime>, can be
-converted to an OS-specific representation using Time::Local.
-
-When calculating specific times, such as for tests in time or date modules,
-it may be appropriate to calculate an offset for the epoch.
-
- require Time::Local;
- my $offset = Time::Local::timegm(0, 0, 0, 1, 0, 70);
-
-The value for C<$offset> in Unix will be C<0>, but in Mac OS Classic
-will be some large number. C<$offset> can then be added to a Unix time
-value to get what should be the proper value on any system.
-
-=head2 Character sets and character encoding
-
-Assume very little about character sets.
-
-Assume nothing about numerical values (C<ord>, C<chr>) of characters.
-Do not use explicit code point ranges (like \xHH-\xHH); use for
-example symbolic character classes like C<[:print:]>.
-
-Do not assume that the alphabetic characters are encoded contiguously
-(in the numeric sense). There may be gaps.
-
-Do not assume anything about the ordering of the characters.
-The lowercase letters may come before or after the uppercase letters;
-the lowercase and uppercase may be interlaced so that both "a" and "A"
-come before "b"; the accented and other international characters may
-be interlaced so that E<auml> comes before "b".
-
-=head2 Internationalisation
-
-If you may assume POSIX (a rather large assumption), you may read
-more about the POSIX locale system from L<perllocale>. The locale
-system at least attempts to make things a little bit more portable,
-or at least more convenient and native-friendly for non-English
-users. The system affects character sets and encoding, and date
-and time formatting--amongst other things.
-
-If you really want to be international, you should consider Unicode.
-See L<perluniintro> and L<perlunicode> for more information.
-
-If you want to use non-ASCII bytes (outside the bytes 0x00..0x7f) in
-the "source code" of your code, to be portable you have to be explicit
-about what bytes they are. Someone might for example be using your
-code under a UTF-8 locale, in which case random native bytes might be
-illegal ("Malformed UTF-8 ...") This means that for example embedding
-ISO 8859-1 bytes beyond 0x7f into your strings might cause trouble
-later. If the bytes are native 8-bit bytes, you can use the C<bytes>
-pragma. If the bytes are in a string (regular expression being a
-curious string), you can often also use the C<\xHH> notation instead
-of embedding the bytes as-is. (If you want to write your code in UTF-8,
-you can use the C<utf8>.) The C<bytes> and C<utf8> pragmata are
-available since Perl 5.6.0.
-
-=head2 System Resources
-
-If your code is destined for systems with severely constrained (or
-missing!) virtual memory systems then you want to be I<especially> mindful
-of avoiding wasteful constructs such as:
-
- my @lines = <$very_large_file>; # bad
-
- while (<$fh>) {$file .= $_} # sometimes bad
- my $file = join('', <$fh>); # better
-
-The last two constructs may appear unintuitive to most people. The
-first repeatedly grows a string, whereas the second allocates a
-large chunk of memory in one go. On some systems, the second is
-more efficient that the first.
-
-=head2 Security
-
-Most multi-user platforms provide basic levels of security, usually
-implemented at the filesystem level. Some, however, unfortunately do
-not. Thus the notion of user id, or "home" directory,
-or even the state of being logged-in, may be unrecognizable on many
-platforms. If you write programs that are security-conscious, it
-is usually best to know what type of system you will be running
-under so that you can write code explicitly for that platform (or
-class of platforms).
-
-Don't assume the Unix filesystem access semantics: the operating
-system or the filesystem may be using some ACL systems, which are
-richer languages than the usual rwx. Even if the rwx exist,
-their semantics might be different.
-
-(From security viewpoint testing for permissions before attempting to
-do something is silly anyway: if one tries this, there is potential
-for race conditions. Someone or something might change the
-permissions between the permissions check and the actual operation.
-Just try the operation.)
-
-Don't assume the Unix user and group semantics: especially, don't
-expect the C<< $< >> and C<< $> >> (or the C<$(> and C<$)>) to work
-for switching identities (or memberships).
-
-Don't assume set-uid and set-gid semantics. (And even if you do,
-think twice: set-uid and set-gid are a known can of security worms.)
-
-=head2 Style
-
-For those times when it is necessary to have platform-specific code,
-consider keeping the platform-specific code in one place, making porting
-to other platforms easier. Use the Config module and the special
-variable C<$^O> to differentiate platforms, as described in
-L<"PLATFORMS">.
-
-Be careful in the tests you supply with your module or programs.
-Module code may be fully portable, but its tests might not be. This
-often happens when tests spawn off other processes or call external
-programs to aid in the testing, or when (as noted above) the tests
-assume certain things about the filesystem and paths. Be careful not
-to depend on a specific output style for errors, such as when checking
-C<$!> after a failed system call. Using C<$!> for anything else than
-displaying it as output is doubtful (though see the Errno module for
-testing reasonably portably for error value). Some platforms expect
-a certain output format, and Perl on those platforms may have been
-adjusted accordingly. Most specifically, don't anchor a regex when
-testing an error value.
-
-=head1 CPAN Testers
-
-Modules uploaded to CPAN are tested by a variety of volunteers on
-different platforms. These CPAN testers are notified by mail of each
-new upload, and reply to the list with PASS, FAIL, NA (not applicable to
-this platform), or UNKNOWN (unknown), along with any relevant notations.
-
-The purpose of the testing is twofold: one, to help developers fix any
-problems in their code that crop up because of lack of testing on other
-platforms; two, to provide users with information about whether
-a given module works on a given platform.
-
-Also see:
-
-=over 4
-
-=item *
-
-Mailing list: cpan-testers-discuss@perl.org
-
-=item *
-
-Testing results: L<http://www.cpantesters.org/>
-
-=back
-
-=head1 PLATFORMS
-
-As of version 5.002, Perl is built with a C<$^O> variable that
-indicates the operating system it was built on. This was implemented
-to help speed up code that would otherwise have to C<use Config>
-and use the value of C<$Config{osname}>. Of course, to get more
-detailed information about the system, looking into C<%Config> is
-certainly recommended.
-
-C<%Config> cannot always be trusted, however, because it was built
-at compile time. If perl was built in one place, then transferred
-elsewhere, some values may be wrong. The values may even have been
-edited after the fact.
-
-=head2 Unix
-
-Perl works on a bewildering variety of Unix and Unix-like platforms (see
-e.g. most of the files in the F<hints/> directory in the source code kit).
-On most of these systems, the value of C<$^O> (hence C<$Config{'osname'}>,
-too) is determined either by lowercasing and stripping punctuation from the
-first field of the string returned by typing C<uname -a> (or a similar command)
-at the shell prompt or by testing the file system for the presence of
-uniquely named files such as a kernel or header file. Here, for example,
-are a few of the more popular Unix flavors:
-
- uname $^O $Config{'archname'}
- --------------------------------------------
- AIX aix aix
- BSD/OS bsdos i386-bsdos
- Darwin darwin darwin
- dgux dgux AViiON-dgux
- DYNIX/ptx dynixptx i386-dynixptx
- FreeBSD freebsd freebsd-i386
- Haiku haiku BePC-haiku
- Linux linux arm-linux
- Linux linux i386-linux
- Linux linux i586-linux
- Linux linux ppc-linux
- HP-UX hpux PA-RISC1.1
- IRIX irix irix
- Mac OS X darwin darwin
- NeXT 3 next next-fat
- NeXT 4 next OPENSTEP-Mach
- openbsd openbsd i386-openbsd
- OSF1 dec_osf alpha-dec_osf
- reliantunix-n svr4 RM400-svr4
- SCO_SV sco_sv i386-sco_sv
- SINIX-N svr4 RM400-svr4
- sn4609 unicos CRAY_C90-unicos
- sn6521 unicosmk t3e-unicosmk
- sn9617 unicos CRAY_J90-unicos
- SunOS solaris sun4-solaris
- SunOS solaris i86pc-solaris
- SunOS4 sunos sun4-sunos
-
-Because the value of C<$Config{archname}> may depend on the
-hardware architecture, it can vary more than the value of C<$^O>.
-
-=head2 DOS and Derivatives
-
-Perl has long been ported to Intel-style microcomputers running under
-systems like PC-DOS, MS-DOS, OS/2, and most Windows platforms you can
-bring yourself to mention (except for Windows CE, if you count that).
-Users familiar with I<COMMAND.COM> or I<CMD.EXE> style shells should
-be aware that each of these file specifications may have subtle
-differences:
-
- my $filespec0 = "c:/foo/bar/file.txt";
- my $filespec1 = "c:\\foo\\bar\\file.txt";
- my $filespec2 = 'c:\foo\bar\file.txt';
- my $filespec3 = 'c:\\foo\\bar\\file.txt';
-
-System calls accept either C</> or C<\> as the path separator.
-However, many command-line utilities of DOS vintage treat C</> as
-the option prefix, so may get confused by filenames containing C</>.
-Aside from calling any external programs, C</> will work just fine,
-and probably better, as it is more consistent with popular usage,
-and avoids the problem of remembering what to backwhack and what
-not to.
-
-The DOS FAT filesystem can accommodate only "8.3" style filenames. Under
-the "case-insensitive, but case-preserving" HPFS (OS/2) and NTFS (NT)
-filesystems you may have to be careful about case returned with functions
-like C<readdir> or used with functions like C<open> or C<opendir>.
-
-DOS also treats several filenames as special, such as AUX, PRN,
-NUL, CON, COM1, LPT1, LPT2, etc. Unfortunately, sometimes these
-filenames won't even work if you include an explicit directory
-prefix. It is best to avoid such filenames, if you want your code
-to be portable to DOS and its derivatives. It's hard to know what
-these all are, unfortunately.
-
-Users of these operating systems may also wish to make use of
-scripts such as I<pl2bat.bat> or I<pl2cmd> to
-put wrappers around your scripts.
-
-Newline (C<\n>) is translated as C<\015\012> by STDIO when reading from
-and writing to files (see L<"Newlines">). C<binmode(FILEHANDLE)>
-will keep C<\n> translated as C<\012> for that filehandle. Since it is a
-no-op on other systems, C<binmode> should be used for cross-platform code
-that deals with binary data. That's assuming you realize in advance
-that your data is in binary. General-purpose programs should
-often assume nothing about their data.
-
-The C<$^O> variable and the C<$Config{archname}> values for various
-DOSish perls are as follows:
-
- OS $^O $Config{archname} ID Version
- --------------------------------------------------------
- MS-DOS dos ?
- PC-DOS dos ?
- OS/2 os2 ?
- Windows 3.1 ? ? 0 3 01
- Windows 95 MSWin32 MSWin32-x86 1 4 00
- Windows 98 MSWin32 MSWin32-x86 1 4 10
- Windows ME MSWin32 MSWin32-x86 1 ?
- Windows NT MSWin32 MSWin32-x86 2 4 xx
- Windows NT MSWin32 MSWin32-ALPHA 2 4 xx
- Windows NT MSWin32 MSWin32-ppc 2 4 xx
- Windows 2000 MSWin32 MSWin32-x86 2 5 00
- Windows XP MSWin32 MSWin32-x86 2 5 01
- Windows 2003 MSWin32 MSWin32-x86 2 5 02
- Windows Vista MSWin32 MSWin32-x86 2 6 00
- Windows 7 MSWin32 MSWin32-x86 2 6 01
- Windows 7 MSWin32 MSWin32-x64 2 6 01
- Windows 2008 MSWin32 MSWin32-x86 2 6 01
- Windows 2008 MSWin32 MSWin32-x64 2 6 01
- Windows CE MSWin32 ? 3
- Cygwin cygwin cygwin
-
-The various MSWin32 Perl's can distinguish the OS they are running on
-via the value of the fifth element of the list returned from
-Win32::GetOSVersion(). For example:
-
- if ($^O eq 'MSWin32') {
- my @os_version_info = Win32::GetOSVersion();
- print +('3.1','95','NT')[$os_version_info[4]],"\n";
- }
-
-There are also Win32::IsWinNT() and Win32::IsWin95(), try C<perldoc Win32>,
-and as of libwin32 0.19 (not part of the core Perl distribution)
-Win32::GetOSName(). The very portable POSIX::uname() will work too:
-
- c:\> perl -MPOSIX -we "print join '|', uname"
- Windows NT|moonru|5.0|Build 2195 (Service Pack 2)|x86
-
-Also see:
-
-=over 4
-
-=item *
-
-The djgpp environment for DOS, L<http://www.delorie.com/djgpp/>
-and L<perldos>.
-
-=item *
-
-The EMX environment for DOS, OS/2, etc. emx@iaehv.nl,
-L<ftp://hobbes.nmsu.edu/pub/os2/dev/emx/> Also L<perlos2>.
-
-=item *
-
-Build instructions for Win32 in L<perlwin32>, or under the Cygnus environment
-in L<perlcygwin>.
-
-=item *
-
-The C<Win32::*> modules in L<Win32>.
-
-=item *
-
-The ActiveState Pages, L<http://www.activestate.com/>
-
-=item *
-
-The Cygwin environment for Win32; F<README.cygwin> (installed
-as L<perlcygwin>), L<http://www.cygwin.com/>
-
-=item *
-
-The U/WIN environment for Win32,
-L<http://www.research.att.com/sw/tools/uwin/>
-
-=item *
-
-Build instructions for OS/2, L<perlos2>
-
-=back
-
-=head2 VMS
-
-Perl on VMS is discussed in L<perlvms> in the perl distribution.
-
-The official name of VMS as of this writing is OpenVMS.
-
-Perl on VMS can accept either VMS- or Unix-style file
-specifications as in either of the following:
-
- $ perl -ne "print if /perl_setup/i" SYS$LOGIN:LOGIN.COM
- $ perl -ne "print if /perl_setup/i" /sys$login/login.com
-
-but not a mixture of both as in:
-
- $ perl -ne "print if /perl_setup/i" sys$login:/login.com
- Can't open sys$login:/login.com: file specification syntax error
-
-Interacting with Perl from the Digital Command Language (DCL) shell
-often requires a different set of quotation marks than Unix shells do.
-For example:
-
- $ perl -e "print ""Hello, world.\n"""
- Hello, world.
-
-There are several ways to wrap your perl scripts in DCL F<.COM> files, if
-you are so inclined. For example:
-
- $ write sys$output "Hello from DCL!"
- $ if p1 .eqs. ""
- $ then perl -x 'f$environment("PROCEDURE")
- $ else perl -x - 'p1 'p2 'p3 'p4 'p5 'p6 'p7 'p8
- $ deck/dollars="__END__"
- #!/usr/bin/perl
-
- print "Hello from Perl!\n";
-
- __END__
- $ endif
-
-Do take care with C<$ ASSIGN/nolog/user SYS$COMMAND: SYS$INPUT> if your
-perl-in-DCL script expects to do things like C<< $read = <STDIN>; >>.
-
-The VMS operating system has two filesystems, known as ODS-2 and ODS-5.
-
-For ODS-2, filenames are in the format "name.extension;version". The
-maximum length for filenames is 39 characters, and the maximum length for
-extensions is also 39 characters. Version is a number from 1 to
-32767. Valid characters are C</[A-Z0-9$_-]/>.
-
-The ODS-2 filesystem is case-insensitive and does not preserve case.
-Perl simulates this by converting all filenames to lowercase internally.
-
-For ODS-5, filenames may have almost any character in them and can include
-Unicode characters. Characters that could be misinterpreted by the DCL
-shell or file parsing utilities need to be prefixed with the C<^>
-character, or replaced with hexadecimal characters prefixed with the
-C<^> character. Such prefixing is only needed with the pathnames are
-in VMS format in applications. Programs that can accept the Unix format
-of pathnames do not need the escape characters. The maximum length for
-filenames is 255 characters. The ODS-5 file system can handle both
-a case preserved and a case sensitive mode.
-
-ODS-5 is only available on the OpenVMS for 64 bit platforms.
-
-Support for the extended file specifications is being done as optional
-settings to preserve backward compatibility with Perl scripts that
-assume the previous VMS limitations.
-
-In general routines on VMS that get a Unix format file specification
-should return it in a Unix format, and when they get a VMS format
-specification they should return a VMS format unless they are documented
-to do a conversion.
-
-For routines that generate return a file specification, VMS allows setting
-if the C library which Perl is built on if it will be returned in VMS
-format or in Unix format.
-
-With the ODS-2 file system, there is not much difference in syntax of
-filenames without paths for VMS or Unix. With the extended character
-set available with ODS-5 there can be a significant difference.
-
-Because of this, existing Perl scripts written for VMS were sometimes
-treating VMS and Unix filenames interchangeably. Without the extended
-character set enabled, this behavior will mostly be maintained for
-backwards compatibility.
-
-When extended characters are enabled with ODS-5, the handling of
-Unix formatted file specifications is to that of a Unix system.
-
-VMS file specifications without extensions have a trailing dot. An
-equivalent Unix file specification should not show the trailing dot.
-
-The result of all of this, is that for VMS, for portable scripts, you
-can not depend on Perl to present the filenames in lowercase, to be
-case sensitive, and that the filenames could be returned in either
-Unix or VMS format.
-
-And if a routine returns a file specification, unless it is intended to
-convert it, it should return it in the same format as it found it.
-
-C<readdir> by default has traditionally returned lowercased filenames.
-When the ODS-5 support is enabled, it will return the exact case of the
-filename on the disk.
-
-Files without extensions have a trailing period on them, so doing a
-C<readdir> in the default mode with a file named F<A.;5> will
-return F<a.> when VMS is (though that file could be opened with
-C<open(FH, 'A')>).
-
-With support for extended file specifications and if C<opendir> was
-given a Unix format directory, a file named F<A.;5> will return F<a>
-and optionally in the exact case on the disk. When C<opendir> is given
-a VMS format directory, then C<readdir> should return F<a.>, and
-again with the optionally the exact case.
-
-RMS had an eight level limit on directory depths from any rooted logical
-(allowing 16 levels overall) prior to VMS 7.2, and even with versions of
-VMS on VAX up through 7.3. Hence C<PERL_ROOT:[LIB.2.3.4.5.6.7.8]> is a
-valid directory specification but C<PERL_ROOT:[LIB.2.3.4.5.6.7.8.9]> is
-not. F<Makefile.PL> authors might have to take this into account, but at
-least they can refer to the former as C</PERL_ROOT/lib/2/3/4/5/6/7/8/>.
-
-Pumpkings and module integrators can easily see whether files with too many
-directory levels have snuck into the core by running the following in the
-top-level source directory:
-
- $ perl -ne "$_=~s/\s+.*//; print if scalar(split /\//) > 8;" < MANIFEST
-
-
-The VMS::Filespec module, which gets installed as part of the build
-process on VMS, is a pure Perl module that can easily be installed on
-non-VMS platforms and can be helpful for conversions to and from RMS
-native formats. It is also now the only way that you should check to
-see if VMS is in a case sensitive mode.
-
-What C<\n> represents depends on the type of file opened. It usually
-represents C<\012> but it could also be C<\015>, C<\012>, C<\015\012>,
-C<\000>, C<\040>, or nothing depending on the file organization and
-record format. The VMS::Stdio module provides access to the
-special fopen() requirements of files with unusual attributes on VMS.
-
-TCP/IP stacks are optional on VMS, so socket routines might not be
-implemented. UDP sockets may not be supported.
-
-The TCP/IP library support for all current versions of VMS is dynamically
-loaded if present, so even if the routines are configured, they may
-return a status indicating that they are not implemented.
-
-The value of C<$^O> on OpenVMS is "VMS". To determine the architecture
-that you are running on without resorting to loading all of C<%Config>
-you can examine the content of the C<@INC> array like so:
-
- if (grep(/VMS_AXP/, @INC)) {
- print "I'm on Alpha!\n";
-
- } elsif (grep(/VMS_VAX/, @INC)) {
- print "I'm on VAX!\n";
-
- } elsif (grep(/VMS_IA64/, @INC)) {
- print "I'm on IA64!\n";
-
- } else {
- print "I'm not so sure about where $^O is...\n";
- }
-
-In general, the significant differences should only be if Perl is running
-on VMS_VAX or one of the 64 bit OpenVMS platforms.
-
-On VMS, perl determines the UTC offset from the C<SYS$TIMEZONE_DIFFERENTIAL>
-logical name. Although the VMS epoch began at 17-NOV-1858 00:00:00.00,
-calls to C<localtime> are adjusted to count offsets from
-01-JAN-1970 00:00:00.00, just like Unix.
-
-Also see:
-
-=over 4
-
-=item *
-
-F<README.vms> (installed as F<README_vms>), L<perlvms>
-
-=item *
-
-vmsperl list, vmsperl-subscribe@perl.org
-
-=item *
-
-vmsperl on the web, L<http://www.sidhe.org/vmsperl/index.html>
-
-=back
-
-=head2 VOS
-
-Perl on VOS (also known as OpenVOS) is discussed in F<README.vos>
-in the perl distribution (installed as L<perlvos>). Perl on VOS
-can accept either VOS- or Unix-style file specifications as in
-either of the following:
-
- $ perl -ne "print if /perl_setup/i" >system>notices
- $ perl -ne "print if /perl_setup/i" /system/notices
-
-or even a mixture of both as in:
-
- $ perl -ne "print if /perl_setup/i" >system/notices
-
-Even though VOS allows the slash character to appear in object
-names, because the VOS port of Perl interprets it as a pathname
-delimiting character, VOS files, directories, or links whose
-names contain a slash character cannot be processed. Such files
-must be renamed before they can be processed by Perl.
-
-Older releases of VOS (prior to OpenVOS Release 17.0) limit file
-names to 32 or fewer characters, prohibit file names from
-starting with a C<-> character, and prohibit file names from
-containing any character matching C<< tr/ !#%&'()*;<=>?// >>.
-
-Newer releases of VOS (OpenVOS Release 17.0 or later) support a
-feature known as extended names. On these releases, file names
-can contain up to 255 characters, are prohibited from starting
-with a C<-> character, and the set of prohibited characters is
-reduced to any character matching C<< tr/#%*<>?// >>. There are
-restrictions involving spaces and apostrophes: these characters
-must not begin or end a name, nor can they immediately precede or
-follow a period. Additionally, a space must not immediately
-precede another space or hyphen. Specifically, the following
-character combinations are prohibited: space-space,
-space-hyphen, period-space, space-period, period-apostrophe,
-apostrophe-period, leading or trailing space, and leading or
-trailing apostrophe. Although an extended file name is limited
-to 255 characters, a path name is still limited to 256
-characters.
-
-The value of C<$^O> on VOS is "VOS". To determine the
-architecture that you are running on without resorting to loading
-all of C<%Config> you can examine the content of the @INC array
-like so:
-
- if ($^O =~ /VOS/) {
- print "I'm on a Stratus box!\n";
- } else {
- print "I'm not on a Stratus box!\n";
- die;
- }
-
-Also see:
-
-=over 4
-
-=item *
-
-F<README.vos> (installed as L<perlvos>)
-
-=item *
-
-The VOS mailing list.
-
-There is no specific mailing list for Perl on VOS. You can post
-comments to the comp.sys.stratus newsgroup, or use the contact
-information located in the distribution files on the Stratus
-Anonymous FTP site.
-
-=item *
-
-VOS Perl on the web at L<http://ftp.stratus.com/pub/vos/posix/posix.html>
-
-=back
-
-=head2 EBCDIC Platforms
-
-Recent versions of Perl have been ported to platforms such as OS/400 on
-AS/400 minicomputers as well as OS/390, VM/ESA, and BS2000 for S/390
-Mainframes. Such computers use EBCDIC character sets internally (usually
-Character Code Set ID 0037 for OS/400 and either 1047 or POSIX-BC for S/390
-systems). On the mainframe perl currently works under the "Unix system
-services for OS/390" (formerly known as OpenEdition), VM/ESA OpenEdition, or
-the BS200 POSIX-BC system (BS2000 is supported in perl 5.6 and greater).
-See L<perlos390> for details. Note that for OS/400 there is also a port of
-Perl 5.8.1/5.9.0 or later to the PASE which is ASCII-based (as opposed to
-ILE which is EBCDIC-based), see L<perlos400>.
-
-As of R2.5 of USS for OS/390 and Version 2.3 of VM/ESA these Unix
-sub-systems do not support the C<#!> shebang trick for script invocation.
-Hence, on OS/390 and VM/ESA perl scripts can be executed with a header
-similar to the following simple script:
-
- : # use perl
- eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
- if 0;
- #!/usr/local/bin/perl # just a comment really
-
- print "Hello from perl!\n";
-
-OS/390 will support the C<#!> shebang trick in release 2.8 and beyond.
-Calls to C<system> and backticks can use POSIX shell syntax on all
-S/390 systems.
-
-On the AS/400, if PERL5 is in your library list, you may need
-to wrap your perl scripts in a CL procedure to invoke them like so:
-
- BEGIN
- CALL PGM(PERL5/PERL) PARM('/QOpenSys/hello.pl')
- ENDPGM
-
-This will invoke the perl script F<hello.pl> in the root of the
-QOpenSys file system. On the AS/400 calls to C<system> or backticks
-must use CL syntax.
-
-On these platforms, bear in mind that the EBCDIC character set may have
-an effect on what happens with some perl functions (such as C<chr>,
-C<pack>, C<print>, C<printf>, C<ord>, C<sort>, C<sprintf>, C<unpack>), as
-well as bit-fiddling with ASCII constants using operators like C<^>, C<&>
-and C<|>, not to mention dealing with socket interfaces to ASCII computers
-(see L<"Newlines">).
-
-Fortunately, most web servers for the mainframe will correctly
-translate the C<\n> in the following statement to its ASCII equivalent
-(C<\r> is the same under both Unix and OS/390 & VM/ESA):
-
- print "Content-type: text/html\r\n\r\n";
-
-The values of C<$^O> on some of these platforms includes:
-
- uname $^O $Config{'archname'}
- --------------------------------------------
- OS/390 os390 os390
- OS400 os400 os400
- POSIX-BC posix-bc BS2000-posix-bc
- VM/ESA vmesa vmesa
-
-Some simple tricks for determining if you are running on an EBCDIC
-platform could include any of the following (perhaps all):
-
- if ("\t" eq "\005") { print "EBCDIC may be spoken here!\n"; }
-
- if (ord('A') == 193) { print "EBCDIC may be spoken here!\n"; }
-
- if (chr(169) eq 'z') { print "EBCDIC may be spoken here!\n"; }
-
-One thing you may not want to rely on is the EBCDIC encoding
-of punctuation characters since these may differ from code page to code
-page (and once your module or script is rumoured to work with EBCDIC,
-folks will want it to work with all EBCDIC character sets).
-
-Also see:
-
-=over 4
-
-=item *
-
-L<perlos390>, F<README.os390>, F<perlbs2000>, F<README.vmesa>,
-L<perlebcdic>.
-
-=item *
-
-The perl-mvs@perl.org list is for discussion of porting issues as well as
-general usage issues for all EBCDIC Perls. Send a message body of
-"subscribe perl-mvs" to majordomo@perl.org.
-
-=item *
-
-AS/400 Perl information at
-L<http://as400.rochester.ibm.com/>
-as well as on CPAN in the F<ports/> directory.
-
-=back
-
-=head2 Acorn RISC OS
-
-Because Acorns use ASCII with newlines (C<\n>) in text files as C<\012> like
-Unix, and because Unix filename emulation is turned on by default,
-most simple scripts will probably work "out of the box". The native
-filesystem is modular, and individual filesystems are free to be
-case-sensitive or insensitive, and are usually case-preserving. Some
-native filesystems have name length limits, which file and directory
-names are silently truncated to fit. Scripts should be aware that the
-standard filesystem currently has a name length limit of B<10>
-characters, with up to 77 items in a directory, but other filesystems
-may not impose such limitations.
-
-Native filenames are of the form
-
- Filesystem#Special_Field::DiskName.$.Directory.Directory.File
-
-where
-
- Special_Field is not usually present, but may contain . and $ .
- Filesystem =~ m|[A-Za-z0-9_]|
- DsicName =~ m|[A-Za-z0-9_/]|
- $ represents the root directory
- . is the path separator
- @ is the current directory (per filesystem but machine global)
- ^ is the parent directory
- Directory and File =~ m|[^\0- "\.\$\%\&:\@\\^\|\177]+|
-
-The default filename translation is roughly C<tr|/.|./|;>
-
-Note that C<"ADFS::HardDisk.$.File" ne 'ADFS::HardDisk.$.File'> and that
-the second stage of C<$> interpolation in regular expressions will fall
-foul of the C<$.> if scripts are not careful.
-
-Logical paths specified by system variables containing comma-separated
-search lists are also allowed; hence C<System:Modules> is a valid
-filename, and the filesystem will prefix C<Modules> with each section of
-C<System$Path> until a name is made that points to an object on disk.
-Writing to a new file C<System:Modules> would be allowed only if
-C<System$Path> contains a single item list. The filesystem will also
-expand system variables in filenames if enclosed in angle brackets, so
-C<< <System$Dir>.Modules >> would look for the file
-S<C<$ENV{'System$Dir'} . 'Modules'>>. The obvious implication of this is
-that B<fully qualified filenames can start with C<< <> >>> and should
-be protected when C<open> is used for input.
-
-Because C<.> was in use as a directory separator and filenames could not
-be assumed to be unique after 10 characters, Acorn implemented the C
-compiler to strip the trailing C<.c> C<.h> C<.s> and C<.o> suffix from
-filenames specified in source code and store the respective files in
-subdirectories named after the suffix. Hence files are translated:
-
- foo.h h.foo
- C:foo.h C:h.foo (logical path variable)
- sys/os.h sys.h.os (C compiler groks Unix-speak)
- 10charname.c c.10charname
- 10charname.o o.10charname
- 11charname_.c c.11charname (assuming filesystem truncates at 10)
-
-The Unix emulation library's translation of filenames to native assumes
-that this sort of translation is required, and it allows a user-defined list
-of known suffixes that it will transpose in this fashion. This may
-seem transparent, but consider that with these rules F<foo/bar/baz.h>
-and F<foo/bar/h/baz> both map to F<foo.bar.h.baz>, and that C<readdir> and
-C<glob> cannot and do not attempt to emulate the reverse mapping. Other
-C<.>'s in filenames are translated to C</>.
-
-As implied above, the environment accessed through C<%ENV> is global, and
-the convention is that program specific environment variables are of the
-form C<Program$Name>. Each filesystem maintains a current directory,
-and the current filesystem's current directory is the B<global> current
-directory. Consequently, sociable programs don't change the current
-directory but rely on full pathnames, and programs (and Makefiles) cannot
-assume that they can spawn a child process which can change the current
-directory without affecting its parent (and everyone else for that
-matter).
-
-Because native operating system filehandles are global and are currently
-allocated down from 255, with 0 being a reserved value, the Unix emulation
-library emulates Unix filehandles. Consequently, you can't rely on
-passing C<STDIN>, C<STDOUT>, or C<STDERR> to your children.
-
-The desire of users to express filenames of the form
-C<< <Foo$Dir>.Bar >> on the command line unquoted causes problems,
-too: C<``> command output capture has to perform a guessing game. It
-assumes that a string C<< <[^<>]+\$[^<>]> >> is a
-reference to an environment variable, whereas anything else involving
-C<< < >> or C<< > >> is redirection, and generally manages to be 99%
-right. Of course, the problem remains that scripts cannot rely on any
-Unix tools being available, or that any tools found have Unix-like command
-line arguments.
-
-Extensions and XS are, in theory, buildable by anyone using free
-tools. In practice, many don't, as users of the Acorn platform are
-used to binary distributions. MakeMaker does run, but no available
-make currently copes with MakeMaker's makefiles; even if and when
-this should be fixed, the lack of a Unix-like shell will cause
-problems with makefile rules, especially lines of the form C<cd
-sdbm && make all>, and anything using quoting.
-
-"S<RISC OS>" is the proper name for the operating system, but the value
-in C<$^O> is "riscos" (because we don't like shouting).
-
-=head2 Other perls
-
-Perl has been ported to many platforms that do not fit into any of
-the categories listed above. Some, such as AmigaOS, BeOS, HP MPE/iX,
-QNX, Plan 9, and VOS, have been well-integrated into the standard
-Perl source code kit. You may need to see the F<ports/> directory
-on CPAN for information, and possibly binaries, for the likes of:
-aos, Atari ST, lynxos, riscos, Novell Netware, Tandem Guardian,
-I<etc.> (Yes, we know that some of these OSes may fall under the
-Unix category, but we are not a standards body.)
-
-Some approximate operating system names and their C<$^O> values
-in the "OTHER" category include:
-
- OS $^O $Config{'archname'}
- ------------------------------------------
- Amiga DOS amigaos m68k-amigos
- BeOS beos
- MPE/iX mpeix PA-RISC1.1
-
-See also:
-
-=over 4
-
-=item *
-
-Amiga, F<README.amiga> (installed as L<perlamiga>).
-
-=item *
-
-Be OS, F<README.beos>
-
-=item *
-
-HP 300 MPE/iX, F<README.mpeix> and Mark Bixby's web page
-L<http://www.bixby.org/mark/porting.html>
-
-=item *
-
-A free perl5-based PERL.NLM for Novell Netware is available in
-precompiled binary and source code form from L<http://www.novell.com/>
-as well as from CPAN.
-
-=item *
-
-S<Plan 9>, F<README.plan9>
-
-=back
-
-=head1 FUNCTION IMPLEMENTATIONS
-
-Listed below are functions that are either completely unimplemented
-or else have been implemented differently on various platforms.
-Following each description will be, in parentheses, a list of
-platforms that the description applies to.
-
-The list may well be incomplete, or even wrong in some places. When
-in doubt, consult the platform-specific README files in the Perl
-source distribution, and any other documentation resources accompanying
-a given port.
-
-Be aware, moreover, that even among Unix-ish systems there are variations.
-
-For many functions, you can also query C<%Config>, exported by
-default from the Config module. For example, to check whether the
-platform has the C<lstat> call, check C<$Config{d_lstat}>. See
-L<Config> for a full description of available variables.
-
-=head2 Alphabetical Listing of Perl Functions
-
-=over 8
-
-=item -X
-
-C<-w> only inspects the read-only file attribute (FILE_ATTRIBUTE_READONLY),
-which determines whether the directory can be deleted, not whether it can
-be written to. Directories always have read and write access unless denied
-by discretionary access control lists (DACLs). (S<Win32>)
-
-C<-r>, C<-w>, C<-x>, and C<-o> tell whether the file is accessible,
-which may not reflect UIC-based file protections. (VMS)
-
-C<-s> by name on an open file will return the space reserved on disk,
-rather than the current extent. C<-s> on an open filehandle returns the
-current size. (S<RISC OS>)
-
-C<-R>, C<-W>, C<-X>, C<-O> are indistinguishable from C<-r>, C<-w>,
-C<-x>, C<-o>. (Win32, VMS, S<RISC OS>)
-
-C<-g>, C<-k>, C<-l>, C<-u>, C<-A> are not particularly meaningful.
-(Win32, VMS, S<RISC OS>)
-
-C<-p> is not particularly meaningful. (VMS, S<RISC OS>)
-
-C<-d> is true if passed a device spec without an explicit directory.
-(VMS)
-
-C<-x> (or C<-X>) determine if a file ends in one of the executable
-suffixes. C<-S> is meaningless. (Win32)
-
-C<-x> (or C<-X>) determine if a file has an executable file type.
-(S<RISC OS>)
-
-=item alarm
-
-Emulated using timers that must be explicitly polled whenever Perl
-wants to dispatch "safe signals" and therefore cannot interrupt
-blocking system calls. (Win32)
-
-=item atan2
-
-Due to issues with various CPUs, math libraries, compilers, and standards,
-results for C<atan2()> may vary depending on any combination of the above.
-Perl attempts to conform to the Open Group/IEEE standards for the results
-returned from C<atan2()>, but cannot force the issue if the system Perl is
-run on does not allow it. (Tru64, HP-UX 10.20)
-
-The current version of the standards for C<atan2()> is available at
-L<http://www.opengroup.org/onlinepubs/009695399/functions/atan2.html>.
-
-=item binmode
-
-Meaningless. (S<RISC OS>)
-
-Reopens file and restores pointer; if function fails, underlying
-filehandle may be closed, or pointer may be in a different position.
-(VMS)
-
-The value returned by C<tell> may be affected after the call, and
-the filehandle may be flushed. (Win32)
-
-=item chmod
-
-Only good for changing "owner" read-write access, "group", and "other"
-bits are meaningless. (Win32)
-
-Only good for changing "owner" and "other" read-write access. (S<RISC OS>)
-
-Access permissions are mapped onto VOS access-control list changes. (VOS)
-
-The actual permissions set depend on the value of the C<CYGWIN>
-in the SYSTEM environment settings. (Cygwin)
-
-=item chown
-
-Not implemented. (Win32, S<Plan 9>, S<RISC OS>)
-
-Does nothing, but won't fail. (Win32)
-
-A little funky, because VOS's notion of ownership is a little funky (VOS).
-
-=item chroot
-
-Not implemented. (Win32, VMS, S<Plan 9>, S<RISC OS>, VOS, VM/ESA)
-
-=item crypt
-
-May not be available if library or source was not provided when building
-perl. (Win32)
-
-=item dbmclose
-
-Not implemented. (VMS, S<Plan 9>, VOS)
-
-=item dbmopen
-
-Not implemented. (VMS, S<Plan 9>, VOS)
-
-=item dump
-
-Not useful. (S<RISC OS>)
-
-Not supported. (Cygwin, Win32)
-
-Invokes VMS debugger. (VMS)
-
-=item exec
-
-Implemented via Spawn. (VM/ESA)
-
-Does not automatically flush output handles on some platforms.
-(SunOS, Solaris, HP-UX)
-
-Not supported. (Symbian OS)
-
-=item exit
-
-Emulates Unix exit() (which considers C<exit 1> to indicate an error) by
-mapping the C<1> to SS$_ABORT (C<44>). This behavior may be overridden
-with the pragma C<use vmsish 'exit'>. As with the CRTL's exit()
-function, C<exit 0> is also mapped to an exit status of SS$_NORMAL
-(C<1>); this mapping cannot be overridden. Any other argument to exit()
-is used directly as Perl's exit status. On VMS, unless the future
-POSIX_EXIT mode is enabled, the exit code should always be a valid
-VMS exit code and not a generic number. When the POSIX_EXIT mode is
-enabled, a generic number will be encoded in a method compatible with
-the C library _POSIX_EXIT macro so that it can be decoded by other
-programs, particularly ones written in C, like the GNV package. (VMS)
-
-C<exit()> resets file pointers, which is a problem when called
-from a child process (created by C<fork()>) in C<BEGIN>.
-A workaround is to use C<POSIX::_exit>. (Solaris)
-
- exit unless $Config{archname} =~ /\bsolaris\b/;
- require POSIX and POSIX::_exit(0);
-
-=item fcntl
-
-Not implemented. (Win32)
-
-Some functions available based on the version of VMS. (VMS)
-
-=item flock
-
-Not implemented (VMS, S<RISC OS>, VOS).
-
-=item fork
-
-Not implemented. (AmigaOS, S<RISC OS>, VM/ESA, VMS)
-
-Emulated using multiple interpreters. See L<perlfork>. (Win32)
-
-Does not automatically flush output handles on some platforms.
-(SunOS, Solaris, HP-UX)
-
-=item getlogin
-
-Not implemented. (S<RISC OS>)
-
-=item getpgrp
-
-Not implemented. (Win32, VMS, S<RISC OS>)
-
-=item getppid
-
-Not implemented. (Win32, S<RISC OS>)
-
-=item getpriority
-
-Not implemented. (Win32, VMS, S<RISC OS>, VOS, VM/ESA)
-
-=item getpwnam
-
-Not implemented. (Win32)
-
-Not useful. (S<RISC OS>)
-
-=item getgrnam
-
-Not implemented. (Win32, VMS, S<RISC OS>)
-
-=item getnetbyname
-
-Not implemented. (Win32, S<Plan 9>)
-
-=item getpwuid
-
-Not implemented. (Win32)
-
-Not useful. (S<RISC OS>)
-
-=item getgrgid
-
-Not implemented. (Win32, VMS, S<RISC OS>)
-
-=item getnetbyaddr
-
-Not implemented. (Win32, S<Plan 9>)
-
-=item getprotobynumber
-
-=item getservbyport
-
-=item getpwent
-
-Not implemented. (Win32, VM/ESA)
-
-=item getgrent
-
-Not implemented. (Win32, VMS, VM/ESA)
-
-=item gethostbyname
-
-C<gethostbyname('localhost')> does not work everywhere: you may have
-to use C<gethostbyname('127.0.0.1')>. (S<Irix 5>)
-
-=item gethostent
-
-Not implemented. (Win32)
-
-=item getnetent
-
-Not implemented. (Win32, S<Plan 9>)
-
-=item getprotoent
-
-Not implemented. (Win32, S<Plan 9>)
-
-=item getservent
-
-Not implemented. (Win32, S<Plan 9>)
-
-=item sethostent
-
-Not implemented. (Win32, S<Plan 9>, S<RISC OS>)
-
-=item setnetent
-
-Not implemented. (Win32, S<Plan 9>, S<RISC OS>)
-
-=item setprotoent
-
-Not implemented. (Win32, S<Plan 9>, S<RISC OS>)
-
-=item setservent
-
-Not implemented. (S<Plan 9>, Win32, S<RISC OS>)
-
-=item endpwent
-
-Not implemented. (MPE/iX, VM/ESA, Win32)
-
-=item endgrent
-
-Not implemented. (MPE/iX, S<RISC OS>, VM/ESA, VMS, Win32)
-
-=item endhostent
-
-Not implemented. (Win32)
-
-=item endnetent
-
-Not implemented. (Win32, S<Plan 9>)
-
-=item endprotoent
-
-Not implemented. (Win32, S<Plan 9>)
-
-=item endservent
-
-Not implemented. (S<Plan 9>, Win32)
-
-=item getsockopt SOCKET,LEVEL,OPTNAME
-
-Not implemented. (S<Plan 9>)
-
-=item glob
-
-This operator is implemented via the File::Glob extension on most
-platforms. See L<File::Glob> for portability information.
-
-=item gmtime
-
-In theory, gmtime() is reliable from -2**63 to 2**63-1. However,
-because work arounds in the implementation use floating point numbers,
-it will become inaccurate as the time gets larger. This is a bug and
-will be fixed in the future.
-
-On VOS, time values are 32-bit quantities.
-
-=item ioctl FILEHANDLE,FUNCTION,SCALAR
-
-Not implemented. (VMS)
-
-Available only for socket handles, and it does what the ioctlsocket() call
-in the Winsock API does. (Win32)
-
-Available only for socket handles. (S<RISC OS>)
-
-=item kill
-
-Not implemented, hence not useful for taint checking. (S<RISC OS>)
-
-C<kill()> doesn't have the semantics of C<raise()>, i.e. it doesn't send
-a signal to the identified process like it does on Unix platforms.
-Instead C<kill($sig, $pid)> terminates the process identified by $pid,
-and makes it exit immediately with exit status $sig. As in Unix, if
-$sig is 0 and the specified process exists, it returns true without
-actually terminating it. (Win32)
-
-C<kill(-9, $pid)> will terminate the process specified by $pid and
-recursively all child processes owned by it. This is different from
-the Unix semantics, where the signal will be delivered to all
-processes in the same process group as the process specified by
-$pid. (Win32)
-
-Is not supported for process identification number of 0 or negative
-numbers. (VMS)
-
-=item link
-
-Not implemented. (MPE/iX, S<RISC OS>, VOS)
-
-Link count not updated because hard links are not quite that hard
-(They are sort of half-way between hard and soft links). (AmigaOS)
-
-Hard links are implemented on Win32 under NTFS only. They are
-natively supported on Windows 2000 and later. On Windows NT they
-are implemented using the Windows POSIX subsystem support and the
-Perl process will need Administrator or Backup Operator privileges
-to create hard links.
-
-Available on 64 bit OpenVMS 8.2 and later. (VMS)
-
-=item localtime
-
-localtime() has the same range as L</gmtime>, but because time zone
-rules change its accuracy for historical and future times may degrade
-but usually by no more than an hour.
-
-=item lstat
-
-Not implemented. (S<RISC OS>)
-
-Return values (especially for device and inode) may be bogus. (Win32)
-
-=item msgctl
-
-=item msgget
-
-=item msgsnd
-
-=item msgrcv
-
-Not implemented. (Win32, VMS, S<Plan 9>, S<RISC OS>, VOS)
-
-=item open
-
-open to C<|-> and C<-|> are unsupported. (Win32, S<RISC OS>)
-
-Opening a process does not automatically flush output handles on some
-platforms. (SunOS, Solaris, HP-UX)
-
-=item readlink
-
-Not implemented. (Win32, VMS, S<RISC OS>)
-
-=item rename
-
-Can't move directories between directories on different logical volumes. (Win32)
-
-=item rewinddir
-
-Will not cause readdir() to re-read the directory stream. The entries
-already read before the rewinddir() call will just be returned again
-from a cache buffer. (Win32)
-
-=item select
-
-Only implemented on sockets. (Win32, VMS)
-
-Only reliable on sockets. (S<RISC OS>)
-
-Note that the C<select FILEHANDLE> form is generally portable.
-
-=item semctl
-
-=item semget
-
-=item semop
-
-Not implemented. (Win32, VMS, S<RISC OS>)
-
-=item setgrent
-
-Not implemented. (MPE/iX, VMS, Win32, S<RISC OS>)
-
-=item setpgrp
-
-Not implemented. (Win32, VMS, S<RISC OS>, VOS)
-
-=item setpriority
-
-Not implemented. (Win32, VMS, S<RISC OS>, VOS)
-
-=item setpwent
-
-Not implemented. (MPE/iX, Win32, S<RISC OS>)
-
-=item setsockopt
-
-Not implemented. (S<Plan 9>)
-
-=item shmctl
-
-=item shmget
-
-=item shmread
-
-=item shmwrite
-
-Not implemented. (Win32, VMS, S<RISC OS>, VOS)
-
-=item sockatmark
-
-A relatively recent addition to socket functions, may not
-be implemented even in Unix platforms.
-
-=item socketpair
-
-Not implemented. (S<RISC OS>, VM/ESA)
-
-Available on OpenVOS Release 17.0 or later. (VOS)
-
-Available on 64 bit OpenVMS 8.2 and later. (VMS)
-
-=item stat
-
-Platforms that do not have rdev, blksize, or blocks will return these
-as '', so numeric comparison or manipulation of these fields may cause
-'not numeric' warnings.
-
-ctime not supported on UFS (S<Mac OS X>).
-
-ctime is creation time instead of inode change time (Win32).
-
-device and inode are not meaningful. (Win32)
-
-device and inode are not necessarily reliable. (VMS)
-
-mtime, atime and ctime all return the last modification time. Device and
-inode are not necessarily reliable. (S<RISC OS>)
-
-dev, rdev, blksize, and blocks are not available. inode is not
-meaningful and will differ between stat calls on the same file. (os2)
-
-some versions of cygwin when doing a stat("foo") and if not finding it
-may then attempt to stat("foo.exe") (Cygwin)
-
-On Win32 stat() needs to open the file to determine the link count
-and update attributes that may have been changed through hard links.
-Setting ${^WIN32_SLOPPY_STAT} to a true value speeds up stat() by
-not performing this operation. (Win32)
-
-=item symlink
-
-Not implemented. (Win32, S<RISC OS>)
-
-Implemented on 64 bit VMS 8.3. VMS requires the symbolic link to be in Unix
-syntax if it is intended to resolve to a valid path.
-
-=item syscall
-
-Not implemented. (Win32, VMS, S<RISC OS>, VOS, VM/ESA)
-
-=item sysopen
-
-The traditional "0", "1", and "2" MODEs are implemented with different
-numeric values on some systems. The flags exported by C<Fcntl>
-(O_RDONLY, O_WRONLY, O_RDWR) should work everywhere though. (S<Mac
-OS>, OS/390, VM/ESA)
-
-=item system
-
-As an optimization, may not call the command shell specified in
-C<$ENV{PERL5SHELL}>. C<system(1, @args)> spawns an external
-process and immediately returns its process designator, without
-waiting for it to terminate. Return value may be used subsequently
-in C<wait> or C<waitpid>. Failure to spawn() a subprocess is indicated
-by setting $? to "255 << 8". C<$?> is set in a way compatible with
-Unix (i.e. the exitstatus of the subprocess is obtained by "$? >> 8",
-as described in the documentation). (Win32)
-
-There is no shell to process metacharacters, and the native standard is
-to pass a command line terminated by "\n" "\r" or "\0" to the spawned
-program. Redirection such as C<< > foo >> is performed (if at all) by
-the run time library of the spawned program. C<system> I<list> will call
-the Unix emulation library's C<exec> emulation, which attempts to provide
-emulation of the stdin, stdout, stderr in force in the parent, providing
-the child program uses a compatible version of the emulation library.
-I<scalar> will call the native command line direct and no such emulation
-of a child Unix program will exists. Mileage B<will> vary. (S<RISC OS>)
-
-Does not automatically flush output handles on some platforms.
-(SunOS, Solaris, HP-UX)
-
-The return value is POSIX-like (shifted up by 8 bits), which only allows
-room for a made-up value derived from the severity bits of the native
-32-bit condition code (unless overridden by C<use vmsish 'status'>).
-If the native condition code is one that has a POSIX value encoded, the
-POSIX value will be decoded to extract the expected exit value.
-For more details see L<perlvms/$?>. (VMS)
-
-=item times
-
-"cumulative" times will be bogus. On anything other than Windows NT
-or Windows 2000, "system" time will be bogus, and "user" time is
-actually the time returned by the clock() function in the C runtime
-library. (Win32)
-
-Not useful. (S<RISC OS>)
-
-=item truncate
-
-Not implemented. (Older versions of VMS)
-
-Truncation to same-or-shorter lengths only. (VOS)
-
-If a FILEHANDLE is supplied, it must be writable and opened in append
-mode (i.e., use C<<< open(FH, '>>filename') >>>
-or C<sysopen(FH,...,O_APPEND|O_RDWR)>. If a filename is supplied, it
-should not be held open elsewhere. (Win32)
-
-=item umask
-
-Returns undef where unavailable, as of version 5.005.
-
-C<umask> works but the correct permissions are set only when the file
-is finally closed. (AmigaOS)
-
-=item utime
-
-Only the modification time is updated. (S<BeOS>, VMS, S<RISC OS>)
-
-May not behave as expected. Behavior depends on the C runtime
-library's implementation of utime(), and the filesystem being
-used. The FAT filesystem typically does not support an "access
-time" field, and it may limit timestamps to a granularity of
-two seconds. (Win32)
-
-=item wait
-
-=item waitpid
-
-Can only be applied to process handles returned for processes spawned
-using C<system(1, ...)> or pseudo processes created with C<fork()>. (Win32)
-
-Not useful. (S<RISC OS>)
-
-=back
-
-
-=head1 Supported Platforms
-
-The following platforms are known to build Perl 5.12 (as of April 2010,
-its release date) from the standard source code distribution available
-at L<http://www.cpan.org/src>
-
-=over
-
-=item Linux (x86, ARM, IA64)
-
-=item HP-UX
-
-=item AIX
-
-=item Win32
-
-=over
-
-=item Windows 2000
-
-=item Windows XP
-
-=item Windows Server 2003
-
-=item Windows Vista
-
-=item Windows Server 2008
-
-=item Windows 7
-
-=back
-
-=item Cygwin
-
-=item Solaris (x86, SPARC)
-
-=item OpenVMS
-
-=over
-
-=item Alpha (7.2 and later)
-
-=item I64 (8.2 and later)
-
-=back
-
-=item Symbian
-
-=item NetBSD
-
-=item FreeBSD
-
-=item Debian GNU/kFreeBSD
-
-=item Haiku
-
-=item Irix (6.5. What else?)
-
-=item OpenBSD
-
-=item Dragonfly BSD
-
-=item QNX Neutrino RTOS (6.5.0)
-
-=item MirOS BSD
-
-Caveats:
-
-=over
-
-=item time_t issues that may or may not be fixed
-
-=back
-
-=item Symbian (Series 60 v3, 3.2 and 5 - what else?)
-
-=item Stratus VOS / OpenVOS
-
-=item AIX
-
-=back
-
-=head1 EOL Platforms (Perl 5.14)
-
-The following platforms were supported by a previous version of
-Perl but have been officially removed from Perl's source code
-as of 5.12:
-
-=over
-
-=item Atari MiNT
-
-=item Apollo Domain/OS
-
-=item Apple Mac OS 8/9
-
-=item Tenon Machten
-
-=back
-
-The following platforms were supported up to 5.10. They may still
-have worked in 5.12, but supporting code has been removed for 5.14:
-
-=over
-
-=item Windows 95
-
-=item Windows 98
-
-=item Windows ME
-
-=item Windows NT4
-
-=back
-
-=head1 Supported Platforms (Perl 5.8)
-
-As of July 2002 (the Perl release 5.8.0), the following platforms were
-able to build Perl from the standard source code distribution
-available at L<http://www.cpan.org/src/>
-
- AIX
- BeOS
- BSD/OS (BSDi)
- Cygwin
- DG/UX
- DOS DJGPP 1)
- DYNIX/ptx
- EPOC R5
- FreeBSD
- HI-UXMPP (Hitachi) (5.8.0 worked but we didn't know it)
- HP-UX
- IRIX
- Linux
- Mac OS Classic
- Mac OS X (Darwin)
- MPE/iX
- NetBSD
- NetWare
- NonStop-UX
- ReliantUNIX (formerly SINIX)
- OpenBSD
- OpenVMS (formerly VMS)
- Open UNIX (Unixware) (since Perl 5.8.1/5.9.0)
- OS/2
- OS/400 (using the PASE) (since Perl 5.8.1/5.9.0)
- PowerUX
- POSIX-BC (formerly BS2000)
- QNX
- Solaris
- SunOS 4
- SUPER-UX (NEC)
- Tru64 UNIX (formerly DEC OSF/1, Digital UNIX)
- UNICOS
- UNICOS/mk
- UTS
- VOS
- Win95/98/ME/2K/XP 2)
- WinCE
- z/OS (formerly OS/390)
- VM/ESA
-
- 1) in DOS mode either the DOS or OS/2 ports can be used
- 2) compilers: Borland, MinGW (GCC), VC6
-
-The following platforms worked with the previous releases (5.6 and
-5.7), but we did not manage either to fix or to test these in time
-for the 5.8.0 release. There is a very good chance that many of these
-will work fine with the 5.8.0.
-
- BSD/OS
- DomainOS
- Hurd
- LynxOS
- MachTen
- PowerMAX
- SCO SV
- SVR4
- Unixware
- Windows 3.1
-
-Known to be broken for 5.8.0 (but 5.6.1 and 5.7.2 can be used):
-
- AmigaOS
-
-The following platforms have been known to build Perl from source in
-the past (5.005_03 and earlier), but we haven't been able to verify
-their status for the current release, either because the
-hardware/software platforms are rare or because we don't have an
-active champion on these platforms--or both. They used to work,
-though, so go ahead and try compiling them, and let perlbug@perl.org
-of any trouble.
-
- 3b1
- A/UX
- ConvexOS
- CX/UX
- DC/OSx
- DDE SMES
- DOS EMX
- Dynix
- EP/IX
- ESIX
- FPS
- GENIX
- Greenhills
- ISC
- MachTen 68k
- MPC
- NEWS-OS
- NextSTEP
- OpenSTEP
- Opus
- Plan 9
- RISC/os
- SCO ODT/OSR
- Stellar
- SVR2
- TI1500
- TitanOS
- Ultrix
- Unisys Dynix
-
-The following platforms have their own source code distributions and
-binaries available via L<http://www.cpan.org/ports/>
-
- Perl release
-
- OS/400 (ILE) 5.005_02
- Tandem Guardian 5.004
-
-The following platforms have only binaries available via
-L<http://www.cpan.org/ports/index.html> :
-
- Perl release
-
- Acorn RISCOS 5.005_02
- AOS 5.002
- LynxOS 5.004_02
-
-Although we do suggest that you always build your own Perl from
-the source code, both for maximal configurability and for security,
-in case you are in a hurry you can check
-L<http://www.cpan.org/ports/index.html> for binary distributions.
-
-=head1 SEE ALSO
-
-L<perlaix>, L<perlamiga>, L<perlbeos>, L<perlbs2000>,
-L<perlce>, L<perlcygwin>, L<perldgux>, L<perldos>, L<perlepoc>,
-L<perlebcdic>, L<perlfreebsd>, L<perlhurd>, L<perlhpux>, L<perlirix>,
-L<perlmacos>, L<perlmacosx>, L<perlmpeix>,
-L<perlnetware>, L<perlos2>, L<perlos390>, L<perlos400>,
-L<perlplan9>, L<perlqnx>, L<perlsolaris>, L<perltru64>,
-L<perlunicode>, L<perlvmesa>, L<perlvms>, L<perlvos>,
-L<perlwin32>, and L<Win32>.
-
-=head1 AUTHORS / CONTRIBUTORS
-
-Abigail <abigail@foad.org>,
-Charles Bailey <bailey@newman.upenn.edu>,
-Graham Barr <gbarr@pobox.com>,
-Tom Christiansen <tchrist@perl.com>,
-Nicholas Clark <nick@ccl4.org>,
-Thomas Dorner <Thomas.Dorner@start.de>,
-Andy Dougherty <doughera@lafayette.edu>,
-Dominic Dunlop <domo@computer.org>,
-Neale Ferguson <neale@vma.tabnsw.com.au>,
-David J. Fiander <davidf@mks.com>,
-Paul Green <Paul.Green@stratus.com>,
-M.J.T. Guy <mjtg@cam.ac.uk>,
-Jarkko Hietaniemi <jhi@iki.fi>,
-Luther Huffman <lutherh@stratcom.com>,
-Nick Ing-Simmons <nick@ing-simmons.net>,
-Andreas J. KE<ouml>nig <a.koenig@mind.de>,
-Markus Laker <mlaker@contax.co.uk>,
-Andrew M. Langmead <aml@world.std.com>,
-Larry Moore <ljmoore@freespace.net>,
-Paul Moore <Paul.Moore@uk.origin-it.com>,
-Chris Nandor <pudge@pobox.com>,
-Matthias Neeracher <neeracher@mac.com>,
-Philip Newton <pne@cpan.org>,
-Gary Ng <71564.1743@CompuServe.COM>,
-Tom Phoenix <rootbeer@teleport.com>,
-AndrE<eacute> Pirard <A.Pirard@ulg.ac.be>,
-Peter Prymmer <pvhp@forte.com>,
-Hugo van der Sanden <hv@crypt0.demon.co.uk>,
-Gurusamy Sarathy <gsar@activestate.com>,
-Paul J. Schinder <schinder@pobox.com>,
-Michael G Schwern <schwern@pobox.com>,
-Dan Sugalski <dan@sidhe.org>,
-Nathan Torkington <gnat@frii.com>,
-John Malmberg <wb8tyw@qsl.net>
diff --git a/Master/tlpkg/tlperl/lib/pods/perlpragma.pod b/Master/tlpkg/tlperl/lib/pods/perlpragma.pod
deleted file mode 100644
index 604387d9f97..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlpragma.pod
+++ /dev/null
@@ -1,163 +0,0 @@
-=head1 NAME
-
-perlpragma - how to write a user pragma
-
-=head1 DESCRIPTION
-
-A pragma is a module which influences some aspect of the compile time or run
-time behaviour of Perl, such as C<strict> or C<warnings>. With Perl 5.10 you
-are no longer limited to the built in pragmata; you can now create user
-pragmata that modify the behaviour of user functions within a lexical scope.
-
-=head1 A basic example
-
-For example, say you need to create a class implementing overloaded
-mathematical operators, and would like to provide your own pragma that
-functions much like C<use integer;> You'd like this code
-
- use MyMaths;
-
- my $l = MyMaths->new(1.2);
- my $r = MyMaths->new(3.4);
-
- print "A: ", $l + $r, "\n";
-
- use myint;
- print "B: ", $l + $r, "\n";
-
- {
- no myint;
- print "C: ", $l + $r, "\n";
- }
-
- print "D: ", $l + $r, "\n";
-
- no myint;
- print "E: ", $l + $r, "\n";
-
-to give the output
-
- A: 4.6
- B: 4
- C: 4.6
- D: 4
- E: 4.6
-
-I<i.e.>, where C<use myint;> is in effect, addition operations are forced
-to integer, whereas by default they are not, with the default behaviour being
-restored via C<no myint;>
-
-The minimal implementation of the package C<MyMaths> would be something like
-this:
-
- package MyMaths;
- use warnings;
- use strict;
- use myint();
- use overload '+' => sub {
- my ($l, $r) = @_;
- # Pass 1 to check up one call level from here
- if (myint::in_effect(1)) {
- int($$l) + int($$r);
- } else {
- $$l + $$r;
- }
- };
-
- sub new {
- my ($class, $value) = @_;
- bless \$value, $class;
- }
-
- 1;
-
-Note how we load the user pragma C<myint> with an empty list C<()> to
-prevent its C<import> being called.
-
-The interaction with the Perl compilation happens inside package C<myint>:
-
- package myint;
-
- use strict;
- use warnings;
-
- sub import {
- $^H{"myint/in_effect"} = 1;
- }
-
- sub unimport {
- $^H{"myint/in_effect"} = 0;
- }
-
- sub in_effect {
- my $level = shift // 0;
- my $hinthash = (caller($level))[10];
- return $hinthash->{"myint/in_effect"};
- }
-
- 1;
-
-As pragmata are implemented as modules, like any other module, C<use myint;>
-becomes
-
- BEGIN {
- require myint;
- myint->import();
- }
-
-and C<no myint;> is
-
- BEGIN {
- require myint;
- myint->unimport();
- }
-
-Hence the C<import> and C<unimport> routines are called at B<compile time>
-for the user's code.
-
-User pragmata store their state by writing to the magical hash C<%^H>,
-hence these two routines manipulate it. The state information in C<%^H> is
-stored in the optree, and can be retrieved read-only at runtime with C<caller()>,
-at index 10 of the list of returned results. In the example pragma, retrieval
-is encapsulated into the routine C<in_effect()>, which takes as parameter
-the number of call frames to go up to find the value of the pragma in the
-user's script. This uses C<caller()> to determine the value of
-C<$^H{"myint/in_effect"}> when each line of the user's script was called, and
-therefore provide the correct semantics in the subroutine implementing the
-overloaded addition.
-
-=head1 Key naming
-
-There is only a single C<%^H>, but arbitrarily many modules that want
-to use its scoping semantics. To avoid stepping on each other's toes,
-they need to be sure to use different keys in the hash. It is therefore
-conventional for a module to use only keys that begin with the module's
-name (the name of its main package) and a "/" character. After this
-module-identifying prefix, the rest of the key is entirely up to the
-module: it may include any characters whatsoever. For example, a module
-C<Foo::Bar> should use keys such as C<Foo::Bar/baz> and C<Foo::Bar/$%/_!>.
-Modules following this convention all play nicely with each other.
-
-The Perl core uses a handful of keys in C<%^H> which do not follow this
-convention, because they predate it. Keys that follow the convention
-won't conflict with the core's historical keys.
-
-=head1 Implementation details
-
-The optree is shared between threads. This means there is a possibility that
-the optree will outlive the particular thread (and therefore the interpreter
-instance) that created it, so true Perl scalars cannot be stored in the
-optree. Instead a compact form is used, which can only store values that are
-integers (signed and unsigned), strings or C<undef> - references and
-floating point values are stringified. If you need to store multiple values
-or complex structures, you should serialise them, for example with C<pack>.
-The deletion of a hash key from C<%^H> is recorded, and as ever can be
-distinguished from the existence of a key with value C<undef> with
-C<exists>.
-
-B<Don't> attempt to store references to data structures as integers which
-are retrieved via C<caller> and converted back, as this will not be threadsafe.
-Accesses would be to the structure without locking (which is not safe for
-Perl's scalars), and either the structure has to leak, or it has to be
-freed when its creating thread terminates, which may be before the optree
-referencing it is deleted, if other threads outlive it.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlqnx.pod b/Master/tlpkg/tlperl/lib/pods/perlqnx.pod
deleted file mode 100644
index a1c2e92226d..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlqnx.pod
+++ /dev/null
@@ -1,143 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you see.
-It is written in the POD format (see pod/perlpod.pod) which is specially
-designed to be readable as is.
-
-=head1 NAME
-
-perlqnx - Perl version 5 on QNX
-
-=head1 DESCRIPTION
-
-As of perl5.7.2 all tests pass under:
-
- QNX 4.24G
- Watcom 10.6 with Beta/970211.wcc.update.tar.F
- socket3r.lib Nov21 1996.
-
-As of perl5.8.1 there is at least one test still failing.
-
-Some tests may complain under known circumstances.
-
-See below and hints/qnx.sh for more information.
-
-Under QNX 6.2.0 there are still a few tests which fail.
-See below and hints/qnx.sh for more information.
-
-=head2 Required Software for Compiling Perl on QNX4
-
-As with many unix ports, this one depends on a few "standard"
-unix utilities which are not necessarily standard for QNX4.
-
-=over 4
-
-=item /bin/sh
-
-This is used heavily by Configure and then by
-perl itself. QNX4's version is fine, but Configure
-will choke on the 16-bit version, so if you are
-running QNX 4.22, link /bin/sh to /bin32/ksh
-
-=item ar
-
-This is the standard unix library builder.
-We use wlib. With Watcom 10.6, when wlib is
-linked as "ar", it behaves like ar and all is
-fine. Under 9.5, a cover is required. One is
-included in ../qnx
-
-=item nm
-
-This is used (optionally) by configure to list
-the contents of libraries. I will generate
-a cover function on the fly in the UU directory.
-
-=item cpp
-
-Configure and perl need a way to invoke a C
-preprocessor. I have created a simple cover
-for cc which does the right thing. Without this,
-Configure will create its own wrapper which works,
-but it doesn't handle some of the command line arguments
-that perl will throw at it.
-
-=item make
-
-You really need GNU make to compile this. GNU make
-ships by default with QNX 4.23, but you can get it
-from quics for earlier versions.
-
-=back
-
-=head2 Outstanding Issues with Perl on QNX4
-
-There is no support for dynamically linked libraries in QNX4.
-
-If you wish to compile with the Socket extension, you need
-to have the TCP/IP toolkit, and you need to make sure that
--lsocket locates the correct copy of socket3r.lib. Beware
-that the Watcom compiler ships with a stub version of
-socket3r.lib which has very little functionality. Also
-beware the order in which wlink searches directories for
-libraries. You may have /usr/lib/socket3r.lib pointing to
-the correct library, but wlink may pick up
-/usr/watcom/10.6/usr/lib/socket3r.lib instead. Make sure
-they both point to the correct library, that is,
-/usr/tcptk/current/usr/lib/socket3r.lib.
-
-The following tests may report errors under QNX4:
-
-dist/Cwd/Cwd.t will complain if `pwd` and cwd don't give
-the same results. cwd calls `fullpath -t`, so if you
-cd `fullpath -t` before running the test, it will
-pass.
-
-lib/File/Find/taint.t will complain if '.' is in your
-PATH. The PATH test is triggered because cwd calls
-`fullpath -t`.
-
-ext/IO/lib/IO/t/io_sock.t: Subtests 14 and 22 are skipped due to
-the fact that the functionality to read back the non-blocking
-status of a socket is not implemented in QNX's TCP/IP. This has
-been reported to QNX and it may work with later versions of
-TCP/IP.
-
-t/io/tell.t: Subtest 27 is failing. We are still investigating.
-
-=head2 QNX auxiliary files
-
-The files in the "qnx" directory are:
-
-=over 4
-
-=item qnx/ar
-
-A script that emulates the standard unix archive (aka library)
-utility. Under Watcom 10.6, ar is linked to wlib and provides the
-expected interface. With Watcom 9.5, a cover function is
-required. This one is fairly crude but has proved adequate for
-compiling perl.
-
-=item qnx/cpp
-
-A script that provides C preprocessing functionality. Configure can
-generate a similar cover, but it doesn't handle all the command-line
-options that perl throws at it. This might be reasonably placed in
-/usr/local/bin.
-
-=back
-
-=head2 Outstanding issues with perl under QNX6
-
-The following tests are still failing for Perl 5.8.1 under QNX 6.2.0:
-
- op/sprintf.........................FAILED at test 91
- lib/Benchmark......................FAILED at test 26
-
-This is due to a bug in the C library's printf routine.
-printf("'%e'", 0. ) produces '0.000000e+0', but ANSI requires
-'0.000000e+00'. QNX has acknowledged the bug.
-
-=head1 AUTHOR
-
-Norton T. Allen (allen@huarp.harvard.edu)
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlre.pod b/Master/tlpkg/tlperl/lib/pods/perlre.pod
deleted file mode 100644
index b69c359006d..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlre.pod
+++ /dev/null
@@ -1,2585 +0,0 @@
-=head1 NAME
-X<regular expression> X<regex> X<regexp>
-
-perlre - Perl regular expressions
-
-=head1 DESCRIPTION
-
-This page describes the syntax of regular expressions in Perl.
-
-If you haven't used regular expressions before, a quick-start
-introduction is available in L<perlrequick>, and a longer tutorial
-introduction is available in L<perlretut>.
-
-For reference on how regular expressions are used in matching
-operations, plus various examples of the same, see discussions of
-C<m//>, C<s///>, C<qr//> and C<??> in L<perlop/"Regexp Quote-Like
-Operators">.
-
-
-=head2 Modifiers
-
-Matching operations can have various modifiers. Modifiers
-that relate to the interpretation of the regular expression inside
-are listed below. Modifiers that alter the way a regular expression
-is used by Perl are detailed in L<perlop/"Regexp Quote-Like Operators"> and
-L<perlop/"Gory details of parsing quoted constructs">.
-
-=over 4
-
-=item m
-X</m> X<regex, multiline> X<regexp, multiline> X<regular expression, multiline>
-
-Treat string as multiple lines. That is, change "^" and "$" from matching
-the start or end of the string to matching the start or end of any
-line anywhere within the string.
-
-=item s
-X</s> X<regex, single-line> X<regexp, single-line>
-X<regular expression, single-line>
-
-Treat string as single line. That is, change "." to match any character
-whatsoever, even a newline, which normally it would not match.
-
-Used together, as C</ms>, they let the "." match any character whatsoever,
-while still allowing "^" and "$" to match, respectively, just after
-and just before newlines within the string.
-
-=item i
-X</i> X<regex, case-insensitive> X<regexp, case-insensitive>
-X<regular expression, case-insensitive>
-
-Do case-insensitive pattern matching.
-
-If locale matching rules are in effect, the case map is taken from the
-current
-locale for code points less than 255, and from Unicode rules for larger
-code points. However, matches that would cross the Unicode
-rules/non-Unicode rules boundary (ords 255/256) will not succeed. See
-L<perllocale>.
-
-There are a number of Unicode characters that match multiple characters
-under C</i>. For example, C<LATIN SMALL LIGATURE FI>
-should match the sequence C<fi>. Perl is not
-currently able to do this when the multiple characters are in the pattern and
-are split between groupings, or when one or more are quantified. Thus
-
- "\N{LATIN SMALL LIGATURE FI}" =~ /fi/i; # Matches
- "\N{LATIN SMALL LIGATURE FI}" =~ /[fi][fi]/i; # Doesn't match!
- "\N{LATIN SMALL LIGATURE FI}" =~ /fi*/i; # Doesn't match!
-
- # The below doesn't match, and it isn't clear what $1 and $2 would
- # be even if it did!!
- "\N{LATIN SMALL LIGATURE FI}" =~ /(f)(i)/i; # Doesn't match!
-
-Perl doesn't match multiple characters in an inverted bracketed
-character class, which otherwise could be highly confusing. See
-L<perlrecharclass/Negation>.
-
-Another bug involves character classes that match both a sequence of
-multiple characters, and an initial sub-string of that sequence. For
-example,
-
- /[s\xDF]/i
-
-should match both a single and a double "s", since C<\xDF> (on ASCII
-platforms) matches "ss". However, this bug
-(L<[perl #89774]|https://rt.perl.org/rt3/Ticket/Display.html?id=89774>)
-causes it to only match a single "s", even if the final larger match
-fails, and matching the double "ss" would have succeeded.
-
-Also, Perl matching doesn't fully conform to the current Unicode C</i>
-recommendations, which ask that the matching be made upon the NFD
-(Normalization Form Decomposed) of the text. However, Unicode is
-in the process of reconsidering and revising their recommendations.
-
-=item x
-X</x>
-
-Extend your pattern's legibility by permitting whitespace and comments.
-Details in L</"/x">
-
-=item p
-X</p> X<regex, preserve> X<regexp, preserve>
-
-Preserve the string matched such that ${^PREMATCH}, ${^MATCH}, and
-${^POSTMATCH} are available for use after matching.
-
-=item g and c
-X</g> X</c>
-
-Global matching, and keep the Current position after failed matching.
-Unlike i, m, s and x, these two flags affect the way the regex is used
-rather than the regex itself. See
-L<perlretut/"Using regular expressions in Perl"> for further explanation
-of the g and c modifiers.
-
-=item a, d, l and u
-X</a> X</d> X</l> X</u>
-
-These modifiers, all new in 5.14, affect which character-set semantics
-(Unicode, etc.) are used, as described below in
-L</Character set modifiers>.
-
-=back
-
-Regular expression modifiers are usually written in documentation
-as e.g., "the C</x> modifier", even though the delimiter
-in question might not really be a slash. The modifiers C</imsxadlup>
-may also be embedded within the regular expression itself using
-the C<(?...)> construct, see L</Extended Patterns> below.
-
-=head3 /x
-
-C</x> tells
-the regular expression parser to ignore most whitespace that is neither
-backslashed nor within a character class. You can use this to break up
-your regular expression into (slightly) more readable parts. The C<#>
-character is also treated as a metacharacter introducing a comment,
-just as in ordinary Perl code. This also means that if you want real
-whitespace or C<#> characters in the pattern (outside a character
-class, where they are unaffected by C</x>), then you'll either have to
-escape them (using backslashes or C<\Q...\E>) or encode them using octal,
-hex, or C<\N{}> escapes. Taken together, these features go a long way towards
-making Perl's regular expressions more readable. Note that you have to
-be careful not to include the pattern delimiter in the comment--perl has
-no way of knowing you did not intend to close the pattern early. See
-the C-comment deletion code in L<perlop>. Also note that anything inside
-a C<\Q...\E> stays unaffected by C</x>. And note that C</x> doesn't affect
-space interpretation within a single multi-character construct. For
-example in C<\x{...}>, regardless of the C</x> modifier, there can be no
-spaces. Same for a L<quantifier|/Quantifiers> such as C<{3}> or
-C<{5,}>. Similarly, C<(?:...)> can't have a space between the C<?> and C<:>,
-but can between the C<(> and C<?>. Within any delimiters for such a
-construct, allowed spaces are not affected by C</x>, and depend on the
-construct. For example, C<\x{...}> can't have spaces because hexadecimal
-numbers don't have spaces in them. But, Unicode properties can have spaces, so
-in C<\p{...}> there can be spaces that follow the Unicode rules, for which see
-L<perluniprops/Properties accessible through \p{} and \P{}>.
-X</x>
-
-=head3 Character set modifiers
-
-C</d>, C</u>, C</a>, and C</l>, available starting in 5.14, are called
-the character set modifiers; they affect the character set semantics
-used for the regular expression.
-
-The C</d>, C</u>, and C</l> modifiers are not likely to be of much use
-to you, and so you need not worry about them very much. They exist for
-Perl's internal use, so that complex regular expression data structures
-can be automatically serialized and later exactly reconstituted,
-including all their nuances. But, since Perl can't keep a secret, and
-there may be rare instances where they are useful, they are documented
-here.
-
-The C</a> modifier, on the other hand, may be useful. Its purpose is to
-allow code that is to work mostly on ASCII data to not have to concern
-itself with Unicode.
-
-Briefly, C</l> sets the character set to that of whatever B<L>ocale is in
-effect at the time of the execution of the pattern match.
-
-C</u> sets the character set to B<U>nicode.
-
-C</a> also sets the character set to Unicode, BUT adds several
-restrictions for B<A>SCII-safe matching.
-
-C</d> is the old, problematic, pre-5.14 B<D>efault character set
-behavior. Its only use is to force that old behavior.
-
-At any given time, exactly one of these modifiers is in effect. Their
-existence allows Perl to keep the originally compiled behavior of a
-regular expression, regardless of what rules are in effect when it is
-actually executed. And if it is interpolated into a larger regex, the
-original's rules continue to apply to it, and only it.
-
-The C</l> and C</u> modifiers are automatically selected for
-regular expressions compiled within the scope of various pragmas,
-and we recommend that in general, you use those pragmas instead of
-specifying these modifiers explicitly. For one thing, the modifiers
-affect only pattern matching, and do not extend to even any replacement
-done, whereas using the pragmas give consistent results for all
-appropriate operations within their scopes. For example,
-
- s/foo/\Ubar/il
-
-will match "foo" using the locale's rules for case-insensitive matching,
-but the C</l> does not affect how the C<\U> operates. Most likely you
-want both of them to use locale rules. To do this, instead compile the
-regular expression within the scope of C<use locale>. This both
-implicitly adds the C</l> and applies locale rules to the C<\U>. The
-lesson is to C<use locale> and not C</l> explicitly.
-
-Similarly, it would be better to use C<use feature 'unicode_strings'>
-instead of,
-
- s/foo/\Lbar/iu
-
-to get Unicode rules, as the C<\L> in the former (but not necessarily
-the latter) would also use Unicode rules.
-
-More detail on each of the modifiers follows. Most likely you don't
-need to know this detail for C</l>, C</u>, and C</d>, and can skip ahead
-to L<E<sol>a|/E<sol>a (and E<sol>aa)>.
-
-=head4 /l
-
-means to use the current locale's rules (see L<perllocale>) when pattern
-matching. For example, C<\w> will match the "word" characters of that
-locale, and C<"/i"> case-insensitive matching will match according to
-the locale's case folding rules. The locale used will be the one in
-effect at the time of execution of the pattern match. This may not be
-the same as the compilation-time locale, and can differ from one match
-to another if there is an intervening call of the
-L<setlocale() function|perllocale/The setlocale function>.
-
-Perl only supports single-byte locales. This means that code points
-above 255 are treated as Unicode no matter what locale is in effect.
-Under Unicode rules, there are a few case-insensitive matches that cross
-the 255/256 boundary. These are disallowed under C</l>. For example,
-0xFF (on ASCII platforms) does not caselessly match the character at
-0x178, C<LATIN CAPITAL LETTER Y WITH DIAERESIS>, because 0xFF may not be
-C<LATIN SMALL LETTER Y WITH DIAERESIS> in the current locale, and Perl
-has no way of knowing if that character even exists in the locale, much
-less what code point it is.
-
-This modifier may be specified to be the default by C<use locale>, but
-see L</Which character set modifier is in effect?>.
-X</l>
-
-=head4 /u
-
-means to use Unicode rules when pattern matching. On ASCII platforms,
-this means that the code points between 128 and 255 take on their
-Latin-1 (ISO-8859-1) meanings (which are the same as Unicode's).
-(Otherwise Perl considers their meanings to be undefined.) Thus,
-under this modifier, the ASCII platform effectively becomes a Unicode
-platform; and hence, for example, C<\w> will match any of the more than
-100_000 word characters in Unicode.
-
-Unlike most locales, which are specific to a language and country pair,
-Unicode classifies all the characters that are letters I<somewhere> in
-the world as
-C<\w>. For example, your locale might not think that C<LATIN SMALL
-LETTER ETH> is a letter (unless you happen to speak Icelandic), but
-Unicode does. Similarly, all the characters that are decimal digits
-somewhere in the world will match C<\d>; this is hundreds, not 10,
-possible matches. And some of those digits look like some of the 10
-ASCII digits, but mean a different number, so a human could easily think
-a number is a different quantity than it really is. For example,
-C<BENGALI DIGIT FOUR> (U+09EA) looks very much like an
-C<ASCII DIGIT EIGHT> (U+0038). And, C<\d+>, may match strings of digits
-that are a mixture from different writing systems, creating a security
-issue. L<Unicode::UCD/num()> can be used to sort
-this out. Or the C</a> modifier can be used to force C<\d> to match
-just the ASCII 0 through 9.
-
-Also, under this modifier, case-insensitive matching works on the full
-set of Unicode
-characters. The C<KELVIN SIGN>, for example matches the letters "k" and
-"K"; and C<LATIN SMALL LIGATURE FF> matches the sequence "ff", which,
-if you're not prepared, might make it look like a hexadecimal constant,
-presenting another potential security issue. See
-L<http://unicode.org/reports/tr36> for a detailed discussion of Unicode
-security issues.
-
-On the EBCDIC platforms that Perl handles, the native character set is
-equivalent to Latin-1. Thus this modifier changes behavior only when
-the C<"/i"> modifier is also specified, and it turns out it affects only
-two characters, giving them full Unicode semantics: the C<MICRO SIGN>
-will match the Greek capital and small letters C<MU>, otherwise not; and
-the C<LATIN CAPITAL LETTER SHARP S> will match any of C<SS>, C<Ss>,
-C<sS>, and C<ss>, otherwise not.
-
-This modifier may be specified to be the default by C<use feature
-'unicode_strings>, C<use locale ':not_characters'>, or
-C<L<use 5.012|perlfunc/use VERSION>> (or higher),
-but see L</Which character set modifier is in effect?>.
-X</u>
-
-=head4 /d
-
-This modifier means to use the "Default" native rules of the platform
-except when there is cause to use Unicode rules instead, as follows:
-
-=over 4
-
-=item 1
-
-the target string is encoded in UTF-8; or
-
-=item 2
-
-the pattern is encoded in UTF-8; or
-
-=item 3
-
-the pattern explicitly mentions a code point that is above 255 (say by
-C<\x{100}>); or
-
-=item 4
-
-the pattern uses a Unicode name (C<\N{...}>); or
-
-=item 5
-
-the pattern uses a Unicode property (C<\p{...}>)
-
-=back
-
-Another mnemonic for this modifier is "Depends", as the rules actually
-used depend on various things, and as a result you can get unexpected
-results. See L<perlunicode/The "Unicode Bug">. The Unicode Bug has
-become rather infamous, leading to yet another (printable) name for this
-modifier, "Dodgy".
-
-On ASCII platforms, the native rules are ASCII, and on EBCDIC platforms
-(at least the ones that Perl handles), they are Latin-1.
-
-Here are some examples of how that works on an ASCII platform:
-
- $str = "\xDF"; # $str is not in UTF-8 format.
- $str =~ /^\w/; # No match, as $str isn't in UTF-8 format.
- $str .= "\x{0e0b}"; # Now $str is in UTF-8 format.
- $str =~ /^\w/; # Match! $str is now in UTF-8 format.
- chop $str;
- $str =~ /^\w/; # Still a match! $str remains in UTF-8 format.
-
-This modifier is automatically selected by default when none of the
-others are, so yet another name for it is "Default".
-
-Because of the unexpected behaviors associated with this modifier, you
-probably should only use it to maintain weird backward compatibilities.
-
-=head4 /a (and /aa)
-
-This modifier stands for ASCII-restrict (or ASCII-safe). This modifier,
-unlike the others, may be doubled-up to increase its effect.
-
-When it appears singly, it causes the sequences C<\d>, C<\s>, C<\w>, and
-the Posix character classes to match only in the ASCII range. They thus
-revert to their pre-5.6, pre-Unicode meanings. Under C</a>, C<\d>
-always means precisely the digits C<"0"> to C<"9">; C<\s> means the five
-characters C<[ \f\n\r\t]>; C<\w> means the 63 characters
-C<[A-Za-z0-9_]>; and likewise, all the Posix classes such as
-C<[[:print:]]> match only the appropriate ASCII-range characters.
-
-This modifier is useful for people who only incidentally use Unicode,
-and who do not wish to be burdened with its complexities and security
-concerns.
-
-With C</a>, one can write C<\d> with confidence that it will only match
-ASCII characters, and should the need arise to match beyond ASCII, you
-can instead use C<\p{Digit}> (or C<\p{Word}> for C<\w>). There are
-similar C<\p{...}> constructs that can match beyond ASCII both white
-space (see L<perlrecharclass/Whitespace>), and Posix classes (see
-L<perlrecharclass/POSIX Character Classes>). Thus, this modifier
-doesn't mean you can't use Unicode, it means that to get Unicode
-matching you must explicitly use a construct (C<\p{}>, C<\P{}>) that
-signals Unicode.
-
-As you would expect, this modifier causes, for example, C<\D> to mean
-the same thing as C<[^0-9]>; in fact, all non-ASCII characters match
-C<\D>, C<\S>, and C<\W>. C<\b> still means to match at the boundary
-between C<\w> and C<\W>, using the C</a> definitions of them (similarly
-for C<\B>).
-
-Otherwise, C</a> behaves like the C</u> modifier, in that
-case-insensitive matching uses Unicode semantics; for example, "k" will
-match the Unicode C<\N{KELVIN SIGN}> under C</i> matching, and code
-points in the Latin1 range, above ASCII will have Unicode rules when it
-comes to case-insensitive matching.
-
-To forbid ASCII/non-ASCII matches (like "k" with C<\N{KELVIN SIGN}>),
-specify the "a" twice, for example C</aai> or C</aia>. (The first
-occurrence of "a" restricts the C<\d>, etc., and the second occurrence
-adds the C</i> restrictions.) But, note that code points outside the
-ASCII range will use Unicode rules for C</i> matching, so the modifier
-doesn't really restrict things to just ASCII; it just forbids the
-intermixing of ASCII and non-ASCII.
-
-To summarize, this modifier provides protection for applications that
-don't wish to be exposed to all of Unicode. Specifying it twice
-gives added protection.
-
-This modifier may be specified to be the default by C<use re '/a'>
-or C<use re '/aa'>. If you do so, you may actually have occasion to use
-the C</u> modifier explictly if there are a few regular expressions
-where you do want full Unicode rules (but even here, it's best if
-everything were under feature C<"unicode_strings">, along with the
-C<use re '/aa'>). Also see L</Which character set modifier is in
-effect?>.
-X</a>
-X</aa>
-
-=head4 Which character set modifier is in effect?
-
-Which of these modifiers is in effect at any given point in a regular
-expression depends on a fairly complex set of interactions. These have
-been designed so that in general you don't have to worry about it, but
-this section gives the gory details. As
-explained below in L</Extended Patterns> it is possible to explicitly
-specify modifiers that apply only to portions of a regular expression.
-The innermost always has priority over any outer ones, and one applying
-to the whole expression has priority over any of the default settings that are
-described in the remainder of this section.
-
-The C<L<use re 'E<sol>foo'|re/"'/flags' mode">> pragma can be used to set
-default modifiers (including these) for regular expressions compiled
-within its scope. This pragma has precedence over the other pragmas
-listed below that also change the defaults.
-
-Otherwise, C<L<use locale|perllocale>> sets the default modifier to C</l>;
-and C<L<use feature 'unicode_strings|feature>>, or
-C<L<use 5.012|perlfunc/use VERSION>> (or higher) set the default to
-C</u> when not in the same scope as either C<L<use locale|perllocale>>
-or C<L<use bytes|bytes>>.
-(C<L<use locale ':not_characters'|perllocale/Unicode and UTF-8>> also
-sets the default to C</u>, overriding any plain C<use locale>.)
-Unlike the mechanisms mentioned above, these
-affect operations besides regular expressions pattern matching, and so
-give more consistent results with other operators, including using
-C<\U>, C<\l>, etc. in substitution replacements.
-
-If none of the above apply, for backwards compatibility reasons, the
-C</d> modifier is the one in effect by default. As this can lead to
-unexpected results, it is best to specify which other rule set should be
-used.
-
-=head4 Character set modifier behavior prior to Perl 5.14
-
-Prior to 5.14, there were no explicit modifiers, but C</l> was implied
-for regexes compiled within the scope of C<use locale>, and C</d> was
-implied otherwise. However, interpolating a regex into a larger regex
-would ignore the original compilation in favor of whatever was in effect
-at the time of the second compilation. There were a number of
-inconsistencies (bugs) with the C</d> modifier, where Unicode rules
-would be used when inappropriate, and vice versa. C<\p{}> did not imply
-Unicode rules, and neither did all occurrences of C<\N{}>, until 5.12.
-
-=head2 Regular Expressions
-
-=head3 Metacharacters
-
-The patterns used in Perl pattern matching evolved from those supplied in
-the Version 8 regex routines. (The routines are derived
-(distantly) from Henry Spencer's freely redistributable reimplementation
-of the V8 routines.) See L<Version 8 Regular Expressions> for
-details.
-
-In particular the following metacharacters have their standard I<egrep>-ish
-meanings:
-X<metacharacter>
-X<\> X<^> X<.> X<$> X<|> X<(> X<()> X<[> X<[]>
-
-
- \ Quote the next metacharacter
- ^ Match the beginning of the line
- . Match any character (except newline)
- $ Match the end of the line (or before newline at the end)
- | Alternation
- () Grouping
- [] Bracketed Character class
-
-By default, the "^" character is guaranteed to match only the
-beginning of the string, the "$" character only the end (or before the
-newline at the end), and Perl does certain optimizations with the
-assumption that the string contains only one line. Embedded newlines
-will not be matched by "^" or "$". You may, however, wish to treat a
-string as a multi-line buffer, such that the "^" will match after any
-newline within the string (except if the newline is the last character in
-the string), and "$" will match before any newline. At the
-cost of a little more overhead, you can do this by using the /m modifier
-on the pattern match operator. (Older programs did this by setting C<$*>,
-but this option was removed in perl 5.9.)
-X<^> X<$> X</m>
-
-To simplify multi-line substitutions, the "." character never matches a
-newline unless you use the C</s> modifier, which in effect tells Perl to pretend
-the string is a single line--even if it isn't.
-X<.> X</s>
-
-=head3 Quantifiers
-
-The following standard quantifiers are recognized:
-X<metacharacter> X<quantifier> X<*> X<+> X<?> X<{n}> X<{n,}> X<{n,m}>
-
- * Match 0 or more times
- + Match 1 or more times
- ? Match 1 or 0 times
- {n} Match exactly n times
- {n,} Match at least n times
- {n,m} Match at least n but not more than m times
-
-(If a curly bracket occurs in any other context and does not form part of
-a backslashed sequence like C<\x{...}>, it is treated
-as a regular character. In particular, the lower quantifier bound
-is not optional. However, in Perl v5.18, it is planned to issue a
-deprecation warning for all such occurrences, and in Perl v5.20 to
-require literal uses of a curly bracket to be escaped, say by preceding
-them with a backslash or enclosing them within square brackets, (C<"\{">
-or C<"[{]">). This change will allow for future syntax extensions (like
-making the lower bound of a quantifier optional), and better error
-checking of quantifiers. Now, a typo in a quantifier silently causes
-it to be treated as the literal characters. For example,
-
- /o{4,3}/
-
-looks like a quantifier that matches 0 times, since 4 is greater than 3,
-but it really means to match the sequence of six characters
-S<C<"o { 4 , 3 }">>.)
-
-The "*" quantifier is equivalent to C<{0,}>, the "+"
-quantifier to C<{1,}>, and the "?" quantifier to C<{0,1}>. n and m are limited
-to non-negative integral values less than a preset limit defined when perl is built.
-This is usually 32766 on the most common platforms. The actual limit can
-be seen in the error message generated by code such as this:
-
- $_ **= $_ , / {$_} / for 2 .. 42;
-
-By default, a quantified subpattern is "greedy", that is, it will match as
-many times as possible (given a particular starting location) while still
-allowing the rest of the pattern to match. If you want it to match the
-minimum number of times possible, follow the quantifier with a "?". Note
-that the meanings don't change, just the "greediness":
-X<metacharacter> X<greedy> X<greediness>
-X<?> X<*?> X<+?> X<??> X<{n}?> X<{n,}?> X<{n,m}?>
-
- *? Match 0 or more times, not greedily
- +? Match 1 or more times, not greedily
- ?? Match 0 or 1 time, not greedily
- {n}? Match exactly n times, not greedily (redundant)
- {n,}? Match at least n times, not greedily
- {n,m}? Match at least n but not more than m times, not greedily
-
-By default, when a quantified subpattern does not allow the rest of the
-overall pattern to match, Perl will backtrack. However, this behaviour is
-sometimes undesirable. Thus Perl provides the "possessive" quantifier form
-as well.
-
- *+ Match 0 or more times and give nothing back
- ++ Match 1 or more times and give nothing back
- ?+ Match 0 or 1 time and give nothing back
- {n}+ Match exactly n times and give nothing back (redundant)
- {n,}+ Match at least n times and give nothing back
- {n,m}+ Match at least n but not more than m times and give nothing back
-
-For instance,
-
- 'aaaa' =~ /a++a/
-
-will never match, as the C<a++> will gobble up all the C<a>'s in the
-string and won't leave any for the remaining part of the pattern. This
-feature can be extremely useful to give perl hints about where it
-shouldn't backtrack. For instance, the typical "match a double-quoted
-string" problem can be most efficiently performed when written as:
-
- /"(?:[^"\\]++|\\.)*+"/
-
-as we know that if the final quote does not match, backtracking will not
-help. See the independent subexpression
-L</C<< (?>pattern) >>> for more details;
-possessive quantifiers are just syntactic sugar for that construct. For
-instance the above example could also be written as follows:
-
- /"(?>(?:(?>[^"\\]+)|\\.)*)"/
-
-=head3 Escape sequences
-
-Because patterns are processed as double-quoted strings, the following
-also work:
-
- \t tab (HT, TAB)
- \n newline (LF, NL)
- \r return (CR)
- \f form feed (FF)
- \a alarm (bell) (BEL)
- \e escape (think troff) (ESC)
- \cK control char (example: VT)
- \x{}, \x00 character whose ordinal is the given hexadecimal number
- \N{name} named Unicode character or character sequence
- \N{U+263D} Unicode character (example: FIRST QUARTER MOON)
- \o{}, \000 character whose ordinal is the given octal number
- \l lowercase next char (think vi)
- \u uppercase next char (think vi)
- \L lowercase till \E (think vi)
- \U uppercase till \E (think vi)
- \Q quote (disable) pattern metacharacters till \E
- \E end either case modification or quoted section, think vi
-
-Details are in L<perlop/Quote and Quote-like Operators>.
-
-=head3 Character Classes and other Special Escapes
-
-In addition, Perl defines the following:
-X<\g> X<\k> X<\K> X<backreference>
-
- Sequence Note Description
- [...] [1] Match a character according to the rules of the
- bracketed character class defined by the "...".
- Example: [a-z] matches "a" or "b" or "c" ... or "z"
- [[:...:]] [2] Match a character according to the rules of the POSIX
- character class "..." within the outer bracketed
- character class. Example: [[:upper:]] matches any
- uppercase character.
- \w [3] Match a "word" character (alphanumeric plus "_", plus
- other connector punctuation chars plus Unicode
- marks)
- \W [3] Match a non-"word" character
- \s [3] Match a whitespace character
- \S [3] Match a non-whitespace character
- \d [3] Match a decimal digit character
- \D [3] Match a non-digit character
- \pP [3] Match P, named property. Use \p{Prop} for longer names
- \PP [3] Match non-P
- \X [4] Match Unicode "eXtended grapheme cluster"
- \C Match a single C-language char (octet) even if that is
- part of a larger UTF-8 character. Thus it breaks up
- characters into their UTF-8 bytes, so you may end up
- with malformed pieces of UTF-8. Unsupported in
- lookbehind.
- \1 [5] Backreference to a specific capture group or buffer.
- '1' may actually be any positive integer.
- \g1 [5] Backreference to a specific or previous group,
- \g{-1} [5] The number may be negative indicating a relative
- previous group and may optionally be wrapped in
- curly brackets for safer parsing.
- \g{name} [5] Named backreference
- \k<name> [5] Named backreference
- \K [6] Keep the stuff left of the \K, don't include it in $&
- \N [7] Any character but \n (experimental). Not affected by
- /s modifier
- \v [3] Vertical whitespace
- \V [3] Not vertical whitespace
- \h [3] Horizontal whitespace
- \H [3] Not horizontal whitespace
- \R [4] Linebreak
-
-=over 4
-
-=item [1]
-
-See L<perlrecharclass/Bracketed Character Classes> for details.
-
-=item [2]
-
-See L<perlrecharclass/POSIX Character Classes> for details.
-
-=item [3]
-
-See L<perlrecharclass/Backslash sequences> for details.
-
-=item [4]
-
-See L<perlrebackslash/Misc> for details.
-
-=item [5]
-
-See L</Capture groups> below for details.
-
-=item [6]
-
-See L</Extended Patterns> below for details.
-
-=item [7]
-
-Note that C<\N> has two meanings. When of the form C<\N{NAME}>, it matches the
-character or character sequence whose name is C<NAME>; and similarly
-when of the form C<\N{U+I<hex>}>, it matches the character whose Unicode
-code point is I<hex>. Otherwise it matches any character but C<\n>.
-
-=back
-
-=head3 Assertions
-
-Perl defines the following zero-width assertions:
-X<zero-width assertion> X<assertion> X<regex, zero-width assertion>
-X<regexp, zero-width assertion>
-X<regular expression, zero-width assertion>
-X<\b> X<\B> X<\A> X<\Z> X<\z> X<\G>
-
- \b Match a word boundary
- \B Match except at a word boundary
- \A Match only at beginning of string
- \Z Match only at end of string, or before newline at the end
- \z Match only at end of string
- \G Match only at pos() (e.g. at the end-of-match position
- of prior m//g)
-
-A word boundary (C<\b>) is a spot between two characters
-that has a C<\w> on one side of it and a C<\W> on the other side
-of it (in either order), counting the imaginary characters off the
-beginning and end of the string as matching a C<\W>. (Within
-character classes C<\b> represents backspace rather than a word
-boundary, just as it normally does in any double-quoted string.)
-The C<\A> and C<\Z> are just like "^" and "$", except that they
-won't match multiple times when the C</m> modifier is used, while
-"^" and "$" will match at every internal line boundary. To match
-the actual end of the string and not ignore an optional trailing
-newline, use C<\z>.
-X<\b> X<\A> X<\Z> X<\z> X</m>
-
-The C<\G> assertion can be used to chain global matches (using
-C<m//g>), as described in L<perlop/"Regexp Quote-Like Operators">.
-It is also useful when writing C<lex>-like scanners, when you have
-several patterns that you want to match against consequent substrings
-of your string; see the previous reference. The actual location
-where C<\G> will match can also be influenced by using C<pos()> as
-an lvalue: see L<perlfunc/pos>. Note that the rule for zero-length
-matches (see L</"Repeated Patterns Matching a Zero-length Substring">)
-is modified somewhat, in that contents to the left of C<\G> are
-not counted when determining the length of the match. Thus the following
-will not match forever:
-X<\G>
-
- my $string = 'ABC';
- pos($string) = 1;
- while ($string =~ /(.\G)/g) {
- print $1;
- }
-
-It will print 'A' and then terminate, as it considers the match to
-be zero-width, and thus will not match at the same position twice in a
-row.
-
-It is worth noting that C<\G> improperly used can result in an infinite
-loop. Take care when using patterns that include C<\G> in an alternation.
-
-=head3 Capture groups
-
-The bracketing construct C<( ... )> creates capture groups (also referred to as
-capture buffers). To refer to the current contents of a group later on, within
-the same pattern, use C<\g1> (or C<\g{1}>) for the first, C<\g2> (or C<\g{2}>)
-for the second, and so on.
-This is called a I<backreference>.
-X<regex, capture buffer> X<regexp, capture buffer>
-X<regex, capture group> X<regexp, capture group>
-X<regular expression, capture buffer> X<backreference>
-X<regular expression, capture group> X<backreference>
-X<\g{1}> X<\g{-1}> X<\g{name}> X<relative backreference> X<named backreference>
-X<named capture buffer> X<regular expression, named capture buffer>
-X<named capture group> X<regular expression, named capture group>
-X<%+> X<$+{name}> X<< \k<name> >>
-There is no limit to the number of captured substrings that you may use.
-Groups are numbered with the leftmost open parenthesis being number 1, etc. If
-a group did not match, the associated backreference won't match either. (This
-can happen if the group is optional, or in a different branch of an
-alternation.)
-You can omit the C<"g">, and write C<"\1">, etc, but there are some issues with
-this form, described below.
-
-You can also refer to capture groups relatively, by using a negative number, so
-that C<\g-1> and C<\g{-1}> both refer to the immediately preceding capture
-group, and C<\g-2> and C<\g{-2}> both refer to the group before it. For
-example:
-
- /
- (Y) # group 1
- ( # group 2
- (X) # group 3
- \g{-1} # backref to group 3
- \g{-3} # backref to group 1
- )
- /x
-
-would match the same as C</(Y) ( (X) \g3 \g1 )/x>. This allows you to
-interpolate regexes into larger regexes and not have to worry about the
-capture groups being renumbered.
-
-You can dispense with numbers altogether and create named capture groups.
-The notation is C<(?E<lt>I<name>E<gt>...)> to declare and C<\g{I<name>}> to
-reference. (To be compatible with .Net regular expressions, C<\g{I<name>}> may
-also be written as C<\k{I<name>}>, C<\kE<lt>I<name>E<gt>> or C<\k'I<name>'>.)
-I<name> must not begin with a number, nor contain hyphens.
-When different groups within the same pattern have the same name, any reference
-to that name assumes the leftmost defined group. Named groups count in
-absolute and relative numbering, and so can also be referred to by those
-numbers.
-(It's possible to do things with named capture groups that would otherwise
-require C<(??{})>.)
-
-Capture group contents are dynamically scoped and available to you outside the
-pattern until the end of the enclosing block or until the next successful
-match, whichever comes first. (See L<perlsyn/"Compound Statements">.)
-You can refer to them by absolute number (using C<"$1"> instead of C<"\g1">,
-etc); or by name via the C<%+> hash, using C<"$+{I<name>}">.
-
-Braces are required in referring to named capture groups, but are optional for
-absolute or relative numbered ones. Braces are safer when creating a regex by
-concatenating smaller strings. For example if you have C<qr/$a$b/>, and C<$a>
-contained C<"\g1">, and C<$b> contained C<"37">, you would get C</\g137/> which
-is probably not what you intended.
-
-The C<\g> and C<\k> notations were introduced in Perl 5.10.0. Prior to that
-there were no named nor relative numbered capture groups. Absolute numbered
-groups were referred to using C<\1>,
-C<\2>, etc., and this notation is still
-accepted (and likely always will be). But it leads to some ambiguities if
-there are more than 9 capture groups, as C<\10> could mean either the tenth
-capture group, or the character whose ordinal in octal is 010 (a backspace in
-ASCII). Perl resolves this ambiguity by interpreting C<\10> as a backreference
-only if at least 10 left parentheses have opened before it. Likewise C<\11> is
-a backreference only if at least 11 left parentheses have opened before it.
-And so on. C<\1> through C<\9> are always interpreted as backreferences.
-There are several examples below that illustrate these perils. You can avoid
-the ambiguity by always using C<\g{}> or C<\g> if you mean capturing groups;
-and for octal constants always using C<\o{}>, or for C<\077> and below, using 3
-digits padded with leading zeros, since a leading zero implies an octal
-constant.
-
-The C<\I<digit>> notation also works in certain circumstances outside
-the pattern. See L</Warning on \1 Instead of $1> below for details.
-
-Examples:
-
- s/^([^ ]*) *([^ ]*)/$2 $1/; # swap first two words
-
- /(.)\g1/ # find first doubled char
- and print "'$1' is the first doubled character\n";
-
- /(?<char>.)\k<char>/ # ... a different way
- and print "'$+{char}' is the first doubled character\n";
-
- /(?'char'.)\g1/ # ... mix and match
- and print "'$1' is the first doubled character\n";
-
- if (/Time: (..):(..):(..)/) { # parse out values
- $hours = $1;
- $minutes = $2;
- $seconds = $3;
- }
-
- /(.)(.)(.)(.)(.)(.)(.)(.)(.)\g10/ # \g10 is a backreference
- /(.)(.)(.)(.)(.)(.)(.)(.)(.)\10/ # \10 is octal
- /((.)(.)(.)(.)(.)(.)(.)(.)(.))\10/ # \10 is a backreference
- /((.)(.)(.)(.)(.)(.)(.)(.)(.))\010/ # \010 is octal
-
- $a = '(.)\1'; # Creates problems when concatenated.
- $b = '(.)\g{1}'; # Avoids the problems.
- "aa" =~ /${a}/; # True
- "aa" =~ /${b}/; # True
- "aa0" =~ /${a}0/; # False!
- "aa0" =~ /${b}0/; # True
- "aa\x08" =~ /${a}0/; # True!
- "aa\x08" =~ /${b}0/; # False
-
-Several special variables also refer back to portions of the previous
-match. C<$+> returns whatever the last bracket match matched.
-C<$&> returns the entire matched string. (At one point C<$0> did
-also, but now it returns the name of the program.) C<$`> returns
-everything before the matched string. C<$'> returns everything
-after the matched string. And C<$^N> contains whatever was matched by
-the most-recently closed group (submatch). C<$^N> can be used in
-extended patterns (see below), for example to assign a submatch to a
-variable.
-X<$+> X<$^N> X<$&> X<$`> X<$'>
-
-These special variables, like the C<%+> hash and the numbered match variables
-(C<$1>, C<$2>, C<$3>, etc.) are dynamically scoped
-until the end of the enclosing block or until the next successful
-match, whichever comes first. (See L<perlsyn/"Compound Statements">.)
-X<$+> X<$^N> X<$&> X<$`> X<$'>
-X<$1> X<$2> X<$3> X<$4> X<$5> X<$6> X<$7> X<$8> X<$9>
-
-B<NOTE>: Failed matches in Perl do not reset the match variables,
-which makes it easier to write code that tests for a series of more
-specific cases and remembers the best match.
-
-B<WARNING>: Once Perl sees that you need one of C<$&>, C<$`>, or
-C<$'> anywhere in the program, it has to provide them for every
-pattern match. This may substantially slow your program. Perl
-uses the same mechanism to produce C<$1>, C<$2>, etc, so you also pay a
-price for each pattern that contains capturing parentheses. (To
-avoid this cost while retaining the grouping behaviour, use the
-extended regular expression C<(?: ... )> instead.) But if you never
-use C<$&>, C<$`> or C<$'>, then patterns I<without> capturing
-parentheses will not be penalized. So avoid C<$&>, C<$'>, and C<$`>
-if you can, but if you can't (and some algorithms really appreciate
-them), once you've used them once, use them at will, because you've
-already paid the price. As of 5.005, C<$&> is not so costly as the
-other two.
-X<$&> X<$`> X<$'>
-
-As a workaround for this problem, Perl 5.10.0 introduces C<${^PREMATCH}>,
-C<${^MATCH}> and C<${^POSTMATCH}>, which are equivalent to C<$`>, C<$&>
-and C<$'>, B<except> that they are only guaranteed to be defined after a
-successful match that was executed with the C</p> (preserve) modifier.
-The use of these variables incurs no global performance penalty, unlike
-their punctuation char equivalents, however at the trade-off that you
-have to tell perl when you want to use them.
-X</p> X<p modifier>
-
-=head2 Quoting metacharacters
-
-Backslashed metacharacters in Perl are alphanumeric, such as C<\b>,
-C<\w>, C<\n>. Unlike some other regular expression languages, there
-are no backslashed symbols that aren't alphanumeric. So anything
-that looks like \\, \(, \), \<, \>, \{, or \} is always
-interpreted as a literal character, not a metacharacter. This was
-once used in a common idiom to disable or quote the special meanings
-of regular expression metacharacters in a string that you want to
-use for a pattern. Simply quote all non-"word" characters:
-
- $pattern =~ s/(\W)/\\$1/g;
-
-(If C<use locale> is set, then this depends on the current locale.)
-Today it is more common to use the quotemeta() function or the C<\Q>
-metaquoting escape sequence to disable all metacharacters' special
-meanings like this:
-
- /$unquoted\Q$quoted\E$unquoted/
-
-Beware that if you put literal backslashes (those not inside
-interpolated variables) between C<\Q> and C<\E>, double-quotish
-backslash interpolation may lead to confusing results. If you
-I<need> to use literal backslashes within C<\Q...\E>,
-consult L<perlop/"Gory details of parsing quoted constructs">.
-
-C<quotemeta()> and C<\Q> are fully described in L<perlfunc/quotemeta>.
-
-=head2 Extended Patterns
-
-Perl also defines a consistent extension syntax for features not
-found in standard tools like B<awk> and
-B<lex>. The syntax for most of these is a
-pair of parentheses with a question mark as the first thing within
-the parentheses. The character after the question mark indicates
-the extension.
-
-The stability of these extensions varies widely. Some have been
-part of the core language for many years. Others are experimental
-and may change without warning or be completely removed. Check
-the documentation on an individual feature to verify its current
-status.
-
-A question mark was chosen for this and for the minimal-matching
-construct because 1) question marks are rare in older regular
-expressions, and 2) whenever you see one, you should stop and
-"question" exactly what is going on. That's psychology....
-
-=over 4
-
-=item C<(?#text)>
-X<(?#)>
-
-A comment. The text is ignored. If the C</x> modifier enables
-whitespace formatting, a simple C<#> will suffice. Note that Perl closes
-the comment as soon as it sees a C<)>, so there is no way to put a literal
-C<)> in the comment.
-
-=item C<(?adlupimsx-imsx)>
-
-=item C<(?^alupimsx)>
-X<(?)> X<(?^)>
-
-One or more embedded pattern-match modifiers, to be turned on (or
-turned off, if preceded by C<->) for the remainder of the pattern or
-the remainder of the enclosing pattern group (if any).
-
-This is particularly useful for dynamic patterns, such as those read in from a
-configuration file, taken from an argument, or specified in a table
-somewhere. Consider the case where some patterns want to be
-case-sensitive and some do not: The case-insensitive ones merely need to
-include C<(?i)> at the front of the pattern. For example:
-
- $pattern = "foobar";
- if ( /$pattern/i ) { }
-
- # more flexible:
-
- $pattern = "(?i)foobar";
- if ( /$pattern/ ) { }
-
-These modifiers are restored at the end of the enclosing group. For example,
-
- ( (?i) blah ) \s+ \g1
-
-will match C<blah> in any case, some spaces, and an exact (I<including the case>!)
-repetition of the previous word, assuming the C</x> modifier, and no C</i>
-modifier outside this group.
-
-These modifiers do not carry over into named subpatterns called in the
-enclosing group. In other words, a pattern such as C<((?i)(?&NAME))> does not
-change the case-sensitivity of the "NAME" pattern.
-
-Any of these modifiers can be set to apply globally to all regular
-expressions compiled within the scope of a C<use re>. See
-L<re/"'/flags' mode">.
-
-Starting in Perl 5.14, a C<"^"> (caret or circumflex accent) immediately
-after the C<"?"> is a shorthand equivalent to C<d-imsx>. Flags (except
-C<"d">) may follow the caret to override it.
-But a minus sign is not legal with it.
-
-Note that the C<a>, C<d>, C<l>, C<p>, and C<u> modifiers are special in
-that they can only be enabled, not disabled, and the C<a>, C<d>, C<l>, and
-C<u> modifiers are mutually exclusive: specifying one de-specifies the
-others, and a maximum of one (or two C<a>'s) may appear in the
-construct. Thus, for
-example, C<(?-p)> will warn when compiled under C<use warnings>;
-C<(?-d:...)> and C<(?dl:...)> are fatal errors.
-
-Note also that the C<p> modifier is special in that its presence
-anywhere in a pattern has a global effect.
-
-=item C<(?:pattern)>
-X<(?:)>
-
-=item C<(?adluimsx-imsx:pattern)>
-
-=item C<(?^aluimsx:pattern)>
-X<(?^:)>
-
-This is for clustering, not capturing; it groups subexpressions like
-"()", but doesn't make backreferences as "()" does. So
-
- @fields = split(/\b(?:a|b|c)\b/)
-
-is like
-
- @fields = split(/\b(a|b|c)\b/)
-
-but doesn't spit out extra fields. It's also cheaper not to capture
-characters if you don't need to.
-
-Any letters between C<?> and C<:> act as flags modifiers as with
-C<(?adluimsx-imsx)>. For example,
-
- /(?s-i:more.*than).*million/i
-
-is equivalent to the more verbose
-
- /(?:(?s-i)more.*than).*million/i
-
-Starting in Perl 5.14, a C<"^"> (caret or circumflex accent) immediately
-after the C<"?"> is a shorthand equivalent to C<d-imsx>. Any positive
-flags (except C<"d">) may follow the caret, so
-
- (?^x:foo)
-
-is equivalent to
-
- (?x-ims:foo)
-
-The caret tells Perl that this cluster doesn't inherit the flags of any
-surrounding pattern, but uses the system defaults (C<d-imsx>),
-modified by any flags specified.
-
-The caret allows for simpler stringification of compiled regular
-expressions. These look like
-
- (?^:pattern)
-
-with any non-default flags appearing between the caret and the colon.
-A test that looks at such stringification thus doesn't need to have the
-system default flags hard-coded in it, just the caret. If new flags are
-added to Perl, the meaning of the caret's expansion will change to include
-the default for those flags, so the test will still work, unchanged.
-
-Specifying a negative flag after the caret is an error, as the flag is
-redundant.
-
-Mnemonic for C<(?^...)>: A fresh beginning since the usual use of a caret is
-to match at the beginning.
-
-=item C<(?|pattern)>
-X<(?|)> X<Branch reset>
-
-This is the "branch reset" pattern, which has the special property
-that the capture groups are numbered from the same starting point
-in each alternation branch. It is available starting from perl 5.10.0.
-
-Capture groups are numbered from left to right, but inside this
-construct the numbering is restarted for each branch.
-
-The numbering within each branch will be as normal, and any groups
-following this construct will be numbered as though the construct
-contained only one branch, that being the one with the most capture
-groups in it.
-
-This construct is useful when you want to capture one of a
-number of alternative matches.
-
-Consider the following pattern. The numbers underneath show in
-which group the captured content will be stored.
-
-
- # before ---------------branch-reset----------- after
- / ( a ) (?| x ( y ) z | (p (q) r) | (t) u (v) ) ( z ) /x
- # 1 2 2 3 2 3 4
-
-Be careful when using the branch reset pattern in combination with
-named captures. Named captures are implemented as being aliases to
-numbered groups holding the captures, and that interferes with the
-implementation of the branch reset pattern. If you are using named
-captures in a branch reset pattern, it's best to use the same names,
-in the same order, in each of the alternations:
-
- /(?| (?<a> x ) (?<b> y )
- | (?<a> z ) (?<b> w )) /x
-
-Not doing so may lead to surprises:
-
- "12" =~ /(?| (?<a> \d+ ) | (?<b> \D+))/x;
- say $+ {a}; # Prints '12'
- say $+ {b}; # *Also* prints '12'.
-
-The problem here is that both the group named C<< a >> and the group
-named C<< b >> are aliases for the group belonging to C<< $1 >>.
-
-=item Look-Around Assertions
-X<look-around assertion> X<lookaround assertion> X<look-around> X<lookaround>
-
-Look-around assertions are zero-width patterns which match a specific
-pattern without including it in C<$&>. Positive assertions match when
-their subpattern matches, negative assertions match when their subpattern
-fails. Look-behind matches text up to the current match position,
-look-ahead matches text following the current match position.
-
-=over 4
-
-=item C<(?=pattern)>
-X<(?=)> X<look-ahead, positive> X<lookahead, positive>
-
-A zero-width positive look-ahead assertion. For example, C</\w+(?=\t)/>
-matches a word followed by a tab, without including the tab in C<$&>.
-
-=item C<(?!pattern)>
-X<(?!)> X<look-ahead, negative> X<lookahead, negative>
-
-A zero-width negative look-ahead assertion. For example C</foo(?!bar)/>
-matches any occurrence of "foo" that isn't followed by "bar". Note
-however that look-ahead and look-behind are NOT the same thing. You cannot
-use this for look-behind.
-
-If you are looking for a "bar" that isn't preceded by a "foo", C</(?!foo)bar/>
-will not do what you want. That's because the C<(?!foo)> is just saying that
-the next thing cannot be "foo"--and it's not, it's a "bar", so "foobar" will
-match. Use look-behind instead (see below).
-
-=item C<(?<=pattern)> C<\K>
-X<(?<=)> X<look-behind, positive> X<lookbehind, positive> X<\K>
-
-A zero-width positive look-behind assertion. For example, C</(?<=\t)\w+/>
-matches a word that follows a tab, without including the tab in C<$&>.
-Works only for fixed-width look-behind.
-
-There is a special form of this construct, called C<\K>, which causes the
-regex engine to "keep" everything it had matched prior to the C<\K> and
-not include it in C<$&>. This effectively provides variable-length
-look-behind. The use of C<\K> inside of another look-around assertion
-is allowed, but the behaviour is currently not well defined.
-
-For various reasons C<\K> may be significantly more efficient than the
-equivalent C<< (?<=...) >> construct, and it is especially useful in
-situations where you want to efficiently remove something following
-something else in a string. For instance
-
- s/(foo)bar/$1/g;
-
-can be rewritten as the much more efficient
-
- s/foo\Kbar//g;
-
-=item C<(?<!pattern)>
-X<(?<!)> X<look-behind, negative> X<lookbehind, negative>
-
-A zero-width negative look-behind assertion. For example C</(?<!bar)foo/>
-matches any occurrence of "foo" that does not follow "bar". Works
-only for fixed-width look-behind.
-
-=back
-
-=item C<(?'NAME'pattern)>
-
-=item C<< (?<NAME>pattern) >>
-X<< (?<NAME>) >> X<(?'NAME')> X<named capture> X<capture>
-
-A named capture group. Identical in every respect to normal capturing
-parentheses C<()> but for the additional fact that the group
-can be referred to by name in various regular expression
-constructs (like C<\g{NAME}>) and can be accessed by name
-after a successful match via C<%+> or C<%->. See L<perlvar>
-for more details on the C<%+> and C<%-> hashes.
-
-If multiple distinct capture groups have the same name then the
-$+{NAME} will refer to the leftmost defined group in the match.
-
-The forms C<(?'NAME'pattern)> and C<< (?<NAME>pattern) >> are equivalent.
-
-B<NOTE:> While the notation of this construct is the same as the similar
-function in .NET regexes, the behavior is not. In Perl the groups are
-numbered sequentially regardless of being named or not. Thus in the
-pattern
-
- /(x)(?<foo>y)(z)/
-
-$+{foo} will be the same as $2, and $3 will contain 'z' instead of
-the opposite which is what a .NET regex hacker might expect.
-
-Currently NAME is restricted to simple identifiers only.
-In other words, it must match C</^[_A-Za-z][_A-Za-z0-9]*\z/> or
-its Unicode extension (see L<utf8>),
-though it isn't extended by the locale (see L<perllocale>).
-
-B<NOTE:> In order to make things easier for programmers with experience
-with the Python or PCRE regex engines, the pattern C<< (?PE<lt>NAMEE<gt>pattern) >>
-may be used instead of C<< (?<NAME>pattern) >>; however this form does not
-support the use of single quotes as a delimiter for the name.
-
-=item C<< \k<NAME> >>
-
-=item C<< \k'NAME' >>
-
-Named backreference. Similar to numeric backreferences, except that
-the group is designated by name and not number. If multiple groups
-have the same name then it refers to the leftmost defined group in
-the current match.
-
-It is an error to refer to a name not defined by a C<< (?<NAME>) >>
-earlier in the pattern.
-
-Both forms are equivalent.
-
-B<NOTE:> In order to make things easier for programmers with experience
-with the Python or PCRE regex engines, the pattern C<< (?P=NAME) >>
-may be used instead of C<< \k<NAME> >>.
-
-=item C<(?{ code })>
-X<(?{})> X<regex, code in> X<regexp, code in> X<regular expression, code in>
-
-B<WARNING>: This extended regular expression feature is considered
-experimental, and may be changed without notice. Code executed that
-has side effects may not perform identically from version to version
-due to the effect of future optimisations in the regex engine.
-
-This zero-width assertion evaluates any embedded Perl code. It
-always succeeds, and its C<code> is not interpolated. Currently,
-the rules to determine where the C<code> ends are somewhat convoluted.
-
-This feature can be used together with the special variable C<$^N> to
-capture the results of submatches in variables without having to keep
-track of the number of nested parentheses. For example:
-
- $_ = "The brown fox jumps over the lazy dog";
- /the (\S+)(?{ $color = $^N }) (\S+)(?{ $animal = $^N })/i;
- print "color = $color, animal = $animal\n";
-
-Inside the C<(?{...})> block, C<$_> refers to the string the regular
-expression is matching against. You can also use C<pos()> to know what is
-the current position of matching within this string.
-
-The C<code> is properly scoped in the following sense: If the assertion
-is backtracked (compare L<"Backtracking">), all changes introduced after
-C<local>ization are undone, so that
-
- $_ = 'a' x 8;
- m<
- (?{ $cnt = 0 }) # Initialize $cnt.
- (
- a
- (?{
- local $cnt = $cnt + 1; # Update $cnt,
- # backtracking-safe.
- })
- )*
- aaaa
- (?{ $res = $cnt }) # On success copy to
- # non-localized location.
- >x;
-
-will set C<$res = 4>. Note that after the match, C<$cnt> returns to the globally
-introduced value, because the scopes that restrict C<local> operators
-are unwound.
-
-This assertion may be used as a C<(?(condition)yes-pattern|no-pattern)>
-switch. If I<not> used in this way, the result of evaluation of
-C<code> is put into the special variable C<$^R>. This happens
-immediately, so C<$^R> can be used from other C<(?{ code })> assertions
-inside the same regular expression.
-
-The assignment to C<$^R> above is properly localized, so the old
-value of C<$^R> is restored if the assertion is backtracked; compare
-L<"Backtracking">.
-
-For reasons of security, this construct is forbidden if the regular
-expression involves run-time interpolation of variables, unless the
-perilous C<use re 'eval'> pragma has been used (see L<re>), or the
-variables contain results of the C<qr//> operator (see
-L<perlop/"qr/STRINGE<sol>msixpodual">).
-
-This restriction is due to the wide-spread and remarkably convenient
-custom of using run-time determined strings as patterns. For example:
-
- $re = <>;
- chomp $re;
- $string =~ /$re/;
-
-Before Perl knew how to execute interpolated code within a pattern,
-this operation was completely safe from a security point of view,
-although it could raise an exception from an illegal pattern. If
-you turn on the C<use re 'eval'>, though, it is no longer secure,
-so you should only do so if you are also using taint checking.
-Better yet, use the carefully constrained evaluation within a Safe
-compartment. See L<perlsec> for details about both these mechanisms.
-
-B<WARNING>: Use of lexical (C<my>) variables in these blocks is
-broken. The result is unpredictable and will make perl unstable. The
-workaround is to use global (C<our>) variables.
-
-B<WARNING>: In perl 5.12.x and earlier, the regex engine
-was not re-entrant, so interpolated code could not
-safely invoke the regex engine either directly with
-C<m//> or C<s///>), or indirectly with functions such as
-C<split>. Invoking the regex engine in these blocks would make perl
-unstable.
-
-=item C<(??{ code })>
-X<(??{})>
-X<regex, postponed> X<regexp, postponed> X<regular expression, postponed>
-
-B<WARNING>: This extended regular expression feature is considered
-experimental, and may be changed without notice. Code executed that
-has side effects may not perform identically from version to version
-due to the effect of future optimisations in the regex engine.
-
-This is a "postponed" regular subexpression. The C<code> is evaluated
-at run time, at the moment this subexpression may match. The result
-of evaluation is considered a regular expression and matched as
-if it were inserted instead of this construct. Note that this means
-that the contents of capture groups defined inside an eval'ed pattern
-are not available outside of the pattern, and vice versa, there is no
-way for the inner pattern returned from the code block to refer to a
-capture group defined outside. (The code block itself can use C<$1>, etc.,
-to refer to the enclosing pattern's capture groups.) Thus,
-
- ('a' x 100)=~/(??{'(.)' x 100})/
-
-B<will> match, it will B<not> set $1.
-
-The C<code> is not interpolated. As before, the rules to determine
-where the C<code> ends are currently somewhat convoluted.
-
-The following pattern matches a parenthesized group:
-
- $re = qr{
- \(
- (?:
- (?> [^()]+ ) # Non-parens without backtracking
- |
- (??{ $re }) # Group with matching parens
- )*
- \)
- }x;
-
-See also C<(?PARNO)> for a different, more efficient way to accomplish
-the same task.
-
-For reasons of security, this construct is forbidden if the regular
-expression involves run-time interpolation of variables, unless the
-perilous C<use re 'eval'> pragma has been used (see L<re>), or the
-variables contain results of the C<qr//> operator (see
-L<perlop/"qrE<sol>STRINGE<sol>msixpodual">).
-
-In perl 5.12.x and earlier, because the regex engine was not re-entrant,
-delayed code could not safely invoke the regex engine either directly with
-C<m//> or C<s///>), or indirectly with functions such as C<split>.
-
-Recursing deeper than 50 times without consuming any input string will
-result in a fatal error. The maximum depth is compiled into perl, so
-changing it requires a custom build.
-
-=item C<(?PARNO)> C<(?-PARNO)> C<(?+PARNO)> C<(?R)> C<(?0)>
-X<(?PARNO)> X<(?1)> X<(?R)> X<(?0)> X<(?-1)> X<(?+1)> X<(?-PARNO)> X<(?+PARNO)>
-X<regex, recursive> X<regexp, recursive> X<regular expression, recursive>
-X<regex, relative recursion>
-
-Similar to C<(??{ code })> except it does not involve compiling any code,
-instead it treats the contents of a capture group as an independent
-pattern that must match at the current position. Capture groups
-contained by the pattern will have the value as determined by the
-outermost recursion.
-
-PARNO is a sequence of digits (not starting with 0) whose value reflects
-the paren-number of the capture group to recurse to. C<(?R)> recurses to
-the beginning of the whole pattern. C<(?0)> is an alternate syntax for
-C<(?R)>. If PARNO is preceded by a plus or minus sign then it is assumed
-to be relative, with negative numbers indicating preceding capture groups
-and positive ones following. Thus C<(?-1)> refers to the most recently
-declared group, and C<(?+1)> indicates the next group to be declared.
-Note that the counting for relative recursion differs from that of
-relative backreferences, in that with recursion unclosed groups B<are>
-included.
-
-The following pattern matches a function foo() which may contain
-balanced parentheses as the argument.
-
- $re = qr{ ( # paren group 1 (full function)
- foo
- ( # paren group 2 (parens)
- \(
- ( # paren group 3 (contents of parens)
- (?:
- (?> [^()]+ ) # Non-parens without backtracking
- |
- (?2) # Recurse to start of paren group 2
- )*
- )
- \)
- )
- )
- }x;
-
-If the pattern was used as follows
-
- 'foo(bar(baz)+baz(bop))'=~/$re/
- and print "\$1 = $1\n",
- "\$2 = $2\n",
- "\$3 = $3\n";
-
-the output produced should be the following:
-
- $1 = foo(bar(baz)+baz(bop))
- $2 = (bar(baz)+baz(bop))
- $3 = bar(baz)+baz(bop)
-
-If there is no corresponding capture group defined, then it is a
-fatal error. Recursing deeper than 50 times without consuming any input
-string will also result in a fatal error. The maximum depth is compiled
-into perl, so changing it requires a custom build.
-
-The following shows how using negative indexing can make it
-easier to embed recursive patterns inside of a C<qr//> construct
-for later use:
-
- my $parens = qr/(\((?:[^()]++|(?-1))*+\))/;
- if (/foo $parens \s+ + \s+ bar $parens/x) {
- # do something here...
- }
-
-B<Note> that this pattern does not behave the same way as the equivalent
-PCRE or Python construct of the same form. In Perl you can backtrack into
-a recursed group, in PCRE and Python the recursed into group is treated
-as atomic. Also, modifiers are resolved at compile time, so constructs
-like (?i:(?1)) or (?:(?i)(?1)) do not affect how the sub-pattern will
-be processed.
-
-=item C<(?&NAME)>
-X<(?&NAME)>
-
-Recurse to a named subpattern. Identical to C<(?PARNO)> except that the
-parenthesis to recurse to is determined by name. If multiple parentheses have
-the same name, then it recurses to the leftmost.
-
-It is an error to refer to a name that is not declared somewhere in the
-pattern.
-
-B<NOTE:> In order to make things easier for programmers with experience
-with the Python or PCRE regex engines the pattern C<< (?P>NAME) >>
-may be used instead of C<< (?&NAME) >>.
-
-=item C<(?(condition)yes-pattern|no-pattern)>
-X<(?()>
-
-=item C<(?(condition)yes-pattern)>
-
-Conditional expression. Matches C<yes-pattern> if C<condition> yields
-a true value, matches C<no-pattern> otherwise. A missing pattern always
-matches.
-
-C<(condition)> should be either an integer in
-parentheses (which is valid if the corresponding pair of parentheses
-matched), a look-ahead/look-behind/evaluate zero-width assertion, a
-name in angle brackets or single quotes (which is valid if a group
-with the given name matched), or the special symbol (R) (true when
-evaluated inside of recursion or eval). Additionally the R may be
-followed by a number, (which will be true when evaluated when recursing
-inside of the appropriate group), or by C<&NAME>, in which case it will
-be true only when evaluated during recursion in the named group.
-
-Here's a summary of the possible predicates:
-
-=over 4
-
-=item (1) (2) ...
-
-Checks if the numbered capturing group has matched something.
-
-=item (<NAME>) ('NAME')
-
-Checks if a group with the given name has matched something.
-
-=item (?=...) (?!...) (?<=...) (?<!...)
-
-Checks whether the pattern matches (or does not match, for the '!'
-variants).
-
-=item (?{ CODE })
-
-Treats the return value of the code block as the condition.
-
-=item (R)
-
-Checks if the expression has been evaluated inside of recursion.
-
-=item (R1) (R2) ...
-
-Checks if the expression has been evaluated while executing directly
-inside of the n-th capture group. This check is the regex equivalent of
-
- if ((caller(0))[3] eq 'subname') { ... }
-
-In other words, it does not check the full recursion stack.
-
-=item (R&NAME)
-
-Similar to C<(R1)>, this predicate checks to see if we're executing
-directly inside of the leftmost group with a given name (this is the same
-logic used by C<(?&NAME)> to disambiguate). It does not check the full
-stack, but only the name of the innermost active recursion.
-
-=item (DEFINE)
-
-In this case, the yes-pattern is never directly executed, and no
-no-pattern is allowed. Similar in spirit to C<(?{0})> but more efficient.
-See below for details.
-
-=back
-
-For example:
-
- m{ ( \( )?
- [^()]+
- (?(1) \) )
- }x
-
-matches a chunk of non-parentheses, possibly included in parentheses
-themselves.
-
-A special form is the C<(DEFINE)> predicate, which never executes its
-yes-pattern directly, and does not allow a no-pattern. This allows one to
-define subpatterns which will be executed only by the recursion mechanism.
-This way, you can define a set of regular expression rules that can be
-bundled into any pattern you choose.
-
-It is recommended that for this usage you put the DEFINE block at the
-end of the pattern, and that you name any subpatterns defined within it.
-
-Also, it's worth noting that patterns defined this way probably will
-not be as efficient, as the optimiser is not very clever about
-handling them.
-
-An example of how this might be used is as follows:
-
- /(?<NAME>(?&NAME_PAT))(?<ADDR>(?&ADDRESS_PAT))
- (?(DEFINE)
- (?<NAME_PAT>....)
- (?<ADRESS_PAT>....)
- )/x
-
-Note that capture groups matched inside of recursion are not accessible
-after the recursion returns, so the extra layer of capturing groups is
-necessary. Thus C<$+{NAME_PAT}> would not be defined even though
-C<$+{NAME}> would be.
-
-Finally, keep in mind that subpatterns created inside a DEFINE block
-count towards the absolute and relative number of captures, so this:
-
- my @captures = "a" =~ /(.) # First capture
- (?(DEFINE)
- (?<EXAMPLE> 1 ) # Second capture
- )/x;
- say scalar @captures;
-
-Will output 2, not 1. This is particularly important if you intend to
-compile the definitions with the C<qr//> operator, and later
-interpolate them in another pattern.
-
-=item C<< (?>pattern) >>
-X<backtrack> X<backtracking> X<atomic> X<possessive>
-
-An "independent" subexpression, one which matches the substring
-that a I<standalone> C<pattern> would match if anchored at the given
-position, and it matches I<nothing other than this substring>. This
-construct is useful for optimizations of what would otherwise be
-"eternal" matches, because it will not backtrack (see L<"Backtracking">).
-It may also be useful in places where the "grab all you can, and do not
-give anything back" semantic is desirable.
-
-For example: C<< ^(?>a*)ab >> will never match, since C<< (?>a*) >>
-(anchored at the beginning of string, as above) will match I<all>
-characters C<a> at the beginning of string, leaving no C<a> for
-C<ab> to match. In contrast, C<a*ab> will match the same as C<a+b>,
-since the match of the subgroup C<a*> is influenced by the following
-group C<ab> (see L<"Backtracking">). In particular, C<a*> inside
-C<a*ab> will match fewer characters than a standalone C<a*>, since
-this makes the tail match.
-
-C<< (?>pattern) >> does not disable backtracking altogether once it has
-matched. It is still possible to backtrack past the construct, but not
-into it. So C<< ((?>a*)|(?>b*))ar >> will still match "bar".
-
-An effect similar to C<< (?>pattern) >> may be achieved by writing
-C<(?=(pattern))\g{-1}>. This matches the same substring as a standalone
-C<a+>, and the following C<\g{-1}> eats the matched string; it therefore
-makes a zero-length assertion into an analogue of C<< (?>...) >>.
-(The difference between these two constructs is that the second one
-uses a capturing group, thus shifting ordinals of backreferences
-in the rest of a regular expression.)
-
-Consider this pattern:
-
- m{ \(
- (
- [^()]+ # x+
- |
- \( [^()]* \)
- )+
- \)
- }x
-
-That will efficiently match a nonempty group with matching parentheses
-two levels deep or less. However, if there is no such group, it
-will take virtually forever on a long string. That's because there
-are so many different ways to split a long string into several
-substrings. This is what C<(.+)+> is doing, and C<(.+)+> is similar
-to a subpattern of the above pattern. Consider how the pattern
-above detects no-match on C<((()aaaaaaaaaaaaaaaaaa> in several
-seconds, but that each extra letter doubles this time. This
-exponential performance will make it appear that your program has
-hung. However, a tiny change to this pattern
-
- m{ \(
- (
- (?> [^()]+ ) # change x+ above to (?> x+ )
- |
- \( [^()]* \)
- )+
- \)
- }x
-
-which uses C<< (?>...) >> matches exactly when the one above does (verifying
-this yourself would be a productive exercise), but finishes in a fourth
-the time when used on a similar string with 1000000 C<a>s. Be aware,
-however, that, when this construct is followed by a
-quantifier, it currently triggers a warning message under
-the C<use warnings> pragma or B<-w> switch saying it
-C<"matches null string many times in regex">.
-
-On simple groups, such as the pattern C<< (?> [^()]+ ) >>, a comparable
-effect may be achieved by negative look-ahead, as in C<[^()]+ (?! [^()] )>.
-This was only 4 times slower on a string with 1000000 C<a>s.
-
-The "grab all you can, and do not give anything back" semantic is desirable
-in many situations where on the first sight a simple C<()*> looks like
-the correct solution. Suppose we parse text with comments being delimited
-by C<#> followed by some optional (horizontal) whitespace. Contrary to
-its appearance, C<#[ \t]*> I<is not> the correct subexpression to match
-the comment delimiter, because it may "give up" some whitespace if
-the remainder of the pattern can be made to match that way. The correct
-answer is either one of these:
-
- (?>#[ \t]*)
- #[ \t]*(?![ \t])
-
-For example, to grab non-empty comments into $1, one should use either
-one of these:
-
- / (?> \# [ \t]* ) ( .+ ) /x;
- / \# [ \t]* ( [^ \t] .* ) /x;
-
-Which one you pick depends on which of these expressions better reflects
-the above specification of comments.
-
-In some literature this construct is called "atomic matching" or
-"possessive matching".
-
-Possessive quantifiers are equivalent to putting the item they are applied
-to inside of one of these constructs. The following equivalences apply:
-
- Quantifier Form Bracketing Form
- --------------- ---------------
- PAT*+ (?>PAT*)
- PAT++ (?>PAT+)
- PAT?+ (?>PAT?)
- PAT{min,max}+ (?>PAT{min,max})
-
-=back
-
-=head2 Special Backtracking Control Verbs
-
-B<WARNING:> These patterns are experimental and subject to change or
-removal in a future version of Perl. Their usage in production code should
-be noted to avoid problems during upgrades.
-
-These special patterns are generally of the form C<(*VERB:ARG)>. Unless
-otherwise stated the ARG argument is optional; in some cases, it is
-forbidden.
-
-Any pattern containing a special backtracking verb that allows an argument
-has the special behaviour that when executed it sets the current package's
-C<$REGERROR> and C<$REGMARK> variables. When doing so the following
-rules apply:
-
-On failure, the C<$REGERROR> variable will be set to the ARG value of the
-verb pattern, if the verb was involved in the failure of the match. If the
-ARG part of the pattern was omitted, then C<$REGERROR> will be set to the
-name of the last C<(*MARK:NAME)> pattern executed, or to TRUE if there was
-none. Also, the C<$REGMARK> variable will be set to FALSE.
-
-On a successful match, the C<$REGERROR> variable will be set to FALSE, and
-the C<$REGMARK> variable will be set to the name of the last
-C<(*MARK:NAME)> pattern executed. See the explanation for the
-C<(*MARK:NAME)> verb below for more details.
-
-B<NOTE:> C<$REGERROR> and C<$REGMARK> are not magic variables like C<$1>
-and most other regex-related variables. They are not local to a scope, nor
-readonly, but instead are volatile package variables similar to C<$AUTOLOAD>.
-Use C<local> to localize changes to them to a specific scope if necessary.
-
-If a pattern does not contain a special backtracking verb that allows an
-argument, then C<$REGERROR> and C<$REGMARK> are not touched at all.
-
-=over 3
-
-=item Verbs that take an argument
-
-=over 4
-
-=item C<(*PRUNE)> C<(*PRUNE:NAME)>
-X<(*PRUNE)> X<(*PRUNE:NAME)>
-
-This zero-width pattern prunes the backtracking tree at the current point
-when backtracked into on failure. Consider the pattern C<A (*PRUNE) B>,
-where A and B are complex patterns. Until the C<(*PRUNE)> verb is reached,
-A may backtrack as necessary to match. Once it is reached, matching
-continues in B, which may also backtrack as necessary; however, should B
-not match, then no further backtracking will take place, and the pattern
-will fail outright at the current starting position.
-
-The following example counts all the possible matching strings in a
-pattern (without actually matching any of them).
-
- 'aaab' =~ /a+b?(?{print "$&\n"; $count++})(*FAIL)/;
- print "Count=$count\n";
-
-which produces:
-
- aaab
- aaa
- aa
- a
- aab
- aa
- a
- ab
- a
- Count=9
-
-If we add a C<(*PRUNE)> before the count like the following
-
- 'aaab' =~ /a+b?(*PRUNE)(?{print "$&\n"; $count++})(*FAIL)/;
- print "Count=$count\n";
-
-we prevent backtracking and find the count of the longest matching string
-at each matching starting point like so:
-
- aaab
- aab
- ab
- Count=3
-
-Any number of C<(*PRUNE)> assertions may be used in a pattern.
-
-See also C<< (?>pattern) >> and possessive quantifiers for other ways to
-control backtracking. In some cases, the use of C<(*PRUNE)> can be
-replaced with a C<< (?>pattern) >> with no functional difference; however,
-C<(*PRUNE)> can be used to handle cases that cannot be expressed using a
-C<< (?>pattern) >> alone.
-
-=item C<(*SKIP)> C<(*SKIP:NAME)>
-X<(*SKIP)>
-
-This zero-width pattern is similar to C<(*PRUNE)>, except that on
-failure it also signifies that whatever text that was matched leading up
-to the C<(*SKIP)> pattern being executed cannot be part of I<any> match
-of this pattern. This effectively means that the regex engine "skips" forward
-to this position on failure and tries to match again, (assuming that
-there is sufficient room to match).
-
-The name of the C<(*SKIP:NAME)> pattern has special significance. If a
-C<(*MARK:NAME)> was encountered while matching, then it is that position
-which is used as the "skip point". If no C<(*MARK)> of that name was
-encountered, then the C<(*SKIP)> operator has no effect. When used
-without a name the "skip point" is where the match point was when
-executing the (*SKIP) pattern.
-
-Compare the following to the examples in C<(*PRUNE)>; note the string
-is twice as long:
-
- 'aaabaaab' =~ /a+b?(*SKIP)(?{print "$&\n"; $count++})(*FAIL)/;
- print "Count=$count\n";
-
-outputs
-
- aaab
- aaab
- Count=2
-
-Once the 'aaab' at the start of the string has matched, and the C<(*SKIP)>
-executed, the next starting point will be where the cursor was when the
-C<(*SKIP)> was executed.
-
-=item C<(*MARK:NAME)> C<(*:NAME)>
-X<(*MARK)> X<(*MARK:NAME)> X<(*:NAME)>
-
-This zero-width pattern can be used to mark the point reached in a string
-when a certain part of the pattern has been successfully matched. This
-mark may be given a name. A later C<(*SKIP)> pattern will then skip
-forward to that point if backtracked into on failure. Any number of
-C<(*MARK)> patterns are allowed, and the NAME portion may be duplicated.
-
-In addition to interacting with the C<(*SKIP)> pattern, C<(*MARK:NAME)>
-can be used to "label" a pattern branch, so that after matching, the
-program can determine which branches of the pattern were involved in the
-match.
-
-When a match is successful, the C<$REGMARK> variable will be set to the
-name of the most recently executed C<(*MARK:NAME)> that was involved
-in the match.
-
-This can be used to determine which branch of a pattern was matched
-without using a separate capture group for each branch, which in turn
-can result in a performance improvement, as perl cannot optimize
-C</(?:(x)|(y)|(z))/> as efficiently as something like
-C</(?:x(*MARK:x)|y(*MARK:y)|z(*MARK:z))/>.
-
-When a match has failed, and unless another verb has been involved in
-failing the match and has provided its own name to use, the C<$REGERROR>
-variable will be set to the name of the most recently executed
-C<(*MARK:NAME)>.
-
-See L</(*SKIP)> for more details.
-
-As a shortcut C<(*MARK:NAME)> can be written C<(*:NAME)>.
-
-=item C<(*THEN)> C<(*THEN:NAME)>
-
-This is similar to the "cut group" operator C<::> from Perl 6. Like
-C<(*PRUNE)>, this verb always matches, and when backtracked into on
-failure, it causes the regex engine to try the next alternation in the
-innermost enclosing group (capturing or otherwise) that has alternations.
-The two branches of a C<(?(condition)yes-pattern|no-pattern)> do not
-count as an alternation, as far as C<(*THEN)> is concerned.
-
-Its name comes from the observation that this operation combined with the
-alternation operator (C<|>) can be used to create what is essentially a
-pattern-based if/then/else block:
-
- ( COND (*THEN) FOO | COND2 (*THEN) BAR | COND3 (*THEN) BAZ )
-
-Note that if this operator is used and NOT inside of an alternation then
-it acts exactly like the C<(*PRUNE)> operator.
-
- / A (*PRUNE) B /
-
-is the same as
-
- / A (*THEN) B /
-
-but
-
- / ( A (*THEN) B | C (*THEN) D ) /
-
-is not the same as
-
- / ( A (*PRUNE) B | C (*PRUNE) D ) /
-
-as after matching the A but failing on the B the C<(*THEN)> verb will
-backtrack and try C; but the C<(*PRUNE)> verb will simply fail.
-
-=back
-
-=item Verbs without an argument
-
-=over 4
-
-=item C<(*COMMIT)>
-X<(*COMMIT)>
-
-This is the Perl 6 "commit pattern" C<< <commit> >> or C<:::>. It's a
-zero-width pattern similar to C<(*SKIP)>, except that when backtracked
-into on failure it causes the match to fail outright. No further attempts
-to find a valid match by advancing the start pointer will occur again.
-For example,
-
- 'aaabaaab' =~ /a+b?(*COMMIT)(?{print "$&\n"; $count++})(*FAIL)/;
- print "Count=$count\n";
-
-outputs
-
- aaab
- Count=1
-
-In other words, once the C<(*COMMIT)> has been entered, and if the pattern
-does not match, the regex engine will not try any further matching on the
-rest of the string.
-
-=item C<(*FAIL)> C<(*F)>
-X<(*FAIL)> X<(*F)>
-
-This pattern matches nothing and always fails. It can be used to force the
-engine to backtrack. It is equivalent to C<(?!)>, but easier to read. In
-fact, C<(?!)> gets optimised into C<(*FAIL)> internally.
-
-It is probably useful only when combined with C<(?{})> or C<(??{})>.
-
-=item C<(*ACCEPT)>
-X<(*ACCEPT)>
-
-B<WARNING:> This feature is highly experimental. It is not recommended
-for production code.
-
-This pattern matches nothing and causes the end of successful matching at
-the point at which the C<(*ACCEPT)> pattern was encountered, regardless of
-whether there is actually more to match in the string. When inside of a
-nested pattern, such as recursion, or in a subpattern dynamically generated
-via C<(??{})>, only the innermost pattern is ended immediately.
-
-If the C<(*ACCEPT)> is inside of capturing groups then the groups are
-marked as ended at the point at which the C<(*ACCEPT)> was encountered.
-For instance:
-
- 'AB' =~ /(A (A|B(*ACCEPT)|C) D)(E)/x;
-
-will match, and C<$1> will be C<AB> and C<$2> will be C<B>, C<$3> will not
-be set. If another branch in the inner parentheses was matched, such as in the
-string 'ACDE', then the C<D> and C<E> would have to be matched as well.
-
-=back
-
-=back
-
-=head2 Backtracking
-X<backtrack> X<backtracking>
-
-NOTE: This section presents an abstract approximation of regular
-expression behavior. For a more rigorous (and complicated) view of
-the rules involved in selecting a match among possible alternatives,
-see L<Combining RE Pieces>.
-
-A fundamental feature of regular expression matching involves the
-notion called I<backtracking>, which is currently used (when needed)
-by all regular non-possessive expression quantifiers, namely C<*>, C<*?>, C<+>,
-C<+?>, C<{n,m}>, and C<{n,m}?>. Backtracking is often optimized
-internally, but the general principle outlined here is valid.
-
-For a regular expression to match, the I<entire> regular expression must
-match, not just part of it. So if the beginning of a pattern containing a
-quantifier succeeds in a way that causes later parts in the pattern to
-fail, the matching engine backs up and recalculates the beginning
-part--that's why it's called backtracking.
-
-Here is an example of backtracking: Let's say you want to find the
-word following "foo" in the string "Food is on the foo table.":
-
- $_ = "Food is on the foo table.";
- if ( /\b(foo)\s+(\w+)/i ) {
- print "$2 follows $1.\n";
- }
-
-When the match runs, the first part of the regular expression (C<\b(foo)>)
-finds a possible match right at the beginning of the string, and loads up
-$1 with "Foo". However, as soon as the matching engine sees that there's
-no whitespace following the "Foo" that it had saved in $1, it realizes its
-mistake and starts over again one character after where it had the
-tentative match. This time it goes all the way until the next occurrence
-of "foo". The complete regular expression matches this time, and you get
-the expected output of "table follows foo."
-
-Sometimes minimal matching can help a lot. Imagine you'd like to match
-everything between "foo" and "bar". Initially, you write something
-like this:
-
- $_ = "The food is under the bar in the barn.";
- if ( /foo(.*)bar/ ) {
- print "got <$1>\n";
- }
-
-Which perhaps unexpectedly yields:
-
- got <d is under the bar in the >
-
-That's because C<.*> was greedy, so you get everything between the
-I<first> "foo" and the I<last> "bar". Here it's more effective
-to use minimal matching to make sure you get the text between a "foo"
-and the first "bar" thereafter.
-
- if ( /foo(.*?)bar/ ) { print "got <$1>\n" }
- got <d is under the >
-
-Here's another example. Let's say you'd like to match a number at the end
-of a string, and you also want to keep the preceding part of the match.
-So you write this:
-
- $_ = "I have 2 numbers: 53147";
- if ( /(.*)(\d*)/ ) { # Wrong!
- print "Beginning is <$1>, number is <$2>.\n";
- }
-
-That won't work at all, because C<.*> was greedy and gobbled up the
-whole string. As C<\d*> can match on an empty string the complete
-regular expression matched successfully.
-
- Beginning is <I have 2 numbers: 53147>, number is <>.
-
-Here are some variants, most of which don't work:
-
- $_ = "I have 2 numbers: 53147";
- @pats = qw{
- (.*)(\d*)
- (.*)(\d+)
- (.*?)(\d*)
- (.*?)(\d+)
- (.*)(\d+)$
- (.*?)(\d+)$
- (.*)\b(\d+)$
- (.*\D)(\d+)$
- };
-
- for $pat (@pats) {
- printf "%-12s ", $pat;
- if ( /$pat/ ) {
- print "<$1> <$2>\n";
- } else {
- print "FAIL\n";
- }
- }
-
-That will print out:
-
- (.*)(\d*) <I have 2 numbers: 53147> <>
- (.*)(\d+) <I have 2 numbers: 5314> <7>
- (.*?)(\d*) <> <>
- (.*?)(\d+) <I have > <2>
- (.*)(\d+)$ <I have 2 numbers: 5314> <7>
- (.*?)(\d+)$ <I have 2 numbers: > <53147>
- (.*)\b(\d+)$ <I have 2 numbers: > <53147>
- (.*\D)(\d+)$ <I have 2 numbers: > <53147>
-
-As you see, this can be a bit tricky. It's important to realize that a
-regular expression is merely a set of assertions that gives a definition
-of success. There may be 0, 1, or several different ways that the
-definition might succeed against a particular string. And if there are
-multiple ways it might succeed, you need to understand backtracking to
-know which variety of success you will achieve.
-
-When using look-ahead assertions and negations, this can all get even
-trickier. Imagine you'd like to find a sequence of non-digits not
-followed by "123". You might try to write that as
-
- $_ = "ABC123";
- if ( /^\D*(?!123)/ ) { # Wrong!
- print "Yup, no 123 in $_\n";
- }
-
-But that isn't going to match; at least, not the way you're hoping. It
-claims that there is no 123 in the string. Here's a clearer picture of
-why that pattern matches, contrary to popular expectations:
-
- $x = 'ABC123';
- $y = 'ABC445';
-
- print "1: got $1\n" if $x =~ /^(ABC)(?!123)/;
- print "2: got $1\n" if $y =~ /^(ABC)(?!123)/;
-
- print "3: got $1\n" if $x =~ /^(\D*)(?!123)/;
- print "4: got $1\n" if $y =~ /^(\D*)(?!123)/;
-
-This prints
-
- 2: got ABC
- 3: got AB
- 4: got ABC
-
-You might have expected test 3 to fail because it seems to a more
-general purpose version of test 1. The important difference between
-them is that test 3 contains a quantifier (C<\D*>) and so can use
-backtracking, whereas test 1 will not. What's happening is
-that you've asked "Is it true that at the start of $x, following 0 or more
-non-digits, you have something that's not 123?" If the pattern matcher had
-let C<\D*> expand to "ABC", this would have caused the whole pattern to
-fail.
-
-The search engine will initially match C<\D*> with "ABC". Then it will
-try to match C<(?!123)> with "123", which fails. But because
-a quantifier (C<\D*>) has been used in the regular expression, the
-search engine can backtrack and retry the match differently
-in the hope of matching the complete regular expression.
-
-The pattern really, I<really> wants to succeed, so it uses the
-standard pattern back-off-and-retry and lets C<\D*> expand to just "AB" this
-time. Now there's indeed something following "AB" that is not
-"123". It's "C123", which suffices.
-
-We can deal with this by using both an assertion and a negation.
-We'll say that the first part in $1 must be followed both by a digit
-and by something that's not "123". Remember that the look-aheads
-are zero-width expressions--they only look, but don't consume any
-of the string in their match. So rewriting this way produces what
-you'd expect; that is, case 5 will fail, but case 6 succeeds:
-
- print "5: got $1\n" if $x =~ /^(\D*)(?=\d)(?!123)/;
- print "6: got $1\n" if $y =~ /^(\D*)(?=\d)(?!123)/;
-
- 6: got ABC
-
-In other words, the two zero-width assertions next to each other work as though
-they're ANDed together, just as you'd use any built-in assertions: C</^$/>
-matches only if you're at the beginning of the line AND the end of the
-line simultaneously. The deeper underlying truth is that juxtaposition in
-regular expressions always means AND, except when you write an explicit OR
-using the vertical bar. C</ab/> means match "a" AND (then) match "b",
-although the attempted matches are made at different positions because "a"
-is not a zero-width assertion, but a one-width assertion.
-
-B<WARNING>: Particularly complicated regular expressions can take
-exponential time to solve because of the immense number of possible
-ways they can use backtracking to try for a match. For example, without
-internal optimizations done by the regular expression engine, this will
-take a painfully long time to run:
-
- 'aaaaaaaaaaaa' =~ /((a{0,5}){0,5})*[c]/
-
-And if you used C<*>'s in the internal groups instead of limiting them
-to 0 through 5 matches, then it would take forever--or until you ran
-out of stack space. Moreover, these internal optimizations are not
-always applicable. For example, if you put C<{0,5}> instead of C<*>
-on the external group, no current optimization is applicable, and the
-match takes a long time to finish.
-
-A powerful tool for optimizing such beasts is what is known as an
-"independent group",
-which does not backtrack (see L</C<< (?>pattern) >>>). Note also that
-zero-length look-ahead/look-behind assertions will not backtrack to make
-the tail match, since they are in "logical" context: only
-whether they match is considered relevant. For an example
-where side-effects of look-ahead I<might> have influenced the
-following match, see L</C<< (?>pattern) >>>.
-
-=head2 Version 8 Regular Expressions
-X<regular expression, version 8> X<regex, version 8> X<regexp, version 8>
-
-In case you're not familiar with the "regular" Version 8 regex
-routines, here are the pattern-matching rules not described above.
-
-Any single character matches itself, unless it is a I<metacharacter>
-with a special meaning described here or above. You can cause
-characters that normally function as metacharacters to be interpreted
-literally by prefixing them with a "\" (e.g., "\." matches a ".", not any
-character; "\\" matches a "\"). This escape mechanism is also required
-for the character used as the pattern delimiter.
-
-A series of characters matches that series of characters in the target
-string, so the pattern C<blurfl> would match "blurfl" in the target
-string.
-
-You can specify a character class, by enclosing a list of characters
-in C<[]>, which will match any character from the list. If the
-first character after the "[" is "^", the class matches any character not
-in the list. Within a list, the "-" character specifies a
-range, so that C<a-z> represents all characters between "a" and "z",
-inclusive. If you want either "-" or "]" itself to be a member of a
-class, put it at the start of the list (possibly after a "^"), or
-escape it with a backslash. "-" is also taken literally when it is
-at the end of the list, just before the closing "]". (The
-following all specify the same class of three characters: C<[-az]>,
-C<[az-]>, and C<[a\-z]>. All are different from C<[a-z]>, which
-specifies a class containing twenty-six characters, even on EBCDIC-based
-character sets.) Also, if you try to use the character
-classes C<\w>, C<\W>, C<\s>, C<\S>, C<\d>, or C<\D> as endpoints of
-a range, the "-" is understood literally.
-
-Note also that the whole range idea is rather unportable between
-character sets--and even within character sets they may cause results
-you probably didn't expect. A sound principle is to use only ranges
-that begin from and end at either alphabetics of equal case ([a-e],
-[A-E]), or digits ([0-9]). Anything else is unsafe. If in doubt,
-spell out the character sets in full.
-
-Characters may be specified using a metacharacter syntax much like that
-used in C: "\n" matches a newline, "\t" a tab, "\r" a carriage return,
-"\f" a form feed, etc. More generally, \I<nnn>, where I<nnn> is a string
-of three octal digits, matches the character whose coded character set value
-is I<nnn>. Similarly, \xI<nn>, where I<nn> are hexadecimal digits,
-matches the character whose ordinal is I<nn>. The expression \cI<x>
-matches the character control-I<x>. Finally, the "." metacharacter
-matches any character except "\n" (unless you use C</s>).
-
-You can specify a series of alternatives for a pattern using "|" to
-separate them, so that C<fee|fie|foe> will match any of "fee", "fie",
-or "foe" in the target string (as would C<f(e|i|o)e>). The
-first alternative includes everything from the last pattern delimiter
-("(", "(?:", etc. or the beginning of the pattern) up to the first "|", and
-the last alternative contains everything from the last "|" to the next
-closing pattern delimiter. That's why it's common practice to include
-alternatives in parentheses: to minimize confusion about where they
-start and end.
-
-Alternatives are tried from left to right, so the first
-alternative found for which the entire expression matches, is the one that
-is chosen. This means that alternatives are not necessarily greedy. For
-example: when matching C<foo|foot> against "barefoot", only the "foo"
-part will match, as that is the first alternative tried, and it successfully
-matches the target string. (This might not seem important, but it is
-important when you are capturing matched text using parentheses.)
-
-Also remember that "|" is interpreted as a literal within square brackets,
-so if you write C<[fee|fie|foe]> you're really only matching C<[feio|]>.
-
-Within a pattern, you may designate subpatterns for later reference
-by enclosing them in parentheses, and you may refer back to the
-I<n>th subpattern later in the pattern using the metacharacter
-\I<n> or \gI<n>. Subpatterns are numbered based on the left to right order
-of their opening parenthesis. A backreference matches whatever
-actually matched the subpattern in the string being examined, not
-the rules for that subpattern. Therefore, C<(0|0x)\d*\s\g1\d*> will
-match "0x1234 0x4321", but not "0x1234 01234", because subpattern
-1 matched "0x", even though the rule C<0|0x> could potentially match
-the leading 0 in the second number.
-
-=head2 Warning on \1 Instead of $1
-
-Some people get too used to writing things like:
-
- $pattern =~ s/(\W)/\\\1/g;
-
-This is grandfathered (for \1 to \9) for the RHS of a substitute to avoid
-shocking the
-B<sed> addicts, but it's a dirty habit to get into. That's because in
-PerlThink, the righthand side of an C<s///> is a double-quoted string. C<\1> in
-the usual double-quoted string means a control-A. The customary Unix
-meaning of C<\1> is kludged in for C<s///>. However, if you get into the habit
-of doing that, you get yourself into trouble if you then add an C</e>
-modifier.
-
- s/(\d+)/ \1 + 1 /eg; # causes warning under -w
-
-Or if you try to do
-
- s/(\d+)/\1000/;
-
-You can't disambiguate that by saying C<\{1}000>, whereas you can fix it with
-C<${1}000>. The operation of interpolation should not be confused
-with the operation of matching a backreference. Certainly they mean two
-different things on the I<left> side of the C<s///>.
-
-=head2 Repeated Patterns Matching a Zero-length Substring
-
-B<WARNING>: Difficult material (and prose) ahead. This section needs a rewrite.
-
-Regular expressions provide a terse and powerful programming language. As
-with most other power tools, power comes together with the ability
-to wreak havoc.
-
-A common abuse of this power stems from the ability to make infinite
-loops using regular expressions, with something as innocuous as:
-
- 'foo' =~ m{ ( o? )* }x;
-
-The C<o?> matches at the beginning of C<'foo'>, and since the position
-in the string is not moved by the match, C<o?> would match again and again
-because of the C<*> quantifier. Another common way to create a similar cycle
-is with the looping modifier C<//g>:
-
- @matches = ( 'foo' =~ m{ o? }xg );
-
-or
-
- print "match: <$&>\n" while 'foo' =~ m{ o? }xg;
-
-or the loop implied by split().
-
-However, long experience has shown that many programming tasks may
-be significantly simplified by using repeated subexpressions that
-may match zero-length substrings. Here's a simple example being:
-
- @chars = split //, $string; # // is not magic in split
- ($whitewashed = $string) =~ s/()/ /g; # parens avoid magic s// /
-
-Thus Perl allows such constructs, by I<forcefully breaking
-the infinite loop>. The rules for this are different for lower-level
-loops given by the greedy quantifiers C<*+{}>, and for higher-level
-ones like the C</g> modifier or split() operator.
-
-The lower-level loops are I<interrupted> (that is, the loop is
-broken) when Perl detects that a repeated expression matched a
-zero-length substring. Thus
-
- m{ (?: NON_ZERO_LENGTH | ZERO_LENGTH )* }x;
-
-is made equivalent to
-
- m{ (?: NON_ZERO_LENGTH )* (?: ZERO_LENGTH )? }x;
-
-For example, this program
-
- #!perl -l
- "aaaaab" =~ /
- (?:
- a # non-zero
- | # or
- (?{print "hello"}) # print hello whenever this
- # branch is tried
- (?=(b)) # zero-width assertion
- )* # any number of times
- /x;
- print $&;
- print $1;
-
-prints
-
- hello
- aaaaa
- b
-
-Notice that "hello" is only printed once, as when Perl sees that the sixth
-iteration of the outermost C<(?:)*> matches a zero-length string, it stops
-the C<*>.
-
-The higher-level loops preserve an additional state between iterations:
-whether the last match was zero-length. To break the loop, the following
-match after a zero-length match is prohibited to have a length of zero.
-This prohibition interacts with backtracking (see L<"Backtracking">),
-and so the I<second best> match is chosen if the I<best> match is of
-zero length.
-
-For example:
-
- $_ = 'bar';
- s/\w??/<$&>/g;
-
-results in C<< <><b><><a><><r><> >>. At each position of the string the best
-match given by non-greedy C<??> is the zero-length match, and the I<second
-best> match is what is matched by C<\w>. Thus zero-length matches
-alternate with one-character-long matches.
-
-Similarly, for repeated C<m/()/g> the second-best match is the match at the
-position one notch further in the string.
-
-The additional state of being I<matched with zero-length> is associated with
-the matched string, and is reset by each assignment to pos().
-Zero-length matches at the end of the previous match are ignored
-during C<split>.
-
-=head2 Combining RE Pieces
-
-Each of the elementary pieces of regular expressions which were described
-before (such as C<ab> or C<\Z>) could match at most one substring
-at the given position of the input string. However, in a typical regular
-expression these elementary pieces are combined into more complicated
-patterns using combining operators C<ST>, C<S|T>, C<S*> etc.
-(in these examples C<S> and C<T> are regular subexpressions).
-
-Such combinations can include alternatives, leading to a problem of choice:
-if we match a regular expression C<a|ab> against C<"abc">, will it match
-substring C<"a"> or C<"ab">? One way to describe which substring is
-actually matched is the concept of backtracking (see L<"Backtracking">).
-However, this description is too low-level and makes you think
-in terms of a particular implementation.
-
-Another description starts with notions of "better"/"worse". All the
-substrings which may be matched by the given regular expression can be
-sorted from the "best" match to the "worst" match, and it is the "best"
-match which is chosen. This substitutes the question of "what is chosen?"
-by the question of "which matches are better, and which are worse?".
-
-Again, for elementary pieces there is no such question, since at most
-one match at a given position is possible. This section describes the
-notion of better/worse for combining operators. In the description
-below C<S> and C<T> are regular subexpressions.
-
-=over 4
-
-=item C<ST>
-
-Consider two possible matches, C<AB> and C<A'B'>, C<A> and C<A'> are
-substrings which can be matched by C<S>, C<B> and C<B'> are substrings
-which can be matched by C<T>.
-
-If C<A> is a better match for C<S> than C<A'>, C<AB> is a better
-match than C<A'B'>.
-
-If C<A> and C<A'> coincide: C<AB> is a better match than C<AB'> if
-C<B> is a better match for C<T> than C<B'>.
-
-=item C<S|T>
-
-When C<S> can match, it is a better match than when only C<T> can match.
-
-Ordering of two matches for C<S> is the same as for C<S>. Similar for
-two matches for C<T>.
-
-=item C<S{REPEAT_COUNT}>
-
-Matches as C<SSS...S> (repeated as many times as necessary).
-
-=item C<S{min,max}>
-
-Matches as C<S{max}|S{max-1}|...|S{min+1}|S{min}>.
-
-=item C<S{min,max}?>
-
-Matches as C<S{min}|S{min+1}|...|S{max-1}|S{max}>.
-
-=item C<S?>, C<S*>, C<S+>
-
-Same as C<S{0,1}>, C<S{0,BIG_NUMBER}>, C<S{1,BIG_NUMBER}> respectively.
-
-=item C<S??>, C<S*?>, C<S+?>
-
-Same as C<S{0,1}?>, C<S{0,BIG_NUMBER}?>, C<S{1,BIG_NUMBER}?> respectively.
-
-=item C<< (?>S) >>
-
-Matches the best match for C<S> and only that.
-
-=item C<(?=S)>, C<(?<=S)>
-
-Only the best match for C<S> is considered. (This is important only if
-C<S> has capturing parentheses, and backreferences are used somewhere
-else in the whole regular expression.)
-
-=item C<(?!S)>, C<(?<!S)>
-
-For this grouping operator there is no need to describe the ordering, since
-only whether or not C<S> can match is important.
-
-=item C<(??{ EXPR })>, C<(?PARNO)>
-
-The ordering is the same as for the regular expression which is
-the result of EXPR, or the pattern contained by capture group PARNO.
-
-=item C<(?(condition)yes-pattern|no-pattern)>
-
-Recall that which of C<yes-pattern> or C<no-pattern> actually matches is
-already determined. The ordering of the matches is the same as for the
-chosen subexpression.
-
-=back
-
-The above recipes describe the ordering of matches I<at a given position>.
-One more rule is needed to understand how a match is determined for the
-whole regular expression: a match at an earlier position is always better
-than a match at a later position.
-
-=head2 Creating Custom RE Engines
-
-As of Perl 5.10.0, one can create custom regular expression engines. This
-is not for the faint of heart, as they have to plug in at the C level. See
-L<perlreapi> for more details.
-
-As an alternative, overloaded constants (see L<overload>) provide a simple
-way to extend the functionality of the RE engine, by substituting one
-pattern for another.
-
-Suppose that we want to enable a new RE escape-sequence C<\Y|> which
-matches at a boundary between whitespace characters and non-whitespace
-characters. Note that C<(?=\S)(?<!\S)|(?!\S)(?<=\S)> matches exactly
-at these positions, so we want to have each C<\Y|> in the place of the
-more complicated version. We can create a module C<customre> to do
-this:
-
- package customre;
- use overload;
-
- sub import {
- shift;
- die "No argument to customre::import allowed" if @_;
- overload::constant 'qr' => \&convert;
- }
-
- sub invalid { die "/$_[0]/: invalid escape '\\$_[1]'"}
-
- # We must also take care of not escaping the legitimate \\Y|
- # sequence, hence the presence of '\\' in the conversion rules.
- my %rules = ( '\\' => '\\\\',
- 'Y|' => qr/(?=\S)(?<!\S)|(?!\S)(?<=\S)/ );
- sub convert {
- my $re = shift;
- $re =~ s{
- \\ ( \\ | Y . )
- }
- { $rules{$1} or invalid($re,$1) }sgex;
- return $re;
- }
-
-Now C<use customre> enables the new escape in constant regular
-expressions, i.e., those without any runtime variable interpolations.
-As documented in L<overload>, this conversion will work only over
-literal parts of regular expressions. For C<\Y|$re\Y|> the variable
-part of this regular expression needs to be converted explicitly
-(but only if the special meaning of C<\Y|> should be enabled inside $re):
-
- use customre;
- $re = <>;
- chomp $re;
- $re = customre::convert $re;
- /\Y|$re\Y|/;
-
-=head2 PCRE/Python Support
-
-As of Perl 5.10.0, Perl supports several Python/PCRE-specific extensions
-to the regex syntax. While Perl programmers are encouraged to use the
-Perl-specific syntax, the following are also accepted:
-
-=over 4
-
-=item C<< (?PE<lt>NAMEE<gt>pattern) >>
-
-Define a named capture group. Equivalent to C<< (?<NAME>pattern) >>.
-
-=item C<< (?P=NAME) >>
-
-Backreference to a named capture group. Equivalent to C<< \g{NAME} >>.
-
-=item C<< (?P>NAME) >>
-
-Subroutine call to a named capture group. Equivalent to C<< (?&NAME) >>.
-
-=back
-
-=head1 BUGS
-
-Many regular expression constructs don't work on EBCDIC platforms.
-
-There are a number of issues with regard to case-insensitive matching
-in Unicode rules. See C<i> under L</Modifiers> above.
-
-This document varies from difficult to understand to completely
-and utterly opaque. The wandering prose riddled with jargon is
-hard to fathom in several places.
-
-This document needs a rewrite that separates the tutorial content
-from the reference content.
-
-=head1 SEE ALSO
-
-L<perlrequick>.
-
-L<perlretut>.
-
-L<perlop/"Regexp Quote-Like Operators">.
-
-L<perlop/"Gory details of parsing quoted constructs">.
-
-L<perlfaq6>.
-
-L<perlfunc/pos>.
-
-L<perllocale>.
-
-L<perlebcdic>.
-
-I<Mastering Regular Expressions> by Jeffrey Friedl, published
-by O'Reilly and Associates.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlreapi.pod b/Master/tlpkg/tlperl/lib/pods/perlreapi.pod
deleted file mode 100644
index 5e456208684..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlreapi.pod
+++ /dev/null
@@ -1,706 +0,0 @@
-=head1 NAME
-
-perlreapi - perl regular expression plugin interface
-
-=head1 DESCRIPTION
-
-As of Perl 5.9.5 there is a new interface for plugging and using other
-regular expression engines than the default one.
-
-Each engine is supposed to provide access to a constant structure of the
-following format:
-
- typedef struct regexp_engine {
- REGEXP* (*comp) (pTHX_ const SV * const pattern, const U32 flags);
- I32 (*exec) (pTHX_ REGEXP * const rx, char* stringarg, char* strend,
- char* strbeg, I32 minend, SV* screamer,
- void* data, U32 flags);
- char* (*intuit) (pTHX_ REGEXP * const rx, SV *sv, char *strpos,
- char *strend, U32 flags,
- struct re_scream_pos_data_s *data);
- SV* (*checkstr) (pTHX_ REGEXP * const rx);
- void (*free) (pTHX_ REGEXP * const rx);
- void (*numbered_buff_FETCH) (pTHX_ REGEXP * const rx, const I32 paren,
- SV * const sv);
- void (*numbered_buff_STORE) (pTHX_ REGEXP * const rx, const I32 paren,
- SV const * const value);
- I32 (*numbered_buff_LENGTH) (pTHX_ REGEXP * const rx, const SV * const sv,
- const I32 paren);
- SV* (*named_buff) (pTHX_ REGEXP * const rx, SV * const key,
- SV * const value, U32 flags);
- SV* (*named_buff_iter) (pTHX_ REGEXP * const rx, const SV * const lastkey,
- const U32 flags);
- SV* (*qr_package)(pTHX_ REGEXP * const rx);
- #ifdef USE_ITHREADS
- void* (*dupe) (pTHX_ REGEXP * const rx, CLONE_PARAMS *param);
- #endif
-
-When a regexp is compiled, its C<engine> field is then set to point at
-the appropriate structure, so that when it needs to be used Perl can find
-the right routines to do so.
-
-In order to install a new regexp handler, C<$^H{regcomp}> is set
-to an integer which (when casted appropriately) resolves to one of these
-structures. When compiling, the C<comp> method is executed, and the
-resulting regexp structure's engine field is expected to point back at
-the same structure.
-
-The pTHX_ symbol in the definition is a macro used by perl under threading
-to provide an extra argument to the routine holding a pointer back to
-the interpreter that is executing the regexp. So under threading all
-routines get an extra argument.
-
-=head1 Callbacks
-
-=head2 comp
-
- REGEXP* comp(pTHX_ const SV * const pattern, const U32 flags);
-
-Compile the pattern stored in C<pattern> using the given C<flags> and
-return a pointer to a prepared C<REGEXP> structure that can perform
-the match. See L</The REGEXP structure> below for an explanation of
-the individual fields in the REGEXP struct.
-
-The C<pattern> parameter is the scalar that was used as the
-pattern. previous versions of perl would pass two C<char*> indicating
-the start and end of the stringified pattern, the following snippet can
-be used to get the old parameters:
-
- STRLEN plen;
- char* exp = SvPV(pattern, plen);
- char* xend = exp + plen;
-
-Since any scalar can be passed as a pattern it's possible to implement
-an engine that does something with an array (C<< "ook" =~ [ qw/ eek
-hlagh / ] >>) or with the non-stringified form of a compiled regular
-expression (C<< "ook" =~ qr/eek/ >>). perl's own engine will always
-stringify everything using the snippet above but that doesn't mean
-other engines have to.
-
-The C<flags> parameter is a bitfield which indicates which of the
-C<msixp> flags the regex was compiled with. It also contains
-additional info such as whether C<use locale> is in effect.
-
-The C<eogc> flags are stripped out before being passed to the comp
-routine. The regex engine does not need to know whether any of these
-are set as those flags should only affect what perl does with the
-pattern and its match variables, not how it gets compiled and
-executed.
-
-By the time the comp callback is called, some of these flags have
-already had effect (noted below where applicable). However most of
-their effect occurs after the comp callback has run in routines that
-read the C<< rx->extflags >> field which it populates.
-
-In general the flags should be preserved in C<< rx->extflags >> after
-compilation, although the regex engine might want to add or delete
-some of them to invoke or disable some special behavior in perl. The
-flags along with any special behavior they cause are documented below:
-
-The pattern modifiers:
-
-=over 4
-
-=item C</m> - RXf_PMf_MULTILINE
-
-If this is in C<< rx->extflags >> it will be passed to
-C<Perl_fbm_instr> by C<pp_split> which will treat the subject string
-as a multi-line string.
-
-=item C</s> - RXf_PMf_SINGLELINE
-
-=item C</i> - RXf_PMf_FOLD
-
-=item C</x> - RXf_PMf_EXTENDED
-
-If present on a regex C<#> comments will be handled differently by the
-tokenizer in some cases.
-
-TODO: Document those cases.
-
-=item C</p> - RXf_PMf_KEEPCOPY
-
-TODO: Document this
-
-=item Character set
-
-The character set semantics are determined by an enum that is contained
-in this field. This is still experimental and subject to change, but
-the current interface returns the rules by use of the in-line function
-C<get_regex_charset(const U32 flags)>. The only currently documented
-value returned from it is REGEX_LOCALE_CHARSET, which is set if
-C<use locale> is in effect. If present in C<< rx->extflags >>,
-C<split> will use the locale dependent definition of whitespace
-when RXf_SKIPWHITE or RXf_WHITE is in effect. ASCII whitespace
-is defined as per L<isSPACE|perlapi/isSPACE>, and by the internal
-macros C<is_utf8_space> under UTF-8, and C<isSPACE_LC> under C<use
-locale>.
-
-=back
-
-Additional flags:
-
-=over 4
-
-=item RXf_UTF8
-
-Set if the pattern is L<SvUTF8()|perlapi/SvUTF8>, set by Perl_pmruntime.
-
-A regex engine may want to set or disable this flag during
-compilation. The perl engine for instance may upgrade non-UTF-8
-strings to UTF-8 if the pattern includes constructs such as C<\x{...}>
-that can only match Unicode values.
-
-=item RXf_SPLIT
-
-If C<split> is invoked as C<split ' '> or with no arguments (which
-really means C<split(' ', $_)>, see L<split|perlfunc/split>), perl will
-set this flag. The regex engine can then check for it and set the
-SKIPWHITE and WHITE extflags. To do this the perl engine does:
-
- if (flags & RXf_SPLIT && r->prelen == 1 && r->precomp[0] == ' ')
- r->extflags |= (RXf_SKIPWHITE|RXf_WHITE);
-
-=back
-
-These flags can be set during compilation to enable optimizations in
-the C<split> operator.
-
-=over 4
-
-=item RXf_SKIPWHITE
-
-If the flag is present in C<< rx->extflags >> C<split> will delete
-whitespace from the start of the subject string before it's operated
-on. What is considered whitespace depends on whether the subject is a
-UTF-8 string and whether the C<RXf_PMf_LOCALE> flag is set.
-
-If RXf_WHITE is set in addition to this flag C<split> will behave like
-C<split " "> under the perl engine.
-
-=item RXf_START_ONLY
-
-Tells the split operator to split the target string on newlines
-(C<\n>) without invoking the regex engine.
-
-Perl's engine sets this if the pattern is C</^/> (C<plen == 1 && *exp
-== '^'>), even under C</^/s>, see L<split|perlfunc>. Of course a
-different regex engine might want to use the same optimizations
-with a different syntax.
-
-=item RXf_WHITE
-
-Tells the split operator to split the target string on whitespace
-without invoking the regex engine. The definition of whitespace varies
-depending on whether the target string is a UTF-8 string and on
-whether RXf_PMf_LOCALE is set.
-
-Perl's engine sets this flag if the pattern is C<\s+>.
-
-=item RXf_NULL
-
-Tells the split operator to split the target string on
-characters. The definition of character varies depending on whether
-the target string is a UTF-8 string.
-
-Perl's engine sets this flag on empty patterns, this optimization
-makes C<split //> much faster than it would otherwise be. It's even
-faster than C<unpack>.
-
-=back
-
-=head2 exec
-
- I32 exec(pTHX_ REGEXP * const rx,
- char *stringarg, char* strend, char* strbeg,
- I32 minend, SV* screamer,
- void* data, U32 flags);
-
-Execute a regexp.
-
-=head2 intuit
-
- char* intuit(pTHX_ REGEXP * const rx,
- SV *sv, char *strpos, char *strend,
- const U32 flags, struct re_scream_pos_data_s *data);
-
-Find the start position where a regex match should be attempted,
-or possibly whether the regex engine should not be run because the
-pattern can't match. This is called as appropriate by the core
-depending on the values of the extflags member of the regexp
-structure.
-
-=head2 checkstr
-
- SV* checkstr(pTHX_ REGEXP * const rx);
-
-Return a SV containing a string that must appear in the pattern. Used
-by C<split> for optimising matches.
-
-=head2 free
-
- void free(pTHX_ REGEXP * const rx);
-
-Called by perl when it is freeing a regexp pattern so that the engine
-can release any resources pointed to by the C<pprivate> member of the
-regexp structure. This is only responsible for freeing private data;
-perl will handle releasing anything else contained in the regexp structure.
-
-=head2 Numbered capture callbacks
-
-Called to get/set the value of C<$`>, C<$'>, C<$&> and their named
-equivalents, ${^PREMATCH}, ${^POSTMATCH} and $^{MATCH}, as well as the
-numbered capture groups (C<$1>, C<$2>, ...).
-
-The C<paren> parameter will be C<-2> for C<$`>, C<-1> for C<$'>, C<0>
-for C<$&>, C<1> for C<$1> and so forth.
-
-The names have been chosen by analogy with L<Tie::Scalar> methods
-names with an additional B<LENGTH> callback for efficiency. However
-named capture variables are currently not tied internally but
-implemented via magic.
-
-=head3 numbered_buff_FETCH
-
- void numbered_buff_FETCH(pTHX_ REGEXP * const rx, const I32 paren,
- SV * const sv);
-
-Fetch a specified numbered capture. C<sv> should be set to the scalar
-to return, the scalar is passed as an argument rather than being
-returned from the function because when it's called perl already has a
-scalar to store the value, creating another one would be
-redundant. The scalar can be set with C<sv_setsv>, C<sv_setpvn> and
-friends, see L<perlapi>.
-
-This callback is where perl untaints its own capture variables under
-taint mode (see L<perlsec>). See the C<Perl_reg_numbered_buff_fetch>
-function in F<regcomp.c> for how to untaint capture variables if
-that's something you'd like your engine to do as well.
-
-=head3 numbered_buff_STORE
-
- void (*numbered_buff_STORE) (pTHX_ REGEXP * const rx, const I32 paren,
- SV const * const value);
-
-Set the value of a numbered capture variable. C<value> is the scalar
-that is to be used as the new value. It's up to the engine to make
-sure this is used as the new value (or reject it).
-
-Example:
-
- if ("ook" =~ /(o*)/) {
- # 'paren' will be '1' and 'value' will be 'ee'
- $1 =~ tr/o/e/;
- }
-
-Perl's own engine will croak on any attempt to modify the capture
-variables, to do this in another engine use the following callback
-(copied from C<Perl_reg_numbered_buff_store>):
-
- void
- Example_reg_numbered_buff_store(pTHX_ REGEXP * const rx, const I32 paren,
- SV const * const value)
- {
- PERL_UNUSED_ARG(rx);
- PERL_UNUSED_ARG(paren);
- PERL_UNUSED_ARG(value);
-
- if (!PL_localizing)
- Perl_croak(aTHX_ PL_no_modify);
- }
-
-Actually perl will not I<always> croak in a statement that looks
-like it would modify a numbered capture variable. This is because the
-STORE callback will not be called if perl can determine that it
-doesn't have to modify the value. This is exactly how tied variables
-behave in the same situation:
-
- package CaptureVar;
- use base 'Tie::Scalar';
-
- sub TIESCALAR { bless [] }
- sub FETCH { undef }
- sub STORE { die "This doesn't get called" }
-
- package main;
-
- tie my $sv => "CaptureVar";
- $sv =~ y/a/b/;
-
-Because C<$sv> is C<undef> when the C<y///> operator is applied to it
-the transliteration won't actually execute and the program won't
-C<die>. This is different to how 5.8 and earlier versions behaved
-since the capture variables were READONLY variables then, now they'll
-just die when assigned to in the default engine.
-
-=head3 numbered_buff_LENGTH
-
- I32 numbered_buff_LENGTH (pTHX_ REGEXP * const rx, const SV * const sv,
- const I32 paren);
-
-Get the C<length> of a capture variable. There's a special callback
-for this so that perl doesn't have to do a FETCH and run C<length> on
-the result, since the length is (in perl's case) known from an offset
-stored in C<< rx->offs >> this is much more efficient:
-
- I32 s1 = rx->offs[paren].start;
- I32 s2 = rx->offs[paren].end;
- I32 len = t1 - s1;
-
-This is a little bit more complex in the case of UTF-8, see what
-C<Perl_reg_numbered_buff_length> does with
-L<is_utf8_string_loclen|perlapi/is_utf8_string_loclen>.
-
-=head2 Named capture callbacks
-
-Called to get/set the value of C<%+> and C<%-> as well as by some
-utility functions in L<re>.
-
-There are two callbacks, C<named_buff> is called in all the cases the
-FETCH, STORE, DELETE, CLEAR, EXISTS and SCALAR L<Tie::Hash> callbacks
-would be on changes to C<%+> and C<%-> and C<named_buff_iter> in the
-same cases as FIRSTKEY and NEXTKEY.
-
-The C<flags> parameter can be used to determine which of these
-operations the callbacks should respond to, the following flags are
-currently defined:
-
-Which L<Tie::Hash> operation is being performed from the Perl level on
-C<%+> or C<%+>, if any:
-
- RXapif_FETCH
- RXapif_STORE
- RXapif_DELETE
- RXapif_CLEAR
- RXapif_EXISTS
- RXapif_SCALAR
- RXapif_FIRSTKEY
- RXapif_NEXTKEY
-
-Whether C<%+> or C<%-> is being operated on, if any.
-
- RXapif_ONE /* %+ */
- RXapif_ALL /* %- */
-
-Whether this is being called as C<re::regname>, C<re::regnames> or
-C<re::regnames_count>, if any. The first two will be combined with
-C<RXapif_ONE> or C<RXapif_ALL>.
-
- RXapif_REGNAME
- RXapif_REGNAMES
- RXapif_REGNAMES_COUNT
-
-Internally C<%+> and C<%-> are implemented with a real tied interface
-via L<Tie::Hash::NamedCapture>. The methods in that package will call
-back into these functions. However the usage of
-L<Tie::Hash::NamedCapture> for this purpose might change in future
-releases. For instance this might be implemented by magic instead
-(would need an extension to mgvtbl).
-
-=head3 named_buff
-
- SV* (*named_buff) (pTHX_ REGEXP * const rx, SV * const key,
- SV * const value, U32 flags);
-
-=head3 named_buff_iter
-
- SV* (*named_buff_iter) (pTHX_ REGEXP * const rx, const SV * const lastkey,
- const U32 flags);
-
-=head2 qr_package
-
- SV* qr_package(pTHX_ REGEXP * const rx);
-
-The package the qr// magic object is blessed into (as seen by C<ref
-qr//>). It is recommended that engines change this to their package
-name for identification regardless of whether they implement methods
-on the object.
-
-The package this method returns should also have the internal
-C<Regexp> package in its C<@ISA>. C<< qr//->isa("Regexp") >> should always
-be true regardless of what engine is being used.
-
-Example implementation might be:
-
- SV*
- Example_qr_package(pTHX_ REGEXP * const rx)
- {
- PERL_UNUSED_ARG(rx);
- return newSVpvs("re::engine::Example");
- }
-
-Any method calls on an object created with C<qr//> will be dispatched to the
-package as a normal object.
-
- use re::engine::Example;
- my $re = qr//;
- $re->meth; # dispatched to re::engine::Example::meth()
-
-To retrieve the C<REGEXP> object from the scalar in an XS function use
-the C<SvRX> macro, see L<"REGEXP Functions" in perlapi|perlapi/REGEXP
-Functions>.
-
- void meth(SV * rv)
- PPCODE:
- REGEXP * re = SvRX(sv);
-
-=head2 dupe
-
- void* dupe(pTHX_ REGEXP * const rx, CLONE_PARAMS *param);
-
-On threaded builds a regexp may need to be duplicated so that the pattern
-can be used by multiple threads. This routine is expected to handle the
-duplication of any private data pointed to by the C<pprivate> member of
-the regexp structure. It will be called with the preconstructed new
-regexp structure as an argument, the C<pprivate> member will point at
-the B<old> private structure, and it is this routine's responsibility to
-construct a copy and return a pointer to it (which perl will then use to
-overwrite the field as passed to this routine.)
-
-This allows the engine to dupe its private data but also if necessary
-modify the final structure if it really must.
-
-On unthreaded builds this field doesn't exist.
-
-=head1 The REGEXP structure
-
-The REGEXP struct is defined in F<regexp.h>. All regex engines must be able to
-correctly build such a structure in their L</comp> routine.
-
-The REGEXP structure contains all the data that perl needs to be aware of
-to properly work with the regular expression. It includes data about
-optimisations that perl can use to determine if the regex engine should
-really be used, and various other control info that is needed to properly
-execute patterns in various contexts such as is the pattern anchored in
-some way, or what flags were used during the compile, or whether the
-program contains special constructs that perl needs to be aware of.
-
-In addition it contains two fields that are intended for the private
-use of the regex engine that compiled the pattern. These are the
-C<intflags> and C<pprivate> members. C<pprivate> is a void pointer to
-an arbitrary structure whose use and management is the responsibility
-of the compiling engine. perl will never modify either of these
-values.
-
- typedef struct regexp {
- /* what engine created this regexp? */
- const struct regexp_engine* engine;
-
- /* what re is this a lightweight copy of? */
- struct regexp* mother_re;
-
- /* Information about the match that the perl core uses to manage things */
- U32 extflags; /* Flags used both externally and internally */
- I32 minlen; /* mininum possible length of string to match */
- I32 minlenret; /* mininum possible length of $& */
- U32 gofs; /* chars left of pos that we search from */
-
- /* substring data about strings that must appear
- in the final match, used for optimisations */
- struct reg_substr_data *substrs;
-
- U32 nparens; /* number of capture groups */
-
- /* private engine specific data */
- U32 intflags; /* Engine Specific Internal flags */
- void *pprivate; /* Data private to the regex engine which
- created this object. */
-
- /* Data about the last/current match. These are modified during matching*/
- U32 lastparen; /* last open paren matched */
- U32 lastcloseparen; /* last close paren matched */
- regexp_paren_pair *swap; /* Swap copy of *offs */
- regexp_paren_pair *offs; /* Array of offsets for (@-) and (@+) */
-
- char *subbeg; /* saved or original string so \digit works forever. */
- SV_SAVED_COPY /* If non-NULL, SV which is COW from original */
- I32 sublen; /* Length of string pointed by subbeg */
-
- /* Information about the match that isn't often used */
- I32 prelen; /* length of precomp */
- const char *precomp; /* pre-compilation regular expression */
-
- char *wrapped; /* wrapped version of the pattern */
- I32 wraplen; /* length of wrapped */
-
- I32 seen_evals; /* number of eval groups in the pattern - for security checks */
- HV *paren_names; /* Optional hash of paren names */
-
- /* Refcount of this regexp */
- I32 refcnt; /* Refcount of this regexp */
- } regexp;
-
-The fields are discussed in more detail below:
-
-=head2 C<engine>
-
-This field points at a regexp_engine structure which contains pointers
-to the subroutines that are to be used for performing a match. It
-is the compiling routine's responsibility to populate this field before
-returning the regexp object.
-
-Internally this is set to C<NULL> unless a custom engine is specified in
-C<$^H{regcomp}>, perl's own set of callbacks can be accessed in the struct
-pointed to by C<RE_ENGINE_PTR>.
-
-=head2 C<mother_re>
-
-TODO, see L<http://www.mail-archive.com/perl5-changes@perl.org/msg17328.html>
-
-=head2 C<extflags>
-
-This will be used by perl to see what flags the regexp was compiled
-with, this will normally be set to the value of the flags parameter by
-the L<comp|/comp> callback. See the L<comp|/comp> documentation for
-valid flags.
-
-=head2 C<minlen> C<minlenret>
-
-The minimum string length required for the pattern to match. This is used to
-prune the search space by not bothering to match any closer to the end of a
-string than would allow a match. For instance there is no point in even
-starting the regex engine if the minlen is 10 but the string is only 5
-characters long. There is no way that the pattern can match.
-
-C<minlenret> is the minimum length of the string that would be found
-in $& after a match.
-
-The difference between C<minlen> and C<minlenret> can be seen in the
-following pattern:
-
- /ns(?=\d)/
-
-where the C<minlen> would be 3 but C<minlenret> would only be 2 as the \d is
-required to match but is not actually included in the matched content. This
-distinction is particularly important as the substitution logic uses the
-C<minlenret> to tell whether it can do in-place substitution which can result in
-considerable speedup.
-
-=head2 C<gofs>
-
-Left offset from pos() to start match at.
-
-=head2 C<substrs>
-
-Substring data about strings that must appear in the final match. This
-is currently only used internally by perl's engine for but might be
-used in the future for all engines for optimisations.
-
-=head2 C<nparens>, C<lastparen>, and C<lastcloseparen>
-
-These fields are used to keep track of how many paren groups could be matched
-in the pattern, which was the last open paren to be entered, and which was
-the last close paren to be entered.
-
-=head2 C<intflags>
-
-The engine's private copy of the flags the pattern was compiled with. Usually
-this is the same as C<extflags> unless the engine chose to modify one of them.
-
-=head2 C<pprivate>
-
-A void* pointing to an engine-defined data structure. The perl engine uses the
-C<regexp_internal> structure (see L<perlreguts/Base Structures>) but a custom
-engine should use something else.
-
-=head2 C<swap>
-
-Unused. Left in for compatibility with perl 5.10.0.
-
-=head2 C<offs>
-
-A C<regexp_paren_pair> structure which defines offsets into the string being
-matched which correspond to the C<$&> and C<$1>, C<$2> etc. captures, the
-C<regexp_paren_pair> struct is defined as follows:
-
- typedef struct regexp_paren_pair {
- I32 start;
- I32 end;
- } regexp_paren_pair;
-
-If C<< ->offs[num].start >> or C<< ->offs[num].end >> is C<-1> then that
-capture group did not match. C<< ->offs[0].start/end >> represents C<$&> (or
-C<${^MATCH> under C<//p>) and C<< ->offs[paren].end >> matches C<$$paren> where
-C<$paren >= 1>.
-
-=head2 C<precomp> C<prelen>
-
-Used for optimisations. C<precomp> holds a copy of the pattern that
-was compiled and C<prelen> its length. When a new pattern is to be
-compiled (such as inside a loop) the internal C<regcomp> operator
-checks whether the last compiled C<REGEXP>'s C<precomp> and C<prelen>
-are equivalent to the new one, and if so uses the old pattern instead
-of compiling a new one.
-
-The relevant snippet from C<Perl_pp_regcomp>:
-
- if (!re || !re->precomp || re->prelen != (I32)len ||
- memNE(re->precomp, t, len))
- /* Compile a new pattern */
-
-=head2 C<paren_names>
-
-This is a hash used internally to track named capture groups and their
-offsets. The keys are the names of the buffers the values are dualvars,
-with the IV slot holding the number of buffers with the given name and the
-pv being an embedded array of I32. The values may also be contained
-independently in the data array in cases where named backreferences are
-used.
-
-=head2 C<substrs>
-
-Holds information on the longest string that must occur at a fixed
-offset from the start of the pattern, and the longest string that must
-occur at a floating offset from the start of the pattern. Used to do
-Fast-Boyer-Moore searches on the string to find out if its worth using
-the regex engine at all, and if so where in the string to search.
-
-=head2 C<subbeg> C<sublen> C<saved_copy>
-
-Used during execution phase for managing search and replace patterns.
-
-=head2 C<wrapped> C<wraplen>
-
-Stores the string C<qr//> stringifies to. The perl engine for example
-stores C<(?^:eek)> in the case of C<qr/eek/>.
-
-When using a custom engine that doesn't support the C<(?:)> construct
-for inline modifiers, it's probably best to have C<qr//> stringify to
-the supplied pattern, note that this will create undesired patterns in
-cases such as:
-
- my $x = qr/a|b/; # "a|b"
- my $y = qr/c/i; # "c"
- my $z = qr/$x$y/; # "a|bc"
-
-There's no solution for this problem other than making the custom
-engine understand a construct like C<(?:)>.
-
-=head2 C<seen_evals>
-
-This stores the number of eval groups in the pattern. This is used for security
-purposes when embedding compiled regexes into larger patterns with C<qr//>.
-
-=head2 C<refcnt>
-
-The number of times the structure is referenced. When this falls to 0 the
-regexp is automatically freed by a call to pregfree. This should be set to 1 in
-each engine's L</comp> routine.
-
-=head1 HISTORY
-
-Originally part of L<perlreguts>.
-
-=head1 AUTHORS
-
-Originally written by Yves Orton, expanded by E<AElig>var ArnfjE<ouml>rE<eth>
-Bjarmason.
-
-=head1 LICENSE
-
-Copyright 2006 Yves Orton and 2007 E<AElig>var ArnfjE<ouml>rE<eth> Bjarmason.
-
-This program is free software; you can redistribute it and/or modify it under
-the same terms as Perl itself.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlrebackslash.pod b/Master/tlpkg/tlperl/lib/pods/perlrebackslash.pod
deleted file mode 100644
index f81af0c6dd7..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlrebackslash.pod
+++ /dev/null
@@ -1,661 +0,0 @@
-=head1 NAME
-
-perlrebackslash - Perl Regular Expression Backslash Sequences and Escapes
-
-=head1 DESCRIPTION
-
-The top level documentation about Perl regular expressions
-is found in L<perlre>.
-
-This document describes all backslash and escape sequences. After
-explaining the role of the backslash, it lists all the sequences that have
-a special meaning in Perl regular expressions (in alphabetical order),
-then describes each of them.
-
-Most sequences are described in detail in different documents; the primary
-purpose of this document is to have a quick reference guide describing all
-backslash and escape sequences.
-
-=head2 The backslash
-
-In a regular expression, the backslash can perform one of two tasks:
-it either takes away the special meaning of the character following it
-(for instance, C<\|> matches a vertical bar, it's not an alternation),
-or it is the start of a backslash or escape sequence.
-
-The rules determining what it is are quite simple: if the character
-following the backslash is an ASCII punctuation (non-word) character (that is,
-anything that is not a letter, digit, or underscore), then the backslash just
-takes away any special meaning of the character following it.
-
-If the character following the backslash is an ASCII letter or an ASCII digit,
-then the sequence may be special; if so, it's listed below. A few letters have
-not been used yet, so escaping them with a backslash doesn't change them to be
-special. A future version of Perl may assign a special meaning to them, so if
-you have warnings turned on, Perl issues a warning if you use such a
-sequence. [1].
-
-It is however guaranteed that backslash or escape sequences never have a
-punctuation character following the backslash, not now, and not in a future
-version of Perl 5. So it is safe to put a backslash in front of a non-word
-character.
-
-Note that the backslash itself is special; if you want to match a backslash,
-you have to escape the backslash with a backslash: C</\\/> matches a single
-backslash.
-
-=over 4
-
-=item [1]
-
-There is one exception. If you use an alphanumeric character as the
-delimiter of your pattern (which you probably shouldn't do for readability
-reasons), you have to escape the delimiter if you want to match
-it. Perl won't warn then. See also L<perlop/Gory details of parsing
-quoted constructs>.
-
-=back
-
-
-=head2 All the sequences and escapes
-
-Those not usable within a bracketed character class (like C<[\da-z]>) are marked
-as C<Not in [].>
-
- \000 Octal escape sequence. See also \o{}.
- \1 Absolute backreference. Not in [].
- \a Alarm or bell.
- \A Beginning of string. Not in [].
- \b Word/non-word boundary. (Backspace in []).
- \B Not a word/non-word boundary. Not in [].
- \cX Control-X
- \C Single octet, even under UTF-8. Not in [].
- \d Character class for digits.
- \D Character class for non-digits.
- \e Escape character.
- \E Turn off \Q, \L and \U processing. Not in [].
- \f Form feed.
- \F Foldcase till \E. Not in [].
- \g{}, \g1 Named, absolute or relative backreference. Not in []
- \G Pos assertion. Not in [].
- \h Character class for horizontal whitespace.
- \H Character class for non horizontal whitespace.
- \k{}, \k<>, \k'' Named backreference. Not in [].
- \K Keep the stuff left of \K. Not in [].
- \l Lowercase next character. Not in [].
- \L Lowercase till \E. Not in [].
- \n (Logical) newline character.
- \N Any character but newline. Experimental. Not in [].
- \N{} Named or numbered (Unicode) character or sequence.
- \o{} Octal escape sequence.
- \p{}, \pP Character with the given Unicode property.
- \P{}, \PP Character without the given Unicode property.
- \Q Quote (disable) pattern metacharacters till \E. Not
- in [].
- \r Return character.
- \R Generic new line. Not in [].
- \s Character class for whitespace.
- \S Character class for non whitespace.
- \t Tab character.
- \u Titlecase next character. Not in [].
- \U Uppercase till \E. Not in [].
- \v Character class for vertical whitespace.
- \V Character class for non vertical whitespace.
- \w Character class for word characters.
- \W Character class for non-word characters.
- \x{}, \x00 Hexadecimal escape sequence.
- \X Unicode "extended grapheme cluster". Not in [].
- \z End of string. Not in [].
- \Z End of string. Not in [].
-
-=head2 Character Escapes
-
-=head3 Fixed characters
-
-A handful of characters have a dedicated I<character escape>. The following
-table shows them, along with their ASCII code points (in decimal and hex),
-their ASCII name, the control escape on ASCII platforms and a short
-description. (For EBCDIC platforms, see L<perlebcdic/OPERATOR DIFFERENCES>.)
-
- Seq. Code Point ASCII Cntrl Description.
- Dec Hex
- \a 7 07 BEL \cG alarm or bell
- \b 8 08 BS \cH backspace [1]
- \e 27 1B ESC \c[ escape character
- \f 12 0C FF \cL form feed
- \n 10 0A LF \cJ line feed [2]
- \r 13 0D CR \cM carriage return
- \t 9 09 TAB \cI tab
-
-=over 4
-
-=item [1]
-
-C<\b> is the backspace character only inside a character class. Outside a
-character class, C<\b> is a word/non-word boundary.
-
-=item [2]
-
-C<\n> matches a logical newline. Perl converts between C<\n> and your
-OS's native newline character when reading from or writing to text files.
-
-=back
-
-=head4 Example
-
- $str =~ /\t/; # Matches if $str contains a (horizontal) tab.
-
-=head3 Control characters
-
-C<\c> is used to denote a control character; the character following C<\c>
-determines the value of the construct. For example the value of C<\cA> is
-C<chr(1)>, and the value of C<\cb> is C<chr(2)>, etc.
-The gory details are in L<perlop/"Regexp Quote-Like Operators">. A complete
-list of what C<chr(1)>, etc. means for ASCII and EBCDIC platforms is in
-L<perlebcdic/OPERATOR DIFFERENCES>.
-
-Note that C<\c\> alone at the end of a regular expression (or doubled-quoted
-string) is not valid. The backslash must be followed by another character.
-That is, C<\c\I<X>> means C<chr(28) . 'I<X>'> for all characters I<X>.
-
-To write platform-independent code, you must use C<\N{I<NAME>}> instead, like
-C<\N{ESCAPE}> or C<\N{U+001B}>, see L<charnames>.
-
-Mnemonic: I<c>ontrol character.
-
-=head4 Example
-
- $str =~ /\cK/; # Matches if $str contains a vertical tab (control-K).
-
-=head3 Named or numbered characters and character sequences
-
-Unicode characters have a Unicode name and numeric code point (ordinal)
-value. Use the
-C<\N{}> construct to specify a character by either of these values.
-Certain sequences of characters also have names.
-
-To specify by name, the name of the character or character sequence goes
-between the curly braces.
-
-To specify a character by Unicode code point, use the form C<\N{U+I<code
-point>}>, where I<code point> is a number in hexadecimal that gives the
-code point that Unicode has assigned to the desired character. It is
-customary but not required to use leading zeros to pad the number to 4
-digits. Thus C<\N{U+0041}> means C<LATIN CAPITAL LETTER A>, and you will
-rarely see it written without the two leading zeros. C<\N{U+0041}> means
-"A" even on EBCDIC machines (where the ordinal value of "A" is not 0x41).
-
-It is even possible to give your own names to characters and character
-sequences. For details, see L<charnames>.
-
-(There is an expanded internal form that you may see in debug output:
-C<\N{U+I<code point>.I<code point>...}>.
-The C<...> means any number of these I<code point>s separated by dots.
-This represents the sequence formed by the characters. This is an internal
-form only, subject to change, and you should not try to use it yourself.)
-
-Mnemonic: I<N>amed character.
-
-Note that a character or character sequence expressed as a named
-or numbered character is considered a character without special
-meaning by the regex engine, and will match "as is".
-
-=head4 Example
-
- $str =~ /\N{THAI CHARACTER SO SO}/; # Matches the Thai SO SO character
-
- use charnames 'Cyrillic'; # Loads Cyrillic names.
- $str =~ /\N{ZHE}\N{KA}/; # Match "ZHE" followed by "KA".
-
-=head3 Octal escapes
-
-There are two forms of octal escapes. Each is used to specify a character by
-its code point specified in octal notation.
-
-One form, available starting in Perl 5.14 looks like C<\o{...}>, where the dots
-represent one or more octal digits. It can be used for any Unicode character.
-
-It was introduced to avoid the potential problems with the other form,
-available in all Perls. That form consists of a backslash followed by three
-octal digits. One problem with this form is that it can look exactly like an
-old-style backreference (see
-L</Disambiguation rules between old-style octal escapes and backreferences>
-below.) You can avoid this by making the first of the three digits always a
-zero, but that makes \077 the largest code point specifiable.
-
-In some contexts, a backslash followed by two or even one octal digits may be
-interpreted as an octal escape, sometimes with a warning, and because of some
-bugs, sometimes with surprising results. Also, if you are creating a regex
-out of smaller snippets concatenated together, and you use fewer than three
-digits, the beginning of one snippet may be interpreted as adding digits to the
-ending of the snippet before it. See L</Absolute referencing> for more
-discussion and examples of the snippet problem.
-
-Note that a character expressed as an octal escape is considered
-a character without special meaning by the regex engine, and will match
-"as is".
-
-To summarize, the C<\o{}> form is always safe to use, and the other form is
-safe to use for code points through \077 when you use exactly three digits to
-specify them.
-
-Mnemonic: I<0>ctal or I<o>ctal.
-
-=head4 Examples (assuming an ASCII platform)
-
- $str = "Perl";
- $str =~ /\o{120}/; # Match, "\120" is "P".
- $str =~ /\120/; # Same.
- $str =~ /\o{120}+/; # Match, "\120" is "P", it's repeated at least once
- $str =~ /\120+/; # Same.
- $str =~ /P\053/; # No match, "\053" is "+" and taken literally.
- /\o{23073}/ # Black foreground, white background smiling face.
- /\o{4801234567}/ # Raises a warning, and yields chr(4)
-
-=head4 Disambiguation rules between old-style octal escapes and backreferences
-
-Octal escapes of the C<\000> form outside of bracketed character classes
-potentially clash with old-style backreferences. (see L</Absolute referencing>
-below). They both consist of a backslash followed by numbers. So Perl has to
-use heuristics to determine whether it is a backreference or an octal escape.
-Perl uses the following rules to disambiguate:
-
-=over 4
-
-=item 1
-
-If the backslash is followed by a single digit, it's a backreference.
-
-=item 2
-
-If the first digit following the backslash is a 0, it's an octal escape.
-
-=item 3
-
-If the number following the backslash is N (in decimal), and Perl already
-has seen N capture groups, Perl considers this a backreference. Otherwise,
-it considers it an octal escape. If N has more than three digits, Perl
-takes only the first three for the octal escape; the rest are matched as is.
-
- my $pat = "(" x 999;
- $pat .= "a";
- $pat .= ")" x 999;
- /^($pat)\1000$/; # Matches 'aa'; there are 1000 capture groups.
- /^$pat\1000$/; # Matches 'a@0'; there are 999 capture groups
- # and \1000 is seen as \100 (a '@') and a '0'
-
-=back
-
-You can force a backreference interpretation always by using the C<\g{...}>
-form. You can the force an octal interpretation always by using the C<\o{...}>
-form, or for numbers up through \077 (= 63 decimal), by using three digits,
-beginning with a "0".
-
-=head3 Hexadecimal escapes
-
-Like octal escapes, there are two forms of hexadecimal escapes, but both start
-with the same thing, C<\x>. This is followed by either exactly two hexadecimal
-digits forming a number, or a hexadecimal number of arbitrary length surrounded
-by curly braces. The hexadecimal number is the code point of the character you
-want to express.
-
-Note that a character expressed as one of these escapes is considered a
-character without special meaning by the regex engine, and will match
-"as is".
-
-Mnemonic: heI<x>adecimal.
-
-=head4 Examples (assuming an ASCII platform)
-
- $str = "Perl";
- $str =~ /\x50/; # Match, "\x50" is "P".
- $str =~ /\x50+/; # Match, "\x50" is "P", it is repeated at least once
- $str =~ /P\x2B/; # No match, "\x2B" is "+" and taken literally.
-
- /\x{2603}\x{2602}/ # Snowman with an umbrella.
- # The Unicode character 2603 is a snowman,
- # the Unicode character 2602 is an umbrella.
- /\x{263B}/ # Black smiling face.
- /\x{263b}/ # Same, the hex digits A - F are case insensitive.
-
-=head2 Modifiers
-
-A number of backslash sequences have to do with changing the character,
-or characters following them. C<\l> will lowercase the character following
-it, while C<\u> will uppercase (or, more accurately, titlecase) the
-character following it. They provide functionality similar to the
-functions C<lcfirst> and C<ucfirst>.
-
-To uppercase or lowercase several characters, one might want to use
-C<\L> or C<\U>, which will lowercase/uppercase all characters following
-them, until either the end of the pattern or the next occurrence of
-C<\E>, whichever comes first. They provide functionality similar to what
-the functions C<lc> and C<uc> provide.
-
-C<\Q> is used to quote (disable) pattern metacharacters, up to the next
-C<\E> or the end of the pattern. C<\Q> adds a backslash to any character
-that could have special meaning to Perl. In the ASCII range, it quotes
-every character that isn't a letter, digit, or underscore. See
-L<perlfunc/quotemeta> for details on what gets quoted for non-ASCII
-code points. Using this ensures that any character between C<\Q> and
-C<\E> will be matched literally, not interpreted as a metacharacter by
-the regex engine.
-
-C<\F> can be used to casefold all characters following, up to the next C<\E>
-or the end of the pattern. It provides the functionality similar to
-the C<fc> function.
-
-Mnemonic: I<L>owercase, I<U>ppercase, I<F>old-case, I<Q>uotemeta, I<E>nd.
-
-=head4 Examples
-
- $sid = "sid";
- $greg = "GrEg";
- $miranda = "(Miranda)";
- $str =~ /\u$sid/; # Matches 'Sid'
- $str =~ /\L$greg/; # Matches 'greg'
- $str =~ /\Q$miranda\E/; # Matches '(Miranda)', as if the pattern
- # had been written as /\(Miranda\)/
-
-=head2 Character classes
-
-Perl regular expressions have a large range of character classes. Some of
-the character classes are written as a backslash sequence. We will briefly
-discuss those here; full details of character classes can be found in
-L<perlrecharclass>.
-
-C<\w> is a character class that matches any single I<word> character
-(letters, digits, Unicode marks, and connector punctuation (like the
-underscore)). C<\d> is a character class that matches any decimal
-digit, while the character class C<\s> matches any whitespace character.
-New in perl 5.10.0 are the classes C<\h> and C<\v> which match horizontal
-and vertical whitespace characters.
-
-The exact set of characters matched by C<\d>, C<\s>, and C<\w> varies
-depending on various pragma and regular expression modifiers. It is
-possible to restrict the match to the ASCII range by using the C</a>
-regular expression modifier. See L<perlrecharclass>.
-
-The uppercase variants (C<\W>, C<\D>, C<\S>, C<\H>, and C<\V>) are
-character classes that match, respectively, any character that isn't a
-word character, digit, whitespace, horizontal whitespace, or vertical
-whitespace.
-
-Mnemonics: I<w>ord, I<d>igit, I<s>pace, I<h>orizontal, I<v>ertical.
-
-=head3 Unicode classes
-
-C<\pP> (where C<P> is a single letter) and C<\p{Property}> are used to
-match a character that matches the given Unicode property; properties
-include things like "letter", or "thai character". Capitalizing the
-sequence to C<\PP> and C<\P{Property}> make the sequence match a character
-that doesn't match the given Unicode property. For more details, see
-L<perlrecharclass/Backslash sequences> and
-L<perlunicode/Unicode Character Properties>.
-
-Mnemonic: I<p>roperty.
-
-=head2 Referencing
-
-If capturing parenthesis are used in a regular expression, we can refer
-to the part of the source string that was matched, and match exactly the
-same thing. There are three ways of referring to such I<backreference>:
-absolutely, relatively, and by name.
-
-=for later add link to perlrecapture
-
-=head3 Absolute referencing
-
-Either C<\gI<N>> (starting in Perl 5.10.0), or C<\I<N>> (old-style) where I<N>
-is a positive (unsigned) decimal number of any length is an absolute reference
-to a capturing group.
-
-I<N> refers to the Nth set of parentheses, so C<\gI<N>> refers to whatever has
-been matched by that set of parentheses. Thus C<\g1> refers to the first
-capture group in the regex.
-
-The C<\gI<N>> form can be equivalently written as C<\g{I<N>}>
-which avoids ambiguity when building a regex by concatenating shorter
-strings. Otherwise if you had a regex C<qr/$a$b/>, and C<$a> contained
-C<"\g1">, and C<$b> contained C<"37">, you would get C</\g137/> which is
-probably not what you intended.
-
-In the C<\I<N>> form, I<N> must not begin with a "0", and there must be at
-least I<N> capturing groups, or else I<N> is considered an octal escape
-(but something like C<\18> is the same as C<\0018>; that is, the octal escape
-C<"\001"> followed by a literal digit C<"8">).
-
-Mnemonic: I<g>roup.
-
-=head4 Examples
-
- /(\w+) \g1/; # Finds a duplicated word, (e.g. "cat cat").
- /(\w+) \1/; # Same thing; written old-style
- /(.)(.)\g2\g1/; # Match a four letter palindrome (e.g. "ABBA").
-
-
-=head3 Relative referencing
-
-C<\g-I<N>> (starting in Perl 5.10.0) is used for relative addressing. (It can
-be written as C<\g{-I<N>>.) It refers to the I<N>th group before the
-C<\g{-I<N>}>.
-
-The big advantage of this form is that it makes it much easier to write
-patterns with references that can be interpolated in larger patterns,
-even if the larger pattern also contains capture groups.
-
-=head4 Examples
-
- /(A) # Group 1
- ( # Group 2
- (B) # Group 3
- \g{-1} # Refers to group 3 (B)
- \g{-3} # Refers to group 1 (A)
- )
- /x; # Matches "ABBA".
-
- my $qr = qr /(.)(.)\g{-2}\g{-1}/; # Matches 'abab', 'cdcd', etc.
- /$qr$qr/ # Matches 'ababcdcd'.
-
-=head3 Named referencing
-
-C<\g{I<name>}> (starting in Perl 5.10.0) can be used to back refer to a
-named capture group, dispensing completely with having to think about capture
-buffer positions.
-
-To be compatible with .Net regular expressions, C<\g{name}> may also be
-written as C<\k{name}>, C<< \k<name> >> or C<\k'name'>.
-
-To prevent any ambiguity, I<name> must not start with a digit nor contain a
-hyphen.
-
-=head4 Examples
-
- /(?<word>\w+) \g{word}/ # Finds duplicated word, (e.g. "cat cat")
- /(?<word>\w+) \k{word}/ # Same.
- /(?<word>\w+) \k<word>/ # Same.
- /(?<letter1>.)(?<letter2>.)\g{letter2}\g{letter1}/
- # Match a four letter palindrome (e.g. "ABBA")
-
-=head2 Assertions
-
-Assertions are conditions that have to be true; they don't actually
-match parts of the substring. There are six assertions that are written as
-backslash sequences.
-
-=over 4
-
-=item \A
-
-C<\A> only matches at the beginning of the string. If the C</m> modifier
-isn't used, then C</\A/> is equivalent to C</^/>. However, if the C</m>
-modifier is used, then C</^/> matches internal newlines, but the meaning
-of C</\A/> isn't changed by the C</m> modifier. C<\A> matches at the beginning
-of the string regardless whether the C</m> modifier is used.
-
-=item \z, \Z
-
-C<\z> and C<\Z> match at the end of the string. If the C</m> modifier isn't
-used, then C</\Z/> is equivalent to C</$/>; that is, it matches at the
-end of the string, or one before the newline at the end of the string. If the
-C</m> modifier is used, then C</$/> matches at internal newlines, but the
-meaning of C</\Z/> isn't changed by the C</m> modifier. C<\Z> matches at
-the end of the string (or just before a trailing newline) regardless whether
-the C</m> modifier is used.
-
-C<\z> is just like C<\Z>, except that it does not match before a trailing
-newline. C<\z> matches at the end of the string only, regardless of the
-modifiers used, and not just before a newline. It is how to anchor the
-match to the true end of the string under all conditions.
-
-=item \G
-
-C<\G> is usually used only in combination with the C</g> modifier. If the
-C</g> modifier is used and the match is done in scalar context, Perl
-remembers where in the source string the last match ended, and the next time,
-it will start the match from where it ended the previous time.
-
-C<\G> matches the point where the previous match on that string ended,
-or the beginning of that string if there was no previous match.
-
-=for later add link to perlremodifiers
-
-Mnemonic: I<G>lobal.
-
-=item \b, \B
-
-C<\b> matches at any place between a word and a non-word character; C<\B>
-matches at any place between characters where C<\b> doesn't match. C<\b>
-and C<\B> assume there's a non-word character before the beginning and after
-the end of the source string; so C<\b> will match at the beginning (or end)
-of the source string if the source string begins (or ends) with a word
-character. Otherwise, C<\B> will match.
-
-Do not use something like C<\b=head\d\b> and expect it to match the
-beginning of a line. It can't, because for there to be a boundary before
-the non-word "=", there must be a word character immediately previous.
-All boundary determinations look for word characters alone, not for
-non-words characters nor for string ends. It may help to understand how
-<\b> and <\B> work by equating them as follows:
-
- \b really means (?:(?<=\w)(?!\w)|(?<!\w)(?=\w))
- \B really means (?:(?<=\w)(?=\w)|(?<!\w)(?!\w))
-
-Mnemonic: I<b>oundary.
-
-=back
-
-=head4 Examples
-
- "cat" =~ /\Acat/; # Match.
- "cat" =~ /cat\Z/; # Match.
- "cat\n" =~ /cat\Z/; # Match.
- "cat\n" =~ /cat\z/; # No match.
-
- "cat" =~ /\bcat\b/; # Matches.
- "cats" =~ /\bcat\b/; # No match.
- "cat" =~ /\bcat\B/; # No match.
- "cats" =~ /\bcat\B/; # Match.
-
- while ("cat dog" =~ /(\w+)/g) {
- print $1; # Prints 'catdog'
- }
- while ("cat dog" =~ /\G(\w+)/g) {
- print $1; # Prints 'cat'
- }
-
-=head2 Misc
-
-Here we document the backslash sequences that don't fall in one of the
-categories above. These are:
-
-=over 4
-
-=item \C
-
-C<\C> always matches a single octet, even if the source string is encoded
-in UTF-8 format, and the character to be matched is a multi-octet character.
-C<\C> was introduced in perl 5.6. This is very dangerous, because it violates
-the logical character abstraction and can cause UTF-8 sequences to become malformed.
-
-Mnemonic: oI<C>tet.
-
-=item \K
-
-This appeared in perl 5.10.0. Anything matched left of C<\K> is
-not included in C<$&>, and will not be replaced if the pattern is
-used in a substitution. This lets you write C<s/PAT1 \K PAT2/REPL/x>
-instead of C<s/(PAT1) PAT2/${1}REPL/x> or C<s/(?<=PAT1) PAT2/REPL/x>.
-
-Mnemonic: I<K>eep.
-
-=item \N
-
-This is an experimental feature new to perl 5.12.0. It matches any character
-that is B<not> a newline. It is a short-hand for writing C<[^\n]>, and is
-identical to the C<.> metasymbol, except under the C</s> flag, which changes
-the meaning of C<.>, but not C<\N>.
-
-Note that C<\N{...}> can mean a
-L<named or numbered character
-|/Named or numbered characters and character sequences>.
-
-Mnemonic: Complement of I<\n>.
-
-=item \R
-X<\R>
-
-C<\R> matches a I<generic newline>; that is, anything considered a
-linebreak sequence by Unicode. This includes all characters matched by
-C<\v> (vertical whitespace), and the multi character sequence C<"\x0D\x0A">
-(carriage return followed by a line feed, sometimes called the network
-newline; it's the end of line sequence used in Microsoft text files opened
-in binary mode). C<\R> is equivalent to C<< (?>\x0D\x0A|\v) >>. (The
-reason it doesn't backtrack is that the sequence is considered
-inseparable. That means that
-
- "\x0D\x0A" =~ /^\R\x0A$/ # No match
-
-fails, because the C<\R> matches the entire string, and won't backtrack
-to match just the C<"\x0D">.) Since
-C<\R> can match a sequence of more than one character, it cannot be put
-inside a bracketed character class; C</[\R]/> is an error; use C<\v>
-instead. C<\R> was introduced in perl 5.10.0.
-
-Note that this does not respect any locale that might be in effect; it
-matches according to the platform's native character set.
-
-Mnemonic: none really. C<\R> was picked because PCRE already uses C<\R>,
-and more importantly because Unicode recommends such a regular expression
-metacharacter, and suggests C<\R> as its notation.
-
-=item \X
-X<\X>
-
-This matches a Unicode I<extended grapheme cluster>.
-
-C<\X> matches quite well what normal (non-Unicode-programmer) usage
-would consider a single character. As an example, consider a G with some sort
-of diacritic mark, such as an arrow. There is no such single character in
-Unicode, but one can be composed by using a G followed by a Unicode "COMBINING
-UPWARDS ARROW BELOW", and would be displayed by Unicode-aware software as if it
-were a single character.
-
-Mnemonic: eI<X>tended Unicode character.
-
-=back
-
-=head4 Examples
-
- "\x{256}" =~ /^\C\C$/; # Match as chr (0x256) takes 2 octets in UTF-8.
-
- $str =~ s/foo\Kbar/baz/g; # Change any 'bar' following a 'foo' to 'baz'
- $str =~ s/(.)\K\g1//g; # Delete duplicated characters.
-
- "\n" =~ /^\R$/; # Match, \n is a generic newline.
- "\r" =~ /^\R$/; # Match, \r is a generic newline.
- "\r\n" =~ /^\R$/; # Match, \r\n is a generic newline.
-
- "P\x{307}" =~ /^\X$/ # \X matches a P with a dot above.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlrecharclass.pod b/Master/tlpkg/tlperl/lib/pods/perlrecharclass.pod
deleted file mode 100644
index 06d206b2f8b..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlrecharclass.pod
+++ /dev/null
@@ -1,850 +0,0 @@
-=head1 NAME
-X<character class>
-
-perlrecharclass - Perl Regular Expression Character Classes
-
-=head1 DESCRIPTION
-
-The top level documentation about Perl regular expressions
-is found in L<perlre>.
-
-This manual page discusses the syntax and use of character
-classes in Perl regular expressions.
-
-A character class is a way of denoting a set of characters
-in such a way that one character of the set is matched.
-It's important to remember that: matching a character class
-consumes exactly one character in the source string. (The source
-string is the string the regular expression is matched against.)
-
-There are three types of character classes in Perl regular
-expressions: the dot, backslash sequences, and the form enclosed in square
-brackets. Keep in mind, though, that often the term "character class" is used
-to mean just the bracketed form. Certainly, most Perl documentation does that.
-
-=head2 The dot
-
-The dot (or period), C<.> is probably the most used, and certainly
-the most well-known character class. By default, a dot matches any
-character, except for the newline. That default can be changed to
-add matching the newline by using the I<single line> modifier: either
-for the entire regular expression with the C</s> modifier, or
-locally with C<(?s)>. (The experimental C<\N> backslash sequence, described
-below, matches any character except newline without regard to the
-I<single line> modifier.)
-
-Here are some examples:
-
- "a" =~ /./ # Match
- "." =~ /./ # Match
- "" =~ /./ # No match (dot has to match a character)
- "\n" =~ /./ # No match (dot does not match a newline)
- "\n" =~ /./s # Match (global 'single line' modifier)
- "\n" =~ /(?s:.)/ # Match (local 'single line' modifier)
- "ab" =~ /^.$/ # No match (dot matches one character)
-
-=head2 Backslash sequences
-X<\w> X<\W> X<\s> X<\S> X<\d> X<\D> X<\p> X<\P>
-X<\N> X<\v> X<\V> X<\h> X<\H>
-X<word> X<whitespace>
-
-A backslash sequence is a sequence of characters, the first one of which is a
-backslash. Perl ascribes special meaning to many such sequences, and some of
-these are character classes. That is, they match a single character each,
-provided that the character belongs to the specific set of characters defined
-by the sequence.
-
-Here's a list of the backslash sequences that are character classes. They
-are discussed in more detail below. (For the backslash sequences that aren't
-character classes, see L<perlrebackslash>.)
-
- \d Match a decimal digit character.
- \D Match a non-decimal-digit character.
- \w Match a "word" character.
- \W Match a non-"word" character.
- \s Match a whitespace character.
- \S Match a non-whitespace character.
- \h Match a horizontal whitespace character.
- \H Match a character that isn't horizontal whitespace.
- \v Match a vertical whitespace character.
- \V Match a character that isn't vertical whitespace.
- \N Match a character that isn't a newline. Experimental.
- \pP, \p{Prop} Match a character that has the given Unicode property.
- \PP, \P{Prop} Match a character that doesn't have the Unicode property
-
-=head3 \N
-
-C<\N> is new in 5.12, and is experimental. It, like the dot, matches any
-character that is not a newline. The difference is that C<\N> is not influenced
-by the I<single line> regular expression modifier (see L</The dot> above). Note
-that the form C<\N{...}> may mean something completely different. When the
-C<{...}> is a L<quantifier|perlre/Quantifiers>, it means to match a non-newline
-character that many times. For example, C<\N{3}> means to match 3
-non-newlines; C<\N{5,}> means to match 5 or more non-newlines. But if C<{...}>
-is not a legal quantifier, it is presumed to be a named character. See
-L<charnames> for those. For example, none of C<\N{COLON}>, C<\N{4F}>, and
-C<\N{F4}> contain legal quantifiers, so Perl will try to find characters whose
-names are respectively C<COLON>, C<4F>, and C<F4>.
-
-=head3 Digits
-
-C<\d> matches a single character considered to be a decimal I<digit>.
-If the C</a> regular expression modifier is in effect, it matches [0-9].
-Otherwise, it
-matches anything that is matched by C<\p{Digit}>, which includes [0-9].
-(An unlikely possible exception is that under locale matching rules, the
-current locale might not have [0-9] matched by C<\d>, and/or might match
-other characters whose code point is less than 256. Such a locale
-definition would be in violation of the C language standard, but Perl
-doesn't currently assume anything in regard to this.)
-
-What this means is that unless the C</a> modifier is in effect C<\d> not
-only matches the digits '0' - '9', but also Arabic, Devanagari, and
-digits from other languages. This may cause some confusion, and some
-security issues.
-
-Some digits that C<\d> matches look like some of the [0-9] ones, but
-have different values. For example, BENGALI DIGIT FOUR (U+09EA) looks
-very much like an ASCII DIGIT EIGHT (U+0038). An application that
-is expecting only the ASCII digits might be misled, or if the match is
-C<\d+>, the matched string might contain a mixture of digits from
-different writing systems that look like they signify a number different
-than they actually do. L<Unicode::UCD/num()> can
-be used to safely
-calculate the value, returning C<undef> if the input string contains
-such a mixture.
-
-What C<\p{Digit}> means (and hence C<\d> except under the C</a>
-modifier) is C<\p{General_Category=Decimal_Number}>, or synonymously,
-C<\p{General_Category=Digit}>. Starting with Unicode version 4.1, this
-is the same set of characters matched by C<\p{Numeric_Type=Decimal}>.
-But Unicode also has a different property with a similar name,
-C<\p{Numeric_Type=Digit}>, which matches a completely different set of
-characters. These characters are things such as C<CIRCLED DIGIT ONE>
-or subscripts, or are from writing systems that lack all ten digits.
-
-The design intent is for C<\d> to exactly match the set of characters
-that can safely be used with "normal" big-endian positional decimal
-syntax, where, for example 123 means one 'hundred', plus two 'tens',
-plus three 'ones'. This positional notation does not necessarily apply
-to characters that match the other type of "digit",
-C<\p{Numeric_Type=Digit}>, and so C<\d> doesn't match them.
-
-The Tamil digits (U+0BE6 - U+0BEF) can also legally be
-used in old-style Tamil numbers in which they would appear no more than
-one in a row, separated by characters that mean "times 10", "times 100",
-etc. (See L<http://www.unicode.org/notes/tn21>.)
-
-Any character not matched by C<\d> is matched by C<\D>.
-
-=head3 Word characters
-
-A C<\w> matches a single alphanumeric character (an alphabetic character, or a
-decimal digit) or a connecting punctuation character, such as an
-underscore ("_"). It does not match a whole word. To match a whole
-word, use C<\w+>. This isn't the same thing as matching an English word, but
-in the ASCII range it is the same as a string of Perl-identifier
-characters.
-
-=over
-
-=item If the C</a> modifier is in effect ...
-
-C<\w> matches the 63 characters [a-zA-Z0-9_].
-
-=item otherwise ...
-
-=over
-
-=item For code points above 255 ...
-
-C<\w> matches the same as C<\p{Word}> matches in this range. That is,
-it matches Thai letters, Greek letters, etc. This includes connector
-punctuation (like the underscore) which connect two words together, or
-diacritics, such as a C<COMBINING TILDE> and the modifier letters, which
-are generally used to add auxiliary markings to letters.
-
-=item For code points below 256 ...
-
-=over
-
-=item if locale rules are in effect ...
-
-C<\w> matches the platform's native underscore character plus whatever
-the locale considers to be alphanumeric.
-
-=item if Unicode rules are in effect or if on an EBCDIC platform ...
-
-C<\w> matches exactly what C<\p{Word}> matches.
-
-=item otherwise ...
-
-C<\w> matches [a-zA-Z0-9_].
-
-=back
-
-=back
-
-=back
-
-Which rules apply are determined as described in L<perlre/Which character set modifier is in effect?>.
-
-There are a number of security issues with the full Unicode list of word
-characters. See L<http://unicode.org/reports/tr36>.
-
-Also, for a somewhat finer-grained set of characters that are in programming
-language identifiers beyond the ASCII range, you may wish to instead use the
-more customized L</Unicode Properties>, C<\p{ID_Start}>,
-C<\p{ID_Continue}>, C<\p{XID_Start}>, and C<\p{XID_Continue}>. See
-L<http://unicode.org/reports/tr31>.
-
-Any character not matched by C<\w> is matched by C<\W>.
-
-=head3 Whitespace
-
-C<\s> matches any single character considered whitespace.
-
-=over
-
-=item If the C</a> modifier is in effect ...
-
-C<\s> matches the 5 characters [\t\n\f\r ]; that is, the horizontal tab,
-the newline, the form feed, the carriage return, and the space. (Note
-that it doesn't match the vertical tab, C<\cK> on ASCII platforms.)
-
-=item otherwise ...
-
-=over
-
-=item For code points above 255 ...
-
-C<\s> matches exactly the code points above 255 shown with an "s" column
-in the table below.
-
-=item For code points below 256 ...
-
-=over
-
-=item if locale rules are in effect ...
-
-C<\s> matches whatever the locale considers to be whitespace. Note that
-this is likely to include the vertical space, unlike non-locale C<\s>
-matching.
-
-=item if Unicode rules are in effect or if on an EBCDIC platform ...
-
-C<\s> matches exactly the characters shown with an "s" column in the
-table below.
-
-=item otherwise ...
-
-C<\s> matches [\t\n\f\r ].
-Note that this list doesn't include the non-breaking space.
-
-=back
-
-=back
-
-=back
-
-Which rules apply are determined as described in L<perlre/Which character set modifier is in effect?>.
-
-Any character not matched by C<\s> is matched by C<\S>.
-
-C<\h> matches any character considered horizontal whitespace;
-this includes the platform's space and tab characters and several others
-listed in the table below. C<\H> matches any character
-not considered horizontal whitespace. They use the platform's native
-character set, and do not consider any locale that may otherwise be in
-use.
-
-C<\v> matches any character considered vertical whitespace;
-this includes the platform's carriage return and line feed characters (newline)
-plus several other characters, all listed in the table below.
-C<\V> matches any character not considered vertical whitespace.
-They use the platform's native character set, and do not consider any
-locale that may otherwise be in use.
-
-C<\R> matches anything that can be considered a newline under Unicode
-rules. It's not a character class, as it can match a multi-character
-sequence. Therefore, it cannot be used inside a bracketed character
-class; use C<\v> instead (vertical whitespace). It uses the platform's
-native character set, and does not consider any locale that may
-otherwise be in use.
-Details are discussed in L<perlrebackslash>.
-
-Note that unlike C<\s> (and C<\d> and C<\w>), C<\h> and C<\v> always match
-the same characters, without regard to other factors, such as the active
-locale or whether the source string is in UTF-8 format.
-
-One might think that C<\s> is equivalent to C<[\h\v]>. This is not true.
-The difference is that the vertical tab (C<"\x0b">) is not matched by
-C<\s>; it is however considered vertical whitespace.
-
-The following table is a complete listing of characters matched by
-C<\s>, C<\h> and C<\v> as of Unicode 6.0.
-
-The first column gives the Unicode code point of the character (in hex format),
-the second column gives the (Unicode) name. The third column indicates
-by which class(es) the character is matched (assuming no locale or EBCDIC code
-page is in effect that changes the C<\s> matching).
-
- 0x0009 CHARACTER TABULATION h s
- 0x000a LINE FEED (LF) vs
- 0x000b LINE TABULATION v
- 0x000c FORM FEED (FF) vs
- 0x000d CARRIAGE RETURN (CR) vs
- 0x0020 SPACE h s
- 0x0085 NEXT LINE (NEL) vs [1]
- 0x00a0 NO-BREAK SPACE h s [1]
- 0x1680 OGHAM SPACE MARK h s
- 0x180e MONGOLIAN VOWEL SEPARATOR h s
- 0x2000 EN QUAD h s
- 0x2001 EM QUAD h s
- 0x2002 EN SPACE h s
- 0x2003 EM SPACE h s
- 0x2004 THREE-PER-EM SPACE h s
- 0x2005 FOUR-PER-EM SPACE h s
- 0x2006 SIX-PER-EM SPACE h s
- 0x2007 FIGURE SPACE h s
- 0x2008 PUNCTUATION SPACE h s
- 0x2009 THIN SPACE h s
- 0x200a HAIR SPACE h s
- 0x2028 LINE SEPARATOR vs
- 0x2029 PARAGRAPH SEPARATOR vs
- 0x202f NARROW NO-BREAK SPACE h s
- 0x205f MEDIUM MATHEMATICAL SPACE h s
- 0x3000 IDEOGRAPHIC SPACE h s
-
-=over 4
-
-=item [1]
-
-NEXT LINE and NO-BREAK SPACE may or may not match C<\s> depending
-on the rules in effect. See
-L<the beginning of this section|/Whitespace>.
-
-=back
-
-=head3 Unicode Properties
-
-C<\pP> and C<\p{Prop}> are character classes to match characters that fit given
-Unicode properties. One letter property names can be used in the C<\pP> form,
-with the property name following the C<\p>, otherwise, braces are required.
-When using braces, there is a single form, which is just the property name
-enclosed in the braces, and a compound form which looks like C<\p{name=value}>,
-which means to match if the property "name" for the character has that particular
-"value".
-For instance, a match for a number can be written as C</\pN/> or as
-C</\p{Number}/>, or as C</\p{Number=True}/>.
-Lowercase letters are matched by the property I<Lowercase_Letter> which
-has the short form I<Ll>. They need the braces, so are written as C</\p{Ll}/> or
-C</\p{Lowercase_Letter}/>, or C</\p{General_Category=Lowercase_Letter}/>
-(the underscores are optional).
-C</\pLl/> is valid, but means something different.
-It matches a two character string: a letter (Unicode property C<\pL>),
-followed by a lowercase C<l>.
-
-If neither the C</a> modifier nor locale rules are in effect, the use of
-a Unicode property will force the regular expression into using Unicode
-rules.
-
-Note that almost all properties are immune to case-insensitive matching.
-That is, adding a C</i> regular expression modifier does not change what
-they match. There are two sets that are affected. The first set is
-C<Uppercase_Letter>,
-C<Lowercase_Letter>,
-and C<Titlecase_Letter>,
-all of which match C<Cased_Letter> under C</i> matching.
-The second set is
-C<Uppercase>,
-C<Lowercase>,
-and C<Titlecase>,
-all of which match C<Cased> under C</i> matching.
-(The difference between these sets is that some things, such as Roman
-numerals, come in both upper and lower case, so they are C<Cased>, but
-aren't considered to be letters, so they aren't C<Cased_Letter>s. They're
-actually C<Letter_Number>s.)
-This set also includes its subsets C<PosixUpper> and C<PosixLower>, both
-of which under C</i> match C<PosixAlpha>.
-
-For more details on Unicode properties, see L<perlunicode/Unicode
-Character Properties>; for a
-complete list of possible properties, see
-L<perluniprops/Properties accessible through \p{} and \P{}>,
-which notes all forms that have C</i> differences.
-It is also possible to define your own properties. This is discussed in
-L<perlunicode/User-Defined Character Properties>.
-
-Unicode properties are defined (surprise!) only on Unicode code points.
-A warning is raised and all matches fail on non-Unicode code points
-(those above the legal Unicode maximum of 0x10FFFF). This can be
-somewhat surprising,
-
- chr(0x110000) =~ \p{ASCII_Hex_Digit=True} # Fails.
- chr(0x110000) =~ \p{ASCII_Hex_Digit=False} # Also fails!
-
-Even though these two matches might be thought of as complements, they
-are so only on Unicode code points.
-
-=head4 Examples
-
- "a" =~ /\w/ # Match, "a" is a 'word' character.
- "7" =~ /\w/ # Match, "7" is a 'word' character as well.
- "a" =~ /\d/ # No match, "a" isn't a digit.
- "7" =~ /\d/ # Match, "7" is a digit.
- " " =~ /\s/ # Match, a space is whitespace.
- "a" =~ /\D/ # Match, "a" is a non-digit.
- "7" =~ /\D/ # No match, "7" is not a non-digit.
- " " =~ /\S/ # No match, a space is not non-whitespace.
-
- " " =~ /\h/ # Match, space is horizontal whitespace.
- " " =~ /\v/ # No match, space is not vertical whitespace.
- "\r" =~ /\v/ # Match, a return is vertical whitespace.
-
- "a" =~ /\pL/ # Match, "a" is a letter.
- "a" =~ /\p{Lu}/ # No match, /\p{Lu}/ matches upper case letters.
-
- "\x{0e0b}" =~ /\p{Thai}/ # Match, \x{0e0b} is the character
- # 'THAI CHARACTER SO SO', and that's in
- # Thai Unicode class.
- "a" =~ /\P{Lao}/ # Match, as "a" is not a Laotian character.
-
-It is worth emphasizing that C<\d>, C<\w>, etc, match single characters, not
-complete numbers or words. To match a number (that consists of digits),
-use C<\d+>; to match a word, use C<\w+>. But be aware of the security
-considerations in doing so, as mentioned above.
-
-=head2 Bracketed Character Classes
-
-The third form of character class you can use in Perl regular expressions
-is the bracketed character class. In its simplest form, it lists the characters
-that may be matched, surrounded by square brackets, like this: C<[aeiou]>.
-This matches one of C<a>, C<e>, C<i>, C<o> or C<u>. Like the other
-character classes, exactly one character is matched.* To match
-a longer string consisting of characters mentioned in the character
-class, follow the character class with a L<quantifier|perlre/Quantifiers>. For
-instance, C<[aeiou]+> matches one or more lowercase English vowels.
-
-Repeating a character in a character class has no
-effect; it's considered to be in the set only once.
-
-Examples:
-
- "e" =~ /[aeiou]/ # Match, as "e" is listed in the class.
- "p" =~ /[aeiou]/ # No match, "p" is not listed in the class.
- "ae" =~ /^[aeiou]$/ # No match, a character class only matches
- # a single character.
- "ae" =~ /^[aeiou]+$/ # Match, due to the quantifier.
-
- -------
-
-* There is an exception to a bracketed character class matching a
-single character only. When the class is to match caselessly under C</i>
-matching rules, and a character inside the class matches a
-multiple-character sequence caselessly under Unicode rules, the class
-(when not L<inverted|/Negation>) will also match that sequence. For
-example, Unicode says that the letter C<LATIN SMALL LETTER SHARP S>
-should match the sequence C<ss> under C</i> rules. Thus,
-
- 'ss' =~ /\A\N{LATIN SMALL LETTER SHARP S}\z/i # Matches
- 'ss' =~ /\A[aeioust\N{LATIN SMALL LETTER SHARP S}]\z/i # Matches
-
-=head3 Special Characters Inside a Bracketed Character Class
-
-Most characters that are meta characters in regular expressions (that
-is, characters that carry a special meaning like C<.>, C<*>, or C<(>) lose
-their special meaning and can be used inside a character class without
-the need to escape them. For instance, C<[()]> matches either an opening
-parenthesis, or a closing parenthesis, and the parens inside the character
-class don't group or capture.
-
-Characters that may carry a special meaning inside a character class are:
-C<\>, C<^>, C<->, C<[> and C<]>, and are discussed below. They can be
-escaped with a backslash, although this is sometimes not needed, in which
-case the backslash may be omitted.
-
-The sequence C<\b> is special inside a bracketed character class. While
-outside the character class, C<\b> is an assertion indicating a point
-that does not have either two word characters or two non-word characters
-on either side, inside a bracketed character class, C<\b> matches a
-backspace character.
-
-The sequences
-C<\a>,
-C<\c>,
-C<\e>,
-C<\f>,
-C<\n>,
-C<\N{I<NAME>}>,
-C<\N{U+I<hex char>}>,
-C<\r>,
-C<\t>,
-and
-C<\x>
-are also special and have the same meanings as they do outside a
-bracketed character class. (However, inside a bracketed character
-class, if C<\N{I<NAME>}> expands to a sequence of characters, only the first
-one in the sequence is used, with a warning.)
-
-Also, a backslash followed by two or three octal digits is considered an octal
-number.
-
-A C<[> is not special inside a character class, unless it's the start of a
-POSIX character class (see L</POSIX Character Classes> below). It normally does
-not need escaping.
-
-A C<]> is normally either the end of a POSIX character class (see
-L</POSIX Character Classes> below), or it signals the end of the bracketed
-character class. If you want to include a C<]> in the set of characters, you
-must generally escape it.
-
-However, if the C<]> is the I<first> (or the second if the first
-character is a caret) character of a bracketed character class, it
-does not denote the end of the class (as you cannot have an empty class)
-and is considered part of the set of characters that can be matched without
-escaping.
-
-Examples:
-
- "+" =~ /[+?*]/ # Match, "+" in a character class is not special.
- "\cH" =~ /[\b]/ # Match, \b inside in a character class
- # is equivalent to a backspace.
- "]" =~ /[][]/ # Match, as the character class contains.
- # both [ and ].
- "[]" =~ /[[]]/ # Match, the pattern contains a character class
- # containing just ], and the character class is
- # followed by a ].
-
-=head3 Character Ranges
-
-It is not uncommon to want to match a range of characters. Luckily, instead
-of listing all characters in the range, one may use the hyphen (C<->).
-If inside a bracketed character class you have two characters separated
-by a hyphen, it's treated as if all characters between the two were in
-the class. For instance, C<[0-9]> matches any ASCII digit, and C<[a-m]>
-matches any lowercase letter from the first half of the ASCII alphabet.
-
-Note that the two characters on either side of the hyphen are not
-necessarily both letters or both digits. Any character is possible,
-although not advisable. C<['-?]> contains a range of characters, but
-most people will not know which characters that means. Furthermore,
-such ranges may lead to portability problems if the code has to run on
-a platform that uses a different character set, such as EBCDIC.
-
-If a hyphen in a character class cannot syntactically be part of a range, for
-instance because it is the first or the last character of the character class,
-or if it immediately follows a range, the hyphen isn't special, and so is
-considered a character to be matched literally. If you want a hyphen in
-your set of characters to be matched and its position in the class is such
-that it could be considered part of a range, you must escape that hyphen
-with a backslash.
-
-Examples:
-
- [a-z] # Matches a character that is a lower case ASCII letter.
- [a-fz] # Matches any letter between 'a' and 'f' (inclusive) or
- # the letter 'z'.
- [-z] # Matches either a hyphen ('-') or the letter 'z'.
- [a-f-m] # Matches any letter between 'a' and 'f' (inclusive), the
- # hyphen ('-'), or the letter 'm'.
- ['-?] # Matches any of the characters '()*+,-./0123456789:;<=>?
- # (But not on an EBCDIC platform).
-
-
-=head3 Negation
-
-It is also possible to instead list the characters you do not want to
-match. You can do so by using a caret (C<^>) as the first character in the
-character class. For instance, C<[^a-z]> matches any character that is not a
-lowercase ASCII letter, which therefore includes more than a million
-Unicode code points. The class is said to be "negated" or "inverted".
-
-This syntax make the caret a special character inside a bracketed character
-class, but only if it is the first character of the class. So if you want
-the caret as one of the characters to match, either escape the caret or
-else don't list it first.
-
-In inverted bracketed character classes, Perl ignores the Unicode rules
-that normally say that certain characters should match a sequence of
-multiple characters under caseless C</i> matching. Following those
-rules could lead to highly confusing situations:
-
- "ss" =~ /^[^\xDF]+$/ui; # Matches!
-
-This should match any sequences of characters that aren't C<\xDF> nor
-what C<\xDF> matches under C</i>. C<"s"> isn't C<\xDF>, but Unicode
-says that C<"ss"> is what C<\xDF> matches under C</i>. So which one
-"wins"? Do you fail the match because the string has C<ss> or accept it
-because it has an C<s> followed by another C<s>? Perl has chosen the
-latter.
-
-Examples:
-
- "e" =~ /[^aeiou]/ # No match, the 'e' is listed.
- "x" =~ /[^aeiou]/ # Match, as 'x' isn't a lowercase vowel.
- "^" =~ /[^^]/ # No match, matches anything that isn't a caret.
- "^" =~ /[x^]/ # Match, caret is not special here.
-
-=head3 Backslash Sequences
-
-You can put any backslash sequence character class (with the exception of
-C<\N> and C<\R>) inside a bracketed character class, and it will act just
-as if you had put all characters matched by the backslash sequence inside the
-character class. For instance, C<[a-f\d]> matches any decimal digit, or any
-of the lowercase letters between 'a' and 'f' inclusive.
-
-C<\N> within a bracketed character class must be of the forms C<\N{I<name>}>
-or C<\N{U+I<hex char>}>, and NOT be the form that matches non-newlines,
-for the same reason that a dot C<.> inside a bracketed character class loses
-its special meaning: it matches nearly anything, which generally isn't what you
-want to happen.
-
-
-Examples:
-
- /[\p{Thai}\d]/ # Matches a character that is either a Thai
- # character, or a digit.
- /[^\p{Arabic}()]/ # Matches a character that is neither an Arabic
- # character, nor a parenthesis.
-
-Backslash sequence character classes cannot form one of the endpoints
-of a range. Thus, you can't say:
-
- /[\p{Thai}-\d]/ # Wrong!
-
-=head3 POSIX Character Classes
-X<character class> X<\p> X<\p{}>
-X<alpha> X<alnum> X<ascii> X<blank> X<cntrl> X<digit> X<graph>
-X<lower> X<print> X<punct> X<space> X<upper> X<word> X<xdigit>
-
-POSIX character classes have the form C<[:class:]>, where I<class> is
-name, and the C<[:> and C<:]> delimiters. POSIX character classes only appear
-I<inside> bracketed character classes, and are a convenient and descriptive
-way of listing a group of characters.
-
-Be careful about the syntax,
-
- # Correct:
- $string =~ /[[:alpha:]]/
-
- # Incorrect (will warn):
- $string =~ /[:alpha:]/
-
-The latter pattern would be a character class consisting of a colon,
-and the letters C<a>, C<l>, C<p> and C<h>.
-POSIX character classes can be part of a larger bracketed character class.
-For example,
-
- [01[:alpha:]%]
-
-is valid and matches '0', '1', any alphabetic character, and the percent sign.
-
-Perl recognizes the following POSIX character classes:
-
- alpha Any alphabetical character ("[A-Za-z]").
- alnum Any alphanumeric character. ("[A-Za-z0-9]")
- ascii Any character in the ASCII character set.
- blank A GNU extension, equal to a space or a horizontal tab ("\t").
- cntrl Any control character. See Note [2] below.
- digit Any decimal digit ("[0-9]"), equivalent to "\d".
- graph Any printable character, excluding a space. See Note [3] below.
- lower Any lowercase character ("[a-z]").
- print Any printable character, including a space. See Note [4] below.
- punct Any graphical character excluding "word" characters. Note [5].
- space Any whitespace character. "\s" plus the vertical tab ("\cK").
- upper Any uppercase character ("[A-Z]").
- word A Perl extension ("[A-Za-z0-9_]"), equivalent to "\w".
- xdigit Any hexadecimal digit ("[0-9a-fA-F]").
-
-Most POSIX character classes have two Unicode-style C<\p> property
-counterparts. (They are not official Unicode properties, but Perl extensions
-derived from official Unicode properties.) The table below shows the relation
-between POSIX character classes and these counterparts.
-
-One counterpart, in the column labelled "ASCII-range Unicode" in
-the table, matches only characters in the ASCII character set.
-
-The other counterpart, in the column labelled "Full-range Unicode", matches any
-appropriate characters in the full Unicode character set. For example,
-C<\p{Alpha}> matches not just the ASCII alphabetic characters, but any
-character in the entire Unicode character set considered alphabetic.
-An entry in the column labelled "backslash sequence" is a (short)
-equivalent.
-
- [[:...:]] ASCII-range Full-range backslash Note
- Unicode Unicode sequence
- -----------------------------------------------------
- alpha \p{PosixAlpha} \p{XPosixAlpha}
- alnum \p{PosixAlnum} \p{XPosixAlnum}
- ascii \p{ASCII}
- blank \p{PosixBlank} \p{XPosixBlank} \h [1]
- or \p{HorizSpace} [1]
- cntrl \p{PosixCntrl} \p{XPosixCntrl} [2]
- digit \p{PosixDigit} \p{XPosixDigit} \d
- graph \p{PosixGraph} \p{XPosixGraph} [3]
- lower \p{PosixLower} \p{XPosixLower}
- print \p{PosixPrint} \p{XPosixPrint} [4]
- punct \p{PosixPunct} \p{XPosixPunct} [5]
- \p{PerlSpace} \p{XPerlSpace} \s [6]
- space \p{PosixSpace} \p{XPosixSpace} [6]
- upper \p{PosixUpper} \p{XPosixUpper}
- word \p{PosixWord} \p{XPosixWord} \w
- xdigit \p{PosixXDigit} \p{XPosixXDigit}
-
-=over 4
-
-=item [1]
-
-C<\p{Blank}> and C<\p{HorizSpace}> are synonyms.
-
-=item [2]
-
-Control characters don't produce output as such, but instead usually control
-the terminal somehow: for example, newline and backspace are control characters.
-In the ASCII range, characters whose code points are between 0 and 31 inclusive,
-plus 127 (C<DEL>) are control characters.
-
-On EBCDIC platforms, it is likely that the code page will define C<[[:cntrl:]]>
-to be the EBCDIC equivalents of the ASCII controls, plus the controls
-that in Unicode have code pointss from 128 through 159.
-
-=item [3]
-
-Any character that is I<graphical>, that is, visible. This class consists
-of all alphanumeric characters and all punctuation characters.
-
-=item [4]
-
-All printable characters, which is the set of all graphical characters
-plus those whitespace characters which are not also controls.
-
-=item [5]
-
-C<\p{PosixPunct}> and C<[[:punct:]]> in the ASCII range match all
-non-controls, non-alphanumeric, non-space characters:
-C<[-!"#$%&'()*+,./:;<=E<gt>?@[\\\]^_`{|}~]> (although if a locale is in effect,
-it could alter the behavior of C<[[:punct:]]>).
-
-The similarly named property, C<\p{Punct}>, matches a somewhat different
-set in the ASCII range, namely
-C<[-!"#%&'()*,./:;?@[\\\]_{}]>. That is, it is missing the nine
-characters C<[$+E<lt>=E<gt>^`|~]>.
-This is because Unicode splits what POSIX considers to be punctuation into two
-categories, Punctuation and Symbols.
-
-C<\p{XPosixPunct}> and (under Unicode rules) C<[[:punct:]]>, match what
-C<\p{PosixPunct}> matches in the ASCII range, plus what C<\p{Punct}>
-matches. This is different than strictly matching according to
-C<\p{Punct}>. Another way to say it is that
-if Unicode rules are in effect, C<[[:punct:]]> matches all characters
-that Unicode considers punctuation, plus all ASCII-range characters that
-Unicode considers symbols.
-
-=item [6]
-
-C<\p{SpacePerl}> and C<\p{Space}> differ only in that in non-locale
-matching, C<\p{Space}> additionally
-matches the vertical tab, C<\cK>. Same for the two ASCII-only range forms.
-
-=back
-
-There are various other synonyms that can be used besides the names
-listed in the table. For example, C<\p{PosixAlpha}> can be written as
-C<\p{Alpha}>. All are listed in
-L<perluniprops/Properties accessible through \p{} and \P{}>,
-plus all characters matched by each ASCII-range property.
-
-Both the C<\p> counterparts always assume Unicode rules are in effect.
-On ASCII platforms, this means they assume that the code points from 128
-to 255 are Latin-1, and that means that using them under locale rules is
-unwise unless the locale is guaranteed to be Latin-1 or UTF-8. In contrast, the
-POSIX character classes are useful under locale rules. They are
-affected by the actual rules in effect, as follows:
-
-=over
-
-=item If the C</a> modifier, is in effect ...
-
-Each of the POSIX classes matches exactly the same as their ASCII-range
-counterparts.
-
-=item otherwise ...
-
-=over
-
-=item For code points above 255 ...
-
-The POSIX class matches the same as its Full-range counterpart.
-
-=item For code points below 256 ...
-
-=over
-
-=item if locale rules are in effect ...
-
-The POSIX class matches according to the locale, except that
-C<word> uses the platform's native underscore character, no matter what
-the locale is.
-
-=item if Unicode rules are in effect or if on an EBCDIC platform ...
-
-The POSIX class matches the same as the Full-range counterpart.
-
-=item otherwise ...
-
-The POSIX class matches the same as the ASCII range counterpart.
-
-=back
-
-=back
-
-=back
-
-Which rules apply are determined as described in
-L<perlre/Which character set modifier is in effect?>.
-
-It is proposed to change this behavior in a future release of Perl so that
-whether or not Unicode rules are in effect would not change the
-behavior: Outside of locale or an EBCDIC code page, the POSIX classes
-would behave like their ASCII-range counterparts. If you wish to
-comment on this proposal, send email to C<perl5-porters@perl.org>.
-
-=head4 Negation of POSIX character classes
-X<character class, negation>
-
-A Perl extension to the POSIX character class is the ability to
-negate it. This is done by prefixing the class name with a caret (C<^>).
-Some examples:
-
- POSIX ASCII-range Full-range backslash
- Unicode Unicode sequence
- -----------------------------------------------------
- [[:^digit:]] \P{PosixDigit} \P{XPosixDigit} \D
- [[:^space:]] \P{PosixSpace} \P{XPosixSpace}
- \P{PerlSpace} \P{XPerlSpace} \S
- [[:^word:]] \P{PerlWord} \P{XPosixWord} \W
-
-The backslash sequence can mean either ASCII- or Full-range Unicode,
-depending on various factors as described in L<perlre/Which character set modifier is in effect?>.
-
-=head4 [= =] and [. .]
-
-Perl recognizes the POSIX character classes C<[=class=]> and
-C<[.class.]>, but does not (yet?) support them. Any attempt to use
-either construct raises an exception.
-
-=head4 Examples
-
- /[[:digit:]]/ # Matches a character that is a digit.
- /[01[:lower:]]/ # Matches a character that is either a
- # lowercase letter, or '0' or '1'.
- /[[:digit:][:^xdigit:]]/ # Matches a character that can be anything
- # except the letters 'a' to 'f'. This is
- # because the main character class is composed
- # of two POSIX character classes that are ORed
- # together, one that matches any digit, and
- # the other that matches anything that isn't a
- # hex digit. The result matches all
- # characters except the letters 'a' to 'f' and
- # 'A' to 'F'.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlref.pod b/Master/tlpkg/tlperl/lib/pods/perlref.pod
deleted file mode 100644
index 0fab80969aa..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlref.pod
+++ /dev/null
@@ -1,751 +0,0 @@
-=head1 NAME
-X<reference> X<pointer> X<data structure> X<structure> X<struct>
-
-perlref - Perl references and nested data structures
-
-=head1 NOTE
-
-This is complete documentation about all aspects of references.
-For a shorter, tutorial introduction to just the essential features,
-see L<perlreftut>.
-
-=head1 DESCRIPTION
-
-Before release 5 of Perl it was difficult to represent complex data
-structures, because all references had to be symbolic--and even then
-it was difficult to refer to a variable instead of a symbol table entry.
-Perl now not only makes it easier to use symbolic references to variables,
-but also lets you have "hard" references to any piece of data or code.
-Any scalar may hold a hard reference. Because arrays and hashes contain
-scalars, you can now easily build arrays of arrays, arrays of hashes,
-hashes of arrays, arrays of hashes of functions, and so on.
-
-Hard references are smart--they keep track of reference counts for you,
-automatically freeing the thing referred to when its reference count goes
-to zero. (Reference counts for values in self-referential or
-cyclic data structures may not go to zero without a little help; see
-L</"Circular References"> for a detailed explanation.)
-If that thing happens to be an object, the object is destructed. See
-L<perlobj> for more about objects. (In a sense, everything in Perl is an
-object, but we usually reserve the word for references to objects that
-have been officially "blessed" into a class package.)
-
-Symbolic references are names of variables or other objects, just as a
-symbolic link in a Unix filesystem contains merely the name of a file.
-The C<*glob> notation is something of a symbolic reference. (Symbolic
-references are sometimes called "soft references", but please don't call
-them that; references are confusing enough without useless synonyms.)
-X<reference, symbolic> X<reference, soft>
-X<symbolic reference> X<soft reference>
-
-In contrast, hard references are more like hard links in a Unix file
-system: They are used to access an underlying object without concern for
-what its (other) name is. When the word "reference" is used without an
-adjective, as in the following paragraph, it is usually talking about a
-hard reference.
-X<reference, hard> X<hard reference>
-
-References are easy to use in Perl. There is just one overriding
-principle: Perl does no implicit referencing or dereferencing. When a
-scalar is holding a reference, it always behaves as a simple scalar. It
-doesn't magically start being an array or hash or subroutine; you have to
-tell it explicitly to do so, by dereferencing it.
-
-References are easy to use in Perl. There is just one overriding
-principle: in general, Perl does no implicit referencing or dereferencing.
-When a scalar is holding a reference, it always behaves as a simple scalar.
-It doesn't magically start being an array or hash or subroutine; you have to
-tell it explicitly to do so, by dereferencing it.
-
-That said, be aware that Perl version 5.14 introduces an exception
-to the rule, for syntactic convenience. Experimental array and hash container
-function behavior allows array and hash references to be handled by Perl as
-if they had been explicitly syntactically dereferenced. See
-L<perl5140delta/"Syntactical Enhancements">
-and L<perlfunc> for details.
-
-=head2 Making References
-X<reference, creation> X<referencing>
-
-References can be created in several ways.
-
-=over 4
-
-=item 1.
-X<\> X<backslash>
-
-By using the backslash operator on a variable, subroutine, or value.
-(This works much like the & (address-of) operator in C.)
-This typically creates I<another> reference to a variable, because
-there's already a reference to the variable in the symbol table. But
-the symbol table reference might go away, and you'll still have the
-reference that the backslash returned. Here are some examples:
-
- $scalarref = \$foo;
- $arrayref = \@ARGV;
- $hashref = \%ENV;
- $coderef = \&handler;
- $globref = \*foo;
-
-It isn't possible to create a true reference to an IO handle (filehandle
-or dirhandle) using the backslash operator. The most you can get is a
-reference to a typeglob, which is actually a complete symbol table entry.
-But see the explanation of the C<*foo{THING}> syntax below. However,
-you can still use type globs and globrefs as though they were IO handles.
-
-=item 2.
-X<array, anonymous> X<[> X<[]> X<square bracket>
-X<bracket, square> X<arrayref> X<array reference> X<reference, array>
-
-A reference to an anonymous array can be created using square
-brackets:
-
- $arrayref = [1, 2, ['a', 'b', 'c']];
-
-Here we've created a reference to an anonymous array of three elements
-whose final element is itself a reference to another anonymous array of three
-elements. (The multidimensional syntax described later can be used to
-access this. For example, after the above, C<< $arrayref->[2][1] >> would have
-the value "b".)
-
-Taking a reference to an enumerated list is not the same
-as using square brackets--instead it's the same as creating
-a list of references!
-
- @list = (\$a, \@b, \%c);
- @list = \($a, @b, %c); # same thing!
-
-As a special case, C<\(@foo)> returns a list of references to the contents
-of C<@foo>, not a reference to C<@foo> itself. Likewise for C<%foo>,
-except that the key references are to copies (since the keys are just
-strings rather than full-fledged scalars).
-
-=item 3.
-X<hash, anonymous> X<{> X<{}> X<curly bracket>
-X<bracket, curly> X<brace> X<hashref> X<hash reference> X<reference, hash>
-
-A reference to an anonymous hash can be created using curly
-brackets:
-
- $hashref = {
- 'Adam' => 'Eve',
- 'Clyde' => 'Bonnie',
- };
-
-Anonymous hash and array composers like these can be intermixed freely to
-produce as complicated a structure as you want. The multidimensional
-syntax described below works for these too. The values above are
-literals, but variables and expressions would work just as well, because
-assignment operators in Perl (even within local() or my()) are executable
-statements, not compile-time declarations.
-
-Because curly brackets (braces) are used for several other things
-including BLOCKs, you may occasionally have to disambiguate braces at the
-beginning of a statement by putting a C<+> or a C<return> in front so
-that Perl realizes the opening brace isn't starting a BLOCK. The economy and
-mnemonic value of using curlies is deemed worth this occasional extra
-hassle.
-
-For example, if you wanted a function to make a new hash and return a
-reference to it, you have these options:
-
- sub hashem { { @_ } } # silently wrong
- sub hashem { +{ @_ } } # ok
- sub hashem { return { @_ } } # ok
-
-On the other hand, if you want the other meaning, you can do this:
-
- sub showem { { @_ } } # ambiguous (currently ok, but may change)
- sub showem { {; @_ } } # ok
- sub showem { { return @_ } } # ok
-
-The leading C<+{> and C<{;> always serve to disambiguate
-the expression to mean either the HASH reference, or the BLOCK.
-
-=item 4.
-X<subroutine, anonymous> X<subroutine, reference> X<reference, subroutine>
-X<scope, lexical> X<closure> X<lexical> X<lexical scope>
-
-A reference to an anonymous subroutine can be created by using
-C<sub> without a subname:
-
- $coderef = sub { print "Boink!\n" };
-
-Note the semicolon. Except for the code
-inside not being immediately executed, a C<sub {}> is not so much a
-declaration as it is an operator, like C<do{}> or C<eval{}>. (However, no
-matter how many times you execute that particular line (unless you're in an
-C<eval("...")>), $coderef will still have a reference to the I<same>
-anonymous subroutine.)
-
-Anonymous subroutines act as closures with respect to my() variables,
-that is, variables lexically visible within the current scope. Closure
-is a notion out of the Lisp world that says if you define an anonymous
-function in a particular lexical context, it pretends to run in that
-context even when it's called outside the context.
-
-In human terms, it's a funny way of passing arguments to a subroutine when
-you define it as well as when you call it. It's useful for setting up
-little bits of code to run later, such as callbacks. You can even
-do object-oriented stuff with it, though Perl already provides a different
-mechanism to do that--see L<perlobj>.
-
-You might also think of closure as a way to write a subroutine
-template without using eval(). Here's a small example of how
-closures work:
-
- sub newprint {
- my $x = shift;
- return sub { my $y = shift; print "$x, $y!\n"; };
- }
- $h = newprint("Howdy");
- $g = newprint("Greetings");
-
- # Time passes...
-
- &$h("world");
- &$g("earthlings");
-
-This prints
-
- Howdy, world!
- Greetings, earthlings!
-
-Note particularly that $x continues to refer to the value passed
-into newprint() I<despite> "my $x" having gone out of scope by the
-time the anonymous subroutine runs. That's what a closure is all
-about.
-
-This applies only to lexical variables, by the way. Dynamic variables
-continue to work as they have always worked. Closure is not something
-that most Perl programmers need trouble themselves about to begin with.
-
-=item 5.
-X<constructor> X<new>
-
-References are often returned by special subroutines called constructors. Perl
-objects are just references to a special type of object that happens to know
-which package it's associated with. Constructors are just special subroutines
-that know how to create that association. They do so by starting with an
-ordinary reference, and it remains an ordinary reference even while it's also
-being an object. Constructors are often named C<new()>. You I<can> call them
-indirectly:
-
- $objref = new Doggie( Tail => 'short', Ears => 'long' );
-
-But that can produce ambiguous syntax in certain cases, so it's often
-better to use the direct method invocation approach:
-
- $objref = Doggie->new(Tail => 'short', Ears => 'long');
-
- use Term::Cap;
- $terminal = Term::Cap->Tgetent( { OSPEED => 9600 });
-
- use Tk;
- $main = MainWindow->new();
- $menubar = $main->Frame(-relief => "raised",
- -borderwidth => 2)
-
-=item 6.
-X<autovivification>
-
-References of the appropriate type can spring into existence if you
-dereference them in a context that assumes they exist. Because we haven't
-talked about dereferencing yet, we can't show you any examples yet.
-
-=item 7.
-X<*foo{THING}> X<*>
-
-A reference can be created by using a special syntax, lovingly known as
-the *foo{THING} syntax. *foo{THING} returns a reference to the THING
-slot in *foo (which is the symbol table entry which holds everything
-known as foo).
-
- $scalarref = *foo{SCALAR};
- $arrayref = *ARGV{ARRAY};
- $hashref = *ENV{HASH};
- $coderef = *handler{CODE};
- $ioref = *STDIN{IO};
- $globref = *foo{GLOB};
- $formatref = *foo{FORMAT};
-
-All of these are self-explanatory except for C<*foo{IO}>. It returns
-the IO handle, used for file handles (L<perlfunc/open>), sockets
-(L<perlfunc/socket> and L<perlfunc/socketpair>), and directory
-handles (L<perlfunc/opendir>). For compatibility with previous
-versions of Perl, C<*foo{FILEHANDLE}> is a synonym for C<*foo{IO}>, though it
-is deprecated as of 5.8.0. If deprecation warnings are in effect, it will warn
-of its use.
-
-C<*foo{THING}> returns undef if that particular THING hasn't been used yet,
-except in the case of scalars. C<*foo{SCALAR}> returns a reference to an
-anonymous scalar if $foo hasn't been used yet. This might change in a
-future release.
-
-C<*foo{IO}> is an alternative to the C<*HANDLE> mechanism given in
-L<perldata/"Typeglobs and Filehandles"> for passing filehandles
-into or out of subroutines, or storing into larger data structures.
-Its disadvantage is that it won't create a new filehandle for you.
-Its advantage is that you have less risk of clobbering more than
-you want to with a typeglob assignment. (It still conflates file
-and directory handles, though.) However, if you assign the incoming
-value to a scalar instead of a typeglob as we do in the examples
-below, there's no risk of that happening.
-
- splutter(*STDOUT); # pass the whole glob
- splutter(*STDOUT{IO}); # pass both file and dir handles
-
- sub splutter {
- my $fh = shift;
- print $fh "her um well a hmmm\n";
- }
-
- $rec = get_rec(*STDIN); # pass the whole glob
- $rec = get_rec(*STDIN{IO}); # pass both file and dir handles
-
- sub get_rec {
- my $fh = shift;
- return scalar <$fh>;
- }
-
-=back
-
-=head2 Using References
-X<reference, use> X<dereferencing> X<dereference>
-
-That's it for creating references. By now you're probably dying to
-know how to use references to get back to your long-lost data. There
-are several basic methods.
-
-=over 4
-
-=item 1.
-
-Anywhere you'd put an identifier (or chain of identifiers) as part
-of a variable or subroutine name, you can replace the identifier with
-a simple scalar variable containing a reference of the correct type:
-
- $bar = $$scalarref;
- push(@$arrayref, $filename);
- $$arrayref[0] = "January";
- $$hashref{"KEY"} = "VALUE";
- &$coderef(1,2,3);
- print $globref "output\n";
-
-It's important to understand that we are specifically I<not> dereferencing
-C<$arrayref[0]> or C<$hashref{"KEY"}> there. The dereference of the
-scalar variable happens I<before> it does any key lookups. Anything more
-complicated than a simple scalar variable must use methods 2 or 3 below.
-However, a "simple scalar" includes an identifier that itself uses method
-1 recursively. Therefore, the following prints "howdy".
-
- $refrefref = \\\"howdy";
- print $$$$refrefref;
-
-=item 2.
-
-Anywhere you'd put an identifier (or chain of identifiers) as part of a
-variable or subroutine name, you can replace the identifier with a
-BLOCK returning a reference of the correct type. In other words, the
-previous examples could be written like this:
-
- $bar = ${$scalarref};
- push(@{$arrayref}, $filename);
- ${$arrayref}[0] = "January";
- ${$hashref}{"KEY"} = "VALUE";
- &{$coderef}(1,2,3);
- $globref->print("output\n"); # iff IO::Handle is loaded
-
-Admittedly, it's a little silly to use the curlies in this case, but
-the BLOCK can contain any arbitrary expression, in particular,
-subscripted expressions:
-
- &{ $dispatch{$index} }(1,2,3); # call correct routine
-
-Because of being able to omit the curlies for the simple case of C<$$x>,
-people often make the mistake of viewing the dereferencing symbols as
-proper operators, and wonder about their precedence. If they were,
-though, you could use parentheses instead of braces. That's not the case.
-Consider the difference below; case 0 is a short-hand version of case 1,
-I<not> case 2:
-
- $$hashref{"KEY"} = "VALUE"; # CASE 0
- ${$hashref}{"KEY"} = "VALUE"; # CASE 1
- ${$hashref{"KEY"}} = "VALUE"; # CASE 2
- ${$hashref->{"KEY"}} = "VALUE"; # CASE 3
-
-Case 2 is also deceptive in that you're accessing a variable
-called %hashref, not dereferencing through $hashref to the hash
-it's presumably referencing. That would be case 3.
-
-=item 3.
-
-Subroutine calls and lookups of individual array elements arise often
-enough that it gets cumbersome to use method 2. As a form of
-syntactic sugar, the examples for method 2 may be written:
-
- $arrayref->[0] = "January"; # Array element
- $hashref->{"KEY"} = "VALUE"; # Hash element
- $coderef->(1,2,3); # Subroutine call
-
-The left side of the arrow can be any expression returning a reference,
-including a previous dereference. Note that C<$array[$x]> is I<not> the
-same thing as C<< $array->[$x] >> here:
-
- $array[$x]->{"foo"}->[0] = "January";
-
-This is one of the cases we mentioned earlier in which references could
-spring into existence when in an lvalue context. Before this
-statement, C<$array[$x]> may have been undefined. If so, it's
-automatically defined with a hash reference so that we can look up
-C<{"foo"}> in it. Likewise C<< $array[$x]->{"foo"} >> will automatically get
-defined with an array reference so that we can look up C<[0]> in it.
-This process is called I<autovivification>.
-
-One more thing here. The arrow is optional I<between> brackets
-subscripts, so you can shrink the above down to
-
- $array[$x]{"foo"}[0] = "January";
-
-Which, in the degenerate case of using only ordinary arrays, gives you
-multidimensional arrays just like C's:
-
- $score[$x][$y][$z] += 42;
-
-Well, okay, not entirely like C's arrays, actually. C doesn't know how
-to grow its arrays on demand. Perl does.
-
-=item 4.
-
-If a reference happens to be a reference to an object, then there are
-probably methods to access the things referred to, and you should probably
-stick to those methods unless you're in the class package that defines the
-object's methods. In other words, be nice, and don't violate the object's
-encapsulation without a very good reason. Perl does not enforce
-encapsulation. We are not totalitarians here. We do expect some basic
-civility though.
-
-=back
-
-Using a string or number as a reference produces a symbolic reference,
-as explained above. Using a reference as a number produces an
-integer representing its storage location in memory. The only
-useful thing to be done with this is to compare two references
-numerically to see whether they refer to the same location.
-X<reference, numeric context>
-
- if ($ref1 == $ref2) { # cheap numeric compare of references
- print "refs 1 and 2 refer to the same thing\n";
- }
-
-Using a reference as a string produces both its referent's type,
-including any package blessing as described in L<perlobj>, as well
-as the numeric address expressed in hex. The ref() operator returns
-just the type of thing the reference is pointing to, without the
-address. See L<perlfunc/ref> for details and examples of its use.
-X<reference, string context>
-
-The bless() operator may be used to associate the object a reference
-points to with a package functioning as an object class. See L<perlobj>.
-
-A typeglob may be dereferenced the same way a reference can, because
-the dereference syntax always indicates the type of reference desired.
-So C<${*foo}> and C<${\$foo}> both indicate the same scalar variable.
-
-Here's a trick for interpolating a subroutine call into a string:
-
- print "My sub returned @{[mysub(1,2,3)]} that time.\n";
-
-The way it works is that when the C<@{...}> is seen in the double-quoted
-string, it's evaluated as a block. The block creates a reference to an
-anonymous array containing the results of the call to C<mysub(1,2,3)>. So
-the whole block returns a reference to an array, which is then
-dereferenced by C<@{...}> and stuck into the double-quoted string. This
-chicanery is also useful for arbitrary expressions:
-
- print "That yields @{[$n + 5]} widgets\n";
-
-Similarly, an expression that returns a reference to a scalar can be
-dereferenced via C<${...}>. Thus, the above expression may be written
-as:
-
- print "That yields ${\($n + 5)} widgets\n";
-
-=head2 Circular References
-X<circular reference> X<reference, circular>
-
-It is possible to create a "circular reference" in Perl, which can lead
-to memory leaks. A circular reference occurs when two references
-contain a reference to each other, like this:
-
- my $foo = {};
- my $bar = { foo => $foo };
- $foo->{bar} = $bar;
-
-You can also create a circular reference with a single variable:
-
- my $foo;
- $foo = \$foo;
-
-In this case, the reference count for the variables will never reach 0,
-and the references will never be garbage-collected. This can lead to
-memory leaks.
-
-Because objects in Perl are implemented as references, it's possible to
-have circular references with objects as well. Imagine a TreeNode class
-where each node references its parent and child nodes. Any node with a
-parent will be part of a circular reference.
-
-You can break circular references by creating a "weak reference". A
-weak reference does not increment the reference count for a variable,
-which means that the object can go out of scope and be destroyed. You
-can weaken a reference with the C<weaken> function exported by the
-L<Scalar::Util> module.
-
-Here's how we can make the first example safer:
-
- use Scalar::Util 'weaken';
-
- my $foo = {};
- my $bar = { foo => $foo };
- $foo->{bar} = $bar;
-
- weaken $foo->{bar};
-
-The reference from C<$foo> to C<$bar> has been weakened. When the
-C<$bar> variable goes out of scope, it will be garbage-collected. The
-next time you look at the value of the C<< $foo->{bar} >> key, it will
-be C<undef>.
-
-This action at a distance can be confusing, so you should be careful
-with your use of weaken. You should weaken the reference in the
-variable that will go out of scope I<first>. That way, the longer-lived
-variable will contain the expected reference until it goes out of
-scope.
-
-=head2 Symbolic references
-X<reference, symbolic> X<reference, soft>
-X<symbolic reference> X<soft reference>
-
-We said that references spring into existence as necessary if they are
-undefined, but we didn't say what happens if a value used as a
-reference is already defined, but I<isn't> a hard reference. If you
-use it as a reference, it'll be treated as a symbolic
-reference. That is, the value of the scalar is taken to be the I<name>
-of a variable, rather than a direct link to a (possibly) anonymous
-value.
-
-People frequently expect it to work like this. So it does.
-
- $name = "foo";
- $$name = 1; # Sets $foo
- ${$name} = 2; # Sets $foo
- ${$name x 2} = 3; # Sets $foofoo
- $name->[0] = 4; # Sets $foo[0]
- @$name = (); # Clears @foo
- &$name(); # Calls &foo() (as in Perl 4)
- $pack = "THAT";
- ${"${pack}::$name"} = 5; # Sets $THAT::foo without eval
-
-This is powerful, and slightly dangerous, in that it's possible
-to intend (with the utmost sincerity) to use a hard reference, and
-accidentally use a symbolic reference instead. To protect against
-that, you can say
-
- use strict 'refs';
-
-and then only hard references will be allowed for the rest of the enclosing
-block. An inner block may countermand that with
-
- no strict 'refs';
-
-Only package variables (globals, even if localized) are visible to
-symbolic references. Lexical variables (declared with my()) aren't in
-a symbol table, and thus are invisible to this mechanism. For example:
-
- local $value = 10;
- $ref = "value";
- {
- my $value = 20;
- print $$ref;
- }
-
-This will still print 10, not 20. Remember that local() affects package
-variables, which are all "global" to the package.
-
-=head2 Not-so-symbolic references
-
-Since Perl verion 5.001, brackets around a symbolic reference can simply
-serve to isolate an identifier or variable name from the rest of an
-expression, just as they always have within a string. For example,
-
- $push = "pop on ";
- print "${push}over";
-
-has always meant to print "pop on over", even though push is
-a reserved word. In 5.001, this was generalized to work the same
-without the enclosing double quotes, so that
-
- print ${push} . "over";
-
-and even
-
- print ${ push } . "over";
-
-will have the same effect. (This would have been a syntax error in
-Perl 5.000, though Perl 4 allowed it in the spaceless form.) This
-construct is I<not> considered to be a symbolic reference when you're
-using strict refs:
-
- use strict 'refs';
- ${ bareword }; # Okay, means $bareword.
- ${ "bareword" }; # Error, symbolic reference.
-
-Similarly, because of all the subscripting that is done using single words,
-the same rule applies to any bareword that is used for subscripting a hash.
-So now, instead of writing
-
- $array{ "aaa" }{ "bbb" }{ "ccc" }
-
-you can write just
-
- $array{ aaa }{ bbb }{ ccc }
-
-and not worry about whether the subscripts are reserved words. In the
-rare event that you do wish to do something like
-
- $array{ shift }
-
-you can force interpretation as a reserved word by adding anything that
-makes it more than a bareword:
-
- $array{ shift() }
- $array{ +shift }
- $array{ shift @_ }
-
-The C<use warnings> pragma or the B<-w> switch will warn you if it
-interprets a reserved word as a string.
-But it will no longer warn you about using lowercase words, because the
-string is effectively quoted.
-
-=head2 Pseudo-hashes: Using an array as a hash
-X<pseudo-hash> X<pseudo hash> X<pseudohash>
-
-Pseudo-hashes have been removed from Perl. The 'fields' pragma
-remains available.
-
-=head2 Function Templates
-X<scope, lexical> X<closure> X<lexical> X<lexical scope>
-X<subroutine, nested> X<sub, nested> X<subroutine, local> X<sub, local>
-
-As explained above, an anonymous function with access to the lexical
-variables visible when that function was compiled, creates a closure. It
-retains access to those variables even though it doesn't get run until
-later, such as in a signal handler or a Tk callback.
-
-Using a closure as a function template allows us to generate many functions
-that act similarly. Suppose you wanted functions named after the colors
-that generated HTML font changes for the various colors:
-
- print "Be ", red("careful"), "with that ", green("light");
-
-The red() and green() functions would be similar. To create these,
-we'll assign a closure to a typeglob of the name of the function we're
-trying to build.
-
- @colors = qw(red blue green yellow orange purple violet);
- for my $name (@colors) {
- no strict 'refs'; # allow symbol table manipulation
- *$name = *{uc $name} = sub { "<FONT COLOR='$name'>@_</FONT>" };
- }
-
-Now all those different functions appear to exist independently. You can
-call red(), RED(), blue(), BLUE(), green(), etc. This technique saves on
-both compile time and memory use, and is less error-prone as well, since
-syntax checks happen at compile time. It's critical that any variables in
-the anonymous subroutine be lexicals in order to create a proper closure.
-That's the reasons for the C<my> on the loop iteration variable.
-
-This is one of the only places where giving a prototype to a closure makes
-much sense. If you wanted to impose scalar context on the arguments of
-these functions (probably not a wise idea for this particular example),
-you could have written it this way instead:
-
- *$name = sub ($) { "<FONT COLOR='$name'>$_[0]</FONT>" };
-
-However, since prototype checking happens at compile time, the assignment
-above happens too late to be of much use. You could address this by
-putting the whole loop of assignments within a BEGIN block, forcing it
-to occur during compilation.
-
-Access to lexicals that change over time--like those in the C<for> loop
-above, basically aliases to elements from the surrounding lexical scopes--
-only works with anonymous subs, not with named subroutines. Generally
-said, named subroutines do not nest properly and should only be declared
-in the main package scope.
-
-This is because named subroutines are created at compile time so their
-lexical variables get assigned to the parent lexicals from the first
-execution of the parent block. If a parent scope is entered a second
-time, its lexicals are created again, while the nested subs still
-reference the old ones.
-
-Anonymous subroutines get to capture each time you execute the C<sub>
-operator, as they are created on the fly. If you are accustomed to using
-nested subroutines in other programming languages with their own private
-variables, you'll have to work at it a bit in Perl. The intuitive coding
-of this type of thing incurs mysterious warnings about "will not stay
-shared" due to the reasons explained above.
-For example, this won't work:
-
- sub outer {
- my $x = $_[0] + 35;
- sub inner { return $x * 19 } # WRONG
- return $x + inner();
- }
-
-A work-around is the following:
-
- sub outer {
- my $x = $_[0] + 35;
- local *inner = sub { return $x * 19 };
- return $x + inner();
- }
-
-Now inner() can only be called from within outer(), because of the
-temporary assignments of the anonymous subroutine. But when it does,
-it has normal access to the lexical variable $x from the scope of
-outer() at the time outer is invoked.
-
-This has the interesting effect of creating a function local to another
-function, something not normally supported in Perl.
-
-=head1 WARNING
-X<reference, string context> X<reference, use as hash key>
-
-You may not (usefully) use a reference as the key to a hash. It will be
-converted into a string:
-
- $x{ \$a } = $a;
-
-If you try to dereference the key, it won't do a hard dereference, and
-you won't accomplish what you're attempting. You might want to do something
-more like
-
- $r = \@a;
- $x{ $r } = $r;
-
-And then at least you can use the values(), which will be
-real refs, instead of the keys(), which won't.
-
-The standard Tie::RefHash module provides a convenient workaround to this.
-
-=head1 SEE ALSO
-
-Besides the obvious documents, source code can be instructive.
-Some pathological examples of the use of references can be found
-in the F<t/op/ref.t> regression test in the Perl source directory.
-
-See also L<perldsc> and L<perllol> for how to use references to create
-complex data structures, and L<perlootut> and L<perlobj>
-for how to use them to create objects.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlreftut.pod b/Master/tlpkg/tlperl/lib/pods/perlreftut.pod
deleted file mode 100644
index 9565562711d..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlreftut.pod
+++ /dev/null
@@ -1,527 +0,0 @@
-=head1 NAME
-
-perlreftut - Mark's very short tutorial about references
-
-=head1 DESCRIPTION
-
-One of the most important new features in Perl 5 was the capability to
-manage complicated data structures like multidimensional arrays and
-nested hashes. To enable these, Perl 5 introduced a feature called
-'references', and using references is the key to managing complicated,
-structured data in Perl. Unfortunately, there's a lot of funny syntax
-to learn, and the main manual page can be hard to follow. The manual
-is quite complete, and sometimes people find that a problem, because
-it can be hard to tell what is important and what isn't.
-
-Fortunately, you only need to know 10% of what's in the main page to get
-90% of the benefit. This page will show you that 10%.
-
-=head1 Who Needs Complicated Data Structures?
-
-One problem that came up all the time in Perl 4 was how to represent a
-hash whose values were lists. Perl 4 had hashes, of course, but the
-values had to be scalars; they couldn't be lists.
-
-Why would you want a hash of lists? Let's take a simple example: You
-have a file of city and country names, like this:
-
- Chicago, USA
- Frankfurt, Germany
- Berlin, Germany
- Washington, USA
- Helsinki, Finland
- New York, USA
-
-and you want to produce an output like this, with each country mentioned
-once, and then an alphabetical list of the cities in that country:
-
- Finland: Helsinki.
- Germany: Berlin, Frankfurt.
- USA: Chicago, New York, Washington.
-
-The natural way to do this is to have a hash whose keys are country
-names. Associated with each country name key is a list of the cities in
-that country. Each time you read a line of input, split it into a country
-and a city, look up the list of cities already known to be in that
-country, and append the new city to the list. When you're done reading
-the input, iterate over the hash as usual, sorting each list of cities
-before you print it out.
-
-If hash values can't be lists, you lose. In Perl 4, hash values can't
-be lists; they can only be strings. You lose. You'd probably have to
-combine all the cities into a single string somehow, and then when
-time came to write the output, you'd have to break the string into a
-list, sort the list, and turn it back into a string. This is messy
-and error-prone. And it's frustrating, because Perl already has
-perfectly good lists that would solve the problem if only you could
-use them.
-
-=head1 The Solution
-
-By the time Perl 5 rolled around, we were already stuck with this
-design: Hash values must be scalars. The solution to this is
-references.
-
-A reference is a scalar value that I<refers to> an entire array or an
-entire hash (or to just about anything else). Names are one kind of
-reference that you're already familiar with. Think of the President
-of the United States: a messy, inconvenient bag of blood and bones.
-But to talk about him, or to represent him in a computer program, all
-you need is the easy, convenient scalar string "Barack Obama".
-
-References in Perl are like names for arrays and hashes. They're
-Perl's private, internal names, so you can be sure they're
-unambiguous. Unlike "Barack Obama", a reference only refers to one
-thing, and you always know what it refers to. If you have a reference
-to an array, you can recover the entire array from it. If you have a
-reference to a hash, you can recover the entire hash. But the
-reference is still an easy, compact scalar value.
-
-You can't have a hash whose values are arrays; hash values can only be
-scalars. We're stuck with that. But a single reference can refer to
-an entire array, and references are scalars, so you can have a hash of
-references to arrays, and it'll act a lot like a hash of arrays, and
-it'll be just as useful as a hash of arrays.
-
-We'll come back to this city-country problem later, after we've seen
-some syntax for managing references.
-
-
-=head1 Syntax
-
-There are just two ways to make a reference, and just two ways to use
-it once you have it.
-
-=head2 Making References
-
-=head3 B<Make Rule 1>
-
-If you put a C<\> in front of a variable, you get a
-reference to that variable.
-
- $aref = \@array; # $aref now holds a reference to @array
- $href = \%hash; # $href now holds a reference to %hash
- $sref = \$scalar; # $sref now holds a reference to $scalar
-
-Once the reference is stored in a variable like $aref or $href, you
-can copy it or store it just the same as any other scalar value:
-
- $xy = $aref; # $xy now holds a reference to @array
- $p[3] = $href; # $p[3] now holds a reference to %hash
- $z = $p[3]; # $z now holds a reference to %hash
-
-
-These examples show how to make references to variables with names.
-Sometimes you want to make an array or a hash that doesn't have a
-name. This is analogous to the way you like to be able to use the
-string C<"\n"> or the number 80 without having to store it in a named
-variable first.
-
-B<Make Rule 2>
-
-C<[ ITEMS ]> makes a new, anonymous array, and returns a reference to
-that array. C<{ ITEMS }> makes a new, anonymous hash, and returns a
-reference to that hash.
-
- $aref = [ 1, "foo", undef, 13 ];
- # $aref now holds a reference to an array
-
- $href = { APR => 4, AUG => 8 };
- # $href now holds a reference to a hash
-
-
-The references you get from rule 2 are the same kind of
-references that you get from rule 1:
-
- # This:
- $aref = [ 1, 2, 3 ];
-
- # Does the same as this:
- @array = (1, 2, 3);
- $aref = \@array;
-
-
-The first line is an abbreviation for the following two lines, except
-that it doesn't create the superfluous array variable C<@array>.
-
-If you write just C<[]>, you get a new, empty anonymous array.
-If you write just C<{}>, you get a new, empty anonymous hash.
-
-
-=head2 Using References
-
-What can you do with a reference once you have it? It's a scalar
-value, and we've seen that you can store it as a scalar and get it back
-again just like any scalar. There are just two more ways to use it:
-
-=head3 B<Use Rule 1>
-
-You can always use an array reference, in curly braces, in place of
-the name of an array. For example, C<@{$aref}> instead of C<@array>.
-
-Here are some examples of that:
-
-Arrays:
-
-
- @a @{$aref} An array
- reverse @a reverse @{$aref} Reverse the array
- $a[3] ${$aref}[3] An element of the array
- $a[3] = 17; ${$aref}[3] = 17 Assigning an element
-
-
-On each line are two expressions that do the same thing. The
-left-hand versions operate on the array C<@a>. The right-hand
-versions operate on the array that is referred to by C<$aref>. Once
-they find the array they're operating on, both versions do the same
-things to the arrays.
-
-Using a hash reference is I<exactly> the same:
-
- %h %{$href} A hash
- keys %h keys %{$href} Get the keys from the hash
- $h{'red'} ${$href}{'red'} An element of the hash
- $h{'red'} = 17 ${$href}{'red'} = 17 Assigning an element
-
-Whatever you want to do with a reference, B<Use Rule 1> tells you how
-to do it. You just write the Perl code that you would have written
-for doing the same thing to a regular array or hash, and then replace
-the array or hash name with C<{$reference}>. "How do I loop over an
-array when all I have is a reference?" Well, to loop over an array, you
-would write
-
- for my $element (@array) {
- ...
- }
-
-so replace the array name, C<@array>, with the reference:
-
- for my $element (@{$aref}) {
- ...
- }
-
-"How do I print out the contents of a hash when all I have is a
-reference?" First write the code for printing out a hash:
-
- for my $key (keys %hash) {
- print "$key => $hash{$key}\n";
- }
-
-And then replace the hash name with the reference:
-
- for my $key (keys %{$href}) {
- print "$key => ${$href}{$key}\n";
- }
-
-=head3 B<Use Rule 2>
-
-B<Use Rule 1> is all you really need, because it tells you how to do
-absolutely everything you ever need to do with references. But the
-most common thing to do with an array or a hash is to extract a single
-element, and the B<Use Rule 1> notation is cumbersome. So there is an
-abbreviation.
-
-C<${$aref}[3]> is too hard to read, so you can write C<< $aref->[3] >>
-instead.
-
-C<${$href}{red}> is too hard to read, so you can write
-C<< $href->{red} >> instead.
-
-If C<$aref> holds a reference to an array, then C<< $aref->[3] >> is
-the fourth element of the array. Don't confuse this with C<$aref[3]>,
-which is the fourth element of a totally different array, one
-deceptively named C<@aref>. C<$aref> and C<@aref> are unrelated the
-same way that C<$item> and C<@item> are.
-
-Similarly, C<< $href->{'red'} >> is part of the hash referred to by
-the scalar variable C<$href>, perhaps even one with no name.
-C<$href{'red'}> is part of the deceptively named C<%href> hash. It's
-easy to forget to leave out the C<< -> >>, and if you do, you'll get
-bizarre results when your program gets array and hash elements out of
-totally unexpected hashes and arrays that weren't the ones you wanted
-to use.
-
-
-=head2 An Example
-
-Let's see a quick example of how all this is useful.
-
-First, remember that C<[1, 2, 3]> makes an anonymous array containing
-C<(1, 2, 3)>, and gives you a reference to that array.
-
-Now think about
-
- @a = ( [1, 2, 3],
- [4, 5, 6],
- [7, 8, 9]
- );
-
-@a is an array with three elements, and each one is a reference to
-another array.
-
-C<$a[1]> is one of these references. It refers to an array, the array
-containing C<(4, 5, 6)>, and because it is a reference to an array,
-B<Use Rule 2> says that we can write C<< $a[1]->[2] >> to get the
-third element from that array. C<< $a[1]->[2] >> is the 6.
-Similarly, C<< $a[0]->[1] >> is the 2. What we have here is like a
-two-dimensional array; you can write C<< $a[ROW]->[COLUMN] >> to get
-or set the element in any row and any column of the array.
-
-The notation still looks a little cumbersome, so there's one more
-abbreviation:
-
-=head2 Arrow Rule
-
-In between two B<subscripts>, the arrow is optional.
-
-Instead of C<< $a[1]->[2] >>, we can write C<$a[1][2]>; it means the
-same thing. Instead of C<< $a[0]->[1] = 23 >>, we can write
-C<$a[0][1] = 23>; it means the same thing.
-
-Now it really looks like two-dimensional arrays!
-
-You can see why the arrows are important. Without them, we would have
-had to write C<${$a[1]}[2]> instead of C<$a[1][2]>. For
-three-dimensional arrays, they let us write C<$x[2][3][5]> instead of
-the unreadable C<${${$x[2]}[3]}[5]>.
-
-=head1 Solution
-
-Here's the answer to the problem I posed earlier, of reformatting a
-file of city and country names.
-
- 1 my %table;
-
- 2 while (<>) {
- 3 chomp;
- 4 my ($city, $country) = split /, /;
- 5 $table{$country} = [] unless exists $table{$country};
- 6 push @{$table{$country}}, $city;
- 7 }
-
- 8 foreach $country (sort keys %table) {
- 9 print "$country: ";
- 10 my @cities = @{$table{$country}};
- 11 print join ', ', sort @cities;
- 12 print ".\n";
- 13 }
-
-
-The program has two pieces: Lines 2--7 read the input and build a data
-structure, and lines 8-13 analyze the data and print out the report.
-We're going to have a hash, C<%table>, whose keys are country names,
-and whose values are references to arrays of city names. The data
-structure will look like this:
-
-
- %table
- +-------+---+
- | | | +-----------+--------+
- |Germany| *---->| Frankfurt | Berlin |
- | | | +-----------+--------+
- +-------+---+
- | | | +----------+
- |Finland| *---->| Helsinki |
- | | | +----------+
- +-------+---+
- | | | +---------+------------+----------+
- | USA | *---->| Chicago | Washington | New York |
- | | | +---------+------------+----------+
- +-------+---+
-
-We'll look at output first. Supposing we already have this structure,
-how do we print it out?
-
- 8 foreach $country (sort keys %table) {
- 9 print "$country: ";
- 10 my @cities = @{$table{$country}};
- 11 print join ', ', sort @cities;
- 12 print ".\n";
- 13 }
-
-C<%table> is an
-ordinary hash, and we get a list of keys from it, sort the keys, and
-loop over the keys as usual. The only use of references is in line 10.
-C<$table{$country}> looks up the key C<$country> in the hash
-and gets the value, which is a reference to an array of cities in that country.
-B<Use Rule 1> says that
-we can recover the array by saying
-C<@{$table{$country}}>. Line 10 is just like
-
- @cities = @array;
-
-except that the name C<array> has been replaced by the reference
-C<{$table{$country}}>. The C<@> tells Perl to get the entire array.
-Having gotten the list of cities, we sort it, join it, and print it
-out as usual.
-
-Lines 2-7 are responsible for building the structure in the first
-place. Here they are again:
-
- 2 while (<>) {
- 3 chomp;
- 4 my ($city, $country) = split /, /;
- 5 $table{$country} = [] unless exists $table{$country};
- 6 push @{$table{$country}}, $city;
- 7 }
-
-Lines 2-4 acquire a city and country name. Line 5 looks to see if the
-country is already present as a key in the hash. If it's not, the
-program uses the C<[]> notation (B<Make Rule 2>) to manufacture a new,
-empty anonymous array of cities, and installs a reference to it into
-the hash under the appropriate key.
-
-Line 6 installs the city name into the appropriate array.
-C<$table{$country}> now holds a reference to the array of cities seen
-in that country so far. Line 6 is exactly like
-
- push @array, $city;
-
-except that the name C<array> has been replaced by the reference
-C<{$table{$country}}>. The C<push> adds a city name to the end of the
-referred-to array.
-
-There's one fine point I skipped. Line 5 is unnecessary, and we can
-get rid of it.
-
- 2 while (<>) {
- 3 chomp;
- 4 my ($city, $country) = split /, /;
- 5 #### $table{$country} = [] unless exists $table{$country};
- 6 push @{$table{$country}}, $city;
- 7 }
-
-If there's already an entry in C<%table> for the current C<$country>,
-then nothing is different. Line 6 will locate the value in
-C<$table{$country}>, which is a reference to an array, and push
-C<$city> into the array. But
-what does it do when
-C<$country> holds a key, say C<Greece>, that is not yet in C<%table>?
-
-This is Perl, so it does the exact right thing. It sees that you want
-to push C<Athens> onto an array that doesn't exist, so it helpfully
-makes a new, empty, anonymous array for you, installs it into
-C<%table>, and then pushes C<Athens> onto it. This is called
-'autovivification'--bringing things to life automatically. Perl saw
-that they key wasn't in the hash, so it created a new hash entry
-automatically. Perl saw that you wanted to use the hash value as an
-array, so it created a new empty array and installed a reference to it
-in the hash automatically. And as usual, Perl made the array one
-element longer to hold the new city name.
-
-=head1 The Rest
-
-I promised to give you 90% of the benefit with 10% of the details, and
-that means I left out 90% of the details. Now that you have an
-overview of the important parts, it should be easier to read the
-L<perlref> manual page, which discusses 100% of the details.
-
-Some of the highlights of L<perlref>:
-
-=over 4
-
-=item *
-
-You can make references to anything, including scalars, functions, and
-other references.
-
-=item *
-
-In B<Use Rule 1>, you can omit the curly brackets whenever the thing
-inside them is an atomic scalar variable like C<$aref>. For example,
-C<@$aref> is the same as C<@{$aref}>, and C<$$aref[1]> is the same as
-C<${$aref}[1]>. If you're just starting out, you may want to adopt
-the habit of always including the curly brackets.
-
-=item *
-
-This doesn't copy the underlying array:
-
- $aref2 = $aref1;
-
-You get two references to the same array. If you modify
-C<< $aref1->[23] >> and then look at
-C<< $aref2->[23] >> you'll see the change.
-
-To copy the array, use
-
- $aref2 = [@{$aref1}];
-
-This uses C<[...]> notation to create a new anonymous array, and
-C<$aref2> is assigned a reference to the new array. The new array is
-initialized with the contents of the array referred to by C<$aref1>.
-
-Similarly, to copy an anonymous hash, you can use
-
- $href2 = {%{$href1}};
-
-=item *
-
-To see if a variable contains a reference, use the C<ref> function. It
-returns true if its argument is a reference. Actually it's a little
-better than that: It returns C<HASH> for hash references and C<ARRAY>
-for array references.
-
-=item *
-
-If you try to use a reference like a string, you get strings like
-
- ARRAY(0x80f5dec) or HASH(0x826afc0)
-
-If you ever see a string that looks like this, you'll know you
-printed out a reference by mistake.
-
-A side effect of this representation is that you can use C<eq> to see
-if two references refer to the same thing. (But you should usually use
-C<==> instead because it's much faster.)
-
-=item *
-
-You can use a string as if it were a reference. If you use the string
-C<"foo"> as an array reference, it's taken to be a reference to the
-array C<@foo>. This is called a I<soft reference> or I<symbolic
-reference>. The declaration C<use strict 'refs'> disables this
-feature, which can cause all sorts of trouble if you use it by accident.
-
-=back
-
-You might prefer to go on to L<perllol> instead of L<perlref>; it
-discusses lists of lists and multidimensional arrays in detail. After
-that, you should move on to L<perldsc>; it's a Data Structure Cookbook
-that shows recipes for using and printing out arrays of hashes, hashes
-of arrays, and other kinds of data.
-
-=head1 Summary
-
-Everyone needs compound data structures, and in Perl the way you get
-them is with references. There are four important rules for managing
-references: Two for making references and two for using them. Once
-you know these rules you can do most of the important things you need
-to do with references.
-
-=head1 Credits
-
-Author: Mark Jason Dominus, Plover Systems (C<mjd-perl-ref+@plover.com>)
-
-This article originally appeared in I<The Perl Journal>
-( http://www.tpj.com/ ) volume 3, #2. Reprinted with permission.
-
-The original title was I<Understand References Today>.
-
-=head2 Distribution Conditions
-
-Copyright 1998 The Perl Journal.
-
-This documentation is free; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-Irrespective of its distribution, all code examples in these files are
-hereby placed into the public domain. You are permitted and
-encouraged to use this code in your own programs for fun or for profit
-as you see fit. A simple comment in the code giving credit would be
-courteous but is not required.
-
-
-
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlreguts.pod b/Master/tlpkg/tlperl/lib/pods/perlreguts.pod
deleted file mode 100644
index ec1c243f8a9..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlreguts.pod
+++ /dev/null
@@ -1,886 +0,0 @@
-=head1 NAME
-
-perlreguts - Description of the Perl regular expression engine.
-
-=head1 DESCRIPTION
-
-This document is an attempt to shine some light on the guts of the regex
-engine and how it works. The regex engine represents a significant chunk
-of the perl codebase, but is relatively poorly understood. This document
-is a meagre attempt at addressing this situation. It is derived from the
-author's experience, comments in the source code, other papers on the
-regex engine, feedback on the perl5-porters mail list, and no doubt other
-places as well.
-
-B<NOTICE!> It should be clearly understood that the behavior and
-structures discussed in this represents the state of the engine as the
-author understood it at the time of writing. It is B<NOT> an API
-definition, it is purely an internals guide for those who want to hack
-the regex engine, or understand how the regex engine works. Readers of
-this document are expected to understand perl's regex syntax and its
-usage in detail. If you want to learn about the basics of Perl's
-regular expressions, see L<perlre>. And if you want to replace the
-regex engine with your own, see L<perlreapi>.
-
-=head1 OVERVIEW
-
-=head2 A quick note on terms
-
-There is some debate as to whether to say "regexp" or "regex". In this
-document we will use the term "regex" unless there is a special reason
-not to, in which case we will explain why.
-
-When speaking about regexes we need to distinguish between their source
-code form and their internal form. In this document we will use the term
-"pattern" when we speak of their textual, source code form, and the term
-"program" when we speak of their internal representation. These
-correspond to the terms I<S-regex> and I<B-regex> that Mark Jason
-Dominus employs in his paper on "Rx" ([1] in L</REFERENCES>).
-
-=head2 What is a regular expression engine?
-
-A regular expression engine is a program that takes a set of constraints
-specified in a mini-language, and then applies those constraints to a
-target string, and determines whether or not the string satisfies the
-constraints. See L<perlre> for a full definition of the language.
-
-In less grandiose terms, the first part of the job is to turn a pattern into
-something the computer can efficiently use to find the matching point in
-the string, and the second part is performing the search itself.
-
-To do this we need to produce a program by parsing the text. We then
-need to execute the program to find the point in the string that
-matches. And we need to do the whole thing efficiently.
-
-=head2 Structure of a Regexp Program
-
-=head3 High Level
-
-Although it is a bit confusing and some people object to the terminology, it
-is worth taking a look at a comment that has
-been in F<regexp.h> for years:
-
-I<This is essentially a linear encoding of a nondeterministic
-finite-state machine (aka syntax charts or "railroad normal form" in
-parsing technology).>
-
-The term "railroad normal form" is a bit esoteric, with "syntax
-diagram/charts", or "railroad diagram/charts" being more common terms.
-Nevertheless it provides a useful mental image of a regex program: each
-node can be thought of as a unit of track, with a single entry and in
-most cases a single exit point (there are pieces of track that fork, but
-statistically not many), and the whole forms a layout with a
-single entry and single exit point. The matching process can be thought
-of as a car that moves along the track, with the particular route through
-the system being determined by the character read at each possible
-connector point. A car can fall off the track at any point but it may
-only proceed as long as it matches the track.
-
-Thus the pattern C</foo(?:\w+|\d+|\s+)bar/> can be thought of as the
-following chart:
-
- [start]
- |
- <foo>
- |
- +-----+-----+
- | | |
- <\w+> <\d+> <\s+>
- | | |
- +-----+-----+
- |
- <bar>
- |
- [end]
-
-The truth of the matter is that perl's regular expressions these days are
-much more complex than this kind of structure, but visualising it this way
-can help when trying to get your bearings, and it matches the
-current implementation pretty closely.
-
-To be more precise, we will say that a regex program is an encoding
-of a graph. Each node in the graph corresponds to part of
-the original regex pattern, such as a literal string or a branch,
-and has a pointer to the nodes representing the next component
-to be matched. Since "node" and "opcode" already have other meanings in the
-perl source, we will call the nodes in a regex program "regops".
-
-The program is represented by an array of C<regnode> structures, one or
-more of which represent a single regop of the program. Struct
-C<regnode> is the smallest struct needed, and has a field structure which is
-shared with all the other larger structures.
-
-The "next" pointers of all regops except C<BRANCH> implement concatenation;
-a "next" pointer with a C<BRANCH> on both ends of it is connecting two
-alternatives. [Here we have one of the subtle syntax dependencies: an
-individual C<BRANCH> (as opposed to a collection of them) is never
-concatenated with anything because of operator precedence.]
-
-The operand of some types of regop is a literal string; for others,
-it is a regop leading into a sub-program. In particular, the operand
-of a C<BRANCH> node is the first regop of the branch.
-
-B<NOTE>: As the railroad metaphor suggests, this is B<not> a tree
-structure: the tail of the branch connects to the thing following the
-set of C<BRANCH>es. It is a like a single line of railway track that
-splits as it goes into a station or railway yard and rejoins as it comes
-out the other side.
-
-=head3 Regops
-
-The base structure of a regop is defined in F<regexp.h> as follows:
-
- struct regnode {
- U8 flags; /* Various purposes, sometimes overridden */
- U8 type; /* Opcode value as specified by regnodes.h */
- U16 next_off; /* Offset in size regnode */
- };
-
-Other larger C<regnode>-like structures are defined in F<regcomp.h>. They
-are almost like subclasses in that they have the same fields as
-C<regnode>, with possibly additional fields following in
-the structure, and in some cases the specific meaning (and name)
-of some of base fields are overridden. The following is a more
-complete description.
-
-=over 4
-
-=item C<regnode_1>
-
-=item C<regnode_2>
-
-C<regnode_1> structures have the same header, followed by a single
-four-byte argument; C<regnode_2> structures contain two two-byte
-arguments instead:
-
- regnode_1 U32 arg1;
- regnode_2 U16 arg1; U16 arg2;
-
-=item C<regnode_string>
-
-C<regnode_string> structures, used for literal strings, follow the header
-with a one-byte length and then the string data. Strings are padded on
-the end with zero bytes so that the total length of the node is a
-multiple of four bytes:
-
- regnode_string char string[1];
- U8 str_len; /* overrides flags */
-
-=item C<regnode_charclass>
-
-Character classes are represented by C<regnode_charclass> structures,
-which have a four-byte argument and then a 32-byte (256-bit) bitmap
-indicating which characters are included in the class.
-
- regnode_charclass U32 arg1;
- char bitmap[ANYOF_BITMAP_SIZE];
-
-=item C<regnode_charclass_class>
-
-There is also a larger form of a char class structure used to represent
-POSIX char classes called C<regnode_charclass_class> which has an
-additional 4-byte (32-bit) bitmap indicating which POSIX char classes
-have been included.
-
- regnode_charclass_class U32 arg1;
- char bitmap[ANYOF_BITMAP_SIZE];
- char classflags[ANYOF_CLASSBITMAP_SIZE];
-
-=back
-
-F<regnodes.h> defines an array called C<regarglen[]> which gives the size
-of each opcode in units of C<size regnode> (4-byte). A macro is used
-to calculate the size of an C<EXACT> node based on its C<str_len> field.
-
-The regops are defined in F<regnodes.h> which is generated from
-F<regcomp.sym> by F<regcomp.pl>. Currently the maximum possible number
-of distinct regops is restricted to 256, with about a quarter already
-used.
-
-A set of macros makes accessing the fields
-easier and more consistent. These include C<OP()>, which is used to determine
-the type of a C<regnode>-like structure; C<NEXT_OFF()>, which is the offset to
-the next node (more on this later); C<ARG()>, C<ARG1()>, C<ARG2()>, C<ARG_SET()>,
-and equivalents for reading and setting the arguments; and C<STR_LEN()>,
-C<STRING()> and C<OPERAND()> for manipulating strings and regop bearing
-types.
-
-=head3 What regop is next?
-
-There are three distinct concepts of "next" in the regex engine, and
-it is important to keep them clear.
-
-=over 4
-
-=item *
-
-There is the "next regnode" from a given regnode, a value which is
-rarely useful except that sometimes it matches up in terms of value
-with one of the others, and that sometimes the code assumes this to
-always be so.
-
-=item *
-
-There is the "next regop" from a given regop/regnode. This is the
-regop physically located after the current one, as determined by
-the size of the current regop. This is often useful, such as when
-dumping the structure we use this order to traverse. Sometimes the code
-assumes that the "next regnode" is the same as the "next regop", or in
-other words assumes that the sizeof a given regop type is always going
-to be one regnode large.
-
-=item *
-
-There is the "regnext" from a given regop. This is the regop which
-is reached by jumping forward by the value of C<NEXT_OFF()>,
-or in a few cases for longer jumps by the C<arg1> field of the C<regnode_1>
-structure. The subroutine C<regnext()> handles this transparently.
-This is the logical successor of the node, which in some cases, like
-that of the C<BRANCH> regop, has special meaning.
-
-=back
-
-=head1 Process Overview
-
-Broadly speaking, performing a match of a string against a pattern
-involves the following steps:
-
-=over 5
-
-=item A. Compilation
-
-=over 5
-
-=item 1. Parsing for size
-
-=item 2. Parsing for construction
-
-=item 3. Peep-hole optimisation and analysis
-
-=back
-
-=item B. Execution
-
-=over 5
-
-=item 4. Start position and no-match optimisations
-
-=item 5. Program execution
-
-=back
-
-=back
-
-
-Where these steps occur in the actual execution of a perl program is
-determined by whether the pattern involves interpolating any string
-variables. If interpolation occurs, then compilation happens at run time. If it
-does not, then compilation is performed at compile time. (The C</o> modifier changes this,
-as does C<qr//> to a certain extent.) The engine doesn't really care that
-much.
-
-=head2 Compilation
-
-This code resides primarily in F<regcomp.c>, along with the header files
-F<regcomp.h>, F<regexp.h> and F<regnodes.h>.
-
-Compilation starts with C<pregcomp()>, which is mostly an initialisation
-wrapper which farms work out to two other routines for the heavy lifting: the
-first is C<reg()>, which is the start point for parsing; the second,
-C<study_chunk()>, is responsible for optimisation.
-
-Initialisation in C<pregcomp()> mostly involves the creation and data-filling
-of a special structure, C<RExC_state_t> (defined in F<regcomp.c>).
-Almost all internally-used routines in F<regcomp.h> take a pointer to one
-of these structures as their first argument, with the name C<pRExC_state>.
-This structure is used to store the compilation state and contains many
-fields. Likewise there are many macros which operate on this
-variable: anything that looks like C<RExC_xxxx> is a macro that operates on
-this pointer/structure.
-
-=head3 Parsing for size
-
-In this pass the input pattern is parsed in order to calculate how much
-space is needed for each regop we would need to emit. The size is also
-used to determine whether long jumps will be required in the program.
-
-This stage is controlled by the macro C<SIZE_ONLY> being set.
-
-The parse proceeds pretty much exactly as it does during the
-construction phase, except that most routines are short-circuited to
-change the size field C<RExC_size> and not do anything else.
-
-=head3 Parsing for construction
-
-Once the size of the program has been determined, the pattern is parsed
-again, but this time for real. Now C<SIZE_ONLY> will be false, and the
-actual construction can occur.
-
-C<reg()> is the start of the parse process. It is responsible for
-parsing an arbitrary chunk of pattern up to either the end of the
-string, or the first closing parenthesis it encounters in the pattern.
-This means it can be used to parse the top-level regex, or any section
-inside of a grouping parenthesis. It also handles the "special parens"
-that perl's regexes have. For instance when parsing C</x(?:foo)y/> C<reg()>
-will at one point be called to parse from the "?" symbol up to and
-including the ")".
-
-Additionally, C<reg()> is responsible for parsing the one or more
-branches from the pattern, and for "finishing them off" by correctly
-setting their next pointers. In order to do the parsing, it repeatedly
-calls out to C<regbranch()>, which is responsible for handling up to the
-first C<|> symbol it sees.
-
-C<regbranch()> in turn calls C<regpiece()> which
-handles "things" followed by a quantifier. In order to parse the
-"things", C<regatom()> is called. This is the lowest level routine, which
-parses out constant strings, character classes, and the
-various special symbols like C<$>. If C<regatom()> encounters a "("
-character it in turn calls C<reg()>.
-
-The routine C<regtail()> is called by both C<reg()> and C<regbranch()>
-in order to "set the tail pointer" correctly. When executing and
-we get to the end of a branch, we need to go to the node following the
-grouping parens. When parsing, however, we don't know where the end will
-be until we get there, so when we do we must go back and update the
-offsets as appropriate. C<regtail> is used to make this easier.
-
-A subtlety of the parsing process means that a regex like C</foo/> is
-originally parsed into an alternation with a single branch. It is only
-afterwards that the optimiser converts single branch alternations into the
-simpler form.
-
-=head3 Parse Call Graph and a Grammar
-
-The call graph looks like this:
-
- reg() # parse a top level regex, or inside of parens
- regbranch() # parse a single branch of an alternation
- regpiece() # parse a pattern followed by a quantifier
- regatom() # parse a simple pattern
- regclass() # used to handle a class
- reg() # used to handle a parenthesised subpattern
- ....
- ...
- regtail() # finish off the branch
- ...
- regtail() # finish off the branch sequence. Tie each
- # branch's tail to the tail of the sequence
- # (NEW) In Debug mode this is
- # regtail_study().
-
-A grammar form might be something like this:
-
- atom : constant | class
- quant : '*' | '+' | '?' | '{min,max}'
- _branch: piece
- | piece _branch
- | nothing
- branch: _branch
- | _branch '|' branch
- group : '(' branch ')'
- _piece: atom | group
- piece : _piece
- | _piece quant
-
-=head3 Debug Output
-
-In the 5.9.x development version of perl you can C<< use re Debug => 'PARSE' >>
-to see some trace information about the parse process. We will start with some
-simple patterns and build up to more complex patterns.
-
-So when we parse C</foo/> we see something like the following table. The
-left shows what is being parsed, and the number indicates where the next regop
-would go. The stuff on the right is the trace output of the graph. The
-names are chosen to be short to make it less dense on the screen. 'tsdy'
-is a special form of C<regtail()> which does some extra analysis.
-
- >foo< 1 reg
- brnc
- piec
- atom
- >< 4 tsdy~ EXACT <foo> (EXACT) (1)
- ~ attach to END (3) offset to 2
-
-The resulting program then looks like:
-
- 1: EXACT <foo>(3)
- 3: END(0)
-
-As you can see, even though we parsed out a branch and a piece, it was ultimately
-only an atom. The final program shows us how things work. We have an C<EXACT> regop,
-followed by an C<END> regop. The number in parens indicates where the C<regnext> of
-the node goes. The C<regnext> of an C<END> regop is unused, as C<END> regops mean
-we have successfully matched. The number on the left indicates the position of
-the regop in the regnode array.
-
-Now let's try a harder pattern. We will add a quantifier, so now we have the pattern
-C</foo+/>. We will see that C<regbranch()> calls C<regpiece()> twice.
-
- >foo+< 1 reg
- brnc
- piec
- atom
- >o+< 3 piec
- atom
- >< 6 tail~ EXACT <fo> (1)
- 7 tsdy~ EXACT <fo> (EXACT) (1)
- ~ PLUS (END) (3)
- ~ attach to END (6) offset to 3
-
-And we end up with the program:
-
- 1: EXACT <fo>(3)
- 3: PLUS(6)
- 4: EXACT <o>(0)
- 6: END(0)
-
-Now we have a special case. The C<EXACT> regop has a C<regnext> of 0. This is
-because if it matches it should try to match itself again. The C<PLUS> regop
-handles the actual failure of the C<EXACT> regop and acts appropriately (going
-to regnode 6 if the C<EXACT> matched at least once, or failing if it didn't).
-
-Now for something much more complex: C</x(?:foo*|b[a][rR])(foo|bar)$/>
-
- >x(?:foo*|b... 1 reg
- brnc
- piec
- atom
- >(?:foo*|b[... 3 piec
- atom
- >?:foo*|b[a... reg
- >foo*|b[a][... brnc
- piec
- atom
- >o*|b[a][rR... 5 piec
- atom
- >|b[a][rR])... 8 tail~ EXACT <fo> (3)
- >b[a][rR])(... 9 brnc
- 10 piec
- atom
- >[a][rR])(f... 12 piec
- atom
- >a][rR])(fo... clas
- >[rR])(foo|... 14 tail~ EXACT <b> (10)
- piec
- atom
- >rR])(foo|b... clas
- >)(foo|bar)... 25 tail~ EXACT <a> (12)
- tail~ BRANCH (3)
- 26 tsdy~ BRANCH (END) (9)
- ~ attach to TAIL (25) offset to 16
- tsdy~ EXACT <fo> (EXACT) (4)
- ~ STAR (END) (6)
- ~ attach to TAIL (25) offset to 19
- tsdy~ EXACT <b> (EXACT) (10)
- ~ EXACT <a> (EXACT) (12)
- ~ ANYOF[Rr] (END) (14)
- ~ attach to TAIL (25) offset to 11
- >(foo|bar)$< tail~ EXACT <x> (1)
- piec
- atom
- >foo|bar)$< reg
- 28 brnc
- piec
- atom
- >|bar)$< 31 tail~ OPEN1 (26)
- >bar)$< brnc
- 32 piec
- atom
- >)$< 34 tail~ BRANCH (28)
- 36 tsdy~ BRANCH (END) (31)
- ~ attach to CLOSE1 (34) offset to 3
- tsdy~ EXACT <foo> (EXACT) (29)
- ~ attach to CLOSE1 (34) offset to 5
- tsdy~ EXACT <bar> (EXACT) (32)
- ~ attach to CLOSE1 (34) offset to 2
- >$< tail~ BRANCH (3)
- ~ BRANCH (9)
- ~ TAIL (25)
- piec
- atom
- >< 37 tail~ OPEN1 (26)
- ~ BRANCH (28)
- ~ BRANCH (31)
- ~ CLOSE1 (34)
- 38 tsdy~ EXACT <x> (EXACT) (1)
- ~ BRANCH (END) (3)
- ~ BRANCH (END) (9)
- ~ TAIL (END) (25)
- ~ OPEN1 (END) (26)
- ~ BRANCH (END) (28)
- ~ BRANCH (END) (31)
- ~ CLOSE1 (END) (34)
- ~ EOL (END) (36)
- ~ attach to END (37) offset to 1
-
-Resulting in the program
-
- 1: EXACT <x>(3)
- 3: BRANCH(9)
- 4: EXACT <fo>(6)
- 6: STAR(26)
- 7: EXACT <o>(0)
- 9: BRANCH(25)
- 10: EXACT <ba>(14)
- 12: OPTIMIZED (2 nodes)
- 14: ANYOF[Rr](26)
- 25: TAIL(26)
- 26: OPEN1(28)
- 28: TRIE-EXACT(34)
- [StS:1 Wds:2 Cs:6 Uq:5 #Sts:7 Mn:3 Mx:3 Stcls:bf]
- <foo>
- <bar>
- 30: OPTIMIZED (4 nodes)
- 34: CLOSE1(36)
- 36: EOL(37)
- 37: END(0)
-
-Here we can see a much more complex program, with various optimisations in
-play. At regnode 10 we see an example where a character class with only
-one character in it was turned into an C<EXACT> node. We can also see where
-an entire alternation was turned into a C<TRIE-EXACT> node. As a consequence,
-some of the regnodes have been marked as optimised away. We can see that
-the C<$> symbol has been converted into an C<EOL> regop, a special piece of
-code that looks for C<\n> or the end of the string.
-
-The next pointer for C<BRANCH>es is interesting in that it points at where
-execution should go if the branch fails. When executing, if the engine
-tries to traverse from a branch to a C<regnext> that isn't a branch then
-the engine will know that the entire set of branches has failed.
-
-=head3 Peep-hole Optimisation and Analysis
-
-The regular expression engine can be a weighty tool to wield. On long
-strings and complex patterns it can end up having to do a lot of work
-to find a match, and even more to decide that no match is possible.
-Consider a situation like the following pattern.
-
- 'ababababababababababab' =~ /(a|b)*z/
-
-The C<(a|b)*> part can match at every char in the string, and then fail
-every time because there is no C<z> in the string. So obviously we can
-avoid using the regex engine unless there is a C<z> in the string.
-Likewise in a pattern like:
-
- /foo(\w+)bar/
-
-In this case we know that the string must contain a C<foo> which must be
-followed by C<bar>. We can use Fast Boyer-Moore matching as implemented
-in C<fbm_instr()> to find the location of these strings. If they don't exist
-then we don't need to resort to the much more expensive regex engine.
-Even better, if they do exist then we can use their positions to
-reduce the search space that the regex engine needs to cover to determine
-if the entire pattern matches.
-
-There are various aspects of the pattern that can be used to facilitate
-optimisations along these lines:
-
-=over 5
-
-=item * anchored fixed strings
-
-=item * floating fixed strings
-
-=item * minimum and maximum length requirements
-
-=item * start class
-
-=item * Beginning/End of line positions
-
-=back
-
-Another form of optimisation that can occur is the post-parse "peep-hole"
-optimisation, where inefficient constructs are replaced by more efficient
-constructs. The C<TAIL> regops which are used during parsing to mark the end
-of branches and the end of groups are examples of this. These regops are used
-as place-holders during construction and "always match" so they can be
-"optimised away" by making the things that point to the C<TAIL> point to the
-thing that C<TAIL> points to, thus "skipping" the node.
-
-Another optimisation that can occur is that of "C<EXACT> merging" which is
-where two consecutive C<EXACT> nodes are merged into a single
-regop. An even more aggressive form of this is that a branch
-sequence of the form C<EXACT BRANCH ... EXACT> can be converted into a
-C<TRIE-EXACT> regop.
-
-All of this occurs in the routine C<study_chunk()> which uses a special
-structure C<scan_data_t> to store the analysis that it has performed, and
-does the "peep-hole" optimisations as it goes.
-
-The code involved in C<study_chunk()> is extremely cryptic. Be careful. :-)
-
-=head2 Execution
-
-Execution of a regex generally involves two phases, the first being
-finding the start point in the string where we should match from,
-and the second being running the regop interpreter.
-
-If we can tell that there is no valid start point then we don't bother running
-interpreter at all. Likewise, if we know from the analysis phase that we
-cannot detect a short-cut to the start position, we go straight to the
-interpreter.
-
-The two entry points are C<re_intuit_start()> and C<pregexec()>. These routines
-have a somewhat incestuous relationship with overlap between their functions,
-and C<pregexec()> may even call C<re_intuit_start()> on its own. Nevertheless
-other parts of the perl source code may call into either, or both.
-
-Execution of the interpreter itself used to be recursive, but thanks to the
-efforts of Dave Mitchell in the 5.9.x development track, that has changed: now an
-internal stack is maintained on the heap and the routine is fully
-iterative. This can make it tricky as the code is quite conservative
-about what state it stores, with the result that two consecutive lines in the
-code can actually be running in totally different contexts due to the
-simulated recursion.
-
-=head3 Start position and no-match optimisations
-
-C<re_intuit_start()> is responsible for handling start points and no-match
-optimisations as determined by the results of the analysis done by
-C<study_chunk()> (and described in L<Peep-hole Optimisation and Analysis>).
-
-The basic structure of this routine is to try to find the start- and/or
-end-points of where the pattern could match, and to ensure that the string
-is long enough to match the pattern. It tries to use more efficient
-methods over less efficient methods and may involve considerable
-cross-checking of constraints to find the place in the string that matches.
-For instance it may try to determine that a given fixed string must be
-not only present but a certain number of chars before the end of the
-string, or whatever.
-
-It calls several other routines, such as C<fbm_instr()> which does
-Fast Boyer Moore matching and C<find_byclass()> which is responsible for
-finding the start using the first mandatory regop in the program.
-
-When the optimisation criteria have been satisfied, C<reg_try()> is called
-to perform the match.
-
-=head3 Program execution
-
-C<pregexec()> is the main entry point for running a regex. It contains
-support for initialising the regex interpreter's state, running
-C<re_intuit_start()> if needed, and running the interpreter on the string
-from various start positions as needed. When it is necessary to use
-the regex interpreter C<pregexec()> calls C<regtry()>.
-
-C<regtry()> is the entry point into the regex interpreter. It expects
-as arguments a pointer to a C<regmatch_info> structure and a pointer to
-a string. It returns an integer 1 for success and a 0 for failure.
-It is basically a set-up wrapper around C<regmatch()>.
-
-C<regmatch> is the main "recursive loop" of the interpreter. It is
-basically a giant switch statement that implements a state machine, where
-the possible states are the regops themselves, plus a number of additional
-intermediate and failure states. A few of the states are implemented as
-subroutines but the bulk are inline code.
-
-=head1 MISCELLANEOUS
-
-=head2 Unicode and Localisation Support
-
-When dealing with strings containing characters that cannot be represented
-using an eight-bit character set, perl uses an internal representation
-that is a permissive version of Unicode's UTF-8 encoding[2]. This uses single
-bytes to represent characters from the ASCII character set, and sequences
-of two or more bytes for all other characters. (See L<perlunitut>
-for more information about the relationship between UTF-8 and perl's
-encoding, utf8. The difference isn't important for this discussion.)
-
-No matter how you look at it, Unicode support is going to be a pain in a
-regex engine. Tricks that might be fine when you have 256 possible
-characters often won't scale to handle the size of the UTF-8 character
-set. Things you can take for granted with ASCII may not be true with
-Unicode. For instance, in ASCII, it is safe to assume that
-C<sizeof(char1) == sizeof(char2)>, but in UTF-8 it isn't. Unicode case folding is
-vastly more complex than the simple rules of ASCII, and even when not
-using Unicode but only localised single byte encodings, things can get
-tricky (for example, B<LATIN SMALL LETTER SHARP S> (U+00DF, E<szlig>)
-should match 'SS' in localised case-insensitive matching).
-
-Making things worse is that UTF-8 support was a later addition to the
-regex engine (as it was to perl) and this necessarily made things a lot
-more complicated. Obviously it is easier to design a regex engine with
-Unicode support in mind from the beginning than it is to retrofit it to
-one that wasn't.
-
-Nearly all regops that involve looking at the input string have
-two cases, one for UTF-8, and one not. In fact, it's often more complex
-than that, as the pattern may be UTF-8 as well.
-
-Care must be taken when making changes to make sure that you handle
-UTF-8 properly, both at compile time and at execution time, including
-when the string and pattern are mismatched.
-
-The following comment in F<regcomp.h> gives an example of exactly how
-tricky this can be:
-
- Two problematic code points in Unicode casefolding of EXACT nodes:
-
- U+0390 - GREEK SMALL LETTER IOTA WITH DIALYTIKA AND TONOS
- U+03B0 - GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND TONOS
-
- which casefold to
-
- Unicode UTF-8
-
- U+03B9 U+0308 U+0301 0xCE 0xB9 0xCC 0x88 0xCC 0x81
- U+03C5 U+0308 U+0301 0xCF 0x85 0xCC 0x88 0xCC 0x81
-
- This means that in case-insensitive matching (or "loose matching",
- as Unicode calls it), an EXACTF of length six (the UTF-8 encoded
- byte length of the above casefolded versions) can match a target
- string of length two (the byte length of UTF-8 encoded U+0390 or
- U+03B0). This would rather mess up the minimum length computation.
-
- What we'll do is to look for the tail four bytes, and then peek
- at the preceding two bytes to see whether we need to decrease
- the minimum length by four (six minus two).
-
- Thanks to the design of UTF-8, there cannot be false matches:
- A sequence of valid UTF-8 bytes cannot be a subsequence of
- another valid sequence of UTF-8 bytes.
-
-
-=head2 Base Structures
-
-The C<regexp> structure described in L<perlreapi> is common to all
-regex engines. Two of its fields that are intended for the private use
-of the regex engine that compiled the pattern. These are the
-C<intflags> and pprivate members. The C<pprivate> is a void pointer to
-an arbitrary structure whose use and management is the responsibility
-of the compiling engine. perl will never modify either of these
-values. In the case of the stock engine the structure pointed to by
-C<pprivate> is called C<regexp_internal>.
-
-Its C<pprivate> and C<intflags> fields contain data
-specific to each engine.
-
-There are two structures used to store a compiled regular expression.
-One, the C<regexp> structure described in L<perlreapi> is populated by
-the engine currently being. used and some of its fields read by perl to
-implement things such as the stringification of C<qr//>.
-
-
-The other structure is pointed to be the C<regexp> struct's
-C<pprivate> and is in addition to C<intflags> in the same struct
-considered to be the property of the regex engine which compiled the
-regular expression;
-
-The regexp structure contains all the data that perl needs to be aware of
-to properly work with the regular expression. It includes data about
-optimisations that perl can use to determine if the regex engine should
-really be used, and various other control info that is needed to properly
-execute patterns in various contexts such as is the pattern anchored in
-some way, or what flags were used during the compile, or whether the
-program contains special constructs that perl needs to be aware of.
-
-In addition it contains two fields that are intended for the private use
-of the regex engine that compiled the pattern. These are the C<intflags>
-and pprivate members. The C<pprivate> is a void pointer to an arbitrary
-structure whose use and management is the responsibility of the compiling
-engine. perl will never modify either of these values.
-
-As mentioned earlier, in the case of the default engines, the C<pprivate>
-will be a pointer to a regexp_internal structure which holds the compiled
-program and any additional data that is private to the regex engine
-implementation.
-
-=head3 Perl's C<pprivate> structure
-
-The following structure is used as the C<pprivate> struct by perl's
-regex engine. Since it is specific to perl it is only of curiosity
-value to other engine implementations.
-
- typedef struct regexp_internal {
- regexp_paren_ofs *swap; /* Swap copy of *startp / *endp */
- U32 *offsets; /* offset annotations 20001228 MJD
- data about mapping the program to the
- string*/
- regnode *regstclass; /* Optional startclass as identified or constructed
- by the optimiser */
- struct reg_data *data; /* Additional miscellaneous data used by the program.
- Used to make it easier to clone and free arbitrary
- data that the regops need. Often the ARG field of
- a regop is an index into this structure */
- regnode program[1]; /* Unwarranted chumminess with compiler. */
- } regexp_internal;
-
-=over 5
-
-=item C<swap>
-
-C<swap> formerly was an extra set of startp/endp stored in a
-C<regexp_paren_ofs> struct. This was used when the last successful match
-was from the same pattern as the current pattern, so that a partial
-match didn't overwrite the previous match's results, but it caused a
-problem with re-entrant code such as trying to build the UTF-8 swashes.
-Currently unused and left for backward compatibility with 5.10.0.
-
-=item C<offsets>
-
-Offsets holds a mapping of offset in the C<program>
-to offset in the C<precomp> string. This is only used by ActiveState's
-visual regex debugger.
-
-=item C<regstclass>
-
-Special regop that is used by C<re_intuit_start()> to check if a pattern
-can match at a certain position. For instance if the regex engine knows
-that the pattern must start with a 'Z' then it can scan the string until
-it finds one and then launch the regex engine from there. The routine
-that handles this is called C<find_by_class()>. Sometimes this field
-points at a regop embedded in the program, and sometimes it points at
-an independent synthetic regop that has been constructed by the optimiser.
-
-=item C<data>
-
-This field points at a reg_data structure, which is defined as follows
-
- struct reg_data {
- U32 count;
- U8 *what;
- void* data[1];
- };
-
-This structure is used for handling data structures that the regex engine
-needs to handle specially during a clone or free operation on the compiled
-product. Each element in the data array has a corresponding element in the
-what array. During compilation regops that need special structures stored
-will add an element to each array using the add_data() routine and then store
-the index in the regop.
-
-=item C<program>
-
-Compiled program. Inlined into the structure so the entire struct can be
-treated as a single blob.
-
-=back
-
-=head1 SEE ALSO
-
-L<perlreapi>
-
-L<perlre>
-
-L<perlunitut>
-
-=head1 AUTHOR
-
-by Yves Orton, 2006.
-
-With excerpts from Perl, and contributions and suggestions from
-Ronald J. Kimball, Dave Mitchell, Dominic Dunlop, Mark Jason Dominus,
-Stephen McCamant, and David Landgren.
-
-=head1 LICENCE
-
-Same terms as Perl.
-
-=head1 REFERENCES
-
-[1] L<http://perl.plover.com/Rx/paper/>
-
-[2] L<http://www.unicode.org>
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlrequick.pod b/Master/tlpkg/tlperl/lib/pods/perlrequick.pod
deleted file mode 100644
index bd44d013c54..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlrequick.pod
+++ /dev/null
@@ -1,519 +0,0 @@
-=head1 NAME
-
-perlrequick - Perl regular expressions quick start
-
-=head1 DESCRIPTION
-
-This page covers the very basics of understanding, creating and
-using regular expressions ('regexes') in Perl.
-
-
-=head1 The Guide
-
-=head2 Simple word matching
-
-The simplest regex is simply a word, or more generally, a string of
-characters. A regex consisting of a word matches any string that
-contains that word:
-
- "Hello World" =~ /World/; # matches
-
-In this statement, C<World> is a regex and the C<//> enclosing
-C</World/> tells Perl to search a string for a match. The operator
-C<=~> associates the string with the regex match and produces a true
-value if the regex matched, or false if the regex did not match. In
-our case, C<World> matches the second word in C<"Hello World">, so the
-expression is true. This idea has several variations.
-
-Expressions like this are useful in conditionals:
-
- print "It matches\n" if "Hello World" =~ /World/;
-
-The sense of the match can be reversed by using C<!~> operator:
-
- print "It doesn't match\n" if "Hello World" !~ /World/;
-
-The literal string in the regex can be replaced by a variable:
-
- $greeting = "World";
- print "It matches\n" if "Hello World" =~ /$greeting/;
-
-If you're matching against C<$_>, the C<$_ =~> part can be omitted:
-
- $_ = "Hello World";
- print "It matches\n" if /World/;
-
-Finally, the C<//> default delimiters for a match can be changed to
-arbitrary delimiters by putting an C<'m'> out front:
-
- "Hello World" =~ m!World!; # matches, delimited by '!'
- "Hello World" =~ m{World}; # matches, note the matching '{}'
- "/usr/bin/perl" =~ m"/perl"; # matches after '/usr/bin',
- # '/' becomes an ordinary char
-
-Regexes must match a part of the string I<exactly> in order for the
-statement to be true:
-
- "Hello World" =~ /world/; # doesn't match, case sensitive
- "Hello World" =~ /o W/; # matches, ' ' is an ordinary char
- "Hello World" =~ /World /; # doesn't match, no ' ' at end
-
-Perl will always match at the earliest possible point in the string:
-
- "Hello World" =~ /o/; # matches 'o' in 'Hello'
- "That hat is red" =~ /hat/; # matches 'hat' in 'That'
-
-Not all characters can be used 'as is' in a match. Some characters,
-called B<metacharacters>, are reserved for use in regex notation.
-The metacharacters are
-
- {}[]()^$.|*+?\
-
-A metacharacter can be matched by putting a backslash before it:
-
- "2+2=4" =~ /2+2/; # doesn't match, + is a metacharacter
- "2+2=4" =~ /2\+2/; # matches, \+ is treated like an ordinary +
- 'C:\WIN32' =~ /C:\\WIN/; # matches
- "/usr/bin/perl" =~ /\/usr\/bin\/perl/; # matches
-
-In the last regex, the forward slash C<'/'> is also backslashed,
-because it is used to delimit the regex.
-
-Non-printable ASCII characters are represented by B<escape sequences>.
-Common examples are C<\t> for a tab, C<\n> for a newline, and C<\r>
-for a carriage return. Arbitrary bytes are represented by octal
-escape sequences, e.g., C<\033>, or hexadecimal escape sequences,
-e.g., C<\x1B>:
-
- "1000\t2000" =~ m(0\t2) # matches
- "cat" =~ /\143\x61\x74/ # matches in ASCII, but a weird way to spell cat
-
-Regexes are treated mostly as double-quoted strings, so variable
-substitution works:
-
- $foo = 'house';
- 'cathouse' =~ /cat$foo/; # matches
- 'housecat' =~ /${foo}cat/; # matches
-
-With all of the regexes above, if the regex matched anywhere in the
-string, it was considered a match. To specify I<where> it should
-match, we would use the B<anchor> metacharacters C<^> and C<$>. The
-anchor C<^> means match at the beginning of the string and the anchor
-C<$> means match at the end of the string, or before a newline at the
-end of the string. Some examples:
-
- "housekeeper" =~ /keeper/; # matches
- "housekeeper" =~ /^keeper/; # doesn't match
- "housekeeper" =~ /keeper$/; # matches
- "housekeeper\n" =~ /keeper$/; # matches
- "housekeeper" =~ /^housekeeper$/; # matches
-
-=head2 Using character classes
-
-A B<character class> allows a set of possible characters, rather than
-just a single character, to match at a particular point in a regex.
-Character classes are denoted by brackets C<[...]>, with the set of
-characters to be possibly matched inside. Here are some examples:
-
- /cat/; # matches 'cat'
- /[bcr]at/; # matches 'bat', 'cat', or 'rat'
- "abc" =~ /[cab]/; # matches 'a'
-
-In the last statement, even though C<'c'> is the first character in
-the class, the earliest point at which the regex can match is C<'a'>.
-
- /[yY][eE][sS]/; # match 'yes' in a case-insensitive way
- # 'yes', 'Yes', 'YES', etc.
- /yes/i; # also match 'yes' in a case-insensitive way
-
-The last example shows a match with an C<'i'> B<modifier>, which makes
-the match case-insensitive.
-
-Character classes also have ordinary and special characters, but the
-sets of ordinary and special characters inside a character class are
-different than those outside a character class. The special
-characters for a character class are C<-]\^$> and are matched using an
-escape:
-
- /[\]c]def/; # matches ']def' or 'cdef'
- $x = 'bcr';
- /[$x]at/; # matches 'bat, 'cat', or 'rat'
- /[\$x]at/; # matches '$at' or 'xat'
- /[\\$x]at/; # matches '\at', 'bat, 'cat', or 'rat'
-
-The special character C<'-'> acts as a range operator within character
-classes, so that the unwieldy C<[0123456789]> and C<[abc...xyz]>
-become the svelte C<[0-9]> and C<[a-z]>:
-
- /item[0-9]/; # matches 'item0' or ... or 'item9'
- /[0-9a-fA-F]/; # matches a hexadecimal digit
-
-If C<'-'> is the first or last character in a character class, it is
-treated as an ordinary character.
-
-The special character C<^> in the first position of a character class
-denotes a B<negated character class>, which matches any character but
-those in the brackets. Both C<[...]> and C<[^...]> must match a
-character, or the match fails. Then
-
- /[^a]at/; # doesn't match 'aat' or 'at', but matches
- # all other 'bat', 'cat, '0at', '%at', etc.
- /[^0-9]/; # matches a non-numeric character
- /[a^]at/; # matches 'aat' or '^at'; here '^' is ordinary
-
-Perl has several abbreviations for common character classes. (These
-definitions are those that Perl uses in ASCII-safe mode with the C</a> modifier.
-Otherwise they could match many more non-ASCII Unicode characters as
-well. See L<perlrecharclass/Backslash sequences> for details.)
-
-=over 4
-
-=item *
-
-\d is a digit and represents
-
- [0-9]
-
-=item *
-
-\s is a whitespace character and represents
-
- [\ \t\r\n\f]
-
-=item *
-
-\w is a word character (alphanumeric or _) and represents
-
- [0-9a-zA-Z_]
-
-=item *
-
-\D is a negated \d; it represents any character but a digit
-
- [^0-9]
-
-=item *
-
-\S is a negated \s; it represents any non-whitespace character
-
- [^\s]
-
-=item *
-
-\W is a negated \w; it represents any non-word character
-
- [^\w]
-
-=item *
-
-The period '.' matches any character but "\n"
-
-=back
-
-The C<\d\s\w\D\S\W> abbreviations can be used both inside and outside
-of character classes. Here are some in use:
-
- /\d\d:\d\d:\d\d/; # matches a hh:mm:ss time format
- /[\d\s]/; # matches any digit or whitespace character
- /\w\W\w/; # matches a word char, followed by a
- # non-word char, followed by a word char
- /..rt/; # matches any two chars, followed by 'rt'
- /end\./; # matches 'end.'
- /end[.]/; # same thing, matches 'end.'
-
-The S<B<word anchor> > C<\b> matches a boundary between a word
-character and a non-word character C<\w\W> or C<\W\w>:
-
- $x = "Housecat catenates house and cat";
- $x =~ /\bcat/; # matches cat in 'catenates'
- $x =~ /cat\b/; # matches cat in 'housecat'
- $x =~ /\bcat\b/; # matches 'cat' at end of string
-
-In the last example, the end of the string is considered a word
-boundary.
-
-=head2 Matching this or that
-
-We can match different character strings with the B<alternation>
-metacharacter C<'|'>. To match C<dog> or C<cat>, we form the regex
-C<dog|cat>. As before, Perl will try to match the regex at the
-earliest possible point in the string. At each character position,
-Perl will first try to match the first alternative, C<dog>. If
-C<dog> doesn't match, Perl will then try the next alternative, C<cat>.
-If C<cat> doesn't match either, then the match fails and Perl moves to
-the next position in the string. Some examples:
-
- "cats and dogs" =~ /cat|dog|bird/; # matches "cat"
- "cats and dogs" =~ /dog|cat|bird/; # matches "cat"
-
-Even though C<dog> is the first alternative in the second regex,
-C<cat> is able to match earlier in the string.
-
- "cats" =~ /c|ca|cat|cats/; # matches "c"
- "cats" =~ /cats|cat|ca|c/; # matches "cats"
-
-At a given character position, the first alternative that allows the
-regex match to succeed will be the one that matches. Here, all the
-alternatives match at the first string position, so the first matches.
-
-=head2 Grouping things and hierarchical matching
-
-The B<grouping> metacharacters C<()> allow a part of a regex to be
-treated as a single unit. Parts of a regex are grouped by enclosing
-them in parentheses. The regex C<house(cat|keeper)> means match
-C<house> followed by either C<cat> or C<keeper>. Some more examples
-are
-
- /(a|b)b/; # matches 'ab' or 'bb'
- /(^a|b)c/; # matches 'ac' at start of string or 'bc' anywhere
-
- /house(cat|)/; # matches either 'housecat' or 'house'
- /house(cat(s|)|)/; # matches either 'housecats' or 'housecat' or
- # 'house'. Note groups can be nested.
-
- "20" =~ /(19|20|)\d\d/; # matches the null alternative '()\d\d',
- # because '20\d\d' can't match
-
-=head2 Extracting matches
-
-The grouping metacharacters C<()> also allow the extraction of the
-parts of a string that matched. For each grouping, the part that
-matched inside goes into the special variables C<$1>, C<$2>, etc.
-They can be used just as ordinary variables:
-
- # extract hours, minutes, seconds
- $time =~ /(\d\d):(\d\d):(\d\d)/; # match hh:mm:ss format
- $hours = $1;
- $minutes = $2;
- $seconds = $3;
-
-In list context, a match C</regex/> with groupings will return the
-list of matched values C<($1,$2,...)>. So we could rewrite it as
-
- ($hours, $minutes, $second) = ($time =~ /(\d\d):(\d\d):(\d\d)/);
-
-If the groupings in a regex are nested, C<$1> gets the group with the
-leftmost opening parenthesis, C<$2> the next opening parenthesis,
-etc. For example, here is a complex regex and the matching variables
-indicated below it:
-
- /(ab(cd|ef)((gi)|j))/;
- 1 2 34
-
-Associated with the matching variables C<$1>, C<$2>, ... are
-the B<backreferences> C<\g1>, C<\g2>, ... Backreferences are
-matching variables that can be used I<inside> a regex:
-
- /(\w\w\w)\s\g1/; # find sequences like 'the the' in string
-
-C<$1>, C<$2>, ... should only be used outside of a regex, and C<\g1>,
-C<\g2>, ... only inside a regex.
-
-=head2 Matching repetitions
-
-The B<quantifier> metacharacters C<?>, C<*>, C<+>, and C<{}> allow us
-to determine the number of repeats of a portion of a regex we
-consider to be a match. Quantifiers are put immediately after the
-character, character class, or grouping that we want to specify. They
-have the following meanings:
-
-=over 4
-
-=item *
-
-C<a?> = match 'a' 1 or 0 times
-
-=item *
-
-C<a*> = match 'a' 0 or more times, i.e., any number of times
-
-=item *
-
-C<a+> = match 'a' 1 or more times, i.e., at least once
-
-=item *
-
-C<a{n,m}> = match at least C<n> times, but not more than C<m>
-times.
-
-=item *
-
-C<a{n,}> = match at least C<n> or more times
-
-=item *
-
-C<a{n}> = match exactly C<n> times
-
-=back
-
-Here are some examples:
-
- /[a-z]+\s+\d*/; # match a lowercase word, at least some space, and
- # any number of digits
- /(\w+)\s+\g1/; # match doubled words of arbitrary length
- $year =~ /^\d{2,4}$/; # make sure year is at least 2 but not more
- # than 4 digits
- $year =~ /^\d{4}$|^\d{2}$/; # better match; throw out 3 digit dates
-
-These quantifiers will try to match as much of the string as possible,
-while still allowing the regex to match. So we have
-
- $x = 'the cat in the hat';
- $x =~ /^(.*)(at)(.*)$/; # matches,
- # $1 = 'the cat in the h'
- # $2 = 'at'
- # $3 = '' (0 matches)
-
-The first quantifier C<.*> grabs as much of the string as possible
-while still having the regex match. The second quantifier C<.*> has
-no string left to it, so it matches 0 times.
-
-=head2 More matching
-
-There are a few more things you might want to know about matching
-operators.
-The global modifier C<//g> allows the matching operator to match
-within a string as many times as possible. In scalar context,
-successive matches against a string will have C<//g> jump from match
-to match, keeping track of position in the string as it goes along.
-You can get or set the position with the C<pos()> function.
-For example,
-
- $x = "cat dog house"; # 3 words
- while ($x =~ /(\w+)/g) {
- print "Word is $1, ends at position ", pos $x, "\n";
- }
-
-prints
-
- Word is cat, ends at position 3
- Word is dog, ends at position 7
- Word is house, ends at position 13
-
-A failed match or changing the target string resets the position. If
-you don't want the position reset after failure to match, add the
-C<//c>, as in C</regex/gc>.
-
-In list context, C<//g> returns a list of matched groupings, or if
-there are no groupings, a list of matches to the whole regex. So
-
- @words = ($x =~ /(\w+)/g); # matches,
- # $word[0] = 'cat'
- # $word[1] = 'dog'
- # $word[2] = 'house'
-
-=head2 Search and replace
-
-Search and replace is performed using C<s/regex/replacement/modifiers>.
-The C<replacement> is a Perl double-quoted string that replaces in the
-string whatever is matched with the C<regex>. The operator C<=~> is
-also used here to associate a string with C<s///>. If matching
-against C<$_>, the S<C<$_ =~>> can be dropped. If there is a match,
-C<s///> returns the number of substitutions made; otherwise it returns
-false. Here are a few examples:
-
- $x = "Time to feed the cat!";
- $x =~ s/cat/hacker/; # $x contains "Time to feed the hacker!"
- $y = "'quoted words'";
- $y =~ s/^'(.*)'$/$1/; # strip single quotes,
- # $y contains "quoted words"
-
-With the C<s///> operator, the matched variables C<$1>, C<$2>, etc.
-are immediately available for use in the replacement expression. With
-the global modifier, C<s///g> will search and replace all occurrences
-of the regex in the string:
-
- $x = "I batted 4 for 4";
- $x =~ s/4/four/; # $x contains "I batted four for 4"
- $x = "I batted 4 for 4";
- $x =~ s/4/four/g; # $x contains "I batted four for four"
-
-The non-destructive modifier C<s///r> causes the result of the substitution
-to be returned instead of modifying C<$_> (or whatever variable the
-substitute was bound to with C<=~>):
-
- $x = "I like dogs.";
- $y = $x =~ s/dogs/cats/r;
- print "$x $y\n"; # prints "I like dogs. I like cats."
-
- $x = "Cats are great.";
- print $x =~ s/Cats/Dogs/r =~ s/Dogs/Frogs/r =~ s/Frogs/Hedgehogs/r, "\n";
- # prints "Hedgehogs are great."
-
- @foo = map { s/[a-z]/X/r } qw(a b c 1 2 3);
- # @foo is now qw(X X X 1 2 3)
-
-The evaluation modifier C<s///e> wraps an C<eval{...}> around the
-replacement string and the evaluated result is substituted for the
-matched substring. Some examples:
-
- # reverse all the words in a string
- $x = "the cat in the hat";
- $x =~ s/(\w+)/reverse $1/ge; # $x contains "eht tac ni eht tah"
-
- # convert percentage to decimal
- $x = "A 39% hit rate";
- $x =~ s!(\d+)%!$1/100!e; # $x contains "A 0.39 hit rate"
-
-The last example shows that C<s///> can use other delimiters, such as
-C<s!!!> and C<s{}{}>, and even C<s{}//>. If single quotes are used
-C<s'''>, then the regex and replacement are treated as single-quoted
-strings.
-
-=head2 The split operator
-
-C<split /regex/, string> splits C<string> into a list of substrings
-and returns that list. The regex determines the character sequence
-that C<string> is split with respect to. For example, to split a
-string into words, use
-
- $x = "Calvin and Hobbes";
- @word = split /\s+/, $x; # $word[0] = 'Calvin'
- # $word[1] = 'and'
- # $word[2] = 'Hobbes'
-
-To extract a comma-delimited list of numbers, use
-
- $x = "1.618,2.718, 3.142";
- @const = split /,\s*/, $x; # $const[0] = '1.618'
- # $const[1] = '2.718'
- # $const[2] = '3.142'
-
-If the empty regex C<//> is used, the string is split into individual
-characters. If the regex has groupings, then the list produced contains
-the matched substrings from the groupings as well:
-
- $x = "/usr/bin";
- @parts = split m!(/)!, $x; # $parts[0] = ''
- # $parts[1] = '/'
- # $parts[2] = 'usr'
- # $parts[3] = '/'
- # $parts[4] = 'bin'
-
-Since the first character of $x matched the regex, C<split> prepended
-an empty initial element to the list.
-
-=head1 BUGS
-
-None.
-
-=head1 SEE ALSO
-
-This is just a quick start guide. For a more in-depth tutorial on
-regexes, see L<perlretut> and for the reference page, see L<perlre>.
-
-=head1 AUTHOR AND COPYRIGHT
-
-Copyright (c) 2000 Mark Kvale
-All rights reserved.
-
-This document may be distributed under the same terms as Perl itself.
-
-=head2 Acknowledgments
-
-The author would like to thank Mark-Jason Dominus, Tom Christiansen,
-Ilya Zakharevich, Brad Hughes, and Mike Giroux for all their helpful
-comments.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlreref.pod b/Master/tlpkg/tlperl/lib/pods/perlreref.pod
deleted file mode 100644
index 954a423759c..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlreref.pod
+++ /dev/null
@@ -1,408 +0,0 @@
-=head1 NAME
-
-perlreref - Perl Regular Expressions Reference
-
-=head1 DESCRIPTION
-
-This is a quick reference to Perl's regular expressions.
-For full information see L<perlre> and L<perlop>, as well
-as the L</"SEE ALSO"> section in this document.
-
-=head2 OPERATORS
-
-C<=~> determines to which variable the regex is applied.
-In its absence, $_ is used.
-
- $var =~ /foo/;
-
-C<!~> determines to which variable the regex is applied,
-and negates the result of the match; it returns
-false if the match succeeds, and true if it fails.
-
- $var !~ /foo/;
-
-C<m/pattern/msixpogcdual> searches a string for a pattern match,
-applying the given options.
-
- m Multiline mode - ^ and $ match internal lines
- s match as a Single line - . matches \n
- i case-Insensitive
- x eXtended legibility - free whitespace and comments
- p Preserve a copy of the matched string -
- ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be defined.
- o compile pattern Once
- g Global - all occurrences
- c don't reset pos on failed matches when using /g
- a restrict \d, \s, \w and [:posix:] to match ASCII only
- aa (two a's) also /i matches exclude ASCII/non-ASCII
- l match according to current locale
- u match according to Unicode rules
- d match according to native rules unless something indicates
- Unicode
-
-If 'pattern' is an empty string, the last I<successfully> matched
-regex is used. Delimiters other than '/' may be used for both this
-operator and the following ones. The leading C<m> can be omitted
-if the delimiter is '/'.
-
-C<qr/pattern/msixpodual> lets you store a regex in a variable,
-or pass one around. Modifiers as for C<m//>, and are stored
-within the regex.
-
-C<s/pattern/replacement/msixpogcedual> substitutes matches of
-'pattern' with 'replacement'. Modifiers as for C<m//>,
-with two additions:
-
- e Evaluate 'replacement' as an expression
- r Return substitution and leave the original string untouched.
-
-'e' may be specified multiple times. 'replacement' is interpreted
-as a double quoted string unless a single-quote (C<'>) is the delimiter.
-
-C<?pattern?> is like C<m/pattern/> but matches only once. No alternate
-delimiters can be used. Must be reset with reset().
-
-=head2 SYNTAX
-
- \ Escapes the character immediately following it
- . Matches any single character except a newline (unless /s is
- used)
- ^ Matches at the beginning of the string (or line, if /m is used)
- $ Matches at the end of the string (or line, if /m is used)
- * Matches the preceding element 0 or more times
- + Matches the preceding element 1 or more times
- ? Matches the preceding element 0 or 1 times
- {...} Specifies a range of occurrences for the element preceding it
- [...] Matches any one of the characters contained within the brackets
- (...) Groups subexpressions for capturing to $1, $2...
- (?:...) Groups subexpressions without capturing (cluster)
- | Matches either the subexpression preceding or following it
- \g1 or \g{1}, \g2 ... Matches the text from the Nth group
- \1, \2, \3 ... Matches the text from the Nth group
- \g-1 or \g{-1}, \g-2 ... Matches the text from the Nth previous group
- \g{name} Named backreference
- \k<name> Named backreference
- \k'name' Named backreference
- (?P=name) Named backreference (python syntax)
-
-=head2 ESCAPE SEQUENCES
-
-These work as in normal strings.
-
- \a Alarm (beep)
- \e Escape
- \f Formfeed
- \n Newline
- \r Carriage return
- \t Tab
- \037 Char whose ordinal is the 3 octal digits, max \777
- \o{2307} Char whose ordinal is the octal number, unrestricted
- \x7f Char whose ordinal is the 2 hex digits, max \xFF
- \x{263a} Char whose ordinal is the hex number, unrestricted
- \cx Control-x
- \N{name} A named Unicode character or character sequence
- \N{U+263D} A Unicode character by hex ordinal
-
- \l Lowercase next character
- \u Titlecase next character
- \L Lowercase until \E
- \U Uppercase until \E
- \F Foldcase until \E
- \Q Disable pattern metacharacters until \E
- \E End modification
-
-For Titlecase, see L</Titlecase>.
-
-This one works differently from normal strings:
-
- \b An assertion, not backspace, except in a character class
-
-=head2 CHARACTER CLASSES
-
- [amy] Match 'a', 'm' or 'y'
- [f-j] Dash specifies "range"
- [f-j-] Dash escaped or at start or end means 'dash'
- [^f-j] Caret indicates "match any character _except_ these"
-
-The following sequences (except C<\N>) work within or without a character class.
-The first six are locale aware, all are Unicode aware. See L<perllocale>
-and L<perlunicode> for details.
-
- \d A digit
- \D A nondigit
- \w A word character
- \W A non-word character
- \s A whitespace character
- \S A non-whitespace character
- \h An horizontal whitespace
- \H A non horizontal whitespace
- \N A non newline (when not followed by '{NAME}'; experimental;
- not valid in a character class; equivalent to [^\n]; it's
- like '.' without /s modifier)
- \v A vertical whitespace
- \V A non vertical whitespace
- \R A generic newline (?>\v|\x0D\x0A)
-
- \C Match a byte (with Unicode, '.' matches a character)
- \pP Match P-named (Unicode) property
- \p{...} Match Unicode property with name longer than 1 character
- \PP Match non-P
- \P{...} Match lack of Unicode property with name longer than 1 char
- \X Match Unicode extended grapheme cluster
-
-POSIX character classes and their Unicode and Perl equivalents:
-
- ASCII- Full-
- POSIX range range backslash
- [[:...:]] \p{...} \p{...} sequence Description
-
- -----------------------------------------------------------------------
- alnum PosixAlnum XPosixAlnum Alpha plus Digit
- alpha PosixAlpha XPosixAlpha Alphabetic characters
- ascii ASCII Any ASCII character
- blank PosixBlank XPosixBlank \h Horizontal whitespace;
- full-range also
- written as
- \p{HorizSpace} (GNU
- extension)
- cntrl PosixCntrl XPosixCntrl Control characters
- digit PosixDigit XPosixDigit \d Decimal digits
- graph PosixGraph XPosixGraph Alnum plus Punct
- lower PosixLower XPosixLower Lowercase characters
- print PosixPrint XPosixPrint Graph plus Print, but
- not any Cntrls
- punct PosixPunct XPosixPunct Punctuation and Symbols
- in ASCII-range; just
- punct outside it
- space PosixSpace XPosixSpace [\s\cK]
- PerlSpace XPerlSpace \s Perl's whitespace def'n
- upper PosixUpper XPosixUpper Uppercase characters
- word PosixWord XPosixWord \w Alnum + Unicode marks +
- connectors, like '_'
- (Perl extension)
- xdigit ASCII_Hex_Digit XPosixDigit Hexadecimal digit,
- ASCII-range is
- [0-9A-Fa-f]
-
-Also, various synonyms like C<\p{Alpha}> for C<\p{XPosixAlpha}>; all listed
-in L<perluniprops/Properties accessible through \p{} and \P{}>
-
-Within a character class:
-
- POSIX traditional Unicode
- [:digit:] \d \p{Digit}
- [:^digit:] \D \P{Digit}
-
-=head2 ANCHORS
-
-All are zero-width assertions.
-
- ^ Match string start (or line, if /m is used)
- $ Match string end (or line, if /m is used) or before newline
- \b Match word boundary (between \w and \W)
- \B Match except at word boundary (between \w and \w or \W and \W)
- \A Match string start (regardless of /m)
- \Z Match string end (before optional newline)
- \z Match absolute string end
- \G Match where previous m//g left off
- \K Keep the stuff left of the \K, don't include it in $&
-
-=head2 QUANTIFIERS
-
-Quantifiers are greedy by default and match the B<longest> leftmost.
-
- Maximal Minimal Possessive Allowed range
- ------- ------- ---------- -------------
- {n,m} {n,m}? {n,m}+ Must occur at least n times
- but no more than m times
- {n,} {n,}? {n,}+ Must occur at least n times
- {n} {n}? {n}+ Must occur exactly n times
- * *? *+ 0 or more times (same as {0,})
- + +? ++ 1 or more times (same as {1,})
- ? ?? ?+ 0 or 1 time (same as {0,1})
-
-The possessive forms (new in Perl 5.10) prevent backtracking: what gets
-matched by a pattern with a possessive quantifier will not be backtracked
-into, even if that causes the whole match to fail.
-
-There is no quantifier C<{,n}>. That's interpreted as a literal string.
-
-=head2 EXTENDED CONSTRUCTS
-
- (?#text) A comment
- (?:...) Groups subexpressions without capturing (cluster)
- (?pimsx-imsx:...) Enable/disable option (as per m// modifiers)
- (?=...) Zero-width positive lookahead assertion
- (?!...) Zero-width negative lookahead assertion
- (?<=...) Zero-width positive lookbehind assertion
- (?<!...) Zero-width negative lookbehind assertion
- (?>...) Grab what we can, prohibit backtracking
- (?|...) Branch reset
- (?<name>...) Named capture
- (?'name'...) Named capture
- (?P<name>...) Named capture (python syntax)
- (?{ code }) Embedded code, return value becomes $^R
- (??{ code }) Dynamic regex, return value used as regex
- (?N) Recurse into subpattern number N
- (?-N), (?+N) Recurse into Nth previous/next subpattern
- (?R), (?0) Recurse at the beginning of the whole pattern
- (?&name) Recurse into a named subpattern
- (?P>name) Recurse into a named subpattern (python syntax)
- (?(cond)yes|no)
- (?(cond)yes) Conditional expression, where "cond" can be:
- (?=pat) look-ahead
- (?!pat) negative look-ahead
- (?<=pat) look-behind
- (?<!pat) negative look-behind
- (N) subpattern N has matched something
- (<name>) named subpattern has matched something
- ('name') named subpattern has matched something
- (?{code}) code condition
- (R) true if recursing
- (RN) true if recursing into Nth subpattern
- (R&name) true if recursing into named subpattern
- (DEFINE) always false, no no-pattern allowed
-
-=head2 VARIABLES
-
- $_ Default variable for operators to use
-
- $` Everything prior to matched string
- $& Entire matched string
- $' Everything after to matched string
-
- ${^PREMATCH} Everything prior to matched string
- ${^MATCH} Entire matched string
- ${^POSTMATCH} Everything after to matched string
-
-The use of C<$`>, C<$&> or C<$'> will slow down B<all> regex use
-within your program. Consult L<perlvar> for C<@->
-to see equivalent expressions that won't cause slow down.
-See also L<Devel::SawAmpersand>. Starting with Perl 5.10, you
-can also use the equivalent variables C<${^PREMATCH}>, C<${^MATCH}>
-and C<${^POSTMATCH}>, but for them to be defined, you have to
-specify the C</p> (preserve) modifier on your regular expression.
-
- $1, $2 ... hold the Xth captured expr
- $+ Last parenthesized pattern match
- $^N Holds the most recently closed capture
- $^R Holds the result of the last (?{...}) expr
- @- Offsets of starts of groups. $-[0] holds start of whole match
- @+ Offsets of ends of groups. $+[0] holds end of whole match
- %+ Named capture groups
- %- Named capture groups, as array refs
-
-Captured groups are numbered according to their I<opening> paren.
-
-=head2 FUNCTIONS
-
- lc Lowercase a string
- lcfirst Lowercase first char of a string
- uc Uppercase a string
- ucfirst Titlecase first char of a string
- fc Foldcase a string
-
- pos Return or set current match position
- quotemeta Quote metacharacters
- reset Reset ?pattern? status
- study Analyze string for optimizing matching
-
- split Use a regex to split a string into parts
-
-The first five of these are like the escape sequences C<\L>, C<\l>,
-C<\U>, C<\u>, and C<\F>. For Titlecase, see L</Titlecase>; For
-Foldcase, see L</Foldcase>.
-
-=head2 TERMINOLOGY
-
-=head3 Titlecase
-
-Unicode concept which most often is equal to uppercase, but for
-certain characters like the German "sharp s" there is a difference.
-
-=head3 Foldcase
-
-Unicode form that is useful when comparing strings regardless of case,
-as certain characters have compex one-to-many case mappings. Primarily a
-variant of lowercase.
-
-=head1 AUTHOR
-
-Iain Truskett. Updated by the Perl 5 Porters.
-
-This document may be distributed under the same terms as Perl itself.
-
-=head1 SEE ALSO
-
-=over 4
-
-=item *
-
-L<perlretut> for a tutorial on regular expressions.
-
-=item *
-
-L<perlrequick> for a rapid tutorial.
-
-=item *
-
-L<perlre> for more details.
-
-=item *
-
-L<perlvar> for details on the variables.
-
-=item *
-
-L<perlop> for details on the operators.
-
-=item *
-
-L<perlfunc> for details on the functions.
-
-=item *
-
-L<perlfaq6> for FAQs on regular expressions.
-
-=item *
-
-L<perlrebackslash> for a reference on backslash sequences.
-
-=item *
-
-L<perlrecharclass> for a reference on character classes.
-
-=item *
-
-The L<re> module to alter behaviour and aid
-debugging.
-
-=item *
-
-L<perldebug/"Debugging Regular Expressions">
-
-=item *
-
-L<perluniintro>, L<perlunicode>, L<charnames> and L<perllocale>
-for details on regexes and internationalisation.
-
-=item *
-
-I<Mastering Regular Expressions> by Jeffrey Friedl
-(F<http://oreilly.com/catalog/9780596528126/>) for a thorough grounding and
-reference on the topic.
-
-=back
-
-=head1 THANKS
-
-David P.C. Wollmann,
-Richard Soderberg,
-Sean M. Burke,
-Tom Christiansen,
-Jim Cromie,
-and
-Jeffrey Goff
-for useful advice.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlretut.pod b/Master/tlpkg/tlperl/lib/pods/perlretut.pod
deleted file mode 100644
index a3ff6ad28c4..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlretut.pod
+++ /dev/null
@@ -1,2928 +0,0 @@
-=head1 NAME
-
-perlretut - Perl regular expressions tutorial
-
-=head1 DESCRIPTION
-
-This page provides a basic tutorial on understanding, creating and
-using regular expressions in Perl. It serves as a complement to the
-reference page on regular expressions L<perlre>. Regular expressions
-are an integral part of the C<m//>, C<s///>, C<qr//> and C<split>
-operators and so this tutorial also overlaps with
-L<perlop/"Regexp Quote-Like Operators"> and L<perlfunc/split>.
-
-Perl is widely renowned for excellence in text processing, and regular
-expressions are one of the big factors behind this fame. Perl regular
-expressions display an efficiency and flexibility unknown in most
-other computer languages. Mastering even the basics of regular
-expressions will allow you to manipulate text with surprising ease.
-
-What is a regular expression? A regular expression is simply a string
-that describes a pattern. Patterns are in common use these days;
-examples are the patterns typed into a search engine to find web pages
-and the patterns used to list files in a directory, e.g., C<ls *.txt>
-or C<dir *.*>. In Perl, the patterns described by regular expressions
-are used to search strings, extract desired parts of strings, and to
-do search and replace operations.
-
-Regular expressions have the undeserved reputation of being abstract
-and difficult to understand. Regular expressions are constructed using
-simple concepts like conditionals and loops and are no more difficult
-to understand than the corresponding C<if> conditionals and C<while>
-loops in the Perl language itself. In fact, the main challenge in
-learning regular expressions is just getting used to the terse
-notation used to express these concepts.
-
-This tutorial flattens the learning curve by discussing regular
-expression concepts, along with their notation, one at a time and with
-many examples. The first part of the tutorial will progress from the
-simplest word searches to the basic regular expression concepts. If
-you master the first part, you will have all the tools needed to solve
-about 98% of your needs. The second part of the tutorial is for those
-comfortable with the basics and hungry for more power tools. It
-discusses the more advanced regular expression operators and
-introduces the latest cutting-edge innovations.
-
-A note: to save time, 'regular expression' is often abbreviated as
-regexp or regex. Regexp is a more natural abbreviation than regex, but
-is harder to pronounce. The Perl pod documentation is evenly split on
-regexp vs regex; in Perl, there is more than one way to abbreviate it.
-We'll use regexp in this tutorial.
-
-=head1 Part 1: The basics
-
-=head2 Simple word matching
-
-The simplest regexp is simply a word, or more generally, a string of
-characters. A regexp consisting of a word matches any string that
-contains that word:
-
- "Hello World" =~ /World/; # matches
-
-What is this Perl statement all about? C<"Hello World"> is a simple
-double-quoted string. C<World> is the regular expression and the
-C<//> enclosing C</World/> tells Perl to search a string for a match.
-The operator C<=~> associates the string with the regexp match and
-produces a true value if the regexp matched, or false if the regexp
-did not match. In our case, C<World> matches the second word in
-C<"Hello World">, so the expression is true. Expressions like this
-are useful in conditionals:
-
- if ("Hello World" =~ /World/) {
- print "It matches\n";
- }
- else {
- print "It doesn't match\n";
- }
-
-There are useful variations on this theme. The sense of the match can
-be reversed by using the C<!~> operator:
-
- if ("Hello World" !~ /World/) {
- print "It doesn't match\n";
- }
- else {
- print "It matches\n";
- }
-
-The literal string in the regexp can be replaced by a variable:
-
- $greeting = "World";
- if ("Hello World" =~ /$greeting/) {
- print "It matches\n";
- }
- else {
- print "It doesn't match\n";
- }
-
-If you're matching against the special default variable C<$_>, the
-C<$_ =~> part can be omitted:
-
- $_ = "Hello World";
- if (/World/) {
- print "It matches\n";
- }
- else {
- print "It doesn't match\n";
- }
-
-And finally, the C<//> default delimiters for a match can be changed
-to arbitrary delimiters by putting an C<'m'> out front:
-
- "Hello World" =~ m!World!; # matches, delimited by '!'
- "Hello World" =~ m{World}; # matches, note the matching '{}'
- "/usr/bin/perl" =~ m"/perl"; # matches after '/usr/bin',
- # '/' becomes an ordinary char
-
-C</World/>, C<m!World!>, and C<m{World}> all represent the
-same thing. When, e.g., the quote (C<">) is used as a delimiter, the forward
-slash C<'/'> becomes an ordinary character and can be used in this regexp
-without trouble.
-
-Let's consider how different regexps would match C<"Hello World">:
-
- "Hello World" =~ /world/; # doesn't match
- "Hello World" =~ /o W/; # matches
- "Hello World" =~ /oW/; # doesn't match
- "Hello World" =~ /World /; # doesn't match
-
-The first regexp C<world> doesn't match because regexps are
-case-sensitive. The second regexp matches because the substring
-S<C<'o W'>> occurs in the string S<C<"Hello World">>. The space
-character ' ' is treated like any other character in a regexp and is
-needed to match in this case. The lack of a space character is the
-reason the third regexp C<'oW'> doesn't match. The fourth regexp
-C<'World '> doesn't match because there is a space at the end of the
-regexp, but not at the end of the string. The lesson here is that
-regexps must match a part of the string I<exactly> in order for the
-statement to be true.
-
-If a regexp matches in more than one place in the string, Perl will
-always match at the earliest possible point in the string:
-
- "Hello World" =~ /o/; # matches 'o' in 'Hello'
- "That hat is red" =~ /hat/; # matches 'hat' in 'That'
-
-With respect to character matching, there are a few more points you
-need to know about. First of all, not all characters can be used 'as
-is' in a match. Some characters, called I<metacharacters>, are reserved
-for use in regexp notation. The metacharacters are
-
- {}[]()^$.|*+?\
-
-The significance of each of these will be explained
-in the rest of the tutorial, but for now, it is important only to know
-that a metacharacter can be matched by putting a backslash before it:
-
- "2+2=4" =~ /2+2/; # doesn't match, + is a metacharacter
- "2+2=4" =~ /2\+2/; # matches, \+ is treated like an ordinary +
- "The interval is [0,1)." =~ /[0,1)./ # is a syntax error!
- "The interval is [0,1)." =~ /\[0,1\)\./ # matches
- "#!/usr/bin/perl" =~ /#!\/usr\/bin\/perl/; # matches
-
-In the last regexp, the forward slash C<'/'> is also backslashed,
-because it is used to delimit the regexp. This can lead to LTS
-(leaning toothpick syndrome), however, and it is often more readable
-to change delimiters.
-
- "#!/usr/bin/perl" =~ m!#\!/usr/bin/perl!; # easier to read
-
-The backslash character C<'\'> is a metacharacter itself and needs to
-be backslashed:
-
- 'C:\WIN32' =~ /C:\\WIN/; # matches
-
-In addition to the metacharacters, there are some ASCII characters
-which don't have printable character equivalents and are instead
-represented by I<escape sequences>. Common examples are C<\t> for a
-tab, C<\n> for a newline, C<\r> for a carriage return and C<\a> for a
-bell (or alert). If your string is better thought of as a sequence of arbitrary
-bytes, the octal escape sequence, e.g., C<\033>, or hexadecimal escape
-sequence, e.g., C<\x1B> may be a more natural representation for your
-bytes. Here are some examples of escapes:
-
- "1000\t2000" =~ m(0\t2) # matches
- "1000\n2000" =~ /0\n20/ # matches
- "1000\t2000" =~ /\000\t2/ # doesn't match, "0" ne "\000"
- "cat" =~ /\o{143}\x61\x74/ # matches in ASCII, but a weird way
- # to spell cat
-
-If you've been around Perl a while, all this talk of escape sequences
-may seem familiar. Similar escape sequences are used in double-quoted
-strings and in fact the regexps in Perl are mostly treated as
-double-quoted strings. This means that variables can be used in
-regexps as well. Just like double-quoted strings, the values of the
-variables in the regexp will be substituted in before the regexp is
-evaluated for matching purposes. So we have:
-
- $foo = 'house';
- 'housecat' =~ /$foo/; # matches
- 'cathouse' =~ /cat$foo/; # matches
- 'housecat' =~ /${foo}cat/; # matches
-
-So far, so good. With the knowledge above you can already perform
-searches with just about any literal string regexp you can dream up.
-Here is a I<very simple> emulation of the Unix grep program:
-
- % cat > simple_grep
- #!/usr/bin/perl
- $regexp = shift;
- while (<>) {
- print if /$regexp/;
- }
- ^D
-
- % chmod +x simple_grep
-
- % simple_grep abba /usr/dict/words
- Babbage
- cabbage
- cabbages
- sabbath
- Sabbathize
- Sabbathizes
- sabbatical
- scabbard
- scabbards
-
-This program is easy to understand. C<#!/usr/bin/perl> is the standard
-way to invoke a perl program from the shell.
-S<C<$regexp = shift;>> saves the first command line argument as the
-regexp to be used, leaving the rest of the command line arguments to
-be treated as files. S<C<< while (<>) >>> loops over all the lines in
-all the files. For each line, S<C<print if /$regexp/;>> prints the
-line if the regexp matches the line. In this line, both C<print> and
-C</$regexp/> use the default variable C<$_> implicitly.
-
-With all of the regexps above, if the regexp matched anywhere in the
-string, it was considered a match. Sometimes, however, we'd like to
-specify I<where> in the string the regexp should try to match. To do
-this, we would use the I<anchor> metacharacters C<^> and C<$>. The
-anchor C<^> means match at the beginning of the string and the anchor
-C<$> means match at the end of the string, or before a newline at the
-end of the string. Here is how they are used:
-
- "housekeeper" =~ /keeper/; # matches
- "housekeeper" =~ /^keeper/; # doesn't match
- "housekeeper" =~ /keeper$/; # matches
- "housekeeper\n" =~ /keeper$/; # matches
-
-The second regexp doesn't match because C<^> constrains C<keeper> to
-match only at the beginning of the string, but C<"housekeeper"> has
-keeper starting in the middle. The third regexp does match, since the
-C<$> constrains C<keeper> to match only at the end of the string.
-
-When both C<^> and C<$> are used at the same time, the regexp has to
-match both the beginning and the end of the string, i.e., the regexp
-matches the whole string. Consider
-
- "keeper" =~ /^keep$/; # doesn't match
- "keeper" =~ /^keeper$/; # matches
- "" =~ /^$/; # ^$ matches an empty string
-
-The first regexp doesn't match because the string has more to it than
-C<keep>. Since the second regexp is exactly the string, it
-matches. Using both C<^> and C<$> in a regexp forces the complete
-string to match, so it gives you complete control over which strings
-match and which don't. Suppose you are looking for a fellow named
-bert, off in a string by himself:
-
- "dogbert" =~ /bert/; # matches, but not what you want
-
- "dilbert" =~ /^bert/; # doesn't match, but ..
- "bertram" =~ /^bert/; # matches, so still not good enough
-
- "bertram" =~ /^bert$/; # doesn't match, good
- "dilbert" =~ /^bert$/; # doesn't match, good
- "bert" =~ /^bert$/; # matches, perfect
-
-Of course, in the case of a literal string, one could just as easily
-use the string comparison S<C<$string eq 'bert'>> and it would be
-more efficient. The C<^...$> regexp really becomes useful when we
-add in the more powerful regexp tools below.
-
-=head2 Using character classes
-
-Although one can already do quite a lot with the literal string
-regexps above, we've only scratched the surface of regular expression
-technology. In this and subsequent sections we will introduce regexp
-concepts (and associated metacharacter notations) that will allow a
-regexp to represent not just a single character sequence, but a I<whole
-class> of them.
-
-One such concept is that of a I<character class>. A character class
-allows a set of possible characters, rather than just a single
-character, to match at a particular point in a regexp. Character
-classes are denoted by brackets C<[...]>, with the set of characters
-to be possibly matched inside. Here are some examples:
-
- /cat/; # matches 'cat'
- /[bcr]at/; # matches 'bat, 'cat', or 'rat'
- /item[0123456789]/; # matches 'item0' or ... or 'item9'
- "abc" =~ /[cab]/; # matches 'a'
-
-In the last statement, even though C<'c'> is the first character in
-the class, C<'a'> matches because the first character position in the
-string is the earliest point at which the regexp can match.
-
- /[yY][eE][sS]/; # match 'yes' in a case-insensitive way
- # 'yes', 'Yes', 'YES', etc.
-
-This regexp displays a common task: perform a case-insensitive
-match. Perl provides a way of avoiding all those brackets by simply
-appending an C<'i'> to the end of the match. Then C</[yY][eE][sS]/;>
-can be rewritten as C</yes/i;>. The C<'i'> stands for
-case-insensitive and is an example of a I<modifier> of the matching
-operation. We will meet other modifiers later in the tutorial.
-
-We saw in the section above that there were ordinary characters, which
-represented themselves, and special characters, which needed a
-backslash C<\> to represent themselves. The same is true in a
-character class, but the sets of ordinary and special characters
-inside a character class are different than those outside a character
-class. The special characters for a character class are C<-]\^$> (and
-the pattern delimiter, whatever it is).
-C<]> is special because it denotes the end of a character class. C<$> is
-special because it denotes a scalar variable. C<\> is special because
-it is used in escape sequences, just like above. Here is how the
-special characters C<]$\> are handled:
-
- /[\]c]def/; # matches ']def' or 'cdef'
- $x = 'bcr';
- /[$x]at/; # matches 'bat', 'cat', or 'rat'
- /[\$x]at/; # matches '$at' or 'xat'
- /[\\$x]at/; # matches '\at', 'bat, 'cat', or 'rat'
-
-The last two are a little tricky. In C<[\$x]>, the backslash protects
-the dollar sign, so the character class has two members C<$> and C<x>.
-In C<[\\$x]>, the backslash is protected, so C<$x> is treated as a
-variable and substituted in double quote fashion.
-
-The special character C<'-'> acts as a range operator within character
-classes, so that a contiguous set of characters can be written as a
-range. With ranges, the unwieldy C<[0123456789]> and C<[abc...xyz]>
-become the svelte C<[0-9]> and C<[a-z]>. Some examples are
-
- /item[0-9]/; # matches 'item0' or ... or 'item9'
- /[0-9bx-z]aa/; # matches '0aa', ..., '9aa',
- # 'baa', 'xaa', 'yaa', or 'zaa'
- /[0-9a-fA-F]/; # matches a hexadecimal digit
- /[0-9a-zA-Z_]/; # matches a "word" character,
- # like those in a Perl variable name
-
-If C<'-'> is the first or last character in a character class, it is
-treated as an ordinary character; C<[-ab]>, C<[ab-]> and C<[a\-b]> are
-all equivalent.
-
-The special character C<^> in the first position of a character class
-denotes a I<negated character class>, which matches any character but
-those in the brackets. Both C<[...]> and C<[^...]> must match a
-character, or the match fails. Then
-
- /[^a]at/; # doesn't match 'aat' or 'at', but matches
- # all other 'bat', 'cat, '0at', '%at', etc.
- /[^0-9]/; # matches a non-numeric character
- /[a^]at/; # matches 'aat' or '^at'; here '^' is ordinary
-
-Now, even C<[0-9]> can be a bother to write multiple times, so in the
-interest of saving keystrokes and making regexps more readable, Perl
-has several abbreviations for common character classes, as shown below.
-Since the introduction of Unicode, unless the C<//a> modifier is in
-effect, these character classes match more than just a few characters in
-the ASCII range.
-
-=over 4
-
-=item *
-
-\d matches a digit, not just [0-9] but also digits from non-roman scripts
-
-=item *
-
-\s matches a whitespace character, the set [\ \t\r\n\f] and others
-
-=item *
-
-\w matches a word character (alphanumeric or _), not just [0-9a-zA-Z_]
-but also digits and characters from non-roman scripts
-
-=item *
-
-\D is a negated \d; it represents any other character than a digit, or [^\d]
-
-=item *
-
-\S is a negated \s; it represents any non-whitespace character [^\s]
-
-=item *
-
-\W is a negated \w; it represents any non-word character [^\w]
-
-=item *
-
-The period '.' matches any character but "\n" (unless the modifier C<//s> is
-in effect, as explained below).
-
-=item *
-
-\N, like the period, matches any character but "\n", but it does so
-regardless of whether the modifier C<//s> is in effect.
-
-=back
-
-The C<//a> modifier, available starting in Perl 5.14, is used to
-restrict the matches of \d, \s, and \w to just those in the ASCII range.
-It is useful to keep your program from being needlessly exposed to full
-Unicode (and its accompanying security considerations) when all you want
-is to process English-like text. (The "a" may be doubled, C<//aa>, to
-provide even more restrictions, preventing case-insensitive matching of
-ASCII with non-ASCII characters; otherwise a Unicode "Kelvin Sign"
-would caselessly match a "k" or "K".)
-
-The C<\d\s\w\D\S\W> abbreviations can be used both inside and outside
-of character classes. Here are some in use:
-
- /\d\d:\d\d:\d\d/; # matches a hh:mm:ss time format
- /[\d\s]/; # matches any digit or whitespace character
- /\w\W\w/; # matches a word char, followed by a
- # non-word char, followed by a word char
- /..rt/; # matches any two chars, followed by 'rt'
- /end\./; # matches 'end.'
- /end[.]/; # same thing, matches 'end.'
-
-Because a period is a metacharacter, it needs to be escaped to match
-as an ordinary period. Because, for example, C<\d> and C<\w> are sets
-of characters, it is incorrect to think of C<[^\d\w]> as C<[\D\W]>; in
-fact C<[^\d\w]> is the same as C<[^\w]>, which is the same as
-C<[\W]>. Think DeMorgan's laws.
-
-An anchor useful in basic regexps is the I<word anchor>
-C<\b>. This matches a boundary between a word character and a non-word
-character C<\w\W> or C<\W\w>:
-
- $x = "Housecat catenates house and cat";
- $x =~ /cat/; # matches cat in 'housecat'
- $x =~ /\bcat/; # matches cat in 'catenates'
- $x =~ /cat\b/; # matches cat in 'housecat'
- $x =~ /\bcat\b/; # matches 'cat' at end of string
-
-Note in the last example, the end of the string is considered a word
-boundary.
-
-You might wonder why C<'.'> matches everything but C<"\n"> - why not
-every character? The reason is that often one is matching against
-lines and would like to ignore the newline characters. For instance,
-while the string C<"\n"> represents one line, we would like to think
-of it as empty. Then
-
- "" =~ /^$/; # matches
- "\n" =~ /^$/; # matches, $ anchors before "\n"
-
- "" =~ /./; # doesn't match; it needs a char
- "" =~ /^.$/; # doesn't match; it needs a char
- "\n" =~ /^.$/; # doesn't match; it needs a char other than "\n"
- "a" =~ /^.$/; # matches
- "a\n" =~ /^.$/; # matches, $ anchors before "\n"
-
-This behavior is convenient, because we usually want to ignore
-newlines when we count and match characters in a line. Sometimes,
-however, we want to keep track of newlines. We might even want C<^>
-and C<$> to anchor at the beginning and end of lines within the
-string, rather than just the beginning and end of the string. Perl
-allows us to choose between ignoring and paying attention to newlines
-by using the C<//s> and C<//m> modifiers. C<//s> and C<//m> stand for
-single line and multi-line and they determine whether a string is to
-be treated as one continuous string, or as a set of lines. The two
-modifiers affect two aspects of how the regexp is interpreted: 1) how
-the C<'.'> character class is defined, and 2) where the anchors C<^>
-and C<$> are able to match. Here are the four possible combinations:
-
-=over 4
-
-=item *
-
-no modifiers (//): Default behavior. C<'.'> matches any character
-except C<"\n">. C<^> matches only at the beginning of the string and
-C<$> matches only at the end or before a newline at the end.
-
-=item *
-
-s modifier (//s): Treat string as a single long line. C<'.'> matches
-any character, even C<"\n">. C<^> matches only at the beginning of
-the string and C<$> matches only at the end or before a newline at the
-end.
-
-=item *
-
-m modifier (//m): Treat string as a set of multiple lines. C<'.'>
-matches any character except C<"\n">. C<^> and C<$> are able to match
-at the start or end of I<any> line within the string.
-
-=item *
-
-both s and m modifiers (//sm): Treat string as a single long line, but
-detect multiple lines. C<'.'> matches any character, even
-C<"\n">. C<^> and C<$>, however, are able to match at the start or end
-of I<any> line within the string.
-
-=back
-
-Here are examples of C<//s> and C<//m> in action:
-
- $x = "There once was a girl\nWho programmed in Perl\n";
-
- $x =~ /^Who/; # doesn't match, "Who" not at start of string
- $x =~ /^Who/s; # doesn't match, "Who" not at start of string
- $x =~ /^Who/m; # matches, "Who" at start of second line
- $x =~ /^Who/sm; # matches, "Who" at start of second line
-
- $x =~ /girl.Who/; # doesn't match, "." doesn't match "\n"
- $x =~ /girl.Who/s; # matches, "." matches "\n"
- $x =~ /girl.Who/m; # doesn't match, "." doesn't match "\n"
- $x =~ /girl.Who/sm; # matches, "." matches "\n"
-
-Most of the time, the default behavior is what is wanted, but C<//s> and
-C<//m> are occasionally very useful. If C<//m> is being used, the start
-of the string can still be matched with C<\A> and the end of the string
-can still be matched with the anchors C<\Z> (matches both the end and
-the newline before, like C<$>), and C<\z> (matches only the end):
-
- $x =~ /^Who/m; # matches, "Who" at start of second line
- $x =~ /\AWho/m; # doesn't match, "Who" is not at start of string
-
- $x =~ /girl$/m; # matches, "girl" at end of first line
- $x =~ /girl\Z/m; # doesn't match, "girl" is not at end of string
-
- $x =~ /Perl\Z/m; # matches, "Perl" is at newline before end
- $x =~ /Perl\z/m; # doesn't match, "Perl" is not at end of string
-
-We now know how to create choices among classes of characters in a
-regexp. What about choices among words or character strings? Such
-choices are described in the next section.
-
-=head2 Matching this or that
-
-Sometimes we would like our regexp to be able to match different
-possible words or character strings. This is accomplished by using
-the I<alternation> metacharacter C<|>. To match C<dog> or C<cat>, we
-form the regexp C<dog|cat>. As before, Perl will try to match the
-regexp at the earliest possible point in the string. At each
-character position, Perl will first try to match the first
-alternative, C<dog>. If C<dog> doesn't match, Perl will then try the
-next alternative, C<cat>. If C<cat> doesn't match either, then the
-match fails and Perl moves to the next position in the string. Some
-examples:
-
- "cats and dogs" =~ /cat|dog|bird/; # matches "cat"
- "cats and dogs" =~ /dog|cat|bird/; # matches "cat"
-
-Even though C<dog> is the first alternative in the second regexp,
-C<cat> is able to match earlier in the string.
-
- "cats" =~ /c|ca|cat|cats/; # matches "c"
- "cats" =~ /cats|cat|ca|c/; # matches "cats"
-
-Here, all the alternatives match at the first string position, so the
-first alternative is the one that matches. If some of the
-alternatives are truncations of the others, put the longest ones first
-to give them a chance to match.
-
- "cab" =~ /a|b|c/ # matches "c"
- # /a|b|c/ == /[abc]/
-
-The last example points out that character classes are like
-alternations of characters. At a given character position, the first
-alternative that allows the regexp match to succeed will be the one
-that matches.
-
-=head2 Grouping things and hierarchical matching
-
-Alternation allows a regexp to choose among alternatives, but by
-itself it is unsatisfying. The reason is that each alternative is a whole
-regexp, but sometime we want alternatives for just part of a
-regexp. For instance, suppose we want to search for housecats or
-housekeepers. The regexp C<housecat|housekeeper> fits the bill, but is
-inefficient because we had to type C<house> twice. It would be nice to
-have parts of the regexp be constant, like C<house>, and some
-parts have alternatives, like C<cat|keeper>.
-
-The I<grouping> metacharacters C<()> solve this problem. Grouping
-allows parts of a regexp to be treated as a single unit. Parts of a
-regexp are grouped by enclosing them in parentheses. Thus we could solve
-the C<housecat|housekeeper> by forming the regexp as
-C<house(cat|keeper)>. The regexp C<house(cat|keeper)> means match
-C<house> followed by either C<cat> or C<keeper>. Some more examples
-are
-
- /(a|b)b/; # matches 'ab' or 'bb'
- /(ac|b)b/; # matches 'acb' or 'bb'
- /(^a|b)c/; # matches 'ac' at start of string or 'bc' anywhere
- /(a|[bc])d/; # matches 'ad', 'bd', or 'cd'
-
- /house(cat|)/; # matches either 'housecat' or 'house'
- /house(cat(s|)|)/; # matches either 'housecats' or 'housecat' or
- # 'house'. Note groups can be nested.
-
- /(19|20|)\d\d/; # match years 19xx, 20xx, or the Y2K problem, xx
- "20" =~ /(19|20|)\d\d/; # matches the null alternative '()\d\d',
- # because '20\d\d' can't match
-
-Alternations behave the same way in groups as out of them: at a given
-string position, the leftmost alternative that allows the regexp to
-match is taken. So in the last example at the first string position,
-C<"20"> matches the second alternative, but there is nothing left over
-to match the next two digits C<\d\d>. So Perl moves on to the next
-alternative, which is the null alternative and that works, since
-C<"20"> is two digits.
-
-The process of trying one alternative, seeing if it matches, and
-moving on to the next alternative, while going back in the string
-from where the previous alternative was tried, if it doesn't, is called
-I<backtracking>. The term 'backtracking' comes from the idea that
-matching a regexp is like a walk in the woods. Successfully matching
-a regexp is like arriving at a destination. There are many possible
-trailheads, one for each string position, and each one is tried in
-order, left to right. From each trailhead there may be many paths,
-some of which get you there, and some which are dead ends. When you
-walk along a trail and hit a dead end, you have to backtrack along the
-trail to an earlier point to try another trail. If you hit your
-destination, you stop immediately and forget about trying all the
-other trails. You are persistent, and only if you have tried all the
-trails from all the trailheads and not arrived at your destination, do
-you declare failure. To be concrete, here is a step-by-step analysis
-of what Perl does when it tries to match the regexp
-
- "abcde" =~ /(abd|abc)(df|d|de)/;
-
-=over 4
-
-=item 0
-
-Start with the first letter in the string 'a'.
-
-=item 1
-
-Try the first alternative in the first group 'abd'.
-
-=item 2
-
-Match 'a' followed by 'b'. So far so good.
-
-=item 3
-
-'d' in the regexp doesn't match 'c' in the string - a dead
-end. So backtrack two characters and pick the second alternative in
-the first group 'abc'.
-
-=item 4
-
-Match 'a' followed by 'b' followed by 'c'. We are on a roll
-and have satisfied the first group. Set $1 to 'abc'.
-
-=item 5
-
-Move on to the second group and pick the first alternative
-'df'.
-
-=item 6
-
-Match the 'd'.
-
-=item 7
-
-'f' in the regexp doesn't match 'e' in the string, so a dead
-end. Backtrack one character and pick the second alternative in the
-second group 'd'.
-
-=item 8
-
-'d' matches. The second grouping is satisfied, so set $2 to
-'d'.
-
-=item 9
-
-We are at the end of the regexp, so we are done! We have
-matched 'abcd' out of the string "abcde".
-
-=back
-
-There are a couple of things to note about this analysis. First, the
-third alternative in the second group 'de' also allows a match, but we
-stopped before we got to it - at a given character position, leftmost
-wins. Second, we were able to get a match at the first character
-position of the string 'a'. If there were no matches at the first
-position, Perl would move to the second character position 'b' and
-attempt the match all over again. Only when all possible paths at all
-possible character positions have been exhausted does Perl give
-up and declare S<C<$string =~ /(abd|abc)(df|d|de)/;>> to be false.
-
-Even with all this work, regexp matching happens remarkably fast. To
-speed things up, Perl compiles the regexp into a compact sequence of
-opcodes that can often fit inside a processor cache. When the code is
-executed, these opcodes can then run at full throttle and search very
-quickly.
-
-=head2 Extracting matches
-
-The grouping metacharacters C<()> also serve another completely
-different function: they allow the extraction of the parts of a string
-that matched. This is very useful to find out what matched and for
-text processing in general. For each grouping, the part that matched
-inside goes into the special variables C<$1>, C<$2>, etc. They can be
-used just as ordinary variables:
-
- # extract hours, minutes, seconds
- if ($time =~ /(\d\d):(\d\d):(\d\d)/) { # match hh:mm:ss format
- $hours = $1;
- $minutes = $2;
- $seconds = $3;
- }
-
-Now, we know that in scalar context,
-S<C<$time =~ /(\d\d):(\d\d):(\d\d)/>> returns a true or false
-value. In list context, however, it returns the list of matched values
-C<($1,$2,$3)>. So we could write the code more compactly as
-
- # extract hours, minutes, seconds
- ($hours, $minutes, $second) = ($time =~ /(\d\d):(\d\d):(\d\d)/);
-
-If the groupings in a regexp are nested, C<$1> gets the group with the
-leftmost opening parenthesis, C<$2> the next opening parenthesis,
-etc. Here is a regexp with nested groups:
-
- /(ab(cd|ef)((gi)|j))/;
- 1 2 34
-
-If this regexp matches, C<$1> contains a string starting with
-C<'ab'>, C<$2> is either set to C<'cd'> or C<'ef'>, C<$3> equals either
-C<'gi'> or C<'j'>, and C<$4> is either set to C<'gi'>, just like C<$3>,
-or it remains undefined.
-
-For convenience, Perl sets C<$+> to the string held by the highest numbered
-C<$1>, C<$2>,... that got assigned (and, somewhat related, C<$^N> to the
-value of the C<$1>, C<$2>,... most-recently assigned; i.e. the C<$1>,
-C<$2>,... associated with the rightmost closing parenthesis used in the
-match).
-
-
-=head2 Backreferences
-
-Closely associated with the matching variables C<$1>, C<$2>, ... are
-the I<backreferences> C<\g1>, C<\g2>,... Backreferences are simply
-matching variables that can be used I<inside> a regexp. This is a
-really nice feature; what matches later in a regexp is made to depend on
-what matched earlier in the regexp. Suppose we wanted to look
-for doubled words in a text, like 'the the'. The following regexp finds
-all 3-letter doubles with a space in between:
-
- /\b(\w\w\w)\s\g1\b/;
-
-The grouping assigns a value to \g1, so that the same 3-letter sequence
-is used for both parts.
-
-A similar task is to find words consisting of two identical parts:
-
- % simple_grep '^(\w\w\w\w|\w\w\w|\w\w|\w)\g1$' /usr/dict/words
- beriberi
- booboo
- coco
- mama
- murmur
- papa
-
-The regexp has a single grouping which considers 4-letter
-combinations, then 3-letter combinations, etc., and uses C<\g1> to look for
-a repeat. Although C<$1> and C<\g1> represent the same thing, care should be
-taken to use matched variables C<$1>, C<$2>,... only I<outside> a regexp
-and backreferences C<\g1>, C<\g2>,... only I<inside> a regexp; not doing
-so may lead to surprising and unsatisfactory results.
-
-
-=head2 Relative backreferences
-
-Counting the opening parentheses to get the correct number for a
-backreference is error-prone as soon as there is more than one
-capturing group. A more convenient technique became available
-with Perl 5.10: relative backreferences. To refer to the immediately
-preceding capture group one now may write C<\g{-1}>, the next but
-last is available via C<\g{-2}>, and so on.
-
-Another good reason in addition to readability and maintainability
-for using relative backreferences is illustrated by the following example,
-where a simple pattern for matching peculiar strings is used:
-
- $a99a = '([a-z])(\d)\g2\g1'; # matches a11a, g22g, x33x, etc.
-
-Now that we have this pattern stored as a handy string, we might feel
-tempted to use it as a part of some other pattern:
-
- $line = "code=e99e";
- if ($line =~ /^(\w+)=$a99a$/){ # unexpected behavior!
- print "$1 is valid\n";
- } else {
- print "bad line: '$line'\n";
- }
-
-But this doesn't match, at least not the way one might expect. Only
-after inserting the interpolated C<$a99a> and looking at the resulting
-full text of the regexp is it obvious that the backreferences have
-backfired. The subexpression C<(\w+)> has snatched number 1 and
-demoted the groups in C<$a99a> by one rank. This can be avoided by
-using relative backreferences:
-
- $a99a = '([a-z])(\d)\g{-1}\g{-2}'; # safe for being interpolated
-
-
-=head2 Named backreferences
-
-Perl 5.10 also introduced named capture groups and named backreferences.
-To attach a name to a capturing group, you write either
-C<< (?<name>...) >> or C<< (?'name'...) >>. The backreference may
-then be written as C<\g{name}>. It is permissible to attach the
-same name to more than one group, but then only the leftmost one of the
-eponymous set can be referenced. Outside of the pattern a named
-capture group is accessible through the C<%+> hash.
-
-Assuming that we have to match calendar dates which may be given in one
-of the three formats yyyy-mm-dd, mm/dd/yyyy or dd.mm.yyyy, we can write
-three suitable patterns where we use 'd', 'm' and 'y' respectively as the
-names of the groups capturing the pertaining components of a date. The
-matching operation combines the three patterns as alternatives:
-
- $fmt1 = '(?<y>\d\d\d\d)-(?<m>\d\d)-(?<d>\d\d)';
- $fmt2 = '(?<m>\d\d)/(?<d>\d\d)/(?<y>\d\d\d\d)';
- $fmt3 = '(?<d>\d\d)\.(?<m>\d\d)\.(?<y>\d\d\d\d)';
- for my $d qw( 2006-10-21 15.01.2007 10/31/2005 ){
- if ( $d =~ m{$fmt1|$fmt2|$fmt3} ){
- print "day=$+{d} month=$+{m} year=$+{y}\n";
- }
- }
-
-If any of the alternatives matches, the hash C<%+> is bound to contain the
-three key-value pairs.
-
-
-=head2 Alternative capture group numbering
-
-Yet another capturing group numbering technique (also as from Perl 5.10)
-deals with the problem of referring to groups within a set of alternatives.
-Consider a pattern for matching a time of the day, civil or military style:
-
- if ( $time =~ /(\d\d|\d):(\d\d)|(\d\d)(\d\d)/ ){
- # process hour and minute
- }
-
-Processing the results requires an additional if statement to determine
-whether C<$1> and C<$2> or C<$3> and C<$4> contain the goodies. It would
-be easier if we could use group numbers 1 and 2 in second alternative as
-well, and this is exactly what the parenthesized construct C<(?|...)>,
-set around an alternative achieves. Here is an extended version of the
-previous pattern:
-
- if ( $time =~ /(?|(\d\d|\d):(\d\d)|(\d\d)(\d\d))\s+([A-Z][A-Z][A-Z])/ ){
- print "hour=$1 minute=$2 zone=$3\n";
- }
-
-Within the alternative numbering group, group numbers start at the same
-position for each alternative. After the group, numbering continues
-with one higher than the maximum reached across all the alternatives.
-
-=head2 Position information
-
-In addition to what was matched, Perl (since 5.6.0) also provides the
-positions of what was matched as contents of the C<@-> and C<@+>
-arrays. C<$-[0]> is the position of the start of the entire match and
-C<$+[0]> is the position of the end. Similarly, C<$-[n]> is the
-position of the start of the C<$n> match and C<$+[n]> is the position
-of the end. If C<$n> is undefined, so are C<$-[n]> and C<$+[n]>. Then
-this code
-
- $x = "Mmm...donut, thought Homer";
- $x =~ /^(Mmm|Yech)\.\.\.(donut|peas)/; # matches
- foreach $expr (1..$#-) {
- print "Match $expr: '${$expr}' at position ($-[$expr],$+[$expr])\n";
- }
-
-prints
-
- Match 1: 'Mmm' at position (0,3)
- Match 2: 'donut' at position (6,11)
-
-Even if there are no groupings in a regexp, it is still possible to
-find out what exactly matched in a string. If you use them, Perl
-will set C<$`> to the part of the string before the match, will set C<$&>
-to the part of the string that matched, and will set C<$'> to the part
-of the string after the match. An example:
-
- $x = "the cat caught the mouse";
- $x =~ /cat/; # $` = 'the ', $& = 'cat', $' = ' caught the mouse'
- $x =~ /the/; # $` = '', $& = 'the', $' = ' cat caught the mouse'
-
-In the second match, C<$`> equals C<''> because the regexp matched at the
-first character position in the string and stopped; it never saw the
-second 'the'. It is important to note that using C<$`> and C<$'>
-slows down regexp matching quite a bit, while C<$&> slows it down to a
-lesser extent, because if they are used in one regexp in a program,
-they are generated for I<all> regexps in the program. So if raw
-performance is a goal of your application, they should be avoided.
-If you need to extract the corresponding substrings, use C<@-> and
-C<@+> instead:
-
- $` is the same as substr( $x, 0, $-[0] )
- $& is the same as substr( $x, $-[0], $+[0]-$-[0] )
- $' is the same as substr( $x, $+[0] )
-
-As of Perl 5.10, the C<${^PREMATCH}>, C<${^MATCH}> and C<${^POSTMATCH}>
-variables may be used. These are only set if the C</p> modifier is present.
-Consequently they do not penalize the rest of the program.
-
-=head2 Non-capturing groupings
-
-A group that is required to bundle a set of alternatives may or may not be
-useful as a capturing group. If it isn't, it just creates a superfluous
-addition to the set of available capture group values, inside as well as
-outside the regexp. Non-capturing groupings, denoted by C<(?:regexp)>,
-still allow the regexp to be treated as a single unit, but don't establish
-a capturing group at the same time. Both capturing and non-capturing
-groupings are allowed to co-exist in the same regexp. Because there is
-no extraction, non-capturing groupings are faster than capturing
-groupings. Non-capturing groupings are also handy for choosing exactly
-which parts of a regexp are to be extracted to matching variables:
-
- # match a number, $1-$4 are set, but we only want $1
- /([+-]?\ *(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?)/;
-
- # match a number faster , only $1 is set
- /([+-]?\ *(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?)/;
-
- # match a number, get $1 = whole number, $2 = exponent
- /([+-]?\ *(?:\d+(?:\.\d*)?|\.\d+)(?:[eE]([+-]?\d+))?)/;
-
-Non-capturing groupings are also useful for removing nuisance
-elements gathered from a split operation where parentheses are
-required for some reason:
-
- $x = '12aba34ba5';
- @num = split /(a|b)+/, $x; # @num = ('12','a','34','a','5')
- @num = split /(?:a|b)+/, $x; # @num = ('12','34','5')
-
-
-=head2 Matching repetitions
-
-The examples in the previous section display an annoying weakness. We
-were only matching 3-letter words, or chunks of words of 4 letters or
-less. We'd like to be able to match words or, more generally, strings
-of any length, without writing out tedious alternatives like
-C<\w\w\w\w|\w\w\w|\w\w|\w>.
-
-This is exactly the problem the I<quantifier> metacharacters C<?>,
-C<*>, C<+>, and C<{}> were created for. They allow us to delimit the
-number of repeats for a portion of a regexp we consider to be a
-match. Quantifiers are put immediately after the character, character
-class, or grouping that we want to specify. They have the following
-meanings:
-
-=over 4
-
-=item *
-
-C<a?> means: match 'a' 1 or 0 times
-
-=item *
-
-C<a*> means: match 'a' 0 or more times, i.e., any number of times
-
-=item *
-
-C<a+> means: match 'a' 1 or more times, i.e., at least once
-
-=item *
-
-C<a{n,m}> means: match at least C<n> times, but not more than C<m>
-times.
-
-=item *
-
-C<a{n,}> means: match at least C<n> or more times
-
-=item *
-
-C<a{n}> means: match exactly C<n> times
-
-=back
-
-Here are some examples:
-
- /[a-z]+\s+\d*/; # match a lowercase word, at least one space, and
- # any number of digits
- /(\w+)\s+\g1/; # match doubled words of arbitrary length
- /y(es)?/i; # matches 'y', 'Y', or a case-insensitive 'yes'
- $year =~ /^\d{2,4}$/; # make sure year is at least 2 but not more
- # than 4 digits
- $year =~ /^\d{4}$|^\d{2}$/; # better match; throw out 3-digit dates
- $year =~ /^\d{2}(\d{2})?$/; # same thing written differently. However,
- # this captures the last two digits in $1
- # and the other does not.
-
- % simple_grep '^(\w+)\g1$' /usr/dict/words # isn't this easier?
- beriberi
- booboo
- coco
- mama
- murmur
- papa
-
-For all of these quantifiers, Perl will try to match as much of the
-string as possible, while still allowing the regexp to succeed. Thus
-with C</a?.../>, Perl will first try to match the regexp with the C<a>
-present; if that fails, Perl will try to match the regexp without the
-C<a> present. For the quantifier C<*>, we get the following:
-
- $x = "the cat in the hat";
- $x =~ /^(.*)(cat)(.*)$/; # matches,
- # $1 = 'the '
- # $2 = 'cat'
- # $3 = ' in the hat'
-
-Which is what we might expect, the match finds the only C<cat> in the
-string and locks onto it. Consider, however, this regexp:
-
- $x =~ /^(.*)(at)(.*)$/; # matches,
- # $1 = 'the cat in the h'
- # $2 = 'at'
- # $3 = '' (0 characters match)
-
-One might initially guess that Perl would find the C<at> in C<cat> and
-stop there, but that wouldn't give the longest possible string to the
-first quantifier C<.*>. Instead, the first quantifier C<.*> grabs as
-much of the string as possible while still having the regexp match. In
-this example, that means having the C<at> sequence with the final C<at>
-in the string. The other important principle illustrated here is that,
-when there are two or more elements in a regexp, the I<leftmost>
-quantifier, if there is one, gets to grab as much of the string as
-possible, leaving the rest of the regexp to fight over scraps. Thus in
-our example, the first quantifier C<.*> grabs most of the string, while
-the second quantifier C<.*> gets the empty string. Quantifiers that
-grab as much of the string as possible are called I<maximal match> or
-I<greedy> quantifiers.
-
-When a regexp can match a string in several different ways, we can use
-the principles above to predict which way the regexp will match:
-
-=over 4
-
-=item *
-
-Principle 0: Taken as a whole, any regexp will be matched at the
-earliest possible position in the string.
-
-=item *
-
-Principle 1: In an alternation C<a|b|c...>, the leftmost alternative
-that allows a match for the whole regexp will be the one used.
-
-=item *
-
-Principle 2: The maximal matching quantifiers C<?>, C<*>, C<+> and
-C<{n,m}> will in general match as much of the string as possible while
-still allowing the whole regexp to match.
-
-=item *
-
-Principle 3: If there are two or more elements in a regexp, the
-leftmost greedy quantifier, if any, will match as much of the string
-as possible while still allowing the whole regexp to match. The next
-leftmost greedy quantifier, if any, will try to match as much of the
-string remaining available to it as possible, while still allowing the
-whole regexp to match. And so on, until all the regexp elements are
-satisfied.
-
-=back
-
-As we have seen above, Principle 0 overrides the others. The regexp
-will be matched as early as possible, with the other principles
-determining how the regexp matches at that earliest character
-position.
-
-Here is an example of these principles in action:
-
- $x = "The programming republic of Perl";
- $x =~ /^(.+)(e|r)(.*)$/; # matches,
- # $1 = 'The programming republic of Pe'
- # $2 = 'r'
- # $3 = 'l'
-
-This regexp matches at the earliest string position, C<'T'>. One
-might think that C<e>, being leftmost in the alternation, would be
-matched, but C<r> produces the longest string in the first quantifier.
-
- $x =~ /(m{1,2})(.*)$/; # matches,
- # $1 = 'mm'
- # $2 = 'ing republic of Perl'
-
-Here, The earliest possible match is at the first C<'m'> in
-C<programming>. C<m{1,2}> is the first quantifier, so it gets to match
-a maximal C<mm>.
-
- $x =~ /.*(m{1,2})(.*)$/; # matches,
- # $1 = 'm'
- # $2 = 'ing republic of Perl'
-
-Here, the regexp matches at the start of the string. The first
-quantifier C<.*> grabs as much as possible, leaving just a single
-C<'m'> for the second quantifier C<m{1,2}>.
-
- $x =~ /(.?)(m{1,2})(.*)$/; # matches,
- # $1 = 'a'
- # $2 = 'mm'
- # $3 = 'ing republic of Perl'
-
-Here, C<.?> eats its maximal one character at the earliest possible
-position in the string, C<'a'> in C<programming>, leaving C<m{1,2}>
-the opportunity to match both C<m>'s. Finally,
-
- "aXXXb" =~ /(X*)/; # matches with $1 = ''
-
-because it can match zero copies of C<'X'> at the beginning of the
-string. If you definitely want to match at least one C<'X'>, use
-C<X+>, not C<X*>.
-
-Sometimes greed is not good. At times, we would like quantifiers to
-match a I<minimal> piece of string, rather than a maximal piece. For
-this purpose, Larry Wall created the I<minimal match> or
-I<non-greedy> quantifiers C<??>, C<*?>, C<+?>, and C<{}?>. These are
-the usual quantifiers with a C<?> appended to them. They have the
-following meanings:
-
-=over 4
-
-=item *
-
-C<a??> means: match 'a' 0 or 1 times. Try 0 first, then 1.
-
-=item *
-
-C<a*?> means: match 'a' 0 or more times, i.e., any number of times,
-but as few times as possible
-
-=item *
-
-C<a+?> means: match 'a' 1 or more times, i.e., at least once, but
-as few times as possible
-
-=item *
-
-C<a{n,m}?> means: match at least C<n> times, not more than C<m>
-times, as few times as possible
-
-=item *
-
-C<a{n,}?> means: match at least C<n> times, but as few times as
-possible
-
-=item *
-
-C<a{n}?> means: match exactly C<n> times. Because we match exactly
-C<n> times, C<a{n}?> is equivalent to C<a{n}> and is just there for
-notational consistency.
-
-=back
-
-Let's look at the example above, but with minimal quantifiers:
-
- $x = "The programming republic of Perl";
- $x =~ /^(.+?)(e|r)(.*)$/; # matches,
- # $1 = 'Th'
- # $2 = 'e'
- # $3 = ' programming republic of Perl'
-
-The minimal string that will allow both the start of the string C<^>
-and the alternation to match is C<Th>, with the alternation C<e|r>
-matching C<e>. The second quantifier C<.*> is free to gobble up the
-rest of the string.
-
- $x =~ /(m{1,2}?)(.*?)$/; # matches,
- # $1 = 'm'
- # $2 = 'ming republic of Perl'
-
-The first string position that this regexp can match is at the first
-C<'m'> in C<programming>. At this position, the minimal C<m{1,2}?>
-matches just one C<'m'>. Although the second quantifier C<.*?> would
-prefer to match no characters, it is constrained by the end-of-string
-anchor C<$> to match the rest of the string.
-
- $x =~ /(.*?)(m{1,2}?)(.*)$/; # matches,
- # $1 = 'The progra'
- # $2 = 'm'
- # $3 = 'ming republic of Perl'
-
-In this regexp, you might expect the first minimal quantifier C<.*?>
-to match the empty string, because it is not constrained by a C<^>
-anchor to match the beginning of the word. Principle 0 applies here,
-however. Because it is possible for the whole regexp to match at the
-start of the string, it I<will> match at the start of the string. Thus
-the first quantifier has to match everything up to the first C<m>. The
-second minimal quantifier matches just one C<m> and the third
-quantifier matches the rest of the string.
-
- $x =~ /(.??)(m{1,2})(.*)$/; # matches,
- # $1 = 'a'
- # $2 = 'mm'
- # $3 = 'ing republic of Perl'
-
-Just as in the previous regexp, the first quantifier C<.??> can match
-earliest at position C<'a'>, so it does. The second quantifier is
-greedy, so it matches C<mm>, and the third matches the rest of the
-string.
-
-We can modify principle 3 above to take into account non-greedy
-quantifiers:
-
-=over 4
-
-=item *
-
-Principle 3: If there are two or more elements in a regexp, the
-leftmost greedy (non-greedy) quantifier, if any, will match as much
-(little) of the string as possible while still allowing the whole
-regexp to match. The next leftmost greedy (non-greedy) quantifier, if
-any, will try to match as much (little) of the string remaining
-available to it as possible, while still allowing the whole regexp to
-match. And so on, until all the regexp elements are satisfied.
-
-=back
-
-Just like alternation, quantifiers are also susceptible to
-backtracking. Here is a step-by-step analysis of the example
-
- $x = "the cat in the hat";
- $x =~ /^(.*)(at)(.*)$/; # matches,
- # $1 = 'the cat in the h'
- # $2 = 'at'
- # $3 = '' (0 matches)
-
-=over 4
-
-=item 0
-
-Start with the first letter in the string 't'.
-
-=item 1
-
-The first quantifier '.*' starts out by matching the whole
-string 'the cat in the hat'.
-
-=item 2
-
-'a' in the regexp element 'at' doesn't match the end of the
-string. Backtrack one character.
-
-=item 3
-
-'a' in the regexp element 'at' still doesn't match the last
-letter of the string 't', so backtrack one more character.
-
-=item 4
-
-Now we can match the 'a' and the 't'.
-
-=item 5
-
-Move on to the third element '.*'. Since we are at the end of
-the string and '.*' can match 0 times, assign it the empty string.
-
-=item 6
-
-We are done!
-
-=back
-
-Most of the time, all this moving forward and backtracking happens
-quickly and searching is fast. There are some pathological regexps,
-however, whose execution time exponentially grows with the size of the
-string. A typical structure that blows up in your face is of the form
-
- /(a|b+)*/;
-
-The problem is the nested indeterminate quantifiers. There are many
-different ways of partitioning a string of length n between the C<+>
-and C<*>: one repetition with C<b+> of length n, two repetitions with
-the first C<b+> length k and the second with length n-k, m repetitions
-whose bits add up to length n, etc. In fact there are an exponential
-number of ways to partition a string as a function of its length. A
-regexp may get lucky and match early in the process, but if there is
-no match, Perl will try I<every> possibility before giving up. So be
-careful with nested C<*>'s, C<{n,m}>'s, and C<+>'s. The book
-I<Mastering Regular Expressions> by Jeffrey Friedl gives a wonderful
-discussion of this and other efficiency issues.
-
-
-=head2 Possessive quantifiers
-
-Backtracking during the relentless search for a match may be a waste
-of time, particularly when the match is bound to fail. Consider
-the simple pattern
-
- /^\w+\s+\w+$/; # a word, spaces, a word
-
-Whenever this is applied to a string which doesn't quite meet the
-pattern's expectations such as S<C<"abc ">> or S<C<"abc def ">>,
-the regex engine will backtrack, approximately once for each character
-in the string. But we know that there is no way around taking I<all>
-of the initial word characters to match the first repetition, that I<all>
-spaces must be eaten by the middle part, and the same goes for the second
-word.
-
-With the introduction of the I<possessive quantifiers> in Perl 5.10, we
-have a way of instructing the regex engine not to backtrack, with the
-usual quantifiers with a C<+> appended to them. This makes them greedy as
-well as stingy; once they succeed they won't give anything back to permit
-another solution. They have the following meanings:
-
-=over 4
-
-=item *
-
-C<a{n,m}+> means: match at least C<n> times, not more than C<m> times,
-as many times as possible, and don't give anything up. C<a?+> is short
-for C<a{0,1}+>
-
-=item *
-
-C<a{n,}+> means: match at least C<n> times, but as many times as possible,
-and don't give anything up. C<a*+> is short for C<a{0,}+> and C<a++> is
-short for C<a{1,}+>.
-
-=item *
-
-C<a{n}+> means: match exactly C<n> times. It is just there for
-notational consistency.
-
-=back
-
-These possessive quantifiers represent a special case of a more general
-concept, the I<independent subexpression>, see below.
-
-As an example where a possessive quantifier is suitable we consider
-matching a quoted string, as it appears in several programming languages.
-The backslash is used as an escape character that indicates that the
-next character is to be taken literally, as another character for the
-string. Therefore, after the opening quote, we expect a (possibly
-empty) sequence of alternatives: either some character except an
-unescaped quote or backslash or an escaped character.
-
- /"(?:[^"\\]++|\\.)*+"/;
-
-
-=head2 Building a regexp
-
-At this point, we have all the basic regexp concepts covered, so let's
-give a more involved example of a regular expression. We will build a
-regexp that matches numbers.
-
-The first task in building a regexp is to decide what we want to match
-and what we want to exclude. In our case, we want to match both
-integers and floating point numbers and we want to reject any string
-that isn't a number.
-
-The next task is to break the problem down into smaller problems that
-are easily converted into a regexp.
-
-The simplest case is integers. These consist of a sequence of digits,
-with an optional sign in front. The digits we can represent with
-C<\d+> and the sign can be matched with C<[+-]>. Thus the integer
-regexp is
-
- /[+-]?\d+/; # matches integers
-
-A floating point number potentially has a sign, an integral part, a
-decimal point, a fractional part, and an exponent. One or more of these
-parts is optional, so we need to check out the different
-possibilities. Floating point numbers which are in proper form include
-123., 0.345, .34, -1e6, and 25.4E-72. As with integers, the sign out
-front is completely optional and can be matched by C<[+-]?>. We can
-see that if there is no exponent, floating point numbers must have a
-decimal point, otherwise they are integers. We might be tempted to
-model these with C<\d*\.\d*>, but this would also match just a single
-decimal point, which is not a number. So the three cases of floating
-point number without exponent are
-
- /[+-]?\d+\./; # 1., 321., etc.
- /[+-]?\.\d+/; # .1, .234, etc.
- /[+-]?\d+\.\d+/; # 1.0, 30.56, etc.
-
-These can be combined into a single regexp with a three-way alternation:
-
- /[+-]?(\d+\.\d+|\d+\.|\.\d+)/; # floating point, no exponent
-
-In this alternation, it is important to put C<'\d+\.\d+'> before
-C<'\d+\.'>. If C<'\d+\.'> were first, the regexp would happily match that
-and ignore the fractional part of the number.
-
-Now consider floating point numbers with exponents. The key
-observation here is that I<both> integers and numbers with decimal
-points are allowed in front of an exponent. Then exponents, like the
-overall sign, are independent of whether we are matching numbers with
-or without decimal points, and can be 'decoupled' from the
-mantissa. The overall form of the regexp now becomes clear:
-
- /^(optional sign)(integer | f.p. mantissa)(optional exponent)$/;
-
-The exponent is an C<e> or C<E>, followed by an integer. So the
-exponent regexp is
-
- /[eE][+-]?\d+/; # exponent
-
-Putting all the parts together, we get a regexp that matches numbers:
-
- /^[+-]?(\d+\.\d+|\d+\.|\.\d+|\d+)([eE][+-]?\d+)?$/; # Ta da!
-
-Long regexps like this may impress your friends, but can be hard to
-decipher. In complex situations like this, the C<//x> modifier for a
-match is invaluable. It allows one to put nearly arbitrary whitespace
-and comments into a regexp without affecting their meaning. Using it,
-we can rewrite our 'extended' regexp in the more pleasing form
-
- /^
- [+-]? # first, match an optional sign
- ( # then match integers or f.p. mantissas:
- \d+\.\d+ # mantissa of the form a.b
- |\d+\. # mantissa of the form a.
- |\.\d+ # mantissa of the form .b
- |\d+ # integer of the form a
- )
- ([eE][+-]?\d+)? # finally, optionally match an exponent
- $/x;
-
-If whitespace is mostly irrelevant, how does one include space
-characters in an extended regexp? The answer is to backslash it
-S<C<'\ '>> or put it in a character class S<C<[ ]>>. The same thing
-goes for pound signs: use C<\#> or C<[#]>. For instance, Perl allows
-a space between the sign and the mantissa or integer, and we could add
-this to our regexp as follows:
-
- /^
- [+-]?\ * # first, match an optional sign *and space*
- ( # then match integers or f.p. mantissas:
- \d+\.\d+ # mantissa of the form a.b
- |\d+\. # mantissa of the form a.
- |\.\d+ # mantissa of the form .b
- |\d+ # integer of the form a
- )
- ([eE][+-]?\d+)? # finally, optionally match an exponent
- $/x;
-
-In this form, it is easier to see a way to simplify the
-alternation. Alternatives 1, 2, and 4 all start with C<\d+>, so it
-could be factored out:
-
- /^
- [+-]?\ * # first, match an optional sign
- ( # then match integers or f.p. mantissas:
- \d+ # start out with a ...
- (
- \.\d* # mantissa of the form a.b or a.
- )? # ? takes care of integers of the form a
- |\.\d+ # mantissa of the form .b
- )
- ([eE][+-]?\d+)? # finally, optionally match an exponent
- $/x;
-
-or written in the compact form,
-
- /^[+-]?\ *(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/;
-
-This is our final regexp. To recap, we built a regexp by
-
-=over 4
-
-=item *
-
-specifying the task in detail,
-
-=item *
-
-breaking down the problem into smaller parts,
-
-=item *
-
-translating the small parts into regexps,
-
-=item *
-
-combining the regexps,
-
-=item *
-
-and optimizing the final combined regexp.
-
-=back
-
-These are also the typical steps involved in writing a computer
-program. This makes perfect sense, because regular expressions are
-essentially programs written in a little computer language that specifies
-patterns.
-
-=head2 Using regular expressions in Perl
-
-The last topic of Part 1 briefly covers how regexps are used in Perl
-programs. Where do they fit into Perl syntax?
-
-We have already introduced the matching operator in its default
-C</regexp/> and arbitrary delimiter C<m!regexp!> forms. We have used
-the binding operator C<=~> and its negation C<!~> to test for string
-matches. Associated with the matching operator, we have discussed the
-single line C<//s>, multi-line C<//m>, case-insensitive C<//i> and
-extended C<//x> modifiers. There are a few more things you might
-want to know about matching operators.
-
-=head3 Prohibiting substitution
-
-If you change C<$pattern> after the first substitution happens, Perl
-will ignore it. If you don't want any substitutions at all, use the
-special delimiter C<m''>:
-
- @pattern = ('Seuss');
- while (<>) {
- print if m'@pattern'; # matches literal '@pattern', not 'Seuss'
- }
-
-Similar to strings, C<m''> acts like apostrophes on a regexp; all other
-C<m> delimiters act like quotes. If the regexp evaluates to the empty string,
-the regexp in the I<last successful match> is used instead. So we have
-
- "dog" =~ /d/; # 'd' matches
- "dogbert =~ //; # this matches the 'd' regexp used before
-
-
-=head3 Global matching
-
-The final two modifiers we will discuss here,
-C<//g> and C<//c>, concern multiple matches.
-The modifier C<//g> stands for global matching and allows the
-matching operator to match within a string as many times as possible.
-In scalar context, successive invocations against a string will have
-C<//g> jump from match to match, keeping track of position in the
-string as it goes along. You can get or set the position with the
-C<pos()> function.
-
-The use of C<//g> is shown in the following example. Suppose we have
-a string that consists of words separated by spaces. If we know how
-many words there are in advance, we could extract the words using
-groupings:
-
- $x = "cat dog house"; # 3 words
- $x =~ /^\s*(\w+)\s+(\w+)\s+(\w+)\s*$/; # matches,
- # $1 = 'cat'
- # $2 = 'dog'
- # $3 = 'house'
-
-But what if we had an indeterminate number of words? This is the sort
-of task C<//g> was made for. To extract all words, form the simple
-regexp C<(\w+)> and loop over all matches with C</(\w+)/g>:
-
- while ($x =~ /(\w+)/g) {
- print "Word is $1, ends at position ", pos $x, "\n";
- }
-
-prints
-
- Word is cat, ends at position 3
- Word is dog, ends at position 7
- Word is house, ends at position 13
-
-A failed match or changing the target string resets the position. If
-you don't want the position reset after failure to match, add the
-C<//c>, as in C</regexp/gc>. The current position in the string is
-associated with the string, not the regexp. This means that different
-strings have different positions and their respective positions can be
-set or read independently.
-
-In list context, C<//g> returns a list of matched groupings, or if
-there are no groupings, a list of matches to the whole regexp. So if
-we wanted just the words, we could use
-
- @words = ($x =~ /(\w+)/g); # matches,
- # $words[0] = 'cat'
- # $words[1] = 'dog'
- # $words[2] = 'house'
-
-Closely associated with the C<//g> modifier is the C<\G> anchor. The
-C<\G> anchor matches at the point where the previous C<//g> match left
-off. C<\G> allows us to easily do context-sensitive matching:
-
- $metric = 1; # use metric units
- ...
- $x = <FILE>; # read in measurement
- $x =~ /^([+-]?\d+)\s*/g; # get magnitude
- $weight = $1;
- if ($metric) { # error checking
- print "Units error!" unless $x =~ /\Gkg\./g;
- }
- else {
- print "Units error!" unless $x =~ /\Glbs\./g;
- }
- $x =~ /\G\s+(widget|sprocket)/g; # continue processing
-
-The combination of C<//g> and C<\G> allows us to process the string a
-bit at a time and use arbitrary Perl logic to decide what to do next.
-Currently, the C<\G> anchor is only fully supported when used to anchor
-to the start of the pattern.
-
-C<\G> is also invaluable in processing fixed-length records with
-regexps. Suppose we have a snippet of coding region DNA, encoded as
-base pair letters C<ATCGTTGAAT...> and we want to find all the stop
-codons C<TGA>. In a coding region, codons are 3-letter sequences, so
-we can think of the DNA snippet as a sequence of 3-letter records. The
-naive regexp
-
- # expanded, this is "ATC GTT GAA TGC AAA TGA CAT GAC"
- $dna = "ATCGTTGAATGCAAATGACATGAC";
- $dna =~ /TGA/;
-
-doesn't work; it may match a C<TGA>, but there is no guarantee that
-the match is aligned with codon boundaries, e.g., the substring
-S<C<GTT GAA>> gives a match. A better solution is
-
- while ($dna =~ /(\w\w\w)*?TGA/g) { # note the minimal *?
- print "Got a TGA stop codon at position ", pos $dna, "\n";
- }
-
-which prints
-
- Got a TGA stop codon at position 18
- Got a TGA stop codon at position 23
-
-Position 18 is good, but position 23 is bogus. What happened?
-
-The answer is that our regexp works well until we get past the last
-real match. Then the regexp will fail to match a synchronized C<TGA>
-and start stepping ahead one character position at a time, not what we
-want. The solution is to use C<\G> to anchor the match to the codon
-alignment:
-
- while ($dna =~ /\G(\w\w\w)*?TGA/g) {
- print "Got a TGA stop codon at position ", pos $dna, "\n";
- }
-
-This prints
-
- Got a TGA stop codon at position 18
-
-which is the correct answer. This example illustrates that it is
-important not only to match what is desired, but to reject what is not
-desired.
-
-(There are other regexp modifiers that are available, such as
-C<//o>, but their specialized uses are beyond the
-scope of this introduction. )
-
-=head3 Search and replace
-
-Regular expressions also play a big role in I<search and replace>
-operations in Perl. Search and replace is accomplished with the
-C<s///> operator. The general form is
-C<s/regexp/replacement/modifiers>, with everything we know about
-regexps and modifiers applying in this case as well. The
-C<replacement> is a Perl double-quoted string that replaces in the
-string whatever is matched with the C<regexp>. The operator C<=~> is
-also used here to associate a string with C<s///>. If matching
-against C<$_>, the S<C<$_ =~>> can be dropped. If there is a match,
-C<s///> returns the number of substitutions made; otherwise it returns
-false. Here are a few examples:
-
- $x = "Time to feed the cat!";
- $x =~ s/cat/hacker/; # $x contains "Time to feed the hacker!"
- if ($x =~ s/^(Time.*hacker)!$/$1 now!/) {
- $more_insistent = 1;
- }
- $y = "'quoted words'";
- $y =~ s/^'(.*)'$/$1/; # strip single quotes,
- # $y contains "quoted words"
-
-In the last example, the whole string was matched, but only the part
-inside the single quotes was grouped. With the C<s///> operator, the
-matched variables C<$1>, C<$2>, etc. are immediately available for use
-in the replacement expression, so we use C<$1> to replace the quoted
-string with just what was quoted. With the global modifier, C<s///g>
-will search and replace all occurrences of the regexp in the string:
-
- $x = "I batted 4 for 4";
- $x =~ s/4/four/; # doesn't do it all:
- # $x contains "I batted four for 4"
- $x = "I batted 4 for 4";
- $x =~ s/4/four/g; # does it all:
- # $x contains "I batted four for four"
-
-If you prefer 'regex' over 'regexp' in this tutorial, you could use
-the following program to replace it:
-
- % cat > simple_replace
- #!/usr/bin/perl
- $regexp = shift;
- $replacement = shift;
- while (<>) {
- s/$regexp/$replacement/g;
- print;
- }
- ^D
-
- % simple_replace regexp regex perlretut.pod
-
-In C<simple_replace> we used the C<s///g> modifier to replace all
-occurrences of the regexp on each line. (Even though the regular
-expression appears in a loop, Perl is smart enough to compile it
-only once.) As with C<simple_grep>, both the
-C<print> and the C<s/$regexp/$replacement/g> use C<$_> implicitly.
-
-If you don't want C<s///> to change your original variable you can use
-the non-destructive substitute modifier, C<s///r>. This changes the
-behavior so that C<s///r> returns the final substituted string
-(instead of the number of substitutions):
-
- $x = "I like dogs.";
- $y = $x =~ s/dogs/cats/r;
- print "$x $y\n";
-
-That example will print "I like dogs. I like cats". Notice the original
-C<$x> variable has not been affected. The overall
-result of the substitution is instead stored in C<$y>. If the
-substitution doesn't affect anything then the original string is
-returned:
-
- $x = "I like dogs.";
- $y = $x =~ s/elephants/cougars/r;
- print "$x $y\n"; # prints "I like dogs. I like dogs."
-
-One other interesting thing that the C<s///r> flag allows is chaining
-substitutions:
-
- $x = "Cats are great.";
- print $x =~ s/Cats/Dogs/r =~ s/Dogs/Frogs/r =~ s/Frogs/Hedgehogs/r, "\n";
- # prints "Hedgehogs are great."
-
-A modifier available specifically to search and replace is the
-C<s///e> evaluation modifier. C<s///e> treats the
-replacement text as Perl code, rather than a double-quoted
-string. The value that the code returns is substituted for the
-matched substring. C<s///e> is useful if you need to do a bit of
-computation in the process of replacing text. This example counts
-character frequencies in a line:
-
- $x = "Bill the cat";
- $x =~ s/(.)/$chars{$1}++;$1/eg; # final $1 replaces char with itself
- print "frequency of '$_' is $chars{$_}\n"
- foreach (sort {$chars{$b} <=> $chars{$a}} keys %chars);
-
-This prints
-
- frequency of ' ' is 2
- frequency of 't' is 2
- frequency of 'l' is 2
- frequency of 'B' is 1
- frequency of 'c' is 1
- frequency of 'e' is 1
- frequency of 'h' is 1
- frequency of 'i' is 1
- frequency of 'a' is 1
-
-As with the match C<m//> operator, C<s///> can use other delimiters,
-such as C<s!!!> and C<s{}{}>, and even C<s{}//>. If single quotes are
-used C<s'''>, then the regexp and replacement are
-treated as single-quoted strings and there are no
-variable substitutions. C<s///> in list context
-returns the same thing as in scalar context, i.e., the number of
-matches.
-
-=head3 The split function
-
-The C<split()> function is another place where a regexp is used.
-C<split /regexp/, string, limit> separates the C<string> operand into
-a list of substrings and returns that list. The regexp must be designed
-to match whatever constitutes the separators for the desired substrings.
-The C<limit>, if present, constrains splitting into no more than C<limit>
-number of strings. For example, to split a string into words, use
-
- $x = "Calvin and Hobbes";
- @words = split /\s+/, $x; # $word[0] = 'Calvin'
- # $word[1] = 'and'
- # $word[2] = 'Hobbes'
-
-If the empty regexp C<//> is used, the regexp always matches and
-the string is split into individual characters. If the regexp has
-groupings, then the resulting list contains the matched substrings from the
-groupings as well. For instance,
-
- $x = "/usr/bin/perl";
- @dirs = split m!/!, $x; # $dirs[0] = ''
- # $dirs[1] = 'usr'
- # $dirs[2] = 'bin'
- # $dirs[3] = 'perl'
- @parts = split m!(/)!, $x; # $parts[0] = ''
- # $parts[1] = '/'
- # $parts[2] = 'usr'
- # $parts[3] = '/'
- # $parts[4] = 'bin'
- # $parts[5] = '/'
- # $parts[6] = 'perl'
-
-Since the first character of $x matched the regexp, C<split> prepended
-an empty initial element to the list.
-
-If you have read this far, congratulations! You now have all the basic
-tools needed to use regular expressions to solve a wide range of text
-processing problems. If this is your first time through the tutorial,
-why not stop here and play around with regexps a while.... S<Part 2>
-concerns the more esoteric aspects of regular expressions and those
-concepts certainly aren't needed right at the start.
-
-=head1 Part 2: Power tools
-
-OK, you know the basics of regexps and you want to know more. If
-matching regular expressions is analogous to a walk in the woods, then
-the tools discussed in Part 1 are analogous to topo maps and a
-compass, basic tools we use all the time. Most of the tools in part 2
-are analogous to flare guns and satellite phones. They aren't used
-too often on a hike, but when we are stuck, they can be invaluable.
-
-What follows are the more advanced, less used, or sometimes esoteric
-capabilities of Perl regexps. In Part 2, we will assume you are
-comfortable with the basics and concentrate on the advanced features.
-
-=head2 More on characters, strings, and character classes
-
-There are a number of escape sequences and character classes that we
-haven't covered yet.
-
-There are several escape sequences that convert characters or strings
-between upper and lower case, and they are also available within
-patterns. C<\l> and C<\u> convert the next character to lower or
-upper case, respectively:
-
- $x = "perl";
- $string =~ /\u$x/; # matches 'Perl' in $string
- $x = "M(rs?|s)\\."; # note the double backslash
- $string =~ /\l$x/; # matches 'mr.', 'mrs.', and 'ms.',
-
-A C<\L> or C<\U> indicates a lasting conversion of case, until
-terminated by C<\E> or thrown over by another C<\U> or C<\L>:
-
- $x = "This word is in lower case:\L SHOUT\E";
- $x =~ /shout/; # matches
- $x = "I STILL KEYPUNCH CARDS FOR MY 360"
- $x =~ /\Ukeypunch/; # matches punch card string
-
-If there is no C<\E>, case is converted until the end of the
-string. The regexps C<\L\u$word> or C<\u\L$word> convert the first
-character of C<$word> to uppercase and the rest of the characters to
-lowercase.
-
-Control characters can be escaped with C<\c>, so that a control-Z
-character would be matched with C<\cZ>. The escape sequence
-C<\Q>...C<\E> quotes, or protects most non-alphabetic characters. For
-instance,
-
- $x = "\QThat !^*&%~& cat!";
- $x =~ /\Q!^*&%~&\E/; # check for rough language
-
-It does not protect C<$> or C<@>, so that variables can still be
-substituted.
-
-C<\Q>, C<\L>, C<\l>, C<\U>, C<\u> and C<\E> are actually part of
-double-quotish syntax, and not part of regexp syntax proper. They will
-work if they appear in a regular expression embedded directly in a
-program, but not when contained in a string that is interpolated in a
-pattern.
-
-With the advent of 5.6.0, Perl regexps can handle more than just the
-standard ASCII character set. Perl now supports I<Unicode>, a standard
-for representing the alphabets from virtually all of the world's written
-languages, and a host of symbols. Perl's text strings are Unicode strings, so
-they can contain characters with a value (codepoint or character number) higher
-than 255.
-
-What does this mean for regexps? Well, regexp users don't need to know
-much about Perl's internal representation of strings. But they do need
-to know 1) how to represent Unicode characters in a regexp and 2) that
-a matching operation will treat the string to be searched as a sequence
-of characters, not bytes. The answer to 1) is that Unicode characters
-greater than C<chr(255)> are represented using the C<\x{hex}> notation, because
-\x hex (without curly braces) doesn't go further than 255. (Starting in Perl
-5.14, if you're an octal fan, you can also use C<\o{oct}>.)
-
- /\x{263a}/; # match a Unicode smiley face :)
-
-B<NOTE>: In Perl 5.6.0 it used to be that one needed to say C<use
-utf8> to use any Unicode features. This is no more the case: for
-almost all Unicode processing, the explicit C<utf8> pragma is not
-needed. (The only case where it matters is if your Perl script is in
-Unicode and encoded in UTF-8, then an explicit C<use utf8> is needed.)
-
-Figuring out the hexadecimal sequence of a Unicode character you want
-or deciphering someone else's hexadecimal Unicode regexp is about as
-much fun as programming in machine code. So another way to specify
-Unicode characters is to use the I<named character> escape
-sequence C<\N{I<name>}>. I<name> is a name for the Unicode character, as
-specified in the Unicode standard. For instance, if we wanted to
-represent or match the astrological sign for the planet Mercury, we
-could use
-
- $x = "abc\N{MERCURY}def";
- $x =~ /\N{MERCURY}/; # matches
-
-One can also use "short" names:
-
- print "\N{GREEK SMALL LETTER SIGMA} is called sigma.\n";
- print "\N{greek:Sigma} is an upper-case sigma.\n";
-
-You can also restrict names to a certain alphabet by specifying the
-L<charnames> pragma:
-
- use charnames qw(greek);
- print "\N{sigma} is Greek sigma\n";
-
-An index of character names is available on-line from the Unicode
-Consortium, L<http://www.unicode.org/charts/charindex.html>; explanatory
-material with links to other resources at
-L<http://www.unicode.org/standard/where>.
-
-The answer to requirement 2) is, as of 5.6.0, that a regexp (mostly)
-uses Unicode characters. (The "mostly" is for messy backward
-compatibility reasons, but starting in Perl 5.14, any regex compiled in
-the scope of a C<use feature 'unicode_strings'> (which is automatically
-turned on within the scope of a C<use 5.012> or higher) will turn that
-"mostly" into "always". If you want to handle Unicode properly, you
-should ensure that C<'unicode_strings'> is turned on.)
-Internally, this is encoded to bytes using either UTF-8 or a native 8
-bit encoding, depending on the history of the string, but conceptually
-it is a sequence of characters, not bytes. See L<perlunitut> for a
-tutorial about that.
-
-Let us now discuss Unicode character classes. Just as with Unicode
-characters, there are named Unicode character classes represented by the
-C<\p{name}> escape sequence. Closely associated is the C<\P{name}>
-character class, which is the negation of the C<\p{name}> class. For
-example, to match lower and uppercase characters,
-
- $x = "BOB";
- $x =~ /^\p{IsUpper}/; # matches, uppercase char class
- $x =~ /^\P{IsUpper}/; # doesn't match, char class sans uppercase
- $x =~ /^\p{IsLower}/; # doesn't match, lowercase char class
- $x =~ /^\P{IsLower}/; # matches, char class sans lowercase
-
-(The "Is" is optional.)
-
-Here is the association between some Perl named classes and the
-traditional Unicode classes:
-
- Perl class name Unicode class name or regular expression
-
- IsAlpha /^[LM]/
- IsAlnum /^[LMN]/
- IsASCII $code <= 127
- IsCntrl /^C/
- IsBlank $code =~ /^(0020|0009)$/ || /^Z[^lp]/
- IsDigit Nd
- IsGraph /^([LMNPS]|Co)/
- IsLower Ll
- IsPrint /^([LMNPS]|Co|Zs)/
- IsPunct /^P/
- IsSpace /^Z/ || ($code =~ /^(0009|000A|000B|000C|000D)$/
- IsSpacePerl /^Z/ || ($code =~ /^(0009|000A|000C|000D|0085|2028|2029)$/
- IsUpper /^L[ut]/
- IsWord /^[LMN]/ || $code eq "005F"
- IsXDigit $code =~ /^00(3[0-9]|[46][1-6])$/
-
-You can also use the official Unicode class names with C<\p> and
-C<\P>, like C<\p{L}> for Unicode 'letters', C<\p{Lu}> for uppercase
-letters, or C<\P{Nd}> for non-digits. If a C<name> is just one
-letter, the braces can be dropped. For instance, C<\pM> is the
-character class of Unicode 'marks', for example accent marks.
-For the full list see L<perlunicode>.
-
-Unicode has also been separated into various sets of characters
-which you can test with C<\p{...}> (in) and C<\P{...}> (not in).
-To test whether a character is (or is not) an element of a script
-you would use the script name, for example C<\p{Latin}>, C<\p{Greek}>,
-or C<\P{Katakana}>.
-
-What we have described so far is the single form of the C<\p{...}> character
-classes. There is also a compound form which you may run into. These
-look like C<\p{name=value}> or C<\p{name:value}> (the equals sign and colon
-can be used interchangeably). These are more general than the single form,
-and in fact most of the single forms are just Perl-defined shortcuts for common
-compound forms. For example, the script examples in the previous paragraph
-could be written equivalently as C<\p{Script=Latin}>, C<\p{Script:Greek}>, and
-C<\P{script=katakana}> (case is irrelevant between the C<{}> braces). You may
-never have to use the compound forms, but sometimes it is necessary, and their
-use can make your code easier to understand.
-
-C<\X> is an abbreviation for a character class that comprises
-a Unicode I<extended grapheme cluster>. This represents a "logical character":
-what appears to be a single character, but may be represented internally by more
-than one. As an example, using the Unicode full names, e.g., S<C<A + COMBINING
-RING>> is a grapheme cluster with base character C<A> and combining character
-S<C<COMBINING RING>>, which translates in Danish to A with the circle atop it,
-as in the word Angstrom.
-
-For the full and latest information about Unicode see the latest
-Unicode standard, or the Unicode Consortium's website L<http://www.unicode.org>
-
-As if all those classes weren't enough, Perl also defines POSIX-style
-character classes. These have the form C<[:name:]>, with C<name> the
-name of the POSIX class. The POSIX classes are C<alpha>, C<alnum>,
-C<ascii>, C<cntrl>, C<digit>, C<graph>, C<lower>, C<print>, C<punct>,
-C<space>, C<upper>, and C<xdigit>, and two extensions, C<word> (a Perl
-extension to match C<\w>), and C<blank> (a GNU extension). The C<//a>
-modifier restricts these to matching just in the ASCII range; otherwise
-they can match the same as their corresponding Perl Unicode classes:
-C<[:upper:]> is the same as C<\p{IsUpper}>, etc. (There are some
-exceptions and gotchas with this; see L<perlrecharclass> for a full
-discussion.) The C<[:digit:]>, C<[:word:]>, and
-C<[:space:]> correspond to the familiar C<\d>, C<\w>, and C<\s>
-character classes. To negate a POSIX class, put a C<^> in front of
-the name, so that, e.g., C<[:^digit:]> corresponds to C<\D> and, under
-Unicode, C<\P{IsDigit}>. The Unicode and POSIX character classes can
-be used just like C<\d>, with the exception that POSIX character
-classes can only be used inside of a character class:
-
- /\s+[abc[:digit:]xyz]\s*/; # match a,b,c,x,y,z, or a digit
- /^=item\s[[:digit:]]/; # match '=item',
- # followed by a space and a digit
- /\s+[abc\p{IsDigit}xyz]\s+/; # match a,b,c,x,y,z, or a digit
- /^=item\s\p{IsDigit}/; # match '=item',
- # followed by a space and a digit
-
-Whew! That is all the rest of the characters and character classes.
-
-=head2 Compiling and saving regular expressions
-
-In Part 1 we mentioned that Perl compiles a regexp into a compact
-sequence of opcodes. Thus, a compiled regexp is a data structure
-that can be stored once and used again and again. The regexp quote
-C<qr//> does exactly that: C<qr/string/> compiles the C<string> as a
-regexp and transforms the result into a form that can be assigned to a
-variable:
-
- $reg = qr/foo+bar?/; # reg contains a compiled regexp
-
-Then C<$reg> can be used as a regexp:
-
- $x = "fooooba";
- $x =~ $reg; # matches, just like /foo+bar?/
- $x =~ /$reg/; # same thing, alternate form
-
-C<$reg> can also be interpolated into a larger regexp:
-
- $x =~ /(abc)?$reg/; # still matches
-
-As with the matching operator, the regexp quote can use different
-delimiters, e.g., C<qr!!>, C<qr{}> or C<qr~~>. Apostrophes
-as delimiters (C<qr''>) inhibit any interpolation.
-
-Pre-compiled regexps are useful for creating dynamic matches that
-don't need to be recompiled each time they are encountered. Using
-pre-compiled regexps, we write a C<grep_step> program which greps
-for a sequence of patterns, advancing to the next pattern as soon
-as one has been satisfied.
-
- % cat > grep_step
- #!/usr/bin/perl
- # grep_step - match <number> regexps, one after the other
- # usage: multi_grep <number> regexp1 regexp2 ... file1 file2 ...
-
- $number = shift;
- $regexp[$_] = shift foreach (0..$number-1);
- @compiled = map qr/$_/, @regexp;
- while ($line = <>) {
- if ($line =~ /$compiled[0]/) {
- print $line;
- shift @compiled;
- last unless @compiled;
- }
- }
- ^D
-
- % grep_step 3 shift print last grep_step
- $number = shift;
- print $line;
- last unless @compiled;
-
-Storing pre-compiled regexps in an array C<@compiled> allows us to
-simply loop through the regexps without any recompilation, thus gaining
-flexibility without sacrificing speed.
-
-
-=head2 Composing regular expressions at runtime
-
-Backtracking is more efficient than repeated tries with different regular
-expressions. If there are several regular expressions and a match with
-any of them is acceptable, then it is possible to combine them into a set
-of alternatives. If the individual expressions are input data, this
-can be done by programming a join operation. We'll exploit this idea in
-an improved version of the C<simple_grep> program: a program that matches
-multiple patterns:
-
- % cat > multi_grep
- #!/usr/bin/perl
- # multi_grep - match any of <number> regexps
- # usage: multi_grep <number> regexp1 regexp2 ... file1 file2 ...
-
- $number = shift;
- $regexp[$_] = shift foreach (0..$number-1);
- $pattern = join '|', @regexp;
-
- while ($line = <>) {
- print $line if $line =~ /$pattern/;
- }
- ^D
-
- % multi_grep 2 shift for multi_grep
- $number = shift;
- $regexp[$_] = shift foreach (0..$number-1);
-
-Sometimes it is advantageous to construct a pattern from the I<input>
-that is to be analyzed and use the permissible values on the left
-hand side of the matching operations. As an example for this somewhat
-paradoxical situation, let's assume that our input contains a command
-verb which should match one out of a set of available command verbs,
-with the additional twist that commands may be abbreviated as long as
-the given string is unique. The program below demonstrates the basic
-algorithm.
-
- % cat > keymatch
- #!/usr/bin/perl
- $kwds = 'copy compare list print';
- while( $command = <> ){
- $command =~ s/^\s+|\s+$//g; # trim leading and trailing spaces
- if( ( @matches = $kwds =~ /\b$command\w*/g ) == 1 ){
- print "command: '@matches'\n";
- } elsif( @matches == 0 ){
- print "no such command: '$command'\n";
- } else {
- print "not unique: '$command' (could be one of: @matches)\n";
- }
- }
- ^D
-
- % keymatch
- li
- command: 'list'
- co
- not unique: 'co' (could be one of: copy compare)
- printer
- no such command: 'printer'
-
-Rather than trying to match the input against the keywords, we match the
-combined set of keywords against the input. The pattern matching
-operation S<C<$kwds =~ /\b($command\w*)/g>> does several things at the
-same time. It makes sure that the given command begins where a keyword
-begins (C<\b>). It tolerates abbreviations due to the added C<\w*>. It
-tells us the number of matches (C<scalar @matches>) and all the keywords
-that were actually matched. You could hardly ask for more.
-
-=head2 Embedding comments and modifiers in a regular expression
-
-Starting with this section, we will be discussing Perl's set of
-I<extended patterns>. These are extensions to the traditional regular
-expression syntax that provide powerful new tools for pattern
-matching. We have already seen extensions in the form of the minimal
-matching constructs C<??>, C<*?>, C<+?>, C<{n,m}?>, and C<{n,}?>. Most
-of the extensions below have the form C<(?char...)>, where the
-C<char> is a character that determines the type of extension.
-
-The first extension is an embedded comment C<(?#text)>. This embeds a
-comment into the regular expression without affecting its meaning. The
-comment should not have any closing parentheses in the text. An
-example is
-
- /(?# Match an integer:)[+-]?\d+/;
-
-This style of commenting has been largely superseded by the raw,
-freeform commenting that is allowed with the C<//x> modifier.
-
-Most modifiers, such as C<//i>, C<//m>, C<//s> and C<//x> (or any
-combination thereof) can also be embedded in
-a regexp using C<(?i)>, C<(?m)>, C<(?s)>, and C<(?x)>. For instance,
-
- /(?i)yes/; # match 'yes' case insensitively
- /yes/i; # same thing
- /(?x)( # freeform version of an integer regexp
- [+-]? # match an optional sign
- \d+ # match a sequence of digits
- )
- /x;
-
-Embedded modifiers can have two important advantages over the usual
-modifiers. Embedded modifiers allow a custom set of modifiers to
-I<each> regexp pattern. This is great for matching an array of regexps
-that must have different modifiers:
-
- $pattern[0] = '(?i)doctor';
- $pattern[1] = 'Johnson';
- ...
- while (<>) {
- foreach $patt (@pattern) {
- print if /$patt/;
- }
- }
-
-The second advantage is that embedded modifiers (except C<//p>, which
-modifies the entire regexp) only affect the regexp
-inside the group the embedded modifier is contained in. So grouping
-can be used to localize the modifier's effects:
-
- /Answer: ((?i)yes)/; # matches 'Answer: yes', 'Answer: YES', etc.
-
-Embedded modifiers can also turn off any modifiers already present
-by using, e.g., C<(?-i)>. Modifiers can also be combined into
-a single expression, e.g., C<(?s-i)> turns on single line mode and
-turns off case insensitivity.
-
-Embedded modifiers may also be added to a non-capturing grouping.
-C<(?i-m:regexp)> is a non-capturing grouping that matches C<regexp>
-case insensitively and turns off multi-line mode.
-
-
-=head2 Looking ahead and looking behind
-
-This section concerns the lookahead and lookbehind assertions. First,
-a little background.
-
-In Perl regular expressions, most regexp elements 'eat up' a certain
-amount of string when they match. For instance, the regexp element
-C<[abc}]> eats up one character of the string when it matches, in the
-sense that Perl moves to the next character position in the string
-after the match. There are some elements, however, that don't eat up
-characters (advance the character position) if they match. The examples
-we have seen so far are the anchors. The anchor C<^> matches the
-beginning of the line, but doesn't eat any characters. Similarly, the
-word boundary anchor C<\b> matches wherever a character matching C<\w>
-is next to a character that doesn't, but it doesn't eat up any
-characters itself. Anchors are examples of I<zero-width assertions>:
-zero-width, because they consume
-no characters, and assertions, because they test some property of the
-string. In the context of our walk in the woods analogy to regexp
-matching, most regexp elements move us along a trail, but anchors have
-us stop a moment and check our surroundings. If the local environment
-checks out, we can proceed forward. But if the local environment
-doesn't satisfy us, we must backtrack.
-
-Checking the environment entails either looking ahead on the trail,
-looking behind, or both. C<^> looks behind, to see that there are no
-characters before. C<$> looks ahead, to see that there are no
-characters after. C<\b> looks both ahead and behind, to see if the
-characters on either side differ in their "word-ness".
-
-The lookahead and lookbehind assertions are generalizations of the
-anchor concept. Lookahead and lookbehind are zero-width assertions
-that let us specify which characters we want to test for. The
-lookahead assertion is denoted by C<(?=regexp)> and the lookbehind
-assertion is denoted by C<< (?<=fixed-regexp) >>. Some examples are
-
- $x = "I catch the housecat 'Tom-cat' with catnip";
- $x =~ /cat(?=\s)/; # matches 'cat' in 'housecat'
- @catwords = ($x =~ /(?<=\s)cat\w+/g); # matches,
- # $catwords[0] = 'catch'
- # $catwords[1] = 'catnip'
- $x =~ /\bcat\b/; # matches 'cat' in 'Tom-cat'
- $x =~ /(?<=\s)cat(?=\s)/; # doesn't match; no isolated 'cat' in
- # middle of $x
-
-Note that the parentheses in C<(?=regexp)> and C<< (?<=regexp) >> are
-non-capturing, since these are zero-width assertions. Thus in the
-second regexp, the substrings captured are those of the whole regexp
-itself. Lookahead C<(?=regexp)> can match arbitrary regexps, but
-lookbehind C<< (?<=fixed-regexp) >> only works for regexps of fixed
-width, i.e., a fixed number of characters long. Thus
-C<< (?<=(ab|bc)) >> is fine, but C<< (?<=(ab)*) >> is not. The
-negated versions of the lookahead and lookbehind assertions are
-denoted by C<(?!regexp)> and C<< (?<!fixed-regexp) >> respectively.
-They evaluate true if the regexps do I<not> match:
-
- $x = "foobar";
- $x =~ /foo(?!bar)/; # doesn't match, 'bar' follows 'foo'
- $x =~ /foo(?!baz)/; # matches, 'baz' doesn't follow 'foo'
- $x =~ /(?<!\s)foo/; # matches, there is no \s before 'foo'
-
-The C<\C> is unsupported in lookbehind, because the already
-treacherous definition of C<\C> would become even more so
-when going backwards.
-
-Here is an example where a string containing blank-separated words,
-numbers and single dashes is to be split into its components.
-Using C</\s+/> alone won't work, because spaces are not required between
-dashes, or a word or a dash. Additional places for a split are established
-by looking ahead and behind:
-
- $str = "one two - --6-8";
- @toks = split / \s+ # a run of spaces
- | (?<=\S) (?=-) # any non-space followed by '-'
- | (?<=-) (?=\S) # a '-' followed by any non-space
- /x, $str; # @toks = qw(one two - - - 6 - 8)
-
-
-=head2 Using independent subexpressions to prevent backtracking
-
-I<Independent subexpressions> are regular expressions, in the
-context of a larger regular expression, that function independently of
-the larger regular expression. That is, they consume as much or as
-little of the string as they wish without regard for the ability of
-the larger regexp to match. Independent subexpressions are represented
-by C<< (?>regexp) >>. We can illustrate their behavior by first
-considering an ordinary regexp:
-
- $x = "ab";
- $x =~ /a*ab/; # matches
-
-This obviously matches, but in the process of matching, the
-subexpression C<a*> first grabbed the C<a>. Doing so, however,
-wouldn't allow the whole regexp to match, so after backtracking, C<a*>
-eventually gave back the C<a> and matched the empty string. Here, what
-C<a*> matched was I<dependent> on what the rest of the regexp matched.
-
-Contrast that with an independent subexpression:
-
- $x =~ /(?>a*)ab/; # doesn't match!
-
-The independent subexpression C<< (?>a*) >> doesn't care about the rest
-of the regexp, so it sees an C<a> and grabs it. Then the rest of the
-regexp C<ab> cannot match. Because C<< (?>a*) >> is independent, there
-is no backtracking and the independent subexpression does not give
-up its C<a>. Thus the match of the regexp as a whole fails. A similar
-behavior occurs with completely independent regexps:
-
- $x = "ab";
- $x =~ /a*/g; # matches, eats an 'a'
- $x =~ /\Gab/g; # doesn't match, no 'a' available
-
-Here C<//g> and C<\G> create a 'tag team' handoff of the string from
-one regexp to the other. Regexps with an independent subexpression are
-much like this, with a handoff of the string to the independent
-subexpression, and a handoff of the string back to the enclosing
-regexp.
-
-The ability of an independent subexpression to prevent backtracking
-can be quite useful. Suppose we want to match a non-empty string
-enclosed in parentheses up to two levels deep. Then the following
-regexp matches:
-
- $x = "abc(de(fg)h"; # unbalanced parentheses
- $x =~ /\( ( [^()]+ | \([^()]*\) )+ \)/x;
-
-The regexp matches an open parenthesis, one or more copies of an
-alternation, and a close parenthesis. The alternation is two-way, with
-the first alternative C<[^()]+> matching a substring with no
-parentheses and the second alternative C<\([^()]*\)> matching a
-substring delimited by parentheses. The problem with this regexp is
-that it is pathological: it has nested indeterminate quantifiers
-of the form C<(a+|b)+>. We discussed in Part 1 how nested quantifiers
-like this could take an exponentially long time to execute if there
-was no match possible. To prevent the exponential blowup, we need to
-prevent useless backtracking at some point. This can be done by
-enclosing the inner quantifier as an independent subexpression:
-
- $x =~ /\( ( (?>[^()]+) | \([^()]*\) )+ \)/x;
-
-Here, C<< (?>[^()]+) >> breaks the degeneracy of string partitioning
-by gobbling up as much of the string as possible and keeping it. Then
-match failures fail much more quickly.
-
-
-=head2 Conditional expressions
-
-A I<conditional expression> is a form of if-then-else statement
-that allows one to choose which patterns are to be matched, based on
-some condition. There are two types of conditional expression:
-C<(?(condition)yes-regexp)> and
-C<(?(condition)yes-regexp|no-regexp)>. C<(?(condition)yes-regexp)> is
-like an S<C<'if () {}'>> statement in Perl. If the C<condition> is true,
-the C<yes-regexp> will be matched. If the C<condition> is false, the
-C<yes-regexp> will be skipped and Perl will move onto the next regexp
-element. The second form is like an S<C<'if () {} else {}'>> statement
-in Perl. If the C<condition> is true, the C<yes-regexp> will be
-matched, otherwise the C<no-regexp> will be matched.
-
-The C<condition> can have several forms. The first form is simply an
-integer in parentheses C<(integer)>. It is true if the corresponding
-backreference C<\integer> matched earlier in the regexp. The same
-thing can be done with a name associated with a capture group, written
-as C<< (<name>) >> or C<< ('name') >>. The second form is a bare
-zero-width assertion C<(?...)>, either a lookahead, a lookbehind, or a
-code assertion (discussed in the next section). The third set of forms
-provides tests that return true if the expression is executed within
-a recursion (C<(R)>) or is being called from some capturing group,
-referenced either by number (C<(R1)>, C<(R2)>,...) or by name
-(C<(R&name)>).
-
-The integer or name form of the C<condition> allows us to choose,
-with more flexibility, what to match based on what matched earlier in the
-regexp. This searches for words of the form C<"$x$x"> or C<"$x$y$y$x">:
-
- % simple_grep '^(\w+)(\w+)?(?(2)\g2\g1|\g1)$' /usr/dict/words
- beriberi
- coco
- couscous
- deed
- ...
- toot
- toto
- tutu
-
-The lookbehind C<condition> allows, along with backreferences,
-an earlier part of the match to influence a later part of the
-match. For instance,
-
- /[ATGC]+(?(?<=AA)G|C)$/;
-
-matches a DNA sequence such that it either ends in C<AAG>, or some
-other base pair combination and C<C>. Note that the form is
-C<< (?(?<=AA)G|C) >> and not C<< (?((?<=AA))G|C) >>; for the
-lookahead, lookbehind or code assertions, the parentheses around the
-conditional are not needed.
-
-
-=head2 Defining named patterns
-
-Some regular expressions use identical subpatterns in several places.
-Starting with Perl 5.10, it is possible to define named subpatterns in
-a section of the pattern so that they can be called up by name
-anywhere in the pattern. This syntactic pattern for this definition
-group is C<< (?(DEFINE)(?<name>pattern)...) >>. An insertion
-of a named pattern is written as C<(?&name)>.
-
-The example below illustrates this feature using the pattern for
-floating point numbers that was presented earlier on. The three
-subpatterns that are used more than once are the optional sign, the
-digit sequence for an integer and the decimal fraction. The DEFINE
-group at the end of the pattern contains their definition. Notice
-that the decimal fraction pattern is the first place where we can
-reuse the integer pattern.
-
- /^ (?&osg)\ * ( (?&int)(?&dec)? | (?&dec) )
- (?: [eE](?&osg)(?&int) )?
- $
- (?(DEFINE)
- (?<osg>[-+]?) # optional sign
- (?<int>\d++) # integer
- (?<dec>\.(?&int)) # decimal fraction
- )/x
-
-
-=head2 Recursive patterns
-
-This feature (introduced in Perl 5.10) significantly extends the
-power of Perl's pattern matching. By referring to some other
-capture group anywhere in the pattern with the construct
-C<(?group-ref)>, the I<pattern> within the referenced group is used
-as an independent subpattern in place of the group reference itself.
-Because the group reference may be contained I<within> the group it
-refers to, it is now possible to apply pattern matching to tasks that
-hitherto required a recursive parser.
-
-To illustrate this feature, we'll design a pattern that matches if
-a string contains a palindrome. (This is a word or a sentence that,
-while ignoring spaces, interpunctuation and case, reads the same backwards
-as forwards. We begin by observing that the empty string or a string
-containing just one word character is a palindrome. Otherwise it must
-have a word character up front and the same at its end, with another
-palindrome in between.
-
- /(?: (\w) (?...Here be a palindrome...) \g{-1} | \w? )/x
-
-Adding C<\W*> at either end to eliminate what is to be ignored, we already
-have the full pattern:
-
- my $pp = qr/^(\W* (?: (\w) (?1) \g{-1} | \w? ) \W*)$/ix;
- for $s ( "saippuakauppias", "A man, a plan, a canal: Panama!" ){
- print "'$s' is a palindrome\n" if $s =~ /$pp/;
- }
-
-In C<(?...)> both absolute and relative backreferences may be used.
-The entire pattern can be reinserted with C<(?R)> or C<(?0)>.
-If you prefer to name your groups, you can use C<(?&name)> to
-recurse into that group.
-
-
-=head2 A bit of magic: executing Perl code in a regular expression
-
-Normally, regexps are a part of Perl expressions.
-I<Code evaluation> expressions turn that around by allowing
-arbitrary Perl code to be a part of a regexp. A code evaluation
-expression is denoted C<(?{code})>, with I<code> a string of Perl
-statements.
-
-Be warned that this feature is considered experimental, and may be
-changed without notice.
-
-Code expressions are zero-width assertions, and the value they return
-depends on their environment. There are two possibilities: either the
-code expression is used as a conditional in a conditional expression
-C<(?(condition)...)>, or it is not. If the code expression is a
-conditional, the code is evaluated and the result (i.e., the result of
-the last statement) is used to determine truth or falsehood. If the
-code expression is not used as a conditional, the assertion always
-evaluates true and the result is put into the special variable
-C<$^R>. The variable C<$^R> can then be used in code expressions later
-in the regexp. Here are some silly examples:
-
- $x = "abcdef";
- $x =~ /abc(?{print "Hi Mom!";})def/; # matches,
- # prints 'Hi Mom!'
- $x =~ /aaa(?{print "Hi Mom!";})def/; # doesn't match,
- # no 'Hi Mom!'
-
-Pay careful attention to the next example:
-
- $x =~ /abc(?{print "Hi Mom!";})ddd/; # doesn't match,
- # no 'Hi Mom!'
- # but why not?
-
-At first glance, you'd think that it shouldn't print, because obviously
-the C<ddd> isn't going to match the target string. But look at this
-example:
-
- $x =~ /abc(?{print "Hi Mom!";})[dD]dd/; # doesn't match,
- # but _does_ print
-
-Hmm. What happened here? If you've been following along, you know that
-the above pattern should be effectively (almost) the same as the last one;
-enclosing the C<d> in a character class isn't going to change what it
-matches. So why does the first not print while the second one does?
-
-The answer lies in the optimizations the regex engine makes. In the first
-case, all the engine sees are plain old characters (aside from the
-C<?{}> construct). It's smart enough to realize that the string 'ddd'
-doesn't occur in our target string before actually running the pattern
-through. But in the second case, we've tricked it into thinking that our
-pattern is more complicated. It takes a look, sees our
-character class, and decides that it will have to actually run the
-pattern to determine whether or not it matches, and in the process of
-running it hits the print statement before it discovers that we don't
-have a match.
-
-To take a closer look at how the engine does optimizations, see the
-section L<"Pragmas and debugging"> below.
-
-More fun with C<?{}>:
-
- $x =~ /(?{print "Hi Mom!";})/; # matches,
- # prints 'Hi Mom!'
- $x =~ /(?{$c = 1;})(?{print "$c";})/; # matches,
- # prints '1'
- $x =~ /(?{$c = 1;})(?{print "$^R";})/; # matches,
- # prints '1'
-
-The bit of magic mentioned in the section title occurs when the regexp
-backtracks in the process of searching for a match. If the regexp
-backtracks over a code expression and if the variables used within are
-localized using C<local>, the changes in the variables produced by the
-code expression are undone! Thus, if we wanted to count how many times
-a character got matched inside a group, we could use, e.g.,
-
- $x = "aaaa";
- $count = 0; # initialize 'a' count
- $c = "bob"; # test if $c gets clobbered
- $x =~ /(?{local $c = 0;}) # initialize count
- ( a # match 'a'
- (?{local $c = $c + 1;}) # increment count
- )* # do this any number of times,
- aa # but match 'aa' at the end
- (?{$count = $c;}) # copy local $c var into $count
- /x;
- print "'a' count is $count, \$c variable is '$c'\n";
-
-This prints
-
- 'a' count is 2, $c variable is 'bob'
-
-If we replace the S<C< (?{local $c = $c + 1;})>> with
-S<C< (?{$c = $c + 1;})>>, the variable changes are I<not> undone
-during backtracking, and we get
-
- 'a' count is 4, $c variable is 'bob'
-
-Note that only localized variable changes are undone. Other side
-effects of code expression execution are permanent. Thus
-
- $x = "aaaa";
- $x =~ /(a(?{print "Yow\n";}))*aa/;
-
-produces
-
- Yow
- Yow
- Yow
- Yow
-
-The result C<$^R> is automatically localized, so that it will behave
-properly in the presence of backtracking.
-
-This example uses a code expression in a conditional to match a
-definite article, either 'the' in English or 'der|die|das' in German:
-
- $lang = 'DE'; # use German
- ...
- $text = "das";
- print "matched\n"
- if $text =~ /(?(?{
- $lang eq 'EN'; # is the language English?
- })
- the | # if so, then match 'the'
- (der|die|das) # else, match 'der|die|das'
- )
- /xi;
-
-Note that the syntax here is C<(?(?{...})yes-regexp|no-regexp)>, not
-C<(?((?{...}))yes-regexp|no-regexp)>. In other words, in the case of a
-code expression, we don't need the extra parentheses around the
-conditional.
-
-If you try to use code expressions with interpolating variables, Perl
-may surprise you:
-
- $bar = 5;
- $pat = '(?{ 1 })';
- /foo(?{ $bar })bar/; # compiles ok, $bar not interpolated
- /foo(?{ 1 })$bar/; # compile error!
- /foo${pat}bar/; # compile error!
-
- $pat = qr/(?{ $foo = 1 })/; # precompile code regexp
- /foo${pat}bar/; # compiles ok
-
-If a regexp has (1) code expressions and interpolating variables, or
-(2) a variable that interpolates a code expression, Perl treats the
-regexp as an error. If the code expression is precompiled into a
-variable, however, interpolating is ok. The question is, why is this
-an error?
-
-The reason is that variable interpolation and code expressions
-together pose a security risk. The combination is dangerous because
-many programmers who write search engines often take user input and
-plug it directly into a regexp:
-
- $regexp = <>; # read user-supplied regexp
- $chomp $regexp; # get rid of possible newline
- $text =~ /$regexp/; # search $text for the $regexp
-
-If the C<$regexp> variable contains a code expression, the user could
-then execute arbitrary Perl code. For instance, some joker could
-search for S<C<system('rm -rf *');>> to erase your files. In this
-sense, the combination of interpolation and code expressions I<taints>
-your regexp. So by default, using both interpolation and code
-expressions in the same regexp is not allowed. If you're not
-concerned about malicious users, it is possible to bypass this
-security check by invoking S<C<use re 'eval'>>:
-
- use re 'eval'; # throw caution out the door
- $bar = 5;
- $pat = '(?{ 1 })';
- /foo(?{ 1 })$bar/; # compiles ok
- /foo${pat}bar/; # compiles ok
-
-Another form of code expression is the I<pattern code expression>.
-The pattern code expression is like a regular code expression, except
-that the result of the code evaluation is treated as a regular
-expression and matched immediately. A simple example is
-
- $length = 5;
- $char = 'a';
- $x = 'aaaaabb';
- $x =~ /(??{$char x $length})/x; # matches, there are 5 of 'a'
-
-
-This final example contains both ordinary and pattern code
-expressions. It detects whether a binary string C<1101010010001...> has a
-Fibonacci spacing 0,1,1,2,3,5,... of the C<1>'s:
-
- $x = "1101010010001000001";
- $z0 = ''; $z1 = '0'; # initial conditions
- print "It is a Fibonacci sequence\n"
- if $x =~ /^1 # match an initial '1'
- (?:
- ((??{ $z0 })) # match some '0'
- 1 # and then a '1'
- (?{ $z0 = $z1; $z1 .= $^N; })
- )+ # repeat as needed
- $ # that is all there is
- /x;
- printf "Largest sequence matched was %d\n", length($z1)-length($z0);
-
-Remember that C<$^N> is set to whatever was matched by the last
-completed capture group. This prints
-
- It is a Fibonacci sequence
- Largest sequence matched was 5
-
-Ha! Try that with your garden variety regexp package...
-
-Note that the variables C<$z0> and C<$z1> are not substituted when the
-regexp is compiled, as happens for ordinary variables outside a code
-expression. Rather, the code expressions are evaluated when Perl
-encounters them during the search for a match.
-
-The regexp without the C<//x> modifier is
-
- /^1(?:((??{ $z0 }))1(?{ $z0 = $z1; $z1 .= $^N; }))+$/
-
-which shows that spaces are still possible in the code parts. Nevertheless,
-when working with code and conditional expressions, the extended form of
-regexps is almost necessary in creating and debugging regexps.
-
-
-=head2 Backtracking control verbs
-
-Perl 5.10 introduced a number of control verbs intended to provide
-detailed control over the backtracking process, by directly influencing
-the regexp engine and by providing monitoring techniques. As all
-the features in this group are experimental and subject to change or
-removal in a future version of Perl, the interested reader is
-referred to L<perlre/"Special Backtracking Control Verbs"> for a
-detailed description.
-
-Below is just one example, illustrating the control verb C<(*FAIL)>,
-which may be abbreviated as C<(*F)>. If this is inserted in a regexp
-it will cause it to fail, just as it would at some
-mismatch between the pattern and the string. Processing
-of the regexp continues as it would after any "normal"
-failure, so that, for instance, the next position in the string or another
-alternative will be tried. As failing to match doesn't preserve capture
-groups or produce results, it may be necessary to use this in
-combination with embedded code.
-
- %count = ();
- "supercalifragilisticexpialidocious" =~
- /([aeiou])(?{ $count{$1}++; })(*FAIL)/i;
- printf "%3d '%s'\n", $count{$_}, $_ for (sort keys %count);
-
-The pattern begins with a class matching a subset of letters. Whenever
-this matches, a statement like C<$count{'a'}++;> is executed, incrementing
-the letter's counter. Then C<(*FAIL)> does what it says, and
-the regexp engine proceeds according to the book: as long as the end of
-the string hasn't been reached, the position is advanced before looking
-for another vowel. Thus, match or no match makes no difference, and the
-regexp engine proceeds until the entire string has been inspected.
-(It's remarkable that an alternative solution using something like
-
- $count{lc($_)}++ for split('', "supercalifragilisticexpialidocious");
- printf "%3d '%s'\n", $count2{$_}, $_ for ( qw{ a e i o u } );
-
-is considerably slower.)
-
-
-=head2 Pragmas and debugging
-
-Speaking of debugging, there are several pragmas available to control
-and debug regexps in Perl. We have already encountered one pragma in
-the previous section, S<C<use re 'eval';>>, that allows variable
-interpolation and code expressions to coexist in a regexp. The other
-pragmas are
-
- use re 'taint';
- $tainted = <>;
- @parts = ($tainted =~ /(\w+)\s+(\w+)/; # @parts is now tainted
-
-The C<taint> pragma causes any substrings from a match with a tainted
-variable to be tainted as well. This is not normally the case, as
-regexps are often used to extract the safe bits from a tainted
-variable. Use C<taint> when you are not extracting safe bits, but are
-performing some other processing. Both C<taint> and C<eval> pragmas
-are lexically scoped, which means they are in effect only until
-the end of the block enclosing the pragmas.
-
- use re '/m'; # or any other flags
- $multiline_string =~ /^foo/; # /m is implied
-
-The C<re '/flags'> pragma (introduced in Perl
-5.14) turns on the given regular expression flags
-until the end of the lexical scope. See
-L<re/"'E<sol>flags' mode"> for more
-detail.
-
- use re 'debug';
- /^(.*)$/s; # output debugging info
-
- use re 'debugcolor';
- /^(.*)$/s; # output debugging info in living color
-
-The global C<debug> and C<debugcolor> pragmas allow one to get
-detailed debugging info about regexp compilation and
-execution. C<debugcolor> is the same as debug, except the debugging
-information is displayed in color on terminals that can display
-termcap color sequences. Here is example output:
-
- % perl -e 'use re "debug"; "abc" =~ /a*b+c/;'
- Compiling REx 'a*b+c'
- size 9 first at 1
- 1: STAR(4)
- 2: EXACT <a>(0)
- 4: PLUS(7)
- 5: EXACT <b>(0)
- 7: EXACT <c>(9)
- 9: END(0)
- floating 'bc' at 0..2147483647 (checking floating) minlen 2
- Guessing start of match, REx 'a*b+c' against 'abc'...
- Found floating substr 'bc' at offset 1...
- Guessed: match at offset 0
- Matching REx 'a*b+c' against 'abc'
- Setting an EVAL scope, savestack=3
- 0 <> <abc> | 1: STAR
- EXACT <a> can match 1 times out of 32767...
- Setting an EVAL scope, savestack=3
- 1 <a> <bc> | 4: PLUS
- EXACT <b> can match 1 times out of 32767...
- Setting an EVAL scope, savestack=3
- 2 <ab> <c> | 7: EXACT <c>
- 3 <abc> <> | 9: END
- Match successful!
- Freeing REx: 'a*b+c'
-
-If you have gotten this far into the tutorial, you can probably guess
-what the different parts of the debugging output tell you. The first
-part
-
- Compiling REx 'a*b+c'
- size 9 first at 1
- 1: STAR(4)
- 2: EXACT <a>(0)
- 4: PLUS(7)
- 5: EXACT <b>(0)
- 7: EXACT <c>(9)
- 9: END(0)
-
-describes the compilation stage. C<STAR(4)> means that there is a
-starred object, in this case C<'a'>, and if it matches, goto line 4,
-i.e., C<PLUS(7)>. The middle lines describe some heuristics and
-optimizations performed before a match:
-
- floating 'bc' at 0..2147483647 (checking floating) minlen 2
- Guessing start of match, REx 'a*b+c' against 'abc'...
- Found floating substr 'bc' at offset 1...
- Guessed: match at offset 0
-
-Then the match is executed and the remaining lines describe the
-process:
-
- Matching REx 'a*b+c' against 'abc'
- Setting an EVAL scope, savestack=3
- 0 <> <abc> | 1: STAR
- EXACT <a> can match 1 times out of 32767...
- Setting an EVAL scope, savestack=3
- 1 <a> <bc> | 4: PLUS
- EXACT <b> can match 1 times out of 32767...
- Setting an EVAL scope, savestack=3
- 2 <ab> <c> | 7: EXACT <c>
- 3 <abc> <> | 9: END
- Match successful!
- Freeing REx: 'a*b+c'
-
-Each step is of the form S<C<< n <x> <y> >>>, with C<< <x> >> the
-part of the string matched and C<< <y> >> the part not yet
-matched. The S<C<< | 1: STAR >>> says that Perl is at line number 1
-in the compilation list above. See
-L<perldebguts/"Debugging Regular Expressions"> for much more detail.
-
-An alternative method of debugging regexps is to embed C<print>
-statements within the regexp. This provides a blow-by-blow account of
-the backtracking in an alternation:
-
- "that this" =~ m@(?{print "Start at position ", pos, "\n";})
- t(?{print "t1\n";})
- h(?{print "h1\n";})
- i(?{print "i1\n";})
- s(?{print "s1\n";})
- |
- t(?{print "t2\n";})
- h(?{print "h2\n";})
- a(?{print "a2\n";})
- t(?{print "t2\n";})
- (?{print "Done at position ", pos, "\n";})
- @x;
-
-prints
-
- Start at position 0
- t1
- h1
- t2
- h2
- a2
- t2
- Done at position 4
-
-=head1 BUGS
-
-Code expressions, conditional expressions, and independent expressions
-are I<experimental>. Don't use them in production code. Yet.
-
-=head1 SEE ALSO
-
-This is just a tutorial. For the full story on Perl regular
-expressions, see the L<perlre> regular expressions reference page.
-
-For more information on the matching C<m//> and substitution C<s///>
-operators, see L<perlop/"Regexp Quote-Like Operators">. For
-information on the C<split> operation, see L<perlfunc/split>.
-
-For an excellent all-around resource on the care and feeding of
-regular expressions, see the book I<Mastering Regular Expressions> by
-Jeffrey Friedl (published by O'Reilly, ISBN 1556592-257-3).
-
-=head1 AUTHOR AND COPYRIGHT
-
-Copyright (c) 2000 Mark Kvale
-All rights reserved.
-
-This document may be distributed under the same terms as Perl itself.
-
-=head2 Acknowledgments
-
-The inspiration for the stop codon DNA example came from the ZIP
-code example in chapter 7 of I<Mastering Regular Expressions>.
-
-The author would like to thank Jeff Pinyan, Andrew Johnson, Peter
-Haworth, Ronald J Kimball, and Joe Smith for all their helpful
-comments.
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlriscos.pod b/Master/tlpkg/tlperl/lib/pods/perlriscos.pod
deleted file mode 100644
index 2acd738c8c3..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlriscos.pod
+++ /dev/null
@@ -1,67 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see pod/perlpod.pod) which is
-specifically designed to be readable as is.
-
-=head1 NAME
-
-perlriscos - Perl version 5 for RISC OS
-
-=head1 DESCRIPTION
-
-This document gives instructions for building Perl for RISC OS. It is
-complicated by the need to cross compile. There is a binary version of
-perl available from L<http://www.cp15.org/perl/> which you may wish to
-use instead of trying to compile it yourself.
-
-=head1 BUILD
-
-You need an installed and working gccsdk cross compiler
-L<http://gccsdk.riscos.info/> and REXEN
-L<http://www.cp15.org/programming/>
-
-Firstly, copy the source and build a native copy of perl for your host
-system.
-Then, in the source to be cross compiled:
-
-=over 4
-
-=item 1.
-
- $ ./Configure
-
-=item 2.
-
-Select the riscos hint file. The default answers for the rest of the
-questions are usually sufficient.
-
-Note that, if you wish to run Configure non-interactively (see the INSTALL
-document for details), to have it select the correct hint file, you'll
-need to provide the argument -Dhintfile=riscos on the Configure
-command-line.
-
-=item 3.
-
- $ make miniperl
-
-=item 4.
-
-This should build miniperl and then fail when it tries to run it.
-
-=item 5.
-
-Copy the miniperl executable from the native build done earlier to
-replace the cross compiled miniperl.
-
-=item 6.
-
- $ make
-
-=item 7.
-
-This will use miniperl to complete the rest of the build.
-
-=back
-
-=head1 AUTHOR
-
-Alex Waugh <alex@alexwaugh.com>
diff --git a/Master/tlpkg/tlperl/lib/pods/perlrun.pod b/Master/tlpkg/tlperl/lib/pods/perlrun.pod
deleted file mode 100644
index 6ddc608d4f4..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlrun.pod
+++ /dev/null
@@ -1,1353 +0,0 @@
-=head1 NAME
-
-perlrun - how to execute the Perl interpreter
-
-=head1 SYNOPSIS
-
-B<perl> S<[ B<-sTtuUWX> ]>
- S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
- S<[ B<-cw> ] [ B<-d>[B<t>][:I<debugger>] ] [ B<-D>[I<number/list>] ]>
- S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal/hexadecimal>] ]>
- S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ] [ B<-f> ]>
- S<[ B<-C [I<number/list>] >]>
- S<[ B<-S> ]>
- S<[ B<-x>[I<dir>] ]>
- S<[ B<-i>[I<extension>] ]>
- S<[ [B<-e>|B<-E>] I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
-
-=head1 DESCRIPTION
-
-The normal way to run a Perl program is by making it directly
-executable, or else by passing the name of the source file as an
-argument on the command line. (An interactive Perl environment
-is also possible--see L<perldebug> for details on how to do that.)
-Upon startup, Perl looks for your program in one of the following
-places:
-
-=over 4
-
-=item 1.
-
-Specified line by line via B<-e> or B<-E> switches on the command line.
-
-=item 2.
-
-Contained in the file specified by the first filename on the command line.
-(Note that systems supporting the C<#!> notation invoke interpreters this
-way. See L<Location of Perl>.)
-
-=item 3.
-
-Passed in implicitly via standard input. This works only if there are
-no filename arguments--to pass arguments to a STDIN-read program you
-must explicitly specify a "-" for the program name.
-
-=back
-
-With methods 2 and 3, Perl starts parsing the input file from the
-beginning, unless you've specified a B<-x> switch, in which case it
-scans for the first line starting with C<#!> and containing the word
-"perl", and starts there instead. This is useful for running a program
-embedded in a larger message. (In this case you would indicate the end
-of the program using the C<__END__> token.)
-
-The C<#!> line is always examined for switches as the line is being
-parsed. Thus, if you're on a machine that allows only one argument
-with the C<#!> line, or worse, doesn't even recognize the C<#!> line, you
-still can get consistent switch behaviour regardless of how Perl was
-invoked, even if B<-x> was used to find the beginning of the program.
-
-Because historically some operating systems silently chopped off
-kernel interpretation of the C<#!> line after 32 characters, some
-switches may be passed in on the command line, and some may not;
-you could even get a "-" without its letter, if you're not careful.
-You probably want to make sure that all your switches fall either
-before or after that 32-character boundary. Most switches don't
-actually care if they're processed redundantly, but getting a "-"
-instead of a complete switch could cause Perl to try to execute
-standard input instead of your program. And a partial B<-I> switch
-could also cause odd results.
-
-Some switches do care if they are processed twice, for instance
-combinations of B<-l> and B<-0>. Either put all the switches after
-the 32-character boundary (if applicable), or replace the use of
-B<-0>I<digits> by C<BEGIN{ $/ = "\0digits"; }>.
-
-Parsing of the C<#!> switches starts wherever "perl" is mentioned in the line.
-The sequences "-*" and "- " are specifically ignored so that you could,
-if you were so inclined, say
-
- #!/bin/sh
- #! -*-perl-*-
- eval 'exec perl -x -wS $0 ${1+"$@"}'
- if 0;
-
-to let Perl see the B<-p> switch.
-
-A similar trick involves the I<env> program, if you have it.
-
- #!/usr/bin/env perl
-
-The examples above use a relative path to the perl interpreter,
-getting whatever version is first in the user's path. If you want
-a specific version of Perl, say, perl5.005_57, you should place
-that directly in the C<#!> line's path.
-
-If the C<#!> line does not contain the word "perl" nor the word "indir"
-the program named after the C<#!> is executed instead of the Perl
-interpreter. This is slightly bizarre, but it helps people on machines
-that don't do C<#!>, because they can tell a program that their SHELL is
-F</usr/bin/perl>, and Perl will then dispatch the program to the correct
-interpreter for them.
-
-After locating your program, Perl compiles the entire program to an
-internal form. If there are any compilation errors, execution of the
-program is not attempted. (This is unlike the typical shell script,
-which might run part-way through before finding a syntax error.)
-
-If the program is syntactically correct, it is executed. If the program
-runs off the end without hitting an exit() or die() operator, an implicit
-C<exit(0)> is provided to indicate successful completion.
-
-=head2 #! and quoting on non-Unix systems
-X<hashbang> X<#!>
-
-Unix's C<#!> technique can be simulated on other systems:
-
-=over 4
-
-=item OS/2
-
-Put
-
- extproc perl -S -your_switches
-
-as the first line in C<*.cmd> file (B<-S> due to a bug in cmd.exe's
-`extproc' handling).
-
-=item MS-DOS
-
-Create a batch file to run your program, and codify it in
-C<ALTERNATE_SHEBANG> (see the F<dosish.h> file in the source
-distribution for more information).
-
-=item Win95/NT
-
-The Win95/NT installation, when using the ActiveState installer for Perl,
-will modify the Registry to associate the F<.pl> extension with the perl
-interpreter. If you install Perl by other means (including building from
-the sources), you may have to modify the Registry yourself. Note that
-this means you can no longer tell the difference between an executable
-Perl program and a Perl library file.
-
-=item VMS
-
-Put
-
- $ perl -mysw 'f$env("procedure")' 'p1' 'p2' 'p3' 'p4' 'p5' 'p6' 'p7' 'p8' !
- $ exit++ + ++$status != 0 and $exit = $status = undef;
-
-at the top of your program, where B<-mysw> are any command line switches you
-want to pass to Perl. You can now invoke the program directly, by saying
-C<perl program>, or as a DCL procedure, by saying C<@program> (or implicitly
-via F<DCL$PATH> by just using the name of the program).
-
-This incantation is a bit much to remember, but Perl will display it for
-you if you say C<perl "-V:startperl">.
-
-=back
-
-Command-interpreters on non-Unix systems have rather different ideas
-on quoting than Unix shells. You'll need to learn the special
-characters in your command-interpreter (C<*>, C<\> and C<"> are
-common) and how to protect whitespace and these characters to run
-one-liners (see L<-e|/-e commandline> below).
-
-On some systems, you may have to change single-quotes to double ones,
-which you must I<not> do on Unix or Plan 9 systems. You might also
-have to change a single % to a %%.
-
-For example:
-
- # Unix
- perl -e 'print "Hello world\n"'
-
- # MS-DOS, etc.
- perl -e "print \"Hello world\n\""
-
- # VMS
- perl -e "print ""Hello world\n"""
-
-The problem is that none of this is reliable: it depends on the
-command and it is entirely possible neither works. If I<4DOS> were
-the command shell, this would probably work better:
-
- perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>""
-
-B<CMD.EXE> in Windows NT slipped a lot of standard Unix functionality in
-when nobody was looking, but just try to find documentation for its
-quoting rules.
-
-There is no general solution to all of this. It's just a mess.
-
-=head2 Location of Perl
-X<perl, location of interpreter>
-
-It may seem obvious to say, but Perl is useful only when users can
-easily find it. When possible, it's good for both F</usr/bin/perl>
-and F</usr/local/bin/perl> to be symlinks to the actual binary. If
-that can't be done, system administrators are strongly encouraged
-to put (symlinks to) perl and its accompanying utilities into a
-directory typically found along a user's PATH, or in some other
-obvious and convenient place.
-
-In this documentation, C<#!/usr/bin/perl> on the first line of the program
-will stand in for whatever method works on your system. You are
-advised to use a specific path if you care about a specific version.
-
- #!/usr/local/bin/perl5.00554
-
-or if you just want to be running at least version, place a statement
-like this at the top of your program:
-
- use 5.005_54;
-
-=head2 Command Switches
-X<perl, command switches> X<command switches>
-
-As with all standard commands, a single-character switch may be
-clustered with the following switch, if any.
-
- #!/usr/bin/perl -spi.orig # same as -s -p -i.orig
-
-Switches include:
-
-=over 5
-
-=item B<-0>[I<octal/hexadecimal>]
-X<-0> X<$/>
-
-specifies the input record separator (C<$/>) as an octal or
-hexadecimal number. If there are no digits, the null character is the
-separator. Other switches may precede or follow the digits. For
-example, if you have a version of I<find> which can print filenames
-terminated by the null character, you can say this:
-
- find . -name '*.orig' -print0 | perl -n0e unlink
-
-The special value 00 will cause Perl to slurp files in paragraph mode.
-Any value 0400 or above will cause Perl to slurp files whole, but by convention
-the value 0777 is the one normally used for this purpose.
-
-You can also specify the separator character using hexadecimal notation:
-B<-0xI<HHH...>>, where the C<I<H>> are valid hexadecimal digits. Unlike
-the octal form, this one may be used to specify any Unicode character, even
-those beyond 0xFF. So if you I<really> want a record separator of 0777,
-specify it as B<-0x1FF>. (This means that you cannot use the B<-x> option
-with a directory name that consists of hexadecimal digits, or else Perl
-will think you have specified a hex number to B<-0>.)
-
-=item B<-a>
-X<-a> X<autosplit>
-
-turns on autosplit mode when used with a B<-n> or B<-p>. An implicit
-split command to the @F array is done as the first thing inside the
-implicit while loop produced by the B<-n> or B<-p>.
-
- perl -ane 'print pop(@F), "\n";'
-
-is equivalent to
-
- while (<>) {
- @F = split(' ');
- print pop(@F), "\n";
- }
-
-An alternate delimiter may be specified using B<-F>.
-
-=item B<-C [I<number/list>]>
-X<-C>
-
-The B<-C> flag controls some of the Perl Unicode features.
-
-As of 5.8.1, the B<-C> can be followed either by a number or a list
-of option letters. The letters, their numeric values, and effects
-are as follows; listing the letters is equal to summing the numbers.
-
- I 1 STDIN is assumed to be in UTF-8
- O 2 STDOUT will be in UTF-8
- E 4 STDERR will be in UTF-8
- S 7 I + O + E
- i 8 UTF-8 is the default PerlIO layer for input streams
- o 16 UTF-8 is the default PerlIO layer for output streams
- D 24 i + o
- A 32 the @ARGV elements are expected to be strings encoded
- in UTF-8
- L 64 normally the "IOEioA" are unconditional, the L makes
- them conditional on the locale environment variables
- (the LC_ALL, LC_TYPE, and LANG, in the order of
- decreasing precedence) -- if the variables indicate
- UTF-8, then the selected "IOEioA" are in effect
- a 256 Set ${^UTF8CACHE} to -1, to run the UTF-8 caching
- code in debugging mode.
-
-=for documenting_the_underdocumented
-perl.h gives W/128 as PERL_UNICODE_WIDESYSCALLS "/* for Sarathy */"
-
-=for todo
-perltodo mentions Unicode in %ENV and filenames. I guess that these will be
-options e and f (or F).
-
-For example, B<-COE> and B<-C6> will both turn on UTF-8-ness on both
-STDOUT and STDERR. Repeating letters is just redundant, not cumulative
-nor toggling.
-
-The C<io> options mean that any subsequent open() (or similar I/O
-operations) in the current file scope will have the C<:utf8> PerlIO layer
-implicitly applied to them, in other words, UTF-8 is expected from any
-input stream, and UTF-8 is produced to any output stream. This is just
-the default, with explicit layers in open() and with binmode() one can
-manipulate streams as usual.
-
-B<-C> on its own (not followed by any number or option list), or the
-empty string C<""> for the C<PERL_UNICODE> environment variable, has the
-same effect as B<-CSDL>. In other words, the standard I/O handles and
-the default C<open()> layer are UTF-8-fied I<but> only if the locale
-environment variables indicate a UTF-8 locale. This behaviour follows
-the I<implicit> (and problematic) UTF-8 behaviour of Perl 5.8.0.
-(See L<perl581delta/UTF-8 no longer default under UTF-8 locales>.)
-
-You can use B<-C0> (or C<"0"> for C<PERL_UNICODE>) to explicitly
-disable all the above Unicode features.
-
-The read-only magic variable C<${^UNICODE}> reflects the numeric value
-of this setting. This variable is set during Perl startup and is
-thereafter read-only. If you want runtime effects, use the three-arg
-open() (see L<perlfunc/open>), the two-arg binmode() (see L<perlfunc/binmode>),
-and the C<open> pragma (see L<open>).
-
-(In Perls earlier than 5.8.1 the B<-C> switch was a Win32-only switch
-that enabled the use of Unicode-aware "wide system call" Win32 APIs.
-This feature was practically unused, however, and the command line
-switch was therefore "recycled".)
-
-B<Note:> Since perl 5.10.1, if the B<-C> option is used on the C<#!> line,
-it must be specified on the command line as well, since the standard streams
-are already set up at this point in the execution of the perl interpreter.
-You can also use binmode() to set the encoding of an I/O stream.
-
-=item B<-c>
-X<-c>
-
-causes Perl to check the syntax of the program and then exit without
-executing it. Actually, it I<will> execute and C<BEGIN>, C<UNITCHECK>,
-or C<CHECK> blocks and any C<use> statements: these are considered as
-occurring outside the execution of your program. C<INIT> and C<END>
-blocks, however, will be skipped.
-
-=item B<-d>
-X<-d> X<-dt>
-
-=item B<-dt>
-
-runs the program under the Perl debugger. See L<perldebug>.
-If B<t> is specified, it indicates to the debugger that threads
-will be used in the code being debugged.
-
-=item B<-d:>I<MOD[=bar,baz]>
-X<-d> X<-dt>
-
-=item B<-dt:>I<MOD[=bar,baz]>
-
-runs the program under the control of a debugging, profiling, or tracing
-module installed as C<Devel::I<MOD>>. E.g., B<-d:DProf> executes the
-program using the C<Devel::DProf> profiler. As with the B<-M> flag, options
-may be passed to the C<Devel::I<MOD>> package where they will be received
-and interpreted by the C<Devel::I<MOD>::import> routine. Again, like B<-M>,
-use -B<-d:-I<MOD>> to call C<Devel::I<MOD>::unimport> instead of import. The
-comma-separated list of options must follow a C<=> character. If B<t> is
-specified, it indicates to the debugger that threads will be used in the
-code being debugged. See L<perldebug>.
-
-=item B<-D>I<letters>
-X<-D> X<DEBUGGING> X<-DDEBUGGING>
-
-=item B<-D>I<number>
-
-sets debugging flags. To watch how it executes your program, use
-B<-Dtls>. (This works only if debugging is compiled into your
-Perl.) Another nice value is B<-Dx>, which lists your compiled
-syntax tree. And B<-Dr> displays compiled regular expressions;
-the format of the output is explained in L<perldebguts>.
-
-As an alternative, specify a number instead of list of letters (e.g.,
-B<-D14> is equivalent to B<-Dtls>):
-
- 1 p Tokenizing and parsing (with v, displays parse stack)
- 2 s Stack snapshots (with v, displays all stacks)
- 4 l Context (loop) stack processing
- 8 t Trace execution
- 16 o Method and overloading resolution
- 32 c String/numeric conversions
- 64 P Print profiling info, source file input state
- 128 m Memory and SV allocation
- 256 f Format processing
- 512 r Regular expression parsing and execution
- 1024 x Syntax tree dump
- 2048 u Tainting checks
- 4096 U Unofficial, User hacking (reserved for private,
- unreleased use)
- 8192 H Hash dump -- usurps values()
- 16384 X Scratchpad allocation
- 32768 D Cleaning up
- 131072 T Tokenizing
- 262144 R Include reference counts of dumped variables (eg when
- using -Ds)
- 524288 J show s,t,P-debug (don't Jump over) on opcodes within
- package DB
- 1048576 v Verbose: use in conjunction with other flags
- 2097152 C Copy On Write
- 4194304 A Consistency checks on internal structures
- 8388608 q quiet - currently only suppresses the "EXECUTING"
- message
- 16777216 M trace smart match resolution
- 33554432 B dump suBroutine definitions, including special Blocks
- like BEGIN
-
-All these flags require B<-DDEBUGGING> when you compile the Perl
-executable (but see C<:opd> in L<Devel::Peek> or L<re/'debug' mode>
-which may change this).
-See the F<INSTALL> file in the Perl source distribution
-for how to do this. This flag is automatically set if you include B<-g>
-option when C<Configure> asks you about optimizer/debugger flags.
-
-If you're just trying to get a print out of each line of Perl code
-as it executes, the way that C<sh -x> provides for shell scripts,
-you can't use Perl's B<-D> switch. Instead do this
-
- # If you have "env" utility
- env PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
-
- # Bourne shell syntax
- $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
-
- # csh syntax
- % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl -dS program)
-
-See L<perldebug> for details and variations.
-
-=item B<-e> I<commandline>
-X<-e>
-
-may be used to enter one line of program. If B<-e> is given, Perl
-will not look for a filename in the argument list. Multiple B<-e>
-commands may be given to build up a multi-line script. Make sure
-to use semicolons where you would in a normal program.
-
-=item B<-E> I<commandline>
-X<-E>
-
-behaves just like B<-e>, except that it implicitly enables all
-optional features (in the main compilation unit). See L<feature>.
-
-=item B<-f>
-X<-f> X<sitecustomize> X<sitecustomize.pl>
-
-Disable executing F<$Config{sitelib}/sitecustomize.pl> at startup.
-
-Perl can be built so that it by default will try to execute
-F<$Config{sitelib}/sitecustomize.pl> at startup (in a BEGIN block).
-This is a hook that allows the sysadmin to customize how Perl behaves.
-It can for instance be used to add entries to the @INC array to make Perl
-find modules in non-standard locations.
-
-Perl actually inserts the following code:
-
- BEGIN {
- do { local $!; -f "$Config{sitelib}/sitecustomize.pl"; }
- && do "$Config{sitelib}/sitecustomize.pl";
- }
-
-Since it is an actual C<do> (not a C<require>), F<sitecustomize.pl>
-doesn't need to return a true value. The code is run in package C<main>,
-in its own lexical scope. However, if the script dies, C<$@> will not
-be set.
-
-The value of C<$Config{sitelib}> is also determined in C code and not
-read from C<Config.pm>, which is not loaded.
-
-The code is executed I<very> early. For example, any changes made to
-C<@INC> will show up in the output of `perl -V`. Of course, C<END>
-blocks will be likewise executed very late.
-
-To determine at runtime if this capability has been compiled in your
-perl, you can check the value of C<$Config{usesitecustomize}>.
-
-=item B<-F>I<pattern>
-X<-F>
-
-specifies the pattern to split on if B<-a> is also in effect. The
-pattern may be surrounded by C<//>, C<"">, or C<''>, otherwise it will be
-put in single quotes. You can't use literal whitespace in the pattern.
-
-=item B<-h>
-X<-h>
-
-prints a summary of the options.
-
-=item B<-i>[I<extension>]
-X<-i> X<in-place>
-
-specifies that files processed by the C<E<lt>E<gt>> construct are to be
-edited in-place. It does this by renaming the input file, opening the
-output file by the original name, and selecting that output file as the
-default for print() statements. The extension, if supplied, is used to
-modify the name of the old file to make a backup copy, following these
-rules:
-
-If no extension is supplied, no backup is made and the current file is
-overwritten.
-
-If the extension doesn't contain a C<*>, then it is appended to the
-end of the current filename as a suffix. If the extension does
-contain one or more C<*> characters, then each C<*> is replaced
-with the current filename. In Perl terms, you could think of this
-as:
-
- ($backup = $extension) =~ s/\*/$file_name/g;
-
-This allows you to add a prefix to the backup file, instead of (or in
-addition to) a suffix:
-
- $ perl -pi'orig_*' -e 's/bar/baz/' fileA # backup to
- # 'orig_fileA'
-
-Or even to place backup copies of the original files into another
-directory (provided the directory already exists):
-
- $ perl -pi'old/*.orig' -e 's/bar/baz/' fileA # backup to
- # 'old/fileA.orig'
-
-These sets of one-liners are equivalent:
-
- $ perl -pi -e 's/bar/baz/' fileA # overwrite current file
- $ perl -pi'*' -e 's/bar/baz/' fileA # overwrite current file
-
- $ perl -pi'.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
- $ perl -pi'*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
-
-From the shell, saying
-
- $ perl -p -i.orig -e "s/foo/bar/; ... "
-
-is the same as using the program:
-
- #!/usr/bin/perl -pi.orig
- s/foo/bar/;
-
-which is equivalent to
-
- #!/usr/bin/perl
- $extension = '.orig';
- LINE: while (<>) {
- if ($ARGV ne $oldargv) {
- if ($extension !~ /\*/) {
- $backup = $ARGV . $extension;
- }
- else {
- ($backup = $extension) =~ s/\*/$ARGV/g;
- }
- rename($ARGV, $backup);
- open(ARGVOUT, ">$ARGV");
- select(ARGVOUT);
- $oldargv = $ARGV;
- }
- s/foo/bar/;
- }
- continue {
- print; # this prints to original filename
- }
- select(STDOUT);
-
-except that the B<-i> form doesn't need to compare $ARGV to $oldargv to
-know when the filename has changed. It does, however, use ARGVOUT for
-the selected filehandle. Note that STDOUT is restored as the default
-output filehandle after the loop.
-
-As shown above, Perl creates the backup file whether or not any output
-is actually changed. So this is just a fancy way to copy files:
-
- $ perl -p -i'/some/file/path/*' -e 1 file1 file2 file3...
-or
- $ perl -p -i'.orig' -e 1 file1 file2 file3...
-
-You can use C<eof> without parentheses to locate the end of each input
-file, in case you want to append to each file, or reset line numbering
-(see example in L<perlfunc/eof>).
-
-If, for a given file, Perl is unable to create the backup file as
-specified in the extension then it will skip that file and continue on
-with the next one (if it exists).
-
-For a discussion of issues surrounding file permissions and B<-i>,
-see L<perlfaq5/Why does Perl let me delete read-only files? Why does -i clobber protected files? Isn't this a bug in Perl?>.
-
-You cannot use B<-i> to create directories or to strip extensions from
-files.
-
-Perl does not expand C<~> in filenames, which is good, since some
-folks use it for their backup files:
-
- $ perl -pi~ -e 's/foo/bar/' file1 file2 file3...
-
-Note that because B<-i> renames or deletes the original file before
-creating a new file of the same name, Unix-style soft and hard links will
-not be preserved.
-
-Finally, the B<-i> switch does not impede execution when no
-files are given on the command line. In this case, no backup is made
-(the original file cannot, of course, be determined) and processing
-proceeds from STDIN to STDOUT as might be expected.
-
-=item B<-I>I<directory>
-X<-I> X<@INC>
-
-Directories specified by B<-I> are prepended to the search path for
-modules (C<@INC>).
-
-=item B<-l>[I<octnum>]
-X<-l> X<$/> X<$\>
-
-enables automatic line-ending processing. It has two separate
-effects. First, it automatically chomps C<$/> (the input record
-separator) when used with B<-n> or B<-p>. Second, it assigns C<$\>
-(the output record separator) to have the value of I<octnum> so
-that any print statements will have that separator added back on.
-If I<octnum> is omitted, sets C<$\> to the current value of
-C<$/>. For instance, to trim lines to 80 columns:
-
- perl -lpe 'substr($_, 80) = ""'
-
-Note that the assignment C<$\ = $/> is done when the switch is processed,
-so the input record separator can be different than the output record
-separator if the B<-l> switch is followed by a B<-0> switch:
-
- gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
-
-This sets C<$\> to newline and then sets C<$/> to the null character.
-
-=item B<-m>[B<->]I<module>
-X<-m> X<-M>
-
-=item B<-M>[B<->]I<module>
-
-=item B<-M>[B<->]I<'module ...'>
-
-=item B<-[mM]>[B<->]I<module=arg[,arg]...>
-
-B<-m>I<module> executes C<use> I<module> C<();> before executing your
-program.
-
-B<-M>I<module> executes C<use> I<module> C<;> before executing your
-program. You can use quotes to add extra code after the module name,
-e.g., C<'-MI<MODULE> qw(foo bar)'>.
-
-If the first character after the B<-M> or B<-m> is a dash (B<->)
-then the 'use' is replaced with 'no'.
-
-A little builtin syntactic sugar means you can also say
-B<-mI<MODULE>=foo,bar> or B<-MI<MODULE>=foo,bar> as a shortcut for
-B<'-MI<MODULE> qw(foo bar)'>. This avoids the need to use quotes when
-importing symbols. The actual code generated by B<-MI<MODULE>=foo,bar> is
-C<use module split(/,/,q{foo,bar})>. Note that the C<=> form
-removes the distinction between B<-m> and B<-M>.
-
-A consequence of this is that B<-MI<MODULE>=number> never does a version check,
-unless C<I<MODULE>::import()> itself is set up to do a version check, which
-could happen for example if I<MODULE> inherits from L<Exporter>.
-
-=item B<-n>
-X<-n>
-
-causes Perl to assume the following loop around your program, which
-makes it iterate over filename arguments somewhat like I<sed -n> or
-I<awk>:
-
- LINE:
- while (<>) {
- ... # your program goes here
- }
-
-Note that the lines are not printed by default. See L</-p> to have
-lines printed. If a file named by an argument cannot be opened for
-some reason, Perl warns you about it and moves on to the next file.
-
-Also note that C<< <> >> passes command line arguments to
-L<perlfunc/open>, which doesn't necessarily interpret them as file names.
-See L<perlop> for possible security implications.
-
-Here is an efficient way to delete all files that haven't been modified for
-at least a week:
-
- find . -mtime +7 -print | perl -nle unlink
-
-This is faster than using the B<-exec> switch of I<find> because you don't
-have to start a process on every filename found. It does suffer from
-the bug of mishandling newlines in pathnames, which you can fix if
-you follow the example under B<-0>.
-
-C<BEGIN> and C<END> blocks may be used to capture control before or after
-the implicit program loop, just as in I<awk>.
-
-=item B<-p>
-X<-p>
-
-causes Perl to assume the following loop around your program, which
-makes it iterate over filename arguments somewhat like I<sed>:
-
-
- LINE:
- while (<>) {
- ... # your program goes here
- } continue {
- print or die "-p destination: $!\n";
- }
-
-If a file named by an argument cannot be opened for some reason, Perl
-warns you about it, and moves on to the next file. Note that the
-lines are printed automatically. An error occurring during printing is
-treated as fatal. To suppress printing use the B<-n> switch. A B<-p>
-overrides a B<-n> switch.
-
-C<BEGIN> and C<END> blocks may be used to capture control before or after
-the implicit loop, just as in I<awk>.
-
-=item B<-s>
-X<-s>
-
-enables rudimentary switch parsing for switches on the command
-line after the program name but before any filename arguments (or before
-an argument of B<-->). Any switch found there is removed from @ARGV and sets the
-corresponding variable in the Perl program. The following program
-prints "1" if the program is invoked with a B<-xyz> switch, and "abc"
-if it is invoked with B<-xyz=abc>.
-
- #!/usr/bin/perl -s
- if ($xyz) { print "$xyz\n" }
-
-Do note that a switch like B<--help> creates the variable C<${-help}>, which is not compliant
-with C<use strict "refs">. Also, when using this option on a script with
-warnings enabled you may get a lot of spurious "used only once" warnings.
-
-=item B<-S>
-X<-S>
-
-makes Perl use the PATH environment variable to search for the
-program unless the name of the program contains path separators.
-
-On some platforms, this also makes Perl append suffixes to the
-filename while searching for it. For example, on Win32 platforms,
-the ".bat" and ".cmd" suffixes are appended if a lookup for the
-original name fails, and if the name does not already end in one
-of those suffixes. If your Perl was compiled with C<DEBUGGING> turned
-on, using the B<-Dp> switch to Perl shows how the search progresses.
-
-Typically this is used to emulate C<#!> startup on platforms that don't
-support C<#!>. It's also convenient when debugging a script that uses C<#!>,
-and is thus normally found by the shell's $PATH search mechanism.
-
-This example works on many platforms that have a shell compatible with
-Bourne shell:
-
- #!/usr/bin/perl
- eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
- if $running_under_some_shell;
-
-The system ignores the first line and feeds the program to F</bin/sh>,
-which proceeds to try to execute the Perl program as a shell script.
-The shell executes the second line as a normal shell command, and thus
-starts up the Perl interpreter. On some systems $0 doesn't always
-contain the full pathname, so the B<-S> tells Perl to search for the
-program if necessary. After Perl locates the program, it parses the
-lines and ignores them because the variable $running_under_some_shell
-is never true. If the program will be interpreted by csh, you will need
-to replace C<${1+"$@"}> with C<$*>, even though that doesn't understand
-embedded spaces (and such) in the argument list. To start up I<sh> rather
-than I<csh>, some systems may have to replace the C<#!> line with a line
-containing just a colon, which will be politely ignored by Perl. Other
-systems can't control that, and need a totally devious construct that
-will work under any of I<csh>, I<sh>, or Perl, such as the following:
-
- eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}'
- & eval 'exec /usr/bin/perl -wS $0 $argv:q'
- if $running_under_some_shell;
-
-If the filename supplied contains directory separators (and so is an
-absolute or relative pathname), and if that file is not found,
-platforms that append file extensions will do so and try to look
-for the file with those extensions added, one by one.
-
-On DOS-like platforms, if the program does not contain directory
-separators, it will first be searched for in the current directory
-before being searched for on the PATH. On Unix platforms, the
-program will be searched for strictly on the PATH.
-
-=item B<-t>
-X<-t>
-
-Like B<-T>, but taint checks will issue warnings rather than fatal
-errors. These warnings can now be controlled normally with C<no warnings
-qw(taint)>.
-
-B<Note: This is not a substitute for C<-T>!> This is meant to be
-used I<only> as a temporary development aid while securing legacy code:
-for real production code and for new secure code written from scratch,
-always use the real B<-T>.
-
-=item B<-T>
-X<-T>
-
-turns on "taint" so you can test them. Ordinarily
-these checks are done only when running setuid or setgid. It's a
-good idea to turn them on explicitly for programs that run on behalf
-of someone else whom you might not necessarily trust, such as CGI
-programs or any internet servers you might write in Perl. See
-L<perlsec> for details. For security reasons, this option must be
-seen by Perl quite early; usually this means it must appear early
-on the command line or in the C<#!> line for systems which support
-that construct.
-
-=item B<-u>
-X<-u>
-
-This switch causes Perl to dump core after compiling your
-program. You can then in theory take this core dump and turn it
-into an executable file by using the I<undump> program (not supplied).
-This speeds startup at the expense of some disk space (which you
-can minimize by stripping the executable). (Still, a "hello world"
-executable comes out to about 200K on my machine.) If you want to
-execute a portion of your program before dumping, use the dump()
-operator instead. Note: availability of I<undump> is platform
-specific and may not be available for a specific port of Perl.
-
-=item B<-U>
-X<-U>
-
-allows Perl to do unsafe operations. Currently the only "unsafe"
-operations are attempting to unlink directories while running as superuser
-and running setuid programs with fatal taint checks turned into warnings.
-Note that warnings must be enabled along with this option to actually
-I<generate> the taint-check warnings.
-
-=item B<-v>
-X<-v>
-
-prints the version and patchlevel of your perl executable.
-
-=item B<-V>
-X<-V>
-
-prints summary of the major perl configuration values and the current
-values of @INC.
-
-=item B<-V:>I<configvar>
-
-Prints to STDOUT the value of the named configuration variable(s),
-with multiples when your C<I<configvar>> argument looks like a regex (has
-non-letters). For example:
-
- $ perl -V:libc
- libc='/lib/libc-2.2.4.so';
- $ perl -V:lib.
- libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc';
- libc='/lib/libc-2.2.4.so';
- $ perl -V:lib.*
- libpth='/usr/local/lib /lib /usr/lib';
- libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc';
- lib_ext='.a';
- libc='/lib/libc-2.2.4.so';
- libperl='libperl.a';
- ....
-
-Additionally, extra colons can be used to control formatting. A
-trailing colon suppresses the linefeed and terminator ";", allowing
-you to embed queries into shell commands. (mnemonic: PATH separator
-":".)
-
- $ echo "compression-vars: " `perl -V:z.*: ` " are here !"
- compression-vars: zcat='' zip='zip' are here !
-
-A leading colon removes the "name=" part of the response, this allows
-you to map to the name you need. (mnemonic: empty label)
-
- $ echo "goodvfork="`./perl -Ilib -V::usevfork`
- goodvfork=false;
-
-Leading and trailing colons can be used together if you need
-positional parameter values without the names. Note that in the case
-below, the C<PERL_API> params are returned in alphabetical order.
-
- $ echo building_on `perl -V::osname: -V::PERL_API_.*:` now
- building_on 'linux' '5' '1' '9' now
-
-=item B<-w>
-X<-w>
-
-prints warnings about dubious constructs, such as variable names
-mentioned only once and scalar variables used
-before being set; redefined subroutines; references to undefined
-filehandles; filehandles opened read-only that you are attempting
-to write on; values used as a number that don't I<look> like numbers;
-using an array as though it were a scalar; if your subroutines
-recurse more than 100 deep; and innumerable other things.
-
-This switch really just enables the global C<$^W> variable; normally,
-the lexically scoped C<use warnings> pragma is preferred. You
-can disable or promote into fatal errors specific warnings using
-C<__WARN__> hooks, as described in L<perlvar> and L<perlfunc/warn>.
-See also L<perldiag> and L<perltrap>. A fine-grained warning
-facility is also available if you want to manipulate entire classes
-of warnings; see L<warnings> or L<perllexwarn>.
-
-=item B<-W>
-X<-W>
-
-Enables all warnings regardless of C<no warnings> or C<$^W>.
-See L<perllexwarn>.
-
-=item B<-X>
-X<-X>
-
-Disables all warnings regardless of C<use warnings> or C<$^W>.
-See L<perllexwarn>.
-
-=item B<-x>
-X<-x>
-
-=item B<-x>I<directory>
-
-tells Perl that the program is embedded in a larger chunk of unrelated
-text, such as in a mail message. Leading garbage will be
-discarded until the first line that starts with C<#!> and contains the
-string "perl". Any meaningful switches on that line will be applied.
-
-All references to line numbers by the program (warnings, errors, ...)
-will treat the C<#!> line as the first line.
-Thus a warning on the 2nd line of the program, which is on the 100th
-line in the file will be reported as line 2, not as line 100.
-This can be overridden by using the C<#line> directive.
-(See L<perlsyn/"Plain Old Comments (Not!)">)
-
-If a directory name is specified, Perl will switch to that directory
-before running the program. The B<-x> switch controls only the
-disposal of leading garbage. The program must be terminated with
-C<__END__> if there is trailing garbage to be ignored; the program
-can process any or all of the trailing garbage via the C<DATA> filehandle
-if desired.
-
-The directory, if specified, must appear immediately following the B<-x>
-with no intervening whitespace.
-
-=back
-
-=head1 ENVIRONMENT
-X<perl, environment variables>
-
-=over 12
-
-=item HOME
-X<HOME>
-
-Used if C<chdir> has no argument.
-
-=item LOGDIR
-X<LOGDIR>
-
-Used if C<chdir> has no argument and HOME is not set.
-
-=item PATH
-X<PATH>
-
-Used in executing subprocesses, and in finding the program if B<-S> is
-used.
-
-=item PERL5LIB
-X<PERL5LIB>
-
-A list of directories in which to look for Perl library
-files before looking in the standard library and the current
-directory. Any architecture-specific directories under the specified
-locations are automatically included if they exist, with this lookup
-done at interpreter startup time.
-
-If PERL5LIB is not defined, PERLLIB is used. Directories are separated
-(like in PATH) by a colon on Unixish platforms and by a semicolon on
-Windows (the proper path separator being given by the command C<perl
--V:I<path_sep>>).
-
-When running taint checks, either because the program was running setuid or
-setgid, or the B<-T> or B<-t> switch was specified, neither PERL5LIB nor
-PERLLIB is consulted. The program should instead say:
-
- use lib "/my/directory";
-
-=item PERL5OPT
-X<PERL5OPT>
-
-Command-line options (switches). Switches in this variable are treated
-as if they were on every Perl command line. Only the B<-[CDIMUdmtwW]>
-switches are allowed. When running taint checks (either because the
-program was running setuid or setgid, or because the B<-T> or B<-t>
-switch was used), this variable is ignored. If PERL5OPT begins with
-B<- T>, tainting will be enabled and subsequent options ignored. If
-PERL5OPT begins with B<-t>, tainting will be enabled, a writable dot
-removed from @INC, and subsequent options honored.
-
-=item PERLIO
-X<PERLIO>
-
-A space (or colon) separated list of PerlIO layers. If perl is built
-to use PerlIO system for IO (the default) these layers affect Perl's IO.
-
-It is conventional to start layer names with a colon (for example, C<:perlio>) to
-emphasize their similarity to variable "attributes". But the code that parses
-layer specification strings, which is also used to decode the PERLIO
-environment variable, treats the colon as a separator.
-
-An unset or empty PERLIO is equivalent to the default set of layers for
-your platform; for example, C<:unix:perlio> on Unix-like systems
-and C<:unix:crlf> on Windows and other DOS-like systems.
-
-The list becomes the default for I<all> Perl's IO. Consequently only built-in
-layers can appear in this list, as external layers (such as C<:encoding()>) need
-IO in order to load them!. See L<"open pragma"|open> for how to add external
-encodings as defaults.
-
-Layers it makes sense to include in the PERLIO environment
-variable are briefly summarized below. For more details see L<PerlIO>.
-
-=over 8
-
-=item :bytes
-X<:bytes>
-
-A pseudolayer that turns the C<:utf8> flag I<off> for the layer below;
-unlikely to be useful on its own in the global PERLIO environment variable.
-You perhaps were thinking of C<:crlf:bytes> or C<:perlio:bytes>.
-
-=item :crlf
-X<:crlf>
-
-A layer which does CRLF to C<"\n"> translation distinguishing "text" and
-"binary" files in the manner of MS-DOS and similar operating systems.
-(It currently does I<not> mimic MS-DOS as far as treating of Control-Z
-as being an end-of-file marker.)
-
-=item :mmap
-X<:mmap>
-
-A layer that implements "reading" of files by using I<mmap>(2) to
-make an entire file appear in the process's address space, and then
-using that as PerlIO's "buffer".
-
-=item :perlio
-X<:perlio>
-
-This is a re-implementation of stdio-like buffering written as a
-PerlIO layer. As such it will call whatever layer is below it for
-its operations, typically C<:unix>.
-
-=item :pop
-X<:pop>
-
-An experimental pseudolayer that removes the topmost layer.
-Use with the same care as is reserved for nitroglycerine.
-
-=item :raw
-X<:raw>
-
-A pseudolayer that manipulates other layers. Applying the C<:raw>
-layer is equivalent to calling C<binmode($fh)>. It makes the stream
-pass each byte as-is without translation. In particular, both CRLF
-translation and intuiting C<:utf8> from the locale are disabled.
-
-Unlike in earlier versions of Perl, C<:raw> is I<not>
-just the inverse of C<:crlf>: other layers which would affect the
-binary nature of the stream are also removed or disabled.
-
-=item :stdio
-X<:stdio>
-
-This layer provides a PerlIO interface by wrapping system's ANSI C "stdio"
-library calls. The layer provides both buffering and IO.
-Note that the C<:stdio> layer does I<not> do CRLF translation even if that
-is the platform's normal behaviour. You will need a C<:crlf> layer above it
-to do that.
-
-=item :unix
-X<:unix>
-
-Low-level layer that calls C<read>, C<write>, C<lseek>, etc.
-
-=item :utf8
-X<:utf8>
-
-A pseudolayer that enables a flag in the layer below to tell Perl
-that output should be in utf8 and that input should be regarded as
-already in valid utf8 form. B<WARNING: It does not check for validity and as such
-should be handled with extreme caution for input, because security violations
-can occur with non-shortest UTF-8 encodings, etc.> Generally C<:encoding(utf8)> is
-the best option when reading UTF-8 encoded data.
-
-=item :win32
-X<:win32>
-
-On Win32 platforms this I<experimental> layer uses native "handle" IO
-rather than a Unix-like numeric file descriptor layer. Known to be
-buggy in this release (5.14).
-
-=back
-
-The default set of layers should give acceptable results on all platforms
-
-For Unix platforms that will be the equivalent of "unix perlio" or "stdio".
-Configure is set up to prefer the "stdio" implementation if the system's library
-provides for fast access to the buffer; otherwise, it uses the "unix perlio"
-implementation.
-
-On Win32 the default in this release (5.14) is "unix crlf". Win32's "stdio"
-has a number of bugs/mis-features for Perl IO which are somewhat depending
-on the version and vendor of the C compiler. Using our own C<crlf> layer as
-the buffer avoids those issues and makes things more uniform. The C<crlf>
-layer provides CRLF conversion as well as buffering.
-
-This release (5.14) uses C<unix> as the bottom layer on Win32, and so still
-uses the C compiler's numeric file descriptor routines. There is an
-experimental native C<win32> layer, which is expected to be enhanced and
-should eventually become the default under Win32.
-
-The PERLIO environment variable is completely ignored when Perl
-is run in taint mode.
-
-=item PERLIO_DEBUG
-X<PERLIO_DEBUG>
-
-If set to the name of a file or device, certain operations of PerlIO
-subsystem will be logged to that file, which is opened in append mode
-Typical uses are in Unix:
-
- % env PERLIO_DEBUG=/dev/tty perl script ...
-
-and under Win32, the approximately equivalent:
-
- > set PERLIO_DEBUG=CON
- perl script ...
-
-This functionality is disabled for setuid scripts and for scripts run
-with B<-T>.
-
-=item PERLLIB
-X<PERLLIB>
-
-A list of directories in which to look for Perl library
-files before looking in the standard library and the current directory.
-If PERL5LIB is defined, PERLLIB is not used.
-
-The PERLLIB environment variable is completely ignored when Perl
-is run in taint mode.
-
-=item PERL5DB
-X<PERL5DB>
-
-The command used to load the debugger code. The default is:
-
- BEGIN { require "perl5db.pl" }
-
-The PERL5DB environment variable is only used when Perl is started with
-a bare B<-d> switch.
-
-=item PERL5DB_THREADED
-X<PERL5DB_THREADED>
-
-If set to a true value, indicates to the debugger that the code being
-debugged uses threads.
-
-=item PERL5SHELL (specific to the Win32 port)
-X<PERL5SHELL>
-
-On Win32 ports only, may be set to an alternative shell that Perl must use
-internally for executing "backtick" commands or system(). Default is
-C<cmd.exe /x/d/c> on WindowsNT and C<command.com /c> on Windows95. The
-value is considered space-separated. Precede any character that
-needs to be protected, like a space or backslash, with another backslash.
-
-Note that Perl doesn't use COMSPEC for this purpose because
-COMSPEC has a high degree of variability among users, leading to
-portability concerns. Besides, Perl can use a shell that may not be
-fit for interactive use, and setting COMSPEC to such a shell may
-interfere with the proper functioning of other programs (which usually
-look in COMSPEC to find a shell fit for interactive use).
-
-Before Perl 5.10.0 and 5.8.8, PERL5SHELL was not taint checked
-when running external commands. It is recommended that
-you explicitly set (or delete) C<$ENV{PERL5SHELL}> when running
-in taint mode under Windows.
-
-=item PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)
-X<PERL_ALLOW_NON_IFS_LSP>
-
-Set to 1 to allow the use of non-IFS compatible LSPs (Layered Service Providers).
-Perl normally searches for an IFS-compatible LSP because this is required
-for its emulation of Windows sockets as real filehandles. However, this may
-cause problems if you have a firewall such as I<McAfee Guardian>, which requires
-that all applications use its LSP but which is not IFS-compatible, because clearly
-Perl will normally avoid using such an LSP.
-
-Setting this environment variable to 1 means that Perl will simply use the
-first suitable LSP enumerated in the catalog, which keeps I<McAfee Guardian>
-happy--and in that particular case Perl still works too because I<McAfee
-Guardian>'s LSP actually plays other games which allow applications
-requiring IFS compatibility to work.
-
-=item PERL_DEBUG_MSTATS
-X<PERL_DEBUG_MSTATS>
-
-Relevant only if Perl is compiled with the C<malloc> included with the Perl
-distribution; that is, if C<perl -V:d_mymalloc> is "define".
-
-If set, this dumps out memory statistics after execution. If set
-to an integer greater than one, also dumps out memory statistics
-after compilation.
-
-=item PERL_DESTRUCT_LEVEL
-X<PERL_DESTRUCT_LEVEL>
-
-Relevant only if your Perl executable was built with B<-DDEBUGGING>,
-this controls the behaviour of global destruction of objects and other
-references. See L<perlhacktips/PERL_DESTRUCT_LEVEL> for more information.
-
-=item PERL_DL_NONLAZY
-X<PERL_DL_NONLAZY>
-
-Set to C<"1"> to have Perl resolve I<all> undefined symbols when it loads
-a dynamic library. The default behaviour is to resolve symbols when
-they are used. Setting this variable is useful during testing of
-extensions, as it ensures that you get an error on misspelled function
-names even if the test suite doesn't call them.
-
-=item PERL_ENCODING
-X<PERL_ENCODING>
-
-If using the C<use encoding> pragma without an explicit encoding name, the
-PERL_ENCODING environment variable is consulted for an encoding name.
-
-=item PERL_HASH_SEED
-X<PERL_HASH_SEED>
-
-(Since Perl 5.8.1.) Used to randomize Perl's internal hash function.
-To emulate the pre-5.8.1 behaviour, set to an integer; C<"0"> means
-exactly the same order as in 5.8.0. "Pre-5.8.1" means, among other
-things, that hash keys will always have the same ordering between
-different runs of Perl.
-
-Most hashes by default return elements in the same order as in Perl 5.8.0.
-On a hash by hash basis, if pathological data is detected during a hash
-key insertion, then that hash will switch to an alternative random hash
-seed.
-
-The default behaviour is to randomize unless the PERL_HASH_SEED is set.
-If Perl has been compiled with B<-DUSE_HASH_SEED_EXPLICIT>, the default
-behaviour is I<not> to randomize unless the PERL_HASH_SEED is set.
-
-If PERL_HASH_SEED is unset or set to a non-numeric string, Perl uses
-the pseudorandom seed supplied by the operating system and libraries.
-
-B<PLEASE NOTE: The hash seed is sensitive information>. Hashes are
-randomized to protect against local and remote attacks against Perl
-code. By manually setting a seed, this protection may be partially or
-completely lost.
-
-See L<perlsec/"Algorithmic Complexity Attacks"> and
-L</PERL_HASH_SEED_DEBUG> for more information.
-
-=item PERL_HASH_SEED_DEBUG
-X<PERL_HASH_SEED_DEBUG>
-
-(Since Perl 5.8.1.) Set to C<"1"> to display (to STDERR) the value of
-the hash seed at the beginning of execution. This, combined with
-L</PERL_HASH_SEED> is intended to aid in debugging nondeterministic
-behaviour caused by hash randomization.
-
-B<Note that the hash seed is sensitive information>: by knowing it, one
-can craft a denial-of-service attack against Perl code, even remotely;
-see L<perlsec/"Algorithmic Complexity Attacks"> for more information.
-B<Do not disclose the hash seed> to people who don't need to know it.
-See also hash_seed() in L<Hash::Util>.
-
-=item PERL_MEM_LOG
-X<PERL_MEM_LOG>
-
-If your Perl was configured with B<-Accflags=-DPERL_MEM_LOG>, setting
-the environment variable C<PERL_MEM_LOG> enables logging debug
-messages. The value has the form C<< <I<number>>[m][s][t] >>, where
-C<I<number>> is the file descriptor number you want to write to (2 is
-default), and the combination of letters specifies that you want
-information about (m)emory and/or (s)v, optionally with
-(t)imestamps. For example, C<PERL_MEM_LOG=1mst> logs all
-information to stdout. You can write to other opened file descriptors
-in a variety of ways:
-
- $ 3>foo3 PERL_MEM_LOG=3m perl ...
-
-=item PERL_ROOT (specific to the VMS port)
-X<PERL_ROOT>
-
-A translation-concealed rooted logical name that contains Perl and the
-logical device for the @INC path on VMS only. Other logical names that
-affect Perl on VMS include PERLSHR, PERL_ENV_TABLES, and
-SYS$TIMEZONE_DIFFERENTIAL, but are optional and discussed further in
-L<perlvms> and in F<README.vms> in the Perl source distribution.
-
-=item PERL_SIGNALS
-X<PERL_SIGNALS>
-
-Available in Perls 5.8.1 and later. If set to C<"unsafe">, the pre-Perl-5.8.0
-signal behaviour (which is immediate but unsafe) is restored. If set
-to C<safe>, then safe (but deferred) signals are used. See
-L<perlipc/"Deferred Signals (Safe Signals)">.
-
-=item PERL_UNICODE
-X<PERL_UNICODE>
-
-Equivalent to the B<-C> command-line switch. Note that this is not
-a boolean variable. Setting this to C<"1"> is not the right way to
-"enable Unicode" (whatever that would mean). You can use C<"0"> to
-"disable Unicode", though (or alternatively unset PERL_UNICODE in
-your shell before starting Perl). See the description of the B<-C>
-switch for more information.
-
-=item SYS$LOGIN (specific to the VMS port)
-X<SYS$LOGIN>
-
-Used if chdir has no argument and HOME and LOGDIR are not set.
-
-=back
-
-Perl also has environment variables that control how Perl handles data
-specific to particular natural languages; see L<perllocale>.
-
-Perl and its various modules and components, including its test frameworks,
-may sometimes make use of certain other environment variables. Some of
-these are specific to a particular platform. Please consult the
-appropriate module documentation and any documentation for your platform
-(like L<perlsolaris>, L<perllinux>, L<perlmacosx>, L<perlwin32>, etc) for
-variables peculiar to those specific situations.
-
-Perl makes all environment variables available to the program being
-executed, and passes these along to any child processes it starts.
-However, programs running setuid would do well to execute the following
-lines before doing anything else, just to keep people honest:
-
- $ENV{PATH} = "/bin:/usr/bin"; # or whatever you need
- $ENV{SHELL} = "/bin/sh" if exists $ENV{SHELL};
- delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};
diff --git a/Master/tlpkg/tlperl/lib/pods/perlsec.pod b/Master/tlpkg/tlperl/lib/pods/perlsec.pod
deleted file mode 100644
index d8470eccccb..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlsec.pod
+++ /dev/null
@@ -1,521 +0,0 @@
-=head1 NAME
-
-perlsec - Perl security
-
-=head1 DESCRIPTION
-
-Perl is designed to make it easy to program securely even when running
-with extra privileges, like setuid or setgid programs. Unlike most
-command line shells, which are based on multiple substitution passes on
-each line of the script, Perl uses a more conventional evaluation scheme
-with fewer hidden snags. Additionally, because the language has more
-builtin functionality, it can rely less upon external (and possibly
-untrustworthy) programs to accomplish its purposes.
-
-=head1 SECURITY VULNERABILITY CONTACT INFORMATION
-
-If you believe you have found a security vulnerability in Perl, please email
-perl5-security-report@perl.org with details. This points to a closed
-subscription, unarchived mailing list. Please only use this address for
-security issues in the Perl core, not for modules independently distributed on
-CPAN.
-
-=head1 SECURITY MECHANISMS AND CONCERNS
-
-=head2 Taint mode
-
-Perl automatically enables a set of special security checks, called I<taint
-mode>, when it detects its program running with differing real and effective
-user or group IDs. The setuid bit in Unix permissions is mode 04000, the
-setgid bit mode 02000; either or both may be set. You can also enable taint
-mode explicitly by using the B<-T> command line flag. This flag is
-I<strongly> suggested for server programs and any program run on behalf of
-someone else, such as a CGI script. Once taint mode is on, it's on for
-the remainder of your script.
-
-While in this mode, Perl takes special precautions called I<taint
-checks> to prevent both obvious and subtle traps. Some of these checks
-are reasonably simple, such as verifying that path directories aren't
-writable by others; careful programmers have always used checks like
-these. Other checks, however, are best supported by the language itself,
-and it is these checks especially that contribute to making a set-id Perl
-program more secure than the corresponding C program.
-
-You may not use data derived from outside your program to affect
-something else outside your program--at least, not by accident. All
-command line arguments, environment variables, locale information (see
-L<perllocale>), results of certain system calls (C<readdir()>,
-C<readlink()>, the variable of C<shmread()>, the messages returned by
-C<msgrcv()>, the password, gcos and shell fields returned by the
-C<getpwxxx()> calls), and all file input are marked as "tainted".
-Tainted data may not be used directly or indirectly in any command
-that invokes a sub-shell, nor in any command that modifies files,
-directories, or processes, B<with the following exceptions>:
-
-=over 4
-
-=item *
-
-Arguments to C<print> and C<syswrite> are B<not> checked for taintedness.
-
-=item *
-
-Symbolic methods
-
- $obj->$method(@args);
-
-and symbolic sub references
-
- &{$foo}(@args);
- $foo->(@args);
-
-are not checked for taintedness. This requires extra carefulness
-unless you want external data to affect your control flow. Unless
-you carefully limit what these symbolic values are, people are able
-to call functions B<outside> your Perl code, such as POSIX::system,
-in which case they are able to run arbitrary external code.
-
-=item *
-
-Hash keys are B<never> tainted.
-
-=back
-
-For efficiency reasons, Perl takes a conservative view of
-whether data is tainted. If an expression contains tainted data,
-any subexpression may be considered tainted, even if the value
-of the subexpression is not itself affected by the tainted data.
-
-Because taintedness is associated with each scalar value, some
-elements of an array or hash can be tainted and others not.
-The keys of a hash are B<never> tainted.
-
-For example:
-
- $arg = shift; # $arg is tainted
- $hid = $arg, 'bar'; # $hid is also tainted
- $line = <>; # Tainted
- $line = <STDIN>; # Also tainted
- open FOO, "/home/me/bar" or die $!;
- $line = <FOO>; # Still tainted
- $path = $ENV{'PATH'}; # Tainted, but see below
- $data = 'abc'; # Not tainted
-
- system "echo $arg"; # Insecure
- system "/bin/echo", $arg; # Considered insecure
- # (Perl doesn't know about /bin/echo)
- system "echo $hid"; # Insecure
- system "echo $data"; # Insecure until PATH set
-
- $path = $ENV{'PATH'}; # $path now tainted
-
- $ENV{'PATH'} = '/bin:/usr/bin';
- delete @ENV{'IFS', 'CDPATH', 'ENV', 'BASH_ENV'};
-
- $path = $ENV{'PATH'}; # $path now NOT tainted
- system "echo $data"; # Is secure now!
-
- open(FOO, "< $arg"); # OK - read-only file
- open(FOO, "> $arg"); # Not OK - trying to write
-
- open(FOO,"echo $arg|"); # Not OK
- open(FOO,"-|")
- or exec 'echo', $arg; # Also not OK
-
- $shout = `echo $arg`; # Insecure, $shout now tainted
-
- unlink $data, $arg; # Insecure
- umask $arg; # Insecure
-
- exec "echo $arg"; # Insecure
- exec "echo", $arg; # Insecure
- exec "sh", '-c', $arg; # Very insecure!
-
- @files = <*.c>; # insecure (uses readdir() or similar)
- @files = glob('*.c'); # insecure (uses readdir() or similar)
-
- # In Perl releases older than 5.6.0 the <*.c> and glob('*.c') would
- # have used an external program to do the filename expansion; but in
- # either case the result is tainted since the list of filenames comes
- # from outside of the program.
-
- $bad = ($arg, 23); # $bad will be tainted
- $arg, `true`; # Insecure (although it isn't really)
-
-If you try to do something insecure, you will get a fatal error saying
-something like "Insecure dependency" or "Insecure $ENV{PATH}".
-
-The exception to the principle of "one tainted value taints the whole
-expression" is with the ternary conditional operator C<?:>. Since code
-with a ternary conditional
-
- $result = $tainted_value ? "Untainted" : "Also untainted";
-
-is effectively
-
- if ( $tainted_value ) {
- $result = "Untainted";
- } else {
- $result = "Also untainted";
- }
-
-it doesn't make sense for C<$result> to be tainted.
-
-=head2 Laundering and Detecting Tainted Data
-
-To test whether a variable contains tainted data, and whose use would
-thus trigger an "Insecure dependency" message, you can use the
-C<tainted()> function of the Scalar::Util module, available in your
-nearby CPAN mirror, and included in Perl starting from the release 5.8.0.
-Or you may be able to use the following C<is_tainted()> function.
-
- sub is_tainted {
- local $@; # Don't pollute caller's value.
- return ! eval { eval("#" . substr(join("", @_), 0, 0)); 1 };
- }
-
-This function makes use of the fact that the presence of tainted data
-anywhere within an expression renders the entire expression tainted. It
-would be inefficient for every operator to test every argument for
-taintedness. Instead, the slightly more efficient and conservative
-approach is used that if any tainted value has been accessed within the
-same expression, the whole expression is considered tainted.
-
-But testing for taintedness gets you only so far. Sometimes you have just
-to clear your data's taintedness. Values may be untainted by using them
-as keys in a hash; otherwise the only way to bypass the tainting
-mechanism is by referencing subpatterns from a regular expression match.
-Perl presumes that if you reference a substring using $1, $2, etc., that
-you knew what you were doing when you wrote the pattern. That means using
-a bit of thought--don't just blindly untaint anything, or you defeat the
-entire mechanism. It's better to verify that the variable has only good
-characters (for certain values of "good") rather than checking whether it
-has any bad characters. That's because it's far too easy to miss bad
-characters that you never thought of.
-
-Here's a test to make sure that the data contains nothing but "word"
-characters (alphabetics, numerics, and underscores), a hyphen, an at sign,
-or a dot.
-
- if ($data =~ /^([-\@\w.]+)$/) {
- $data = $1; # $data now untainted
- } else {
- die "Bad data in '$data'"; # log this somewhere
- }
-
-This is fairly secure because C</\w+/> doesn't normally match shell
-metacharacters, nor are dot, dash, or at going to mean something special
-to the shell. Use of C</.+/> would have been insecure in theory because
-it lets everything through, but Perl doesn't check for that. The lesson
-is that when untainting, you must be exceedingly careful with your patterns.
-Laundering data using regular expression is the I<only> mechanism for
-untainting dirty data, unless you use the strategy detailed below to fork
-a child of lesser privilege.
-
-The example does not untaint C<$data> if C<use locale> is in effect,
-because the characters matched by C<\w> are determined by the locale.
-Perl considers that locale definitions are untrustworthy because they
-contain data from outside the program. If you are writing a
-locale-aware program, and want to launder data with a regular expression
-containing C<\w>, put C<no locale> ahead of the expression in the same
-block. See L<perllocale/SECURITY> for further discussion and examples.
-
-=head2 Switches On the "#!" Line
-
-When you make a script executable, in order to make it usable as a
-command, the system will pass switches to perl from the script's #!
-line. Perl checks that any command line switches given to a setuid
-(or setgid) script actually match the ones set on the #! line. Some
-Unix and Unix-like environments impose a one-switch limit on the #!
-line, so you may need to use something like C<-wU> instead of C<-w -U>
-under such systems. (This issue should arise only in Unix or
-Unix-like environments that support #! and setuid or setgid scripts.)
-
-=head2 Taint mode and @INC
-
-When the taint mode (C<-T>) is in effect, the "." directory is removed
-from C<@INC>, and the environment variables C<PERL5LIB> and C<PERLLIB>
-are ignored by Perl. You can still adjust C<@INC> from outside the
-program by using the C<-I> command line option as explained in
-L<perlrun>. The two environment variables are ignored because
-they are obscured, and a user running a program could be unaware that
-they are set, whereas the C<-I> option is clearly visible and
-therefore permitted.
-
-Another way to modify C<@INC> without modifying the program, is to use
-the C<lib> pragma, e.g.:
-
- perl -Mlib=/foo program
-
-The benefit of using C<-Mlib=/foo> over C<-I/foo>, is that the former
-will automagically remove any duplicated directories, while the later
-will not.
-
-Note that if a tainted string is added to C<@INC>, the following
-problem will be reported:
-
- Insecure dependency in require while running with -T switch
-
-=head2 Cleaning Up Your Path
-
-For "Insecure C<$ENV{PATH}>" messages, you need to set C<$ENV{'PATH'}> to
-a known value, and each directory in the path must be absolute and
-non-writable by others than its owner and group. You may be surprised to
-get this message even if the pathname to your executable is fully
-qualified. This is I<not> generated because you didn't supply a full path
-to the program; instead, it's generated because you never set your PATH
-environment variable, or you didn't set it to something that was safe.
-Because Perl can't guarantee that the executable in question isn't itself
-going to turn around and execute some other program that is dependent on
-your PATH, it makes sure you set the PATH.
-
-The PATH isn't the only environment variable which can cause problems.
-Because some shells may use the variables IFS, CDPATH, ENV, and
-BASH_ENV, Perl checks that those are either empty or untainted when
-starting subprocesses. You may wish to add something like this to your
-setid and taint-checking scripts.
-
- delete @ENV{qw(IFS CDPATH ENV BASH_ENV)}; # Make %ENV safer
-
-It's also possible to get into trouble with other operations that don't
-care whether they use tainted values. Make judicious use of the file
-tests in dealing with any user-supplied filenames. When possible, do
-opens and such B<after> properly dropping any special user (or group!)
-privileges. Perl doesn't prevent you from opening tainted filenames for reading,
-so be careful what you print out. The tainting mechanism is intended to
-prevent stupid mistakes, not to remove the need for thought.
-
-Perl does not call the shell to expand wild cards when you pass C<system>
-and C<exec> explicit parameter lists instead of strings with possible shell
-wildcards in them. Unfortunately, the C<open>, C<glob>, and
-backtick functions provide no such alternate calling convention, so more
-subterfuge will be required.
-
-Perl provides a reasonably safe way to open a file or pipe from a setuid
-or setgid program: just create a child process with reduced privilege who
-does the dirty work for you. First, fork a child using the special
-C<open> syntax that connects the parent and child by a pipe. Now the
-child resets its ID set and any other per-process attributes, like
-environment variables, umasks, current working directories, back to the
-originals or known safe values. Then the child process, which no longer
-has any special permissions, does the C<open> or other system call.
-Finally, the child passes the data it managed to access back to the
-parent. Because the file or pipe was opened in the child while running
-under less privilege than the parent, it's not apt to be tricked into
-doing something it shouldn't.
-
-Here's a way to do backticks reasonably safely. Notice how the C<exec> is
-not called with a string that the shell could expand. This is by far the
-best way to call something that might be subjected to shell escapes: just
-never call the shell at all.
-
- use English '-no_match_vars';
- die "Can't fork: $!" unless defined($pid = open(KID, "-|"));
- if ($pid) { # parent
- while (<KID>) {
- # do something
- }
- close KID;
- } else {
- my @temp = ($EUID, $EGID);
- my $orig_uid = $UID;
- my $orig_gid = $GID;
- $EUID = $UID;
- $EGID = $GID;
- # Drop privileges
- $UID = $orig_uid;
- $GID = $orig_gid;
- # Make sure privs are really gone
- ($EUID, $EGID) = @temp;
- die "Can't drop privileges"
- unless $UID == $EUID && $GID eq $EGID;
- $ENV{PATH} = "/bin:/usr/bin"; # Minimal PATH.
- # Consider sanitizing the environment even more.
- exec 'myprog', 'arg1', 'arg2'
- or die "can't exec myprog: $!";
- }
-
-A similar strategy would work for wildcard expansion via C<glob>, although
-you can use C<readdir> instead.
-
-Taint checking is most useful when although you trust yourself not to have
-written a program to give away the farm, you don't necessarily trust those
-who end up using it not to try to trick it into doing something bad. This
-is the kind of security checking that's useful for set-id programs and
-programs launched on someone else's behalf, like CGI programs.
-
-This is quite different, however, from not even trusting the writer of the
-code not to try to do something evil. That's the kind of trust needed
-when someone hands you a program you've never seen before and says, "Here,
-run this." For that kind of safety, you might want to check out the Safe
-module, included standard in the Perl distribution. This module allows the
-programmer to set up special compartments in which all system operations
-are trapped and namespace access is carefully controlled. Safe should
-not be considered bullet-proof, though: it will not prevent the foreign
-code to set up infinite loops, allocate gigabytes of memory, or even
-abusing perl bugs to make the host interpreter crash or behave in
-unpredictable ways. In any case it's better avoided completely if you're
-really concerned about security.
-
-=head2 Security Bugs
-
-Beyond the obvious problems that stem from giving special privileges to
-systems as flexible as scripts, on many versions of Unix, set-id scripts
-are inherently insecure right from the start. The problem is a race
-condition in the kernel. Between the time the kernel opens the file to
-see which interpreter to run and when the (now-set-id) interpreter turns
-around and reopens the file to interpret it, the file in question may have
-changed, especially if you have symbolic links on your system.
-
-Fortunately, sometimes this kernel "feature" can be disabled.
-Unfortunately, there are two ways to disable it. The system can simply
-outlaw scripts with any set-id bit set, which doesn't help much.
-Alternately, it can simply ignore the set-id bits on scripts.
-
-However, if the kernel set-id script feature isn't disabled, Perl will
-complain loudly that your set-id script is insecure. You'll need to
-either disable the kernel set-id script feature, or put a C wrapper around
-the script. A C wrapper is just a compiled program that does nothing
-except call your Perl program. Compiled programs are not subject to the
-kernel bug that plagues set-id scripts. Here's a simple wrapper, written
-in C:
-
- #define REAL_PATH "/path/to/script"
- main(ac, av)
- char **av;
- {
- execv(REAL_PATH, av);
- }
-
-Compile this wrapper into a binary executable and then make I<it> rather
-than your script setuid or setgid.
-
-In recent years, vendors have begun to supply systems free of this
-inherent security bug. On such systems, when the kernel passes the name
-of the set-id script to open to the interpreter, rather than using a
-pathname subject to meddling, it instead passes I</dev/fd/3>. This is a
-special file already opened on the script, so that there can be no race
-condition for evil scripts to exploit. On these systems, Perl should be
-compiled with C<-DSETUID_SCRIPTS_ARE_SECURE_NOW>. The F<Configure>
-program that builds Perl tries to figure this out for itself, so you
-should never have to specify this yourself. Most modern releases of
-SysVr4 and BSD 4.4 use this approach to avoid the kernel race condition.
-
-=head2 Protecting Your Programs
-
-There are a number of ways to hide the source to your Perl programs,
-with varying levels of "security".
-
-First of all, however, you I<can't> take away read permission, because
-the source code has to be readable in order to be compiled and
-interpreted. (That doesn't mean that a CGI script's source is
-readable by people on the web, though.) So you have to leave the
-permissions at the socially friendly 0755 level. This lets
-people on your local system only see your source.
-
-Some people mistakenly regard this as a security problem. If your program does
-insecure things, and relies on people not knowing how to exploit those
-insecurities, it is not secure. It is often possible for someone to
-determine the insecure things and exploit them without viewing the
-source. Security through obscurity, the name for hiding your bugs
-instead of fixing them, is little security indeed.
-
-You can try using encryption via source filters (Filter::* from CPAN,
-or Filter::Util::Call and Filter::Simple since Perl 5.8).
-But crackers might be able to decrypt it. You can try using the byte
-code compiler and interpreter described below, but crackers might be
-able to de-compile it. You can try using the native-code compiler
-described below, but crackers might be able to disassemble it. These
-pose varying degrees of difficulty to people wanting to get at your
-code, but none can definitively conceal it (this is true of every
-language, not just Perl).
-
-If you're concerned about people profiting from your code, then the
-bottom line is that nothing but a restrictive license will give you
-legal security. License your software and pepper it with threatening
-statements like "This is unpublished proprietary software of XYZ Corp.
-Your access to it does not give you permission to use it blah blah
-blah." You should see a lawyer to be sure your license's wording will
-stand up in court.
-
-=head2 Unicode
-
-Unicode is a new and complex technology and one may easily overlook
-certain security pitfalls. See L<perluniintro> for an overview and
-L<perlunicode> for details, and L<perlunicode/"Security Implications
-of Unicode"> for security implications in particular.
-
-=head2 Algorithmic Complexity Attacks
-
-Certain internal algorithms used in the implementation of Perl can
-be attacked by choosing the input carefully to consume large amounts
-of either time or space or both. This can lead into the so-called
-I<Denial of Service> (DoS) attacks.
-
-=over 4
-
-=item *
-
-Hash Function - the algorithm used to "order" hash elements has been
-changed several times during the development of Perl, mainly to be
-reasonably fast. In Perl 5.8.1 also the security aspect was taken
-into account.
-
-In Perls before 5.8.1 one could rather easily generate data that as
-hash keys would cause Perl to consume large amounts of time because
-internal structure of hashes would badly degenerate. In Perl 5.8.1
-the hash function is randomly perturbed by a pseudorandom seed which
-makes generating such naughty hash keys harder.
-See L<perlrun/PERL_HASH_SEED> for more information.
-
-In Perl 5.8.1 the random perturbation was done by default, but as of
-5.8.2 it is only used on individual hashes if the internals detect the
-insertion of pathological data. If one wants for some reason emulate the
-old behaviour (and expose oneself to DoS attacks) one can set the
-environment variable PERL_HASH_SEED to zero to disable the protection
-(or any other integer to force a known perturbation, rather than random).
-One possible reason for wanting to emulate the old behaviour is that in the
-new behaviour consecutive runs of Perl will order hash keys differently,
-which may confuse some applications (like Data::Dumper: the outputs of two
-different runs are no longer identical).
-
-B<Perl has never guaranteed any ordering of the hash keys>, and the
-ordering has already changed several times during the lifetime of
-Perl 5. Also, the ordering of hash keys has always been, and
-continues to be, affected by the insertion order.
-
-Also note that while the order of the hash elements might be
-randomised, this "pseudoordering" should B<not> be used for
-applications like shuffling a list randomly (use List::Util::shuffle()
-for that, see L<List::Util>, a standard core module since Perl 5.8.0;
-or the CPAN module Algorithm::Numerical::Shuffle), or for generating
-permutations (use e.g. the CPAN modules Algorithm::Permute or
-Algorithm::FastPermute), or for any cryptographic applications.
-
-=item *
-
-Regular expressions - Perl's regular expression engine is so called NFA
-(Non-deterministic Finite Automaton), which among other things means that
-it can rather easily consume large amounts of both time and space if the
-regular expression may match in several ways. Careful crafting of the
-regular expressions can help but quite often there really isn't much
-one can do (the book "Mastering Regular Expressions" is required
-reading, see L<perlfaq2>). Running out of space manifests itself by
-Perl running out of memory.
-
-=item *
-
-Sorting - the quicksort algorithm used in Perls before 5.8.0 to
-implement the sort() function is very easy to trick into misbehaving
-so that it consumes a lot of time. Starting from Perl 5.8.0 a different
-sorting algorithm, mergesort, is used by default. Mergesort cannot
-misbehave on any input.
-
-=back
-
-See L<http://www.cs.rice.edu/~scrosby/hash/> for more information,
-and any computer science textbook on algorithmic complexity.
-
-=head1 SEE ALSO
-
-L<perlrun> for its description of cleaning up environment variables.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlsolaris.pod b/Master/tlpkg/tlperl/lib/pods/perlsolaris.pod
deleted file mode 100644
index 0e6ffd9a9fb..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlsolaris.pod
+++ /dev/null
@@ -1,697 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see pod/perlpod.pod) which is
-specifically designed to be readable as is.
-
-=head1 NAME
-
-perlsolaris - Perl version 5 on Solaris systems
-
-=head1 DESCRIPTION
-
-This document describes various features of Sun's Solaris operating system
-that will affect how Perl version 5 (hereafter just perl) is
-compiled and/or runs. Some issues relating to the older SunOS 4.x are
-also discussed, though they may be out of date.
-
-For the most part, everything should just work.
-
-Starting with Solaris 8, perl5.00503 (or higher) is supplied with the
-operating system, so you might not even need to build a newer version
-of perl at all. The Sun-supplied version is installed in /usr/perl5
-with F</usr/bin/perl> pointing to F</usr/perl5/bin/perl>. Do not disturb
-that installation unless you really know what you are doing. If you
-remove the perl supplied with the OS, you will render some bits of
-your system inoperable. If you wish to install a newer version of perl,
-install it under a different prefix from /usr/perl5. Common prefixes
-to use are /usr/local and /opt/perl.
-
-You may wish to put your version of perl in the PATH of all users by
-changing the link F</usr/bin/perl>. This is probably OK, as most perl
-scripts shipped with Solaris use an explicit path. (There are a few
-exceptions, such as F</usr/bin/rpm2cpio> and F</etc/rcm/scripts/README>, but
-these are also sufficiently generic that the actual version of perl
-probably doesn't matter too much.)
-
-Solaris ships with a range of Solaris-specific modules. If you choose
-to install your own version of perl you will find the source of many of
-these modules is available on CPAN under the Sun::Solaris:: namespace.
-
-Solaris may include two versions of perl, e.g. Solaris 9 includes
-both 5.005_03 and 5.6.1. This is to provide stability across Solaris
-releases, in cases where a later perl version has incompatibilities
-with the version included in the preceding Solaris release. The
-default perl version will always be the most recent, and in general
-the old version will only be retained for one Solaris release. Note
-also that the default perl will NOT be configured to search for modules
-in the older version, again due to compatibility/stability concerns.
-As a consequence if you upgrade Solaris, you will have to
-rebuild/reinstall any additional CPAN modules that you installed for
-the previous Solaris version. See the CPAN manpage under 'autobundle'
-for a quick way of doing this.
-
-As an interim measure, you may either change the #! line of your
-scripts to specifically refer to the old perl version, e.g. on
-Solaris 9 use #!/usr/perl5/5.00503/bin/perl to use the perl version
-that was the default for Solaris 8, or if you have a large number of
-scripts it may be more convenient to make the old version of perl the
-default on your system. You can do this by changing the appropriate
-symlinks under /usr/perl5 as follows (example for Solaris 9):
-
- # cd /usr/perl5
- # rm bin man pod
- # ln -s ./5.00503/bin
- # ln -s ./5.00503/man
- # ln -s ./5.00503/lib/pod
- # rm /usr/bin/perl
- # ln -s ../perl5/5.00503/bin/perl /usr/bin/perl
-
-In both cases this should only be considered to be a temporary
-measure - you should upgrade to the later version of perl as soon as
-is practicable.
-
-Note also that the perl command-line utilities (e.g. perldoc) and any
-that are added by modules that you install will be under
-/usr/perl5/bin, so that directory should be added to your PATH.
-
-=head2 Solaris Version Numbers.
-
-For consistency with common usage, perl's Configure script performs
-some minor manipulations on the operating system name and version
-number as reported by uname. Here's a partial translation table:
-
- Sun: perl's Configure:
- uname uname -r Name osname osvers
- SunOS 4.1.3 Solaris 1.1 sunos 4.1.3
- SunOS 5.6 Solaris 2.6 solaris 2.6
- SunOS 5.8 Solaris 8 solaris 2.8
- SunOS 5.9 Solaris 9 solaris 2.9
- SunOS 5.10 Solaris 10 solaris 2.10
-
-The complete table can be found in the Sun Managers' FAQ
-L<ftp://ftp.cs.toronto.edu/pub/jdd/sunmanagers/faq> under
-"9.1) Which Sun models run which versions of SunOS?".
-
-=head1 RESOURCES
-
-There are many, many sources for Solaris information. A few of the
-important ones for perl:
-
-=over 4
-
-=item Solaris FAQ
-
-The Solaris FAQ is available at
-L<http://www.science.uva.nl/pub/solaris/solaris2.html>.
-
-The Sun Managers' FAQ is available at
-L<ftp://ftp.cs.toronto.edu/pub/jdd/sunmanagers/faq>
-
-=item Precompiled Binaries
-
-Precompiled binaries, links to many sites, and much, much more are
-available at L<http://www.sunfreeware.com/> and
-L<http://www.blastwave.org/>.
-
-=item Solaris Documentation
-
-All Solaris documentation is available on-line at L<http://docs.sun.com/>.
-
-=back
-
-=head1 SETTING UP
-
-=head2 File Extraction Problems on Solaris.
-
-Be sure to use a tar program compiled under Solaris (not SunOS 4.x)
-to extract the perl-5.x.x.tar.gz file. Do not use GNU tar compiled
-for SunOS4 on Solaris. (GNU tar compiled for Solaris should be fine.)
-When you run SunOS4 binaries on Solaris, the run-time system magically
-alters pathnames matching m#lib/locale# so that when tar tries to create
-lib/locale.pm, a file named lib/oldlocale.pm gets created instead.
-If you found this advice too late and used a SunOS4-compiled tar
-anyway, you must find the incorrectly renamed file and move it back
-to lib/locale.pm.
-
-=head2 Compiler and Related Tools on Solaris.
-
-You must use an ANSI C compiler to build perl. Perl can be compiled
-with either Sun's add-on C compiler or with gcc. The C compiler that
-shipped with SunOS4 will not do.
-
-=head3 Include /usr/ccs/bin/ in your PATH.
-
-Several tools needed to build perl are located in /usr/ccs/bin/: ar,
-as, ld, and make. Make sure that /usr/ccs/bin/ is in your PATH.
-
-
-On all the released versions of Solaris (8, 9 and 10) you need to make sure the following packages are installed (this info is extracted from the Solaris FAQ):
-
-for tools (sccs, lex, yacc, make, nm, truss, ld, as): SUNWbtool,
-SUNWsprot, SUNWtoo
-
-for libraries & headers: SUNWhea, SUNWarc, SUNWlibm, SUNWlibms, SUNWdfbh,
-SUNWcg6h, SUNWxwinc
-
-Additionaly, on Solaris 8 and 9 you also need:
-
-for 64 bit development: SUNWarcx, SUNWbtoox, SUNWdplx, SUNWscpux,
-SUNWsprox, SUNWtoox, SUNWlmsx, SUNWlmx, SUNWlibCx
-
-And only on Solaris 8 you also need:
-
-for libraries & headers: SUNWolinc
-
-
-If you are in doubt which package contains a file you are missing,
-try to find an installation that has that file. Then do a
-
- $ grep /my/missing/file /var/sadm/install/contents
-
-This will display a line like this:
-
-/usr/include/sys/errno.h f none 0644 root bin 7471 37605 956241356 SUNWhea
-
-The last item listed (SUNWhea in this example) is the package you need.
-
-=head3 Avoid /usr/ucb/cc.
-
-You don't need to have /usr/ucb/ in your PATH to build perl. If you
-want /usr/ucb/ in your PATH anyway, make sure that /usr/ucb/ is NOT
-in your PATH before the directory containing the right C compiler.
-
-=head3 Sun's C Compiler
-
-If you use Sun's C compiler, make sure the correct directory
-(usually /opt/SUNWspro/bin/) is in your PATH (before /usr/ucb/).
-
-=head3 GCC
-
-If you use gcc, make sure your installation is recent and complete.
-perl versions since 5.6.0 build fine with gcc > 2.8.1 on Solaris >=
-2.6.
-
-You must Configure perl with
-
- $ sh Configure -Dcc=gcc
-
-If you don't, you may experience strange build errors.
-
-If you have updated your Solaris version, you may also have to update
-your gcc. For example, if you are running Solaris 2.6 and your gcc is
-installed under /usr/local, check in /usr/local/lib/gcc-lib and make
-sure you have the appropriate directory, sparc-sun-solaris2.6/ or
-i386-pc-solaris2.6/. If gcc's directory is for a different version of
-Solaris than you are running, then you will need to rebuild gcc for
-your new version of Solaris.
-
-You can get a precompiled version of gcc from
-L<http://www.sunfreeware.com/> or L<http://www.blastwave.org/>. Make
-sure you pick up the package for your Solaris release.
-
-If you wish to use gcc to build add-on modules for use with the perl
-shipped with Solaris, you should use the Solaris::PerlGcc module
-which is available from CPAN. The perl shipped with Solaris
-is configured and built with the Sun compilers, and the compiler
-configuration information stored in Config.pm is therefore only
-relevant to the Sun compilers. The Solaris:PerlGcc module contains a
-replacement Config.pm that is correct for gcc - see the module for
-details.
-
-=head3 GNU as and GNU ld
-
-The following information applies to gcc version 2. Volunteers to
-update it as appropriately for gcc version 3 would be appreciated.
-
-The versions of as and ld supplied with Solaris work fine for building
-perl. There is normally no need to install the GNU versions to
-compile perl.
-
-If you decide to ignore this advice and use the GNU versions anyway,
-then be sure that they are relatively recent. Versions newer than 2.7
-are apparently new enough. Older versions may have trouble with
-dynamic loading.
-
-If you wish to use GNU ld, then you need to pass it the -Wl,-E flag.
-The hints/solaris_2.sh file tries to do this automatically by setting
-the following Configure variables:
-
- ccdlflags="$ccdlflags -Wl,-E"
- lddlflags="$lddlflags -Wl,-E -G"
-
-However, over the years, changes in gcc, GNU ld, and Solaris ld have made
-it difficult to automatically detect which ld ultimately gets called.
-You may have to manually edit config.sh and add the -Wl,-E flags
-yourself, or else run Configure interactively and add the flags at the
-appropriate prompts.
-
-If your gcc is configured to use GNU as and ld but you want to use the
-Solaris ones instead to build perl, then you'll need to add
--B/usr/ccs/bin/ to the gcc command line. One convenient way to do
-that is with
-
- $ sh Configure -Dcc='gcc -B/usr/ccs/bin/'
-
-Note that the trailing slash is required. This will result in some
-harmless warnings as Configure is run:
-
- gcc: file path prefix `/usr/ccs/bin/' never used
-
-These messages may safely be ignored.
-(Note that for a SunOS4 system, you must use -B/bin/ instead.)
-
-Alternatively, you can use the GCC_EXEC_PREFIX environment variable to
-ensure that Sun's as and ld are used. Consult your gcc documentation
-for further information on the -B option and the GCC_EXEC_PREFIX variable.
-
-=head3 Sun and GNU make
-
-The make under /usr/ccs/bin works fine for building perl. If you
-have the Sun C compilers, you will also have a parallel version of
-make (dmake). This works fine to build perl, but can sometimes cause
-problems when running 'make test' due to underspecified dependencies
-between the different test harness files. The same problem can also
-affect the building of some add-on modules, so in those cases either
-specify '-m serial' on the dmake command line, or use
-/usr/ccs/bin/make instead. If you wish to use GNU make, be sure that
-the set-group-id bit is not set. If it is, then arrange your PATH so
-that /usr/ccs/bin/make is before GNU make or else have the system
-administrator disable the set-group-id bit on GNU make.
-
-=head3 Avoid libucb.
-
-Solaris provides some BSD-compatibility functions in /usr/ucblib/libucb.a.
-Perl will not build and run correctly if linked against -lucb since it
-contains routines that are incompatible with the standard Solaris libc.
-Normally this is not a problem since the solaris hints file prevents
-Configure from even looking in /usr/ucblib for libraries, and also
-explicitly omits -lucb.
-
-=head2 Environment for Compiling perl on Solaris
-
-=head3 PATH
-
-Make sure your PATH includes the compiler (/opt/SUNWspro/bin/ if you're
-using Sun's compiler) as well as /usr/ccs/bin/ to pick up the other
-development tools (such as make, ar, as, and ld). Make sure your path
-either doesn't include /usr/ucb or that it includes it after the
-compiler and compiler tools and other standard Solaris directories.
-You definitely don't want /usr/ucb/cc.
-
-=head3 LD_LIBRARY_PATH
-
-If you have the LD_LIBRARY_PATH environment variable set, be sure that
-it does NOT include /lib or /usr/lib. If you will be building
-extensions that call third-party shared libraries (e.g. Berkeley DB)
-then make sure that your LD_LIBRARY_PATH environment variable includes
-the directory with that library (e.g. /usr/local/lib).
-
-If you get an error message
-
- dlopen: stub interception failed
-
-it is probably because your LD_LIBRARY_PATH environment variable
-includes a directory which is a symlink to /usr/lib (such as /lib).
-The reason this causes a problem is quite subtle. The file
-libdl.so.1.0 actually *only* contains functions which generate 'stub
-interception failed' errors! The runtime linker intercepts links to
-"/usr/lib/libdl.so.1.0" and links in internal implementations of those
-functions instead. [Thanks to Tim Bunce for this explanation.]
-
-=head1 RUN CONFIGURE.
-
-See the INSTALL file for general information regarding Configure.
-Only Solaris-specific issues are discussed here. Usually, the
-defaults should be fine.
-
-=head2 64-bit perl on Solaris.
-
-See the INSTALL file for general information regarding 64-bit compiles.
-In general, the defaults should be fine for most people.
-
-By default, perl-5.6.0 (or later) is compiled as a 32-bit application
-with largefile and long-long support.
-
-=head3 General 32-bit vs. 64-bit issues.
-
-Solaris 7 and above will run in either 32 bit or 64 bit mode on SPARC
-CPUs, via a reboot. You can build 64 bit apps whilst running 32 bit
-mode and vice-versa. 32 bit apps will run under Solaris running in
-either 32 or 64 bit mode. 64 bit apps require Solaris to be running
-64 bit mode.
-
-Existing 32 bit apps are properly known as LP32, i.e. Longs and
-Pointers are 32 bit. 64-bit apps are more properly known as LP64.
-The discriminating feature of a LP64 bit app is its ability to utilise a
-64-bit address space. It is perfectly possible to have a LP32 bit app
-that supports both 64-bit integers (long long) and largefiles (> 2GB),
-and this is the default for perl-5.6.0.
-
-For a more complete explanation of 64-bit issues, see the
-"Solaris 64-bit Developer's Guide" at L<http://docs.sun.com/>
-
-You can detect the OS mode using "isainfo -v", e.g.
-
- $ isainfo -v # Ultra 30 in 64 bit mode
- 64-bit sparcv9 applications
- 32-bit sparc applications
-
-By default, perl will be compiled as a 32-bit application. Unless
-you want to allocate more than ~ 4GB of memory inside perl, or unless
-you need more than 255 open file descriptors, you probably don't need
-perl to be a 64-bit app.
-
-=head3 Large File Support
-
-For Solaris 2.6 and onwards, there are two different ways for 32-bit
-applications to manipulate large files (files whose size is > 2GByte).
-(A 64-bit application automatically has largefile support built in
-by default.)
-
-First is the "transitional compilation environment", described in
-lfcompile64(5). According to the man page,
-
- The transitional compilation environment exports all the
- explicit 64-bit functions (xxx64()) and types in addition to
- all the regular functions (xxx()) and types. Both xxx() and
- xxx64() functions are available to the program source. A
- 32-bit application must use the xxx64() functions in order
- to access large files. See the lf64(5) manual page for a
- complete listing of the 64-bit transitional interfaces.
-
-The transitional compilation environment is obtained with the
-following compiler and linker flags:
-
- getconf LFS64_CFLAGS -D_LARGEFILE64_SOURCE
- getconf LFS64_LDFLAG # nothing special needed
- getconf LFS64_LIBS # nothing special needed
-
-Second is the "large file compilation environment", described in
-lfcompile(5). According to the man page,
-
- Each interface named xxx() that needs to access 64-bit entities
- to access large files maps to a xxx64() call in the
- resulting binary. All relevant data types are defined to be
- of correct size (for example, off_t has a typedef definition
- for a 64-bit entity).
-
- An application compiled in this environment is able to use
- the xxx() source interfaces to access both large and small
- files, rather than having to explicitly utilize the transitional
- xxx64() interface calls to access large files.
-
-Two exceptions are fseek() and ftell(). 32-bit applications should
-use fseeko(3C) and ftello(3C). These will get automatically mapped
-to fseeko64() and ftello64().
-
-The large file compilation environment is obtained with
-
- getconf LFS_CFLAGS -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64
- getconf LFS_LDFLAGS # nothing special needed
- getconf LFS_LIBS # nothing special needed
-
-By default, perl uses the large file compilation environment and
-relies on Solaris to do the underlying mapping of interfaces.
-
-=head3 Building an LP64 perl
-
-To compile a 64-bit application on an UltraSparc with a recent Sun Compiler,
-you need to use the flag "-xarch=v9". getconf(1) will tell you this, e.g.
-
- $ getconf -a | grep v9
- XBS5_LP64_OFF64_CFLAGS: -xarch=v9
- XBS5_LP64_OFF64_LDFLAGS: -xarch=v9
- XBS5_LP64_OFF64_LINTFLAGS: -xarch=v9
- XBS5_LPBIG_OFFBIG_CFLAGS: -xarch=v9
- XBS5_LPBIG_OFFBIG_LDFLAGS: -xarch=v9
- XBS5_LPBIG_OFFBIG_LINTFLAGS: -xarch=v9
- _XBS5_LP64_OFF64_CFLAGS: -xarch=v9
- _XBS5_LP64_OFF64_LDFLAGS: -xarch=v9
- _XBS5_LP64_OFF64_LINTFLAGS: -xarch=v9
- _XBS5_LPBIG_OFFBIG_CFLAGS: -xarch=v9
- _XBS5_LPBIG_OFFBIG_LDFLAGS: -xarch=v9
- _XBS5_LPBIG_OFFBIG_LINTFLAGS: -xarch=v9
-
-This flag is supported in Sun WorkShop Compilers 5.0 and onwards
-(now marketed under the name Forte) when used on Solaris 7 or later on
-UltraSparc systems.
-
-If you are using gcc, you would need to use -mcpu=v9 -m64 instead. This
-option is not yet supported as of gcc 2.95.2; from install/SPECIFIC
-in that release:
-
- GCC version 2.95 is not able to compile code correctly for sparc64
- targets. Users of the Linux kernel, at least, can use the sparc32
- program to start up a new shell invocation with an environment that
- causes configure to recognize (via uname -a) the system as sparc-*-*
- instead.
-
-All this should be handled automatically by the hints file, if
-requested.
-
-=head3 Long Doubles.
-
-As of 5.8.1, long doubles are working if you use the Sun compilers
-(needed for additional math routines not included in libm).
-
-=head2 Threads in perl on Solaris.
-
-It is possible to build a threaded version of perl on Solaris. The entire
-perl thread implementation is still experimental, however, so beware.
-
-=head2 Malloc Issues with perl on Solaris.
-
-Starting from perl 5.7.1 perl uses the Solaris malloc, since the perl
-malloc breaks when dealing with more than 2GB of memory, and the Solaris
-malloc also seems to be faster.
-
-If you for some reason (such as binary backward compatibility) really
-need to use perl's malloc, you can rebuild perl from the sources
-and Configure the build with
-
- $ sh Configure -Dusemymalloc
-
-You should not use perl's malloc if you are building with gcc. There
-are reports of core dumps, especially in the PDL module. The problem
-appears to go away under -DDEBUGGING, so it has been difficult to
-track down. Sun's compiler appears to be okay with or without perl's
-malloc. [XXX further investigation is needed here.]
-
-=head1 MAKE PROBLEMS.
-
-=over 4
-
-=item Dynamic Loading Problems With GNU as and GNU ld
-
-If you have problems with dynamic loading using gcc on SunOS or
-Solaris, and you are using GNU as and GNU ld, see the section
-L<"GNU as and GNU ld"> above.
-
-=item ld.so.1: ./perl: fatal: relocation error:
-
-If you get this message on SunOS or Solaris, and you're using gcc,
-it's probably the GNU as or GNU ld problem in the previous item
-L<"GNU as and GNU ld">.
-
-=item dlopen: stub interception failed
-
-The primary cause of the 'dlopen: stub interception failed' message is
-that the LD_LIBRARY_PATH environment variable includes a directory
-which is a symlink to /usr/lib (such as /lib). See
-L<"LD_LIBRARY_PATH"> above.
-
-=item #error "No DATAMODEL_NATIVE specified"
-
-This is a common error when trying to build perl on Solaris 2.6 with a
-gcc installation from Solaris 2.5 or 2.5.1. The Solaris header files
-changed, so you need to update your gcc installation. You can either
-rerun the fixincludes script from gcc or take the opportunity to
-update your gcc installation.
-
-=item sh: ar: not found
-
-This is a message from your shell telling you that the command 'ar'
-was not found. You need to check your PATH environment variable to
-make sure that it includes the directory with the 'ar' command. This
-is a common problem on Solaris, where 'ar' is in the /usr/ccs/bin/
-directory.
-
-=back
-
-=head1 MAKE TEST
-
-=head2 op/stat.t test 4 in Solaris
-
-F<op/stat.t> test 4 may fail if you are on a tmpfs of some sort.
-Building in /tmp sometimes shows this behavior. The
-test suite detects if you are building in /tmp, but it may not be able
-to catch all tmpfs situations.
-
-=head2 nss_delete core dump from op/pwent or op/grent
-
-See L<perlhpux/"nss_delete core dump from op/pwent or op/grent">.
-
-=head1 PREBUILT BINARIES OF PERL FOR SOLARIS.
-
-You can pick up prebuilt binaries for Solaris from
-L<http://www.sunfreeware.com/>, L<http://www.blastwave.org>,
-ActiveState L<http://www.activestate.com/>, and
-L<http://www.perl.com/> under the Binaries list at the top of the
-page. There are probably other sources as well. Please note that
-these sites are under the control of their respective owners, not the
-perl developers.
-
-=head1 RUNTIME ISSUES FOR PERL ON SOLARIS.
-
-=head2 Limits on Numbers of Open Files on Solaris.
-
-The stdio(3C) manpage notes that for LP32 applications, only 255
-files may be opened using fopen(), and only file descriptors 0
-through 255 can be used in a stream. Since perl calls open() and
-then fdopen(3C) with the resulting file descriptor, perl is limited
-to 255 simultaneous open files, even if sysopen() is used. If this
-proves to be an insurmountable problem, you can compile perl as a
-LP64 application, see L<Building an LP64 perl> for details. Note
-also that the default resource limit for open file descriptors on
-Solaris is 255, so you will have to modify your ulimit or rctl
-(Solaris 9 onwards) appropriately.
-
-=head1 SOLARIS-SPECIFIC MODULES.
-
-See the modules under the Solaris:: and Sun::Solaris namespaces on CPAN,
-see L<http://www.cpan.org/modules/by-module/Solaris/> and
-L<http://www.cpan.org/modules/by-module/Sun/>.
-
-=head1 SOLARIS-SPECIFIC PROBLEMS WITH MODULES.
-
-=head2 Proc::ProcessTable on Solaris
-
-Proc::ProcessTable does not compile on Solaris with perl5.6.0 and higher
-if you have LARGEFILES defined. Since largefile support is the
-default in 5.6.0 and later, you have to take special steps to use this
-module.
-
-The problem is that various structures visible via procfs use off_t,
-and if you compile with largefile support these change from 32 bits to
-64 bits. Thus what you get back from procfs doesn't match up with
-the structures in perl, resulting in garbage. See proc(4) for further
-discussion.
-
-A fix for Proc::ProcessTable is to edit Makefile to
-explicitly remove the largefile flags from the ones MakeMaker picks up
-from Config.pm. This will result in Proc::ProcessTable being built
-under the correct environment. Everything should then be OK as long as
-Proc::ProcessTable doesn't try to share off_t's with the rest of perl,
-or if it does they should be explicitly specified as off64_t.
-
-=head2 BSD::Resource on Solaris
-
-BSD::Resource versions earlier than 1.09 do not compile on Solaris
-with perl 5.6.0 and higher, for the same reasons as Proc::ProcessTable.
-BSD::Resource versions starting from 1.09 have a workaround for the problem.
-
-=head2 Net::SSLeay on Solaris
-
-Net::SSLeay requires a /dev/urandom to be present. This device is
-available from Solaris 9 onwards. For earlier Solaris versions you
-can either get the package SUNWski (packaged with several Sun
-software products, for example the Sun WebServer, which is part of
-the Solaris Server Intranet Extension, or the Sun Directory Services,
-part of Solaris for ISPs) or download the ANDIrand package from
-L<http://www.cosy.sbg.ac.at/~andi/>. If you use SUNWski, make a
-symbolic link /dev/urandom pointing to /dev/random. For more details,
-see Document ID27606 entitled "Differing /dev/random support requirements
-within Solaris[TM] Operating Environments", available at
-L<http://sunsolve.sun.com> .
-
-It may be possible to use the Entropy Gathering Daemon (written in
-Perl!), available from L<http://www.lothar.com/tech/crypto/>.
-
-=head1 SunOS 4.x
-
-In SunOS 4.x you most probably want to use the SunOS ld, /usr/bin/ld,
-since the more recent versions of GNU ld (like 2.13) do not seem to
-work for building Perl anymore. When linking the extensions, the
-GNU ld gets very unhappy and spews a lot of errors like this
-
- ... relocation truncated to fit: BASE13 ...
-
-and dies. Therefore the SunOS 4.1 hints file explicitly sets the
-ld to be F</usr/bin/ld>.
-
-As of Perl 5.8.1 the dynamic loading of libraries (DynaLoader, XSLoader)
-also seems to have become broken in in SunOS 4.x. Therefore the default
-is to build Perl statically.
-
-Running the test suite in SunOS 4.1 is a bit tricky since the
-F<lib/Tie/File/t/09_gen_rs> test hangs (subtest #51, FWIW) for some
-unknown reason. Just stop the test and kill that particular Perl
-process.
-
-There are various other failures, that as of SunOS 4.1.4 and gcc 3.2.2
-look a lot like gcc bugs. Many of the failures happen in the Encode
-tests, where for example when the test expects "0" you get "&#48;"
-which should after a little squinting look very odd indeed.
-Another example is earlier in F<t/run/fresh_perl> where chr(0xff) is
-expected but the test fails because the result is chr(0xff). Exactly.
-
-This is the "make test" result from the said combination:
-
- Failed 27 test scripts out of 745, 96.38% okay.
-
-Running the C<harness> is painful because of the many failing
-Unicode-related tests will output megabytes of failure messages,
-but if one patiently waits, one gets these results:
-
- Failed Test Stat Wstat Total Fail Failed List of Failed
- -----------------------------------------------------------------------------
- ...
- ../ext/Encode/t/at-cn.t 4 1024 29 4 13.79% 14-17
- ../ext/Encode/t/at-tw.t 10 2560 17 10 58.82% 2 4 6 8 10 12
- 14-17
- ../ext/Encode/t/enc_data.t 29 7424 ?? ?? % ??
- ../ext/Encode/t/enc_eucjp.t 29 7424 ?? ?? % ??
- ../ext/Encode/t/enc_module.t 29 7424 ?? ?? % ??
- ../ext/Encode/t/encoding.t 29 7424 ?? ?? % ??
- ../ext/Encode/t/grow.t 12 3072 24 12 50.00% 2 4 6 8 10 12 14
- 16 18 20 22 24
- Failed Test Stat Wstat Total Fail Failed List of Failed
- ------------------------------------------------------------------------------
- ../ext/Encode/t/guess.t 255 65280 29 40 137.93% 10-29
- ../ext/Encode/t/jperl.t 29 7424 15 30 200.00% 1-15
- ../ext/Encode/t/mime-header.t 2 512 10 2 20.00% 2-3
- ../ext/Encode/t/perlio.t 22 5632 38 22 57.89% 1-4 9-16 19-20
- 23-24 27-32
- ../ext/List/Util/t/shuffle.t 0 139 ?? ?? % ??
- ../ext/PerlIO/t/encoding.t 14 1 7.14% 11
- ../ext/PerlIO/t/fallback.t 9 2 22.22% 3 5
- ../ext/Socket/t/socketpair.t 0 2 45 70 155.56% 11-45
- ../lib/CPAN/t/vcmp.t 30 1 3.33% 25
- ../lib/Tie/File/t/09_gen_rs.t 0 15 ?? ?? % ??
- ../lib/Unicode/Collate/t/test.t 199 30 15.08% 7 26-27 71-75
- 81-88 95 101
- 103-104 106 108-
- 109 122 124 161
- 169-172
- ../lib/sort.t 0 139 119 26 21.85% 107-119
- op/alarm.t 4 1 25.00% 4
- op/utfhash.t 97 1 1.03% 31
- run/fresh_perl.t 91 1 1.10% 32
- uni/tr_7jis.t ?? ?? % ??
- uni/tr_eucjp.t 29 7424 6 12 200.00% 1-6
- uni/tr_sjis.t 29 7424 6 12 200.00% 1-6
- 56 tests and 467 subtests skipped.
- Failed 27/811 test scripts, 96.67% okay. 1383/75399 subtests failed, 98.17% okay.
-
-The alarm() test failure is caused by system() apparently blocking
-alarm(). That is probably a libc bug, and given that SunOS 4.x
-has been end-of-lifed years ago, don't hold your breath for a fix.
-In addition to that, don't try anything too Unicode-y, especially
-with Encode, and you should be fine in SunOS 4.x.
-
-=head1 AUTHOR
-
-The original was written by Andy Dougherty F<doughera@lafayette.edu>
-drawing heavily on advice from Alan Burlison, Nick Ing-Simmons, Tim Bunce,
-and many other Solaris users over the years.
-
-Please report any errors, updates, or suggestions to F<perlbug@perl.org>.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlsource.pod b/Master/tlpkg/tlperl/lib/pods/perlsource.pod
deleted file mode 100644
index 16252eb3f07..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlsource.pod
+++ /dev/null
@@ -1,223 +0,0 @@
-=encoding utf8
-
-=for comment
-Consistent formatting of this file is achieved with:
- perl ./Porting/podtidy pod/perlsource.pod
-
-=head1 NAME
-
-perlsource - A guide to the Perl source tree
-
-=head1 DESCRIPTION
-
-This document describes the layout of the Perl source tree. If you're
-hacking on the Perl core, this will help you find what you're looking
-for.
-
-=head1 FINDING YOUR WAY AROUND
-
-The Perl source tree is big. Here's some of the thing you'll find in
-it:
-
-=head2 C code
-
-The C source code and header files mostly live in the root of the
-source tree. There are a few platform-specific directories which
-contain C code. In addition, some of the modules shipped with Perl
-include C or XS code.
-
-See L<perlinterp> for more details on the files that make up the Perl
-interpreter, as well as details on how it works.
-
-=head2 Core modules
-
-Modules shipped as part of the Perl core live in four subdirectories.
-Two of these directories contain modules that live in the core, and two
-contain modules that can also be released separately on CPAN. Modules
-which can be released on cpan are known as "dual-life" modules.
-
-=over 4
-
-=item * F<lib/>
-
-This directory contains pure-Perl modules which are only released as
-part of the core. This directory contains I<all> of the modules and
-their tests, unlike other core modules.
-
-=item * F<ext/>
-
-This directory contains XS-using modules which are only released as
-part of the core. These modules generally have their F<Makefile.PL> and
-are laid out more like a typical CPAN module.
-
-=item * F<dist/>
-
-This directory is for dual-life modules where the blead source is
-canonical. Note that some modules in this directory may not yet have
-been released separately on CPAN.
-
-=item * F<cpan/>
-
-This directory contains dual-life modules where the CPAN module is
-canonical. Do not patch these modules directly! Changes to these
-modules should be submitted to the maintainer of the CPAN module. Once
-those changes are applied and released, the new version of the module
-will be incorporated into the core.
-
-=back
-
-For some dual-life modules, it has not yet been determined if the CPAN
-version or the blead source is canonical. Until that is done, those
-modules should be in F<cpan/>.
-
-=head2 Tests
-
-The Perl core has an extensive test suite. If you add new tests (or new
-modules with tests), you may need to update the F<t/TEST> file so that
-the tests are run.
-
-=over 4
-
-=item * Module tests
-
-Tests for core modules in the F<lib/> directory are right next to the
-module itself. For example, we have F<lib/strict.pm> and
-F<lib/strict.t>.
-
-Tests for modules in F<ext/> and the dual-life modules are in F<t/>
-subdirectories for each module, like a standard CPAN distribution.
-
-=item * F<t/base/>
-
-Tests for the absolute basic functionality of Perl. This includes
-C<if>, basic file reads and writes, simple regexes, etc. These are run
-first in the test suite and if any of them fail, something is I<really>
-broken.
-
-=item * F<t/cmd/>
-
-Tests for basic control structures, C<if/else>, C<while>, subroutines,
-etc.
-
-=item * F<t/comp/>
-
-Tests for basic issues of how Perl parses and compiles itself.
-
-=item * F<t/io/>
-
-Tests for built-in IO functions, including command line arguments.
-
-=item * F<t/mro/>
-
-Tests for perl's method resolution order implementations (see L<mro>).
-
-=item * F<t/op/>
-
-Tests for perl's built in functions that don't fit into any of the
-other directories.
-
-=item * F<t/re/>
-
-Tests for regex related functions or behaviour. (These used to live in
-t/op).
-
-=item * F<t/run/>
-
-Tests for features of how perl actually runs, including exit codes and
-handling of PERL* environment variables.
-
-=item * F<t/uni/>
-
-Tests for the core support of Unicode.
-
-=item * F<t/win32/>
-
-Windows-specific tests.
-
-=item * F<t/porting/>
-
-Tests the state of the source tree for various common errors. For
-example, it tests that everyone who is listed in the git log has a
-corresponding entry in the F<AUTHORS> file.
-
-=item * F<t/lib/>
-
-The old home for the module tests, you shouldn't put anything new in
-here. There are still some bits and pieces hanging around in here that
-need to be moved. Perhaps you could move them? Thanks!
-
-=item * F<t/x2p>
-
-A test suite for the s2p converter.
-
-=back
-
-=head2 Documentation
-
-All of the core documentation intended for end users lives in F<pod/>.
-Individual modules in F<lib/>, F<ext/>, F<dist/>, and F<cpan/> usually
-have their own documentation, either in the F<Module.pm> file or an
-accompanying F<Module.pod> file.
-
-Finally, documentation intended for core Perl developers lives in the
-F<Porting/> directory.
-
-=head2 Hacking tools and documentation
-
-The F<Porting> directory contains a grab bag of code and documentation
-intended to help porters work on Perl. Some of the highlights include:
-
-=over 4
-
-=item * F<check*>
-
-These are scripts which will check the source things like ANSI C
-violations, POD encoding issues, etc.
-
-=item * F<Maintainers>, F<Maintainers.pl>, and F<Maintainers.pm>
-
-These files contain information on who maintains which modules. Run
-C<perl Porting/Maintainers -M Module::Name> to find out more
-information about a dual-life module.
-
-=item * F<podtidy>
-
-Tidies a pod file. It's a good idea to run this on a pod file you've
-patched.
-
-=back
-
-=head2 Build system
-
-The Perl build system starts with the F<Configure> script in the root
-directory.
-
-Platform-specific pieces of the build system also live in
-platform-specific directories like F<win32/>, F<vms/>, etc.
-
-The F<Configure> script is ultimately responsible for generating a
-F<Makefile>.
-
-The build system that Perl uses is called metaconfig. This system is
-maintained separately from the Perl core.
-
-The metaconfig system has its own git repository. Please see its README
-file in L<http://perl5.git.perl.org/metaconfig.git/> for more details.
-
-The F<Cross> directory contains various files related to
-cross-compiling Perl. See F<Cross/README> for more details.
-
-=head2 F<AUTHORS>
-
-This file lists everyone who's contributed to Perl. If you submit a
-patch, you should add your name to this file as part of the patch.
-
-=head2 F<MANIFEST>
-
-The F<MANIFEST> file in the root of the source tree contains a list of
-every file in the Perl core, as well as a brief description of each
-file.
-
-You can get an overview of all the files with this command:
-
- % perl -lne 'print if /^[^\/]+\.[ch]\s+/' MANIFEST
diff --git a/Master/tlpkg/tlperl/lib/pods/perlstyle.pod b/Master/tlpkg/tlperl/lib/pods/perlstyle.pod
deleted file mode 100644
index 37dfaaf1413..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlstyle.pod
+++ /dev/null
@@ -1,303 +0,0 @@
-=head1 NAME
-
-perlstyle - Perl style guide
-
-=head1 DESCRIPTION
-
-Each programmer will, of course, have his or her own preferences in
-regards to formatting, but there are some general guidelines that will
-make your programs easier to read, understand, and maintain.
-
-The most important thing is to run your programs under the B<-w>
-flag at all times. You may turn it off explicitly for particular
-portions of code via the C<no warnings> pragma or the C<$^W> variable
-if you must. You should also always run under C<use strict> or know the
-reason why not. The C<use sigtrap> and even C<use diagnostics> pragmas
-may also prove useful.
-
-Regarding aesthetics of code lay out, about the only thing Larry
-cares strongly about is that the closing curly bracket of
-a multi-line BLOCK should line up with the keyword that started the construct.
-Beyond that, he has other preferences that aren't so strong:
-
-=over 4
-
-=item *
-
-4-column indent.
-
-=item *
-
-Opening curly on same line as keyword, if possible, otherwise line up.
-
-=item *
-
-Space before the opening curly of a multi-line BLOCK.
-
-=item *
-
-One-line BLOCK may be put on one line, including curlies.
-
-=item *
-
-No space before the semicolon.
-
-=item *
-
-Semicolon omitted in "short" one-line BLOCK.
-
-=item *
-
-Space around most operators.
-
-=item *
-
-Space around a "complex" subscript (inside brackets).
-
-=item *
-
-Blank lines between chunks that do different things.
-
-=item *
-
-Uncuddled elses.
-
-=item *
-
-No space between function name and its opening parenthesis.
-
-=item *
-
-Space after each comma.
-
-=item *
-
-Long lines broken after an operator (except C<and> and C<or>).
-
-=item *
-
-Space after last parenthesis matching on current line.
-
-=item *
-
-Line up corresponding items vertically.
-
-=item *
-
-Omit redundant punctuation as long as clarity doesn't suffer.
-
-=back
-
-Larry has his reasons for each of these things, but he doesn't claim that
-everyone else's mind works the same as his does.
-
-Here are some other more substantive style issues to think about:
-
-=over 4
-
-=item *
-
-Just because you I<CAN> do something a particular way doesn't mean that
-you I<SHOULD> do it that way. Perl is designed to give you several
-ways to do anything, so consider picking the most readable one. For
-instance
-
- open(FOO,$foo) || die "Can't open $foo: $!";
-
-is better than
-
- die "Can't open $foo: $!" unless open(FOO,$foo);
-
-because the second way hides the main point of the statement in a
-modifier. On the other hand
-
- print "Starting analysis\n" if $verbose;
-
-is better than
-
- $verbose && print "Starting analysis\n";
-
-because the main point isn't whether the user typed B<-v> or not.
-
-Similarly, just because an operator lets you assume default arguments
-doesn't mean that you have to make use of the defaults. The defaults
-are there for lazy systems programmers writing one-shot programs. If
-you want your program to be readable, consider supplying the argument.
-
-Along the same lines, just because you I<CAN> omit parentheses in many
-places doesn't mean that you ought to:
-
- return print reverse sort num values %array;
- return print(reverse(sort num (values(%array))));
-
-When in doubt, parenthesize. At the very least it will let some poor
-schmuck bounce on the % key in B<vi>.
-
-Even if you aren't in doubt, consider the mental welfare of the person
-who has to maintain the code after you, and who will probably put
-parentheses in the wrong place.
-
-=item *
-
-Don't go through silly contortions to exit a loop at the top or the
-bottom, when Perl provides the C<last> operator so you can exit in
-the middle. Just "outdent" it a little to make it more visible:
-
- LINE:
- for (;;) {
- statements;
- last LINE if $foo;
- next LINE if /^#/;
- statements;
- }
-
-=item *
-
-Don't be afraid to use loop labels--they're there to enhance
-readability as well as to allow multilevel loop breaks. See the
-previous example.
-
-=item *
-
-Avoid using C<grep()> (or C<map()>) or `backticks` in a void context, that is,
-when you just throw away their return values. Those functions all
-have return values, so use them. Otherwise use a C<foreach()> loop or
-the C<system()> function instead.
-
-=item *
-
-For portability, when using features that may not be implemented on
-every machine, test the construct in an eval to see if it fails. If
-you know what version or patchlevel a particular feature was
-implemented, you can test C<$]> (C<$PERL_VERSION> in C<English>) to see if it
-will be there. The C<Config> module will also let you interrogate values
-determined by the B<Configure> program when Perl was installed.
-
-=item *
-
-Choose mnemonic identifiers. If you can't remember what mnemonic means,
-you've got a problem.
-
-=item *
-
-While short identifiers like C<$gotit> are probably ok, use underscores to
-separate words in longer identifiers. It is generally easier to read
-C<$var_names_like_this> than C<$VarNamesLikeThis>, especially for
-non-native speakers of English. It's also a simple rule that works
-consistently with C<VAR_NAMES_LIKE_THIS>.
-
-Package names are sometimes an exception to this rule. Perl informally
-reserves lowercase module names for "pragma" modules like C<integer> and
-C<strict>. Other modules should begin with a capital letter and use mixed
-case, but probably without underscores due to limitations in primitive
-file systems' representations of module names as files that must fit into a
-few sparse bytes.
-
-=item *
-
-You may find it helpful to use letter case to indicate the scope
-or nature of a variable. For example:
-
- $ALL_CAPS_HERE constants only (beware clashes with perl vars!)
- $Some_Caps_Here package-wide global/static
- $no_caps_here function scope my() or local() variables
-
-Function and method names seem to work best as all lowercase.
-E.g., C<$obj-E<gt>as_string()>.
-
-You can use a leading underscore to indicate that a variable or
-function should not be used outside the package that defined it.
-
-=item *
-
-If you have a really hairy regular expression, use the C</x> modifier and
-put in some whitespace to make it look a little less like line noise.
-Don't use slash as a delimiter when your regexp has slashes or backslashes.
-
-=item *
-
-Use the new C<and> and C<or> operators to avoid having to parenthesize
-list operators so much, and to reduce the incidence of punctuation
-operators like C<&&> and C<||>. Call your subroutines as if they were
-functions or list operators to avoid excessive ampersands and parentheses.
-
-=item *
-
-Use here documents instead of repeated C<print()> statements.
-
-=item *
-
-Line up corresponding things vertically, especially if it'd be too long
-to fit on one line anyway.
-
- $IDX = $ST_MTIME;
- $IDX = $ST_ATIME if $opt_u;
- $IDX = $ST_CTIME if $opt_c;
- $IDX = $ST_SIZE if $opt_s;
-
- mkdir $tmpdir, 0700 or die "can't mkdir $tmpdir: $!";
- chdir($tmpdir) or die "can't chdir $tmpdir: $!";
- mkdir 'tmp', 0777 or die "can't mkdir $tmpdir/tmp: $!";
-
-=item *
-
-Always check the return codes of system calls. Good error messages should
-go to C<STDERR>, include which program caused the problem, what the failed
-system call and arguments were, and (VERY IMPORTANT) should contain the
-standard system error message for what went wrong. Here's a simple but
-sufficient example:
-
- opendir(D, $dir) or die "can't opendir $dir: $!";
-
-=item *
-
-Line up your transliterations when it makes sense:
-
- tr [abc]
- [xyz];
-
-=item *
-
-Think about reusability. Why waste brainpower on a one-shot when you
-might want to do something like it again? Consider generalizing your
-code. Consider writing a module or object class. Consider making your
-code run cleanly with C<use strict> and C<use warnings> (or B<-w>) in
-effect. Consider giving away your code. Consider changing your whole
-world view. Consider... oh, never mind.
-
-=item *
-
-Try to document your code and use Pod formatting in a consistent way. Here
-are commonly expected conventions:
-
-=over 4
-
-=item *
-
-use C<CE<lt>E<gt>> for function, variable and module names (and more
-generally anything that can be considered part of code, like filehandles
-or specific values). Note that function names are considered more readable
-with parentheses after their name, that is C<function()>.
-
-=item *
-
-use C<BE<lt>E<gt>> for commands names like B<cat> or B<grep>.
-
-=item *
-
-use C<FE<lt>E<gt>> or C<CE<lt>E<gt>> for file names. C<FE<lt>E<gt>> should
-be the only Pod code for file names, but as most Pod formatters render it
-as italic, Unix and Windows paths with their slashes and backslashes may
-be less readable, and better rendered with C<CE<lt>E<gt>>.
-
-=back
-
-=item *
-
-Be consistent.
-
-=item *
-
-Be nice.
-
-=back
diff --git a/Master/tlpkg/tlperl/lib/pods/perlsub.pod b/Master/tlpkg/tlperl/lib/pods/perlsub.pod
deleted file mode 100644
index 760e496fab7..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlsub.pod
+++ /dev/null
@@ -1,1535 +0,0 @@
-=head1 NAME
-X<subroutine> X<function>
-
-perlsub - Perl subroutines
-
-=head1 SYNOPSIS
-
-To declare subroutines:
-X<subroutine, declaration> X<sub>
-
- sub NAME; # A "forward" declaration.
- sub NAME(PROTO); # ditto, but with prototypes
- sub NAME : ATTRS; # with attributes
- sub NAME(PROTO) : ATTRS; # with attributes and prototypes
-
- sub NAME BLOCK # A declaration and a definition.
- sub NAME(PROTO) BLOCK # ditto, but with prototypes
- sub NAME : ATTRS BLOCK # with attributes
- sub NAME(PROTO) : ATTRS BLOCK # with prototypes and attributes
-
-To define an anonymous subroutine at runtime:
-X<subroutine, anonymous>
-
- $subref = sub BLOCK; # no proto
- $subref = sub (PROTO) BLOCK; # with proto
- $subref = sub : ATTRS BLOCK; # with attributes
- $subref = sub (PROTO) : ATTRS BLOCK; # with proto and attributes
-
-To import subroutines:
-X<import>
-
- use MODULE qw(NAME1 NAME2 NAME3);
-
-To call subroutines:
-X<subroutine, call> X<call>
-
- NAME(LIST); # & is optional with parentheses.
- NAME LIST; # Parentheses optional if predeclared/imported.
- &NAME(LIST); # Circumvent prototypes.
- &NAME; # Makes current @_ visible to called subroutine.
-
-=head1 DESCRIPTION
-
-Like many languages, Perl provides for user-defined subroutines.
-These may be located anywhere in the main program, loaded in from
-other files via the C<do>, C<require>, or C<use> keywords, or
-generated on the fly using C<eval> or anonymous subroutines.
-You can even call a function indirectly using a variable containing
-its name or a CODE reference.
-
-The Perl model for function call and return values is simple: all
-functions are passed as parameters one single flat list of scalars, and
-all functions likewise return to their caller one single flat list of
-scalars. Any arrays or hashes in these call and return lists will
-collapse, losing their identities--but you may always use
-pass-by-reference instead to avoid this. Both call and return lists may
-contain as many or as few scalar elements as you'd like. (Often a
-function without an explicit return statement is called a subroutine, but
-there's really no difference from Perl's perspective.)
-X<subroutine, parameter> X<parameter>
-
-Any arguments passed in show up in the array C<@_>. Therefore, if
-you called a function with two arguments, those would be stored in
-C<$_[0]> and C<$_[1]>. The array C<@_> is a local array, but its
-elements are aliases for the actual scalar parameters. In particular,
-if an element C<$_[0]> is updated, the corresponding argument is
-updated (or an error occurs if it is not updatable). If an argument
-is an array or hash element which did not exist when the function
-was called, that element is created only when (and if) it is modified
-or a reference to it is taken. (Some earlier versions of Perl
-created the element whether or not the element was assigned to.)
-Assigning to the whole array C<@_> removes that aliasing, and does
-not update any arguments.
-X<subroutine, argument> X<argument> X<@_>
-
-A C<return> statement may be used to exit a subroutine, optionally
-specifying the returned value, which will be evaluated in the
-appropriate context (list, scalar, or void) depending on the context of
-the subroutine call. If you specify no return value, the subroutine
-returns an empty list in list context, the undefined value in scalar
-context, or nothing in void context. If you return one or more
-aggregates (arrays and hashes), these will be flattened together into
-one large indistinguishable list.
-
-If no C<return> is found and if the last statement is an expression, its
-value is returned. If the last statement is a loop control structure
-like a C<foreach> or a C<while>, the returned value is unspecified. The
-empty sub returns the empty list.
-X<subroutine, return value> X<return value> X<return>
-
-Perl does not have named formal parameters. In practice all you
-do is assign to a C<my()> list of these. Variables that aren't
-declared to be private are global variables. For gory details
-on creating private variables, see L<"Private Variables via my()">
-and L<"Temporary Values via local()">. To create protected
-environments for a set of functions in a separate package (and
-probably a separate file), see L<perlmod/"Packages">.
-X<formal parameter> X<parameter, formal>
-
-Example:
-
- sub max {
- my $max = shift(@_);
- foreach $foo (@_) {
- $max = $foo if $max < $foo;
- }
- return $max;
- }
- $bestday = max($mon,$tue,$wed,$thu,$fri);
-
-Example:
-
- # get a line, combining continuation lines
- # that start with whitespace
-
- sub get_line {
- $thisline = $lookahead; # global variables!
- LINE: while (defined($lookahead = <STDIN>)) {
- if ($lookahead =~ /^[ \t]/) {
- $thisline .= $lookahead;
- }
- else {
- last LINE;
- }
- }
- return $thisline;
- }
-
- $lookahead = <STDIN>; # get first line
- while (defined($line = get_line())) {
- ...
- }
-
-Assigning to a list of private variables to name your arguments:
-
- sub maybeset {
- my($key, $value) = @_;
- $Foo{$key} = $value unless $Foo{$key};
- }
-
-Because the assignment copies the values, this also has the effect
-of turning call-by-reference into call-by-value. Otherwise a
-function is free to do in-place modifications of C<@_> and change
-its caller's values.
-X<call-by-reference> X<call-by-value>
-
- upcase_in($v1, $v2); # this changes $v1 and $v2
- sub upcase_in {
- for (@_) { tr/a-z/A-Z/ }
- }
-
-You aren't allowed to modify constants in this way, of course. If an
-argument were actually literal and you tried to change it, you'd take a
-(presumably fatal) exception. For example, this won't work:
-X<call-by-reference> X<call-by-value>
-
- upcase_in("frederick");
-
-It would be much safer if the C<upcase_in()> function
-were written to return a copy of its parameters instead
-of changing them in place:
-
- ($v3, $v4) = upcase($v1, $v2); # this doesn't change $v1 and $v2
- sub upcase {
- return unless defined wantarray; # void context, do nothing
- my @parms = @_;
- for (@parms) { tr/a-z/A-Z/ }
- return wantarray ? @parms : $parms[0];
- }
-
-Notice how this (unprototyped) function doesn't care whether it was
-passed real scalars or arrays. Perl sees all arguments as one big,
-long, flat parameter list in C<@_>. This is one area where
-Perl's simple argument-passing style shines. The C<upcase()>
-function would work perfectly well without changing the C<upcase()>
-definition even if we fed it things like this:
-
- @newlist = upcase(@list1, @list2);
- @newlist = upcase( split /:/, $var );
-
-Do not, however, be tempted to do this:
-
- (@a, @b) = upcase(@list1, @list2);
-
-Like the flattened incoming parameter list, the return list is also
-flattened on return. So all you have managed to do here is stored
-everything in C<@a> and made C<@b> empty. See
-L<Pass by Reference> for alternatives.
-
-A subroutine may be called using an explicit C<&> prefix. The
-C<&> is optional in modern Perl, as are parentheses if the
-subroutine has been predeclared. The C<&> is I<not> optional
-when just naming the subroutine, such as when it's used as
-an argument to defined() or undef(). Nor is it optional when you
-want to do an indirect subroutine call with a subroutine name or
-reference using the C<&$subref()> or C<&{$subref}()> constructs,
-although the C<< $subref->() >> notation solves that problem.
-See L<perlref> for more about all that.
-X<&>
-
-Subroutines may be called recursively. If a subroutine is called
-using the C<&> form, the argument list is optional, and if omitted,
-no C<@_> array is set up for the subroutine: the C<@_> array at the
-time of the call is visible to subroutine instead. This is an
-efficiency mechanism that new users may wish to avoid.
-X<recursion>
-
- &foo(1,2,3); # pass three arguments
- foo(1,2,3); # the same
-
- foo(); # pass a null list
- &foo(); # the same
-
- &foo; # foo() get current args, like foo(@_) !!
- foo; # like foo() IFF sub foo predeclared, else "foo"
-
-Not only does the C<&> form make the argument list optional, it also
-disables any prototype checking on arguments you do provide. This
-is partly for historical reasons, and partly for having a convenient way
-to cheat if you know what you're doing. See L</Prototypes> below.
-X<&>
-
-Since Perl 5.16.0, the C<__SUB__> token is available under C<use feature
-'current_sub'> and C<use 5.16.0>. It will evaluate to a reference to the
-currently-running sub, which allows for recursive calls without knowing
-your subroutine's name.
-
- use 5.16.0;
- my $factorial = sub {
- my ($x) = @_;
- return 1 if $x == 1;
- return($x * __SUB__->( $x - 1 ) );
- };
-
-Subroutines whose names are in all upper case are reserved to the Perl
-core, as are modules whose names are in all lower case. A subroutine in
-all capitals is a loosely-held convention meaning it will be called
-indirectly by the run-time system itself, usually due to a triggered event.
-Subroutines that do special, pre-defined things include C<AUTOLOAD>, C<CLONE>,
-C<DESTROY> plus all functions mentioned in L<perltie> and L<PerlIO::via>.
-
-The C<BEGIN>, C<UNITCHECK>, C<CHECK>, C<INIT> and C<END> subroutines
-are not so much subroutines as named special code blocks, of which you
-can have more than one in a package, and which you can B<not> call
-explicitly. See L<perlmod/"BEGIN, UNITCHECK, CHECK, INIT and END">
-
-=head2 Private Variables via my()
-X<my> X<variable, lexical> X<lexical> X<lexical variable> X<scope, lexical>
-X<lexical scope> X<attributes, my>
-
-Synopsis:
-
- my $foo; # declare $foo lexically local
- my (@wid, %get); # declare list of variables local
- my $foo = "flurp"; # declare $foo lexical, and init it
- my @oof = @bar; # declare @oof lexical, and init it
- my $x : Foo = $y; # similar, with an attribute applied
-
-B<WARNING>: The use of attribute lists on C<my> declarations is still
-evolving. The current semantics and interface are subject to change.
-See L<attributes> and L<Attribute::Handlers>.
-
-The C<my> operator declares the listed variables to be lexically
-confined to the enclosing block, conditional (C<if/unless/elsif/else>),
-loop (C<for/foreach/while/until/continue>), subroutine, C<eval>,
-or C<do/require/use>'d file. If more than one value is listed, the
-list must be placed in parentheses. All listed elements must be
-legal lvalues. Only alphanumeric identifiers may be lexically
-scoped--magical built-ins like C<$/> must currently be C<local>ized
-with C<local> instead.
-
-Unlike dynamic variables created by the C<local> operator, lexical
-variables declared with C<my> are totally hidden from the outside
-world, including any called subroutines. This is true if it's the
-same subroutine called from itself or elsewhere--every call gets
-its own copy.
-X<local>
-
-This doesn't mean that a C<my> variable declared in a statically
-enclosing lexical scope would be invisible. Only dynamic scopes
-are cut off. For example, the C<bumpx()> function below has access
-to the lexical $x variable because both the C<my> and the C<sub>
-occurred at the same scope, presumably file scope.
-
- my $x = 10;
- sub bumpx { $x++ }
-
-An C<eval()>, however, can see lexical variables of the scope it is
-being evaluated in, so long as the names aren't hidden by declarations within
-the C<eval()> itself. See L<perlref>.
-X<eval, scope of>
-
-The parameter list to my() may be assigned to if desired, which allows you
-to initialize your variables. (If no initializer is given for a
-particular variable, it is created with the undefined value.) Commonly
-this is used to name input parameters to a subroutine. Examples:
-
- $arg = "fred"; # "global" variable
- $n = cube_root(27);
- print "$arg thinks the root is $n\n";
- fred thinks the root is 3
-
- sub cube_root {
- my $arg = shift; # name doesn't matter
- $arg **= 1/3;
- return $arg;
- }
-
-The C<my> is simply a modifier on something you might assign to. So when
-you do assign to variables in its argument list, C<my> doesn't
-change whether those variables are viewed as a scalar or an array. So
-
- my ($foo) = <STDIN>; # WRONG?
- my @FOO = <STDIN>;
-
-both supply a list context to the right-hand side, while
-
- my $foo = <STDIN>;
-
-supplies a scalar context. But the following declares only one variable:
-
- my $foo, $bar = 1; # WRONG
-
-That has the same effect as
-
- my $foo;
- $bar = 1;
-
-The declared variable is not introduced (is not visible) until after
-the current statement. Thus,
-
- my $x = $x;
-
-can be used to initialize a new $x with the value of the old $x, and
-the expression
-
- my $x = 123 and $x == 123
-
-is false unless the old $x happened to have the value C<123>.
-
-Lexical scopes of control structures are not bounded precisely by the
-braces that delimit their controlled blocks; control expressions are
-part of that scope, too. Thus in the loop
-
- while (my $line = <>) {
- $line = lc $line;
- } continue {
- print $line;
- }
-
-the scope of $line extends from its declaration throughout the rest of
-the loop construct (including the C<continue> clause), but not beyond
-it. Similarly, in the conditional
-
- if ((my $answer = <STDIN>) =~ /^yes$/i) {
- user_agrees();
- } elsif ($answer =~ /^no$/i) {
- user_disagrees();
- } else {
- chomp $answer;
- die "'$answer' is neither 'yes' nor 'no'";
- }
-
-the scope of $answer extends from its declaration through the rest
-of that conditional, including any C<elsif> and C<else> clauses,
-but not beyond it. See L<perlsyn/"Simple Statements"> for information
-on the scope of variables in statements with modifiers.
-
-The C<foreach> loop defaults to scoping its index variable dynamically
-in the manner of C<local>. However, if the index variable is
-prefixed with the keyword C<my>, or if there is already a lexical
-by that name in scope, then a new lexical is created instead. Thus
-in the loop
-X<foreach> X<for>
-
- for my $i (1, 2, 3) {
- some_function();
- }
-
-the scope of $i extends to the end of the loop, but not beyond it,
-rendering the value of $i inaccessible within C<some_function()>.
-X<foreach> X<for>
-
-Some users may wish to encourage the use of lexically scoped variables.
-As an aid to catching implicit uses to package variables,
-which are always global, if you say
-
- use strict 'vars';
-
-then any variable mentioned from there to the end of the enclosing
-block must either refer to a lexical variable, be predeclared via
-C<our> or C<use vars>, or else must be fully qualified with the package name.
-A compilation error results otherwise. An inner block may countermand
-this with C<no strict 'vars'>.
-
-A C<my> has both a compile-time and a run-time effect. At compile
-time, the compiler takes notice of it. The principal usefulness
-of this is to quiet C<use strict 'vars'>, but it is also essential
-for generation of closures as detailed in L<perlref>. Actual
-initialization is delayed until run time, though, so it gets executed
-at the appropriate time, such as each time through a loop, for
-example.
-
-Variables declared with C<my> are not part of any package and are therefore
-never fully qualified with the package name. In particular, you're not
-allowed to try to make a package variable (or other global) lexical:
-
- my $pack::var; # ERROR! Illegal syntax
-
-In fact, a dynamic variable (also known as package or global variables)
-are still accessible using the fully qualified C<::> notation even while a
-lexical of the same name is also visible:
-
- package main;
- local $x = 10;
- my $x = 20;
- print "$x and $::x\n";
-
-That will print out C<20> and C<10>.
-
-You may declare C<my> variables at the outermost scope of a file
-to hide any such identifiers from the world outside that file. This
-is similar in spirit to C's static variables when they are used at
-the file level. To do this with a subroutine requires the use of
-a closure (an anonymous function that accesses enclosing lexicals).
-If you want to create a private subroutine that cannot be called
-from outside that block, it can declare a lexical variable containing
-an anonymous sub reference:
-
- my $secret_version = '1.001-beta';
- my $secret_sub = sub { print $secret_version };
- &$secret_sub();
-
-As long as the reference is never returned by any function within the
-module, no outside module can see the subroutine, because its name is not in
-any package's symbol table. Remember that it's not I<REALLY> called
-C<$some_pack::secret_version> or anything; it's just $secret_version,
-unqualified and unqualifiable.
-
-This does not work with object methods, however; all object methods
-have to be in the symbol table of some package to be found. See
-L<perlref/"Function Templates"> for something of a work-around to
-this.
-
-=head2 Persistent Private Variables
-X<state> X<state variable> X<static> X<variable, persistent> X<variable, static> X<closure>
-
-There are two ways to build persistent private variables in Perl 5.10.
-First, you can simply use the C<state> feature. Or, you can use closures,
-if you want to stay compatible with releases older than 5.10.
-
-=head3 Persistent variables via state()
-
-Beginning with Perl 5.9.4, you can declare variables with the C<state>
-keyword in place of C<my>. For that to work, though, you must have
-enabled that feature beforehand, either by using the C<feature> pragma, or
-by using C<-E> on one-liners (see L<feature>). Beginning with Perl 5.16,
-the C<CORE::state> form does not require the
-C<feature> pragma.
-
-For example, the following code maintains a private counter, incremented
-each time the gimme_another() function is called:
-
- use feature 'state';
- sub gimme_another { state $x; return ++$x }
-
-Also, since C<$x> is lexical, it can't be reached or modified by any Perl
-code outside.
-
-When combined with variable declaration, simple scalar assignment to C<state>
-variables (as in C<state $x = 42>) is executed only the first time. When such
-statements are evaluated subsequent times, the assignment is ignored. The
-behavior of this sort of assignment to non-scalar variables is undefined.
-
-=head3 Persistent variables with closures
-
-Just because a lexical variable is lexically (also called statically)
-scoped to its enclosing block, C<eval>, or C<do> FILE, this doesn't mean that
-within a function it works like a C static. It normally works more
-like a C auto, but with implicit garbage collection.
-
-Unlike local variables in C or C++, Perl's lexical variables don't
-necessarily get recycled just because their scope has exited.
-If something more permanent is still aware of the lexical, it will
-stick around. So long as something else references a lexical, that
-lexical won't be freed--which is as it should be. You wouldn't want
-memory being free until you were done using it, or kept around once you
-were done. Automatic garbage collection takes care of this for you.
-
-This means that you can pass back or save away references to lexical
-variables, whereas to return a pointer to a C auto is a grave error.
-It also gives us a way to simulate C's function statics. Here's a
-mechanism for giving a function private variables with both lexical
-scoping and a static lifetime. If you do want to create something like
-C's static variables, just enclose the whole function in an extra block,
-and put the static variable outside the function but in the block.
-
- {
- my $secret_val = 0;
- sub gimme_another {
- return ++$secret_val;
- }
- }
- # $secret_val now becomes unreachable by the outside
- # world, but retains its value between calls to gimme_another
-
-If this function is being sourced in from a separate file
-via C<require> or C<use>, then this is probably just fine. If it's
-all in the main program, you'll need to arrange for the C<my>
-to be executed early, either by putting the whole block above
-your main program, or more likely, placing merely a C<BEGIN>
-code block around it to make sure it gets executed before your program
-starts to run:
-
- BEGIN {
- my $secret_val = 0;
- sub gimme_another {
- return ++$secret_val;
- }
- }
-
-See L<perlmod/"BEGIN, UNITCHECK, CHECK, INIT and END"> about the
-special triggered code blocks, C<BEGIN>, C<UNITCHECK>, C<CHECK>,
-C<INIT> and C<END>.
-
-If declared at the outermost scope (the file scope), then lexicals
-work somewhat like C's file statics. They are available to all
-functions in that same file declared below them, but are inaccessible
-from outside that file. This strategy is sometimes used in modules
-to create private variables that the whole module can see.
-
-=head2 Temporary Values via local()
-X<local> X<scope, dynamic> X<dynamic scope> X<variable, local>
-X<variable, temporary>
-
-B<WARNING>: In general, you should be using C<my> instead of C<local>, because
-it's faster and safer. Exceptions to this include the global punctuation
-variables, global filehandles and formats, and direct manipulation of the
-Perl symbol table itself. C<local> is mostly used when the current value
-of a variable must be visible to called subroutines.
-
-Synopsis:
-
- # localization of values
-
- local $foo; # make $foo dynamically local
- local (@wid, %get); # make list of variables local
- local $foo = "flurp"; # make $foo dynamic, and init it
- local @oof = @bar; # make @oof dynamic, and init it
-
- local $hash{key} = "val"; # sets a local value for this hash entry
- delete local $hash{key}; # delete this entry for the current block
- local ($cond ? $v1 : $v2); # several types of lvalues support
- # localization
-
- # localization of symbols
-
- local *FH; # localize $FH, @FH, %FH, &FH ...
- local *merlyn = *randal; # now $merlyn is really $randal, plus
- # @merlyn is really @randal, etc
- local *merlyn = 'randal'; # SAME THING: promote 'randal' to *randal
- local *merlyn = \$randal; # just alias $merlyn, not @merlyn etc
-
-A C<local> modifies its listed variables to be "local" to the
-enclosing block, C<eval>, or C<do FILE>--and to I<any subroutine
-called from within that block>. A C<local> just gives temporary
-values to global (meaning package) variables. It does I<not> create
-a local variable. This is known as dynamic scoping. Lexical scoping
-is done with C<my>, which works more like C's auto declarations.
-
-Some types of lvalues can be localized as well: hash and array elements
-and slices, conditionals (provided that their result is always
-localizable), and symbolic references. As for simple variables, this
-creates new, dynamically scoped values.
-
-If more than one variable or expression is given to C<local>, they must be
-placed in parentheses. This operator works
-by saving the current values of those variables in its argument list on a
-hidden stack and restoring them upon exiting the block, subroutine, or
-eval. This means that called subroutines can also reference the local
-variable, but not the global one. The argument list may be assigned to if
-desired, which allows you to initialize your local variables. (If no
-initializer is given for a particular variable, it is created with an
-undefined value.)
-
-Because C<local> is a run-time operator, it gets executed each time
-through a loop. Consequently, it's more efficient to localize your
-variables outside the loop.
-
-=head3 Grammatical note on local()
-X<local, context>
-
-A C<local> is simply a modifier on an lvalue expression. When you assign to
-a C<local>ized variable, the C<local> doesn't change whether its list is viewed
-as a scalar or an array. So
-
- local($foo) = <STDIN>;
- local @FOO = <STDIN>;
-
-both supply a list context to the right-hand side, while
-
- local $foo = <STDIN>;
-
-supplies a scalar context.
-
-=head3 Localization of special variables
-X<local, special variable>
-
-If you localize a special variable, you'll be giving a new value to it,
-but its magic won't go away. That means that all side-effects related
-to this magic still work with the localized value.
-
-This feature allows code like this to work :
-
- # Read the whole contents of FILE in $slurp
- { local $/ = undef; $slurp = <FILE>; }
-
-Note, however, that this restricts localization of some values ; for
-example, the following statement dies, as of perl 5.9.0, with an error
-I<Modification of a read-only value attempted>, because the $1 variable is
-magical and read-only :
-
- local $1 = 2;
-
-One exception is the default scalar variable: starting with perl 5.14
-C<local($_)> will always strip all magic from $_, to make it possible
-to safely reuse $_ in a subroutine.
-
-B<WARNING>: Localization of tied arrays and hashes does not currently
-work as described.
-This will be fixed in a future release of Perl; in the meantime, avoid
-code that relies on any particular behaviour of localising tied arrays
-or hashes (localising individual elements is still okay).
-See L<perl58delta/"Localising Tied Arrays and Hashes Is Broken"> for more
-details.
-X<local, tie>
-
-=head3 Localization of globs
-X<local, glob> X<glob>
-
-The construct
-
- local *name;
-
-creates a whole new symbol table entry for the glob C<name> in the
-current package. That means that all variables in its glob slot ($name,
-@name, %name, &name, and the C<name> filehandle) are dynamically reset.
-
-This implies, among other things, that any magic eventually carried by
-those variables is locally lost. In other words, saying C<local */>
-will not have any effect on the internal value of the input record
-separator.
-
-=head3 Localization of elements of composite types
-X<local, composite type element> X<local, array element> X<local, hash element>
-
-It's also worth taking a moment to explain what happens when you
-C<local>ize a member of a composite type (i.e. an array or hash element).
-In this case, the element is C<local>ized I<by name>. This means that
-when the scope of the C<local()> ends, the saved value will be
-restored to the hash element whose key was named in the C<local()>, or
-the array element whose index was named in the C<local()>. If that
-element was deleted while the C<local()> was in effect (e.g. by a
-C<delete()> from a hash or a C<shift()> of an array), it will spring
-back into existence, possibly extending an array and filling in the
-skipped elements with C<undef>. For instance, if you say
-
- %hash = ( 'This' => 'is', 'a' => 'test' );
- @ary = ( 0..5 );
- {
- local($ary[5]) = 6;
- local($hash{'a'}) = 'drill';
- while (my $e = pop(@ary)) {
- print "$e . . .\n";
- last unless $e > 3;
- }
- if (@ary) {
- $hash{'only a'} = 'test';
- delete $hash{'a'};
- }
- }
- print join(' ', map { "$_ $hash{$_}" } sort keys %hash),".\n";
- print "The array has ",scalar(@ary)," elements: ",
- join(', ', map { defined $_ ? $_ : 'undef' } @ary),"\n";
-
-Perl will print
-
- 6 . . .
- 4 . . .
- 3 . . .
- This is a test only a test.
- The array has 6 elements: 0, 1, 2, undef, undef, 5
-
-The behavior of local() on non-existent members of composite
-types is subject to change in future.
-
-=head3 Localized deletion of elements of composite types
-X<delete> X<local, composite type element> X<local, array element> X<local, hash element>
-
-You can use the C<delete local $array[$idx]> and C<delete local $hash{key}>
-constructs to delete a composite type entry for the current block and restore
-it when it ends. They return the array/hash value before the localization,
-which means that they are respectively equivalent to
-
- do {
- my $val = $array[$idx];
- local $array[$idx];
- delete $array[$idx];
- $val
- }
-
-and
-
- do {
- my $val = $hash{key};
- local $hash{key};
- delete $hash{key};
- $val
- }
-
-except that for those the C<local> is scoped to the C<do> block. Slices are
-also accepted.
-
- my %hash = (
- a => [ 7, 8, 9 ],
- b => 1,
- )
-
- {
- my $a = delete local $hash{a};
- # $a is [ 7, 8, 9 ]
- # %hash is (b => 1)
-
- {
- my @nums = delete local @$a[0, 2]
- # @nums is (7, 9)
- # $a is [ undef, 8 ]
-
- $a[0] = 999; # will be erased when the scope ends
- }
- # $a is back to [ 7, 8, 9 ]
-
- }
- # %hash is back to its original state
-
-=head2 Lvalue subroutines
-X<lvalue> X<subroutine, lvalue>
-
-B<WARNING>: Lvalue subroutines are still experimental and the
-implementation may change in future versions of Perl.
-
-It is possible to return a modifiable value from a subroutine.
-To do this, you have to declare the subroutine to return an lvalue.
-
- my $val;
- sub canmod : lvalue {
- $val; # or: return $val;
- }
- sub nomod {
- $val;
- }
-
- canmod() = 5; # assigns to $val
- nomod() = 5; # ERROR
-
-The scalar/list context for the subroutine and for the right-hand
-side of assignment is determined as if the subroutine call is replaced
-by a scalar. For example, consider:
-
- data(2,3) = get_data(3,4);
-
-Both subroutines here are called in a scalar context, while in:
-
- (data(2,3)) = get_data(3,4);
-
-and in:
-
- (data(2),data(3)) = get_data(3,4);
-
-all the subroutines are called in a list context.
-
-=over 4
-
-=item Lvalue subroutines are EXPERIMENTAL
-
-They appear to be convenient, but there is at least one reason to be
-circumspect.
-
-They violate encapsulation. A normal mutator can check the supplied
-argument before setting the attribute it is protecting, an lvalue
-subroutine never gets that chance. Consider;
-
- my $some_array_ref = []; # protected by mutators ??
-
- sub set_arr { # normal mutator
- my $val = shift;
- die("expected array, you supplied ", ref $val)
- unless ref $val eq 'ARRAY';
- $some_array_ref = $val;
- }
- sub set_arr_lv : lvalue { # lvalue mutator
- $some_array_ref;
- }
-
- # set_arr_lv cannot stop this !
- set_arr_lv() = { a => 1 };
-
-=back
-
-=head2 Passing Symbol Table Entries (typeglobs)
-X<typeglob> X<*>
-
-B<WARNING>: The mechanism described in this section was originally
-the only way to simulate pass-by-reference in older versions of
-Perl. While it still works fine in modern versions, the new reference
-mechanism is generally easier to work with. See below.
-
-Sometimes you don't want to pass the value of an array to a subroutine
-but rather the name of it, so that the subroutine can modify the global
-copy of it rather than working with a local copy. In perl you can
-refer to all objects of a particular name by prefixing the name
-with a star: C<*foo>. This is often known as a "typeglob", because the
-star on the front can be thought of as a wildcard match for all the
-funny prefix characters on variables and subroutines and such.
-
-When evaluated, the typeglob produces a scalar value that represents
-all the objects of that name, including any filehandle, format, or
-subroutine. When assigned to, it causes the name mentioned to refer to
-whatever C<*> value was assigned to it. Example:
-
- sub doubleary {
- local(*someary) = @_;
- foreach $elem (@someary) {
- $elem *= 2;
- }
- }
- doubleary(*foo);
- doubleary(*bar);
-
-Scalars are already passed by reference, so you can modify
-scalar arguments without using this mechanism by referring explicitly
-to C<$_[0]> etc. You can modify all the elements of an array by passing
-all the elements as scalars, but you have to use the C<*> mechanism (or
-the equivalent reference mechanism) to C<push>, C<pop>, or change the size of
-an array. It will certainly be faster to pass the typeglob (or reference).
-
-Even if you don't want to modify an array, this mechanism is useful for
-passing multiple arrays in a single LIST, because normally the LIST
-mechanism will merge all the array values so that you can't extract out
-the individual arrays. For more on typeglobs, see
-L<perldata/"Typeglobs and Filehandles">.
-
-=head2 When to Still Use local()
-X<local> X<variable, local>
-
-Despite the existence of C<my>, there are still three places where the
-C<local> operator still shines. In fact, in these three places, you
-I<must> use C<local> instead of C<my>.
-
-=over 4
-
-=item 1.
-
-You need to give a global variable a temporary value, especially $_.
-
-The global variables, like C<@ARGV> or the punctuation variables, must be
-C<local>ized with C<local()>. This block reads in F</etc/motd>, and splits
-it up into chunks separated by lines of equal signs, which are placed
-in C<@Fields>.
-
- {
- local @ARGV = ("/etc/motd");
- local $/ = undef;
- local $_ = <>;
- @Fields = split /^\s*=+\s*$/;
- }
-
-It particular, it's important to C<local>ize $_ in any routine that assigns
-to it. Look out for implicit assignments in C<while> conditionals.
-
-=item 2.
-
-You need to create a local file or directory handle or a local function.
-
-A function that needs a filehandle of its own must use
-C<local()> on a complete typeglob. This can be used to create new symbol
-table entries:
-
- sub ioqueue {
- local (*READER, *WRITER); # not my!
- pipe (READER, WRITER) or die "pipe: $!";
- return (*READER, *WRITER);
- }
- ($head, $tail) = ioqueue();
-
-See the Symbol module for a way to create anonymous symbol table
-entries.
-
-Because assignment of a reference to a typeglob creates an alias, this
-can be used to create what is effectively a local function, or at least,
-a local alias.
-
- {
- local *grow = \&shrink; # only until this block exits
- grow(); # really calls shrink()
- move(); # if move() grow()s, it shrink()s too
- }
- grow(); # get the real grow() again
-
-See L<perlref/"Function Templates"> for more about manipulating
-functions by name in this way.
-
-=item 3.
-
-You want to temporarily change just one element of an array or hash.
-
-You can C<local>ize just one element of an aggregate. Usually this
-is done on dynamics:
-
- {
- local $SIG{INT} = 'IGNORE';
- funct(); # uninterruptible
- }
- # interruptibility automatically restored here
-
-But it also works on lexically declared aggregates. Prior to 5.005,
-this operation could on occasion misbehave.
-
-=back
-
-=head2 Pass by Reference
-X<pass by reference> X<pass-by-reference> X<reference>
-
-If you want to pass more than one array or hash into a function--or
-return them from it--and have them maintain their integrity, then
-you're going to have to use an explicit pass-by-reference. Before you
-do that, you need to understand references as detailed in L<perlref>.
-This section may not make much sense to you otherwise.
-
-Here are a few simple examples. First, let's pass in several arrays
-to a function and have it C<pop> all of then, returning a new list
-of all their former last elements:
-
- @tailings = popmany ( \@a, \@b, \@c, \@d );
-
- sub popmany {
- my $aref;
- my @retlist = ();
- foreach $aref ( @_ ) {
- push @retlist, pop @$aref;
- }
- return @retlist;
- }
-
-Here's how you might write a function that returns a
-list of keys occurring in all the hashes passed to it:
-
- @common = inter( \%foo, \%bar, \%joe );
- sub inter {
- my ($k, $href, %seen); # locals
- foreach $href (@_) {
- while ( $k = each %$href ) {
- $seen{$k}++;
- }
- }
- return grep { $seen{$_} == @_ } keys %seen;
- }
-
-So far, we're using just the normal list return mechanism.
-What happens if you want to pass or return a hash? Well,
-if you're using only one of them, or you don't mind them
-concatenating, then the normal calling convention is ok, although
-a little expensive.
-
-Where people get into trouble is here:
-
- (@a, @b) = func(@c, @d);
-or
- (%a, %b) = func(%c, %d);
-
-That syntax simply won't work. It sets just C<@a> or C<%a> and
-clears the C<@b> or C<%b>. Plus the function didn't get passed
-into two separate arrays or hashes: it got one long list in C<@_>,
-as always.
-
-If you can arrange for everyone to deal with this through references, it's
-cleaner code, although not so nice to look at. Here's a function that
-takes two array references as arguments, returning the two array elements
-in order of how many elements they have in them:
-
- ($aref, $bref) = func(\@c, \@d);
- print "@$aref has more than @$bref\n";
- sub func {
- my ($cref, $dref) = @_;
- if (@$cref > @$dref) {
- return ($cref, $dref);
- } else {
- return ($dref, $cref);
- }
- }
-
-It turns out that you can actually do this also:
-
- (*a, *b) = func(\@c, \@d);
- print "@a has more than @b\n";
- sub func {
- local (*c, *d) = @_;
- if (@c > @d) {
- return (\@c, \@d);
- } else {
- return (\@d, \@c);
- }
- }
-
-Here we're using the typeglobs to do symbol table aliasing. It's
-a tad subtle, though, and also won't work if you're using C<my>
-variables, because only globals (even in disguise as C<local>s)
-are in the symbol table.
-
-If you're passing around filehandles, you could usually just use the bare
-typeglob, like C<*STDOUT>, but typeglobs references work, too.
-For example:
-
- splutter(\*STDOUT);
- sub splutter {
- my $fh = shift;
- print $fh "her um well a hmmm\n";
- }
-
- $rec = get_rec(\*STDIN);
- sub get_rec {
- my $fh = shift;
- return scalar <$fh>;
- }
-
-If you're planning on generating new filehandles, you could do this.
-Notice to pass back just the bare *FH, not its reference.
-
- sub openit {
- my $path = shift;
- local *FH;
- return open (FH, $path) ? *FH : undef;
- }
-
-=head2 Prototypes
-X<prototype> X<subroutine, prototype>
-
-Perl supports a very limited kind of compile-time argument checking
-using function prototyping. If you declare
-
- sub mypush (+@)
-
-then C<mypush()> takes arguments exactly like C<push()> does. The
-function declaration must be visible at compile time. The prototype
-affects only interpretation of new-style calls to the function,
-where new-style is defined as not using the C<&> character. In
-other words, if you call it like a built-in function, then it behaves
-like a built-in function. If you call it like an old-fashioned
-subroutine, then it behaves like an old-fashioned subroutine. It
-naturally falls out from this rule that prototypes have no influence
-on subroutine references like C<\&foo> or on indirect subroutine
-calls like C<&{$subref}> or C<< $subref->() >>.
-
-Method calls are not influenced by prototypes either, because the
-function to be called is indeterminate at compile time, since
-the exact code called depends on inheritance.
-
-Because the intent of this feature is primarily to let you define
-subroutines that work like built-in functions, here are prototypes
-for some other functions that parse almost exactly like the
-corresponding built-in.
-
- Declared as Called as
-
- sub mylink ($$) mylink $old, $new
- sub myvec ($$$) myvec $var, $offset, 1
- sub myindex ($$;$) myindex &getstring, "substr"
- sub mysyswrite ($$$;$) mysyswrite $buf, 0, length($buf) - $off, $off
- sub myreverse (@) myreverse $a, $b, $c
- sub myjoin ($@) myjoin ":", $a, $b, $c
- sub mypop (+) mypop @array
- sub mysplice (+$$@) mysplice @array, 0, 2, @pushme
- sub mykeys (+) mykeys %{$hashref}
- sub myopen (*;$) myopen HANDLE, $name
- sub mypipe (**) mypipe READHANDLE, WRITEHANDLE
- sub mygrep (&@) mygrep { /foo/ } $a, $b, $c
- sub myrand (;$) myrand 42
- sub mytime () mytime
-
-Any backslashed prototype character represents an actual argument
-that must start with that character (optionally preceded by C<my>,
-C<our> or C<local>), with the exception of C<$>, which will
-accept any scalar lvalue expression, such as C<$foo = 7> or
-C<< my_function()->[0] >>. The value passed as part of C<@_> will be a
-reference to the actual argument given in the subroutine call,
-obtained by applying C<\> to that argument.
-
-You can use the C<\[]> backslash group notation to specify more than one
-allowed argument type. For example:
-
- sub myref (\[$@%&*])
-
-will allow calling myref() as
-
- myref $var
- myref @array
- myref %hash
- myref &sub
- myref *glob
-
-and the first argument of myref() will be a reference to
-a scalar, an array, a hash, a code, or a glob.
-
-Unbackslashed prototype characters have special meanings. Any
-unbackslashed C<@> or C<%> eats all remaining arguments, and forces
-list context. An argument represented by C<$> forces scalar context. An
-C<&> requires an anonymous subroutine, which, if passed as the first
-argument, does not require the C<sub> keyword or a subsequent comma.
-
-A C<*> allows the subroutine to accept a bareword, constant, scalar expression,
-typeglob, or a reference to a typeglob in that slot. The value will be
-available to the subroutine either as a simple scalar, or (in the latter
-two cases) as a reference to the typeglob. If you wish to always convert
-such arguments to a typeglob reference, use Symbol::qualify_to_ref() as
-follows:
-
- use Symbol 'qualify_to_ref';
-
- sub foo (*) {
- my $fh = qualify_to_ref(shift, caller);
- ...
- }
-
-The C<+> prototype is a special alternative to C<$> that will act like
-C<\[@%]> when given a literal array or hash variable, but will otherwise
-force scalar context on the argument. This is useful for functions which
-should accept either a literal array or an array reference as the argument:
-
- sub mypush (+@) {
- my $aref = shift;
- die "Not an array or arrayref" unless ref $aref eq 'ARRAY';
- push @$aref, @_;
- }
-
-When using the C<+> prototype, your function must check that the argument
-is of an acceptable type.
-
-A semicolon (C<;>) separates mandatory arguments from optional arguments.
-It is redundant before C<@> or C<%>, which gobble up everything else.
-
-As the last character of a prototype, or just before a semicolon, a C<@>
-or a C<%>, you can use C<_> in place of C<$>: if this argument is not
-provided, C<$_> will be used instead.
-
-Note how the last three examples in the table above are treated
-specially by the parser. C<mygrep()> is parsed as a true list
-operator, C<myrand()> is parsed as a true unary operator with unary
-precedence the same as C<rand()>, and C<mytime()> is truly without
-arguments, just like C<time()>. That is, if you say
-
- mytime +2;
-
-you'll get C<mytime() + 2>, not C<mytime(2)>, which is how it would be parsed
-without a prototype. If you want to force a unary function to have the
-same precedence as a list operator, add C<;> to the end of the prototype:
-
- sub mygetprotobynumber($;);
- mygetprotobynumber $a > $b; # parsed as mygetprotobynumber($a > $b)
-
-The interesting thing about C<&> is that you can generate new syntax with it,
-provided it's in the initial position:
-X<&>
-
- sub try (&@) {
- my($try,$catch) = @_;
- eval { &$try };
- if ($@) {
- local $_ = $@;
- &$catch;
- }
- }
- sub catch (&) { $_[0] }
-
- try {
- die "phooey";
- } catch {
- /phooey/ and print "unphooey\n";
- };
-
-That prints C<"unphooey">. (Yes, there are still unresolved
-issues having to do with visibility of C<@_>. I'm ignoring that
-question for the moment. (But note that if we make C<@_> lexically
-scoped, those anonymous subroutines can act like closures... (Gee,
-is this sounding a little Lispish? (Never mind.))))
-
-And here's a reimplementation of the Perl C<grep> operator:
-X<grep>
-
- sub mygrep (&@) {
- my $code = shift;
- my @result;
- foreach $_ (@_) {
- push(@result, $_) if &$code;
- }
- @result;
- }
-
-Some folks would prefer full alphanumeric prototypes. Alphanumerics have
-been intentionally left out of prototypes for the express purpose of
-someday in the future adding named, formal parameters. The current
-mechanism's main goal is to let module writers provide better diagnostics
-for module users. Larry feels the notation quite understandable to Perl
-programmers, and that it will not intrude greatly upon the meat of the
-module, nor make it harder to read. The line noise is visually
-encapsulated into a small pill that's easy to swallow.
-
-If you try to use an alphanumeric sequence in a prototype you will
-generate an optional warning - "Illegal character in prototype...".
-Unfortunately earlier versions of Perl allowed the prototype to be
-used as long as its prefix was a valid prototype. The warning may be
-upgraded to a fatal error in a future version of Perl once the
-majority of offending code is fixed.
-
-It's probably best to prototype new functions, not retrofit prototyping
-into older ones. That's because you must be especially careful about
-silent impositions of differing list versus scalar contexts. For example,
-if you decide that a function should take just one parameter, like this:
-
- sub func ($) {
- my $n = shift;
- print "you gave me $n\n";
- }
-
-and someone has been calling it with an array or expression
-returning a list:
-
- func(@foo);
- func( split /:/ );
-
-Then you've just supplied an automatic C<scalar> in front of their
-argument, which can be more than a bit surprising. The old C<@foo>
-which used to hold one thing doesn't get passed in. Instead,
-C<func()> now gets passed in a C<1>; that is, the number of elements
-in C<@foo>. And the C<split> gets called in scalar context so it
-starts scribbling on your C<@_> parameter list. Ouch!
-
-This is all very powerful, of course, and should be used only in moderation
-to make the world a better place.
-
-=head2 Constant Functions
-X<constant>
-
-Functions with a prototype of C<()> are potential candidates for
-inlining. If the result after optimization and constant folding
-is either a constant or a lexically-scoped scalar which has no other
-references, then it will be used in place of function calls made
-without C<&>. Calls made using C<&> are never inlined. (See
-F<constant.pm> for an easy way to declare most constants.)
-
-The following functions would all be inlined:
-
- sub pi () { 3.14159 } # Not exact, but close.
- sub PI () { 4 * atan2 1, 1 } # As good as it gets,
- # and it's inlined, too!
- sub ST_DEV () { 0 }
- sub ST_INO () { 1 }
-
- sub FLAG_FOO () { 1 << 8 }
- sub FLAG_BAR () { 1 << 9 }
- sub FLAG_MASK () { FLAG_FOO | FLAG_BAR }
-
- sub OPT_BAZ () { not (0x1B58 & FLAG_MASK) }
-
- sub N () { int(OPT_BAZ) / 3 }
-
- sub FOO_SET () { 1 if FLAG_MASK & FLAG_FOO }
-
-Be aware that these will not be inlined; as they contain inner scopes,
-the constant folding doesn't reduce them to a single constant:
-
- sub foo_set () { if (FLAG_MASK & FLAG_FOO) { 1 } }
-
- sub baz_val () {
- if (OPT_BAZ) {
- return 23;
- }
- else {
- return 42;
- }
- }
-
-If you redefine a subroutine that was eligible for inlining, you'll get
-a warning by default. (You can use this warning to tell whether or not a
-particular subroutine is considered constant.) The warning is
-considered severe enough not to be affected by the B<-w>
-switch (or its absence) because previously compiled
-invocations of the function will still be using the old value of the
-function. If you need to be able to redefine the subroutine, you need to
-ensure that it isn't inlined, either by dropping the C<()> prototype
-(which changes calling semantics, so beware) or by thwarting the
-inlining mechanism in some other way, such as
-
- sub not_inlined () {
- 23 if $];
- }
-
-=head2 Overriding Built-in Functions
-X<built-in> X<override> X<CORE> X<CORE::GLOBAL>
-
-Many built-in functions may be overridden, though this should be tried
-only occasionally and for good reason. Typically this might be
-done by a package attempting to emulate missing built-in functionality
-on a non-Unix system.
-
-Overriding may be done only by importing the name from a module at
-compile time--ordinary predeclaration isn't good enough. However, the
-C<use subs> pragma lets you, in effect, predeclare subs
-via the import syntax, and these names may then override built-in ones:
-
- use subs 'chdir', 'chroot', 'chmod', 'chown';
- chdir $somewhere;
- sub chdir { ... }
-
-To unambiguously refer to the built-in form, precede the
-built-in name with the special package qualifier C<CORE::>. For example,
-saying C<CORE::open()> always refers to the built-in C<open()>, even
-if the current package has imported some other subroutine called
-C<&open()> from elsewhere. Even though it looks like a regular
-function call, it isn't: the CORE:: prefix in that case is part of Perl's
-syntax, and works for any keyword, regardless of what is in the CORE
-package. Taking a reference to it, that is, C<\&CORE::open>, only works
-for some keywords. See L<CORE>.
-
-Library modules should not in general export built-in names like C<open>
-or C<chdir> as part of their default C<@EXPORT> list, because these may
-sneak into someone else's namespace and change the semantics unexpectedly.
-Instead, if the module adds that name to C<@EXPORT_OK>, then it's
-possible for a user to import the name explicitly, but not implicitly.
-That is, they could say
-
- use Module 'open';
-
-and it would import the C<open> override. But if they said
-
- use Module;
-
-they would get the default imports without overrides.
-
-The foregoing mechanism for overriding built-in is restricted, quite
-deliberately, to the package that requests the import. There is a second
-method that is sometimes applicable when you wish to override a built-in
-everywhere, without regard to namespace boundaries. This is achieved by
-importing a sub into the special namespace C<CORE::GLOBAL::>. Here is an
-example that quite brazenly replaces the C<glob> operator with something
-that understands regular expressions.
-
- package REGlob;
- require Exporter;
- @ISA = 'Exporter';
- @EXPORT_OK = 'glob';
-
- sub import {
- my $pkg = shift;
- return unless @_;
- my $sym = shift;
- my $where = ($sym =~ s/^GLOBAL_// ? 'CORE::GLOBAL' : caller(0));
- $pkg->export($where, $sym, @_);
- }
-
- sub glob {
- my $pat = shift;
- my @got;
- if (opendir my $d, '.') {
- @got = grep /$pat/, readdir $d;
- closedir $d;
- }
- return @got;
- }
- 1;
-
-And here's how it could be (ab)used:
-
- #use REGlob 'GLOBAL_glob'; # override glob() in ALL namespaces
- package Foo;
- use REGlob 'glob'; # override glob() in Foo:: only
- print for <^[a-z_]+\.pm\$>; # show all pragmatic modules
-
-The initial comment shows a contrived, even dangerous example.
-By overriding C<glob> globally, you would be forcing the new (and
-subversive) behavior for the C<glob> operator for I<every> namespace,
-without the complete cognizance or cooperation of the modules that own
-those namespaces. Naturally, this should be done with extreme caution--if
-it must be done at all.
-
-The C<REGlob> example above does not implement all the support needed to
-cleanly override perl's C<glob> operator. The built-in C<glob> has
-different behaviors depending on whether it appears in a scalar or list
-context, but our C<REGlob> doesn't. Indeed, many perl built-in have such
-context sensitive behaviors, and these must be adequately supported by
-a properly written override. For a fully functional example of overriding
-C<glob>, study the implementation of C<File::DosGlob> in the standard
-library.
-
-When you override a built-in, your replacement should be consistent (if
-possible) with the built-in native syntax. You can achieve this by using
-a suitable prototype. To get the prototype of an overridable built-in,
-use the C<prototype> function with an argument of C<"CORE::builtin_name">
-(see L<perlfunc/prototype>).
-
-Note however that some built-ins can't have their syntax expressed by a
-prototype (such as C<system> or C<chomp>). If you override them you won't
-be able to fully mimic their original syntax.
-
-The built-ins C<do>, C<require> and C<glob> can also be overridden, but due
-to special magic, their original syntax is preserved, and you don't have
-to define a prototype for their replacements. (You can't override the
-C<do BLOCK> syntax, though).
-
-C<require> has special additional dark magic: if you invoke your
-C<require> replacement as C<require Foo::Bar>, it will actually receive
-the argument C<"Foo/Bar.pm"> in @_. See L<perlfunc/require>.
-
-And, as you'll have noticed from the previous example, if you override
-C<glob>, the C<< <*> >> glob operator is overridden as well.
-
-In a similar fashion, overriding the C<readline> function also overrides
-the equivalent I/O operator C<< <FILEHANDLE> >>. Also, overriding
-C<readpipe> also overrides the operators C<``> and C<qx//>.
-
-Finally, some built-ins (e.g. C<exists> or C<grep>) can't be overridden.
-
-=head2 Autoloading
-X<autoloading> X<AUTOLOAD>
-
-If you call a subroutine that is undefined, you would ordinarily
-get an immediate, fatal error complaining that the subroutine doesn't
-exist. (Likewise for subroutines being used as methods, when the
-method doesn't exist in any base class of the class's package.)
-However, if an C<AUTOLOAD> subroutine is defined in the package or
-packages used to locate the original subroutine, then that
-C<AUTOLOAD> subroutine is called with the arguments that would have
-been passed to the original subroutine. The fully qualified name
-of the original subroutine magically appears in the global $AUTOLOAD
-variable of the same package as the C<AUTOLOAD> routine. The name
-is not passed as an ordinary argument because, er, well, just
-because, that's why. (As an exception, a method call to a nonexistent
-C<import> or C<unimport> method is just skipped instead. Also, if
-the AUTOLOAD subroutine is an XSUB, there are other ways to retrieve the
-subroutine name. See L<perlguts/Autoloading with XSUBs> for details.)
-
-
-Many C<AUTOLOAD> routines load in a definition for the requested
-subroutine using eval(), then execute that subroutine using a special
-form of goto() that erases the stack frame of the C<AUTOLOAD> routine
-without a trace. (See the source to the standard module documented
-in L<AutoLoader>, for example.) But an C<AUTOLOAD> routine can
-also just emulate the routine and never define it. For example,
-let's pretend that a function that wasn't defined should just invoke
-C<system> with those arguments. All you'd do is:
-
- sub AUTOLOAD {
- my $program = $AUTOLOAD;
- $program =~ s/.*:://;
- system($program, @_);
- }
- date();
- who('am', 'i');
- ls('-l');
-
-In fact, if you predeclare functions you want to call that way, you don't
-even need parentheses:
-
- use subs qw(date who ls);
- date;
- who "am", "i";
- ls '-l';
-
-A more complete example of this is the Shell module on CPAN, which
-can treat undefined subroutine calls as calls to external programs.
-
-Mechanisms are available to help modules writers split their modules
-into autoloadable files. See the standard AutoLoader module
-described in L<AutoLoader> and in L<AutoSplit>, the standard
-SelfLoader modules in L<SelfLoader>, and the document on adding C
-functions to Perl code in L<perlxs>.
-
-=head2 Subroutine Attributes
-X<attribute> X<subroutine, attribute> X<attrs>
-
-A subroutine declaration or definition may have a list of attributes
-associated with it. If such an attribute list is present, it is
-broken up at space or colon boundaries and treated as though a
-C<use attributes> had been seen. See L<attributes> for details
-about what attributes are currently supported.
-Unlike the limitation with the obsolescent C<use attrs>, the
-C<sub : ATTRLIST> syntax works to associate the attributes with
-a pre-declaration, and not just with a subroutine definition.
-
-The attributes must be valid as simple identifier names (without any
-punctuation other than the '_' character). They may have a parameter
-list appended, which is only checked for whether its parentheses ('(',')')
-nest properly.
-
-Examples of valid syntax (even though the attributes are unknown):
-
- sub fnord (&\%) : switch(10,foo(7,3)) : expensive;
- sub plugh () : Ugly('\(") :Bad;
- sub xyzzy : _5x5 { ... }
-
-Examples of invalid syntax:
-
- sub fnord : switch(10,foo(); # ()-string not balanced
- sub snoid : Ugly('('); # ()-string not balanced
- sub xyzzy : 5x5; # "5x5" not a valid identifier
- sub plugh : Y2::north; # "Y2::north" not a simple identifier
- sub snurt : foo + bar; # "+" not a colon or space
-
-The attribute list is passed as a list of constant strings to the code
-which associates them with the subroutine. In particular, the second example
-of valid syntax above currently looks like this in terms of how it's
-parsed and invoked:
-
- use attributes __PACKAGE__, \&plugh, q[Ugly('\(")], 'Bad';
-
-For further details on attribute lists and their manipulation,
-see L<attributes> and L<Attribute::Handlers>.
-
-=head1 SEE ALSO
-
-See L<perlref/"Function Templates"> for more about references and closures.
-See L<perlxs> if you'd like to learn about calling C subroutines from Perl.
-See L<perlembed> if you'd like to learn about calling Perl subroutines from C.
-See L<perlmod> to learn about bundling up your functions in separate files.
-See L<perlmodlib> to learn what library modules come standard on your system.
-See L<perlootut> to learn how to make object method calls.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlsymbian.pod b/Master/tlpkg/tlperl/lib/pods/perlsymbian.pod
deleted file mode 100644
index 2572631c12a..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlsymbian.pod
+++ /dev/null
@@ -1,432 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you see.
-It is written in the POD format (see pod/perlpod.pod) which is specially
-designed to be readable as is.
-
-=head1 NAME
-
-perlsymbian - Perl version 5 on Symbian OS
-
-=head1 DESCRIPTION
-
-This document describes various features of the Symbian operating
-system that will affect how Perl version 5 (hereafter just Perl)
-is compiled and/or runs.
-
-B<NOTE: this port (as of 0.4.1) does not compile into a Symbian
-OS GUI application, but instead it results in a Symbian DLL.>
-The DLL includes a C++ class called CPerlBase, which one can then
-(derive from and) use to embed Perl into applications, see F<symbian/README>.
-
-The base port of Perl to Symbian only implements the basic POSIX-like
-functionality; it does not implement any further Symbian or Series 60,
-Series 80, or UIQ bindings for Perl.
-
-It is also possible to generate Symbian executables for "miniperl"
-and "perl", but since there is no standard command line interface
-for Symbian (nor full keyboards in the devices), these are useful
-mainly as demonstrations.
-
-=head2 Compiling Perl on Symbian
-
-(0) You need to have the appropriate Symbian SDK installed.
-
- These instructions have been tested under various Nokia Series 60
- Symbian SDKs (1.2 to 2.6, 2.8 should also work, 1.2 compiles but
- does not work), Series 80 2.0, and Nokia 7710 (Series 90) SDK.
- You can get the SDKs from Forum Nokia (L<http://www.forum.nokia.com/>).
- A very rough port ("it compiles") to UIQ 2.1 has also been made.
-
- A prerequisite for any of the SDKs is to install ActivePerl
- from ActiveState, L<http://www.activestate.com/Products/ActivePerl/>
-
- Having the SDK installed also means that you need to have either
- the Metrowerks CodeWarrior installed (2.8 and 3.0 were used in testing)
- or the Microsoft Visual C++ 6.0 installed (SP3 minimum, SP5 recommended).
-
- Note that for example the Series 60 2.0 VC SDK installation talks
- about ActivePerl build 518, which does no more (as of mid-2005) exist
- at the ActiveState website. The ActivePerl 5.8.4 build 810 was
- used successfully for compiling Perl on Symbian. The 5.6.x ActivePerls
- do not work.
-
- Other SDKs or compilers like Visual.NET, command-line-only
- Visual.NET, Borland, GnuPoc, or sdk2unix have not been tried.
-
- These instructions almost certainly won't work with older Symbian
- releases or other SDKs. Patches to get this port running in other
- releases, SDKs, compilers, platforms, or devices are naturally welcome.
-
-(1) Get a Perl source code distribution (for example the file
- perl-5.9.2.tar.gz is fine) from L<http://www.cpan.org/src/>
- and unpack it in your the C:/Symbian directory of your Windows
- system.
-
-(2) Change to the perl source directory.
-
- cd c:\Symbian\perl-5.x.x
-
-(3) Run the following script using the perl coming with the SDK
-
- perl symbian\config.pl
-
- You must use the cmd.exe, the Cygwin shell will not work.
- The PATH must include the SDK tools, including a Perl,
- which should be the case under cmd.exe. If you do not
- have that, see the end of symbian\sdk.pl for notes of
- how your environment should be set up for Symbian compiles.
-
-(4) Build the project, either by
-
- make all
-
- in cmd.exe or by using either the Metrowerks CodeWarrior
- or the Visual C++ 6.0, or the Visual Studio 8 (the Visual C++
- 2005 Express Edition works fine).
-
- If you use the VC IDE, you will have to run F<symbian\config.pl>
- first using the cmd.exe, and then run 'make win.mf vc6.mf' to generate
- the VC6 makefiles and workspaces. "make vc6" will compile for the VC6,
- and "make cw" for the CodeWarrior.
-
- The following SDK and compiler configurations and Nokia phones were
- tested at some point in time (+ = compiled and PerlApp run, - = not),
- both for Perl 5.8.x and 5.9.x:
-
- SDK | VC | CW |
- --------+----+----+---
- S60 1.2 | + | + | 3650 (*)
- S60 2.0 | + | + | 6600
- S60 2.1 | - | + | 6670
- S60 2.6 | + | + | 6630
- S60 2.8 | + | + | (not tested in a device)
- S80 2.6 | - | + | 9300
- S90 1.1 | + | - | 7710
- UIQ 2.1 | - | + | (not tested in a device)
-
- (*) Compiles but does not work, unfortunately, a problem with Symbian.
-
- If you are using the 'make' directly, it is the GNU make from the SDKs,
- and it will invoke the right make commands for the Windows emulator
- build and the Arm target builds ('thumb' by default) as necessary.
-
- The build scripts assume the 'absolute style' SDK installs under C:,
- the 'subst style' will not work.
-
- If using the VC IDE, to build use for example the File->Open Workspace->
- C:\Symbian\8.0a\S60_2nd_FP2\epoc32\build\symbian\perl\perl\wins\perl.dsw
- The emulator binaries will appear in the same directory.
-
- If using the VC IDE, you will a lot of warnings in the beginning of
- the build because a lot of headers mentioned by the source cannot
- be found, but this is not serious since those headers are not used.
-
- The Metrowerks will give a lot of warnings about unused variables and
- empty declarations, you can ignore those.
-
- When the Windows and Arm DLLs are built do not be scared by a very long
- messages whizzing by: it is the "export freeze" phase where the whole
- (rather large) API of Perl is listed.
-
- Once the build is completed you need to create the DLL SIS file by
-
- make perldll.sis
-
- which will create the file perlXYZ.sis (the XYZ being the Perl version)
- which you can then install into your Symbian device: an easy way
- to do this is to send them via Bluetooth or infrared and just open
- the messages.
-
- Since the total size of all Perl SIS files once installed is
- over 2 MB, it is recommended to do the installation into a
- memory card (drive E:) instead of the C: drive.
-
- The size of the perlXYZ.SIS is about 370 kB but once it is in the
- device it is about one 750 kB (according to the application manager).
-
- The perlXYZ.sis includes only the Perl DLL: to create an additional
- SIS file which includes some of the standard (pure) Perl libraries,
- issue the command
-
- make perllib.sis
-
- Some of the standard Perl libraries are included, but not all:
- see L</HISTORY> or F<symbian\install.cfg> for more details
- (250 kB -> 700 kB).
-
- Some of the standard Perl XS extensions (see L</HISTORY> are
- also available:
-
- make perlext.sis
-
- which will create perlXYZext.sis (290 kB -> 770 kB).
-
- To compile the demonstration application PerlApp you need first to
- install the Perl headers under the SDK.
-
- To install the Perl headers and the class CPerlBase documentation
- so that you no more need the Perl sources around to compile Perl
- applications using the SDK:
-
- make sdkinstall
-
- The destination directory is C:\Symbian\perl\X.Y.Z. For more
- details, see F<symbian\PerlBase.pod>.
-
- Once the headers have been installed, you can create a SIS for
- the PerlApp:
-
- make perlapp.sis
-
- The perlapp.sis (11 kB -> 16 kB) will be built in the symbian
- subdirectory, but a copy will also be made to the main directory.
-
- If you want to package the Perl DLLs (one for WINS, one for ARMI),
- the headers, and the documentation:
-
- make perlsdk.zip
-
- which will create perlXYZsdk.zip that can be used in another
- Windows system with the SDK, without having to compile Perl in
- that system.
-
- If you want to package the PerlApp sources:
-
- make perlapp.zip
-
- If you want to package the perl.exe and miniperl.exe, you
- can use the perlexe.sis and miniperlexe.sis make targets.
- You also probably want the perllib.sis for the libraries
- and maybe even the perlapp.sis for the recognizer.
-
- The make target 'allsis' combines all the above SIS targets.
-
- To clean up after compilation you can use either of
-
- make clean
- make distclean
-
- depending on how clean you want to be.
-
-=head2 Compilation problems
-
-If you see right after "make" this
-
- cat makefile.sh >makefile
- 'cat' is not recognized as an internal or external command,
- operable program or batch file.
-
-it means you need to (re)run the F<symbian\config.pl>.
-
-If you get the error
-
- 'perl' is not recognized as an internal or external command,
- operable program or batch file.
-
-you may need to reinstall the ActivePerl.
-
-If you see this
-
- ren makedef.pl nomakedef.pl
- The system cannot find the file specified.
- C:\Symbian\...\make.exe: [rename_makedef] Error 1 (ignored)
-
-please ignore it since it is nothing serious (the build process of
-renames the Perl makedef.pl as nomakedef.pl to avoid confusing it
-with a makedef.pl of the SDK).
-
-=head2 PerlApp
-
-The PerlApp application demonstrates how to embed Perl interpreters
-to a Symbian application. The "Time" menu item runs the following
-Perl code: C<print "Running in ", $^O, "\n", scalar localtime>,
-the "Oneliner" allows one to type in Perl code, and the "Run"
-opens a file chooser for selecting a Perl file to run.
-
-The PerlApp also is started when the "Perl recognizer" (also included
-and installed) detects a Perl file being activated through the GUI,
-and offers either to install it under \Perl (if the Perl file is in
-the inbox of the messaging application) or to run it (if the Perl file
-is under \Perl).
-
-=head2 sisify.pl
-
-In the symbian subdirectory there is F<sisify.pl> utility which can be used
-to package Perl scripts and/or Perl library directories into SIS files,
-which can be installed to the device. To run the sisify.pl utility,
-you will need to have the 'makesis' and 'uidcrc' utilities already
-installed. If you don't have the Win32 SDKs, you may try for example
-L<http://gnupoc.sourceforge.net/> or L<http://symbianos.org/~andreh/>.
-
-=head2 Using Perl in Symbian
-
-First of all note that you have full access to the Symbian device
-when using Perl: you can do a lot of damage to your device (like
-removing system files) unless you are careful. Please do take
-backups before doing anything.
-
-The Perl port has been done for the most part using the Symbian
-standard POSIX-ish STDLIB library. It is a reasonably complete
-library, but certain corners of such emulation libraries that tend
-to be left unimplemented on non-UNIX platforms have been left
-unimplemented also this time: fork(), signals(), user/group ids,
-select() working for sockets, non-blocking sockets, and so forth.
-See the file F<symbian/config.sh> and look for 'undef' to find the
-unsupported APIs (or from Perl use Config).
-
-The filesystem of Symbian devices uses DOSish syntax, "drives"
-separated from paths by a colon, and backslashes for the path. The
-exact assignment of the drives probably varies between platforms, but
-for example in Series 60 you might see C: as the (flash) main memory,
-D: as the RAM drive, E: as the memory card (MMC), Z: as the ROM. In
-Series 80 D: is the memory card. As far the devices go the NUL: is
-the bit bucket, the COMx: are the serial lines, IRCOMx: are the IR
-ports, TMP: might be C:\System\Temp. Remember to double those
-backslashes in doublequoted strings.
-
-The Perl DLL is installed in \System\Libs\. The Perl libraries and
-extension DLLs are installed in \System\Libs\Perl\X.Y.Z\. The PerlApp
-is installed in \System\Apps\, and the SIS also installs a couple of
-demo scripts in \Perl\ (C:\Mydocs\Perl\ on Nokia 7710).
-
-Note that the Symbian filesystem is very picky: it strongly prefers
-the \ instead of the /.
-
-When doing XS / Symbian C++ programming include first the Symbian
-headers, then any standard C/POSIX headers, then Perl headers, and finally
-any application headers.
-
-New() and Copy() are unfortunately used by both Symbian and Perl code
-so you'll have to play cpp games if you need them. PerlBase.h undefines
-the Perl definitions and redefines them as PerlNew() and PerlCopy().
-
-=head1 TO DO
-
-Lots. See F<symbian/TODO>.
-
-=head1 WARNING
-
-As of Perl Symbian port version 0.4.1 any part of Perl's standard
-regression test suite has not been run on a real Symbian device using
-the ported Perl, so innumerable bugs may lie in wait. Therefore there
-is absolutely no warranty.
-
-=head1 NOTE
-
-When creating and extending application programming interfaces (APIs)
-for Symbian or Series 60 or Series 80 or Series 90 it is suggested
-that trademarks, registered trademarks, or trade names are not used in
-the API names. Instead, developers should consider basing the API
-naming in the existing (C++, or maybe Java) public component and API
-naming, modified as appropriate by the rules of the programming
-language the new APIs are for.
-
-Nokia is a registered trademark of Nokia Corporation. Nokia's product
-names are trademarks or registered trademarks of Nokia. Other product
-and company names mentioned herein may be trademarks or trade names of
-their respective owners.
-
-=head1 AUTHOR
-
-Jarkko Hietaniemi
-
-=head1 COPYRIGHT
-
-Copyright (c) 2004-2005 Nokia. All rights reserved.
-
-Copyright (c) 2006-2007 Jarkko Hietaniemi.
-
-=head1 LICENSE
-
-The Symbian port is licensed under the same terms as Perl itself.
-
-=head1 HISTORY
-
-=over 4
-
-=item *
-
-0.1.0: April 2005
-
-(This will show as "0.01" in the Symbian Installer.)
-
- - The console window is a very simple console indeed: one can
- get the newline with "000" and the "C" button is a backspace.
- Do not expect a terminal capable of vt100 or ANSI sequences.
- The console is also "ASCII", you cannot input e.g. any accented
- letters. Because of obvious physical constraints the console is
- also very small: (in Nokia 6600) 22 columns, 17 rows.
- - The following libraries are available:
- AnyDBM_File AutoLoader base Carp Config Cwd constant
- DynaLoader Exporter File::Spec integer lib strict Symbol
- vars warnings XSLoader
- - The following extensions are available:
- attributes Compress::Zlib Cwd Data::Dumper Devel::Peek Digest::MD5 DynaLoader
- Fcntl File::Glob Filter::Util::Call IO List::Util MIME::Base64
- PerlIO::scalar PerlIO::via SDBM_File Socket Storable Time::HiRes
- - The following extensions are missing for various technical reasons:
- B ByteLoader Devel::DProf Devel::PPPort Encode GDBM_File
- I18N::Langinfo IPC::SysV NDBM_File Opcode PerlIO::encoding POSIX
- re Safe Sys::Hostname Sys::Syslog
- threads threads::shared Unicode::Normalize
- - Using MakeMaker or the Module::* to build and install modules
- is not supported.
- - Building XS other than the ones in the core is not supported.
-
-Since this is 0.something release, any future releases are almost
-guaranteed to be binary incompatible. As a sign of this the Symbian
-symbol exports are kept unfrozen and the .def files fully rebuilt
-every time.
-
-=item *
-
-0.2.0: October 2005
-
- - Perl 5.9.3 (patch level 25741)
- - Compress::Zlib and IO::Zlib supported
- - sisify.pl added
-
-We maintain the binary incompatibility.
-
-=item *
-
-0.3.0: October 2005
-
- - Perl 5.9.3 (patch level 25911)
- - Series 80 2.0 and UIQ 2.1 support
-
-We maintain the binary incompatibility.
-
-=item *
-
-0.4.0: November 2005
-
- - Perl 5.9.3 (patch level 26052)
- - adding a sample Symbian extension
-
-We maintain the binary incompatibility.
-
-=item *
-
-0.4.1: December 2006
-
- - Perl 5.9.5-to-be (patch level 30002)
- - added extensions: Compress/Raw/Zlib, Digest/SHA,
- Hash/Util, Math/BigInt/FastCalc, Text/Soundex, Time/Piece
- - port to S90 1.1 by alexander smishlajev
-
-We maintain the binary incompatibility.
-
-=item *
-
-0.4.2: March 2007
-
- - catchup with Perl 5.9.5-to-be (patch level 30812)
- - tested to build with Microsoft Visual C++ 2005 Express Edition
- (which uses Microsoft Visual C 8, instead of the old VC6),
- SDK used for testing S60_2nd_FP3 aka 8.1a
-
-We maintain the binary incompatibility.
-
-=back
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlsyn.pod b/Master/tlpkg/tlperl/lib/pods/perlsyn.pod
deleted file mode 100644
index 3bebeec7adb..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlsyn.pod
+++ /dev/null
@@ -1,1213 +0,0 @@
-=head1 NAME
-X<syntax>
-
-perlsyn - Perl syntax
-
-=head1 DESCRIPTION
-
-A Perl program consists of a sequence of declarations and statements
-which run from the top to the bottom. Loops, subroutines, and other
-control structures allow you to jump around within the code.
-
-Perl is a B<free-form> language: you can format and indent it however
-you like. Whitespace serves mostly to separate tokens, unlike
-languages like Python where it is an important part of the syntax,
-or Fortran where it is immaterial.
-
-Many of Perl's syntactic elements are B<optional>. Rather than
-requiring you to put parentheses around every function call and
-declare every variable, you can often leave such explicit elements off
-and Perl will figure out what you meant. This is known as B<Do What I
-Mean>, abbreviated B<DWIM>. It allows programmers to be B<lazy> and to
-code in a style with which they are comfortable.
-
-Perl B<borrows syntax> and concepts from many languages: awk, sed, C,
-Bourne Shell, Smalltalk, Lisp and even English. Other
-languages have borrowed syntax from Perl, particularly its regular
-expression extensions. So if you have programmed in another language
-you will see familiar pieces in Perl. They often work the same, but
-see L<perltrap> for information about how they differ.
-
-=head2 Declarations
-X<declaration> X<undef> X<undefined> X<uninitialized>
-
-The only things you need to declare in Perl are report formats and
-subroutines (and sometimes not even subroutines). A scalar variable holds
-the undefined value (C<undef>) until it has been assigned a defined
-value, which is anything other than C<undef>. When used as a number,
-C<undef> is treated as C<0>; when used as a string, it is treated as
-the empty string, C<"">; and when used as a reference that isn't being
-assigned to, it is treated as an error. If you enable warnings,
-you'll be notified of an uninitialized value whenever you treat
-C<undef> as a string or a number. Well, usually. Boolean contexts,
-such as:
-
- if ($a) {}
-
-are exempt from warnings (because they care about truth rather than
-definedness). Operators such as C<++>, C<-->, C<+=>,
-C<-=>, and C<.=>, that operate on undefined variables such as:
-
- undef $a;
- $a++;
-
-are also always exempt from such warnings.
-
-A declaration can be put anywhere a statement can, but has no effect on
-the execution of the primary sequence of statements: declarations all
-take effect at compile time. All declarations are typically put at
-the beginning or the end of the script. However, if you're using
-lexically-scoped private variables created with C<my()>,
-C<state()>, or C<our()>, you'll have to make sure
-your format or subroutine definition is within the same block scope
-as the my if you expect to be able to access those private variables.
-
-Declaring a subroutine allows a subroutine name to be used as if it were a
-list operator from that point forward in the program. You can declare a
-subroutine without defining it by saying C<sub name>, thus:
-X<subroutine, declaration>
-
- sub myname;
- $me = myname $0 or die "can't get myname";
-
-A bare declaration like that declares the function to be a list operator,
-not a unary operator, so you have to be careful to use parentheses (or
-C<or> instead of C<||>.) The C<||> operator binds too tightly to use after
-list operators; it becomes part of the last element. You can always use
-parentheses around the list operators arguments to turn the list operator
-back into something that behaves more like a function call. Alternatively,
-you can use the prototype C<($)> to turn the subroutine into a unary
-operator:
-
- sub myname ($);
- $me = myname $0 || die "can't get myname";
-
-That now parses as you'd expect, but you still ought to get in the habit of
-using parentheses in that situation. For more on prototypes, see
-L<perlsub>
-
-Subroutines declarations can also be loaded up with the C<require> statement
-or both loaded and imported into your namespace with a C<use> statement.
-See L<perlmod> for details on this.
-
-A statement sequence may contain declarations of lexically-scoped
-variables, but apart from declaring a variable name, the declaration acts
-like an ordinary statement, and is elaborated within the sequence of
-statements as if it were an ordinary statement. That means it actually
-has both compile-time and run-time effects.
-
-=head2 Comments
-X<comment> X<#>
-
-Text from a C<"#"> character until the end of the line is a comment,
-and is ignored. Exceptions include C<"#"> inside a string or regular
-expression.
-
-=head2 Simple Statements
-X<statement> X<semicolon> X<expression> X<;>
-
-The only kind of simple statement is an expression evaluated for its
-side-effects. Every simple statement must be terminated with a
-semicolon, unless it is the final statement in a block, in which case
-the semicolon is optional. But put the semicolon in anyway if the
-block takes up more than one line, because you may eventually add
-another line. Note that there are operators like C<eval {}>, C<sub {}>, and
-C<do {}> that I<look> like compound statements, but aren't--they're just
-TERMs in an expression--and thus need an explicit termination when used
-as the last item in a statement.
-
-=head2 Truth and Falsehood
-X<truth> X<falsehood> X<true> X<false> X<!> X<not> X<negation> X<0>
-
-The number 0, the strings C<'0'> and C<"">, the empty list C<()>, and
-C<undef> are all false in a boolean context. All other values are true.
-Negation of a true value by C<!> or C<not> returns a special false value.
-When evaluated as a string it is treated as C<"">, but as a number, it
-is treated as 0. Most Perl operators
-that return true or false behave this way.
-
-=head2 Statement Modifiers
-X<statement modifier> X<modifier> X<if> X<unless> X<while>
-X<until> X<when> X<foreach> X<for>
-
-Any simple statement may optionally be followed by a I<SINGLE> modifier,
-just before the terminating semicolon (or block ending). The possible
-modifiers are:
-
- if EXPR
- unless EXPR
- while EXPR
- until EXPR
- for LIST
- foreach LIST
- when EXPR
-
-The C<EXPR> following the modifier is referred to as the "condition".
-Its truth or falsehood determines how the modifier will behave.
-
-C<if> executes the statement once I<if> and only if the condition is
-true. C<unless> is the opposite, it executes the statement I<unless>
-the condition is true (that is, if the condition is false).
-
- print "Basset hounds got long ears" if length $ear >= 10;
- go_outside() and play() unless $is_raining;
-
-The C<for(each)> modifier is an iterator: it executes the statement once
-for each item in the LIST (with C<$_> aliased to each item in turn).
-
- print "Hello $_!\n" for qw(world Dolly nurse);
-
-C<while> repeats the statement I<while> the condition is true.
-C<until> does the opposite, it repeats the statement I<until> the
-condition is true (or while the condition is false):
-
- # Both of these count from 0 to 10.
- print $i++ while $i <= 10;
- print $j++ until $j > 10;
-
-The C<while> and C<until> modifiers have the usual "C<while> loop"
-semantics (conditional evaluated first), except when applied to a
-C<do>-BLOCK (or to the Perl4 C<do>-SUBROUTINE statement), in
-which case the block executes once before the conditional is
-evaluated.
-
-This is so that you can write loops like:
-
- do {
- $line = <STDIN>;
- ...
- } until !defined($line) || $line eq ".\n"
-
-See L<perlfunc/do>. Note also that the loop control statements described
-later will I<NOT> work in this construct, because modifiers don't take
-loop labels. Sorry. You can always put another block inside of it
-(for C<next>) or around it (for C<last>) to do that sort of thing.
-For C<next>, just double the braces:
-X<next> X<last> X<redo>
-
- do {{
- next if $x == $y;
- # do something here
- }} until $x++ > $z;
-
-For C<last>, you have to be more elaborate:
-X<last>
-
- LOOP: {
- do {
- last if $x = $y**2;
- # do something here
- } while $x++ <= $z;
- }
-
-B<NOTE:> The behaviour of a C<my>, C<state>, or
-C<our> modified with a statement modifier conditional
-or loop construct (for example, C<my $x if ...>) is
-B<undefined>. The value of the C<my> variable may be C<undef>, any
-previously assigned value, or possibly anything else. Don't rely on
-it. Future versions of perl might do something different from the
-version of perl you try it out on. Here be dragons.
-X<my>
-
-The C<when> modifier is an experimental feature that first appeared in Perl
-5.14. To use it, you should include a C<use v5.14> declaration.
-(Technically, it requires only the C<switch> feature, but that aspect of it
-was not available before 5.14.) Operative only from within a C<foreach>
-loop or a C<given> block, it executes the statement only if the smartmatch
-C<< $_ ~~ I<EXPR> >> is true. If the statement executes, it is followed by
-a C<next> from inside a C<foreach> and C<break> from inside a C<given>.
-
-Under the current implementation, the C<foreach> loop can be
-anywhere within the C<when> modifier's dynamic scope, but must be
-within the C<given> block's lexical scope. This restricted may
-be relaxed in a future release. See L<"Switch Statements"> below.
-
-=head2 Compound Statements
-X<statement, compound> X<block> X<bracket, curly> X<curly bracket> X<brace>
-X<{> X<}> X<if> X<unless> X<given> X<while> X<until> X<foreach> X<for> X<continue>
-
-In Perl, a sequence of statements that defines a scope is called a block.
-Sometimes a block is delimited by the file containing it (in the case
-of a required file, or the program as a whole), and sometimes a block
-is delimited by the extent of a string (in the case of an eval).
-
-But generally, a block is delimited by curly brackets, also known as braces.
-We will call this syntactic construct a BLOCK.
-
-The following compound statements may be used to control flow:
-
- if (EXPR) BLOCK
- if (EXPR) BLOCK else BLOCK
- if (EXPR) BLOCK elsif (EXPR) BLOCK ...
- if (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
-
- unless (EXPR) BLOCK
- unless (EXPR) BLOCK else BLOCK
- unless (EXPR) BLOCK elsif (EXPR) BLOCK ...
- unless (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
-
- given (EXPR) BLOCK
-
- LABEL while (EXPR) BLOCK
- LABEL while (EXPR) BLOCK continue BLOCK
-
- LABEL until (EXPR) BLOCK
- LABEL until (EXPR) BLOCK continue BLOCK
-
- LABEL for (EXPR; EXPR; EXPR) BLOCK
- LABEL for VAR (LIST) BLOCK
- LABEL for VAR (LIST) BLOCK continue BLOCK
-
- LABEL foreach (EXPR; EXPR; EXPR) BLOCK
- LABEL foreach VAR (LIST) BLOCK
- LABEL foreach VAR (LIST) BLOCK continue BLOCK
-
- LABEL BLOCK
- LABEL BLOCK continue BLOCK
-
- PHASE BLOCK
-
-The experimental C<given> statement is I<not automatically enabled>; see
-L</"Switch Statements"> below for how to do so, and the attendant caveats.
-
-Unlike in C and Pascal, in Perl these are all defined in terms of BLOCKs,
-not statements. This means that the curly brackets are I<required>--no
-dangling statements allowed. If you want to write conditionals without
-curly brackets, there are several other ways to do it. The following
-all do the same thing:
-
- if (!open(FOO)) { die "Can't open $FOO: $!" }
- die "Can't open $FOO: $!" unless open(FOO);
- open(FOO) || die "Can't open $FOO: $!";
- open(FOO) ? () : die "Can't open $FOO: $!";
- # a bit exotic, that last one
-
-The C<if> statement is straightforward. Because BLOCKs are always
-bounded by curly brackets, there is never any ambiguity about which
-C<if> an C<else> goes with. If you use C<unless> in place of C<if>,
-the sense of the test is reversed. Like C<if>, C<unless> can be followed
-by C<else>. C<unless> can even be followed by one or more C<elsif>
-statements, though you may want to think twice before using that particular
-language construct, as everyone reading your code will have to think at least
-twice before they can understand what's going on.
-
-The C<while> statement executes the block as long as the expression is
-L<true|/"Truth and Falsehood">.
-The C<until> statement executes the block as long as the expression is
-false.
-The LABEL is optional, and if present, consists of an identifier followed
-by a colon. The LABEL identifies the loop for the loop control
-statements C<next>, C<last>, and C<redo>.
-If the LABEL is omitted, the loop control statement
-refers to the innermost enclosing loop. This may include dynamically
-looking back your call-stack at run time to find the LABEL. Such
-desperate behavior triggers a warning if you use the C<use warnings>
-pragma or the B<-w> flag.
-
-If there is a C<continue> BLOCK, it is always executed just before the
-conditional is about to be evaluated again. Thus it can be used to
-increment a loop variable, even when the loop has been continued via
-the C<next> statement.
-
-When a block is preceding by a compilation phase keyword such as C<BEGIN>,
-C<END>, C<INIT>, C<CHECK>, or C<UNITCHECK>, then the block will run only
-during the corresponding phase of execution. See L<perlmod> for more details.
-
-Extension modules can also hook into the Perl parser to define new
-kinds of compound statements. These are introduced by a keyword which
-the extension recognizes, and the syntax following the keyword is
-defined entirely by the extension. If you are an implementor, see
-L<perlapi/PL_keyword_plugin> for the mechanism. If you are using such
-a module, see the module's documentation for details of the syntax that
-it defines.
-
-=head2 Loop Control
-X<loop control> X<loop, control> X<next> X<last> X<redo> X<continue>
-
-The C<next> command starts the next iteration of the loop:
-
- LINE: while (<STDIN>) {
- next LINE if /^#/; # discard comments
- ...
- }
-
-The C<last> command immediately exits the loop in question. The
-C<continue> block, if any, is not executed:
-
- LINE: while (<STDIN>) {
- last LINE if /^$/; # exit when done with header
- ...
- }
-
-The C<redo> command restarts the loop block without evaluating the
-conditional again. The C<continue> block, if any, is I<not> executed.
-This command is normally used by programs that want to lie to themselves
-about what was just input.
-
-For example, when processing a file like F</etc/termcap>.
-If your input lines might end in backslashes to indicate continuation, you
-want to skip ahead and get the next record.
-
- while (<>) {
- chomp;
- if (s/\\$//) {
- $_ .= <>;
- redo unless eof();
- }
- # now process $_
- }
-
-which is Perl shorthand for the more explicitly written version:
-
- LINE: while (defined($line = <ARGV>)) {
- chomp($line);
- if ($line =~ s/\\$//) {
- $line .= <ARGV>;
- redo LINE unless eof(); # not eof(ARGV)!
- }
- # now process $line
- }
-
-Note that if there were a C<continue> block on the above code, it would
-get executed only on lines discarded by the regex (since redo skips the
-continue block). A continue block is often used to reset line counters
-or C<m?pat?> one-time matches:
-
- # inspired by :1,$g/fred/s//WILMA/
- while (<>) {
- m?(fred)? && s//WILMA $1 WILMA/;
- m?(barney)? && s//BETTY $1 BETTY/;
- m?(homer)? && s//MARGE $1 MARGE/;
- } continue {
- print "$ARGV $.: $_";
- close ARGV if eof; # reset $.
- reset if eof; # reset ?pat?
- }
-
-If the word C<while> is replaced by the word C<until>, the sense of the
-test is reversed, but the conditional is still tested before the first
-iteration.
-
-Loop control statements don't work in an C<if> or C<unless>, since
-they aren't loops. You can double the braces to make them such, though.
-
- if (/pattern/) {{
- last if /fred/;
- next if /barney/; # same effect as "last",
- # but doesn't document as well
- # do something here
- }}
-
-This is caused by the fact that a block by itself acts as a loop that
-executes once, see L<"Basic BLOCKs">.
-
-The form C<while/if BLOCK BLOCK>, available in Perl 4, is no longer
-available. Replace any occurrence of C<if BLOCK> by C<if (do BLOCK)>.
-
-=head2 For Loops
-X<for> X<foreach>
-
-Perl's C-style C<for> loop works like the corresponding C<while> loop;
-that means that this:
-
- for ($i = 1; $i < 10; $i++) {
- ...
- }
-
-is the same as this:
-
- $i = 1;
- while ($i < 10) {
- ...
- } continue {
- $i++;
- }
-
-There is one minor difference: if variables are declared with C<my>
-in the initialization section of the C<for>, the lexical scope of
-those variables is exactly the C<for> loop (the body of the loop
-and the control sections).
-X<my>
-
-Besides the normal array index looping, C<for> can lend itself
-to many other interesting applications. Here's one that avoids the
-problem you get into if you explicitly test for end-of-file on
-an interactive file descriptor causing your program to appear to
-hang.
-X<eof> X<end-of-file> X<end of file>
-
- $on_a_tty = -t STDIN && -t STDOUT;
- sub prompt { print "yes? " if $on_a_tty }
- for ( prompt(); <STDIN>; prompt() ) {
- # do something
- }
-
-Using C<readline> (or the operator form, C<< <EXPR> >>) as the
-conditional of a C<for> loop is shorthand for the following. This
-behaviour is the same as a C<while> loop conditional.
-X<readline> X<< <> >>
-
- for ( prompt(); defined( $_ = <STDIN> ); prompt() ) {
- # do something
- }
-
-=head2 Foreach Loops
-X<for> X<foreach>
-
-The C<foreach> loop iterates over a normal list value and sets the
-variable VAR to be each element of the list in turn. If the variable
-is preceded with the keyword C<my>, then it is lexically scoped, and
-is therefore visible only within the loop. Otherwise, the variable is
-implicitly local to the loop and regains its former value upon exiting
-the loop. If the variable was previously declared with C<my>, it uses
-that variable instead of the global one, but it's still localized to
-the loop. This implicit localization occurs I<only> in a C<foreach>
-loop.
-X<my> X<local>
-
-The C<foreach> keyword is actually a synonym for the C<for> keyword, so
-you can use either. If VAR is omitted, C<$_> is set to each value.
-X<$_>
-
-If any element of LIST is an lvalue, you can modify it by modifying
-VAR inside the loop. Conversely, if any element of LIST is NOT an
-lvalue, any attempt to modify that element will fail. In other words,
-the C<foreach> loop index variable is an implicit alias for each item
-in the list that you're looping over.
-X<alias>
-
-If any part of LIST is an array, C<foreach> will get very confused if
-you add or remove elements within the loop body, for example with
-C<splice>. So don't do that.
-X<splice>
-
-C<foreach> probably won't do what you expect if VAR is a tied or other
-special variable. Don't do that either.
-
-Examples:
-
- for (@ary) { s/foo/bar/ }
-
- for my $elem (@elements) {
- $elem *= 2;
- }
-
- for $count (reverse(1..10), "BOOM") {
- print $count, "\n";
- sleep(1);
- }
-
- for (1..15) { print "Merry Christmas\n"; }
-
- foreach $item (split(/:[\\\n:]*/, $ENV{TERMCAP})) {
- print "Item: $item\n";
- }
-
-Here's how a C programmer might code up a particular algorithm in Perl:
-
- for (my $i = 0; $i < @ary1; $i++) {
- for (my $j = 0; $j < @ary2; $j++) {
- if ($ary1[$i] > $ary2[$j]) {
- last; # can't go to outer :-(
- }
- $ary1[$i] += $ary2[$j];
- }
- # this is where that last takes me
- }
-
-Whereas here's how a Perl programmer more comfortable with the idiom might
-do it:
-
- OUTER: for my $wid (@ary1) {
- INNER: for my $jet (@ary2) {
- next OUTER if $wid > $jet;
- $wid += $jet;
- }
- }
-
-See how much easier this is? It's cleaner, safer, and faster. It's
-cleaner because it's less noisy. It's safer because if code gets added
-between the inner and outer loops later on, the new code won't be
-accidentally executed. The C<next> explicitly iterates the other loop
-rather than merely terminating the inner one. And it's faster because
-Perl executes a C<foreach> statement more rapidly than it would the
-equivalent C<for> loop.
-
-=head2 Basic BLOCKs
-X<block>
-
-A BLOCK by itself (labeled or not) is semantically equivalent to a
-loop that executes once. Thus you can use any of the loop control
-statements in it to leave or restart the block. (Note that this is
-I<NOT> true in C<eval{}>, C<sub{}>, or contrary to popular belief
-C<do{}> blocks, which do I<NOT> count as loops.) The C<continue>
-block is optional.
-
-The BLOCK construct can be used to emulate case structures.
-
- SWITCH: {
- if (/^abc/) { $abc = 1; last SWITCH; }
- if (/^def/) { $def = 1; last SWITCH; }
- if (/^xyz/) { $xyz = 1; last SWITCH; }
- $nothing = 1;
- }
-
-You'll also find that C<foreach> loop used to create a topicalizer
-and a switch:
-
- SWITCH:
- for ($var) {
- if (/^abc/) { $abc = 1; last SWITCH; }
- if (/^def/) { $def = 1; last SWITCH; }
- if (/^xyz/) { $xyz = 1; last SWITCH; }
- $nothing = 1;
- }
-
-Such constructs are quite frequently used, both because older versions of
-Perl had no official C<switch> statement, and also because the new version
-described immediately below remains experimental and can sometimes be confusing.
-
-=head2 Switch Statements
-
-X<switch> X<case> X<given> X<when> X<default>
-
-Starting from Perl 5.10.1 (well, 5.10.0, but it didn't work
-right), you can say
-
- use feature "switch";
-
-to enable an experimental switch feature. This is loosely based on an
-old version of a Perl 6 proposal, but it no longer resembles the Perl 6
-construct. You also get the switch feature whenever you declare that your
-code prefers to run under a version of Perl that is 5.10 or later. For
-example:
-
- use v5.14;
-
-Under the "switch" feature, Perl gains the experimental keywords
-C<given>, C<when>, C<default>, C<continue>, and C<break>.
-Starting from Perl 5.16, one can prefix the switch
-keywords with C<CORE::> to access the feature without a C<use feature>
-statement. The keywords C<given> and
-C<when> are analogous to C<switch> and
-C<case> in other languages, so the code in the previous section could be
-rewritten as
-
- use v5.10.1;
- for ($var) {
- when (/^abc/) { $abc = 1 }
- when (/^def/) { $def = 1 }
- when (/^xyz/) { $xyz = 1 }
- default { $nothing = 1 }
- }
-
-The C<foreach> is the non-experimental way to set a topicalizer.
-If you wish to use the highly experimental C<given>, that could be
-written like this:
-
- use v5.10.1;
- given ($var) {
- when (/^abc/) { $abc = 1 }
- when (/^def/) { $def = 1 }
- when (/^xyz/) { $xyz = 1 }
- default { $nothing = 1 }
- }
-
-As of 5.14, that can also be written this way:
-
- use v5.14;
- for ($var) {
- $abc = 1 when /^abc/;
- $def = 1 when /^def/;
- $xyz = 1 when /^xyz/;
- default { $nothing = 1 }
- }
-
-Or if you don't care to play it safe, like this:
-
- use v5.14;
- given ($var) {
- $abc = 1 when /^abc/;
- $def = 1 when /^def/;
- $xyz = 1 when /^xyz/;
- default { $nothing = 1 }
- }
-
-The arguments to C<given> and C<when> are in scalar context,
-and C<given> assigns the C<$_> variable its topic value.
-
-Exactly what the I<EXPR> argument to C<when> does is hard to describe
-precisely, but in general, it tries to guess what you want done. Sometimes
-it is interpreted as C<< $_ ~~ I<EXPR> >>, and sometimes it does not. It
-also behaves differently when lexically enclosed by a C<given> block than
-it does when dynamically enclosed by a C<foreach> loop. The rules are far
-too difficult to understand to be described here. See L</"Experimental Details
-on given and when"> later on.
-
-Due to an unfortunate bug in how C<given> was implemented between Perl 5.10
-and 5.14, under those implementations the version of C<$_> governed by
-C<given> is merely a lexically scoped copy of the original, not a
-dynamically scoped alias to the original, as it would be if it were a
-C<foreach> or under both the original and the current Perl 6 language
-specification. This bug is expected to be addressed in a future release of
-Perl. For forwards compatibility, if you really want a lexical C<$_>,
-specify that explicitly:
-
- given(my $_ = EXPR) { ... }
-
-In the meanwhile, stick to C<foreach> for your topicalizer and
-you will be less unhappy.
-
-=head2 Goto
-X<goto>
-
-Although not for the faint of heart, Perl does support a C<goto>
-statement. There are three forms: C<goto>-LABEL, C<goto>-EXPR, and
-C<goto>-&NAME. A loop's LABEL is not actually a valid target for
-a C<goto>; it's just the name of the loop.
-
-The C<goto>-LABEL form finds the statement labeled with LABEL and resumes
-execution there. It may not be used to go into any construct that
-requires initialization, such as a subroutine or a C<foreach> loop. It
-also can't be used to go into a construct that is optimized away. It
-can be used to go almost anywhere else within the dynamic scope,
-including out of subroutines, but it's usually better to use some other
-construct such as C<last> or C<die>. The author of Perl has never felt the
-need to use this form of C<goto> (in Perl, that is--C is another matter).
-
-The C<goto>-EXPR form expects a label name, whose scope will be resolved
-dynamically. This allows for computed C<goto>s per FORTRAN, but isn't
-necessarily recommended if you're optimizing for maintainability:
-
- goto(("FOO", "BAR", "GLARCH")[$i]);
-
-The C<goto>-&NAME form is highly magical, and substitutes a call to the
-named subroutine for the currently running subroutine. This is used by
-C<AUTOLOAD()> subroutines that wish to load another subroutine and then
-pretend that the other subroutine had been called in the first place
-(except that any modifications to C<@_> in the current subroutine are
-propagated to the other subroutine.) After the C<goto>, not even C<caller()>
-will be able to tell that this routine was called first.
-
-In almost all cases like this, it's usually a far, far better idea to use the
-structured control flow mechanisms of C<next>, C<last>, or C<redo> instead of
-resorting to a C<goto>. For certain applications, the catch and throw pair of
-C<eval{}> and die() for exception processing can also be a prudent approach.
-
-=head2 The Ellipsis Statement
-X<...>
-X<... statement>
-X<ellipsis operator>
-X<elliptical statement>
-X<unimplemented statement>
-X<unimplemented operator>
-X<yada-yada>
-X<yada-yada operator>
-X<... operator>
-X<whatever operator>
-X<triple-dot operator>
-
-Beginning in Perl 5.12, Perl accepts an ellipsis, "C<...>", as a
-placeholder for code that you haven't implemented yet. This form of
-ellipsis, the unimplemented statement, should not be confused with the
-binary flip-flop C<...> operator. One is a statement and the other an
-operator. (Perl doesn't usually confuse them because usually Perl can tell
-whether it wants an operator or a statement, but see below for exceptions.)
-
-When Perl 5.12 or later encounters an ellipsis statement, it parses this
-without error, but if and when you should actually try to execute it, Perl
-throws an exception with the text C<Unimplemented>:
-
- use v5.12;
- sub unimplemented { ... }
- eval { unimplemented() };
- if ($@ =~ /^Unimplemented at /) {
- say "I found an ellipsis!";
- }
-
-You can only use the elliptical statement to stand in for a
-complete statement. These examples of how the ellipsis works:
-
- use v5.12;
- { ... }
- sub foo { ... }
- ...;
- eval { ... };
- sub somemeth {
- my $self = shift;
- ...;
- }
- $x = do {
- my $n;
- ...;
- say "Hurrah!";
- $n;
- };
-
-The elliptical statement cannot stand in for an expression that
-is part of a larger statement, since the C<...> is also the three-dot
-version of the flip-flop operator (see L<perlop/"Range Operators">).
-
-These examples of attempts to use an ellipsis are syntax errors:
-
- use v5.12;
-
- print ...;
- open(my $fh, ">", "/dev/passwd") or ...;
- if ($condition && ... ) { say "Howdy" };
-
-There are some cases where Perl can't immediately tell the difference
-between an expression and a statement. For instance, the syntax for a
-block and an anonymous hash reference constructor look the same unless
-there's something in the braces to give Perl a hint. The ellipsis is a
-syntax error if Perl doesn't guess that the C<{ ... }> is a block. In that
-case, it doesn't think the C<...> is an ellipsis because it's expecting an
-expression instead of a statement:
-
- @transformed = map { ... } @input; # syntax error
-
-You can use a C<;> inside your block to denote that the C<{ ... }> is a
-block and not a hash reference constructor. Now the ellipsis works:
-
- @transformed = map {; ... } @input; # ; disambiguates
-
- @transformed = map { ...; } @input; # ; disambiguates
-
-Note: Some folks colloquially refer to this bit of punctuation as a
-"yada-yada" or "triple-dot", but its true name
-is actually an ellipsis. Perl does not yet
-accept the Unicode version, U+2026 HORIZONTAL ELLIPSIS, as an alias for
-C<...>, but someday it may.
-
-=head2 PODs: Embedded Documentation
-X<POD> X<documentation>
-
-Perl has a mechanism for intermixing documentation with source code.
-While it's expecting the beginning of a new statement, if the compiler
-encounters a line that begins with an equal sign and a word, like this
-
- =head1 Here There Be Pods!
-
-Then that text and all remaining text up through and including a line
-beginning with C<=cut> will be ignored. The format of the intervening
-text is described in L<perlpod>.
-
-This allows you to intermix your source code
-and your documentation text freely, as in
-
- =item snazzle($)
-
- The snazzle() function will behave in the most spectacular
- form that you can possibly imagine, not even excepting
- cybernetic pyrotechnics.
-
- =cut back to the compiler, nuff of this pod stuff!
-
- sub snazzle($) {
- my $thingie = shift;
- .........
- }
-
-Note that pod translators should look at only paragraphs beginning
-with a pod directive (it makes parsing easier), whereas the compiler
-actually knows to look for pod escapes even in the middle of a
-paragraph. This means that the following secret stuff will be
-ignored by both the compiler and the translators.
-
- $a=3;
- =secret stuff
- warn "Neither POD nor CODE!?"
- =cut back
- print "got $a\n";
-
-You probably shouldn't rely upon the C<warn()> being podded out forever.
-Not all pod translators are well-behaved in this regard, and perhaps
-the compiler will become pickier.
-
-One may also use pod directives to quickly comment out a section
-of code.
-
-=head2 Plain Old Comments (Not!)
-X<comment> X<line> X<#> X<preprocessor> X<eval>
-
-Perl can process line directives, much like the C preprocessor. Using
-this, one can control Perl's idea of filenames and line numbers in
-error or warning messages (especially for strings that are processed
-with C<eval()>). The syntax for this mechanism is almost the same as for
-most C preprocessors: it matches the regular expression
-
- # example: '# line 42 "new_filename.plx"'
- /^\# \s*
- line \s+ (\d+) \s*
- (?:\s("?)([^"]+)\g2)? \s*
- $/x
-
-with C<$1> being the line number for the next line, and C<$3> being
-the optional filename (specified with or without quotes). Note that
-no whitespace may precede the C<< # >>, unlike modern C preprocessors.
-
-There is a fairly obvious gotcha included with the line directive:
-Debuggers and profilers will only show the last source line to appear
-at a particular line number in a given file. Care should be taken not
-to cause line number collisions in code you'd like to debug later.
-
-Here are some examples that you should be able to type into your command
-shell:
-
- % perl
- # line 200 "bzzzt"
- # the '#' on the previous line must be the first char on line
- die 'foo';
- __END__
- foo at bzzzt line 201.
-
- % perl
- # line 200 "bzzzt"
- eval qq[\n#line 2001 ""\ndie 'foo']; print $@;
- __END__
- foo at - line 2001.
-
- % perl
- eval qq[\n#line 200 "foo bar"\ndie 'foo']; print $@;
- __END__
- foo at foo bar line 200.
-
- % perl
- # line 345 "goop"
- eval "\n#line " . __LINE__ . ' "' . __FILE__ ."\"\ndie 'foo'";
- print $@;
- __END__
- foo at goop line 345.
-
-=head2 Experimental Details on given and when
-
-As previously mentioned, the "switch" feature is considered highly
-experimental; it is subject to change with little notice. In particular,
-both C<given> and C<when> have tricky behaviours that are expected to
-change to become less tricky in the future. Do not rely upon their
-current (mis)implementations.
-
-Here is a longer example of C<given>:
-
- use feature ":5.10";
- given ($foo) {
- when (undef) {
- say '$foo is undefined';
- }
- when ("foo") {
- say '$foo is the string "foo"';
- }
- when ([1,3,5,7,9]) {
- say '$foo is an odd digit';
- continue; # Fall through
- }
- when ($_ < 100) {
- say '$foo is numerically less than 100';
- }
- when (\&complicated_check) {
- say 'a complicated check for $foo is true';
- }
- default {
- die q(I don't know what to do with $foo);
- }
- }
-
-As currently implemented, C<given(EXPR)> assign the value of I<EXPR> to
-merely a lexically scoped I<B<copy>> (!) of C<$_>, not a dynamically
-scoped alias the way C<foreach> does. That makes it similar to
-
- do { my $_ = EXPR; ... }
-
-except that the block is automatically broken out of by a
-successful C<when> or an explicit C<break>. Because it is only a
-copy, and because it is only lexically scoped, not dynamically
-scoped, you cannot do the things with it that you are used to in
-a C<foreach> loop. In particular, you probably cannot use
-arbitrary function calls. Best stick to C<foreach> for that.
-
-Most of the power comes from the implicit smartmatching that can
-sometimes apply. Most of the time, C<when(EXPR)> is treated as an
-implicit smartmatch of C<$_>, that is, C<$_ ~~ EXPR>. (See
-L<perlop/"Smartmatch Operator"> for more information on smartmatching.)
-But when I<EXPR> is one of the 10 exceptional cases (or things like them)
-listed below, it is used directly as a boolean.
-
-=over 4
-
-=item 1.
-
-A user-defined subroutine call or a method invocation.
-
-=item 2.
-
-A regular expression match in the form of C</REGEX/>, C<$foo =~ /REGEX/>,
-or C<$foo =~ EXPR>. Also, a negated regular expression match in
-the form C<!/REGEX/>, C<$foo !~ /REGEX/>, or C<$foo !~ EXPR>.
-
-=item 3.
-
-A smart match that uses an explicit C<~~> operator, such as C<EXPR ~~ EXPR>.
-
-=item 4.
-
-A boolean comparison operator such as C<$_ E<lt> 10> or C<$x eq "abc"> The
-relational operators that this applies to are the six numeric comparisons
-(C<< < >>, C<< > >>, C<< <= >>, C<< >= >>, C<< == >>, and C<< != >>), and
-the six string comparisons (C<lt>, C<gt>, C<le>, C<ge>, C<eq>, and C<ne>).
-
-B<NOTE:> You will often have to use C<$c ~~ $_> because
-the default case uses C<$_ ~~ $c> , which is frequently
-the opposite of what you want.
-
-=item 5.
-
-At least the three builtin functions C<defined(...)>, C<exists(...)>, and
-C<eof(...)>. We might someday add more of these later if we think of them.
-
-=item 6.
-
-A negated expression, whether C<!(EXPR)> or C<not(EXPR)>, or a logical
-exclusive-or, C<(EXPR1) xor (EXPR2)>. The bitwise versions (C<~> and C<^>)
-are not included.
-
-=item 7.
-
-A filetest operator, with exactly 4 exceptions: C<-s>, C<-M>, C<-A>, and
-C<-C>, as these return numerical values, not boolean ones. The C<-z>
-filetest operator is not included in the exception list.
-
-=item 8.
-
-The C<..> and C<...> flip-flop operators. Note that the C<...> flip-flop
-operator is completely different from the C<...> elliptical statement
-just described.
-
-=back
-
-In those 8 cases above, the value of EXPR is used directly as a boolean, so
-no smartmatching is done. You may think of C<when> as a smartsmartmatch.
-
-Furthermore, Perl inspects the operands of logical operators to
-decide whether to use smartmatching for each one by applying the
-above test to the operands:
-
-=over 4
-
-=item 9.
-
-If EXPR is C<EXPR1 && EXPR2> or C<EXPR1 and EXPR2>, the test is applied
-I<recursively> to both EXPR1 and EXPR2.
-Only if I<both> operands also pass the
-test, I<recursively>, will the expression be treated as boolean. Otherwise,
-smartmatching is used.
-
-=item 10.
-
-If EXPR is C<EXPR1 || EXPR2>, C<EXPR1 // EXPR2>, or C<EXPR1 or EXPR2>, the
-test is applied I<recursively> to EXPR1 only (which might itself be a
-higher-precedence AND operator, for example, and thus subject to the
-previous rule), not to EXPR2. If EXPR1 is to use smartmatching, then EXPR2
-also does so, no matter what EXPR2 contains. But if EXPR2 does not get to
-use smartmatching, then the second argument will not be either. This is
-quite different from the C<&&> case just described, so be careful.
-
-=back
-
-These rules are complicated, but the goal is for them to do what you want
-(even if you don't quite understand why they are doing it). For example:
-
- when (/^\d+$/ && $_ < 75) { ... }
-
-will be treated as a boolean match because the rules say both
-a regex match and an explicit test on C<$_> will be treated
-as boolean.
-
-Also:
-
- when ([qw(foo bar)] && /baz/) { ... }
-
-will use smartmatching because only I<one> of the operands is a boolean:
-the other uses smartmatching, and that wins.
-
-Further:
-
- when ([qw(foo bar)] || /^baz/) { ... }
-
-will use smart matching (only the first operand is considered), whereas
-
- when (/^baz/ || [qw(foo bar)]) { ... }
-
-will test only the regex, which causes both operands to be
-treated as boolean. Watch out for this one, then, because an
-arrayref is always a true value, which makes it effectively
-redundant. Not a good idea.
-
-Tautologous boolean operators are still going to be optimized
-away. Don't be tempted to write
-
- when ("foo" or "bar") { ... }
-
-This will optimize down to C<"foo">, so C<"bar"> will never be considered (even
-though the rules say to use a smartmatch
-on C<"foo">). For an alternation like
-this, an array ref will work, because this will instigate smartmatching:
-
- when ([qw(foo bar)] { ... }
-
-This is somewhat equivalent to the C-style switch statement's fallthrough
-functionality (not to be confused with I<Perl's> fallthrough
-functionality--see below), wherein the same block is used for several
-C<case> statements.
-
-Another useful shortcut is that, if you use a literal array or hash as the
-argument to C<given>, it is turned into a reference. So C<given(@foo)> is
-the same as C<given(\@foo)>, for example.
-
-C<default> behaves exactly like C<when(1 == 1)>, which is
-to say that it always matches.
-
-=head3 Breaking out
-
-You can use the C<break> keyword to break out of the enclosing
-C<given> block. Every C<when> block is implicitly ended with
-a C<break>.
-
-=head3 Fall-through
-
-You can use the C<continue> keyword to fall through from one
-case to the next:
-
- given($foo) {
- when (/x/) { say '$foo contains an x'; continue }
- when (/y/) { say '$foo contains a y' }
- default { say '$foo does not contain a y' }
- }
-
-=head3 Return value
-
-When a C<given> statement is also a valid expression (for example,
-when it's the last statement of a block), it evaluates to:
-
-=over 4
-
-=item *
-
-An empty list as soon as an explicit C<break> is encountered.
-
-=item *
-
-The value of the last evaluated expression of the successful
-C<when>/C<default> clause, if there happens to be one.
-
-=item *
-
-The value of the last evaluated expression of the C<given> block if no
-condition is true.
-
-=back
-
-In both last cases, the last expression is evaluated in the context that
-was applied to the C<given> block.
-
-Note that, unlike C<if> and C<unless>, failed C<when> statements always
-evaluate to an empty list.
-
- my $price = do {
- given ($item) {
- when (["pear", "apple"]) { 1 }
- break when "vote"; # My vote cannot be bought
- 1e10 when /Mona Lisa/;
- "unknown";
- }
- };
-
-Currently, C<given> blocks can't always
-be used as proper expressions. This
-may be addressed in a future version of Perl.
-
-=head3 Switching in a loop
-
-Instead of using C<given()>, you can use a C<foreach()> loop.
-For example, here's one way to count how many times a particular
-string occurs in an array:
-
- use v5.10.1;
- my $count = 0;
- for (@array) {
- when ("foo") { ++$count }
- }
- print "\@array contains $count copies of 'foo'\n";
-
-Or in a more recent version:
-
- use v5.14;
- my $count = 0;
- for (@array) {
- ++$count when "foo";
- }
- print "\@array contains $count copies of 'foo'\n";
-
-At the end of all C<when> blocks, there is an implicit C<next>.
-You can override that with an explicit C<last> if you're
-interested in only the first match alone.
-
-This doesn't work if you explicitly specify a loop variable, as
-in C<for $item (@array)>. You have to use the default variable C<$_>.
-
-=head3 Differences from Perl 6
-
-The Perl 5 smartmatch and C<given>/C<when> constructs are not compatible
-with their Perl 6 analogues. The most visible difference and least
-important difference is that, in Perl 5, parentheses are required around
-the argument to C<given()> and C<when()> (except when this last one is used
-as a statement modifier). Parentheses in Perl 6 are always optional in a
-control construct such as C<if()>, C<while()>, or C<when()>; they can't be
-made optional in Perl 5 without a great deal of potential confusion,
-because Perl 5 would parse the expression
-
- given $foo {
- ...
- }
-
-as though the argument to C<given> were an element of the hash
-C<%foo>, interpreting the braces as hash-element syntax.
-
-However, their are many, many other differences. For example,
-this works in Perl 5:
-
- use v5.12;
- my @primary = ("red", "blue", "green");
-
- if (@primary ~~ "red") {
- say "primary smartmatches red";
- }
-
- if ("red" ~~ @primary) {
- say "red smartmatches primary";
- }
-
- say "that's all, folks!";
-
-But it doesn't work at all in Perl 6. Instead, you should
-use the (parallelizable) C<any> operator instead:
-
- if any(@primary) eq "red" {
- say "primary smartmatches red";
- }
-
- if "red" eq any(@primary) {
- say "red smartmatches primary";
- }
-
-The table of smartmatches in L<perlop/"Smartmatch Operator"> is not
-identical to that proposed by the Perl 6 specification, mainly due to
-differences between Perl 6's and Perl 5's data models, but also because
-the Perl 6 spec has changed since Perl 5 rushed into early adoption.
-
-In Perl 6, C<when()> will always do an implicit smartmatch with its
-argument, while in Perl 5 it is convenient (albeit potentially confusing) to
-suppress this implicit smartmatch in various rather loosely-defined
-situations, as roughly outlined above. (The difference is largely because
-Perl 5 does not have, even internally, a boolean type.)
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlthrtut.pod b/Master/tlpkg/tlperl/lib/pods/perlthrtut.pod
deleted file mode 100644
index 6b693d1b0e1..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlthrtut.pod
+++ /dev/null
@@ -1,1178 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perlthrtut - Tutorial on threads in Perl
-
-=head1 DESCRIPTION
-
-This tutorial describes the use of Perl interpreter threads (sometimes
-referred to as I<ithreads>) that was first introduced in Perl 5.6.0. In this
-model, each thread runs in its own Perl interpreter, and any data sharing
-between threads must be explicit. The user-level interface for I<ithreads>
-uses the L<threads> class.
-
-B<NOTE>: There was another older Perl threading flavor called the 5.005 model
-that used the L<threads> class. This old model was known to have problems, is
-deprecated, and was removed for release 5.10. You are
-strongly encouraged to migrate any existing 5.005 threads code to the new
-model as soon as possible.
-
-You can see which (or neither) threading flavour you have by
-running C<perl -V> and looking at the C<Platform> section.
-If you have C<useithreads=define> you have ithreads, if you
-have C<use5005threads=define> you have 5.005 threads.
-If you have neither, you don't have any thread support built in.
-If you have both, you are in trouble.
-
-The L<threads> and L<threads::shared> modules are included in the core Perl
-distribution. Additionally, they are maintained as a separate modules on
-CPAN, so you can check there for any updates.
-
-=head1 What Is A Thread Anyway?
-
-A thread is a flow of control through a program with a single
-execution point.
-
-Sounds an awful lot like a process, doesn't it? Well, it should.
-Threads are one of the pieces of a process. Every process has at least
-one thread and, up until now, every process running Perl had only one
-thread. With 5.8, though, you can create extra threads. We're going
-to show you how, when, and why.
-
-=head1 Threaded Program Models
-
-There are three basic ways that you can structure a threaded
-program. Which model you choose depends on what you need your program
-to do. For many non-trivial threaded programs, you'll need to choose
-different models for different pieces of your program.
-
-=head2 Boss/Worker
-
-The boss/worker model usually has one I<boss> thread and one or more
-I<worker> threads. The boss thread gathers or generates tasks that need
-to be done, then parcels those tasks out to the appropriate worker
-thread.
-
-This model is common in GUI and server programs, where a main thread
-waits for some event and then passes that event to the appropriate
-worker threads for processing. Once the event has been passed on, the
-boss thread goes back to waiting for another event.
-
-The boss thread does relatively little work. While tasks aren't
-necessarily performed faster than with any other method, it tends to
-have the best user-response times.
-
-=head2 Work Crew
-
-In the work crew model, several threads are created that do
-essentially the same thing to different pieces of data. It closely
-mirrors classical parallel processing and vector processors, where a
-large array of processors do the exact same thing to many pieces of
-data.
-
-This model is particularly useful if the system running the program
-will distribute multiple threads across different processors. It can
-also be useful in ray tracing or rendering engines, where the
-individual threads can pass on interim results to give the user visual
-feedback.
-
-=head2 Pipeline
-
-The pipeline model divides up a task into a series of steps, and
-passes the results of one step on to the thread processing the
-next. Each thread does one thing to each piece of data and passes the
-results to the next thread in line.
-
-This model makes the most sense if you have multiple processors so two
-or more threads will be executing in parallel, though it can often
-make sense in other contexts as well. It tends to keep the individual
-tasks small and simple, as well as allowing some parts of the pipeline
-to block (on I/O or system calls, for example) while other parts keep
-going. If you're running different parts of the pipeline on different
-processors you may also take advantage of the caches on each
-processor.
-
-This model is also handy for a form of recursive programming where,
-rather than having a subroutine call itself, it instead creates
-another thread. Prime and Fibonacci generators both map well to this
-form of the pipeline model. (A version of a prime number generator is
-presented later on.)
-
-=head1 What kind of threads are Perl threads?
-
-If you have experience with other thread implementations, you might
-find that things aren't quite what you expect. It's very important to
-remember when dealing with Perl threads that I<Perl Threads Are Not X
-Threads> for all values of X. They aren't POSIX threads, or
-DecThreads, or Java's Green threads, or Win32 threads. There are
-similarities, and the broad concepts are the same, but if you start
-looking for implementation details you're going to be either
-disappointed or confused. Possibly both.
-
-This is not to say that Perl threads are completely different from
-everything that's ever come before. They're not. Perl's threading
-model owes a lot to other thread models, especially POSIX. Just as
-Perl is not C, though, Perl threads are not POSIX threads. So if you
-find yourself looking for mutexes, or thread priorities, it's time to
-step back a bit and think about what you want to do and how Perl can
-do it.
-
-However, it is important to remember that Perl threads cannot magically
-do things unless your operating system's threads allow it. So if your
-system blocks the entire process on C<sleep()>, Perl usually will, as well.
-
-B<Perl Threads Are Different.>
-
-=head1 Thread-Safe Modules
-
-The addition of threads has changed Perl's internals
-substantially. There are implications for people who write
-modules with XS code or external libraries. However, since Perl data is
-not shared among threads by default, Perl modules stand a high chance of
-being thread-safe or can be made thread-safe easily. Modules that are not
-tagged as thread-safe should be tested or code reviewed before being used
-in production code.
-
-Not all modules that you might use are thread-safe, and you should
-always assume a module is unsafe unless the documentation says
-otherwise. This includes modules that are distributed as part of the
-core. Threads are a relatively new feature, and even some of the standard
-modules aren't thread-safe.
-
-Even if a module is thread-safe, it doesn't mean that the module is optimized
-to work well with threads. A module could possibly be rewritten to utilize
-the new features in threaded Perl to increase performance in a threaded
-environment.
-
-If you're using a module that's not thread-safe for some reason, you
-can protect yourself by using it from one, and only one thread at all.
-If you need multiple threads to access such a module, you can use semaphores and
-lots of programming discipline to control access to it. Semaphores
-are covered in L</"Basic semaphores">.
-
-See also L</"Thread-Safety of System Libraries">.
-
-=head1 Thread Basics
-
-The L<threads> module provides the basic functions you need to write
-threaded programs. In the following sections, we'll cover the basics,
-showing you what you need to do to create a threaded program. After
-that, we'll go over some of the features of the L<threads> module that
-make threaded programming easier.
-
-=head2 Basic Thread Support
-
-Thread support is a Perl compile-time option. It's something that's
-turned on or off when Perl is built at your site, rather than when
-your programs are compiled. If your Perl wasn't compiled with thread
-support enabled, then any attempt to use threads will fail.
-
-Your programs can use the Config module to check whether threads are
-enabled. If your program can't run without them, you can say something
-like:
-
- use Config;
- $Config{useithreads} or die('Recompile Perl with threads to run this program.');
-
-A possibly-threaded program using a possibly-threaded module might
-have code like this:
-
- use Config;
- use MyMod;
-
- BEGIN {
- if ($Config{useithreads}) {
- # We have threads
- require MyMod_threaded;
- import MyMod_threaded;
- } else {
- require MyMod_unthreaded;
- import MyMod_unthreaded;
- }
- }
-
-Since code that runs both with and without threads is usually pretty
-messy, it's best to isolate the thread-specific code in its own
-module. In our example above, that's what C<MyMod_threaded> is, and it's
-only imported if we're running on a threaded Perl.
-
-=head2 A Note about the Examples
-
-In a real situation, care should be taken that all threads are finished
-executing before the program exits. That care has B<not> been taken in these
-examples in the interest of simplicity. Running these examples I<as is> will
-produce error messages, usually caused by the fact that there are still
-threads running when the program exits. You should not be alarmed by this.
-
-=head2 Creating Threads
-
-The L<threads> module provides the tools you need to create new
-threads. Like any other module, you need to tell Perl that you want to use
-it; C<use threads;> imports all the pieces you need to create basic
-threads.
-
-The simplest, most straightforward way to create a thread is with C<create()>:
-
- use threads;
-
- my $thr = threads->create(\&sub1);
-
- sub sub1 {
- print("In the thread\n");
- }
-
-The C<create()> method takes a reference to a subroutine and creates a new
-thread that starts executing in the referenced subroutine. Control
-then passes both to the subroutine and the caller.
-
-If you need to, your program can pass parameters to the subroutine as
-part of the thread startup. Just include the list of parameters as
-part of the C<threads-E<gt>create()> call, like this:
-
- use threads;
-
- my $Param3 = 'foo';
- my $thr1 = threads->create(\&sub1, 'Param 1', 'Param 2', $Param3);
- my @ParamList = (42, 'Hello', 3.14);
- my $thr2 = threads->create(\&sub1, @ParamList);
- my $thr3 = threads->create(\&sub1, qw(Param1 Param2 Param3));
-
- sub sub1 {
- my @InboundParameters = @_;
- print("In the thread\n");
- print('Got parameters >', join('<>', @InboundParameters), "<\n");
- }
-
-The last example illustrates another feature of threads. You can spawn
-off several threads using the same subroutine. Each thread executes
-the same subroutine, but in a separate thread with a separate
-environment and potentially separate arguments.
-
-C<new()> is a synonym for C<create()>.
-
-=head2 Waiting For A Thread To Exit
-
-Since threads are also subroutines, they can return values. To wait
-for a thread to exit and extract any values it might return, you can
-use the C<join()> method:
-
- use threads;
-
- my ($thr) = threads->create(\&sub1);
-
- my @ReturnData = $thr->join();
- print('Thread returned ', join(', ', @ReturnData), "\n");
-
- sub sub1 { return ('Fifty-six', 'foo', 2); }
-
-In the example above, the C<join()> method returns as soon as the thread
-ends. In addition to waiting for a thread to finish and gathering up
-any values that the thread might have returned, C<join()> also performs
-any OS cleanup necessary for the thread. That cleanup might be
-important, especially for long-running programs that spawn lots of
-threads. If you don't want the return values and don't want to wait
-for the thread to finish, you should call the C<detach()> method
-instead, as described next.
-
-NOTE: In the example above, the thread returns a list, thus necessitating
-that the thread creation call be made in list context (i.e., C<my ($thr)>).
-See L<< threads/"$thr->join()" >> and L<threads/"THREAD CONTEXT"> for more
-details on thread context and return values.
-
-=head2 Ignoring A Thread
-
-C<join()> does three things: it waits for a thread to exit, cleans up
-after it, and returns any data the thread may have produced. But what
-if you're not interested in the thread's return values, and you don't
-really care when the thread finishes? All you want is for the thread
-to get cleaned up after when it's done.
-
-In this case, you use the C<detach()> method. Once a thread is detached,
-it'll run until it's finished; then Perl will clean up after it
-automatically.
-
- use threads;
-
- my $thr = threads->create(\&sub1); # Spawn the thread
-
- $thr->detach(); # Now we officially don't care any more
-
- sleep(15); # Let thread run for awhile
-
- sub sub1 {
- $a = 0;
- while (1) {
- $a++;
- print("\$a is $a\n");
- sleep(1);
- }
- }
-
-Once a thread is detached, it may not be joined, and any return data
-that it might have produced (if it was done and waiting for a join) is
-lost.
-
-C<detach()> can also be called as a class method to allow a thread to
-detach itself:
-
- use threads;
-
- my $thr = threads->create(\&sub1);
-
- sub sub1 {
- threads->detach();
- # Do more work
- }
-
-=head2 Process and Thread Termination
-
-With threads one must be careful to make sure they all have a chance to
-run to completion, assuming that is what you want.
-
-An action that terminates a process will terminate I<all> running
-threads. die() and exit() have this property,
-and perl does an exit when the main thread exits,
-perhaps implicitly by falling off the end of your code,
-even if that's not what you want.
-
-As an example of this case, this code prints the message
-"Perl exited with active threads: 2 running and unjoined":
-
- use threads;
- my $thr1 = threads->new(\&thrsub, "test1");
- my $thr2 = threads->new(\&thrsub, "test2");
- sub thrsub {
- my ($message) = @_;
- sleep 1;
- print "thread $message\n";
- }
-
-But when the following lines are added at the end:
-
- $thr1->join();
- $thr2->join();
-
-it prints two lines of output, a perhaps more useful outcome.
-
-=head1 Threads And Data
-
-Now that we've covered the basics of threads, it's time for our next
-topic: Data. Threading introduces a couple of complications to data
-access that non-threaded programs never need to worry about.
-
-=head2 Shared And Unshared Data
-
-The biggest difference between Perl I<ithreads> and the old 5.005 style
-threading, or for that matter, to most other threading systems out there,
-is that by default, no data is shared. When a new Perl thread is created,
-all the data associated with the current thread is copied to the new
-thread, and is subsequently private to that new thread!
-This is similar in feel to what happens when a Unix process forks,
-except that in this case, the data is just copied to a different part of
-memory within the same process rather than a real fork taking place.
-
-To make use of threading, however, one usually wants the threads to share
-at least some data between themselves. This is done with the
-L<threads::shared> module and the C<:shared> attribute:
-
- use threads;
- use threads::shared;
-
- my $foo :shared = 1;
- my $bar = 1;
- threads->create(sub { $foo++; $bar++; })->join();
-
- print("$foo\n"); # Prints 2 since $foo is shared
- print("$bar\n"); # Prints 1 since $bar is not shared
-
-In the case of a shared array, all the array's elements are shared, and for
-a shared hash, all the keys and values are shared. This places
-restrictions on what may be assigned to shared array and hash elements: only
-simple values or references to shared variables are allowed - this is
-so that a private variable can't accidentally become shared. A bad
-assignment will cause the thread to die. For example:
-
- use threads;
- use threads::shared;
-
- my $var = 1;
- my $svar :shared = 2;
- my %hash :shared;
-
- ... create some threads ...
-
- $hash{a} = 1; # All threads see exists($hash{a}) and $hash{a} == 1
- $hash{a} = $var; # okay - copy-by-value: same effect as previous
- $hash{a} = $svar; # okay - copy-by-value: same effect as previous
- $hash{a} = \$svar; # okay - a reference to a shared variable
- $hash{a} = \$var; # This will die
- delete($hash{a}); # okay - all threads will see !exists($hash{a})
-
-Note that a shared variable guarantees that if two or more threads try to
-modify it at the same time, the internal state of the variable will not
-become corrupted. However, there are no guarantees beyond this, as
-explained in the next section.
-
-=head2 Thread Pitfalls: Races
-
-While threads bring a new set of useful tools, they also bring a
-number of pitfalls. One pitfall is the race condition:
-
- use threads;
- use threads::shared;
-
- my $a :shared = 1;
- my $thr1 = threads->create(\&sub1);
- my $thr2 = threads->create(\&sub2);
-
- $thr1->join();
- $thr2->join();
- print("$a\n");
-
- sub sub1 { my $foo = $a; $a = $foo + 1; }
- sub sub2 { my $bar = $a; $a = $bar + 1; }
-
-What do you think C<$a> will be? The answer, unfortunately, is I<it
-depends>. Both C<sub1()> and C<sub2()> access the global variable C<$a>, once
-to read and once to write. Depending on factors ranging from your
-thread implementation's scheduling algorithm to the phase of the moon,
-C<$a> can be 2 or 3.
-
-Race conditions are caused by unsynchronized access to shared
-data. Without explicit synchronization, there's no way to be sure that
-nothing has happened to the shared data between the time you access it
-and the time you update it. Even this simple code fragment has the
-possibility of error:
-
- use threads;
- my $a :shared = 2;
- my $b :shared;
- my $c :shared;
- my $thr1 = threads->create(sub { $b = $a; $a = $b + 1; });
- my $thr2 = threads->create(sub { $c = $a; $a = $c + 1; });
- $thr1->join();
- $thr2->join();
-
-Two threads both access C<$a>. Each thread can potentially be interrupted
-at any point, or be executed in any order. At the end, C<$a> could be 3
-or 4, and both C<$b> and C<$c> could be 2 or 3.
-
-Even C<$a += 5> or C<$a++> are not guaranteed to be atomic.
-
-Whenever your program accesses data or resources that can be accessed
-by other threads, you must take steps to coordinate access or risk
-data inconsistency and race conditions. Note that Perl will protect its
-internals from your race conditions, but it won't protect you from you.
-
-=head1 Synchronization and control
-
-Perl provides a number of mechanisms to coordinate the interactions
-between themselves and their data, to avoid race conditions and the like.
-Some of these are designed to resemble the common techniques used in thread
-libraries such as C<pthreads>; others are Perl-specific. Often, the
-standard techniques are clumsy and difficult to get right (such as
-condition waits). Where possible, it is usually easier to use Perlish
-techniques such as queues, which remove some of the hard work involved.
-
-=head2 Controlling access: lock()
-
-The C<lock()> function takes a shared variable and puts a lock on it.
-No other thread may lock the variable until the variable is unlocked
-by the thread holding the lock. Unlocking happens automatically
-when the locking thread exits the block that contains the call to the
-C<lock()> function. Using C<lock()> is straightforward: This example has
-several threads doing some calculations in parallel, and occasionally
-updating a running total:
-
- use threads;
- use threads::shared;
-
- my $total :shared = 0;
-
- sub calc {
- while (1) {
- my $result;
- # (... do some calculations and set $result ...)
- {
- lock($total); # Block until we obtain the lock
- $total += $result;
- } # Lock implicitly released at end of scope
- last if $result == 0;
- }
- }
-
- my $thr1 = threads->create(\&calc);
- my $thr2 = threads->create(\&calc);
- my $thr3 = threads->create(\&calc);
- $thr1->join();
- $thr2->join();
- $thr3->join();
- print("total=$total\n");
-
-C<lock()> blocks the thread until the variable being locked is
-available. When C<lock()> returns, your thread can be sure that no other
-thread can lock that variable until the block containing the
-lock exits.
-
-It's important to note that locks don't prevent access to the variable
-in question, only lock attempts. This is in keeping with Perl's
-longstanding tradition of courteous programming, and the advisory file
-locking that C<flock()> gives you.
-
-You may lock arrays and hashes as well as scalars. Locking an array,
-though, will not block subsequent locks on array elements, just lock
-attempts on the array itself.
-
-Locks are recursive, which means it's okay for a thread to
-lock a variable more than once. The lock will last until the outermost
-C<lock()> on the variable goes out of scope. For example:
-
- my $x :shared;
- doit();
-
- sub doit {
- {
- {
- lock($x); # Wait for lock
- lock($x); # NOOP - we already have the lock
- {
- lock($x); # NOOP
- {
- lock($x); # NOOP
- lockit_some_more();
- }
- }
- } # *** Implicit unlock here ***
- }
- }
-
- sub lockit_some_more {
- lock($x); # NOOP
- } # Nothing happens here
-
-Note that there is no C<unlock()> function - the only way to unlock a
-variable is to allow it to go out of scope.
-
-A lock can either be used to guard the data contained within the variable
-being locked, or it can be used to guard something else, like a section
-of code. In this latter case, the variable in question does not hold any
-useful data, and exists only for the purpose of being locked. In this
-respect, the variable behaves like the mutexes and basic semaphores of
-traditional thread libraries.
-
-=head2 A Thread Pitfall: Deadlocks
-
-Locks are a handy tool to synchronize access to data, and using them
-properly is the key to safe shared data. Unfortunately, locks aren't
-without their dangers, especially when multiple locks are involved.
-Consider the following code:
-
- use threads;
-
- my $a :shared = 4;
- my $b :shared = 'foo';
- my $thr1 = threads->create(sub {
- lock($a);
- sleep(20);
- lock($b);
- });
- my $thr2 = threads->create(sub {
- lock($b);
- sleep(20);
- lock($a);
- });
-
-This program will probably hang until you kill it. The only way it
-won't hang is if one of the two threads acquires both locks
-first. A guaranteed-to-hang version is more complicated, but the
-principle is the same.
-
-The first thread will grab a lock on C<$a>, then, after a pause during which
-the second thread has probably had time to do some work, try to grab a
-lock on C<$b>. Meanwhile, the second thread grabs a lock on C<$b>, then later
-tries to grab a lock on C<$a>. The second lock attempt for both threads will
-block, each waiting for the other to release its lock.
-
-This condition is called a deadlock, and it occurs whenever two or
-more threads are trying to get locks on resources that the others
-own. Each thread will block, waiting for the other to release a lock
-on a resource. That never happens, though, since the thread with the
-resource is itself waiting for a lock to be released.
-
-There are a number of ways to handle this sort of problem. The best
-way is to always have all threads acquire locks in the exact same
-order. If, for example, you lock variables C<$a>, C<$b>, and C<$c>, always lock
-C<$a> before C<$b>, and C<$b> before C<$c>. It's also best to hold on to locks for
-as short a period of time to minimize the risks of deadlock.
-
-The other synchronization primitives described below can suffer from
-similar problems.
-
-=head2 Queues: Passing Data Around
-
-A queue is a special thread-safe object that lets you put data in one
-end and take it out the other without having to worry about
-synchronization issues. They're pretty straightforward, and look like
-this:
-
- use threads;
- use Thread::Queue;
-
- my $DataQueue = Thread::Queue->new();
- my $thr = threads->create(sub {
- while (my $DataElement = $DataQueue->dequeue()) {
- print("Popped $DataElement off the queue\n");
- }
- });
-
- $DataQueue->enqueue(12);
- $DataQueue->enqueue("A", "B", "C");
- sleep(10);
- $DataQueue->enqueue(undef);
- $thr->join();
-
-You create the queue with C<Thread::Queue-E<gt>new()>. Then you can
-add lists of scalars onto the end with C<enqueue()>, and pop scalars off
-the front of it with C<dequeue()>. A queue has no fixed size, and can grow
-as needed to hold everything pushed on to it.
-
-If a queue is empty, C<dequeue()> blocks until another thread enqueues
-something. This makes queues ideal for event loops and other
-communications between threads.
-
-=head2 Semaphores: Synchronizing Data Access
-
-Semaphores are a kind of generic locking mechanism. In their most basic
-form, they behave very much like lockable scalars, except that they
-can't hold data, and that they must be explicitly unlocked. In their
-advanced form, they act like a kind of counter, and can allow multiple
-threads to have the I<lock> at any one time.
-
-=head2 Basic semaphores
-
-Semaphores have two methods, C<down()> and C<up()>: C<down()> decrements the resource
-count, while C<up()> increments it. Calls to C<down()> will block if the
-semaphore's current count would decrement below zero. This program
-gives a quick demonstration:
-
- use threads;
- use Thread::Semaphore;
-
- my $semaphore = Thread::Semaphore->new();
- my $GlobalVariable :shared = 0;
-
- $thr1 = threads->create(\&sample_sub, 1);
- $thr2 = threads->create(\&sample_sub, 2);
- $thr3 = threads->create(\&sample_sub, 3);
-
- sub sample_sub {
- my $SubNumber = shift(@_);
- my $TryCount = 10;
- my $LocalCopy;
- sleep(1);
- while ($TryCount--) {
- $semaphore->down();
- $LocalCopy = $GlobalVariable;
- print("$TryCount tries left for sub $SubNumber (\$GlobalVariable is $GlobalVariable)\n");
- sleep(2);
- $LocalCopy++;
- $GlobalVariable = $LocalCopy;
- $semaphore->up();
- }
- }
-
- $thr1->join();
- $thr2->join();
- $thr3->join();
-
-The three invocations of the subroutine all operate in sync. The
-semaphore, though, makes sure that only one thread is accessing the
-global variable at once.
-
-=head2 Advanced Semaphores
-
-By default, semaphores behave like locks, letting only one thread
-C<down()> them at a time. However, there are other uses for semaphores.
-
-Each semaphore has a counter attached to it. By default, semaphores are
-created with the counter set to one, C<down()> decrements the counter by
-one, and C<up()> increments by one. However, we can override any or all
-of these defaults simply by passing in different values:
-
- use threads;
- use Thread::Semaphore;
-
- my $semaphore = Thread::Semaphore->new(5);
- # Creates a semaphore with the counter set to five
-
- my $thr1 = threads->create(\&sub1);
- my $thr2 = threads->create(\&sub1);
-
- sub sub1 {
- $semaphore->down(5); # Decrements the counter by five
- # Do stuff here
- $semaphore->up(5); # Increment the counter by five
- }
-
- $thr1->detach();
- $thr2->detach();
-
-If C<down()> attempts to decrement the counter below zero, it blocks until
-the counter is large enough. Note that while a semaphore can be created
-with a starting count of zero, any C<up()> or C<down()> always changes the
-counter by at least one, and so C<< $semaphore->down(0) >> is the same as
-C<< $semaphore->down(1) >>.
-
-The question, of course, is why would you do something like this? Why
-create a semaphore with a starting count that's not one, or why
-decrement or increment it by more than one? The answer is resource
-availability. Many resources that you want to manage access for can be
-safely used by more than one thread at once.
-
-For example, let's take a GUI driven program. It has a semaphore that
-it uses to synchronize access to the display, so only one thread is
-ever drawing at once. Handy, but of course you don't want any thread
-to start drawing until things are properly set up. In this case, you
-can create a semaphore with a counter set to zero, and up it when
-things are ready for drawing.
-
-Semaphores with counters greater than one are also useful for
-establishing quotas. Say, for example, that you have a number of
-threads that can do I/O at once. You don't want all the threads
-reading or writing at once though, since that can potentially swamp
-your I/O channels, or deplete your process's quota of filehandles. You
-can use a semaphore initialized to the number of concurrent I/O
-requests (or open files) that you want at any one time, and have your
-threads quietly block and unblock themselves.
-
-Larger increments or decrements are handy in those cases where a
-thread needs to check out or return a number of resources at once.
-
-=head2 Waiting for a Condition
-
-The functions C<cond_wait()> and C<cond_signal()>
-can be used in conjunction with locks to notify
-co-operating threads that a resource has become available. They are
-very similar in use to the functions found in C<pthreads>. However
-for most purposes, queues are simpler to use and more intuitive. See
-L<threads::shared> for more details.
-
-=head2 Giving up control
-
-There are times when you may find it useful to have a thread
-explicitly give up the CPU to another thread. You may be doing something
-processor-intensive and want to make sure that the user-interface thread
-gets called frequently. Regardless, there are times that you might want
-a thread to give up the processor.
-
-Perl's threading package provides the C<yield()> function that does
-this. C<yield()> is pretty straightforward, and works like this:
-
- use threads;
-
- sub loop {
- my $thread = shift;
- my $foo = 50;
- while($foo--) { print("In thread $thread\n"); }
- threads->yield();
- $foo = 50;
- while($foo--) { print("In thread $thread\n"); }
- }
-
- my $thr1 = threads->create(\&loop, 'first');
- my $thr2 = threads->create(\&loop, 'second');
- my $thr3 = threads->create(\&loop, 'third');
-
-It is important to remember that C<yield()> is only a hint to give up the CPU,
-it depends on your hardware, OS and threading libraries what actually happens.
-B<On many operating systems, yield() is a no-op.> Therefore it is important
-to note that one should not build the scheduling of the threads around
-C<yield()> calls. It might work on your platform but it won't work on another
-platform.
-
-=head1 General Thread Utility Routines
-
-We've covered the workhorse parts of Perl's threading package, and
-with these tools you should be well on your way to writing threaded
-code and packages. There are a few useful little pieces that didn't
-really fit in anyplace else.
-
-=head2 What Thread Am I In?
-
-The C<threads-E<gt>self()> class method provides your program with a way to
-get an object representing the thread it's currently in. You can use this
-object in the same way as the ones returned from thread creation.
-
-=head2 Thread IDs
-
-C<tid()> is a thread object method that returns the thread ID of the
-thread the object represents. Thread IDs are integers, with the main
-thread in a program being 0. Currently Perl assigns a unique TID to
-every thread ever created in your program, assigning the first thread
-to be created a TID of 1, and increasing the TID by 1 for each new
-thread that's created. When used as a class method, C<threads-E<gt>tid()>
-can be used by a thread to get its own TID.
-
-=head2 Are These Threads The Same?
-
-The C<equal()> method takes two thread objects and returns true
-if the objects represent the same thread, and false if they don't.
-
-Thread objects also have an overloaded C<==> comparison so that you can do
-comparison on them as you would with normal objects.
-
-=head2 What Threads Are Running?
-
-C<threads-E<gt>list()> returns a list of thread objects, one for each thread
-that's currently running and not detached. Handy for a number of things,
-including cleaning up at the end of your program (from the main Perl thread,
-of course):
-
- # Loop through all the threads
- foreach my $thr (threads->list()) {
- $thr->join();
- }
-
-If some threads have not finished running when the main Perl thread
-ends, Perl will warn you about it and die, since it is impossible for Perl
-to clean up itself while other threads are running.
-
-NOTE: The main Perl thread (thread 0) is in a I<detached> state, and so
-does not appear in the list returned by C<threads-E<gt>list()>.
-
-=head1 A Complete Example
-
-Confused yet? It's time for an example program to show some of the
-things we've covered. This program finds prime numbers using threads.
-
- 1 #!/usr/bin/perl
- 2 # prime-pthread, courtesy of Tom Christiansen
- 3
- 4 use strict;
- 5 use warnings;
- 6
- 7 use threads;
- 8 use Thread::Queue;
- 9
- 10 sub check_num {
- 11 my ($upstream, $cur_prime) = @_;
- 12 my $kid;
- 13 my $downstream = Thread::Queue->new();
- 14 while (my $num = $upstream->dequeue()) {
- 15 next unless ($num % $cur_prime);
- 16 if ($kid) {
- 17 $downstream->enqueue($num);
- 18 } else {
- 19 print("Found prime: $num\n");
- 20 $kid = threads->create(\&check_num, $downstream, $num);
- 21 if (! $kid) {
- 22 warn("Sorry. Ran out of threads.\n");
- 23 last;
- 24 }
- 25 }
- 26 }
- 27 if ($kid) {
- 28 $downstream->enqueue(undef);
- 29 $kid->join();
- 30 }
- 31 }
- 32
- 33 my $stream = Thread::Queue->new(3..1000, undef);
- 34 check_num($stream, 2);
-
-This program uses the pipeline model to generate prime numbers. Each
-thread in the pipeline has an input queue that feeds numbers to be
-checked, a prime number that it's responsible for, and an output queue
-into which it funnels numbers that have failed the check. If the thread
-has a number that's failed its check and there's no child thread, then
-the thread must have found a new prime number. In that case, a new
-child thread is created for that prime and stuck on the end of the
-pipeline.
-
-This probably sounds a bit more confusing than it really is, so let's
-go through this program piece by piece and see what it does. (For
-those of you who might be trying to remember exactly what a prime
-number is, it's a number that's only evenly divisible by itself and 1.)
-
-The bulk of the work is done by the C<check_num()> subroutine, which
-takes a reference to its input queue and a prime number that it's
-responsible for. After pulling in the input queue and the prime that
-the subroutine is checking (line 11), we create a new queue (line 13)
-and reserve a scalar for the thread that we're likely to create later
-(line 12).
-
-The while loop from line 14 to line 26 grabs a scalar off the input
-queue and checks against the prime this thread is responsible
-for. Line 15 checks to see if there's a remainder when we divide the
-number to be checked by our prime. If there is one, the number
-must not be evenly divisible by our prime, so we need to either pass
-it on to the next thread if we've created one (line 17) or create a
-new thread if we haven't.
-
-The new thread creation is line 20. We pass on to it a reference to
-the queue we've created, and the prime number we've found. In lines 21
-through 24, we check to make sure that our new thread got created, and
-if not, we stop checking any remaining numbers in the queue.
-
-Finally, once the loop terminates (because we got a 0 or C<undef> in the
-queue, which serves as a note to terminate), we pass on the notice to our
-child, and wait for it to exit if we've created a child (lines 27 and
-30).
-
-Meanwhile, back in the main thread, we first create a queue (line 33) and
-queue up all the numbers from 3 to 1000 for checking, plus a termination
-notice. Then all we have to do to get the ball rolling is pass the queue
-and the first prime to the C<check_num()> subroutine (line 34).
-
-That's how it works. It's pretty simple; as with many Perl programs,
-the explanation is much longer than the program.
-
-=head1 Different implementations of threads
-
-Some background on thread implementations from the operating system
-viewpoint. There are three basic categories of threads: user-mode threads,
-kernel threads, and multiprocessor kernel threads.
-
-User-mode threads are threads that live entirely within a program and
-its libraries. In this model, the OS knows nothing about threads. As
-far as it's concerned, your process is just a process.
-
-This is the easiest way to implement threads, and the way most OSes
-start. The big disadvantage is that, since the OS knows nothing about
-threads, if one thread blocks they all do. Typical blocking activities
-include most system calls, most I/O, and things like C<sleep()>.
-
-Kernel threads are the next step in thread evolution. The OS knows
-about kernel threads, and makes allowances for them. The main
-difference between a kernel thread and a user-mode thread is
-blocking. With kernel threads, things that block a single thread don't
-block other threads. This is not the case with user-mode threads,
-where the kernel blocks at the process level and not the thread level.
-
-This is a big step forward, and can give a threaded program quite a
-performance boost over non-threaded programs. Threads that block
-performing I/O, for example, won't block threads that are doing other
-things. Each process still has only one thread running at once,
-though, regardless of how many CPUs a system might have.
-
-Since kernel threading can interrupt a thread at any time, they will
-uncover some of the implicit locking assumptions you may make in your
-program. For example, something as simple as C<$a = $a + 2> can behave
-unpredictably with kernel threads if C<$a> is visible to other
-threads, as another thread may have changed C<$a> between the time it
-was fetched on the right hand side and the time the new value is
-stored.
-
-Multiprocessor kernel threads are the final step in thread
-support. With multiprocessor kernel threads on a machine with multiple
-CPUs, the OS may schedule two or more threads to run simultaneously on
-different CPUs.
-
-This can give a serious performance boost to your threaded program,
-since more than one thread will be executing at the same time. As a
-tradeoff, though, any of those nagging synchronization issues that
-might not have shown with basic kernel threads will appear with a
-vengeance.
-
-In addition to the different levels of OS involvement in threads,
-different OSes (and different thread implementations for a particular
-OS) allocate CPU cycles to threads in different ways.
-
-Cooperative multitasking systems have running threads give up control
-if one of two things happen. If a thread calls a yield function, it
-gives up control. It also gives up control if the thread does
-something that would cause it to block, such as perform I/O. In a
-cooperative multitasking implementation, one thread can starve all the
-others for CPU time if it so chooses.
-
-Preemptive multitasking systems interrupt threads at regular intervals
-while the system decides which thread should run next. In a preemptive
-multitasking system, one thread usually won't monopolize the CPU.
-
-On some systems, there can be cooperative and preemptive threads
-running simultaneously. (Threads running with realtime priorities
-often behave cooperatively, for example, while threads running at
-normal priorities behave preemptively.)
-
-Most modern operating systems support preemptive multitasking nowadays.
-
-=head1 Performance considerations
-
-The main thing to bear in mind when comparing Perl's I<ithreads> to other threading
-models is the fact that for each new thread created, a complete copy of
-all the variables and data of the parent thread has to be taken. Thus,
-thread creation can be quite expensive, both in terms of memory usage and
-time spent in creation. The ideal way to reduce these costs is to have a
-relatively short number of long-lived threads, all created fairly early
-on (before the base thread has accumulated too much data). Of course, this
-may not always be possible, so compromises have to be made. However, after
-a thread has been created, its performance and extra memory usage should
-be little different than ordinary code.
-
-Also note that under the current implementation, shared variables
-use a little more memory and are a little slower than ordinary variables.
-
-=head1 Process-scope Changes
-
-Note that while threads themselves are separate execution threads and
-Perl data is thread-private unless explicitly shared, the threads can
-affect process-scope state, affecting all the threads.
-
-The most common example of this is changing the current working
-directory using C<chdir()>. One thread calls C<chdir()>, and the working
-directory of all the threads changes.
-
-Even more drastic example of a process-scope change is C<chroot()>:
-the root directory of all the threads changes, and no thread can
-undo it (as opposed to C<chdir()>).
-
-Further examples of process-scope changes include C<umask()> and
-changing uids and gids.
-
-Thinking of mixing C<fork()> and threads? Please lie down and wait
-until the feeling passes. Be aware that the semantics of C<fork()> vary
-between platforms. For example, some Unix systems copy all the current
-threads into the child process, while others only copy the thread that
-called C<fork()>. You have been warned!
-
-Similarly, mixing signals and threads may be problematic.
-Implementations are platform-dependent, and even the POSIX
-semantics may not be what you expect (and Perl doesn't even
-give you the full POSIX API). For example, there is no way to
-guarantee that a signal sent to a multi-threaded Perl application
-will get intercepted by any particular thread. (However, a recently
-added feature does provide the capability to send signals between
-threads. See L<threads/THREAD SIGNALLING> for more details.)
-
-=head1 Thread-Safety of System Libraries
-
-Whether various library calls are thread-safe is outside the control
-of Perl. Calls often suffering from not being thread-safe include:
-C<localtime()>, C<gmtime()>, functions fetching user, group and
-network information (such as C<getgrent()>, C<gethostent()>,
-C<getnetent()> and so on), C<readdir()>, C<rand()>, and C<srand()>. In
-general, calls that depend on some global external state.
-
-If the system Perl is compiled in has thread-safe variants of such
-calls, they will be used. Beyond that, Perl is at the mercy of
-the thread-safety or -unsafety of the calls. Please consult your
-C library call documentation.
-
-On some platforms the thread-safe library interfaces may fail if the
-result buffer is too small (for example the user group databases may
-be rather large, and the reentrant interfaces may have to carry around
-a full snapshot of those databases). Perl will start with a small
-buffer, but keep retrying and growing the result buffer
-until the result fits. If this limitless growing sounds bad for
-security or memory consumption reasons you can recompile Perl with
-C<PERL_REENTRANT_MAXSIZE> defined to the maximum number of bytes you will
-allow.
-
-=head1 Conclusion
-
-A complete thread tutorial could fill a book (and has, many times),
-but with what we've covered in this introduction, you should be well
-on your way to becoming a threaded Perl expert.
-
-=head1 SEE ALSO
-
-Annotated POD for L<threads>:
-L<http://annocpan.org/?mode=search&field=Module&name=threads>
-
-Latest version of L<threads> on CPAN:
-L<http://search.cpan.org/search?module=threads>
-
-Annotated POD for L<threads::shared>:
-L<http://annocpan.org/?mode=search&field=Module&name=threads%3A%3Ashared>
-
-Latest version of L<threads::shared> on CPAN:
-L<http://search.cpan.org/search?module=threads%3A%3Ashared>
-
-Perl threads mailing list:
-L<http://lists.perl.org/list/ithreads.html>
-
-=head1 Bibliography
-
-Here's a short bibliography courtesy of Jürgen Christoffel:
-
-=head2 Introductory Texts
-
-Birrell, Andrew D. An Introduction to Programming with
-Threads. Digital Equipment Corporation, 1989, DEC-SRC Research Report
-#35 online as
-ftp://ftp.dec.com/pub/DEC/SRC/research-reports/SRC-035.pdf
-(highly recommended)
-
-Robbins, Kay. A., and Steven Robbins. Practical Unix Programming: A
-Guide to Concurrency, Communication, and
-Multithreading. Prentice-Hall, 1996.
-
-Lewis, Bill, and Daniel J. Berg. Multithreaded Programming with
-Pthreads. Prentice Hall, 1997, ISBN 0-13-443698-9 (a well-written
-introduction to threads).
-
-Nelson, Greg (editor). Systems Programming with Modula-3. Prentice
-Hall, 1991, ISBN 0-13-590464-1.
-
-Nichols, Bradford, Dick Buttlar, and Jacqueline Proulx Farrell.
-Pthreads Programming. O'Reilly & Associates, 1996, ISBN 156592-115-1
-(covers POSIX threads).
-
-=head2 OS-Related References
-
-Boykin, Joseph, David Kirschen, Alan Langerman, and Susan
-LoVerso. Programming under Mach. Addison-Wesley, 1994, ISBN
-0-201-52739-1.
-
-Tanenbaum, Andrew S. Distributed Operating Systems. Prentice Hall,
-1995, ISBN 0-13-219908-4 (great textbook).
-
-Silberschatz, Abraham, and Peter B. Galvin. Operating System Concepts,
-4th ed. Addison-Wesley, 1995, ISBN 0-201-59292-4
-
-=head2 Other References
-
-Arnold, Ken and James Gosling. The Java Programming Language, 2nd
-ed. Addison-Wesley, 1998, ISBN 0-201-31006-6.
-
-comp.programming.threads FAQ,
-L<http://www.serpentine.com/~bos/threads-faq/>
-
-Le Sergent, T. and B. Berthomieu. "Incremental MultiThreaded Garbage
-Collection on Virtually Shared Memory Architectures" in Memory
-Management: Proc. of the International Workshop IWMM 92, St. Malo,
-France, September 1992, Yves Bekkers and Jacques Cohen, eds. Springer,
-1992, ISBN 3540-55940-X (real-life thread applications).
-
-Artur Bergman, "Where Wizards Fear To Tread", June 11, 2002,
-L<http://www.perl.com/pub/a/2002/06/11/threads.html>
-
-=head1 Acknowledgements
-
-Thanks (in no particular order) to Chaim Frenkel, Steve Fink, Gurusamy
-Sarathy, Ilya Zakharevich, Benjamin Sugars, Jürgen Christoffel, Joshua
-Pritikin, and Alan Burlison, for their help in reality-checking and
-polishing this article. Big thanks to Tom Christiansen for his rewrite
-of the prime number generator.
-
-=head1 AUTHOR
-
-Dan Sugalski E<lt>dan@sidhe.org<gt>
-
-Slightly modified by Arthur Bergman to fit the new thread model/module.
-
-Reworked slightly by Jörg Walter E<lt>jwalt@cpan.org<gt> to be more concise
-about thread-safety of Perl code.
-
-Rearranged slightly by Elizabeth Mattijsen E<lt>liz@dijkmat.nl<gt> to put
-less emphasis on yield().
-
-=head1 Copyrights
-
-The original version of this article originally appeared in The Perl
-Journal #10, and is copyright 1998 The Perl Journal. It appears courtesy
-of Jon Orwant and The Perl Journal. This document may be distributed
-under the same terms as Perl itself.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perltie.pod b/Master/tlpkg/tlperl/lib/pods/perltie.pod
deleted file mode 100644
index 887f2f02edd..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perltie.pod
+++ /dev/null
@@ -1,1225 +0,0 @@
-=head1 NAME
-X<tie>
-
-perltie - how to hide an object class in a simple variable
-
-=head1 SYNOPSIS
-
- tie VARIABLE, CLASSNAME, LIST
-
- $object = tied VARIABLE
-
- untie VARIABLE
-
-=head1 DESCRIPTION
-
-Prior to release 5.0 of Perl, a programmer could use dbmopen()
-to connect an on-disk database in the standard Unix dbm(3x)
-format magically to a %HASH in their program. However, their Perl was either
-built with one particular dbm library or another, but not both, and
-you couldn't extend this mechanism to other packages or types of variables.
-
-Now you can.
-
-The tie() function binds a variable to a class (package) that will provide
-the implementation for access methods for that variable. Once this magic
-has been performed, accessing a tied variable automatically triggers
-method calls in the proper class. The complexity of the class is
-hidden behind magic methods calls. The method names are in ALL CAPS,
-which is a convention that Perl uses to indicate that they're called
-implicitly rather than explicitly--just like the BEGIN() and END()
-functions.
-
-In the tie() call, C<VARIABLE> is the name of the variable to be
-enchanted. C<CLASSNAME> is the name of a class implementing objects of
-the correct type. Any additional arguments in the C<LIST> are passed to
-the appropriate constructor method for that class--meaning TIESCALAR(),
-TIEARRAY(), TIEHASH(), or TIEHANDLE(). (Typically these are arguments
-such as might be passed to the dbminit() function of C.) The object
-returned by the "new" method is also returned by the tie() function,
-which would be useful if you wanted to access other methods in
-C<CLASSNAME>. (You don't actually have to return a reference to a right
-"type" (e.g., HASH or C<CLASSNAME>) so long as it's a properly blessed
-object.) You can also retrieve a reference to the underlying object
-using the tied() function.
-
-Unlike dbmopen(), the tie() function will not C<use> or C<require> a module
-for you--you need to do that explicitly yourself.
-
-=head2 Tying Scalars
-X<scalar, tying>
-
-A class implementing a tied scalar should define the following methods:
-TIESCALAR, FETCH, STORE, and possibly UNTIE and/or DESTROY.
-
-Let's look at each in turn, using as an example a tie class for
-scalars that allows the user to do something like:
-
- tie $his_speed, 'Nice', getppid();
- tie $my_speed, 'Nice', $$;
-
-And now whenever either of those variables is accessed, its current
-system priority is retrieved and returned. If those variables are set,
-then the process's priority is changed!
-
-We'll use Jarkko Hietaniemi <F<jhi@iki.fi>>'s BSD::Resource class (not
-included) to access the PRIO_PROCESS, PRIO_MIN, and PRIO_MAX constants
-from your system, as well as the getpriority() and setpriority() system
-calls. Here's the preamble of the class.
-
- package Nice;
- use Carp;
- use BSD::Resource;
- use strict;
- $Nice::DEBUG = 0 unless defined $Nice::DEBUG;
-
-=over 4
-
-=item TIESCALAR classname, LIST
-X<TIESCALAR>
-
-This is the constructor for the class. That means it is
-expected to return a blessed reference to a new scalar
-(probably anonymous) that it's creating. For example:
-
- sub TIESCALAR {
- my $class = shift;
- my $pid = shift || $$; # 0 means me
-
- if ($pid !~ /^\d+$/) {
- carp "Nice::Tie::Scalar got non-numeric pid $pid" if $^W;
- return undef;
- }
-
- unless (kill 0, $pid) { # EPERM or ERSCH, no doubt
- carp "Nice::Tie::Scalar got bad pid $pid: $!" if $^W;
- return undef;
- }
-
- return bless \$pid, $class;
- }
-
-This tie class has chosen to return an error rather than raising an
-exception if its constructor should fail. While this is how dbmopen() works,
-other classes may well not wish to be so forgiving. It checks the global
-variable C<$^W> to see whether to emit a bit of noise anyway.
-
-=item FETCH this
-X<FETCH>
-
-This method will be triggered every time the tied variable is accessed
-(read). It takes no arguments beyond its self reference, which is the
-object representing the scalar we're dealing with. Because in this case
-we're using just a SCALAR ref for the tied scalar object, a simple $$self
-allows the method to get at the real value stored there. In our example
-below, that real value is the process ID to which we've tied our variable.
-
- sub FETCH {
- my $self = shift;
- confess "wrong type" unless ref $self;
- croak "usage error" if @_;
- my $nicety;
- local($!) = 0;
- $nicety = getpriority(PRIO_PROCESS, $$self);
- if ($!) { croak "getpriority failed: $!" }
- return $nicety;
- }
-
-This time we've decided to blow up (raise an exception) if the renice
-fails--there's no place for us to return an error otherwise, and it's
-probably the right thing to do.
-
-=item STORE this, value
-X<STORE>
-
-This method will be triggered every time the tied variable is set
-(assigned). Beyond its self reference, it also expects one (and only one)
-argument: the new value the user is trying to assign. Don't worry about
-returning a value from STORE; the semantic of assignment returning the
-assigned value is implemented with FETCH.
-
- sub STORE {
- my $self = shift;
- confess "wrong type" unless ref $self;
- my $new_nicety = shift;
- croak "usage error" if @_;
-
- if ($new_nicety < PRIO_MIN) {
- carp sprintf
- "WARNING: priority %d less than minimum system priority %d",
- $new_nicety, PRIO_MIN if $^W;
- $new_nicety = PRIO_MIN;
- }
-
- if ($new_nicety > PRIO_MAX) {
- carp sprintf
- "WARNING: priority %d greater than maximum system priority %d",
- $new_nicety, PRIO_MAX if $^W;
- $new_nicety = PRIO_MAX;
- }
-
- unless (defined setpriority(PRIO_PROCESS, $$self, $new_nicety)) {
- confess "setpriority failed: $!";
- }
- }
-
-=item UNTIE this
-X<UNTIE>
-
-This method will be triggered when the C<untie> occurs. This can be useful
-if the class needs to know when no further calls will be made. (Except DESTROY
-of course.) See L<The C<untie> Gotcha> below for more details.
-
-=item DESTROY this
-X<DESTROY>
-
-This method will be triggered when the tied variable needs to be destructed.
-As with other object classes, such a method is seldom necessary, because Perl
-deallocates its moribund object's memory for you automatically--this isn't
-C++, you know. We'll use a DESTROY method here for debugging purposes only.
-
- sub DESTROY {
- my $self = shift;
- confess "wrong type" unless ref $self;
- carp "[ Nice::DESTROY pid $$self ]" if $Nice::DEBUG;
- }
-
-=back
-
-That's about all there is to it. Actually, it's more than all there
-is to it, because we've done a few nice things here for the sake
-of completeness, robustness, and general aesthetics. Simpler
-TIESCALAR classes are certainly possible.
-
-=head2 Tying Arrays
-X<array, tying>
-
-A class implementing a tied ordinary array should define the following
-methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE and perhaps UNTIE and/or DESTROY.
-
-FETCHSIZE and STORESIZE are used to provide C<$#array> and
-equivalent C<scalar(@array)> access.
-
-The methods POP, PUSH, SHIFT, UNSHIFT, SPLICE, DELETE, and EXISTS are
-required if the perl operator with the corresponding (but lowercase) name
-is to operate on the tied array. The B<Tie::Array> class can be used as a
-base class to implement the first five of these in terms of the basic
-methods above. The default implementations of DELETE and EXISTS in
-B<Tie::Array> simply C<croak>.
-
-In addition EXTEND will be called when perl would have pre-extended
-allocation in a real array.
-
-For this discussion, we'll implement an array whose elements are a fixed
-size at creation. If you try to create an element larger than the fixed
-size, you'll take an exception. For example:
-
- use FixedElem_Array;
- tie @array, 'FixedElem_Array', 3;
- $array[0] = 'cat'; # ok.
- $array[1] = 'dogs'; # exception, length('dogs') > 3.
-
-The preamble code for the class is as follows:
-
- package FixedElem_Array;
- use Carp;
- use strict;
-
-=over 4
-
-=item TIEARRAY classname, LIST
-X<TIEARRAY>
-
-This is the constructor for the class. That means it is expected to
-return a blessed reference through which the new array (probably an
-anonymous ARRAY ref) will be accessed.
-
-In our example, just to show you that you don't I<really> have to return an
-ARRAY reference, we'll choose a HASH reference to represent our object.
-A HASH works out well as a generic record type: the C<{ELEMSIZE}> field will
-store the maximum element size allowed, and the C<{ARRAY}> field will hold the
-true ARRAY ref. If someone outside the class tries to dereference the
-object returned (doubtless thinking it an ARRAY ref), they'll blow up.
-This just goes to show you that you should respect an object's privacy.
-
- sub TIEARRAY {
- my $class = shift;
- my $elemsize = shift;
- if ( @_ || $elemsize =~ /\D/ ) {
- croak "usage: tie ARRAY, '" . __PACKAGE__ . "', elem_size";
- }
- return bless {
- ELEMSIZE => $elemsize,
- ARRAY => [],
- }, $class;
- }
-
-=item FETCH this, index
-X<FETCH>
-
-This method will be triggered every time an individual element the tied array
-is accessed (read). It takes one argument beyond its self reference: the
-index whose value we're trying to fetch.
-
- sub FETCH {
- my $self = shift;
- my $index = shift;
- return $self->{ARRAY}->[$index];
- }
-
-If a negative array index is used to read from an array, the index
-will be translated to a positive one internally by calling FETCHSIZE
-before being passed to FETCH. You may disable this feature by
-assigning a true value to the variable C<$NEGATIVE_INDICES> in the
-tied array class.
-
-As you may have noticed, the name of the FETCH method (et al.) is the same
-for all accesses, even though the constructors differ in names (TIESCALAR
-vs TIEARRAY). While in theory you could have the same class servicing
-several tied types, in practice this becomes cumbersome, and it's easiest
-to keep them at simply one tie type per class.
-
-=item STORE this, index, value
-X<STORE>
-
-This method will be triggered every time an element in the tied array is set
-(written). It takes two arguments beyond its self reference: the index at
-which we're trying to store something and the value we're trying to put
-there.
-
-In our example, C<undef> is really C<$self-E<gt>{ELEMSIZE}> number of
-spaces so we have a little more work to do here:
-
- sub STORE {
- my $self = shift;
- my( $index, $value ) = @_;
- if ( length $value > $self->{ELEMSIZE} ) {
- croak "length of $value is greater than $self->{ELEMSIZE}";
- }
- # fill in the blanks
- $self->EXTEND( $index ) if $index > $self->FETCHSIZE();
- # right justify to keep element size for smaller elements
- $self->{ARRAY}->[$index] = sprintf "%$self->{ELEMSIZE}s", $value;
- }
-
-Negative indexes are treated the same as with FETCH.
-
-=item FETCHSIZE this
-X<FETCHSIZE>
-
-Returns the total number of items in the tied array associated with
-object I<this>. (Equivalent to C<scalar(@array)>). For example:
-
- sub FETCHSIZE {
- my $self = shift;
- return scalar @{$self->{ARRAY}};
- }
-
-=item STORESIZE this, count
-X<STORESIZE>
-
-Sets the total number of items in the tied array associated with
-object I<this> to be I<count>. If this makes the array larger then
-class's mapping of C<undef> should be returned for new positions.
-If the array becomes smaller then entries beyond count should be
-deleted.
-
-In our example, 'undef' is really an element containing
-C<$self-E<gt>{ELEMSIZE}> number of spaces. Observe:
-
- sub STORESIZE {
- my $self = shift;
- my $count = shift;
- if ( $count > $self->FETCHSIZE() ) {
- foreach ( $count - $self->FETCHSIZE() .. $count ) {
- $self->STORE( $_, '' );
- }
- } elsif ( $count < $self->FETCHSIZE() ) {
- foreach ( 0 .. $self->FETCHSIZE() - $count - 2 ) {
- $self->POP();
- }
- }
- }
-
-=item EXTEND this, count
-X<EXTEND>
-
-Informative call that array is likely to grow to have I<count> entries.
-Can be used to optimize allocation. This method need do nothing.
-
-In our example, we want to make sure there are no blank (C<undef>)
-entries, so C<EXTEND> will make use of C<STORESIZE> to fill elements
-as needed:
-
- sub EXTEND {
- my $self = shift;
- my $count = shift;
- $self->STORESIZE( $count );
- }
-
-=item EXISTS this, key
-X<EXISTS>
-
-Verify that the element at index I<key> exists in the tied array I<this>.
-
-In our example, we will determine that if an element consists of
-C<$self-E<gt>{ELEMSIZE}> spaces only, it does not exist:
-
- sub EXISTS {
- my $self = shift;
- my $index = shift;
- return 0 if ! defined $self->{ARRAY}->[$index] ||
- $self->{ARRAY}->[$index] eq ' ' x $self->{ELEMSIZE};
- return 1;
- }
-
-=item DELETE this, key
-X<DELETE>
-
-Delete the element at index I<key> from the tied array I<this>.
-
-In our example, a deleted item is C<$self-E<gt>{ELEMSIZE}> spaces:
-
- sub DELETE {
- my $self = shift;
- my $index = shift;
- return $self->STORE( $index, '' );
- }
-
-=item CLEAR this
-X<CLEAR>
-
-Clear (remove, delete, ...) all values from the tied array associated with
-object I<this>. For example:
-
- sub CLEAR {
- my $self = shift;
- return $self->{ARRAY} = [];
- }
-
-=item PUSH this, LIST
-X<PUSH>
-
-Append elements of I<LIST> to the array. For example:
-
- sub PUSH {
- my $self = shift;
- my @list = @_;
- my $last = $self->FETCHSIZE();
- $self->STORE( $last + $_, $list[$_] ) foreach 0 .. $#list;
- return $self->FETCHSIZE();
- }
-
-=item POP this
-X<POP>
-
-Remove last element of the array and return it. For example:
-
- sub POP {
- my $self = shift;
- return pop @{$self->{ARRAY}};
- }
-
-=item SHIFT this
-X<SHIFT>
-
-Remove the first element of the array (shifting other elements down)
-and return it. For example:
-
- sub SHIFT {
- my $self = shift;
- return shift @{$self->{ARRAY}};
- }
-
-=item UNSHIFT this, LIST
-X<UNSHIFT>
-
-Insert LIST elements at the beginning of the array, moving existing elements
-up to make room. For example:
-
- sub UNSHIFT {
- my $self = shift;
- my @list = @_;
- my $size = scalar( @list );
- # make room for our list
- @{$self->{ARRAY}}[ $size .. $#{$self->{ARRAY}} + $size ]
- = @{$self->{ARRAY}};
- $self->STORE( $_, $list[$_] ) foreach 0 .. $#list;
- }
-
-=item SPLICE this, offset, length, LIST
-X<SPLICE>
-
-Perform the equivalent of C<splice> on the array.
-
-I<offset> is optional and defaults to zero, negative values count back
-from the end of the array.
-
-I<length> is optional and defaults to rest of the array.
-
-I<LIST> may be empty.
-
-Returns a list of the original I<length> elements at I<offset>.
-
-In our example, we'll use a little shortcut if there is a I<LIST>:
-
- sub SPLICE {
- my $self = shift;
- my $offset = shift || 0;
- my $length = shift || $self->FETCHSIZE() - $offset;
- my @list = ();
- if ( @_ ) {
- tie @list, __PACKAGE__, $self->{ELEMSIZE};
- @list = @_;
- }
- return splice @{$self->{ARRAY}}, $offset, $length, @list;
- }
-
-=item UNTIE this
-X<UNTIE>
-
-Will be called when C<untie> happens. (See L<The C<untie> Gotcha> below.)
-
-=item DESTROY this
-X<DESTROY>
-
-This method will be triggered when the tied variable needs to be destructed.
-As with the scalar tie class, this is almost never needed in a
-language that does its own garbage collection, so this time we'll
-just leave it out.
-
-=back
-
-=head2 Tying Hashes
-X<hash, tying>
-
-Hashes were the first Perl data type to be tied (see dbmopen()). A class
-implementing a tied hash should define the following methods: TIEHASH is
-the constructor. FETCH and STORE access the key and value pairs. EXISTS
-reports whether a key is present in the hash, and DELETE deletes one.
-CLEAR empties the hash by deleting all the key and value pairs. FIRSTKEY
-and NEXTKEY implement the keys() and each() functions to iterate over all
-the keys. SCALAR is triggered when the tied hash is evaluated in scalar
-context. UNTIE is called when C<untie> happens, and DESTROY is called when
-the tied variable is garbage collected.
-
-If this seems like a lot, then feel free to inherit from merely the
-standard Tie::StdHash module for most of your methods, redefining only the
-interesting ones. See L<Tie::Hash> for details.
-
-Remember that Perl distinguishes between a key not existing in the hash,
-and the key existing in the hash but having a corresponding value of
-C<undef>. The two possibilities can be tested with the C<exists()> and
-C<defined()> functions.
-
-Here's an example of a somewhat interesting tied hash class: it gives you
-a hash representing a particular user's dot files. You index into the hash
-with the name of the file (minus the dot) and you get back that dot file's
-contents. For example:
-
- use DotFiles;
- tie %dot, 'DotFiles';
- if ( $dot{profile} =~ /MANPATH/ ||
- $dot{login} =~ /MANPATH/ ||
- $dot{cshrc} =~ /MANPATH/ )
- {
- print "you seem to set your MANPATH\n";
- }
-
-Or here's another sample of using our tied class:
-
- tie %him, 'DotFiles', 'daemon';
- foreach $f ( keys %him ) {
- printf "daemon dot file %s is size %d\n",
- $f, length $him{$f};
- }
-
-In our tied hash DotFiles example, we use a regular
-hash for the object containing several important
-fields, of which only the C<{LIST}> field will be what the
-user thinks of as the real hash.
-
-=over 5
-
-=item USER
-
-whose dot files this object represents
-
-=item HOME
-
-where those dot files live
-
-=item CLOBBER
-
-whether we should try to change or remove those dot files
-
-=item LIST
-
-the hash of dot file names and content mappings
-
-=back
-
-Here's the start of F<Dotfiles.pm>:
-
- package DotFiles;
- use Carp;
- sub whowasi { (caller(1))[3] . '()' }
- my $DEBUG = 0;
- sub debug { $DEBUG = @_ ? shift : 1 }
-
-For our example, we want to be able to emit debugging info to help in tracing
-during development. We keep also one convenience function around
-internally to help print out warnings; whowasi() returns the function name
-that calls it.
-
-Here are the methods for the DotFiles tied hash.
-
-=over 4
-
-=item TIEHASH classname, LIST
-X<TIEHASH>
-
-This is the constructor for the class. That means it is expected to
-return a blessed reference through which the new object (probably but not
-necessarily an anonymous hash) will be accessed.
-
-Here's the constructor:
-
- sub TIEHASH {
- my $self = shift;
- my $user = shift || $>;
- my $dotdir = shift || '';
- croak "usage: @{[&whowasi]} [USER [DOTDIR]]" if @_;
- $user = getpwuid($user) if $user =~ /^\d+$/;
- my $dir = (getpwnam($user))[7]
- || croak "@{[&whowasi]}: no user $user";
- $dir .= "/$dotdir" if $dotdir;
-
- my $node = {
- USER => $user,
- HOME => $dir,
- LIST => {},
- CLOBBER => 0,
- };
-
- opendir(DIR, $dir)
- || croak "@{[&whowasi]}: can't opendir $dir: $!";
- foreach $dot ( grep /^\./ && -f "$dir/$_", readdir(DIR)) {
- $dot =~ s/^\.//;
- $node->{LIST}{$dot} = undef;
- }
- closedir DIR;
- return bless $node, $self;
- }
-
-It's probably worth mentioning that if you're going to filetest the
-return values out of a readdir, you'd better prepend the directory
-in question. Otherwise, because we didn't chdir() there, it would
-have been testing the wrong file.
-
-=item FETCH this, key
-X<FETCH>
-
-This method will be triggered every time an element in the tied hash is
-accessed (read). It takes one argument beyond its self reference: the key
-whose value we're trying to fetch.
-
-Here's the fetch for our DotFiles example.
-
- sub FETCH {
- carp &whowasi if $DEBUG;
- my $self = shift;
- my $dot = shift;
- my $dir = $self->{HOME};
- my $file = "$dir/.$dot";
-
- unless (exists $self->{LIST}->{$dot} || -f $file) {
- carp "@{[&whowasi]}: no $dot file" if $DEBUG;
- return undef;
- }
-
- if (defined $self->{LIST}->{$dot}) {
- return $self->{LIST}->{$dot};
- } else {
- return $self->{LIST}->{$dot} = `cat $dir/.$dot`;
- }
- }
-
-It was easy to write by having it call the Unix cat(1) command, but it
-would probably be more portable to open the file manually (and somewhat
-more efficient). Of course, because dot files are a Unixy concept, we're
-not that concerned.
-
-=item STORE this, key, value
-X<STORE>
-
-This method will be triggered every time an element in the tied hash is set
-(written). It takes two arguments beyond its self reference: the index at
-which we're trying to store something, and the value we're trying to put
-there.
-
-Here in our DotFiles example, we'll be careful not to let
-them try to overwrite the file unless they've called the clobber()
-method on the original object reference returned by tie().
-
- sub STORE {
- carp &whowasi if $DEBUG;
- my $self = shift;
- my $dot = shift;
- my $value = shift;
- my $file = $self->{HOME} . "/.$dot";
- my $user = $self->{USER};
-
- croak "@{[&whowasi]}: $file not clobberable"
- unless $self->{CLOBBER};
-
- open(my $f, '>', $file) || croak "can't open $file: $!";
- print $f $value;
- close($f);
- }
-
-If they wanted to clobber something, they might say:
-
- $ob = tie %daemon_dots, 'daemon';
- $ob->clobber(1);
- $daemon_dots{signature} = "A true daemon\n";
-
-Another way to lay hands on a reference to the underlying object is to
-use the tied() function, so they might alternately have set clobber
-using:
-
- tie %daemon_dots, 'daemon';
- tied(%daemon_dots)->clobber(1);
-
-The clobber method is simply:
-
- sub clobber {
- my $self = shift;
- $self->{CLOBBER} = @_ ? shift : 1;
- }
-
-=item DELETE this, key
-X<DELETE>
-
-This method is triggered when we remove an element from the hash,
-typically by using the delete() function. Again, we'll
-be careful to check whether they really want to clobber files.
-
- sub DELETE {
- carp &whowasi if $DEBUG;
-
- my $self = shift;
- my $dot = shift;
- my $file = $self->{HOME} . "/.$dot";
- croak "@{[&whowasi]}: won't remove file $file"
- unless $self->{CLOBBER};
- delete $self->{LIST}->{$dot};
- my $success = unlink($file);
- carp "@{[&whowasi]}: can't unlink $file: $!" unless $success;
- $success;
- }
-
-The value returned by DELETE becomes the return value of the call
-to delete(). If you want to emulate the normal behavior of delete(),
-you should return whatever FETCH would have returned for this key.
-In this example, we have chosen instead to return a value which tells
-the caller whether the file was successfully deleted.
-
-=item CLEAR this
-X<CLEAR>
-
-This method is triggered when the whole hash is to be cleared, usually by
-assigning the empty list to it.
-
-In our example, that would remove all the user's dot files! It's such a
-dangerous thing that they'll have to set CLOBBER to something higher than
-1 to make it happen.
-
- sub CLEAR {
- carp &whowasi if $DEBUG;
- my $self = shift;
- croak "@{[&whowasi]}: won't remove all dot files for $self->{USER}"
- unless $self->{CLOBBER} > 1;
- my $dot;
- foreach $dot ( keys %{$self->{LIST}}) {
- $self->DELETE($dot);
- }
- }
-
-=item EXISTS this, key
-X<EXISTS>
-
-This method is triggered when the user uses the exists() function
-on a particular hash. In our example, we'll look at the C<{LIST}>
-hash element for this:
-
- sub EXISTS {
- carp &whowasi if $DEBUG;
- my $self = shift;
- my $dot = shift;
- return exists $self->{LIST}->{$dot};
- }
-
-=item FIRSTKEY this
-X<FIRSTKEY>
-
-This method will be triggered when the user is going
-to iterate through the hash, such as via a keys() or each()
-call.
-
- sub FIRSTKEY {
- carp &whowasi if $DEBUG;
- my $self = shift;
- my $a = keys %{$self->{LIST}}; # reset each() iterator
- each %{$self->{LIST}}
- }
-
-=item NEXTKEY this, lastkey
-X<NEXTKEY>
-
-This method gets triggered during a keys() or each() iteration. It has a
-second argument which is the last key that had been accessed. This is
-useful if you're carrying about ordering or calling the iterator from more
-than one sequence, or not really storing things in a hash anywhere.
-
-For our example, we're using a real hash so we'll do just the simple
-thing, but we'll have to go through the LIST field indirectly.
-
- sub NEXTKEY {
- carp &whowasi if $DEBUG;
- my $self = shift;
- return each %{ $self->{LIST} }
- }
-
-=item SCALAR this
-X<SCALAR>
-
-This is called when the hash is evaluated in scalar context. In order
-to mimic the behaviour of untied hashes, this method should return a
-false value when the tied hash is considered empty. If this method does
-not exist, perl will make some educated guesses and return true when
-the hash is inside an iteration. If this isn't the case, FIRSTKEY is
-called, and the result will be a false value if FIRSTKEY returns the empty
-list, true otherwise.
-
-However, you should B<not> blindly rely on perl always doing the right
-thing. Particularly, perl will mistakenly return true when you clear the
-hash by repeatedly calling DELETE until it is empty. You are therefore
-advised to supply your own SCALAR method when you want to be absolutely
-sure that your hash behaves nicely in scalar context.
-
-In our example we can just call C<scalar> on the underlying hash
-referenced by C<$self-E<gt>{LIST}>:
-
- sub SCALAR {
- carp &whowasi if $DEBUG;
- my $self = shift;
- return scalar %{ $self->{LIST} }
- }
-
-=item UNTIE this
-X<UNTIE>
-
-This is called when C<untie> occurs. See L<The C<untie> Gotcha> below.
-
-=item DESTROY this
-X<DESTROY>
-
-This method is triggered when a tied hash is about to go out of
-scope. You don't really need it unless you're trying to add debugging
-or have auxiliary state to clean up. Here's a very simple function:
-
- sub DESTROY {
- carp &whowasi if $DEBUG;
- }
-
-=back
-
-Note that functions such as keys() and values() may return huge lists
-when used on large objects, like DBM files. You may prefer to use the
-each() function to iterate over such. Example:
-
- # print out history file offsets
- use NDBM_File;
- tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
- while (($key,$val) = each %HIST) {
- print $key, ' = ', unpack('L',$val), "\n";
- }
- untie(%HIST);
-
-=head2 Tying FileHandles
-X<filehandle, tying>
-
-This is partially implemented now.
-
-A class implementing a tied filehandle should define the following
-methods: TIEHANDLE, at least one of PRINT, PRINTF, WRITE, READLINE, GETC,
-READ, and possibly CLOSE, UNTIE and DESTROY. The class can also provide: BINMODE,
-OPEN, EOF, FILENO, SEEK, TELL - if the corresponding perl operators are
-used on the handle.
-
-When STDERR is tied, its PRINT method will be called to issue warnings
-and error messages. This feature is temporarily disabled during the call,
-which means you can use C<warn()> inside PRINT without starting a recursive
-loop. And just like C<__WARN__> and C<__DIE__> handlers, STDERR's PRINT
-method may be called to report parser errors, so the caveats mentioned under
-L<perlvar/%SIG> apply.
-
-All of this is especially useful when perl is embedded in some other
-program, where output to STDOUT and STDERR may have to be redirected
-in some special way. See nvi and the Apache module for examples.
-
-When tying a handle, the first argument to C<tie> should begin with an
-asterisk. So, if you are tying STDOUT, use C<*STDOUT>. If you have
-assigned it to a scalar variable, say C<$handle>, use C<*$handle>.
-C<tie $handle> ties the scalar variable C<$handle>, not the handle inside
-it.
-
-In our example we're going to create a shouting handle.
-
- package Shout;
-
-=over 4
-
-=item TIEHANDLE classname, LIST
-X<TIEHANDLE>
-
-This is the constructor for the class. That means it is expected to
-return a blessed reference of some sort. The reference can be used to
-hold some internal information.
-
- sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift }
-
-=item WRITE this, LIST
-X<WRITE>
-
-This method will be called when the handle is written to via the
-C<syswrite> function.
-
- sub WRITE {
- $r = shift;
- my($buf,$len,$offset) = @_;
- print "WRITE called, \$buf=$buf, \$len=$len, \$offset=$offset";
- }
-
-=item PRINT this, LIST
-X<PRINT>
-
-This method will be triggered every time the tied handle is printed to
-with the C<print()> or C<say()> functions. Beyond its self reference
-it also expects the list that was passed to the print function.
-
- sub PRINT { $r = shift; $$r++; print join($,,map(uc($_),@_)),$\ }
-
-C<say()> acts just like C<print()> except $\ will be localized to C<\n> so
-you need do nothing special to handle C<say()> in C<PRINT()>.
-
-=item PRINTF this, LIST
-X<PRINTF>
-
-This method will be triggered every time the tied handle is printed to
-with the C<printf()> function.
-Beyond its self reference it also expects the format and list that was
-passed to the printf function.
-
- sub PRINTF {
- shift;
- my $fmt = shift;
- print sprintf($fmt, @_);
- }
-
-=item READ this, LIST
-X<READ>
-
-This method will be called when the handle is read from via the C<read>
-or C<sysread> functions.
-
- sub READ {
- my $self = shift;
- my $bufref = \$_[0];
- my(undef,$len,$offset) = @_;
- print "READ called, \$buf=$bufref, \$len=$len, \$offset=$offset";
- # add to $$bufref, set $len to number of characters read
- $len;
- }
-
-=item READLINE this
-X<READLINE>
-
-This method is called when the handle is read via C<E<lt>HANDLEE<gt>>
-or C<readline HANDLE>.
-
-As per L<C<readline>|perlfunc/readline>, in scalar context it should return
-the next line, or C<undef> for no more data. In list context it should
-return all remaining lines, or an empty list for no more data. The strings
-returned should include the input record separator C<$/> (see L<perlvar>),
-unless it is C<undef> (which means "slurp" mode).
-
- sub READLINE {
- my $r = shift;
- if (wantarray) {
- return ("all remaining\n",
- "lines up\n",
- "to eof\n");
- } else {
- return "READLINE called " . ++$$r . " times\n";
- }
- }
-
-=item GETC this
-X<GETC>
-
-This method will be called when the C<getc> function is called.
-
- sub GETC { print "Don't GETC, Get Perl"; return "a"; }
-
-=item EOF this
-X<EOF>
-
-This method will be called when the C<eof> function is called.
-
-Starting with Perl 5.12, an additional integer parameter will be passed. It
-will be zero if C<eof> is called without parameter; C<1> if C<eof> is given
-a filehandle as a parameter, e.g. C<eof(FH)>; and C<2> in the very special
-case that the tied filehandle is C<ARGV> and C<eof> is called with an empty
-parameter list, e.g. C<eof()>.
-
- sub EOF { not length $stringbuf }
-
-=item CLOSE this
-X<CLOSE>
-
-This method will be called when the handle is closed via the C<close>
-function.
-
- sub CLOSE { print "CLOSE called.\n" }
-
-=item UNTIE this
-X<UNTIE>
-
-As with the other types of ties, this method will be called when C<untie> happens.
-It may be appropriate to "auto CLOSE" when this occurs. See
-L<The C<untie> Gotcha> below.
-
-=item DESTROY this
-X<DESTROY>
-
-As with the other types of ties, this method will be called when the
-tied handle is about to be destroyed. This is useful for debugging and
-possibly cleaning up.
-
- sub DESTROY { print "</shout>\n" }
-
-=back
-
-Here's how to use our little example:
-
- tie(*FOO,'Shout');
- print FOO "hello\n";
- $a = 4; $b = 6;
- print FOO $a, " plus ", $b, " equals ", $a + $b, "\n";
- print <FOO>;
-
-=head2 UNTIE this
-X<UNTIE>
-
-You can define for all tie types an UNTIE method that will be called
-at untie(). See L<The C<untie> Gotcha> below.
-
-=head2 The C<untie> Gotcha
-X<untie>
-
-If you intend making use of the object returned from either tie() or
-tied(), and if the tie's target class defines a destructor, there is a
-subtle gotcha you I<must> guard against.
-
-As setup, consider this (admittedly rather contrived) example of a
-tie; all it does is use a file to keep a log of the values assigned to
-a scalar.
-
- package Remember;
-
- use strict;
- use warnings;
- use IO::File;
-
- sub TIESCALAR {
- my $class = shift;
- my $filename = shift;
- my $handle = IO::File->new( "> $filename" )
- or die "Cannot open $filename: $!\n";
-
- print $handle "The Start\n";
- bless {FH => $handle, Value => 0}, $class;
- }
-
- sub FETCH {
- my $self = shift;
- return $self->{Value};
- }
-
- sub STORE {
- my $self = shift;
- my $value = shift;
- my $handle = $self->{FH};
- print $handle "$value\n";
- $self->{Value} = $value;
- }
-
- sub DESTROY {
- my $self = shift;
- my $handle = $self->{FH};
- print $handle "The End\n";
- close $handle;
- }
-
- 1;
-
-Here is an example that makes use of this tie:
-
- use strict;
- use Remember;
-
- my $fred;
- tie $fred, 'Remember', 'myfile.txt';
- $fred = 1;
- $fred = 4;
- $fred = 5;
- untie $fred;
- system "cat myfile.txt";
-
-This is the output when it is executed:
-
- The Start
- 1
- 4
- 5
- The End
-
-So far so good. Those of you who have been paying attention will have
-spotted that the tied object hasn't been used so far. So lets add an
-extra method to the Remember class to allow comments to be included in
-the file; say, something like this:
-
- sub comment {
- my $self = shift;
- my $text = shift;
- my $handle = $self->{FH};
- print $handle $text, "\n";
- }
-
-And here is the previous example modified to use the C<comment> method
-(which requires the tied object):
-
- use strict;
- use Remember;
-
- my ($fred, $x);
- $x = tie $fred, 'Remember', 'myfile.txt';
- $fred = 1;
- $fred = 4;
- comment $x "changing...";
- $fred = 5;
- untie $fred;
- system "cat myfile.txt";
-
-When this code is executed there is no output. Here's why:
-
-When a variable is tied, it is associated with the object which is the
-return value of the TIESCALAR, TIEARRAY, or TIEHASH function. This
-object normally has only one reference, namely, the implicit reference
-from the tied variable. When untie() is called, that reference is
-destroyed. Then, as in the first example above, the object's
-destructor (DESTROY) is called, which is normal for objects that have
-no more valid references; and thus the file is closed.
-
-In the second example, however, we have stored another reference to
-the tied object in $x. That means that when untie() gets called
-there will still be a valid reference to the object in existence, so
-the destructor is not called at that time, and thus the file is not
-closed. The reason there is no output is because the file buffers
-have not been flushed to disk.
-
-Now that you know what the problem is, what can you do to avoid it?
-Prior to the introduction of the optional UNTIE method the only way
-was the good old C<-w> flag. Which will spot any instances where you call
-untie() and there are still valid references to the tied object. If
-the second script above this near the top C<use warnings 'untie'>
-or was run with the C<-w> flag, Perl prints this
-warning message:
-
- untie attempted while 1 inner references still exist
-
-To get the script to work properly and silence the warning make sure
-there are no valid references to the tied object I<before> untie() is
-called:
-
- undef $x;
- untie $fred;
-
-Now that UNTIE exists the class designer can decide which parts of the
-class functionality are really associated with C<untie> and which with
-the object being destroyed. What makes sense for a given class depends
-on whether the inner references are being kept so that non-tie-related
-methods can be called on the object. But in most cases it probably makes
-sense to move the functionality that would have been in DESTROY to the UNTIE
-method.
-
-If the UNTIE method exists then the warning above does not occur. Instead the
-UNTIE method is passed the count of "extra" references and can issue its own
-warning if appropriate. e.g. to replicate the no UNTIE case this method can
-be used:
-
- sub UNTIE
- {
- my ($obj,$count) = @_;
- carp "untie attempted while $count inner references still exist" if $count;
- }
-
-=head1 SEE ALSO
-
-See L<DB_File> or L<Config> for some interesting tie() implementations.
-A good starting point for many tie() implementations is with one of the
-modules L<Tie::Scalar>, L<Tie::Array>, L<Tie::Hash>, or L<Tie::Handle>.
-
-=head1 BUGS
-
-The bucket usage information provided by C<scalar(%hash)> is not
-available. What this means is that using %tied_hash in boolean
-context doesn't work right (currently this always tests false,
-regardless of whether the hash is empty or hash elements).
-
-Localizing tied arrays or hashes does not work. After exiting the
-scope the arrays or the hashes are not restored.
-
-Counting the number of entries in a hash via C<scalar(keys(%hash))>
-or C<scalar(values(%hash)>) is inefficient since it needs to iterate
-through all the entries with FIRSTKEY/NEXTKEY.
-
-Tied hash/array slices cause multiple FETCH/STORE pairs, there are no
-tie methods for slice operations.
-
-You cannot easily tie a multilevel data structure (such as a hash of
-hashes) to a dbm file. The first problem is that all but GDBM and
-Berkeley DB have size limitations, but beyond that, you also have problems
-with how references are to be represented on disk. One
-module that does attempt to address this need is DBM::Deep. Check your
-nearest CPAN site as described in L<perlmodlib> for source code. Note
-that despite its name, DBM::Deep does not use dbm. Another earlier attempt
-at solving the problem is MLDBM, which is also available on the CPAN, but
-which has some fairly serious limitations.
-
-Tied filehandles are still incomplete. sysopen(), truncate(),
-flock(), fcntl(), stat() and -X can't currently be trapped.
-
-=head1 AUTHOR
-
-Tom Christiansen
-
-TIEHANDLE by Sven Verdoolaege <F<skimo@dns.ufsia.ac.be>> and Doug MacEachern <F<dougm@osf.org>>
-
-UNTIE by Nick Ing-Simmons <F<nick@ing-simmons.net>>
-
-SCALAR by Tassilo von Parseval <F<tassilo.von.parseval@rwth-aachen.de>>
-
-Tying Arrays by Casey West <F<casey@geeknest.com>>
diff --git a/Master/tlpkg/tlperl/lib/pods/perltoc.pod b/Master/tlpkg/tlperl/lib/pods/perltoc.pod
deleted file mode 100644
index 35868311f54..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perltoc.pod
+++ /dev/null
@@ -1,37266 +0,0 @@
-
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is autogenerated by buildtoc from all the other pods.
-# Edit those files and run ..\pod\buildtoc to effect changes.
-
-=head1 NAME
-
-perltoc - perl documentation table of contents
-
-=head1 DESCRIPTION
-
-This page provides a brief table of contents for the rest of the Perl
-documentation set. It is meant to be scanned quickly or grepped
-through to locate the proper section you're looking for.
-
-=head1 BASIC DOCUMENTATION
-
-=head2 perl - The Perl 5 language interpreter
-
-=over 4
-
-=item SYNOPSIS
-
-=item GETTING HELP
-
-=over 4
-
-=item Overview
-
-=item Tutorials
-
-=item Reference Manual
-
-=item Internals and C Language Interface
-
-=item Miscellaneous
-
-=item Language-Specific
-
-=item Platform-Specific
-
-=item Stubs for Deleted Documents
-
-=back
-
-=item DESCRIPTION
-
-=item AVAILABILITY
-
-=item ENVIRONMENT
-
-=item AUTHOR
-
-=item FILES
-
-=item SEE ALSO
-
-=item DIAGNOSTICS
-
-=item BUGS
-
-=item NOTES
-
-=back
-
-=head2 perlintro -- a brief introduction and overview of Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item What is Perl?
-
-=item Running Perl programs
-
-=item Safety net
-
-=item Basic syntax overview
-
-=item Perl variable types
-
-Scalars, Arrays, Hashes
-
-=item Variable scoping
-
-=item Conditional and looping constructs
-
-if, while, for, foreach
-
-=item Builtin operators and functions
-
-Arithmetic, Numeric comparison, String comparison, Boolean logic,
-Miscellaneous
-
-=item Files and I/O
-
-=item Regular expressions
-
-Simple matching, Simple substitution, More complex regular expressions,
-Parentheses for capturing, Other regexp features
-
-=item Writing subroutines
-
-=item OO Perl
-
-=item Using Perl modules
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 perlreftut - Mark's very short tutorial about references
-
-=over 4
-
-=item DESCRIPTION
-
-=item Who Needs Complicated Data Structures?
-
-=item The Solution
-
-=item Syntax
-
-=over 4
-
-=item Making References
-
-=item Using References
-
-=item An Example
-
-=item Arrow Rule
-
-=back
-
-=item Solution
-
-=item The Rest
-
-=item Summary
-
-=item Credits
-
-=over 4
-
-=item Distribution Conditions
-
-=back
-
-=back
-
-=head2 perldsc - Perl Data Structures Cookbook
-
-=over 4
-
-=item DESCRIPTION
-
-arrays of arrays, hashes of arrays, arrays of hashes, hashes of hashes,
-more elaborate constructs
-
-=item REFERENCES
-X<reference> X<dereference> X<dereferencing> X<pointer>
-
-=item COMMON MISTAKES
-
-=item CAVEAT ON PRECEDENCE
-X<dereference, precedence> X<dereferencing, precedence>
-
-=item WHY YOU SHOULD ALWAYS C<use strict>
-
-=item DEBUGGING
-X<data structure, debugging> X<complex data structure, debugging>
-X<AoA, debugging> X<HoA, debugging> X<AoH, debugging> X<HoH, debugging>
-X<array of arrays, debugging> X<hash of arrays, debugging>
-X<array of hashes, debugging> X<hash of hashes, debugging>
-
-=item CODE EXAMPLES
-
-=item ARRAYS OF ARRAYS
-X<array of arrays> X<AoA>
-
-=over 4
-
-=item Declaration of an ARRAY OF ARRAYS
-
-=item Generation of an ARRAY OF ARRAYS
-
-=item Access and Printing of an ARRAY OF ARRAYS
-
-=back
-
-=item HASHES OF ARRAYS
-X<hash of arrays> X<HoA>
-
-=over 4
-
-=item Declaration of a HASH OF ARRAYS
-
-=item Generation of a HASH OF ARRAYS
-
-=item Access and Printing of a HASH OF ARRAYS
-
-=back
-
-=item ARRAYS OF HASHES
-X<array of hashes> X<AoH>
-
-=over 4
-
-=item Declaration of an ARRAY OF HASHES
-
-=item Generation of an ARRAY OF HASHES
-
-=item Access and Printing of an ARRAY OF HASHES
-
-=back
-
-=item HASHES OF HASHES
-X<hash of hashes> X<HoH>
-
-=over 4
-
-=item Declaration of a HASH OF HASHES
-
-=item Generation of a HASH OF HASHES
-
-=item Access and Printing of a HASH OF HASHES
-
-=back
-
-=item MORE ELABORATE RECORDS
-X<record> X<structure> X<struct>
-
-=over 4
-
-=item Declaration of MORE ELABORATE RECORDS
-
-=item Declaration of a HASH OF COMPLEX RECORDS
-
-=item Generation of a HASH OF COMPLEX RECORDS
-
-=back
-
-=item Database Ties
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 perllol - Manipulating Arrays of Arrays in Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Declaration and Access of Arrays of Arrays
-
-=item Growing Your Own
-
-=item Access and Printing
-
-=item Slices
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 perlrequick - Perl regular expressions quick start
-
-=over 4
-
-=item DESCRIPTION
-
-=item The Guide
-
-=over 4
-
-=item Simple word matching
-
-=item Using character classes
-
-=item Matching this or that
-
-=item Grouping things and hierarchical matching
-
-=item Extracting matches
-
-=item Matching repetitions
-
-=item More matching
-
-=item Search and replace
-
-=item The split operator
-
-=back
-
-=item BUGS
-
-=item SEE ALSO
-
-=item AUTHOR AND COPYRIGHT
-
-=over 4
-
-=item Acknowledgments
-
-=back
-
-=back
-
-=head2 perlretut - Perl regular expressions tutorial
-
-=over 4
-
-=item DESCRIPTION
-
-=item Part 1: The basics
-
-=over 4
-
-=item Simple word matching
-
-=item Using character classes
-
-=item Matching this or that
-
-=item Grouping things and hierarchical matching
-
-=item Extracting matches
-
-=item Backreferences
-
-=item Relative backreferences
-
-=item Named backreferences
-
-=item Alternative capture group numbering
-
-=item Position information
-
-=item Non-capturing groupings
-
-=item Matching repetitions
-
-=item Possessive quantifiers
-
-=item Building a regexp
-
-=item Using regular expressions in Perl
-
-=back
-
-=item Part 2: Power tools
-
-=over 4
-
-=item More on characters, strings, and character classes
-
-=item Compiling and saving regular expressions
-
-=item Composing regular expressions at runtime
-
-=item Embedding comments and modifiers in a regular expression
-
-=item Looking ahead and looking behind
-
-=item Using independent subexpressions to prevent backtracking
-
-=item Conditional expressions
-
-=item Defining named patterns
-
-=item Recursive patterns
-
-=item A bit of magic: executing Perl code in a regular expression
-
-=item Backtracking control verbs
-
-=item Pragmas and debugging
-
-=back
-
-=item BUGS
-
-=item SEE ALSO
-
-=item AUTHOR AND COPYRIGHT
-
-=over 4
-
-=item Acknowledgments
-
-=back
-
-=back
-
-=head2 perlootut - Object-Oriented Programming in Perl Tutorial
-
-=over 4
-
-=item DATE
-
-=item DESCRIPTION
-
-=item OBJECT-ORIENTED FUNDAMENTALS
-
-=over 4
-
-=item Object
-
-=item Class
-
-=item Methods
-
-=item Attributes
-
-=item Polymorphism
-
-=item Inheritance
-
-=item Encapsulation
-
-=item Composition
-
-=item Roles
-
-=item When to Use OO
-
-=back
-
-=item PERL OO SYSTEMS
-
-=over 4
-
-=item Moose
-
-Declarative sugar, Roles built-in, A miniature type system, Full
-introspection and manipulation, Self-hosted and extensible, Rich ecosystem,
-Many more features
-
-=item Class::Accessor
-
-=item Object::Tiny
-
-=item Role::Tiny
-
-=item OO System Summary
-
-L<Moose>, L<Class::Accessor>, L<Object::Tiny>, L<Role::Tiny>
-
-=item Other OO Systems
-
-=back
-
-=item CONCLUSION
-
-=back
-
-=head2 perlperf - Perl Performance and Optimization Techniques
-
-=over 4
-
-=item DESCRIPTION
-
-=item OVERVIEW
-
-=over 4
-
-=item ONE STEP SIDEWAYS
-
-=item ONE STEP FORWARD
-
-=item ANOTHER STEP SIDEWAYS
-
-=back
-
-=item GENERAL GUIDELINES
-
-=item BENCHMARKS
-
-=over 4
-
-=item Assigning and Dereferencing Variables.
-
-=item Search and replace or tr
-
-=back
-
-=item PROFILING TOOLS
-
-=over 4
-
-=item Devel::DProf
-
-=item Devel::Profiler
-
-=item Devel::SmallProf
-
-=item Devel::FastProf
-
-=item Devel::NYTProf
-
-=back
-
-=item SORTING
-
-Elapsed Real Time, User CPU Time, System CPU Time
-
-=item LOGGING
-
-=over 4
-
-=item Logging if DEBUG (constant)
-
-=back
-
-=item POSTSCRIPT
-
-=item SEE ALSO
-
-=over 4
-
-=item PERLDOCS
-
-=item MAN PAGES
-
-=item MODULES
-
-=item URLS
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 perlstyle - Perl style guide
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=head2 perlcheat - Perl 5 Cheat Sheet
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item The sheet
-
-=back
-
-=item ACKNOWLEDGEMENTS
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 perltrap - Perl traps for the unwary
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Awk Traps
-
-=item C/C++ Traps
-
-=item Sed Traps
-
-=item Shell Traps
-
-=item Perl Traps
-
-=item Perl4 to Perl5 Traps
-
-Discontinuance, Deprecation, and BugFix traps, Parsing Traps, Numerical
-Traps, General data type traps, Context Traps - scalar, list contexts,
-Precedence Traps, General Regular Expression Traps using s///, etc,
-Subroutine, Signal, Sorting Traps, OS Traps, DBM Traps, Unclassified Traps
-
-=item Discontinuance, Deprecation, and BugFix traps
-
-Symbols starting with "_" no longer forced into main, Double-colon valid
-package separator in variable name, 2nd and 3rd args to C<splice()> are now
-in scalar context, Can't do C<goto> into a block that is optimized away,
-Can't use whitespace as variable name or quote delimiter, C<while/if BLOCK
-BLOCK> gone, C<**> binds tighter than unary minus, C<foreach> changed when
-iterating over a list, C<split> with no args behavior changed, B<-e>
-behavior fixed, C<push> returns number of elements in resulting list, Some
-error messages differ, C<split()> honors subroutine args, Bugs removed
-
-=item Parsing Traps
-
-Space between . and = triggers syntax error, Better parsing in perl 5,
-Function parsing, String interpolation of C<$#array> differs, Perl guesses
-on C<map>, C<grep> followed by C<{> if it starts BLOCK or hash ref
-
-=item Numerical Traps
-
-Formatted output and significant digits, Auto-increment operator over
-signed int limit deleted, Assignment of return values from numeric equality
-tests doesn't work, Bitwise string ops
-
-=item General data type traps
-
-Negative array subscripts now count from the end of array, Setting
-C<$#array> lower now discards array elements, Hashes get defined before
-use, Glob assignment from localized variable to variable, Assigning
-C<undef> to glob, Changes in unary negation (of strings), Modifying of
-constants prohibited, C<defined $var> behavior changed, Variable Suicide
-
-=item Context Traps - scalar, list contexts
-
-Elements of argument lists for formats evaluated in list context,
-C<caller()> returns false value in scalar context if no caller present,
-Comma operator in scalar context gives scalar context to args, C<sprintf()>
-prototyped as C<($;@)>
-
-=item Precedence Traps
-
-LHS vs. RHS of any assignment operator, Semantic errors introduced due to
-precedence, Precedence of assignment operators same as the precedence of
-assignment, C<open> requires parentheses around filehandle, C<$:>
-precedence over C<$::> gone, Precedence of file test operators documented,
-C<keys>, C<each>, C<values> are regular named unary operators
-
-=item General Regular Expression Traps using s///, etc.
-
-C<s'$lhs'$rhs'> interpolates on either side, C<m//g> attaches its state to
-the searched string, C<m//o> used within an anonymous sub, C<$+> isn't set
-to whole match, Substitution now returns null string if it fails,
-C<s`lhs`rhs`> is now a normal substitution, Stricter parsing of variables
-in regular expressions, C<m?x?> matches only once, Failed matches don't
-reset the match variables
-
-=item Subroutine, Signal, Sorting Traps
-
-Barewords that used to look like strings look like subroutine calls,
-Reverse is no longer allowed as the name of a sort subroutine, C<warn()>
-won't let you specify a filehandle
-
-=item OS Traps
-
-SysV resets signal handler correctly, SysV C<seek()> appends correctly
-
-=item Interpolation Traps
-
-C<@> always interpolates an array in double-quotish strings, Double-quoted
-strings may no longer end with an unescaped $, Arbitrary expressions are
-evaluated inside braces within double quotes, C<$$x> now tries to
-dereference $x, Creation of hashes on the fly with C<eval "EXPR"> requires
-protection, Bugs in earlier perl versions, Array and hash brackets during
-interpolation, Interpolation of C<\$$foo{bar}>, C<qq()> string passed to
-C<eval> will not find string terminator
-
-=item DBM Traps
-
-Perl5 must have been linked with same dbm/ndbm as the default for
-C<dbmopen()>, DBM exceeding limit on the key/value size will cause perl5 to
-exit immediately
-
-=item Unclassified Traps
-
-C<require>/C<do> trap using returned value, C<split> on empty string with
-LIMIT specified
-
-=back
-
-=back
-
-=head2 perldebtut - Perl debugging tutorial
-
-=over 4
-
-=item DESCRIPTION
-
-=item use strict
-
-=item Looking at data and -w and v
-
-=item help
-
-=item Stepping through code
-
-=item Placeholder for a, w, t, T
-
-=item REGULAR EXPRESSIONS
-
-=item OUTPUT TIPS
-
-=item CGI
-
-=item GUIs
-
-=item SUMMARY
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item CONTRIBUTORS
-
-=back
-
-=head2 perlfaq - frequently asked questions about Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Where to find the perlfaq
-
-=item How to use the perlfaq
-
-=item How to contribute to the perlfaq
-
-=item What if my question isn't answered in the FAQ?
-
-=back
-
-=item TABLE OF CONTENTS
-
-perlfaq1 - General Questions About Perl, perlfaq2 - Obtaining and Learning
-about Perl, perlfaq3 - Programming Tools, perlfaq4 - Data Manipulation,
-perlfaq5 - Files and Formats, perlfaq6 - Regular Expressions, perlfaq7 -
-General Perl Language Issues, perlfaq8 - System Interaction, perlfaq9 -
-Web, Email and Networking
-
-=item THE QUESTIONS
-
-=over 4
-
-=item L<perlfaq1>: General Questions About Perl
-
-=item L<perlfaq2>: Obtaining and Learning about Perl
-
-=item L<perlfaq3>: Programming Tools
-
-=item L<perlfaq4>: Data Manipulation
-
-=item L<perlfaq5>: Files and Formats
-
-=item L<perlfaq6>: Regular Expressions
-
-=item L<perlfaq7>: General Perl Language Issues
-
-=item L<perlfaq8>: System Interaction
-
-=item L<perlfaq9>: Web, Email and Networking
-
-=back
-
-=item CREDITS
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq1 - General Questions About Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item What is Perl?
-
-=item Who supports Perl? Who develops it? Why is it free?
-
-=item Which version of Perl should I use?
-
-=item What are Perl 4, Perl 5, or Perl 6?
-
-=item What is Perl 6?
-
-=item How stable is Perl?
-
-=item Is Perl difficult to learn?
-
-=item How does Perl compare with other languages like Java, Python, REXX,
-Scheme, or Tcl?
-
-=item Can I do [task] in Perl?
-
-=item When shouldn't I program in Perl?
-
-=item What's the difference between "perl" and "Perl"?
-
-=item What is a JAPH?
-
-=item How can I convince others to use Perl?
-
-L<http://www.perl.org/about.html>,
-L<http://perltraining.com.au/whyperl.html>
-
-=back
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq2 - Obtaining and Learning about Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item What machines support Perl? Where do I get it?
-
-=item How can I get a binary version of Perl?
-
-=item I don't have a C compiler. How can I build my own Perl interpreter?
-
-=item I copied the Perl binary from one machine to another, but scripts
-don't work.
-
-=item I grabbed the sources and tried to compile but gdbm/dynamic
-loading/malloc/linking/... failed. How do I make it work?
-
-=item What modules and extensions are available for Perl? What is CPAN?
-
-=item Where can I get information on Perl?
-
-L<http://www.perl.org/>, L<http://perldoc.perl.org/>,
-L<http://learn.perl.org/>
-
-=item What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?
-
-L<http://www.perl.org/>, L<http://learn.perl.org/>,
-L<http://jobs.perl.org/>, L<http://lists.perl.org/>
-
-=item Where can I post questions?
-
-=item Perl Books
-
-=item Which magazines have Perl content?
-
-=item Which Perl blogs should I read?
-
-=item What mailing lists are there for Perl?
-
-=item Where can I buy a commercial version of Perl?
-
-=item Where do I send bug reports?
-
-=back
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq3 - Programming Tools
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item How do I do (anything)?
-
-Basics, L<perldata> - Perl data types, L<perlvar> - Perl pre-defined
-variables, L<perlsyn> - Perl syntax, L<perlop> - Perl operators and
-precedence, L<perlsub> - Perl subroutines, Execution, L<perlrun> - how to
-execute the Perl interpreter, L<perldebug> - Perl debugging, Functions,
-L<perlfunc> - Perl builtin functions, Objects, L<perlref> - Perl references
-and nested data structures, L<perlmod> - Perl modules (packages and symbol
-tables), L<perlobj> - Perl objects, L<perltie> - how to hide an object
-class in a simple variable, Data Structures, L<perlref> - Perl references
-and nested data structures, L<perllol> - Manipulating arrays of arrays in
-Perl, L<perldsc> - Perl Data Structures Cookbook, Modules, L<perlmod> -
-Perl modules (packages and symbol tables), L<perlmodlib> - constructing new
-Perl modules and finding existing ones, Regexes, L<perlre> - Perl regular
-expressions, L<perlfunc> - Perl builtin functions>, L<perlop> - Perl
-operators and precedence, L<perllocale> - Perl locale handling
-(internationalization and localization), Moving to perl5, L<perltrap> -
-Perl traps for the unwary, L<perl>, Linking with C, L<perlxstut> - Tutorial
-for writing XSUBs, L<perlxs> - XS language reference manual, L<perlcall> -
-Perl calling conventions from C, L<perlguts> - Introduction to the Perl
-API, L<perlembed> - how to embed perl in your C program, Various
-
-=item How can I use Perl interactively?
-
-=item How do I find which modules are installed on my system?
-
-=item How do I debug my Perl programs?
-
-=item How do I profile my Perl programs?
-
-=item How do I cross-reference my Perl programs?
-
-=item Is there a pretty-printer (formatter) for Perl?
-
-=item Is there an IDE or Windows Perl Editor?
-
-Eclipse, Enginsite, Komodo, Notepad++, Open Perl IDE, OptiPerl, Padre,
-PerlBuilder, visiPerl+, Visual Perl, Zeus, GNU Emacs, MicroEMACS, XEmacs,
-Jed, Vim, Vile, Codewright, MultiEdit, SlickEdit, ConTEXT, Bash, Ksh, Tcsh,
-Zsh, Affrus, Alpha, BBEdit and BBEdit Lite
-
-=item Where can I get Perl macros for vi?
-
-=item Where can I get perl-mode or cperl-mode for emacs?
-X<emacs>
-
-=item How can I use curses with Perl?
-
-=item How can I write a GUI (X, Tk, Gtk, etc.) in Perl?
-X<GUI> X<Tk> X<Wx> X<WxWidgets> X<Gtk> X<Gtk2> X<CamelBones> X<Qt>
-
-Tk, Wx, Gtk and Gtk2, Win32::GUI, CamelBones, Qt, Athena
-
-=item How can I make my Perl program run faster?
-
-=item How can I make my Perl program take less memory?
-
-Don't slurp!, Use map and grep selectively, Avoid unnecessary quotes and
-stringification, Pass by reference, Tie large variables to disk
-
-=item Is it safe to return a reference to local or lexical data?
-
-=item How can I free an array or hash so my program shrinks?
-
-=item How can I make my CGI script more efficient?
-
-=item How can I hide the source for my Perl program?
-
-=item How can I compile my Perl program into byte code or C?
-
-=item How can I get C<#!perl> to work on [MS-DOS,NT,...]?
-
-=item Can I write useful Perl programs on the command line?
-
-=item Why don't Perl one-liners work on my DOS/Mac/VMS system?
-
-=item Where can I learn about CGI or Web programming in Perl?
-
-=item Where can I learn about object-oriented Perl programming?
-
-=item Where can I learn about linking C with Perl?
-
-=item I've read perlembed, perlguts, etc., but I can't embed perl in my C
-program; what am I doing wrong?
-
-=item When I tried to run my script, I got this message. What does it mean?
-
-=item What's MakeMaker?
-
-=back
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq4 - Data Manipulation
-
-=over 4
-
-=item DESCRIPTION
-
-=item Data: Numbers
-
-=over 4
-
-=item Why am I getting long decimals (eg, 19.9499999999999) instead of the
-numbers I should be getting (eg, 19.95)?
-
-=item Why is int() broken?
-
-=item Why isn't my octal data interpreted correctly?
-
-=item Does Perl have a round() function? What about ceil() and floor()?
-Trig functions?
-
-=item How do I convert between numeric representations/bases/radixes?
-
-How do I convert hexadecimal into decimal, How do I convert from decimal to
-hexadecimal, How do I convert from octal to decimal, How do I convert from
-decimal to octal, How do I convert from binary to decimal, How do I convert
-from decimal to binary
-
-=item Why doesn't & work the way I want it to?
-
-=item How do I multiply matrices?
-
-=item How do I perform an operation on a series of integers?
-
-=item How can I output Roman numerals?
-
-=item Why aren't my random numbers random?
-
-=item How do I get a random number between X and Y?
-
-=back
-
-=item Data: Dates
-
-=over 4
-
-=item How do I find the day or week of the year?
-
-=item How do I find the current century or millennium?
-
-=item How can I compare two dates and find the difference?
-
-=item How can I take a string and turn it into epoch seconds?
-
-=item How can I find the Julian Day?
-
-=item How do I find yesterday's date?
-X<date> X<yesterday> X<DateTime> X<Date::Calc> X<Time::Local>
-X<daylight saving time> X<day> X<Today_and_Now> X<localtime>
-X<timelocal>
-
-=item Does Perl have a Year 2000 or 2038 problem? Is Perl Y2K compliant?
-
-=back
-
-=item Data: Strings
-
-=over 4
-
-=item How do I validate input?
-
-=item How do I unescape a string?
-
-=item How do I remove consecutive pairs of characters?
-
-=item How do I expand function calls in a string?
-
-=item How do I find matching/nesting anything?
-
-=item How do I reverse a string?
-
-=item How do I expand tabs in a string?
-
-=item How do I reformat a paragraph?
-
-=item How can I access or change N characters of a string?
-
-=item How do I change the Nth occurrence of something?
-
-=item How can I count the number of occurrences of a substring within a
-string?
-
-=item How do I capitalize all the words on one line?
-X<Text::Autoformat> X<capitalize> X<case, title> X<case, sentence>
-
-=item How can I split a [character]-delimited string except when inside
-[character]?
-
-=item How do I strip blank space from the beginning/end of a string?
-
-=item How do I pad a string with blanks or pad a number with zeroes?
-
-=item How do I extract selected columns from a string?
-
-=item How do I find the soundex value of a string?
-
-=item How can I expand variables in text strings?
-
-=item What's wrong with always quoting "$vars"?
-
-=item Why don't my E<lt>E<lt>HERE documents work?
-
-There must be no space after the E<lt>E<lt> part, There (probably) should
-be a semicolon at the end of the opening token, You can't (easily) have any
-space in front of the tag, There needs to be at least a line separator
-after the end token
-
-=back
-
-=item Data: Arrays
-
-=over 4
-
-=item What is the difference between a list and an array?
-
-=item What is the difference between $array[1] and @array[1]?
-
-=item How can I remove duplicate elements from a list or array?
-
-=item How can I tell whether a certain element is contained in a list or
-array?
-
-=item How do I compute the difference of two arrays? How do I compute the
-intersection of two arrays?
-
-=item How do I test whether two arrays or hashes are equal?
-
-=item How do I find the first array element for which a condition is true?
-
-=item How do I handle linked lists?
-
-=item How do I handle circular lists?
-X<circular> X<array> X<Tie::Cycle> X<Array::Iterator::Circular>
-X<cycle> X<modulus>
-
-=item How do I shuffle an array randomly?
-
-=item How do I process/modify each element of an array?
-
-=item How do I select a random element from an array?
-
-=item How do I permute N elements of a list?
-X<List::Permutor> X<permute> X<Algorithm::Loops> X<Knuth>
-X<The Art of Computer Programming> X<Fischer-Krause>
-
-=item How do I sort an array by (anything)?
-
-=item How do I manipulate arrays of bits?
-
-=item Why does defined() return true on empty arrays and hashes?
-
-=back
-
-=item Data: Hashes (Associative Arrays)
-
-=over 4
-
-=item How do I process an entire hash?
-
-=item How do I merge two hashes?
-X<hash> X<merge> X<slice, hash>
-
-=item What happens if I add or remove keys from a hash while iterating over
-it?
-
-=item How do I look up a hash element by value?
-
-=item How can I know how many entries are in a hash?
-
-=item How do I sort a hash (optionally by value instead of key)?
-
-=item How can I always keep my hash sorted?
-X<hash tie sort DB_File Tie::IxHash>
-
-=item What's the difference between "delete" and "undef" with hashes?
-
-=item Why don't my tied hashes make the defined/exists distinction?
-
-=item How do I reset an each() operation part-way through?
-
-=item How can I get the unique keys from two hashes?
-
-=item How can I store a multidimensional array in a DBM file?
-
-=item How can I make my hash remember the order I put elements into it?
-
-=item Why does passing a subroutine an undefined element in a hash create
-it?
-
-=item How can I make the Perl equivalent of a C structure/C++ class/hash or
-array of hashes or arrays?
-
-=item How can I use a reference as a hash key?
-
-=item How can I check if a key exists in a multilevel hash?
-
-=item How can I prevent addition of unwanted keys into a hash?
-
-=back
-
-=item Data: Misc
-
-=over 4
-
-=item How do I handle binary data correctly?
-
-=item How do I determine whether a scalar is a number/whole/integer/float?
-
-=item How do I keep persistent data across program calls?
-
-=item How do I print out or copy a recursive data structure?
-
-=item How do I define methods for every class/object?
-
-=item How do I verify a credit card checksum?
-
-=item How do I pack arrays of doubles or floats for XS code?
-
-=back
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq5 - Files and Formats
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item How do I flush/unbuffer an output filehandle? Why must I do this?
-X<flush> X<buffer> X<unbuffer> X<autoflush>
-
-=item How do I change, delete, or insert a line in a file, or append to the
-beginning of a file?
-X<file, editing>
-
-=item How do I count the number of lines in a file?
-X<file, counting lines> X<lines> X<line>
-
-=item How do I delete the last N lines from a file?
-X<lines> X<file>
-
-=item How can I use Perl's C<-i> option from within a program?
-X<-i> X<in-place>
-
-=item How can I copy a file?
-X<copy> X<file, copy> X<File::Copy>
-
-=item How do I make a temporary file name?
-X<file, temporary>
-
-=item How can I manipulate fixed-record-length files?
-X<fixed-length> X<file, fixed-length records>
-
-=item How can I make a filehandle local to a subroutine? How do I pass
-filehandles between subroutines? How do I make an array of filehandles?
-X<filehandle, local> X<filehandle, passing> X<filehandle, reference>
-
-=item How can I use a filehandle indirectly?
-X<filehandle, indirect>
-
-=item How can I set up a footer format to be used with write()?
-X<footer>
-
-=item How can I write() into a string?
-X<write, into a string>
-
-=item How can I open a filehandle to a string?
-X<string> X<open> X<IO::String> X<filehandle>
-
-=item How can I output my numbers with commas added?
-X<number, commify>
-
-=item How can I translate tildes (~) in a filename?
-X<tilde> X<tilde expansion>
-
-=item How come when I open a file read-write it wipes it out?
-X<clobber> X<read-write> X<clobbering> X<truncate> X<truncating>
-
-=item Why do I sometimes get an "Argument list too long" when I use
-E<lt>*E<gt>?
-X<argument list too long>
-
-=item How can I open a file with a leading ">" or trailing blanks?
-X<filename, special characters>
-
-=item How can I reliably rename a file?
-X<rename> X<mv> X<move> X<file, rename>
-
-=item How can I lock a file?
-X<lock> X<file, lock> X<flock>
-
-=item Why can't I just open(FH, "E<gt>file.lock")?
-X<lock, lockfile race condition>
-
-=item I still don't get locking. I just want to increment the number in the
-file. How can I do this?
-X<counter> X<file, counter>
-
-=item All I want to do is append a small amount of text to the end of a
-file. Do I still have to use locking?
-X<append> X<file, append>
-
-=item How do I randomly update a binary file?
-X<file, binary patch>
-
-=item How do I get a file's timestamp in perl?
-X<timestamp> X<file, timestamp>
-
-=item How do I set a file's timestamp in perl?
-X<timestamp> X<file, timestamp>
-
-=item How do I print to more than one file at once?
-X<print, to multiple files>
-
-=item How can I read in an entire file all at once?
-X<slurp> X<file, slurping>
-
-=item How can I read in a file by paragraphs?
-X<file, reading by paragraphs>
-
-=item How can I read a single character from a file? From the keyboard?
-X<getc> X<file, reading one character at a time>
-
-=item How can I tell whether there's a character waiting on a filehandle?
-
-=item How do I do a C<tail -f> in perl?
-X<tail> X<IO::Handle> X<File::Tail> X<clearerr>
-
-=item How do I dup() a filehandle in Perl?
-X<dup>
-
-=item How do I close a file descriptor by number?
-X<file, closing file descriptors> X<POSIX> X<close>
-
-=item Why can't I use "C:\temp\foo" in DOS paths? Why doesn't
-`C:\temp\foo.exe` work?
-X<filename, DOS issues>
-
-=item Why doesn't glob("*.*") get all the files?
-X<glob>
-
-=item Why does Perl let me delete read-only files? Why does C<-i> clobber
-protected files? Isn't this a bug in Perl?
-
-=item How do I select a random line from a file?
-X<file, selecting a random line>
-
-=item Why do I get weird spaces when I print an array of lines?
-
-=item How do I traverse a directory tree?
-
-=item How do I delete a directory tree?
-
-=item How do I copy an entire directory?
-
-=back
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq6 - Regular Expressions
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item How can I hope to use regular expressions without creating illegible
-and unmaintainable code?
-X<regex, legibility> X<regexp, legibility>
-X<regular expression, legibility> X</x>
-
-Comments Outside the Regex, Comments Inside the Regex, Different Delimiters
-
-=item I'm having trouble matching over more than one line. What's wrong?
-X<regex, multiline> X<regexp, multiline> X<regular expression, multiline>
-
-=item How can I pull out lines between two patterns that are themselves on
-different lines?
-X<..>
-
-=item How do I match XML, HTML, or other nasty, ugly things with a regex?
-X<regex, XML> X<regex, HTML> X<XML> X<HTML> X<pain> X<frustration>
-X<sucking out, will to live>
-
-=item I put a regular expression into $/ but it didn't work. What's wrong?
-X<$/, regexes in> X<$INPUT_RECORD_SEPARATOR, regexes in>
-X<$RS, regexes in>
-
-=item How do I substitute case-insensitively on the LHS while preserving
-case on the RHS?
-X<replace, case preserving> X<substitute, case preserving>
-X<substitution, case preserving> X<s, case preserving>
-
-=item How can I make C<\w> match national character sets?
-X<\w>
-
-=item How can I match a locale-smart version of C</[a-zA-Z]/>?
-X<alpha>
-
-=item How can I quote a variable to use in a regex?
-X<regex, escaping> X<regexp, escaping> X<regular expression, escaping>
-
-=item What is C</o> really for?
-X</o, regular expressions> X<compile, regular expressions>
-
-=item How do I use a regular expression to strip C-style comments from a
-file?
-
-=item Can I use Perl regular expressions to match balanced text?
-X<regex, matching balanced test> X<regexp, matching balanced test>
-X<regular expression, matching balanced test> X<possessive> X<PARNO>
-X<Text::Balanced> X<Regexp::Common> X<backtracking> X<recursion>
-
-=item What does it mean that regexes are greedy? How can I get around it?
-X<greedy> X<greediness>
-
-=item How do I process each word on each line?
-X<word>
-
-=item How can I print out a word-frequency or line-frequency summary?
-
-=item How can I do approximate matching?
-X<match, approximate> X<matching, approximate>
-
-=item How do I efficiently match many regular expressions at once?
-X<regex, efficiency> X<regexp, efficiency>
-X<regular expression, efficiency>
-
-=item Why don't word-boundary searches with C<\b> work for me?
-X<\b>
-
-=item Why does using $&, $`, or $' slow my program down?
-X<$MATCH> X<$&> X<$POSTMATCH> X<$'> X<$PREMATCH> X<$`>
-
-=item What good is C<\G> in a regular expression?
-X<\G>
-
-=item Are Perl regexes DFAs or NFAs? Are they POSIX compliant?
-X<DFA> X<NFA> X<POSIX>
-
-=item What's wrong with using grep in a void context?
-X<grep>
-
-=item How can I match strings with multibyte characters?
-X<regex, and multibyte characters> X<regexp, and multibyte characters>
-X<regular expression, and multibyte characters> X<martian> X<encoding,
-Martian>
-
-=item How do I match a regular expression that's in a variable?
-X<regex, in variable> X<eval> X<regex> X<quotemeta> X<\Q, regex>
-X<\E, regex> X<qr//>
-
-=back
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq7 - General Perl Language Issues
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Can I get a BNF/yacc/RE for the Perl language?
-
-=item What are all these $@%&* punctuation signs, and how do I know when to
-use them?
-
-=item Do I always/never have to quote my strings or use semicolons and
-commas?
-
-=item How do I skip some return values?
-
-=item How do I temporarily block warnings?
-
-=item What's an extension?
-
-=item Why do Perl operators have different precedence than C operators?
-
-=item How do I declare/create a structure?
-
-=item How do I create a module?
-
-=item How do I adopt or take over a module already on CPAN?
-
-=item How do I create a class?
-X<class, creation> X<package>
-
-=item How can I tell if a variable is tainted?
-
-=item What's a closure?
-
-=item What is variable suicide and how can I prevent it?
-
-=item How can I pass/return a {Function, FileHandle, Array, Hash, Method,
-Regex}?
-
-Passing Variables and Functions, Passing Filehandles, Passing Regexes,
-Passing Methods
-
-=item How do I create a static variable?
-
-=item What's the difference between dynamic and lexical (static) scoping?
-Between local() and my()?
-
-=item How can I access a dynamic variable while a similarly named lexical
-is in scope?
-
-=item What's the difference between deep and shallow binding?
-
-=item Why doesn't "my($foo) = E<lt>$fhE<gt>;" work right?
-
-=item How do I redefine a builtin function, operator, or method?
-
-=item What's the difference between calling a function as &foo and foo()?
-
-=item How do I create a switch or case statement?
-
-=item How can I catch accesses to undefined variables, functions, or
-methods?
-
-=item Why can't a method included in this same file be found?
-
-=item How can I find out my current or calling package?
-
-=item How can I comment out a large block of Perl code?
-
-=item How do I clear a package?
-
-=item How can I use a variable as a variable name?
-
-=item What does "bad interpreter" mean?
-
-=back
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq8 - System Interaction
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item How do I find out which operating system I'm running under?
-
-=item How come exec() doesn't return?
-X<exec> X<system> X<fork> X<open> X<pipe>
-
-=item How do I do fancy stuff with the keyboard/screen/mouse?
-
-Keyboard, Screen, Mouse
-
-=item How do I print something out in color?
-
-=item How do I read just one key without waiting for a return key?
-
-=item How do I check whether input is ready on the keyboard?
-
-=item How do I clear the screen?
-
-=item How do I get the screen size?
-
-=item How do I ask the user for a password?
-
-=item How do I read and write the serial port?
-
-lockfiles, open mode, end of line, flushing output, non-blocking input
-
-=item How do I decode encrypted password files?
-
-=item How do I start a process in the background?
-
-STDIN, STDOUT, and STDERR are shared, Signals, Zombies
-
-=item How do I trap control characters/signals?
-
-=item How do I modify the shadow password file on a Unix system?
-
-=item How do I set the time and date?
-
-=item How can I sleep() or alarm() for under a second?
-X<Time::HiRes> X<BSD::Itimer> X<sleep> X<select>
-
-=item How can I measure time under a second?
-X<Time::HiRes> X<BSD::Itimer> X<sleep> X<select>
-
-=item How can I do an atexit() or setjmp()/longjmp()? (Exception handling)
-
-=item Why doesn't my sockets program work under System V (Solaris)? What
-does the error message "Protocol not supported" mean?
-
-=item How can I call my system's unique C functions from Perl?
-
-=item Where do I get the include files to do ioctl() or syscall()?
-
-=item Why do setuid perl scripts complain about kernel problems?
-
-=item How can I open a pipe both to and from a command?
-
-=item Why can't I get the output of a command with system()?
-
-=item How can I capture STDERR from an external command?
-
-=item Why doesn't open() return an error when a pipe open fails?
-
-=item What's wrong with using backticks in a void context?
-
-=item How can I call backticks without shell processing?
-
-=item Why can't my script read from STDIN after I gave it EOF (^D on Unix,
-^Z on MS-DOS)?
-
-=item How can I convert my shell script to perl?
-
-=item Can I use perl to run a telnet or ftp session?
-
-=item How can I write expect in Perl?
-
-=item Is there a way to hide perl's command line from programs such as
-"ps"?
-
-=item I {changed directory, modified my environment} in a perl script. How
-come the change disappeared when I exited the script? How do I get my
-changes to be visible?
-
-Unix
-
-=item How do I close a process's filehandle without waiting for it to
-complete?
-
-=item How do I fork a daemon process?
-
-=item How do I find out if I'm running interactively or not?
-
-=item How do I timeout a slow event?
-
-=item How do I set CPU limits?
-X<BSD::Resource> X<limit> X<CPU>
-
-=item How do I avoid zombies on a Unix system?
-
-=item How do I use an SQL database?
-
-=item How do I make a system() exit on control-C?
-
-=item How do I open a file without blocking?
-
-=item How do I tell the difference between errors from the shell and perl?
-
-=item How do I install a module from CPAN?
-
-=item What's the difference between require and use?
-
-=item How do I keep my own module/library directory?
-
-=item How do I add the directory my program lives in to the module/library
-search path?
-
-=item How do I add a directory to my include path (@INC) at runtime?
-
-the C<PERLLIB> environment variable, the C<PERL5LIB> environment variable,
-the C<perl -Idir> command line flag, the C<lib> pragma:, the L<local::lib>
-module:
-
-=item What is socket.ph and where do I get it?
-
-=back
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq9 - Web, Email and Networking
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Should I use a web framework?
-
-=item Which web framework should I use?
-X<framework> X<CGI.pm> X<CGI> X<Catalyst> X<Dancer>
-
-L<Catalyst>, L<Dancer>, L<Mojolicious>, L<Web::Simple>
-
-=item What is Plack and PSGI?
-
-=item How do I remove HTML from a string?
-
-=item How do I extract URLs?
-
-=item How do I fetch an HTML file?
-
-=item How do I automate an HTML form submission?
-
-=item How do I decode or create those %-encodings on the web?
-X<URI> X<URI::Escape> X<RFC 2396>
-
-=item How do I redirect to another page?
-
-=item How do I put a password on my web pages?
-
-=item How do I make sure users can't enter values into a form that causes
-my CGI script to do bad things?
-
-=item How do I parse a mail header?
-
-=item How do I check a valid mail address?
-
-=item How do I decode a MIME/BASE64 string?
-
-=item How do I find the user's mail address?
-
-=item How do I send email?
-
-L<Email::Sender::Transport::Sendmail>, L<Email::Sender::Transport::SMTP>,
-L<Email::Sender::Transport::SMTP::TLS>
-
-=item How do I use MIME to make an attachment to a mail message?
-
-=item How do I read email?
-
-=item How do I find out my hostname, domainname, or IP address?
-X<hostname, domainname, IP address, host, domain, hostfqdn, inet_ntoa,
-gethostbyname, Socket, Net::Domain, Sys::Hostname>
-
-=item How do I fetch/put an (S)FTP file?
-
-=item How can I do RPC in Perl?
-
-=back
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlsyn - Perl syntax
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Declarations
-X<declaration> X<undef> X<undefined> X<uninitialized>
-
-=item Comments
-X<comment> X<#>
-
-=item Simple Statements
-X<statement> X<semicolon> X<expression> X<;>
-
-=item Truth and Falsehood
-X<truth> X<falsehood> X<true> X<false> X<!> X<not> X<negation> X<0>
-
-=item Statement Modifiers
-X<statement modifier> X<modifier> X<if> X<unless> X<while>
-X<until> X<when> X<foreach> X<for>
-
-=item Compound Statements
-X<statement, compound> X<block> X<bracket, curly> X<curly bracket> X<brace>
-X<{> X<}> X<if> X<unless> X<given> X<while> X<until> X<foreach> X<for>
-X<continue>
-
-=item Loop Control
-X<loop control> X<loop, control> X<next> X<last> X<redo> X<continue>
-
-=item For Loops
-X<for> X<foreach>
-
-=item Foreach Loops
-X<for> X<foreach>
-
-=item Basic BLOCKs
-X<block>
-
-=item Switch Statements
-
-=item Goto
-X<goto>
-
-=item The Ellipsis Statement
-X<...>
-X<... statement>
-X<ellipsis operator>
-X<elliptical statement>
-X<unimplemented statement>
-X<unimplemented operator>
-X<yada-yada>
-X<yada-yada operator>
-X<... operator>
-X<whatever operator>
-X<triple-dot operator>
-
-=item PODs: Embedded Documentation
-X<POD> X<documentation>
-
-=item Plain Old Comments (Not!)
-X<comment> X<line> X<#> X<preprocessor> X<eval>
-
-=item Experimental Details on given and when
-
-=back
-
-=back
-
-=head2 perldata - Perl data types
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Variable names
-X<variable, name> X<variable name> X<data type> X<type>
-
-=item Context
-X<context> X<scalar context> X<list context>
-
-=item Scalar values
-X<scalar> X<number> X<string> X<reference>
-
-=item Scalar value constructors
-X<scalar, literal> X<scalar, constant>
-
-=item List value constructors
-X<list>
-
-=item Subscripts
-
-=item Multi-dimensional array emulation
-
-=item Slices
-X<slice> X<array, slice> X<hash, slice>
-
-=item Typeglobs and Filehandles
-X<typeglob> X<filehandle> X<*>
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 perlop - Perl operators and precedence
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Operator Precedence and Associativity
-X<operator, precedence> X<precedence> X<associativity>
-
-=item Terms and List Operators (Leftward)
-X<list operator> X<operator, list> X<term>
-
-=item The Arrow Operator
-X<arrow> X<dereference> X<< -> >>
-
-=item Auto-increment and Auto-decrement
-X<increment> X<auto-increment> X<++> X<decrement> X<auto-decrement> X<-->
-
-=item Exponentiation
-X<**> X<exponentiation> X<power>
-
-=item Symbolic Unary Operators
-X<unary operator> X<operator, unary>
-
-=item Binding Operators
-X<binding> X<operator, binding> X<=~> X<!~>
-
-=item Multiplicative Operators
-X<operator, multiplicative>
-
-=item Additive Operators
-X<operator, additive>
-
-=item Shift Operators
-X<shift operator> X<operator, shift> X<<< << >>>
-X<<< >> >>> X<right shift> X<left shift> X<bitwise shift>
-X<shl> X<shr> X<shift, right> X<shift, left>
-
-=item Named Unary Operators
-X<operator, named unary>
-
-=item Relational Operators
-X<relational operator> X<operator, relational>
-
-=item Equality Operators
-X<equality> X<equal> X<equals> X<operator, equality>
-
-=item Smartmatch Operator
-
-1. Empty hashes or arrays match, 2. That is, each element smartmatches the
-element of the same index in the other array.[3], 3. If a circular
-reference is found, fall back to referential equality, 4. Either an actual
-number, or a string that looks like one
-
-=item Bitwise And
-X<operator, bitwise, and> X<bitwise and> X<&>
-
-=item Bitwise Or and Exclusive Or
-X<operator, bitwise, or> X<bitwise or> X<|> X<operator, bitwise, xor>
-X<bitwise xor> X<^>
-
-=item C-style Logical And
-X<&&> X<logical and> X<operator, logical, and>
-
-=item C-style Logical Or
-X<||> X<operator, logical, or>
-
-=item Logical Defined-Or
-X<//> X<operator, logical, defined-or>
-
-=item Range Operators
-X<operator, range> X<range> X<..> X<...>
-
-=item Conditional Operator
-X<operator, conditional> X<operator, ternary> X<ternary> X<?:>
-
-=item Assignment Operators
-X<assignment> X<operator, assignment> X<=> X<**=> X<+=> X<*=> X<&=>
-X<<< <<= >>> X<&&=> X<-=> X</=> X<|=> X<<< >>= >>> X<||=> X<//=> X<.=>
-X<%=> X<^=> X<x=>
-
-=item Comma Operator
-X<comma> X<operator, comma> X<,>
-
-=item List Operators (Rightward)
-X<operator, list, rightward> X<list operator>
-
-=item Logical Not
-X<operator, logical, not> X<not>
-
-=item Logical And
-X<operator, logical, and> X<and>
-
-=item Logical or and Exclusive Or
-X<operator, logical, or> X<operator, logical, xor>
-X<operator, logical, exclusive or>
-X<or> X<xor>
-
-=item C Operators Missing From Perl
-X<operator, missing from perl> X<&> X<*>
-X<typecasting> X<(TYPE)>
-
-unary &, unary *, (TYPE)
-
-=item Quote and Quote-like Operators
-X<operator, quote> X<operator, quote-like> X<q> X<qq> X<qx> X<qw> X<m>
-X<qr> X<s> X<tr> X<'> X<''> X<"> X<""> X<//> X<`> X<``> X<<< << >>>
-X<escape sequence> X<escape>
-
-[1], [2], [3], [4], [5], [6], [7], [8]
-
-=item Regexp Quote-Like Operators
-X<operator, regexp>
-
-qr/STRING/msixpodual X<qr> X</i> X</m> X</o> X</s> X</x> X</p>,
-m/PATTERN/msixpodualgc X<m> X<operator, match> X<regexp, options> X<regexp>
-X<regex, options> X<regex> X</m> X</s> X</i> X</x> X</p> X</o> X</g> X</c>,
-/PATTERN/msixpodualgc, The empty pattern //, Matching in list context, \G
-assertion, m?PATTERN?msixpodualgc X<?> X<operator, match-once>,
-?PATTERN?msixpodualgc, s/PATTERN/REPLACEMENT/msixpodualgcer X<substitute>
-X<substitution> X<replace> X<regexp, replace> X<regexp, substitute> X</m>
-X</s> X</i> X</x> X</p> X</o> X</g> X</c> X</e> X</r>
-
-=item Quote-Like Operators
-X<operator, quote-like>
-
-q/STRING/ X<q> X<quote, single> X<'> X<''>, 'STRING', qq/STRING/ X<qq>
-X<quote, double> X<"> X<"">, "STRING", qx/STRING/ X<qx> X<`> X<``>
-X<backtick>, `STRING`, qw/STRING/ X<qw> X<quote, list> X<quote, words>,
-tr/SEARCHLIST/REPLACEMENTLIST/cdsr X<tr> X<y> X<transliterate> X</c> X</d>
-X</s>, y/SEARCHLIST/REPLACEMENTLIST/cdsr, <<EOF X<here-doc> X<heredoc>
-X<here-document> X<<< << >>>, Double Quotes, Single Quotes, Backticks
-
-=item Gory details of parsing quoted constructs
-X<quote, gory details>
-
-Finding the end, Interpolation X<interpolation>, C<<<'EOF'>, C<m''>, the
-pattern of C<s'''>, C<''>, C<q//>, C<tr'''>, C<y'''>, the replacement of
-C<s'''>, C<tr///>, C<y///>, C<"">, C<``>, C<qq//>, C<qx//>, C<< <file*glob>
->>, C<<<"EOF">, the replacement of C<s///>, C<RE> in C<?RE?>, C</RE/>,
-C<m/RE/>, C<s/RE/foo/>,, parsing regular expressions X<regexp, parse>,
-Optimization of regular expressions X<regexp, optimization>
-
-=item I/O Operators
-X<operator, i/o> X<operator, io> X<io> X<while> X<filehandle>
-X<< <> >> X<@ARGV>
-
-=item Constant Folding
-X<constant folding> X<folding>
-
-=item No-ops
-X<no-op> X<nop>
-
-=item Bitwise String Operators
-X<operator, bitwise, string>
-
-=item Integer Arithmetic
-X<integer>
-
-=item Floating-point Arithmetic
-
-=item Bigger Numbers
-X<number, arbitrary precision>
-
-=back
-
-=back
-
-=head2 perlsub - Perl subroutines
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Private Variables via my()
-X<my> X<variable, lexical> X<lexical> X<lexical variable> X<scope, lexical>
-X<lexical scope> X<attributes, my>
-
-=item Persistent Private Variables
-X<state> X<state variable> X<static> X<variable, persistent> X<variable,
-static> X<closure>
-
-=item Temporary Values via local()
-X<local> X<scope, dynamic> X<dynamic scope> X<variable, local>
-X<variable, temporary>
-
-=item Lvalue subroutines
-X<lvalue> X<subroutine, lvalue>
-
-Lvalue subroutines are EXPERIMENTAL
-
-=item Passing Symbol Table Entries (typeglobs)
-X<typeglob> X<*>
-
-=item When to Still Use local()
-X<local> X<variable, local>
-
-=item Pass by Reference
-X<pass by reference> X<pass-by-reference> X<reference>
-
-=item Prototypes
-X<prototype> X<subroutine, prototype>
-
-=item Constant Functions
-X<constant>
-
-=item Overriding Built-in Functions
-X<built-in> X<override> X<CORE> X<CORE::GLOBAL>
-
-=item Autoloading
-X<autoloading> X<AUTOLOAD>
-
-=item Subroutine Attributes
-X<attribute> X<subroutine, attribute> X<attrs>
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 perlfunc - Perl builtin functions
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Perl Functions by Category
-X<function>
-
-Functions for SCALARs or strings X<scalar> X<string> X<character>, Regular
-expressions and pattern matching X<regular expression> X<regex> X<regexp>,
-Numeric functions X<numeric> X<number> X<trigonometric> X<trigonometry>,
-Functions for real @ARRAYs X<array>, Functions for list data X<list>,
-Functions for real %HASHes X<hash>, Input and output functions X<I/O>
-X<input> X<output> X<dbm>, Functions for fixed-length data or records,
-Functions for filehandles, files, or directories X<file> X<filehandle>
-X<directory> X<pipe> X<link> X<symlink>, Keywords related to the control
-flow of your Perl program X<control flow>, Keywords related to scoping,
-Miscellaneous functions, Functions for processes and process groups
-X<process> X<pid> X<process id>, Keywords related to Perl modules
-X<module>, Keywords related to classes and object-orientation X<object>
-X<class> X<package>, Low-level socket functions X<socket> X<sock>, System V
-interprocess communication functions X<IPC> X<System V> X<semaphore>
-X<shared memory> X<memory> X<message>, Fetching user and group info X<user>
-X<group> X<password> X<uid> X<gid> X<passwd> X</etc/passwd>, Fetching
-network info X<network> X<protocol> X<host> X<hostname> X<IP> X<address>
-X<service>, Time-related functions X<time> X<date>, Non-function keywords
-
-=item Portability
-X<portability> X<Unix> X<portable>
-
-=item Alphabetical Listing of Perl Functions
-
--I<X> FILEHANDLE
-X<-r>X<-w>X<-x>X<-o>X<-R>X<-W>X<-X>X<-O>X<-e>X<-z>X<-s>X<-f>X<-d>X<-l>X<-p>
-X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>, -I<X> EXPR,
--I<X> DIRHANDLE, -I<X>, abs VALUE X<abs> X<absolute>, abs, accept
-NEWSOCKET,GENERICSOCKET X<accept>, alarm SECONDS X<alarm> X<SIGALRM>
-X<timer>, alarm, atan2 Y,X X<atan2> X<arctangent> X<tan> X<tangent>, bind
-SOCKET,NAME X<bind>, binmode FILEHANDLE, LAYER X<binmode> X<binary> X<text>
-X<DOS> X<Windows>, binmode FILEHANDLE, bless REF,CLASSNAME X<bless>, bless
-REF, break, caller EXPR X<caller> X<call stack> X<stack> X<stack trace>,
-caller, chdir EXPR X<chdir> X<cd> X<directory, change>, chdir FILEHANDLE,
-chdir DIRHANDLE, chdir, chmod LIST X<chmod> X<permission> X<mode>, chomp
-VARIABLE X<chomp> X<INPUT_RECORD_SEPARATOR> X<$/> X<newline> X<eol>, chomp(
-LIST ), chomp, chop VARIABLE X<chop>, chop( LIST ), chop, chown LIST
-X<chown> X<owner> X<user> X<group>, chr NUMBER X<chr> X<character> X<ASCII>
-X<Unicode>, chr, chroot FILENAME X<chroot> X<root>, chroot, close
-FILEHANDLE X<close>, close, closedir DIRHANDLE X<closedir>, connect
-SOCKET,NAME X<connect>, continue BLOCK X<continue>, continue, cos EXPR
-X<cos> X<cosine> X<acos> X<arccosine>, cos, crypt PLAINTEXT,SALT X<crypt>
-X<digest> X<hash> X<salt> X<plaintext> X<password> X<decrypt>
-X<cryptography> X<passwd> X<encrypt>, dbmclose HASH X<dbmclose>, dbmopen
-HASH,DBNAME,MASK X<dbmopen> X<dbm> X<ndbm> X<sdbm> X<gdbm>, defined EXPR
-X<defined> X<undef> X<undefined>, defined, delete EXPR X<delete>, die LIST
-X<die> X<throw> X<exception> X<raise> X<$@> X<abort>, do BLOCK X<do>
-X<block>, do SUBROUTINE(LIST) X<do>, do EXPR X<do>, dump LABEL X<dump>
-X<core> X<undump>, dump, each HASH X<each> X<hash, iterator>, each ARRAY
-X<array, iterator>, each EXPR, eof FILEHANDLE X<eof> X<end of file>
-X<end-of-file>, eof (), eof, eval EXPR X<eval> X<try> X<catch> X<evaluate>
-X<parse> X<execute> X<error, handling> X<exception, handling>, eval BLOCK,
-eval, evalbytes EXPR X<evalbytes>, evalbytes, exec LIST X<exec> X<execute>,
-exec PROGRAM LIST, exists EXPR X<exists> X<autovivification>, exit EXPR
-X<exit> X<terminate> X<abort>, exit, exp EXPR X<exp> X<exponential>
-X<antilog> X<antilogarithm> X<e>, exp, fc EXPR X<fc> X<foldcase>
-X<casefold> X<fold-case> X<case-fold>, fc, fcntl FILEHANDLE,FUNCTION,SCALAR
-X<fcntl>, __FILE__ X<__FILE__>, fileno FILEHANDLE X<fileno>, flock
-FILEHANDLE,OPERATION X<flock> X<lock> X<locking>, fork X<fork> X<child>
-X<parent>, format X<format>, formline PICTURE,LIST X<formline>, getc
-FILEHANDLE X<getc> X<getchar> X<character> X<file, read>, getc, getlogin
-X<getlogin> X<login>, getpeername SOCKET X<getpeername> X<peer>, getpgrp
-PID X<getpgrp> X<group>, getppid X<getppid> X<parent> X<pid>, getpriority
-WHICH,WHO X<getpriority> X<priority> X<nice>, getpwnam NAME X<getpwnam>
-X<getgrnam> X<gethostbyname> X<getnetbyname> X<getprotobyname> X<getpwuid>
-X<getgrgid> X<getservbyname> X<gethostbyaddr> X<getnetbyaddr>
-X<getprotobynumber> X<getservbyport> X<getpwent> X<getgrent> X<gethostent>
-X<getnetent> X<getprotoent> X<getservent> X<setpwent> X<setgrent>
-X<sethostent> X<setnetent> X<setprotoent> X<setservent> X<endpwent>
-X<endgrent> X<endhostent> X<endnetent> X<endprotoent> X<endservent>,
-getgrnam NAME, gethostbyname NAME, getnetbyname NAME, getprotobyname NAME,
-getpwuid UID, getgrgid GID, getservbyname NAME,PROTO, gethostbyaddr
-ADDR,ADDRTYPE, getnetbyaddr ADDR,ADDRTYPE, getprotobynumber NUMBER,
-getservbyport PORT,PROTO, getpwent, getgrent, gethostent, getnetent,
-getprotoent, getservent, setpwent, setgrent, sethostent STAYOPEN, setnetent
-STAYOPEN, setprotoent STAYOPEN, setservent STAYOPEN, endpwent, endgrent,
-endhostent, endnetent, endprotoent, endservent, getsockname SOCKET
-X<getsockname>, getsockopt SOCKET,LEVEL,OPTNAME X<getsockopt>, glob EXPR
-X<glob> X<wildcard> X<filename, expansion> X<expand>, glob, gmtime EXPR
-X<gmtime> X<UTC> X<Greenwich>, gmtime, goto LABEL X<goto> X<jump> X<jmp>,
-goto EXPR, goto &NAME, grep BLOCK LIST X<grep>, grep EXPR,LIST, hex EXPR
-X<hex> X<hexadecimal>, hex, import LIST X<import>, index
-STR,SUBSTR,POSITION X<index> X<indexOf> X<InStr>, index STR,SUBSTR, int
-EXPR X<int> X<integer> X<truncate> X<trunc> X<floor>, int, ioctl
-FILEHANDLE,FUNCTION,SCALAR X<ioctl>, join EXPR,LIST X<join>, keys HASH
-X<keys> X<key>, keys ARRAY, keys EXPR, kill SIGNAL, LIST, kill SIGNAL
-X<kill> X<signal>, last LABEL X<last> X<break>, last, lc EXPR X<lc>
-X<lowercase>, lc, If C<use bytes> is in effect:, On EBCDIC platforms, On
-ASCII platforms, Otherwise, if C<use locale> (but not C<use locale
-':not_characters'>) is in effect:, Otherwise, If EXPR has the UTF8 flag
-set:, Otherwise, if C<use feature 'unicode_strings'> or C<use locale
-':not_characters'>) is in effect:, Otherwise:, On EBCDIC platforms, On
-ASCII platforms, lcfirst EXPR X<lcfirst> X<lowercase>, lcfirst, length EXPR
-X<length> X<size>, length, __LINE__ X<__LINE__>, link OLDFILE,NEWFILE
-X<link>, listen SOCKET,QUEUESIZE X<listen>, local EXPR X<local>, localtime
-EXPR X<localtime> X<ctime>, localtime, lock THING X<lock>, log EXPR X<log>
-X<logarithm> X<e> X<ln> X<base>, log, lstat FILEHANDLE X<lstat>, lstat
-EXPR, lstat DIRHANDLE, lstat, m//, map BLOCK LIST X<map>, map EXPR,LIST,
-mkdir FILENAME,MASK X<mkdir> X<md> X<directory, create>, mkdir FILENAME,
-mkdir, msgctl ID,CMD,ARG X<msgctl>, msgget KEY,FLAGS X<msgget>, msgrcv
-ID,VAR,SIZE,TYPE,FLAGS X<msgrcv>, msgsnd ID,MSG,FLAGS X<msgsnd>, my EXPR
-X<my>, my TYPE EXPR, my EXPR : ATTRS, my TYPE EXPR : ATTRS, next LABEL
-X<next> X<continue>, next, no MODULE VERSION LIST X<no declarations>
-X<unimporting>, no MODULE VERSION, no MODULE LIST, no MODULE, no VERSION,
-oct EXPR X<oct> X<octal> X<hex> X<hexadecimal> X<binary> X<bin>, oct, open
-FILEHANDLE,EXPR X<open> X<pipe> X<file, open> X<fopen>, open
-FILEHANDLE,MODE,EXPR, open FILEHANDLE,MODE,EXPR,LIST, open
-FILEHANDLE,MODE,REFERENCE, open FILEHANDLE, opendir DIRHANDLE,EXPR
-X<opendir>, ord EXPR X<ord> X<encoding>, ord, our EXPR X<our> X<global>,
-our TYPE EXPR, our EXPR : ATTRS, our TYPE EXPR : ATTRS, pack TEMPLATE,LIST
-X<pack>, package NAMESPACE, package NAMESPACE VERSION X<package> X<module>
-X<namespace> X<version>, package NAMESPACE BLOCK, package NAMESPACE VERSION
-BLOCK X<package> X<module> X<namespace> X<version>, __PACKAGE__
-X<__PACKAGE__>, pipe READHANDLE,WRITEHANDLE X<pipe>, pop ARRAY X<pop>
-X<stack>, pop EXPR, pop, pos SCALAR X<pos> X<match, position>, pos, print
-FILEHANDLE LIST X<print>, print FILEHANDLE, print LIST, print, printf
-FILEHANDLE FORMAT, LIST X<printf>, printf FILEHANDLE, printf FORMAT, LIST,
-printf, prototype FUNCTION X<prototype>, push ARRAY,LIST X<push> X<stack>,
-push EXPR,LIST, q/STRING/, qq/STRING/, qw/STRING/, qx/STRING/, qr/STRING/,
-quotemeta EXPR X<quotemeta> X<metacharacter>, quotemeta, rand EXPR X<rand>
-X<random>, rand, read FILEHANDLE,SCALAR,LENGTH,OFFSET X<read> X<file,
-read>, read FILEHANDLE,SCALAR,LENGTH, readdir DIRHANDLE X<readdir>,
-readline EXPR, readline X<readline> X<gets> X<fgets>, readlink EXPR
-X<readlink>, readlink, readpipe EXPR, readpipe X<readpipe>, recv
-SOCKET,SCALAR,LENGTH,FLAGS X<recv>, redo LABEL X<redo>, redo, ref EXPR
-X<ref> X<reference>, ref, rename OLDNAME,NEWNAME X<rename> X<move> X<mv>
-X<ren>, require VERSION X<require>, require EXPR, require, reset EXPR
-X<reset>, reset, return EXPR X<return>, return, reverse LIST X<reverse>
-X<rev> X<invert>, rewinddir DIRHANDLE X<rewinddir>, rindex
-STR,SUBSTR,POSITION X<rindex>, rindex STR,SUBSTR, rmdir FILENAME X<rmdir>
-X<rd> X<directory, remove>, rmdir, s///, say FILEHANDLE LIST X<say>, say
-FILEHANDLE, say LIST, say, scalar EXPR X<scalar> X<context>, seek
-FILEHANDLE,POSITION,WHENCE X<seek> X<fseek> X<filehandle, position>,
-seekdir DIRHANDLE,POS X<seekdir>, select FILEHANDLE X<select> X<filehandle,
-default>, select, select RBITS,WBITS,EBITS,TIMEOUT X<select>, semctl
-ID,SEMNUM,CMD,ARG X<semctl>, semget KEY,NSEMS,FLAGS X<semget>, semop
-KEY,OPSTRING X<semop>, send SOCKET,MSG,FLAGS,TO X<send>, send
-SOCKET,MSG,FLAGS, setpgrp PID,PGRP X<setpgrp> X<group>, setpriority
-WHICH,WHO,PRIORITY X<setpriority> X<priority> X<nice> X<renice>, setsockopt
-SOCKET,LEVEL,OPTNAME,OPTVAL X<setsockopt>, shift ARRAY X<shift>, shift
-EXPR, shift, shmctl ID,CMD,ARG X<shmctl>, shmget KEY,SIZE,FLAGS X<shmget>,
-shmread ID,VAR,POS,SIZE X<shmread> X<shmwrite>, shmwrite
-ID,STRING,POS,SIZE, shutdown SOCKET,HOW X<shutdown>, sin EXPR X<sin>
-X<sine> X<asin> X<arcsine>, sin, sleep EXPR X<sleep> X<pause>, sleep,
-socket SOCKET,DOMAIN,TYPE,PROTOCOL X<socket>, socketpair
-SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL X<socketpair>, sort SUBNAME LIST
-X<sort> X<qsort> X<quicksort> X<mergesort>, sort BLOCK LIST, sort LIST,
-splice ARRAY or EXPR,OFFSET,LENGTH,LIST X<splice>, splice ARRAY or
-EXPR,OFFSET,LENGTH, splice ARRAY or EXPR,OFFSET, splice ARRAY or EXPR,
-split /PATTERN/,EXPR,LIMIT X<split>, split /PATTERN/,EXPR, split /PATTERN/,
-split, sprintf FORMAT, LIST X<sprintf>, format parameter index, flags,
-vector flag, (minimum) width, precision, or maximum width X<precision>,
-size, order of arguments, sqrt EXPR X<sqrt> X<root> X<square root>, sqrt,
-srand EXPR X<srand> X<seed> X<randseed>, srand, stat FILEHANDLE X<stat>
-X<file, status> X<ctime>, stat EXPR, stat DIRHANDLE, stat, state EXPR
-X<state>, state TYPE EXPR, state EXPR : ATTRS, state TYPE EXPR : ATTRS,
-study SCALAR X<study>, study, sub NAME BLOCK X<sub>, sub NAME (PROTO)
-BLOCK, sub NAME : ATTRS BLOCK, sub NAME (PROTO) : ATTRS BLOCK, __SUB__
-X<__SUB__>, substr EXPR,OFFSET,LENGTH,REPLACEMENT X<substr> X<substring>
-X<mid> X<left> X<right>, substr EXPR,OFFSET,LENGTH, substr EXPR,OFFSET,
-symlink OLDFILE,NEWFILE X<symlink> X<link> X<symbolic link> X<link,
-symbolic>, syscall NUMBER, LIST X<syscall> X<system call>, sysopen
-FILEHANDLE,FILENAME,MODE X<sysopen>, sysopen
-FILEHANDLE,FILENAME,MODE,PERMS, sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
-X<sysread>, sysread FILEHANDLE,SCALAR,LENGTH, sysseek
-FILEHANDLE,POSITION,WHENCE X<sysseek> X<lseek>, system LIST X<system>
-X<shell>, system PROGRAM LIST, syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
-X<syswrite>, syswrite FILEHANDLE,SCALAR,LENGTH, syswrite FILEHANDLE,SCALAR,
-tell FILEHANDLE X<tell>, tell, telldir DIRHANDLE X<telldir>, tie
-VARIABLE,CLASSNAME,LIST X<tie>, tied VARIABLE X<tied>, time X<time>
-X<epoch>, times X<times>, tr///, truncate FILEHANDLE,LENGTH X<truncate>,
-truncate EXPR,LENGTH, uc EXPR X<uc> X<uppercase> X<toupper>, uc, ucfirst
-EXPR X<ucfirst> X<uppercase>, ucfirst, umask EXPR X<umask>, umask, undef
-EXPR X<undef> X<undefine>, undef, unlink LIST X<unlink> X<delete> X<remove>
-X<rm> X<del>, unlink, unpack TEMPLATE,EXPR X<unpack>, unpack TEMPLATE,
-unshift ARRAY,LIST X<unshift>, unshift EXPR,LIST, untie VARIABLE X<untie>,
-use Module VERSION LIST X<use> X<module> X<import>, use Module VERSION, use
-Module LIST, use Module, use VERSION, utime LIST X<utime>, values HASH
-X<values>, values ARRAY, values EXPR, vec EXPR,OFFSET,BITS X<vec> X<bit>
-X<bit vector>, wait X<wait>, waitpid PID,FLAGS X<waitpid>, wantarray
-X<wantarray> X<context>, warn LIST X<warn> X<warning> X<STDERR>, write
-FILEHANDLE X<write>, write EXPR, write, y///
-
-=item Non-function Keywords by Cross-reference
-
-__DATA__, __END__, BEGIN, CHECK, END, INIT, UNITCHECK, DESTROY, and, cmp,
-eq, ge, gt, if, le, lt, ne, not, or, x, xor, AUTOLOAD, else, elseif, elsif,
-for, foreach, unless, until, while, default, given, when
-
-=back
-
-=back
-
-=head2 perlopentut - tutorial on opening things in Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=item Open E<agrave> la shell
-
-=over 4
-
-=item Simple Opens
-
-=item Indirect Filehandles
-
-=item Pipe Opens
-
-=item The Minus File
-
-=item Mixing Reads and Writes
-
-=item Filters
-
-=back
-
-=item Open E<agrave> la C
-
-=over 4
-
-=item Permissions E<agrave> la mode
-
-=back
-
-=item Obscure Open Tricks
-
-=over 4
-
-=item Re-Opening Files (dups)
-
-=item Dispelling the Dweomer
-
-=item Paths as Opens
-
-=item Single Argument Open
-
-=item Playing with STDIN and STDOUT
-
-=back
-
-=item Other I/O Issues
-
-=over 4
-
-=item Opening Non-File Files
-
-=item Opening Named Pipes
-
-=item Opening Sockets
-
-=item Binary Files
-
-=item File Locking
-
-=item IO Layers
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR and COPYRIGHT
-
-=item HISTORY
-
-=back
-
-=head2 perlpacktut - tutorial on C<pack> and C<unpack>
-
-=over 4
-
-=item DESCRIPTION
-
-=item The Basic Principle
-
-=item Packing Text
-
-=item Packing Numbers
-
-=over 4
-
-=item Integers
-
-=item Unpacking a Stack Frame
-
-=item How to Eat an Egg on a Net
-
-=item Byte-order modifiers
-
-=item Floating point Numbers
-
-=back
-
-=item Exotic Templates
-
-=over 4
-
-=item Bit Strings
-
-=item Uuencoding
-
-=item Doing Sums
-
-=item Unicode
-
-=item Another Portable Binary Encoding
-
-=back
-
-=item Template Grouping
-
-=item Lengths and Widths
-
-=over 4
-
-=item String Lengths
-
-=item Dynamic Templates
-
-=item Counting Repetitions
-
-=item Intel HEX
-
-=back
-
-=item Packing and Unpacking C Structures
-
-=over 4
-
-=item The Alignment Pit
-
-=item Dealing with Endian-ness
-
-=item Alignment, Take 2
-
-=item Alignment, Take 3
-
-=item Pointers for How to Use Them
-
-=back
-
-=item Pack Recipes
-
-=item Funnies Section
-
-=item Authors
-
-=back
-
-=head2 perlpod - the Plain Old Documentation format
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Ordinary Paragraph
-X<POD, ordinary paragraph>
-
-=item Verbatim Paragraph
-X<POD, verbatim paragraph> X<verbatim>
-
-=item Command Paragraph
-X<POD, command>
-
-C<=head1 I<Heading Text>> X<=head1> X<=head2> X<=head3> X<=head4> X<head1>
-X<head2> X<head3> X<head4>, C<=head2 I<Heading Text>>, C<=head3 I<Heading
-Text>>, C<=head4 I<Heading Text>>, C<=over I<indentlevel>> X<=over>
-X<=item> X<=back> X<over> X<item> X<back>, C<=item I<stuff...>>, C<=back>,
-C<=cut> X<=cut> X<cut>, C<=pod> X<=pod> X<pod>, C<=begin I<formatname>>
-X<=begin> X<=end> X<=for> X<begin> X<end> X<for>, C<=end I<formatname>>,
-C<=for I<formatname> I<text...>>, C<=encoding I<encodingname>> X<=encoding>
-X<encoding>
-
-=item Formatting Codes
-X<POD, formatting code> X<formatting code>
-X<POD, interior sequence> X<interior sequence>
-
-C<IE<lt>textE<gt>> -- italic text X<I> X<< IZ<><> >> X<POD, formatting
-code, italic> X<italic>, C<BE<lt>textE<gt>> -- bold text X<B> X<< BZ<><> >>
-X<POD, formatting code, bold> X<bold>, C<CE<lt>codeE<gt>> -- code text X<C>
-X<< CZ<><> >> X<POD, formatting code, code> X<code>, C<LE<lt>nameE<gt>> --
-a hyperlink X<L> X<< LZ<><> >> X<POD, formatting code, hyperlink>
-X<hyperlink>, C<EE<lt>escapeE<gt>> -- a character escape X<E> X<< EZ<><> >>
-X<POD, formatting code, escape> X<escape>, C<FE<lt>filenameE<gt>> -- used
-for filenames X<F> X<< FZ<><> >> X<POD, formatting code, filename>
-X<filename>, C<SE<lt>textE<gt>> -- text contains non-breaking spaces X<S>
-X<< SZ<><> >> X<POD, formatting code, non-breaking space> X<non-breaking
-space>, C<XE<lt>topic nameE<gt>> -- an index entry X<X> X<< XZ<><> >>
-X<POD, formatting code, index entry> X<index entry>, C<ZE<lt>E<gt>> -- a
-null (zero-effect) formatting code X<Z> X<< ZZ<><> >> X<POD, formatting
-code, null> X<null>
-
-=item The Intent
-X<POD, intent of>
-
-=item Embedding Pods in Perl Modules
-X<POD, embedding>
-
-=item Hints for Writing Pod
-
-X<podchecker> X<POD, validating>
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 perlpodspec - Plain Old Documentation: format specification and
-notes
-
-=over 4
-
-=item DESCRIPTION
-
-=item Pod Definitions
-
-=item Pod Commands
-
-"=head1", "=head2", "=head3", "=head4", "=pod", "=cut", "=over", "=item",
-"=back", "=begin formatname", "=begin formatname parameter", "=end
-formatname", "=for formatname text...", "=encoding encodingname"
-
-=item Pod Formatting Codes
-
-C<IE<lt>textE<gt>> -- italic text, C<BE<lt>textE<gt>> -- bold text,
-C<CE<lt>codeE<gt>> -- code text, C<FE<lt>filenameE<gt>> -- style for
-filenames, C<XE<lt>topic nameE<gt>> -- an index entry, C<ZE<lt>E<gt>> -- a
-null (zero-effect) formatting code, C<LE<lt>nameE<gt>> -- a hyperlink,
-C<EE<lt>escapeE<gt>> -- a character escape, C<SE<lt>textE<gt>> -- text
-contains non-breaking spaces
-
-=item Notes on Implementing Pod Processors
-
-=item About LE<lt>...E<gt> Codes
-
-First:, Second:, Third:, Fourth:, Fifth:, Sixth:
-
-=item About =over...=back Regions
-
-=item About Data Paragraphs and "=begin/=end" Regions
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 perlpodstyle - Perl POD style guide
-
-=over 4
-
-=item DESCRIPTION
-
-bold (BE<lt>E<gt>), italic (IE<lt>E<gt>), code (CE<lt>E<gt>), files
-(FE<lt>E<gt>), NAME, SYNOPSIS, DESCRIPTION, OPTIONS, RETURN VALUE, ERRORS,
-DIAGNOSTICS, EXAMPLES, ENVIRONMENT, FILES, CAVEATS, BUGS, RESTRICTIONS,
-NOTES, AUTHOR, HISTORY, COPYRIGHT AND LICENSE, SEE ALSO
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 perlrun - how to execute the Perl interpreter
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item #! and quoting on non-Unix systems
-X<hashbang> X<#!>
-
-OS/2, MS-DOS, Win95/NT, VMS
-
-=item Location of Perl
-X<perl, location of interpreter>
-
-=item Command Switches
-X<perl, command switches> X<command switches>
-
-B<-0>[I<octal/hexadecimal>] X<-0> X<$/>, B<-a> X<-a> X<autosplit>, B<-C
-[I<number/list>]> X<-C>, B<-c> X<-c>, B<-d> X<-d> X<-dt>, B<-dt>,
-B<-d:>I<MOD[=bar,baz]> X<-d> X<-dt>, B<-dt:>I<MOD[=bar,baz]>,
-B<-D>I<letters> X<-D> X<DEBUGGING> X<-DDEBUGGING>, B<-D>I<number>, B<-e>
-I<commandline> X<-e>, B<-E> I<commandline> X<-E>, B<-f> X<-f>
-X<sitecustomize> X<sitecustomize.pl>, B<-F>I<pattern> X<-F>, B<-h> X<-h>,
-B<-i>[I<extension>] X<-i> X<in-place>, B<-I>I<directory> X<-I> X<@INC>,
-B<-l>[I<octnum>] X<-l> X<$/> X<$\>, B<-m>[B<->]I<module> X<-m> X<-M>,
-B<-M>[B<->]I<module>, B<-M>[B<->]I<'module ...'>,
-B<-[mM]>[B<->]I<module=arg[,arg]...>, B<-n> X<-n>, B<-p> X<-p>, B<-s>
-X<-s>, B<-S> X<-S>, B<-t> X<-t>, B<-T> X<-T>, B<-u> X<-u>, B<-U> X<-U>,
-B<-v> X<-v>, B<-V> X<-V>, B<-V:>I<configvar>, B<-w> X<-w>, B<-W> X<-W>,
-B<-X> X<-X>, B<-x> X<-x>, B<-x>I<directory>
-
-=back
-
-=item ENVIRONMENT
-X<perl, environment variables>
-
-HOME X<HOME>, LOGDIR X<LOGDIR>, PATH X<PATH>, PERL5LIB X<PERL5LIB>,
-PERL5OPT X<PERL5OPT>, PERLIO X<PERLIO>, :bytes X<:bytes>, :crlf X<:crlf>,
-:mmap X<:mmap>, :perlio X<:perlio>, :pop X<:pop>, :raw X<:raw>, :stdio
-X<:stdio>, :unix X<:unix>, :utf8 X<:utf8>, :win32 X<:win32>, PERLIO_DEBUG
-X<PERLIO_DEBUG>, PERLLIB X<PERLLIB>, PERL5DB X<PERL5DB>, PERL5DB_THREADED
-X<PERL5DB_THREADED>, PERL5SHELL (specific to the Win32 port) X<PERL5SHELL>,
-PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)
-X<PERL_ALLOW_NON_IFS_LSP>, PERL_DEBUG_MSTATS X<PERL_DEBUG_MSTATS>,
-PERL_DESTRUCT_LEVEL X<PERL_DESTRUCT_LEVEL>, PERL_DL_NONLAZY
-X<PERL_DL_NONLAZY>, PERL_ENCODING X<PERL_ENCODING>, PERL_HASH_SEED
-X<PERL_HASH_SEED>, PERL_HASH_SEED_DEBUG X<PERL_HASH_SEED_DEBUG>,
-PERL_MEM_LOG X<PERL_MEM_LOG>, PERL_ROOT (specific to the VMS port)
-X<PERL_ROOT>, PERL_SIGNALS X<PERL_SIGNALS>, PERL_UNICODE X<PERL_UNICODE>,
-SYS$LOGIN (specific to the VMS port) X<SYS$LOGIN>
-
-=back
-
-=head2 perldiag - various Perl diagnostics
-
-=over 4
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=back
-
-=head2 perllexwarn - Perl Lexical Warnings
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Default Warnings and Optional Warnings
-
-=item What's wrong with B<-w> and C<$^W>
-
-=item Controlling Warnings from the Command Line
-
-B<-w> X<-w>, B<-W> X<-W>, B<-X> X<-X>
-
-=item Backward Compatibility
-
-=item Category Hierarchy
-X<warning, categories>
-
-=item Fatal Warnings
-X<warning, fatal>
-
-=item Reporting Warnings from a Module
-X<warning, reporting> X<warning, registering>
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 perldebug - Perl debugging
-
-=over 4
-
-=item DESCRIPTION
-
-=item The Perl Debugger
-
-=over 4
-
-=item Calling the Debugger
-
-perl -d program_name, perl -d -e 0, perl -d:Ptkdb program_name, perl -dt
-threaded_program_name
-
-=item Debugger Commands
-
-h X<debugger command, h>, h [command], h h, p expr X<debugger command, p>,
-x [maxdepth] expr X<debugger command, x>, V [pkg [vars]] X<debugger
-command, V>, X [vars] X<debugger command, X>, y [level [vars]] X<debugger
-command, y>, T X<debugger command, T> X<backtrace> X<stack, backtrace>, s
-[expr] X<debugger command, s> X<step>, n [expr] X<debugger command, n>, r
-X<debugger command, r>, <CR>, c [line|sub] X<debugger command, c>, l
-X<debugger command, l>, l min+incr, l min-max, l line, l subname, -
-X<debugger command, ->, v [line] X<debugger command, v>, . X<debugger
-command, .>, f filename X<debugger command, f>, /pattern/, ?pattern?, L
-[abw] X<debugger command, L>, S [[!]regex] X<debugger command, S>, t [n]
-X<debugger command, t>, t [n] expr X<debugger command, t>, b X<breakpoint>
-X<debugger command, b>, b [line] [condition] X<breakpoint> X<debugger
-command, b>, b [file]:[line] [condition] X<breakpoint> X<debugger command,
-b>, b subname [condition] X<breakpoint> X<debugger command, b>, b postpone
-subname [condition] X<breakpoint> X<debugger command, b>, b load filename
-X<breakpoint> X<debugger command, b>, b compile subname X<breakpoint>
-X<debugger command, b>, B line X<breakpoint> X<debugger command, B>, B *
-X<breakpoint> X<debugger command, B>, disable [file]:[line] X<breakpoint>
-X<debugger command, disable> X<disable>, disable [line] X<breakpoint>
-X<debugger command, disable> X<disable>, enable [file]:[line] X<breakpoint>
-X<debugger command, disable> X<disable>, enable [line] X<breakpoint>
-X<debugger command, disable> X<disable>, a [line] command X<debugger
-command, a>, A line X<debugger command, A>, A * X<debugger command, A>, w
-expr X<debugger command, w>, W expr X<debugger command, W>, W * X<debugger
-command, W>, o X<debugger command, o>, o booloption ... X<debugger command,
-o>, o anyoption? ... X<debugger command, o>, o option=value ... X<debugger
-command, o>, < ? X<< debugger command, < >>, < [ command ] X<< debugger
-command, < >>, < * X<< debugger command, < >>, << command X<< debugger
-command, << >>, > ? X<< debugger command, > >>, > command X<< debugger
-command, > >>, > * X<< debugger command, > >>, >> command X<<< debugger
-command, >> >>>, { ? X<debugger command, {>, { [ command ], { * X<debugger
-command, {>, {{ command X<debugger command, {{>, ! number X<debugger
-command, !>, ! -number X<debugger command, !>, ! pattern X<debugger
-command, !>, !! cmd X<debugger command, !!>, source file X<debugger
-command, source>, H -number X<debugger command, H>, q or ^D X<debugger
-command, q> X<debugger command, ^D>, R X<debugger command, R>, |dbcmd
-X<debugger command, |>, ||dbcmd X<debugger command, ||>, command, m expr
-X<debugger command, m>, M X<debugger command, M>, man [manpage] X<debugger
-command, man>
-
-=item Configurable Options
-
-C<recallCommand>, C<ShellBang> X<debugger option, recallCommand> X<debugger
-option, ShellBang>, C<pager> X<debugger option, pager>, C<tkRunning>
-X<debugger option, tkRunning>, C<signalLevel>, C<warnLevel>, C<dieLevel>
-X<debugger option, signalLevel> X<debugger option, warnLevel> X<debugger
-option, dieLevel>, C<AutoTrace> X<debugger option, AutoTrace>, C<LineInfo>
-X<debugger option, LineInfo>, C<inhibit_exit> X<debugger option,
-inhibit_exit>, C<PrintRet> X<debugger option, PrintRet>, C<ornaments>
-X<debugger option, ornaments>, C<frame> X<debugger option, frame>,
-C<maxTraceLen> X<debugger option, maxTraceLen>, C<windowSize> X<debugger
-option, windowSize>, C<arrayDepth>, C<hashDepth> X<debugger option,
-arrayDepth> X<debugger option, hashDepth>, C<dumpDepth> X<debugger option,
-dumpDepth>, C<compactDump>, C<veryCompact> X<debugger option, compactDump>
-X<debugger option, veryCompact>, C<globPrint> X<debugger option,
-globPrint>, C<DumpDBFiles> X<debugger option, DumpDBFiles>, C<DumpPackages>
-X<debugger option, DumpPackages>, C<DumpReused> X<debugger option,
-DumpReused>, C<quote>, C<HighBit>, C<undefPrint> X<debugger option, quote>
-X<debugger option, HighBit> X<debugger option, undefPrint>, C<UsageOnly>
-X<debugger option, UsageOnly>, C<TTY> X<debugger option, TTY>, C<noTTY>
-X<debugger option, noTTY>, C<ReadLine> X<debugger option, ReadLine>,
-C<NonStop> X<debugger option, NonStop>
-
-=item Debugger Input/Output
-
-Prompt, Multiline commands, Stack backtrace X<backtrace> X<stack,
-backtrace>, Line Listing Format, Frame listing
-
-=item Debugging Compile-Time Statements
-
-=item Debugger Customization
-
-=item Readline Support / History in the Debugger
-
-=item Editor Support for Debugging
-
-=item The Perl Profiler
-X<profile> X<profiling> X<profiler>
-
-=back
-
-=item Debugging Regular Expressions
-X<regular expression, debugging>
-X<regex, debugging> X<regexp, debugging>
-
-=item Debugging Memory Usage
-X<memory usage>
-
-=item SEE ALSO
-
-=item BUGS
-
-=back
-
-=head2 perlvar - Perl predefined variables
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item The Syntax of Variable Names
-
-=back
-
-=item SPECIAL VARIABLES
-
-=over 4
-
-=item General Variables
-
-$ARG, $_ X<$_> X<$ARG>, @ARG, @_ X<@_> X<@ARG>, $LIST_SEPARATOR, $" X<$">
-X<$LIST_SEPARATOR>, $PROCESS_ID, $PID, $$ X<$$> X<$PID> X<$PROCESS_ID>,
-$PROGRAM_NAME, $0 X<$0> X<$PROGRAM_NAME>, $REAL_GROUP_ID, $GID, $( X<$(>
-X<$GID> X<$REAL_GROUP_ID>, $EFFECTIVE_GROUP_ID, $EGID, $) X<$)> X<$EGID>
-X<$EFFECTIVE_GROUP_ID>, $REAL_USER_ID, $UID, $< X<< $< >> X<$UID>
-X<$REAL_USER_ID>, $EFFECTIVE_USER_ID, $EUID, $> X<< $> >> X<$EUID>
-X<$EFFECTIVE_USER_ID>, $SUBSCRIPT_SEPARATOR, $SUBSEP, $; X<$;> X<$SUBSEP>
-X<SUBSCRIPT_SEPARATOR>, $a, $b X<$a> X<$b>, %ENV X<%ENV>, $SYSTEM_FD_MAX,
-$^F X<$^F> X<$SYSTEM_FD_MAX>, @F X<@F>, @INC X<@INC>, %INC X<%INC>,
-$INPLACE_EDIT, $^I X<$^I> X<$INPLACE_EDIT>, $^M X<$^M>, $OSNAME, $^O X<$^O>
-X<$OSNAME>, %SIG X<%SIG>, $BASETIME, $^T X<$^T> X<$BASETIME>,
-$PERL_VERSION, $^V X<$^V> X<$PERL_VERSION>, ${^WIN32_SLOPPY_STAT}
-X<${^WIN32_SLOPPY_STAT}> X<sitecustomize> X<sitecustomize.pl>,
-$EXECUTABLE_NAME, $^X X<$^X> X<$EXECUTABLE_NAME>
-
-=item Variables related to regular expressions
-
-$<I<digits>> ($1, $2, ...) X<$1> X<$2> X<$3>, $MATCH, $& X<$&> X<$MATCH>,
-${^MATCH} X<${^MATCH}>, $PREMATCH, $` X<$`> X<$PREMATCH> X<${^PREMATCH}>,
-${^PREMATCH} X<$`> X<${^PREMATCH}>, $POSTMATCH, $' X<$'> X<$POSTMATCH>
-X<${^POSTMATCH}> X<@->, ${^POSTMATCH} X<${^POSTMATCH}> X<$'> X<$POSTMATCH>,
-$LAST_PAREN_MATCH, $+ X<$+> X<$LAST_PAREN_MATCH>, $LAST_SUBMATCH_RESULT,
-$^N X<$^N> X<$LAST_SUBMATCH_RESULT>, @LAST_MATCH_END, @+ X<@+>
-X<@LAST_MATCH_END>, %LAST_PAREN_MATCH, %+ X<%+> X<%LAST_PAREN_MATCH>,
-@LAST_MATCH_START, @- X<@-> X<@LAST_MATCH_START>, C<$`> is the same as
-C<substr($var, 0, $-[0])>, C<$&> is the same as C<substr($var, $-[0], $+[0]
-- $-[0])>, C<$'> is the same as C<substr($var, $+[0])>, C<$1> is the same
-as C<substr($var, $-[1], $+[1] - $-[1])>, C<$2> is the same as
-C<substr($var, $-[2], $+[2] - $-[2])>, C<$3> is the same as C<substr($var,
-$-[3], $+[3] - $-[3])>, %LAST_MATCH_START, %- X<%-> X<%LAST_MATCH_START>,
-$LAST_REGEXP_CODE_RESULT, $^R X<$^R> X<$LAST_REGEXP_CODE_RESULT>,
-${^RE_DEBUG_FLAGS} X<${^RE_DEBUG_FLAGS}>, ${^RE_TRIE_MAXBUF}
-X<${^RE_TRIE_MAXBUF}>
-
-=item Variables related to filehandles
-
-$ARGV X<$ARGV>, @ARGV X<@ARGV>, ARGV X<ARGV>, ARGVOUT X<ARGVOUT>,
-Handle->output_field_separator( EXPR ), $OUTPUT_FIELD_SEPARATOR, $OFS, $,
-X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR>, HANDLE->input_line_number( EXPR
-), $INPUT_LINE_NUMBER, $NR, $. X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X<line
-number>, HANDLE->input_record_separator( EXPR ), $INPUT_RECORD_SEPARATOR,
-$RS, $/ X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR>,
-Handle->output_record_separator( EXPR ), $OUTPUT_RECORD_SEPARATOR, $ORS, $\
-X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR>, HANDLE->autoflush( EXPR ),
-$OUTPUT_AUTOFLUSH, $| X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH>,
-$ACCUMULATOR, $^A X<$^A> X<$ACCUMULATOR>, HANDLE->format_formfeed(EXPR),
-$FORMAT_FORMFEED, $^L X<$^L> X<$FORMAT_FORMFEED>,
-HANDLE->format_page_number(EXPR), $FORMAT_PAGE_NUMBER, $% X<$%>
-X<$FORMAT_PAGE_NUMBER>, HANDLE->format_lines_left(EXPR),
-$FORMAT_LINES_LEFT, $- X<$-> X<$FORMAT_LINES_LEFT>,
-Handle->format_line_break_characters EXPR, $FORMAT_LINE_BREAK_CHARACTERS,
-$: X<$:> X<FORMAT_LINE_BREAK_CHARACTERS>,
-HANDLE->format_lines_per_page(EXPR), $FORMAT_LINES_PER_PAGE, $= X<$=>
-X<$FORMAT_LINES_PER_PAGE>, HANDLE->format_top_name(EXPR), $FORMAT_TOP_NAME,
-$^ X<$^> X<$FORMAT_TOP_NAME>, HANDLE->format_name(EXPR), $FORMAT_NAME, $~
-X<$~> X<$FORMAT_NAME>
-
-=item Error Variables
-X<error> X<exception>
-
-${^CHILD_ERROR_NATIVE} X<$^CHILD_ERROR_NATIVE>, $EXTENDED_OS_ERROR, $^E
-X<$^E> X<$EXTENDED_OS_ERROR>, $EXCEPTIONS_BEING_CAUGHT, $^S X<$^S>
-X<$EXCEPTIONS_BEING_CAUGHT>, $WARNING, $^W X<$^W> X<$WARNING>,
-${^WARNING_BITS} X<${^WARNING_BITS}>, $OS_ERROR, $ERRNO, $! X<$!> X<$ERRNO>
-X<$OS_ERROR>, %OS_ERROR, %ERRNO, %! X<%!> X<%OS_ERROR> X<%ERRNO>,
-$CHILD_ERROR, $? X<$?> X<$CHILD_ERROR>, $EVAL_ERROR, $@ X<$@>
-X<$EVAL_ERROR>
-
-=item Variables related to the interpreter state
-
-$COMPILING, $^C X<$^C> X<$COMPILING>, $DEBUGGING, $^D X<$^D> X<$DEBUGGING>,
-${^ENCODING} X<${^ENCODING}>, ${^GLOBAL_PHASE} X<${^GLOBAL_PHASE}>,
-CONSTRUCT, START, CHECK, INIT, RUN, END, DESTRUCT, $^H X<$^H>, %^H X<%^H>,
-${^OPEN} X<${^OPEN}>, $PERLDB, $^P X<$^P> X<$PERLDB>, 0x01, 0x02, 0x04,
-0x08, 0x10, 0x20, 0x40, 0x80, 0x100, 0x200, 0x400, ${^TAINT} X<${^TAINT}>,
-${^UNICODE} X<${^UNICODE}>, ${^UTF8CACHE} X<${^UTF8CACHE}>, ${^UTF8LOCALE}
-X<${^UTF8LOCALE}>
-
-=item Deprecated and removed variables
-
-$OFMT, $# X<$#> X<$OFMT>, $* X<$*>, $ARRAY_BASE, $[ X<$[> X<$ARRAY_BASE>,
-$OLD_PERL_VERSION, $] X<$]> X<$OLD_PERL_VERSION>
-
-=back
-
-=back
-
-=head2 perlre - Perl regular expressions
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Modifiers
-
-m X</m> X<regex, multiline> X<regexp, multiline> X<regular expression,
-multiline>, s X</s> X<regex, single-line> X<regexp, single-line> X<regular
-expression, single-line>, i X</i> X<regex, case-insensitive> X<regexp,
-case-insensitive> X<regular expression, case-insensitive>, x X</x>, p X</p>
-X<regex, preserve> X<regexp, preserve>, g and c X</g> X</c>, a, d, l and u
-X</a> X</d> X</l> X</u>
-
-=item Regular Expressions
-
-[1], [2], [3], [4], [5], [6], [7]
-
-=item Quoting metacharacters
-
-=item Extended Patterns
-
-C<(?#text)> X<(?#)>, C<(?adlupimsx-imsx)>, C<(?^alupimsx)> X<(?)> X<(?^)>,
-C<(?:pattern)> X<(?:)>, C<(?adluimsx-imsx:pattern)>, C<(?^aluimsx:pattern)>
-X<(?^:)>, C<(?|pattern)> X<(?|)> X<Branch reset>, Look-Around Assertions
-X<look-around assertion> X<lookaround assertion> X<look-around>
-X<lookaround>, C<(?=pattern)> X<(?=)> X<look-ahead, positive> X<lookahead,
-positive>, C<(?!pattern)> X<(?!)> X<look-ahead, negative> X<lookahead,
-negative>, C<(?<=pattern)> C<\K> X<(?<=)> X<look-behind, positive>
-X<lookbehind, positive> X<\K>, C<(?<!pattern)> X<(?<!)> X<look-behind,
-negative> X<lookbehind, negative>, C<(?'NAME'pattern)>, C<<
-(?<NAME>pattern) >> X<< (?<NAME>) >> X<(?'NAME')> X<named capture>
-X<capture>, C<< \k<NAME> >>, C<< \k'NAME' >>, C<(?{ code })> X<(?{})>
-X<regex, code in> X<regexp, code in> X<regular expression, code in>, C<(??{
-code })> X<(??{})> X<regex, postponed> X<regexp, postponed> X<regular
-expression, postponed>, C<(?PARNO)> C<(?-PARNO)> C<(?+PARNO)> C<(?R)>
-C<(?0)> X<(?PARNO)> X<(?1)> X<(?R)> X<(?0)> X<(?-1)> X<(?+1)> X<(?-PARNO)>
-X<(?+PARNO)> X<regex, recursive> X<regexp, recursive> X<regular expression,
-recursive> X<regex, relative recursion>, C<(?&NAME)> X<(?&NAME)>,
-C<(?(condition)yes-pattern|no-pattern)> X<(?()>,
-C<(?(condition)yes-pattern)>, (1) (2) .., (<NAME>) ('NAME'), (?=...)
-(?!...) (?<=...) (?<!...), (?{ CODE }), (R), (R1) (R2) .., (R&NAME),
-(DEFINE), C<< (?>pattern) >> X<backtrack> X<backtracking> X<atomic>
-X<possessive>
-
-=item Special Backtracking Control Verbs
-
-Verbs that take an argument, C<(*PRUNE)> C<(*PRUNE:NAME)> X<(*PRUNE)>
-X<(*PRUNE:NAME)>, C<(*SKIP)> C<(*SKIP:NAME)> X<(*SKIP)>, C<(*MARK:NAME)>
-C<(*:NAME)> X<(*MARK)> X<(*MARK:NAME)> X<(*:NAME)>, C<(*THEN)>
-C<(*THEN:NAME)>, Verbs without an argument, C<(*COMMIT)> X<(*COMMIT)>,
-C<(*FAIL)> C<(*F)> X<(*FAIL)> X<(*F)>, C<(*ACCEPT)> X<(*ACCEPT)>
-
-=item Backtracking
-X<backtrack> X<backtracking>
-
-=item Version 8 Regular Expressions
-X<regular expression, version 8> X<regex, version 8> X<regexp, version 8>
-
-=item Warning on \1 Instead of $1
-
-=item Repeated Patterns Matching a Zero-length Substring
-
-=item Combining RE Pieces
-
-C<ST>, C<S|T>, C<S{REPEAT_COUNT}>, C<S{min,max}>, C<S{min,max}?>, C<S?>,
-C<S*>, C<S+>, C<S??>, C<S*?>, C<S+?>, C<< (?>S) >>, C<(?=S)>, C<(?<=S)>,
-C<(?!S)>, C<(?<!S)>, C<(??{ EXPR })>, C<(?PARNO)>,
-C<(?(condition)yes-pattern|no-pattern)>
-
-=item Creating Custom RE Engines
-
-=item PCRE/Python Support
-
-C<< (?PE<lt>NAMEE<gt>pattern) >>, C<< (?P=NAME) >>, C<< (?P>NAME) >>
-
-=back
-
-=item BUGS
-
-=item SEE ALSO
-
-=back
-
-=head2 perlrebackslash - Perl Regular Expression Backslash Sequences and
-Escapes
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item The backslash
-
-[1]
-
-=item All the sequences and escapes
-
-=item Character Escapes
-
-[1], [2]
-
-=item Modifiers
-
-=item Character classes
-
-=item Referencing
-
-=item Assertions
-
-\A, \z, \Z, \G, \b, \B
-
-=item Misc
-
-\C, \K, \N, \R X<\R>, \X X<\X>
-
-=back
-
-=back
-
-=head2 perlrecharclass - Perl Regular Expression Character Classes
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item The dot
-
-=item Backslash sequences
-X<\w> X<\W> X<\s> X<\S> X<\d> X<\D> X<\p> X<\P>
-X<\N> X<\v> X<\V> X<\h> X<\H>
-X<word> X<whitespace>
-
-If the C</a> modifier is in effect .., otherwise .., For code points above
-255 .., For code points below 256 .., if locale rules are in effect .., if
-Unicode rules are in effect or if on an EBCDIC platform .., otherwise ..,
-If the C</a> modifier is in effect .., otherwise .., For code points above
-255 .., For code points below 256 .., if locale rules are in effect .., if
-Unicode rules are in effect or if on an EBCDIC platform .., otherwise ..,
-[1]
-
-=item Bracketed Character Classes
-
-[1], [2], [3], [4], [5], [6], If the C</a> modifier, is in effect ..,
-otherwise .., For code points above 255 .., For code points below 256 ..,
-if locale rules are in effect .., if Unicode rules are in effect or if on
-an EBCDIC platform .., otherwise ..
-
-=back
-
-=back
-
-=head2 perlreref - Perl Regular Expressions Reference
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item OPERATORS
-
-=item SYNTAX
-
-=item ESCAPE SEQUENCES
-
-=item CHARACTER CLASSES
-
-=item ANCHORS
-
-=item QUANTIFIERS
-
-=item EXTENDED CONSTRUCTS
-
-=item VARIABLES
-
-=item FUNCTIONS
-
-=item TERMINOLOGY
-
-=back
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=item THANKS
-
-=back
-
-=head2 perlref - Perl references and nested data structures
-
-=over 4
-
-=item NOTE
-
-=item DESCRIPTION
-
-=over 4
-
-=item Making References
-X<reference, creation> X<referencing>
-
-1. X<\> X<backslash>, 2. X<array, anonymous> X<[> X<[]> X<square bracket>
-X<bracket, square> X<arrayref> X<array reference> X<reference, array>, 3.
-X<hash, anonymous> X<{> X<{}> X<curly bracket> X<bracket, curly> X<brace>
-X<hashref> X<hash reference> X<reference, hash>, 4. X<subroutine,
-anonymous> X<subroutine, reference> X<reference, subroutine> X<scope,
-lexical> X<closure> X<lexical> X<lexical scope>, 5. X<constructor> X<new>,
-6. X<autovivification>, 7. X<*foo{THING}> X<*>
-
-=item Using References
-X<reference, use> X<dereferencing> X<dereference>
-
-=item Circular References
-X<circular reference> X<reference, circular>
-
-=item Symbolic references
-X<reference, symbolic> X<reference, soft>
-X<symbolic reference> X<soft reference>
-
-=item Not-so-symbolic references
-
-=item Pseudo-hashes: Using an array as a hash
-X<pseudo-hash> X<pseudo hash> X<pseudohash>
-
-=item Function Templates
-X<scope, lexical> X<closure> X<lexical> X<lexical scope>
-X<subroutine, nested> X<sub, nested> X<subroutine, local> X<sub, local>
-
-=back
-
-=item WARNING
-X<reference, string context> X<reference, use as hash key>
-
-=item SEE ALSO
-
-=back
-
-=head2 perlform - Perl formats
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Text Fields
-X<format, text field>
-
-=item Numeric Fields
-X<#> X<format, numeric field>
-
-=item The Field @* for Variable-Width Multi-Line Text
-X<@*>
-
-=item The Field ^* for Variable-Width One-line-at-a-time Text
-X<^*>
-
-=item Specifying Values
-X<format, specifying values>
-
-=item Using Fill Mode
-X<format, fill mode>
-
-=item Suppressing Lines Where All Fields Are Void
-X<format, suppressing lines>
-
-=item Repeating Format Lines
-X<format, repeating lines>
-
-=item Top of Form Processing
-X<format, top of form> X<top> X<header>
-
-=item Format Variables
-X<format variables>
-X<format, variables>
-
-=back
-
-=item NOTES
-
-=over 4
-
-=item Footers
-X<format, footer> X<footer>
-
-=item Accessing Formatting Internals
-X<format, internals>
-
-=back
-
-=item WARNINGS
-
-=back
-
-=head2 perlobj - Perl object reference
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item An Object is Simply a Data Structure
-X<object> X<bless> X<constructor> X<new>
-
-=item A Class is Simply a Package
-X<class> X<package> X<@ISA> X<inheritance>
-
-=item A Method is Simply a Subroutine
-X<method>
-
-=item Method Invocation
-X<invocation> X<method> X<arrow> X<< -> >>
-
-=item Inheritance
-X<inheritance>
-
-=item Writing Constructors
-X<constructor>
-
-=item Attributes
-X<attribute>
-
-=item An Aside About Smarter and Safer Code
-
-=item Method Call Variations
-X<method>
-
-=item Invoking Class Methods
-X<invocation>
-
-=item C<bless>, C<blessed>, and C<ref>
-
-=item The UNIVERSAL Class
-X<UNIVERSAL>
-
-isa($class) X<isa>, DOES($role) X<DOES>, can($method) X<can>,
-VERSION($need) X<VERSION>
-
-=item AUTOLOAD
-X<AUTOLOAD>
-
-=item Destructors
-X<destructor> X<DESTROY>
-
-=item Non-Hash Objects
-
-=item Inside-Out objects
-
-=item Pseudo-hashes
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 perltie - how to hide an object class in a simple variable
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Tying Scalars
-X<scalar, tying>
-
-TIESCALAR classname, LIST X<TIESCALAR>, FETCH this X<FETCH>, STORE this,
-value X<STORE>, UNTIE this X<UNTIE>, DESTROY this X<DESTROY>
-
-=item Tying Arrays
-X<array, tying>
-
-TIEARRAY classname, LIST X<TIEARRAY>, FETCH this, index X<FETCH>, STORE
-this, index, value X<STORE>, FETCHSIZE this X<FETCHSIZE>, STORESIZE this,
-count X<STORESIZE>, EXTEND this, count X<EXTEND>, EXISTS this, key
-X<EXISTS>, DELETE this, key X<DELETE>, CLEAR this X<CLEAR>, PUSH this, LIST
- X<PUSH>, POP this X<POP>, SHIFT this X<SHIFT>, UNSHIFT this, LIST
-X<UNSHIFT>, SPLICE this, offset, length, LIST X<SPLICE>, UNTIE this
-X<UNTIE>, DESTROY this X<DESTROY>
-
-=item Tying Hashes
-X<hash, tying>
-
-USER, HOME, CLOBBER, LIST, TIEHASH classname, LIST X<TIEHASH>, FETCH this,
-key X<FETCH>, STORE this, key, value X<STORE>, DELETE this, key X<DELETE>,
-CLEAR this X<CLEAR>, EXISTS this, key X<EXISTS>, FIRSTKEY this X<FIRSTKEY>,
-NEXTKEY this, lastkey X<NEXTKEY>, SCALAR this X<SCALAR>, UNTIE this
-X<UNTIE>, DESTROY this X<DESTROY>
-
-=item Tying FileHandles
-X<filehandle, tying>
-
-TIEHANDLE classname, LIST X<TIEHANDLE>, WRITE this, LIST X<WRITE>, PRINT
-this, LIST X<PRINT>, PRINTF this, LIST X<PRINTF>, READ this, LIST X<READ>,
-READLINE this X<READLINE>, GETC this X<GETC>, EOF this X<EOF>, CLOSE this
-X<CLOSE>, UNTIE this X<UNTIE>, DESTROY this X<DESTROY>
-
-=item UNTIE this
-X<UNTIE>
-
-=item The C<untie> Gotcha
-X<untie>
-
-=back
-
-=item SEE ALSO
-
-=item BUGS
-
-=item AUTHOR
-
-=back
-
-=head2 perldbmfilter - Perl DBM Filters
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-B<filter_store_key>, B<filter_store_value>, B<filter_fetch_key>,
-B<filter_fetch_value>
-
-=over 4
-
-=item The Filter
-
-=item An Example: the NULL termination problem.
-
-=item Another Example: Key is a C int.
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 perlipc - Perl interprocess communication (signals, fifos, pipes,
-safe subprocesses, sockets, and semaphores)
-
-=over 4
-
-=item DESCRIPTION
-
-=item Signals
-
-=over 4
-
-=item Handling the SIGHUP Signal in Daemons
-
-=item Deferred Signals (Safe Signals)
-
-Long-running opcodes, Interrupting IO, Restartable system calls, Signals as
-"faults", Signals triggered by operating system state
-
-=back
-
-=item Named Pipes
-
-=item Using open() for IPC
-
-=over 4
-
-=item Filehandles
-
-=item Background Processes
-
-=item Complete Dissociation of Child from Parent
-
-=item Safe Pipe Opens
-
-=item Avoiding Pipe Deadlocks
-
-=item Bidirectional Communication with Another Process
-
-=item Bidirectional Communication with Yourself
-
-=back
-
-=item Sockets: Client/Server Communication
-
-=over 4
-
-=item Internet Line Terminators
-
-=item Internet TCP Clients and Servers
-
-=item Unix-Domain TCP Clients and Servers
-
-=back
-
-=item TCP Clients with IO::Socket
-
-=over 4
-
-=item A Simple Client
-
-C<Proto>, C<PeerAddr>, C<PeerPort>
-
-=item A Webget Client
-
-=item Interactive Client with IO::Socket
-
-=back
-
-=item TCP Servers with IO::Socket
-
-Proto, LocalPort, Listen, Reuse
-
-=item UDP: Message Passing
-
-=item SysV IPC
-
-=item NOTES
-
-=item BUGS
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 perlfork - Perl's fork() emulation
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Behavior of other Perl features in forked pseudo-processes
-
-$$ or $PROCESS_ID, %ENV, chdir() and all other builtins that accept
-filenames, wait() and waitpid(), kill(), exec(), exit(), Open handles to
-files, directories and network sockets
-
-=item Resource limits
-
-=item Killing the parent process
-
-=item Lifetime of the parent process and pseudo-processes
-
-=back
-
-=item CAVEATS AND LIMITATIONS
-
-BEGIN blocks, Open filehandles, Open directory handles, Forking pipe open()
-not yet implemented, Global state maintained by XSUBs, Interpreter embedded
-in larger application, Thread-safety of extensions
-
-=item PORTABILITY CAVEATS
-
-=item BUGS
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 perlnumber - semantics of numbers and numeric operations in Perl
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Storing numbers
-
-=item Numeric operators and numeric conversions
-
-=item Flavors of Perl numeric operations
-
-Arithmetic operators, ++, Arithmetic operators during C<use integer>, Other
-mathematical operators, Bitwise operators, Bitwise operators during C<use
-integer>, Operators which expect an integer, Operators which expect a
-string
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 perlthrtut - Tutorial on threads in Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=item What Is A Thread Anyway?
-
-=item Threaded Program Models
-
-=over 4
-
-=item Boss/Worker
-
-=item Work Crew
-
-=item Pipeline
-
-=back
-
-=item What kind of threads are Perl threads?
-
-=item Thread-Safe Modules
-
-=item Thread Basics
-
-=over 4
-
-=item Basic Thread Support
-
-=item A Note about the Examples
-
-=item Creating Threads
-
-=item Waiting For A Thread To Exit
-
-=item Ignoring A Thread
-
-=item Process and Thread Termination
-
-=back
-
-=item Threads And Data
-
-=over 4
-
-=item Shared And Unshared Data
-
-=item Thread Pitfalls: Races
-
-=back
-
-=item Synchronization and control
-
-=over 4
-
-=item Controlling access: lock()
-
-=item A Thread Pitfall: Deadlocks
-
-=item Queues: Passing Data Around
-
-=item Semaphores: Synchronizing Data Access
-
-=item Basic semaphores
-
-=item Advanced Semaphores
-
-=item Waiting for a Condition
-
-=item Giving up control
-
-=back
-
-=item General Thread Utility Routines
-
-=over 4
-
-=item What Thread Am I In?
-
-=item Thread IDs
-
-=item Are These Threads The Same?
-
-=item What Threads Are Running?
-
-=back
-
-=item A Complete Example
-
-=item Different implementations of threads
-
-=item Performance considerations
-
-=item Process-scope Changes
-
-=item Thread-Safety of System Libraries
-
-=item Conclusion
-
-=item SEE ALSO
-
-=item Bibliography
-
-=over 4
-
-=item Introductory Texts
-
-=item OS-Related References
-
-=item Other References
-
-=back
-
-=item Acknowledgements
-
-=item AUTHOR
-
-=item Copyrights
-
-=back
-
-=head2 perlport - Writing portable Perl
-
-=over 4
-
-=item DESCRIPTION
-
-Not all Perl programs have to be portable, Nearly all of Perl already I<is>
-portable
-
-=item ISSUES
-
-=over 4
-
-=item Newlines
-
-=item Numbers endianness and Width
-
-=item Files and Filesystems
-
-=item System Interaction
-
-=item Command names versus file pathnames
-
-=item Networking
-
-=item Interprocess Communication (IPC)
-
-=item External Subroutines (XS)
-
-=item Standard Modules
-
-=item Time and Date
-
-=item Character sets and character encoding
-
-=item Internationalisation
-
-=item System Resources
-
-=item Security
-
-=item Style
-
-=back
-
-=item CPAN Testers
-
-=item PLATFORMS
-
-=over 4
-
-=item Unix
-
-=item DOS and Derivatives
-
-=item VMS
-
-=item VOS
-
-=item EBCDIC Platforms
-
-=item Acorn RISC OS
-
-=item Other perls
-
-=back
-
-=item FUNCTION IMPLEMENTATIONS
-
-=over 4
-
-=item Alphabetical Listing of Perl Functions
-
--I<X>, alarm, atan2, binmode, chmod, chown, chroot, crypt, dbmclose,
-dbmopen, dump, exec, exit, fcntl, flock, fork, getlogin, getpgrp, getppid,
-getpriority, getpwnam, getgrnam, getnetbyname, getpwuid, getgrgid,
-getnetbyaddr, getprotobynumber, getservbyport, getpwent, getgrent,
-gethostbyname, gethostent, getnetent, getprotoent, getservent, sethostent,
-setnetent, setprotoent, setservent, endpwent, endgrent, endhostent,
-endnetent, endprotoent, endservent, getsockopt SOCKET,LEVEL,OPTNAME, glob,
-gmtime, ioctl FILEHANDLE,FUNCTION,SCALAR, kill, link, localtime, lstat,
-msgctl, msgget, msgsnd, msgrcv, open, readlink, rename, rewinddir, select,
-semctl, semget, semop, setgrent, setpgrp, setpriority, setpwent,
-setsockopt, shmctl, shmget, shmread, shmwrite, sockatmark, socketpair,
-stat, symlink, syscall, sysopen, system, times, truncate, umask, utime,
-wait, waitpid
-
-=back
-
-=item Supported Platforms
-
-Linux (x86, ARM, IA64), HP-UX, AIX, Win32, Windows 2000, Windows XP,
-Windows Server 2003, Windows Vista, Windows Server 2008, Windows 7, Cygwin,
-Solaris (x86, SPARC), OpenVMS, Alpha (7.2 and later), I64 (8.2 and later),
-Symbian, NetBSD, FreeBSD, Debian GNU/kFreeBSD, Haiku, Irix (6.5. What
-else?), OpenBSD, Dragonfly BSD, QNX Neutrino RTOS (6.5.0), MirOS BSD,
-time_t issues that may or may not be fixed, Symbian (Series 60 v3, 3.2 and
-5 - what else?), Stratus VOS / OpenVOS, AIX
-
-=item EOL Platforms (Perl 5.14)
-
-Atari MiNT, Apollo Domain/OS, Apple Mac OS 8/9, Tenon Machten, Windows 95,
-Windows 98, Windows ME, Windows NT4
-
-=item Supported Platforms (Perl 5.8)
-
-=item SEE ALSO
-
-=item AUTHORS / CONTRIBUTORS
-
-=back
-
-=head2 perllocale - Perl locale handling (internationalization and
-localization)
-
-=over 4
-
-=item DESCRIPTION
-
-=item WHAT IS A LOCALE
-
-Category LC_NUMERIC: Numeric formatting, Category LC_MONETARY: Formatting
-of monetary amounts, Category LC_TIME: Date/Time formatting, Category
-LC_MESSAGES: Error and other messages, Category LC_COLLATE: Collation,
-Category LC_CTYPE: Character Types
-
-=item PREPARING TO USE LOCALES
-
-=item USING LOCALES
-
-=over 4
-
-=item The use locale pragma
-
-B<Under C<use locale ':not_characters';>>, B<Under just plain C<use
-locale;>>
-
-=item The setlocale function
-
-=item Finding locales
-
-=item LOCALE PROBLEMS
-
-=item Temporarily fixing locale problems
-
-=item Permanently fixing locale problems
-
-=item Permanently fixing your system's locale configuration
-
-=item Fixing system locale configuration
-
-=item The localeconv function
-
-=item I18N::Langinfo
-
-=back
-
-=item LOCALE CATEGORIES
-
-=over 4
-
-=item Category LC_COLLATE: Collation
-
-=item Category LC_CTYPE: Character Types
-
-=item Category LC_NUMERIC: Numeric Formatting
-
-=item Category LC_MONETARY: Formatting of monetary amounts
-
-=item LC_TIME
-
-=item Other categories
-
-=back
-
-=item SECURITY
-
-=item ENVIRONMENT
-
-PERL_BADLANG, LC_ALL, LANGUAGE, LC_CTYPE, LC_COLLATE, LC_MONETARY,
-LC_NUMERIC, LC_TIME, LANG
-
-=over 4
-
-=item Examples
-
-=back
-
-=item NOTES
-
-=over 4
-
-=item Backward compatibility
-
-=item I18N:Collate obsolete
-
-=item Sort speed and memory use impacts
-
-=item write() and LC_NUMERIC
-
-=item Freely available locale definitions
-
-=item I18n and l10n
-
-=item An imperfect standard
-
-=back
-
-=item Unicode and UTF-8
-
-=item BUGS
-
-=over 4
-
-=item Broken systems
-
-=back
-
-=item SEE ALSO
-
-=item HISTORY
-
-=back
-
-=head2 perluniintro - Perl Unicode introduction
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Unicode
-
-=item Perl's Unicode Support
-
-=item Perl's Unicode Model
-
-=item Unicode and EBCDIC
-
-=item Creating Unicode
-
-=item Handling Unicode
-
-=item Legacy Encodings
-
-=item Unicode I/O
-
-=item Displaying Unicode As Text
-
-=item Special Cases
-
-=item Advanced Topics
-
-=item Miscellaneous
-
-=item Questions With Answers
-
-=item Hexadecimal Notation
-
-=item Further Resources
-
-=back
-
-=item UNICODE IN OLDER PERLS
-
-=item SEE ALSO
-
-=item ACKNOWLEDGMENTS
-
-=item AUTHOR, COPYRIGHT, AND LICENSE
-
-=back
-
-=head2 perlunicode - Unicode support in Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Important Caveats
-
-Safest if you "use feature 'unicode_strings'", Input and Output Layers,
-C<use utf8> still needed to enable UTF-8/UTF-EBCDIC in scripts, BOM-marked
-scripts and UTF-16 scripts autodetected, C<use encoding> needed to upgrade
-non-Latin-1 byte strings
-
-=item Byte and Character Semantics
-
-=item Effects of Character Semantics
-
-=item Unicode Character Properties
-
-B<C<\p{All}>>, B<C<\p{Alnum}>>, B<C<\p{Any}>>, B<C<\p{ASCII}>>,
-B<C<\p{Assigned}>>, B<C<\p{Blank}>>, B<C<\p{Decomposition_Type:
-Non_Canonical}>> (Short: C<\p{Dt=NonCanon}>), B<C<\p{Graph}>>,
-B<C<\p{HorizSpace}>>, B<C<\p{In=*}>>, B<C<\p{PerlSpace}>>,
-B<C<\p{PerlWord}>>, B<C<\p{Posix...}>>, B<C<\p{Present_In: *}>> (Short:
-C<\p{In=*}>), B<C<\p{Print}>>, B<C<\p{SpacePerl}>>, B<C<\p{Title}>> and
-B<C<\p{Titlecase}>>, B<C<\p{VertSpace}>>, B<C<\p{Word}>>,
-B<C<\p{XPosix...}>>
-
-=item User-Defined Character Properties
-
-=item User-Defined Case Mappings (for serious hackers only)
-
-=item Character Encodings for Input and Output
-
-=item Unicode Regular Expression Support Level
-
-=item Unicode Encodings
-
-=item Non-character code points
-
-=item Beyond Unicode code points
-
-=item Security Implications of Unicode
-
-=item Unicode in Perl on EBCDIC
-
-=item Locales
-
-=item When Unicode Does Not Happen
-
-=item The "Unicode Bug"
-
-=item Forcing Unicode in Perl (Or Unforcing Unicode in Perl)
-
-=item Using Unicode in XS
-
-=item Hacking Perl to work on earlier Unicode versions (for very serious
-hackers only)
-
-=back
-
-=item BUGS
-
-=over 4
-
-=item Interaction with Locales
-
-=item Problems with characters in the Latin-1 Supplement range
-
-=item Interaction with Extensions
-
-=item Speed
-
-=item Problems on EBCDIC platforms
-
-=item Porting code from perl-5.6.X
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 perlunifaq - Perl Unicode FAQ
-
-=over 4
-
-=item Q and A
-
-=over 4
-
-=item perlunitut isn't really a Unicode tutorial, is it?
-
-=item What character encodings does Perl support?
-
-=item Which version of perl should I use?
-
-=item What about binary data, like images?
-
-=item When should I decode or encode?
-
-=item What if I don't decode?
-
-=item What if I don't encode?
-
-=item Is there a way to automatically decode or encode?
-
-=item What if I don't know which encoding was used?
-
-=item Can I use Unicode in my Perl sources?
-
-=item Data::Dumper doesn't restore the UTF8 flag; is it broken?
-
-=item Why do regex character classes sometimes match only in the ASCII
-range?
-
-=item Why do some characters not uppercase or lowercase correctly?
-
-=item How can I determine if a string is a text string or a binary string?
-
-=item How do I convert from encoding FOO to encoding BAR?
-
-=item What are C<decode_utf8> and C<encode_utf8>?
-
-=item What is a "wide character"?
-
-=back
-
-=item INTERNALS
-
-=over 4
-
-=item What is "the UTF8 flag"?
-
-=item What about the C<use bytes> pragma?
-
-=item What about the C<use encoding> pragma?
-
-=item What is the difference between C<:encoding> and C<:utf8>?
-
-=item What's the difference between C<UTF-8> and C<utf8>?
-
-=item I lost track; what encoding is the internal format really?
-
-=back
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 perluniprops - Index of Unicode Version 6.1.0 character properties
-in Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=item Properties accessible through C<\p{}> and C<\P{}>
-
-Single form (C<\p{name}>) tighter rules:, white space adjacent to a
-non-word character, underscores separating digits in numbers, Compound form
-(C<\p{name=value}> or C<\p{name:value}>) tighter rules:, Stabilized,
-Deprecated, Obsolete, Z<>B<*> is a wild-card, B<(\d+)> in the info column
-gives the number of code points matched by this property, B<D> means this
-is deprecated, B<O> means this is obsolete, B<S> means this is stabilized,
-B<T> means tighter (stricter) name matching applies, B<X> means use of this
-form is discouraged, and may not be stable
-
-=over 4
-
-=item Legal C<\p{}> and C<\P{}> constructs that match no characters
-
-\p{Canonical_Combining_Class=Attached_Below_Left},
-\p{Grapheme_Cluster_Break=Prepend}, \p{Joining_Type=Left_Joining}
-
-=back
-
-=item Properties accessible through Unicode::UCD
-
-=item Properties accessible through other means
-
-=item Unicode character properties that are NOT accepted by Perl
-
-I<Expands_On_NFC> (XO_NFC), I<Expands_On_NFD> (XO_NFD), I<Expands_On_NFKC>
-(XO_NFKC), I<Expands_On_NFKD> (XO_NFKD), I<Grapheme_Link> (Gr_Link),
-I<Indic_Matra_Category> (InMC), I<Indic_Syllabic_Category> (InSC),
-I<Jamo_Short_Name> (JSN), I<Other_Alphabetic> (OAlpha),
-I<Other_Default_Ignorable_Code_Point> (ODI), I<Other_Grapheme_Extend>
-(OGr_Ext), I<Other_ID_Continue> (OIDC), I<Other_ID_Start> (OIDS),
-I<Other_Lowercase> (OLower), I<Other_Math> (OMath), I<Other_Uppercase>
-(OUpper), I<Script=Katakana_Or_Hiragana> (sc=Hrkt),
-I<Script_Extensions=Katakana_Or_Hiragana> (scx=Hrkt)
-
-=item Other information in the Unicode data base
-
-F<auxiliary/GraphemeBreakTest.html>, F<auxiliary/LineBreakTest.html>,
-F<auxiliary/SentenceBreakTest.html>, F<auxiliary/WordBreakTest.html>,
-F<auxiliary\LBTest.txt>, F<auxiliary\SBTest.txt>, F<auxiliary\WBTest.txt>,
-F<BidiTest.txt>, F<NormalizationTest.txt>, F<CJKRadicals.txt>,
-F<EmojiSources.txt>, F<Index.txt>, F<IndicMatraCategory.txt>,
-F<IndicSyllabicCategory.txt>, F<NamedSqProv.txt>, F<NamesList.txt>,
-F<NormalizationCorrections.txt>, F<Props.txt>, F<ReadMe.txt>,
-F<StandardizedVariants.txt>
-
-=item SEE ALSO
-
-=back
-
-=head2 perlunitut - Perl Unicode Tutorial
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Definitions
-
-=item Your new toolkit
-
-=item I/O flow (the actual 5 minute tutorial)
-
-=back
-
-=item SUMMARY
-
-=item Q and A (or FAQ)
-
-=item ACKNOWLEDGEMENTS
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 perlebcdic - Considerations for running Perl on EBCDIC platforms
-
-=over 4
-
-=item DESCRIPTION
-
-=item COMMON CHARACTER CODE SETS
-
-=over 4
-
-=item ASCII
-
-=item ISO 8859
-
-=item Latin 1 (ISO 8859-1)
-
-=item EBCDIC
-
-=item The 13 variant characters
-
-=item 0037
-
-=item 1047
-
-=item POSIX-BC
-
-=item Unicode code points versus EBCDIC code points
-
-=item Remaining Perl Unicode problems in EBCDIC
-
-=item Unicode and UTF
-
-=item Using Encode
-
-=back
-
-=item SINGLE OCTET TABLES
-
-recipe 0, recipe 1, recipe 2, recipe 3, recipe 4, recipe 5, recipe 6
-
-=item IDENTIFYING CHARACTER CODE SETS
-
-=item CONVERSIONS
-
-=over 4
-
-=item tr///
-
-=item iconv
-
-=item C RTL
-
-=back
-
-=item OPERATOR DIFFERENCES
-
-=item FUNCTION DIFFERENCES
-
-chr(), ord(), pack(), print(), printf(), sort(), sprintf(), unpack()
-
-=item REGULAR EXPRESSION DIFFERENCES
-
-=item SOCKETS
-
-=item SORTING
-
-=over 4
-
-=item Ignore ASCII vs. EBCDIC sort differences.
-
-=item MONO CASE then sort data.
-
-=item Convert, sort data, then re convert.
-
-=item Perform sorting on one type of platform only.
-
-=back
-
-=item TRANSFORMATION FORMATS
-
-=over 4
-
-=item URL decoding and encoding
-
-=item uu encoding and decoding
-
-=item Quoted-Printable encoding and decoding
-
-=item Caesarean ciphers
-
-=back
-
-=item Hashing order and checksums
-
-=item I18N AND L10N
-
-=item MULTI-OCTET CHARACTER SETS
-
-=item OS ISSUES
-
-=over 4
-
-=item OS/400
-
-PASE, IFS access
-
-=item OS/390, z/OS
-
-chcp, dataset access, OS/390, z/OS iconv, locales
-
-=item VM/ESA?
-
-=item POSIX-BC?
-
-=back
-
-=item BUGS
-
-=item SEE ALSO
-
-=item REFERENCES
-
-=item HISTORY
-
-=item AUTHOR
-
-=back
-
-=head2 perlsec - Perl security
-
-=over 4
-
-=item DESCRIPTION
-
-=item SECURITY VULNERABILITY CONTACT INFORMATION
-
-=item SECURITY MECHANISMS AND CONCERNS
-
-=over 4
-
-=item Taint mode
-
-=item Laundering and Detecting Tainted Data
-
-=item Switches On the "#!" Line
-
-=item Taint mode and @INC
-
-=item Cleaning Up Your Path
-
-=item Security Bugs
-
-=item Protecting Your Programs
-
-=item Unicode
-
-=item Algorithmic Complexity Attacks
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 perlmod - Perl modules (packages and symbol tables)
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Packages
-X<package> X<namespace> X<variable, global> X<global variable> X<global>
-
-=item Symbol Tables
-X<symbol table> X<stash> X<%::> X<%main::> X<typeglob> X<glob> X<alias>
-
-=item BEGIN, UNITCHECK, CHECK, INIT and END
-X<BEGIN> X<UNITCHECK> X<CHECK> X<INIT> X<END>
-
-=item Perl Classes
-X<class> X<@ISA>
-
-=item Perl Modules
-X<module>
-
-=item Making your module threadsafe
-X<threadsafe> X<thread safe>
-X<module, threadsafe> X<module, thread safe>
-X<CLONE> X<CLONE_SKIP> X<thread> X<threads> X<ithread>
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 perlmodlib - constructing new Perl modules and finding existing ones
-
-=over 4
-
-=item THE PERL MODULE LIBRARY
-
-=over 4
-
-=item Pragmatic Modules
-
-arybase, attributes, autodie, autodie::exception,
-autodie::exception::system, autodie::hints, autouse, base, bigint, bignum,
-bigrat, blib, bytes, charnames, constant, deprecate, diagnostics, encoding,
-encoding::warnings, feature, fields, filetest, if, inc::latest, integer,
-less, lib, locale, mro, open, ops, overload, overloading, parent, perldoc,
-perlfaq, perlfaq1, perlfaq2, perlfaq3, perlfaq4, perlfaq5, perlfaq6,
-perlfaq7, perlfaq8, perlfaq9, perlfunc, perlglossary, perlpodspeccopy,
-perlvarcopy, perlxs, perlxstut, perlxstypemap, re, sigtrap, sort, strict,
-subs, threads, threads::shared, utf8, vars, version, vmsish, warnings,
-warnings::register
-
-=item Standard Modules
-
-AnyDBM_File, App::Cpan, App::Prove, App::Prove::State,
-App::Prove::State::Result, App::Prove::State::Result::Test,
-Archive::Extract, Archive::Tar, Archive::Tar::File, Attribute::Handlers,
-AutoLoader, AutoSplit, B, B::Concise, B::Debug, B::Deparse, B::Lint,
-B::Lint::Debug, B::Showlex, B::Terse, B::Xref, Benchmark, C<Socket>, CGI,
-CGI::Apache, CGI::Carp, CGI::Cookie, CGI::Fast, CGI::Pretty, CGI::Push,
-CGI::Switch, CGI::Util, CORE, CPAN, CPAN::API::HOWTO, CPAN::Distroprefs,
-CPAN::FirstTime, CPAN::Kwalify, CPAN::Meta, CPAN::Meta::Converter,
-CPAN::Meta::Feature, CPAN::Meta::History, CPAN::Meta::Prereqs,
-CPAN::Meta::Requirements, CPAN::Meta::Spec, CPAN::Meta::Validator,
-CPAN::Meta::YAML, CPAN::Nox, CPAN::Version, CPANPLUS, CPANPLUS::Backend,
-CPANPLUS::Backend::RV, CPANPLUS::Config, CPANPLUS::Configure,
-CPANPLUS::Dist, CPANPLUS::Dist::Autobundle, CPANPLUS::Dist::Base,
-CPANPLUS::Dist::Build, CPANPLUS::Dist::Build::Constants,
-CPANPLUS::Dist::MM, CPANPLUS::Dist::Sample, CPANPLUS::Error, CPANPLUS::FAQ,
-CPANPLUS::Hacking, CPANPLUS::Internals, CPANPLUS::Internals::Extract,
-CPANPLUS::Internals::Fetch, CPANPLUS::Internals::Report,
-CPANPLUS::Internals::Search, CPANPLUS::Internals::Source,
-CPANPLUS::Internals::Source::Memory, CPANPLUS::Internals::Source::SQLite,
-CPANPLUS::Internals::Utils, CPANPLUS::Module, CPANPLUS::Module::Author,
-CPANPLUS::Module::Author::Fake, CPANPLUS::Module::Checksums,
-CPANPLUS::Module::Fake, CPANPLUS::Selfupdate, CPANPLUS::Shell,
-CPANPLUS::Shell::Classic, CPANPLUS::Shell::Default,
-CPANPLUS::Shell::Default::Plugins::CustomSource,
-CPANPLUS::Shell::Default::Plugins::HOWTO,
-CPANPLUS::Shell::Default::Plugins::Remote,
-CPANPLUS::Shell::Default::Plugins::Source, Carp, Class::Struct,
-Compress::Raw::Bzip2, Compress::Raw::Zlib, Compress::Zlib, Config, Cwd, DB,
-DBM_Filter, DBM_Filter::compress, DBM_Filter::encode, DBM_Filter::int32,
-DBM_Filter::null, DBM_Filter::utf8, DB_File, Data::Dumper,
-Devel::InnerPackage, Devel::PPPort, Devel::Peek, Devel::SelfStubber,
-Digest, Digest::MD5, Digest::SHA, Digest::base, Digest::file, DirHandle,
-Dumpvalue, DynaLoader, Encode, Encode::Alias, Encode::Byte,
-Encode::CJKConstants, Encode::CN, Encode::CN::HZ, Encode::Config,
-Encode::EBCDIC, Encode::Encoder, Encode::Encoding, Encode::GSM0338,
-Encode::Guess, Encode::JP, Encode::JP::H2Z, Encode::JP::JIS7, Encode::KR,
-Encode::KR::2022_KR, Encode::MIME::Header, Encode::MIME::Name,
-Encode::PerlIO, Encode::Supported, Encode::Symbol, Encode::TW,
-Encode::Unicode, Encode::Unicode::UTF7, English, Env, Errno, Exporter,
-Exporter::Heavy, ExtUtils::CBuilder, ExtUtils::CBuilder::Platform::Windows,
-ExtUtils::Command, ExtUtils::Command::MM, ExtUtils::Constant,
-ExtUtils::Constant::Base, ExtUtils::Constant::Utils,
-ExtUtils::Constant::XS, ExtUtils::Embed, ExtUtils::Install,
-ExtUtils::Installed, ExtUtils::Liblist, ExtUtils::MM, ExtUtils::MM_AIX,
-ExtUtils::MM_Any, ExtUtils::MM_BeOS, ExtUtils::MM_Cygwin, ExtUtils::MM_DOS,
-ExtUtils::MM_Darwin, ExtUtils::MM_MacOS, ExtUtils::MM_NW5,
-ExtUtils::MM_OS2, ExtUtils::MM_QNX, ExtUtils::MM_UWIN, ExtUtils::MM_Unix,
-ExtUtils::MM_VMS, ExtUtils::MM_VOS, ExtUtils::MM_Win32, ExtUtils::MM_Win95,
-ExtUtils::MY, ExtUtils::MakeMaker, ExtUtils::MakeMaker::Config,
-ExtUtils::MakeMaker::FAQ, ExtUtils::MakeMaker::Tutorial,
-ExtUtils::Manifest, ExtUtils::Mkbootstrap, ExtUtils::Mksymlists,
-ExtUtils::Packlist, ExtUtils::ParseXS, ExtUtils::ParseXS::Constants,
-ExtUtils::ParseXS::Utilities, ExtUtils::Typemaps, ExtUtils::Typemaps::Cmd,
-ExtUtils::Typemaps::InputMap, ExtUtils::Typemaps::OutputMap,
-ExtUtils::Typemaps::Type, ExtUtils::XSSymSet, ExtUtils::testlib, Fatal,
-Fcntl, File::Basename, File::CheckTree, File::Compare, File::Copy,
-File::DosGlob, File::Fetch, File::Find, File::Glob, File::GlobMapper,
-File::Path, File::Spec, File::Spec::Cygwin, File::Spec::Epoc,
-File::Spec::Functions, File::Spec::Mac, File::Spec::OS2, File::Spec::Unix,
-File::Spec::VMS, File::Spec::Win32, File::Temp, File::stat, FileCache,
-FileHandle, Filter::Simple, Filter::Util::Call, FindBin, GDBM_File,
-Getopt::Long, Getopt::Std, HTTP::Tiny, Hash::Util, Hash::Util::FieldHash,
-I18N::Collate, I18N::LangTags, I18N::LangTags::Detect,
-I18N::LangTags::List, I18N::Langinfo, IO, IO::Compress::Base,
-IO::Compress::Bzip2, IO::Compress::Deflate, IO::Compress::FAQ,
-IO::Compress::Gzip, IO::Compress::RawDeflate, IO::Compress::Zip, IO::Dir,
-IO::File, IO::Handle, IO::Pipe, IO::Poll, IO::Seekable, IO::Select,
-IO::Socket, IO::Socket::INET, IO::Socket::UNIX, IO::Uncompress::AnyInflate,
-IO::Uncompress::AnyUncompress, IO::Uncompress::Base,
-IO::Uncompress::Bunzip2, IO::Uncompress::Gunzip, IO::Uncompress::Inflate,
-IO::Uncompress::RawInflate, IO::Uncompress::Unzip, IO::Zlib, IPC::Cmd,
-IPC::Msg, IPC::Open2, IPC::Open3, IPC::Semaphore, IPC::SharedMem,
-IPC::SysV, JSON::PP, JSON::PP::Boolean, List::Util, List::Util::XS,
-Locale::Codes, Locale::Codes::API, Locale::Codes::Changes,
-Locale::Codes::Constants, Locale::Codes::Country,
-Locale::Codes::Country_Codes, Locale::Codes::Country_Retired,
-Locale::Codes::Currency, Locale::Codes::Currency_Codes,
-Locale::Codes::Currency_Retired, Locale::Codes::LangExt,
-Locale::Codes::LangExt_Codes, Locale::Codes::LangExt_Retired,
-Locale::Codes::LangFam, Locale::Codes::LangFam_Codes,
-Locale::Codes::LangFam_Retired, Locale::Codes::LangVar,
-Locale::Codes::LangVar_Codes, Locale::Codes::LangVar_Retired,
-Locale::Codes::Language, Locale::Codes::Language_Codes,
-Locale::Codes::Language_Retired, Locale::Codes::Script,
-Locale::Codes::Script_Codes, Locale::Codes::Script_Retired,
-Locale::Country, Locale::Currency, Locale::Language, Locale::Maketext,
-Locale::Maketext::Cookbook, Locale::Maketext::Guts,
-Locale::Maketext::GutsLoader, Locale::Maketext::Simple,
-Locale::Maketext::TPJ13, Locale::Script, Log::Message,
-Log::Message::Config, Log::Message::Handlers, Log::Message::Item,
-Log::Message::Simple, MIME::Base64, MIME::QuotedPrint, Math::BigFloat,
-Math::BigInt, Math::BigInt::Calc, Math::BigInt::CalcEmu,
-Math::BigInt::FastCalc, Math::BigRat, Math::Complex, Math::Trig, Memoize,
-Memoize::AnyDBM_File, Memoize::Expire, Memoize::ExpireFile,
-Memoize::ExpireTest, Memoize::NDBM_File, Memoize::SDBM_File,
-Memoize::Storable, Module::Build, Module::Build::API,
-Module::Build::Authoring, Module::Build::Base, Module::Build::Bundling,
-Module::Build::Compat, Module::Build::ConfigData, Module::Build::Cookbook,
-Module::Build::ModuleInfo, Module::Build::Notes, Module::Build::PPMMaker,
-Module::Build::Platform::Amiga, Module::Build::Platform::Default,
-Module::Build::Platform::EBCDIC, Module::Build::Platform::MPEiX,
-Module::Build::Platform::MacOS, Module::Build::Platform::RiscOS,
-Module::Build::Platform::Unix, Module::Build::Platform::VMS,
-Module::Build::Platform::VOS, Module::Build::Platform::Windows,
-Module::Build::Platform::aix, Module::Build::Platform::cygwin,
-Module::Build::Platform::darwin, Module::Build::Platform::os2,
-Module::Build::Version, Module::Build::YAML, Module::CoreList,
-Module::Load, Module::Load::Conditional, Module::Loaded, Module::Metadata,
-Module::Pluggable, Module::Pluggable::Object, NDBM_File, NEXT, Net::Cmd,
-Net::Config, Net::Domain, Net::FTP, Net::NNTP, Net::Netrc, Net::POP3,
-Net::Ping, Net::SMTP, Net::Time, Net::hostent, Net::libnetFAQ, Net::netent,
-Net::protoent, Net::servent, O, ODBM_File, Object::Accessor, Opcode, POSIX,
-Package::Constants, Params::Check, Parse::CPAN::Meta, Perl::OSType, PerlIO,
-PerlIO::encoding, PerlIO::mmap, PerlIO::scalar, PerlIO::via,
-PerlIO::via::QuotedPrint, Pod::Checker, Pod::Escapes, Pod::Find,
-Pod::Functions, Pod::Html, Pod::InputObjects, Pod::LaTeX, Pod::Man,
-Pod::ParseLink, Pod::ParseUtils, Pod::Parser, Pod::Perldoc,
-Pod::Perldoc::BaseTo, Pod::Perldoc::GetOptsOO, Pod::Perldoc::ToANSI,
-Pod::Perldoc::ToChecker, Pod::Perldoc::ToMan, Pod::Perldoc::ToNroff,
-Pod::Perldoc::ToPod, Pod::Perldoc::ToRtf, Pod::Perldoc::ToTerm,
-Pod::Perldoc::ToText, Pod::Perldoc::ToTk, Pod::Perldoc::ToXml,
-Pod::PlainText, Pod::Select, Pod::Simple, Pod::Simple::Checker,
-Pod::Simple::Debug, Pod::Simple::DumpAsText, Pod::Simple::DumpAsXML,
-Pod::Simple::HTML, Pod::Simple::HTMLBatch, Pod::Simple::LinkSection,
-Pod::Simple::Methody, Pod::Simple::PullParser,
-Pod::Simple::PullParserEndToken, Pod::Simple::PullParserStartToken,
-Pod::Simple::PullParserTextToken, Pod::Simple::PullParserToken,
-Pod::Simple::RTF, Pod::Simple::Search, Pod::Simple::SimpleTree,
-Pod::Simple::Subclassing, Pod::Simple::Text, Pod::Simple::TextContent,
-Pod::Simple::XHTML, Pod::Simple::XMLOutStream, Pod::Text, Pod::Text::Color,
-Pod::Text::Termcap, Pod::Usage, SDBM_File, Safe, Scalar::Util,
-Search::Dict, SelectSaver, SelfLoader, Storable, Symbol, Sys::Hostname,
-Sys::Syslog, Sys::Syslog::Win32, TAP::Base, TAP::Formatter::Base,
-TAP::Formatter::Color, TAP::Formatter::Console,
-TAP::Formatter::Console::ParallelSession, TAP::Formatter::Console::Session,
-TAP::Formatter::File, TAP::Formatter::File::Session,
-TAP::Formatter::Session, TAP::Harness, TAP::Object, TAP::Parser,
-TAP::Parser::Aggregator, TAP::Parser::Grammar, TAP::Parser::Iterator,
-TAP::Parser::Iterator::Array, TAP::Parser::Iterator::Process,
-TAP::Parser::Iterator::Stream, TAP::Parser::IteratorFactory,
-TAP::Parser::Multiplexer, TAP::Parser::Result,
-TAP::Parser::Result::Bailout, TAP::Parser::Result::Comment,
-TAP::Parser::Result::Plan, TAP::Parser::Result::Pragma,
-TAP::Parser::Result::Test, TAP::Parser::Result::Unknown,
-TAP::Parser::Result::Version, TAP::Parser::Result::YAML,
-TAP::Parser::ResultFactory, TAP::Parser::Scheduler,
-TAP::Parser::Scheduler::Job, TAP::Parser::Scheduler::Spinner,
-TAP::Parser::Source, TAP::Parser::SourceHandler,
-TAP::Parser::SourceHandler::Executable, TAP::Parser::SourceHandler::File,
-TAP::Parser::SourceHandler::Handle, TAP::Parser::SourceHandler::Perl,
-TAP::Parser::SourceHandler::RawTAP, TAP::Parser::Utils,
-TAP::Parser::YAMLish::Reader, TAP::Parser::YAMLish::Writer,
-Term::ANSIColor, Term::Cap, Term::Complete, Term::ReadLine, Term::UI,
-Term::UI::History, Test, Test::Builder, Test::Builder::Module,
-Test::Builder::Tester, Test::Builder::Tester::Color, Test::Harness,
-Test::More, Test::Simple, Test::Tutorial, Text::Abbrev, Text::Balanced,
-Text::ParseWords, Text::Soundex, Text::Tabs, Text::Wrap, Thread,
-Thread::Queue, Thread::Semaphore, Tie::Array, Tie::File, Tie::Handle,
-Tie::Hash, Tie::Hash::NamedCapture, Tie::Memoize, Tie::RefHash,
-Tie::Scalar, Tie::StdHandle, Tie::SubstrHash, Time::HiRes, Time::Local,
-Time::Piece, Time::Seconds, Time::gmtime, Time::localtime, Time::tm,
-UNIVERSAL, Unicode::Collate, Unicode::Collate::CJK::Big5,
-Unicode::Collate::CJK::GB2312, Unicode::Collate::CJK::JISX0208,
-Unicode::Collate::CJK::Korean, Unicode::Collate::CJK::Pinyin,
-Unicode::Collate::CJK::Stroke, Unicode::Collate::Locale,
-Unicode::Normalize, Unicode::UCD, User::grent, User::pwent, VMS::DCLsym,
-VMS::Stdio, Version::Requirements, Win32, Win32API::File, Win32CORE,
-XS::APItest, XS::Typemap, XSLoader, version::Internals
-
-=item Extension Modules
-
-=back
-
-=item CPAN
-
-=over 4
-
-=item Africa
-
-South Africa
-
-=item Asia
-
-China, Hong Kong, India, Indonesia, Japan, Republic of Korea, Russia,
-Singapore, Taiwan, Thailand, Turkey
-
-=item Central America
-
-Costa Rica
-
-=item Europe
-
-Austria, Belgium, Bosnia and Herzegovina, Bulgaria, Croatia, Czech
-Republic, Denmark, Finland, France, Germany, Greece, Hungary, Iceland,
-Ireland, Italy, Latvia, Lithuania, Malta, Netherlands, Norway, Poland,
-Portugal, Romania, Russia, Slovakia, Slovenia, Spain, Sweden, Switzerland,
-Ukraine, United Kingdom
-
-=item North America
-
-Bahamas, Canada, Mexico, United States, Alabama, Arizona, California,
-Florida, Idaho, Illinois, Indiana, Massachusetts, Michigan, Minnesota, New
-Jersey, New York, North Carolina, Oregon, Pennsylvania, South Carolina,
-Tennessee, Texas, Utah, Virginia, Washington, Wisconsin
-
-=item Oceania
-
-Australia, New Zealand
-
-=item South America
-
-Argentina, Brazil, Chile, Colombia
-
-=item RSYNC Mirrors
-
-=back
-
-=item Modules: Creation, Use, and Abuse
-
-=over 4
-
-=item Guidelines for Module Creation
-
-=item Guidelines for Converting Perl 4 Library Scripts into Modules
-
-=item Guidelines for Reusing Application Code
-
-=back
-
-=item NOTE
-
-=back
-
-=head2 perlmodstyle - Perl module style guide
-
-=over 4
-
-=item INTRODUCTION
-
-=item QUICK CHECKLIST
-
-=over 4
-
-=item Before you start
-
-=item The API
-
-=item Stability
-
-=item Documentation
-
-=item Release considerations
-
-=back
-
-=item BEFORE YOU START WRITING A MODULE
-
-=over 4
-
-=item Has it been done before?
-
-=item Do one thing and do it well
-
-=item What's in a name?
-
-=back
-
-=item DESIGNING AND WRITING YOUR MODULE
-
-=over 4
-
-=item To OO or not to OO?
-
-=item Designing your API
-
-Write simple routines to do simple things, Separate functionality from
-output, Provide sensible shortcuts and defaults, Naming conventions,
-Parameter passing
-
-=item Strictness and warnings
-
-=item Backwards compatibility
-
-=item Error handling and messages
-
-=back
-
-=item DOCUMENTING YOUR MODULE
-
-=over 4
-
-=item POD
-
-=item README, INSTALL, release notes, changelogs
-
-perl Makefile.PL, make, make test, make install, perl Build.PL, perl Build,
-perl Build test, perl Build install
-
-=back
-
-=item RELEASE CONSIDERATIONS
-
-=over 4
-
-=item Version numbering
-
-=item Pre-requisites
-
-=item Testing
-
-=item Packaging
-
-=item Licensing
-
-=back
-
-=item COMMON PITFALLS
-
-=over 4
-
-=item Reinventing the wheel
-
-=item Trying to do too much
-
-=item Inappropriate documentation
-
-=back
-
-=item SEE ALSO
-
-L<perlstyle>, L<perlnewmod>, L<perlpod>, L<podchecker>, Packaging Tools,
-Testing tools, http://pause.perl.org/, Any good book on software
-engineering
-
-=item AUTHOR
-
-=back
-
-=head2 perlmodinstall - Installing CPAN Modules
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item PREAMBLE
-
-B<DECOMPRESS> the file, B<UNPACK> the file into a directory, B<BUILD> the
-module (sometimes unnecessary), B<INSTALL> the module
-
-=back
-
-=item PORTABILITY
-
-=item HEY
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 perlnewmod - preparing a new module for distribution
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Warning
-
-=item What should I make into a module?
-
-=item Step-by-step: Preparing the ground
-
-Look around, Check it's new, Discuss the need, Choose a name, Check again
-
-=item Step-by-step: Making the module
-
-Start with F<module-starter> or F<h2xs>, Use L<strict|strict> and
-L<warnings|warnings>, Use L<Carp|Carp>, Use L<Exporter|Exporter> - wisely!,
-Use L<plain old documentation|perlpod>, Write tests, Write the README
-
-=item Step-by-step: Distributing your module
-
-Get a CPAN user ID, C<perl Makefile.PL; make test; make dist>, Upload the
-tarball, Announce to the modules list, Announce to clpa, Fix bugs!
-
-=back
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 perlpragma - how to write a user pragma
-
-=over 4
-
-=item DESCRIPTION
-
-=item A basic example
-
-=item Key naming
-
-=item Implementation details
-
-=back
-
-=head2 perlutil - utilities packaged with the Perl distribution
-
-=over 4
-
-=item DESCRIPTION
-
-=item LIST OF UTILITIES
-
-=over 4
-
-=item Documentation
-
-L<perldoc|perldoc>, L<pod2man|pod2man> and L<pod2text|pod2text>,
-L<pod2html|pod2html> and L<pod2latex|pod2latex>, L<pod2usage|pod2usage>,
-L<podselect|podselect>, L<podchecker|podchecker>, L<splain|splain>,
-C<roffitall>
-
-=item Converters
-
-L<a2p|a2p>, L<s2p|s2p> and L<psed>, L<find2perl|find2perl>
-
-=item Administration
-
-L<config_data|config_data>, L<libnetcfg|libnetcfg>, L<perlivp>
-
-=item Development
-
-L<perlbug|perlbug>, L<perlthanks|perlbug>, L<h2ph|h2ph>, L<c2ph|c2ph> and
-L<pstruct|pstruct>, L<h2xs|h2xs>, L<enc2xs>, L<xsubpp>, L<prove>,
-L<corelist>
-
-=item General tools
-
-L<piconv>, L<ptar>, L<ptardiff>, L<ptargrep>, L<shasum>, L<zipdetails>
-
-=item Installation
-
-L<cpan>, L<cpanp>, L<cpan2dist>, L<instmodsh>
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 perlfilter - Source Filters
-
-=over 4
-
-=item DESCRIPTION
-
-=item CONCEPTS
-
-=item USING FILTERS
-
-=item WRITING A SOURCE FILTER
-
-=item WRITING A SOURCE FILTER IN C
-
-B<Decryption Filters>
-
-=item CREATING A SOURCE FILTER AS A SEPARATE EXECUTABLE
-
-=item WRITING A SOURCE FILTER IN PERL
-
-=item USING CONTEXT: THE DEBUG FILTER
-
-=item CONCLUSION
-
-=item THINGS TO LOOK OUT FOR
-
-Some Filters Clobber the C<DATA> Handle
-
-=item REQUIREMENTS
-
-=item AUTHOR
-
-=item Copyrights
-
-=back
-
-=head2 perldtrace - Perl's support for DTrace
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item HISTORY
-
-=item PROBES
-
-sub-entry(SUBNAME, FILE, LINE, PACKAGE), sub-return(SUBNAME, FILE, LINE,
-PACKAGE), phase-change(NEWPHASE, OLDPHASE)
-
-=item EXAMPLES
-
-Most frequently called functions, Trace function calls, Function calls
-during interpreter cleanup, System calls at compile time
-
-=item REFERENCES
-
-DTrace User Guide, DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and
-FreeBSD
-
-=item AUTHORS
-
-=back
-
-=head2 perlglossary - Perl Glossary
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item A
-
-accessor methods, actual arguments, address operator, algorithm, alias,
-alternatives, anonymous, architecture, argument, ARGV, arithmetical
-operator, array, array context, ASCII, assertion, assignment, assignment
-operator, associative array, associativity, asynchronous, atom, atomic
-operation, attribute, autogeneration, autoincrement, autoload, autosplit,
-autovivification, AV, awk
-
-=item B
-
-backreference, backtracking, backward compatibility, bareword, base class,
-big-endian, binary, binary operator, bind, bit, bit shift, bit string,
-bless, block, BLOCK, block buffering, Boolean, Boolean context, breakpoint,
-broadcast, BSD, bucket, buffer, built-in, bundle, byte, bytecode
-
-=item C
-
-C, C preprocessor, call by reference, call by value, callback, canonical,
-capture buffer, capture group, capturing, character, character class,
-character property, circumfix operator, class, class method, client,
-cloister, closure, cluster, CODE, code generator, code point, code
-subpattern, collating sequence, command, command buffering, command name,
-command-line arguments, comment, compilation unit, compile phase, compile
-time, compiler, composer, concatenation, conditional, connection,
-construct, constructor, context, continuation, core dump, CPAN, cracker,
-current package, current working directory, currently selected output
-channel, CV
-
-=item D
-
-dangling statement, data structure, data type, datagram, DBM, declaration,
-decrement, default, defined, delimiter, deprecated modules and features,
-dereference, derived class, descriptor, destroy, destructor, device,
-directive, directory, directory handle, dispatch, distribution, (to be)
-dropped modules, dweomer, dwimmer, dynamic scoping
-
-=item E
-
-eclectic, element, embedding, empty list, empty subclass test, en passant,
-encapsulation, endian, environment, environment variable, EOF, errno,
-error, escape sequence, exception, exception handling, exec, executable
-file, execute, execute bit, exit status, export, expression, extension
-
-=item F
-
-false, FAQ, fatal error, field, FIFO, file, file descriptor, file test
-operator, fileglob, filehandle, filename, filesystem, filter, flag,
-floating point, flush, FMTEYEWTK, fork, formal arguments, format, freely
-available, freely redistributable, freeware, function, funny character
-
-=item G
-
-garbage collection, GID, glob, global, global destruction, glue language,
-granularity, greedy, grep, group, GV
-
-=item H
-
-hacker, handler, hard reference, hash, hash table, header file, here
-document, hexadecimal, home directory, host, hubris, HV
-
-=item I
-
-identifier, impatience, implementation, import, increment, indexing,
-indirect filehandle, indirect object, indirect object slot, indirection,
-infix, inheritance, instance, instance variable, integer, interface,
-interpolation, interpreter, invocant, invocation, I/O, IO, IP, IPC, is-a,
-iteration, iterator, IV
-
-=item J
-
-JAPH
-
-=item K
-
-key, keyword
-
-=item L
-
-label, laziness, left shift, leftmost longest, lexeme, lexer, lexical
-analysis, lexical scoping, lexical variable, library, LIFO, line, line
-buffering, line number, link, LIST, list, list context, list operator, list
-value, literal, little-endian, local, logical operator, lookahead,
-lookbehind, loop, loop control statement, loop label, lvaluable, lvalue,
-lvalue modifier
-
-=item M
-
-magic, magical increment, magical variables, Makefile, man, manpage,
-matching, member data, memory, metacharacter, metasymbol, method,
-minimalism, mode, modifier, module, modulus, monger, mortal,
-multidimensional array, multiple inheritance
-
-=item N
-
-named pipe, namespace, network address, newline, NFS, null character, null
-list, null string, numeric context, NV, nybble
-
-=item O
-
-object, octal, offset, one-liner, open source software, operand, operating
-system, operator, operator overloading, options, ordinal, overloading,
-overriding, owner
-
-=item P
-
-package, pad, parameter, parent class, parse tree, parsing, patch, PATH,
-pathname, pattern, pattern matching, permission bits, Pern, pipe, pipeline,
-platform, pod, pointer, polymorphism, port, portable, porter, POSIX,
-postfix, pp, pragma, precedence, prefix, preprocessing, procedure, process,
-program generator, progressive matching, property, protocol, prototype,
-pseudofunction, pseudohash, pseudoliteral, public domain, pumpkin,
-pumpking, PV
-
-=item Q
-
-qualified, quantifier
-
-=item R
-
-readable, reaping, record, recursion, reference, referent, regex, regular
-expression, regular expression modifier, regular file, relational operator,
-reserved words, restricted hash, return value, RFC, right shift, root,
-RTFM, run phase, run time, run-time pattern, RV, rvalue
-
-=item S
-
-scalar, scalar context, scalar literal, scalar value, scalar variable,
-scope, scratchpad, script, script kiddie, sed, semaphore, separator,
-serialization, server, service, setgid, setuid, shared memory, shebang,
-shell, side effects, signal, signal handler, single inheritance, slice,
-slurp, socket, soft reference, source filter, stack, standard, standard
-error, standard I/O, standard input, standard output, stat structure,
-statement, statement modifier, static, static method, static scoping,
-static variable, status, STDERR, STDIN, STDIO, STDOUT, stream, string,
-string context, stringification, struct, structure, subclass, subpattern,
-subroutine, subscript, substitution, substring, superclass, superuser, SV,
-switch, switch cluster, switch statement, symbol, symbol table, symbolic
-debugger, symbolic link, symbolic reference, synchronous, syntactic sugar,
-syntax, syntax tree, syscall
-
-=item T
-
-tainted, TCP, term, terminator, ternary, text, thread, tie, TMTOWTDI,
-token, tokener, tokenizing, toolbox approach, transliterate, trigger,
-trinary, troff, true, truncating, type, type casting, typed lexical,
-typedef, typeglob, typemap
-
-=item U
-
-UDP, UID, umask, unary operator, Unicode, Unix
-
-=item V
-
-value, variable, variable interpolation, variadic, vector, virtual, void
-context, v-string
-
-=item W
-
-warning, watch expression, whitespace, word, working directory, wrapper,
-WYSIWYG
-
-=item X
-
-XS, XSUB
-
-=item Y
-
-yacc
-
-=item Z
-
-zero width, zombie
-
-=back
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlembed - how to embed perl in your C program
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item PREAMBLE
-
-B<Use C from Perl?>, B<Use a Unix program from Perl?>, B<Use Perl from
-Perl?>, B<Use C from C?>, B<Use Perl from C?>
-
-=item ROADMAP
-
-=item Compiling your C program
-
-=item Adding a Perl interpreter to your C program
-
-=item Calling a Perl subroutine from your C program
-
-=item Evaluating a Perl statement from your C program
-
-=item Performing Perl pattern matches and substitutions from your C program
-
-=item Fiddling with the Perl stack from your C program
-
-=item Maintaining a persistent interpreter
-
-=item Execution of END blocks
-
-=item $0 assignments
-
-=item Maintaining multiple interpreter instances
-
-=item Using Perl modules, which themselves use C libraries, from your C
-program
-
-=back
-
-=item Hiding Perl_
-
-=item MORAL
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 perldebguts - Guts of Perl debugging
-
-=over 4
-
-=item DESCRIPTION
-
-=item Debugger Internals
-
-=over 4
-
-=item Writing Your Own Debugger
-
-=back
-
-=item Frame Listing Output Examples
-
-=item Debugging Regular Expressions
-
-=over 4
-
-=item Compile-time Output
-
-C<anchored> I<STRING> C<at> I<POS>, C<floating> I<STRING> C<at>
-I<POS1..POS2>, C<matching floating/anchored>, C<minlen>, C<stclass>
-I<TYPE>, C<noscan>, C<isall>, C<GPOS>, C<plus>, C<implicit>, C<with eval>,
-C<anchored(TYPE)>
-
-=item Types of Nodes
-
-=item Run-time Output
-
-=back
-
-=item Debugging Perl Memory Usage
-
-=over 4
-
-=item Using C<$ENV{PERL_DEBUG_MSTATS}>
-
-C<buckets SMALLEST(APPROX)..GREATEST(APPROX)>, Free/Used, C<Total sbrk():
-SBRKed/SBRKs:CONTINUOUS>, C<pad: 0>, C<heads: 2192>, C<chain: 0>, C<tail:
-6144>
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 perlxstut - Tutorial for writing XSUBs
-
-=over 4
-
-=item DESCRIPTION
-
-=item SPECIAL NOTES
-
-=over 4
-
-=item make
-
-=item Version caveat
-
-=item Dynamic Loading versus Static Loading
-
-=back
-
-=item TUTORIAL
-
-=over 4
-
-=item EXAMPLE 1
-
-=item EXAMPLE 2
-
-=item What has gone on?
-
-=item Writing good test scripts
-
-=item EXAMPLE 3
-
-=item What's new here?
-
-=item Input and Output Parameters
-
-=item The XSUBPP Program
-
-=item The TYPEMAP file
-
-=item Warning about Output Arguments
-
-=item EXAMPLE 4
-
-=item What has happened here?
-
-=item Anatomy of .xs file
-
-=item Getting the fat out of XSUBs
-
-=item More about XSUB arguments
-
-=item The Argument Stack
-
-=item Extending your Extension
-
-=item Documenting your Extension
-
-=item Installing your Extension
-
-=item EXAMPLE 5
-
-=item New Things in this Example
-
-=item EXAMPLE 6
-
-=item New Things in this Example
-
-=item EXAMPLE 7 (Coming Soon)
-
-=item EXAMPLE 8 (Coming Soon)
-
-=item EXAMPLE 9 Passing open files to XSes
-
-=item Troubleshooting these Examples
-
-=back
-
-=item See also
-
-=item Author
-
-=over 4
-
-=item Last Changed
-
-=back
-
-=back
-
-=head2 perlxs - XS language reference manual
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Introduction
-
-=item On The Road
-
-=item The Anatomy of an XSUB
-
-=item The Argument Stack
-
-=item The RETVAL Variable
-
-=item Returning SVs, AVs and HVs through RETVAL
-
-=item The MODULE Keyword
-
-=item The PACKAGE Keyword
-
-=item The PREFIX Keyword
-
-=item The OUTPUT: Keyword
-
-=item The NO_OUTPUT Keyword
-
-=item The CODE: Keyword
-
-=item The INIT: Keyword
-
-=item The NO_INIT Keyword
-
-=item The TYPEMAP: Keyword
-
-=item Initializing Function Parameters
-
-=item Default Parameter Values
-
-=item The PREINIT: Keyword
-
-=item The SCOPE: Keyword
-
-=item The INPUT: Keyword
-
-=item The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords
-
-=item The C<length(NAME)> Keyword
-
-=item Variable-length Parameter Lists
-
-=item The C_ARGS: Keyword
-
-=item The PPCODE: Keyword
-
-=item Returning Undef And Empty Lists
-
-=item The REQUIRE: Keyword
-
-=item The CLEANUP: Keyword
-
-=item The POSTCALL: Keyword
-
-=item The BOOT: Keyword
-
-=item The VERSIONCHECK: Keyword
-
-=item The PROTOTYPES: Keyword
-
-=item The PROTOTYPE: Keyword
-
-=item The ALIAS: Keyword
-
-=item The OVERLOAD: Keyword
-
-=item The FALLBACK: Keyword
-
-=item The INTERFACE: Keyword
-
-=item The INTERFACE_MACRO: Keyword
-
-=item The INCLUDE: Keyword
-
-=item The INCLUDE_COMMAND: Keyword
-
-=item The CASE: Keyword
-
-=item The EXPORT_XSUB_SYMBOLS: Keyword
-
-=item The & Unary Operator
-
-=item Inserting POD, Comments and C Preprocessor Directives
-
-=item Using XS With C++
-
-=item Interface Strategy
-
-=item Perl Objects And C Structures
-
-=item Safely Storing Static Data in XS
-
-MY_CXT_KEY, typedef my_cxt_t, START_MY_CXT, MY_CXT_INIT, dMY_CXT, MY_CXT,
-aMY_CXT/pMY_CXT, MY_CXT_CLONE, MY_CXT_INIT_INTERP(my_perl),
-dMY_CXT_INTERP(my_perl)
-
-=item Thread-aware system interfaces
-
-=back
-
-=item EXAMPLES
-
-=item XS VERSION
-
-=item AUTHOR
-
-=back
-
-=head2 perlxstypemap - Perl XS C/Perl type mapping
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Anatomy of a typemap
-
-=item The Role of the typemap File in Your Distribution
-
-=item Sharing typemaps Between CPAN Distributions
-
-=item Writing typemap Entries
-
-=item Full Listing of Core Typemaps
-
-T_SV, T_SVREF, T_SVREF_FIXED, T_AVREF, T_AVREF_REFCOUNT_FIXED, T_HVREF,
-T_HVREF_REFCOUNT_FIXED, T_CVREF, T_CVREF_REFCOUNT_FIXED, T_SYSRET, T_UV,
-T_IV, T_INT, T_ENUM, T_BOOL, T_U_INT, T_SHORT, T_U_SHORT, T_LONG, T_U_LONG,
-T_CHAR, T_U_CHAR, T_FLOAT, T_NV, T_DOUBLE, T_PV, T_PTR, T_PTRREF, T_PTROBJ,
-T_REF_IV_REF, T_REF_IV_PTR, T_PTRDESC, T_REFREF, T_REFOBJ, T_OPAQUEPTR,
-T_OPAQUE, Implicit array, T_PACKED, T_PACKEDARRAY, T_DATAUNIT, T_CALLBACK,
-T_ARRAY, T_STDIO, T_INOUT, T_IN, T_OUT
-
-=back
-
-=back
-
-=head2 perlclib - Internal replacements for standard C library functions
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Conventions
-
-C<t>, C<p>, C<n>, C<s>
-
-=item File Operations
-
-=item File Input and Output
-
-=item File Positioning
-
-=item Memory Management and String Handling
-
-=item Character Class Tests
-
-=item F<stdlib.h> functions
-
-=item Miscellaneous functions
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 perlguts - Introduction to the Perl API
-
-=over 4
-
-=item DESCRIPTION
-
-=item Variables
-
-=over 4
-
-=item Datatypes
-
-=item What is an "IV"?
-
-=item Working with SVs
-
-=item Offsets
-
-=item What's Really Stored in an SV?
-
-=item Working with AVs
-
-=item Working with HVs
-
-=item Hash API Extensions
-
-=item AVs, HVs and undefined values
-
-=item References
-
-=item Blessed References and Class Objects
-
-=item Creating New Variables
-
-GV_ADDMULTI, GV_ADDWARN
-
-=item Reference Counts and Mortality
-
-=item Stashes and Globs
-
-=item Double-Typed SVs
-
-=item Magic Variables
-
-=item Assigning Magic
-
-=item Magic Virtual Tables
-
-=item Finding Magic
-
-=item Understanding the Magic of Tied Hashes and Arrays
-
-=item Localizing changes
-
-C<SAVEINT(int i)>, C<SAVEIV(IV i)>, C<SAVEI32(I32 i)>, C<SAVELONG(long i)>,
-C<SAVESPTR(s)>, C<SAVEPPTR(p)>, C<SAVEFREESV(SV *sv)>, C<SAVEMORTALIZESV(SV
-*sv)>, C<SAVEFREEOP(OP *op)>, C<SAVEFREEPV(p)>, C<SAVECLEARSV(SV *sv)>,
-C<SAVEDELETE(HV *hv, char *key, I32 length)>,
-C<SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)>,
-C<SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)>, C<SAVESTACK_POS()>, C<SV*
-save_scalar(GV *gv)>, C<AV* save_ary(GV *gv)>, C<HV* save_hash(GV *gv)>,
-C<void save_item(SV *item)>, C<void save_list(SV **sarg, I32 maxsarg)>,
-C<SV* save_svref(SV **sptr)>, C<void save_aptr(AV **aptr)>, C<void
-save_hptr(HV **hptr)>
-
-=back
-
-=item Subroutines
-
-=over 4
-
-=item XSUBs and the Argument Stack
-
-=item Autoloading with XSUBs
-
-=item Calling Perl Routines from within C Programs
-
-=item Memory Allocation
-
-=item PerlIO
-
-=item Putting a C value on Perl stack
-
-=item Scratchpads
-
-=item Scratchpads and recursion
-
-=back
-
-=item Compiled code
-
-=over 4
-
-=item Code tree
-
-=item Examining the tree
-
-=item Compile pass 1: check routines
-
-=item Compile pass 1a: constant folding
-
-=item Compile pass 2: context propagation
-
-=item Compile pass 3: peephole optimization
-
-=item Pluggable runops
-
-=item Compile-time scope hooks
-
-C<void bhk_start(pTHX_ int full)>, C<void bhk_pre_end(pTHX_ OP **o)>,
-C<void bhk_post_end(pTHX_ OP **o)>, C<void bhk_eval(pTHX_ OP *const o)>
-
-=back
-
-=item Examining internal data structures with the C<dump> functions
-
-=item How multiple interpreters and concurrency are supported
-
-=over 4
-
-=item Background and PERL_IMPLICIT_CONTEXT
-
-=item So what happened to dTHR?
-
-=item How do I use all this in extensions?
-
-=item Should I do anything special if I call perl from multiple threads?
-
-=item Future Plans and PERL_IMPLICIT_SYS
-
-=back
-
-=item Internal Functions
-
-A, p, d, s, n, r, f, M, o, x, m, X, E, b, others
-
-=over 4
-
-=item Formatted Printing of IVs, UVs, and NVs
-
-=item Pointer-To-Integer and Integer-To-Pointer
-
-=item Exception Handling
-
-=item Source Documentation
-
-=item Backwards compatibility
-
-=back
-
-=item Unicode Support
-
-=over 4
-
-=item What B<is> Unicode, anyway?
-
-=item How can I recognise a UTF-8 string?
-
-=item How does UTF-8 represent Unicode characters?
-
-=item How does Perl store UTF-8 strings?
-
-=item How do I convert a string to UTF-8?
-
-=item Is there anything else I need to know?
-
-=back
-
-=item Custom Operators
-
-xop_name, xop_desc, xop_class, OA_BASEOP, OA_UNOP, OA_BINOP, OA_LOGOP,
-OA_LISTOP, OA_PMOP, OA_SVOP, OA_PADOP, OA_PVOP_OR_SVOP, OA_LOOP, OA_COP,
-xop_peep
-
-=item AUTHORS
-
-=item SEE ALSO
-
-=back
-
-=head2 perlcall - Perl calling conventions from C
-
-=over 4
-
-=item DESCRIPTION
-
-An Error Handler, An Event-Driven Program
-
-=item THE CALL_ FUNCTIONS
-
-call_sv, call_pv, call_method, call_argv
-
-=item FLAG VALUES
-
-=over 4
-
-=item G_VOID
-
-=item G_SCALAR
-
-=item G_ARRAY
-
-=item G_DISCARD
-
-=item G_NOARGS
-
-=item G_EVAL
-
-=item G_KEEPERR
-
-=item Determining the Context
-
-=back
-
-=item EXAMPLES
-
-=over 4
-
-=item No Parameters, Nothing Returned
-
-=item Passing Parameters
-
-=item Returning a Scalar
-
-=item Returning a List of Values
-
-=item Returning a List in a Scalar Context
-
-=item Returning Data from Perl via the Parameter List
-
-=item Using G_EVAL
-
-=item Using G_KEEPERR
-
-=item Using call_sv
-
-=item Using call_argv
-
-=item Using call_method
-
-=item Using GIMME_V
-
-=item Using Perl to Dispose of Temporaries
-
-=item Strategies for Storing Callback Context Information
-
-1. Ignore the problem - Allow only 1 callback, 2. Create a sequence of
-callbacks - hard wired limit, 3. Use a parameter to map to the Perl
-callback
-
-=item Alternate Stack Manipulation
-
-=item Creating and Calling an Anonymous Subroutine in C
-
-=back
-
-=item LIGHTWEIGHT CALLBACKS
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item DATE
-
-=back
-
-=head2 perlmroapi - Perl method resolution plugin interface
-
-=over 4
-
-=item DESCRIPTION
-
-resolve, name, length, kflags, hash
-
-=item Callbacks
-
-=item Caching
-
-=item Examples
-
-=item AUTHORS
-
-=back
-
-=head2 perlreapi - perl regular expression plugin interface
-
-=over 4
-
-=item DESCRIPTION
-
-=item Callbacks
-
-=over 4
-
-=item comp
-
-C</m> - RXf_PMf_MULTILINE, C</s> - RXf_PMf_SINGLELINE, C</i> -
-RXf_PMf_FOLD, C</x> - RXf_PMf_EXTENDED, C</p> - RXf_PMf_KEEPCOPY, Character
-set, RXf_UTF8, RXf_SPLIT, RXf_SKIPWHITE, RXf_START_ONLY, RXf_WHITE,
-RXf_NULL
-
-=item exec
-
-=item intuit
-
-=item checkstr
-
-=item free
-
-=item Numbered capture callbacks
-
-=item Named capture callbacks
-
-=item qr_package
-
-=item dupe
-
-=back
-
-=item The REGEXP structure
-
-=over 4
-
-=item C<engine>
-
-=item C<mother_re>
-
-=item C<extflags>
-
-=item C<minlen> C<minlenret>
-
-=item C<gofs>
-
-=item C<substrs>
-
-=item C<nparens>, C<lastparen>, and C<lastcloseparen>
-
-=item C<intflags>
-
-=item C<pprivate>
-
-=item C<swap>
-
-=item C<offs>
-
-=item C<precomp> C<prelen>
-
-=item C<paren_names>
-
-=item C<substrs>
-
-=item C<subbeg> C<sublen> C<saved_copy>
-
-=item C<wrapped> C<wraplen>
-
-=item C<seen_evals>
-
-=item C<refcnt>
-
-=back
-
-=item HISTORY
-
-=item AUTHORS
-
-=item LICENSE
-
-=back
-
-=head2 perlreguts - Description of the Perl regular expression engine.
-
-=over 4
-
-=item DESCRIPTION
-
-=item OVERVIEW
-
-=over 4
-
-=item A quick note on terms
-
-=item What is a regular expression engine?
-
-=item Structure of a Regexp Program
-
-C<regnode_1>, C<regnode_2>, C<regnode_string>, C<regnode_charclass>,
-C<regnode_charclass_class>
-
-=back
-
-=item Process Overview
-
-A. Compilation, 1. Parsing for size, 2. Parsing for construction, 3.
-Peep-hole optimisation and analysis, B. Execution, 4. Start position and
-no-match optimisations, 5. Program execution
-
-=over 4
-
-=item Compilation
-
-anchored fixed strings, floating fixed strings, minimum and maximum length
-requirements, start class, Beginning/End of line positions
-
-=item Execution
-
-=back
-
-=item MISCELLANEOUS
-
-=over 4
-
-=item Unicode and Localisation Support
-
-=item Base Structures
-
-C<swap>, C<offsets>, C<regstclass>, C<data>, C<program>
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item LICENCE
-
-=item REFERENCES
-
-=back
-
-=head2 perlapi - autogenerated documentation for the perl public API
-
-=over 4
-
-=item DESCRIPTION
-X<Perl API> X<API> X<api>
-
-=item "Gimme" Values
-
-GIMME X<GIMME>, GIMME_V X<GIMME_V>, G_ARRAY X<G_ARRAY>, G_DISCARD
-X<G_DISCARD>, G_EVAL X<G_EVAL>, G_NOARGS X<G_NOARGS>, G_SCALAR X<G_SCALAR>,
-G_VOID X<G_VOID>
-
-=item Array Manipulation Functions
-
-AvFILL X<AvFILL>, av_clear X<av_clear>, av_create_and_push
-X<av_create_and_push>, av_create_and_unshift_one
-X<av_create_and_unshift_one>, av_delete X<av_delete>, av_exists
-X<av_exists>, av_extend X<av_extend>, av_fetch X<av_fetch>, av_fill
-X<av_fill>, av_len X<av_len>, av_make X<av_make>, av_pop X<av_pop>, av_push
-X<av_push>, av_shift X<av_shift>, av_store X<av_store>, av_undef
-X<av_undef>, av_unshift X<av_unshift>, get_av X<get_av>, newAV X<newAV>,
-sortsv X<sortsv>, sortsv_flags X<sortsv_flags>
-
-=item Callback Functions
-
-call_argv X<call_argv>, call_method X<call_method>, call_pv X<call_pv>,
-call_sv X<call_sv>, ENTER X<ENTER>, eval_pv X<eval_pv>, eval_sv X<eval_sv>,
-FREETMPS X<FREETMPS>, LEAVE X<LEAVE>, SAVETMPS X<SAVETMPS>
-
-=item Character case changing
-
-toLOWER X<toLOWER>, toUPPER X<toUPPER>
-
-=item Character classes
-
-isALPHA X<isALPHA>, isASCII X<isASCII>, isDIGIT X<isDIGIT>, isLOWER
-X<isLOWER>, isOCTAL X<isOCTAL>, isSPACE X<isSPACE>, isUPPER X<isUPPER>,
-isWORDCHAR X<isWORDCHAR>, isXDIGIT X<isXDIGIT>
-
-=item Cloning an interpreter
-
-perl_clone X<perl_clone>
-
-=item Compile-time scope hooks
-
-BhkDISABLE X<BhkDISABLE>, BhkENABLE X<BhkENABLE>, BhkENTRY_set
-X<BhkENTRY_set>, blockhook_register X<blockhook_register>
-
-=item COP Hint Hashes
-
-cophh_2hv X<cophh_2hv>, cophh_copy X<cophh_copy>, cophh_delete_pv
-X<cophh_delete_pv>, cophh_delete_pvn X<cophh_delete_pvn>, cophh_delete_pvs
-X<cophh_delete_pvs>, cophh_delete_sv X<cophh_delete_sv>, cophh_fetch_pv
-X<cophh_fetch_pv>, cophh_fetch_pvn X<cophh_fetch_pvn>, cophh_fetch_pvs
-X<cophh_fetch_pvs>, cophh_fetch_sv X<cophh_fetch_sv>, cophh_free
-X<cophh_free>, cophh_new_empty X<cophh_new_empty>, cophh_store_pv
-X<cophh_store_pv>, cophh_store_pvn X<cophh_store_pvn>, cophh_store_pvs
-X<cophh_store_pvs>, cophh_store_sv X<cophh_store_sv>
-
-=item COP Hint Reading
-
-cop_hints_2hv X<cop_hints_2hv>, cop_hints_fetch_pv X<cop_hints_fetch_pv>,
-cop_hints_fetch_pvn X<cop_hints_fetch_pvn>, cop_hints_fetch_pvs
-X<cop_hints_fetch_pvs>, cop_hints_fetch_sv X<cop_hints_fetch_sv>
-
-=item Custom Operators
-
-custom_op_register X<custom_op_register>, custom_op_xop X<custom_op_xop>,
-XopDISABLE X<XopDISABLE>, XopENABLE X<XopENABLE>, XopENTRY X<XopENTRY>,
-XopENTRY_set X<XopENTRY_set>, XopFLAGS X<XopFLAGS>
-
-=item CV Manipulation Functions
-
-CvSTASH X<CvSTASH>, get_cv X<get_cv>, get_cvn_flags X<get_cvn_flags>
-
-=item Embedding Functions
-
-cv_clone X<cv_clone>, cv_undef X<cv_undef>, find_rundefsv X<find_rundefsv>,
-find_rundefsvoffset X<find_rundefsvoffset>, load_module X<load_module>,
-nothreadhook X<nothreadhook>, pad_add_anon X<pad_add_anon>, pad_add_name_pv
-X<pad_add_name_pv>, pad_add_name_pvn X<pad_add_name_pvn>, pad_add_name_sv
-X<pad_add_name_sv>, pad_alloc X<pad_alloc>, pad_compname_type
-X<pad_compname_type>, pad_findmy_pv X<pad_findmy_pv>, pad_findmy_pvn
-X<pad_findmy_pvn>, pad_findmy_sv X<pad_findmy_sv>, pad_setsv X<pad_setsv>,
-pad_sv X<pad_sv>, pad_tidy X<pad_tidy>, perl_alloc X<perl_alloc>,
-perl_construct X<perl_construct>, perl_destruct X<perl_destruct>, perl_free
-X<perl_free>, perl_parse X<perl_parse>, perl_run X<perl_run>, require_pv
-X<require_pv>
-
-=item Functions in file dump.c
-
-pv_display X<pv_display>, pv_escape X<pv_escape>, pv_pretty X<pv_pretty>
-
-=item Functions in file mathoms.c
-
-custom_op_desc X<custom_op_desc>, custom_op_name X<custom_op_name>,
-gv_fetchmethod X<gv_fetchmethod>, pack_cat X<pack_cat>, sv_2pvbyte_nolen
-X<sv_2pvbyte_nolen>, sv_2pvutf8_nolen X<sv_2pvutf8_nolen>, sv_2pv_nolen
-X<sv_2pv_nolen>, sv_catpvn_mg X<sv_catpvn_mg>, sv_catsv_mg X<sv_catsv_mg>,
-sv_force_normal X<sv_force_normal>, sv_iv X<sv_iv>, sv_nolocking
-X<sv_nolocking>, sv_nounlocking X<sv_nounlocking>, sv_nv X<sv_nv>, sv_pv
-X<sv_pv>, sv_pvbyte X<sv_pvbyte>, sv_pvbyten X<sv_pvbyten>, sv_pvn
-X<sv_pvn>, sv_pvutf8 X<sv_pvutf8>, sv_pvutf8n X<sv_pvutf8n>, sv_taint
-X<sv_taint>, sv_unref X<sv_unref>, sv_usepvn X<sv_usepvn>, sv_usepvn_mg
-X<sv_usepvn_mg>, sv_uv X<sv_uv>, unpack_str X<unpack_str>
-
-=item Functions in file op.c
-
-op_contextualize X<op_contextualize>
-
-=item Functions in file perl.h
-
-PERL_SYS_INIT X<PERL_SYS_INIT>, PERL_SYS_INIT3 X<PERL_SYS_INIT3>,
-PERL_SYS_TERM X<PERL_SYS_TERM>
-
-=item Functions in file pp_ctl.c
-
-caller_cx X<caller_cx>, find_runcv X<find_runcv>
-
-=item Functions in file pp_pack.c
-
-packlist X<packlist>, unpackstring X<unpackstring>
-
-=item Functions in file pp_sys.c
-
-setdefout X<setdefout>
-
-=item Functions in file utf8.h
-
-ibcmp_utf8 X<ibcmp_utf8>
-
-=item Functions in file util.h
-
-ibcmp X<ibcmp>, ibcmp_locale X<ibcmp_locale>
-
-=item Global Variables
-
-PL_check X<PL_check>, PL_keyword_plugin X<PL_keyword_plugin>
-
-=item GV Functions
-
-GvSV X<GvSV>, gv_const_sv X<gv_const_sv>, gv_fetchmeth X<gv_fetchmeth>,
-gv_fetchmethod_autoload X<gv_fetchmethod_autoload>, gv_fetchmeth_autoload
-X<gv_fetchmeth_autoload>, gv_fetchmeth_pv X<gv_fetchmeth_pv>,
-gv_fetchmeth_pvn X<gv_fetchmeth_pvn>, gv_fetchmeth_pvn_autoload
-X<gv_fetchmeth_pvn_autoload>, gv_fetchmeth_pv_autoload
-X<gv_fetchmeth_pv_autoload>, gv_fetchmeth_sv X<gv_fetchmeth_sv>,
-gv_fetchmeth_sv_autoload X<gv_fetchmeth_sv_autoload>, gv_init X<gv_init>,
-gv_init_pv X<gv_init_pv>, gv_init_pvn X<gv_init_pvn>, gv_init_sv
-X<gv_init_sv>, gv_stashpv X<gv_stashpv>, gv_stashpvn X<gv_stashpvn>,
-gv_stashpvs X<gv_stashpvs>, gv_stashsv X<gv_stashsv>
-
-=item Handy Values
-
-Nullav X<Nullav>, Nullch X<Nullch>, Nullcv X<Nullcv>, Nullhv X<Nullhv>,
-Nullsv X<Nullsv>
-
-=item Hash Manipulation Functions
-
-cop_fetch_label X<cop_fetch_label>, cop_store_label X<cop_store_label>,
-get_hv X<get_hv>, HEf_SVKEY X<HEf_SVKEY>, HeHASH X<HeHASH>, HeKEY X<HeKEY>,
-HeKLEN X<HeKLEN>, HePV X<HePV>, HeSVKEY X<HeSVKEY>, HeSVKEY_force
-X<HeSVKEY_force>, HeSVKEY_set X<HeSVKEY_set>, HeUTF8 X<HeUTF8>, HeVAL
-X<HeVAL>, HvENAME X<HvENAME>, HvENAMELEN X<HvENAMELEN>, HvENAMEUTF8
-X<HvENAMEUTF8>, HvNAME X<HvNAME>, HvNAMELEN X<HvNAMELEN>, HvNAMEUTF8
-X<HvNAMEUTF8>, hv_assert X<hv_assert>, hv_clear X<hv_clear>,
-hv_clear_placeholders X<hv_clear_placeholders>, hv_copy_hints_hv
-X<hv_copy_hints_hv>, hv_delete X<hv_delete>, hv_delete_ent
-X<hv_delete_ent>, hv_exists X<hv_exists>, hv_exists_ent X<hv_exists_ent>,
-hv_fetch X<hv_fetch>, hv_fetchs X<hv_fetchs>, hv_fetch_ent X<hv_fetch_ent>,
-hv_fill X<hv_fill>, hv_iterinit X<hv_iterinit>, hv_iterkey X<hv_iterkey>,
-hv_iterkeysv X<hv_iterkeysv>, hv_iternext X<hv_iternext>, hv_iternextsv
-X<hv_iternextsv>, hv_iternext_flags X<hv_iternext_flags>, hv_iterval
-X<hv_iterval>, hv_magic X<hv_magic>, hv_scalar X<hv_scalar>, hv_store
-X<hv_store>, hv_stores X<hv_stores>, hv_store_ent X<hv_store_ent>, hv_undef
-X<hv_undef>, newHV X<newHV>
-
-=item Hook manipulation
-
-wrap_op_checker X<wrap_op_checker>
-
-=item Lexer interface
-
-lex_bufutf8 X<lex_bufutf8>, lex_discard_to X<lex_discard_to>,
-lex_grow_linestr X<lex_grow_linestr>, lex_next_chunk X<lex_next_chunk>,
-lex_peek_unichar X<lex_peek_unichar>, lex_read_space X<lex_read_space>,
-lex_read_to X<lex_read_to>, lex_read_unichar X<lex_read_unichar>, lex_start
-X<lex_start>, lex_stuff_pv X<lex_stuff_pv>, lex_stuff_pvn X<lex_stuff_pvn>,
-lex_stuff_pvs X<lex_stuff_pvs>, lex_stuff_sv X<lex_stuff_sv>, lex_unstuff
-X<lex_unstuff>, parse_arithexpr X<parse_arithexpr>, parse_barestmt
-X<parse_barestmt>, parse_block X<parse_block>, parse_fullexpr
-X<parse_fullexpr>, parse_fullstmt X<parse_fullstmt>, parse_label
-X<parse_label>, parse_listexpr X<parse_listexpr>, parse_stmtseq
-X<parse_stmtseq>, parse_termexpr X<parse_termexpr>, PL_parser X<PL_parser>,
-PL_parser-E<gt>bufend X<PL_parser-E<gt>bufend>, PL_parser-E<gt>bufptr
-X<PL_parser-E<gt>bufptr>, PL_parser-E<gt>linestart
-X<PL_parser-E<gt>linestart>, PL_parser-E<gt>linestr
-X<PL_parser-E<gt>linestr>
-
-=item Magical Functions
-
-mg_clear X<mg_clear>, mg_copy X<mg_copy>, mg_find X<mg_find>, mg_findext
-X<mg_findext>, mg_free X<mg_free>, mg_free_type X<mg_free_type>, mg_get
-X<mg_get>, mg_length X<mg_length>, mg_magical X<mg_magical>, mg_set
-X<mg_set>, SvGETMAGIC X<SvGETMAGIC>, SvLOCK X<SvLOCK>, SvSETMAGIC
-X<SvSETMAGIC>, SvSetMagicSV X<SvSetMagicSV>, SvSetMagicSV_nosteal
-X<SvSetMagicSV_nosteal>, SvSetSV X<SvSetSV>, SvSetSV_nosteal
-X<SvSetSV_nosteal>, SvSHARE X<SvSHARE>, SvUNLOCK X<SvUNLOCK>
-
-=item Memory Management
-
-Copy X<Copy>, CopyD X<CopyD>, Move X<Move>, MoveD X<MoveD>, Newx X<Newx>,
-Newxc X<Newxc>, Newxz X<Newxz>, Poison X<Poison>, PoisonFree X<PoisonFree>,
-PoisonNew X<PoisonNew>, PoisonWith X<PoisonWith>, Renew X<Renew>, Renewc
-X<Renewc>, Safefree X<Safefree>, savepv X<savepv>, savepvn X<savepvn>,
-savepvs X<savepvs>, savesharedpv X<savesharedpv>, savesharedpvn
-X<savesharedpvn>, savesharedpvs X<savesharedpvs>, savesharedsvpv
-X<savesharedsvpv>, savesvpv X<savesvpv>, StructCopy X<StructCopy>, Zero
-X<Zero>, ZeroD X<ZeroD>
-
-=item Miscellaneous Functions
-
-fbm_compile X<fbm_compile>, fbm_instr X<fbm_instr>, foldEQ X<foldEQ>,
-foldEQ_locale X<foldEQ_locale>, form X<form>, getcwd_sv X<getcwd_sv>, mess
-X<mess>, mess_sv X<mess_sv>, my_snprintf X<my_snprintf>, my_sprintf
-X<my_sprintf>, my_vsnprintf X<my_vsnprintf>, new_version X<new_version>,
-prescan_version X<prescan_version>, scan_version X<scan_version>, strEQ
-X<strEQ>, strGE X<strGE>, strGT X<strGT>, strLE X<strLE>, strLT X<strLT>,
-strNE X<strNE>, strnEQ X<strnEQ>, strnNE X<strnNE>, sv_destroyable
-X<sv_destroyable>, sv_nosharing X<sv_nosharing>, upg_version
-X<upg_version>, vcmp X<vcmp>, vmess X<vmess>, vnormal X<vnormal>, vnumify
-X<vnumify>, vstringify X<vstringify>, vverify X<vverify>
-
-=item MRO Functions
-
-mro_get_linear_isa X<mro_get_linear_isa>, mro_method_changed_in
-X<mro_method_changed_in>, mro_register X<mro_register>
-
-=item Multicall Functions
-
-dMULTICALL X<dMULTICALL>, MULTICALL X<MULTICALL>, POP_MULTICALL
-X<POP_MULTICALL>, PUSH_MULTICALL X<PUSH_MULTICALL>
-
-=item Numeric functions
-
-grok_bin X<grok_bin>, grok_hex X<grok_hex>, grok_number X<grok_number>,
-grok_numeric_radix X<grok_numeric_radix>, grok_oct X<grok_oct>,
-Perl_signbit X<Perl_signbit>, scan_bin X<scan_bin>, scan_hex X<scan_hex>,
-scan_oct X<scan_oct>
-
-=item Optree construction
-
-newASSIGNOP X<newASSIGNOP>, newBINOP X<newBINOP>, newCONDOP X<newCONDOP>,
-newFOROP X<newFOROP>, newGIVENOP X<newGIVENOP>, newGVOP X<newGVOP>,
-newLISTOP X<newLISTOP>, newLOGOP X<newLOGOP>, newLOOPEX X<newLOOPEX>,
-newLOOPOP X<newLOOPOP>, newNULLLIST X<newNULLLIST>, newOP X<newOP>,
-newPADOP X<newPADOP>, newPMOP X<newPMOP>, newPVOP X<newPVOP>, newRANGE
-X<newRANGE>, newSLICEOP X<newSLICEOP>, newSTATEOP X<newSTATEOP>, newSVOP
-X<newSVOP>, newUNOP X<newUNOP>, newWHENOP X<newWHENOP>, newWHILEOP
-X<newWHILEOP>
-
-=item Optree Manipulation Functions
-
-ck_entersub_args_list X<ck_entersub_args_list>, ck_entersub_args_proto
-X<ck_entersub_args_proto>, ck_entersub_args_proto_or_list
-X<ck_entersub_args_proto_or_list>, cv_const_sv X<cv_const_sv>,
-cv_get_call_checker X<cv_get_call_checker>, cv_set_call_checker
-X<cv_set_call_checker>, LINKLIST X<LINKLIST>, newCONSTSUB X<newCONSTSUB>,
-newCONSTSUB_flags X<newCONSTSUB_flags>, newXS X<newXS>, op_append_elem
-X<op_append_elem>, op_append_list X<op_append_list>, OP_CLASS X<OP_CLASS>,
-OP_DESC X<OP_DESC>, op_linklist X<op_linklist>, op_lvalue X<op_lvalue>,
-OP_NAME X<OP_NAME>, op_prepend_elem X<op_prepend_elem>, op_scope
-X<op_scope>, rv2cv_op_cv X<rv2cv_op_cv>
-
-=item Pad Data Structures
-
-CvPADLIST X<CvPADLIST>, pad_add_name_pvs X<pad_add_name_pvs>,
-pad_findmy_pvs X<pad_findmy_pvs>, pad_new X<pad_new>, PL_comppad
-X<PL_comppad>, PL_comppad_name X<PL_comppad_name>, PL_curpad X<PL_curpad>
-
-=item Per-Interpreter Variables
-
-PL_modglobal X<PL_modglobal>, PL_na X<PL_na>, PL_opfreehook
-X<PL_opfreehook>, PL_peepp X<PL_peepp>, PL_rpeepp X<PL_rpeepp>, PL_sv_no
-X<PL_sv_no>, PL_sv_undef X<PL_sv_undef>, PL_sv_yes X<PL_sv_yes>
-
-=item REGEXP Functions
-
-SvRX X<SvRX>, SvRXOK X<SvRXOK>
-
-=item Simple Exception Handling Macros
-
-dXCPT X<dXCPT>, XCPT_CATCH X<XCPT_CATCH>, XCPT_RETHROW X<XCPT_RETHROW>,
-XCPT_TRY_END X<XCPT_TRY_END>, XCPT_TRY_START X<XCPT_TRY_START>
-
-=item Stack Manipulation Macros
-
-dMARK X<dMARK>, dORIGMARK X<dORIGMARK>, dSP X<dSP>, EXTEND X<EXTEND>, MARK
-X<MARK>, mPUSHi X<mPUSHi>, mPUSHn X<mPUSHn>, mPUSHp X<mPUSHp>, mPUSHs
-X<mPUSHs>, mPUSHu X<mPUSHu>, mXPUSHi X<mXPUSHi>, mXPUSHn X<mXPUSHn>,
-mXPUSHp X<mXPUSHp>, mXPUSHs X<mXPUSHs>, mXPUSHu X<mXPUSHu>, ORIGMARK
-X<ORIGMARK>, POPi X<POPi>, POPl X<POPl>, POPn X<POPn>, POPp X<POPp>,
-POPpbytex X<POPpbytex>, POPpx X<POPpx>, POPs X<POPs>, PUSHi X<PUSHi>,
-PUSHMARK X<PUSHMARK>, PUSHmortal X<PUSHmortal>, PUSHn X<PUSHn>, PUSHp
-X<PUSHp>, PUSHs X<PUSHs>, PUSHu X<PUSHu>, PUTBACK X<PUTBACK>, SP X<SP>,
-SPAGAIN X<SPAGAIN>, XPUSHi X<XPUSHi>, XPUSHmortal X<XPUSHmortal>, XPUSHn
-X<XPUSHn>, XPUSHp X<XPUSHp>, XPUSHs X<XPUSHs>, XPUSHu X<XPUSHu>, XSRETURN
-X<XSRETURN>, XSRETURN_EMPTY X<XSRETURN_EMPTY>, XSRETURN_IV X<XSRETURN_IV>,
-XSRETURN_NO X<XSRETURN_NO>, XSRETURN_NV X<XSRETURN_NV>, XSRETURN_PV
-X<XSRETURN_PV>, XSRETURN_UNDEF X<XSRETURN_UNDEF>, XSRETURN_UV
-X<XSRETURN_UV>, XSRETURN_YES X<XSRETURN_YES>, XST_mIV X<XST_mIV>, XST_mNO
-X<XST_mNO>, XST_mNV X<XST_mNV>, XST_mPV X<XST_mPV>, XST_mUNDEF
-X<XST_mUNDEF>, XST_mYES X<XST_mYES>
-
-=item SV Flags
-
-svtype X<svtype>, SVt_IV X<SVt_IV>, SVt_NV X<SVt_NV>, SVt_PV X<SVt_PV>,
-SVt_PVAV X<SVt_PVAV>, SVt_PVCV X<SVt_PVCV>, SVt_PVHV X<SVt_PVHV>, SVt_PVMG
-X<SVt_PVMG>
-
-=item SV Manipulation Functions
-
-boolSV X<boolSV>, croak_xs_usage X<croak_xs_usage>, get_sv X<get_sv>,
-newRV_inc X<newRV_inc>, newSVpvn_utf8 X<newSVpvn_utf8>, SvCUR X<SvCUR>,
-SvCUR_set X<SvCUR_set>, SvEND X<SvEND>, SvGAMAGIC X<SvGAMAGIC>, SvGROW
-X<SvGROW>, SvIOK X<SvIOK>, SvIOKp X<SvIOKp>, SvIOK_notUV X<SvIOK_notUV>,
-SvIOK_off X<SvIOK_off>, SvIOK_on X<SvIOK_on>, SvIOK_only X<SvIOK_only>,
-SvIOK_only_UV X<SvIOK_only_UV>, SvIOK_UV X<SvIOK_UV>, SvIsCOW X<SvIsCOW>,
-SvIsCOW_shared_hash X<SvIsCOW_shared_hash>, SvIV X<SvIV>, SvIVX X<SvIVX>,
-SvIVx X<SvIVx>, SvIV_nomg X<SvIV_nomg>, SvIV_set X<SvIV_set>, SvLEN
-X<SvLEN>, SvLEN_set X<SvLEN_set>, SvMAGIC_set X<SvMAGIC_set>, SvNIOK
-X<SvNIOK>, SvNIOKp X<SvNIOKp>, SvNIOK_off X<SvNIOK_off>, SvNOK X<SvNOK>,
-SvNOKp X<SvNOKp>, SvNOK_off X<SvNOK_off>, SvNOK_on X<SvNOK_on>, SvNOK_only
-X<SvNOK_only>, SvNV X<SvNV>, SvNVX X<SvNVX>, SvNVx X<SvNVx>, SvNV_nomg
-X<SvNV_nomg>, SvNV_set X<SvNV_set>, SvOK X<SvOK>, SvOOK X<SvOOK>,
-SvOOK_offset X<SvOOK_offset>, SvPOK X<SvPOK>, SvPOKp X<SvPOKp>, SvPOK_off
-X<SvPOK_off>, SvPOK_on X<SvPOK_on>, SvPOK_only X<SvPOK_only>,
-SvPOK_only_UTF8 X<SvPOK_only_UTF8>, SvPV X<SvPV>, SvPVbyte X<SvPVbyte>,
-SvPVbytex X<SvPVbytex>, SvPVbytex_force X<SvPVbytex_force>, SvPVbyte_force
-X<SvPVbyte_force>, SvPVbyte_nolen X<SvPVbyte_nolen>, SvPVutf8 X<SvPVutf8>,
-SvPVutf8x X<SvPVutf8x>, SvPVutf8x_force X<SvPVutf8x_force>, SvPVutf8_force
-X<SvPVutf8_force>, SvPVutf8_nolen X<SvPVutf8_nolen>, SvPVX X<SvPVX>, SvPVx
-X<SvPVx>, SvPV_force X<SvPV_force>, SvPV_force_nomg X<SvPV_force_nomg>,
-SvPV_nolen X<SvPV_nolen>, SvPV_nomg X<SvPV_nomg>, SvPV_nomg_nolen
-X<SvPV_nomg_nolen>, SvPV_set X<SvPV_set>, SvREFCNT X<SvREFCNT>,
-SvREFCNT_dec X<SvREFCNT_dec>, SvREFCNT_inc X<SvREFCNT_inc>, SvREFCNT_inc_NN
-X<SvREFCNT_inc_NN>, SvREFCNT_inc_simple X<SvREFCNT_inc_simple>,
-SvREFCNT_inc_simple_NN X<SvREFCNT_inc_simple_NN>, SvREFCNT_inc_simple_void
-X<SvREFCNT_inc_simple_void>, SvREFCNT_inc_simple_void_NN
-X<SvREFCNT_inc_simple_void_NN>, SvREFCNT_inc_void X<SvREFCNT_inc_void>,
-SvREFCNT_inc_void_NN X<SvREFCNT_inc_void_NN>, SvROK X<SvROK>, SvROK_off
-X<SvROK_off>, SvROK_on X<SvROK_on>, SvRV X<SvRV>, SvRV_set X<SvRV_set>,
-SvSTASH X<SvSTASH>, SvSTASH_set X<SvSTASH_set>, SvTAINT X<SvTAINT>,
-SvTAINTED X<SvTAINTED>, SvTAINTED_off X<SvTAINTED_off>, SvTAINTED_on
-X<SvTAINTED_on>, SvTRUE X<SvTRUE>, SvTRUE_nomg X<SvTRUE_nomg>, SvTYPE
-X<SvTYPE>, SvUOK X<SvUOK>, SvUPGRADE X<SvUPGRADE>, SvUTF8 X<SvUTF8>,
-SvUTF8_off X<SvUTF8_off>, SvUTF8_on X<SvUTF8_on>, SvUV X<SvUV>, SvUVX
-X<SvUVX>, SvUVx X<SvUVx>, SvUV_nomg X<SvUV_nomg>, SvUV_set X<SvUV_set>,
-SvVOK X<SvVOK>, sv_catpvn_nomg X<sv_catpvn_nomg>, sv_catpv_nomg
-X<sv_catpv_nomg>, sv_catsv_nomg X<sv_catsv_nomg>, sv_derived_from
-X<sv_derived_from>, sv_derived_from_pv X<sv_derived_from_pv>,
-sv_derived_from_pvn X<sv_derived_from_pvn>, sv_derived_from_sv
-X<sv_derived_from_sv>, sv_does X<sv_does>, sv_does_pv X<sv_does_pv>,
-sv_does_pvn X<sv_does_pvn>, sv_does_sv X<sv_does_sv>, sv_report_used
-X<sv_report_used>, sv_setsv_nomg X<sv_setsv_nomg>, sv_utf8_upgrade_nomg
-X<sv_utf8_upgrade_nomg>
-
-=item SV-Body Allocation
-
-looks_like_number X<looks_like_number>, newRV_noinc X<newRV_noinc>, newSV
-X<newSV>, newSVhek X<newSVhek>, newSViv X<newSViv>, newSVnv X<newSVnv>,
-newSVpv X<newSVpv>, newSVpvf X<newSVpvf>, newSVpvn X<newSVpvn>,
-newSVpvn_flags X<newSVpvn_flags>, newSVpvn_share X<newSVpvn_share>,
-newSVpvs X<newSVpvs>, newSVpvs_flags X<newSVpvs_flags>, newSVpvs_share
-X<newSVpvs_share>, newSVpv_share X<newSVpv_share>, newSVrv X<newSVrv>,
-newSVsv X<newSVsv>, newSVuv X<newSVuv>, newSV_type X<newSV_type>, sv_2bool
-X<sv_2bool>, sv_2bool_flags X<sv_2bool_flags>, sv_2cv X<sv_2cv>, sv_2io
-X<sv_2io>, sv_2iv_flags X<sv_2iv_flags>, sv_2mortal X<sv_2mortal>,
-sv_2nv_flags X<sv_2nv_flags>, sv_2pvbyte X<sv_2pvbyte>, sv_2pvutf8
-X<sv_2pvutf8>, sv_2pv_flags X<sv_2pv_flags>, sv_2uv_flags X<sv_2uv_flags>,
-sv_backoff X<sv_backoff>, sv_bless X<sv_bless>, sv_catpv X<sv_catpv>,
-sv_catpvf X<sv_catpvf>, sv_catpvf_mg X<sv_catpvf_mg>, sv_catpvn
-X<sv_catpvn>, sv_catpvn_flags X<sv_catpvn_flags>, sv_catpvs X<sv_catpvs>,
-sv_catpvs_flags X<sv_catpvs_flags>, sv_catpvs_mg X<sv_catpvs_mg>,
-sv_catpvs_nomg X<sv_catpvs_nomg>, sv_catpv_flags X<sv_catpv_flags>,
-sv_catpv_mg X<sv_catpv_mg>, sv_catsv X<sv_catsv>, sv_catsv_flags
-X<sv_catsv_flags>, sv_chop X<sv_chop>, sv_clear X<sv_clear>, sv_cmp
-X<sv_cmp>, sv_cmp_flags X<sv_cmp_flags>, sv_cmp_locale X<sv_cmp_locale>,
-sv_cmp_locale_flags X<sv_cmp_locale_flags>, sv_collxfrm X<sv_collxfrm>,
-sv_collxfrm_flags X<sv_collxfrm_flags>, sv_copypv X<sv_copypv>, sv_dec
-X<sv_dec>, sv_dec_nomg X<sv_dec_nomg>, sv_eq X<sv_eq>, sv_eq_flags
-X<sv_eq_flags>, sv_force_normal_flags X<sv_force_normal_flags>, sv_free
-X<sv_free>, sv_gets X<sv_gets>, sv_grow X<sv_grow>, sv_inc X<sv_inc>,
-sv_inc_nomg X<sv_inc_nomg>, sv_insert X<sv_insert>, sv_insert_flags
-X<sv_insert_flags>, sv_isa X<sv_isa>, sv_isobject X<sv_isobject>, sv_len
-X<sv_len>, sv_len_utf8 X<sv_len_utf8>, sv_magic X<sv_magic>, sv_magicext
-X<sv_magicext>, sv_mortalcopy X<sv_mortalcopy>, sv_newmortal
-X<sv_newmortal>, sv_newref X<sv_newref>, sv_pos_b2u X<sv_pos_b2u>,
-sv_pos_u2b X<sv_pos_u2b>, sv_pos_u2b_flags X<sv_pos_u2b_flags>,
-sv_pvbyten_force X<sv_pvbyten_force>, sv_pvn_force X<sv_pvn_force>,
-sv_pvn_force_flags X<sv_pvn_force_flags>, sv_pvutf8n_force
-X<sv_pvutf8n_force>, sv_reftype X<sv_reftype>, sv_replace X<sv_replace>,
-sv_reset X<sv_reset>, sv_rvweaken X<sv_rvweaken>, sv_setiv X<sv_setiv>,
-sv_setiv_mg X<sv_setiv_mg>, sv_setnv X<sv_setnv>, sv_setnv_mg
-X<sv_setnv_mg>, sv_setpv X<sv_setpv>, sv_setpvf X<sv_setpvf>, sv_setpvf_mg
-X<sv_setpvf_mg>, sv_setpviv X<sv_setpviv>, sv_setpviv_mg X<sv_setpviv_mg>,
-sv_setpvn X<sv_setpvn>, sv_setpvn_mg X<sv_setpvn_mg>, sv_setpvs
-X<sv_setpvs>, sv_setpvs_mg X<sv_setpvs_mg>, sv_setpv_mg X<sv_setpv_mg>,
-sv_setref_iv X<sv_setref_iv>, sv_setref_nv X<sv_setref_nv>, sv_setref_pv
-X<sv_setref_pv>, sv_setref_pvn X<sv_setref_pvn>, sv_setref_pvs
-X<sv_setref_pvs>, sv_setref_uv X<sv_setref_uv>, sv_setsv X<sv_setsv>,
-sv_setsv_flags X<sv_setsv_flags>, sv_setsv_mg X<sv_setsv_mg>, sv_setuv
-X<sv_setuv>, sv_setuv_mg X<sv_setuv_mg>, sv_tainted X<sv_tainted>, sv_true
-X<sv_true>, sv_unmagic X<sv_unmagic>, sv_unmagicext X<sv_unmagicext>,
-sv_unref_flags X<sv_unref_flags>, sv_untaint X<sv_untaint>, sv_upgrade
-X<sv_upgrade>, sv_usepvn_flags X<sv_usepvn_flags>, sv_utf8_decode
-X<sv_utf8_decode>, sv_utf8_downgrade X<sv_utf8_downgrade>, sv_utf8_encode
-X<sv_utf8_encode>, sv_utf8_upgrade X<sv_utf8_upgrade>,
-sv_utf8_upgrade_flags X<sv_utf8_upgrade_flags>, sv_utf8_upgrade_nomg
-X<sv_utf8_upgrade_nomg>, sv_vcatpvf X<sv_vcatpvf>, sv_vcatpvfn
-X<sv_vcatpvfn>, sv_vcatpvf_mg X<sv_vcatpvf_mg>, sv_vsetpvf X<sv_vsetpvf>,
-sv_vsetpvfn X<sv_vsetpvfn>, sv_vsetpvf_mg X<sv_vsetpvf_mg>
-
-=item Unicode Support
-
-bytes_cmp_utf8 X<bytes_cmp_utf8>, bytes_from_utf8 X<bytes_from_utf8>,
-bytes_to_utf8 X<bytes_to_utf8>, foldEQ_utf8 X<foldEQ_utf8>, is_ascii_string
-X<is_ascii_string>, is_utf8_char X<is_utf8_char>, is_utf8_char_buf
-X<is_utf8_char_buf>, is_utf8_string X<is_utf8_string>, is_utf8_string_loc
-X<is_utf8_string_loc>, is_utf8_string_loclen X<is_utf8_string_loclen>,
-pv_uni_display X<pv_uni_display>, sv_cat_decode X<sv_cat_decode>,
-sv_recode_to_utf8 X<sv_recode_to_utf8>, sv_uni_display X<sv_uni_display>,
-to_utf8_case X<to_utf8_case>, to_utf8_fold X<to_utf8_fold>, to_utf8_lower
-X<to_utf8_lower>, to_utf8_title X<to_utf8_title>, to_utf8_upper
-X<to_utf8_upper>, utf8n_to_uvchr X<utf8n_to_uvchr>, utf8n_to_uvuni
-X<utf8n_to_uvuni>, utf8_distance X<utf8_distance>, utf8_hop X<utf8_hop>,
-utf8_length X<utf8_length>, utf8_to_bytes X<utf8_to_bytes>, utf8_to_uvchr
-X<utf8_to_uvchr>, utf8_to_uvchr_buf X<utf8_to_uvchr_buf>, utf8_to_uvuni
-X<utf8_to_uvuni>, utf8_to_uvuni_buf X<utf8_to_uvuni_buf>, uvchr_to_utf8
-X<uvchr_to_utf8>, uvuni_to_utf8_flags X<uvuni_to_utf8_flags>
-
-=item Variables created by C<xsubpp> and C<xsubpp> internal functions
-
-ax X<ax>, CLASS X<CLASS>, dAX X<dAX>, dAXMARK X<dAXMARK>, dITEMS X<dITEMS>,
-dUNDERBAR X<dUNDERBAR>, dXSARGS X<dXSARGS>, dXSI32 X<dXSI32>, items
-X<items>, ix X<ix>, newXSproto X<newXSproto>, RETVAL X<RETVAL>, ST X<ST>,
-THIS X<THIS>, UNDERBAR X<UNDERBAR>, XS X<XS>, XS_APIVERSION_BOOTCHECK
-X<XS_APIVERSION_BOOTCHECK>, XS_EXTERNAL X<XS_EXTERNAL>, XS_INTERNAL
-X<XS_INTERNAL>, XS_VERSION X<XS_VERSION>, XS_VERSION_BOOTCHECK
-X<XS_VERSION_BOOTCHECK>
-
-=item Warning and Dieing
-
-croak X<croak>, croak_no_modify X<croak_no_modify>, croak_sv X<croak_sv>,
-die X<die>, die_sv X<die_sv>, vcroak X<vcroak>, vwarn X<vwarn>, warn
-X<warn>, warn_sv X<warn_sv>
-
-=item Undocumented functions
-
-GetVars X<GetVars>, Gv_AMupdate X<Gv_AMupdate>, PerlIO_clearerr
-X<PerlIO_clearerr>, PerlIO_close X<PerlIO_close>, PerlIO_context_layers
-X<PerlIO_context_layers>, PerlIO_eof X<PerlIO_eof>, PerlIO_error
-X<PerlIO_error>, PerlIO_fileno X<PerlIO_fileno>, PerlIO_fill
-X<PerlIO_fill>, PerlIO_flush X<PerlIO_flush>, PerlIO_get_base
-X<PerlIO_get_base>, PerlIO_get_bufsiz X<PerlIO_get_bufsiz>, PerlIO_get_cnt
-X<PerlIO_get_cnt>, PerlIO_get_ptr X<PerlIO_get_ptr>, PerlIO_read
-X<PerlIO_read>, PerlIO_seek X<PerlIO_seek>, PerlIO_set_cnt
-X<PerlIO_set_cnt>, PerlIO_set_ptrcnt X<PerlIO_set_ptrcnt>,
-PerlIO_setlinebuf X<PerlIO_setlinebuf>, PerlIO_stderr X<PerlIO_stderr>,
-PerlIO_stdin X<PerlIO_stdin>, PerlIO_stdout X<PerlIO_stdout>, PerlIO_tell
-X<PerlIO_tell>, PerlIO_unread X<PerlIO_unread>, PerlIO_write
-X<PerlIO_write>, Slab_Alloc X<Slab_Alloc>, Slab_Free X<Slab_Free>,
-_is_utf8_quotemeta X<_is_utf8_quotemeta>, amagic_call X<amagic_call>,
-amagic_deref_call X<amagic_deref_call>, any_dup X<any_dup>, atfork_lock
-X<atfork_lock>, atfork_unlock X<atfork_unlock>, av_arylen_p X<av_arylen_p>,
-av_iter_p X<av_iter_p>, block_gimme X<block_gimme>, call_atexit
-X<call_atexit>, call_list X<call_list>, calloc X<calloc>, cast_i32
-X<cast_i32>, cast_iv X<cast_iv>, cast_ulong X<cast_ulong>, cast_uv
-X<cast_uv>, ck_warner X<ck_warner>, ck_warner_d X<ck_warner_d>, ckwarn
-X<ckwarn>, ckwarn_d X<ckwarn_d>, clone_params_del X<clone_params_del>,
-clone_params_new X<clone_params_new>, croak_nocontext X<croak_nocontext>,
-csighandler X<csighandler>, cx_dump X<cx_dump>, cx_dup X<cx_dup>, cxinc
-X<cxinc>, deb X<deb>, deb_nocontext X<deb_nocontext>, debop X<debop>,
-debprofdump X<debprofdump>, debstack X<debstack>, debstackptrs
-X<debstackptrs>, delimcpy X<delimcpy>, despatch_signals
-X<despatch_signals>, die_nocontext X<die_nocontext>, dirp_dup X<dirp_dup>,
-do_aspawn X<do_aspawn>, do_binmode X<do_binmode>, do_close X<do_close>,
-do_gv_dump X<do_gv_dump>, do_gvgv_dump X<do_gvgv_dump>, do_hv_dump
-X<do_hv_dump>, do_join X<do_join>, do_magic_dump X<do_magic_dump>,
-do_op_dump X<do_op_dump>, do_open X<do_open>, do_open9 X<do_open9>,
-do_openn X<do_openn>, do_pmop_dump X<do_pmop_dump>, do_spawn X<do_spawn>,
-do_spawn_nowait X<do_spawn_nowait>, do_sprintf X<do_sprintf>, do_sv_dump
-X<do_sv_dump>, doing_taint X<doing_taint>, doref X<doref>, dounwind
-X<dounwind>, dowantarray X<dowantarray>, dump_all X<dump_all>, dump_eval
-X<dump_eval>, dump_fds X<dump_fds>, dump_form X<dump_form>, dump_indent
-X<dump_indent>, dump_mstats X<dump_mstats>, dump_packsubs X<dump_packsubs>,
-dump_sub X<dump_sub>, dump_vindent X<dump_vindent>, filter_add
-X<filter_add>, filter_del X<filter_del>, filter_read X<filter_read>,
-foldEQ_latin1 X<foldEQ_latin1>, form_nocontext X<form_nocontext>, fp_dup
-X<fp_dup>, fprintf_nocontext X<fprintf_nocontext>, free_global_struct
-X<free_global_struct>, free_tmps X<free_tmps>, get_context X<get_context>,
-get_mstats X<get_mstats>, get_op_descs X<get_op_descs>, get_op_names
-X<get_op_names>, get_ppaddr X<get_ppaddr>, get_vtbl X<get_vtbl>, gp_dup
-X<gp_dup>, gp_free X<gp_free>, gp_ref X<gp_ref>, gv_AVadd X<gv_AVadd>,
-gv_HVadd X<gv_HVadd>, gv_IOadd X<gv_IOadd>, gv_SVadd X<gv_SVadd>,
-gv_add_by_type X<gv_add_by_type>, gv_autoload4 X<gv_autoload4>,
-gv_autoload_pv X<gv_autoload_pv>, gv_autoload_pvn X<gv_autoload_pvn>,
-gv_autoload_sv X<gv_autoload_sv>, gv_check X<gv_check>, gv_dump X<gv_dump>,
-gv_efullname X<gv_efullname>, gv_efullname3 X<gv_efullname3>, gv_efullname4
-X<gv_efullname4>, gv_fetchfile X<gv_fetchfile>, gv_fetchfile_flags
-X<gv_fetchfile_flags>, gv_fetchpv X<gv_fetchpv>, gv_fetchpvn_flags
-X<gv_fetchpvn_flags>, gv_fetchsv X<gv_fetchsv>, gv_fullname X<gv_fullname>,
-gv_fullname3 X<gv_fullname3>, gv_fullname4 X<gv_fullname4>, gv_handler
-X<gv_handler>, gv_name_set X<gv_name_set>, he_dup X<he_dup>, hek_dup
-X<hek_dup>, hv_common X<hv_common>, hv_common_key_len X<hv_common_key_len>,
-hv_delayfree_ent X<hv_delayfree_ent>, hv_eiter_p X<hv_eiter_p>,
-hv_eiter_set X<hv_eiter_set>, hv_free_ent X<hv_free_ent>, hv_ksplit
-X<hv_ksplit>, hv_name_set X<hv_name_set>, hv_placeholders_get
-X<hv_placeholders_get>, hv_placeholders_p X<hv_placeholders_p>,
-hv_placeholders_set X<hv_placeholders_set>, hv_riter_p X<hv_riter_p>,
-hv_riter_set X<hv_riter_set>, init_global_struct X<init_global_struct>,
-init_i18nl10n X<init_i18nl10n>, init_i18nl14n X<init_i18nl14n>, init_stacks
-X<init_stacks>, init_tm X<init_tm>, instr X<instr>, is_lvalue_sub
-X<is_lvalue_sub>, is_uni_alnum X<is_uni_alnum>, is_uni_alnum_lc
-X<is_uni_alnum_lc>, is_uni_alpha X<is_uni_alpha>, is_uni_alpha_lc
-X<is_uni_alpha_lc>, is_uni_ascii X<is_uni_ascii>, is_uni_ascii_lc
-X<is_uni_ascii_lc>, is_uni_cntrl X<is_uni_cntrl>, is_uni_cntrl_lc
-X<is_uni_cntrl_lc>, is_uni_digit X<is_uni_digit>, is_uni_digit_lc
-X<is_uni_digit_lc>, is_uni_graph X<is_uni_graph>, is_uni_graph_lc
-X<is_uni_graph_lc>, is_uni_idfirst X<is_uni_idfirst>, is_uni_idfirst_lc
-X<is_uni_idfirst_lc>, is_uni_lower X<is_uni_lower>, is_uni_lower_lc
-X<is_uni_lower_lc>, is_uni_print X<is_uni_print>, is_uni_print_lc
-X<is_uni_print_lc>, is_uni_punct X<is_uni_punct>, is_uni_punct_lc
-X<is_uni_punct_lc>, is_uni_space X<is_uni_space>, is_uni_space_lc
-X<is_uni_space_lc>, is_uni_upper X<is_uni_upper>, is_uni_upper_lc
-X<is_uni_upper_lc>, is_uni_xdigit X<is_uni_xdigit>, is_uni_xdigit_lc
-X<is_uni_xdigit_lc>, is_utf8_alnum X<is_utf8_alnum>, is_utf8_alpha
-X<is_utf8_alpha>, is_utf8_ascii X<is_utf8_ascii>, is_utf8_cntrl
-X<is_utf8_cntrl>, is_utf8_digit X<is_utf8_digit>, is_utf8_graph
-X<is_utf8_graph>, is_utf8_idcont X<is_utf8_idcont>, is_utf8_idfirst
-X<is_utf8_idfirst>, is_utf8_lower X<is_utf8_lower>, is_utf8_mark
-X<is_utf8_mark>, is_utf8_perl_space X<is_utf8_perl_space>,
-is_utf8_perl_word X<is_utf8_perl_word>, is_utf8_posix_digit
-X<is_utf8_posix_digit>, is_utf8_print X<is_utf8_print>, is_utf8_punct
-X<is_utf8_punct>, is_utf8_space X<is_utf8_space>, is_utf8_upper
-X<is_utf8_upper>, is_utf8_xdigit X<is_utf8_xdigit>, is_utf8_xidcont
-X<is_utf8_xidcont>, is_utf8_xidfirst X<is_utf8_xidfirst>, leave_scope
-X<leave_scope>, load_module_nocontext X<load_module_nocontext>, magic_dump
-X<magic_dump>, malloc X<malloc>, markstack_grow X<markstack_grow>,
-mess_nocontext X<mess_nocontext>, mfree X<mfree>, mg_dup X<mg_dup>, mg_size
-X<mg_size>, mini_mktime X<mini_mktime>, moreswitches X<moreswitches>,
-mro_get_from_name X<mro_get_from_name>, mro_get_private_data
-X<mro_get_private_data>, mro_set_mro X<mro_set_mro>, mro_set_private_data
-X<mro_set_private_data>, my_atof X<my_atof>, my_atof2 X<my_atof2>, my_bcopy
-X<my_bcopy>, my_bzero X<my_bzero>, my_chsize X<my_chsize>, my_cxt_index
-X<my_cxt_index>, my_cxt_init X<my_cxt_init>, my_dirfd X<my_dirfd>, my_exit
-X<my_exit>, my_failure_exit X<my_failure_exit>, my_fflush_all
-X<my_fflush_all>, my_fork X<my_fork>, my_htonl X<my_htonl>, my_lstat
-X<my_lstat>, my_memcmp X<my_memcmp>, my_memset X<my_memset>, my_ntohl
-X<my_ntohl>, my_pclose X<my_pclose>, my_popen X<my_popen>, my_popen_list
-X<my_popen_list>, my_setenv X<my_setenv>, my_socketpair X<my_socketpair>,
-my_stat X<my_stat>, my_strftime X<my_strftime>, my_strlcat X<my_strlcat>,
-my_strlcpy X<my_strlcpy>, my_swap X<my_swap>, newANONATTRSUB
-X<newANONATTRSUB>, newANONHASH X<newANONHASH>, newANONLIST X<newANONLIST>,
-newANONSUB X<newANONSUB>, newATTRSUB X<newATTRSUB>, newAVREF X<newAVREF>,
-newCVREF X<newCVREF>, newFORM X<newFORM>, newGVREF X<newGVREF>, newGVgen
-X<newGVgen>, newGVgen_flags X<newGVgen_flags>, newHVREF X<newHVREF>,
-newHVhv X<newHVhv>, newIO X<newIO>, newMYSUB X<newMYSUB>, newPROG
-X<newPROG>, newRV X<newRV>, newSUB X<newSUB>, newSVREF X<newSVREF>,
-newSVpvf_nocontext X<newSVpvf_nocontext>, new_collate X<new_collate>,
-new_ctype X<new_ctype>, new_numeric X<new_numeric>, new_stackinfo
-X<new_stackinfo>, ninstr X<ninstr>, op_dump X<op_dump>, op_free X<op_free>,
-op_null X<op_null>, op_refcnt_lock X<op_refcnt_lock>, op_refcnt_unlock
-X<op_refcnt_unlock>, parser_dup X<parser_dup>, perl_alloc_using
-X<perl_alloc_using>, perl_clone_using X<perl_clone_using>, pmop_dump
-X<pmop_dump>, pop_scope X<pop_scope>, pregcomp X<pregcomp>, pregexec
-X<pregexec>, pregfree X<pregfree>, pregfree2 X<pregfree2>, printf_nocontext
-X<printf_nocontext>, ptr_table_clear X<ptr_table_clear>, ptr_table_fetch
-X<ptr_table_fetch>, ptr_table_free X<ptr_table_free>, ptr_table_new
-X<ptr_table_new>, ptr_table_split X<ptr_table_split>, ptr_table_store
-X<ptr_table_store>, push_scope X<push_scope>, re_compile X<re_compile>,
-re_dup_guts X<re_dup_guts>, re_intuit_start X<re_intuit_start>,
-re_intuit_string X<re_intuit_string>, realloc X<realloc>, reentrant_free
-X<reentrant_free>, reentrant_init X<reentrant_init>, reentrant_retry
-X<reentrant_retry>, reentrant_size X<reentrant_size>, ref X<ref>,
-reg_named_buff_all X<reg_named_buff_all>, reg_named_buff_exists
-X<reg_named_buff_exists>, reg_named_buff_fetch X<reg_named_buff_fetch>,
-reg_named_buff_firstkey X<reg_named_buff_firstkey>, reg_named_buff_nextkey
-X<reg_named_buff_nextkey>, reg_named_buff_scalar X<reg_named_buff_scalar>,
-regclass_swash X<regclass_swash>, regdump X<regdump>, regdupe_internal
-X<regdupe_internal>, regexec_flags X<regexec_flags>, regfree_internal
-X<regfree_internal>, reginitcolors X<reginitcolors>, regnext X<regnext>,
-repeatcpy X<repeatcpy>, rninstr X<rninstr>, rsignal X<rsignal>,
-rsignal_state X<rsignal_state>, runops_debug X<runops_debug>,
-runops_standard X<runops_standard>, rvpv_dup X<rvpv_dup>, safesyscalloc
-X<safesyscalloc>, safesysfree X<safesysfree>, safesysmalloc
-X<safesysmalloc>, safesysrealloc X<safesysrealloc>, save_I16 X<save_I16>,
-save_I32 X<save_I32>, save_I8 X<save_I8>, save_adelete X<save_adelete>,
-save_aelem X<save_aelem>, save_aelem_flags X<save_aelem_flags>, save_alloc
-X<save_alloc>, save_aptr X<save_aptr>, save_ary X<save_ary>, save_bool
-X<save_bool>, save_clearsv X<save_clearsv>, save_delete X<save_delete>,
-save_destructor X<save_destructor>, save_destructor_x X<save_destructor_x>,
-save_freeop X<save_freeop>, save_freepv X<save_freepv>, save_freesv
-X<save_freesv>, save_generic_pvref X<save_generic_pvref>,
-save_generic_svref X<save_generic_svref>, save_gp X<save_gp>, save_hash
-X<save_hash>, save_hdelete X<save_hdelete>, save_helem X<save_helem>,
-save_helem_flags X<save_helem_flags>, save_hints X<save_hints>, save_hptr
-X<save_hptr>, save_int X<save_int>, save_item X<save_item>, save_iv
-X<save_iv>, save_list X<save_list>, save_long X<save_long>,
-save_mortalizesv X<save_mortalizesv>, save_nogv X<save_nogv>, save_op
-X<save_op>, save_padsv_and_mortalize X<save_padsv_and_mortalize>, save_pptr
-X<save_pptr>, save_pushi32ptr X<save_pushi32ptr>, save_pushptr
-X<save_pushptr>, save_pushptrptr X<save_pushptrptr>, save_re_context
-X<save_re_context>, save_scalar X<save_scalar>, save_set_svflags
-X<save_set_svflags>, save_shared_pvref X<save_shared_pvref>, save_sptr
-X<save_sptr>, save_svref X<save_svref>, save_vptr X<save_vptr>,
-savestack_grow X<savestack_grow>, savestack_grow_cnt X<savestack_grow_cnt>,
-scan_num X<scan_num>, scan_vstring X<scan_vstring>, screaminstr
-X<screaminstr>, seed X<seed>, set_context X<set_context>, set_numeric_local
-X<set_numeric_local>, set_numeric_radix X<set_numeric_radix>,
-set_numeric_standard X<set_numeric_standard>, share_hek X<share_hek>,
-si_dup X<si_dup>, ss_dup X<ss_dup>, stack_grow X<stack_grow>,
-start_subparse X<start_subparse>, stashpv_hvname_match
-X<stashpv_hvname_match>, str_to_version X<str_to_version>, sv_2iv
-X<sv_2iv>, sv_2pv X<sv_2pv>, sv_2uv X<sv_2uv>, sv_catpvf_mg_nocontext
-X<sv_catpvf_mg_nocontext>, sv_catpvf_nocontext X<sv_catpvf_nocontext>,
-sv_compile_2op X<sv_compile_2op>, sv_dump X<sv_dump>, sv_dup X<sv_dup>,
-sv_dup_inc X<sv_dup_inc>, sv_peek X<sv_peek>, sv_pvn_nomg X<sv_pvn_nomg>,
-sv_setpvf_mg_nocontext X<sv_setpvf_mg_nocontext>, sv_setpvf_nocontext
-X<sv_setpvf_nocontext>, sv_utf8_upgrade_flags_grow
-X<sv_utf8_upgrade_flags_grow>, swash_fetch X<swash_fetch>, swash_init
-X<swash_init>, sys_init X<sys_init>, sys_init3 X<sys_init3>,
-sys_intern_clear X<sys_intern_clear>, sys_intern_dup X<sys_intern_dup>,
-sys_intern_init X<sys_intern_init>, sys_term X<sys_term>, taint_env
-X<taint_env>, taint_proper X<taint_proper>, tmps_grow X<tmps_grow>,
-to_uni_fold X<to_uni_fold>, to_uni_lower X<to_uni_lower>, to_uni_lower_lc
-X<to_uni_lower_lc>, to_uni_title X<to_uni_title>, to_uni_title_lc
-X<to_uni_title_lc>, to_uni_upper X<to_uni_upper>, to_uni_upper_lc
-X<to_uni_upper_lc>, unlnk X<unlnk>, unsharepvn X<unsharepvn>, utf16_to_utf8
-X<utf16_to_utf8>, utf16_to_utf8_reversed X<utf16_to_utf8_reversed>,
-uvchr_to_utf8_flags X<uvchr_to_utf8_flags>, uvuni_to_utf8 X<uvuni_to_utf8>,
-vdeb X<vdeb>, vform X<vform>, vload_module X<vload_module>, vnewSVpvf
-X<vnewSVpvf>, vwarner X<vwarner>, warn_nocontext X<warn_nocontext>, warner
-X<warner>, warner_nocontext X<warner_nocontext>, whichsig X<whichsig>,
-whichsig_pv X<whichsig_pv>, whichsig_pvn X<whichsig_pvn>, whichsig_sv
-X<whichsig_sv>
-
-=item AUTHORS
-
-=item SEE ALSO
-
-=back
-
-=head2 perlintern - autogenerated documentation of purely B<internal>
- Perl functions
-
-=over 4
-
-=item DESCRIPTION
-X<internal Perl functions> X<interpreter functions>
-
-=item Compile-time scope hooks
-
-BhkENTRY X<BhkENTRY>, BhkFLAGS X<BhkFLAGS>, CALL_BLOCK_HOOKS
-X<CALL_BLOCK_HOOKS>
-
-=item CV reference counts and CvOUTSIDE
-
-CvWEAKOUTSIDE X<CvWEAKOUTSIDE>
-
-=item Embedding Functions
-
-cv_dump X<cv_dump>, do_dump_pad X<do_dump_pad>, intro_my X<intro_my>,
-padlist_dup X<padlist_dup>, pad_alloc_name X<pad_alloc_name>,
-pad_block_start X<pad_block_start>, pad_check_dup X<pad_check_dup>,
-pad_findlex X<pad_findlex>, pad_fixup_inner_anons X<pad_fixup_inner_anons>,
-pad_free X<pad_free>, pad_leavemy X<pad_leavemy>, pad_push X<pad_push>,
-pad_reset X<pad_reset>, pad_swipe X<pad_swipe>
-
-=item Functions in file op.c
-
-core_prototype X<core_prototype>
-
-=item Functions in file pp_ctl.c
-
-docatch X<docatch>
-
-=item GV Functions
-
-gv_try_downgrade X<gv_try_downgrade>
-
-=item Hash Manipulation Functions
-
-hv_ename_add X<hv_ename_add>, hv_ename_delete X<hv_ename_delete>,
-refcounted_he_chain_2hv X<refcounted_he_chain_2hv>, refcounted_he_fetch_pv
-X<refcounted_he_fetch_pv>, refcounted_he_fetch_pvn
-X<refcounted_he_fetch_pvn>, refcounted_he_fetch_pvs
-X<refcounted_he_fetch_pvs>, refcounted_he_fetch_sv
-X<refcounted_he_fetch_sv>, refcounted_he_free X<refcounted_he_free>,
-refcounted_he_inc X<refcounted_he_inc>, refcounted_he_new_pv
-X<refcounted_he_new_pv>, refcounted_he_new_pvn X<refcounted_he_new_pvn>,
-refcounted_he_new_pvs X<refcounted_he_new_pvs>, refcounted_he_new_sv
-X<refcounted_he_new_sv>
-
-=item IO Functions
-
-start_glob X<start_glob>
-
-=item Magical Functions
-
-magic_clearhint X<magic_clearhint>, magic_clearhints X<magic_clearhints>,
-magic_methcall X<magic_methcall>, magic_sethint X<magic_sethint>,
-mg_localize X<mg_localize>
-
-=item MRO Functions
-
-mro_get_linear_isa_dfs X<mro_get_linear_isa_dfs>, mro_isa_changed_in
-X<mro_isa_changed_in>, mro_package_moved X<mro_package_moved>
-
-=item Optree Manipulation Functions
-
-finalize_optree X<finalize_optree>
-
-=item Pad Data Structures
-
-CX_CURPAD_SAVE X<CX_CURPAD_SAVE>, CX_CURPAD_SV X<CX_CURPAD_SV>, PAD_BASE_SV
-X<PAD_BASE_SV>, PAD_CLONE_VARS X<PAD_CLONE_VARS>, PAD_COMPNAME_FLAGS
-X<PAD_COMPNAME_FLAGS>, PAD_COMPNAME_GEN X<PAD_COMPNAME_GEN>,
-PAD_COMPNAME_GEN_set X<PAD_COMPNAME_GEN_set>, PAD_COMPNAME_OURSTASH
-X<PAD_COMPNAME_OURSTASH>, PAD_COMPNAME_PV X<PAD_COMPNAME_PV>,
-PAD_COMPNAME_TYPE X<PAD_COMPNAME_TYPE>, pad_peg X<pad_peg>,
-PAD_RESTORE_LOCAL X<PAD_RESTORE_LOCAL>, PAD_SAVE_LOCAL X<PAD_SAVE_LOCAL>,
-PAD_SAVE_SETNULLPAD X<PAD_SAVE_SETNULLPAD>, PAD_SETSV X<PAD_SETSV>,
-PAD_SET_CUR X<PAD_SET_CUR>, PAD_SET_CUR_NOSAVE X<PAD_SET_CUR_NOSAVE>,
-PAD_SV X<PAD_SV>, PAD_SVl X<PAD_SVl>, SAVECLEARSV X<SAVECLEARSV>,
-SAVECOMPPAD X<SAVECOMPPAD>, SAVEPADSV X<SAVEPADSV>
-
-=item Per-Interpreter Variables
-
-PL_DBsingle X<PL_DBsingle>, PL_DBsub X<PL_DBsub>, PL_DBtrace X<PL_DBtrace>,
-PL_dowarn X<PL_dowarn>, PL_last_in_gv X<PL_last_in_gv>, PL_ofsgv
-X<PL_ofsgv>, PL_rs X<PL_rs>
-
-=item Stack Manipulation Macros
-
-djSP X<djSP>, LVRET X<LVRET>
-
-=item SV Manipulation Functions
-
-sv_add_arena X<sv_add_arena>, sv_clean_all X<sv_clean_all>, sv_clean_objs
-X<sv_clean_objs>, sv_free_arenas X<sv_free_arenas>
-
-=item SV-Body Allocation
-
-sv_2num X<sv_2num>, sv_ref X<sv_ref>
-
-=item Unicode Support
-
-find_uninit_var X<find_uninit_var>, report_uninit X<report_uninit>
-
-=item Undocumented functions
-
-_add_range_to_invlist X<_add_range_to_invlist>, _core_swash_init
-X<_core_swash_init>, _invlist_array_init X<_invlist_array_init>,
-_invlist_contents X<_invlist_contents>, _invlist_intersection
-X<_invlist_intersection>, _invlist_intersection_maybe_complement_2nd
-X<_invlist_intersection_maybe_complement_2nd>, _invlist_invert
-X<_invlist_invert>, _invlist_invert_prop X<_invlist_invert_prop>,
-_invlist_populate_swatch X<_invlist_populate_swatch>, _invlist_subtract
-X<_invlist_subtract>, _invlist_union X<_invlist_union>,
-_invlist_union_maybe_complement_2nd X<_invlist_union_maybe_complement_2nd>,
-_is_utf8__perl_idstart X<_is_utf8__perl_idstart>, _new_invlist
-X<_new_invlist>, _swash_inversion_hash X<_swash_inversion_hash>,
-_swash_to_invlist X<_swash_to_invlist>, _to_fold_latin1 X<_to_fold_latin1>,
-_to_upper_title_latin1 X<_to_upper_title_latin1>, aassign_common_vars
-X<aassign_common_vars>, add_cp_to_invlist X<add_cp_to_invlist>, addmad
-X<addmad>, allocmy X<allocmy>, amagic_is_enabled X<amagic_is_enabled>,
-append_madprops X<append_madprops>, apply X<apply>, av_reify X<av_reify>,
-bind_match X<bind_match>, block_end X<block_end>, block_start
-X<block_start>, boot_core_PerlIO X<boot_core_PerlIO>, boot_core_UNIVERSAL
-X<boot_core_UNIVERSAL>, boot_core_mro X<boot_core_mro>, cando X<cando>,
-check_utf8_print X<check_utf8_print>, ck_entersub_args_core
-X<ck_entersub_args_core>, convert X<convert>, coresub_op X<coresub_op>,
-create_eval_scope X<create_eval_scope>, cv_ckproto_len_flags
-X<cv_ckproto_len_flags>, cvgv_set X<cvgv_set>, cvstash_set X<cvstash_set>,
-deb_stack_all X<deb_stack_all>, delete_eval_scope X<delete_eval_scope>,
-die_unwind X<die_unwind>, do_aexec X<do_aexec>, do_aexec5 X<do_aexec5>,
-do_eof X<do_eof>, do_exec X<do_exec>, do_exec3 X<do_exec3>, do_execfree
-X<do_execfree>, do_ipcctl X<do_ipcctl>, do_ipcget X<do_ipcget>, do_msgrcv
-X<do_msgrcv>, do_msgsnd X<do_msgsnd>, do_ncmp X<do_ncmp>, do_op_xmldump
-X<do_op_xmldump>, do_pmop_xmldump X<do_pmop_xmldump>, do_print X<do_print>,
-do_readline X<do_readline>, do_seek X<do_seek>, do_semop X<do_semop>,
-do_shmio X<do_shmio>, do_sysseek X<do_sysseek>, do_tell X<do_tell>,
-do_trans X<do_trans>, do_vecget X<do_vecget>, do_vecset X<do_vecset>,
-do_vop X<do_vop>, dofile X<dofile>, dump_all_perl X<dump_all_perl>,
-dump_packsubs_perl X<dump_packsubs_perl>, dump_sub_perl X<dump_sub_perl>,
-dump_sv_child X<dump_sv_child>, emulate_cop_io X<emulate_cop_io>,
-feature_is_enabled X<feature_is_enabled>, find_rundefsv2 X<find_rundefsv2>,
-find_script X<find_script>, free_tied_hv_pool X<free_tied_hv_pool>,
-get_db_sub X<get_db_sub>, get_debug_opts X<get_debug_opts>, get_hash_seed
-X<get_hash_seed>, get_invlist_iter_addr X<get_invlist_iter_addr>,
-get_invlist_len_addr X<get_invlist_len_addr>, get_invlist_version_id_addr
-X<get_invlist_version_id_addr>, get_invlist_zero_addr
-X<get_invlist_zero_addr>, get_no_modify X<get_no_modify>, get_opargs
-X<get_opargs>, get_re_arg X<get_re_arg>, getenv_len X<getenv_len>,
-hfree_next_entry X<hfree_next_entry>, hv_backreferences_p
-X<hv_backreferences_p>, hv_kill_backrefs X<hv_kill_backrefs>,
-hv_undef_flags X<hv_undef_flags>, init_argv_symbols X<init_argv_symbols>,
-init_dbargs X<init_dbargs>, init_debugger X<init_debugger>, invert
-X<invert>, invlist_array X<invlist_array>, invlist_clone X<invlist_clone>,
-invlist_iterinit X<invlist_iterinit>, invlist_len X<invlist_len>,
-invlist_max X<invlist_max>, invlist_set_len X<invlist_set_len>,
-invlist_trim X<invlist_trim>, io_close X<io_close>, is_utf8_X_L
-X<is_utf8_X_L>, is_utf8_X_LV X<is_utf8_X_LV>, is_utf8_X_LVT
-X<is_utf8_X_LVT>, is_utf8_X_LV_LVT_V X<is_utf8_X_LV_LVT_V>, is_utf8_X_T
-X<is_utf8_X_T>, is_utf8_X_V X<is_utf8_X_V>, is_utf8_X_begin
-X<is_utf8_X_begin>, is_utf8_X_extend X<is_utf8_X_extend>,
-is_utf8_X_non_hangul X<is_utf8_X_non_hangul>, is_utf8_X_prepend
-X<is_utf8_X_prepend>, jmaybe X<jmaybe>, keyword X<keyword>,
-keyword_plugin_standard X<keyword_plugin_standard>, list X<list>, localize
-X<localize>, mad_free X<mad_free>, madlex X<madlex>, madparse X<madparse>,
-magic_clear_all_env X<magic_clear_all_env>, magic_clearenv
-X<magic_clearenv>, magic_clearisa X<magic_clearisa>, magic_clearpack
-X<magic_clearpack>, magic_clearsig X<magic_clearsig>, magic_existspack
-X<magic_existspack>, magic_freearylen_p X<magic_freearylen_p>,
-magic_freeovrld X<magic_freeovrld>, magic_get X<magic_get>, magic_getarylen
-X<magic_getarylen>, magic_getdefelem X<magic_getdefelem>, magic_getnkeys
-X<magic_getnkeys>, magic_getpack X<magic_getpack>, magic_getpos
-X<magic_getpos>, magic_getsig X<magic_getsig>, magic_getsubstr
-X<magic_getsubstr>, magic_gettaint X<magic_gettaint>, magic_getuvar
-X<magic_getuvar>, magic_getvec X<magic_getvec>, magic_killbackrefs
-X<magic_killbackrefs>, magic_len X<magic_len>, magic_nextpack
-X<magic_nextpack>, magic_regdata_cnt X<magic_regdata_cnt>,
-magic_regdatum_get X<magic_regdatum_get>, magic_regdatum_set
-X<magic_regdatum_set>, magic_scalarpack X<magic_scalarpack>, magic_set
-X<magic_set>, magic_set_all_env X<magic_set_all_env>, magic_setamagic
-X<magic_setamagic>, magic_setarylen X<magic_setarylen>, magic_setcollxfrm
-X<magic_setcollxfrm>, magic_setdbline X<magic_setdbline>, magic_setdefelem
-X<magic_setdefelem>, magic_setenv X<magic_setenv>, magic_setisa
-X<magic_setisa>, magic_setmglob X<magic_setmglob>, magic_setnkeys
-X<magic_setnkeys>, magic_setpack X<magic_setpack>, magic_setpos
-X<magic_setpos>, magic_setregexp X<magic_setregexp>, magic_setsig
-X<magic_setsig>, magic_setsubstr X<magic_setsubstr>, magic_settaint
-X<magic_settaint>, magic_setutf8 X<magic_setutf8>, magic_setuvar
-X<magic_setuvar>, magic_setvec X<magic_setvec>, magic_setvstring
-X<magic_setvstring>, magic_sizepack X<magic_sizepack>, magic_wipepack
-X<magic_wipepack>, malloc_good_size X<malloc_good_size>, malloced_size
-X<malloced_size>, mem_collxfrm X<mem_collxfrm>, mode_from_discipline
-X<mode_from_discipline>, more_bodies X<more_bodies>, mro_meta_dup
-X<mro_meta_dup>, mro_meta_init X<mro_meta_init>, munge_qwlist_to_paren_list
-X<munge_qwlist_to_paren_list>, my_attrs X<my_attrs>, my_betoh16
-X<my_betoh16>, my_betoh32 X<my_betoh32>, my_betoh64 X<my_betoh64>,
-my_betohi X<my_betohi>, my_betohl X<my_betohl>, my_betohs X<my_betohs>,
-my_clearenv X<my_clearenv>, my_htobe16 X<my_htobe16>, my_htobe32
-X<my_htobe32>, my_htobe64 X<my_htobe64>, my_htobei X<my_htobei>, my_htobel
-X<my_htobel>, my_htobes X<my_htobes>, my_htole16 X<my_htole16>, my_htole32
-X<my_htole32>, my_htole64 X<my_htole64>, my_htolei X<my_htolei>, my_htolel
-X<my_htolel>, my_htoles X<my_htoles>, my_letoh16 X<my_letoh16>, my_letoh32
-X<my_letoh32>, my_letoh64 X<my_letoh64>, my_letohi X<my_letohi>, my_letohl
-X<my_letohl>, my_letohs X<my_letohs>, my_lstat_flags X<my_lstat_flags>,
-my_stat_flags X<my_stat_flags>, my_swabn X<my_swabn>, my_unexec
-X<my_unexec>, newATTRSUB_flags X<newATTRSUB_flags>, newGP X<newGP>,
-newMADPROP X<newMADPROP>, newMADsv X<newMADsv>, newTOKEN X<newTOKEN>,
-newXS_len_flags X<newXS_len_flags>, new_warnings_bitfield
-X<new_warnings_bitfield>, nextargv X<nextargv>, oopsAV X<oopsAV>, oopsHV
-X<oopsHV>, op_clear X<op_clear>, op_const_sv X<op_const_sv>, op_getmad
-X<op_getmad>, op_getmad_weak X<op_getmad_weak>, op_integerize
-X<op_integerize>, op_lvalue_flags X<op_lvalue_flags>, op_refcnt_dec
-X<op_refcnt_dec>, op_refcnt_inc X<op_refcnt_inc>, op_std_init
-X<op_std_init>, op_xmldump X<op_xmldump>, package X<package>,
-package_version X<package_version>, parse_unicode_opts
-X<parse_unicode_opts>, parser_free X<parser_free>, peep X<peep>,
-pending_Slabs_to_ro X<pending_Slabs_to_ro>, pmop_xmldump X<pmop_xmldump>,
-pmruntime X<pmruntime>, populate_isa X<populate_isa>, prepend_madprops
-X<prepend_madprops>, qerror X<qerror>, reg_named_buff X<reg_named_buff>,
-reg_named_buff_iter X<reg_named_buff_iter>, reg_numbered_buff_fetch
-X<reg_numbered_buff_fetch>, reg_numbered_buff_length
-X<reg_numbered_buff_length>, reg_numbered_buff_store
-X<reg_numbered_buff_store>, reg_qr_package X<reg_qr_package>, reg_temp_copy
-X<reg_temp_copy>, regcurly X<regcurly>, regprop X<regprop>, report_evil_fh
-X<report_evil_fh>, report_redefined_cv X<report_redefined_cv>,
-report_wrongway_fh X<report_wrongway_fh>, rpeep X<rpeep>, rsignal_restore
-X<rsignal_restore>, rsignal_save X<rsignal_save>, rxres_save X<rxres_save>,
-same_dirent X<same_dirent>, sawparens X<sawparens>, scalar X<scalar>,
-scalarvoid X<scalarvoid>, set_regclass_bit X<set_regclass_bit>, sighandler
-X<sighandler>, softref2xv X<softref2xv>, sub_crush_depth
-X<sub_crush_depth>, sv_add_backref X<sv_add_backref>, sv_catxmlpv
-X<sv_catxmlpv>, sv_catxmlpvn X<sv_catxmlpvn>, sv_catxmlsv X<sv_catxmlsv>,
-sv_compile_2op_is_broken X<sv_compile_2op_is_broken>, sv_del_backref
-X<sv_del_backref>, sv_free2 X<sv_free2>, sv_kill_backrefs
-X<sv_kill_backrefs>, sv_sethek X<sv_sethek>, sv_setsv_cow X<sv_setsv_cow>,
-sv_unglob X<sv_unglob>, sv_xmlpeek X<sv_xmlpeek>, tied_method
-X<tied_method>, token_free X<token_free>, token_getmad X<token_getmad>,
-translate_substr_offsets X<translate_substr_offsets>, try_amagic_bin
-X<try_amagic_bin>, try_amagic_un X<try_amagic_un>, unshare_hek
-X<unshare_hek>, utilize X<utilize>, varname X<varname>, vivify_defelem
-X<vivify_defelem>, vivify_ref X<vivify_ref>, wait4pid X<wait4pid>,
-was_lvalue_sub X<was_lvalue_sub>, watch X<watch>, write_to_stderr
-X<write_to_stderr>, xmldump_all X<xmldump_all>, xmldump_all_perl
-X<xmldump_all_perl>, xmldump_eval X<xmldump_eval>, xmldump_form
-X<xmldump_form>, xmldump_indent X<xmldump_indent>, xmldump_packsubs
-X<xmldump_packsubs>, xmldump_packsubs_perl X<xmldump_packsubs_perl>,
-xmldump_sub X<xmldump_sub>, xmldump_sub_perl X<xmldump_sub_perl>,
-xmldump_vindent X<xmldump_vindent>, xs_apiversion_bootcheck
-X<xs_apiversion_bootcheck>, xs_version_bootcheck X<xs_version_bootcheck>,
-yyerror X<yyerror>, yyerror_pv X<yyerror_pv>, yyerror_pvn X<yyerror_pvn>,
-yylex X<yylex>, yyparse X<yyparse>, yyunlex X<yyunlex>
-
-=item AUTHORS
-
-=item SEE ALSO
-
-=back
-
-=head2 perliol - C API for Perl's implementation of IO in Layers.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item History and Background
-
-=item Basic Structure
-
-=item Layers vs Disciplines
-
-=item Data Structures
-
-=item Functions and Attributes
-
-=item Per-instance Data
-
-=item Layers in action.
-
-=item Per-instance flag bits
-
-PERLIO_F_EOF, PERLIO_F_CANWRITE, PERLIO_F_CANREAD, PERLIO_F_ERROR,
-PERLIO_F_TRUNCATE, PERLIO_F_APPEND, PERLIO_F_CRLF, PERLIO_F_UTF8,
-PERLIO_F_UNBUF, PERLIO_F_WRBUF, PERLIO_F_RDBUF, PERLIO_F_LINEBUF,
-PERLIO_F_TEMP, PERLIO_F_OPEN, PERLIO_F_FASTGETS
-
-=item Methods in Detail
-
-fsize, name, size, kind, PERLIO_K_BUFFERED, PERLIO_K_RAW, PERLIO_K_CANCRLF,
-PERLIO_K_FASTGETS, PERLIO_K_MULTIARG, Pushed, Popped, Open, Binmode,
-Getarg, Fileno, Dup, Read, Write, Seek, Tell, Close, Flush, Fill, Eof,
-Error, Clearerr, Setlinebuf, Get_base, Get_bufsiz, Get_ptr, Get_cnt,
-Set_ptrcnt
-
-=item Utilities
-
-=item Implementing PerlIO Layers
-
-C implementations, Perl implementations
-
-=item Core Layers
-
-"unix", "perlio", "stdio", "crlf", "mmap", "pending", "raw", "utf8"
-
-=item Extension Layers
-
-":encoding", ":scalar", ":via"
-
-=back
-
-=item TODO
-
-=back
-
-=head2 perlapio - perl's IO abstraction interface.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-1. USE_STDIO, 2. USE_SFIO, 3. USE_PERLIO, B<PerlIO_stdin()>,
-B<PerlIO_stdout()>, B<PerlIO_stderr()>, B<PerlIO_open(path, mode)>,
-B<PerlIO_fdopen(fd,mode)>, B<PerlIO_reopen(path,mode,f)>,
-B<PerlIO_printf(f,fmt,...)>, B<PerlIO_vprintf(f,fmt,a)>,
-B<PerlIO_stdoutf(fmt,...)>, B<PerlIO_read(f,buf,count)>,
-B<PerlIO_write(f,buf,count)>, B<PerlIO_close(f)>, B<PerlIO_puts(f,s)>,
-B<PerlIO_putc(f,c)>, B<PerlIO_ungetc(f,c)>, B<PerlIO_getc(f)>,
-B<PerlIO_eof(f)>, B<PerlIO_error(f)>, B<PerlIO_fileno(f)>,
-B<PerlIO_clearerr(f)>, B<PerlIO_flush(f)>, B<PerlIO_seek(f,offset,whence)>,
-B<PerlIO_tell(f)>, B<PerlIO_getpos(f,p)>, B<PerlIO_setpos(f,p)>,
-B<PerlIO_rewind(f)>, B<PerlIO_tmpfile()>, B<PerlIO_setlinebuf(f)>
-
-=over 4
-
-=item Co-existence with stdio
-
-B<PerlIO_importFILE(f,mode)>, B<PerlIO_exportFILE(f,mode)>,
-B<PerlIO_releaseFILE(p,f)>, B<PerlIO_findFILE(f)>
-
-=item "Fast gets" Functions
-
-B<PerlIO_fast_gets(f)>, B<PerlIO_has_cntptr(f)>, B<PerlIO_get_cnt(f)>,
-B<PerlIO_get_ptr(f)>, B<PerlIO_set_ptrcnt(f,p,c)>, B<PerlIO_canset_cnt(f)>,
-B<PerlIO_set_cnt(f,c)>, B<PerlIO_has_base(f)>, B<PerlIO_get_base(f)>,
-B<PerlIO_get_bufsiz(f)>
-
-=item Other Functions
-
-PerlIO_apply_layers(f,mode,layers), PerlIO_binmode(f,ptype,imode,layers),
-'E<lt>' read, 'E<gt>' write, '+' read/write, PerlIO_debug(fmt,...)
-
-=back
-
-=back
-
-=head2 perlhack - How to hack on Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=item SUPER QUICK PATCH GUIDE
-
-Check out the source repository, Make your change, Test your change, Commit
-your change, Send your change to perlbug, Thank you
-
-=item BUG REPORTING
-
-=item PERL 5 PORTERS
-
-=over 4
-
-=item perl-changes mailing list
-
-=item #p5p on IRC
-
-=back
-
-=item GETTING THE PERL SOURCE
-
-=over 4
-
-=item Read access via Git
-
-=item Read access via the web
-
-=item Read access via rsync
-
-=item Write access via git
-
-=back
-
-=item PATCHING PERL
-
-=over 4
-
-=item Submitting patches
-
-=item Getting your patch accepted
-
-Why, What, How
-
-=item Patching a core module
-
-=item Updating perldelta
-
-=item What makes for a good patch?
-
-=back
-
-=item TESTING
-
-F<t/base> and F<t/comp>, F<t/cmd>, F<t/run>, F<t/io> and F<t/op>,
-Everything else
-
-=over 4
-
-=item Special C<make test> targets
-
-test_porting, coretest, test.deparse, test.taintwarn, minitest,
-test.valgrind check.valgrind utest.valgrind ucheck.valgrind, test.torture
-torturetest, utest ucheck test.utf8 check.utf8, minitest.utf16 test.utf16,
-test_harness, test-notty test_notty
-
-=item Parallel tests
-
-=item Running tests by hand
-
-=item Using F<t/harness> for testing
-
--v, -torture, -re=PATTERN, -re LIST OF PATTERNS, PERL_CORE=1,
-PERL_DESTRUCT_LEVEL=2, PERL, PERL_SKIP_TTY_TEST, PERL_TEST_Net_Ping,
-PERL_TEST_NOVREXX, PERL_TEST_NUMCONVERTS
-
-=back
-
-=item MORE READING FOR GUTS HACKERS
-
-L<perlsource>, L<perlinterp>, L<perlhacktut>, L<perlhacktips>, L<perlguts>,
-L<perlxstut> and L<perlxs>, L<perlapi>, F<Porting/pumpkin.pod>, The
-perl5-porters FAQ
-
-=item CPAN TESTERS AND PERL SMOKERS
-
-=item WHAT NEXT?
-
-=over 4
-
-=item "The Road goes ever on and on, down from the door where it began."
-
-=item Metaphoric Quotations
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 perlsource - A guide to the Perl source tree
-
-=over 4
-
-=item DESCRIPTION
-
-=item FINDING YOUR WAY AROUND
-
-=over 4
-
-=item C code
-
-=item Core modules
-
-F<lib/>, F<ext/>, F<dist/>, F<cpan/>
-
-=item Tests
-
-Module tests, F<t/base/>, F<t/cmd/>, F<t/comp/>, F<t/io/>, F<t/mro/>,
-F<t/op/>, F<t/re/>, F<t/run/>, F<t/uni/>, F<t/win32/>, F<t/porting/>,
-F<t/lib/>, F<t/x2p>
-
-=item Documentation
-
-=item Hacking tools and documentation
-
-F<check*>, F<Maintainers>, F<Maintainers.pl>, and F<Maintainers.pm>,
-F<podtidy>
-
-=item Build system
-
-=item F<AUTHORS>
-
-=item F<MANIFEST>
-
-=back
-
-=back
-
-=head2 perlinterp - An overview of the Perl interpreter
-
-=over 4
-
-=item DESCRIPTION
-
-=item ELEMENTS OF THE INTERPRETER
-
-=over 4
-
-=item Startup
-
-=item Parsing
-
-=item Optimization
-
-=item Running
-
-=item Exception handing
-
-=item INTERNAL VARIABLE TYPES
-
-=back
-
-=item OP TREES
-
-=item STACKS
-
-=over 4
-
-=item Argument stack
-
-=item Mark stack
-
-=item Save stack
-
-=back
-
-=item MILLIONS OF MACROS
-
-=item FURTHER READING
-
-=back
-
-=head2 perlhacktut - Walk through the creation of a simple C code patch
-
-=over 4
-
-=item DESCRIPTION
-
-=item EXAMPLE OF A SIMPLE PATCH
-
-=over 4
-
-=item Writing the patch
-
-=item Testing the patch
-
-=item Documenting the patch
-
-=item Submit
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 perlhacktips - Tips for Perl core C code hacking
-
-=over 4
-
-=item DESCRIPTION
-
-=item COMMON PROBLEMS
-
-=over 4
-
-=item Perl environment problems
-
-=item Portability problems
-
-=item Problematic System Interfaces
-
-=item Security problems
-
-=back
-
-=item DEBUGGING
-
-=over 4
-
-=item Poking at Perl
-
-=item Using a source-level debugger
-
-run [args], break function_name, break source.c:xxx, step, next, continue,
-finish, 'enter', print
-
-=item gdb macro support
-
-=item Dumping Perl Data Structures
-
-=back
-
-=item SOURCE CODE STATIC ANALYSIS
-
-=over 4
-
-=item lint, splint
-
-=item Coverity
-
-=item cpd (cut-and-paste detector)
-
-=item gcc warnings
-
-=item Warnings of other C compilers
-
-=back
-
-=item MEMORY DEBUGGERS
-
-=over 4
-
-=item Rational Software's Purify
-
--Accflags=-DPURIFY, -Doptimize='-g', -Uusemymalloc, -Dusemultiplicity,
-DEFINES, USE_MULTI = define, #PERL_MALLOC = define, CFG = Debug
-
-=item valgrind
-
-=back
-
-=item PROFILING
-
-=over 4
-
-=item Gprof Profiling
-
--a, -b, -e routine, -f routine, -s, -z
-
-=item GCC gcov Profiling
-
-=back
-
-=item MISCELLANEOUS TRICKS
-
-=over 4
-
-=item PERL_DESTRUCT_LEVEL
-
-=item PERL_MEM_LOG
-
-=item DDD over gdb
-
-=item Poison
-
-=item Read-only optrees
-
-=item The .i Targets
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 perlpolicy - Various and sundry policies and commitments related to
-the Perl core
-
-=over 4
-
-=item DESCRIPTION
-
-=item GOVERNANCE
-
-=over 4
-
-=item Perl 5 Porters
-
-=back
-
-=item MAINTENANCE AND SUPPORT
-
-=item BACKWARD COMPATIBILITY AND DEPRECATION
-
-=over 4
-
-=item Terminology
-
-experimental, deprecated, discouraged, removed
-
-=back
-
-=item MAINTENANCE BRANCHES
-
-=over 4
-
-=item Getting changes into a maint branch
-
-=back
-
-=item CONTRIBUTED MODULES
-
-=over 4
-
-=item A Social Contract about Artistic Control
-
-=back
-
-=item DOCUMENTATION
-
-=item CREDITS
-
-=back
-
-=head2 perlgit - Detailed information about git and the Perl repository
-
-=over 4
-
-=item DESCRIPTION
-
-=item CLONING THE REPOSITORY
-
-=item WORKING WITH THE REPOSITORY
-
-=over 4
-
-=item Finding out your status
-
-=item Patch workflow
-
-=item Committing your changes
-
-=item Using git to send patch emails
-
-=item A note on derived files
-
-=item Cleaning a working directory
-
-=item Bisecting
-
-=back
-
-=item Topic branches and rewriting history
-
-=over 4
-
-=item Grafts
-
-=back
-
-=item WRITE ACCESS TO THE GIT REPOSITORY
-
-=item Accepting a patch
-
-=over 4
-
-=item Committing to blead
-
-=item Committing to maintenance versions
-
-=item Merging from a branch via GitHub
-
-=item A note on camel and dromedary
-
-=back
-
-=back
-
-=head2 perlbook - Books about and related to Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item The most popular books
-
-I<Programming Perl> (the "Camel Book"):, I<The Perl Cookbook> (the "Ram
-Book"):, I<Learning Perl> (the "Llama Book"), I<Intermediate Perl> (the
-"Alpaca Book")
-
-=item References
-
-I<Perl 5 Pocket Reference>, I<Perl Debugger Pocket Reference>, I<Regular
-Expression Pocket Reference>
-
-=item Tutorials
-
-I<Beginning Perl>, I<Learning Perl>, I<Intermediate Perl> (the "Alpaca
-Book"), I<Mastering Perl>, I<Effective Perl Programming>
-
-=item Task-Oriented
-
-I<Writing Perl Modules for CPAN>, I<The Perl Cookbook>, I<Automating System
-Administration with Perl>, I<Real World SQL Server Administration with
-Perl>
-
-=item Special Topics
-
-I<Regular Expressions Cookbook>, I<Programming the Perl DBI>, I<Perl Best
-Practices>, I<Higher-Order Perl>, I<Mastering Regular Expressions>,
-I<Network Programming with Perl>, I<Perl Template Toolkit>, I<Object
-Oriented Perl>, I<Data Munging with Perl>, I<Mastering Perl/Tk>,
-I<Extending and Embedding Perl>, I<Pro Perl Debugging>
-
-=item Free (as in beer) books
-
-=item Other interesting, non-Perl books
-
-I<Programming Pearls>, I<More Programming Pearls>
-
-=item A note on freshness
-
-=item Get your book listed
-
-=back
-
-=back
-
-=head2 perlcommunity - a brief overview of the Perl community
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Where to Find the Community
-
-=item Mailing Lists and Newsgroups
-
-=item IRC
-
-=item Websites
-
-L<http://perl.com/>, L<http://use.perl.org/>, L<http://www.perlmonks.org/>
-
-=item User Groups
-
-=item Workshops
-
-=item Hackathons
-
-=item Conventions
-
-=item Calendar of Perl Events
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 perldoc - Look up Perl documentation in Pod format.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item OPTIONS
-
-B<-h>, B<-D>, B<-t>, B<-u>, B<-m> I<module>, B<-l>, B<-F>, B<-f>
-I<perlfunc>, B<-q> I<perlfaq-search-regexp>, B<-v> I<perlvar>, B<-T>, B<-d>
-I<destination-filename>, B<-o> I<output-formatname>, B<-M> I<module-name>,
-B<-w> I<option:value> or B<-w> I<option>, B<-X>, B<-L> I<language_code>,
-B<PageName|ModuleName|ProgramName|URL>, B<-n> I<some-formatter>, B<-r>,
-B<-i>, B<-V>
-
-=item SECURITY
-
-=item ENVIRONMENT
-
-=item CHANGES
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 perlhist - the Perl history records
-
-=over 4
-
-=item DESCRIPTION
-
-=item INTRODUCTION
-
-=item THE KEEPERS OF THE PUMPKIN
-
-=over 4
-
-=item PUMPKIN?
-
-=back
-
-=item THE RECORDS
-
-=over 4
-
-=item SELECTED RELEASE SIZES
-
-=item SELECTED PATCH SIZES
-
-=back
-
-=item THE KEEPERS OF THE RECORDS
-
-=back
-
-=head2 perldelta - what is new for perl v5.16.2
-
-=over 4
-
-=item DESCRIPTION
-
-=item Incompatible Changes
-
-=item Modules and Pragmata
-
-=over 4
-
-=item Updated Modules and Pragmata
-
-=back
-
-=item Configuration and Compilation
-
-configuration should no longer be confused by ls colorization
-
-=item Platform Support
-
-=over 4
-
-=item Platform-Specific Notes
-
-AIX
-
-=back
-
-=item Selected Bug Fixes
-
-fix /\h/ equivalence with /[\h]/
-
-=item Known Problems
-
-=item Acknowledgements
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl5162delta, perldelta - what is new for perl v5.16.2
-
-=over 4
-
-=item DESCRIPTION
-
-=item Incompatible Changes
-
-=item Modules and Pragmata
-
-=over 4
-
-=item Updated Modules and Pragmata
-
-=back
-
-=item Configuration and Compilation
-
-configuration should no longer be confused by ls colorization
-
-=item Platform Support
-
-=over 4
-
-=item Platform-Specific Notes
-
-AIX
-
-=back
-
-=item Selected Bug Fixes
-
-fix /\h/ equivalence with /[\h]/
-
-=item Known Problems
-
-=item Acknowledgements
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl5161delta - what is new for perl v5.16.1
-
-=over 4
-
-=item DESCRIPTION
-
-=item Security
-
-=over 4
-
-=item an off-by-two error in Scalar-List-Util has been fixed
-
-=back
-
-=item Incompatible Changes
-
-=item Modules and Pragmata
-
-=over 4
-
-=item Updated Modules and Pragmata
-
-=back
-
-=item Configuration and Compilation
-
-=item Platform Support
-
-=over 4
-
-=item Platform-Specific Notes
-
-VMS
-
-=back
-
-=item Selected Bug Fixes
-
-=item Known Problems
-
-=item Acknowledgements
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl5160delta - what is new for perl v5.16.0
-
-=over 4
-
-=item DESCRIPTION
-
-=item Notice
-
-=item Core Enhancements
-
-=over 4
-
-=item C<use I<VERSION>>
-
-=item C<__SUB__>
-
-=item New and Improved Built-ins
-
-=item Unicode Support
-
-=item XS Changes
-
-=item Changes to Special Variables
-
-=item Debugger Changes
-
-=item The C<CORE> Namespace
-
-=item Other Changes
-
-=back
-
-=item Security
-
-=over 4
-
-=item Use C<is_utf8_char_buf()> and not C<is_utf8_char()>
-
-=item Malformed UTF-8 input could cause attempts to read beyond the end of
-the buffer
-
-=item C<File::Glob::bsd_glob()> memory error with GLOB_ALTDIRFUNC
-(CVE-2011-2728).
-
-=item Privileges are now set correctly when assigning to C<$(>
-
-=back
-
-=item Deprecations
-
-=over 4
-
-=item Don't read the Unicode data base files in F<lib/unicore>
-
-=item XS functions C<is_utf8_char()>, C<utf8_to_uvchr()> and
-C<utf8_to_uvuni()>
-
-=back
-
-=item Future Deprecations
-
-=over 4
-
-=item Core Modules
-
-=item Platforms with no supporting programmers:
-
-=item Other Future Deprecations
-
-=back
-
-=item Incompatible Changes
-
-=over 4
-
-=item Special blocks called in void context
-
-=item The C<overloading> pragma and regexp objects
-
-=item Two XS typemap Entries removed
-
-=item Unicode 6.1 has incompatibilities with Unicode 6.0
-
-=item Borland compiler
-
-=item Certain deprecated Unicode properties are no longer supported by
-default
-
-=item Dereferencing IO thingies as typeglobs
-
-=item User-defined case-changing operations
-
-=item XSUBs are now 'static'
-
-=item Weakening read-only references
-
-=item Tying scalars that hold typeglobs
-
-=item IPC::Open3 no longer provides C<xfork()>, C<xclose_on_exec()>
-and C<xpipe_anon()>
-
-=item C<$$> no longer caches PID
-
-=item C<$$> and C<getppid()> no longer emulate POSIX semantics under
-LinuxThreads
-
-=item C<< $< >>, C<< $> >>, C<$(> and C<$)> are no longer cached
-
-=item Which Non-ASCII characters get quoted by C<quotemeta> and C<\Q> has
-changed
-
-=back
-
-=item Performance Enhancements
-
-=item Modules and Pragmata
-
-=over 4
-
-=item Deprecated Modules
-
-L<Version::Requirements>
-
-=item New Modules and Pragmata
-
-=item Updated Modules and Pragmata
-
-=item Removed Modules and Pragmata
-
-=back
-
-=item Documentation
-
-=over 4
-
-=item New Documentation
-
-=item Changes to Existing Documentation
-
-=item Removed Documentation
-
-=back
-
-=item Diagnostics
-
-=over 4
-
-=item New Diagnostics
-
-=item Removed Errors
-
-=item Changes to Existing Diagnostics
-
-=back
-
-=item Utility Changes
-
-=item Configuration and Compilation
-
-=item Platform Support
-
-=over 4
-
-=item Platform-Specific Notes
-
-=back
-
-=item Internal Changes
-
-=item Selected Bug Fixes
-
-=over 4
-
-=item Array and hash
-
-=item C API fixes
-
-=item Compile-time hints
-
-=item Copy-on-write scalars
-
-=item The debugger
-
-=item Dereferencing operators
-
-=item Filehandle, last-accessed
-
-=item Filetests and C<stat>
-
-=item Formats
-
-=item C<given> and C<when>
-
-=item The C<glob> operator
-
-=item Lvalue subroutines
-
-=item Overloading
-
-=item Prototypes of built-in keywords
-
-=item Regular expressions
-
-=item Smartmatching
-
-=item The C<sort> operator
-
-=item The C<substr> operator
-
-=item Support for embedded nulls
-
-=item Threading bugs
-
-=item Tied variables
-
-=item Version objects and vstrings
-
-=item Warnings, redefinition
-
-=item Warnings, "Uninitialized"
-
-=item Weak references
-
-=item Other notable fixes
-
-=back
-
-=item Known Problems
-
-=item Acknowledgements
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl5160delta - what is new for perl v5.16.0
-
-=over 4
-
-=item DESCRIPTION
-
-=item Notice
-
-=item Core Enhancements
-
-=over 4
-
-=item C<use I<VERSION>>
-
-=item C<__SUB__>
-
-=item New and Improved Built-ins
-
-=item Unicode Support
-
-=item XS Changes
-
-=item Changes to Special Variables
-
-=item Debugger Changes
-
-=item The C<CORE> Namespace
-
-=item Other Changes
-
-=back
-
-=item Security
-
-=over 4
-
-=item Use C<is_utf8_char_buf()> and not C<is_utf8_char()>
-
-=item Malformed UTF-8 input could cause attempts to read beyond the end of
-the buffer
-
-=item C<File::Glob::bsd_glob()> memory error with GLOB_ALTDIRFUNC
-(CVE-2011-2728).
-
-=item Privileges are now set correctly when assigning to C<$(>
-
-=back
-
-=item Deprecations
-
-=over 4
-
-=item Don't read the Unicode data base files in F<lib/unicore>
-
-=item XS functions C<is_utf8_char()>, C<utf8_to_uvchr()> and
-C<utf8_to_uvuni()>
-
-=back
-
-=item Future Deprecations
-
-=over 4
-
-=item Core Modules
-
-=item Platforms with no supporting programmers:
-
-=item Other Future Deprecations
-
-=back
-
-=item Incompatible Changes
-
-=over 4
-
-=item Special blocks called in void context
-
-=item The C<overloading> pragma and regexp objects
-
-=item Two XS typemap Entries removed
-
-=item Unicode 6.1 has incompatibilities with Unicode 6.0
-
-=item Borland compiler
-
-=item Certain deprecated Unicode properties are no longer supported by
-default
-
-=item Dereferencing IO thingies as typeglobs
-
-=item User-defined case-changing operations
-
-=item XSUBs are now 'static'
-
-=item Weakening read-only references
-
-=item Tying scalars that hold typeglobs
-
-=item IPC::Open3 no longer provides C<xfork()>, C<xclose_on_exec()>
-and C<xpipe_anon()>
-
-=item C<$$> no longer caches PID
-
-=item C<$$> and C<getppid()> no longer emulate POSIX semantics under
-LinuxThreads
-
-=item C<< $< >>, C<< $> >>, C<$(> and C<$)> are no longer cached
-
-=item Which Non-ASCII characters get quoted by C<quotemeta> and C<\Q> has
-changed
-
-=back
-
-=item Performance Enhancements
-
-=item Modules and Pragmata
-
-=over 4
-
-=item Deprecated Modules
-
-L<Version::Requirements>
-
-=item New Modules and Pragmata
-
-=item Updated Modules and Pragmata
-
-=item Removed Modules and Pragmata
-
-=back
-
-=item Documentation
-
-=over 4
-
-=item New Documentation
-
-=item Changes to Existing Documentation
-
-=item Removed Documentation
-
-=back
-
-=item Diagnostics
-
-=over 4
-
-=item New Diagnostics
-
-=item Removed Errors
-
-=item Changes to Existing Diagnostics
-
-=back
-
-=item Utility Changes
-
-=item Configuration and Compilation
-
-=item Platform Support
-
-=over 4
-
-=item Platform-Specific Notes
-
-=back
-
-=item Internal Changes
-
-=item Selected Bug Fixes
-
-=over 4
-
-=item Array and hash
-
-=item C API fixes
-
-=item Compile-time hints
-
-=item Copy-on-write scalars
-
-=item The debugger
-
-=item Dereferencing operators
-
-=item Filehandle, last-accessed
-
-=item Filetests and C<stat>
-
-=item Formats
-
-=item C<given> and C<when>
-
-=item The C<glob> operator
-
-=item Lvalue subroutines
-
-=item Overloading
-
-=item Prototypes of built-in keywords
-
-=item Regular expressions
-
-=item Smartmatching
-
-=item The C<sort> operator
-
-=item The C<substr> operator
-
-=item Support for embedded nulls
-
-=item Threading bugs
-
-=item Tied variables
-
-=item Version objects and vstrings
-
-=item Warnings, redefinition
-
-=item Warnings, "Uninitialized"
-
-=item Weak references
-
-=item Other notable fixes
-
-=back
-
-=item Known Problems
-
-=item Acknowledgements
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl5143delta - what is new for perl v5.14.3
-
-=over 4
-
-=item DESCRIPTION
-
-=item Core Enhancements
-
-=item Security
-
-=over 4
-
-=item C<Digest> unsafe use of eval (CVE-2011-3597)
-
-=item Heap buffer overrun in 'x' string repeat operator (CVE-2012-5195)
-
-=back
-
-=item Incompatible Changes
-
-=item Deprecations
-
-=item Modules and Pragmata
-
-=over 4
-
-=item New Modules and Pragmata
-
-=item Updated Modules and Pragmata
-
-=item Removed Modules and Pragmata
-
-=back
-
-=item Documentation
-
-=over 4
-
-=item New Documentation
-
-=item Changes to Existing Documentation
-
-=back
-
-=item Configuration and Compilation
-
-=item Platform Support
-
-=over 4
-
-=item New Platforms
-
-=item Discontinued Platforms
-
-=item Platform-Specific Notes
-
-FreeBSD, Solaris and NetBSD, HP-UX, Linux, Mac OS X, GNU/Hurd, NetBSD
-
-=back
-
-=item Bug Fixes
-
-=item Acknowledgements
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl5142delta - what is new for perl v5.14.2
-
-=over 4
-
-=item DESCRIPTION
-
-=item Core Enhancements
-
-=item Security
-
-=over 4
-
-=item C<File::Glob::bsd_glob()> memory error with GLOB_ALTDIRFUNC
-(CVE-2011-2728).
-
-=item C<Encode> decode_xs n-byte heap-overflow (CVE-2011-2939)
-
-=back
-
-=item Incompatible Changes
-
-=item Deprecations
-
-=item Modules and Pragmata
-
-=over 4
-
-=item New Modules and Pragmata
-
-=item Updated Modules and Pragmata
-
-=item Removed Modules and Pragmata
-
-=back
-
-=item Platform Support
-
-=over 4
-
-=item New Platforms
-
-=item Discontinued Platforms
-
-=item Platform-Specific Notes
-
-HP-UX PA-RISC/64 now supports gcc-4.x, Building on OS X 10.7 Lion and Xcode
-4 works again
-
-=back
-
-=item Bug Fixes
-
-=item Known Problems
-
-=item Acknowledgements
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl5141delta - what is new for perl v5.14.1
-
-=over 4
-
-=item DESCRIPTION
-
-=item Core Enhancements
-
-=item Security
-
-=item Incompatible Changes
-
-=item Deprecations
-
-=item Modules and Pragmata
-
-=over 4
-
-=item New Modules and Pragmata
-
-=item Updated Modules and Pragmata
-
-=item Removed Modules and Pragmata
-
-=back
-
-=item Documentation
-
-=over 4
-
-=item New Documentation
-
-=item Changes to Existing Documentation
-
-=back
-
-=item Diagnostics
-
-=over 4
-
-=item New Diagnostics
-
-=item Changes to Existing Diagnostics
-
-=back
-
-=item Utility Changes
-
-=item Configuration and Compilation
-
-=item Testing
-
-=item Platform Support
-
-=over 4
-
-=item New Platforms
-
-=item Discontinued Platforms
-
-=item Platform-Specific Notes
-
-=back
-
-=item Internal Changes
-
-=item Bug Fixes
-
-=item Acknowledgements
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl5140delta - what is new for perl v5.14.0
-
-=over 4
-
-=item DESCRIPTION
-
-=item Notice
-
-=item Core Enhancements
-
-=over 4
-
-=item Unicode
-
-=item Regular Expressions
-
-=item Syntactical Enhancements
-
-=item Exception Handling
-
-=item Other Enhancements
-
-C<-d:-foo>, C<-d:-foo=bar>
-
-=item New C APIs
-
-=back
-
-=item Security
-
-=over 4
-
-=item User-defined regular expression properties
-
-=back
-
-=item Incompatible Changes
-
-=over 4
-
-=item Regular Expressions and String Escapes
-
-=item Stashes and Package Variables
-
-=item Changes to Syntax or to Perl Operators
-
-=item Threads and Processes
-
-=item Configuration
-
-=back
-
-=item Deprecations
-
-=over 4
-
-=item Omitting a space between a regular expression and subsequent word
-
-=item C<\cI<X>>
-
-=item C<"\b{"> and C<"\B{">
-
-=item Perl 4-era .pl libraries
-
-=item List assignment to C<$[>
-
-=item Use of qw(...) as parentheses
-
-=item C<\N{BELL}>
-
-=item C<?PATTERN?>
-
-=item Tie functions on scalars holding typeglobs
-
-=item User-defined case-mapping
-
-=item Deprecated modules
-
-L<Devel::DProf>
-
-=back
-
-=item Performance Enhancements
-
-=over 4
-
-=item "Safe signals" optimisation
-
-=item Optimisation of shift() and pop() calls without arguments
-
-=item Optimisation of regexp engine string comparison work
-
-=item Regular expression compilation speed-up
-
-=item String appending is 100 times faster
-
-=item Eliminate C<PL_*> accessor functions under ithreads
-
-=item Freeing weak references
-
-=item Lexical array and hash assignments
-
-=item C<@_> uses less memory
-
-=item Size optimisations to SV and HV structures
-
-=item Memory consumption improvements to Exporter
-
-=item Memory savings for weak references
-
-=item C<%+> and C<%-> use less memory
-
-=item Multiple small improvements to threads
-
-=item Adjacent pairs of nextstate opcodes are now optimized away
-
-=back
-
-=item Modules and Pragmata
-
-=over 4
-
-=item New Modules and Pragmata
-
-=item Updated Modules and Pragma
-
-much less configuration dialog hassle, support for F<META/MYMETA.json>,
-support for L<local::lib>, support for L<HTTP::Tiny> to reduce the
-dependency on FTP sites, automatic mirror selection, iron out all known
-bugs in configure_requires, support for distributions compressed with
-L<bzip2(1)>, allow F<Foo/Bar.pm> on the command line to mean C<Foo::Bar>,
-charinfo(), charscript(), charblock()
-
-=item Removed Modules and Pragmata
-
-=back
-
-=item Documentation
-
-=over 4
-
-=item New Documentation
-
-=item Changes to Existing Documentation
-
-=back
-
-=item Diagnostics
-
-=over 4
-
-=item New Diagnostics
-
-Closure prototype called, Insecure user-defined property %s, panic: gp_free
-failed to free glob pointer - something is repeatedly re-creating entries,
-Parsing code internal error (%s), refcnt: fd %d%s, Regexp modifier "/%c"
-may not appear twice, Regexp modifiers "/%c" and "/%c" are mutually
-exclusive, Using !~ with %s doesn't make sense, "\b{" is deprecated; use
-"\b\{" instead, "\B{" is deprecated; use "\B\{" instead, Operation "%s"
-returns its argument for .., Use of qw(...) as parentheses is deprecated
-
-=item Changes to Existing Diagnostics
-
-=back
-
-=item Utility Changes
-
-=item Configuration and Compilation
-
-=item Platform Support
-
-=over 4
-
-=item New Platforms
-
-AIX
-
-=item Discontinued Platforms
-
-Apollo DomainOS, MacOS Classic
-
-=item Platform-Specific Notes
-
-=back
-
-=item Internal Changes
-
-=over 4
-
-=item New APIs
-
-=item C API Changes
-
-=item Deprecated C APIs
-
-C<Perl_ptr_table_clear>, C<sv_compile_2op>, C<find_rundefsvoffset>,
-C<CALL_FPTR> and C<CPERLscope>
-
-=item Other Internal Changes
-
-=back
-
-=item Selected Bug Fixes
-
-=over 4
-
-=item I/O
-
-=item Regular Expression Bug Fixes
-
-=item Syntax/Parsing Bugs
-
-=item Stashes, Globs and Method Lookup
-
-Aliasing packages by assigning to globs [perl #77358], Deleting packages by
-deleting their containing stash elements, Undefining the glob containing a
-package (C<undef *Foo::>), Undefining an ISA glob (C<undef *Foo::ISA>),
-Deleting an ISA stash element (C<delete $Foo::{ISA}>), Sharing @ISA arrays
-between classes (via C<*Foo::ISA = \@Bar::ISA> or C<*Foo::ISA = *Bar::ISA>)
-[perl #77238]
-
-=item Unicode
-
-=item Ties, Overloading and Other Magic
-
-=item The Debugger
-
-=item Threads
-
-=item Scoping and Subroutines
-
-=item Signals
-
-=item Miscellaneous Memory Leaks
-
-=item Memory Corruption and Crashes
-
-=item Fixes to Various Perl Operators
-
-=item Bugs Relating to the C API
-
-=back
-
-=item Known Problems
-
-=item Errata
-
-=over 4
-
-=item keys(), values(), and each() work on arrays
-
-=item split() and C<@_>
-
-=back
-
-=item Obituary
-
-=item Acknowledgements
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl5124delta - what is new for perl v5.12.4
-
-=over 4
-
-=item DESCRIPTION
-
-=item Incompatible Changes
-
-=item Selected Bug Fixes
-
-=item Modules and Pragmata
-
-=item Testing
-
-=item Documentation
-
-=item Platform Specific Notes
-
-Linux
-
-=item Acknowledgements
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl5123delta - what is new for perl v5.12.3
-
-=over 4
-
-=item DESCRIPTION
-
-=item Incompatible Changes
-
-=item Core Enhancements
-
-=over 4
-
-=item C<keys>, C<values> work on arrays
-
-=back
-
-=item Bug Fixes
-
-=item Platform Specific Notes
-
-Solaris, VMS, VOS
-
-=item Acknowledgements
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl5122delta - what is new for perl v5.12.2
-
-=over 4
-
-=item DESCRIPTION
-
-=item Incompatible Changes
-
-=item Core Enhancements
-
-=item Modules and Pragmata
-
-=over 4
-
-=item New Modules and Pragmata
-
-=item Pragmata Changes
-
-=item Updated Modules
-
-C<Carp>, C<CPANPLUS>, C<File::Glob>, C<File::Copy>, C<File::Spec>
-
-=back
-
-=item Utility Changes
-
-=item Changes to Existing Documentation
-
-=item Installation and Configuration Improvements
-
-=over 4
-
-=item Configuration improvements
-
-=item Compilation improvements
-
-=back
-
-=item Selected Bug Fixes
-
-=item Platform Specific Notes
-
-=over 4
-
-=item AIX
-
-=item Windows
-
-=item VMS
-
-=back
-
-=item Acknowledgements
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl5121delta - what is new for perl v5.12.1
-
-=over 4
-
-=item DESCRIPTION
-
-=item Incompatible Changes
-
-=item Core Enhancements
-
-=item Modules and Pragmata
-
-=over 4
-
-=item Pragmata Changes
-
-=item Updated Modules
-
-=back
-
-=item Changes to Existing Documentation
-
-=item Testing
-
-=over 4
-
-=item Testing Improvements
-
-=back
-
-=item Installation and Configuration Improvements
-
-=over 4
-
-=item Configuration improvements
-
-=back
-
-=item Bug Fixes
-
-=item Platform Specific Notes
-
-=over 4
-
-=item HP-UX
-
-=item AIX
-
-=item FreeBSD 7
-
-=item VMS
-
-=back
-
-=item Known Problems
-
-=item Acknowledgements
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl5120delta - what is new for perl v5.12.0
-
-=over 4
-
-=item DESCRIPTION
-
-=item Core Enhancements
-
-=over 4
-
-=item New C<package NAME VERSION> syntax
-
-=item The C<...> operator
-
-=item Implicit strictures
-
-=item Unicode improvements
-
-=item Y2038 compliance
-
-=item qr overloading
-
-=item Pluggable keywords
-
-=item APIs for more internals
-
-=item Overridable function lookup
-
-=item A proper interface for pluggable Method Resolution Orders
-
-=item C<\N> experimental regex escape
-
-=item DTrace support
-
-=item Support for C<configure_requires> in CPAN module metadata
-
-=item C<each>, C<keys>, C<values> are now more flexible
-
-=item C<when> as a statement modifier
-
-=item C<$,> flexibility
-
-=item // in when clauses
-
-=item Enabling warnings from your shell environment
-
-=item C<delete local>
-
-=item New support for Abstract namespace sockets
-
-=item 32-bit limit on substr arguments removed
-
-=back
-
-=item Potentially Incompatible Changes
-
-=over 4
-
-=item Deprecations warn by default
-
-=item Version number formats
-
-=item @INC reorganization
-
-=item REGEXPs are now first class
-
-=item Switch statement changes
-
-flip-flop operators, defined-or operator
-
-=item Smart match changes
-
-=item Other potentially incompatible changes
-
-=back
-
-=item Deprecations
-
-suidperl, Use of C<:=> to mean an empty attribute list, C<<
-UNIVERSAL->import() >>, Use of "goto" to jump into a construct, Custom
-character names in \N{name} that don't look like names, Deprecated Modules,
-L<Class::ISA>, L<Pod::Plainer>, L<Shell>, L<Switch>, Assignment to $[, Use
-of the attribute :locked on subroutines, Use of "locked" with the
-attributes pragma, Use of "unique" with the attributes pragma, Perl_pmflag,
-Numerous Perl 4-era libraries
-
-=item Unicode overhaul
-
-=item Modules and Pragmata
-
-=over 4
-
-=item New Modules and Pragmata
-
-C<autodie>, C<Compress::Raw::Bzip2>, C<overloading>, C<parent>,
-C<Parse::CPAN::Meta>, C<VMS::DCLsym>, C<VMS::Stdio>,
-C<XS::APItest::KeywordRPN>
-
-=item Updated Pragmata
-
-C<base>, C<bignum>, C<charnames>, C<constant>, C<diagnostics>, C<feature>,
-C<less>, C<lib>, C<mro>, C<overload>, C<threads>, C<threads::shared>,
-C<version>, C<warnings>
-
-=item Updated Modules
-
-C<Archive::Extract>, C<Archive::Tar>, C<Attribute::Handlers>,
-C<AutoLoader>, C<B::Concise>, C<B::Debug>, C<B::Deparse>, C<B::Lint>,
-C<CGI>, C<Class::ISA>, C<Compress::Raw::Zlib>, C<CPAN>, C<CPANPLUS>,
-C<CPANPLUS::Dist::Build>, C<Data::Dumper>, C<DB_File>, C<Devel::PPPort>,
-C<Digest>, C<Digest::MD5>, C<Digest::SHA>, C<Encode>, C<Exporter>,
-C<ExtUtils::CBuilder>, C<ExtUtils::Command>, C<ExtUtils::Constant>,
-C<ExtUtils::Install>, C<ExtUtils::MakeMaker>, C<ExtUtils::Manifest>,
-C<ExtUtils::ParseXS>, C<File::Fetch>, C<File::Path>, C<File::Temp>,
-C<Filter::Simple>, C<Filter::Util::Call>, C<Getopt::Long>, C<IO>,
-C<IO::Zlib>, C<IPC::Cmd>, C<IPC::SysV>, C<Locale::Maketext>,
-C<Locale::Maketext::Simple>, C<Log::Message>, C<Log::Message::Simple>,
-C<Math::BigInt>, C<Math::BigInt::FastCalc>, C<Math::BigRat>,
-C<Math::Complex>, C<Memoize>, C<MIME::Base64>, C<Module::Build>,
-C<Module::CoreList>, C<Module::Load>, C<Module::Load::Conditional>,
-C<Module::Loaded>, C<Module::Pluggable>, C<Net::Ping>, C<NEXT>,
-C<Object::Accessor>, C<Package::Constants>, C<PerlIO>, C<Pod::Parser>,
-C<Pod::Perldoc>, C<Pod::Plainer>, C<Pod::Simple>, C<Safe>, C<SelfLoader>,
-C<Storable>, C<Switch>, C<Sys::Syslog>, C<Term::ANSIColor>, C<Term::UI>,
-C<Test>, C<Test::Harness>, C<Test::Simple>, C<Text::Balanced>,
-C<Text::ParseWords>, C<Text::Soundex>, C<Thread::Queue>,
-C<Thread::Semaphore>, C<Tie::RefHash>, C<Time::HiRes>, C<Time::Local>,
-C<Time::Piece>, C<Unicode::Collate>, C<Unicode::Normalize>, C<Win32>,
-C<Win32API::File>, C<XSLoader>
-
-=item Removed Modules and Pragmata
-
-C<attrs>, C<CPAN::API::HOWTO>, C<CPAN::DeferedCode>, C<CPANPLUS::inc>,
-C<DCLsym>, C<ExtUtils::MakeMaker::bytes>, C<ExtUtils::MakeMaker::vmsish>,
-C<Stdio>, C<Test::Harness::Assert>, C<Test::Harness::Iterator>,
-C<Test::Harness::Point>, C<Test::Harness::Results>,
-C<Test::Harness::Straps>, C<Test::Harness::Util>, C<XSSymSet>
-
-=item Deprecated Modules and Pragmata
-
-=back
-
-=item Documentation
-
-=over 4
-
-=item New Documentation
-
-=item Changes to Existing Documentation
-
-=back
-
-=item Selected Performance Enhancements
-
-=item Installation and Configuration Improvements
-
-=item Internal Changes
-
-=item Testing
-
-=over 4
-
-=item Testing improvements
-
-Parallel tests, Test harness flexibility, Test watchdog
-
-=item New Tests
-
-=back
-
-=item New or Changed Diagnostics
-
-=over 4
-
-=item New Diagnostics
-
-=item Changed Diagnostics
-
-C<Illegal character in prototype for %s : %s>, C<Prototype after '%c' for
-%s : %s>
-
-=back
-
-=item Utility Changes
-
-=item Selected Bug Fixes
-
-=item Platform Specific Changes
-
-=over 4
-
-=item New Platforms
-
-Haiku, MirOS BSD
-
-=item Discontinued Platforms
-
-Domain/OS, MiNT, Tenon MachTen
-
-=item Updated Platforms
-
-AIX, Cygwin, Darwin (Mac OS X), DragonFly BSD, FreeBSD, Irix, NetBSD,
-OpenVMS, Stratus VOS, Symbian, Windows
-
-=back
-
-=item Known Problems
-
-=item Errata
-
-=item Acknowledgements
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl5101delta - what is new for perl v5.10.1
-
-=over 4
-
-=item DESCRIPTION
-
-=item Incompatible Changes
-
-=over 4
-
-=item Switch statement changes
-
-flip-flop operators, defined-or operator
-
-=item Smart match changes
-
-=item Other incompatible changes
-
-=back
-
-=item Core Enhancements
-
-=over 4
-
-=item Unicode Character Database 5.1.0
-
-=item A proper interface for pluggable Method Resolution Orders
-
-=item The C<overloading> pragma
-
-=item Parallel tests
-
-=item DTrace support
-
-=item Support for C<configure_requires> in CPAN module metadata
-
-=back
-
-=item Modules and Pragmata
-
-=over 4
-
-=item New Modules and Pragmata
-
-C<autodie>, C<Compress::Raw::Bzip2>, C<parent>, C<Parse::CPAN::Meta>
-
-=item Pragmata Changes
-
-C<attributes>, C<attrs>, C<base>, C<bigint>, C<bignum>, C<bigrat>,
-C<charnames>, C<constant>, C<feature>, C<fields>, C<lib>, C<open>,
-C<overload>, C<overloading>, C<version>
-
-=item Updated Modules
-
-C<Archive::Extract>, C<Archive::Tar>, C<Attribute::Handlers>,
-C<AutoLoader>, C<AutoSplit>, C<B>, C<B::Debug>, C<B::Deparse>, C<B::Lint>,
-C<B::Xref>, C<Benchmark>, C<Carp>, C<CGI>, C<Compress::Zlib>, C<CPAN>,
-C<CPANPLUS>, C<CPANPLUS::Dist::Build>, C<Cwd>, C<Data::Dumper>, C<DB>,
-C<DB_File>, C<Devel::PPPort>, C<Digest::MD5>, C<Digest::SHA>, C<DirHandle>,
-C<Dumpvalue>, C<DynaLoader>, C<Encode>, C<Errno>, C<Exporter>,
-C<ExtUtils::CBuilder>, C<ExtUtils::Command>, C<ExtUtils::Constant>,
-C<ExtUtils::Embed>, C<ExtUtils::Install>, C<ExtUtils::MakeMaker>,
-C<ExtUtils::Manifest>, C<ExtUtils::ParseXS>, C<Fatal>, C<File::Basename>,
-C<File::Compare>, C<File::Copy>, C<File::Fetch>, C<File::Find>,
-C<File::Path>, C<File::Spec>, C<File::stat>, C<File::Temp>, C<FileCache>,
-C<FileHandle>, C<Filter::Simple>, C<Filter::Util::Call>, C<FindBin>,
-C<GDBM_File>, C<Getopt::Long>, C<Hash::Util::FieldHash>, C<I18N::Collate>,
-C<IO>, C<IO::Compress::*>, C<IO::Dir>, C<IO::Handle>, C<IO::Socket>,
-C<IO::Zlib>, C<IPC::Cmd>, C<IPC::Open3>, C<IPC::SysV>, C<lib>,
-C<List::Util>, C<Locale::MakeText>, C<Log::Message>, C<Math::BigFloat>,
-C<Math::BigInt>, C<Math::BigInt::FastCalc>, C<Math::BigRat>,
-C<Math::Complex>, C<Math::Trig>, C<Memoize>, C<Module::Build>,
-C<Module::CoreList>, C<Module::Load>, C<Module::Load::Conditional>,
-C<Module::Loaded>, C<Module::Pluggable>, C<NDBM_File>, C<Net::Ping>,
-C<NEXT>, C<Object::Accessor>, C<OS2::REXX>, C<Package::Constants>,
-C<PerlIO>, C<PerlIO::via>, C<Pod::Man>, C<Pod::Parser>, C<Pod::Simple>,
-C<Pod::Text>, C<POSIX>, C<Safe>, C<Scalar::Util>, C<SelectSaver>,
-C<SelfLoader>, C<Socket>, C<Storable>, C<Switch>, C<Symbol>,
-C<Sys::Syslog>, C<Term::ANSIColor>, C<Term::ReadLine>, C<Term::UI>,
-C<Test::Harness>, C<Test::Simple>, C<Text::ParseWords>, C<Text::Tabs>,
-C<Text::Wrap>, C<Thread::Queue>, C<Thread::Semaphore>, C<threads>,
-C<threads::shared>, C<Tie::RefHash>, C<Tie::StdHandle>, C<Time::HiRes>,
-C<Time::Local>, C<Time::Piece>, C<Unicode::Normalize>, C<Unicode::UCD>,
-C<UNIVERSAL>, C<Win32>, C<Win32API::File>, C<XSLoader>
-
-=back
-
-=item Utility Changes
-
-F<h2ph>, F<h2xs>, F<perl5db.pl>, F<perlthanks>
-
-=item New Documentation
-
-L<perlhaiku>, L<perlmroapi>, L<perlperf>, L<perlrepository>, L<perlthanks>
-
-=item Changes to Existing Documentation
-
-=item Performance Enhancements
-
-=item Installation and Configuration Improvements
-
-=over 4
-
-=item F<ext/> reorganisation
-
-=item Configuration improvements
-
-=item Compilation improvements
-
-=item Platform Specific Changes
-
-AIX, Cygwin, FreeBSD, Irix, Haiku, MirOS BSD, NetBSD, Stratus VOS, Symbian,
-Win32, VMS
-
-=back
-
-=item Selected Bug Fixes
-
-=item New or Changed Diagnostics
-
-C<panic: sv_chop %s>, C<Can't locate package %s for the parents of %s>,
-C<v-string in use/require is non-portable>, C<Deep recursion on subroutine
-"%s">
-
-=item Changed Internals
-
-C<SVf_UTF8>, C<SVs_TEMP>
-
-=item New Tests
-
-t/comp/retainedlines.t, t/io/perlio_fail.t, t/io/perlio_leaks.t,
-t/io/perlio_open.t, t/io/perlio.t, t/io/pvbm.t, t/mro/package_aliases.t,
-t/op/dbm.t, t/op/index_thr.t, t/op/pat_thr.t, t/op/qr_gc.t,
-t/op/reg_email_thr.t, t/op/regexp_qr_embed_thr.t,
-t/op/regexp_unicode_prop.t, t/op/regexp_unicode_prop_thr.t,
-t/op/reg_nc_tie.t, t/op/reg_posixcc.t, t/op/re.t, t/op/setpgrpstack.t,
-t/op/substr_thr.t, t/op/upgrade.t, t/uni/lex_utf8.t, t/uni/tie.t
-
-=item Known Problems
-
-=item Deprecations
-
-=item Acknowledgements
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl5100delta - what is new for perl 5.10.0
-
-=over 4
-
-=item DESCRIPTION
-
-=item Core Enhancements
-
-=over 4
-
-=item The C<feature> pragma
-
-=item New B<-E> command-line switch
-
-=item Defined-or operator
-
-=item Switch and Smart Match operator
-
-=item Regular expressions
-
-Recursive Patterns, Named Capture Buffers, Possessive Quantifiers,
-Backtracking control verbs, Relative backreferences, C<\K> escape, Vertical
-and horizontal whitespace, and linebreak
-
-=item C<say()>
-
-=item Lexical C<$_>
-
-=item The C<_> prototype
-
-=item UNITCHECK blocks
-
-=item New Pragma, C<mro>
-
-=item readdir() may return a "short filename" on Windows
-
-=item readpipe() is now overridable
-
-=item Default argument for readline()
-
-=item state() variables
-
-=item Stacked filetest operators
-
-=item UNIVERSAL::DOES()
-
-=item Formats
-
-=item Byte-order modifiers for pack() and unpack()
-
-=item C<no VERSION>
-
-=item C<chdir>, C<chmod> and C<chown> on filehandles
-
-=item OS groups
-
-=item Recursive sort subs
-
-=item Exceptions in constant folding
-
-=item Source filters in @INC
-
-=item New internal variables
-
-C<${^RE_DEBUG_FLAGS}>, C<${^CHILD_ERROR_NATIVE}>, C<${^RE_TRIE_MAXBUF}>,
-C<${^WIN32_SLOPPY_STAT}>
-
-=item Miscellaneous
-
-=item UCD 5.0.0
-
-=item MAD
-
-=item kill() on Windows
-
-=back
-
-=item Incompatible Changes
-
-=over 4
-
-=item Packing and UTF-8 strings
-
-=item Byte/character count feature in unpack()
-
-=item The C<$*> and C<$#> variables have been removed
-
-=item substr() lvalues are no longer fixed-length
-
-=item Parsing of C<-f _>
-
-=item C<:unique>
-
-=item Effect of pragmas in eval
-
-=item chdir FOO
-
-=item Handling of .pmc files
-
-=item $^V is now a C<version> object instead of a v-string
-
-=item @- and @+ in patterns
-
-=item $AUTOLOAD can now be tainted
-
-=item Tainting and printf
-
-=item undef and signal handlers
-
-=item strictures and dereferencing in defined()
-
-=item C<(?p{})> has been removed
-
-=item Pseudo-hashes have been removed
-
-=item Removal of the bytecode compiler and of perlcc
-
-=item Removal of the JPL
-
-=item Recursive inheritance detected earlier
-
-=item warnings::enabled and warnings::warnif changed to favor users of
-modules
-
-=back
-
-=item Modules and Pragmata
-
-=over 4
-
-=item Upgrading individual core modules
-
-=item Pragmata Changes
-
-C<feature>, C<mro>, Scoping of the C<sort> pragma, Scoping of C<bignum>,
-C<bigint>, C<bigrat>, C<base>, C<strict> and C<warnings>, C<version>,
-C<warnings>, C<less>
-
-=item New modules
-
-=item Selected Changes to Core Modules
-
-C<Attribute::Handlers>, C<B::Lint>, C<B>, C<Thread>
-
-=back
-
-=item Utility Changes
-
-perl -d, ptar, ptardiff, shasum, corelist, h2ph and h2xs, perlivp,
-find2perl, config_data, cpanp, cpan2dist, pod2html
-
-=item New Documentation
-
-=item Performance Enhancements
-
-=over 4
-
-=item In-place sorting
-
-=item Lexical array access
-
-=item XS-assisted SWASHGET
-
-=item Constant subroutines
-
-=item C<PERL_DONT_CREATE_GVSV>
-
-=item Weak references are cheaper
-
-=item sort() enhancements
-
-=item Memory optimisations
-
-=item UTF-8 cache optimisation
-
-=item Sloppy stat on Windows
-
-=item Regular expressions optimisations
-
-Engine de-recursivised, Single char char-classes treated as literals, Trie
-optimisation of literal string alternations, Aho-Corasick start-point
-optimisation
-
-=back
-
-=item Installation and Configuration Improvements
-
-=over 4
-
-=item Configuration improvements
-
-C<-Dusesitecustomize>, Relocatable installations, strlcat() and strlcpy(),
-C<d_pseudofork> and C<d_printf_format_null>, Configure help
-
-=item Compilation improvements
-
-Parallel build, Borland's compilers support, Static build on Windows,
-ppport.h files, C++ compatibility, Support for Microsoft 64-bit compiler,
-Visual C++, Win32 builds
-
-=item Installation improvements
-
-Module auxiliary files
-
-=item New Or Improved Platforms
-
-=back
-
-=item Selected Bug Fixes
-
-strictures in regexp-eval blocks, Calling CORE::require(), Subscripts of
-slices, C<no warnings 'category'> works correctly with -w, threads
-improvements, chr() and negative values, PERL5SHELL and tainting, Using
-*FILE{IO}, Overloading and reblessing, Overloading and UTF-8, eval memory
-leaks fixed, Random device on Windows, PERLIO_DEBUG, PerlIO::scalar and
-read-only scalars, study() and UTF-8, Critical signals, @INC-hook fix,
-C<-t> switch fix, Duping UTF-8 filehandles, Localisation of hash elements
-
-=item New or Changed Diagnostics
-
-Use of uninitialized value, Deprecated use of my() in false conditional,
-!=~ should be !~, Newline in left-justified string, Too late for "-T"
-option, "%s" variable %s masks earlier declaration,
-readdir()/closedir()/etc. attempted on invalid dirhandle, Opening
-dirhandle/filehandle %s also as a file/directory, Use of -P is deprecated,
-v-string in use/require is non-portable, perl -V
-
-=item Changed Internals
-
-=over 4
-
-=item Reordering of SVt_* constants
-
-=item Elimination of SVt_PVBM
-
-=item New type SVt_BIND
-
-=item Removal of CPP symbols
-
-=item Less space is used by ops
-
-=item New parser
-
-=item Use of C<const>
-
-=item Mathoms
-
-=item C<AvFLAGS> has been removed
-
-=item C<av_*> changes
-
-=item $^H and %^H
-
-=item B:: modules inheritance changed
-
-=item Anonymous hash and array constructors
-
-=back
-
-=item Known Problems
-
-=over 4
-
-=item UTF-8 problems
-
-=back
-
-=item Platform Specific Problems
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl589delta - what is new for perl v5.8.9
-
-=over 4
-
-=item DESCRIPTION
-
-=item Notice
-
-=item Incompatible Changes
-
-=item Core Enhancements
-
-=over 4
-
-=item Unicode Character Database 5.1.0.
-
-=item stat and -X on directory handles
-
-=item Source filters in @INC
-
-=item Exceptions in constant folding
-
-=item C<no VERSION>
-
-=item Improved internal UTF-8 caching code
-
-=item Runtime relocatable installations
-
-=item New internal variables
-
-C<${^CHILD_ERROR_NATIVE}>, C<${^UTF8CACHE}>
-
-=item C<readpipe> is now overridable
-
-=item simple exception handling macros
-
-=item -D option enhancements
-
-=item XS-assisted SWASHGET
-
-=item Constant subroutines
-
-=back
-
-=item New Platforms
-
-=item Modules and Pragmata
-
-=over 4
-
-=item New Modules
-
-=item Updated Modules
-
-=back
-
-=item Utility Changes
-
-=over 4
-
-=item debugger upgraded to version 1.31
-
-=item F<perlthanks>
-
-=item F<perlbug>
-
-=item F<h2xs>
-
-=item F<h2ph>
-
-=back
-
-=item New Documentation
-
-=item Changes to Existing Documentation
-
-=item Performance Enhancements
-
-=item Installation and Configuration Improvements
-
-=over 4
-
-=item Relocatable installations
-
-=item Configuration improvements
-
-=item Compilation improvements
-
-=item Installation improvements.
-
-=item Platform Specific Changes
-
-=back
-
-=item Selected Bug Fixes
-
-=over 4
-
-=item Unicode
-
-=item PerlIO
-
-=item Magic
-
-=item Reblessing overloaded objects now works
-
-=item C<strict> now propagates correctly into string evals
-
-=item Other fixes
-
-=item Platform Specific Fixes
-
-=item Smaller fixes
-
-=back
-
-=item New or Changed Diagnostics
-
-=over 4
-
-=item panic: sv_chop %s
-
-=item Maximal count of pending signals (%s) exceeded
-
-=item panic: attempt to call %s in %s
-
-=item FETCHSIZE returned a negative value
-
-=item Can't upgrade %s (%d) to %d
-
-=item %s argument is not a HASH or ARRAY element or a subroutine
-
-=item Cannot make the non-overridable builtin %s fatal
-
-=item Unrecognized character '%s' in column %d
-
-=item Offset outside string
-
-=item Invalid escape in the specified encoding in regexp; marked by <--
-HERE in m/%s/
-
-=item Your machine doesn't support dump/undump.
-
-=back
-
-=item Changed Internals
-
-=over 4
-
-=item Macro cleanups
-
-=back
-
-=item New Tests
-
-ext/DynaLoader/t/DynaLoader.t, t/comp/fold.t, t/io/pvbm.t,
-t/lib/proxy_constant_subs.t, t/op/attrhand.t, t/op/dbm.t,
-t/op/inccode-tie.t, t/op/incfilter.t, t/op/kill0.t, t/op/qrstack.t,
-t/op/qr.t, t/op/regexp_qr_embed.t, t/op/regexp_qr.t, t/op/rxcode.t,
-t/op/studytied.t, t/op/substT.t, t/op/symbolcache.t, t/op/upgrade.t,
-t/mro/package_aliases.t, t/pod/twice.t, t/run/cloexec.t, t/uni/cache.t,
-t/uni/chr.t, t/uni/greek.t, t/uni/latin2.t, t/uni/overload.t, t/uni/tie.t
-
-=item Known Problems
-
-=item Platform Specific Notes
-
-=over 4
-
-=item Win32
-
-=item OS/2
-
-=item VMS
-
-=back
-
-=item Obituary
-
-=item Acknowledgements
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl588delta - what is new for perl v5.8.8
-
-=over 4
-
-=item DESCRIPTION
-
-=item Incompatible Changes
-
-=item Core Enhancements
-
-=item Modules and Pragmata
-
-=item Utility Changes
-
-=over 4
-
-=item C<h2xs> enhancements
-
-=item C<perlivp> enhancements
-
-=back
-
-=item New Documentation
-
-=item Performance Enhancements
-
-=item Installation and Configuration Improvements
-
-=item Selected Bug Fixes
-
-=over 4
-
-=item no warnings 'category' works correctly with -w
-
-=item Remove over-optimisation
-
-=item sprintf() fixes
-
-=item Debugger and Unicode slowdown
-
-=item Smaller fixes
-
-=back
-
-=item New or Changed Diagnostics
-
-=over 4
-
-=item Attempt to set length of freed array
-
-=item Non-string passed as bitmask
-
-=item Search pattern not terminated or ternary operator parsed as search
-pattern
-
-=back
-
-=item Changed Internals
-
-=item Platform Specific Problems
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl587delta - what is new for perl v5.8.7
-
-=over 4
-
-=item DESCRIPTION
-
-=item Incompatible Changes
-
-=item Core Enhancements
-
-=over 4
-
-=item Unicode Character Database 4.1.0
-
-=item suidperl less insecure
-
-=item Optional site customization script
-
-=item C<Config.pm> is now much smaller.
-
-=back
-
-=item Modules and Pragmata
-
-=item Utility Changes
-
-=over 4
-
-=item find2perl enhancements
-
-=back
-
-=item Performance Enhancements
-
-=item Installation and Configuration Improvements
-
-=item Selected Bug Fixes
-
-=item New or Changed Diagnostics
-
-=item Changed Internals
-
-=item Known Problems
-
-=item Platform Specific Problems
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl586delta - what is new for perl v5.8.6
-
-=over 4
-
-=item DESCRIPTION
-
-=item Incompatible Changes
-
-=item Core Enhancements
-
-=item Modules and Pragmata
-
-=item Utility Changes
-
-=item Performance Enhancements
-
-=item Selected Bug Fixes
-
-=item New or Changed Diagnostics
-
-=item Changed Internals
-
-=item New Tests
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl585delta - what is new for perl v5.8.5
-
-=over 4
-
-=item DESCRIPTION
-
-=item Incompatible Changes
-
-=item Core Enhancements
-
-=item Modules and Pragmata
-
-=item Utility Changes
-
-=over 4
-
-=item Perl's debugger
-
-=item h2ph
-
-=back
-
-=item Installation and Configuration Improvements
-
-=item Selected Bug Fixes
-
-=item New or Changed Diagnostics
-
-=item Changed Internals
-
-=item Known Problems
-
-=item Platform Specific Problems
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl584delta - what is new for perl v5.8.4
-
-=over 4
-
-=item DESCRIPTION
-
-=item Incompatible Changes
-
-=item Core Enhancements
-
-=over 4
-
-=item Malloc wrapping
-
-=item Unicode Character Database 4.0.1
-
-=item suidperl less insecure
-
-=item format
-
-=back
-
-=item Modules and Pragmata
-
-=over 4
-
-=item Updated modules
-
-Attribute::Handlers, B, Benchmark, CGI, Carp, Cwd, Exporter, File::Find,
-IO, IPC::Open3, Local::Maketext, Math::BigFloat, Math::BigInt,
-Math::BigRat, MIME::Base64, ODBM_File, POSIX, Shell, Socket, Storable,
-Switch, Sys::Syslog, Term::ANSIColor, Time::HiRes, Unicode::UCD, Win32,
-base, open, threads, utf8
-
-=back
-
-=item Performance Enhancements
-
-=item Utility Changes
-
-=item Installation and Configuration Improvements
-
-=item Selected Bug Fixes
-
-=item New or Changed Diagnostics
-
-=item Changed Internals
-
-=item Future Directions
-
-=item Platform Specific Problems
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl583delta - what is new for perl v5.8.3
-
-=over 4
-
-=item DESCRIPTION
-
-=item Incompatible Changes
-
-=item Core Enhancements
-
-=item Modules and Pragmata
-
-CGI, Cwd, Digest, Digest::MD5, Encode, File::Spec, FindBin, List::Util,
-Math::BigInt, PodParser, Pod::Perldoc, POSIX, Unicode::Collate,
-Unicode::Normalize, Test::Harness, threads::shared
-
-=item Utility Changes
-
-=item New Documentation
-
-=item Installation and Configuration Improvements
-
-=item Selected Bug Fixes
-
-=item New or Changed Diagnostics
-
-=item Changed Internals
-
-=item Configuration and Building
-
-=item Platform Specific Problems
-
-=item Known Problems
-
-=item Future Directions
-
-=item Obituary
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl582delta - what is new for perl v5.8.2
-
-=over 4
-
-=item DESCRIPTION
-
-=item Incompatible Changes
-
-=item Core Enhancements
-
-=over 4
-
-=item Hash Randomisation
-
-=item Threading
-
-=back
-
-=item Modules and Pragmata
-
-=over 4
-
-=item Updated Modules And Pragmata
-
-Devel::PPPort, Digest::MD5, I18N::LangTags, libnet, MIME::Base64,
-Pod::Perldoc, strict, Tie::Hash, Time::HiRes, Unicode::Collate,
-Unicode::Normalize, UNIVERSAL
-
-=back
-
-=item Selected Bug Fixes
-
-=item Changed Internals
-
-=item Platform Specific Problems
-
-=item Future Directions
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl581delta - what is new for perl v5.8.1
-
-=over 4
-
-=item DESCRIPTION
-
-=item Incompatible Changes
-
-=over 4
-
-=item Hash Randomisation
-
-=item UTF-8 On Filehandles No Longer Activated By Locale
-
-=item Single-number v-strings are no longer v-strings before "=>"
-
-=item (Win32) The -C Switch Has Been Repurposed
-
-=item (Win32) The /d Switch Of cmd.exe
-
-=back
-
-=item Core Enhancements
-
-=over 4
-
-=item UTF-8 no longer default under UTF-8 locales
-
-=item Unsafe signals again available
-
-=item Tied Arrays with Negative Array Indices
-
-=item local ${$x}
-
-=item Unicode Character Database 4.0.0
-
-=item Deprecation Warnings
-
-=item Miscellaneous Enhancements
-
-=back
-
-=item Modules and Pragmata
-
-=over 4
-
-=item Updated Modules And Pragmata
-
-base, B::Bytecode, B::Concise, B::Deparse, Benchmark, ByteLoader, bytes,
-CGI, charnames, CPAN, Data::Dumper, DB_File, Devel::PPPort, Digest::MD5,
-Encode, fields, libnet, Math::BigInt, MIME::Base64, NEXT, Net::Ping,
-PerlIO::scalar, podlators, Pod::LaTeX, PodParsers, Pod::Perldoc,
-Scalar::Util, Storable, strict, Term::ANSIcolor, Test::Harness, Test::More,
-Test::Simple, Text::Balanced, Time::HiRes, threads, threads::shared,
-Unicode::Collate, Unicode::Normalize, Win32::GetFolderPath,
-Win32::GetOSVersion
-
-=back
-
-=item Utility Changes
-
-=item New Documentation
-
-=item Installation and Configuration Improvements
-
-=over 4
-
-=item Platform-specific enhancements
-
-=back
-
-=item Selected Bug Fixes
-
-=over 4
-
-=item Closures, eval and lexicals
-
-=item Generic fixes
-
-=item Platform-specific fixes
-
-=back
-
-=item New or Changed Diagnostics
-
-=over 4
-
-=item Changed "A thread exited while %d threads were running"
-
-=item Removed "Attempt to clear a restricted hash"
-
-=item New "Illegal declaration of anonymous subroutine"
-
-=item Changed "Invalid range "%s" in transliteration operator"
-
-=item New "Missing control char name in \c"
-
-=item New "Newline in left-justified string for %s"
-
-=item New "Possible precedence problem on bitwise %c operator"
-
-=item New "Pseudo-hashes are deprecated"
-
-=item New "read() on %s filehandle %s"
-
-=item New "5.005 threads are deprecated"
-
-=item New "Tied variable freed while still in use"
-
-=item New "To%s: illegal mapping '%s'"
-
-=item New "Use of freed value in iteration"
-
-=back
-
-=item Changed Internals
-
-=item New Tests
-
-=item Known Problems
-
-=over 4
-
-=item Tied hashes in scalar context
-
-=item Net::Ping 450_service and 510_ping_udp failures
-
-=item B::C
-
-=back
-
-=item Platform Specific Problems
-
-=over 4
-
-=item EBCDIC Platforms
-
-=item Cygwin 1.5 problems
-
-=item HP-UX: HP cc warnings about sendfile and sendpath
-
-=item IRIX: t/uni/tr_7jis.t falsely failing
-
-=item Mac OS X: no usemymalloc
-
-=item Tru64: No threaded builds with GNU cc (gcc)
-
-=item Win32: sysopen, sysread, syswrite
-
-=back
-
-=item Future Directions
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=back
-
-=head2 perl58delta - what is new for perl v5.8.0
-
-=over 4
-
-=item DESCRIPTION
-
-=item Highlights In 5.8.0
-
-=item Incompatible Changes
-
-=over 4
-
-=item Binary Incompatibility
-
-=item 64-bit platforms and malloc
-
-=item AIX Dynaloading
-
-=item Attributes for C<my> variables now handled at run-time
-
-=item Socket Extension Dynamic in VMS
-
-=item IEEE-format Floating Point Default on OpenVMS Alpha
-
-=item New Unicode Semantics (no more C<use utf8>, almost)
-
-=item New Unicode Properties
-
-=item REF(...) Instead Of SCALAR(...)
-
-=item pack/unpack D/F recycled
-
-=item glob() now returns filenames in alphabetical order
-
-=item Deprecations
-
-=back
-
-=item Core Enhancements
-
-=over 4
-
-=item Unicode Overhaul
-
-=item PerlIO is Now The Default
-
-=item ithreads
-
-=item Restricted Hashes
-
-=item Safe Signals
-
-=item Understanding of Numbers
-
-=item Arrays now always interpolate into double-quoted strings [561]
-
-=item Miscellaneous Changes
-
-=back
-
-=item Modules and Pragmata
-
-=over 4
-
-=item New Modules and Pragmata
-
-=item Updated And Improved Modules and Pragmata
-
-=back
-
-=item Utility Changes
-
-=item New Documentation
-
-=item Performance Enhancements
-
-=item Installation and Configuration Improvements
-
-=over 4
-
-=item Generic Improvements
-
-=item New Or Improved Platforms
-
-=back
-
-=item Selected Bug Fixes
-
-=over 4
-
-=item Platform Specific Changes and Fixes
-
-=back
-
-=item New or Changed Diagnostics
-
-=item Changed Internals
-
-=item Security Vulnerability Closed [561]
-
-=item New Tests
-
-=item Known Problems
-
-=over 4
-
-=item The Compiler Suite Is Still Very Experimental
-
-=item Localising Tied Arrays and Hashes Is Broken
-
-=item Building Extensions Can Fail Because Of Largefiles
-
-=item Modifying $_ Inside for(..)
-
-=item mod_perl 1.26 Doesn't Build With Threaded Perl
-
-=item lib/ftmp-security tests warn 'system possibly insecure'
-
-=item libwww-perl (LWP) fails base/date #51
-
-=item PDL failing some tests
-
-=item Perl_get_sv
-
-=item Self-tying Problems
-
-=item ext/threads/t/libc
-
-=item Failure of Thread (5.005-style) tests
-
-=item Timing problems
-
-=item Tied/Magical Array/Hash Elements Do Not Autovivify
-
-=item Unicode in package/class and subroutine names does not work
-
-=back
-
-=item Platform Specific Problems
-
-=over 4
-
-=item AIX
-
-=item Alpha systems with old gccs fail several tests
-
-=item AmigaOS
-
-=item BeOS
-
-=item Cygwin "unable to remap"
-
-=item Cygwin ndbm tests fail on FAT
-
-=item DJGPP Failures
-
-=item FreeBSD built with ithreads coredumps reading large directories
-
-=item FreeBSD Failing locale Test 117 For ISO 8859-15 Locales
-
-=item IRIX fails ext/List/Util/t/shuffle.t or Digest::MD5
-
-=item HP-UX lib/posix Subtest 9 Fails When LP64-Configured
-
-=item Linux with glibc 2.2.5 fails t/op/int subtest #6 with -Duse64bitint
-
-=item Linux With Sfio Fails op/misc Test 48
-
-=item Mac OS X
-
-=item Mac OS X dyld undefined symbols
-
-=item OS/2 Test Failures
-
-=item op/sprintf tests 91, 129, and 130
-
-=item SCO
-
-=item Solaris 2.5
-
-=item Solaris x86 Fails Tests With -Duse64bitint
-
-=item SUPER-UX (NEC SX)
-
-=item Term::ReadKey not working on Win32
-
-=item UNICOS/mk
-
-=item UTS
-
-=item VOS (Stratus)
-
-=item VMS
-
-=item Win32
-
-=item XML::Parser not working
-
-=item z/OS (OS/390)
-
-=item Unicode Support on EBCDIC Still Spotty
-
-=item Seen In Perl 5.7 But Gone Now
-
-=back
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=item HISTORY
-
-=back
-
-=head2 perl561delta - what's new for perl v5.6.1
-
-=over 4
-
-=item DESCRIPTION
-
-=item Summary of changes between 5.6.0 and 5.6.1
-
-=over 4
-
-=item Security Issues
-
-=item Core bug fixes
-
-C<UNIVERSAL::isa()>, Memory leaks, Numeric conversions, qw(a\\b), caller(),
-Bugs in regular expressions, "slurp" mode, Autovivification of symbolic
-references to special variables, Lexical warnings, Spurious warnings and
-errors, glob(), Tainting, sort(), #line directives, Subroutine prototypes,
-map(), Debugger, PERL5OPT, chop(), Unicode support, 64-bit support,
-Compiler, Lvalue subroutines, IO::Socket, File::Find, xsubpp, C<no
-Module;>, Tests
-
-=item Core features
-
-=item Configuration issues
-
-=item Documentation
-
-=item Bundled modules
-
-B::Concise, File::Temp, Pod::LaTeX, Pod::Text::Overstrike, CGI, CPAN,
-Class::Struct, DB_File, Devel::Peek, File::Find, Getopt::Long, IO::Poll,
-IPC::Open3, Math::BigFloat, Math::Complex, Net::Ping, Opcode, Pod::Parser,
-Pod::Text, SDBM_File, Sys::Syslog, Tie::RefHash, Tie::SubstrHash
-
-=item Platform-specific improvements
-
-NCR MP-RAS, NonStop-UX
-
-=back
-
-=item Core Enhancements
-
-=over 4
-
-=item Interpreter cloning, threads, and concurrency
-
-=item Lexically scoped warning categories
-
-=item Unicode and UTF-8 support
-
-=item Support for interpolating named characters
-
-=item "our" declarations
-
-=item Support for strings represented as a vector of ordinals
-
-=item Improved Perl version numbering system
-
-=item New syntax for declaring subroutine attributes
-
-=item File and directory handles can be autovivified
-
-=item open() with more than two arguments
-
-=item 64-bit support
-
-=item Large file support
-
-=item Long doubles
-
-=item "more bits"
-
-=item Enhanced support for sort() subroutines
-
-=item C<sort $coderef @foo> allowed
-
-=item File globbing implemented internally
-
-=item Support for CHECK blocks
-
-=item POSIX character class syntax [: :] supported
-
-=item Better pseudo-random number generator
-
-=item Improved C<qw//> operator
-
-=item Better worst-case behavior of hashes
-
-=item pack() format 'Z' supported
-
-=item pack() format modifier '!' supported
-
-=item pack() and unpack() support counted strings
-
-=item Comments in pack() templates
-
-=item Weak references
-
-=item Binary numbers supported
-
-=item Lvalue subroutines
-
-=item Some arrows may be omitted in calls through references
-
-=item Boolean assignment operators are legal lvalues
-
-=item exists() is supported on subroutine names
-
-=item exists() and delete() are supported on array elements
-
-=item Pseudo-hashes work better
-
-=item Automatic flushing of output buffers
-
-=item Better diagnostics on meaningless filehandle operations
-
-=item Where possible, buffered data discarded from duped input filehandle
-
-=item eof() has the same old magic as <>
-
-=item binmode() can be used to set :crlf and :raw modes
-
-=item C<-T> filetest recognizes UTF-8 encoded files as "text"
-
-=item system(), backticks and pipe open now reflect exec() failure
-
-=item Improved diagnostics
-
-=item Diagnostics follow STDERR
-
-=item More consistent close-on-exec behavior
-
-=item syswrite() ease-of-use
-
-=item Better syntax checks on parenthesized unary operators
-
-=item Bit operators support full native integer width
-
-=item Improved security features
-
-=item More functional bareword prototype (*)
-
-=item C<require> and C<do> may be overridden
-
-=item $^X variables may now have names longer than one character
-
-=item New variable $^C reflects C<-c> switch
-
-=item New variable $^V contains Perl version as a string
-
-=item Optional Y2K warnings
-
-=item Arrays now always interpolate into double-quoted strings
-
-=item @- and @+ provide starting/ending offsets of regex submatches
-
-=back
-
-=item Modules and Pragmata
-
-=over 4
-
-=item Modules
-
-attributes, B, Benchmark, ByteLoader, constant, charnames, Data::Dumper,
-DB, DB_File, Devel::DProf, Devel::Peek, Dumpvalue, DynaLoader, English,
-Env, Fcntl, File::Compare, File::Find, File::Glob, File::Spec,
-File::Spec::Functions, Getopt::Long, IO, JPL, lib, Math::BigInt,
-Math::Complex, Math::Trig, Pod::Parser, Pod::InputObjects, Pod::Checker,
-podchecker, Pod::ParseUtils, Pod::Find, Pod::Select, podselect, Pod::Usage,
-pod2usage, Pod::Text and Pod::Man, SDBM_File, Sys::Syslog, Sys::Hostname,
-Term::ANSIColor, Time::Local, Win32, XSLoader, DBM Filters
-
-=item Pragmata
-
-=back
-
-=item Utility Changes
-
-=over 4
-
-=item dprofpp
-
-=item find2perl
-
-=item h2xs
-
-=item perlcc
-
-=item perldoc
-
-=item The Perl Debugger
-
-=back
-
-=item Improved Documentation
-
-perlapi.pod, perlboot.pod, perlcompile.pod, perldbmfilter.pod,
-perldebug.pod, perldebguts.pod, perlfork.pod, perlfilter.pod, perlhack.pod,
-perlintern.pod, perllexwarn.pod, perlnumber.pod, perlopentut.pod,
-perlreftut.pod, perltootc.pod, perltodo.pod, perlunicode.pod
-
-=item Performance enhancements
-
-=over 4
-
-=item Simple sort() using { $a <=> $b } and the like are optimized
-
-=item Optimized assignments to lexical variables
-
-=item Faster subroutine calls
-
-=item delete(), each(), values() and hash iteration are faster
-
-=back
-
-=item Installation and Configuration Improvements
-
-=over 4
-
-=item -Dusethreads means something different
-
-=item New Configure flags
-
-=item Threadedness and 64-bitness now more daring
-
-=item Long Doubles
-
-=item -Dusemorebits
-
-=item -Duselargefiles
-
-=item installusrbinperl
-
-=item SOCKS support
-
-=item C<-A> flag
-
-=item Enhanced Installation Directories
-
-=item gcc automatically tried if 'cc' does not seem to be working
-
-=back
-
-=item Platform specific changes
-
-=over 4
-
-=item Supported platforms
-
-=item DOS
-
-=item OS390 (OpenEdition MVS)
-
-=item VMS
-
-=item Win32
-
-=back
-
-=item Significant bug fixes
-
-=over 4
-
-=item <HANDLE> on empty files
-
-=item C<eval '...'> improvements
-
-=item All compilation errors are true errors
-
-=item Implicitly closed filehandles are safer
-
-=item Behavior of list slices is more consistent
-
-=item C<(\$)> prototype and C<$foo{a}>
-
-=item C<goto &sub> and AUTOLOAD
-
-=item C<-bareword> allowed under C<use integer>
-
-=item Failures in DESTROY()
-
-=item Locale bugs fixed
-
-=item Memory leaks
-
-=item Spurious subroutine stubs after failed subroutine calls
-
-=item Taint failures under C<-U>
-
-=item END blocks and the C<-c> switch
-
-=item Potential to leak DATA filehandles
-
-=back
-
-=item New or Changed Diagnostics
-
-"%s" variable %s masks earlier declaration in same %s, "my sub" not yet
-implemented, "our" variable %s redeclared, '!' allowed only after types %s,
-/ cannot take a count, / must be followed by a, A or Z, / must be followed
-by a*, A* or Z*, / must follow a numeric type, /%s/: Unrecognized escape
-\\%c passed through, /%s/: Unrecognized escape \\%c in character class
-passed through, /%s/ should probably be written as "%s", %s() called too
-early to check prototype, %s argument is not a HASH or ARRAY element, %s
-argument is not a HASH or ARRAY element or slice, %s argument is not a
-subroutine name, %s package attribute may clash with future reserved word:
-%s, (in cleanup) %s, <> should be quotes, Attempt to join self, Bad evalled
-substitution pattern, Bad realloc() ignored, Bareword found in conditional,
-Binary number > 0b11111111111111111111111111111111 non-portable, Bit vector
-size > 32 non-portable, Buffer overflow in prime_env_iter: %s, Can't check
-filesystem of script "%s", Can't declare class for non-scalar %s in "%s",
-Can't declare %s in "%s", Can't ignore signal CHLD, forcing to default,
-Can't modify non-lvalue subroutine call, Can't read CRTL environ, Can't
-remove %s: %s, skipping file, Can't return %s from lvalue subroutine, Can't
-weaken a nonreference, Character class [:%s:] unknown, Character class
-syntax [%s] belongs inside character classes, Constant is not %s reference,
-constant(%s): %s, CORE::%s is not a keyword, defined(@array) is deprecated,
-defined(%hash) is deprecated, Did not produce a valid header, (Did you mean
-"local" instead of "our"?), Document contains no data, entering effective
-%s failed, false [] range "%s" in regexp, Filehandle %s opened only for
-output, flock() on closed filehandle %s, Global symbol "%s" requires
-explicit package name, Hexadecimal number > 0xffffffff non-portable,
-Ill-formed CRTL environ value "%s", Ill-formed message in prime_env_iter:
-|%s|, Illegal binary digit %s, Illegal binary digit %s ignored, Illegal
-number of bits in vec, Integer overflow in %s number, Invalid %s attribute:
-%s, Invalid %s attributes: %s, invalid [] range "%s" in regexp, Invalid
-separator character %s in attribute list, Invalid separator character %s in
-subroutine attribute list, leaving effective %s failed, Lvalue subs
-returning %s not implemented yet, Method %s not permitted, Missing
-%sbrace%s on \N{}, Missing command in piped open, Missing name in "my sub",
-No %s specified for -%c, No package name allowed for variable %s in "our",
-No space allowed after -%c, no UTC offset information; assuming local time
-is UTC, Octal number > 037777777777 non-portable, panic: del_backref,
-panic: kid popen errno read, panic: magic_killbackrefs, Parentheses missing
-around "%s" list, Possible unintended interpolation of %s in string,
-Possible Y2K bug: %s, pragma "attrs" is deprecated, use "sub NAME : ATTRS"
-instead, Premature end of script headers, Repeat count in pack overflows,
-Repeat count in unpack overflows, realloc() of freed memory ignored,
-Reference is already weak, setpgrp can't take arguments, Strange *+?{} on
-zero-length expression, switching effective %s is not implemented, This
-Perl can't reset CRTL environ elements (%s), This Perl can't set CRTL
-environ elements (%s=%s), Too late to run %s block, Unknown open() mode
-'%s', Unknown process %x sent message to prime_env_iter: %s, Unrecognized
-escape \\%c passed through, Unterminated attribute parameter in attribute
-list, Unterminated attribute list, Unterminated attribute parameter in
-subroutine attribute list, Unterminated subroutine attribute list, Value of
-CLI symbol "%s" too long, Version number must be a constant number
-
-=item New tests
-
-=item Incompatible Changes
-
-=over 4
-
-=item Perl Source Incompatibilities
-
-CHECK is a new keyword, Treatment of list slices of undef has changed,
-Format of $English::PERL_VERSION is different, Literals of the form
-C<1.2.3> parse differently, Possibly changed pseudo-random number
-generator, Hashing function for hash keys has changed, C<undef> fails on
-read only values, Close-on-exec bit may be set on pipe and socket handles,
-Writing C<"$$1"> to mean C<"${$}1"> is unsupported, delete(), each(),
-values() and C<\(%h)>, vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS,
-Text of some diagnostic output has changed, C<%@> has been removed,
-Parenthesized not() behaves like a list operator, Semantics of bareword
-prototype C<(*)> have changed, Semantics of bit operators may have changed
-on 64-bit platforms, More builtins taint their results
-
-=item C Source Incompatibilities
-
-C<PERL_POLLUTE>, C<PERL_IMPLICIT_CONTEXT>, C<PERL_POLLUTE_MALLOC>
-
-=item Compatible C Source API Changes
-
-C<PATCHLEVEL> is now C<PERL_VERSION>
-
-=item Binary Incompatibilities
-
-=back
-
-=item Known Problems
-
-=over 4
-
-=item Localizing a tied hash element may leak memory
-
-=item Known test failures
-
-=item EBCDIC platforms not fully supported
-
-=item UNICOS/mk CC failures during Configure run
-
-=item Arrow operator and arrays
-
-=item Experimental features
-
-Threads, Unicode, 64-bit support, Lvalue subroutines, Weak references, The
-pseudo-hash data type, The Compiler suite, Internal implementation of file
-globbing, The DB module, The regular expression code constructs:
-
-=back
-
-=item Obsolete Diagnostics
-
-Character class syntax [: :] is reserved for future extensions, Ill-formed
-logical name |%s| in prime_env_iter, In string, @%s now must be written as
-\@%s, Probable precedence problem on %s, regexp too big, Use of "$$<digit>"
-to mean "${$}<digit>" is deprecated
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=item HISTORY
-
-=back
-
-=head2 perl56delta - what's new for perl v5.6.0
-
-=over 4
-
-=item DESCRIPTION
-
-=item Core Enhancements
-
-=over 4
-
-=item Interpreter cloning, threads, and concurrency
-
-=item Lexically scoped warning categories
-
-=item Unicode and UTF-8 support
-
-=item Support for interpolating named characters
-
-=item "our" declarations
-
-=item Support for strings represented as a vector of ordinals
-
-=item Improved Perl version numbering system
-
-=item New syntax for declaring subroutine attributes
-
-=item File and directory handles can be autovivified
-
-=item open() with more than two arguments
-
-=item 64-bit support
-
-=item Large file support
-
-=item Long doubles
-
-=item "more bits"
-
-=item Enhanced support for sort() subroutines
-
-=item C<sort $coderef @foo> allowed
-
-=item File globbing implemented internally
-
-=item Support for CHECK blocks
-
-=item POSIX character class syntax [: :] supported
-
-=item Better pseudo-random number generator
-
-=item Improved C<qw//> operator
-
-=item Better worst-case behavior of hashes
-
-=item pack() format 'Z' supported
-
-=item pack() format modifier '!' supported
-
-=item pack() and unpack() support counted strings
-
-=item Comments in pack() templates
-
-=item Weak references
-
-=item Binary numbers supported
-
-=item Lvalue subroutines
-
-=item Some arrows may be omitted in calls through references
-
-=item Boolean assignment operators are legal lvalues
-
-=item exists() is supported on subroutine names
-
-=item exists() and delete() are supported on array elements
-
-=item Pseudo-hashes work better
-
-=item Automatic flushing of output buffers
-
-=item Better diagnostics on meaningless filehandle operations
-
-=item Where possible, buffered data discarded from duped input filehandle
-
-=item eof() has the same old magic as <>
-
-=item binmode() can be used to set :crlf and :raw modes
-
-=item C<-T> filetest recognizes UTF-8 encoded files as "text"
-
-=item system(), backticks and pipe open now reflect exec() failure
-
-=item Improved diagnostics
-
-=item Diagnostics follow STDERR
-
-=item More consistent close-on-exec behavior
-
-=item syswrite() ease-of-use
-
-=item Better syntax checks on parenthesized unary operators
-
-=item Bit operators support full native integer width
-
-=item Improved security features
-
-=item More functional bareword prototype (*)
-
-=item C<require> and C<do> may be overridden
-
-=item $^X variables may now have names longer than one character
-
-=item New variable $^C reflects C<-c> switch
-
-=item New variable $^V contains Perl version as a string
-
-=item Optional Y2K warnings
-
-=item Arrays now always interpolate into double-quoted strings
-
-=item @- and @+ provide starting/ending offsets of regex matches
-
-=back
-
-=item Modules and Pragmata
-
-=over 4
-
-=item Modules
-
-attributes, B, Benchmark, ByteLoader, constant, charnames, Data::Dumper,
-DB, DB_File, Devel::DProf, Devel::Peek, Dumpvalue, DynaLoader, English,
-Env, Fcntl, File::Compare, File::Find, File::Glob, File::Spec,
-File::Spec::Functions, Getopt::Long, IO, JPL, lib, Math::BigInt,
-Math::Complex, Math::Trig, Pod::Parser, Pod::InputObjects, Pod::Checker,
-podchecker, Pod::ParseUtils, Pod::Find, Pod::Select, podselect, Pod::Usage,
-pod2usage, Pod::Text and Pod::Man, SDBM_File, Sys::Syslog, Sys::Hostname,
-Term::ANSIColor, Time::Local, Win32, XSLoader, DBM Filters
-
-=item Pragmata
-
-=back
-
-=item Utility Changes
-
-=over 4
-
-=item dprofpp
-
-=item find2perl
-
-=item h2xs
-
-=item perlcc
-
-=item perldoc
-
-=item The Perl Debugger
-
-=back
-
-=item Improved Documentation
-
-perlapi.pod, perlboot.pod, perlcompile.pod, perldbmfilter.pod,
-perldebug.pod, perldebguts.pod, perlfork.pod, perlfilter.pod, perlhack.pod,
-perlintern.pod, perllexwarn.pod, perlnumber.pod, perlopentut.pod,
-perlreftut.pod, perltootc.pod, perltodo.pod, perlunicode.pod
-
-=item Performance enhancements
-
-=over 4
-
-=item Simple sort() using { $a <=> $b } and the like are optimized
-
-=item Optimized assignments to lexical variables
-
-=item Faster subroutine calls
-
-=item delete(), each(), values() and hash iteration are faster
-
-=back
-
-=item Installation and Configuration Improvements
-
-=over 4
-
-=item -Dusethreads means something different
-
-=item New Configure flags
-
-=item Threadedness and 64-bitness now more daring
-
-=item Long Doubles
-
-=item -Dusemorebits
-
-=item -Duselargefiles
-
-=item installusrbinperl
-
-=item SOCKS support
-
-=item C<-A> flag
-
-=item Enhanced Installation Directories
-
-=back
-
-=item Platform specific changes
-
-=over 4
-
-=item Supported platforms
-
-=item DOS
-
-=item OS390 (OpenEdition MVS)
-
-=item VMS
-
-=item Win32
-
-=back
-
-=item Significant bug fixes
-
-=over 4
-
-=item <HANDLE> on empty files
-
-=item C<eval '...'> improvements
-
-=item All compilation errors are true errors
-
-=item Implicitly closed filehandles are safer
-
-=item Behavior of list slices is more consistent
-
-=item C<(\$)> prototype and C<$foo{a}>
-
-=item C<goto &sub> and AUTOLOAD
-
-=item C<-bareword> allowed under C<use integer>
-
-=item Failures in DESTROY()
-
-=item Locale bugs fixed
-
-=item Memory leaks
-
-=item Spurious subroutine stubs after failed subroutine calls
-
-=item Taint failures under C<-U>
-
-=item END blocks and the C<-c> switch
-
-=item Potential to leak DATA filehandles
-
-=back
-
-=item New or Changed Diagnostics
-
-"%s" variable %s masks earlier declaration in same %s, "my sub" not yet
-implemented, "our" variable %s redeclared, '!' allowed only after types %s,
-/ cannot take a count, / must be followed by a, A or Z, / must be followed
-by a*, A* or Z*, / must follow a numeric type, /%s/: Unrecognized escape
-\\%c passed through, /%s/: Unrecognized escape \\%c in character class
-passed through, /%s/ should probably be written as "%s", %s() called too
-early to check prototype, %s argument is not a HASH or ARRAY element, %s
-argument is not a HASH or ARRAY element or slice, %s argument is not a
-subroutine name, %s package attribute may clash with future reserved word:
-%s, (in cleanup) %s, <> should be quotes, Attempt to join self, Bad evalled
-substitution pattern, Bad realloc() ignored, Bareword found in conditional,
-Binary number > 0b11111111111111111111111111111111 non-portable, Bit vector
-size > 32 non-portable, Buffer overflow in prime_env_iter: %s, Can't check
-filesystem of script "%s", Can't declare class for non-scalar %s in "%s",
-Can't declare %s in "%s", Can't ignore signal CHLD, forcing to default,
-Can't modify non-lvalue subroutine call, Can't read CRTL environ, Can't
-remove %s: %s, skipping file, Can't return %s from lvalue subroutine, Can't
-weaken a nonreference, Character class [:%s:] unknown, Character class
-syntax [%s] belongs inside character classes, Constant is not %s reference,
-constant(%s): %s, CORE::%s is not a keyword, defined(@array) is deprecated,
-defined(%hash) is deprecated, Did not produce a valid header, (Did you mean
-"local" instead of "our"?), Document contains no data, entering effective
-%s failed, false [] range "%s" in regexp, Filehandle %s opened only for
-output, flock() on closed filehandle %s, Global symbol "%s" requires
-explicit package name, Hexadecimal number > 0xffffffff non-portable,
-Ill-formed CRTL environ value "%s", Ill-formed message in prime_env_iter:
-|%s|, Illegal binary digit %s, Illegal binary digit %s ignored, Illegal
-number of bits in vec, Integer overflow in %s number, Invalid %s attribute:
-%s, Invalid %s attributes: %s, invalid [] range "%s" in regexp, Invalid
-separator character %s in attribute list, Invalid separator character %s in
-subroutine attribute list, leaving effective %s failed, Lvalue subs
-returning %s not implemented yet, Method %s not permitted, Missing
-%sbrace%s on \N{}, Missing command in piped open, Missing name in "my sub",
-No %s specified for -%c, No package name allowed for variable %s in "our",
-No space allowed after -%c, no UTC offset information; assuming local time
-is UTC, Octal number > 037777777777 non-portable, panic: del_backref,
-panic: kid popen errno read, panic: magic_killbackrefs, Parentheses missing
-around "%s" list, Possible unintended interpolation of %s in string,
-Possible Y2K bug: %s, pragma "attrs" is deprecated, use "sub NAME : ATTRS"
-instead, Premature end of script headers, Repeat count in pack overflows,
-Repeat count in unpack overflows, realloc() of freed memory ignored,
-Reference is already weak, setpgrp can't take arguments, Strange *+?{} on
-zero-length expression, switching effective %s is not implemented, This
-Perl can't reset CRTL environ elements (%s), This Perl can't set CRTL
-environ elements (%s=%s), Too late to run %s block, Unknown open() mode
-'%s', Unknown process %x sent message to prime_env_iter: %s, Unrecognized
-escape \\%c passed through, Unterminated attribute parameter in attribute
-list, Unterminated attribute list, Unterminated attribute parameter in
-subroutine attribute list, Unterminated subroutine attribute list, Value of
-CLI symbol "%s" too long, Version number must be a constant number
-
-=item New tests
-
-=item Incompatible Changes
-
-=over 4
-
-=item Perl Source Incompatibilities
-
-CHECK is a new keyword, Treatment of list slices of undef has changed,
-Format of $English::PERL_VERSION is different, Literals of the form
-C<1.2.3> parse differently, Possibly changed pseudo-random number
-generator, Hashing function for hash keys has changed, C<undef> fails on
-read only values, Close-on-exec bit may be set on pipe and socket handles,
-Writing C<"$$1"> to mean C<"${$}1"> is unsupported, delete(), each(),
-values() and C<\(%h)>, vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS,
-Text of some diagnostic output has changed, C<%@> has been removed,
-Parenthesized not() behaves like a list operator, Semantics of bareword
-prototype C<(*)> have changed, Semantics of bit operators may have changed
-on 64-bit platforms, More builtins taint their results
-
-=item C Source Incompatibilities
-
-C<PERL_POLLUTE>, C<PERL_IMPLICIT_CONTEXT>, C<PERL_POLLUTE_MALLOC>
-
-=item Compatible C Source API Changes
-
-C<PATCHLEVEL> is now C<PERL_VERSION>
-
-=item Binary Incompatibilities
-
-=back
-
-=item Known Problems
-
-=over 4
-
-=item Thread test failures
-
-=item EBCDIC platforms not supported
-
-=item In 64-bit HP-UX the lib/io_multihomed test may hang
-
-=item NEXTSTEP 3.3 POSIX test failure
-
-=item Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with
-gcc
-
-=item UNICOS/mk CC failures during Configure run
-
-=item Arrow operator and arrays
-
-=item Experimental features
-
-Threads, Unicode, 64-bit support, Lvalue subroutines, Weak references, The
-pseudo-hash data type, The Compiler suite, Internal implementation of file
-globbing, The DB module, The regular expression code constructs:
-
-=back
-
-=item Obsolete Diagnostics
-
-Character class syntax [: :] is reserved for future extensions, Ill-formed
-logical name |%s| in prime_env_iter, In string, @%s now must be written as
-\@%s, Probable precedence problem on %s, regexp too big, Use of "$$<digit>"
-to mean "${$}<digit>" is deprecated
-
-=item Reporting Bugs
-
-=item SEE ALSO
-
-=item HISTORY
-
-=back
-
-=head2 perl5005delta - what's new for perl5.005
-
-=over 4
-
-=item DESCRIPTION
-
-=item About the new versioning system
-
-=item Incompatible Changes
-
-=over 4
-
-=item WARNING: This version is not binary compatible with Perl 5.004.
-
-=item Default installation structure has changed
-
-=item Perl Source Compatibility
-
-=item C Source Compatibility
-
-=item Binary Compatibility
-
-=item Security fixes may affect compatibility
-
-=item Relaxed new mandatory warnings introduced in 5.004
-
-=item Licensing
-
-=back
-
-=item Core Changes
-
-=over 4
-
-=item Threads
-
-=item Compiler
-
-=item Regular Expressions
-
-Many new and improved optimizations, Many bug fixes, New regular expression
-constructs, New operator for precompiled regular expressions, Other
-improvements, Incompatible changes
-
-=item Improved malloc()
-
-=item Quicksort is internally implemented
-
-=item Reliable signals
-
-=item Reliable stack pointers
-
-=item More generous treatment of carriage returns
-
-=item Memory leaks
-
-=item Better support for multiple interpreters
-
-=item Behavior of local() on array and hash elements is now well-defined
-
-=item C<%!> is transparently tied to the L<Errno> module
-
-=item Pseudo-hashes are supported
-
-=item C<EXPR foreach EXPR> is supported
-
-=item Keywords can be globally overridden
-
-=item C<$^E> is meaningful on Win32
-
-=item C<foreach (1..1000000)> optimized
-
-=item C<Foo::> can be used as implicitly quoted package name
-
-=item C<exists $Foo::{Bar::}> tests existence of a package
-
-=item Better locale support
-
-=item Experimental support for 64-bit platforms
-
-=item prototype() returns useful results on builtins
-
-=item Extended support for exception handling
-
-=item Re-blessing in DESTROY() supported for chaining DESTROY() methods
-
-=item All C<printf> format conversions are handled internally
-
-=item New C<INIT> keyword
-
-=item New C<lock> keyword
-
-=item New C<qr//> operator
-
-=item C<our> is now a reserved word
-
-=item Tied arrays are now fully supported
-
-=item Tied handles support is better
-
-=item 4th argument to substr
-
-=item Negative LENGTH argument to splice
-
-=item Magic lvalues are now more magical
-
-=item <> now reads in records
-
-=back
-
-=item Supported Platforms
-
-=over 4
-
-=item New Platforms
-
-=item Changes in existing support
-
-=back
-
-=item Modules and Pragmata
-
-=over 4
-
-=item New Modules
-
-B, Data::Dumper, Dumpvalue, Errno, File::Spec, ExtUtils::Installed,
-ExtUtils::Packlist, Fatal, IPC::SysV, Test, Tie::Array, Tie::Handle,
-Thread, attrs, fields, re
-
-=item Changes in existing modules
-
-Benchmark, Carp, CGI, Fcntl, Math::Complex, Math::Trig, POSIX, DB_File,
-MakeMaker, CPAN, Cwd
-
-=back
-
-=item Utility Changes
-
-=item Documentation Changes
-
-=item New Diagnostics
-
-Ambiguous call resolved as CORE::%s(), qualify as such or use &, Bad index
-while coercing array into hash, Bareword "%s" refers to nonexistent
-package, Can't call method "%s" on an undefined value, Can't check
-filesystem of script "%s" for nosuid, Can't coerce array into hash, Can't
-goto subroutine from an eval-string, Can't localize pseudo-hash element,
-Can't use %%! because Errno.pm is not available, Cannot find an opnumber
-for "%s", Character class syntax [. .] is reserved for future extensions,
-Character class syntax [: :] is reserved for future extensions, Character
-class syntax [= =] is reserved for future extensions, %s: Eval-group in
-insecure regular expression, %s: Eval-group not allowed, use re 'eval', %s:
-Eval-group not allowed at run time, Explicit blessing to '' (assuming
-package main), Illegal hex digit ignored, No such array field, No such
-field "%s" in variable %s of type %s, Out of memory during ridiculously
-large request, Range iterator outside integer range, Recursive inheritance
-detected while looking for method '%s' %s, Reference found where even-sized
-list expected, Undefined value assigned to typeglob, Use of reserved word
-"%s" is deprecated, perl: warning: Setting locale failed
-
-=item Obsolete Diagnostics
-
-Can't mktemp(), Can't write to temp file for B<-e>: %s, Cannot open
-temporary file, regexp too big
-
-=item Configuration Changes
-
-=item BUGS
-
-=item SEE ALSO
-
-=item HISTORY
-
-=back
-
-=head2 perl5004delta - what's new for perl5.004
-
-=over 4
-
-=item DESCRIPTION
-
-=item Supported Environments
-
-=item Core Changes
-
-=over 4
-
-=item List assignment to %ENV works
-
-=item Change to "Can't locate Foo.pm in @INC" error
-
-=item Compilation option: Binary compatibility with 5.003
-
-=item $PERL5OPT environment variable
-
-=item Limitations on B<-M>, B<-m>, and B<-T> options
-
-=item More precise warnings
-
-=item Deprecated: Inherited C<AUTOLOAD> for non-methods
-
-=item Previously deprecated %OVERLOAD is no longer usable
-
-=item Subroutine arguments created only when they're modified
-
-=item Group vector changeable with C<$)>
-
-=item Fixed parsing of $$<digit>, &$<digit>, etc.
-
-=item Fixed localization of $<digit>, $&, etc.
-
-=item No resetting of $. on implicit close
-
-=item C<wantarray> may return undef
-
-=item C<eval EXPR> determines value of EXPR in scalar context
-
-=item Changes to tainting checks
-
-No glob() or <*>, No spawning if tainted $CDPATH, $ENV, $BASH_ENV, No
-spawning if tainted $TERM doesn't look like a terminal name
-
-=item New Opcode module and revised Safe module
-
-=item Embedding improvements
-
-=item Internal change: FileHandle class based on IO::* classes
-
-=item Internal change: PerlIO abstraction interface
-
-=item New and changed syntax
-
-$coderef->(PARAMS)
-
-=item New and changed builtin constants
-
-__PACKAGE__
-
-=item New and changed builtin variables
-
-$^E, $^H, $^M
-
-=item New and changed builtin functions
-
-delete on slices, flock, printf and sprintf, keys as an lvalue, my() in
-Control Structures, pack() and unpack(), sysseek(), use VERSION, use Module
-VERSION LIST, prototype(FUNCTION), srand, $_ as Default, C<m//gc> does not
-reset search position on failure, C<m//x> ignores whitespace before ?*+{},
-nested C<sub{}> closures work now, formats work right on changing lexicals
-
-=item New builtin methods
-
-isa(CLASS), can(METHOD), VERSION( [NEED] )
-
-=item TIEHANDLE now supported
-
-TIEHANDLE classname, LIST, PRINT this, LIST, PRINTF this, LIST, READ this
-LIST, READLINE this, GETC this, DESTROY this
-
-=item Malloc enhancements
-
--DPERL_EMERGENCY_SBRK, -DPACK_MALLOC, -DTWO_POT_OPTIMIZE
-
-=item Miscellaneous efficiency enhancements
-
-=back
-
-=item Support for More Operating Systems
-
-=over 4
-
-=item Win32
-
-=item Plan 9
-
-=item QNX
-
-=item AmigaOS
-
-=back
-
-=item Pragmata
-
-use autouse MODULE => qw(sub1 sub2 sub3), use blib, use blib 'dir', use
-constant NAME => VALUE, use locale, use ops, use vmsish
-
-=item Modules
-
-=over 4
-
-=item Required Updates
-
-=item Installation directories
-
-=item Module information summary
-
-=item Fcntl
-
-=item IO
-
-=item Math::Complex
-
-=item Math::Trig
-
-=item DB_File
-
-=item Net::Ping
-
-=item Object-oriented overrides for builtin operators
-
-=back
-
-=item Utility Changes
-
-=over 4
-
-=item pod2html
-
-Sends converted HTML to standard output
-
-=item xsubpp
-
-C<void> XSUBs now default to returning nothing
-
-=back
-
-=item C Language API Changes
-
-C<gv_fetchmethod> and C<perl_call_sv>, C<perl_eval_pv>, Extended API for
-manipulating hashes
-
-=item Documentation Changes
-
-L<perldelta>, L<perlfaq>, L<perllocale>, L<perltoot>, L<perlapio>,
-L<perlmodlib>, L<perldebug>, L<perlsec>
-
-=item New Diagnostics
-
-"my" variable %s masks earlier declaration in same scope, %s argument is
-not a HASH element or slice, Allocation too large: %lx, Allocation too
-large, Applying %s to %s will act on scalar(%s), Attempt to free
-nonexistent shared string, Attempt to use reference as lvalue in substr,
-Bareword "%s" refers to nonexistent package, Can't redefine active sort
-subroutine %s, Can't use bareword ("%s") as %s ref while "strict refs" in
-use, Cannot resolve method `%s' overloading `%s' in package `%s', Constant
-subroutine %s redefined, Constant subroutine %s undefined, Copy method did
-not return a reference, Died, Exiting pseudo-block via %s, Identifier too
-long, Illegal character %s (carriage return), Illegal switch in PERL5OPT:
-%s, Integer overflow in hex number, Integer overflow in octal number,
-internal error: glob failed, Invalid conversion in %s: "%s", Invalid type
-in pack: '%s', Invalid type in unpack: '%s', Name "%s::%s" used only once:
-possible typo, Null picture in formline, Offset outside string, Out of
-memory!, Out of memory during request for %s, panic: frexp, Possible
-attempt to put comments in qw() list, Possible attempt to separate words
-with commas, Scalar value @%s{%s} better written as $%s{%s}, Stub found
-while resolving method `%s' overloading `%s' in %s, Too late for "B<-T>"
-option, untie attempted while %d inner references still exist, Unrecognized
-character %s, Unsupported function fork, Use of "$$<digit>" to mean
-"${$}<digit>" is deprecated, Value of %s can be "0"; test with defined(),
-Variable "%s" may be unavailable, Variable "%s" will not stay shared,
-Warning: something's wrong, Ill-formed logical name |%s| in prime_env_iter,
-Got an error from DosAllocMem, Malformed PERLLIB_PREFIX, PERL_SH_DIR too
-long, Process terminated by SIG%s
-
-=item BUGS
-
-=item SEE ALSO
-
-=item HISTORY
-
-=back
-
-=head2 perlexperiment - A listing of experimental features in Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Current experiments
-
-fork() emulation, Weak references, Internal file glob, 64-bit support, die
-accepts a reference, Unicode support, -Dusemultiplicity -Dusethreads, Long
-Doubles Still Don't Work In Solaris, GetOpt::Long Options can now take
-multiple values at once (experimental), 5.005-style threading,
-Test::Harness::Straps, perlcc, C<our> can now have an experimental optional
-attribute C<unique>, Assertions, Linux abstract Unix domain sockets,
-L<Pod::HTML2Pod|Pod::HTML2Pod>, L<Pod::PXML|Pod::PXML>, threads, The <:pop>
-IO pseudolayer, The <:win32> IO pseudolayer, MLDBM, internal functions with
-M flag, lex_start API, internal API for C<%H>, av_create_and_push,
-av_create_and_unshift_one, av_create_and_unshift_one, PL_keyword_plugin,
-hv_iternext_flags, lex_bufutf8, lex_discard_to, lex_grow_linestr,
-lex_next_chunk, lex_peek_unichar, lex_read_space, lex_read_to,
-lex_read_unichar, lex_stuff_pv, lex_stuff_pvn, lex_stuff_pvs, lex_stuff_sv,
-lex_unstuff, parse_fullstmt, parse_stmtseq, PL_parser-E<gt>bufend,
-PL_parser-E<gt>bufptr, PL_parser-E<gt>linestart, PL_parser-E<gt>linestr,
-Perl_signbit, pad_findmy, sv_utf8_decode, sv_utf8_downgrade,
-bytes_from_utf8, bytes_to_utf8, utf8_to_bytes, DB module, The pseudo-hash
-data type, Lvalue subroutines, There is an C<installhtml> target in the
-Makefile, Unicode in Perl on EBCDIC, C<(?{code})>, C<(??{ code })>,
-Backtracking control verbs, Code expressions, conditional expressions, and
-independent expressions in regexes, The C<\N> regex character class,
-gv_try_downgrade, Experimental Support for Sun Studio Compilers for Linux
-OS, Pluggable keywords
-
-=item Accepted features
-
-(none yet identified)
-
-=item Removed features
-
-C<legacy>
-
-=back
-
-=item AUTHORS
-
-=item COPYRIGHT
-
-=item LICENSE
-
-=back
-
-=head2 perlartistic - the Perl Artistic License
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item The "Artistic License"
-
-=over 4
-
-=item Preamble
-
-=item Definitions
-
-"Package", "Standard Version", "Copyright Holder", "You", "Reasonable
-copying fee", "Freely Available"
-
-=item Conditions
-
-a), b), c), d), a), b), c), d)
-
-=back
-
-=back
-
-=head2 perlgpl - the GNU General Public License, version 1
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item GNU GENERAL PUBLIC LICENSE
-
-=back
-
-=head2 perlaix - Perl version 5 on IBM AIX (UNIX) systems
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Compiling Perl 5 on AIX
-
-=item Supported Compilers
-
-=item Incompatibility with AIX Toolbox lib gdbm
-
-=item Perl 5 was successfully compiled and tested on:
-
-=item Building Dynamic Extensions on AIX
-
-=item Using Large Files with Perl
-
-=item Threaded Perl
-
-=item 64-bit Perl
-
-=item Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (threaded/32-bit)
-
-=item Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (32-bit)
-
-=item Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (threaded/64-bit)
-
-=item Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (64-bit)
-
-=item Compiling Perl 5 on older AIX versions up to 4.3.3
-
-=item OS level
-
-=item Building Dynamic Extensions on AIX E<lt> 5L
-
-=item The IBM ANSI C Compiler
-
-=item The usenm option
-
-=item Using GNU's gcc for building Perl
-
-=item Using Large Files with Perl E<lt> 5L
-
-=item Threaded Perl E<lt> 5L
-
-=item 64-bit Perl E<lt> 5L
-
-=item AIX 4.2 and extensions using C++ with statics
-
-=back
-
-=item AUTHORS
-
-=back
-
-=head2 perlamiga - Perl under Amiga OS
-
-=over 4
-
-=item NOTE
-
-=item SYNOPSIS
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Prerequisites for Compiling Perl on AmigaOS
-
-B<Unix emulation for AmigaOS: ixemul.library>, B<Version of Amiga OS>
-
-=item Starting Perl programs under AmigaOS
-
-=item Shortcomings of Perl under AmigaOS
-
-=back
-
-=item INSTALLATION
-
-=item Accessing documentation
-
-=over 4
-
-=item Manpages for Perl on AmigaOS
-
-=item Perl HTML Documentation on AmigaOS
-
-=item Perl GNU Info Files on AmigaOS
-
-=item Perl LaTeX Documentation on AmigaOS
-
-=back
-
-=item BUILDING PERL ON AMIGAOS
-
-=over 4
-
-=item Build Prerequisites for Perl on AmigaOS
-
-=item Getting the Perl Source for AmigaOS
-
-=item Making Perl on AmigaOS
-
-=item Testing Perl on AmigaOS
-
-=item Installing the built Perl on AmigaOS
-
-=back
-
-=item PERL 5.8.0 BROKEN IN AMIGAOS
-
-=item AUTHORS
-
-=item SEE ALSO
-
-=back
-
-=head2 perlbeos - Perl version 5.8+ on BeOS
-
-=over 4
-
-=item DESCRIPTION
-
-=item BUILD AND INSTALL
-
-=over 4
-
-=item Requirements
-
-=item Configure
-
-=item Build
-
-=item Install
-
-=back
-
-=item KNOWN PROBLEMS
-
-=item CONTACT
-
-=back
-
-=head2 perlbs2000 - building and installing Perl for BS2000.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item gzip on BS2000
-
-=item bison on BS2000
-
-=item Unpacking Perl Distribution on BS2000
-
-=item Compiling Perl on BS2000
-
-=item Testing Perl on BS2000
-
-=item Installing Perl on BS2000
-
-=item Using Perl in the Posix-Shell of BS2000
-
-=item Using Perl in "native" BS2000
-
-=item Floating point anomalies on BS2000
-
-=item Using PerlIO and different encodings on ASCII and EBCDIC partitions
-
-=back
-
-=item AUTHORS
-
-=item SEE ALSO
-
-=over 4
-
-=item Mailing list
-
-=back
-
-=item HISTORY
-
-=back
-
-=head2 perlce - Perl for WinCE
-
-=over 4
-
-=item Building Perl for WinCE
-
-=over 4
-
-=item DESCRIPTION
-
-=item General explanations on cross-compiling WinCE
-
-=item BUILD
-
-Microsoft Embedded Visual Tools, Microsoft Visual C++, Rainer Keuchel's
-celib-sources, Rainer Keuchel's console-sources, go to F<./win32>
-subdirectory, edit file F<./win32/ce-helpers/compile.bat>, run
-compile.bat, run compile.bat dist
-
-=back
-
-=item Using Perl on WinCE
-
-=over 4
-
-=item DESCRIPTION
-
-=item LIMITATIONS
-
-=item ENVIRONMENT
-
-PERL5LIB, PATH, TMP, UNIXROOTPATH, ROWS/COLS, HOME, CONSOLEFONTSIZE
-
-=item REGISTRY
-
-=item XS
-
-=item BUGS
-
-=item INSTALLATION
-
-=back
-
-=item ACKNOWLEDGEMENTS
-
-=item History of WinCE port
-
-=item AUTHORS
-
-Rainer Keuchel <coyxc@rainer-keuchel.de>, Vadim Konovalov
-
-=back
-
-=head2 perlcygwin - Perl for Cygwin
-
-=over 4
-
-=item SYNOPSIS
-
-=item PREREQUISITES FOR COMPILING PERL ON CYGWIN
-
-=over 4
-
-=item Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it)
-
-=item Cygwin Configuration
-
-C<PATH>, I<nroff>
-
-=back
-
-=item CONFIGURE PERL ON CYGWIN
-
-=over 4
-
-=item Stripping Perl Binaries on Cygwin
-
-=item Optional Libraries for Perl on Cygwin
-
-C<-lcrypt>, C<-lgdbm_compat> (C<use GDBM_File>), C<-ldb> (C<use DB_File>),
-C<cygserver> (C<use IPC::SysV>), C<-lutil>
-
-=item Configure-time Options for Perl on Cygwin
-
-C<-Uusedl>, C<-Dusemymalloc>, C<-Uuseperlio>, C<-Dusemultiplicity>,
-C<-Uuse64bitint>, C<-Duselongdouble>, C<-Uuseithreads>, C<-Duselargefiles>,
-C<-Dmksymlinks>
-
-=item Suspicious Warnings on Cygwin
-
-Win9x and C<d_eofnblk>, Compiler/Preprocessor defines
-
-=back
-
-=item MAKE ON CYGWIN
-
-=item TEST ON CYGWIN
-
-=over 4
-
-=item File Permissions on Cygwin
-
-=item NDBM_File and ODBM_File do not work on FAT filesystems
-
-=item C<fork()> failures in io_* tests
-
-=back
-
-=item Specific features of the Cygwin port
-
-=over 4
-
-=item Script Portability on Cygwin
-
-Pathnames, Text/Binary, PerlIO, F<.exe>, Cygwin vs. Windows process ids,
-Cygwin vs. Windows errors, rebase errors on fork or system, C<chown()>,
-Miscellaneous
-
-=item Prebuilt methods:
-
-C<Cwd::cwd>, C<Cygwin::pid_to_winpid>, C<Cygwin::winpid_to_pid>,
-C<Cygwin::win_to_posix_path>, C<Cygwin::posix_to_win_path>,
-C<Cygwin::mount_table()>, C<Cygwin::mount_flags>, C<Cygwin::is_binmount>,
-C<Cygwin::sync_winenv>
-
-=back
-
-=item INSTALL PERL ON CYGWIN
-
-=item MANIFEST ON CYGWIN
-
-Documentation, Build, Configure, Make, Install, Tests, Compiled Perl
-Source, Compiled Module Source, Perl Modules/Scripts, Perl Module Tests
-
-=item BUGS ON CYGWIN
-
-=item AUTHORS
-
-=item HISTORY
-
-=back
-
-=head2 perldgux - Perl under DG/UX.
-
-=over 4
-
-=item SYNOPSIS
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item BUILDING PERL ON DG/UX
-
-=over 4
-
-=item Non-threaded Perl on DG/UX
-
-=item Threaded Perl on DG/UX
-
-=item Testing Perl on DG/UX
-
-=item Installing the built perl on DG/UX
-
-=back
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 perldos - Perl under DOS, W31, W95.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Prerequisites for Compiling Perl on DOS
-
-DJGPP, Pthreads
-
-=item Shortcomings of Perl under DOS
-
-=item Building Perl on DOS
-
-=item Testing Perl on DOS
-
-=item Installation of Perl on DOS
-
-=back
-
-=item BUILDING AND INSTALLING MODULES ON DOS
-
-=over 4
-
-=item Building Prerequisites for Perl on DOS
-
-=item Unpacking CPAN Modules on DOS
-
-=item Building Non-XS Modules on DOS
-
-=item Building XS Modules on DOS
-
-=back
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 perlepoc - Perl for EPOC
-
-=over 4
-
-=item SYNOPSIS
-
-=item INTRODUCTION
-
-=item INSTALLING PERL ON EPOC
-
-=item STARTING PERL ON EPOC
-
-=over 4
-
-=item Features of Perl on Epoc
-
-=item Restrictions of Perl on Epoc
-
-=item Compiling Perl 5 on the EPOC cross compiling environment
-
-=back
-
-=item SUPPORT STATUS OF PERL ON EPOC
-
-=item AUTHOR
-
-=item LAST UPDATE
-
-=back
-
-=head2 perlfreebsd - Perl version 5 on FreeBSD systems
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item FreeBSD core dumps from readdir_r with ithreads
-
-=item $^X doesn't always contain a full path in FreeBSD
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 perlhaiku - Perl version 5.10+ on Haiku
-
-=over 4
-
-=item DESCRIPTION
-
-=item BUILD AND INSTALL
-
-=item KNOWN PROBLEMS
-
-=item CONTACT
-
-=back
-
-=head2 perlhpux - Perl version 5 on Hewlett-Packard Unix (HP-UX) systems
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Using perl as shipped with HP-UX
-
-=item Using perl from HP's porting centre
-
-=item Compiling Perl 5 on HP-UX
-
-=item PA-RISC
-
-=item Portability Between PA-RISC Versions
-
-=item PA-RISC 1.0
-
-=item PA-RISC 1.1
-
-=item PA-RISC 2.0
-
-=item Itanium Processor Family (IPF) and HP-UX
-
-=item Itanium, Itanium 2 & Madison 6
-
-=item HP-UX versions
-
-=item Building Dynamic Extensions on HP-UX
-
-=item The HP ANSI C Compiler
-
-=item The GNU C Compiler
-
-=item Using Large Files with Perl on HP-UX
-
-=item Threaded Perl on HP-UX
-
-=item 64-bit Perl on HP-UX
-
-=item Oracle on HP-UX
-
-=item GDBM and Threads on HP-UX
-
-=item NFS filesystems and utime(2) on HP-UX
-
-=item HP-UX Kernel Parameters (maxdsiz) for Compiling Perl
-
-=back
-
-=item nss_delete core dump from op/pwent or op/grent
-
-=item error: pasting ")" and "l" does not give a valid preprocessing token
-
-=item Miscellaneous
-
-=item AUTHOR
-
-=back
-
-=head2 perlhurd - Perl version 5 on Hurd
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Known Problems with Perl on Hurd
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 perlirix - Perl version 5 on Irix systems
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Building 32-bit Perl in Irix
-
-=item Building 64-bit Perl in Irix
-
-=item About Compiler Versions of Irix
-
-=item Linker Problems in Irix
-
-=item Malloc in Irix
-
-=item Building with threads in Irix
-
-=item Irix 5.3
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 perllinux - Perl version 5 on Linux systems
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Experimental Support for Sun Studio Compilers for Linux OS
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 perlmacos - Perl under Mac OS (Classic)
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=back
-
-=head2 perlmacosx - Perl under Mac OS X
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Installation Prefix
-
-=item SDK support
-
-=item Universal Binary support
-
-=item 64-bit PPC support
-
-=item libperl and Prebinding
-
-=item Updating Apple's Perl
-
-=item Known problems
-
-=item Cocoa
-
-=back
-
-=item Starting From Scratch
-
-=item AUTHOR
-
-=item DATE
-
-=back
-
-=head2 perlmpeix - Perl/iX for HP e3000 MPE
-
-=over 4
-
-=item SYNOPSIS
-
-=item NOTE
-
-=item What's New in Perl for MPE/iX
-
-=item Welcome to Perl/iX
-
-=item System Requirements for Perl/iX
-
-=item How to Obtain Perl/iX
-
-=item Perl/iX Distribution Contents Highlights
-
-README, INSTALL, LIBSHP3K, PERL, .cpan/, lib/, man/,
-public_html/feedback.cgi, src/perl-5.6.0-mpe
-
-=item How to Compile Perl/iX
-
- 4, 6
-
-=item Getting Started with Perl/iX
-
-=item MPE/iX Implementation Considerations
-
-=item Known Perl/iX Bugs Under Investigation
-
-=item Perl/iX To-Do List
-
-=item Perl/iX Change History
-
-=item AUTHOR
-
-=back
-
-=head2 perlnetware - Perl for NetWare
-
-=over 4
-
-=item DESCRIPTION
-
-=item BUILD
-
-=over 4
-
-=item Tools & SDK
-
-=item Setup
-
-SetNWBld.bat, Buildtype.bat
-
-=item Make
-
-=item Interpreter
-
-=item Extensions
-
-=back
-
-=item INSTALL
-
-=item BUILD NEW EXTENSIONS
-
-=item ACKNOWLEDGEMENTS
-
-=item AUTHORS
-
-=item DATE
-
-=back
-
-=head2 perlopenbsd - Perl version 5 on OpenBSD systems
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item OpenBSD core dumps from getprotobyname_r and getservbyname_r with
-ithreads
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
-
-=over 4
-
-=item SYNOPSIS
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Target
-
-=item Other OSes
-
-=item Prerequisites
-
-EMX, RSX, HPFS, pdksh
-
-=item Starting Perl programs under OS/2 (and DOS and...)
-
-=item Starting OS/2 (and DOS) programs under Perl
-
-=back
-
-=item Frequently asked questions
-
-=over 4
-
-=item "It does not work"
-
-=item I cannot run external programs
-
-=item I cannot embed perl into my program, or use F<perl.dll> from my
-program.
-
-Is your program EMX-compiled with C<-Zmt -Zcrtdll>?, Did you use
-L<ExtUtils::Embed>?
-
-=item C<``> and pipe-C<open> do not work under DOS.
-
-=item Cannot start C<find.exe "pattern" file>
-
-=back
-
-=item INSTALLATION
-
-=over 4
-
-=item Automatic binary installation
-
-C<PERL_BADLANG>, C<PERL_BADFREE>, F<Config.pm>
-
-=item Manual binary installation
-
-Perl VIO and PM executables (dynamically linked), Perl_ VIO executable
-(statically linked), Executables for Perl utilities, Main Perl library,
-Additional Perl modules, Tools to compile Perl modules, Manpages for Perl
-and utilities, Manpages for Perl modules, Source for Perl documentation,
-Perl manual in F<.INF> format, Pdksh
-
-=item B<Warning>
-
-=back
-
-=item Accessing documentation
-
-=over 4
-
-=item OS/2 F<.INF> file
-
-=item Plain text
-
-=item Manpages
-
-=item HTML
-
-=item GNU C<info> files
-
-=item F<PDF> files
-
-=item C<LaTeX> docs
-
-=back
-
-=item BUILD
-
-=over 4
-
-=item The short story
-
-=item Prerequisites
-
-=item Getting perl source
-
-=item Application of the patches
-
-=item Hand-editing
-
-=item Making
-
-=item Testing
-
-A lot of C<bad free>, Process terminated by SIGTERM/SIGINT, F<op/fs.t>,
-F<op/stat.t>
-
-=item Installing the built perl
-
-=item C<a.out>-style build
-
-=back
-
-=item Building a binary distribution
-
-=item Building custom F<.EXE> files
-
-=over 4
-
-=item Making executables with a custom collection of statically loaded
-extensions
-
-=item Making executables with a custom search-paths
-
-=back
-
-=item Build FAQ
-
-=over 4
-
-=item Some C</> became C<\> in pdksh.
-
-=item C<'errno'> - unresolved external
-
-=item Problems with tr or sed
-
-=item Some problem (forget which ;-)
-
-=item Library ... not found
-
-=item Segfault in make
-
-=item op/sprintf test failure
-
-=back
-
-=item Specific (mis)features of OS/2 port
-
-=over 4
-
-=item C<setpriority>, C<getpriority>
-
-=item C<system()>
-
-=item C<extproc> on the first line
-
-=item Additional modules:
-
-=item Prebuilt methods:
-
-C<File::Copy::syscopy>, C<DynaLoader::mod2fname>, C<Cwd::current_drive()>,
- C<Cwd::sys_chdir(name)>, C<Cwd::change_drive(name)>,
-C<Cwd::sys_is_absolute(name)>, C<Cwd::sys_is_rooted(name)>,
-C<Cwd::sys_is_relative(name)>, C<Cwd::sys_cwd(name)>,
-C<Cwd::sys_abspath(name, dir)>, C<Cwd::extLibpath([type])>,
-C<Cwd::extLibpath_set( path [, type ] )>,
-C<OS2::Error(do_harderror,do_exception)>, C<OS2::Errors2Drive(drive)>,
-OS2::SysInfo(), OS2::BootDrive(), C<OS2::MorphPM(serve)>,
-C<OS2::UnMorphPM(serve)>, C<OS2::Serve_Messages(force)>,
-C<OS2::Process_Messages(force [, cnt])>, C<OS2::_control87(new,mask)>,
-OS2::get_control87(), C<OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)>,
-C<OS2::DLLname([how [, \&xsub]])>
-
-=item Prebuilt variables:
-
-$OS2::emx_rev, $OS2::emx_env, $OS2::os_ver, $OS2::is_aout, $OS2::can_fork,
-$OS2::nsyserror
-
-=item Misfeatures
-
-=item Modifications
-
-C<popen>, C<tmpnam>, C<tmpfile>, C<ctermid>, C<stat>, C<mkdir>, C<rmdir>,
-C<flock>
-
-=item Identifying DLLs
-
-=item Centralized management of resources
-
-C<HAB>, C<HMQ>, Treating errors reported by OS/2 API,
-C<CheckOSError(expr)>, C<CheckWinError(expr)>, C<SaveWinError(expr)>,
-C<SaveCroakWinError(expr,die,name1,name2)>, C<WinError_2_Perl_rc>,
-C<FillWinError>, C<FillOSError(rc)>, Loading DLLs and ordinals in DLLs
-
-=back
-
-=item Perl flavors
-
-=over 4
-
-=item F<perl.exe>
-
-=item F<perl_.exe>
-
-=item F<perl__.exe>
-
-=item F<perl___.exe>
-
-=item Why strange names?
-
-=item Why dynamic linking?
-
-=item Why chimera build?
-
-=back
-
-=item ENVIRONMENT
-
-=over 4
-
-=item C<PERLLIB_PREFIX>
-
-=item C<PERL_BADLANG>
-
-=item C<PERL_BADFREE>
-
-=item C<PERL_SH_DIR>
-
-=item C<USE_PERL_FLOCK>
-
-=item C<TMP> or C<TEMP>
-
-=back
-
-=item Evolution
-
-=over 4
-
-=item Text-mode filehandles
-
-=item Priorities
-
-=item DLL name mangling: pre 5.6.2
-
-=item DLL name mangling: 5.6.2 and beyond
-
-Global DLLs, specific DLLs, C<BEGINLIBPATH> and C<ENDLIBPATH>, F<.> from
-C<LIBPATH>
-
-=item DLL forwarder generation
-
-=item Threading
-
-=item Calls to external programs
-
-=item Memory allocation
-
-=item Threads
-
-C<COND_WAIT>, F<os2.c>
-
-=back
-
-=item BUGS
-
-=back
-
-=over 4
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 perlos390 - building and installing Perl for OS/390 and z/OS
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Tools
-
-=item Unpacking Perl distribution on OS/390
-
-=item Setup and utilities for Perl on OS/390
-
-=item Configure Perl on OS/390
-
-=item Build, Test, Install Perl on OS/390
-
-=item Build Anomalies with Perl on OS/390
-
-=item Testing Anomalies with Perl on OS/390
-
-=item Installation Anomalies with Perl on OS/390
-
-=item Usage Hints for Perl on OS/390
-
-=item Floating Point Anomalies with Perl on OS/390
-
-=item Modules and Extensions for Perl on OS/390
-
-=back
-
-=item AUTHORS
-
-=item SEE ALSO
-
-=over 4
-
-=item Mailing list for Perl on OS/390
-
-=back
-
-=item HISTORY
-
-=back
-
-=head2 perlos400 - Perl version 5 on OS/400
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Compiling Perl for OS/400 PASE
-
-=item Installing Perl in OS/400 PASE
-
-=item Using Perl in OS/400 PASE
-
-=item Known Problems
-
-=item Perl on ILE
-
-=back
-
-=item AUTHORS
-
-=back
-
-=head2 perlplan9 - Plan 9-specific documentation for Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Invoking Perl
-
-=item What's in Plan 9 Perl
-
-=item What's not in Plan 9 Perl
-
-=item Perl5 Functions not currently supported in Plan 9 Perl
-
-=item Signals in Plan 9 Perl
-
-=back
-
-=item COMPILING AND INSTALLING PERL ON PLAN 9
-
-=over 4
-
-=item Installing Perl Documentation on Plan 9
-
-=back
-
-=item BUGS
-
-=item Revision date
-
-=item AUTHOR
-
-=back
-
-=head2 perlqnx - Perl version 5 on QNX
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Required Software for Compiling Perl on QNX4
-
-/bin/sh, ar, nm, cpp, make
-
-=item Outstanding Issues with Perl on QNX4
-
-=item QNX auxiliary files
-
-qnx/ar, qnx/cpp
-
-=item Outstanding issues with perl under QNX6
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 perlriscos - Perl version 5 for RISC OS
-
-=over 4
-
-=item DESCRIPTION
-
-=item BUILD
-
-=item AUTHOR
-
-=back
-
-=head2 perlsolaris - Perl version 5 on Solaris systems
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Solaris Version Numbers.
-
-=back
-
-=item RESOURCES
-
-Solaris FAQ, Precompiled Binaries, Solaris Documentation
-
-=item SETTING UP
-
-=over 4
-
-=item File Extraction Problems on Solaris.
-
-=item Compiler and Related Tools on Solaris.
-
-=item Environment for Compiling perl on Solaris
-
-=back
-
-=item RUN CONFIGURE.
-
-=over 4
-
-=item 64-bit perl on Solaris.
-
-=item Threads in perl on Solaris.
-
-=item Malloc Issues with perl on Solaris.
-
-=back
-
-=item MAKE PROBLEMS.
-
-Dynamic Loading Problems With GNU as and GNU ld, ld.so.1: ./perl: fatal:
-relocation error:, dlopen: stub interception failed, #error "No
-DATAMODEL_NATIVE specified", sh: ar: not found
-
-=item MAKE TEST
-
-=over 4
-
-=item op/stat.t test 4 in Solaris
-
-=item nss_delete core dump from op/pwent or op/grent
-
-=back
-
-=item PREBUILT BINARIES OF PERL FOR SOLARIS.
-
-=item RUNTIME ISSUES FOR PERL ON SOLARIS.
-
-=over 4
-
-=item Limits on Numbers of Open Files on Solaris.
-
-=back
-
-=item SOLARIS-SPECIFIC MODULES.
-
-=item SOLARIS-SPECIFIC PROBLEMS WITH MODULES.
-
-=over 4
-
-=item Proc::ProcessTable on Solaris
-
-=item BSD::Resource on Solaris
-
-=item Net::SSLeay on Solaris
-
-=back
-
-=item SunOS 4.x
-
-=item AUTHOR
-
-=back
-
-=head2 perlsymbian - Perl version 5 on Symbian OS
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Compiling Perl on Symbian
-
-=item Compilation problems
-
-=item PerlApp
-
-=item sisify.pl
-
-=item Using Perl in Symbian
-
-=back
-
-=item TO DO
-
-=item WARNING
-
-=item NOTE
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item LICENSE
-
-=item HISTORY
-
-=back
-
-=head2 perltru64 - Perl version 5 on Tru64 (formerly known as Digital UNIX
-formerly known as DEC OSF/1) systems
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Compiling Perl 5 on Tru64
-
-=item Using Large Files with Perl on Tru64
-
-=item Threaded Perl on Tru64
-
-=item Long Doubles on Tru64
-
-=item DB_File tests failing on Tru64
-
-=item 64-bit Perl on Tru64
-
-=item Warnings about floating-point overflow when compiling Perl on Tru64
-
-=back
-
-=item Testing Perl on Tru64
-
-=item ext/ODBM_File/odbm Test Failing With Static Builds
-
-=item Perl Fails Because Of Unresolved Symbol sockatmark
-
-=item AUTHOR
-
-=back
-
-=head2 perluts - Perl under UTS
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item BUILDING PERL ON UTS
-
-=item Installing the built perl on UTS
-
-=item AUTHOR
-
-=back
-
-=head2 perlvmesa - building and installing Perl for VM/ESA.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Unpacking Perl Distribution on VM/ESA
-
-=item Setup Perl and utilities on VM/ESA
-
-=item Configure Perl on VM/ESA
-
-=item Testing Anomalies of Perl on VM/ESA
-
-=item Usage Hints for Perl on VM/ESA
-
-=back
-
-=item AUTHORS
-
-=item SEE ALSO
-
-=over 4
-
-=item Mailing list for Perl on VM/ESA
-
-=back
-
-=back
-
-=head2 perlvms - VMS-specific documentation for Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=item Installation
-
-=item Organization of Perl Images
-
-=over 4
-
-=item Core Images
-
-=item Perl Extensions
-
-=item Installing static extensions
-
-=item Installing dynamic extensions
-
-=back
-
-=item File specifications
-
-=over 4
-
-=item Syntax
-
-=item Filename Case
-
-=item Symbolic Links
-
-=item Wildcard expansion
-
-=item Pipes
-
-=back
-
-=item PERL5LIB and PERLLIB
-
-=item The Perl Forked Debugger
-
-=item PERL_VMS_EXCEPTION_DEBUG
-
-=item Command line
-
-=over 4
-
-=item I/O redirection and backgrounding
-
-=item Command line switches
-
--i, -S, -u
-
-=back
-
-=item Perl functions
-
-File tests, backticks, binmode FILEHANDLE, crypt PLAINTEXT, USER, die,
-dump, exec LIST, fork, getpwent, getpwnam, getpwuid, gmtime, kill, qx//,
-select (system call), stat EXPR, system LIST, time, times, unlink LIST,
-utime LIST, waitpid PID,FLAGS
-
-=item Perl variables
-
-%ENV, CRTL_ENV, CLISYM_[LOCAL], Any other string, $!, $^E, $?, $|
-
-=item Standard modules with VMS-specific differences
-
-=over 4
-
-=item SDBM_File
-
-=back
-
-=item Revision date
-
-=item AUTHOR
-
-=back
-
-=head2 perlvos - Perl for Stratus VOS
-
-=over 4
-
-=item SYNOPSIS
-
-=item BUILDING PERL FOR VOS
-
-=item INSTALLING PERL IN VOS
-
-=item USING PERL IN VOS
-
-=over 4
-
-=item Restrictions of Perl on VOS
-
-=item Handling of underflow and overflow
-
-=back
-
-=item TEST STATUS
-
-=item SUPPORT STATUS
-
-=item AUTHOR
-
-=item LAST UPDATE
-
-=back
-
-=head2 perlwin32 - Perl under Windows
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-L<http://mingw.org>, L<http://mingw-w64.sf.net>
-
-=over 4
-
-=item Setting Up Perl on Windows
-
-Make, Command Shell, Microsoft Visual C++, Microsoft Visual C++ 2008/2010
-Express Edition, Microsoft Visual C++ 2005 Express Edition, Microsoft
-Visual C++ Toolkit 2003, Microsoft Platform SDK 64-bit Compiler, MinGW
-release 3 with gcc
-
-=item Building
-
-=item Testing Perl on Windows
-
-=item Installation of Perl on Windows
-
-=item Usage Hints for Perl on Windows
-
-Environment Variables, File Globbing, Using perl from the command line,
-Building Extensions, Command-line Wildcard Expansion, Notes on 64-bit
-Windows
-
-=item Running Perl Scripts
-
-=item Miscellaneous Things
-
-=back
-
-=item BUGS AND CAVEATS
-
-=item ACKNOWLEDGEMENTS
-
-=item AUTHORS
-
-Gary Ng E<lt>71564.1743@CompuServe.COME<gt>, Gurusamy Sarathy
-E<lt>gsar@activestate.comE<gt>, Nick Ing-Simmons
-E<lt>nick@ing-simmons.netE<gt>, Jan Dubois E<lt>jand@activestate.comE<gt>,
-Steve Hay E<lt>steve.m.hay@googlemail.comE<gt>
-
-=item SEE ALSO
-
-=item HISTORY
-
-=back
-
-=head2 perlboot - This document has been deleted
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=head2 perlbot - This document has been deleted
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=head2 perltodo - Perl TO-DO List
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=head2 perltooc - This document has been deleted
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=head2 perltoot - This document has been deleted
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=head1 PRAGMA DOCUMENTATION
-
-=head2 arybase - Set indexing base via $[
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item HISTORY
-
-=item BUGS
-
-=item SEE ALSO
-
-=back
-
-=head2 attributes - get/set subroutine or variable attributes
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item What C<import> does
-
-=item Built-in Attributes
-
-lvalue, method, locked
-
-=item Available Subroutines
-
-get, reftype
-
-=item Package-specific Attribute Handling
-
-FETCH_I<type>_ATTRIBUTES, MODIFY_I<type>_ATTRIBUTES
-
-=item Syntax of Attribute Lists
-
-=back
-
-=item EXPORTS
-
-=over 4
-
-=item Default exports
-
-=item Available exports
-
-=item Export tags defined
-
-=back
-
-=item EXAMPLES
-
-=item MORE EXAMPLES
-
-=item SEE ALSO
-
-=back
-
-=head2 autodie - Replace functions with ones that succeed or die with
-lexical scope
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item EXCEPTIONS
-
-=item CATEGORIES
-
-=item FUNCTION SPECIFIC NOTES
-
-=over 4
-
-=item flock
-
-=item system/exec
-
-=back
-
-=item GOTCHAS
-
-=item DIAGNOSTICS
-
-:void cannot be used with lexical scope, No user hints defined for %s
-
-=item BUGS
-
-=over 4
-
-=item autodie and string eval
-
-=item REPORTING BUGS
-
-=back
-
-=item FEEDBACK
-
-=item AUTHOR
-
-=item LICENSE
-
-=item SEE ALSO
-
-=item ACKNOWLEDGEMENTS
-
-=back
-
-=head2 autodie::exception - Exceptions from autodying functions.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Common Methods
-
-=back
-
-=back
-
-=over 4
-
-=item Advanced methods
-
-=back
-
-=over 4
-
-=item SEE ALSO
-
-=item LICENSE
-
-=item AUTHOR
-
-=back
-
-=head2 autodie::exception::system - Exceptions from autodying system().
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item stringify
-
-=back
-
-=over 4
-
-=item LICENSE
-
-=item AUTHOR
-
-=back
-
-=head2 autodie::hints - Provide hints about user subroutines to autodie
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Introduction
-
-=item What are hints?
-
-=item Example hints
-
-=back
-
-=item Manually setting hints from within your program
-
-=item Adding hints to your module
-
-=item Insisting on hints
-
-=back
-
-=over 4
-
-=item Diagnostics
-
-Attempts to set_hints_for unidentifiable subroutine, fail hints cannot be
-provided with either scalar or list hints for %s, %s hint missing for %s
-
-=item ACKNOWLEDGEMENTS
-
-=item AUTHOR
-
-=item LICENSE
-
-=item SEE ALSO
-
-=back
-
-=head2 autouse - postpone load of modules until a function is used
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item WARNING
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 base - Establish an ISA relationship with base classes at compile
-time
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item DIAGNOSTICS
-
-Base class package "%s" is empty, Class 'Foo' tried to inherit from itself
-
-=item HISTORY
-
-=item CAVEATS
-
-=item SEE ALSO
-
-=back
-
-=head2 bigint - Transparent BigInteger support for Perl
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item use integer vs. use bigint
-
-=item Options
-
-a or accuracy, p or precision, t or trace, hex, oct, l, lib, try or only, v
-or version
-
-=item Math Library
-
-=item Internal Format
-
-=item Sign
-
-=item Methods
-
-inf(), NaN(), e, PI, bexp(), bpi(), upgrade(), in_effect()
-
-=item MATH LIBRARY
-
-=item Caveat
-
-=back
-
-=item CAVEATS
-
-in_effect(), hex()/oct()
-
-=item MODULES USED
-
-=item EXAMPLES
-
-=item LICENSE
-
-=item SEE ALSO
-
-=item AUTHORS
-
-=back
-
-=head2 bignum - Transparent BigNumber support for Perl
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Options
-
-a or accuracy, p or precision, t or trace, l or lib, hex, oct, v or version
-
-=item Methods
-
-=item Caveats
-
-inf(), NaN(), e, PI(), bexp(), bpi(), upgrade(), in_effect()
-
-=item Math Library
-
-=item INTERNAL FORMAT
-
-=item SIGN
-
-=back
-
-=item CAVEATS
-
-in_effect(), hex()/oct()
-
-=item MODULES USED
-
-=item EXAMPLES
-
-=item LICENSE
-
-=item SEE ALSO
-
-=item AUTHORS
-
-=back
-
-=head2 bigrat - Transparent BigNumber/BigRational support for Perl
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Modules Used
-
-=item Math Library
-
-=item Sign
-
-=item Methods
-
-inf(), NaN(), e, PI, bexp(), bpi(), upgrade(), in_effect()
-
-=item MATH LIBRARY
-
-=item Caveat
-
-=item Options
-
-a or accuracy, p or precision, t or trace, l or lib, hex, oct, v or version
-
-=back
-
-=item CAVEATS
-
-in_effect(), hex()/oct()
-
-=item EXAMPLES
-
-=item LICENSE
-
-=item SEE ALSO
-
-=item AUTHORS
-
-=back
-
-=head2 blib - Use MakeMaker's uninstalled version of a package
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item BUGS
-
-=item AUTHOR
-
-=back
-
-=head2 bytes - Perl pragma to force byte semantics rather than character
-semantics
-
-=over 4
-
-=item NOTICE
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item LIMITATIONS
-
-=item SEE ALSO
-
-=back
-
-=head2 charnames - access to Unicode character names and named character
-sequences; also define character names
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item LOOSE MATCHES
-
-=item ALIASES
-
-=item CUSTOM ALIASES
-
-=item charnames::string_vianame(I<name>)
-
-=item charnames::vianame(I<name>)
-
-=item charnames::viacode(I<code>)
-
-=item CUSTOM TRANSLATORS
-
-=item BUGS
-
-=back
-
-=head2 constant - Perl pragma to declare constants
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item NOTES
-
-=over 4
-
-=item List constants
-
-=item Defining multiple constants at once
-
-=item Magic constants
-
-=back
-
-=item TECHNICAL NOTES
-
-=item CAVEATS
-
-=item SEE ALSO
-
-=item BUGS
-
-=item AUTHORS
-
-=item COPYRIGHT & LICENSE
-
-=back
-
-=head2 deprecate - Perl pragma for deprecating the core version of a module
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item EXPORT
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 diagnostics, splain - produce verbose warning diagnostics
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item The C<diagnostics> Pragma
-
-=item The I<splain> Program
-
-=back
-
-=item EXAMPLES
-
-=item INTERNALS
-
-=item BUGS
-
-=item AUTHOR
-
-=back
-
-=head2 encoding - allows you to write your script in non-ascii or non-utf8
-
-=over 4
-
-=item SYNOPSIS
-
-=item ABSTRACT
-
-=over 4
-
-=item Literal Conversions
-
-=item PerlIO layers for C<STD(IN|OUT)>
-
-=item Implicit upgrading for byte strings
-
-=item Side effects
-
-=back
-
-=item FEATURES THAT REQUIRE 5.8.1
-
-"NON-EUC" doublebyte encodings, tr//, DATA pseudo-filehandle
-
-=item USAGE
-
-use encoding [I<ENCNAME>] ;, use encoding I<ENCNAME> [ STDIN =E<gt>
-I<ENCNAME_IN> ...] ;, use encoding I<ENCNAME> Filter=E<gt>1;, no encoding;
-
-=item The Filter Option
-
-=over 4
-
-=item Filter-related changes at Encode version 1.87
-
-=back
-
-=item CAVEATS
-
-=over 4
-
-=item NOT SCOPED
-
-=item DO NOT MIX MULTIPLE ENCODINGS
-
-=item tr/// with ranges
-
-Legend of characters above
-
-=back
-
-=item EXAMPLE - Greekperl
-
-=item KNOWN PROBLEMS
-
-literals in regex that are longer than 127 bytes, EBCDIC, format, Thread
-safety
-
-=over 4
-
-=item The Logic of :locale
-
-=back
-
-=item HISTORY
-
-=item SEE ALSO
-
-=back
-
-=head2 encoding::warnings - Warn on implicit encoding conversions
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Overview of the problem
-
-=item Detecting the problem
-
-=item Solving the problem
-
-Upgrade both sides to unicode-strings, Downgrade both sides to
-byte-strings, Specify the encoding for implicit byte-string upgrading,
-PerlIO layers for B<STDIN> and B<STDOUT>, Literal conversions, Implicit
-upgrading for byte-strings
-
-=back
-
-=item CAVEATS
-
-=back
-
-=over 4
-
-=item SEE ALSO
-
-=item AUTHORS
-
-=item COPYRIGHT
-
-=back
-
-=head2 feature - Perl pragma to enable new features
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Lexical effect
-
-=item C<no feature>
-
-=back
-
-=item AVAILABLE FEATURES
-
-=over 4
-
-=item The 'say' feature
-
-=item The 'state' feature
-
-=item The 'switch' feature
-
-=item The 'unicode_strings' feature
-
-=item The 'unicode_eval' and 'evalbytes' features
-
-=item The 'current_sub' feature
-
-=item The 'array_base' feature
-
-=item The 'fc' feature
-
-=back
-
-=item FEATURE BUNDLES
-
-=item IMPLICIT LOADING
-
-=back
-
-=head2 fields - compile-time class fields
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-new, phash
-
-=item SEE ALSO
-
-=back
-
-=head2 filetest - Perl pragma to control the filetest permission operators
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Consider this carefully
-
-=item The "access" sub-pragma
-
-=item Limitation with regard to C<_>
-
-=back
-
-=back
-
-=head2 if - C<use> a Perl module if a condition holds
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item BUGS
-
-=item AUTHOR
-
-=back
-
-=head2 inc::latest - use modules bundled in inc/ if they are newer than
-installed ones
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Special notes on bundling
-
-=back
-
-=item USAGE
-
-=over 4
-
-=item Author-mode
-
-loaded_modules(), write(), bundle_module()
-
-=item As bundled in inc/
-
-=back
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 integer - Perl pragma to use integer arithmetic instead of floating
-point
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 less - perl pragma to request less of something
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item FOR MODULE AUTHORS
-
-=over 4
-
-=item C<< BOOLEAN = less->of( FEATURE ) >>
-
-=item C<< FEATURES = less->of() >>
-
-=back
-
-=item CAVEATS
-
-This probably does nothing, This works only on 5.10+
-
-=back
-
-=head2 lib - manipulate @INC at compile time
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Adding directories to @INC
-
-=item Deleting directories from @INC
-
-=item Restoring original @INC
-
-=back
-
-=item CAVEATS
-
-=item NOTES
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 locale - Perl pragma to use or avoid POSIX locales for built-in
-operations
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 mro - Method Resolution Order
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item OVERVIEW
-
-=item The C3 MRO
-
-=over 4
-
-=item What is C3?
-
-=item How does C3 work
-
-=back
-
-=item Functions
-
-=over 4
-
-=item mro::get_linear_isa($classname[, $type])
-
-=item mro::set_mro ($classname, $type)
-
-=item mro::get_mro($classname)
-
-=item mro::get_isarev($classname)
-
-=item mro::is_universal($classname)
-
-=item mro::invalidate_all_method_caches()
-
-=item mro::method_changed_in($classname)
-
-=item mro::get_pkg_gen($classname)
-
-=item next::method
-
-=item next::can
-
-=item maybe::next::method
-
-=back
-
-=item SEE ALSO
-
-=over 4
-
-=item The original Dylan paper
-
-L<http://www.webcom.com/haahr/dylan/linearization-oopsla96.html>
-
-=item Pugs
-
-=item Parrot
-
-L<http://use.perl.org/~autrijus/journal/25768>
-
-=item Python 2.3 MRO related links
-
-L<http://www.python.org/2.3/mro.html>,
-L<http://www.python.org/2.2.2/descrintro.html#mro>
-
-=item Class::C3
-
-L<Class::C3>
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 open - perl pragma to set default PerlIO layers for input and output
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item NONPERLIO FUNCTIONALITY
-
-=item IMPLEMENTATION DETAILS
-
-=item SEE ALSO
-
-=back
-
-=head2 ops - Perl pragma to restrict unsafe operations when compiling
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=back
-
-=head2 overload - Package for overloading Perl operations
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Fundamentals
-
-=item Overloadable Operations
-
-C<not>, C<neg>, C<++>, C<-->, I<Assignments>, I<Non-mutators with a mutator
-variant>, C<int>, I<String, numeric, boolean, and regexp conversions>,
-I<Iteration>, I<File tests>, I<Matching>, I<Dereferencing>, I<Special>
-
-=item Magic Autogeneration
-
-=item Special Keys for C<use overload>
-
-defined, but FALSE, C<undef>, TRUE
-
-=item How Perl Chooses an Operator Implementation
-
-=item Losing Overloading
-
-=item Inheritance and Overloading
-
-Method names in the C<use overload> directive, Overloading of an operation
-is inherited by derived classes
-
-=item Run-time Overloading
-
-=item Public Functions
-
-overload::StrVal(arg), overload::Overloaded(arg), overload::Method(obj,op)
-
-=item Overloading Constants
-
-integer, float, binary, q, qr
-
-=back
-
-=item IMPLEMENTATION
-
-=item COOKBOOK
-
-=over 4
-
-=item Two-face Scalars
-
-=item Two-face References
-
-=item Symbolic Calculator
-
-=item I<Really> Symbolic Calculator
-
-=back
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=item DIAGNOSTICS
-
-Odd number of arguments for overload::constant, '%s' is not an overloadable
-type, '%s' is not a code reference, overload arg '%s' is invalid
-
-=item BUGS AND PITFALLS
-
-=back
-
-=head2 overloading - perl pragma to lexically control overloading
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-C<no overloading>, C<no overloading @ops>, C<use overloading>, C<use
-overloading @ops>
-
-=back
-
-=head2 parent - Establish an ISA relationship with base classes at compile
-time
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item DIAGNOSTICS
-
-Class 'Foo' tried to inherit from itself
-
-=item HISTORY
-
-=item CAVEATS
-
-=item SEE ALSO
-
-=item AUTHORS AND CONTRIBUTORS
-
-=item MAINTAINER
-
-=item LICENSE
-
-=back
-
-=head2 re - Perl pragma to alter regular expression behaviour
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item 'taint' mode
-
-=item 'eval' mode
-
-=item '/flags' mode
-
-=item 'debug' mode
-
-=item 'Debug' mode
-
-Compile related options, COMPILE, PARSE, OPTIMISE, TRIEC, DUMP, Execute
-related options, EXECUTE, MATCH, TRIEE, INTUIT, Extra debugging options,
-EXTRA, BUFFERS, TRIEM, STATE, STACK, OPTIMISEM, OFFSETS, OFFSETSDBG, Other
-useful flags, ALL, All, MORE, More
-
-=item Exportable Functions
-
-is_regexp($ref), regexp_pattern($ref), regmust($ref), regname($name,$all),
-regnames($all), regnames_count()
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 sigtrap - Perl pragma to enable simple signal handling
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item OPTIONS
-
-=over 4
-
-=item SIGNAL HANDLERS
-
-B<stack-trace>, B<die>, B<handler> I<your-handler>
-
-=item SIGNAL LISTS
-
-B<normal-signals>, B<error-signals>, B<old-interface-signals>
-
-=item OTHER
-
-B<untrapped>, B<any>, I<signal>, I<number>
-
-=back
-
-=item EXAMPLES
-
-=back
-
-=head2 sort - perl pragma to control sort() behaviour
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CAVEATS
-
-=back
-
-=head2 strict - Perl pragma to restrict unsafe constructs
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-C<strict refs>, C<strict vars>, C<strict subs>
-
-=item HISTORY
-
-=back
-
-=head2 subs - Perl pragma to predeclare sub names
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 threads - Perl interpreter-based threads
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-$thr = threads->create(FUNCTION, ARGS), $thr->join(), $thr->detach(),
-threads->detach(), threads->self(), $thr->tid(), threads->tid(), "$thr",
-threads->object($tid), threads->yield(), threads->list(),
-threads->list(threads::all), threads->list(threads::running),
-threads->list(threads::joinable), $thr1->equal($thr2), async BLOCK;,
-$thr->error(), $thr->_handle(), threads->_handle()
-
-=item EXITING A THREAD
-
-threads->exit(), threads->exit(status), die(), exit(status), use threads
-'exit' => 'threads_only', threads->create({'exit' => 'thread_only'}, ...),
-$thr->set_thread_exit_only(boolean), threads->set_thread_exit_only(boolean)
-
-=item THREAD STATE
-
-$thr->is_running(), $thr->is_joinable(), $thr->is_detached(),
-threads->is_detached()
-
-=item THREAD CONTEXT
-
-=over 4
-
-=item Explicit context
-
-=item Implicit context
-
-=item $thr->wantarray()
-
-=item threads->wantarray()
-
-=back
-
-=item THREAD STACK SIZE
-
-threads->get_stack_size();, $size = $thr->get_stack_size();, $old_size =
-threads->set_stack_size($new_size);, use threads ('stack_size' => VALUE);,
-$ENV{'PERL5_ITHREADS_STACK_SIZE'}, threads->create({'stack_size' => VALUE},
-FUNCTION, ARGS), $thr2 = $thr1->create(FUNCTION, ARGS)
-
-=item THREAD SIGNALLING
-
-$thr->kill('SIG...');
-
-=item WARNINGS
-
-Perl exited with active threads:, Thread creation failed: pthread_create
-returned #, Thread # terminated abnormally: .., Using minimum thread stack
-size of #, Thread creation failed: pthread_attr_setstacksize(I<SIZE>)
-returned 22
-
-=item ERRORS
-
-This Perl not built to support threads, Cannot change stack size of an
-existing thread, Cannot signal threads without safe signals, Unrecognized
-signal name: ..
-
-=item BUGS AND LIMITATIONS
-
-Thread-safe modules, Using non-thread-safe modules, Memory consumption,
-Current working directory, Environment variables, Catching signals,
-Parent-child threads, Creating threads inside special blocks, Unsafe
-signals, Perl has been built with C<PERL_OLD_SIGNALS> (see C<perl -V>), The
-environment variable C<PERL_SIGNALS> is set to C<unsafe> (see
-L<perlrun/"PERL_SIGNALS">), The module L<Perl::Unsafe::Signals> is used,
-Returning closures from threads, Returning objects from threads, END blocks
-in threads, Open directory handles, Perl Bugs and the CPAN Version of
-L<threads>
-
-=item REQUIREMENTS
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item LICENSE
-
-=item ACKNOWLEDGEMENTS
-
-=back
-
-=head2 threads::shared - Perl extension for sharing data structures between
-threads
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item EXPORT
-
-=item FUNCTIONS
-
-share VARIABLE, shared_clone REF, is_shared VARIABLE, lock VARIABLE,
-cond_wait VARIABLE, cond_wait CONDVAR, LOCKVAR, cond_timedwait VARIABLE,
-ABS_TIMEOUT, cond_timedwait CONDVAR, ABS_TIMEOUT, LOCKVAR, cond_signal
-VARIABLE, cond_broadcast VARIABLE
-
-=item OBJECTS
-
-=item NOTES
-
-=item BUGS AND LIMITATIONS
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item LICENSE
-
-=back
-
-=head2 utf8 - Perl pragma to enable/disable UTF-8 (or UTF-EBCDIC) in source
-code
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Utility functions
-
-$num_octets = utf8::upgrade($string), $success = utf8::downgrade($string[,
-FAIL_OK]), utf8::encode($string), $success = utf8::decode($string), $flag =
-utf8::is_utf8(STRING), $flag = utf8::valid(STRING)
-
-=back
-
-=item BUGS
-
-=item SEE ALSO
-
-=back
-
-=head2 vars - Perl pragma to predeclare global variable names (obsolete)
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 version - Perl extension for Version Objects
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item TYPES OF VERSION OBJECTS
-
-Decimal Versions, Dotted Decimal Versions
-
-=item DECLARING VERSIONS
-
-=over 4
-
-=item How to convert a module from decimal to dotted-decimal
-
-=item How to C<declare()> a dotted-decimal version
-
-=back
-
-=item PARSING AND COMPARING VERSIONS
-
-=over 4
-
-=item How to C<parse()> a version
-
-=item How to check for a legal version string
-
-C<is_lax()>, C<is_strict()>
-
-=item How to compare version objects
-
-=back
-
-=item OBJECT METHODS
-
-=over 4
-
-=item is_alpha()
-
-=item is_qv()
-
-=item normal()
-
-=item numify()
-
-=item stringify()
-
-=back
-
-=item EXPORTED FUNCTIONS
-
-=over 4
-
-=item qv()
-
-=item is_lax()
-
-=item is_strict()
-
-=back
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 version::Internals - Perl extension for Version Objects
-
-=over 4
-
-=item DESCRIPTION
-
-=item WHAT IS A VERSION?
-
-Decimal Versions, Dotted-Decimal Versions
-
-=over 4
-
-=item Decimal Versions
-
-=item Dotted-Decimal Versions
-
-=item Alpha Versions
-
-=item Regular Expressions for Version Parsing
-
-C<$version::LAX>, C<$version::STRICT>, v1.234.5
-
-=back
-
-=item IMPLEMENTATION DETAILS
-
-=over 4
-
-=item Equivalence between Decimal and Dotted-Decimal Versions
-
-=item Quoting Rules
-
-=item What about v-strings?
-
-=item Version Object Internals
-
-original, qv, alpha, version
-
-=item Replacement UNIVERSAL::VERSION
-
-=back
-
-=item USAGE DETAILS
-
-=over 4
-
-=item Using modules that use version.pm
-
-Decimal versions always work, Dotted-Decimal version work sometimes
-
-=item Object Methods
-
-new(), qv(), Normal Form, Numification, Stringification, Comparison
-operators, Logical Operators
-
-=back
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 version::Requirements, Version::Requirements - a set of version
-requirements for a CPAN dist
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item new
-
-=item add_minimum
-
-=item add_maximum
-
-=item add_exclusion
-
-=item exact_version
-
-=item add_requirements
-
-=item accepts_module
-
-=item clear_requirement
-
-=item required_modules
-
-=item clone
-
-=item is_simple
-
-=item is_finalized
-
-=item finalize
-
-=item as_string_hash
-
-=item from_string_hash
-
-=back
-
-=item AUTHOR
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 vmsish - Perl pragma to control VMS-specific language features
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-C<vmsish status>, C<vmsish exit>, C<vmsish time>, C<vmsish hushed>
-
-=back
-
-=head2 warnings - Perl pragma to control optional warnings
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-use warnings::register, warnings::enabled(), warnings::enabled($category),
-warnings::enabled($object), warnings::fatal_enabled(),
-warnings::fatal_enabled($category), warnings::fatal_enabled($object),
-warnings::warn($message), warnings::warn($category, $message),
-warnings::warn($object, $message), warnings::warnif($message),
-warnings::warnif($category, $message), warnings::warnif($object, $message),
-warnings::register_categories(@names)
-
-=back
-
-=head2 warnings::register - warnings import function
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head1 MODULE DOCUMENTATION
-
-=head2 AnyDBM_File - provide framework for multiple DBMs
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item DBM Comparisons
-
-[0], [1], [2], [3]
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 App::Cpan - easily interact with CPAN from the command line
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Options
-
--a, -A module [ module ... ], -c module, -C module [ module ... ], -D
-module [ module ... ], -f, -F, -g module [ module ... ], -G module [ module
-... ], -h, -i, -j Config.pm, -J, -l, -L author [ author ... ], -m, -O, -t,
--r, -u, -v
-
-=item Examples
-
-=item Methods
-
-=back
-
-=back
-
-run()
-
-=over 4
-
-=item EXIT VALUES
-
-=item TO DO
-
-=item BUGS
-
-=item SEE ALSO
-
-=item SOURCE AVAILABILITY
-
-=item CREDITS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 App::Prove - Implements the C<prove> command.
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item SYNOPSIS
-
-=back
-
-=over 4
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=over 4
-
-=item Attributes
-
-C<archive>, C<argv>, C<backwards>, C<blib>, C<color>, C<directives>,
-C<dry>, C<exec>, C<extensions>, C<failures>, C<comments>, C<formatter>,
-C<harness>, C<ignore_exit>, C<includes>, C<jobs>, C<lib>, C<merge>,
-C<modules>, C<parse>, C<plugins>, C<quiet>, C<really_quiet>, C<recurse>,
-C<rules>, C<show_count>, C<show_help>, C<show_man>, C<show_version>,
-C<shuffle>, C<state>, C<state_class>, C<taint_fail>, C<taint_warn>,
-C<test_args>, C<timer>, C<verbose>, C<warnings_fail>, C<warnings_warn>,
-C<tapversion>, C<trap>
-
-=back
-
-=over 4
-
-=item PLUGINS
-
-=over 4
-
-=item Sample Plugin
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 App::Prove::State - State storage for the C<prove> command.
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item SYNOPSIS
-
-=back
-
-=over 4
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-C<store>, C<extensions> (optional), C<result_class> (optional)
-
-=back
-
-=back
-
-=over 4
-
-=item C<result_class>
-
-=back
-
-=over 4
-
-=item C<extensions>
-
-=back
-
-=over 4
-
-=item C<results>
-
-=back
-
-=over 4
-
-=item C<commit>
-
-=back
-
-=over 4
-
-=item Instance Methods
-
-C<last>, C<failed>, C<passed>, C<all>, C<hot>, C<todo>, C<slow>, C<fast>,
-C<new>, C<old>, C<save>
-
-=back
-
-=head2 App::Prove::State::Result - Individual test suite results.
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item SYNOPSIS
-
-=back
-
-=over 4
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=over 4
-
-=item C<state_version>
-
-=back
-
-=over 4
-
-=item C<test_class>
-
-=back
-
-=head2 App::Prove::State::Result::Test - Individual test results.
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item SYNOPSIS
-
-=back
-
-=over 4
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=over 4
-
-=item Instance Methods
-
-=back
-
-=head2 Archive::Extract - A generic archive extracting mechanism
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item METHODS
-
-=over 4
-
-=item $ae = Archive::Extract->new(archive => '/path/to/archive',[type =>
-TYPE])
-
-tar, tgz, gz, Z, zip, bz2, tbz, lzma, xz, txz
-
-=back
-
-=back
-
-=over 4
-
-=item $ae->extract( [to => '/output/path'] )
-
-$ae->extract_path, $ae->files
-
-=back
-
-=over 4
-
-=item ACCESSORS
-
-=over 4
-
-=item $ae->error([BOOL])
-
-=item $ae->extract_path
-
-=item $ae->files
-
-=item $ae->archive
-
-=item $ae->type
-
-=item $ae->types
-
-=back
-
-=back
-
-=over 4
-
-=item $ae->is_tgz
-
-=item $ae->is_tar
-
-=item $ae->is_gz
-
-=item $ae->is_Z
-
-=item $ae->is_zip
-
-=item $ae->is_lzma
-
-=item $ae->is_xz
-
-=back
-
-=over 4
-
-=item $ae->bin_tar
-
-=item $ae->bin_gzip
-
-=item $ae->bin_unzip
-
-=item $ae->bin_unlzma
-
-=item $ae->bin_unxz
-
-=back
-
-=over 4
-
-=item $bool = $ae->have_old_bunzip2
-
-=back
-
-=over 4
-
-=item debug( MESSAGE )
-
-=back
-
-=over 4
-
-=item HOW IT WORKS
-
-=item CAVEATS
-
-=over 4
-
-=item File Extensions
-
-=item Supporting Very Large Files
-
-=item Bunzip2 support of arbitrary extensions.
-
-=back
-
-=item GLOBAL VARIABLES
-
-=over 4
-
-=item $Archive::Extract::DEBUG
-
-=item $Archive::Extract::WARN
-
-=item $Archive::Extract::PREFER_BIN
-
-=back
-
-=item TODO / CAVEATS
-
-Mime magic support, Thread safety
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Archive::Tar - module for manipulations of tar archives
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Object Methods
-
-=over 4
-
-=item Archive::Tar->new( [$file, $compressed] )
-
-=back
-
-=back
-
-=over 4
-
-=item $tar->read ( $filename|$handle, [$compressed, {opt => 'val'}] )
-
-limit, filter, md5, extract
-
-=back
-
-=over 4
-
-=item $tar->contains_file( $filename )
-
-=back
-
-=over 4
-
-=item $tar->extract( [@filenames] )
-
-=back
-
-=over 4
-
-=item $tar->extract_file( $file, [$extract_path] )
-
-=back
-
-=over 4
-
-=item $tar->list_files( [\@properties] )
-
-=back
-
-=over 4
-
-=item $tar->get_files( [@filenames] )
-
-=back
-
-=over 4
-
-=item $tar->get_content( $file )
-
-=back
-
-=over 4
-
-=item $tar->replace_content( $file, $content )
-
-=back
-
-=over 4
-
-=item $tar->rename( $file, $new_name )
-
-=back
-
-=over 4
-
-=item $tar->chmod( $file, $mode )
-
-=back
-
-=over 4
-
-=item $tar->chown( $file, $uname [, $gname] )
-
-=back
-
-=over 4
-
-=item $tar->remove (@filenamelist)
-
-=back
-
-=over 4
-
-=item $tar->clear
-
-=back
-
-=over 4
-
-=item $tar->write ( [$file, $compressed, $prefix] )
-
-=back
-
-=over 4
-
-=item $tar->add_files( @filenamelist )
-
-=back
-
-=over 4
-
-=item $tar->add_data ( $filename, $data, [$opthashref] )
-
-FILE, HARDLINK, SYMLINK, CHARDEV, BLOCKDEV, DIR, FIFO, SOCKET
-
-=back
-
-=over 4
-
-=item $tar->error( [$BOOL] )
-
-=back
-
-=over 4
-
-=item $tar->setcwd( $cwd );
-
-=back
-
-=over 4
-
-=item Class Methods
-
-=over 4
-
-=item Archive::Tar->create_archive($file, $compressed, @filelist)
-
-=back
-
-=back
-
-=over 4
-
-=item Archive::Tar->iter( $filename, [ $compressed, {opt => $val} ] )
-
-=back
-
-=over 4
-
-=item Archive::Tar->list_archive($file, $compressed, [\@properties])
-
-=back
-
-=over 4
-
-=item Archive::Tar->extract_archive($file, $compressed)
-
-=back
-
-=over 4
-
-=item $bool = Archive::Tar->has_io_string
-
-=back
-
-=over 4
-
-=item $bool = Archive::Tar->has_perlio
-
-=back
-
-=over 4
-
-=item $bool = Archive::Tar->has_zlib_support
-
-=back
-
-=over 4
-
-=item $bool = Archive::Tar->has_bzip2_support
-
-=back
-
-=over 4
-
-=item Archive::Tar->can_handle_compressed_files
-
-=back
-
-=over 4
-
-=item GLOBAL VARIABLES
-
-=over 4
-
-=item $Archive::Tar::FOLLOW_SYMLINK
-
-=item $Archive::Tar::CHOWN
-
-=item $Archive::Tar::CHMOD
-
-=item $Archive::Tar::SAME_PERMISSIONS
-
-=item $Archive::Tar::DO_NOT_USE_PREFIX
-
-=item $Archive::Tar::DEBUG
-
-=item $Archive::Tar::WARN
-
-=item $Archive::Tar::error
-
-=item $Archive::Tar::INSECURE_EXTRACT_MODE
-
-=item $Archive::Tar::HAS_PERLIO
-
-=item $Archive::Tar::HAS_IO_STRING
-
-=item $Archive::Tar::ZERO_PAD_NUMBERS
-
-=back
-
-=item FAQ
-
-What's the minimum perl version required to run Archive::Tar?, Isn't
-Archive::Tar slow?, Isn't Archive::Tar heavier on memory than /bin/tar?,
-Can you lazy-load data instead?, How much memory will an X kb tar file
-need?, What do you do with unsupported filetypes in an archive?, I'm using
-WinZip, or some other non-POSIX client, and files are not being extracted
-properly!, How do I extract only files that have property X from an
-archive?, How do I access .tar.Z files?, How do I handle Unicode strings?
-
-=item CAVEATS
-
-=item TODO
-
-Check if passed in handles are open for read/write, Allow archives to be
-passed in as string, Facilitate processing an opened filehandle of a
-compressed archive
-
-=item SEE ALSO
-
-The GNU tar specification, The PAX format specification, A comparison of
-GNU and POSIX tar standards;
-C<http://www.delorie.com/gnu/docs/tar/tar_114.html>, GNU tar intends to
-switch to POSIX compatibility, A Comparison between various tar
-implementations
-
-=item AUTHOR
-
-=item ACKNOWLEDGEMENTS
-
-=item COPYRIGHT
-
-=back
-
-=head2 Archive::Tar::File - a subclass for in-memory extracted file from
-Archive::Tar
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Accessors
-
-name, mode, uid, gid, size, mtime, chksum, type, linkname, magic, version,
-uname, gname, devmajor, devminor, prefix, raw
-
-=back
-
-=item Methods
-
-=over 4
-
-=item Archive::Tar::File->new( file => $path )
-
-=item Archive::Tar::File->new( data => $path, $data, $opt )
-
-=item Archive::Tar::File->new( chunk => $chunk )
-
-=back
-
-=back
-
-=over 4
-
-=item $bool = $file->extract( [ $alternative_name ] )
-
-=back
-
-=over 4
-
-=item $path = $file->full_path
-
-=back
-
-=over 4
-
-=item $bool = $file->validate
-
-=back
-
-=over 4
-
-=item $bool = $file->has_content
-
-=back
-
-=over 4
-
-=item $content = $file->get_content
-
-=back
-
-=over 4
-
-=item $cref = $file->get_content_by_ref
-
-=back
-
-=over 4
-
-=item $bool = $file->replace_content( $content )
-
-=back
-
-=over 4
-
-=item $bool = $file->rename( $new_name )
-
-=back
-
-=over 4
-
-=item $bool = $file->chmod $mode)
-
-=back
-
-=over 4
-
-=item $bool = $file->chown( $user [, $group])
-
-=back
-
-=over 4
-
-=item Convenience methods
-
-$file->is_file, $file->is_dir, $file->is_hardlink, $file->is_symlink,
-$file->is_chardev, $file->is_blockdev, $file->is_fifo, $file->is_socket,
-$file->is_longlink, $file->is_label, $file->is_unknown
-
-=back
-
-=head2 Attribute::Handlers - Simpler definition of attribute handlers
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-[0], [1], [2], [3], [4], [5], [6], [7]
-
-=over 4
-
-=item Typed lexicals
-
-=item Type-specific attribute handlers
-
-=item Non-interpretive attribute handlers
-
-=item Phase-specific attribute handlers
-
-=item Attributes as C<tie> interfaces
-
-=back
-
-=item EXAMPLES
-
-=item UTILITY FUNCTIONS
-
-findsym
-
-=item DIAGNOSTICS
-
-C<Bad attribute type: ATTR(%s)>, C<Attribute handler %s doesn't handle %s
-attributes>, C<Declaration of %s attribute in package %s may clash with
-future reserved word>, C<Can't have two ATTR specifiers on one subroutine>,
-C<Can't autotie a %s>, C<Internal error: %s symbol went missing>, C<Won't
-be able to apply END handler>
-
-=item AUTHOR
-
-=item BUGS
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 AutoLoader - load subroutines only on demand
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Subroutine Stubs
-
-=item Using B<AutoLoader>'s AUTOLOAD Subroutine
-
-=item Overriding B<AutoLoader>'s AUTOLOAD Subroutine
-
-=item Package Lexicals
-
-=item Not Using AutoLoader
-
-=item B<AutoLoader> vs. B<SelfLoader>
-
-=back
-
-=item CAVEATS
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 AutoSplit - split a package for autoloading
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-$keep, $check, $modtime
-
-=over 4
-
-=item Multiple packages
-
-=back
-
-=item DIAGNOSTICS
-
-=item AUTHOR
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 B - The Perl Compiler Backend
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item OVERVIEW
-
-=item Utility Functions
-
-=over 4
-
-=item Functions Returning C<B::SV>, C<B::AV>, C<B::HV>, and C<B::CV>
-objects
-
-sv_undef, sv_yes, sv_no, svref_2object(SVREF), amagic_generation, init_av,
-check_av, unitcheck_av, begin_av, end_av, comppadlist, regex_padav, main_cv
-
-=item Functions for Examining the Symbol Table
-
-walksymtable(SYMREF, METHOD, RECURSE, PREFIX)
-
-=item Functions Returning C<B::OP> objects or for walking op trees
-
-main_root, main_start, walkoptree(OP, METHOD), walkoptree_debug(DEBUG)
-
-=item Miscellaneous Utility Functions
-
-ppname(OPNUM), hash(STR), cast_I32(I), minus_c, cstring(STR),
-perlstring(STR), class(OBJ), threadsv_names
-
-=item Exported utility variables
-
-@optype, @specialsv_name
-
-=back
-
-=item OVERVIEW OF CLASSES
-
-=over 4
-
-=item SV-RELATED CLASSES
-
-=item B::SV Methods
-
-REFCNT, FLAGS, object_2svref
-
-=item B::IV Methods
-
-IV, IVX, UVX, int_value, needs64bits, packiv
-
-=item B::NV Methods
-
-NV, NVX
-
-=item B::RV Methods
-
-RV
-
-=item B::PV Methods
-
-PV, RV, PVX, CUR, LEN
-
-=item B::PVMG Methods
-
-MAGIC, SvSTASH
-
-=item B::MAGIC Methods
-
-MOREMAGIC, precomp, PRIVATE, TYPE, FLAGS, OBJ, PTR, REGEX
-
-=item B::PVLV Methods
-
-TARGOFF, TARGLEN, TYPE, TARG
-
-=item B::BM Methods
-
-USEFUL, PREVIOUS, RARE, TABLE
-
-=item B::GV Methods
-
-is_empty, NAME, SAFENAME, STASH, SV, IO, FORM, AV, HV, EGV, CV, CVGEN,
-LINE, FILE, FILEGV, GvREFCNT, FLAGS
-
-=item B::IO Methods
-
-LINES, PAGE, PAGE_LEN, LINES_LEFT, TOP_NAME, TOP_GV, FMT_NAME, FMT_GV,
-BOTTOM_NAME, BOTTOM_GV, SUBPROCESS, IoTYPE, IoFLAGS, IsSTD
-
-=item B::AV Methods
-
-FILL, MAX, ARRAY, ARRAYelt, OFF, AvFLAGS
-
-=item B::CV Methods
-
-STASH, START, ROOT, GV, FILE, DEPTH, PADLIST, OUTSIDE, OUTSIDE_SEQ, XSUB,
-XSUBANY, CvFLAGS, const_sv
-
-=item B::HV Methods
-
-FILL, MAX, KEYS, RITER, NAME, ARRAY, PMROOT
-
-=item OP-RELATED CLASSES
-
-=item B::OP Methods
-
-next, sibling, name, ppaddr, desc, targ, type, opt, flags, private, spare
-
-=item B::UNOP METHOD
-
-first
-
-=item B::BINOP METHOD
-
-last
-
-=item B::LOGOP METHOD
-
-other
-
-=item B::LISTOP METHOD
-
-children
-
-=item B::PMOP Methods
-
-pmreplroot, pmreplstart, pmnext, pmflags, extflags, precomp, pmoffset
-
-=item B::SVOP METHOD
-
-sv, gv
-
-=item B::PADOP METHOD
-
-padix
-
-=item B::PVOP METHOD
-
-pv
-
-=item B::LOOP Methods
-
-redoop, nextop, lastop
-
-=item B::COP Methods
-
-label, stash, stashpv, stashlen, file, cop_seq, arybase, line, warnings,
-io, hints, hints_hash
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 B::Concise - Walk Perl syntax tree, printing concise info about ops
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item EXAMPLE
-
-=item OPTIONS
-
-=over 4
-
-=item Options for Opcode Ordering
-
-B<-basic>, B<-exec>, B<-tree>
-
-=item Options for Line-Style
-
-B<-concise>, B<-terse>, B<-linenoise>, B<-debug>, B<-env>
-
-=item Options for tree-specific formatting
-
-B<-compact>, B<-loose>, B<-vt>, B<-ascii>
-
-=item Options controlling sequence numbering
-
-B<-base>I<n>, B<-bigendian>, B<-littleendian>
-
-=item Other options
-
-B<-src>, B<-stash="somepackage">, B<-main>, B<-nomain>, B<-nobanner>,
-B<-banner>, B<-banneris> => subref
-
-=item Option Stickiness
-
-=back
-
-=item ABBREVIATIONS
-
-=over 4
-
-=item OP class abbreviations
-
-=item OP flags abbreviations
-
-=back
-
-=item FORMATTING SPECIFICATIONS
-
-=over 4
-
-=item Special Patterns
-
-B<(x(>I<exec_text>B<;>I<basic_text>B<)x)>, B<(*(>I<text>B<)*)>,
-B<(*(>I<text1>B<;>I<text2>B<)*)>, B<(?(>I<text1>B<#>I<var>I<Text2>B<)?)>,
-B<~>
-
-=item # Variables
-
-B<#>I<var>, B<#>I<var>I<N>, B<#>I<Var>, B<#addr>, B<#arg>, B<#class>,
-B<#classsym>, B<#coplabel>, B<#exname>, B<#extarg>, B<#firstaddr>,
-B<#flags>, B<#flagval>, B<#hints>, B<#hintsval>, B<#hyphseq>, B<#label>,
-B<#lastaddr>, B<#name>, B<#NAME>, B<#next>, B<#nextaddr>, B<#noise>,
-B<#private>, B<#privval>, B<#seq>, B<#seqnum>, B<#opt>, B<#sibaddr>,
-B<#svaddr>, B<#svclass>, B<#svval>, B<#targ>, B<#targarg>, B<#targarglife>,
-B<#typenum>
-
-=back
-
-=item One-Liner Command tips
-
-perl -MO=Concise,bar foo.pl, perl -MDigest::MD5=md5 -MO=Concise,md5 -e1,
-perl -MPOSIX -MO=Concise,_POSIX_ARG_MAX -e1, perl -MPOSIX -MO=Concise,a -e
-'print _POSIX_SAVED_IDS', perl -MPOSIX -MO=Concise,a -e 'sub
-a{_POSIX_SAVED_IDS}', perl -MB::Concise -e
-'B::Concise::compile("-exec","-src", \%B::Concise::)->()'
-
-=item Using B::Concise outside of the O framework
-
-=over 4
-
-=item Example: Altering Concise Renderings
-
-=item set_style()
-
-=item set_style_standard($name)
-
-=item add_style ()
-
-=item add_callback ()
-
-=item Running B::Concise::compile()
-
-=item B::Concise::reset_sequence()
-
-=item Errors
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 B::Debug - Walk Perl syntax tree, printing debug info about ops
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item OPTIONS
-
-=item AUTHOR
-
-=item LICENSE
-
-=back
-
-=head2 B::Deparse - Perl compiler backend to produce perl code
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item OPTIONS
-
-B<-d>, B<-f>I<FILE>, B<-l>, B<-p>, B<-P>, B<-q>, B<-s>I<LETTERS>, B<C>,
-B<i>I<NUMBER>, B<T>, B<v>I<STRING>B<.>, B<-x>I<LEVEL>
-
-=item USING B::Deparse AS A MODULE
-
-=over 4
-
-=item Synopsis
-
-=item Description
-
-=item new
-
-=item ambient_pragmas
-
-strict, $[, bytes, utf8, integer, re, warnings, hint_bits, warning_bits,
-%^H
-
-=item coderef2text
-
-=back
-
-=item BUGS
-
-=item AUTHOR
-
-=back
-
-=head2 B::Lint - Perl lint
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item OPTIONS AND LINT CHECKS
-
-B<magic-diamond>, B<context>, B<implicit-read> and B<implicit-write>,
-B<bare-subs>, B<dollar-underscore>, B<private-names>, B<undefined-subs>,
-B<regexp-variables>, B<all>, B<none>
-
-=item NON LINT-CHECK OPTIONS
-
-B<-u Package>
-
-=item EXTENDING LINT
-
-=item TODO
-
-while(<FH>) stomps $_, strict oo, unchecked system calls, more tests,
-validate against older perls
-
-=item BUGS
-
-=item AUTHOR
-
-=item ACKNOWLEDGEMENTS
-
-=back
-
-=head2 B::Lint::Debug - Adds debugging stringification to B::
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=head2 B::Showlex - Show lexical variables used in functions or files
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item EXAMPLES
-
-=over 4
-
-=item OPTIONS
-
-=back
-
-=item SEE ALSO
-
-=item TODO
-
-=item AUTHOR
-
-=back
-
-=head2 B::Terse - Walk Perl syntax tree, printing terse info about ops
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=back
-
-=head2 B::Xref - Generates cross reference reports for Perl programs
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-i, &, s, r
-
-=item OPTIONS
-
-C<-oFILENAME>, C<-r>, C<-d>, C<-D[tO]>
-
-=item BUGS
-
-=item AUTHOR
-
-=back
-
-=head2 Benchmark - benchmark running times of Perl code
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Methods
-
-new, debug, iters
-
-=item Standard Exports
-
-timeit(COUNT, CODE), timethis ( COUNT, CODE, [ TITLE, [ STYLE ]] ),
-timethese ( COUNT, CODEHASHREF, [ STYLE ] ), timediff ( T1, T2 ), timestr (
-TIMEDIFF, [ STYLE, [ FORMAT ] ] )
-
-=item Optional Exports
-
-clearcache ( COUNT ), clearallcache ( ), cmpthese ( COUNT, CODEHASHREF, [
-STYLE ] ), cmpthese ( RESULTSHASHREF, [ STYLE ] ), countit(TIME, CODE),
-disablecache ( ), enablecache ( ), timesum ( T1, T2 )
-
-=item :hireswallclock
-
-=back
-
-=item NOTES
-
-=item EXAMPLES
-
-=item INHERITANCE
-
-=item CAVEATS
-
-=item SEE ALSO
-
-=item AUTHORS
-
-=item MODIFICATION HISTORY
-
-=back
-
-=head2 CGI - Handle Common Gateway Interface requests and responses
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item PROGRAMMING STYLE
-
-=item CALLING CGI.PM ROUTINES
-
-=item CREATING A NEW QUERY OBJECT (OBJECT-ORIENTED STYLE):
-
-=item CREATING A NEW QUERY OBJECT FROM AN INPUT FILE
-
-=item FETCHING A LIST OF KEYWORDS FROM THE QUERY:
-
-=item FETCHING THE NAMES OF ALL THE PARAMETERS PASSED TO YOUR SCRIPT:
-
-=item FETCHING THE VALUE OR VALUES OF A SINGLE NAMED PARAMETER:
-
-=item SETTING THE VALUE(S) OF A NAMED PARAMETER:
-
-=item APPENDING ADDITIONAL VALUES TO A NAMED PARAMETER:
-
-=item IMPORTING ALL PARAMETERS INTO A NAMESPACE:
-
-=item DELETING A PARAMETER COMPLETELY:
-
-=item DELETING ALL PARAMETERS:
-
-=item HANDLING NON-URLENCODED ARGUMENTS
-
-=item DIRECT ACCESS TO THE PARAMETER LIST:
-
-=item FETCHING THE PARAMETER LIST AS A HASH:
-
-=item SAVING THE STATE OF THE SCRIPT TO A FILE:
-
-=item RETRIEVING CGI ERRORS
-
-=item USING THE FUNCTION-ORIENTED INTERFACE
-
-B<:cgi>, B<:form>, B<:html2>, B<:html3>, B<:html4>, B<:netscape>, B<:html>,
-B<:standard>, B<:all>
-
-=item PRAGMAS
-
--any, -compile, -nosticky, -tabindex, -no_undef_params, -no_xhtml, -utf8,
--nph, -newstyle_urls, -oldstyle_urls, -autoload, -no_debug, -debug,
--private_tempfiles
-
-=item SPECIAL FORMS FOR IMPORTING HTML-TAG FUNCTIONS
-
-1. start_table() (generates a <table> tag), 2. end_table() (generates a
-</table> tag), 3. start_ul() (generates a <ul> tag), 4. end_ul() (generates
-a </ul> tag)
-
-=back
-
-=item GENERATING DYNAMIC DOCUMENTS
-
-=over 4
-
-=item CREATING A STANDARD HTTP HEADER:
-
-=item GENERATING A REDIRECTION HEADER
-
-=item CREATING THE HTML DOCUMENT HEADER
-
-B<Parameters:>, 4, 5, 6..
-
-=item ENDING THE HTML DOCUMENT:
-
-=item CREATING A SELF-REFERENCING URL THAT PRESERVES STATE INFORMATION:
-
-=item OBTAINING THE SCRIPT'S URL
-
-B<-absolute>, B<-relative>, B<-full>, B<-path> (B<-path_info>), B<-query>
-(B<-query_string>), B<-base>, B<-rewrite>
-
-=item MIXING POST AND URL PARAMETERS
-
-=back
-
-=item CREATING STANDARD HTML ELEMENTS:
-
-=over 4
-
-=item PROVIDING ARGUMENTS TO HTML SHORTCUTS
-
-=item THE DISTRIBUTIVE PROPERTY OF HTML SHORTCUTS
-
-=item HTML SHORTCUTS AND LIST INTERPOLATION
-
-=item NON-STANDARD HTML SHORTCUTS
-
-=item AUTOESCAPING HTML
-
-$escaped_string = escapeHTML("unescaped string");, $charset =
-charset([$charset]);, $flag = autoEscape([$flag]);
-
-=item PRETTY-PRINTING HTML
-
-=back
-
-=item CREATING FILL-OUT FORMS:
-
-=over 4
-
-=item CREATING AN ISINDEX TAG
-
-=item STARTING AND ENDING A FORM
-
-B<application/x-www-form-urlencoded>, B<multipart/form-data>
-
-=item FORM ELEMENTS
-
-B<-name>, B<-value>, B<-values>, B<-tabindex>, B<-id>, B<-override>,
-B<-onChange>, B<-onFocus>, B<-onBlur>, B<-onMouseOver>, B<-onMouseOut>,
-B<-onSelect>
-
-=item CREATING A TEXT FIELD
-
-B<Parameters>
-
-=item CREATING A BIG TEXT FIELD
-
-=item CREATING A PASSWORD FIELD
-
-=item CREATING A FILE UPLOAD FIELD
-
-B<Parameters>
-
-=item PROCESSING A FILE UPLOAD FIELD
-
-=item CREATING A POPUP MENU
-
-=item CREATING AN OPTION GROUP
-
-=item CREATING A SCROLLING LIST
-
-B<Parameters:>
-
-=item CREATING A GROUP OF RELATED CHECKBOXES
-
-B<Parameters:>
-
-=item CREATING A STANDALONE CHECKBOX
-
-B<Parameters:>
-
-=item CREATING A RADIO BUTTON GROUP
-
-B<Parameters:>
-
-=item CREATING A SUBMIT BUTTON
-
-B<Parameters:>
-
-=item CREATING A RESET BUTTON
-
-=item CREATING A DEFAULT BUTTON
-
-=item CREATING A HIDDEN FIELD
-
-B<Parameters:>
-
-=item CREATING A CLICKABLE IMAGE BUTTON
-
-B<Parameters:>, 3. The third option (-align, optional) is an alignment
-type, and may be TOP, BOTTOM or MIDDLE
-
-=item CREATING A JAVASCRIPT ACTION BUTTON
-
-=back
-
-=item HTTP COOKIES
-
-1. an expiration time, 2. a domain, 3. a path, 4. a "secure" flag,
-B<-name>, B<-value>, B<-path>, B<-domain>, B<-expires>, B<-secure>
-
-=item WORKING WITH FRAMES
-
-1. Create a <Frameset> document, 2. Specify the destination for the
-document in the HTTP header, 3. Specify the destination for the document in
-the <form> tag
-
-=item SUPPORT FOR JAVASCRIPT
-
-B<onLoad>, B<onUnload>, B<onSubmit>, B<onClick>, B<onChange>, B<onFocus>,
-B<onBlur>, B<onSelect>, B<onMouseOver>, B<onMouseOut>
-
-=item LIMITED SUPPORT FOR CASCADING STYLE SHEETS
-
-=item DEBUGGING
-
-=over 4
-
-=item DUMPING OUT ALL THE NAME/VALUE PAIRS
-
-=back
-
-=item FETCHING ENVIRONMENT VARIABLES
-
-B<Accept()>, B<raw_cookie()>, B<user_agent()>, B<path_info()>,
-B<path_translated()>, B<remote_host()>, B<remote_addr()>, B<script_name()>
-Return the script name as a partial URL, for self-referring scripts,
-B<referer()>, B<auth_type ()>, B<server_name ()>, B<virtual_host ()>,
-B<server_port ()>, B<virtual_port ()>, B<server_software ()>, B<remote_user
-()>, B<user_name ()>, B<request_method()>, B<content_type()>, B<http()>,
-B<https()>
-
-=item USING NPH SCRIPTS
-
-In the B<use> statement, By calling the B<nph()> method:, By using B<-nph>
-parameters
-
-=item Server Push
-
-multipart_init(), multipart_start(), multipart_end(), multipart_final()
-
-=item Avoiding Denial of Service Attacks
-
-B<$CGI::POST_MAX>, B<$CGI::DISABLE_UPLOADS>, B<1. On a script-by-script
-basis>, B<2. Globally for all scripts>
-
-=item COMPATIBILITY WITH CGI-LIB.PL
-
-=over 4
-
-=item Cgi-lib functions that are available in CGI.pm
-
-=item Cgi-lib functions that are not available in CGI.pm
-
-=back
-
-=item AUTHOR INFORMATION
-
-=item CREDITS
-
-Matt Heffron (heffron@falstaff.css.beckman.com), James Taylor
-(james.taylor@srs.gov), Scott Anguish <sanguish@digifix.com>, Mike Jewell
-(mlj3u@virginia.edu), Timothy Shimmin (tes@kbs.citri.edu.au), Joergen Haegg
-(jh@axis.se), Laurent Delfosse (delfosse@delfosse.com), Richard Resnick
-(applepi1@aol.com), Craig Bishop (csb@barwonwater.vic.gov.au), Tony Curtis
-(tc@vcpc.univie.ac.at), Tim Bunce (Tim.Bunce@ig.co.uk), Tom Christiansen
-(tchrist@convex.com), Andreas Koenig (k@franz.ww.TU-Berlin.DE), Tim
-MacKenzie (Tim.MacKenzie@fulcrum.com.au), Kevin B. Hendricks
-(kbhend@dogwood.tyler.wm.edu), Stephen Dahmen (joyfire@inxpress.net), Ed
-Jordan (ed@fidalgo.net), David Alan Pisoni (david@cnation.com), Doug
-MacEachern (dougm@opengroup.org), Robin Houston (robin@oneworld.org),
-...and many many more..
-
-=item A COMPLETE EXAMPLE OF A SIMPLE FORM-BASED SCRIPT
-
-=item BUGS
-
-=item SEE ALSO
-
-=back
-
-=head2 CGI::Apache - Backward compatibility module for CGI.pm
-
-=over 4
-
-=item SYNOPSIS
-
-=item ABSTRACT
-
-=item DESCRIPTION
-
-=item AUTHOR INFORMATION
-
-=item BUGS
-
-=item SEE ALSO
-
-=back
-
-=head2 CGI::Carp, B<CGI::Carp> - CGI routines for writing to the HTTPD (or
-other) error log
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item REDIRECTING ERROR MESSAGES
-
-=item MAKING PERL ERRORS APPEAR IN THE BROWSER WINDOW
-
-=over 4
-
-=item Changing the default message
-
-=back
-
-=item DOING MORE THAN PRINTING A MESSAGE IN THE EVENT OF PERL ERRORS
-
-=over 4
-
-=item SUPPRESSING PERL ERRORS APPEARING IN THE BROWSER WINDOW
-
-=back
-
-=item MAKING WARNINGS APPEAR AS HTML COMMENTS
-
-=item OVERRIDING THE NAME OF THE PROGRAM
-
-=item AUTHORS
-
-=item SEE ALSO
-
-=back
-
-=head2 CGI::Cookie - Interface to HTTP Cookies
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item USING CGI::Cookie
-
-B<1. expiration date>, B<2. domain>, B<3. path>, B<4. secure flag>, B<5.
-httponly flag>
-
-=over 4
-
-=item Creating New Cookies
-
-=item Sending the Cookie to the Browser
-
-=item Recovering Previous Cookies
-
-=item Manipulating Cookies
-
-B<name()>, B<value()>, B<domain()>, B<path()>, B<expires()>
-
-=back
-
-=item AUTHOR INFORMATION
-
-=item BUGS
-
-=item SEE ALSO
-
-=back
-
-=head2 CGI::Fast - CGI Interface for Fast CGI
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item OTHER PIECES OF THE PUZZLE
-
-=item WRITING FASTCGI PERL SCRIPTS
-
-=item INSTALLING FASTCGI SCRIPTS
-
-=item USING FASTCGI SCRIPTS AS CGI SCRIPTS
-
-=item EXTERNAL FASTCGI SERVER INVOCATION
-
-FCGI_SOCKET_PATH, FCGI_LISTEN_QUEUE
-
-=item CAVEATS
-
-=item AUTHOR INFORMATION
-
-=item BUGS
-
-=item SEE ALSO
-
-=back
-
-=head2 CGI::Pretty - module to produce nicely formatted HTML code
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Recommendation for when to use CGI::Pretty
-
-=item Tags that won't be formatted
-
-=item Customizing the Indenting
-
-=back
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 CGI::Push - Simple Interface to Server Push
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item USING CGI::Push
-
--next_page, -last_page, -type, -delay, -cookie, -target, -expires, -nph
-
-=over 4
-
-=item Heterogeneous Pages
-
-=item Changing the Page Delay on the Fly
-
-=back
-
-=item INSTALLING CGI::Push SCRIPTS
-
-=item AUTHOR INFORMATION
-
-=item BUGS
-
-=item SEE ALSO
-
-=back
-
-=head2 CGI::Switch - Backward compatibility module for defunct CGI::Switch
-
-=over 4
-
-=item SYNOPSIS
-
-=item ABSTRACT
-
-=item DESCRIPTION
-
-=item AUTHOR INFORMATION
-
-=item BUGS
-
-=item SEE ALSO
-
-=back
-
-=head2 CGI::Util - Internal utilities used by CGI module
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item AUTHOR INFORMATION
-
-=item SEE ALSO
-
-=back
-
-=head2 CORE - Namespace for Perl's core routines
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item OVERRIDING CORE FUNCTIONS
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 CPAN - query, download and build perl modules from CPAN sites
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item CPAN::shell([$prompt, $command]) Starting Interactive Mode
-
-Searching for authors, bundles, distribution files and modules, C<get>,
-C<make>, C<test>, C<install>, C<clean> modules or distributions, C<readme>,
-C<perldoc>, C<look> module or distribution, C<ls> author, C<ls>
-globbing_expression, C<failed>, Persistence between sessions, The C<force>
-and the C<fforce> pragma, Lockfile, Signals
-
-=item CPAN::Shell
-
-=item autobundle
-
-=item hosts
-
-=item mkmyconfig
-
-=item r [Module|/Regexp/]...
-
-=item recent ***EXPERIMENTAL COMMAND***
-
-=item recompile
-
-=item report Bundle|Distribution|Module
-
-=item smoke ***EXPERIMENTAL COMMAND***
-
-=item upgrade [Module|/Regexp/]...
-
-=item The four C<CPAN::*> Classes: Author, Bundle, Module, Distribution
-
-=item Integrating local directories
-
-=item Redirection
-
-=back
-
-=item CONFIGURATION
-
-completion support, displaying some help: o conf help, displaying current
-values: o conf [KEY], changing of scalar values: o conf KEY VALUE, changing
-of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST, reverting to
-saved: o conf defaults, saving the config: o conf commit
-
-=over 4
-
-=item Config Variables
-
-C<o conf E<lt>scalar optionE<gt>>, C<o conf E<lt>scalar optionE<gt>
-E<lt>valueE<gt>>, C<o conf E<lt>list optionE<gt>>, C<o conf E<lt>list
-optionE<gt> [shift|pop]>, C<o conf E<lt>list optionE<gt>
-[unshift|push|splice] E<lt>listE<gt>>, interactive editing: o conf init
-[MATCH|LIST]
-
-=item CPAN::anycwd($path): Note on config variable getcwd
-
-cwd, getcwd, fastcwd, backtickcwd
-
-=item Note on the format of the urllist parameter
-
-=item The urllist parameter has CD-ROM support
-
-=item Maintaining the urllist parameter
-
-=item The C<requires> and C<build_requires> dependency declarations
-
-=item Configuration for individual distributions (I<Distroprefs>)
-
-=item Filenames
-
-=item Fallback Data::Dumper and Storable
-
-=item Blueprint
-
-=item Language Specs
-
-comment [scalar], cpanconfig [hash], depends [hash] *** EXPERIMENTAL
-FEATURE ***, disabled [boolean], features [array] *** EXPERIMENTAL FEATURE
-***, goto [string], install [hash], make [hash], match [hash], patches
-[array], pl [hash], test [hash]
-
-=item Processing Instructions
-
-args [array], commandline, eexpect [hash], env [hash], expect [array]
-
-=item Schema verification with C<Kwalify>
-
-=item Example Distroprefs Files
-
-=back
-
-=item PROGRAMMER'S INTERFACE
-
-expand($type,@things), expandany(@things), Programming Examples
-
-=over 4
-
-=item Methods in the other Classes
-
-CPAN::Author::as_glimpse(), CPAN::Author::as_string(),
-CPAN::Author::email(), CPAN::Author::fullname(), CPAN::Author::name(),
-CPAN::Bundle::as_glimpse(), CPAN::Bundle::as_string(),
-CPAN::Bundle::clean(), CPAN::Bundle::contains(),
-CPAN::Bundle::force($method,@args), CPAN::Bundle::get(),
-CPAN::Bundle::inst_file(), CPAN::Bundle::inst_version(),
-CPAN::Bundle::uptodate(), CPAN::Bundle::install(), CPAN::Bundle::make(),
-CPAN::Bundle::readme(), CPAN::Bundle::test(),
-CPAN::Distribution::as_glimpse(), CPAN::Distribution::as_string(),
-CPAN::Distribution::author, CPAN::Distribution::pretty_id(),
-CPAN::Distribution::base_id(), CPAN::Distribution::clean(),
-CPAN::Distribution::containsmods(), CPAN::Distribution::cvs_import(),
-CPAN::Distribution::dir(), CPAN::Distribution::force($method,@args),
-CPAN::Distribution::get(), CPAN::Distribution::install(),
-CPAN::Distribution::install_tested(), CPAN::Distribution::isa_perl(),
-CPAN::Distribution::look(), CPAN::Distribution::make(),
-CPAN::Distribution::perldoc(), CPAN::Distribution::prefs(),
-CPAN::Distribution::prereq_pm(), CPAN::Distribution::readme(),
-CPAN::Distribution::reports(), CPAN::Distribution::read_yaml(),
-CPAN::Distribution::test(), CPAN::Distribution::uptodate(),
-CPAN::Index::force_reload(), CPAN::Index::reload(), CPAN::InfoObj::dump(),
-CPAN::Module::as_glimpse(), CPAN::Module::as_string(),
-CPAN::Module::clean(), CPAN::Module::cpan_file(),
-CPAN::Module::cpan_version(), CPAN::Module::cvs_import(),
-CPAN::Module::description(), CPAN::Module::distribution(),
-CPAN::Module::dslip_status(), CPAN::Module::force($method,@args),
-CPAN::Module::get(), CPAN::Module::inst_file(),
-CPAN::Module::available_file(), CPAN::Module::inst_version(),
-CPAN::Module::available_version(), CPAN::Module::install(),
-CPAN::Module::look(), CPAN::Module::make(),
-CPAN::Module::manpage_headline(), CPAN::Module::perldoc(),
-CPAN::Module::readme(), CPAN::Module::reports(), CPAN::Module::test(),
-CPAN::Module::uptodate(), CPAN::Module::userid()
-
-=item Cache Manager
-
-=item Bundles
-
-=back
-
-=item PREREQUISITES
-
-=item UTILITIES
-
-=over 4
-
-=item Finding packages and VERSION
-
-=item Debugging
-
-o debug package.., o debug -package.., o debug all, o debug number
-
-=item Floppy, Zip, Offline Mode
-
-=item Basic Utilities for Programmers
-
-has_inst($module), has_usable($module), instance($module)
-
-=back
-
-=item SECURITY
-
-=over 4
-
-=item Cryptographically signed modules
-
-=back
-
-=item EXPORT
-
-=item ENVIRONMENT
-
-=item POPULATE AN INSTALLATION WITH LOTS OF MODULES
-
-=item WORKING WITH CPAN.pm BEHIND FIREWALLS
-
-=over 4
-
-=item Three basic types of firewalls
-
-http firewall, ftp firewall, One-way visibility, SOCKS, IP Masquerade
-
-=item Configuring lynx or ncftp for going through a firewall
-
-=back
-
-=item FAQ
-
-1), 2), 3), 4), 5), 6), 7), 8), 9), 10), 11), 12), 13), 14), 15), 16), 17),
-18)
-
-=item COMPATIBILITY
-
-=over 4
-
-=item OLD PERL VERSIONS
-
-=item CPANPLUS
-
-=item CPANMINUS
-
-=back
-
-=item SECURITY ADVICE
-
-=item BUGS
-
-=item AUTHOR
-
-=item LICENSE
-
-=item TRANSLATIONS
-
-=item SEE ALSO
-
-=back
-
-=head2 CPAN::API::HOWTO - a recipe book for programming with CPAN.pm
-
-=over 4
-
-=item RECIPES
-
-=over 4
-
-=item What distribution contains a particular module?
-
-=item What modules does a particular distribution contain?
-
-=back
-
-=item SEE ALSO
-
-=item LICENSE
-
-=item AUTHOR
-
-=back
-
-=head2 CPAN::Distroprefs -- read and match distroprefs
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item INTERFACE
-
-a CPAN::Distroprefs::Result object, C<undef>, indicating that no prefs
-files remain to be found
-
-=item RESULTS
-
-=over 4
-
-=item Common
-
-=item Errors
-
-=item Successes
-
-=back
-
-=item PREFS
-
-=item LICENSE
-
-=back
-
-=head2 CPAN::FirstTime - Utility for CPAN::Config file Initialization
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-auto_commit, build_cache, build_dir, build_dir_reuse,
-build_requires_install_policy, cache_metadata, check_sigs, colorize_output,
-colorize_print, colorize_warn, colorize_debug, commandnumber_in_prompt,
-connect_to_internet_ok, ftp_passive, ftpstats_period, ftpstats_size,
-getcwd, halt_on_failure, histfile, histsize, inactivity_timeout,
-index_expire, inhibit_startup_message, keep_source_where,
-load_module_verbosity, makepl_arg, make_arg, make_install_arg,
-make_install_make_command, mbuildpl_arg, mbuild_arg, mbuild_install_arg,
-mbuild_install_build_command, pager, prefer_installer, prefs_dir,
-prerequisites_policy, randomize_urllist, scan_cache, shell,
-show_unparsable_versions, show_upload_date, show_zero_versions,
-tar_verbosity, term_is_latin, term_ornaments, test_report,
-perl5lib_verbosity, prefer_external_tar, trust_test_report_history,
-use_sqlite, version_timeout, yaml_load_code, yaml_module
-
-=over 4
-
-=item LICENSE
-
-=back
-
-=head2 CPAN::Kwalify - Interface between CPAN.pm and Kwalify.pm
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-_validate($schema_name, $data, $file, $doc), yaml($schema_name)
-
-=item AUTHOR
-
-=item LICENSE
-
-=back
-
-=head2 CPAN::Meta - the distribution metadata for a CPAN dist
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item new
-
-=item create
-
-=item load_file
-
-=item load_yaml_string
-
-=item load_json_string
-
-=item save
-
-=item meta_spec_version
-
-=item effective_prereqs
-
-=item should_index_file
-
-=item should_index_package
-
-=item features
-
-=item feature
-
-=item as_struct
-
-=item as_string
-
-=back
-
-=item STRING DATA
-
-=item LIST DATA
-
-=item MAP DATA
-
-=item CUSTOM DATA
-
-=item BUGS
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=over 4
-
-=item Bugs / Feature Requests
-
-=item Source Code
-
-=back
-
-=item AUTHORS
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 CPAN::Meta::Converter - Convert CPAN distribution metadata
-structures
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item new
-
-=item convert
-
-=back
-
-=item BUGS
-
-=item AUTHORS
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 CPAN::Meta::Feature - an optional feature provided by a CPAN
-distribution
-
-=over 4
-
-=item VERSION
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item new
-
-=item identifier
-
-=item description
-
-=item prereqs
-
-=back
-
-=item BUGS
-
-=item AUTHORS
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 CPAN::Meta::History - history of CPAN Meta Spec changes
-
-=over 4
-
-=item VERSION
-
-=item DESCRIPTION
-
-=item HISTORY
-
-=over 4
-
-=item Version 2
-
-=item Version 1.4
-
-=item Version 1.3
-
-=item Version 1.2
-
-=item Version 1.1
-
-=item Version 1.0
-
-=back
-
-=item AUTHORS
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 CPAN::Meta::Prereqs - a set of distribution prerequisites by phase
-and type
-
-=over 4
-
-=item VERSION
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item new
-
-=item requirements_for
-
-=item with_merged_prereqs
-
-=item as_string_hash
-
-=item is_finalized
-
-=item finalize
-
-=item clone
-
-=back
-
-=item BUGS
-
-=item AUTHORS
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 CPAN::Meta::Requirements - a set of version requirements for a CPAN
-dist
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item new
-
-=item add_minimum
-
-=item add_maximum
-
-=item add_exclusion
-
-=item exact_version
-
-=item add_requirements
-
-=item accepts_module
-
-=item clear_requirement
-
-=item required_modules
-
-=item clone
-
-=item is_simple
-
-=item is_finalized
-
-=item finalize
-
-=item as_string_hash
-
-=item add_string_requirement
-
->= 1.3, <= 1.3, ! 1.3, > 1.3, < 1.3, >= 1.3, ! 1.5, <= 2.0
-
-=item from_string_hash
-
-=back
-
-=item AUTHORS
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 CPAN::Meta::Spec - specification for CPAN distribution metadata
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item TERMINOLOGY
-
-distribution, module, package, consumer, producer, must, should, may, etc
-
-=item DATA TYPES
-
-=over 4
-
-=item Boolean
-
-=item String
-
-=item List
-
-=item Map
-
-=item License String
-
-=item URL
-
-=item Version
-
-=item Version Range
-
-=back
-
-=item STRUCTURE
-
-=over 4
-
-=item REQUIRED FIELDS
-
-version, url, stable, testing, unstable
-
-=item OPTIONAL FIELDS
-
-file, directory, package, namespace, description, prereqs, file, version,
-homepage, license, bugtracker, repository
-
-=item DEPRECATED FIELDS
-
-=back
-
-=item VERSION NUMBERS
-
-=over 4
-
-=item Version Formats
-
-Decimal versions, Dotted-integer versions
-
-=item Version Ranges
-
-=back
-
-=item PREREQUISITES
-
-=over 4
-
-=item Prereq Spec
-
-configure, build, test, runtime, develop, requires, recommends, suggests,
-conflicts
-
-=item Merging and Resolving Prerequisites
-
-=back
-
-=item SERIALIZATION
-
-=item NOTES FOR IMPLEMENTORS
-
-=over 4
-
-=item Extracting Version Numbers from Perl Modules
-
-=item Comparing Version Numbers
-
-=back
-
-=item SEE ALSO
-
-=item CONTRIBUTORS
-
-=item AUTHORS
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 CPAN::Meta::Validator - validate CPAN distribution metadata
-structures
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item new
-
-=item is_valid
-
-=item errors
-
-=item Check Methods
-
-=item Validator Methods
-
-=back
-
-=item BUGS
-
-=item AUTHORS
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 CPAN::Meta::YAML - Read and write a subset of YAML for CPAN Meta
-files
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SUPPORT
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=over 4
-
-=item Bugs / Feature Requests
-
-=item Source Code
-
-=back
-
-=item AUTHORS
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-new( LOCAL_FILE_NAME )
-
-continents()
-
-countries( [CONTINENTS] )
-
-mirrors( [COUNTRIES] )
-
-get_mirrors_by_countries( [COUNTRIES] )
-
-get_mirrors_by_continents( [CONTINENTS] )
-
-get_countries_by_continents( [CONTINENTS] )
-
-best_mirrors
-
-get_n_random_mirrors_by_continents( N, [CONTINENTS]
-
-get_mirrors_timings( MIRROR_LIST, SEEN, CALLBACK );
-
-find_best_continents( HASH_REF );
-
-=over 4
-
-=item AUTHOR
-
-=item LICENSE
-
-=back
-
-=head2 CPAN::Nox - Wrapper around CPAN.pm without using any XS module
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item LICENSE
-
-=item SEE ALSO
-
-=back
-
-=head2 CPAN::Version - utility functions to compare CPAN versions
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item LICENSE
-
-=back
-
-=head2 CPANPLUS - API & CLI access to the CPAN mirrors
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item GUIDE TO DOCUMENTATION
-
-=over 4
-
-=item GENERAL USAGE
-
-=item API REFERENCE
-
-=back
-
-=back
-
-=over 4
-
-=item COMMANDLINE TOOLS
-
-=over 4
-
-=item STARTING AN INTERACTIVE SHELL
-
-=item CHOOSE A SHELL
-
-=item BUILDING PACKAGES
-
-=back
-
-=item FUNCTIONS
-
-=over 4
-
-=item $bool = install( Module::Name | /A/AU/AUTHOR/Module-Name-1.tgz )
-
-=item $where = fetch( Module::Name | /A/AU/AUTHOR/Module-Name-1.tgz )
-
-=item $where = get( Module::Name | /A/AU/AUTHOR/Module-Name-1.tgz )
-
-=item shell()
-
-=back
-
-=item FAQ
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=item CONTACT INFORMATION
-
-Bug reporting: I<bug-cpanplus@rt.cpan.org>, Questions & suggestions:
-I<bug-cpanplus@rt.cpan.org>
-
-=back
-
-=head2 CPANPLUS::Backend - programmer's interface to CPANPLUS
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item ENVIRONMENT
-
-=item METHODS
-
-=over 4
-
-=item $cb = CPANPLUS::Backend->new( [CONFIGURE_OBJ] )
-
-Provide a valid C<CPANPLUS::Configure> object, No arguments
-
-=back
-
-=back
-
-=over 4
-
-=item $href = $cb->module_tree( [@modules_names_list] )
-
-=back
-
-=over 4
-
-=item $href = $cb->author_tree( [@author_names_list] )
-
-=back
-
-=over 4
-
-=item $conf = $cb->configure_object;
-
-=back
-
-=over 4
-
-=item $su = $cb->selfupdate_object;
-
-=back
-
-=over 4
-
-=item @mods = $cb->search( type => TYPE, allow => AREF, [data => AREF,
-verbose => BOOL] )
-
-=back
-
-=over 4
-
-=item $backend_rv = $cb->fetch( modules => \@mods )
-
-=item $backend_rv = $cb->extract( modules => \@mods )
-
-=item $backend_rv = $cb->install( modules => \@mods )
-
-=item $backend_rv = $cb->readme( modules => \@mods )
-
-=item $backend_rv = $cb->files( modules => \@mods )
-
-=item $backend_rv = $cb->distributions( modules => \@mods )
-
-=back
-
-=over 4
-
-=item $mod_obj = $cb->parse_module( module =>
-$modname|$distname|$modobj|URI|PATH )
-
-Text::Bastardize, Text-Bastardize, Text/Bastardize.pm,
-Text-Bastardize-1.06, AYRNIEU/Text-Bastardize,
-AYRNIEU/Text-Bastardize-1.06, AYRNIEU/Text-Bastardize-1.06.tar.gz,
-http://example.com/Text-Bastardize-1.06.tar.gz,
-file:///tmp/Text-Bastardize-1.06.tar.gz, /tmp/Text-Bastardize-1.06,
-./Text-Bastardize-1.06
-
-=back
-
-=over 4
-
-=item $bool = $cb->reload_indices( [update_source => BOOL, verbose => BOOL]
-);
-
-=back
-
-=over 4
-
-=item $bool = $cb->flush(CACHE_NAME)
-
-C<methods>, C<hosts>, C<modules>, C<lib>, C<load>, C<all>
-
-=back
-
-=over 4
-
-=item @mods = $cb->installed()
-
-=back
-
-=over 4
-
-=item $bool = $cb->local_mirror([path => '/dir/to/save/to', index_files =>
-BOOL, force => BOOL, verbose => BOOL] )
-
-path, index_files, force, verbose
-
-=back
-
-=over 4
-
-=item $file = $cb->autobundle([path => OUTPUT_PATH, force => BOOL, verbose
-=> BOOL])
-
-=back
-
-=over 4
-
-=item $bool = $cb->save_state
-
-=back
-
-=over 4
-
-=item CUSTOM MODULE SOURCES
-
-=over 4
-
-=item %files = $cb->list_custom_sources
-
-=back
-
-=back
-
-=over 4
-
-=item $local_index = $cb->add_custom_source( uri => URI, [verbose => BOOL]
-);
-
-=back
-
-=over 4
-
-=item $local_index = $cb->remove_custom_source( uri => URI, [verbose =>
-BOOL] );
-
-=back
-
-=over 4
-
-=item $bool = $cb->update_custom_source( [remote => URI] );
-
-=back
-
-=over 4
-
-=item $file = $cb->write_custom_source_index( path =>
-/path/to/package/root, [to => /path/to/index/file, verbose => BOOL] );
-
-=back
-
-=over 4
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 CPANPLUS::Backend::RV - return value objects
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item new( ok => BOOL, args => DATA, rv => DATA, [function => $method_name]
-)
-
-ok, args, rv, function
-
-=back
-
-=back
-
-=over 4
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 CPANPLUS::Config - configuration defaults and heuristics for
-CPANPLUS
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CONFIGURATION
-
-=back
-
-=over 4
-
-=item Section 'conf'
-
-hosts
-
-=back
-
-allow_build_interactivity
-
-allow_unknown_prereqs
-
-base
-
-buildflags
-
-cpantest
-
-cpantest_mx
-
-debug
-
-dist_type
-
-email
-
-enable_custom_sources
-
-extractdir
-
-fetchdir
-
-flush
-
-force
-
-lib
-
-makeflags
-
-makemakerflags
-
-md5
-
-no_update
-
-passive
-
-prefer_bin
-
-prefer_makefile
-
-prereqs
-
-shell
-
-show_startup_tip
-
-signature
-
-skiptest
-
-storable
-
-timeout
-
-verbose
-
-write_install_log
-
-source_engine
-
-cpantest_reporter_args
-
-=over 4
-
-=item Section 'program'
-
-=back
-
-editor
-
-make
-
-pager
-
-shell
-
-sudo
-
-perlwrapper
-
-=over 4
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 CPANPLUS::Configure - configuration for CPANPLUS
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item $Configure = CPANPLUS::Configure->new( load_configs => BOOL )
-
-load_configs
-
-=back
-
-=back
-
-=over 4
-
-=item $bool = $Configure->init( [rescan => BOOL])
-
-=back
-
-=over 4
-
-=item can_save( [$config_location] )
-
-=back
-
-=over 4
-
-=item $file = $conf->save( [$package_name] )
-
-=back
-
-=over 4
-
-=item options( type => TYPE )
-
-=back
-
-=over 4
-
-=item ACCESSORS
-
-=over 4
-
-=item get_SOMETHING( ITEM, [ITEM, ITEM, ... ] );
-
-=item set_SOMETHING( ITEM => VAL, [ITEM => VAL, ITEM => VAL, ... ] );
-
-=item add_SOMETHING( ITEM => VAL, [ITEM => VAL, ITEM => VAL, ... ] );
-
-set|get_conf, set|get_program, _set|_get_build, _set|_get_source,
-_set|_get_mirror, _set|_get_fetch
-
-=back
-
-=back
-
-=over 4
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 CPANPLUS::Dist - base class for plugins
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item ACCESSORS
-
-parent(), status()
-
-=item STATUS ACCESSORS
-
-created(), installed(), uninstalled(), dist()
-
-=back
-
-=over 4
-
-=item $dist = CPANPLUS::Dist::YOUR_DIST_TYPE_HERE->new( module => MODOBJ );
-
-=back
-
-=over 4
-
-=item @dists = CPANPLUS::Dist->dist_types;
-
-=back
-
-=over 4
-
-=item $bool = CPANPLUS::Dist->rescan_dist_types;
-
-=back
-
-=over 4
-
-=item $bool = CPANPLUS::Dist->has_dist_type( $type )
-
-=back
-
-=over 4
-
-=item $bool = $dist->prereq_satisfied( modobj => $modobj, version =>
-$version_spec )
-
-=back
-
-=over 4
-
-=item $configure_requires = $dist->find_configure_requires( [file =>
-/path/to/META.yml] )
-
-=back
-
-=over 4
-
-=item $bool = $dist->_resolve_prereqs( ... )
-
-=back
-
-=head2 CPANPLUS::Dist::Autobundle - distribution class for installation
-snapshots
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 CPANPLUS::Dist::Base - Base class for custom distribution classes
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item FLOW
-
-=item METHODS
-
-=back
-
-=over 4
-
-=item @subs = $Class->methods
-
-=back
-
-=over 4
-
-=item $bool = $Class->format_available
-
-=back
-
-=over 4
-
-=item $bool = $dist->init
-
-=back
-
-=over 4
-
-=item $bool = $dist->prepare
-
-=back
-
-=over 4
-
-=item $bool = $dist->create
-
-=back
-
-=over 4
-
-=item $bool = $dist->install
-
-=back
-
-=over 4
-
-=item $bool = $dist->uninstall
-
-=back
-
-=head2 CPANPLUS::Dist::Build - CPANPLUS plugin to install packages that use
-Build.PL
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item ACCESSORS
-
-C<parent()>, C<status()>
-
-=item STATUS ACCESSORS
-
-C<build_pl ()>, C<build ()>, C<test ()>, C<prepared ()>, C<distdir ()>,
-C<created ()>, C<installed ()>, uninstalled (), C<_create_args ()>,
-C<_install_args ()>
-
-=back
-
-=over 4
-
-=item METHODS
-
-=over 4
-
-=item $bool = CPANPLUS::Dist::Build->format_available();
-
-=back
-
-=back
-
-=over 4
-
-=item $bool = $dist->init();
-
-=back
-
-=over 4
-
-=item $bool = $dist->prepare([perl => '/path/to/perl', buildflags =>
-'EXTRA=FLAGS', force => BOOL, verbose => BOOL])
-
-=back
-
-=over 4
-
-=item $dist->create([perl => '/path/to/perl', buildflags => 'EXTRA=FLAGS',
-prereq_target => TARGET, force => BOOL, verbose => BOOL, skiptest => BOOL])
-
-=back
-
-=over 4
-
-=item $dist->install([verbose => BOOL, perl => /path/to/perl])
-
-=back
-
-=over 4
-
-=item AUTHOR
-
-=item LICENSE
-
-=back
-
-=head2 CPANPLUS::Dist::Build::Constants - Constants for
-CPANPLUS::Dist::Build
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=item LICENSE
-
-=back
-
-=head2 CPANPLUS::Dist::MM - distribution class for MakeMaker related
-modules
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item ACCESSORS
-
-parent(), status()
-
-=item STATUS ACCESSORS
-
-makefile (), make (), test (), prepared (), distdir (), created (),
-installed (), uninstalled (), _create_args (), _install_args ()
-
-=back
-
-=over 4
-
-=item METHODS
-
-=over 4
-
-=item $bool = $dist->format_available();
-
-=back
-
-=back
-
-=over 4
-
-=item $bool = $dist->init();
-
-=back
-
-=over 4
-
-=item $bool = $dist->prepare([perl => '/path/to/perl', makemakerflags =>
-'EXTRA=FLAGS', force => BOOL, verbose => BOOL])
-
-=back
-
-=over 4
-
-=item $href = $dist->_find_prereqs( file => '/path/to/Makefile', [verbose
-=> BOOL])
-
-=back
-
-=over 4
-
-=item $bool = $dist->create([perl => '/path/to/perl', make =>
-'/path/to/make', makeflags => 'EXTRA=FLAGS', prereq_target => TARGET,
-skiptest => BOOL, force => BOOL, verbose => BOOL])
-
-=back
-
-=over 4
-
-=item $bool = $dist->install([make => '/path/to/make', makemakerflags =>
-'EXTRA=FLAGS', force => BOOL, verbose => BOOL])
-
-=back
-
-=over 4
-
-=item $bool = $dist->write_makefile_pl([force => BOOL, verbose => BOOL])
-
-=back
-
-=head2 CPANPLUS::Dist::Sample -- Sample code to create your own Dist::*
-plugin
-
-=over 4
-
-=item Description.
-
-=back
-
-=head2 CPANPLUS::Error - error handling for CPANPLUS
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item FUNCTIONS
-
-=over 4
-
-=item cp_msg("message string" [,VERBOSE])
-
-=item msg()
-
-=item cp_error("error string" [,VERBOSE])
-
-=item error()
-
-=back
-
-=item CLASS METHODS
-
-=over 4
-
-=item CPANPLUS::Error->stack()
-
-=item CPANPLUS::Error->stack_as_string([TRACE])
-
-=item CPANPLUS::Error->flush()
-
-=back
-
-=back
-
-=over 4
-
-=item GLOBAL VARIABLES
-
-$ERROR_FH, $MSG_FH
-
-=back
-
-=head2 CPANPLUS::FAQ - CPANPLUS Frequently Asked Questions
-
-=head2 CPANPLUS::FAQ
-
-=over 4
-
-=item DESCRIPTION
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 CPANPLUS::Hacking - developing CPANPLUS
-
-=over 4
-
-=item DESCRIPTION
-
-=item OBTAINING CPANPLUS
-
-=item INSTALLING CPANPLUS
-
-=item CONFIGURING CPANPLUS
-
-=item RUNNING CPANPLUS FROM DEVELOPMENT ENVIRONMENT
-
-=item RUNNING CPANPLUS TESTS
-
-=item FINDING BUGS
-
-Problem description, Program demonstrating the bug, [OPTIONAL] A patch to
-the test suite to test for the bug, [OPTIONAL] A patch to the code + tests
-+ documentation
-
-=item SUPPLYING PATCHES
-
-In C<diff -u> or C<diff -c> format, From the root of the snapshot,
-Including patches for code + tests + docs, Sent per mail to
-bug-cpanplus@rt.cpan.org, With subject containing C<[PATCH]> + description
-of the patch
-
-=back
-
-=head2 CPANPLUS::Internals - CPANPLUS internals
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item ACCESSORS
-
-_conf, _id
-
-=back
-
-=over 4
-
-=item METHODS
-
-=over 4
-
-=item $internals = CPANPLUS::Internals->_init( _conf => CONFIG_OBJ )
-
-=back
-
-=back
-
-=over 4
-
-=item $bool = $internals->_flush( list => \@caches )
-
-=back
-
-=over 4
-
-=item $bool = $internals->_register_callback( name => CALLBACK_NAME, code
-=> CODEREF );
-
-install_prerequisite, send_test_report, munge_test_report,
-edit_test_report, proceed_on_test_failure, munge_dist_metafile
-
-=back
-
-=over 4
-
-=item $bool = $internals->_add_to_includepath( directories => \@dirs )
-
-=back
-
-=over 4
-
-=item $id = CPANPLUS::Internals->_last_id
-
-=item $id = CPANPLUS::Internals->_store_id( $internals )
-
-=item $obj = CPANPLUS::Internals->_retrieve_id( $ID )
-
-=item CPANPLUS::Internals->_remove_id( $ID )
-
-=item @objs = CPANPLUS::Internals->_return_all_objects
-
-=back
-
-=head2 CPANPLUS::Internals::Extract - internals for archive extraction
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item $dir = _extract( module => $modobj, [perl => '/path/to/perl',
-extractdir => '/path/to/extract/to', prefer_bin => BOOL, verbose => BOOL,
-force => BOOL] )
-
-module, extractdir, prefer_bin, perl, verbose, force
-
-=back
-
-=back
-
-=head2 CPANPLUS::Internals::Fetch - internals for fetching files
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=back
-
-=over 4
-
-=item $path = _fetch( module => $modobj, [fetchdir => '/path/to/save/to',
-fetch_from => 'scheme://path/to/fetch/from', verbose => BOOL, force =>
-BOOL, prefer_bin => BOOL, ttl => $seconds] )
-
-=back
-
-=over 4
-
-=item _add_fail_host( host => $host_hashref )
-
-=item _host_ok( host => $host_hashref )
-
-=back
-
-=head2 CPANPLUS::Internals::Report - internals for sending test reports
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item $bool = $cb->_have_query_report_modules
-
-=item $bool = $cb->_have_send_report_modules
-
-=back
-
-=back
-
-=over 4
-
-=item @list = $cb->_query_report( module => $modobj, [all_versions => BOOL,
-verbose => BOOL] )
-
-=back
-
-=over 4
-
-=item $bool = $cb->_send_report( module => $modobj, buffer => $make_output,
-failed => BOOL, [save => BOOL, address => $email_to, verbose => BOOL, force
-=> BOOL]);
-
-module, buffer, failed, save, address, verbose, force
-
-=back
-
-=head2 CPANPLUS::Internals::Search - internals for searching for modules
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item _search_module_tree( type => TYPE, allow => \@regexes, [data =>
-\@previous_results ] )
-
-type, allow, data
-
-=back
-
-=back
-
-=over 4
-
-=item _search_author_tree( type => TYPE, allow => \@regexex, [data =>
-\@previous_results ] )
-
-type, allow, data
-
-=back
-
-=over 4
-
-=item _all_installed()
-
-=back
-
-=head2 CPANPLUS::Internals::Source - internals for updating source files
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=back
-
-=over 4
-
-=item $cb->_build_trees( uptodate => BOOL, [use_stored => BOOL, path =>
-$path, verbose => BOOL] )
-
-uptodate, path, verbose, use_stored
-
-=back
-
-=over 4
-
-=item $cb->_check_trees( [update_source => BOOL, path => PATH, verbose =>
-BOOL] )
-
-update_source, path, verbose
-
-=back
-
-=over 4
-
-=item $cb->__check_uptodate( file => $file, name => $name, [update_source
-=> BOOL, verbose => BOOL] )
-
-file, name, update_source, verbose
-
-=back
-
-=over 4
-
-=item $cb->_update_source( name => $name, [path => $path, verbose => BOOL]
-)
-
-name, path, verbose
-
-=back
-
-=over 4
-
-=item $cb->__create_author_tree([path => $path, uptodate => BOOL, verbose
-=> BOOL])
-
-uptodate, path, verbose
-
-=back
-
-=over 4
-
-=item $cb->_create_mod_tree([path => $path, uptodate => BOOL, verbose =>
-BOOL])
-
-uptodate, path, verbose
-
-=back
-
-=over 4
-
-=item $cb->__create_dslip_tree([path => $path, uptodate => BOOL, verbose =>
-BOOL])
-
-uptodate, path, verbose
-
-=back
-
-=over 4
-
-=item $cb->_dslip_defs ()
-
-=back
-
-=over 4
-
-=item $file = $cb->_add_custom_module_source( uri => URI, [verbose => BOOL]
-);
-
-=back
-
-=over 4
-
-=item $index = $cb->__custom_module_source_index_file( uri => $uri );
-
-=back
-
-=over 4
-
-=item $file = $cb->_remove_custom_module_source( uri => URI, [verbose =>
-BOOL] );
-
-=back
-
-=over 4
-
-=item %files = $cb->__list_custom_module_sources
-
-=back
-
-=over 4
-
-=item $bool = $cb->__update_custom_module_sources( [verbose => BOOL] );
-
-=back
-
-=over 4
-
-=item $ok = $cb->__update_custom_module_source
-
-=back
-
-=over 4
-
-=item $bool = $cb->__write_custom_module_index( path => /path/to/packages,
-[to => /path/to/index/file, verbose => BOOL] )
-
-=back
-
-=over 4
-
-=item $bool = $cb->__create_custom_module_entries( [verbose => BOOL] )
-
-=back
-
-=head2 CPANPLUS::Internals::Source::Memory - In memory implementation
-
-=over 4
-
-=item $cb->__memory_retrieve_source(name => $name, [path => $path, uptodate
-=> BOOL, verbose => BOOL])
-
-name, uptodate, path, verbose
-
-=back
-
-=over 4
-
-=item $cb->__memory_save_source([verbose => BOOL, path => $path])
-
-path, verbose
-
-=back
-
-=head2 CPANPLUS::Internals::Source::SQLite - SQLite implementation
-
-=head2 CPANPLUS::Internals::Utils - convenience functions for CPANPLUS
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item $cb->_mkdir( dir => '/some/dir' )
-
-=back
-
-=back
-
-=over 4
-
-=item $cb->_chdir( dir => '/some/dir' )
-
-=back
-
-=over 4
-
-=item $cb->_rmdir( dir => '/some/dir' );
-
-=back
-
-=over 4
-
-=item $cb->_perl_version ( perl => 'some/perl/binary' );
-
-=back
-
-=over 4
-
-=item $cb->_version_to_number( version => $version );
-
-=back
-
-=over 4
-
-=item $cb->_whoami
-
-=back
-
-=over 4
-
-=item _get_file_contents( file => $file );
-
-=back
-
-=over 4
-
-=item $cb->_move( from => $file|$dir, to => $target );
-
-=back
-
-=over 4
-
-=item $cb->_copy( from => $file|$dir, to => $target );
-
-=back
-
-=over 4
-
-=item $cb->_mode_plus_w( file => '/path/to/file' );
-
-=back
-
-=over 4
-
-=item $uri = $cb->_host_to_uri( scheme => SCHEME, host => HOST, path =>
-PATH );
-
-=back
-
-=over 4
-
-=item $cb->_vcmp( VERSION, VERSION );
-
-=back
-
-=over 4
-
-=item $cb->_home_dir
-
-=back
-
-=over 4
-
-=item $path = $cb->_safe_path( path => $path );
-
-=back
-
-=over 4
-
-=item ($pkg, $version, $ext) = $cb->_split_package_string( package =>
-PACKAGE_STRING );
-
-=back
-
-=head2 CPANPLUS::Module - CPAN module objects for CPANPLUS
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item CLASS METHODS
-
-=over 4
-
-=item accessors ()
-
-=back
-
-=back
-
-=over 4
-
-=item ACCESSORS
-
-name, module, version, path, comment, package, description, dslip
-
-=back
-
-status, author, parent
-
-=over 4
-
-=item STATUS ACCESSORS
-
-installer_type, dist_cpan, dist, prereqs | requires, configure_requires,
-signature, extract, fetch, readme, uninstall, created, installed,
-checksums, checksum_ok, checksum_value
-
-=item METHODS
-
-=over 4
-
-=item $self = CPANPLUS::Module->new( OPTIONS )
-
-=back
-
-=back
-
-=over 4
-
-=item $mod->package_name( [$package_string] )
-
-=item $mod->package_version( [$package_string] )
-
-=item $mod->package_extension( [$package_string] )
-
-=item $mod->package_is_perl_core
-
-=item $mod->module_is_supplied_with_perl_core( [version => $]] )
-
-=item $mod->is_bundle
-
-=item $mod->is_autobundle;
-
-=item $mod->is_third_party
-
-=item $mod->third_party_information
-
-=back
-
-=over 4
-
-=item $clone = $self->clone
-
-=back
-
-=over 4
-
-=item $where = $self->fetch
-
-=back
-
-=over 4
-
-=item $path = $self->extract
-
-=back
-
-=over 4
-
-=item $type = $self->get_installer_type([prefer_makefile => BOOL])
-
-=back
-
-=over 4
-
-=item $dist = $self->dist([target => 'prepare|create', format =>
-DISTRIBUTION_TYPE, args => {key => val}]);
-
-=back
-
-=over 4
-
-=item $bool = $mod->prepare( )
-
-=back
-
-=over 4
-
-=item $bool = $mod->create( )
-
-=back
-
-=over 4
-
-=item $bool = $mod->test( )
-
-=back
-
-=over 4
-
-=item $bool = $self->install([ target => 'init|prepare|create|install',
-format => FORMAT_TYPE, extractdir => DIRECTORY, fetchdir => DIRECTORY,
-prefer_bin => BOOL, force => BOOL, verbose => BOOL, ..... ]);
-
-=back
-
-=over 4
-
-=item $text = $self->readme
-
-=back
-
-=over 4
-
-=item $version = $self->installed_version()
-
-=item $where = $self->installed_file()
-
-=item $dir = $self->installed_dir()
-
-=item $bool = $self->is_uptodate([version => VERSION_NUMBER])
-
-=back
-
-=over 4
-
-=item $href = $self->details()
-
-=back
-
-=over 4
-
-=item @list = $self->contains()
-
-=back
-
-=over 4
-
-=item @list_of_hrefs = $self->fetch_report()
-
-=back
-
-=over 4
-
-=item $bool = $self->uninstall([type => [all|man|prog])
-
-=back
-
-=over 4
-
-=item @modobj = $self->distributions()
-
-=back
-
-=over 4
-
-=item @list = $self->files ()
-
-=item @list = $self->directory_tree ()
-
-=item @list = $self->packlist ()
-
-=item @list = $self->validate ()
-
-=back
-
-=over 4
-
-=item $bool = $self->add_to_includepath;
-
-=back
-
-=over 4
-
-=item $path = $self->best_path_to_module_build();
-
-=back
-
-=over 4
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 CPANPLUS::Module::Author - CPAN author object for CPANPLUS
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item ACCESSORS
-
-author, cpanid, email, parent
-
-=back
-
-=over 4
-
-=item METHODS
-
-=over 4
-
-=item $auth = CPANPLUS::Module::Author->new( author => AUTHOR_NAME, cpanid
-=> CPAN_ID, _id => INTERNALS_ID [, email => AUTHOR_EMAIL] )
-
-=back
-
-=back
-
-=over 4
-
-=item @mod_objs = $auth->modules()
-
-=back
-
-=over 4
-
-=item @dists = $auth->distributions()
-
-=back
-
-=over 4
-
-=item CLASS METHODS
-
-=over 4
-
-=item accessors ()
-
-=back
-
-=back
-
-=head2 CPANPLUS::Module::Author::Fake - dummy author object for CPANPLUS
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item new( _id => DIGIT )
-
-=back
-
-=back
-
-=head2 CPANPLUS::Module::Checksums - checking the checksum of a
-distribution
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item $mod->checksums
-
-=back
-
-=back
-
-=head2 CPANPLUS::Module::Fake - fake module object for internal use
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item new( module => $mod, path => $path, package => $pkg, [_id => DIGIT] )
-
-=back
-
-=back
-
-=head2 CPANPLUS::Selfupdate - self-updating for CPANPLUS
-
-=over 4
-
-=item SYNOPSIS
-
-=back
-
-=over 4
-
-=item METHODS
-
-=over 4
-
-=item $self = CPANPLUS::Selfupdate->new( $backend_object );
-
-=back
-
-=back
-
-=over 4
-
-=item @cat = $self->list_categories
-
-=back
-
-=over 4
-
-=item %list = $self->list_modules_to_update( update =>
-"core|dependencies|enabled_features|features|all", [latest => BOOL] )
-
-=back
-
-=over 4
-
-=item $bool = $self->selfupdate( update =>
-"core|dependencies|enabled_features|features|all", [latest => BOOL, force
-=> BOOL] )
-
-=back
-
-=over 4
-
-=item @features = $self->list_features
-
-=back
-
-=over 4
-
-=item @features = $self->list_enabled_features
-
-=back
-
-=over 4
-
-=item @mods = $self->modules_for_feature( FEATURE [,AS_HASH] )
-
-=back
-
-=over 4
-
-=item @mods = $self->list_core_dependencies( [AS_HASH] )
-
-=back
-
-=over 4
-
-=item @mods = $self->list_core_modules( [AS_HASH] )
-
-=back
-
-=over 4
-
-=item CPANPLUS::Selfupdate::Module
-
-=back
-
-=over 4
-
-=item $version = $mod->version_required
-
-=back
-
-=over 4
-
-=item $bool = $mod->is_installed_version_sufficient
-
-=back
-
-=over 4
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 CPANPLUS::Shell - base class for CPANPLUS shells
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 CPANPLUS::Shell::Classic - CPAN.pm emulation for CPANPLUS
-
-=over 4
-
-=item DESCRIPTION
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=over 4
-
-=item SEE ALSO
-
-=back
-
-=head2 CPANPLUS::Shell::Default - the default CPANPLUS shell
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 CPANPLUS::Shell::Default::Plugins::CustomSource - add custom sources
-to CPANPLUS
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 CPANPLUS::Shell::Default::Plugins::HOWTO -- documentation on how to
-write your own plugins
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item HOWTO
-
-=over 4
-
-=item Registering Plugin Modules
-
-=item Registering Plugin Commands
-
-=item Registering Plugin Help
-
-=item Arguments to Plugin Commands
-
-Classname -- The name of your plugin class, Shell -- The
-CPANPLUS::Shell::Default object, Backend -- The CPANPLUS::Backend object,
-Command -- The command issued by the user, Input -- The input string
-from the user, Options -- A hashref of options provided by the user
-
-=back
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 CPANPLUS::Shell::Default::Plugins::Remote - connect to a remote
-CPANPLUS
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 CPANPLUS::Shell::Default::Plugins::Source - read in CPANPLUS
-commands
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 Carp - alternative warn and die for modules
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Forcing a Stack Trace
-
-=back
-
-=item GLOBAL VARIABLES
-
-=over 4
-
-=item $Carp::MaxEvalLen
-
-=item $Carp::MaxArgLen
-
-=item $Carp::MaxArgNums
-
-=item $Carp::Verbose
-
-=item @CARP_NOT
-
-=item %Carp::Internal
-
-=item %Carp::CarpInternal
-
-=item $Carp::CarpLevel
-
-=back
-
-=item BUGS
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item LICENSE
-
-=back
-
-=head2 Class::Struct - declare struct-like datatypes as Perl classes
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item The C<struct()> function
-
-=item Class Creation at Compile Time
-
-=item Element Types and Accessor Methods
-
-Scalar (C<'$'> or C<'*$'>), Array (C<'@'> or C<'*@'>), Hash (C<'%'> or
-C<'*%'>), Class (C<'Class_Name'> or C<'*Class_Name'>)
-
-=item Initializing with C<new>
-
-=back
-
-=item EXAMPLES
-
-Example 1, Example 2, Example 3
-
-=item Author and Modification History
-
-=back
-
-=head2 Compress::Raw::Bzip2 - Low-Level Interface to bzip2 compression
-library
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Compression
-
-=over 4
-
-=item ($z, $status) = new Compress::Raw::Bzip2 $appendOutput,
-$blockSize100k, $workfactor;
-
-B<$appendOutput>, B<$blockSize100k>, B<$workfactor>
-
-=item $status = $bz->bzdeflate($input, $output);
-
-=item $status = $bz->bzflush($output);
-
-=item $status = $bz->bzclose($output);
-
-=item Example
-
-=back
-
-=item Uncompression
-
-=over 4
-
-=item ($z, $status) = new Compress::Raw::Bunzip2 $appendOutput,
-$consumeInput, $small, $verbosity, $limitOutput;
-
-B<$appendOutput>, B<$consumeInput>, B<$small>, B<$limitOutput>,
-B<$verbosity>
-
-=item $status = $z->bzinflate($input, $output);
-
-=back
-
-=item Misc
-
-=over 4
-
-=item my $version = Compress::Raw::Bzip2::bzlibversion();
-
-=back
-
-=item Constants
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item MODIFICATION HISTORY
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 Compress::Raw::Zlib - Low-Level Interface to zlib compression
-library
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Compress::Raw::Zlib::Deflate
-
-=over 4
-
-=item B<($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) >
-
-B<-Level>, B<-Method>, B<-WindowBits>, B<-MemLevel>, B<-Strategy>,
-B<-Dictionary>, B<-Bufsize>, B<-AppendOutput>, B<-CRC32>, B<-ADLER32>
-
-=item B<$status = $d-E<gt>deflate($input, $output)>
-
-=item B<$status = $d-E<gt>flush($output [, $flush_type]) >
-
-=item B<$status = $d-E<gt>deflateReset() >
-
-=item B<$status = $d-E<gt>deflateParams([OPT])>
-
-B<-Level>, B<-Strategy>, B<-BufSize>
-
-=item B<$status = $d-E<gt>deflateTune($good_length, $max_lazy,
-$nice_length, $max_chain)>
-
-=item B<$d-E<gt>dict_adler()>
-
-=item B<$d-E<gt>crc32()>
-
-=item B<$d-E<gt>adler32()>
-
-=item B<$d-E<gt>msg()>
-
-=item B<$d-E<gt>total_in()>
-
-=item B<$d-E<gt>total_out()>
-
-=item B<$d-E<gt>get_Strategy()>
-
-=item B<$d-E<gt>get_Level()>
-
-=item B<$d-E<gt>get_BufSize()>
-
-=item Example
-
-=back
-
-=item Compress::Raw::Zlib::Inflate
-
-=over 4
-
-=item B< ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) >
-
-B<-WindowBits>, B<-Bufsize>, B<-Dictionary>, B<-AppendOutput>, B<-CRC32>,
-B<-ADLER32>, B<-ConsumeInput>, B<-LimitOutput>
-
-=item B< $status = $i-E<gt>inflate($input, $output [,$eof]) >
-
-=item B<$status = $i-E<gt>inflateSync($input)>
-
-=item B<$status = $i-E<gt>inflateReset() >
-
-=item B<$i-E<gt>dict_adler()>
-
-=item B<$i-E<gt>crc32()>
-
-=item B<$i-E<gt>adler32()>
-
-=item B<$i-E<gt>msg()>
-
-=item B<$i-E<gt>total_in()>
-
-=item B<$i-E<gt>total_out()>
-
-=item B<$d-E<gt>get_BufSize()>
-
-=item Examples
-
-=back
-
-=item CHECKSUM FUNCTIONS
-
-=item Misc
-
-=over 4
-
-=item my $version = Compress::Raw::Zlib::zlib_version();
-
-=item my $flags = Compress::Raw::Zlib::zlibCompileFlags();
-
-=back
-
-=item The LimitOutput option.
-
-=item ACCESSING ZIP FILES
-
-=item FAQ
-
-=over 4
-
-=item Compatibility with Unix compress/uncompress.
-
-=item Accessing .tar.Z files
-
-=item Zlib Library Version Support
-
-=back
-
-=item CONSTANTS
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item MODIFICATION HISTORY
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 Compress::Zlib - Interface to zlib compression library
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Notes for users of Compress::Zlib version 1
-
-=back
-
-=item GZIP INTERFACE
-
-B<$gz = gzopen($filename, $mode)>, B<$gz = gzopen($filehandle, $mode)>,
-B<$bytesread = $gz-E<gt>gzread($buffer [, $size]) ;>, B<$bytesread =
-$gz-E<gt>gzreadline($line) ;>, B<$byteswritten = $gz-E<gt>gzwrite($buffer)
-;>, B<$status = $gz-E<gt>gzflush($flush_type) ;>, B<$offset =
-$gz-E<gt>gztell() ;>, B<$status = $gz-E<gt>gzseek($offset, $whence) ;>,
-B<$gz-E<gt>gzclose>, B<$gz-E<gt>gzsetparams($level, $strategy>, B<$level>,
-B<$strategy>, B<$gz-E<gt>gzerror>, B<$gzerrno>
-
-=over 4
-
-=item Examples
-
-=item Compress::Zlib::memGzip
-
-=item Compress::Zlib::memGunzip
-
-=back
-
-=item COMPRESS/UNCOMPRESS
-
-B<$dest = compress($source [, $level] ) ;>, B<$dest = uncompress($source)
-;>
-
-=item Deflate Interface
-
-=over 4
-
-=item B<($d, $status) = deflateInit( [OPT] )>
-
-B<-Level>, B<-Method>, B<-WindowBits>, B<-MemLevel>, B<-Strategy>,
-B<-Dictionary>, B<-Bufsize>
-
-=item B<($out, $status) = $d-E<gt>deflate($buffer)>
-
-=item B<($out, $status) = $d-E<gt>flush()>
-=head2 B<($out, $status) = $d-E<gt>flush($flush_type)>
-
-=item B<$status = $d-E<gt>deflateParams([OPT])>
-
-B<-Level>, B<-Strategy>
-
-=item B<$d-E<gt>dict_adler()>
-
-=item B<$d-E<gt>msg()>
-
-=item B<$d-E<gt>total_in()>
-
-=item B<$d-E<gt>total_out()>
-
-=item Example
-
-=back
-
-=item Inflate Interface
-
-=over 4
-
-=item B<($i, $status) = inflateInit()>
-
-B<-WindowBits>, B<-Bufsize>, B<-Dictionary>
-
-=item B<($out, $status) = $i-E<gt>inflate($buffer)>
-
-=item B<$status = $i-E<gt>inflateSync($buffer)>
-
-=item B<$i-E<gt>dict_adler()>
-
-=item B<$i-E<gt>msg()>
-
-=item B<$i-E<gt>total_in()>
-
-=item B<$i-E<gt>total_out()>
-
-=item Example
-
-=back
-
-=item CHECKSUM FUNCTIONS
-
-=item Misc
-
-=over 4
-
-=item my $version = Compress::Zlib::zlib_version();
-
-=back
-
-=item CONSTANTS
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item MODIFICATION HISTORY
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 Config - access Perl configuration information
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-myconfig(), config_sh(), config_re($regex), config_vars(@names),
-bincompat_options(), non_bincompat_options(), compile_date(),
-local_patches(), header_files()
-
-=item EXAMPLE
-
-=item WARNING
-
-=item GLOSSARY
-
-=back
-
-=over 4
-
-=item _
-
-=back
-
-C<_a>, C<_exe>, C<_o>
-
-=over 4
-
-=item a
-
-=back
-
-C<afs>, C<afsroot>, C<alignbytes>, C<ansi2knr>, C<aphostname>,
-C<api_revision>, C<api_subversion>, C<api_version>, C<api_versionstring>,
-C<ar>, C<archlib>, C<archlibexp>, C<archname>, C<archname64>, C<archobjs>,
-C<asctime_r_proto>, C<awk>
-
-=over 4
-
-=item b
-
-=back
-
-C<baserev>, C<bash>, C<bin>, C<bin_ELF>, C<binexp>, C<bison>, C<byacc>,
-C<byteorder>
-
-=over 4
-
-=item c
-
-=back
-
-C<c>, C<castflags>, C<cat>, C<cc>, C<cccdlflags>, C<ccdlflags>, C<ccflags>,
-C<ccflags_uselargefiles>, C<ccname>, C<ccsymbols>, C<ccversion>, C<cf_by>,
-C<cf_email>, C<cf_time>, C<charbits>, C<charsize>, C<chgrp>, C<chmod>,
-C<chown>, C<clocktype>, C<comm>, C<compress>, C<config_arg0>,
-C<config_argc>, C<config_args>, C<contains>, C<cp>, C<cpio>, C<cpp>,
-C<cpp_stuff>, C<cppccsymbols>, C<cppflags>, C<cpplast>, C<cppminus>,
-C<cpprun>, C<cppstdin>, C<cppsymbols>, C<crypt_r_proto>, C<cryptlib>,
-C<csh>, C<ctermid_r_proto>, C<ctime_r_proto>
-
-=over 4
-
-=item d
-
-=back
-
-C<d__fwalk>, C<d_access>, C<d_accessx>, C<d_aintl>, C<d_alarm>,
-C<d_archlib>, C<d_asctime64>, C<d_asctime_r>, C<d_atolf>, C<d_atoll>,
-C<d_attribute_deprecated>, C<d_attribute_format>, C<d_attribute_malloc>,
-C<d_attribute_nonnull>, C<d_attribute_noreturn>, C<d_attribute_pure>,
-C<d_attribute_unused>, C<d_attribute_warn_unused_result>, C<d_bcmp>,
-C<d_bcopy>, C<d_bsd>, C<d_bsdgetpgrp>, C<d_bsdsetpgrp>,
-C<d_builtin_choose_expr>, C<d_builtin_expect>, C<d_bzero>,
-C<d_c99_variadic_macros>, C<d_casti32>, C<d_castneg>, C<d_charvspr>,
-C<d_chown>, C<d_chroot>, C<d_chsize>, C<d_class>, C<d_clearenv>,
-C<d_closedir>, C<d_cmsghdr_s>, C<d_const>, C<d_copysignl>, C<d_cplusplus>,
-C<d_crypt>, C<d_crypt_r>, C<d_csh>, C<d_ctermid>, C<d_ctermid_r>,
-C<d_ctime64>, C<d_ctime_r>, C<d_cuserid>, C<d_dbl_dig>, C<d_dbminitproto>,
-C<d_difftime>, C<d_difftime64>, C<d_dir_dd_fd>, C<d_dirfd>, C<d_dirnamlen>,
-C<d_dlerror>, C<d_dlopen>, C<d_dlsymun>, C<d_dosuid>, C<d_drand48_r>,
-C<d_drand48proto>, C<d_dup2>, C<d_eaccess>, C<d_endgrent>, C<d_endgrent_r>,
-C<d_endhent>, C<d_endhostent_r>, C<d_endnent>, C<d_endnetent_r>,
-C<d_endpent>, C<d_endprotoent_r>, C<d_endpwent>, C<d_endpwent_r>,
-C<d_endsent>, C<d_endservent_r>, C<d_eofnblk>, C<d_eunice>, C<d_faststdio>,
-C<d_fchdir>, C<d_fchmod>, C<d_fchown>, C<d_fcntl>, C<d_fcntl_can_lock>,
-C<d_fd_macros>, C<d_fd_set>, C<d_fds_bits>, C<d_fgetpos>, C<d_finite>,
-C<d_finitel>, C<d_flexfnam>, C<d_flock>, C<d_flockproto>, C<d_fork>,
-C<d_fp_class>, C<d_fpathconf>, C<d_fpclass>, C<d_fpclassify>,
-C<d_fpclassl>, C<d_fpos64_t>, C<d_frexpl>, C<d_fs_data_s>, C<d_fseeko>,
-C<d_fsetpos>, C<d_fstatfs>, C<d_fstatvfs>, C<d_fsync>, C<d_ftello>,
-C<d_ftime>, C<d_futimes>, C<d_Gconvert>, C<d_gdbm_ndbm_h_uses_prototypes>,
-C<d_gdbmndbm_h_uses_prototypes>, C<d_getaddrinfo>, C<d_getcwd>,
-C<d_getespwnam>, C<d_getfsstat>, C<d_getgrent>, C<d_getgrent_r>,
-C<d_getgrgid_r>, C<d_getgrnam_r>, C<d_getgrps>, C<d_gethbyaddr>,
-C<d_gethbyname>, C<d_gethent>, C<d_gethname>, C<d_gethostbyaddr_r>,
-C<d_gethostbyname_r>, C<d_gethostent_r>, C<d_gethostprotos>,
-C<d_getitimer>, C<d_getlogin>, C<d_getlogin_r>, C<d_getmnt>,
-C<d_getmntent>, C<d_getnameinfo>, C<d_getnbyaddr>, C<d_getnbyname>,
-C<d_getnent>, C<d_getnetbyaddr_r>, C<d_getnetbyname_r>, C<d_getnetent_r>,
-C<d_getnetprotos>, C<d_getpagsz>, C<d_getpbyname>, C<d_getpbynumber>,
-C<d_getpent>, C<d_getpgid>, C<d_getpgrp>, C<d_getpgrp2>, C<d_getppid>,
-C<d_getprior>, C<d_getprotobyname_r>, C<d_getprotobynumber_r>,
-C<d_getprotoent_r>, C<d_getprotoprotos>, C<d_getprpwnam>, C<d_getpwent>,
-C<d_getpwent_r>, C<d_getpwnam_r>, C<d_getpwuid_r>, C<d_getsbyname>,
-C<d_getsbyport>, C<d_getsent>, C<d_getservbyname_r>, C<d_getservbyport_r>,
-C<d_getservent_r>, C<d_getservprotos>, C<d_getspnam>, C<d_getspnam_r>,
-C<d_gettimeod>, C<d_gmtime64>, C<d_gmtime_r>, C<d_gnulibc>, C<d_grpasswd>,
-C<d_hasmntopt>, C<d_htonl>, C<d_ilogbl>, C<d_inc_version_list>, C<d_index>,
-C<d_inetaton>, C<d_inetntop>, C<d_inetpton>, C<d_int64_t>, C<d_ipv6_mreq>,
-C<d_isascii>, C<d_isblank>, C<d_isfinite>, C<d_isinf>, C<d_isnan>,
-C<d_isnanl>, C<d_killpg>, C<d_lchown>, C<d_ldbl_dig>,
-C<d_libm_lib_version>, C<d_link>, C<d_localtime64>, C<d_localtime_r>,
-C<d_localtime_r_needs_tzset>, C<d_locconv>, C<d_lockf>, C<d_longdbl>,
-C<d_longlong>, C<d_lseekproto>, C<d_lstat>, C<d_madvise>,
-C<d_malloc_good_size>, C<d_malloc_size>, C<d_mblen>, C<d_mbstowcs>,
-C<d_mbtowc>, C<d_memchr>, C<d_memcmp>, C<d_memcpy>, C<d_memmove>,
-C<d_memset>, C<d_mkdir>, C<d_mkdtemp>, C<d_mkfifo>, C<d_mkstemp>,
-C<d_mkstemps>, C<d_mktime>, C<d_mktime64>, C<d_mmap>, C<d_modfl>,
-C<d_modfl_pow32_bug>, C<d_modflproto>, C<d_mprotect>, C<d_msg>,
-C<d_msg_ctrunc>, C<d_msg_dontroute>, C<d_msg_oob>, C<d_msg_peek>,
-C<d_msg_proxy>, C<d_msgctl>, C<d_msgget>, C<d_msghdr_s>, C<d_msgrcv>,
-C<d_msgsnd>, C<d_msync>, C<d_munmap>, C<d_mymalloc>, C<d_ndbm>,
-C<d_ndbm_h_uses_prototypes>, C<d_nice>, C<d_nl_langinfo>,
-C<d_nv_preserves_uv>, C<d_nv_zero_is_allbits_zero>, C<d_off64_t>,
-C<d_old_pthread_create_joinable>, C<d_oldpthreads>, C<d_oldsock>,
-C<d_open3>, C<d_pathconf>, C<d_pause>, C<d_perl_otherlibdirs>,
-C<d_phostname>, C<d_pipe>, C<d_poll>, C<d_portable>, C<d_prctl>,
-C<d_prctl_set_name>, C<d_PRId64>, C<d_PRIeldbl>, C<d_PRIEUldbl>,
-C<d_PRIfldbl>, C<d_PRIFUldbl>, C<d_PRIgldbl>, C<d_PRIGUldbl>, C<d_PRIi64>,
-C<d_printf_format_null>, C<d_PRIo64>, C<d_PRIu64>, C<d_PRIx64>,
-C<d_PRIXU64>, C<d_procselfexe>, C<d_pseudofork>, C<d_pthread_atfork>,
-C<d_pthread_attr_setscope>, C<d_pthread_yield>, C<d_pwage>, C<d_pwchange>,
-C<d_pwclass>, C<d_pwcomment>, C<d_pwexpire>, C<d_pwgecos>, C<d_pwpasswd>,
-C<d_pwquota>, C<d_qgcvt>, C<d_quad>, C<d_random_r>, C<d_readdir>,
-C<d_readdir64_r>, C<d_readdir_r>, C<d_readlink>, C<d_readv>, C<d_recvmsg>,
-C<d_rename>, C<d_rewinddir>, C<d_rmdir>, C<d_safebcpy>, C<d_safemcpy>,
-C<d_sanemcmp>, C<d_sbrkproto>, C<d_scalbnl>, C<d_sched_yield>,
-C<d_scm_rights>, C<d_SCNfldbl>, C<d_seekdir>, C<d_select>, C<d_sem>,
-C<d_semctl>, C<d_semctl_semid_ds>, C<d_semctl_semun>, C<d_semget>,
-C<d_semop>, C<d_sendmsg>, C<d_setegid>, C<d_seteuid>, C<d_setgrent>,
-C<d_setgrent_r>, C<d_setgrps>, C<d_sethent>, C<d_sethostent_r>,
-C<d_setitimer>, C<d_setlinebuf>, C<d_setlocale>, C<d_setlocale_r>,
-C<d_setnent>, C<d_setnetent_r>, C<d_setpent>, C<d_setpgid>, C<d_setpgrp>,
-C<d_setpgrp2>, C<d_setprior>, C<d_setproctitle>, C<d_setprotoent_r>,
-C<d_setpwent>, C<d_setpwent_r>, C<d_setregid>, C<d_setresgid>,
-C<d_setresuid>, C<d_setreuid>, C<d_setrgid>, C<d_setruid>, C<d_setsent>,
-C<d_setservent_r>, C<d_setsid>, C<d_setvbuf>, C<d_sfio>, C<d_shm>,
-C<d_shmat>, C<d_shmatprototype>, C<d_shmctl>, C<d_shmdt>, C<d_shmget>,
-C<d_sigaction>, C<d_signbit>, C<d_sigprocmask>, C<d_sigsetjmp>,
-C<d_sin6_scope_id>, C<d_sitearch>, C<d_snprintf>, C<d_sockaddr_in6>,
-C<d_sockaddr_sa_len>, C<d_sockatmark>, C<d_sockatmarkproto>, C<d_socket>,
-C<d_socklen_t>, C<d_sockpair>, C<d_socks5_init>,
-C<d_sprintf_returns_strlen>, C<d_sqrtl>, C<d_srand48_r>, C<d_srandom_r>,
-C<d_sresgproto>, C<d_sresuproto>, C<d_statblks>, C<d_statfs_f_flags>,
-C<d_statfs_s>, C<d_static_inline>, C<d_statvfs>, C<d_stdio_cnt_lval>,
-C<d_stdio_ptr_lval>, C<d_stdio_ptr_lval_nochange_cnt>,
-C<d_stdio_ptr_lval_sets_cnt>, C<d_stdio_stream_array>, C<d_stdiobase>,
-C<d_stdstdio>, C<d_strchr>, C<d_strcoll>, C<d_strctcpy>, C<d_strerrm>,
-C<d_strerror>, C<d_strerror_r>, C<d_strftime>, C<d_strlcat>, C<d_strlcpy>,
-C<d_strtod>, C<d_strtol>, C<d_strtold>, C<d_strtoll>, C<d_strtoq>,
-C<d_strtoul>, C<d_strtoull>, C<d_strtouq>, C<d_strxfrm>, C<d_suidsafe>,
-C<d_symlink>, C<d_syscall>, C<d_syscallproto>, C<d_sysconf>,
-C<d_sysernlst>, C<d_syserrlst>, C<d_system>, C<d_tcgetpgrp>,
-C<d_tcsetpgrp>, C<d_telldir>, C<d_telldirproto>, C<d_time>, C<d_timegm>,
-C<d_times>, C<d_tm_tm_gmtoff>, C<d_tm_tm_zone>, C<d_tmpnam_r>,
-C<d_truncate>, C<d_ttyname_r>, C<d_tzname>, C<d_u32align>, C<d_ualarm>,
-C<d_umask>, C<d_uname>, C<d_union_semun>, C<d_unordered>, C<d_unsetenv>,
-C<d_usleep>, C<d_usleepproto>, C<d_ustat>, C<d_vendorarch>, C<d_vendorbin>,
-C<d_vendorlib>, C<d_vendorscript>, C<d_vfork>, C<d_void_closedir>,
-C<d_voidsig>, C<d_voidtty>, C<d_volatile>, C<d_vprintf>, C<d_vsnprintf>,
-C<d_wait4>, C<d_waitpid>, C<d_wcstombs>, C<d_wctomb>, C<d_writev>,
-C<d_xenix>, C<date>, C<db_hashtype>, C<db_prefixtype>, C<db_version_major>,
-C<db_version_minor>, C<db_version_patch>, C<defvoidused>, C<direntrytype>,
-C<dlext>, C<dlsrc>, C<doublesize>, C<drand01>, C<drand48_r_proto>,
-C<dtrace>, C<dynamic_ext>
-
-=over 4
-
-=item e
-
-=back
-
-C<eagain>, C<ebcdic>, C<echo>, C<egrep>, C<emacs>, C<endgrent_r_proto>,
-C<endhostent_r_proto>, C<endnetent_r_proto>, C<endprotoent_r_proto>,
-C<endpwent_r_proto>, C<endservent_r_proto>, C<eunicefix>, C<exe_ext>,
-C<expr>, C<extensions>, C<extern_C>, C<extras>
-
-=over 4
-
-=item f
-
-=back
-
-C<fflushall>, C<fflushNULL>, C<find>, C<firstmakefile>, C<flex>,
-C<fpossize>, C<fpostype>, C<freetype>, C<from>, C<full_ar>, C<full_csh>,
-C<full_sed>
-
-=over 4
-
-=item g
-
-=back
-
-C<gccansipedantic>, C<gccosandvers>, C<gccversion>, C<getgrent_r_proto>,
-C<getgrgid_r_proto>, C<getgrnam_r_proto>, C<gethostbyaddr_r_proto>,
-C<gethostbyname_r_proto>, C<gethostent_r_proto>, C<getlogin_r_proto>,
-C<getnetbyaddr_r_proto>, C<getnetbyname_r_proto>, C<getnetent_r_proto>,
-C<getprotobyname_r_proto>, C<getprotobynumber_r_proto>,
-C<getprotoent_r_proto>, C<getpwent_r_proto>, C<getpwnam_r_proto>,
-C<getpwuid_r_proto>, C<getservbyname_r_proto>, C<getservbyport_r_proto>,
-C<getservent_r_proto>, C<getspnam_r_proto>, C<gidformat>, C<gidsign>,
-C<gidsize>, C<gidtype>, C<glibpth>, C<gmake>, C<gmtime_r_proto>,
-C<gnulibc_version>, C<grep>, C<groupcat>, C<groupstype>, C<gzip>
-
-=over 4
-
-=item h
-
-=back
-
-C<h_fcntl>, C<h_sysfile>, C<hint>, C<hostcat>, C<html1dir>, C<html1direxp>,
-C<html3dir>, C<html3direxp>
-
-=over 4
-
-=item i
-
-=back
-
-C<i16size>, C<i16type>, C<i32size>, C<i32type>, C<i64size>, C<i64type>,
-C<i8size>, C<i8type>, C<i_arpainet>, C<i_assert>, C<i_bsdioctl>,
-C<i_crypt>, C<i_db>, C<i_dbm>, C<i_dirent>, C<i_dld>, C<i_dlfcn>,
-C<i_fcntl>, C<i_float>, C<i_fp>, C<i_fp_class>, C<i_gdbm>, C<i_gdbm_ndbm>,
-C<i_gdbmndbm>, C<i_grp>, C<i_ieeefp>, C<i_inttypes>, C<i_langinfo>,
-C<i_libutil>, C<i_limits>, C<i_locale>, C<i_machcthr>, C<i_malloc>,
-C<i_mallocmalloc>, C<i_math>, C<i_memory>, C<i_mntent>, C<i_ndbm>,
-C<i_netdb>, C<i_neterrno>, C<i_netinettcp>, C<i_niin>, C<i_poll>,
-C<i_prot>, C<i_pthread>, C<i_pwd>, C<i_rpcsvcdbm>, C<i_sfio>, C<i_sgtty>,
-C<i_shadow>, C<i_socks>, C<i_stdarg>, C<i_stdbool>, C<i_stddef>,
-C<i_stdlib>, C<i_string>, C<i_sunmath>, C<i_sysaccess>, C<i_sysdir>,
-C<i_sysfile>, C<i_sysfilio>, C<i_sysin>, C<i_sysioctl>, C<i_syslog>,
-C<i_sysmman>, C<i_sysmode>, C<i_sysmount>, C<i_sysndir>, C<i_sysparam>,
-C<i_syspoll>, C<i_sysresrc>, C<i_syssecrt>, C<i_sysselct>, C<i_syssockio>,
-C<i_sysstat>, C<i_sysstatfs>, C<i_sysstatvfs>, C<i_systime>, C<i_systimek>,
-C<i_systimes>, C<i_systypes>, C<i_sysuio>, C<i_sysun>, C<i_sysutsname>,
-C<i_sysvfs>, C<i_syswait>, C<i_termio>, C<i_termios>, C<i_time>,
-C<i_unistd>, C<i_ustat>, C<i_utime>, C<i_values>, C<i_varargs>,
-C<i_varhdr>, C<i_vfork>, C<ignore_versioned_solibs>, C<inc_version_list>,
-C<inc_version_list_init>, C<incpath>, C<inews>, C<initialinstalllocation>,
-C<installarchlib>, C<installbin>, C<installhtml1dir>, C<installhtml3dir>,
-C<installman1dir>, C<installman3dir>, C<installprefix>,
-C<installprefixexp>, C<installprivlib>, C<installscript>,
-C<installsitearch>, C<installsitebin>, C<installsitehtml1dir>,
-C<installsitehtml3dir>, C<installsitelib>, C<installsiteman1dir>,
-C<installsiteman3dir>, C<installsitescript>, C<installstyle>,
-C<installusrbinperl>, C<installvendorarch>, C<installvendorbin>,
-C<installvendorhtml1dir>, C<installvendorhtml3dir>, C<installvendorlib>,
-C<installvendorman1dir>, C<installvendorman3dir>, C<installvendorscript>,
-C<intsize>, C<issymlink>, C<ivdformat>, C<ivsize>, C<ivtype>
-
-=over 4
-
-=item k
-
-=back
-
-C<known_extensions>, C<ksh>
-
-=over 4
-
-=item l
-
-=back
-
-C<ld>, C<ld_can_script>, C<lddlflags>, C<ldflags>,
-C<ldflags_uselargefiles>, C<ldlibpthname>, C<less>, C<lib_ext>, C<libc>,
-C<libperl>, C<libpth>, C<libs>, C<libsdirs>, C<libsfiles>, C<libsfound>,
-C<libspath>, C<libswanted>, C<libswanted_uselargefiles>, C<line>, C<lint>,
-C<lkflags>, C<ln>, C<lns>, C<localtime_r_proto>, C<locincpth>,
-C<loclibpth>, C<longdblsize>, C<longlongsize>, C<longsize>, C<lp>, C<lpr>,
-C<ls>, C<lseeksize>, C<lseektype>
-
-=over 4
-
-=item m
-
-=back
-
-C<mad>, C<madlyh>, C<madlyobj>, C<madlysrc>, C<mail>, C<mailx>, C<make>,
-C<make_set_make>, C<mallocobj>, C<mallocsrc>, C<malloctype>, C<man1dir>,
-C<man1direxp>, C<man1ext>, C<man3dir>, C<man3direxp>, C<man3ext>,
-C<mips_type>, C<mistrustnm>, C<mkdir>, C<mmaptype>, C<modetype>, C<more>,
-C<multiarch>, C<mv>, C<myarchname>, C<mydomain>, C<myhostname>, C<myuname>
-
-=over 4
-
-=item n
-
-=back
-
-C<n>, C<need_va_copy>, C<netdb_hlen_type>, C<netdb_host_type>,
-C<netdb_name_type>, C<netdb_net_type>, C<nm>, C<nm_opt>, C<nm_so_opt>,
-C<nonxs_ext>, C<nroff>, C<nv_overflows_integers_at>,
-C<nv_preserves_uv_bits>, C<nveformat>, C<nvEUformat>, C<nvfformat>,
-C<nvFUformat>, C<nvgformat>, C<nvGUformat>, C<nvsize>, C<nvtype>
-
-=over 4
-
-=item o
-
-=back
-
-C<o_nonblock>, C<obj_ext>, C<old_pthread_create_joinable>, C<optimize>,
-C<orderlib>, C<osname>, C<osvers>, C<otherlibdirs>
-
-=over 4
-
-=item p
-
-=back
-
-C<package>, C<pager>, C<passcat>, C<patchlevel>, C<path_sep>, C<perl>,
-C<perl5>
-
-=over 4
-
-=item P
-
-=back
-
-C<PERL_API_REVISION>, C<PERL_API_SUBVERSION>, C<PERL_API_VERSION>,
-C<PERL_CONFIG_SH>, C<PERL_PATCHLEVEL>, C<perl_patchlevel>,
-C<PERL_REVISION>, C<perl_static_inline>, C<PERL_SUBVERSION>,
-C<PERL_VERSION>, C<perladmin>, C<perllibs>, C<perlpath>, C<pg>,
-C<phostname>, C<pidtype>, C<plibpth>, C<pmake>, C<pr>, C<prefix>,
-C<prefixexp>, C<privlib>, C<privlibexp>, C<procselfexe>, C<prototype>,
-C<ptrsize>
-
-=over 4
-
-=item q
-
-=back
-
-C<quadkind>, C<quadtype>
-
-=over 4
-
-=item r
-
-=back
-
-C<randbits>, C<randfunc>, C<random_r_proto>, C<randseedtype>, C<ranlib>,
-C<rd_nodata>, C<readdir64_r_proto>, C<readdir_r_proto>, C<revision>, C<rm>,
-C<rm_try>, C<rmail>, C<run>, C<runnm>
-
-=over 4
-
-=item s
-
-=back
-
-C<sched_yield>, C<scriptdir>, C<scriptdirexp>, C<sed>, C<seedfunc>,
-C<selectminbits>, C<selecttype>, C<sendmail>, C<setgrent_r_proto>,
-C<sethostent_r_proto>, C<setlocale_r_proto>, C<setnetent_r_proto>,
-C<setprotoent_r_proto>, C<setpwent_r_proto>, C<setservent_r_proto>,
-C<sGMTIME_max>, C<sGMTIME_min>, C<sh>, C<shar>, C<sharpbang>, C<shmattype>,
-C<shortsize>, C<shrpenv>, C<shsharp>, C<sig_count>, C<sig_name>,
-C<sig_name_init>, C<sig_num>, C<sig_num_init>, C<sig_size>, C<signal_t>,
-C<sitearch>, C<sitearchexp>, C<sitebin>, C<sitebinexp>, C<sitehtml1dir>,
-C<sitehtml1direxp>, C<sitehtml3dir>, C<sitehtml3direxp>, C<sitelib>,
-C<sitelib_stem>, C<sitelibexp>, C<siteman1dir>, C<siteman1direxp>,
-C<siteman3dir>, C<siteman3direxp>, C<siteprefix>, C<siteprefixexp>,
-C<sitescript>, C<sitescriptexp>, C<sizesize>, C<sizetype>, C<sleep>,
-C<sLOCALTIME_max>, C<sLOCALTIME_min>, C<smail>, C<so>, C<sockethdr>,
-C<socketlib>, C<socksizetype>, C<sort>, C<spackage>, C<spitshell>,
-C<sPRId64>, C<sPRIeldbl>, C<sPRIEUldbl>, C<sPRIfldbl>, C<sPRIFUldbl>,
-C<sPRIgldbl>, C<sPRIGUldbl>, C<sPRIi64>, C<sPRIo64>, C<sPRIu64>,
-C<sPRIx64>, C<sPRIXU64>, C<srand48_r_proto>, C<srandom_r_proto>, C<src>,
-C<sSCNfldbl>, C<ssizetype>, C<st_ino_sign>, C<st_ino_size>, C<startperl>,
-C<startsh>, C<static_ext>, C<stdchar>, C<stdio_base>, C<stdio_bufsiz>,
-C<stdio_cnt>, C<stdio_filbuf>, C<stdio_ptr>, C<stdio_stream_array>,
-C<strerror_r_proto>, C<strings>, C<submit>, C<subversion>, C<sysman>
-
-=over 4
-
-=item t
-
-=back
-
-C<tail>, C<tar>, C<targetarch>, C<tbl>, C<tee>, C<test>, C<timeincl>,
-C<timetype>, C<tmpnam_r_proto>, C<to>, C<touch>, C<tr>, C<trnl>, C<troff>,
-C<ttyname_r_proto>
-
-=over 4
-
-=item u
-
-=back
-
-C<u16size>, C<u16type>, C<u32size>, C<u32type>, C<u64size>, C<u64type>,
-C<u8size>, C<u8type>, C<uidformat>, C<uidsign>, C<uidsize>, C<uidtype>,
-C<uname>, C<uniq>, C<uquadtype>, C<use5005threads>, C<use64bitall>,
-C<use64bitint>, C<usecrosscompile>, C<usedevel>, C<usedl>, C<usedtrace>,
-C<usefaststdio>, C<useithreads>, C<usekernprocpathname>, C<uselargefiles>,
-C<uselongdouble>, C<usemallocwrap>, C<usemorebits>, C<usemultiplicity>,
-C<usemymalloc>, C<usenm>, C<usensgetexecutablepath>, C<useopcode>,
-C<useperlio>, C<useposix>, C<usereentrant>, C<userelocatableinc>,
-C<usesfio>, C<useshrplib>, C<usesitecustomize>, C<usesocks>, C<usethreads>,
-C<usevendorprefix>, C<usevfork>, C<usrinc>, C<uuname>, C<uvoformat>,
-C<uvsize>, C<uvtype>, C<uvuformat>, C<uvxformat>, C<uvXUformat>
-
-=over 4
-
-=item v
-
-=back
-
-C<vaproto>, C<vendorarch>, C<vendorarchexp>, C<vendorbin>, C<vendorbinexp>,
-C<vendorhtml1dir>, C<vendorhtml1direxp>, C<vendorhtml3dir>,
-C<vendorhtml3direxp>, C<vendorlib>, C<vendorlib_stem>, C<vendorlibexp>,
-C<vendorman1dir>, C<vendorman1direxp>, C<vendorman3dir>,
-C<vendorman3direxp>, C<vendorprefix>, C<vendorprefixexp>, C<vendorscript>,
-C<vendorscriptexp>, C<version>, C<version_patchlevel_string>,
-C<versiononly>, C<vi>, C<voidflags>
-
-=over 4
-
-=item x
-
-=back
-
-C<xlibpth>
-
-=over 4
-
-=item y
-
-=back
-
-C<yacc>, C<yaccflags>
-
-=over 4
-
-=item z
-
-=back
-
-C<zcat>, C<zip>
-
-=over 4
-
-=item GIT DATA
-
-=item NOTE
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-dynamic, nonxs, static
-
-=item AUTHOR
-
-=back
-
-=head2 Cwd - get pathname of current working directory
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item getcwd and friends
-
-getcwd, cwd, fastcwd, fastgetcwd, getdcwd
-
-=item abs_path and friends
-
-abs_path, realpath, fast_abs_path
-
-=item $ENV{PWD}
-
-=back
-
-=item NOTES
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 DB - programmatic interface to the Perl debugging API
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Global Variables
-
- $DB::sub, %DB::sub, $DB::single, $DB::signal, $DB::trace, @DB::args,
-@DB::dbline, %DB::dbline, $DB::package, $DB::filename, $DB::subname,
-$DB::lineno
-
-=item API Methods
-
-CLIENT->register(), CLIENT->evalcode(STRING), CLIENT->skippkg('D::hide'),
-CLIENT->run(), CLIENT->step(), CLIENT->next(), CLIENT->done()
-
-=item Client Callback Methods
-
-CLIENT->init(), CLIENT->prestop([STRING]), CLIENT->stop(), CLIENT->idle(),
-CLIENT->poststop([STRING]), CLIENT->evalcode(STRING), CLIENT->cleanup(),
-CLIENT->output(LIST)
-
-=back
-
-=item BUGS
-
-=item AUTHOR
-
-=back
-
-=head2 DBM_Filter -- Filter DBM keys/values
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item What is a DBM Filter?
-
-=over 4
-
-=item So what's new?
-
-=back
-
-=item METHODS
-
-=over 4
-
-=item $db->Filter_Push() / $db->Filter_Key_Push() /
-$db->Filter_Value_Push()
-
-Filter_Push, Filter_Key_Push, Filter_Value_Push
-
-=item $db->Filter_Pop()
-
-=item $db->Filtered()
-
-=back
-
-=item Writing a Filter
-
-=over 4
-
-=item Immediate Filters
-
-=item Canned Filters
-
-"name", params
-
-=back
-
-=item Filters Included
-
-utf8, encode, compress, int32, null
-
-=item NOTES
-
-=over 4
-
-=item Maintain Round Trip Integrity
-
-=item Don't mix filtered & non-filtered data in the same database file.
-
-=back
-
-=item EXAMPLE
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 DBM_Filter::compress - filter for DBM_Filter
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 DBM_Filter::encode - filter for DBM_Filter
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 DBM_Filter::int32 - filter for DBM_Filter
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 DBM_Filter::null - filter for DBM_Filter
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 DBM_Filter::utf8 - filter for DBM_Filter
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 Data::Dumper - stringified perl data structures, suitable for both
-printing and C<eval>
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Methods
-
-I<PACKAGE>->new(I<ARRAYREF [>, I<ARRAYREF]>), I<$OBJ>->Dump I<or>
-I<PACKAGE>->Dump(I<ARRAYREF [>, I<ARRAYREF]>), I<$OBJ>->Seen(I<[HASHREF]>),
-I<$OBJ>->Values(I<[ARRAYREF]>), I<$OBJ>->Names(I<[ARRAYREF]>),
-I<$OBJ>->Reset
-
-=item Functions
-
-Dumper(I<LIST>)
-
-=item Configuration Variables or Methods
-
-=item Exports
-
-Dumper
-
-=back
-
-=item EXAMPLES
-
-=item BUGS
-
-=over 4
-
-=item NOTE
-
-=back
-
-=item AUTHOR
-
-=item VERSION
-
-=item SEE ALSO
-
-=back
-
-=head2 Devel::InnerPackage - find all the inner packages of a package
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item list_packages <package name>
-
-=back
-
-=back
-
-=over 4
-
-=item AUTHOR
-
-=item COPYING
-
-=item BUGS
-
-=back
-
-=head2 Devel::PPPort - Perl/Pollution/Portability
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Why use ppport.h?
-
-=item How to use ppport.h
-
-=item Running ppport.h
-
-=back
-
-=item FUNCTIONS
-
-=over 4
-
-=item WriteFile
-
-=back
-
-=item COMPATIBILITY
-
-=over 4
-
-=item Provided Perl compatibility API
-
-=item Perl API not supported by ppport.h
-
-perl 5.14.0, perl 5.13.10, perl 5.13.8, perl 5.13.7, perl 5.13.6, perl
-5.13.5, perl 5.13.4, perl 5.13.3, perl 5.13.2, perl 5.13.1, perl 5.11.5,
-perl 5.11.4, perl 5.11.2, perl 5.11.1, perl 5.11.0, perl 5.10.1, perl
-5.10.0, perl 5.9.5, perl 5.9.4, perl 5.9.3, perl 5.9.2, perl 5.9.1, perl
-5.9.0, perl 5.8.3, perl 5.8.1, perl 5.8.0, perl 5.7.3, perl 5.7.2, perl
-5.7.1, perl 5.6.1, perl 5.6.0, perl 5.005_03, perl 5.005, perl 5.004_05,
-perl 5.004
-
-=back
-
-=item BUGS
-
-=item AUTHORS
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 Devel::Peek - A data debugging tool for the XS programmer
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Runtime debugging
-
-=item Memory footprint debugging
-
-=back
-
-=item EXAMPLES
-
-=over 4
-
-=item A simple scalar string
-
-=item A simple scalar number
-
-=item A simple scalar with an extra reference
-
-=item A reference to a simple scalar
-
-=item A reference to an array
-
-=item A reference to a hash
-
-=item Dumping a large array or hash
-
-=item A reference to an SV which holds a C pointer
-
-=item A reference to a subroutine
-
-=back
-
-=item EXPORTS
-
-=item BUGS
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Devel::SelfStubber - generate stubs for a SelfLoading module
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 Digest - Modules that calculate message digests
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-I<binary>, I<hex>, I<base64>
-
-=item OO INTERFACE
-
-$ctx = Digest->XXX($arg,...), $ctx = Digest->new(XXX => $arg,...), $ctx =
-Digest::XXX->new($arg,...), $other_ctx = $ctx->clone, $ctx->reset,
-$ctx->add( $data ), $ctx->add( $chunk1, $chunk2, ... ), $ctx->addfile(
-$io_handle ), $ctx->add_bits( $data, $nbits ), $ctx->add_bits( $bitstring
-), $ctx->digest, $ctx->hexdigest, $ctx->b64digest
-
-=item Digest speed
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 Digest::MD5 - Perl interface to the MD5 Algorithm
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item FUNCTIONS
-
-md5($data,...), md5_hex($data,...), md5_base64($data,...)
-
-=item METHODS
-
-$md5 = Digest::MD5->new, $md5->reset, $md5->clone, $md5->add($data,...),
-$md5->addfile($io_handle), $md5->add_bits($data, $nbits),
-$md5->add_bits($bitstring), $md5->digest, $md5->hexdigest, $md5->b64digest
-
-=item EXAMPLES
-
-=item SEE ALSO
-
-=item COPYRIGHT
-
-=item AUTHORS
-
-=back
-
-=head2 Digest::SHA - Perl extension for SHA-1/224/256/384/512
-
-=over 4
-
-=item SYNOPSIS
-
-=item SYNOPSIS (HMAC-SHA)
-
-=item ABSTRACT
-
-=item DESCRIPTION
-
-=item NIST STATEMENT ON SHA-1
-
-=item PADDING OF BASE64 DIGESTS
-
-=item EXPORT
-
-=item EXPORTABLE FUNCTIONS
-
-B<sha1($data, ...)>, B<sha224($data, ...)>, B<sha256($data, ...)>,
-B<sha384($data, ...)>, B<sha512($data, ...)>, B<sha512224($data, ...)>,
-B<sha512256($data, ...)>, B<sha1_hex($data, ...)>, B<sha224_hex($data,
-...)>, B<sha256_hex($data, ...)>, B<sha384_hex($data, ...)>,
-B<sha512_hex($data, ...)>, B<sha512224_hex($data, ...)>,
-B<sha512256_hex($data, ...)>, B<sha1_base64($data, ...)>,
-B<sha224_base64($data, ...)>, B<sha256_base64($data, ...)>,
-B<sha384_base64($data, ...)>, B<sha512_base64($data, ...)>,
-B<sha512224_base64($data, ...)>, B<sha512256_base64($data, ...)>,
-B<new($alg)>, B<reset($alg)>, B<hashsize>, B<algorithm>, B<clone>,
-B<add($data, ...)>, B<add_bits($data, $nbits)>, B<add_bits($bits)>,
-B<addfile(*FILE)>, B<addfile($filename [, $mode])>, B<dump($filename)>,
-B<load($filename)>, B<digest>, B<hexdigest>, B<b64digest>,
-B<hmac_sha1($data, $key)>, B<hmac_sha224($data, $key)>,
-B<hmac_sha256($data, $key)>, B<hmac_sha384($data, $key)>,
-B<hmac_sha512($data, $key)>, B<hmac_sha512224($data, $key)>,
-B<hmac_sha512256($data, $key)>, B<hmac_sha1_hex($data, $key)>,
-B<hmac_sha224_hex($data, $key)>, B<hmac_sha256_hex($data, $key)>,
-B<hmac_sha384_hex($data, $key)>, B<hmac_sha512_hex($data, $key)>,
-B<hmac_sha512224_hex($data, $key)>, B<hmac_sha512256_hex($data, $key)>,
-B<hmac_sha1_base64($data, $key)>, B<hmac_sha224_base64($data, $key)>,
-B<hmac_sha256_base64($data, $key)>, B<hmac_sha384_base64($data, $key)>,
-B<hmac_sha512_base64($data, $key)>, B<hmac_sha512224_base64($data, $key)>,
-B<hmac_sha512256_base64($data, $key)>
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item ACKNOWLEDGMENTS
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 Digest::base - Digest base class
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=back
-
-=head2 Digest::file - Calculate digests of files
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-digest_file( $file, $algorithm, [$arg,...] ), digest_file_hex( $file,
-$algorithm, [$arg,...] ), digest_file_base64( $file, $algorithm, [$arg,...]
-)
-
-=item SEE ALSO
-
-=back
-
-=head2 DirHandle - supply object methods for directory handles
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 Dumpvalue - provides screen dump of Perl data.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Creation
-
-C<arrayDepth>, C<hashDepth>, C<compactDump>, C<veryCompact>, C<globPrint>,
-C<dumpDBFiles>, C<dumpPackages>, C<dumpReused>, C<tick>, C<quoteHighBit>,
-C<printUndef>, C<usageOnly>, unctrl, subdump, bareStringify, quoteHighBit,
-stopDbSignal
-
-=item Methods
-
-dumpValue, dumpValues, stringify, dumpvars, set_quote, set_unctrl,
-compactDump, veryCompact, set, get
-
-=back
-
-=back
-
-=head2 DynaLoader - Dynamically load C libraries into Perl code
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-@dl_library_path, @dl_resolve_using, @dl_require_symbols, @dl_librefs,
-@dl_modules, @dl_shared_objects, dl_error(), $dl_debug, dl_findfile(),
-dl_expandspec(), dl_load_file(), dl_unload_file(), dl_load_flags(),
-dl_find_symbol(), dl_find_symbol_anywhere(), dl_undef_symbols(),
-dl_install_xsub(), bootstrap()
-
-=item AUTHOR
-
-=back
-
-=head2 Encode - character encodings in Perl
-
-=over 4
-
-=item SYNOPSIS
-
-=over 4
-
-=item Table of Contents
-
-=back
-
-=item DESCRIPTION
-
-=over 4
-
-=item TERMINOLOGY
-
-=back
-
-=item THE PERL ENCODING API
-
-$octets = encode(ENCODING, STRING[, CHECK]), $string = decode(ENCODING,
-OCTETS[, CHECK]), [$obj =] find_encoding(ENCODING), [$length =]
-from_to($octets, FROM_ENC, TO_ENC [, CHECK]), $octets =
-encode_utf8($string);, $string = decode_utf8($octets [, CHECK]);
-
-=over 4
-
-=item Listing available encodings
-
-=item Defining Aliases
-
-=item Finding IANA Character Set Registry names
-
-=back
-
-=item Encoding via PerlIO
-
-=item Handling Malformed Data
-
-B<NOTE:> Not all encoding support this feature, I<CHECK> =
-Encode::FB_DEFAULT ( == 0), I<CHECK> = Encode::FB_CROAK ( == 1), I<CHECK> =
-Encode::FB_QUIET, I<CHECK> = Encode::FB_WARN, perlqq mode (I<CHECK> =
-Encode::FB_PERLQQ), HTML charref mode (I<CHECK> = Encode::FB_HTMLCREF), XML
-charref mode (I<CHECK> = Encode::FB_XMLCREF), The bitmask,
-Encode::LEAVE_SRC
-
-=over 4
-
-=item coderef for CHECK
-
-=back
-
-=item Defining Encodings
-
-=item The UTF8 flag
-
-Goal #1:, Goal #2:, Goal #3:, Goal #4:
-
-=over 4
-
-=item Messing with Perl's Internals
-
-is_utf8(STRING [, CHECK]), _utf8_on(STRING), _utf8_off(STRING)
-
-=back
-
-=item UTF-8 vs. utf8 vs. UTF8
-
-=item SEE ALSO
-
-=item MAINTAINER
-
-=item COPYRIGHT
-
-=back
-
-=head2 Encode::Alias - alias definitions to encodings
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-As a simple string, As a qr// compiled regular expression, e.g.:, As a code
-reference, e.g.:
-
-=over 4
-
-=item Alias overloading
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 Encode::Byte - Single Byte Encodings
-
-=over 4
-
-=item SYNOPSIS
-
-=item ABSTRACT
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=back
-
-=head2 Encode::CJKConstants -- Internally used by Encode::??::ISO_2022_*
-
-=head2 Encode::CN - China-based Chinese Encodings
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item NOTES
-
-=item BUGS
-
-=item SEE ALSO
-
-=back
-
-=head2 Encode::CN::HZ -- internally used by Encode::CN
-
-=head2 Encode::Config -- internally used by Encode
-
-=head2 Encode::EBCDIC - EBCDIC Encodings
-
-=over 4
-
-=item SYNOPSIS
-
-=item ABSTRACT
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=back
-
-=head2 Encode::Encoder -- Object Oriented Encoder
-
-=over 4
-
-=item SYNOPSIS
-
-=item ABSTRACT
-
-=item Description
-
-=over 4
-
-=item Predefined Methods
-
-$e = Encode::Encoder-E<gt>new([$data, $encoding]);, encoder(),
-$e-E<gt>data([$data]), $e-E<gt>encoding([$encoding]),
-$e-E<gt>bytes([$encoding])
-
-=item Example: base64 transcoder
-
-=item Operator Overloading
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 Encode::Encoding - Encode Implementation Base Class
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Methods you should implement
-
--E<gt>encode($string [,$check]), -E<gt>decode($octets [,$check]),
--E<gt>cat_decode($destination, $octets, $offset, $terminator [,$check])
-
-=item Other methods defined in Encode::Encodings
-
--E<gt>name, -E<gt>mime_name, -E<gt>renew, -E<gt>renewed, -E<gt>perlio_ok(),
--E<gt>needs_lines()
-
-=item Example: Encode::ROT13
-
-=back
-
-=item Why the heck Encode API is different?
-
-=over 4
-
-=item Compiled Encodings
-
-=back
-
-=item SEE ALSO
-
-Scheme 1, Scheme 2, Other Schemes
-
-=back
-
-=head2 Encode::GSM0338 -- ESTI GSM 03.38 Encoding
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item NOTES
-
-=item BUGS
-
-=item SEE ALSO
-
-=back
-
-=head2 Encode::Guess -- Guesses encoding from data
-
-=over 4
-
-=item SYNOPSIS
-
-=item ABSTRACT
-
-=item DESCRIPTION
-
-Encode::Guess->set_suspects, Encode::Guess->add_suspects,
-Encode::decode("Guess" ...), Encode::Guess->guess($data),
-guess_encoding($data, [, I<list of suspects>])
-
-=item CAVEATS
-
-=item TO DO
-
-=item SEE ALSO
-
-=back
-
-=head2 Encode::JP - Japanese Encodings
-
-=over 4
-
-=item SYNOPSIS
-
-=item ABSTRACT
-
-=item DESCRIPTION
-
-=item Note on ISO-2022-JP(-1)?
-
-=item BUGS
-
-=item SEE ALSO
-
-=back
-
-=head2 Encode::JP::H2Z -- internally used by Encode::JP::2022_JP*
-
-=head2 Encode::JP::JIS7 -- internally used by Encode::JP
-
-=head2 Encode::KR - Korean Encodings
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item BUGS
-
-=item SEE ALSO
-
-=back
-
-=head2 Encode::KR::2022_KR -- internally used by Encode::KR
-
-=head2 Encode::MIME::Header -- MIME 'B' and 'Q' header encoding
-
-=over 4
-
-=item SYNOPSIS
-
-=item ABSTRACT
-
-=item DESCRIPTION
-
-=item BUGS
-
-=item SEE ALSO
-
-=back
-
-=head2 Encode::MIME::Name, Encode::MIME::NAME -- internally used by Encode
-
-=over 4
-
-=item SEE ALSO
-
-=back
-
-=head2 Encode::PerlIO -- a detailed document on Encode and PerlIO
-
-=over 4
-
-=item Overview
-
-=item How does it work?
-
-=item Line Buffering
-
-=over 4
-
-=item How can I tell whether my encoding fully supports PerlIO ?
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 Encode::Supported -- Encodings supported by Encode
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Encoding Names
-
-=back
-
-=item Supported Encodings
-
-=over 4
-
-=item Built-in Encodings
-
-=item Encode::Unicode -- other Unicode encodings
-
-=item Encode::Byte -- Extended ASCII
-
-ISO-8859 and corresponding vendor mappings, KOI8 - De Facto Standard for
-the Cyrillic world
-
-=item gsm0338 - Hentai Latin 1
-
-gsm0338 support before 2.19
-
-=item CJK: Chinese, Japanese, Korean (Multibyte)
-
-Encode::CN -- Continental China, Encode::JP -- Japan, Encode::KR -- Korea,
-Encode::TW -- Taiwan, Encode::HanExtra -- More Chinese via CPAN,
-Encode::JIS2K -- JIS X 0213 encodings via CPAN
-
-=item Miscellaneous encodings
-
-Encode::EBCDIC, Encode::Symbols, Encode::MIME::Header, Encode::Guess
-
-=back
-
-=item Unsupported encodings
-
- ISO-2022-JP-2 [RFC1554], ISO-2022-CN [RFC1922], Various HP-UX encodings,
-Cyrillic encoding ISO-IR-111, ISO-8859-8-1 [Hebrew], ISIRI 3342, Iran
-System, ISIRI 2900 [Farsi], Thai encoding TCVN, Vietnamese encodings VPS,
-Various Mac encodings, (Mac) Indic encodings
-
-=item Encoding vs. Charset -- terminology
-
-=item Encoding Classification (by Anton Tagunov and Dan Kogai)
-
-=over 4
-
-=item Microsoft-related naming mess
-
-KS_C_5601-1987, GB2312, Big5, Shift_JIS
-
-=back
-
-=item Glossary
-
-character repertoire, coded character set (CCS), character encoding scheme
-(CES), charset (in MIME context), EUC, ISO-2022, UCS, UCS-2, Unicode, UTF,
-UTF-16
-
-=item See Also
-
-=item References
-
-ECMA, ECMA-035 (eq C<ISO-2022>), IANA, Assigned Charset Names by IANA, ISO,
-RFC, UC, Unicode Glossary
-
-=over 4
-
-=item Other Notable Sites
-
-czyborra.com, CJK.inf, Jungshik Shin's Hangul FAQ, debian.org:
-"Introduction to i18n"
-
-=item Offline sources
-
-C<CJKV Information Processing> by Ken Lunde
-
-=back
-
-=back
-
-=head2 Encode::Symbol - Symbol Encodings
-
-=over 4
-
-=item SYNOPSIS
-
-=item ABSTRACT
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=back
-
-=head2 Encode::TW - Taiwan-based Chinese Encodings
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item NOTES
-
-=item BUGS
-
-=item SEE ALSO
-
-=back
-
-=head2 Encode::Unicode -- Various Unicode Transformation Formats
-
-=over 4
-
-=item SYNOPSIS
-
-=item ABSTRACT
-
-L<http://www.unicode.org/glossary/> says:, Quick Reference
-
-=item Size, Endianness, and BOM
-
-=over 4
-
-=item by size
-
-=item by endianness
-
-BOM as integer when fetched in network byte order
-
-=back
-
-=item Surrogate Pairs
-
-=item Error Checking
-
-=item SEE ALSO
-
-=back
-
-=head2 Encode::Unicode::UTF7 -- UTF-7 encoding
-
-=over 4
-
-=item SYNOPSIS
-
-=item ABSTRACT
-
-=item In Practice
-
-=item SEE ALSO
-
-=back
-
-=head2 English - use nice English (or awk) names for ugly punctuation
-variables
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item PERFORMANCE
-
-=back
-
-=head2 Env - perl module that imports environment variables as scalars or
-arrays
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item LIMITATIONS
-
-=item AUTHOR
-
-=back
-
-=head2 Errno - System errno constants
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CAVEATS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Exporter - Implements default import method for modules
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item How to Export
-
-=item Selecting What To Export
-
-=item How to Import
-
-C<use YourModule;>, C<use YourModule ();>, C<use YourModule qw(...);>
-
-=back
-
-=item Advanced features
-
-=over 4
-
-=item Specialised Import Lists
-
-=item Exporting without using Exporter's import method
-
-=item Exporting without inheriting from Exporter
-
-=item Module Version Checking
-
-=item Managing Unknown Symbols
-
-=item Tag Handling Utility Functions
-
-=item Generating combined tags
-
-=item C<AUTOLOAD>ed Constants
-
-=back
-
-=item Good Practices
-
-=over 4
-
-=item Declaring C<@EXPORT_OK> and Friends
-
-=item Playing Safe
-
-=item What not to Export
-
-=back
-
-=item SEE ALSO
-
-=item LICENSE
-
-=back
-
-=head2 Exporter::Heavy - Exporter guts
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 ExtUtils::CBuilder - Compile and link C code for Perl modules
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-new, have_compiler, have_cplusplus, compile, C<object_file>,
-C<include_dirs>, C<extra_compiler_flags>, C<C++>, link, lib_file,
-module_name, extra_linker_flags, link_executable, exe_file, object_file,
-lib_file, exe_file, prelink, need_prelink, extra_link_args_after_prelink
-
-=item TO DO
-
-=item HISTORY
-
-=item SUPPORT
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 ExtUtils::CBuilder::Platform::Windows - Builder class for Windows
-platforms
-
-=over 4
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 ExtUtils::Command - utilities to replace common UNIX commands in
-Makefiles etc.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item FUNCTIONS
-
-=back
-
-=back
-
-cat
-
-eqtime
-
-rm_rf
-
-rm_f
-
-touch
-
-mv
-
-cp
-
-chmod
-
-mkpath
-
-test_f
-
-test_d
-
-dos2unix
-
-=over 4
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 ExtUtils::Command::MM - Commands for the MM's to use in Makefiles
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-B<test_harness>
-
-=back
-
-B<pod2man>
-
-B<warn_if_old_packlist>
-
-B<perllocal_install>
-
-B<uninstall>
-
-=head2 ExtUtils::Constant - generate XS code to import C header constants
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item USAGE
-
-IV, UV, NV, PV, PVN, SV, YES, NO, UNDEF
-
-=item FUNCTIONS
-
-=back
-
-constant_types
-
-XS_constant PACKAGE, TYPES, XS_SUBNAME, C_SUBNAME
-
-autoload PACKAGE, VERSION, AUTOLOADER
-
-WriteMakefileSnippet
-
-WriteConstants ATTRIBUTE =E<gt> VALUE [, ...], NAME, DEFAULT_TYPE,
-BREAKOUT_AT, NAMES, PROXYSUBS, C_FH, C_FILE, XS_FH, XS_FILE, XS_SUBNAME,
-C_SUBNAME
-
-=over 4
-
-=item AUTHOR
-
-=back
-
-=head2 ExtUtils::Constant::Base - base class for ExtUtils::Constant objects
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item USAGE
-
-=back
-
-header
-
-memEQ_clause args_hashref
-
-dump_names arg_hashref, ITEM..
-
-assign arg_hashref, VALUE..
-
-return_clause arg_hashref, ITEM
-
-switch_clause arg_hashref, NAMELEN, ITEMHASH, ITEM..
-
-params WHAT
-
-dogfood arg_hashref, ITEM..
-
-normalise_items args, default_type, seen_types, seen_items, ITEM..
-
-C_constant arg_hashref, ITEM.., name, type, value, macro, default, pre,
-post, def_pre, def_post, utf8, weight
-
-=over 4
-
-=item BUGS
-
-=item AUTHOR
-
-=back
-
-=head2 ExtUtils::Constant::Utils - helper functions for ExtUtils::Constant
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item USAGE
-
-C_stringify NAME
-
-=back
-
-perl_stringify NAME
-
-=over 4
-
-=item AUTHOR
-
-=back
-
-=head2 ExtUtils::Constant::XS - generate C code for XS modules' constants.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item BUGS
-
-=item AUTHOR
-
-=back
-
-=head2 ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item @EXPORT
-
-=item FUNCTIONS
-
-xsinit(), Examples, ldopts(), Examples, perl_inc(), ccflags(), ccdlflags(),
-ccopts(), xsi_header(), xsi_protos(@modules), xsi_body(@modules)
-
-=item EXAMPLES
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 ExtUtils::Install - install files from here to there
-
-=over 4
-
-=item SYNOPSIS
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-_chmod($$;$), _warnonce(@), _choke(@)
-
-=back
-
-_move_file_at_boot( $file, $target, $moan )
-
-_unlink_or_rename( $file, $tryhard, $installing )
-
-=over 4
-
-=item Functions
-
-_get_install_skip
-
-=back
-
-_have_write_access
-
-_can_write_dir(C<$dir>)
-
-_mkpath($dir,$show,$mode,$verbose,$dry_run)
-
-_copy($from,$to,$verbose,$dry_run)
-
-_chdir($from)
-
-B<install>
-
-_do_cleanup
-
-install_rooted_file( $file ), install_rooted_dir( $dir )
-
-forceunlink( $file, $tryhard )
-
-directory_not_empty( $dir )
-
-B<install_default> I<DISCOURAGED>
-
-B<uninstall>
-
-inc_uninstall($filepath,$libdir,$verbose,$dry_run,$ignore,$results)
-
-run_filter($cmd,$src,$dest)
-
-B<pm_to_blib>
-
-_autosplit
-
-_invokant
-
-=over 4
-
-=item ENVIRONMENT
-
-B<PERL_INSTALL_ROOT>, B<EU_INSTALL_IGNORE_SKIP>,
-B<EU_INSTALL_SITE_SKIPFILE>, B<EU_INSTALL_ALWAYS_COPY>
-
-=item AUTHOR
-
-=item LICENSE
-
-=back
-
-=head2 ExtUtils::Installed - Inventory management of installed modules
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item USAGE
-
-=item METHODS
-
-new(), modules(), files(), directories(), directory_tree(), validate(),
-packlist(), version()
-
-=item EXAMPLE
-
-=item AUTHOR
-
-=back
-
-=head2 ExtUtils::Liblist - determine libraries to use and how to use them
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-For static extensions, For dynamic extensions at build/link time, For
-dynamic extensions at load time
-
-=over 4
-
-=item EXTRALIBS
-
-=item LDLOADLIBS and LD_RUN_PATH
-
-=item BSLOADLIBS
-
-=back
-
-=item PORTABILITY
-
-=over 4
-
-=item VMS implementation
-
-=item Win32 implementation
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 ExtUtils::MM - OS adjusted ExtUtils::MakeMaker subclass
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 ExtUtils::MM_AIX - AIX specific subclass of ExtUtils::MM_Unix
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Overridden methods
-
-=back
-
-=back
-
-=over 4
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 ExtUtils::MM_Any - Platform-agnostic MM methods
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Cross-platform helper methods
-
-=back
-
-=back
-
-=over 4
-
-=item Targets
-
-=back
-
-=over 4
-
-=item Init methods
-
-=back
-
-=over 4
-
-=item Tools
-
-=back
-
-=over 4
-
-=item File::Spec wrappers
-
-=back
-
-=over 4
-
-=item Misc
-
-=back
-
-=over 4
-
-=item AUTHOR
-
-=back
-
-=head2 ExtUtils::MM_BeOS - methods to override UN*X behaviour in
-ExtUtils::MakeMaker
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-os_flavor
-
-init_linker
-
-=head2 ExtUtils::MM_Cygwin - methods to override UN*X behaviour in
-ExtUtils::MakeMaker
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-os_flavor
-
-=back
-
-cflags
-
-replace_manpage_separator
-
-init_linker
-
-maybe_command
-
-dynamic_lib
-
-all_target
-
-=head2 ExtUtils::MM_DOS - DOS specific subclass of ExtUtils::MM_Unix
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Overridden methods
-
-os_flavor
-
-=back
-
-=back
-
-B<replace_manpage_separator>
-
-=over 4
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 ExtUtils::MM_Darwin - special behaviors for OS X
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Overriden Methods
-
-=back
-
-=back
-
-=head2 ExtUtils::MM_MacOS - once produced Makefiles for MacOS Classic
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 ExtUtils::MM_NW5 - methods to override UN*X behaviour in
-ExtUtils::MakeMaker
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-os_flavor
-
-init_platform, platform_constants
-
-const_cccmd
-
-static_lib
-
-dynamic_lib
-
-=head2 ExtUtils::MM_OS2 - methods to override UN*X behaviour in
-ExtUtils::MakeMaker
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-init_dist
-
-=back
-
-init_linker
-
-os_flavor
-
-=head2 ExtUtils::MM_QNX - QNX specific subclass of ExtUtils::MM_Unix
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Overridden methods
-
-=back
-
-=back
-
-=over 4
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 ExtUtils::MM_UWIN - U/WIN specific subclass of ExtUtils::MM_Unix
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Overridden methods
-
-os_flavor
-
-=back
-
-=back
-
-B<replace_manpage_separator>
-
-=over 4
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 ExtUtils::MM_Unix - methods used by ExtUtils::MakeMaker
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=back
-
-=over 4
-
-=item Methods
-
-os_flavor
-
-=back
-
-c_o (o)
-
-cflags (o)
-
-const_cccmd (o)
-
-const_config (o)
-
-const_loadlibs (o)
-
-constants (o)
-
-depend (o)
-
-init_DEST
-
-init_dist
-
-dist (o)
-
-dist_basics (o)
-
-dist_ci (o)
-
-dist_core (o)
-
-B<dist_target>
-
-B<tardist_target>
-
-B<zipdist_target>
-
-B<tarfile_target>
-
-zipfile_target
-
-uutardist_target
-
-shdist_target
-
-dlsyms (o)
-
-dynamic_bs (o)
-
-dynamic_lib (o)
-
-exescan
-
-extliblist
-
-find_perl
-
-fixin
-
-force (o)
-
-guess_name
-
-has_link_code
-
-init_dirscan
-
-init_MANPODS
-
-init_MAN1PODS
-
-init_MAN3PODS
-
-init_PM
-
-init_DIRFILESEP
-
-init_main
-
-init_tools
-
-init_linker
-
-init_lib2arch
-
-init_PERL
-
-init_platform, platform_constants
-
-init_PERM
-
-init_xs
-
-install (o)
-
-installbin (o)
-
-linkext (o)
-
-lsdir
-
-macro (o)
-
-makeaperl (o)
-
-makefile (o)
-
-maybe_command
-
-needs_linking (o)
-
-parse_abstract
-
-parse_version
-
-pasthru (o)
-
-perl_script
-
-perldepend (o)
-
-pm_to_blib
-
-post_constants (o)
-
-post_initialize (o)
-
-postamble (o)
-
-ppd
-
-prefixify
-
-processPL (o)
-
-quote_paren
-
-replace_manpage_separator
-
-cd
-
-oneliner
-
-quote_literal
-
-escape_newlines
-
-max_exec_len
-
-static (o)
-
-static_lib (o)
-
-staticmake (o)
-
-subdir_x (o)
-
-subdirs (o)
-
-test (o)
-
-test_via_harness (override)
-
-test_via_script (override)
-
-tool_xsubpp (o)
-
-all_target
-
-top_targets (o)
-
-writedoc
-
-xs_c (o)
-
-xs_cpp (o)
-
-xs_o (o)
-
-=over 4
-
-=item SEE ALSO
-
-=back
-
-=head2 ExtUtils::MM_VMS - methods to override UN*X behaviour in
-ExtUtils::MakeMaker
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Methods always loaded
-
-wraplist
-
-=back
-
-=back
-
-=over 4
-
-=item Methods
-
-guess_name (override)
-
-=back
-
-find_perl (override)
-
-_fixin_replace_shebang (override)
-
-maybe_command (override)
-
-pasthru (override)
-
-pm_to_blib (override)
-
-perl_script (override)
-
-replace_manpage_separator
-
-init_DEST
-
-init_DIRFILESEP
-
-init_main (override)
-
-init_tools (override)
-
-init_others (override)
-
-init_platform (override)
-
-platform_constants
-
-init_VERSION (override)
-
-constants (override)
-
-special_targets
-
-cflags (override)
-
-const_cccmd (override)
-
-tools_other (override)
-
-init_dist (override)
-
-c_o (override)
-
-xs_c (override)
-
-xs_o (override)
-
-dlsyms (override)
-
-dynamic_lib (override)
-
-static_lib (override)
-
-extra_clean_files
-
-zipfile_target, tarfile_target, shdist_target
-
-install (override)
-
-perldepend (override)
-
-makeaperl (override)
-
-maketext_filter (override)
-
-prefixify (override)
-
-cd
-
-oneliner
-
-B<echo>
-
-quote_literal
-
-escape_dollarsigns
-
-escape_all_dollarsigns
-
-escape_newlines
-
-max_exec_len
-
-init_linker
-
-catdir (override), catfile (override)
-
-eliminate_macros
-
-fixpath
-
-os_flavor
-
-=over 4
-
-=item AUTHOR
-
-=back
-
-=head2 ExtUtils::MM_VOS - VOS specific subclass of ExtUtils::MM_Unix
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Overridden methods
-
-=back
-
-=back
-
-=over 4
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 ExtUtils::MM_Win32 - methods to override UN*X behaviour in
-ExtUtils::MakeMaker
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item Overridden methods
-
-B<dlsyms>
-
-=back
-
-replace_manpage_separator
-
-B<maybe_command>
-
-B<init_DIRFILESEP>
-
-init_tools
-
-init_others
-
-init_platform, platform_constants
-
-constants
-
-special_targets
-
-static_lib
-
-dynamic_lib
-
-extra_clean_files
-
-init_linker
-
-perl_script
-
-xs_o
-
-pasthru
-
-arch_check (override)
-
-oneliner
-
-cd
-
-max_exec_len
-
-os_flavor
-
-cflags
-
-=head2 ExtUtils::MM_Win95 - method to customize MakeMaker for Win9X
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Overridden methods
-
-xs_c
-
-=back
-
-=back
-
-xs_cpp
-
-xs_o
-
-max_exec_len
-
-os_flavor
-
-=over 4
-
-=item AUTHOR
-
-=back
-
-=head2 ExtUtils::MY - ExtUtils::MakeMaker subclass for customization
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 ExtUtils::MakeMaker - Create a module Makefile
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item How To Write A Makefile.PL
-
-=item Default Makefile Behaviour
-
-=item make test
-
-=item make testdb
-
-=item make install
-
-=item INSTALL_BASE
-
-=item PREFIX and LIB attribute
-
-=item AFS users
-
-=item Static Linking of a new Perl Binary
-
-=item Determination of Perl Library and Installation Locations
-
-=item Which architecture dependent directory?
-
-=item Using Attributes and Parameters
-
-ABSTRACT, ABSTRACT_FROM, AUTHOR, BINARY_LOCATION, BUILD_REQUIRES, C,
-CCFLAGS, CONFIG, CONFIGURE, CONFIGURE_REQUIRES, DEFINE, DESTDIR, DIR,
-DISTNAME, DISTVNAME, DL_FUNCS, DL_VARS, EXCLUDE_EXT, EXE_FILES,
-FIRST_MAKEFILE, FULLPERL, FULLPERLRUN, FULLPERLRUNINST, FUNCLIST, H,
-IMPORTS, INC, INCLUDE_EXT, INSTALLARCHLIB, INSTALLBIN, INSTALLDIRS,
-INSTALLMAN1DIR, INSTALLMAN3DIR, INSTALLPRIVLIB, INSTALLSCRIPT,
-INSTALLSITEARCH, INSTALLSITEBIN, INSTALLSITELIB, INSTALLSITEMAN1DIR,
-INSTALLSITEMAN3DIR, INSTALLSITESCRIPT, INSTALLVENDORARCH, INSTALLVENDORBIN,
-INSTALLVENDORLIB, INSTALLVENDORMAN1DIR, INSTALLVENDORMAN3DIR,
-INSTALLVENDORSCRIPT, INST_ARCHLIB, INST_BIN, INST_LIB, INST_MAN1DIR,
-INST_MAN3DIR, INST_SCRIPT, LD, LDDLFLAGS, LDFROM, LIB, LIBPERL_A, LIBS,
-LICENSE, LINKTYPE, MAKE, MAKEAPERL, MAKEFILE_OLD, MAN1PODS, MAN3PODS,
-MAP_TARGET, META_ADD, META_MERGE, MIN_PERL_VERSION, MYEXTLIB, NAME,
-NEEDS_LINKING, NOECHO, NORECURS, NO_META, NO_MYMETA, NO_VC, OBJECT,
-OPTIMIZE, PERL, PERL_CORE, PERLMAINCC, PERL_ARCHLIB, PERL_LIB,
-PERL_MALLOC_OK, PERLPREFIX, PERLRUN, PERLRUNINST, PERL_SRC, PERM_DIR,
-PERM_RW, PERM_RWX, PL_FILES, PM, PMLIBDIRS, PM_FILTER, POLLUTE,
-PPM_INSTALL_EXEC, PPM_INSTALL_SCRIPT, PREFIX, PREREQ_FATAL, PREREQ_PM,
-PREREQ_PRINT, PRINT_PREREQ, SITEPREFIX, SIGN, SKIP, TYPEMAPS, VENDORPREFIX,
-VERBINST, VERSION, VERSION_FROM, VERSION_SYM, XS, XSOPT, XSPROTOARG,
-XS_VERSION
-
-=item Additional lowercase attributes
-
-clean, depend, dist, dynamic_lib, linkext, macro, postamble, realclean,
-test, tool_autosplit
-
-=item Overriding MakeMaker Methods
-
-=item The End Of Cargo Cult Programming
-
-C<< MAN3PODS => ' ' >>
-
-=item Hintsfile support
-
-=item Distribution Support
-
- make distcheck, make skipcheck, make distclean, make manifest,
- make distdir, make disttest, make tardist, make dist, make
-uutardist, make shdist, make zipdist, make ci
-
-=item Module Meta-Data (META and MYMETA)
-
-=item Disabling an extension
-
-=item Other Handy Functions
-
-prompt
-
-=back
-
-=item ENVIRONMENT
-
-PERL_MM_OPT, PERL_MM_USE_DEFAULT, PERL_CORE
-
-=item SEE ALSO
-
-=item AUTHORS
-
-=item LICENSE
-
-=back
-
-=head2 ExtUtils::MakeMaker::Config - Wrapper around Config.pm
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About
-MakeMaker
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Module Installation
-
-How do I install a module into my home directory?, How do I get MakeMaker
-and Module::Build to install to the same place?, How do I keep from
-installing man pages?, How do I use a module without installing it?, PREFIX
-vs INSTALL_BASE from Module::Build::Cookbook
-
-=item Philosophy and History
-
-Why not just use <insert other build config tool here>?, What is
-Module::Build and how does it relate to MakeMaker?, pure perl. no make, no
-shell commands, easier to customize, cleaner internals, less cruft
-
-=item Module Writing
-
-How do I keep my $VERSION up to date without resetting it manually?, What's
-this F<META.yml> thing and how did it get in my F<MANIFEST>?!, How do I
-delete everything not in my F<MANIFEST>?, Which tar should I use on
-Windows?, Which zip should I use on Windows for '[nd]make zipdist'?
-
-=item XS
-
-How to I prevent "object version X.XX does not match bootstrap parameter
-Y.YY" errors?, How do I make two or more XS files coexist in the same
-directory?
-
-=back
-
-=item PATCHING
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 ExtUtils::MakeMaker::Tutorial - Writing a module with MakeMaker
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item The Mantra
-
-=item The Layout
-
-Makefile.PL, MANIFEST, lib/, t/, Changes, README, INSTALL, MANIFEST.SKIP,
-bin/
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 ExtUtils::Manifest - utilities to write and check a MANIFEST file
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Functions
-
-mkmanifest
-
-=back
-
-=back
-
-manifind
-
-manicheck
-
-filecheck
-
-fullcheck
-
-skipcheck
-
-maniread
-
-maniskip
-
-manicopy
-
-maniadd
-
-=over 4
-
-=item MANIFEST
-
-=item MANIFEST.SKIP
-
-#!include_default, #!include /Path/to/another/manifest.skip
-
-=item EXPORT_OK
-
-=item GLOBAL VARIABLES
-
-=back
-
-=over 4
-
-=item DIAGNOSTICS
-
-C<Not in MANIFEST:> I<file>, C<Skipping> I<file>, C<No such file:> I<file>,
-C<MANIFEST:> I<$!>, C<Added to MANIFEST:> I<file>
-
-=item ENVIRONMENT
-
-B<PERL_MM_MANIFEST_DEBUG>
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 ExtUtils::Miniperl, writemain - write the C code for perlmain.c
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=back
-
-=head2 ExtUtils::Mkbootstrap - make a bootstrap file for use by DynaLoader
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 ExtUtils::Mksymlists - write linker options files for dynamic
-extension
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-DLBASE, DL_FUNCS, DL_VARS, FILE, FUNCLIST, IMPORTS, NAME
-
-=item AUTHOR
-
-=item REVISION
-
-mkfh()
-
-=back
-
-__find_relocations
-
-=head2 ExtUtils::Packlist - manage .packlist files
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item USAGE
-
-=item FUNCTIONS
-
-new(), read(), write(), validate(), packlist_file()
-
-=item EXAMPLE
-
-=item AUTHOR
-
-=back
-
-=head2 ExtUtils::ParseXS - converts Perl XS code into C code
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item EXPORT
-
-=item FUNCTIONS
-
-process_file(), B<C++>, B<hiertype>, B<except>, B<typemap>, B<prototypes>,
-B<versioncheck>, B<linenumbers>, B<optimize>, B<inout>, B<argtypes>, B<s>,
-errors()
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 ExtUtils::ParseXS::Constants - Initialization values for some
-globals
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 ExtUtils::ParseXS::Utilities - Subroutines used with
-ExtUtils::ParseXS
-
-=over 4
-
-=item SYNOPSIS
-
-=item SUBROUTINES
-
-=over 4
-
-=item C<standard_typemap_locations()>
-
-Purpose, Arguments, Return Value
-
-=back
-
-=back
-
-=over 4
-
-=item C<trim_whitespace()>
-
-Purpose, Argument, Return Value
-
-=back
-
-=over 4
-
-=item C<tidy_type()>
-
-Purpose, Arguments, Return Value
-
-=back
-
-=over 4
-
-=item C<C_string()>
-
-Purpose, Arguments, Return Value
-
-=back
-
-=over 4
-
-=item C<valid_proto_string()>
-
-Purpose, Arguments, Return Value
-
-=back
-
-=over 4
-
-=item C<process_typemaps()>
-
-Purpose, Arguments, Return Value
-
-=back
-
-=over 4
-
-=item C<make_targetable()>
-
-Purpose, Arguments, Return Value
-
-=back
-
-=over 4
-
-=item C<map_type()>
-
-Purpose, Arguments, Return Value
-
-=back
-
-=over 4
-
-=item C<standard_XS_defs()>
-
-Purpose, Arguments, Return Value
-
-=back
-
-=over 4
-
-=item C<assign_func_args()>
-
-Purpose, Arguments, Return Value
-
-=back
-
-=over 4
-
-=item C<analyze_preprocessor_statements()>
-
-Purpose, Arguments, Return Value
-
-=back
-
-=over 4
-
-=item C<set_cond()>
-
-Purpose, Arguments, Return Value
-
-=back
-
-=over 4
-
-=item C<current_line_number()>
-
-Purpose, Arguments, Return Value
-
-=back
-
-=over 4
-
-=item C<Warn()>
-
-Purpose, Arguments, Return Value
-
-=back
-
-=over 4
-
-=item C<blurt()>
-
-Purpose, Arguments, Return Value
-
-=back
-
-=over 4
-
-=item C<death()>
-
-Purpose, Arguments, Return Value
-
-=back
-
-=over 4
-
-=item C<check_conditional_preprocessor_statements()>
-
-Purpose, Arguments, Return Value
-
-=back
-
-=over 4
-
-=item C<escape_file_for_line_directive()>
-
-Purpose, Arguments, Return Value
-
-=back
-
-=over 4
-
-=item C<report_typemap_failure>
-
-Purpose, Arguments, Return Value
-
-=back
-
-=head2 ExtUtils::Typemaps - Read/Write/Modify Perl/XS typemap files
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=back
-
-=over 4
-
-=item new
-
-=back
-
-=over 4
-
-=item file
-
-=back
-
-=over 4
-
-=item add_typemap
-
-=back
-
-=over 4
-
-=item add_inputmap
-
-=back
-
-=over 4
-
-=item add_outputmap
-
-=back
-
-=over 4
-
-=item add_string
-
-=back
-
-=over 4
-
-=item remove_typemap
-
-=back
-
-=over 4
-
-=item remove_inputmap
-
-=back
-
-=over 4
-
-=item remove_inputmap
-
-=back
-
-=over 4
-
-=item get_typemap
-
-=back
-
-=over 4
-
-=item get_inputmap
-
-=back
-
-=over 4
-
-=item get_outputmap
-
-=back
-
-=over 4
-
-=item write
-
-=back
-
-=over 4
-
-=item as_string
-
-=back
-
-=over 4
-
-=item as_embedded_typemap
-
-=back
-
-=over 4
-
-=item merge
-
-=back
-
-=over 4
-
-=item is_empty
-
-=back
-
-=over 4
-
-=item list_mapped_ctypes
-
-=back
-
-=over 4
-
-=item _get_typemap_hash
-
-=back
-
-=over 4
-
-=item _get_inputmap_hash
-
-=back
-
-=over 4
-
-=item _get_outputmap_hash
-
-=back
-
-=over 4
-
-=item _get_prototype_hash
-
-=back
-
-=over 4
-
-=item CAVEATS
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT & LICENSE
-
-=back
-
-=head2 ExtUtils::Typemaps::Cmd - Quick commands for handling typemaps
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item EXPORTED FUNCTIONS
-
-=over 4
-
-=item embeddable_typemap
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT & LICENSE
-
-=back
-
-=head2 ExtUtils::Typemaps::InputMap - Entry in the INPUT section of a
-typemap
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=back
-
-=over 4
-
-=item new
-
-=back
-
-=over 4
-
-=item code
-
-=back
-
-=over 4
-
-=item xstype
-
-=back
-
-=over 4
-
-=item cleaned_code
-
-=back
-
-=over 4
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT & LICENSE
-
-=back
-
-=head2 ExtUtils::Typemaps::OutputMap - Entry in the OUTPUT section of a
-typemap
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=back
-
-=over 4
-
-=item new
-
-=back
-
-=over 4
-
-=item code
-
-=back
-
-=over 4
-
-=item xstype
-
-=back
-
-=over 4
-
-=item cleaned_code
-
-=back
-
-=over 4
-
-=item targetable
-
-=back
-
-=over 4
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT & LICENSE
-
-=back
-
-=head2 ExtUtils::Typemaps::Type - Entry in the TYPEMAP section of a typemap
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=back
-
-=over 4
-
-=item new
-
-=back
-
-=over 4
-
-=item proto
-
-=back
-
-=over 4
-
-=item xstype
-
-=back
-
-=over 4
-
-=item ctype
-
-=back
-
-=over 4
-
-=item tidy_ctype
-
-=back
-
-=over 4
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT & LICENSE
-
-=back
-
-=head2 ExtUtils::XSSymSet - keep sets of symbol names palatable to the VMS
-linker
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-new([$maxlen[,$silent]]), addsym($name[,$maxlen[,$silent]]),
-trimsym($name[,$maxlen[,$silent]]), delsym($name), get_orig($trimmed),
-get_trimmed($name), all_orig(), all_trimmed()
-
-=item AUTHOR
-
-=item REVISION
-
-=back
-
-=head2 ExtUtils::testlib - add blib/* directories to @INC
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 Fatal - Replace functions with equivalents which succeed or die
-
-=over 4
-
-=item SYNOPSIS
-
-=item BEST PRACTICE
-
-=item DESCRIPTION
-
-=item DIAGNOSTICS
-
-Bad subroutine name for Fatal: %s, %s is not a Perl subroutine, %s is
-neither a builtin, nor a Perl subroutine, Cannot make the non-overridable
-%s fatal, Internal error: %s
-
-=item BUGS
-
-=item AUTHOR
-
-=item LICENSE
-
-=item SEE ALSO
-
-=back
-
-=head2 Fcntl - load the C Fcntl.h defines
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item NOTE
-
-=item EXPORTED SYMBOLS
-
-=back
-
-=head2 File::Basename - Parse file paths into directory, filename and
-suffix.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-C<fileparse> X<fileparse>
-
-C<basename> X<basename> X<filename>
-
-C<dirname> X<dirname>
-
-C<fileparse_set_fstype> X<filesystem>
-
-=over 4
-
-=item SEE ALSO
-
-=back
-
-=head2 File::CheckTree - run many filetest checks on a tree
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=item HISTORY
-
-=back
-
-=head2 File::Compare - Compare files or filehandles
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item RETURN
-
-=item AUTHOR
-
-=back
-
-=head2 File::Copy - Copy files or filehandles
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-copy X<copy> X<cp>, move X<move> X<mv> X<rename>, syscopy X<syscopy>,
-rmscopy($from,$to[,$date_flag]) X<rmscopy>
-
-=item RETURN
-
-=item AUTHOR
-
-=back
-
-=head2 File::DosGlob - DOS like globbing and then some
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item EXPORTS (by request only)
-
-=item BUGS
-
-=item AUTHOR
-
-=item HISTORY
-
-=item SEE ALSO
-
-=back
-
-=head2 File::Fetch - A generic file fetching mechanism
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item ACCESSORS
-
-$ff->uri, $ff->scheme, $ff->host, $ff->vol, $ff->share, $ff->path,
-$ff->file
-
-=back
-
-$ff->output_file
-
-=over 4
-
-=item METHODS
-
-=over 4
-
-=item $ff = File::Fetch->new( uri => 'http://some.where.com/dir/file.txt'
-);
-
-=back
-
-=back
-
-=over 4
-
-=item $where = $ff->fetch( [to => /my/output/dir/ | \$scalar] )
-
-=back
-
-=over 4
-
-=item $ff->error([BOOL])
-
-=back
-
-=over 4
-
-=item HOW IT WORKS
-
-=item GLOBAL VARIABLES
-
-=over 4
-
-=item $File::Fetch::FROM_EMAIL
-
-=item $File::Fetch::USER_AGENT
-
-=item $File::Fetch::FTP_PASSIVE
-
-=item $File::Fetch::TIMEOUT
-
-=item $File::Fetch::WARN
-
-=item $File::Fetch::DEBUG
-
-=item $File::Fetch::BLACKLIST
-
-=item $File::Fetch::METHOD_FAIL
-
-=back
-
-=item MAPPING
-
-=item FREQUENTLY ASKED QUESTIONS
-
-=over 4
-
-=item So how do I use a proxy with File::Fetch?
-
-=item I used 'lynx' to fetch a file, but its contents is all wrong!
-
-=item Files I'm trying to fetch have reserved characters or non-ASCII
-characters in them. What do I do?
-
-=back
-
-=item TODO
-
-Implement $PREFER_BIN
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 File::Find - Traverse a directory tree.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-B<find>, B<finddepth>
-
-=over 4
-
-=item %options
-
-C<wanted>, C<bydepth>, C<preprocess>, C<postprocess>, C<follow>,
-C<follow_fast>, C<follow_skip>, C<dangling_symlinks>, C<no_chdir>,
-C<untaint>, C<untaint_pattern>, C<untaint_skip>
-
-=item The wanted function
-
-C<$File::Find::dir> is the current directory name,, C<$_> is the current
-filename within that directory, C<$File::Find::name> is the complete
-pathname to the file
-
-=back
-
-=item WARNINGS
-
-=item CAVEAT
-
-$dont_use_nlink, symlinks
-
-=item BUGS AND CAVEATS
-
-=item HISTORY
-
-=item SEE ALSO
-
-=back
-
-=head2 File::Glob - Perl extension for BSD glob routine
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item META CHARACTERS
-
-=item EXPORTS
-
-=item POSIX FLAGS
-
-C<GLOB_ERR>, C<GLOB_LIMIT>, C<GLOB_MARK>, C<GLOB_NOCASE>, C<GLOB_NOCHECK>,
-C<GLOB_NOSORT>, C<GLOB_BRACE>, C<GLOB_NOMAGIC>, C<GLOB_QUOTE>,
-C<GLOB_TILDE>, C<GLOB_CSH>, C<GLOB_ALPHASORT>
-
-=back
-
-=item DIAGNOSTICS
-
-C<GLOB_NOSPACE>, C<GLOB_ABEND>
-
-=item NOTES
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 File::GlobMapper - Extend File Glob to Allow Input and Output Files
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Behind The Scenes
-
-=item Limitations
-
-=item Input File Glob
-
-B<~>, B<~user>, B<.>, B<*>, B<?>, B<\>, B<[]>, B<{,}>, B<()>
-
-=item Output File Glob
-
-"*", #1
-
-=item Returned Data
-
-=back
-
-=item EXAMPLES
-
-=over 4
-
-=item A Rename script
-
-=item A few example globmaps
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 File::Path - Create or remove directory trees
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-make_path( $dir1, $dir2, .... ), make_path( $dir1, $dir2, ...., \%opts ),
-mode => $num, verbose => $bool, error => \$err, owner => $owner, user =>
-$owner, uid => $owner, group => $group, mkpath( $dir ), mkpath( $dir,
-$verbose, $mode ), mkpath( [$dir1, $dir2,...], $verbose, $mode ), mkpath(
-$dir1, $dir2,..., \%opt ), remove_tree( $dir1, $dir2, .... ), remove_tree(
-$dir1, $dir2, ...., \%opts ), verbose => $bool, safe => $bool, keep_root =>
-$bool, result => \$res, error => \$err, rmtree( $dir ), rmtree( $dir,
-$verbose, $safe ), rmtree( [$dir1, $dir2,...], $verbose, $safe ), rmtree(
-$dir1, $dir2,..., \%opt )
-
-=over 4
-
-=item ERROR HANDLING
-
-B<NOTE:>
-
-=item NOTES
-
-=back
-
-=item DIAGNOSTICS
-
-mkdir [path]: [errmsg] (SEVERE), No root path(s) specified, No such file or
-directory, cannot fetch initial working directory: [errmsg], cannot stat
-initial working directory: [errmsg], cannot chdir to [dir]: [errmsg],
-directory [dir] changed before chdir, expected dev=[n] ino=[n], actual
-dev=[n] ino=[n], aborting. (FATAL), cannot make directory [dir]
-read+writeable: [errmsg], cannot read [dir]: [errmsg], cannot reset chmod
-[dir]: [errmsg], cannot remove [dir] when cwd is [dir], cannot chdir to
-[parent-dir] from [child-dir]: [errmsg], aborting. (FATAL), cannot stat
-prior working directory [dir]: [errmsg], aborting. (FATAL), previous
-directory [parent-dir] changed before entering [child-dir], expected
-dev=[n] ino=[n], actual dev=[n] ino=[n], aborting. (FATAL), cannot make
-directory [dir] writeable: [errmsg], cannot remove directory [dir]:
-[errmsg], cannot restore permissions of [dir] to [0nnn]: [errmsg], cannot
-make file [file] writeable: [errmsg], cannot unlink file [file]: [errmsg],
-cannot restore permissions of [file] to [0nnn]: [errmsg], unable to map
-[owner] to a uid, ownership not changed");, unable to map [group] to a gid,
-group ownership not changed
-
-=item SEE ALSO
-
-=item BUGS
-
-=item ACKNOWLEDGEMENTS
-
-=item AUTHORS
-
-=item COPYRIGHT
-
-=item LICENSE
-
-=back
-
-=head2 File::Spec - portably perform operations on file names
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-canonpath X<canonpath>, catdir X<catdir>, catfile X<catfile>, curdir
-X<curdir>, devnull X<devnull>, rootdir X<rootdir>, tmpdir X<tmpdir>, updir
-X<updir>, no_upwards, case_tolerant, file_name_is_absolute, path X<path>,
-join X<join, path>, splitpath X<splitpath> X<split, path>, splitdir
-X<splitdir> X<split, dir>, catpath(), abs2rel X<abs2rel> X<absolute, path>
-X<relative, path>, rel2abs() X<rel2abs> X<absolute, path> X<relative, path>
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 File::Spec::Cygwin - methods for Cygwin file specs
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-canonpath
-
-file_name_is_absolute
-
-tmpdir (override)
-
-case_tolerant
-
-=over 4
-
-=item COPYRIGHT
-
-=back
-
-=head2 File::Spec::Epoc - methods for Epoc file specs
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-canonpath()
-
-=over 4
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 File::Spec::Functions - portably perform operations on file names
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Exports
-
-=back
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 File::Spec::Mac - File::Spec for Mac OS (Classic)
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-canonpath
-
-=back
-
-catdir()
-
-catfile
-
-curdir
-
-devnull
-
-rootdir
-
-tmpdir
-
-updir
-
-file_name_is_absolute
-
-path
-
-splitpath
-
-splitdir
-
-catpath
-
-abs2rel
-
-rel2abs
-
-=over 4
-
-=item AUTHORS
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 File::Spec::OS2 - methods for OS/2 file specs
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-tmpdir, splitpath
-
-=item COPYRIGHT
-
-=back
-
-=head2 File::Spec::Unix - File::Spec for Unix, base for other File::Spec
-modules
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-canonpath()
-
-=back
-
-catdir()
-
-catfile
-
-curdir
-
-devnull
-
-rootdir
-
-tmpdir
-
-updir
-
-no_upwards
-
-case_tolerant
-
-file_name_is_absolute
-
-path
-
-join
-
-splitpath
-
-splitdir
-
-catpath()
-
-abs2rel
-
-rel2abs()
-
-=over 4
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 File::Spec::VMS - methods for VMS file specs
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-canonpath (override)
-
-catdir (override)
-
-catfile (override)
-
-curdir (override)
-
-devnull (override)
-
-rootdir (override)
-
-tmpdir (override)
-
-updir (override)
-
-case_tolerant (override)
-
-path (override)
-
-file_name_is_absolute (override)
-
-splitpath (override)
-
-splitdir (override)
-
-catpath (override)
-
-abs2rel (override)
-
-rel2abs (override)
-
-=over 4
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 File::Spec::Win32 - methods for Win32 file specs
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-devnull
-
-=back
-
-tmpdir
-
-case_tolerant
-
-file_name_is_absolute
-
-catfile
-
-canonpath
-
-splitpath
-
-splitdir
-
-catpath
-
-=over 4
-
-=item Note For File::Spec::Win32 Maintainers
-
-=back
-
-=over 4
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 File::Temp - return name and handle of a temporary file safely
-
-=over 4
-
-=item PORTABILITY
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item OBJECT-ORIENTED INTERFACE
-
-B<new>
-
-=back
-
-B<newdir>
-
-B<filename>
-
-B<dirname>, B<unlink_on_destroy>
-
-B<DESTROY>
-
-=over 4
-
-=item FUNCTIONS
-
-B<tempfile>
-
-=back
-
-B<tempdir>
-
-=over 4
-
-=item MKTEMP FUNCTIONS
-
-B<mkstemp>
-
-=back
-
-B<mkstemps>
-
-B<mkdtemp>
-
-B<mktemp>
-
-=over 4
-
-=item POSIX FUNCTIONS
-
-B<tmpnam>
-
-=back
-
-B<tmpfile>
-
-=over 4
-
-=item ADDITIONAL FUNCTIONS
-
-B<tempnam>
-
-=back
-
-=over 4
-
-=item UTILITY FUNCTIONS
-
-B<unlink0>
-
-=back
-
-B<cmpstat>
-
-B<unlink1>
-
-B<cleanup>
-
-=over 4
-
-=item PACKAGE VARIABLES
-
-B<safe_level>, STANDARD, MEDIUM, HIGH
-
-=back
-
-TopSystemUID
-
-B<$KEEP_ALL>, B<$DEBUG>
-
-=over 4
-
-=item WARNING
-
-=over 4
-
-=item Temporary files and NFS
-
-=item Forking
-
-=item Directory removal
-
-=item BINMODE
-
-=back
-
-=item HISTORY
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 File::stat - by-name interface to Perl's built-in stat() functions
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item BUGS
-
-=item ERRORS
-
--%s is not implemented on a File::stat object
-
-=item WARNINGS
-
-File::stat ignores use filetest 'access', File::stat ignores VMS ACLs
-
-=item NOTE
-
-=item AUTHOR
-
-=back
-
-=head2 FileCache - keep more files open than the system permits
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-cacheout EXPR, cacheout MODE, EXPR
-
-=item CAVEATS
-
-=item BUGS
-
-=back
-
-=head2 FileHandle - supply object methods for filehandles
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-$fh->print, $fh->printf, $fh->getline, $fh->getlines
-
-=item SEE ALSO
-
-=back
-
-=head2 Filter::Simple - Simplified source filtering
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item The Problem
-
-=item A Solution
-
-=item Disabling or changing <no> behaviour
-
-=item All-in-one interface
-
-=item Filtering only specific components of source code
-
-C<"code">, C<"code_no_comments">, C<"executable">,
-C<"executable_no_comments">, C<"quotelike">, C<"string">, C<"regex">,
-C<"all">
-
-=item Filtering only the code parts of source code
-
-=item Using Filter::Simple with an explicit C<import> subroutine
-
-=item Using Filter::Simple and Exporter together
-
-=item How it works
-
-=back
-
-=item AUTHOR
-
-=item CONTACT
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 Filter::Util::Call - Perl Source Filter Utility Module
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item B<use Filter::Util::Call>
-
-=item B<import()>
-
-=item B<filter() and anonymous sub>
-
-B<$_>, B<$status>, B<filter_read> and B<filter_read_exact>, B<filter_del>
-
-=back
-
-=item EXAMPLES
-
-=over 4
-
-=item Example 1: A simple filter.
-
-=item Example 2: Using the context
-
-=item Example 3: Using the context within the filter
-
-=item Example 4: Using filter_del
-
-=back
-
-=item Filter::Simple
-
-=item AUTHOR
-
-=item DATE
-
-=back
-
-=head2 FindBin - Locate directory of original perl script
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item EXPORTABLE VARIABLES
-
-=item KNOWN ISSUES
-
-=item AUTHORS
-
-=item COPYRIGHT
-
-=back
-
-=head2 Getopt::Long - Extended processing of command line options
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Command Line Options, an Introduction
-
-=item Getting Started with Getopt::Long
-
-=over 4
-
-=item Simple options
-
-=item A little bit less simple options
-
-=item Mixing command line option with other arguments
-
-=item Options with values
-
-=item Options with multiple values
-
-=item Options with hash values
-
-=item User-defined subroutines to handle options
-
-=item Options with multiple names
-
-=item Case and abbreviations
-
-=item Summary of Option Specifications
-
-!, +, s, i, o, f, : I<type> [ I<desttype> ], : I<number> [ I<desttype> ], :
-+ [ I<desttype> ]
-
-=back
-
-=item Advanced Possibilities
-
-=over 4
-
-=item Object oriented interface
-
-=item Thread Safety
-
-=item Documentation and help texts
-
-=item Parsing options from an arbitrary array
-
-=item Parsing options from an arbitrary string
-
-=item Storing options values in a hash
-
-=item Bundling
-
-=item The lonesome dash
-
-=item Argument callback
-
-=back
-
-=item Configuring Getopt::Long
-
-default, posix_default, auto_abbrev, getopt_compat, gnu_compat, gnu_getopt,
-require_order, permute, bundling (default: disabled), bundling_override
-(default: disabled), ignore_case (default: enabled), ignore_case_always
-(default: disabled), auto_version (default:disabled), auto_help
-(default:disabled), pass_through (default: disabled), prefix,
-prefix_pattern, long_prefix_pattern, debug (default: disabled)
-
-=item Exportable Methods
-
-VersionMessage, C<-message>, C<-msg>, C<-exitval>, C<-output>, HelpMessage
-
-=item Return values and Errors
-
-=item Legacy
-
-=over 4
-
-=item Default destinations
-
-=item Alternative option starters
-
-=item Configuration variables
-
-=back
-
-=item Tips and Techniques
-
-=over 4
-
-=item Pushing multiple values in a hash option
-
-=back
-
-=item Troubleshooting
-
-=over 4
-
-=item GetOptions does not return a false result when an option is not
-supplied
-
-=item GetOptions does not split the command line correctly
-
-=item Undefined subroutine &main::GetOptions called
-
-=item How do I put a "-?" option into a Getopt::Long?
-
-=back
-
-=item AUTHOR
-
-=item COPYRIGHT AND DISCLAIMER
-
-=back
-
-=head2 Getopt::Std, getopt, getopts - Process single-character switches
-with switch clustering
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item C<--help> and C<--version>
-
-=back
-
-=head2 HTTP::Tiny - A small, simple, correct HTTP/1.1 client
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item new
-
-=item get|head|put|post|delete
-
-=item post_form
-
-=item mirror
-
-=item request
-
-=item www_form_urlencode
-
-=back
-
-=item LIMITATIONS
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=over 4
-
-=item Bugs / Feature Requests
-
-=item Source Code
-
-=back
-
-=item AUTHORS
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 Hash::Util - A selection of general-utility hash subroutines
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Restricted hashes
-
-B<lock_keys>, B<unlock_keys>
-
-=back
-
-=back
-
-B<lock_keys_plus>
-
-B<lock_value>, B<unlock_value>
-
-B<lock_hash>, B<unlock_hash>
-
-B<lock_hash_recurse>, B<unlock_hash_recurse>
-
-B<hash_unlocked>
-
-B<legal_keys>, B<hidden_keys>, B<all_keys>, B<hash_seed>
-
-B<hv_store>
-
-=over 4
-
-=item Operating on references to hashes.
-
-lock_ref_keys, unlock_ref_keys, lock_ref_keys_plus, lock_ref_value,
-unlock_ref_value, lock_hashref, unlock_hashref, lock_hashref_recurse,
-unlock_hashref_recurse, hash_ref_unlocked, legal_ref_keys, hidden_ref_keys
-
-=back
-
-=over 4
-
-=item CAVEATS
-
-=item BUGS
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Hash::Util::FieldHash - Support for Inside-Out Classes
-
-=over 4
-
-=item SYNOPSIS
-
-=item FUNCTIONS
-
-id, id_2obj, register, idhash, idhashes, fieldhash, fieldhashes
-
-=item DESCRIPTION
-
-=over 4
-
-=item The Inside-out Technique
-
-=item Problems of Inside-out
-
-=item Solutions
-
-=item More Problems
-
-=item The Generic Object
-
-=item How to use Field Hashes
-
-=item Garbage-Collected Hashes
-
-=back
-
-=item EXAMPLES
-
-C<init()>, C<first()>, C<last()>, C<name()>, C<Name_hash>, C<Name_id>,
-C<Name_idhash>, C<Name_id_reg>, C<Name_idhash_reg>, C<Name_fieldhash>
-
-=over 4
-
-=item Example 1
-
-=item Example 2
-
-=back
-
-=item GUTS
-
-=over 4
-
-=item The C<PERL_MAGIC_uvar> interface for hashes
-
-=item Weakrefs call uvar magic
-
-=item How field hashes work
-
-=item Internal function Hash::Util::FieldHash::_fieldhash
-
-=back
-
-=item AUTHOR
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 I18N::Collate - compare 8-bit scalar data according to the current
-locale
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 I18N::LangTags - functions for dealing with RFC3066-style language
-tags
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-the function is_language_tag($lang1)
-
-the function extract_language_tags($whatever)
-
-the function same_language_tag($lang1, $lang2)
-
-the function similarity_language_tag($lang1, $lang2)
-
-the function is_dialect_of($lang1, $lang2)
-
-the function super_languages($lang1)
-
-the function locale2language_tag($locale_identifier)
-
-the function encode_language_tag($lang1)
-
-the function alternate_language_tags($lang1)
-
-the function @langs = panic_languages(@accept_languages)
-
-the function implicate_supers( ...languages... ), the function
-implicate_supers_strictly( ...languages... )
-
-=over 4
-
-=item ABOUT LOWERCASING
-
-=item ABOUT UNICODE PLAINTEXT LANGUAGE TAGS
-
-=item SEE ALSO
-
-=item COPYRIGHT
-
-=item AUTHOR
-
-=back
-
-=head2 I18N::LangTags::Detect - detect the user's language preferences
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item FUNCTIONS
-
-=item ENVIRONMENT
-
-=item SEE ALSO
-
-=item COPYRIGHT
-
-=item AUTHOR
-
-=back
-
-=head2 I18N::LangTags::List -- tags and names for human languages
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item ABOUT LANGUAGE TAGS
-
-=item LIST OF LANGUAGES
-
-{ab} : Abkhazian, {ace} : Achinese, {ach} : Acoli, {ada} : Adangme, {ady} :
-Adyghe, {aa} : Afar, {afh} : Afrihili, {af} : Afrikaans, [{afa} :
-Afro-Asiatic (Other)], {ak} : Akan, {akk} : Akkadian, {sq} : Albanian,
-{ale} : Aleut, [{alg} : Algonquian languages], [{tut} : Altaic (Other)],
-{am} : Amharic, {i-ami} : Ami, [{apa} : Apache languages], {ar} : Arabic,
-{arc} : Aramaic, {arp} : Arapaho, {arn} : Araucanian, {arw} : Arawak, {hy}
-: Armenian, {an} : Aragonese, [{art} : Artificial (Other)], {ast} :
-Asturian, {as} : Assamese, [{ath} : Athapascan languages], [{aus} :
-Australian languages], [{map} : Austronesian (Other)], {av} : Avaric, {ae}
-: Avestan, {awa} : Awadhi, {ay} : Aymara, {az} : Azerbaijani, {ban} :
-Balinese, [{bat} : Baltic (Other)], {bal} : Baluchi, {bm} : Bambara, [{bai}
-: Bamileke languages], {bad} : Banda, [{bnt} : Bantu (Other)], {bas} :
-Basa, {ba} : Bashkir, {eu} : Basque, {btk} : Batak (Indonesia), {bej} :
-Beja, {be} : Belarusian, {bem} : Bemba, {bn} : Bengali, [{ber} : Berber
-(Other)], {bho} : Bhojpuri, {bh} : Bihari, {bik} : Bikol, {bin} : Bini,
-{bi} : Bislama, {bs} : Bosnian, {bra} : Braj, {br} : Breton, {bug} :
-Buginese, {bg} : Bulgarian, {i-bnn} : Bunun, {bua} : Buriat, {my} :
-Burmese, {cad} : Caddo, {car} : Carib, {ca} : Catalan, [{cau} : Caucasian
-(Other)], {ceb} : Cebuano, [{cel} : Celtic (Other)], [{cai} : Central
-American Indian (Other)], {chg} : Chagatai, [{cmc} : Chamic languages],
-{ch} : Chamorro, {ce} : Chechen, {chr} : Cherokee, {chy} : Cheyenne, {chb}
-: Chibcha, {ny} : Chichewa, {zh} : Chinese, {chn} : Chinook Jargon, {chp} :
-Chipewyan, {cho} : Choctaw, {cu} : Church Slavic, {chk} : Chuukese, {cv} :
-Chuvash, {cop} : Coptic, {kw} : Cornish, {co} : Corsican, {cr} : Cree,
-{mus} : Creek, [{cpe} : English-based Creoles and pidgins (Other)], [{cpf}
-: French-based Creoles and pidgins (Other)], [{cpp} : Portuguese-based
-Creoles and pidgins (Other)], [{crp} : Creoles and pidgins (Other)], {hr} :
-Croatian, [{cus} : Cushitic (Other)], {cs} : Czech, {dak} : Dakota, {da} :
-Danish, {dar} : Dargwa, {day} : Dayak, {i-default} : Default (Fallthru)
-Language, {del} : Delaware, {din} : Dinka, {dv} : Divehi, {doi} : Dogri,
-{dgr} : Dogrib, [{dra} : Dravidian (Other)], {dua} : Duala, {nl} : Dutch,
-{dum} : Middle Dutch (ca.1050-1350), {dyu} : Dyula, {dz} : Dzongkha, {efi}
-: Efik, {egy} : Ancient Egyptian, {eka} : Ekajuk, {elx} : Elamite, {en} :
-English, {enm} : Old English (1100-1500), {ang} : Old English
-(ca.450-1100), {i-enochian} : Enochian (Artificial), {myv} : Erzya, {eo} :
-Esperanto, {et} : Estonian, {ee} : Ewe, {ewo} : Ewondo, {fan} : Fang, {fat}
-: Fanti, {fo} : Faroese, {fj} : Fijian, {fi} : Finnish, [{fiu} :
-Finno-Ugrian (Other)], {fon} : Fon, {fr} : French, {frm} : Middle French
-(ca.1400-1600), {fro} : Old French (842-ca.1400), {fy} : Frisian, {fur} :
-Friulian, {ff} : Fulah, {gaa} : Ga, {gd} : Scots Gaelic, {gl} : Gallegan,
-{lg} : Ganda, {gay} : Gayo, {gba} : Gbaya, {gez} : Geez, {ka} : Georgian,
-{de} : German, {gmh} : Middle High German (ca.1050-1500), {goh} : Old High
-German (ca.750-1050), [{gem} : Germanic (Other)], {gil} : Gilbertese, {gon}
-: Gondi, {gor} : Gorontalo, {got} : Gothic, {grb} : Grebo, {grc} : Ancient
-Greek, {el} : Modern Greek, {gn} : Guarani, {gu} : Gujarati, {gwi} :
-Gwich'in, {hai} : Haida, {ht} : Haitian, {ha} : Hausa, {haw} : Hawaiian,
-{he} : Hebrew, {hz} : Herero, {hil} : Hiligaynon, {him} : Himachali, {hi} :
-Hindi, {ho} : Hiri Motu, {hit} : Hittite, {hmn} : Hmong, {hu} : Hungarian,
-{hup} : Hupa, {iba} : Iban, {is} : Icelandic, {io} : Ido, {ig} : Igbo,
-{ijo} : Ijo, {ilo} : Iloko, [{inc} : Indic (Other)], [{ine} : Indo-European
-(Other)], {id} : Indonesian, {inh} : Ingush, {ia} : Interlingua
-(International Auxiliary Language Association), {ie} : Interlingue, {iu} :
-Inuktitut, {ik} : Inupiaq, [{ira} : Iranian (Other)], {ga} : Irish, {mga} :
-Middle Irish (900-1200), {sga} : Old Irish (to 900), [{iro} : Iroquoian
-languages], {it} : Italian, {ja} : Japanese, {jv} : Javanese, {jrb} :
-Judeo-Arabic, {jpr} : Judeo-Persian, {kbd} : Kabardian, {kab} : Kabyle,
-{kac} : Kachin, {kl} : Kalaallisut, {xal} : Kalmyk, {kam} : Kamba, {kn} :
-Kannada, {kr} : Kanuri, {krc} : Karachay-Balkar, {kaa} : Kara-Kalpak, {kar}
-: Karen, {ks} : Kashmiri, {csb} : Kashubian, {kaw} : Kawi, {kk} : Kazakh,
-{kha} : Khasi, {km} : Khmer, [{khi} : Khoisan (Other)], {kho} : Khotanese,
-{ki} : Kikuyu, {kmb} : Kimbundu, {rw} : Kinyarwanda, {ky} : Kirghiz,
-{i-klingon} : Klingon, {kv} : Komi, {kg} : Kongo, {kok} : Konkani, {ko} :
-Korean, {kos} : Kosraean, {kpe} : Kpelle, {kro} : Kru, {kj} : Kuanyama,
-{kum} : Kumyk, {ku} : Kurdish, {kru} : Kurukh, {kut} : Kutenai, {lad} :
-Ladino, {lah} : Lahnda, {lam} : Lamba, {lo} : Lao, {la} : Latin, {lv} :
-Latvian, {lb} : Letzeburgesch, {lez} : Lezghian, {li} : Limburgish, {ln} :
-Lingala, {lt} : Lithuanian, {nds} : Low German, {art-lojban} : Lojban
-(Artificial), {loz} : Lozi, {lu} : Luba-Katanga, {lua} : Luba-Lulua, {lui}
-: Luiseno, {lun} : Lunda, {luo} : Luo (Kenya and Tanzania), {lus} : Lushai,
-{mk} : Macedonian, {mad} : Madurese, {mag} : Magahi, {mai} : Maithili,
-{mak} : Makasar, {mg} : Malagasy, {ms} : Malay, {ml} : Malayalam, {mt} :
-Maltese, {mnc} : Manchu, {mdr} : Mandar, {man} : Mandingo, {mni} :
-Manipuri, [{mno} : Manobo languages], {gv} : Manx, {mi} : Maori, {mr} :
-Marathi, {chm} : Mari, {mh} : Marshall, {mwr} : Marwari, {mas} : Masai,
-[{myn} : Mayan languages], {men} : Mende, {mic} : Micmac, {min} :
-Minangkabau, {i-mingo} : Mingo, [{mis} : Miscellaneous languages], {moh} :
-Mohawk, {mdf} : Moksha, {mo} : Moldavian, [{mkh} : Mon-Khmer (Other)],
-{lol} : Mongo, {mn} : Mongolian, {mos} : Mossi, [{mul} : Multiple
-languages], [{mun} : Munda languages], {nah} : Nahuatl, {nap} : Neapolitan,
-{na} : Nauru, {nv} : Navajo, {nd} : North Ndebele, {nr} : South Ndebele,
-{ng} : Ndonga, {ne} : Nepali, {new} : Newari, {nia} : Nias, [{nic} :
-Niger-Kordofanian (Other)], [{ssa} : Nilo-Saharan (Other)], {niu} : Niuean,
-{nog} : Nogai, {non} : Old Norse, [{nai} : North American Indian], {no} :
-Norwegian, {nb} : Norwegian Bokmal, {nn} : Norwegian Nynorsk, [{nub} :
-Nubian languages], {nym} : Nyamwezi, {nyn} : Nyankole, {nyo} : Nyoro, {nzi}
-: Nzima, {oc} : Occitan (post 1500), {oj} : Ojibwa, {or} : Oriya, {om} :
-Oromo, {osa} : Osage, {os} : Ossetian; Ossetic, [{oto} : Otomian
-languages], {pal} : Pahlavi, {i-pwn} : Paiwan, {pau} : Palauan, {pi} :
-Pali, {pam} : Pampanga, {pag} : Pangasinan, {pa} : Panjabi, {pap} :
-Papiamento, [{paa} : Papuan (Other)], {fa} : Persian, {peo} : Old Persian
-(ca.600-400 B.C.), [{phi} : Philippine (Other)], {phn} : Phoenician, {pon}
-: Pohnpeian, {pl} : Polish, {pt} : Portuguese, [{pra} : Prakrit languages],
-{pro} : Old Provencal (to 1500), {ps} : Pushto, {qu} : Quechua, {rm} :
-Raeto-Romance, {raj} : Rajasthani, {rap} : Rapanui, {rar} : Rarotongan,
-[{qaa - qtz} : Reserved for local use.], [{roa} : Romance (Other)], {ro} :
-Romanian, {rom} : Romany, {rn} : Rundi, {ru} : Russian, [{sal} : Salishan
-languages], {sam} : Samaritan Aramaic, {se} : Northern Sami, {sma} :
-Southern Sami, {smn} : Inari Sami, {smj} : Lule Sami, {sms} : Skolt Sami,
-[{smi} : Sami languages (Other)], {sm} : Samoan, {sad} : Sandawe, {sg} :
-Sango, {sa} : Sanskrit, {sat} : Santali, {sc} : Sardinian, {sas} : Sasak,
-{sco} : Scots, {sel} : Selkup, [{sem} : Semitic (Other)], {sr} : Serbian,
-{srr} : Serer, {shn} : Shan, {sn} : Shona, {sid} : Sidamo, {sgn-...} : Sign
-Languages, {bla} : Siksika, {sd} : Sindhi, {si} : Sinhalese, [{sit} :
-Sino-Tibetan (Other)], [{sio} : Siouan languages], {den} : Slave
-(Athapascan), [{sla} : Slavic (Other)], {sk} : Slovak, {sl} : Slovenian,
-{sog} : Sogdian, {so} : Somali, {son} : Songhai, {snk} : Soninke, {wen} :
-Sorbian languages, {nso} : Northern Sotho, {st} : Southern Sotho, [{sai} :
-South American Indian (Other)], {es} : Spanish, {suk} : Sukuma, {sux} :
-Sumerian, {su} : Sundanese, {sus} : Susu, {sw} : Swahili, {ss} : Swati,
-{sv} : Swedish, {syr} : Syriac, {tl} : Tagalog, {ty} : Tahitian, [{tai} :
-Tai (Other)], {tg} : Tajik, {tmh} : Tamashek, {ta} : Tamil, {i-tao} : Tao,
-{tt} : Tatar, {i-tay} : Tayal, {te} : Telugu, {ter} : Tereno, {tet} :
-Tetum, {th} : Thai, {bo} : Tibetan, {tig} : Tigre, {ti} : Tigrinya, {tem} :
-Timne, {tiv} : Tiv, {tli} : Tlingit, {tpi} : Tok Pisin, {tkl} : Tokelau,
-{tog} : Tonga (Nyasa), {to} : Tonga (Tonga Islands), {tsi} : Tsimshian,
-{ts} : Tsonga, {i-tsu} : Tsou, {tn} : Tswana, {tum} : Tumbuka, [{tup} :
-Tupi languages], {tr} : Turkish, {ota} : Ottoman Turkish (1500-1928), {crh}
-: Crimean Turkish, {tk} : Turkmen, {tvl} : Tuvalu, {tyv} : Tuvinian, {tw} :
-Twi, {udm} : Udmurt, {uga} : Ugaritic, {ug} : Uighur, {uk} : Ukrainian,
-{umb} : Umbundu, {und} : Undetermined, {ur} : Urdu, {uz} : Uzbek, {vai} :
-Vai, {ve} : Venda, {vi} : Vietnamese, {vo} : Volapuk, {vot} : Votic, [{wak}
-: Wakashan languages], {wa} : Walloon, {wal} : Walamo, {war} : Waray, {was}
-: Washo, {cy} : Welsh, {wo} : Wolof, {x-...} : Unregistered (Semi-Private
-Use), {xh} : Xhosa, {sah} : Yakut, {yao} : Yao, {yap} : Yapese, {ii} :
-Sichuan Yi, {yi} : Yiddish, {yo} : Yoruba, [{ypk} : Yupik languages], {znd}
-: Zande, [{zap} : Zapotec], {zen} : Zenaga, {za} : Zhuang, {zu} : Zulu,
-{zun} : Zuni
-
-=item SEE ALSO
-
-=item COPYRIGHT AND DISCLAIMER
-
-=item AUTHOR
-
-=back
-
-=head2 IO - load various IO modules
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item DEPRECATED
-
-=back
-
-=head2 IO::Compress::Base - Base Class for IO::Compress modules
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item MODIFICATION HISTORY
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 IO::Compress::Bzip2 - Write bzip2 files/buffers
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Functional Interface
-
-=over 4
-
-=item bzip2 $input => $output [, OPTS]
-
-A filename, A filehandle, A scalar reference, An array reference, An Input
-FileGlob string, A filename, A filehandle, A scalar reference, An Array
-Reference, An Output FileGlob
-
-=item Notes
-
-=item Optional Parameters
-
-C<< AutoClose => 0|1 >>, C<< BinModeIn => 0|1 >>, C<< Append => 0|1 >>
-
-=item Examples
-
-=back
-
-=item OO Interface
-
-=over 4
-
-=item Constructor
-
-A filename, A filehandle, A scalar reference
-
-=item Constructor Options
-
-C<< AutoClose => 0|1 >>, C<< Append => 0|1 >>, A Buffer, A Filename, A
-Filehandle, C<< BlockSize100K => number >>, C<< WorkFactor => number >>,
-C<< Strict => 0|1 >>
-
-=item Examples
-
-=back
-
-=item Methods
-
-=over 4
-
-=item print
-
-=item printf
-
-=item syswrite
-
-=item write
-
-=item flush
-
-=item tell
-
-=item eof
-
-=item seek
-
-=item binmode
-
-=item opened
-
-=item autoflush
-
-=item input_line_number
-
-=item fileno
-
-=item close
-
-=item newStream([OPTS])
-
-=back
-
-=item Importing
-
-:all
-
-=item EXAMPLES
-
-=over 4
-
-=item Apache::GZip Revisited
-
-=item Working with Net::FTP
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item MODIFICATION HISTORY
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 IO::Compress::Deflate - Write RFC 1950 files/buffers
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Functional Interface
-
-=over 4
-
-=item deflate $input => $output [, OPTS]
-
-A filename, A filehandle, A scalar reference, An array reference, An Input
-FileGlob string, A filename, A filehandle, A scalar reference, An Array
-Reference, An Output FileGlob
-
-=item Notes
-
-=item Optional Parameters
-
-C<< AutoClose => 0|1 >>, C<< BinModeIn => 0|1 >>, C<< Append => 0|1 >>, A
-Buffer, A Filename, A Filehandle
-
-=item Examples
-
-=back
-
-=item OO Interface
-
-=over 4
-
-=item Constructor
-
-A filename, A filehandle, A scalar reference
-
-=item Constructor Options
-
-C<< AutoClose => 0|1 >>, C<< Append => 0|1 >>, A Buffer, A Filename, A
-Filehandle, C<< Merge => 0|1 >>, -Level, -Strategy, C<< Strict => 0|1 >>
-
-=item Examples
-
-=back
-
-=item Methods
-
-=over 4
-
-=item print
-
-=item printf
-
-=item syswrite
-
-=item write
-
-=item flush
-
-=item tell
-
-=item eof
-
-=item seek
-
-=item binmode
-
-=item opened
-
-=item autoflush
-
-=item input_line_number
-
-=item fileno
-
-=item close
-
-=item newStream([OPTS])
-
-=item deflateParams
-
-=back
-
-=item Importing
-
-:all, :constants, :flush, :level, :strategy
-
-=item EXAMPLES
-
-=over 4
-
-=item Apache::GZip Revisited
-
-=item Working with Net::FTP
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item MODIFICATION HISTORY
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 IO::Compress::FAQ -- Frequently Asked Questions about IO::Compress
-
-=over 4
-
-=item DESCRIPTION
-
-=item GENERAL
-
-=over 4
-
-=item Compatibility with Unix compress/uncompress.
-
-=item Accessing .tar.Z files
-
-=item How do I recompress using a different compression?
-
-=back
-
-=item ZIP
-
-=over 4
-
-=item What Compression Types do IO::Compress::Zip & IO::Uncompress::Unzip
-support?
-
-Store (method 0), Deflate (method 8), Bzip2 (method 12), Lzma (method 14)
-
-=item Can I Read/Write Zip files larger the 4 Gig?
-
-=item Zip Resources
-
-=back
-
-=item GZIP
-
-=over 4
-
-=item Gzip Resources
-
-=back
-
-=item ZLIB
-
-=over 4
-
-=item Zlib Resources
-
-=back
-
-=item HTTP & NETWORK
-
-=over 4
-
-=item Apache::GZip Revisited
-
-=item Compressed files and Net::FTP
-
-=back
-
-=item MISC
-
-=over 4
-
-=item Using C<InputLength> to uncompress data embedded in a larger
-file/buffer.
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item MODIFICATION HISTORY
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 IO::Compress::Gzip - Write RFC 1952 files/buffers
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Functional Interface
-
-=over 4
-
-=item gzip $input => $output [, OPTS]
-
-A filename, A filehandle, A scalar reference, An array reference, An Input
-FileGlob string, A filename, A filehandle, A scalar reference, An Array
-Reference, An Output FileGlob
-
-=item Notes
-
-=item Optional Parameters
-
-C<< AutoClose => 0|1 >>, C<< BinModeIn => 0|1 >>, C<< Append => 0|1 >>, A
-Buffer, A Filename, A Filehandle
-
-=item Examples
-
-=back
-
-=item OO Interface
-
-=over 4
-
-=item Constructor
-
-A filename, A filehandle, A scalar reference
-
-=item Constructor Options
-
-C<< AutoClose => 0|1 >>, C<< Append => 0|1 >>, A Buffer, A Filename, A
-Filehandle, C<< Merge => 0|1 >>, -Level, -Strategy, C<< Minimal => 0|1 >>,
-C<< Comment => $comment >>, C<< Name => $string >>, C<< Time => $number >>,
-C<< TextFlag => 0|1 >>, C<< HeaderCRC => 0|1 >>, C<< OS_Code => $value >>,
-C<< ExtraField => $data >>, C<< ExtraFlags => $value >>, C<< Strict => 0|1
->>
-
-=item Examples
-
-=back
-
-=item Methods
-
-=over 4
-
-=item print
-
-=item printf
-
-=item syswrite
-
-=item write
-
-=item flush
-
-=item tell
-
-=item eof
-
-=item seek
-
-=item binmode
-
-=item opened
-
-=item autoflush
-
-=item input_line_number
-
-=item fileno
-
-=item close
-
-=item newStream([OPTS])
-
-=item deflateParams
-
-=back
-
-=item Importing
-
-:all, :constants, :flush, :level, :strategy
-
-=item EXAMPLES
-
-=over 4
-
-=item Apache::GZip Revisited
-
-=item Working with Net::FTP
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item MODIFICATION HISTORY
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 IO::Compress::RawDeflate - Write RFC 1951 files/buffers
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Functional Interface
-
-=over 4
-
-=item rawdeflate $input => $output [, OPTS]
-
-A filename, A filehandle, A scalar reference, An array reference, An Input
-FileGlob string, A filename, A filehandle, A scalar reference, An Array
-Reference, An Output FileGlob
-
-=item Notes
-
-=item Optional Parameters
-
-C<< AutoClose => 0|1 >>, C<< BinModeIn => 0|1 >>, C<< Append => 0|1 >>, A
-Buffer, A Filename, A Filehandle
-
-=item Examples
-
-=back
-
-=item OO Interface
-
-=over 4
-
-=item Constructor
-
-A filename, A filehandle, A scalar reference
-
-=item Constructor Options
-
-C<< AutoClose => 0|1 >>, C<< Append => 0|1 >>, A Buffer, A Filename, A
-Filehandle, C<< Merge => 0|1 >>, -Level, -Strategy, C<< Strict => 0|1 >>
-
-=item Examples
-
-=back
-
-=item Methods
-
-=over 4
-
-=item print
-
-=item printf
-
-=item syswrite
-
-=item write
-
-=item flush
-
-=item tell
-
-=item eof
-
-=item seek
-
-=item binmode
-
-=item opened
-
-=item autoflush
-
-=item input_line_number
-
-=item fileno
-
-=item close
-
-=item newStream([OPTS])
-
-=item deflateParams
-
-=back
-
-=item Importing
-
-:all, :constants, :flush, :level, :strategy
-
-=item EXAMPLES
-
-=over 4
-
-=item Apache::GZip Revisited
-
-=item Working with Net::FTP
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item MODIFICATION HISTORY
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 IO::Compress::Zip - Write zip files/buffers
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Functional Interface
-
-=over 4
-
-=item zip $input => $output [, OPTS]
-
-A filename, A filehandle, A scalar reference, An array reference, An Input
-FileGlob string, A filename, A filehandle, A scalar reference, An Array
-Reference, An Output FileGlob
-
-=item Notes
-
-=item Optional Parameters
-
-C<< AutoClose => 0|1 >>, C<< BinModeIn => 0|1 >>, C<< Append => 0|1 >>, A
-Buffer, A Filename, A Filehandle
-
-=item Examples
-
-=back
-
-=item OO Interface
-
-=over 4
-
-=item Constructor
-
-A filename, A filehandle, A scalar reference
-
-=item Constructor Options
-
-C<< AutoClose => 0|1 >>, C<< Append => 0|1 >>, A Buffer, A Filename, A
-Filehandle, C<< Name => $string >>, C<< CanonicalName => 0|1 >>, C<<
-FilterName => sub { ... } >>, C<< Time => $number >>, C<< ExtAttr => $attr
->>, C<< exTime => [$atime, $mtime, $ctime] >>, C<< exUnix2 => [$uid, $gid]
->>, C<< exUnixN => [$uid, $gid] >>, C<< Comment => $comment >>, C<<
-ZipComment => $comment >>, C<< Method => $method >>, C<< Stream => 0|1 >>,
-C<< Zip64 => 0|1 >>, C<< TextFlag => 0|1 >>, C<< ExtraFieldLocal => $data
->> =item C<< ExtraFieldCentral => $data >>, C<< Minimal => 1|0 >>, C<<
-BlockSize100K => number >>, C<< WorkFactor => number >>, C<< Preset =>
-number >>, C<< Extreme => 0|1 >>, -Level, -Strategy, C<< Strict => 0|1 >>
-
-=item Examples
-
-=back
-
-=item Methods
-
-=over 4
-
-=item print
-
-=item printf
-
-=item syswrite
-
-=item write
-
-=item flush
-
-=item tell
-
-=item eof
-
-=item seek
-
-=item binmode
-
-=item opened
-
-=item autoflush
-
-=item input_line_number
-
-=item fileno
-
-=item close
-
-=item newStream([OPTS])
-
-=item deflateParams
-
-=back
-
-=item Importing
-
-:all, :constants, :flush, :level, :strategy, :zip_method
-
-=item EXAMPLES
-
-=over 4
-
-=item Apache::GZip Revisited
-
-=item Working with Net::FTP
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item MODIFICATION HISTORY
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 IO::Dir - supply object methods for directory handles
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-new ( [ DIRNAME ] ), open ( DIRNAME ), read (), seek ( POS ), tell (),
-rewind (), close (), tie %hash, 'IO::Dir', DIRNAME [, OPTIONS ]
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 IO::File - supply object methods for filehandles
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CONSTRUCTOR
-
-new ( FILENAME [,MODE [,PERMS]] ), new_tmpfile
-
-=item METHODS
-
-open( FILENAME [,MODE [,PERMS]] ), open( FILENAME, IOLAYERS ), binmode(
-[LAYER] )
-
-=item NOTE
-
-=item SEE ALSO
-
-=item HISTORY
-
-=back
-
-=head2 IO::Handle - supply object methods for I/O handles
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CONSTRUCTOR
-
-new (), new_from_fd ( FD, MODE )
-
-=item METHODS
-
-$io->fdopen ( FD, MODE ), $io->opened, $io->getline, $io->getlines,
-$io->ungetc ( ORD ), $io->write ( BUF, LEN [, OFFSET ] ), $io->error,
-$io->clearerr, $io->sync, $io->flush, $io->printflush ( ARGS ),
-$io->blocking ( [ BOOL ] ), $io->untaint
-
-=item NOTE
-
-=item SEE ALSO
-
-=item BUGS
-
-=item HISTORY
-
-=back
-
-=head2 IO::Pipe - supply object methods for pipes
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CONSTRUCTOR
-
-new ( [READER, WRITER] )
-
-=item METHODS
-
-reader ([ARGS]), writer ([ARGS]), handles ()
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 IO::Poll - Object interface to system poll call
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-mask ( IO [, EVENT_MASK ] ), poll ( [ TIMEOUT ] ), events ( IO ), remove (
-IO ), handles( [ EVENT_MASK ] )
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 IO::Seekable - supply seek based methods for I/O objects
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-$io->getpos, $io->setpos, $io->seek ( POS, WHENCE ), WHENCE=0 (SEEK_SET),
-WHENCE=1 (SEEK_CUR), WHENCE=2 (SEEK_END), $io->sysseek( POS, WHENCE ),
-$io->tell
-
-=item SEE ALSO
-
-=item HISTORY
-
-=back
-
-=head2 IO::Select - OO interface to the select system call
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CONSTRUCTOR
-
-new ( [ HANDLES ] )
-
-=item METHODS
-
-add ( HANDLES ), remove ( HANDLES ), exists ( HANDLE ), handles, can_read (
-[ TIMEOUT ] ), can_write ( [ TIMEOUT ] ), has_exception ( [ TIMEOUT ] ),
-count (), bits(), select ( READ, WRITE, EXCEPTION [, TIMEOUT ] )
-
-=item EXAMPLE
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 IO::Socket - Object interface to socket communications
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CONSTRUCTOR
-
-new ( [ARGS] )
-
-=item METHODS
-
-accept([PKG]), socketpair(DOMAIN, TYPE, PROTOCOL), atmark, connected,
-protocol, sockdomain, sockopt(OPT [, VAL]), getsockopt(LEVEL, OPT),
-setsockopt(LEVEL, OPT, VAL), socktype, timeout([VAL])
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 IO::Socket::INET - Object interface for AF_INET domain sockets
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CONSTRUCTOR
-
-new ( [ARGS] )
-
-=over 4
-
-=item METHODS
-
-sockaddr (), sockport (), sockhost (), peeraddr (), peerport (), peerhost
-()
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 IO::Socket::UNIX - Object interface for AF_UNIX domain sockets
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CONSTRUCTOR
-
-new ( [ARGS] )
-
-=item METHODS
-
-hostpath(), peerpath()
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 IO::Uncompress::AnyInflate - Uncompress zlib-based (zip, gzip)
-file/buffer
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-RFC 1950, RFC 1951 (optionally), gzip (RFC 1952), zip
-
-=item Functional Interface
-
-=over 4
-
-=item anyinflate $input => $output [, OPTS]
-
-A filename, A filehandle, A scalar reference, An array reference, An Input
-FileGlob string, A filename, A filehandle, A scalar reference, An Array
-Reference, An Output FileGlob
-
-=item Notes
-
-=item Optional Parameters
-
-C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>, A
-Buffer, A Filename, A Filehandle, C<< MultiStream => 0|1 >>, C<<
-TrailingData => $scalar >>
-
-=item Examples
-
-=back
-
-=item OO Interface
-
-=over 4
-
-=item Constructor
-
-A filename, A filehandle, A scalar reference
-
-=item Constructor Options
-
-C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string
->>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength =>
-$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>, C<< RawInflate => 0|1
->>, C<< ParseExtra => 0|1 >> If the gzip FEXTRA header field is present and
-this option is set, it will force the module to check that it conforms to
-the sub-field structure as defined in RFC 1952
-
-=item Examples
-
-=back
-
-=item Methods
-
-=over 4
-
-=item read
-
-=item read
-
-=item getline
-
-=item getc
-
-=item ungetc
-
-=item inflateSync
-
-=item getHeaderInfo
-
-=item tell
-
-=item eof
-
-=item seek
-
-=item binmode
-
-=item opened
-
-=item autoflush
-
-=item input_line_number
-
-=item fileno
-
-=item close
-
-=item nextStream
-
-=item trailingData
-
-=back
-
-=item Importing
-
-:all
-
-=item EXAMPLES
-
-=over 4
-
-=item Working with Net::FTP
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item MODIFICATION HISTORY
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 IO::Uncompress::AnyUncompress - Uncompress gzip, zip, bzip2 or lzop
-file/buffer
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-RFC 1950, RFC 1951 (optionally), gzip (RFC 1952), zip, bzip2, lzop, lzf,
-lzma, xz
-
-=item Functional Interface
-
-=over 4
-
-=item anyuncompress $input => $output [, OPTS]
-
-A filename, A filehandle, A scalar reference, An array reference, An Input
-FileGlob string, A filename, A filehandle, A scalar reference, An Array
-Reference, An Output FileGlob
-
-=item Notes
-
-=item Optional Parameters
-
-C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>, A
-Buffer, A Filename, A Filehandle, C<< MultiStream => 0|1 >>, C<<
-TrailingData => $scalar >>
-
-=item Examples
-
-=back
-
-=item OO Interface
-
-=over 4
-
-=item Constructor
-
-A filename, A filehandle, A scalar reference
-
-=item Constructor Options
-
-C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string
->>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength =>
-$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>, C<< RawInflate => 0|1
->>, C<< UnLzma => 0|1 >>
-
-=item Examples
-
-=back
-
-=item Methods
-
-=over 4
-
-=item read
-
-=item read
-
-=item getline
-
-=item getc
-
-=item ungetc
-
-=item getHeaderInfo
-
-=item tell
-
-=item eof
-
-=item seek
-
-=item binmode
-
-=item opened
-
-=item autoflush
-
-=item input_line_number
-
-=item fileno
-
-=item close
-
-=item nextStream
-
-=item trailingData
-
-=back
-
-=item Importing
-
-:all
-
-=item EXAMPLES
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item MODIFICATION HISTORY
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 IO::Uncompress::Base - Base Class for IO::Uncompress modules
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item MODIFICATION HISTORY
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 IO::Uncompress::Bunzip2 - Read bzip2 files/buffers
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Functional Interface
-
-=over 4
-
-=item bunzip2 $input => $output [, OPTS]
-
-A filename, A filehandle, A scalar reference, An array reference, An Input
-FileGlob string, A filename, A filehandle, A scalar reference, An Array
-Reference, An Output FileGlob
-
-=item Notes
-
-=item Optional Parameters
-
-C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>,
-C<< MultiStream => 0|1 >>, C<< TrailingData => $scalar >>
-
-=item Examples
-
-=back
-
-=item OO Interface
-
-=over 4
-
-=item Constructor
-
-A filename, A filehandle, A scalar reference
-
-=item Constructor Options
-
-C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string
->>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength =>
-$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>, C<< Small => 0|1 >>
-
-=item Examples
-
-=back
-
-=item Methods
-
-=over 4
-
-=item read
-
-=item read
-
-=item getline
-
-=item getc
-
-=item ungetc
-
-=item getHeaderInfo
-
-=item tell
-
-=item eof
-
-=item seek
-
-=item binmode
-
-=item opened
-
-=item autoflush
-
-=item input_line_number
-
-=item fileno
-
-=item close
-
-=item nextStream
-
-=item trailingData
-
-=back
-
-=item Importing
-
-:all
-
-=item EXAMPLES
-
-=over 4
-
-=item Working with Net::FTP
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item MODIFICATION HISTORY
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 IO::Uncompress::Gunzip - Read RFC 1952 files/buffers
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Functional Interface
-
-=over 4
-
-=item gunzip $input => $output [, OPTS]
-
-A filename, A filehandle, A scalar reference, An array reference, An Input
-FileGlob string, A filename, A filehandle, A scalar reference, An Array
-Reference, An Output FileGlob
-
-=item Notes
-
-=item Optional Parameters
-
-C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>, A
-Buffer, A Filename, A Filehandle, C<< MultiStream => 0|1 >>, C<<
-TrailingData => $scalar >>
-
-=item Examples
-
-=back
-
-=item OO Interface
-
-=over 4
-
-=item Constructor
-
-A filename, A filehandle, A scalar reference
-
-=item Constructor Options
-
-C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string
->>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength =>
-$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>, C<< ParseExtra => 0|1
->> If the gzip FEXTRA header field is present and this option is set, it
-will force the module to check that it conforms to the sub-field structure
-as defined in RFC 1952
-
-=item Examples
-
-=back
-
-=item Methods
-
-=over 4
-
-=item read
-
-=item read
-
-=item getline
-
-=item getc
-
-=item ungetc
-
-=item inflateSync
-
-=item getHeaderInfo
-
-Name, Comment
-
-=item tell
-
-=item eof
-
-=item seek
-
-=item binmode
-
-=item opened
-
-=item autoflush
-
-=item input_line_number
-
-=item fileno
-
-=item close
-
-=item nextStream
-
-=item trailingData
-
-=back
-
-=item Importing
-
-:all
-
-=item EXAMPLES
-
-=over 4
-
-=item Working with Net::FTP
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item MODIFICATION HISTORY
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 IO::Uncompress::Inflate - Read RFC 1950 files/buffers
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Functional Interface
-
-=over 4
-
-=item inflate $input => $output [, OPTS]
-
-A filename, A filehandle, A scalar reference, An array reference, An Input
-FileGlob string, A filename, A filehandle, A scalar reference, An Array
-Reference, An Output FileGlob
-
-=item Notes
-
-=item Optional Parameters
-
-C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>, A
-Buffer, A Filename, A Filehandle, C<< MultiStream => 0|1 >>, C<<
-TrailingData => $scalar >>
-
-=item Examples
-
-=back
-
-=item OO Interface
-
-=over 4
-
-=item Constructor
-
-A filename, A filehandle, A scalar reference
-
-=item Constructor Options
-
-C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string
->>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength =>
-$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>
-
-=item Examples
-
-=back
-
-=item Methods
-
-=over 4
-
-=item read
-
-=item read
-
-=item getline
-
-=item getc
-
-=item ungetc
-
-=item inflateSync
-
-=item getHeaderInfo
-
-=item tell
-
-=item eof
-
-=item seek
-
-=item binmode
-
-=item opened
-
-=item autoflush
-
-=item input_line_number
-
-=item fileno
-
-=item close
-
-=item nextStream
-
-=item trailingData
-
-=back
-
-=item Importing
-
-:all
-
-=item EXAMPLES
-
-=over 4
-
-=item Working with Net::FTP
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item MODIFICATION HISTORY
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 IO::Uncompress::RawInflate - Read RFC 1951 files/buffers
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Functional Interface
-
-=over 4
-
-=item rawinflate $input => $output [, OPTS]
-
-A filename, A filehandle, A scalar reference, An array reference, An Input
-FileGlob string, A filename, A filehandle, A scalar reference, An Array
-Reference, An Output FileGlob
-
-=item Notes
-
-=item Optional Parameters
-
-C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>, A
-Buffer, A Filename, A Filehandle, C<< MultiStream => 0|1 >>, C<<
-TrailingData => $scalar >>
-
-=item Examples
-
-=back
-
-=item OO Interface
-
-=over 4
-
-=item Constructor
-
-A filename, A filehandle, A scalar reference
-
-=item Constructor Options
-
-C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string
->>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength =>
-$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>
-
-=item Examples
-
-=back
-
-=item Methods
-
-=over 4
-
-=item read
-
-=item read
-
-=item getline
-
-=item getc
-
-=item ungetc
-
-=item inflateSync
-
-=item getHeaderInfo
-
-=item tell
-
-=item eof
-
-=item seek
-
-=item binmode
-
-=item opened
-
-=item autoflush
-
-=item input_line_number
-
-=item fileno
-
-=item close
-
-=item nextStream
-
-=item trailingData
-
-=back
-
-=item Importing
-
-:all
-
-=item EXAMPLES
-
-=over 4
-
-=item Working with Net::FTP
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item MODIFICATION HISTORY
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 IO::Uncompress::Unzip - Read zip files/buffers
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Functional Interface
-
-=over 4
-
-=item unzip $input => $output [, OPTS]
-
-A filename, A filehandle, A scalar reference, An array reference, An Input
-FileGlob string, A filename, A filehandle, A scalar reference, An Array
-Reference, An Output FileGlob
-
-=item Notes
-
-=item Optional Parameters
-
-C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>, A
-Buffer, A Filename, A Filehandle, C<< MultiStream => 0|1 >>, C<<
-TrailingData => $scalar >>
-
-=item Examples
-
-=back
-
-=item OO Interface
-
-=over 4
-
-=item Constructor
-
-A filename, A filehandle, A scalar reference
-
-=item Constructor Options
-
-C<< Name => "membername" >>, C<< AutoClose => 0|1 >>, C<< MultiStream =>
-0|1 >>, C<< Prime => $string >>, C<< Transparent => 0|1 >>, C<< BlockSize
-=> $num >>, C<< InputLength => $size >>, C<< Append => 0|1 >>, C<< Strict
-=> 0|1 >>
-
-=item Examples
-
-=back
-
-=item Methods
-
-=over 4
-
-=item read
-
-=item read
-
-=item getline
-
-=item getc
-
-=item ungetc
-
-=item inflateSync
-
-=item getHeaderInfo
-
-=item tell
-
-=item eof
-
-=item seek
-
-=item binmode
-
-=item opened
-
-=item autoflush
-
-=item input_line_number
-
-=item fileno
-
-=item close
-
-=item nextStream
-
-=item trailingData
-
-=back
-
-=item Importing
-
-:all
-
-=item EXAMPLES
-
-=over 4
-
-=item Working with Net::FTP
-
-=item Walking through a zip file
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item MODIFICATION HISTORY
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 IO::Zlib - IO:: style interface to L<Compress::Zlib>
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CONSTRUCTOR
-
-new ( [ARGS] )
-
-=item OBJECT METHODS
-
-open ( FILENAME, MODE ), opened, close, getc, getline, getlines, print (
-ARGS... ), read ( BUF, NBYTES, [OFFSET] ), eof, seek ( OFFSET, WHENCE ),
-tell, setpos ( POS ), getpos ( POS )
-
-=item USING THE EXTERNAL GZIP
-
-=item CLASS METHODS
-
-has_Compress_Zlib, gzip_external, gzip_used, gzip_read_open,
-gzip_write_open
-
-=item DIAGNOSTICS
-
-IO::Zlib::getlines: must be called in list context,
-IO::Zlib::gzopen_external: mode '...' is illegal, IO::Zlib::import: '...'
-is illegal, IO::Zlib::import: ':gzip_external' requires an argument,
-IO::Zlib::import: 'gzip_read_open' requires an argument, IO::Zlib::import:
-'gzip_read' '...' is illegal, IO::Zlib::import: 'gzip_write_open' requires
-an argument, IO::Zlib::import: 'gzip_write_open' '...' is illegal,
-IO::Zlib::import: no Compress::Zlib and no external gzip, IO::Zlib::open:
-needs a filename, IO::Zlib::READ: NBYTES must be specified,
-IO::Zlib::WRITE: too long LENGTH
-
-=item SEE ALSO
-
-=item HISTORY
-
-=item COPYRIGHT
-
-=back
-
-=head2 IPC::Cmd - finding and running system commands made easy
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CLASS METHODS
-
-=over 4
-
-=item $ipc_run_version = IPC::Cmd->can_use_ipc_run( [VERBOSE] )
-
-=back
-
-=back
-
-=over 4
-
-=item $ipc_open3_version = IPC::Cmd->can_use_ipc_open3( [VERBOSE] )
-
-=back
-
-=over 4
-
-=item $bool = IPC::Cmd->can_capture_buffer
-
-=back
-
-=over 4
-
-=item $bool = IPC::Cmd->can_use_run_forked
-
-=back
-
-=over 4
-
-=item FUNCTIONS
-
-=over 4
-
-=item $path = can_run( PROGRAM );
-
-=back
-
-=back
-
-=over 4
-
-=item $ok | ($ok, $err, $full_buf, $stdout_buff, $stderr_buff) = run(
-command => COMMAND, [verbose => BOOL, buffer => \$SCALAR, timeout => DIGIT]
-);
-
-command, verbose, buffer, timeout, success, error message, full_buffer,
-out_buffer, error_buffer
-
-=back
-
-=over 4
-
-=item $hashref = run_forked( COMMAND, { child_stdin => SCALAR, timeout =>
-DIGIT, stdout_handler => CODEREF, stderr_handler => CODEREF} );
-
-C<timeout>, C<child_stdin>, C<stdout_handler>, C<stderr_handler>,
-C<discard_output>, C<terminate_on_parent_sudden_death>, C<exit_code>,
-C<timeout>, C<stdout>, C<stderr>, C<merged>, C<err_msg>
-
-=back
-
-=over 4
-
-=item $q = QUOTE
-
-=back
-
-=over 4
-
-=item HOW IT WORKS
-
-=item Global Variables
-
-=over 4
-
-=item $IPC::Cmd::VERBOSE
-
-=item $IPC::Cmd::USE_IPC_RUN
-
-=item $IPC::Cmd::USE_IPC_OPEN3
-
-=item $IPC::Cmd::WARN
-
-=item $IPC::Cmd::INSTANCES
-
-=item $IPC::Cmd::ALLOW_NULL_ARGS
-
-=back
-
-=item Caveats
-
-Whitespace and IPC::Open3 / system(), Whitespace and IPC::Run, IO Redirect,
-Interleaving STDOUT/STDERR
-
-=item See Also
-
-=item ACKNOWLEDGEMENTS
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 IPC::Open2 - open a process for both reading and writing using
-open2()
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item WARNING
-
-=item SEE ALSO
-
-=back
-
-=head2 IPC::Open3 - open a process for reading, writing, and error handling
-using open3()
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item See Also
-
-L<IPC::Open2>, L<IPC::Run>
-
-=item WARNING
-
-=back
-
-=head2 JSON::PP - JSON::XS compatible pure-Perl module.
-
-=over 4
-
-=item SYNOPSIS
-
-=item VERSION
-
-=item NOTE
-
-=item DESCRIPTION
-
-=over 4
-
-=item FEATURES
-
-correct unicode handling, round-trip integrity, strict checking of JSON
-correctness
-
-=back
-
-=item FUNCTIONAL INTERFACE
-
-=over 4
-
-=item encode_json
-
-=item decode_json
-
-=item JSON::PP::is_bool
-
-=item JSON::PP::true
-
-=item JSON::PP::false
-
-=item JSON::PP::null
-
-=back
-
-=item HOW DO I DECODE A DATA FROM OUTER AND ENCODE TO OUTER
-
-=item METHODS
-
-=over 4
-
-=item new
-
-=item ascii
-
-=item latin1
-
-=item utf8
-
-=item pretty
-
-=item indent
-
-=item space_before
-
-=item space_after
-
-=item relaxed
-
-list items can have an end-comma, shell-style '#'-comments
-
-=item canonical
-
-=item allow_nonref
-
-=item allow_unknown
-
-=item allow_blessed
-
-=item convert_blessed
-
-=item filter_json_object
-
-=item filter_json_single_key_object
-
-=item shrink
-
-=item max_depth
-
-=item max_size
-
-=item encode
-
-=item decode
-
-=item decode_prefix
-
-=back
-
-=item INCREMENTAL PARSING
-
-=over 4
-
-=item incr_parse
-
-=item incr_text
-
-=item incr_skip
-
-=item incr_reset
-
-=back
-
-=item JSON::PP OWN METHODS
-
-=over 4
-
-=item allow_singlequote
-
-=item allow_barekey
-
-=item allow_bignum
-
-=item loose
-
-=item escape_slash
-
-=item indent_length
-
-=item sort_by
-
-=back
-
-=item INTERNAL
-
-PP_encode_box, PP_decode_box
-
-=item MAPPING
-
-=over 4
-
-=item JSON -> PERL
-
-object, array, string, number, true, false, null
-
-=item PERL -> JSON
-
-hash references, array references, other references, JSON::PP::true,
-JSON::PP::false, JSON::PP::null, blessed objects, simple scalars, Big
-Number
-
-=back
-
-=item UNICODE HANDLING ON PERLS
-
-=over 4
-
-=item Perl 5.8 and later
-
-=item Perl 5.6
-
-=item Perl 5.005
-
-=back
-
-=item TODO
-
-speed, memory saving
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 JSON::PP::Boolean - dummy module providing JSON::PP::Boolean
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item AUTHOR
-
-=back
-
-=head2 List::Util - A selection of general-utility list subroutines
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-first BLOCK LIST, max LIST, maxstr LIST, min LIST, minstr LIST, reduce
-BLOCK LIST, shuffle LIST, sum LIST
-
-=item KNOWN BUGS
-
-=item SUGGESTED ADDITIONS
-
-=item SEE ALSO
-
-=item COPYRIGHT
-
-=back
-
-=head2 List::Util::XS - Indicate if List::Util was compiled with a C
-compiler
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes - a distribution of modules to handle locale codes
-
-=over 4
-
-=item DESCRIPTION
-
-B<Locale::Codes::Country, Locale::Country>, B<Locale::Codes::Language,
-Locale::Language>, B<Locale::Codes::Currency, Locale::Currency>,
-B<Locale::Codes::Script, Locale::Script>, B<Locale::Codes::LangExt>,
-B<Locale::Codes::LangVar>, B<Locale::Codes::LangFam>, B<Locale::Codes>,
-B<Locale::Codes::Constants>, B<Locale::Codes::Country_codes>,
-B<Locale::Codes::Language_codes>, B<Locale::Codes::Currency_codes>,
-B<Locale::Codes::Script_codes>, B<Locale::Codes::LangExt_codes>,
-B<Locale::Codes::LangVar_codes>, B<Locale::Codes::LangFam_codes>
-
-=item NEW CODE SETS
-
-B<General-use code set>, B<An official source of data>, B<A free source of
-the data>, B<A reliable source of data>
-
-=item COMMON ALIASES
-
-=item DEPRECATED CODES
-
-=item SEE ALSO
-
-B<Locale::Codes::API>, B<Locale::Codes::Country>,
-B<Locale::Codes::Language>, B<Locale::Codes::Script>,
-B<Locale::Codes::Currency>, B<Locale::Codes::Changes>
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::API - a description of the callable function in each
-module
-
-=over 4
-
-=item DESCRIPTION
-
-=item ROUTINES
-
-B<code2XXX ( CODE [,CODESET] [,'retired'] )>, B<XXX2code ( NAME [,CODESET]
-[,'retired'] )>, B<XXX_code2code ( CODE ,CODESET ,CODESET2 )>,
-B<all_XXX_codes ( [CODESET] [,'retired'] )>, B<all_XXX_names ( [CODESET]
-[,'retired'] )>
-
-=item SEMI-PRIVATE ROUTINES
-
-B<MODULE::rename_XXX ( CODE ,NEW_NAME [,CODESET] )>, B<MODULE::add_XXX (
-CODE ,NAME [,CODESET] )>, B<MODULE::delete_XXX ( CODE [,CODESET] )>,
-B<MODULE::add_XXX_alias ( NAME ,NEW_NAME )>, B<MODULE::delete_XXX_alias (
-NAME )>, B<MODULE::rename_XXX_code ( CODE ,NEW_CODE [,CODESET] )>,
-B<MODULE::add_XXX_code_alias ( CODE ,NEW_CODE [,CODESET] )>,
-B<MODULE::delete_XXX_code_alias ( CODE [,CODESET] )>
-
-=item KNOWN BUGS AND LIMITATIONS
-
-B<*>, B<*>
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::Changes - details changes to Locale::Codes
-
-=over 4
-
-=item SYNOPSIS
-
-=item VERSION 3.22 (yyyy-mm-dd; sbeck)
-
-=item VERSION 3.21 (2012-03-01; sbeck)
-
-=item VERSION 3.20 (2011-12-01; sbeck)
-
-B<Added limited support for deprecated codes>, B<Fixed capitalization>,
-B<Pod tests off by default>, B<Codesets may be specified by name>,
-B<alias_code deprecated>, B<Code cleanup>, B<Added LangFam module>
-
-=item VERSION 3.18 (2011-08-31; sbeck)
-
-B<No longer use CIA data>
-
-=item VERSION 3.17 (2011-06-28; sbeck)
-
-B<Added new types of codes>, B<Added new codeset(s)>, B<Bug fixes>,
-B<Reorganized code>
-
-=item VERSION 3.16 (2011-03-01; sbeck)
-
-=item VERSION 3.15 (2010-12-02; sbeck)
-
-B<Minor fixes>
-
-=item VERSION 3.14 (2010-09-28; sbeck)
-
-B<Bug fixes>
-
-=item VERSION 3.13 (2010-06-04; sbeck)
-
-=item VERSION 3.12 (2010-04-06; sbeck)
-
-B<Reorganized code>
-
-=item VERSION 3.11 (2010-03-01; sbeck)
-
-B<Added new codeset(s)>, B<Bug fixes>
-
-=item VERSION 3.10 (2010-02-18; sbeck)
-
-B<Reorganized code>, B<(!) Changed XXX_code2code behavior slightly>,
-B<Added many semi-private routines>, B<New aliases>
-
-=item VERSION 3.01 (2010-02-15; sbeck)
-
-B<Fixed Makefile.PL and Build.PL>
-
-=item VERSION 3.00 (2010-02-10; sbeck)
-
-B<New maintainer>, B<(*) (!) All codes are generated from standards>,
-B<Added new codeset(s)>, B<(*) (!) Locale::Script changed>, B<Added missing
-functions>, B<(!) Dropped support for _alias_code>, B<(!) All functions
-return the standard value>, B<(!) rename_country function altered>
-
-=item VERSION 2.07 (2004-06-10; neilb)
-
-=item VERSION 2.06 (2002-07-15; neilb)
-
-=item VERSION 2.05 (2002-07-08; neilb)
-
-=item VERSION 2.04 (2002-05-23; neilb)
-
-=item VERSION 2.03 (2002-03-24; neilb)
-
-=item VERSION 2.02 (2002-03-09; neilb)
-
-=item VERSION 2.01 (2002-02-18; neilb)
-
-=item VERSION 2.00 (2002-02-17; neilb)
-
-=item VERSION 1.06 (2001-03-04; neilb)
-
-=item VERSION 1.05 (2001-02-13; neilb)
-
-=item VERSION 1.04 (2000-12-21; neilb)
-
-=item VERSION 1.03 (2000-12-??; neilb)
-
-=item VERSION 1.02 (2000-05-04; neilb)
-
-=item VERSION 1.00 (1998-03-09; neilb)
-
-=item VERSION 0.003 (1997-05-09; neilb)
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::Constants - constants for Locale codes
-
-=over 4
-
-=item DESCRIPTION
-
-=item KNOWN BUGS AND LIMITATIONS
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::Country - standard codes for country identification
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SUPPORTED CODE SETS
-
-B<alpha-2, LOCALE_CODE_ALPHA_2>, B<alpha-3, LOCALE_CODE_ALPHA_3>,
-B<numeric, LOCALE_CODE_NUMERIC>, B<fips-10, LOCALE_CODE_FIPS>, B<dom,
-LOCALE_CODE_DOM>
-
-=item ROUTINES
-
-B<code2country ( CODE [,CODESET] )>, B<country2code ( NAME [,CODESET] )>,
-B<country_code2code ( CODE ,CODESET ,CODESET2 )>, B<all_country_codes (
-[CODESET] )>, B<all_country_names ( [CODESET] )>,
-B<Locale::Codes::Country::rename_country ( CODE ,NEW_NAME [,CODESET] )>,
-B<Locale::Codes::Country::add_country ( CODE ,NAME [,CODESET] )>,
-B<Locale::Codes::Country::delete_country ( CODE [,CODESET] )>,
-B<Locale::Codes::Country::add_country_alias ( NAME ,NEW_NAME )>,
-B<Locale::Codes::Country::delete_country_alias ( NAME )>,
-B<Locale::Codes::Country::rename_country_code ( CODE ,NEW_CODE [,CODESET]
-)>, B<Locale::Codes::Country::add_country_code_alias ( CODE ,NEW_CODE
-[,CODESET] )>, B<Locale::Codes::Country::delete_country_code_alias ( CODE
-[,CODESET] )>, B<alias_code ( ALIAS, CODE [,CODESET] )>
-
-=item SEE ALSO
-
-B<Locale::Codes>, B<Locale::Codes::API>, B<Locale::SubCountry>,
-B<http://www.iso.org/iso/country_codes>,
-B<http://www.iso.org/iso/list-en1-semic-3.txt>,
-B<http://unstats.un.org/unsd/methods/m49/m49alpha.htm>,
-B<http://earth-info.nga.mil/gns/html/digraphs.htm>,
-B<http://www.iana.org/domains/>,
-B<https://www.cia.gov/library/publications/the-world-factbook/appendix/prin
-t_appendix-d.html>, B<http://www.statoids.com/wab.html>
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::Country_Codes - country codes for the
-Locale::Codes::Country module
-
-=over 4
-
-=item SYNOPSIS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::Country_Retired - retired country codes for the
-Locale::Codes::Country module
-
-=over 4
-
-=item SYNOPSIS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::Currency - standard codes for currency identification
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SUPPORTED CODE SETS
-
-B<alpha, LOCALE_CURR_ALPHA>, B<num, LOCALE_CURR_NUMERIC>
-
-=item ROUTINES
-
-B<code2currency ( CODE [,CODESET] )>, B<currency2code ( NAME [,CODESET] )>,
-B<currency_code2code ( CODE ,CODESET ,CODESET2 )>, B<all_currency_codes (
-[CODESET] )>, B<all_currency_names ( [CODESET] )>,
-B<Locale::Codes::Currency::rename_currency ( CODE ,NEW_NAME [,CODESET] )>,
-B<Locale::Codes::Currency::add_currency ( CODE ,NAME [,CODESET] )>,
-B<Locale::Codes::Currency::delete_currency ( CODE [,CODESET] )>,
-B<Locale::Codes::Currency::add_currency_alias ( NAME ,NEW_NAME )>,
-B<Locale::Codes::Currency::delete_currency_alias ( NAME )>,
-B<Locale::Codes::Currency::rename_currency_code ( CODE ,NEW_CODE
-[,CODESET] )>, B<Locale::Codes::Currency::add_currency_code_alias ( CODE
-,NEW_CODE [,CODESET] )>,
-B<Locale::Codes::Currency::delete_currency_code_alias ( CODE [,CODESET] )>
-
-=item SEE ALSO
-
-B<Locale::Codes>, B<Locale::Codes::API>,
-B<http://www.iso.org/iso/support/currency_codes_list-1.htm>
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::Currency_Codes - currency codes for the
-Locale::Codes::Currency module
-
-=over 4
-
-=item SYNOPSIS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::Currency_Retired - retired currency codes for the
-Locale::Codes::Currency module
-
-=over 4
-
-=item SYNOPSIS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::LangExt - standard codes for language extension
-identification
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SUPPORTED CODE SETS
-
-B<alpha>
-
-=item ROUTINES
-
-B<code2langext ( CODE [,CODESET] )>, B<langext2code ( NAME [,CODESET] )>,
-B<langext_code2code ( CODE ,CODESET ,CODESET2 )>, B<all_langext_codes (
-[CODESET] )>, B<all_langext_names ( [CODESET] )>,
-B<Locale::Codes::LangExt::rename_langext ( CODE ,NEW_NAME [,CODESET] )>,
-B<Locale::Codes::LangExt::add_langext ( CODE ,NAME [,CODESET] )>,
-B<Locale::Codes::LangExt::delete_langext ( CODE [,CODESET] )>,
-B<Locale::Codes::LangExt::add_langext_alias ( NAME ,NEW_NAME )>,
-B<Locale::Codes::LangExt::delete_langext_alias ( NAME )>,
-B<Locale::Codes::LangExt::rename_langext_code ( CODE ,NEW_CODE [,CODESET]
-)>, B<Locale::Codes::LangExt::add_langext_code_alias ( CODE ,NEW_CODE
-[,CODESET] )>, B<Locale::Codes::LangExt::delete_langext_code_alias ( CODE
-[,CODESET] )>
-
-=item SEE ALSO
-
-B<Locale::Codes>, B<Locale::Codes::API>,
-B<http://www.iana.org/assignments/language-subtag-registry>
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::LangExt_Codes - langext codes for the
-Locale::Codes::LangExt module
-
-=over 4
-
-=item SYNOPSIS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::LangExt_Retired - retired langext codes for the
-Locale::Codes::LangExt module
-
-=over 4
-
-=item SYNOPSIS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::LangFam - standard codes for language extension
-identification
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SUPPORTED CODE SETS
-
-B<alpha>
-
-=item ROUTINES
-
-B<code2langfam ( CODE [,CODESET] )>, B<langfam2code ( NAME [,CODESET] )>,
-B<langfam_code2code ( CODE ,CODESET ,CODESET2 )>, B<all_langfam_codes (
-[CODESET] )>, B<all_langfam_names ( [CODESET] )>,
-B<Locale::Codes::LangFam::rename_langfam ( CODE ,NEW_NAME [,CODESET] )>,
-B<Locale::Codes::LangFam::add_langfam ( CODE ,NAME [,CODESET] )>,
-B<Locale::Codes::LangFam::delete_langfam ( CODE [,CODESET] )>,
-B<Locale::Codes::LangFam::add_langfam_alias ( NAME ,NEW_NAME )>,
-B<Locale::Codes::LangFam::delete_langfam_alias ( NAME )>,
-B<Locale::Codes::LangFam::rename_langfam_code ( CODE ,NEW_CODE [,CODESET]
-)>, B<Locale::Codes::LangFam::add_langfam_code_alias ( CODE ,NEW_CODE
-[,CODESET] )>, B<Locale::Codes::LangFam::delete_langfam_code_alias ( CODE
-[,CODESET] )>
-
-=item SEE ALSO
-
-B<Locale::Codes>, B<Locale::Codes::API>,
-B<http://www.loc.gov/standards/iso639-5/id.php>
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::LangFam_Codes - langfam codes for the
-Locale::Codes::LangFam module
-
-=over 4
-
-=item SYNOPSIS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::LangFam_Retired - retired langfam codes for the
-Locale::Codes::LangFam module
-
-=over 4
-
-=item SYNOPSIS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::LangVar - standard codes for language variation
-identification
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SUPPORTED CODE SETS
-
-B<alpha>
-
-=item ROUTINES
-
-B<code2langvar ( CODE [,CODESET] )>, B<langvar2code ( NAME [,CODESET] )>,
-B<langvar_code2code ( CODE ,CODESET ,CODESET2 )>, B<all_langvar_codes (
-[CODESET] )>, B<all_langvar_names ( [CODESET] )>,
-B<Locale::Codes::LangVar::rename_langvar ( CODE ,NEW_NAME [,CODESET] )>,
-B<Locale::Codes::LangVar::add_langvar ( CODE ,NAME [,CODESET] )>,
-B<Locale::Codes::LangVar::delete_langvar ( CODE [,CODESET] )>,
-B<Locale::Codes::LangVar::add_langvar_alias ( NAME ,NEW_NAME )>,
-B<Locale::Codes::LangVar::delete_langvar_alias ( NAME )>,
-B<Locale::Codes::LangVar::rename_langvar_code ( CODE ,NEW_CODE [,CODESET]
-)>, B<Locale::Codes::LangVar::add_langvar_code_alias ( CODE ,NEW_CODE
-[,CODESET] )>, B<Locale::Codes::LangVar::delete_langvar_code_alias ( CODE
-[,CODESET] )>
-
-=item SEE ALSO
-
-B<Locale::Codes>, B<Locale::Codes::API>,
-B<http://www.iana.org/assignments/language-subtag-registry>
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::LangVar_Codes - langvar codes for the
-Locale::Codes::LangVar module
-
-=over 4
-
-=item SYNOPSIS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::LangVar_Retired - retired langvar codes for the
-Locale::Codes::LangVar module
-
-=over 4
-
-=item SYNOPSIS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::Language - standard codes for language identification
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SUPPORTED CODE SETS
-
-B<alpha-2, LOCALE_LANG_ALPHA_2>, B<alpha-3, LOCALE_LANG_ALPHA_3>, B<term,
-LOCALE_LANG_TERM>
-
-=item ROUTINES
-
-B<code2language ( CODE [,CODESET] )>, B<language2code ( NAME [,CODESET] )>,
-B<language_code2code ( CODE ,CODESET ,CODESET2 )>, B<all_language_codes (
-[CODESET] )>, B<all_language_names ( [CODESET] )>,
-B<Locale::Codes::Language::rename_language ( CODE ,NEW_NAME [,CODESET] )>,
-B<Locale::Codes::Language::add_language ( CODE ,NAME [,CODESET] )>,
-B<Locale::Codes::Language::delete_language ( CODE [,CODESET] )>,
-B<Locale::Codes::Language::add_language_alias ( NAME ,NEW_NAME )>,
-B<Locale::Codes::Language::delete_language_alias ( NAME )>,
-B<Locale::Codes::Language::rename_language_code ( CODE ,NEW_CODE
-[,CODESET] )>, B<Locale::Codes::Language::add_language_code_alias ( CODE
-,NEW_CODE [,CODESET] )>,
-B<Locale::Codes::Language::delete_language_code_alias ( CODE [,CODESET] )>
-
-=item SEE ALSO
-
-B<Locale::Codes>, B<Locale::Codes::API>,
-B<http://www.loc.gov/standards/iso639-2/>,
-B<http://www.loc.gov/standards/iso639-5/>,
-B<http://www.iana.org/assignments/language-subtag-registry>
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::Language_Codes - language codes for the
-Locale::Codes::Language module
-
-=over 4
-
-=item SYNOPSIS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::Language_Retired - retired language codes for the
-Locale::Codes::Language module
-
-=over 4
-
-=item SYNOPSIS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::Script - standard codes for script identification
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SUPPORTED CODE SETS
-
-B<alpha, LOCALE_SCRIPT_ALPHA>, B<num, LOCALE_SCRIPT_NUMERIC>
-
-=item ROUTINES
-
-B<code2script ( CODE [,CODESET] )>, B<script2code ( NAME [,CODESET] )>,
-B<script_code2code ( CODE ,CODESET ,CODESET2 )>, B<all_script_codes (
-[CODESET] )>, B<all_script_names ( [CODESET] )>,
-B<Locale::Codes::Script::rename_script ( CODE ,NEW_NAME [,CODESET] )>,
-B<Locale::Codes::Script::add_script ( CODE ,NAME [,CODESET] )>,
-B<Locale::Codes::Script::delete_script ( CODE [,CODESET] )>,
-B<Locale::Codes::Script::add_script_alias ( NAME ,NEW_NAME )>,
-B<Locale::Codes::Script::delete_script_alias ( NAME )>,
-B<Locale::Codes::Script::rename_script_code ( CODE ,NEW_CODE [,CODESET]
-)>, B<Locale::Codes::Script::add_script_code_alias ( CODE ,NEW_CODE
-[,CODESET] )>, B<Locale::Codes::Script::delete_script_code_alias ( CODE
-[,CODESET] )>
-
-=item SEE ALSO
-
-B<Locale::Codes>, B<Locale::Codes::API>,
-B<http://www.unicode.org/iso15924/>,
-B<http://www.iana.org/assignments/language-subtag-registry>
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::Script_Codes - script codes for the
-Locale::Codes::Script module
-
-=over 4
-
-=item SYNOPSIS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Codes::Script_Retired - retired script codes for the
-Locale::Codes::Script module
-
-=over 4
-
-=item SYNOPSIS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Country - standard codes for country identification
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SUPPORTED CODE SETS
-
-B<alpha-2, LOCALE_CODE_ALPHA_2>, B<alpha-3, LOCALE_CODE_ALPHA_3>,
-B<numeric, LOCALE_CODE_NUMERIC>, B<fips-10, LOCALE_CODE_FIPS>, B<dom,
-LOCALE_CODE_DOM>
-
-=item ROUTINES
-
-B<code2country ( CODE [,CODESET] )>, B<country2code ( NAME [,CODESET] )>,
-B<country_code2code ( CODE ,CODESET ,CODESET2 )>, B<all_country_codes (
-[CODESET] )>, B<all_country_names ( [CODESET] )>,
-B<Locale::Country::rename_country ( CODE ,NEW_NAME [,CODESET] )>,
-B<Locale::Country::add_country ( CODE ,NAME [,CODESET] )>,
-B<Locale::Country::delete_country ( CODE [,CODESET] )>,
-B<Locale::Country::add_country_alias ( NAME ,NEW_NAME )>,
-B<Locale::Country::delete_country_alias ( NAME )>,
-B<Locale::Country::rename_country_code ( CODE ,NEW_CODE [,CODESET] )>,
-B<Locale::Country::add_country_code_alias ( CODE ,NEW_CODE [,CODESET] )>,
-B<Locale::Country::delete_country_code_alias ( CODE [,CODESET] )>,
-B<alias_code ( ALIAS, CODE [,CODESET] )>
-
-=item SEE ALSO
-
-B<Locale::Codes>, B<Locale::Codes::API>, B<Locale::SubCountry>,
-B<http://www.iso.org/iso/country_codes>,
-B<http://www.iso.org/iso/list-en1-semic-3.txt>,
-B<http://unstats.un.org/unsd/methods/m49/m49alpha.htm>,
-B<http://earth-info.nga.mil/gns/html/digraphs.htm>,
-B<http://www.iana.org/domains/>,
-B<https://www.cia.gov/library/publications/the-world-factbook/appendix/prin
-t_appendix-d.html>, B<http://www.statoids.com/wab.html>
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Currency - standard codes for currency identification
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SUPPORTED CODE SETS
-
-B<alpha, LOCALE_CURR_ALPHA>, B<num, LOCALE_CURR_NUMERIC>
-
-=item ROUTINES
-
-B<code2currency ( CODE [,CODESET] )>, B<currency2code ( NAME [,CODESET] )>,
-B<currency_code2code ( CODE ,CODESET ,CODESET2 )>, B<all_currency_codes (
-[CODESET] )>, B<all_currency_names ( [CODESET] )>,
-B<Locale::Currency::rename_currency ( CODE ,NEW_NAME [,CODESET] )>,
-B<Locale::Currency::add_currency ( CODE ,NAME [,CODESET] )>,
-B<Locale::Currency::delete_currency ( CODE [,CODESET] )>,
-B<Locale::Currency::add_currency_alias ( NAME ,NEW_NAME )>,
-B<Locale::Currency::delete_currency_alias ( NAME )>,
-B<Locale::Currency::rename_currency_code ( CODE ,NEW_CODE [,CODESET] )>,
-B<Locale::Currency::add_currency_code_alias ( CODE ,NEW_CODE [,CODESET]
-)>, B<Locale::Currency::delete_currency_code_alias ( CODE [,CODESET] )>
-
-=item SEE ALSO
-
-B<Locale::Codes>, B<Locale::Codes::API>,
-B<http://www.iso.org/iso/support/currency_codes_list-1.htm>
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Language - standard codes for language identification
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SUPPORTED CODE SETS
-
-B<alpha-2, LOCALE_LANG_ALPHA_2>, B<alpha-3, LOCALE_LANG_ALPHA_3>, B<term,
-LOCALE_LANG_TERM>
-
-=item ROUTINES
-
-B<code2language ( CODE [,CODESET] )>, B<language2code ( NAME [,CODESET] )>,
-B<language_code2code ( CODE ,CODESET ,CODESET2 )>, B<all_language_codes (
-[CODESET] )>, B<all_language_names ( [CODESET] )>,
-B<Locale::Language::rename_language ( CODE ,NEW_NAME [,CODESET] )>,
-B<Locale::Language::add_language ( CODE ,NAME [,CODESET] )>,
-B<Locale::Language::delete_language ( CODE [,CODESET] )>,
-B<Locale::Language::add_language_alias ( NAME ,NEW_NAME )>,
-B<Locale::Language::delete_language_alias ( NAME )>,
-B<Locale::Language::rename_language_code ( CODE ,NEW_CODE [,CODESET] )>,
-B<Locale::Language::add_language_code_alias ( CODE ,NEW_CODE [,CODESET]
-)>, B<Locale::Language::delete_language_code_alias ( CODE [,CODESET] )>
-
-=item SEE ALSO
-
-B<Locale::Codes>, B<Locale::Codes::API>,
-B<http://www.loc.gov/standards/iso639-2/>,
-B<http://www.loc.gov/standards/iso639-5/>,
-B<http://www.iana.org/assignments/language-subtag-registry>
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Locale::Maketext - framework for localization
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item QUICK OVERVIEW
-
-=item METHODS
-
-=over 4
-
-=item Construction Methods
-
-=item The "maketext" Method
-
-$lh->fail_with I<or> $lh->fail_with(I<PARAM>), $lh->failure_handler_auto
-
-=item Utility Methods
-
-$language->quant($number, $singular), $language->quant($number, $singular,
-$plural), $language->quant($number, $singular, $plural, $negative),
-$language->numf($number), $language->numerate($number, $singular, $plural,
-$negative), $language->sprintf($format, @items), $language->language_tag(),
-$language->encoding()
-
-=item Language Handle Attributes and Internals
-
-=back
-
-=item LANGUAGE CLASS HIERARCHIES
-
-=item ENTRIES IN EACH LEXICON
-
-=item BRACKET NOTATION
-
-=item AUTO LEXICONS
-
-=item READONLY LEXICONS
-
-=item CONTROLLING LOOKUP FAILURE
-
-=item HOW TO USE MAKETEXT
-
-=item SEE ALSO
-
-=item COPYRIGHT AND DISCLAIMER
-
-=item AUTHOR
-
-=back
-
-=head2 Locale::Maketext::Cookbook - recipes for using Locale::Maketext
-
-=over 4
-
-=item INTRODUCTION
-
-=item ONESIDED LEXICONS
-
-=item DECIMAL PLACES IN NUMBER FORMATTING
-
-=back
-
-=head2 Locale::Maketext::Guts - Deprecated module to load Locale::Maketext
-utf8 code
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 Locale::Maketext::GutsLoader - Deprecated module to load
-Locale::Maketext utf8 code
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 Locale::Maketext::Simple - Simple interface to
-Locale::Maketext::Lexicon
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item OPTIONS
-
-=over 4
-
-=item Class
-
-=item Path
-
-=item Style
-
-=item Export
-
-=item Subclass
-
-=item Decode
-
-=item Encoding
-
-=back
-
-=back
-
-=over 4
-
-=item ACKNOWLEDGMENTS
-
-=item SEE ALSO
-
-=item AUTHORS
-
-=item COPYRIGHT
-
-=over 4
-
-=item The "MIT" License
-
-=back
-
-=back
-
-=head2 Locale::Maketext::TPJ13 -- article about software localization
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Localization and Perl: gettext breaks, Maketext fixes
-
-=over 4
-
-=item A Localization Horror Story: It Could Happen To You
-
-=item The Linguistic View
-
-=item Breaking gettext
-
-=item Replacing gettext
-
-=item Buzzwords: Abstraction and Encapsulation
-
-=item Buzzword: Isomorphism
-
-=item Buzzword: Inheritance
-
-=item Buzzword: Concision
-
-=item The Devil in the Details
-
-=item The Proof in the Pudding: Localizing Web Sites
-
-=item References
-
-=back
-
-=back
-
-=head2 Locale::Script - standard codes for script identification
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SUPPORTED CODE SETS
-
-B<alpha, LOCALE_SCRIPT_ALPHA>, B<num, LOCALE_SCRIPT_NUMERIC>
-
-=item ROUTINES
-
-B<code2script ( CODE [,CODESET] )>, B<script2code ( NAME [,CODESET] )>,
-B<script_code2code ( CODE ,CODESET ,CODESET2 )>, B<all_script_codes (
-[CODESET] )>, B<all_script_names ( [CODESET] )>,
-B<Locale::Script::rename_script ( CODE ,NEW_NAME [,CODESET] )>,
-B<Locale::Script::add_script ( CODE ,NAME [,CODESET] )>,
-B<Locale::Script::delete_script ( CODE [,CODESET] )>,
-B<Locale::Script::add_script_alias ( NAME ,NEW_NAME )>,
-B<Locale::Script::delete_script_alias ( NAME )>,
-B<Locale::Script::rename_script_code ( CODE ,NEW_CODE [,CODESET] )>,
-B<Locale::Script::add_script_code_alias ( CODE ,NEW_CODE [,CODESET] )>,
-B<Locale::Script::delete_script_code_alias ( CODE [,CODESET] )>
-
-=item SEE ALSO
-
-B<Locale::Codes>, B<Locale::Codes::API>,
-B<http://www.unicode.org/iso15924/>,
-B<http://www.iana.org/assignments/language-subtag-registry>
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Log::Message - A generic message storing mechanism;
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Hierarchy
-
-Log::Message, Log::Message::Item, Log::Message::Handlers,
-Log::Message::Config
-
-=item Options
-
-config, private, verbose, tag, level, remove, chrono
-
-=back
-
-=over 4
-
-=item Methods
-
-=over 4
-
-=item new
-
-=back
-
-=back
-
-=over 4
-
-=item store
-
-message, tag, level, extra
-
-=back
-
-=over 4
-
-=item retrieve
-
-tag, level, message, amount, chrono, remove
-
-=back
-
-=over 4
-
-=item first
-
-=back
-
-=over 4
-
-=item last
-
-=back
-
-=over 4
-
-=item flush
-
-=back
-
-=over 4
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item Acknowledgements
-
-=item COPYRIGHT
-
-=back
-
-=head2 Log::Message::Config - Configuration options for Log::Message
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item Acknowledgements
-
-=item COPYRIGHT
-
-=back
-
-=head2 Log::Message::Handlers - Message handlers for Log::Message
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Default Handlers
-
-=over 4
-
-=item log
-
-=back
-
-=back
-
-=over 4
-
-=item carp
-
-=back
-
-=over 4
-
-=item croak
-
-=back
-
-=over 4
-
-=item cluck
-
-=back
-
-=over 4
-
-=item confess
-
-=back
-
-=over 4
-
-=item die
-
-=back
-
-=over 4
-
-=item warn
-
-=back
-
-=over 4
-
-=item trace
-
-=back
-
-=over 4
-
-=item Custom Handlers
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item Acknowledgements
-
-=item COPYRIGHT
-
-=back
-
-=head2 Log::Message::Item - Message objects for Log::Message
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Methods and Accessors
-
-=over 4
-
-=item remove
-
-=item id
-
-=item when
-
-=item message
-
-=item level
-
-=item tag
-
-=item shortmess
-
-=item longmess
-
-=item parent
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item Acknowledgements
-
-=item COPYRIGHT
-
-=back
-
-=head2 Log::Message::Simple - Simplified interface to Log::Message
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item FUNCTIONS
-
-=over 4
-
-=item msg("message string" [,VERBOSE])
-
-=item debug("message string" [,VERBOSE])
-
-=item error("error string" [,VERBOSE])
-
-=back
-
-=back
-
-=over 4
-
-=item carp();
-
-=item croak();
-
-=item confess();
-
-=item cluck();
-
-=back
-
-=over 4
-
-=item CLASS METHODS
-
-=over 4
-
-=item Log::Message::Simple->stack()
-
-=item Log::Message::Simple->stack_as_string([TRACE])
-
-=item Log::Message::Simple->flush()
-
-=back
-
-=back
-
-=over 4
-
-=item GLOBAL VARIABLES
-
-$ERROR_FH, $MSG_FH, $DEBUG_FH, $STACKTRACE_ON_ERROR
-
-=back
-
-=head2 MIME::Base64 - Encoding and decoding of base64 strings
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-encode_base64( $bytes ), encode_base64( $bytes, $eol );, decode_base64(
-$str ), encode_base64url( $bytes ), decode_base64url( $str ),
-encoded_base64_length( $bytes ), encoded_base64_length( $bytes, $eol ),
-decoded_base64_length( $str )
-
-=item EXAMPLES
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 MIME::QuotedPrint - Encoding and decoding of quoted-printable
-strings
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-encode_qp( $str), encode_qp( $str, $eol), encode_qp( $str, $eol, $binmode
-), decode_qp( $str )
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 Math::BigFloat - Arbitrary size floating point math package
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Canonical notation
-
-=item Output
-
-=item C<mantissa()>, C<exponent()> and C<parts()>
-
-=item Accuracy vs. Precision
-
-=item Rounding
-
-ffround ( +$scale ), ffround ( -$scale ), ffround ( 0 ), fround ( +$scale
-), fround ( -$scale ) and fround ( 0 )
-
-=back
-
-=item METHODS
-
-=over 4
-
-=item accuracy
-
-=item precision()
-
-=item bexp()
-
-=item bnok()
-
-=item bpi()
-
-=item bcos()
-
-=item bsin()
-
-=item batan2()
-
-=item batan()
-
-=item bmuladd()
-
-=back
-
-=item Autocreating constants
-
-=over 4
-
-=item Math library
-
-=item Using Math::BigInt::Lite
-
-=back
-
-=item EXPORTS
-
-=item BUGS
-
-=item CAVEATS
-
-stringify, bstr(), bdiv, brsft, Modifying and =, bpow, precision() vs.
-accuracy()
-
-=item SEE ALSO
-
-=item LICENSE
-
-=item AUTHORS
-
-=back
-
-=head2 Math::BigInt - Arbitrary size integer/float math package
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-Input, Output
-
-=item METHODS
-
-=over 4
-
-=item config()
-
-=item accuracy()
-
-=item precision()
-
-=item brsft()
-
-=item new()
-
-=item from_oct()
-
-=item from_hex()
-
-=item from_bin()
-
-=item bnan()
-
-=item bzero()
-
-=item binf()
-
-=item bone()
-
-=item is_one()/is_zero()/is_nan()/is_inf()
-
-=item is_pos()/is_neg()/is_positive()/is_negative()
-
-=item is_odd()/is_even()/is_int()
-
-=item bcmp()
-
-=item bacmp()
-
-=item sign()
-
-=item digit()
-
-=item bneg()
-
-=item babs()
-
-=item bsgn()
-
-=item bnorm()
-
-=item bnot()
-
-=item binc()
-
-=item bdec()
-
-=item badd()
-
-=item bsub()
-
-=item bmul()
-
-=item bmuladd()
-
-=item bdiv()
-
-=item bmod()
-
-=item bmodinv()
-
-=item bmodpow()
-
-=item bpow()
-
-=item blog()
-
-=item bexp()
-
-=item bnok()
-
-=item bpi()
-
-=item bcos()
-
-=item bsin()
-
-=item batan2()
-
-=item batan()
-
-=item blsft()
-
-=item brsft()
-
-=item band()
-
-=item bior()
-
-=item bxor()
-
-=item bnot()
-
-=item bsqrt()
-
-=item broot()
-
-=item bfac()
-
-=item round()
-
-=item bround()
-
-=item bfround()
-
-=item bfloor()
-
-=item bceil()
-
-=item bgcd()
-
-=item blcm()
-
-=item exponent()
-
-=item mantissa()
-
-=item parts()
-
-=item copy()
-
-=item as_int()/as_number()
-
-=item bstr()
-
-=item bsstr()
-
-=item as_hex()
-
-=item as_bin()
-
-=item as_oct()
-
-=item numify()
-
-=item modify()
-
-=item upgrade()/downgrade()
-
-=item div_scale()
-
-=item round_mode()
-
-=back
-
-=item ACCURACY and PRECISION
-
-=over 4
-
-=item Precision P
-
-=item Accuracy A
-
-=item Fallback F
-
-=item Rounding mode R
-
-'trunc', 'even', 'odd', '+inf', '-inf', 'zero', 'common', Precision,
-Accuracy (significant digits), Setting/Accessing, Creating numbers, Usage,
-Precedence, Overriding globals, Local settings, Rounding, Default values,
-Remarks
-
-=back
-
-=item Infinity and Not a Number
-
-oct()/hex(), log(-inf), exp(), cos(), sin(), atan2()
-
-=item INTERNALS
-
-=over 4
-
-=item MATH LIBRARY
-
-=item SIGN
-
-=item mantissa(), exponent() and parts()
-
-=back
-
-=item EXAMPLES
-
-=item Autocreating constants
-
-=item PERFORMANCE
-
-=over 4
-
-=item Alternative math libraries
-
-=back
-
-=item SUBCLASSING
-
-=over 4
-
-=item Subclassing Math::BigInt
-
-=back
-
-=item UPGRADING
-
-=over 4
-
-=item Auto-upgrade
-
-bsqrt(), div(), blog(), bexp()
-
-=back
-
-=item EXPORTS
-
-=item CAVEATS
-
-bstr(), bsstr() and 'cmp', int(), length, bdiv, infinity handling,
-Modifying and =, bpow, Overloading -$x, Mixing different object types,
-bsqrt(), brsft()
-
-=item LICENSE
-
-=item SEE ALSO
-
-=item AUTHORS
-
-=back
-
-=head2 Math::BigInt::Calc - Pure Perl module to support Math::BigInt
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item THE Math::BigInt API
-
-=over 4
-
-=item General Notes
-
-=item API version 1
-
-I<api_version()>, I<_new(STR)>, I<_zero()>, I<_one()>, I<_two()>,
-I<_ten()>, I<_from_bin(STR)>, I<_from_oct(STR)>, I<_from_hex(STR)>,
-I<_add(OBJ1, OBJ2)>, I<_mul(OBJ1, OBJ2)>, I<_div(OBJ1, OBJ2)>, I<_sub(OBJ1,
-OBJ2, FLAG)>, I<_sub(OBJ1, OBJ2)>, I<_dec(OBJ)>, I<_inc(OBJ)>, I<_mod(OBJ1,
-OBJ2)>, I<_sqrt(OBJ)>, I<_root(OBJ, N)>, I<_fac(OBJ)>, I<_pow(OBJ1, OBJ2)>,
-I<_modinv(OBJ1, OBJ2)>, I<_modpow(OBJ1, OBJ2, OBJ3)>, I<_rsft(OBJ, N, B)>,
-I<_lsft(OBJ, N, B)>, I<_log_int(OBJ, B)>, I<_gcd(OBJ1, OBJ2)>, I<_and(OBJ1,
-OBJ2)>, I<_or(OBJ1, OBJ2)>, I<_xor(OBJ1, OBJ2)>, I<_is_zero(OBJ)>,
-I<_is_one(OBJ)>, I<_is_two(OBJ)>, I<_is_ten(OBJ)>, I<_is_even(OBJ)>,
-I<_is_odd(OBJ)>, I<_acmp(OBJ1, OBJ2)>, I<_str(OBJ)>, I<_as_bin(OBJ)>,
-I<_as_oct(OBJ)>, I<_as_hex(OBJ)>, I<_num(OBJ)>, I<_copy(OBJ)>,
-I<_len(OBJ)>, I<_zeros(OBJ)>, I<_digit(OBJ, N)>, I<_check(OBJ)>
-
-=item API version 2
-
-I<_1ex(N)>, I<_nok(OBJ1, OBJ2)>, I<_alen(OBJ)>
-
-=item API optional methods
-
-I<_signed_or(OBJ1, OBJ2, SIGN1, SIGN2)>, I<_signed_and(OBJ1, OBJ2, SIGN1,
-SIGN2)>, I<_signed_xor(OBJ1, OBJ2, SIGN1, SIGN2)>
-
-=back
-
-=item WRAP YOUR OWN
-
-=item LICENSE
-
-=item AUTHORS
-
-=item SEE ALSO
-
-=back
-
-=head2 Math::BigInt::CalcEmu - Emulate low-level math with BigInt code
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item __emu_bxor
-
-=item __emu_band
-
-=item __emu_bior
-
-=back
-
-=item LICENSE
-
-=item AUTHORS
-
-=item SEE ALSO
-
-=back
-
-=head2 Math::BigInt::FastCalc - Math::BigInt::Calc with some XS for more
-speed
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item STORAGE
-
-=item METHODS
-
-=item LICENSE
-
-=item AUTHORS
-
-=item SEE ALSO
-
-=back
-
-=head2 Math::BigRat - Arbitrary big rational numbers
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item MATH LIBRARY
-
-=back
-
-=item METHODS
-
-=over 4
-
-=item new()
-
-=item numerator()
-
-=item denominator()
-
-=item parts()
-
-=item numify()
-
-=item as_int()/as_number()
-
-=item as_float()
-
-=item as_hex()
-
-=item as_bin()
-
-=item as_oct()
-
-=item from_hex()/from_bin()/from_oct()
-
-=item length()
-
-=item digit()
-
-=item bnorm()
-
-=item bfac()
-
-=item bround()/round()/bfround()
-
-=item bmod()
-
-=item bneg()
-
-=item is_one()
-
-=item is_zero()
-
-=item is_pos()/is_positive()
-
-=item is_neg()/is_negative()
-
-=item is_int()
-
-=item is_odd()
-
-=item is_even()
-
-=item bceil()
-
-=item bfloor()
-
-=item bsqrt()
-
-=item broot()
-
-=item badd()/bmul()/bsub()/bdiv()/bdec()/binc()
-
-=item copy()
-
-=item bstr()/bsstr()
-
-=item bacmp()/bcmp()
-
-=item blsft()/brsft()
-
-=item bpow()
-
-=item bexp()
-
-=item bnok()
-
-=item config()
-
-=item objectify()
-
-=back
-
-=item BUGS
-
-inf handling (partial), NaN handling (partial), rounding (not implemented
-except for bceil/bfloor), $x ** $y where $y is not an integer, bmod(),
-blog(), bmodinv() and bmodpow() (partial)
-
-=item LICENSE
-
-=item SEE ALSO
-
-=item AUTHORS
-
-=back
-
-=head2 Math::Complex - complex numbers and associated mathematical
-functions
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item OPERATIONS
-
-=item CREATION
-
-=item DISPLAYING
-
-=over 4
-
-=item CHANGED IN PERL 5.6
-
-=back
-
-=item USAGE
-
-=item CONSTANTS
-
-=over 4
-
-=item PI
-
-=item Inf
-
-=back
-
-=item ERRORS DUE TO DIVISION BY ZERO OR LOGARITHM OF ZERO
-
-=item ERRORS DUE TO INDIGESTIBLE ARGUMENTS
-
-=item BUGS
-
-=item SEE ALSO
-
-=item AUTHORS
-
-=item LICENSE
-
-=back
-
-=head2 Math::Trig - trigonometric functions
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item TRIGONOMETRIC FUNCTIONS
-
-B<tan>
-
-=over 4
-
-=item ERRORS DUE TO DIVISION BY ZERO
-
-=item SIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS
-
-=back
-
-=item PLANE ANGLE CONVERSIONS
-
-deg2rad, grad2rad, rad2deg, grad2deg, deg2grad, rad2grad, rad2rad, deg2deg,
-grad2grad
-
-=item RADIAL COORDINATE CONVERSIONS
-
-=over 4
-
-=item COORDINATE SYSTEMS
-
-=item 3-D ANGLE CONVERSIONS
-
-cartesian_to_cylindrical, cartesian_to_spherical, cylindrical_to_cartesian,
-cylindrical_to_spherical, spherical_to_cartesian, spherical_to_cylindrical
-
-=back
-
-=item GREAT CIRCLE DISTANCES AND DIRECTIONS
-
-=over 4
-
-=item great_circle_distance
-
-=item great_circle_direction
-
-=item great_circle_bearing
-
-=item great_circle_destination
-
-=item great_circle_midpoint
-
-=item great_circle_waypoint
-
-=back
-
-=item EXAMPLES
-
-=over 4
-
-=item CAVEAT FOR GREAT CIRCLE FORMULAS
-
-=item Real-valued asin and acos
-
-asin_real, acos_real
-
-=back
-
-=item BUGS
-
-=item AUTHORS
-
-=item LICENSE
-
-=back
-
-=head2 Memoize - Make functions faster by trading space for time
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item DETAILS
-
-=item OPTIONS
-
-=over 4
-
-=item INSTALL
-
-=item NORMALIZER
-
-=item C<SCALAR_CACHE>, C<LIST_CACHE>
-
-C<MEMORY>, C<HASH>, C<TIE>, C<FAULT>, C<MERGE>
-
-=back
-
-=item OTHER FACILITIES
-
-=over 4
-
-=item C<unmemoize>
-
-=item C<flush_cache>
-
-=back
-
-=item CAVEATS
-
-=item PERSISTENT CACHE SUPPORT
-
-=item EXPIRATION SUPPORT
-
-=item BUGS
-
-=item MAILING LIST
-
-=item AUTHOR
-
-=item COPYRIGHT AND LICENSE
-
-=item THANK YOU
-
-=back
-
-=head2 Memoize::AnyDBM_File - glue to provide EXISTS for AnyDBM_File for
-Storable use
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=head2 Memoize::Expire - Plug-in module for automatic expiration of
-memoized values
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item INTERFACE
-
- TIEHASH, EXISTS, STORE
-
-=item ALTERNATIVES
-
-=item CAVEATS
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Memoize::ExpireFile - test for Memoize expiration semantics
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=head2 Memoize::ExpireTest - test for Memoize expiration semantics
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=head2 Memoize::NDBM_File - glue to provide EXISTS for NDBM_File for
-Storable use
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=head2 Memoize::SDBM_File - glue to provide EXISTS for SDBM_File for
-Storable use
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=head2 Memoize::Storable - store Memoized data in Storable database
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=head2 Module::Build - Build and install Perl modules
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item GUIDE TO DOCUMENTATION
-
-General Usage (L<Module::Build>), Authoring Reference
-(L<Module::Build::Authoring>), API Reference (L<Module::Build::API>),
-Cookbook (L<Module::Build::Cookbook>)
-
-=item ACTIONS
-
-build, clean, code, config_data, diff, dist, distcheck, distclean, distdir,
-distinstall, distmeta, distsign, disttest, docs, fakeinstall, help, html,
-install, installdeps, manifest, manifest_skip, manpages, pardist, ppd,
-ppmdist, prereq_data, prereq_report, pure_install, realclean, retest,
-skipcheck, test, testall, testcover, testdb, testpod, testpodcoverage,
-versioninstall
-
-=item OPTIONS
-
-=over 4
-
-=item Command Line Options
-
-quiet, verbose, cpan_client, use_rcfile, allow_mb_mismatch, debug
-
-=item Default Options File (F<.modulebuildrc>)
-
-=item Environment variables
-
-MODULEBUILDRC, PERL_MB_OPT
-
-=back
-
-=item INSTALL PATHS
-
-lib, arch, script, bin, bindoc, libdoc, binhtml, libhtml, installdirs,
-install_path, install_base, destdir, prefix
-
-=item MOTIVATIONS
-
-+, +
-
-=item TO DO
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::API - API Reference for Module Authors
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item CONSTRUCTORS
-
-current(), new(), add_to_cleanup, auto_configure_requires, auto_features,
-autosplit, build_class, build_requires, create_packlist, c_source,
-conflicts, create_license, create_makefile_pl, create_readme,
-dist_abstract, dist_author, dist_name, dist_suffix, dist_version,
-dist_version_from, dynamic_config, extra_compiler_flags,
-extra_linker_flags, get_options, type, store, default, include_dirs,
-install_path, installdirs, license, apache, apache_1_1, artistic,
-artistic_2, bsd, gpl, lgpl, mit, mozilla, open_source, perl, restrictive,
-unrestricted, meta_add, meta_merge, module_name, needs_compiler, PL_files,
-pm_files, pod_files, recommends, recursive_test_files, release_status,
-requires, script_files, share_dir, sign, test_files, use_tap_harness,
-tap_harness_args, xs_files, new_from_context(%args), resume(), subclass(),
-add_property, C<default>, C<check>, property_error
-
-=item METHODS
-
-add_build_element($type), add_to_cleanup(@files), args(),
-autosplit_file($from, $to), base_dir(), build_requires(), can_action(
-$action ), cbuilder(), check_installed_status($module, $version),
-check_installed_version($module, $version), compare_versions($v1, $op,
-$v2), config($key), config($key, $value), config() [deprecated],
-config_data($name), config_data($name => $value), conflicts(),
-contains_pod($file) [deprecated], copy_if_modified(%parameters),
-create_build_script(), current_action(), depends_on(@actions),
-dir_contains($first_dir, $second_dir), dispatch($action, %args),
-dist_dir(), dist_name(), dist_version(), do_system($cmd, @args),
-feature($name), feature($name => $value), fix_shebang_line(@files),
-have_c_compiler(), install_base_relpaths(), install_base_relpaths($type),
-install_base_relpaths($type => $path), install_destination($type),
-install_path(), install_path($type), install_path($type => $path),
-install_types(), invoked_action(), notes(), notes($key), notes($key =>
-$value), orig_dir(), os_type(), is_vmsish(), is_windowsish(), is_unixish(),
-prefix_relpaths(), prefix_relpaths($installdirs),
-prefix_relpaths($installdirs, $type), prefix_relpaths($installdirs, $type
-=> $path), get_metadata(), prepare_metadata() [deprecated],
-prereq_failures(), prereq_data(), prereq_report(), prompt($message,
-$default), recommends(), requires(), rscan_dir($dir, $pattern),
-runtime_params(), runtime_params($key), script_files(),
-up_to_date($source_file, $derived_file), up_to_date(\@source_files,
-\@derived_files), y_n($message, $default)
-
-=item Autogenerated Accessors
-
-PL_files(), allow_mb_mismatch(), auto_configure_requires(), autosplit(),
-base_dir(), bindoc_dirs(), blib(), build_bat(), build_class(),
-build_elements(), build_requires(), build_script(), bundle_inc(),
-bundle_inc_preload(), c_source(), config_dir(), configure_requires(),
-conflicts(), cpan_client(), create_license(), create_makefile_pl(),
-create_packlist(), create_readme(), debug(), debugger(), destdir(),
-dynamic_config(), get_options(), html_css(), include_dirs(),
-install_base(), installdirs(), libdoc_dirs(), license(), magic_number(),
-mb_version(), meta_add(), meta_merge(), metafile(), metafile2(),
-module_name(), mymetafile(), mymetafile2(), needs_compiler(), orig_dir(),
-perl(), pm_files(), pod_files(), pollute(), prefix(),
-prereq_action_types(), program_name(), quiet(), recommends(),
-recurse_into(), recursive_test_files(), requires(), scripts(), sign(),
-tap_harness_args(), test_file_exts(), use_rcfile(), use_tap_harness(),
-verbose(), xs_files()
-
-=back
-
-=item MODULE METADATA
-
-keywords, resources
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Authoring - Authoring Module::Build modules
-
-=over 4
-
-=item DESCRIPTION
-
-=item STRUCTURE
-
-=item SUBCLASSING
-
-=item PREREQUISITES
-
-=over 4
-
-=item Types of prerequisites
-
-configure_requires, build_requires, requires, recommends, conflicts
-
-=item Format of prerequisites
-
-=item XS Extensions
-
-=back
-
-=item SAVING CONFIGURATION INFORMATION
-
-=item STARTING MODULE DEVELOPMENT
-
-=item AUTOMATION
-
-=item MIGRATION
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Base - Default methods for Module::Build
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Bundling - How to bundle Module::Build with a
-distribution
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item BUNDLING OTHER CONFIGURATION DEPENDENCIES
-
-=over 4
-
-=item WARNING -- How to Manage Dependency Chains
-
-=back
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Compat - Compatibility with ExtUtils::MakeMaker
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-create_makefile_pl($style, $build), traditional, small, passthrough
-(DEPRECATED), run_build_pl(args => \@ARGV), args, script, write_makefile(),
-makefile
-
-=item SCENARIOS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::ConfigData - Configuration for Module::Build
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-config($name), feature($name), set_config($name, $value),
-set_feature($name, $value), config_names(), feature_names(),
-auto_feature_names(), write()
-
-=item AUTHOR
-
-=back
-
-=head2 Module::Build::Cookbook - Examples of Module::Build Usage
-
-=over 4
-
-=item DESCRIPTION
-
-=item BASIC RECIPES
-
-=over 4
-
-=item Installing modules that use Module::Build
-
-=item Modifying Config.pm values
-
-=item Installing modules using the programmatic interface
-
-=item Installing to a temporary directory
-
-=item Installing to a non-standard directory
-
-=item Installing in the same location as ExtUtils::MakeMaker
-
-=item Running a single test file
-
-=back
-
-=item ADVANCED RECIPES
-
-=over 4
-
-=item Making a CPAN.pm-compatible distribution
-
-=item Changing the order of the build process
-
-=item Adding new file types to the build process
-
-=item Adding new elements to the install process
-
-=back
-
-=item EXAMPLES ON CPAN
-
-=over 4
-
-=item SVN-Notify-Mirror
-
-1. Using C<auto_features>, I check to see whether two optional modules are
-available - SVN::Notify::Config and Net::SSH;, 2. If the S::N::Config
-module is loaded, I automatically generate test files for it during Build
-(using the C<PL_files> property), 3. If the C<ssh_feature> is available, I
-ask if the user wishes to perform the ssh tests (since it requires a little
-preliminary setup);, 4. Only if the user has C<ssh_feature> and answers yes
-to the testing, do I generate a test file
-
-=item Modifying an action
-
-=item Adding an action
-
-=item Bundling Module::Build
-
-=back
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::ModuleInfo - DEPRECATED
-
-=over 4
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Notes - Create persistent distribution configuration
-modules
-
-=over 4
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Notes, NOTES_NAME - Configuration for MODULE_NAME
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-config($name), feature($name), set_config($name, $value),
-set_feature($name, $value), config_names(), feature_names(),
-auto_feature_names(), write()
-
-=item AUTHOR
-
-=back
-
-=head2 Module::Build::PPMMaker - Perl Package Manager file creation
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Platform::Amiga - Builder class for Amiga platforms
-
-=over 4
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Platform::Default - Stub class for unknown platforms
-
-=over 4
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Platform::EBCDIC - Builder class for EBCDIC platforms
-
-=over 4
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Platform::MPEiX - Builder class for MPEiX platforms
-
-=over 4
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Platform::MacOS - Builder class for MacOS platforms
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Overridden Methods
-
-new(), make_executable(), dispatch(), ACTION_realclean()
-
-=back
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Platform::RiscOS - Builder class for RiscOS platforms
-
-=over 4
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Platform::Unix - Builder class for Unix platforms
-
-=over 4
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Platform::VMS - Builder class for VMS platforms
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Overridden Methods
-
-_set_defaults
-
-=back
-
-=back
-
-cull_args
-
-manpage_separator
-
-prefixify
-
-_quote_args
-
-have_forkpipe
-
-_backticks
-
-find_command
-
-_maybe_command (override)
-
-do_system
-
-oneliner
-
-_infer_xs_spec
-
-rscan_dir
-
-dist_dir
-
-man3page_name
-
-expand_test_dir
-
-_detildefy
-
-find_perl_interpreter
-
-localize_file_path
-
-localize_dir_path
-
-ACTION_clean
-
-=over 4
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Platform::VOS - Builder class for VOS platforms
-
-=over 4
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Platform::Windows - Builder class for Windows
-platforms
-
-=over 4
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Platform::aix - Builder class for AIX platform
-
-=over 4
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Platform::cygwin - Builder class for Cygwin platform
-
-=over 4
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Platform::darwin - Builder class for Mac OS X
-platform
-
-=over 4
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Platform::os2 - Builder class for OS/2 platform
-
-=over 4
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Build::Version - DEPRECATED
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=head2 Module::Build::YAML - DEPRECATED
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=head2 Module::CoreList - what modules shipped with versions of perl
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item FUNCTIONS API
-
-C<first_release( MODULE )>, C<first_release_by_date( MODULE )>,
-C<find_modules( REGEX, [ LIST OF PERLS ] )>, C<find_version( PERL_VERSION
-)>, C<is_deprecated( MODULE, PERL_VERSION )>, C<removed_from( MODULE )>,
-C<removed_from_by_date( MODULE )>, C<changes_between( PERL_VERSION,
-PERL_VERSION )>
-
-=item DATA STRUCTURES
-
-C<%Module::CoreList::version>, C<%Module::CoreList::released>,
-C<%Module::CoreList::families>, C<%Module::CoreList::deprecated>,
-C<%Module::CoreList::upstream>, C<%Module::CoreList::bug_tracker>
-
-=item CAVEATS
-
-=item HISTORY
-
-=item AUTHOR
-
-=item LICENSE
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Load - runtime require of both modules and files
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Rules
-
-=item Caveats
-
-=item ACKNOWLEDGEMENTS
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Module::Load::Conditional - Looking up module information / loading
-at runtime
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Methods
-
-=over 4
-
-=item $href = check_install( module => NAME [, version => VERSION, verbose
-=> BOOL ] );
-
-module, version, verbose, file, dir, version, uptodate
-
-=back
-
-=back
-
-=over 4
-
-=item $bool = can_load( modules => { NAME => VERSION [,NAME => VERSION] },
-[verbose => BOOL, nocache => BOOL] )
-
-modules, verbose, nocache
-
-=back
-
-=over 4
-
-=item @list = requires( MODULE );
-
-=back
-
-=over 4
-
-=item Global Variables
-
-=over 4
-
-=item $Module::Load::Conditional::VERBOSE
-
-=item $Module::Load::Conditional::FIND_VERSION
-
-=item $Module::Load::Conditional::CHECK_INC_HASH
-
-=item $Module::Load::Conditional::CACHE
-
-=item $Module::Load::Conditional::ERROR
-
-=item $Module::Load::Conditional::DEPRECATED
-
-=back
-
-=item See Also
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Module::Loaded - mark modules as loaded or unloaded
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item FUNCTIONS
-
-=over 4
-
-=item $bool = mark_as_loaded( PACKAGE );
-
-=back
-
-=back
-
-=over 4
-
-=item $bool = mark_as_unloaded( PACKAGE );
-
-=back
-
-=over 4
-
-=item $loc = is_loaded( PACKAGE );
-
-=back
-
-=over 4
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Module::Metadata - Gather package and POD information from perl
-module files
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item USAGE
-
-=over 4
-
-=item Class methods
-
-C<< new_from_file($filename, collect_pod => 1) >>, C<<
-new_from_handle($handle, $filename, collect_pod => 1) >>, C<<
-new_from_module($module, collect_pod => 1, inc => \@dirs) >>, C<<
-find_module_by_name($module, \@dirs) >>, C<<
-find_module_dir_by_name($module, \@dirs) >>, C<< provides( %options ) >>,
-version B<(required)>, dir, files, prefix, C<<
-package_versions_from_directory($dir, \@files?) >>, C<< log_info (internal)
->>
-
-=item Object methods
-
-C<< name() >>, C<< version($package) >>, C<< filename() >>, C<<
-packages_inside() >>, C<< pod_inside() >>, C<< contains_pod() >>, C<<
-pod($section) >>
-
-=back
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Module::Pluggable - automatically give your module the ability to
-have plugins
-
-=over 4
-
-=item SYNOPSIS
-
-=item EXAMPLE
-
-=item DESCRIPTION
-
-=item ADVANCED USAGE
-
-=item INNER PACKAGES
-
-=item OPTIONS
-
-=over 4
-
-=item sub_name
-
-=item search_path
-
-=item search_dirs
-
-=item instantiate
-
-=item require
-
-=item inner
-
-=item only
-
-=item except
-
-=item package
-
-=item file_regex
-
-=item include_editor_junk
-
-=back
-
-=item METHODs
-
-=over 4
-
-=item search_path
-
-=back
-
-=item FUTURE PLANS
-
-=item AUTHOR
-
-=item COPYING
-
-=item BUGS
-
-=item SEE ALSO
-
-=back
-
-=head2 Module::Pluggable::Object - automatically give your module the
-ability to have plugins
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item OPTIONS
-
-=item AUTHOR
-
-=item COPYING
-
-=item BUGS
-
-=item SEE ALSO
-
-=back
-
-=head2 NEXT - Provide a pseudo-class NEXT (et al) that allows method
-redispatch
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Enforcing redispatch
-
-=item Avoiding repetitions
-
-=item Invoking all versions of a method with a single call
-
-=item Using C<EVERY> methods
-
-=back
-
-=item AUTHOR
-
-=item BUGS AND IRRITATIONS
-
-=item COPYRIGHT
-
-=back
-
-=head2 Net::Cmd - Network Command class (as used by FTP, SMTP etc)
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item USER METHODS
-
-debug ( VALUE ), message (), code (), ok (), status (), datasend ( DATA ),
-dataend ()
-
-=item CLASS METHODS
-
-debug_print ( DIR, TEXT ), debug_text ( TEXT ), command ( CMD [, ARGS, ...
-]), unsupported (), response (), parse_response ( TEXT ), getline (),
-ungetline ( TEXT ), rawdatasend ( DATA ), read_until_dot (), tied_fh ()
-
-=item EXPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Net::Config - Local configuration data for libnet
-
-=over 4
-
-=item SYNOPSYS
-
-=item DESCRIPTION
-
-=item METHODS
-
-requires_firewall HOST
-
-=item NetConfig VALUES
-
-nntp_hosts, snpp_hosts, pop3_hosts, smtp_hosts, ph_hosts, daytime_hosts,
-time_hosts, inet_domain, ftp_firewall, ftp_firewall_type, ftp_ext_passive,
-ftp_int_passive, local_netmask, test_hosts, test_exists
-
-=back
-
-=head2 Net::Domain - Attempt to evaluate the current host's internet name
-and domain
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-hostfqdn (), domainname (), hostname (), hostdomain ()
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Net::FTP - FTP Client class
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item OVERVIEW
-
-=item CONSTRUCTOR
-
-new ([ HOST ] [, OPTIONS ])
-
-=item METHODS
-
-login ([LOGIN [,PASSWORD [, ACCOUNT] ] ]), authorize ( [AUTH [, RESP]]),
-site (ARGS), ascii, binary, rename ( OLDNAME, NEWNAME ), delete ( FILENAME
-), cwd ( [ DIR ] ), cdup (), pwd (), restart ( WHERE ), rmdir ( DIR [,
-RECURSE ]), mkdir ( DIR [, RECURSE ]), alloc ( SIZE [, RECORD_SIZE] ), ls (
-[ DIR ] ), dir ( [ DIR ] ), get ( REMOTE_FILE [, LOCAL_FILE [, WHERE]] ),
-put ( LOCAL_FILE [, REMOTE_FILE ] ), put_unique ( LOCAL_FILE [, REMOTE_FILE
-] ), append ( LOCAL_FILE [, REMOTE_FILE ] ), unique_name (), mdtm ( FILE ),
-size ( FILE ), supported ( CMD ), hash ( [FILEHANDLE_GLOB_REF],[
-BYTES_PER_HASH_MARK] ), feature ( NAME ), nlst ( [ DIR ] ), list ( [ DIR ]
-), retr ( FILE ), stor ( FILE ), stou ( FILE ), appe ( FILE ), port ( [
-PORT ] ), pasv (), pasv_xfer ( SRC_FILE, DEST_SERVER [, DEST_FILE ] ),
-pasv_xfer_unique ( SRC_FILE, DEST_SERVER [, DEST_FILE ] ), pasv_wait (
-NON_PASV_SERVER ), abort (), quit ()
-
-=over 4
-
-=item Methods for the adventurous
-
-quot (CMD [,ARGS])
-
-=back
-
-=item THE dataconn CLASS
-
-read ( BUFFER, SIZE [, TIMEOUT ] ), write ( BUFFER, SIZE [, TIMEOUT ] ),
-bytes_read (), abort (), close ()
-
-=item UNIMPLEMENTED
-
-B<SMNT>, B<HELP>, B<MODE>, B<SYST>, B<STAT>, B<STRU>, B<REIN>
-
-=item REPORTING BUGS
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=item USE EXAMPLES
-
-http://www.csh.rit.edu/~adam/Progs/
-
-=item CREDITS
-
-=item COPYRIGHT
-
-=back
-
-=head2 Net::NNTP - NNTP Client class
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CONSTRUCTOR
-
-new ( [ HOST ] [, OPTIONS ])
-
-=item METHODS
-
-article ( [ MSGID|MSGNUM ], [FH] ), body ( [ MSGID|MSGNUM ], [FH] ), head (
-[ MSGID|MSGNUM ], [FH] ), articlefh ( [ MSGID|MSGNUM ] ), bodyfh ( [
-MSGID|MSGNUM ] ), headfh ( [ MSGID|MSGNUM ] ), nntpstat ( [ MSGID|MSGNUM ]
-), group ( [ GROUP ] ), ihave ( MSGID [, MESSAGE ]), last (), date (),
-postok (), authinfo ( USER, PASS ), list (), newgroups ( SINCE [,
-DISTRIBUTIONS ]), newnews ( SINCE [, GROUPS [, DISTRIBUTIONS ]]), next (),
-post ( [ MESSAGE ] ), postfh (), slave (), quit ()
-
-=over 4
-
-=item Extension methods
-
-newsgroups ( [ PATTERN ] ), distributions (), subscriptions (),
-overview_fmt (), active_times (), active ( [ PATTERN ] ), xgtitle ( PATTERN
-), xhdr ( HEADER, MESSAGE-SPEC ), xover ( MESSAGE-SPEC ), xpath (
-MESSAGE-ID ), xpat ( HEADER, PATTERN, MESSAGE-SPEC), xrover, listgroup ( [
-GROUP ] ), reader
-
-=back
-
-=item UNSUPPORTED
-
-=item DEFINITIONS
-
-MESSAGE-SPEC, PATTERN, Examples, C<[^]-]>, C<*bdc>, C<[0-9a-zA-Z]>, C<a??d>
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Net::Netrc - OO interface to users netrc file
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item THE .netrc FILE
-
-machine name, default, login name, password string, account string, macdef
-name
-
-=item CONSTRUCTOR
-
-lookup ( MACHINE [, LOGIN ])
-
-=item METHODS
-
-login (), password (), account (), lpa ()
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=item COPYRIGHT
-
-=back
-
-=head2 Net::POP3 - Post Office Protocol 3 Client class (RFC1939)
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CONSTRUCTOR
-
-new ( [ HOST ] [, OPTIONS ] 0
-
-=item METHODS
-
-auth ( USERNAME, PASSWORD ), user ( USER ), pass ( PASS ), login ( [ USER
-[, PASS ]] ), apop ( [ USER [, PASS ]] ), banner (), capa (), capabilities
-(), top ( MSGNUM [, NUMLINES ] ), list ( [ MSGNUM ] ), get ( MSGNUM [, FH ]
-), getfh ( MSGNUM ), last (), popstat (), ping ( USER ), uidl ( [ MSGNUM ]
-), delete ( MSGNUM ), reset (), quit ()
-
-=item NOTES
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Net::Ping - check a remote host for reachability
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Functions
-
-Net::Ping->new([$proto [, $def_timeout [, $bytes [, $device [, $tos
-]]]]]);, $p->ping($host [, $timeout]);, $p->source_verify( { 0 | 1 } );,
-$p->service_check( { 0 | 1 } );, $p->tcp_service_check( { 0 | 1 } );,
-$p->hires( { 0 | 1 } );, $p->bind($local_addr);, $p->open($host);, $p->ack(
-[ $host ] );, $p->nack( $failed_ack_host );, $p->close();,
-$p->port_number([$port_number]), pingecho($host [, $timeout]);
-
-=back
-
-=item NOTES
-
-=item INSTALL
-
-=item BUGS
-
-=item AUTHORS
-
-=item COPYRIGHT
-
-=back
-
-=head2 Net::SMTP - Simple Mail Transfer Protocol Client
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item EXAMPLES
-
-=item CONSTRUCTOR
-
-new ( [ HOST ] [, OPTIONS ] )
-
-=item METHODS
-
-banner (), domain (), hello ( DOMAIN ), host (), etrn ( DOMAIN ), auth (
-USERNAME, PASSWORD ), mail ( ADDRESS [, OPTIONS] ), send ( ADDRESS ),
-send_or_mail ( ADDRESS ), send_and_mail ( ADDRESS ), reset (), recipient (
-ADDRESS [, ADDRESS, [...]] [, OPTIONS ] ), to ( ADDRESS [, ADDRESS [...]]
-), cc ( ADDRESS [, ADDRESS [...]] ), bcc ( ADDRESS [, ADDRESS [...]] ),
-data ( [ DATA ] ), expand ( ADDRESS ), verify ( ADDRESS ), help ( [
-$subject ] ), quit ()
-
-=item ADDRESSES
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Net::Time - time and daytime network client interface
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-inet_time ( [HOST [, PROTOCOL [, TIMEOUT]]]), inet_daytime ( [HOST [,
-PROTOCOL [, TIMEOUT]]])
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Net::hostent - by-name interface to Perl's built-in gethost*()
-functions
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item EXAMPLES
-
-=item NOTE
-
-=item AUTHOR
-
-=back
-
-=head2 Net::libnetFAQ, libnetFAQ - libnet Frequently Asked Questions
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Where to get this document
-
-=item How to contribute to this document
-
-=back
-
-=item Author and Copyright Information
-
-=over 4
-
-=item Disclaimer
-
-=back
-
-=item Obtaining and installing libnet
-
-=over 4
-
-=item What is libnet ?
-
-=item Which version of perl do I need ?
-
-=item What other modules do I need ?
-
-=item What machines support libnet ?
-
-=item Where can I get the latest libnet release
-
-=back
-
-=item Using Net::FTP
-
-=over 4
-
-=item How do I download files from an FTP server ?
-
-=item How do I transfer files in binary mode ?
-
-=item How can I get the size of a file on a remote FTP server ?
-
-=item How can I get the modification time of a file on a remote FTP server
-?
-
-=item How can I change the permissions of a file on a remote server ?
-
-=item Can I do a reget operation like the ftp command ?
-
-=item How do I get a directory listing from an FTP server ?
-
-=item Changing directory to "" does not fail ?
-
-=item I am behind a SOCKS firewall, but the Firewall option does not work ?
-
-=item I am behind an FTP proxy firewall, but cannot access machines outside
-?
-
-=item My ftp proxy firewall does not listen on port 21
-
-=item Is it possible to change the file permissions of a file on an FTP
-server ?
-
-=item I have seen scripts call a method message, but cannot find it
-documented ?
-
-=item Why does Net::FTP not implement mput and mget methods
-
-=back
-
-=item Using Net::SMTP
-
-=over 4
-
-=item Why can't the part of an Email address after the @ be used as the
-hostname ?
-
-=item Why does Net::SMTP not do DNS MX lookups ?
-
-=item The verify method always returns true ?
-
-=back
-
-=item Debugging scripts
-
-=over 4
-
-=item How can I debug my scripts that use Net::* modules ?
-
-=back
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 Net::netent - by-name interface to Perl's built-in getnet*()
-functions
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item EXAMPLES
-
-=item NOTE
-
-=item AUTHOR
-
-=back
-
-=head2 Net::protoent - by-name interface to Perl's built-in getproto*()
-functions
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item NOTE
-
-=item AUTHOR
-
-=back
-
-=head2 Net::servent - by-name interface to Perl's built-in getserv*()
-functions
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item EXAMPLES
-
-=item NOTE
-
-=item AUTHOR
-
-=back
-
-=head2 O - Generic interface to Perl Compiler backends
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CONVENTIONS
-
-=item IMPLEMENTATION
-
-=item BUGS
-
-=item AUTHOR
-
-=back
-
-=head2 Object::Accessor - interface to create per object accessors
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item $object = Object::Accessor->new( [ARGS] );
-
-=back
-
-=back
-
-=over 4
-
-=item $bool = $object->mk_accessors( @ACCESSORS | \%ACCESSOR_MAP );
-
-=back
-
-=over 4
-
-=item @list = $self->ls_accessors;
-
-=back
-
-=over 4
-
-=item $ref = $self->ls_allow(KEY)
-
-=back
-
-=over 4
-
-=item $bool = $self->mk_aliases( alias => method, [alias2 => method2, ...]
-);
-
-=back
-
-=over 4
-
-=item $clone = $self->mk_clone;
-
-=back
-
-=over 4
-
-=item $bool = $self->mk_flush;
-
-=back
-
-=over 4
-
-=item $bool = $self->mk_verify;
-
-=back
-
-=over 4
-
-=item $bool = $self->register_callback( sub { ... } );
-
-=back
-
-=over 4
-
-=item $bool = $self->can( METHOD_NAME )
-
-=back
-
-=over 4
-
-=item $val = $self->___get( METHOD_NAME );
-
-=back
-
-=over 4
-
-=item $bool = $self->___set( METHOD_NAME => VALUE );
-
-=back
-
-=over 4
-
-=item $bool = $self->___alias( ALIAS => METHOD );
-
-=back
-
-=over 4
-
-=item LVALUE ACCESSORS
-
-=over 4
-
-=item CAVEATS
-
-Allow handlers, Callbacks
-
-=back
-
-=back
-
-=over 4
-
-=item GLOBAL VARIABLES
-
-=over 4
-
-=item $Object::Accessor::FATAL
-
-=item $Object::Accessor::DEBUG
-
-=back
-
-=item TODO
-
-=over 4
-
-=item Create read-only accessors
-
-=back
-
-=item CAVEATS
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Opcode - Disable named opcodes when compiling perl code
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item NOTE
-
-=item WARNING
-
-=item Operator Names and Operator Lists
-
-an operator name (opname), an operator tag name (optag), a negated opname
-or optag, an operator set (opset)
-
-=item Opcode Functions
-
-opcodes, opset (OP, ...), opset_to_ops (OPSET), opset_to_hex (OPSET),
-full_opset, empty_opset, invert_opset (OPSET), verify_opset (OPSET, ...),
-define_optag (OPTAG, OPSET), opmask_add (OPSET), opmask, opdesc (OP, ...),
-opdump (PAT)
-
-=item Manipulating Opsets
-
-=item TO DO (maybe)
-
-=back
-
-=over 4
-
-=item Predefined Opcode Tags
-
-:base_core, :base_mem, :base_loop, :base_io, :base_orig, :base_math,
-:base_thread, :default, :filesys_read, :sys_db, :browse, :filesys_open,
-:filesys_write, :subprocess, :ownprocess, :others, :load,
-:still_to_be_decided, :dangerous
-
-=item SEE ALSO
-
-=item AUTHORS
-
-=back
-
-=head2 POSIX - Perl interface to IEEE Std 1003.1
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CAVEATS
-
-=item FUNCTIONS
-
-_exit, abort, abs, access, acos, alarm, asctime, asin, assert, atan, atan2,
-atexit, atof, atoi, atol, bsearch, calloc, ceil, chdir, chmod, chown,
-clearerr, clock, close, closedir, cos, cosh, creat, ctermid, ctime,
-cuserid, difftime, div, dup, dup2, errno, execl, execle, execlp, execv,
-execve, execvp, exit, exp, fabs, fclose, fcntl, fdopen, feof, ferror,
-fflush, fgetc, fgetpos, fgets, fileno, floor, fmod, fopen, fork, fpathconf,
-fprintf, fputc, fputs, fread, free, freopen, frexp, fscanf, fseek, fsetpos,
-fstat, fsync, ftell, fwrite, getc, getchar, getcwd, getegid, getenv,
-geteuid, getgid, getgrgid, getgrnam, getgroups, getlogin, getpgrp, getpid,
-getppid, getpwnam, getpwuid, gets, getuid, gmtime, isalnum, isalpha,
-isatty, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace,
-isupper, isxdigit, kill, labs, lchown, ldexp, ldiv, link, localeconv,
-localtime, log, log10, longjmp, lseek, malloc, mblen, mbstowcs, mbtowc,
-memchr, memcmp, memcpy, memmove, memset, mkdir, mkfifo, mktime, modf, nice,
-offsetof, open, opendir, pathconf, pause, perror, pipe, pow, printf, putc,
-putchar, puts, qsort, raise, rand, read, readdir, realloc, remove, rename,
-rewind, rewinddir, rmdir, scanf, setgid, setjmp, setlocale, setpgid,
-setsid, setuid, sigaction, siglongjmp, sigpending, sigprocmask, sigsetjmp,
-sigsuspend, sin, sinh, sleep, sprintf, sqrt, srand, sscanf, stat, strcat,
-strchr, strcmp, strcoll, strcpy, strcspn, strerror, strftime, strlen,
-strncat, strncmp, strncpy, strpbrk, strrchr, strspn, strstr, strtod,
-strtok, strtol, strtoul, strxfrm, sysconf, system, tan, tanh, tcdrain,
-tcflow, tcflush, tcgetpgrp, tcsendbreak, tcsetpgrp, time, times, tmpfile,
-tmpnam, tolower, toupper, ttyname, tzname, tzset, umask, uname, ungetc,
-unlink, utime, vfprintf, vprintf, vsprintf, wait, waitpid, wcstombs,
-wctomb, write
-
-=item CLASSES
-
-=over 4
-
-=item POSIX::SigAction
-
-new, handler, mask, flags, safe
-
-=item POSIX::SigRt
-
-%SIGRT, SIGRTMIN, SIGRTMAX
-
-=item POSIX::SigSet
-
-new, addset, delset, emptyset, fillset, ismember
-
-=item POSIX::Termios
-
-new, getattr, getcc, getcflag, getiflag, getispeed, getlflag, getoflag,
-getospeed, setattr, setcc, setcflag, setiflag, setispeed, setlflag,
-setoflag, setospeed, Baud rate values, Terminal interface values, c_cc
-field values, c_cflag field values, c_iflag field values, c_lflag field
-values, c_oflag field values
-
-=back
-
-=item PATHNAME CONSTANTS
-
-Constants
-
-=item POSIX CONSTANTS
-
-Constants
-
-=item SYSTEM CONFIGURATION
-
-Constants
-
-=item ERRNO
-
-Constants
-
-=item FCNTL
-
-Constants
-
-=item FLOAT
-
-Constants
-
-=item LIMITS
-
-Constants
-
-=item LOCALE
-
-Constants
-
-=item MATH
-
-Constants
-
-=item SIGNAL
-
-Constants
-
-=item STAT
-
-Constants, Macros
-
-=item STDLIB
-
-Constants
-
-=item STDIO
-
-Constants
-
-=item TIME
-
-Constants
-
-=item UNISTD
-
-Constants
-
-=item WAIT
-
-Constants, WNOHANG, WUNTRACED, Macros, WIFEXITED, WEXITSTATUS, WIFSIGNALED,
-WTERMSIG, WIFSTOPPED, WSTOPSIG
-
-=back
-
-=head2 Package::Constants - List all constants declared in a package
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CLASS METHODS
-
-=over 4
-
-=item @const = Package::Constants->list( PACKAGE_NAME );
-
-=back
-
-=back
-
-=over 4
-
-=item GLOBAL VARIABLES
-
-=over 4
-
-=item $Package::Constants::DEBUG
-
-=back
-
-=back
-
-=over 4
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Params::Check - A generic input parsing/checking mechanism.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Template
-
-default, required, strict_type, defined, no_override, store, allow
-
-=item Functions
-
-=over 4
-
-=item check( \%tmpl, \%args, [$verbose] );
-
-Template, Arguments, Verbose
-
-=back
-
-=back
-
-=over 4
-
-=item allow( $test_me, \@criteria );
-
-string, regexp, subroutine, array ref
-
-=back
-
-=over 4
-
-=item last_error()
-
-=back
-
-=over 4
-
-=item Global Variables
-
-=over 4
-
-=item $Params::Check::VERBOSE
-
-=item $Params::Check::STRICT_TYPE
-
-=item $Params::Check::ALLOW_UNKNOWN
-
-=item $Params::Check::STRIP_LEADING_DASHES
-
-=item $Params::Check::NO_DUPLICATES
-
-=item $Params::Check::PRESERVE_CASE
-
-=item $Params::Check::ONLY_ALLOW_DEFINED
-
-=item $Params::Check::SANITY_CHECK_TEMPLATE
-
-=item $Params::Check::WARNINGS_FATAL
-
-=item $Params::Check::CALLER_DEPTH
-
-=back
-
-=item Acknowledgements
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Parse::CPAN::Meta - Parse META.yml and META.json CPAN metadata files
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item load_file
-
-=item load_yaml_string
-
-=item load_json_string
-
-=item yaml_backend
-
-=item json_backend
-
-=back
-
-=item FUNCTIONS
-
-=over 4
-
-=item Load
-
-=item LoadFile
-
-=back
-
-=item ENVIRONMENT
-
-=over 4
-
-=item PERL_JSON_BACKEND
-
-=item PERL_YAML_BACKEND
-
-=back
-
-=item SUPPORT
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Perl::OSType - Map Perl operating system names to generic types
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item USAGE
-
-=over 4
-
-=item os_type()
-
-=item is_os_type()
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 PerlIO - On demand loader for PerlIO layers and root of PerlIO::*
-name space
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-:unix, :stdio, :perlio, :crlf, :utf8, :bytes, :raw, :pop, :win32
-
-=over 4
-
-=item Custom Layers
-
-:encoding, :mmap, :via
-
-=item Alternatives to raw
-
-=item Defaults and how to override them
-
-=item Querying the layers of filehandles
-
-=back
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 PerlIO::encoding - encoding layer
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=back
-
-=head2 PerlIO::mmap - Memory mapped IO
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item IMPLEMENTATION NOTE
-
-=back
-
-=head2 PerlIO::scalar - in-memory IO, scalar IO
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item IMPLEMENTATION NOTE
-
-=back
-
-=head2 PerlIO::via - Helper class for PerlIO layers implemented in perl
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item EXPECTED METHODS
-
-$class->PUSHED([$mode,[$fh]]), $obj->POPPED([$fh]),
-$obj->UTF8($belowFlag,[$fh]), $obj->OPEN($path,$mode,[$fh]),
-$obj->BINMODE([$fh]), $obj->FDOPEN($fd,[$fh]),
-$obj->SYSOPEN($path,$imode,$perm,[$fh]), $obj->FILENO($fh),
-$obj->READ($buffer,$len,$fh), $obj->WRITE($buffer,$fh), $obj->FILL($fh),
-$obj->CLOSE($fh), $obj->SEEK($posn,$whence,$fh), $obj->TELL($fh),
-$obj->UNREAD($buffer,$fh), $obj->FLUSH($fh), $obj->SETLINEBUF($fh),
-$obj->CLEARERR($fh), $obj->ERROR($fh), $obj->EOF($fh)
-
-=item EXAMPLES
-
-=over 4
-
-=item Example - a Hexadecimal Handle
-
-=back
-
-=back
-
-=head2 PerlIO::via::QuotedPrint - PerlIO layer for quoted-printable strings
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item REQUIRED MODULES
-
-=item SEE ALSO
-
-=item ACKNOWLEDGEMENTS
-
-=item COPYRIGHT
-
-=back
-
-=head2 Pod::Checker, podchecker() - check pod documents for syntax errors
-
-=over 4
-
-=item SYNOPSIS
-
-=item OPTIONS/ARGUMENTS
-
-=over 4
-
-=item podchecker()
-
-B<-warnings> =E<gt> I<val>
-
-=back
-
-=item DESCRIPTION
-
-=item DIAGNOSTICS
-
-=over 4
-
-=item Errors
-
-empty =headn, =over on line I<N> without closing =back, =item without
-previous =over, =back without previous =over, No argument for =begin, =end
-without =begin, Nested =begin's, =for without formatter specification,
-Apparent command =foo not preceded by blank line, unresolved internal link
-I<NAME>, Unknown command "I<CMD>", Unknown interior-sequence "I<SEQ>",
-nested commands I<CMD>E<lt>...I<CMD>E<lt>...E<gt>...E<gt>, garbled entity
-I<STRING>, Entity number out of range, malformed link LE<lt>E<gt>, nonempty
-ZE<lt>E<gt>, empty XE<lt>E<gt>, Spurious text after =pod / =cut, Spurious
-=cut command, Spurious =pod command, Spurious character(s) after =back
-
-=item Warnings
-
-multiple occurrence of link target I<name>, line containing nothing but
-whitespace in paragraph, file does not start with =head, previous =item has
-no contents, preceding non-item paragraph(s), =item type mismatch (I<one>
-vs. I<two>), I<N> unescaped C<E<lt>E<gt>> in paragraph, Unknown entity, No
-items in =over, No argument for =item, empty section in previous paragraph,
-Verbatim paragraph in NAME section, =headI<n> without preceding higher
-level
-
-=item Hyperlinks
-
-ignoring leading/trailing whitespace in link, (section) in '$page'
-deprecated, alternative text/node '%s' contains non-escaped | or /
-
-=back
-
-=item RETURN VALUE
-
-=item EXAMPLES
-
-=item INTERFACE
-
-=back
-
-C<Pod::Checker-E<gt>new( %options )>
-
-C<$checker-E<gt>poderror( @args )>, C<$checker-E<gt>poderror( {%opts},
-@args )>
-
-C<$checker-E<gt>num_errors()>
-
-C<$checker-E<gt>num_warnings()>
-
-C<$checker-E<gt>name()>
-
-C<$checker-E<gt>node()>
-
-C<$checker-E<gt>idx()>
-
-C<$checker-E<gt>hyperlink()>
-
-=over 4
-
-=item AUTHOR
-
-=back
-
-=head2 Pod::Escapes -- for resolving Pod EE<lt>...E<gt> sequences
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item GOODIES
-
-e2char($e_content), e2charnum($e_content), $Name2character{I<name>},
-$Name2character_number{I<name>}, $Latin1Code_to_fallback{I<integer>},
-$Latin1Char_to_fallback{I<character>}, $Code2USASCII{I<integer>}
-
-=item CAVEATS
-
-=item SEE ALSO
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-=back
-
-=head2 Pod::Find - find POD documents in directory trees
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item C<pod_find( { %opts } , @directories )>
-
-C<-verbose =E<gt> 1>, C<-perl =E<gt> 1>, C<-script =E<gt> 1>, C<-inc =E<gt>
-1>
-
-=back
-
-=over 4
-
-=item C<simplify_name( $str )>
-
-=back
-
-=over 4
-
-=item C<pod_where( { %opts }, $pod )>
-
-C<-inc =E<gt> 1>, C<-dirs =E<gt> [ $dir1, $dir2, ... ]>, C<-verbose =E<gt>
-1>
-
-=back
-
-=over 4
-
-=item C<contains_pod( $file , $verbose )>
-
-=back
-
-=over 4
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Pod::Html - module to convert pod files to HTML
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item FUNCTIONS
-
-=over 4
-
-=item pod2html
-
-backlink, cachedir, css, flush, header, help, htmldir, htmlroot, index,
-infile, outfile, poderrors, podpath, podroot, quiet, recurse, title,
-verbose
-
-=item htmlify
-
-=item anchorify
-
-=back
-
-=item ENVIRONMENT
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=item COPYRIGHT
-
-=back
-
-=head2 Pod::InputObjects - objects representing POD input paragraphs,
-commands, etc.
-
-=over 4
-
-=item SYNOPSIS
-
-=item REQUIRES
-
-=item EXPORTS
-
-=item DESCRIPTION
-
-package B<Pod::InputSource>, package B<Pod::Paragraph>, package
-B<Pod::InteriorSequence>, package B<Pod::ParseTree>
-
-=back
-
-=over 4
-
-=item B<Pod::InputSource>
-
-=back
-
-=over 4
-
-=item B<new()>
-
-=back
-
-=over 4
-
-=item B<name()>
-
-=back
-
-=over 4
-
-=item B<handle()>
-
-=back
-
-=over 4
-
-=item B<was_cutting()>
-
-=back
-
-=over 4
-
-=item B<Pod::Paragraph>
-
-=back
-
-=over 4
-
-=item Pod::Paragraph-E<gt>B<new()>
-
-=back
-
-=over 4
-
-=item $pod_para-E<gt>B<cmd_name()>
-
-=back
-
-=over 4
-
-=item $pod_para-E<gt>B<text()>
-
-=back
-
-=over 4
-
-=item $pod_para-E<gt>B<raw_text()>
-
-=back
-
-=over 4
-
-=item $pod_para-E<gt>B<cmd_prefix()>
-
-=back
-
-=over 4
-
-=item $pod_para-E<gt>B<cmd_separator()>
-
-=back
-
-=over 4
-
-=item $pod_para-E<gt>B<parse_tree()>
-
-=back
-
-=over 4
-
-=item $pod_para-E<gt>B<file_line()>
-
-=back
-
-=over 4
-
-=item B<Pod::InteriorSequence>
-
-=back
-
-=over 4
-
-=item Pod::InteriorSequence-E<gt>B<new()>
-
-=back
-
-=over 4
-
-=item $pod_seq-E<gt>B<cmd_name()>
-
-=back
-
-=over 4
-
-=item $pod_seq-E<gt>B<prepend()>
-
-=back
-
-=over 4
-
-=item $pod_seq-E<gt>B<append()>
-
-=back
-
-=over 4
-
-=item $pod_seq-E<gt>B<nested()>
-
-=back
-
-=over 4
-
-=item $pod_seq-E<gt>B<raw_text()>
-
-=back
-
-=over 4
-
-=item $pod_seq-E<gt>B<left_delimiter()>
-
-=back
-
-=over 4
-
-=item $pod_seq-E<gt>B<right_delimiter()>
-
-=back
-
-=over 4
-
-=item $pod_seq-E<gt>B<parse_tree()>
-
-=back
-
-=over 4
-
-=item $pod_seq-E<gt>B<file_line()>
-
-=back
-
-=over 4
-
-=item Pod::InteriorSequence::B<DESTROY()>
-
-=back
-
-=over 4
-
-=item B<Pod::ParseTree>
-
-=back
-
-=over 4
-
-=item Pod::ParseTree-E<gt>B<new()>
-
-=back
-
-=over 4
-
-=item $ptree-E<gt>B<top()>
-
-=back
-
-=over 4
-
-=item $ptree-E<gt>B<children()>
-
-=back
-
-=over 4
-
-=item $ptree-E<gt>B<prepend()>
-
-=back
-
-=over 4
-
-=item $ptree-E<gt>B<append()>
-
-=back
-
-=over 4
-
-=item $ptree-E<gt>B<raw_text()>
-
-=back
-
-=over 4
-
-=item Pod::ParseTree::B<DESTROY()>
-
-=back
-
-=over 4
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 Pod::LaTeX - Convert Pod data to formatted Latex
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item OBJECT METHODS
-
-C<initialize>
-
-=back
-
-=over 4
-
-=item Data Accessors
-
-B<AddPreamble>
-
-=back
-
-B<AddPostamble>
-
-B<Head1Level>
-
-B<Label>
-
-B<LevelNoNum>
-
-B<MakeIndex>
-
-B<ReplaceNAMEwithSection>
-
-B<StartWithNewPage>
-
-B<TableOfContents>
-
-B<UniqueLabels>
-
-B<UserPreamble>
-
-B<UserPostamble>
-
-B<Lists>
-
-=over 4
-
-=item Subclassed methods
-
-=back
-
-B<begin_pod>
-
-B<end_pod>
-
-B<command>
-
-B<verbatim>
-
-B<textblock>
-
-B<interior_sequence>
-
-=over 4
-
-=item List Methods
-
-B<begin_list>
-
-=back
-
-B<end_list>
-
-B<add_item>
-
-=over 4
-
-=item Methods for headings
-
-B<head>
-
-=back
-
-=over 4
-
-=item Internal methods
-
-B<_output>
-
-=back
-
-B<_replace_special_chars>
-
-B<_replace_special_chars_late>
-
-B<_create_label>
-
-B<_create_index>
-
-B<_clean_latex_commands>
-
-B<_split_delimited>
-
-=over 4
-
-=item NOTES
-
-=item SEE ALSO
-
-=item AUTHORS
-
-=item COPYRIGHT
-
-=item REVISION
-
-=back
-
-=head2 Pod::Man - Convert POD data to formatted *roff input
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-center, date, fixed, fixedbold, fixeditalic, fixedbolditalic, name, quotes,
-release, section, stderr, utf8
-
-=item DIAGNOSTICS
-
-roff font should be 1 or 2 chars, not "%s", Invalid quote specification
-"%s"
-
-=item BUGS
-
-=item CAVEATS
-
-=item AUTHOR
-
-=item COPYRIGHT AND LICENSE
-
-=item SEE ALSO
-
-=back
-
-=head2 Pod::ParseLink - Parse an LE<lt>E<gt> formatting code in POD text
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 Pod::ParseUtils - helpers for POD parsing and conversion
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item Pod::List
-
-Pod::List-E<gt>new()
-
-=back
-
-$list-E<gt>file()
-
-$list-E<gt>start()
-
-$list-E<gt>indent()
-
-$list-E<gt>type()
-
-$list-E<gt>rx()
-
-$list-E<gt>item()
-
-$list-E<gt>parent()
-
-$list-E<gt>tag()
-
-=over 4
-
-=item Pod::Hyperlink
-
-Pod::Hyperlink-E<gt>new()
-
-=back
-
-$link-E<gt>parse($string)
-
-$link-E<gt>markup($string)
-
-$link-E<gt>text()
-
-$link-E<gt>warning()
-
-$link-E<gt>file(), $link-E<gt>line()
-
-$link-E<gt>page()
-
-$link-E<gt>node()
-
-$link-E<gt>alttext()
-
-$link-E<gt>type()
-
-$link-E<gt>link()
-
-=over 4
-
-=item Pod::Cache
-
-Pod::Cache-E<gt>new()
-
-=back
-
-$cache-E<gt>item()
-
-$cache-E<gt>find_page($name)
-
-=over 4
-
-=item Pod::Cache::Item
-
-Pod::Cache::Item-E<gt>new()
-
-=back
-
-$cacheitem-E<gt>page()
-
-$cacheitem-E<gt>description()
-
-$cacheitem-E<gt>path()
-
-$cacheitem-E<gt>file()
-
-$cacheitem-E<gt>nodes()
-
-$cacheitem-E<gt>find_node($name)
-
-$cacheitem-E<gt>idx()
-
-=over 4
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Pod::Parser - base class for creating POD filters and translators
-
-=over 4
-
-=item SYNOPSIS
-
-=item REQUIRES
-
-=item EXPORTS
-
-=item DESCRIPTION
-
-=item QUICK OVERVIEW
-
-=item PARSING OPTIONS
-
-B<-want_nonPODs> (default: unset), B<-process_cut_cmd> (default: unset),
-B<-warnings> (default: unset)
-
-=back
-
-=over 4
-
-=item RECOMMENDED SUBROUTINE/METHOD OVERRIDES
-
-=back
-
-=over 4
-
-=item B<command()>
-
-C<$cmd>, C<$text>, C<$line_num>, C<$pod_para>
-
-=back
-
-=over 4
-
-=item B<verbatim()>
-
-C<$text>, C<$line_num>, C<$pod_para>
-
-=back
-
-=over 4
-
-=item B<textblock()>
-
-C<$text>, C<$line_num>, C<$pod_para>
-
-=back
-
-=over 4
-
-=item B<interior_sequence()>
-
-=back
-
-=over 4
-
-=item OPTIONAL SUBROUTINE/METHOD OVERRIDES
-
-=back
-
-=over 4
-
-=item B<new()>
-
-=back
-
-=over 4
-
-=item B<initialize()>
-
-=back
-
-=over 4
-
-=item B<begin_pod()>
-
-=back
-
-=over 4
-
-=item B<begin_input()>
-
-=back
-
-=over 4
-
-=item B<end_input()>
-
-=back
-
-=over 4
-
-=item B<end_pod()>
-
-=back
-
-=over 4
-
-=item B<preprocess_line()>
-
-=back
-
-=over 4
-
-=item B<preprocess_paragraph()>
-
-=back
-
-=over 4
-
-=item METHODS FOR PARSING AND PROCESSING
-
-=back
-
-=over 4
-
-=item B<parse_text()>
-
-B<-expand_seq> =E<gt> I<code-ref>|I<method-name>, B<-expand_text> =E<gt>
-I<code-ref>|I<method-name>, B<-expand_ptree> =E<gt>
-I<code-ref>|I<method-name>
-
-=back
-
-=over 4
-
-=item B<interpolate()>
-
-=back
-
-=over 4
-
-=item B<parse_paragraph()>
-
-=back
-
-=over 4
-
-=item B<parse_from_filehandle()>
-
-=back
-
-=over 4
-
-=item B<parse_from_file()>
-
-=back
-
-=over 4
-
-=item ACCESSOR METHODS
-
-=back
-
-=over 4
-
-=item B<errorsub()>
-
-=back
-
-=over 4
-
-=item B<cutting()>
-
-=back
-
-=over 4
-
-=item B<parseopts()>
-
-=back
-
-=over 4
-
-=item B<output_file()>
-
-=back
-
-=over 4
-
-=item B<output_handle()>
-
-=back
-
-=over 4
-
-=item B<input_file()>
-
-=back
-
-=over 4
-
-=item B<input_handle()>
-
-=back
-
-=over 4
-
-=item B<input_streams()>
-
-=back
-
-=over 4
-
-=item B<top_stream()>
-
-=back
-
-=over 4
-
-=item PRIVATE METHODS AND DATA
-
-=back
-
-=over 4
-
-=item B<_push_input_stream()>
-
-=back
-
-=over 4
-
-=item B<_pop_input_stream()>
-
-=back
-
-=over 4
-
-=item TREE-BASED PARSING
-
-=item CAVEATS
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item LICENSE
-
-=back
-
-=head2 Pod::Perldoc - Look up Perl documentation in Pod format.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-=back
-
-=head2 Pod::Perldoc::BaseTo - Base for Pod::Perldoc formatters
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-=back
-
-=head2 Pod::Perldoc::GetOptsOO - Customized option parser for Pod::Perldoc
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-Call Pod::Perldoc::GetOptsOO::getopts($object, \@ARGV, $truth), Given -n,
-if there's a opt_n_with, it'll call $object->opt_n_with( ARGUMENT )
-(e.g., "-n foo" => $object->opt_n_with('foo'). Ditto "-nfoo"), Otherwise
-(given -n) if there's an opt_n, we'll call it $object->opt_n($truth)
-(Truth defaults to 1), Otherwise we try calling
-$object->handle_unknown_option('n') (and we increment the error count by
-the return value of it), If there's no handle_unknown_option, then we just
-warn, and then increment the error counter
-
-=item SEE ALSO
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-=back
-
-=head2 Pod::Perldoc::ToANSI - render Pod with ANSI color escapes
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CAVEAT
-
-=item SEE ALSO
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-=back
-
-=head2 Pod::Perldoc::ToChecker - let Perldoc check Pod for errors
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-=back
-
-=head2 Pod::Perldoc::ToMan - let Perldoc render Pod as man pages
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CAVEAT
-
-=item SEE ALSO
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-=back
-
-=head2 Pod::Perldoc::ToNroff - let Perldoc convert Pod to nroff
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CAVEAT
-
-=item SEE ALSO
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-=back
-
-=head2 Pod::Perldoc::ToPod - let Perldoc render Pod as ... Pod!
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-=back
-
-=head2 Pod::Perldoc::ToRtf - let Perldoc render Pod as RTF
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-=back
-
-=head2 Pod::Perldoc::ToTerm - render Pod with terminal escapes
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CAVEAT
-
-=item SEE ALSO
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-=back
-
-=head2 Pod::Perldoc::ToText - let Perldoc render Pod as plaintext
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CAVEAT
-
-=item SEE ALSO
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-=back
-
-=head2 Pod::Perldoc::ToTk - let Perldoc use Tk::Pod to render Pod
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 Pod::Perldoc::ToXml - let Perldoc render Pod as XML
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-=back
-
-=head2 Pod::PlainText - Convert POD data to formatted ASCII text
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-alt, indent, loose, sentence, width
-
-=item DIAGNOSTICS
-
-Bizarre space in item, Can't open %s for reading: %s, Unknown escape: %s,
-Unknown sequence: %s, Unmatched =back
-
-=item RESTRICTIONS
-
-=item NOTES
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 Pod::Select, podselect() - extract selected sections of POD from
-input
-
-=over 4
-
-=item SYNOPSIS
-
-=item REQUIRES
-
-=item EXPORTS
-
-=item DESCRIPTION
-
-=item SECTION SPECIFICATIONS
-
-=item RANGE SPECIFICATIONS
-
-=back
-
-=over 4
-
-=item OBJECT METHODS
-
-=back
-
-=over 4
-
-=item B<curr_headings()>
-
-=back
-
-=over 4
-
-=item B<select()>
-
-=back
-
-=over 4
-
-=item B<add_selection()>
-
-=back
-
-=over 4
-
-=item B<clear_selections()>
-
-=back
-
-=over 4
-
-=item B<match_section()>
-
-=back
-
-=over 4
-
-=item B<is_selected()>
-
-=back
-
-=over 4
-
-=item EXPORTED FUNCTIONS
-
-=back
-
-=over 4
-
-=item B<podselect()>
-
-B<-output>, B<-sections>, B<-ranges>
-
-=back
-
-=over 4
-
-=item PRIVATE METHODS AND DATA
-
-=back
-
-=over 4
-
-=item B<_compile_section_spec()>
-
-=back
-
-=over 4
-
-=item $self->{_SECTION_HEADINGS}
-
-=back
-
-=over 4
-
-=item $self->{_SELECTED_SECTIONS}
-
-=back
-
-=over 4
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 Pod::Simple - framework for parsing Pod
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item MAIN METHODS
-
-C<< $parser = I<SomeClass>->new(); >>, C<< $parser->output_fh( *OUT ); >>,
-C<< $parser->output_string( \$somestring ); >>, C<< $parser->parse_file(
-I<$some_filename> ); >>, C<< $parser->parse_file( *INPUT_FH ); >>, C<<
-$parser->parse_string_document( I<$all_content> ); >>, C<<
-$parser->parse_lines( I<...@lines...>, undef ); >>, C<<
-$parser->content_seen >>, C<< I<SomeClass>->filter( I<$filename> ); >>, C<<
-I<SomeClass>->filter( I<*INPUT_FH> ); >>, C<< I<SomeClass>->filter(
-I<\$document_content> ); >>
-
-=item SECONDARY METHODS
-
-C<< $parser->no_whining( I<SOMEVALUE> ) >>, C<< $parser->no_errata_section(
-I<SOMEVALUE> ) >>, C<< $parser->complain_stderr( I<SOMEVALUE> ) >>, C<<
-$parser->source_filename >>, C<< $parser->doc_has_started >>, C<<
-$parser->source_dead >>, C<< $parser->strip_verbatim_indent( I<SOMEVALUE> )
->>
-
-=item TERTIARY METHODS
-
-C<< $parser->abandon_output_fh() >>X<abandon_output_fh>, C<<
-$parser->abandon_output_string() >>X<abandon_output_string>, C<<
-$parser->accept_code( @codes ) >>X<accept_code>, C<< $parser->accept_codes(
-@codes ) >>X<accept_codes>, C<< $parser->accept_directive_as_data(
-@directives ) >>X<accept_directive_as_data>, C<<
-$parser->accept_directive_as_processed( @directives )
->>X<accept_directive_as_processed>, C<<
-$parser->accept_directive_as_verbatim( @directives )
->>X<accept_directive_as_verbatim>, C<< $parser->accept_target( @targets )
->>X<accept_target>, C<< $parser->accept_target_as_text( @targets )
->>X<accept_target_as_text>, C<< $parser->accept_targets( @targets )
->>X<accept_targets>, C<< $parser->accept_targets_as_text( @targets )
->>X<accept_targets_as_text>, C<< $parser->any_errata_seen()
->>X<any_errata_seen>, C<< $parser->parse_from_file( $source, $to )
->>X<parse_from_file>, C<< $parser->scream( @error_messages ) >>X<scream>,
-C<< $parser->unaccept_code( @codes ) >>X<unaccept_code>, C<<
-$parser->unaccept_codes( @codes ) >>X<unaccept_codes>, C<<
-$parser->unaccept_directive( @directives ) >>X<unaccept_directive>, C<<
-$parser->unaccept_directives( @directives ) >>X<unaccept_directives>, C<<
-$parser->unaccept_target( @targets ) >>X<unaccept_target>, C<<
-$parser->unaccept_targets( @targets ) >>X<unaccept_targets>, C<<
-$parser->version_report() >>X<version_report>, C<< $parser->whine(
-@error_messages ) >>X<whine>
-
-=item CAVEATS
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>, Gabor Szabo C<szabgab@gmail.com>,
-Shawn H Corey C<SHCOREY at cpan.org>
-
-=back
-
-=head2 Pod::Simple::Checker -- check the Pod syntax of a document
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::Debug -- put Pod::Simple into trace/debug mode
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CAVEATS
-
-=item GUTS
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::DumpAsText -- dump Pod-parsing events as text
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::DumpAsXML -- turn Pod into XML
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::HTML - convert Pod to HTML
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CALLING FROM THE COMMAND LINE
-
-=item CALLING FROM PERL
-
-=over 4
-
-=item Minimal code
-
-=item More detailed example
-
-=back
-
-=item METHODS
-
-=over 4
-
-=item html_css
-
-=item html_javascript
-
-=item title_prefix
-
-=item title_postfix
-
-=item html_header_before_title
-
-=item html_h_level
-
-=item index
-
-=item html_header_after_title
-
-=item html_footer
-
-=back
-
-=item SUBCLASSING
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item ACKNOWLEDGEMENTS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::HTMLBatch - convert several Pod files to several HTML
-files
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item FROM THE COMMAND LINE
-
-=back
-
-=item MAIN METHODS
-
-$batchconv = Pod::Simple::HTMLBatch->new;, $batchconv->batch_convert(
-I<indirs>, I<outdir> );, $batchconv->batch_convert( undef , ...);,
-$batchconv->batch_convert( q{@INC}, ...);, $batchconv->batch_convert(
-\@dirs , ...);, $batchconv->batch_convert( "somedir" , ...);,
-$batchconv->batch_convert( 'somedir:someother:also' , ...);,
-$batchconv->batch_convert( ... , undef );, $batchconv->batch_convert( ... ,
-'somedir' );
-
-=over 4
-
-=item ACCESSOR METHODS
-
-$batchconv->verbose( I<nonnegative_integer> );, $batchconv->index(
-I<true-or-false> );, $batchconv->contents_file( I<filename> );,
-$batchconv->contents_page_start( I<HTML_string> );,
-$batchconv->contents_page_end( I<HTML_string> );, $batchconv->add_css( $url
-);, $batchconv->add_javascript( $url );, $batchconv->css_flurry(
-I<true-or-false> );, $batchconv->javascript_flurry( I<true-or-false> );,
-$batchconv->no_contents_links( I<true-or-false> );,
-$batchconv->html_render_class( I<classname> );, $batchconv->search_class(
-I<classname> );
-
-=back
-
-=item NOTES ON CUSTOMIZATION
-
-=item ASK ME!
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::LinkSection -- represent "section" attributes of L
-codes
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::Methody -- turn Pod::Simple events into method calls
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHOD CALLING
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::PullParser -- a pull-parser interface to parsing Pod
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-my $token = $parser->get_token, $parser->unget_token( $token ),
-$parser->unget_token( $token1, $token2, ... ), $parser->set_source(
-$filename ), $parser->set_source( $filehandle_object ),
-$parser->set_source( \$document_source ), $parser->set_source(
-\@document_lines ), $parser->parse_file(...),
-$parser->parse_string_document(...), $parser->filter(...),
-$parser->parse_from_file(...), my $title_string = $parser->get_title, my
-$title_string = $parser->get_short_title, $author_name =
-$parser->get_author, $description_name = $parser->get_description,
-$version_block = $parser->get_version
-
-=item NOTE
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::PullParserEndToken -- end-tokens from
-Pod::Simple::PullParser
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-$token->tagname, $token->tagname(I<somestring>), $token->tag(...),
-$token->is_tag(I<somestring>) or $token->is_tagname(I<somestring>)
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::PullParserStartToken -- start-tokens from
-Pod::Simple::PullParser
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-$token->tagname, $token->tagname(I<somestring>), $token->tag(...),
-$token->is_tag(I<somestring>) or $token->is_tagname(I<somestring>),
-$token->attr(I<attrname>), $token->attr(I<attrname>, I<newvalue>),
-$token->attr_hash
-
-=item SEE ALSO
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::PullParserTextToken -- text-tokens from
-Pod::Simple::PullParser
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-$token->text, $token->text(I<somestring>), $token->text_r()
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::PullParserToken -- tokens from Pod::Simple::PullParser
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-$token->type, $token->is_start, $token->is_text, $token->is_end,
-$token->dump
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::RTF -- format Pod as RTF
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item FORMAT CONTROL ATTRIBUTES
-
-$parser->head1_halfpoint_size( I<halfpoint_integer> );,
-$parser->head2_halfpoint_size( I<halfpoint_integer> );,
-$parser->head3_halfpoint_size( I<halfpoint_integer> );,
-$parser->head4_halfpoint_size( I<halfpoint_integer> );,
-$parser->codeblock_halfpoint_size( I<halfpoint_integer> );,
-$parser->header_halfpoint_size( I<halfpoint_integer> );,
-$parser->normal_halfpoint_size( I<halfpoint_integer> );,
-$parser->no_proofing_exemptions( I<true_or_false> );, $parser->doc_lang(
-I<microsoft_decimal_language_code> )
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::Search - find POD documents in directory trees
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CONSTRUCTOR
-
-=item ACCESSORS
-
-$search->inc( I<true-or-false> );, $search->verbose( I<nonnegative-number>
-);, $search->limit_glob( I<some-glob-string> );, $search->callback(
-I<\&some_routine> );, $search->laborious( I<true-or-false> );,
-$search->shadows( I<true-or-false> );, $search->limit_re( I<some-regxp> );,
-$search->dir_prefix( I<some-string-value> );, $search->progress(
-I<some-progress-object> );, $name2path = $self->name2path;, $path2name =
-$self->path2name;
-
-=item MAIN SEARCH METHODS
-
-=over 4
-
-=item C<< $search->survey( @directories ) >>
-
-C<name2path>, C<path2name>
-
-=item C<< $search->simplify_name( $str ) >>
-
-=item C<< $search->find( $pod ) >>
-
-=item C<< $search->find( $pod, @search_dirs ) >>
-
-=item C<< $self->contains_pod( $file ) >>
-
-=back
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::SimpleTree -- parse Pod into a simple parse tree
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=item Tree Contents
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::Subclassing -- write a formatter as a Pod::Simple
-subclass
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Events
-
-C<< $parser->_handle_element_start( I<element_name>, I<attr_hashref> ) >>,
-C<< $parser->_handle_element_end( I<element_name> ) >>, C<<
-$parser->_handle_text( I<text_string> ) >>, events with an element_name
-of Document, events with an element_name of Para, events with an
-element_name of B, C, F, or I, events with an element_name of S, events
-with an element_name of X, events with an element_name of L, events with an
-element_name of E or Z, events with an element_name of Verbatim, events
-with an element_name of head1 .. head4, events with an element_name of
-over-bullet, events with an element_name of over-number, events with an
-element_name of over-text, events with an element_name of over-block,
-events with an element_name of over-empty, events with an element_name of
-item-bullet, events with an element_name of item-number, events with an
-element_name of item-text, events with an element_name of for, events with
-an element_name of Data
-
-=item More Pod::Simple Methods
-
-C<< $parser->accept_targets( I<SOMEVALUE> ) >>, C<<
-$parser->accept_targets_as_text( I<SOMEVALUE> ) >>, C<<
-$parser->accept_codes( I<Codename>, I<Codename>... ) >>, C<<
-$parser->accept_directive_as_data( I<directive_name> ) >>, C<<
-$parser->accept_directive_as_verbatim( I<directive_name> ) >>, C<<
-$parser->accept_directive_as_processed( I<directive_name> ) >>, C<<
-$parser->nbsp_for_S( I<BOOLEAN> ); >>, C<< $parser->version_report() >>,
-C<< $parser->pod_para_count() >>, C<< $parser->line_count() >>, C<<
-$parser->nix_X_codes( I<SOMEVALUE> ) >>, C<< $parser->merge_text(
-I<SOMEVALUE> ) >>, C<< $parser->code_handler( I<CODE_REF> ) >>, C<<
-$parser->cut_handler( I<CODE_REF> ) >>, C<< $parser->pod_handler(
-I<CODE_REF> ) >>, C<< $parser->whiteline_handler( I<CODE_REF> ) >>, C<<
-$parser->whine( I<linenumber>, I<complaint string> ) >>, C<<
-$parser->scream( I<linenumber>, I<complaint string> ) >>, C<<
-$parser->source_dead(1) >>, C<< $parser->hide_line_numbers( I<SOMEVALUE> )
->>, C<< $parser->no_whining( I<SOMEVALUE> ) >>, C<<
-$parser->no_errata_section( I<SOMEVALUE> ) >>, C<<
-$parser->complain_stderr( I<SOMEVALUE> ) >>, C<< $parser->bare_output(
-I<SOMEVALUE> ) >>, C<< $parser->preserve_whitespace( I<SOMEVALUE> ) >>, C<<
-$parser->parse_empty_lists( I<SOMEVALUE> ) >>
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::Text -- format Pod as plaintext
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::TextContent -- get the text content of Pod
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::XHTML -- format Pod as validating XHTML
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Minimal code
-
-=back
-
-=back
-
-=over 4
-
-=item METHODS
-
-=over 4
-
-=item perldoc_url_prefix
-
-=item perldoc_url_postfix
-
-=item man_url_prefix
-
-=item man_url_postfix
-
-=item title_prefix, title_postfix
-
-=item html_css
-
-=item html_javascript
-
-=item html_doctype
-
-=item html_charset
-
-=item html_header_tags
-
-=item html_h_level
-
-=item default_title
-
-=item force_title
-
-=item html_header, html_footer
-
-=item index
-
-=item anchor_items
-
-=item backlink
-
-=back
-
-=back
-
-=over 4
-
-=item SUBCLASSING
-
-=back
-
-=over 4
-
-=item handle_text
-
-=item accept_targets_as_html
-
-=back
-
-=over 4
-
-=item resolve_pod_page_link
-
-=back
-
-=over 4
-
-=item resolve_man_page_link
-
-=back
-
-=over 4
-
-=item idify
-
-=back
-
-=over 4
-
-=item batch_mode_page_object_init
-
-=back
-
-=over 4
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item ACKNOWLEDGEMENTS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Simple::XMLOutStream -- turn Pod into XML
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=item ABOUT EXTENDING POD
-
-=item ASK ME!
-
-=item SEE ALSO
-
-=item SUPPORT
-
-=item COPYRIGHT AND DISCLAIMERS
-
-=item AUTHOR
-
-Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>,
-David E. Wheeler C<dwheeler@cpan.org>
-
-=back
-
-=head2 Pod::Text - Convert POD data to formatted ASCII text
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-alt, code, indent, loose, margin, quotes, sentence, stderr, utf8, width
-
-=item DIAGNOSTICS
-
-Bizarre space in item, Item called without tag, Can't open %s for reading:
-%s, Invalid quote specification "%s"
-
-=item BUGS
-
-=item CAVEATS
-
-=item NOTES
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 Pod::Text::Color - Convert POD data to formatted color ASCII text
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item BUGS
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 Pod::Text::Overstrike, =for stopwords
-overstrike
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item BUGS
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 Pod::Text::Termcap - Convert POD data to ASCII text with format
-escapes
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item NOTES
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 Pod::Usage, pod2usage() - print a usage message from embedded pod
-documentation
-
-=over 4
-
-=item SYNOPSIS
-
-=item ARGUMENTS
-
-C<-message>, C<-msg>, C<-exitval>, C<-verbose>, C<-sections>, C<-output>,
-C<-input>, C<-pathlist>, C<-noperldoc>
-
-=over 4
-
-=item Pass-through options
-
-=back
-
-=item DESCRIPTION
-
-=item EXAMPLES
-
-=over 4
-
-=item Recommended Use
-
-=back
-
-=item CAVEATS
-
-=item AUTHOR
-
-=item ACKNOWLEDGMENTS
-
-=item SEE ALSO
-
-=back
-
-=head2 SDBM_File - Tied access to sdbm files
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-C<O_RDONLY>, C<O_WRONLY>, C<O_RDWR>
-
-=item DIAGNOSTICS
-
-=over 4
-
-=item C<sdbm store returned -1, errno 22, key "..." at ...>
-
-=back
-
-=item BUGS AND WARNINGS
-
-=back
-
-=head2 Safe - Compile and execute code in restricted compartments
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-a new namespace, an operator mask
-
-=item WARNING
-
-=item METHODS
-
-=over 4
-
-=item permit (OP, ...)
-
-=item permit_only (OP, ...)
-
-=item deny (OP, ...)
-
-=item deny_only (OP, ...)
-
-=item trap (OP, ...)
-
-=item untrap (OP, ...)
-
-=item share (NAME, ...)
-
-=item share_from (PACKAGE, ARRAYREF)
-
-=item varglob (VARNAME)
-
-=item reval (STRING, STRICT)
-
-=item rdo (FILENAME)
-
-=item root (NAMESPACE)
-
-=item mask (MASK)
-
-=item wrap_code_ref (CODEREF)
-
-=item wrap_code_refs_within (...)
-
-=back
-
-=item RISKS
-
-Memory, CPU, Snooping, Signals, State Changes
-
-=item AUTHOR
-
-=back
-
-=head2 Scalar::Util - A selection of general-utility scalar subroutines
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-blessed EXPR, dualvar NUM, STRING, isvstring EXPR, isweak EXPR,
-looks_like_number EXPR, openhandle FH, refaddr EXPR, reftype EXPR,
-set_prototype CODEREF, PROTOTYPE, tainted EXPR, weaken REF
-
-=item DIAGNOSTICS
-
-Weak references are not implemented in the version of perl, Vstrings are
-not implemented in the version of perl, C<NAME> is only available with the
-XS version of Scalar::Util
-
-=item KNOWN BUGS
-
-=item SEE ALSO
-
-=item COPYRIGHT
-
-=back
-
-=head2 Search::Dict - look - search for key in dictionary file
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 SelectSaver - save and restore selected file handle
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 SelfLoader - load functions only on demand
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item The __DATA__ token
-
-=item SelfLoader autoloading
-
-=item Autoloading and package lexicals
-
-=item SelfLoader and AutoLoader
-
-=item __DATA__, __END__, and the FOOBAR::DATA filehandle.
-
-=item Classes and inherited methods.
-
-=back
-
-=item Multiple packages and fully qualified subroutine names
-
-=item AUTHOR
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 Socket, C<Socket> - networking constants and support functions
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item CONSTANTS
-
-=back
-
-=over 4
-
-=item PF_INET, PF_INET6, PF_UNIX, ...
-
-=item AF_INET, AF_INET6, AF_UNIX, ...
-
-=item SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, ...
-
-=item SOL_SOCKET
-
-=item SO_ACCEPTCONN, SO_BROADCAST, SO_ERROR, ...
-
-=item IP_OPTIONS, IP_TOS, IP_TTL, ...
-
-=item MSG_BCAST, MSG_OOB, MSG_TRUNC, ...
-
-=item SHUT_RD, SHUT_RDWR, SHUT_WR
-
-=item INADDR_ANY, INADDR_BROADCAST, INADDR_LOOPBACK, INADDR_NONE
-
-=item IPPROTO_IP, IPPROTO_IPV6, IPPROTO_TCP, ...
-
-=item TCP_CORK, TCP_KEEPALIVE, TCP_NODELAY, ...
-
-=item IN6ADDR_ANY, IN6ADDR_LOOPBACK
-
-=item IPV6_ADD_MEMBERSHIP, IPV6_MTU, IPV6_V6ONLY, ...
-
-=back
-
-=over 4
-
-=item STRUCTURE MANIPULATORS
-
-=back
-
-=over 4
-
-=item $family = sockaddr_family $sockaddr
-
-=item $sockaddr = pack_sockaddr_in $port, $ip_address
-
-=item ($port, $ip_address) = unpack_sockaddr_in $sockaddr
-
-=item $sockaddr = sockaddr_in $port, $ip_address
-
-=item ($port, $ip_address) = sockaddr_in $sockaddr
-
-=item $sockaddr = pack_sockaddr_in6 $port, $ip6_address, [$scope_id,
-[$flowinfo]]
-
-=item ($port, $ip6_address, $scope_id, $flowinfo) = unpack_sockaddr_in6
-$sockaddr
-
-=item $sockaddr = sockaddr_in6 $port, $ip6_address, [$scope_id,
-[$flowinfo]]
-
-=item ($port, $ip6_address, $scope_id, $flowinfo) = sockaddr_in6 $sockaddr
-
-=item $sockaddr = pack_sockaddr_un $path
-
-=item ($path) = unpack_sockaddr_un $sockaddr
-
-=item $sockaddr = sockaddr_un $path
-
-=item ($path) = sockaddr_un $sockaddr
-
-=item $ipv6_mreq = pack_ipv6_mreq $ip6_address, $ifindex
-
-=item ($ip6_address, $ifindex) = unpack_ipv6_mreq $ipv6_mreq
-
-=back
-
-=over 4
-
-=item FUNCTIONS
-
-=back
-
-=over 4
-
-=item $ip_address = inet_aton $string
-
-=item $string = inet_ntoa $ip_address
-
-=item $address = inet_pton $family, $string
-
-=item $string = inet_ntop $family, $address
-
-=item ($err, @result) = getaddrinfo $host, $service, [$hints]
-
-flags => INT, family => INT, socktype => INT, protocol => INT, family =>
-INT, socktype => INT, protocol => INT, addr => STRING, canonname => STRING,
-AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST
-
-=item ($err, $hostname, $servicename) = getnameinfo $sockaddr, [$flags,
-[$xflags]]
-
-NI_NUMERICHOST, NI_NUMERICSERV, NI_NAMEREQD, NI_DGRAM, NIx_NOHOST,
-NIx_NOSERV
-
-=back
-
-=over 4
-
-=item getaddrinfo() / getnameinfo() ERROR CONSTANTS
-
-EAI_AGAIN, EAI_BADFLAGS, EAI_FAMILY, EAI_NODATA, EAI_NONAME, EAI_SERVICE
-
-=back
-
-=over 4
-
-=item EXAMPLES
-
-=over 4
-
-=item Lookup for connect()
-
-=item Making a human-readable string out of an address
-
-=item Resolving hostnames into IP addresses
-
-=item Accessing socket options
-
-=back
-
-=back
-
-=over 4
-
-=item AUTHOR
-
-=back
-
-=head2 Storable - persistence for Perl data structures
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item MEMORY STORE
-
-=item ADVISORY LOCKING
-
-=item SPEED
-
-=item CANONICAL REPRESENTATION
-
-=item CODE REFERENCES
-
-=item FORWARD COMPATIBILITY
-
-utf8 data, restricted hashes, files from future versions of Storable
-
-=item ERROR REPORTING
-
-=item WIZARDS ONLY
-
-=over 4
-
-=item Hooks
-
-C<STORABLE_freeze> I<obj>, I<cloning>, C<STORABLE_thaw> I<obj>, I<cloning>,
-I<serialized>, .., C<STORABLE_attach> I<class>, I<cloning>, I<serialized>
-
-=item Predicates
-
-C<Storable::last_op_in_netorder>, C<Storable::is_storing>,
-C<Storable::is_retrieving>
-
-=item Recursion
-
-=item Deep Cloning
-
-=back
-
-=item Storable magic
-
-$info = Storable::file_magic( $filename ), C<version>, C<version_nv>,
-C<major>, C<minor>, C<hdrsize>, C<netorder>, C<byteorder>, C<intsize>,
-C<longsize>, C<ptrsize>, C<nvsize>, C<file>, $info = Storable::read_magic(
-$buffer ), $info = Storable::read_magic( $buffer, $must_be_file )
-
-=item EXAMPLES
-
-=item WARNING
-
-=item BUGS
-
-=over 4
-
-=item 64 bit data in perl 5.6.0 and 5.6.1
-
-=back
-
-=item CREDITS
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Symbol - manipulate Perl symbols and their names
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item BUGS
-
-=back
-
-=head2 Sys::Hostname - Try every conceivable way to get hostname
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=back
-
-=head2 TAP::Base - Base class that provides common functionality to
-L<TAP::Parser>
-and L<TAP::Harness>
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=head2 TAP::Formatter::Base - Base class for harness output delegates
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item SYNOPSIS
-
-=back
-
-=over 4
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-C<verbosity>, C<verbose>, C<timer>, C<failures>, C<comments>, C<quiet>,
-C<really_quiet>, C<silent>, C<errors>, C<directives>, C<stdout>, C<color>,
-C<jobs>, C<show_count>
-
-=back
-
-=back
-
-=head2 TAP::Formatter::Color - Run Perl test scripts with color
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item SYNOPSIS
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=head2 TAP::Formatter::Console - Harness output delegate for default
-console output
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item SYNOPSIS
-
-=over 4
-
-=item C<< open_test >>
-
-=back
-
-=back
-
-=head2 TAP::Formatter::Console::ParallelSession - Harness output delegate
-for parallel console output
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item SYNOPSIS
-
-=back
-
-=over 4
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=head2 TAP::Formatter::Console::Session - Harness output delegate for
-default console output
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item C<< clear_for_close >>
-
-=item C<< close_test >>
-
-=item C<< header >>
-
-=item C<< result >>
-
-=back
-
-=head2 TAP::Formatter::File - Harness output delegate for file output
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item SYNOPSIS
-
-=over 4
-
-=item C<< open_test >>
-
-=back
-
-=back
-
-=head2 TAP::Formatter::File::Session - Harness output delegate for file
-output
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item METHODS
-
-=over 4
-
-=item result
-
-=back
-
-=back
-
-=over 4
-
-=item close_test
-
-=back
-
-=head2 TAP::Formatter::Session - Abstract base class for harness output
-delegate
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-C<formatter>, C<parser>, C<name>, C<show_count>
-
-=back
-
-=back
-
-=head2 TAP::Harness - Run test scripts with statistics
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item SYNOPSIS
-
-=back
-
-=over 4
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-C<verbosity>, C<timer>, C<failures>, C<comments>, C<show_count>,
-C<normalize>, C<lib>, C<switches>, C<test_args>, C<color>, C<exec>,
-C<merge>, C<sources>, C<aggregator_class>, C<version>, C<formatter_class>,
-C<multiplexer_class>, C<parser_class>, C<scheduler_class>, C<formatter>,
-C<errors>, C<directives>, C<ignore_exit>, C<jobs>, C<rules>, C<stdout>,
-C<trap>
-
-=back
-
-=back
-
-=over 4
-
-=item Instance Methods
-
-=back
-
-the source name of a test to run, a reference to a [ source name, display
-name ] array
-
-=over 4
-
-=item CONFIGURING
-
-=over 4
-
-=item Plugins
-
-=item C<Module::Build>
-
-=item C<ExtUtils::MakeMaker>
-
-=item C<prove>
-
-=back
-
-=item WRITING PLUGINS
-
-Customize how TAP gets into the parser, Customize how TAP results are
-output from the parser
-
-=item SUBCLASSING
-
-=over 4
-
-=item Methods
-
-L</new>, L</runtests>, L</summary>
-
-=back
-
-=back
-
-=over 4
-
-=item REPLACING
-
-=item SEE ALSO
-
-=back
-
-=head2 TAP::Object - Base class that provides common functionality to all
-C<TAP::*> modules
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=over 4
-
-=item Instance Methods
-
-=back
-
-=head2 TAP::Parser - Parse L<TAP|Test::Harness::TAP> output
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-C<source>, C<tap>, C<exec>, C<sources>, C<callback>, C<switches>,
-C<test_args>, C<spool>, C<merge>, C<grammar_class>,
-C<result_factory_class>, C<iterator_factory_class>
-
-=back
-
-=back
-
-=over 4
-
-=item Instance Methods
-
-=back
-
-=over 4
-
-=item INDIVIDUAL RESULTS
-
-=over 4
-
-=item Result types
-
-Version, Plan, Pragma, Test, Comment, Bailout, Unknown
-
-=item Common type methods
-
-=item C<plan> methods
-
-=item C<pragma> methods
-
-=item C<bailout> methods
-
-=item C<unknown> methods
-
-=item C<test> methods
-
-=back
-
-=item TOTAL RESULTS
-
-=over 4
-
-=item Individual Results
-
-=back
-
-=back
-
-=over 4
-
-=item Pragmas
-
-=back
-
-=over 4
-
-=item Summary Results
-
-=back
-
-=over 4
-
-=item C<ignore_exit>
-
-=back
-
-Misplaced plan, No plan, More than one plan, Test numbers out of sequence
-
-=over 4
-
-=item CALLBACKS
-
-C<test>, C<version>, C<plan>, C<comment>, C<bailout>, C<yaml>, C<unknown>,
-C<ELSE>, C<ALL>, C<EOF>
-
-=item TAP GRAMMAR
-
-=item BACKWARDS COMPATIBILITY
-
-=over 4
-
-=item Differences
-
-TODO plans, 'Missing' tests
-
-=back
-
-=item SUBCLASSING
-
-=over 4
-
-=item Parser Components
-
-option 1, option 2
-
-=back
-
-=item ACKNOWLEDGMENTS
-
-Michael Schwern, Andy Lester, chromatic, GEOFFR, Shlomi Fish, Torsten
-Schoenfeld, Jerry Gay, Aristotle, Adam Kennedy, Yves Orton, Adrian Howard,
-Sean & Lil, Andreas J. Koenig, Florian Ragwitz, Corion, Mark Stosberg, Matt
-Kraai, David Wheeler, Alex Vandiver, Cosimo Streppone, Ville Skyttä
-
-=item AUTHORS
-
-=item BUGS
-
-=item COPYRIGHT & LICENSE
-
-=back
-
-=head2 TAP::Parser::Aggregator - Aggregate TAP::Parser results
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=over 4
-
-=item Instance Methods
-
-=back
-
-=over 4
-
-=item Summary methods
-
-failed, parse_errors, passed, planned, skipped, todo, todo_passed, wait,
-exit
-
-=back
-
-Failed tests, Parse errors, Bad exit or wait status
-
-=over 4
-
-=item See Also
-
-=back
-
-=head2 TAP::Parser::Grammar - A grammar for the Test Anything Protocol.
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=over 4
-
-=item Instance Methods
-
-=back
-
-=over 4
-
-=item TAP GRAMMAR
-
-=item SUBCLASSING
-
-=item SEE ALSO
-
-=back
-
-=head2 TAP::Parser::Iterator - Base class for TAP source iterators
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=item Instance Methods
-
-=back
-
-=back
-
-=over 4
-
-=item SUBCLASSING
-
-=over 4
-
-=item Example
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 TAP::Parser::Iterator::Array - Iterator for array-based TAP sources
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=item Instance Methods
-
-=back
-
-=back
-
-=over 4
-
-=item ATTRIBUTION
-
-=item SEE ALSO
-
-=back
-
-=head2 TAP::Parser::Iterator::Process - Iterator for process-based TAP
-sources
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=item Instance Methods
-
-=back
-
-=back
-
-=over 4
-
-=item ATTRIBUTION
-
-=item SEE ALSO
-
-=back
-
-=head2 TAP::Parser::Iterator::Stream - Iterator for filehandle-based TAP
-sources
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=over 4
-
-=item Instance Methods
-
-=back
-
-=over 4
-
-=item ATTRIBUTION
-
-=item SEE ALSO
-
-=back
-
-=head2 TAP::Parser::IteratorFactory - Figures out which SourceHandler
-objects to use for a given Source
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=over 4
-
-=item Instance Methods
-
-=back
-
-=over 4
-
-=item SUBCLASSING
-
-=over 4
-
-=item Example
-
-=back
-
-=item AUTHORS
-
-=item ATTRIBUTION
-
-=item SEE ALSO
-
-=back
-
-=head2 TAP::Parser::Multiplexer - Multiplex multiple TAP::Parsers
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=over 4
-
-=item Instance Methods
-
-=back
-
-=over 4
-
-=item See Also
-
-=back
-
-=head2 TAP::Parser::Result - Base class for TAP::Parser output objects
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=over 4
-
-=item DESCRIPTION
-
-=item METHODS
-
-=back
-
-=back
-
-=over 4
-
-=item Boolean methods
-
-C<is_plan>, C<is_pragma>, C<is_test>, C<is_comment>, C<is_bailout>,
-C<is_version>, C<is_unknown>, C<is_yaml>
-
-=back
-
-=over 4
-
-=item SUBCLASSING
-
-=over 4
-
-=item Example
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 TAP::Parser::Result::Bailout - Bailout result token.
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item OVERRIDDEN METHODS
-
-C<as_string>
-
-=back
-
-=over 4
-
-=item Instance Methods
-
-=back
-
-=head2 TAP::Parser::Result::Comment - Comment result token.
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item OVERRIDDEN METHODS
-
-C<as_string>
-
-=back
-
-=over 4
-
-=item Instance Methods
-
-=back
-
-=head2 TAP::Parser::Result::Plan - Plan result token.
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item OVERRIDDEN METHODS
-
-C<as_string>, C<raw>
-
-=back
-
-=over 4
-
-=item Instance Methods
-
-=back
-
-=head2 TAP::Parser::Result::Pragma - TAP pragma token.
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item OVERRIDDEN METHODS
-
-C<as_string>, C<raw>
-
-=back
-
-=over 4
-
-=item Instance Methods
-
-=back
-
-=head2 TAP::Parser::Result::Test - Test result token.
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item OVERRIDDEN METHODS
-
-=over 4
-
-=item Instance Methods
-
-=back
-
-=back
-
-=head2 TAP::Parser::Result::Unknown - Unknown result token.
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item OVERRIDDEN METHODS
-
-C<as_string>, C<raw>
-
-=back
-
-=head2 TAP::Parser::Result::Version - TAP syntax version token.
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item OVERRIDDEN METHODS
-
-C<as_string>, C<raw>
-
-=back
-
-=over 4
-
-=item Instance Methods
-
-=back
-
-=head2 TAP::Parser::Result::YAML - YAML result token.
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item OVERRIDDEN METHODS
-
-C<as_string>, C<raw>
-
-=back
-
-=over 4
-
-=item Instance Methods
-
-=back
-
-=head2 TAP::Parser::ResultFactory - Factory for creating TAP::Parser output
-objects
-
-=over 4
-
-=item SYNOPSIS
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item DESCRIPTION
-
-=item METHODS
-
-=item Class Methods
-
-=back
-
-=over 4
-
-=item SUBCLASSING
-
-=over 4
-
-=item Example
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 TAP::Parser::Scheduler - Schedule tests during parallel testing
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=head2 TAP::Parser::Scheduler::Job - A single testing job.
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=head2 TAP::Parser::Scheduler::Spinner - A no-op job.
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=head2 TAP::Parser::Source - a TAP source & meta data about it
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=over 4
-
-=item Instance Methods
-
-=back
-
-=over 4
-
-=item AUTHORS
-
-=item SEE ALSO
-
-=back
-
-=head2 TAP::Parser::SourceHandler - Base class for different TAP source
-handlers
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=over 4
-
-=item SUBCLASSING
-
-=over 4
-
-=item Example
-
-=back
-
-=item AUTHORS
-
-=item SEE ALSO
-
-=back
-
-=head2 TAP::Parser::SourceHandler::Executable - Stream output from an
-executable TAP source
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=over 4
-
-=item SUBCLASSING
-
-=over 4
-
-=item Example
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 TAP::Parser::SourceHandler::File - Stream TAP from a text file.
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=over 4
-
-=item CONFIGURATION
-
-=item SUBCLASSING
-
-=item SEE ALSO
-
-=back
-
-=head2 TAP::Parser::SourceHandler::Handle - Stream TAP from an IO::Handle
-or a GLOB.
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=over 4
-
-=item SUBCLASSING
-
-=item SEE ALSO
-
-=back
-
-=head2 TAP::Parser::SourceHandler::Perl - Stream TAP from a Perl executable
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=over 4
-
-=item SUBCLASSING
-
-=over 4
-
-=item Example
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 TAP::Parser::SourceHandler::RawTAP - Stream output from raw TAP in a
-scalar/array ref.
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=back
-
-=back
-
-=over 4
-
-=item SUBCLASSING
-
-=item SEE ALSO
-
-=back
-
-=head2 TAP::Parser::Utils - Internal TAP::Parser utilities
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item INTERFACE
-
-=back
-
-=back
-
-=head2 TAP::Parser::YAMLish::Reader - Read YAMLish data from iterator
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=item Instance Methods
-
-=back
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=item COPYRIGHT
-
-=back
-
-=head2 TAP::Parser::YAMLish::Writer - Write YAMLish data
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=over 4
-
-=item Class Methods
-
-=item Instance Methods
-
-a reference to a scalar to append YAML to, the handle of an open file, a
-reference to an array into which YAML will be pushed, a code reference
-
-=back
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=item COPYRIGHT
-
-=back
-
-=head2 Term::ANSIColor - Color screen output using ANSI escape sequences
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Supported Colors
-
-=item Function Interface
-
-color(ATTR[, ATTR ...]), colored(STRING, ATTRIBUTES), colored(ATTR-REF,
-STRING[, STRING...]), uncolor(ESCAPE), colorstrip(STRING[, STRING ...]),
-colorvalid(ATTR[, ATTR ...])
-
-=item Constant Interface
-
-=item The Color Stack
-
-=back
-
-=item DIAGNOSTICS
-
-Bad escape sequence %s, Bareword "%s" not allowed while "strict subs" in
-use, Invalid attribute name %s, Name "%s" used only once: possible typo, No
-comma allowed after filehandle, No name for escape sequence %s
-
-=item ENVIRONMENT
-
-ANSI_COLORS_DISABLED
-
-=item RESTRICTIONS
-
-=item NOTES
-
-=item SEE ALSO
-
-=item AUTHORS
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 Term::Cap - Perl termcap interface
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item METHODS
-
-=back
-
-=back
-
-B<Tgetent>, OSPEED, TERM
-
-B<Tpad>, B<$string>, B<$cnt>, B<$FH>
-
-B<Tputs>, B<$cap>, B<$cnt>, B<$FH>
-
-B<Tgoto>, B<$cap>, B<$col>, B<$row>, B<$FH>
-
-B<Trequire>
-
-=over 4
-
-=item EXAMPLES
-
-=item COPYRIGHT AND LICENSE
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Term::Complete - Perl word completion module
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-E<lt>tabE<gt>, ^D, ^U, E<lt>delE<gt>, E<lt>bsE<gt>
-
-=item DIAGNOSTICS
-
-=item BUGS
-
-=item AUTHOR
-
-=back
-
-=head2 Term::ReadLine - Perl interface to various C<readline> packages.
-If no real package is found, substitutes stubs instead of basic functions.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Minimal set of supported functions
-
-C<ReadLine>, C<new>, C<readline>, C<addhistory>, C<IN>, C<OUT>, C<MinLine>,
-C<findConsole>, Attribs, C<Features>
-
-=item Additional supported functions
-
-C<tkRunning>, C<event_loop>, C<ornaments>, C<newTTY>
-
-=item EXPORTS
-
-=item ENVIRONMENT
-
-=back
-
-=head2 Term::UI - Term::ReadLine UI made easy
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item HOW IT WORKS
-
-=item METHODS
-
-=over 4
-
-=item $reply = $term->get_reply( prompt => 'question?', [choices => \@list,
-default => $list[0], multi => BOOL, print_me => "extra text to print &
-record", allow => $ref] );
-
-=back
-
-=back
-
-=over 4
-
-=item $bool = $term->ask_yn( prompt => "your question", [default =>
-(y|1,n|0), print_me => "extra text to print & record"] )
-
-=back
-
-=over 4
-
-=item ($opts, $munged) = $term->parse_options( STRING );
-
-=back
-
-=over 4
-
-=item $str = $term->history_as_string
-
-=back
-
-=over 4
-
-=item GLOBAL VARIABLES
-
-=over 4
-
-=item $Term::UI::VERBOSE
-
-=item $Term::UI::AUTOREPLY
-
-=item $Term::UI::INVALID
-
-=item $Term::UI::History::HISTORY_FH
-
-=back
-
-=item EXAMPLES
-
-=over 4
-
-=item Basic get_reply sample
-
-=item get_reply with choices
-
-=item get_reply with choices and default
-
-=item get_reply using print_me & multi
-
-=item get_reply & allow
-
-=item an elaborate ask_yn sample
-
-=back
-
-=item See Also
-
-=item BUG REPORTS
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Term::UI::History - history function
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item FUNCTIONS
-
-=over 4
-
-=item history("message string" [,VERBOSE])
-
-=back
-
-=back
-
-=over 4
-
-=item GLOBAL VARIABLES
-
-$HISTORY_FH
-
-=item See Also
-
-=item AUTHOR
-
-=item COPYRIGHT
-
-=back
-
-=head2 Test - provides a simple framework for writing test scripts
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item QUICK START GUIDE
-
-=over 4
-
-=item Functions
-
-C<plan(...)>, C<tests =E<gt> I<number>>, C<todo =E<gt> [I<1,5,14>]>,
-C<onfail =E<gt> sub { ... }>, C<onfail =E<gt> \&some_sub>
-
-=back
-
-=back
-
-B<_to_value>
-
-C<ok(...)>
-
-C<skip(I<skip_if_true>, I<args...>)>
-
-=over 4
-
-=item TEST TYPES
-
-NORMAL TESTS, SKIPPED TESTS, TODO TESTS
-
-=item ONFAIL
-
-=item BUGS and CAVEATS
-
-=item ENVIRONMENT
-
-=item NOTE
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 Test::Builder - Backend for building test libraries
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Construction
-
-B<new>
-
-=back
-
-=back
-
-B<create>
-
-B<child>
-
-B<subtest>
-
-B<_plan_handled>, Explicitly setting the number of tests, Setting
-'no_plan', Set 'skip_all'
-
-B<finalize>
-
-B<parent>
-
-B<name>
-
-B<reset>
-
-=over 4
-
-=item Setting up tests
-
-B<plan>
-
-=back
-
-B<expected_tests>
-
-B<no_plan>
-
-B<_output_plan>
-
-B<done_testing>
-
-B<has_plan>
-
-B<skip_all>
-
-B<exported_to>
-
-=over 4
-
-=item Running tests
-
-B<ok>
-
-=back
-
-B<is_eq>, B<is_num>
-
-B<isnt_eq>, B<isnt_num>
-
-B<like>, B<unlike>
-
-B<cmp_ok>
-
-=over 4
-
-=item Other Testing Methods
-
-B<BAIL_OUT>
-
-=back
-
-B<skip>
-
-B<todo_skip>
-
-B<skip_rest>
-
-=over 4
-
-=item Test building utility methods
-
-B<maybe_regex>
-
-=back
-
-B<_try>
-
-B<is_fh>
-
-=over 4
-
-=item Test style
-
-B<level>
-
-=back
-
-B<use_numbers>
-
-B<no_diag>, B<no_ending>, B<no_header>
-
-=over 4
-
-=item Output
-
-B<diag>
-
-=back
-
-B<note>
-
-B<explain>
-
-B<_print>
-
-B<output>, B<failure_output>, B<todo_output>
-
-reset_outputs
-
-carp, croak
-
-=over 4
-
-=item Test Status and Info
-
-B<current_test>
-
-=back
-
-B<is_passing>
-
-B<summary>
-
-B<details>
-
-B<todo>
-
-B<find_TODO>
-
-B<in_todo>
-
-B<todo_start>
-
-C<todo_end>
-
-B<caller>
-
-B<_sanity_check>
-
-B<_whoa>
-
-B<_my_exit>
-
-=over 4
-
-=item EXIT CODES
-
-=item THREADS
-
-=item MEMORY
-
-=item EXAMPLES
-
-=item SEE ALSO
-
-=item AUTHORS
-
-=item COPYRIGHT
-
-=back
-
-=head2 Test::Builder::Module - Base class for test modules
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Importing
-
-=back
-
-=back
-
-=over 4
-
-=item Builder
-
-=back
-
-=head2 Test::Builder::Tester - test testsuites that have been built with
-Test::Builder
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item Functions
-
-test_out, test_err
-
-=back
-
-test_fail
-
-test_diag
-
-test_test, title (synonym 'name', 'label'), skip_out, skip_err
-
-line_num
-
-color
-
-=over 4
-
-=item BUGS
-
-=item AUTHOR
-
-=item NOTES
-
-=item SEE ALSO
-
-=back
-
-=head2 Test::Builder::Tester::Color - turn on colour in
-Test::Builder::Tester
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=over 4
-
-=item AUTHOR
-
-=item BUGS
-
-=item SEE ALSO
-
-=back
-
-=head2 Test::Harness - Run Perl standard test scripts with statistics
-
-=over 4
-
-=item VERSION
-
-=back
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item FUNCTIONS
-
-=over 4
-
-=item runtests( @test_files )
-
-=back
-
-=back
-
-=over 4
-
-=item execute_tests( tests => \@test_files, out => \*FH )
-
-=back
-
-=over 4
-
-=item EXPORT
-
-=item ENVIRONMENT VARIABLES THAT TAP::HARNESS::COMPATIBLE SETS
-
-C<HARNESS_ACTIVE>, C<HARNESS_VERSION>
-
-=item ENVIRONMENT VARIABLES THAT AFFECT TEST::HARNESS
-
-C<HARNESS_TIMER>, C<HARNESS_VERBOSE>, C<HARNESS_OPTIONS>, C<< j<n> >>, C<<
-c >>, C<HARNESS_SUBCLASS>
-
-=item Taint Mode
-
-=item SEE ALSO
-
-=item BUGS
-
-=item AUTHORS
-
-=item LICENCE AND COPYRIGHT
-
-=back
-
-=head2 Test::More - yet another framework for writing test scripts
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item I love it when a plan comes together
-
-=back
-
-=back
-
-B<done_testing>
-
-=over 4
-
-=item Test names
-
-=item I'm ok, you're not ok.
-
-B<ok>
-
-=back
-
-B<is>, B<isnt>
-
-B<like>
-
-B<unlike>
-
-B<cmp_ok>
-
-B<can_ok>
-
-B<isa_ok>
-
-B<new_ok>
-
-B<subtest>
-
-B<pass>, B<fail>
-
-=over 4
-
-=item Module tests
-
-B<use_ok>
-
-=back
-
-B<require_ok>
-
-=over 4
-
-=item Complex data structures
-
-B<is_deeply>
-
-=back
-
-=over 4
-
-=item Diagnostics
-
-B<diag>, B<note>
-
-=back
-
-B<explain>
-
-=over 4
-
-=item Conditional tests
-
-B<SKIP: BLOCK>
-
-=back
-
-B<TODO: BLOCK>, B<todo_skip>
-
-When do I use SKIP vs. TODO?
-
-=over 4
-
-=item Test control
-
-B<BAIL_OUT>
-
-=back
-
-=over 4
-
-=item Discouraged comparison functions
-
-B<eq_array>
-
-=back
-
-B<eq_hash>
-
-B<eq_set>
-
-=over 4
-
-=item Extending and Embedding Test::More
-
-B<builder>
-
-=back
-
-=over 4
-
-=item EXIT CODES
-
-=item CAVEATS and NOTES
-
-Backwards compatibility, utf8 / "Wide character in print", Overloaded
-objects, Threads
-
-=item HISTORY
-
-=item SEE ALSO
-
-=item AUTHORS
-
-=item BUGS
-
-=item SOURCE
-
-=item COPYRIGHT
-
-=back
-
-=head2 Test::Simple - Basic utilities for writing tests.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-B<ok>
-
-=back
-
-=over 4
-
-=item EXAMPLE
-
-=item CAVEATS
-
-=item NOTES
-
-=item HISTORY
-
-=item SEE ALSO
-
-L<Test::More>
-
-=item AUTHORS
-
-=item COPYRIGHT
-
-=back
-
-=head2 Test::Tutorial - A tutorial about writing really basic tests
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Nuts and bolts of testing.
-
-=item Where to start?
-
-=item Names
-
-=item Test the manual
-
-=item Sometimes the tests are wrong
-
-=item Testing lots of values
-
-=item Informative names
-
-=item Skipping tests
-
-=item Todo tests
-
-=item Testing with taint mode.
-
-=back
-
-=item FOOTNOTES
-
-=item AUTHORS
-
-=item COPYRIGHT
-
-=back
-
-=head2 Text::Abbrev - abbrev - create an abbreviation table from a list
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item EXAMPLE
-
-=back
-
-=head2 Text::Balanced - Extract delimited text sequences from strings.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item General behaviour in list contexts
-
-[0], [1], [2]
-
-=item General behaviour in scalar and void contexts
-
-=item A note about prefixes
-
-=item C<extract_delimited>
-
-=item C<extract_bracketed>
-
-=item C<extract_variable>
-
-[0], [1], [2]
-
-=item C<extract_tagged>
-
-C<reject =E<gt> $listref>, C<ignore =E<gt> $listref>, C<fail =E<gt> $str>,
-[0], [1], [2], [3], [4], [5]
-
-=item C<gen_extract_tagged>
-
-=item C<extract_quotelike>
-
-[0], [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]
-
-=item C<extract_quotelike> and "here documents"
-
-[0], [1], [2], [3], [4], [5], [6], [7..10]
-
-=item C<extract_codeblock>
-
-=item C<extract_multiple>
-
-=item C<gen_delimited_pat>
-
-=item C<delimited_pat>
-
-=back
-
-=item DIAGNOSTICS
-
- C<Did not find a suitable bracket: "%s">, C<Did not find prefix: /%s/>,
-C<Did not find opening bracket after prefix: "%s">, C<No quotelike
-operator found after prefix: "%s">, C<Unmatched closing bracket: "%c">,
-C<Unmatched opening bracket(s): "%s">, C<Unmatched embedded quote (%s)>,
-C<Did not find closing delimiter to match '%s'>, C<Mismatched closing
-bracket: expected "%c" but found "%s">, C<No block delimiter found after
-quotelike "%s">, C<Did not find leading dereferencer>, C<Bad identifier
-after dereferencer>, C<Did not find expected opening bracket at %s>,
-C<Improperly nested codeblock at %s>, C<Missing second block for quotelike
-"%s">, C<No match found for opening bracket>, C<Did not find opening tag:
-/%s/>, C<Unable to construct closing tag to match: /%s/>, C<Found invalid
-nested tag: %s>, C<Found unbalanced nested tag: %s>, C<Did not find closing
-tag>
-
-=item AUTHOR
-
-=item BUGS AND IRRITATIONS
-
-=item COPYRIGHT
-
-=back
-
-=head2 Text::ParseWords - parse text into an array of tokens or array of
-arrays
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item EXAMPLES
-
-=item AUTHORS
-
-=back
-
-=head2 Text::Soundex - Implementation of the soundex algorithm.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item EXAMPLES
-
-=item LIMITATIONS
-
-=item MAINTAINER
-
-=item HISTORY
-
-=back
-
-=head2 Text::Tabs -- expand and unexpand tabs per the unix expand(1) and
-unexpand(1)
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item EXAMPLE
-
-=item LICENSE
-
-=back
-
-=head2 Text::Wrap - line wrapping to form simple paragraphs
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item OVERRIDES
-
-=item EXAMPLES
-
-=item SEE ALSO
-
-=item LICENSE
-
-=back
-
-=head2 Thread - Manipulate threads in Perl (for old code only)
-
-=over 4
-
-=item DEPRECATED
-
-=item HISTORY
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item FUNCTIONS
-
-$thread = Thread->new(\&start_sub), $thread = Thread->new(\&start_sub,
-LIST), lock VARIABLE, async BLOCK;, Thread->self, Thread->list, cond_wait
-VARIABLE, cond_signal VARIABLE, cond_broadcast VARIABLE, yield
-
-=item METHODS
-
-join, detach, equal, tid, done
-
-=item DEFUNCT
-
-lock(\&sub), eval, flags
-
-=item SEE ALSO
-
-=back
-
-=head2 Thread::Queue - Thread-safe queues
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-Ordinary scalars, Array refs, Hash refs, Scalar refs, Objects based on the
-above
-
-=item QUEUE CREATION
-
-->new(), ->new(LIST)
-
-=item BASIC METHODS
-
-->enqueue(LIST), ->dequeue(), ->dequeue(COUNT), ->dequeue_nb(),
-->dequeue_nb(COUNT), ->pending()
-
-=item ADVANCED METHODS
-
-->peek(), ->peek(INDEX), ->insert(INDEX, LIST), ->extract(),
-->extract(INDEX), ->extract(INDEX, COUNT)
-
-=item NOTES
-
-=item LIMITATIONS
-
-=item SEE ALSO
-
-=item MAINTAINER
-
-=item LICENSE
-
-=back
-
-=head2 Thread::Semaphore - Thread-safe semaphores
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-->new(), ->new(NUMBER), ->down(), ->down(NUMBER), ->down_nb(),
-->down_nb(NUMBER), ->down_force(), ->down_force(NUMBER), ->up(),
-->up(NUMBER)
-
-=item NOTES
-
-=item SEE ALSO
-
-=item MAINTAINER
-
-=item LICENSE
-
-=back
-
-=head2 Tie::Array - base class for tied arrays
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-TIEARRAY classname, LIST, STORE this, index, value, FETCH this, index,
-FETCHSIZE this, STORESIZE this, count, EXTEND this, count, EXISTS this,
-key, DELETE this, key, CLEAR this, DESTROY this, PUSH this, LIST, POP this,
-SHIFT this, UNSHIFT this, LIST, SPLICE this, offset, length, LIST
-
-=item CAVEATS
-
-=item AUTHOR
-
-=back
-
-=head2 Tie::File - Access the lines of a disk file via a Perl array
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item C<recsep>
-
-=item C<autochomp>
-
-=item C<mode>
-
-=item C<memory>
-
-=item C<dw_size>
-
-=item Option Format
-
-=back
-
-=item Public Methods
-
-=over 4
-
-=item C<flock>
-
-=item C<autochomp>
-
-=item C<defer>, C<flush>, C<discard>, and C<autodefer>
-
-=item C<offset>
-
-=back
-
-=item Tying to an already-opened filehandle
-
-=item Deferred Writing
-
-=over 4
-
-=item Autodeferring
-
-=back
-
-=item CONCURRENT ACCESS TO FILES
-
-=item CAVEATS
-
-=item SUBCLASSING
-
-=item WHAT ABOUT C<DB_File>?
-
-=item AUTHOR
-
-=item LICENSE
-
-=item WARRANTY
-
-=item THANKS
-
-=item TODO
-
-=back
-
-=head2 Tie::Handle - base class definitions for tied handles
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-TIEHANDLE classname, LIST, WRITE this, scalar, length, offset, PRINT this,
-LIST, PRINTF this, format, LIST, READ this, scalar, length, offset,
-READLINE this, GETC this, CLOSE this, OPEN this, filename, BINMODE this,
-EOF this, TELL this, SEEK this, offset, whence, DESTROY this
-
-=item MORE INFORMATION
-
-=item COMPATIBILITY
-
-=back
-
-=head2 Tie::Hash, Tie::StdHash, Tie::ExtraHash - base class definitions for
-tied hashes
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-TIEHASH classname, LIST, STORE this, key, value, FETCH this, key, FIRSTKEY
-this, NEXTKEY this, lastkey, EXISTS this, key, DELETE this, key, CLEAR
-this, SCALAR this
-
-=item Inheriting from B<Tie::StdHash>
-
-=item Inheriting from B<Tie::ExtraHash>
-
-=item C<SCALAR>, C<UNTIE> and C<DESTROY>
-
-=item MORE INFORMATION
-
-=back
-
-=head2 Tie::Hash::NamedCapture - Named regexp capture buffers
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-=back
-
-=head2 Tie::Memoize - add data to hash when needed
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item Inheriting from B<Tie::Memoize>
-
-=item EXAMPLE
-
-=item BUGS
-
-=item AUTHOR
-
-=back
-
-=head2 Tie::RefHash - use references as hash keys
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item EXAMPLE
-
-=item THREAD SUPPORT
-
-=item STORABLE SUPPORT
-
-=item RELIC SUPPORT
-
-=item LICENSE
-
-=item MAINTAINER
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Tie::Scalar, Tie::StdScalar - base class definitions for tied
-scalars
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-TIESCALAR classname, LIST, FETCH this, STORE this, value, DESTROY this
-
-=over 4
-
-=item Tie::Scalar vs Tie::StdScalar
-
-=back
-
-=item MORE INFORMATION
-
-=back
-
-=head2 Tie::StdHandle - base class definitions for tied handles
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=back
-
-=head2 Tie::SubstrHash - Fixed-table-size, fixed-key-length hashing
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CAVEATS
-
-=back
-
-=head2 Time::HiRes - High resolution alarm, sleep, gettimeofday, interval
-timers
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-gettimeofday (), usleep ( $useconds ), nanosleep ( $nanoseconds ), ualarm (
-$useconds [, $interval_useconds ] ), tv_interval, time (), sleep (
-$floating_seconds ), alarm ( $floating_seconds [,
-$interval_floating_seconds ] ), setitimer ( $which, $floating_seconds [,
-$interval_floating_seconds ] ), getitimer ( $which ), clock_gettime (
-$which ), clock_getres ( $which ), clock_nanosleep ( $which, $nanoseconds,
-$flags = 0), clock(), stat, stat FH, stat EXPR
-
-=item EXAMPLES
-
-=item C API
-
-=item DIAGNOSTICS
-
-=over 4
-
-=item useconds or interval more than ...
-
-=item negative time not invented yet
-
-=item internal error: useconds < 0 (unsigned ... signed ...)
-
-=item useconds or uinterval equal to or more than 1000000
-
-=item unimplemented in this platform
-
-=back
-
-=item CAVEATS
-
-=item SEE ALSO
-
-=item AUTHORS
-
-=item COPYRIGHT AND LICENSE
-
-=back
-
-=head2 Time::Local - efficiently compute time from local and GMT time
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item FUNCTIONS
-
-=over 4
-
-=item C<timelocal()> and C<timegm()>
-
-=item C<timelocal_nocheck()> and C<timegm_nocheck()>
-
-=item Year Value Interpretation
-
-=item Limits of time_t
-
-=item Ambiguous Local Times (DST)
-
-=item Non-Existent Local Times (DST)
-
-=item Negative Epoch Values
-
-=back
-
-=item IMPLEMENTATION
-
-=item BUGS
-
-=item SUPPORT
-
-=item COPYRIGHT
-
-=item AUTHOR
-
-=back
-
-=head2 Time::Piece - Object Oriented time objects
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item USAGE
-
-=over 4
-
-=item Local Locales
-
-=item Date Calculations
-
-=item Date Comparisons
-
-=item Date Parsing
-
-=item YYYY-MM-DDThh:mm:ss
-
-=item Week Number
-
-=item Global Overriding
-
-=back
-
-=item CAVEATS
-
-=over 4
-
-=item Setting $ENV{TZ} in Threads on Win32
-
-=item Use of epoch seconds
-
-=back
-
-=item AUTHOR
-
-=item License
-
-=item SEE ALSO
-
-=item BUGS
-
-=back
-
-=head2 Time::Seconds - a simple API to convert seconds to other date values
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item METHODS
-
-=item AUTHOR
-
-=item LICENSE
-
-=item Bugs
-
-=back
-
-=head2 Time::gmtime - by-name interface to Perl's built-in gmtime()
-function
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item NOTE
-
-=item AUTHOR
-
-=back
-
-=head2 Time::localtime - by-name interface to Perl's built-in localtime()
-function
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item NOTE
-
-=item AUTHOR
-
-=back
-
-=head2 Time::tm - internal object used by Time::gmtime and Time::localtime
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item AUTHOR
-
-=back
-
-=head2 UNIVERSAL - base class for ALL classes (blessed references)
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-C<< $obj->isa( TYPE ) >>, C<< CLASS->isa( TYPE ) >>, C<< eval { VAL->isa(
-TYPE ) } >>, C<TYPE>, C<$obj>, C<CLASS>, C<VAL>, C<< $obj->DOES( ROLE ) >>,
-C<< CLASS->DOES( ROLE ) >>, C<< $obj->can( METHOD ) >>, C<< CLASS->can(
-METHOD ) >>, C<< eval { VAL->can( METHOD ) } >>, C<VERSION ( [ REQUIRE ] )>
-
-=item WARNINGS
-
-=item EXPORTS
-
-=back
-
-=head2 Unicode::Collate - Unicode Collation Algorithm
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Constructor and Tailoring
-
-UCA_Version, alternate, backwards, entry, hangul_terminator, ignoreChar,
-ignoreName, ignore_level2, katakana_before_hiragana, level, normalization,
-overrideCJK, overrideHangul, preprocess, rearrange, rewrite, suppress,
-table, undefChar, undefName, upper_before_lower, variable
-
-=item Methods for Collation
-
-C<@sorted = $Collator-E<gt>sort(@not_sorted)>, C<$result =
-$Collator-E<gt>cmp($a, $b)>, C<$result = $Collator-E<gt>eq($a, $b)>,
-C<$result = $Collator-E<gt>ne($a, $b)>, C<$result = $Collator-E<gt>lt($a,
-$b)>, C<$result = $Collator-E<gt>le($a, $b)>, C<$result =
-$Collator-E<gt>gt($a, $b)>, C<$result = $Collator-E<gt>ge($a, $b)>,
-C<$sortKey = $Collator-E<gt>getSortKey($string)>, C<$sortKeyForm =
-$Collator-E<gt>viewSortKey($string)>
-
-=item Methods for Searching
-
-C<$position = $Collator-E<gt>index($string, $substring[, $position])>,
-C<($position, $length) = $Collator-E<gt>index($string, $substring[,
-$position])>, C<$match_ref = $Collator-E<gt>match($string, $substring)>,
-C<($match) = $Collator-E<gt>match($string, $substring)>, C<@match =
-$Collator-E<gt>gmatch($string, $substring)>, C<$count =
-$Collator-E<gt>subst($string, $substring, $replacement)>, C<$count =
-$Collator-E<gt>gsubst($string, $substring, $replacement)>
-
-=item Other Methods
-
-C<%old_tailoring = $Collator-E<gt>change(%new_tailoring)>,
-C<$modified_collator = $Collator-E<gt>change(%new_tailoring)>, C<$version =
-$Collator-E<gt>version()>, C<UCA_Version()>, C<Base_Unicode_Version()>
-
-=back
-
-=item EXPORT
-
-=item INSTALL
-
-=item CAVEATS
-
-Normalization, Conformance Test
-
-=item AUTHOR, COPYRIGHT AND LICENSE
-
-=item SEE ALSO
-
-Unicode Collation Algorithm - UTS #10, The Default Unicode Collation
-Element Table (DUCET), The conformance test for the UCA, Hangul Syllable
-Type, Unicode Normalization Forms - UAX #15, Unicode Locale Data Markup
-Language (LDML) - UTS #35
-
-=back
-
-=head2 Unicode::Collate::CJK::Big5 - weighting CJK Unified Ideographs
-for Unicode::Collate
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-CLDR - Unicode Common Locale Data Repository, Unicode Locale Data Markup
-Language (LDML) - UTS #35, L<Unicode::Collate>, L<Unicode::Collate::Locale>
-
-=back
-
-=head2 Unicode::Collate::CJK::GB2312 - weighting CJK Unified Ideographs
-for Unicode::Collate
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CAVEAT
-
-=item SEE ALSO
-
-CLDR - Unicode Common Locale Data Repository, Unicode Locale Data Markup
-Language (LDML) - UTS #35, L<Unicode::Collate>, L<Unicode::Collate::Locale>
-
-=back
-
-=head2 Unicode::Collate::CJK::JISX0208 - weighting JIS KANJI for
-Unicode::Collate
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-L<Unicode::Collate>, L<Unicode::Collate::Locale>
-
-=back
-
-=head2 Unicode::Collate::CJK::Korean - weighting CJK Unified Ideographs
-for Unicode::Collate
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-CLDR - Unicode Common Locale Data Repository, Unicode Locale Data Markup
-Language (LDML) - UTS #35, L<Unicode::Collate>, L<Unicode::Collate::Locale>
-
-=back
-
-=head2 Unicode::Collate::CJK::Pinyin - weighting CJK Unified Ideographs
-for Unicode::Collate
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item CAVEAT
-
-=item SEE ALSO
-
-CLDR - Unicode Common Locale Data Repository, Unicode Locale Data Markup
-Language (LDML) - UTS #35, L<Unicode::Collate>, L<Unicode::Collate::Locale>
-
-=back
-
-=head2 Unicode::Collate::CJK::Stroke - weighting CJK Unified Ideographs
-for Unicode::Collate
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item SEE ALSO
-
-CLDR - Unicode Common Locale Data Repository, Unicode Locale Data Markup
-Language (LDML) - UTS #35, L<Unicode::Collate>, L<Unicode::Collate::Locale>
-
-=back
-
-=head2 Unicode::Collate::Locale - Linguistic tailoring for DUCET via
-Unicode::Collate
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Constructor
-
-=item Methods
-
-C<$Collator-E<gt>getlocale>, C<$Collator-E<gt>locale_version>
-
-=item A list of tailorable locales
-
-=back
-
-=item INSTALL
-
-=item CAVEAT
-
-tailoring is not maximum
-
-=item AUTHOR
-
-=item SEE ALSO
-
-Unicode Collation Algorithm - UTS #10, The Default Unicode Collation
-Element Table (DUCET), Unicode Locale Data Markup Language (LDML) - UTS
-#35, CLDR - Unicode Common Locale Data Repository, L<Unicode::Collate>,
-L<Unicode::Normalize>
-
-=back
-
-=head2 Unicode::Normalize - Unicode Normalization Forms
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Normalization Forms
-
-C<$NFD_string = NFD($string)>, C<$NFC_string = NFC($string)>,
-C<$NFKD_string = NFKD($string)>, C<$NFKC_string = NFKC($string)>,
-C<$FCD_string = FCD($string)>, C<$FCC_string = FCC($string)>,
-C<$normalized_string = normalize($form_name, $string)>
-
-=item Decomposition and Composition
-
-C<$decomposed_string = decompose($string [, $useCompatMapping])>,
-C<$reordered_string = reorder($string)>, C<$composed_string =
-compose($string)>, C<($processed, $unprocessed) =
-splitOnLastStarter($normalized)>, C<$processed = normalize_partial($form,
-$unprocessed)>, C<$processed = NFD_partial($unprocessed)>, C<$processed =
-NFC_partial($unprocessed)>, C<$processed = NFKD_partial($unprocessed)>,
-C<$processed = NFKC_partial($unprocessed)>
-
-=item Quick Check
-
-C<$result = checkNFD($string)>, C<$result = checkNFC($string)>, C<$result =
-checkNFKD($string)>, C<$result = checkNFKC($string)>, C<$result =
-checkFCD($string)>, C<$result = checkFCC($string)>, C<$result =
-check($form_name, $string)>
-
-=item Character Data
-
-C<$canonical_decomposition = getCanon($code_point)>,
-C<$compatibility_decomposition = getCompat($code_point)>,
-C<$code_point_composite = getComposite($code_point_here,
-$code_point_next)>, C<$combining_class = getCombinClass($code_point)>,
-C<$may_be_composed_with_prev_char = isComp2nd($code_point)>,
-C<$is_exclusion = isExclusion($code_point)>, C<$is_singleton =
-isSingleton($code_point)>, C<$is_non_starter_decomposition =
-isNonStDecomp($code_point)>, C<$is_Full_Composition_Exclusion =
-isComp_Ex($code_point)>, C<$NFD_is_NO = isNFD_NO($code_point)>,
-C<$NFC_is_NO = isNFC_NO($code_point)>, C<$NFC_is_MAYBE =
-isNFC_MAYBE($code_point)>, C<$NFKD_is_NO = isNFKD_NO($code_point)>,
-C<$NFKC_is_NO = isNFKC_NO($code_point)>, C<$NFKC_is_MAYBE =
-isNFKC_MAYBE($code_point)>
-
-=back
-
-=item EXPORT
-
-=item CAVEATS
-
-Perl's version vs. Unicode version, Correction of decomposition mapping,
-Revised definition of canonical composition
-
-=item AUTHOR
-
-=item SEE ALSO
-
-http://www.unicode.org/reports/tr15/,
-http://www.unicode.org/Public/UNIDATA/CompositionExclusions.txt,
-http://www.unicode.org/Public/UNIDATA/DerivedNormalizationProps.txt,
-http://www.unicode.org/Public/UNIDATA/NormalizationCorrections.txt,
-http://www.unicode.org/review/pr-29.html, http://www.unicode.org/notes/tn5/
-
-=back
-
-=head2 Unicode::UCD - Unicode character database
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item code point argument
-
-=back
-
-=back
-
-=over 4
-
-=item B<charinfo()>
-
-B<code>, B<name>, B<category>, B<combining>, B<bidi>, B<decomposition>,
-B<decimal>, B<digit>, B<numeric>, B<mirrored>, B<unicode10>, B<comment>,
-B<upper>, B<lower>, B<title>, B<block>, B<script>
-
-=back
-
-=over 4
-
-=item B<charblock()>
-
-=back
-
-=over 4
-
-=item B<charscript()>
-
-=back
-
-=over 4
-
-=item B<charblocks()>
-
-=back
-
-=over 4
-
-=item B<charscripts()>
-
-=back
-
-=over 4
-
-=item B<charinrange()>
-
-=back
-
-=over 4
-
-=item B<general_categories()>
-
-=back
-
-=over 4
-
-=item B<bidi_types()>
-
-=back
-
-=over 4
-
-=item B<compexcl()>
-
-=back
-
-=over 4
-
-=item B<casefold()>
-
-B<code>, B<full>, B<simple>, B<mapping>, B<status>, B<*> If you use this
-C<I> mapping, B<*> If you exclude this C<I> mapping, B<turkic>
-
-=back
-
-=over 4
-
-=item B<casespec()>
-
-B<code>, B<lower>, B<title>, B<upper>, B<condition>
-
-=back
-
-=over 4
-
-=item B<namedseq()>
-
-=back
-
-=over 4
-
-=item B<num()>
-
-=back
-
-=over 4
-
-=item B<prop_aliases()>
-
-=back
-
-=over 4
-
-=item B<prop_value_aliases()>
-
-=back
-
-=over 4
-
-=item B<prop_invlist()>
-
-=back
-
-=over 4
-
-=item B<prop_invmap()>
-
-B<C<s>>, B<C<sl>>, C<correction>, C<control>, C<alternate>, C<figment>,
-C<abbreviation>, B<C<a>>, B<C<al>>, B<C<ae>>, B<C<ale>>, B<C<ar>>, B<C<n>>,
-B<C<ad>>
-
-=back
-
-=over 4
-
-=item Unicode::UCD::UnicodeVersion
-
-=back
-
-=over 4
-
-=item B<Blocks versus Scripts>
-
-=item B<Matching Scripts and Blocks>
-
-=item Old-style versus new-style block names
-
-=back
-
-=over 4
-
-=item BUGS
-
-=item AUTHOR
-
-=back
-
-=head2 User::grent - by-name interface to Perl's built-in getgr*()
-functions
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=item NOTE
-
-=item AUTHOR
-
-=back
-
-=head2 User::pwent - by-name interface to Perl's built-in getpw*()
-functions
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item System Specifics
-
-=back
-
-=item NOTE
-
-=item AUTHOR
-
-=item HISTORY
-
-March 18th, 2000
-
-=back
-
-=head2 Win32 - Interfaces to some Win32 API Functions
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Alphabetical Listing of Win32 Functions
-
-Win32::AbortSystemShutdown(MACHINE), Win32::BuildNumber(),
-Win32::CopyFile(FROM, TO, OVERWRITE), Win32::CreateDirectory(DIRECTORY),
-Win32::CreateFile(FILE), Win32::DomainName(),
-Win32::ExpandEnvironmentStrings(STRING), Win32::FormatMessage(ERRORCODE),
-Win32::FsType(), Win32::FreeLibrary(HANDLE),
-Win32::GetANSIPathName(FILENAME), Win32::GetArchName(),
-Win32::GetChipName(), Win32::GetCwd(), Win32::GetCurrentProcessId(),
-Win32::GetCurrentThreadId(), Win32::GetFileVersion(FILENAME),
-Win32::GetFolderPath(FOLDER [, CREATE]), Win32::GetFullPathName(FILENAME),
-Win32::GetLastError(), Win32::GetLongPathName(PATHNAME),
-Win32::GetNextAvailDrive(), Win32::GetOSDisplayName(), Win32::GetOSName(),
-Win32::GetOSVersion(), Win32::GetShortPathName(PATHNAME),
-Win32::GetSystemMetrics(INDEX), Win32::GetProcAddress(INSTANCE, PROCNAME),
-Win32::GetProductInfo(OSMAJOR, OSMINOR, SPMAJOR, SPMINOR),
-Win32::GetTickCount(), Win32::GuidGen(), Win32::InitiateSystemShutdown,
-Win32::IsAdminUser(), Win32::IsWinNT(), Win32::IsWin95(),
-Win32::LoadLibrary(LIBNAME), Win32::LoginName(),
-Win32::LookupAccountName(SYSTEM, ACCOUNT, DOMAIN, SID, SIDTYPE),
-Win32::LookupAccountSID(SYSTEM, SID, ACCOUNT, DOMAIN, SIDTYPE),
-Win32::MsgBox(MESSAGE [, FLAGS [, TITLE]]), Win32::NodeName(),
-Win32::OutputDebugString(STRING), Win32::RegisterServer(LIBRARYNAME),
-Win32::SetChildShowWindow(SHOWWINDOW), Win32::SetCwd(NEWDIRECTORY),
-Win32::SetLastError(ERROR), Win32::Sleep(TIME), Win32::Spawn(COMMAND, ARGS,
-PID), Win32::UnregisterServer(LIBRARYNAME)
-
-=back
-
-=back
-
-=head2 Win32API::File - Low-level access to Win32 system API calls for
-files/dirs.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Object Oriented/Tied Handle Interface
-
-=item Exports
-
-C<":Func">, attrLetsToBits, C<$uBits= attrLetsToBits( $sAttributeLetters
-)>, C<"a">, C<"c">, C<"h">, C<"o">, C<"r">, C<"s">, C<"t">, createFile,
-C<$hObject= createFile( $sPath )>, C<$hObject= createFile( $sPath,
-$rvhvOptions )>, C<$hObject= createFile( $sPath, $svAccess )>, C<$hObject=
-createFile( $sPath, $svAccess, $rvhvOptions )>, C<$hObject= createFile(
-$sPath, $svAccess, $svShare )>, C<$hObject= createFile( $sPath, $svAccess,
-$svShare, $rvhvOptions )>, C<"q">, C<"r">, C<"w">, C<"k">, C<"t">, C<"n">,
-C<"c">, C<"e">, C<"kc">, C<"ke">, C<"tc">, C<"te">, C<"nc">, C<"ne">, Flags
-=> $uFlags, Attributes => $sAttributes, Security => $pSecurityAttributes,
-Model => $hModelFile, Access => $sAccess, Access => $uAccess, Create =>
-$sCreate, Create => $uCreate, Share => $sShare, Share => $uShare,
-getLogicalDrives, C<@roots= getLogicalDrives()>, CloseHandle,
-C<CloseHandle( $hObject )>, CopyFile, C<CopyFile( $sOldFileName,
-$sNewFileName, $bFailIfExists )>, CreateFile, C<$hObject= CreateFile(
-$sPath, $uAccess, $uShare, $pSecAttr, $uCreate, $uFlags, $hModel )>,
-C<"//./PhysicalDrive0">, C<"//./C:">, C<"//./A:">, C<"//./PIPE/PipeName">,
-DefineDosDevice, C<DefineDosDevice( $uFlags, $sDosDeviceName, $sTargetPath
-)>, C<DDD_RAW_TARGET_PATH>, C<DDD_REMOVE_DEFINITION>,
-C<DDD_EXACT_MATCH_ON_REMOVE>, DeleteFile, C<DeleteFile( $sFileName )>,
-DeviceIoControl, C<DeviceIoControl( $hDevice, $uIoControlCode, $pInBuf,
-$lInBuf, $opOutBuf, $lOutBuf, $olRetBytes, $pOverlapped )>, FdGetOsFHandle,
-C<$hNativeHandle= FdGetOsFHandle( $ivFd )>, fileConstant, C<$value=
-fileConstant( $sConstantName )>, fileLastError, C<$svError=
-fileLastError();>, C<fileLastError( $uError );>, GetDriveType,
-C<$uDriveType= GetDriveType( $sRootPath )>, C<DRIVE_UNKNOWN>,
-C<DRIVE_NO_ROOT_DIR>, C<DRIVE_REMOVABLE>, C<DRIVE_FIXED>, C<DRIVE_REMOTE>,
-C<DRIVE_CDROM>, C<DRIVE_RAMDISK>, GetFileAttributes, C<$uAttrs =
-GetFileAttributes( $sPath )>, C<FILE_ATTRIBUTE_ARCHIVE>,
-C<FILE_ATTRIBUTE_COMPRESSED>, C<FILE_ATTRIBUTE_DEVICE>,
-C<FILE_ATTRIBUTE_DIRECTORY>, C<FILE_ATTRIBUTE_ENCRYPTED>,
-C<FILE_ATTRIBUTE_HIDDEN>, C<FILE_ATTRIBUTE_NORMAL>,
-C<FILE_ATTRIBUTE_NOT_CONTENT_INDEXED>, C<FILE_ATTRIBUTE_OFFLINE>,
-C<FILE_ATTRIBUTE_READONLY>, C<FILE_ATTRIBUTE_REPARSE_POINT>,
-C<FILE_ATTRIBUTE_SPARSE_FILE>, C<FILE_ATTRIBUTE_SYSTEM>,
-C<FILE_ATTRIBUTE_TEMPORARY>, GetFileType, C<$uFileType= GetFileType( $hFile
-)>, C<FILE_TYPE_UNKNOWN>, C<FILE_TYPE_DISK>, C<FILE_TYPE_CHAR>,
-C<FILE_TYPE_PIPE>, getFileSize, C<$size= getFileSize( $hFile )>,
-GetFileSize, C<$iSizeLow= GetFileSize($win32Handle, $iSizeHigh)>,
-GetOverlappedResult, C<$bRetval= GetOverlappedResult( $win32Handle,
-$pOverlapped, $numBytesTransferred, $bWait )>, GetLogicalDrives,
-C<$uDriveBits= GetLogicalDrives()>, GetLogicalDriveStrings, C<$olOutLength=
-GetLogicalDriveStrings( $lBufSize, $osBuffer )>, GetHandleInformation,
-C<GetHandleInformation( $hObject, $ouFlags )>, GetOsFHandle,
-C<$hNativeHandle= GetOsFHandle( FILE )>, GetVolumeInformation,
-C<GetVolumeInformation( $sRootPath, $osVolName, $lVolName, $ouSerialNum,
-$ouMaxNameLen, $ouFsFlags, $osFsType, $lFsType )>, C<FS_CASE_IS_PRESERVED>,
-C<FS_CASE_SENSITIVE>, C<FS_UNICODE_STORED_ON_DISK>, C<FS_PERSISTENT_ACLS>,
-C<FS_FILE_COMPRESSION>, C<FS_VOL_IS_COMPRESSED>, IsRecognizedPartition,
-C<IsRecognizedPartition( $ivPartitionType )>, IsContainerPartition,
-C<IsContainerPartition( $ivPartitionType )>, MoveFile, C<MoveFile(
-$sOldName, $sNewName )>, MoveFileEx, C<MoveFileEx( $sOldName, $sNewName,
-$uFlags )>, C<MOVEFILE_REPLACE_EXISTING>, C<MOVEFILE_COPY_ALLOWED>,
-C<MOVEFILE_DELAY_UNTIL_REBOOT>, C<MOVEFILE_WRITE_THROUGH>, OsFHandleOpen,
-C<OsFHandleOpen( FILE, $hNativeHandle, $sMode )>, OsFHandleOpenFd, C<$ivFD=
-OsFHandleOpenFd( $hNativeHandle, $uMode )>, QueryDosDevice, C<$olTargetLen=
-QueryDosDevice( $sDosDeviceName, $osTargetPath, $lTargetBuf )>, ReadFile,
-C<ReadFile( $hFile, $opBuffer, $lBytes, $olBytesRead, $pOverlapped )>,
-SetErrorMode, C<$uOldMode= SetErrorMode( $uNewMode )>,
-C<SEM_FAILCRITICALERRORS>, C<SEM_NOALIGNMENTFAULTEXCEPT>,
-C<SEM_NOGPFAULTERRORBOX>, C<SEM_NOOPENFILEERRORBOX>, setFilePointer,
-C<$uNewPos = setFilePointer( $hFile, $ivOffset, $uFromWhere )>,
-SetFilePointer, C<$uNewPos = SetFilePointer( $hFile, $ivOffset,
-$ioivOffsetHigh, $uFromWhere )>, SetHandleInformation,
-C<SetHandleInformation( $hObject, $uMask, $uFlags )>, WriteFile,
-C<WriteFile( $hFile, $pBuffer, $lBytes, $ouBytesWritten, $pOverlapped )>,
-C<":FuncA">, C<":FuncW">, CopyFileW, C<CopyFileW( $swOldFileName,
-$swNewFileName, $bFailIfExists )>, CreateFileW, C<$hObject= CreateFileW(
-$swPath, $uAccess, $uShare, $pSecAttr, $uCreate, $uFlags, $hModel )>,
-DefineDosDeviceW, C<DefineDosDeviceW( $uFlags, $swDosDeviceName,
-$swTargetPath )>, DeleteFileW, C<DeleteFileW( $swFileName )>,
-GetDriveTypeW, C<$uDriveType= GetDriveTypeW( $swRootPath )>,
-GetFileAttributesW, C<$uAttrs= GetFileAttributesW( $swPath )>,
-GetLogicalDriveStringsW, C<$olwOutLength= GetLogicalDriveStringsW(
-$lwBufSize, $oswBuffer )>, GetVolumeInformationW, C<GetVolumeInformationW(
-$swRootPath, $oswVolName, $lwVolName, $ouSerialNum, $ouMaxNameLen,
-$ouFsFlags, $oswFsType, $lwFsType )>, MoveFileW, C<MoveFileW( $swOldName,
-$swNewName )>, MoveFileExW, C<MoveFileExW( $swOldName, $swNewName, $uFlags
-)>, QueryDosDeviceW, C<$olwTargetLen= QueryDosDeviceW( $swDeviceName,
-$oswTargetPath, $lwTargetBuf )>, C<":Misc">, C<":DDD_">, C<":DRIVE_">,
-C<":FILE_">, C<":FILE_ATTRIBUTE_">, C<":FILE_FLAG_">, C<":FILE_SHARE_">,
-C<":FILE_TYPE_">, C<":FS_">, C<":HANDLE_FLAG_">, HANDLE_FLAG_INHERIT,
-HANDLE_FLAG_PROTECT_FROM_CLOSE, C<":IOCTL_STORAGE_">,
-C<IOCTL_STORAGE_CHECK_VERIFY>, C<IOCTL_STORAGE_MEDIA_REMOVAL>,
-C<IOCTL_STORAGE_EJECT_MEDIA>, C<IOCTL_STORAGE_LOAD_MEDIA>,
-C<IOCTL_STORAGE_RESERVE>, C<IOCTL_STORAGE_RELEASE>,
-C<IOCTL_STORAGE_FIND_NEW_DEVICES>, C<IOCTL_STORAGE_GET_MEDIA_TYPES>,
-C<$ucCylsLow[$i]>, C<$ivcCylsHigh[$i]>, C<$uMediaType[$i]>,
-C<$uTracksPerCyl[$i]>, C<$uSectsPerTrack[$i]>, C<$uBytesPerSect[$i]>,
-C<":IOCTL_DISK_">, C<IOCTL_DISK_GET_DRIVE_GEOMETRY>, C<$ucCylsLow>,
-C<$ivcCylsHigh>, C<$uMediaType>, C<$uTracksPerCyl>, C<$uSectsPerTrack>,
-C<$uBytesPerSect>, C<IOCTL_DISK_GET_PARTITION_INFO>, C<$uStartLow> and
-C<$ivStartHigh>, C<$ucHiddenSects>, C<$uPartitionSeqNumber>,
-C<$uPartitionType>, C<$bActive>, C<$bRecognized>, C<$bToRewrite>,
-C<IOCTL_DISK_SET_PARTITION_INFO>, C<IOCTL_DISK_GET_DRIVE_LAYOUT>,
-C<$cPartitions>, C<$uDiskSignature>, C<IOCTL_DISK_GET_MEDIA_TYPES>,
-C<IOCTL_DISK_SET_DRIVE_LAYOUT>, C<IOCTL_DISK_VERIFY>, C<$uStartOffsetLow>
-and C<$ivStartOffsetHigh>, C<$uLength>, C<IOCTL_DISK_FORMAT_TRACKS>,
-C<IOCTL_DISK_REASSIGN_BLOCKS>, C<IOCTL_DISK_PERFORMANCE>,
-C<IOCTL_DISK_IS_WRITABLE>, C<IOCTL_DISK_LOGGING>, DISK_LOGGING_START,
-DISK_LOGGING_STOP, DISK_LOGGING_DUMP, DISK_LOGGING_BINNING,
-C<IOCTL_DISK_FORMAT_TRACKS_EX>, C<IOCTL_DISK_HISTOGRAM_STRUCTURE>,
-C<IOCTL_DISK_HISTOGRAM_DATA>, C<IOCTL_DISK_HISTOGRAM_RESET>,
-C<IOCTL_DISK_REQUEST_STRUCTURE>, C<IOCTL_DISK_REQUEST_DATA>, C<":FSCTL_">,
-C<FSCTL_SET_REPARSE_POINT>, C<FSCTL_GET_REPARSE_POINT>,
-C<FSCTL_DELETE_REPARSE_POINT>, C<":GENERIC_">, C<":MEDIA_TYPE">,
-C<Unknown>, C<F5_1Pt2_512>, C<F3_1Pt44_512>, C<F3_2Pt88_512>,
-C<F3_20Pt8_512>, C<F3_720_512>, C<F5_360_512>, C<F5_320_512>,
-C<F5_320_1024>, C<F5_180_512>, C<F5_160_512>, C<RemovableMedia>,
-C<FixedMedia>, C<F3_120M_512>, C<":MOVEFILE_">, C<":SECURITY_">,
-C<":SEM_">, C<":PARTITION_">, C<":ALL">
-
-=back
-
-=item BUGS
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 Win32CORE - Win32 CORE function stubs
-
-=over 4
-
-=item DESCRIPTION
-
-=item HISTORY
-
-=back
-
-=head2 XSLoader - Dynamically load C libraries into Perl code
-
-=over 4
-
-=item VERSION
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Migration from C<DynaLoader>
-
-=item Backward compatible boilerplate
-
-=back
-
-=item Order of initialization: early load()
-
-=over 4
-
-=item The most hairy case
-
-=back
-
-=item DIAGNOSTICS
-
-C<Can't find '%s' symbol in %s>, C<Can't load '%s' for module %s: %s>,
-C<Undefined symbols present after loading %s: %s>
-
-=item LIMITATIONS
-
-=item KNOWN BUGS
-
-=item BUGS
-
-=item SEE ALSO
-
-=item AUTHORS
-
-=item COPYRIGHT & LICENSE
-
-=back
-
-=head1 AUXILIARY DOCUMENTATION
-
-Here should be listed all the extra programs' documentation, but they
-don't all have manual pages yet:
-
-=over 4
-
-=item a2p
-
-=item c2ph
-
-=item h2ph
-
-=item h2xs
-
-=item perlbug
-
-=item pl2pm
-
-=item pod2html
-
-=item pod2man
-
-=item s2p
-
-=item splain
-
-=item xsubpp
-
-=back
-
-=head1 AUTHOR
-
-Larry Wall <F<larry@wall.org>>, with the help of oodles
-of other folks.
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perltodo.pod b/Master/tlpkg/tlperl/lib/pods/perltodo.pod
deleted file mode 100644
index 524a501681f..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perltodo.pod
+++ /dev/null
@@ -1,10 +0,0 @@
-=head1 NAME
-
-perltodo - Perl TO-DO List
-
-=head1 DESCRIPTION
-
-We no longer install the Perl 5 to-do list as a manpage, as installing
-snapshot that becomes increasingly out of date isn't that useful to anyone.
-The current Perl 5 to-do list is maintained in the git repository, and can
-be viewed at L<http://perl5.git.perl.org/perl.git/blob/HEAD:/Porting/todo.pod>
diff --git a/Master/tlpkg/tlperl/lib/pods/perltooc.pod b/Master/tlpkg/tlperl/lib/pods/perltooc.pod
deleted file mode 100644
index 35163255300..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perltooc.pod
+++ /dev/null
@@ -1,12 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perltooc - This document has been deleted
-
-=head1 DESCRIPTION
-
-For information on OO programming with Perl, please see L<perlootut>
-and L<perlobj>.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perltoot.pod b/Master/tlpkg/tlperl/lib/pods/perltoot.pod
deleted file mode 100644
index c89629036c3..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perltoot.pod
+++ /dev/null
@@ -1,12 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-perltoot - This document has been deleted
-
-=head1 DESCRIPTION
-
-For information on OO programming with Perl, please see L<perlootut>
-and L<perlobj>.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perltrap.pod b/Master/tlpkg/tlperl/lib/pods/perltrap.pod
deleted file mode 100644
index e4fbb23a536..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perltrap.pod
+++ /dev/null
@@ -1,1591 +0,0 @@
-=head1 NAME
-
-perltrap - Perl traps for the unwary
-
-=head1 DESCRIPTION
-
-The biggest trap of all is forgetting to C<use warnings> or use the B<-w>
-switch; see L<perllexwarn> and L<perlrun>. The second biggest trap is not
-making your entire program runnable under C<use strict>. The third biggest
-trap is not reading the list of changes in this version of Perl; see
-L<perldelta>.
-
-=head2 Awk Traps
-
-Accustomed B<awk> users should take special note of the following:
-
-=over 4
-
-=item *
-
-A Perl program executes only once, not once for each input line. You can
-do an implicit loop with C<-n> or C<-p>.
-
-=item *
-
-The English module, loaded via
-
- use English;
-
-allows you to refer to special variables (like C<$/>) with names (like
-$RS), as though they were in B<awk>; see L<perlvar> for details.
-
-=item *
-
-Semicolons are required after all simple statements in Perl (except
-at the end of a block). Newline is not a statement delimiter.
-
-=item *
-
-Curly brackets are required on C<if>s and C<while>s.
-
-=item *
-
-Variables begin with "$", "@" or "%" in Perl.
-
-=item *
-
-Arrays index from 0. Likewise string positions in substr() and
-index().
-
-=item *
-
-You have to decide whether your array has numeric or string indices.
-
-=item *
-
-Hash values do not spring into existence upon mere reference.
-
-=item *
-
-You have to decide whether you want to use string or numeric
-comparisons.
-
-=item *
-
-Reading an input line does not split it for you. You get to split it
-to an array yourself. And the split() operator has different
-arguments than B<awk>'s.
-
-=item *
-
-The current input line is normally in $_, not $0. It generally does
-not have the newline stripped. ($0 is the name of the program
-executed.) See L<perlvar>.
-
-=item *
-
-$<I<digit>> does not refer to fields--it refers to substrings matched
-by the last match pattern.
-
-=item *
-
-The print() statement does not add field and record separators unless
-you set C<$,> and C<$\>. You can set $OFS and $ORS if you're using
-the English module.
-
-=item *
-
-You must open your files before you print to them.
-
-=item *
-
-The range operator is "..", not comma. The comma operator works as in
-C.
-
-=item *
-
-The match operator is "=~", not "~". ("~" is the one's complement
-operator, as in C.)
-
-=item *
-
-The exponentiation operator is "**", not "^". "^" is the XOR
-operator, as in C. (You know, one could get the feeling that B<awk> is
-basically incompatible with C.)
-
-=item *
-
-The concatenation operator is ".", not the null string. (Using the
-null string would render C</pat/ /pat/> unparsable, because the third slash
-would be interpreted as a division operator--the tokenizer is in fact
-slightly context sensitive for operators like "/", "?", and ">".
-And in fact, "." itself can be the beginning of a number.)
-
-=item *
-
-The C<next>, C<exit>, and C<continue> keywords work differently.
-
-=item *
-
-
-The following variables work differently:
-
- Awk Perl
- ARGC scalar @ARGV (compare with $#ARGV)
- ARGV[0] $0
- FILENAME $ARGV
- FNR $. - something
- FS (whatever you like)
- NF $#Fld, or some such
- NR $.
- OFMT $#
- OFS $,
- ORS $\
- RLENGTH length($&)
- RS $/
- RSTART length($`)
- SUBSEP $;
-
-=item *
-
-You cannot set $RS to a pattern, only a string.
-
-=item *
-
-When in doubt, run the B<awk> construct through B<a2p> and see what it
-gives you.
-
-=back
-
-=head2 C/C++ Traps
-
-Cerebral C and C++ programmers should take note of the following:
-
-=over 4
-
-=item *
-
-Curly brackets are required on C<if>'s and C<while>'s.
-
-=item *
-
-You must use C<elsif> rather than C<else if>.
-
-=item *
-
-The C<break> and C<continue> keywords from C become in Perl C<last>
-and C<next>, respectively. Unlike in C, these do I<not> work within a
-C<do { } while> construct. See L<perlsyn/"Loop Control">.
-
-=item *
-
-The switch statement is called C<given/when> and only available in
-perl 5.10 or newer. See L<perlsyn/"Switch Statements">.
-
-=item *
-
-Variables begin with "$", "@" or "%" in Perl.
-
-=item *
-
-Comments begin with "#", not "/*" or "//". Perl may interpret C/C++
-comments as division operators, unterminated regular expressions or
-the defined-or operator.
-
-=item *
-
-You can't take the address of anything, although a similar operator
-in Perl is the backslash, which creates a reference.
-
-=item *
-
-C<ARGV> must be capitalized. C<$ARGV[0]> is C's C<argv[1]>, and C<argv[0]>
-ends up in C<$0>.
-
-=item *
-
-System calls such as link(), unlink(), rename(), etc. return nonzero for
-success, not 0. (system(), however, returns zero for success.)
-
-=item *
-
-Signal handlers deal with signal names, not numbers. Use C<kill -l>
-to find their names on your system.
-
-=back
-
-=head2 Sed Traps
-
-Seasoned B<sed> programmers should take note of the following:
-
-=over 4
-
-=item *
-
-A Perl program executes only once, not once for each input line. You can
-do an implicit loop with C<-n> or C<-p>.
-
-=item *
-
-Backreferences in substitutions use "$" rather than "\".
-
-=item *
-
-The pattern matching metacharacters "(", ")", and "|" do not have backslashes
-in front.
-
-=item *
-
-The range operator is C<...>, rather than comma.
-
-=back
-
-=head2 Shell Traps
-
-Sharp shell programmers should take note of the following:
-
-=over 4
-
-=item *
-
-The backtick operator does variable interpolation without regard to
-the presence of single quotes in the command.
-
-=item *
-
-The backtick operator does no translation of the return value, unlike B<csh>.
-
-=item *
-
-Shells (especially B<csh>) do several levels of substitution on each
-command line. Perl does substitution in only certain constructs
-such as double quotes, backticks, angle brackets, and search patterns.
-
-=item *
-
-Shells interpret scripts a little bit at a time. Perl compiles the
-entire program before executing it (except for C<BEGIN> blocks, which
-execute at compile time).
-
-=item *
-
-The arguments are available via @ARGV, not $1, $2, etc.
-
-=item *
-
-The environment is not automatically made available as separate scalar
-variables.
-
-=item *
-
-The shell's C<test> uses "=", "!=", "<" etc for string comparisons and "-eq",
-"-ne", "-lt" etc for numeric comparisons. This is the reverse of Perl, which
-uses C<eq>, C<ne>, C<lt> for string comparisons, and C<==>, C<!=> C<< < >> etc
-for numeric comparisons.
-
-=back
-
-=head2 Perl Traps
-
-Practicing Perl Programmers should take note of the following:
-
-=over 4
-
-=item *
-
-Remember that many operations behave differently in a list
-context than they do in a scalar one. See L<perldata> for details.
-
-=item *
-
-Avoid barewords if you can, especially all lowercase ones.
-You can't tell by just looking at it whether a bareword is
-a function or a string. By using quotes on strings and
-parentheses on function calls, you won't ever get them confused.
-
-=item *
-
-You cannot discern from mere inspection which builtins
-are unary operators (like chop() and chdir())
-and which are list operators (like print() and unlink()).
-(Unless prototyped, user-defined subroutines can B<only> be list
-operators, never unary ones.) See L<perlop> and L<perlsub>.
-
-=item *
-
-People have a hard time remembering that some functions
-default to $_, or @ARGV, or whatever, but that others which
-you might expect to do not.
-
-=item *
-
-The <FH> construct is not the name of the filehandle, it is a readline
-operation on that handle. The data read is assigned to $_ only if the
-file read is the sole condition in a while loop:
-
- while (<FH>) { }
- while (defined($_ = <FH>)) { }..
- <FH>; # data discarded!
-
-=item *
-
-Remember not to use C<=> when you need C<=~>;
-these two constructs are quite different:
-
- $x = /foo/;
- $x =~ /foo/;
-
-=item *
-
-The C<do {}> construct isn't a real loop that you can use
-loop control on.
-
-=item *
-
-Use C<my()> for local variables whenever you can get away with
-it (but see L<perlform> for where you can't).
-Using C<local()> actually gives a local value to a global
-variable, which leaves you open to unforeseen side-effects
-of dynamic scoping.
-
-=item *
-
-If you localize an exported variable in a module, its exported value will
-not change. The local name becomes an alias to a new value but the
-external name is still an alias for the original.
-
-=back
-
-=head2 Perl4 to Perl5 Traps
-
-Practicing Perl4 Programmers should take note of the following
-Perl4-to-Perl5 specific traps.
-
-They're crudely ordered according to the following list:
-
-=over 4
-
-=item Discontinuance, Deprecation, and BugFix traps
-
-Anything that's been fixed as a perl4 bug, removed as a perl4 feature
-or deprecated as a perl4 feature with the intent to encourage usage of
-some other perl5 feature.
-
-=item Parsing Traps
-
-Traps that appear to stem from the new parser.
-
-=item Numerical Traps
-
-Traps having to do with numerical or mathematical operators.
-
-=item General data type traps
-
-Traps involving perl standard data types.
-
-=item Context Traps - scalar, list contexts
-
-Traps related to context within lists, scalar statements/declarations.
-
-=item Precedence Traps
-
-Traps related to the precedence of parsing, evaluation, and execution of
-code.
-
-=item General Regular Expression Traps using s///, etc.
-
-Traps related to the use of pattern matching.
-
-=item Subroutine, Signal, Sorting Traps
-
-Traps related to the use of signals and signal handlers, general subroutines,
-and sorting, along with sorting subroutines.
-
-=item OS Traps
-
-OS-specific traps.
-
-=item DBM Traps
-
-Traps specific to the use of C<dbmopen()>, and specific dbm implementations.
-
-=item Unclassified Traps
-
-Everything else.
-
-=back
-
-If you find an example of a conversion trap that is not listed here,
-please submit it to <F<perlbug@perl.org>> for inclusion.
-Also note that at least some of these can be caught with the
-C<use warnings> pragma or the B<-w> switch.
-
-=head2 Discontinuance, Deprecation, and BugFix traps
-
-Anything that has been discontinued, deprecated, or fixed as
-a bug from perl4.
-
-=over 4
-
-=item * Symbols starting with "_" no longer forced into main
-
-Symbols starting with "_" are no longer forced into package main, except
-for C<$_> itself (and C<@_>, etc.).
-
- package test;
- $_legacy = 1;
-
- package main;
- print "\$_legacy is ",$_legacy,"\n";
-
- # perl4 prints: $_legacy is 1
- # perl5 prints: $_legacy is
-
-=item * Double-colon valid package separator in variable name
-
-Double-colon is now a valid package separator in a variable name. Thus these
-behave differently in perl4 vs. perl5, because the packages don't exist.
-
- $a=1;$b=2;$c=3;$var=4;
- print "$a::$b::$c ";
- print "$var::abc::xyz\n";
-
- # perl4 prints: 1::2::3 4::abc::xyz
- # perl5 prints: 3
-
-Given that C<::> is now the preferred package delimiter, it is debatable
-whether this should be classed as a bug or not.
-(The older package delimiter, ' ,is used here)
-
- $x = 10;
- print "x=${'x}\n";
-
- # perl4 prints: x=10
- # perl5 prints: Can't find string terminator "'" anywhere before EOF
-
-You can avoid this problem, and remain compatible with perl4, if you
-always explicitly include the package name:
-
- $x = 10;
- print "x=${main'x}\n";
-
-Also see precedence traps, for parsing C<$:>.
-
-=item * 2nd and 3rd args to C<splice()> are now in scalar context
-
-The second and third arguments of C<splice()> are now evaluated in scalar
-context (as the Camel says) rather than list context.
-
- sub sub1{return(0,2) } # return a 2-element list
- sub sub2{ return(1,2,3)} # return a 3-element list
- @a1 = ("a","b","c","d","e");
- @a2 = splice(@a1,&sub1,&sub2);
- print join(' ',@a2),"\n";
-
- # perl4 prints: a b
- # perl5 prints: c d e
-
-=item * Can't do C<goto> into a block that is optimized away
-
-You can't do a C<goto> into a block that is optimized away. Darn.
-
- goto marker1;
-
- for(1){
- marker1:
- print "Here I is!\n";
- }
-
- # perl4 prints: Here I is!
- # perl5 errors: Can't "goto" into the middle of a foreach loop
-
-=item * Can't use whitespace as variable name or quote delimiter
-
-It is no longer syntactically legal to use whitespace as the name
-of a variable, or as a delimiter for any kind of quote construct.
-Double darn.
-
- $a = ("foo bar");
- $b = q baz ;
- print "a is $a, b is $b\n";
-
- # perl4 prints: a is foo bar, b is baz
- # perl5 errors: Bareword found where operator expected
-
-=item * C<while/if BLOCK BLOCK> gone
-
-The archaic while/if BLOCK BLOCK syntax is no longer supported.
-
- if { 1 } {
- print "True!";
- }
- else {
- print "False!";
- }
-
- # perl4 prints: True!
- # perl5 errors: syntax error at test.pl line 1, near "if {"
-
-=item * C<**> binds tighter than unary minus
-
-The C<**> operator now binds more tightly than unary minus.
-It was documented to work this way before, but didn't.
-
- print -4**2,"\n";
-
- # perl4 prints: 16
- # perl5 prints: -16
-
-=item * C<foreach> changed when iterating over a list
-
-The meaning of C<foreach{}> has changed slightly when it is iterating over a
-list which is not an array. This used to assign the list to a
-temporary array, but no longer does so (for efficiency). This means
-that you'll now be iterating over the actual values, not over copies of
-the values. Modifications to the loop variable can change the original
-values.
-
- @list = ('ab','abc','bcd','def');
- foreach $var (grep(/ab/,@list)){
- $var = 1;
- }
- print (join(':',@list));
-
- # perl4 prints: ab:abc:bcd:def
- # perl5 prints: 1:1:bcd:def
-
-To retain Perl4 semantics you need to assign your list
-explicitly to a temporary array and then iterate over that. For
-example, you might need to change
-
- foreach $var (grep(/ab/,@list)){
-
-to
-
- foreach $var (@tmp = grep(/ab/,@list)){
-
-Otherwise changing $var will clobber the values of @list. (This most often
-happens when you use C<$_> for the loop variable, and call subroutines in
-the loop that don't properly localize C<$_>.)
-
-=item * C<split> with no args behavior changed
-
-C<split> with no arguments now behaves like C<split ' '> (which doesn't
-return an initial null field if $_ starts with whitespace), it used to
-behave like C<split /\s+/> (which does).
-
- $_ = ' hi mom';
- print join(':', split);
-
- # perl4 prints: :hi:mom
- # perl5 prints: hi:mom
-
-=item * B<-e> behavior fixed
-
-Perl 4 would ignore any text which was attached to an B<-e> switch,
-always taking the code snippet from the following arg. Additionally, it
-would silently accept an B<-e> switch without a following arg. Both of
-these behaviors have been fixed.
-
- perl -e'print "attached to -e"' 'print "separate arg"'
-
- # perl4 prints: separate arg
- # perl5 prints: attached to -e
-
- perl -e
-
- # perl4 prints:
- # perl5 dies: No code specified for -e.
-
-=item * C<push> returns number of elements in resulting list
-
-In Perl 4 the return value of C<push> was undocumented, but it was
-actually the last value being pushed onto the target list. In Perl 5
-the return value of C<push> is documented, but has changed, it is the
-number of elements in the resulting list.
-
- @x = ('existing');
- print push(@x, 'first new', 'second new');
-
- # perl4 prints: second new
- # perl5 prints: 3
-
-=item * Some error messages differ
-
-Some error messages will be different.
-
-=item * C<split()> honors subroutine args
-
-In Perl 4, if in list context the delimiters to the first argument of
-C<split()> were C<??>, the result would be placed in C<@_> as well as
-being returned. Perl 5 has more respect for your subroutine arguments.
-
-=item * Bugs removed
-
-Some bugs may have been inadvertently removed. :-)
-
-=back
-
-=head2 Parsing Traps
-
-Perl4-to-Perl5 traps from having to do with parsing.
-
-=over 4
-
-=item * Space between . and = triggers syntax error
-
-Note the space between . and =
-
- $string . = "more string";
- print $string;
-
- # perl4 prints: more string
- # perl5 prints: syntax error at - line 1, near ". ="
-
-=item * Better parsing in perl 5
-
-Better parsing in perl 5
-
- sub foo {}
- &foo
- print("hello, world\n");
-
- # perl4 prints: hello, world
- # perl5 prints: syntax error
-
-=item * Function parsing
-
-"if it looks like a function, it is a function" rule.
-
- print
- ($foo == 1) ? "is one\n" : "is zero\n";
-
- # perl4 prints: is zero
- # perl5 warns: "Useless use of a constant in void context" if using -w
-
-=item * String interpolation of C<$#array> differs
-
-String interpolation of the C<$#array> construct differs when braces
-are to used around the name.
-
- @a = (1..3);
- print "${#a}";
-
- # perl4 prints: 2
- # perl5 fails with syntax error
-
- @a = (1..3);
- print "$#{a}";
-
- # perl4 prints: {a}
- # perl5 prints: 2
-
-=item * Perl guesses on C<map>, C<grep> followed by C<{> if it starts BLOCK or hash ref
-
-When perl sees C<map {> (or C<grep {>), it has to guess whether the C<{>
-starts a BLOCK or a hash reference. If it guesses wrong, it will report
-a syntax error near the C<}> and the missing (or unexpected) comma.
-
-Use unary C<+> before C<{> on a hash reference, and unary C<+> applied
-to the first thing in a BLOCK (after C<{>), for perl to guess right all
-the time. (See L<perlfunc/map>.)
-
-=back
-
-=head2 Numerical Traps
-
-Perl4-to-Perl5 traps having to do with numerical operators,
-operands, or output from same.
-
-=over 5
-
-=item * Formatted output and significant digits
-
-Formatted output and significant digits. In general, Perl 5
-tries to be more precise. For example, on a Solaris Sparc:
-
- print 7.373504 - 0, "\n";
- printf "%20.18f\n", 7.373504 - 0;
-
- # Perl4 prints:
- 7.3750399999999996141
- 7.375039999999999614
-
- # Perl5 prints:
- 7.373504
- 7.373503999999999614
-
-Notice how the first result looks better in Perl 5.
-
-Your results may vary, since your floating point formatting routines
-and even floating point format may be slightly different.
-
-=item * Auto-increment operator over signed int limit deleted
-
-This specific item has been deleted. It demonstrated how the auto-increment
-operator would not catch when a number went over the signed int limit. Fixed
-in version 5.003_04. But always be wary when using large integers.
-If in doubt:
-
- use Math::BigInt;
-
-=item * Assignment of return values from numeric equality tests doesn't work
-
-Assignment of return values from numeric equality tests
-does not work in perl5 when the test evaluates to false (0).
-Logical tests now return a null, instead of 0
-
- $p = ($test == 1);
- print $p,"\n";
-
- # perl4 prints: 0
- # perl5 prints:
-
-Also see L<"General Regular Expression Traps using s///, etc.">
-for another example of this new feature...
-
-=item * Bitwise string ops
-
-When bitwise operators which can operate upon either numbers or
-strings (C<& | ^ ~>) are given only strings as arguments, perl4 would
-treat the operands as bitstrings so long as the program contained a call
-to the C<vec()> function. perl5 treats the string operands as bitstrings.
-(See L<perlop/Bitwise String Operators> for more details.)
-
- $fred = "10";
- $barney = "12";
- $betty = $fred & $barney;
- print "$betty\n";
- # Uncomment the next line to change perl4's behavior
- # ($dummy) = vec("dummy", 0, 0);
-
- # Perl4 prints:
- 8
-
- # Perl5 prints:
- 10
-
- # If vec() is used anywhere in the program, both print:
- 10
-
-=back
-
-=head2 General data type traps
-
-Perl4-to-Perl5 traps involving most data-types, and their usage
-within certain expressions and/or context.
-
-=over 5
-
-=item * Negative array subscripts now count from the end of array
-
-Negative array subscripts now count from the end of the array.
-
- @a = (1, 2, 3, 4, 5);
- print "The third element of the array is $a[3] also expressed as $a[-2] \n";
-
- # perl4 prints: The third element of the array is 4 also expressed as
- # perl5 prints: The third element of the array is 4 also expressed as 4
-
-=item * Setting C<$#array> lower now discards array elements
-
-Setting C<$#array> lower now discards array elements, and makes them
-impossible to recover.
-
- @a = (a,b,c,d,e);
- print "Before: ",join('',@a);
- $#a =1;
- print ", After: ",join('',@a);
- $#a =3;
- print ", Recovered: ",join('',@a),"\n";
-
- # perl4 prints: Before: abcde, After: ab, Recovered: abcd
- # perl5 prints: Before: abcde, After: ab, Recovered: ab
-
-=item * Hashes get defined before use
-
-Hashes get defined before use
-
- local($s,@a,%h);
- die "scalar \$s defined" if defined($s);
- die "array \@a defined" if defined(@a);
- die "hash \%h defined" if defined(%h);
-
- # perl4 prints:
- # perl5 dies: hash %h defined
-
-Perl will now generate a warning when it sees defined(@a) and
-defined(%h).
-
-=item * Glob assignment from localized variable to variable
-
-glob assignment from variable to variable will fail if the assigned
-variable is localized subsequent to the assignment
-
- @a = ("This is Perl 4");
- *b = *a;
- local(@a);
- print @b,"\n";
-
- # perl4 prints: This is Perl 4
- # perl5 prints:
-
-=item * Assigning C<undef> to glob
-
-Assigning C<undef> to a glob has no effect in Perl 5. In Perl 4
-it undefines the associated scalar (but may have other side effects
-including SEGVs). Perl 5 will also warn if C<undef> is assigned to a
-typeglob. (Note that assigning C<undef> to a typeglob is different
-than calling the C<undef> function on a typeglob (C<undef *foo>), which
-has quite a few effects.
-
- $foo = "bar";
- *foo = undef;
- print $foo;
-
- # perl4 prints:
- # perl4 warns: "Use of uninitialized variable" if using -w
- # perl5 prints: bar
- # perl5 warns: "Undefined value assigned to typeglob" if using -w
-
-=item * Changes in unary negation (of strings)
-
-Changes in unary negation (of strings)
-This change effects both the return value and what it
-does to auto(magic)increment.
-
- $x = "aaa";
- print ++$x," : ";
- print -$x," : ";
- print ++$x,"\n";
-
- # perl4 prints: aab : -0 : 1
- # perl5 prints: aab : -aab : aac
-
-=item * Modifying of constants prohibited
-
-perl 4 lets you modify constants:
-
- $foo = "x";
- &mod($foo);
- for ($x = 0; $x < 3; $x++) {
- &mod("a");
- }
- sub mod {
- print "before: $_[0]";
- $_[0] = "m";
- print " after: $_[0]\n";
- }
-
- # perl4:
- # before: x after: m
- # before: a after: m
- # before: m after: m
- # before: m after: m
-
- # Perl5:
- # before: x after: m
- # Modification of a read-only value attempted at foo.pl line 12.
- # before: a
-
-=item * C<defined $var> behavior changed
-
-The behavior is slightly different for:
-
- print "$x", defined $x
-
- # perl 4: 1
- # perl 5: <no output, $x is not called into existence>
-
-=item * Variable Suicide
-
-Variable suicide behavior is more consistent under Perl 5.
-Perl5 exhibits the same behavior for hashes and scalars,
-that perl4 exhibits for only scalars.
-
- $aGlobal{ "aKey" } = "global value";
- print "MAIN:", $aGlobal{"aKey"}, "\n";
- $GlobalLevel = 0;
- &test( *aGlobal );
-
- sub test {
- local( *theArgument ) = @_;
- local( %aNewLocal ); # perl 4 != 5.001l,m
- $aNewLocal{"aKey"} = "this should never appear";
- print "SUB: ", $theArgument{"aKey"}, "\n";
- $aNewLocal{"aKey"} = "level $GlobalLevel"; # what should print
- $GlobalLevel++;
- if( $GlobalLevel<4 ) {
- &test( *aNewLocal );
- }
- }
-
- # Perl4:
- # MAIN:global value
- # SUB: global value
- # SUB: level 0
- # SUB: level 1
- # SUB: level 2
-
- # Perl5:
- # MAIN:global value
- # SUB: global value
- # SUB: this should never appear
- # SUB: this should never appear
- # SUB: this should never appear
-
-=back
-
-=head2 Context Traps - scalar, list contexts
-
-=over 5
-
-=item * Elements of argument lists for formats evaluated in list context
-
-The elements of argument lists for formats are now evaluated in list
-context. This means you can interpolate list values now.
-
- @fmt = ("foo","bar","baz");
- format STDOUT=
- @<<<<< @||||| @>>>>>
- @fmt;
- .
- write;
-
- # perl4 errors: Please use commas to separate fields in file
- # perl5 prints: foo bar baz
-
-=item * C<caller()> returns false value in scalar context if no caller present
-
-The C<caller()> function now returns a false value in a scalar context
-if there is no caller. This lets library files determine if they're
-being required.
-
- caller() ? (print "You rang?\n") : (print "Got a 0\n");
-
- # perl4 errors: There is no caller
- # perl5 prints: Got a 0
-
-=item * Comma operator in scalar context gives scalar context to args
-
-The comma operator in a scalar context is now guaranteed to give a
-scalar context to its last argument. It gives scalar or void context
-to any preceding arguments, depending on circumstances.
-
- @y= ('a','b','c');
- $x = (1, 2, @y);
- print "x = $x\n";
-
- # Perl4 prints: x = c # Interpolates array @y into the list
- # Perl5 prints: x = 3 # Evaluates array @y in scalar context
-
-=item * C<sprintf()> prototyped as C<($;@)>
-
-C<sprintf()> is prototyped as ($;@), so its first argument is given scalar
-context. Thus, if passed an array, it will probably not do what you want,
-unlike Perl 4:
-
- @z = ('%s%s', 'foo', 'bar');
- $x = sprintf(@z);
- print $x;
-
- # perl4 prints: foobar
- # perl5 prints: 3
-
-C<printf()> works the same as it did in Perl 4, though:
-
- @z = ('%s%s', 'foo', 'bar');
- printf STDOUT (@z);
-
- # perl4 prints: foobar
- # perl5 prints: foobar
-
-=back
-
-=head2 Precedence Traps
-
-Perl4-to-Perl5 traps involving precedence order.
-
-Perl 4 has almost the same precedence rules as Perl 5 for the operators
-that they both have. Perl 4 however, seems to have had some
-inconsistencies that made the behavior differ from what was documented.
-
-=over 5
-
-=item * LHS vs. RHS of any assignment operator
-
-LHS vs. RHS of any assignment operator. LHS is evaluated first
-in perl4, second in perl5; this can affect the relationship
-between side-effects in sub-expressions.
-
- @arr = ( 'left', 'right' );
- $a{shift @arr} = shift @arr;
- print join( ' ', keys %a );
-
- # perl4 prints: left
- # perl5 prints: right
-
-=item * Semantic errors introduced due to precedence
-
-These are now semantic errors because of precedence:
-
- @list = (1,2,3,4,5);
- %map = ("a",1,"b",2,"c",3,"d",4);
- $n = shift @list + 2; # first item in list plus 2
- print "n is $n, ";
- $m = keys %map + 2; # number of items in hash plus 2
- print "m is $m\n";
-
- # perl4 prints: n is 3, m is 6
- # perl5 errors and fails to compile
-
-=item * Precedence of assignment operators same as the precedence of assignment
-
-The precedence of assignment operators is now the same as the precedence
-of assignment. Perl 4 mistakenly gave them the precedence of the associated
-operator. So you now must parenthesize them in expressions like
-
- /foo/ ? ($a += 2) : ($a -= 2);
-
-Otherwise
-
- /foo/ ? $a += 2 : $a -= 2
-
-would be erroneously parsed as
-
- (/foo/ ? $a += 2 : $a) -= 2;
-
-On the other hand,
-
- $a += /foo/ ? 1 : 2;
-
-now works as a C programmer would expect.
-
-=item * C<open> requires parentheses around filehandle
-
- open FOO || die;
-
-is now incorrect. You need parentheses around the filehandle.
-Otherwise, perl5 leaves the statement as its default precedence:
-
- open(FOO || die);
-
- # perl4 opens or dies
- # perl5 opens FOO, dying only if 'FOO' is false, i.e. never
-
-=item * C<$:> precedence over C<$::> gone
-
-perl4 gives the special variable, C<$:> precedence, where perl5
-treats C<$::> as main C<package>
-
- $a = "x"; print "$::a";
-
- # perl 4 prints: -:a
- # perl 5 prints: x
-
-=item * Precedence of file test operators documented
-
-perl4 had buggy precedence for the file test operators vis-a-vis
-the assignment operators. Thus, although the precedence table
-for perl4 leads one to believe C<-e $foo .= "q"> should parse as
-C<((-e $foo) .= "q")>, it actually parses as C<(-e ($foo .= "q"))>.
-In perl5, the precedence is as documented.
-
- -e $foo .= "q"
-
- # perl4 prints: no output
- # perl5 prints: Can't modify -e in concatenation
-
-=item * C<keys>, C<each>, C<values> are regular named unary operators
-
-In perl4, keys(), each() and values() were special high-precedence operators
-that operated on a single hash, but in perl5, they are regular named unary
-operators. As documented, named unary operators have lower precedence
-than the arithmetic and concatenation operators C<+ - .>, but the perl4
-variants of these operators actually bind tighter than C<+ - .>.
-Thus, for:
-
- %foo = 1..10;
- print keys %foo - 1
-
- # perl4 prints: 4
- # perl5 prints: Type of arg 1 to keys must be hash (not subtraction)
-
-The perl4 behavior was probably more useful, if less consistent.
-
-=back
-
-=head2 General Regular Expression Traps using s///, etc.
-
-All types of RE traps.
-
-=over 5
-
-=item * C<s'$lhs'$rhs'> interpolates on either side
-
-C<s'$lhs'$rhs'> now does no interpolation on either side. It used to
-interpolate $lhs but not $rhs. (And still does not match a literal
-'$' in string)
-
- $a=1;$b=2;
- $string = '1 2 $a $b';
- $string =~ s'$a'$b';
- print $string,"\n";
-
- # perl4 prints: $b 2 $a $b
- # perl5 prints: 1 2 $a $b
-
-=item * C<m//g> attaches its state to the searched string
-
-C<m//g> now attaches its state to the searched string rather than the
-regular expression. (Once the scope of a block is left for the sub, the
-state of the searched string is lost)
-
- $_ = "ababab";
- while(m/ab/g){
- &doit("blah");
- }
- sub doit{local($_) = shift; print "Got $_ "}
-
- # perl4 prints: Got blah Got blah Got blah Got blah
- # perl5 prints: infinite loop blah...
-
-=item * C<m//o> used within an anonymous sub
-
-Currently, if you use the C<m//o> qualifier on a regular expression
-within an anonymous sub, I<all> closures generated from that anonymous
-sub will use the regular expression as it was compiled when it was used
-the very first time in any such closure. For instance, if you say
-
- sub build_match {
- my($left,$right) = @_;
- return sub { $_[0] =~ /$left stuff $right/o; };
- }
- $good = build_match('foo','bar');
- $bad = build_match('baz','blarch');
- print $good->('foo stuff bar') ? "ok\n" : "not ok\n";
- print $bad->('baz stuff blarch') ? "ok\n" : "not ok\n";
- print $bad->('foo stuff bar') ? "not ok\n" : "ok\n";
-
-For most builds of Perl5, this will print:
-ok
-not ok
-not ok
-
-build_match() will always return a sub which matches the contents of
-$left and $right as they were the I<first> time that build_match()
-was called, not as they are in the current call.
-
-=item * C<$+> isn't set to whole match
-
-If no parentheses are used in a match, Perl4 sets C<$+> to
-the whole match, just like C<$&>. Perl5 does not.
-
- "abcdef" =~ /b.*e/;
- print "\$+ = $+\n";
-
- # perl4 prints: bcde
- # perl5 prints:
-
-=item * Substitution now returns null string if it fails
-
-substitution now returns the null string if it fails
-
- $string = "test";
- $value = ($string =~ s/foo//);
- print $value, "\n";
-
- # perl4 prints: 0
- # perl5 prints:
-
-Also see L<Numerical Traps> for another example of this new feature.
-
-=item * C<s`lhs`rhs`> is now a normal substitution
-
-C<s`lhs`rhs`> (using backticks) is now a normal substitution, with no
-backtick expansion
-
- $string = "";
- $string =~ s`^`hostname`;
- print $string, "\n";
-
- # perl4 prints: <the local hostname>
- # perl5 prints: hostname
-
-=item * Stricter parsing of variables in regular expressions
-
-Stricter parsing of variables used in regular expressions
-
- s/^([^$grpc]*$grpc[$opt$plus$rep]?)//o;
-
- # perl4: compiles w/o error
- # perl5: with Scalar found where operator expected ..., near "$opt$plus"
-
-an added component of this example, apparently from the same script, is
-the actual value of the s'd string after the substitution.
-C<[$opt]> is a character class in perl4 and an array subscript in perl5
-
- $grpc = 'a';
- $opt = 'r';
- $_ = 'bar';
- s/^([^$grpc]*$grpc[$opt]?)/foo/;
- print;
-
- # perl4 prints: foo
- # perl5 prints: foobar
-
-=item * C<m?x?> matches only once
-
-Under perl5, C<m?x?> matches only once, like C<?x?>. Under perl4, it matched
-repeatedly, like C</x/> or C<m!x!>.
-
- $test = "once";
- sub match { $test =~ m?once?; }
- &match();
- if( &match() ) {
- # m?x? matches more then once
- print "perl4\n";
- } else {
- # m?x? matches only once
- print "perl5\n";
- }
-
- # perl4 prints: perl4
- # perl5 prints: perl5
-
-=item * Failed matches don't reset the match variables
-
-Unlike in Ruby, failed matches in Perl do not reset the match variables
-($1, $2, ..., C<$`>, ...).
-
-=back
-
-=head2 Subroutine, Signal, Sorting Traps
-
-The general group of Perl4-to-Perl5 traps having to do with
-Signals, Sorting, and their related subroutines, as well as
-general subroutine traps. Includes some OS-Specific traps.
-
-=over 5
-
-=item * Barewords that used to look like strings look like subroutine calls
-
-Barewords that used to look like strings to Perl will now look like subroutine
-calls if a subroutine by that name is defined before the compiler sees them.
-
- sub SeeYa { warn"Hasta la vista, baby!" }
- $SIG{'TERM'} = SeeYa;
- print "SIGTERM is now $SIG{'TERM'}\n";
-
- # perl4 prints: SIGTERM is now main'SeeYa
- # perl5 prints: SIGTERM is now main::1 (and warns "Hasta la vista, baby!")
-
-Use B<-w> to catch this one
-
-=item * Reverse is no longer allowed as the name of a sort subroutine
-
-reverse is no longer allowed as the name of a sort subroutine.
-
- sub reverse{ print "yup "; $a <=> $b }
- print sort reverse (2,1,3);
-
- # perl4 prints: yup yup 123
- # perl5 prints: 123
- # perl5 warns (if using -w): Ambiguous call resolved as CORE::reverse()
-
-=item * C<warn()> won't let you specify a filehandle.
-
-Although it _always_ printed to STDERR, warn() would let you specify a
-filehandle in perl4. With perl5 it does not.
-
- warn STDERR "Foo!";
-
- # perl4 prints: Foo!
- # perl5 prints: String found where operator expected
-
-=back
-
-=head2 OS Traps
-
-=over 5
-
-=item * SysV resets signal handler correctly
-
-Under HPUX, and some other SysV OSes, one had to reset any signal handler,
-within the signal handler function, each time a signal was handled with
-perl4. With perl5, the reset is now done correctly. Any code relying
-on the handler _not_ being reset will have to be reworked.
-
-Since version 5.002, Perl uses sigaction() under SysV.
-
- sub gotit {
- print "Got @_... ";
- }
- $SIG{'INT'} = 'gotit';
-
- $| = 1;
- $pid = fork;
- if ($pid) {
- kill('INT', $pid);
- sleep(1);
- kill('INT', $pid);
- } else {
- while (1) {sleep(10);}
- }
-
- # perl4 (HPUX) prints: Got INT...
- # perl5 (HPUX) prints: Got INT... Got INT...
-
-=item * SysV C<seek()> appends correctly
-
-Under SysV OSes, C<seek()> on a file opened to append C<<< >> >>> now does
-the right thing w.r.t. the fopen() manpage. e.g., - When a file is opened
-for append, it is impossible to overwrite information already in
-the file.
-
- open(TEST,">>seek.test");
- $start = tell TEST;
- foreach(1 .. 9){
- print TEST "$_ ";
- }
- $end = tell TEST;
- seek(TEST,$start,0);
- print TEST "18 characters here";
-
- # perl4 (solaris) seek.test has: 18 characters here
- # perl5 (solaris) seek.test has: 1 2 3 4 5 6 7 8 9 18 characters here
-
-
-
-=back
-
-=head2 Interpolation Traps
-
-Perl4-to-Perl5 traps having to do with how things get interpolated
-within certain expressions, statements, contexts, or whatever.
-
-=over 5
-
-=item * C<@> always interpolates an array in double-quotish strings
-
-@ now always interpolates an array in double-quotish strings.
-
- print "To: someone@somewhere.com\n";
-
- # perl4 prints: To:someone@somewhere.com
- # perl < 5.6.1, error : In string, @somewhere now must be written as \@somewhere
- # perl >= 5.6.1, warning : Possible unintended interpolation of @somewhere in string
-
-=item * Double-quoted strings may no longer end with an unescaped $
-
-Double-quoted strings may no longer end with an unescaped $.
-
- $foo = "foo$";
- print "foo is $foo\n";
-
- # perl4 prints: foo is foo$
- # perl5 errors: Final $ should be \$ or $name
-
-Note: perl5 DOES NOT error on the terminating @ in $bar
-
-=item * Arbitrary expressions are evaluated inside braces within double quotes
-
-Perl now sometimes evaluates arbitrary expressions inside braces that occur
-within double quotes (usually when the opening brace is preceded by C<$>
-or C<@>).
-
- @www = "buz";
- $foo = "foo";
- $bar = "bar";
- sub foo { return "bar" };
- print "|@{w.w.w}|${main'foo}|";
-
- # perl4 prints: |@{w.w.w}|foo|
- # perl5 prints: |buz|bar|
-
-Note that you can C<use strict;> to ward off such trappiness under perl5.
-
-=item * C<$$x> now tries to dereference $x
-
-The construct "this is $$x" used to interpolate the pid at that point, but
-now tries to dereference $x. C<$$> by itself still works fine, however.
-
- $s = "a reference";
- $x = *s;
- print "this is $$x\n";
-
- # perl4 prints: this is XXXx (XXX is the current pid)
- # perl5 prints: this is a reference
-
-=item * Creation of hashes on the fly with C<eval "EXPR"> requires protection
-
-Creation of hashes on the fly with C<eval "EXPR"> now requires either both
-C<$>'s to be protected in the specification of the hash name, or both curlies
-to be protected. If both curlies are protected, the result will be compatible
-with perl4 and perl5. This is a very common practice, and should be changed
-to use the block form of C<eval{}> if possible.
-
- $hashname = "foobar";
- $key = "baz";
- $value = 1234;
- eval "\$$hashname{'$key'} = q|$value|";
- (defined($foobar{'baz'})) ? (print "Yup") : (print "Nope");
-
- # perl4 prints: Yup
- # perl5 prints: Nope
-
-Changing
-
- eval "\$$hashname{'$key'} = q|$value|";
-
-to
-
- eval "\$\$hashname{'$key'} = q|$value|";
-
-causes the following result:
-
- # perl4 prints: Nope
- # perl5 prints: Yup
-
-or, changing to
-
- eval "\$$hashname\{'$key'\} = q|$value|";
-
-causes the following result:
-
- # perl4 prints: Yup
- # perl5 prints: Yup
- # and is compatible for both versions
-
-
-=item * Bugs in earlier perl versions
-
-perl4 programs which unconsciously rely on the bugs in earlier perl versions.
-
- perl -e '$bar=q/not/; print "This is $foo{$bar} perl5"'
-
- # perl4 prints: This is not perl5
- # perl5 prints: This is perl5
-
-=item * Array and hash brackets during interpolation
-
-You also have to be careful about array and hash brackets during
-interpolation.
-
- print "$foo["
-
- perl 4 prints: [
- perl 5 prints: syntax error
-
- print "$foo{"
-
- perl 4 prints: {
- perl 5 prints: syntax error
-
-Perl 5 is expecting to find an index or key name following the respective
-brackets, as well as an ending bracket of the appropriate type. In order
-to mimic the behavior of Perl 4, you must escape the bracket like so.
-
- print "$foo\[";
- print "$foo\{";
-
-=item * Interpolation of C<\$$foo{bar}>
-
-Similarly, watch out for: C<\$$foo{bar}>
-
- $foo = "baz";
- print "\$$foo{bar}\n";
-
- # perl4 prints: $baz{bar}
- # perl5 prints: $
-
-Perl 5 is looking for C<$foo{bar}> which doesn't exist, but perl 4 is
-happy just to expand $foo to "baz" by itself. Watch out for this
-especially in C<eval>'s.
-
-=item * C<qq()> string passed to C<eval> will not find string terminator
-
-C<qq()> string passed to C<eval>
-
- eval qq(
- foreach \$y (keys %\$x\) {
- \$count++;
- }
- );
-
- # perl4 runs this ok
- # perl5 prints: Can't find string terminator ")"
-
-=back
-
-=head2 DBM Traps
-
-General DBM traps.
-
-=over 5
-
-=item * Perl5 must have been linked with same dbm/ndbm as the default for C<dbmopen()>
-
-Existing dbm databases created under perl4 (or any other dbm/ndbm tool)
-may cause the same script, run under perl5, to fail. The build of perl5
-must have been linked with the same dbm/ndbm as the default for C<dbmopen()>
-to function properly without C<tie>'ing to an extension dbm implementation.
-
- dbmopen (%dbm, "file", undef);
- print "ok\n";
-
- # perl4 prints: ok
- # perl5 prints: ok (IFF linked with -ldbm or -lndbm)
-
-
-=item * DBM exceeding limit on the key/value size will cause perl5 to exit immediately
-
-Existing dbm databases created under perl4 (or any other dbm/ndbm tool)
-may cause the same script, run under perl5, to fail. The error generated
-when exceeding the limit on the key/value size will cause perl5 to exit
-immediately.
-
- dbmopen(DB, "testdb",0600) || die "couldn't open db! $!";
- $DB{'trap'} = "x" x 1024; # value too large for most dbm/ndbm
- print "YUP\n";
-
- # perl4 prints:
- dbm store returned -1, errno 28, key "trap" at - line 3.
- YUP
-
- # perl5 prints:
- dbm store returned -1, errno 28, key "trap" at - line 3.
-
-=back
-
-=head2 Unclassified Traps
-
-Everything else.
-
-=over 5
-
-=item * C<require>/C<do> trap using returned value
-
-If the file doit.pl has:
-
- sub foo {
- $rc = do "./do.pl";
- return 8;
- }
- print &foo, "\n";
-
-And the do.pl file has the following single line:
-
- return 3;
-
-Running doit.pl gives the following:
-
- # perl 4 prints: 3 (aborts the subroutine early)
- # perl 5 prints: 8
-
-Same behavior if you replace C<do> with C<require>.
-
-=item * C<split> on empty string with LIMIT specified
-
- $string = '';
- @list = split(/foo/, $string, 2)
-
-Perl4 returns a one element list containing the empty string but Perl5
-returns an empty list.
-
-=back
-
-As always, if any of these are ever officially declared as bugs,
-they'll be fixed and removed.
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perltru64.pod b/Master/tlpkg/tlperl/lib/pods/perltru64.pod
deleted file mode 100644
index 81ef9feb98c..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perltru64.pod
+++ /dev/null
@@ -1,172 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you see.
-It is written in the POD format (see pod/perlpod.pod) which is specially
-designed to be readable as is.
-
-=head1 NAME
-
-perltru64 - Perl version 5 on Tru64 (formerly known as Digital UNIX formerly known as DEC OSF/1) systems
-
-=head1 DESCRIPTION
-
-This document describes various features of HP's (formerly Compaq's,
-formerly Digital's) Unix operating system (Tru64) that will affect
-how Perl version 5 (hereafter just Perl) is configured, compiled
-and/or runs.
-
-=head2 Compiling Perl 5 on Tru64
-
-The recommended compiler to use in Tru64 is the native C compiler.
-The native compiler produces much faster code (the speed difference is
-noticeable: several dozen percentages) and also more correct code: if
-you are considering using the GNU C compiler you should use at the
-very least the release of 2.95.3 since all older gcc releases are
-known to produce broken code when compiling Perl. One manifestation
-of this brokenness is the lib/sdbm test dumping core; another is many
-of the op/regexp and op/pat, or ext/Storable tests dumping core
-(the exact pattern of failures depending on the GCC release and
-optimization flags).
-
-gcc 3.2.1 is known to work okay with Perl 5.8.0. However, when
-optimizing the toke.c gcc likes to have a lot of memory, 256 megabytes
-seems to be enough. The default setting of the process data section
-in Tru64 should be one gigabyte, but some sites/setups might have
-lowered that. The configuration process of Perl checks for too low
-process limits, and lowers the optimization for the toke.c if
-necessary, and also gives advice on how to raise the process limits.
-
-Also, Configure might abort with
-
- Build a threading Perl? [n]
- Configure[2437]: Syntax error at line 1 : 'config.sh' is not expected.
-
-This indicates that Configure is being run with a broken Korn shell
-(even though you think you are using a Bourne shell by using
-"sh Configure" or "./Configure"). The Korn shell bug has been reported
-to Compaq as of February 1999 but in the meanwhile, the reason ksh is
-being used is that you have the environment variable BIN_SH set to
-'xpg4'. This causes /bin/sh to delegate its duties to /bin/posix/sh
-(a ksh). Unset the environment variable and rerun Configure.
-
-=head2 Using Large Files with Perl on Tru64
-
-In Tru64 Perl is automatically able to use large files, that is,
-files larger than 2 gigabytes, there is no need to use the Configure
--Duselargefiles option as described in INSTALL (though using the option
-is harmless).
-
-=head2 Threaded Perl on Tru64
-
-If you want to use threads, you should primarily use the Perl
-5.8.0 threads model by running Configure with -Duseithreads.
-
-Perl threading is going to work only in Tru64 4.0 and newer releases,
-older operating releases like 3.2 aren't probably going to work
-properly with threads.
-
-In Tru64 V5 (at least V5.1A, V5.1B) you cannot build threaded Perl with gcc
-because the system header <pthread.h> explicitly checks for supported
-C compilers, gcc (at least 3.2.2) not being one of them. But the
-system C compiler should work just fine.
-
-=head2 Long Doubles on Tru64
-
-You cannot Configure Perl to use long doubles unless you have at least
-Tru64 V5.0, the long double support simply wasn't functional enough
-before that. Perl's Configure will override attempts to use the long
-doubles (you can notice this by Configure finding out that the modfl()
-function does not work as it should).
-
-At the time of this writing (June 2002), there is a known bug in the
-Tru64 libc printing of long doubles when not using "e" notation.
-The values are correct and usable, but you only get a limited number
-of digits displayed unless you force the issue by using C<printf
-"%.33e",$num> or the like. For Tru64 versions V5.0A through V5.1A, a
-patch is expected sometime after perl 5.8.0 is released. If your libc
-has not yet been patched, you'll get a warning from Configure when
-selecting long doubles.
-
-=head2 DB_File tests failing on Tru64
-
-The DB_File tests (db-btree.t, db-hash.t, db-recno.t) may fail you
-have installed a newer version of Berkeley DB into the system and the
--I and -L compiler and linker flags introduce version conflicts with
-the DB 1.85 headers and libraries that came with the Tru64. For example,
-mixing a DB v2 library with the DB v1 headers is a bad idea. Watch
-out for Configure options -Dlocincpth and -Dloclibpth, and check your
-/usr/local/include and /usr/local/lib since they are included by default.
-
-The second option is to explicitly instruct Configure to detect the
-newer Berkeley DB installation, by supplying the right directories with
-C<-Dlocincpth=/some/include> and C<-Dloclibpth=/some/lib> B<and> before
-running "make test" setting your LD_LIBRARY_PATH to F</some/lib>.
-
-The third option is to work around the problem by disabling the
-DB_File completely when build Perl by specifying -Ui_db to Configure,
-and then using the BerkeleyDB module from CPAN instead of DB_File.
-The BerkeleyDB works with Berkeley DB versions 2.* or greater.
-
-The Berkeley DB 4.1.25 has been tested with Tru64 V5.1A and found
-to work. The latest Berkeley DB can be found from L<http://www.sleepycat.com>.
-
-=head2 64-bit Perl on Tru64
-
-In Tru64 Perl's integers are automatically 64-bit wide, there is
-no need to use the Configure -Duse64bitint option as described
-in INSTALL. Similarly, there is no need for -Duse64bitall
-since pointers are automatically 64-bit wide.
-
-=head2 Warnings about floating-point overflow when compiling Perl on Tru64
-
-When compiling Perl in Tru64 you may (depending on the compiler
-release) see two warnings like this
-
- cc: Warning: numeric.c, line 104: In this statement, floating-point overflow occurs in evaluating the expression "1.8e308". (floatoverfl)
- return HUGE_VAL;
- -----------^
-
-and when compiling the POSIX extension
-
- cc: Warning: const-c.inc, line 2007: In this statement, floating-point overflow occurs in evaluating the expression "1.8e308". (floatoverfl)
- return HUGE_VAL;
- -------------------^
-
-The exact line numbers may vary between Perl releases. The warnings
-are benign and can be ignored: in later C compiler releases the warnings
-should be gone.
-
-When the file F<pp_sys.c> is being compiled you may (depending on the
-operating system release) see an additional compiler flag being used:
-C<-DNO_EFF_ONLY_OK>. This is normal and refers to a feature that is
-relevant only if you use the C<filetest> pragma. In older releases of
-the operating system the feature was broken and the NO_EFF_ONLY_OK
-instructs Perl not to use the feature.
-
-=head1 Testing Perl on Tru64
-
-During "make test" the C<comp/cpp> will be skipped because on Tru64 it
-cannot be tested before Perl has been installed. The test refers to
-the use of the C<-P> option of Perl.
-
-=head1 ext/ODBM_File/odbm Test Failing With Static Builds
-
-The ext/ODBM_File/odbm is known to fail with static builds
-(Configure -Uusedl) due to a known bug in Tru64's static libdbm
-library. The good news is that you very probably don't need to ever
-use the ODBM_File extension since more advanced NDBM_File works fine,
-not to mention the even more advanced DB_File.
-
-=head1 Perl Fails Because Of Unresolved Symbol sockatmark
-
-If you get an error like
-
- Can't load '.../OSF1/lib/perl5/5.8.0/alpha-dec_osf/auto/IO/IO.so' for module IO: Unresolved symbol in .../lib/perl5/5.8.0/alpha-dec_osf/auto/IO/IO.so: sockatmark at .../lib/perl5/5.8.0/alpha-dec_osf/XSLoader.pm line 75.
-
-you need to either recompile your Perl in Tru64 4.0D or upgrade your
-Tru64 4.0D to at least 4.0F: the sockatmark() system call was
-added in Tru64 4.0F, and the IO extension refers that symbol.
-
-=head1 AUTHOR
-
-Jarkko Hietaniemi <jhi@iki.fi>
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perltw.pod b/Master/tlpkg/tlperl/lib/pods/perltw.pod
deleted file mode 100644
index 4e029d91f2a..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perltw.pod
+++ /dev/null
@@ -1,172 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see perlpod manpage) which is
-specially designed to be readable as is.
-
-The following documentation is written in UTF-8 encoding.
-
-如果你用一般的文字編輯器閱覽這份文件, 請忽略文中奇特的註記字符.
-這份文件是以 POD (簡明文件格å¼) 寫æˆ; 這種格å¼æ˜¯ç‚ºäº†èƒ½è®“人直接讀å–,
-而特別設計的. 關於此格å¼çš„進一步資訊, è«‹åƒè€ƒ perlpod 線上文件.
-
-=encoding UTF-8
-
-=head1 NAME
-
-perltw - 正體中文 Perl 指å—
-
-=head1 DESCRIPTION
-
-歡迎來到 Perl 的天地!
-
-從 5.8.0 版開始, Perl 具備了完善的 Unicode (è¬åœ‹ç¢¼) 支æ´,
-也連帶支æ´äº†è¨±å¤šæ‹‰ä¸èªžç³»ä»¥å¤–的編碼方å¼; CJK (中日韓) 便是其中的一部份.
-Unicode 是國際性的標準, 試圖涵蓋世界上所有的字符: 西方世界, æ±æ–¹ä¸–ç•Œ,
-以åŠå…©è€…間的一切 (希臘文, 敘利亞文, 阿拉伯文, 希伯來文, å°åº¦æ–‡,
-å°åœ°å®‰æ–‡, 等等). 它也容ç´äº†å¤šç¨®ä½œæ¥­ç³»çµ±èˆ‡å¹³è‡º (如 PC åŠéº¥é‡‘å¡”).
-
-Perl 本身以 Unicode 進行æ“作. 這表示 Perl 內部的字串資料å¯ç”¨ Unicode
-表示; Perl 的函å¼èˆ‡ç®—符 (例如正è¦è¡¨ç¤ºå¼æ¯”å°) ä¹Ÿèƒ½å° Unicode 進行æ“作.
-在輸入åŠè¼¸å‡ºæ™‚, 為了處ç†ä»¥ Unicode 之å‰çš„編碼方å¼å„²å­˜çš„資料, Perl
-æ供了 Encode 這個模組, å¯ä»¥è®“你輕易地讀å–åŠå¯«å…¥èˆŠæœ‰çš„編碼資料.
-
-Encode 延伸模組支æ´ä¸‹åˆ—æ­£é«”ä¸­æ–‡çš„ç·¨ç¢¼æ–¹å¼ ('big5' 表示 'big5-eten'):
-
- big5-eten Big5 編碼 (å«å€šå¤©å»¶ä¼¸å­—å½¢)
- big5-hkscs Big5 + 香港外字集, 2001 年版
- cp950 å­—ç¢¼é  950 (Big5 + 微軟添加的字符)
-
-舉例來說, å°‡ Big5 ç·¨ç¢¼çš„æª”æ¡ˆè½‰æˆ Unicode, 祗需éµå…¥ä¸‹åˆ—指令:
-
- perl -Mencoding=big5,STDOUT,utf8 -pe1 < file.big5 > file.utf8
-
-Perl 也內附了 "piconv", 一支完全以 Perl 寫æˆçš„字符轉æ›å·¥å…·ç¨‹å¼, 用法如下:
-
- piconv -f big5 -t utf8 < file.big5 > file.utf8
- piconv -f utf8 -t big5 < file.utf8 > file.big5
-
-å¦å¤–, 利用 encoding 模組, ä½ å¯ä»¥è¼•æ˜“寫出以字符為單ä½çš„程å¼ç¢¼, 如下所示:
-
- #!/usr/bin/env perl
- # å•Ÿå‹• big5 字串解æž; 標準輸出入åŠæ¨™æº–錯誤都設為 big5 編碼
- use encoding 'big5', STDIN => 'big5', STDOUT => 'big5';
- print length("駱é§"); # 2 (雙引號表示字符)
- print length('駱é§'); # 4 (單引號表示ä½å…ƒçµ„)
- print index("諄諄教誨", "彖帢"); # -1 (ä¸åŒ…å«æ­¤å­å­—串)
- print index('諄諄教誨', '彖帢'); # 1 (從第二個ä½å…ƒçµ„開始)
-
-在最後一列例å­è£¡, "è«„" 的第二個ä½å…ƒçµ„與 "è«„" 的第一個ä½å…ƒçµ„çµåˆæˆ Big5
-碼的 "å½–"; "è«„" 的第二個ä½å…ƒçµ„則與 "æ•™" 的第一個ä½å…ƒçµ„çµåˆæˆ "帢".
-é€™è§£æ±ºäº†ä»¥å‰ Big5 碼比å°è™•ç†ä¸Šå¸¸è¦‹çš„å•é¡Œ.
-
-=head2 é¡å¤–的中文編碼
-
-如果需è¦æ›´å¤šçš„中文編碼, å¯ä»¥å¾ž CPAN (L<http://www.cpan.org/>) 下載
-Encode::HanExtra 模組. 它目å‰æ供下列編碼方å¼:
-
- cccii 1980 年文建會的中文資訊交æ›ç¢¼
- euc-tw Unix 延伸字符集, åŒ…å« CNS11643 å¹³é¢ 1-7
- big5plus 中文數ä½åŒ–技術推廣基金會的 Big5+
- big5ext 中文數ä½åŒ–技術推廣基金會的 Big5e
-
-å¦å¤–, Encode::HanConvert 模組則æ供了簡ç¹è½‰æ›ç”¨çš„兩種編碼:
-
- big5-simp Big5 正體中文與 Unicode 簡體中文互轉
- gbk-trad GBK 簡體中文與 Unicode 正體中文互轉
-
-若想在 GBK 與 Big5 之間互轉, è«‹åƒè€ƒè©²æ¨¡çµ„內附的 b2g.pl 與 g2b.pl 兩支程å¼,
-或在程å¼å…§ä½¿ç”¨ä¸‹åˆ—寫法:
-
- use Encode::HanConvert;
- $euc_cn = big5_to_gb($big5); # 從 Big5 轉為 GBK
- $big5 = gb_to_big5($euc_cn); # 從 GBK 轉為 Big5
-
-=head2 進一步的資訊
-
-è«‹åƒè€ƒ Perl 內附的大é‡èªªæ˜Žæ–‡ä»¶ (ä¸å¹¸å…¨æ˜¯ç”¨è‹±æ–‡å¯«çš„), 來學習更多關於
-Perl 的知識, ä»¥åŠ Unicode 的使用方å¼. ä¸éŽ, 外部的資æºç›¸ç•¶è±å¯Œ:
-
-=head2 æä¾› Perl 資æºçš„網å€
-
-=over 4
-
-=item L<http://www.perl.com/>
-
-Perl çš„é¦–é  (ç”±æ­èŠç¦®å…¬å¸ç¶­è­·)
-
-=item L<http://www.cpan.org/>
-
-Perl 綜åˆå…¸è—網 (Comprehensive Perl Archive Network)
-
-=item L<http://lists.perl.org/>
-
-Perl 郵éžè«–壇一覽
-
-=back
-
-=head2 學習 Perl 的網å€
-
-=over 4
-
-=item L<http://www.oreilly.com.tw/product_perl.php?id=index_perl>
-
-正體中文版的æ­èŠç¦® Perl 書藉
-
-=item L<http://groups.google.com/groups?q=tw.bbs.comp.lang.perl>
-
-è‡ºç£ Perl é€£ç·šè¨Žè«–å€ (也就是å„大 BBS çš„ Perl 連線版)
-
-=back
-
-=head2 Perl 使用者集會
-
-=over 4
-
-=item L<http://www.pm.org/groups/taiwan.html>
-
-è‡ºç£ Perl 推廣組一覽
-
-=item L<irc://irc.freenode.org/#perl.tw>
-
-Perl.tw 線上èŠå¤©å®¤
-
-=back
-
-=head2 Unicode 相關網å€
-
-=over 4
-
-=item L<http://www.unicode.org/>
-
-Unicode 學術學會 (Unicode 標準的制定者)
-
-=item L<http://www.cl.cam.ac.uk/%7Emgk25/unicode.html>
-
-Unix/Linux 上的 UTF-8 åŠ Unicode 答客å•
-
-=back
-
-=head2 中文化資訊
-
-=over 4
-
-=item 中文化軟體è¯ç›Ÿ
-
-L<http://www.cpatch.org/>
-
-=item Linux 軟體中文化計劃
-
-L<http://www.linux.org.tw/CLDP/>
-
-=back
-
-=head1 SEE ALSO
-
-L<Encode>, L<Encode::TW>, L<encoding>, L<perluniintro>, L<perlunicode>
-
-=head1 AUTHORS
-
-Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>
-
-Audrey Tang (å”é³³) E<lt>audreyt@audreyt.orgE<gt>
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlunicode.pod b/Master/tlpkg/tlperl/lib/pods/perlunicode.pod
deleted file mode 100644
index 77daca34a7d..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlunicode.pod
+++ /dev/null
@@ -1,1826 +0,0 @@
-=head1 NAME
-
-perlunicode - Unicode support in Perl
-
-=head1 DESCRIPTION
-
-=head2 Important Caveats
-
-Unicode support is an extensive requirement. While Perl does not
-implement the Unicode standard or the accompanying technical reports
-from cover to cover, Perl does support many Unicode features.
-
-People who want to learn to use Unicode in Perl, should probably read
-the L<Perl Unicode tutorial, perlunitut|perlunitut> and
-L<perluniintro>, before reading
-this reference document.
-
-Also, the use of Unicode may present security issues that aren't obvious.
-Read L<Unicode Security Considerations|http://www.unicode.org/reports/tr36>.
-
-=over 4
-
-=item Safest if you "use feature 'unicode_strings'"
-
-In order to preserve backward compatibility, Perl does not turn
-on full internal Unicode support unless the pragma
-C<use feature 'unicode_strings'> is specified. (This is automatically
-selected if you use C<use 5.012> or higher.) Failure to do this can
-trigger unexpected surprises. See L</The "Unicode Bug"> below.
-
-This pragma doesn't affect I/O, and there are still several places
-where Unicode isn't fully supported, such as in filenames.
-
-=item Input and Output Layers
-
-Perl knows when a filehandle uses Perl's internal Unicode encodings
-(UTF-8, or UTF-EBCDIC if in EBCDIC) if the filehandle is opened with
-the ":encoding(utf8)" layer. Other encodings can be converted to Perl's
-encoding on input or from Perl's encoding on output by use of the
-":encoding(...)" layer. See L<open>.
-
-To indicate that Perl source itself is in UTF-8, use C<use utf8;>.
-
-=item C<use utf8> still needed to enable UTF-8/UTF-EBCDIC in scripts
-
-As a compatibility measure, the C<use utf8> pragma must be explicitly
-included to enable recognition of UTF-8 in the Perl scripts themselves
-(in string or regular expression literals, or in identifier names) on
-ASCII-based machines or to recognize UTF-EBCDIC on EBCDIC-based
-machines. B<These are the only times when an explicit C<use utf8>
-is needed.> See L<utf8>.
-
-=item BOM-marked scripts and UTF-16 scripts autodetected
-
-If a Perl script begins marked with the Unicode BOM (UTF-16LE, UTF16-BE,
-or UTF-8), or if the script looks like non-BOM-marked UTF-16 of either
-endianness, Perl will correctly read in the script as Unicode.
-(BOMless UTF-8 cannot be effectively recognized or differentiated from
-ISO 8859-1 or other eight-bit encodings.)
-
-=item C<use encoding> needed to upgrade non-Latin-1 byte strings
-
-By default, there is a fundamental asymmetry in Perl's Unicode model:
-implicit upgrading from byte strings to Unicode strings assumes that
-they were encoded in I<ISO 8859-1 (Latin-1)>, but Unicode strings are
-downgraded with UTF-8 encoding. This happens because the first 256
-codepoints in Unicode happens to agree with Latin-1.
-
-See L</"Byte and Character Semantics"> for more details.
-
-=back
-
-=head2 Byte and Character Semantics
-
-Beginning with version 5.6, Perl uses logically-wide characters to
-represent strings internally.
-
-Starting in Perl 5.14, Perl-level operations work with
-characters rather than bytes within the scope of a
-C<L<use feature 'unicode_strings'|feature>> (or equivalently
-C<use 5.012> or higher). (This is not true if bytes have been
-explicitly requested by C<L<use bytes|bytes>>, nor necessarily true
-for interactions with the platform's operating system.)
-
-For earlier Perls, and when C<unicode_strings> is not in effect, Perl
-provides a fairly safe environment that can handle both types of
-semantics in programs. For operations where Perl can unambiguously
-decide that the input data are characters, Perl switches to character
-semantics. For operations where this determination cannot be made
-without additional information from the user, Perl decides in favor of
-compatibility and chooses to use byte semantics.
-
-When C<use locale> (but not C<use locale ':not_characters'>) is in
-effect, Perl uses the semantics associated with the current locale.
-(C<use locale> overrides C<use feature 'unicode_strings'> in the same scope;
-while C<use locale ':not_characters'> effectively also selects
-C<use feature 'unicode_strings'> in its scope; see L<perllocale>.)
-Otherwise, Perl uses the platform's native
-byte semantics for characters whose code points are less than 256, and
-Unicode semantics for those greater than 255. On EBCDIC platforms, this
-is almost seamless, as the EBCDIC code pages that Perl handles are
-equivalent to Unicode's first 256 code points. (The exception is that
-EBCDIC regular expression case-insensitive matching rules are not as
-as robust as Unicode's.) But on ASCII platforms, Perl uses US-ASCII
-(or Basic Latin in Unicode terminology) byte semantics, meaning that characters
-whose ordinal numbers are in the range 128 - 255 are undefined except for their
-ordinal numbers. This means that none have case (upper and lower), nor are any
-a member of character classes, like C<[:alpha:]> or C<\w>. (But all do belong
-to the C<\W> class or the Perl regular expression extension C<[:^alpha:]>.)
-
-This behavior preserves compatibility with earlier versions of Perl,
-which allowed byte semantics in Perl operations only if
-none of the program's inputs were marked as being a source of Unicode
-character data. Such data may come from filehandles, from calls to
-external programs, from information provided by the system (such as %ENV),
-or from literals and constants in the source text.
-
-The C<utf8> pragma is primarily a compatibility device that enables
-recognition of UTF-(8|EBCDIC) in literals encountered by the parser.
-Note that this pragma is only required while Perl defaults to byte
-semantics; when character semantics become the default, this pragma
-may become a no-op. See L<utf8>.
-
-If strings operating under byte semantics and strings with Unicode
-character data are concatenated, the new string will have
-character semantics. This can cause surprises: See L</BUGS>, below.
-You can choose to be warned when this happens. See L<encoding::warnings>.
-
-Under character semantics, many operations that formerly operated on
-bytes now operate on characters. A character in Perl is
-logically just a number ranging from 0 to 2**31 or so. Larger
-characters may encode into longer sequences of bytes internally, but
-this internal detail is mostly hidden for Perl code.
-See L<perluniintro> for more.
-
-=head2 Effects of Character Semantics
-
-Character semantics have the following effects:
-
-=over 4
-
-=item *
-
-Strings--including hash keys--and regular expression patterns may
-contain characters that have an ordinal value larger than 255.
-
-If you use a Unicode editor to edit your program, Unicode characters may
-occur directly within the literal strings in UTF-8 encoding, or UTF-16.
-(The former requires a BOM or C<use utf8>, the latter requires a BOM.)
-
-Unicode characters can also be added to a string by using the C<\N{U+...}>
-notation. The Unicode code for the desired character, in hexadecimal,
-should be placed in the braces, after the C<U>. For instance, a smiley face is
-C<\N{U+263A}>.
-
-Alternatively, you can use the C<\x{...}> notation for characters 0x100 and
-above. For characters below 0x100 you may get byte semantics instead of
-character semantics; see L</The "Unicode Bug">. On EBCDIC machines there is
-the additional problem that the value for such characters gives the EBCDIC
-character rather than the Unicode one, thus it is more portable to use
-C<\N{U+...}> instead.
-
-Additionally, you can use the C<\N{...}> notation and put the official
-Unicode character name within the braces, such as
-C<\N{WHITE SMILING FACE}>. This automatically loads the L<charnames>
-module with the C<:full> and C<:short> options. If you prefer different
-options for this module, you can instead, before the C<\N{...}>,
-explicitly load it with your desired options; for example,
-
- use charnames ':loose';
-
-=item *
-
-If an appropriate L<encoding> is specified, identifiers within the
-Perl script may contain Unicode alphanumeric characters, including
-ideographs. Perl does not currently attempt to canonicalize variable
-names.
-
-=item *
-
-Regular expressions match characters instead of bytes. "." matches
-a character instead of a byte.
-
-=item *
-
-Bracketed character classes in regular expressions match characters instead of
-bytes and match against the character properties specified in the
-Unicode properties database. C<\w> can be used to match a Japanese
-ideograph, for instance.
-
-=item *
-
-Named Unicode properties, scripts, and block ranges may be used (like bracketed
-character classes) by using the C<\p{}> "matches property" construct and
-the C<\P{}> negation, "doesn't match property".
-See L</"Unicode Character Properties"> for more details.
-
-You can define your own character properties and use them
-in the regular expression with the C<\p{}> or C<\P{}> construct.
-See L</"User-Defined Character Properties"> for more details.
-
-=item *
-
-The special pattern C<\X> matches a logical character, an "extended grapheme
-cluster" in Standardese. In Unicode what appears to the user to be a single
-character, for example an accented C<G>, may in fact be composed of a sequence
-of characters, in this case a C<G> followed by an accent character. C<\X>
-will match the entire sequence.
-
-=item *
-
-The C<tr///> operator translates characters instead of bytes. Note
-that the C<tr///CU> functionality has been removed. For similar
-functionality see pack('U0', ...) and pack('C0', ...).
-
-=item *
-
-Case translation operators use the Unicode case translation tables
-when character input is provided. Note that C<uc()>, or C<\U> in
-interpolated strings, translates to uppercase, while C<ucfirst>,
-or C<\u> in interpolated strings, translates to titlecase in languages
-that make the distinction (which is equivalent to uppercase in languages
-without the distinction).
-
-=item *
-
-Most operators that deal with positions or lengths in a string will
-automatically switch to using character positions, including
-C<chop()>, C<chomp()>, C<substr()>, C<pos()>, C<index()>, C<rindex()>,
-C<sprintf()>, C<write()>, and C<length()>. An operator that
-specifically does not switch is C<vec()>. Operators that really don't
-care include operators that treat strings as a bucket of bits such as
-C<sort()>, and operators dealing with filenames.
-
-=item *
-
-The C<pack()>/C<unpack()> letter C<C> does I<not> change, since it is often
-used for byte-oriented formats. Again, think C<char> in the C language.
-
-There is a new C<U> specifier that converts between Unicode characters
-and code points. There is also a C<W> specifier that is the equivalent of
-C<chr>/C<ord> and properly handles character values even if they are above 255.
-
-=item *
-
-The C<chr()> and C<ord()> functions work on characters, similar to
-C<pack("W")> and C<unpack("W")>, I<not> C<pack("C")> and
-C<unpack("C")>. C<pack("C")> and C<unpack("C")> are methods for
-emulating byte-oriented C<chr()> and C<ord()> on Unicode strings.
-While these methods reveal the internal encoding of Unicode strings,
-that is not something one normally needs to care about at all.
-
-=item *
-
-The bit string operators, C<& | ^ ~>, can operate on character data.
-However, for backward compatibility, such as when using bit string
-operations when characters are all less than 256 in ordinal value, one
-should not use C<~> (the bit complement) with characters of both
-values less than 256 and values greater than 256. Most importantly,
-DeMorgan's laws (C<~($x|$y) eq ~$x&~$y> and C<~($x&$y) eq ~$x|~$y>)
-will not hold. The reason for this mathematical I<faux pas> is that
-the complement cannot return B<both> the 8-bit (byte-wide) bit
-complement B<and> the full character-wide bit complement.
-
-=item *
-
-There is a CPAN module, L<Unicode::Casing>, which allows you to define
-your own mappings to be used in C<lc()>, C<lcfirst()>, C<uc()>,
-C<ucfirst()>, and C<fc> (or their double-quoted string inlined
-versions such as C<\U>).
-(Prior to Perl 5.16, this functionality was partially provided
-in the Perl core, but suffered from a number of insurmountable
-drawbacks, so the CPAN module was written instead.)
-
-=back
-
-=over 4
-
-=item *
-
-And finally, C<scalar reverse()> reverses by character rather than by byte.
-
-=back
-
-=head2 Unicode Character Properties
-
-(The only time that Perl considers a sequence of individual code
-points as a single logical character is in the C<\X> construct, already
-mentioned above. Therefore "character" in this discussion means a single
-Unicode code point.)
-
-Very nearly all Unicode character properties are accessible through
-regular expressions by using the C<\p{}> "matches property" construct
-and the C<\P{}> "doesn't match property" for its negation.
-
-For instance, C<\p{Uppercase}> matches any single character with the Unicode
-"Uppercase" property, while C<\p{L}> matches any character with a
-General_Category of "L" (letter) property. Brackets are not
-required for single letter property names, so C<\p{L}> is equivalent to C<\pL>.
-
-More formally, C<\p{Uppercase}> matches any single character whose Unicode
-Uppercase property value is True, and C<\P{Uppercase}> matches any character
-whose Uppercase property value is False, and they could have been written as
-C<\p{Uppercase=True}> and C<\p{Uppercase=False}>, respectively.
-
-This formality is needed when properties are not binary; that is, if they can
-take on more values than just True and False. For example, the Bidi_Class (see
-L</"Bidirectional Character Types"> below), can take on several different
-values, such as Left, Right, Whitespace, and others. To match these, one needs
-to specify both the property name (Bidi_Class), AND the value being
-matched against
-(Left, Right, etc.). This is done, as in the examples above, by having the
-two components separated by an equal sign (or interchangeably, a colon), like
-C<\p{Bidi_Class: Left}>.
-
-All Unicode-defined character properties may be written in these compound forms
-of C<\p{property=value}> or C<\p{property:value}>, but Perl provides some
-additional properties that are written only in the single form, as well as
-single-form short-cuts for all binary properties and certain others described
-below, in which you may omit the property name and the equals or colon
-separator.
-
-Most Unicode character properties have at least two synonyms (or aliases if you
-prefer): a short one that is easier to type and a longer one that is more
-descriptive and hence easier to understand. Thus the "L" and "Letter" properties
-above are equivalent and can be used interchangeably. Likewise,
-"Upper" is a synonym for "Uppercase", and we could have written
-C<\p{Uppercase}> equivalently as C<\p{Upper}>. Also, there are typically
-various synonyms for the values the property can be. For binary properties,
-"True" has 3 synonyms: "T", "Yes", and "Y"; and "False has correspondingly "F",
-"No", and "N". But be careful. A short form of a value for one property may
-not mean the same thing as the same short form for another. Thus, for the
-General_Category property, "L" means "Letter", but for the Bidi_Class property,
-"L" means "Left". A complete list of properties and synonyms is in
-L<perluniprops>.
-
-Upper/lower case differences in property names and values are irrelevant;
-thus C<\p{Upper}> means the same thing as C<\p{upper}> or even C<\p{UpPeR}>.
-Similarly, you can add or subtract underscores anywhere in the middle of a
-word, so that these are also equivalent to C<\p{U_p_p_e_r}>. And white space
-is irrelevant adjacent to non-word characters, such as the braces and the equals
-or colon separators, so C<\p{ Upper }> and C<\p{ Upper_case : Y }> are
-equivalent to these as well. In fact, white space and even
-hyphens can usually be added or deleted anywhere. So even C<\p{ Up-per case = Yes}> is
-equivalent. All this is called "loose-matching" by Unicode. The few places
-where stricter matching is used is in the middle of numbers, and in the Perl
-extension properties that begin or end with an underscore. Stricter matching
-cares about white space (except adjacent to non-word characters),
-hyphens, and non-interior underscores.
-
-You can also use negation in both C<\p{}> and C<\P{}> by introducing a caret
-(^) between the first brace and the property name: C<\p{^Tamil}> is
-equal to C<\P{Tamil}>.
-
-Almost all properties are immune to case-insensitive matching. That is,
-adding a C</i> regular expression modifier does not change what they
-match. There are two sets that are affected.
-The first set is
-C<Uppercase_Letter>,
-C<Lowercase_Letter>,
-and C<Titlecase_Letter>,
-all of which match C<Cased_Letter> under C</i> matching.
-And the second set is
-C<Uppercase>,
-C<Lowercase>,
-and C<Titlecase>,
-all of which match C<Cased> under C</i> matching.
-This set also includes its subsets C<PosixUpper> and C<PosixLower> both
-of which under C</i> matching match C<PosixAlpha>.
-(The difference between these sets is that some things, such as Roman
-numerals, come in both upper and lower case so they are C<Cased>, but aren't considered
-letters, so they aren't C<Cased_Letter>s.)
-
-The result is undefined if you try to match a non-Unicode code point
-(that is, one above 0x10FFFF) against a Unicode property. Currently, a
-warning is raised, and the match will fail. In some cases, this is
-counterintuitive, as both these fail:
-
- chr(0x110000) =~ \p{ASCII_Hex_Digit=True} # Fails.
- chr(0x110000) =~ \p{ASCII_Hex_Digit=False} # Fails!
-
-=head3 B<General_Category>
-
-Every Unicode character is assigned a general category, which is the "most
-usual categorization of a character" (from
-L<http://www.unicode.org/reports/tr44>).
-
-The compound way of writing these is like C<\p{General_Category=Number}>
-(short, C<\p{gc:n}>). But Perl furnishes shortcuts in which everything up
-through the equal or colon separator is omitted. So you can instead just write
-C<\pN>.
-
-Here are the short and long forms of the General Category properties:
-
- Short Long
-
- L Letter
- LC, L& Cased_Letter (that is: [\p{Ll}\p{Lu}\p{Lt}])
- Lu Uppercase_Letter
- Ll Lowercase_Letter
- Lt Titlecase_Letter
- Lm Modifier_Letter
- Lo Other_Letter
-
- M Mark
- Mn Nonspacing_Mark
- Mc Spacing_Mark
- Me Enclosing_Mark
-
- N Number
- Nd Decimal_Number (also Digit)
- Nl Letter_Number
- No Other_Number
-
- P Punctuation (also Punct)
- Pc Connector_Punctuation
- Pd Dash_Punctuation
- Ps Open_Punctuation
- Pe Close_Punctuation
- Pi Initial_Punctuation
- (may behave like Ps or Pe depending on usage)
- Pf Final_Punctuation
- (may behave like Ps or Pe depending on usage)
- Po Other_Punctuation
-
- S Symbol
- Sm Math_Symbol
- Sc Currency_Symbol
- Sk Modifier_Symbol
- So Other_Symbol
-
- Z Separator
- Zs Space_Separator
- Zl Line_Separator
- Zp Paragraph_Separator
-
- C Other
- Cc Control (also Cntrl)
- Cf Format
- Cs Surrogate
- Co Private_Use
- Cn Unassigned
-
-Single-letter properties match all characters in any of the
-two-letter sub-properties starting with the same letter.
-C<LC> and C<L&> are special: both are aliases for the set consisting of everything matched by C<Ll>, C<Lu>, and C<Lt>.
-
-=head3 B<Bidirectional Character Types>
-
-Because scripts differ in their directionality (Hebrew and Arabic are
-written right to left, for example) Unicode supplies these properties in
-the Bidi_Class class:
-
- Property Meaning
-
- L Left-to-Right
- LRE Left-to-Right Embedding
- LRO Left-to-Right Override
- R Right-to-Left
- AL Arabic Letter
- RLE Right-to-Left Embedding
- RLO Right-to-Left Override
- PDF Pop Directional Format
- EN European Number
- ES European Separator
- ET European Terminator
- AN Arabic Number
- CS Common Separator
- NSM Non-Spacing Mark
- BN Boundary Neutral
- B Paragraph Separator
- S Segment Separator
- WS Whitespace
- ON Other Neutrals
-
-This property is always written in the compound form.
-For example, C<\p{Bidi_Class:R}> matches characters that are normally
-written right to left.
-
-=head3 B<Scripts>
-
-The world's languages are written in many different scripts. This sentence
-(unless you're reading it in translation) is written in Latin, while Russian is
-written in Cyrillic, and Greek is written in, well, Greek; Japanese mainly in
-Hiragana or Katakana. There are many more.
-
-The Unicode Script and Script_Extensions properties give what script a
-given character is in. Either property can be specified with the
-compound form like
-C<\p{Script=Hebrew}> (short: C<\p{sc=hebr}>), or
-C<\p{Script_Extensions=Javanese}> (short: C<\p{scx=java}>).
-In addition, Perl furnishes shortcuts for all
-C<Script> property names. You can omit everything up through the equals
-(or colon), and simply write C<\p{Latin}> or C<\P{Cyrillic}>.
-(This is not true for C<Script_Extensions>, which is required to be
-written in the compound form.)
-
-The difference between these two properties involves characters that are
-used in multiple scripts. For example the digits '0' through '9' are
-used in many parts of the world. These are placed in a script named
-C<Common>. Other characters are used in just a few scripts. For
-example, the "KATAKANA-HIRAGANA DOUBLE HYPHEN" is used in both Japanese
-scripts, Katakana and Hiragana, but nowhere else. The C<Script>
-property places all characters that are used in multiple scripts in the
-C<Common> script, while the C<Script_Extensions> property places those
-that are used in only a few scripts into each of those scripts; while
-still using C<Common> for those used in many scripts. Thus both these
-match:
-
- "0" =~ /\p{sc=Common}/ # Matches
- "0" =~ /\p{scx=Common}/ # Matches
-
-and only the first of these match:
-
- "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{sc=Common} # Matches
- "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{scx=Common} # No match
-
-And only the last two of these match:
-
- "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{sc=Hiragana} # No match
- "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{sc=Katakana} # No match
- "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{scx=Hiragana} # Matches
- "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{scx=Katakana} # Matches
-
-C<Script_Extensions> is thus an improved C<Script>, in which there are
-fewer characters in the C<Common> script, and correspondingly more in
-other scripts. It is new in Unicode version 6.0, and its data are likely
-to change significantly in later releases, as things get sorted out.
-
-(Actually, besides C<Common>, the C<Inherited> script, contains
-characters that are used in multiple scripts. These are modifier
-characters which modify other characters, and inherit the script value
-of the controlling character. Some of these are used in many scripts,
-and so go into C<Inherited> in both C<Script> and C<Script_Extensions>.
-Others are used in just a few scripts, so are in C<Inherited> in
-C<Script>, but not in C<Script_Extensions>.)
-
-It is worth stressing that there are several different sets of digits in
-Unicode that are equivalent to 0-9 and are matchable by C<\d> in a
-regular expression. If they are used in a single language only, they
-are in that language's C<Script> and C<Script_Extension>. If they are
-used in more than one script, they will be in C<sc=Common>, but only
-if they are used in many scripts should they be in C<scx=Common>.
-
-A complete list of scripts and their shortcuts is in L<perluniprops>.
-
-=head3 B<Use of "Is" Prefix>
-
-For backward compatibility (with Perl 5.6), all properties mentioned
-so far may have C<Is> or C<Is_> prepended to their name, so C<\P{Is_Lu}>, for
-example, is equal to C<\P{Lu}>, and C<\p{IsScript:Arabic}> is equal to
-C<\p{Arabic}>.
-
-=head3 B<Blocks>
-
-In addition to B<scripts>, Unicode also defines B<blocks> of
-characters. The difference between scripts and blocks is that the
-concept of scripts is closer to natural languages, while the concept
-of blocks is more of an artificial grouping based on groups of Unicode
-characters with consecutive ordinal values. For example, the "Basic Latin"
-block is all characters whose ordinals are between 0 and 127, inclusive; in
-other words, the ASCII characters. The "Latin" script contains some letters
-from this as well as several other blocks, like "Latin-1 Supplement",
-"Latin Extended-A", etc., but it does not contain all the characters from
-those blocks. It does not, for example, contain the digits 0-9, because
-those digits are shared across many scripts, and hence are in the
-C<Common> script.
-
-For more about scripts versus blocks, see UAX#24 "Unicode Script Property":
-L<http://www.unicode.org/reports/tr24>
-
-The C<Script> or C<Script_Extensions> properties are likely to be the
-ones you want to use when processing
-natural language; the Block property may occasionally be useful in working
-with the nuts and bolts of Unicode.
-
-Block names are matched in the compound form, like C<\p{Block: Arrows}> or
-C<\p{Blk=Hebrew}>. Unlike most other properties, only a few block names have a
-Unicode-defined short name. But Perl does provide a (slight) shortcut: You
-can say, for example C<\p{In_Arrows}> or C<\p{In_Hebrew}>. For backwards
-compatibility, the C<In> prefix may be omitted if there is no naming conflict
-with a script or any other property, and you can even use an C<Is> prefix
-instead in those cases. But it is not a good idea to do this, for a couple
-reasons:
-
-=over 4
-
-=item 1
-
-It is confusing. There are many naming conflicts, and you may forget some.
-For example, C<\p{Hebrew}> means the I<script> Hebrew, and NOT the I<block>
-Hebrew. But would you remember that 6 months from now?
-
-=item 2
-
-It is unstable. A new version of Unicode may pre-empt the current meaning by
-creating a property with the same name. There was a time in very early Unicode
-releases when C<\p{Hebrew}> would have matched the I<block> Hebrew; now it
-doesn't.
-
-=back
-
-Some people prefer to always use C<\p{Block: foo}> and C<\p{Script: bar}>
-instead of the shortcuts, whether for clarity, because they can't remember the
-difference between 'In' and 'Is' anyway, or they aren't confident that those who
-eventually will read their code will know that difference.
-
-A complete list of blocks and their shortcuts is in L<perluniprops>.
-
-=head3 B<Other Properties>
-
-There are many more properties than the very basic ones described here.
-A complete list is in L<perluniprops>.
-
-Unicode defines all its properties in the compound form, so all single-form
-properties are Perl extensions. Most of these are just synonyms for the
-Unicode ones, but some are genuine extensions, including several that are in
-the compound form. And quite a few of these are actually recommended by Unicode
-(in L<http://www.unicode.org/reports/tr18>).
-
-This section gives some details on all extensions that aren't just
-synonyms for compound-form Unicode properties
-(for those properties, you'll have to refer to the
-L<Unicode Standard|http://www.unicode.org/reports/tr44>.
-
-=over
-
-=item B<C<\p{All}>>
-
-This matches any of the 1_114_112 Unicode code points. It is a synonym for
-C<\p{Any}>.
-
-=item B<C<\p{Alnum}>>
-
-This matches any C<\p{Alphabetic}> or C<\p{Decimal_Number}> character.
-
-=item B<C<\p{Any}>>
-
-This matches any of the 1_114_112 Unicode code points. It is a synonym for
-C<\p{All}>.
-
-=item B<C<\p{ASCII}>>
-
-This matches any of the 128 characters in the US-ASCII character set,
-which is a subset of Unicode.
-
-=item B<C<\p{Assigned}>>
-
-This matches any assigned code point; that is, any code point whose general
-category is not Unassigned (or equivalently, not Cn).
-
-=item B<C<\p{Blank}>>
-
-This is the same as C<\h> and C<\p{HorizSpace}>: A character that changes the
-spacing horizontally.
-
-=item B<C<\p{Decomposition_Type: Non_Canonical}>> (Short: C<\p{Dt=NonCanon}>)
-
-Matches a character that has a non-canonical decomposition.
-
-To understand the use of this rarely used property=value combination, it is
-necessary to know some basics about decomposition.
-Consider a character, say H. It could appear with various marks around it,
-such as an acute accent, or a circumflex, or various hooks, circles, arrows,
-I<etc.>, above, below, to one side or the other, etc. There are many
-possibilities among the world's languages. The number of combinations is
-astronomical, and if there were a character for each combination, it would
-soon exhaust Unicode's more than a million possible characters. So Unicode
-took a different approach: there is a character for the base H, and a
-character for each of the possible marks, and these can be variously combined
-to get a final logical character. So a logical character--what appears to be a
-single character--can be a sequence of more than one individual characters.
-This is called an "extended grapheme cluster"; Perl furnishes the C<\X>
-regular expression construct to match such sequences.
-
-But Unicode's intent is to unify the existing character set standards and
-practices, and several pre-existing standards have single characters that
-mean the same thing as some of these combinations. An example is ISO-8859-1,
-which has quite a few of these in the Latin-1 range, an example being "LATIN
-CAPITAL LETTER E WITH ACUTE". Because this character was in this pre-existing
-standard, Unicode added it to its repertoire. But this character is considered
-by Unicode to be equivalent to the sequence consisting of the character
-"LATIN CAPITAL LETTER E" followed by the character "COMBINING ACUTE ACCENT".
-
-"LATIN CAPITAL LETTER E WITH ACUTE" is called a "pre-composed" character, and
-its equivalence with the sequence is called canonical equivalence. All
-pre-composed characters are said to have a decomposition (into the equivalent
-sequence), and the decomposition type is also called canonical.
-
-However, many more characters have a different type of decomposition, a
-"compatible" or "non-canonical" decomposition. The sequences that form these
-decompositions are not considered canonically equivalent to the pre-composed
-character. An example, again in the Latin-1 range, is the "SUPERSCRIPT ONE".
-It is somewhat like a regular digit 1, but not exactly; its decomposition
-into the digit 1 is called a "compatible" decomposition, specifically a
-"super" decomposition. There are several such compatibility
-decompositions (see L<http://www.unicode.org/reports/tr44>), including one
-called "compat", which means some miscellaneous type of decomposition
-that doesn't fit into the decomposition categories that Unicode has chosen.
-
-Note that most Unicode characters don't have a decomposition, so their
-decomposition type is "None".
-
-For your convenience, Perl has added the C<Non_Canonical> decomposition
-type to mean any of the several compatibility decompositions.
-
-=item B<C<\p{Graph}>>
-
-Matches any character that is graphic. Theoretically, this means a character
-that on a printer would cause ink to be used.
-
-=item B<C<\p{HorizSpace}>>
-
-This is the same as C<\h> and C<\p{Blank}>: a character that changes the
-spacing horizontally.
-
-=item B<C<\p{In=*}>>
-
-This is a synonym for C<\p{Present_In=*}>
-
-=item B<C<\p{PerlSpace}>>
-
-This is the same as C<\s>, restricted to ASCII, namely C<S<[ \f\n\r\t]>>.
-
-Mnemonic: Perl's (original) space
-
-=item B<C<\p{PerlWord}>>
-
-This is the same as C<\w>, restricted to ASCII, namely C<[A-Za-z0-9_]>
-
-Mnemonic: Perl's (original) word.
-
-=item B<C<\p{Posix...}>>
-
-There are several of these, which are equivalents using the C<\p>
-notation for Posix classes and are described in
-L<perlrecharclass/POSIX Character Classes>.
-
-=item B<C<\p{Present_In: *}>> (Short: C<\p{In=*}>)
-
-This property is used when you need to know in what Unicode version(s) a
-character is.
-
-The "*" above stands for some two digit Unicode version number, such as
-C<1.1> or C<4.0>; or the "*" can also be C<Unassigned>. This property will
-match the code points whose final disposition has been settled as of the
-Unicode release given by the version number; C<\p{Present_In: Unassigned}>
-will match those code points whose meaning has yet to be assigned.
-
-For example, C<U+0041> "LATIN CAPITAL LETTER A" was present in the very first
-Unicode release available, which is C<1.1>, so this property is true for all
-valid "*" versions. On the other hand, C<U+1EFF> was not assigned until version
-5.1 when it became "LATIN SMALL LETTER Y WITH LOOP", so the only "*" that
-would match it are 5.1, 5.2, and later.
-
-Unicode furnishes the C<Age> property from which this is derived. The problem
-with Age is that a strict interpretation of it (which Perl takes) has it
-matching the precise release a code point's meaning is introduced in. Thus
-C<U+0041> would match only 1.1; and C<U+1EFF> only 5.1. This is not usually what
-you want.
-
-Some non-Perl implementations of the Age property may change its meaning to be
-the same as the Perl Present_In property; just be aware of that.
-
-Another confusion with both these properties is that the definition is not
-that the code point has been I<assigned>, but that the meaning of the code point
-has been I<determined>. This is because 66 code points will always be
-unassigned, and so the Age for them is the Unicode version in which the decision
-to make them so was made. For example, C<U+FDD0> is to be permanently
-unassigned to a character, and the decision to do that was made in version 3.1,
-so C<\p{Age=3.1}> matches this character, as also does C<\p{Present_In: 3.1}> and up.
-
-=item B<C<\p{Print}>>
-
-This matches any character that is graphical or blank, except controls.
-
-=item B<C<\p{SpacePerl}>>
-
-This is the same as C<\s>, including beyond ASCII.
-
-Mnemonic: Space, as modified by Perl. (It doesn't include the vertical tab
-which both the Posix standard and Unicode consider white space.)
-
-=item B<C<\p{Title}>> and B<C<\p{Titlecase}>>
-
-Under case-sensitive matching, these both match the same code points as
-C<\p{General Category=Titlecase_Letter}> (C<\p{gc=lt}>). The difference
-is that under C</i> caseless matching, these match the same as
-C<\p{Cased}>, whereas C<\p{gc=lt}> matches C<\p{Cased_Letter>).
-
-=item B<C<\p{VertSpace}>>
-
-This is the same as C<\v>: A character that changes the spacing vertically.
-
-=item B<C<\p{Word}>>
-
-This is the same as C<\w>, including over 100_000 characters beyond ASCII.
-
-=item B<C<\p{XPosix...}>>
-
-There are several of these, which are the standard Posix classes
-extended to the full Unicode range. They are described in
-L<perlrecharclass/POSIX Character Classes>.
-
-=back
-
-=head2 User-Defined Character Properties
-
-You can define your own binary character properties by defining subroutines
-whose names begin with "In" or "Is". The subroutines can be defined in any
-package. The user-defined properties can be used in the regular expression
-C<\p> and C<\P> constructs; if you are using a user-defined property from a
-package other than the one you are in, you must specify its package in the
-C<\p> or C<\P> construct.
-
- # assuming property Is_Foreign defined in Lang::
- package main; # property package name required
- if ($txt =~ /\p{Lang::IsForeign}+/) { ... }
-
- package Lang; # property package name not required
- if ($txt =~ /\p{IsForeign}+/) { ... }
-
-
-Note that the effect is compile-time and immutable once defined.
-However, the subroutines are passed a single parameter, which is 0 if
-case-sensitive matching is in effect and non-zero if caseless matching
-is in effect. The subroutine may return different values depending on
-the value of the flag, and one set of values will immutably be in effect
-for all case-sensitive matches, and the other set for all case-insensitive
-matches.
-
-Note that if the regular expression is tainted, then Perl will die rather
-than calling the subroutine, where the name of the subroutine is
-determined by the tainted data.
-
-The subroutines must return a specially-formatted string, with one
-or more newline-separated lines. Each line must be one of the following:
-
-=over 4
-
-=item *
-
-A single hexadecimal number denoting a Unicode code point to include.
-
-=item *
-
-Two hexadecimal numbers separated by horizontal whitespace (space or
-tabular characters) denoting a range of Unicode code points to include.
-
-=item *
-
-Something to include, prefixed by "+": a built-in character
-property (prefixed by "utf8::") or a fully qualified (including package
-name) user-defined character property,
-to represent all the characters in that property; two hexadecimal code
-points for a range; or a single hexadecimal code point.
-
-=item *
-
-Something to exclude, prefixed by "-": an existing character
-property (prefixed by "utf8::") or a fully qualified (including package
-name) user-defined character property,
-to represent all the characters in that property; two hexadecimal code
-points for a range; or a single hexadecimal code point.
-
-=item *
-
-Something to negate, prefixed "!": an existing character
-property (prefixed by "utf8::") or a fully qualified (including package
-name) user-defined character property,
-to represent all the characters in that property; two hexadecimal code
-points for a range; or a single hexadecimal code point.
-
-=item *
-
-Something to intersect with, prefixed by "&": an existing character
-property (prefixed by "utf8::") or a fully qualified (including package
-name) user-defined character property,
-for all the characters except the characters in the property; two
-hexadecimal code points for a range; or a single hexadecimal code point.
-
-=back
-
-For example, to define a property that covers both the Japanese
-syllabaries (hiragana and katakana), you can define
-
- sub InKana {
- return <<END;
- 3040\t309F
- 30A0\t30FF
- END
- }
-
-Imagine that the here-doc end marker is at the beginning of the line.
-Now you can use C<\p{InKana}> and C<\P{InKana}>.
-
-You could also have used the existing block property names:
-
- sub InKana {
- return <<'END';
- +utf8::InHiragana
- +utf8::InKatakana
- END
- }
-
-Suppose you wanted to match only the allocated characters,
-not the raw block ranges: in other words, you want to remove
-the non-characters:
-
- sub InKana {
- return <<'END';
- +utf8::InHiragana
- +utf8::InKatakana
- -utf8::IsCn
- END
- }
-
-The negation is useful for defining (surprise!) negated classes.
-
- sub InNotKana {
- return <<'END';
- !utf8::InHiragana
- -utf8::InKatakana
- +utf8::IsCn
- END
- }
-
-This will match all non-Unicode code points, since every one of them is
-not in Kana. You can use intersection to exclude these, if desired, as
-this modified example shows:
-
- sub InNotKana {
- return <<'END';
- !utf8::InHiragana
- -utf8::InKatakana
- +utf8::IsCn
- &utf8::Any
- END
- }
-
-C<&utf8::Any> must be the last line in the definition.
-
-Intersection is used generally for getting the common characters matched
-by two (or more) classes. It's important to remember not to use "&" for
-the first set; that would be intersecting with nothing, resulting in an
-empty set.
-
-(Note that official Unicode properties differ from these in that they
-automatically exclude non-Unicode code points and a warning is raised if
-a match is attempted on one of those.)
-
-=head2 User-Defined Case Mappings (for serious hackers only)
-
-B<This feature has been removed as of Perl 5.16.>
-The CPAN module L<Unicode::Casing> provides better functionality without
-the drawbacks that this feature had. If you are using a Perl earlier
-than 5.16, this feature was most fully documented in the 5.14 version of
-this pod:
-L<http://perldoc.perl.org/5.14.0/perlunicode.html#User-Defined-Case-Mappings-%28for-serious-hackers-only%29>
-
-=head2 Character Encodings for Input and Output
-
-See L<Encode>.
-
-=head2 Unicode Regular Expression Support Level
-
-The following list of Unicode supported features for regular expressions describes
-all features currently directly supported by core Perl. The references to "Level N"
-and the section numbers refer to the Unicode Technical Standard #18,
-"Unicode Regular Expressions", version 13, from August 2008.
-
-=over 4
-
-=item *
-
-Level 1 - Basic Unicode Support
-
- RL1.1 Hex Notation - done [1]
- RL1.2 Properties - done [2][3]
- RL1.2a Compatibility Properties - done [4]
- RL1.3 Subtraction and Intersection - MISSING [5]
- RL1.4 Simple Word Boundaries - done [6]
- RL1.5 Simple Loose Matches - done [7]
- RL1.6 Line Boundaries - MISSING [8][9]
- RL1.7 Supplementary Code Points - done [10]
-
- [1] \x{...}
- [2] \p{...} \P{...}
- [3] supports not only minimal list, but all Unicode character
- properties (see Unicode Character Properties above)
- [4] \d \D \s \S \w \W \X [:prop:] [:^prop:]
- [5] can use regular expression look-ahead [a] or
- user-defined character properties [b] to emulate set
- operations
- [6] \b \B
- [7] note that Perl does Full case-folding in matching (but with
- bugs), not Simple: for example U+1F88 is equivalent to
- U+1F00 U+03B9, instead of just U+1F80. This difference
- matters mainly for certain Greek capital letters with certain
- modifiers: the Full case-folding decomposes the letter,
- while the Simple case-folding would map it to a single
- character.
- [8] should do ^ and $ also on U+000B (\v in C), FF (\f), CR
- (\r), CRLF (\r\n), NEL (U+0085), LS (U+2028), and PS
- (U+2029); should also affect <>, $., and script line
- numbers; should not split lines within CRLF [c] (i.e. there
- is no empty line between \r and \n)
- [9] Linebreaking conformant with UAX#14 "Unicode Line Breaking
- Algorithm" is available through the Unicode::LineBreaking
- module.
- [10] UTF-8/UTF-EBDDIC used in Perl allows not only U+10000 to
- U+10FFFF but also beyond U+10FFFF
-
-[a] You can mimic class subtraction using lookahead.
-For example, what UTS#18 might write as
-
- [{Greek}-[{UNASSIGNED}]]
-
-in Perl can be written as:
-
- (?!\p{Unassigned})\p{InGreekAndCoptic}
- (?=\p{Assigned})\p{InGreekAndCoptic}
-
-But in this particular example, you probably really want
-
- \p{GreekAndCoptic}
-
-which will match assigned characters known to be part of the Greek script.
-
-Also see the L<Unicode::Regex::Set> module; it does implement the full
-UTS#18 grouping, intersection, union, and removal (subtraction) syntax.
-
-[b] '+' for union, '-' for removal (set-difference), '&' for intersection
-(see L</"User-Defined Character Properties">)
-
-[c] Try the C<:crlf> layer (see L<PerlIO>).
-
-=item *
-
-Level 2 - Extended Unicode Support
-
- RL2.1 Canonical Equivalents - MISSING [10][11]
- RL2.2 Default Grapheme Clusters - MISSING [12]
- RL2.3 Default Word Boundaries - MISSING [14]
- RL2.4 Default Loose Matches - MISSING [15]
- RL2.5 Name Properties - DONE
- RL2.6 Wildcard Properties - MISSING
-
- [10] see UAX#15 "Unicode Normalization Forms"
- [11] have Unicode::Normalize but not integrated to regexes
- [12] have \X but we don't have a "Grapheme Cluster Mode"
- [14] see UAX#29, Word Boundaries
- [15] This is covered in Chapter 3.13 (in Unicode 6.0)
-
-=item *
-
-Level 3 - Tailored Support
-
- RL3.1 Tailored Punctuation - MISSING
- RL3.2 Tailored Grapheme Clusters - MISSING [17][18]
- RL3.3 Tailored Word Boundaries - MISSING
- RL3.4 Tailored Loose Matches - MISSING
- RL3.5 Tailored Ranges - MISSING
- RL3.6 Context Matching - MISSING [19]
- RL3.7 Incremental Matches - MISSING
- ( RL3.8 Unicode Set Sharing )
- RL3.9 Possible Match Sets - MISSING
- RL3.10 Folded Matching - MISSING [20]
- RL3.11 Submatchers - MISSING
-
- [17] see UAX#10 "Unicode Collation Algorithms"
- [18] have Unicode::Collate but not integrated to regexes
- [19] have (?<=x) and (?=x), but look-aheads or look-behinds
- should see outside of the target substring
- [20] need insensitive matching for linguistic features other
- than case; for example, hiragana to katakana, wide and
- narrow, simplified Han to traditional Han (see UTR#30
- "Character Foldings")
-
-=back
-
-=head2 Unicode Encodings
-
-Unicode characters are assigned to I<code points>, which are abstract
-numbers. To use these numbers, various encodings are needed.
-
-=over 4
-
-=item *
-
-UTF-8
-
-UTF-8 is a variable-length (1 to 4 bytes), byte-order independent
-encoding. For ASCII (and we really do mean 7-bit ASCII, not another
-8-bit encoding), UTF-8 is transparent.
-
-The following table is from Unicode 3.2.
-
- Code Points 1st Byte 2nd Byte 3rd Byte 4th Byte
-
- U+0000..U+007F 00..7F
- U+0080..U+07FF * C2..DF 80..BF
- U+0800..U+0FFF E0 * A0..BF 80..BF
- U+1000..U+CFFF E1..EC 80..BF 80..BF
- U+D000..U+D7FF ED 80..9F 80..BF
- U+D800..U+DFFF +++++ utf16 surrogates, not legal utf8 +++++
- U+E000..U+FFFF EE..EF 80..BF 80..BF
- U+10000..U+3FFFF F0 * 90..BF 80..BF 80..BF
- U+40000..U+FFFFF F1..F3 80..BF 80..BF 80..BF
- U+100000..U+10FFFF F4 80..8F 80..BF 80..BF
-
-Note the gaps marked by "*" before several of the byte entries above. These are
-caused by legal UTF-8 avoiding non-shortest encodings: it is technically
-possible to UTF-8-encode a single code point in different ways, but that is
-explicitly forbidden, and the shortest possible encoding should always be used
-(and that is what Perl does).
-
-Another way to look at it is via bits:
-
- Code Points 1st Byte 2nd Byte 3rd Byte 4th Byte
-
- 0aaaaaaa 0aaaaaaa
- 00000bbbbbaaaaaa 110bbbbb 10aaaaaa
- ccccbbbbbbaaaaaa 1110cccc 10bbbbbb 10aaaaaa
- 00000dddccccccbbbbbbaaaaaa 11110ddd 10cccccc 10bbbbbb 10aaaaaa
-
-As you can see, the continuation bytes all begin with "10", and the
-leading bits of the start byte tell how many bytes there are in the
-encoded character.
-
-The original UTF-8 specification allowed up to 6 bytes, to allow
-encoding of numbers up to 0x7FFF_FFFF. Perl continues to allow those,
-and has extended that up to 13 bytes to encode code points up to what
-can fit in a 64-bit word. However, Perl will warn if you output any of
-these as being non-portable; and under strict UTF-8 input protocols,
-they are forbidden.
-
-The Unicode non-character code points are also disallowed in UTF-8 in
-"open interchange". See L</Non-character code points>.
-
-=item *
-
-UTF-EBCDIC
-
-Like UTF-8 but EBCDIC-safe, in the way that UTF-8 is ASCII-safe.
-
-=item *
-
-UTF-16, UTF-16BE, UTF-16LE, Surrogates, and BOMs (Byte Order Marks)
-
-The followings items are mostly for reference and general Unicode
-knowledge, Perl doesn't use these constructs internally.
-
-Like UTF-8, UTF-16 is a variable-width encoding, but where
-UTF-8 uses 8-bit code units, UTF-16 uses 16-bit code units.
-All code points occupy either 2 or 4 bytes in UTF-16: code points
-C<U+0000..U+FFFF> are stored in a single 16-bit unit, and code
-points C<U+10000..U+10FFFF> in two 16-bit units. The latter case is
-using I<surrogates>, the first 16-bit unit being the I<high
-surrogate>, and the second being the I<low surrogate>.
-
-Surrogates are code points set aside to encode the C<U+10000..U+10FFFF>
-range of Unicode code points in pairs of 16-bit units. The I<high
-surrogates> are the range C<U+D800..U+DBFF> and the I<low surrogates>
-are the range C<U+DC00..U+DFFF>. The surrogate encoding is
-
- $hi = ($uni - 0x10000) / 0x400 + 0xD800;
- $lo = ($uni - 0x10000) % 0x400 + 0xDC00;
-
-and the decoding is
-
- $uni = 0x10000 + ($hi - 0xD800) * 0x400 + ($lo - 0xDC00);
-
-Because of the 16-bitness, UTF-16 is byte-order dependent. UTF-16
-itself can be used for in-memory computations, but if storage or
-transfer is required either UTF-16BE (big-endian) or UTF-16LE
-(little-endian) encodings must be chosen.
-
-This introduces another problem: what if you just know that your data
-is UTF-16, but you don't know which endianness? Byte Order Marks, or
-BOMs, are a solution to this. A special character has been reserved
-in Unicode to function as a byte order marker: the character with the
-code point C<U+FEFF> is the BOM.
-
-The trick is that if you read a BOM, you will know the byte order,
-since if it was written on a big-endian platform, you will read the
-bytes C<0xFE 0xFF>, but if it was written on a little-endian platform,
-you will read the bytes C<0xFF 0xFE>. (And if the originating platform
-was writing in UTF-8, you will read the bytes C<0xEF 0xBB 0xBF>.)
-
-The way this trick works is that the character with the code point
-C<U+FFFE> is not supposed to be in input streams, so the
-sequence of bytes C<0xFF 0xFE> is unambiguously "BOM, represented in
-little-endian format" and cannot be C<U+FFFE>, represented in big-endian
-format".
-
-Surrogates have no meaning in Unicode outside their use in pairs to
-represent other code points. However, Perl allows them to be
-represented individually internally, for example by saying
-C<chr(0xD801)>, so that all code points, not just those valid for open
-interchange, are
-representable. Unicode does define semantics for them, such as their
-General Category is "Cs". But because their use is somewhat dangerous,
-Perl will warn (using the warning category "surrogate", which is a
-sub-category of "utf8") if an attempt is made
-to do things like take the lower case of one, or match
-case-insensitively, or to output them. (But don't try this on Perls
-before 5.14.)
-
-=item *
-
-UTF-32, UTF-32BE, UTF-32LE
-
-The UTF-32 family is pretty much like the UTF-16 family, expect that
-the units are 32-bit, and therefore the surrogate scheme is not
-needed. UTF-32 is a fixed-width encoding. The BOM signatures are
-C<0x00 0x00 0xFE 0xFF> for BE and C<0xFF 0xFE 0x00 0x00> for LE.
-
-=item *
-
-UCS-2, UCS-4
-
-Legacy, fixed-width encodings defined by the ISO 10646 standard. UCS-2 is a 16-bit
-encoding. Unlike UTF-16, UCS-2 is not extensible beyond C<U+FFFF>,
-because it does not use surrogates. UCS-4 is a 32-bit encoding,
-functionally identical to UTF-32 (the difference being that
-UCS-4 forbids neither surrogates nor code points larger than 0x10_FFFF).
-
-=item *
-
-UTF-7
-
-A seven-bit safe (non-eight-bit) encoding, which is useful if the
-transport or storage is not eight-bit safe. Defined by RFC 2152.
-
-=back
-
-=head2 Non-character code points
-
-66 code points are set aside in Unicode as "non-character code points".
-These all have the Unassigned (Cn) General Category, and they never will
-be assigned. These are never supposed to be in legal Unicode input
-streams, so that code can use them as sentinels that can be mixed in
-with character data, and they always will be distinguishable from that data.
-To keep them out of Perl input streams, strict UTF-8 should be
-specified, such as by using the layer C<:encoding('UTF-8')>. The
-non-character code points are the 32 between U+FDD0 and U+FDEF, and the
-34 code points U+FFFE, U+FFFF, U+1FFFE, U+1FFFF, ... U+10FFFE, U+10FFFF.
-Some people are under the mistaken impression that these are "illegal",
-but that is not true. An application or cooperating set of applications
-can legally use them at will internally; but these code points are
-"illegal for open interchange". Therefore, Perl will not accept these
-from input streams unless lax rules are being used, and will warn
-(using the warning category "nonchar", which is a sub-category of "utf8") if
-an attempt is made to output them.
-
-=head2 Beyond Unicode code points
-
-The maximum Unicode code point is U+10FFFF. But Perl accepts code
-points up to the maximum permissible unsigned number available on the
-platform. However, Perl will not accept these from input streams unless
-lax rules are being used, and will warn (using the warning category
-"non_unicode", which is a sub-category of "utf8") if an attempt is made to
-operate on or output them. For example, C<uc(0x11_0000)> will generate
-this warning, returning the input parameter as its result, as the upper
-case of every non-Unicode code point is the code point itself.
-
-=head2 Security Implications of Unicode
-
-Read L<Unicode Security Considerations|http://www.unicode.org/reports/tr36>.
-Also, note the following:
-
-=over 4
-
-=item *
-
-Malformed UTF-8
-
-Unfortunately, the original specification of UTF-8 leaves some room for
-interpretation of how many bytes of encoded output one should generate
-from one input Unicode character. Strictly speaking, the shortest
-possible sequence of UTF-8 bytes should be generated,
-because otherwise there is potential for an input buffer overflow at
-the receiving end of a UTF-8 connection. Perl always generates the
-shortest length UTF-8, and with warnings on, Perl will warn about
-non-shortest length UTF-8 along with other malformations, such as the
-surrogates, which are not Unicode code points valid for interchange.
-
-=item *
-
-Regular expression pattern matching may surprise you if you're not
-accustomed to Unicode. Starting in Perl 5.14, several pattern
-modifiers are available to control this, called the character set
-modifiers. Details are given in L<perlre/Character set modifiers>.
-
-=back
-
-As discussed elsewhere, Perl has one foot (two hooves?) planted in
-each of two worlds: the old world of bytes and the new world of
-characters, upgrading from bytes to characters when necessary.
-If your legacy code does not explicitly use Unicode, no automatic
-switch-over to characters should happen. Characters shouldn't get
-downgraded to bytes, either. It is possible to accidentally mix bytes
-and characters, however (see L<perluniintro>), in which case C<\w> in
-regular expressions might start behaving differently (unless the C</a>
-modifier is in effect). Review your code. Use warnings and the C<strict> pragma.
-
-=head2 Unicode in Perl on EBCDIC
-
-The way Unicode is handled on EBCDIC platforms is still
-experimental. On such platforms, references to UTF-8 encoding in this
-document and elsewhere should be read as meaning the UTF-EBCDIC
-specified in Unicode Technical Report 16, unless ASCII vs. EBCDIC issues
-are specifically discussed. There is no C<utfebcdic> pragma or
-":utfebcdic" layer; rather, "utf8" and ":utf8" are reused to mean
-the platform's "natural" 8-bit encoding of Unicode. See L<perlebcdic>
-for more discussion of the issues.
-
-=head2 Locales
-
-See L<perllocale/Unicode and UTF-8>
-
-=head2 When Unicode Does Not Happen
-
-While Perl does have extensive ways to input and output in Unicode,
-and a few other "entry points" like the @ARGV array (which can sometimes be
-interpreted as UTF-8), there are still many places where Unicode
-(in some encoding or another) could be given as arguments or received as
-results, or both, but it is not.
-
-The following are such interfaces. Also, see L</The "Unicode Bug">.
-For all of these interfaces Perl
-currently (as of 5.8.3) simply assumes byte strings both as arguments
-and results, or UTF-8 strings if the (problematic) C<encoding> pragma has been used.
-
-One reason that Perl does not attempt to resolve the role of Unicode in
-these situations is that the answers are highly dependent on the operating
-system and the file system(s). For example, whether filenames can be
-in Unicode and in exactly what kind of encoding, is not exactly a
-portable concept. Similarly for C<qx> and C<system>: how well will the
-"command-line interface" (and which of them?) handle Unicode?
-
-=over 4
-
-=item *
-
-chdir, chmod, chown, chroot, exec, link, lstat, mkdir,
-rename, rmdir, stat, symlink, truncate, unlink, utime, -X
-
-=item *
-
-%ENV
-
-=item *
-
-glob (aka the <*>)
-
-=item *
-
-open, opendir, sysopen
-
-=item *
-
-qx (aka the backtick operator), system
-
-=item *
-
-readdir, readlink
-
-=back
-
-=head2 The "Unicode Bug"
-
-The term, "Unicode bug" has been applied to an inconsistency
-on ASCII platforms with the
-Unicode code points in the Latin-1 Supplement block, that
-is, between 128 and 255. Without a locale specified, unlike all other
-characters or code points, these characters have very different semantics in
-byte semantics versus character semantics, unless
-C<use feature 'unicode_strings'> is specified, directly or indirectly.
-(It is indirectly specified by a C<use v5.12> or higher.)
-
-In character semantics these upper-Latin1 characters are interpreted as
-Unicode code points, which means
-they have the same semantics as Latin-1 (ISO-8859-1).
-
-In byte semantics (without C<unicode_strings>), they are considered to
-be unassigned characters, meaning that the only semantics they have is
-their ordinal numbers, and that they are
-not members of various character classes. None are considered to match C<\w>
-for example, but all match C<\W>.
-
-Perl 5.12.0 added C<unicode_strings> to force character semantics on
-these code points in some circumstances, which fixed portions of the
-bug; Perl 5.14.0 fixed almost all of it; and Perl 5.16.0 fixed the
-remainder (so far as we know, anyway). The lesson here is to enable
-C<unicode_strings> to avoid the headaches described below.
-
-The old, problematic behavior affects these areas:
-
-=over 4
-
-=item *
-
-Changing the case of a scalar, that is, using C<uc()>, C<ucfirst()>, C<lc()>,
-and C<lcfirst()>, or C<\L>, C<\U>, C<\u> and C<\l> in double-quotish
-contexts, such as regular expression substitutions.
-Under C<unicode_strings> starting in Perl 5.12.0, character semantics are
-generally used. See L<perlfunc/lc> for details on how this works
-in combination with various other pragmas.
-
-=item *
-
-Using caseless (C</i>) regular expression matching.
-Starting in Perl 5.14.0, regular expressions compiled within
-the scope of C<unicode_strings> use character semantics
-even when executed or compiled into larger
-regular expressions outside the scope.
-
-=item *
-
-Matching any of several properties in regular expressions, namely C<\b>,
-C<\B>, C<\s>, C<\S>, C<\w>, C<\W>, and all the Posix character classes
-I<except> C<[[:ascii:]]>.
-Starting in Perl 5.14.0, regular expressions compiled within
-the scope of C<unicode_strings> use character semantics
-even when executed or compiled into larger
-regular expressions outside the scope.
-
-=item *
-
-In C<quotemeta> or its inline equivalent C<\Q>, no code points above 127
-are quoted in UTF-8 encoded strings, but in byte encoded strings, code
-points between 128-255 are always quoted.
-Starting in Perl 5.16.0, consistent quoting rules are used within the
-scope of C<unicode_strings>, as described in L<perlfunc/quotemeta>.
-
-=back
-
-This behavior can lead to unexpected results in which a string's semantics
-suddenly change if a code point above 255 is appended to or removed from it,
-which changes the string's semantics from byte to character or vice versa. As
-an example, consider the following program and its output:
-
- $ perl -le'
- no feature 'unicode_strings';
- $s1 = "\xC2";
- $s2 = "\x{2660}";
- for ($s1, $s2, $s1.$s2) {
- print /\w/ || 0;
- }
- '
- 0
- 0
- 1
-
-If there's no C<\w> in C<s1> or in C<s2>, why does their concatenation have one?
-
-This anomaly stems from Perl's attempt to not disturb older programs that
-didn't use Unicode, and hence had no semantics for characters outside of the
-ASCII range (except in a locale), along with Perl's desire to add Unicode
-support seamlessly. The result wasn't seamless: these characters were
-orphaned.
-
-For Perls earlier than those described above, or when a string is passed
-to a function outside the subpragma's scope, a workaround is to always
-call C<utf8::upgrade($string)>,
-or to use the standard module L<Encode>. Also, a scalar that has any characters
-whose ordinal is above 0x100, or which were specified using either of the
-C<\N{...}> notations, will automatically have character semantics.
-
-=head2 Forcing Unicode in Perl (Or Unforcing Unicode in Perl)
-
-Sometimes (see L</"When Unicode Does Not Happen"> or L</The "Unicode Bug">)
-there are situations where you simply need to force a byte
-string into UTF-8, or vice versa. The low-level calls
-utf8::upgrade($bytestring) and utf8::downgrade($utf8string[, FAIL_OK]) are
-the answers.
-
-Note that utf8::downgrade() can fail if the string contains characters
-that don't fit into a byte.
-
-Calling either function on a string that already is in the desired state is a
-no-op.
-
-=head2 Using Unicode in XS
-
-If you want to handle Perl Unicode in XS extensions, you may find the
-following C APIs useful. See also L<perlguts/"Unicode Support"> for an
-explanation about Unicode at the XS level, and L<perlapi> for the API
-details.
-
-=over 4
-
-=item *
-
-C<DO_UTF8(sv)> returns true if the C<UTF8> flag is on and the bytes
-pragma is not in effect. C<SvUTF8(sv)> returns true if the C<UTF8>
-flag is on; the bytes pragma is ignored. The C<UTF8> flag being on
-does B<not> mean that there are any characters of code points greater
-than 255 (or 127) in the scalar or that there are even any characters
-in the scalar. What the C<UTF8> flag means is that the sequence of
-octets in the representation of the scalar is the sequence of UTF-8
-encoded code points of the characters of a string. The C<UTF8> flag
-being off means that each octet in this representation encodes a
-single character with code point 0..255 within the string. Perl's
-Unicode model is not to use UTF-8 until it is absolutely necessary.
-
-=item *
-
-C<uvchr_to_utf8(buf, chr)> writes a Unicode character code point into
-a buffer encoding the code point as UTF-8, and returns a pointer
-pointing after the UTF-8 bytes. It works appropriately on EBCDIC machines.
-
-=item *
-
-C<utf8_to_uvchr_buf(buf, bufend, lenp)> reads UTF-8 encoded bytes from a
-buffer and
-returns the Unicode character code point and, optionally, the length of
-the UTF-8 byte sequence. It works appropriately on EBCDIC machines.
-
-=item *
-
-C<utf8_length(start, end)> returns the length of the UTF-8 encoded buffer
-in characters. C<sv_len_utf8(sv)> returns the length of the UTF-8 encoded
-scalar.
-
-=item *
-
-C<sv_utf8_upgrade(sv)> converts the string of the scalar to its UTF-8
-encoded form. C<sv_utf8_downgrade(sv)> does the opposite, if
-possible. C<sv_utf8_encode(sv)> is like sv_utf8_upgrade except that
-it does not set the C<UTF8> flag. C<sv_utf8_decode()> does the
-opposite of C<sv_utf8_encode()>. Note that none of these are to be
-used as general-purpose encoding or decoding interfaces: C<use Encode>
-for that. C<sv_utf8_upgrade()> is affected by the encoding pragma
-but C<sv_utf8_downgrade()> is not (since the encoding pragma is
-designed to be a one-way street).
-
-=item *
-
-C<is_utf8_string(buf, len)> returns true if C<len> bytes of the buffer
-are valid UTF-8.
-
-=item *
-
-C<is_utf8_char(s)> returns true if the pointer points to a valid UTF-8
-character. However, this function should not be used because of
-security concerns. Instead, use C<is_utf8_string()>.
-
-=item *
-
-C<UTF8SKIP(buf)> will return the number of bytes in the UTF-8 encoded
-character in the buffer. C<UNISKIP(chr)> will return the number of bytes
-required to UTF-8-encode the Unicode character code point. C<UTF8SKIP()>
-is useful for example for iterating over the characters of a UTF-8
-encoded buffer; C<UNISKIP()> is useful, for example, in computing
-the size required for a UTF-8 encoded buffer.
-
-=item *
-
-C<utf8_distance(a, b)> will tell the distance in characters between the
-two pointers pointing to the same UTF-8 encoded buffer.
-
-=item *
-
-C<utf8_hop(s, off)> will return a pointer to a UTF-8 encoded buffer
-that is C<off> (positive or negative) Unicode characters displaced
-from the UTF-8 buffer C<s>. Be careful not to overstep the buffer:
-C<utf8_hop()> will merrily run off the end or the beginning of the
-buffer if told to do so.
-
-=item *
-
-C<pv_uni_display(dsv, spv, len, pvlim, flags)> and
-C<sv_uni_display(dsv, ssv, pvlim, flags)> are useful for debugging the
-output of Unicode strings and scalars. By default they are useful
-only for debugging--they display B<all> characters as hexadecimal code
-points--but with the flags C<UNI_DISPLAY_ISPRINT>,
-C<UNI_DISPLAY_BACKSLASH>, and C<UNI_DISPLAY_QQ> you can make the
-output more readable.
-
-=item *
-
-C<foldEQ_utf8(s1, pe1, l1, u1, s2, pe2, l2, u2)> can be used to
-compare two strings case-insensitively in Unicode. For case-sensitive
-comparisons you can just use C<memEQ()> and C<memNE()> as usual, except
-if one string is in utf8 and the other isn't.
-
-=back
-
-For more information, see L<perlapi>, and F<utf8.c> and F<utf8.h>
-in the Perl source code distribution.
-
-=head2 Hacking Perl to work on earlier Unicode versions (for very serious hackers only)
-
-Perl by default comes with the latest supported Unicode version built in, but
-you can change to use any earlier one.
-
-Download the files in the desired version of Unicode from the Unicode web
-site L<http://www.unicode.org>). These should replace the existing files in
-F<lib/unicore> in the Perl source tree. Follow the instructions in
-F<README.perl> in that directory to change some of their names, and then build
-perl (see L<INSTALL>).
-
-=head1 BUGS
-
-=head2 Interaction with Locales
-
-See L<perllocale/Unicode and UTF-8>
-
-=head2 Problems with characters in the Latin-1 Supplement range
-
-See L</The "Unicode Bug">
-
-=head2 Interaction with Extensions
-
-When Perl exchanges data with an extension, the extension should be
-able to understand the UTF8 flag and act accordingly. If the
-extension doesn't recognize that flag, it's likely that the extension
-will return incorrectly-flagged data.
-
-So if you're working with Unicode data, consult the documentation of
-every module you're using if there are any issues with Unicode data
-exchange. If the documentation does not talk about Unicode at all,
-suspect the worst and probably look at the source to learn how the
-module is implemented. Modules written completely in Perl shouldn't
-cause problems. Modules that directly or indirectly access code written
-in other programming languages are at risk.
-
-For affected functions, the simple strategy to avoid data corruption is
-to always make the encoding of the exchanged data explicit. Choose an
-encoding that you know the extension can handle. Convert arguments passed
-to the extensions to that encoding and convert results back from that
-encoding. Write wrapper functions that do the conversions for you, so
-you can later change the functions when the extension catches up.
-
-To provide an example, let's say the popular Foo::Bar::escape_html
-function doesn't deal with Unicode data yet. The wrapper function
-would convert the argument to raw UTF-8 and convert the result back to
-Perl's internal representation like so:
-
- sub my_escape_html ($) {
- my($what) = shift;
- return unless defined $what;
- Encode::decode_utf8(Foo::Bar::escape_html(
- Encode::encode_utf8($what)));
- }
-
-Sometimes, when the extension does not convert data but just stores
-and retrieves them, you will be able to use the otherwise
-dangerous Encode::_utf8_on() function. Let's say the popular
-C<Foo::Bar> extension, written in C, provides a C<param> method that
-lets you store and retrieve data according to these prototypes:
-
- $self->param($name, $value); # set a scalar
- $value = $self->param($name); # retrieve a scalar
-
-If it does not yet provide support for any encoding, one could write a
-derived class with such a C<param> method:
-
- sub param {
- my($self,$name,$value) = @_;
- utf8::upgrade($name); # make sure it is UTF-8 encoded
- if (defined $value) {
- utf8::upgrade($value); # make sure it is UTF-8 encoded
- return $self->SUPER::param($name,$value);
- } else {
- my $ret = $self->SUPER::param($name);
- Encode::_utf8_on($ret); # we know, it is UTF-8 encoded
- return $ret;
- }
- }
-
-Some extensions provide filters on data entry/exit points, such as
-DB_File::filter_store_key and family. Look out for such filters in
-the documentation of your extensions, they can make the transition to
-Unicode data much easier.
-
-=head2 Speed
-
-Some functions are slower when working on UTF-8 encoded strings than
-on byte encoded strings. All functions that need to hop over
-characters such as length(), substr() or index(), or matching regular
-expressions can work B<much> faster when the underlying data are
-byte-encoded.
-
-In Perl 5.8.0 the slowness was often quite spectacular; in Perl 5.8.1
-a caching scheme was introduced which will hopefully make the slowness
-somewhat less spectacular, at least for some operations. In general,
-operations with UTF-8 encoded strings are still slower. As an example,
-the Unicode properties (character classes) like C<\p{Nd}> are known to
-be quite a bit slower (5-20 times) than their simpler counterparts
-like C<\d> (then again, there are hundreds of Unicode characters matching C<Nd>
-compared with the 10 ASCII characters matching C<d>).
-
-=head2 Problems on EBCDIC platforms
-
-There are several known problems with Perl on EBCDIC platforms. If you
-want to use Perl there, send email to perlbug@perl.org.
-
-In earlier versions, when byte and character data were concatenated,
-the new string was sometimes created by
-decoding the byte strings as I<ISO 8859-1 (Latin-1)>, even if the
-old Unicode string used EBCDIC.
-
-If you find any of these, please report them as bugs.
-
-=head2 Porting code from perl-5.6.X
-
-Perl 5.8 has a different Unicode model from 5.6. In 5.6 the programmer
-was required to use the C<utf8> pragma to declare that a given scope
-expected to deal with Unicode data and had to make sure that only
-Unicode data were reaching that scope. If you have code that is
-working with 5.6, you will need some of the following adjustments to
-your code. The examples are written such that the code will continue
-to work under 5.6, so you should be safe to try them out.
-
-=over 3
-
-=item *
-
-A filehandle that should read or write UTF-8
-
- if ($] > 5.007) {
- binmode $fh, ":encoding(utf8)";
- }
-
-=item *
-
-A scalar that is going to be passed to some extension
-
-Be it Compress::Zlib, Apache::Request or any extension that has no
-mention of Unicode in the manpage, you need to make sure that the
-UTF8 flag is stripped off. Note that at the time of this writing
-(October 2002) the mentioned modules are not UTF-8-aware. Please
-check the documentation to verify if this is still true.
-
- if ($] > 5.007) {
- require Encode;
- $val = Encode::encode_utf8($val); # make octets
- }
-
-=item *
-
-A scalar we got back from an extension
-
-If you believe the scalar comes back as UTF-8, you will most likely
-want the UTF8 flag restored:
-
- if ($] > 5.007) {
- require Encode;
- $val = Encode::decode_utf8($val);
- }
-
-=item *
-
-Same thing, if you are really sure it is UTF-8
-
- if ($] > 5.007) {
- require Encode;
- Encode::_utf8_on($val);
- }
-
-=item *
-
-A wrapper for fetchrow_array and fetchrow_hashref
-
-When the database contains only UTF-8, a wrapper function or method is
-a convenient way to replace all your fetchrow_array and
-fetchrow_hashref calls. A wrapper function will also make it easier to
-adapt to future enhancements in your database driver. Note that at the
-time of this writing (October 2002), the DBI has no standardized way
-to deal with UTF-8 data. Please check the documentation to verify if
-that is still true.
-
- sub fetchrow {
- # $what is one of fetchrow_{array,hashref}
- my($self, $sth, $what) = @_;
- if ($] < 5.007) {
- return $sth->$what;
- } else {
- require Encode;
- if (wantarray) {
- my @arr = $sth->$what;
- for (@arr) {
- defined && /[^\000-\177]/ && Encode::_utf8_on($_);
- }
- return @arr;
- } else {
- my $ret = $sth->$what;
- if (ref $ret) {
- for my $k (keys %$ret) {
- defined
- && /[^\000-\177]/
- && Encode::_utf8_on($_) for $ret->{$k};
- }
- return $ret;
- } else {
- defined && /[^\000-\177]/ && Encode::_utf8_on($_) for $ret;
- return $ret;
- }
- }
- }
- }
-
-
-=item *
-
-A large scalar that you know can only contain ASCII
-
-Scalars that contain only ASCII and are marked as UTF-8 are sometimes
-a drag to your program. If you recognize such a situation, just remove
-the UTF8 flag:
-
- utf8::downgrade($val) if $] > 5.007;
-
-=back
-
-=head1 SEE ALSO
-
-L<perlunitut>, L<perluniintro>, L<perluniprops>, L<Encode>, L<open>, L<utf8>, L<bytes>,
-L<perlretut>, L<perlvar/"${^UNICODE}">
-L<http://www.unicode.org/reports/tr44>).
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlunifaq.pod b/Master/tlpkg/tlperl/lib/pods/perlunifaq.pod
deleted file mode 100644
index 9bd103c9ac2..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlunifaq.pod
+++ /dev/null
@@ -1,319 +0,0 @@
-=head1 NAME
-
-perlunifaq - Perl Unicode FAQ
-
-=head1 Q and A
-
-This is a list of questions and answers about Unicode in Perl, intended to be
-read after L<perlunitut>.
-
-=head2 perlunitut isn't really a Unicode tutorial, is it?
-
-No, and this isn't really a Unicode FAQ.
-
-Perl has an abstracted interface for all supported character encodings, so this
-is actually a generic C<Encode> tutorial and C<Encode> FAQ. But many people
-think that Unicode is special and magical, and I didn't want to disappoint
-them, so I decided to call the document a Unicode tutorial.
-
-=head2 What character encodings does Perl support?
-
-To find out which character encodings your Perl supports, run:
-
- perl -MEncode -le "print for Encode->encodings(':all')"
-
-=head2 Which version of perl should I use?
-
-Well, if you can, upgrade to the most recent, but certainly C<5.8.1> or newer.
-The tutorial and FAQ assume the latest release.
-
-You should also check your modules, and upgrade them if necessary. For example,
-HTML::Entities requires version >= 1.32 to function correctly, even though the
-changelog is silent about this.
-
-=head2 What about binary data, like images?
-
-Well, apart from a bare C<binmode $fh>, you shouldn't treat them specially.
-(The binmode is needed because otherwise Perl may convert line endings on Win32
-systems.)
-
-Be careful, though, to never combine text strings with binary strings. If you
-need text in a binary stream, encode your text strings first using the
-appropriate encoding, then join them with binary strings. See also: "What if I
-don't encode?".
-
-=head2 When should I decode or encode?
-
-Whenever you're communicating text with anything that is external to your perl
-process, like a database, a text file, a socket, or another program. Even if
-the thing you're communicating with is also written in Perl.
-
-=head2 What if I don't decode?
-
-Whenever your encoded, binary string is used together with a text string, Perl
-will assume that your binary string was encoded with ISO-8859-1, also known as
-latin-1. If it wasn't latin-1, then your data is unpleasantly converted. For
-example, if it was UTF-8, the individual bytes of multibyte characters are seen
-as separate characters, and then again converted to UTF-8. Such double encoding
-can be compared to double HTML encoding (C<&amp;gt;>), or double URI encoding
-(C<%253E>).
-
-This silent implicit decoding is known as "upgrading". That may sound
-positive, but it's best to avoid it.
-
-=head2 What if I don't encode?
-
-Your text string will be sent using the bytes in Perl's internal format. In
-some cases, Perl will warn you that you're doing something wrong, with a
-friendly warning:
-
- Wide character in print at example.pl line 2.
-
-Because the internal format is often UTF-8, these bugs are hard to spot,
-because UTF-8 is usually the encoding you wanted! But don't be lazy, and don't
-use the fact that Perl's internal format is UTF-8 to your advantage. Encode
-explicitly to avoid weird bugs, and to show to maintenance programmers that you
-thought this through.
-
-=head2 Is there a way to automatically decode or encode?
-
-If all data that comes from a certain handle is encoded in exactly the same
-way, you can tell the PerlIO system to automatically decode everything, with
-the C<encoding> layer. If you do this, you can't accidentally forget to decode
-or encode anymore, on things that use the layered handle.
-
-You can provide this layer when C<open>ing the file:
-
- open my $fh, '>:encoding(UTF-8)', $filename; # auto encoding on write
- open my $fh, '<:encoding(UTF-8)', $filename; # auto decoding on read
-
-Or if you already have an open filehandle:
-
- binmode $fh, ':encoding(UTF-8)';
-
-Some database drivers for DBI can also automatically encode and decode, but
-that is sometimes limited to the UTF-8 encoding.
-
-=head2 What if I don't know which encoding was used?
-
-Do whatever you can to find out, and if you have to: guess. (Don't forget to
-document your guess with a comment.)
-
-You could open the document in a web browser, and change the character set or
-character encoding until you can visually confirm that all characters look the
-way they should.
-
-There is no way to reliably detect the encoding automatically, so if people
-keep sending you data without charset indication, you may have to educate them.
-
-=head2 Can I use Unicode in my Perl sources?
-
-Yes, you can! If your sources are UTF-8 encoded, you can indicate that with the
-C<use utf8> pragma.
-
- use utf8;
-
-This doesn't do anything to your input, or to your output. It only influences
-the way your sources are read. You can use Unicode in string literals, in
-identifiers (but they still have to be "word characters" according to C<\w>),
-and even in custom delimiters.
-
-=head2 Data::Dumper doesn't restore the UTF8 flag; is it broken?
-
-No, Data::Dumper's Unicode abilities are as they should be. There have been
-some complaints that it should restore the UTF8 flag when the data is read
-again with C<eval>. However, you should really not look at the flag, and
-nothing indicates that Data::Dumper should break this rule.
-
-Here's what happens: when Perl reads in a string literal, it sticks to 8 bit
-encoding as long as it can. (But perhaps originally it was internally encoded
-as UTF-8, when you dumped it.) When it has to give that up because other
-characters are added to the text string, it silently upgrades the string to
-UTF-8.
-
-If you properly encode your strings for output, none of this is of your
-concern, and you can just C<eval> dumped data as always.
-
-=head2 Why do regex character classes sometimes match only in the ASCII range?
-
-=head2 Why do some characters not uppercase or lowercase correctly?
-
-Starting in Perl 5.14 (and partially in Perl 5.12), just put a
-C<use feature 'unicode_strings'> near the beginning of your program.
-Within its lexical scope you shouldn't have this problem. It also is
-automatically enabled under C<use feature ':5.12'> or using C<-E> on the
-command line for Perl 5.12 or higher.
-
-The rationale for requiring this is to not break older programs that
-rely on the way things worked before Unicode came along. Those older
-programs knew only about the ASCII character set, and so may not work
-properly for additional characters. When a string is encoded in UTF-8,
-Perl assumes that the program is prepared to deal with Unicode, but when
-the string isn't, Perl assumes that only ASCII (unless it is an EBCDIC
-platform) is wanted, and so those characters that are not ASCII
-characters aren't recognized as to what they would be in Unicode.
-C<use feature 'unicode_strings'> tells Perl to treat all characters as
-Unicode, whether the string is encoded in UTF-8 or not, thus avoiding
-the problem.
-
-However, on earlier Perls, or if you pass strings to subroutines outside
-the feature's scope, you can force Unicode semantics by changing the
-encoding to UTF-8 by doing C<utf8::upgrade($string)>. This can be used
-safely on any string, as it checks and does not change strings that have
-already been upgraded.
-
-For a more detailed discussion, see L<Unicode::Semantics> on CPAN.
-
-=head2 How can I determine if a string is a text string or a binary string?
-
-You can't. Some use the UTF8 flag for this, but that's misuse, and makes well
-behaved modules like Data::Dumper look bad. The flag is useless for this
-purpose, because it's off when an 8 bit encoding (by default ISO-8859-1) is
-used to store the string.
-
-This is something you, the programmer, has to keep track of; sorry. You could
-consider adopting a kind of "Hungarian notation" to help with this.
-
-=head2 How do I convert from encoding FOO to encoding BAR?
-
-By first converting the FOO-encoded byte string to a text string, and then the
-text string to a BAR-encoded byte string:
-
- my $text_string = decode('FOO', $foo_string);
- my $bar_string = encode('BAR', $text_string);
-
-or by skipping the text string part, and going directly from one binary
-encoding to the other:
-
- use Encode qw(from_to);
- from_to($string, 'FOO', 'BAR'); # changes contents of $string
-
-or by letting automatic decoding and encoding do all the work:
-
- open my $foofh, '<:encoding(FOO)', 'example.foo.txt';
- open my $barfh, '>:encoding(BAR)', 'example.bar.txt';
- print { $barfh } $_ while <$foofh>;
-
-=head2 What are C<decode_utf8> and C<encode_utf8>?
-
-These are alternate syntaxes for C<decode('utf8', ...)> and C<encode('utf8',
-...)>.
-
-=head2 What is a "wide character"?
-
-This is a term used both for characters with an ordinal value greater than 127,
-characters with an ordinal value greater than 255, or any character occupying
-more than one byte, depending on the context.
-
-The Perl warning "Wide character in ..." is caused by a character with an
-ordinal value greater than 255. With no specified encoding layer, Perl tries to
-fit things in ISO-8859-1 for backward compatibility reasons. When it can't, it
-emits this warning (if warnings are enabled), and outputs UTF-8 encoded data
-instead.
-
-To avoid this warning and to avoid having different output encodings in a single
-stream, always specify an encoding explicitly, for example with a PerlIO layer:
-
- binmode STDOUT, ":encoding(UTF-8)";
-
-=head1 INTERNALS
-
-=head2 What is "the UTF8 flag"?
-
-Please, unless you're hacking the internals, or debugging weirdness, don't
-think about the UTF8 flag at all. That means that you very probably shouldn't
-use C<is_utf8>, C<_utf8_on> or C<_utf8_off> at all.
-
-The UTF8 flag, also called SvUTF8, is an internal flag that indicates that the
-current internal representation is UTF-8. Without the flag, it is assumed to be
-ISO-8859-1. Perl converts between these automatically. (Actually Perl usually
-assumes the representation is ASCII; see L</Why do regex character classes
-sometimes match only in the ASCII range?> above.)
-
-One of Perl's internal formats happens to be UTF-8. Unfortunately, Perl can't
-keep a secret, so everyone knows about this. That is the source of much
-confusion. It's better to pretend that the internal format is some unknown
-encoding, and that you always have to encode and decode explicitly.
-
-=head2 What about the C<use bytes> pragma?
-
-Don't use it. It makes no sense to deal with bytes in a text string, and it
-makes no sense to deal with characters in a byte string. Do the proper
-conversions (by decoding/encoding), and things will work out well: you get
-character counts for decoded data, and byte counts for encoded data.
-
-C<use bytes> is usually a failed attempt to do something useful. Just forget
-about it.
-
-=head2 What about the C<use encoding> pragma?
-
-Don't use it. Unfortunately, it assumes that the programmer's environment and
-that of the user will use the same encoding. It will use the same encoding for
-the source code and for STDIN and STDOUT. When a program is copied to another
-machine, the source code does not change, but the STDIO environment might.
-
-If you need non-ASCII characters in your source code, make it a UTF-8 encoded
-file and C<use utf8>.
-
-If you need to set the encoding for STDIN, STDOUT, and STDERR, for example
-based on the user's locale, C<use open>.
-
-=head2 What is the difference between C<:encoding> and C<:utf8>?
-
-Because UTF-8 is one of Perl's internal formats, you can often just skip the
-encoding or decoding step, and manipulate the UTF8 flag directly.
-
-Instead of C<:encoding(UTF-8)>, you can simply use C<:utf8>, which skips the
-encoding step if the data was already represented as UTF8 internally. This is
-widely accepted as good behavior when you're writing, but it can be dangerous
-when reading, because it causes internal inconsistency when you have invalid
-byte sequences. Using C<:utf8> for input can sometimes result in security
-breaches, so please use C<:encoding(UTF-8)> instead.
-
-Instead of C<decode> and C<encode>, you could use C<_utf8_on> and C<_utf8_off>,
-but this is considered bad style. Especially C<_utf8_on> can be dangerous, for
-the same reason that C<:utf8> can.
-
-There are some shortcuts for oneliners;
-see L<-C|perlrun/-C [numberE<sol>list]> in L<perlrun>.
-
-=head2 What's the difference between C<UTF-8> and C<utf8>?
-
-C<UTF-8> is the official standard. C<utf8> is Perl's way of being liberal in
-what it accepts. If you have to communicate with things that aren't so liberal,
-you may want to consider using C<UTF-8>. If you have to communicate with things
-that are too liberal, you may have to use C<utf8>. The full explanation is in
-L<Encode>.
-
-C<UTF-8> is internally known as C<utf-8-strict>. The tutorial uses UTF-8
-consistently, even where utf8 is actually used internally, because the
-distinction can be hard to make, and is mostly irrelevant.
-
-For example, utf8 can be used for code points that don't exist in Unicode, like
-9999999, but if you encode that to UTF-8, you get a substitution character (by
-default; see L<Encode/"Handling Malformed Data"> for more ways of dealing with
-this.)
-
-Okay, if you insist: the "internal format" is utf8, not UTF-8. (When it's not
-some other encoding.)
-
-=head2 I lost track; what encoding is the internal format really?
-
-It's good that you lost track, because you shouldn't depend on the internal
-format being any specific encoding. But since you asked: by default, the
-internal format is either ISO-8859-1 (latin-1), or utf8, depending on the
-history of the string. On EBCDIC platforms, this may be different even.
-
-Perl knows how it stored the string internally, and will use that knowledge
-when you C<encode>. In other words: don't try to find out what the internal
-encoding for a certain string is, but instead just encode it into the encoding
-that you want.
-
-=head1 AUTHOR
-
-Juerd Waalboer <#####@juerd.nl>
-
-=head1 SEE ALSO
-
-L<perlunicode>, L<perluniintro>, L<Encode>
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perluniintro.pod b/Master/tlpkg/tlperl/lib/pods/perluniintro.pod
deleted file mode 100644
index 8ce4b7b4464..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perluniintro.pod
+++ /dev/null
@@ -1,946 +0,0 @@
-=head1 NAME
-
-perluniintro - Perl Unicode introduction
-
-=head1 DESCRIPTION
-
-This document gives a general idea of Unicode and how to use Unicode
-in Perl. See L</Further Resources> for references to more in-depth
-treatments of Unicode.
-
-=head2 Unicode
-
-Unicode is a character set standard which plans to codify all of the
-writing systems of the world, plus many other symbols.
-
-Unicode and ISO/IEC 10646 are coordinated standards that unify
-almost all other modern character set standards,
-covering more than 80 writing systems and hundreds of languages,
-including all commercially-important modern languages. All characters
-in the largest Chinese, Japanese, and Korean dictionaries are also
-encoded. The standards will eventually cover almost all characters in
-more than 250 writing systems and thousands of languages.
-Unicode 1.0 was released in October 1991, and 6.0 in October 2010.
-
-A Unicode I<character> is an abstract entity. It is not bound to any
-particular integer width, especially not to the C language C<char>.
-Unicode is language-neutral and display-neutral: it does not encode the
-language of the text, and it does not generally define fonts or other graphical
-layout details. Unicode operates on characters and on text built from
-those characters.
-
-Unicode defines characters like C<LATIN CAPITAL LETTER A> or C<GREEK
-SMALL LETTER ALPHA> and unique numbers for the characters, in this
-case 0x0041 and 0x03B1, respectively. These unique numbers are called
-I<code points>. A code point is essentially the position of the
-character within the set of all possible Unicode characters, and thus in
-Perl, the term I<ordinal> is often used interchangeably with it.
-
-The Unicode standard prefers using hexadecimal notation for the code
-points. If numbers like C<0x0041> are unfamiliar to you, take a peek
-at a later section, L</"Hexadecimal Notation">. The Unicode standard
-uses the notation C<U+0041 LATIN CAPITAL LETTER A>, to give the
-hexadecimal code point and the normative name of the character.
-
-Unicode also defines various I<properties> for the characters, like
-"uppercase" or "lowercase", "decimal digit", or "punctuation";
-these properties are independent of the names of the characters.
-Furthermore, various operations on the characters like uppercasing,
-lowercasing, and collating (sorting) are defined.
-
-A Unicode I<logical> "character" can actually consist of more than one internal
-I<actual> "character" or code point. For Western languages, this is adequately
-modelled by a I<base character> (like C<LATIN CAPITAL LETTER A>) followed
-by one or more I<modifiers> (like C<COMBINING ACUTE ACCENT>). This sequence of
-base character and modifiers is called a I<combining character
-sequence>. Some non-western languages require more complicated
-models, so Unicode created the I<grapheme cluster> concept, which was
-later further refined into the I<extended grapheme cluster>. For
-example, a Korean Hangul syllable is considered a single logical
-character, but most often consists of three actual
-Unicode characters: a leading consonant followed by an interior vowel followed
-by a trailing consonant.
-
-Whether to call these extended grapheme clusters "characters" depends on your
-point of view. If you are a programmer, you probably would tend towards seeing
-each element in the sequences as one unit, or "character". However from
-the user's point of view, the whole sequence could be seen as one
-"character" since that's probably what it looks like in the context of the
-user's language. In this document, we take the programmer's point of
-view: one "character" is one Unicode code point.
-
-For some combinations of base character and modifiers, there are
-I<precomposed> characters. There is a single character equivalent, for
-example, to the sequence C<LATIN CAPITAL LETTER A> followed by
-C<COMBINING ACUTE ACCENT>. It is called C<LATIN CAPITAL LETTER A WITH
-ACUTE>. These precomposed characters are, however, only available for
-some combinations, and are mainly meant to support round-trip
-conversions between Unicode and legacy standards (like ISO 8859). Using
-sequences, as Unicode does, allows for needing fewer basic building blocks
-(code points) to express many more potential grapheme clusters. To
-support conversion between equivalent forms, various I<normalization
-forms> are also defined. Thus, C<LATIN CAPITAL LETTER A WITH ACUTE> is
-in I<Normalization Form Composed>, (abbreviated NFC), and the sequence
-C<LATIN CAPITAL LETTER A> followed by C<COMBINING ACUTE ACCENT>
-represents the same character in I<Normalization Form Decomposed> (NFD).
-
-Because of backward compatibility with legacy encodings, the "a unique
-number for every character" idea breaks down a bit: instead, there is
-"at least one number for every character". The same character could
-be represented differently in several legacy encodings. The
-converse is not also true: some code points do not have an assigned
-character. Firstly, there are unallocated code points within
-otherwise used blocks. Secondly, there are special Unicode control
-characters that do not represent true characters.
-
-When Unicode was first conceived, it was thought that all the world's
-characters could be represented using a 16-bit word; that is a maximum of
-C<0x10000> (or 65536) characters from C<0x0000> to C<0xFFFF> would be
-needed. This soon proved to be false, and since Unicode 2.0 (July
-1996), Unicode has been defined all the way up to 21 bits (C<0x10FFFF>),
-and Unicode 3.1 (March 2001) defined the first characters above C<0xFFFF>.
-The first C<0x10000> characters are called the I<Plane 0>, or the
-I<Basic Multilingual Plane> (BMP). With Unicode 3.1, 17 (yes,
-seventeen) planes in all were defined--but they are nowhere near full of
-defined characters, yet.
-
-When a new language is being encoded, Unicode generally will choose a
-C<block> of consecutive unallocated code points for its characters. So
-far, the number of code points in these blocks has always been evenly
-divisible by 16. Extras in a block, not currently needed, are left
-unallocated, for future growth. But there have been occasions when
-a later relase needed more code points than the available extras, and a
-new block had to allocated somewhere else, not contiguous to the initial
-one, to handle the overflow. Thus, it became apparent early on that
-"block" wasn't an adequate organizing principal, and so the C<Script>
-property was created. (Later an improved script property was added as
-well, the C<Script_Extensions> property.) Those code points that are in
-overflow blocks can still
-have the same script as the original ones. The script concept fits more
-closely with natural language: there is C<Latin> script, C<Greek>
-script, and so on; and there are several artificial scripts, like
-C<Common> for characters that are used in multiple scripts, such as
-mathematical symbols. Scripts usually span varied parts of several
-blocks. For more information about scripts, see L<perlunicode/Scripts>.
-The division into blocks exists, but it is almost completely
-accidental--an artifact of how the characters have been and still are
-allocated. (Note that this paragraph has oversimplified things for the
-sake of this being an introduction. Unicode doesn't really encode
-languages, but the writing systems for them--their scripts; and one
-script can be used by many languages. Unicode also encodes things that
-aren't really about languages, such as symbols like C<BAGGAGE CLAIM>.)
-
-The Unicode code points are just abstract numbers. To input and
-output these abstract numbers, the numbers must be I<encoded> or
-I<serialised> somehow. Unicode defines several I<character encoding
-forms>, of which I<UTF-8> is perhaps the most popular. UTF-8 is a
-variable length encoding that encodes Unicode characters as 1 to 6
-bytes. Other encodings
-include UTF-16 and UTF-32 and their big- and little-endian variants
-(UTF-8 is byte-order independent) The ISO/IEC 10646 defines the UCS-2
-and UCS-4 encoding forms.
-
-For more information about encodings--for instance, to learn what
-I<surrogates> and I<byte order marks> (BOMs) are--see L<perlunicode>.
-
-=head2 Perl's Unicode Support
-
-Starting from Perl 5.6.0, Perl has had the capacity to handle Unicode
-natively. Perl 5.8.0, however, is the first recommended release for
-serious Unicode work. The maintenance release 5.6.1 fixed many of the
-problems of the initial Unicode implementation, but for example
-regular expressions still do not work with Unicode in 5.6.1.
-Perl 5.14.0 is the first release where Unicode support is
-(almost) seamlessly integrable without some gotchas (the exception being
-some differences in L<quotemeta|perlfunc/quotemeta>, which is fixed
-starting in Perl 5.16.0). To enable this
-seamless support, you should C<use feature 'unicode_strings'> (which is
-automatically selected if you C<use 5.012> or higher). See L<feature>.
-(5.14 also fixes a number of bugs and departures from the Unicode
-standard.)
-
-Before Perl 5.8.0, the use of C<use utf8> was used to declare
-that operations in the current block or file would be Unicode-aware.
-This model was found to be wrong, or at least clumsy: the "Unicodeness"
-is now carried with the data, instead of being attached to the
-operations.
-Starting with Perl 5.8.0, only one case remains where an explicit C<use
-utf8> is needed: if your Perl script itself is encoded in UTF-8, you can
-use UTF-8 in your identifier names, and in string and regular expression
-literals, by saying C<use utf8>. This is not the default because
-scripts with legacy 8-bit data in them would break. See L<utf8>.
-
-=head2 Perl's Unicode Model
-
-Perl supports both pre-5.6 strings of eight-bit native bytes, and
-strings of Unicode characters. The general principle is that Perl tries
-to keep its data as eight-bit bytes for as long as possible, but as soon
-as Unicodeness cannot be avoided, the data is transparently upgraded
-to Unicode. Prior to Perl 5.14, the upgrade was not completely
-transparent (see L<perlunicode/The "Unicode Bug">), and for backwards
-compatibility, full transparency is not gained unless C<use feature
-'unicode_strings'> (see L<feature>) or C<use 5.012> (or higher) is
-selected.
-
-Internally, Perl currently uses either whatever the native eight-bit
-character set of the platform (for example Latin-1) is, defaulting to
-UTF-8, to encode Unicode strings. Specifically, if all code points in
-the string are C<0xFF> or less, Perl uses the native eight-bit
-character set. Otherwise, it uses UTF-8.
-
-A user of Perl does not normally need to know nor care how Perl
-happens to encode its internal strings, but it becomes relevant when
-outputting Unicode strings to a stream without a PerlIO layer (one with
-the "default" encoding). In such a case, the raw bytes used internally
-(the native character set or UTF-8, as appropriate for each string)
-will be used, and a "Wide character" warning will be issued if those
-strings contain a character beyond 0x00FF.
-
-For example,
-
- perl -e 'print "\x{DF}\n", "\x{0100}\x{DF}\n"'
-
-produces a fairly useless mixture of native bytes and UTF-8, as well
-as a warning:
-
- Wide character in print at ...
-
-To output UTF-8, use the C<:encoding> or C<:utf8> output layer. Prepending
-
- binmode(STDOUT, ":utf8");
-
-to this sample program ensures that the output is completely UTF-8,
-and removes the program's warning.
-
-You can enable automatic UTF-8-ification of your standard file
-handles, default C<open()> layer, and C<@ARGV> by using either
-the C<-C> command line switch or the C<PERL_UNICODE> environment
-variable, see L<perlrun> for the documentation of the C<-C> switch.
-
-Note that this means that Perl expects other software to work the same
-way:
-if Perl has been led to believe that STDIN should be UTF-8, but then
-STDIN coming in from another command is not UTF-8, Perl will likely
-complain about the malformed UTF-8.
-
-All features that combine Unicode and I/O also require using the new
-PerlIO feature. Almost all Perl 5.8 platforms do use PerlIO, though:
-you can see whether yours is by running "perl -V" and looking for
-C<useperlio=define>.
-
-=head2 Unicode and EBCDIC
-
-Perl 5.8.0 also supports Unicode on EBCDIC platforms. There,
-Unicode support is somewhat more complex to implement since
-additional conversions are needed at every step.
-
-Later Perl releases have added code that will not work on EBCDIC platforms, and
-no one has complained, so the divergence has continued. If you want to run
-Perl on an EBCDIC platform, send email to perlbug@perl.org
-
-On EBCDIC platforms, the internal Unicode encoding form is UTF-EBCDIC
-instead of UTF-8. The difference is that as UTF-8 is "ASCII-safe" in
-that ASCII characters encode to UTF-8 as-is, while UTF-EBCDIC is
-"EBCDIC-safe".
-
-=head2 Creating Unicode
-
-To create Unicode characters in literals for code points above C<0xFF>,
-use the C<\x{...}> notation in double-quoted strings:
-
- my $smiley = "\x{263a}";
-
-Similarly, it can be used in regular expression literals
-
- $smiley =~ /\x{263a}/;
-
-At run-time you can use C<chr()>:
-
- my $hebrew_alef = chr(0x05d0);
-
-See L</"Further Resources"> for how to find all these numeric codes.
-
-Naturally, C<ord()> will do the reverse: it turns a character into
-a code point.
-
-Note that C<\x..> (no C<{}> and only two hexadecimal digits), C<\x{...}>,
-and C<chr(...)> for arguments less than C<0x100> (decimal 256)
-generate an eight-bit character for backward compatibility with older
-Perls. For arguments of C<0x100> or more, Unicode characters are
-always produced. If you want to force the production of Unicode
-characters regardless of the numeric value, use C<pack("U", ...)>
-instead of C<\x..>, C<\x{...}>, or C<chr()>.
-
-You can invoke characters
-by name in double-quoted strings:
-
- my $arabic_alef = "\N{ARABIC LETTER ALEF}";
-
-And, as mentioned above, you can also C<pack()> numbers into Unicode
-characters:
-
- my $georgian_an = pack("U", 0x10a0);
-
-Note that both C<\x{...}> and C<\N{...}> are compile-time string
-constants: you cannot use variables in them. if you want similar
-run-time functionality, use C<chr()> and C<charnames::string_vianame()>.
-
-If you want to force the result to Unicode characters, use the special
-C<"U0"> prefix. It consumes no arguments but causes the following bytes
-to be interpreted as the UTF-8 encoding of Unicode characters:
-
- my $chars = pack("U0W*", 0x80, 0x42);
-
-Likewise, you can stop such UTF-8 interpretation by using the special
-C<"C0"> prefix.
-
-=head2 Handling Unicode
-
-Handling Unicode is for the most part transparent: just use the
-strings as usual. Functions like C<index()>, C<length()>, and
-C<substr()> will work on the Unicode characters; regular expressions
-will work on the Unicode characters (see L<perlunicode> and L<perlretut>).
-
-Note that Perl considers grapheme clusters to be separate characters, so for
-example
-
- print length("\N{LATIN CAPITAL LETTER A}\N{COMBINING ACUTE ACCENT}"),
- "\n";
-
-will print 2, not 1. The only exception is that regular expressions
-have C<\X> for matching an extended grapheme cluster. (Thus C<\X> in a
-regular expression would match the entire sequence of both the example
-characters.)
-
-Life is not quite so transparent, however, when working with legacy
-encodings, I/O, and certain special cases:
-
-=head2 Legacy Encodings
-
-When you combine legacy data and Unicode, the legacy data needs
-to be upgraded to Unicode. Normally the legacy data is assumed to be
-ISO 8859-1 (or EBCDIC, if applicable).
-
-The C<Encode> module knows about many encodings and has interfaces
-for doing conversions between those encodings:
-
- use Encode 'decode';
- $data = decode("iso-8859-3", $data); # convert from legacy to utf-8
-
-=head2 Unicode I/O
-
-Normally, writing out Unicode data
-
- print FH $some_string_with_unicode, "\n";
-
-produces raw bytes that Perl happens to use to internally encode the
-Unicode string. Perl's internal encoding depends on the system as
-well as what characters happen to be in the string at the time. If
-any of the characters are at code points C<0x100> or above, you will get
-a warning. To ensure that the output is explicitly rendered in the
-encoding you desire--and to avoid the warning--open the stream with
-the desired encoding. Some examples:
-
- open FH, ">:utf8", "file";
-
- open FH, ">:encoding(ucs2)", "file";
- open FH, ">:encoding(UTF-8)", "file";
- open FH, ">:encoding(shift_jis)", "file";
-
-and on already open streams, use C<binmode()>:
-
- binmode(STDOUT, ":utf8");
-
- binmode(STDOUT, ":encoding(ucs2)");
- binmode(STDOUT, ":encoding(UTF-8)");
- binmode(STDOUT, ":encoding(shift_jis)");
-
-The matching of encoding names is loose: case does not matter, and
-many encodings have several aliases. Note that the C<:utf8> layer
-must always be specified exactly like that; it is I<not> subject to
-the loose matching of encoding names. Also note that currently C<:utf8> is unsafe for
-input, because it accepts the data without validating that it is indeed valid
-UTF-8; you should instead use C<:encoding(utf-8)> (with or without a
-hyphen).
-
-See L<PerlIO> for the C<:utf8> layer, L<PerlIO::encoding> and
-L<Encode::PerlIO> for the C<:encoding()> layer, and
-L<Encode::Supported> for many encodings supported by the C<Encode>
-module.
-
-Reading in a file that you know happens to be encoded in one of the
-Unicode or legacy encodings does not magically turn the data into
-Unicode in Perl's eyes. To do that, specify the appropriate
-layer when opening files
-
- open(my $fh,'<:encoding(utf8)', 'anything');
- my $line_of_unicode = <$fh>;
-
- open(my $fh,'<:encoding(Big5)', 'anything');
- my $line_of_unicode = <$fh>;
-
-The I/O layers can also be specified more flexibly with
-the C<open> pragma. See L<open>, or look at the following example.
-
- use open ':encoding(utf8)'; # input/output default encoding will be
- # UTF-8
- open X, ">file";
- print X chr(0x100), "\n";
- close X;
- open Y, "<file";
- printf "%#x\n", ord(<Y>); # this should print 0x100
- close Y;
-
-With the C<open> pragma you can use the C<:locale> layer
-
- BEGIN { $ENV{LC_ALL} = $ENV{LANG} = 'ru_RU.KOI8-R' }
- # the :locale will probe the locale environment variables like
- # LC_ALL
- use open OUT => ':locale'; # russki parusski
- open(O, ">koi8");
- print O chr(0x430); # Unicode CYRILLIC SMALL LETTER A = KOI8-R 0xc1
- close O;
- open(I, "<koi8");
- printf "%#x\n", ord(<I>), "\n"; # this should print 0xc1
- close I;
-
-These methods install a transparent filter on the I/O stream that
-converts data from the specified encoding when it is read in from the
-stream. The result is always Unicode.
-
-The L<open> pragma affects all the C<open()> calls after the pragma by
-setting default layers. If you want to affect only certain
-streams, use explicit layers directly in the C<open()> call.
-
-You can switch encodings on an already opened stream by using
-C<binmode()>; see L<perlfunc/binmode>.
-
-The C<:locale> does not currently (as of Perl 5.8.0) work with
-C<open()> and C<binmode()>, only with the C<open> pragma. The
-C<:utf8> and C<:encoding(...)> methods do work with all of C<open()>,
-C<binmode()>, and the C<open> pragma.
-
-Similarly, you may use these I/O layers on output streams to
-automatically convert Unicode to the specified encoding when it is
-written to the stream. For example, the following snippet copies the
-contents of the file "text.jis" (encoded as ISO-2022-JP, aka JIS) to
-the file "text.utf8", encoded as UTF-8:
-
- open(my $nihongo, '<:encoding(iso-2022-jp)', 'text.jis');
- open(my $unicode, '>:utf8', 'text.utf8');
- while (<$nihongo>) { print $unicode $_ }
-
-The naming of encodings, both by the C<open()> and by the C<open>
-pragma allows for flexible names: C<koi8-r> and C<KOI8R> will both be
-understood.
-
-Common encodings recognized by ISO, MIME, IANA, and various other
-standardisation organisations are recognised; for a more detailed
-list see L<Encode::Supported>.
-
-C<read()> reads characters and returns the number of characters.
-C<seek()> and C<tell()> operate on byte counts, as do C<sysread()>
-and C<sysseek()>.
-
-Notice that because of the default behaviour of not doing any
-conversion upon input if there is no default layer,
-it is easy to mistakenly write code that keeps on expanding a file
-by repeatedly encoding the data:
-
- # BAD CODE WARNING
- open F, "file";
- local $/; ## read in the whole file of 8-bit characters
- $t = <F>;
- close F;
- open F, ">:encoding(utf8)", "file";
- print F $t; ## convert to UTF-8 on output
- close F;
-
-If you run this code twice, the contents of the F<file> will be twice
-UTF-8 encoded. A C<use open ':encoding(utf8)'> would have avoided the
-bug, or explicitly opening also the F<file> for input as UTF-8.
-
-B<NOTE>: the C<:utf8> and C<:encoding> features work only if your
-Perl has been built with the new PerlIO feature (which is the default
-on most systems).
-
-=head2 Displaying Unicode As Text
-
-Sometimes you might want to display Perl scalars containing Unicode as
-simple ASCII (or EBCDIC) text. The following subroutine converts
-its argument so that Unicode characters with code points greater than
-255 are displayed as C<\x{...}>, control characters (like C<\n>) are
-displayed as C<\x..>, and the rest of the characters as themselves:
-
- sub nice_string {
- join("",
- map { $_ > 255 ? # if wide character...
- sprintf("\\x{%04X}", $_) : # \x{...}
- chr($_) =~ /[[:cntrl:]]/ ? # else if control character...
- sprintf("\\x%02X", $_) : # \x..
- quotemeta(chr($_)) # else quoted or as themselves
- } unpack("W*", $_[0])); # unpack Unicode characters
- }
-
-For example,
-
- nice_string("foo\x{100}bar\n")
-
-returns the string
-
- 'foo\x{0100}bar\x0A'
-
-which is ready to be printed.
-
-=head2 Special Cases
-
-=over 4
-
-=item *
-
-Bit Complement Operator ~ And vec()
-
-The bit complement operator C<~> may produce surprising results if
-used on strings containing characters with ordinal values above
-255. In such a case, the results are consistent with the internal
-encoding of the characters, but not with much else. So don't do
-that. Similarly for C<vec()>: you will be operating on the
-internally-encoded bit patterns of the Unicode characters, not on
-the code point values, which is very probably not what you want.
-
-=item *
-
-Peeking At Perl's Internal Encoding
-
-Normal users of Perl should never care how Perl encodes any particular
-Unicode string (because the normal ways to get at the contents of a
-string with Unicode--via input and output--should always be via
-explicitly-defined I/O layers). But if you must, there are two
-ways of looking behind the scenes.
-
-One way of peeking inside the internal encoding of Unicode characters
-is to use C<unpack("C*", ...> to get the bytes of whatever the string
-encoding happens to be, or C<unpack("U0..", ...)> to get the bytes of the
-UTF-8 encoding:
-
- # this prints c4 80 for the UTF-8 bytes 0xc4 0x80
- print join(" ", unpack("U0(H2)*", pack("U", 0x100))), "\n";
-
-Yet another way would be to use the Devel::Peek module:
-
- perl -MDevel::Peek -e 'Dump(chr(0x100))'
-
-That shows the C<UTF8> flag in FLAGS and both the UTF-8 bytes
-and Unicode characters in C<PV>. See also later in this document
-the discussion about the C<utf8::is_utf8()> function.
-
-=back
-
-=head2 Advanced Topics
-
-=over 4
-
-=item *
-
-String Equivalence
-
-The question of string equivalence turns somewhat complicated
-in Unicode: what do you mean by "equal"?
-
-(Is C<LATIN CAPITAL LETTER A WITH ACUTE> equal to
-C<LATIN CAPITAL LETTER A>?)
-
-The short answer is that by default Perl compares equivalence (C<eq>,
-C<ne>) based only on code points of the characters. In the above
-case, the answer is no (because 0x00C1 != 0x0041). But sometimes, any
-CAPITAL LETTER A's should be considered equal, or even A's of any case.
-
-The long answer is that you need to consider character normalization
-and casing issues: see L<Unicode::Normalize>, Unicode Technical Report #15,
-L<Unicode Normalization Forms|http://www.unicode.org/unicode/reports/tr15> and
-sections on case mapping in the L<Unicode Standard|http://www.unicode.org>.
-
-As of Perl 5.8.0, the "Full" case-folding of I<Case
-Mappings/SpecialCasing> is implemented, but bugs remain in C<qr//i> with them,
-mostly fixed by 5.14.
-
-=item *
-
-String Collation
-
-People like to see their strings nicely sorted--or as Unicode
-parlance goes, collated. But again, what do you mean by collate?
-
-(Does C<LATIN CAPITAL LETTER A WITH ACUTE> come before or after
-C<LATIN CAPITAL LETTER A WITH GRAVE>?)
-
-The short answer is that by default, Perl compares strings (C<lt>,
-C<le>, C<cmp>, C<ge>, C<gt>) based only on the code points of the
-characters. In the above case, the answer is "after", since
-C<0x00C1> > C<0x00C0>.
-
-The long answer is that "it depends", and a good answer cannot be
-given without knowing (at the very least) the language context.
-See L<Unicode::Collate>, and I<Unicode Collation Algorithm>
-L<http://www.unicode.org/unicode/reports/tr10/>
-
-=back
-
-=head2 Miscellaneous
-
-=over 4
-
-=item *
-
-Character Ranges and Classes
-
-Character ranges in regular expression bracketed character classes ( e.g.,
-C</[a-z]/>) and in the C<tr///> (also known as C<y///>) operator are not
-magically Unicode-aware. What this means is that C<[A-Za-z]> will not
-magically start to mean "all alphabetic letters" (not that it does mean that
-even for 8-bit characters; for those, if you are using locales (L<perllocale>),
-use C</[[:alpha:]]/>; and if not, use the 8-bit-aware property C<\p{alpha}>).
-
-All the properties that begin with C<\p> (and its inverse C<\P>) are actually
-character classes that are Unicode-aware. There are dozens of them, see
-L<perluniprops>.
-
-You can use Unicode code points as the end points of character ranges, and the
-range will include all Unicode code points that lie between those end points.
-
-=item *
-
-String-To-Number Conversions
-
-Unicode does define several other decimal--and numeric--characters
-besides the familiar 0 to 9, such as the Arabic and Indic digits.
-Perl does not support string-to-number conversion for digits other
-than ASCII 0 to 9 (and ASCII a to f for hexadecimal).
-To get safe conversions from any Unicode string, use
-L<Unicode::UCD/num()>.
-
-=back
-
-=head2 Questions With Answers
-
-=over 4
-
-=item *
-
-Will My Old Scripts Break?
-
-Very probably not. Unless you are generating Unicode characters
-somehow, old behaviour should be preserved. About the only behaviour
-that has changed and which could start generating Unicode is the old
-behaviour of C<chr()> where supplying an argument more than 255
-produced a character modulo 255. C<chr(300)>, for example, was equal
-to C<chr(45)> or "-" (in ASCII), now it is LATIN CAPITAL LETTER I WITH
-BREVE.
-
-=item *
-
-How Do I Make My Scripts Work With Unicode?
-
-Very little work should be needed since nothing changes until you
-generate Unicode data. The most important thing is getting input as
-Unicode; for that, see the earlier I/O discussion.
-To get full seamless Unicode support, add
-C<use feature 'unicode_strings'> (or C<use 5.012> or higher) to your
-script.
-
-=item *
-
-How Do I Know Whether My String Is In Unicode?
-
-You shouldn't have to care. But you may if your Perl is before 5.14.0
-or you haven't specified C<use feature 'unicode_strings'> or C<use
-5.012> (or higher) because otherwise the semantics of the code points
-in the range 128 to 255 are different depending on
-whether the string they are contained within is in Unicode or not.
-(See L<perlunicode/When Unicode Does Not Happen>.)
-
-To determine if a string is in Unicode, use:
-
- print utf8::is_utf8($string) ? 1 : 0, "\n";
-
-But note that this doesn't mean that any of the characters in the
-string are necessary UTF-8 encoded, or that any of the characters have
-code points greater than 0xFF (255) or even 0x80 (128), or that the
-string has any characters at all. All the C<is_utf8()> does is to
-return the value of the internal "utf8ness" flag attached to the
-C<$string>. If the flag is off, the bytes in the scalar are interpreted
-as a single byte encoding. If the flag is on, the bytes in the scalar
-are interpreted as the (variable-length, potentially multi-byte) UTF-8 encoded
-code points of the characters. Bytes added to a UTF-8 encoded string are
-automatically upgraded to UTF-8. If mixed non-UTF-8 and UTF-8 scalars
-are merged (double-quoted interpolation, explicit concatenation, or
-printf/sprintf parameter substitution), the result will be UTF-8 encoded
-as if copies of the byte strings were upgraded to UTF-8: for example,
-
- $a = "ab\x80c";
- $b = "\x{100}";
- print "$a = $b\n";
-
-the output string will be UTF-8-encoded C<ab\x80c = \x{100}\n>, but
-C<$a> will stay byte-encoded.
-
-Sometimes you might really need to know the byte length of a string
-instead of the character length. For that use either the
-C<Encode::encode_utf8()> function or the C<bytes> pragma
-and the C<length()> function:
-
- my $unicode = chr(0x100);
- print length($unicode), "\n"; # will print 1
- require Encode;
- print length(Encode::encode_utf8($unicode)),"\n"; # will print 2
- use bytes;
- print length($unicode), "\n"; # will also print 2
- # (the 0xC4 0x80 of the UTF-8)
- no bytes;
-
-=item *
-
-How Do I Find Out What Encoding a File Has?
-
-You might try L<Encode::Guess>, but it has a number of limitations.
-
-=item *
-
-How Do I Detect Data That's Not Valid In a Particular Encoding?
-
-Use the C<Encode> package to try converting it.
-For example,
-
- use Encode 'decode_utf8';
-
- if (eval { decode_utf8($string, Encode::FB_CROAK); 1 }) {
- # $string is valid utf8
- } else {
- # $string is not valid utf8
- }
-
-Or use C<unpack> to try decoding it:
-
- use warnings;
- @chars = unpack("C0U*", $string_of_bytes_that_I_think_is_utf8);
-
-If invalid, a C<Malformed UTF-8 character> warning is produced. The "C0" means
-"process the string character per character". Without that, the
-C<unpack("U*", ...)> would work in C<U0> mode (the default if the format
-string starts with C<U>) and it would return the bytes making up the UTF-8
-encoding of the target string, something that will always work.
-
-=item *
-
-How Do I Convert Binary Data Into a Particular Encoding, Or Vice Versa?
-
-This probably isn't as useful as you might think.
-Normally, you shouldn't need to.
-
-In one sense, what you are asking doesn't make much sense: encodings
-are for characters, and binary data are not "characters", so converting
-"data" into some encoding isn't meaningful unless you know in what
-character set and encoding the binary data is in, in which case it's
-not just binary data, now is it?
-
-If you have a raw sequence of bytes that you know should be
-interpreted via a particular encoding, you can use C<Encode>:
-
- use Encode 'from_to';
- from_to($data, "iso-8859-1", "utf-8"); # from latin-1 to utf-8
-
-The call to C<from_to()> changes the bytes in C<$data>, but nothing
-material about the nature of the string has changed as far as Perl is
-concerned. Both before and after the call, the string C<$data>
-contains just a bunch of 8-bit bytes. As far as Perl is concerned,
-the encoding of the string remains as "system-native 8-bit bytes".
-
-You might relate this to a fictional 'Translate' module:
-
- use Translate;
- my $phrase = "Yes";
- Translate::from_to($phrase, 'english', 'deutsch');
- ## phrase now contains "Ja"
-
-The contents of the string changes, but not the nature of the string.
-Perl doesn't know any more after the call than before that the
-contents of the string indicates the affirmative.
-
-Back to converting data. If you have (or want) data in your system's
-native 8-bit encoding (e.g. Latin-1, EBCDIC, etc.), you can use
-pack/unpack to convert to/from Unicode.
-
- $native_string = pack("W*", unpack("U*", $Unicode_string));
- $Unicode_string = pack("U*", unpack("W*", $native_string));
-
-If you have a sequence of bytes you B<know> is valid UTF-8,
-but Perl doesn't know it yet, you can make Perl a believer, too:
-
- use Encode 'decode_utf8';
- $Unicode = decode_utf8($bytes);
-
-or:
-
- $Unicode = pack("U0a*", $bytes);
-
-You can find the bytes that make up a UTF-8 sequence with
-
- @bytes = unpack("C*", $Unicode_string)
-
-and you can create well-formed Unicode with
-
- $Unicode_string = pack("U*", 0xff, ...)
-
-=item *
-
-How Do I Display Unicode? How Do I Input Unicode?
-
-See L<http://www.alanwood.net/unicode/> and
-L<http://www.cl.cam.ac.uk/~mgk25/unicode.html>
-
-=item *
-
-How Does Unicode Work With Traditional Locales?
-
-Starting in Perl 5.16, you can specify
-
- use locale ':not_characters';
-
-to get Perl to work well with tradtional locales. The catch is that you
-have to translate from the locale character set to/from Unicode
-yourself. See L</Unicode IE<sol>O> above for how to
-
- use open ':locale';
-
-to accomplish this, but full details are in L<perllocale/Unicode and
-UTF-8>, including gotchas that happen if you don't specifiy
-C<:not_characters>.
-
-=back
-
-=head2 Hexadecimal Notation
-
-The Unicode standard prefers using hexadecimal notation because
-that more clearly shows the division of Unicode into blocks of 256 characters.
-Hexadecimal is also simply shorter than decimal. You can use decimal
-notation, too, but learning to use hexadecimal just makes life easier
-with the Unicode standard. The C<U+HHHH> notation uses hexadecimal,
-for example.
-
-The C<0x> prefix means a hexadecimal number, the digits are 0-9 I<and>
-a-f (or A-F, case doesn't matter). Each hexadecimal digit represents
-four bits, or half a byte. C<print 0x..., "\n"> will show a
-hexadecimal number in decimal, and C<printf "%x\n", $decimal> will
-show a decimal number in hexadecimal. If you have just the
-"hex digits" of a hexadecimal number, you can use the C<hex()> function.
-
- print 0x0009, "\n"; # 9
- print 0x000a, "\n"; # 10
- print 0x000f, "\n"; # 15
- print 0x0010, "\n"; # 16
- print 0x0011, "\n"; # 17
- print 0x0100, "\n"; # 256
-
- print 0x0041, "\n"; # 65
-
- printf "%x\n", 65; # 41
- printf "%#x\n", 65; # 0x41
-
- print hex("41"), "\n"; # 65
-
-=head2 Further Resources
-
-=over 4
-
-=item *
-
-Unicode Consortium
-
-L<http://www.unicode.org/>
-
-=item *
-
-Unicode FAQ
-
-L<http://www.unicode.org/unicode/faq/>
-
-=item *
-
-Unicode Glossary
-
-L<http://www.unicode.org/glossary/>
-
-=item *
-
-Unicode Recommended Reading List
-
-The Unicode Consortium has a list of articles and books, some of which
-give a much more in depth treatment of Unicode:
-L<http://unicode.org/resources/readinglist.html>
-
-=item *
-
-Unicode Useful Resources
-
-L<http://www.unicode.org/unicode/onlinedat/resources.html>
-
-=item *
-
-Unicode and Multilingual Support in HTML, Fonts, Web Browsers and Other Applications
-
-L<http://www.alanwood.net/unicode/>
-
-=item *
-
-UTF-8 and Unicode FAQ for Unix/Linux
-
-L<http://www.cl.cam.ac.uk/~mgk25/unicode.html>
-
-=item *
-
-Legacy Character Sets
-
-L<http://www.czyborra.com/>
-L<http://www.eki.ee/letter/>
-
-=item *
-
-You can explore various information from the Unicode data files using
-the C<Unicode::UCD> module.
-
-=back
-
-=head1 UNICODE IN OLDER PERLS
-
-If you cannot upgrade your Perl to 5.8.0 or later, you can still
-do some Unicode processing by using the modules C<Unicode::String>,
-C<Unicode::Map8>, and C<Unicode::Map>, available from CPAN.
-If you have the GNU recode installed, you can also use the
-Perl front-end C<Convert::Recode> for character conversions.
-
-The following are fast conversions from ISO 8859-1 (Latin-1) bytes
-to UTF-8 bytes and back, the code works even with older Perl 5 versions.
-
- # ISO 8859-1 to UTF-8
- s/([\x80-\xFF])/chr(0xC0|ord($1)>>6).chr(0x80|ord($1)&0x3F)/eg;
-
- # UTF-8 to ISO 8859-1
- s/([\xC2\xC3])([\x80-\xBF])/chr(ord($1)<<6&0xC0|ord($2)&0x3F)/eg;
-
-=head1 SEE ALSO
-
-L<perlunitut>, L<perlunicode>, L<Encode>, L<open>, L<utf8>, L<bytes>,
-L<perlretut>, L<perlrun>, L<Unicode::Collate>, L<Unicode::Normalize>,
-L<Unicode::UCD>
-
-=head1 ACKNOWLEDGMENTS
-
-Thanks to the kind readers of the perl5-porters@perl.org,
-perl-unicode@perl.org, linux-utf8@nl.linux.org, and unicore@unicode.org
-mailing lists for their valuable feedback.
-
-=head1 AUTHOR, COPYRIGHT, AND LICENSE
-
-Copyright 2001-2011 Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>
-
-This document may be distributed under the same terms as Perl itself.
diff --git a/Master/tlpkg/tlperl/lib/pods/perluniprops.pod b/Master/tlpkg/tlperl/lib/pods/perluniprops.pod
deleted file mode 100644
index 91bf37c8284..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perluniprops.pod
+++ /dev/null
@@ -1,4306 +0,0 @@
-=begin comment
-
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-
-To change this file, edit mktables instead.
-
-=end comment
-
-=head1 NAME
-
-perluniprops - Index of Unicode Version 6.1.0 character properties in Perl
-
-=head1 DESCRIPTION
-
-This document provides information about the portion of the Unicode database
-that deals with character properties, that is the portion that is defined on
-single code points. (L</Other information in the Unicode data base>
-below briefly mentions other data that Unicode provides.)
-
-Perl can provide access to all non-provisional Unicode character properties,
-though not all are enabled by default. The omitted ones are the Unihan
-properties (accessible via the CPAN module L<Unicode::Unihan>) and certain
-deprecated or Unicode-internal properties. (An installation may choose to
-recompile Perl's tables to change this. See L<Unicode character
-properties that are NOT accepted by Perl>.)
-
-For most purposes, access to Unicode properties from the Perl core is through
-regular expression matches, as described in the next section.
-For some special purposes, and to access the properties that are not suitable
-for regular expression matching, all the Unicode character properties that
-Perl handles are accessible via the standard L<Unicode::UCD> module, as
-described in the section L</Properties accessible through Unicode::UCD>.
-
-Perl also provides some additional extensions and short-cut synonyms
-for Unicode properties.
-
-This document merely lists all available properties and does not attempt to
-explain what each property really means. There is a brief description of each
-Perl extension; see L<perlunicode/Other Properties> for more information on
-these. There is some detail about Blocks, Scripts, General_Category,
-and Bidi_Class in L<perlunicode>, but to find out about the intricacies of the
-official Unicode properties, refer to the Unicode standard. A good starting
-place is L<http://www.unicode.org/reports/tr44/>.
-
-Note that you can define your own properties; see
-L<perlunicode/"User-Defined Character Properties">.
-
-=head1 Properties accessible through C<\p{}> and C<\P{}>
-
-The Perl regular expression C<\p{}> and C<\P{}> constructs give access to
-most of the Unicode character properties. The table below shows all these
-constructs, both single and compound forms.
-
-B<Compound forms> consist of two components, separated by an equals sign or a
-colon. The first component is the property name, and the second component is
-the particular value of the property to match against, for example,
-C<\p{Script: Greek}> and C<\p{Script=Greek}> both mean to match characters
-whose Script property is Greek.
-
-B<Single forms>, like C<\p{Greek}>, are mostly Perl-defined shortcuts for
-their equivalent compound forms. The table shows these equivalences. (In our
-example, C<\p{Greek}> is a just a shortcut for C<\p{Script=Greek}>.)
-There are also a few Perl-defined single forms that are not shortcuts for a
-compound form. One such is C<\p{Word}>. These are also listed in the table.
-
-In parsing these constructs, Perl always ignores Upper/lower case differences
-everywhere within the {braces}. Thus C<\p{Greek}> means the same thing as
-C<\p{greek}>. But note that changing the case of the C<"p"> or C<"P"> before
-the left brace completely changes the meaning of the construct, from "match"
-(for C<\p{}>) to "doesn't match" (for C<\P{}>). Casing in this document is
-for improved legibility.
-
-Also, white space, hyphens, and underscores are also normally ignored
-everywhere between the {braces}, and hence can be freely added or removed
-even if the C</x> modifier hasn't been specified on the regular expression.
-But a 'B<T>' at the beginning of an entry in the table below
-means that tighter (stricter) rules are used for that entry:
-
-=over 4
-
-=item Single form (C<\p{name}>) tighter rules:
-
-White space, hyphens, and underscores ARE significant
-except for:
-
-=over 4
-
-=item * white space adjacent to a non-word character
-
-=item * underscores separating digits in numbers
-
-=back
-
-That means, for example, that you can freely add or remove white space
-adjacent to (but within) the braces without affecting the meaning.
-
-=item Compound form (C<\p{name=value}> or C<\p{name:value}>) tighter rules:
-
-The tighter rules given above for the single form apply to everything to the
-right of the colon or equals; the looser rules still apply to everything to
-the left.
-
-That means, for example, that you can freely add or remove white space
-adjacent to (but within) the braces and the colon or equal sign.
-
-=back
-
-Some properties are considered obsolete by Unicode, but still available.
-There are several varieties of obsolescence:
-
-=over 4
-
-=item Stabilized
-
-A property may be stabilized. Such a determination does not indicate
-that the property should or should not be used; instead it is a declaration
-that the property will not be maintained nor extended for newly encoded
-characters. Such properties are marked with an 'B<S>' in the
-table.
-
-=item Deprecated
-
-A property may be deprecated, perhaps because its original intent
-has been replaced by another property, or because its specification was
-somehow defective. This means that its use is strongly
-discouraged, so much so that a warning will be issued if used, unless the
-regular expression is in the scope of a C<S<no warnings 'deprecated'>>
-statement. A 'B<D>' flags each such entry in the table, and
-the entry there for the longest, most descriptive version of the property will
-give the reason it is deprecated, and perhaps advice. Perl may issue such a
-warning, even for properties that aren't officially deprecated by Unicode,
-when there used to be characters or code points that were matched by them, but
-no longer. This is to warn you that your program may not work like it did on
-earlier Unicode releases.
-
-A deprecated property may be made unavailable in a future Perl version, so it
-is best to move away from them.
-
-A deprecated property may also be stabilized, but this fact is not shown.
-
-=item Obsolete
-
-Properties marked with an 'B<O>' in the table are considered (plain)
-obsolete. Generally this designation is given to properties that Unicode once
-used for internal purposes (but not any longer).
-
-=back
-
-Some Perl extensions are present for backwards compatibility and are
-discouraged from being used, but are not obsolete. An 'B<X>'
-flags each such entry in the table. Future Unicode versions may force
-some of these extensions to be removed without warning, replaced by another
-property with the same name that means something different. Use the
-equivalent shown instead.
-
-
-Matches in the Block property have shortcuts that begin with "In_". For
-example, C<\p{Block=Latin1}> can be written as C<\p{In_Latin1}>. For
-backward compatibility, if there is no conflict with another shortcut, these
-may also be written as C<\p{Latin1}> or C<\p{Is_Latin1}>. But, N.B., there
-are numerous such conflicting shortcuts. Use of these forms for Block is
-discouraged, and are flagged as such, not only because of the potential
-confusion as to what is meant, but also because a later release of Unicode may
-preempt the shortcut, and your program would no longer be correct. Use the
-"In_" form instead to avoid this, or even more clearly, use the compound form,
-e.g., C<\p{blk:latin1}>. See L<perlunicode/"Blocks"> for more information
-about this.
-
-
-The table below has two columns. The left column contains the C<\p{}>
-constructs to look up, possibly preceded by the flags mentioned above; and
-the right column contains information about them, like a description, or
-synonyms. It shows both the single and compound forms for each property that
-has them. If the left column is a short name for a property, the right column
-will give its longer, more descriptive name; and if the left column is the
-longest name, the right column will show any equivalent shortest name, in both
-single and compound forms if applicable.
-
-The right column will also caution you if a property means something different
-than what might normally be expected.
-
-All single forms are Perl extensions; a few compound forms are as well, and
-are noted as such.
-
-Numbers in (parentheses) indicate the total number of code points matched by
-the property. For emphasis, those properties that match no code points at all
-are listed as well in a separate section following the table.
-
-Most properties match the same code points regardless of whether C<"/i">
-case-insensitive matching is specified or not. But a few properties are
-affected. These are shown with the notation
-
- (/i= other_property)
-
-in the second column. Under case-insensitive matching they match the
-same code pode points as the property "other_property".
-
-There is no description given for most non-Perl defined properties (See
-L<http://www.unicode.org/reports/tr44/> for that).
-
-For compactness, 'B<*>' is used as a wildcard instead of showing all possible
-combinations. For example, entries like:
-
- \p{Gc: *} \p{General_Category: *}
-
-mean that 'Gc' is a synonym for 'General_Category', and anything that is valid
-for the latter is also valid for the former. Similarly,
-
- \p{Is_*} \p{*}
-
-means that if and only if, for example, C<\p{Foo}> exists, then
-C<\p{Is_Foo}> and C<\p{IsFoo}> are also valid and all mean the same thing.
-And similarly, C<\p{Foo=Bar}> means the same as C<\p{Is_Foo=Bar}> and
-C<\p{IsFoo=Bar}>. "*" here is restricted to something not beginning with an
-underscore.
-
-Also, in binary properties, 'Yes', 'T', and 'True' are all synonyms for 'Y'.
-And 'No', 'F', and 'False' are all synonyms for 'N'. The table shows 'Y*' and
-'N*' to indicate this, and doesn't have separate entries for the other
-possibilities. Note that not all properties which have values 'Yes' and 'No'
-are binary, and they have all their values spelled out without using this wild
-card, and a C<NOT> clause in their description that highlights their not being
-binary. These also require the compound form to match them, whereas true
-binary properties have both single and compound forms available.
-
-Note that all non-essential underscores are removed in the display of the
-short names below.
-
-B<Legend summary:>
-
-=over 4
-
-=item Z<>B<*> is a wild-card
-
-=item B<(\d+)> in the info column gives the number of code points matched by
-this property.
-
-=item B<D> means this is deprecated.
-
-=item B<O> means this is obsolete.
-
-=item B<S> means this is stabilized.
-
-=item B<T> means tighter (stricter) name matching applies.
-
-=item B<X> means use of this form is discouraged, and may not be
-stable.
-
-=back
-
- NAME INFO
-
- X \p{Aegean_Numbers} \p{Block=Aegean_Numbers} (64)
- T \p{Age: 1.1} \p{Age=V1_1} (33_979)
- T \p{Age: 2.0} \p{Age=V2_0} (144_521)
- T \p{Age: 2.1} \p{Age=V2_1} (2)
- T \p{Age: 3.0} \p{Age=V3_0} (10_307)
- T \p{Age: 3.1} \p{Age=V3_1} (44_978)
- T \p{Age: 3.2} \p{Age=V3_2} (1016)
- T \p{Age: 4.0} \p{Age=V4_0} (1226)
- T \p{Age: 4.1} \p{Age=V4_1} (1273)
- T \p{Age: 5.0} \p{Age=V5_0} (1369)
- T \p{Age: 5.1} \p{Age=V5_1} (1624)
- T \p{Age: 5.2} \p{Age=V5_2} (6648)
- T \p{Age: 6.0} \p{Age=V6_0} (2088)
- T \p{Age: 6.1} \p{Age=V6_1} (732)
- \p{Age: NA} \p{Age=Unassigned} (864_349)
- \p{Age: Unassigned} Code point's usage has not been assigned
- in any Unicode release thus far. (Short:
- \p{Age=NA}) (864_349)
- \p{Age: V1_1} Code point's usage introduced in version
- 1.1 (33_979)
- \p{Age: V2_0} Code point's usage was introduced in
- version 2.0; See also Property
- 'Present_In' (144_521)
- \p{Age: V2_1} Code point's usage was introduced in
- version 2.1; See also Property
- 'Present_In' (2)
- \p{Age: V3_0} Code point's usage was introduced in
- version 3.0; See also Property
- 'Present_In' (10_307)
- \p{Age: V3_1} Code point's usage was introduced in
- version 3.1; See also Property
- 'Present_In' (44_978)
- \p{Age: V3_2} Code point's usage was introduced in
- version 3.2; See also Property
- 'Present_In' (1016)
- \p{Age: V4_0} Code point's usage was introduced in
- version 4.0; See also Property
- 'Present_In' (1226)
- \p{Age: V4_1} Code point's usage was introduced in
- version 4.1; See also Property
- 'Present_In' (1273)
- \p{Age: V5_0} Code point's usage was introduced in
- version 5.0; See also Property
- 'Present_In' (1369)
- \p{Age: V5_1} Code point's usage was introduced in
- version 5.1; See also Property
- 'Present_In' (1624)
- \p{Age: V5_2} Code point's usage was introduced in
- version 5.2; See also Property
- 'Present_In' (6648)
- \p{Age: V6_0} Code point's usage was introduced in
- version 6.0; See also Property
- 'Present_In' (2088)
- \p{Age: V6_1} Code point's usage was introduced in
- version 6.1; See also Property
- 'Present_In' (732)
- \p{AHex} \p{PosixXDigit} (= \p{ASCII_Hex_Digit=Y})
- (22)
- \p{AHex: *} \p{ASCII_Hex_Digit: *}
- X \p{Alchemical} \p{Alchemical_Symbols} (= \p{Block=
- Alchemical_Symbols}) (128)
- X \p{Alchemical_Symbols} \p{Block=Alchemical_Symbols} (Short:
- \p{InAlchemical}) (128)
- \p{All} \p{Any} (1_114_112)
- \p{Alnum} Alphabetic and (decimal) Numeric (102_619)
- \p{Alpha} \p{Alphabetic=Y} (102_159)
- \p{Alpha: *} \p{Alphabetic: *}
- \p{Alphabetic} \p{Alpha} (= \p{Alphabetic=Y}) (102_159)
- \p{Alphabetic: N*} (Short: \p{Alpha=N}, \P{Alpha}) (1_011_953)
- \p{Alphabetic: Y*} (Short: \p{Alpha=Y}, \p{Alpha}) (102_159)
- X \p{Alphabetic_PF} \p{Alphabetic_Presentation_Forms} (=
- \p{Block=Alphabetic_Presentation_Forms})
- (80)
- X \p{Alphabetic_Presentation_Forms} \p{Block=
- Alphabetic_Presentation_Forms} (Short:
- \p{InAlphabeticPF}) (80)
- X \p{Ancient_Greek_Music} \p{Ancient_Greek_Musical_Notation} (=
- \p{Block=
- Ancient_Greek_Musical_Notation}) (80)
- X \p{Ancient_Greek_Musical_Notation} \p{Block=
- Ancient_Greek_Musical_Notation} (Short:
- \p{InAncientGreekMusic}) (80)
- X \p{Ancient_Greek_Numbers} \p{Block=Ancient_Greek_Numbers} (80)
- X \p{Ancient_Symbols} \p{Block=Ancient_Symbols} (64)
- \p{Any} [\x{0000}-\x{10FFFF}] (1_114_112)
- \p{Arab} \p{Arabic} (= \p{Script=Arabic}) (NOT
- \p{Block=Arabic}) (1234)
- \p{Arabic} \p{Script=Arabic} (Short: \p{Arab}; NOT
- \p{Block=Arabic}) (1234)
- X \p{Arabic_Ext_A} \p{Arabic_Extended_A} (= \p{Block=
- Arabic_Extended_A}) (96)
- X \p{Arabic_Extended_A} \p{Block=Arabic_Extended_A} (Short:
- \p{InArabicExtA}) (96)
- X \p{Arabic_Math} \p{Arabic_Mathematical_Alphabetic_Symbols}
- (= \p{Block=
- Arabic_Mathematical_Alphabetic_Symbols})
- (256)
- X \p{Arabic_Mathematical_Alphabetic_Symbols} \p{Block=
- Arabic_Mathematical_Alphabetic_Symbols}
- (Short: \p{InArabicMath}) (256)
- X \p{Arabic_PF_A} \p{Arabic_Presentation_Forms_A} (=
- \p{Block=Arabic_Presentation_Forms_A})
- (688)
- X \p{Arabic_PF_B} \p{Arabic_Presentation_Forms_B} (=
- \p{Block=Arabic_Presentation_Forms_B})
- (144)
- X \p{Arabic_Presentation_Forms_A} \p{Block=
- Arabic_Presentation_Forms_A} (Short:
- \p{InArabicPFA}) (688)
- X \p{Arabic_Presentation_Forms_B} \p{Block=
- Arabic_Presentation_Forms_B} (Short:
- \p{InArabicPFB}) (144)
- X \p{Arabic_Sup} \p{Arabic_Supplement} (= \p{Block=
- Arabic_Supplement}) (48)
- X \p{Arabic_Supplement} \p{Block=Arabic_Supplement} (Short:
- \p{InArabicSup}) (48)
- \p{Armenian} \p{Script=Armenian} (Short: \p{Armn}; NOT
- \p{Block=Armenian}) (91)
- \p{Armi} \p{Imperial_Aramaic} (= \p{Script=
- Imperial_Aramaic}) (NOT \p{Block=
- Imperial_Aramaic}) (31)
- \p{Armn} \p{Armenian} (= \p{Script=Armenian}) (NOT
- \p{Block=Armenian}) (91)
- X \p{Arrows} \p{Block=Arrows} (112)
- \p{ASCII} \p{Block=Basic_Latin} [[:ASCII:]] (128)
- \p{ASCII_Hex_Digit} \p{PosixXDigit} (= \p{ASCII_Hex_Digit=Y})
- (22)
- \p{ASCII_Hex_Digit: N*} (Short: \p{AHex=N}, \P{AHex}) (1_114_090)
- \p{ASCII_Hex_Digit: Y*} (Short: \p{AHex=Y}, \p{AHex}) (22)
- \p{Assigned} All assigned code points (249_697)
- \p{Avestan} \p{Script=Avestan} (Short: \p{Avst}; NOT
- \p{Block=Avestan}) (61)
- \p{Avst} \p{Avestan} (= \p{Script=Avestan}) (NOT
- \p{Block=Avestan}) (61)
- \p{Bali} \p{Balinese} (= \p{Script=Balinese}) (NOT
- \p{Block=Balinese}) (121)
- \p{Balinese} \p{Script=Balinese} (Short: \p{Bali}; NOT
- \p{Block=Balinese}) (121)
- \p{Bamu} \p{Bamum} (= \p{Script=Bamum}) (NOT
- \p{Block=Bamum}) (657)
- \p{Bamum} \p{Script=Bamum} (Short: \p{Bamu}; NOT
- \p{Block=Bamum}) (657)
- X \p{Bamum_Sup} \p{Bamum_Supplement} (= \p{Block=
- Bamum_Supplement}) (576)
- X \p{Bamum_Supplement} \p{Block=Bamum_Supplement} (Short:
- \p{InBamumSup}) (576)
- X \p{Basic_Latin} \p{ASCII} (= \p{Block=Basic_Latin}) (128)
- \p{Batak} \p{Script=Batak} (Short: \p{Batk}; NOT
- \p{Block=Batak}) (56)
- \p{Batk} \p{Batak} (= \p{Script=Batak}) (NOT
- \p{Block=Batak}) (56)
- \p{Bc: *} \p{Bidi_Class: *}
- \p{Beng} \p{Bengali} (= \p{Script=Bengali}) (NOT
- \p{Block=Bengali}) (92)
- \p{Bengali} \p{Script=Bengali} (Short: \p{Beng}; NOT
- \p{Block=Bengali}) (92)
- \p{Bidi_C} \p{Bidi_Control} (= \p{Bidi_Control=Y}) (7)
- \p{Bidi_C: *} \p{Bidi_Control: *}
- \p{Bidi_Class: AL} \p{Bidi_Class=Arabic_Letter} (1438)
- \p{Bidi_Class: AN} \p{Bidi_Class=Arabic_Number} (49)
- \p{Bidi_Class: Arabic_Letter} (Short: \p{Bc=AL}) (1438)
- \p{Bidi_Class: Arabic_Number} (Short: \p{Bc=AN}) (49)
- \p{Bidi_Class: B} \p{Bidi_Class=Paragraph_Separator} (7)
- \p{Bidi_Class: BN} \p{Bidi_Class=Boundary_Neutral} (4015)
- \p{Bidi_Class: Boundary_Neutral} (Short: \p{Bc=BN}) (4015)
- \p{Bidi_Class: Common_Separator} (Short: \p{Bc=CS}) (15)
- \p{Bidi_Class: CS} \p{Bidi_Class=Common_Separator} (15)
- \p{Bidi_Class: EN} \p{Bidi_Class=European_Number} (131)
- \p{Bidi_Class: ES} \p{Bidi_Class=European_Separator} (12)
- \p{Bidi_Class: ET} \p{Bidi_Class=European_Terminator} (65)
- \p{Bidi_Class: European_Number} (Short: \p{Bc=EN}) (131)
- \p{Bidi_Class: European_Separator} (Short: \p{Bc=ES}) (12)
- \p{Bidi_Class: European_Terminator} (Short: \p{Bc=ET}) (65)
- \p{Bidi_Class: L} \p{Bidi_Class=Left_To_Right} (1_098_531)
- \p{Bidi_Class: Left_To_Right} (Short: \p{Bc=L}) (1_098_531)
- \p{Bidi_Class: Left_To_Right_Embedding} (Short: \p{Bc=LRE}) (1)
- \p{Bidi_Class: Left_To_Right_Override} (Short: \p{Bc=LRO}) (1)
- \p{Bidi_Class: LRE} \p{Bidi_Class=Left_To_Right_Embedding} (1)
- \p{Bidi_Class: LRO} \p{Bidi_Class=Left_To_Right_Override} (1)
- \p{Bidi_Class: Nonspacing_Mark} (Short: \p{Bc=NSM}) (1290)
- \p{Bidi_Class: NSM} \p{Bidi_Class=Nonspacing_Mark} (1290)
- \p{Bidi_Class: ON} \p{Bidi_Class=Other_Neutral} (4447)
- \p{Bidi_Class: Other_Neutral} (Short: \p{Bc=ON}) (4447)
- \p{Bidi_Class: Paragraph_Separator} (Short: \p{Bc=B}) (7)
- \p{Bidi_Class: PDF} \p{Bidi_Class=Pop_Directional_Format} (1)
- \p{Bidi_Class: Pop_Directional_Format} (Short: \p{Bc=PDF}) (1)
- \p{Bidi_Class: R} \p{Bidi_Class=Right_To_Left} (4086)
- \p{Bidi_Class: Right_To_Left} (Short: \p{Bc=R}) (4086)
- \p{Bidi_Class: Right_To_Left_Embedding} (Short: \p{Bc=RLE}) (1)
- \p{Bidi_Class: Right_To_Left_Override} (Short: \p{Bc=RLO}) (1)
- \p{Bidi_Class: RLE} \p{Bidi_Class=Right_To_Left_Embedding} (1)
- \p{Bidi_Class: RLO} \p{Bidi_Class=Right_To_Left_Override} (1)
- \p{Bidi_Class: S} \p{Bidi_Class=Segment_Separator} (3)
- \p{Bidi_Class: Segment_Separator} (Short: \p{Bc=S}) (3)
- \p{Bidi_Class: White_Space} (Short: \p{Bc=WS}) (18)
- \p{Bidi_Class: WS} \p{Bidi_Class=White_Space} (18)
- \p{Bidi_Control} \p{Bidi_Control=Y} (Short: \p{BidiC}) (7)
- \p{Bidi_Control: N*} (Short: \p{BidiC=N}, \P{BidiC}) (1_114_105)
- \p{Bidi_Control: Y*} (Short: \p{BidiC=Y}, \p{BidiC}) (7)
- \p{Bidi_M} \p{Bidi_Mirrored} (= \p{Bidi_Mirrored=Y})
- (545)
- \p{Bidi_M: *} \p{Bidi_Mirrored: *}
- \p{Bidi_Mirrored} \p{Bidi_Mirrored=Y} (Short: \p{BidiM})
- (545)
- \p{Bidi_Mirrored: N*} (Short: \p{BidiM=N}, \P{BidiM}) (1_113_567)
- \p{Bidi_Mirrored: Y*} (Short: \p{BidiM=Y}, \p{BidiM}) (545)
- \p{Blank} \h, Horizontal white space (19)
- \p{Blk: *} \p{Block: *}
- \p{Block: Aegean_Numbers} (Single: \p{InAegeanNumbers}) (64)
- \p{Block: Alchemical} \p{Block=Alchemical_Symbols} (128)
- \p{Block: Alchemical_Symbols} (Short: \p{Blk=Alchemical},
- \p{InAlchemical}) (128)
- \p{Block: Alphabetic_PF} \p{Block=Alphabetic_Presentation_Forms}
- (80)
- \p{Block: Alphabetic_Presentation_Forms} (Short: \p{Blk=
- AlphabeticPF}, \p{InAlphabeticPF}) (80)
- \p{Block: Ancient_Greek_Music} \p{Block=
- Ancient_Greek_Musical_Notation} (80)
- \p{Block: Ancient_Greek_Musical_Notation} (Short: \p{Blk=
- AncientGreekMusic},
- \p{InAncientGreekMusic}) (80)
- \p{Block: Ancient_Greek_Numbers} (Single:
- \p{InAncientGreekNumbers}) (80)
- \p{Block: Ancient_Symbols} (Single: \p{InAncientSymbols}) (64)
- \p{Block: Arabic} (Single: \p{InArabic}; NOT \p{Arabic} NOR
- \p{Is_Arabic}) (256)
- \p{Block: Arabic_Ext_A} \p{Block=Arabic_Extended_A} (96)
- \p{Block: Arabic_Extended_A} (Short: \p{Blk=ArabicExtA},
- \p{InArabicExtA}) (96)
- \p{Block: Arabic_Math} \p{Block=
- Arabic_Mathematical_Alphabetic_Symbols}
- (256)
- \p{Block: Arabic_Mathematical_Alphabetic_Symbols} (Short: \p{Blk=
- ArabicMath}, \p{InArabicMath}) (256)
- \p{Block: Arabic_PF_A} \p{Block=Arabic_Presentation_Forms_A} (688)
- \p{Block: Arabic_PF_B} \p{Block=Arabic_Presentation_Forms_B} (144)
- \p{Block: Arabic_Presentation_Forms_A} (Short: \p{Blk=ArabicPFA},
- \p{InArabicPFA}) (688)
- \p{Block: Arabic_Presentation_Forms_B} (Short: \p{Blk=ArabicPFB},
- \p{InArabicPFB}) (144)
- \p{Block: Arabic_Sup} \p{Block=Arabic_Supplement} (48)
- \p{Block: Arabic_Supplement} (Short: \p{Blk=ArabicSup},
- \p{InArabicSup}) (48)
- \p{Block: Armenian} (Single: \p{InArmenian}; NOT \p{Armenian}
- NOR \p{Is_Armenian}) (96)
- \p{Block: Arrows} (Single: \p{InArrows}) (112)
- \p{Block: ASCII} \p{Block=Basic_Latin} (128)
- \p{Block: Avestan} (Single: \p{InAvestan}; NOT \p{Avestan}
- NOR \p{Is_Avestan}) (64)
- \p{Block: Balinese} (Single: \p{InBalinese}; NOT \p{Balinese}
- NOR \p{Is_Balinese}) (128)
- \p{Block: Bamum} (Single: \p{InBamum}; NOT \p{Bamum} NOR
- \p{Is_Bamum}) (96)
- \p{Block: Bamum_Sup} \p{Block=Bamum_Supplement} (576)
- \p{Block: Bamum_Supplement} (Short: \p{Blk=BamumSup},
- \p{InBamumSup}) (576)
- \p{Block: Basic_Latin} (Short: \p{Blk=ASCII}, \p{ASCII}) (128)
- \p{Block: Batak} (Single: \p{InBatak}; NOT \p{Batak} NOR
- \p{Is_Batak}) (64)
- \p{Block: Bengali} (Single: \p{InBengali}; NOT \p{Bengali}
- NOR \p{Is_Bengali}) (128)
- \p{Block: Block_Elements} (Single: \p{InBlockElements}) (32)
- \p{Block: Bopomofo} (Single: \p{InBopomofo}; NOT \p{Bopomofo}
- NOR \p{Is_Bopomofo}) (48)
- \p{Block: Bopomofo_Ext} \p{Block=Bopomofo_Extended} (32)
- \p{Block: Bopomofo_Extended} (Short: \p{Blk=BopomofoExt},
- \p{InBopomofoExt}) (32)
- \p{Block: Box_Drawing} (Single: \p{InBoxDrawing}) (128)
- \p{Block: Brahmi} (Single: \p{InBrahmi}; NOT \p{Brahmi} NOR
- \p{Is_Brahmi}) (128)
- \p{Block: Braille} \p{Block=Braille_Patterns} (256)
- \p{Block: Braille_Patterns} (Short: \p{Blk=Braille},
- \p{InBraille}) (256)
- \p{Block: Buginese} (Single: \p{InBuginese}; NOT \p{Buginese}
- NOR \p{Is_Buginese}) (32)
- \p{Block: Buhid} (Single: \p{InBuhid}; NOT \p{Buhid} NOR
- \p{Is_Buhid}) (32)
- \p{Block: Byzantine_Music} \p{Block=Byzantine_Musical_Symbols}
- (256)
- \p{Block: Byzantine_Musical_Symbols} (Short: \p{Blk=
- ByzantineMusic}, \p{InByzantineMusic})
- (256)
- \p{Block: Canadian_Syllabics} \p{Block=
- Unified_Canadian_Aboriginal_Syllabics}
- (640)
- \p{Block: Carian} (Single: \p{InCarian}; NOT \p{Carian} NOR
- \p{Is_Carian}) (64)
- \p{Block: Chakma} (Single: \p{InChakma}; NOT \p{Chakma} NOR
- \p{Is_Chakma}) (80)
- \p{Block: Cham} (Single: \p{InCham}; NOT \p{Cham} NOR
- \p{Is_Cham}) (96)
- \p{Block: Cherokee} (Single: \p{InCherokee}; NOT \p{Cherokee}
- NOR \p{Is_Cherokee}) (96)
- \p{Block: CJK} \p{Block=CJK_Unified_Ideographs} (20_992)
- \p{Block: CJK_Compat} \p{Block=CJK_Compatibility} (256)
- \p{Block: CJK_Compat_Forms} \p{Block=CJK_Compatibility_Forms} (32)
- \p{Block: CJK_Compat_Ideographs} \p{Block=
- CJK_Compatibility_Ideographs} (512)
- \p{Block: CJK_Compat_Ideographs_Sup} \p{Block=
- CJK_Compatibility_Ideographs_Supplement}
- (544)
- \p{Block: CJK_Compatibility} (Short: \p{Blk=CJKCompat},
- \p{InCJKCompat}) (256)
- \p{Block: CJK_Compatibility_Forms} (Short: \p{Blk=CJKCompatForms},
- \p{InCJKCompatForms}) (32)
- \p{Block: CJK_Compatibility_Ideographs} (Short: \p{Blk=
- CJKCompatIdeographs},
- \p{InCJKCompatIdeographs}) (512)
- \p{Block: CJK_Compatibility_Ideographs_Supplement} (Short: \p{Blk=
- CJKCompatIdeographsSup},
- \p{InCJKCompatIdeographsSup}) (544)
- \p{Block: CJK_Ext_A} \p{Block=
- CJK_Unified_Ideographs_Extension_A}
- (6592)
- \p{Block: CJK_Ext_B} \p{Block=
- CJK_Unified_Ideographs_Extension_B}
- (42_720)
- \p{Block: CJK_Ext_C} \p{Block=
- CJK_Unified_Ideographs_Extension_C}
- (4160)
- \p{Block: CJK_Ext_D} \p{Block=
- CJK_Unified_Ideographs_Extension_D} (224)
- \p{Block: CJK_Radicals_Sup} \p{Block=CJK_Radicals_Supplement} (128)
- \p{Block: CJK_Radicals_Supplement} (Short: \p{Blk=CJKRadicalsSup},
- \p{InCJKRadicalsSup}) (128)
- \p{Block: CJK_Strokes} (Single: \p{InCJKStrokes}) (48)
- \p{Block: CJK_Symbols} \p{Block=CJK_Symbols_And_Punctuation} (64)
- \p{Block: CJK_Symbols_And_Punctuation} (Short: \p{Blk=CJKSymbols},
- \p{InCJKSymbols}) (64)
- \p{Block: CJK_Unified_Ideographs} (Short: \p{Blk=CJK}, \p{InCJK})
- (20_992)
- \p{Block: CJK_Unified_Ideographs_Extension_A} (Short: \p{Blk=
- CJKExtA}, \p{InCJKExtA}) (6592)
- \p{Block: CJK_Unified_Ideographs_Extension_B} (Short: \p{Blk=
- CJKExtB}, \p{InCJKExtB}) (42_720)
- \p{Block: CJK_Unified_Ideographs_Extension_C} (Short: \p{Blk=
- CJKExtC}, \p{InCJKExtC}) (4160)
- \p{Block: CJK_Unified_Ideographs_Extension_D} (Short: \p{Blk=
- CJKExtD}, \p{InCJKExtD}) (224)
- \p{Block: Combining_Diacritical_Marks} (Short: \p{Blk=
- Diacriticals}, \p{InDiacriticals}) (112)
- \p{Block: Combining_Diacritical_Marks_For_Symbols} (Short: \p{Blk=
- DiacriticalsForSymbols},
- \p{InDiacriticalsForSymbols}) (48)
- \p{Block: Combining_Diacritical_Marks_Supplement} (Short: \p{Blk=
- DiacriticalsSup}, \p{InDiacriticalsSup})
- (64)
- \p{Block: Combining_Half_Marks} (Short: \p{Blk=HalfMarks},
- \p{InHalfMarks}) (16)
- \p{Block: Combining_Marks_For_Symbols} \p{Block=
- Combining_Diacritical_Marks_For_Symbols}
- (48)
- \p{Block: Common_Indic_Number_Forms} (Short: \p{Blk=
- IndicNumberForms},
- \p{InIndicNumberForms}) (16)
- \p{Block: Compat_Jamo} \p{Block=Hangul_Compatibility_Jamo} (96)
- \p{Block: Control_Pictures} (Single: \p{InControlPictures}) (64)
- \p{Block: Coptic} (Single: \p{InCoptic}; NOT \p{Coptic} NOR
- \p{Is_Coptic}) (128)
- \p{Block: Counting_Rod} \p{Block=Counting_Rod_Numerals} (32)
- \p{Block: Counting_Rod_Numerals} (Short: \p{Blk=CountingRod},
- \p{InCountingRod}) (32)
- \p{Block: Cuneiform} (Single: \p{InCuneiform}; NOT
- \p{Cuneiform} NOR \p{Is_Cuneiform})
- (1024)
- \p{Block: Cuneiform_Numbers} \p{Block=
- Cuneiform_Numbers_And_Punctuation} (128)
- \p{Block: Cuneiform_Numbers_And_Punctuation} (Short: \p{Blk=
- CuneiformNumbers},
- \p{InCuneiformNumbers}) (128)
- \p{Block: Currency_Symbols} (Single: \p{InCurrencySymbols}) (48)
- \p{Block: Cypriot_Syllabary} (Single: \p{InCypriotSyllabary}) (64)
- \p{Block: Cyrillic} (Single: \p{InCyrillic}; NOT \p{Cyrillic}
- NOR \p{Is_Cyrillic}) (256)
- \p{Block: Cyrillic_Ext_A} \p{Block=Cyrillic_Extended_A} (32)
- \p{Block: Cyrillic_Ext_B} \p{Block=Cyrillic_Extended_B} (96)
- \p{Block: Cyrillic_Extended_A} (Short: \p{Blk=CyrillicExtA},
- \p{InCyrillicExtA}) (32)
- \p{Block: Cyrillic_Extended_B} (Short: \p{Blk=CyrillicExtB},
- \p{InCyrillicExtB}) (96)
- \p{Block: Cyrillic_Sup} \p{Block=Cyrillic_Supplement} (48)
- \p{Block: Cyrillic_Supplement} (Short: \p{Blk=CyrillicSup},
- \p{InCyrillicSup}) (48)
- \p{Block: Cyrillic_Supplementary} \p{Block=Cyrillic_Supplement}
- (48)
- \p{Block: Deseret} (Single: \p{InDeseret}) (80)
- \p{Block: Devanagari} (Single: \p{InDevanagari}; NOT
- \p{Devanagari} NOR \p{Is_Devanagari})
- (128)
- \p{Block: Devanagari_Ext} \p{Block=Devanagari_Extended} (32)
- \p{Block: Devanagari_Extended} (Short: \p{Blk=DevanagariExt},
- \p{InDevanagariExt}) (32)
- \p{Block: Diacriticals} \p{Block=Combining_Diacritical_Marks} (112)
- \p{Block: Diacriticals_For_Symbols} \p{Block=
- Combining_Diacritical_Marks_For_Symbols}
- (48)
- \p{Block: Diacriticals_Sup} \p{Block=
- Combining_Diacritical_Marks_Supplement}
- (64)
- \p{Block: Dingbats} (Single: \p{InDingbats}) (192)
- \p{Block: Domino} \p{Block=Domino_Tiles} (112)
- \p{Block: Domino_Tiles} (Short: \p{Blk=Domino}, \p{InDomino}) (112)
- \p{Block: Egyptian_Hieroglyphs} (Single:
- \p{InEgyptianHieroglyphs}; NOT
- \p{Egyptian_Hieroglyphs} NOR
- \p{Is_Egyptian_Hieroglyphs}) (1072)
- \p{Block: Emoticons} (Single: \p{InEmoticons}) (80)
- \p{Block: Enclosed_Alphanum} \p{Block=Enclosed_Alphanumerics} (160)
- \p{Block: Enclosed_Alphanum_Sup} \p{Block=
- Enclosed_Alphanumeric_Supplement} (256)
- \p{Block: Enclosed_Alphanumeric_Supplement} (Short: \p{Blk=
- EnclosedAlphanumSup},
- \p{InEnclosedAlphanumSup}) (256)
- \p{Block: Enclosed_Alphanumerics} (Short: \p{Blk=
- EnclosedAlphanum},
- \p{InEnclosedAlphanum}) (160)
- \p{Block: Enclosed_CJK} \p{Block=Enclosed_CJK_Letters_And_Months}
- (256)
- \p{Block: Enclosed_CJK_Letters_And_Months} (Short: \p{Blk=
- EnclosedCJK}, \p{InEnclosedCJK}) (256)
- \p{Block: Enclosed_Ideographic_Sup} \p{Block=
- Enclosed_Ideographic_Supplement} (256)
- \p{Block: Enclosed_Ideographic_Supplement} (Short: \p{Blk=
- EnclosedIdeographicSup},
- \p{InEnclosedIdeographicSup}) (256)
- \p{Block: Ethiopic} (Single: \p{InEthiopic}; NOT \p{Ethiopic}
- NOR \p{Is_Ethiopic}) (384)
- \p{Block: Ethiopic_Ext} \p{Block=Ethiopic_Extended} (96)
- \p{Block: Ethiopic_Ext_A} \p{Block=Ethiopic_Extended_A} (48)
- \p{Block: Ethiopic_Extended} (Short: \p{Blk=EthiopicExt},
- \p{InEthiopicExt}) (96)
- \p{Block: Ethiopic_Extended_A} (Short: \p{Blk=EthiopicExtA},
- \p{InEthiopicExtA}) (48)
- \p{Block: Ethiopic_Sup} \p{Block=Ethiopic_Supplement} (32)
- \p{Block: Ethiopic_Supplement} (Short: \p{Blk=EthiopicSup},
- \p{InEthiopicSup}) (32)
- \p{Block: General_Punctuation} (Short: \p{Blk=Punctuation},
- \p{InPunctuation}; NOT \p{Punct} NOR
- \p{Is_Punctuation}) (112)
- \p{Block: Geometric_Shapes} (Single: \p{InGeometricShapes}) (96)
- \p{Block: Georgian} (Single: \p{InGeorgian}; NOT \p{Georgian}
- NOR \p{Is_Georgian}) (96)
- \p{Block: Georgian_Sup} \p{Block=Georgian_Supplement} (48)
- \p{Block: Georgian_Supplement} (Short: \p{Blk=GeorgianSup},
- \p{InGeorgianSup}) (48)
- \p{Block: Glagolitic} (Single: \p{InGlagolitic}; NOT
- \p{Glagolitic} NOR \p{Is_Glagolitic})
- (96)
- \p{Block: Gothic} (Single: \p{InGothic}; NOT \p{Gothic} NOR
- \p{Is_Gothic}) (32)
- \p{Block: Greek} \p{Block=Greek_And_Coptic} (NOT \p{Greek}
- NOR \p{Is_Greek}) (144)
- \p{Block: Greek_And_Coptic} (Short: \p{Blk=Greek}, \p{InGreek};
- NOT \p{Greek} NOR \p{Is_Greek}) (144)
- \p{Block: Greek_Ext} \p{Block=Greek_Extended} (256)
- \p{Block: Greek_Extended} (Short: \p{Blk=GreekExt},
- \p{InGreekExt}) (256)
- \p{Block: Gujarati} (Single: \p{InGujarati}; NOT \p{Gujarati}
- NOR \p{Is_Gujarati}) (128)
- \p{Block: Gurmukhi} (Single: \p{InGurmukhi}; NOT \p{Gurmukhi}
- NOR \p{Is_Gurmukhi}) (128)
- \p{Block: Half_And_Full_Forms} \p{Block=
- Halfwidth_And_Fullwidth_Forms} (240)
- \p{Block: Half_Marks} \p{Block=Combining_Half_Marks} (16)
- \p{Block: Halfwidth_And_Fullwidth_Forms} (Short: \p{Blk=
- HalfAndFullForms},
- \p{InHalfAndFullForms}) (240)
- \p{Block: Hangul} \p{Block=Hangul_Syllables} (NOT \p{Hangul}
- NOR \p{Is_Hangul}) (11_184)
- \p{Block: Hangul_Compatibility_Jamo} (Short: \p{Blk=CompatJamo},
- \p{InCompatJamo}) (96)
- \p{Block: Hangul_Jamo} (Short: \p{Blk=Jamo}, \p{InJamo}) (256)
- \p{Block: Hangul_Jamo_Extended_A} (Short: \p{Blk=JamoExtA},
- \p{InJamoExtA}) (32)
- \p{Block: Hangul_Jamo_Extended_B} (Short: \p{Blk=JamoExtB},
- \p{InJamoExtB}) (80)
- \p{Block: Hangul_Syllables} (Short: \p{Blk=Hangul}, \p{InHangul};
- NOT \p{Hangul} NOR \p{Is_Hangul})
- (11_184)
- \p{Block: Hanunoo} (Single: \p{InHanunoo}; NOT \p{Hanunoo}
- NOR \p{Is_Hanunoo}) (32)
- \p{Block: Hebrew} (Single: \p{InHebrew}; NOT \p{Hebrew} NOR
- \p{Is_Hebrew}) (112)
- \p{Block: High_Private_Use_Surrogates} (Short: \p{Blk=
- HighPUSurrogates},
- \p{InHighPUSurrogates}) (128)
- \p{Block: High_PU_Surrogates} \p{Block=
- High_Private_Use_Surrogates} (128)
- \p{Block: High_Surrogates} (Single: \p{InHighSurrogates}) (896)
- \p{Block: Hiragana} (Single: \p{InHiragana}; NOT \p{Hiragana}
- NOR \p{Is_Hiragana}) (96)
- \p{Block: IDC} \p{Block=
- Ideographic_Description_Characters} (NOT
- \p{ID_Continue} NOR \p{Is_IDC}) (16)
- \p{Block: Ideographic_Description_Characters} (Short: \p{Blk=IDC},
- \p{InIDC}; NOT \p{ID_Continue} NOR
- \p{Is_IDC}) (16)
- \p{Block: Imperial_Aramaic} (Single: \p{InImperialAramaic}; NOT
- \p{Imperial_Aramaic} NOR
- \p{Is_Imperial_Aramaic}) (32)
- \p{Block: Indic_Number_Forms} \p{Block=Common_Indic_Number_Forms}
- (16)
- \p{Block: Inscriptional_Pahlavi} (Single:
- \p{InInscriptionalPahlavi}; NOT
- \p{Inscriptional_Pahlavi} NOR
- \p{Is_Inscriptional_Pahlavi}) (32)
- \p{Block: Inscriptional_Parthian} (Single:
- \p{InInscriptionalParthian}; NOT
- \p{Inscriptional_Parthian} NOR
- \p{Is_Inscriptional_Parthian}) (32)
- \p{Block: IPA_Ext} \p{Block=IPA_Extensions} (96)
- \p{Block: IPA_Extensions} (Short: \p{Blk=IPAExt}, \p{InIPAExt})
- (96)
- \p{Block: Jamo} \p{Block=Hangul_Jamo} (256)
- \p{Block: Jamo_Ext_A} \p{Block=Hangul_Jamo_Extended_A} (32)
- \p{Block: Jamo_Ext_B} \p{Block=Hangul_Jamo_Extended_B} (80)
- \p{Block: Javanese} (Single: \p{InJavanese}; NOT \p{Javanese}
- NOR \p{Is_Javanese}) (96)
- \p{Block: Kaithi} (Single: \p{InKaithi}; NOT \p{Kaithi} NOR
- \p{Is_Kaithi}) (80)
- \p{Block: Kana_Sup} \p{Block=Kana_Supplement} (256)
- \p{Block: Kana_Supplement} (Short: \p{Blk=KanaSup}, \p{InKanaSup})
- (256)
- \p{Block: Kanbun} (Single: \p{InKanbun}) (16)
- \p{Block: Kangxi} \p{Block=Kangxi_Radicals} (224)
- \p{Block: Kangxi_Radicals} (Short: \p{Blk=Kangxi}, \p{InKangxi})
- (224)
- \p{Block: Kannada} (Single: \p{InKannada}; NOT \p{Kannada}
- NOR \p{Is_Kannada}) (128)
- \p{Block: Katakana} (Single: \p{InKatakana}; NOT \p{Katakana}
- NOR \p{Is_Katakana}) (96)
- \p{Block: Katakana_Ext} \p{Block=Katakana_Phonetic_Extensions} (16)
- \p{Block: Katakana_Phonetic_Extensions} (Short: \p{Blk=
- KatakanaExt}, \p{InKatakanaExt}) (16)
- \p{Block: Kayah_Li} (Single: \p{InKayahLi}) (48)
- \p{Block: Kharoshthi} (Single: \p{InKharoshthi}; NOT
- \p{Kharoshthi} NOR \p{Is_Kharoshthi})
- (96)
- \p{Block: Khmer} (Single: \p{InKhmer}; NOT \p{Khmer} NOR
- \p{Is_Khmer}) (128)
- \p{Block: Khmer_Symbols} (Single: \p{InKhmerSymbols}) (32)
- \p{Block: Lao} (Single: \p{InLao}; NOT \p{Lao} NOR
- \p{Is_Lao}) (128)
- \p{Block: Latin_1} \p{Block=Latin_1_Supplement} (128)
- \p{Block: Latin_1_Sup} \p{Block=Latin_1_Supplement} (128)
- \p{Block: Latin_1_Supplement} (Short: \p{Blk=Latin1},
- \p{InLatin1}) (128)
- \p{Block: Latin_Ext_A} \p{Block=Latin_Extended_A} (128)
- \p{Block: Latin_Ext_Additional} \p{Block=
- Latin_Extended_Additional} (256)
- \p{Block: Latin_Ext_B} \p{Block=Latin_Extended_B} (208)
- \p{Block: Latin_Ext_C} \p{Block=Latin_Extended_C} (32)
- \p{Block: Latin_Ext_D} \p{Block=Latin_Extended_D} (224)
- \p{Block: Latin_Extended_A} (Short: \p{Blk=LatinExtA},
- \p{InLatinExtA}) (128)
- \p{Block: Latin_Extended_Additional} (Short: \p{Blk=
- LatinExtAdditional},
- \p{InLatinExtAdditional}) (256)
- \p{Block: Latin_Extended_B} (Short: \p{Blk=LatinExtB},
- \p{InLatinExtB}) (208)
- \p{Block: Latin_Extended_C} (Short: \p{Blk=LatinExtC},
- \p{InLatinExtC}) (32)
- \p{Block: Latin_Extended_D} (Short: \p{Blk=LatinExtD},
- \p{InLatinExtD}) (224)
- \p{Block: Lepcha} (Single: \p{InLepcha}; NOT \p{Lepcha} NOR
- \p{Is_Lepcha}) (80)
- \p{Block: Letterlike_Symbols} (Single: \p{InLetterlikeSymbols})
- (80)
- \p{Block: Limbu} (Single: \p{InLimbu}; NOT \p{Limbu} NOR
- \p{Is_Limbu}) (80)
- \p{Block: Linear_B_Ideograms} (Single: \p{InLinearBIdeograms})
- (128)
- \p{Block: Linear_B_Syllabary} (Single: \p{InLinearBSyllabary})
- (128)
- \p{Block: Lisu} (Single: \p{InLisu}) (48)
- \p{Block: Low_Surrogates} (Single: \p{InLowSurrogates}) (1024)
- \p{Block: Lycian} (Single: \p{InLycian}; NOT \p{Lycian} NOR
- \p{Is_Lycian}) (32)
- \p{Block: Lydian} (Single: \p{InLydian}; NOT \p{Lydian} NOR
- \p{Is_Lydian}) (32)
- \p{Block: Mahjong} \p{Block=Mahjong_Tiles} (48)
- \p{Block: Mahjong_Tiles} (Short: \p{Blk=Mahjong}, \p{InMahjong})
- (48)
- \p{Block: Malayalam} (Single: \p{InMalayalam}; NOT
- \p{Malayalam} NOR \p{Is_Malayalam}) (128)
- \p{Block: Mandaic} (Single: \p{InMandaic}; NOT \p{Mandaic}
- NOR \p{Is_Mandaic}) (32)
- \p{Block: Math_Alphanum} \p{Block=
- Mathematical_Alphanumeric_Symbols} (1024)
- \p{Block: Math_Operators} \p{Block=Mathematical_Operators} (256)
- \p{Block: Mathematical_Alphanumeric_Symbols} (Short: \p{Blk=
- MathAlphanum}, \p{InMathAlphanum}) (1024)
- \p{Block: Mathematical_Operators} (Short: \p{Blk=MathOperators},
- \p{InMathOperators}) (256)
- \p{Block: Meetei_Mayek} (Single: \p{InMeeteiMayek}; NOT
- \p{Meetei_Mayek} NOR
- \p{Is_Meetei_Mayek}) (64)
- \p{Block: Meetei_Mayek_Ext} \p{Block=Meetei_Mayek_Extensions} (32)
- \p{Block: Meetei_Mayek_Extensions} (Short: \p{Blk=MeeteiMayekExt},
- \p{InMeeteiMayekExt}) (32)
- \p{Block: Meroitic_Cursive} (Single: \p{InMeroiticCursive}; NOT
- \p{Meroitic_Cursive} NOR
- \p{Is_Meroitic_Cursive}) (96)
- \p{Block: Meroitic_Hieroglyphs} (Single:
- \p{InMeroiticHieroglyphs}) (32)
- \p{Block: Miao} (Single: \p{InMiao}; NOT \p{Miao} NOR
- \p{Is_Miao}) (160)
- \p{Block: Misc_Arrows} \p{Block=Miscellaneous_Symbols_And_Arrows}
- (256)
- \p{Block: Misc_Math_Symbols_A} \p{Block=
- Miscellaneous_Mathematical_Symbols_A}
- (48)
- \p{Block: Misc_Math_Symbols_B} \p{Block=
- Miscellaneous_Mathematical_Symbols_B}
- (128)
- \p{Block: Misc_Pictographs} \p{Block=
- Miscellaneous_Symbols_And_Pictographs}
- (768)
- \p{Block: Misc_Symbols} \p{Block=Miscellaneous_Symbols} (256)
- \p{Block: Misc_Technical} \p{Block=Miscellaneous_Technical} (256)
- \p{Block: Miscellaneous_Mathematical_Symbols_A} (Short: \p{Blk=
- MiscMathSymbolsA},
- \p{InMiscMathSymbolsA}) (48)
- \p{Block: Miscellaneous_Mathematical_Symbols_B} (Short: \p{Blk=
- MiscMathSymbolsB},
- \p{InMiscMathSymbolsB}) (128)
- \p{Block: Miscellaneous_Symbols} (Short: \p{Blk=MiscSymbols},
- \p{InMiscSymbols}) (256)
- \p{Block: Miscellaneous_Symbols_And_Arrows} (Short: \p{Blk=
- MiscArrows}, \p{InMiscArrows}) (256)
- \p{Block: Miscellaneous_Symbols_And_Pictographs} (Short: \p{Blk=
- MiscPictographs}, \p{InMiscPictographs})
- (768)
- \p{Block: Miscellaneous_Technical} (Short: \p{Blk=MiscTechnical},
- \p{InMiscTechnical}) (256)
- \p{Block: Modifier_Letters} \p{Block=Spacing_Modifier_Letters} (80)
- \p{Block: Modifier_Tone_Letters} (Single:
- \p{InModifierToneLetters}) (32)
- \p{Block: Mongolian} (Single: \p{InMongolian}; NOT
- \p{Mongolian} NOR \p{Is_Mongolian}) (176)
- \p{Block: Music} \p{Block=Musical_Symbols} (256)
- \p{Block: Musical_Symbols} (Short: \p{Blk=Music}, \p{InMusic})
- (256)
- \p{Block: Myanmar} (Single: \p{InMyanmar}; NOT \p{Myanmar}
- NOR \p{Is_Myanmar}) (160)
- \p{Block: Myanmar_Ext_A} \p{Block=Myanmar_Extended_A} (32)
- \p{Block: Myanmar_Extended_A} (Short: \p{Blk=MyanmarExtA},
- \p{InMyanmarExtA}) (32)
- \p{Block: NB} \p{Block=No_Block} (860_672)
- \p{Block: New_Tai_Lue} (Single: \p{InNewTaiLue}; NOT
- \p{New_Tai_Lue} NOR \p{Is_New_Tai_Lue})
- (96)
- \p{Block: NKo} (Single: \p{InNKo}; NOT \p{Nko} NOR
- \p{Is_NKo}) (64)
- \p{Block: No_Block} (Short: \p{Blk=NB}, \p{InNB}) (860_672)
- \p{Block: Number_Forms} (Single: \p{InNumberForms}) (64)
- \p{Block: OCR} \p{Block=Optical_Character_Recognition}
- (32)
- \p{Block: Ogham} (Single: \p{InOgham}; NOT \p{Ogham} NOR
- \p{Is_Ogham}) (32)
- \p{Block: Ol_Chiki} (Single: \p{InOlChiki}) (48)
- \p{Block: Old_Italic} (Single: \p{InOldItalic}; NOT
- \p{Old_Italic} NOR \p{Is_Old_Italic})
- (48)
- \p{Block: Old_Persian} (Single: \p{InOldPersian}; NOT
- \p{Old_Persian} NOR \p{Is_Old_Persian})
- (64)
- \p{Block: Old_South_Arabian} (Single: \p{InOldSouthArabian}) (32)
- \p{Block: Old_Turkic} (Single: \p{InOldTurkic}; NOT
- \p{Old_Turkic} NOR \p{Is_Old_Turkic})
- (80)
- \p{Block: Optical_Character_Recognition} (Short: \p{Blk=OCR},
- \p{InOCR}) (32)
- \p{Block: Oriya} (Single: \p{InOriya}; NOT \p{Oriya} NOR
- \p{Is_Oriya}) (128)
- \p{Block: Osmanya} (Single: \p{InOsmanya}; NOT \p{Osmanya}
- NOR \p{Is_Osmanya}) (48)
- \p{Block: Phags_Pa} (Single: \p{InPhagsPa}; NOT \p{Phags_Pa}
- NOR \p{Is_Phags_Pa}) (64)
- \p{Block: Phaistos} \p{Block=Phaistos_Disc} (48)
- \p{Block: Phaistos_Disc} (Short: \p{Blk=Phaistos}, \p{InPhaistos})
- (48)
- \p{Block: Phoenician} (Single: \p{InPhoenician}; NOT
- \p{Phoenician} NOR \p{Is_Phoenician})
- (32)
- \p{Block: Phonetic_Ext} \p{Block=Phonetic_Extensions} (128)
- \p{Block: Phonetic_Ext_Sup} \p{Block=
- Phonetic_Extensions_Supplement} (64)
- \p{Block: Phonetic_Extensions} (Short: \p{Blk=PhoneticExt},
- \p{InPhoneticExt}) (128)
- \p{Block: Phonetic_Extensions_Supplement} (Short: \p{Blk=
- PhoneticExtSup}, \p{InPhoneticExtSup})
- (64)
- \p{Block: Playing_Cards} (Single: \p{InPlayingCards}) (96)
- \p{Block: Private_Use} \p{Block=Private_Use_Area} (NOT
- \p{Private_Use} NOR \p{Is_Private_Use})
- (6400)
- \p{Block: Private_Use_Area} (Short: \p{Blk=PUA}, \p{InPUA}; NOT
- \p{Private_Use} NOR \p{Is_Private_Use})
- (6400)
- \p{Block: PUA} \p{Block=Private_Use_Area} (NOT
- \p{Private_Use} NOR \p{Is_Private_Use})
- (6400)
- \p{Block: Punctuation} \p{Block=General_Punctuation} (NOT
- \p{Punct} NOR \p{Is_Punctuation}) (112)
- \p{Block: Rejang} (Single: \p{InRejang}; NOT \p{Rejang} NOR
- \p{Is_Rejang}) (48)
- \p{Block: Rumi} \p{Block=Rumi_Numeral_Symbols} (32)
- \p{Block: Rumi_Numeral_Symbols} (Short: \p{Blk=Rumi}, \p{InRumi})
- (32)
- \p{Block: Runic} (Single: \p{InRunic}; NOT \p{Runic} NOR
- \p{Is_Runic}) (96)
- \p{Block: Samaritan} (Single: \p{InSamaritan}; NOT
- \p{Samaritan} NOR \p{Is_Samaritan}) (64)
- \p{Block: Saurashtra} (Single: \p{InSaurashtra}; NOT
- \p{Saurashtra} NOR \p{Is_Saurashtra})
- (96)
- \p{Block: Sharada} (Single: \p{InSharada}; NOT \p{Sharada}
- NOR \p{Is_Sharada}) (96)
- \p{Block: Shavian} (Single: \p{InShavian}) (48)
- \p{Block: Sinhala} (Single: \p{InSinhala}; NOT \p{Sinhala}
- NOR \p{Is_Sinhala}) (128)
- \p{Block: Small_Form_Variants} (Short: \p{Blk=SmallForms},
- \p{InSmallForms}) (32)
- \p{Block: Small_Forms} \p{Block=Small_Form_Variants} (32)
- \p{Block: Sora_Sompeng} (Single: \p{InSoraSompeng}; NOT
- \p{Sora_Sompeng} NOR
- \p{Is_Sora_Sompeng}) (48)
- \p{Block: Spacing_Modifier_Letters} (Short: \p{Blk=
- ModifierLetters}, \p{InModifierLetters})
- (80)
- \p{Block: Specials} (Single: \p{InSpecials}) (16)
- \p{Block: Sundanese} (Single: \p{InSundanese}; NOT
- \p{Sundanese} NOR \p{Is_Sundanese}) (64)
- \p{Block: Sundanese_Sup} \p{Block=Sundanese_Supplement} (16)
- \p{Block: Sundanese_Supplement} (Short: \p{Blk=SundaneseSup},
- \p{InSundaneseSup}) (16)
- \p{Block: Sup_Arrows_A} \p{Block=Supplemental_Arrows_A} (16)
- \p{Block: Sup_Arrows_B} \p{Block=Supplemental_Arrows_B} (128)
- \p{Block: Sup_Math_Operators} \p{Block=
- Supplemental_Mathematical_Operators}
- (256)
- \p{Block: Sup_PUA_A} \p{Block=Supplementary_Private_Use_Area_A}
- (65_536)
- \p{Block: Sup_PUA_B} \p{Block=Supplementary_Private_Use_Area_B}
- (65_536)
- \p{Block: Sup_Punctuation} \p{Block=Supplemental_Punctuation} (128)
- \p{Block: Super_And_Sub} \p{Block=Superscripts_And_Subscripts} (48)
- \p{Block: Superscripts_And_Subscripts} (Short: \p{Blk=
- SuperAndSub}, \p{InSuperAndSub}) (48)
- \p{Block: Supplemental_Arrows_A} (Short: \p{Blk=SupArrowsA},
- \p{InSupArrowsA}) (16)
- \p{Block: Supplemental_Arrows_B} (Short: \p{Blk=SupArrowsB},
- \p{InSupArrowsB}) (128)
- \p{Block: Supplemental_Mathematical_Operators} (Short: \p{Blk=
- SupMathOperators},
- \p{InSupMathOperators}) (256)
- \p{Block: Supplemental_Punctuation} (Short: \p{Blk=
- SupPunctuation}, \p{InSupPunctuation})
- (128)
- \p{Block: Supplementary_Private_Use_Area_A} (Short: \p{Blk=
- SupPUAA}, \p{InSupPUAA}) (65_536)
- \p{Block: Supplementary_Private_Use_Area_B} (Short: \p{Blk=
- SupPUAB}, \p{InSupPUAB}) (65_536)
- \p{Block: Syloti_Nagri} (Single: \p{InSylotiNagri}; NOT
- \p{Syloti_Nagri} NOR
- \p{Is_Syloti_Nagri}) (48)
- \p{Block: Syriac} (Single: \p{InSyriac}; NOT \p{Syriac} NOR
- \p{Is_Syriac}) (80)
- \p{Block: Tagalog} (Single: \p{InTagalog}; NOT \p{Tagalog}
- NOR \p{Is_Tagalog}) (32)
- \p{Block: Tagbanwa} (Single: \p{InTagbanwa}; NOT \p{Tagbanwa}
- NOR \p{Is_Tagbanwa}) (32)
- \p{Block: Tags} (Single: \p{InTags}) (128)
- \p{Block: Tai_Le} (Single: \p{InTaiLe}; NOT \p{Tai_Le} NOR
- \p{Is_Tai_Le}) (48)
- \p{Block: Tai_Tham} (Single: \p{InTaiTham}; NOT \p{Tai_Tham}
- NOR \p{Is_Tai_Tham}) (144)
- \p{Block: Tai_Viet} (Single: \p{InTaiViet}; NOT \p{Tai_Viet}
- NOR \p{Is_Tai_Viet}) (96)
- \p{Block: Tai_Xuan_Jing} \p{Block=Tai_Xuan_Jing_Symbols} (96)
- \p{Block: Tai_Xuan_Jing_Symbols} (Short: \p{Blk=TaiXuanJing},
- \p{InTaiXuanJing}) (96)
- \p{Block: Takri} (Single: \p{InTakri}; NOT \p{Takri} NOR
- \p{Is_Takri}) (80)
- \p{Block: Tamil} (Single: \p{InTamil}; NOT \p{Tamil} NOR
- \p{Is_Tamil}) (128)
- \p{Block: Telugu} (Single: \p{InTelugu}; NOT \p{Telugu} NOR
- \p{Is_Telugu}) (128)
- \p{Block: Thaana} (Single: \p{InThaana}; NOT \p{Thaana} NOR
- \p{Is_Thaana}) (64)
- \p{Block: Thai} (Single: \p{InThai}; NOT \p{Thai} NOR
- \p{Is_Thai}) (128)
- \p{Block: Tibetan} (Single: \p{InTibetan}; NOT \p{Tibetan}
- NOR \p{Is_Tibetan}) (256)
- \p{Block: Tifinagh} (Single: \p{InTifinagh}; NOT \p{Tifinagh}
- NOR \p{Is_Tifinagh}) (80)
- \p{Block: Transport_And_Map} \p{Block=Transport_And_Map_Symbols}
- (128)
- \p{Block: Transport_And_Map_Symbols} (Short: \p{Blk=
- TransportAndMap}, \p{InTransportAndMap})
- (128)
- \p{Block: UCAS} \p{Block=
- Unified_Canadian_Aboriginal_Syllabics}
- (640)
- \p{Block: UCAS_Ext} \p{Block=
- Unified_Canadian_Aboriginal_Syllabics_-
- Extended} (80)
- \p{Block: Ugaritic} (Single: \p{InUgaritic}; NOT \p{Ugaritic}
- NOR \p{Is_Ugaritic}) (32)
- \p{Block: Unified_Canadian_Aboriginal_Syllabics} (Short: \p{Blk=
- UCAS}, \p{InUCAS}) (640)
- \p{Block: Unified_Canadian_Aboriginal_Syllabics_Extended} (Short:
- \p{Blk=UCASExt}, \p{InUCASExt}) (80)
- \p{Block: Vai} (Single: \p{InVai}; NOT \p{Vai} NOR
- \p{Is_Vai}) (320)
- \p{Block: Variation_Selectors} (Short: \p{Blk=VS}, \p{InVS}; NOT
- \p{Variation_Selector} NOR \p{Is_VS})
- (16)
- \p{Block: Variation_Selectors_Supplement} (Short: \p{Blk=VSSup},
- \p{InVSSup}) (240)
- \p{Block: Vedic_Ext} \p{Block=Vedic_Extensions} (48)
- \p{Block: Vedic_Extensions} (Short: \p{Blk=VedicExt},
- \p{InVedicExt}) (48)
- \p{Block: Vertical_Forms} (Single: \p{InVerticalForms}) (16)
- \p{Block: VS} \p{Block=Variation_Selectors} (NOT
- \p{Variation_Selector} NOR \p{Is_VS})
- (16)
- \p{Block: VS_Sup} \p{Block=Variation_Selectors_Supplement}
- (240)
- \p{Block: Yi_Radicals} (Single: \p{InYiRadicals}) (64)
- \p{Block: Yi_Syllables} (Single: \p{InYiSyllables}) (1168)
- \p{Block: Yijing} \p{Block=Yijing_Hexagram_Symbols} (64)
- \p{Block: Yijing_Hexagram_Symbols} (Short: \p{Blk=Yijing},
- \p{InYijing}) (64)
- X \p{Block_Elements} \p{Block=Block_Elements} (32)
- \p{Bopo} \p{Bopomofo} (= \p{Script=Bopomofo}) (NOT
- \p{Block=Bopomofo}) (70)
- \p{Bopomofo} \p{Script=Bopomofo} (Short: \p{Bopo}; NOT
- \p{Block=Bopomofo}) (70)
- X \p{Bopomofo_Ext} \p{Bopomofo_Extended} (= \p{Block=
- Bopomofo_Extended}) (32)
- X \p{Bopomofo_Extended} \p{Block=Bopomofo_Extended} (Short:
- \p{InBopomofoExt}) (32)
- X \p{Box_Drawing} \p{Block=Box_Drawing} (128)
- \p{Brah} \p{Brahmi} (= \p{Script=Brahmi}) (NOT
- \p{Block=Brahmi}) (108)
- \p{Brahmi} \p{Script=Brahmi} (Short: \p{Brah}; NOT
- \p{Block=Brahmi}) (108)
- \p{Brai} \p{Braille} (= \p{Script=Braille}) (256)
- \p{Braille} \p{Script=Braille} (Short: \p{Brai}) (256)
- X \p{Braille_Patterns} \p{Block=Braille_Patterns} (Short:
- \p{InBraille}) (256)
- \p{Bugi} \p{Buginese} (= \p{Script=Buginese}) (NOT
- \p{Block=Buginese}) (30)
- \p{Buginese} \p{Script=Buginese} (Short: \p{Bugi}; NOT
- \p{Block=Buginese}) (30)
- \p{Buhd} \p{Buhid} (= \p{Script=Buhid}) (NOT
- \p{Block=Buhid}) (20)
- \p{Buhid} \p{Script=Buhid} (Short: \p{Buhd}; NOT
- \p{Block=Buhid}) (20)
- X \p{Byzantine_Music} \p{Byzantine_Musical_Symbols} (= \p{Block=
- Byzantine_Musical_Symbols}) (256)
- X \p{Byzantine_Musical_Symbols} \p{Block=Byzantine_Musical_Symbols}
- (Short: \p{InByzantineMusic}) (256)
- \p{C} \p{Other} (= \p{General_Category=Other})
- (1_004_135)
- \p{Cakm} \p{Chakma} (= \p{Script=Chakma}) (NOT
- \p{Block=Chakma}) (67)
- \p{Canadian_Aboriginal} \p{Script=Canadian_Aboriginal} (Short:
- \p{Cans}) (710)
- X \p{Canadian_Syllabics} \p{Unified_Canadian_Aboriginal_Syllabics}
- (= \p{Block=
- Unified_Canadian_Aboriginal_Syllabics})
- (640)
- T \p{Canonical_Combining_Class: 0} \p{Canonical_Combining_Class=
- Not_Reordered} (1_113_459)
- T \p{Canonical_Combining_Class: 1} \p{Canonical_Combining_Class=
- Overlay} (26)
- T \p{Canonical_Combining_Class: 7} \p{Canonical_Combining_Class=
- Nukta} (13)
- T \p{Canonical_Combining_Class: 8} \p{Canonical_Combining_Class=
- Kana_Voicing} (2)
- T \p{Canonical_Combining_Class: 9} \p{Canonical_Combining_Class=
- Virama} (37)
- T \p{Canonical_Combining_Class: 10} \p{Canonical_Combining_Class=
- CCC10} (1)
- T \p{Canonical_Combining_Class: 11} \p{Canonical_Combining_Class=
- CCC11} (1)
- T \p{Canonical_Combining_Class: 12} \p{Canonical_Combining_Class=
- CCC12} (1)
- T \p{Canonical_Combining_Class: 13} \p{Canonical_Combining_Class=
- CCC13} (1)
- T \p{Canonical_Combining_Class: 14} \p{Canonical_Combining_Class=
- CCC14} (1)
- T \p{Canonical_Combining_Class: 15} \p{Canonical_Combining_Class=
- CCC15} (1)
- T \p{Canonical_Combining_Class: 16} \p{Canonical_Combining_Class=
- CCC16} (1)
- T \p{Canonical_Combining_Class: 17} \p{Canonical_Combining_Class=
- CCC17} (1)
- T \p{Canonical_Combining_Class: 18} \p{Canonical_Combining_Class=
- CCC18} (2)
- T \p{Canonical_Combining_Class: 19} \p{Canonical_Combining_Class=
- CCC19} (2)
- T \p{Canonical_Combining_Class: 20} \p{Canonical_Combining_Class=
- CCC20} (1)
- T \p{Canonical_Combining_Class: 21} \p{Canonical_Combining_Class=
- CCC21} (1)
- T \p{Canonical_Combining_Class: 22} \p{Canonical_Combining_Class=
- CCC22} (1)
- T \p{Canonical_Combining_Class: 23} \p{Canonical_Combining_Class=
- CCC23} (1)
- T \p{Canonical_Combining_Class: 24} \p{Canonical_Combining_Class=
- CCC24} (1)
- T \p{Canonical_Combining_Class: 25} \p{Canonical_Combining_Class=
- CCC25} (1)
- T \p{Canonical_Combining_Class: 26} \p{Canonical_Combining_Class=
- CCC26} (1)
- T \p{Canonical_Combining_Class: 27} \p{Canonical_Combining_Class=
- CCC27} (2)
- T \p{Canonical_Combining_Class: 28} \p{Canonical_Combining_Class=
- CCC28} (2)
- T \p{Canonical_Combining_Class: 29} \p{Canonical_Combining_Class=
- CCC29} (2)
- T \p{Canonical_Combining_Class: 30} \p{Canonical_Combining_Class=
- CCC30} (2)
- T \p{Canonical_Combining_Class: 31} \p{Canonical_Combining_Class=
- CCC31} (2)
- T \p{Canonical_Combining_Class: 32} \p{Canonical_Combining_Class=
- CCC32} (2)
- T \p{Canonical_Combining_Class: 33} \p{Canonical_Combining_Class=
- CCC33} (1)
- T \p{Canonical_Combining_Class: 34} \p{Canonical_Combining_Class=
- CCC34} (1)
- T \p{Canonical_Combining_Class: 35} \p{Canonical_Combining_Class=
- CCC35} (1)
- T \p{Canonical_Combining_Class: 36} \p{Canonical_Combining_Class=
- CCC36} (1)
- T \p{Canonical_Combining_Class: 84} \p{Canonical_Combining_Class=
- CCC84} (1)
- T \p{Canonical_Combining_Class: 91} \p{Canonical_Combining_Class=
- CCC91} (1)
- T \p{Canonical_Combining_Class: 103} \p{Canonical_Combining_Class=
- CCC103} (2)
- T \p{Canonical_Combining_Class: 107} \p{Canonical_Combining_Class=
- CCC107} (4)
- T \p{Canonical_Combining_Class: 118} \p{Canonical_Combining_Class=
- CCC118} (2)
- T \p{Canonical_Combining_Class: 122} \p{Canonical_Combining_Class=
- CCC122} (4)
- T \p{Canonical_Combining_Class: 129} \p{Canonical_Combining_Class=
- CCC129} (1)
- T \p{Canonical_Combining_Class: 130} \p{Canonical_Combining_Class=
- CCC130} (6)
- T \p{Canonical_Combining_Class: 132} \p{Canonical_Combining_Class=
- CCC132} (1)
- T \p{Canonical_Combining_Class: 200} \p{Canonical_Combining_Class=
- Attached_Below_Left} (0)
- T \p{Canonical_Combining_Class: 202} \p{Canonical_Combining_Class=
- Attached_Below} (5)
- T \p{Canonical_Combining_Class: 214} \p{Canonical_Combining_Class=
- Attached_Above} (1)
- T \p{Canonical_Combining_Class: 216} \p{Canonical_Combining_Class=
- Attached_Above_Right} (9)
- T \p{Canonical_Combining_Class: 218} \p{Canonical_Combining_Class=
- Below_Left} (1)
- T \p{Canonical_Combining_Class: 220} \p{Canonical_Combining_Class=
- Below} (129)
- T \p{Canonical_Combining_Class: 222} \p{Canonical_Combining_Class=
- Below_Right} (4)
- T \p{Canonical_Combining_Class: 224} \p{Canonical_Combining_Class=
- Left} (2)
- T \p{Canonical_Combining_Class: 226} \p{Canonical_Combining_Class=
- Right} (1)
- T \p{Canonical_Combining_Class: 228} \p{Canonical_Combining_Class=
- Above_Left} (3)
- T \p{Canonical_Combining_Class: 230} \p{Canonical_Combining_Class=
- Above} (349)
- T \p{Canonical_Combining_Class: 232} \p{Canonical_Combining_Class=
- Above_Right} (4)
- T \p{Canonical_Combining_Class: 233} \p{Canonical_Combining_Class=
- Double_Below} (4)
- T \p{Canonical_Combining_Class: 234} \p{Canonical_Combining_Class=
- Double_Above} (5)
- T \p{Canonical_Combining_Class: 240} \p{Canonical_Combining_Class=
- Iota_Subscript} (1)
- \p{Canonical_Combining_Class: A} \p{Canonical_Combining_Class=
- Above} (349)
- \p{Canonical_Combining_Class: Above} (Short: \p{Ccc=A}) (349)
- \p{Canonical_Combining_Class: Above_Left} (Short: \p{Ccc=AL}) (3)
- \p{Canonical_Combining_Class: Above_Right} (Short: \p{Ccc=AR}) (4)
- \p{Canonical_Combining_Class: AL} \p{Canonical_Combining_Class=
- Above_Left} (3)
- \p{Canonical_Combining_Class: AR} \p{Canonical_Combining_Class=
- Above_Right} (4)
- \p{Canonical_Combining_Class: ATA} \p{Canonical_Combining_Class=
- Attached_Above} (1)
- \p{Canonical_Combining_Class: ATAR} \p{Canonical_Combining_Class=
- Attached_Above_Right} (9)
- \p{Canonical_Combining_Class: ATB} \p{Canonical_Combining_Class=
- Attached_Below} (5)
- \p{Canonical_Combining_Class: ATBL} \p{Canonical_Combining_Class=
- Attached_Below_Left} (0)
- \p{Canonical_Combining_Class: Attached_Above} (Short: \p{Ccc=ATA})
- (1)
- \p{Canonical_Combining_Class: Attached_Above_Right} (Short:
- \p{Ccc=ATAR}) (9)
- \p{Canonical_Combining_Class: Attached_Below} (Short: \p{Ccc=ATB})
- (5)
- \p{Canonical_Combining_Class: Attached_Below_Left} (Short: \p{Ccc=
- ATBL}) (0)
- \p{Canonical_Combining_Class: B} \p{Canonical_Combining_Class=
- Below} (129)
- \p{Canonical_Combining_Class: Below} (Short: \p{Ccc=B}) (129)
- \p{Canonical_Combining_Class: Below_Left} (Short: \p{Ccc=BL}) (1)
- \p{Canonical_Combining_Class: Below_Right} (Short: \p{Ccc=BR}) (4)
- \p{Canonical_Combining_Class: BL} \p{Canonical_Combining_Class=
- Below_Left} (1)
- \p{Canonical_Combining_Class: BR} \p{Canonical_Combining_Class=
- Below_Right} (4)
- \p{Canonical_Combining_Class: CCC10} (Short: \p{Ccc=CCC10}) (1)
- \p{Canonical_Combining_Class: CCC103} (Short: \p{Ccc=CCC103}) (2)
- \p{Canonical_Combining_Class: CCC107} (Short: \p{Ccc=CCC107}) (4)
- \p{Canonical_Combining_Class: CCC11} (Short: \p{Ccc=CCC11}) (1)
- \p{Canonical_Combining_Class: CCC118} (Short: \p{Ccc=CCC118}) (2)
- \p{Canonical_Combining_Class: CCC12} (Short: \p{Ccc=CCC12}) (1)
- \p{Canonical_Combining_Class: CCC122} (Short: \p{Ccc=CCC122}) (4)
- \p{Canonical_Combining_Class: CCC129} (Short: \p{Ccc=CCC129}) (1)
- \p{Canonical_Combining_Class: CCC13} (Short: \p{Ccc=CCC13}) (1)
- \p{Canonical_Combining_Class: CCC130} (Short: \p{Ccc=CCC130}) (6)
- \p{Canonical_Combining_Class: CCC132} (Short: \p{Ccc=CCC132}) (1)
- \p{Canonical_Combining_Class: CCC14} (Short: \p{Ccc=CCC14}) (1)
- \p{Canonical_Combining_Class: CCC15} (Short: \p{Ccc=CCC15}) (1)
- \p{Canonical_Combining_Class: CCC16} (Short: \p{Ccc=CCC16}) (1)
- \p{Canonical_Combining_Class: CCC17} (Short: \p{Ccc=CCC17}) (1)
- \p{Canonical_Combining_Class: CCC18} (Short: \p{Ccc=CCC18}) (2)
- \p{Canonical_Combining_Class: CCC19} (Short: \p{Ccc=CCC19}) (2)
- \p{Canonical_Combining_Class: CCC20} (Short: \p{Ccc=CCC20}) (1)
- \p{Canonical_Combining_Class: CCC21} (Short: \p{Ccc=CCC21}) (1)
- \p{Canonical_Combining_Class: CCC22} (Short: \p{Ccc=CCC22}) (1)
- \p{Canonical_Combining_Class: CCC23} (Short: \p{Ccc=CCC23}) (1)
- \p{Canonical_Combining_Class: CCC24} (Short: \p{Ccc=CCC24}) (1)
- \p{Canonical_Combining_Class: CCC25} (Short: \p{Ccc=CCC25}) (1)
- \p{Canonical_Combining_Class: CCC26} (Short: \p{Ccc=CCC26}) (1)
- \p{Canonical_Combining_Class: CCC27} (Short: \p{Ccc=CCC27}) (2)
- \p{Canonical_Combining_Class: CCC28} (Short: \p{Ccc=CCC28}) (2)
- \p{Canonical_Combining_Class: CCC29} (Short: \p{Ccc=CCC29}) (2)
- \p{Canonical_Combining_Class: CCC30} (Short: \p{Ccc=CCC30}) (2)
- \p{Canonical_Combining_Class: CCC31} (Short: \p{Ccc=CCC31}) (2)
- \p{Canonical_Combining_Class: CCC32} (Short: \p{Ccc=CCC32}) (2)
- \p{Canonical_Combining_Class: CCC33} (Short: \p{Ccc=CCC33}) (1)
- \p{Canonical_Combining_Class: CCC34} (Short: \p{Ccc=CCC34}) (1)
- \p{Canonical_Combining_Class: CCC35} (Short: \p{Ccc=CCC35}) (1)
- \p{Canonical_Combining_Class: CCC36} (Short: \p{Ccc=CCC36}) (1)
- \p{Canonical_Combining_Class: CCC84} (Short: \p{Ccc=CCC84}) (1)
- \p{Canonical_Combining_Class: CCC91} (Short: \p{Ccc=CCC91}) (1)
- \p{Canonical_Combining_Class: DA} \p{Canonical_Combining_Class=
- Double_Above} (5)
- \p{Canonical_Combining_Class: DB} \p{Canonical_Combining_Class=
- Double_Below} (4)
- \p{Canonical_Combining_Class: Double_Above} (Short: \p{Ccc=DA}) (5)
- \p{Canonical_Combining_Class: Double_Below} (Short: \p{Ccc=DB}) (4)
- \p{Canonical_Combining_Class: Iota_Subscript} (Short: \p{Ccc=IS})
- (1)
- \p{Canonical_Combining_Class: IS} \p{Canonical_Combining_Class=
- Iota_Subscript} (1)
- \p{Canonical_Combining_Class: Kana_Voicing} (Short: \p{Ccc=KV}) (2)
- \p{Canonical_Combining_Class: KV} \p{Canonical_Combining_Class=
- Kana_Voicing} (2)
- \p{Canonical_Combining_Class: L} \p{Canonical_Combining_Class=
- Left} (2)
- \p{Canonical_Combining_Class: Left} (Short: \p{Ccc=L}) (2)
- \p{Canonical_Combining_Class: NK} \p{Canonical_Combining_Class=
- Nukta} (13)
- \p{Canonical_Combining_Class: Not_Reordered} (Short: \p{Ccc=NR})
- (1_113_459)
- \p{Canonical_Combining_Class: NR} \p{Canonical_Combining_Class=
- Not_Reordered} (1_113_459)
- \p{Canonical_Combining_Class: Nukta} (Short: \p{Ccc=NK}) (13)
- \p{Canonical_Combining_Class: OV} \p{Canonical_Combining_Class=
- Overlay} (26)
- \p{Canonical_Combining_Class: Overlay} (Short: \p{Ccc=OV}) (26)
- \p{Canonical_Combining_Class: R} \p{Canonical_Combining_Class=
- Right} (1)
- \p{Canonical_Combining_Class: Right} (Short: \p{Ccc=R}) (1)
- \p{Canonical_Combining_Class: Virama} (Short: \p{Ccc=VR}) (37)
- \p{Canonical_Combining_Class: VR} \p{Canonical_Combining_Class=
- Virama} (37)
- \p{Cans} \p{Canadian_Aboriginal} (= \p{Script=
- Canadian_Aboriginal}) (710)
- \p{Cari} \p{Carian} (= \p{Script=Carian}) (NOT
- \p{Block=Carian}) (49)
- \p{Carian} \p{Script=Carian} (Short: \p{Cari}; NOT
- \p{Block=Carian}) (49)
- \p{Case_Ignorable} \p{Case_Ignorable=Y} (Short: \p{CI}) (1799)
- \p{Case_Ignorable: N*} (Short: \p{CI=N}, \P{CI}) (1_112_313)
- \p{Case_Ignorable: Y*} (Short: \p{CI=Y}, \p{CI}) (1799)
- \p{Cased} \p{Cased=Y} (3448)
- \p{Cased: N*} (Single: \P{Cased}) (1_110_664)
- \p{Cased: Y*} (Single: \p{Cased}) (3448)
- \p{Cased_Letter} \p{General_Category=Cased_Letter} (Short:
- \p{LC}) (3223)
- \p{Category: *} \p{General_Category: *}
- \p{Cc} \p{Cntrl} (= \p{General_Category=Control})
- (65)
- \p{Ccc: *} \p{Canonical_Combining_Class: *}
- \p{CE} \p{Composition_Exclusion} (=
- \p{Composition_Exclusion=Y}) (81)
- \p{CE: *} \p{Composition_Exclusion: *}
- \p{Cf} \p{Format} (= \p{General_Category=Format})
- (139)
- \p{Chakma} \p{Script=Chakma} (Short: \p{Cakm}; NOT
- \p{Block=Chakma}) (67)
- \p{Cham} \p{Script=Cham} (NOT \p{Block=Cham}) (83)
- \p{Changes_When_Casefolded} \p{Changes_When_Casefolded=Y} (Short:
- \p{CWCF}) (1107)
- \p{Changes_When_Casefolded: N*} (Short: \p{CWCF=N}, \P{CWCF})
- (1_113_005)
- \p{Changes_When_Casefolded: Y*} (Short: \p{CWCF=Y}, \p{CWCF})
- (1107)
- \p{Changes_When_Casemapped} \p{Changes_When_Casemapped=Y} (Short:
- \p{CWCM}) (2138)
- \p{Changes_When_Casemapped: N*} (Short: \p{CWCM=N}, \P{CWCM})
- (1_111_974)
- \p{Changes_When_Casemapped: Y*} (Short: \p{CWCM=Y}, \p{CWCM})
- (2138)
- \p{Changes_When_Lowercased} \p{Changes_When_Lowercased=Y} (Short:
- \p{CWL}) (1043)
- \p{Changes_When_Lowercased: N*} (Short: \p{CWL=N}, \P{CWL})
- (1_113_069)
- \p{Changes_When_Lowercased: Y*} (Short: \p{CWL=Y}, \p{CWL}) (1043)
- \p{Changes_When_NFKC_Casefolded} \p{Changes_When_NFKC_Casefolded=
- Y} (Short: \p{CWKCF}) (9944)
- \p{Changes_When_NFKC_Casefolded: N*} (Short: \p{CWKCF=N},
- \P{CWKCF}) (1_104_168)
- \p{Changes_When_NFKC_Casefolded: Y*} (Short: \p{CWKCF=Y},
- \p{CWKCF}) (9944)
- \p{Changes_When_Titlecased} \p{Changes_When_Titlecased=Y} (Short:
- \p{CWT}) (1099)
- \p{Changes_When_Titlecased: N*} (Short: \p{CWT=N}, \P{CWT})
- (1_113_013)
- \p{Changes_When_Titlecased: Y*} (Short: \p{CWT=Y}, \p{CWT}) (1099)
- \p{Changes_When_Uppercased} \p{Changes_When_Uppercased=Y} (Short:
- \p{CWU}) (1126)
- \p{Changes_When_Uppercased: N*} (Short: \p{CWU=N}, \P{CWU})
- (1_112_986)
- \p{Changes_When_Uppercased: Y*} (Short: \p{CWU=Y}, \p{CWU}) (1126)
- \p{Cher} \p{Cherokee} (= \p{Script=Cherokee}) (NOT
- \p{Block=Cherokee}) (85)
- \p{Cherokee} \p{Script=Cherokee} (Short: \p{Cher}; NOT
- \p{Block=Cherokee}) (85)
- \p{CI} \p{Case_Ignorable} (= \p{Case_Ignorable=
- Y}) (1799)
- \p{CI: *} \p{Case_Ignorable: *}
- X \p{CJK} \p{CJK_Unified_Ideographs} (= \p{Block=
- CJK_Unified_Ideographs}) (20_992)
- X \p{CJK_Compat} \p{CJK_Compatibility} (= \p{Block=
- CJK_Compatibility}) (256)
- X \p{CJK_Compat_Forms} \p{CJK_Compatibility_Forms} (= \p{Block=
- CJK_Compatibility_Forms}) (32)
- X \p{CJK_Compat_Ideographs} \p{CJK_Compatibility_Ideographs} (=
- \p{Block=CJK_Compatibility_Ideographs})
- (512)
- X \p{CJK_Compat_Ideographs_Sup}
- \p{CJK_Compatibility_Ideographs_-
- Supplement} (= \p{Block=
- CJK_Compatibility_Ideographs_-
- Supplement}) (544)
- X \p{CJK_Compatibility} \p{Block=CJK_Compatibility} (Short:
- \p{InCJKCompat}) (256)
- X \p{CJK_Compatibility_Forms} \p{Block=CJK_Compatibility_Forms}
- (Short: \p{InCJKCompatForms}) (32)
- X \p{CJK_Compatibility_Ideographs} \p{Block=
- CJK_Compatibility_Ideographs} (Short:
- \p{InCJKCompatIdeographs}) (512)
- X \p{CJK_Compatibility_Ideographs_Supplement} \p{Block=
- CJK_Compatibility_Ideographs_Supplement}
- (Short: \p{InCJKCompatIdeographsSup})
- (544)
- X \p{CJK_Ext_A} \p{CJK_Unified_Ideographs_Extension_A} (=
- \p{Block=
- CJK_Unified_Ideographs_Extension_A})
- (6592)
- X \p{CJK_Ext_B} \p{CJK_Unified_Ideographs_Extension_B} (=
- \p{Block=
- CJK_Unified_Ideographs_Extension_B})
- (42_720)
- X \p{CJK_Ext_C} \p{CJK_Unified_Ideographs_Extension_C} (=
- \p{Block=
- CJK_Unified_Ideographs_Extension_C})
- (4160)
- X \p{CJK_Ext_D} \p{CJK_Unified_Ideographs_Extension_D} (=
- \p{Block=
- CJK_Unified_Ideographs_Extension_D})
- (224)
- X \p{CJK_Radicals_Sup} \p{CJK_Radicals_Supplement} (= \p{Block=
- CJK_Radicals_Supplement}) (128)
- X \p{CJK_Radicals_Supplement} \p{Block=CJK_Radicals_Supplement}
- (Short: \p{InCJKRadicalsSup}) (128)
- X \p{CJK_Strokes} \p{Block=CJK_Strokes} (48)
- X \p{CJK_Symbols} \p{CJK_Symbols_And_Punctuation} (=
- \p{Block=CJK_Symbols_And_Punctuation})
- (64)
- X \p{CJK_Symbols_And_Punctuation} \p{Block=
- CJK_Symbols_And_Punctuation} (Short:
- \p{InCJKSymbols}) (64)
- X \p{CJK_Unified_Ideographs} \p{Block=CJK_Unified_Ideographs}
- (Short: \p{InCJK}) (20_992)
- X \p{CJK_Unified_Ideographs_Extension_A} \p{Block=
- CJK_Unified_Ideographs_Extension_A}
- (Short: \p{InCJKExtA}) (6592)
- X \p{CJK_Unified_Ideographs_Extension_B} \p{Block=
- CJK_Unified_Ideographs_Extension_B}
- (Short: \p{InCJKExtB}) (42_720)
- X \p{CJK_Unified_Ideographs_Extension_C} \p{Block=
- CJK_Unified_Ideographs_Extension_C}
- (Short: \p{InCJKExtC}) (4160)
- X \p{CJK_Unified_Ideographs_Extension_D} \p{Block=
- CJK_Unified_Ideographs_Extension_D}
- (Short: \p{InCJKExtD}) (224)
- \p{Close_Punctuation} \p{General_Category=Close_Punctuation}
- (Short: \p{Pe}) (71)
- \p{Cn} \p{Unassigned} (= \p{General_Category=
- Unassigned}) (864_415)
- \p{Cntrl} \p{General_Category=Control} Control
- characters (Short: \p{Cc}) (65)
- \p{Co} \p{Private_Use} (= \p{General_Category=
- Private_Use}) (NOT \p{Private_Use_Area})
- (137_468)
- X \p{Combining_Diacritical_Marks} \p{Block=
- Combining_Diacritical_Marks} (Short:
- \p{InDiacriticals}) (112)
- X \p{Combining_Diacritical_Marks_For_Symbols} \p{Block=
- Combining_Diacritical_Marks_For_Symbols}
- (Short: \p{InDiacriticalsForSymbols})
- (48)
- X \p{Combining_Diacritical_Marks_Supplement} \p{Block=
- Combining_Diacritical_Marks_Supplement}
- (Short: \p{InDiacriticalsSup}) (64)
- X \p{Combining_Half_Marks} \p{Block=Combining_Half_Marks} (Short:
- \p{InHalfMarks}) (16)
- \p{Combining_Mark} \p{Mark} (= \p{General_Category=Mark})
- (1645)
- X \p{Combining_Marks_For_Symbols}
- \p{Combining_Diacritical_Marks_For_-
- Symbols} (= \p{Block=
- Combining_Diacritical_Marks_For_-
- Symbols}) (48)
- \p{Common} \p{Script=Common} (Short: \p{Zyyy}) (6412)
- X \p{Common_Indic_Number_Forms} \p{Block=Common_Indic_Number_Forms}
- (Short: \p{InIndicNumberForms}) (16)
- \p{Comp_Ex} \p{Full_Composition_Exclusion} (=
- \p{Full_Composition_Exclusion=Y}) (1120)
- \p{Comp_Ex: *} \p{Full_Composition_Exclusion: *}
- X \p{Compat_Jamo} \p{Hangul_Compatibility_Jamo} (= \p{Block=
- Hangul_Compatibility_Jamo}) (96)
- \p{Composition_Exclusion} \p{Composition_Exclusion=Y} (Short:
- \p{CE}) (81)
- \p{Composition_Exclusion: N*} (Short: \p{CE=N}, \P{CE}) (1_114_031)
- \p{Composition_Exclusion: Y*} (Short: \p{CE=Y}, \p{CE}) (81)
- \p{Connector_Punctuation} \p{General_Category=
- Connector_Punctuation} (Short: \p{Pc})
- (10)
- \p{Control} \p{Cntrl} (= \p{General_Category=Control})
- (65)
- X \p{Control_Pictures} \p{Block=Control_Pictures} (64)
- \p{Copt} \p{Coptic} (= \p{Script=Coptic}) (NOT
- \p{Block=Coptic}) (137)
- \p{Coptic} \p{Script=Coptic} (Short: \p{Copt}; NOT
- \p{Block=Coptic}) (137)
- X \p{Counting_Rod} \p{Counting_Rod_Numerals} (= \p{Block=
- Counting_Rod_Numerals}) (32)
- X \p{Counting_Rod_Numerals} \p{Block=Counting_Rod_Numerals} (Short:
- \p{InCountingRod}) (32)
- \p{Cprt} \p{Cypriot} (= \p{Script=Cypriot}) (55)
- \p{Cs} \p{Surrogate} (= \p{General_Category=
- Surrogate}) (2048)
- \p{Cuneiform} \p{Script=Cuneiform} (Short: \p{Xsux}; NOT
- \p{Block=Cuneiform}) (982)
- X \p{Cuneiform_Numbers} \p{Cuneiform_Numbers_And_Punctuation} (=
- \p{Block=
- Cuneiform_Numbers_And_Punctuation}) (128)
- X \p{Cuneiform_Numbers_And_Punctuation} \p{Block=
- Cuneiform_Numbers_And_Punctuation}
- (Short: \p{InCuneiformNumbers}) (128)
- \p{Currency_Symbol} \p{General_Category=Currency_Symbol}
- (Short: \p{Sc}) (48)
- X \p{Currency_Symbols} \p{Block=Currency_Symbols} (48)
- \p{CWCF} \p{Changes_When_Casefolded} (=
- \p{Changes_When_Casefolded=Y}) (1107)
- \p{CWCF: *} \p{Changes_When_Casefolded: *}
- \p{CWCM} \p{Changes_When_Casemapped} (=
- \p{Changes_When_Casemapped=Y}) (2138)
- \p{CWCM: *} \p{Changes_When_Casemapped: *}
- \p{CWKCF} \p{Changes_When_NFKC_Casefolded} (=
- \p{Changes_When_NFKC_Casefolded=Y})
- (9944)
- \p{CWKCF: *} \p{Changes_When_NFKC_Casefolded: *}
- \p{CWL} \p{Changes_When_Lowercased} (=
- \p{Changes_When_Lowercased=Y}) (1043)
- \p{CWL: *} \p{Changes_When_Lowercased: *}
- \p{CWT} \p{Changes_When_Titlecased} (=
- \p{Changes_When_Titlecased=Y}) (1099)
- \p{CWT: *} \p{Changes_When_Titlecased: *}
- \p{CWU} \p{Changes_When_Uppercased} (=
- \p{Changes_When_Uppercased=Y}) (1126)
- \p{CWU: *} \p{Changes_When_Uppercased: *}
- \p{Cypriot} \p{Script=Cypriot} (Short: \p{Cprt}) (55)
- X \p{Cypriot_Syllabary} \p{Block=Cypriot_Syllabary} (64)
- \p{Cyrillic} \p{Script=Cyrillic} (Short: \p{Cyrl}; NOT
- \p{Block=Cyrillic}) (417)
- X \p{Cyrillic_Ext_A} \p{Cyrillic_Extended_A} (= \p{Block=
- Cyrillic_Extended_A}) (32)
- X \p{Cyrillic_Ext_B} \p{Cyrillic_Extended_B} (= \p{Block=
- Cyrillic_Extended_B}) (96)
- X \p{Cyrillic_Extended_A} \p{Block=Cyrillic_Extended_A} (Short:
- \p{InCyrillicExtA}) (32)
- X \p{Cyrillic_Extended_B} \p{Block=Cyrillic_Extended_B} (Short:
- \p{InCyrillicExtB}) (96)
- X \p{Cyrillic_Sup} \p{Cyrillic_Supplement} (= \p{Block=
- Cyrillic_Supplement}) (48)
- X \p{Cyrillic_Supplement} \p{Block=Cyrillic_Supplement} (Short:
- \p{InCyrillicSup}) (48)
- X \p{Cyrillic_Supplementary} \p{Cyrillic_Supplement} (= \p{Block=
- Cyrillic_Supplement}) (48)
- \p{Cyrl} \p{Cyrillic} (= \p{Script=Cyrillic}) (NOT
- \p{Block=Cyrillic}) (417)
- \p{Dash} \p{Dash=Y} (27)
- \p{Dash: N*} (Single: \P{Dash}) (1_114_085)
- \p{Dash: Y*} (Single: \p{Dash}) (27)
- \p{Dash_Punctuation} \p{General_Category=Dash_Punctuation}
- (Short: \p{Pd}) (23)
- \p{Decimal_Number} \p{Digit} (= \p{General_Category=
- Decimal_Number}) (460)
- \p{Decomposition_Type: Can} \p{Decomposition_Type=Canonical}
- (13_225)
- \p{Decomposition_Type: Canonical} (Short: \p{Dt=Can}) (13_225)
- \p{Decomposition_Type: Circle} (Short: \p{Dt=Enc}) (240)
- \p{Decomposition_Type: Com} \p{Decomposition_Type=Compat} (720)
- \p{Decomposition_Type: Compat} (Short: \p{Dt=Com}) (720)
- \p{Decomposition_Type: Enc} \p{Decomposition_Type=Circle} (240)
- \p{Decomposition_Type: Fin} \p{Decomposition_Type=Final} (240)
- \p{Decomposition_Type: Final} (Short: \p{Dt=Fin}) (240)
- \p{Decomposition_Type: Font} (Short: \p{Dt=Font}) (1184)
- \p{Decomposition_Type: Fra} \p{Decomposition_Type=Fraction} (20)
- \p{Decomposition_Type: Fraction} (Short: \p{Dt=Fra}) (20)
- \p{Decomposition_Type: Init} \p{Decomposition_Type=Initial} (171)
- \p{Decomposition_Type: Initial} (Short: \p{Dt=Init}) (171)
- \p{Decomposition_Type: Iso} \p{Decomposition_Type=Isolated} (238)
- \p{Decomposition_Type: Isolated} (Short: \p{Dt=Iso}) (238)
- \p{Decomposition_Type: Med} \p{Decomposition_Type=Medial} (82)
- \p{Decomposition_Type: Medial} (Short: \p{Dt=Med}) (82)
- \p{Decomposition_Type: Nar} \p{Decomposition_Type=Narrow} (122)
- \p{Decomposition_Type: Narrow} (Short: \p{Dt=Nar}) (122)
- \p{Decomposition_Type: Nb} \p{Decomposition_Type=Nobreak} (5)
- \p{Decomposition_Type: Nobreak} (Short: \p{Dt=Nb}) (5)
- \p{Decomposition_Type: Non_Canon} \p{Decomposition_Type=
- Non_Canonical} (Perl extension) (3655)
- \p{Decomposition_Type: Non_Canonical} Union of all non-canonical
- decompositions (Short: \p{Dt=NonCanon})
- (Perl extension) (3655)
- \p{Decomposition_Type: None} (Short: \p{Dt=None}) (1_097_232)
- \p{Decomposition_Type: Small} (Short: \p{Dt=Sml}) (26)
- \p{Decomposition_Type: Sml} \p{Decomposition_Type=Small} (26)
- \p{Decomposition_Type: Sqr} \p{Decomposition_Type=Square} (284)
- \p{Decomposition_Type: Square} (Short: \p{Dt=Sqr}) (284)
- \p{Decomposition_Type: Sub} (Short: \p{Dt=Sub}) (38)
- \p{Decomposition_Type: Sup} \p{Decomposition_Type=Super} (146)
- \p{Decomposition_Type: Super} (Short: \p{Dt=Sup}) (146)
- \p{Decomposition_Type: Vert} \p{Decomposition_Type=Vertical} (35)
- \p{Decomposition_Type: Vertical} (Short: \p{Dt=Vert}) (35)
- \p{Decomposition_Type: Wide} (Short: \p{Dt=Wide}) (104)
- \p{Default_Ignorable_Code_Point} \p{Default_Ignorable_Code_Point=
- Y} (Short: \p{DI}) (4167)
- \p{Default_Ignorable_Code_Point: N*} (Short: \p{DI=N}, \P{DI})
- (1_109_945)
- \p{Default_Ignorable_Code_Point: Y*} (Short: \p{DI=Y}, \p{DI})
- (4167)
- \p{Dep} \p{Deprecated} (= \p{Deprecated=Y}) (111)
- \p{Dep: *} \p{Deprecated: *}
- \p{Deprecated} \p{Deprecated=Y} (Short: \p{Dep}) (111)
- \p{Deprecated: N*} (Short: \p{Dep=N}, \P{Dep}) (1_114_001)
- \p{Deprecated: Y*} (Short: \p{Dep=Y}, \p{Dep}) (111)
- \p{Deseret} \p{Script=Deseret} (Short: \p{Dsrt}) (80)
- \p{Deva} \p{Devanagari} (= \p{Script=Devanagari})
- (NOT \p{Block=Devanagari}) (151)
- \p{Devanagari} \p{Script=Devanagari} (Short: \p{Deva};
- NOT \p{Block=Devanagari}) (151)
- X \p{Devanagari_Ext} \p{Devanagari_Extended} (= \p{Block=
- Devanagari_Extended}) (32)
- X \p{Devanagari_Extended} \p{Block=Devanagari_Extended} (Short:
- \p{InDevanagariExt}) (32)
- \p{DI} \p{Default_Ignorable_Code_Point} (=
- \p{Default_Ignorable_Code_Point=Y})
- (4167)
- \p{DI: *} \p{Default_Ignorable_Code_Point: *}
- \p{Dia} \p{Diacritic} (= \p{Diacritic=Y}) (693)
- \p{Dia: *} \p{Diacritic: *}
- \p{Diacritic} \p{Diacritic=Y} (Short: \p{Dia}) (693)
- \p{Diacritic: N*} (Short: \p{Dia=N}, \P{Dia}) (1_113_419)
- \p{Diacritic: Y*} (Short: \p{Dia=Y}, \p{Dia}) (693)
- X \p{Diacriticals} \p{Combining_Diacritical_Marks} (=
- \p{Block=Combining_Diacritical_Marks})
- (112)
- X \p{Diacriticals_For_Symbols}
- \p{Combining_Diacritical_Marks_For_-
- Symbols} (= \p{Block=
- Combining_Diacritical_Marks_For_-
- Symbols}) (48)
- X \p{Diacriticals_Sup} \p{Combining_Diacritical_Marks_Supplement}
- (= \p{Block=
- Combining_Diacritical_Marks_Supplement})
- (64)
- \p{Digit} \p{General_Category=Decimal_Number} [0-9]
- + all other decimal digits (Short:
- \p{Nd}) (460)
- X \p{Dingbats} \p{Block=Dingbats} (192)
- X \p{Domino} \p{Domino_Tiles} (= \p{Block=
- Domino_Tiles}) (112)
- X \p{Domino_Tiles} \p{Block=Domino_Tiles} (Short:
- \p{InDomino}) (112)
- \p{Dsrt} \p{Deseret} (= \p{Script=Deseret}) (80)
- \p{Dt: *} \p{Decomposition_Type: *}
- \p{Ea: *} \p{East_Asian_Width: *}
- \p{East_Asian_Width: A} \p{East_Asian_Width=Ambiguous} (138_746)
- \p{East_Asian_Width: Ambiguous} (Short: \p{Ea=A}) (138_746)
- \p{East_Asian_Width: F} \p{East_Asian_Width=Fullwidth} (104)
- \p{East_Asian_Width: Fullwidth} (Short: \p{Ea=F}) (104)
- \p{East_Asian_Width: H} \p{East_Asian_Width=Halfwidth} (123)
- \p{East_Asian_Width: Halfwidth} (Short: \p{Ea=H}) (123)
- \p{East_Asian_Width: N} \p{East_Asian_Width=Neutral} (801_811)
- \p{East_Asian_Width: Na} \p{East_Asian_Width=Narrow} (111)
- \p{East_Asian_Width: Narrow} (Short: \p{Ea=Na}) (111)
- \p{East_Asian_Width: Neutral} (Short: \p{Ea=N}) (801_811)
- \p{East_Asian_Width: W} \p{East_Asian_Width=Wide} (173_217)
- \p{East_Asian_Width: Wide} (Short: \p{Ea=W}) (173_217)
- \p{Egyp} \p{Egyptian_Hieroglyphs} (= \p{Script=
- Egyptian_Hieroglyphs}) (NOT \p{Block=
- Egyptian_Hieroglyphs}) (1071)
- \p{Egyptian_Hieroglyphs} \p{Script=Egyptian_Hieroglyphs} (Short:
- \p{Egyp}; NOT \p{Block=
- Egyptian_Hieroglyphs}) (1071)
- X \p{Emoticons} \p{Block=Emoticons} (80)
- X \p{Enclosed_Alphanum} \p{Enclosed_Alphanumerics} (= \p{Block=
- Enclosed_Alphanumerics}) (160)
- X \p{Enclosed_Alphanum_Sup} \p{Enclosed_Alphanumeric_Supplement} (=
- \p{Block=
- Enclosed_Alphanumeric_Supplement}) (256)
- X \p{Enclosed_Alphanumeric_Supplement} \p{Block=
- Enclosed_Alphanumeric_Supplement}
- (Short: \p{InEnclosedAlphanumSup}) (256)
- X \p{Enclosed_Alphanumerics} \p{Block=Enclosed_Alphanumerics}
- (Short: \p{InEnclosedAlphanum}) (160)
- X \p{Enclosed_CJK} \p{Enclosed_CJK_Letters_And_Months} (=
- \p{Block=
- Enclosed_CJK_Letters_And_Months}) (256)
- X \p{Enclosed_CJK_Letters_And_Months} \p{Block=
- Enclosed_CJK_Letters_And_Months} (Short:
- \p{InEnclosedCJK}) (256)
- X \p{Enclosed_Ideographic_Sup} \p{Enclosed_Ideographic_Supplement}
- (= \p{Block=
- Enclosed_Ideographic_Supplement}) (256)
- X \p{Enclosed_Ideographic_Supplement} \p{Block=
- Enclosed_Ideographic_Supplement} (Short:
- \p{InEnclosedIdeographicSup}) (256)
- \p{Enclosing_Mark} \p{General_Category=Enclosing_Mark}
- (Short: \p{Me}) (12)
- \p{Ethi} \p{Ethiopic} (= \p{Script=Ethiopic}) (NOT
- \p{Block=Ethiopic}) (495)
- \p{Ethiopic} \p{Script=Ethiopic} (Short: \p{Ethi}; NOT
- \p{Block=Ethiopic}) (495)
- X \p{Ethiopic_Ext} \p{Ethiopic_Extended} (= \p{Block=
- Ethiopic_Extended}) (96)
- X \p{Ethiopic_Ext_A} \p{Ethiopic_Extended_A} (= \p{Block=
- Ethiopic_Extended_A}) (48)
- X \p{Ethiopic_Extended} \p{Block=Ethiopic_Extended} (Short:
- \p{InEthiopicExt}) (96)
- X \p{Ethiopic_Extended_A} \p{Block=Ethiopic_Extended_A} (Short:
- \p{InEthiopicExtA}) (48)
- X \p{Ethiopic_Sup} \p{Ethiopic_Supplement} (= \p{Block=
- Ethiopic_Supplement}) (32)
- X \p{Ethiopic_Supplement} \p{Block=Ethiopic_Supplement} (Short:
- \p{InEthiopicSup}) (32)
- \p{Ext} \p{Extender} (= \p{Extender=Y}) (31)
- \p{Ext: *} \p{Extender: *}
- \p{Extender} \p{Extender=Y} (Short: \p{Ext}) (31)
- \p{Extender: N*} (Short: \p{Ext=N}, \P{Ext}) (1_114_081)
- \p{Extender: Y*} (Short: \p{Ext=Y}, \p{Ext}) (31)
- \p{Final_Punctuation} \p{General_Category=Final_Punctuation}
- (Short: \p{Pf}) (10)
- \p{Format} \p{General_Category=Format} (Short:
- \p{Cf}) (139)
- \p{Full_Composition_Exclusion} \p{Full_Composition_Exclusion=Y}
- (Short: \p{CompEx}) (1120)
- \p{Full_Composition_Exclusion: N*} (Short: \p{CompEx=N},
- \P{CompEx}) (1_112_992)
- \p{Full_Composition_Exclusion: Y*} (Short: \p{CompEx=Y},
- \p{CompEx}) (1120)
- \p{Gc: *} \p{General_Category: *}
- \p{GCB: *} \p{Grapheme_Cluster_Break: *}
- \p{General_Category: C} \p{General_Category=Other} (1_004_135)
- \p{General_Category: Cased_Letter} [\p{Ll}\p{Lu}\p{Lt}] (Short:
- \p{Gc=LC}, \p{LC}) (3223)
- \p{General_Category: Cc} \p{General_Category=Control} (65)
- \p{General_Category: Cf} \p{General_Category=Format} (139)
- \p{General_Category: Close_Punctuation} (Short: \p{Gc=Pe}, \p{Pe})
- (71)
- \p{General_Category: Cn} \p{General_Category=Unassigned} (864_415)
- \p{General_Category: Cntrl} \p{General_Category=Control} (65)
- \p{General_Category: Co} \p{General_Category=Private_Use} (137_468)
- \p{General_Category: Combining_Mark} \p{General_Category=Mark}
- (1645)
- \p{General_Category: Connector_Punctuation} (Short: \p{Gc=Pc},
- \p{Pc}) (10)
- \p{General_Category: Control} (Short: \p{Gc=Cc}, \p{Cc}) (65)
- \p{General_Category: Cs} \p{General_Category=Surrogate} (2048)
- \p{General_Category: Currency_Symbol} (Short: \p{Gc=Sc}, \p{Sc})
- (48)
- \p{General_Category: Dash_Punctuation} (Short: \p{Gc=Pd}, \p{Pd})
- (23)
- \p{General_Category: Decimal_Number} (Short: \p{Gc=Nd}, \p{Nd})
- (460)
- \p{General_Category: Digit} \p{General_Category=Decimal_Number}
- (460)
- \p{General_Category: Enclosing_Mark} (Short: \p{Gc=Me}, \p{Me})
- (12)
- \p{General_Category: Final_Punctuation} (Short: \p{Gc=Pf}, \p{Pf})
- (10)
- \p{General_Category: Format} (Short: \p{Gc=Cf}, \p{Cf}) (139)
- \p{General_Category: Initial_Punctuation} (Short: \p{Gc=Pi},
- \p{Pi}) (12)
- \p{General_Category: L} \p{General_Category=Letter} (101_013)
- X \p{General_Category: L&} \p{General_Category=Cased_Letter} (3223)
- X \p{General_Category: L_} \p{General_Category=Cased_Letter} Note
- the trailing '_' matters in spite of
- loose matching rules. (3223)
- \p{General_Category: LC} \p{General_Category=Cased_Letter} (3223)
- \p{General_Category: Letter} (Short: \p{Gc=L}, \p{L}) (101_013)
- \p{General_Category: Letter_Number} (Short: \p{Gc=Nl}, \p{Nl})
- (224)
- \p{General_Category: Line_Separator} (Short: \p{Gc=Zl}, \p{Zl}) (1)
- \p{General_Category: Ll} \p{General_Category=Lowercase_Letter}
- (/i= General_Category=Cased_Letter)
- (1751)
- \p{General_Category: Lm} \p{General_Category=Modifier_Letter} (237)
- \p{General_Category: Lo} \p{General_Category=Other_Letter} (97_553)
- \p{General_Category: Lowercase_Letter} (Short: \p{Gc=Ll}, \p{Ll};
- /i= General_Category=Cased_Letter) (1751)
- \p{General_Category: Lt} \p{General_Category=Titlecase_Letter}
- (/i= General_Category=Cased_Letter) (31)
- \p{General_Category: Lu} \p{General_Category=Uppercase_Letter}
- (/i= General_Category=Cased_Letter)
- (1441)
- \p{General_Category: M} \p{General_Category=Mark} (1645)
- \p{General_Category: Mark} (Short: \p{Gc=M}, \p{M}) (1645)
- \p{General_Category: Math_Symbol} (Short: \p{Gc=Sm}, \p{Sm}) (952)
- \p{General_Category: Mc} \p{General_Category=Spacing_Mark} (353)
- \p{General_Category: Me} \p{General_Category=Enclosing_Mark} (12)
- \p{General_Category: Mn} \p{General_Category=Nonspacing_Mark}
- (1280)
- \p{General_Category: Modifier_Letter} (Short: \p{Gc=Lm}, \p{Lm})
- (237)
- \p{General_Category: Modifier_Symbol} (Short: \p{Gc=Sk}, \p{Sk})
- (115)
- \p{General_Category: N} \p{General_Category=Number} (1148)
- \p{General_Category: Nd} \p{General_Category=Decimal_Number} (460)
- \p{General_Category: Nl} \p{General_Category=Letter_Number} (224)
- \p{General_Category: No} \p{General_Category=Other_Number} (464)
- \p{General_Category: Nonspacing_Mark} (Short: \p{Gc=Mn}, \p{Mn})
- (1280)
- \p{General_Category: Number} (Short: \p{Gc=N}, \p{N}) (1148)
- \p{General_Category: Open_Punctuation} (Short: \p{Gc=Ps}, \p{Ps})
- (72)
- \p{General_Category: Other} (Short: \p{Gc=C}, \p{C}) (1_004_135)
- \p{General_Category: Other_Letter} (Short: \p{Gc=Lo}, \p{Lo})
- (97_553)
- \p{General_Category: Other_Number} (Short: \p{Gc=No}, \p{No}) (464)
- \p{General_Category: Other_Punctuation} (Short: \p{Gc=Po}, \p{Po})
- (434)
- \p{General_Category: Other_Symbol} (Short: \p{Gc=So}, \p{So})
- (4404)
- \p{General_Category: P} \p{General_Category=Punctuation} (632)
- \p{General_Category: Paragraph_Separator} (Short: \p{Gc=Zp},
- \p{Zp}) (1)
- \p{General_Category: Pc} \p{General_Category=
- Connector_Punctuation} (10)
- \p{General_Category: Pd} \p{General_Category=Dash_Punctuation} (23)
- \p{General_Category: Pe} \p{General_Category=Close_Punctuation}
- (71)
- \p{General_Category: Pf} \p{General_Category=Final_Punctuation}
- (10)
- \p{General_Category: Pi} \p{General_Category=Initial_Punctuation}
- (12)
- \p{General_Category: Po} \p{General_Category=Other_Punctuation}
- (434)
- \p{General_Category: Private_Use} (Short: \p{Gc=Co}, \p{Co})
- (137_468)
- \p{General_Category: Ps} \p{General_Category=Open_Punctuation} (72)
- \p{General_Category: Punct} \p{General_Category=Punctuation} (632)
- \p{General_Category: Punctuation} (Short: \p{Gc=P}, \p{P}) (632)
- \p{General_Category: S} \p{General_Category=Symbol} (5519)
- \p{General_Category: Sc} \p{General_Category=Currency_Symbol} (48)
- \p{General_Category: Separator} (Short: \p{Gc=Z}, \p{Z}) (20)
- \p{General_Category: Sk} \p{General_Category=Modifier_Symbol} (115)
- \p{General_Category: Sm} \p{General_Category=Math_Symbol} (952)
- \p{General_Category: So} \p{General_Category=Other_Symbol} (4404)
- \p{General_Category: Space_Separator} (Short: \p{Gc=Zs}, \p{Zs})
- (18)
- \p{General_Category: Spacing_Mark} (Short: \p{Gc=Mc}, \p{Mc}) (353)
- \p{General_Category: Surrogate} (Short: \p{Gc=Cs}, \p{Cs}) (2048)
- \p{General_Category: Symbol} (Short: \p{Gc=S}, \p{S}) (5519)
- \p{General_Category: Titlecase_Letter} (Short: \p{Gc=Lt}, \p{Lt};
- /i= General_Category=Cased_Letter) (31)
- \p{General_Category: Unassigned} (Short: \p{Gc=Cn}, \p{Cn})
- (864_415)
- \p{General_Category: Uppercase_Letter} (Short: \p{Gc=Lu}, \p{Lu};
- /i= General_Category=Cased_Letter) (1441)
- \p{General_Category: Z} \p{General_Category=Separator} (20)
- \p{General_Category: Zl} \p{General_Category=Line_Separator} (1)
- \p{General_Category: Zp} \p{General_Category=Paragraph_Separator}
- (1)
- \p{General_Category: Zs} \p{General_Category=Space_Separator} (18)
- X \p{General_Punctuation} \p{Block=General_Punctuation} (Short:
- \p{InPunctuation}) (112)
- X \p{Geometric_Shapes} \p{Block=Geometric_Shapes} (96)
- \p{Geor} \p{Georgian} (= \p{Script=Georgian}) (NOT
- \p{Block=Georgian}) (127)
- \p{Georgian} \p{Script=Georgian} (Short: \p{Geor}; NOT
- \p{Block=Georgian}) (127)
- X \p{Georgian_Sup} \p{Georgian_Supplement} (= \p{Block=
- Georgian_Supplement}) (48)
- X \p{Georgian_Supplement} \p{Block=Georgian_Supplement} (Short:
- \p{InGeorgianSup}) (48)
- \p{Glag} \p{Glagolitic} (= \p{Script=Glagolitic})
- (NOT \p{Block=Glagolitic}) (94)
- \p{Glagolitic} \p{Script=Glagolitic} (Short: \p{Glag};
- NOT \p{Block=Glagolitic}) (94)
- \p{Goth} \p{Gothic} (= \p{Script=Gothic}) (NOT
- \p{Block=Gothic}) (27)
- \p{Gothic} \p{Script=Gothic} (Short: \p{Goth}; NOT
- \p{Block=Gothic}) (27)
- \p{Gr_Base} \p{Grapheme_Base} (= \p{Grapheme_Base=Y})
- (108_660)
- \p{Gr_Base: *} \p{Grapheme_Base: *}
- \p{Gr_Ext} \p{Grapheme_Extend} (= \p{Grapheme_Extend=
- Y}) (1317)
- \p{Gr_Ext: *} \p{Grapheme_Extend: *}
- \p{Graph} Characters that are graphical (247_564)
- \p{Grapheme_Base} \p{Grapheme_Base=Y} (Short: \p{GrBase})
- (108_660)
- \p{Grapheme_Base: N*} (Short: \p{GrBase=N}, \P{GrBase})
- (1_005_452)
- \p{Grapheme_Base: Y*} (Short: \p{GrBase=Y}, \p{GrBase}) (108_660)
- \p{Grapheme_Cluster_Break: CN} \p{Grapheme_Cluster_Break=Control}
- (6023)
- \p{Grapheme_Cluster_Break: Control} (Short: \p{GCB=CN}) (6023)
- \p{Grapheme_Cluster_Break: CR} (Short: \p{GCB=CR}) (1)
- \p{Grapheme_Cluster_Break: EX} \p{Grapheme_Cluster_Break=Extend}
- (1317)
- \p{Grapheme_Cluster_Break: Extend} (Short: \p{GCB=EX}) (1317)
- \p{Grapheme_Cluster_Break: L} (Short: \p{GCB=L}) (125)
- \p{Grapheme_Cluster_Break: LF} (Short: \p{GCB=LF}) (1)
- \p{Grapheme_Cluster_Break: LV} (Short: \p{GCB=LV}) (399)
- \p{Grapheme_Cluster_Break: LVT} (Short: \p{GCB=LVT}) (10_773)
- \p{Grapheme_Cluster_Break: Other} (Short: \p{GCB=XX}) (1_094_950)
- \p{Grapheme_Cluster_Break: PP} \p{Grapheme_Cluster_Break=Prepend}
- (0)
- \p{Grapheme_Cluster_Break: Prepend} (Short: \p{GCB=PP}) (0)
- \p{Grapheme_Cluster_Break: SM} \p{Grapheme_Cluster_Break=
- SpacingMark} (291)
- \p{Grapheme_Cluster_Break: SpacingMark} (Short: \p{GCB=SM}) (291)
- \p{Grapheme_Cluster_Break: T} (Short: \p{GCB=T}) (137)
- \p{Grapheme_Cluster_Break: V} (Short: \p{GCB=V}) (95)
- \p{Grapheme_Cluster_Break: XX} \p{Grapheme_Cluster_Break=Other}
- (1_094_950)
- \p{Grapheme_Extend} \p{Grapheme_Extend=Y} (Short: \p{GrExt})
- (1317)
- \p{Grapheme_Extend: N*} (Short: \p{GrExt=N}, \P{GrExt}) (1_112_795)
- \p{Grapheme_Extend: Y*} (Short: \p{GrExt=Y}, \p{GrExt}) (1317)
- \p{Greek} \p{Script=Greek} (Short: \p{Grek}; NOT
- \p{Greek_And_Coptic}) (511)
- X \p{Greek_And_Coptic} \p{Block=Greek_And_Coptic} (Short:
- \p{InGreek}) (144)
- X \p{Greek_Ext} \p{Greek_Extended} (= \p{Block=
- Greek_Extended}) (256)
- X \p{Greek_Extended} \p{Block=Greek_Extended} (Short:
- \p{InGreekExt}) (256)
- \p{Grek} \p{Greek} (= \p{Script=Greek}) (NOT
- \p{Greek_And_Coptic}) (511)
- \p{Gujarati} \p{Script=Gujarati} (Short: \p{Gujr}; NOT
- \p{Block=Gujarati}) (84)
- \p{Gujr} \p{Gujarati} (= \p{Script=Gujarati}) (NOT
- \p{Block=Gujarati}) (84)
- \p{Gurmukhi} \p{Script=Gurmukhi} (Short: \p{Guru}; NOT
- \p{Block=Gurmukhi}) (79)
- \p{Guru} \p{Gurmukhi} (= \p{Script=Gurmukhi}) (NOT
- \p{Block=Gurmukhi}) (79)
- X \p{Half_And_Full_Forms} \p{Halfwidth_And_Fullwidth_Forms} (=
- \p{Block=Halfwidth_And_Fullwidth_Forms})
- (240)
- X \p{Half_Marks} \p{Combining_Half_Marks} (= \p{Block=
- Combining_Half_Marks}) (16)
- X \p{Halfwidth_And_Fullwidth_Forms} \p{Block=
- Halfwidth_And_Fullwidth_Forms} (Short:
- \p{InHalfAndFullForms}) (240)
- \p{Han} \p{Script=Han} (75_963)
- \p{Hang} \p{Hangul} (= \p{Script=Hangul}) (NOT
- \p{Hangul_Syllables}) (11_739)
- \p{Hangul} \p{Script=Hangul} (Short: \p{Hang}; NOT
- \p{Hangul_Syllables}) (11_739)
- X \p{Hangul_Compatibility_Jamo} \p{Block=Hangul_Compatibility_Jamo}
- (Short: \p{InCompatJamo}) (96)
- X \p{Hangul_Jamo} \p{Block=Hangul_Jamo} (Short: \p{InJamo})
- (256)
- X \p{Hangul_Jamo_Extended_A} \p{Block=Hangul_Jamo_Extended_A}
- (Short: \p{InJamoExtA}) (32)
- X \p{Hangul_Jamo_Extended_B} \p{Block=Hangul_Jamo_Extended_B}
- (Short: \p{InJamoExtB}) (80)
- \p{Hangul_Syllable_Type: L} \p{Hangul_Syllable_Type=Leading_Jamo}
- (125)
- \p{Hangul_Syllable_Type: Leading_Jamo} (Short: \p{Hst=L}) (125)
- \p{Hangul_Syllable_Type: LV} \p{Hangul_Syllable_Type=LV_Syllable}
- (399)
- \p{Hangul_Syllable_Type: LV_Syllable} (Short: \p{Hst=LV}) (399)
- \p{Hangul_Syllable_Type: LVT} \p{Hangul_Syllable_Type=
- LVT_Syllable} (10_773)
- \p{Hangul_Syllable_Type: LVT_Syllable} (Short: \p{Hst=LVT})
- (10_773)
- \p{Hangul_Syllable_Type: NA} \p{Hangul_Syllable_Type=
- Not_Applicable} (1_102_583)
- \p{Hangul_Syllable_Type: Not_Applicable} (Short: \p{Hst=NA})
- (1_102_583)
- \p{Hangul_Syllable_Type: T} \p{Hangul_Syllable_Type=Trailing_Jamo}
- (137)
- \p{Hangul_Syllable_Type: Trailing_Jamo} (Short: \p{Hst=T}) (137)
- \p{Hangul_Syllable_Type: V} \p{Hangul_Syllable_Type=Vowel_Jamo}
- (95)
- \p{Hangul_Syllable_Type: Vowel_Jamo} (Short: \p{Hst=V}) (95)
- X \p{Hangul_Syllables} \p{Block=Hangul_Syllables} (Short:
- \p{InHangul}) (11_184)
- \p{Hani} \p{Han} (= \p{Script=Han}) (75_963)
- \p{Hano} \p{Hanunoo} (= \p{Script=Hanunoo}) (NOT
- \p{Block=Hanunoo}) (21)
- \p{Hanunoo} \p{Script=Hanunoo} (Short: \p{Hano}; NOT
- \p{Block=Hanunoo}) (21)
- \p{Hebr} \p{Hebrew} (= \p{Script=Hebrew}) (NOT
- \p{Block=Hebrew}) (133)
- \p{Hebrew} \p{Script=Hebrew} (Short: \p{Hebr}; NOT
- \p{Block=Hebrew}) (133)
- \p{Hex} \p{XDigit} (= \p{Hex_Digit=Y}) (44)
- \p{Hex: *} \p{Hex_Digit: *}
- \p{Hex_Digit} \p{XDigit} (= \p{Hex_Digit=Y}) (44)
- \p{Hex_Digit: N*} (Short: \p{Hex=N}, \P{Hex}) (1_114_068)
- \p{Hex_Digit: Y*} (Short: \p{Hex=Y}, \p{Hex}) (44)
- X \p{High_Private_Use_Surrogates} \p{Block=
- High_Private_Use_Surrogates} (Short:
- \p{InHighPUSurrogates}) (128)
- X \p{High_PU_Surrogates} \p{High_Private_Use_Surrogates} (=
- \p{Block=High_Private_Use_Surrogates})
- (128)
- X \p{High_Surrogates} \p{Block=High_Surrogates} (896)
- \p{Hira} \p{Hiragana} (= \p{Script=Hiragana}) (NOT
- \p{Block=Hiragana}) (91)
- \p{Hiragana} \p{Script=Hiragana} (Short: \p{Hira}; NOT
- \p{Block=Hiragana}) (91)
- \p{HorizSpace} \p{Blank} (19)
- \p{Hst: *} \p{Hangul_Syllable_Type: *}
- D \p{Hyphen} \p{Hyphen=Y} (11)
- D \p{Hyphen: N*} Supplanted by Line_Break property values;
- see www.unicode.org/reports/tr14
- (Single: \P{Hyphen}) (1_114_101)
- D \p{Hyphen: Y*} Supplanted by Line_Break property values;
- see www.unicode.org/reports/tr14
- (Single: \p{Hyphen}) (11)
- \p{ID_Continue} \p{ID_Continue=Y} (Short: \p{IDC}; NOT
- \p{Ideographic_Description_Characters})
- (103_355)
- \p{ID_Continue: N*} (Short: \p{IDC=N}, \P{IDC}) (1_010_757)
- \p{ID_Continue: Y*} (Short: \p{IDC=Y}, \p{IDC}) (103_355)
- \p{ID_Start} \p{ID_Start=Y} (Short: \p{IDS}) (101_240)
- \p{ID_Start: N*} (Short: \p{IDS=N}, \P{IDS}) (1_012_872)
- \p{ID_Start: Y*} (Short: \p{IDS=Y}, \p{IDS}) (101_240)
- \p{IDC} \p{ID_Continue} (= \p{ID_Continue=Y}) (NOT
- \p{Ideographic_Description_Characters})
- (103_355)
- \p{IDC: *} \p{ID_Continue: *}
- \p{Ideo} \p{Ideographic} (= \p{Ideographic=Y})
- (75_633)
- \p{Ideo: *} \p{Ideographic: *}
- \p{Ideographic} \p{Ideographic=Y} (Short: \p{Ideo})
- (75_633)
- \p{Ideographic: N*} (Short: \p{Ideo=N}, \P{Ideo}) (1_038_479)
- \p{Ideographic: Y*} (Short: \p{Ideo=Y}, \p{Ideo}) (75_633)
- X \p{Ideographic_Description_Characters} \p{Block=
- Ideographic_Description_Characters}
- (Short: \p{InIDC}) (16)
- \p{IDS} \p{ID_Start} (= \p{ID_Start=Y}) (101_240)
- \p{IDS: *} \p{ID_Start: *}
- \p{IDS_Binary_Operator} \p{IDS_Binary_Operator=Y} (Short:
- \p{IDSB}) (10)
- \p{IDS_Binary_Operator: N*} (Short: \p{IDSB=N}, \P{IDSB})
- (1_114_102)
- \p{IDS_Binary_Operator: Y*} (Short: \p{IDSB=Y}, \p{IDSB}) (10)
- \p{IDS_Trinary_Operator} \p{IDS_Trinary_Operator=Y} (Short:
- \p{IDST}) (2)
- \p{IDS_Trinary_Operator: N*} (Short: \p{IDST=N}, \P{IDST})
- (1_114_110)
- \p{IDS_Trinary_Operator: Y*} (Short: \p{IDST=Y}, \p{IDST}) (2)
- \p{IDSB} \p{IDS_Binary_Operator} (=
- \p{IDS_Binary_Operator=Y}) (10)
- \p{IDSB: *} \p{IDS_Binary_Operator: *}
- \p{IDST} \p{IDS_Trinary_Operator} (=
- \p{IDS_Trinary_Operator=Y}) (2)
- \p{IDST: *} \p{IDS_Trinary_Operator: *}
- \p{Imperial_Aramaic} \p{Script=Imperial_Aramaic} (Short:
- \p{Armi}; NOT \p{Block=
- Imperial_Aramaic}) (31)
- \p{In: *} \p{Present_In: *} (Perl extension)
- \p{In_*} \p{Block: *}
- X \p{Indic_Number_Forms} \p{Common_Indic_Number_Forms} (= \p{Block=
- Common_Indic_Number_Forms}) (16)
- \p{Inherited} \p{Script=Inherited} (Short: \p{Zinh})
- (524)
- \p{Initial_Punctuation} \p{General_Category=Initial_Punctuation}
- (Short: \p{Pi}) (12)
- \p{Inscriptional_Pahlavi} \p{Script=Inscriptional_Pahlavi} (Short:
- \p{Phli}; NOT \p{Block=
- Inscriptional_Pahlavi}) (27)
- \p{Inscriptional_Parthian} \p{Script=Inscriptional_Parthian}
- (Short: \p{Prti}; NOT \p{Block=
- Inscriptional_Parthian}) (30)
- X \p{IPA_Ext} \p{IPA_Extensions} (= \p{Block=
- IPA_Extensions}) (96)
- X \p{IPA_Extensions} \p{Block=IPA_Extensions} (Short:
- \p{InIPAExt}) (96)
- \p{Is_*} \p{*} (Any exceptions are individually
- noted beginning with the word NOT.) If
- an entry has flag(s) at its beginning,
- like "D", the "Is_" form has the same
- flag(s)
- \p{Ital} \p{Old_Italic} (= \p{Script=Old_Italic})
- (NOT \p{Block=Old_Italic}) (35)
- X \p{Jamo} \p{Hangul_Jamo} (= \p{Block=Hangul_Jamo})
- (256)
- X \p{Jamo_Ext_A} \p{Hangul_Jamo_Extended_A} (= \p{Block=
- Hangul_Jamo_Extended_A}) (32)
- X \p{Jamo_Ext_B} \p{Hangul_Jamo_Extended_B} (= \p{Block=
- Hangul_Jamo_Extended_B}) (80)
- \p{Java} \p{Javanese} (= \p{Script=Javanese}) (NOT
- \p{Block=Javanese}) (91)
- \p{Javanese} \p{Script=Javanese} (Short: \p{Java}; NOT
- \p{Block=Javanese}) (91)
- \p{Jg: *} \p{Joining_Group: *}
- \p{Join_C} \p{Join_Control} (= \p{Join_Control=Y}) (2)
- \p{Join_C: *} \p{Join_Control: *}
- \p{Join_Control} \p{Join_Control=Y} (Short: \p{JoinC}) (2)
- \p{Join_Control: N*} (Short: \p{JoinC=N}, \P{JoinC}) (1_114_110)
- \p{Join_Control: Y*} (Short: \p{JoinC=Y}, \p{JoinC}) (2)
- \p{Joining_Group: Ain} (Short: \p{Jg=Ain}) (7)
- \p{Joining_Group: Alaph} (Short: \p{Jg=Alaph}) (1)
- \p{Joining_Group: Alef} (Short: \p{Jg=Alef}) (10)
- \p{Joining_Group: Beh} (Short: \p{Jg=Beh}) (20)
- \p{Joining_Group: Beth} (Short: \p{Jg=Beth}) (2)
- \p{Joining_Group: Burushaski_Yeh_Barree} (Short: \p{Jg=
- BurushaskiYehBarree}) (2)
- \p{Joining_Group: Dal} (Short: \p{Jg=Dal}) (14)
- \p{Joining_Group: Dalath_Rish} (Short: \p{Jg=DalathRish}) (4)
- \p{Joining_Group: E} (Short: \p{Jg=E}) (1)
- \p{Joining_Group: Farsi_Yeh} (Short: \p{Jg=FarsiYeh}) (7)
- \p{Joining_Group: Fe} (Short: \p{Jg=Fe}) (1)
- \p{Joining_Group: Feh} (Short: \p{Jg=Feh}) (10)
- \p{Joining_Group: Final_Semkath} (Short: \p{Jg=FinalSemkath}) (1)
- \p{Joining_Group: Gaf} (Short: \p{Jg=Gaf}) (13)
- \p{Joining_Group: Gamal} (Short: \p{Jg=Gamal}) (3)
- \p{Joining_Group: Hah} (Short: \p{Jg=Hah}) (18)
- \p{Joining_Group: Hamza_On_Heh_Goal} (Short: \p{Jg=
- HamzaOnHehGoal}) (1)
- \p{Joining_Group: He} (Short: \p{Jg=He}) (1)
- \p{Joining_Group: Heh} (Short: \p{Jg=Heh}) (1)
- \p{Joining_Group: Heh_Goal} (Short: \p{Jg=HehGoal}) (2)
- \p{Joining_Group: Heth} (Short: \p{Jg=Heth}) (1)
- \p{Joining_Group: Kaf} (Short: \p{Jg=Kaf}) (5)
- \p{Joining_Group: Kaph} (Short: \p{Jg=Kaph}) (1)
- \p{Joining_Group: Khaph} (Short: \p{Jg=Khaph}) (1)
- \p{Joining_Group: Knotted_Heh} (Short: \p{Jg=KnottedHeh}) (2)
- \p{Joining_Group: Lam} (Short: \p{Jg=Lam}) (7)
- \p{Joining_Group: Lamadh} (Short: \p{Jg=Lamadh}) (1)
- \p{Joining_Group: Meem} (Short: \p{Jg=Meem}) (4)
- \p{Joining_Group: Mim} (Short: \p{Jg=Mim}) (1)
- \p{Joining_Group: No_Joining_Group} (Short: \p{Jg=NoJoiningGroup})
- (1_113_870)
- \p{Joining_Group: Noon} (Short: \p{Jg=Noon}) (8)
- \p{Joining_Group: Nun} (Short: \p{Jg=Nun}) (1)
- \p{Joining_Group: Nya} (Short: \p{Jg=Nya}) (1)
- \p{Joining_Group: Pe} (Short: \p{Jg=Pe}) (1)
- \p{Joining_Group: Qaf} (Short: \p{Jg=Qaf}) (5)
- \p{Joining_Group: Qaph} (Short: \p{Jg=Qaph}) (1)
- \p{Joining_Group: Reh} (Short: \p{Jg=Reh}) (17)
- \p{Joining_Group: Reversed_Pe} (Short: \p{Jg=ReversedPe}) (1)
- \p{Joining_Group: Rohingya_Yeh} (Short: \p{Jg=RohingyaYeh}) (1)
- \p{Joining_Group: Sad} (Short: \p{Jg=Sad}) (5)
- \p{Joining_Group: Sadhe} (Short: \p{Jg=Sadhe}) (1)
- \p{Joining_Group: Seen} (Short: \p{Jg=Seen}) (11)
- \p{Joining_Group: Semkath} (Short: \p{Jg=Semkath}) (1)
- \p{Joining_Group: Shin} (Short: \p{Jg=Shin}) (1)
- \p{Joining_Group: Swash_Kaf} (Short: \p{Jg=SwashKaf}) (1)
- \p{Joining_Group: Syriac_Waw} (Short: \p{Jg=SyriacWaw}) (1)
- \p{Joining_Group: Tah} (Short: \p{Jg=Tah}) (4)
- \p{Joining_Group: Taw} (Short: \p{Jg=Taw}) (1)
- \p{Joining_Group: Teh_Marbuta} (Short: \p{Jg=TehMarbuta}) (3)
- \p{Joining_Group: Teh_Marbuta_Goal} \p{Joining_Group=
- Hamza_On_Heh_Goal} (1)
- \p{Joining_Group: Teth} (Short: \p{Jg=Teth}) (2)
- \p{Joining_Group: Waw} (Short: \p{Jg=Waw}) (16)
- \p{Joining_Group: Yeh} (Short: \p{Jg=Yeh}) (10)
- \p{Joining_Group: Yeh_Barree} (Short: \p{Jg=YehBarree}) (2)
- \p{Joining_Group: Yeh_With_Tail} (Short: \p{Jg=YehWithTail}) (1)
- \p{Joining_Group: Yudh} (Short: \p{Jg=Yudh}) (1)
- \p{Joining_Group: Yudh_He} (Short: \p{Jg=YudhHe}) (1)
- \p{Joining_Group: Zain} (Short: \p{Jg=Zain}) (1)
- \p{Joining_Group: Zhain} (Short: \p{Jg=Zhain}) (1)
- \p{Joining_Type: C} \p{Joining_Type=Join_Causing} (3)
- \p{Joining_Type: D} \p{Joining_Type=Dual_Joining} (215)
- \p{Joining_Type: Dual_Joining} (Short: \p{Jt=D}) (215)
- \p{Joining_Type: Join_Causing} (Short: \p{Jt=C}) (3)
- \p{Joining_Type: L} \p{Joining_Type=Left_Joining} (0)
- \p{Joining_Type: Left_Joining} (Short: \p{Jt=L}) (0)
- \p{Joining_Type: Non_Joining} (Short: \p{Jt=U}) (1_112_389)
- \p{Joining_Type: R} \p{Joining_Type=Right_Joining} (82)
- \p{Joining_Type: Right_Joining} (Short: \p{Jt=R}) (82)
- \p{Joining_Type: T} \p{Joining_Type=Transparent} (1423)
- \p{Joining_Type: Transparent} (Short: \p{Jt=T}) (1423)
- \p{Joining_Type: U} \p{Joining_Type=Non_Joining} (1_112_389)
- \p{Jt: *} \p{Joining_Type: *}
- \p{Kaithi} \p{Script=Kaithi} (Short: \p{Kthi}; NOT
- \p{Block=Kaithi}) (66)
- \p{Kali} \p{Kayah_Li} (= \p{Script=Kayah_Li}) (48)
- \p{Kana} \p{Katakana} (= \p{Script=Katakana}) (NOT
- \p{Block=Katakana}) (300)
- X \p{Kana_Sup} \p{Kana_Supplement} (= \p{Block=
- Kana_Supplement}) (256)
- X \p{Kana_Supplement} \p{Block=Kana_Supplement} (Short:
- \p{InKanaSup}) (256)
- X \p{Kanbun} \p{Block=Kanbun} (16)
- X \p{Kangxi} \p{Kangxi_Radicals} (= \p{Block=
- Kangxi_Radicals}) (224)
- X \p{Kangxi_Radicals} \p{Block=Kangxi_Radicals} (Short:
- \p{InKangxi}) (224)
- \p{Kannada} \p{Script=Kannada} (Short: \p{Knda}; NOT
- \p{Block=Kannada}) (86)
- \p{Katakana} \p{Script=Katakana} (Short: \p{Kana}; NOT
- \p{Block=Katakana}) (300)
- X \p{Katakana_Ext} \p{Katakana_Phonetic_Extensions} (=
- \p{Block=Katakana_Phonetic_Extensions})
- (16)
- X \p{Katakana_Phonetic_Extensions} \p{Block=
- Katakana_Phonetic_Extensions} (Short:
- \p{InKatakanaExt}) (16)
- \p{Kayah_Li} \p{Script=Kayah_Li} (Short: \p{Kali}) (48)
- \p{Khar} \p{Kharoshthi} (= \p{Script=Kharoshthi})
- (NOT \p{Block=Kharoshthi}) (65)
- \p{Kharoshthi} \p{Script=Kharoshthi} (Short: \p{Khar};
- NOT \p{Block=Kharoshthi}) (65)
- \p{Khmer} \p{Script=Khmer} (Short: \p{Khmr}; NOT
- \p{Block=Khmer}) (146)
- X \p{Khmer_Symbols} \p{Block=Khmer_Symbols} (32)
- \p{Khmr} \p{Khmer} (= \p{Script=Khmer}) (NOT
- \p{Block=Khmer}) (146)
- \p{Knda} \p{Kannada} (= \p{Script=Kannada}) (NOT
- \p{Block=Kannada}) (86)
- \p{Kthi} \p{Kaithi} (= \p{Script=Kaithi}) (NOT
- \p{Block=Kaithi}) (66)
- \p{L} \p{Letter} (= \p{General_Category=Letter})
- (101_013)
- X \p{L&} \p{Cased_Letter} (= \p{General_Category=
- Cased_Letter}) (3223)
- X \p{L_} \p{Cased_Letter} (= \p{General_Category=
- Cased_Letter}) Note the trailing '_'
- matters in spite of loose matching
- rules. (3223)
- \p{Lana} \p{Tai_Tham} (= \p{Script=Tai_Tham}) (NOT
- \p{Block=Tai_Tham}) (127)
- \p{Lao} \p{Script=Lao} (NOT \p{Block=Lao}) (67)
- \p{Laoo} \p{Lao} (= \p{Script=Lao}) (NOT \p{Block=
- Lao}) (67)
- \p{Latin} \p{Script=Latin} (Short: \p{Latn}) (1272)
- X \p{Latin_1} \p{Latin_1_Supplement} (= \p{Block=
- Latin_1_Supplement}) (128)
- X \p{Latin_1_Sup} \p{Latin_1_Supplement} (= \p{Block=
- Latin_1_Supplement}) (128)
- X \p{Latin_1_Supplement} \p{Block=Latin_1_Supplement} (Short:
- \p{InLatin1}) (128)
- X \p{Latin_Ext_A} \p{Latin_Extended_A} (= \p{Block=
- Latin_Extended_A}) (128)
- X \p{Latin_Ext_Additional} \p{Latin_Extended_Additional} (=
- \p{Block=Latin_Extended_Additional})
- (256)
- X \p{Latin_Ext_B} \p{Latin_Extended_B} (= \p{Block=
- Latin_Extended_B}) (208)
- X \p{Latin_Ext_C} \p{Latin_Extended_C} (= \p{Block=
- Latin_Extended_C}) (32)
- X \p{Latin_Ext_D} \p{Latin_Extended_D} (= \p{Block=
- Latin_Extended_D}) (224)
- X \p{Latin_Extended_A} \p{Block=Latin_Extended_A} (Short:
- \p{InLatinExtA}) (128)
- X \p{Latin_Extended_Additional} \p{Block=Latin_Extended_Additional}
- (Short: \p{InLatinExtAdditional}) (256)
- X \p{Latin_Extended_B} \p{Block=Latin_Extended_B} (Short:
- \p{InLatinExtB}) (208)
- X \p{Latin_Extended_C} \p{Block=Latin_Extended_C} (Short:
- \p{InLatinExtC}) (32)
- X \p{Latin_Extended_D} \p{Block=Latin_Extended_D} (Short:
- \p{InLatinExtD}) (224)
- \p{Latn} \p{Latin} (= \p{Script=Latin}) (1272)
- \p{Lb: *} \p{Line_Break: *}
- \p{LC} \p{Cased_Letter} (= \p{General_Category=
- Cased_Letter}) (3223)
- \p{Lepc} \p{Lepcha} (= \p{Script=Lepcha}) (NOT
- \p{Block=Lepcha}) (74)
- \p{Lepcha} \p{Script=Lepcha} (Short: \p{Lepc}; NOT
- \p{Block=Lepcha}) (74)
- \p{Letter} \p{General_Category=Letter} (Short: \p{L})
- (101_013)
- \p{Letter_Number} \p{General_Category=Letter_Number} (Short:
- \p{Nl}) (224)
- X \p{Letterlike_Symbols} \p{Block=Letterlike_Symbols} (80)
- \p{Limb} \p{Limbu} (= \p{Script=Limbu}) (NOT
- \p{Block=Limbu}) (66)
- \p{Limbu} \p{Script=Limbu} (Short: \p{Limb}; NOT
- \p{Block=Limbu}) (66)
- \p{Linb} \p{Linear_B} (= \p{Script=Linear_B}) (211)
- \p{Line_Break: AI} \p{Line_Break=Ambiguous} (724)
- \p{Line_Break: AL} \p{Line_Break=Alphabetic} (16_251)
- \p{Line_Break: Alphabetic} (Short: \p{Lb=AL}) (16_251)
- \p{Line_Break: Ambiguous} (Short: \p{Lb=AI}) (724)
- \p{Line_Break: B2} \p{Line_Break=Break_Both} (3)
- \p{Line_Break: BA} \p{Line_Break=Break_After} (151)
- \p{Line_Break: BB} \p{Line_Break=Break_Before} (19)
- \p{Line_Break: BK} \p{Line_Break=Mandatory_Break} (4)
- \p{Line_Break: Break_After} (Short: \p{Lb=BA}) (151)
- \p{Line_Break: Break_Before} (Short: \p{Lb=BB}) (19)
- \p{Line_Break: Break_Both} (Short: \p{Lb=B2}) (3)
- \p{Line_Break: Break_Symbols} (Short: \p{Lb=SY}) (1)
- \p{Line_Break: Carriage_Return} (Short: \p{Lb=CR}) (1)
- \p{Line_Break: CB} \p{Line_Break=Contingent_Break} (1)
- \p{Line_Break: CJ} \p{Line_Break=
- Conditional_Japanese_Starter} (51)
- \p{Line_Break: CL} \p{Line_Break=Close_Punctuation} (87)
- \p{Line_Break: Close_Parenthesis} (Short: \p{Lb=CP}) (2)
- \p{Line_Break: Close_Punctuation} (Short: \p{Lb=CL}) (87)
- \p{Line_Break: CM} \p{Line_Break=Combining_Mark} (1628)
- \p{Line_Break: Combining_Mark} (Short: \p{Lb=CM}) (1628)
- \p{Line_Break: Complex_Context} (Short: \p{Lb=SA}) (665)
- \p{Line_Break: Conditional_Japanese_Starter} (Short: \p{Lb=CJ})
- (51)
- \p{Line_Break: Contingent_Break} (Short: \p{Lb=CB}) (1)
- \p{Line_Break: CP} \p{Line_Break=Close_Parenthesis} (2)
- \p{Line_Break: CR} \p{Line_Break=Carriage_Return} (1)
- \p{Line_Break: EX} \p{Line_Break=Exclamation} (34)
- \p{Line_Break: Exclamation} (Short: \p{Lb=EX}) (34)
- \p{Line_Break: GL} \p{Line_Break=Glue} (18)
- \p{Line_Break: Glue} (Short: \p{Lb=GL}) (18)
- \p{Line_Break: H2} (Short: \p{Lb=H2}) (399)
- \p{Line_Break: H3} (Short: \p{Lb=H3}) (10_773)
- \p{Line_Break: Hebrew_Letter} (Short: \p{Lb=HL}) (74)
- \p{Line_Break: HL} \p{Line_Break=Hebrew_Letter} (74)
- \p{Line_Break: HY} \p{Line_Break=Hyphen} (1)
- \p{Line_Break: Hyphen} (Short: \p{Lb=HY}) (1)
- \p{Line_Break: ID} \p{Line_Break=Ideographic} (161_793)
- \p{Line_Break: Ideographic} (Short: \p{Lb=ID}) (161_793)
- \p{Line_Break: IN} \p{Line_Break=Inseparable} (4)
- \p{Line_Break: Infix_Numeric} (Short: \p{Lb=IS}) (13)
- \p{Line_Break: Inseparable} (Short: \p{Lb=IN}) (4)
- \p{Line_Break: Inseperable} \p{Line_Break=Inseparable} (4)
- \p{Line_Break: IS} \p{Line_Break=Infix_Numeric} (13)
- \p{Line_Break: JL} (Short: \p{Lb=JL}) (125)
- \p{Line_Break: JT} (Short: \p{Lb=JT}) (137)
- \p{Line_Break: JV} (Short: \p{Lb=JV}) (95)
- \p{Line_Break: LF} \p{Line_Break=Line_Feed} (1)
- \p{Line_Break: Line_Feed} (Short: \p{Lb=LF}) (1)
- \p{Line_Break: Mandatory_Break} (Short: \p{Lb=BK}) (4)
- \p{Line_Break: Next_Line} (Short: \p{Lb=NL}) (1)
- \p{Line_Break: NL} \p{Line_Break=Next_Line} (1)
- \p{Line_Break: Nonstarter} (Short: \p{Lb=NS}) (26)
- \p{Line_Break: NS} \p{Line_Break=Nonstarter} (26)
- \p{Line_Break: NU} \p{Line_Break=Numeric} (452)
- \p{Line_Break: Numeric} (Short: \p{Lb=NU}) (452)
- \p{Line_Break: OP} \p{Line_Break=Open_Punctuation} (81)
- \p{Line_Break: Open_Punctuation} (Short: \p{Lb=OP}) (81)
- \p{Line_Break: PO} \p{Line_Break=Postfix_Numeric} (28)
- \p{Line_Break: Postfix_Numeric} (Short: \p{Lb=PO}) (28)
- \p{Line_Break: PR} \p{Line_Break=Prefix_Numeric} (45)
- \p{Line_Break: Prefix_Numeric} (Short: \p{Lb=PR}) (45)
- \p{Line_Break: QU} \p{Line_Break=Quotation} (34)
- \p{Line_Break: Quotation} (Short: \p{Lb=QU}) (34)
- \p{Line_Break: SA} \p{Line_Break=Complex_Context} (665)
- D \p{Line_Break: SG} \p{Line_Break=Surrogate} (2048)
- \p{Line_Break: SP} \p{Line_Break=Space} (1)
- \p{Line_Break: Space} (Short: \p{Lb=SP}) (1)
- D \p{Line_Break: Surrogate} Deprecated by Unicode because surrogates
- should never appear in well-formed text,
- and therefore shouldn't be the basis for
- line breaking (Short: \p{Lb=SG}) (2048)
- \p{Line_Break: SY} \p{Line_Break=Break_Symbols} (1)
- \p{Line_Break: Unknown} (Short: \p{Lb=XX}) (918_338)
- \p{Line_Break: WJ} \p{Line_Break=Word_Joiner} (2)
- \p{Line_Break: Word_Joiner} (Short: \p{Lb=WJ}) (2)
- \p{Line_Break: XX} \p{Line_Break=Unknown} (918_338)
- \p{Line_Break: ZW} \p{Line_Break=ZWSpace} (1)
- \p{Line_Break: ZWSpace} (Short: \p{Lb=ZW}) (1)
- \p{Line_Separator} \p{General_Category=Line_Separator}
- (Short: \p{Zl}) (1)
- \p{Linear_B} \p{Script=Linear_B} (Short: \p{Linb}) (211)
- X \p{Linear_B_Ideograms} \p{Block=Linear_B_Ideograms} (128)
- X \p{Linear_B_Syllabary} \p{Block=Linear_B_Syllabary} (128)
- \p{Lisu} \p{Script=Lisu} (48)
- \p{Ll} \p{Lowercase_Letter} (=
- \p{General_Category=Lowercase_Letter})
- (/i= General_Category=Cased_Letter)
- (1751)
- \p{Lm} \p{Modifier_Letter} (=
- \p{General_Category=Modifier_Letter})
- (237)
- \p{Lo} \p{Other_Letter} (= \p{General_Category=
- Other_Letter}) (97_553)
- \p{LOE} \p{Logical_Order_Exception} (=
- \p{Logical_Order_Exception=Y}) (15)
- \p{LOE: *} \p{Logical_Order_Exception: *}
- \p{Logical_Order_Exception} \p{Logical_Order_Exception=Y} (Short:
- \p{LOE}) (15)
- \p{Logical_Order_Exception: N*} (Short: \p{LOE=N}, \P{LOE})
- (1_114_097)
- \p{Logical_Order_Exception: Y*} (Short: \p{LOE=Y}, \p{LOE}) (15)
- X \p{Low_Surrogates} \p{Block=Low_Surrogates} (1024)
- \p{Lower} \p{Lowercase=Y} (/i= Cased=Yes) (1934)
- \p{Lower: *} \p{Lowercase: *}
- \p{Lowercase} \p{Lower} (= \p{Lowercase=Y}) (/i= Cased=
- Yes) (1934)
- \p{Lowercase: N*} (Short: \p{Lower=N}, \P{Lower}; /i= Cased=
- No) (1_112_178)
- \p{Lowercase: Y*} (Short: \p{Lower=Y}, \p{Lower}; /i= Cased=
- Yes) (1934)
- \p{Lowercase_Letter} \p{General_Category=Lowercase_Letter}
- (Short: \p{Ll}; /i= General_Category=
- Cased_Letter) (1751)
- \p{Lt} \p{Titlecase_Letter} (=
- \p{General_Category=Titlecase_Letter})
- (/i= General_Category=Cased_Letter) (31)
- \p{Lu} \p{Uppercase_Letter} (=
- \p{General_Category=Uppercase_Letter})
- (/i= General_Category=Cased_Letter)
- (1441)
- \p{Lyci} \p{Lycian} (= \p{Script=Lycian}) (NOT
- \p{Block=Lycian}) (29)
- \p{Lycian} \p{Script=Lycian} (Short: \p{Lyci}; NOT
- \p{Block=Lycian}) (29)
- \p{Lydi} \p{Lydian} (= \p{Script=Lydian}) (NOT
- \p{Block=Lydian}) (27)
- \p{Lydian} \p{Script=Lydian} (Short: \p{Lydi}; NOT
- \p{Block=Lydian}) (27)
- \p{M} \p{Mark} (= \p{General_Category=Mark})
- (1645)
- X \p{Mahjong} \p{Mahjong_Tiles} (= \p{Block=
- Mahjong_Tiles}) (48)
- X \p{Mahjong_Tiles} \p{Block=Mahjong_Tiles} (Short:
- \p{InMahjong}) (48)
- \p{Malayalam} \p{Script=Malayalam} (Short: \p{Mlym}; NOT
- \p{Block=Malayalam}) (98)
- \p{Mand} \p{Mandaic} (= \p{Script=Mandaic}) (NOT
- \p{Block=Mandaic}) (29)
- \p{Mandaic} \p{Script=Mandaic} (Short: \p{Mand}; NOT
- \p{Block=Mandaic}) (29)
- \p{Mark} \p{General_Category=Mark} (Short: \p{M})
- (1645)
- \p{Math} \p{Math=Y} (2310)
- \p{Math: N*} (Single: \P{Math}) (1_111_802)
- \p{Math: Y*} (Single: \p{Math}) (2310)
- X \p{Math_Alphanum} \p{Mathematical_Alphanumeric_Symbols} (=
- \p{Block=
- Mathematical_Alphanumeric_Symbols})
- (1024)
- X \p{Math_Operators} \p{Mathematical_Operators} (= \p{Block=
- Mathematical_Operators}) (256)
- \p{Math_Symbol} \p{General_Category=Math_Symbol} (Short:
- \p{Sm}) (952)
- X \p{Mathematical_Alphanumeric_Symbols} \p{Block=
- Mathematical_Alphanumeric_Symbols}
- (Short: \p{InMathAlphanum}) (1024)
- X \p{Mathematical_Operators} \p{Block=Mathematical_Operators}
- (Short: \p{InMathOperators}) (256)
- \p{Mc} \p{Spacing_Mark} (= \p{General_Category=
- Spacing_Mark}) (353)
- \p{Me} \p{Enclosing_Mark} (= \p{General_Category=
- Enclosing_Mark}) (12)
- \p{Meetei_Mayek} \p{Script=Meetei_Mayek} (Short: \p{Mtei};
- NOT \p{Block=Meetei_Mayek}) (79)
- X \p{Meetei_Mayek_Ext} \p{Meetei_Mayek_Extensions} (= \p{Block=
- Meetei_Mayek_Extensions}) (32)
- X \p{Meetei_Mayek_Extensions} \p{Block=Meetei_Mayek_Extensions}
- (Short: \p{InMeeteiMayekExt}) (32)
- \p{Merc} \p{Meroitic_Cursive} (= \p{Script=
- Meroitic_Cursive}) (NOT \p{Block=
- Meroitic_Cursive}) (26)
- \p{Mero} \p{Meroitic_Hieroglyphs} (= \p{Script=
- Meroitic_Hieroglyphs}) (32)
- \p{Meroitic_Cursive} \p{Script=Meroitic_Cursive} (Short:
- \p{Merc}; NOT \p{Block=
- Meroitic_Cursive}) (26)
- \p{Meroitic_Hieroglyphs} \p{Script=Meroitic_Hieroglyphs} (Short:
- \p{Mero}) (32)
- \p{Miao} \p{Script=Miao} (NOT \p{Block=Miao}) (133)
- X \p{Misc_Arrows} \p{Miscellaneous_Symbols_And_Arrows} (=
- \p{Block=
- Miscellaneous_Symbols_And_Arrows}) (256)
- X \p{Misc_Math_Symbols_A} \p{Miscellaneous_Mathematical_Symbols_A}
- (= \p{Block=
- Miscellaneous_Mathematical_Symbols_A})
- (48)
- X \p{Misc_Math_Symbols_B} \p{Miscellaneous_Mathematical_Symbols_B}
- (= \p{Block=
- Miscellaneous_Mathematical_Symbols_B})
- (128)
- X \p{Misc_Pictographs} \p{Miscellaneous_Symbols_And_Pictographs}
- (= \p{Block=
- Miscellaneous_Symbols_And_Pictographs})
- (768)
- X \p{Misc_Symbols} \p{Miscellaneous_Symbols} (= \p{Block=
- Miscellaneous_Symbols}) (256)
- X \p{Misc_Technical} \p{Miscellaneous_Technical} (= \p{Block=
- Miscellaneous_Technical}) (256)
- X \p{Miscellaneous_Mathematical_Symbols_A} \p{Block=
- Miscellaneous_Mathematical_Symbols_A}
- (Short: \p{InMiscMathSymbolsA}) (48)
- X \p{Miscellaneous_Mathematical_Symbols_B} \p{Block=
- Miscellaneous_Mathematical_Symbols_B}
- (Short: \p{InMiscMathSymbolsB}) (128)
- X \p{Miscellaneous_Symbols} \p{Block=Miscellaneous_Symbols} (Short:
- \p{InMiscSymbols}) (256)
- X \p{Miscellaneous_Symbols_And_Arrows} \p{Block=
- Miscellaneous_Symbols_And_Arrows}
- (Short: \p{InMiscArrows}) (256)
- X \p{Miscellaneous_Symbols_And_Pictographs} \p{Block=
- Miscellaneous_Symbols_And_Pictographs}
- (Short: \p{InMiscPictographs}) (768)
- X \p{Miscellaneous_Technical} \p{Block=Miscellaneous_Technical}
- (Short: \p{InMiscTechnical}) (256)
- \p{Mlym} \p{Malayalam} (= \p{Script=Malayalam})
- (NOT \p{Block=Malayalam}) (98)
- \p{Mn} \p{Nonspacing_Mark} (=
- \p{General_Category=Nonspacing_Mark})
- (1280)
- \p{Modifier_Letter} \p{General_Category=Modifier_Letter}
- (Short: \p{Lm}) (237)
- X \p{Modifier_Letters} \p{Spacing_Modifier_Letters} (= \p{Block=
- Spacing_Modifier_Letters}) (80)
- \p{Modifier_Symbol} \p{General_Category=Modifier_Symbol}
- (Short: \p{Sk}) (115)
- X \p{Modifier_Tone_Letters} \p{Block=Modifier_Tone_Letters} (32)
- \p{Mong} \p{Mongolian} (= \p{Script=Mongolian})
- (NOT \p{Block=Mongolian}) (153)
- \p{Mongolian} \p{Script=Mongolian} (Short: \p{Mong}; NOT
- \p{Block=Mongolian}) (153)
- \p{Mtei} \p{Meetei_Mayek} (= \p{Script=
- Meetei_Mayek}) (NOT \p{Block=
- Meetei_Mayek}) (79)
- X \p{Music} \p{Musical_Symbols} (= \p{Block=
- Musical_Symbols}) (256)
- X \p{Musical_Symbols} \p{Block=Musical_Symbols} (Short:
- \p{InMusic}) (256)
- \p{Myanmar} \p{Script=Myanmar} (Short: \p{Mymr}; NOT
- \p{Block=Myanmar}) (188)
- X \p{Myanmar_Ext_A} \p{Myanmar_Extended_A} (= \p{Block=
- Myanmar_Extended_A}) (32)
- X \p{Myanmar_Extended_A} \p{Block=Myanmar_Extended_A} (Short:
- \p{InMyanmarExtA}) (32)
- \p{Mymr} \p{Myanmar} (= \p{Script=Myanmar}) (NOT
- \p{Block=Myanmar}) (188)
- \p{N} \p{Number} (= \p{General_Category=Number})
- (1148)
- X \p{NB} \p{No_Block} (= \p{Block=No_Block})
- (860_672)
- \p{NChar} \p{Noncharacter_Code_Point} (=
- \p{Noncharacter_Code_Point=Y}) (66)
- \p{NChar: *} \p{Noncharacter_Code_Point: *}
- \p{Nd} \p{Digit} (= \p{General_Category=
- Decimal_Number}) (460)
- \p{New_Tai_Lue} \p{Script=New_Tai_Lue} (Short: \p{Talu};
- NOT \p{Block=New_Tai_Lue}) (83)
- \p{NFC_QC: *} \p{NFC_Quick_Check: *}
- \p{NFC_Quick_Check: M} \p{NFC_Quick_Check=Maybe} (104)
- \p{NFC_Quick_Check: Maybe} (Short: \p{NFCQC=M}) (104)
- \p{NFC_Quick_Check: N} \p{NFC_Quick_Check=No} (NOT
- \P{NFC_Quick_Check} NOR \P{NFC_QC})
- (1120)
- \p{NFC_Quick_Check: No} (Short: \p{NFCQC=N}; NOT
- \P{NFC_Quick_Check} NOR \P{NFC_QC})
- (1120)
- \p{NFC_Quick_Check: Y} \p{NFC_Quick_Check=Yes} (NOT
- \p{NFC_Quick_Check} NOR \p{NFC_QC})
- (1_112_888)
- \p{NFC_Quick_Check: Yes} (Short: \p{NFCQC=Y}; NOT
- \p{NFC_Quick_Check} NOR \p{NFC_QC})
- (1_112_888)
- \p{NFD_QC: *} \p{NFD_Quick_Check: *}
- \p{NFD_Quick_Check: N} \p{NFD_Quick_Check=No} (NOT
- \P{NFD_Quick_Check} NOR \P{NFD_QC})
- (13_225)
- \p{NFD_Quick_Check: No} (Short: \p{NFDQC=N}; NOT
- \P{NFD_Quick_Check} NOR \P{NFD_QC})
- (13_225)
- \p{NFD_Quick_Check: Y} \p{NFD_Quick_Check=Yes} (NOT
- \p{NFD_Quick_Check} NOR \p{NFD_QC})
- (1_100_887)
- \p{NFD_Quick_Check: Yes} (Short: \p{NFDQC=Y}; NOT
- \p{NFD_Quick_Check} NOR \p{NFD_QC})
- (1_100_887)
- \p{NFKC_QC: *} \p{NFKC_Quick_Check: *}
- \p{NFKC_Quick_Check: M} \p{NFKC_Quick_Check=Maybe} (104)
- \p{NFKC_Quick_Check: Maybe} (Short: \p{NFKCQC=M}) (104)
- \p{NFKC_Quick_Check: N} \p{NFKC_Quick_Check=No} (NOT
- \P{NFKC_Quick_Check} NOR \P{NFKC_QC})
- (4787)
- \p{NFKC_Quick_Check: No} (Short: \p{NFKCQC=N}; NOT
- \P{NFKC_Quick_Check} NOR \P{NFKC_QC})
- (4787)
- \p{NFKC_Quick_Check: Y} \p{NFKC_Quick_Check=Yes} (NOT
- \p{NFKC_Quick_Check} NOR \p{NFKC_QC})
- (1_109_221)
- \p{NFKC_Quick_Check: Yes} (Short: \p{NFKCQC=Y}; NOT
- \p{NFKC_Quick_Check} NOR \p{NFKC_QC})
- (1_109_221)
- \p{NFKD_QC: *} \p{NFKD_Quick_Check: *}
- \p{NFKD_Quick_Check: N} \p{NFKD_Quick_Check=No} (NOT
- \P{NFKD_Quick_Check} NOR \P{NFKD_QC})
- (16_880)
- \p{NFKD_Quick_Check: No} (Short: \p{NFKDQC=N}; NOT
- \P{NFKD_Quick_Check} NOR \P{NFKD_QC})
- (16_880)
- \p{NFKD_Quick_Check: Y} \p{NFKD_Quick_Check=Yes} (NOT
- \p{NFKD_Quick_Check} NOR \p{NFKD_QC})
- (1_097_232)
- \p{NFKD_Quick_Check: Yes} (Short: \p{NFKDQC=Y}; NOT
- \p{NFKD_Quick_Check} NOR \p{NFKD_QC})
- (1_097_232)
- \p{Nko} \p{Script=Nko} (NOT \p{NKo}) (59)
- \p{Nkoo} \p{Nko} (= \p{Script=Nko}) (NOT \p{NKo})
- (59)
- \p{Nl} \p{Letter_Number} (= \p{General_Category=
- Letter_Number}) (224)
- \p{No} \p{Other_Number} (= \p{General_Category=
- Other_Number}) (464)
- X \p{No_Block} \p{Block=No_Block} (Short: \p{InNB})
- (860_672)
- \p{Noncharacter_Code_Point} \p{Noncharacter_Code_Point=Y} (Short:
- \p{NChar}) (66)
- \p{Noncharacter_Code_Point: N*} (Short: \p{NChar=N}, \P{NChar})
- (1_114_046)
- \p{Noncharacter_Code_Point: Y*} (Short: \p{NChar=Y}, \p{NChar})
- (66)
- \p{Nonspacing_Mark} \p{General_Category=Nonspacing_Mark}
- (Short: \p{Mn}) (1280)
- \p{Nt: *} \p{Numeric_Type: *}
- \p{Number} \p{General_Category=Number} (Short: \p{N})
- (1148)
- X \p{Number_Forms} \p{Block=Number_Forms} (64)
- \p{Numeric_Type: De} \p{Numeric_Type=Decimal} (460)
- \p{Numeric_Type: Decimal} (Short: \p{Nt=De}) (460)
- \p{Numeric_Type: Di} \p{Numeric_Type=Digit} (128)
- \p{Numeric_Type: Digit} (Short: \p{Nt=Di}) (128)
- \p{Numeric_Type: None} (Short: \p{Nt=None}) (1_112_887)
- \p{Numeric_Type: Nu} \p{Numeric_Type=Numeric} (637)
- \p{Numeric_Type: Numeric} (Short: \p{Nt=Nu}) (637)
- T \p{Numeric_Value: -1/2} (Short: \p{Nv=-1/2}) (1)
- T \p{Numeric_Value: 0} (Short: \p{Nv=0}) (60)
- T \p{Numeric_Value: 1/16} (Short: \p{Nv=1/16}) (3)
- T \p{Numeric_Value: 1/10} (Short: \p{Nv=1/10}) (1)
- T \p{Numeric_Value: 1/9} (Short: \p{Nv=1/9}) (1)
- T \p{Numeric_Value: 1/8} (Short: \p{Nv=1/8}) (5)
- T \p{Numeric_Value: 1/7} (Short: \p{Nv=1/7}) (1)
- T \p{Numeric_Value: 1/6} (Short: \p{Nv=1/6}) (2)
- T \p{Numeric_Value: 3/16} (Short: \p{Nv=3/16}) (3)
- T \p{Numeric_Value: 1/5} (Short: \p{Nv=1/5}) (1)
- T \p{Numeric_Value: 1/4} (Short: \p{Nv=1/4}) (9)
- T \p{Numeric_Value: 1/3} (Short: \p{Nv=1/3}) (4)
- T \p{Numeric_Value: 3/8} (Short: \p{Nv=3/8}) (1)
- T \p{Numeric_Value: 2/5} (Short: \p{Nv=2/5}) (1)
- T \p{Numeric_Value: 1/2} (Short: \p{Nv=1/2}) (10)
- T \p{Numeric_Value: 3/5} (Short: \p{Nv=3/5}) (1)
- T \p{Numeric_Value: 5/8} (Short: \p{Nv=5/8}) (1)
- T \p{Numeric_Value: 2/3} (Short: \p{Nv=2/3}) (5)
- T \p{Numeric_Value: 3/4} (Short: \p{Nv=3/4}) (6)
- T \p{Numeric_Value: 4/5} (Short: \p{Nv=4/5}) (1)
- T \p{Numeric_Value: 5/6} (Short: \p{Nv=5/6}) (2)
- T \p{Numeric_Value: 7/8} (Short: \p{Nv=7/8}) (1)
- T \p{Numeric_Value: 1} (Short: \p{Nv=1}) (97)
- T \p{Numeric_Value: 3/2} (Short: \p{Nv=3/2}) (1)
- T \p{Numeric_Value: 2} (Short: \p{Nv=2}) (100)
- T \p{Numeric_Value: 5/2} (Short: \p{Nv=5/2}) (1)
- T \p{Numeric_Value: 3} (Short: \p{Nv=3}) (102)
- T \p{Numeric_Value: 7/2} (Short: \p{Nv=7/2}) (1)
- T \p{Numeric_Value: 4} (Short: \p{Nv=4}) (93)
- T \p{Numeric_Value: 9/2} (Short: \p{Nv=9/2}) (1)
- T \p{Numeric_Value: 5} (Short: \p{Nv=5}) (90)
- T \p{Numeric_Value: 11/2} (Short: \p{Nv=11/2}) (1)
- T \p{Numeric_Value: 6} (Short: \p{Nv=6}) (82)
- T \p{Numeric_Value: 13/2} (Short: \p{Nv=13/2}) (1)
- T \p{Numeric_Value: 7} (Short: \p{Nv=7}) (81)
- T \p{Numeric_Value: 15/2} (Short: \p{Nv=15/2}) (1)
- T \p{Numeric_Value: 8} (Short: \p{Nv=8}) (77)
- T \p{Numeric_Value: 17/2} (Short: \p{Nv=17/2}) (1)
- T \p{Numeric_Value: 9} (Short: \p{Nv=9}) (81)
- T \p{Numeric_Value: 10} (Short: \p{Nv=10}) (40)
- T \p{Numeric_Value: 11} (Short: \p{Nv=11}) (6)
- T \p{Numeric_Value: 12} (Short: \p{Nv=12}) (6)
- T \p{Numeric_Value: 13} (Short: \p{Nv=13}) (4)
- T \p{Numeric_Value: 14} (Short: \p{Nv=14}) (4)
- T \p{Numeric_Value: 15} (Short: \p{Nv=15}) (4)
- T \p{Numeric_Value: 16} (Short: \p{Nv=16}) (5)
- T \p{Numeric_Value: 17} (Short: \p{Nv=17}) (5)
- T \p{Numeric_Value: 18} (Short: \p{Nv=18}) (5)
- T \p{Numeric_Value: 19} (Short: \p{Nv=19}) (5)
- T \p{Numeric_Value: 20} (Short: \p{Nv=20}) (19)
- T \p{Numeric_Value: 21} (Short: \p{Nv=21}) (1)
- T \p{Numeric_Value: 22} (Short: \p{Nv=22}) (1)
- T \p{Numeric_Value: 23} (Short: \p{Nv=23}) (1)
- T \p{Numeric_Value: 24} (Short: \p{Nv=24}) (1)
- T \p{Numeric_Value: 25} (Short: \p{Nv=25}) (1)
- T \p{Numeric_Value: 26} (Short: \p{Nv=26}) (1)
- T \p{Numeric_Value: 27} (Short: \p{Nv=27}) (1)
- T \p{Numeric_Value: 28} (Short: \p{Nv=28}) (1)
- T \p{Numeric_Value: 29} (Short: \p{Nv=29}) (1)
- T \p{Numeric_Value: 30} (Short: \p{Nv=30}) (11)
- T \p{Numeric_Value: 31} (Short: \p{Nv=31}) (1)
- T \p{Numeric_Value: 32} (Short: \p{Nv=32}) (1)
- T \p{Numeric_Value: 33} (Short: \p{Nv=33}) (1)
- T \p{Numeric_Value: 34} (Short: \p{Nv=34}) (1)
- T \p{Numeric_Value: 35} (Short: \p{Nv=35}) (1)
- T \p{Numeric_Value: 36} (Short: \p{Nv=36}) (1)
- T \p{Numeric_Value: 37} (Short: \p{Nv=37}) (1)
- T \p{Numeric_Value: 38} (Short: \p{Nv=38}) (1)
- T \p{Numeric_Value: 39} (Short: \p{Nv=39}) (1)
- T \p{Numeric_Value: 40} (Short: \p{Nv=40}) (10)
- T \p{Numeric_Value: 41} (Short: \p{Nv=41}) (1)
- T \p{Numeric_Value: 42} (Short: \p{Nv=42}) (1)
- T \p{Numeric_Value: 43} (Short: \p{Nv=43}) (1)
- T \p{Numeric_Value: 44} (Short: \p{Nv=44}) (1)
- T \p{Numeric_Value: 45} (Short: \p{Nv=45}) (1)
- T \p{Numeric_Value: 46} (Short: \p{Nv=46}) (1)
- T \p{Numeric_Value: 47} (Short: \p{Nv=47}) (1)
- T \p{Numeric_Value: 48} (Short: \p{Nv=48}) (1)
- T \p{Numeric_Value: 49} (Short: \p{Nv=49}) (1)
- T \p{Numeric_Value: 50} (Short: \p{Nv=50}) (20)
- T \p{Numeric_Value: 60} (Short: \p{Nv=60}) (6)
- T \p{Numeric_Value: 70} (Short: \p{Nv=70}) (6)
- T \p{Numeric_Value: 80} (Short: \p{Nv=80}) (6)
- T \p{Numeric_Value: 90} (Short: \p{Nv=90}) (6)
- T \p{Numeric_Value: 100} (Short: \p{Nv=100}) (20)
- T \p{Numeric_Value: 200} (Short: \p{Nv=200}) (2)
- T \p{Numeric_Value: 300} (Short: \p{Nv=300}) (3)
- T \p{Numeric_Value: 400} (Short: \p{Nv=400}) (2)
- T \p{Numeric_Value: 500} (Short: \p{Nv=500}) (12)
- T \p{Numeric_Value: 600} (Short: \p{Nv=600}) (2)
- T \p{Numeric_Value: 700} (Short: \p{Nv=700}) (2)
- T \p{Numeric_Value: 800} (Short: \p{Nv=800}) (2)
- T \p{Numeric_Value: 900} (Short: \p{Nv=900}) (3)
- T \p{Numeric_Value: 1000} (Short: \p{Nv=1000}) (17)
- T \p{Numeric_Value: 2000} (Short: \p{Nv=2000}) (1)
- T \p{Numeric_Value: 3000} (Short: \p{Nv=3000}) (1)
- T \p{Numeric_Value: 4000} (Short: \p{Nv=4000}) (1)
- T \p{Numeric_Value: 5000} (Short: \p{Nv=5000}) (5)
- T \p{Numeric_Value: 6000} (Short: \p{Nv=6000}) (1)
- T \p{Numeric_Value: 7000} (Short: \p{Nv=7000}) (1)
- T \p{Numeric_Value: 8000} (Short: \p{Nv=8000}) (1)
- T \p{Numeric_Value: 9000} (Short: \p{Nv=9000}) (1)
- T \p{Numeric_Value: 10000} (= 1.0e+004) (Short: \p{Nv=10000}) (7)
- T \p{Numeric_Value: 20000} (= 2.0e+004) (Short: \p{Nv=20000}) (1)
- T \p{Numeric_Value: 30000} (= 3.0e+004) (Short: \p{Nv=30000}) (1)
- T \p{Numeric_Value: 40000} (= 4.0e+004) (Short: \p{Nv=40000}) (1)
- T \p{Numeric_Value: 50000} (= 5.0e+004) (Short: \p{Nv=50000}) (4)
- T \p{Numeric_Value: 60000} (= 6.0e+004) (Short: \p{Nv=60000}) (1)
- T \p{Numeric_Value: 70000} (= 7.0e+004) (Short: \p{Nv=70000}) (1)
- T \p{Numeric_Value: 80000} (= 8.0e+004) (Short: \p{Nv=80000}) (1)
- T \p{Numeric_Value: 90000} (= 9.0e+004) (Short: \p{Nv=90000}) (1)
- T \p{Numeric_Value: 100000} (= 1.0e+005) (Short: \p{Nv=100000}) (1)
- T \p{Numeric_Value: 100000000} (= 1.0e+008) (Short: \p{Nv=
- 100000000}) (2)
- T \p{Numeric_Value: 1000000000000} (= 1.0e+012) (Short: \p{Nv=
- 1000000000000}) (1)
- \p{Numeric_Value: NaN} (Short: \p{Nv=NaN}) (1_112_887)
- \p{Nv: *} \p{Numeric_Value: *}
- X \p{OCR} \p{Optical_Character_Recognition} (=
- \p{Block=Optical_Character_Recognition})
- (32)
- \p{Ogam} \p{Ogham} (= \p{Script=Ogham}) (NOT
- \p{Block=Ogham}) (29)
- \p{Ogham} \p{Script=Ogham} (Short: \p{Ogam}; NOT
- \p{Block=Ogham}) (29)
- \p{Ol_Chiki} \p{Script=Ol_Chiki} (Short: \p{Olck}) (48)
- \p{Olck} \p{Ol_Chiki} (= \p{Script=Ol_Chiki}) (48)
- \p{Old_Italic} \p{Script=Old_Italic} (Short: \p{Ital};
- NOT \p{Block=Old_Italic}) (35)
- \p{Old_Persian} \p{Script=Old_Persian} (Short: \p{Xpeo};
- NOT \p{Block=Old_Persian}) (50)
- \p{Old_South_Arabian} \p{Script=Old_South_Arabian} (Short:
- \p{Sarb}) (32)
- \p{Old_Turkic} \p{Script=Old_Turkic} (Short: \p{Orkh};
- NOT \p{Block=Old_Turkic}) (73)
- \p{Open_Punctuation} \p{General_Category=Open_Punctuation}
- (Short: \p{Ps}) (72)
- X \p{Optical_Character_Recognition} \p{Block=
- Optical_Character_Recognition} (Short:
- \p{InOCR}) (32)
- \p{Oriya} \p{Script=Oriya} (Short: \p{Orya}; NOT
- \p{Block=Oriya}) (90)
- \p{Orkh} \p{Old_Turkic} (= \p{Script=Old_Turkic})
- (NOT \p{Block=Old_Turkic}) (73)
- \p{Orya} \p{Oriya} (= \p{Script=Oriya}) (NOT
- \p{Block=Oriya}) (90)
- \p{Osma} \p{Osmanya} (= \p{Script=Osmanya}) (NOT
- \p{Block=Osmanya}) (40)
- \p{Osmanya} \p{Script=Osmanya} (Short: \p{Osma}; NOT
- \p{Block=Osmanya}) (40)
- \p{Other} \p{General_Category=Other} (Short: \p{C})
- (1_004_135)
- \p{Other_Letter} \p{General_Category=Other_Letter} (Short:
- \p{Lo}) (97_553)
- \p{Other_Number} \p{General_Category=Other_Number} (Short:
- \p{No}) (464)
- \p{Other_Punctuation} \p{General_Category=Other_Punctuation}
- (Short: \p{Po}) (434)
- \p{Other_Symbol} \p{General_Category=Other_Symbol} (Short:
- \p{So}) (4404)
- \p{P} \p{Punct} (= \p{General_Category=
- Punctuation}) (NOT
- \p{General_Punctuation}) (632)
- \p{Paragraph_Separator} \p{General_Category=Paragraph_Separator}
- (Short: \p{Zp}) (1)
- \p{Pat_Syn} \p{Pattern_Syntax} (= \p{Pattern_Syntax=
- Y}) (2760)
- \p{Pat_Syn: *} \p{Pattern_Syntax: *}
- \p{Pat_WS} \p{Pattern_White_Space} (=
- \p{Pattern_White_Space=Y}) (11)
- \p{Pat_WS: *} \p{Pattern_White_Space: *}
- \p{Pattern_Syntax} \p{Pattern_Syntax=Y} (Short: \p{PatSyn})
- (2760)
- \p{Pattern_Syntax: N*} (Short: \p{PatSyn=N}, \P{PatSyn})
- (1_111_352)
- \p{Pattern_Syntax: Y*} (Short: \p{PatSyn=Y}, \p{PatSyn}) (2760)
- \p{Pattern_White_Space} \p{Pattern_White_Space=Y} (Short:
- \p{PatWS}) (11)
- \p{Pattern_White_Space: N*} (Short: \p{PatWS=N}, \P{PatWS})
- (1_114_101)
- \p{Pattern_White_Space: Y*} (Short: \p{PatWS=Y}, \p{PatWS}) (11)
- \p{Pc} \p{Connector_Punctuation} (=
- \p{General_Category=
- Connector_Punctuation}) (10)
- \p{Pd} \p{Dash_Punctuation} (=
- \p{General_Category=Dash_Punctuation})
- (23)
- \p{Pe} \p{Close_Punctuation} (=
- \p{General_Category=Close_Punctuation})
- (71)
- \p{PerlSpace} \s, restricted to ASCII = [ \f\n\r\t] (5)
- \p{PerlWord} \w, restricted to ASCII = [A-Za-z0-9_] (63)
- \p{Pf} \p{Final_Punctuation} (=
- \p{General_Category=Final_Punctuation})
- (10)
- \p{Phag} \p{Phags_Pa} (= \p{Script=Phags_Pa}) (NOT
- \p{Block=Phags_Pa}) (56)
- \p{Phags_Pa} \p{Script=Phags_Pa} (Short: \p{Phag}; NOT
- \p{Block=Phags_Pa}) (56)
- X \p{Phaistos} \p{Phaistos_Disc} (= \p{Block=
- Phaistos_Disc}) (48)
- X \p{Phaistos_Disc} \p{Block=Phaistos_Disc} (Short:
- \p{InPhaistos}) (48)
- \p{Phli} \p{Inscriptional_Pahlavi} (= \p{Script=
- Inscriptional_Pahlavi}) (NOT \p{Block=
- Inscriptional_Pahlavi}) (27)
- \p{Phnx} \p{Phoenician} (= \p{Script=Phoenician})
- (NOT \p{Block=Phoenician}) (29)
- \p{Phoenician} \p{Script=Phoenician} (Short: \p{Phnx};
- NOT \p{Block=Phoenician}) (29)
- X \p{Phonetic_Ext} \p{Phonetic_Extensions} (= \p{Block=
- Phonetic_Extensions}) (128)
- X \p{Phonetic_Ext_Sup} \p{Phonetic_Extensions_Supplement} (=
- \p{Block=
- Phonetic_Extensions_Supplement}) (64)
- X \p{Phonetic_Extensions} \p{Block=Phonetic_Extensions} (Short:
- \p{InPhoneticExt}) (128)
- X \p{Phonetic_Extensions_Supplement} \p{Block=
- Phonetic_Extensions_Supplement} (Short:
- \p{InPhoneticExtSup}) (64)
- \p{Pi} \p{Initial_Punctuation} (=
- \p{General_Category=
- Initial_Punctuation}) (12)
- X \p{Playing_Cards} \p{Block=Playing_Cards} (96)
- \p{Plrd} \p{Miao} (= \p{Script=Miao}) (NOT
- \p{Block=Miao}) (133)
- \p{Po} \p{Other_Punctuation} (=
- \p{General_Category=Other_Punctuation})
- (434)
- \p{PosixAlnum} [A-Za-z0-9] (62)
- \p{PosixAlpha} [A-Za-z] (52)
- \p{PosixBlank} \t and ' ' (2)
- \p{PosixCntrl} ASCII control characters: NUL, SOH, STX,
- ETX, EOT, ENQ, ACK, BEL, BS, HT, LF, VT,
- FF, CR, SO, SI, DLE, DC1, DC2, DC3, DC4,
- NAK, SYN, ETB, CAN, EOM, SUB, ESC, FS,
- GS, RS, US, and DEL (33)
- \p{PosixDigit} [0-9] (10)
- \p{PosixGraph} [-!"#$%&'()*+,./:;<>?@[\\]^_`{|}~0-9A-Za-
- z] (94)
- \p{PosixLower} [a-z] (/i= PosixAlpha) (26)
- \p{PosixPrint} [- 0-9A-Za-
- z!"#$%&'()*+,./:;<>?@[\\]^_`{|}~] (95)
- \p{PosixPunct} [-!"#$%&'()*+,./:;<>?@[\\]^_`{|}~] (32)
- \p{PosixSpace} \t, \n, \cK, \f, \r, and ' '. (\cK is
- vertical tab) (6)
- \p{PosixUpper} [A-Z] (/i= PosixAlpha) (26)
- \p{PosixWord} \p{PerlWord} (63)
- \p{PosixXDigit} \p{ASCII_Hex_Digit=Y} [0-9A-Fa-f] (Short:
- \p{AHex}) (22)
- T \p{Present_In: 1.1} \p{Age=V1_1} (Short: \p{In=1.1}) (Perl
- extension) (33_979)
- T \p{Present_In: 2.0} Code point's usage introduced in version
- 2.0 or earlier (Short: \p{In=2.0}) (Perl
- extension) (178_500)
- T \p{Present_In: 2.1} Code point's usage introduced in version
- 2.1 or earlier (Short: \p{In=2.1}) (Perl
- extension) (178_502)
- T \p{Present_In: 3.0} Code point's usage introduced in version
- 3.0 or earlier (Short: \p{In=3.0}) (Perl
- extension) (188_809)
- T \p{Present_In: 3.1} Code point's usage introduced in version
- 3.1 or earlier (Short: \p{In=3.1}) (Perl
- extension) (233_787)
- T \p{Present_In: 3.2} Code point's usage introduced in version
- 3.2 or earlier (Short: \p{In=3.2}) (Perl
- extension) (234_803)
- T \p{Present_In: 4.0} Code point's usage introduced in version
- 4.0 or earlier (Short: \p{In=4.0}) (Perl
- extension) (236_029)
- T \p{Present_In: 4.1} Code point's usage introduced in version
- 4.1 or earlier (Short: \p{In=4.1}) (Perl
- extension) (237_302)
- T \p{Present_In: 5.0} Code point's usage introduced in version
- 5.0 or earlier (Short: \p{In=5.0}) (Perl
- extension) (238_671)
- T \p{Present_In: 5.1} Code point's usage introduced in version
- 5.1 or earlier (Short: \p{In=5.1}) (Perl
- extension) (240_295)
- T \p{Present_In: 5.2} Code point's usage introduced in version
- 5.2 or earlier (Short: \p{In=5.2}) (Perl
- extension) (246_943)
- T \p{Present_In: 6.0} Code point's usage introduced in version
- 6.0 or earlier (Short: \p{In=6.0}) (Perl
- extension) (249_031)
- T \p{Present_In: 6.1} Code point's usage introduced in version
- 6.1 or earlier (Short: \p{In=6.1}) (Perl
- extension) (249_763)
- \p{Present_In: Unassigned} \p{Age=Unassigned} (Short: \p{In=
- Unassigned}) (Perl extension) (864_349)
- \p{Print} Characters that are graphical plus space
- characters (but no controls) (247_582)
- \p{Private_Use} \p{General_Category=Private_Use} (Short:
- \p{Co}; NOT \p{Private_Use_Area})
- (137_468)
- X \p{Private_Use_Area} \p{Block=Private_Use_Area} (Short:
- \p{InPUA}) (6400)
- \p{Prti} \p{Inscriptional_Parthian} (= \p{Script=
- Inscriptional_Parthian}) (NOT \p{Block=
- Inscriptional_Parthian}) (30)
- \p{Ps} \p{Open_Punctuation} (=
- \p{General_Category=Open_Punctuation})
- (72)
- X \p{PUA} \p{Private_Use_Area} (= \p{Block=
- Private_Use_Area}) (6400)
- \p{Punct} \p{General_Category=Punctuation} (Short:
- \p{P}; NOT \p{General_Punctuation}) (632)
- \p{Punctuation} \p{Punct} (= \p{General_Category=
- Punctuation}) (NOT
- \p{General_Punctuation}) (632)
- \p{Qaac} \p{Coptic} (= \p{Script=Coptic}) (NOT
- \p{Block=Coptic}) (137)
- \p{Qaai} \p{Inherited} (= \p{Script=Inherited})
- (524)
- \p{QMark} \p{Quotation_Mark} (= \p{Quotation_Mark=
- Y}) (29)
- \p{QMark: *} \p{Quotation_Mark: *}
- \p{Quotation_Mark} \p{Quotation_Mark=Y} (Short: \p{QMark})
- (29)
- \p{Quotation_Mark: N*} (Short: \p{QMark=N}, \P{QMark}) (1_114_083)
- \p{Quotation_Mark: Y*} (Short: \p{QMark=Y}, \p{QMark}) (29)
- \p{Radical} \p{Radical=Y} (329)
- \p{Radical: N*} (Single: \P{Radical}) (1_113_783)
- \p{Radical: Y*} (Single: \p{Radical}) (329)
- \p{Rejang} \p{Script=Rejang} (Short: \p{Rjng}; NOT
- \p{Block=Rejang}) (37)
- \p{Rjng} \p{Rejang} (= \p{Script=Rejang}) (NOT
- \p{Block=Rejang}) (37)
- X \p{Rumi} \p{Rumi_Numeral_Symbols} (= \p{Block=
- Rumi_Numeral_Symbols}) (32)
- X \p{Rumi_Numeral_Symbols} \p{Block=Rumi_Numeral_Symbols} (Short:
- \p{InRumi}) (32)
- \p{Runic} \p{Script=Runic} (Short: \p{Runr}; NOT
- \p{Block=Runic}) (78)
- \p{Runr} \p{Runic} (= \p{Script=Runic}) (NOT
- \p{Block=Runic}) (78)
- \p{S} \p{Symbol} (= \p{General_Category=Symbol})
- (5519)
- \p{Samaritan} \p{Script=Samaritan} (Short: \p{Samr}; NOT
- \p{Block=Samaritan}) (61)
- \p{Samr} \p{Samaritan} (= \p{Script=Samaritan})
- (NOT \p{Block=Samaritan}) (61)
- \p{Sarb} \p{Old_South_Arabian} (= \p{Script=
- Old_South_Arabian}) (32)
- \p{Saur} \p{Saurashtra} (= \p{Script=Saurashtra})
- (NOT \p{Block=Saurashtra}) (81)
- \p{Saurashtra} \p{Script=Saurashtra} (Short: \p{Saur};
- NOT \p{Block=Saurashtra}) (81)
- \p{SB: *} \p{Sentence_Break: *}
- \p{Sc} \p{Currency_Symbol} (=
- \p{General_Category=Currency_Symbol})
- (48)
- \p{Sc: *} \p{Script: *}
- \p{Script: Arab} \p{Script=Arabic} (1234)
- \p{Script: Arabic} (Short: \p{Sc=Arab}, \p{Arab}) (1234)
- \p{Script: Armenian} (Short: \p{Sc=Armn}, \p{Armn}) (91)
- \p{Script: Armi} \p{Script=Imperial_Aramaic} (31)
- \p{Script: Armn} \p{Script=Armenian} (91)
- \p{Script: Avestan} (Short: \p{Sc=Avst}, \p{Avst}) (61)
- \p{Script: Avst} \p{Script=Avestan} (61)
- \p{Script: Bali} \p{Script=Balinese} (121)
- \p{Script: Balinese} (Short: \p{Sc=Bali}, \p{Bali}) (121)
- \p{Script: Bamu} \p{Script=Bamum} (657)
- \p{Script: Bamum} (Short: \p{Sc=Bamu}, \p{Bamu}) (657)
- \p{Script: Batak} (Short: \p{Sc=Batk}, \p{Batk}) (56)
- \p{Script: Batk} \p{Script=Batak} (56)
- \p{Script: Beng} \p{Script=Bengali} (92)
- \p{Script: Bengali} (Short: \p{Sc=Beng}, \p{Beng}) (92)
- \p{Script: Bopo} \p{Script=Bopomofo} (70)
- \p{Script: Bopomofo} (Short: \p{Sc=Bopo}, \p{Bopo}) (70)
- \p{Script: Brah} \p{Script=Brahmi} (108)
- \p{Script: Brahmi} (Short: \p{Sc=Brah}, \p{Brah}) (108)
- \p{Script: Brai} \p{Script=Braille} (256)
- \p{Script: Braille} (Short: \p{Sc=Brai}, \p{Brai}) (256)
- \p{Script: Bugi} \p{Script=Buginese} (30)
- \p{Script: Buginese} (Short: \p{Sc=Bugi}, \p{Bugi}) (30)
- \p{Script: Buhd} \p{Script=Buhid} (20)
- \p{Script: Buhid} (Short: \p{Sc=Buhd}, \p{Buhd}) (20)
- \p{Script: Cakm} \p{Script=Chakma} (67)
- \p{Script: Canadian_Aboriginal} (Short: \p{Sc=Cans}, \p{Cans})
- (710)
- \p{Script: Cans} \p{Script=Canadian_Aboriginal} (710)
- \p{Script: Cari} \p{Script=Carian} (49)
- \p{Script: Carian} (Short: \p{Sc=Cari}, \p{Cari}) (49)
- \p{Script: Chakma} (Short: \p{Sc=Cakm}, \p{Cakm}) (67)
- \p{Script: Cham} (Short: \p{Sc=Cham}, \p{Cham}) (83)
- \p{Script: Cher} \p{Script=Cherokee} (85)
- \p{Script: Cherokee} (Short: \p{Sc=Cher}, \p{Cher}) (85)
- \p{Script: Common} (Short: \p{Sc=Zyyy}, \p{Zyyy}) (6412)
- \p{Script: Copt} \p{Script=Coptic} (137)
- \p{Script: Coptic} (Short: \p{Sc=Copt}, \p{Copt}) (137)
- \p{Script: Cprt} \p{Script=Cypriot} (55)
- \p{Script: Cuneiform} (Short: \p{Sc=Xsux}, \p{Xsux}) (982)
- \p{Script: Cypriot} (Short: \p{Sc=Cprt}, \p{Cprt}) (55)
- \p{Script: Cyrillic} (Short: \p{Sc=Cyrl}, \p{Cyrl}) (417)
- \p{Script: Cyrl} \p{Script=Cyrillic} (417)
- \p{Script: Deseret} (Short: \p{Sc=Dsrt}, \p{Dsrt}) (80)
- \p{Script: Deva} \p{Script=Devanagari} (151)
- \p{Script: Devanagari} (Short: \p{Sc=Deva}, \p{Deva}) (151)
- \p{Script: Dsrt} \p{Script=Deseret} (80)
- \p{Script: Egyp} \p{Script=Egyptian_Hieroglyphs} (1071)
- \p{Script: Egyptian_Hieroglyphs} (Short: \p{Sc=Egyp}, \p{Egyp})
- (1071)
- \p{Script: Ethi} \p{Script=Ethiopic} (495)
- \p{Script: Ethiopic} (Short: \p{Sc=Ethi}, \p{Ethi}) (495)
- \p{Script: Geor} \p{Script=Georgian} (127)
- \p{Script: Georgian} (Short: \p{Sc=Geor}, \p{Geor}) (127)
- \p{Script: Glag} \p{Script=Glagolitic} (94)
- \p{Script: Glagolitic} (Short: \p{Sc=Glag}, \p{Glag}) (94)
- \p{Script: Goth} \p{Script=Gothic} (27)
- \p{Script: Gothic} (Short: \p{Sc=Goth}, \p{Goth}) (27)
- \p{Script: Greek} (Short: \p{Sc=Grek}, \p{Grek}) (511)
- \p{Script: Grek} \p{Script=Greek} (511)
- \p{Script: Gujarati} (Short: \p{Sc=Gujr}, \p{Gujr}) (84)
- \p{Script: Gujr} \p{Script=Gujarati} (84)
- \p{Script: Gurmukhi} (Short: \p{Sc=Guru}, \p{Guru}) (79)
- \p{Script: Guru} \p{Script=Gurmukhi} (79)
- \p{Script: Han} (Short: \p{Sc=Han}, \p{Han}) (75_963)
- \p{Script: Hang} \p{Script=Hangul} (11_739)
- \p{Script: Hangul} (Short: \p{Sc=Hang}, \p{Hang}) (11_739)
- \p{Script: Hani} \p{Script=Han} (75_963)
- \p{Script: Hano} \p{Script=Hanunoo} (21)
- \p{Script: Hanunoo} (Short: \p{Sc=Hano}, \p{Hano}) (21)
- \p{Script: Hebr} \p{Script=Hebrew} (133)
- \p{Script: Hebrew} (Short: \p{Sc=Hebr}, \p{Hebr}) (133)
- \p{Script: Hira} \p{Script=Hiragana} (91)
- \p{Script: Hiragana} (Short: \p{Sc=Hira}, \p{Hira}) (91)
- \p{Script: Imperial_Aramaic} (Short: \p{Sc=Armi}, \p{Armi}) (31)
- \p{Script: Inherited} (Short: \p{Sc=Zinh}, \p{Zinh}) (524)
- \p{Script: Inscriptional_Pahlavi} (Short: \p{Sc=Phli}, \p{Phli})
- (27)
- \p{Script: Inscriptional_Parthian} (Short: \p{Sc=Prti}, \p{Prti})
- (30)
- \p{Script: Ital} \p{Script=Old_Italic} (35)
- \p{Script: Java} \p{Script=Javanese} (91)
- \p{Script: Javanese} (Short: \p{Sc=Java}, \p{Java}) (91)
- \p{Script: Kaithi} (Short: \p{Sc=Kthi}, \p{Kthi}) (66)
- \p{Script: Kali} \p{Script=Kayah_Li} (48)
- \p{Script: Kana} \p{Script=Katakana} (300)
- \p{Script: Kannada} (Short: \p{Sc=Knda}, \p{Knda}) (86)
- \p{Script: Katakana} (Short: \p{Sc=Kana}, \p{Kana}) (300)
- \p{Script: Kayah_Li} (Short: \p{Sc=Kali}, \p{Kali}) (48)
- \p{Script: Khar} \p{Script=Kharoshthi} (65)
- \p{Script: Kharoshthi} (Short: \p{Sc=Khar}, \p{Khar}) (65)
- \p{Script: Khmer} (Short: \p{Sc=Khmr}, \p{Khmr}) (146)
- \p{Script: Khmr} \p{Script=Khmer} (146)
- \p{Script: Knda} \p{Script=Kannada} (86)
- \p{Script: Kthi} \p{Script=Kaithi} (66)
- \p{Script: Lana} \p{Script=Tai_Tham} (127)
- \p{Script: Lao} (Short: \p{Sc=Lao}, \p{Lao}) (67)
- \p{Script: Laoo} \p{Script=Lao} (67)
- \p{Script: Latin} (Short: \p{Sc=Latn}, \p{Latn}) (1272)
- \p{Script: Latn} \p{Script=Latin} (1272)
- \p{Script: Lepc} \p{Script=Lepcha} (74)
- \p{Script: Lepcha} (Short: \p{Sc=Lepc}, \p{Lepc}) (74)
- \p{Script: Limb} \p{Script=Limbu} (66)
- \p{Script: Limbu} (Short: \p{Sc=Limb}, \p{Limb}) (66)
- \p{Script: Linb} \p{Script=Linear_B} (211)
- \p{Script: Linear_B} (Short: \p{Sc=Linb}, \p{Linb}) (211)
- \p{Script: Lisu} (Short: \p{Sc=Lisu}, \p{Lisu}) (48)
- \p{Script: Lyci} \p{Script=Lycian} (29)
- \p{Script: Lycian} (Short: \p{Sc=Lyci}, \p{Lyci}) (29)
- \p{Script: Lydi} \p{Script=Lydian} (27)
- \p{Script: Lydian} (Short: \p{Sc=Lydi}, \p{Lydi}) (27)
- \p{Script: Malayalam} (Short: \p{Sc=Mlym}, \p{Mlym}) (98)
- \p{Script: Mand} \p{Script=Mandaic} (29)
- \p{Script: Mandaic} (Short: \p{Sc=Mand}, \p{Mand}) (29)
- \p{Script: Meetei_Mayek} (Short: \p{Sc=Mtei}, \p{Mtei}) (79)
- \p{Script: Merc} \p{Script=Meroitic_Cursive} (26)
- \p{Script: Mero} \p{Script=Meroitic_Hieroglyphs} (32)
- \p{Script: Meroitic_Cursive} (Short: \p{Sc=Merc}, \p{Merc}) (26)
- \p{Script: Meroitic_Hieroglyphs} (Short: \p{Sc=Mero}, \p{Mero})
- (32)
- \p{Script: Miao} (Short: \p{Sc=Miao}, \p{Miao}) (133)
- \p{Script: Mlym} \p{Script=Malayalam} (98)
- \p{Script: Mong} \p{Script=Mongolian} (153)
- \p{Script: Mongolian} (Short: \p{Sc=Mong}, \p{Mong}) (153)
- \p{Script: Mtei} \p{Script=Meetei_Mayek} (79)
- \p{Script: Myanmar} (Short: \p{Sc=Mymr}, \p{Mymr}) (188)
- \p{Script: Mymr} \p{Script=Myanmar} (188)
- \p{Script: New_Tai_Lue} (Short: \p{Sc=Talu}, \p{Talu}) (83)
- \p{Script: Nko} (Short: \p{Sc=Nko}, \p{Nko}) (59)
- \p{Script: Nkoo} \p{Script=Nko} (59)
- \p{Script: Ogam} \p{Script=Ogham} (29)
- \p{Script: Ogham} (Short: \p{Sc=Ogam}, \p{Ogam}) (29)
- \p{Script: Ol_Chiki} (Short: \p{Sc=Olck}, \p{Olck}) (48)
- \p{Script: Olck} \p{Script=Ol_Chiki} (48)
- \p{Script: Old_Italic} (Short: \p{Sc=Ital}, \p{Ital}) (35)
- \p{Script: Old_Persian} (Short: \p{Sc=Xpeo}, \p{Xpeo}) (50)
- \p{Script: Old_South_Arabian} (Short: \p{Sc=Sarb}, \p{Sarb}) (32)
- \p{Script: Old_Turkic} (Short: \p{Sc=Orkh}, \p{Orkh}) (73)
- \p{Script: Oriya} (Short: \p{Sc=Orya}, \p{Orya}) (90)
- \p{Script: Orkh} \p{Script=Old_Turkic} (73)
- \p{Script: Orya} \p{Script=Oriya} (90)
- \p{Script: Osma} \p{Script=Osmanya} (40)
- \p{Script: Osmanya} (Short: \p{Sc=Osma}, \p{Osma}) (40)
- \p{Script: Phag} \p{Script=Phags_Pa} (56)
- \p{Script: Phags_Pa} (Short: \p{Sc=Phag}, \p{Phag}) (56)
- \p{Script: Phli} \p{Script=Inscriptional_Pahlavi} (27)
- \p{Script: Phnx} \p{Script=Phoenician} (29)
- \p{Script: Phoenician} (Short: \p{Sc=Phnx}, \p{Phnx}) (29)
- \p{Script: Plrd} \p{Script=Miao} (133)
- \p{Script: Prti} \p{Script=Inscriptional_Parthian} (30)
- \p{Script: Qaac} \p{Script=Coptic} (137)
- \p{Script: Qaai} \p{Script=Inherited} (524)
- \p{Script: Rejang} (Short: \p{Sc=Rjng}, \p{Rjng}) (37)
- \p{Script: Rjng} \p{Script=Rejang} (37)
- \p{Script: Runic} (Short: \p{Sc=Runr}, \p{Runr}) (78)
- \p{Script: Runr} \p{Script=Runic} (78)
- \p{Script: Samaritan} (Short: \p{Sc=Samr}, \p{Samr}) (61)
- \p{Script: Samr} \p{Script=Samaritan} (61)
- \p{Script: Sarb} \p{Script=Old_South_Arabian} (32)
- \p{Script: Saur} \p{Script=Saurashtra} (81)
- \p{Script: Saurashtra} (Short: \p{Sc=Saur}, \p{Saur}) (81)
- \p{Script: Sharada} (Short: \p{Sc=Shrd}, \p{Shrd}) (83)
- \p{Script: Shavian} (Short: \p{Sc=Shaw}, \p{Shaw}) (48)
- \p{Script: Shaw} \p{Script=Shavian} (48)
- \p{Script: Shrd} \p{Script=Sharada} (83)
- \p{Script: Sinh} \p{Script=Sinhala} (80)
- \p{Script: Sinhala} (Short: \p{Sc=Sinh}, \p{Sinh}) (80)
- \p{Script: Sora} \p{Script=Sora_Sompeng} (35)
- \p{Script: Sora_Sompeng} (Short: \p{Sc=Sora}, \p{Sora}) (35)
- \p{Script: Sund} \p{Script=Sundanese} (72)
- \p{Script: Sundanese} (Short: \p{Sc=Sund}, \p{Sund}) (72)
- \p{Script: Sylo} \p{Script=Syloti_Nagri} (44)
- \p{Script: Syloti_Nagri} (Short: \p{Sc=Sylo}, \p{Sylo}) (44)
- \p{Script: Syrc} \p{Script=Syriac} (77)
- \p{Script: Syriac} (Short: \p{Sc=Syrc}, \p{Syrc}) (77)
- \p{Script: Tagalog} (Short: \p{Sc=Tglg}, \p{Tglg}) (20)
- \p{Script: Tagb} \p{Script=Tagbanwa} (18)
- \p{Script: Tagbanwa} (Short: \p{Sc=Tagb}, \p{Tagb}) (18)
- \p{Script: Tai_Le} (Short: \p{Sc=Tale}, \p{Tale}) (35)
- \p{Script: Tai_Tham} (Short: \p{Sc=Lana}, \p{Lana}) (127)
- \p{Script: Tai_Viet} (Short: \p{Sc=Tavt}, \p{Tavt}) (72)
- \p{Script: Takr} \p{Script=Takri} (66)
- \p{Script: Takri} (Short: \p{Sc=Takr}, \p{Takr}) (66)
- \p{Script: Tale} \p{Script=Tai_Le} (35)
- \p{Script: Talu} \p{Script=New_Tai_Lue} (83)
- \p{Script: Tamil} (Short: \p{Sc=Taml}, \p{Taml}) (72)
- \p{Script: Taml} \p{Script=Tamil} (72)
- \p{Script: Tavt} \p{Script=Tai_Viet} (72)
- \p{Script: Telu} \p{Script=Telugu} (93)
- \p{Script: Telugu} (Short: \p{Sc=Telu}, \p{Telu}) (93)
- \p{Script: Tfng} \p{Script=Tifinagh} (59)
- \p{Script: Tglg} \p{Script=Tagalog} (20)
- \p{Script: Thaa} \p{Script=Thaana} (50)
- \p{Script: Thaana} (Short: \p{Sc=Thaa}, \p{Thaa}) (50)
- \p{Script: Thai} (Short: \p{Sc=Thai}, \p{Thai}) (86)
- \p{Script: Tibetan} (Short: \p{Sc=Tibt}, \p{Tibt}) (207)
- \p{Script: Tibt} \p{Script=Tibetan} (207)
- \p{Script: Tifinagh} (Short: \p{Sc=Tfng}, \p{Tfng}) (59)
- \p{Script: Ugar} \p{Script=Ugaritic} (31)
- \p{Script: Ugaritic} (Short: \p{Sc=Ugar}, \p{Ugar}) (31)
- \p{Script: Unknown} (Short: \p{Sc=Zzzz}, \p{Zzzz}) (1_003_931)
- \p{Script: Vai} (Short: \p{Sc=Vai}, \p{Vai}) (300)
- \p{Script: Vaii} \p{Script=Vai} (300)
- \p{Script: Xpeo} \p{Script=Old_Persian} (50)
- \p{Script: Xsux} \p{Script=Cuneiform} (982)
- \p{Script: Yi} (Short: \p{Sc=Yi}, \p{Yi}) (1220)
- \p{Script: Yiii} \p{Script=Yi} (1220)
- \p{Script: Zinh} \p{Script=Inherited} (524)
- \p{Script: Zyyy} \p{Script=Common} (6412)
- \p{Script: Zzzz} \p{Script=Unknown} (1_003_931)
- \p{Script_Extensions: Arab} \p{Script_Extensions=Arabic} (1261)
- \p{Script_Extensions: Arabic} (Short: \p{Scx=Arab}) (1261)
- \p{Script_Extensions: Armenian} (Short: \p{Scx=Armn}) (92)
- \p{Script_Extensions: Armi} \p{Script_Extensions=Imperial_Aramaic}
- (31)
- \p{Script_Extensions: Armn} \p{Script_Extensions=Armenian} (92)
- \p{Script_Extensions: Avestan} (Short: \p{Scx=Avst}) (61)
- \p{Script_Extensions: Avst} \p{Script_Extensions=Avestan} (61)
- \p{Script_Extensions: Bali} \p{Script_Extensions=Balinese} (121)
- \p{Script_Extensions: Balinese} (Short: \p{Scx=Bali}) (121)
- \p{Script_Extensions: Bamu} \p{Script_Extensions=Bamum} (657)
- \p{Script_Extensions: Bamum} (Short: \p{Scx=Bamu}) (657)
- \p{Script_Extensions: Batak} (Short: \p{Scx=Batk}) (56)
- \p{Script_Extensions: Batk} \p{Script_Extensions=Batak} (56)
- \p{Script_Extensions: Beng} \p{Script_Extensions=Bengali} (94)
- \p{Script_Extensions: Bengali} (Short: \p{Scx=Beng}) (94)
- \p{Script_Extensions: Bopo} \p{Script_Extensions=Bopomofo} (306)
- \p{Script_Extensions: Bopomofo} (Short: \p{Scx=Bopo}) (306)
- \p{Script_Extensions: Brah} \p{Script_Extensions=Brahmi} (108)
- \p{Script_Extensions: Brahmi} (Short: \p{Scx=Brah}) (108)
- \p{Script_Extensions: Brai} \p{Script_Extensions=Braille} (256)
- \p{Script_Extensions: Braille} (Short: \p{Scx=Brai}) (256)
- \p{Script_Extensions: Bugi} \p{Script_Extensions=Buginese} (30)
- \p{Script_Extensions: Buginese} (Short: \p{Scx=Bugi}) (30)
- \p{Script_Extensions: Buhd} \p{Script_Extensions=Buhid} (22)
- \p{Script_Extensions: Buhid} (Short: \p{Scx=Buhd}) (22)
- \p{Script_Extensions: Cakm} \p{Script_Extensions=Chakma} (67)
- \p{Script_Extensions: Canadian_Aboriginal} (Short: \p{Scx=Cans})
- (710)
- \p{Script_Extensions: Cans} \p{Script_Extensions=
- Canadian_Aboriginal} (710)
- \p{Script_Extensions: Cari} \p{Script_Extensions=Carian} (49)
- \p{Script_Extensions: Carian} (Short: \p{Scx=Cari}) (49)
- \p{Script_Extensions: Chakma} (Short: \p{Scx=Cakm}) (67)
- \p{Script_Extensions: Cham} (Short: \p{Scx=Cham}) (83)
- \p{Script_Extensions: Cher} \p{Script_Extensions=Cherokee} (85)
- \p{Script_Extensions: Cherokee} (Short: \p{Scx=Cher}) (85)
- \p{Script_Extensions: Common} (Short: \p{Scx=Zyyy}) (6059)
- \p{Script_Extensions: Copt} \p{Script_Extensions=Coptic} (137)
- \p{Script_Extensions: Coptic} (Short: \p{Scx=Copt}) (137)
- \p{Script_Extensions: Cprt} \p{Script_Extensions=Cypriot} (112)
- \p{Script_Extensions: Cuneiform} (Short: \p{Scx=Xsux}) (982)
- \p{Script_Extensions: Cypriot} (Short: \p{Scx=Cprt}) (112)
- \p{Script_Extensions: Cyrillic} (Short: \p{Scx=Cyrl}) (417)
- \p{Script_Extensions: Cyrl} \p{Script_Extensions=Cyrillic} (417)
- \p{Script_Extensions: Deseret} (Short: \p{Scx=Dsrt}) (80)
- \p{Script_Extensions: Deva} \p{Script_Extensions=Devanagari} (163)
- \p{Script_Extensions: Devanagari} (Short: \p{Scx=Deva}) (163)
- \p{Script_Extensions: Dsrt} \p{Script_Extensions=Deseret} (80)
- \p{Script_Extensions: Egyp} \p{Script_Extensions=
- Egyptian_Hieroglyphs} (1071)
- \p{Script_Extensions: Egyptian_Hieroglyphs} (Short: \p{Scx=Egyp})
- (1071)
- \p{Script_Extensions: Ethi} \p{Script_Extensions=Ethiopic} (495)
- \p{Script_Extensions: Ethiopic} (Short: \p{Scx=Ethi}) (495)
- \p{Script_Extensions: Geor} \p{Script_Extensions=Georgian} (128)
- \p{Script_Extensions: Georgian} (Short: \p{Scx=Geor}) (128)
- \p{Script_Extensions: Glag} \p{Script_Extensions=Glagolitic} (94)
- \p{Script_Extensions: Glagolitic} (Short: \p{Scx=Glag}) (94)
- \p{Script_Extensions: Goth} \p{Script_Extensions=Gothic} (27)
- \p{Script_Extensions: Gothic} (Short: \p{Scx=Goth}) (27)
- \p{Script_Extensions: Greek} (Short: \p{Scx=Grek}) (511)
- \p{Script_Extensions: Grek} \p{Script_Extensions=Greek} (511)
- \p{Script_Extensions: Gujarati} (Short: \p{Scx=Gujr}) (94)
- \p{Script_Extensions: Gujr} \p{Script_Extensions=Gujarati} (94)
- \p{Script_Extensions: Gurmukhi} (Short: \p{Scx=Guru}) (91)
- \p{Script_Extensions: Guru} \p{Script_Extensions=Gurmukhi} (91)
- \p{Script_Extensions: Han} (Short: \p{Scx=Han}) (76_218)
- \p{Script_Extensions: Hang} \p{Script_Extensions=Hangul} (11_971)
- \p{Script_Extensions: Hangul} (Short: \p{Scx=Hang}) (11_971)
- \p{Script_Extensions: Hani} \p{Script_Extensions=Han} (76_218)
- \p{Script_Extensions: Hano} \p{Script_Extensions=Hanunoo} (23)
- \p{Script_Extensions: Hanunoo} (Short: \p{Scx=Hano}) (23)
- \p{Script_Extensions: Hebr} \p{Script_Extensions=Hebrew} (133)
- \p{Script_Extensions: Hebrew} (Short: \p{Scx=Hebr}) (133)
- \p{Script_Extensions: Hira} \p{Script_Extensions=Hiragana} (356)
- \p{Script_Extensions: Hiragana} (Short: \p{Scx=Hira}) (356)
- \p{Script_Extensions: Imperial_Aramaic} (Short: \p{Scx=Armi}) (31)
- \p{Script_Extensions: Inherited} (Short: \p{Scx=Zinh}) (506)
- \p{Script_Extensions: Inscriptional_Pahlavi} (Short: \p{Scx=Phli})
- (27)
- \p{Script_Extensions: Inscriptional_Parthian} (Short: \p{Scx=
- Prti}) (30)
- \p{Script_Extensions: Ital} \p{Script_Extensions=Old_Italic} (35)
- \p{Script_Extensions: Java} \p{Script_Extensions=Javanese} (91)
- \p{Script_Extensions: Javanese} (Short: \p{Scx=Java}) (91)
- \p{Script_Extensions: Kaithi} (Short: \p{Scx=Kthi}) (76)
- \p{Script_Extensions: Kali} \p{Script_Extensions=Kayah_Li} (48)
- \p{Script_Extensions: Kana} \p{Script_Extensions=Katakana} (565)
- \p{Script_Extensions: Kannada} (Short: \p{Scx=Knda}) (86)
- \p{Script_Extensions: Katakana} (Short: \p{Scx=Kana}) (565)
- \p{Script_Extensions: Kayah_Li} (Short: \p{Scx=Kali}) (48)
- \p{Script_Extensions: Khar} \p{Script_Extensions=Kharoshthi} (65)
- \p{Script_Extensions: Kharoshthi} (Short: \p{Scx=Khar}) (65)
- \p{Script_Extensions: Khmer} (Short: \p{Scx=Khmr}) (146)
- \p{Script_Extensions: Khmr} \p{Script_Extensions=Khmer} (146)
- \p{Script_Extensions: Knda} \p{Script_Extensions=Kannada} (86)
- \p{Script_Extensions: Kthi} \p{Script_Extensions=Kaithi} (76)
- \p{Script_Extensions: Lana} \p{Script_Extensions=Tai_Tham} (127)
- \p{Script_Extensions: Lao} (Short: \p{Scx=Lao}) (67)
- \p{Script_Extensions: Laoo} \p{Script_Extensions=Lao} (67)
- \p{Script_Extensions: Latin} (Short: \p{Scx=Latn}) (1272)
- \p{Script_Extensions: Latn} \p{Script_Extensions=Latin} (1272)
- \p{Script_Extensions: Lepc} \p{Script_Extensions=Lepcha} (74)
- \p{Script_Extensions: Lepcha} (Short: \p{Scx=Lepc}) (74)
- \p{Script_Extensions: Limb} \p{Script_Extensions=Limbu} (66)
- \p{Script_Extensions: Limbu} (Short: \p{Scx=Limb}) (66)
- \p{Script_Extensions: Linb} \p{Script_Extensions=Linear_B} (268)
- \p{Script_Extensions: Linear_B} (Short: \p{Scx=Linb}) (268)
- \p{Script_Extensions: Lisu} (Short: \p{Scx=Lisu}) (48)
- \p{Script_Extensions: Lyci} \p{Script_Extensions=Lycian} (29)
- \p{Script_Extensions: Lycian} (Short: \p{Scx=Lyci}) (29)
- \p{Script_Extensions: Lydi} \p{Script_Extensions=Lydian} (27)
- \p{Script_Extensions: Lydian} (Short: \p{Scx=Lydi}) (27)
- \p{Script_Extensions: Malayalam} (Short: \p{Scx=Mlym}) (98)
- \p{Script_Extensions: Mand} \p{Script_Extensions=Mandaic} (30)
- \p{Script_Extensions: Mandaic} (Short: \p{Scx=Mand}) (30)
- \p{Script_Extensions: Meetei_Mayek} (Short: \p{Scx=Mtei}) (79)
- \p{Script_Extensions: Merc} \p{Script_Extensions=Meroitic_Cursive}
- (26)
- \p{Script_Extensions: Mero} \p{Script_Extensions=
- Meroitic_Hieroglyphs} (32)
- \p{Script_Extensions: Meroitic_Cursive} (Short: \p{Scx=Merc}) (26)
- \p{Script_Extensions: Meroitic_Hieroglyphs} (Short: \p{Scx=Mero})
- (32)
- \p{Script_Extensions: Miao} (Short: \p{Scx=Miao}) (133)
- \p{Script_Extensions: Mlym} \p{Script_Extensions=Malayalam} (98)
- \p{Script_Extensions: Mong} \p{Script_Extensions=Mongolian} (156)
- \p{Script_Extensions: Mongolian} (Short: \p{Scx=Mong}) (156)
- \p{Script_Extensions: Mtei} \p{Script_Extensions=Meetei_Mayek} (79)
- \p{Script_Extensions: Myanmar} (Short: \p{Scx=Mymr}) (188)
- \p{Script_Extensions: Mymr} \p{Script_Extensions=Myanmar} (188)
- \p{Script_Extensions: New_Tai_Lue} (Short: \p{Scx=Talu}) (83)
- \p{Script_Extensions: Nko} (Short: \p{Scx=Nko}) (59)
- \p{Script_Extensions: Nkoo} \p{Script_Extensions=Nko} (59)
- \p{Script_Extensions: Ogam} \p{Script_Extensions=Ogham} (29)
- \p{Script_Extensions: Ogham} (Short: \p{Scx=Ogam}) (29)
- \p{Script_Extensions: Ol_Chiki} (Short: \p{Scx=Olck}) (48)
- \p{Script_Extensions: Olck} \p{Script_Extensions=Ol_Chiki} (48)
- \p{Script_Extensions: Old_Italic} (Short: \p{Scx=Ital}) (35)
- \p{Script_Extensions: Old_Persian} (Short: \p{Scx=Xpeo}) (50)
- \p{Script_Extensions: Old_South_Arabian} (Short: \p{Scx=Sarb}) (32)
- \p{Script_Extensions: Old_Turkic} (Short: \p{Scx=Orkh}) (73)
- \p{Script_Extensions: Oriya} (Short: \p{Scx=Orya}) (92)
- \p{Script_Extensions: Orkh} \p{Script_Extensions=Old_Turkic} (73)
- \p{Script_Extensions: Orya} \p{Script_Extensions=Oriya} (92)
- \p{Script_Extensions: Osma} \p{Script_Extensions=Osmanya} (40)
- \p{Script_Extensions: Osmanya} (Short: \p{Scx=Osma}) (40)
- \p{Script_Extensions: Phag} \p{Script_Extensions=Phags_Pa} (59)
- \p{Script_Extensions: Phags_Pa} (Short: \p{Scx=Phag}) (59)
- \p{Script_Extensions: Phli} \p{Script_Extensions=
- Inscriptional_Pahlavi} (27)
- \p{Script_Extensions: Phnx} \p{Script_Extensions=Phoenician} (29)
- \p{Script_Extensions: Phoenician} (Short: \p{Scx=Phnx}) (29)
- \p{Script_Extensions: Plrd} \p{Script_Extensions=Miao} (133)
- \p{Script_Extensions: Prti} \p{Script_Extensions=
- Inscriptional_Parthian} (30)
- \p{Script_Extensions: Qaac} \p{Script_Extensions=Coptic} (137)
- \p{Script_Extensions: Qaai} \p{Script_Extensions=Inherited} (506)
- \p{Script_Extensions: Rejang} (Short: \p{Scx=Rjng}) (37)
- \p{Script_Extensions: Rjng} \p{Script_Extensions=Rejang} (37)
- \p{Script_Extensions: Runic} (Short: \p{Scx=Runr}) (78)
- \p{Script_Extensions: Runr} \p{Script_Extensions=Runic} (78)
- \p{Script_Extensions: Samaritan} (Short: \p{Scx=Samr}) (61)
- \p{Script_Extensions: Samr} \p{Script_Extensions=Samaritan} (61)
- \p{Script_Extensions: Sarb} \p{Script_Extensions=
- Old_South_Arabian} (32)
- \p{Script_Extensions: Saur} \p{Script_Extensions=Saurashtra} (81)
- \p{Script_Extensions: Saurashtra} (Short: \p{Scx=Saur}) (81)
- \p{Script_Extensions: Sharada} (Short: \p{Scx=Shrd}) (83)
- \p{Script_Extensions: Shavian} (Short: \p{Scx=Shaw}) (48)
- \p{Script_Extensions: Shaw} \p{Script_Extensions=Shavian} (48)
- \p{Script_Extensions: Shrd} \p{Script_Extensions=Sharada} (83)
- \p{Script_Extensions: Sinh} \p{Script_Extensions=Sinhala} (80)
- \p{Script_Extensions: Sinhala} (Short: \p{Scx=Sinh}) (80)
- \p{Script_Extensions: Sora} \p{Script_Extensions=Sora_Sompeng} (35)
- \p{Script_Extensions: Sora_Sompeng} (Short: \p{Scx=Sora}) (35)
- \p{Script_Extensions: Sund} \p{Script_Extensions=Sundanese} (72)
- \p{Script_Extensions: Sundanese} (Short: \p{Scx=Sund}) (72)
- \p{Script_Extensions: Sylo} \p{Script_Extensions=Syloti_Nagri} (44)
- \p{Script_Extensions: Syloti_Nagri} (Short: \p{Scx=Sylo}) (44)
- \p{Script_Extensions: Syrc} \p{Script_Extensions=Syriac} (93)
- \p{Script_Extensions: Syriac} (Short: \p{Scx=Syrc}) (93)
- \p{Script_Extensions: Tagalog} (Short: \p{Scx=Tglg}) (22)
- \p{Script_Extensions: Tagb} \p{Script_Extensions=Tagbanwa} (20)
- \p{Script_Extensions: Tagbanwa} (Short: \p{Scx=Tagb}) (20)
- \p{Script_Extensions: Tai_Le} (Short: \p{Scx=Tale}) (35)
- \p{Script_Extensions: Tai_Tham} (Short: \p{Scx=Lana}) (127)
- \p{Script_Extensions: Tai_Viet} (Short: \p{Scx=Tavt}) (72)
- \p{Script_Extensions: Takr} \p{Script_Extensions=Takri} (78)
- \p{Script_Extensions: Takri} (Short: \p{Scx=Takr}) (78)
- \p{Script_Extensions: Tale} \p{Script_Extensions=Tai_Le} (35)
- \p{Script_Extensions: Talu} \p{Script_Extensions=New_Tai_Lue} (83)
- \p{Script_Extensions: Tamil} (Short: \p{Scx=Taml}) (72)
- \p{Script_Extensions: Taml} \p{Script_Extensions=Tamil} (72)
- \p{Script_Extensions: Tavt} \p{Script_Extensions=Tai_Viet} (72)
- \p{Script_Extensions: Telu} \p{Script_Extensions=Telugu} (93)
- \p{Script_Extensions: Telugu} (Short: \p{Scx=Telu}) (93)
- \p{Script_Extensions: Tfng} \p{Script_Extensions=Tifinagh} (59)
- \p{Script_Extensions: Tglg} \p{Script_Extensions=Tagalog} (22)
- \p{Script_Extensions: Thaa} \p{Script_Extensions=Thaana} (65)
- \p{Script_Extensions: Thaana} (Short: \p{Scx=Thaa}) (65)
- \p{Script_Extensions: Thai} (Short: \p{Scx=Thai}) (86)
- \p{Script_Extensions: Tibetan} (Short: \p{Scx=Tibt}) (207)
- \p{Script_Extensions: Tibt} \p{Script_Extensions=Tibetan} (207)
- \p{Script_Extensions: Tifinagh} (Short: \p{Scx=Tfng}) (59)
- \p{Script_Extensions: Ugar} \p{Script_Extensions=Ugaritic} (31)
- \p{Script_Extensions: Ugaritic} (Short: \p{Scx=Ugar}) (31)
- \p{Script_Extensions: Unknown} (Short: \p{Scx=Zzzz}) (1_003_931)
- \p{Script_Extensions: Vai} (Short: \p{Scx=Vai}) (300)
- \p{Script_Extensions: Vaii} \p{Script_Extensions=Vai} (300)
- \p{Script_Extensions: Xpeo} \p{Script_Extensions=Old_Persian} (50)
- \p{Script_Extensions: Xsux} \p{Script_Extensions=Cuneiform} (982)
- \p{Script_Extensions: Yi} (Short: \p{Scx=Yi}) (1246)
- \p{Script_Extensions: Yiii} \p{Script_Extensions=Yi} (1246)
- \p{Script_Extensions: Zinh} \p{Script_Extensions=Inherited} (506)
- \p{Script_Extensions: Zyyy} \p{Script_Extensions=Common} (6059)
- \p{Script_Extensions: Zzzz} \p{Script_Extensions=Unknown}
- (1_003_931)
- \p{Scx: *} \p{Script_Extensions: *}
- \p{SD} \p{Soft_Dotted} (= \p{Soft_Dotted=Y}) (46)
- \p{SD: *} \p{Soft_Dotted: *}
- \p{Sentence_Break: AT} \p{Sentence_Break=ATerm} (4)
- \p{Sentence_Break: ATerm} (Short: \p{SB=AT}) (4)
- \p{Sentence_Break: CL} \p{Sentence_Break=Close} (177)
- \p{Sentence_Break: Close} (Short: \p{SB=CL}) (177)
- \p{Sentence_Break: CR} (Short: \p{SB=CR}) (1)
- \p{Sentence_Break: EX} \p{Sentence_Break=Extend} (1649)
- \p{Sentence_Break: Extend} (Short: \p{SB=EX}) (1649)
- \p{Sentence_Break: FO} \p{Sentence_Break=Format} (137)
- \p{Sentence_Break: Format} (Short: \p{SB=FO}) (137)
- \p{Sentence_Break: LE} \p{Sentence_Break=OLetter} (97_841)
- \p{Sentence_Break: LF} (Short: \p{SB=LF}) (1)
- \p{Sentence_Break: LO} \p{Sentence_Break=Lower} (1933)
- \p{Sentence_Break: Lower} (Short: \p{SB=LO}) (1933)
- \p{Sentence_Break: NU} \p{Sentence_Break=Numeric} (452)
- \p{Sentence_Break: Numeric} (Short: \p{SB=NU}) (452)
- \p{Sentence_Break: OLetter} (Short: \p{SB=LE}) (97_841)
- \p{Sentence_Break: Other} (Short: \p{SB=XX}) (1_010_273)
- \p{Sentence_Break: SC} \p{Sentence_Break=SContinue} (26)
- \p{Sentence_Break: SContinue} (Short: \p{SB=SC}) (26)
- \p{Sentence_Break: SE} \p{Sentence_Break=Sep} (3)
- \p{Sentence_Break: Sep} (Short: \p{SB=SE}) (3)
- \p{Sentence_Break: Sp} (Short: \p{SB=Sp}) (21)
- \p{Sentence_Break: ST} \p{Sentence_Break=STerm} (80)
- \p{Sentence_Break: STerm} (Short: \p{SB=ST}) (80)
- \p{Sentence_Break: UP} \p{Sentence_Break=Upper} (1514)
- \p{Sentence_Break: Upper} (Short: \p{SB=UP}) (1514)
- \p{Sentence_Break: XX} \p{Sentence_Break=Other} (1_010_273)
- \p{Separator} \p{General_Category=Separator} (Short:
- \p{Z}) (20)
- \p{Sharada} \p{Script=Sharada} (Short: \p{Shrd}; NOT
- \p{Block=Sharada}) (83)
- \p{Shavian} \p{Script=Shavian} (Short: \p{Shaw}) (48)
- \p{Shaw} \p{Shavian} (= \p{Script=Shavian}) (48)
- \p{Shrd} \p{Sharada} (= \p{Script=Sharada}) (NOT
- \p{Block=Sharada}) (83)
- \p{Sinh} \p{Sinhala} (= \p{Script=Sinhala}) (NOT
- \p{Block=Sinhala}) (80)
- \p{Sinhala} \p{Script=Sinhala} (Short: \p{Sinh}; NOT
- \p{Block=Sinhala}) (80)
- \p{Sk} \p{Modifier_Symbol} (=
- \p{General_Category=Modifier_Symbol})
- (115)
- \p{Sm} \p{Math_Symbol} (= \p{General_Category=
- Math_Symbol}) (952)
- X \p{Small_Form_Variants} \p{Block=Small_Form_Variants} (Short:
- \p{InSmallForms}) (32)
- X \p{Small_Forms} \p{Small_Form_Variants} (= \p{Block=
- Small_Form_Variants}) (32)
- \p{So} \p{Other_Symbol} (= \p{General_Category=
- Other_Symbol}) (4404)
- \p{Soft_Dotted} \p{Soft_Dotted=Y} (Short: \p{SD}) (46)
- \p{Soft_Dotted: N*} (Short: \p{SD=N}, \P{SD}) (1_114_066)
- \p{Soft_Dotted: Y*} (Short: \p{SD=Y}, \p{SD}) (46)
- \p{Sora} \p{Sora_Sompeng} (= \p{Script=
- Sora_Sompeng}) (NOT \p{Block=
- Sora_Sompeng}) (35)
- \p{Sora_Sompeng} \p{Script=Sora_Sompeng} (Short: \p{Sora};
- NOT \p{Block=Sora_Sompeng}) (35)
- \p{Space} \p{White_Space=Y} \s including beyond
- ASCII plus vertical tab (26)
- \p{Space: *} \p{White_Space: *}
- \p{Space_Separator} \p{General_Category=Space_Separator}
- (Short: \p{Zs}) (18)
- \p{SpacePerl} \p{XPerlSpace} (25)
- \p{Spacing_Mark} \p{General_Category=Spacing_Mark} (Short:
- \p{Mc}) (353)
- X \p{Spacing_Modifier_Letters} \p{Block=Spacing_Modifier_Letters}
- (Short: \p{InModifierLetters}) (80)
- X \p{Specials} \p{Block=Specials} (16)
- \p{STerm} \p{STerm=Y} (83)
- \p{STerm: N*} (Single: \P{STerm}) (1_114_029)
- \p{STerm: Y*} (Single: \p{STerm}) (83)
- \p{Sund} \p{Sundanese} (= \p{Script=Sundanese})
- (NOT \p{Block=Sundanese}) (72)
- \p{Sundanese} \p{Script=Sundanese} (Short: \p{Sund}; NOT
- \p{Block=Sundanese}) (72)
- X \p{Sundanese_Sup} \p{Sundanese_Supplement} (= \p{Block=
- Sundanese_Supplement}) (16)
- X \p{Sundanese_Supplement} \p{Block=Sundanese_Supplement} (Short:
- \p{InSundaneseSup}) (16)
- X \p{Sup_Arrows_A} \p{Supplemental_Arrows_A} (= \p{Block=
- Supplemental_Arrows_A}) (16)
- X \p{Sup_Arrows_B} \p{Supplemental_Arrows_B} (= \p{Block=
- Supplemental_Arrows_B}) (128)
- X \p{Sup_Math_Operators} \p{Supplemental_Mathematical_Operators} (=
- \p{Block=
- Supplemental_Mathematical_Operators})
- (256)
- X \p{Sup_PUA_A} \p{Supplementary_Private_Use_Area_A} (=
- \p{Block=
- Supplementary_Private_Use_Area_A})
- (65_536)
- X \p{Sup_PUA_B} \p{Supplementary_Private_Use_Area_B} (=
- \p{Block=
- Supplementary_Private_Use_Area_B})
- (65_536)
- X \p{Sup_Punctuation} \p{Supplemental_Punctuation} (= \p{Block=
- Supplemental_Punctuation}) (128)
- X \p{Super_And_Sub} \p{Superscripts_And_Subscripts} (=
- \p{Block=Superscripts_And_Subscripts})
- (48)
- X \p{Superscripts_And_Subscripts} \p{Block=
- Superscripts_And_Subscripts} (Short:
- \p{InSuperAndSub}) (48)
- X \p{Supplemental_Arrows_A} \p{Block=Supplemental_Arrows_A} (Short:
- \p{InSupArrowsA}) (16)
- X \p{Supplemental_Arrows_B} \p{Block=Supplemental_Arrows_B} (Short:
- \p{InSupArrowsB}) (128)
- X \p{Supplemental_Mathematical_Operators} \p{Block=
- Supplemental_Mathematical_Operators}
- (Short: \p{InSupMathOperators}) (256)
- X \p{Supplemental_Punctuation} \p{Block=Supplemental_Punctuation}
- (Short: \p{InSupPunctuation}) (128)
- X \p{Supplementary_Private_Use_Area_A} \p{Block=
- Supplementary_Private_Use_Area_A}
- (Short: \p{InSupPUAA}) (65_536)
- X \p{Supplementary_Private_Use_Area_B} \p{Block=
- Supplementary_Private_Use_Area_B}
- (Short: \p{InSupPUAB}) (65_536)
- \p{Surrogate} \p{General_Category=Surrogate} (Short:
- \p{Cs}) (2048)
- \p{Sylo} \p{Syloti_Nagri} (= \p{Script=
- Syloti_Nagri}) (NOT \p{Block=
- Syloti_Nagri}) (44)
- \p{Syloti_Nagri} \p{Script=Syloti_Nagri} (Short: \p{Sylo};
- NOT \p{Block=Syloti_Nagri}) (44)
- \p{Symbol} \p{General_Category=Symbol} (Short: \p{S})
- (5519)
- \p{Syrc} \p{Syriac} (= \p{Script=Syriac}) (NOT
- \p{Block=Syriac}) (77)
- \p{Syriac} \p{Script=Syriac} (Short: \p{Syrc}; NOT
- \p{Block=Syriac}) (77)
- \p{Tagalog} \p{Script=Tagalog} (Short: \p{Tglg}; NOT
- \p{Block=Tagalog}) (20)
- \p{Tagb} \p{Tagbanwa} (= \p{Script=Tagbanwa}) (NOT
- \p{Block=Tagbanwa}) (18)
- \p{Tagbanwa} \p{Script=Tagbanwa} (Short: \p{Tagb}; NOT
- \p{Block=Tagbanwa}) (18)
- X \p{Tags} \p{Block=Tags} (128)
- \p{Tai_Le} \p{Script=Tai_Le} (Short: \p{Tale}; NOT
- \p{Block=Tai_Le}) (35)
- \p{Tai_Tham} \p{Script=Tai_Tham} (Short: \p{Lana}; NOT
- \p{Block=Tai_Tham}) (127)
- \p{Tai_Viet} \p{Script=Tai_Viet} (Short: \p{Tavt}; NOT
- \p{Block=Tai_Viet}) (72)
- X \p{Tai_Xuan_Jing} \p{Tai_Xuan_Jing_Symbols} (= \p{Block=
- Tai_Xuan_Jing_Symbols}) (96)
- X \p{Tai_Xuan_Jing_Symbols} \p{Block=Tai_Xuan_Jing_Symbols} (Short:
- \p{InTaiXuanJing}) (96)
- \p{Takr} \p{Takri} (= \p{Script=Takri}) (NOT
- \p{Block=Takri}) (66)
- \p{Takri} \p{Script=Takri} (Short: \p{Takr}; NOT
- \p{Block=Takri}) (66)
- \p{Tale} \p{Tai_Le} (= \p{Script=Tai_Le}) (NOT
- \p{Block=Tai_Le}) (35)
- \p{Talu} \p{New_Tai_Lue} (= \p{Script=New_Tai_Lue})
- (NOT \p{Block=New_Tai_Lue}) (83)
- \p{Tamil} \p{Script=Tamil} (Short: \p{Taml}; NOT
- \p{Block=Tamil}) (72)
- \p{Taml} \p{Tamil} (= \p{Script=Tamil}) (NOT
- \p{Block=Tamil}) (72)
- \p{Tavt} \p{Tai_Viet} (= \p{Script=Tai_Viet}) (NOT
- \p{Block=Tai_Viet}) (72)
- \p{Telu} \p{Telugu} (= \p{Script=Telugu}) (NOT
- \p{Block=Telugu}) (93)
- \p{Telugu} \p{Script=Telugu} (Short: \p{Telu}; NOT
- \p{Block=Telugu}) (93)
- \p{Term} \p{Terminal_Punctuation} (=
- \p{Terminal_Punctuation=Y}) (176)
- \p{Term: *} \p{Terminal_Punctuation: *}
- \p{Terminal_Punctuation} \p{Terminal_Punctuation=Y} (Short:
- \p{Term}) (176)
- \p{Terminal_Punctuation: N*} (Short: \p{Term=N}, \P{Term})
- (1_113_936)
- \p{Terminal_Punctuation: Y*} (Short: \p{Term=Y}, \p{Term}) (176)
- \p{Tfng} \p{Tifinagh} (= \p{Script=Tifinagh}) (NOT
- \p{Block=Tifinagh}) (59)
- \p{Tglg} \p{Tagalog} (= \p{Script=Tagalog}) (NOT
- \p{Block=Tagalog}) (20)
- \p{Thaa} \p{Thaana} (= \p{Script=Thaana}) (NOT
- \p{Block=Thaana}) (50)
- \p{Thaana} \p{Script=Thaana} (Short: \p{Thaa}; NOT
- \p{Block=Thaana}) (50)
- \p{Thai} \p{Script=Thai} (NOT \p{Block=Thai}) (86)
- \p{Tibetan} \p{Script=Tibetan} (Short: \p{Tibt}; NOT
- \p{Block=Tibetan}) (207)
- \p{Tibt} \p{Tibetan} (= \p{Script=Tibetan}) (NOT
- \p{Block=Tibetan}) (207)
- \p{Tifinagh} \p{Script=Tifinagh} (Short: \p{Tfng}; NOT
- \p{Block=Tifinagh}) (59)
- \p{Title} \p{Titlecase} (/i= Cased=Yes) (31)
- \p{Titlecase} (= \p{Gc=Lt}) (Short: \p{Title}; /i=
- Cased=Yes) (31)
- \p{Titlecase_Letter} \p{General_Category=Titlecase_Letter}
- (Short: \p{Lt}; /i= General_Category=
- Cased_Letter) (31)
- X \p{Transport_And_Map} \p{Transport_And_Map_Symbols} (= \p{Block=
- Transport_And_Map_Symbols}) (128)
- X \p{Transport_And_Map_Symbols} \p{Block=Transport_And_Map_Symbols}
- (Short: \p{InTransportAndMap}) (128)
- X \p{UCAS} \p{Unified_Canadian_Aboriginal_Syllabics}
- (= \p{Block=
- Unified_Canadian_Aboriginal_Syllabics})
- (640)
- X \p{UCAS_Ext} \p{Unified_Canadian_Aboriginal_Syllabics_-
- Extended} (= \p{Block=
- Unified_Canadian_Aboriginal_Syllabics_-
- Extended}) (80)
- \p{Ugar} \p{Ugaritic} (= \p{Script=Ugaritic}) (NOT
- \p{Block=Ugaritic}) (31)
- \p{Ugaritic} \p{Script=Ugaritic} (Short: \p{Ugar}; NOT
- \p{Block=Ugaritic}) (31)
- \p{UIdeo} \p{Unified_Ideograph} (=
- \p{Unified_Ideograph=Y}) (74_617)
- \p{UIdeo: *} \p{Unified_Ideograph: *}
- \p{Unassigned} \p{General_Category=Unassigned} (Short:
- \p{Cn}) (864_415)
- X \p{Unified_Canadian_Aboriginal_Syllabics} \p{Block=
- Unified_Canadian_Aboriginal_Syllabics}
- (Short: \p{InUCAS}) (640)
- X \p{Unified_Canadian_Aboriginal_Syllabics_Extended} \p{Block=
- Unified_Canadian_Aboriginal_Syllabics_-
- Extended} (Short: \p{InUCASExt}) (80)
- \p{Unified_Ideograph} \p{Unified_Ideograph=Y} (Short: \p{UIdeo})
- (74_617)
- \p{Unified_Ideograph: N*} (Short: \p{UIdeo=N}, \P{UIdeo})
- (1_039_495)
- \p{Unified_Ideograph: Y*} (Short: \p{UIdeo=Y}, \p{UIdeo}) (74_617)
- \p{Unknown} \p{Script=Unknown} (Short: \p{Zzzz})
- (1_003_931)
- \p{Upper} \p{Uppercase=Y} (/i= Cased=Yes) (1483)
- \p{Upper: *} \p{Uppercase: *}
- \p{Uppercase} \p{Upper} (= \p{Uppercase=Y}) (/i= Cased=
- Yes) (1483)
- \p{Uppercase: N*} (Short: \p{Upper=N}, \P{Upper}; /i= Cased=
- No) (1_112_629)
- \p{Uppercase: Y*} (Short: \p{Upper=Y}, \p{Upper}; /i= Cased=
- Yes) (1483)
- \p{Uppercase_Letter} \p{General_Category=Uppercase_Letter}
- (Short: \p{Lu}; /i= General_Category=
- Cased_Letter) (1441)
- \p{Vai} \p{Script=Vai} (NOT \p{Block=Vai}) (300)
- \p{Vaii} \p{Vai} (= \p{Script=Vai}) (NOT \p{Block=
- Vai}) (300)
- \p{Variation_Selector} \p{Variation_Selector=Y} (Short: \p{VS};
- NOT \p{Variation_Selectors}) (259)
- \p{Variation_Selector: N*} (Short: \p{VS=N}, \P{VS}) (1_113_853)
- \p{Variation_Selector: Y*} (Short: \p{VS=Y}, \p{VS}) (259)
- X \p{Variation_Selectors} \p{Block=Variation_Selectors} (Short:
- \p{InVS}) (16)
- X \p{Variation_Selectors_Supplement} \p{Block=
- Variation_Selectors_Supplement} (Short:
- \p{InVSSup}) (240)
- X \p{Vedic_Ext} \p{Vedic_Extensions} (= \p{Block=
- Vedic_Extensions}) (48)
- X \p{Vedic_Extensions} \p{Block=Vedic_Extensions} (Short:
- \p{InVedicExt}) (48)
- X \p{Vertical_Forms} \p{Block=Vertical_Forms} (16)
- \p{VertSpace} \v (7)
- \p{VS} \p{Variation_Selector} (=
- \p{Variation_Selector=Y}) (NOT
- \p{Variation_Selectors}) (259)
- \p{VS: *} \p{Variation_Selector: *}
- X \p{VS_Sup} \p{Variation_Selectors_Supplement} (=
- \p{Block=
- Variation_Selectors_Supplement}) (240)
- \p{WB: *} \p{Word_Break: *}
- \p{White_Space} \p{White_Space=Y} (Short: \p{WSpace}) (26)
- \p{White_Space: N*} (Short: \p{Space=N}, \P{WSpace})
- (1_114_086)
- \p{White_Space: Y*} (Short: \p{Space=Y}, \p{WSpace}) (26)
- \p{Word} \w, including beyond ASCII; = \p{Alnum} +
- \pM + \p{Pc} (103_404)
- \p{Word_Break: ALetter} (Short: \p{WB=LE}) (24_941)
- \p{Word_Break: CR} (Short: \p{WB=CR}) (1)
- \p{Word_Break: EX} \p{Word_Break=ExtendNumLet} (10)
- \p{Word_Break: Extend} (Short: \p{WB=Extend}) (1649)
- \p{Word_Break: ExtendNumLet} (Short: \p{WB=EX}) (10)
- \p{Word_Break: FO} \p{Word_Break=Format} (136)
- \p{Word_Break: Format} (Short: \p{WB=FO}) (136)
- \p{Word_Break: KA} \p{Word_Break=Katakana} (310)
- \p{Word_Break: Katakana} (Short: \p{WB=KA}) (310)
- \p{Word_Break: LE} \p{Word_Break=ALetter} (24_941)
- \p{Word_Break: LF} (Short: \p{WB=LF}) (1)
- \p{Word_Break: MB} \p{Word_Break=MidNumLet} (8)
- \p{Word_Break: MidLetter} (Short: \p{WB=ML}) (8)
- \p{Word_Break: MidNum} (Short: \p{WB=MN}) (15)
- \p{Word_Break: MidNumLet} (Short: \p{WB=MB}) (8)
- \p{Word_Break: ML} \p{Word_Break=MidLetter} (8)
- \p{Word_Break: MN} \p{Word_Break=MidNum} (15)
- \p{Word_Break: Newline} (Short: \p{WB=NL}) (5)
- \p{Word_Break: NL} \p{Word_Break=Newline} (5)
- \p{Word_Break: NU} \p{Word_Break=Numeric} (451)
- \p{Word_Break: Numeric} (Short: \p{WB=NU}) (451)
- \p{Word_Break: Other} (Short: \p{WB=XX}) (1_086_577)
- \p{Word_Break: XX} \p{Word_Break=Other} (1_086_577)
- \p{WSpace} \p{White_Space} (= \p{White_Space=Y}) (26)
- \p{WSpace: *} \p{White_Space: *}
- \p{XDigit} \p{Hex_Digit=Y} (Short: \p{Hex}) (44)
- \p{XID_Continue} \p{XID_Continue=Y} (Short: \p{XIDC})
- (103_336)
- \p{XID_Continue: N*} (Short: \p{XIDC=N}, \P{XIDC}) (1_010_776)
- \p{XID_Continue: Y*} (Short: \p{XIDC=Y}, \p{XIDC}) (103_336)
- \p{XID_Start} \p{XID_Start=Y} (Short: \p{XIDS}) (101_217)
- \p{XID_Start: N*} (Short: \p{XIDS=N}, \P{XIDS}) (1_012_895)
- \p{XID_Start: Y*} (Short: \p{XIDS=Y}, \p{XIDS}) (101_217)
- \p{XIDC} \p{XID_Continue} (= \p{XID_Continue=Y})
- (103_336)
- \p{XIDC: *} \p{XID_Continue: *}
- \p{XIDS} \p{XID_Start} (= \p{XID_Start=Y}) (101_217)
- \p{XIDS: *} \p{XID_Start: *}
- \p{Xpeo} \p{Old_Persian} (= \p{Script=Old_Persian})
- (NOT \p{Block=Old_Persian}) (50)
- \p{XPerlSpace} \s, including beyond ASCII (Short:
- \p{SpacePerl}) (25)
- \p{XPosixAlnum} \p{Alnum} (102_619)
- \p{XPosixAlpha} \p{Alpha} (= \p{Alphabetic=Y}) (102_159)
- \p{XPosixBlank} \p{Blank} (19)
- \p{XPosixCntrl} \p{Cntrl} (= \p{General_Category=Control})
- (65)
- \p{XPosixDigit} \p{Digit} (= \p{General_Category=
- Decimal_Number}) (460)
- \p{XPosixGraph} \p{Graph} (247_564)
- \p{XPosixLower} \p{Lower} (= \p{Lowercase=Y}) (/i= Cased=
- Yes) (1934)
- \p{XPosixPrint} \p{Print} (247_582)
- \p{XPosixPunct} \p{Punct} + ASCII-range \p{Symbol} (641)
- \p{XPosixSpace} \p{Space} (= \p{White_Space=Y}) (26)
- \p{XPosixUpper} \p{Upper} (= \p{Uppercase=Y}) (/i= Cased=
- Yes) (1483)
- \p{XPosixWord} \p{Word} (103_404)
- \p{XPosixXDigit} \p{XDigit} (= \p{Hex_Digit=Y}) (44)
- \p{Xsux} \p{Cuneiform} (= \p{Script=Cuneiform})
- (NOT \p{Block=Cuneiform}) (982)
- \p{Yi} \p{Script=Yi} (1220)
- X \p{Yi_Radicals} \p{Block=Yi_Radicals} (64)
- X \p{Yi_Syllables} \p{Block=Yi_Syllables} (1168)
- \p{Yiii} \p{Yi} (= \p{Script=Yi}) (1220)
- X \p{Yijing} \p{Yijing_Hexagram_Symbols} (= \p{Block=
- Yijing_Hexagram_Symbols}) (64)
- X \p{Yijing_Hexagram_Symbols} \p{Block=Yijing_Hexagram_Symbols}
- (Short: \p{InYijing}) (64)
- \p{Z} \p{Separator} (= \p{General_Category=
- Separator}) (20)
- \p{Zinh} \p{Inherited} (= \p{Script=Inherited})
- (524)
- \p{Zl} \p{Line_Separator} (= \p{General_Category=
- Line_Separator}) (1)
- \p{Zp} \p{Paragraph_Separator} (=
- \p{General_Category=
- Paragraph_Separator}) (1)
- \p{Zs} \p{Space_Separator} (=
- \p{General_Category=Space_Separator})
- (18)
- \p{Zyyy} \p{Common} (= \p{Script=Common}) (6412)
- \p{Zzzz} \p{Unknown} (= \p{Script=Unknown})
- (1_003_931)
- TX\p{_CanonDCIJ} (For internal use by Perl, not necessarily
- stable) (= \p{Soft_Dotted=Y}) (46)
- TX\p{_Case_Ignorable} (For internal use by Perl, not necessarily
- stable) (= \p{Case_Ignorable=Y}) (1799)
- TX\p{_CombAbove} (For internal use by Perl, not necessarily
- stable) (= \p{Canonical_Combining_Class=
- Above}) (349)
-
-
-
-=head2 Legal C<\p{}> and C<\P{}> constructs that match no characters
-
-Unicode has some property-value pairs that currently don't match anything.
-This happens generally either because they are obsolete, or they exist for
-symmetry with other forms, but no language has yet been encoded that uses
-them. In this version of Unicode, the following match zero code points:
-
-=over 4
-
-=item \p{Canonical_Combining_Class=Attached_Below_Left}
-
-=item \p{Grapheme_Cluster_Break=Prepend}
-
-=item \p{Joining_Type=Left_Joining}
-
-=back
-
-
-
-=head1 Properties accessible through Unicode::UCD
-
-All the Unicode character properties mentioned above (except for those marked
-as for internal use by Perl) are also accessible by
-L<Unicode::UCD/prop_invlist()>.
-
-Due to their nature, not all Unicode character properties are suitable for
-regular expression matches, nor C<prop_invlist()>. The remaining
-non-provisional, non-internal ones are accessible via
-L<Unicode::UCD/prop_invmap()> (except for those that this Perl installation
-hasn't included; see L<below for which those are|/Unicode character properties
-that are NOT accepted by Perl>).
-
-For compatibility with other parts of Perl, all the single forms given in the
-table in the L<section above|/Properties accessible through \p{} and \P{}>
-are recognized. BUT, there are some ambiguities between some Perl extensions
-and the Unicode properties, all of which are silently resolved in favor of the
-official Unicode property. To avoid surprises, you should only use
-C<prop_invmap()> for forms listed in the table below, which omits the
-non-recommended ones. The affected forms are the Perl single form equivalents
-of Unicode properties, such as C<\p{sc}> being a single-form equivalent of
-C<\p{gc=sc}>, which is treated by C<prop_invmap()> as the C<Script> property,
-whose short name is C<sc>. The table indicates the current ambiguities in the
-INFO column, beginning with the word C<"NOT">.
-
-The standard Unicode properties listed below are documented in
-L<http://www.unicode.org/reports/tr44/>; Perl_Decimal_Digit is documented in
-L<Unicode::UCD/prop_invmap()>. The other Perl extensions are in
-L<perlunicode/Other Properties>;
-
-The first column in the table is a name for the property; the second column is
-an alternative name, if any, plus possibly some annotations. The alternative
-name is the property's full name, unless that would simply repeat the first
-column, in which case the second column indicates the property's short name
-(if different). The annotations are given only in the entry for the full
-name. If a property is obsolete, etc, the entry will be flagged with the same
-characters used in the table in the L<section above|/Properties accessible
-through \p{} and \P{}>, like B<D> or B<S>.
-
- NAME INFO
-
- Age
- AHex ASCII_Hex_Digit
- All Any. (Perl extension)
- Alnum (Perl extension). Alphabetic and
- (decimal) Numeric
- Alpha Alphabetic
- Alphabetic (Short: Alpha)
- Any (Perl extension). [\x{0000}-\x{10FFFF}]
- ASCII Block=ASCII. (Perl extension).
- [[:ASCII:]]
- ASCII_Hex_Digit (Short: AHex)
- Assigned (Perl extension). All assigned code points
- Bc Bidi_Class
- Bidi_C Bidi_Control
- Bidi_Class (Short: bc)
- Bidi_Control (Short: Bidi_C)
- Bidi_M Bidi_Mirrored
- Bidi_Mirrored (Short: Bidi_M)
- Bidi_Mirroring_Glyph (Short: bmg)
- Blank (Perl extension). \h, Horizontal white
- space
- Blk Block
- Block (Short: blk)
- Bmg Bidi_Mirroring_Glyph
- Canonical_Combining_Class (Short: ccc)
- Case_Folding (Short: cf)
- Case_Ignorable (Short: CI)
- Cased
- Category General_Category
- Ccc Canonical_Combining_Class
- CE Composition_Exclusion
- Cf Case_Folding; NOT 'cf' meaning
- 'General_Category=Format'
- Changes_When_Casefolded (Short: CWCF)
- Changes_When_Casemapped (Short: CWCM)
- Changes_When_Lowercased (Short: CWL)
- Changes_When_NFKC_Casefolded (Short: CWKCF)
- Changes_When_Titlecased (Short: CWT)
- Changes_When_Uppercased (Short: CWU)
- CI Case_Ignorable
- Cntrl General_Category=Cntrl. (Perl extension).
- Control characters
- Comp_Ex Full_Composition_Exclusion
- Composition_Exclusion (Short: CE)
- CWCF Changes_When_Casefolded
- CWCM Changes_When_Casemapped
- CWKCF Changes_When_NFKC_Casefolded
- CWL Changes_When_Lowercased
- CWT Changes_When_Titlecased
- CWU Changes_When_Uppercased
- Dash
- Decomposition_Mapping (Short: dm)
- Decomposition_Type (Short: dt)
- Default_Ignorable_Code_Point (Short: DI)
- Dep Deprecated
- Deprecated (Short: Dep)
- DI Default_Ignorable_Code_Point
- Dia Diacritic
- Diacritic (Short: Dia)
- Digit General_Category=Digit. (Perl extension).
- [0-9] + all other decimal digits
- Dm Decomposition_Mapping
- Dt Decomposition_Type
- Ea East_Asian_Width
- East_Asian_Width (Short: ea)
- Ext Extender
- Extender (Short: Ext)
- Full_Composition_Exclusion (Short: Comp_Ex)
- Gc General_Category
- GCB Grapheme_Cluster_Break
- General_Category (Short: gc)
- Gr_Base Grapheme_Base
- Gr_Ext Grapheme_Extend
- Graph (Perl extension). Characters that are
- graphical
- Grapheme_Base (Short: Gr_Base)
- Grapheme_Cluster_Break (Short: GCB)
- Grapheme_Extend (Short: Gr_Ext)
- Hangul_Syllable_Type (Short: hst)
- Hex Hex_Digit
- Hex_Digit (Short: Hex)
- HorizSpace Blank. (Perl extension)
- Hst Hangul_Syllable_Type
- D Hyphen Supplanted by Line_Break property values;
- see www.unicode.org/reports/tr14
- ID_Continue (Short: IDC)
- ID_Start (Short: IDS)
- IDC ID_Continue
- Ideo Ideographic
- Ideographic (Short: Ideo)
- IDS ID_Start
- IDS_Binary_Operator (Short: IDSB)
- IDS_Trinary_Operator (Short: IDST)
- IDSB IDS_Binary_Operator
- IDST IDS_Trinary_Operator
- In Present_In. (Perl extension)
- Isc ISO_Comment; NOT 'isc' meaning
- 'General_Category=Other'
- ISO_Comment (Short: isc)
- Jg Joining_Group
- Join_C Join_Control
- Join_Control (Short: Join_C)
- Joining_Group (Short: jg)
- Joining_Type (Short: jt)
- Jt Joining_Type
- Lb Line_Break
- Lc Lowercase_Mapping; NOT 'lc' meaning
- 'General_Category=Cased_Letter'
- Line_Break (Short: lb)
- LOE Logical_Order_Exception
- Logical_Order_Exception (Short: LOE)
- Lower Lowercase
- Lowercase (Short: Lower)
- Lowercase_Mapping (Short: lc)
- Math
- Na Name
- Na1 Unicode_1_Name
- Name (Short: na)
- Name_Alias
- NChar Noncharacter_Code_Point
- NFC_QC NFC_Quick_Check
- NFC_Quick_Check (Short: NFC_QC)
- NFD_QC NFD_Quick_Check
- NFD_Quick_Check (Short: NFD_QC)
- NFKC_Casefold (Short: NFKC_CF)
- NFKC_CF NFKC_Casefold
- NFKC_QC NFKC_Quick_Check
- NFKC_Quick_Check (Short: NFKC_QC)
- NFKD_QC NFKD_Quick_Check
- NFKD_Quick_Check (Short: NFKD_QC)
- Noncharacter_Code_Point (Short: NChar)
- Nt Numeric_Type
- Numeric_Type (Short: nt)
- Numeric_Value (Short: nv)
- Nv Numeric_Value
- Pat_Syn Pattern_Syntax
- Pat_WS Pattern_White_Space
- Pattern_Syntax (Short: Pat_Syn)
- Pattern_White_Space (Short: Pat_WS)
- Perl_Decimal_Digit (Perl extension)
- PerlSpace (Perl extension). \s, restricted to ASCII
- = [ \f\n\r\t]
- PerlWord (Perl extension). \w, restricted to ASCII
- = [A-Za-z0-9_]
- PosixAlnum (Perl extension). [A-Za-z0-9]
- PosixAlpha (Perl extension). [A-Za-z]
- PosixBlank (Perl extension). \t and ' '
- PosixCntrl (Perl extension). ASCII control
- characters: NUL, SOH, STX, ETX, EOT, ENQ,
- ACK, BEL, BS, HT, LF, VT, FF, CR, SO, SI,
- DLE, DC1, DC2, DC3, DC4, NAK, SYN, ETB,
- CAN, EOM, SUB, ESC, FS, GS, RS, US, and DEL
- PosixDigit (Perl extension). [0-9]
- PosixGraph (Perl extension). [-
- !"#$%&'()*+,./:;<>?@[\\]^_`{|}~0-9A-Za-z]
- PosixLower (Perl extension). [a-z]
- PosixPrint (Perl extension). [- 0-9A-Za-
- z!"#$%&'()*+,./:;<>?@[\\]^_`{|}~]
- PosixPunct (Perl extension). [-
- !"#$%&'()*+,./:;<>?@[\\]^_`{|}~]
- PosixSpace (Perl extension). \t, \n, \cK, \f, \r,
- and ' '. (\cK is vertical tab)
- PosixUpper (Perl extension). [A-Z]
- PosixWord PerlWord. (Perl extension)
- PosixXDigit (Perl extension). [0-9A-Fa-f]
- Present_In (Short: In). (Perl extension)
- Print (Perl extension). Characters that are
- graphical plus space characters (but no
- controls)
- Punct General_Category=Punct. (Perl extension)
- QMark Quotation_Mark
- Quotation_Mark (Short: QMark)
- Radical
- SB Sentence_Break
- Sc Script; NOT 'sc' meaning
- 'General_Category=Currency_Symbol'
- Scf Simple_Case_Folding
- Script (Short: sc)
- Script_Extensions (Short: scx)
- Scx Script_Extensions
- SD Soft_Dotted
- Sentence_Break (Short: SB)
- Sfc Simple_Case_Folding
- Simple_Case_Folding (Short: scf)
- Simple_Lowercase_Mapping (Short: slc)
- Simple_Titlecase_Mapping (Short: stc)
- Simple_Uppercase_Mapping (Short: suc)
- Slc Simple_Lowercase_Mapping
- Soft_Dotted (Short: SD)
- Space White_Space
- SpacePerl XPerlSpace. (Perl extension)
- Stc Simple_Titlecase_Mapping
- STerm
- Suc Simple_Uppercase_Mapping
- Tc Titlecase_Mapping
- Term Terminal_Punctuation
- Terminal_Punctuation (Short: Term)
- Title Titlecase. (Perl extension)
- Titlecase (Short: Title). (Perl extension). (=
- \p{Gc=Lt})
- Titlecase_Mapping (Short: tc)
- Uc Uppercase_Mapping
- UIdeo Unified_Ideograph
- Unicode_1_Name (Short: na1)
- Unified_Ideograph (Short: UIdeo)
- Upper Uppercase
- Uppercase (Short: Upper)
- Uppercase_Mapping (Short: uc)
- Variation_Selector (Short: VS)
- VertSpace (Perl extension). \v
- VS Variation_Selector
- WB Word_Break
- White_Space (Short: WSpace)
- Word (Perl extension). \w, including beyond
- ASCII; = \p{Alnum} + \pM + \p{Pc}
- Word_Break (Short: WB)
- WSpace White_Space
- XDigit (Perl extension)
- XID_Continue (Short: XIDC)
- XID_Start (Short: XIDS)
- XIDC XID_Continue
- XIDS XID_Start
- XPerlSpace (Perl extension). \s, including beyond
- ASCII
- XPosixAlnum Alnum. (Perl extension)
- XPosixAlpha Alpha. (Perl extension)
- XPosixBlank Blank. (Perl extension)
- XPosixCntrl General_Category=Cntrl. (Perl extension)
- XPosixDigit General_Category=Digit. (Perl extension)
- XPosixGraph Graph. (Perl extension)
- XPosixLower Lower. (Perl extension)
- XPosixPrint Print. (Perl extension)
- XPosixPunct (Perl extension). \p{Punct} + ASCII-range
- \p{Symbol}
- XPosixSpace Space. (Perl extension)
- XPosixUpper Upper. (Perl extension)
- XPosixWord Word. (Perl extension)
- XPosixXDigit XDigit. (Perl extension)
-
-
-=head1 Properties accessible through other means
-
-Certain properties are accessible also via core function calls. These are:
-
- Lowercase_Mapping lc() and lcfirst()
- Titlecase_Mapping ucfirst()
- Uppercase_Mapping uc()
-
-Also, Case_Folding is accessible through the C</i> modifier in regular
-expressions, the C<\F> transliteration escape, and the C<L<fc|perlfunc/fc>>
-operator.
-
-And, the Name and Name_Aliases properties are accessible through the C<\N{}>
-interpolation in double-quoted strings and regular expressions; and functions
-C<charnames::viacode()>, C<charnames::vianame()>, and
-C<charnames::string_vianame()> (which require a C<use charnames ();> to be
-specified.
-
-Finally, most properties related to decomposition are accessible via
-L<Unicode::Normalize>.
-
-=head1 Unicode character properties that are NOT accepted by Perl
-
-Perl will generate an error for a few character properties in Unicode when
-used in a regular expression. The non-Unihan ones are listed below, with the
-reasons they are not accepted, perhaps with work-arounds. The short names for
-the properties are listed enclosed in (parentheses).
-As described after the list, an installation can change the defaults and choose
-to accept any of these. The list is machine generated based on the
-choices made for the installation that generated this document.
-
-
-=over 4
-
-
-
-=item I<Expands_On_NFC> (XO_NFC)
-
-=item I<Expands_On_NFD> (XO_NFD)
-
-=item I<Expands_On_NFKC> (XO_NFKC)
-
-=item I<Expands_On_NFKD> (XO_NFKD)
-
-Deprecated by Unicode. These are characters that expand to more than one character in the specified normalization form, but whether they actually take up more bytes or not depends on the encoding being used. For example, a UTF-8 encoded character may expand to a different number of bytes than a UTF-32 encoded character.
-
-
-
-=item I<Grapheme_Link> (Gr_Link)
-
-Deprecated by Unicode: Duplicates ccc=vr (Canonical_Combining_Class=Virama)
-
-
-
-=item I<Indic_Matra_Category> (InMC)
-
-=item I<Indic_Syllabic_Category> (InSC)
-
-Provisional
-
-
-
-=item I<Jamo_Short_Name> (JSN)
-
-=item I<Other_Alphabetic> (OAlpha)
-
-=item I<Other_Default_Ignorable_Code_Point> (ODI)
-
-=item I<Other_Grapheme_Extend> (OGr_Ext)
-
-=item I<Other_ID_Continue> (OIDC)
-
-=item I<Other_ID_Start> (OIDS)
-
-=item I<Other_Lowercase> (OLower)
-
-=item I<Other_Math> (OMath)
-
-=item I<Other_Uppercase> (OUpper)
-
-Used by Unicode internally for generating other properties and not intended to be used stand-alone
-
-
-
-=item I<Script=Katakana_Or_Hiragana> (sc=Hrkt)
-
-Obsolete. All code points previously matched by this have been moved to "Script=Common". Consider instead using "Script_Extensions=Katakana" or "Script_Extensions=Hiragana (or both)"
-
-
-
-=item I<Script_Extensions=Katakana_Or_Hiragana> (scx=Hrkt)
-
-All code points that would be matched by this are matched by either "Script_Extensions=Katakana" or "Script_Extensions=Hiragana"
-
-=back
-
-
-An installation can choose to allow any of these to be matched by downloading
-the Unicode database from L<http://www.unicode.org/Public/> to
-C<$Config{privlib}>/F<unicore/> in the Perl source tree, changing the
-controlling lists contained in the program
-C<$Config{privlib}>/F<unicore/mktables> and then re-compiling and installing.
-(C<%Config> is available from the Config module).
-
-=head1 Other information in the Unicode data base
-
-The Unicode data base is delivered in two different formats. The XML version
-is valid for more modern Unicode releases. The other version is a collection
-of files. The two are intended to give equivalent information. Perl uses the
-older form; this allows you to recompile Perl to use early Unicode releases.
-
-The only non-character property that Perl currently supports is Named
-Sequences, in which a sequence of code points
-is given a name and generally treated as a single entity. (Perl supports
-these via the C<\N{...}> double-quotish construct,
-L<charnames/charnames::string_vianame(name)>, and L<Unicode::UCD/namedseq()>.
-
-Below is a list of the files in the Unicode data base that Perl doesn't
-currently use, along with very brief descriptions of their purposes.
-Some of the names of the files have been shortened from those that Unicode
-uses, in order to allow them to be distinguishable from similarly named files
-on file systems for which only the first 8 characters of a name are
-significant.
-
-=over 4
-
-
-
-
-=item F<auxiliary/GraphemeBreakTest.html>
-
-=item F<auxiliary/LineBreakTest.html>
-
-=item F<auxiliary/SentenceBreakTest.html>
-
-=item F<auxiliary/WordBreakTest.html>
-
-Documentation of validation tests
-
-
-
-=item F<auxiliary\LBTest.txt>
-
-=item F<auxiliary\SBTest.txt>
-
-=item F<auxiliary\WBTest.txt>
-
-=item F<BidiTest.txt>
-
-=item F<NormalizationTest.txt>
-
-Validation Tests
-
-
-
-=item F<CJKRadicals.txt>
-
-Maps the kRSUnicode property values to corresponding code points
-
-
-
-=item F<EmojiSources.txt>
-
-Maps certain Unicode code points to their legacy Japanese cell-phone values
-
-
-
-=item F<Index.txt>
-
-Alphabetical index of Unicode characters
-
-
-
-=item F<IndicMatraCategory.txt>
-
-=item F<IndicSyllabicCategory.txt>
-
-Provisional; for the analysis and processing of Indic scripts
-
-
-
-=item F<NamedSqProv.txt>
-
-Named sequences proposed for inclusion in a later version of the Unicode Standard; if you need them now, you can append this file to F<NamedSequences.txt> and recompile perl
-
-
-
-=item F<NamesList.txt>
-
-Annotated list of characters
-
-
-
-=item F<NormalizationCorrections.txt>
-
-Documentation of corrections already incorporated into the Unicode data base
-
-
-
-=item F<Props.txt>
-
-Only in very early releases; is a subset of F<PropList.txt> (which is used instead)
-
-
-
-=item F<ReadMe.txt>
-
-Documentation
-
-
-
-=item F<StandardizedVariants.txt>
-
-Certain glyph variations for character display are standardized. This lists the non-Unihan ones; the Unihan ones are also not used by Perl, and are in a separate Unicode data base L<http://www.unicode.org/ivd>
-
-
-=back
-
-=head1 SEE ALSO
-
-L<http://www.unicode.org/reports/tr44/>
-
-L<perlrecharclass>
-
-L<perlunicode>
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlunitut.pod b/Master/tlpkg/tlperl/lib/pods/perlunitut.pod
deleted file mode 100644
index 9e5af04ec79..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlunitut.pod
+++ /dev/null
@@ -1,208 +0,0 @@
-=head1 NAME
-
-perlunitut - Perl Unicode Tutorial
-
-=head1 DESCRIPTION
-
-The days of just flinging strings around are over. It's well established that
-modern programs need to be capable of communicating funny accented letters, and
-things like euro symbols. This means that programmers need new habits. It's
-easy to program Unicode capable software, but it does require discipline to do
-it right.
-
-There's a lot to know about character sets, and text encodings. It's probably
-best to spend a full day learning all this, but the basics can be learned in
-minutes.
-
-These are not the very basics, though. It is assumed that you already
-know the difference between bytes and characters, and realise (and accept!)
-that there are many different character sets and encodings, and that your
-program has to be explicit about them. Recommended reading is "The Absolute
-Minimum Every Software Developer Absolutely, Positively Must Know About Unicode
-and Character Sets (No Excuses!)" by Joel Spolsky, at
-L<http://joelonsoftware.com/articles/Unicode.html>.
-
-This tutorial speaks in rather absolute terms, and provides only a limited view
-of the wealth of character string related features that Perl has to offer. For
-most projects, this information will probably suffice.
-
-=head2 Definitions
-
-It's important to set a few things straight first. This is the most important
-part of this tutorial. This view may conflict with other information that you
-may have found on the web, but that's mostly because many sources are wrong.
-
-You may have to re-read this entire section a few times...
-
-=head3 Unicode
-
-B<Unicode> is a character set with room for lots of characters. The ordinal
-value of a character is called a B<code point>. (But in practice, the
-distinction between code point and character is blurred, so the terms often
-are used interchangeably.)
-
-There are many, many code points, but computers work with bytes, and a byte has
-room for only 256 values. Unicode has many more characters than that,
-so you need a method to make these accessible.
-
-Unicode is encoded using several competing encodings, of which UTF-8 is the
-most used. In a Unicode encoding, multiple subsequent bytes can be used to
-store a single code point, or simply: character.
-
-=head3 UTF-8
-
-B<UTF-8> is a Unicode encoding. Many people think that Unicode and UTF-8 are
-the same thing, but they're not. There are more Unicode encodings, but much of
-the world has standardized on UTF-8.
-
-UTF-8 treats the first 128 codepoints, 0..127, the same as ASCII. They take
-only one byte per character. All other characters are encoded as two or more
-(up to six) bytes using a complex scheme. Fortunately, Perl handles this for
-us, so we don't have to worry about this.
-
-=head3 Text strings (character strings)
-
-B<Text strings>, or B<character strings> are made of characters. Bytes are
-irrelevant here, and so are encodings. Each character is just that: the
-character.
-
-On a text string, you would do things like:
-
- $text =~ s/foo/bar/;
- if ($string =~ /^\d+$/) { ... }
- $text = ucfirst $text;
- my $character_count = length $text;
-
-The value of a character (C<ord>, C<chr>) is the corresponding Unicode code
-point.
-
-=head3 Binary strings (byte strings)
-
-B<Binary strings>, or B<byte strings> are made of bytes. Here, you don't have
-characters, just bytes. All communication with the outside world (anything
-outside of your current Perl process) is done in binary.
-
-On a binary string, you would do things like:
-
- my (@length_content) = unpack "(V/a)*", $binary;
- $binary =~ s/\x00\x0F/\xFF\xF0/; # for the brave :)
- print {$fh} $binary;
- my $byte_count = length $binary;
-
-=head3 Encoding
-
-B<Encoding> (as a verb) is the conversion from I<text> to I<binary>. To encode,
-you have to supply the target encoding, for example C<iso-8859-1> or C<UTF-8>.
-Some encodings, like the C<iso-8859> ("latin") range, do not support the full
-Unicode standard; characters that can't be represented are lost in the
-conversion.
-
-=head3 Decoding
-
-B<Decoding> is the conversion from I<binary> to I<text>. To decode, you have to
-know what encoding was used during the encoding phase. And most of all, it must
-be something decodable. It doesn't make much sense to decode a PNG image into a
-text string.
-
-=head3 Internal format
-
-Perl has an B<internal format>, an encoding that it uses to encode text strings
-so it can store them in memory. All text strings are in this internal format.
-In fact, text strings are never in any other format!
-
-You shouldn't worry about what this format is, because conversion is
-automatically done when you decode or encode.
-
-=head2 Your new toolkit
-
-Add to your standard heading the following line:
-
- use Encode qw(encode decode);
-
-Or, if you're lazy, just:
-
- use Encode;
-
-=head2 I/O flow (the actual 5 minute tutorial)
-
-The typical input/output flow of a program is:
-
- 1. Receive and decode
- 2. Process
- 3. Encode and output
-
-If your input is binary, and is supposed to remain binary, you shouldn't decode
-it to a text string, of course. But in all other cases, you should decode it.
-
-Decoding can't happen reliably if you don't know how the data was encoded. If
-you get to choose, it's a good idea to standardize on UTF-8.
-
- my $foo = decode('UTF-8', get 'http://example.com/');
- my $bar = decode('ISO-8859-1', readline STDIN);
- my $xyzzy = decode('Windows-1251', $cgi->param('foo'));
-
-Processing happens as you knew before. The only difference is that you're now
-using characters instead of bytes. That's very useful if you use things like
-C<substr>, or C<length>.
-
-It's important to realize that there are no bytes in a text string. Of course,
-Perl has its internal encoding to store the string in memory, but ignore that.
-If you have to do anything with the number of bytes, it's probably best to move
-that part to step 3, just after you've encoded the string. Then you know
-exactly how many bytes it will be in the destination string.
-
-The syntax for encoding text strings to binary strings is as simple as decoding:
-
- $body = encode('UTF-8', $body);
-
-If you needed to know the length of the string in bytes, now's the perfect time
-for that. Because C<$body> is now a byte string, C<length> will report the
-number of bytes, instead of the number of characters. The number of
-characters is no longer known, because characters only exist in text strings.
-
- my $byte_count = length $body;
-
-And if the protocol you're using supports a way of letting the recipient know
-which character encoding you used, please help the receiving end by using that
-feature! For example, E-mail and HTTP support MIME headers, so you can use the
-C<Content-Type> header. They can also have C<Content-Length> to indicate the
-number of I<bytes>, which is always a good idea to supply if the number is
-known.
-
- "Content-Type: text/plain; charset=UTF-8",
- "Content-Length: $byte_count"
-
-=head1 SUMMARY
-
-Decode everything you receive, encode everything you send out. (If it's text
-data.)
-
-=head1 Q and A (or FAQ)
-
-After reading this document, you ought to read L<perlunifaq> too.
-
-=head1 ACKNOWLEDGEMENTS
-
-Thanks to Johan Vromans from Squirrel Consultancy. His UTF-8 rants during the
-Amsterdam Perl Mongers meetings got me interested and determined to find out
-how to use character encodings in Perl in ways that don't break easily.
-
-Thanks to Gerard Goossen from TTY. His presentation "UTF-8 in the wild" (Dutch
-Perl Workshop 2006) inspired me to publish my thoughts and write this tutorial.
-
-Thanks to the people who asked about this kind of stuff in several Perl IRC
-channels, and have constantly reminded me that a simpler explanation was
-needed.
-
-Thanks to the people who reviewed this document for me, before it went public.
-They are: Benjamin Smith, Jan-Pieter Cornet, Johan Vromans, Lukas Mai, Nathan
-Gray.
-
-=head1 AUTHOR
-
-Juerd Waalboer <#####@juerd.nl>
-
-=head1 SEE ALSO
-
-L<perlunifaq>, L<perlunicode>, L<perluniintro>, L<Encode>
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlutil.pod b/Master/tlpkg/tlperl/lib/pods/perlutil.pod
deleted file mode 100644
index 040f51d5f65..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlutil.pod
+++ /dev/null
@@ -1,311 +0,0 @@
-=head1 NAME
-
-perlutil - utilities packaged with the Perl distribution
-
-=head1 DESCRIPTION
-
-Along with the Perl interpreter itself, the Perl distribution installs a
-range of utilities on your system. There are also several utilities
-which are used by the Perl distribution itself as part of the install
-process. This document exists to list all of these utilities, explain
-what they are for and provide pointers to each module's documentation,
-if appropriate.
-
-=head1 LIST OF UTILITIES
-
-=head2 Documentation
-
-=over 3
-
-=item L<perldoc|perldoc>
-
-The main interface to Perl's documentation is C<perldoc>, although
-if you're reading this, it's more than likely that you've already found
-it. F<perldoc> will extract and format the documentation from any file
-in the current directory, any Perl module installed on the system, or
-any of the standard documentation pages, such as this one. Use
-C<perldoc E<lt>nameE<gt>> to get information on any of the utilities
-described in this document.
-
-=item L<pod2man|pod2man> and L<pod2text|pod2text>
-
-If it's run from a terminal, F<perldoc> will usually call F<pod2man> to
-translate POD (Plain Old Documentation - see L<perlpod> for an
-explanation) into a manpage, and then run F<man> to display it; if
-F<man> isn't available, F<pod2text> will be used instead and the output
-piped through your favourite pager.
-
-=item L<pod2html|pod2html> and L<pod2latex|pod2latex>
-
-As well as these two, there are two other converters: F<pod2html> will
-produce HTML pages from POD, and F<pod2latex>, which produces LaTeX
-files.
-
-=item L<pod2usage|pod2usage>
-
-If you just want to know how to use the utilities described here,
-F<pod2usage> will just extract the "USAGE" section; some of
-the utilities will automatically call F<pod2usage> on themselves when
-you call them with C<-help>.
-
-=item L<podselect|podselect>
-
-F<pod2usage> is a special case of F<podselect>, a utility to extract
-named sections from documents written in POD. For instance, while
-utilities have "USAGE" sections, Perl modules usually have "SYNOPSIS"
-sections: C<podselect -s "SYNOPSIS" ...> will extract this section for
-a given file.
-
-=item L<podchecker|podchecker>
-
-If you're writing your own documentation in POD, the F<podchecker>
-utility will look for errors in your markup.
-
-=item L<splain|splain>
-
-F<splain> is an interface to L<perldiag> - paste in your error message
-to it, and it'll explain it for you.
-
-=item C<roffitall>
-
-The C<roffitall> utility is not installed on your system but lives in
-the F<pod/> directory of your Perl source kit; it converts all the
-documentation from the distribution to F<*roff> format, and produces a
-typeset PostScript or text file of the whole lot.
-
-=back
-
-=head2 Converters
-
-To help you convert legacy programs to Perl, we've included three
-conversion filters:
-
-=over 3
-
-=item L<a2p|a2p>
-
-F<a2p> converts F<awk> scripts to Perl programs; for example, C<a2p -F:>
-on the simple F<awk> script C<{print $2}> will produce a Perl program
-based around this code:
-
- while (<>) {
- ($Fld1,$Fld2) = split(/[:\n]/, $_, -1);
- print $Fld2;
- }
-
-=item L<s2p|s2p> and L<psed>
-
-Similarly, F<s2p> converts F<sed> scripts to Perl programs. F<s2p> run
-on C<s/foo/bar> will produce a Perl program based around this:
-
- while (<>) {
- chomp;
- s/foo/bar/g;
- print if $printit;
- }
-
-When invoked as F<psed>, it behaves as a F<sed> implementation, written in
-Perl.
-
-=item L<find2perl|find2perl>
-
-Finally, F<find2perl> translates C<find> commands to Perl equivalents which
-use the L<File::Find|File::Find> module. As an example,
-C<find2perl . -user root -perm 4000 -print> produces the following callback
-subroutine for C<File::Find>:
-
- sub wanted {
- my ($dev,$ino,$mode,$nlink,$uid,$gid);
- (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_)) &&
- $uid == $uid{'root'}) &&
- (($mode & 0777) == 04000);
- print("$name\n");
- }
-
-=back
-
-As well as these filters for converting other languages, the
-L<pl2pm|pl2pm> utility will help you convert old-style Perl 4 libraries to
-new-style Perl5 modules.
-
-=head2 Administration
-
-=over 3
-
-=item L<config_data|config_data>
-
-Query or change configuration of Perl modules that use Module::Build-based
-configuration files for features and config data.
-
-=item L<libnetcfg|libnetcfg>
-
-To display and change the libnet configuration run the libnetcfg command.
-
-=item L<perlivp>
-
-The F<perlivp> program is set up at Perl source code build time to test
-the Perl version it was built under. It can be used after running C<make
-install> (or your platform's equivalent procedure) to verify that perl
-and its libraries have been installed correctly.
-
-=back
-
-=head2 Development
-
-There are a set of utilities which help you in developing Perl programs,
-and in particular, extending Perl with C.
-
-=over 3
-
-=item L<perlbug|perlbug>
-
-F<perlbug> is the recommended way to report bugs in the perl interpreter
-itself or any of the standard library modules back to the developers;
-please read through the documentation for F<perlbug> thoroughly before
-using it to submit a bug report.
-
-=item L<perlthanks|perlbug>
-
-This program provides an easy way to send a thank-you message back to the
-authors and maintainers of perl. It's just F<perlbug> installed under
-another name.
-
-=item L<h2ph|h2ph>
-
-Back before Perl had the XS system for connecting with C libraries,
-programmers used to get library constants by reading through the C
-header files. You may still see C<require 'syscall.ph'> or similar
-around - the F<.ph> file should be created by running F<h2ph> on the
-corresponding F<.h> file. See the F<h2ph> documentation for more on how
-to convert a whole bunch of header files at once.
-
-=item L<c2ph|c2ph> and L<pstruct|pstruct>
-
-F<c2ph> and F<pstruct>, which are actually the same program but behave
-differently depending on how they are called, provide another way of
-getting at C with Perl - they'll convert C structures and union declarations
-to Perl code. This is deprecated in favour of F<h2xs> these days.
-
-=item L<h2xs|h2xs>
-
-F<h2xs> converts C header files into XS modules, and will try and write
-as much glue between C libraries and Perl modules as it can. It's also
-very useful for creating skeletons of pure Perl modules.
-
-=item L<enc2xs>
-
-F<enc2xs> builds a Perl extension for use by Encode from either
-Unicode Character Mapping files (.ucm) or Tcl Encoding Files (.enc).
-Besides being used internally during the build process of the Encode
-module, you can use F<enc2xs> to add your own encoding to perl.
-No knowledge of XS is necessary.
-
-=item L<xsubpp>
-
-F<xsubpp> is a compiler to convert Perl XS code into C code.
-It is typically run by the makefiles created by L<ExtUtils::MakeMaker>.
-
-F<xsubpp> will compile XS code into C code by embedding the constructs
-necessary to let C functions manipulate Perl values and creates the glue
-necessary to let Perl access those functions.
-
-=item L<prove>
-
-F<prove> is a command-line interface to the test-running functionality
-of F<Test::Harness>. It's an alternative to C<make test>.
-
-=item L<corelist>
-
-A command-line front-end to C<Module::CoreList>, to query what modules
-were shipped with given versions of perl.
-
-=back
-
-=head2 General tools
-
-A few general-purpose tools are shipped with perl, mostly because they
-came along modules included in the perl distribution.
-
-=over 3
-
-=item L<piconv>
-
-B<piconv> is a Perl version of B<iconv>, a character encoding converter
-widely available for various Unixen today. This script was primarily a
-technology demonstrator for Perl 5.8.0, but you can use piconv in the
-place of iconv for virtually any case.
-
-=item L<ptar>
-
-F<ptar> is a tar-like program, written in pure Perl.
-
-=item L<ptardiff>
-
-F<ptardiff> is a small utility that produces a diff between an extracted
-archive and an unextracted one. (Note that this utility requires the
-C<Text::Diff> module to function properly; this module isn't distributed
-with perl, but is available from the CPAN.)
-
-=item L<ptargrep>
-
-F<ptargrep> is a utility to apply pattern matching to the contents of files
-in a tar archive.
-
-=item L<shasum>
-
-This utility, that comes with the C<Digest::SHA> module, is used to print
-or verify SHA checksums.
-
-=item L<zipdetails>
-
-L<zipdetails> displays information about the internal record structure of the zip file.
-It is not concerned with displaying any details of the compressed data stored in the zip file.
-
-=back
-
-=head2 Installation
-
-These utilities help manage extra Perl modules that don't come with the perl
-distribution.
-
-=over 3
-
-=item L<cpan>
-
-F<cpan> is a command-line interface to CPAN.pm. It allows you to install
-modules or distributions from CPAN, or just get information about them, and
-a lot more. It is similar to the command line mode of the L<CPAN> module,
-
- perl -MCPAN -e shell
-
-=item L<cpanp>
-
-F<cpanp> is, like F<cpan>, a command-line interface to the CPAN, using
-the C<CPANPLUS> module as a back-end. It can be used interactively or
-imperatively.
-
-=item L<cpan2dist>
-
-F<cpan2dist> is a tool to create distributions (or packages) from CPAN
-modules, then suitable for your package manager of choice. Support for
-specific formats are available from CPAN as C<CPANPLUS::Dist::*> modules.
-
-=item L<instmodsh>
-
-A little interface to ExtUtils::Installed to examine installed modules,
-validate your packlists and even create a tarball from an installed module.
-
-=back
-
-=head1 SEE ALSO
-
-L<perldoc|perldoc>, L<pod2man|pod2man>, L<perlpod>,
-L<pod2html|pod2html>, L<pod2usage|pod2usage>, L<podselect|podselect>,
-L<podchecker|podchecker>, L<splain|splain>, L<perldiag>,
-C<roffitall|roffitall>, L<a2p|a2p>, L<s2p|s2p>, L<find2perl|find2perl>,
-L<File::Find|File::Find>, L<pl2pm|pl2pm>, L<perlbug|perlbug>,
-L<h2ph|h2ph>, L<c2ph|c2ph>, L<h2xs|h2xs>, L<enc2xs>, L<xsubpp>,
-L<cpan>, L<cpanp>, L<cpan2dist>, L<instmodsh>, L<piconv>, L<prove>,
-L<corelist>, L<ptar>, L<ptardiff>, L<shasum>, L<zipdetails>
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perluts.pod b/Master/tlpkg/tlperl/lib/pods/perluts.pod
deleted file mode 100644
index 2025e37ef7a..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perluts.pod
+++ /dev/null
@@ -1,107 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see perlpod manpage) which is
-specially designed to be readable as is.
-
-=head1 NAME
-
-perluts - Perl under UTS
-
-=head1 SYNOPSIS
-
-This document can be read I<as is>: as F<README.uts>, or you
-can read it after you build your package using "man perluts".
-
-The purpose is to help you build Perl for UTS, which, if you
-follow these instructions, should be easy, and result in
-a solidly working installation.
-
-=head1 DESCRIPTION
-
-Perl 5.7.2 (Developmental) or Perl 5.8.x (forthcoming) for UTS
-
-=head1 BUILDING PERL ON UTS
-
-NOTE: Some sites have redefined the way uname works, and if yours
-does this, special steps must be taken so that Configure can
-recognize your system as a UTS system. To see if you are in
-this category, issue the command "uname -a". It should look
-something like:
-
- uts juno 4 4.4 9672 370
-
-At any rate, the first field should be "uts". If this is not
-the case; supposing it is, say telcoUTS, create a script, uts/uname
-(i.e. uname, in the subdirectory "uts" of the main Perl source dir):
- # uname
- /usr/bin/uname "$@" | sed -e 's/^telcoUTS/uts/'
-
-and when you execute Configure, do it as below, except for adding
-PATH=uts:$PATH as a prefix. I.e. do:
-
- PATH=uts:$PATH ./Configure ...
-
-There is no need to do an interactive configure, just type
-
- ./Configure -de [-Dusedevel] [-Doptimize=-g ] 2>&1 | tee Conf.out
-
-"-Dusedevel" may be required to configure Perl 5.7.2 non-interactively.
-Use -Doptimize=-g if you want to run Perl under sdb or gdb, OR
-if you want to be able to use the -D command line flags to perl,
-which are occasionally useful in debugging perl scripts.
-
-In this and the following steps, the "2>&1 | tee XXX.out" records all
-output from the process, which will be useful if anything unexpected
-goes wrong.
-
-Then do the compilation with
-
- make 2>&1 | tee make.out
-
-Finally, test using
-
- make test 2>&1 | tee make-test.out
-
-In the output, the only failures you should see should look like:
-
- lib/Math/BigInt/t/bigfltpm.........Use of uninitialized value ...
- FAILED at test 57
- lib/Math/BigInt/t/bigintc..........ok
- lib/Math/BigInt/t/bigintpm.........FAILED at test 204
- lib/Math/BigInt/t/mbimbf...........Use of uninitialized value ...
- Illegal division by zero at ../lib/Math/BigInt/Calc.pm line 314.
- FAILED at test 71
- lib/Math/Complex...................exp: OVERFLOW
- FAILED at test 250
- lib/Math/Trig......................exp: OVERFLOW
- ok
- lib/Memoize/t/array................ok
- ...
- lib/Net/protoent...................ok
- lib/Net/servent....................FAILED at test 0
-
-This means that everything passes except for some problems in the
-packages "Math::BigInt", "Math::Complex", and "Math::Trig".
-The lib/Net/servent failure seems to be a bug in the test
-program. To confirm this, from the main Perl source dir, do:
-
- LD_LIBRARY_PATH=`pwd` ./perl -Ilib lib/Net/servent.t
-
-and it should output
-
- 1..3
- ok 1
- ok 2
- ok 3
-
-=head1 Installing the built perl on UTS
-
-Run the command "make install"
-
-=head1 AUTHOR
-
- Hal Morris
- UTS Global LLC
- email: hom00@utsglobal.com
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlvar.pod b/Master/tlpkg/tlperl/lib/pods/perlvar.pod
deleted file mode 100644
index c09aea52027..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlvar.pod
+++ /dev/null
@@ -1,2174 +0,0 @@
-=head1 NAME
-
-perlvar - Perl predefined variables
-
-=head1 DESCRIPTION
-
-=head2 The Syntax of Variable Names
-
-Variable names in Perl can have several formats. Usually, they
-must begin with a letter or underscore, in which case they can be
-arbitrarily long (up to an internal limit of 251 characters) and
-may contain letters, digits, underscores, or the special sequence
-C<::> or C<'>. In this case, the part before the last C<::> or
-C<'> is taken to be a I<package qualifier>; see L<perlmod>.
-
-Perl variable names may also be a sequence of digits or a single
-punctuation or control character. These names are all reserved for
-special uses by Perl; for example, the all-digits names are used
-to hold data captured by backreferences after a regular expression
-match. Perl has a special syntax for the single-control-character
-names: It understands C<^X> (caret C<X>) to mean the control-C<X>
-character. For example, the notation C<$^W> (dollar-sign caret
-C<W>) is the scalar variable whose name is the single character
-control-C<W>. This is better than typing a literal control-C<W>
-into your program.
-
-Since Perl 5.6, Perl variable names may be alphanumeric
-strings that begin with control characters (or better yet, a caret).
-These variables must be written in the form C<${^Foo}>; the braces
-are not optional. C<${^Foo}> denotes the scalar variable whose
-name is a control-C<F> followed by two C<o>'s. These variables are
-reserved for future special uses by Perl, except for the ones that
-begin with C<^_> (control-underscore or caret-underscore). No
-control-character name that begins with C<^_> will acquire a special
-meaning in any future version of Perl; such names may therefore be
-used safely in programs. C<$^_> itself, however, I<is> reserved.
-
-Perl identifiers that begin with digits, control characters, or
-punctuation characters are exempt from the effects of the C<package>
-declaration and are always forced to be in package C<main>; they are
-also exempt from C<strict 'vars'> errors. A few other names are also
-exempt in these ways:
-
- ENV STDIN
- INC STDOUT
- ARGV STDERR
- ARGVOUT
- SIG
-
-In particular, the special C<${^_XYZ}> variables are always taken
-to be in package C<main>, regardless of any C<package> declarations
-presently in scope.
-
-=head1 SPECIAL VARIABLES
-
-The following names have special meaning to Perl. Most punctuation
-names have reasonable mnemonics, or analogs in the shells.
-Nevertheless, if you wish to use long variable names, you need only say:
-
- use English;
-
-at the top of your program. This aliases all the short names to the long
-names in the current package. Some even have medium names, generally
-borrowed from B<awk>. To avoid a performance hit, if you don't need the
-C<$PREMATCH>, C<$MATCH>, or C<$POSTMATCH> it's best to use the C<English>
-module without them:
-
- use English '-no_match_vars';
-
-Before you continue, note the sort order for variables. In general, we
-first list the variables in case-insensitive, almost-lexigraphical
-order (ignoring the C<{> or C<^> preceding words, as in C<${^UNICODE}>
-or C<$^T>), although C<$_> and C<@_> move up to the top of the pile.
-For variables with the same identifier, we list it in order of scalar,
-array, hash, and bareword.
-
-=head2 General Variables
-
-=over 8
-
-=item $ARG
-
-=item $_
-X<$_> X<$ARG>
-
-The default input and pattern-searching space. The following pairs are
-equivalent:
-
- while (<>) {...} # equivalent only in while!
- while (defined($_ = <>)) {...}
-
- /^Subject:/
- $_ =~ /^Subject:/
-
- tr/a-z/A-Z/
- $_ =~ tr/a-z/A-Z/
-
- chomp
- chomp($_)
-
-Here are the places where Perl will assume C<$_> even if you don't use it:
-
-=over 3
-
-=item *
-
-The following functions use C<$_> as a default argument:
-
-abs, alarm, chomp, chop, chr, chroot,
-cos, defined, eval, evalbytes, exp, glob,
-hex, int, lc, lcfirst, length, log, lstat, mkdir, oct, ord, pos, print,
-quotemeta, readlink, readpipe, ref, require, reverse (in scalar context only),
-rmdir, sin, split (on its second argument), sqrt, stat, study, uc, ucfirst,
-unlink, unpack.
-
-=item *
-
-All file tests (C<-f>, C<-d>) except for C<-t>, which defaults to STDIN.
-See L<perlfunc/-X>
-
-=item *
-
-The pattern matching operations C<m//>, C<s///> and C<tr///> (aka C<y///>)
-when used without an C<=~> operator.
-
-=item *
-
-The default iterator variable in a C<foreach> loop if no other
-variable is supplied.
-
-=item *
-
-The implicit iterator variable in the C<grep()> and C<map()> functions.
-
-=item *
-
-The implicit variable of C<given()>.
-
-=item *
-
-The default place to put an input record when a C<< <FH> >>
-operation's result is tested by itself as the sole criterion of a C<while>
-test. Outside a C<while> test, this will not happen.
-
-=back
-
-As C<$_> is a global variable, this may lead in some cases to unwanted
-side-effects. As of perl 5.10, you can now use a lexical version of
-C<$_> by declaring it in a file or in a block with C<my>. Moreover,
-declaring C<our $_> restores the global C<$_> in the current scope.
-
-Mnemonic: underline is understood in certain operations.
-
-=item @ARG
-
-=item @_
-X<@_> X<@ARG>
-
-Within a subroutine the array C<@_> contains the parameters passed to
-that subroutine. Inside a subroutine, C<@_> is the default array for
-the array operators C<push>, C<pop>, C<shift>, and C<unshift>.
-
-See L<perlsub>.
-
-=item $LIST_SEPARATOR
-
-=item $"
-X<$"> X<$LIST_SEPARATOR>
-
-When an array or an array slice is interpolated into a double-quoted
-string or a similar context such as C</.../>, its elements are
-separated by this value. Default is a space. For example, this:
-
- print "The array is: @array\n";
-
-is equivalent to this:
-
- print "The array is: " . join($", @array) . "\n";
-
-Mnemonic: works in double-quoted context.
-
-=item $PROCESS_ID
-
-=item $PID
-
-=item $$
-X<$$> X<$PID> X<$PROCESS_ID>
-
-The process number of the Perl running this script. Though you I<can> set
-this variable, doing so is generally discouraged, although it can be
-invaluable for some testing purposes. It will be reset automatically
-across C<fork()> calls.
-
-Note for Linux and Debian GNU/kFreeBSD users: Before Perl v5.16.0 perl
-would emulate POSIX semantics on Linux systems using LinuxThreads, a
-partial implementation of POSIX Threads that has since been superseded
-by the Native POSIX Thread Library (NPTL).
-
-LinuxThreads is now obsolete on Linux, and and caching C<getpid()>
-like this made embedding perl unnecessarily complex (since you'd have
-to manually update the value of $$), so now C<$$> and C<getppid()>
-will always return the same values as the underlying C library.
-
-Debian GNU/kFreeBSD systems also used LinuxThreads up until and
-including the 6.0 release, but after that moved to FreeBSD thread
-semantics, which are POSIX-like.
-
-To see if your system is affected by this discrepancy check if
-C<getconf GNU_LIBPTHREAD_VERSION | grep -q NPTL> returns a false
-value. NTPL threads preserve the POSIX semantics.
-
-Mnemonic: same as shells.
-
-=item $PROGRAM_NAME
-
-=item $0
-X<$0> X<$PROGRAM_NAME>
-
-Contains the name of the program being executed.
-
-On some (but not all) operating systems assigning to C<$0> modifies
-the argument area that the C<ps> program sees. On some platforms you
-may have to use special C<ps> options or a different C<ps> to see the
-changes. Modifying the C<$0> is more useful as a way of indicating the
-current program state than it is for hiding the program you're
-running.
-
-Note that there are platform-specific limitations on the maximum
-length of C<$0>. In the most extreme case it may be limited to the
-space occupied by the original C<$0>.
-
-In some platforms there may be arbitrary amount of padding, for
-example space characters, after the modified name as shown by C<ps>.
-In some platforms this padding may extend all the way to the original
-length of the argument area, no matter what you do (this is the case
-for example with Linux 2.2).
-
-Note for BSD users: setting C<$0> does not completely remove "perl"
-from the ps(1) output. For example, setting C<$0> to C<"foobar"> may
-result in C<"perl: foobar (perl)"> (whether both the C<"perl: "> prefix
-and the " (perl)" suffix are shown depends on your exact BSD variant
-and version). This is an operating system feature, Perl cannot help it.
-
-In multithreaded scripts Perl coordinates the threads so that any
-thread may modify its copy of the C<$0> and the change becomes visible
-to ps(1) (assuming the operating system plays along). Note that
-the view of C<$0> the other threads have will not change since they
-have their own copies of it.
-
-If the program has been given to perl via the switches C<-e> or C<-E>,
-C<$0> will contain the string C<"-e">.
-
-On Linux as of perl 5.14 the legacy process name will be set with
-C<prctl(2)>, in addition to altering the POSIX name via C<argv[0]> as
-perl has done since version 4.000. Now system utilities that read the
-legacy process name such as ps, top and killall will recognize the
-name you set when assigning to C<$0>. The string you supply will be
-cut off at 16 bytes, this is a limitation imposed by Linux.
-
-Mnemonic: same as B<sh> and B<ksh>.
-
-=item $REAL_GROUP_ID
-
-=item $GID
-
-=item $(
-X<$(> X<$GID> X<$REAL_GROUP_ID>
-
-The real gid of this process. If you are on a machine that supports
-membership in multiple groups simultaneously, gives a space separated
-list of groups you are in. The first number is the one returned by
-C<getgid()>, and the subsequent ones by C<getgroups()>, one of which may be
-the same as the first number.
-
-However, a value assigned to C<$(> must be a single number used to
-set the real gid. So the value given by C<$(> should I<not> be assigned
-back to C<$(> without being forced numeric, such as by adding zero. Note
-that this is different to the effective gid (C<$)>) which does take a
-list.
-
-You can change both the real gid and the effective gid at the same
-time by using C<POSIX::setgid()>. Changes
-to C<$(> require a check to C<$!>
-to detect any possible errors after an attempted change.
-
-Mnemonic: parentheses are used to I<group> things. The real gid is the
-group you I<left>, if you're running setgid.
-
-=item $EFFECTIVE_GROUP_ID
-
-=item $EGID
-
-=item $)
-X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID>
-
-The effective gid of this process. If you are on a machine that
-supports membership in multiple groups simultaneously, gives a space
-separated list of groups you are in. The first number is the one
-returned by C<getegid()>, and the subsequent ones by C<getgroups()>,
-one of which may be the same as the first number.
-
-Similarly, a value assigned to C<$)> must also be a space-separated
-list of numbers. The first number sets the effective gid, and
-the rest (if any) are passed to C<setgroups()>. To get the effect of an
-empty list for C<setgroups()>, just repeat the new effective gid; that is,
-to force an effective gid of 5 and an effectively empty C<setgroups()>
-list, say C< $) = "5 5" >.
-
-You can change both the effective gid and the real gid at the same
-time by using C<POSIX::setgid()> (use only a single numeric argument).
-Changes to C<$)> require a check to C<$!> to detect any possible errors
-after an attempted change.
-
-C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on
-machines that support the corresponding I<set[re][ug]id()> routine. C<$(>
-and C<$)> can be swapped only on machines supporting C<setregid()>.
-
-Mnemonic: parentheses are used to I<group> things. The effective gid
-is the group that's I<right> for you, if you're running setgid.
-
-=item $REAL_USER_ID
-
-=item $UID
-
-=item $<
-X<< $< >> X<$UID> X<$REAL_USER_ID>
-
-The real uid of this process. You can change both the real uid and the
-effective uid at the same time by using C<POSIX::setuid()>. Since
-changes to C<< $< >> require a system call, check C<$!> after a change
-attempt to detect any possible errors.
-
-Mnemonic: it's the uid you came I<from>, if you're running setuid.
-
-=item $EFFECTIVE_USER_ID
-
-=item $EUID
-
-=item $>
-X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID>
-
-The effective uid of this process. For example:
-
- $< = $>; # set real to effective uid
- ($<,$>) = ($>,$<); # swap real and effective uids
-
-You can change both the effective uid and the real uid at the same
-time by using C<POSIX::setuid()>. Changes to C<< $> >> require a check
-to C<$!> to detect any possible errors after an attempted change.
-
-C<< $< >> and C<< $> >> can be swapped only on machines
-supporting C<setreuid()>.
-
-Mnemonic: it's the uid you went I<to>, if you're running setuid.
-
-=item $SUBSCRIPT_SEPARATOR
-
-=item $SUBSEP
-
-=item $;
-X<$;> X<$SUBSEP> X<SUBSCRIPT_SEPARATOR>
-
-The subscript separator for multidimensional array emulation. If you
-refer to a hash element as
-
- $foo{$a,$b,$c}
-
-it really means
-
- $foo{join($;, $a, $b, $c)}
-
-But don't put
-
- @foo{$a,$b,$c} # a slice--note the @
-
-which means
-
- ($foo{$a},$foo{$b},$foo{$c})
-
-Default is "\034", the same as SUBSEP in B<awk>. If your keys contain
-binary data there might not be any safe value for C<$;>.
-
-Consider using "real" multidimensional arrays as described
-in L<perllol>.
-
-Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon.
-
-=item $a
-
-=item $b
-X<$a> X<$b>
-
-Special package variables when using C<sort()>, see L<perlfunc/sort>.
-Because of this specialness C<$a> and C<$b> don't need to be declared
-(using C<use vars>, or C<our()>) even when using the C<strict 'vars'>
-pragma. Don't lexicalize them with C<my $a> or C<my $b> if you want to
-be able to use them in the C<sort()> comparison block or function.
-
-=item %ENV
-X<%ENV>
-
-The hash C<%ENV> contains your current environment. Setting a
-value in C<ENV> changes the environment for any child processes
-you subsequently C<fork()> off.
-
-=item $SYSTEM_FD_MAX
-
-=item $^F
-X<$^F> X<$SYSTEM_FD_MAX>
-
-The maximum system file descriptor, ordinarily 2. System file
-descriptors are passed to C<exec()>ed processes, while higher file
-descriptors are not. Also, during an
-C<open()>, system file descriptors are
-preserved even if the C<open()> fails (ordinary file descriptors are
-closed before the C<open()> is attempted). The close-on-exec
-status of a file descriptor will be decided according to the value of
-C<$^F> when the corresponding file, pipe, or socket was opened, not the
-time of the C<exec()>.
-
-=item @F
-X<@F>
-
-The array C<@F> contains the fields of each line read in when autosplit
-mode is turned on. See L<perlrun> for the B<-a> switch. This array
-is package-specific, and must be declared or given a full package name
-if not in package main when running under C<strict 'vars'>.
-
-=item @INC
-X<@INC>
-
-The array C<@INC> contains the list of places that the C<do EXPR>,
-C<require>, or C<use> constructs look for their library files. It
-initially consists of the arguments to any B<-I> command-line
-switches, followed by the default Perl library, probably
-F</usr/local/lib/perl>, followed by ".", to represent the current
-directory. ("." will not be appended if taint checks are enabled,
-either by C<-T> or by C<-t>.) If you need to modify this at runtime,
-you should use the C<use lib> pragma to get the machine-dependent
-library properly loaded also:
-
- use lib '/mypath/libdir/';
- use SomeMod;
-
-You can also insert hooks into the file inclusion system by putting Perl
-code directly into C<@INC>. Those hooks may be subroutine references,
-array references or blessed objects. See L<perlfunc/require> for details.
-
-=item %INC
-X<%INC>
-
-The hash C<%INC> contains entries for each filename included via the
-C<do>, C<require>, or C<use> operators. The key is the filename
-you specified (with module names converted to pathnames), and the
-value is the location of the file found. The C<require>
-operator uses this hash to determine whether a particular file has
-already been included.
-
-If the file was loaded via a hook (e.g. a subroutine reference, see
-L<perlfunc/require> for a description of these hooks), this hook is
-by default inserted into C<%INC> in place of a filename. Note, however,
-that the hook may have set the C<%INC> entry by itself to provide some more
-specific info.
-
-=item $INPLACE_EDIT
-
-=item $^I
-X<$^I> X<$INPLACE_EDIT>
-
-The current value of the inplace-edit extension. Use C<undef> to disable
-inplace editing.
-
-Mnemonic: value of B<-i> switch.
-
-=item $^M
-X<$^M>
-
-By default, running out of memory is an untrappable, fatal error.
-However, if suitably built, Perl can use the contents of C<$^M>
-as an emergency memory pool after C<die()>ing. Suppose that your Perl
-were compiled with C<-DPERL_EMERGENCY_SBRK> and used Perl's malloc.
-Then
-
- $^M = 'a' x (1 << 16);
-
-would allocate a 64K buffer for use in an emergency. See the
-F<INSTALL> file in the Perl distribution for information on how to
-add custom C compilation flags when compiling perl. To discourage casual
-use of this advanced feature, there is no L<English|English> long name for
-this variable.
-
-This variable was added in Perl 5.004.
-
-=item $OSNAME
-
-=item $^O
-X<$^O> X<$OSNAME>
-
-The name of the operating system under which this copy of Perl was
-built, as determined during the configuration process. For examples
-see L<perlport/PLATFORMS>.
-
-The value is identical to C<$Config{'osname'}>. See also L<Config>
-and the B<-V> command-line switch documented in L<perlrun>.
-
-In Windows platforms, C<$^O> is not very helpful: since it is always
-C<MSWin32>, it doesn't tell the difference between
-95/98/ME/NT/2000/XP/CE/.NET. Use C<Win32::GetOSName()> or
-Win32::GetOSVersion() (see L<Win32> and L<perlport>) to distinguish
-between the variants.
-
-This variable was added in Perl 5.003.
-
-=item %SIG
-X<%SIG>
-
-The hash C<%SIG> contains signal handlers for signals. For example:
-
- sub handler { # 1st argument is signal name
- my($sig) = @_;
- print "Caught a SIG$sig--shutting down\n";
- close(LOG);
- exit(0);
- }
-
- $SIG{'INT'} = \&handler;
- $SIG{'QUIT'} = \&handler;
- ...
- $SIG{'INT'} = 'DEFAULT'; # restore default action
- $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT
-
-Using a value of C<'IGNORE'> usually has the effect of ignoring the
-signal, except for the C<CHLD> signal. See L<perlipc> for more about
-this special case.
-
-Here are some other examples:
-
- $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not
- # recommended)
- $SIG{"PIPE"} = \&Plumber; # just fine; assume current
- # Plumber
- $SIG{"PIPE"} = *Plumber; # somewhat esoteric
- $SIG{"PIPE"} = Plumber(); # oops, what did Plumber()
- # return??
-
-Be sure not to use a bareword as the name of a signal handler,
-lest you inadvertently call it.
-
-If your system has the C<sigaction()> function then signal handlers
-are installed using it. This means you get reliable signal handling.
-
-The default delivery policy of signals changed in Perl 5.8.0 from
-immediate (also known as "unsafe") to deferred, also known as "safe
-signals". See L<perlipc> for more information.
-
-Certain internal hooks can be also set using the C<%SIG> hash. The
-routine indicated by C<$SIG{__WARN__}> is called when a warning
-message is about to be printed. The warning message is passed as the
-first argument. The presence of a C<__WARN__> hook causes the
-ordinary printing of warnings to C<STDERR> to be suppressed. You can
-use this to save warnings in a variable, or turn warnings into fatal
-errors, like this:
-
- local $SIG{__WARN__} = sub { die $_[0] };
- eval $proggie;
-
-As the C<'IGNORE'> hook is not supported by C<__WARN__>, you can
-disable warnings using the empty subroutine:
-
- local $SIG{__WARN__} = sub {};
-
-The routine indicated by C<$SIG{__DIE__}> is called when a fatal
-exception is about to be thrown. The error message is passed as the
-first argument. When a C<__DIE__> hook routine returns, the exception
-processing continues as it would have in the absence of the hook,
-unless the hook routine itself exits via a C<goto &sub>, a loop exit,
-or a C<die()>. The C<__DIE__> handler is explicitly disabled during
-the call, so that you can die from a C<__DIE__> handler. Similarly
-for C<__WARN__>.
-
-Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called
-even inside an C<eval()>. Do not use this to rewrite a pending
-exception in C<$@>, or as a bizarre substitute for overriding
-C<CORE::GLOBAL::die()>. This strange action at a distance may be fixed
-in a future release so that C<$SIG{__DIE__}> is only called if your
-program is about to exit, as was the original intent. Any other use is
-deprecated.
-
-C<__DIE__>/C<__WARN__> handlers are very special in one respect: they
-may be called to report (probable) errors found by the parser. In such
-a case the parser may be in inconsistent state, so any attempt to
-evaluate Perl code from such a handler will probably result in a
-segfault. This means that warnings or errors that result from parsing
-Perl should be used with extreme caution, like this:
-
- require Carp if defined $^S;
- Carp::confess("Something wrong") if defined &Carp::confess;
- die "Something wrong, but could not load Carp to give "
- . "backtrace...\n\t"
- . "To see backtrace try starting Perl with -MCarp switch";
-
-Here the first line will load C<Carp> I<unless> it is the parser who
-called the handler. The second line will print backtrace and die if
-C<Carp> was available. The third line will be executed only if C<Carp> was
-not available.
-
-Having to even think about the C<$^S> variable in your exception
-handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented
-invites grievous and difficult to track down errors. Avoid it
-and use an C<END{}> or CORE::GLOBAL::die override instead.
-
-See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and
-L<warnings> for additional information.
-
-=item $BASETIME
-
-=item $^T
-X<$^T> X<$BASETIME>
-
-The time at which the program began running, in seconds since the
-epoch (beginning of 1970). The values returned by the B<-M>, B<-A>,
-and B<-C> filetests are based on this value.
-
-=item $PERL_VERSION
-
-=item $^V
-X<$^V> X<$PERL_VERSION>
-
-The revision, version, and subversion of the Perl interpreter,
-represented as a C<version> object.
-
-This variable first appeared in perl 5.6.0; earlier versions of perl
-will see an undefined value. Before perl 5.10.0 C<$^V> was represented
-as a v-string.
-
-C<$^V> can be used to determine whether the Perl interpreter executing
-a script is in the right range of versions. For example:
-
- warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1
-
-To convert C<$^V> into its string representation use C<sprintf()>'s
-C<"%vd"> conversion:
-
- printf "version is v%vd\n", $^V; # Perl's version
-
-See the documentation of C<use VERSION> and C<require VERSION>
-for a convenient way to fail if the running Perl interpreter is too old.
-
-See also C<$]> for an older representation of the Perl version.
-
-This variable was added in Perl 5.6.
-
-Mnemonic: use ^V for Version Control.
-
-=item ${^WIN32_SLOPPY_STAT}
-X<${^WIN32_SLOPPY_STAT}> X<sitecustomize> X<sitecustomize.pl>
-
-If this variable is set to a true value, then C<stat()> on Windows will
-not try to open the file. This means that the link count cannot be
-determined and file attributes may be out of date if additional
-hardlinks to the file exist. On the other hand, not opening the file
-is considerably faster, especially for files on network drives.
-
-This variable could be set in the F<sitecustomize.pl> file to
-configure the local Perl installation to use "sloppy" C<stat()> by
-default. See the documentation for B<-f> in
-L<perlrun|perlrun/"Command Switches"> for more information about site
-customization.
-
-This variable was added in Perl 5.10.
-
-=item $EXECUTABLE_NAME
-
-=item $^X
-X<$^X> X<$EXECUTABLE_NAME>
-
-The name used to execute the current copy of Perl, from C's
-C<argv[0]> or (where supported) F</proc/self/exe>.
-
-Depending on the host operating system, the value of C<$^X> may be
-a relative or absolute pathname of the perl program file, or may
-be the string used to invoke perl but not the pathname of the
-perl program file. Also, most operating systems permit invoking
-programs that are not in the PATH environment variable, so there
-is no guarantee that the value of C<$^X> is in PATH. For VMS, the
-value may or may not include a version number.
-
-You usually can use the value of C<$^X> to re-invoke an independent
-copy of the same perl that is currently running, e.g.,
-
- @first_run = `$^X -le "print int rand 100 for 1..100"`;
-
-But recall that not all operating systems support forking or
-capturing of the output of commands, so this complex statement
-may not be portable.
-
-It is not safe to use the value of C<$^X> as a path name of a file,
-as some operating systems that have a mandatory suffix on
-executable files do not require use of the suffix when invoking
-a command. To convert the value of C<$^X> to a path name, use the
-following statements:
-
- # Build up a set of file names (not command names).
- use Config;
- my $this_perl = $^X;
- if ($^O ne 'VMS') {
- $this_perl .= $Config{_exe}
- unless $this_perl =~ m/$Config{_exe}$/i;
- }
-
-Because many operating systems permit anyone with read access to
-the Perl program file to make a copy of it, patch the copy, and
-then execute the copy, the security-conscious Perl programmer
-should take care to invoke the installed copy of perl, not the
-copy referenced by C<$^X>. The following statements accomplish
-this goal, and produce a pathname that can be invoked as a
-command or referenced as a file.
-
- use Config;
- my $secure_perl_path = $Config{perlpath};
- if ($^O ne 'VMS') {
- $secure_perl_path .= $Config{_exe}
- unless $secure_perl_path =~ m/$Config{_exe}$/i;
- }
-
-=back
-
-=head2 Variables related to regular expressions
-
-Most of the special variables related to regular expressions are side
-effects. Perl sets these variables when it has a successful match, so
-you should check the match result before using them. For instance:
-
- if( /P(A)TT(ER)N/ ) {
- print "I found $1 and $2\n";
- }
-
-These variables are read-only and dynamically-scoped, unless we note
-otherwise.
-
-The dynamic nature of the regular expression variables means that
-their value is limited to the block that they are in, as demonstrated
-by this bit of code:
-
- my $outer = 'Wallace and Grommit';
- my $inner = 'Mutt and Jeff';
-
- my $pattern = qr/(\S+) and (\S+)/;
-
- sub show_n { print "\$1 is $1; \$2 is $2\n" }
-
- {
- OUTER:
- show_n() if $outer =~ m/$pattern/;
-
- INNER: {
- show_n() if $inner =~ m/$pattern/;
- }
-
- show_n();
- }
-
-The output shows that while in the C<OUTER> block, the values of C<$1>
-and C<$2> are from the match against C<$outer>. Inside the C<INNER>
-block, the values of C<$1> and C<$2> are from the match against
-C<$inner>, but only until the end of the block (i.e. the dynamic
-scope). After the C<INNER> block completes, the values of C<$1> and
-C<$2> return to the values for the match against C<$outer> even though
-we have not made another match:
-
- $1 is Wallace; $2 is Grommit
- $1 is Mutt; $2 is Jeff
- $1 is Wallace; $2 is Grommit
-
-Due to an unfortunate accident of Perl's implementation, C<use
-English> imposes a considerable performance penalty on all regular
-expression matches in a program because it uses the C<$`>, C<$&>, and
-C<$'>, regardless of whether they occur in the scope of C<use
-English>. For that reason, saying C<use English> in libraries is
-strongly discouraged unless you import it without the match variables:
-
- use English '-no_match_vars'
-
-The C<Devel::NYTProf> and C<Devel::FindAmpersand>
-modules can help you find uses of these
-problematic match variables in your code.
-
-Since Perl 5.10, you can use the C</p> match operator flag and the
-C<${^PREMATCH}>, C<${^MATCH}>, and C<${^POSTMATCH}> variables instead
-so you only suffer the performance penalties.
-
-=over 8
-
-=item $<I<digits>> ($1, $2, ...)
-X<$1> X<$2> X<$3>
-
-Contains the subpattern from the corresponding set of capturing
-parentheses from the last successful pattern match, not counting patterns
-matched in nested blocks that have been exited already.
-
-These variables are read-only and dynamically-scoped.
-
-Mnemonic: like \digits.
-
-=item $MATCH
-
-=item $&
-X<$&> X<$MATCH>
-
-The string matched by the last successful pattern match (not counting
-any matches hidden within a BLOCK or C<eval()> enclosed by the current
-BLOCK).
-
-The use of this variable anywhere in a program imposes a considerable
-performance penalty on all regular expression matches. To avoid this
-penalty, you can extract the same substring by using L</@->. Starting
-with Perl 5.10, you can use the C</p> match flag and the C<${^MATCH}>
-variable to do the same thing for particular match operations.
-
-This variable is read-only and dynamically-scoped.
-
-Mnemonic: like C<&> in some editors.
-
-=item ${^MATCH}
-X<${^MATCH}>
-
-This is similar to C<$&> (C<$MATCH>) except that it does not incur the
-performance penalty associated with that variable, and is only guaranteed
-to return a defined value when the pattern was compiled or executed with
-the C</p> modifier.
-
-This variable was added in Perl 5.10.
-
-This variable is read-only and dynamically-scoped.
-
-=item $PREMATCH
-
-=item $`
-X<$`> X<$PREMATCH> X<${^PREMATCH}>
-
-The string preceding whatever was matched by the last successful
-pattern match, not counting any matches hidden within a BLOCK or C<eval>
-enclosed by the current BLOCK.
-
-The use of this variable anywhere in a program imposes a considerable
-performance penalty on all regular expression matches. To avoid this
-penalty, you can extract the same substring by using L</@->. Starting
-with Perl 5.10, you can use the C</p> match flag and the
-C<${^PREMATCH}> variable to do the same thing for particular match
-operations.
-
-This variable is read-only and dynamically-scoped.
-
-Mnemonic: C<`> often precedes a quoted string.
-
-=item ${^PREMATCH}
-X<$`> X<${^PREMATCH}>
-
-This is similar to C<$`> ($PREMATCH) except that it does not incur the
-performance penalty associated with that variable, and is only guaranteed
-to return a defined value when the pattern was compiled or executed with
-the C</p> modifier.
-
-This variable was added in Perl 5.10
-
-This variable is read-only and dynamically-scoped.
-
-=item $POSTMATCH
-
-=item $'
-X<$'> X<$POSTMATCH> X<${^POSTMATCH}> X<@->
-
-The string following whatever was matched by the last successful
-pattern match (not counting any matches hidden within a BLOCK or C<eval()>
-enclosed by the current BLOCK). Example:
-
- local $_ = 'abcdefghi';
- /def/;
- print "$`:$&:$'\n"; # prints abc:def:ghi
-
-The use of this variable anywhere in a program imposes a considerable
-performance penalty on all regular expression matches.
-To avoid this penalty, you can extract the same substring by
-using L</@->. Starting with Perl 5.10, you can use the C</p> match flag
-and the C<${^POSTMATCH}> variable to do the same thing for particular
-match operations.
-
-This variable is read-only and dynamically-scoped.
-
-Mnemonic: C<'> often follows a quoted string.
-
-=item ${^POSTMATCH}
-X<${^POSTMATCH}> X<$'> X<$POSTMATCH>
-
-This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the
-performance penalty associated with that variable, and is only guaranteed
-to return a defined value when the pattern was compiled or executed with
-the C</p> modifier.
-
-This variable was added in Perl 5.10.
-
-This variable is read-only and dynamically-scoped.
-
-=item $LAST_PAREN_MATCH
-
-=item $+
-X<$+> X<$LAST_PAREN_MATCH>
-
-The text matched by the last bracket of the last successful search pattern.
-This is useful if you don't know which one of a set of alternative patterns
-matched. For example:
-
- /Version: (.*)|Revision: (.*)/ && ($rev = $+);
-
-This variable is read-only and dynamically-scoped.
-
-Mnemonic: be positive and forward looking.
-
-=item $LAST_SUBMATCH_RESULT
-
-=item $^N
-X<$^N> X<$LAST_SUBMATCH_RESULT>
-
-The text matched by the used group most-recently closed (i.e. the group
-with the rightmost closing parenthesis) of the last successful search
-pattern.
-
-This is primarily used inside C<(?{...})> blocks for examining text
-recently matched. For example, to effectively capture text to a variable
-(in addition to C<$1>, C<$2>, etc.), replace C<(...)> with
-
- (?:(...)(?{ $var = $^N }))
-
-By setting and then using C<$var> in this way relieves you from having to
-worry about exactly which numbered set of parentheses they are.
-
-This variable was added in Perl 5.8.
-
-Mnemonic: the (possibly) Nested parenthesis that most recently closed.
-
-=item @LAST_MATCH_END
-
-=item @+
-X<@+> X<@LAST_MATCH_END>
-
-This array holds the offsets of the ends of the last successful
-submatches in the currently active dynamic scope. C<$+[0]> is
-the offset into the string of the end of the entire match. This
-is the same value as what the C<pos> function returns when called
-on the variable that was matched against. The I<n>th element
-of this array holds the offset of the I<n>th submatch, so
-C<$+[1]> is the offset past where C<$1> ends, C<$+[2]> the offset
-past where C<$2> ends, and so on. You can use C<$#+> to determine
-how many subgroups were in the last successful match. See the
-examples given for the C<@-> variable.
-
-This variable was added in Perl 5.6.
-
-=item %LAST_PAREN_MATCH
-
-=item %+
-X<%+> X<%LAST_PAREN_MATCH>
-
-Similar to C<@+>, the C<%+> hash allows access to the named capture
-buffers, should they exist, in the last successful match in the
-currently active dynamic scope.
-
-For example, C<$+{foo}> is equivalent to C<$1> after the following match:
-
- 'foo' =~ /(?<foo>foo)/;
-
-The keys of the C<%+> hash list only the names of buffers that have
-captured (and that are thus associated to defined values).
-
-The underlying behaviour of C<%+> is provided by the
-L<Tie::Hash::NamedCapture> module.
-
-B<Note:> C<%-> and C<%+> are tied views into a common internal hash
-associated with the last successful regular expression. Therefore mixing
-iterative access to them via C<each> may have unpredictable results.
-Likewise, if the last successful match changes, then the results may be
-surprising.
-
-This variable was added in Perl 5.10.
-
-This variable is read-only and dynamically-scoped.
-
-=item @LAST_MATCH_START
-
-=item @-
-X<@-> X<@LAST_MATCH_START>
-
-C<$-[0]> is the offset of the start of the last successful match.
-C<$-[>I<n>C<]> is the offset of the start of the substring matched by
-I<n>-th subpattern, or undef if the subpattern did not match.
-
-Thus, after a match against C<$_>, C<$&> coincides with C<substr $_, $-[0],
-$+[0] - $-[0]>. Similarly, $I<n> coincides with C<substr $_, $-[n],
-$+[n] - $-[n]> if C<$-[n]> is defined, and $+ coincides with
-C<substr $_, $-[$#-], $+[$#-] - $-[$#-]>. One can use C<$#-> to find the
-last matched subgroup in the last successful match. Contrast with
-C<$#+>, the number of subgroups in the regular expression. Compare
-with C<@+>.
-
-This array holds the offsets of the beginnings of the last
-successful submatches in the currently active dynamic scope.
-C<$-[0]> is the offset into the string of the beginning of the
-entire match. The I<n>th element of this array holds the offset
-of the I<n>th submatch, so C<$-[1]> is the offset where C<$1>
-begins, C<$-[2]> the offset where C<$2> begins, and so on.
-
-After a match against some variable C<$var>:
-
-=over 5
-
-=item C<$`> is the same as C<substr($var, 0, $-[0])>
-
-=item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])>
-
-=item C<$'> is the same as C<substr($var, $+[0])>
-
-=item C<$1> is the same as C<substr($var, $-[1], $+[1] - $-[1])>
-
-=item C<$2> is the same as C<substr($var, $-[2], $+[2] - $-[2])>
-
-=item C<$3> is the same as C<substr($var, $-[3], $+[3] - $-[3])>
-
-=back
-
-This variable was added in Perl 5.6.
-
-=item %LAST_MATCH_START
-
-=item %-
-X<%-> X<%LAST_MATCH_START>
-
-Similar to C<%+>, this variable allows access to the named capture groups
-in the last successful match in the currently active dynamic scope. To
-each capture group name found in the regular expression, it associates a
-reference to an array containing the list of values captured by all
-buffers with that name (should there be several of them), in the order
-where they appear.
-
-Here's an example:
-
- if ('1234' =~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) {
- foreach my $bufname (sort keys %-) {
- my $ary = $-{$bufname};
- foreach my $idx (0..$#$ary) {
- print "\$-{$bufname}[$idx] : ",
- (defined($ary->[$idx])
- ? "'$ary->[$idx]'"
- : "undef"),
- "\n";
- }
- }
- }
-
-would print out:
-
- $-{A}[0] : '1'
- $-{A}[1] : '3'
- $-{B}[0] : '2'
- $-{B}[1] : '4'
-
-The keys of the C<%-> hash correspond to all buffer names found in
-the regular expression.
-
-The behaviour of C<%-> is implemented via the
-L<Tie::Hash::NamedCapture> module.
-
-B<Note:> C<%-> and C<%+> are tied views into a common internal hash
-associated with the last successful regular expression. Therefore mixing
-iterative access to them via C<each> may have unpredictable results.
-Likewise, if the last successful match changes, then the results may be
-surprising.
-
-This variable was added in Perl 5.10
-
-This variable is read-only and dynamically-scoped.
-
-=item $LAST_REGEXP_CODE_RESULT
-
-=item $^R
-X<$^R> X<$LAST_REGEXP_CODE_RESULT>
-
-The result of evaluation of the last successful C<(?{ code })>
-regular expression assertion (see L<perlre>). May be written to.
-
-This variable was added in Perl 5.005.
-
-=item ${^RE_DEBUG_FLAGS}
-X<${^RE_DEBUG_FLAGS}>
-
-The current value of the regex debugging flags. Set to 0 for no debug output
-even when the C<re 'debug'> module is loaded. See L<re> for details.
-
-This variable was added in Perl 5.10.
-
-=item ${^RE_TRIE_MAXBUF}
-X<${^RE_TRIE_MAXBUF}>
-
-Controls how certain regex optimisations are applied and how much memory they
-utilize. This value by default is 65536 which corresponds to a 512kB
-temporary cache. Set this to a higher value to trade
-memory for speed when matching large alternations. Set
-it to a lower value if you want the optimisations to
-be as conservative of memory as possible but still occur, and set it to a
-negative value to prevent the optimisation and conserve the most memory.
-Under normal situations this variable should be of no interest to you.
-
-This variable was added in Perl 5.10.
-
-=back
-
-=head2 Variables related to filehandles
-
-Variables that depend on the currently selected filehandle may be set
-by calling an appropriate object method on the C<IO::Handle> object,
-although this is less efficient than using the regular built-in
-variables. (Summary lines below for this contain the word HANDLE.)
-First you must say
-
- use IO::Handle;
-
-after which you may use either
-
- method HANDLE EXPR
-
-or more safely,
-
- HANDLE->method(EXPR)
-
-Each method returns the old value of the C<IO::Handle> attribute. The
-methods each take an optional EXPR, which, if supplied, specifies the
-new value for the C<IO::Handle> attribute in question. If not
-supplied, most methods do nothing to the current value--except for
-C<autoflush()>, which will assume a 1 for you, just to be different.
-
-Because loading in the C<IO::Handle> class is an expensive operation,
-you should learn how to use the regular built-in variables.
-
-A few of these variables are considered "read-only". This means that
-if you try to assign to this variable, either directly or indirectly
-through a reference, you'll raise a run-time exception.
-
-You should be very careful when modifying the default values of most
-special variables described in this document. In most cases you want
-to localize these variables before changing them, since if you don't,
-the change may affect other modules which rely on the default values
-of the special variables that you have changed. This is one of the
-correct ways to read the whole file at once:
-
- open my $fh, "<", "foo" or die $!;
- local $/; # enable localized slurp mode
- my $content = <$fh>;
- close $fh;
-
-But the following code is quite bad:
-
- open my $fh, "<", "foo" or die $!;
- undef $/; # enable slurp mode
- my $content = <$fh>;
- close $fh;
-
-since some other module, may want to read data from some file in the
-default "line mode", so if the code we have just presented has been
-executed, the global value of C<$/> is now changed for any other code
-running inside the same Perl interpreter.
-
-Usually when a variable is localized you want to make sure that this
-change affects the shortest scope possible. So unless you are already
-inside some short C<{}> block, you should create one yourself. For
-example:
-
- my $content = '';
- open my $fh, "<", "foo" or die $!;
- {
- local $/;
- $content = <$fh>;
- }
- close $fh;
-
-Here is an example of how your own code can go broken:
-
- for ( 1..3 ){
- $\ = "\r\n";
- nasty_break();
- print "$_";
- }
-
- sub nasty_break {
- $\ = "\f";
- # do something with $_
- }
-
-You probably expect this code to print the equivalent of
-
- "1\r\n2\r\n3\r\n"
-
-but instead you get:
-
- "1\f2\f3\f"
-
-Why? Because C<nasty_break()> modifies C<$\> without localizing it
-first. The value you set in C<nasty_break()> is still there when you
-return. The fix is to add C<local()> so the value doesn't leak out of
-C<nasty_break()>:
-
- local $\ = "\f";
-
-It's easy to notice the problem in such a short example, but in more
-complicated code you are looking for trouble if you don't localize
-changes to the special variables.
-
-=over 8
-
-=item $ARGV
-X<$ARGV>
-
-Contains the name of the current file when reading from C<< <> >>.
-
-=item @ARGV
-X<@ARGV>
-
-The array C<@ARGV> contains the command-line arguments intended for
-the script. C<$#ARGV> is generally the number of arguments minus
-one, because C<$ARGV[0]> is the first argument, I<not> the program's
-command name itself. See L</$0> for the command name.
-
-=item ARGV
-X<ARGV>
-
-The special filehandle that iterates over command-line filenames in
-C<@ARGV>. Usually written as the null filehandle in the angle operator
-C<< <> >>. Note that currently C<ARGV> only has its magical effect
-within the C<< <> >> operator; elsewhere it is just a plain filehandle
-corresponding to the last file opened by C<< <> >>. In particular,
-passing C<\*ARGV> as a parameter to a function that expects a filehandle
-may not cause your function to automatically read the contents of all the
-files in C<@ARGV>.
-
-=item ARGVOUT
-X<ARGVOUT>
-
-The special filehandle that points to the currently open output file
-when doing edit-in-place processing with B<-i>. Useful when you have
-to do a lot of inserting and don't want to keep modifying C<$_>. See
-L<perlrun> for the B<-i> switch.
-
-=item Handle->output_field_separator( EXPR )
-
-=item $OUTPUT_FIELD_SEPARATOR
-
-=item $OFS
-
-=item $,
-X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR>
-
-The output field separator for the print operator. If defined, this
-value is printed between each of print's arguments. Default is C<undef>.
-
-Mnemonic: what is printed when there is a "," in your print statement.
-
-=item HANDLE->input_line_number( EXPR )
-
-=item $INPUT_LINE_NUMBER
-
-=item $NR
-
-=item $.
-X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X<line number>
-
-Current line number for the last filehandle accessed.
-
-Each filehandle in Perl counts the number of lines that have been read
-from it. (Depending on the value of C<$/>, Perl's idea of what
-constitutes a line may not match yours.) When a line is read from a
-filehandle (via C<readline()> or C<< <> >>), or when C<tell()> or
-C<seek()> is called on it, C<$.> becomes an alias to the line counter
-for that filehandle.
-
-You can adjust the counter by assigning to C<$.>, but this will not
-actually move the seek pointer. I<Localizing C<$.> will not localize
-the filehandle's line count>. Instead, it will localize perl's notion
-of which filehandle C<$.> is currently aliased to.
-
-C<$.> is reset when the filehandle is closed, but B<not> when an open
-filehandle is reopened without an intervening C<close()>. For more
-details, see L<perlop/"IE<sol>O Operators">. Because C<< <> >> never does
-an explicit close, line numbers increase across C<ARGV> files (but see
-examples in L<perlfunc/eof>).
-
-You can also use C<< HANDLE->input_line_number(EXPR) >> to access the
-line counter for a given filehandle without having to worry about
-which handle you last accessed.
-
-Mnemonic: many programs use "." to mean the current line number.
-
-=item HANDLE->input_record_separator( EXPR )
-
-=item $INPUT_RECORD_SEPARATOR
-
-=item $RS
-
-=item $/
-X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR>
-
-The input record separator, newline by default. This influences Perl's
-idea of what a "line" is. Works like B<awk>'s RS variable, including
-treating empty lines as a terminator if set to the null string (an
-empty line cannot contain any spaces or tabs). You may set it to a
-multi-character string to match a multi-character terminator, or to
-C<undef> to read through the end of file. Setting it to C<"\n\n">
-means something slightly different than setting to C<"">, if the file
-contains consecutive empty lines. Setting to C<""> will treat two or
-more consecutive empty lines as a single empty line. Setting to
-C<"\n\n"> will blindly assume that the next input character belongs to
-the next paragraph, even if it's a newline.
-
- local $/; # enable "slurp" mode
- local $_ = <FH>; # whole file now here
- s/\n[ \t]+/ /g;
-
-Remember: the value of C<$/> is a string, not a regex. B<awk> has to
-be better for something. :-)
-
-Setting C<$/> to a reference to an integer, scalar containing an
-integer, or scalar that's convertible to an integer will attempt to
-read records instead of lines, with the maximum record size being the
-referenced integer. So this:
-
- local $/ = \32768; # or \"32768", or \$var_containing_32768
- open my $fh, "<", $myfile or die $!;
- local $_ = <$fh>;
-
-will read a record of no more than 32768 bytes from FILE. If you're
-not reading from a record-oriented file (or your OS doesn't have
-record-oriented files), then you'll likely get a full chunk of data
-with every read. If a record is larger than the record size you've
-set, you'll get the record back in pieces. Trying to set the record
-size to zero or less will cause reading in the (rest of the) whole file.
-
-On VMS only, record reads bypass PerlIO layers and any associated
-buffering,so you must not mix record and non-record reads on the
-same filehandle. Record mode mixes with line mode only when the
-same buffering layer is in use for both modes.
-
-If you perform a record read on a FILE with an encoding layer such as
-C<:encoding(latin1)> or C<:utf8>, you may get an invalid string as a
-result, may leave the FILE positioned between characters in the stream
-and may not be reading the number of bytes from the underlying file
-that you specified. This behaviour may change without warning in a
-future version of perl.
-
-See also L<perlport/"Newlines">. Also see L</$.>.
-
-Mnemonic: / delimits line boundaries when quoting poetry.
-
-=item Handle->output_record_separator( EXPR )
-
-=item $OUTPUT_RECORD_SEPARATOR
-
-=item $ORS
-
-=item $\
-X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR>
-
-The output record separator for the print operator. If defined, this
-value is printed after the last of print's arguments. Default is C<undef>.
-
-Mnemonic: you set C<$\> instead of adding "\n" at the end of the print.
-Also, it's just like C<$/>, but it's what you get "back" from Perl.
-
-=item HANDLE->autoflush( EXPR )
-
-=item $OUTPUT_AUTOFLUSH
-
-=item $|
-X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH>
-
-If set to nonzero, forces a flush right away and after every write or
-print on the currently selected output channel. Default is 0
-(regardless of whether the channel is really buffered by the system or
-not; C<$|> tells you only whether you've asked Perl explicitly to
-flush after each write). STDOUT will typically be line buffered if
-output is to the terminal and block buffered otherwise. Setting this
-variable is useful primarily when you are outputting to a pipe or
-socket, such as when you are running a Perl program under B<rsh> and
-want to see the output as it's happening. This has no effect on input
-buffering. See L<perlfunc/getc> for that. See L<perlfunc/select> on
-how to select the output channel. See also L<IO::Handle>.
-
-Mnemonic: when you want your pipes to be piping hot.
-
-=back
-
-=head3 Variables related to formats
-
-The special variables for formats are a subset of those for
-filehandles. See L<perlform> for more information about Perl's
-formats.
-
-=over 8
-
-=item $ACCUMULATOR
-
-=item $^A
-X<$^A> X<$ACCUMULATOR>
-
-The current value of the C<write()> accumulator for C<format()> lines.
-A format contains C<formline()> calls that put their result into
-C<$^A>. After calling its format, C<write()> prints out the contents
-of C<$^A> and empties. So you never really see the contents of C<$^A>
-unless you call C<formline()> yourself and then look at it. See
-L<perlform> and L<perlfunc/"formline PICTURE,LIST">.
-
-=item HANDLE->format_formfeed(EXPR)
-
-=item $FORMAT_FORMFEED
-
-=item $^L
-X<$^L> X<$FORMAT_FORMFEED>
-
-What formats output as a form feed. The default is C<\f>.
-
-=item HANDLE->format_page_number(EXPR)
-
-=item $FORMAT_PAGE_NUMBER
-
-=item $%
-X<$%> X<$FORMAT_PAGE_NUMBER>
-
-The current page number of the currently selected output channel.
-
-Mnemonic: C<%> is page number in B<nroff>.
-
-=item HANDLE->format_lines_left(EXPR)
-
-=item $FORMAT_LINES_LEFT
-
-=item $-
-X<$-> X<$FORMAT_LINES_LEFT>
-
-The number of lines left on the page of the currently selected output
-channel.
-
-Mnemonic: lines_on_page - lines_printed.
-
-=item Handle->format_line_break_characters EXPR
-
-=item $FORMAT_LINE_BREAK_CHARACTERS
-
-=item $:
-X<$:> X<FORMAT_LINE_BREAK_CHARACTERS>
-
-The current set of characters after which a string may be broken to
-fill continuation fields (starting with C<^>) in a format. The default is
-S<" \n-">, to break on a space, newline, or a hyphen.
-
-Mnemonic: a "colon" in poetry is a part of a line.
-
-=item HANDLE->format_lines_per_page(EXPR)
-
-=item $FORMAT_LINES_PER_PAGE
-
-=item $=
-X<$=> X<$FORMAT_LINES_PER_PAGE>
-
-The current page length (printable lines) of the currently selected
-output channel. The default is 60.
-
-Mnemonic: = has horizontal lines.
-
-=item HANDLE->format_top_name(EXPR)
-
-=item $FORMAT_TOP_NAME
-
-=item $^
-X<$^> X<$FORMAT_TOP_NAME>
-
-The name of the current top-of-page format for the currently selected
-output channel. The default is the name of the filehandle with C<_TOP>
-appended. For example, the default format top name for the C<STDOUT>
-filehandle is C<STDOUT_TOP>.
-
-Mnemonic: points to top of page.
-
-=item HANDLE->format_name(EXPR)
-
-=item $FORMAT_NAME
-
-=item $~
-X<$~> X<$FORMAT_NAME>
-
-The name of the current report format for the currently selected
-output channel. The default format name is the same as the filehandle
-name. For example, the default format name for the C<STDOUT>
-filehandle is just C<STDOUT>.
-
-Mnemonic: brother to C<$^>.
-
-=back
-
-=head2 Error Variables
-X<error> X<exception>
-
-The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information
-about different types of error conditions that may appear during
-execution of a Perl program. The variables are shown ordered by
-the "distance" between the subsystem which reported the error and
-the Perl process. They correspond to errors detected by the Perl
-interpreter, C library, operating system, or an external program,
-respectively.
-
-To illustrate the differences between these variables, consider the
-following Perl expression, which uses a single-quoted string. After
-execution of this statement, perl may have set all four special error
-variables:
-
- eval q{
- open my $pipe, "/cdrom/install |" or die $!;
- my @res = <$pipe>;
- close $pipe or die "bad pipe: $?, $!";
- };
-
-When perl executes the C<eval()> expression, it translates the
-C<open()>, C<< <PIPE> >>, and C<close> calls in the C run-time library
-and thence to the operating system kernel. perl sets C<$!> to
-the C library's C<errno> if one of these calls fails.
-
-C<$@> is set if the string to be C<eval>-ed did not compile (this may
-happen if C<open> or C<close> were imported with bad prototypes), or
-if Perl code executed during evaluation C<die()>d. In these cases the
-value of C<$@> is the compile error, or the argument to C<die> (which
-will interpolate C<$!> and C<$?>). (See also L<Fatal>, though.)
-
-Under a few operating systems, C<$^E> may contain a more verbose error
-indicator, such as in this case, "CDROM tray not closed." Systems that
-do not support extended error messages leave C<$^E> the same as C<$!>.
-
-Finally, C<$?> may be set to non-0 value if the external program
-F</cdrom/install> fails. The upper eight bits reflect specific error
-conditions encountered by the program (the program's C<exit()> value).
-The lower eight bits reflect mode of failure, like signal death and
-core dump information. See L<wait(2)> for details. In contrast to
-C<$!> and C<$^E>, which are set only if error condition is detected,
-the variable C<$?> is set on each C<wait> or pipe C<close>,
-overwriting the old value. This is more like C<$@>, which on every
-C<eval()> is always set on failure and cleared on success.
-
-For more details, see the individual descriptions at C<$@>, C<$!>,
-C<$^E>, and C<$?>.
-
-=over 8
-
-=item ${^CHILD_ERROR_NATIVE}
-X<$^CHILD_ERROR_NATIVE>
-
-The native status returned by the last pipe close, backtick (C<``>)
-command, successful call to C<wait()> or C<waitpid()>, or from the
-C<system()> operator. On POSIX-like systems this value can be decoded
-with the WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED,
-WSTOPSIG and WIFCONTINUED functions provided by the L<POSIX> module.
-
-Under VMS this reflects the actual VMS exit status; i.e. it is the
-same as C<$?> when the pragma C<use vmsish 'status'> is in effect.
-
-This variable was added in Perl 5.8.9.
-
-=item $EXTENDED_OS_ERROR
-
-=item $^E
-X<$^E> X<$EXTENDED_OS_ERROR>
-
-Error information specific to the current operating system. At the
-moment, this differs from C<$!> under only VMS, OS/2, and Win32 (and
-for MacPerl). On all other platforms, C<$^E> is always just the same
-as C<$!>.
-
-Under VMS, C<$^E> provides the VMS status value from the last system
-error. This is more specific information about the last system error
-than that provided by C<$!>. This is particularly important when C<$!>
-is set to B<EVMSERR>.
-
-Under OS/2, C<$^E> is set to the error code of the last call to OS/2
-API either via CRT, or directly from perl.
-
-Under Win32, C<$^E> always returns the last error information reported
-by the Win32 call C<GetLastError()> which describes the last error
-from within the Win32 API. Most Win32-specific code will report errors
-via C<$^E>. ANSI C and Unix-like calls set C<errno> and so most
-portable Perl code will report errors via C<$!>.
-
-Caveats mentioned in the description of C<$!> generally apply to
-C<$^E>, also.
-
-This variable was added in Perl 5.003.
-
-Mnemonic: Extra error explanation.
-
-=item $EXCEPTIONS_BEING_CAUGHT
-
-=item $^S
-X<$^S> X<$EXCEPTIONS_BEING_CAUGHT>
-
-Current state of the interpreter.
-
- $^S State
- --------- -------------------
- undef Parsing module/eval
- true (1) Executing an eval
- false (0) Otherwise
-
-The first state may happen in C<$SIG{__DIE__}> and C<$SIG{__WARN__}>
-handlers.
-
-This variable was added in Perl 5.004.
-
-=item $WARNING
-
-=item $^W
-X<$^W> X<$WARNING>
-
-The current value of the warning switch, initially true if B<-w> was
-used, false otherwise, but directly modifiable.
-
-See also L<warnings>.
-
-Mnemonic: related to the B<-w> switch.
-
-=item ${^WARNING_BITS}
-X<${^WARNING_BITS}>
-
-The current set of warning checks enabled by the C<use warnings> pragma.
-It has the same scoping as the C<$^H> and C<%^H> variables. The exact
-values are considered internal to the L<warnings> pragma and may change
-between versions of Perl.
-
-This variable was added in Perl 5.6.
-
-=item $OS_ERROR
-
-=item $ERRNO
-
-=item $!
-X<$!> X<$ERRNO> X<$OS_ERROR>
-
-When referenced, C<$!> retrieves the current value
-of the C C<errno> integer variable.
-If C<$!> is assigned a numerical value, that value is stored in C<errno>.
-When referenced as a string, C<$!> yields the system error string
-corresponding to C<errno>.
-
-Many system or library calls set C<errno> if they fail,
-to indicate the cause of failure. They usually do B<not>
-set C<errno> to zero if they succeed. This means C<errno>,
-hence C<$!>, is meaningful only I<immediately> after a B<failure>:
-
- if (open my $fh, "<", $filename) {
- # Here $! is meaningless.
- ...
- }
- else {
- # ONLY here is $! meaningful.
- ...
- # Already here $! might be meaningless.
- }
- # Since here we might have either success or failure,
- # $! is meaningless.
-
-Here, I<meaningless> means that C<$!> may be unrelated to the outcome
-of the C<open()> operator. Assignment to C<$!> is similarly ephemeral.
-It can be used immediately before invoking the C<die()> operator,
-to set the exit value, or to inspect the system error string
-corresponding to error I<n>, or to restore C<$!> to a meaningful state.
-
-Mnemonic: What just went bang?
-
-=item %OS_ERROR
-
-=item %ERRNO
-
-=item %!
-X<%!> X<%OS_ERROR> X<%ERRNO>
-
-Each element of C<%!> has a true value only if C<$!> is set to that
-value. For example, C<$!{ENOENT}> is true if and only if the current
-value of C<$!> is C<ENOENT>; that is, if the most recent error was "No
-such file or directory" (or its moral equivalent: not all operating
-systems give that exact error, and certainly not all languages). To
-check if a particular key is meaningful on your system, use C<exists
-$!{the_key}>; for a list of legal keys, use C<keys %!>. See L<Errno>
-for more information, and also see L</$!>.
-
-This variable was added in Perl 5.005.
-
-=item $CHILD_ERROR
-
-=item $?
-X<$?> X<$CHILD_ERROR>
-
-The status returned by the last pipe close, backtick (C<``>) command,
-successful call to C<wait()> or C<waitpid()>, or from the C<system()>
-operator. This is just the 16-bit status word returned by the
-traditional Unix C<wait()> system call (or else is made up to look
-like it). Thus, the exit value of the subprocess is really (C<<< $? >>
-8 >>>), and C<$? & 127> gives which signal, if any, the process died
-from, and C<$? & 128> reports whether there was a core dump.
-
-Additionally, if the C<h_errno> variable is supported in C, its value
-is returned via C<$?> if any C<gethost*()> function fails.
-
-If you have installed a signal handler for C<SIGCHLD>, the
-value of C<$?> will usually be wrong outside that handler.
-
-Inside an C<END> subroutine C<$?> contains the value that is going to be
-given to C<exit()>. You can modify C<$?> in an C<END> subroutine to
-change the exit status of your program. For example:
-
- END {
- $? = 1 if $? == 255; # die would make it 255
- }
-
-Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the
-actual VMS exit status, instead of the default emulation of POSIX
-status; see L<perlvms/$?> for details.
-
-Mnemonic: similar to B<sh> and B<ksh>.
-
-=item $EVAL_ERROR
-
-=item $@
-X<$@> X<$EVAL_ERROR>
-
-The Perl syntax error message from the
-last C<eval()> operator. If C<$@> is
-the null string, the last C<eval()> parsed and executed correctly
-(although the operations you invoked may have failed in the normal
-fashion).
-
-Warning messages are not collected in this variable. You can, however,
-set up a routine to process warnings by setting C<$SIG{__WARN__}> as
-described in L</%SIG>.
-
-Mnemonic: Where was the syntax error "at"?
-
-=back
-
-=head2 Variables related to the interpreter state
-
-These variables provide information about the current interpreter state.
-
-=over 8
-
-=item $COMPILING
-
-=item $^C
-X<$^C> X<$COMPILING>
-
-The current value of the flag associated with the B<-c> switch.
-Mainly of use with B<-MO=...> to allow code to alter its behavior
-when being compiled, such as for example to C<AUTOLOAD> at compile
-time rather than normal, deferred loading. Setting
-C<$^C = 1> is similar to calling C<B::minus_c>.
-
-This variable was added in Perl 5.6.
-
-=item $DEBUGGING
-
-=item $^D
-X<$^D> X<$DEBUGGING>
-
-The current value of the debugging flags. May be read or set. Like its
-command-line equivalent, you can use numeric or symbolic values, eg
-C<$^D = 10> or C<$^D = "st">.
-
-Mnemonic: value of B<-D> switch.
-
-=item ${^ENCODING}
-X<${^ENCODING}>
-
-The I<object reference> to the C<Encode> object that is used to convert
-the source code to Unicode. Thanks to this variable your Perl script
-does not have to be written in UTF-8. Default is I<undef>. The direct
-manipulation of this variable is highly discouraged.
-
-This variable was added in Perl 5.8.2.
-
-=item ${^GLOBAL_PHASE}
-X<${^GLOBAL_PHASE}>
-
-The current phase of the perl interpreter.
-
-Possible values are:
-
-=over 8
-
-=item CONSTRUCT
-
-The C<PerlInterpreter*> is being constructed via C<perl_construct>. This
-value is mostly there for completeness and for use via the
-underlying C variable C<PL_phase>. It's not really possible for Perl
-code to be executed unless construction of the interpreter is
-finished.
-
-=item START
-
-This is the global compile-time. That includes, basically, every
-C<BEGIN> block executed directly or indirectly from during the
-compile-time of the top-level program.
-
-This phase is not called "BEGIN" to avoid confusion with
-C<BEGIN>-blocks, as those are executed during compile-time of any
-compilation unit, not just the top-level program. A new, localised
-compile-time entered at run-time, for example by constructs as
-C<eval "use SomeModule"> are not global interpreter phases, and
-therefore aren't reflected by C<${^GLOBAL_PHASE}>.
-
-=item CHECK
-
-Execution of any C<CHECK> blocks.
-
-=item INIT
-
-Similar to "CHECK", but for C<INIT>-blocks, not C<CHECK> blocks.
-
-=item RUN
-
-The main run-time, i.e. the execution of C<PL_main_root>.
-
-=item END
-
-Execution of any C<END> blocks.
-
-=item DESTRUCT
-
-Global destruction.
-
-=back
-
-Also note that there's no value for UNITCHECK-blocks. That's because
-those are run for each compilation unit individually, and therefore is
-not a global interpreter phase.
-
-Not every program has to go through each of the possible phases, but
-transition from one phase to another can only happen in the order
-described in the above list.
-
-An example of all of the phases Perl code can see:
-
- BEGIN { print "compile-time: ${^GLOBAL_PHASE}\n" }
-
- INIT { print "init-time: ${^GLOBAL_PHASE}\n" }
-
- CHECK { print "check-time: ${^GLOBAL_PHASE}\n" }
-
- {
- package Print::Phase;
-
- sub new {
- my ($class, $time) = @_;
- return bless \$time, $class;
- }
-
- sub DESTROY {
- my $self = shift;
- print "$$self: ${^GLOBAL_PHASE}\n";
- }
- }
-
- print "run-time: ${^GLOBAL_PHASE}\n";
-
- my $runtime = Print::Phase->new(
- "lexical variables are garbage collected before END"
- );
-
- END { print "end-time: ${^GLOBAL_PHASE}\n" }
-
- our $destruct = Print::Phase->new(
- "package variables are garbage collected after END"
- );
-
-This will print out
-
- compile-time: START
- check-time: CHECK
- init-time: INIT
- run-time: RUN
- lexical variables are garbage collected before END: RUN
- end-time: END
- package variables are garbage collected after END: DESTRUCT
-
-This variable was added in Perl 5.14.0.
-
-=item $^H
-X<$^H>
-
-WARNING: This variable is strictly for
-internal use only. Its availability,
-behavior, and contents are subject to change without notice.
-
-This variable contains compile-time hints for the Perl interpreter. At the
-end of compilation of a BLOCK the value of this variable is restored to the
-value when the interpreter started to compile the BLOCK.
-
-When perl begins to parse any block construct that provides a lexical scope
-(e.g., eval body, required file, subroutine body, loop body, or conditional
-block), the existing value of C<$^H> is saved, but its value is left unchanged.
-When the compilation of the block is completed, it regains the saved value.
-Between the points where its value is saved and restored, code that
-executes within BEGIN blocks is free to change the value of C<$^H>.
-
-This behavior provides the semantic of lexical scoping, and is used in,
-for instance, the C<use strict> pragma.
-
-The contents should be an integer; different bits of it are used for
-different pragmatic flags. Here's an example:
-
- sub add_100 { $^H |= 0x100 }
-
- sub foo {
- BEGIN { add_100() }
- bar->baz($boon);
- }
-
-Consider what happens during execution of the BEGIN block. At this point
-the BEGIN block has already been compiled, but the body of C<foo()> is still
-being compiled. The new value of C<$^H>
-will therefore be visible only while
-the body of C<foo()> is being compiled.
-
-Substitution of C<BEGIN { add_100() }> block with:
-
- BEGIN { require strict; strict->import('vars') }
-
-demonstrates how C<use strict 'vars'> is implemented. Here's a conditional
-version of the same lexical pragma:
-
- BEGIN {
- require strict; strict->import('vars') if $condition
- }
-
-This variable was added in Perl 5.003.
-
-=item %^H
-X<%^H>
-
-The C<%^H> hash provides the same scoping semantic as C<$^H>. This makes
-it useful for implementation of lexically scoped pragmas. See
-L<perlpragma>.
-
-When putting items into C<%^H>, in order to avoid conflicting with other
-users of the hash there is a convention regarding which keys to use.
-A module should use only keys that begin with the module's name (the
-name of its main package) and a "/" character. For example, a module
-C<Foo::Bar> should use keys such as C<Foo::Bar/baz>.
-
-This variable was added in Perl 5.6.
-
-=item ${^OPEN}
-X<${^OPEN}>
-
-An internal variable used by PerlIO. A string in two parts, separated
-by a C<\0> byte, the first part describes the input layers, the second
-part describes the output layers.
-
-This variable was added in Perl 5.8.0.
-
-=item $PERLDB
-
-=item $^P
-X<$^P> X<$PERLDB>
-
-The internal variable for debugging support. The meanings of the
-various bits are subject to change, but currently indicate:
-
-=over 6
-
-=item 0x01
-
-Debug subroutine enter/exit.
-
-=item 0x02
-
-Line-by-line debugging. Causes C<DB::DB()> subroutine to be called for
-each statement executed. Also causes saving source code lines (like
-0x400).
-
-=item 0x04
-
-Switch off optimizations.
-
-=item 0x08
-
-Preserve more data for future interactive inspections.
-
-=item 0x10
-
-Keep info about source lines on which a subroutine is defined.
-
-=item 0x20
-
-Start with single-step on.
-
-=item 0x40
-
-Use subroutine address instead of name when reporting.
-
-=item 0x80
-
-Report C<goto &subroutine> as well.
-
-=item 0x100
-
-Provide informative "file" names for evals based on the place they were compiled.
-
-=item 0x200
-
-Provide informative names to anonymous subroutines based on the place they
-were compiled.
-
-=item 0x400
-
-Save source code lines into C<@{"_<$filename"}>.
-
-=back
-
-Some bits may be relevant at compile-time only, some at
-run-time only. This is a new mechanism and the details may change.
-See also L<perldebguts>.
-
-=item ${^TAINT}
-X<${^TAINT}>
-
-Reflects if taint mode is on or off. 1 for on (the program was run with
-B<-T>), 0 for off, -1 when only taint warnings are enabled (i.e. with
-B<-t> or B<-TU>).
-
-This variable is read-only.
-
-This variable was added in Perl 5.8.
-
-=item ${^UNICODE}
-X<${^UNICODE}>
-
-Reflects certain Unicode settings of Perl. See L<perlrun>
-documentation for the C<-C> switch for more information about
-the possible values.
-
-This variable is set during Perl startup and is thereafter read-only.
-
-This variable was added in Perl 5.8.2.
-
-=item ${^UTF8CACHE}
-X<${^UTF8CACHE}>
-
-This variable controls the state of the internal UTF-8 offset caching code.
-1 for on (the default), 0 for off, -1 to debug the caching code by checking
-all its results against linear scans, and panicking on any discrepancy.
-
-This variable was added in Perl 5.8.9.
-
-=item ${^UTF8LOCALE}
-X<${^UTF8LOCALE}>
-
-This variable indicates whether a UTF-8 locale was detected by perl at
-startup. This information is used by perl when it's in
-adjust-utf8ness-to-locale mode (as when run with the C<-CL> command-line
-switch); see L<perlrun> for more info on this.
-
-This variable was added in Perl 5.8.8.
-
-=back
-
-=head2 Deprecated and removed variables
-
-Deprecating a variable announces the intent of the perl maintainers to
-eventually remove the variable from the language. It may still be
-available despite its status. Using a deprecated variable triggers
-a warning.
-
-Once a variable is removed, its use triggers an error telling you
-the variable is unsupported.
-
-See L<perldiag> for details about error messages.
-
-=over 8
-
-=item $OFMT
-
-=item $#
-X<$#> X<$OFMT>
-
-C<$#> was a variable that could be used to format printed numbers.
-After a deprecation cycle, its magic was removed in Perl 5.10 and
-using it now triggers a warning: C<$# is no longer supported>.
-
-This is not the sigil you use in front of an array name to get the
-last index, like C<$#array>. That's still how you get the last index
-of an array in Perl. The two have nothing to do with each other.
-
-Deprecated in Perl 5.
-
-Removed in Perl 5.10.
-
-=item $*
-X<$*>
-
-C<$*> was a variable that you could use to enable multiline matching.
-After a deprecation cycle, its magic was removed in Perl 5.10.
-Using it now triggers a warning: C<$* is no longer supported>.
-You should use the C</s> and C</m> regexp modifiers instead.
-
-Deprecated in Perl 5.
-
-Removed in Perl 5.10.
-
-=item $ARRAY_BASE
-
-=item $[
-X<$[> X<$ARRAY_BASE>
-
-This variable stores the index of the first element in an array, and
-of the first character in a substring. The default is 0, but you could
-theoretically set it to 1 to make Perl behave more like B<awk> (or Fortran)
-when subscripting and when evaluating the index() and substr() functions.
-
-As of release 5 of Perl, assignment to C<$[> is treated as a compiler
-directive, and cannot influence the behavior of any other file.
-(That's why you can only assign compile-time constants to it.)
-Its use is highly discouraged.
-
-Prior to Perl 5.10, assignment to C<$[> could be seen from outer lexical
-scopes in the same file, unlike other compile-time directives (such as
-L<strict>). Using local() on it would bind its value strictly to a lexical
-block. Now it is always lexically scoped.
-
-As of Perl 5.16, it is implemented by the L<arybase> module. See
-L<arybase> for more details on its behaviour.
-
-Under C<use v5.16>, or C<no feature "array_base">, C<$[> no longer has any
-effect, and always contains 0. Assigning 0 to it is permitted, but any
-other value will produce an error.
-
-Mnemonic: [ begins subscripts.
-
-Deprecated in Perl 5.12.
-
-=item $OLD_PERL_VERSION
-
-=item $]
-X<$]> X<$OLD_PERL_VERSION>
-
-See L</$^V> for a more modern representation of the Perl version that allows
-accurate string comparisons.
-
-The version + patchlevel / 1000 of the Perl interpreter. This variable
-can be used to determine whether the Perl interpreter executing a
-script is in the right range of versions:
-
- warn "No checksumming!\n" if $] < 3.019;
-
-The floating point representation can sometimes lead to inaccurate
-numeric comparisons.
-
-See also the documentation of C<use VERSION> and C<require VERSION>
-for a convenient way to fail if the running Perl interpreter is too old.
-
-Mnemonic: Is this version of perl in the right bracket?
-
-=back
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlvmesa.pod b/Master/tlpkg/tlperl/lib/pods/perlvmesa.pod
deleted file mode 100644
index ae8e3864da4..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlvmesa.pod
+++ /dev/null
@@ -1,140 +0,0 @@
-
-This document is written in pod format hence there are punctuation
-characters in odd places. Do not worry, you've apparently got
-the ASCII->EBCDIC translation worked out correctly. You can read
-more about pod in pod/perlpod.pod or the short summary in the
-INSTALL file.
-
-=head1 NAME
-
-perlvmesa - building and installing Perl for VM/ESA.
-
-=head1 SYNOPSIS
-
-This document will help you Configure, build, test and install Perl
-on VM/ESA.
-
-=head1 DESCRIPTION
-
-This is a fully ported perl for VM/ESA 2.3.0. It may work on
-other versions, but that's the one we've tested it on.
-
-If you've downloaded the binary distribution, it needs to be
-installed below /usr/local. Source code distributions have an
-automated "make install" step that means you do not need to extract
-the source code below /usr/local (though that is where it will be
-installed by default). You may need to worry about the networking
-configuration files discussed in the last bullet below.
-
-=head2 Unpacking Perl Distribution on VM/ESA
-
-To extract an ASCII tar archive on VM/ESA, try this:
-
- pax -o to=IBM-1047,from=ISO8859-1 -r < latest.tar
-
-=head2 Setup Perl and utilities on VM/ESA
-
-GNU make for VM/ESA, which may be required for the build of perl,
-is available from:
-
-L<http://vm.marist.edu/~neale/vmoe.html>
-
-=head2 Configure Perl on VM/ESA
-
-Once you've unpacked the distribution, run Configure (see INSTALL for
-full discussion of the Configure options), and then run make, then
-"make test" then "make install" (this last step may require UID=0
-privileges).
-
-There is a "hints" file for vmesa that specifies the correct values
-for most things. Some things to watch out for are:
-
-=over 4
-
-=item *
-
-this port does support dynamic loading but it's not had much testing
-
-=item *
-
-Don't turn on the compiler optimization flag "-O". There's
-a bug in the compiler (APAR PQ18812) that generates some bad code
-the optimizer is on.
-
-=item *
-
-As VM/ESA doesn't fully support the fork() API programs relying on
-this call will not work. I've replaced fork()/exec() with spawn()
-and the standalone exec() with spawn(). This has a side effect when
-opening unnamed pipes in a shell script: there is no child process
-generated under.
-
-=item *
-
-At the moment the hints file for VM/ESA basically bypasses all of the
-automatic configuration process. This is because Configure relies on:
-1. The header files living in the Byte File System (you could put the
-there if you want); 2. The C preprocessor including the #include
-statements in the preprocessor output (.i) file.
-
-=back
-
-=head2 Testing Anomalies of Perl on VM/ESA
-
-The "make test" step runs a Perl Verification Procedure, usually before
-installation. As the 5.6.1 kit was being assembled
-the following "failures" were known to appear on some machines
-during "make test" (mostly due to ASCII vs. EBCDIC conflicts),
-your results may differ:
-
-[the list of failures being compiled]
-
-=head2 Usage Hints for Perl on VM/ESA
-
-When using perl on VM/ESA please keep in mind that the EBCDIC and ASCII
-character sets are different. Perl builtin functions that may behave
-differently under EBCDIC are mentioned in the perlport.pod document.
-
-OpenEdition (UNIX System Services) does not (yet) support the #! means
-of script invocation.
-See:
-
- head `whence perldoc`
-
-for an example of how to use the "eval exec" trick to ask the shell to
-have perl run your scripts for you.
-
-=head1 AUTHORS
-
-Neale Ferguson.
-
-=head1 SEE ALSO
-
-L<INSTALL>, L<perlport>, L<perlebcdic>.
-
-=head2 Mailing list for Perl on VM/ESA
-
-If you are interested in the VM/ESA, z/OS (formerly known as OS/390)
-and POSIX-BC (BS2000) ports of Perl then see the perl-mvs mailing list.
-To subscribe, send an empty message to perl-mvs-subscribe@perl.org.
-
-See also:
-
-L<http://lists.perl.org/list/perl-mvs.html>
-
-There are web archives of the mailing list at:
-
-=over 4
-
-=item *
-
-L<http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/>
-
-=item *
-
-L<http://archive.develooper.com/perl-mvs@perl.org/>
-
-=back
-
-=cut
-
diff --git a/Master/tlpkg/tlperl/lib/pods/perlvms.pod b/Master/tlpkg/tlperl/lib/pods/perlvms.pod
deleted file mode 100644
index d88e6b14be7..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlvms.pod
+++ /dev/null
@@ -1,1225 +0,0 @@
-=head1 NAME
-
-perlvms - VMS-specific documentation for Perl
-
-=head1 DESCRIPTION
-
-Gathered below are notes describing details of Perl 5's
-behavior on VMS. They are a supplement to the regular Perl 5
-documentation, so we have focussed on the ways in which Perl
-5 functions differently under VMS than it does under Unix,
-and on the interactions between Perl and the rest of the
-operating system. We haven't tried to duplicate complete
-descriptions of Perl features from the main Perl
-documentation, which can be found in the F<[.pod]>
-subdirectory of the Perl distribution.
-
-We hope these notes will save you from confusion and lost
-sleep when writing Perl scripts on VMS. If you find we've
-missed something you think should appear here, please don't
-hesitate to drop a line to vmsperl@perl.org.
-
-=head1 Installation
-
-Directions for building and installing Perl 5 can be found in
-the file F<README.vms> in the main source directory of the
-Perl distribution..
-
-=head1 Organization of Perl Images
-
-=head2 Core Images
-
-During the installation process, three Perl images are produced.
-F<Miniperl.Exe> is an executable image which contains all of
-the basic functionality of Perl, but cannot take advantage of
-Perl extensions. It is used to generate several files needed
-to build the complete Perl and various extensions. Once you've
-finished installing Perl, you can delete this image.
-
-Most of the complete Perl resides in the shareable image
-F<PerlShr.Exe>, which provides a core to which the Perl executable
-image and all Perl extensions are linked. You should place this
-image in F<Sys$Share>, or define the logical name F<PerlShr> to
-translate to the full file specification of this image. It should
-be world readable. (Remember that if a user has execute only access
-to F<PerlShr>, VMS will treat it as if it were a privileged shareable
-image, and will therefore require all downstream shareable images to be
-INSTALLed, etc.)
-
-
-Finally, F<Perl.Exe> is an executable image containing the main
-entry point for Perl, as well as some initialization code. It
-should be placed in a public directory, and made world executable.
-In order to run Perl with command line arguments, you should
-define a foreign command to invoke this image.
-
-=head2 Perl Extensions
-
-Perl extensions are packages which provide both XS and Perl code
-to add new functionality to perl. (XS is a meta-language which
-simplifies writing C code which interacts with Perl, see
-L<perlxs> for more details.) The Perl code for an
-extension is treated like any other library module - it's
-made available in your script through the appropriate
-C<use> or C<require> statement, and usually defines a Perl
-package containing the extension.
-
-The portion of the extension provided by the XS code may be
-connected to the rest of Perl in either of two ways. In the
-B<static> configuration, the object code for the extension is
-linked directly into F<PerlShr.Exe>, and is initialized whenever
-Perl is invoked. In the B<dynamic> configuration, the extension's
-machine code is placed into a separate shareable image, which is
-mapped by Perl's DynaLoader when the extension is C<use>d or
-C<require>d in your script. This allows you to maintain the
-extension as a separate entity, at the cost of keeping track of the
-additional shareable image. Most extensions can be set up as either
-static or dynamic.
-
-The source code for an extension usually resides in its own
-directory. At least three files are generally provided:
-I<Extshortname>F<.xs> (where I<Extshortname> is the portion of
-the extension's name following the last C<::>), containing
-the XS code, I<Extshortname>F<.pm>, the Perl library module
-for the extension, and F<Makefile.PL>, a Perl script which uses
-the C<MakeMaker> library modules supplied with Perl to generate
-a F<Descrip.MMS> file for the extension.
-
-=head2 Installing static extensions
-
-Since static extensions are incorporated directly into
-F<PerlShr.Exe>, you'll have to rebuild Perl to incorporate a
-new extension. You should edit the main F<Descrip.MMS> or F<Makefile>
-you use to build Perl, adding the extension's name to the C<ext>
-macro, and the extension's object file to the C<extobj> macro.
-You'll also need to build the extension's object file, either
-by adding dependencies to the main F<Descrip.MMS>, or using a
-separate F<Descrip.MMS> for the extension. Then, rebuild
-F<PerlShr.Exe> to incorporate the new code.
-
-Finally, you'll need to copy the extension's Perl library
-module to the F<[.>I<Extname>F<]> subdirectory under one
-of the directories in C<@INC>, where I<Extname> is the name
-of the extension, with all C<::> replaced by C<.> (e.g.
-the library module for extension Foo::Bar would be copied
-to a F<[.Foo.Bar]> subdirectory).
-
-=head2 Installing dynamic extensions
-
-In general, the distributed kit for a Perl extension includes
-a file named Makefile.PL, which is a Perl program which is used
-to create a F<Descrip.MMS> file which can be used to build and
-install the files required by the extension. The kit should be
-unpacked into a directory tree B<not> under the main Perl source
-directory, and the procedure for building the extension is simply
-
- $ perl Makefile.PL ! Create Descrip.MMS
- $ mmk ! Build necessary files
- $ mmk test ! Run test code, if supplied
- $ mmk install ! Install into public Perl tree
-
-I<N.B.> The procedure by which extensions are built and
-tested creates several levels (at least 4) under the
-directory in which the extension's source files live.
-For this reason if you are running a version of VMS prior
-to V7.1 you shouldn't nest the source directory
-too deeply in your directory structure lest you exceed RMS'
-maximum of 8 levels of subdirectory in a filespec. (You
-can use rooted logical names to get another 8 levels of
-nesting, if you can't place the files near the top of
-the physical directory structure.)
-
-VMS support for this process in the current release of Perl
-is sufficient to handle most extensions. However, it does
-not yet recognize extra libraries required to build shareable
-images which are part of an extension, so these must be added
-to the linker options file for the extension by hand. For
-instance, if the F<PGPLOT> extension to Perl requires the
-F<PGPLOTSHR.EXE> shareable image in order to properly link
-the Perl extension, then the line C<PGPLOTSHR/Share> must
-be added to the linker options file F<PGPLOT.Opt> produced
-during the build process for the Perl extension.
-
-By default, the shareable image for an extension is placed in
-the F<[.lib.site_perl.auto>I<Arch>.I<Extname>F<]> directory of the
-installed Perl directory tree (where I<Arch> is F<VMS_VAX> or
-F<VMS_AXP>, and I<Extname> is the name of the extension, with
-each C<::> translated to C<.>). (See the MakeMaker documentation
-for more details on installation options for extensions.)
-However, it can be manually placed in any of several locations:
-
-=over 4
-
-=item *
-
-the F<[.Lib.Auto.>I<Arch>I<$PVers>I<Extname>F<]> subdirectory
-of one of the directories in C<@INC> (where I<PVers>
-is the version of Perl you're using, as supplied in C<$]>,
-with '.' converted to '_'), or
-
-=item *
-
-one of the directories in C<@INC>, or
-
-=item *
-
-a directory which the extensions Perl library module
-passes to the DynaLoader when asking it to map
-the shareable image, or
-
-=item *
-
-F<Sys$Share> or F<Sys$Library>.
-
-=back
-
-If the shareable image isn't in any of these places, you'll need
-to define a logical name I<Extshortname>, where I<Extshortname>
-is the portion of the extension's name after the last C<::>, which
-translates to the full file specification of the shareable image.
-
-=head1 File specifications
-
-=head2 Syntax
-
-We have tried to make Perl aware of both VMS-style and Unix-style file
-specifications wherever possible. You may use either style, or both,
-on the command line and in scripts, but you may not combine the two
-styles within a single file specification. VMS Perl interprets Unix
-pathnames in much the same way as the CRTL (I<e.g.> the first component
-of an absolute path is read as the device name for the VMS file
-specification). There are a set of functions provided in the
-C<VMS::Filespec> package for explicit interconversion between VMS and
-Unix syntax; its documentation provides more details.
-
-We've tried to minimize the dependence of Perl library
-modules on Unix syntax, but you may find that some of these,
-as well as some scripts written for Unix systems, will
-require that you use Unix syntax, since they will assume that
-'/' is the directory separator, I<etc.> If you find instances
-of this in the Perl distribution itself, please let us know,
-so we can try to work around them.
-
-Also when working on Perl programs on VMS, if you need a syntax
-in a specific operating system format, then you need either to
-check the appropriate DECC$ feature logical, or call a conversion
-routine to force it to that format.
-
-The feature logical name DECC$FILENAME_UNIX_REPORT modifies traditional
-Perl behavior in the conversion of file specifications from Unix to VMS
-format in order to follow the extended character handling rules now
-expected by the CRTL. Specifically, when this feature is in effect, the
-C<./.../> in a Unix path is now translated to C<[.^.^.^.]> instead of
-the traditional VMS C<[...]>. To be compatible with what MakeMaker
-expects, if a VMS path cannot be translated to a Unix path, it is
-passed through unchanged, so C<unixify("[...]")> will return C<[...]>.
-
-The handling of extended characters is largely complete in the
-VMS-specific C infrastructure of Perl, but more work is still needed to
-fully support extended syntax filenames in several core modules. In
-particular, at this writing PathTools has only partial support for
-directories containing some extended characters.
-
-There are several ambiguous cases where a conversion routine cannot
-determine whether an input filename is in Unix format or in VMS format,
-since now both VMS and Unix file specifications may have characters in
-them that could be mistaken for syntax delimiters of the other type. So
-some pathnames simply cannot be used in a mode that allows either type
-of pathname to be present. Perl will tend to assume that an ambiguous
-filename is in Unix format.
-
-Allowing "." as a version delimiter is simply incompatible with
-determining whether a pathname is in VMS format or in Unix format with
-extended file syntax. There is no way to know whether "perl-5.8.6" is a
-Unix "perl-5.8.6" or a VMS "perl-5.8;6" when passing it to unixify() or
-vmsify().
-
-The DECC$FILENAME_UNIX_REPORT logical name controls how Perl interprets
-filenames to the extent that Perl uses the CRTL internally for many
-purposes, and attempts to follow CRTL conventions for reporting
-filenames. The DECC$FILENAME_UNIX_ONLY feature differs in that it
-expects all filenames passed to the C run-time to be already in Unix
-format. This feature is not yet supported in Perl since Perl uses
-traditional OpenVMS file specifications internally and in the test
-harness, and it is not yet clear whether this mode will be useful or
-useable. The feature logical name DECC$POSIX_COMPLIANT_PATHNAMES is new
-with the RMS Symbolic Link SDK and included with OpenVMS v8.3, but is
-not yet supported in Perl.
-
-=head2 Filename Case
-
-Perl follows VMS defaults and override settings in preserving (or not
-preserving) filename case. Case is not preserved on ODS-2 formatted
-volumes on any architecture. On ODS-5 volumes, filenames may be case
-preserved depending on process and feature settings. Perl now honors
-DECC$EFS_CASE_PRESERVE and DECC$ARGV_PARSE_STYLE on those systems where
-the CRTL supports these features. When these features are not enabled
-or the CRTL does not support them, Perl follows the traditional CRTL
-behavior of downcasing command-line arguments and returning file
-specifications in lower case only.
-
-I<N. B.> It is very easy to get tripped up using a mixture of other
-programs, external utilities, and Perl scripts that are in varying
-states of being able to handle case preservation. For example, a file
-created by an older version of an archive utility or a build utility
-such as MMK or MMS may generate a filename in all upper case even on an
-ODS-5 volume. If this filename is later retrieved by a Perl script or
-module in a case preserving environment, that upper case name may not
-match the mixed-case or lower-case exceptions of the Perl code. Your
-best bet is to follow an all-or-nothing approach to case preservation:
-either don't use it at all, or make sure your entire toolchain and
-application environment support and use it.
-
-OpenVMS Alpha v7.3-1 and later and all version of OpenVMS I64 support
-case sensitivity as a process setting (see C<SET PROCESS
-/CASE_LOOKUP=SENSITIVE>). Perl does not currently support case
-sensitivity on VMS, but it may in the future, so Perl programs should
-use the C<< File::Spec->case_tolerant >> method to determine the state, and
-not the C<$^O> variable.
-
-=head2 Symbolic Links
-
-When built on an ODS-5 volume with symbolic links enabled, Perl by
-default supports symbolic links when the requisite support is available
-in the filesystem and CRTL (generally 64-bit OpenVMS v8.3 and later).
-There are a number of limitations and caveats to be aware of when
-working with symbolic links on VMS. Most notably, the target of a valid
-symbolic link must be expressed as a Unix-style path and it must exist
-on a volume visible from your POSIX root (see the C<SHOW ROOT> command
-in DCL help). For further details on symbolic link capabilities and
-requirements, see chapter 12 of the CRTL manual that ships with OpenVMS
-v8.3 or later.
-
-=head2 Wildcard expansion
-
-File specifications containing wildcards are allowed both on
-the command line and within Perl globs (e.g. C<E<lt>*.cE<gt>>). If
-the wildcard filespec uses VMS syntax, the resultant
-filespecs will follow VMS syntax; if a Unix-style filespec is
-passed in, Unix-style filespecs will be returned.
-Similar to the behavior of wildcard globbing for a Unix shell,
-one can escape command line wildcards with double quotation
-marks C<"> around a perl program command line argument. However,
-owing to the stripping of C<"> characters carried out by the C
-handling of argv you will need to escape a construct such as
-this one (in a directory containing the files F<PERL.C>, F<PERL.EXE>,
-F<PERL.H>, and F<PERL.OBJ>):
-
- $ perl -e "print join(' ',@ARGV)" perl.*
- perl.c perl.exe perl.h perl.obj
-
-in the following triple quoted manner:
-
- $ perl -e "print join(' ',@ARGV)" """perl.*"""
- perl.*
-
-In both the case of unquoted command line arguments or in calls
-to C<glob()> VMS wildcard expansion is performed. (csh-style
-wildcard expansion is available if you use C<File::Glob::glob>.)
-If the wildcard filespec contains a device or directory
-specification, then the resultant filespecs will also contain
-a device and directory; otherwise, device and directory
-information are removed. VMS-style resultant filespecs will
-contain a full device and directory, while Unix-style
-resultant filespecs will contain only as much of a directory
-path as was present in the input filespec. For example, if
-your default directory is Perl_Root:[000000], the expansion
-of C<[.t]*.*> will yield filespecs like
-"perl_root:[t]base.dir", while the expansion of C<t/*/*> will
-yield filespecs like "t/base.dir". (This is done to match
-the behavior of glob expansion performed by Unix shells.)
-
-Similarly, the resultant filespec will contain the file version
-only if one was present in the input filespec.
-
-
-=head2 Pipes
-
-Input and output pipes to Perl filehandles are supported; the
-"file name" is passed to lib$spawn() for asynchronous
-execution. You should be careful to close any pipes you have
-opened in a Perl script, lest you leave any "orphaned"
-subprocesses around when Perl exits.
-
-You may also use backticks to invoke a DCL subprocess, whose
-output is used as the return value of the expression. The
-string between the backticks is handled as if it were the
-argument to the C<system> operator (see below). In this case,
-Perl will wait for the subprocess to complete before continuing.
-
-The mailbox (MBX) that perl can create to communicate with a pipe
-defaults to a buffer size of 8192 on 64-bit systems, 512 on VAX. The
-default buffer size is adjustable via the logical name PERL_MBX_SIZE
-provided that the value falls between 128 and the SYSGEN parameter
-MAXBUF inclusive. For example, to set the mailbox size to 32767 use
-C<$ENV{'PERL_MBX_SIZE'} = 32767;> and then open and use pipe constructs.
-An alternative would be to issue the command:
-
- $ Define PERL_MBX_SIZE 32767
-
-before running your wide record pipe program. A larger value may
-improve performance at the expense of the BYTLM UAF quota.
-
-=head1 PERL5LIB and PERLLIB
-
-The PERL5LIB and PERLLIB logical names work as documented in L<perl>,
-except that the element separator is '|' instead of ':'. The
-directory specifications may use either VMS or Unix syntax.
-
-=head1 The Perl Forked Debugger
-
-The Perl forked debugger places the debugger commands and output in a
-separate X-11 terminal window so that commands and output from multiple
-processes are not mixed together.
-
-Perl on VMS supports an emulation of the forked debugger when Perl is
-run on a VMS system that has X11 support installed.
-
-To use the forked debugger, you need to have the default display set to an
-X-11 Server and some environment variables set that Unix expects.
-
-The forked debugger requires the environment variable C<TERM> to be C<xterm>,
-and the environment variable C<DISPLAY> to exist. C<xterm> must be in
-lower case.
-
- $define TERM "xterm"
-
- $define DISPLAY "hostname:0.0"
-
-Currently the value of C<DISPLAY> is ignored. It is recommended that it be set
-to be the hostname of the display, the server and screen in Unix notation. In
-the future the value of DISPLAY may be honored by Perl instead of using the
-default display.
-
-It may be helpful to always use the forked debugger so that script I/O is
-separated from debugger I/O. You can force the debugger to be forked by
-assigning a value to the logical name <PERLDB_PIDS> that is not a process
-identification number.
-
- $define PERLDB_PIDS XXXX
-
-
-=head1 PERL_VMS_EXCEPTION_DEBUG
-
-The PERL_VMS_EXCEPTION_DEBUG being defined as "ENABLE" will cause the VMS
-debugger to be invoked if a fatal exception that is not otherwise
-handled is raised. The purpose of this is to allow debugging of
-internal Perl problems that would cause such a condition.
-
-This allows the programmer to look at the execution stack and variables to
-find out the cause of the exception. As the debugger is being invoked as
-the Perl interpreter is about to do a fatal exit, continuing the execution
-in debug mode is usually not practical.
-
-Starting Perl in the VMS debugger may change the program execution
-profile in a way that such problems are not reproduced.
-
-The C<kill> function can be used to test this functionality from within
-a program.
-
-In typical VMS style, only the first letter of the value of this logical
-name is actually checked in a case insensitive mode, and it is considered
-enabled if it is the value "T","1" or "E".
-
-This logical name must be defined before Perl is started.
-
-=head1 Command line
-
-=head2 I/O redirection and backgrounding
-
-Perl for VMS supports redirection of input and output on the
-command line, using a subset of Bourne shell syntax:
-
-=over 4
-
-=item *
-
-C<E<lt>file> reads stdin from C<file>,
-
-=item *
-
-C<E<gt>file> writes stdout to C<file>,
-
-=item *
-
-C<E<gt>E<gt>file> appends stdout to C<file>,
-
-=item *
-
-C<2E<gt>file> writes stderr to C<file>,
-
-=item *
-
-C<2E<gt>E<gt>file> appends stderr to C<file>, and
-
-=item *
-
-C<< 2>&1 >> redirects stderr to stdout.
-
-=back
-
-In addition, output may be piped to a subprocess, using the
-character '|'. Anything after this character on the command
-line is passed to a subprocess for execution; the subprocess
-takes the output of Perl as its input.
-
-Finally, if the command line ends with '&', the entire
-command is run in the background as an asynchronous
-subprocess.
-
-=head2 Command line switches
-
-The following command line switches behave differently under
-VMS than described in L<perlrun>. Note also that in order
-to pass uppercase switches to Perl, you need to enclose
-them in double-quotes on the command line, since the CRTL
-downcases all unquoted strings.
-
-On newer 64 bit versions of OpenVMS, a process setting now
-controls if the quoting is needed to preserve the case of
-command line arguments.
-
-=over 4
-
-=item -i
-
-If the C<-i> switch is present but no extension for a backup
-copy is given, then inplace editing creates a new version of
-a file; the existing copy is not deleted. (Note that if
-an extension is given, an existing file is renamed to the backup
-file, as is the case under other operating systems, so it does
-not remain as a previous version under the original filename.)
-
-=item -S
-
-If the C<"-S"> or C<-"S"> switch is present I<and> the script
-name does not contain a directory, then Perl translates the
-logical name DCL$PATH as a searchlist, using each translation
-as a directory in which to look for the script. In addition,
-if no file type is specified, Perl looks in each directory
-for a file matching the name specified, with a blank type,
-a type of F<.pl>, and a type of F<.com>, in that order.
-
-=item -u
-
-The C<-u> switch causes the VMS debugger to be invoked
-after the Perl program is compiled, but before it has
-run. It does not create a core dump file.
-
-=back
-
-=head1 Perl functions
-
-As of the time this document was last revised, the following
-Perl functions were implemented in the VMS port of Perl
-(functions marked with * are discussed in more detail below):
-
- file tests*, abs, alarm, atan, backticks*, binmode*, bless,
- caller, chdir, chmod, chown, chomp, chop, chr,
- close, closedir, cos, crypt*, defined, delete, die, do, dump*,
- each, endgrent, endpwent, eof, eval, exec*, exists, exit, exp,
- fileno, flock getc, getgrent*, getgrgid*, getgrnam, getlogin, getppid,
- getpwent*, getpwnam*, getpwuid*, glob, gmtime*, goto,
- grep, hex, ioctl, import, index, int, join, keys, kill*,
- last, lc, lcfirst, lchown*, length, link*, local, localtime, log, lstat, m//,
- map, mkdir, my, next, no, oct, open, opendir, ord, pack,
- pipe, pop, pos, print, printf, push, q//, qq//, qw//,
- qx//*, quotemeta, rand, read, readdir, readlink*, redo, ref, rename,
- require, reset, return, reverse, rewinddir, rindex,
- rmdir, s///, scalar, seek, seekdir, select(internal),
- select (system call)*, setgrent, setpwent, shift, sin, sleep,
- socketpair, sort, splice, split, sprintf, sqrt, srand, stat,
- study, substr, symlink*, sysread, system*, syswrite, tell,
- telldir, tie, time, times*, tr///, uc, ucfirst, umask,
- undef, unlink*, unpack, untie, unshift, use, utime*,
- values, vec, wait, waitpid*, wantarray, warn, write, y///
-
-The following functions were not implemented in the VMS port,
-and calling them produces a fatal error (usually) or
-undefined behavior (rarely, we hope):
-
- chroot, dbmclose, dbmopen, fork*, getpgrp, getpriority,
- msgctl, msgget, msgsend, msgrcv, semctl,
- semget, semop, setpgrp, setpriority, shmctl, shmget,
- shmread, shmwrite, syscall
-
-The following functions are available on Perls compiled with Dec C
-5.2 or greater and running VMS 7.0 or greater:
-
- truncate
-
-The following functions are available on Perls built on VMS 7.2 or
-greater:
-
- fcntl (without locking)
-
-The following functions may or may not be implemented,
-depending on what type of socket support you've built into
-your copy of Perl:
-
- accept, bind, connect, getpeername,
- gethostbyname, getnetbyname, getprotobyname,
- getservbyname, gethostbyaddr, getnetbyaddr,
- getprotobynumber, getservbyport, gethostent,
- getnetent, getprotoent, getservent, sethostent,
- setnetent, setprotoent, setservent, endhostent,
- endnetent, endprotoent, endservent, getsockname,
- getsockopt, listen, recv, select(system call)*,
- send, setsockopt, shutdown, socket
-
-The following function is available on Perls built on 64 bit OpenVMS v8.2
-with hard links enabled on an ODS-5 formatted build disk. CRTL support
-is in principle available as of OpenVMS v7.3-1, and better configuration
-support could detect this.
-
- link
-
-The following functions are available on Perls built on 64 bit OpenVMS
-v8.2 and later. CRTL support is in principle available as of OpenVMS
-v7.3-2, and better configuration support could detect this.
-
- getgrgid, getgrnam, getpwnam, getpwuid,
- setgrent, ttyname
-
-The following functions are available on Perls built on 64 bit OpenVMS v8.2
-and later.
-
- statvfs, socketpair
-
-=over 4
-
-=item File tests
-
-The tests C<-b>, C<-B>, C<-c>, C<-C>, C<-d>, C<-e>, C<-f>,
-C<-o>, C<-M>, C<-s>, C<-S>, C<-t>, C<-T>, and C<-z> work as
-advertised. The return values for C<-r>, C<-w>, and C<-x>
-tell you whether you can actually access the file; this may
-not reflect the UIC-based file protections. Since real and
-effective UIC don't differ under VMS, C<-O>, C<-R>, C<-W>,
-and C<-X> are equivalent to C<-o>, C<-r>, C<-w>, and C<-x>.
-Similarly, several other tests, including C<-A>, C<-g>, C<-k>,
-C<-l>, C<-p>, and C<-u>, aren't particularly meaningful under
-VMS, and the values returned by these tests reflect whatever
-your CRTL C<stat()> routine does to the equivalent bits in the
-st_mode field. Finally, C<-d> returns true if passed a device
-specification without an explicit directory (e.g. C<DUA1:>), as
-well as if passed a directory.
-
-There are DECC feature logical names AND ODS-5 volume attributes that
-also control what values are returned for the date fields.
-
-Note: Some sites have reported problems when using the file-access
-tests (C<-r>, C<-w>, and C<-x>) on files accessed via DEC's DFS.
-Specifically, since DFS does not currently provide access to the
-extended file header of files on remote volumes, attempts to
-examine the ACL fail, and the file tests will return false,
-with C<$!> indicating that the file does not exist. You can
-use C<stat> on these files, since that checks UIC-based protection
-only, and then manually check the appropriate bits, as defined by
-your C compiler's F<stat.h>, in the mode value it returns, if you
-need an approximation of the file's protections.
-
-=item backticks
-
-Backticks create a subprocess, and pass the enclosed string
-to it for execution as a DCL command. Since the subprocess is
-created directly via C<lib$spawn()>, any valid DCL command string
-may be specified.
-
-=item binmode FILEHANDLE
-
-The C<binmode> operator will attempt to insure that no translation
-of carriage control occurs on input from or output to this filehandle.
-Since this involves reopening the file and then restoring its
-file position indicator, if this function returns FALSE, the
-underlying filehandle may no longer point to an open file, or may
-point to a different position in the file than before C<binmode>
-was called.
-
-Note that C<binmode> is generally not necessary when using normal
-filehandles; it is provided so that you can control I/O to existing
-record-structured files when necessary. You can also use the
-C<vmsfopen> function in the VMS::Stdio extension to gain finer
-control of I/O to files and devices with different record structures.
-
-=item crypt PLAINTEXT, USER
-
-The C<crypt> operator uses the C<sys$hash_password> system
-service to generate the hashed representation of PLAINTEXT.
-If USER is a valid username, the algorithm and salt values
-are taken from that user's UAF record. If it is not, then
-the preferred algorithm and a salt of 0 are used. The
-quadword encrypted value is returned as an 8-character string.
-
-The value returned by C<crypt> may be compared against
-the encrypted password from the UAF returned by the C<getpw*>
-functions, in order to authenticate users. If you're
-going to do this, remember that the encrypted password in
-the UAF was generated using uppercase username and
-password strings; you'll have to upcase the arguments to
-C<crypt> to insure that you'll get the proper value:
-
- sub validate_passwd {
- my($user,$passwd) = @_;
- my($pwdhash);
- if ( !($pwdhash = (getpwnam($user))[1]) ||
- $pwdhash ne crypt("\U$passwd","\U$name") ) {
- intruder_alert($name);
- }
- return 1;
- }
-
-
-=item die
-
-C<die> will force the native VMS exit status to be an SS$_ABORT code
-if neither of the $! or $? status values are ones that would cause
-the native status to be interpreted as being what VMS classifies as
-SEVERE_ERROR severity for DCL error handling.
-
-When C<PERL_VMS_POSIX_EXIT> is active (see L</"$?"> below), the native VMS exit
-status value will have either one of the C<$!> or C<$?> or C<$^E> or
-the Unix value 255 encoded into it in a way that the effective original
-value can be decoded by other programs written in C, including Perl
-and the GNV package. As per the normal non-VMS behavior of C<die> if
-either C<$!> or C<$?> are non-zero, one of those values will be
-encoded into a native VMS status value. If both of the Unix status
-values are 0, and the C<$^E> value is set one of ERROR or SEVERE_ERROR
-severity, then the C<$^E> value will be used as the exit code as is.
-If none of the above apply, the Unix value of 255 will be encoded into
-a native VMS exit status value.
-
-Please note a significant difference in the behavior of C<die> in
-the C<PERL_VMS_POSIX_EXIT> mode is that it does not force a VMS
-SEVERE_ERROR status on exit. The Unix exit values of 2 through
-255 will be encoded in VMS status values with severity levels of
-SUCCESS. The Unix exit value of 1 will be encoded in a VMS status
-value with a severity level of ERROR. This is to be compatible with
-how the VMS C library encodes these values.
-
-The minimum severity level set by C<die> in C<PERL_VMS_POSIX_EXIT> mode
-may be changed to be ERROR or higher in the future depending on the
-results of testing and further review.
-
-See L</"$?"> for a description of the encoding of the Unix value to
-produce a native VMS status containing it.
-
-=item dump
-
-Rather than causing Perl to abort and dump core, the C<dump>
-operator invokes the VMS debugger. If you continue to
-execute the Perl program under the debugger, control will
-be transferred to the label specified as the argument to
-C<dump>, or, if no label was specified, back to the
-beginning of the program. All other state of the program
-(I<e.g.> values of variables, open file handles) are not
-affected by calling C<dump>.
-
-=item exec LIST
-
-A call to C<exec> will cause Perl to exit, and to invoke the command
-given as an argument to C<exec> via C<lib$do_command>. If the
-argument begins with '@' or '$' (other than as part of a filespec),
-then it is executed as a DCL command. Otherwise, the first token on
-the command line is treated as the filespec of an image to run, and
-an attempt is made to invoke it (using F<.Exe> and the process
-defaults to expand the filespec) and pass the rest of C<exec>'s
-argument to it as parameters. If the token has no file type, and
-matches a file with null type, then an attempt is made to determine
-whether the file is an executable image which should be invoked
-using C<MCR> or a text file which should be passed to DCL as a
-command procedure.
-
-=item fork
-
-While in principle the C<fork> operator could be implemented via
-(and with the same rather severe limitations as) the CRTL C<vfork()>
-routine, and while some internal support to do just that is in
-place, the implementation has never been completed, making C<fork>
-currently unavailable. A true kernel C<fork()> is expected in a
-future version of VMS, and the pseudo-fork based on interpreter
-threads may be available in a future version of Perl on VMS (see
-L<perlfork>). In the meantime, use C<system>, backticks, or piped
-filehandles to create subprocesses.
-
-=item getpwent
-
-=item getpwnam
-
-=item getpwuid
-
-These operators obtain the information described in L<perlfunc>,
-if you have the privileges necessary to retrieve the named user's
-UAF information via C<sys$getuai>. If not, then only the C<$name>,
-C<$uid>, and C<$gid> items are returned. The C<$dir> item contains
-the login directory in VMS syntax, while the C<$comment> item
-contains the login directory in Unix syntax. The C<$gcos> item
-contains the owner field from the UAF record. The C<$quota>
-item is not used.
-
-=item gmtime
-
-The C<gmtime> operator will function properly if you have a
-working CRTL C<gmtime()> routine, or if the logical name
-SYS$TIMEZONE_DIFFERENTIAL is defined as the number of seconds
-which must be added to UTC to yield local time. (This logical
-name is defined automatically if you are running a version of
-VMS with built-in UTC support.) If neither of these cases is
-true, a warning message is printed, and C<undef> is returned.
-
-=item kill
-
-In most cases, C<kill> is implemented via the undocumented system
-service C<$SIGPRC>, which has the same calling sequence as C<$FORCEX>, but
-throws an exception in the target process rather than forcing it to call
-C<$EXIT>. Generally speaking, C<kill> follows the behavior of the
-CRTL's C<kill()> function, but unlike that function can be called from
-within a signal handler. Also, unlike the C<kill> in some versions of
-the CRTL, Perl's C<kill> checks the validity of the signal passed in and
-returns an error rather than attempting to send an unrecognized signal.
-
-Also, negative signal values don't do anything special under
-VMS; they're just converted to the corresponding positive value.
-
-=item qx//
-
-See the entry on C<backticks> above.
-
-=item select (system call)
-
-If Perl was not built with socket support, the system call
-version of C<select> is not available at all. If socket
-support is present, then the system call version of
-C<select> functions only for file descriptors attached
-to sockets. It will not provide information about regular
-files or pipes, since the CRTL C<select()> routine does not
-provide this functionality.
-
-=item stat EXPR
-
-Since VMS keeps track of files according to a different scheme
-than Unix, it's not really possible to represent the file's ID
-in the C<st_dev> and C<st_ino> fields of a C<struct stat>. Perl
-tries its best, though, and the values it uses are pretty unlikely
-to be the same for two different files. We can't guarantee this,
-though, so caveat scriptor.
-
-=item system LIST
-
-The C<system> operator creates a subprocess, and passes its
-arguments to the subprocess for execution as a DCL command.
-Since the subprocess is created directly via C<lib$spawn()>, any
-valid DCL command string may be specified. If the string begins with
-'@', it is treated as a DCL command unconditionally. Otherwise, if
-the first token contains a character used as a delimiter in file
-specification (e.g. C<:> or C<]>), an attempt is made to expand it
-using a default type of F<.Exe> and the process defaults, and if
-successful, the resulting file is invoked via C<MCR>. This allows you
-to invoke an image directly simply by passing the file specification
-to C<system>, a common Unixish idiom. If the token has no file type,
-and matches a file with null type, then an attempt is made to
-determine whether the file is an executable image which should be
-invoked using C<MCR> or a text file which should be passed to DCL
-as a command procedure.
-
-If LIST consists of the empty string, C<system> spawns an
-interactive DCL subprocess, in the same fashion as typing
-B<SPAWN> at the DCL prompt.
-
-Perl waits for the subprocess to complete before continuing
-execution in the current process. As described in L<perlfunc>,
-the return value of C<system> is a fake "status" which follows
-POSIX semantics unless the pragma C<use vmsish 'status'> is in
-effect; see the description of C<$?> in this document for more
-detail.
-
-=item time
-
-The value returned by C<time> is the offset in seconds from
-01-JAN-1970 00:00:00 (just like the CRTL's times() routine), in order
-to make life easier for code coming in from the POSIX/Unix world.
-
-=item times
-
-The array returned by the C<times> operator is divided up
-according to the same rules the CRTL C<times()> routine.
-Therefore, the "system time" elements will always be 0, since
-there is no difference between "user time" and "system" time
-under VMS, and the time accumulated by a subprocess may or may
-not appear separately in the "child time" field, depending on
-whether C<times()> keeps track of subprocesses separately. Note
-especially that the VAXCRTL (at least) keeps track only of
-subprocesses spawned using C<fork()> and C<exec()>; it will not
-accumulate the times of subprocesses spawned via pipes, C<system()>,
-or backticks.
-
-=item unlink LIST
-
-C<unlink> will delete the highest version of a file only; in
-order to delete all versions, you need to say
-
- 1 while unlink LIST;
-
-You may need to make this change to scripts written for a
-Unix system which expect that after a call to C<unlink>,
-no files with the names passed to C<unlink> will exist.
-(Note: This can be changed at compile time; if you
-C<use Config> and C<$Config{'d_unlink_all_versions'}> is
-C<define>, then C<unlink> will delete all versions of a
-file on the first call.)
-
-C<unlink> will delete a file if at all possible, even if it
-requires changing file protection (though it won't try to
-change the protection of the parent directory). You can tell
-whether you've got explicit delete access to a file by using the
-C<VMS::Filespec::candelete> operator. For instance, in order
-to delete only files to which you have delete access, you could
-say something like
-
- sub safe_unlink {
- my($file,$num);
- foreach $file (@_) {
- next unless VMS::Filespec::candelete($file);
- $num += unlink $file;
- }
- $num;
- }
-
-(or you could just use C<VMS::Stdio::remove>, if you've installed
-the VMS::Stdio extension distributed with Perl). If C<unlink> has to
-change the file protection to delete the file, and you interrupt it
-in midstream, the file may be left intact, but with a changed ACL
-allowing you delete access.
-
-This behavior of C<unlink> is to be compatible with POSIX behavior
-and not traditional VMS behavior.
-
-=item utime LIST
-
-This operator changes only the modification time of the file (VMS
-revision date) on ODS-2 volumes and ODS-5 volumes without access
-dates enabled. On ODS-5 volumes with access dates enabled, the
-true access time is modified.
-
-=item waitpid PID,FLAGS
-
-If PID is a subprocess started by a piped C<open()> (see L<open>),
-C<waitpid> will wait for that subprocess, and return its final status
-value in C<$?>. If PID is a subprocess created in some other way (e.g.
-SPAWNed before Perl was invoked), C<waitpid> will simply check once per
-second whether the process has completed, and return when it has. (If
-PID specifies a process that isn't a subprocess of the current process,
-and you invoked Perl with the C<-w> switch, a warning will be issued.)
-
-Returns PID on success, -1 on error. The FLAGS argument is ignored
-in all cases.
-
-=back
-
-=head1 Perl variables
-
-The following VMS-specific information applies to the indicated
-"special" Perl variables, in addition to the general information
-in L<perlvar>. Where there is a conflict, this information
-takes precedence.
-
-=over 4
-
-=item %ENV
-
-The operation of the C<%ENV> array depends on the translation
-of the logical name F<PERL_ENV_TABLES>. If defined, it should
-be a search list, each element of which specifies a location
-for C<%ENV> elements. If you tell Perl to read or set the
-element C<$ENV{>I<name>C<}>, then Perl uses the translations of
-F<PERL_ENV_TABLES> as follows:
-
-=over 4
-
-=item CRTL_ENV
-
-This string tells Perl to consult the CRTL's internal C<environ>
-array of key-value pairs, using I<name> as the key. In most cases,
-this contains only a few keys, but if Perl was invoked via the C
-C<exec[lv]e()> function, as is the case for CGI processing by some
-HTTP servers, then the C<environ> array may have been populated by
-the calling program.
-
-=item CLISYM_[LOCAL]
-
-A string beginning with C<CLISYM_>tells Perl to consult the CLI's
-symbol tables, using I<name> as the name of the symbol. When reading
-an element of C<%ENV>, the local symbol table is scanned first, followed
-by the global symbol table.. The characters following C<CLISYM_> are
-significant when an element of C<%ENV> is set or deleted: if the
-complete string is C<CLISYM_LOCAL>, the change is made in the local
-symbol table; otherwise the global symbol table is changed.
-
-=item Any other string
-
-If an element of F<PERL_ENV_TABLES> translates to any other string,
-that string is used as the name of a logical name table, which is
-consulted using I<name> as the logical name. The normal search
-order of access modes is used.
-
-=back
-
-F<PERL_ENV_TABLES> is translated once when Perl starts up; any changes
-you make while Perl is running do not affect the behavior of C<%ENV>.
-If F<PERL_ENV_TABLES> is not defined, then Perl defaults to consulting
-first the logical name tables specified by F<LNM$FILE_DEV>, and then
-the CRTL C<environ> array.
-
-In all operations on %ENV, the key string is treated as if it
-were entirely uppercase, regardless of the case actually
-specified in the Perl expression.
-
-When an element of C<%ENV> is read, the locations to which
-F<PERL_ENV_TABLES> points are checked in order, and the value
-obtained from the first successful lookup is returned. If the
-name of the C<%ENV> element contains a semi-colon, it and
-any characters after it are removed. These are ignored when
-the CRTL C<environ> array or a CLI symbol table is consulted.
-However, the name is looked up in a logical name table, the
-suffix after the semi-colon is treated as the translation index
-to be used for the lookup. This lets you look up successive values
-for search list logical names. For instance, if you say
-
- $ Define STORY once,upon,a,time,there,was
- $ perl -e "for ($i = 0; $i <= 6; $i++) " -
- _$ -e "{ print $ENV{'story;'.$i},' '}"
-
-Perl will print C<ONCE UPON A TIME THERE WAS>, assuming, of course,
-that F<PERL_ENV_TABLES> is set up so that the logical name C<story>
-is found, rather than a CLI symbol or CRTL C<environ> element with
-the same name.
-
-When an element of C<%ENV> is set to a defined string, the
-corresponding definition is made in the location to which the
-first translation of F<PERL_ENV_TABLES> points. If this causes a
-logical name to be created, it is defined in supervisor mode.
-(The same is done if an existing logical name was defined in
-executive or kernel mode; an existing user or supervisor mode
-logical name is reset to the new value.) If the value is an empty
-string, the logical name's translation is defined as a single NUL
-(ASCII 00) character, since a logical name cannot translate to a
-zero-length string. (This restriction does not apply to CLI symbols
-or CRTL C<environ> values; they are set to the empty string.)
-An element of the CRTL C<environ> array can be set only if your
-copy of Perl knows about the CRTL's C<setenv()> function. (This is
-present only in some versions of the DECCRTL; check C<$Config{d_setenv}>
-to see whether your copy of Perl was built with a CRTL that has this
-function.)
-
-When an element of C<%ENV> is set to C<undef>,
-the element is looked up as if it were being read, and if it is
-found, it is deleted. (An item "deleted" from the CRTL C<environ>
-array is set to the empty string; this can only be done if your
-copy of Perl knows about the CRTL C<setenv()> function.) Using
-C<delete> to remove an element from C<%ENV> has a similar effect,
-but after the element is deleted, another attempt is made to
-look up the element, so an inner-mode logical name or a name in
-another location will replace the logical name just deleted.
-In either case, only the first value found searching PERL_ENV_TABLES
-is altered. It is not possible at present to define a search list
-logical name via %ENV.
-
-The element C<$ENV{DEFAULT}> is special: when read, it returns
-Perl's current default device and directory, and when set, it
-resets them, regardless of the definition of F<PERL_ENV_TABLES>.
-It cannot be cleared or deleted; attempts to do so are silently
-ignored.
-
-Note that if you want to pass on any elements of the
-C-local environ array to a subprocess which isn't
-started by fork/exec, or isn't running a C program, you
-can "promote" them to logical names in the current
-process, which will then be inherited by all subprocesses,
-by saying
-
- foreach my $key (qw[C-local keys you want promoted]) {
- my $temp = $ENV{$key}; # read from C-local array
- $ENV{$key} = $temp; # and define as logical name
- }
-
-(You can't just say C<$ENV{$key} = $ENV{$key}>, since the
-Perl optimizer is smart enough to elide the expression.)
-
-Don't try to clear C<%ENV> by saying C<%ENV = ();>, it will throw
-a fatal error. This is equivalent to doing the following from DCL:
-
- DELETE/LOGICAL *
-
-You can imagine how bad things would be if, for example, the SYS$MANAGER
-or SYS$SYSTEM logical names were deleted.
-
-At present, the first time you iterate over %ENV using
-C<keys>, or C<values>, you will incur a time penalty as all
-logical names are read, in order to fully populate %ENV.
-Subsequent iterations will not reread logical names, so they
-won't be as slow, but they also won't reflect any changes
-to logical name tables caused by other programs.
-
-You do need to be careful with the logical names representing
-process-permanent files, such as C<SYS$INPUT> and C<SYS$OUTPUT>.
-The translations for these logical names are prepended with a
-two-byte binary value (0x1B 0x00) that needs to be stripped off
-if you wantto use it. (In previous versions of Perl it wasn't
-possible to get the values of these logical names, as the null
-byte acted as an end-of-string marker)
-
-=item $!
-
-The string value of C<$!> is that returned by the CRTL's
-strerror() function, so it will include the VMS message for
-VMS-specific errors. The numeric value of C<$!> is the
-value of C<errno>, except if errno is EVMSERR, in which
-case C<$!> contains the value of vaxc$errno. Setting C<$!>
-always sets errno to the value specified. If this value is
-EVMSERR, it also sets vaxc$errno to 4 (NONAME-F-NOMSG), so
-that the string value of C<$!> won't reflect the VMS error
-message from before C<$!> was set.
-
-=item $^E
-
-This variable provides direct access to VMS status values
-in vaxc$errno, which are often more specific than the
-generic Unix-style error messages in C<$!>. Its numeric value
-is the value of vaxc$errno, and its string value is the
-corresponding VMS message string, as retrieved by sys$getmsg().
-Setting C<$^E> sets vaxc$errno to the value specified.
-
-While Perl attempts to keep the vaxc$errno value to be current, if
-errno is not EVMSERR, it may not be from the current operation.
-
-=item $?
-
-The "status value" returned in C<$?> is synthesized from the
-actual exit status of the subprocess in a way that approximates
-POSIX wait(5) semantics, in order to allow Perl programs to
-portably test for successful completion of subprocesses. The
-low order 8 bits of C<$?> are always 0 under VMS, since the
-termination status of a process may or may not have been
-generated by an exception.
-
-The next 8 bits contain the termination status of the program.
-
-If the child process follows the convention of C programs
-compiled with the _POSIX_EXIT macro set, the status value will
-contain the actual value of 0 to 255 returned by that program
-on a normal exit.
-
-With the _POSIX_EXIT macro set, the Unix exit value of zero is
-represented as a VMS native status of 1, and the Unix values
-from 2 to 255 are encoded by the equation:
-
- VMS_status = 0x35a000 + (unix_value * 8) + 1.
-
-And in the special case of Unix value 1 the encoding is:
-
- VMS_status = 0x35a000 + 8 + 2 + 0x10000000.
-
-For other termination statuses, the severity portion of the
-subprocess's exit status is used: if the severity was success or
-informational, these bits are all 0; if the severity was
-warning, they contain a value of 1; if the severity was
-error or fatal error, they contain the actual severity bits,
-which turns out to be a value of 2 for error and 4 for severe_error.
-Fatal is another term for the severe_error status.
-
-As a result, C<$?> will always be zero if the subprocess's exit
-status indicated successful completion, and non-zero if a
-warning or error occurred or a program compliant with encoding
-_POSIX_EXIT values was run and set a status.
-
-How can you tell the difference between a non-zero status that is
-the result of a VMS native error status or an encoded Unix status?
-You can not unless you look at the ${^CHILD_ERROR_NATIVE} value.
-The ${^CHILD_ERROR_NATIVE} value returns the actual VMS status value
-and check the severity bits. If the severity bits are equal to 1,
-then if the numeric value for C<$?> is between 2 and 255 or 0, then
-C<$?> accurately reflects a value passed back from a Unix application.
-If C<$?> is 1, and the severity bits indicate a VMS error (2), then
-C<$?> is from a Unix application exit value.
-
-In practice, Perl scripts that call programs that return _POSIX_EXIT
-type status values will be expecting those values, and programs that
-call traditional VMS programs will either be expecting the previous
-behavior or just checking for a non-zero status.
-
-And success is always the value 0 in all behaviors.
-
-When the actual VMS termination status of the child is an error,
-internally the C<$!> value will be set to the closest Unix errno
-value to that error so that Perl scripts that test for error
-messages will see the expected Unix style error message instead
-of a VMS message.
-
-Conversely, when setting C<$?> in an END block, an attempt is made
-to convert the POSIX value into a native status intelligible to
-the operating system upon exiting Perl. What this boils down to
-is that setting C<$?> to zero results in the generic success value
-SS$_NORMAL, and setting C<$?> to a non-zero value results in the
-generic failure status SS$_ABORT. See also L<perlport/exit>.
-
-With the C<PERL_VMS_POSIX_EXIT> logical name defined as "ENABLE",
-setting C<$?> will cause the new value to be encoded into C<$^E>
-so that either the original parent or child exit status values
- 0 to 255 can be automatically recovered by C programs expecting
-_POSIX_EXIT behavior. If both a parent and a child exit value are
-non-zero, then it will be assumed that this is actually a VMS native
-status value to be passed through. The special value of 0xFFFF is
-almost a NOOP as it will cause the current native VMS status in the
-C library to become the current native Perl VMS status, and is handled
-this way as it is known to not be a valid native VMS status value.
-It is recommend that only values in the range of normal Unix parent or
-child status numbers, 0 to 255 are used.
-
-The pragma C<use vmsish 'status'> makes C<$?> reflect the actual
-VMS exit status instead of the default emulation of POSIX status
-described above. This pragma also disables the conversion of
-non-zero values to SS$_ABORT when setting C<$?> in an END
-block (but zero will still be converted to SS$_NORMAL).
-
-Do not use the pragma C<use vmsish 'status'> with C<PERL_VMS_POSIX_EXIT>
-enabled, as they are at times requesting conflicting actions and the
-consequence of ignoring this advice will be undefined to allow future
-improvements in the POSIX exit handling.
-
-In general, with C<PERL_VMS_POSIX_EXIT> enabled, more detailed information
-will be available in the exit status for DCL scripts or other native VMS tools,
-and will give the expected information for Posix programs. It has not been
-made the default in order to preserve backward compatibility.
-
-N.B. Setting C<DECC$FILENAME_UNIX_REPORT> implicitly enables
-C<PERL_VMS_POSIX_EXIT>.
-
-=item $|
-
-Setting C<$|> for an I/O stream causes data to be flushed
-all the way to disk on each write (I<i.e.> not just to
-the underlying RMS buffers for a file). In other words,
-it's equivalent to calling fflush() and fsync() from C.
-
-=back
-
-=head1 Standard modules with VMS-specific differences
-
-=head2 SDBM_File
-
-SDBM_File works properly on VMS. It has, however, one minor
-difference. The database directory file created has a F<.sdbm_dir>
-extension rather than a F<.dir> extension. F<.dir> files are VMS filesystem
-directory files, and using them for other purposes could cause unacceptable
-problems.
-
-=head1 Revision date
-
-Please see the git repository for revision history.
-
-=head1 AUTHOR
-
-Charles Bailey bailey@cor.newman.upenn.edu
-Craig Berry craigberry@mac.com
-Dan Sugalski dan@sidhe.org
-John Malmberg wb8tyw@qsl.net
diff --git a/Master/tlpkg/tlperl/lib/pods/perlvos.pod b/Master/tlpkg/tlperl/lib/pods/perlvos.pod
deleted file mode 100644
index 28cc9d130dd..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlvos.pod
+++ /dev/null
@@ -1,169 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see pod/perlpod.pod) which is
-specially designed to be readable as is.
-
-=head1 NAME
-
-perlvos - Perl for Stratus VOS
-
-=head1 SYNOPSIS
-
-This file contains notes for building perl on the Stratus VOS
-operating system. Perl is a scripting or macro language that is
-popular on many systems. See L<perlbook> for a number of good
-books on Perl.
-
-These are instructions for building Perl from source. This version of
-Perl is not supported on VOS Release 14.2 or earlier releases. If you
-have a Continuum platform running VOS Release 14.3 through 14.7,
-download Perl from the Stratus Anonymous FTP site at
-ftp://ftp.stratus.com/pub/vos/posix/ga/continuum/continuum.html. If
-you have a V Series platform running VOS Release 15.0 or later, or if
-you have a V Series platform running OpenVOS Release 17.0 or later,
-download Perl from
-ftp://ftp.stratus.com/pub/vos/posix/ga/v-series/v-series.html. The
-perl distribution files on the Stratus anonymous FTP site are stored
-in a format called a "bundled file". Instructions for unbundling the
-Perl distribution file are at
-ftp://ftp.stratus.com/pub/vos/utility/utility.html.
-
-If you are running VOS Release 14.4.1 or later, you can obtain a
-pre-compiled, supported copy of perl by purchasing Release 2.0.1
-(or later) of the VOS GNU C/C++ and GNU Tools product from
-Stratus Technologies.
-
-=head1 BUILDING PERL FOR VOS
-
-To build perl from its source code on the Stratus Continuum
-platform, you must be have VOS Release 14.5.0 or later, the STCP
-product, and the GNU C/C++ and GNU Tools, Release 2.0.1 or
-later. On the V Series platform you must have VOS Release
-15.0.0 or later, and any version of the GNU C/C++ and GNU Tools
-product.
-
-To build full perl using the supplied Configure script and
-makefiles, change to the "vos" subdirectory and type the command
-"compile_full_perl" or "start_process compile_full_perl". This
-will configure, build, and test perl.
-
-=head1 INSTALLING PERL IN VOS
-
-=over 4
-
-=item 1
-
-If you have built perl using the Configure script, ensure that
-you have modify and default write permission to C<<
->system>ported >> and all subdirectories. Then type
-
- gmake install
-
-=item 2
-
-While there are currently no architecture-specific extensions or
-modules distributed with perl, the following directories can be
-used to hold such files (replace the string VERSION by the
-appropriate version number):
-
- >system>ported>lib>perl5>VERSION>7100
- >system>ported>lib>perl5>VERSION>8000
- >system>ported>lib>perl5>VERSION>i786
-
-=item 3
-
-Site-specific perl extensions and modules can be installed in one of
-two places. Put architecture-independent files into:
-
- >system>ported>lib>perl5>site_perl>VERSION
-
-Put site-specific architecture-dependent files into one of the
-following directories:
-
- >system>ported>lib>perl5>site_perl>VERSION>7100
- >system>ported>lib>perl5>site_perl>VERSION>8000
- >system>ported>lib>perl5>site_perl>VERSION>i786
-
-=item 4
-
-You can examine the @INC variable from within a perl program
-to see the order in which Perl searches these directories.
-
-=back
-
-=head1 USING PERL IN VOS
-
-=head2 Restrictions of Perl on VOS
-
-This port of Perl version 5 to VOS prefers Unix-style,
-slash-separated pathnames over VOS-style greater-than-separated
-pathnames. VOS-style pathnames should work in most contexts, but
-if you have trouble, replace all greater-than characters by slash
-characters. Because the slash character is used as a pathname
-delimiter, Perl cannot process VOS pathnames containing a slash
-character in a directory or file name; these must be renamed.
-
-This port of Perl also uses Unix-epoch date values internally.
-As long as you are dealing with ASCII character string
-representations of dates, this should not be an issue. The
-supported epoch is January 1, 1980 to January 17, 2038.
-
-See the file pod/perlport.pod for more information about the VOS
-port of Perl.
-
-=head2 Handling of underflow and overflow
-
-Prior to VOS Release 14.7.0, VOS does not support automatically
-mapping overflowed floating-point values to +infinity, nor
-automatically mapping underflowed floating-point values to zero,
-unlike many other platforms. The Perl pack function has been
-modified to perform such mapping in software on VOS. Performing
-other floating-point computations that underflow or overflow
-will probably result in SIGFPE. Don't push your luck.
-
-As of VOS Release 14.7.0 or later, the VOS POSIX runtime sets up
-the PA-RISC and IA-32 hardware floating-point status register so
-that the overflow and underflow exceptions do not trap, but
-instead automatically convert the result to infinity or zero, as
-appropriate. As of this writing, there are still floating-point
-operations that can trap, for example, subtracting two infinite
-values. This is recorded as suggestion posix-1022, which has
-been fixed in VOS Release 15.2 and higher.
-
-=head1 TEST STATUS
-
-When Perl 5.9.0 is built using the native build process on VOS
-Release 14.7.0 and GNU C++/GNU Tools 2.0.2a, all but nine
-attempted tests either pass or result in TODO (ignored)
-failures. The tests that fail are:
-
-t/io/dup, test 2
-t/io/tell, test 28
-t/op/pack, test 0
-ext/B/t/bytecode, test 1
-ext/Devel/Peek/t/Peek, test 1
-ext/Encode/t/enc_module, test 1
-ext/IO/t/io_dup, test 2
-lib/ExtUtils/t/MM_Unix, test 94
-lib/Net/ing/t/450_service, test 8
-
-=head1 SUPPORT STATUS
-
-I'm offering this port "as is". You can ask me questions, but I
-can't guarantee I'll be able to answer them. There are some
-excellent books available on the Perl language; consult a book
-seller.
-
-If you want a supported version of perl for VOS, purchase the
-VOS GNU C/C++ and GNU Tools Release 2.0.1 (or later) product from
-Stratus Technologies, along with a support contract (or from
-anyone else who will sell you support).
-
-=head1 AUTHOR
-
-Paul Green (Paul.Green@stratus.com)
-
-=head1 LAST UPDATE
-
-October 6, 2010
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlwin32.pod b/Master/tlpkg/tlperl/lib/pods/perlwin32.pod
deleted file mode 100644
index 7095f75a261..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlwin32.pod
+++ /dev/null
@@ -1,895 +0,0 @@
-If you read this file _as_is_, just ignore the funny characters you
-see. It is written in the POD format (see pod/perlpod.pod) which is
-specially designed to be readable as is.
-
-=head1 NAME
-
-perlwin32 - Perl under Windows
-
-=head1 SYNOPSIS
-
-These are instructions for building Perl under Windows 2000 and later.
-
-=head1 DESCRIPTION
-
-Before you start, you should glance through the README file
-found in the top-level directory to which the Perl distribution
-was extracted. Make sure you read and understand the terms under
-which this software is being distributed.
-
-Also make sure you read L<BUGS AND CAVEATS> below for the
-known limitations of this port.
-
-The INSTALL file in the perl top-level has much information that is
-only relevant to people building Perl on Unix-like systems. In
-particular, you can safely ignore any information that talks about
-"Configure".
-
-You may also want to look at one other option for building a perl that
-will work on Windows: the README.cygwin file, which give a different
-set of rules to build a perl for Windows. This method will probably
-enable you to build a more Unix-compatible perl, but you will also
-need to download and use various other build-time and run-time support
-software described in that file.
-
-This set of instructions is meant to describe a so-called "native"
-port of Perl to the Windows platform. This includes both 32-bit and
-64-bit Windows operating systems. The resulting Perl requires no
-additional software to run (other than what came with your operating
-system). Currently, this port is capable of using one of the
-following compilers on the Intel x86 architecture:
-
- Microsoft Visual C++ version 6.0 or later
- Gcc by mingw.org gcc version 3.2 or later
- Gcc by mingw-w64.sf.net gcc version 4.4.3 or later
-
-Note that the last two of these are actually competing projects both
-delivering complete gcc toolchain for MS Windows:
-
-=over 4
-
-=item L<http://mingw.org>
-
-Delivers gcc toolchain targeting 32-bit Windows platform.
-
-=item L<http://mingw-w64.sf.net>
-
-Delivers gcc toolchain targeting both 64-bit Windows and 32-bit Windows
-platforms (despite the project name "mingw-w64" they are not only 64-bit
-oriented). They deliver the native gcc compilers and cross-compilers
-that are also supported by perl's makefile.
-
-=back
-
-The Microsoft Visual C++ compilers are also now being given away free. They are
-available as "Visual C++ Toolkit 2003" or "Visual C++ 2005/2008/2010 Express
-Edition" (and also as part of the ".NET Framework SDK") and are the same
-compilers that ship with "Visual C++ .NET 2003 Professional" or "Visual C++
-2005/2008/2010 Professional" respectively.
-
-This port can also be built on IA64/AMD64 using:
-
- Microsoft Platform SDK Nov 2001 (64-bit compiler and tools)
- MinGW64 compiler (gcc version 4.4.3 or later)
-
-The Windows SDK can be downloaded from L<http://www.microsoft.com/>.
-The MinGW64 compiler is available at L<http://sourceforge.net/projects/mingw-w64>.
-The latter is actually a cross-compiler targeting Win64. There's also a trimmed
-down compiler (no java, or gfortran) suitable for building perl available at:
-L<http://strawberryperl.com/package/kmx/64_gcctoolchain/>
-
-NOTE: If you're using a 32-bit compiler to build perl on a 64-bit Windows
-operating system, then you should set the WIN64 environment variable to "undef".
-Also, the trimmed down compiler only passes tests when USE_ITHREADS *= define
-(as opposed to undef) and when the CFG *= Debug line is commented out.
-
-This port fully supports MakeMaker (the set of modules that
-is used to build extensions to perl). Therefore, you should be
-able to build and install most extensions found in the CPAN sites.
-See L<Usage Hints for Perl on Windows> below for general hints about this.
-
-=head2 Setting Up Perl on Windows
-
-=over 4
-
-=item Make
-
-You need a "make" program to build the sources. If you are using
-Visual C++ or the Windows SDK tools, nmake will work. Builds using
-the gcc need dmake.
-
-dmake is a freely available make that has very nice macro features
-and parallelability.
-
-A port of dmake for Windows is available from:
-
-L<http://search.cpan.org/dist/dmake/>
-
-Fetch and install dmake somewhere on your path.
-
-=item Command Shell
-
-Use the default "cmd" shell that comes with Windows. Some versions of the
-popular 4DOS/NT shell have incompatibilities that may cause you trouble.
-If the build fails under that shell, try building again with the cmd
-shell.
-
-Make sure the path to the build directory does not contain spaces. The
-build usually works in this circumstance, but some tests will fail.
-
-=item Microsoft Visual C++
-
-The nmake that comes with Visual C++ will suffice for building.
-You will need to run the VCVARS32.BAT file, usually found somewhere
-like C:\Program Files\Microsoft Visual Studio\VC98\Bin.
-This will set your build environment.
-
-You can also use dmake to build using Visual C++; provided, however,
-you set OSRELEASE to "microsft" (or whatever the directory name
-under which the Visual C dmake configuration lives) in your environment
-and edit win32/config.vc to change "make=nmake" into "make=dmake". The
-latter step is only essential if you want to use dmake as your default
-make for building extensions using MakeMaker.
-
-=item Microsoft Visual C++ 2008/2010 Express Edition
-
-These free versions of Visual C++ 2008/2010 Professional contain the same
-compilers and linkers that ship with the full versions, and also contain
-everything necessary to build Perl, rather than requiring a separate download
-of the Windows SDK like previous versions did.
-
-These packages can be downloaded by searching in the Download Center at
-L<http://www.microsoft.com/downloads/search.aspx?displaylang=en>. (Providing exact
-links to these packages has proven a pointless task because the links keep on
-changing so often.)
-
-Install Visual C++ 2008/2010 Express, then setup your environment using, e.g.
-
- C:\Program Files\Microsoft Visual Studio 10.0\Common7\Tools\vsvars32.bat
-
-(assuming the default installation location was chosen).
-
-Perl should now build using the win32/Makefile. You will need to edit that
-file to set CCTYPE to MSVC90FREE or MSVC100FREE first.
-
-=item Microsoft Visual C++ 2005 Express Edition
-
-This free version of Visual C++ 2005 Professional contains the same compiler
-and linker that ship with the full version, but doesn't contain everything
-necessary to build Perl.
-
-You will also need to download the "Windows SDK" (the "Core SDK" and "MDAC
-SDK" components are required) for more header files and libraries.
-
-These packages can both be downloaded by searching in the Download Center at
-L<http://www.microsoft.com/downloads/search.aspx?displaylang=en>. (Providing exact
-links to these packages has proven a pointless task because the links keep on
-changing so often.)
-
-Try to obtain the latest version of the Windows SDK. Sometimes these packages
-contain a particular Windows OS version in their name, but actually work on
-other OS versions too. For example, the "Windows Server 2003 R2 Platform SDK"
-also runs on Windows XP SP2 and Windows 2000.
-
-Install Visual C++ 2005 first, then the Platform SDK. Setup your environment
-as follows (assuming default installation locations were chosen):
-
- SET PlatformSDKDir=C:\Program Files\Microsoft Platform SDK
-
- SET PATH=%SystemRoot%\system32;%SystemRoot%;C:\Program Files\Microsoft Visual Studio 8\Common7\IDE;C:\Program Files\Microsoft Visual Studio 8\VC\BIN;C:\Program Files\Microsoft Visual Studio 8\Common7\Tools;C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\bin;C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727;C:\Program Files\Microsoft Visual Studio 8\VC\VCPackages;%PlatformSDKDir%\Bin
-
- SET INCLUDE=C:\Program Files\Microsoft Visual Studio 8\VC\INCLUDE;%PlatformSDKDir%\include
-
- SET LIB=C:\Program Files\Microsoft Visual Studio 8\VC\LIB;C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\lib;%PlatformSDKDir%\lib
-
- SET LIBPATH=C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727
-
-(The PlatformSDKDir might need to be set differently depending on which version
-you are using. Earlier versions installed into "C:\Program Files\Microsoft SDK",
-while the latest versions install into version-specific locations such as
-"C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2".)
-
-Perl should now build using the win32/Makefile. You will need to edit that
-file to set
-
- CCTYPE = MSVC80FREE
-
-and to set CCHOME, CCINCDIR and CCLIBDIR as per the environment setup above.
-
-=item Microsoft Visual C++ Toolkit 2003
-
-This free toolkit contains the same compiler and linker that ship with
-Visual C++ .NET 2003 Professional, but doesn't contain everything
-necessary to build Perl.
-
-You will also need to download the "Platform SDK" (the "Core SDK" and "MDAC
-SDK" components are required) for header files, libraries and rc.exe, and
-".NET Framework SDK" for more libraries and nmake.exe. Note that the latter
-(which also includes the free compiler and linker) requires the ".NET
-Framework Redistributable" to be installed first. This can be downloaded and
-installed separately, but is included in the "Visual C++ Toolkit 2003" anyway.
-
-These packages can all be downloaded by searching in the Download Center at
-L<http://www.microsoft.com/downloads/search.aspx?displaylang=en>. (Providing exact
-links to these packages has proven a pointless task because the links keep on
-changing so often.)
-
-Try to obtain the latest version of the Windows SDK. Sometimes these packages
-contain a particular Windows OS version in their name, but actually work on
-other OS versions too. For example, the "Windows Server 2003 R2 Platform SDK"
-also runs on Windows XP SP2 and Windows 2000.
-
-Install the Toolkit first, then the Platform SDK, then the .NET Framework SDK.
-Setup your environment as follows (assuming default installation locations
-were chosen):
-
- SET PlatformSDKDir=C:\Program Files\Microsoft Platform SDK
-
- SET PATH=%SystemRoot%\system32;%SystemRoot%;C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin;%PlatformSDKDir%\Bin;C:\Program Files\Microsoft.NET\SDK\v1.1\Bin
-
- SET INCLUDE=C:\Program Files\Microsoft Visual C++ Toolkit 2003\include;%PlatformSDKDir%\include;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\include
-
- SET LIB=C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib;%PlatformSDKDir%\lib;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\lib
-
-(The PlatformSDKDir might need to be set differently depending on which version
-you are using. Earlier versions installed into "C:\Program Files\Microsoft SDK",
-while the latest versions install into version-specific locations such as
-"C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2".)
-
-Several required files will still be missing:
-
-=over 4
-
-=item *
-
-cvtres.exe is required by link.exe when using a .res file. It is actually
-installed by the .NET Framework SDK, but into a location such as the
-following:
-
- C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322
-
-Copy it from there to %PlatformSDKDir%\Bin
-
-=item *
-
-lib.exe is normally used to build libraries, but link.exe with the /lib
-option also works, so change win32/config.vc to use it instead:
-
-Change the line reading:
-
- ar='lib'
-
-to:
-
- ar='link /lib'
-
-It may also be useful to create a batch file called lib.bat in
-C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin containing:
-
- @echo off
- link /lib %*
-
-for the benefit of any naughty C extension modules that you might want to build
-later which explicitly reference "lib" rather than taking their value from
-$Config{ar}.
-
-=item *
-
-setargv.obj is required to build perlglob.exe (and perl.exe if the USE_SETARGV
-option is enabled). The Platform SDK supplies this object file in source form
-in %PlatformSDKDir%\src\crt. Copy setargv.c, cruntime.h and
-internal.h from there to some temporary location and build setargv.obj using
-
- cl.exe /c /I. /D_CRTBLD setargv.c
-
-Then copy setargv.obj to %PlatformSDKDir%\lib
-
-Alternatively, if you don't need perlglob.exe and don't need to enable the
-USE_SETARGV option then you can safely just remove all mention of $(GLOBEXE)
-from win32/Makefile and setargv.obj won't be required anyway.
-
-=back
-
-Perl should now build using the win32/Makefile. You will need to edit that
-file to set
-
- CCTYPE = MSVC70FREE
-
-and to set CCHOME, CCINCDIR and CCLIBDIR as per the environment setup above.
-
-=item Microsoft Platform SDK 64-bit Compiler
-
-The nmake that comes with the Platform SDK will suffice for building
-Perl. Make sure you are building within one of the "Build Environment"
-shells available after you install the Platform SDK from the Start Menu.
-
-=item MinGW release 3 with gcc
-
-Perl can be compiled with gcc from MinGW release 3 and later (using gcc 3.2.x
-and later). It can be downloaded here:
-
-L<http://www.mingw.org/>
-
-You also need dmake. See L</"Make"> above on how to get it.
-
-=back
-
-=head2 Building
-
-=over 4
-
-=item *
-
-Make sure you are in the "win32" subdirectory under the perl toplevel.
-This directory contains a "Makefile" that will work with
-versions of nmake that come with Visual C++ or the Windows SDK, and
-a dmake "makefile.mk" that will work for all supported compilers. The
-defaults in the dmake makefile are setup to build using MinGW/gcc.
-
-=item *
-
-Edit the makefile.mk (or Makefile, if you're using nmake) and change
-the values of INST_DRV and INST_TOP. You can also enable various
-build flags. These are explained in the makefiles.
-
-Note that it is generally not a good idea to try to build a perl with
-INST_DRV and INST_TOP set to a path that already exists from a previous
-build. In particular, this may cause problems with the
-lib/ExtUtils/t/Embed.t test, which attempts to build a test program and
-may end up building against the installed perl's lib/CORE directory rather
-than the one being tested.
-
-You will have to make sure that CCTYPE is set correctly and that
-CCHOME points to wherever you installed your compiler.
-
-If building with the cross-compiler provided by
-mingw-w64.sourceforge.net you'll need to uncomment the line that sets
-GCCCROSS in the makefile.mk. Do this only if it's the cross-compiler - ie
-only if the bin folder doesn't contain a gcc.exe. (The cross-compiler
-does not provide a gcc.exe, g++.exe, ar.exe, etc. Instead, all of these
-executables are prefixed with 'x86_64-w64-mingw32-'.)
-
-The default value for CCHOME in the makefiles for Visual C++
-may not be correct for some versions. Make sure the default exists
-and is valid.
-
-You may also need to comment out the C<DELAYLOAD = ...> line in the
-Makefile if you're using VC++ 6.0 without the latest service pack and
-the linker reports an internal error.
-
-If you want build some core extensions statically into perl's dll, specify
-them in the STATIC_EXT macro.
-
-Be sure to read the instructions near the top of the makefiles carefully.
-
-=item *
-
-Type "dmake" (or "nmake" if you are using that make).
-
-This should build everything. Specifically, it will create perl.exe,
-perl516.dll at the perl toplevel, and various other extension dll's
-under the lib\auto directory. If the build fails for any reason, make
-sure you have done the previous steps correctly.
-
-=back
-
-=head2 Testing Perl on Windows
-
-Type "dmake test" (or "nmake test"). This will run most of the tests from
-the testsuite (many tests will be skipped).
-
-There should be no test failures.
-
-Some test failures may occur if you use a command shell other than the
-native "cmd.exe", or if you are building from a path that contains
-spaces. So don't do that.
-
-If you are running the tests from a emacs shell window, you may see
-failures in op/stat.t. Run "dmake test-notty" in that case.
-
-If you run the tests on a FAT partition, you may see some failures for
-C<link()> related tests (I<op/write.t>, I<op/stat.t> ...). Testing on
-NTFS avoids these errors.
-
-Furthermore, you should make sure that during C<make test> you do not
-have any GNU tool packages in your path: some toolkits like Unixutils
-include some tools (C<type> for instance) which override the Windows
-ones and makes tests fail. Remove them from your path while testing to
-avoid these errors.
-
-Please report any other failures as described under L<BUGS AND CAVEATS>.
-
-=head2 Installation of Perl on Windows
-
-Type "dmake install" (or "nmake install"). This will put the newly
-built perl and the libraries under whatever C<INST_TOP> points to in the
-Makefile. It will also install the pod documentation under
-C<$INST_TOP\$INST_VER\lib\pod> and HTML versions of the same under
-C<$INST_TOP\$INST_VER\lib\pod\html>.
-
-To use the Perl you just installed you will need to add a new entry to
-your PATH environment variable: C<$INST_TOP\bin>, e.g.
-
- set PATH=c:\perl\bin;%PATH%
-
-If you opted to uncomment C<INST_VER> and C<INST_ARCH> in the makefile
-then the installation structure is a little more complicated and you will
-need to add two new PATH components instead: C<$INST_TOP\$INST_VER\bin> and
-C<$INST_TOP\$INST_VER\bin\$ARCHNAME>, e.g.
-
- set PATH=c:\perl\5.6.0\bin;c:\perl\5.6.0\bin\MSWin32-x86;%PATH%
-
-=head2 Usage Hints for Perl on Windows
-
-=over 4
-
-=item Environment Variables
-
-The installation paths that you set during the build get compiled
-into perl, so you don't have to do anything additional to start
-using that perl (except add its location to your PATH variable).
-
-If you put extensions in unusual places, you can set PERL5LIB
-to a list of paths separated by semicolons where you want perl
-to look for libraries. Look for descriptions of other environment
-variables you can set in L<perlrun>.
-
-You can also control the shell that perl uses to run system() and
-backtick commands via PERL5SHELL. See L<perlrun>.
-
-Perl does not depend on the registry, but it can look up certain default
-values if you choose to put them there. Perl attempts to read entries from
-C<HKEY_CURRENT_USER\Software\Perl> and C<HKEY_LOCAL_MACHINE\Software\Perl>.
-Entries in the former override entries in the latter. One or more of the
-following entries (of type REG_SZ or REG_EXPAND_SZ) may be set:
-
- lib-$] version-specific standard library path to add to @INC
- lib standard library path to add to @INC
- sitelib-$] version-specific site library path to add to @INC
- sitelib site library path to add to @INC
- vendorlib-$] version-specific vendor library path to add to @INC
- vendorlib vendor library path to add to @INC
- PERL* fallback for all %ENV lookups that begin with "PERL"
-
-Note the C<$]> in the above is not literal. Substitute whatever version
-of perl you want to honor that entry, e.g. C<5.6.0>. Paths must be
-separated with semicolons, as usual on Windows.
-
-=item File Globbing
-
-By default, perl handles file globbing using the File::Glob extension,
-which provides portable globbing.
-
-If you want perl to use globbing that emulates the quirks of DOS
-filename conventions, you might want to consider using File::DosGlob
-to override the internal glob() implementation. See L<File::DosGlob> for
-details.
-
-=item Using perl from the command line
-
-If you are accustomed to using perl from various command-line
-shells found in UNIX environments, you will be less than pleased
-with what Windows offers by way of a command shell.
-
-The crucial thing to understand about the Windows environment is that
-the command line you type in is processed twice before Perl sees it.
-First, your command shell (usually CMD.EXE) preprocesses the command
-line, to handle redirection, environment variable expansion, and
-location of the executable to run. Then, the perl executable splits
-the remaining command line into individual arguments, using the
-C runtime library upon which Perl was built.
-
-It is particularly important to note that neither the shell nor the C
-runtime do any wildcard expansions of command-line arguments (so
-wildcards need not be quoted). Also, the quoting behaviours of the
-shell and the C runtime are rudimentary at best (and may, if you are
-using a non-standard shell, be inconsistent). The only (useful) quote
-character is the double quote ("). It can be used to protect spaces
-and other special characters in arguments.
-
-The Windows documentation describes the shell parsing rules here:
-L<http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/cmd.mspx?mfr=true>
-and the C runtime parsing rules here:
-L<http://msdn.microsoft.com/en-us/library/17w5ykft%28v=VS.100%29.aspx>.
-
-Here are some further observations based on experiments: The C runtime
-breaks arguments at spaces and passes them to programs in argc/argv.
-Double quotes can be used to prevent arguments with spaces in them from
-being split up. You can put a double quote in an argument by escaping
-it with a backslash and enclosing the whole argument within double quotes.
-The backslash and the pair of double quotes surrounding the argument will
-be stripped by the C runtime.
-
-The file redirection characters "E<lt>", "E<gt>", and "|" can be quoted by
-double quotes (although there are suggestions that this may not always
-be true). Single quotes are not treated as quotes by the shell or
-the C runtime, they don't get stripped by the shell (just to make
-this type of quoting completely useless). The caret "^" has also
-been observed to behave as a quoting character, but this appears
-to be a shell feature, and the caret is not stripped from the command
-line, so Perl still sees it (and the C runtime phase does not treat
-the caret as a quote character).
-
-Here are some examples of usage of the "cmd" shell:
-
-This prints two doublequotes:
-
- perl -e "print '\"\"' "
-
-This does the same:
-
- perl -e "print \"\\\"\\\"\" "
-
-This prints "bar" and writes "foo" to the file "blurch":
-
- perl -e "print 'foo'; print STDERR 'bar'" > blurch
-
-This prints "foo" ("bar" disappears into nowhereland):
-
- perl -e "print 'foo'; print STDERR 'bar'" 2> nul
-
-This prints "bar" and writes "foo" into the file "blurch":
-
- perl -e "print 'foo'; print STDERR 'bar'" 1> blurch
-
-This pipes "foo" to the "less" pager and prints "bar" on the console:
-
- perl -e "print 'foo'; print STDERR 'bar'" | less
-
-This pipes "foo\nbar\n" to the less pager:
-
- perl -le "print 'foo'; print STDERR 'bar'" 2>&1 | less
-
-This pipes "foo" to the pager and writes "bar" in the file "blurch":
-
- perl -e "print 'foo'; print STDERR 'bar'" 2> blurch | less
-
-
-Discovering the usefulness of the "command.com" shell on Windows 9x
-is left as an exercise to the reader :)
-
-One particularly pernicious problem with the 4NT command shell for
-Windows is that it (nearly) always treats a % character as indicating
-that environment variable expansion is needed. Under this shell, it is
-therefore important to always double any % characters which you want
-Perl to see (for example, for hash variables), even when they are
-quoted.
-
-=item Building Extensions
-
-The Comprehensive Perl Archive Network (CPAN) offers a wealth
-of extensions, some of which require a C compiler to build.
-Look in L<http://www.cpan.org/> for more information on CPAN.
-
-Note that not all of the extensions available from CPAN may work
-in the Windows environment; you should check the information at
-L<http://testers.cpan.org/> before investing too much effort into
-porting modules that don't readily build.
-
-Most extensions (whether they require a C compiler or not) can
-be built, tested and installed with the standard mantra:
-
- perl Makefile.PL
- $MAKE
- $MAKE test
- $MAKE install
-
-where $MAKE is whatever 'make' program you have configured perl to
-use. Use "perl -V:make" to find out what this is. Some extensions
-may not provide a testsuite (so "$MAKE test" may not do anything or
-fail), but most serious ones do.
-
-It is important that you use a supported 'make' program, and
-ensure Config.pm knows about it. If you don't have nmake, you can
-either get dmake from the location mentioned earlier or get an
-old version of nmake reportedly available from:
-
-L<http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe>
-
-Another option is to use the make written in Perl, available from
-CPAN.
-
-L<http://www.cpan.org/modules/by-module/Make/>
-
-You may also use dmake. See L</"Make"> above on how to get it.
-
-Note that MakeMaker actually emits makefiles with different syntax
-depending on what 'make' it thinks you are using. Therefore, it is
-important that one of the following values appears in Config.pm:
-
- make='nmake' # MakeMaker emits nmake syntax
- make='dmake' # MakeMaker emits dmake syntax
- any other value # MakeMaker emits generic make syntax
- (e.g GNU make, or Perl make)
-
-If the value doesn't match the 'make' program you want to use,
-edit Config.pm to fix it.
-
-If a module implements XSUBs, you will need one of the supported
-C compilers. You must make sure you have set up the environment for
-the compiler for command-line compilation.
-
-If a module does not build for some reason, look carefully for
-why it failed, and report problems to the module author. If
-it looks like the extension building support is at fault, report
-that with full details of how the build failed using the perlbug
-utility.
-
-=item Command-line Wildcard Expansion
-
-The default command shells on DOS descendant operating systems (such
-as they are) usually do not expand wildcard arguments supplied to
-programs. They consider it the application's job to handle that.
-This is commonly achieved by linking the application (in our case,
-perl) with startup code that the C runtime libraries usually provide.
-However, doing that results in incompatible perl versions (since the
-behavior of the argv expansion code differs depending on the
-compiler, and it is even buggy on some compilers). Besides, it may
-be a source of frustration if you use such a perl binary with an
-alternate shell that *does* expand wildcards.
-
-Instead, the following solution works rather well. The nice things
-about it are 1) you can start using it right away; 2) it is more
-powerful, because it will do the right thing with a pattern like
-*/*/*.c; 3) you can decide whether you do/don't want to use it; and
-4) you can extend the method to add any customizations (or even
-entirely different kinds of wildcard expansion).
-
- C:\> copy con c:\perl\lib\Wild.pm
- # Wild.pm - emulate shell @ARGV expansion on shells that don't
- use File::DosGlob;
- @ARGV = map {
- my @g = File::DosGlob::glob($_) if /[*?]/;
- @g ? @g : $_;
- } @ARGV;
- 1;
- ^Z
- C:\> set PERL5OPT=-MWild
- C:\> perl -le "for (@ARGV) { print }" */*/perl*.c
- p4view/perl/perl.c
- p4view/perl/perlio.c
- p4view/perl/perly.c
- perl5.005/win32/perlglob.c
- perl5.005/win32/perllib.c
- perl5.005/win32/perlglob.c
- perl5.005/win32/perllib.c
- perl5.005/win32/perlglob.c
- perl5.005/win32/perllib.c
-
-Note there are two distinct steps there: 1) You'll have to create
-Wild.pm and put it in your perl lib directory. 2) You'll need to
-set the PERL5OPT environment variable. If you want argv expansion
-to be the default, just set PERL5OPT in your default startup
-environment.
-
-If you are using the Visual C compiler, you can get the C runtime's
-command line wildcard expansion built into perl binary. The resulting
-binary will always expand unquoted command lines, which may not be
-what you want if you use a shell that does that for you. The expansion
-done is also somewhat less powerful than the approach suggested above.
-
-=item Notes on 64-bit Windows
-
-Windows .NET Server supports the LLP64 data model on the Intel Itanium
-architecture.
-
-The LLP64 data model is different from the LP64 data model that is the
-norm on 64-bit Unix platforms. In the former, C<int> and C<long> are
-both 32-bit data types, while pointers are 64 bits wide. In addition,
-there is a separate 64-bit wide integral type, C<__int64>. In contrast,
-the LP64 data model that is pervasive on Unix platforms provides C<int>
-as the 32-bit type, while both the C<long> type and pointers are of
-64-bit precision. Note that both models provide for 64-bits of
-addressability.
-
-64-bit Windows running on Itanium is capable of running 32-bit x86
-binaries transparently. This means that you could use a 32-bit build
-of Perl on a 64-bit system. Given this, why would one want to build
-a 64-bit build of Perl? Here are some reasons why you would bother:
-
-=over
-
-=item *
-
-A 64-bit native application will run much more efficiently on
-Itanium hardware.
-
-=item *
-
-There is no 2GB limit on process size.
-
-=item *
-
-Perl automatically provides large file support when built under
-64-bit Windows.
-
-=item *
-
-Embedding Perl inside a 64-bit application.
-
-=back
-
-=back
-
-=head2 Running Perl Scripts
-
-Perl scripts on UNIX use the "#!" (a.k.a "shebang") line to
-indicate to the OS that it should execute the file using perl.
-Windows has no comparable means to indicate arbitrary files are
-executables.
-
-Instead, all available methods to execute plain text files on
-Windows rely on the file "extension". There are three methods
-to use this to execute perl scripts:
-
-=over 8
-
-=item 1
-
-There is a facility called "file extension associations". This can be
-manipulated via the two commands "assoc" and "ftype" that come
-standard with Windows. Type "ftype /?" for a complete example of how
-to set this up for perl scripts (Say what? You thought Windows
-wasn't perl-ready? :).
-
-=item 2
-
-Since file associations don't work everywhere, and there are
-reportedly bugs with file associations where it does work, the
-old method of wrapping the perl script to make it look like a
-regular batch file to the OS, may be used. The install process
-makes available the "pl2bat.bat" script which can be used to wrap
-perl scripts into batch files. For example:
-
- pl2bat foo.pl
-
-will create the file "FOO.BAT". Note "pl2bat" strips any
-.pl suffix and adds a .bat suffix to the generated file.
-
-If you use the 4DOS/NT or similar command shell, note that
-"pl2bat" uses the "%*" variable in the generated batch file to
-refer to all the command line arguments, so you may need to make
-sure that construct works in batch files. As of this writing,
-4DOS/NT users will need a "ParameterChar = *" statement in their
-4NT.INI file or will need to execute "setdos /p*" in the 4DOS/NT
-startup file to enable this to work.
-
-=item 3
-
-Using "pl2bat" has a few problems: the file name gets changed,
-so scripts that rely on C<$0> to find what they must do may not
-run properly; running "pl2bat" replicates the contents of the
-original script, and so this process can be maintenance intensive
-if the originals get updated often. A different approach that
-avoids both problems is possible.
-
-A script called "runperl.bat" is available that can be copied
-to any filename (along with the .bat suffix). For example,
-if you call it "foo.bat", it will run the file "foo" when it is
-executed. Since you can run batch files on Windows platforms simply
-by typing the name (without the extension), this effectively
-runs the file "foo", when you type either "foo" or "foo.bat".
-With this method, "foo.bat" can even be in a different location
-than the file "foo", as long as "foo" is available somewhere on
-the PATH. If your scripts are on a filesystem that allows symbolic
-links, you can even avoid copying "runperl.bat".
-
-Here's a diversion: copy "runperl.bat" to "runperl", and type
-"runperl". Explain the observed behavior, or lack thereof. :)
-Hint: .gnidnats llits er'uoy fi ,"lrepnur" eteled :tniH
-
-=back
-
-=head2 Miscellaneous Things
-
-A full set of HTML documentation is installed, so you should be
-able to use it if you have a web browser installed on your
-system.
-
-C<perldoc> is also a useful tool for browsing information contained
-in the documentation, especially in conjunction with a pager
-like C<less> (recent versions of which have Windows support). You may
-have to set the PAGER environment variable to use a specific pager.
-"perldoc -f foo" will print information about the perl operator
-"foo".
-
-One common mistake when using this port with a GUI library like C<Tk>
-is assuming that Perl's normal behavior of opening a command-line
-window will go away. This isn't the case. If you want to start a copy
-of C<perl> without opening a command-line window, use the C<wperl>
-executable built during the installation process. Usage is exactly
-the same as normal C<perl> on Windows, except that options like C<-h>
-don't work (since they need a command-line window to print to).
-
-If you find bugs in perl, you can run C<perlbug> to create a
-bug report (you may have to send it manually if C<perlbug> cannot
-find a mailer on your system).
-
-=head1 BUGS AND CAVEATS
-
-Norton AntiVirus interferes with the build process, particularly if
-set to "AutoProtect, All Files, when Opened". Unlike large applications
-the perl build process opens and modifies a lot of files. Having the
-the AntiVirus scan each and every one slows build the process significantly.
-Worse, with PERLIO=stdio the build process fails with peculiar messages
-as the virus checker interacts badly with miniperl.exe writing configure
-files (it seems to either catch file part written and treat it as suspicious,
-or virus checker may have it "locked" in a way which inhibits miniperl
-updating it). The build does complete with
-
- set PERLIO=perlio
-
-but that may be just luck. Other AntiVirus software may have similar issues.
-
-Some of the built-in functions do not act exactly as documented in
-L<perlfunc>, and a few are not implemented at all. To avoid
-surprises, particularly if you have had prior exposure to Perl
-in other operating environments or if you intend to write code
-that will be portable to other environments, see L<perlport>
-for a reasonably definitive list of these differences.
-
-Not all extensions available from CPAN may build or work properly
-in the Windows environment. See L</"Building Extensions">.
-
-Most C<socket()> related calls are supported, but they may not
-behave as on Unix platforms. See L<perlport> for the full list.
-
-Signal handling may not behave as on Unix platforms (where it
-doesn't exactly "behave", either :). For instance, calling C<die()>
-or C<exit()> from signal handlers will cause an exception, since most
-implementations of C<signal()> on Windows are severely crippled.
-Thus, signals may work only for simple things like setting a flag
-variable in the handler. Using signals under this port should
-currently be considered unsupported.
-
-Please send detailed descriptions of any problems and solutions that
-you may find to E<lt>F<perlbug@perl.org>E<gt>, along with the output
-produced by C<perl -V>.
-
-=head1 ACKNOWLEDGEMENTS
-
-The use of a camel with the topic of Perl is a trademark
-of O'Reilly and Associates, Inc. Used with permission.
-
-=head1 AUTHORS
-
-=over 4
-
-=item Gary Ng E<lt>71564.1743@CompuServe.COME<gt>
-
-=item Gurusamy Sarathy E<lt>gsar@activestate.comE<gt>
-
-=item Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
-
-=item Jan Dubois E<lt>jand@activestate.comE<gt>
-
-=item Steve Hay E<lt>steve.m.hay@googlemail.comE<gt>
-
-=back
-
-This document is maintained by Jan Dubois.
-
-=head1 SEE ALSO
-
-L<perl>
-
-=head1 HISTORY
-
-This port was originally contributed by Gary Ng around 5.003_24,
-and borrowed from the Hip Communications port that was available
-at the time. Various people have made numerous and sundry hacks
-since then.
-
-GCC/mingw32 support was added in 5.005 (Nick Ing-Simmons).
-
-Support for PERL_OBJECT was added in 5.005 (ActiveState Tool Corp).
-
-Support for fork() emulation was added in 5.6 (ActiveState Tool Corp).
-
-Win9x support was added in 5.6 (Benjamin Stuhl).
-
-Support for 64-bit Windows added in 5.8 (ActiveState Corp).
-
-Last updated: 10 September 2011
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/pods/perlxs.pod b/Master/tlpkg/tlperl/lib/pods/perlxs.pod
deleted file mode 100644
index 11fc13c5ff5..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlxs.pod
+++ /dev/null
@@ -1,2123 +0,0 @@
-=head1 NAME
-
-perlxs - XS language reference manual
-
-=head1 DESCRIPTION
-
-=head2 Introduction
-
-XS is an interface description file format used to create an extension
-interface between Perl and C code (or a C library) which one wishes
-to use with Perl. The XS interface is combined with the library to
-create a new library which can then be either dynamically loaded
-or statically linked into perl. The XS interface description is
-written in the XS language and is the core component of the Perl
-extension interface.
-
-An B<XSUB> forms the basic unit of the XS interface. After compilation
-by the B<xsubpp> compiler, each XSUB amounts to a C function definition
-which will provide the glue between Perl calling conventions and C
-calling conventions.
-
-The glue code pulls the arguments from the Perl stack, converts these
-Perl values to the formats expected by a C function, call this C function,
-transfers the return values of the C function back to Perl.
-Return values here may be a conventional C return value or any C
-function arguments that may serve as output parameters. These return
-values may be passed back to Perl either by putting them on the
-Perl stack, or by modifying the arguments supplied from the Perl side.
-
-The above is a somewhat simplified view of what really happens. Since
-Perl allows more flexible calling conventions than C, XSUBs may do much
-more in practice, such as checking input parameters for validity,
-throwing exceptions (or returning undef/empty list) if the return value
-from the C function indicates failure, calling different C functions
-based on numbers and types of the arguments, providing an object-oriented
-interface, etc.
-
-Of course, one could write such glue code directly in C. However, this
-would be a tedious task, especially if one needs to write glue for
-multiple C functions, and/or one is not familiar enough with the Perl
-stack discipline and other such arcana. XS comes to the rescue here:
-instead of writing this glue C code in long-hand, one can write
-a more concise short-hand I<description> of what should be done by
-the glue, and let the XS compiler B<xsubpp> handle the rest.
-
-The XS language allows one to describe the mapping between how the C
-routine is used, and how the corresponding Perl routine is used. It
-also allows creation of Perl routines which are directly translated to
-C code and which are not related to a pre-existing C function. In cases
-when the C interface coincides with the Perl interface, the XSUB
-declaration is almost identical to a declaration of a C function (in K&R
-style). In such circumstances, there is another tool called C<h2xs>
-that is able to translate an entire C header file into a corresponding
-XS file that will provide glue to the functions/macros described in
-the header file.
-
-The XS compiler is called B<xsubpp>. This compiler creates
-the constructs necessary to let an XSUB manipulate Perl values, and
-creates the glue necessary to let Perl call the XSUB. The compiler
-uses B<typemaps> to determine how to map C function parameters
-and output values to Perl values and back. The default typemap
-(which comes with Perl) handles many common C types. A supplementary
-typemap may also be needed to handle any special structures and types
-for the library being linked. For more information on typemaps,
-see L<perlxstypemap>.
-
-A file in XS format starts with a C language section which goes until the
-first C<MODULE =Z<>> directive. Other XS directives and XSUB definitions
-may follow this line. The "language" used in this part of the file
-is usually referred to as the XS language. B<xsubpp> recognizes and
-skips POD (see L<perlpod>) in both the C and XS language sections, which
-allows the XS file to contain embedded documentation.
-
-See L<perlxstut> for a tutorial on the whole extension creation process.
-
-Note: For some extensions, Dave Beazley's SWIG system may provide a
-significantly more convenient mechanism for creating the extension
-glue code. See L<http://www.swig.org/> for more information.
-
-=head2 On The Road
-
-Many of the examples which follow will concentrate on creating an interface
-between Perl and the ONC+ RPC bind library functions. The rpcb_gettime()
-function is used to demonstrate many features of the XS language. This
-function has two parameters; the first is an input parameter and the second
-is an output parameter. The function also returns a status value.
-
- bool_t rpcb_gettime(const char *host, time_t *timep);
-
-From C this function will be called with the following
-statements.
-
- #include <rpc/rpc.h>
- bool_t status;
- time_t timep;
- status = rpcb_gettime( "localhost", &timep );
-
-If an XSUB is created to offer a direct translation between this function
-and Perl, then this XSUB will be used from Perl with the following code.
-The $status and $timep variables will contain the output of the function.
-
- use RPC;
- $status = rpcb_gettime( "localhost", $timep );
-
-The following XS file shows an XS subroutine, or XSUB, which
-demonstrates one possible interface to the rpcb_gettime()
-function. This XSUB represents a direct translation between
-C and Perl and so preserves the interface even from Perl.
-This XSUB will be invoked from Perl with the usage shown
-above. Note that the first three #include statements, for
-C<EXTERN.h>, C<perl.h>, and C<XSUB.h>, will always be present at the
-beginning of an XS file. This approach and others will be
-expanded later in this document.
-
- #include "EXTERN.h"
- #include "perl.h"
- #include "XSUB.h"
- #include <rpc/rpc.h>
-
- MODULE = RPC PACKAGE = RPC
-
- bool_t
- rpcb_gettime(host,timep)
- char *host
- time_t &timep
- OUTPUT:
- timep
-
-Any extension to Perl, including those containing XSUBs,
-should have a Perl module to serve as the bootstrap which
-pulls the extension into Perl. This module will export the
-extension's functions and variables to the Perl program and
-will cause the extension's XSUBs to be linked into Perl.
-The following module will be used for most of the examples
-in this document and should be used from Perl with the C<use>
-command as shown earlier. Perl modules are explained in
-more detail later in this document.
-
- package RPC;
-
- require Exporter;
- require DynaLoader;
- @ISA = qw(Exporter DynaLoader);
- @EXPORT = qw( rpcb_gettime );
-
- bootstrap RPC;
- 1;
-
-Throughout this document a variety of interfaces to the rpcb_gettime()
-XSUB will be explored. The XSUBs will take their parameters in different
-orders or will take different numbers of parameters. In each case the
-XSUB is an abstraction between Perl and the real C rpcb_gettime()
-function, and the XSUB must always ensure that the real rpcb_gettime()
-function is called with the correct parameters. This abstraction will
-allow the programmer to create a more Perl-like interface to the C
-function.
-
-=head2 The Anatomy of an XSUB
-
-The simplest XSUBs consist of 3 parts: a description of the return
-value, the name of the XSUB routine and the names of its arguments,
-and a description of types or formats of the arguments.
-
-The following XSUB allows a Perl program to access a C library function
-called sin(). The XSUB will imitate the C function which takes a single
-argument and returns a single value.
-
- double
- sin(x)
- double x
-
-Optionally, one can merge the description of types and the list of
-argument names, rewriting this as
-
- double
- sin(double x)
-
-This makes this XSUB look similar to an ANSI C declaration. An optional
-semicolon is allowed after the argument list, as in
-
- double
- sin(double x);
-
-Parameters with C pointer types can have different semantic: C functions
-with similar declarations
-
- bool string_looks_as_a_number(char *s);
- bool make_char_uppercase(char *c);
-
-are used in absolutely incompatible manner. Parameters to these functions
-could be described B<xsubpp> like this:
-
- char * s
- char &c
-
-Both these XS declarations correspond to the C<char*> C type, but they have
-different semantics, see L<"The & Unary Operator">.
-
-It is convenient to think that the indirection operator
-C<*> should be considered as a part of the type and the address operator C<&>
-should be considered part of the variable. See L<perlxstypemap>
-for more info about handling qualifiers and unary operators in C types.
-
-The function name and the return type must be placed on
-separate lines and should be flush left-adjusted.
-
- INCORRECT CORRECT
-
- double sin(x) double
- double x sin(x)
- double x
-
-The rest of the function description may be indented or left-adjusted. The
-following example shows a function with its body left-adjusted. Most
-examples in this document will indent the body for better readability.
-
- CORRECT
-
- double
- sin(x)
- double x
-
-More complicated XSUBs may contain many other sections. Each section of
-an XSUB starts with the corresponding keyword, such as INIT: or CLEANUP:.
-However, the first two lines of an XSUB always contain the same data:
-descriptions of the return type and the names of the function and its
-parameters. Whatever immediately follows these is considered to be
-an INPUT: section unless explicitly marked with another keyword.
-(See L<The INPUT: Keyword>.)
-
-An XSUB section continues until another section-start keyword is found.
-
-=head2 The Argument Stack
-
-The Perl argument stack is used to store the values which are
-sent as parameters to the XSUB and to store the XSUB's
-return value(s). In reality all Perl functions (including non-XSUB
-ones) keep their values on this stack all the same time, each limited
-to its own range of positions on the stack. In this document the
-first position on that stack which belongs to the active
-function will be referred to as position 0 for that function.
-
-XSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x>
-refers to a position in this XSUB's part of the stack. Position 0 for that
-function would be known to the XSUB as ST(0). The XSUB's incoming
-parameters and outgoing return values always begin at ST(0). For many
-simple cases the B<xsubpp> compiler will generate the code necessary to
-handle the argument stack by embedding code fragments found in the
-typemaps. In more complex cases the programmer must supply the code.
-
-=head2 The RETVAL Variable
-
-The RETVAL variable is a special C variable that is declared automatically
-for you. The C type of RETVAL matches the return type of the C library
-function. The B<xsubpp> compiler will declare this variable in each XSUB
-with non-C<void> return type. By default the generated C function
-will use RETVAL to hold the return value of the C library function being
-called. In simple cases the value of RETVAL will be placed in ST(0) of
-the argument stack where it can be received by Perl as the return value
-of the XSUB.
-
-If the XSUB has a return type of C<void> then the compiler will
-not declare a RETVAL variable for that function. When using
-a PPCODE: section no manipulation of the RETVAL variable is required, the
-section may use direct stack manipulation to place output values on the stack.
-
-If PPCODE: directive is not used, C<void> return value should be used
-only for subroutines which do not return a value, I<even if> CODE:
-directive is used which sets ST(0) explicitly.
-
-Older versions of this document recommended to use C<void> return
-value in such cases. It was discovered that this could lead to
-segfaults in cases when XSUB was I<truly> C<void>. This practice is
-now deprecated, and may be not supported at some future version. Use
-the return value C<SV *> in such cases. (Currently C<xsubpp> contains
-some heuristic code which tries to disambiguate between "truly-void"
-and "old-practice-declared-as-void" functions. Hence your code is at
-mercy of this heuristics unless you use C<SV *> as return value.)
-
-=head2 Returning SVs, AVs and HVs through RETVAL
-
-When you're using RETVAL to return an C<SV *>, there's some magic
-going on behind the scenes that should be mentioned. When you're
-manipulating the argument stack using the ST(x) macro, for example,
-you usually have to pay special attention to reference counts. (For
-more about reference counts, see L<perlguts>.) To make your life
-easier, the typemap file automatically makes C<RETVAL> mortal when
-you're returning an C<SV *>. Thus, the following two XSUBs are more
-or less equivalent:
-
- void
- alpha()
- PPCODE:
- ST(0) = newSVpv("Hello World",0);
- sv_2mortal(ST(0));
- XSRETURN(1);
-
- SV *
- beta()
- CODE:
- RETVAL = newSVpv("Hello World",0);
- OUTPUT:
- RETVAL
-
-This is quite useful as it usually improves readability. While
-this works fine for an C<SV *>, it's unfortunately not as easy
-to have C<AV *> or C<HV *> as a return value. You I<should> be
-able to write:
-
- AV *
- array()
- CODE:
- RETVAL = newAV();
- /* do something with RETVAL */
- OUTPUT:
- RETVAL
-
-But due to an unfixable bug (fixing it would break lots of existing
-CPAN modules) in the typemap file, the reference count of the C<AV *>
-is not properly decremented. Thus, the above XSUB would leak memory
-whenever it is being called. The same problem exists for C<HV *>,
-C<CV *>, and C<SVREF> (which indicates a scalar reference, not
-a general C<SV *>).
-In XS code on perls starting with perl 5.16, you can override the
-typemaps for any of these types with a version that has proper
-handling of refcounts. In your C<TYPEMAP> section, do
-
- AV* T_AVREF_REFCOUNT_FIXED
-
-to get the repaired variant. For backward compatibility with older
-versions of perl, you can instead decrement the reference count
-manually when you're returning one of the aforementioned
-types using C<sv_2mortal>:
-
- AV *
- array()
- CODE:
- RETVAL = newAV();
- sv_2mortal((SV*)RETVAL);
- /* do something with RETVAL */
- OUTPUT:
- RETVAL
-
-Remember that you don't have to do this for an C<SV *>. The reference
-documentation for all core typemaps can be found in L<perlxstypemap>.
-
-=head2 The MODULE Keyword
-
-The MODULE keyword is used to start the XS code and to specify the package
-of the functions which are being defined. All text preceding the first
-MODULE keyword is considered C code and is passed through to the output with
-POD stripped, but otherwise untouched. Every XS module will have a
-bootstrap function which is used to hook the XSUBs into Perl. The package
-name of this bootstrap function will match the value of the last MODULE
-statement in the XS source files. The value of MODULE should always remain
-constant within the same XS file, though this is not required.
-
-The following example will start the XS code and will place
-all functions in a package named RPC.
-
- MODULE = RPC
-
-=head2 The PACKAGE Keyword
-
-When functions within an XS source file must be separated into packages
-the PACKAGE keyword should be used. This keyword is used with the MODULE
-keyword and must follow immediately after it when used.
-
- MODULE = RPC PACKAGE = RPC
-
- [ XS code in package RPC ]
-
- MODULE = RPC PACKAGE = RPCB
-
- [ XS code in package RPCB ]
-
- MODULE = RPC PACKAGE = RPC
-
- [ XS code in package RPC ]
-
-The same package name can be used more than once, allowing for
-non-contiguous code. This is useful if you have a stronger ordering
-principle than package names.
-
-Although this keyword is optional and in some cases provides redundant
-information it should always be used. This keyword will ensure that the
-XSUBs appear in the desired package.
-
-=head2 The PREFIX Keyword
-
-The PREFIX keyword designates prefixes which should be
-removed from the Perl function names. If the C function is
-C<rpcb_gettime()> and the PREFIX value is C<rpcb_> then Perl will
-see this function as C<gettime()>.
-
-This keyword should follow the PACKAGE keyword when used.
-If PACKAGE is not used then PREFIX should follow the MODULE
-keyword.
-
- MODULE = RPC PREFIX = rpc_
-
- MODULE = RPC PACKAGE = RPCB PREFIX = rpcb_
-
-=head2 The OUTPUT: Keyword
-
-The OUTPUT: keyword indicates that certain function parameters should be
-updated (new values made visible to Perl) when the XSUB terminates or that
-certain values should be returned to the calling Perl function. For
-simple functions which have no CODE: or PPCODE: section,
-such as the sin() function above, the RETVAL variable is
-automatically designated as an output value. For more complex functions
-the B<xsubpp> compiler will need help to determine which variables are output
-variables.
-
-This keyword will normally be used to complement the CODE: keyword.
-The RETVAL variable is not recognized as an output variable when the
-CODE: keyword is present. The OUTPUT: keyword is used in this
-situation to tell the compiler that RETVAL really is an output
-variable.
-
-The OUTPUT: keyword can also be used to indicate that function parameters
-are output variables. This may be necessary when a parameter has been
-modified within the function and the programmer would like the update to
-be seen by Perl.
-
- bool_t
- rpcb_gettime(host,timep)
- char *host
- time_t &timep
- OUTPUT:
- timep
-
-The OUTPUT: keyword will also allow an output parameter to
-be mapped to a matching piece of code rather than to a
-typemap.
-
- bool_t
- rpcb_gettime(host,timep)
- char *host
- time_t &timep
- OUTPUT:
- timep sv_setnv(ST(1), (double)timep);
-
-B<xsubpp> emits an automatic C<SvSETMAGIC()> for all parameters in the
-OUTPUT section of the XSUB, except RETVAL. This is the usually desired
-behavior, as it takes care of properly invoking 'set' magic on output
-parameters (needed for hash or array element parameters that must be
-created if they didn't exist). If for some reason, this behavior is
-not desired, the OUTPUT section may contain a C<SETMAGIC: DISABLE> line
-to disable it for the remainder of the parameters in the OUTPUT section.
-Likewise, C<SETMAGIC: ENABLE> can be used to reenable it for the
-remainder of the OUTPUT section. See L<perlguts> for more details
-about 'set' magic.
-
-=head2 The NO_OUTPUT Keyword
-
-The NO_OUTPUT can be placed as the first token of the XSUB. This keyword
-indicates that while the C subroutine we provide an interface to has
-a non-C<void> return type, the return value of this C subroutine should not
-be returned from the generated Perl subroutine.
-
-With this keyword present L<The RETVAL Variable> is created, and in the
-generated call to the subroutine this variable is assigned to, but the value
-of this variable is not going to be used in the auto-generated code.
-
-This keyword makes sense only if C<RETVAL> is going to be accessed by the
-user-supplied code. It is especially useful to make a function interface
-more Perl-like, especially when the C return value is just an error condition
-indicator. For example,
-
- NO_OUTPUT int
- delete_file(char *name)
- POSTCALL:
- if (RETVAL != 0)
- croak("Error %d while deleting file '%s'", RETVAL, name);
-
-Here the generated XS function returns nothing on success, and will die()
-with a meaningful error message on error.
-
-=head2 The CODE: Keyword
-
-This keyword is used in more complicated XSUBs which require
-special handling for the C function. The RETVAL variable is
-still declared, but it will not be returned unless it is specified
-in the OUTPUT: section.
-
-The following XSUB is for a C function which requires special handling of
-its parameters. The Perl usage is given first.
-
- $status = rpcb_gettime( "localhost", $timep );
-
-The XSUB follows.
-
- bool_t
- rpcb_gettime(host,timep)
- char *host
- time_t timep
- CODE:
- RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
- timep
- RETVAL
-
-=head2 The INIT: Keyword
-
-The INIT: keyword allows initialization to be inserted into the XSUB before
-the compiler generates the call to the C function. Unlike the CODE: keyword
-above, this keyword does not affect the way the compiler handles RETVAL.
-
- bool_t
- rpcb_gettime(host,timep)
- char *host
- time_t &timep
- INIT:
- printf("# Host is %s\n", host );
- OUTPUT:
- timep
-
-Another use for the INIT: section is to check for preconditions before
-making a call to the C function:
-
- long long
- lldiv(a,b)
- long long a
- long long b
- INIT:
- if (a == 0 && b == 0)
- XSRETURN_UNDEF;
- if (b == 0)
- croak("lldiv: cannot divide by 0");
-
-=head2 The NO_INIT Keyword
-
-The NO_INIT keyword is used to indicate that a function
-parameter is being used only as an output value. The B<xsubpp>
-compiler will normally generate code to read the values of
-all function parameters from the argument stack and assign
-them to C variables upon entry to the function. NO_INIT
-will tell the compiler that some parameters will be used for
-output rather than for input and that they will be handled
-before the function terminates.
-
-The following example shows a variation of the rpcb_gettime() function.
-This function uses the timep variable only as an output variable and does
-not care about its initial contents.
-
- bool_t
- rpcb_gettime(host,timep)
- char *host
- time_t &timep = NO_INIT
- OUTPUT:
- timep
-
-=head2 The TYPEMAP: Keyword
-
-Starting with Perl 5.16, you can embed typemaps into your XS code
-instead of or in addition to typemaps in a separate file. Multiple
-such embedded typemaps will be processed in order of appearance in
-the XS code and like local typemap files take precendence over the
-default typemap, the embedded typemaps may overwrite previous
-definitions of TYPEMAP, INPUT, and OUTPUT stanzas. The syntax for
-embedded typemaps is
-
- TYPEMAP: <<HERE
- ... your typemap code here ...
- HERE
-
-where the C<TYPEMAP> keyword must appear in the first column of a
-new line.
-
-Refer to L<perlxstypemap> for details on writing typemaps.
-
-=head2 Initializing Function Parameters
-
-C function parameters are normally initialized with their values from
-the argument stack (which in turn contains the parameters that were
-passed to the XSUB from Perl). The typemaps contain the
-code segments which are used to translate the Perl values to
-the C parameters. The programmer, however, is allowed to
-override the typemaps and supply alternate (or additional)
-initialization code. Initialization code starts with the first
-C<=>, C<;> or C<+> on a line in the INPUT: section. The only
-exception happens if this C<;> terminates the line, then this C<;>
-is quietly ignored.
-
-The following code demonstrates how to supply initialization code for
-function parameters. The initialization code is eval'ed within double
-quotes by the compiler before it is added to the output so anything
-which should be interpreted literally [mainly C<$>, C<@>, or C<\\>]
-must be protected with backslashes. The variables C<$var>, C<$arg>,
-and C<$type> can be used as in typemaps.
-
- bool_t
- rpcb_gettime(host,timep)
- char *host = (char *)SvPV_nolen($arg);
- time_t &timep = 0;
- OUTPUT:
- timep
-
-This should not be used to supply default values for parameters. One
-would normally use this when a function parameter must be processed by
-another library function before it can be used. Default parameters are
-covered in the next section.
-
-If the initialization begins with C<=>, then it is output in
-the declaration for the input variable, replacing the initialization
-supplied by the typemap. If the initialization
-begins with C<;> or C<+>, then it is performed after
-all of the input variables have been declared. In the C<;>
-case the initialization normally supplied by the typemap is not performed.
-For the C<+> case, the declaration for the variable will include the
-initialization from the typemap. A global
-variable, C<%v>, is available for the truly rare case where
-information from one initialization is needed in another
-initialization.
-
-Here's a truly obscure example:
-
- bool_t
- rpcb_gettime(host,timep)
- time_t &timep; /* \$v{timep}=@{[$v{timep}=$arg]} */
- char *host + SvOK($v{timep}) ? SvPV_nolen($arg) : NULL;
- OUTPUT:
- timep
-
-The construct C<\$v{timep}=@{[$v{timep}=$arg]}> used in the above
-example has a two-fold purpose: first, when this line is processed by
-B<xsubpp>, the Perl snippet C<$v{timep}=$arg> is evaluated. Second,
-the text of the evaluated snippet is output into the generated C file
-(inside a C comment)! During the processing of C<char *host> line,
-C<$arg> will evaluate to C<ST(0)>, and C<$v{timep}> will evaluate to
-C<ST(1)>.
-
-=head2 Default Parameter Values
-
-Default values for XSUB arguments can be specified by placing an
-assignment statement in the parameter list. The default value may
-be a number, a string or the special string C<NO_INIT>. Defaults should
-always be used on the right-most parameters only.
-
-To allow the XSUB for rpcb_gettime() to have a default host
-value the parameters to the XSUB could be rearranged. The
-XSUB will then call the real rpcb_gettime() function with
-the parameters in the correct order. This XSUB can be called
-from Perl with either of the following statements:
-
- $status = rpcb_gettime( $timep, $host );
-
- $status = rpcb_gettime( $timep );
-
-The XSUB will look like the code which follows. A CODE:
-block is used to call the real rpcb_gettime() function with
-the parameters in the correct order for that function.
-
- bool_t
- rpcb_gettime(timep,host="localhost")
- char *host
- time_t timep = NO_INIT
- CODE:
- RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
- timep
- RETVAL
-
-=head2 The PREINIT: Keyword
-
-The PREINIT: keyword allows extra variables to be declared immediately
-before or after the declarations of the parameters from the INPUT: section
-are emitted.
-
-If a variable is declared inside a CODE: section it will follow any typemap
-code that is emitted for the input parameters. This may result in the
-declaration ending up after C code, which is C syntax error. Similar
-errors may happen with an explicit C<;>-type or C<+>-type initialization of
-parameters is used (see L<"Initializing Function Parameters">). Declaring
-these variables in an INIT: section will not help.
-
-In such cases, to force an additional variable to be declared together
-with declarations of other variables, place the declaration into a
-PREINIT: section. The PREINIT: keyword may be used one or more times
-within an XSUB.
-
-The following examples are equivalent, but if the code is using complex
-typemaps then the first example is safer.
-
- bool_t
- rpcb_gettime(timep)
- time_t timep = NO_INIT
- PREINIT:
- char *host = "localhost";
- CODE:
- RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
- timep
- RETVAL
-
-For this particular case an INIT: keyword would generate the
-same C code as the PREINIT: keyword. Another correct, but error-prone example:
-
- bool_t
- rpcb_gettime(timep)
- time_t timep = NO_INIT
- CODE:
- char *host = "localhost";
- RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
- timep
- RETVAL
-
-Another way to declare C<host> is to use a C block in the CODE: section:
-
- bool_t
- rpcb_gettime(timep)
- time_t timep = NO_INIT
- CODE:
- {
- char *host = "localhost";
- RETVAL = rpcb_gettime( host, &timep );
- }
- OUTPUT:
- timep
- RETVAL
-
-The ability to put additional declarations before the typemap entries are
-processed is very handy in the cases when typemap conversions manipulate
-some global state:
-
- MyObject
- mutate(o)
- PREINIT:
- MyState st = global_state;
- INPUT:
- MyObject o;
- CLEANUP:
- reset_to(global_state, st);
-
-Here we suppose that conversion to C<MyObject> in the INPUT: section and from
-MyObject when processing RETVAL will modify a global variable C<global_state>.
-After these conversions are performed, we restore the old value of
-C<global_state> (to avoid memory leaks, for example).
-
-There is another way to trade clarity for compactness: INPUT sections allow
-declaration of C variables which do not appear in the parameter list of
-a subroutine. Thus the above code for mutate() can be rewritten as
-
- MyObject
- mutate(o)
- MyState st = global_state;
- MyObject o;
- CLEANUP:
- reset_to(global_state, st);
-
-and the code for rpcb_gettime() can be rewritten as
-
- bool_t
- rpcb_gettime(timep)
- time_t timep = NO_INIT
- char *host = "localhost";
- C_ARGS:
- host, &timep
- OUTPUT:
- timep
- RETVAL
-
-=head2 The SCOPE: Keyword
-
-The SCOPE: keyword allows scoping to be enabled for a particular XSUB. If
-enabled, the XSUB will invoke ENTER and LEAVE automatically.
-
-To support potentially complex type mappings, if a typemap entry used
-by an XSUB contains a comment like C</*scope*/> then scoping will
-be automatically enabled for that XSUB.
-
-To enable scoping:
-
- SCOPE: ENABLE
-
-To disable scoping:
-
- SCOPE: DISABLE
-
-=head2 The INPUT: Keyword
-
-The XSUB's parameters are usually evaluated immediately after entering the
-XSUB. The INPUT: keyword can be used to force those parameters to be
-evaluated a little later. The INPUT: keyword can be used multiple times
-within an XSUB and can be used to list one or more input variables. This
-keyword is used with the PREINIT: keyword.
-
-The following example shows how the input parameter C<timep> can be
-evaluated late, after a PREINIT.
-
- bool_t
- rpcb_gettime(host,timep)
- char *host
- PREINIT:
- time_t tt;
- INPUT:
- time_t timep
- CODE:
- RETVAL = rpcb_gettime( host, &tt );
- timep = tt;
- OUTPUT:
- timep
- RETVAL
-
-The next example shows each input parameter evaluated late.
-
- bool_t
- rpcb_gettime(host,timep)
- PREINIT:
- time_t tt;
- INPUT:
- char *host
- PREINIT:
- char *h;
- INPUT:
- time_t timep
- CODE:
- h = host;
- RETVAL = rpcb_gettime( h, &tt );
- timep = tt;
- OUTPUT:
- timep
- RETVAL
-
-Since INPUT sections allow declaration of C variables which do not appear
-in the parameter list of a subroutine, this may be shortened to:
-
- bool_t
- rpcb_gettime(host,timep)
- time_t tt;
- char *host;
- char *h = host;
- time_t timep;
- CODE:
- RETVAL = rpcb_gettime( h, &tt );
- timep = tt;
- OUTPUT:
- timep
- RETVAL
-
-(We used our knowledge that input conversion for C<char *> is a "simple" one,
-thus C<host> is initialized on the declaration line, and our assignment
-C<h = host> is not performed too early. Otherwise one would need to have the
-assignment C<h = host> in a CODE: or INIT: section.)
-
-=head2 The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords
-
-In the list of parameters for an XSUB, one can precede parameter names
-by the C<IN>/C<OUTLIST>/C<IN_OUTLIST>/C<OUT>/C<IN_OUT> keywords.
-C<IN> keyword is the default, the other keywords indicate how the Perl
-interface should differ from the C interface.
-
-Parameters preceded by C<OUTLIST>/C<IN_OUTLIST>/C<OUT>/C<IN_OUT>
-keywords are considered to be used by the C subroutine I<via
-pointers>. C<OUTLIST>/C<OUT> keywords indicate that the C subroutine
-does not inspect the memory pointed by this parameter, but will write
-through this pointer to provide additional return values.
-
-Parameters preceded by C<OUTLIST> keyword do not appear in the usage
-signature of the generated Perl function.
-
-Parameters preceded by C<IN_OUTLIST>/C<IN_OUT>/C<OUT> I<do> appear as
-parameters to the Perl function. With the exception of
-C<OUT>-parameters, these parameters are converted to the corresponding
-C type, then pointers to these data are given as arguments to the C
-function. It is expected that the C function will write through these
-pointers.
-
-The return list of the generated Perl function consists of the C return value
-from the function (unless the XSUB is of C<void> return type or
-C<The NO_OUTPUT Keyword> was used) followed by all the C<OUTLIST>
-and C<IN_OUTLIST> parameters (in the order of appearance). On the
-return from the XSUB the C<IN_OUT>/C<OUT> Perl parameter will be
-modified to have the values written by the C function.
-
-For example, an XSUB
-
- void
- day_month(OUTLIST day, IN unix_time, OUTLIST month)
- int day
- int unix_time
- int month
-
-should be used from Perl as
-
- my ($day, $month) = day_month(time);
-
-The C signature of the corresponding function should be
-
- void day_month(int *day, int unix_time, int *month);
-
-The C<IN>/C<OUTLIST>/C<IN_OUTLIST>/C<IN_OUT>/C<OUT> keywords can be
-mixed with ANSI-style declarations, as in
-
- void
- day_month(OUTLIST int day, int unix_time, OUTLIST int month)
-
-(here the optional C<IN> keyword is omitted).
-
-The C<IN_OUT> parameters are identical with parameters introduced with
-L<The & Unary Operator> and put into the C<OUTPUT:> section (see
-L<The OUTPUT: Keyword>). The C<IN_OUTLIST> parameters are very similar,
-the only difference being that the value C function writes through the
-pointer would not modify the Perl parameter, but is put in the output
-list.
-
-The C<OUTLIST>/C<OUT> parameter differ from C<IN_OUTLIST>/C<IN_OUT>
-parameters only by the initial value of the Perl parameter not
-being read (and not being given to the C function - which gets some
-garbage instead). For example, the same C function as above can be
-interfaced with as
-
- void day_month(OUT int day, int unix_time, OUT int month);
-
-or
-
- void
- day_month(day, unix_time, month)
- int &day = NO_INIT
- int unix_time
- int &month = NO_INIT
- OUTPUT:
- day
- month
-
-However, the generated Perl function is called in very C-ish style:
-
- my ($day, $month);
- day_month($day, time, $month);
-
-=head2 The C<length(NAME)> Keyword
-
-If one of the input arguments to the C function is the length of a string
-argument C<NAME>, one can substitute the name of the length-argument by
-C<length(NAME)> in the XSUB declaration. This argument must be omitted when
-the generated Perl function is called. E.g.,
-
- void
- dump_chars(char *s, short l)
- {
- short n = 0;
- while (n < l) {
- printf("s[%d] = \"\\%#03o\"\n", n, (int)s[n]);
- n++;
- }
- }
-
- MODULE = x PACKAGE = x
-
- void dump_chars(char *s, short length(s))
-
-should be called as C<dump_chars($string)>.
-
-This directive is supported with ANSI-type function declarations only.
-
-=head2 Variable-length Parameter Lists
-
-XSUBs can have variable-length parameter lists by specifying an ellipsis
-C<(...)> in the parameter list. This use of the ellipsis is similar to that
-found in ANSI C. The programmer is able to determine the number of
-arguments passed to the XSUB by examining the C<items> variable which the
-B<xsubpp> compiler supplies for all XSUBs. By using this mechanism one can
-create an XSUB which accepts a list of parameters of unknown length.
-
-The I<host> parameter for the rpcb_gettime() XSUB can be
-optional so the ellipsis can be used to indicate that the
-XSUB will take a variable number of parameters. Perl should
-be able to call this XSUB with either of the following statements.
-
- $status = rpcb_gettime( $timep, $host );
-
- $status = rpcb_gettime( $timep );
-
-The XS code, with ellipsis, follows.
-
- bool_t
- rpcb_gettime(timep, ...)
- time_t timep = NO_INIT
- PREINIT:
- char *host = "localhost";
- CODE:
- if( items > 1 )
- host = (char *)SvPV_nolen(ST(1));
- RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
- timep
- RETVAL
-
-=head2 The C_ARGS: Keyword
-
-The C_ARGS: keyword allows creating of XSUBS which have different
-calling sequence from Perl than from C, without a need to write
-CODE: or PPCODE: section. The contents of the C_ARGS: paragraph is
-put as the argument to the called C function without any change.
-
-For example, suppose that a C function is declared as
-
- symbolic nth_derivative(int n, symbolic function, int flags);
-
-and that the default flags are kept in a global C variable
-C<default_flags>. Suppose that you want to create an interface which
-is called as
-
- $second_deriv = $function->nth_derivative(2);
-
-To do this, declare the XSUB as
-
- symbolic
- nth_derivative(function, n)
- symbolic function
- int n
- C_ARGS:
- n, function, default_flags
-
-=head2 The PPCODE: Keyword
-
-The PPCODE: keyword is an alternate form of the CODE: keyword and is used
-to tell the B<xsubpp> compiler that the programmer is supplying the code to
-control the argument stack for the XSUBs return values. Occasionally one
-will want an XSUB to return a list of values rather than a single value.
-In these cases one must use PPCODE: and then explicitly push the list of
-values on the stack. The PPCODE: and CODE: keywords should not be used
-together within the same XSUB.
-
-The actual difference between PPCODE: and CODE: sections is in the
-initialization of C<SP> macro (which stands for the I<current> Perl
-stack pointer), and in the handling of data on the stack when returning
-from an XSUB. In CODE: sections SP preserves the value which was on
-entry to the XSUB: SP is on the function pointer (which follows the
-last parameter). In PPCODE: sections SP is moved backward to the
-beginning of the parameter list, which allows C<PUSH*()> macros
-to place output values in the place Perl expects them to be when
-the XSUB returns back to Perl.
-
-The generated trailer for a CODE: section ensures that the number of return
-values Perl will see is either 0 or 1 (depending on the C<void>ness of the
-return value of the C function, and heuristics mentioned in
-L<"The RETVAL Variable">). The trailer generated for a PPCODE: section
-is based on the number of return values and on the number of times
-C<SP> was updated by C<[X]PUSH*()> macros.
-
-Note that macros C<ST(i)>, C<XST_m*()> and C<XSRETURN*()> work equally
-well in CODE: sections and PPCODE: sections.
-
-The following XSUB will call the C rpcb_gettime() function
-and will return its two output values, timep and status, to
-Perl as a single list.
-
- void
- rpcb_gettime(host)
- char *host
- PREINIT:
- time_t timep;
- bool_t status;
- PPCODE:
- status = rpcb_gettime( host, &timep );
- EXTEND(SP, 2);
- PUSHs(sv_2mortal(newSViv(status)));
- PUSHs(sv_2mortal(newSViv(timep)));
-
-Notice that the programmer must supply the C code necessary
-to have the real rpcb_gettime() function called and to have
-the return values properly placed on the argument stack.
-
-The C<void> return type for this function tells the B<xsubpp> compiler that
-the RETVAL variable is not needed or used and that it should not be created.
-In most scenarios the void return type should be used with the PPCODE:
-directive.
-
-The EXTEND() macro is used to make room on the argument
-stack for 2 return values. The PPCODE: directive causes the
-B<xsubpp> compiler to create a stack pointer available as C<SP>, and it
-is this pointer which is being used in the EXTEND() macro.
-The values are then pushed onto the stack with the PUSHs()
-macro.
-
-Now the rpcb_gettime() function can be used from Perl with
-the following statement.
-
- ($status, $timep) = rpcb_gettime("localhost");
-
-When handling output parameters with a PPCODE section, be sure to handle
-'set' magic properly. See L<perlguts> for details about 'set' magic.
-
-=head2 Returning Undef And Empty Lists
-
-Occasionally the programmer will want to return simply
-C<undef> or an empty list if a function fails rather than a
-separate status value. The rpcb_gettime() function offers
-just this situation. If the function succeeds we would like
-to have it return the time and if it fails we would like to
-have undef returned. In the following Perl code the value
-of $timep will either be undef or it will be a valid time.
-
- $timep = rpcb_gettime( "localhost" );
-
-The following XSUB uses the C<SV *> return type as a mnemonic only,
-and uses a CODE: block to indicate to the compiler
-that the programmer has supplied all the necessary code. The
-sv_newmortal() call will initialize the return value to undef, making that
-the default return value.
-
- SV *
- rpcb_gettime(host)
- char * host
- PREINIT:
- time_t timep;
- bool_t x;
- CODE:
- ST(0) = sv_newmortal();
- if( rpcb_gettime( host, &timep ) )
- sv_setnv( ST(0), (double)timep);
-
-The next example demonstrates how one would place an explicit undef in the
-return value, should the need arise.
-
- SV *
- rpcb_gettime(host)
- char * host
- PREINIT:
- time_t timep;
- bool_t x;
- CODE:
- if( rpcb_gettime( host, &timep ) ){
- ST(0) = sv_newmortal();
- sv_setnv( ST(0), (double)timep);
- }
- else{
- ST(0) = &PL_sv_undef;
- }
-
-To return an empty list one must use a PPCODE: block and
-then not push return values on the stack.
-
- void
- rpcb_gettime(host)
- char *host
- PREINIT:
- time_t timep;
- PPCODE:
- if( rpcb_gettime( host, &timep ) )
- PUSHs(sv_2mortal(newSViv(timep)));
- else{
- /* Nothing pushed on stack, so an empty
- * list is implicitly returned. */
- }
-
-Some people may be inclined to include an explicit C<return> in the above
-XSUB, rather than letting control fall through to the end. In those
-situations C<XSRETURN_EMPTY> should be used, instead. This will ensure that
-the XSUB stack is properly adjusted. Consult L<perlapi> for other
-C<XSRETURN> macros.
-
-Since C<XSRETURN_*> macros can be used with CODE blocks as well, one can
-rewrite this example as:
-
- int
- rpcb_gettime(host)
- char *host
- PREINIT:
- time_t timep;
- CODE:
- RETVAL = rpcb_gettime( host, &timep );
- if (RETVAL == 0)
- XSRETURN_UNDEF;
- OUTPUT:
- RETVAL
-
-In fact, one can put this check into a POSTCALL: section as well. Together
-with PREINIT: simplifications, this leads to:
-
- int
- rpcb_gettime(host)
- char *host
- time_t timep;
- POSTCALL:
- if (RETVAL == 0)
- XSRETURN_UNDEF;
-
-=head2 The REQUIRE: Keyword
-
-The REQUIRE: keyword is used to indicate the minimum version of the
-B<xsubpp> compiler needed to compile the XS module. An XS module which
-contains the following statement will compile with only B<xsubpp> version
-1.922 or greater:
-
- REQUIRE: 1.922
-
-=head2 The CLEANUP: Keyword
-
-This keyword can be used when an XSUB requires special cleanup procedures
-before it terminates. When the CLEANUP: keyword is used it must follow
-any CODE:, PPCODE:, or OUTPUT: blocks which are present in the XSUB. The
-code specified for the cleanup block will be added as the last statements
-in the XSUB.
-
-=head2 The POSTCALL: Keyword
-
-This keyword can be used when an XSUB requires special procedures
-executed after the C subroutine call is performed. When the POSTCALL:
-keyword is used it must precede OUTPUT: and CLEANUP: blocks which are
-present in the XSUB.
-
-See examples in L<"The NO_OUTPUT Keyword"> and L<"Returning Undef And Empty Lists">.
-
-The POSTCALL: block does not make a lot of sense when the C subroutine
-call is supplied by user by providing either CODE: or PPCODE: section.
-
-=head2 The BOOT: Keyword
-
-The BOOT: keyword is used to add code to the extension's bootstrap
-function. The bootstrap function is generated by the B<xsubpp> compiler and
-normally holds the statements necessary to register any XSUBs with Perl.
-With the BOOT: keyword the programmer can tell the compiler to add extra
-statements to the bootstrap function.
-
-This keyword may be used any time after the first MODULE keyword and should
-appear on a line by itself. The first blank line after the keyword will
-terminate the code block.
-
- BOOT:
- # The following message will be printed when the
- # bootstrap function executes.
- printf("Hello from the bootstrap!\n");
-
-=head2 The VERSIONCHECK: Keyword
-
-The VERSIONCHECK: keyword corresponds to B<xsubpp>'s C<-versioncheck> and
-C<-noversioncheck> options. This keyword overrides the command line
-options. Version checking is enabled by default. When version checking is
-enabled the XS module will attempt to verify that its version matches the
-version of the PM module.
-
-To enable version checking:
-
- VERSIONCHECK: ENABLE
-
-To disable version checking:
-
- VERSIONCHECK: DISABLE
-
-Note that if the version of the PM module is an NV (a floating point
-number), it will be stringified with a possible loss of precision
-(currently chopping to nine decimal places) so that it may not match
-the version of the XS module anymore. Quoting the $VERSION declaration
-to make it a string is recommended if long version numbers are used.
-
-=head2 The PROTOTYPES: Keyword
-
-The PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and
-C<-noprototypes> options. This keyword overrides the command line options.
-Prototypes are enabled by default. When prototypes are enabled XSUBs will
-be given Perl prototypes. This keyword may be used multiple times in an XS
-module to enable and disable prototypes for different parts of the module.
-
-To enable prototypes:
-
- PROTOTYPES: ENABLE
-
-To disable prototypes:
-
- PROTOTYPES: DISABLE
-
-=head2 The PROTOTYPE: Keyword
-
-This keyword is similar to the PROTOTYPES: keyword above but can be used to
-force B<xsubpp> to use a specific prototype for the XSUB. This keyword
-overrides all other prototype options and keywords but affects only the
-current XSUB. Consult L<perlsub/Prototypes> for information about Perl
-prototypes.
-
- bool_t
- rpcb_gettime(timep, ...)
- time_t timep = NO_INIT
- PROTOTYPE: $;$
- PREINIT:
- char *host = "localhost";
- CODE:
- if( items > 1 )
- host = (char *)SvPV_nolen(ST(1));
- RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
- timep
- RETVAL
-
-If the prototypes are enabled, you can disable it locally for a given
-XSUB as in the following example:
-
- void
- rpcb_gettime_noproto()
- PROTOTYPE: DISABLE
- ...
-
-=head2 The ALIAS: Keyword
-
-The ALIAS: keyword allows an XSUB to have two or more unique Perl names
-and to know which of those names was used when it was invoked. The Perl
-names may be fully-qualified with package names. Each alias is given an
-index. The compiler will setup a variable called C<ix> which contain the
-index of the alias which was used. When the XSUB is called with its
-declared name C<ix> will be 0.
-
-The following example will create aliases C<FOO::gettime()> and
-C<BAR::getit()> for this function.
-
- bool_t
- rpcb_gettime(host,timep)
- char *host
- time_t &timep
- ALIAS:
- FOO::gettime = 1
- BAR::getit = 2
- INIT:
- printf("# ix = %d\n", ix );
- OUTPUT:
- timep
-
-=head2 The OVERLOAD: Keyword
-
-Instead of writing an overloaded interface using pure Perl, you
-can also use the OVERLOAD keyword to define additional Perl names
-for your functions (like the ALIAS: keyword above). However, the
-overloaded functions must be defined with three parameters (except
-for the nomethod() function which needs four parameters). If any
-function has the OVERLOAD: keyword, several additional lines
-will be defined in the c file generated by xsubpp in order to
-register with the overload magic.
-
-Since blessed objects are actually stored as RV's, it is useful
-to use the typemap features to preprocess parameters and extract
-the actual SV stored within the blessed RV. See the sample for
-T_PTROBJ_SPECIAL below.
-
-To use the OVERLOAD: keyword, create an XS function which takes
-three input parameters ( or use the c style '...' definition) like
-this:
-
- SV *
- cmp (lobj, robj, swap)
- My_Module_obj lobj
- My_Module_obj robj
- IV swap
- OVERLOAD: cmp <=>
- { /* function defined here */}
-
-In this case, the function will overload both of the three way
-comparison operators. For all overload operations using non-alpha
-characters, you must type the parameter without quoting, separating
-multiple overloads with whitespace. Note that "" (the stringify
-overload) should be entered as \"\" (i.e. escaped).
-
-=head2 The FALLBACK: Keyword
-
-In addition to the OVERLOAD keyword, if you need to control how
-Perl autogenerates missing overloaded operators, you can set the
-FALLBACK keyword in the module header section, like this:
-
- MODULE = RPC PACKAGE = RPC
-
- FALLBACK: TRUE
- ...
-
-where FALLBACK can take any of the three values TRUE, FALSE, or
-UNDEF. If you do not set any FALLBACK value when using OVERLOAD,
-it defaults to UNDEF. FALLBACK is not used except when one or
-more functions using OVERLOAD have been defined. Please see
-L<overload/fallback> for more details.
-
-=head2 The INTERFACE: Keyword
-
-This keyword declares the current XSUB as a keeper of the given
-calling signature. If some text follows this keyword, it is
-considered as a list of functions which have this signature, and
-should be attached to the current XSUB.
-
-For example, if you have 4 C functions multiply(), divide(), add(),
-subtract() all having the signature:
-
- symbolic f(symbolic, symbolic);
-
-you can make them all to use the same XSUB using this:
-
- symbolic
- interface_s_ss(arg1, arg2)
- symbolic arg1
- symbolic arg2
- INTERFACE:
- multiply divide
- add subtract
-
-(This is the complete XSUB code for 4 Perl functions!) Four generated
-Perl function share names with corresponding C functions.
-
-The advantage of this approach comparing to ALIAS: keyword is that there
-is no need to code a switch statement, each Perl function (which shares
-the same XSUB) knows which C function it should call. Additionally, one
-can attach an extra function remainder() at runtime by using
-
- CV *mycv = newXSproto("Symbolic::remainder",
- XS_Symbolic_interface_s_ss, __FILE__, "$$");
- XSINTERFACE_FUNC_SET(mycv, remainder);
-
-say, from another XSUB. (This example supposes that there was no
-INTERFACE_MACRO: section, otherwise one needs to use something else instead of
-C<XSINTERFACE_FUNC_SET>, see the next section.)
-
-=head2 The INTERFACE_MACRO: Keyword
-
-This keyword allows one to define an INTERFACE using a different way
-to extract a function pointer from an XSUB. The text which follows
-this keyword should give the name of macros which would extract/set a
-function pointer. The extractor macro is given return type, C<CV*>,
-and C<XSANY.any_dptr> for this C<CV*>. The setter macro is given cv,
-and the function pointer.
-
-The default value is C<XSINTERFACE_FUNC> and C<XSINTERFACE_FUNC_SET>.
-An INTERFACE keyword with an empty list of functions can be omitted if
-INTERFACE_MACRO keyword is used.
-
-Suppose that in the previous example functions pointers for
-multiply(), divide(), add(), subtract() are kept in a global C array
-C<fp[]> with offsets being C<multiply_off>, C<divide_off>, C<add_off>,
-C<subtract_off>. Then one can use
-
- #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \
- ((XSINTERFACE_CVT_ANON(ret))fp[CvXSUBANY(cv).any_i32])
- #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \
- CvXSUBANY(cv).any_i32 = CAT2( f, _off )
-
-in C section,
-
- symbolic
- interface_s_ss(arg1, arg2)
- symbolic arg1
- symbolic arg2
- INTERFACE_MACRO:
- XSINTERFACE_FUNC_BYOFFSET
- XSINTERFACE_FUNC_BYOFFSET_set
- INTERFACE:
- multiply divide
- add subtract
-
-in XSUB section.
-
-=head2 The INCLUDE: Keyword
-
-This keyword can be used to pull other files into the XS module. The other
-files may have XS code. INCLUDE: can also be used to run a command to
-generate the XS code to be pulled into the module.
-
-The file F<Rpcb1.xsh> contains our C<rpcb_gettime()> function:
-
- bool_t
- rpcb_gettime(host,timep)
- char *host
- time_t &timep
- OUTPUT:
- timep
-
-The XS module can use INCLUDE: to pull that file into it.
-
- INCLUDE: Rpcb1.xsh
-
-If the parameters to the INCLUDE: keyword are followed by a pipe (C<|>) then
-the compiler will interpret the parameters as a command. This feature is
-mildly deprecated in favour of the C<INCLUDE_COMMAND:> directive, as documented
-below.
-
- INCLUDE: cat Rpcb1.xsh |
-
-Do not use this to run perl: C<INCLUDE: perl |> will run the perl that
-happens to be the first in your path and not necessarily the same perl that is
-used to run C<xsubpp>. See L<"The INCLUDE_COMMAND: Keyword">.
-
-=head2 The INCLUDE_COMMAND: Keyword
-
-Runs the supplied command and includes its output into the current XS
-document. C<INCLUDE_COMMAND> assigns special meaning to the C<$^X> token
-in that it runs the same perl interpreter that is running C<xsubpp>:
-
- INCLUDE_COMMAND: cat Rpcb1.xsh
-
- INCLUDE_COMMAND: $^X -e ...
-
-=head2 The CASE: Keyword
-
-The CASE: keyword allows an XSUB to have multiple distinct parts with each
-part acting as a virtual XSUB. CASE: is greedy and if it is used then all
-other XS keywords must be contained within a CASE:. This means nothing may
-precede the first CASE: in the XSUB and anything following the last CASE: is
-included in that case.
-
-A CASE: might switch via a parameter of the XSUB, via the C<ix> ALIAS:
-variable (see L<"The ALIAS: Keyword">), or maybe via the C<items> variable
-(see L<"Variable-length Parameter Lists">). The last CASE: becomes the
-B<default> case if it is not associated with a conditional. The following
-example shows CASE switched via C<ix> with a function C<rpcb_gettime()>
-having an alias C<x_gettime()>. When the function is called as
-C<rpcb_gettime()> its parameters are the usual C<(char *host, time_t *timep)>,
-but when the function is called as C<x_gettime()> its parameters are
-reversed, C<(time_t *timep, char *host)>.
-
- long
- rpcb_gettime(a,b)
- CASE: ix == 1
- ALIAS:
- x_gettime = 1
- INPUT:
- # 'a' is timep, 'b' is host
- char *b
- time_t a = NO_INIT
- CODE:
- RETVAL = rpcb_gettime( b, &a );
- OUTPUT:
- a
- RETVAL
- CASE:
- # 'a' is host, 'b' is timep
- char *a
- time_t &b = NO_INIT
- OUTPUT:
- b
- RETVAL
-
-That function can be called with either of the following statements. Note
-the different argument lists.
-
- $status = rpcb_gettime( $host, $timep );
-
- $status = x_gettime( $timep, $host );
-
-=head2 The EXPORT_XSUB_SYMBOLS: Keyword
-
-The EXPORT_XSUB_SYMBOLS: keyword is likely something you will never need.
-In perl versions earlier than 5.16.0, this keyword does nothing. Starting
-with 5.16, XSUB symbols are no longer exported by default. That is, they
-are C<static> functions. If you include
-
- EXPORT_XSUB_SYMBOLS: ENABLE
-
-in your XS code, the XSUBs following this line will not be declared C<static>.
-You can later disable this with
-
- EXPORT_XSUB_SYMBOLS: DISABLE
-
-which, again, is the default that you should probably never change.
-You cannot use this keyword on versions of perl before 5.16 to make
-XSUBs C<static>.
-
-=head2 The & Unary Operator
-
-The C<&> unary operator in the INPUT: section is used to tell B<xsubpp>
-that it should convert a Perl value to/from C using the C type to the left
-of C<&>, but provide a pointer to this value when the C function is called.
-
-This is useful to avoid a CODE: block for a C function which takes a parameter
-by reference. Typically, the parameter should be not a pointer type (an
-C<int> or C<long> but not an C<int*> or C<long*>).
-
-The following XSUB will generate incorrect C code. The B<xsubpp> compiler will
-turn this into code which calls C<rpcb_gettime()> with parameters C<(char
-*host, time_t timep)>, but the real C<rpcb_gettime()> wants the C<timep>
-parameter to be of type C<time_t*> rather than C<time_t>.
-
- bool_t
- rpcb_gettime(host,timep)
- char *host
- time_t timep
- OUTPUT:
- timep
-
-That problem is corrected by using the C<&> operator. The B<xsubpp> compiler
-will now turn this into code which calls C<rpcb_gettime()> correctly with
-parameters C<(char *host, time_t *timep)>. It does this by carrying the
-C<&> through, so the function call looks like C<rpcb_gettime(host, &timep)>.
-
- bool_t
- rpcb_gettime(host,timep)
- char *host
- time_t &timep
- OUTPUT:
- timep
-
-=head2 Inserting POD, Comments and C Preprocessor Directives
-
-C preprocessor directives are allowed within BOOT:, PREINIT: INIT:, CODE:,
-PPCODE:, POSTCALL:, and CLEANUP: blocks, as well as outside the functions.
-Comments are allowed anywhere after the MODULE keyword. The compiler will
-pass the preprocessor directives through untouched and will remove the
-commented lines. POD documentation is allowed at any point, both in the
-C and XS language sections. POD must be terminated with a C<=cut> command;
-C<xsubpp> will exit with an error if it does not. It is very unlikely that
-human generated C code will be mistaken for POD, as most indenting styles
-result in whitespace in front of any line starting with C<=>. Machine
-generated XS files may fall into this trap unless care is taken to
-ensure that a space breaks the sequence "\n=".
-
-Comments can be added to XSUBs by placing a C<#> as the first
-non-whitespace of a line. Care should be taken to avoid making the
-comment look like a C preprocessor directive, lest it be interpreted as
-such. The simplest way to prevent this is to put whitespace in front of
-the C<#>.
-
-If you use preprocessor directives to choose one of two
-versions of a function, use
-
- #if ... version1
- #else /* ... version2 */
- #endif
-
-and not
-
- #if ... version1
- #endif
- #if ... version2
- #endif
-
-because otherwise B<xsubpp> will believe that you made a duplicate
-definition of the function. Also, put a blank line before the
-#else/#endif so it will not be seen as part of the function body.
-
-=head2 Using XS With C++
-
-If an XSUB name contains C<::>, it is considered to be a C++ method.
-The generated Perl function will assume that
-its first argument is an object pointer. The object pointer
-will be stored in a variable called THIS. The object should
-have been created by C++ with the new() function and should
-be blessed by Perl with the sv_setref_pv() macro. The
-blessing of the object by Perl can be handled by a typemap. An example
-typemap is shown at the end of this section.
-
-If the return type of the XSUB includes C<static>, the method is considered
-to be a static method. It will call the C++
-function using the class::method() syntax. If the method is not static
-the function will be called using the THIS-E<gt>method() syntax.
-
-The next examples will use the following C++ class.
-
- class color {
- public:
- color();
- ~color();
- int blue();
- void set_blue( int );
-
- private:
- int c_blue;
- };
-
-The XSUBs for the blue() and set_blue() methods are defined with the class
-name but the parameter for the object (THIS, or "self") is implicit and is
-not listed.
-
- int
- color::blue()
-
- void
- color::set_blue( val )
- int val
-
-Both Perl functions will expect an object as the first parameter. In the
-generated C++ code the object is called C<THIS>, and the method call will
-be performed on this object. So in the C++ code the blue() and set_blue()
-methods will be called as this:
-
- RETVAL = THIS->blue();
-
- THIS->set_blue( val );
-
-You could also write a single get/set method using an optional argument:
-
- int
- color::blue( val = NO_INIT )
- int val
- PROTOTYPE $;$
- CODE:
- if (items > 1)
- THIS->set_blue( val );
- RETVAL = THIS->blue();
- OUTPUT:
- RETVAL
-
-If the function's name is B<DESTROY> then the C++ C<delete> function will be
-called and C<THIS> will be given as its parameter. The generated C++ code for
-
- void
- color::DESTROY()
-
-will look like this:
-
- color *THIS = ...; // Initialized as in typemap
-
- delete THIS;
-
-If the function's name is B<new> then the C++ C<new> function will be called
-to create a dynamic C++ object. The XSUB will expect the class name, which
-will be kept in a variable called C<CLASS>, to be given as the first
-argument.
-
- color *
- color::new()
-
-The generated C++ code will call C<new>.
-
- RETVAL = new color();
-
-The following is an example of a typemap that could be used for this C++
-example.
-
- TYPEMAP
- color * O_OBJECT
-
- OUTPUT
- # The Perl object is blessed into 'CLASS', which should be a
- # char* having the name of the package for the blessing.
- O_OBJECT
- sv_setref_pv( $arg, CLASS, (void*)$var );
-
- INPUT
- O_OBJECT
- if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
- $var = ($type)SvIV((SV*)SvRV( $arg ));
- else{
- warn( \"${Package}::$func_name() -- $var is not a blessed SV reference\" );
- XSRETURN_UNDEF;
- }
-
-=head2 Interface Strategy
-
-When designing an interface between Perl and a C library a straight
-translation from C to XS (such as created by C<h2xs -x>) is often sufficient.
-However, sometimes the interface will look
-very C-like and occasionally nonintuitive, especially when the C function
-modifies one of its parameters, or returns failure inband (as in "negative
-return values mean failure"). In cases where the programmer wishes to
-create a more Perl-like interface the following strategy may help to
-identify the more critical parts of the interface.
-
-Identify the C functions with input/output or output parameters. The XSUBs for
-these functions may be able to return lists to Perl.
-
-Identify the C functions which use some inband info as an indication
-of failure. They may be
-candidates to return undef or an empty list in case of failure. If the
-failure may be detected without a call to the C function, you may want to use
-an INIT: section to report the failure. For failures detectable after the C
-function returns one may want to use a POSTCALL: section to process the
-failure. In more complicated cases use CODE: or PPCODE: sections.
-
-If many functions use the same failure indication based on the return value,
-you may want to create a special typedef to handle this situation. Put
-
- typedef int negative_is_failure;
-
-near the beginning of XS file, and create an OUTPUT typemap entry
-for C<negative_is_failure> which converts negative values to C<undef>, or
-maybe croak()s. After this the return value of type C<negative_is_failure>
-will create more Perl-like interface.
-
-Identify which values are used by only the C and XSUB functions
-themselves, say, when a parameter to a function should be a contents of a
-global variable. If Perl does not need to access the contents of the value
-then it may not be necessary to provide a translation for that value
-from C to Perl.
-
-Identify the pointers in the C function parameter lists and return
-values. Some pointers may be used to implement input/output or
-output parameters, they can be handled in XS with the C<&> unary operator,
-and, possibly, using the NO_INIT keyword.
-Some others will require handling of types like C<int *>, and one needs
-to decide what a useful Perl translation will do in such a case. When
-the semantic is clear, it is advisable to put the translation into a typemap
-file.
-
-Identify the structures used by the C functions. In many
-cases it may be helpful to use the T_PTROBJ typemap for
-these structures so they can be manipulated by Perl as
-blessed objects. (This is handled automatically by C<h2xs -x>.)
-
-If the same C type is used in several different contexts which require
-different translations, C<typedef> several new types mapped to this C type,
-and create separate F<typemap> entries for these new types. Use these
-types in declarations of return type and parameters to XSUBs.
-
-=head2 Perl Objects And C Structures
-
-When dealing with C structures one should select either
-B<T_PTROBJ> or B<T_PTRREF> for the XS type. Both types are
-designed to handle pointers to complex objects. The
-T_PTRREF type will allow the Perl object to be unblessed
-while the T_PTROBJ type requires that the object be blessed.
-By using T_PTROBJ one can achieve a form of type-checking
-because the XSUB will attempt to verify that the Perl object
-is of the expected type.
-
-The following XS code shows the getnetconfigent() function which is used
-with ONC+ TIRPC. The getnetconfigent() function will return a pointer to a
-C structure and has the C prototype shown below. The example will
-demonstrate how the C pointer will become a Perl reference. Perl will
-consider this reference to be a pointer to a blessed object and will
-attempt to call a destructor for the object. A destructor will be
-provided in the XS source to free the memory used by getnetconfigent().
-Destructors in XS can be created by specifying an XSUB function whose name
-ends with the word B<DESTROY>. XS destructors can be used to free memory
-which may have been malloc'd by another XSUB.
-
- struct netconfig *getnetconfigent(const char *netid);
-
-A C<typedef> will be created for C<struct netconfig>. The Perl
-object will be blessed in a class matching the name of the C
-type, with the tag C<Ptr> appended, and the name should not
-have embedded spaces if it will be a Perl package name. The
-destructor will be placed in a class corresponding to the
-class of the object and the PREFIX keyword will be used to
-trim the name to the word DESTROY as Perl will expect.
-
- typedef struct netconfig Netconfig;
-
- MODULE = RPC PACKAGE = RPC
-
- Netconfig *
- getnetconfigent(netid)
- char *netid
-
- MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
-
- void
- rpcb_DESTROY(netconf)
- Netconfig *netconf
- CODE:
- printf("Now in NetconfigPtr::DESTROY\n");
- free( netconf );
-
-This example requires the following typemap entry. Consult
-L<perlxstypemap> for more information about adding new typemaps
-for an extension.
-
- TYPEMAP
- Netconfig * T_PTROBJ
-
-This example will be used with the following Perl statements.
-
- use RPC;
- $netconf = getnetconfigent("udp");
-
-When Perl destroys the object referenced by $netconf it will send the
-object to the supplied XSUB DESTROY function. Perl cannot determine, and
-does not care, that this object is a C struct and not a Perl object. In
-this sense, there is no difference between the object created by the
-getnetconfigent() XSUB and an object created by a normal Perl subroutine.
-
-=head2 Safely Storing Static Data in XS
-
-Starting with Perl 5.8, a macro framework has been defined to allow
-static data to be safely stored in XS modules that will be accessed from
-a multi-threaded Perl.
-
-Although primarily designed for use with multi-threaded Perl, the macros
-have been designed so that they will work with non-threaded Perl as well.
-
-It is therefore strongly recommended that these macros be used by all
-XS modules that make use of static data.
-
-The easiest way to get a template set of macros to use is by specifying
-the C<-g> (C<--global>) option with h2xs (see L<h2xs>).
-
-Below is an example module that makes use of the macros.
-
- #include "EXTERN.h"
- #include "perl.h"
- #include "XSUB.h"
-
- /* Global Data */
-
- #define MY_CXT_KEY "BlindMice::_guts" XS_VERSION
-
- typedef struct {
- int count;
- char name[3][100];
- } my_cxt_t;
-
- START_MY_CXT
-
- MODULE = BlindMice PACKAGE = BlindMice
-
- BOOT:
- {
- MY_CXT_INIT;
- MY_CXT.count = 0;
- strcpy(MY_CXT.name[0], "None");
- strcpy(MY_CXT.name[1], "None");
- strcpy(MY_CXT.name[2], "None");
- }
-
- int
- newMouse(char * name)
- char * name;
- PREINIT:
- dMY_CXT;
- CODE:
- if (MY_CXT.count >= 3) {
- warn("Already have 3 blind mice");
- RETVAL = 0;
- }
- else {
- RETVAL = ++ MY_CXT.count;
- strcpy(MY_CXT.name[MY_CXT.count - 1], name);
- }
-
- char *
- get_mouse_name(index)
- int index
- CODE:
- dMY_CXT;
- RETVAL = MY_CXT.lives ++;
- if (index > MY_CXT.count)
- croak("There are only 3 blind mice.");
- else
- RETVAL = newSVpv(MY_CXT.name[index - 1]);
-
- void
- CLONE(...)
- CODE:
- MY_CXT_CLONE;
-
-B<REFERENCE>
-
-=over 5
-
-=item MY_CXT_KEY
-
-This macro is used to define a unique key to refer to the static data
-for an XS module. The suggested naming scheme, as used by h2xs, is to
-use a string that consists of the module name, the string "::_guts"
-and the module version number.
-
- #define MY_CXT_KEY "MyModule::_guts" XS_VERSION
-
-=item typedef my_cxt_t
-
-This struct typedef I<must> always be called C<my_cxt_t>. The other
-C<CXT*> macros assume the existence of the C<my_cxt_t> typedef name.
-
-Declare a typedef named C<my_cxt_t> that is a structure that contains
-all the data that needs to be interpreter-local.
-
- typedef struct {
- int some_value;
- } my_cxt_t;
-
-=item START_MY_CXT
-
-Always place the START_MY_CXT macro directly after the declaration
-of C<my_cxt_t>.
-
-=item MY_CXT_INIT
-
-The MY_CXT_INIT macro initialises storage for the C<my_cxt_t> struct.
-
-It I<must> be called exactly once, typically in a BOOT: section. If you
-are maintaining multiple interpreters, it should be called once in each
-interpreter instance, except for interpreters cloned from existing ones.
-(But see L</MY_CXT_CLONE> below.)
-
-=item dMY_CXT
-
-Use the dMY_CXT macro (a declaration) in all the functions that access
-MY_CXT.
-
-=item MY_CXT
-
-Use the MY_CXT macro to access members of the C<my_cxt_t> struct. For
-example, if C<my_cxt_t> is
-
- typedef struct {
- int index;
- } my_cxt_t;
-
-then use this to access the C<index> member
-
- dMY_CXT;
- MY_CXT.index = 2;
-
-=item aMY_CXT/pMY_CXT
-
-C<dMY_CXT> may be quite expensive to calculate, and to avoid the overhead
-of invoking it in each function it is possible to pass the declaration
-onto other functions using the C<aMY_CXT>/C<pMY_CXT> macros, eg
-
- void sub1() {
- dMY_CXT;
- MY_CXT.index = 1;
- sub2(aMY_CXT);
- }
-
- void sub2(pMY_CXT) {
- MY_CXT.index = 2;
- }
-
-Analogously to C<pTHX>, there are equivalent forms for when the macro is the
-first or last in multiple arguments, where an underscore represents a
-comma, i.e. C<_aMY_CXT>, C<aMY_CXT_>, C<_pMY_CXT> and C<pMY_CXT_>.
-
-=item MY_CXT_CLONE
-
-By default, when a new interpreter is created as a copy of an existing one
-(eg via C<< threads->create() >>), both interpreters share the same physical
-my_cxt_t structure. Calling C<MY_CXT_CLONE> (typically via the package's
-C<CLONE()> function), causes a byte-for-byte copy of the structure to be
-taken, and any future dMY_CXT will cause the copy to be accessed instead.
-
-=item MY_CXT_INIT_INTERP(my_perl)
-
-=item dMY_CXT_INTERP(my_perl)
-
-These are versions of the macros which take an explicit interpreter as an
-argument.
-
-=back
-
-Note that these macros will only work together within the I<same> source
-file; that is, a dMY_CTX in one source file will access a different structure
-than a dMY_CTX in another source file.
-
-=head2 Thread-aware system interfaces
-
-Starting from Perl 5.8, in C/C++ level Perl knows how to wrap
-system/library interfaces that have thread-aware versions
-(e.g. getpwent_r()) into frontend macros (e.g. getpwent()) that
-correctly handle the multithreaded interaction with the Perl
-interpreter. This will happen transparently, the only thing
-you need to do is to instantiate a Perl interpreter.
-
-This wrapping happens always when compiling Perl core source
-(PERL_CORE is defined) or the Perl core extensions (PERL_EXT is
-defined). When compiling XS code outside of Perl core the wrapping
-does not take place. Note, however, that intermixing the _r-forms
-(as Perl compiled for multithreaded operation will do) and the _r-less
-forms is neither well-defined (inconsistent results, data corruption,
-or even crashes become more likely), nor is it very portable.
-
-=head1 EXAMPLES
-
-File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
-
- #include "EXTERN.h"
- #include "perl.h"
- #include "XSUB.h"
-
- #include <rpc/rpc.h>
-
- typedef struct netconfig Netconfig;
-
- MODULE = RPC PACKAGE = RPC
-
- SV *
- rpcb_gettime(host="localhost")
- char *host
- PREINIT:
- time_t timep;
- CODE:
- ST(0) = sv_newmortal();
- if( rpcb_gettime( host, &timep ) )
- sv_setnv( ST(0), (double)timep );
-
- Netconfig *
- getnetconfigent(netid="udp")
- char *netid
-
- MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
-
- void
- rpcb_DESTROY(netconf)
- Netconfig *netconf
- CODE:
- printf("NetconfigPtr::DESTROY\n");
- free( netconf );
-
-File C<typemap>: Custom typemap for RPC.xs. (cf. L<perlxstypemap>)
-
- TYPEMAP
- Netconfig * T_PTROBJ
-
-File C<RPC.pm>: Perl module for the RPC extension.
-
- package RPC;
-
- require Exporter;
- require DynaLoader;
- @ISA = qw(Exporter DynaLoader);
- @EXPORT = qw(rpcb_gettime getnetconfigent);
-
- bootstrap RPC;
- 1;
-
-File C<rpctest.pl>: Perl test program for the RPC extension.
-
- use RPC;
-
- $netconf = getnetconfigent();
- $a = rpcb_gettime();
- print "time = $a\n";
- print "netconf = $netconf\n";
-
- $netconf = getnetconfigent("tcp");
- $a = rpcb_gettime("poplar");
- print "time = $a\n";
- print "netconf = $netconf\n";
-
-
-=head1 XS VERSION
-
-This document covers features supported by C<ExtUtils::ParseXS>
-(also known as C<xsubpp>) 3.13_01.
-
-=head1 AUTHOR
-
-Originally written by Dean Roehrich <F<roehrich@cray.com>>.
-
-Maintained since 1996 by The Perl Porters <F<perlbug@perl.org>>.
diff --git a/Master/tlpkg/tlperl/lib/pods/perlxstut.pod b/Master/tlpkg/tlperl/lib/pods/perlxstut.pod
deleted file mode 100644
index 93c1bfbe61b..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlxstut.pod
+++ /dev/null
@@ -1,1379 +0,0 @@
-=head1 NAME
-
-perlxstut - Tutorial for writing XSUBs
-
-=head1 DESCRIPTION
-
-This tutorial will educate the reader on the steps involved in creating
-a Perl extension. The reader is assumed to have access to L<perlguts>,
-L<perlapi> and L<perlxs>.
-
-This tutorial starts with very simple examples and becomes more complex,
-with each new example adding new features. Certain concepts may not be
-completely explained until later in the tutorial in order to slowly ease
-the reader into building extensions.
-
-This tutorial was written from a Unix point of view. Where I know them
-to be otherwise different for other platforms (e.g. Win32), I will list
-them. If you find something that was missed, please let me know.
-
-=head1 SPECIAL NOTES
-
-=head2 make
-
-This tutorial assumes that the make program that Perl is configured to
-use is called C<make>. Instead of running "make" in the examples that
-follow, you may have to substitute whatever make program Perl has been
-configured to use. Running B<perl -V:make> should tell you what it is.
-
-=head2 Version caveat
-
-When writing a Perl extension for general consumption, one should expect that
-the extension will be used with versions of Perl different from the
-version available on your machine. Since you are reading this document,
-the version of Perl on your machine is probably 5.005 or later, but the users
-of your extension may have more ancient versions.
-
-To understand what kinds of incompatibilities one may expect, and in the rare
-case that the version of Perl on your machine is older than this document,
-see the section on "Troubleshooting these Examples" for more information.
-
-If your extension uses some features of Perl which are not available on older
-releases of Perl, your users would appreciate an early meaningful warning.
-You would probably put this information into the F<README> file, but nowadays
-installation of extensions may be performed automatically, guided by F<CPAN.pm>
-module or other tools.
-
-In MakeMaker-based installations, F<Makefile.PL> provides the earliest
-opportunity to perform version checks. One can put something like this
-in F<Makefile.PL> for this purpose:
-
- eval { require 5.007 }
- or die <<EOD;
- ############
- ### This module uses frobnication framework which is not available before
- ### version 5.007 of Perl. Upgrade your Perl before installing Kara::Mba.
- ############
- EOD
-
-=head2 Dynamic Loading versus Static Loading
-
-It is commonly thought that if a system does not have the capability to
-dynamically load a library, you cannot build XSUBs. This is incorrect.
-You I<can> build them, but you must link the XSUBs subroutines with the
-rest of Perl, creating a new executable. This situation is similar to
-Perl 4.
-
-This tutorial can still be used on such a system. The XSUB build mechanism
-will check the system and build a dynamically-loadable library if possible,
-or else a static library and then, optionally, a new statically-linked
-executable with that static library linked in.
-
-Should you wish to build a statically-linked executable on a system which
-can dynamically load libraries, you may, in all the following examples,
-where the command "C<make>" with no arguments is executed, run the command
-"C<make perl>" instead.
-
-If you have generated such a statically-linked executable by choice, then
-instead of saying "C<make test>", you should say "C<make test_static>".
-On systems that cannot build dynamically-loadable libraries at all, simply
-saying "C<make test>" is sufficient.
-
-=head1 TUTORIAL
-
-Now let's go on with the show!
-
-=head2 EXAMPLE 1
-
-Our first extension will be very simple. When we call the routine in the
-extension, it will print out a well-known message and return.
-
-Run "C<h2xs -A -n Mytest>". This creates a directory named Mytest,
-possibly under ext/ if that directory exists in the current working
-directory. Several files will be created under the Mytest dir, including
-MANIFEST, Makefile.PL, lib/Mytest.pm, Mytest.xs, t/Mytest.t, and Changes.
-
-The MANIFEST file contains the names of all the files just created in the
-Mytest directory.
-
-The file Makefile.PL should look something like this:
-
- use ExtUtils::MakeMaker;
- # See lib/ExtUtils/MakeMaker.pm for details of how to influence
- # the contents of the Makefile that is written.
- WriteMakefile(
- NAME => 'Mytest',
- VERSION_FROM => 'Mytest.pm', # finds $VERSION
- LIBS => [''], # e.g., '-lm'
- DEFINE => '', # e.g., '-DHAVE_SOMETHING'
- INC => '', # e.g., '-I/usr/include/other'
- );
-
-The file Mytest.pm should start with something like this:
-
- package Mytest;
-
- use 5.008008;
- use strict;
- use warnings;
-
- require Exporter;
-
- our @ISA = qw(Exporter);
- our %EXPORT_TAGS = ( 'all' => [ qw(
-
- ) ] );
-
- our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
-
- our @EXPORT = qw(
-
- );
-
- our $VERSION = '0.01';
-
- require XSLoader;
- XSLoader::load('Mytest', $VERSION);
-
- # Preloaded methods go here.
-
- 1;
- __END__
- # Below is the stub of documentation for your module. You better edit it!
-
-The rest of the .pm file contains sample code for providing documentation for
-the extension.
-
-Finally, the Mytest.xs file should look something like this:
-
- #include "EXTERN.h"
- #include "perl.h"
- #include "XSUB.h"
-
- #include "ppport.h"
-
- MODULE = Mytest PACKAGE = Mytest
-
-Let's edit the .xs file by adding this to the end of the file:
-
- void
- hello()
- CODE:
- printf("Hello, world!\n");
-
-It is okay for the lines starting at the "CODE:" line to not be indented.
-However, for readability purposes, it is suggested that you indent CODE:
-one level and the lines following one more level.
-
-Now we'll run "C<perl Makefile.PL>". This will create a real Makefile,
-which make needs. Its output looks something like:
-
- % perl Makefile.PL
- Checking if your kit is complete...
- Looks good
- Writing Makefile for Mytest
- %
-
-Now, running make will produce output that looks something like this (some
-long lines have been shortened for clarity and some extraneous lines have
-been deleted):
-
- % make
- cp lib/Mytest.pm blib/lib/Mytest.pm
- perl xsubpp -typemap typemap Mytest.xs > Mytest.xsc && mv Mytest.xsc Mytest.c
- Please specify prototyping behavior for Mytest.xs (see perlxs manual)
- cc -c Mytest.c
- Running Mkbootstrap for Mytest ()
- chmod 644 Mytest.bs
- rm -f blib/arch/auto/Mytest/Mytest.so
- cc -shared -L/usr/local/lib Mytest.o -o blib/arch/auto/Mytest/Mytest.so \
- \
-
- chmod 755 blib/arch/auto/Mytest/Mytest.so
- cp Mytest.bs blib/arch/auto/Mytest/Mytest.bs
- chmod 644 blib/arch/auto/Mytest/Mytest.bs
- Manifying blib/man3/Mytest.3pm
- %
-
-You can safely ignore the line about "prototyping behavior" - it is
-explained in L<perlxs/"The PROTOTYPES: Keyword">.
-
-Perl has its own special way of easily writing test scripts, but for this
-example only, we'll create our own test script. Create a file called hello
-that looks like this:
-
- #! /opt/perl5/bin/perl
-
- use ExtUtils::testlib;
-
- use Mytest;
-
- Mytest::hello();
-
-Now we make the script executable (C<chmod +x hello>), run the script
-and we should see the following output:
-
- % ./hello
- Hello, world!
- %
-
-=head2 EXAMPLE 2
-
-Now let's add to our extension a subroutine that will take a single numeric
-argument as input and return 1 if the number is even or 0 if the number
-is odd.
-
-Add the following to the end of Mytest.xs:
-
- int
- is_even(input)
- int input
- CODE:
- RETVAL = (input % 2 == 0);
- OUTPUT:
- RETVAL
-
-There does not need to be whitespace at the start of the "C<int input>"
-line, but it is useful for improving readability. Placing a semi-colon at
-the end of that line is also optional. Any amount and kind of whitespace
-may be placed between the "C<int>" and "C<input>".
-
-Now re-run make to rebuild our new shared library.
-
-Now perform the same steps as before, generating a Makefile from the
-Makefile.PL file, and running make.
-
-In order to test that our extension works, we now need to look at the
-file Mytest.t. This file is set up to imitate the same kind of testing
-structure that Perl itself has. Within the test script, you perform a
-number of tests to confirm the behavior of the extension, printing "ok"
-when the test is correct, "not ok" when it is not.
-
- use Test::More tests => 4;
- BEGIN { use_ok('Mytest') };
-
- #########################
-
- # Insert your test code below, the Test::More module is use()ed here so read
- # its man page ( perldoc Test::More ) for help writing this test script.
-
- is(&Mytest::is_even(0), 1);
- is(&Mytest::is_even(1), 0);
- is(&Mytest::is_even(2), 1);
-
-We will be calling the test script through the command "C<make test>". You
-should see output that looks something like this:
-
- %make test
- PERL_DL_NONLAZY=1 /usr/bin/perl "-MExtUtils::Command::MM" "-e" "test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
- t/Mytest....ok
- All tests successful.
- Files=1, Tests=4, 0 wallclock secs ( 0.03 cusr + 0.00 csys = 0.03 CPU)
- %
-
-=head2 What has gone on?
-
-The program h2xs is the starting point for creating extensions. In later
-examples we'll see how we can use h2xs to read header files and generate
-templates to connect to C routines.
-
-h2xs creates a number of files in the extension directory. The file
-Makefile.PL is a perl script which will generate a true Makefile to build
-the extension. We'll take a closer look at it later.
-
-The .pm and .xs files contain the meat of the extension. The .xs file holds
-the C routines that make up the extension. The .pm file contains routines
-that tell Perl how to load your extension.
-
-Generating the Makefile and running C<make> created a directory called blib
-(which stands for "build library") in the current working directory. This
-directory will contain the shared library that we will build. Once we have
-tested it, we can install it into its final location.
-
-Invoking the test script via "C<make test>" did something very important.
-It invoked perl with all those C<-I> arguments so that it could find the
-various files that are part of the extension. It is I<very> important that
-while you are still testing extensions that you use "C<make test>". If you
-try to run the test script all by itself, you will get a fatal error.
-Another reason it is important to use "C<make test>" to run your test
-script is that if you are testing an upgrade to an already-existing version,
-using "C<make test>" ensures that you will test your new extension, not the
-already-existing version.
-
-When Perl sees a C<use extension;>, it searches for a file with the same name
-as the C<use>'d extension that has a .pm suffix. If that file cannot be found,
-Perl dies with a fatal error. The default search path is contained in the
-C<@INC> array.
-
-In our case, Mytest.pm tells perl that it will need the Exporter and Dynamic
-Loader extensions. It then sets the C<@ISA> and C<@EXPORT> arrays and the
-C<$VERSION> scalar; finally it tells perl to bootstrap the module. Perl
-will call its dynamic loader routine (if there is one) and load the shared
-library.
-
-The two arrays C<@ISA> and C<@EXPORT> are very important. The C<@ISA>
-array contains a list of other packages in which to search for methods (or
-subroutines) that do not exist in the current package. This is usually
-only important for object-oriented extensions (which we will talk about
-much later), and so usually doesn't need to be modified.
-
-The C<@EXPORT> array tells Perl which of the extension's variables and
-subroutines should be placed into the calling package's namespace. Because
-you don't know if the user has already used your variable and subroutine
-names, it's vitally important to carefully select what to export. Do I<not>
-export method or variable names I<by default> without a good reason.
-
-As a general rule, if the module is trying to be object-oriented then don't
-export anything. If it's just a collection of functions and variables, then
-you can export them via another array, called C<@EXPORT_OK>. This array
-does not automatically place its subroutine and variable names into the
-namespace unless the user specifically requests that this be done.
-
-See L<perlmod> for more information.
-
-The C<$VERSION> variable is used to ensure that the .pm file and the shared
-library are "in sync" with each other. Any time you make changes to
-the .pm or .xs files, you should increment the value of this variable.
-
-=head2 Writing good test scripts
-
-The importance of writing good test scripts cannot be over-emphasized. You
-should closely follow the "ok/not ok" style that Perl itself uses, so that
-it is very easy and unambiguous to determine the outcome of each test case.
-When you find and fix a bug, make sure you add a test case for it.
-
-By running "C<make test>", you ensure that your Mytest.t script runs and uses
-the correct version of your extension. If you have many test cases,
-save your test files in the "t" directory and use the suffix ".t".
-When you run "C<make test>", all of these test files will be executed.
-
-=head2 EXAMPLE 3
-
-Our third extension will take one argument as its input, round off that
-value, and set the I<argument> to the rounded value.
-
-Add the following to the end of Mytest.xs:
-
- void
- round(arg)
- double arg
- CODE:
- if (arg > 0.0) {
- arg = floor(arg + 0.5);
- } else if (arg < 0.0) {
- arg = ceil(arg - 0.5);
- } else {
- arg = 0.0;
- }
- OUTPUT:
- arg
-
-Edit the Makefile.PL file so that the corresponding line looks like this:
-
- 'LIBS' => ['-lm'], # e.g., '-lm'
-
-Generate the Makefile and run make. Change the test number in Mytest.t to
-"9" and add the following tests:
-
- $i = -1.5; &Mytest::round($i); is( $i, -2.0 );
- $i = -1.1; &Mytest::round($i); is( $i, -1.0 );
- $i = 0.0; &Mytest::round($i); is( $i, 0.0 );
- $i = 0.5; &Mytest::round($i); is( $i, 1.0 );
- $i = 1.2; &Mytest::round($i); is( $i, 1.0 );
-
-Running "C<make test>" should now print out that all nine tests are okay.
-
-Notice that in these new test cases, the argument passed to round was a
-scalar variable. You might be wondering if you can round a constant or
-literal. To see what happens, temporarily add the following line to Mytest.t:
-
- &Mytest::round(3);
-
-Run "C<make test>" and notice that Perl dies with a fatal error. Perl won't
-let you change the value of constants!
-
-=head2 What's new here?
-
-=over 4
-
-=item *
-
-We've made some changes to Makefile.PL. In this case, we've specified an
-extra library to be linked into the extension's shared library, the math
-library libm in this case. We'll talk later about how to write XSUBs that
-can call every routine in a library.
-
-=item *
-
-The value of the function is not being passed back as the function's return
-value, but by changing the value of the variable that was passed into the
-function. You might have guessed that when you saw that the return value
-of round is of type "void".
-
-=back
-
-=head2 Input and Output Parameters
-
-You specify the parameters that will be passed into the XSUB on the line(s)
-after you declare the function's return value and name. Each input parameter
-line starts with optional whitespace, and may have an optional terminating
-semicolon.
-
-The list of output parameters occurs at the very end of the function, just
-after the OUTPUT: directive. The use of RETVAL tells Perl that you
-wish to send this value back as the return value of the XSUB function. In
-Example 3, we wanted the "return value" placed in the original variable
-which we passed in, so we listed it (and not RETVAL) in the OUTPUT: section.
-
-=head2 The XSUBPP Program
-
-The B<xsubpp> program takes the XS code in the .xs file and translates it into
-C code, placing it in a file whose suffix is .c. The C code created makes
-heavy use of the C functions within Perl.
-
-=head2 The TYPEMAP file
-
-The B<xsubpp> program uses rules to convert from Perl's data types (scalar,
-array, etc.) to C's data types (int, char, etc.). These rules are stored
-in the typemap file ($PERLLIB/ExtUtils/typemap). There's a brief discussion
-below, but all the nitty-gritty details can be found in L<perlxstypemap>.
-If you have a new-enough version of perl (5.16 and up) or an upgraded
-XS compiler (C<ExtUtils::ParseXS> 3.13_01 or better), then you can inline
-typemaps in your XS instead of writing separate files.
-Either way, this typemap thing is split into three parts:
-
-The first section maps various C data types to a name, which corresponds
-somewhat with the various Perl types. The second section contains C code
-which B<xsubpp> uses to handle input parameters. The third section contains
-C code which B<xsubpp> uses to handle output parameters.
-
-Let's take a look at a portion of the .c file created for our extension.
-The file name is Mytest.c:
-
- XS(XS_Mytest_round)
- {
- dXSARGS;
- if (items != 1)
- Perl_croak(aTHX_ "Usage: Mytest::round(arg)");
- PERL_UNUSED_VAR(cv); /* -W */
- {
- double arg = (double)SvNV(ST(0)); /* XXXXX */
- if (arg > 0.0) {
- arg = floor(arg + 0.5);
- } else if (arg < 0.0) {
- arg = ceil(arg - 0.5);
- } else {
- arg = 0.0;
- }
- sv_setnv(ST(0), (double)arg); /* XXXXX */
- SvSETMAGIC(ST(0));
- }
- XSRETURN_EMPTY;
- }
-
-Notice the two lines commented with "XXXXX". If you check the first part
-of the typemap file (or section), you'll see that doubles are of type
-T_DOUBLE. In the INPUT part of the typemap, an argument that is T_DOUBLE
-is assigned to the variable arg by calling the routine SvNV on something,
-then casting it to double, then assigned to the variable arg. Similarly,
-in the OUTPUT section, once arg has its final value, it is passed to the
-sv_setnv function to be passed back to the calling subroutine. These two
-functions are explained in L<perlguts>; we'll talk more later about what
-that "ST(0)" means in the section on the argument stack.
-
-=head2 Warning about Output Arguments
-
-In general, it's not a good idea to write extensions that modify their input
-parameters, as in Example 3. Instead, you should probably return multiple
-values in an array and let the caller handle them (we'll do this in a later
-example). However, in order to better accommodate calling pre-existing C
-routines, which often do modify their input parameters, this behavior is
-tolerated.
-
-=head2 EXAMPLE 4
-
-In this example, we'll now begin to write XSUBs that will interact with
-pre-defined C libraries. To begin with, we will build a small library of
-our own, then let h2xs write our .pm and .xs files for us.
-
-Create a new directory called Mytest2 at the same level as the directory
-Mytest. In the Mytest2 directory, create another directory called mylib,
-and cd into that directory.
-
-Here we'll create some files that will generate a test library. These will
-include a C source file and a header file. We'll also create a Makefile.PL
-in this directory. Then we'll make sure that running make at the Mytest2
-level will automatically run this Makefile.PL file and the resulting Makefile.
-
-In the mylib directory, create a file mylib.h that looks like this:
-
- #define TESTVAL 4
-
- extern double foo(int, long, const char*);
-
-Also create a file mylib.c that looks like this:
-
- #include <stdlib.h>
- #include "./mylib.h"
-
- double
- foo(int a, long b, const char *c)
- {
- return (a + b + atof(c) + TESTVAL);
- }
-
-And finally create a file Makefile.PL that looks like this:
-
- use ExtUtils::MakeMaker;
- $Verbose = 1;
- WriteMakefile(
- NAME => 'Mytest2::mylib',
- SKIP => [qw(all static static_lib dynamic dynamic_lib)],
- clean => {'FILES' => 'libmylib$(LIB_EXT)'},
- );
-
-
- sub MY::top_targets {
- '
- all :: static
-
- pure_all :: static
-
- static :: libmylib$(LIB_EXT)
-
- libmylib$(LIB_EXT): $(O_FILES)
- $(AR) cr libmylib$(LIB_EXT) $(O_FILES)
- $(RANLIB) libmylib$(LIB_EXT)
-
- ';
- }
-
-Make sure you use a tab and not spaces on the lines beginning with "$(AR)"
-and "$(RANLIB)". Make will not function properly if you use spaces.
-It has also been reported that the "cr" argument to $(AR) is unnecessary
-on Win32 systems.
-
-We will now create the main top-level Mytest2 files. Change to the directory
-above Mytest2 and run the following command:
-
- % h2xs -O -n Mytest2 ./Mytest2/mylib/mylib.h
-
-This will print out a warning about overwriting Mytest2, but that's okay.
-Our files are stored in Mytest2/mylib, and will be untouched.
-
-The normal Makefile.PL that h2xs generates doesn't know about the mylib
-directory. We need to tell it that there is a subdirectory and that we
-will be generating a library in it. Let's add the argument MYEXTLIB to
-the WriteMakefile call so that it looks like this:
-
- WriteMakefile(
- 'NAME' => 'Mytest2',
- 'VERSION_FROM' => 'Mytest2.pm', # finds $VERSION
- 'LIBS' => [''], # e.g., '-lm'
- 'DEFINE' => '', # e.g., '-DHAVE_SOMETHING'
- 'INC' => '', # e.g., '-I/usr/include/other'
- 'MYEXTLIB' => 'mylib/libmylib$(LIB_EXT)',
- );
-
-and then at the end add a subroutine (which will override the pre-existing
-subroutine). Remember to use a tab character to indent the line beginning
-with "cd"!
-
- sub MY::postamble {
- '
- $(MYEXTLIB): mylib/Makefile
- cd mylib && $(MAKE) $(PASSTHRU)
- ';
- }
-
-Let's also fix the MANIFEST file so that it accurately reflects the contents
-of our extension. The single line that says "mylib" should be replaced by
-the following three lines:
-
- mylib/Makefile.PL
- mylib/mylib.c
- mylib/mylib.h
-
-To keep our namespace nice and unpolluted, edit the .pm file and change
-the variable C<@EXPORT> to C<@EXPORT_OK>. Finally, in the
-.xs file, edit the #include line to read:
-
- #include "mylib/mylib.h"
-
-And also add the following function definition to the end of the .xs file:
-
- double
- foo(a,b,c)
- int a
- long b
- const char * c
- OUTPUT:
- RETVAL
-
-Now we also need to create a typemap because the default Perl doesn't
-currently support the C<const char *> type. Include a new TYPEMAP
-section in your XS code before the above function:
-
- TYPEMAP: <<END;
- const char * T_PV
- END
-
-Now run perl on the top-level Makefile.PL. Notice that it also created a
-Makefile in the mylib directory. Run make and watch that it does cd into
-the mylib directory and run make in there as well.
-
-Now edit the Mytest2.t script and change the number of tests to "4",
-and add the following lines to the end of the script:
-
- is( &Mytest2::foo(1, 2, "Hello, world!"), 7 );
- is( &Mytest2::foo(1, 2, "0.0"), 7 );
- ok( abs(&Mytest2::foo(0, 0, "-3.4") - 0.6) <= 0.01 );
-
-(When dealing with floating-point comparisons, it is best to not check for
-equality, but rather that the difference between the expected and actual
-result is below a certain amount (called epsilon) which is 0.01 in this case)
-
-Run "C<make test>" and all should be well. There are some warnings on missing tests
-for the Mytest2::mylib extension, but you can ignore them.
-
-=head2 What has happened here?
-
-Unlike previous examples, we've now run h2xs on a real include file. This
-has caused some extra goodies to appear in both the .pm and .xs files.
-
-=over 4
-
-=item *
-
-In the .xs file, there's now a #include directive with the absolute path to
-the mylib.h header file. We changed this to a relative path so that we
-could move the extension directory if we wanted to.
-
-=item *
-
-There's now some new C code that's been added to the .xs file. The purpose
-of the C<constant> routine is to make the values that are #define'd in the
-header file accessible by the Perl script (by calling either C<TESTVAL> or
-C<&Mytest2::TESTVAL>). There's also some XS code to allow calls to the
-C<constant> routine.
-
-=item *
-
-The .pm file originally exported the name C<TESTVAL> in the C<@EXPORT> array.
-This could lead to name clashes. A good rule of thumb is that if the #define
-is only going to be used by the C routines themselves, and not by the user,
-they should be removed from the C<@EXPORT> array. Alternately, if you don't
-mind using the "fully qualified name" of a variable, you could move most
-or all of the items from the C<@EXPORT> array into the C<@EXPORT_OK> array.
-
-=item *
-
-If our include file had contained #include directives, these would not have
-been processed by h2xs. There is no good solution to this right now.
-
-=item *
-
-We've also told Perl about the library that we built in the mylib
-subdirectory. That required only the addition of the C<MYEXTLIB> variable
-to the WriteMakefile call and the replacement of the postamble subroutine
-to cd into the subdirectory and run make. The Makefile.PL for the
-library is a bit more complicated, but not excessively so. Again we
-replaced the postamble subroutine to insert our own code. This code
-simply specified that the library to be created here was a static archive
-library (as opposed to a dynamically loadable library) and provided the
-commands to build it.
-
-=back
-
-=head2 Anatomy of .xs file
-
-The .xs file of L<"EXAMPLE 4"> contained some new elements. To understand
-the meaning of these elements, pay attention to the line which reads
-
- MODULE = Mytest2 PACKAGE = Mytest2
-
-Anything before this line is plain C code which describes which headers
-to include, and defines some convenience functions. No translations are
-performed on this part, apart from having embedded POD documentation
-skipped over (see L<perlpod>) it goes into the generated output C file as is.
-
-Anything after this line is the description of XSUB functions.
-These descriptions are translated by B<xsubpp> into C code which
-implements these functions using Perl calling conventions, and which
-makes these functions visible from Perl interpreter.
-
-Pay a special attention to the function C<constant>. This name appears
-twice in the generated .xs file: once in the first part, as a static C
-function, then another time in the second part, when an XSUB interface to
-this static C function is defined.
-
-This is quite typical for .xs files: usually the .xs file provides
-an interface to an existing C function. Then this C function is defined
-somewhere (either in an external library, or in the first part of .xs file),
-and a Perl interface to this function (i.e. "Perl glue") is described in the
-second part of .xs file. The situation in L<"EXAMPLE 1">, L<"EXAMPLE 2">,
-and L<"EXAMPLE 3">, when all the work is done inside the "Perl glue", is
-somewhat of an exception rather than the rule.
-
-=head2 Getting the fat out of XSUBs
-
-In L<"EXAMPLE 4"> the second part of .xs file contained the following
-description of an XSUB:
-
- double
- foo(a,b,c)
- int a
- long b
- const char * c
- OUTPUT:
- RETVAL
-
-Note that in contrast with L<"EXAMPLE 1">, L<"EXAMPLE 2"> and L<"EXAMPLE 3">,
-this description does not contain the actual I<code> for what is done
-during a call to Perl function foo(). To understand what is going
-on here, one can add a CODE section to this XSUB:
-
- double
- foo(a,b,c)
- int a
- long b
- const char * c
- CODE:
- RETVAL = foo(a,b,c);
- OUTPUT:
- RETVAL
-
-However, these two XSUBs provide almost identical generated C code: B<xsubpp>
-compiler is smart enough to figure out the C<CODE:> section from the first
-two lines of the description of XSUB. What about C<OUTPUT:> section? In
-fact, that is absolutely the same! The C<OUTPUT:> section can be removed
-as well, I<as far as C<CODE:> section or C<PPCODE:> section> is not
-specified: B<xsubpp> can see that it needs to generate a function call
-section, and will autogenerate the OUTPUT section too. Thus one can
-shortcut the XSUB to become:
-
- double
- foo(a,b,c)
- int a
- long b
- const char * c
-
-Can we do the same with an XSUB
-
- int
- is_even(input)
- int input
- CODE:
- RETVAL = (input % 2 == 0);
- OUTPUT:
- RETVAL
-
-of L<"EXAMPLE 2">? To do this, one needs to define a C function C<int
-is_even(int input)>. As we saw in L<Anatomy of .xs file>, a proper place
-for this definition is in the first part of .xs file. In fact a C function
-
- int
- is_even(int arg)
- {
- return (arg % 2 == 0);
- }
-
-is probably overkill for this. Something as simple as a C<#define> will
-do too:
-
- #define is_even(arg) ((arg) % 2 == 0)
-
-After having this in the first part of .xs file, the "Perl glue" part becomes
-as simple as
-
- int
- is_even(input)
- int input
-
-This technique of separation of the glue part from the workhorse part has
-obvious tradeoffs: if you want to change a Perl interface, you need to
-change two places in your code. However, it removes a lot of clutter,
-and makes the workhorse part independent from idiosyncrasies of Perl calling
-convention. (In fact, there is nothing Perl-specific in the above description,
-a different version of B<xsubpp> might have translated this to TCL glue or
-Python glue as well.)
-
-=head2 More about XSUB arguments
-
-With the completion of Example 4, we now have an easy way to simulate some
-real-life libraries whose interfaces may not be the cleanest in the world.
-We shall now continue with a discussion of the arguments passed to the
-B<xsubpp> compiler.
-
-When you specify arguments to routines in the .xs file, you are really
-passing three pieces of information for each argument listed. The first
-piece is the order of that argument relative to the others (first, second,
-etc). The second is the type of argument, and consists of the type
-declaration of the argument (e.g., int, char*, etc). The third piece is
-the calling convention for the argument in the call to the library function.
-
-While Perl passes arguments to functions by reference,
-C passes arguments by value; to implement a C function which modifies data
-of one of the "arguments", the actual argument of this C function would be
-a pointer to the data. Thus two C functions with declarations
-
- int string_length(char *s);
- int upper_case_char(char *cp);
-
-may have completely different semantics: the first one may inspect an array
-of chars pointed by s, and the second one may immediately dereference C<cp>
-and manipulate C<*cp> only (using the return value as, say, a success
-indicator). From Perl one would use these functions in
-a completely different manner.
-
-One conveys this info to B<xsubpp> by replacing C<*> before the
-argument by C<&>. C<&> means that the argument should be passed to a library
-function by its address. The above two function may be XSUB-ified as
-
- int
- string_length(s)
- char * s
-
- int
- upper_case_char(cp)
- char &cp
-
-For example, consider:
-
- int
- foo(a,b)
- char &a
- char * b
-
-The first Perl argument to this function would be treated as a char and assigned
-to the variable a, and its address would be passed into the function foo.
-The second Perl argument would be treated as a string pointer and assigned to the
-variable b. The I<value> of b would be passed into the function foo. The
-actual call to the function foo that B<xsubpp> generates would look like this:
-
- foo(&a, b);
-
-B<xsubpp> will parse the following function argument lists identically:
-
- char &a
- char&a
- char & a
-
-However, to help ease understanding, it is suggested that you place a "&"
-next to the variable name and away from the variable type), and place a
-"*" near the variable type, but away from the variable name (as in the
-call to foo above). By doing so, it is easy to understand exactly what
-will be passed to the C function; it will be whatever is in the "last
-column".
-
-You should take great pains to try to pass the function the type of variable
-it wants, when possible. It will save you a lot of trouble in the long run.
-
-=head2 The Argument Stack
-
-If we look at any of the C code generated by any of the examples except
-example 1, you will notice a number of references to ST(n), where n is
-usually 0. "ST" is actually a macro that points to the n'th argument
-on the argument stack. ST(0) is thus the first argument on the stack and
-therefore the first argument passed to the XSUB, ST(1) is the second
-argument, and so on.
-
-When you list the arguments to the XSUB in the .xs file, that tells B<xsubpp>
-which argument corresponds to which of the argument stack (i.e., the first
-one listed is the first argument, and so on). You invite disaster if you
-do not list them in the same order as the function expects them.
-
-The actual values on the argument stack are pointers to the values passed
-in. When an argument is listed as being an OUTPUT value, its corresponding
-value on the stack (i.e., ST(0) if it was the first argument) is changed.
-You can verify this by looking at the C code generated for Example 3.
-The code for the round() XSUB routine contains lines that look like this:
-
- double arg = (double)SvNV(ST(0));
- /* Round the contents of the variable arg */
- sv_setnv(ST(0), (double)arg);
-
-The arg variable is initially set by taking the value from ST(0), then is
-stored back into ST(0) at the end of the routine.
-
-XSUBs are also allowed to return lists, not just scalars. This must be
-done by manipulating stack values ST(0), ST(1), etc, in a subtly
-different way. See L<perlxs> for details.
-
-XSUBs are also allowed to avoid automatic conversion of Perl function arguments
-to C function arguments. See L<perlxs> for details. Some people prefer
-manual conversion by inspecting C<ST(i)> even in the cases when automatic
-conversion will do, arguing that this makes the logic of an XSUB call clearer.
-Compare with L<"Getting the fat out of XSUBs"> for a similar tradeoff of
-a complete separation of "Perl glue" and "workhorse" parts of an XSUB.
-
-While experts may argue about these idioms, a novice to Perl guts may
-prefer a way which is as little Perl-guts-specific as possible, meaning
-automatic conversion and automatic call generation, as in
-L<"Getting the fat out of XSUBs">. This approach has the additional
-benefit of protecting the XSUB writer from future changes to the Perl API.
-
-=head2 Extending your Extension
-
-Sometimes you might want to provide some extra methods or subroutines
-to assist in making the interface between Perl and your extension simpler
-or easier to understand. These routines should live in the .pm file.
-Whether they are automatically loaded when the extension itself is loaded
-or only loaded when called depends on where in the .pm file the subroutine
-definition is placed. You can also consult L<AutoLoader> for an alternate
-way to store and load your extra subroutines.
-
-=head2 Documenting your Extension
-
-There is absolutely no excuse for not documenting your extension.
-Documentation belongs in the .pm file. This file will be fed to pod2man,
-and the embedded documentation will be converted to the manpage format,
-then placed in the blib directory. It will be copied to Perl's
-manpage directory when the extension is installed.
-
-You may intersperse documentation and Perl code within the .pm file.
-In fact, if you want to use method autoloading, you must do this,
-as the comment inside the .pm file explains.
-
-See L<perlpod> for more information about the pod format.
-
-=head2 Installing your Extension
-
-Once your extension is complete and passes all its tests, installing it
-is quite simple: you simply run "make install". You will either need
-to have write permission into the directories where Perl is installed,
-or ask your system administrator to run the make for you.
-
-Alternately, you can specify the exact directory to place the extension's
-files by placing a "PREFIX=/destination/directory" after the make install.
-(or in between the make and install if you have a brain-dead version of make).
-This can be very useful if you are building an extension that will eventually
-be distributed to multiple systems. You can then just archive the files in
-the destination directory and distribute them to your destination systems.
-
-=head2 EXAMPLE 5
-
-In this example, we'll do some more work with the argument stack. The
-previous examples have all returned only a single value. We'll now
-create an extension that returns an array.
-
-This extension is very Unix-oriented (struct statfs and the statfs system
-call). If you are not running on a Unix system, you can substitute for
-statfs any other function that returns multiple values, you can hard-code
-values to be returned to the caller (although this will be a bit harder
-to test the error case), or you can simply not do this example. If you
-change the XSUB, be sure to fix the test cases to match the changes.
-
-Return to the Mytest directory and add the following code to the end of
-Mytest.xs:
-
- void
- statfs(path)
- char * path
- INIT:
- int i;
- struct statfs buf;
-
- PPCODE:
- i = statfs(path, &buf);
- if (i == 0) {
- XPUSHs(sv_2mortal(newSVnv(buf.f_bavail)));
- XPUSHs(sv_2mortal(newSVnv(buf.f_bfree)));
- XPUSHs(sv_2mortal(newSVnv(buf.f_blocks)));
- XPUSHs(sv_2mortal(newSVnv(buf.f_bsize)));
- XPUSHs(sv_2mortal(newSVnv(buf.f_ffree)));
- XPUSHs(sv_2mortal(newSVnv(buf.f_files)));
- XPUSHs(sv_2mortal(newSVnv(buf.f_type)));
- } else {
- XPUSHs(sv_2mortal(newSVnv(errno)));
- }
-
-You'll also need to add the following code to the top of the .xs file, just
-after the include of "XSUB.h":
-
- #include <sys/vfs.h>
-
-Also add the following code segment to Mytest.t while incrementing the "9"
-tests to "11":
-
- @a = &Mytest::statfs("/blech");
- ok( scalar(@a) == 1 && $a[0] == 2 );
- @a = &Mytest::statfs("/");
- is( scalar(@a), 7 );
-
-=head2 New Things in this Example
-
-This example added quite a few new concepts. We'll take them one at a time.
-
-=over 4
-
-=item *
-
-The INIT: directive contains code that will be placed immediately after
-the argument stack is decoded. C does not allow variable declarations at
-arbitrary locations inside a function,
-so this is usually the best way to declare local variables needed by the XSUB.
-(Alternatively, one could put the whole C<PPCODE:> section into braces, and
-put these declarations on top.)
-
-=item *
-
-This routine also returns a different number of arguments depending on the
-success or failure of the call to statfs. If there is an error, the error
-number is returned as a single-element array. If the call is successful,
-then a 7-element array is returned. Since only one argument is passed into
-this function, we need room on the stack to hold the 7 values which may be
-returned.
-
-We do this by using the PPCODE: directive, rather than the CODE: directive.
-This tells B<xsubpp> that we will be managing the return values that will be
-put on the argument stack by ourselves.
-
-=item *
-
-When we want to place values to be returned to the caller onto the stack,
-we use the series of macros that begin with "XPUSH". There are five
-different versions, for placing integers, unsigned integers, doubles,
-strings, and Perl scalars on the stack. In our example, we placed a
-Perl scalar onto the stack. (In fact this is the only macro which
-can be used to return multiple values.)
-
-The XPUSH* macros will automatically extend the return stack to prevent
-it from being overrun. You push values onto the stack in the order you
-want them seen by the calling program.
-
-=item *
-
-The values pushed onto the return stack of the XSUB are actually mortal SV's.
-They are made mortal so that once the values are copied by the calling
-program, the SV's that held the returned values can be deallocated.
-If they were not mortal, then they would continue to exist after the XSUB
-routine returned, but would not be accessible. This is a memory leak.
-
-=item *
-
-If we were interested in performance, not in code compactness, in the success
-branch we would not use C<XPUSHs> macros, but C<PUSHs> macros, and would
-pre-extend the stack before pushing the return values:
-
- EXTEND(SP, 7);
-
-The tradeoff is that one needs to calculate the number of return values
-in advance (though overextending the stack will not typically hurt
-anything but memory consumption).
-
-Similarly, in the failure branch we could use C<PUSHs> I<without> extending
-the stack: the Perl function reference comes to an XSUB on the stack, thus
-the stack is I<always> large enough to take one return value.
-
-=back
-
-=head2 EXAMPLE 6
-
-In this example, we will accept a reference to an array as an input
-parameter, and return a reference to an array of hashes. This will
-demonstrate manipulation of complex Perl data types from an XSUB.
-
-This extension is somewhat contrived. It is based on the code in
-the previous example. It calls the statfs function multiple times,
-accepting a reference to an array of filenames as input, and returning
-a reference to an array of hashes containing the data for each of the
-filesystems.
-
-Return to the Mytest directory and add the following code to the end of
-Mytest.xs:
-
- SV *
- multi_statfs(paths)
- SV * paths
- INIT:
- AV * results;
- I32 numpaths = 0;
- int i, n;
- struct statfs buf;
-
- SvGETMAGIC(paths);
- if ((!SvROK(paths))
- || (SvTYPE(SvRV(paths)) != SVt_PVAV)
- || ((numpaths = av_len((AV *)SvRV(paths))) < 0))
- {
- XSRETURN_UNDEF;
- }
- results = (AV *)sv_2mortal((SV *)newAV());
- CODE:
- for (n = 0; n <= numpaths; n++) {
- HV * rh;
- STRLEN l;
- char * fn = SvPV(*av_fetch((AV *)SvRV(paths), n, 0), l);
-
- i = statfs(fn, &buf);
- if (i != 0) {
- av_push(results, newSVnv(errno));
- continue;
- }
-
- rh = (HV *)sv_2mortal((SV *)newHV());
-
- hv_store(rh, "f_bavail", 8, newSVnv(buf.f_bavail), 0);
- hv_store(rh, "f_bfree", 7, newSVnv(buf.f_bfree), 0);
- hv_store(rh, "f_blocks", 8, newSVnv(buf.f_blocks), 0);
- hv_store(rh, "f_bsize", 7, newSVnv(buf.f_bsize), 0);
- hv_store(rh, "f_ffree", 7, newSVnv(buf.f_ffree), 0);
- hv_store(rh, "f_files", 7, newSVnv(buf.f_files), 0);
- hv_store(rh, "f_type", 6, newSVnv(buf.f_type), 0);
-
- av_push(results, newRV((SV *)rh));
- }
- RETVAL = newRV((SV *)results);
- OUTPUT:
- RETVAL
-
-And add the following code to Mytest.t, while incrementing the "11"
-tests to "13":
-
- $results = Mytest::multi_statfs([ '/', '/blech' ]);
- ok( ref $results->[0] );
- ok( ! ref $results->[1] );
-
-=head2 New Things in this Example
-
-There are a number of new concepts introduced here, described below:
-
-=over 4
-
-=item *
-
-This function does not use a typemap. Instead, we declare it as accepting
-one SV* (scalar) parameter, and returning an SV* value, and we take care of
-populating these scalars within the code. Because we are only returning
-one value, we don't need a C<PPCODE:> directive - instead, we use C<CODE:>
-and C<OUTPUT:> directives.
-
-=item *
-
-When dealing with references, it is important to handle them with caution.
-The C<INIT:> block first calls SvGETMAGIC(paths), in case
-paths is a tied variable. Then it checks that C<SvROK> returns
-true, which indicates that paths is a valid reference. (Simply
-checking C<SvROK> won't trigger FETCH on a tied variable.) It
-then verifies that the object referenced by paths is an array, using C<SvRV>
-to dereference paths, and C<SvTYPE> to discover its type. As an added test,
-it checks that the array referenced by paths is non-empty, using the C<av_len>
-function (which returns -1 if the array is empty). The XSRETURN_UNDEF macro
-is used to abort the XSUB and return the undefined value whenever all three of
-these conditions are not met.
-
-=item *
-
-We manipulate several arrays in this XSUB. Note that an array is represented
-internally by an AV* pointer. The functions and macros for manipulating
-arrays are similar to the functions in Perl: C<av_len> returns the highest
-index in an AV*, much like $#array; C<av_fetch> fetches a single scalar value
-from an array, given its index; C<av_push> pushes a scalar value onto the
-end of the array, automatically extending the array as necessary.
-
-Specifically, we read pathnames one at a time from the input array, and
-store the results in an output array (results) in the same order. If
-statfs fails, the element pushed onto the return array is the value of
-errno after the failure. If statfs succeeds, though, the value pushed
-onto the return array is a reference to a hash containing some of the
-information in the statfs structure.
-
-As with the return stack, it would be possible (and a small performance win)
-to pre-extend the return array before pushing data into it, since we know
-how many elements we will return:
-
- av_extend(results, numpaths);
-
-=item *
-
-We are performing only one hash operation in this function, which is storing
-a new scalar under a key using C<hv_store>. A hash is represented by an HV*
-pointer. Like arrays, the functions for manipulating hashes from an XSUB
-mirror the functionality available from Perl. See L<perlguts> and L<perlapi>
-for details.
-
-=item *
-
-To create a reference, we use the C<newRV> function. Note that you can
-cast an AV* or an HV* to type SV* in this case (and many others). This
-allows you to take references to arrays, hashes and scalars with the same
-function. Conversely, the C<SvRV> function always returns an SV*, which may
-need to be cast to the appropriate type if it is something other than a
-scalar (check with C<SvTYPE>).
-
-=item *
-
-At this point, xsubpp is doing very little work - the differences between
-Mytest.xs and Mytest.c are minimal.
-
-=back
-
-=head2 EXAMPLE 7 (Coming Soon)
-
-XPUSH args AND set RETVAL AND assign return value to array
-
-=head2 EXAMPLE 8 (Coming Soon)
-
-Setting $!
-
-=head2 EXAMPLE 9 Passing open files to XSes
-
-You would think passing files to an XS is difficult, with all the
-typeglobs and stuff. Well, it isn't.
-
-Suppose that for some strange reason we need a wrapper around the
-standard C library function C<fputs()>. This is all we need:
-
- #define PERLIO_NOT_STDIO 0
- #include "EXTERN.h"
- #include "perl.h"
- #include "XSUB.h"
-
- #include <stdio.h>
-
- int
- fputs(s, stream)
- char * s
- FILE * stream
-
-The real work is done in the standard typemap.
-
-B<But> you loose all the fine stuff done by the perlio layers. This
-calls the stdio function C<fputs()>, which knows nothing about them.
-
-The standard typemap offers three variants of PerlIO *:
-C<InputStream> (T_IN), C<InOutStream> (T_INOUT) and C<OutputStream>
-(T_OUT). A bare C<PerlIO *> is considered a T_INOUT. If it matters
-in your code (see below for why it might) #define or typedef
-one of the specific names and use that as the argument or result
-type in your XS file.
-
-The standard typemap does not contain PerlIO * before perl 5.7,
-but it has the three stream variants. Using a PerlIO * directly
-is not backwards compatible unless you provide your own typemap.
-
-For streams coming I<from> perl the main difference is that
-C<OutputStream> will get the output PerlIO * - which may make
-a difference on a socket. Like in our example...
-
-For streams being handed I<to> perl a new file handle is created
-(i.e. a reference to a new glob) and associated with the PerlIO *
-provided. If the read/write state of the PerlIO * is not correct then you
-may get errors or warnings from when the file handle is used.
-So if you opened the PerlIO * as "w" it should really be an
-C<OutputStream> if open as "r" it should be an C<InputStream>.
-
-Now, suppose you want to use perlio layers in your XS. We'll use the
-perlio C<PerlIO_puts()> function as an example.
-
-In the C part of the XS file (above the first MODULE line) you
-have
-
- #define OutputStream PerlIO *
- or
- typedef PerlIO * OutputStream;
-
-
-And this is the XS code:
-
- int
- perlioputs(s, stream)
- char * s
- OutputStream stream
- CODE:
- RETVAL = PerlIO_puts(stream, s);
- OUTPUT:
- RETVAL
-
-We have to use a C<CODE> section because C<PerlIO_puts()> has the arguments
-reversed compared to C<fputs()>, and we want to keep the arguments the same.
-
-Wanting to explore this thoroughly, we want to use the stdio C<fputs()>
-on a PerlIO *. This means we have to ask the perlio system for a stdio
-C<FILE *>:
-
- int
- perliofputs(s, stream)
- char * s
- OutputStream stream
- PREINIT:
- FILE *fp = PerlIO_findFILE(stream);
- CODE:
- if (fp != (FILE*) 0) {
- RETVAL = fputs(s, fp);
- } else {
- RETVAL = -1;
- }
- OUTPUT:
- RETVAL
-
-Note: C<PerlIO_findFILE()> will search the layers for a stdio
-layer. If it can't find one, it will call C<PerlIO_exportFILE()> to
-generate a new stdio C<FILE>. Please only call C<PerlIO_exportFILE()> if
-you want a I<new> C<FILE>. It will generate one on each call and push a
-new stdio layer. So don't call it repeatedly on the same
-file. C<PerlIO_findFILE()> will retrieve the stdio layer once it has been
-generated by C<PerlIO_exportFILE()>.
-
-This applies to the perlio system only. For versions before 5.7,
-C<PerlIO_exportFILE()> is equivalent to C<PerlIO_findFILE()>.
-
-=head2 Troubleshooting these Examples
-
-As mentioned at the top of this document, if you are having problems with
-these example extensions, you might see if any of these help you.
-
-=over 4
-
-=item *
-
-In versions of 5.002 prior to the gamma version, the test script in Example
-1 will not function properly. You need to change the "use lib" line to
-read:
-
- use lib './blib';
-
-=item *
-
-In versions of 5.002 prior to version 5.002b1h, the test.pl file was not
-automatically created by h2xs. This means that you cannot say "make test"
-to run the test script. You will need to add the following line before the
-"use extension" statement:
-
- use lib './blib';
-
-=item *
-
-In versions 5.000 and 5.001, instead of using the above line, you will need
-to use the following line:
-
- BEGIN { unshift(@INC, "./blib") }
-
-=item *
-
-This document assumes that the executable named "perl" is Perl version 5.
-Some systems may have installed Perl version 5 as "perl5".
-
-=back
-
-=head1 See also
-
-For more information, consult L<perlguts>, L<perlapi>, L<perlxs>, L<perlmod>,
-and L<perlpod>.
-
-=head1 Author
-
-Jeff Okamoto <F<okamoto@corp.hp.com>>
-
-Reviewed and assisted by Dean Roehrich, Ilya Zakharevich, Andreas Koenig,
-and Tim Bunce.
-
-PerlIO material contributed by Lupe Christoph, with some clarification
-by Nick Ing-Simmons.
-
-Changes for h2xs as of Perl 5.8.x by Renee Baecker
-
-=head2 Last Changed
-
-2012-01-20
diff --git a/Master/tlpkg/tlperl/lib/pods/perlxstypemap.pod b/Master/tlpkg/tlperl/lib/pods/perlxstypemap.pod
deleted file mode 100644
index 67ddadefef7..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlxstypemap.pod
+++ /dev/null
@@ -1,699 +0,0 @@
-=head1 NAME
-
-perlxstypemap - Perl XS C/Perl type mapping
-
-=head1 DESCRIPTION
-
-The more you think about interfacing between two languages, the more
-you'll realize that the majority of programmer effort has to go into
-converting between the data structures that are native to either of
-the languages involved. This trumps other matter such as differing
-calling conventions because the problem space is so much greater.
-There are simply more ways to shove data into memory than there are
-ways to implement a function call.
-
-Perl XS' attempt at a solution to this is the concept of typemaps.
-At an abstract level, a Perl XS typemap is nothing but a recipe for
-converting from a certain Perl data structure to a certain C
-data structure and vice versa. Since there can be C types that
-are sufficiently similar to warrant converting with the same logic,
-XS typemaps are represented by a unique identifier, henceforth
-called an <XS type> in this document. You can then tell the XS
-compiler that multiple C types are to be mapped with the same
-XS typemap.
-
-In your XS code, when you define an argument with a C type or when
-you are using a C<CODE:> and an C<OUTPUT:> section together with a
-C return type of your XSUB, it'll be the typemapping mechanism that
-makes this easy.
-
-=head2 Anatomy of a typemap
-
-In more practical terms, the typemap is a collection of code
-fragments which are used by the B<xsubpp> compiler to map C function
-parameters and values to Perl values. The typemap file may consist
-of three sections labelled C<TYPEMAP>, C<INPUT>, and C<OUTPUT>.
-An unlabelled initial section is assumed to be a C<TYPEMAP> section.
-The INPUT section tells the compiler how to translate Perl values
-into variables of certain C types. The OUTPUT section tells the
-compiler how to translate the values from certain C types into values
-Perl can understand. The TYPEMAP section tells the compiler which
-of the INPUT and OUTPUT code fragments should be used to map a given
-C type to a Perl value. The section labels C<TYPEMAP>, C<INPUT>, or
-C<OUTPUT> must begin in the first column on a line by themselves,
-and must be in uppercase.
-
-Each type of section can appear an arbitrary number of times
-and does not have to appear at all. For example, a typemap may
-commonly lack C<INPUT> and C<OUTPUT> sections if all it needs to
-do is associate additional C types with core XS types like T_PTROBJ.
-Lines that start with a hash C<#> are considered comments and ignored
-in the C<TYPEMAP> section, but are considered significant in C<INPUT>
-and C<OUTPUT>. Blank lines are generally ignored.
-
-Traditionally, typemaps needed to be written to a separate file,
-conventionally called C<typemap> in a CPAN distribution. With
-ExtUtils::ParseXS (the XS compiler) version 3.12 or better which
-comes with perl 5.16, typemaps can also be embedded directly into
-XS code using a HERE-doc like syntax:
-
- TYPEMAP: <<HERE
- ...
- HERE
-
-where C<HERE> can be replaced by other identifiers like with normal
-Perl HERE-docs. All details below about the typemap textual format
-remain valid.
-
-The C<TYPEMAP> section should contain one pair of C type and
-XS type per line as follows. An example from the core typemap file:
-
- TYPEMAP
- # all variants of char* is handled by the T_PV typemap
- char * T_PV
- const char * T_PV
- unsigned char * T_PV
- ...
-
-The C<INPUT> and C<OUTPUT> sections have identical formats, that is,
-each unindented line starts a new in- or output map respectively.
-A new in- or output map must start with the name of the XS type to
-map on a line by itself, followed by the code that implements it
-indented on the following lines. Example:
-
- INPUT
- T_PV
- $var = ($type)SvPV_nolen($arg)
- T_PTR
- $var = INT2PTR($type,SvIV($arg))
-
-We'll get to the meaning of those Perlish-looking variables in a
-little bit.
-
-Finally, here's an example of the full typemap file for mapping C
-strings of the C<char *> type to Perl scalars/strings:
-
- TYPEMAP
- char * T_PV
-
- INPUT
- T_PV
- $var = ($type)SvPV_nolen($arg)
-
- OUTPUT
- T_PV
- sv_setpv((SV*)$arg, $var);
-
-Here's a more complicated example: suppose that you wanted
-C<struct netconfig> to be blessed into the class C<Net::Config>.
-One way to do this is to use underscores (_) to separate package
-names, as follows:
-
- typedef struct netconfig * Net_Config;
-
-And then provide a typemap entry C<T_PTROBJ_SPECIAL> that maps
-underscores to double-colons (::), and declare C<Net_Config> to be of
-that type:
-
- TYPEMAP
- Net_Config T_PTROBJ_SPECIAL
-
- INPUT
- T_PTROBJ_SPECIAL
- if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")){
- IV tmp = SvIV((SV*)SvRV($arg));
- $var = INT2PTR($type, tmp);
- }
- else
- croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")
-
- OUTPUT
- T_PTROBJ_SPECIAL
- sv_setref_pv($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\",
- (void*)$var);
-
-The INPUT and OUTPUT sections substitute underscores for double-colons
-on the fly, giving the desired effect. This example demonstrates some
-of the power and versatility of the typemap facility.
-
-The C<INT2PTR> macro (defined in perl.h) casts an integer to a pointer
-of a given type, taking care of the possible different size of integers
-and pointers. There are also C<PTR2IV>, C<PTR2UV>, C<PTR2NV> macros,
-to map the other way, which may be useful in OUTPUT sections.
-
-=head2 The Role of the typemap File in Your Distribution
-
-The default typemap in the F<lib/ExtUtils> directory of the Perl source
-contains many useful types which can be used by Perl extensions. Some
-extensions define additional typemaps which they keep in their own directory.
-These additional typemaps may reference INPUT and OUTPUT maps in the main
-typemap. The B<xsubpp> compiler will allow the extension's own typemap to
-override any mappings which are in the default typemap. Instead of using
-an additional F<typemap> file, typemaps may be embedded verbatim in XS
-with a heredoc-like syntax. See the documentation on the C<TYPEMAP:> XS
-keyword.
-
-For CPAN distributions, you can assume that the XS types defined by
-the perl core are already available. Additionally, the core typemap
-has default XS types for a large number of C types. For example, if
-you simply return a C<char *> from your XSUB, the core typemap will
-have this C type associated with the T_PV XS type. That means your
-C string will be copied into the PV (pointer value) slot of a new scalar
-that will be returned from your XSUB to to Perl.
-
-If you're developing a CPAN distribution using XS, you may add your own
-file called F<typemap> to the distribution. That file may contain
-typemaps that either map types that are specific to your code or that
-override the core typemap file's mappings for common C types.
-
-=head2 Sharing typemaps Between CPAN Distributions
-
-Starting with ExtUtils::ParseXS version 3.13_01 (comes with perl 5.16
-and better), it is rather easy to share typemap code between multiple
-CPAN distributions. The general idea is to share it as a module that
-offers a certain API and have the dependent modules declare that as a
-built-time requirement and import the typemap into the XS. An example
-of such a typemap-sharing module on CPAN is
-C<ExtUtils::Typemaps::Basic>. Two steps to getting that module's
-typemaps available in your code:
-
-=over 4
-
-=item *
-
-Declare C<ExtUtils::Typemaps::Basic> as a build-time dependency
-in C<Makefile.PL> (use C<BUILD_REQUIRES>), or in your C<Build.PL>
-(use C<build_requires>).
-
-=item *
-
-Include the following line in the XS section of your XS file:
-(don't break the line)
-
- INCLUDE_COMMAND: $^X -MExtUtils::Typemaps::Cmd
- -e "print embeddable_typemap(q{Basic})"
-
-=back
-
-=head2 Writing typemap Entries
-
-Each INPUT or OUTPUT typemap entry is a double-quoted Perl string that
-will be evaluated in the presence of certain variables to get the
-final C code for mapping a certain C type.
-
-This means that you can embed Perl code in your typemap (C) code using
-constructs such as
-C<${ perl code that evaluates to scalar reference here }>. A common
-use case is to generate error messages that refer to the true function
-name even when using the ALIAS XS feature:
-
- ${ $ALIAS ? \q[GvNAME(CvGV(cv))] : \qq[\"$pname\"] }
-
-For many typemap examples, refer to the core typemap file that can be
-found in the perl source tree at F<lib/ExtUtils/typemap>.
-
-The Perl variables that are available for interpolation into typemaps
-are the following:
-
-=over 4
-
-=item *
-
-I<$var> - the name of the input or output variable, eg. RETVAL for
-return values.
-
-=item *
-
-I<$type> - the raw C type of the parameter, any C<:> replaced with
-C<_>.
-
-=item *
-
-I<$ntype> - the supplied type with C<*> replaced with C<Ptr>.
-e.g. for a type of C<Foo::Bar>, I<$ntype> is C<Foo::Bar>
-
-=item *
-
-I<$arg> - the stack entry, that the parameter is input from or output
-to, e.g. C<ST(0)>
-
-=item *
-
-I<$argoff> - the argument stack offset of the argument. ie. 0 for the
-first argument, etc.
-
-=item *
-
-I<$pname> - the full name of the XSUB, with including the C<PACKAGE>
-name, with any C<PREFIX> stripped. This is the non-ALIAS name.
-
-=item *
-
-I<$Package> - the package specified by the most recent C<PACKAGE>
-keyword.
-
-=item *
-
-I<$ALIAS> - non-zero if the current XSUB has any aliases declared with
-C<ALIAS>.
-
-=back
-
-=head2 Full Listing of Core Typemaps
-
-Each C type is represented by an entry in the typemap file that
-is responsible for converting perl variables (SV, AV, HV, CV, etc.)
-to and from that type. The following sections list all XS types
-that come with perl by default.
-
-=over 4
-
-=item T_SV
-
-This simply passes the C representation of the Perl variable (an SV*)
-in and out of the XS layer. This can be used if the C code wants
-to deal directly with the Perl variable.
-
-=item T_SVREF
-
-Used to pass in and return a reference to an SV.
-
-Note that this typemap does not decrement the reference count
-when returning the reference to an SV*.
-See also: T_SVREF_REFCOUNT_FIXED
-
-=item T_SVREF_FIXED
-
-Used to pass in and return a reference to an SV.
-This is a fixed
-variant of T_SVREF that decrements the refcount appropriately
-when returning a reference to an SV*. Introduced in perl 5.15.4.
-
-=item T_AVREF
-
-From the perl level this is a reference to a perl array.
-From the C level this is a pointer to an AV.
-
-Note that this typemap does not decrement the reference count
-when returning an AV*. See also: T_AVREF_REFCOUNT_FIXED
-
-=item T_AVREF_REFCOUNT_FIXED
-
-From the perl level this is a reference to a perl array.
-From the C level this is a pointer to an AV. This is a fixed
-variant of T_AVREF that decrements the refcount appropriately
-when returning an AV*. Introduced in perl 5.15.4.
-
-=item T_HVREF
-
-From the perl level this is a reference to a perl hash.
-From the C level this is a pointer to an HV.
-
-Note that this typemap does not decrement the reference count
-when returning an HV*. See also: T_HVREF_REFCOUNT_FIXED
-
-=item T_HVREF_REFCOUNT_FIXED
-
-From the perl level this is a reference to a perl hash.
-From the C level this is a pointer to an HV. This is a fixed
-variant of T_HVREF that decrements the refcount appropriately
-when returning an HV*. Introduced in perl 5.15.4.
-
-=item T_CVREF
-
-From the perl level this is a reference to a perl subroutine
-(e.g. $sub = sub { 1 };). From the C level this is a pointer
-to a CV.
-
-Note that this typemap does not decrement the reference count
-when returning an HV*. See also: T_HVREF_REFCOUNT_FIXED
-
-=item T_CVREF_REFCOUNT_FIXED
-
-From the perl level this is a reference to a perl subroutine
-(e.g. $sub = sub { 1 };). From the C level this is a pointer
-to a CV.
-
-This is a fixed
-variant of T_HVREF that decrements the refcount appropriately
-when returning an HV*. Introduced in perl 5.15.4.
-
-=item T_SYSRET
-
-The T_SYSRET typemap is used to process return values from system calls.
-It is only meaningful when passing values from C to perl (there is
-no concept of passing a system return value from Perl to C).
-
-System calls return -1 on error (setting ERRNO with the reason)
-and (usually) 0 on success. If the return value is -1 this typemap
-returns C<undef>. If the return value is not -1, this typemap
-translates a 0 (perl false) to "0 but true" (which
-is perl true) or returns the value itself, to indicate that the
-command succeeded.
-
-The L<POSIX|POSIX> module makes extensive use of this type.
-
-=item T_UV
-
-An unsigned integer.
-
-=item T_IV
-
-A signed integer. This is cast to the required integer type when
-passed to C and converted to an IV when passed back to Perl.
-
-=item T_INT
-
-A signed integer. This typemap converts the Perl value to a native
-integer type (the C<int> type on the current platform). When returning
-the value to perl it is processed in the same way as for T_IV.
-
-Its behaviour is identical to using an C<int> type in XS with T_IV.
-
-=item T_ENUM
-
-An enum value. Used to transfer an enum component
-from C. There is no reason to pass an enum value to C since
-it is stored as an IV inside perl.
-
-=item T_BOOL
-
-A boolean type. This can be used to pass true and false values to and
-from C.
-
-=item T_U_INT
-
-This is for unsigned integers. It is equivalent to using T_UV
-but explicitly casts the variable to type C<unsigned int>.
-The default type for C<unsigned int> is T_UV.
-
-=item T_SHORT
-
-Short integers. This is equivalent to T_IV but explicitly casts
-the return to type C<short>. The default typemap for C<short>
-is T_IV.
-
-=item T_U_SHORT
-
-Unsigned short integers. This is equivalent to T_UV but explicitly
-casts the return to type C<unsigned short>. The default typemap for
-C<unsigned short> is T_UV.
-
-T_U_SHORT is used for type C<U16> in the standard typemap.
-
-=item T_LONG
-
-Long integers. This is equivalent to T_IV but explicitly casts
-the return to type C<long>. The default typemap for C<long>
-is T_IV.
-
-=item T_U_LONG
-
-Unsigned long integers. This is equivalent to T_UV but explicitly
-casts the return to type C<unsigned long>. The default typemap for
-C<unsigned long> is T_UV.
-
-T_U_LONG is used for type C<U32> in the standard typemap.
-
-=item T_CHAR
-
-Single 8-bit characters.
-
-=item T_U_CHAR
-
-An unsigned byte.
-
-=item T_FLOAT
-
-A floating point number. This typemap guarantees to return a variable
-cast to a C<float>.
-
-=item T_NV
-
-A Perl floating point number. Similar to T_IV and T_UV in that the
-return type is cast to the requested numeric type rather than
-to a specific type.
-
-=item T_DOUBLE
-
-A double precision floating point number. This typemap guarantees to
-return a variable cast to a C<double>.
-
-=item T_PV
-
-A string (char *).
-
-=item T_PTR
-
-A memory address (pointer). Typically associated with a C<void *>
-type.
-
-=item T_PTRREF
-
-Similar to T_PTR except that the pointer is stored in a scalar and the
-reference to that scalar is returned to the caller. This can be used
-to hide the actual pointer value from the programmer since it is usually
-not required directly from within perl.
-
-The typemap checks that a scalar reference is passed from perl to XS.
-
-=item T_PTROBJ
-
-Similar to T_PTRREF except that the reference is blessed into a class.
-This allows the pointer to be used as an object. Most commonly used to
-deal with C structs. The typemap checks that the perl object passed
-into the XS routine is of the correct class (or part of a subclass).
-
-The pointer is blessed into a class that is derived from the name
-of type of the pointer but with all '*' in the name replaced with
-'Ptr'.
-
-=item T_REF_IV_REF
-
-NOT YET
-
-=item T_REF_IV_PTR
-
-Similar to T_PTROBJ in that the pointer is blessed into a scalar object.
-The difference is that when the object is passed back into XS it must be
-of the correct type (inheritance is not supported).
-
-The pointer is blessed into a class that is derived from the name
-of type of the pointer but with all '*' in the name replaced with
-'Ptr'.
-
-=item T_PTRDESC
-
-NOT YET
-
-=item T_REFREF
-
-Similar to T_PTRREF, except the pointer stored in the referenced scalar
-is dereferenced and copied to the output variable. This means that
-T_REFREF is to T_PTRREF as T_OPAQUE is to T_OPAQUEPTR. All clear?
-
-Only the INPUT part of this is implemented (Perl to XSUB) and there
-are no known users in core or on CPAN.
-
-=item T_REFOBJ
-
-NOT YET
-
-=item T_OPAQUEPTR
-
-This can be used to store bytes in the string component of the
-SV. Here the representation of the data is irrelevant to perl and the
-bytes themselves are just stored in the SV. It is assumed that the C
-variable is a pointer (the bytes are copied from that memory
-location). If the pointer is pointing to something that is
-represented by 8 bytes then those 8 bytes are stored in the SV (and
-length() will report a value of 8). This entry is similar to T_OPAQUE.
-
-In principle the unpack() command can be used to convert the bytes
-back to a number (if the underlying type is known to be a number).
-
-This entry can be used to store a C structure (the number
-of bytes to be copied is calculated using the C C<sizeof> function)
-and can be used as an alternative to T_PTRREF without having to worry
-about a memory leak (since Perl will clean up the SV).
-
-=item T_OPAQUE
-
-This can be used to store data from non-pointer types in the string
-part of an SV. It is similar to T_OPAQUEPTR except that the
-typemap retrieves the pointer directly rather than assuming it
-is being supplied. For example, if an integer is imported into
-Perl using T_OPAQUE rather than T_IV the underlying bytes representing
-the integer will be stored in the SV but the actual integer value will
-not be available. i.e. The data is opaque to perl.
-
-The data may be retrieved using the C<unpack> function if the
-underlying type of the byte stream is known.
-
-T_OPAQUE supports input and output of simple types.
-T_OPAQUEPTR can be used to pass these bytes back into C if a pointer
-is acceptable.
-
-=item Implicit array
-
-xsubpp supports a special syntax for returning
-packed C arrays to perl. If the XS return type is given as
-
- array(type, nelem)
-
-xsubpp will copy the contents of C<nelem * sizeof(type)> bytes from
-RETVAL to an SV and push it onto the stack. This is only really useful
-if the number of items to be returned is known at compile time and you
-don't mind having a string of bytes in your SV. Use T_ARRAY to push a
-variable number of arguments onto the return stack (they won't be
-packed as a single string though).
-
-This is similar to using T_OPAQUEPTR but can be used to process more
-than one element.
-
-=item T_PACKED
-
-Calls user-supplied functions for conversion. For C<OUTPUT>
-(XSUB to Perl), a function named C<XS_pack_$ntype> is called
-with the output Perl scalar and the C variable to convert from.
-C<$ntype> is the normalized C type that is to be mapped to
-Perl. Normalized means that all C<*> are replaced by the
-string C<Ptr>. The return value of the function is ignored.
-
-Conversely for C<INPUT> (Perl to XSUB) mapping, the
-function named C<XS_unpack_$ntype> is called with the input Perl
-scalar as argument and the return value is cast to the mapped
-C type and assigned to the output C variable.
-
-An example conversion function for a typemapped struct
-C<foo_t *> might be:
-
- static void
- XS_pack_foo_tPtr(SV *out, foo_t *in)
- {
- dTHX; /* alas, signature does not include pTHX_ */
- HV* hash = newHV();
- hv_stores(hash, "int_member", newSViv(in->int_member));
- hv_stores(hash, "float_member", newSVnv(in->float_member));
- /* ... */
-
- /* mortalize as thy stack is not refcounted */
- sv_setsv(out, sv_2mortal(newRV_noinc((SV*)hash)));
- }
-
-The conversion from Perl to C is left as an exercise to the reader,
-but the prototype would be:
-
- static foo_t *
- XS_unpack_foo_tPtr(SV *in);
-
-Instead of an actual C function that has to fetch the thread context
-using C<dTHX>, you can define macros of the same name and avoid the
-overhead. Also, keep in mind to possibly free the memory allocated by
-C<XS_unpack_foo_tPtr>.
-
-=item T_PACKEDARRAY
-
-T_PACKEDARRAY is similar to T_PACKED. In fact, the C<INPUT> (Perl
-to XSUB) typemap is indentical, but the C<OUTPUT> typemap passes
-an additional argument to the C<XS_pack_$ntype> function. This
-third parameter indicates the number of elements in the output
-so that the function can handle C arrays sanely. The variable
-needs to be declared by the user and must have the name
-C<count_$ntype> where C<$ntype> is the normalized C type name
-as explained above. The signature of the function would be for
-the example above and C<foo_t **>:
-
- static void
- XS_pack_foo_tPtrPtr(SV *out, foo_t *in, UV count_foo_tPtrPtr);
-
-The type of the third parameter is arbitrary as far as the typemap
-is concerned. It just has to be in line with the declared variable.
-
-Of course, unless you know the number of elements in the
-C<sometype **> C array, within your XSUB, the return value from
-C<foo_t ** XS_unpack_foo_tPtrPtr(...)> will be hard to decypher.
-Since the details are all up to the XS author (the typemap user),
-there are several solutions, none of which particularly elegant.
-The most commonly seen solution has been to allocate memory for
-N+1 pointers and assign C<NULL> to the (N+1)th to facilitate
-iteration.
-
-Alternatively, using a customized typemap for your purposes in
-the first place is probably preferrable.
-
-=item T_DATAUNIT
-
-NOT YET
-
-=item T_CALLBACK
-
-NOT YET
-
-=item T_ARRAY
-
-This is used to convert the perl argument list to a C array
-and for pushing the contents of a C array onto the perl
-argument stack.
-
-The usual calling signature is
-
- @out = array_func( @in );
-
-Any number of arguments can occur in the list before the array but
-the input and output arrays must be the last elements in the list.
-
-When used to pass a perl list to C the XS writer must provide a
-function (named after the array type but with 'Ptr' substituted for
-'*') to allocate the memory required to hold the list. A pointer
-should be returned. It is up to the XS writer to free the memory on
-exit from the function. The variable C<ix_$var> is set to the number
-of elements in the new array.
-
-When returning a C array to Perl the XS writer must provide an integer
-variable called C<size_$var> containing the number of elements in the
-array. This is used to determine how many elements should be pushed
-onto the return argument stack. This is not required on input since
-Perl knows how many arguments are on the stack when the routine is
-called. Ordinarily this variable would be called C<size_RETVAL>.
-
-Additionally, the type of each element is determined from the type of
-the array. If the array uses type C<intArray *> xsubpp will
-automatically work out that it contains variables of type C<int> and
-use that typemap entry to perform the copy of each element. All
-pointer '*' and 'Array' tags are removed from the name to determine
-the subtype.
-
-=item T_STDIO
-
-This is used for passing perl filehandles to and from C using
-C<FILE *> structures.
-
-=item T_INOUT
-
-This is used for passing perl filehandles to and from C using
-C<PerlIO *> structures. The file handle can used for reading and
-writing. This corresponds to the C<+E<lt>> mode, see also T_IN
-and T_OUT.
-
-See L<perliol> for more information on the Perl IO abstraction
-layer. Perl must have been built with C<-Duseperlio>.
-
-There is no check to assert that the filehandle passed from Perl
-to C was created with the right C<open()> mode.
-
-Hint: The L<perlxstut> tutorial covers the T_INOUT, T_IN, and T_OUT
-XS types nicely.
-
-=item T_IN
-
-Same as T_INOUT, but the filehandle that is returned from C to Perl
-can only be used for reading (mode C<E<lt>>).
-
-=item T_OUT
-
-Same as T_INOUT, but the filehandle that is returned from C to Perl
-is set to use the open mode C<+E<gt>>.
-
-=back
-
diff --git a/Master/tlpkg/tlperl/lib/unicore/CaseFolding.txt b/Master/tlpkg/tlperl/lib/unicore/CaseFolding.txt
deleted file mode 100644
index 0d9a4090cde..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/CaseFolding.txt
+++ /dev/null
@@ -1,1224 +0,0 @@
-# CaseFolding-6.1.0.txt
-# Date: 2011-07-25, 21:21:56 GMT [MD]
-#
-# Unicode Character Database
-# Copyright (c) 1991-2011 Unicode, Inc.
-# For terms of use, see http://www.unicode.org/terms_of_use.html
-# For documentation, see http://www.unicode.org/reports/tr44/
-#
-# Case Folding Properties
-#
-# This file is a supplement to the UnicodeData file.
-# It provides a case folding mapping generated from the Unicode Character Database.
-# If all characters are mapped according to the full mapping below, then
-# case differences (according to UnicodeData.txt and SpecialCasing.txt)
-# are eliminated.
-#
-# The data supports both implementations that require simple case foldings
-# (where string lengths don't change), and implementations that allow full case folding
-# (where string lengths may grow). Note that where they can be supported, the
-# full case foldings are superior: for example, they allow "MASSE" and "Maße" to match.
-#
-# All code points not listed in this file map to themselves.
-#
-# NOTE: case folding does not preserve normalization formats!
-#
-# For information on case folding, including how to have case folding
-# preserve normalization formats, see Section 3.13 Default Case Algorithms in
-# The Unicode Standard, Version 5.0.
-#
-# ================================================================================
-# Format
-# ================================================================================
-# The entries in this file are in the following machine-readable format:
-#
-# <code>; <status>; <mapping>; # <name>
-#
-# The status field is:
-# C: common case folding, common mappings shared by both simple and full mappings.
-# F: full case folding, mappings that cause strings to grow in length. Multiple characters are separated by spaces.
-# S: simple case folding, mappings to single characters where different from F.
-# T: special case for uppercase I and dotted uppercase I
-# - For non-Turkic languages, this mapping is normally not used.
-# - For Turkic languages (tr, az), this mapping can be used instead of the normal mapping for these characters.
-# Note that the Turkic mappings do not maintain canonical equivalence without additional processing.
-# See the discussions of case mapping in the Unicode Standard for more information.
-#
-# Usage:
-# A. To do a simple case folding, use the mappings with status C + S.
-# B. To do a full case folding, use the mappings with status C + F.
-#
-# The mappings with status T can be used or omitted depending on the desired case-folding
-# behavior. (The default option is to exclude them.)
-#
-# =================================================================
-
-# Property: Case_Folding
-
-# All code points not explicitly listed for Case_Folding
-# have the value C for the status field, and the code point itself for the mapping field.
-
-# @missing: 0000..10FFFF; C; <code point>
-
-# =================================================================
-0041; C; 0061; # LATIN CAPITAL LETTER A
-0042; C; 0062; # LATIN CAPITAL LETTER B
-0043; C; 0063; # LATIN CAPITAL LETTER C
-0044; C; 0064; # LATIN CAPITAL LETTER D
-0045; C; 0065; # LATIN CAPITAL LETTER E
-0046; C; 0066; # LATIN CAPITAL LETTER F
-0047; C; 0067; # LATIN CAPITAL LETTER G
-0048; C; 0068; # LATIN CAPITAL LETTER H
-0049; C; 0069; # LATIN CAPITAL LETTER I
-0049; T; 0131; # LATIN CAPITAL LETTER I
-004A; C; 006A; # LATIN CAPITAL LETTER J
-004B; C; 006B; # LATIN CAPITAL LETTER K
-004C; C; 006C; # LATIN CAPITAL LETTER L
-004D; C; 006D; # LATIN CAPITAL LETTER M
-004E; C; 006E; # LATIN CAPITAL LETTER N
-004F; C; 006F; # LATIN CAPITAL LETTER O
-0050; C; 0070; # LATIN CAPITAL LETTER P
-0051; C; 0071; # LATIN CAPITAL LETTER Q
-0052; C; 0072; # LATIN CAPITAL LETTER R
-0053; C; 0073; # LATIN CAPITAL LETTER S
-0054; C; 0074; # LATIN CAPITAL LETTER T
-0055; C; 0075; # LATIN CAPITAL LETTER U
-0056; C; 0076; # LATIN CAPITAL LETTER V
-0057; C; 0077; # LATIN CAPITAL LETTER W
-0058; C; 0078; # LATIN CAPITAL LETTER X
-0059; C; 0079; # LATIN CAPITAL LETTER Y
-005A; C; 007A; # LATIN CAPITAL LETTER Z
-00B5; C; 03BC; # MICRO SIGN
-00C0; C; 00E0; # LATIN CAPITAL LETTER A WITH GRAVE
-00C1; C; 00E1; # LATIN CAPITAL LETTER A WITH ACUTE
-00C2; C; 00E2; # LATIN CAPITAL LETTER A WITH CIRCUMFLEX
-00C3; C; 00E3; # LATIN CAPITAL LETTER A WITH TILDE
-00C4; C; 00E4; # LATIN CAPITAL LETTER A WITH DIAERESIS
-00C5; C; 00E5; # LATIN CAPITAL LETTER A WITH RING ABOVE
-00C6; C; 00E6; # LATIN CAPITAL LETTER AE
-00C7; C; 00E7; # LATIN CAPITAL LETTER C WITH CEDILLA
-00C8; C; 00E8; # LATIN CAPITAL LETTER E WITH GRAVE
-00C9; C; 00E9; # LATIN CAPITAL LETTER E WITH ACUTE
-00CA; C; 00EA; # LATIN CAPITAL LETTER E WITH CIRCUMFLEX
-00CB; C; 00EB; # LATIN CAPITAL LETTER E WITH DIAERESIS
-00CC; C; 00EC; # LATIN CAPITAL LETTER I WITH GRAVE
-00CD; C; 00ED; # LATIN CAPITAL LETTER I WITH ACUTE
-00CE; C; 00EE; # LATIN CAPITAL LETTER I WITH CIRCUMFLEX
-00CF; C; 00EF; # LATIN CAPITAL LETTER I WITH DIAERESIS
-00D0; C; 00F0; # LATIN CAPITAL LETTER ETH
-00D1; C; 00F1; # LATIN CAPITAL LETTER N WITH TILDE
-00D2; C; 00F2; # LATIN CAPITAL LETTER O WITH GRAVE
-00D3; C; 00F3; # LATIN CAPITAL LETTER O WITH ACUTE
-00D4; C; 00F4; # LATIN CAPITAL LETTER O WITH CIRCUMFLEX
-00D5; C; 00F5; # LATIN CAPITAL LETTER O WITH TILDE
-00D6; C; 00F6; # LATIN CAPITAL LETTER O WITH DIAERESIS
-00D8; C; 00F8; # LATIN CAPITAL LETTER O WITH STROKE
-00D9; C; 00F9; # LATIN CAPITAL LETTER U WITH GRAVE
-00DA; C; 00FA; # LATIN CAPITAL LETTER U WITH ACUTE
-00DB; C; 00FB; # LATIN CAPITAL LETTER U WITH CIRCUMFLEX
-00DC; C; 00FC; # LATIN CAPITAL LETTER U WITH DIAERESIS
-00DD; C; 00FD; # LATIN CAPITAL LETTER Y WITH ACUTE
-00DE; C; 00FE; # LATIN CAPITAL LETTER THORN
-00DF; F; 0073 0073; # LATIN SMALL LETTER SHARP S
-0100; C; 0101; # LATIN CAPITAL LETTER A WITH MACRON
-0102; C; 0103; # LATIN CAPITAL LETTER A WITH BREVE
-0104; C; 0105; # LATIN CAPITAL LETTER A WITH OGONEK
-0106; C; 0107; # LATIN CAPITAL LETTER C WITH ACUTE
-0108; C; 0109; # LATIN CAPITAL LETTER C WITH CIRCUMFLEX
-010A; C; 010B; # LATIN CAPITAL LETTER C WITH DOT ABOVE
-010C; C; 010D; # LATIN CAPITAL LETTER C WITH CARON
-010E; C; 010F; # LATIN CAPITAL LETTER D WITH CARON
-0110; C; 0111; # LATIN CAPITAL LETTER D WITH STROKE
-0112; C; 0113; # LATIN CAPITAL LETTER E WITH MACRON
-0114; C; 0115; # LATIN CAPITAL LETTER E WITH BREVE
-0116; C; 0117; # LATIN CAPITAL LETTER E WITH DOT ABOVE
-0118; C; 0119; # LATIN CAPITAL LETTER E WITH OGONEK
-011A; C; 011B; # LATIN CAPITAL LETTER E WITH CARON
-011C; C; 011D; # LATIN CAPITAL LETTER G WITH CIRCUMFLEX
-011E; C; 011F; # LATIN CAPITAL LETTER G WITH BREVE
-0120; C; 0121; # LATIN CAPITAL LETTER G WITH DOT ABOVE
-0122; C; 0123; # LATIN CAPITAL LETTER G WITH CEDILLA
-0124; C; 0125; # LATIN CAPITAL LETTER H WITH CIRCUMFLEX
-0126; C; 0127; # LATIN CAPITAL LETTER H WITH STROKE
-0128; C; 0129; # LATIN CAPITAL LETTER I WITH TILDE
-012A; C; 012B; # LATIN CAPITAL LETTER I WITH MACRON
-012C; C; 012D; # LATIN CAPITAL LETTER I WITH BREVE
-012E; C; 012F; # LATIN CAPITAL LETTER I WITH OGONEK
-0130; F; 0069 0307; # LATIN CAPITAL LETTER I WITH DOT ABOVE
-0130; T; 0069; # LATIN CAPITAL LETTER I WITH DOT ABOVE
-0132; C; 0133; # LATIN CAPITAL LIGATURE IJ
-0134; C; 0135; # LATIN CAPITAL LETTER J WITH CIRCUMFLEX
-0136; C; 0137; # LATIN CAPITAL LETTER K WITH CEDILLA
-0139; C; 013A; # LATIN CAPITAL LETTER L WITH ACUTE
-013B; C; 013C; # LATIN CAPITAL LETTER L WITH CEDILLA
-013D; C; 013E; # LATIN CAPITAL LETTER L WITH CARON
-013F; C; 0140; # LATIN CAPITAL LETTER L WITH MIDDLE DOT
-0141; C; 0142; # LATIN CAPITAL LETTER L WITH STROKE
-0143; C; 0144; # LATIN CAPITAL LETTER N WITH ACUTE
-0145; C; 0146; # LATIN CAPITAL LETTER N WITH CEDILLA
-0147; C; 0148; # LATIN CAPITAL LETTER N WITH CARON
-0149; F; 02BC 006E; # LATIN SMALL LETTER N PRECEDED BY APOSTROPHE
-014A; C; 014B; # LATIN CAPITAL LETTER ENG
-014C; C; 014D; # LATIN CAPITAL LETTER O WITH MACRON
-014E; C; 014F; # LATIN CAPITAL LETTER O WITH BREVE
-0150; C; 0151; # LATIN CAPITAL LETTER O WITH DOUBLE ACUTE
-0152; C; 0153; # LATIN CAPITAL LIGATURE OE
-0154; C; 0155; # LATIN CAPITAL LETTER R WITH ACUTE
-0156; C; 0157; # LATIN CAPITAL LETTER R WITH CEDILLA
-0158; C; 0159; # LATIN CAPITAL LETTER R WITH CARON
-015A; C; 015B; # LATIN CAPITAL LETTER S WITH ACUTE
-015C; C; 015D; # LATIN CAPITAL LETTER S WITH CIRCUMFLEX
-015E; C; 015F; # LATIN CAPITAL LETTER S WITH CEDILLA
-0160; C; 0161; # LATIN CAPITAL LETTER S WITH CARON
-0162; C; 0163; # LATIN CAPITAL LETTER T WITH CEDILLA
-0164; C; 0165; # LATIN CAPITAL LETTER T WITH CARON
-0166; C; 0167; # LATIN CAPITAL LETTER T WITH STROKE
-0168; C; 0169; # LATIN CAPITAL LETTER U WITH TILDE
-016A; C; 016B; # LATIN CAPITAL LETTER U WITH MACRON
-016C; C; 016D; # LATIN CAPITAL LETTER U WITH BREVE
-016E; C; 016F; # LATIN CAPITAL LETTER U WITH RING ABOVE
-0170; C; 0171; # LATIN CAPITAL LETTER U WITH DOUBLE ACUTE
-0172; C; 0173; # LATIN CAPITAL LETTER U WITH OGONEK
-0174; C; 0175; # LATIN CAPITAL LETTER W WITH CIRCUMFLEX
-0176; C; 0177; # LATIN CAPITAL LETTER Y WITH CIRCUMFLEX
-0178; C; 00FF; # LATIN CAPITAL LETTER Y WITH DIAERESIS
-0179; C; 017A; # LATIN CAPITAL LETTER Z WITH ACUTE
-017B; C; 017C; # LATIN CAPITAL LETTER Z WITH DOT ABOVE
-017D; C; 017E; # LATIN CAPITAL LETTER Z WITH CARON
-017F; C; 0073; # LATIN SMALL LETTER LONG S
-0181; C; 0253; # LATIN CAPITAL LETTER B WITH HOOK
-0182; C; 0183; # LATIN CAPITAL LETTER B WITH TOPBAR
-0184; C; 0185; # LATIN CAPITAL LETTER TONE SIX
-0186; C; 0254; # LATIN CAPITAL LETTER OPEN O
-0187; C; 0188; # LATIN CAPITAL LETTER C WITH HOOK
-0189; C; 0256; # LATIN CAPITAL LETTER AFRICAN D
-018A; C; 0257; # LATIN CAPITAL LETTER D WITH HOOK
-018B; C; 018C; # LATIN CAPITAL LETTER D WITH TOPBAR
-018E; C; 01DD; # LATIN CAPITAL LETTER REVERSED E
-018F; C; 0259; # LATIN CAPITAL LETTER SCHWA
-0190; C; 025B; # LATIN CAPITAL LETTER OPEN E
-0191; C; 0192; # LATIN CAPITAL LETTER F WITH HOOK
-0193; C; 0260; # LATIN CAPITAL LETTER G WITH HOOK
-0194; C; 0263; # LATIN CAPITAL LETTER GAMMA
-0196; C; 0269; # LATIN CAPITAL LETTER IOTA
-0197; C; 0268; # LATIN CAPITAL LETTER I WITH STROKE
-0198; C; 0199; # LATIN CAPITAL LETTER K WITH HOOK
-019C; C; 026F; # LATIN CAPITAL LETTER TURNED M
-019D; C; 0272; # LATIN CAPITAL LETTER N WITH LEFT HOOK
-019F; C; 0275; # LATIN CAPITAL LETTER O WITH MIDDLE TILDE
-01A0; C; 01A1; # LATIN CAPITAL LETTER O WITH HORN
-01A2; C; 01A3; # LATIN CAPITAL LETTER OI
-01A4; C; 01A5; # LATIN CAPITAL LETTER P WITH HOOK
-01A6; C; 0280; # LATIN LETTER YR
-01A7; C; 01A8; # LATIN CAPITAL LETTER TONE TWO
-01A9; C; 0283; # LATIN CAPITAL LETTER ESH
-01AC; C; 01AD; # LATIN CAPITAL LETTER T WITH HOOK
-01AE; C; 0288; # LATIN CAPITAL LETTER T WITH RETROFLEX HOOK
-01AF; C; 01B0; # LATIN CAPITAL LETTER U WITH HORN
-01B1; C; 028A; # LATIN CAPITAL LETTER UPSILON
-01B2; C; 028B; # LATIN CAPITAL LETTER V WITH HOOK
-01B3; C; 01B4; # LATIN CAPITAL LETTER Y WITH HOOK
-01B5; C; 01B6; # LATIN CAPITAL LETTER Z WITH STROKE
-01B7; C; 0292; # LATIN CAPITAL LETTER EZH
-01B8; C; 01B9; # LATIN CAPITAL LETTER EZH REVERSED
-01BC; C; 01BD; # LATIN CAPITAL LETTER TONE FIVE
-01C4; C; 01C6; # LATIN CAPITAL LETTER DZ WITH CARON
-01C5; C; 01C6; # LATIN CAPITAL LETTER D WITH SMALL LETTER Z WITH CARON
-01C7; C; 01C9; # LATIN CAPITAL LETTER LJ
-01C8; C; 01C9; # LATIN CAPITAL LETTER L WITH SMALL LETTER J
-01CA; C; 01CC; # LATIN CAPITAL LETTER NJ
-01CB; C; 01CC; # LATIN CAPITAL LETTER N WITH SMALL LETTER J
-01CD; C; 01CE; # LATIN CAPITAL LETTER A WITH CARON
-01CF; C; 01D0; # LATIN CAPITAL LETTER I WITH CARON
-01D1; C; 01D2; # LATIN CAPITAL LETTER O WITH CARON
-01D3; C; 01D4; # LATIN CAPITAL LETTER U WITH CARON
-01D5; C; 01D6; # LATIN CAPITAL LETTER U WITH DIAERESIS AND MACRON
-01D7; C; 01D8; # LATIN CAPITAL LETTER U WITH DIAERESIS AND ACUTE
-01D9; C; 01DA; # LATIN CAPITAL LETTER U WITH DIAERESIS AND CARON
-01DB; C; 01DC; # LATIN CAPITAL LETTER U WITH DIAERESIS AND GRAVE
-01DE; C; 01DF; # LATIN CAPITAL LETTER A WITH DIAERESIS AND MACRON
-01E0; C; 01E1; # LATIN CAPITAL LETTER A WITH DOT ABOVE AND MACRON
-01E2; C; 01E3; # LATIN CAPITAL LETTER AE WITH MACRON
-01E4; C; 01E5; # LATIN CAPITAL LETTER G WITH STROKE
-01E6; C; 01E7; # LATIN CAPITAL LETTER G WITH CARON
-01E8; C; 01E9; # LATIN CAPITAL LETTER K WITH CARON
-01EA; C; 01EB; # LATIN CAPITAL LETTER O WITH OGONEK
-01EC; C; 01ED; # LATIN CAPITAL LETTER O WITH OGONEK AND MACRON
-01EE; C; 01EF; # LATIN CAPITAL LETTER EZH WITH CARON
-01F0; F; 006A 030C; # LATIN SMALL LETTER J WITH CARON
-01F1; C; 01F3; # LATIN CAPITAL LETTER DZ
-01F2; C; 01F3; # LATIN CAPITAL LETTER D WITH SMALL LETTER Z
-01F4; C; 01F5; # LATIN CAPITAL LETTER G WITH ACUTE
-01F6; C; 0195; # LATIN CAPITAL LETTER HWAIR
-01F7; C; 01BF; # LATIN CAPITAL LETTER WYNN
-01F8; C; 01F9; # LATIN CAPITAL LETTER N WITH GRAVE
-01FA; C; 01FB; # LATIN CAPITAL LETTER A WITH RING ABOVE AND ACUTE
-01FC; C; 01FD; # LATIN CAPITAL LETTER AE WITH ACUTE
-01FE; C; 01FF; # LATIN CAPITAL LETTER O WITH STROKE AND ACUTE
-0200; C; 0201; # LATIN CAPITAL LETTER A WITH DOUBLE GRAVE
-0202; C; 0203; # LATIN CAPITAL LETTER A WITH INVERTED BREVE
-0204; C; 0205; # LATIN CAPITAL LETTER E WITH DOUBLE GRAVE
-0206; C; 0207; # LATIN CAPITAL LETTER E WITH INVERTED BREVE
-0208; C; 0209; # LATIN CAPITAL LETTER I WITH DOUBLE GRAVE
-020A; C; 020B; # LATIN CAPITAL LETTER I WITH INVERTED BREVE
-020C; C; 020D; # LATIN CAPITAL LETTER O WITH DOUBLE GRAVE
-020E; C; 020F; # LATIN CAPITAL LETTER O WITH INVERTED BREVE
-0210; C; 0211; # LATIN CAPITAL LETTER R WITH DOUBLE GRAVE
-0212; C; 0213; # LATIN CAPITAL LETTER R WITH INVERTED BREVE
-0214; C; 0215; # LATIN CAPITAL LETTER U WITH DOUBLE GRAVE
-0216; C; 0217; # LATIN CAPITAL LETTER U WITH INVERTED BREVE
-0218; C; 0219; # LATIN CAPITAL LETTER S WITH COMMA BELOW
-021A; C; 021B; # LATIN CAPITAL LETTER T WITH COMMA BELOW
-021C; C; 021D; # LATIN CAPITAL LETTER YOGH
-021E; C; 021F; # LATIN CAPITAL LETTER H WITH CARON
-0220; C; 019E; # LATIN CAPITAL LETTER N WITH LONG RIGHT LEG
-0222; C; 0223; # LATIN CAPITAL LETTER OU
-0224; C; 0225; # LATIN CAPITAL LETTER Z WITH HOOK
-0226; C; 0227; # LATIN CAPITAL LETTER A WITH DOT ABOVE
-0228; C; 0229; # LATIN CAPITAL LETTER E WITH CEDILLA
-022A; C; 022B; # LATIN CAPITAL LETTER O WITH DIAERESIS AND MACRON
-022C; C; 022D; # LATIN CAPITAL LETTER O WITH TILDE AND MACRON
-022E; C; 022F; # LATIN CAPITAL LETTER O WITH DOT ABOVE
-0230; C; 0231; # LATIN CAPITAL LETTER O WITH DOT ABOVE AND MACRON
-0232; C; 0233; # LATIN CAPITAL LETTER Y WITH MACRON
-023A; C; 2C65; # LATIN CAPITAL LETTER A WITH STROKE
-023B; C; 023C; # LATIN CAPITAL LETTER C WITH STROKE
-023D; C; 019A; # LATIN CAPITAL LETTER L WITH BAR
-023E; C; 2C66; # LATIN CAPITAL LETTER T WITH DIAGONAL STROKE
-0241; C; 0242; # LATIN CAPITAL LETTER GLOTTAL STOP
-0243; C; 0180; # LATIN CAPITAL LETTER B WITH STROKE
-0244; C; 0289; # LATIN CAPITAL LETTER U BAR
-0245; C; 028C; # LATIN CAPITAL LETTER TURNED V
-0246; C; 0247; # LATIN CAPITAL LETTER E WITH STROKE
-0248; C; 0249; # LATIN CAPITAL LETTER J WITH STROKE
-024A; C; 024B; # LATIN CAPITAL LETTER SMALL Q WITH HOOK TAIL
-024C; C; 024D; # LATIN CAPITAL LETTER R WITH STROKE
-024E; C; 024F; # LATIN CAPITAL LETTER Y WITH STROKE
-0345; C; 03B9; # COMBINING GREEK YPOGEGRAMMENI
-0370; C; 0371; # GREEK CAPITAL LETTER HETA
-0372; C; 0373; # GREEK CAPITAL LETTER ARCHAIC SAMPI
-0376; C; 0377; # GREEK CAPITAL LETTER PAMPHYLIAN DIGAMMA
-0386; C; 03AC; # GREEK CAPITAL LETTER ALPHA WITH TONOS
-0388; C; 03AD; # GREEK CAPITAL LETTER EPSILON WITH TONOS
-0389; C; 03AE; # GREEK CAPITAL LETTER ETA WITH TONOS
-038A; C; 03AF; # GREEK CAPITAL LETTER IOTA WITH TONOS
-038C; C; 03CC; # GREEK CAPITAL LETTER OMICRON WITH TONOS
-038E; C; 03CD; # GREEK CAPITAL LETTER UPSILON WITH TONOS
-038F; C; 03CE; # GREEK CAPITAL LETTER OMEGA WITH TONOS
-0390; F; 03B9 0308 0301; # GREEK SMALL LETTER IOTA WITH DIALYTIKA AND TONOS
-0391; C; 03B1; # GREEK CAPITAL LETTER ALPHA
-0392; C; 03B2; # GREEK CAPITAL LETTER BETA
-0393; C; 03B3; # GREEK CAPITAL LETTER GAMMA
-0394; C; 03B4; # GREEK CAPITAL LETTER DELTA
-0395; C; 03B5; # GREEK CAPITAL LETTER EPSILON
-0396; C; 03B6; # GREEK CAPITAL LETTER ZETA
-0397; C; 03B7; # GREEK CAPITAL LETTER ETA
-0398; C; 03B8; # GREEK CAPITAL LETTER THETA
-0399; C; 03B9; # GREEK CAPITAL LETTER IOTA
-039A; C; 03BA; # GREEK CAPITAL LETTER KAPPA
-039B; C; 03BB; # GREEK CAPITAL LETTER LAMDA
-039C; C; 03BC; # GREEK CAPITAL LETTER MU
-039D; C; 03BD; # GREEK CAPITAL LETTER NU
-039E; C; 03BE; # GREEK CAPITAL LETTER XI
-039F; C; 03BF; # GREEK CAPITAL LETTER OMICRON
-03A0; C; 03C0; # GREEK CAPITAL LETTER PI
-03A1; C; 03C1; # GREEK CAPITAL LETTER RHO
-03A3; C; 03C3; # GREEK CAPITAL LETTER SIGMA
-03A4; C; 03C4; # GREEK CAPITAL LETTER TAU
-03A5; C; 03C5; # GREEK CAPITAL LETTER UPSILON
-03A6; C; 03C6; # GREEK CAPITAL LETTER PHI
-03A7; C; 03C7; # GREEK CAPITAL LETTER CHI
-03A8; C; 03C8; # GREEK CAPITAL LETTER PSI
-03A9; C; 03C9; # GREEK CAPITAL LETTER OMEGA
-03AA; C; 03CA; # GREEK CAPITAL LETTER IOTA WITH DIALYTIKA
-03AB; C; 03CB; # GREEK CAPITAL LETTER UPSILON WITH DIALYTIKA
-03B0; F; 03C5 0308 0301; # GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND TONOS
-03C2; C; 03C3; # GREEK SMALL LETTER FINAL SIGMA
-03CF; C; 03D7; # GREEK CAPITAL KAI SYMBOL
-03D0; C; 03B2; # GREEK BETA SYMBOL
-03D1; C; 03B8; # GREEK THETA SYMBOL
-03D5; C; 03C6; # GREEK PHI SYMBOL
-03D6; C; 03C0; # GREEK PI SYMBOL
-03D8; C; 03D9; # GREEK LETTER ARCHAIC KOPPA
-03DA; C; 03DB; # GREEK LETTER STIGMA
-03DC; C; 03DD; # GREEK LETTER DIGAMMA
-03DE; C; 03DF; # GREEK LETTER KOPPA
-03E0; C; 03E1; # GREEK LETTER SAMPI
-03E2; C; 03E3; # COPTIC CAPITAL LETTER SHEI
-03E4; C; 03E5; # COPTIC CAPITAL LETTER FEI
-03E6; C; 03E7; # COPTIC CAPITAL LETTER KHEI
-03E8; C; 03E9; # COPTIC CAPITAL LETTER HORI
-03EA; C; 03EB; # COPTIC CAPITAL LETTER GANGIA
-03EC; C; 03ED; # COPTIC CAPITAL LETTER SHIMA
-03EE; C; 03EF; # COPTIC CAPITAL LETTER DEI
-03F0; C; 03BA; # GREEK KAPPA SYMBOL
-03F1; C; 03C1; # GREEK RHO SYMBOL
-03F4; C; 03B8; # GREEK CAPITAL THETA SYMBOL
-03F5; C; 03B5; # GREEK LUNATE EPSILON SYMBOL
-03F7; C; 03F8; # GREEK CAPITAL LETTER SHO
-03F9; C; 03F2; # GREEK CAPITAL LUNATE SIGMA SYMBOL
-03FA; C; 03FB; # GREEK CAPITAL LETTER SAN
-03FD; C; 037B; # GREEK CAPITAL REVERSED LUNATE SIGMA SYMBOL
-03FE; C; 037C; # GREEK CAPITAL DOTTED LUNATE SIGMA SYMBOL
-03FF; C; 037D; # GREEK CAPITAL REVERSED DOTTED LUNATE SIGMA SYMBOL
-0400; C; 0450; # CYRILLIC CAPITAL LETTER IE WITH GRAVE
-0401; C; 0451; # CYRILLIC CAPITAL LETTER IO
-0402; C; 0452; # CYRILLIC CAPITAL LETTER DJE
-0403; C; 0453; # CYRILLIC CAPITAL LETTER GJE
-0404; C; 0454; # CYRILLIC CAPITAL LETTER UKRAINIAN IE
-0405; C; 0455; # CYRILLIC CAPITAL LETTER DZE
-0406; C; 0456; # CYRILLIC CAPITAL LETTER BYELORUSSIAN-UKRAINIAN I
-0407; C; 0457; # CYRILLIC CAPITAL LETTER YI
-0408; C; 0458; # CYRILLIC CAPITAL LETTER JE
-0409; C; 0459; # CYRILLIC CAPITAL LETTER LJE
-040A; C; 045A; # CYRILLIC CAPITAL LETTER NJE
-040B; C; 045B; # CYRILLIC CAPITAL LETTER TSHE
-040C; C; 045C; # CYRILLIC CAPITAL LETTER KJE
-040D; C; 045D; # CYRILLIC CAPITAL LETTER I WITH GRAVE
-040E; C; 045E; # CYRILLIC CAPITAL LETTER SHORT U
-040F; C; 045F; # CYRILLIC CAPITAL LETTER DZHE
-0410; C; 0430; # CYRILLIC CAPITAL LETTER A
-0411; C; 0431; # CYRILLIC CAPITAL LETTER BE
-0412; C; 0432; # CYRILLIC CAPITAL LETTER VE
-0413; C; 0433; # CYRILLIC CAPITAL LETTER GHE
-0414; C; 0434; # CYRILLIC CAPITAL LETTER DE
-0415; C; 0435; # CYRILLIC CAPITAL LETTER IE
-0416; C; 0436; # CYRILLIC CAPITAL LETTER ZHE
-0417; C; 0437; # CYRILLIC CAPITAL LETTER ZE
-0418; C; 0438; # CYRILLIC CAPITAL LETTER I
-0419; C; 0439; # CYRILLIC CAPITAL LETTER SHORT I
-041A; C; 043A; # CYRILLIC CAPITAL LETTER KA
-041B; C; 043B; # CYRILLIC CAPITAL LETTER EL
-041C; C; 043C; # CYRILLIC CAPITAL LETTER EM
-041D; C; 043D; # CYRILLIC CAPITAL LETTER EN
-041E; C; 043E; # CYRILLIC CAPITAL LETTER O
-041F; C; 043F; # CYRILLIC CAPITAL LETTER PE
-0420; C; 0440; # CYRILLIC CAPITAL LETTER ER
-0421; C; 0441; # CYRILLIC CAPITAL LETTER ES
-0422; C; 0442; # CYRILLIC CAPITAL LETTER TE
-0423; C; 0443; # CYRILLIC CAPITAL LETTER U
-0424; C; 0444; # CYRILLIC CAPITAL LETTER EF
-0425; C; 0445; # CYRILLIC CAPITAL LETTER HA
-0426; C; 0446; # CYRILLIC CAPITAL LETTER TSE
-0427; C; 0447; # CYRILLIC CAPITAL LETTER CHE
-0428; C; 0448; # CYRILLIC CAPITAL LETTER SHA
-0429; C; 0449; # CYRILLIC CAPITAL LETTER SHCHA
-042A; C; 044A; # CYRILLIC CAPITAL LETTER HARD SIGN
-042B; C; 044B; # CYRILLIC CAPITAL LETTER YERU
-042C; C; 044C; # CYRILLIC CAPITAL LETTER SOFT SIGN
-042D; C; 044D; # CYRILLIC CAPITAL LETTER E
-042E; C; 044E; # CYRILLIC CAPITAL LETTER YU
-042F; C; 044F; # CYRILLIC CAPITAL LETTER YA
-0460; C; 0461; # CYRILLIC CAPITAL LETTER OMEGA
-0462; C; 0463; # CYRILLIC CAPITAL LETTER YAT
-0464; C; 0465; # CYRILLIC CAPITAL LETTER IOTIFIED E
-0466; C; 0467; # CYRILLIC CAPITAL LETTER LITTLE YUS
-0468; C; 0469; # CYRILLIC CAPITAL LETTER IOTIFIED LITTLE YUS
-046A; C; 046B; # CYRILLIC CAPITAL LETTER BIG YUS
-046C; C; 046D; # CYRILLIC CAPITAL LETTER IOTIFIED BIG YUS
-046E; C; 046F; # CYRILLIC CAPITAL LETTER KSI
-0470; C; 0471; # CYRILLIC CAPITAL LETTER PSI
-0472; C; 0473; # CYRILLIC CAPITAL LETTER FITA
-0474; C; 0475; # CYRILLIC CAPITAL LETTER IZHITSA
-0476; C; 0477; # CYRILLIC CAPITAL LETTER IZHITSA WITH DOUBLE GRAVE ACCENT
-0478; C; 0479; # CYRILLIC CAPITAL LETTER UK
-047A; C; 047B; # CYRILLIC CAPITAL LETTER ROUND OMEGA
-047C; C; 047D; # CYRILLIC CAPITAL LETTER OMEGA WITH TITLO
-047E; C; 047F; # CYRILLIC CAPITAL LETTER OT
-0480; C; 0481; # CYRILLIC CAPITAL LETTER KOPPA
-048A; C; 048B; # CYRILLIC CAPITAL LETTER SHORT I WITH TAIL
-048C; C; 048D; # CYRILLIC CAPITAL LETTER SEMISOFT SIGN
-048E; C; 048F; # CYRILLIC CAPITAL LETTER ER WITH TICK
-0490; C; 0491; # CYRILLIC CAPITAL LETTER GHE WITH UPTURN
-0492; C; 0493; # CYRILLIC CAPITAL LETTER GHE WITH STROKE
-0494; C; 0495; # CYRILLIC CAPITAL LETTER GHE WITH MIDDLE HOOK
-0496; C; 0497; # CYRILLIC CAPITAL LETTER ZHE WITH DESCENDER
-0498; C; 0499; # CYRILLIC CAPITAL LETTER ZE WITH DESCENDER
-049A; C; 049B; # CYRILLIC CAPITAL LETTER KA WITH DESCENDER
-049C; C; 049D; # CYRILLIC CAPITAL LETTER KA WITH VERTICAL STROKE
-049E; C; 049F; # CYRILLIC CAPITAL LETTER KA WITH STROKE
-04A0; C; 04A1; # CYRILLIC CAPITAL LETTER BASHKIR KA
-04A2; C; 04A3; # CYRILLIC CAPITAL LETTER EN WITH DESCENDER
-04A4; C; 04A5; # CYRILLIC CAPITAL LIGATURE EN GHE
-04A6; C; 04A7; # CYRILLIC CAPITAL LETTER PE WITH MIDDLE HOOK
-04A8; C; 04A9; # CYRILLIC CAPITAL LETTER ABKHASIAN HA
-04AA; C; 04AB; # CYRILLIC CAPITAL LETTER ES WITH DESCENDER
-04AC; C; 04AD; # CYRILLIC CAPITAL LETTER TE WITH DESCENDER
-04AE; C; 04AF; # CYRILLIC CAPITAL LETTER STRAIGHT U
-04B0; C; 04B1; # CYRILLIC CAPITAL LETTER STRAIGHT U WITH STROKE
-04B2; C; 04B3; # CYRILLIC CAPITAL LETTER HA WITH DESCENDER
-04B4; C; 04B5; # CYRILLIC CAPITAL LIGATURE TE TSE
-04B6; C; 04B7; # CYRILLIC CAPITAL LETTER CHE WITH DESCENDER
-04B8; C; 04B9; # CYRILLIC CAPITAL LETTER CHE WITH VERTICAL STROKE
-04BA; C; 04BB; # CYRILLIC CAPITAL LETTER SHHA
-04BC; C; 04BD; # CYRILLIC CAPITAL LETTER ABKHASIAN CHE
-04BE; C; 04BF; # CYRILLIC CAPITAL LETTER ABKHASIAN CHE WITH DESCENDER
-04C0; C; 04CF; # CYRILLIC LETTER PALOCHKA
-04C1; C; 04C2; # CYRILLIC CAPITAL LETTER ZHE WITH BREVE
-04C3; C; 04C4; # CYRILLIC CAPITAL LETTER KA WITH HOOK
-04C5; C; 04C6; # CYRILLIC CAPITAL LETTER EL WITH TAIL
-04C7; C; 04C8; # CYRILLIC CAPITAL LETTER EN WITH HOOK
-04C9; C; 04CA; # CYRILLIC CAPITAL LETTER EN WITH TAIL
-04CB; C; 04CC; # CYRILLIC CAPITAL LETTER KHAKASSIAN CHE
-04CD; C; 04CE; # CYRILLIC CAPITAL LETTER EM WITH TAIL
-04D0; C; 04D1; # CYRILLIC CAPITAL LETTER A WITH BREVE
-04D2; C; 04D3; # CYRILLIC CAPITAL LETTER A WITH DIAERESIS
-04D4; C; 04D5; # CYRILLIC CAPITAL LIGATURE A IE
-04D6; C; 04D7; # CYRILLIC CAPITAL LETTER IE WITH BREVE
-04D8; C; 04D9; # CYRILLIC CAPITAL LETTER SCHWA
-04DA; C; 04DB; # CYRILLIC CAPITAL LETTER SCHWA WITH DIAERESIS
-04DC; C; 04DD; # CYRILLIC CAPITAL LETTER ZHE WITH DIAERESIS
-04DE; C; 04DF; # CYRILLIC CAPITAL LETTER ZE WITH DIAERESIS
-04E0; C; 04E1; # CYRILLIC CAPITAL LETTER ABKHASIAN DZE
-04E2; C; 04E3; # CYRILLIC CAPITAL LETTER I WITH MACRON
-04E4; C; 04E5; # CYRILLIC CAPITAL LETTER I WITH DIAERESIS
-04E6; C; 04E7; # CYRILLIC CAPITAL LETTER O WITH DIAERESIS
-04E8; C; 04E9; # CYRILLIC CAPITAL LETTER BARRED O
-04EA; C; 04EB; # CYRILLIC CAPITAL LETTER BARRED O WITH DIAERESIS
-04EC; C; 04ED; # CYRILLIC CAPITAL LETTER E WITH DIAERESIS
-04EE; C; 04EF; # CYRILLIC CAPITAL LETTER U WITH MACRON
-04F0; C; 04F1; # CYRILLIC CAPITAL LETTER U WITH DIAERESIS
-04F2; C; 04F3; # CYRILLIC CAPITAL LETTER U WITH DOUBLE ACUTE
-04F4; C; 04F5; # CYRILLIC CAPITAL LETTER CHE WITH DIAERESIS
-04F6; C; 04F7; # CYRILLIC CAPITAL LETTER GHE WITH DESCENDER
-04F8; C; 04F9; # CYRILLIC CAPITAL LETTER YERU WITH DIAERESIS
-04FA; C; 04FB; # CYRILLIC CAPITAL LETTER GHE WITH STROKE AND HOOK
-04FC; C; 04FD; # CYRILLIC CAPITAL LETTER HA WITH HOOK
-04FE; C; 04FF; # CYRILLIC CAPITAL LETTER HA WITH STROKE
-0500; C; 0501; # CYRILLIC CAPITAL LETTER KOMI DE
-0502; C; 0503; # CYRILLIC CAPITAL LETTER KOMI DJE
-0504; C; 0505; # CYRILLIC CAPITAL LETTER KOMI ZJE
-0506; C; 0507; # CYRILLIC CAPITAL LETTER KOMI DZJE
-0508; C; 0509; # CYRILLIC CAPITAL LETTER KOMI LJE
-050A; C; 050B; # CYRILLIC CAPITAL LETTER KOMI NJE
-050C; C; 050D; # CYRILLIC CAPITAL LETTER KOMI SJE
-050E; C; 050F; # CYRILLIC CAPITAL LETTER KOMI TJE
-0510; C; 0511; # CYRILLIC CAPITAL LETTER REVERSED ZE
-0512; C; 0513; # CYRILLIC CAPITAL LETTER EL WITH HOOK
-0514; C; 0515; # CYRILLIC CAPITAL LETTER LHA
-0516; C; 0517; # CYRILLIC CAPITAL LETTER RHA
-0518; C; 0519; # CYRILLIC CAPITAL LETTER YAE
-051A; C; 051B; # CYRILLIC CAPITAL LETTER QA
-051C; C; 051D; # CYRILLIC CAPITAL LETTER WE
-051E; C; 051F; # CYRILLIC CAPITAL LETTER ALEUT KA
-0520; C; 0521; # CYRILLIC CAPITAL LETTER EL WITH MIDDLE HOOK
-0522; C; 0523; # CYRILLIC CAPITAL LETTER EN WITH MIDDLE HOOK
-0524; C; 0525; # CYRILLIC CAPITAL LETTER PE WITH DESCENDER
-0526; C; 0527; # CYRILLIC CAPITAL LETTER SHHA WITH DESCENDER
-0531; C; 0561; # ARMENIAN CAPITAL LETTER AYB
-0532; C; 0562; # ARMENIAN CAPITAL LETTER BEN
-0533; C; 0563; # ARMENIAN CAPITAL LETTER GIM
-0534; C; 0564; # ARMENIAN CAPITAL LETTER DA
-0535; C; 0565; # ARMENIAN CAPITAL LETTER ECH
-0536; C; 0566; # ARMENIAN CAPITAL LETTER ZA
-0537; C; 0567; # ARMENIAN CAPITAL LETTER EH
-0538; C; 0568; # ARMENIAN CAPITAL LETTER ET
-0539; C; 0569; # ARMENIAN CAPITAL LETTER TO
-053A; C; 056A; # ARMENIAN CAPITAL LETTER ZHE
-053B; C; 056B; # ARMENIAN CAPITAL LETTER INI
-053C; C; 056C; # ARMENIAN CAPITAL LETTER LIWN
-053D; C; 056D; # ARMENIAN CAPITAL LETTER XEH
-053E; C; 056E; # ARMENIAN CAPITAL LETTER CA
-053F; C; 056F; # ARMENIAN CAPITAL LETTER KEN
-0540; C; 0570; # ARMENIAN CAPITAL LETTER HO
-0541; C; 0571; # ARMENIAN CAPITAL LETTER JA
-0542; C; 0572; # ARMENIAN CAPITAL LETTER GHAD
-0543; C; 0573; # ARMENIAN CAPITAL LETTER CHEH
-0544; C; 0574; # ARMENIAN CAPITAL LETTER MEN
-0545; C; 0575; # ARMENIAN CAPITAL LETTER YI
-0546; C; 0576; # ARMENIAN CAPITAL LETTER NOW
-0547; C; 0577; # ARMENIAN CAPITAL LETTER SHA
-0548; C; 0578; # ARMENIAN CAPITAL LETTER VO
-0549; C; 0579; # ARMENIAN CAPITAL LETTER CHA
-054A; C; 057A; # ARMENIAN CAPITAL LETTER PEH
-054B; C; 057B; # ARMENIAN CAPITAL LETTER JHEH
-054C; C; 057C; # ARMENIAN CAPITAL LETTER RA
-054D; C; 057D; # ARMENIAN CAPITAL LETTER SEH
-054E; C; 057E; # ARMENIAN CAPITAL LETTER VEW
-054F; C; 057F; # ARMENIAN CAPITAL LETTER TIWN
-0550; C; 0580; # ARMENIAN CAPITAL LETTER REH
-0551; C; 0581; # ARMENIAN CAPITAL LETTER CO
-0552; C; 0582; # ARMENIAN CAPITAL LETTER YIWN
-0553; C; 0583; # ARMENIAN CAPITAL LETTER PIWR
-0554; C; 0584; # ARMENIAN CAPITAL LETTER KEH
-0555; C; 0585; # ARMENIAN CAPITAL LETTER OH
-0556; C; 0586; # ARMENIAN CAPITAL LETTER FEH
-0587; F; 0565 0582; # ARMENIAN SMALL LIGATURE ECH YIWN
-10A0; C; 2D00; # GEORGIAN CAPITAL LETTER AN
-10A1; C; 2D01; # GEORGIAN CAPITAL LETTER BAN
-10A2; C; 2D02; # GEORGIAN CAPITAL LETTER GAN
-10A3; C; 2D03; # GEORGIAN CAPITAL LETTER DON
-10A4; C; 2D04; # GEORGIAN CAPITAL LETTER EN
-10A5; C; 2D05; # GEORGIAN CAPITAL LETTER VIN
-10A6; C; 2D06; # GEORGIAN CAPITAL LETTER ZEN
-10A7; C; 2D07; # GEORGIAN CAPITAL LETTER TAN
-10A8; C; 2D08; # GEORGIAN CAPITAL LETTER IN
-10A9; C; 2D09; # GEORGIAN CAPITAL LETTER KAN
-10AA; C; 2D0A; # GEORGIAN CAPITAL LETTER LAS
-10AB; C; 2D0B; # GEORGIAN CAPITAL LETTER MAN
-10AC; C; 2D0C; # GEORGIAN CAPITAL LETTER NAR
-10AD; C; 2D0D; # GEORGIAN CAPITAL LETTER ON
-10AE; C; 2D0E; # GEORGIAN CAPITAL LETTER PAR
-10AF; C; 2D0F; # GEORGIAN CAPITAL LETTER ZHAR
-10B0; C; 2D10; # GEORGIAN CAPITAL LETTER RAE
-10B1; C; 2D11; # GEORGIAN CAPITAL LETTER SAN
-10B2; C; 2D12; # GEORGIAN CAPITAL LETTER TAR
-10B3; C; 2D13; # GEORGIAN CAPITAL LETTER UN
-10B4; C; 2D14; # GEORGIAN CAPITAL LETTER PHAR
-10B5; C; 2D15; # GEORGIAN CAPITAL LETTER KHAR
-10B6; C; 2D16; # GEORGIAN CAPITAL LETTER GHAN
-10B7; C; 2D17; # GEORGIAN CAPITAL LETTER QAR
-10B8; C; 2D18; # GEORGIAN CAPITAL LETTER SHIN
-10B9; C; 2D19; # GEORGIAN CAPITAL LETTER CHIN
-10BA; C; 2D1A; # GEORGIAN CAPITAL LETTER CAN
-10BB; C; 2D1B; # GEORGIAN CAPITAL LETTER JIL
-10BC; C; 2D1C; # GEORGIAN CAPITAL LETTER CIL
-10BD; C; 2D1D; # GEORGIAN CAPITAL LETTER CHAR
-10BE; C; 2D1E; # GEORGIAN CAPITAL LETTER XAN
-10BF; C; 2D1F; # GEORGIAN CAPITAL LETTER JHAN
-10C0; C; 2D20; # GEORGIAN CAPITAL LETTER HAE
-10C1; C; 2D21; # GEORGIAN CAPITAL LETTER HE
-10C2; C; 2D22; # GEORGIAN CAPITAL LETTER HIE
-10C3; C; 2D23; # GEORGIAN CAPITAL LETTER WE
-10C4; C; 2D24; # GEORGIAN CAPITAL LETTER HAR
-10C5; C; 2D25; # GEORGIAN CAPITAL LETTER HOE
-10C7; C; 2D27; # GEORGIAN CAPITAL LETTER YN
-10CD; C; 2D2D; # GEORGIAN CAPITAL LETTER AEN
-1E00; C; 1E01; # LATIN CAPITAL LETTER A WITH RING BELOW
-1E02; C; 1E03; # LATIN CAPITAL LETTER B WITH DOT ABOVE
-1E04; C; 1E05; # LATIN CAPITAL LETTER B WITH DOT BELOW
-1E06; C; 1E07; # LATIN CAPITAL LETTER B WITH LINE BELOW
-1E08; C; 1E09; # LATIN CAPITAL LETTER C WITH CEDILLA AND ACUTE
-1E0A; C; 1E0B; # LATIN CAPITAL LETTER D WITH DOT ABOVE
-1E0C; C; 1E0D; # LATIN CAPITAL LETTER D WITH DOT BELOW
-1E0E; C; 1E0F; # LATIN CAPITAL LETTER D WITH LINE BELOW
-1E10; C; 1E11; # LATIN CAPITAL LETTER D WITH CEDILLA
-1E12; C; 1E13; # LATIN CAPITAL LETTER D WITH CIRCUMFLEX BELOW
-1E14; C; 1E15; # LATIN CAPITAL LETTER E WITH MACRON AND GRAVE
-1E16; C; 1E17; # LATIN CAPITAL LETTER E WITH MACRON AND ACUTE
-1E18; C; 1E19; # LATIN CAPITAL LETTER E WITH CIRCUMFLEX BELOW
-1E1A; C; 1E1B; # LATIN CAPITAL LETTER E WITH TILDE BELOW
-1E1C; C; 1E1D; # LATIN CAPITAL LETTER E WITH CEDILLA AND BREVE
-1E1E; C; 1E1F; # LATIN CAPITAL LETTER F WITH DOT ABOVE
-1E20; C; 1E21; # LATIN CAPITAL LETTER G WITH MACRON
-1E22; C; 1E23; # LATIN CAPITAL LETTER H WITH DOT ABOVE
-1E24; C; 1E25; # LATIN CAPITAL LETTER H WITH DOT BELOW
-1E26; C; 1E27; # LATIN CAPITAL LETTER H WITH DIAERESIS
-1E28; C; 1E29; # LATIN CAPITAL LETTER H WITH CEDILLA
-1E2A; C; 1E2B; # LATIN CAPITAL LETTER H WITH BREVE BELOW
-1E2C; C; 1E2D; # LATIN CAPITAL LETTER I WITH TILDE BELOW
-1E2E; C; 1E2F; # LATIN CAPITAL LETTER I WITH DIAERESIS AND ACUTE
-1E30; C; 1E31; # LATIN CAPITAL LETTER K WITH ACUTE
-1E32; C; 1E33; # LATIN CAPITAL LETTER K WITH DOT BELOW
-1E34; C; 1E35; # LATIN CAPITAL LETTER K WITH LINE BELOW
-1E36; C; 1E37; # LATIN CAPITAL LETTER L WITH DOT BELOW
-1E38; C; 1E39; # LATIN CAPITAL LETTER L WITH DOT BELOW AND MACRON
-1E3A; C; 1E3B; # LATIN CAPITAL LETTER L WITH LINE BELOW
-1E3C; C; 1E3D; # LATIN CAPITAL LETTER L WITH CIRCUMFLEX BELOW
-1E3E; C; 1E3F; # LATIN CAPITAL LETTER M WITH ACUTE
-1E40; C; 1E41; # LATIN CAPITAL LETTER M WITH DOT ABOVE
-1E42; C; 1E43; # LATIN CAPITAL LETTER M WITH DOT BELOW
-1E44; C; 1E45; # LATIN CAPITAL LETTER N WITH DOT ABOVE
-1E46; C; 1E47; # LATIN CAPITAL LETTER N WITH DOT BELOW
-1E48; C; 1E49; # LATIN CAPITAL LETTER N WITH LINE BELOW
-1E4A; C; 1E4B; # LATIN CAPITAL LETTER N WITH CIRCUMFLEX BELOW
-1E4C; C; 1E4D; # LATIN CAPITAL LETTER O WITH TILDE AND ACUTE
-1E4E; C; 1E4F; # LATIN CAPITAL LETTER O WITH TILDE AND DIAERESIS
-1E50; C; 1E51; # LATIN CAPITAL LETTER O WITH MACRON AND GRAVE
-1E52; C; 1E53; # LATIN CAPITAL LETTER O WITH MACRON AND ACUTE
-1E54; C; 1E55; # LATIN CAPITAL LETTER P WITH ACUTE
-1E56; C; 1E57; # LATIN CAPITAL LETTER P WITH DOT ABOVE
-1E58; C; 1E59; # LATIN CAPITAL LETTER R WITH DOT ABOVE
-1E5A; C; 1E5B; # LATIN CAPITAL LETTER R WITH DOT BELOW
-1E5C; C; 1E5D; # LATIN CAPITAL LETTER R WITH DOT BELOW AND MACRON
-1E5E; C; 1E5F; # LATIN CAPITAL LETTER R WITH LINE BELOW
-1E60; C; 1E61; # LATIN CAPITAL LETTER S WITH DOT ABOVE
-1E62; C; 1E63; # LATIN CAPITAL LETTER S WITH DOT BELOW
-1E64; C; 1E65; # LATIN CAPITAL LETTER S WITH ACUTE AND DOT ABOVE
-1E66; C; 1E67; # LATIN CAPITAL LETTER S WITH CARON AND DOT ABOVE
-1E68; C; 1E69; # LATIN CAPITAL LETTER S WITH DOT BELOW AND DOT ABOVE
-1E6A; C; 1E6B; # LATIN CAPITAL LETTER T WITH DOT ABOVE
-1E6C; C; 1E6D; # LATIN CAPITAL LETTER T WITH DOT BELOW
-1E6E; C; 1E6F; # LATIN CAPITAL LETTER T WITH LINE BELOW
-1E70; C; 1E71; # LATIN CAPITAL LETTER T WITH CIRCUMFLEX BELOW
-1E72; C; 1E73; # LATIN CAPITAL LETTER U WITH DIAERESIS BELOW
-1E74; C; 1E75; # LATIN CAPITAL LETTER U WITH TILDE BELOW
-1E76; C; 1E77; # LATIN CAPITAL LETTER U WITH CIRCUMFLEX BELOW
-1E78; C; 1E79; # LATIN CAPITAL LETTER U WITH TILDE AND ACUTE
-1E7A; C; 1E7B; # LATIN CAPITAL LETTER U WITH MACRON AND DIAERESIS
-1E7C; C; 1E7D; # LATIN CAPITAL LETTER V WITH TILDE
-1E7E; C; 1E7F; # LATIN CAPITAL LETTER V WITH DOT BELOW
-1E80; C; 1E81; # LATIN CAPITAL LETTER W WITH GRAVE
-1E82; C; 1E83; # LATIN CAPITAL LETTER W WITH ACUTE
-1E84; C; 1E85; # LATIN CAPITAL LETTER W WITH DIAERESIS
-1E86; C; 1E87; # LATIN CAPITAL LETTER W WITH DOT ABOVE
-1E88; C; 1E89; # LATIN CAPITAL LETTER W WITH DOT BELOW
-1E8A; C; 1E8B; # LATIN CAPITAL LETTER X WITH DOT ABOVE
-1E8C; C; 1E8D; # LATIN CAPITAL LETTER X WITH DIAERESIS
-1E8E; C; 1E8F; # LATIN CAPITAL LETTER Y WITH DOT ABOVE
-1E90; C; 1E91; # LATIN CAPITAL LETTER Z WITH CIRCUMFLEX
-1E92; C; 1E93; # LATIN CAPITAL LETTER Z WITH DOT BELOW
-1E94; C; 1E95; # LATIN CAPITAL LETTER Z WITH LINE BELOW
-1E96; F; 0068 0331; # LATIN SMALL LETTER H WITH LINE BELOW
-1E97; F; 0074 0308; # LATIN SMALL LETTER T WITH DIAERESIS
-1E98; F; 0077 030A; # LATIN SMALL LETTER W WITH RING ABOVE
-1E99; F; 0079 030A; # LATIN SMALL LETTER Y WITH RING ABOVE
-1E9A; F; 0061 02BE; # LATIN SMALL LETTER A WITH RIGHT HALF RING
-1E9B; C; 1E61; # LATIN SMALL LETTER LONG S WITH DOT ABOVE
-1E9E; F; 0073 0073; # LATIN CAPITAL LETTER SHARP S
-1E9E; S; 00DF; # LATIN CAPITAL LETTER SHARP S
-1EA0; C; 1EA1; # LATIN CAPITAL LETTER A WITH DOT BELOW
-1EA2; C; 1EA3; # LATIN CAPITAL LETTER A WITH HOOK ABOVE
-1EA4; C; 1EA5; # LATIN CAPITAL LETTER A WITH CIRCUMFLEX AND ACUTE
-1EA6; C; 1EA7; # LATIN CAPITAL LETTER A WITH CIRCUMFLEX AND GRAVE
-1EA8; C; 1EA9; # LATIN CAPITAL LETTER A WITH CIRCUMFLEX AND HOOK ABOVE
-1EAA; C; 1EAB; # LATIN CAPITAL LETTER A WITH CIRCUMFLEX AND TILDE
-1EAC; C; 1EAD; # LATIN CAPITAL LETTER A WITH CIRCUMFLEX AND DOT BELOW
-1EAE; C; 1EAF; # LATIN CAPITAL LETTER A WITH BREVE AND ACUTE
-1EB0; C; 1EB1; # LATIN CAPITAL LETTER A WITH BREVE AND GRAVE
-1EB2; C; 1EB3; # LATIN CAPITAL LETTER A WITH BREVE AND HOOK ABOVE
-1EB4; C; 1EB5; # LATIN CAPITAL LETTER A WITH BREVE AND TILDE
-1EB6; C; 1EB7; # LATIN CAPITAL LETTER A WITH BREVE AND DOT BELOW
-1EB8; C; 1EB9; # LATIN CAPITAL LETTER E WITH DOT BELOW
-1EBA; C; 1EBB; # LATIN CAPITAL LETTER E WITH HOOK ABOVE
-1EBC; C; 1EBD; # LATIN CAPITAL LETTER E WITH TILDE
-1EBE; C; 1EBF; # LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND ACUTE
-1EC0; C; 1EC1; # LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND GRAVE
-1EC2; C; 1EC3; # LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND HOOK ABOVE
-1EC4; C; 1EC5; # LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND TILDE
-1EC6; C; 1EC7; # LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND DOT BELOW
-1EC8; C; 1EC9; # LATIN CAPITAL LETTER I WITH HOOK ABOVE
-1ECA; C; 1ECB; # LATIN CAPITAL LETTER I WITH DOT BELOW
-1ECC; C; 1ECD; # LATIN CAPITAL LETTER O WITH DOT BELOW
-1ECE; C; 1ECF; # LATIN CAPITAL LETTER O WITH HOOK ABOVE
-1ED0; C; 1ED1; # LATIN CAPITAL LETTER O WITH CIRCUMFLEX AND ACUTE
-1ED2; C; 1ED3; # LATIN CAPITAL LETTER O WITH CIRCUMFLEX AND GRAVE
-1ED4; C; 1ED5; # LATIN CAPITAL LETTER O WITH CIRCUMFLEX AND HOOK ABOVE
-1ED6; C; 1ED7; # LATIN CAPITAL LETTER O WITH CIRCUMFLEX AND TILDE
-1ED8; C; 1ED9; # LATIN CAPITAL LETTER O WITH CIRCUMFLEX AND DOT BELOW
-1EDA; C; 1EDB; # LATIN CAPITAL LETTER O WITH HORN AND ACUTE
-1EDC; C; 1EDD; # LATIN CAPITAL LETTER O WITH HORN AND GRAVE
-1EDE; C; 1EDF; # LATIN CAPITAL LETTER O WITH HORN AND HOOK ABOVE
-1EE0; C; 1EE1; # LATIN CAPITAL LETTER O WITH HORN AND TILDE
-1EE2; C; 1EE3; # LATIN CAPITAL LETTER O WITH HORN AND DOT BELOW
-1EE4; C; 1EE5; # LATIN CAPITAL LETTER U WITH DOT BELOW
-1EE6; C; 1EE7; # LATIN CAPITAL LETTER U WITH HOOK ABOVE
-1EE8; C; 1EE9; # LATIN CAPITAL LETTER U WITH HORN AND ACUTE
-1EEA; C; 1EEB; # LATIN CAPITAL LETTER U WITH HORN AND GRAVE
-1EEC; C; 1EED; # LATIN CAPITAL LETTER U WITH HORN AND HOOK ABOVE
-1EEE; C; 1EEF; # LATIN CAPITAL LETTER U WITH HORN AND TILDE
-1EF0; C; 1EF1; # LATIN CAPITAL LETTER U WITH HORN AND DOT BELOW
-1EF2; C; 1EF3; # LATIN CAPITAL LETTER Y WITH GRAVE
-1EF4; C; 1EF5; # LATIN CAPITAL LETTER Y WITH DOT BELOW
-1EF6; C; 1EF7; # LATIN CAPITAL LETTER Y WITH HOOK ABOVE
-1EF8; C; 1EF9; # LATIN CAPITAL LETTER Y WITH TILDE
-1EFA; C; 1EFB; # LATIN CAPITAL LETTER MIDDLE-WELSH LL
-1EFC; C; 1EFD; # LATIN CAPITAL LETTER MIDDLE-WELSH V
-1EFE; C; 1EFF; # LATIN CAPITAL LETTER Y WITH LOOP
-1F08; C; 1F00; # GREEK CAPITAL LETTER ALPHA WITH PSILI
-1F09; C; 1F01; # GREEK CAPITAL LETTER ALPHA WITH DASIA
-1F0A; C; 1F02; # GREEK CAPITAL LETTER ALPHA WITH PSILI AND VARIA
-1F0B; C; 1F03; # GREEK CAPITAL LETTER ALPHA WITH DASIA AND VARIA
-1F0C; C; 1F04; # GREEK CAPITAL LETTER ALPHA WITH PSILI AND OXIA
-1F0D; C; 1F05; # GREEK CAPITAL LETTER ALPHA WITH DASIA AND OXIA
-1F0E; C; 1F06; # GREEK CAPITAL LETTER ALPHA WITH PSILI AND PERISPOMENI
-1F0F; C; 1F07; # GREEK CAPITAL LETTER ALPHA WITH DASIA AND PERISPOMENI
-1F18; C; 1F10; # GREEK CAPITAL LETTER EPSILON WITH PSILI
-1F19; C; 1F11; # GREEK CAPITAL LETTER EPSILON WITH DASIA
-1F1A; C; 1F12; # GREEK CAPITAL LETTER EPSILON WITH PSILI AND VARIA
-1F1B; C; 1F13; # GREEK CAPITAL LETTER EPSILON WITH DASIA AND VARIA
-1F1C; C; 1F14; # GREEK CAPITAL LETTER EPSILON WITH PSILI AND OXIA
-1F1D; C; 1F15; # GREEK CAPITAL LETTER EPSILON WITH DASIA AND OXIA
-1F28; C; 1F20; # GREEK CAPITAL LETTER ETA WITH PSILI
-1F29; C; 1F21; # GREEK CAPITAL LETTER ETA WITH DASIA
-1F2A; C; 1F22; # GREEK CAPITAL LETTER ETA WITH PSILI AND VARIA
-1F2B; C; 1F23; # GREEK CAPITAL LETTER ETA WITH DASIA AND VARIA
-1F2C; C; 1F24; # GREEK CAPITAL LETTER ETA WITH PSILI AND OXIA
-1F2D; C; 1F25; # GREEK CAPITAL LETTER ETA WITH DASIA AND OXIA
-1F2E; C; 1F26; # GREEK CAPITAL LETTER ETA WITH PSILI AND PERISPOMENI
-1F2F; C; 1F27; # GREEK CAPITAL LETTER ETA WITH DASIA AND PERISPOMENI
-1F38; C; 1F30; # GREEK CAPITAL LETTER IOTA WITH PSILI
-1F39; C; 1F31; # GREEK CAPITAL LETTER IOTA WITH DASIA
-1F3A; C; 1F32; # GREEK CAPITAL LETTER IOTA WITH PSILI AND VARIA
-1F3B; C; 1F33; # GREEK CAPITAL LETTER IOTA WITH DASIA AND VARIA
-1F3C; C; 1F34; # GREEK CAPITAL LETTER IOTA WITH PSILI AND OXIA
-1F3D; C; 1F35; # GREEK CAPITAL LETTER IOTA WITH DASIA AND OXIA
-1F3E; C; 1F36; # GREEK CAPITAL LETTER IOTA WITH PSILI AND PERISPOMENI
-1F3F; C; 1F37; # GREEK CAPITAL LETTER IOTA WITH DASIA AND PERISPOMENI
-1F48; C; 1F40; # GREEK CAPITAL LETTER OMICRON WITH PSILI
-1F49; C; 1F41; # GREEK CAPITAL LETTER OMICRON WITH DASIA
-1F4A; C; 1F42; # GREEK CAPITAL LETTER OMICRON WITH PSILI AND VARIA
-1F4B; C; 1F43; # GREEK CAPITAL LETTER OMICRON WITH DASIA AND VARIA
-1F4C; C; 1F44; # GREEK CAPITAL LETTER OMICRON WITH PSILI AND OXIA
-1F4D; C; 1F45; # GREEK CAPITAL LETTER OMICRON WITH DASIA AND OXIA
-1F50; F; 03C5 0313; # GREEK SMALL LETTER UPSILON WITH PSILI
-1F52; F; 03C5 0313 0300; # GREEK SMALL LETTER UPSILON WITH PSILI AND VARIA
-1F54; F; 03C5 0313 0301; # GREEK SMALL LETTER UPSILON WITH PSILI AND OXIA
-1F56; F; 03C5 0313 0342; # GREEK SMALL LETTER UPSILON WITH PSILI AND PERISPOMENI
-1F59; C; 1F51; # GREEK CAPITAL LETTER UPSILON WITH DASIA
-1F5B; C; 1F53; # GREEK CAPITAL LETTER UPSILON WITH DASIA AND VARIA
-1F5D; C; 1F55; # GREEK CAPITAL LETTER UPSILON WITH DASIA AND OXIA
-1F5F; C; 1F57; # GREEK CAPITAL LETTER UPSILON WITH DASIA AND PERISPOMENI
-1F68; C; 1F60; # GREEK CAPITAL LETTER OMEGA WITH PSILI
-1F69; C; 1F61; # GREEK CAPITAL LETTER OMEGA WITH DASIA
-1F6A; C; 1F62; # GREEK CAPITAL LETTER OMEGA WITH PSILI AND VARIA
-1F6B; C; 1F63; # GREEK CAPITAL LETTER OMEGA WITH DASIA AND VARIA
-1F6C; C; 1F64; # GREEK CAPITAL LETTER OMEGA WITH PSILI AND OXIA
-1F6D; C; 1F65; # GREEK CAPITAL LETTER OMEGA WITH DASIA AND OXIA
-1F6E; C; 1F66; # GREEK CAPITAL LETTER OMEGA WITH PSILI AND PERISPOMENI
-1F6F; C; 1F67; # GREEK CAPITAL LETTER OMEGA WITH DASIA AND PERISPOMENI
-1F80; F; 1F00 03B9; # GREEK SMALL LETTER ALPHA WITH PSILI AND YPOGEGRAMMENI
-1F81; F; 1F01 03B9; # GREEK SMALL LETTER ALPHA WITH DASIA AND YPOGEGRAMMENI
-1F82; F; 1F02 03B9; # GREEK SMALL LETTER ALPHA WITH PSILI AND VARIA AND YPOGEGRAMMENI
-1F83; F; 1F03 03B9; # GREEK SMALL LETTER ALPHA WITH DASIA AND VARIA AND YPOGEGRAMMENI
-1F84; F; 1F04 03B9; # GREEK SMALL LETTER ALPHA WITH PSILI AND OXIA AND YPOGEGRAMMENI
-1F85; F; 1F05 03B9; # GREEK SMALL LETTER ALPHA WITH DASIA AND OXIA AND YPOGEGRAMMENI
-1F86; F; 1F06 03B9; # GREEK SMALL LETTER ALPHA WITH PSILI AND PERISPOMENI AND YPOGEGRAMMENI
-1F87; F; 1F07 03B9; # GREEK SMALL LETTER ALPHA WITH DASIA AND PERISPOMENI AND YPOGEGRAMMENI
-1F88; F; 1F00 03B9; # GREEK CAPITAL LETTER ALPHA WITH PSILI AND PROSGEGRAMMENI
-1F88; S; 1F80; # GREEK CAPITAL LETTER ALPHA WITH PSILI AND PROSGEGRAMMENI
-1F89; F; 1F01 03B9; # GREEK CAPITAL LETTER ALPHA WITH DASIA AND PROSGEGRAMMENI
-1F89; S; 1F81; # GREEK CAPITAL LETTER ALPHA WITH DASIA AND PROSGEGRAMMENI
-1F8A; F; 1F02 03B9; # GREEK CAPITAL LETTER ALPHA WITH PSILI AND VARIA AND PROSGEGRAMMENI
-1F8A; S; 1F82; # GREEK CAPITAL LETTER ALPHA WITH PSILI AND VARIA AND PROSGEGRAMMENI
-1F8B; F; 1F03 03B9; # GREEK CAPITAL LETTER ALPHA WITH DASIA AND VARIA AND PROSGEGRAMMENI
-1F8B; S; 1F83; # GREEK CAPITAL LETTER ALPHA WITH DASIA AND VARIA AND PROSGEGRAMMENI
-1F8C; F; 1F04 03B9; # GREEK CAPITAL LETTER ALPHA WITH PSILI AND OXIA AND PROSGEGRAMMENI
-1F8C; S; 1F84; # GREEK CAPITAL LETTER ALPHA WITH PSILI AND OXIA AND PROSGEGRAMMENI
-1F8D; F; 1F05 03B9; # GREEK CAPITAL LETTER ALPHA WITH DASIA AND OXIA AND PROSGEGRAMMENI
-1F8D; S; 1F85; # GREEK CAPITAL LETTER ALPHA WITH DASIA AND OXIA AND PROSGEGRAMMENI
-1F8E; F; 1F06 03B9; # GREEK CAPITAL LETTER ALPHA WITH PSILI AND PERISPOMENI AND PROSGEGRAMMENI
-1F8E; S; 1F86; # GREEK CAPITAL LETTER ALPHA WITH PSILI AND PERISPOMENI AND PROSGEGRAMMENI
-1F8F; F; 1F07 03B9; # GREEK CAPITAL LETTER ALPHA WITH DASIA AND PERISPOMENI AND PROSGEGRAMMENI
-1F8F; S; 1F87; # GREEK CAPITAL LETTER ALPHA WITH DASIA AND PERISPOMENI AND PROSGEGRAMMENI
-1F90; F; 1F20 03B9; # GREEK SMALL LETTER ETA WITH PSILI AND YPOGEGRAMMENI
-1F91; F; 1F21 03B9; # GREEK SMALL LETTER ETA WITH DASIA AND YPOGEGRAMMENI
-1F92; F; 1F22 03B9; # GREEK SMALL LETTER ETA WITH PSILI AND VARIA AND YPOGEGRAMMENI
-1F93; F; 1F23 03B9; # GREEK SMALL LETTER ETA WITH DASIA AND VARIA AND YPOGEGRAMMENI
-1F94; F; 1F24 03B9; # GREEK SMALL LETTER ETA WITH PSILI AND OXIA AND YPOGEGRAMMENI
-1F95; F; 1F25 03B9; # GREEK SMALL LETTER ETA WITH DASIA AND OXIA AND YPOGEGRAMMENI
-1F96; F; 1F26 03B9; # GREEK SMALL LETTER ETA WITH PSILI AND PERISPOMENI AND YPOGEGRAMMENI
-1F97; F; 1F27 03B9; # GREEK SMALL LETTER ETA WITH DASIA AND PERISPOMENI AND YPOGEGRAMMENI
-1F98; F; 1F20 03B9; # GREEK CAPITAL LETTER ETA WITH PSILI AND PROSGEGRAMMENI
-1F98; S; 1F90; # GREEK CAPITAL LETTER ETA WITH PSILI AND PROSGEGRAMMENI
-1F99; F; 1F21 03B9; # GREEK CAPITAL LETTER ETA WITH DASIA AND PROSGEGRAMMENI
-1F99; S; 1F91; # GREEK CAPITAL LETTER ETA WITH DASIA AND PROSGEGRAMMENI
-1F9A; F; 1F22 03B9; # GREEK CAPITAL LETTER ETA WITH PSILI AND VARIA AND PROSGEGRAMMENI
-1F9A; S; 1F92; # GREEK CAPITAL LETTER ETA WITH PSILI AND VARIA AND PROSGEGRAMMENI
-1F9B; F; 1F23 03B9; # GREEK CAPITAL LETTER ETA WITH DASIA AND VARIA AND PROSGEGRAMMENI
-1F9B; S; 1F93; # GREEK CAPITAL LETTER ETA WITH DASIA AND VARIA AND PROSGEGRAMMENI
-1F9C; F; 1F24 03B9; # GREEK CAPITAL LETTER ETA WITH PSILI AND OXIA AND PROSGEGRAMMENI
-1F9C; S; 1F94; # GREEK CAPITAL LETTER ETA WITH PSILI AND OXIA AND PROSGEGRAMMENI
-1F9D; F; 1F25 03B9; # GREEK CAPITAL LETTER ETA WITH DASIA AND OXIA AND PROSGEGRAMMENI
-1F9D; S; 1F95; # GREEK CAPITAL LETTER ETA WITH DASIA AND OXIA AND PROSGEGRAMMENI
-1F9E; F; 1F26 03B9; # GREEK CAPITAL LETTER ETA WITH PSILI AND PERISPOMENI AND PROSGEGRAMMENI
-1F9E; S; 1F96; # GREEK CAPITAL LETTER ETA WITH PSILI AND PERISPOMENI AND PROSGEGRAMMENI
-1F9F; F; 1F27 03B9; # GREEK CAPITAL LETTER ETA WITH DASIA AND PERISPOMENI AND PROSGEGRAMMENI
-1F9F; S; 1F97; # GREEK CAPITAL LETTER ETA WITH DASIA AND PERISPOMENI AND PROSGEGRAMMENI
-1FA0; F; 1F60 03B9; # GREEK SMALL LETTER OMEGA WITH PSILI AND YPOGEGRAMMENI
-1FA1; F; 1F61 03B9; # GREEK SMALL LETTER OMEGA WITH DASIA AND YPOGEGRAMMENI
-1FA2; F; 1F62 03B9; # GREEK SMALL LETTER OMEGA WITH PSILI AND VARIA AND YPOGEGRAMMENI
-1FA3; F; 1F63 03B9; # GREEK SMALL LETTER OMEGA WITH DASIA AND VARIA AND YPOGEGRAMMENI
-1FA4; F; 1F64 03B9; # GREEK SMALL LETTER OMEGA WITH PSILI AND OXIA AND YPOGEGRAMMENI
-1FA5; F; 1F65 03B9; # GREEK SMALL LETTER OMEGA WITH DASIA AND OXIA AND YPOGEGRAMMENI
-1FA6; F; 1F66 03B9; # GREEK SMALL LETTER OMEGA WITH PSILI AND PERISPOMENI AND YPOGEGRAMMENI
-1FA7; F; 1F67 03B9; # GREEK SMALL LETTER OMEGA WITH DASIA AND PERISPOMENI AND YPOGEGRAMMENI
-1FA8; F; 1F60 03B9; # GREEK CAPITAL LETTER OMEGA WITH PSILI AND PROSGEGRAMMENI
-1FA8; S; 1FA0; # GREEK CAPITAL LETTER OMEGA WITH PSILI AND PROSGEGRAMMENI
-1FA9; F; 1F61 03B9; # GREEK CAPITAL LETTER OMEGA WITH DASIA AND PROSGEGRAMMENI
-1FA9; S; 1FA1; # GREEK CAPITAL LETTER OMEGA WITH DASIA AND PROSGEGRAMMENI
-1FAA; F; 1F62 03B9; # GREEK CAPITAL LETTER OMEGA WITH PSILI AND VARIA AND PROSGEGRAMMENI
-1FAA; S; 1FA2; # GREEK CAPITAL LETTER OMEGA WITH PSILI AND VARIA AND PROSGEGRAMMENI
-1FAB; F; 1F63 03B9; # GREEK CAPITAL LETTER OMEGA WITH DASIA AND VARIA AND PROSGEGRAMMENI
-1FAB; S; 1FA3; # GREEK CAPITAL LETTER OMEGA WITH DASIA AND VARIA AND PROSGEGRAMMENI
-1FAC; F; 1F64 03B9; # GREEK CAPITAL LETTER OMEGA WITH PSILI AND OXIA AND PROSGEGRAMMENI
-1FAC; S; 1FA4; # GREEK CAPITAL LETTER OMEGA WITH PSILI AND OXIA AND PROSGEGRAMMENI
-1FAD; F; 1F65 03B9; # GREEK CAPITAL LETTER OMEGA WITH DASIA AND OXIA AND PROSGEGRAMMENI
-1FAD; S; 1FA5; # GREEK CAPITAL LETTER OMEGA WITH DASIA AND OXIA AND PROSGEGRAMMENI
-1FAE; F; 1F66 03B9; # GREEK CAPITAL LETTER OMEGA WITH PSILI AND PERISPOMENI AND PROSGEGRAMMENI
-1FAE; S; 1FA6; # GREEK CAPITAL LETTER OMEGA WITH PSILI AND PERISPOMENI AND PROSGEGRAMMENI
-1FAF; F; 1F67 03B9; # GREEK CAPITAL LETTER OMEGA WITH DASIA AND PERISPOMENI AND PROSGEGRAMMENI
-1FAF; S; 1FA7; # GREEK CAPITAL LETTER OMEGA WITH DASIA AND PERISPOMENI AND PROSGEGRAMMENI
-1FB2; F; 1F70 03B9; # GREEK SMALL LETTER ALPHA WITH VARIA AND YPOGEGRAMMENI
-1FB3; F; 03B1 03B9; # GREEK SMALL LETTER ALPHA WITH YPOGEGRAMMENI
-1FB4; F; 03AC 03B9; # GREEK SMALL LETTER ALPHA WITH OXIA AND YPOGEGRAMMENI
-1FB6; F; 03B1 0342; # GREEK SMALL LETTER ALPHA WITH PERISPOMENI
-1FB7; F; 03B1 0342 03B9; # GREEK SMALL LETTER ALPHA WITH PERISPOMENI AND YPOGEGRAMMENI
-1FB8; C; 1FB0; # GREEK CAPITAL LETTER ALPHA WITH VRACHY
-1FB9; C; 1FB1; # GREEK CAPITAL LETTER ALPHA WITH MACRON
-1FBA; C; 1F70; # GREEK CAPITAL LETTER ALPHA WITH VARIA
-1FBB; C; 1F71; # GREEK CAPITAL LETTER ALPHA WITH OXIA
-1FBC; F; 03B1 03B9; # GREEK CAPITAL LETTER ALPHA WITH PROSGEGRAMMENI
-1FBC; S; 1FB3; # GREEK CAPITAL LETTER ALPHA WITH PROSGEGRAMMENI
-1FBE; C; 03B9; # GREEK PROSGEGRAMMENI
-1FC2; F; 1F74 03B9; # GREEK SMALL LETTER ETA WITH VARIA AND YPOGEGRAMMENI
-1FC3; F; 03B7 03B9; # GREEK SMALL LETTER ETA WITH YPOGEGRAMMENI
-1FC4; F; 03AE 03B9; # GREEK SMALL LETTER ETA WITH OXIA AND YPOGEGRAMMENI
-1FC6; F; 03B7 0342; # GREEK SMALL LETTER ETA WITH PERISPOMENI
-1FC7; F; 03B7 0342 03B9; # GREEK SMALL LETTER ETA WITH PERISPOMENI AND YPOGEGRAMMENI
-1FC8; C; 1F72; # GREEK CAPITAL LETTER EPSILON WITH VARIA
-1FC9; C; 1F73; # GREEK CAPITAL LETTER EPSILON WITH OXIA
-1FCA; C; 1F74; # GREEK CAPITAL LETTER ETA WITH VARIA
-1FCB; C; 1F75; # GREEK CAPITAL LETTER ETA WITH OXIA
-1FCC; F; 03B7 03B9; # GREEK CAPITAL LETTER ETA WITH PROSGEGRAMMENI
-1FCC; S; 1FC3; # GREEK CAPITAL LETTER ETA WITH PROSGEGRAMMENI
-1FD2; F; 03B9 0308 0300; # GREEK SMALL LETTER IOTA WITH DIALYTIKA AND VARIA
-1FD3; F; 03B9 0308 0301; # GREEK SMALL LETTER IOTA WITH DIALYTIKA AND OXIA
-1FD6; F; 03B9 0342; # GREEK SMALL LETTER IOTA WITH PERISPOMENI
-1FD7; F; 03B9 0308 0342; # GREEK SMALL LETTER IOTA WITH DIALYTIKA AND PERISPOMENI
-1FD8; C; 1FD0; # GREEK CAPITAL LETTER IOTA WITH VRACHY
-1FD9; C; 1FD1; # GREEK CAPITAL LETTER IOTA WITH MACRON
-1FDA; C; 1F76; # GREEK CAPITAL LETTER IOTA WITH VARIA
-1FDB; C; 1F77; # GREEK CAPITAL LETTER IOTA WITH OXIA
-1FE2; F; 03C5 0308 0300; # GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND VARIA
-1FE3; F; 03C5 0308 0301; # GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND OXIA
-1FE4; F; 03C1 0313; # GREEK SMALL LETTER RHO WITH PSILI
-1FE6; F; 03C5 0342; # GREEK SMALL LETTER UPSILON WITH PERISPOMENI
-1FE7; F; 03C5 0308 0342; # GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND PERISPOMENI
-1FE8; C; 1FE0; # GREEK CAPITAL LETTER UPSILON WITH VRACHY
-1FE9; C; 1FE1; # GREEK CAPITAL LETTER UPSILON WITH MACRON
-1FEA; C; 1F7A; # GREEK CAPITAL LETTER UPSILON WITH VARIA
-1FEB; C; 1F7B; # GREEK CAPITAL LETTER UPSILON WITH OXIA
-1FEC; C; 1FE5; # GREEK CAPITAL LETTER RHO WITH DASIA
-1FF2; F; 1F7C 03B9; # GREEK SMALL LETTER OMEGA WITH VARIA AND YPOGEGRAMMENI
-1FF3; F; 03C9 03B9; # GREEK SMALL LETTER OMEGA WITH YPOGEGRAMMENI
-1FF4; F; 03CE 03B9; # GREEK SMALL LETTER OMEGA WITH OXIA AND YPOGEGRAMMENI
-1FF6; F; 03C9 0342; # GREEK SMALL LETTER OMEGA WITH PERISPOMENI
-1FF7; F; 03C9 0342 03B9; # GREEK SMALL LETTER OMEGA WITH PERISPOMENI AND YPOGEGRAMMENI
-1FF8; C; 1F78; # GREEK CAPITAL LETTER OMICRON WITH VARIA
-1FF9; C; 1F79; # GREEK CAPITAL LETTER OMICRON WITH OXIA
-1FFA; C; 1F7C; # GREEK CAPITAL LETTER OMEGA WITH VARIA
-1FFB; C; 1F7D; # GREEK CAPITAL LETTER OMEGA WITH OXIA
-1FFC; F; 03C9 03B9; # GREEK CAPITAL LETTER OMEGA WITH PROSGEGRAMMENI
-1FFC; S; 1FF3; # GREEK CAPITAL LETTER OMEGA WITH PROSGEGRAMMENI
-2126; C; 03C9; # OHM SIGN
-212A; C; 006B; # KELVIN SIGN
-212B; C; 00E5; # ANGSTROM SIGN
-2132; C; 214E; # TURNED CAPITAL F
-2160; C; 2170; # ROMAN NUMERAL ONE
-2161; C; 2171; # ROMAN NUMERAL TWO
-2162; C; 2172; # ROMAN NUMERAL THREE
-2163; C; 2173; # ROMAN NUMERAL FOUR
-2164; C; 2174; # ROMAN NUMERAL FIVE
-2165; C; 2175; # ROMAN NUMERAL SIX
-2166; C; 2176; # ROMAN NUMERAL SEVEN
-2167; C; 2177; # ROMAN NUMERAL EIGHT
-2168; C; 2178; # ROMAN NUMERAL NINE
-2169; C; 2179; # ROMAN NUMERAL TEN
-216A; C; 217A; # ROMAN NUMERAL ELEVEN
-216B; C; 217B; # ROMAN NUMERAL TWELVE
-216C; C; 217C; # ROMAN NUMERAL FIFTY
-216D; C; 217D; # ROMAN NUMERAL ONE HUNDRED
-216E; C; 217E; # ROMAN NUMERAL FIVE HUNDRED
-216F; C; 217F; # ROMAN NUMERAL ONE THOUSAND
-2183; C; 2184; # ROMAN NUMERAL REVERSED ONE HUNDRED
-24B6; C; 24D0; # CIRCLED LATIN CAPITAL LETTER A
-24B7; C; 24D1; # CIRCLED LATIN CAPITAL LETTER B
-24B8; C; 24D2; # CIRCLED LATIN CAPITAL LETTER C
-24B9; C; 24D3; # CIRCLED LATIN CAPITAL LETTER D
-24BA; C; 24D4; # CIRCLED LATIN CAPITAL LETTER E
-24BB; C; 24D5; # CIRCLED LATIN CAPITAL LETTER F
-24BC; C; 24D6; # CIRCLED LATIN CAPITAL LETTER G
-24BD; C; 24D7; # CIRCLED LATIN CAPITAL LETTER H
-24BE; C; 24D8; # CIRCLED LATIN CAPITAL LETTER I
-24BF; C; 24D9; # CIRCLED LATIN CAPITAL LETTER J
-24C0; C; 24DA; # CIRCLED LATIN CAPITAL LETTER K
-24C1; C; 24DB; # CIRCLED LATIN CAPITAL LETTER L
-24C2; C; 24DC; # CIRCLED LATIN CAPITAL LETTER M
-24C3; C; 24DD; # CIRCLED LATIN CAPITAL LETTER N
-24C4; C; 24DE; # CIRCLED LATIN CAPITAL LETTER O
-24C5; C; 24DF; # CIRCLED LATIN CAPITAL LETTER P
-24C6; C; 24E0; # CIRCLED LATIN CAPITAL LETTER Q
-24C7; C; 24E1; # CIRCLED LATIN CAPITAL LETTER R
-24C8; C; 24E2; # CIRCLED LATIN CAPITAL LETTER S
-24C9; C; 24E3; # CIRCLED LATIN CAPITAL LETTER T
-24CA; C; 24E4; # CIRCLED LATIN CAPITAL LETTER U
-24CB; C; 24E5; # CIRCLED LATIN CAPITAL LETTER V
-24CC; C; 24E6; # CIRCLED LATIN CAPITAL LETTER W
-24CD; C; 24E7; # CIRCLED LATIN CAPITAL LETTER X
-24CE; C; 24E8; # CIRCLED LATIN CAPITAL LETTER Y
-24CF; C; 24E9; # CIRCLED LATIN CAPITAL LETTER Z
-2C00; C; 2C30; # GLAGOLITIC CAPITAL LETTER AZU
-2C01; C; 2C31; # GLAGOLITIC CAPITAL LETTER BUKY
-2C02; C; 2C32; # GLAGOLITIC CAPITAL LETTER VEDE
-2C03; C; 2C33; # GLAGOLITIC CAPITAL LETTER GLAGOLI
-2C04; C; 2C34; # GLAGOLITIC CAPITAL LETTER DOBRO
-2C05; C; 2C35; # GLAGOLITIC CAPITAL LETTER YESTU
-2C06; C; 2C36; # GLAGOLITIC CAPITAL LETTER ZHIVETE
-2C07; C; 2C37; # GLAGOLITIC CAPITAL LETTER DZELO
-2C08; C; 2C38; # GLAGOLITIC CAPITAL LETTER ZEMLJA
-2C09; C; 2C39; # GLAGOLITIC CAPITAL LETTER IZHE
-2C0A; C; 2C3A; # GLAGOLITIC CAPITAL LETTER INITIAL IZHE
-2C0B; C; 2C3B; # GLAGOLITIC CAPITAL LETTER I
-2C0C; C; 2C3C; # GLAGOLITIC CAPITAL LETTER DJERVI
-2C0D; C; 2C3D; # GLAGOLITIC CAPITAL LETTER KAKO
-2C0E; C; 2C3E; # GLAGOLITIC CAPITAL LETTER LJUDIJE
-2C0F; C; 2C3F; # GLAGOLITIC CAPITAL LETTER MYSLITE
-2C10; C; 2C40; # GLAGOLITIC CAPITAL LETTER NASHI
-2C11; C; 2C41; # GLAGOLITIC CAPITAL LETTER ONU
-2C12; C; 2C42; # GLAGOLITIC CAPITAL LETTER POKOJI
-2C13; C; 2C43; # GLAGOLITIC CAPITAL LETTER RITSI
-2C14; C; 2C44; # GLAGOLITIC CAPITAL LETTER SLOVO
-2C15; C; 2C45; # GLAGOLITIC CAPITAL LETTER TVRIDO
-2C16; C; 2C46; # GLAGOLITIC CAPITAL LETTER UKU
-2C17; C; 2C47; # GLAGOLITIC CAPITAL LETTER FRITU
-2C18; C; 2C48; # GLAGOLITIC CAPITAL LETTER HERU
-2C19; C; 2C49; # GLAGOLITIC CAPITAL LETTER OTU
-2C1A; C; 2C4A; # GLAGOLITIC CAPITAL LETTER PE
-2C1B; C; 2C4B; # GLAGOLITIC CAPITAL LETTER SHTA
-2C1C; C; 2C4C; # GLAGOLITIC CAPITAL LETTER TSI
-2C1D; C; 2C4D; # GLAGOLITIC CAPITAL LETTER CHRIVI
-2C1E; C; 2C4E; # GLAGOLITIC CAPITAL LETTER SHA
-2C1F; C; 2C4F; # GLAGOLITIC CAPITAL LETTER YERU
-2C20; C; 2C50; # GLAGOLITIC CAPITAL LETTER YERI
-2C21; C; 2C51; # GLAGOLITIC CAPITAL LETTER YATI
-2C22; C; 2C52; # GLAGOLITIC CAPITAL LETTER SPIDERY HA
-2C23; C; 2C53; # GLAGOLITIC CAPITAL LETTER YU
-2C24; C; 2C54; # GLAGOLITIC CAPITAL LETTER SMALL YUS
-2C25; C; 2C55; # GLAGOLITIC CAPITAL LETTER SMALL YUS WITH TAIL
-2C26; C; 2C56; # GLAGOLITIC CAPITAL LETTER YO
-2C27; C; 2C57; # GLAGOLITIC CAPITAL LETTER IOTATED SMALL YUS
-2C28; C; 2C58; # GLAGOLITIC CAPITAL LETTER BIG YUS
-2C29; C; 2C59; # GLAGOLITIC CAPITAL LETTER IOTATED BIG YUS
-2C2A; C; 2C5A; # GLAGOLITIC CAPITAL LETTER FITA
-2C2B; C; 2C5B; # GLAGOLITIC CAPITAL LETTER IZHITSA
-2C2C; C; 2C5C; # GLAGOLITIC CAPITAL LETTER SHTAPIC
-2C2D; C; 2C5D; # GLAGOLITIC CAPITAL LETTER TROKUTASTI A
-2C2E; C; 2C5E; # GLAGOLITIC CAPITAL LETTER LATINATE MYSLITE
-2C60; C; 2C61; # LATIN CAPITAL LETTER L WITH DOUBLE BAR
-2C62; C; 026B; # LATIN CAPITAL LETTER L WITH MIDDLE TILDE
-2C63; C; 1D7D; # LATIN CAPITAL LETTER P WITH STROKE
-2C64; C; 027D; # LATIN CAPITAL LETTER R WITH TAIL
-2C67; C; 2C68; # LATIN CAPITAL LETTER H WITH DESCENDER
-2C69; C; 2C6A; # LATIN CAPITAL LETTER K WITH DESCENDER
-2C6B; C; 2C6C; # LATIN CAPITAL LETTER Z WITH DESCENDER
-2C6D; C; 0251; # LATIN CAPITAL LETTER ALPHA
-2C6E; C; 0271; # LATIN CAPITAL LETTER M WITH HOOK
-2C6F; C; 0250; # LATIN CAPITAL LETTER TURNED A
-2C70; C; 0252; # LATIN CAPITAL LETTER TURNED ALPHA
-2C72; C; 2C73; # LATIN CAPITAL LETTER W WITH HOOK
-2C75; C; 2C76; # LATIN CAPITAL LETTER HALF H
-2C7E; C; 023F; # LATIN CAPITAL LETTER S WITH SWASH TAIL
-2C7F; C; 0240; # LATIN CAPITAL LETTER Z WITH SWASH TAIL
-2C80; C; 2C81; # COPTIC CAPITAL LETTER ALFA
-2C82; C; 2C83; # COPTIC CAPITAL LETTER VIDA
-2C84; C; 2C85; # COPTIC CAPITAL LETTER GAMMA
-2C86; C; 2C87; # COPTIC CAPITAL LETTER DALDA
-2C88; C; 2C89; # COPTIC CAPITAL LETTER EIE
-2C8A; C; 2C8B; # COPTIC CAPITAL LETTER SOU
-2C8C; C; 2C8D; # COPTIC CAPITAL LETTER ZATA
-2C8E; C; 2C8F; # COPTIC CAPITAL LETTER HATE
-2C90; C; 2C91; # COPTIC CAPITAL LETTER THETHE
-2C92; C; 2C93; # COPTIC CAPITAL LETTER IAUDA
-2C94; C; 2C95; # COPTIC CAPITAL LETTER KAPA
-2C96; C; 2C97; # COPTIC CAPITAL LETTER LAULA
-2C98; C; 2C99; # COPTIC CAPITAL LETTER MI
-2C9A; C; 2C9B; # COPTIC CAPITAL LETTER NI
-2C9C; C; 2C9D; # COPTIC CAPITAL LETTER KSI
-2C9E; C; 2C9F; # COPTIC CAPITAL LETTER O
-2CA0; C; 2CA1; # COPTIC CAPITAL LETTER PI
-2CA2; C; 2CA3; # COPTIC CAPITAL LETTER RO
-2CA4; C; 2CA5; # COPTIC CAPITAL LETTER SIMA
-2CA6; C; 2CA7; # COPTIC CAPITAL LETTER TAU
-2CA8; C; 2CA9; # COPTIC CAPITAL LETTER UA
-2CAA; C; 2CAB; # COPTIC CAPITAL LETTER FI
-2CAC; C; 2CAD; # COPTIC CAPITAL LETTER KHI
-2CAE; C; 2CAF; # COPTIC CAPITAL LETTER PSI
-2CB0; C; 2CB1; # COPTIC CAPITAL LETTER OOU
-2CB2; C; 2CB3; # COPTIC CAPITAL LETTER DIALECT-P ALEF
-2CB4; C; 2CB5; # COPTIC CAPITAL LETTER OLD COPTIC AIN
-2CB6; C; 2CB7; # COPTIC CAPITAL LETTER CRYPTOGRAMMIC EIE
-2CB8; C; 2CB9; # COPTIC CAPITAL LETTER DIALECT-P KAPA
-2CBA; C; 2CBB; # COPTIC CAPITAL LETTER DIALECT-P NI
-2CBC; C; 2CBD; # COPTIC CAPITAL LETTER CRYPTOGRAMMIC NI
-2CBE; C; 2CBF; # COPTIC CAPITAL LETTER OLD COPTIC OOU
-2CC0; C; 2CC1; # COPTIC CAPITAL LETTER SAMPI
-2CC2; C; 2CC3; # COPTIC CAPITAL LETTER CROSSED SHEI
-2CC4; C; 2CC5; # COPTIC CAPITAL LETTER OLD COPTIC SHEI
-2CC6; C; 2CC7; # COPTIC CAPITAL LETTER OLD COPTIC ESH
-2CC8; C; 2CC9; # COPTIC CAPITAL LETTER AKHMIMIC KHEI
-2CCA; C; 2CCB; # COPTIC CAPITAL LETTER DIALECT-P HORI
-2CCC; C; 2CCD; # COPTIC CAPITAL LETTER OLD COPTIC HORI
-2CCE; C; 2CCF; # COPTIC CAPITAL LETTER OLD COPTIC HA
-2CD0; C; 2CD1; # COPTIC CAPITAL LETTER L-SHAPED HA
-2CD2; C; 2CD3; # COPTIC CAPITAL LETTER OLD COPTIC HEI
-2CD4; C; 2CD5; # COPTIC CAPITAL LETTER OLD COPTIC HAT
-2CD6; C; 2CD7; # COPTIC CAPITAL LETTER OLD COPTIC GANGIA
-2CD8; C; 2CD9; # COPTIC CAPITAL LETTER OLD COPTIC DJA
-2CDA; C; 2CDB; # COPTIC CAPITAL LETTER OLD COPTIC SHIMA
-2CDC; C; 2CDD; # COPTIC CAPITAL LETTER OLD NUBIAN SHIMA
-2CDE; C; 2CDF; # COPTIC CAPITAL LETTER OLD NUBIAN NGI
-2CE0; C; 2CE1; # COPTIC CAPITAL LETTER OLD NUBIAN NYI
-2CE2; C; 2CE3; # COPTIC CAPITAL LETTER OLD NUBIAN WAU
-2CEB; C; 2CEC; # COPTIC CAPITAL LETTER CRYPTOGRAMMIC SHEI
-2CED; C; 2CEE; # COPTIC CAPITAL LETTER CRYPTOGRAMMIC GANGIA
-2CF2; C; 2CF3; # COPTIC CAPITAL LETTER BOHAIRIC KHEI
-A640; C; A641; # CYRILLIC CAPITAL LETTER ZEMLYA
-A642; C; A643; # CYRILLIC CAPITAL LETTER DZELO
-A644; C; A645; # CYRILLIC CAPITAL LETTER REVERSED DZE
-A646; C; A647; # CYRILLIC CAPITAL LETTER IOTA
-A648; C; A649; # CYRILLIC CAPITAL LETTER DJERV
-A64A; C; A64B; # CYRILLIC CAPITAL LETTER MONOGRAPH UK
-A64C; C; A64D; # CYRILLIC CAPITAL LETTER BROAD OMEGA
-A64E; C; A64F; # CYRILLIC CAPITAL LETTER NEUTRAL YER
-A650; C; A651; # CYRILLIC CAPITAL LETTER YERU WITH BACK YER
-A652; C; A653; # CYRILLIC CAPITAL LETTER IOTIFIED YAT
-A654; C; A655; # CYRILLIC CAPITAL LETTER REVERSED YU
-A656; C; A657; # CYRILLIC CAPITAL LETTER IOTIFIED A
-A658; C; A659; # CYRILLIC CAPITAL LETTER CLOSED LITTLE YUS
-A65A; C; A65B; # CYRILLIC CAPITAL LETTER BLENDED YUS
-A65C; C; A65D; # CYRILLIC CAPITAL LETTER IOTIFIED CLOSED LITTLE YUS
-A65E; C; A65F; # CYRILLIC CAPITAL LETTER YN
-A660; C; A661; # CYRILLIC CAPITAL LETTER REVERSED TSE
-A662; C; A663; # CYRILLIC CAPITAL LETTER SOFT DE
-A664; C; A665; # CYRILLIC CAPITAL LETTER SOFT EL
-A666; C; A667; # CYRILLIC CAPITAL LETTER SOFT EM
-A668; C; A669; # CYRILLIC CAPITAL LETTER MONOCULAR O
-A66A; C; A66B; # CYRILLIC CAPITAL LETTER BINOCULAR O
-A66C; C; A66D; # CYRILLIC CAPITAL LETTER DOUBLE MONOCULAR O
-A680; C; A681; # CYRILLIC CAPITAL LETTER DWE
-A682; C; A683; # CYRILLIC CAPITAL LETTER DZWE
-A684; C; A685; # CYRILLIC CAPITAL LETTER ZHWE
-A686; C; A687; # CYRILLIC CAPITAL LETTER CCHE
-A688; C; A689; # CYRILLIC CAPITAL LETTER DZZE
-A68A; C; A68B; # CYRILLIC CAPITAL LETTER TE WITH MIDDLE HOOK
-A68C; C; A68D; # CYRILLIC CAPITAL LETTER TWE
-A68E; C; A68F; # CYRILLIC CAPITAL LETTER TSWE
-A690; C; A691; # CYRILLIC CAPITAL LETTER TSSE
-A692; C; A693; # CYRILLIC CAPITAL LETTER TCHE
-A694; C; A695; # CYRILLIC CAPITAL LETTER HWE
-A696; C; A697; # CYRILLIC CAPITAL LETTER SHWE
-A722; C; A723; # LATIN CAPITAL LETTER EGYPTOLOGICAL ALEF
-A724; C; A725; # LATIN CAPITAL LETTER EGYPTOLOGICAL AIN
-A726; C; A727; # LATIN CAPITAL LETTER HENG
-A728; C; A729; # LATIN CAPITAL LETTER TZ
-A72A; C; A72B; # LATIN CAPITAL LETTER TRESILLO
-A72C; C; A72D; # LATIN CAPITAL LETTER CUATRILLO
-A72E; C; A72F; # LATIN CAPITAL LETTER CUATRILLO WITH COMMA
-A732; C; A733; # LATIN CAPITAL LETTER AA
-A734; C; A735; # LATIN CAPITAL LETTER AO
-A736; C; A737; # LATIN CAPITAL LETTER AU
-A738; C; A739; # LATIN CAPITAL LETTER AV
-A73A; C; A73B; # LATIN CAPITAL LETTER AV WITH HORIZONTAL BAR
-A73C; C; A73D; # LATIN CAPITAL LETTER AY
-A73E; C; A73F; # LATIN CAPITAL LETTER REVERSED C WITH DOT
-A740; C; A741; # LATIN CAPITAL LETTER K WITH STROKE
-A742; C; A743; # LATIN CAPITAL LETTER K WITH DIAGONAL STROKE
-A744; C; A745; # LATIN CAPITAL LETTER K WITH STROKE AND DIAGONAL STROKE
-A746; C; A747; # LATIN CAPITAL LETTER BROKEN L
-A748; C; A749; # LATIN CAPITAL LETTER L WITH HIGH STROKE
-A74A; C; A74B; # LATIN CAPITAL LETTER O WITH LONG STROKE OVERLAY
-A74C; C; A74D; # LATIN CAPITAL LETTER O WITH LOOP
-A74E; C; A74F; # LATIN CAPITAL LETTER OO
-A750; C; A751; # LATIN CAPITAL LETTER P WITH STROKE THROUGH DESCENDER
-A752; C; A753; # LATIN CAPITAL LETTER P WITH FLOURISH
-A754; C; A755; # LATIN CAPITAL LETTER P WITH SQUIRREL TAIL
-A756; C; A757; # LATIN CAPITAL LETTER Q WITH STROKE THROUGH DESCENDER
-A758; C; A759; # LATIN CAPITAL LETTER Q WITH DIAGONAL STROKE
-A75A; C; A75B; # LATIN CAPITAL LETTER R ROTUNDA
-A75C; C; A75D; # LATIN CAPITAL LETTER RUM ROTUNDA
-A75E; C; A75F; # LATIN CAPITAL LETTER V WITH DIAGONAL STROKE
-A760; C; A761; # LATIN CAPITAL LETTER VY
-A762; C; A763; # LATIN CAPITAL LETTER VISIGOTHIC Z
-A764; C; A765; # LATIN CAPITAL LETTER THORN WITH STROKE
-A766; C; A767; # LATIN CAPITAL LETTER THORN WITH STROKE THROUGH DESCENDER
-A768; C; A769; # LATIN CAPITAL LETTER VEND
-A76A; C; A76B; # LATIN CAPITAL LETTER ET
-A76C; C; A76D; # LATIN CAPITAL LETTER IS
-A76E; C; A76F; # LATIN CAPITAL LETTER CON
-A779; C; A77A; # LATIN CAPITAL LETTER INSULAR D
-A77B; C; A77C; # LATIN CAPITAL LETTER INSULAR F
-A77D; C; 1D79; # LATIN CAPITAL LETTER INSULAR G
-A77E; C; A77F; # LATIN CAPITAL LETTER TURNED INSULAR G
-A780; C; A781; # LATIN CAPITAL LETTER TURNED L
-A782; C; A783; # LATIN CAPITAL LETTER INSULAR R
-A784; C; A785; # LATIN CAPITAL LETTER INSULAR S
-A786; C; A787; # LATIN CAPITAL LETTER INSULAR T
-A78B; C; A78C; # LATIN CAPITAL LETTER SALTILLO
-A78D; C; 0265; # LATIN CAPITAL LETTER TURNED H
-A790; C; A791; # LATIN CAPITAL LETTER N WITH DESCENDER
-A792; C; A793; # LATIN CAPITAL LETTER C WITH BAR
-A7A0; C; A7A1; # LATIN CAPITAL LETTER G WITH OBLIQUE STROKE
-A7A2; C; A7A3; # LATIN CAPITAL LETTER K WITH OBLIQUE STROKE
-A7A4; C; A7A5; # LATIN CAPITAL LETTER N WITH OBLIQUE STROKE
-A7A6; C; A7A7; # LATIN CAPITAL LETTER R WITH OBLIQUE STROKE
-A7A8; C; A7A9; # LATIN CAPITAL LETTER S WITH OBLIQUE STROKE
-A7AA; C; 0266; # LATIN CAPITAL LETTER H WITH HOOK
-FB00; F; 0066 0066; # LATIN SMALL LIGATURE FF
-FB01; F; 0066 0069; # LATIN SMALL LIGATURE FI
-FB02; F; 0066 006C; # LATIN SMALL LIGATURE FL
-FB03; F; 0066 0066 0069; # LATIN SMALL LIGATURE FFI
-FB04; F; 0066 0066 006C; # LATIN SMALL LIGATURE FFL
-FB05; F; 0073 0074; # LATIN SMALL LIGATURE LONG S T
-FB06; F; 0073 0074; # LATIN SMALL LIGATURE ST
-FB13; F; 0574 0576; # ARMENIAN SMALL LIGATURE MEN NOW
-FB14; F; 0574 0565; # ARMENIAN SMALL LIGATURE MEN ECH
-FB15; F; 0574 056B; # ARMENIAN SMALL LIGATURE MEN INI
-FB16; F; 057E 0576; # ARMENIAN SMALL LIGATURE VEW NOW
-FB17; F; 0574 056D; # ARMENIAN SMALL LIGATURE MEN XEH
-FF21; C; FF41; # FULLWIDTH LATIN CAPITAL LETTER A
-FF22; C; FF42; # FULLWIDTH LATIN CAPITAL LETTER B
-FF23; C; FF43; # FULLWIDTH LATIN CAPITAL LETTER C
-FF24; C; FF44; # FULLWIDTH LATIN CAPITAL LETTER D
-FF25; C; FF45; # FULLWIDTH LATIN CAPITAL LETTER E
-FF26; C; FF46; # FULLWIDTH LATIN CAPITAL LETTER F
-FF27; C; FF47; # FULLWIDTH LATIN CAPITAL LETTER G
-FF28; C; FF48; # FULLWIDTH LATIN CAPITAL LETTER H
-FF29; C; FF49; # FULLWIDTH LATIN CAPITAL LETTER I
-FF2A; C; FF4A; # FULLWIDTH LATIN CAPITAL LETTER J
-FF2B; C; FF4B; # FULLWIDTH LATIN CAPITAL LETTER K
-FF2C; C; FF4C; # FULLWIDTH LATIN CAPITAL LETTER L
-FF2D; C; FF4D; # FULLWIDTH LATIN CAPITAL LETTER M
-FF2E; C; FF4E; # FULLWIDTH LATIN CAPITAL LETTER N
-FF2F; C; FF4F; # FULLWIDTH LATIN CAPITAL LETTER O
-FF30; C; FF50; # FULLWIDTH LATIN CAPITAL LETTER P
-FF31; C; FF51; # FULLWIDTH LATIN CAPITAL LETTER Q
-FF32; C; FF52; # FULLWIDTH LATIN CAPITAL LETTER R
-FF33; C; FF53; # FULLWIDTH LATIN CAPITAL LETTER S
-FF34; C; FF54; # FULLWIDTH LATIN CAPITAL LETTER T
-FF35; C; FF55; # FULLWIDTH LATIN CAPITAL LETTER U
-FF36; C; FF56; # FULLWIDTH LATIN CAPITAL LETTER V
-FF37; C; FF57; # FULLWIDTH LATIN CAPITAL LETTER W
-FF38; C; FF58; # FULLWIDTH LATIN CAPITAL LETTER X
-FF39; C; FF59; # FULLWIDTH LATIN CAPITAL LETTER Y
-FF3A; C; FF5A; # FULLWIDTH LATIN CAPITAL LETTER Z
-10400; C; 10428; # DESERET CAPITAL LETTER LONG I
-10401; C; 10429; # DESERET CAPITAL LETTER LONG E
-10402; C; 1042A; # DESERET CAPITAL LETTER LONG A
-10403; C; 1042B; # DESERET CAPITAL LETTER LONG AH
-10404; C; 1042C; # DESERET CAPITAL LETTER LONG O
-10405; C; 1042D; # DESERET CAPITAL LETTER LONG OO
-10406; C; 1042E; # DESERET CAPITAL LETTER SHORT I
-10407; C; 1042F; # DESERET CAPITAL LETTER SHORT E
-10408; C; 10430; # DESERET CAPITAL LETTER SHORT A
-10409; C; 10431; # DESERET CAPITAL LETTER SHORT AH
-1040A; C; 10432; # DESERET CAPITAL LETTER SHORT O
-1040B; C; 10433; # DESERET CAPITAL LETTER SHORT OO
-1040C; C; 10434; # DESERET CAPITAL LETTER AY
-1040D; C; 10435; # DESERET CAPITAL LETTER OW
-1040E; C; 10436; # DESERET CAPITAL LETTER WU
-1040F; C; 10437; # DESERET CAPITAL LETTER YEE
-10410; C; 10438; # DESERET CAPITAL LETTER H
-10411; C; 10439; # DESERET CAPITAL LETTER PEE
-10412; C; 1043A; # DESERET CAPITAL LETTER BEE
-10413; C; 1043B; # DESERET CAPITAL LETTER TEE
-10414; C; 1043C; # DESERET CAPITAL LETTER DEE
-10415; C; 1043D; # DESERET CAPITAL LETTER CHEE
-10416; C; 1043E; # DESERET CAPITAL LETTER JEE
-10417; C; 1043F; # DESERET CAPITAL LETTER KAY
-10418; C; 10440; # DESERET CAPITAL LETTER GAY
-10419; C; 10441; # DESERET CAPITAL LETTER EF
-1041A; C; 10442; # DESERET CAPITAL LETTER VEE
-1041B; C; 10443; # DESERET CAPITAL LETTER ETH
-1041C; C; 10444; # DESERET CAPITAL LETTER THEE
-1041D; C; 10445; # DESERET CAPITAL LETTER ES
-1041E; C; 10446; # DESERET CAPITAL LETTER ZEE
-1041F; C; 10447; # DESERET CAPITAL LETTER ESH
-10420; C; 10448; # DESERET CAPITAL LETTER ZHEE
-10421; C; 10449; # DESERET CAPITAL LETTER ER
-10422; C; 1044A; # DESERET CAPITAL LETTER EL
-10423; C; 1044B; # DESERET CAPITAL LETTER EM
-10424; C; 1044C; # DESERET CAPITAL LETTER EN
-10425; C; 1044D; # DESERET CAPITAL LETTER ENG
-10426; C; 1044E; # DESERET CAPITAL LETTER OI
-10427; C; 1044F; # DESERET CAPITAL LETTER EW
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Dt/None.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Dt/None.pl
deleted file mode 100644
index 12913a53b1a..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Dt/None.pl
+++ /dev/null
@@ -1,397 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0000 009F
-00A1 00A7
-00A9
-00AB 00AE
-00B0 00B1
-00B6 00B7
-00BB
-00BF
-00C6
-00D0
-00D7 00D8
-00DE 00DF
-00E6
-00F0
-00F7 00F8
-00FE
-0110 0111
-0126 0127
-0131
-0138
-0141 0142
-014A 014B
-0152 0153
-0166 0167
-0180 019F
-01A2 01AE
-01B1 01C3
-01DD
-01E4 01E5
-01F6 01F7
-021C 021D
-0220 0225
-0234 02AF
-02B9 02D7
-02DE 02DF
-02E5 033F
-0342
-0345 0373
-0375 0379
-037B 037D
-037F 0383
-038B
-038D
-0391 03A9
-03B1 03C9
-03CF
-03D7 03EF
-03F3
-03F6 03F8
-03FA 03FF
-0402
-0404 0406
-0408 040B
-040F 0418
-041A 0438
-043A 044F
-0452
-0454 0456
-0458 045B
-045F 0475
-0478 04C0
-04C3 04CF
-04D4 04D5
-04D8 04D9
-04E0 04E1
-04E8 04E9
-04F6 04F7
-04FA 0586
-0588 0621
-0627 0674
-0679 06BF
-06C1
-06C3 06D2
-06D4 0928
-092A 0930
-0932 0933
-0935 0957
-0960 09CA
-09CD 09DB
-09DE
-09E0 0A32
-0A34 0A35
-0A37 0A58
-0A5C 0A5D
-0A5F 0B47
-0B49 0B4A
-0B4D 0B5B
-0B5E 0B93
-0B95 0BC9
-0BCD 0C47
-0C49 0CBF
-0CC1 0CC6
-0CC9
-0CCC 0D49
-0D4D 0DD9
-0DDB
-0DDF 0E32
-0E34 0EB2
-0EB4 0EDB
-0EDE 0F0B
-0F0D 0F42
-0F44 0F4C
-0F4E 0F51
-0F53 0F56
-0F58 0F5B
-0F5D 0F68
-0F6A 0F72
-0F74
-0F7A 0F80
-0F82 0F92
-0F94 0F9C
-0F9E 0FA1
-0FA3 0FA6
-0FA8 0FAB
-0FAD 0FB8
-0FBA 1025
-1027 10FB
-10FD 1B05
-1B07
-1B09
-1B0B
-1B0D
-1B0F 1B11
-1B13 1B3A
-1B3C
-1B3E 1B3F
-1B42
-1B44 1D2B
-1D2F
-1D3B
-1D4E
-1D6B 1D77
-1D79 1D9A
-1DC0 1DFF
-1E9C 1E9F
-1EFA 1EFF
-1F16 1F17
-1F1E 1F1F
-1F46 1F47
-1F4E 1F4F
-1F58
-1F5A
-1F5C
-1F5E
-1F7E 1F7F
-1FB5
-1FC5
-1FD4 1FD5
-1FDC
-1FF0 1FF1
-1FF5
-1FFF
-200B 2010
-2012 2016
-2018 2023
-2027 202E
-2030 2032
-2035
-2038 203B
-203D
-203F 2046
-204A 2056
-2058 205E
-2060 206F
-2072 2073
-208F
-209D 20A7
-20A9 20FF
-2104
-2108
-2114
-2117 2118
-211E 211F
-2123
-2125
-2127
-2129
-212E
-2132
-213A
-2141 2144
-214A 214F
-2180 2188
-218A 2199
-219C 21AD
-21AF 21CC
-21D0 2203
-2205 2208
-220A 220B
-220D 2223
-2225
-2227 222B
-222E
-2231 2240
-2242 2243
-2245 2246
-2248
-224A 225F
-2261
-2263 226C
-2272 2273
-2276 2277
-227A 227F
-2282 2283
-2286 2287
-228A 22AB
-22B0 22DF
-22E4 22E9
-22EE 2328
-232B 245F
-24EB 2A0B
-2A0D 2A73
-2A77 2ADB
-2ADD 2C7B
-2C7E 2D6E
-2D70 2E9E
-2EA0 2EF2
-2EF4 2EFF
-2FD6 2FFF
-3001 3035
-3037
-303B 304B
-304D
-304F
-3051
-3053
-3055
-3057
-3059
-305B
-305D
-305F
-3061
-3063 3064
-3066
-3068
-306A 306F
-3072
-3075
-3078
-307B
-307E 3093
-3095 309A
-309D
-30A0 30AB
-30AD
-30AF
-30B1
-30B3
-30B5
-30B7
-30B9
-30BB
-30BD
-30BF
-30C1
-30C3 30C4
-30C6
-30C8
-30CA 30CF
-30D2
-30D5
-30D8
-30DB
-30DE 30F3
-30F5 30F6
-30FB 30FD
-3100 3130
-318F 3191
-31A0 31FF
-321F
-3248 324F
-327F
-32FF
-3400 A76F
-A771 A7F7
-A7FA ABFF
-D7A4 F8FF
-FA0E FA0F
-FA11
-FA13 FA14
-FA1F
-FA21
-FA23 FA24
-FA27 FA29
-FA6E FA6F
-FADA FAFF
-FB07 FB12
-FB18 FB1C
-FB1E
-FB37
-FB3D
-FB3F
-FB42
-FB45
-FBB2 FBD2
-FD3E FD4F
-FD90 FD91
-FDC8 FDEF
-FDFD FE0F
-FE1A FE2F
-FE45 FE46
-FE53
-FE67
-FE6C FE6F
-FE73
-FE75
-FEFD FF00
-FFBF FFC1
-FFC8 FFC9
-FFD0 FFD1
-FFD8 FFD9
-FFDD FFDF
-FFE7
-FFEF 11099
-1109B
-1109D 110AA
-110AC 1112D
-11130 1D15D
-1D165 1D1BA
-1D1C1 1D3FF
-1D455
-1D49D
-1D4A0 1D4A1
-1D4A3 1D4A4
-1D4A7 1D4A8
-1D4AD
-1D4BA
-1D4BC
-1D4C4
-1D506
-1D50B 1D50C
-1D515
-1D51D
-1D53A
-1D53F
-1D545
-1D547 1D549
-1D551
-1D6A6 1D6A7
-1D7CC 1D7CD
-1D800 1EDFF
-1EE04
-1EE20
-1EE23
-1EE25 1EE26
-1EE28
-1EE33
-1EE38
-1EE3A
-1EE3C 1EE41
-1EE43 1EE46
-1EE48
-1EE4A
-1EE4C
-1EE50
-1EE53
-1EE55 1EE56
-1EE58
-1EE5A
-1EE5C
-1EE5E
-1EE60
-1EE63
-1EE65 1EE66
-1EE6B
-1EE73
-1EE78
-1EE7D
-1EE7F
-1EE8A
-1EE9C 1EEA0
-1EEA4
-1EEAA
-1EEBC 1F0FF
-1F10B 1F10F
-1F12F
-1F150 1F169
-1F16C 1F18F
-1F191 1F1FF
-1F203 1F20F
-1F23B 1F23F
-1F249 1F24F
-1F252 2F7FF
-2FA1E 10FFFF
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Ea/F.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Ea/F.pl
deleted file mode 100644
index 59ba8f5f981..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Ea/F.pl
+++ /dev/null
@@ -1,15 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-3000
-FF01 FF60
-FFE0 FFE6
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Gc/Pc.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Gc/Pc.pl
deleted file mode 100644
index 14e9be47c43..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Gc/Pc.pl
+++ /dev/null
@@ -1,18 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-005F
-203F 2040
-2054
-FE33 FE34
-FE4D FE4F
-FF3F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Lb/CR.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Lb/CR.pl
deleted file mode 100644
index 76840971c71..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Lb/CR.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-000D
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Lb/H2.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Lb/H2.pl
deleted file mode 100644
index 12dae1b1b92..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Lb/H2.pl
+++ /dev/null
@@ -1,411 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-AC00
-AC1C
-AC38
-AC54
-AC70
-AC8C
-ACA8
-ACC4
-ACE0
-ACFC
-AD18
-AD34
-AD50
-AD6C
-AD88
-ADA4
-ADC0
-ADDC
-ADF8
-AE14
-AE30
-AE4C
-AE68
-AE84
-AEA0
-AEBC
-AED8
-AEF4
-AF10
-AF2C
-AF48
-AF64
-AF80
-AF9C
-AFB8
-AFD4
-AFF0
-B00C
-B028
-B044
-B060
-B07C
-B098
-B0B4
-B0D0
-B0EC
-B108
-B124
-B140
-B15C
-B178
-B194
-B1B0
-B1CC
-B1E8
-B204
-B220
-B23C
-B258
-B274
-B290
-B2AC
-B2C8
-B2E4
-B300
-B31C
-B338
-B354
-B370
-B38C
-B3A8
-B3C4
-B3E0
-B3FC
-B418
-B434
-B450
-B46C
-B488
-B4A4
-B4C0
-B4DC
-B4F8
-B514
-B530
-B54C
-B568
-B584
-B5A0
-B5BC
-B5D8
-B5F4
-B610
-B62C
-B648
-B664
-B680
-B69C
-B6B8
-B6D4
-B6F0
-B70C
-B728
-B744
-B760
-B77C
-B798
-B7B4
-B7D0
-B7EC
-B808
-B824
-B840
-B85C
-B878
-B894
-B8B0
-B8CC
-B8E8
-B904
-B920
-B93C
-B958
-B974
-B990
-B9AC
-B9C8
-B9E4
-BA00
-BA1C
-BA38
-BA54
-BA70
-BA8C
-BAA8
-BAC4
-BAE0
-BAFC
-BB18
-BB34
-BB50
-BB6C
-BB88
-BBA4
-BBC0
-BBDC
-BBF8
-BC14
-BC30
-BC4C
-BC68
-BC84
-BCA0
-BCBC
-BCD8
-BCF4
-BD10
-BD2C
-BD48
-BD64
-BD80
-BD9C
-BDB8
-BDD4
-BDF0
-BE0C
-BE28
-BE44
-BE60
-BE7C
-BE98
-BEB4
-BED0
-BEEC
-BF08
-BF24
-BF40
-BF5C
-BF78
-BF94
-BFB0
-BFCC
-BFE8
-C004
-C020
-C03C
-C058
-C074
-C090
-C0AC
-C0C8
-C0E4
-C100
-C11C
-C138
-C154
-C170
-C18C
-C1A8
-C1C4
-C1E0
-C1FC
-C218
-C234
-C250
-C26C
-C288
-C2A4
-C2C0
-C2DC
-C2F8
-C314
-C330
-C34C
-C368
-C384
-C3A0
-C3BC
-C3D8
-C3F4
-C410
-C42C
-C448
-C464
-C480
-C49C
-C4B8
-C4D4
-C4F0
-C50C
-C528
-C544
-C560
-C57C
-C598
-C5B4
-C5D0
-C5EC
-C608
-C624
-C640
-C65C
-C678
-C694
-C6B0
-C6CC
-C6E8
-C704
-C720
-C73C
-C758
-C774
-C790
-C7AC
-C7C8
-C7E4
-C800
-C81C
-C838
-C854
-C870
-C88C
-C8A8
-C8C4
-C8E0
-C8FC
-C918
-C934
-C950
-C96C
-C988
-C9A4
-C9C0
-C9DC
-C9F8
-CA14
-CA30
-CA4C
-CA68
-CA84
-CAA0
-CABC
-CAD8
-CAF4
-CB10
-CB2C
-CB48
-CB64
-CB80
-CB9C
-CBB8
-CBD4
-CBF0
-CC0C
-CC28
-CC44
-CC60
-CC7C
-CC98
-CCB4
-CCD0
-CCEC
-CD08
-CD24
-CD40
-CD5C
-CD78
-CD94
-CDB0
-CDCC
-CDE8
-CE04
-CE20
-CE3C
-CE58
-CE74
-CE90
-CEAC
-CEC8
-CEE4
-CF00
-CF1C
-CF38
-CF54
-CF70
-CF8C
-CFA8
-CFC4
-CFE0
-CFFC
-D018
-D034
-D050
-D06C
-D088
-D0A4
-D0C0
-D0DC
-D0F8
-D114
-D130
-D14C
-D168
-D184
-D1A0
-D1BC
-D1D8
-D1F4
-D210
-D22C
-D248
-D264
-D280
-D29C
-D2B8
-D2D4
-D2F0
-D30C
-D328
-D344
-D360
-D37C
-D398
-D3B4
-D3D0
-D3EC
-D408
-D424
-D440
-D45C
-D478
-D494
-D4B0
-D4CC
-D4E8
-D504
-D520
-D53C
-D558
-D574
-D590
-D5AC
-D5C8
-D5E4
-D600
-D61C
-D638
-D654
-D670
-D68C
-D6A8
-D6C4
-D6E0
-D6FC
-D718
-D734
-D750
-D76C
-D788
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Lb/H3.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Lb/H3.pl
deleted file mode 100644
index da0553bdcb2..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Lb/H3.pl
+++ /dev/null
@@ -1,411 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-AC01 AC1B
-AC1D AC37
-AC39 AC53
-AC55 AC6F
-AC71 AC8B
-AC8D ACA7
-ACA9 ACC3
-ACC5 ACDF
-ACE1 ACFB
-ACFD AD17
-AD19 AD33
-AD35 AD4F
-AD51 AD6B
-AD6D AD87
-AD89 ADA3
-ADA5 ADBF
-ADC1 ADDB
-ADDD ADF7
-ADF9 AE13
-AE15 AE2F
-AE31 AE4B
-AE4D AE67
-AE69 AE83
-AE85 AE9F
-AEA1 AEBB
-AEBD AED7
-AED9 AEF3
-AEF5 AF0F
-AF11 AF2B
-AF2D AF47
-AF49 AF63
-AF65 AF7F
-AF81 AF9B
-AF9D AFB7
-AFB9 AFD3
-AFD5 AFEF
-AFF1 B00B
-B00D B027
-B029 B043
-B045 B05F
-B061 B07B
-B07D B097
-B099 B0B3
-B0B5 B0CF
-B0D1 B0EB
-B0ED B107
-B109 B123
-B125 B13F
-B141 B15B
-B15D B177
-B179 B193
-B195 B1AF
-B1B1 B1CB
-B1CD B1E7
-B1E9 B203
-B205 B21F
-B221 B23B
-B23D B257
-B259 B273
-B275 B28F
-B291 B2AB
-B2AD B2C7
-B2C9 B2E3
-B2E5 B2FF
-B301 B31B
-B31D B337
-B339 B353
-B355 B36F
-B371 B38B
-B38D B3A7
-B3A9 B3C3
-B3C5 B3DF
-B3E1 B3FB
-B3FD B417
-B419 B433
-B435 B44F
-B451 B46B
-B46D B487
-B489 B4A3
-B4A5 B4BF
-B4C1 B4DB
-B4DD B4F7
-B4F9 B513
-B515 B52F
-B531 B54B
-B54D B567
-B569 B583
-B585 B59F
-B5A1 B5BB
-B5BD B5D7
-B5D9 B5F3
-B5F5 B60F
-B611 B62B
-B62D B647
-B649 B663
-B665 B67F
-B681 B69B
-B69D B6B7
-B6B9 B6D3
-B6D5 B6EF
-B6F1 B70B
-B70D B727
-B729 B743
-B745 B75F
-B761 B77B
-B77D B797
-B799 B7B3
-B7B5 B7CF
-B7D1 B7EB
-B7ED B807
-B809 B823
-B825 B83F
-B841 B85B
-B85D B877
-B879 B893
-B895 B8AF
-B8B1 B8CB
-B8CD B8E7
-B8E9 B903
-B905 B91F
-B921 B93B
-B93D B957
-B959 B973
-B975 B98F
-B991 B9AB
-B9AD B9C7
-B9C9 B9E3
-B9E5 B9FF
-BA01 BA1B
-BA1D BA37
-BA39 BA53
-BA55 BA6F
-BA71 BA8B
-BA8D BAA7
-BAA9 BAC3
-BAC5 BADF
-BAE1 BAFB
-BAFD BB17
-BB19 BB33
-BB35 BB4F
-BB51 BB6B
-BB6D BB87
-BB89 BBA3
-BBA5 BBBF
-BBC1 BBDB
-BBDD BBF7
-BBF9 BC13
-BC15 BC2F
-BC31 BC4B
-BC4D BC67
-BC69 BC83
-BC85 BC9F
-BCA1 BCBB
-BCBD BCD7
-BCD9 BCF3
-BCF5 BD0F
-BD11 BD2B
-BD2D BD47
-BD49 BD63
-BD65 BD7F
-BD81 BD9B
-BD9D BDB7
-BDB9 BDD3
-BDD5 BDEF
-BDF1 BE0B
-BE0D BE27
-BE29 BE43
-BE45 BE5F
-BE61 BE7B
-BE7D BE97
-BE99 BEB3
-BEB5 BECF
-BED1 BEEB
-BEED BF07
-BF09 BF23
-BF25 BF3F
-BF41 BF5B
-BF5D BF77
-BF79 BF93
-BF95 BFAF
-BFB1 BFCB
-BFCD BFE7
-BFE9 C003
-C005 C01F
-C021 C03B
-C03D C057
-C059 C073
-C075 C08F
-C091 C0AB
-C0AD C0C7
-C0C9 C0E3
-C0E5 C0FF
-C101 C11B
-C11D C137
-C139 C153
-C155 C16F
-C171 C18B
-C18D C1A7
-C1A9 C1C3
-C1C5 C1DF
-C1E1 C1FB
-C1FD C217
-C219 C233
-C235 C24F
-C251 C26B
-C26D C287
-C289 C2A3
-C2A5 C2BF
-C2C1 C2DB
-C2DD C2F7
-C2F9 C313
-C315 C32F
-C331 C34B
-C34D C367
-C369 C383
-C385 C39F
-C3A1 C3BB
-C3BD C3D7
-C3D9 C3F3
-C3F5 C40F
-C411 C42B
-C42D C447
-C449 C463
-C465 C47F
-C481 C49B
-C49D C4B7
-C4B9 C4D3
-C4D5 C4EF
-C4F1 C50B
-C50D C527
-C529 C543
-C545 C55F
-C561 C57B
-C57D C597
-C599 C5B3
-C5B5 C5CF
-C5D1 C5EB
-C5ED C607
-C609 C623
-C625 C63F
-C641 C65B
-C65D C677
-C679 C693
-C695 C6AF
-C6B1 C6CB
-C6CD C6E7
-C6E9 C703
-C705 C71F
-C721 C73B
-C73D C757
-C759 C773
-C775 C78F
-C791 C7AB
-C7AD C7C7
-C7C9 C7E3
-C7E5 C7FF
-C801 C81B
-C81D C837
-C839 C853
-C855 C86F
-C871 C88B
-C88D C8A7
-C8A9 C8C3
-C8C5 C8DF
-C8E1 C8FB
-C8FD C917
-C919 C933
-C935 C94F
-C951 C96B
-C96D C987
-C989 C9A3
-C9A5 C9BF
-C9C1 C9DB
-C9DD C9F7
-C9F9 CA13
-CA15 CA2F
-CA31 CA4B
-CA4D CA67
-CA69 CA83
-CA85 CA9F
-CAA1 CABB
-CABD CAD7
-CAD9 CAF3
-CAF5 CB0F
-CB11 CB2B
-CB2D CB47
-CB49 CB63
-CB65 CB7F
-CB81 CB9B
-CB9D CBB7
-CBB9 CBD3
-CBD5 CBEF
-CBF1 CC0B
-CC0D CC27
-CC29 CC43
-CC45 CC5F
-CC61 CC7B
-CC7D CC97
-CC99 CCB3
-CCB5 CCCF
-CCD1 CCEB
-CCED CD07
-CD09 CD23
-CD25 CD3F
-CD41 CD5B
-CD5D CD77
-CD79 CD93
-CD95 CDAF
-CDB1 CDCB
-CDCD CDE7
-CDE9 CE03
-CE05 CE1F
-CE21 CE3B
-CE3D CE57
-CE59 CE73
-CE75 CE8F
-CE91 CEAB
-CEAD CEC7
-CEC9 CEE3
-CEE5 CEFF
-CF01 CF1B
-CF1D CF37
-CF39 CF53
-CF55 CF6F
-CF71 CF8B
-CF8D CFA7
-CFA9 CFC3
-CFC5 CFDF
-CFE1 CFFB
-CFFD D017
-D019 D033
-D035 D04F
-D051 D06B
-D06D D087
-D089 D0A3
-D0A5 D0BF
-D0C1 D0DB
-D0DD D0F7
-D0F9 D113
-D115 D12F
-D131 D14B
-D14D D167
-D169 D183
-D185 D19F
-D1A1 D1BB
-D1BD D1D7
-D1D9 D1F3
-D1F5 D20F
-D211 D22B
-D22D D247
-D249 D263
-D265 D27F
-D281 D29B
-D29D D2B7
-D2B9 D2D3
-D2D5 D2EF
-D2F1 D30B
-D30D D327
-D329 D343
-D345 D35F
-D361 D37B
-D37D D397
-D399 D3B3
-D3B5 D3CF
-D3D1 D3EB
-D3ED D407
-D409 D423
-D425 D43F
-D441 D45B
-D45D D477
-D479 D493
-D495 D4AF
-D4B1 D4CB
-D4CD D4E7
-D4E9 D503
-D505 D51F
-D521 D53B
-D53D D557
-D559 D573
-D575 D58F
-D591 D5AB
-D5AD D5C7
-D5C9 D5E3
-D5E5 D5FF
-D601 D61B
-D61D D637
-D639 D653
-D655 D66F
-D671 D68B
-D68D D6A7
-D6A9 D6C3
-D6C5 D6DF
-D6E1 D6FB
-D6FD D717
-D719 D733
-D735 D74F
-D751 D76B
-D76D D787
-D789 D7A3
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Lb/JL.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Lb/JL.pl
deleted file mode 100644
index e01db3f38c1..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Lb/JL.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-1100 115F
-A960 A97C
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Lb/JT.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Lb/JT.pl
deleted file mode 100644
index 2bddf0118c2..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Lb/JT.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-11A8 11FF
-D7CB D7FB
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Lb/JV.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Lb/JV.pl
deleted file mode 100644
index acf437a55ff..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Lb/JV.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-1160 11A7
-D7B0 D7C6
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Lb/LF.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Lb/LF.pl
deleted file mode 100644
index 090014934bb..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Lb/LF.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-000A
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Lb/NU.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Lb/NU.pl
deleted file mode 100644
index 7a439c96b9e..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Lb/NU.pl
+++ /dev/null
@@ -1,54 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0030 0039
-0660 0669
-066B 066C
-06F0 06F9
-07C0 07C9
-0966 096F
-09E6 09EF
-0A66 0A6F
-0AE6 0AEF
-0B66 0B6F
-0BE6 0BEF
-0C66 0C6F
-0CE6 0CEF
-0D66 0D6F
-0E50 0E59
-0ED0 0ED9
-0F20 0F29
-1040 1049
-1090 1099
-17E0 17E9
-1810 1819
-1946 194F
-19D0 19D9
-1A80 1A89
-1A90 1A99
-1B50 1B59
-1BB0 1BB9
-1C40 1C49
-1C50 1C59
-A620 A629
-A8D0 A8D9
-A900 A909
-A9D0 A9D9
-AA50 AA59
-ABF0 ABF9
-104A0 104A9
-11066 1106F
-110F0 110F9
-11136 1113F
-111D0 111D9
-116C0 116C9
-1D7CE 1D7FF
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/NFKCQC/M.pl b/Master/tlpkg/tlperl/lib/unicore/lib/NFKCQC/M.pl
deleted file mode 100644
index 86863c9db40..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/NFKCQC/M.pl
+++ /dev/null
@@ -1,47 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0300 0304
-0306 030C
-030F
-0311
-0313 0314
-031B
-0323 0328
-032D 032E
-0330 0331
-0338
-0342
-0345
-0653 0655
-093C
-09BE
-09D7
-0B3E
-0B56 0B57
-0BBE
-0BD7
-0C56
-0CC2
-0CD5 0CD6
-0D3E
-0D57
-0DCA
-0DCF
-0DDF
-102E
-1161 1175
-11A8 11C2
-1B35
-3099 309A
-110BA
-11127
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Nv/NaN.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Nv/NaN.pl
deleted file mode 100644
index e11ef488de2..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Nv/NaN.pl
+++ /dev/null
@@ -1,175 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0000 002F
-003A 00B1
-00B4 00B8
-00BA 00BB
-00BF 065F
-066A 06EF
-06FA 07BF
-07CA 0965
-0970 09E5
-09F0 09F3
-09FA 0A65
-0A70 0AE5
-0AF0 0B65
-0B70 0B71
-0B78 0BE5
-0BF3 0C65
-0C70 0C77
-0C7F 0CE5
-0CF0 0D65
-0D76 0E4F
-0E5A 0ECF
-0EDA 0F1F
-0F34 103F
-104A 108F
-109A 1368
-137D 16ED
-16F1 17DF
-17EA 17EF
-17FA 180F
-181A 1945
-1950 19CF
-19DB 1A7F
-1A8A 1A8F
-1A9A 1B4F
-1B5A 1BAF
-1BBA 1C3F
-1C4A 1C4F
-1C5A 206F
-2071 2073
-207A 207F
-208A 214F
-2183 2184
-218A 245F
-249C 24E9
-2500 2775
-2794 2CFC
-2CFE 3006
-3008 3020
-302A 3037
-303B 3191
-3196 321F
-322A 3247
-3250
-3260 327F
-328A 32B0
-32C0 3404
-3406 3482
-3484 3829
-382B 3B4C
-3B4E 4DFF
-4E01 4E02
-4E04 4E06
-4E08
-4E0A 4E5C
-4E5E 4E8B
-4E8D 4E93
-4E95
-4E97 4EBE
-4EC1 4EDE
-4EE0 4EE7
-4EE9 4F0C
-4F0E 4F6F
-4F71 5103
-5105 5145
-5147 5168
-516A
-516C
-516E 5340
-5342
-5346 534B
-534D 53C0
-53C5 56DA
-56DC 58F0
-58F2 58F8
-58FA 5E79
-5E7B 5EFD
-5F00 5F0B
-5F0F
-5F11 62FD
-62FF 634B
-634D 67D1
-67D3 6F05
-6F07 7395
-7397 767D
-767F 8085
-8087 842B
-842D 8CAD
-8CAF 8CB2
-8CB4 8D2F
-8D31 9620
-9622 9645
-9647 964B
-964D 9677
-9679 96F5
-96F7 A61F
-A62A A6E5
-A6F0 A82F
-A836 A8CF
-A8DA A8FF
-A90A A9CF
-A9DA AA4F
-AA5A ABEF
-ABFA F96A
-F96C F972
-F974 F977
-F979 F9B1
-F9B3 F9D0
-F9D2
-F9D4 F9FC
-F9FE FF0F
-FF1A 10106
-10134 1013F
-10179 10189
-1018B 1031F
-10324 10340
-10342 10349
-1034B 103D0
-103D6 1049F
-104AA 10857
-10860 10915
-1091C 10A3F
-10A48 10A7C
-10A7F 10B57
-10B60 10B77
-10B80 10E5F
-10E7F 11051
-11070 110EF
-110FA 11135
-11140 111CF
-111DA 116BF
-116CA 123FF
-12432 12433
-12456 12457
-12463 1D35F
-1D372 1D7CD
-1D800 1F0FF
-1F10B 20000
-20002 20063
-20065 200E1
-200E3 20120
-20122 20929
-2092B 20982
-20984 2098B
-2098D 2099B
-2099D 20AE9
-20AEB 20AFC
-20AFE 20B18
-20B1A 2238F
-22391 22997
-22999 23B1A
-23B1C 2626C
-2626E 2F88F
-2F891 10FFFF
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Perl/PosixSpa.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Perl/PosixSpa.pl
deleted file mode 100644
index cceac7bdc75..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Perl/PosixSpa.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0009 000D
-0020
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Perl/_PerlNon.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Perl/_PerlNon.pl
deleted file mode 100644
index 3d5c46a05b5..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Perl/_PerlNon.pl
+++ /dev/null
@@ -1,40 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0061
-0066
-0068 006A
-0073 0074
-0077
-0079
-02BC
-0308
-0313
-0342
-03AC
-03AE
-03B1
-03B7
-03B9
-03C1
-03C5
-03C9
-03CE
-0565
-0574
-057E
-1F00 1F07
-1F20 1F27
-1F60 1F67
-1F70
-1F74
-1F7C
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Perl/_XBegin.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Perl/_XBegin.pl
deleted file mode 100644
index 59f6352f0fe..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Perl/_XBegin.pl
+++ /dev/null
@@ -1,29 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0020 007E
-00A0 00AC
-00AE 05FF
-0605 06DC
-06DE 070E
-0710 200A
-200C 200D
-2010 2027
-202F 205F
-2070 D7FF
-E000 FEFE
-FF00 FFEF
-FFFC 110BC
-110BE 1D172
-1D17B DFFFF
-E0100 E01EF
-E1000 10FFFF
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Armi.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Armi.pl
deleted file mode 100644
index 8c2682af14c..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Armi.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-10840 10855
-10857 1085F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Avst.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Avst.pl
deleted file mode 100644
index b568f0dcce1..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Avst.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-10B00 10B35
-10B39 10B3F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Bali.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Bali.pl
deleted file mode 100644
index 10fae5f9e37..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Bali.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-1B00 1B4B
-1B50 1B7C
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Bamu.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Bamu.pl
deleted file mode 100644
index 0fa743b613d..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Bamu.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-A6A0 A6F7
-16800 16A38
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Batk.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Batk.pl
deleted file mode 100644
index a897b6114ad..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Batk.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-1BC0 1BF3
-1BFC 1BFF
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Brah.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Brah.pl
deleted file mode 100644
index 7a964d1b204..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Brah.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-11000 1104D
-11052 1106F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Brai.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Brai.pl
deleted file mode 100644
index 81dbbb2aacf..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Brai.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-2800 28FF
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Bugi.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Bugi.pl
deleted file mode 100644
index 1320c31898f..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Bugi.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-1A00 1A1B
-1A1E 1A1F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cakm.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cakm.pl
deleted file mode 100644
index 2a6e5d1011d..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cakm.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-11100 11134
-11136 11143
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cans.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cans.pl
deleted file mode 100644
index 942c008ecf7..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cans.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-1400 167F
-18B0 18F5
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cari.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cari.pl
deleted file mode 100644
index fe0bec2beae..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cari.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-102A0 102D0
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cham.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cham.pl
deleted file mode 100644
index c939e15834a..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cham.pl
+++ /dev/null
@@ -1,16 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-AA00 AA36
-AA40 AA4D
-AA50 AA59
-AA5C AA5F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cher.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cher.pl
deleted file mode 100644
index 6ca5fd3bf71..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Cher.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-13A0 13F4
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Copt.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Copt.pl
deleted file mode 100644
index 5de3d935df8..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Copt.pl
+++ /dev/null
@@ -1,15 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-03E2 03EF
-2C80 2CF3
-2CF9 2CFF
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Dsrt.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Dsrt.pl
deleted file mode 100644
index cc68d833d9f..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Dsrt.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-10400 1044F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Egyp.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Egyp.pl
deleted file mode 100644
index eb5e07b985c..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Egyp.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-13000 1342E
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Ethi.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Ethi.pl
deleted file mode 100644
index 90817030b35..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Ethi.pl
+++ /dev/null
@@ -1,44 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-1200 1248
-124A 124D
-1250 1256
-1258
-125A 125D
-1260 1288
-128A 128D
-1290 12B0
-12B2 12B5
-12B8 12BE
-12C0
-12C2 12C5
-12C8 12D6
-12D8 1310
-1312 1315
-1318 135A
-135D 137C
-1380 1399
-2D80 2D96
-2DA0 2DA6
-2DA8 2DAE
-2DB0 2DB6
-2DB8 2DBE
-2DC0 2DC6
-2DC8 2DCE
-2DD0 2DD6
-2DD8 2DDE
-AB01 AB06
-AB09 AB0E
-AB11 AB16
-AB20 AB26
-AB28 AB2E
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Glag.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Glag.pl
deleted file mode 100644
index b19d57f96e3..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Glag.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-2C00 2C2E
-2C30 2C5E
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Goth.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Goth.pl
deleted file mode 100644
index 8775e275890..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Goth.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-10330 1034A
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Hebr.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Hebr.pl
deleted file mode 100644
index 75e067964c6..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Hebr.pl
+++ /dev/null
@@ -1,21 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0591 05C7
-05D0 05EA
-05F0 05F4
-FB1D FB36
-FB38 FB3C
-FB3E
-FB40 FB41
-FB43 FB44
-FB46 FB4F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Ital.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Ital.pl
deleted file mode 100644
index 3c5ca9f76d2..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Ital.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-10300 1031E
-10320 10323
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Java.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Java.pl
deleted file mode 100644
index b564efa909e..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Java.pl
+++ /dev/null
@@ -1,15 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-A980 A9CD
-A9CF A9D9
-A9DE A9DF
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Kali.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Kali.pl
deleted file mode 100644
index b31e0e5da2d..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Kali.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-A900 A92F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Khar.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Khar.pl
deleted file mode 100644
index 193550d501a..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Khar.pl
+++ /dev/null
@@ -1,20 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-10A00 10A03
-10A05 10A06
-10A0C 10A13
-10A15 10A17
-10A19 10A33
-10A38 10A3A
-10A3F 10A47
-10A50 10A58
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Khmr.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Khmr.pl
deleted file mode 100644
index 39034d5c968..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Khmr.pl
+++ /dev/null
@@ -1,16 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-1780 17DD
-17E0 17E9
-17F0 17F9
-19E0 19FF
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Knda.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Knda.pl
deleted file mode 100644
index b00c921a043..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Knda.pl
+++ /dev/null
@@ -1,26 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0C82 0C83
-0C85 0C8C
-0C8E 0C90
-0C92 0CA8
-0CAA 0CB3
-0CB5 0CB9
-0CBC 0CC4
-0CC6 0CC8
-0CCA 0CCD
-0CD5 0CD6
-0CDE
-0CE0 0CE3
-0CE6 0CEF
-0CF1 0CF2
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lana.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lana.pl
deleted file mode 100644
index b271ec2b621..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lana.pl
+++ /dev/null
@@ -1,17 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-1A20 1A5E
-1A60 1A7C
-1A7F 1A89
-1A90 1A99
-1AA0 1AAD
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lao.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lao.pl
deleted file mode 100644
index 68498b98513..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lao.pl
+++ /dev/null
@@ -1,30 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0E81 0E82
-0E84
-0E87 0E88
-0E8A
-0E8D
-0E94 0E97
-0E99 0E9F
-0EA1 0EA3
-0EA5
-0EA7
-0EAA 0EAB
-0EAD 0EB9
-0EBB 0EBD
-0EC0 0EC4
-0EC6
-0EC8 0ECD
-0ED0 0ED9
-0EDC 0EDF
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lepc.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lepc.pl
deleted file mode 100644
index af9a44316f2..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lepc.pl
+++ /dev/null
@@ -1,15 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-1C00 1C37
-1C3B 1C49
-1C4D 1C4F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Limb.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Limb.pl
deleted file mode 100644
index 1eba59ec4d8..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Limb.pl
+++ /dev/null
@@ -1,17 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-1900 191C
-1920 192B
-1930 193B
-1940
-1944 194F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lisu.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lisu.pl
deleted file mode 100644
index bfcca001ae1..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lisu.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-A4D0 A4FF
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lyci.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lyci.pl
deleted file mode 100644
index a4b1ce9f966..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lyci.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-10280 1029C
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lydi.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lydi.pl
deleted file mode 100644
index 56a870ecd25..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Lydi.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-10920 10939
-1093F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Merc.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Merc.pl
deleted file mode 100644
index f8c174b46cb..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Merc.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-109A0 109B7
-109BE 109BF
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Mero.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Mero.pl
deleted file mode 100644
index 0e7590b13f5..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Mero.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-10980 1099F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Miao.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Miao.pl
deleted file mode 100644
index e3a20719864..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Miao.pl
+++ /dev/null
@@ -1,15 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-16F00 16F44
-16F50 16F7E
-16F8F 16F9F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Mlym.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Mlym.pl
deleted file mode 100644
index d0e424934a7..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Mlym.pl
+++ /dev/null
@@ -1,23 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0D02 0D03
-0D05 0D0C
-0D0E 0D10
-0D12 0D3A
-0D3D 0D44
-0D46 0D48
-0D4A 0D4E
-0D57
-0D60 0D63
-0D66 0D75
-0D79 0D7F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Mtei.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Mtei.pl
deleted file mode 100644
index 8823368dd7f..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Mtei.pl
+++ /dev/null
@@ -1,15 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-AAE0 AAF6
-ABC0 ABED
-ABF0 ABF9
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Mymr.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Mymr.pl
deleted file mode 100644
index 44f23a612d8..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Mymr.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-1000 109F
-AA60 AA7B
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Nko.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Nko.pl
deleted file mode 100644
index 210e1395490..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Nko.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-07C0 07FA
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Ogam.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Ogam.pl
deleted file mode 100644
index 88c88c85d3a..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Ogam.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-1680 169C
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Olck.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Olck.pl
deleted file mode 100644
index 3ac15a776c8..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Olck.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-1C50 1C7F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Orkh.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Orkh.pl
deleted file mode 100644
index eab9acbdc01..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Orkh.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-10C00 10C48
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Osma.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Osma.pl
deleted file mode 100644
index de5cd6cefca..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Osma.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-10480 1049D
-104A0 104A9
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Phli.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Phli.pl
deleted file mode 100644
index d14737baa91..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Phli.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-10B60 10B72
-10B78 10B7F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Phnx.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Phnx.pl
deleted file mode 100644
index 3267231a152..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Phnx.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-10900 1091B
-1091F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Prti.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Prti.pl
deleted file mode 100644
index 90cb62a294c..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Prti.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-10B40 10B55
-10B58 10B5F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Rjng.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Rjng.pl
deleted file mode 100644
index ee356ab55e9..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Rjng.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-A930 A953
-A95F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Runr.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Runr.pl
deleted file mode 100644
index 935b11059dc..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Runr.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-16A0 16EA
-16EE 16F0
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Samr.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Samr.pl
deleted file mode 100644
index d5ad76601f7..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Samr.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0800 082D
-0830 083E
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sarb.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sarb.pl
deleted file mode 100644
index adde555a073..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sarb.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-10A60 10A7F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Saur.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Saur.pl
deleted file mode 100644
index a4158cf1b2e..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Saur.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-A880 A8C4
-A8CE A8D9
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Shaw.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Shaw.pl
deleted file mode 100644
index 2f597f234a3..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Shaw.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-10450 1047F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Shrd.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Shrd.pl
deleted file mode 100644
index c68b986392d..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Shrd.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-11180 111C8
-111D0 111D9
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sinh.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sinh.pl
deleted file mode 100644
index 6e54f492300..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sinh.pl
+++ /dev/null
@@ -1,23 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0D82 0D83
-0D85 0D96
-0D9A 0DB1
-0DB3 0DBB
-0DBD
-0DC0 0DC6
-0DCA
-0DCF 0DD4
-0DD6
-0DD8 0DDF
-0DF2 0DF4
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sora.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sora.pl
deleted file mode 100644
index f70d7a88504..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sora.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-110D0 110E8
-110F0 110F9
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sund.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sund.pl
deleted file mode 100644
index 2339aeb3378..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sund.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-1B80 1BBF
-1CC0 1CC7
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sylo.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sylo.pl
deleted file mode 100644
index f1a58fbaede..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Sylo.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-A800 A82B
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Tale.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Tale.pl
deleted file mode 100644
index 8ca22e090bc..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Tale.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-1950 196D
-1970 1974
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Talu.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Talu.pl
deleted file mode 100644
index 07a47dad1d9..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Talu.pl
+++ /dev/null
@@ -1,16 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-1980 19AB
-19B0 19C9
-19D0 19DA
-19DE 19DF
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Taml.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Taml.pl
deleted file mode 100644
index 8590444266d..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Taml.pl
+++ /dev/null
@@ -1,28 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0B82 0B83
-0B85 0B8A
-0B8E 0B90
-0B92 0B95
-0B99 0B9A
-0B9C
-0B9E 0B9F
-0BA3 0BA4
-0BA8 0BAA
-0BAE 0BB9
-0BBE 0BC2
-0BC6 0BC8
-0BCA 0BCD
-0BD0
-0BD7
-0BE6 0BFA
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Tavt.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Tavt.pl
deleted file mode 100644
index 226eb3908c9..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Tavt.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-AA80 AAC2
-AADB AADF
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Telu.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Telu.pl
deleted file mode 100644
index e067fa4198a..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Telu.pl
+++ /dev/null
@@ -1,26 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0C01 0C03
-0C05 0C0C
-0C0E 0C10
-0C12 0C28
-0C2A 0C33
-0C35 0C39
-0C3D 0C44
-0C46 0C48
-0C4A 0C4D
-0C55 0C56
-0C58 0C59
-0C60 0C63
-0C66 0C6F
-0C78 0C7F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Tfng.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Tfng.pl
deleted file mode 100644
index 490cef0b555..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Tfng.pl
+++ /dev/null
@@ -1,15 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-2D30 2D67
-2D6F 2D70
-2D7F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Thai.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Thai.pl
deleted file mode 100644
index d3690f0bdfe..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Thai.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0E01 0E3A
-0E40 0E5B
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Tibt.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Tibt.pl
deleted file mode 100644
index 67acadc5e74..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Tibt.pl
+++ /dev/null
@@ -1,19 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0F00 0F47
-0F49 0F6C
-0F71 0F97
-0F99 0FBC
-0FBE 0FCC
-0FCE 0FD4
-0FD9 0FDA
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Ugar.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Ugar.pl
deleted file mode 100644
index 91d47620525..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Ugar.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-10380 1039D
-1039F
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Vai.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Vai.pl
deleted file mode 100644
index 66a533828b5..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Vai.pl
+++ /dev/null
@@ -1,13 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-A500 A62B
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Xpeo.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Xpeo.pl
deleted file mode 100644
index 2c8fa19f5de..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Xpeo.pl
+++ /dev/null
@@ -1,14 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-103A0 103C3
-103C8 103D5
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Xsux.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Xsux.pl
deleted file mode 100644
index 7f5beb01c27..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Xsux.pl
+++ /dev/null
@@ -1,15 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-12000 1236E
-12400 12462
-12470 12473
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Zzzz.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Zzzz.pl
deleted file mode 100644
index 3146b4c6c88..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Scx/Zzzz.pl
+++ /dev/null
@@ -1,549 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0378 0379
-037F 0383
-038B
-038D
-03A2
-0528 0530
-0557 0558
-0560
-0588
-058B 058E
-0590
-05C8 05CF
-05EB 05EF
-05F5 05FF
-0605
-061C 061D
-070E
-074B 074C
-07B2 07BF
-07FB 07FF
-082E 082F
-083F
-085C 085D
-085F 089F
-08A1
-08AD 08E3
-08FF
-0978
-0980
-0984
-098D 098E
-0991 0992
-09A9
-09B1
-09B3 09B5
-09BA 09BB
-09C5 09C6
-09C9 09CA
-09CF 09D6
-09D8 09DB
-09DE
-09E4 09E5
-09FC 0A00
-0A04
-0A0B 0A0E
-0A11 0A12
-0A29
-0A31
-0A34
-0A37
-0A3A 0A3B
-0A3D
-0A43 0A46
-0A49 0A4A
-0A4E 0A50
-0A52 0A58
-0A5D
-0A5F 0A65
-0A76 0A80
-0A84
-0A8E
-0A92
-0AA9
-0AB1
-0AB4
-0ABA 0ABB
-0AC6
-0ACA
-0ACE 0ACF
-0AD1 0ADF
-0AE4 0AE5
-0AF2 0B00
-0B04
-0B0D 0B0E
-0B11 0B12
-0B29
-0B31
-0B34
-0B3A 0B3B
-0B45 0B46
-0B49 0B4A
-0B4E 0B55
-0B58 0B5B
-0B5E
-0B64 0B65
-0B78 0B81
-0B84
-0B8B 0B8D
-0B91
-0B96 0B98
-0B9B
-0B9D
-0BA0 0BA2
-0BA5 0BA7
-0BAB 0BAD
-0BBA 0BBD
-0BC3 0BC5
-0BC9
-0BCE 0BCF
-0BD1 0BD6
-0BD8 0BE5
-0BFB 0C00
-0C04
-0C0D
-0C11
-0C29
-0C34
-0C3A 0C3C
-0C45
-0C49
-0C4E 0C54
-0C57
-0C5A 0C5F
-0C64 0C65
-0C70 0C77
-0C80 0C81
-0C84
-0C8D
-0C91
-0CA9
-0CB4
-0CBA 0CBB
-0CC5
-0CC9
-0CCE 0CD4
-0CD7 0CDD
-0CDF
-0CE4 0CE5
-0CF0
-0CF3 0D01
-0D04
-0D0D
-0D11
-0D3B 0D3C
-0D45
-0D49
-0D4F 0D56
-0D58 0D5F
-0D64 0D65
-0D76 0D78
-0D80 0D81
-0D84
-0D97 0D99
-0DB2
-0DBC
-0DBE 0DBF
-0DC7 0DC9
-0DCB 0DCE
-0DD5
-0DD7
-0DE0 0DF1
-0DF5 0E00
-0E3B 0E3E
-0E5C 0E80
-0E83
-0E85 0E86
-0E89
-0E8B 0E8C
-0E8E 0E93
-0E98
-0EA0
-0EA4
-0EA6
-0EA8 0EA9
-0EAC
-0EBA
-0EBE 0EBF
-0EC5
-0EC7
-0ECE 0ECF
-0EDA 0EDB
-0EE0 0EFF
-0F48
-0F6D 0F70
-0F98
-0FBD
-0FCD
-0FDB 0FFF
-10C6
-10C8 10CC
-10CE 10CF
-1249
-124E 124F
-1257
-1259
-125E 125F
-1289
-128E 128F
-12B1
-12B6 12B7
-12BF
-12C1
-12C6 12C7
-12D7
-1311
-1316 1317
-135B 135C
-137D 137F
-139A 139F
-13F5 13FF
-169D 169F
-16F1 16FF
-170D
-1715 171F
-1737 173F
-1754 175F
-176D
-1771
-1774 177F
-17DE 17DF
-17EA 17EF
-17FA 17FF
-180F
-181A 181F
-1878 187F
-18AB 18AF
-18F6 18FF
-191D 191F
-192C 192F
-193C 193F
-1941 1943
-196E 196F
-1975 197F
-19AC 19AF
-19CA 19CF
-19DB 19DD
-1A1C 1A1D
-1A5F
-1A7D 1A7E
-1A8A 1A8F
-1A9A 1A9F
-1AAE 1AFF
-1B4C 1B4F
-1B7D 1B7F
-1BF4 1BFB
-1C38 1C3A
-1C4A 1C4C
-1C80 1CBF
-1CC8 1CCF
-1CF7 1CFF
-1DE7 1DFB
-1F16 1F17
-1F1E 1F1F
-1F46 1F47
-1F4E 1F4F
-1F58
-1F5A
-1F5C
-1F5E
-1F7E 1F7F
-1FB5
-1FC5
-1FD4 1FD5
-1FDC
-1FF0 1FF1
-1FF5
-1FFF
-2065 2069
-2072 2073
-208F
-209D 209F
-20BA 20CF
-20F1 20FF
-218A 218F
-23F4 23FF
-2427 243F
-244B 245F
-2700
-2B4D 2B4F
-2B5A 2BFF
-2C2F
-2C5F
-2CF4 2CF8
-2D26
-2D28 2D2C
-2D2E 2D2F
-2D68 2D6E
-2D71 2D7E
-2D97 2D9F
-2DA7
-2DAF
-2DB7
-2DBF
-2DC7
-2DCF
-2DD7
-2DDF
-2E3C 2E7F
-2E9A
-2EF4 2EFF
-2FD6 2FEF
-2FFC 2FFF
-3040
-3097 3098
-3100 3104
-312E 3130
-318F
-31BB 31BF
-31E4 31EF
-321F
-32FF
-4DB6 4DBF
-9FCD 9FFF
-A48D A48F
-A4C7 A4CF
-A62C A63F
-A698 A69E
-A6F8 A6FF
-A78F
-A794 A79F
-A7AB A7F7
-A82C A82F
-A83A A83F
-A878 A87F
-A8C5 A8CD
-A8DA A8DF
-A8FC A8FF
-A954 A95E
-A97D A97F
-A9CE
-A9DA A9DD
-A9E0 A9FF
-AA37 AA3F
-AA4E AA4F
-AA5A AA5B
-AA7C AA7F
-AAC3 AADA
-AAF7 AB00
-AB07 AB08
-AB0F AB10
-AB17 AB1F
-AB27
-AB2F ABBF
-ABEE ABEF
-ABFA ABFF
-D7A4 D7AF
-D7C7 D7CA
-D7FC F8FF
-FA6E FA6F
-FADA FAFF
-FB07 FB12
-FB18 FB1C
-FB37
-FB3D
-FB3F
-FB42
-FB45
-FBC2 FBD2
-FD40 FD4F
-FD90 FD91
-FDC8 FDEF
-FDFE FDFF
-FE1A FE1F
-FE27 FE2F
-FE53
-FE67
-FE6C FE6F
-FE75
-FEFD FEFE
-FF00
-FFBF FFC1
-FFC8 FFC9
-FFD0 FFD1
-FFD8 FFD9
-FFDD FFDF
-FFE7
-FFEF FFF8
-FFFE FFFF
-1000C
-10027
-1003B
-1003E
-1004E 1004F
-1005E 1007F
-100FB 100FF
-10103 10106
-10134 10136
-1018B 1018F
-1019C 101CF
-101FE 1027F
-1029D 1029F
-102D1 102FF
-1031F
-10324 1032F
-1034B 1037F
-1039E
-103C4 103C7
-103D6 103FF
-1049E 1049F
-104AA 107FF
-10806 10807
-10809
-10836
-10839 1083B
-1083D 1083E
-10856
-10860 108FF
-1091C 1091E
-1093A 1093E
-10940 1097F
-109B8 109BD
-109C0 109FF
-10A04
-10A07 10A0B
-10A14
-10A18
-10A34 10A37
-10A3B 10A3E
-10A48 10A4F
-10A59 10A5F
-10A80 10AFF
-10B36 10B38
-10B56 10B57
-10B73 10B77
-10B80 10BFF
-10C49 10E5F
-10E7F 10FFF
-1104E 11051
-11070 1107F
-110C2 110CF
-110E9 110EF
-110FA 110FF
-11135
-11144 1117F
-111C9 111CF
-111DA 1167F
-116B8 116BF
-116CA 11FFF
-1236F 123FF
-12463 1246F
-12474 12FFF
-1342F 167FF
-16A39 16EFF
-16F45 16F4F
-16F7F 16F8E
-16FA0 1AFFF
-1B002 1CFFF
-1D0F6 1D0FF
-1D127 1D128
-1D1DE 1D1FF
-1D246 1D2FF
-1D357 1D35F
-1D372 1D3FF
-1D455
-1D49D
-1D4A0 1D4A1
-1D4A3 1D4A4
-1D4A7 1D4A8
-1D4AD
-1D4BA
-1D4BC
-1D4C4
-1D506
-1D50B 1D50C
-1D515
-1D51D
-1D53A
-1D53F
-1D545
-1D547 1D549
-1D551
-1D6A6 1D6A7
-1D7CC 1D7CD
-1D800 1EDFF
-1EE04
-1EE20
-1EE23
-1EE25 1EE26
-1EE28
-1EE33
-1EE38
-1EE3A
-1EE3C 1EE41
-1EE43 1EE46
-1EE48
-1EE4A
-1EE4C
-1EE50
-1EE53
-1EE55 1EE56
-1EE58
-1EE5A
-1EE5C
-1EE5E
-1EE60
-1EE63
-1EE65 1EE66
-1EE6B
-1EE73
-1EE78
-1EE7D
-1EE7F
-1EE8A
-1EE9C 1EEA0
-1EEA4
-1EEAA
-1EEBC 1EEEF
-1EEF2 1EFFF
-1F02C 1F02F
-1F094 1F09F
-1F0AF 1F0B0
-1F0BF 1F0C0
-1F0D0
-1F0E0 1F0FF
-1F10B 1F10F
-1F12F
-1F16C 1F16F
-1F19B 1F1E5
-1F203 1F20F
-1F23B 1F23F
-1F249 1F24F
-1F252 1F2FF
-1F321 1F32F
-1F336
-1F37D 1F37F
-1F394 1F39F
-1F3C5
-1F3CB 1F3DF
-1F3F1 1F3FF
-1F43F
-1F441
-1F4F8
-1F4FD 1F4FF
-1F53E 1F53F
-1F544 1F54F
-1F568 1F5FA
-1F641 1F644
-1F650 1F67F
-1F6C6 1F6FF
-1F774 1FFFF
-2A6D7 2A6FF
-2B735 2B73F
-2B81E 2F7FF
-2FA1E E0000
-E0002 E001F
-E0080 E00FF
-E01F0 10FFFF
-END
diff --git a/Master/tlpkg/tlperl/lib/unicore/lib/Space/Y.pl b/Master/tlpkg/tlperl/lib/unicore/lib/Space/Y.pl
deleted file mode 100644
index cdba2e59228..00000000000
--- a/Master/tlpkg/tlperl/lib/unicore/lib/Space/Y.pl
+++ /dev/null
@@ -1,23 +0,0 @@
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is machine-generated by mktables from the Unicode
-# database, Version 6.1.0. Any changes made here will be lost!
-
-# !!!!!!! INTERNAL PERL USE ONLY !!!!!!!
-# This file is for internal use by core Perl only. The format and even the
-# name or existence of this file are subject to change without notice. Don't
-# use it directly.
-
-
-return <<'END';
-0009 000D
-0020
-0085
-00A0
-1680
-180E
-2000 200A
-2028 2029
-202F
-205F
-3000
-END
diff --git a/Master/tlpkg/tlperl/lib/version.pod b/Master/tlpkg/tlperl/lib/version.pod
deleted file mode 100644
index f4328f54391..00000000000
--- a/Master/tlpkg/tlperl/lib/version.pod
+++ /dev/null
@@ -1,322 +0,0 @@
-=head1 NAME
-
-version - Perl extension for Version Objects
-
-=head1 SYNOPSIS
-
- # Parsing version strings (decimal or dotted-decimal)
-
- use version 0.77; # get latest bug-fixes and API
- $ver = version->parse($string)
-
- # Declaring a dotted-decimal $VERSION (keep on one line!)
-
- use version; our $VERSION = version->declare("v1.2.3"); # formal
- use version; our $VERSION = qv("v1.2.3"); # shorthand
- use version; our $VERSION = qv("v1.2_3"); # alpha
-
- # Declaring an old-style decimal $VERSION (use quotes!)
-
- our $VERSION = "1.0203"; # recommended
- use version; our $VERSION = version->parse("1.0203"); # formal
- use version; our $VERSION = version->parse("1.02_03"); # alpha
-
- # Comparing mixed version styles (decimals, dotted-decimals, objects)
-
- if ( version->parse($v1) == version->parse($v2) ) {
- # do stuff
- }
-
- # Sorting mixed version styles
-
- @ordered = sort { version->parse($a) <=> version->parse($b) } @list;
-
-=head1 DESCRIPTION
-
-Version objects were added to Perl in 5.10. This module implements version
-objects for older version of Perl and provides the version object API for all
-versions of Perl. All previous releases before 0.74 are deprecated and should
-not be used due to incompatible API changes. Version 0.77 introduces the new
-'parse' and 'declare' methods to standardize usage. You are strongly urged to
-set 0.77 as a minimum in your code, e.g.
-
- use version 0.77; # even for Perl v.5.10.0
-
-=head1 TYPES OF VERSION OBJECTS
-
-There are two different types of version objects, corresponding to the two
-different styles of versions in use:
-
-=over 2
-
-=item Decimal Versions
-
-The classic floating-point number $VERSION. The advantage to this style is
-that you don't need to do anything special, just type a number into your
-source file. Quoting is recommended, as it ensures that trailing zeroes
-("1.50") are preserved in any warnings or other output.
-
-=item Dotted Decimal Versions
-
-The more modern form of version assignment, with 3 (or potentially more)
-integers separated by decimal points (e.g. v1.2.3). This is the form that
-Perl itself has used since 5.6.0 was released. The leading 'v' is now
-strongly recommended for clarity, and will throw a warning in a future
-release if omitted. A leading 'v' character is required to pass the
-L</is_strict()> test.
-
-=back
-
-=head1 DECLARING VERSIONS
-
-If you have a module that uses a decimal $VERSION (floating point), and you
-do not intend to ever change that, this module is not for you. There is
-nothing that version.pm gains you over a simple $VERSION assignment:
-
- our $VERSION = "1.02";
-
-Since Perl v5.10.0 includes the version.pm comparison logic anyways,
-you don't need to do anything at all.
-
-=head2 How to convert a module from decimal to dotted-decimal
-
-If you have used a decimal $VERSION in the past and wish to switch to a
-dotted-decimal $VERSION, then you need to make a one-time conversion to
-the new format.
-
-B<Important Note>: you must ensure that your new $VERSION is numerically
-greater than your current decimal $VERSION; this is not always obvious. First,
-convert your old decimal version (e.g. 1.02) to a normalized dotted-decimal
-form:
-
- $ perl -Mversion -e 'print version->parse("1.02")->normal'
- v1.20.0
-
-Then increment any of the dotted-decimal components (v1.20.1 or v1.21.0).
-
-=head2 How to C<declare()> a dotted-decimal version
-
- use version; our $VERSION = version->declare("v1.2.3");
-
-The C<declare()> method always creates dotted-decimal version objects. When
-used in a module, you B<must> put it on the same line as "use version" to
-ensure that $VERSION is read correctly by PAUSE and installer tools. You
-should also add 'version' to the 'configure_requires' section of your
-module metadata file. See instructions in L<ExtUtils::MakeMaker> or
-L<Module::Build> for details.
-
-B<Important Note>: Even if you pass in what looks like a decimal number
-("1.2"), a dotted-decimal will be created ("v1.200.0"). To avoid confusion
-or unintentional errors on older Perls, follow these guidelines:
-
-=over 2
-
-=item *
-
-Always use a dotted-decimal with (at least) three components
-
-=item *
-
-Always use a leading-v
-
-=item *
-
-Always quote the version
-
-=back
-
-If you really insist on using version.pm with an ordinary decimal version,
-use C<parse()> instead of declare. See the L<PARSING AND COMPARING VERSIONS>
-for details.
-
-See also L<version::Internals> for more on version number conversion,
-quoting, calculated version numbers and declaring developer or "alpha" version
-numbers.
-
-=head1 PARSING AND COMPARING VERSIONS
-
-If you need to compare version numbers, but can't be sure whether they are
-expressed as numbers, strings, v-strings or version objects, then you should
-use version.pm to parse them all into objects for comparison.
-
-=head2 How to C<parse()> a version
-
-The C<parse()> method takes in anything that might be a version and returns
-a corresponding version object, doing any necessary conversion along the way.
-
-=over 2
-
-=item *
-
-Dotted-decimal: bare v-strings (v1.2.3) and strings with more than one
-decimal point and a leading 'v' ("v1.2.3"); NOTE you can technically use a
-v-string or strings with a leading-v and only one decimal point (v1.2 or
-"v1.2"), but you will confuse both yourself and others.
-
-=item *
-
-Decimal: regular decimal numbers (literal or in a string)
-
-=back
-
-Some examples:
-
- $variable version->parse($variable)
- --------- -------------------------
- 1.23 v1.230.0
- "1.23" v1.230.0
- v1.23 v1.23.0
- "v1.23" v1.23.0
- "1.2.3" v1.2.3
- "v1.2.3" v1.2.3
-
-See L<version::Internals> for more on version number conversion.
-
-=head2 How to check for a legal version string
-
-If you do not want to actually create a full blown version object, but
-would still like to verify that a given string meets the criteria to
-be parsed as a version, there are two helper functions that can be
-employed directly:
-
-=over 4
-
-=item C<is_lax()>
-
-The lax criteria corresponds to what is currently allowed by the
-version parser. All of the following formats are acceptable
-for dotted-decimal formats strings:
-
- v1.2
- 1.2345.6
- v1.23_4
- 1.2345
- 1.2345_01
-
-=item C<is_strict()>
-
-If you want to limit yourself to a much more narrow definition of what
-a version string constitutes, C<is_strict()> is limited to version
-strings like the following list:
-
- v1.234.5
- 2.3456
-
-=back
-
-See L<version::Internals> for details of the regular expressions
-that define the legal version string forms, as well as how to use
-those regular expressions in your own code if C<is_lax()> and
-C<is_strict()> are not sufficient for your needs.
-
-=head2 How to compare version objects
-
-Version objects overload the C<cmp> and C<< <=> >> operators. Perl
-automatically generates all of the other comparison operators based on those
-two so all the normal logical comparisons will work.
-
- if ( version->parse($v1) == version->parse($v2) ) {
- # do stuff
- }
-
-If a version object is compared against a non-version object, the non-object
-term will be converted to a version object using C<parse()>. This may give
-surprising results:
-
- $v1 = version->parse("v0.95.0");
- $bool = $v1 < 0.96; # FALSE since 0.96 is v0.960.0
-
-Always comparing to a version object will help avoid surprises:
-
- $bool = $v1 < version->parse("v0.96.0"); # TRUE
-
-Note that "alpha" version objects (where the version string contains
-a trailing underscore segment) compare as less than the equivalent
-version without an underscore:
-
- $bool = version->parse("1.23_45") < version->parse("1.2345"); # TRUE
-
-See L<version::Internals> for more details on "alpha" versions.
-
-=head1 OBJECT METHODS
-
-=head2 is_alpha()
-
-True if and only if the version object was created with a underscore, e.g.
-
- version->parse('1.002_03')->is_alpha; # TRUE
- version->declare('1.2.3_4')->is_alpha; # TRUE
-
-=head2 is_qv()
-
-True only if the version object is a dotted-decimal version, e.g.
-
- version->parse('v1.2.0')->is_qv; # TRUE
- version->declare('v1.2')->is_qv; # TRUE
- qv('1.2')->is_qv; # TRUE
- version->parse('1.2')->is_qv; # FALSE
-
-=head2 normal()
-
-Returns a string with a standard 'normalized' dotted-decimal form with a
-leading-v and at least 3 components.
-
- version->declare('v1.2')->normal; # v1.2.0
- version->parse('1.2')->normal; # v1.200.0
-
-=head2 numify()
-
-Returns a value representing the object in a pure decimal form without
-trailing zeroes.
-
- version->declare('v1.2')->numify; # 1.002
- version->parse('1.2')->numify; # 1.2
-
-=head2 stringify()
-
-Returns a string that is as close to the original representation as possible.
-If the original representation was a numeric literal, it will be returned the
-way perl would normally represent it in a string. This method is used whenever
-a version object is interpolated into a string.
-
- version->declare('v1.2')->stringify; # v1.2
- version->parse('1.200')->stringify; # 1.200
- version->parse(1.02_30)->stringify; # 1.023
-
-=head1 EXPORTED FUNCTIONS
-
-=head2 qv()
-
-This function is no longer recommended for use, but is maintained for
-compatibility with existing code. If you do not want to have it exported
-to your namespace, use this form:
-
- use version 0.77 ();
-
-=head2 is_lax()
-
-(Not exported by default)
-
-This function takes a scalar argument and returns a boolean value indicating
-whether the argument meets the "lax" rules for a version number. Leading and
-trailing spaces are not allowed.
-
-=head2 is_strict()
-
-(Not exported by default)
-
-This function takes a scalar argument and returns a boolean value indicating
-whether the argument meets the "strict" rules for a version number. Leading
-and trailing spaces are not allowed.
-
-=head1 AUTHOR
-
-John Peacock E<lt>jpeacock@cpan.orgE<gt>
-
-=head1 SEE ALSO
-
-L<version::Internals>.
-
-L<perl>.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/version/Internals.pod b/Master/tlpkg/tlperl/lib/version/Internals.pod
deleted file mode 100644
index ff63eba6af0..00000000000
--- a/Master/tlpkg/tlperl/lib/version/Internals.pod
+++ /dev/null
@@ -1,698 +0,0 @@
-=head1 NAME
-
-version::Internals - Perl extension for Version Objects
-
-=head1 DESCRIPTION
-
-Overloaded version objects for all modern versions of Perl. This documents
-the internal data representation and underlying code for version.pm. See
-F<version.pod> for daily usage. This document is only useful for users
-interested in the gory details.
-
-=head1 WHAT IS A VERSION?
-
-For the purposes of this module, a version "number" is a sequence of
-positive integer values separated by one or more decimal points and
-optionally a single underscore. This corresponds to what Perl itself
-uses for a version, as well as extending the "version as number" that
-is discussed in the various editions of the Camel book.
-
-There are actually two distinct kinds of version objects:
-
-=over 4
-
-=item Decimal Versions
-
-Any version which "looks like a number", see L<Decimal Versions>. This
-also includes versions with a single decimal point and a single embedded
-underscore, see L<Alpha Versions>, even though these must be quoted
-to preserve the underscore formatting.
-
-=item Dotted-Decimal Versions
-
-Also referred to as "Dotted-Integer", these contains more than one decimal
-point and may have an optional embedded underscore, see L<Dotted-Decimal
-Versions>. This is what is commonly used in most open source software as
-the "external" version (the one used as part of the tag or tarfile name).
-A leading 'v' character is now required and will warn if it missing.
-
-=back
-
-Both of these methods will produce similar version objects, in that
-the default stringification will yield the version L<Normal Form> only
-if required:
-
- $v = version->new(1.002); # 1.002, but compares like 1.2.0
- $v = version->new(1.002003); # 1.002003
- $v2 = version->new("v1.2.3"); # v1.2.3
-
-In specific, version numbers initialized as L<Decimal Versions> will
-stringify as they were originally created (i.e. the same string that was
-passed to C<new()>. Version numbers initialized as L<Dotted-Decimal Versions>
-will be stringified as L<Normal Form>.
-
-=head2 Decimal Versions
-
-These correspond to historical versions of Perl itself prior to 5.6.0,
-as well as all other modules which follow the Camel rules for the
-$VERSION scalar. A Decimal version is initialized with what looks like
-a floating point number. Leading zeros B<are> significant and trailing
-zeros are implied so that a minimum of three places is maintained
-between subversions. What this means is that any subversion (digits
-to the right of the decimal place) that contains less than three digits
-will have trailing zeros added to make up the difference, but only for
-purposes of comparison with other version objects. For example:
-
- # Prints Equivalent to
- $v = version->new( 1.2); # 1.2 v1.200.0
- $v = version->new( 1.02); # 1.02 v1.20.0
- $v = version->new( 1.002); # 1.002 v1.2.0
- $v = version->new( 1.0023); # 1.0023 v1.2.300
- $v = version->new( 1.00203); # 1.00203 v1.2.30
- $v = version->new( 1.002003); # 1.002003 v1.2.3
-
-All of the preceding examples are true whether or not the input value is
-quoted. The important feature is that the input value contains only a
-single decimal. See also L<Alpha Versions>.
-
-IMPORTANT NOTE: As shown above, if your Decimal version contains more
-than 3 significant digits after the decimal place, it will be split on
-each multiple of 3, so 1.0003 is equivalent to v1.0.300, due to the need
-to remain compatible with Perl's own 5.005_03 == 5.5.30 interpretation.
-Any trailing zeros are ignored for mathematical comparison purposes.
-
-=head2 Dotted-Decimal Versions
-
-These are the newest form of versions, and correspond to Perl's own
-version style beginning with 5.6.0. Starting with Perl 5.10.0,
-and most likely Perl 6, this is likely to be the preferred form. This
-method normally requires that the input parameter be quoted, although
-Perl's after 5.8.1 can use v-strings as a special form of quoting, but
-this is highly discouraged.
-
-Unlike L<Decimal Versions>, Dotted-Decimal Versions have more than
-a single decimal point, e.g.:
-
- # Prints
- $v = version->new( "v1.200"); # v1.200.0
- $v = version->new("v1.20.0"); # v1.20.0
- $v = qv("v1.2.3"); # v1.2.3
- $v = qv("1.2.3"); # v1.2.3
- $v = qv("1.20"); # v1.20.0
-
-In general, Dotted-Decimal Versions permit the greatest amount of freedom
-to specify a version, whereas Decimal Versions enforce a certain
-uniformity.
-
-Just like L</Decimal Versions>, Dotted-Decimal Versions can be used as
-L</Alpha Versions>.
-
-=head2 Alpha Versions
-
-For module authors using CPAN, the convention has been to note unstable
-releases with an underscore in the version string. (See L<CPAN>.) version.pm
-follows this convention and alpha releases will test as being newer than the
-more recent stable release, and less than the next stable release. Only the
-last element may be separated by an underscore:
-
- # Declaring
- use version 0.77; our $VERSION = version->declare("v1.2_3");
-
- # Parsing
- $v1 = version->parse("v1.2_3");
- $v1 = version->parse("1.002_003");
-
-Note that you B<must> quote the version when writing an alpha Decimal version.
-The stringified form of Decimal versions will always be the same string that
-was used to initialize the version object.
-
-=head2 Regular Expressions for Version Parsing
-
-A formalized definition of the legal forms for version strings is
-included in the main F<version.pm> file. Primitives are included for
-common elements, although they are scoped to the file so they are useful
-for reference purposes only. There are two publicly accessible scalars
-that can be used in other code (not exported):
-
-=over 4
-
-=item C<$version::LAX>
-
-This regexp covers all of the legal forms allowed under the current
-version string parser. This is not to say that all of these forms
-are recommended, and some of them can only be used when quoted.
-
-For dotted decimals:
-
- v1.2
- 1.2345.6
- v1.23_4
-
-The leading 'v' is optional if two or more decimals appear. If only
-a single decimal is included, then the leading 'v' is required to
-trigger the dotted-decimal parsing. A leading zero is permitted,
-though not recommended except when quoted, because of the risk that
-Perl will treat the number as octal. A trailing underscore plus one
-or more digits denotes an alpha or development release (and must be
-quoted to be parsed properly).
-
-For decimal versions:
-
- 1
- 1.2345
- 1.2345_01
-
-an integer portion, an optional decimal point, and optionally one or
-more digits to the right of the decimal are all required. A trailing
-underscore is permitted and a leading zero is permitted. Just like
-the lax dotted-decimal version, quoting the values is required for
-alpha/development forms to be parsed correctly.
-
-=item C<$version::STRICT>
-
-This regexp covers a much more limited set of formats and constitutes
-the best practices for initializing version objects. Whether you choose
-to employ decimal or dotted-decimal for is a personal preference however.
-
-=over 4
-
-=item v1.234.5
-
-For dotted-decimal versions, a leading 'v' is required, with three or
-more sub-versions of no more than three digits. A leading 0 (zero)
-before the first sub-version (in the above example, '1') is also
-prohibited.
-
-=item 2.3456
-
-For decimal versions, an integer portion (no leading 0), a decimal point,
-and one or more digits to the right of the decimal are all required.
-
-=back
-
-=back
-
-Both of the provided scalars are already compiled as regular expressions
-and do not contain either anchors or implicit groupings, so they can be
-included in your own regular expressions freely. For example, consider
-the following code:
-
- ($pkg, $ver) =~ /
- ^[ \t]*
- use [ \t]+($PKGNAME)
- (?:[ \t]+($version::STRICT))?
- [ \t]*;
- /x;
-
-This would match a line of the form:
-
- use Foo::Bar::Baz v1.2.3; # legal only in Perl 5.8.1+
-
-where C<$PKGNAME> is another regular expression that defines the legal
-forms for package names.
-
-=head1 IMPLEMENTATION DETAILS
-
-=head2 Equivalence between Decimal and Dotted-Decimal Versions
-
-When Perl 5.6.0 was released, the decision was made to provide a
-transformation between the old-style decimal versions and new-style
-dotted-decimal versions:
-
- 5.6.0 == 5.006000
- 5.005_04 == 5.5.40
-
-The floating point number is taken and split first on the single decimal
-place, then each group of three digits to the right of the decimal makes up
-the next digit, and so on until the number of significant digits is exhausted,
-B<plus> enough trailing zeros to reach the next multiple of three.
-
-This was the method that version.pm adopted as well. Some examples may be
-helpful:
-
- equivalent
- decimal zero-padded dotted-decimal
- ------- ----------- --------------
- 1.2 1.200 v1.200.0
- 1.02 1.020 v1.20.0
- 1.002 1.002 v1.2.0
- 1.0023 1.002300 v1.2.300
- 1.00203 1.002030 v1.2.30
- 1.002003 1.002003 v1.2.3
-
-=head2 Quoting Rules
-
-Because of the nature of the Perl parsing and tokenizing routines,
-certain initialization values B<must> be quoted in order to correctly
-parse as the intended version, especially when using the C<declare> or
-L</qv()> methods. While you do not have to quote decimal numbers when
-creating version objects, it is always safe to quote B<all> initial values
-when using version.pm methods, as this will ensure that what you type is
-what is used.
-
-Additionally, if you quote your initializer, then the quoted value that goes
-B<in> will be be exactly what comes B<out> when your $VERSION is printed
-(stringified). If you do not quote your value, Perl's normal numeric handling
-comes into play and you may not get back what you were expecting.
-
-If you use a mathematic formula that resolves to a floating point number,
-you are dependent on Perl's conversion routines to yield the version you
-expect. You are pretty safe by dividing by a power of 10, for example,
-but other operations are not likely to be what you intend. For example:
-
- $VERSION = version->new((qw$Revision: 1.4)[1]/10);
- print $VERSION; # yields 0.14
- $V2 = version->new(100/9); # Integer overflow in decimal number
- print $V2; # yields something like 11.111.111.100
-
-Perl 5.8.1 and beyond are able to automatically quote v-strings but
-that is not possible in earlier versions of Perl. In other words:
-
- $version = version->new("v2.5.4"); # legal in all versions of Perl
- $newvers = version->new(v2.5.4); # legal only in Perl >= 5.8.1
-
-=head2 What about v-strings?
-
-There are two ways to enter v-strings: a bare number with two or more
-decimal points, or a bare number with one or more decimal points and a
-leading 'v' character (also bare). For example:
-
- $vs1 = 1.2.3; # encoded as \1\2\3
- $vs2 = v1.2; # encoded as \1\2
-
-However, the use of bare v-strings to initialize version objects is
-B<strongly> discouraged in all circumstances. Also, bare
-v-strings are not completely supported in any version of Perl prior to
-5.8.1.
-
-If you insist on using bare v-strings with Perl > 5.6.0, be aware of the
-following limitations:
-
-1) For Perl releases 5.6.0 through 5.8.0, the v-string code merely guesses,
-based on some characteristics of v-strings. You B<must> use a three part
-version, e.g. 1.2.3 or v1.2.3 in order for this heuristic to be successful.
-
-2) For Perl releases 5.8.1 and later, v-strings have changed in the Perl
-core to be magical, which means that the version.pm code can automatically
-determine whether the v-string encoding was used.
-
-3) In all cases, a version created using v-strings will have a stringified
-form that has a leading 'v' character, for the simple reason that sometimes
-it is impossible to tell whether one was present initially.
-
-=head2 Version Object Internals
-
-version.pm provides an overloaded version object that is designed to both
-encapsulate the author's intended $VERSION assignment as well as make it
-completely natural to use those objects as if they were numbers (e.g. for
-comparisons). To do this, a version object contains both the original
-representation as typed by the author, as well as a parsed representation
-to ease comparisons. Version objects employ L<overload> methods to
-simplify code that needs to compare, print, etc the objects.
-
-The internal structure of version objects is a blessed hash with several
-components:
-
- bless( {
- 'original' => 'v1.2.3_4',
- 'alpha' => 1,
- 'qv' => 1,
- 'version' => [
- 1,
- 2,
- 3,
- 4
- ]
- }, 'version' );
-
-=over 4
-
-=item original
-
-A faithful representation of the value used to initialize this version
-object. The only time this will not be precisely the same characters
-that exist in the source file is if a short dotted-decimal version like
-v1.2 was used (in which case it will contain 'v1.2'). This form is
-B<STRONGLY> discouraged, in that it will confuse you and your users.
-
-=item qv
-
-A boolean that denotes whether this is a decimal or dotted-decimal version.
-See L<version/is_qv()>.
-
-=item alpha
-
-A boolean that denotes whether this is an alpha version. NOTE: that the
-underscore can can only appear in the last position. See L<version/is_alpha()>.
-
-=item version
-
-An array of non-negative integers that is used for comparison purposes with
-other version objects.
-
-=back
-
-=head2 Replacement UNIVERSAL::VERSION
-
-In addition to the version objects, this modules also replaces the core
-UNIVERSAL::VERSION function with one that uses version objects for its
-comparisons. The return from this operator is always the stringified form
-as a simple scalar (i.e. not an object), but the warning message generated
-includes either the stringified form or the normal form, depending on how
-it was called.
-
-For example:
-
- package Foo;
- $VERSION = 1.2;
-
- package Bar;
- $VERSION = "v1.3.5"; # works with all Perl's (since it is quoted)
-
- package main;
- use version;
-
- print $Foo::VERSION; # prints 1.2
-
- print $Bar::VERSION; # prints 1.003005
-
- eval "use foo 10";
- print $@; # prints "foo version 10 required..."
- eval "use foo 1.3.5; # work in Perl 5.6.1 or better
- print $@; # prints "foo version 1.3.5 required..."
-
- eval "use bar 1.3.6";
- print $@; # prints "bar version 1.3.6 required..."
- eval "use bar 1.004"; # note Decimal version
- print $@; # prints "bar version 1.004 required..."
-
-
-IMPORTANT NOTE: This may mean that code which searches for a specific
-string (to determine whether a given module is available) may need to be
-changed. It is always better to use the built-in comparison implicit in
-C<use> or C<require>, rather than manually poking at C<< class->VERSION >>
-and then doing a comparison yourself.
-
-The replacement UNIVERSAL::VERSION, when used as a function, like this:
-
- print $module->VERSION;
-
-will also exclusively return the stringified form. See L</Stringification>
-for more details.
-
-=head1 USAGE DETAILS
-
-=head2 Using modules that use version.pm
-
-As much as possible, the version.pm module remains compatible with all
-current code. However, if your module is using a module that has defined
-C<$VERSION> using the version class, there are a couple of things to be
-aware of. For purposes of discussion, we will assume that we have the
-following module installed:
-
- package Example;
- use version; $VERSION = qv('1.2.2');
- ...module code here...
- 1;
-
-=over 4
-
-=item Decimal versions always work
-
-Code of the form:
-
- use Example 1.002003;
-
-will always work correctly. The C<use> will perform an automatic
-C<$VERSION> comparison using the floating point number given as the first
-term after the module name (e.g. above 1.002.003). In this case, the
-installed module is too old for the requested line, so you would see an
-error like:
-
- Example version 1.002003 (v1.2.3) required--this is only version 1.002002 (v1.2.2)...
-
-=item Dotted-Decimal version work sometimes
-
-With Perl >= 5.6.2, you can also use a line like this:
-
- use Example 1.2.3;
-
-and it will again work (i.e. give the error message as above), even with
-releases of Perl which do not normally support v-strings (see L<What about v-strings?> above). This has to do with that fact that C<use> only checks
-to see if the second term I<looks like a number> and passes that to the
-replacement L<UNIVERSAL::VERSION|UNIVERSAL/VERSION>. This is not true in Perl 5.005_04,
-however, so you are B<strongly encouraged> to always use a Decimal version
-in your code, even for those versions of Perl which support the Dotted-Decimal
-version.
-
-=back
-
-=head2 Object Methods
-
-=over 4
-
-=item new()
-
-Like many OO interfaces, the new() method is used to initialize version
-objects. If two arguments are passed to C<new()>, the B<second> one will be
-used as if it were prefixed with "v". This is to support historical use of the
-C<qw> operator with the CVS variable $Revision, which is automatically
-incremented by CVS every time the file is committed to the repository.
-
-In order to facilitate this feature, the following
-code can be employed:
-
- $VERSION = version->new(qw$Revision: 2.7 $);
-
-and the version object will be created as if the following code
-were used:
-
- $VERSION = version->new("v2.7");
-
-In other words, the version will be automatically parsed out of the
-string, and it will be quoted to preserve the meaning CVS normally
-carries for versions. The CVS $Revision$ increments differently from
-Decimal versions (i.e. 1.10 follows 1.9), so it must be handled as if
-it were a Dotted-Decimal Version.
-
-A new version object can be created as a copy of an existing version
-object, either as a class method:
-
- $v1 = version->new(12.3);
- $v2 = version->new($v1);
-
-or as an object method:
-
- $v1 = version->new(12.3);
- $v2 = $v1->new(12.3);
-
-and in each case, $v1 and $v2 will be identical. NOTE: if you create
-a new object using an existing object like this:
-
- $v2 = $v1->new();
-
-the new object B<will not> be a clone of the existing object. In the
-example case, $v2 will be an empty object of the same type as $v1.
-
-=back
-
-=over 4
-
-=item qv()
-
-An alternate way to create a new version object is through the exported
-qv() sub. This is not strictly like other q? operators (like qq, qw),
-in that the only delimiters supported are parentheses (or spaces). It is
-the best way to initialize a short version without triggering the floating
-point interpretation. For example:
-
- $v1 = qv(1.2); # v1.2.0
- $v2 = qv("1.2"); # also v1.2.0
-
-As you can see, either a bare number or a quoted string can usually
-be used interchangeably, except in the case of a trailing zero, which
-must be quoted to be converted properly. For this reason, it is strongly
-recommended that all initializers to qv() be quoted strings instead of
-bare numbers.
-
-To prevent the C<qv()> function from being exported to the caller's namespace,
-either use version with a null parameter:
-
- use version ();
-
-or just require version, like this:
-
- require version;
-
-Both methods will prevent the import() method from firing and exporting the
-C<qv()> sub.
-
-=back
-
-For the subsequent examples, the following three objects will be used:
-
- $ver = version->new("1.2.3.4"); # see "Quoting Rules"
- $alpha = version->new("1.2.3_4"); # see "Alpha Versions"
- $nver = version->new(1.002); # see "Decimal Versions"
-
-=over 4
-
-=item Normal Form
-
-For any version object which is initialized with multiple decimal
-places (either quoted or if possible v-string), or initialized using
-the L<qv()|version/qv()> operator, the stringified representation is returned in
-a normalized or reduced form (no extraneous zeros), and with a leading 'v':
-
- print $ver->normal; # prints as v1.2.3.4
- print $ver->stringify; # ditto
- print $ver; # ditto
- print $nver->normal; # prints as v1.2.0
- print $nver->stringify; # prints as 1.002, see "Stringification"
-
-In order to preserve the meaning of the processed version, the
-normalized representation will always contain at least three sub terms.
-In other words, the following is guaranteed to always be true:
-
- my $newver = version->new($ver->stringify);
- if ($newver eq $ver ) # always true
- {...}
-
-=back
-
-=over 4
-
-=item Numification
-
-Although all mathematical operations on version objects are forbidden
-by default, it is possible to retrieve a number which corresponds
-to the version object through the use of the $obj->numify
-method. For formatting purposes, when displaying a number which
-corresponds a version object, all sub versions are assumed to have
-three decimal places. So for example:
-
- print $ver->numify; # prints 1.002003004
- print $nver->numify; # prints 1.002
-
-Unlike the stringification operator, there is never any need to append
-trailing zeros to preserve the correct version value.
-
-=back
-
-=over 4
-
-=item Stringification
-
-The default stringification for version objects returns exactly the same
-string as was used to create it, whether you used C<new()> or C<qv()>,
-with one exception. The sole exception is if the object was created using
-C<qv()> and the initializer did not have two decimal places or a leading
-'v' (both optional), then the stringified form will have a leading 'v'
-prepended, in order to support round-trip processing.
-
-For example:
-
- Initialized as Stringifies to
- ============== ==============
- version->new("1.2") 1.2
- version->new("v1.2") v1.2
- qv("1.2.3") 1.2.3
- qv("v1.3.5") v1.3.5
- qv("1.2") v1.2 ### exceptional case
-
-See also L<UNIVERSAL::VERSION|UNIVERSAL/VERSION>, as this also returns the stringified form
-when used as a class method.
-
-IMPORTANT NOTE: There is one exceptional cases shown in the above table
-where the "initializer" is not stringwise equivalent to the stringified
-representation. If you use the C<qv>() operator on a version without a
-leading 'v' B<and> with only a single decimal place, the stringified output
-will have a leading 'v', to preserve the sense. See the L</qv()> operator
-for more details.
-
-IMPORTANT NOTE 2: Attempting to bypass the normal stringification rules by
-manually applying L<numify()|version/numify()> and L<normal()|version/normal()> will sometimes yield
-surprising results:
-
- print version->new(version->new("v1.0")->numify)->normal; # v1.0.0
-
-The reason for this is that the L<numify()|version/numify()> operator will turn "v1.0"
-into the equivalent string "1.000000". Forcing the outer version object
-to L<normal()|version/normal()> form will display the mathematically equivalent "v1.0.0".
-
-As the example in L</new()> shows, you can always create a copy of an
-existing version object with the same value by the very compact:
-
- $v2 = $v1->new($v1);
-
-and be assured that both C<$v1> and C<$v2> will be completely equivalent,
-down to the same internal representation as well as stringification.
-
-=back
-
-=over 4
-
-=item Comparison operators
-
-Both C<cmp> and C<E<lt>=E<gt>> operators perform the same comparison between
-terms (upgrading to a version object automatically). Perl automatically
-generates all of the other comparison operators based on those two.
-In addition to the obvious equalities listed below, appending a single
-trailing 0 term does not change the value of a version for comparison
-purposes. In other words "v1.2" and "1.2.0" will compare as identical.
-
-For example, the following relations hold:
-
- As Number As String Truth Value
- ------------- ---------------- -----------
- $ver > 1.0 $ver gt "1.0" true
- $ver < 2.5 $ver lt true
- $ver != 1.3 $ver ne "1.3" true
- $ver == 1.2 $ver eq "1.2" false
- $ver == 1.2.3.4 $ver eq "1.2.3.4" see discussion below
-
-It is probably best to chose either the Decimal notation or the string
-notation and stick with it, to reduce confusion. Perl6 version objects
-B<may> only support Decimal comparisons. See also L<Quoting Rules>.
-
-WARNING: Comparing version with unequal numbers of decimal points (whether
-explicitly or implicitly initialized), may yield unexpected results at
-first glance. For example, the following inequalities hold:
-
- version->new(0.96) > version->new(0.95); # 0.960.0 > 0.950.0
- version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0
-
-For this reason, it is best to use either exclusively L<Decimal Versions> or
-L<Dotted-Decimal Versions> with multiple decimal points.
-
-=back
-
-=over 4
-
-=item Logical Operators
-
-If you need to test whether a version object
-has been initialized, you can simply test it directly:
-
- $vobj = version->new($something);
- if ( $vobj ) # true only if $something was non-blank
-
-You can also test whether a version object is an alpha version, for
-example to prevent the use of some feature not present in the main
-release:
-
- $vobj = version->new("1.2_3"); # MUST QUOTE
- ...later...
- if ( $vobj->is_alpha ) # True
-
-=back
-
-=head1 AUTHOR
-
-John Peacock E<lt>jpeacock@cpan.orgE<gt>
-
-=head1 SEE ALSO
-
-L<perl>.
-
-=cut
diff --git a/Master/tlpkg/tlperl/lib/version/Requirements.pm b/Master/tlpkg/tlperl/lib/version/Requirements.pm
deleted file mode 100644
index 39ae2060909..00000000000
--- a/Master/tlpkg/tlperl/lib/version/Requirements.pm
+++ /dev/null
@@ -1,597 +0,0 @@
-use strict;
-use warnings;
-package Version::Requirements;
-{
- $Version::Requirements::VERSION = '0.101022';
-}
-# ABSTRACT: a set of version requirements for a CPAN dist
-
-
-use Carp ();
-use Scalar::Util ();
-use version 0.77 (); # the ->parse method
-
-# We silence this warning during core tests, because this is only in core
-# because it has to be, and nobody wants to see this stupid warning.
-# -- rjbs, 2012-01-20
-Carp::cluck(
- "Version::Requirements is deprecated; replace with CPAN::Meta::Requirements"
-) unless $ENV{PERL_CORE};
-
-
-sub new {
- my ($class) = @_;
- return bless {} => $class;
-}
-
-sub _version_object {
- my ($self, $version) = @_;
-
- $version = (! defined $version) ? version->parse(0)
- : (! Scalar::Util::blessed($version)) ? version->parse($version)
- : $version;
-
- return $version;
-}
-
-
-BEGIN {
- for my $type (qw(minimum maximum exclusion exact_version)) {
- my $method = "with_$type";
- my $to_add = $type eq 'exact_version' ? $type : "add_$type";
-
- my $code = sub {
- my ($self, $name, $version) = @_;
-
- $version = $self->_version_object( $version );
-
- $self->__modify_entry_for($name, $method, $version);
-
- return $self;
- };
-
- no strict 'refs';
- *$to_add = $code;
- }
-}
-
-
-sub add_requirements {
- my ($self, $req) = @_;
-
- for my $module ($req->required_modules) {
- my $modifiers = $req->__entry_for($module)->as_modifiers;
- for my $modifier (@$modifiers) {
- my ($method, @args) = @$modifier;
- $self->$method($module => @args);
- };
- }
-
- return $self;
-}
-
-
-sub accepts_module {
- my ($self, $module, $version) = @_;
-
- $version = $self->_version_object( $version );
-
- return 1 unless my $range = $self->__entry_for($module);
- return $range->_accepts($version);
-}
-
-
-sub clear_requirement {
- my ($self, $module) = @_;
-
- return $self unless $self->__entry_for($module);
-
- Carp::confess("can't clear requirements on finalized requirements")
- if $self->is_finalized;
-
- delete $self->{requirements}{ $module };
-
- return $self;
-}
-
-
-sub required_modules { keys %{ $_[0]{requirements} } }
-
-
-sub clone {
- my ($self) = @_;
- my $new = (ref $self)->new;
-
- return $new->add_requirements($self);
-}
-
-sub __entry_for { $_[0]{requirements}{ $_[1] } }
-
-sub __modify_entry_for {
- my ($self, $name, $method, $version) = @_;
-
- my $fin = $self->is_finalized;
- my $old = $self->__entry_for($name);
-
- Carp::confess("can't add new requirements to finalized requirements")
- if $fin and not $old;
-
- my $new = ($old || 'Version::Requirements::_Range::Range')
- ->$method($version);
-
- Carp::confess("can't modify finalized requirements")
- if $fin and $old->as_string ne $new->as_string;
-
- $self->{requirements}{ $name } = $new;
-}
-
-
-sub is_simple {
- my ($self) = @_;
- for my $module ($self->required_modules) {
- # XXX: This is a complete hack, but also entirely correct.
- return if $self->__entry_for($module)->as_string =~ /\s/;
- }
-
- return 1;
-}
-
-
-sub is_finalized { $_[0]{finalized} }
-
-
-sub finalize { $_[0]{finalized} = 1 }
-
-
-sub as_string_hash {
- my ($self) = @_;
-
- my %hash = map {; $_ => $self->{requirements}{$_}->as_string }
- $self->required_modules;
-
- return \%hash;
-}
-
-
-my %methods_for_op = (
- '==' => [ qw(exact_version) ],
- '!=' => [ qw(add_exclusion) ],
- '>=' => [ qw(add_minimum) ],
- '<=' => [ qw(add_maximum) ],
- '>' => [ qw(add_minimum add_exclusion) ],
- '<' => [ qw(add_maximum add_exclusion) ],
-);
-
-sub from_string_hash {
- my ($class, $hash) = @_;
-
- my $self = $class->new;
-
- for my $module (keys %$hash) {
- my @parts = split qr{\s*,\s*}, $hash->{ $module };
- for my $part (@parts) {
- my ($op, $ver) = split /\s+/, $part, 2;
-
- if (! defined $ver) {
- $self->add_minimum($module => $op);
- } else {
- Carp::confess("illegal requirement string: $hash->{ $module }")
- unless my $methods = $methods_for_op{ $op };
-
- $self->$_($module => $ver) for @$methods;
- }
- }
- }
-
- return $self;
-}
-
-##############################################################
-
-{
- package
- Version::Requirements::_Range::Exact;
- sub _new { bless { version => $_[1] } => $_[0] }
-
- sub _accepts { return $_[0]{version} == $_[1] }
-
- sub as_string { return "== $_[0]{version}" }
-
- sub as_modifiers { return [ [ exact_version => $_[0]{version} ] ] }
-
- sub _clone {
- (ref $_[0])->_new( version->new( $_[0]{version} ) )
- }
-
- sub with_exact_version {
- my ($self, $version) = @_;
-
- return $self->_clone if $self->_accepts($version);
-
- Carp::confess("illegal requirements: unequal exact version specified");
- }
-
- sub with_minimum {
- my ($self, $minimum) = @_;
- return $self->_clone if $self->{version} >= $minimum;
- Carp::confess("illegal requirements: minimum above exact specification");
- }
-
- sub with_maximum {
- my ($self, $maximum) = @_;
- return $self->_clone if $self->{version} <= $maximum;
- Carp::confess("illegal requirements: maximum below exact specification");
- }
-
- sub with_exclusion {
- my ($self, $exclusion) = @_;
- return $self->_clone unless $exclusion == $self->{version};
- Carp::confess("illegal requirements: excluded exact specification");
- }
-}
-
-##############################################################
-
-{
- package
- Version::Requirements::_Range::Range;
-
- sub _self { ref($_[0]) ? $_[0] : (bless { } => $_[0]) }
-
- sub _clone {
- return (bless { } => $_[0]) unless ref $_[0];
-
- my ($s) = @_;
- my %guts = (
- (exists $s->{minimum} ? (minimum => version->new($s->{minimum})) : ()),
- (exists $s->{maximum} ? (maximum => version->new($s->{maximum})) : ()),
-
- (exists $s->{exclusions}
- ? (exclusions => [ map { version->new($_) } @{ $s->{exclusions} } ])
- : ()),
- );
-
- bless \%guts => ref($s);
- }
-
- sub as_modifiers {
- my ($self) = @_;
- my @mods;
- push @mods, [ add_minimum => $self->{minimum} ] if exists $self->{minimum};
- push @mods, [ add_maximum => $self->{maximum} ] if exists $self->{maximum};
- push @mods, map {; [ add_exclusion => $_ ] } @{$self->{exclusions} || []};
- return \@mods;
- }
-
- sub as_string {
- my ($self) = @_;
-
- return 0 if ! keys %$self;
-
- return "$self->{minimum}" if (keys %$self) == 1 and exists $self->{minimum};
-
- my @exclusions = @{ $self->{exclusions} || [] };
-
- my @parts;
-
- for my $pair (
- [ qw( >= > minimum ) ],
- [ qw( <= < maximum ) ],
- ) {
- my ($op, $e_op, $k) = @$pair;
- if (exists $self->{$k}) {
- my @new_exclusions = grep { $_ != $self->{ $k } } @exclusions;
- if (@new_exclusions == @exclusions) {
- push @parts, "$op $self->{ $k }";
- } else {
- push @parts, "$e_op $self->{ $k }";
- @exclusions = @new_exclusions;
- }
- }
- }
-
- push @parts, map {; "!= $_" } @exclusions;
-
- return join q{, }, @parts;
- }
-
- sub with_exact_version {
- my ($self, $version) = @_;
- $self = $self->_clone;
-
- Carp::confess("illegal requirements: exact specification outside of range")
- unless $self->_accepts($version);
-
- return Version::Requirements::_Range::Exact->_new($version);
- }
-
- sub _simplify {
- my ($self) = @_;
-
- if (defined $self->{minimum} and defined $self->{maximum}) {
- if ($self->{minimum} == $self->{maximum}) {
- Carp::confess("illegal requirements: excluded all values")
- if grep { $_ == $self->{minimum} } @{ $self->{exclusions} || [] };
-
- return Version::Requirements::_Range::Exact->_new($self->{minimum})
- }
-
- Carp::confess("illegal requirements: minimum exceeds maximum")
- if $self->{minimum} > $self->{maximum};
- }
-
- # eliminate irrelevant exclusions
- if ($self->{exclusions}) {
- my %seen;
- @{ $self->{exclusions} } = grep {
- (! defined $self->{minimum} or $_ >= $self->{minimum})
- and
- (! defined $self->{maximum} or $_ <= $self->{maximum})
- and
- ! $seen{$_}++
- } @{ $self->{exclusions} };
- }
-
- return $self;
- }
-
- sub with_minimum {
- my ($self, $minimum) = @_;
- $self = $self->_clone;
-
- if (defined (my $old_min = $self->{minimum})) {
- $self->{minimum} = (sort { $b cmp $a } ($minimum, $old_min))[0];
- } else {
- $self->{minimum} = $minimum;
- }
-
- return $self->_simplify;
- }
-
- sub with_maximum {
- my ($self, $maximum) = @_;
- $self = $self->_clone;
-
- if (defined (my $old_max = $self->{maximum})) {
- $self->{maximum} = (sort { $a cmp $b } ($maximum, $old_max))[0];
- } else {
- $self->{maximum} = $maximum;
- }
-
- return $self->_simplify;
- }
-
- sub with_exclusion {
- my ($self, $exclusion) = @_;
- $self = $self->_clone;
-
- push @{ $self->{exclusions} ||= [] }, $exclusion;
-
- return $self->_simplify;
- }
-
- sub _accepts {
- my ($self, $version) = @_;
-
- return if defined $self->{minimum} and $version < $self->{minimum};
- return if defined $self->{maximum} and $version > $self->{maximum};
- return if defined $self->{exclusions}
- and grep { $version == $_ } @{ $self->{exclusions} };
-
- return 1;
- }
-}
-
-1;
-
-__END__
-=pod
-
-=head1 NAME
-
-Version::Requirements - a set of version requirements for a CPAN dist
-
-=head1 VERSION
-
-version 0.101022
-
-=head1 SYNOPSIS
-
- use Version::Requirements;
-
- my $build_requires = Version::Requirements->new;
-
- $build_requires->add_minimum('Library::Foo' => 1.208);
-
- $build_requires->add_minimum('Library::Foo' => 2.602);
-
- $build_requires->add_minimum('Module::Bar' => 'v1.2.3');
-
- $METAyml->{build_requires} = $build_requires->as_string_hash;
-
-=head1 DESCRIPTION
-
-A Version::Requirements object models a set of version constraints like those
-specified in the F<META.yml> or F<META.json> files in CPAN distributions. It
-can be built up by adding more and more constraints, and it will reduce them to
-the simplest representation.
-
-Logically impossible constraints will be identified immediately by thrown
-exceptions.
-
-=head1 METHODS
-
-=head2 new
-
- my $req = Version::Requirements->new;
-
-This returns a new Version::Requirements object. It ignores any arguments
-given.
-
-=head2 add_minimum
-
- $req->add_minimum( $module => $version );
-
-This adds a new minimum version requirement. If the new requirement is
-redundant to the existing specification, this has no effect.
-
-Minimum requirements are inclusive. C<$version> is required, along with any
-greater version number.
-
-This method returns the requirements object.
-
-=head2 add_maximum
-
- $req->add_maximum( $module => $version );
-
-This adds a new maximum version requirement. If the new requirement is
-redundant to the existing specification, this has no effect.
-
-Maximum requirements are inclusive. No version strictly greater than the given
-version is allowed.
-
-This method returns the requirements object.
-
-=head2 add_exclusion
-
- $req->add_exclusion( $module => $version );
-
-This adds a new excluded version. For example, you might use these three
-method calls:
-
- $req->add_minimum( $module => '1.00' );
- $req->add_maximum( $module => '1.82' );
-
- $req->add_exclusion( $module => '1.75' );
-
-Any version between 1.00 and 1.82 inclusive would be acceptable, except for
-1.75.
-
-This method returns the requirements object.
-
-=head2 exact_version
-
- $req->exact_version( $module => $version );
-
-This sets the version required for the given module to I<exactly> the given
-version. No other version would be considered acceptable.
-
-This method returns the requirements object.
-
-=head2 add_requirements
-
- $req->add_requirements( $another_req_object );
-
-This method adds all the requirements in the given Version::Requirements object
-to the requirements object on which it was called. If there are any conflicts,
-an exception is thrown.
-
-This method returns the requirements object.
-
-=head2 accepts_module
-
- my $bool = $req->accepts_modules($module => $version);
-
-Given an module and version, this method returns true if the version
-specification for the module accepts the provided version. In other words,
-given:
-
- Module => '>= 1.00, < 2.00'
-
-We will accept 1.00 and 1.75 but not 0.50 or 2.00.
-
-For modules that do not appear in the requirements, this method will return
-true.
-
-=head2 clear_requirement
-
- $req->clear_requirement( $module );
-
-This removes the requirement for a given module from the object.
-
-This method returns the requirements object.
-
-=head2 required_modules
-
-This method returns a list of all the modules for which requirements have been
-specified.
-
-=head2 clone
-
- $req->clone;
-
-This method returns a clone of the invocant. The clone and the original object
-can then be changed independent of one another.
-
-=head2 is_simple
-
-This method returns true if and only if all requirements are inclusive minimums
--- that is, if their string expression is just the version number.
-
-=head2 is_finalized
-
-This method returns true if the requirements have been finalized by having the
-C<finalize> method called on them.
-
-=head2 finalize
-
-This method marks the requirements finalized. Subsequent attempts to change
-the requirements will be fatal, I<if> they would result in a change. If they
-would not alter the requirements, they have no effect.
-
-If a finalized set of requirements is cloned, the cloned requirements are not
-also finalized.
-
-=head2 as_string_hash
-
-This returns a reference to a hash describing the requirements using the
-strings in the F<META.yml> specification.
-
-For example after the following program:
-
- my $req = Version::Requirements->new;
-
- $req->add_minimum('Version::Requirements' => 0.102);
-
- $req->add_minimum('Library::Foo' => 1.208);
-
- $req->add_maximum('Library::Foo' => 2.602);
-
- $req->add_minimum('Module::Bar' => 'v1.2.3');
-
- $req->add_exclusion('Module::Bar' => 'v1.2.8');
-
- $req->exact_version('Xyzzy' => '6.01');
-
- my $hashref = $req->as_string_hash;
-
-C<$hashref> would contain:
-
- {
- 'Version::Requirements' => '0.102',
- 'Library::Foo' => '>= 1.208, <= 2.206',
- 'Module::Bar' => '>= v1.2.3, != v1.2.8',
- 'Xyzzy' => '== 6.01',
- }
-
-=head2 from_string_hash
-
- my $req = Version::Requirements->from_string_hash( \%hash );
-
-This is an alternate constructor for a Version::Requirements object. It takes
-a hash of module names and version requirement strings and returns a new
-Version::Requirements object.
-
-=head1 AUTHOR
-
-Ricardo Signes <rjbs@cpan.org>
-
-=head1 COPYRIGHT AND LICENSE
-
-This software is copyright (c) 2010 by Ricardo Signes.
-
-This is free software; you can redistribute it and/or modify it under
-the same terms as the Perl 5 programming language system itself.
-
-=cut
-